8004 on Solana

HyperLogLog (Unique Client Estimation)

256 registers, 4-bit packed (128 bytes). Estimates unique clients with ~6.5% standard error.

// Per-agent salt prevents grinding attacks
salted_hash = keccak256(client_hash || hll_salt)
register_idx = salted_hash[0..8] % 256
leading_zeros = count_leading_zeros(salted_hash[8..])
registers[idx] = max(registers[idx], leading_zeros + 1)

Ring Buffer (Burst Detection & Revoke)

24 slots with 56-bit fingerprints. Round-robin eviction prevents manipulation.

// Fingerprint = truncated keccak hash
fingerprint = keccak256(client_pubkey)[0..7]

// Round-robin eviction (cursor increments each write)
slot = eviction_cursor % 24
recent_callers[slot] = fingerprint
eviction_cursor += 1

EMA Quality Score

Exponential Moving Average with α=0.1 (10% weight to new scores).

// Centered score: 0-100 → -50 to +50
centered = (score as i32) - 50

// EMA update (scaled by 1000 for precision)
quality_score = (quality_score * 900 + centered * 100) / 1000

initialize()

Initialize the registry and create the Metaplex Core Collection.

What it does:

• Creates Config PDA with global state
• Creates Metaplex Core Collection
• Config PDA becomes collection update_authority (enables permissionless registration)

Accounts:

register(agent_uri: String) / register_empty()

Register a new agent with optional URI.

Parameters:

Flow:

1. Create Metaplex Core asset with collection plugin
2. Add to collection via Config PDA signature
3. Initialize AgentAccount PDA keyed by Core asset address
4. Asset address = unique identifier (no sequential counter)

Events: Registered { asset, owner, agent_uri }

set_metadata_pda(key_hash, key, value, immutable)

Create or update a metadata entry as individual PDA. Only Core asset holder can call.

Parameters:

delete_metadata_pda(key_hash)

Delete a metadata PDA and recover rent. Only works if not immutable.

Parameters:

Returns: ~0.0031 SOL rent to owner

Events: MetadataDeleted

set_agent_uri(new_uri: String)

Update agent URI and sync to Metaplex Core asset.

Uses UpdateV1CpiBuilder to update Core asset URI. Config PDA signs as collection update authority.

transfer_agent()

Transfer Core asset to new owner. Uses TransferV1CpiBuilder for Metaplex Core transfer.

RegistryConfig (78 bytes)

pub struct RegistryConfig {
    pub collection: Pubkey,             // 32 bytes (Core Collection)
    pub registry_type: RegistryType,    // 1 byte
    pub authority: Pubkey,              // 32 bytes
    pub base_index: u32,                // 4 bytes
    pub bump: u8,                       // 1 byte
}
// Removed: next_agent_id, total_agents (off-chain via indexer)

AgentAccount (313 bytes)

pub struct AgentAccount {
    pub owner: Pubkey,                  // 32 bytes (cached, synced on transfer)
    pub asset: Pubkey,                  // 32 bytes (Core asset = unique ID)
    pub bump: u8,                       // 1 byte
    pub agent_uri: String,              // 4 + 200 = 204 bytes
    pub nft_name: String,               // 4 + 32 = 36 bytes ("Agent #X")
    // Metadata moved to individual PDAs (v0.2.0)
}
// Removed: agent_id, created_at, nft_symbol
// Use blockTime for timestamps, Metaplex for symbol

MetadataEntryPda (~306 bytes)

pub struct MetadataEntryPda {
    pub metadata_key: String,       // 4 + 32 = 36 bytes
    pub metadata_value: Vec<u8>,    // 4 + 256 = 260 bytes
    pub immutable: bool,            // 1 byte (if true, locked forever)
    pub bump: u8,                   // 1 byte
}
// Removed: agent_id, created_at
// Delete to recover rent (~0.0029 SOL)

give_feedback(score, tag1, tag2, endpoint, feedback_uri, feedback_hash, feedback_index)

Create feedback for an agent. Asset passed via account context.

Parameters:

Global Feedback Index:

// Index verified and incremented from AgentReputationMetadata
require!(feedback_index == agent_reputation.next_feedback_index);
agent_reputation.next_feedback_index += 1;

revoke_feedback(feedback_index, seal_hash)

Emit revocation event and update hash-chain digest. Permissionless (indexer validates authorship).

Parameters:

State Changes:

• agent.revoke_digest updated (hash-chain)
• agent.revoke_count += 1
• CPI to ATOM revoke_stats (if enabled)

append_response(asset_key, client_address, feedback_index, response_uri, response_hash, seal_hash)

Append response to existing feedback. Authorized only (agent owner or agent wallet).

Parameters:

State Changes:

• agent.response_digest updated (hash-chain)
• agent.response_count += 1

Event-Only Architecture

Feedback, revocation, and response data are stored as Solana events (not PDAs) for rent optimization. Integrity is guaranteed by rolling hash-chain digests stored in AgentAccount:

// In AgentAccount (120 bytes for reputation)
pub feedback_digest: [u8; 32],   // Rolling keccak256 hash-chain
pub feedback_count: u64,         // Global feedback counter
pub response_digest: [u8; 32],   // Rolling keccak256 hash-chain
pub response_count: u64,         // Response counter
pub revoke_digest: [u8; 32],     // Rolling keccak256 hash-chain
pub revoke_count: u64,           // Revoke counter

Each operation updates its chain: new_digest = keccak256(old_digest || domain || leaf_data).

Clients verify by replaying all events and comparing final digest against on-chain value.

Agent Existence Verification

Reputation module verifies agent existence by checking the AgentAccount PDA exists before processing.

// Agent PDA must exist (asset = unique identifier)
#[account(
    seeds = [b"agent", asset.key().as_ref()],
    bump = agent_account.bump,
)]
pub agent_account: Account<'info, AgentAccount>,

Ownership Verification (Metaplex Core)

For metadata/URI updates, ownership verified via Core asset directly:

// Core asset stores owner in its data
constraint = asset.owner == owner.key()

Why: Metaplex Core assets store owner directly, simplifying ownership verification.

Events-Only Reputation

Feedbacks, responses, and revocations are events-only (no per-feedback PDAs). Integrity ensured via SEAL v1 hash-chains:

// Hash-chain rolling digests in AgentAccount
agent.feedback_digest = chain_hash(prev_digest, DOMAIN_FEEDBACK, leaf);
agent.feedback_count += 1;

SEAL v1 Integrity

seal_hash computed on-chain from all feedback parameters. Indexers verify by replaying events against on-chain digests.

let seal_hash = compute_seal_hash_v1(value, decimals, score, ...);
// seal_hash emitted in event, bound into hash-chain leaf

1. Validation Module

Removed entirely. Archived for future upgrade.

2. On-chain Aggregates

From AgentReputationMetadata:

• total_feedbacks, total_score_sum, average_score, last_updated

Now computed off-chain. Only next_feedback_index remains for sequencing.

3. Redundant Fields

• agent_id everywhere (replaced by asset)
• collection from FeedbackAccount
• created_at from all accounts (use blockTime)
• nft_symbol from AgentAccount (read from Metaplex)
• response_hash, indices from ResponseAccount (in events)

4. Rent Recovery

Accounts can be closed to recover rent:

• delete_metadata_pda() - Returns ~0.0029 SOL per entry