Skip to content

Commit c61d99a

Browse files
quakequake
authored
Merge pull request #22 from quake/quake/none-pending-unlock
settlement delay epoch fix and batch unlock
2 parents f4fcda6 + ea84410 commit c61d99a

File tree

14 files changed

+1202
-609
lines changed

14 files changed

+1202
-609
lines changed

‎Cargo.lock‎

Lines changed: 280 additions & 196 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎checksums.txt‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
80d0b47a9e4763ae70f478844c0b68f10fbaca8fe4f4a487708af26f1be9ebbc build/release/commitment-lock
2-
c83ac363f2b21cd46a49c0aa23bec6ca70a5e85a2f97f352b809c8d0e26800eb build/release/commitment-lock.debug
3-
a9fab24fdde52628ef5d9e6a492c2d0e85bbb4c8645cb70c0bc668b1935adb3a build/release/funding-lock
4-
c454bbe2febfe3dc05e84ae3ddbcd8ad2e1bf638a06f1adf1dfea4d8e2e62a7a build/release/funding-lock.debug
1+
43f698790b28c433607bc5a2a2b9cbe5ed86ed43a753d014c9a0670f9274ce8d build/release/commitment-lock
2+
41de10902949fd46cb07107068b57e32300fb3659311716c34f3392ca82d7fde build/release/commitment-lock.debug
3+
831f164aad1509db5483dd50c50bf4ed5cb6601f941600287ffdb5e79a29cf9e build/release/funding-lock
4+
291bdd4a48783ce75012a6e21935090806014d33bf6c52b1b2374e8feeaa91f0 build/release/funding-lock.debug

‎contracts/commitment-lock/Cargo.toml‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,13 @@
11
[package]
22
name = "commitment-lock"
33
version = "0.1.0"
4-
edition = "2021"
4+
edition = "2024"
55

66
[dependencies]
7-
ckb-std = "0.16"
8-
ckb-hash = { version = "0.119.0", default-features = false, features = ["ckb-contract"] }
7+
ckb-std = "0.18"
8+
ckb-hash = { version = "0.202.0", default-features = false, features = ["ckb-contract"] }
99
hex = { version = "0.4", default-features = false, features = ["alloc"]}
1010
sha2 = { version = "0.10", default-features = false }
1111

1212
[build-dependencies]
13-
ckb-gen-types = "0.119.0"
13+
ckb-gen-types = "0.202.0"

‎contracts/commitment-lock/README.md‎

Lines changed: 76 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -2,27 +2,25 @@
22

33
This is a commitment lock script for ckb fiber network, which implements [daric] protocol.
44

5+
## Lock Script Args and Witness Structure
56
The lock script args is concatenated by the following fields:
67

