Averray

Polkadot Agent 平台

此仓库包含一个从零开始构建、以 Agent 为先的金库与任务运行时：

• 用于账户、托管、策略、策略注册表和声誉的 Foundry 合约
• 通过 HTTP 和目录安全的 MCP 发现机制提供的共享服务层
• 为后续托管部署搭建的发现与索引框架

发布准备与信任文档：

• 生产就绪检查清单
• 威胁模型
• 无代币声明
• 第 12 周引导门槛
• 产品验证门槛
• 仲裁迁移
• 争议原因代码注册表
• 服务代币运营者手册

mcp-server 工作区目前使用 JavaScript 运行时源代码树，无需维护并行的 TypeScript 构建步骤。

开发环境设置

克隆后，请安装一次 git 钩子，以便扫描暂存提交中意外暂存的 .env 文件和类似私钥的字符串：

./scripts/install-hooks.sh

在本地运行完整测试矩阵：

npm test               # backend + frontend + forge
npm run typecheck:indexer

CI 会在每次推送到 main 以及每个 PR 时，通过 .github/workflows/ci.yml运行相同的四项任务。

多 Agent 分支启动

任何 Agent 开始新工作之前，都必须通过受保护的辅助工具创建其分支：

./scripts/ops/start-agent-branch.sh codex/your-task-name

该工具会获取 origin，将本地 main 切换到最新的 origin/main，仅执行快进更新，然后创建新分支。这样可确保每个 Agent 都不会基于过期的本地 main 开始工作。

本地部署流程

1. 启动本地 Anvil 链：

./scripts/start_anvil.sh

2. 在另一个终端中，部署并配置合约套件：

./scripts/deploy_contracts.sh

3. 导出部署脚本返回的地址，并写入服务环境文件：

export AGENT_ACCOUNT_ADDRESS=0x...
export ESCROW_CORE_ADDRESS=0x...
export REPUTATION_SBT_ADDRESS=0x...
export DISCOVERY_REGISTRY_ADDRESS=0x...
export TREASURY_POLICY_ADDRESS=0x...
export MOCK_DOT_ADDRESS=0x...
./scripts/write_server_env.sh

4. 启动服务：

cd mcp-server
set -a
source .env.local
set +a
npm run start:http

只要环境文件包含有效的 RPC URL、签名者密钥和已部署的合约地址，HTTP 适配器就会使用实时链上读取和签名写入。

实时 API 现在还通过应用代理公开仅推送的 SSE 流：/events，代理路径为 /api/events。

如果需要持久化会话和验证器结果，还需设置：

REDIS_URL=redis://...
REDIS_NAMESPACE=agent-platform

如果未设置 REDIS_URL，服务将在本地开发时回退到内存状态。

Pimlico / ERC-4337 Gas 赞助

设置以下环境变量后，托管 API 现在可提供由 Pimlico 支持的精简 Gas 赞助接口：

PIMLICO_BUNDLER_URL=https://...
PIMLICO_PAYMASTER_URL=https://...
PIMLICO_ENTRY_POINT=0x...
PIMLICO_SPONSORSHIP_POLICY_ID=...
PIMLICO_CHAIN_ID=...

配置完成后，HTTP 服务器会公开以下接口：

• GET /gas/health
• GET /gas/capabilities
• POST /gas/quote
• POST /gas/sponsor

这些端点用于 ERC-4337 用户操作的报价和赞助。目前它们尚不能替代直接签名者流程；它们新增了托管式 Gas 管理路径，使平台能够逐步转向智能账户执行。

要验证 Redis 支持的可恢复性是否能跨不同运行时生效：

cd mcp-server
set -a
source .env.local
export REDIS_URL=redis://...
set +a
npm run check:redis

该检查会在一个运行时中创建会话并进行验证，然后通过第二个运行时加载相同的会话和结果，以证明数据已持久化。

端到端本地演示

在 Anvil 运行且已填好 mcp-server/.env.local 的情况下，运行：

cd mcp-server
set -a
source .env.local
set +a
npm run demo:e2e

该演示会铸造模拟 DOT，将其存入 AgentAccountCore，创建一项已注资的任务，将其认领为工作者，提交工作，通过验证者角色结算托管款项，并检查款项支付和 SBT 铸造是否已完成。

端到端远程演示

要针对类生产 API 运行真实的托管栈冒烟测试：

cd mcp-server
REMOTE_E2E_BASE_URL=https://api.averray.com \
REMOTE_E2E_PRIVATE_KEY=0xyour-test-agent-private-key \
npm run demo:e2e:remote

设置 REMOTE_E2E_PRIVATE_KEY 后，脚本会运行完整的 SIWE 登录流程 — POST /auth/nonce → personal_sign → POST /auth/verify — 并在每次受保护的调用中使用返回的 JWT。对于 AUTH_MODE=permissive 部署，也可以只提供 REMOTE_E2E_WALLET，跳过签名。

