8004-solana

v0.8.3

Published

2 months ago

TypeScript SDK for 8004 on Solana - agent identity, reputation, and ProofPass

0High
0Medium
0Low

quantulabs

solana erc-8004 agent reputation identity blockchain web3 nft

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:

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.

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

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

8004-solana

Features

Installation

Network Defaults

Quick Start

Create Collection (CID-first flow)

Web3 Wallet (Phantom, Solflare)

Sign & Verify

Liveness Check

Read-Only Mode

ProofPass

Feedback System

Revoke Workflows

Tags

ATOM Engine

RPC Provider Recommendations

Examples

Indexer

Documentation

Community & Support

License