8004stellar

name: 8004stellar description: Use when building on Stellar/Soroban with ERC-8004 Agent Trust Protocol — agent identity registration, reputation feedback, validator endorsements.

ERC-8004: Agent Trust Protocol on Stellar

ERC-8004 establishes trust infrastructure for autonomous AI agents on Stellar/Soroban, enabling them to discover, identify, and evaluate other agents across organizational boundaries.

Companion skill: /stellar-dev for Soroban transaction patterns, Freighter integration, nativeToScVal reference, and testnet setup.

When to Use

• Registering an AI agent's identity on-chain so it becomes discoverable
• Building reputation systems for AI agents (feedback, scoring, trust thresholds)
• Verifying agent identity and reputation before interacting or paying
• Querying agent reputation and feedback history
• Implementing trust-based agent interactions with x402 payments

The Protocol Stack

Application Layer    (Agent apps, marketplaces, 8004scan)
        ↓
Trust Layer          (ERC-8004: identity + reputation + validation) ← this skill
        ↓
Payment Layer        (x402: USDC micropayments) ← /x402stellar skill
        ↓
Communication Layer  (A2A, MCP, HTTP)

ERC-8004 sits at the Trust Layer — you verify trust first, then enable payment, then communicate. Without trust, agents can't evaluate each other before transacting.

Contract Addresses

Stellar Testnet

Stellar Mainnet

Network Configuration

Prerequisites

npm install @trionlabs/stellar8004 @stellar/stellar-sdk

• Stellar keypair (G.../S... format) — Keypair.random() for testnet, Keypair.fromSecret(secret) for existing wallets
• Signer — wrapBasicSigner(keypair, networkPassphrase) for scripts, FreighterSigner for browser apps
• Testnet: fund via fundTestnet(address) from SDK or Friendbot
• Companion skill /stellar-dev for Soroban transaction fundamentals

Step 1: Prepare Your Agent Metadata

Metadata Format

Host as IPFS, HTTPS, or inline data URI — passed to register_with_uri():

{
  "type": "https://eips.ethereum.org/EIPS/eip-8004#registration-v1",
  "name": "My AI Agent",
  "description": "What your agent does",
  "image": "https://example.com/agent-logo.png",
  "services": [
    { "name": "x402", "endpoint": "https://your-agent.example.com/task", "version": "1.0", "description": "Summarize documents for USDC", "inputExample": "{\"url\": \"https://example.com/doc.pdf\"}" },
    { "name": "mcp", "endpoint": "https://your-agent.example.com/mcp" },
    { "name": "a2a", "endpoint": "https://your-agent.example.com/.well-known/agent.json" }
  ],
  "supportedTrust": ["reputation"],
  "x402": true
}

Required fields:

• type — must contain eip-8004 or registration-v1
• name — non-empty string

Service Types

Each service entry supports optional description (what the service does) and inputExample (example JSON input). These are displayed in the explorer's Try panel and help users understand your agent's capabilities.

Service types affect discoverability — the explorer filters by hasServices and x402.

Hosting Your Metadata

Using the SDK

import { buildMetadataJson, toDataUri, validateMetadataJson } from '@trionlabs/stellar8004';

const metadata = buildMetadataJson({
  name: 'My AI Agent',
  description: 'Summarizes documents and answers questions',
  imageUrl: 'https://example.com/logo.png',
  services: [
    { name: 'x402', endpoint: 'https://my-agent.example.com/task', version: '1.0', description: 'Summarize documents for USDC', inputExample: '{"url": "https://example.com/doc.pdf"}' },
    { name: 'mcp', endpoint: 'https://my-agent.example.com/mcp' },
  ],
  supportedTrust: ['reputation'],
  x402Enabled: true,
});

// Validate before registering (throws on invalid metadata)
validateMetadataJson(metadata);

// Convert to data URI (fails if > 8KB)
const dataUri = toDataUri(metadata);

Common Metadata Mistakes

Step 2: Register On-Chain

Using the SDK (recommended)

