CKB Pulse
Lessons

What CKB learned

Start here · Glossary · Test yourself · Feed

“Data encoding (molecule, hex, bigints)”

44 lessons found. All lessons

Page 1 of 4

Hand-encoding WitnessArgs in moleculeWorkingFrom one fix

WitnessArgs is a molecule table of three BytesOpt fields (lock, input_type, output_type). An absent field takes zero bytes, but a present empty field still takes a 4-byte length header, so the two encode differently. The table starts with a u32le total size, then three u32le offsets, the first being 16 (4 + 4*3), each counted from the start of the table. Check any hand-written encoder byte for byte against ccc.WitnessArgs.from(...).toBytes(), including the cases lock only, all absent, and a present empty field.

#Data encoding (molecule, hex, bigints) #Witnesses and signatures · Sources (1) · 2026-11-14

Molecule table encoding of absent optional fieldsWorkingFrom one fix

A molecule table or dynvec (Script, CellOutput, WitnessArgs) is serialized as a u32 total size, then one u32 offset per field, then the fields. There is no separate count; readers derive it from the first offset. An absent Opt field takes zero bytes, so its offset equals the next offset, or the total size if it is last. A hand-rolled encoder that inserts a u32 count after the total size, as this commit's dyn_collection does, produces malformed molecule.

#Data encoding (molecule, hex, bigints) #Witnesses and signatures · Sources (1) · 2026-10-09

Use BigInt for uint64 RPC quantitiesWorkingFrom one fix

CKB RPC quantities such as max_cycles and max_block_cycles are uint64 hex strings, and Number or parseInt silently round anything above 2^53. When turning a decimal string a user typed into one, accept only /^[0-9]+$/, parse it with BigInt, reject n >= 1n<<64n, and format it as `0x${n.toString(16)}` (no leading zeros). To show an RPC hex value as decimal, use BigInt(hex).toString(10), never Number.

#Data encoding (molecule, hex, bigints) · Sources (1) · 2026-11-16

Exact CKB-to-shannon conversion with BigIntWorkingFrom one fix

Convert user-entered CKB amounts to shannons with BigInt string arithmetic: BigInt(whole) * 100000000n + BigInt(fraction.padEnd(8, '0')). Never use parseFloat(amount) * 1e8. First validate the input with /^\d+(\.\d{1,8})?$/, which rejects exponents, hex and commas, and reject any result above u64::MAX (0xffffffffffffffffn).

#Data encoding (molecule, hex, bigints) #Capacity and cell size · Sources (1) · 2026-11-15

Molecule hash_type byte valuesWorkingFrom one fix

In the molecule Script encoding, hash_type is data=0, type=1, data1=2, data2=4; 3 is not a valid value. Using 2 where you meant data2 builds a valid data1 script with a different hash, so indexer queries on it return nothing. Assert the raw byte inside the encoded Script, or run against a real devnet, because mocks that reuse the same constant on both sides cannot catch it.

#Data encoding (molecule, hex, bigints) #Indexer queries and cell collection #Testing and devnet · Sources (1) · 2026-11-15

Nervos DAO phase 1 withdrawing cells keep the DAO type; count deposits by 8 zero bytes of dataWorkingChecked by the owner

A Nervos DAO cell in phase 1 of withdrawal still has the DAO type script (code hash 0x82d76d...3f2e, hash_type type, args 0x), so filtering by type alone counts it as a deposit. Only cells whose output data is exactly 0x0000000000000000 are deposits; a withdrawing cell's data holds its deposit block number. The commit's testnet test shows a type-only count giving 500 CKB where the true deposit total is 300 CKB.

#Indexer queries and cell collection #Data encoding (molecule, hex, bigints) · Sources (2) · 2026-11-06

Use raw_data(), not as_slice(), when parsing a packed::Bytes witnessWorkingChecked by the owner

