协议术语与状态边界
本页解释协议文档中反复使用的概念。InvisiPay 托管 商户接口的对应业务概念见商业支付术语;名称相似不表示资源和认证可以互换。
Core 实例与 SDK 类型
Core 实例是某条链上部署的具体合约及其独立资金、树、授权和管理状态。选择实例时固定 chain ID、合约地址、运行时代码身份与部署起点;相同 token 在两个实例中的 Note 不能混为一份库存。
SDK 使用名为 Protocol 的类型表示这个部署上下文。Protocol、protocolAddress、protocol 等代码标识保持原名;文档中的“Core 实例地址”对应这些 API 中的合约地址,并非另一个合约。
Core 接入说明操作;版本与兼容性说明 ABI、SDK、证明资源和服务版本的选择。
Note 与 Credit
| 术语 | 含义 | 不能据此推断什么 |
|---|---|---|
| Note | 已结算资金的私密凭证;金额、资产、收款身份和恢复材料形成其私密原像,链上保存承诺 | 知道承诺或成员路径不等于有花费权,也不证明尚未消费 |
| Credit | 从 owner 钱包未来扣款的授权;私密状态记录条款、有效期和用量 | 额度不是已存入或已锁定余额,不保证 owner 的余额或 allowance 充足 |
| commitment | 对 Note 或 Credit 状态的密码学承诺 | 相同线格式不代表两种凭证可混用 |
| nullifier | 消费旧状态时公开的防重复消费标记 | Credit 状态未消费不代表原始授信未撤销 |
| membership | 某承诺属于一个被接受根的成员证明 | 历史成员关系不替代当前消费、撤销和本地预留核对 |
| opening | 重算承诺和恢复私密状态所需的原像材料 | 完整 Note 查看材料可能允许全额归集到原 owner,并非纯只读权限 |
Note 资金流与Credit 授信分别说明资金和权限。金额在 SDK、Core 与原生 IPP 中使用 token 最小单位;InvisiPay 托管 API 使用币种单位的十进制字符串。
参与者与权限
| 角色 | 在协议中的含义 |
|---|---|
| owner | Note 的所有者,或 Credit 的授信人;自由花费/授信管理使用对应授权 |
| spender | Credit 中被授权发起扣款的一方;不是任意 EVM 交易发送者 |
| payer | 公开 ERC-20 资金的实际提供者;可能是入金方或 draw 中的 owner |
| recipient | 接收输出 Note 或公开提现的一方;可以不同于 Credit spender |
| submitter | 签署并广播 EVM 交易、支付原生币 gas 的账户;可由 Broadcaster 担任 |
| quoteSigner | 客户端信任的 Broadcaster 报价签名者;报价不替代 owner 或 payer 的业务授权 |
| Provenance provider / issuer | Provenance 来源认可的签发者;与外部风险数据供应者、链 RPC 运营者是不同角色 |
同一人可能承担多个角色,但签名、余额、allowance 和信息访问权限仍须分别核对。详见安全与信任。
三类完成状态
| 状态范围 | 表示什么 | 仍需做什么 |
|---|---|---|
链上 included | 交易进入规范区块,回执可判断执行成功或回滚 | 按业务要求继续验证原生 safe 或 finalized |
链上 safe / finalized | 节点支持的原生确认边界已覆盖交易区块 | 核对规范区块身份及来源;不以等待秒数或固定区块深度替代 |
| 钱包 reconciliation | 原操作与规范回执、消费、输出和本地库存完成对账 | 独立观察所需确认等级;未知结果保留输入预留 |
| IPP redemption(核销) | Facilitator 在固定要求和截止时间内验证证据,并原子记录一次成功 receipt | 商户认证查询、绑定原订单并自行保证业务幂等履约 |
Broadcaster 的 confirmed / reverted 表示回执执行成功/回滚,不等于原生 finalized。getConfirmation() 观察确认,不自动释放钱包预留。HTTP 200、提交受理或 receipt JSON 被客户端复制,也不意味着商户应发货。
Provenance 证明与认可
来源证明由付款人在本地生成,说明指定操作的输入满足受信签发者认可集合的成员条件。来源认可是服务在核验链上资金、所需来源判断和证明后发布的签发者声明,两者不是同一完成状态。
broadcastDecision=allow 是短期代发预检;证明作业 valid 表示验证通过。正式认可需观察精确操作的 recognized、已发布 checkpoint、当前 generation 与签名证书,并核对规范 finalized 锚点。认可不证明身份、法律合规、所有权或尚未花费。
参阅Provenance与证据流程。
原生 IPP 与托管 Checkout
原生 IPP 的 Checkout 是启动对象,提供 sessionUrl 和 checkoutUrl。PaymentSession 保存可选项、当前状态、固定 Request 和 receipt。钱包通过 Session Token 跟随 IPP links 读取及确认,实际支付由钱包/Core 授权执行。
InvisiPay 托管 Checkout 是商业支付 API的商户收款资源,使用其独立字段、Bearer API Key、状态与确认速度契约。即使部分路径同为 /v1/checkouts,也不能把两套请求、令牌、金额单位或成功判断混用。