import { Keypair } from '@stellar/stellar-sdk';
import { createClients, TESTNET_CONFIG, wrapBasicSigner } from '@trionlabs/stellar8004';

// Create a signer from a Stellar secret key (S-format)
const keypair = Keypair.fromSecret(process.env.STELLAR_SECRET_KEY!);
const signer = wrapBasicSigner(keypair, TESTNET_CONFIG.networkPassphrase);
const { identity } = createClients(TESTNET_CONFIG, signer);

// Register with metadata URI (recommended)
const tx = await identity.register_with_uri({
  caller: keypair.publicKey(),
  agent_uri: dataUri,  // from Step 1
});
const sent = await tx.signAndSend();
const agentId = sent.result;  // u32 — save this, it's your agent's permanent ID

// Or register with URI + metadata in one call
const tx2 = await identity.register_full({
  caller: keypair.publicKey(),
  agent_uri: dataUri,
  metadata: [{ key: 'category', value: new TextEncoder().encode('defi') }],
});
const sent2 = await tx2.signAndSend();
const agentId2 = sent2.result;

Without the SDK

All contract calls use buildAndSign() from references/build-and-sign.ts (simulate → assemble → sign → poll).

import * as StellarSdk from '@stellar/stellar-sdk';

// Register with URI
const args = [
  StellarSdk.nativeToScVal(signerAddress, { type: 'address' }),
  StellarSdk.nativeToScVal(dataUri, { type: 'string' }),
];
const { hash, result } = await buildAndSign('register_with_uri', IDENTITY_REGISTRY, args, signerAddress, signFn, rpc, networkPassphrase);
const agentId = StellarSdk.scValToNative(result) as number;

// Register minimal (no URI — agent won't be discoverable until URI is set)
const { result } = await buildAndSign('register', IDENTITY_REGISTRY, [
  StellarSdk.nativeToScVal(signerAddress, { type: 'address' }),
], signerAddress, signFn, rpc, networkPassphrase);

// Register with URI + batch metadata
const metadataVec = StellarSdk.nativeToScVal(
  [{ key: 'category', value: Buffer.from('defi') }],
  { type: { vec: { map: { key: 'string', value: 'bytes' } } } },
);
await buildAndSign('register_full', IDENTITY_REGISTRY, [
  StellarSdk.nativeToScVal(signerAddress, { type: 'address' }),
  StellarSdk.nativeToScVal(dataUri, { type: 'string' }),
  metadataVec,
], signerAddress, signFn, rpc, networkPassphrase);

Updating Your Agent

// Update metadata URI (triggers re-indexing)
await buildAndSign('set_agent_uri', IDENTITY_REGISTRY, [
  StellarSdk.nativeToScVal(signerAddress, { type: 'address' }),  // caller
  StellarSdk.nativeToScVal(agentId, { type: 'u32' }),
  StellarSdk.nativeToScVal('ipfs://QmNewMetadata...', { type: 'string' }),
], signerAddress, signFn, rpc, networkPassphrase);

// Set on-chain key-value metadata
await buildAndSign('set_metadata', IDENTITY_REGISTRY, [
  StellarSdk.nativeToScVal(signerAddress, { type: 'address' }),
  StellarSdk.nativeToScVal(agentId, { type: 'u32' }),
  StellarSdk.nativeToScVal('category', { type: 'string' }),      // max 64 bytes
  StellarSdk.nativeToScVal(Buffer.from('defi'), { type: 'bytes' }), // max 4KB
], signerAddress, signFn, rpc, networkPassphrase);

// Set agent wallet — BOTH caller and wallet must authorize (dual require_auth)
await buildAndSign('set_agent_wallet', IDENTITY_REGISTRY, [
  StellarSdk.nativeToScVal(signerAddress, { type: 'address' }),   // caller (owner)
  StellarSdk.nativeToScVal(agentId, { type: 'u32' }),
  StellarSdk.nativeToScVal(walletAddress, { type: 'address' }),   // new wallet
], signerAddress, signFn, rpc, networkPassphrase);

