CKB Pulse
Lessons

What CKB learned

Lessons from the fixes and changes people made in CKB projects, kept up to date, by topic. Each one links to the commits it came from.

198 lessons from 47 projects so far, each one checked against the commit it came from.

Start here · Glossary · Test yourself · Feed

Drawn from public commits and checked against the commit each one came from and the project's code today. Read the source before you rely on one.

What do these mean?

New and newly proven this week

All the best proven lessons

All 198 lessons, in one list: Most proven first · Newest first

CKB node, RPC and indexer

The CKB node, its JSON-RPC and cell queries.

A rejected or unknown get_transaction status does not make a signed transaction deadWorkingFrom one fix

A node reporting a transaction you sent as rejected or unknown does not prove it is dead: one node's answer is not proof, and while all its inputs are live the signed bytes could still be rebroadcast by someone and commit. Only release its reserved inputs if a later transaction is guaranteed to conflict with it (here a shared pool cell every later action must spend, so at most one can commit), and also require that every input is still live, that the status is still rejected or unknown when rechecked after the input reads, and that the submission is old enough (2 minutes here), behind an explicit confirmation.

#Transaction building and fees #Network and RPC reliability · Sources (1) · 2026-10-26

Advancing devnet median time for time-lock testsWorkingFrom one fix

With the IntegrationTest RPC module enabled, call get_block_template, set current_time (hex ms) to a future value, and submit it with generate_block_with_template, block by block. Since/timestamp checks use the median time, which only moves after many future-dated blocks. Poll get_blockchain_info.median_time until it reaches the target rather than mining one far-future block.

#Testing and devnet #Since and time locks · Sources (1) · 2026-11-15

All 45 in this topic

Rust scripts and ckb-std

On-chain scripts written in Rust.

24-bit epoch number overflowWorkingFrom one fix

An absolute epoch since carries only a 24-bit epoch number (max 0xFFFFFF). When a script requires an input since at or after an epoch computed from cell data (for example entry_end plus a wait), compute it with checked addition. Refuse any result above 0xFFFFFF when the cell is created, otherwise the guarded transition can never be satisfied.

#Since and time locks · Sources (2) · 2026-11-17

Absolute epoch since needs the 0x20 metric flag in the top byteWorkingFrom one fix

An input since meaning "not before epoch N" must be 0x2000000000000000 | N: top byte 0x20 (absolute, epoch metric) with the epoch number in the low 24 bits. Without the flag the node reads the value as an absolute block number, which for any realistic epoch is already past, so the node enforces no epoch bound. A script that reads since as an epoch must check the metric flag itself, as this project's contract does by refusing a since whose top byte is not 0x20.

Builder side rule for setting the epoch flag.

#Since and time locks · Sources (2) · 2026-09-25

All 35 in this topic

Developer tooling

Debuggers, devnets, command line tools and tests around CKB.

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

Charging load_program bytes as cycles when building a custom ckb-vm machineAdvancedFrom one fix

When you build a ckb-vm machine yourself (DefaultMachineBuilder or AsmMachine) and call load_program, charge the returned byte count with machine.add_cycles_no_checking(ckb_script::cost_model::transferred_byte_cycles(bytes)). That count covers the loaded program and the stack and argument setup, and TransactionScriptsVerifier charges it on chain, so without it your cycle count comes out too low (in ckb-debugger the fib test went from 1361 to 3364 cycles). For AsmMachine call it on the inner machine, and pass the error up instead of unwrapping.

#Testing and devnet #Other · Sources (1) · 2026-11-03

All 35 in this topic

CCC (TypeScript SDK)

Building and signing transactions with CCC.

Adding a wallet missing from CCC's connector via a SignersController subclassWorkingChecked by the owner

To list a wallet that CCC's connector does not include yet, subclass ccc.SignersController (from @ckb-ccc/connector-react) and override addRealSigners: call this.addSigners(name, icon, [{ name: "CKB", signer }], context) with a ccc.Signer for that wallet, then await super.addRealSigners(context). Pass an instance to ccc.Provider as signersController. Wallets are shown in the order they are added, so adding yours before the super call puts it ahead of CCC's own. The Khie entry is drawn by the connector above that list and is not part of it; the hide-khie attribute removes it.

Order and the Khie entry checked against the CCC source at e10b99d (@ckb-ccc/ccc 1.3.7, connector 2.4.0): packages/ccc/src/signersController.ts (addSigner appends) and packages/connector/src/scenes/selecting/wallets.ts.

#Witnesses and signatures · Sources (1) · 2026-11-06

Building a remote CCC signer by extending SignerCkbPublicKeyWorkingFrom one fix

To expose a remote secp256k1 key as a CCC signer, extend ccc.SignerCkbPublicKey(client, publicKey) and override signOnlyTransaction and signMessageRaw to call the backend. The address and lock come from the public key, and signMessageRaw must sign in the "Nervos Message:" format so signMessage and verifyMessage keep working. SignerCkbPublicKey also reports anyone-can-pay addresses of the key, whose cells a backend that only signs the secp256k1 lock cannot spend, so override getAddressObjs to return only the lock you can sign (ckb-keyway had to do this later).

