Fiber Commitment Lock 约束Fiber Commitment Lock Constraints

来源：nervosnetwork/fiber-scripts / contracts/commitment-lock/src/main.rs（HEAD e7e1c9ba）　·　协议：Daric　·　部署：nervosnetwork/fiber config/*/config.yml　·　mainnet 0x2d45…406c / testnet 0x740d…81d8 (type)Source: nervosnetwork/fiber-scripts / contracts/commitment-lock/src/main.rs (HEAD e7e1c9ba)　·　protocol: Daric　·　deployments: nervosnetwork/fiber config/*/config.yml　·　mainnet 0x2d45…406c / testnet 0x740d…81d8 (type)
Lock 脚本Lock script支付通道 / FiberPayment channel / Fiber主网Mainnet测试网Testnet开源Open sourceNervos 官方Nervos

A撤销（unlock_count = 0）：用更新的版本惩罚旧承诺Revocation (unlock_count = 0): punish an old commitment with a newer version

Inputs 输入Inputs
commitment cellCell{ lock: COMMITMENT_LOCK(args{version v}) }
➜
Outputs 输出Outputs
outputs[0]签名覆盖的新 cell（通常回到新承诺）new cell covered by the signature (usually back to the newer commitment)
args 字节布局（57 或 58 字节）args byte layout (57 or 58 bytes)
pubkey_hash20B
delay_epoch8B
version8B
settlement_hash20B
settlement_flag1B
feature?1B
  • pubkey_hash 20B　blake160(聚合公钥)，撤销路径用blake160(aggregated pubkey), for revocation　—— (23)
  • delay_epoch 8B　相对 epoch since（u64 LE）relative epoch since (u64 LE)　首次结算时延delay for first settlement (6)
  • version 8B　承诺版本（u64 大端）commitment version (u64 big-endian)　撤销需 ≥revocation needs ≥ (17)
  • settlement_hash 20B　blake160(settlement 脚本)blake160(settlement script)　= witness 哈希= witness hash (15)
  • settlement_flag 1B　0x00 首次 / 0x01 后续0x00 first / 0x01 subsequent　决定是否检查 sincedecides the since check (6)
  • feature? 1B　0x01 = 完整 32 字节 payment hash（v1）0x01 = full 32-byte payment hash (v1)　可选；长度 57 或 58optional; length 57 or 58 (12)
witness（撤销）witness (revocation)
empty_witness_args16B
unlock_count1B
version8B
pubkey32B
signature64B
  • empty_witness_args 16B　空 WitnessArgs 占位，兼容 xUDTempty WitnessArgs placeholder for xUDT compatibility　= 0x10000000…10000000= 0x10000000…10000000 (14)
  • unlock_count 1B　0x00 = 撤销0x00 = revocation　——
  • version 8B　新版本（大端）new version (big-endian)　≥ args.version≥ args.version (17)
  • pubkey 32B　x-only 聚合公钥x-only aggregated pubkey　—— (23)
  • signature 64B　Schnorr 聚合签名aggregated Schnorr signature　见下see below (23)

限制Constraints

  • version：: witness.version ≥ args.version（8 字节大端比较）witness.version ≥ args.version (8-byte big-endian comparison) (17)
  • signature：: Schnorr（算法 7）覆盖 blake2b(outputs[0] ‖ data_len u32 LE ‖ data ‖ args[0..28] ‖ new_version)（未检查）Schnorr (algorithm 7) over blake2b(outputs[0] ‖ data_len u32 LE ‖ data ‖ args[0..28] ‖ new_version) (not checked) (23)

B结算（unlock_count ≥ 1）：pending HTLC 与双方余额Settlement (unlock_count ≥ 1): pending HTLCs and party balances