// Read helpers (simulate only, no signing needed)
// agent_uri(agent_id) → Result<String>
// get_metadata(agent_id, key) → Option<Bytes>
// get_agent_wallet(agent_id) → Option<Address>
// find_owner(agent_id) → Option<Address>
// agent_exists(agent_id) → bool
// total_agents() → u32

Extending TTL (Preventing Data Archival)

Soroban data expires if not extended. Call extend_ttl periodically to keep your agent's data alive:

await buildAndSign('extend_ttl', IDENTITY_REGISTRY, [
  StellarSdk.nativeToScVal(agentId, { type: 'u32' }),
], signerAddress, signFn, rpc, networkPassphrase);

This extends TTL for: agent URI, wallet, all metadata keys + values, NFT owner, and owner balance. Without this, archived agents become invisible to on-chain reads.

Step 3: Get Indexed and Discovered

What Happens After Registration

1. You call register_with_uri() → Registered event emitted on-chain
2. Indexer detects event → creates agent record (resolve_uri_pending = true)
3. resolve-uris edge function runs every 30 seconds
4. Fetches your metadata URL → parses services, trust settings
5. Exponential backoff retry: 2, 4, 8, 16, 32 minutes (max 5 attempts)
6. On success: agent becomes searchable and visible in explorer
7. Your agent page: https://stellar8004.com/agents/{agentId}

Verify Your Registration

import { ExplorerClient } from '@trionlabs/stellar8004';

const explorer = new ExplorerClient(); // defaults to mainnet explorer
const agent = await explorer.getAgent(agentId);
console.log(agent.name, agent.services, agent.totalScore);

// Or check if your agents are listed
const myAgents = await explorer.getAgentsByAddress(myAddress);

Explorer API

Base URL: https://stellar8004.com. Rate limit: 30 requests per IP.

Troubleshooting

Step 4: Reputation — Give and Read Feedback

Why Reputation Matters

Reputation is the core of trust between agents:

• Trust before payment — check an agent's score before paying for its services via x402
• Sybil resistance — get_summary accepts a filtered client list, letting you weight trusted sources
• Discoverability — higher-scoring agents rank higher in the explorer (Total Score = Avg Feedback × 0.6 + Volume Factor × 0.2)
• Accountability — agents can respond to feedback on-chain via append_response

Score Calculation

Total Score = (Average Feedback × 0.6) + (Volume Factor × 0.2)
Volume Factor = min(100, log(feedbackCount) / log(100) × 100)

More feedback from more unique clients = higher score = better discoverability.

give_feedback

Self-feedback is blocked. value is i128 (supports negative). value_decimals max 18.

// Create feedback hash (SHA-256)
const content = JSON.stringify({ quality: 'excellent', latency: '200ms' });
const hashBuf = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(content));

const args = [
  StellarSdk.nativeToScVal(signerAddress, { type: 'address' }),   // caller (client)
  StellarSdk.nativeToScVal(agentId, { type: 'u32' }),             // agentId
  StellarSdk.nativeToScVal(BigInt(85), { type: 'i128' }),         // value (0-100 scale)
  StellarSdk.nativeToScVal(0, { type: 'u32' }),                   // valueDecimals
  StellarSdk.nativeToScVal('starred', { type: 'string' }),        // tag1 (max 64 chars)
  StellarSdk.nativeToScVal('', { type: 'string' }),               // tag2
  StellarSdk.nativeToScVal('https://agent.example.com', { type: 'string' }), // endpoint
  StellarSdk.nativeToScVal('', { type: 'string' }),               // feedbackUri
  StellarSdk.nativeToScVal(new Uint8Array(hashBuf), { type: 'bytes' }),       // feedbackHash
];
await buildAndSign('give_feedback', REPUTATION_REGISTRY, args, signerAddress, signFn, rpc, networkPassphrase);

Storage note: Only value, value_decimals, is_revoked, tag1, tag2 are stored on-chain. The endpoint, feedback_uri, and feedback_hash are emitted as event data only — to read them later, use the explorer API or parse events.

revoke_feedback

Revokes feedback you previously gave. Only the original feedback author can revoke.

