# 8004-solana 中文文档

规范地址：https://npmcn.com/package/8004-solana/

版本：0\.8\.5
npm 元数据更新时间：2026-09-10T19:11:47.299Z
中文译文更新时间：2026-11-08T01:16:23.027Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/8004-solana
原文对照：https://npmcn.com/package/8004-solana/?lang=original
项目主页：https://github.com/QuantuLabs/8004-solana-ts
源码仓库：https://github.com/QuantuLabs/8004-solana-ts

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：1.8 MB，226 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=20\.19\.0
- 运行依赖：6 个
- 首次发布：2025-12-11T18:41:59.666Z
- 最新版本发布：2026-09-10T19:11:47.119Z
- 近 30 天下载量：1941（2026-10-04 至 2026-11-02，npm 官方下载统计）
- 已发布版本数：31（近 12 个月 31 个）

## 中文简介

TypeScript SDK for 8004 on Solana - 代理身份、名声和ProofPass

## 安装

```sh
npm install 8004-solana
```

也可以使用：`pnpm add 8004-solana`、`yarn add 8004-solana`、`bun add 8004-solana`

## README

# 8004-索拉纳

[![npm](https://img.shields.io/npm/v/8004-solana)](https://www.npmjs.com/package/8004-solana) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![GitHub](https://img.shields.io/badge/GitHub-QuantuLabs%2F8004--solana--ts-blue)](https://github.com/QuantuLabs/8004-solana-ts)

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

> **自治代理人** (克劳博特,莫特博特等): 见 [`skill.md`](https://github.com/QuantuLabs/8004-solana-ts/blob/main/skill.md) 为自动AI剂消费设计的完整的SDK参考.
> 
> **新来的?** 跟着 [快速启动指南](https://github.com/QuantuLabs/8004-solana-ts/blob/main/docs/QUICKSTART.md) 5分钟后登记第一个探员.

## 特征

-   **收集请求人驱动的经核实的反馈** 与 [`ProofPass`](https://github.com/QuantuLabs/8004-solana-ts/blob/main/examples/proofpass.md)
-   **将代理注册为 NFT** 索拉纳区块链
-   **管理代理元数据** 和终点(MCP, A2A)
-   **提交和查询声誉反馈** 海豹突击队 v1 完整性验证
-   **签名验证( V)** 有代理操作钱包
-   **OASF 分类学** 支持(技能和域)

## 安装

```bash
npm install 8004-solana
```

## 网络默认

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

## 交易版本1为

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

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

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

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

## 快速启动

```typescript
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- 第一流)

```typescript
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`](https://github.com/QuantuLabs/8004-solana-ts/blob/main/docs/COLLECTION.md)。 。 。 .  
高级端到端使用如下所示: [`examples/collection-flow.ts`](https://github.com/QuantuLabs/8004-solana-ts/blob/main/examples/collection-flow.ts)。 。 。 .

### Web3 钱包( Phantom, Solflare)

```typescript
// 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)

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

### 生活检查

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

### 仅读模式

```typescript
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`。 。 。 . 不仅仅是任何服务钱包, 也不是转移后的当前现场所有者 .

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

参见公众实例:

-   [证明文件示例](https://github.com/QuantuLabs/8004-solana-ts/blob/main/examples/proofpass.md)
-   [证明 Pass + x402 示例](https://github.com/QuantuLabs/8004-solana-ts/blob/main/examples/proofpass-x402.md)

## 反馈系统

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

```typescript
// 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`。 。 。 .

```typescript
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)](https://github.com/QuantuLabs/8004-solana-ts/blob/main/docs/FEEDBACK.md) 所有8004标记和图案. 见 [独立文件和海豹突击队核查](https://github.com/QuantuLabs/8004-solana-ts/blob/main/docs/FEEDBACK.md#independent-file-and-seal-verification) 完全重放和原字节检查.

## 标记

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

```typescript
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)](https://github.com/QuantuLabs/8004-solana-ts/blob/main/docs/FEEDBACK.md) 用于完整的标签引用.

## ATOM 引擎

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

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

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

或者在登记后允许:

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

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

合法行读取路径 :

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

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

永久去除代理核心资产:

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

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

海豹突击队的帮助方法和实例见以下文件: [`docs/METHODS.md#seal-v1-methods`](https://github.com/QuantuLabs/8004-solana-ts/blob/main/docs/METHODS.md#seal-v1-methods)。 。 。 . 完整的 ATOM + 合法行距读取指南在 [`docs/ATOM.md`](https://github.com/QuantuLabs/8004-solana-ts/blob/main/docs/ATOM.md)。 。 。 .

## RPC 供应商建议

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

| 提供者 | 自由等级 | 注册 |
| --- | --- | --- |
| **赫利乌斯** | 100雷克/月 | [赫利乌斯.德夫](https://helius.dev/) |
| **快速节点** | 10M信贷/月 | [(原始内容存档于2018-10-21). squicknode.com](https://quicknode.com/) |
| **炼金术** | 每月300百万库吉 | [炼金术.com](https://alchemy.com/) |

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

## 实例

| 示例 | 说明 |
| --- | --- |
| [`quick-start.ts`](https://github.com/QuantuLabs/8004-solana-ts/blob/main/examples/quick-start.ts) | 基本读取/写入IPFS上传 |
| [`collection-flow.ts`](https://github.com/QuantuLabs/8004-solana-ts/blob/main/examples/collection-flow.ts) | 完整收集元数据+创建20个相关代理资产 |
| [`feedback-usage.ts`](https://github.com/QuantuLabs/8004-solana-ts/blob/main/examples/feedback-usage.ts) | 提交和阅读反馈 |
| [`agent-update.ts`](https://github.com/QuantuLabs/8004-solana-ts/blob/main/examples/agent-update.ts) | 链上元数据 & URI 更新 |
| [`transfer-agent.ts`](https://github.com/QuantuLabs/8004-solana-ts/blob/main/examples/transfer-agent.ts) | 转让代理所有权(也可通过标准符号钱包转让) |
| [`server-mode.ts`](https://github.com/QuantuLabs/8004-solana-ts/blob/main/examples/server-mode.ts) | 带有跳过Send的服务器/客户端架构 |
| [`proofpass.md`](https://github.com/QuantuLabs/8004-solana-ts/blob/main/examples/proofpass.md) | 通用请求器驱动的 ProofPass 流量 |
| [`proofpass-x402.md`](https://github.com/QuantuLabs/8004-solana-ts/blob/main/examples/proofpass-x402.md) | 压缩 x402-相容性 ProfPass 流量 |

### 索引器

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

```typescript
const indexed = await sdk.getAgentByAgentId(42);
```

已建公共终点 :

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

自我接待:

-   [8004-索拉纳指数器](https://github.com/QuantuLabs/8004-solana-indexer)

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

## 文档

-   [API 参考](https://github.com/QuantuLabs/8004-solana-ts/blob/main/docs/METHODS.md) - 所有有实例的方法
-   [反馈指南](https://github.com/QuantuLabs/8004-solana-ts/blob/main/docs/FEEDBACK.md) - 标记、值/小数、高级图案
-   [证明文件示例](https://github.com/QuantuLabs/8004-solana-ts/blob/main/examples/proofpass.md) - 通用请求器驱动的经核实的反馈流量
-   [证明 Pass + x402 示例](https://github.com/QuantuLabs/8004-solana-ts/blob/main/examples/proofpass-x402.md) - 压缩x402兼容流量
-   [收藏指南](https://github.com/QuantuLabs/8004-solana-ts/blob/main/docs/COLLECTION.md) - 收集指针和母协会规则
-   [快速启动](https://github.com/QuantuLabs/8004-solana-ts/blob/main/docs/QUICKSTART.md) - 逐步指南
-   [费用](https://github.com/QuantuLabs/8004-solana-ts/blob/main/docs/COSTS.md) - 交易费用
-   [OASF 分类学](https://github.com/QuantuLabs/8004-solana-ts/blob/main/docs/OASF.md) - 技能域参考
-   [AI 特工技能](https://github.com/QuantuLabs/8004-solana-ts/blob/main/skill.md) - AI剂的SDK参考(MCP/LLM)

## 社区与支持

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

## 许可证

麻省理工学院

## 常见问题

### 8004-solana 是什么？

TypeScript SDK for 8004 on Solana - 代理身份、名声和ProofPass

### 如何安装 8004-solana？

在项目目录运行 npm install 8004-solana，或使用 pnpm add / yarn add / bun add。

### 8004-solana 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### 8004-solana 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### 8004-solana 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20\.19\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### 8004-solana 可以商用吗？

8004-solana 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### 8004-solana 的下载量有多少？

根据 npm 官方下载统计，8004-solana 在 2026/10/04 – 2026/11/02 这 30 天内被下载 1,941 次，日均约 65 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### 8004-solana 还在维护吗？

最新版本 0\.8\.5 发布于 2026/09/11（1 个月前）；至今共发布 31 个版本，其中过去 12 个月发布了 31 个；首次发布于 2025/12/12。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。