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

• devnet: fully configured by default.
• mainnet-beta: fully configured by default.
• localnet: supported; set local deployed programIds.
• See the Indexer section for the combined network + indexer config snippet.

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.

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

// 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).

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.

RPC Provider Recommendations

Default Solana devnet RPC works for basic operations. For production or advanced queries (getAllAgents, getAgentsByOwner), use a custom RPC.

Provider	Free Tier	Signup
Helius	100k req/month	helius.dev
QuickNode	10M credits/month	quicknode.com
Alchemy	300M CU/month	alchemy.com

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

Examples

Example	Description
quick-start.ts	Basic read/write with IPFS upload
collection-flow.ts	Full collection metadata + create 20 associated agent assets
feedback-usage.ts	Submit and read feedback
agent-update.ts	On-chain metadata & URI update
transfer-agent.ts	Transfer agent ownership (also possible via standard token wallet transfer)
server-mode.ts	Server/client architecture with skipSend
proofpass.md	Generic requester-driven ProofPass flow
proofpass-x402.md	Compact x402-compatible ProofPass flow

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