await buildAndSign('revoke_feedback', REPUTATION_REGISTRY, [
  StellarSdk.nativeToScVal(signerAddress, { type: 'address' }),   // caller (original client)
  StellarSdk.nativeToScVal(agentId, { type: 'u32' }),
  StellarSdk.nativeToScVal(BigInt(1), { type: 'u64' }),           // feedbackIndex (1-indexed)
], signerAddress, signFn, rpc, networkPassphrase);

append_response

Callable by anyone — any authenticated account, not only the agent owner. The responder's address is recorded in the ResponseAppended event topic, so consumers must treat a response as coming from responder (not necessarily the agent owner) and must NOT assume a response proves agent-owner authorship. Multiple responses per feedback allowed.

const responseContent = JSON.stringify({ reply: 'Thank you for the feedback, we improved latency.' });
const responseHashBuf = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(responseContent));

await buildAndSign('append_response', REPUTATION_REGISTRY, [
  StellarSdk.nativeToScVal(signerAddress, { type: 'address' }),       // caller (any authenticated account; recorded as responder)
  StellarSdk.nativeToScVal(agentId, { type: 'u32' }),
  StellarSdk.nativeToScVal(clientAddress, { type: 'address' }),       // feedback author
  StellarSdk.nativeToScVal(BigInt(1), { type: 'u64' }),               // feedbackIndex
  StellarSdk.nativeToScVal('https://response.example.com', { type: 'string' }), // responseUri
  StellarSdk.nativeToScVal(new Uint8Array(responseHashBuf), { type: 'bytes' }), // responseHash
], signerAddress, signFn, rpc, networkPassphrase);

read_feedback

Reads a single feedback entry. Returns stored fields only (not event-only fields like endpoint or feedbackUri).

const args = [
  StellarSdk.nativeToScVal(agentId, { type: 'u32' }),
  StellarSdk.nativeToScVal(clientAddress, { type: 'address' }),
  StellarSdk.nativeToScVal(BigInt(1), { type: 'u64' }),  // feedbackIndex (1-indexed)
];

const { result } = await buildAndSign('read_feedback', REPUTATION_REGISTRY, args, signerAddress, signFn, rpc, networkPassphrase);
const feedback = StellarSdk.scValToNative(result);
// Returns FeedbackData:
// {
//   value: i128,           — the feedback score
//   value_decimals: u32,   — decimal precision
//   is_revoked: bool,      — whether revoked
//   tag1: string,          — primary tag
//   tag2: string,          — secondary tag
// }

get_summary — Running Aggregates

Returns aggregated reputation across multiple clients. No stored aggregates — the contract iterates all feedback on every call.

const args = [
  StellarSdk.nativeToScVal(agentId, { type: 'u32' }),
  StellarSdk.nativeToScVal(clientAddresses, { type: { vec: 'address' } }), // max 5 clients
  StellarSdk.nativeToScVal('starred', { type: 'string' }),  // tag1 filter ('' = all)
  StellarSdk.nativeToScVal('', { type: 'string' }),         // tag2 filter ('' = all)
];

const { result } = await buildAndSign('get_summary', REPUTATION_REGISTRY, args, signerAddress, signFn, rpc, networkPassphrase);
const summary = StellarSdk.scValToNative(result);
// Returns SummaryResult:
// {
//   count: u64,                    — number of matching feedback entries
//   summary_value: i128,           — WAD-normalized average score
//   summary_value_decimals: u32,   — mode decimal precision (most common)
// }

Performance characteristics:

• MAX_SUMMARY_CLIENTS = 5 — contract limits to 5 client addresses per call
• Complexity: O(clients × feedbacks_per_client) — iterates all non-revoked feedback
• Filters by tag1 and tag2 (empty string = no filter)
• Revoked feedback is excluded automatically
• Sybil best practice: pass a curated list of trusted client addresses, not all clients

get_clients_paginated

Paginated list of addresses that have given feedback to an agent. Soroban per-tx budget caps arrays at ~100 entries.