78
- `pubkey_hash`: 20 bytes, hash result of blake160(x only aggregated public key)
89
- `delay_epoch`: 8 bytes, u64 in little endian, must be a relative [EpochNumberWithFraction](https://github.com/nervosnetwork/ckb/blob/develop/rpc/README.md#type-epochnumberwithfraction)
910
- `version`: 8 bytes, u64 in big-endian
10-
- `htlcs`: 20 bytes, hash result of blake160(pending_htlc_count || N * pending_htlc), optional
11+
- `settlement_hash`: 20 bytes, hash result of blake160(pending_htlc_count || N * pending_htlc || settlement_remote_pubkey_hash || settlement_remote_amount || settlement_local_pubkey_hash || settlement_local_amount)
12+
- `settlement_flag`: 1 byte, 0x00 means this cell is created for first funding cell unlock, 0x01 means this cell is created for subsequent commitment cell unlock, others are reserved
1113

1214
To unlock this lock, the transaction must provide the following fields in the witness:
1315
- `empty_witness_args`: 16 bytes, fixed to 0x10000000100000001000000010000000, for compatibility with the xudt
14-
- `unlock_type`: 1 byte, 0x00 ~ 0xFD for pending HTLC unlock, 0xFE for non-pending HTLC unlock, 0xFF for revocation unlock
16+
- `unlock_count`: 1 byte, 0x00 for revocation unlock, 0x01 ~ 0xFF for settlement unlocks count.
1517

1618
For revocation unlock process, the transaction must provide the following fields in the witness:
1719
- `version`: 8 bytes, u64 in big-endian, must be the same or greater than the version in the lock args
1820
- `pubkey`: 32 bytes, x only aggregated public key
1921
- `signature`: 64 bytes, aggregated signature
2022

21-
For non-pending HTLC unlock process, the transaction must provide the following fields in the witness:
22-
- `pubkey`: 32 bytes, x only aggregated public key
23-
- `signature`: 64 bytes, aggregated signature
24-
25-
For pending HTLC unlock process, the transaction must provide the following fields in the witness:
23+
For settlement unlock process, the transaction must provide the following fields in the witness:
2624
- `pending_htlc_count`: 1 byte, the count of pending HTLCs
2725
- `pending_htlc`: A group of pending HTLCS, each HTLC is 85 bytes, contains:
2826
- `htlc_type`: 1 byte, high 7 bits for payment hash type (0000000 for blake2b, 0000001 for sha256), low 1 bit for offered or received type (0 for offered HTLC, 1 for received HTLC)
@@ -31,8 +29,77 @@ For pending HTLC unlock process, the transaction must provide the following fiel
3129
- `remote_htlc_pubkey_hash`: 20 bytes, hash result of blake160(remote_htlc_pubkey)
3230
- `local_htlc_pubkey_hash`: 20 bytes, hash result of blake160(local_htlc_pubkey)
3331
- `htlc_expiry`: 8 bytes, u64 in little endian, must be an absolute timestamp [since](https://github.com/nervosnetwork/rfcs/blob/master/rfcs/0017-tx-valid-since/0017-tx-valid-since.md)
34-
- `signature`: 65 bytes, the signature of the xxx_pubkey
35-
- `preimage`: 32 bytes, an optional field to provide the preimage of the payment_hash
32+
- `settlement_remote_pubkey_hash`: 20 bytes, hash result of blake160(pubkey)
33+
- `settlement_remote_amount`: 16 bytes, u128 in little endian
34+
- `settlement_local_pubkey_hash`: 20 bytes, hash result of blake160(pubkey)
35+
- `settlement_local_amount`: 16 bytes, u128 in little endian
36+
37+
- `unlocks`: A group of settlement unlock signature and preimage
38+
- `unlock_type`: 0x00 ~ 0xFD for pending htlc group index, 0xFE for settlement remote, 0xFF for settlement local.
39+
- `with_preimage`: 0x00 without preimage, 0x01 with preimage
40+
- `signature`: 65 bytes, the signature of the xxx_pubkey
41+
- `preimage`: 32 bytes, an optional field to provide the preimage of the payment_hash
42+
43+
## Settlement Unlock Process and New Lock Script Args Generation
44+
45+
During the settlement unlock process, when HTLCs are settled or parties claim their funds, a new output cell with updated lock script args is generated. The new lock script args follow the same structure but with updated `settlement_hash`:
46+
47+
### New Settlement Script Generation
48+
49+
The new settlement script is constructed by:
50+
51+
1. **Updated pending HTLCs**: Remove settled HTLCs from the original list
52+
- `new_pending_htlc_count`: Decremented count after settling HTLCs
53+
- Remaining unsettled HTLCs in the same 85-byte format
54+
55+
2. **Updated settlement amounts**: Adjust party amounts based on settlements
56+
- For remote settlement (unlock_type = 0xFE): Set settlement_local_amount to 0 and pubkey hash to 20 bytes zeros
57+
- For local settlement (unlock_type = 0xFF): Set settlement_remote_amount to 0 and pubkey hash to 20 bytes zeros
58+
- For HTLC settlements: Deduct payment amounts from total available funds
59+
60+
### New Lock Script Args Construction
61+
62+
The new lock script args are generated as:
63+
```
64+
new_args = [
65+
pubkey_hash, // Same as original (20 bytes)
66+
delay_epoch, // Same as original (8 bytes)
67+
version, // Same as original (8 bytes)
68+
new_settlement_hash // Updated hash (20 bytes)
69+
]
70+
```
71+
72+
Where `new_settlement_hash = blake2b_256(new_settlement_script)[0..20]`
73+
74+
### Examples from Tests
75+
76+
1. **Local Settlement**: When local party settles, their settlement amount becomes 0 and pubkey hash is updated to 20 bytes zeros:
77+
```rust
78+
new_settlement_script = [
79+
new_pending_htlc_count,
80+
remaining_htlcs...,
81+
remote_pubkey_hash,
82+
remaining_remote_amount.to_le_bytes(),
83+
[0u8; 20], // Local pubkey hash set to 20 bytes zeros
84+
0u128.to_le_bytes(), // Local amount set to 0
85+
]
86+
```
87+
88+
2. **HTLC Settlement**: When HTLCs are settled, they're removed from pending list:
89+
```rust
90+
new_settlement_script = [
91+
(original_count - settled_count),
92+
unsettled_htlcs...,
93+
settlement_party_data...
94+
]
95+
```
96+
97+
3. **Batch Settlement**: Multiple HTLCs and party settlements can be processed together, with all changes reflected in the new settlement script.
98+
99+
The verification logic ensures that:
100+
- The new lock script uses the same code_hash and hash_type
101+
- The new args match the expected format with updated settlement_hash
102+
- Output capacity/UDT amount reflects the settled amounts correctly
36103

37104
To know more about the transaction building process, please refer to the `test_commitment_lock_*` unit test.
38105

‎contracts/commitment-lock/build.rs‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
use ckb_gen_types::{packed::CellOutput, prelude::*};
22
use std::env;
3-
use std::fs::{read, File};
3+
use std::fs::{File, read};
44
use std::io::{BufWriter, Write};
55
use std::path::Path;
66

0 commit comments

Comments
 (0)