8004-solana

8004-solana

TypeScript SDK for 8004 Agent Registry on Solana.

Autonomous Agents (Clawbot, Moltbot, etc.): See skill.md for the complete SDK reference designed for autonomous AI agent consumption.

New here? Follow the Quickstart Guide to register your first agent in 5 minutes.

Features

• Collect requester-driven verified feedback with ProofPass
• Register agents as NFTs on Solana blockchain
• Manage agent metadata and endpoints (MCP, A2A)
• Submit and query reputation feedback with SEAL v1 integrity verification
• Sign & verify with agent operational wallets
• OASF taxonomies support (skills & domains)

Installation

npm install 8004-solana

Network Defaults

• mainnet-beta: the implicit default; RPC and program IDs are preconfigured.
• devnet: still available explicitly via getProgramIds('devnet') or SolanaSDK({ cluster: 'devnet' }).
• localnet: supported; set local deployed programIds.
• Standalone lookups: use getProgramIds() for mainnet, getProgramIds('devnet') for devnet, or sdk.getProgramIds() from a configured SolanaSDK instance.
• See the Indexer section for the combined network + indexer config snippet.

Transaction version 1 reads

The SDK-created connection can read legacy, version 0, and version 1 transactions. Raw connection callers must opt into version 1 on each applicable RPC call:

const connection = sdk.getSolanaClient().getConnection();

const transaction = await connection.getTransaction(signature, {
  maxSupportedTransactionVersion: 1,
});
const block = await connection.getBlock(slot, {
  maxSupportedTransactionVersion: 1,
});

This read compatibility does not add version 1 transaction building or signing support.

Quick Start

import {
  SolanaSDK,
  IPFSClient,
  buildRegistrationFileJson,
  ServiceType,
  Tag,
} from '8004-solana';
import { Keypair } from '@solana/web3.js';

const signer = Keypair.fromSecretKey(/* your key */);
const pinataJwt = 'your-pinata-jwt';
const ipfs = pinataJwt
  ? new IPFSClient({ pinataEnabled: true, pinataJwt })
  : new IPFSClient({ url: 'http://localhost:5001' });
const sdk = new SolanaSDK({ cluster: 'mainnet-beta', signer, ipfsClient: ipfs });

// 1. Create complete collection metadata + upload (off-chain)
const collectionInput = {
  name: 'CasterCorp Agents',
  symbol: 'CAST',
  description: 'Main collection for CasterCorp agents',
  image: 'ipfs://QmCollectionImage...',
  banner_image: 'ipfs://QmCollectionBanner...',
  socials: {
    website: 'https://castercorp.ai',
    x: 'https://x.com/castercorp',
    discord: 'https://discord.gg/castercorp',
  },
};
const collection = await sdk.createCollection(collectionInput);

console.log('Collection CID:', collection.cid);   // <- reuse this in your asset workflow
console.log('Collection URI:', collection.uri);   // ipfs://<cid>
console.log('Collection Pointer:', collection.pointer); // c1:b...

// 2. Build agent metadata
const agentMeta = buildRegistrationFileJson({
  name: 'My AI Agent',
  description: 'Autonomous agent for task automation',
  image: 'ipfs://QmAgentAvatar...',
  services: [
    { type: ServiceType.MCP, value: 'https://api.example.com/mcp' },
    { type: ServiceType.A2A, value: 'https://api.example.com/a2a' },
    { type: ServiceType.OASF, value: 'https://api.example.com/oasf' },
    { type: ServiceType.SNS, value: 'castercorp.sol' },
  ],
  skills: ['natural_language_processing/natural_language_generation/text_completion'],
  domains: ['technology/software_engineering/software_engineering'],
});

// 3. Upload and register (ATOM is off by default; pass atomEnabled: true to opt in now)
const metadataUri = `ipfs://${await ipfs.addJson(agentMeta)}`;
const agent = await sdk.registerAgent(metadataUri, { collectionPointer: collection.pointer! });
console.log('Agent:', agent.asset.toBase58());

// 4. Set operational wallet
const opWallet = Keypair.generate();
await sdk.setAgentWallet(agent.asset, opWallet);

// 5. Give feedback - accepts decimal strings or raw values
await sdk.giveFeedback(agent.asset, {
  value: '99.77',                  // Decimal string -> auto-encoded to 9977, decimals=2
  tag1: Tag.uptime,                // 8004 standardized tag (or free text)
  tag2: Tag.day,                   // Time period
  feedbackUri: 'ipfs://QmFeedback...',
});