const args = [
  StellarSdk.nativeToScVal(agentId, { type: 'u32' }),
  StellarSdk.nativeToScVal(0, { type: 'u32' }),    // start index
  StellarSdk.nativeToScVal(20, { type: 'u32' }),   // limit
];

const { result } = await buildAndSign('get_clients_paginated', REPUTATION_REGISTRY, args, signerAddress, signFn, rpc, networkPassphrase);
const clients = StellarSdk.scValToNative(result) as string[];

get_last_index and get_response_count

// Get the latest feedback index for a specific client
// Returns u64 — the highest feedback_index this client has given to this agent
const { result } = await buildAndSign('get_last_index', REPUTATION_REGISTRY, [
  StellarSdk.nativeToScVal(agentId, { type: 'u32' }),
  StellarSdk.nativeToScVal(clientAddress, { type: 'address' }),
], signerAddress, signFn, rpc, networkPassphrase);
const lastIndex = StellarSdk.scValToNative(result) as number;

// Get the number of responses to a specific feedback entry
// Returns u32
const { result: countResult } = await buildAndSign('get_response_count', REPUTATION_REGISTRY, [
  StellarSdk.nativeToScVal(agentId, { type: 'u32' }),
  StellarSdk.nativeToScVal(clientAddress, { type: 'address' }),
  StellarSdk.nativeToScVal(BigInt(1), { type: 'u64' }),  // feedbackIndex
], signerAddress, signFn, rpc, networkPassphrase);
const responseCount = StellarSdk.scValToNative(countResult) as number;

Reading Feedback via Explorer API (Off-Chain)

For bulk reads, the explorer API is more efficient than on-chain calls:

import { ExplorerClient } from '@trionlabs/stellar8004';

const explorer = new ExplorerClient();
const feedback = await explorer.getFeedback(agentId, { tag: 'starred', limit: 50 });
// Returns full feedback entries including event-only fields (endpoint, feedbackUri, feedbackHash)

Feedback Tags

Tags are free-form strings (max 64 chars). The above are conventions, not enforced by the contract.

Step 5: Validation

Why Validation Matters

Reputation measures past performance. Validation attests to agent properties — identity verification, code audits, hardware guarantees.

validation_request

Submit a validation request for your agent to a specific validator.

// Generate unique request hash
const data = new TextEncoder().encode(
  `${agentId}:${validatorAddr}:${Date.now()}:${crypto.randomUUID()}`
);
const requestHash = new Uint8Array(await crypto.subtle.digest('SHA-256', data));

await buildAndSign('validation_request', VALIDATION_REGISTRY, [
  StellarSdk.nativeToScVal(signerAddress, { type: 'address' }),    // caller
  StellarSdk.nativeToScVal(validatorAddr, { type: 'address' }),    // validator
  StellarSdk.nativeToScVal(agentId, { type: 'u32' }),              // agentId
  StellarSdk.nativeToScVal('https://request.example.com', { type: 'string' }), // requestUri
  StellarSdk.nativeToScVal(requestHash, { type: 'bytes' }),        // requestHash
], signerAddress, signFn, rpc, networkPassphrase);

Or with the SDK:

import { generateRequestNonce } from '@trionlabs/stellar8004';
// generateRequestNonce is async (it awaits crypto.subtle.digest) — you MUST await it.
const requestHash = await generateRequestNonce(agentId, validatorAddr);

validation_response

Validator responds to a pending request.

const responseContent = JSON.stringify({ result: 'passed', details: 'code audit complete' });
const responseHashBuf = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(responseContent));

await buildAndSign('validation_response', VALIDATION_REGISTRY, [
  StellarSdk.nativeToScVal(validatorAddr, { type: 'address' }),    // caller (validator)
  StellarSdk.nativeToScVal(requestHash, { type: 'bytes' }),        // requestHash
  StellarSdk.nativeToScVal(85, { type: 'u32' }),                   // response: a 0-100 score (values > 100 revert with InvalidResponse)
  StellarSdk.nativeToScVal('https://response.example.com', { type: 'string' }), // responseUri
  StellarSdk.nativeToScVal(new Uint8Array(responseHashBuf), { type: 'bytes' }), // responseHash
  StellarSdk.nativeToScVal('kyc', { type: 'string' }),             // tag
], validatorAddr, validatorSignFn, rpc, networkPassphrase);

