跳到主要内容

接入 Provenance API

机器 API 用于来源要求、认可根、证明交付和私有确认跟踪;Explorer REST 用于公开展示与检索。接受任何来源声明前,都需要建立信任配置。

准备连接​

下列 shell 示例需要 Bash 或 zsh、curl 和 jq。从运营者已认证的部署信息取得服务 origin 和 chain ID。运行命令会访问该部署;文档不假定托管端点或链。将 PROVENANCE_ORIGIN 设为无尾部斜杠的 HTTPS origin,CHAIN_ID 设为规范正十进制链 ID。

: "${PROVENANCE_ORIGIN:?Set the authenticated Provenance HTTPS origin}"
: "${CHAIN_ID:?Set the configured decimal chain ID}"
PROVENANCE_RPC="${PROVENANCE_ORIGIN}/v1/chains/${CHAIN_ID}"
curl --fail-with-body --silent --show-error "${PROVENANCE_ORIGIN}/v1"

发现接口返回 apiVersion 与 chains 数组,各项包含 chainId、protocolVersion 和 rpcPath。已配置不代表健康或认可。这套 API 每个 chain 路由配置一个 Protocol;将每次响应的 scope.protocolAddress 与预期部署核对。

读取兼容性、规则与状态​

每次请求是一个带 ID 的 JSON-RPC 2.0 对象。参数是位置数组,params: [{}] 表示一个空查询对象。下面是三个独立调用,不是 batch:

for rpc_method in provenance_getVersion provenance_getRules provenance_getStatus; do
jq -n --arg method "$rpc_method" \
'{jsonrpc:"2.0",id:1,method:$method,params:[{}]}' |
curl --fail-with-body --silent --show-error "$PROVENANCE_RPC" \
-H 'Content-Type: application/json' --data-binary @-
done

getVersion 返回 apiVersion: "v1"、protocolVersion: "1"、证明格式与公开输入数量。serviceVersion 是线协议标识,不是二进制发布版本。getRules 返回单套规则、必需来源和签名历史,没有调用者选择策略的参数。getStatus 包含 generation、已发布 checkpoint 进度与 worker 可用性;只有发布后才返回根。

external 规则下,来源声明包含 adapter、capability、authentication、coverage 和最大年龄。coverage 和适用的 rejectFlags 是经过 JSON 编码的数组字符串。getStatus.sources 是当前进程观察到的来源状态,各副本可能不同;来源健康指标不能替代逐操作资金判断。

查询普通 Note​

将 NOTE_COMMITMENT 设为真实的公开普通 Note commitment:非零规范 BN254 标量域元素,编码为 0x 加 64 位 hex。不能用 seed、opening 或碰巧同长度的秘密代替。

: "${NOTE_COMMITMENT:?Set the public ordinary Note commitment}"
jq -n --arg commitment "$NOTE_COMMITMENT" \
'{jsonrpc:"2.0",id:2,method:"provenance_getNoteRecognition",
params:[{commitment:$commitment}]}' |
curl --fail-with-body --silent --show-error "$PROVENANCE_RPC" \
-H 'Content-Type: application/json' --data-binary @-

无记录时返回 found: false 和 recognitionState: "not_found"。找到记录也可能仍在等待;已认可响应包含 Note 与根证书。应认证证书及其链上下文,不能将认可查询当作所有权或已花费状态查询。

已知交易可调用 provenance_getTransactionRecognition,参数为 {txHash, limit},按返回的不透明 cursor 继续。精确查询一个操作时使用 provenance_getOperationRecognition,参数为 blockHash、txHash、十进制字符串 operationIndex。hash 必须是完整 32 字节 hex。索引尚未完成可能返回 INDEX_PENDING,不能显示为来源拒绝或空历史。

查询根并在本地构建成员路径​

jq -n '{jsonrpc:"2.0",id:3,method:"provenance_getRoots",
params:[{limit:50}]}' |
curl --fail-with-body --silent --show-error "$PROVENANCE_RPC" \
-H 'Content-Type: application/json' --data-binary @-

getRoots 返回证书 items、发布快照与分页字段。机器接口 rootId 为 generation:sequence,受 chain 路由与签发者隔离,与 Explorer 的带作用域 root ID 不同。使用 provenance_getRoot 和 {rootId} 读取具体根;其 allowedForNewProof 还检查 primary-chain 锚点。仅看根列表上的标志不足以接受某张证书。

使用 provenance_getLeaves 和 {rootId, fromIndex:"0", limit:200} 读取叶子,按返回的 nextIndex 继续直到达到证书中的 leaf count,同时核对进度并本地重建根。每页固定在同一证书。也可调用 provenance_getMembership,参数为 {rootId, commitment},但这会向服务暴露你对该 commitment 的关注。同步公开叶子后本地构建路径可避免花费时逐输入查询。

getRoots 的 cursor 模式不能同时带 after、generation 或 treeId。保持筛选和快照上下文一致;筛选后空页也可能仍有下一页。generation 变化后需要刷新。认可树位置独立于 Core Note Tree 位置。

传输与错误处理​

约定接入要求
请求体包含 JSON、hex 和证书在内最多 256 KiB;proof bytes 解码后另限 64 KiB
Envelope只允许 jsonrpc、id、method、params;非 null 字符串或整数 ID;不接受 batch 或 notification
查询单个方法专用对象;不接受未知字段、重复键、通用策略选择器或 URL query string
整数chain ID、高度、generation、金额、索引、时间戳均为十进制字符串;limit 可为整数 JSON 数值或十进制字符串,范围 1–200
浏览器同源或运营者精确配置的 CORS origin;无通配或内置 credential CORS
鉴权无内置 Bearer 鉴权机制;遵循部署方边缘访问要求

先检查 HTTP 状态,再检查 JSON-RPC envelope。curl --fail-with-body 能发现 HTTP 错误,不能发现 HTTP 200 中的 JSON-RPC error。即使成功解码 result,也可能包含 broadcastDecision: "deny" 或 "unavailable"。

例如下列响应即使 HTTP 为 200,仍是错误:

{"jsonrpc":"2.0","id":3,"error":{"code":-32025,"message":"Recognition root is unknown","data":{"code":"ROOT_UNKNOWN"}}}

对 INDEX_PENDING、FINALITY_PENDING、WORKER_UNAVAILABLE 与来源故障采取有界重试并刷新状态,遵循可用的 Retry-After 和 error.data.retryAfter。默认每进程按直连 peer IP 限制每分钟 120 次读取、12 次证明/评估;边缘策略可更严格。scope/manifest 不匹配、证明无效、generation 变化和幂等冲突需要修正上下文或证据。错误数值属于此服务,不能套用其他服务的映射。

Explorer 公开数据​

/api/v1 下 Explorer 路由直接返回 JSON 对象,不使用 JSON-RPC envelope。GET /api/v1/notes/{commitment} 提供公开 Note 数据;交易详情为 /api/v1/transactions/{txHash}。集合支持规定的 scope 筛选和不透明分页,默认每页 20 项、最多 200 项;全局结果保留链与 Protocol 出处。

检索只支持 POST /api/v1/search 与 {query: publicIdentifier},不要把检索词放进 URL。可以检索公开地址和 hash;任意 32 字节秘密无法可靠区别于公开 hash。Explorer 不暴露私有 tracking 任务、不证明余额、不关联 nullifier 与被花费 Note,也不解密普通私密输出。