#Witnesses and signatures · Sources (1) · 2026-10-12

All 33 in this topic

Wallets and signing

Keys, signatures and wallet integrations.

Address balance via get_cells_capacity with snake_case lock scriptWorkingFrom one fix

To show a CKB address balance, convert the address to a lock script (ckb-sdk-utils addressToScript returns camelCase codeHash/hashType) and pass it to the indexer RPC get_cells_capacity with snake_case fields (code_hash, hash_type, args) and script_type "lock". The returned capacity is a hex shannon string, so parse it with BigInt and divide by 10^8 for CKB.

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

Binding an off-chain lock proof to the live cell deps it ran withAdvancedChecked by the owner

When an off-chain signature proof is verified by running the lock against cell deps read live from the chain, record every out point those deps resolved to, dep group members included. Treat the resulting authorization as valid only while all of those cells are still live. A lock upgrade, a redeployment, or a key rotation or recovery in a lock that keeps its keys in a dep cell spends one of them, and the owner must prove again.

#Cell deps and script lookup #Login and authorization · Sources (1) · 2026-11-04

All 23 in this topic

Apps and UI

Building dApps and their interfaces.

All 9 in this topic

Other

Lessons that fit no other topic.

Absolute epoch since needs the 0x20 metric flagWorkingFrom one fix

An input's since meant as an absolute epoch must have bit 61 set (0x2000000000000000) with bit 63 (relative) and bit 62 clear (RFC 0017). With all three top bits zero the node reads the same number as an absolute block number. The epoch number is in the low 24 bits (raw & 0xffffff), with index and length above it, so check the epoch number inclusively against the required epoch before signing.

since flag bits, not covered

#Since and time locks · Sources (1) · 2026-09-25

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

All 9 in this topic

Light client

The CKB light client and what runs on it.

Give light clients the committing block of a cell, not just its outpointWorkingChecked by the owner

A CKB light client that only watches scripts cannot look a cell up by outpoint, so a service that hands one a cell should also give the block number and hash of the transaction that created it. The client can then fetch that transaction by hash and watch for the cell being spent from that block, instead of scanning from genesis.

#Indexer queries and cell collection #Network and RPC reliability · Sources (1) · 2026-09-24

Light client scan absence does not prove a DAO withdrawing cell was spentWorkingFrom one fix

With the CKB light client, a DAO withdrawing cell older than the script's sync start is never returned by the scan, and the phase-2 unlock output is a plain cell that does not point back at it. So absence from the scan cannot mark the position spent: retire it only when the unlock transaction is confirmed (a verified local inclusion, or getTransactionStatus reporting committed on the node), keep it shown as confirming while the unlock is in flight, and never treat an unreachable node or an unknown transaction as a spend.

#Indexer queries and cell collection #Other · Sources (2) · 2026-10-09

All 5 in this topic

Spore and DOB

Digital objects and the Spore protocol.

Finding a spore or cluster by id through the indexer's get_transactionsWorkingFrom one fix

A spore id or cluster id is the args of the spore (or spore_cluster) type script, so you can look one up by calling get_transactions with that type script, args set to the id, script_search_mode "exact" and a limit of 0x1. Because get_transactions returns history and not just live cells, this also finds spores that have since been melted.

Lookup by id via get_transactions, includes melted spores.

#Indexer queries and cell collection · Sources (1) · 2026-10-30

Set cobuild: true when injecting OffCKB devnet Spore scripts into createSporeWorkingFrom one fix

OffCKB 0.4.13's system scripts export for the devnet Spore V2 deployment has only codeHash, hashType and cellDeps, with no field for the protocol mode. When building a SporeScriptInfoLike from it for @ckb-ccc/spore createSpore({ scriptInfo }), set cobuild: true yourself, because the deployed binary uses cobuild semantics. Treat that flag as an assumption you pin, not something read from the export.

cobuild: true needed for OffCKB devnet Spore scripts.

#Cell deps and script lookup #Testing and devnet · Sources (1) · 2026-10-28

xUDT and tokens

Fungible tokens on CKB.

Carry type script and data into the output when spending a lock-only custody cellWorkingFrom one fix

When a custom lock's spend rebuilds an output from an input cell that may carry a type script (a UDT held in custody, say), copy cell.cellOutput.type and cell.outputData into the output and change only the lock; writing outputsData "0x" with no type burns or strands the token. Add the type script's cell deps to the transaction before signing, because the signature covers the cell deps and callers cannot append them afterwards, and refuse to build the spend if a typed cell comes without them. If the lock also constrains who gets the capacity (as Tranfr's recipient claim does today), follow that rule instead of a plain copy.

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

Full-balance UDT burn is valid for SUDT and plain xUDTWorkingFrom one fix

Burning a UDT's entire balance is accepted by SUDT and xUDT without extensions, because those scripts allow output amount to be less than or equal to input amount. offckb removed a guard that rejected destroyAmount === totalBalance and now still emits a zero-balance type cell (16-byte zero amount), which is valid. Extension-enabled xUDT was not covered by this change.

#Transaction building and fees #Capacity and cell size · Sources (1) · 2026-10-08

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.