get_validation_status

const { result } = await buildAndSign('get_validation_status', VALIDATION_REGISTRY, [
  StellarSdk.nativeToScVal(requestHash, { type: 'bytes' }),
], signerAddress, signFn, rpc, networkPassphrase);
const status = StellarSdk.scValToNative(result);
// Returns ValidationStatus:
// {
//   validator_address: Address,
//   agent_id: u32,
//   response: u32,            — a 0-100 score set by the validator (values > 100 revert).
//                               Use has_response (below), NOT response == 0, to detect "pending".
//   response_hash: BytesN<32>,
//   tag: string,
//   last_update: u64,         — ledger sequence
//   has_response: bool,
// }

Storage note: response_uri is event-only — use the indexer or parse ValidationResponse events to retrieve it.

get_summary (Validation)

const { result } = await buildAndSign('get_summary', VALIDATION_REGISTRY, [
  StellarSdk.nativeToScVal(agentId, { type: 'u32' }),
  StellarSdk.nativeToScVal(validatorAddresses, { type: { vec: 'address' } }),
  StellarSdk.nativeToScVal('kyc', { type: 'string' }),  // tag filter ('' = all)
], signerAddress, signFn, rpc, networkPassphrase);
// Returns ValidationSummary with counts and response breakdown

Paginated Queries

// All validation request hashes for an agent
const { result } = await buildAndSign('get_agent_validations_paginated', VALIDATION_REGISTRY, [
  StellarSdk.nativeToScVal(agentId, { type: 'u32' }),
  StellarSdk.nativeToScVal(0, { type: 'u32' }),    // start
  StellarSdk.nativeToScVal(20, { type: 'u32' }),   // limit
], signerAddress, signFn, rpc, networkPassphrase);

// All request hashes assigned to a validator
const { result: valResult } = await buildAndSign('get_validator_requests_paginated', VALIDATION_REGISTRY, [
  StellarSdk.nativeToScVal(validatorAddr, { type: 'address' }),
  StellarSdk.nativeToScVal(0, { type: 'u32' }),
  StellarSdk.nativeToScVal(20, { type: 'u32' }),
], signerAddress, signFn, rpc, networkPassphrase);

// Check if a request exists
// request_exists(requestHash) → bool

Trust Verification Workflow

Full end-to-end: verify identity → check reputation → interact → pay via x402 → give feedback.

import * as StellarSdk from '@stellar/stellar-sdk';
import { ExplorerClient } from '@trionlabs/stellar8004';

async function verifyAndInteract(targetAgentId: number, minScore = 70) {
  const explorer = new ExplorerClient();

  // 1. Verify agent exists and get metadata
  const agent = await explorer.getAgent(targetAgentId);
  if (!agent) throw new Error('Agent not found');

  // 2. Check reputation threshold
  if (agent.feedbackCount > 0 && agent.avgScore < minScore) {
    throw new Error(`Agent score ${agent.avgScore} below threshold ${minScore}`);
  }

  // 3. Find the service endpoint
  const x402Service = agent.services?.find(s => s.name === 'x402');
  if (!x402Service) throw new Error('Agent has no x402 endpoint');

  // 4. Interact via x402 payment (see /x402stellar skill)
  const response = await fetchPaid(x402Service.endpoint);
  const result = await response.json();

  // 5. Give feedback based on outcome
  const feedbackValue = result.success ? BigInt(90) : BigInt(30);
  const tag = result.success ? 'starred' : 'failed';

  const hashBuf = await crypto.subtle.digest('SHA-256',
    new TextEncoder().encode(JSON.stringify(result)));

  await buildAndSign('give_feedback', REPUTATION_REGISTRY, [
    StellarSdk.nativeToScVal(signerAddress, { type: 'address' }),
    StellarSdk.nativeToScVal(targetAgentId, { type: 'u32' }),
    StellarSdk.nativeToScVal(feedbackValue, { type: 'i128' }),
    StellarSdk.nativeToScVal(0, { type: 'u32' }),
    StellarSdk.nativeToScVal(tag, { type: 'string' }),
    StellarSdk.nativeToScVal('', { type: 'string' }),
    StellarSdk.nativeToScVal(x402Service.endpoint, { type: 'string' }),
    StellarSdk.nativeToScVal('', { type: 'string' }),
    StellarSdk.nativeToScVal(new Uint8Array(hashBuf), { type: 'bytes' }),
  ], signerAddress, signFn, rpc, networkPassphrase);

  return result;
}

