Akashi Notari

Anchor Worker

通过 x402 向 Agent 出售锚定服务的 Cloudflare Worker。Agent 在一个 HTTP 请求中发送 SHA-256 文件哈希和已签名的 USDC 付款；Worker 会向 VerifierRegistryUSDC 发送一笔交易，由该合约收取 USDC 并写入证明。整个过程不涉及 facilitator。

API 端点

• POST /anchor → 付费。将哈希写入链上，并返回交易哈希和证书链接
• GET /proof?hash=<sha256 hex> → 免费。查询此哈希是否已锚定，以及它的首个证明
• GET /proof?tx=<transaction hash> → 免费。查询此交易写入的证明
• POST /mcp → MCP 服务（Streamable HTTP），提供 find_proof 和 anchor_hash 工具
• GET /openapi.json → OpenAPI 描述；x402scan 等目录会在注册 /anchor 前读取它
• GET /.well-known/x402 → x402 发现文档，列出 /anchor
• GET /.well-known/agent-registration.json → ERC-8004 Agent 注册文件
• GET /llms.txt → 面向大模型的服务描述
• GET / → 服务描述和当前价格
• GET /health → { ok: true }

POST /anchor

请求体：{ "hash": "<sha256, 64 hex chars>", "filename": "<optional>" }。支持 0x 前缀和大写字母；存储时会将哈希转换为小写且去掉 0x，与 Web 应用写入的格式相同。文件名遵循 Web 应用的规则：仅限小写 a-z 0-9 - _ .，最多 128 个字符。

如果没有 PAYMENT-SIGNATURE 标头，Worker 会以 402 响应，并在 PAYMENT-REQUIRED 标头中附上付款条款（x402 v2，base64 JSON），响应体中也会包含相同的 JSON：

{
  "x402Version": 2,
  "accepts": [
    {
      "scheme": "exact",
      "network": "eip155:8453",
      "amount": "10000",
      "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "payTo": "<VerifierRegistryUSDC>",
      "maxTimeoutSeconds": 120,
      "extra": { "assetTransferMethod": "eip3009", "name": "USD Coin", "version": "2" }
    }
  ]
}

金额从合约的 price() 读取，因此报价始终与合约一致。付款有效时，响应为 200，并包含 PAYMENT-RESPONSE 标头：

{
  "ok": true,
  "status": "confirmed",
  "hash": "be44340d151cbfa7a5dc59b579dd6632fb0891b573f8fdc927264309a3b168f0",
  "filename": "report.pdf",
  "submitter": "<payer address>",
  "timestamp": 1790919801,
  "timestampIso": "2026-10-02T05:43:21.000Z",
  "paid": "10000",
  "currency": "USDC",
  "chain": "base",
  "txHash": "0x...",
  "explorerUrl": "https://basescan.org/tx/0x...",
  "certificateUrl": "https://akashi-notari.com/certificate/?chain=base&hash=0x..."
}

任何 x402 客户端均可使用：

import { wrapFetchWithPaymentFromConfig } from '@x402/fetch';
import { ExactEvmScheme } from '@x402/evm';

const pay = wrapFetchWithPaymentFromConfig(fetch, {
  schemes: [{ network: 'eip155:8453', client: new ExactEvmScheme(account) }],
});
const res = await pay('https://<worker>/anchor', {
  method: 'POST',
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify({ hash, filename: 'report.pdf' }),
});

GET /proof

VerifierRegistryUSDC 会存储每个哈希的首次锚定，因此按哈希查询只需读取一次合约（firstAnchor），并查询其指定区块中的日志。无需搜索整条链，也无需区块浏览器 API 密钥。

{
  "hash": "be44340d…",
  "anchored": true,
  "proofs": [ { "hash": "…", "filename": "report.pdf", "submitter": "0x…", "timestamp": 1790919801, "txHash": "0x…", "contract": "0x…" } ],
  "searched": ["<VerifierRegistryUSDC>", "<VerifierRegistry>"]
}

• proofs 包含该哈希在 VerifierRegistryUSDC 上的首次锚定。同一哈希后续的锚定会作为事件存在，可通过 ?tx= 打开
• Web 应用写入的 ETH VerifierRegistry 不存储任何内容，因此其证明需要通过区块浏览器 API 查询。如果查询失败，合约会从 searched 转为 unsearched，其余结果仍然有效。anchored: false 且包含 unsearched 条目，表示“在可查询的位置未找到”

MCP

POST /mcp 通过 Streamable HTTP 提供 MCP 服务，不使用会话：每个请求都是独立的，GET 返回 405。

• find_proof { hash } 或 { tx }：免费，返回与 GET /proof 相同的结果
• anchor_hash { hash, filename? }：付费，使用 x402 MCP 传输方式。未付款时，结果为工具错误，其 structuredContent 是 x402 PaymentRequired 对象。客户端对其签名后，在 params._meta["x402/payment"] 中附上付款并再次调用；随后结果会包含证明，结算信息则位于 _meta["x402/payment-response"]

