8004-索拉纳

TypeScript SDK for 8004 Agent Register on Solana. 索拉纳的代理注册.

自治代理人 (克劳博特,莫特博特等): 见 skill.md 为自动AI剂消费设计的完整的SDK参考.

新来的? 跟着 快速启动指南 5分钟后登记第一个探员.

特征

• 收集请求人驱动的经核实的反馈 与 ProofPass
• 将代理注册为 NFT 索拉纳区块链
• 管理代理元数据 和终点(MCP, A2A)
• 提交和查询声誉反馈 海豹突击队 v1 完整性验证
• 签名验证( V) 有代理操作钱包
• OASF 分类学 支持(技能和域)

安装

npm install 8004-solana

网络默认

• mainnet-beta:隐性默认;RPC与程序ID被预配置.
• devnet:仍可通过下列方式明确提供: getProgramIds('devnet') 或者说 SolanaSDK({ cluster: 'devnet' })。 。 。 .
• localnet: 支持; 设置本地部署 programIds。 。 。 .
• 独立浏览: 使用 getProgramIds() 为主网, getProgramIds('devnet') 用于devnet,或 sdk.getProgramIds() 从配置 SolanaSDK 举个例子.
• 见 索引器 区域,用于合并网络+索引器配置片段.

交易版本1为

SDK所创建的连接可以读取遗产,版本0,和版本1的交易. 原始连接调用者必须在每次适用的RPC调用时选择第一版:

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

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

此读取相容性不添加版本 1 的交易构建或签名支持 .

快速启动

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}`);

创建收藏( CID- 第一流)

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.

收集与母协会规则载于 docs/COLLECTION.md。 。 。 .
高级端到端使用如下所示: examples/collection-flow.ts。 。 。 .

Web3 钱包( 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);

签名校验( V)

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

生活检查

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

仅读模式

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 是请求者驱动的已核实的反馈流量,用于 8004-solana。 。 。 .

一个服务打开一个反馈请求, 然后审查者最后确定一个真实的 giveFeedback() 等会. 最后反馈仍归因于 reviewer,不给 ProofPass 程序.

creator 必须是不可改变的 creator 目标代理人8004记录 AgentAccount。 。 。 . 不仅仅是任何服务钱包, 也不是转移后的当前现场所有者 .

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',
  },
});

参见公众实例:

• 证明文件示例
• 证明 Pass + x402 示例

反馈系统

反馈系统支持有8004个标准化标记的丰富的度量衡. value 需要, score 是可选的.

// 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...',
});

撤销工作流程

revokeFeedback() 现在默认情况下执行索引器预飞:

• 用户签名器( 或 options.signer)作为反馈客户端.
• 当该客户端的反馈缺失或已经被撤销时,拒绝撤销.
• 自动解析 sealHash 省略时; 如果提供了, 它必须匹配索引 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
});

见 费德巴克(英语:Feedback.md) 所有8004标记和图案. 见 独立文件和海豹突击队核查 完全重放和原字节检查.

标记

使用 Tag 用于标准标记的助手,或通过自定义字符串(最大 32 字节):

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...',
});

见 费德巴克(英语:Feedback.md) 用于完整的标签引用.

ATOM 引擎

默认, registerAgent() 已经 没有 初始化 ATOM 统计(atomEnabled: falseATOM规定:

• 信任级别:青铜 → 银 → 金 → 白金
• 质量分数: 有衰变的加权平均值
• Sybil 检测: HyperLogLog客户端跟踪
• 读取:通过下列途径对每个资产进行分类: getLegitSummary(asset)

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

或者在登记后允许:

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

enableAtom() 对于该代理是单向/不可逆的(以后不能禁用).

合法行读取路径 :

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

使用 getLegitSummary(asset) 在你需要的时候读到 isAuthoritative。 。 。 . 当地网/海关部署,通过明确 programIds 在SDK配置.

永久去除代理核心资产:

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

burnAgent() 只烧核心资产( 不关闭链条) AgentAccount (原始内容存档于2018-10-21). PDA.

海豹突击队的帮助方法和实例见以下文件: docs/METHODS.md#seal-v1-methods。 。 。 . 完整的 ATOM + 合法行距读取指南在 docs/ATOM.md。 。 。 .

RPC 供应商建议

选定集群的默认 Solana RPC 用于基本操作。 打开 devnet,公共RPC是有限的 生产 或者说 高级查询 (get AllAgents, get Agents ByOwner),使用自定义的RPC.

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

实例

索引器

SDK使用索引器进行搜索,收集读取,相继取出ID,并大读取. 默认后端是 图QL v2。 。 。 .

const indexed = await sdk.getAgentByAgentId(42);

已建公共终点 :

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

自我接待:

• 8004-索拉纳指数器

如果您升级了带有持续 DB 的自托管索引器, 请在重新启动前应用待定 DB 迁移 .

文档

• API 参考 - 所有有实例的方法
• 反馈指南 - 标记、值/小数、高级图案
• 证明文件示例 - 通用请求器驱动的经核实的反馈流量
• 证明 Pass + x402 示例 - 压缩x402兼容流量
• 收藏指南 - 收集指针和母协会规则
• 快速启动 - 逐步指南
• 费用 - 交易费用
• OASF 分类学 - 技能域参考
• AI 特工技能 - AI剂的SDK参考(MCP/LLM)

社区与支持

• 电报数字 : t.me/sol8004 (中文(简体) )
• X (转动)数字 : x.com/ Quantu AI (中文(简体) )
• 8004 标准数字 : eips.ethereum.org/EIPS/eip-8004 (英语)

许可证

麻省理工学院