// 6. Check reputation
const summary = await sdk.getSummary(agent.asset);
console.log(`Score: ${summary.averageScore}, Feedbacks: ${summary.totalFeedbacks}`);

Create Collection (CID-first flow)

const collectionInput = {
  name: 'My Collection',
  symbol: 'MYCOL',
  description: 'Collection metadata stored on IPFS',
  image: 'ipfs://QmCollectionImage...',
  banner_image: 'ipfs://QmCollectionBanner...',
  socials: {
    website: 'https://example.com',
    x: 'https://x.com/example',
    discord: 'https://discord.gg/example',
  },
};
const collectionUpload = await sdk.createCollection(collectionInput);

// Returned by createCollection()
const cid = collectionUpload.cid;          // e.g. Qm...
const uri = collectionUpload.uri;          // ipfs://Qm...
const pointer = collectionUpload.pointer;  // c1:b...

// Use `cid` / `uri` in your asset creation pipeline.

Collection and parent association rules are documented in docs/COLLECTION.md.
Advanced end-to-end usage is shown in examples/collection-flow.ts.

Web3 Wallet (Phantom, Solflare)

// For setAgentWallet with browser wallets
const prepared = await sdk.prepareSetAgentWallet(agent.asset, walletPubkey);
const signature = await wallet.signMessage(prepared.message);
await prepared.complete(signature);

Sign & Verify

// Sign any data with agent's operational wallet
const signed = sdk.sign(agent.asset, {
  action: 'authorize',
  user: 'alice',
  permissions: ['read', 'write'],
});

// Returns canonical JSON:
// {
//   "alg": "ed25519",
//   "asset": "AgentAssetPubkey...",
//   "data": { "action": "authorize", "permissions": ["read","write"], "user": "alice" },
//   "issuedAt": 1705512345,
//   "nonce": "randomBase58String",
//   "sig": "base58Ed25519Signature...",
//   "v": 1
// }

// Verify (fetches agent wallet from chain)
const isValid = await sdk.verify(signed, agent.asset);

// Verify with known public key (no RPC)
const isValid2 = await sdk.verify(signed, agent.asset, opWallet.publicKey);

Liveness Check

// Ping agent endpoints
const report = await sdk.isItAlive(agent.asset);
console.log(report.status); // 'live' | 'partially' | 'not_live'
console.log(report.liveServices, report.deadServices);

Read-Only Mode

import { PublicKey } from '@solana/web3.js';

const sdk = new SolanaSDK({ cluster: 'devnet' }); // No signer = read-only
const asset = new PublicKey('YourAgentAssetPubkey...');

const agent = await sdk.loadAgent(asset);
const summary = await sdk.getSummary(asset);

ProofPass

ProofPass is the requester-driven verified feedback flow for 8004-solana.

A service opens a feedback request, then the reviewer finalizes a real giveFeedback() later. The final feedback is still attributed to the reviewer, not to the ProofPass program.

creator must be the immutable creator recorded in the target agent's 8004 AgentAccount. It is not just any service wallet or the current live owner after a transfer.

import { openProofPass, giveFeedbackWithProof } from '8004-solana';

const flow = await openProofPass({
  connection,
  creator: serviceWallet.publicKey,
  reviewer: customerWallet.publicKey,
  targetAgent: agent.asset,
  contextRef: `request:${requestId}`,
});

const finalizeIx = await giveFeedbackWithProof({
  connection,
  session: flow.sessionPda,
  reviewer: customerWallet.publicKey,
  feedback: {
    value: '42',
    tag1: 'quality',
  },
});

See the public examples:

• ProofPass Example
• ProofPass + x402 Example

Feedback System

The feedback system supports rich metrics with 8004 standardized tags. value is required, score is optional.

// Basic feedback (feedbackUri optional, defaults to '')
await sdk.giveFeedback(agent.asset, {
  value: '85',
  tag1: 'starred',
});

// Revenue tracking with decimals
await sdk.giveFeedback(agent.asset, {
  value: '150.00',       // $150.00 -> auto-encoded to 15000, decimals=2
  tag1: 'revenues',
  tag2: 'week',
  feedbackUri: 'ipfs://QmRevenue...',
});