该脚本会：

• 检查实时 API 健康状况
• 使用 SIWE 登录（提供私钥时）
• 通过 /admin/jobs 创建唯一的远程任务
• 领取任务
• 提交工作
• 运行验证
• 确认会话出现在托管历史记录中

身份验证

受保护的路由需要通过 Sign-In with Ethereum（EIP-4361）签发的已登录 JWT。流程如下：

POST /auth/nonce   { wallet }              → { nonce, message }
personal_sign(message) via wallet provider → signature
POST /auth/verify  { message, signature }  → { token, wallet, expiresAt }
POST /auth/logout  (Authorization header)  → revokes the token's jti

后续请求通过 Authorization: Bearer <token> 传递令牌。对于 SSE 端点（/events），令牌通过 ?token=... 传递，因为浏览器的 EventSource API 无法设置自定义标头 — 这是唯一的例外；如果在任何非 SSE 路由上通过查询字符串提供令牌，服务器都会记录警告。

外部 Agent 应从 GET /onboarding 开始。该接口现在会提供：

• onboarding.walletModes — 目前支持 evm-siwe；原生 Substrate 账户模式已标记为计划支持或取决于映射。每种受支持模式的 chain 区块均根据部署的当前网络生成 — Polkadot Hub 主网（chainId 420420419，DOT，无水龙头）或关闭测试版的 Polkadot Hub TestNet 栈（chainId 420420417，PAS，由水龙头提供资金）— 因此应从实时响应中读取链配置，而不是将任一网络硬编码。
• onboarding.actionRequirements — 每项操作的身份验证提示，例如 requiredAction、authScheme、walletModes 和 requiredRole。
• onboarding.readinessChecks — 机器可读的钱包设置、资金、SIWE 会话和预检检查；Agent 在领取任务前应满足这些检查。
• auth.entrypoints — 标准的 nonce、verify 和 logout 端点。

首个 Agent 操作员指南请参阅 docs/AGENT_OPERATOR_ONBOARDING.md。钱包专属设置请参阅 docs/AGENT_WALLET_ONBOARDING.md。当前受保护的 HTTP 路径使用兼容 Ethereum 的 0x... 钱包和 SIWE。Talisman 用户目前应为此流程选择专用的 EVM 账户；onboarding 元数据将原生 Substrate 和映射账户模式标记为计划支持或取决于映射，而非不支持。

调用受保护路由时若未提供令牌，401 响应也会包含相同的机器可读后续步骤（requiredAction: "wallet_sign_in"、authScheme: "SIWE_JWT" 和 authEntrypoints）。受角色限制的路由还会添加 requiredRole。

登出时会将当前令牌的 jti 写入状态存储中的限时黑名单，从而撤销令牌。之后任何使用该令牌的请求都会返回 401 token_revoked。黑名单条目会在令牌自身的 exp 到期时自动过期，避免 Redis 无限增长。

公开路由（无需身份验证）：/、/health、/metrics、/agent-tools.json、/onboarding、/jobs、/jobs/definition、/jobs/tiers、/strategies、/session/state-machine、/schemas/jobs、/schemas/jobs/:name.json、/agents/:wallet、/badges/:sessionId、/gas/health、/gas/capabilities、/verifier/handlers、/auth/nonce、/auth/verify。

AUTH_MODE=strict（生产默认值）会对受保护路由上的未验证请求返回 401。AUTH_MODE=permissive（开发默认值）会回退到旧版 ?wallet= 查询参数，并记录警告 — 这适用于尚未迁移所有调用方时的本地演示。

环境变量（参见 mcp-server/.env.example）：

• AUTH_MODE — strict | permissive
• AUTH_JWT_SECRETS — 以逗号分隔的 HS256 密钥。第一个条目用于签发新令牌；其余密钥在验证时仍受接受，以支持零停机轮换。每个密钥都必须至少有 32 个字符。
• AUTH_DOMAIN — SIWE domain 和预期的验证器检查。
• AUTH_CHAIN_ID — SIWE chainId 和预期的验证器检查。
• AUTH_TOKEN_TTL_SECONDS（默认值为 86400）— JWT 有效期。
• AUTH_NONCE_TTL_SECONDS（默认值为 300）— SIWE nonce 有效期。
• AUTH_ADMIN_WALLETS — 以逗号分隔的 EVM 地址，登录时会被授予 admin 角色声明。调用 POST /admin/jobs 必须具备此角色。
• AUTH_VERIFIER_WALLETS — 以逗号分隔的 EVM 地址，登录时会被授予 verifier 角色声明。调用 POST /verifier/run 必须具备此角色。

角色在登录时根据环境配置确定；用户通过 SIWE 登录后会获得角色声明，因此轮换环境变量列表会在用户下次登录时使权限失效，而不是在每次请求时失效。需要角色的受保护路由会检查 JWT 声明，不匹配时返回 403 missing_role。链上托管款项结算还会受到 TreasuryPolicy.verifiers 的限制；在当前的后端签名者架构中，配置的链签名者地址就是获授权的验证者地址。