x402 Integration

Combine agent trust (/8004stellar) with payments (/x402stellar):

async function payTrustedAgent(agentId: number, serviceUrl: string) {
  const explorer = new ExplorerClient();

  // 1. Check reputation before paying
  const agent = await explorer.getAgent(agentId);
  if ((agent.avgScore ?? 0) < 80) {
    throw new Error('Agent not trusted enough for payment');
  }

  // 2. Pay via x402 (see /x402stellar skill for full setup)
  const response = await fetchPaid(serviceUrl);

  // 3. Give feedback after service delivery
  // (see give_feedback example above)
}

Pattern: verify trust → pay → give feedback. This creates a virtuous cycle — good agents earn reputation, bad agents lose it.

Storage vs Events

Understanding what's stored on-chain vs emitted as events is critical for reading data correctly.

What's Stored On-Chain (readable via contract calls)

What's Event-Only (need indexer or event parsing)

Why This Matters

• read_feedback() returns { value, value_decimals, is_revoked, tag1, tag2 } — not endpoint or feedbackUri
• To get endpoint/URI fields, use the Explorer API (explorer.getFeedback()) or parse events via rpc.getEvents()
• get_validation_status() returns everything except response_uri — parse ValidationResponse events for that

Error Handling

Transaction Errors

Contract Error Codes

Identity Registry (11 codes): not owner or approved, URI not set, agent not found, metadata key too long, metadata value too long, too many metadata keys, reserved metadata key, empty value, no upgrade proposed, timelock not expired, upgrade already proposed

Reputation Registry (12 codes): self-feedback, feedback not found, invalid value decimals, not owner or approved (retained for ABI stability, unused), aggregate overflow, agent not found, empty value, value out of range, client addresses required, no upgrade proposed, timelock not expired, upgrade already proposed

Validation Registry (11 codes): not owner or approved, request not found, invalid response, request already exists, not designated validator, already responded (retained for ABI stability, unused), agent not found, counter overflow, no upgrade proposed, timelock not expired, upgrade already proposed

Use formatSorobanError(err) from the SDK to convert error codes to readable messages.

Technical Reference

All Public Methods

Identity Registry

Ownership (OZ 2-step): get_owner(), transfer_ownership(new_owner), accept_ownership(), renounce_ownership()

Upgrades (3-day timelock): propose_upgrade(new_wasm_hash), execute_upgrade(), cancel_upgrade(), pending_upgrade()

Reputation Registry

Validation Registry

Contract Events

Identity Events

Wallet changes emit MetadataSet with key="agentWallet" — no separate WalletSet/WalletRemoved events.

Reputation Events

Validation Events

Querying Events

const rpc = new StellarSdk.rpc.Server('https://soroban-testnet.stellar.org');
const events = await rpc.getEvents({
  startLedger: lastProcessedLedger,
  filters: [{ type: 'contract', contractIds: [IDENTITY_REGISTRY] }],
  limit: 100,
});
for (const event of events.events) {
  const eventName = StellarSdk.scValToNative(event.topic[0]);
  const firstTopic = StellarSdk.scValToNative(event.topic[1]);
  // topic[0] = event name, topic[1..n] = indexed fields, event.value = data body
}

Additional Resources

• EIP-8004 Specification | 8004.org
• Stellar 8004 Contracts | 8004scan Explorer

Related Skills

• stellar-dev — General Stellar/Soroban development (required companion)
• x402stellar — x402 payment protocol on Stellar