Inputs 输入Inputs
commitment cellCell{ lock: COMMITMENT_LOCK(args), type: UDT?, capacity / UDT amount = A }
witness16B ‖ unlock_count ‖ settlement_script ‖ unlocks[]
➜
Outputs 输出Outputs
outputs[0]（余额 > 0 且双方未全部结算时）outputs[0] (when balance > 0 and not all parties settled)Cell{ lock: COMMITMENT_LOCK(args[0..36] ‖ blake160(new_settlement_script) ‖ 0x01 ‖ feature?), type: same UDT?, amount = A − settled }
settlement_script 布局settlement_script layout
pending_htlc_count1B
pending_htlc × NN × 85B / 97B
remote_pubkey_hash20B
remote_amount16B
local_pubkey_hash20B
local_amount16B
  • pending_htlc_count 1B　NN　——
  • pending_htlc × N N × 85B / 97B　见下see below　——
  • remote_pubkey_hash 20B　对方结算公钥哈希remote settlement pubkey hash　0xFE 签名者0xFE signer
  • remote_amount 16B　u128 LEu128 LE　——
  • local_pubkey_hash 20B　本方结算公钥哈希local settlement pubkey hash　0xFF 签名者0xFF signer
  • local_amount 16B　u128 LEu128 LE　——
pending_htlc 布局（旧版 85 字节；v1 97 字节）pending_htlc layout (85 bytes legacy; 97 bytes v1)
htlc_type1B
payment_amount16B
payment_hash20B / 32B
remote_htlc_pubkey_hash20B
local_htlc_pubkey_hash20B
htlc_expiry8B
  • htlc_type 1B　bit0：0 offered / 1 received；bit1：0 blake2b / 1 sha256bit0: 0 offered / 1 received; bit1: 0 blake2b / 1 sha256　——
  • payment_amount 16B　u128 LEu128 LE　从余额扣除deducted from the balance
  • payment_hash 20B / 32B　旧版 20 字节；v1 32 字节20 bytes legacy; 32 bytes v1　原像哈希前缀相等prefix of the preimage hash (22)
  • remote_htlc_pubkey_hash 20B　blake160(对方 HTLC 公钥)blake160(remote HTLC pubkey)　签名者signer
  • local_htlc_pubkey_hash 20B　blake160(本方 HTLC 公钥)blake160(local HTLC pubkey)　签名者signer
  • htlc_expiry 8B　绝对时间戳 sinceabsolute timestamp since　超时路径要求 since ≥timeout path needs since ≥ (11)
unlock 条目布局（按 HTLC 序号升序排列）unlock entry layout (ascending HTLC index)
unlock_type1B
with_preimage1B
signature65B
preimage?32B
  • unlock_type 1B　0x00–0xFD HTLC 序号；0xFE 对方；0xFF 本方0x00–0xFD HTLC index; 0xFE remote; 0xFF local　< N 或 0xFE/0xFF< N or 0xFE/0xFF (7)
  • with_preimage 1B　0 / 10 / 1　其它值报错other values fail (8)
  • signature 65B　secp256k1 可恢复签名recoverable secp256k1 signature　ckb-auth 算法 0ckb-auth algorithm 0 (23)
  • preimage? 32B　HTLC 原像HTLC preimage　哈希 = payment_hashhash = payment_hash (22)

限制Constraints

  • inputs：: group 只有 1 个输入exactly 1 group input (5)
  • args：: 长度 57，或 58 且 args[57] = 0x01length 57, or 58 with args[57] = 0x01 (12)
  • witness：: 长度 ≥ 1 + N×HTLC + 72；blake2b(settlement_script)[0..20] = args.settlement_hashlength ≥ 1 + N×HTLC + 72; blake2b(settlement_script)[0..20] = args.settlement_hash (13 / 15)
  • unlocks：: 至少一个；最多一个 0xFE/0xFF 条目at least one; at most one 0xFE/0xFF entry (9)
  • htlc preimage：: 交易无绝对时间戳 since 时：原像哈希前缀 = payment_hash；offered 由 remote 签，received 由 local 签；首次结算需相对 since ≥ delay×1/3no absolute timestamp since in the tx: preimage hash prefix = payment_hash; offered signed by remote, received by local; first settlement needs relative since ≥ delay×1/3 (22 / 6)
  • htlc timeout：: 存在绝对时间戳 since 时：since ≥ htlc_expiry；offered 由 local 签，received 由 remote 签；首次结算需 ≥ delay×2/3with an absolute timestamp since: since ≥ htlc_expiry; offered signed by local, received by remote; first settlement needs ≥ delay×2/3 (11 / 6)
  • party settlement：: 0xFE 领取对方余额、0xFF 领取本方余额，新脚本中该方置为 36 字节 0；首次结算需 since ≥ delay_epoch0xFE claims the remote balance and 0xFF the local one; that party becomes 36 zero bytes in the new script; first settlement needs since ≥ delay_epoch (6)
  • outputs[0]：: 余额 > 0 且未全部结算：lock 同脚本、args 为新 settlement_hash 且 flag = 0x01；CKB 通道 capacity = 余额且无 type；UDT 通道 type 相同、数量 = 余额（HTLC 结算时 capacity 不变）balance > 0 and not all settled: same lock, args with the new settlement_hash and flag 0x01; CKB channel capacity = balance with no type; UDT channel same type, amount = balance (capacity unchanged for HTLC settlement) (18 / 19 / 20 / 21)
  • signatures：: 每个结算项一个 secp256k1 签名，覆盖 blake2b(raw tx 去掉 cell_deps)（未检查）one secp256k1 signature per settled item over blake2b(raw tx without cell_deps) (not checked) (10 / 23)