外部 Agent 应从 docs/EXTERNAL_AGENT_WALLET_ONBOARDING.md 开始。 该指南说明哪些内容无需钱包即可查看、哪些需要钱包，以及浏览器监督式 Agent 或可自托管 Agent 应如何获取和使用专用 Agent 钱包，而不向模型暴露私钥（其中的示例以封闭 Beta 测试网技术栈为目标）。

密钥轮换：将新密钥添加到 AUTH_JWT_SECRETS 的首位，重新部署，然后在 AUTH_TOKEN_TTL_SECONDS 经过后移除旧密钥，确保所有使用旧密钥签发的令牌都已过期。

Builder SDK

一个小型 ESM 客户端位于 sdk/agent-platform-client.js。 它直接映射 HTTP 接口，并附带供编辑器使用的类型定义，位于 sdk/agent-platform-client.d.ts。

import { AgentPlatformClient } from "./sdk/agent-platform-client.js";

const client = new AgentPlatformClient({ baseUrl: "https://api.averray.com" });

const manifest = await client.getDiscoveryManifest();
const schemas = await client.listJobSchemas();
const lifecycle = await client.getSessionStateMachine();
const profile = await client.getAgentProfile("0xFd2EAE2043243fDdD2721C0b42aF1b8284Fd6519");

通过 SIWE 验证后，经过身份验证的流程会继续使用同一个客户端：

client.setToken(token);

const account = await client.getAccountSummary();
const recommendations = await client.getRecommendations();
const catalog = await client.listClaimableJobs({ limit: 100 });
const jobs = Array.isArray(catalog) ? catalog : catalog.jobs;
const selected = jobs.find((job) => (
  job.claimable === true && job.onboardingWaiverEligible === true
));
if (!selected) throw new Error("No waiver-eligible claimable onboarding job is available");
const draft = buildSubmissionFor(selected.outputSchemaRef);
const validation = await client.validateJobSubmission(selected.id, draft);
if (!validation.valid) throw new Error(validation.message);
const claim = await client.claimJob(selected.id, "onboarding-claim-001");

这些示例涵盖了外部 Agent 当前的主要使用路径：

• examples/profile-lookup
• examples/claim-and-submit-job
• examples/read-job-timeline

只读查询资料：

examples/profile-lookup：

npm run example:profile-lookup -- \
  --wallet 0xFd2EAE2043243fDdD2721C0b42aF1b8284Fd6519

在进行任何更改前试运行任务：

npm run example:claim-and-submit-job -- \
  --api https://api.averray.com

SIWE 登录后领取并提交一次：

AVERRAY_TOKEN="$TOKEN" npm run example:claim-and-submit-job -- \
  --idempotency-key onboarding-first-try \
  --submission-json "$SUBMISSION_JSON" \
  --execute

使用管理员令牌查看任务时间线：

AVERRAY_TOKEN="$ADMIN_TOKEN" npm run example:read-job-timeline -- \
  --job-id "$COMPLETED_JOB_ID"

Render 部署

仓库中包含一个入门级 Render 配置 render.yaml，简明部署检查清单位于 RENDER_DEPLOY.md。

仓库现在还包含一个 Ponder 索引器工作区：

• 本地开发：npm run dev:indexer
• 类型检查：npm run typecheck:indexer
• Render 检查清单：indexer/RENDER_DEPLOY.md

对于超低成本的托管测试，索引器还支持通过环境变量启用低内存模式。该模式会跳过托管款项索引，从 latest 开始处理新的托管和声誉事件，禁用缓存，仅用于验证在极小型实例上的可行性。

索引器会追踪 Polkadot Hub TestNet 事件，包括：

• TreasuryPolicy
• EscrowCore
• ReputationSBT
• AgentAccountCore
• DiscoveryRegistry

合约迁移说明

v1.0.0-rc1 中用于验证者权限、发现锚定、披露日志、哈希绑定回执事件、终局声誉扣罚和声明质押的骨干扩展，会改变不可变的合约存储和事件。应将现有已部署的合约实例视为已被取代，并使用更新后的部署脚本重新部署，然后再期待托管行为与此代码库一致。

这些信任面的威胁模型依据见 docs/THREAT_MODEL.md。

VPS 运维

当前的可自托管部署使用 OVH VPS，通过 Docker Compose 部署在 /srv/agent-stack 下。

运维辅助脚本现位于：

• scripts/ops/backup-postgres.sh
• scripts/ops/redeploy-backend.sh
• VPS_RUNBOOK.md

典型的类生产环境工作流：

cd /srv/agent-stack/app
./scripts/ops/backup-postgres.sh
./scripts/ops/redeploy-backend.sh