A transaction witness in ckb_types is a molecule packed::Bytes, so as_slice() returns the 4 byte length header followed by the content, while raw_data() returns only the content (here a serialized WitnessArgs). A check that compares a witness to the secp256k1 sighash placeholder WitnessArgs (lock of 65 zero bytes) must use witness.raw_data() (or unpack()), otherwise it is silently never true. Fiber's funding witness merge never recognized placeholders until it switched to raw_data(), so a peer's placeholder could be kept in place of a real signature.

#Data encoding (molecule, hex, bigints) #Witnesses and signatures · Sources (2) · 2026-10-29

Read cell data hash from the consensus DATA_HASH field instead of hashing loaded dataWorkingFrom one fix

To get a cell's data hash in a CKB script, read the DATA_HASH field with LOAD_CELL_BY_FIELD instead of loading the data with LOAD_CELL_DATA and hashing it yourself. The field works for any data size, while a fixed buffer breaks on larger data because LOAD_CELL_DATA reports the full remaining length, not the number of bytes copied. The field also returns 32 zero bytes for empty data, not Blake2b of empty, so a hash computed over loaded data would not match it.

#Data encoding (molecule, hex, bigints) #Capacity and cell size · Sources (1) · 2026-10-27

Strict validation of molecule table headers in hand written decodersWorkingFrom one fix

When decoding a molecule table by hand (here, the CSR registry cell data), check that the leading u32 total size equals the data length, derive the field count as first_offset/4 - 1, and require first_offset == 4 + 4*count and ascending offsets. Reject a field count different from the schema; this parser is strict and does not accept extra trailing fields, so truncated, padded or extended tables raise ValueError, as the tests show.

table header validation, distinct from WitnessArgs encoding lesson

#Data encoding (molecule, hex, bigints) · Sources (1) · 2026-10-19

Computing a transaction's molecule packed size from RPC JSONAdvancedFrom one fix

A CKB Transaction's packed size (the length of get_transaction with verbosity 0) can be computed from its RPC JSON without serializing it. It is 12 (table header) + RawTransaction + witnesses. RawTransaction is 28 (table header) + 4 (version) + cell_deps (4 + 37 each) + header_deps (4 + 32 each) + inputs (4 + 44 each) + outputs + outputs_data. Each CellOutput is 16 + 8 + lock size, plus the type script size only when a type is present. Each Script is 53 + len(args). A dynvec costs 4 + 4 * count + the sum of its item sizes, and every Bytes item in outputs_data and witnesses costs 4 + len.

#Data encoding (molecule, hex, bigints) #Transaction building and fees · Sources (1) · 2026-10-10

Hand-rolled Script hash: hash_type byte mapping and molecule offsets, checked against CCCWorkingReproduced

If you serialise a CKB Script molecule yourself to compute its blake2b hash, use a 16 byte header (total size plus three u32 offsets 16, 48, 49) and map hash_type as data=0, type=1, data1=2, data2=4 (not 3). This commit cross checks the result against ccc.Script.from(...).hash() for all four hash types, and a single wrong offset or data2 mapped to 3 makes that test fail.

#Data encoding (molecule, hex, bigints) #Testing and devnet · Sources (1) · 2026-09-23

Pin JS cell data encoders and decoders to Rust generated vectorsWorkingFrom one fix

When JS code encodes or decodes CKB cell data or script args that an on chain Rust script parses, test it against vectors exported from the Rust crate's own encoder, not against the JS code's own expectations. Assert every decoded field and every encoded byte, because a length check cannot catch a shifted offset. Give each field a distinct non zero value so a one byte shift gives a visibly wrong result. Read u64 shannon fields as BigInt (DataView.getBigUint64) and reject data of the wrong length.

Joined with toastmanAu/daowow@e08898943c.

#Data encoding (molecule, hex, bigints) #Testing and devnet · Sources (2) · 2026-09-22

Page 1 of 4

Text under CC BY 4.0: credit LusoCryptoLabs, CKB lessons, with a link to the lesson. JSON · Want a lesson changed or removed? Open an issue.