// Uptime tracking
await sdk.giveFeedback(agent.asset, {
  value: '99.50',        // 99.50% -> auto-encoded to 9950, decimals=2
  tag1: 'uptime',
  tag2: 'day',
  feedbackUri: 'ipfs://QmUptime...',
});

Revoke Workflows

revokeFeedback() now does indexer preflight by default:

• Uses signer (or options.signer) as the feedback client.
• Refuses revoke when feedback is missing for that client or already revoked.
• Auto-resolves sealHash when omitted; if provided, it must match indexed sealHash.

await sdk.revokeFeedback(agent.asset, 12n); // preflight + auto sealHash

await sdk.revokeFeedback(agent.asset, 12n, sealHash, {
  verifyFeedbackClient: false, // intentionally skip ownership preflight
  waitForIndexerSync: false,   // skip indexer sync wait
});

See FEEDBACK.md for all 8004 tags and patterns. See independent file and SEAL verification for the full replay and original-byte checks.

Tags

Use Tag helpers for standard tags, or pass custom strings (max 32 bytes):

import { Tag } from '8004-solana';

// Using Tag helper
await sdk.giveFeedback(asset, {
  value: '99.77',
  tag1: Tag.uptime,     // 'uptime'
  tag2: Tag.day,        // 'day'
  feedbackUri: 'ipfs://QmFeedback...',
});

// Custom tags (free text)
await sdk.giveFeedback(asset, {
  value: '42.5',
  tag1: 'my-custom-metric',
  tag2: 'hourly',
  feedbackUri: 'ipfs://QmFeedback...',
});

See FEEDBACK.md for the complete tag reference.

ATOM Engine

By default, registerAgent() does not initialize ATOM stats (atomEnabled: false). ATOM provides:

• Trust Tiers: Bronze → Silver → Gold → Platinum
• Quality Score: Weighted average with decay
• Sybil Detection: HyperLogLog client tracking
• Legit Lane Reads: canonical per-asset legit summaries via getLegitSummary(asset)

// Enable ATOM during registration
await sdk.registerAgent('ipfs://...', { atomEnabled: true });

Or enable later after registration:

await sdk.enableAtom(asset);
await sdk.initializeAtomStats(asset);

enableAtom() is one-way/irreversible for that agent (cannot be disabled later).

Legit lane read path:

const legitSummary = await sdk.getLegitSummary(asset);
const legitSnapshot = await sdk.getLegitSnapshot(asset);

Use getLegitSummary(asset) as the canonical read when you need isAuthoritative. For localnet/custom deployments, pass explicit programIds in the SDK config.

To permanently remove an agent Core asset:

await sdk.burnAgent(asset); // irreversible burn

burnAgent() burns the Core asset only (it does not close the on-chain AgentAccount PDA).

SEAL helper methods and examples are documented in docs/METHODS.md#seal-v1-methods. The full ATOM + legit-lane read guide is in docs/ATOM.md.

RPC Provider Recommendations

The default Solana RPC for the selected cluster works for basic operations. On devnet, the public RPC is limited; for production or advanced queries (getAllAgents, getAgentsByOwner), use a custom RPC.

const sdk = new SolanaSDK({
  rpcUrl: 'https://your-helius-rpc.helius.dev',
  signer: yourKeypair,
});

Examples

Indexer

The SDK uses the indexer for search, collection reads, sequential ids, and large reads. Default backend is GraphQL v2.

const indexed = await sdk.getAgentByAgentId(42);

Built-in public endpoints:

• mainnet-beta: https://8004-indexer-main.qnt.sh
• devnet / testnet: https://8004-indexer-dev.qnt.sh

Self-hosting:

• 8004-solana-indexer

If you upgrade a self-hosted indexer with a persisted DB, apply the pending DB migrations before restart.

Documentation

• API Reference - All methods with examples
• Feedback Guide - Tags, value/decimals, advanced patterns
• ProofPass Example - Generic requester-driven verified feedback flow
• ProofPass + x402 Example - Compact x402-compatible flow
• Collection Guide - Collection pointer and parent association rules
• Quickstart - Step-by-step guide
• Costs - Transaction costs
• OASF Taxonomies - Skills & domains reference
• AI Agent Skill - SDK reference for AI agents (MCP/LLM)

Community & Support

• Telegram: t.me/sol8004
• X (Twitter): x.com/Quantu_AI
• 8004 Standard: eips.ethereum.org/EIPS/eip-8004

License

MIT