此文件夹中的 server.json 描述了 MCP 注册表所需的服务信息。

状态码

• 400 哈希、文件名或付款标头无效。此项检查在处理付款前进行，不会扣款
• 402 未付款，或无法结算付款。响应体中的 error 是 x402 错误代码，例如 insufficient_funds
• 409 payment_already_used：此授权已用于购买锚定。请通过 /proof 查询
• 503 Worker 未配置合约地址或 relayer 密钥

说明

• 交易要么转移 USDC 并发出证明，要么回滚且不转移任何资金
• 交易被挖出后，响应会包含 status: "confirmed" 和完整证明。如果 30 秒内没有 RPC 端点报告该交易，响应仍为 200，并包含 status: "submitted"、txHash 和 lookup URL。已广播的付款绝不会被报告为失败
• 链上的 submitter 是付款方，而不是中继者
• 如果某项授权已在代币合约上执行（由支付代理执行，或由抢先中继者的其他人执行），worker 会从代币日志中确认向合约的转账，并通过 anchorPaid 将其锚定。它会回溯 1,800 个区块
• 已取消的授权不会购买任何东西
• 官方 x402 客户端会拒绝超过 1 美元的付款，除非用户提高限额；将价格设为不高于 1 美元，Agent 无需配置即可付款
• 并发请求共用一个中继密钥。若 nonce 冲突，会重试三次；流量较大时需要使用队列
• 公共 RPC 节点和无需密钥的 Blockscout API 会拒绝或限制来自 Cloudflare 共享地址的请求。生产环境中，请将 RPC_URL 设置为一个带密钥的端点，并将其作为密钥保存。只有在 /proof?hash= 中包含 ETH 合约的证明时才需要 LOGS_API_KEY
• 恢复在代币合约上执行的授权时，会搜索代币日志中 1,800 个区块的记录，而免费的 Alchemy 密钥会拒绝此类请求（限制为 10 个区块）。在 RPC_URL 中列出第二个端点，或使用付费密钥，以确保此路径可用
• 每个 IP 每分钟最多允许 RATE_LIMIT_PER_MIN 个请求（默认为 60）

环境变量

• RELAYER_PRIVATE_KEY：密钥。用于发送交易的钱包。该钱包需要 ETH 支付 Gas，并需要在合约上调用 setRelayer(address, true)
• REGISTRY_ADDRESS：已部署的 VerifierRegistryUSDC
• CHAIN_ID：8453（Base，默认值）或 84532（Base Sepolia）。这两个链 ID 对以下所有项目都有内置默认值
• RPC_URL：一个或多个以逗号分隔的 RPC 端点，按顺序尝试。Base 的默认值是一组公共节点；生产环境流量请将带密钥的端点（Alchemy、Infura）设为密钥
• RPC_ORIGIN：作为 Origin 标头随 RPC 调用发送，供限制为允许来源列表的提供商密钥使用
• TOKEN_ADDRESS、TOKEN_NAME、TOKEN_VERSION、EXPLORER_URL：可选覆盖项。TOKEN_NAME 和 TOKEN_VERSION 是代币的 EIP-712 域
• LEGACY_REGISTRY_ADDRESS：ETH VerifierRegistry，会包含在查询结果中
• LOGS_API_URL、LOGS_API_KEY、LOGS_FROM_BLOCK：与 Blockscout 兼容的日志 API，用于搜索 ETH 合约中的 /proof?hash=，以及该 API 的可选密钥。将 LOGS_API_URL 设为空可改用 RPC 节点
• AGENT_REGISTRATIONS：用于 Agent 注册文件中 registrations 字段的 JSON 数组，例如 [{"agentId":22,"agentRegistry":"eip155:8453:0x…"}]；在 Agent 注册到 ERC-8004 身份注册表后设置
• PUBLIC_URL：worker 的公开来源，用于其公布的 resource.url
• CERTIFICATE_URL、CERTIFICATE_CHAIN：证书链接的目标位置
• RATE_LIMIT_PER_MIN：默认值为 60

本地开发

cd workers/anchor
pnpm install
cp dev.vars.template .dev.vars
pnpm dev

测试

端到端脚本会将模拟 USDC 和两个注册表部署到本地链上，然后手动通过官方 x402 客户端及 MCP 驱动 worker。

# terminal 1
cd contracts/registry && npx hardhat compile && npx hardhat node

# terminal 2
cd workers/anchor && pnpm test:e2e

部署

# 1. Deploy the contract and allow the relayer (try baseSepolia first)
cd contracts/registry
RELAYER_ADDRESS=0x... pnpm hardhat run scripts/deploy-usdc.js --network base

# 2. Put the address from constants-usdc.json into wrangler.toml as REGISTRY_ADDRESS

# 3. Set the relayer key and deploy
cd ../../workers/anchor
npx wrangler secret put RELAYER_PRIVATE_KEY
npx wrangler deploy

# 4. Send the relayer a little ETH on Base for gas

# 5. Rebuild and deploy the web app, so the certificate page reads the new contract