CKB Pulse
Lessons

What CKB learned

Start here · Glossary · Test yourself · Feed

Developer tooling

35 lessons found. All lessons

Page 3 of 3

Wait for the indexer to reach the block before truncating the devnet chain in reorg testsWorkingFrom one fix

In a devnet reorg test, the inclusion status a client reads from the node does not mean your own indexing service has processed that block. Before truncating the chain below block n, poll that service's indexed block number until it reaches n. Otherwise it never sees the block, never records a rollback, and the test times out on slow CI runners.

#Testing and devnet #Indexer queries and cell collection · Sources (1) · 2026-10-08

Output type scripts need cell deps too, including the native DAO typeBasicFrom one fix

CKB runs the type script of every output (not only input locks and input types), so a transaction that creates a native DAO deposit must include the DAO type's code cell (genesis tx0 index 2) as a cell dep, or the node rejects it with ScriptNotFound on Outputs[i].Type. Pre-send checks that only verify deps for input locks will miss this; check every input lock, input type and output type, deduplicated by code_hash and hash_type.

#Cell deps and script lookup #Transaction building and fees · Sources (1) · 2026-10-05

Verify header_deps against independently fetched headers, not against the tx's own listWorkingFrom one fix

When checking a transaction that uses header_deps for entropy (for example, headers at fixed offsets from a cell's inclusion block), derive the expected headers yourself: get the creating tx with get_transaction, then get_header on its block_hash, then get_header_by_number for the scheduled heights. Only then compare them to the tx's header_deps. Taking the headers from header_deps makes the check circular, since it only confirms the transaction agrees with itself.

#Since and time locks #Network and RPC reliability · Sources (1) · 2026-10-02

Derive devnet Spore and system script cell deps from a fresh OffCKB exportWorkingSeen again

Do not hardcode devnet code hashes and cell dep out points (secp256k1, Spore, cluster) in an example: they come from the local OffCKB devnet and can drift when OffCKB's bundled scripts change. Export them with `offckb system-scripts --network devnet --export-style ccc` before start, fail if a needed script lacks codeHash, hashType or a cellDep outPoint, and build both the CCC client config and the Spore SDK lumos config from that one file.

#Cell deps and script lookup #Testing and devnet · Sources (2) · 2026-09-29

ckb-cli needs --skip-check to sign and send transactions with custom locksWorkingFrom one fix

ckb-cli refuses transactions whose inputs or outputs use a lock it cannot classify (for example a custom type script based lock with 1 byte of args). `tx sign-inputs` then signs nothing, reporting `invalid lock script ... args.length` and leaving the signatures map and witness empty, and `tx send` refuses the file. Pass `--skip-check` to both sign-inputs and send; otherwise send fails with -2 ERROR_ENCODING because the secp lock reads an empty witness. Since this disables ckb-cli's own checks, run your own verifier on the signed file between sign-inputs and send.

Joined with toastmanAu/daowow@6f4cb48641.

#Witnesses and signatures #Transaction building and fees · Sources (2) · 2026-09-26

ckb-cli tx init overwrites an existing tx file with an empty skeletonWorkingFrom one fix

`ckb-cli tx init --tx-file` creates a new empty transaction file and exits 0, so running it on a prepared transaction silently destroys that transaction. For a prebuilt transaction, write ckb-cli's tx-file wrapper ({transaction, multisig_configs, signatures}) yourself and go straight to `tx info` and `tx sign-inputs`.

#Transaction building and fees #Witnesses and signatures · Sources (1) · 2026-09-23

ckb-cli tx sign-inputs stores signatures in the file's signatures map, not witness 0WorkingFrom one fix

ckb-cli `tx sign-inputs --add-signatures` leaves witness 0's lock zero-filled and records the signature in the tx file's `signatures` map keyed by lock arg; `tx send` assembles the final witnesses from that map. A checker that inspects witness 0 for a signature before `tx send` will wrongly report the transaction as unsigned, so read `doc.signatures[lockArg]` instead.

#Witnesses and signatures #Transaction building and fees · 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

Absence of on-chain references does not mean a code cell is safe to consumeWorkingFrom one fix

Before consuming a deployed code cell, search live cells for its data hash as lock and type script code hash (prefix mode, hash types data, data1 and data2), and compare its data hash (blake2b with personalization ckb-default-hash) against the binaries you currently build. Zero references does not mean superseded: a contract unchanged by a rebuild has no users yet and is still the live deployment. This search does not see type ID references or cell dep use, so treat a cell that anything may resolve by type ID or as a dep as still needed.

#Type ID and upgrades #Indexer queries and cell collection #Cell deps and script lookup · Sources (1) · 2026-09-20

ckb-cli deploy gen-txs does not check the block size limitWorkingFrom one fix

`ckb-cli deploy gen-txs` checks capacity and reports success even when the deployment transaction exceeds the 597,000 byte block size limit; the node only rejects it at broadcast with ExceededMaximumBlockBytes. When deploying several large contract binaries, sum their sizes before signing and split them across separate deployment configs (sending each transaction only after the previous one confirms) if they approach the limit.

#Transaction building and fees #Capacity and cell size · Sources (1) · 2026-09-18

Emit shannon u64 values as strings in cross-language test vectorsWorkingFrom one fix

When generating JSON test vectors in Rust for JavaScript decoders of CKB cell data, emit u64 fields (such as shannon amounts) as strings, because JSON numbers are IEEE-754 doubles and values above 2^53 would be silently rounded. Use distinct, non-zero field values so a decoder reading the wrong offset gives a visibly wrong result.

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

Page 3 of 3

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.