部署与来源Deployments & source 未核验unverified
源码source nervosnetwork/fiber-scripts@e7e1c9ba · contracts/commitment-lock/src/main.rs (commit read when writing this spec)
二进制核验binary check 未核验unverified hash appears in the repo only as a deployment record or doc, which does not prove the recorded commit builds this binary (reproducible build not attempted)
0x7e35b1d77d…9de666df: listed in deployment/mainnet/migrations/2026-01-14-030304.json; listed in deployment/testnet/migrations/2025-11-25-060540.json
网络networkcode_hashcell_deptype_id args数据哈希data hash部署交易deploy tx
mainnet0x2d45c4d3ed3e942f1945386ee82a5d1b7e4bb16d7fe1ab015421174ab747406c type0x95006eee7b…c720b9d6:2 code0xdb16e6dcb1…6c26a39f0x7e35b1d77d…9de666df0x95006eee7b…c720b9d6 #18372567
testnet0x740dee83f87c6f309824d8fd3fbdd3c8380ee6fc9acc90b1a748438afcdf81d8 type0x12c569a258…79dd14a7:2 code0xf7e4588874…78d5751b0x7e35b1d77d…9de666df0x12c569a258…79dd14a7 #19249889
链上数据核对于 on-chain data checked 2026-10-20
错误码（main.rs Error，按枚举顺序）：1 IndexOutOfBound · 2 ItemMissing · 3 LengthNotEnough · 4 Encoding · 5 MultipleInputs · 6 InvalidSince · 7 InvalidUnlockType · 8 InvalidWithPreimageFlag · 9 InvalidSettlementCount · 10 InvalidUnlockCount · 11 InvalidExpiry · 12 ArgsLenError · 13 WitnessLenError · 14 EmptyWitnessArgsError · 15 WitnessHashError · 16 InvalidFundingTx · 17 InvalidRevocationVersion · 18 OutputCapacityError · 19 OutputLockError · 20 OutputTypeError · 21 OutputUdtAmountError · 22 PreimageError · 23 AuthErrorError codes (main.rs Error, enum order): 1 IndexOutOfBound · 2 ItemMissing · 3 LengthNotEnough · 4 Encoding · 5 MultipleInputs · 6 InvalidSince · 7 InvalidUnlockType · 8 InvalidWithPreimageFlag · 9 InvalidSettlementCount · 10 InvalidUnlockCount · 11 InvalidExpiry · 12 ArgsLenError · 13 WitnessLenError · 14 EmptyWitnessArgsError · 15 WitnessHashError · 16 InvalidFundingTx · 17 InvalidRevocationVersion · 18 OutputCapacityError · 19 OutputLockError · 20 OutputTypeError · 21 OutputUdtAmountError · 22 PreimageError · 23 AuthError
README 写的是旧的 85 字节 HTLC；源码另支持 58 字节 args（feature 0x01）与 97 字节 HTLC。链上还存在 36/56 字节 args 的早期版本 cell，本页不解析The README describes the older 85-byte HTLC; the source also supports 58-byte args (feature 0x01) and 97-byte HTLCs. Cells from earlier versions with 36/56-byte args exist on chain and are not decoded here
未核实：当前部署的二进制是否就是 HEAD 版本Unverified: whether the deployed binary is the HEAD version
GitHub · gpBlockchain/ckb-contract-flow-html