RPC 确认与故障恢复
确认必须分别回答三个问题:输出是否已进入本地索引、交易执行是否成功、所在规范区块达到何种原生确认等级。
原生最终性与索引进度
invisi_getStatus 返回 indexedHead 和 finality.latest/safe/finalized。每个原生头都有 status 和 block;status 是 available、unsupported、unavailable 或 inconsistent。
unsupported:上游明确不支持方法或标签。unavailable:暂时无法取得有效头,包括网络错误或 null。inconsistent:链头或已接受的最终历史冲突。available:当前可用的原生头,停滞时高度可以不变。
服务不会把固定区块深度或等待时间换算成 safe/finalized。原生头可能领先索引;缺少最终性能力也不等于所有读取都不可用。应用按业务要求比较交易区块与所需头,不以索引高度替代。
请求受信 Note 确认
以下只读示例需要 POSIX shell、curl 和 jq。设置 PROTOCOL_RPC_URL 为完整可信链路由,NOTE_COMMITMENT 为来自本地收款材料重算的完整、非零、规范 BN254 标量承诺。jq 负责安全构造 JSON。
: "${PROTOCOL_RPC_URL:?Set the full trusted chain RPC URL}"
: "${NOTE_COMMITMENT:?Set the full expected Note commitment}"
jq -n --arg commitment "$NOTE_COMMITMENT" \
'{jsonrpc:"2.0",id:"note-1",method:"invisi_getNote",params:[$commitment,{finality:"finalized"}]}' |
curl --fail-with-body -sS "$PROTOCOL_RPC_URL" \
-H 'Content-Type: application/json' --data-binary @-
仅接受 safe 或 finalized;latest、null 和未知 selector 字段均拒绝。成功的确认响应包含版本、部署、indexedHead、status、reason、output、membership 和 confirmation。
status:"confirmed" 时 reason 为 null,confirmation 包含 finality、verifiedAt 和 finalityHead。验证锚点取索引头和原生最终性头中较低者;服务验证成功回执、规范区块、路径和该锚点的合约根,再重新核验规范性与最终性。
status:"pending" 时 output、membership、confirmation 都为 null。不能将这些 null 保存为永久不存在。
| reason | 应用处理 |
|---|---|
not_observed | 未观察到,保留订单并继续核对预期承诺 |
pending_index | 等待索引赶上 |
confirmation_pending | 等待所需原生层级 |
finality_unsupported | 换用具备能力的可信来源或明确调整业务政策 |
finality_unavailable | 暂停确认,有限退避重试 |
finality_inconsistent | 停止自动核销,核查可信链来源 |
RPC 错误不是 pending,也不能被转换为 confirmed。服务确认不包含商户订单、私密 opening 或本地一次核销状态;应用仍需自行原子记录收款与履约。
单笔交易可用性
invisi_getTransactionNoteUpdates 和 Credit 对应方法返回 status、indexedHead,以及可选区块和 receiptStatus。
| status | 含义 |
|---|---|
not_found | 未取得已挖出回执;可能未知或仍 pending |
pending_index | 已有规范回执,本地规范索引尚未就绪 |
indexed | 可读取该交易的已索引投影 |
索引完成前 notes / states / transitions 为 null;完成后是数组,包括空数组。receiptStatus 0 表示回滚,1 表示执行成功,与索引可用性独立。无关或回滚交易可返回空数组。结算操作查询的 operations 始终初始化为空数组,且使用独立 failed 状态,不要套用同一 null 契约。
错误与重试
先检查 HTTP,再检查 JSON-RPC。HTTP 429 尊重 Retry-After,使用有限指数退避与抖动。HTTP 413 缩小请求;415 修正 Content-Type;404 核对路由与活动链。后端默认没有 CORS/认证,浏览器接入需确认运营者网关策略。
JSON-RPC -32601 表示未知方法,-32602 表示参数解码失败,-32000 表示语义、存储或上游拒绝;公开错误会净化,不能按后台错误文本分类。不要无限重试错误参数。
单体请求上限 1 MiB,批次最多 20 调用,批次响应预算 16 MiB。批响应按 id 匹配,不能依赖顺序。需要确认时使用带 id 的请求;通知没有响应。发生重组时重新获取可信锚点、回滚本地孤块投影,再继续同步。