{"version":1,"generated":"2026-11-20T05:35:03Z","license":{"name":"CC BY 4.0","url":"https://creativecommons.org/licenses/by/4.0/","credit":"LusoCryptoLabs, CKB lessons, from the public commits of the projects each lesson cites"},"notice":"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.","withdrawn":[],"areas":{"apps":{"name":"Apps and UI","summary":"Building dApps and their interfaces."},"ccc":{"name":"CCC (TypeScript SDK)","summary":"Building and signing transactions with CCC."},"light-client":{"name":"Light client","summary":"The CKB light client and what runs on it."},"node":{"name":"CKB node, RPC and indexer","summary":"The CKB node, its JSON-RPC and cell queries."},"other":{"name":"Other","summary":"Lessons that fit no other topic."},"scripts":{"name":"Rust scripts and ckb-std","summary":"On-chain scripts written in Rust."},"spore":{"name":"Spore and DOB","summary":"Digital objects and the Spore protocol."},"tooling":{"name":"Developer tooling","summary":"Debuggers, devnets, command line tools and tests around CKB."},"wallets":{"name":"Wallets and signing","summary":"Keys, signatures and wallet integrations."},"xudt":{"name":"xUDT and tokens","summary":"Fungible tokens on CKB."}},"lessons":[{"id":"apps/exact-ckb-to-shannon-conversion-with-bigint","area":"apps","title":"Exact CKB-to-shannon conversion with BigInt","lesson":"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).","note":"","patterns":["Wrong: Math.round(parseFloat(amount) * 1e8). Preferred: BigInt(whole) * 100000000n + BigInt(fraction.padEnd(8, '0')), after checking /^\\d+(\\.\\d{1,8})?$/ and an upper bound of 0xffffffffffffffffn."],"concepts":["Data encoding (molecule, hex, bigints)","Capacity and cell size"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-11-15","last_touched":"2026-11-15","level":"working","why":"Float or Number arithmetic loses shannon precision for amounts past the safe integer range, such as 99999999999.99999999 CKB, and loose parsing accepts inputs like '1e3' or '0x100' that become the wrong capacity.","sources":[{"repo":"Hanssen0-Alter-Ego/ckb-vm-js","hash":"b6e28a4100","date":"2026-11-15"}],"tests":[{"repo":"Hanssen0-Alter-Ego/ckb-vm-js","hash":"b6e28a4100","files":["tests/browser/playground.spec.js","tests/js/guided.test.js"]}],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"partly right","against_commit":true}},{"id":"apps/lock-based-fallback-when-a-stored-out-point-goes-stale","area":"apps","title":"Lock-based fallback when a stored out point goes stale","lesson":"A saved out point stops being valid once the cell is consumed and recreated. Use the recorded out point if it is still live; otherwise find the unique live cell matching the exact lock (code_hash, hash_type, args). In both cases, still check the cell's contents against the recorded values.","note":"","patterns":["filtering live cells only by the recorded out_point → no match after the cell was replaced; prefer recorded match if present else unique cell matching lock script"],"concepts":["Indexer queries and cell collection"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-11-15","last_touched":"2026-11-15","level":"working","why":"After the cell is consumed and recreated (here by Arm), a lookup that filters only by the recorded out point finds nothing, so verification of a valid switch fails.","sources":[{"repo":"psawyerberlin/ckb-revocable-timelock","hash":"fd33a35810","date":"2026-11-15"}],"tests":[{"repo":"psawyerberlin/ckb-revocable-timelock","hash":"fd33a35810","files":["client/test/chain.test.ts"]}],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"apps/nervos-dao-hold-time-with-term-locked-withdrawals","area":"apps","title":"Nervos DAO hold time with term-locked withdrawals","lesson":"The Nervos DAO pays out phase 2 only at a whole number of 180-epoch cycles counted from the deposit epoch D, so a withdrawal started after D + 180×n matures at D + 180×(n+1). If a lock refuses phase 1 until a term of n cycles has passed, then in practice the funds are held (n + 1) × 180 epochs, not n × 180, and interest stops at the phase 1 block. Only a phase 1 that lands exactly in the boundary epoch fraction avoids the extra cycle.","note":"","patterns":["termMs = daoTermPeriods * 180 * EPOCH_MS  →  (daoTermPeriods + 1) * 180 * EPOCH_MS when the withdrawal can only be started after the term"],"concepts":["Since and time locks","Other"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-11-13","last_touched":"2026-11-13","level":"working","why":"Without it the app tells users a one-term deposit is held about 30 days when it is really about 60, and the last cycle earns no interest.","sources":[{"repo":"toastmanAu/daowow","hash":"186405ba35","date":"2026-11-13"}],"tests":[{"repo":"toastmanAu/daowow","hash":"186405ba35","files":["apps/web/test/model-timeline.test.js"]}],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"partly right","against_commit":true}},{"id":"apps/occupied-capacity-depends-on-the-actual-lock-s-args-length","area":"apps","title":"Occupied capacity depends on the actual lock's args length","lesson":"When quoting the capacity for cells locked to a user's wallet, compute the occupied size from the connected lock script (8 capacity bytes + 32 code_hash + 1 hash_type + args length + type + data), not a hardcoded value. In this commit a JoyID lock with 22 byte args gives a 222 CKB claim cell and a secp256k1 lock with 20 byte args gives 220 CKB. The script's molecule serialization header does not count toward occupied capacity.","note":"Distinct from the pre-sign checker lesson: this is about sizing by the connected lock's real args length.","patterns":["prefer: const lockScriptSize = (lockScript) => 32n + 1n + argsLength(lockScript);"],"concepts":["Capacity and cell size"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-09-23","last_touched":"2026-09-23","level":"working","why":"A hardcoded lock size misquotes the capacity for any wallet whose lock args differ in length. In this commit that is 2 CKB per claim cell between JoyID (22 bytes) and secp256k1 (20 bytes), so the quoted total the user agrees to would not match what the transaction needs.","sources":[{"repo":"toastmanAu/daowow","hash":"6597dc0039","date":"2026-09-23"}],"tests":[{"repo":"toastmanAu/daowow","hash":"6597dc0039","files":["apps/web/test/quote.test.js","crates/daowow-core/tests/gen_vectors.rs"]}],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"apps/pinning-js-codecs-and-derivations-to-rust-test-vectors","area":"apps","title":"Pinning JS codecs and derivations to Rust test vectors","lesson":"When off-chain JS encodes or derives cell data that a Rust type script decodes or re-derives byte for byte, test the JS against JSON vectors generated by the Rust code, using a distinct value in every field so a wrong offset fails. Mirror the contract's validation refusals and its exact ordering and rounding: BTreeMap ascending key order, BigInt floor division with the dust going to fixed indices, and merging duplicates before dividing. The chain only returns a bare error code, so only this off-chain check can tell you which rule failed.","note":"","patterns":["Off-chain JS builds cell data that the script re-derives (sort by lock hash, BigInt floor shares, residual +1 to the lowest keys), with tests asserting the encoded bytes equal Rust vectors.","JS codec tested only against itself → load tests/vectors/*.json written by Rust, decode and re-encode it byte for byte, and mirror the contract's decode refusals and immutable-field checks in the encoder and state-advance helpers"],"concepts":["Data encoding (molecule, hex, bigints)","Testing and devnet","Transaction building and fees"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-11-13","last_touched":"2026-11-13","level":"working","why":"If the JS sorts, rounds or assigns dust differently from the script, it builds settlement data the script refuses with a bare error code that names no rule.","sources":[{"repo":"toastmanAu/daowow","hash":"38c5f839ea","date":"2026-11-13"},{"repo":"toastmanAu/daowow","hash":"07b313eacd","date":"2026-11-13"}],"tests":[{"repo":"toastmanAu/daowow","hash":"38c5f839ea","files":["apps/web/test/entitlements.test.js","crates/daowow-core/tests/gen_vectors.rs"]},{"repo":"toastmanAu/daowow","hash":"07b313eacd","files":["apps/web/test/settlement-codec.test.js"]}],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"partly right","against_commit":true}},{"id":"apps/pre-sign-checkers-must-mirror-every-on-chain-comparison","area":"apps","title":"Pre-sign checkers must mirror every on-chain comparison","lesson":"A pre-sign checker that reuses the builder's assumptions will miss the builder's bugs, so make it compare every field the script compares, outputs_data included. When you add data to an output, count those bytes in its occupied capacity (8 + data + lock + type). Replay refused transactions in ckb-debugger against the deployed binaries to confirm the fix.","note":"","patterns":["outputsData: [..., \"0x\", ...] for a cell whose type script checks its data; capacity computed with 0 data bytes"],"concepts":["Capacity and cell size","Transaction building and fees","Testing and devnet"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-11-11","last_touched":"2026-11-11","level":"working","why":"The builder wrote an empty receipt cell that the contract refused with -28 SHARD_ERROR_DATA on testnet after signing, because the checker shared the builder's belief and never compared outputs_data; the cell's capacity was also short by the 73 data bytes it needed.","sources":[{"repo":"toastmanAu/daowow","hash":"d60153aee0","date":"2026-11-11"}],"tests":[{"repo":"toastmanAu/daowow","hash":"d60153aee0","files":["apps/web/test/aggregate-tx.test.js","apps/web/test/lifecycle-rules.test.js"]}],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"apps/resolving-cell-deps-per-cell-after-redeploying-a-data-hashed","area":"apps","title":"Resolving cell deps per cell after redeploying a data-hashed script","lesson":"After a data/data1 type script is redeployed with a new code hash, old cells still run against the old code. Keep a list of retired deployments and query the indexer for every one. Pick each cell's cell dep by matching the codeHash and hashType of that cell's own type script, not a single 'current' manifest entry.","note":"","patterns":["manifest.scripts[name] used for every cell → resolve per cell: deployments.find(d => d.codeHash===cell.type.codeHash && d.hashType===cell.type.hashType)"],"concepts":["Cell deps and script lookup","Type ID and upgrades","Indexer queries and cell collection"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-11-17","last_touched":"2026-11-17","level":"working","why":"Indexer scans and holdings filters keyed only to the newest code hash miss every cell made under the replaced contract. A transaction built with the newest contract's cell dep for such a cell is built against the wrong code, and the app's checker refuses it.","sources":[{"repo":"toastmanAu/daowow","hash":"ea2df1bbd1","date":"2026-11-17"}],"tests":[{"repo":"toastmanAu/daowow","hash":"ea2df1bbd1","files":["apps/web/test/app-shell.test.js","apps/web/test/helpers/fake-chain.js","apps/web/test/manifest.test.js","apps/web/test/model-claim-guard.test.js","apps/web/test/round-cells.test.js"]}],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"apps/saving-local-state-after-the-first-step-of-a-multi-step-flow","area":"apps","title":"Saving local state after the first step of a multi-step flow","lesson":"In flows like Create followed by Arm, save local state right after the first transaction is sent. If you wait until the whole flow finishes, a failure in a later step leaves an on-chain object the user cannot find or cancel. Add the extra fields, such as the descriptor, once the later steps succeed.","note":"","patterns":["remember() returned early unless the descriptor existed, so the switch was only saved after Arm. The fix calls remember() right after prepared.send() and adds the descriptor fields only when they are present."],"concepts":["Transaction building and fees","Other"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-11-16","last_touched":"2026-11-16","level":"working","why":"If Arm fails after Create was sent, the user has an on-chain switch that does not appear in My switches and cannot be cancelled.","sources":[{"repo":"psawyerberlin/dead-man-switch","hash":"cd29be2349","date":"2026-11-16"}],"tests":[],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"not CKB specific","against_commit":true}},{"id":"apps/witness-data-in-input-type-and-folding-sub-minimum-change","area":"apps","title":"Witness data in input_type and folding sub-minimum change","lesson":"Put the type script's witness data in WitnessArgs.input_type of each input it guards (the type script reads the first witness of its own input group), so the lock field stays free for the wallet's signature and one signature can cover several such inputs. If the change left after a fixed fee is below a plain cell's minimum occupied capacity, add it to an existing output whose scripts accept extra capacity; if there is no such output, refuse the build instead of creating a cell that cannot exist.","note":"","patterns":["witnesses: inputs.map(() => WitnessArgs{inputType: data}); if (rest < plainFloor) outputs[0].capacity += rest"],"concepts":["Witnesses and signatures","Transaction building and fees","Capacity and cell size"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-11-14","last_touched":"2026-11-14","level":"working","why":"If the type script's data sat in the lock field, the wallet's signature would overwrite it or clash with it, and one wallet could not sign a transaction that retires several tickets at once.","sources":[{"repo":"toastmanAu/daowow","hash":"3dc1b8675b","date":"2026-11-14"}],"tests":[{"repo":"toastmanAu/daowow","hash":"3dc1b8675b","files":["apps/web/test/retire-tx.test.js"]}],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"partly right","against_commit":true}},{"id":"ccc/adding-a-wallet-missing-from-ccc-s-connector-via-a-signersco","area":"ccc","title":"Adding a wallet missing from CCC's connector via a SignersController subclass","lesson":"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.","note":"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.","patterns":["prefer: await this.addSigners(\"Cellula\", cellulaIcon, [{ name: \"CKB\", signer: new CellulaWalletSigner(context.client) }], context);"],"concepts":["Witnesses and signatures"],"applies_to":[],"status":"current","evidence":"L2","first_seen":"2026-11-06","last_touched":"2026-11-06","level":"working","why":"Without a custom SignersController, users of a wallet missing from CCC's built-in list, such as Cellula, cannot connect to the dApp at all.","sources":[{"repo":"LusoCryptoLabs/ckb-ward","hash":"90684f0b26","date":"2026-11-06"}],"tests":[],"related":[],"confirmed":{"by":"LusoCryptoLabs","role":"owner","date":"2026-11-19"},"reproduced":null,"checked":{"date":"2026-11-19","verdict":"partly right","against_commit":true}},{"id":"ccc/building-a-remote-ccc-signer-by-extending-signerckbpublickey","area":"ccc","title":"Building a remote CCC signer by extending SignerCkbPublicKey","lesson":"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).","note":"","patterns":[],"concepts":["Witnesses and signatures"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-10-12","last_touched":"2026-10-12","level":"working","why":"If signMessageRaw signs in any other format, signatures from the remote signer fail CCC's verifyMessage even though the key is correct.","sources":[{"repo":"officialcmg/ckb-keyway","hash":"d310483b66","date":"2026-10-12"}],"tests":[],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"partly right","against_commit":true}},{"id":"ccc/ccc-2-3-ccc-connector-fires-close-before-the-connection-even","area":"ccc","title":"CCC 2.3 ccc-connector fires close before the connection event","lesson":"CCC's ccc-connector element emits close before it announces a newly chosen wallet, every time. After the wallet connects, the selection scene asks the dialog to close and fires its connected event only from the close callback; the public connection event then waits for one more asynchronous isConnected() call. Treating close as a cancel therefore loses the connection. On close, check whether a wallet was chosen (the example reads el.walletName and el.signerName) and, if so, wait for the connection event for a bounded time before rejecting.","note":"Checked against the CCC source in @ckb-ccc/connector 2.3.2 (9ffef01) and 2.4.0 (e10b99d): scenes/selecting/index.ts (connectSigner) and connector/index.ts (close, handleConnected, updateSigner).","patterns":["prefer: if (el.walletName && el.signerName) setTimeout(() => void finish(el.connection), 8000);"],"concepts":["Login and authorization"],"applies_to":[],"status":"current","evidence":"L2","first_seen":"2026-10-12","last_touched":"2026-10-12","level":"working","why":"A wallet the user just connected is reported as a cancelled login and the connection is discarded.","sources":[{"repo":"LusoCryptoLabs/poi-onchain","hash":"57df766867","date":"2026-10-12"}],"tests":[],"related":[],"confirmed":{"by":"LusoCryptoLabs","role":"owner","date":"2026-11-19"},"reproduced":null,"checked":{"date":"2026-11-19","verdict":"partly right","against_commit":true}},{"id":"ccc/ccc-client-cache-can-keep-dropped-transactions-check-status","area":"ccc","title":"CCC client cache can keep dropped transactions; check status without cache","lesson":"A ccc client records the transactions it sends in its cache, so a claim or sweep the chain dropped or rejected stays there with its outputs usable and its inputs spent, which breaks later sends. Check such transactions with client.getTransactionNoCache and treat an undefined result or status \"rejected\" as dropped. Rebuild that client's cache from the chain before building new sends, and give automated sends their own ccc client so this rebuild does not touch the account's other pending transactions.","note":"Related to the cache clearing and getTransactionNoCache lessons, but adds a distinct remedy: treat undefined or rejected as dropped, and use a separate client for automated sends to isolate its cache.","patterns":["prefer: const found = await nodeKeyClient.getTransactionNoCache(txHash).catch(() => null);"],"concepts":["Network and RPC reliability","Transaction building and fees"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-11-17","last_touched":"2026-11-17","level":"working","why":"A dropped claim or sweep left in ccc's cache keeps its payout looking usable and its fee reserve looking spent, so every later claim built from that cache fails.","sources":[{"repo":"officialcmg/ckb-keyway","hash":"e690312ef4","date":"2026-11-17"}],"tests":[{"repo":"officialcmg/ckb-keyway","hash":"e690312ef4","files":["tests/api-client.test.ts","tests/browser-watchtower.test.ts","tests/channel-openings.test.ts","tests/logout-handoff.test.ts","tests/node-backup-postgres.test.ts"]}],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"ccc/ccc-custom-client-scripts-must-include-anyonecanpay-for-sign","area":"ccc","title":"CCC custom client scripts must include AnyoneCanPay for SignerCkbPrivateKey","lesson":"On a devnet, if you construct a CCC client with a custom `scripts` map that overrides only `KnownScript.Secp256k1Blake160`, `SignerCkbPrivateKey` can still fail. This commit's comment says the signer also loads AnyoneCanPay metadata while classifying related locks, so it adds a `KnownScript.AnyoneCanPay` entry to the map even though no ACP input or cell dep is used.","note":"","patterns":["prefer: scripts:{[c.KnownScript.Secp256k1Blake160]:{codeHash:K,hashType:'type',cellDeps:[{cellDep:dep}]},[c.KnownScript.AnyoneCanPay]:acp}"],"concepts":["Cell deps and script lookup","Testing and devnet"],"applies_to":[],"status":"current","evidence":"L3","first_seen":"2026-10-23","last_touched":"2026-10-23","level":"working","why":"Without an AnyoneCanPay entry in a custom scripts map, SignerCkbPrivateKey cannot resolve the ACP known script while it classifies related locks, so signing breaks even for a transaction that only uses secp256k1 locks.","sources":[{"repo":"Ticoworld/QuotaCell","hash":"f34c10b933","date":"2026-10-23"}],"tests":[{"repo":"Ticoworld/QuotaCell","hash":"f34c10b933","files":["policy/deps/ckb-c-stdlib/tests/ci.c"]}],"related":[],"confirmed":null,"reproduced":{"repo":"LusoCryptoLabs/ckb-lesson-tests","test":"tests/ccc/custom-scripts-need-anyone-can-pay.test.mjs","commit":"27ec5fdaeb","library":"@ckb-ccc/core","version":"1.23.1","covers":"all","date":"2026-11-20"},"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"ccc/ccc-evm-and-bitcoin-signers-pass-the-exact-signed-text-throu","area":"ccc","title":"CCC EVM and Bitcoin signers pass the exact signed text through signMessageRaw","lesson":"In CCC, the EVM and Bitcoin signers' signTransaction builds the text to sign and passes it to this.signMessageRaw. A dApp can temporarily replace signMessageRaw on the signer instance, record the argument, call the original, and restore it afterwards, to show users the text the wallet will sign. Omnilock in Ethereum display mode (auth flag 0x12) passes \"CKB transaction: 0x…\" and Bitcoin signers pass \"CKB (Bitcoin Layer) transaction: 0x…\". PW-lock and Omnilock with flag 0x01 pass a bare 32 byte hash. This relies on CCC internals, so recheck it when upgrading.","note":"","patterns":["prefer: s.signMessageRaw = (m) => { setWalletShows(typeof m === \"string\" ? m : ccc.hexFrom(m)); return original.call(signer, m); };"],"concepts":["Witnesses and signatures"],"applies_to":[],"status":"current","evidence":"L2","first_seen":"2026-11-07","last_touched":"2026-11-07","level":"working","why":"Without seeing the exact text, users are shown a \"CKB transaction\" prompt or a bare hash they cannot check against the page, so they cannot confirm what they are signing.","sources":[{"repo":"LusoCryptoLabs/ckb-ward","hash":"37b57d4341","date":"2026-11-07"}],"tests":[],"related":[],"confirmed":{"by":"LusoCryptoLabs","role":"owner","date":"2026-11-19"},"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"ccc/ccc-evm-signer-exposes-several-lock-addresses-via-getaddress","area":"ccc","title":"CCC EVM signer exposes several lock addresses via getAddressObjs","lesson":"A CCC signer for MetaMask can control more than one CKB lock (Omnilock addresses and the legacy PW-lock address used by Portal Wallet), and getRecommendedAddressObj returns only one of them. When assets such as Nervos DAO deposits may sit under any of them, call signer.getAddressObjs(), dedupe by script hash and check each, rather than assuming the recommended address holds the funds.","note":"","patterns":["prefer: const all = await signer.getAddressObjs().catch(() => [first]);"],"concepts":["Indexer queries and cell collection","Login and authorization"],"applies_to":[],"status":"current","evidence":"L2","first_seen":"2026-11-06","last_touched":"2026-11-06","level":"working","why":"A MetaMask user whose Nervos DAO deposit sits under the legacy PW-lock (Portal Wallet) address or the other Omnilock address would appear to hold nothing, because only the recommended address is read.","sources":[{"repo":"LusoCryptoLabs/ckb-ward","hash":"33d06821e2","date":"2026-11-06"}],"tests":[],"related":[],"confirmed":{"by":"LusoCryptoLabs","role":"owner","date":"2026-11-19"},"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"ccc/clamp-the-node-s-get-fee-rate-statistics-median-before-using","area":"ccc","title":"Clamp the node's get_fee_rate_statistics median before using it as a fee rate","lesson":"Do not pass the node's get_fee_rate_statistics median straight to a transaction builder: a high or untrusted endpoint can set the fee rate for every transaction you build. Clamp it between the minimum relay rate (1,000 shannons/KB) and an app-chosen ceiling, and fall back to the minimum if the call fails, accepting that a ceiling below the real market rate can make confirmation slow. openswap used 1,000 to 5,000 shannons/KB (testnet nodes suggested 33,000 to 47,000) plus a 0.01 CKB per-transaction cap.","note":"","patterns":["prefer: const rate=suggested<ORDER_FEE_POLICY.minRate?ORDER_FEE_POLICY.minRate:suggested>ORDER_FEE_POLICY.maxRate?ORDER_FEE_POLICY.maxRate:suggested;"],"concepts":["Transaction building and fees","Network and RPC reliability"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-10-29","last_touched":"2026-10-29","level":"working","why":"Without the clamp, order-book transactions paid whatever median the node reported, which on testnet was 33,000 to 47,000 shannons/KB, many times the 1,000 minimum, with no upper bound.","sources":[{"repo":"toastmanAu/openswap","hash":"bbc87255fa","date":"2026-10-29"}],"tests":[{"repo":"toastmanAu/openswap","hash":"bbc87255fa","files":["frontend/test/fixtures.ts","frontend/test/pools.spec.ts","sdk/test/frontend-fees.test.ts"]}],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"ccc/classifying-sendtransaction-failures-before-dropping-a-pendi","area":"ccc","title":"Classifying sendTransaction failures before dropping a pending CKB transaction","lesson":"A failed or timed out ccc client.sendTransaction, or a getTransaction status of \"rejected\" or \"unknown\", does not prove the transaction can never commit: a node may have taken it, and \"rejected\" also covers pool removals such as expiry or a full pool. Store the signed bytes before sending. Drop the pending state only on final refusals (ErrorClientVerification, ErrorClientMaxFeeRateExceeded, TransactionFailedToVerify, PoolRejectedMalformedTransaction), or when an input is not live, the transaction that created that input is committed, and the node no longer holds your transaction as pending, proposed or committed. A not-live input alone is not proof, because CCC's getCellLive also returns not live for a cell the node has not seen. Otherwise resend the stored bytes, treating ErrorClientDuplicatedTransaction and PoolRejectedDuplicatedTransaction as success.","note":"","patterns":["prefer: if (error instanceof ccc.ErrorClientVerification || error instanceof ccc.ErrorClientMaxFeeRateExceeded) return true;"],"concepts":["Network and RPC reliability","Transaction building and fees"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-11-08","last_touched":"2026-11-08","level":"working","why":"Clearing the pending change on a timeout or a non-final rejection loses track of a transaction that a node may still commit, so the account's settings and address diverge from the chain.","sources":[{"repo":"officialcmg/ckb-keyway","hash":"f3362361bb","date":"2026-11-08"}],"tests":[{"repo":"officialcmg/ckb-keyway","hash":"f3362361bb","files":["tests/recovery-postgres.test.ts","tests/user-wallet.test.ts"]}],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"partly right","against_commit":true}},{"id":"ccc/clear-the-ccc-client-cache-after-a-sent-transaction-loses-a","area":"ccc","title":"Clear the CCC client cache after a sent transaction loses a double spend race","lesson":"A CCC client caches the outputs of every transaction it sent, so when that transaction loses a race for the same input and never commits, its change cells still look usable to later builds. This campaign calls client.cache.clear() on every client before rebuilding and confirms candidate cells with getCellLiveNoCache rather than trusting cached state.","note":"","patterns":["prefer: for(const c of clients)await c.cache.clear();"],"concepts":["Indexer queries and cell collection","Transaction building and fees"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-10-29","last_touched":"2026-10-29","level":"working","why":"Without clearing, the losing client's cache still lists that transaction's change outputs as spendable and its inputs as spent, so rebuilds pick cells that do not exist on chain and the node rejects them.","sources":[{"repo":"toastmanAu/openswap","hash":"28324835a0","date":"2026-10-29"}],"tests":[],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"ccc/completefeeby-adds-change-instead-of-shrinking-outputs-break","area":"ccc","title":"completeFeeBy adds change instead of shrinking outputs, breaking output bound proofs","lesson":"When a lock script commits to output 0's exact bytes (capacity included), the capacity must be decided before proving and must equal what the transaction ships. In CCC, tx.completeFeeBy(signer) pays the fee by pulling in the signer's cells and adding a change output, so output 0 keeps its capacity and the fee is then paid from extra inputs, which breaks the binding if the proof assumed inputCapacity minus fee. Instead compute the fee from tx.toBytes().length with the witness already at its final length, build output 0 at inputCapacity minus that fee, and check before sending that the fee recomputed on the real transaction equals the planned one.","note":"","patterns":["avoid: await tx.completeFeeBy(signer);"],"concepts":["Transaction building and fees","Witnesses and signatures","Capacity and cell size"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-11-04","last_touched":"2026-11-04","level":"working","why":"The context was computed for output 0 at inputCapacity minus fee, but completeFeeBy left output 0 at inputCapacity and added a change output, so every bound unlock was rejected on chain with ContextMismatch.","sources":[{"repo":"CECILIA-MULANDI/zk-Lock","hash":"be4ecf3a60","date":"2026-11-04"}],"tests":[{"repo":"CECILIA-MULANDI/zk-Lock","hash":"be4ecf3a60","files":["sdk/ts/test/bound.test.ts"]}],"related":[],"confirmed":null,"reproduced":{"repo":"LusoCryptoLabs/ckb-lesson-tests","test":"tests/ccc/complete-fee-by-adds-change.test.mjs","commit":"27ec5fdaeb","library":"@ckb-ccc/core","version":"1.23.1","covers":"part: what completeFeeBy does to the transaction, not the lock that commits to output 0","date":"2026-11-20"},"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"ccc/convert-fiber-rpc-snake-case-scripts-to-ccc-camelcase-script","area":"ccc","title":"Convert Fiber RPC snake_case scripts to CCC camelCase ScriptLike","lesson":"Fiber RPC returns scripts as { code_hash, hash_type, args }, but CCC's ScriptLike expects { codeHash, hashType, args }. In this commit a Fiber shaped lock was passed to a CCC based sweep as if it were a ccc.ScriptLike and the sweep failed, so map the fields explicitly before handing the script to CCC.","note":"","patterns":["prefer: { codeHash: to.code_hash, hashType: to.hash_type, args: to.args }"],"concepts":["Data encoding (molecule, hex, bigints)","Channels and payments"],"applies_to":[],"status":"current","evidence":"L3","first_seen":"2026-10-14","last_touched":"2026-10-14","level":"working","why":"If a Fiber snake_case script is passed where CCC expects a ScriptLike, codeHash and hashType come through undefined, so the hosted settlement sweep failed and the user's funds were not swept.","sources":[{"repo":"officialcmg/ckb-keyway","hash":"a33b5cf784","date":"2026-10-14"}],"tests":[],"related":[],"confirmed":null,"reproduced":{"repo":"LusoCryptoLabs/ckb-lesson-tests","test":"tests/ccc/fiber-snake-case-script.test.mjs","commit":"27ec5fdaeb","library":"@ckb-ccc/core","version":"1.23.1","covers":"all","date":"2026-11-20"},"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"ccc/deriving-minimum-cell-capacity-with-ccc-celloutput-from-and","area":"ccc","title":"Deriving minimum cell capacity with ccc.CellOutput.from and output data","lesson":"In CCC, calling ccc.CellOutput.from({lock, type}, outputData) without a capacity fills capacity with the cell's occupied size, so it serves as the minimum capacity check for change or receipt cells. This commit uses it to reject dust change before and after subtracting the fee (via transaction.estimateFee), and to top up a receipt cell whose received CKB is below its occupied capacity.","note":"","patterns":["prefer: return ccc.CellOutput.from({lock:cell.cellOutput.lock,type:cell.cellOutput.type},cell.outputData).capacity;"],"concepts":["Capacity and cell size","Transaction building and fees"],"applies_to":[],"status":"current","evidence":"L3","first_seen":"2026-10-01","last_touched":"2026-10-01","level":"working","why":"Without deriving occupied capacity, change or receipt outputs can fall below the cell's minimum capacity (for example after the fee is subtracted, or when a small CKB amount is received), producing a transaction the node rejects for insufficient output capacity.","sources":[{"repo":"toastmanAu/openswap","hash":"85731fe783","date":"2026-10-01"}],"tests":[{"repo":"toastmanAu/openswap","hash":"85731fe783","files":["pool-sdk/test/builders.test.ts","pool-sdk/test/cli.test.ts","pool-sdk/test/codec.test.ts","pool-sdk/test/transport.test.ts","pool-sdk/test/vm-bridge.ts"]}],"related":[],"confirmed":null,"reproduced":{"repo":"LusoCryptoLabs/ckb-lesson-tests","test":"tests/ccc/minimum-capacity.test.mjs","commit":"27ec5fdaeb","library":"@ckb-ccc/core","version":"1.23.1","covers":"all","date":"2026-11-20"},"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"ccc/hand-rolled-script-hash-hash-type-byte-mapping-and-molecule","area":"ccc","title":"Hand-rolled Script hash: hash_type byte mapping and molecule offsets, checked against CCC","lesson":"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.","note":"","patterns":["prefer: const hashType = { data: 0, type: 1, data1: 2, data2: 4 }[script.hashType];"],"concepts":["Data encoding (molecule, hex, bigints)","Testing and devnet"],"applies_to":[],"status":"current","evidence":"L3","first_seen":"2026-09-23","last_touched":"2026-09-23","level":"working","why":"A wrong molecule offset or data2 mapped to 3 yields a plausible script hash that matches nothing, so a lock hash comparison such as entry-lock's committed participant check refuses the spend.","sources":[{"repo":"toastmanAu/daowow","hash":"384178e243","date":"2026-09-23"}],"tests":[{"repo":"toastmanAu/daowow","hash":"384178e243","files":["apps/web/test/refund-tx.test.js"]}],"related":[],"confirmed":null,"reproduced":{"repo":"LusoCryptoLabs/ckb-lesson-tests","test":"tests/ccc/script-hash.test.mjs","commit":"27ec5fdaeb","library":"@ckb-ccc/core","version":"1.23.1","covers":"all","date":"2026-11-20"},"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"ccc/headless-eip-6963-test-wallet-for-driving-the-ccc-connector","area":"ccc","title":"Headless EIP-6963 test wallet for driving the CCC connector in Playwright","lesson":"To drive CCC's real EIP-6963 connector and EVM/Omnilock signing in headless Playwright, inject a minimal EIP-1193 provider with page.addInitScript passed as a string, because transpiled function sources carry helpers such as __name that the page lacks. The provider answers eth_requestAccounts, eth_accounts and personal_sign, stubs on and removeListener, and announces itself on eip6963:announceProvider, also whenever eip6963:requestProvider fires. Signing runs in Node through page.exposeFunction so the key never enters the page, and personal_sign must return r‖s‖v with v = 27 + recovery id; noble-curves 2.x sign with format \"recovered\" yields recovery‖r‖s, so reorder it with hexFrom(bytesConcat(recovered.slice(1, 65), [recovered[0] + 27])) and check it against ccc.verifyMessageEvmPersonal.","note":"","patterns":["prefer: return hexFrom(bytesConcat(recovered.slice(1, 65), [recovered[0] + 27]));"],"concepts":["Testing and devnet","Witnesses and signatures"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-10-22","last_touched":"2026-10-22","level":"working","why":"With noble's recovery‖r‖s layout passed through unchanged, the signature is not in the r‖s‖v form personal_sign is expected to return, so the commit checks its signer against ccc.verifyMessageEvmPersonal.","sources":[{"repo":"salmansarwarr/Tranfr","hash":"dd62e17d02","date":"2026-10-22"}],"tests":[{"repo":"salmansarwarr/Tranfr","hash":"dd62e17d02","files":["demo/e2e/lifecycle.spec.ts","demo/e2e/test-wallet.ts"]}],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"ccc/locate-the-signing-witness-slot-instead-of-hardcoding-its-in","area":"ccc","title":"Locate the signing witness slot instead of hardcoding its index","lesson":"The signing witness of a lock group sits at the index of the first input that uses that lock, so it differs between transaction shapes (in QuotaCell, 1 for payments and most owner actions, 0 for a deposit). In CCC, take the position from tx.getSignHashInfo(lock, client).position and assert it matches the position you set, instead of hardcoding 1. A wallet or test mock that has no lock available can look for the placeholder witness, but a bare \"first non-empty witness\" search is only safe when no other input carries a witness.","note":"","patterns":[],"concepts":["Witnesses and signatures"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-11-05","last_touched":"2026-11-05","level":"working","why":"A hardcoded index such as 1 makes the mock wallet sign the wrong witness when an owner transaction puts the signer's input elsewhere, so that signature fails verification.","sources":[{"repo":"Ticoworld/QuotaCell","hash":"f6c69d99a5","date":"2026-11-05"}],"tests":[],"related":[],"confirmed":null,"reproduced":{"repo":"LusoCryptoLabs/ckb-lesson-tests","test":"tests/ccc/signing-witness-position.test.mjs","commit":"27ec5fdaeb","library":"@ckb-ccc/core","version":"1.23.1","covers":"part: where CCC puts the witness, not the advice for wallets and mocks","date":"2026-11-20"},"checked":{"date":"2026-11-19","verdict":"partly right","against_commit":true}},{"id":"ccc/parsing-snake-case-json-rpc-transactions-in-ccc","area":"ccc","title":"Parsing snake_case JSON-RPC transactions in CCC","lesson":"ccc.Transaction.from reads only camelCase keys, so a snake_case JSON-RPC transaction (such as the ones ckb-cli writes, with cell_deps, outputs_data and similar) has to be converted with cccA.JsonRpcTransformers.transactionTo from @ckb-ccc/core/advanced. Passing that JSON directly to Transaction.from does not read those fields.","note":"","patterns":["prefer: return cccA.JsonRpcTransformers.transactionTo(object as unknown as JsonRpcTransaction);"],"concepts":["Data encoding (molecule, hex, bigints)","Transaction building and fees"],"applies_to":[],"status":"current","evidence":"L3","first_seen":"2026-11-08","last_touched":"2026-11-08","level":"working","why":"Feeding ckb-cli style JSON straight to Transaction.from leaves cell_deps, header_deps and outputs_data unread, so the resulting CCC transaction is missing those fields and hashes or signs as a different transaction.","sources":[{"repo":"ILE-Labs/ckb-msig","hash":"eae398a368","date":"2026-11-08"}],"tests":[],"related":[],"confirmed":null,"reproduced":{"repo":"LusoCryptoLabs/ckb-lesson-tests","test":"tests/ccc/snake-case-transaction.test.mjs","commit":"27ec5fdaeb","library":"@ckb-ccc/core","version":"1.23.1","covers":"all","date":"2026-11-20"},"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"ccc/pass-a-config-object-not-a-url-string-to-ccc-clientpublictes","area":"ccc","title":"Pass a config object, not a URL string, to ccc.ClientPublicTestnet","lesson":"In @ckb-ccc/core, the ClientPublicTestnet constructor takes an options object, so a custom RPC endpoint must be given as { url: rpcUrl } rather than as a bare string argument. This commit corrects the bare string calls in a deploy script to the object form.","note":"","patterns":["prefer: const client = new ccc.ClientPublicTestnet({ url: options.rpcUrl });"],"concepts":["Network and RPC reliability"],"applies_to":[],"status":"current","evidence":"L3","first_seen":"2026-10-13","last_touched":"2026-10-13","level":"working","why":"If you pass a bare URL string, the constructor finds no url field, so the client silently falls back to the default public testnet endpoint and the --rpc or CKB_RPC_URL setting is ignored.","sources":[{"repo":"salmansarwarr/Tranfr","hash":"002aa4b73e","date":"2026-10-13"}],"tests":[{"repo":"salmansarwarr/Tranfr","hash":"002aa4b73e","files":["reference/since-cmp-ts/since_cmp.test.ts","sdk/tests/scaffold.test.ts"]}],"related":[],"confirmed":null,"reproduced":{"repo":"LusoCryptoLabs/ckb-lesson-tests","test":"tests/ccc/client-config-object.test.mjs","commit":"27ec5fdaeb","library":"@ckb-ccc/core","version":"1.23.1","covers":"all","date":"2026-11-20"},"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"ccc/persist-the-transaction-hash-before-broadcasting-it","area":"ccc","title":"Persist the transaction hash before broadcasting it","lesson":"A CKB transaction hash covers the raw transaction but not the witnesses, so after fee completion ccc tx.hash() already gives the final hash before signing. Save that hash to a durable journal before broadcasting, and assert that the hash returned by send equals it. Also assert that signing and preparation did not change the hash, so a rerun after a lost RPC reply waits for the recorded transaction instead of building and sending a duplicate.","note":"","patterns":["prefer: journal.funding=tx.hash();await save();assert.equal(await submit(frozen(tx),maker),journal.funding);"],"concepts":["Transaction building and fees","Network and RPC reliability"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-09-18","last_touched":"2026-09-18","level":"working","why":"If the hash is only recorded from the RPC reply, a crash or lost reply after broadcast leaves no record. A rerun then builds and funds a second transaction, such as another 300 CKB transfer or another order.","sources":[{"repo":"toastmanAu/openswap","hash":"4d2a21c8b7","date":"2026-09-18"}],"tests":[{"repo":"toastmanAu/openswap","hash":"4d2a21c8b7","files":["solver/test/runner.test.ts","tests/src/consensus.rs","tests/src/vectors.rs"]}],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"ccc/plain-ckb-transfer-with-a-ccc-signer","area":"ccc","title":"Plain CKB transfer with a CCC signer","lesson":"With CCC, a simple CKB transfer is built as ccc.Transaction.from({ outputs: [{ lock, capacity }] }), then transaction.completeInputsByCapacity(signer) and transaction.completeFeeBy(signer) are called before signer.sendTransaction(transaction). The recipient lock comes from ccc.Address.fromString(address, signer.client), and its .script is used as the output lock.","note":"","patterns":["prefer: await transaction.completeInputsByCapacity(signer); await transaction.completeFeeBy(signer);"],"concepts":["Transaction building and fees","Witnesses and signatures"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-10-12","last_touched":"2026-10-12","level":"basic","why":"Without completeInputsByCapacity and completeFeeBy the transaction has no inputs to fund the output and no fee, so the node rejects it.","sources":[{"repo":"officialcmg/ckb-keyway","hash":"6876f26834","date":"2026-10-12"}],"tests":[],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"ccc/re-zero-the-witness-lock-before-recomputing-the-sign-message","area":"ccc","title":"Re-zero the witness lock before recomputing the sign message with getSignHashInfo","lesson":"CCC's Transaction.getSignHashInfo hashes whatever is currently in the witness, so after a signature is filled in it no longer gives the signed message. To verify a signature (for example with ccc.recoverMessageSecp256k1), clone the tx and reset witness 0's lock to the zero placeholder of the same length that was used at signing time.","note":"","patterns":["prefer: verifyTx.setWitnessArgs(0, { lock: ccc.hexFrom(new Uint8Array(WITNESS_LOCK_LEN)) });"],"concepts":["Witnesses and signatures","Testing and devnet"],"applies_to":[],"status":"current","evidence":"L3","first_seen":"2026-10-14","last_touched":"2026-10-14","level":"working","why":"If you recompute the sign hash on the signed transaction, the hash covers the signature itself, so recovery returns the wrong public key and a valid signature looks invalid.","sources":[{"repo":"salmansarwarr/Tranfr","hash":"458f716d04","date":"2026-10-14"}],"tests":[{"repo":"salmansarwarr/Tranfr","hash":"458f716d04","files":["sdk/tests/client.test.ts"]}],"related":[],"confirmed":null,"reproduced":{"repo":"LusoCryptoLabs/ckb-lesson-tests","test":"tests/ccc/rezero-witness-before-verifying.test.mjs","commit":"27ec5fdaeb","library":"@ckb-ccc/core","version":"1.23.1","covers":"all","date":"2026-11-20"},"checked":{"date":"2026-11-19","verdict":"partly right","against_commit":true}},{"id":"ccc/registering-nervosdao-on-devnet","area":"ccc","title":"Registering NervosDao on devnet","lesson":"A CCC client for a devnet only knows the scripts you give it, and fee completion looks up KnownScript.NervosDao, so register it by hand. Take the cell dep from genesis block tx 0: find the output whose type script, hashed with Script.from({codeHash: o.type.code_hash, hashType: o.type.hash_type, args: o.type.args}).hash(), equals the DAO code hash 0x82d76d1b75fe2fd9a27dfbaa65a039221a380d76c926f378d3f81cf3e7e13f2e, and fail loudly if none is found. Register it as {codeHash, hashType: 'type', cellDeps: [{cellDep: {outPoint: {txHash: genesisTx0Hash, index: '0x' + daoIndex.toString(16)}, depType: 'code'}}]}.","note":"","patterns":[],"concepts":["Cell deps and script lookup","Testing and devnet"],"applies_to":[],"status":"current","evidence":"L1","first_seen":"2026-11-15","last_touched":"2026-11-15","level":"working","why":"Without a NervosDao entry, a devnet CCC client built with a custom scripts table has no DAO script info, even though CCC fee completion checks DAO identity on every input. The fee step then fails or relies on testnet cells that do not exist on the devnet.","sources":[{"repo":"psawyerberlin/ckb-revocable-timelock","hash":"980a65cc9e","date":"2026-11-15"},{"repo":"Akane-CN/spark-verify","hash":"b47099ccf1","date":"2026-11-02"}],"tests":[{"repo":"Akane-CN/spark-verify","hash":"b47099ccf1","files":["tests/claims-v3.test.ts","tests/cli.test.ts","tests/fixtures/claims-v3/synthetic.ts","tests/fixtures/conformance/manifests/invalid/draft5-account-out-of-range.toml","tests/fixtures/conformance/manifests/invalid/draft5-bare-amount.toml"]}],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"ccc/reserve-co-signer-witness-space-before-completefeeby-in-mult","area":"ccc","title":"Reserve co-signer witness space before completeFeeBy in multi-signer CCC transactions","lesson":"When a CCC transaction has inputs locked by several secp256k1 signers but the fee is paid by one, call tx.prepareSighashAllWitness(coSignerLock, 65, client) for each co-signer before tx.completeFeeBy(payer, feeRate). Otherwise the fee is estimated without their signature witnesses and may come out short. Each co-signer must own at least one input to have a script group to sign.","note":"","patterns":["prefer: await tx.prepareSighashAllWitness(await lockOf(s), SECP_SIGNATURE_LEN, client);"],"concepts":["Transaction building and fees","Witnesses and signatures"],"applies_to":[],"status":"current","evidence":"L3","first_seen":"2026-10-06","last_touched":"2026-10-06","level":"working","why":"completeFeeBy only prepares the payer's witness, so co-signer signatures added later grow the transaction past the size the fee was paid for, and the fee can fall short of the fee rate.","sources":[{"repo":"salmansarwarr/Kirea-finance","hash":"17fc2ee5dc","date":"2026-10-06"}],"tests":[],"related":[],"confirmed":null,"reproduced":{"repo":"LusoCryptoLabs/ckb-lesson-tests","test":"tests/ccc/cosigner-witness-before-fee.test.mjs","commit":"27ec5fdaeb","library":"@ckb-ccc/core","version":"1.23.1","covers":"all","date":"2026-11-20"},"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"ccc/sign-a-prepared-transaction-without-broadcasting-via-ccc-sig","area":"ccc","title":"Sign a prepared transaction without broadcasting via CCC signOnlyTransaction","lesson":"signer.signOnlyTransaction(tx) asks the CCC signer to sign a transaction you already completed (inputs, fee, cell deps, zero placeholder witness) without preparing or sending it. Treat the wallet as untrusted: pass it a copy, recheck the connected account after it returns, and verify the signed result against the sign hash you got from tx.getSignHashInfo(lock, client) on the prepared transaction (same tx hash, other witnesses untouched, signature recovers to the expected public key).","note":"","patterns":["prefer: const signed=await signer.signOnlyTransaction(c.Transaction.fromBytes(req.transaction));"],"concepts":["Witnesses and signatures","Transaction building and fees"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-11-09","last_touched":"2026-11-09","level":"working","why":"Without this, the wallet could switch accounts during signing or return an altered transaction, and the app would accept a signature it never checked.","sources":[{"repo":"Ticoworld/QuotaCell","hash":"13ce92ca7f","date":"2026-11-09"}],"tests":[],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"partly right","against_commit":true}},{"id":"ccc/sign-each-lock-group-with-its-own-placeholder-length-and-wit","area":"ccc","title":"Sign each lock group with its own placeholder length and witness shape","lesson":"When one key controls several lock groups in a CCC transaction, call transaction.prepareSighashAllWitness(script, len, client) for each group with the final witness lock length of that lock, then getSignHashInfo and sign that group's own digest. In KeyWay's case the length is 65 bytes for secp256k1 and 85 bytes for an Omnilock owner witness holding one 65-byte signature; write the bare signature for secp256k1 and wrap it in the OmniLockWitnessLock molecule for Omnilock. A custom lock with its own witness layout needs its own length the same way.","note":"","patterns":["prefer: await transaction.prepareSighashAllWitness(script, witnessLockLength(kind), client);"],"concepts":["Witnesses and signatures","Transaction building and fees"],"applies_to":[],"status":"current","evidence":"L1","first_seen":"2026-10-23","last_touched":"2026-10-23","level":"working","why":"If a group's digest is computed over a placeholder of the wrong length, or one group's signature is reused for another lock, the witness the lock script hashes on chain differs from what was signed and verification fails.","sources":[{"repo":"officialcmg/ckb-keyway","hash":"1b402ba210","date":"2026-10-23"},{"repo":"salmansarwarr/Tranfr","hash":"13d58fa698","date":"2026-10-14"}],"tests":[{"repo":"officialcmg/ckb-keyway","hash":"1b402ba210","files":["tests/general-signing-postgres.test.ts","tests/transaction-policy.test.ts"]}],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"ccc/split-ccc-signtransaction-from-sendtransaction-to-retry-on-c","area":"ccc","title":"Split CCC signTransaction from sendTransaction to retry on consumed inputs","lesson":"When several clients race to spend the same shared cell, sign with signer.signTransaction and send with signer.client.sendTransaction as two steps instead of signer.sendTransaction. The dead-input rejection only appears at broadcast, so wrapping just the send in the retry catch lets you tell contention (re-read the live cell, rebuild, sign again) from a wallet refusal or a script verification failure, which must not be retried. Cap the attempts, because each retry costs another signature.","note":"","patterns":["prefer: return await signer.client.sendTransaction(signedTx);"],"concepts":["Transaction building and fees","Network and RPC reliability"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-09-23","last_touched":"2026-09-23","level":"working","why":"With a single sign-and-send call, a lost race for the shared cell cannot be cleanly separated from a wallet refusal. The retry loop then cannot rebuild against the new live cell.","sources":[{"repo":"toastmanAu/daowow","hash":"862ecf4452","date":"2026-09-23"}],"tests":[],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"partly right","against_commit":true}},{"id":"ccc/transaction-size-for-fee-rate-is-serialized-bytes-plus-4","area":"ccc","title":"Transaction size for fee rate is serialized bytes plus 4","lesson":"To get a transaction's size as the node counts it, take the molecule serialized size of the full transaction with witnesses (for example ccc.Transaction.from(...).toBytes().length) and add 4 bytes for its offset in the block. A size-based fee rate is fee * 1000 / size in shannons per 1000 bytes; the node's pool actually uses weight, the larger of size and cycles scaled, so it can be higher for cycle-heavy transactions. get_transaction returns snake_case JSON, so map the fields (code_hash to codeHash, dep_type dep_group to depGroup) before passing it to ccc.Transaction.from.","note":"","patterns":["prefer: }).toBytes().length + 4;"],"concepts":["Transaction building and fees","Data encoding (molecule, hex, bigints)"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-10-17","last_touched":"2026-10-17","level":"working","why":"Without the extra 4 bytes, or if witnesses are left out, the computed size and fee rate do not match what the node counts, so the displayed or chosen fee rate is off.","sources":[{"repo":"wildanrhmn/ckb-devnet-explorer","hash":"981f619891","date":"2026-10-17"}],"tests":[],"related":[],"confirmed":null,"reproduced":{"repo":"LusoCryptoLabs/ckb-lesson-tests","test":"tests/ccc/transaction-size.test.mjs","commit":"27ec5fdaeb","library":"@ckb-ccc/core","version":"1.23.1","covers":"part: the size rule as CCC applies it, not the node count nor weight by cycles","date":"2026-11-20"},"checked":{"date":"2026-11-19","verdict":"partly right","against_commit":true}},{"id":"ccc/use-findcellsonchain-for-shared-live-state","area":"ccc","title":"Use findCellsOnChain for shared live state","lesson":"client.findCells merges results from the client's local cache, which can still hold outputs of your own earlier transactions after other parties spent them on chain. When you need the true live cell set, such as state shared with other actors or runners, use client.findCellsOnChain.","note":"Medium confidence.","patterns":["client.findCells({script, scriptType, ...}) used to read shared on-chain state → client.findCellsOnChain({...})"],"concepts":["Indexer queries and cell collection"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-11-15","last_touched":"2026-11-15","level":"working","why":"With findCells, a builder can pick up the signer's own earlier outputs that other parties already spent on chain, so it builds transactions over stale cells next to the live ones and they fail or misread state.","sources":[{"repo":"psawyerberlin/ckb-revocable-timelock","hash":"6deabcd3a7","date":"2026-11-15"}],"tests":[],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"ccc/use-findcellsonchain-not-findcells-for-block-range-queries-i","area":"ccc","title":"Use findCellsOnChain, not findCells, for block range queries in CCC","lesson":"In CCC, client.findCells merges the client's local cache of cells it has sent, and its search key takes no blockRange filter. To list live cells created in a block range, call client.findCellsOnChain with filter.blockRange set to [from, to), where the end is exclusive. This queries the indexer directly.","note":"","patterns":["prefer: client.findCellsOnChain({ ...search(from, to), withData: true }, 'asc', 100)"],"concepts":["Indexer queries and cell collection"],"applies_to":[],"status":"current","evidence":"L2","first_seen":"2026-09-25","last_touched":"2026-09-25","level":"working","why":"With findCells, cells from the client's own sent transactions can show up in a block range query even though they were not created in that range, which corrupts an incremental view built from block ranges.","sources":[{"repo":"LusoCryptoLabs/cells-resolver","hash":"50fb20d0f3","date":"2026-09-25"}],"tests":[{"repo":"LusoCryptoLabs/cells-resolver","hash":"50fb20d0f3","files":["test/livenames.test.ts"]}],"related":[],"confirmed":{"by":"LusoCryptoLabs","role":"owner","date":"2026-11-19"},"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"ccc/use-getcelllive-not-getcell-when-a-cell-s-current-state-matt","area":"ccc","title":"Use getCellLive, not getCell, when a cell's current state matters in CCC","lesson":"In CCC, client.getCell(outPoint) can also return a cell that has already been spent, so status checks built on it report claimed or reclaimed cells as still active. Use client.getCellLive(outPoint, true) and treat an undefined result as \"not found or already spent\".","note":"","patterns":["prefer: const cell = await this.client.getCellLive(cellOutPoint, true);"],"concepts":["Indexer queries and cell collection"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-10-20","last_touched":"2026-10-20","level":"working","why":"A status check built on getCell reports a cell that was already claimed or reclaimed as still active, because getCell also returns spent cells.","sources":[{"repo":"salmansarwarr/Tranfr","hash":"a43866c2de","date":"2026-10-20"}],"tests":[{"repo":"salmansarwarr/Tranfr","hash":"a43866c2de","files":["sdk/tests/client.test.ts"]}],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"ccc/use-jsonrpctransformers-transactionfrom-to-serialize-ccc-tra","area":"ccc","title":"Use JsonRpcTransformers.transactionFrom to serialize CCC transactions for CKB/Fiber RPC","lesson":"Serializing a ccc.Transaction with ccc.stringify keeps cached input fields (cellOutput, outputData) that a native RPC such as Fiber submitSignedFundingTx does not expect. JsonRpcTransformers.transactionFrom from @ckb-ccc/core/advanced emits snake_case hex with inputs containing only previous_output and since, while keeping the tx hash and witnesses unchanged, as the commit's tests check.","note":"","patterns":["prefer: return JsonRpcTransformers.transactionFrom(transactionLike as ccc.TransactionLike);"],"concepts":["Data encoding (molecule, hex, bigints)","Transaction building and fees"],"applies_to":[],"status":"current","evidence":"L3","first_seen":"2026-09-28","last_touched":"2026-09-28","level":"working","why":"Serializing with ccc.stringify sends cached input metadata (cellOutput, outputData) in a non-RPC shape to the native Fiber node's submitSignedFundingTx. The commit's tests show the RPC form must carry only previous_output and since per input, with the hash and witnesses intact.","sources":[{"repo":"officialcmg/ckb-keyway","hash":"86b9443494","date":"2026-09-28"}],"tests":[{"repo":"officialcmg/ckb-keyway","hash":"86b9443494","files":["tests/managed-node.test.ts","tests/remote-ckb-signer.test.ts"]}],"related":[],"confirmed":null,"reproduced":{"repo":"LusoCryptoLabs/ckb-lesson-tests","test":"tests/ccc/serialize-for-rpc.test.mjs","commit":"27ec5fdaeb","library":"@ckb-ccc/core","version":"1.23.1","covers":"all","date":"2026-11-20"},"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"ccc/verifying-an-immutable-data1-script-code-cell-after-deployme","area":"ccc","title":"Verifying an immutable data1 script code cell after deployment","lesson":"For a script referenced by hashType 'data1', put the binary in a cell whose lock is the always fail lock (codeHash 32 zero bytes, hashType data1, args 0x, which no code cell can match) and with no type, so the cell can never be spent and the cell dep stays live; the capacity is locked forever. After sending, read the cell with client.getCellLive(outPoint, true) and assert that ccc.hashCkb(outputData) equals the pinned code hash, that the lock equals the always fail lock and that there is no type, ideally on more than one endpoint. The data1 code hash is already pinned by the binary's content; the immutable lock is what keeps the cell available.","note":"","patterns":["prefer: assert(code&&ccc.hashCkb(code.outputData)===LOCK_V2.codeHash ...); assert(code.cellOutput.lock.eq(IMMUTABLE_LOCK)&&!code.cellOutput.type,`Code cell is not immutable on ${url}`);"],"concepts":["Cell deps and script lookup","Type ID and upgrades"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-10-29","last_touched":"2026-10-29","level":"working","why":"If the code cell had a spendable lock, the deployer could consume it, and every transaction using that out point as a cell dep would fail. Without the post-deployment check, a wrong binary, lock or type would be recorded in the manifest unnoticed.","sources":[{"repo":"toastmanAu/openswap","hash":"e1f617c577","date":"2026-10-29"}],"tests":[{"repo":"toastmanAu/openswap","hash":"e1f617c577","files":["frontend/test/fixtures.ts","sdk/test/v2-sdk.test.ts"]}],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"partly right","against_commit":true}},{"id":"ccc/wallet-discovery-with-signerscontroller","area":"ccc","title":"Wallet discovery with SignersController","lesson":"To support every CCC wallet without the @ckb-ccc/connector UI, call `new ccc.SignersController().refresh(client, callback, {name, icon})`. Keep the callback registered and update the picker, because it fires again as EIP-6963 wallets announce themselves. Treat signers that are `instanceof ccc.SignerDummy` as download links, not connectable wallets.","note":"Medium confidence.","patterns":[],"concepts":["Witnesses and signatures","Login and authorization"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-11-12","last_touched":"2026-11-12","level":"working","why":"Without this, wallets that announce late never reach the picker, or overlapping refreshes overwrite the list with stale results. Download links can also be offered or restored as if they were connected wallets.","sources":[{"repo":"toastmanAu/daowow","hash":"d49df9dc97","date":"2026-11-12"}],"tests":[{"repo":"toastmanAu/daowow","hash":"d49df9dc97","files":["apps/web/test/build-site.test.js","apps/web/test/model-copy.test.js","apps/web/test/refund-tx.test.js","apps/web/test/vendor.test.js","apps/web/test/wallet-list.test.js"]}],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"partly right","against_commit":true}},{"id":"light-client/give-light-clients-the-committing-block-of-a-cell-not-just-i","area":"light-client","title":"Give light clients the committing block of a cell, not just its outpoint","lesson":"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.","note":"","patterns":["prefer: blockNumber: a.blockNumber ?? null, blockHash: a.blockHash ?? null,"],"concepts":["Indexer queries and cell collection","Network and RPC reliability"],"applies_to":[],"status":"current","evidence":"L2","first_seen":"2026-09-24","last_touched":"2026-09-24","level":"working","why":"Without the committing block, a script-watching light client has to scan from genesis to find the cell and notice when it is spent.","sources":[{"repo":"LusoCryptoLabs/cells-resolver","hash":"b5a1d6e3da","date":"2026-09-24"}],"tests":[{"repo":"LusoCryptoLabs/cells-resolver","hash":"b5a1d6e3da","files":["test/proof.test.ts"]}],"related":[],"confirmed":{"by":"LusoCryptoLabs","role":"owner","date":"2026-11-19"},"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"light-client/light-client-scan-absence-does-not-prove-a-dao-withdrawing-c","area":"light-client","title":"Light client scan absence does not prove a DAO withdrawing cell was spent","lesson":"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.","note":"","patterns":["prefer: chainVerdict == DaoUnlockChainVerdict.COMMITTED -> DaoUnlockMarkerState.CONFIRMED"],"concepts":["Indexer queries and cell collection","Other"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-09-30","last_touched":"2026-10-09","level":"working","why":"Retiring on absence alone makes a still-unspent DAO position vanish from the screen and the balance, and the unlock preflight then insists it was already claimed, with no way back.","sources":[{"repo":"RaheemJnr/pocket-node","hash":"eacbe89f26","date":"2026-09-30"},{"repo":"RaheemJnr/pocket-node","hash":"ee61d42075","date":"2026-10-09"}],"tests":[{"repo":"RaheemJnr/pocket-node","hash":"eacbe89f26","files":["android/app/src/test/java/com/rjnr/pocketnode/data/database/WalkingMigrationTest.kt","android/app/src/test/java/com/rjnr/pocketnode/data/gateway/DaoCellRetirementTest.kt","android/app/src/test/java/com/rjnr/pocketnode/data/gateway/DaoSyncManagerTest.kt","android/app/src/test/java/com/rjnr/pocketnode/data/gateway/GatewayRepositoryDaoUnlockTest.kt","android/app/src/test/java/com/rjnr/pocketnode/data/wallet/WalletRepositoryTest.kt"]},{"repo":"RaheemJnr/pocket-node","hash":"ee61d42075","files":["android/app/src/test/java/com/rjnr/pocketnode/data/gateway/AndroidLightClientApiTest.kt","android/app/src/test/java/com/rjnr/pocketnode/data/gateway/CandidateRegistrationRecordingTest.kt","android/app/src/test/java/com/rjnr/pocketnode/data/gateway/CandidateSelectionTest.kt","android/app/src/test/java/com/rjnr/pocketnode/data/gateway/DaoGatewayUnlockTest.kt","android/app/src/test/java/com/rjnr/pocketnode/data/gateway/GatewayRepositoryResyncStrategyTest.kt"]}],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"light-client/light-client-set-scripts-all-replaces-the-whole-registered-s","area":"light-client","title":"Light client set_scripts \"all\" replaces the whole registered script set","lesson":"The CKB light client's set_scripts with the all command replaces every registered script, so a call carrying only one wallet's lock script unregisters all other wallets. When several scripts must stay tracked, either pass the full set with each script's own start block, or use the partial command to update only the changed script. If registrations can race, serialise them so a stale full set cannot overwrite a newer one.","note":"","patterns":["avoid: setScriptsAndRecord(scriptStatuses + ..., listOf(activeWalletId) + ..., LightClientNative.CMD_SET_SCRIPTS_ALL)"],"concepts":["Indexer queries and cell collection","Network and RPC reliability"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-09-30","last_touched":"2026-09-30","level":"working","why":"Re-registering one wallet with the all command after a sync mode change silently stopped syncing every other wallet in the app.","sources":[{"repo":"RaheemJnr/pocket-node","hash":"1f1fed29fc","date":"2026-09-30"}],"tests":[{"repo":"RaheemJnr/pocket-node","hash":"1f1fed29fc","files":["android/app/src/test/java/com/rjnr/pocketnode/data/gateway/GatewayRepositoryResyncStrategyTest.kt","android/app/src/test/java/com/rjnr/pocketnode/data/gateway/TestGatewayRepository.kt","android/app/src/test/java/com/rjnr/pocketnode/data/wallet/WalletRepositoryTest.kt","android/app/src/test/java/com/rjnr/pocketnode/ui/screens/onboarding/MnemonicImportViewModelSyncTest.kt","android/app/src/test/java/com/rjnr/pocketnode/ui/screens/wallet/AddWalletViewModelImportSyncTest.kt"]}],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"light-client/light-client-still-reports-a-removed-script-until-the-new-sc","area":"light-client","title":"Light client still reports a removed script until the new script set lands","lesson":"The CKB light client keeps reporting a script, with its block number, from get_scripts until you register a new script set that leaves it out. A sync poll that runs between your local delete and that set_scripts call will still see the removed script. Do not let that poll recreate local per script progress for an owner that no longer exists, and clear that progress again once the new set is registered while polling is excluded.","note":"","patterns":["if (onlyIfWalletExists && walletDao.getById(walletId) == null) return"],"concepts":["Indexer queries and cell collection","Network and RPC reliability"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-10-11","last_touched":"2026-10-11","level":"working","why":"Without the guard, a poll tick in that window writes back the deleted wallet's sync progress row that the delete had just removed, leaving an orphaned row.","sources":[{"repo":"RaheemJnr/pocket-node","hash":"3b6e0d539f","date":"2026-10-11"}],"tests":[{"repo":"RaheemJnr/pocket-node","hash":"3b6e0d539f","files":["android/app/src/test/java/com/rjnr/pocketnode/data/gateway/RegistrationLockTest.kt","android/app/src/test/java/com/rjnr/pocketnode/data/wallet/WalletRepositoryTest.kt","android/app/src/test/java/com/rjnr/pocketnode/ui/components/SyncSheetActionsLayoutTest.kt","android/app/src/test/java/com/rjnr/pocketnode/ui/screens/home/HomeViewModelWalletChangeTest.kt","android/app/src/test/java/com/rjnr/pocketnode/ui/screens/wallet/AddWalletViewModelCancelAddTest.kt"]}],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"light-client/light-client-sync-progress-poll-racing-set-scripts","area":"light-client","title":"Light client sync progress poll racing set_scripts","lesson":"If an app saves per-script sync progress from the light client's get_scripts while another path calls set_scripts to reset or re-register scripts, a get_scripts result read before the set landed can overwrite the reset progress. Do the get_scripts read and the progress write under the same lock that guards set_scripts, and have the poll use tryLock and skip that tick while a registration is in flight, so it never queues behind it. Pocket Node does this in SyncCoordinator.tryWithRegistrationLock.","note":"","patterns":[],"concepts":["Indexer queries and cell collection","Network and RPC reliability"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-10-06","last_touched":"2026-10-06","level":"advanced","why":"A poll tick that read get_scripts before a resync's set_scripts landed writes the old block number back, so the user's reset is silently undone and the wallet resumes from stale progress.","sources":[{"repo":"RaheemJnr/pocket-node","hash":"4ba8f89316","date":"2026-10-06"}],"tests":[{"repo":"RaheemJnr/pocket-node","hash":"4ba8f89316","files":["android/app/src/test/java/com/rjnr/pocketnode/data/gateway/GatewayRepositoryResyncStrategyTest.kt","android/app/src/test/java/com/rjnr/pocketnode/data/gateway/RegistrationLockTest.kt","android/app/src/test/java/com/rjnr/pocketnode/data/gateway/TestGatewayRepository.kt"]}],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"partly right","against_commit":true}},{"id":"node/a-rejected-or-unknown-get-transaction-status-does-not-make-a","area":"node","title":"A rejected or unknown get_transaction status does not make a signed transaction dead","lesson":"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.","note":"","patterns":["requireRecovery(poolInput,'not a pool transaction; nothing guarantees a later conflict');"],"concepts":["Transaction building and fees","Network and RPC reliability"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-10-26","last_touched":"2026-10-26","level":"working","why":"If inputs are freed on a single node's rejected or unknown report, a new action can be built that does not conflict with the old signed transaction, and both may commit if someone rebroadcasts the old bytes while its inputs are still live.","sources":[{"repo":"toastmanAu/openswap","hash":"9c2f186115","date":"2026-10-26"}],"tests":[{"repo":"toastmanAu/openswap","hash":"9c2f186115","files":["frontend/test/pools.spec.ts","pool-sdk/test/recovery.test.ts"]}],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"node/advancing-devnet-median-time-for-time-lock-tests","area":"node","title":"Advancing devnet median time for time-lock tests","lesson":"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.","note":"","patterns":["t = get_block_template(null,null,null); t.current_time = hex(tipMs + step); generate_block_with_template(t); loop until median_time >= target"],"concepts":["Testing and devnet","Since and time locks"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-11-15","last_touched":"2026-11-15","level":"working","why":"A single future-dated block barely moves the median of recent block timestamps, so median_time stays below the target and time-locked spends stay immature, which fails the scenario's 'median time did not reach the target' check.","sources":[{"repo":"psawyerberlin/ckb-revocable-timelock","hash":"d753844282","date":"2026-11-15"}],"tests":[],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"node/check-chain-wide-script-users-before-consuming-a-deployed-co","area":"node","title":"Check chain-wide script users before consuming a deployed code cell","lesson":"Before consuming a deployed code cell, call indexer get_cells across the whole chain with script_search_mode \"prefix\" and args \"0x\", once as lock and once as type. Query the cell's data hash with hash_type data, data1 and data2, and for a Type ID cell also its type script hash with hash_type type. Zero results only means no live cell uses the binary right now. Consuming the cell is irreversible, and a Type ID identity cannot be recreated, so treat unused Type ID cells with extra caution.","note":"","patterns":["prefer: script: { code_hash: codeHash, hash_type: hashType, args: \"0x\" }, script_type: scriptType, script_search_mode: \"prefix\""],"concepts":["Cell deps and script lookup","Indexer queries and cell collection","Type ID and upgrades"],"applies_to":[],"status":"current","evidence":"L2","first_seen":"2026-09-18","last_touched":"2026-10-10","level":"working","why":"If you only check your own wallet's cells, you can consume a binary that someone else's live cells still depend on, and those cells become unspendable. Consuming a Type ID cell destroys an identity that cannot be recreated.","sources":[{"repo":"toastmanAu/daowow","hash":"2be89c08e1","date":"2026-09-18"},{"repo":"LusoCryptoLabs/ckb-pulse","hash":"d62e053e43","date":"2026-10-10"}],"tests":[],"related":[],"confirmed":{"by":"LusoCryptoLabs","role":"owner","date":"2026-11-19"},"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"node/check-indexer-lag-with-get-indexer-tip-before-signing","area":"node","title":"Check indexer lag with get_indexer_tip before signing","lesson":"The built-in CKB indexer can trail the chain tip, so cells it returns may be stale. Before signing, compare the block_number from get_indexer_tip with the height from get_tip_header, show a notice when the gap is large, and refuse to sign while it is. daowow flags the indexer as lagging when it is more than 8 blocks behind, and its entry, refund and claim guards refuse to proceed in that state.","note":"","patterns":["prefer: readIndexerTip: async (r) => BigInt((await r.call(\"get_indexer_tip\", [])).block_number),"],"concepts":["Indexer queries and cell collection","Network and RPC reliability","Transaction building and fees"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-11-10","last_touched":"2026-11-10","level":"working","why":"Without this check, a transaction can be built and signed on stale indexer cells that may already be spent or changed, so the user signs against a picture of the chain that is no longer true.","sources":[{"repo":"toastmanAu/daowow","hash":"e7977d20b6","date":"2026-11-10"}],"tests":[{"repo":"toastmanAu/daowow","hash":"e7977d20b6","files":["apps/web/test/app-shell.test.js","apps/web/test/dao-yield.test.js","apps/web/test/model-draw-script.test.js","apps/web/test/model-entry-guard.test.js","apps/web/test/model-refund-guard.test.js"]}],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"partly right","against_commit":true}},{"id":"node/check-original-tx-unknown-and-input-live-on-independent-node","area":"node","title":"Check original tx unknown and input live on independent nodes before same input cancellation","lesson":"Before signing a same-input cancellation for a deployment whose broadcast outcome is unknown, check on two separate RPC endpoints that get_transaction for the original hash returns status 'unknown' and that get_live_cell for the shared input returns 'live', and fail closed if either endpoint errors or times out. Repeat the check before sending. 'unknown' only means the nodes have not seen the tx yet, so the cancellation is a race: if the original is relayed and committed first, the cancellation fails.","note":"","patterns":["prefer: assert.equal((await rpc('get_transaction',[ORIGINAL]))?.tx_status?.status,'unknown','Original deployment is not unknown'); const live=await rpc('get_live_cell',[INPUT,true]); assert.equal(live.status,'live');"],"concepts":["Network and RPC reliability","Transaction building and fees"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-11-09","last_touched":"2026-11-09","level":"working","why":"Without the check you may sign and send a cancellation after the original deployment is already pending or committed, or trust one node's partial view, so the cancellation fails or you misjudge which transaction actually landed.","sources":[{"repo":"Ticoworld/QuotaCell","hash":"39ef43622a","date":"2026-11-09"}],"tests":[],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"node/ckb-log-subscription-notifications-may-carry-params-result-a","area":"node","title":"CKB log subscription notifications may carry params.result as a JSON string","lesson":"When subscribing to the CKB node's \"log\" topic over the TCP subscription RPC, the notification's params.result can be a JSON-encoded string of the log entry (message, level, target, date) rather than an object. Parse it with JSON.parse when it is a string, and skip malformed payloads instead of stopping the stream; otherwise script debug output (target ckb_script::verify) is silently dropped.","note":"","patterns":["prefer: if (typeof result === 'string') { try { result = JSON.parse(result); } catch { return null; } }"],"concepts":["Network and RPC reliability","Testing and devnet"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-11-09","last_touched":"2026-11-09","level":"working","why":"A client that only accepts an object in params.result discards every log notification CKB sends as a JSON string, so script debug output from ckb_script::verify never reaches the developer.","sources":[{"repo":"ckb-devrel/offckb","hash":"d1318f6666","date":"2026-11-09"}],"tests":[{"repo":"ckb-devrel/offckb","hash":"d1318f6666","files":["tests/cli-startup.test.ts","tests/log-subscription.test.ts"]}],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"node/computing-a-transaction-s-molecule-packed-size-from-rpc-json","area":"node","title":"Computing a transaction's molecule packed size from RPC JSON","lesson":"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.","note":"","patterns":["prefer: return 12 + raw_size + dynamic([4 + len(raw(v)) for v in tx['witnesses']])"],"concepts":["Data encoding (molecule, hex, bigints)","Transaction building and fees"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-10-10","last_touched":"2026-10-10","level":"advanced","why":"Without the exact molecule layout, a tool cannot confirm the node's reported packed transaction size from RPC JSON. The cross-check against the measured node wire bytes would then fail or be skipped.","sources":[{"repo":"Tactus-Labs/tactus-o1","hash":"d784f0d81d","date":"2026-10-10"}],"tests":[],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"node/computing-cell-confirmations-from-get-transaction-block-hash","area":"node","title":"Computing cell confirmations from get_transaction block_hash and tip header","lesson":"To get a cell's confirmation count over raw CKB JSON-RPC, read tx_status.block_hash from get_transaction, look up its number with get_header, then compute tip − included + 1 using get_tip_header; treat a missing block_hash as 0 confirmations. This commit's helper also retries get_transaction without the \"0x2\" verbosity param if the node rejects it, and treats get_live_cell as live only when status === \"live\".","note":"","patterns":["prefer: confirmations: tip >= included ? Number(tip - included + 1n) : 0,"],"concepts":["Network and RPC reliability","Indexer queries and cell collection"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-09-22","last_touched":"2026-09-22","level":"working","why":"Without a confirmation count, a verifier that enforces a minimum confirmation threshold (here MIN_CAPABILITY_CONFIRMATIONS) can neither apply it nor report finality metadata for a just-included or pending capability cell.","sources":[{"repo":"tydeptrai21042004/ckb-skill","hash":"7f689044e0","date":"2026-09-22"}],"tests":[{"repo":"tydeptrai21042004/ckb-skill","hash":"7f689044e0","files":["contracts/capability-type/tests/contract.rs","tests/funding-phase1-hardening.test.mjs","tests/week9-portable-rights.test.mjs"]}],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"partly right","against_commit":true}},{"id":"node/confirm-a-committed-transaction-is-on-the-canonical-chain-vi","area":"node","title":"Confirm a committed transaction is on the canonical chain via get_header and get_block_hash","lesson":"Before recording a transaction as committed, you can cross-check get_transaction's tx_status.block_hash. Call get_header on that hash and require get_block_hash(header.number) to return the same hash. If the header is missing or the hashes differ, keep the transaction marked uncertain and reconcile it later rather than building new transactions on its outputs.","note":"","patterns":["prefer: const header=await rpc('get_header',[tx.tx_status.block_hash]);return !!header && await rpc('get_block_hash',[header.number])===header.hash;"],"concepts":["Network and RPC reliability"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-11-05","last_touched":"2026-11-05","level":"working","why":"Without the cross-check, the app may record a transaction as settled and build later state on its outputs even if the block was reorged out between RPC reads.","sources":[{"repo":"Ticoworld/QuotaCell","hash":"2e36bf2681","date":"2026-11-05"}],"tests":[],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"node/conflict-an-orphaned-transaction-s-input-on-the-winning-bran","area":"node","title":"Conflict an orphaned transaction's input on the winning branch when testing a reorg rollback","lesson":"In a CKB devnet reorg test, transactions from detached blocks can return to the txpool and be committed again on the winning branch, which hides the rollback you want to observe. Have the winning branch spend one input of the orphaned transaction, such as its fee input, before the branches reconnect. Resubmitting the old transaction is then rejected with TransactionFailedToResolve (-301), and you must rebuild it with fresh funding.","note":"","patterns":[],"concepts":["Testing and devnet","Indexer queries and cell collection"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-10-10","last_touched":"2026-10-10","level":"advanced","why":"Without a conflicting spend, the orphaned transaction can be recommitted through the txpool after the reorg, so the test cannot show the rolled-back state.","sources":[{"repo":"Tactus-Labs/tactus-o1","hash":"fa56a45520","date":"2026-10-10"}],"tests":[],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"node/decoding-the-packed-epoch-field-number-index-length","area":"node","title":"Decoding the packed epoch field (number, index, length)","lesson":"A CKB header epoch field packs the epoch number in the low 24 bits, the index in the next 16 bits (shift 24) and the epoch length in the next 16 bits (shift 40). When estimating time to a target epoch from the tip, subtract the fraction already spent (index * epoch duration / length) and guard against length 0 to avoid division by zero.","note":"","patterns":["prefer: number: v & 0xffffffn, index: (v >> 24n) & 0xffffn, length: (v >> 40n) & 0xffffn,"],"concepts":["Since and time locks","Data encoding (molecule, hex, bigints)"],"applies_to":[],"status":"current","evidence":"L1","first_seen":"2026-11-10","last_touched":"2026-11-10","level":"working","why":"Reading the raw epoch hex as a number, or masking it wrongly, gives nonsense epoch numbers for window checks. Ignoring the index fraction makes time-to-epoch estimates off by up to a whole epoch, about four hours.","sources":[{"repo":"toastmanAu/daowow","hash":"ba4d1d0c57","date":"2026-11-10"},{"repo":"toastmanAu/ckb-watch-visualiser","hash":"712a503f55","date":"2026-10-24"},{"repo":"toastmanAu/daowow","hash":"9fc8826630","date":"2026-10-13"}],"tests":[{"repo":"toastmanAu/daowow","hash":"ba4d1d0c57","files":["apps/web/test/model-time.test.js"]},{"repo":"toastmanAu/daowow","hash":"9fc8826630","files":["apps/web/test/round-rules.test.js"]}],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"node/dry-run-a-transaction-with-test-tx-pool-accept-before-send-t","area":"node","title":"Dry run a transaction with test_tx_pool_accept before send_transaction","lesson":"The CKB node RPC test_tx_pool_accept takes the same params as send_transaction (the snake_case tx JSON without its hash, plus an outputs validator such as \"passthrough\"). It returns the cycles and fee the pool would accept without broadcasting, so a tool can check a pasted transaction before sending it for real.","note":"","patterns":["prefer: rpc<{ cycles: string; fee: string }>(this.url, \"test_tx_pool_accept\", [body, \"passthrough\"])"],"concepts":["Transaction building and fees","Network and RPC reliability"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-10-30","last_touched":"2026-10-30","level":"working","why":"Without a dry run, the only way to learn a pasted transaction's verification result, cycles and fee is to broadcast it for real, which cannot be undone once it is accepted.","sources":[{"repo":"wildanrhmn/ckb-devnet-explorer","hash":"60b317b191","date":"2026-10-30"}],"tests":[],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"node/filter-prefix-get-cells-results-by-data-length-before-decodi","area":"node","title":"Filter prefix get_cells results by data length before decoding","lesson":"A get_cells query with script_search_mode \"prefix\" and args \"0x\" returns every live cell whose script has that code hash and hash_type, whatever its args, so it can include cells of the same script with a different data layout (for example a script that owns both a state cell and a ledger cell). Check output_data length, or catch the decode error, and skip the cell before calling a strict decoder. Otherwise one unexpected cell throws and the whole result list is lost.","note":"","patterns":["prefer: if (data.length !== ROUND_CONFIG_SIZE) continue; // not a round config cell"],"concepts":["Indexer queries and cell collection","Data encoding (molecule, hex, bigints)"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-09-18","last_touched":"2026-09-18","level":"working","why":"Without the length check one cell with a different data length makes the strict decoder throw, and the page shows no rounds at all instead of the rounds that exist.","sources":[{"repo":"toastmanAu/daowow","hash":"c76f63c28f","date":"2026-09-18"}],"tests":[{"repo":"toastmanAu/daowow","hash":"c76f63c28f","files":["apps/web/test/discovery.test.js"]}],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"node/filtering-get-cells-for-plain-typeless-empty-funding-cells","area":"node","title":"Filtering get_cells for plain, typeless, empty funding cells","lesson":"To collect plain funding cells of a lock with the indexer get_cells (or get_cells_capacity) RPC, search with script_type \"lock\" and add filter output_data_len_range [\"0x0\",\"0x1\"] and script_len_range [\"0x0\",\"0x1\"]. Ranges are half-open [start, end), so this keeps only cells with empty data, and since the search is by lock, script_len_range applies to the type script, so only cells with no type script come back. Sorting by capacity on the client only sees the page returned (limit), so page through the results if the lock may own more cells than the limit.","note":"","patterns":["prefer: filter=dict(output_data_len_range=[\"0x0\", \"0x1\"], script_len_range=[\"0x0\", \"0x1\"])"],"concepts":["Indexer queries and cell collection"],"applies_to":[],"status":"current","evidence":"L1","first_seen":"2026-11-05","last_touched":"2026-11-05","level":"working","why":"Without the filter, typed or data-carrying cells such as DAO deposits are counted as ordinary balance or picked as funding inputs, which breaks the balance and the transaction built from them.","sources":[{"repo":"wamimi/noir-ckb-verifier","hash":"3944b888b3","date":"2026-11-05"},{"repo":"poshboytl/omavote","hash":"9daae80659","date":"2026-10-08"}],"tests":[{"repo":"wamimi/noir-ckb-verifier","hash":"3944b888b3","files":["scripts/tests/test_try_private_tally.py"]}],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"partly right","against_commit":true}},{"id":"node/finding-cells-of-a-ckb-js-vm-js-contract-needs-a-second-inde","area":"node","title":"Finding cells of a ckb_js_vm JS contract needs a second indexer prefix search","lesson":"A cell that runs a JS contract carries the ckb_js_vm script as its lock or type. Its args are 2 flag bytes, then the contract's 32 byte code hash, then its hash type byte (data 0, type 1, data1 2, data2 4). A get_cells prefix search on the contract's own code_hash finds none of these cells, so also run a prefix search on the ckb_js_vm script with args set to flags plus code hash plus hash type byte, and merge the results. With 0x0000 as the flags, that search only matches cells whose flags are zero.","note":"","patterns":["prefer: prefixes.push({ code_hash: vm.codeHash, hash_type: vm.hashType, args: \"0x0000\" + s.codeHash.slice(2) + Number(byte).toString(16).padStart(2, \"0\") });"],"concepts":["Indexer queries and cell collection","Data encoding (molecule, hex, bigints)"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-10-25","last_touched":"2026-10-25","level":"working","why":"Without the second search, an explorer or indexer query reports zero live cells for every JS contract, even when many exist.","sources":[{"repo":"wildanrhmn/ckb-devnet-explorer","hash":"bdc14d05bc","date":"2026-10-25"}],"tests":[],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"node/get-consensus-dao-type-hash-is-the-dao-code-hash-not-the-dao","area":"node","title":"get_consensus dao_type_hash is the DAO code hash, not the DAO type script hash","lesson":"The dao_type_hash field returned by the get_consensus RPC is the native Nervos DAO code hash (used with hash_type type, args 0x). A contract that checks deposits with load_cell_type_hash needs the hash of the whole script, ccc Script{codeHash: dao_type_hash, hashType: \"type\", args: \"0x\"}.hash() (0xcc77c4de... on testnet); committing the raw dao_type_hash makes every deposit fail the check.","note":"","patterns":["prefer: const nativeDao = ccc.Script.from({ codeHash: (await rpc(\"get_consensus\", [])).dao_type_hash, hashType: \"type\", args: \"0x\" }); const daoTypeHash = nativeDao.hash();"],"concepts":["Cell deps and script lookup","Data encoding (molecule, hex, bigints)"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-10-05","last_touched":"2026-11-10","level":"working","why":"If a config pins the raw code hash, no deposit's type script hashes to it, so the node rejects every aggregate with -28 on Inputs[0].Type and the round can never aggregate; its entries have to be refunded after the deadline.","sources":[{"repo":"toastmanAu/daowow","hash":"0c8b802056","date":"2026-10-05"},{"repo":"toastmanAu/daowow","hash":"2278a835da","date":"2026-11-10"}],"tests":[{"repo":"toastmanAu/daowow","hash":"0c8b802056","files":["apps/web/test/aggregate-tx.test.js","apps/web/test/lifecycle-rules.test.js"]},{"repo":"toastmanAu/daowow","hash":"2278a835da","files":["apps/web/test/app-shell.test.js","apps/web/test/entropy-derive.test.js","apps/web/test/model-entry-guard.test.js","apps/web/test/model-refund-guard.test.js","apps/web/test/model-route.test.js"]}],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"node/get-live-cell-may-return-unknown-rather-than-dead-for-a-spen","area":"node","title":"get_live_cell may return \"unknown\" rather than \"dead\" for a spent output","lesson":"On CKB node 0.210.0 devnet, get_live_cell for an output already consumed by a committed transaction returned status \"unknown\" instead of \"dead\", so a check requiring \"dead\" fails. Accept \"dead\" or \"unknown\" and prove consumption by calling get_transaction on the creating and consuming transactions, confirming both are committed and that the consumer's inputs reference the out point exactly once.","note":"","patterns":["avoid: if old[\"status\"] != \"dead\" {"],"concepts":["Indexer queries and cell collection","Network and RPC reliability"],"applies_to":[],"status":"current","evidence":"L1","first_seen":"2026-10-10","last_touched":"2026-10-30","level":"working","why":"A check that demands \"dead\" fails on a cell that was correctly spent, and accepting \"unknown\" alone would also pass for an out point that never existed, so consumption has to be proven from the committed transactions.","sources":[{"repo":"Tactus-Labs/tactus-o1","hash":"125b4cea3b","date":"2026-10-10"},{"repo":"Ticoworld/QuotaCell","hash":"ce8e50b1ec","date":"2026-10-30"},{"repo":"tydeptrai21042004/ckb-skill","hash":"5889b075a1","date":"2026-10-24"}],"tests":[{"repo":"tydeptrai21042004/ckb-skill","hash":"5889b075a1","files":["tests/recovery-manifest.test.mjs","tests/spend-proof.test.mjs","tests/testnet-workflow-config.test.mjs"]}],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"node/get-transaction-returns-an-object-with-a-null-transaction-fo","area":"node","title":"get_transaction returns an object with a null transaction for rejected and unknown txs","lesson":"The CKB node's get_transaction RPC does not return a null result for rejected or unknown hashes: it returns an object whose transaction field is null and whose tx_status.status is \"rejected\" (with tx_status.reason holding the rejection reason) or \"unknown\". Check res.transaction, not just res, before reading outputs, surface tx_status.reason to users, and make test mocks return this shape rather than result null.","note":"Joined with toastmanAu/openswap@4dbe3232c3.","patterns":["prefer: if (res.tx_status.status === \"rejected\") return { hash, status: \"rejected\", reason: res.tx_status.reason ?? null, rejected: true };"],"concepts":["Network and RPC reliability","Testing and devnet"],"applies_to":[],"status":"current","evidence":"L1","first_seen":"2026-10-30","last_touched":"2026-10-30","level":"working","why":"Code that treats only a null result as 'not found' misreads unknown or rejected hashes: it crashes or misbehaves on the null transaction field, hides the node's rejection reason, and test mocks returning null guard against a shape real nodes never send.","sources":[{"repo":"wildanrhmn/ckb-devnet-explorer","hash":"b5133c1c76","date":"2026-10-30"},{"repo":"toastmanAu/openswap","hash":"4dbe3232c3","date":"2026-10-22"}],"tests":[{"repo":"toastmanAu/openswap","hash":"4dbe3232c3","files":["frontend/test/fixtures.ts"]}],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"node/indexer-free-cell-discovery-by-block-scan-plus-get-live-cell","area":"node","title":"Indexer free cell discovery by block scan plus get_live_cell on a local chain","lesson":"Without an indexer on a small local chain, cells for a lock can be found by walking get_block_by_number from 0 to the tip, matching output locks, and confirming each hit with get_live_cell (with_data true). The commit also checks get_block_hash per height and at the end, then rechecks each match, so the result is treated as a snapshot that a reorg or spend can invalidate.","note":"","patterns":["prefer: live=await rpc('get_live_cell',[outPoint,true]);if(live.status!=='live')continue;"],"concepts":["Indexer queries and cell collection","Testing and devnet"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-11-05","last_touched":"2026-11-05","level":"working","why":"Without the get_live_cell check, outputs that were already spent are returned as funding cells. The test shows this: after the genesis transaction, the owner's original cell at index 3 must drop out and only the new change cell at index 1 remain, otherwise a later transaction would try to spend a dead input.","sources":[{"repo":"Ticoworld/QuotaCell","hash":"6a6074e43b","date":"2026-11-05"},{"repo":"Ticoworld/QuotaCell","hash":"1face2b238","date":"2026-11-05"}],"tests":[],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"node/indexer-get-cells-order-is-by-script-args-not-by-cell-age","area":"node","title":"Indexer get_cells order is by script args, not by cell age","lesson":"Cells returned by a prefix search on type script args (as findRounds does here) come back in indexer key order, sorted by type args, not by creation time, so taking the first result does not give the newest cell. To get the latest, sort by a field stored in the cell (here the round config's entryStart).","note":"","patterns":["avoid: const round = rounds[0];"],"concepts":["Indexer queries and cell collection"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-11-09","last_touched":"2026-11-09","level":"working","why":"Taking the first cell of a prefix search picks whichever cell has the smallest script args, not the newest one. Here that was a dead round, so the entry and refund pages could not reach the live round or the round with pending refunds.","sources":[{"repo":"toastmanAu/daowow","hash":"d189335161","date":"2026-11-09"}],"tests":[{"repo":"toastmanAu/daowow","hash":"d189335161","files":["apps/web/test/discovery.test.js"]}],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"node/indexer-rpc-module-must-be-listed-in-ckb-toml-rpc-modules-fo","area":"node","title":"Indexer RPC module must be listed in ckb.toml rpc modules for get_cells on devnet","lesson":"CKB serves get_cells, get_indexer_tip and the other indexer RPC methods only when \"Indexer\" is listed in the [rpc] modules array of ckb.toml. The ckb.toml generated in the nervos/ckb 0.209.0 devnet image used here leaves Indexer out, so add it before relying on cell collection against a devnet node. Then confirm with a real indexer call such as get_cells after the node starts.","note":"","patterns":[],"concepts":["Indexer queries and cell collection","Testing and devnet"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-09-18","last_touched":"2026-09-18","level":"working","why":"Without Indexer in the rpc modules, get_cells is unavailable on the devnet node, so cell discovery code cannot be exercised and fails confusingly mid-implementation instead of as a missing prerequisite.","sources":[{"repo":"toastmanAu/daowow","hash":"64c5e95757","date":"2026-09-18"}],"tests":[{"repo":"toastmanAu/daowow","hash":"64c5e95757","files":["tests/devnet/node_harness.py","tests/devnet/test_node_harness.py"]}],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"node/molecule-table-encoding-of-absent-optional-fields","area":"node","title":"Molecule table encoding of absent optional fields","lesson":"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.","note":"","patterns":[],"concepts":["Data encoding (molecule, hex, bigints)","Witnesses and signatures"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-10-09","last_touched":"2026-10-09","level":"working","why":"An encoder that writes an extra count word shifts every offset, so the node cannot decode the transactions, witnesses or scripts it builds and rejects them.","sources":[{"repo":"Tactus-Labs/tactus-o1","hash":"6415d97f1e","date":"2026-10-09"}],"tests":[],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"node/nervos-dao-compensation-from-the-header-s-accumulated-rate-a","area":"node","title":"Nervos DAO compensation from the header's accumulated rate (AR)","lesson":"The DAO accumulated rate AR is the second little-endian u64 (bytes 8..16) of a header's `dao` field, for example from `get_header_by_number`. Interest accrues only on free = capacity minus occupied capacity, so compensation = free * AR_end / AR_deposit minus free, and the maximum withdraw is occupied + free * AR_end / AR_deposit. AR_deposit is the AR of the deposit block; AR_end is the AR of the block holding the withdrawing cell (phase 1) once withdrawal was requested, and only for a not yet withdrawn deposit is the tip AR used, as an estimate that is still growing.","note":"","patterns":["prefer: ar: Buffer.from(h.dao.slice(2), \"hex\").readBigUInt64LE(8)"],"concepts":["Capacity and cell size","Data encoding (molecule, hex, bigints)"],"applies_to":[],"status":"current","evidence":"L1","first_seen":"2026-10-30","last_touched":"2026-11-10","level":"working","why":"Reading the wrong word of the dao field, applying the rate to the whole capacity, or using the tip AR for a cell already in withdrawal gives a wrong compensation figure. That last mistake keeps adding interest that has in fact stopped.","sources":[{"repo":"wildanrhmn/ckb-devnet-explorer","hash":"4ccf9e429c","date":"2026-10-30"},{"repo":"toastmanAu/daowow","hash":"c21668498c","date":"2026-11-10"}],"tests":[{"repo":"toastmanAu/daowow","hash":"c21668498c","files":["apps/web/test/dao-yield.test.js","apps/web/test/model-prize-estimate.test.js"]}],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"node/nervos-dao-phase-1-withdrawing-cells-keep-the-dao-type-count","area":"node","title":"Nervos DAO phase 1 withdrawing cells keep the DAO type; count deposits by 8 zero bytes of data","lesson":"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.","note":"","patterns":["prefer: (data === DAO_DEPOSIT_DATA ? deposits : withdrawing).push(cell);"],"concepts":["Indexer queries and cell collection","Data encoding (molecule, hex, bigints)"],"applies_to":[],"status":"current","evidence":"L2","first_seen":"2026-11-06","last_touched":"2026-11-06","level":"working","why":"Counting Nervos DAO cells by type script alone also counts phase 1 withdrawing cells as deposits, so a deposit already being withdrawn still adds weight; in the testnet history this gave 500 CKB instead of 300 CKB.","sources":[{"repo":"LusoCryptoLabs/ckb-ward","hash":"849eef52c4","date":"2026-11-06"},{"repo":"ckb-service-runner/csr-network-monitor","hash":"2b553c5a6c","date":"2026-10-20"}],"tests":[{"repo":"LusoCryptoLabs/ckb-ward","hash":"849eef52c4","files":["tests/weight.test.ts"]}],"related":[],"confirmed":{"by":"LusoCryptoLabs","role":"owner","date":"2026-11-19"},"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"node/never-pass-the-terminal-0x-cursor-back-to-indexer-get-cells","area":"node","title":"Never pass the terminal \"0x\" cursor back to indexer get_cells","lesson":"An exhausted indexer get_cells scan returns {objects: [], last_cursor: \"0x\"} (captured from a real node). The authors report that calling get_cells again with after = \"0x\" then returns nothing, even once matching cells exist, and a hand-written mock that never returned the real \"0x\" hid this for days. When paging, stop on an empty page before reading last_cursor, and never send or persist a \"0x\" cursor. Build paging tests from captured node responses, not hand-written mocks.","note":"","patterns":["prefer: if (objects.length === 0) return; ... if (!next || next === \"0x\" || next === \"0X\") return;"],"concepts":["Indexer queries and cell collection","Testing and devnet"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-09-18","last_touched":"2026-09-18","level":"working","why":"A pager that sends or saves the terminal \"0x\" cursor gets empty pages from then on, even after matching cells appear, so new cells go unseen. In this project inbound messages were lost for days while 360 mock-based tests stayed green.","sources":[{"repo":"toastmanAu/daowow","hash":"02989b477d","date":"2026-09-18"}],"tests":[{"repo":"toastmanAu/daowow","hash":"02989b477d","files":["apps/web/test/rpc.test.js"]}],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"node/one-prefix-get-cells-scan-per-type-code-hash-instead-of-one","area":"node","title":"One prefix get_cells scan per type code hash instead of one scan per round","lesson":"When many logical groups (here rounds) share one type script code hash, query the indexer's get_cells once with script_type \"type\", args \"0x\" and script_search_mode \"prefix\" to get every cell under that code hash, then bucket the cells client side by data length and args. Querying per group repeats the same scan and grows with the group count against a public node. The indexer returns cells in type args order, not age order, so sort the results yourself.","note":"","patterns":["prefer: script: { code_hash: script.codeHash, hash_type: script.hashType, args: \"0x\" }, script_type: \"type\", script_search_mode: \"prefix\","],"concepts":["Indexer queries and cell collection","Network and RPC reliability"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-11-10","last_touched":"2026-11-10","level":"working","why":"Reading the whole deployment one round at a time costs a full scan per round against a public node. Trusting the indexer's order put a dead round first in the list.","sources":[{"repo":"toastmanAu/daowow","hash":"c9b75aa7d7","date":"2026-11-10"}],"tests":[{"repo":"toastmanAu/daowow","hash":"c9b75aa7d7","files":["apps/web/test/helpers/fake-chain.js","apps/web/test/round-cells.test.js"]}],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"partly right","against_commit":true}},{"id":"node/paging-indexer-get-cells-and-get-transactions-with-last-curs","area":"node","title":"Paging indexer get_cells and get_transactions with last_cursor","lesson":"The built-in indexer RPCs get_cells and get_transactions return at most the requested limit (here 0x3e8) plus a last_cursor. To read all results for a search key, pass last_cursor as the fourth param on the next call and stop once a page returns fewer objects than the limit; a single call with a small limit (the old 0xc8 or 0x19) undercounts cells and transactions.","note":"","patterns":["prefer: const params: unknown[] = [key, \"desc\", \"0x3e8\"]; if (cursor) params.push(cursor);"],"concepts":["Indexer queries and cell collection","Network and RPC reliability"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-10-30","last_touched":"2026-10-30","level":"working","why":"With one call, the address page saw only the first 200 cells and 25 transactions. Live cell counts, occupied capacity, token balances and transaction totals were therefore wrong for any lock with more results than that.","sources":[{"repo":"wildanrhmn/ckb-devnet-explorer","hash":"c7304a31b4","date":"2026-10-30"}],"tests":[],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"node/preview-network-spec-removed-from-ckb","area":"node","title":"Preview network spec removed from CKB","lesson":"The preview network is retired and specs/preview.toml has been removed. `ckb init --chain preview` is rejected, and configs using { bundled = \"specs/preview.toml\" } fail to load after upgrading. Point tooling and tests at testnet, staging or dev instead.","note":"","patterns":["spec = { bundled = \"specs/preview.toml\" } in ckb.toml"],"concepts":["Testing and devnet"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-11-12","last_touched":"2026-11-12","level":"working","why":"After upgrading, a node or test setup still configured for the preview chain fails to load its chain spec, and `ckb init --chain preview` is rejected outright.","sources":[{"repo":"nervosnetwork/ckb","hash":"36058a4749","date":"2026-11-12"}],"tests":[],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"node/reading-total-occupied-capacity-u-from-the-header-dao-field","area":"node","title":"Reading total occupied capacity (U) from the header DAO field","lesson":"The block header `dao` field packs four little endian u64 values (C, AR, S, U), and U at byte offset 24 is the total occupied capacity of all live cells in shannons. This commit reads it from `get_tip_header` to show chain state size, and for a genesis that holds the 8.4 billion CKB cell (mainnet and offckb devnet) it subtracts 5.04 billion CKB counted as occupied because it is due to be burnt, as the CKB Explorer does.","note":"","patterns":["prefer: Buffer.from(header.dao.slice(2), \"hex\").readBigUInt64LE(24) - this.burnt"],"concepts":["Capacity and cell size","Data encoding (molecule, hex, bigints)"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-10-30","last_touched":"2026-10-30","level":"working","why":"Without decoding U from the DAO field you cannot cheaply show the chain's total occupied state. Without subtracting the genesis cell's 60% occupied share, a mainnet or offckb devnet figure is inflated by 5.04 billion CKB and will not match the CKB Explorer.","sources":[{"repo":"wildanrhmn/ckb-devnet-explorer","hash":"5b3fbb1a1c","date":"2026-10-30"}],"tests":[],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"node/rebuild-an-append-only-on-chain-accumulator-from-transaction","area":"node","title":"Rebuild an append-only on-chain accumulator from transaction history, not from live cells","lesson":"When a cell stores only the root of an append-only accumulator (an MMR) that commits to every entry ever added, spending an entry cell removes it from the indexer's live set while the root still counts it. Replaying live cells builds a different tree and membership proofs fail (the first refund works, the second fails). If each append transaction carries its entries in a witness and spends the previous head at input 0, recover the full set by walking get_transaction backwards through input 0 and parsing each witness with a strict exact-length check, so unrelated WitnessArgs or empty witnesses are not read as entries. Refuse to act unless the recovered count equals the frozen entry count, and fail if the node no longer serves an old transaction.","note":"Joined with daowow@765895a407.","patterns":["prefer: const replay = await readers.readShardEntries(rpc, ledger.outPoint, want); if (replay.length !== Number(want)) {"],"concepts":["Indexer queries and cell collection","Witnesses and signatures"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-11-10","last_touched":"2026-11-10","level":"advanced","why":"Membership proofs built by replaying only the indexer's live cells target a different tree than the committed root. Once one entry cell is spent, every later refund is refused on chain.","sources":[{"repo":"toastmanAu/daowow","hash":"e512fd3dc9","date":"2026-11-10"},{"repo":"toastmanAu/daowow","hash":"765895a407","date":"2026-10-01"}],"tests":[{"repo":"toastmanAu/daowow","hash":"e512fd3dc9","files":["apps/web/test/app-shell.test.js","apps/web/test/model-refund-guard.test.js","apps/web/test/page-scripts.test.js"]},{"repo":"toastmanAu/daowow","hash":"765895a407","files":["apps/web/test/shard-history.test.js"]}],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"node/reconcile-a-lost-send-transaction-response-by-pinned-hash-no","area":"node","title":"Reconcile a lost send_transaction response by pinned hash, not by rebuilding","lesson":"When a send_transaction response is lost (the node may already have accepted the transaction), this commit pins the signed transaction hash and its input outpoints, and recovers by querying get_transaction for that exact hash and get_live_cell for each input instead of building a new payment. Only a 'committed' status ends the intent; rejected, unknown or spent inputs stay 'uncertain' for operator review, because a fresh rebuild from refreshed cells was shown to let a second payment to the same recipient commit.","note":"","patterns":["prefer: state = \"committed\" if chain_state == \"committed\" else \"uncertain\""],"concepts":["Network and RPC reliability","Transaction building and fees","Indexer queries and cell collection"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-11-02","last_touched":"2026-11-02","level":"working","why":"Building a new payment after a lost response can create a second, different transaction that also commits, paying the same invoice twice.","sources":[{"repo":"Ticoworld/QuotaCell","hash":"67bb8e3c7b","date":"2026-11-02"}],"tests":[],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"partly right","against_commit":true}},{"id":"node/reconstructing-the-live-cell-set-at-a-past-height-from-the-c","area":"node","title":"Reconstructing the live cell set at a past height from the CKB indexer","lesson":"The indexer's get_cells lists only cells live at its current tip. To get Nervos DAO deposits live at height H, read the indexer tip, list get_cells and keep those with block_number <= H, then read the indexer tip again as T. Then query get_transactions on the DAO type script with filter block_range [H+1, T+1) (the end is exclusive), keep io_type input, follow each input's previous_output to the creating tx and its header, and add back cells created at or below H. In both passes keep only real deposits (DAO type and 8 zero bytes of data), since withdrawing cells share the type script, and retry if either tip hash is no longer canonical per get_block_hash.","note":"","patterns":["prefer: \"filter\": {\"block_range\": [format!(\"0x{:x}\", height + 1), format!(\"0x{:x}\", to + 1)]}"],"concepts":["Indexer queries and cell collection","Network and RPC reliability"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-10-08","last_touched":"2026-10-08","level":"advanced","why":"A plain get_cells snapshot misses every deposit that existed at H but was withdrawn later, and withdrawing cells or reorgs during the pass would corrupt the reconstructed set.","sources":[{"repo":"poshboytl/omavote","hash":"d562d8a83f","date":"2026-10-08"}],"tests":[],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"node/reuse-one-ckbrpcclient-across-a-loop-instead-of-building-one","area":"node","title":"Reuse one CkbRpcClient across a loop instead of building one per item","lesson":"Constructing a ckb_sdk CkbRpcClient (CkbRpcClient::with_builder) loads the TLS root store, about 6 ms of CPU each time. In Fiber's watchtower, building one per watched channel made a round over 11,496 channels take 93 to 115 s; building one client before the loop and passing &CkbRpcClient cut it to 5 to 7 s.","note":"","patterns":["prefer: let ckb_client = CkbRpcClient::with_builder(&rpc_url, |builder| { builder.timeout(CKB_RPC_TIMEOUT).no_proxy() }) (built once, before the for loop over watched channels)"],"concepts":["Network and RPC reliability"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-11-03","last_touched":"2026-11-03","level":"working","why":"Building a new ckb_sdk CkbRpcClient for every item reloads the TLS root store each time, about 6 ms of CPU per item. Over 11,496 watched channels that stretched one watchtower round from 5 to 7 s to 93 to 115 s.","sources":[{"repo":"nervosnetwork/fiber","hash":"0e96a175ab","date":"2026-11-03"}],"tests":[],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"node/script-group-hash-is-the-hash-of-the-whole-script-not-the-co","area":"node","title":"Script group hash is the hash of the whole Script, not the code_hash","lesson":"A script group is identified by BLAKE2b-256 with the 'ckb-default-hash' personalization over the Molecule-encoded Script (code_hash, hash_type byte data=0/type=1/data1=2/data2=4, args). Lock groups come only from inputs. Type groups come from inputs and outputs, and lock and type groups with the same hash stay distinct. Passing the code_hash as the group hash yields ScriptNotFound.","note":"","patterns":["script_group.script_hash = cell.output.lock.code_hash  // wrong; use blake2b(molecule(Script)) instead"],"concepts":["Data encoding (molecule, hex, bigints)","Witnesses and signatures"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-11-16","last_touched":"2026-11-16","level":"working","why":"Selecting a script group by its code_hash matches no group, so verification fails with ScriptNotFound and the intended lock or type script never runs.","sources":[{"repo":"Hanssen0-Alter-Ego/ckb-vm-js","hash":"1236321f07","date":"2026-11-16"}],"tests":[{"repo":"Hanssen0-Alter-Ego/ckb-vm-js","hash":"1236321f07","files":["tests/browser/workbench.spec.js","tests/js/guided.test.js","tests/js/wasm.integration.js","tests/js/workbench.test.js"]}],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"node/search-for-a-script-s-cells-under-both-its-data-hash-and-its","area":"node","title":"Search for a script's cells under both its data hash and its type id code hash","lesson":"A script deployed with a type id can be referenced by cells either as hashType data1 with the code's data hash or as hashType type with the deployment's type id hash (per network). An exact indexer search via client.findCells over only one form misses the other; here @ckbfs/api's useTypeID cells read as missing until the reader queried both forms and treated a combined count above one as an error.","note":"","patterns":["prefer: for (const s of ckbfsV3Scripts(client)) { const script = ccc.Script.from({ codeHash: s.codeHash, hashType: s.hashType, args: typeId })"],"concepts":["Indexer queries and cell collection","Type ID and upgrades"],"applies_to":[],"status":"current","evidence":"L2","first_seen":"2026-10-24","last_touched":"2026-10-24","level":"working","why":"Cells whose type script points at the code by its type id hash (here what @ckbfs/api writes with useTypeID) never match an exact search built on the data hash, so the reader reports existing files as missing.","sources":[{"repo":"LusoCryptoLabs/ckbfs-reader","hash":"0e7dcba446","date":"2026-10-24"}],"tests":[{"repo":"LusoCryptoLabs/ckbfs-reader","hash":"0e7dcba446","files":["test/reader.test.ts"]}],"related":[],"confirmed":{"by":"LusoCryptoLabs","role":"owner","date":"2026-11-19"},"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"node/send-transaction-error-1111-poolrejectedrbf-is-a-conflict-no","area":"node","title":"send_transaction error -1111 (PoolRejectedRBF) is a conflict, not \"already in pool\"","lesson":"CKB's send_transaction returns -1107 when the same tx is already in the pool, but -1111 (PoolRejectedRBF) when a different pool tx spends one of its inputs and this tx cannot replace it. Treating -1111 like -1107 makes a client resend a tx whose input is gone and only notice the failure much later. Fiber now reports it as a conflict (failing a funding tx at once) while closing txs keep the old handling.","note":"","patterns":[],"concepts":["Network and RPC reliability","Transaction building and fees"],"applies_to":[],"status":"current","evidence":"L2","first_seen":"2026-10-29","last_touched":"2026-11-18","level":"working","why":"A client that reads -1111 as \"already in pool\" keeps resending a transaction whose input another pool transaction has taken. It only learns of the failure when that other transaction is committed, or at its own timeout.","sources":[{"repo":"nervosnetwork/fiber","hash":"14215f375a","date":"2026-10-29"},{"repo":"LusoCryptoLabs/cells-resolver","hash":"26c5d7c2ed","date":"2026-11-18"}],"tests":[{"repo":"nervosnetwork/fiber","hash":"14215f375a","files":["crates/fiber-lib/src/fiber/tests/in_flight_ckb_tx_actor_tests.rs"]},{"repo":"LusoCryptoLabs/cells-resolver","hash":"26c5d7c2ed","files":["services/gateway/test/accountproof.test.ts","services/gateway/test/card.test.ts","services/gateway/test/counts.test.ts","services/gateway/test/directory.test.ts","services/gateway/test/domainproof.test.ts"]}],"related":[],"confirmed":{"by":"LusoCryptoLabs","role":"owner","date":"2026-11-19"},"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"node/serialize-transfers-from-one-account-until-the-previous-tx-i","area":"node","title":"Serialize transfers from one account until the previous tx is committed","lesson":"When one account sends several transfers in a row (here via `offckb transfer`), a new transfer started before the previous one is committed can pick the same input cell, and the node rejects it with PoolRejectedRBF. This faucet queues claims and polls get_transaction until tx_status is committed, rejected or unknown before building the next transfer.","note":"","patterns":["prefer: this.queue = run.then((c) => this.committed(c.hash), () => undefined);"],"concepts":["Transaction building and fees","Network and RPC reliability"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-10-30","last_touched":"2026-10-30","level":"working","why":"If a second transfer from the same account is built while the first is still in the pool, it selects the same live input cell and the node rejects it with PoolRejectedRBF, so the claim fails.","sources":[{"repo":"wildanrhmn/ckb-devnet-explorer","hash":"005dd74383","date":"2026-10-30"}],"tests":[],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"node/simulating-a-real-ckb-reorg-with-two-devnet-nodes-over-p2p","area":"node","title":"Simulating a real CKB reorg with two devnet nodes over P2P","lesson":"To exercise genuine fork choice on a Dummy devnet, partition two nodes with set_network_active(false) plus remove_node, wait until get_peers is empty on both, then mine a longer competing branch on one node with generate_block. Reconnect with set_network_active(true) and add_node(node_id, /ip4/.../tcp/port), and wait until both nodes report the same get_tip_header hash and the same tx_pool_info tip_hash before checking reorg recovery.","note":"","patterns":["prefer: rpc::call_at(peer, \"add_node\", json!([info[\"node_id\"], address]))?;"],"concepts":["Testing and devnet","Network and RPC reliability"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-10-10","last_touched":"2026-10-10","level":"advanced","why":"Without a confirmed partition the peer simply syncs the main branch and no competing fork forms. Without waiting for both the tip hash and tx_pool_info tip_hash to converge, reorg checks such as liveness, recovery and dependency rejection run against a node that has not yet switched branches or refreshed its pool.","sources":[{"repo":"Tactus-Labs/tactus-o1","hash":"d3f20d2cf2","date":"2026-10-10"},{"repo":"Tactus-Labs/tactus-o1","hash":"935a4477ae","date":"2026-10-10"}],"tests":[],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"node/use-indexer-matched-cell-indexes-to-limit-input-parent-fetch","area":"node","title":"Use indexer matched cell indexes to limit input parent fetches","lesson":"With CCC client.findTransactionsPaged (scriptSearchMode 'prefix', groupByTransaction: true), each returned transaction has a cells list of {isInput, cellIndex} entries for the cells that matched the searched script. If your logic only needs the matched inputs, fetch parent transactions with getTransaction only for those indexes (plus siblings from a parent you already hold) and skip unrelated inputs such as wallet funding. OpenSwap's market scanner did this together with raising read concurrency to 16, and its first scan went from about 8 to 10 s to about 5.3 s; the gain from this change alone was not measured.","note":"","patterns":["prefer: for(const c of t.cells)if(c.isInput)f.inputs.add(Number(c.cellIndex));"],"concepts":["Indexer queries and cell collection","Network and RPC reliability"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-10-29","last_touched":"2026-10-29","level":"working","why":"Without it, every input's parent transaction is fetched with getTransaction, including wallet funding cells the logic never uses, which multiplies RPC reads and slows the scan.","sources":[{"repo":"toastmanAu/openswap","hash":"fa6e518ea1","date":"2026-10-29"}],"tests":[{"repo":"toastmanAu/openswap","hash":"fa6e518ea1","files":["frontend/test/markets-harness.ts","frontend/test/markets.spec.ts","pool-sdk/test/market-scan.test.ts","pool-sdk/test/market.test.ts"]}],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"node/validate-header-and-epoch-lookups-before-using-timestamps","area":"node","title":"Validate header and epoch lookups before using timestamps","lesson":"After get_header_by_number or get_epoch_by_number, treat a null result as unavailable and check that the returned number equals the one you asked for. To get an epoch's start time, read the header at the EpochView's start_number. Then check that this header's epoch field has the epoch number in its low 24 bits and 0 in bits 24 to 39 (the block's index within the epoch), so the block really is the first block of that epoch.","note":"","patterns":["const h = await rpc.call('get_header_by_number',[hex]); if(!h || BigInt(h.number)!==wanted) throw ...; return BigInt(h.timestamp)","readBlockTime(rpc, epoch.start_number) trusted blindly → check (header.epoch & 0xffffff)==epoch && ((header.epoch>>24)&0xffff)==0"],"concepts":["Network and RPC reliability","Since and time locks","Data encoding (molecule, hex, bigints)"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-11-12","last_touched":"2026-11-12","level":"working","why":"Without these checks a node that answers for a neighbouring block or epoch gets that block's time shown as this one's exact date, and it is then cached as if it were correct.","sources":[{"repo":"toastmanAu/daowow","hash":"a8c736cfb2","date":"2026-11-12"},{"repo":"toastmanAu/daowow","hash":"7b41092d7f","date":"2026-11-12"}],"tests":[{"repo":"toastmanAu/daowow","hash":"a8c736cfb2","files":["apps/web/test/app-shell.test.js","apps/web/test/build-site.test.js","apps/web/test/model-copy.test.js","apps/web/test/model-ticket-face.test.js","apps/web/test/model-tickets.test.js"]},{"repo":"toastmanAu/daowow","hash":"7b41092d7f","files":["apps/web/test/model-copy.test.js","apps/web/test/model-ticket-face.test.js","apps/web/test/model-time.test.js","apps/web/test/round-cells.test.js","apps/web/test/store.test.js"]}],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"node/verify-a-deployed-code-cell-is-canonical-and-live-before-rec","area":"node","title":"Verify a deployed code cell is canonical and live before recording it as a cell dep","lesson":"Before writing a deployment manifest for a code cell, this commit checks get_transaction is committed, that get_block_hash at the header number equals the block hash (not reorganized), and that get_live_cell still reports status live with the expected data hash. It then repeats the canonical and live checks after all reads (on two independent RPCs), so a stale, spent or reorganized cell never yields a manifest.","note":"","patterns":["prefer: assert.equal(await source('get_block_hash',[primary.blockNumber]),primary.blockHash,'Deployment reorganized');"],"concepts":["Cell deps and script lookup","Network and RPC reliability"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-11-09","last_touched":"2026-11-09","level":"working","why":"Without these checks a manifest can pin a cell dep out point whose deployment was reorganized away, whose cell was spent, or whose data is not the expected code, so every later transaction that references it fails verification.","sources":[{"repo":"Ticoworld/QuotaCell","hash":"f425ddc384","date":"2026-11-09"}],"tests":[],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"node/verify-a-self-indexed-tip-against-the-node-s-canonical-block","area":"node","title":"Verify a self indexed tip against the node's canonical block hash before serving it","lesson":"A locally maintained index of CKB blocks can lag the node or still hold an orphaned block after a reorg, so before serving its tip as an anchor, fetch the node's tip number, wait briefly for the index to reach it, then ask the node for the canonical block hash at the indexed height and refuse (503 with NOT_SYNCED or REORGANIZING) unless it equals the indexed hash. The check narrows the window but is not atomic, so a client that signs over the anchor should also compare it with an independent source.","note":"","patterns":[],"concepts":["Network and RPC reliability","Indexer queries and cell collection"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-10-08","last_touched":"2026-10-08","level":"working","why":"Without the check, a server whose index lags the node or still holds an orphaned block after a reorg hands clients an anchor that is not the node's current canonical tip. Signatures made over that anchor are then rejected as ANCHOR_INVALID or refer to a block that left the chain.","sources":[{"repo":"poshboytl/omavote","hash":"ad8ea705f6","date":"2026-10-08"}],"tests":[{"repo":"poshboytl/omavote","hash":"ad8ea705f6","files":["web/test/tipcheck.test.ts"]}],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"node/verifying-an-indexer-funding-cell-against-an-advancing-tip-i","area":"node","title":"Verifying an indexer funding cell against an advancing tip instead of a frozen snapshot","lesson":"A frozen-tip check (\"the indexer tip must not change during the scan\") fails often on a live chain, so do not demand it. Select a single funding cell from get_cells, verify it directly against the node (get_live_cell, get_transaction, get_header, output and data equal to the indexed ones), then re-check at the end that get_block_hash at the starting indexer tip still equals the anchor hash, that the cell's block is canonical, and that the cell is still live. New blocks arriving in between are fine, but still fail closed if the indexer lags the node at the start or the anchor hash changed. This gives one verified input, not a snapshot of the whole wallet.","note":"","patterns":["prefer: assert.equal(anchorHash,indexed.block_hash,'Chain reorganized during funding lookup');assert.equal(cellBlockHash,header.hash,'Funding block is noncanonical');"],"concepts":["Indexer queries and cell collection","Network and RPC reliability"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-11-09","last_touched":"2026-11-09","level":"working","why":"A rule that the indexer tip must stay frozen during the scan makes funding lookups on a live chain keep failing and retrying. It also turns away results that are actually safe, because the anchor block, the cell's block and the cell's liveness can all be checked again directly against the node.","sources":[{"repo":"Ticoworld/QuotaCell","hash":"2ad8abd5aa","date":"2026-11-09"}],"tests":[],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"node/wait-for-get-indexer-tip-to-reach-the-commit-block-before-re","area":"node","title":"Wait for get_indexer_tip to reach the commit block before re-reading cells","lesson":"After get_transaction reports tx_status committed, poll get_indexer_tip until its block_number is at least the transaction's block number before calling get_cells. If you query first, the indexer silently returns the pre-transaction cell set with no error.","note":"","patterns":["prefer: if (tip && BigInt(tip.block_number) >= BigInt(blockNumber)) return true;"],"concepts":["Indexer queries and cell collection","Network and RPC reliability"],"applies_to":[],"status":"current","evidence":"L1","first_seen":"2026-09-24","last_touched":"2026-11-09","level":"working","why":"Without this wait, a client re-reads cells right after commit, gets the pre-transaction cell set with no error, and shows stale state (here, a ticket count that did not move) or records a wrong empty selection.","sources":[{"repo":"toastmanAu/daowow","hash":"47fe53b7ff","date":"2026-09-24"},{"repo":"Akane-CN/spark-verify","hash":"f5f680e2c1","date":"2026-11-02"},{"repo":"Akane-CN/spark-verify","hash":"4dca2e904a","date":"2026-11-09"},{"repo":"toastmanAu/openswap","hash":"99dfe12d83","date":"2026-10-29"}],"tests":[{"repo":"toastmanAu/daowow","hash":"47fe53b7ff","files":["apps/web/test/confirm.test.js"]},{"repo":"Akane-CN/spark-verify","hash":"f5f680e2c1","files":["tests/evidence-bundle.test.ts","tests/fixtures/claims-v3/synthetic.ts","tests/fixtures/conformance/manifests/invalid/unsupported-spec.toml","tests/fixtures/conformance/manifests/valid/v0.1.0-vocabulary.toml","tests/frozen-contract.test.ts"]},{"repo":"Akane-CN/spark-verify","hash":"4dca2e904a","files":["tests/cli-main.test.ts","tests/fixtures/conformance/manifests/invalid/unsupported-spec.toml","tests/frozen-contract-v0.2.test.ts","tests/manifest-v6.test.ts","tests/manifest.test.ts"]}],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"node/wait-for-tx-pool-info-tip-to-match-chain-tip-before-submitti","area":"node","title":"Wait for tx_pool_info tip to match chain tip before submitting on devnet","lesson":"After generate_block, CKB's tx pool updates its snapshot asynchronously, so a transaction spending just-committed outputs can be rejected (e.g. \"Resolve failed Unknown\") even though get_live_cell sees them. Before send_transaction or send_test_transaction, poll tx_pool_info until its tip_hash and tip_number equal get_tip_header's hash and number.","note":"","patterns":["prefer: if actual_hash == expected_hash && actual_number == expected_number { return Ok(()); }"],"concepts":["Testing and devnet","Network and RPC reliability"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-10-08","last_touched":"2026-10-08","level":"working","why":"Without the wait, a transaction that spends outputs from a block just mined can be rejected by the pool because the pool still resolves inputs against the older snapshot, and a rejected tx should not simply be resubmitted.","sources":[{"repo":"CellScript-Labs/CellScript","hash":"23822919ac","date":"2026-10-08"}],"tests":[],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"other/absolute-epoch-since-needs-the-0x20-metric-flag","area":"other","title":"Absolute epoch since needs the 0x20 metric flag","lesson":"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.","note":"since flag bits, not covered","patterns":[],"concepts":["Since and time locks"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-09-25","last_touched":"2026-09-25","level":"working","why":"Without the 0x20 metric flag the node reads the since value as an absolute block number, so the lock means something entirely different and the contract's epoch check rejects the transaction.","sources":[{"repo":"toastmanAu/daowow","hash":"6335cfbff0","date":"2026-09-25"}],"tests":[{"repo":"toastmanAu/daowow","hash":"6335cfbff0","files":["apps/web/test/lifecycle-rules.test.js"]}],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"other/hand-encoding-witnessargs-in-molecule","area":"other","title":"Hand-encoding WitnessArgs in molecule","lesson":"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.","note":"","patterns":[],"concepts":["Data encoding (molecule, hex, bigints)","Witnesses and signatures"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-11-14","last_touched":"2026-11-14","level":"working","why":"A hand-written encoder that treats an empty field like an absent one, or gets the offsets wrong, produces witness bytes that do not match what CCC and the scripts expect.","sources":[{"repo":"toastmanAu/daowow","hash":"61246b140b","date":"2026-11-14"}],"tests":[{"repo":"toastmanAu/daowow","hash":"61246b140b","files":["apps/web/test/claim-codec.test.js"]}],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"partly right","against_commit":true}},{"id":"other/nervos-dao-phase-one-withdrawal-layout","area":"other","title":"Nervos DAO phase-one withdrawal layout","lesson":"In phase one, output i must mirror deposit input i (same capacity, lock and DAO type), with its data set to the deposit block number as a u64 LE, and the deposit block hash must be in header_deps. Put any fee-paying input and output after all deposits. A custom lock that enforces a full 180-epoch term before phase one pushes payout to the next cycle boundary (about deposit + 360 epochs, roughly 60 days).","note":"","patterns":["inputs/outputs: [...deposits(index-aligned), sponsor]; outputsData[i]=u64le(depositHeader.number); since = ABSOLUTE_EPOCH_FLAG | (depositEpoch + 180*periods + 1)"],"concepts":["Since and time locks","Transaction building and fees","Cell deps and script lookup"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-11-13","last_touched":"2026-11-13","level":"working","why":"Without index-aligned outputs the DAO type script rejects the withdrawal, and a lock that waits a full term before phase one silently doubles the time to payout.","sources":[{"repo":"toastmanAu/daowow","hash":"0b98880b1d","date":"2026-11-13"}],"tests":[{"repo":"toastmanAu/daowow","hash":"0b98880b1d","files":["apps/web/test/dao-tx.test.js"]}],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"partly right","against_commit":true}},{"id":"other/nervos-dao-phase-two-withdrawal-since-and-amount","area":"other","title":"Nervos DAO phase-two withdrawal since and amount","lesson":"Set the phase-two input since to an absolute epoch counted from the DEPOSIT header, not the withdrawing block. Round the elapsed epochs up to whole 180-epoch cycles, compare epoch fractions by cross-multiplication, and keep the deposit's epoch index and length. The withdrawable amount is occupied + (capacity − occupied) × AR_withdraw / AR_deposit, where AR is a little-endian u64 read from bytes 8..16 of each header's dao field. WitnessArgs.input_type must hold the deposit header's index in header_deps as an 8-byte little-endian u64.","note":"","patterns":["since = withdrawEpoch + 180 (wrong) → since = absoluteEpoch(depositEpoch + ceil(elapsed/180)*180, depositIndex, depositLength)"],"concepts":["Since and time locks","Witnesses and signatures","Capacity and cell size"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-11-13","last_touched":"2026-11-13","level":"working","why":"If the since is counted from the withdrawing block, the cell is reported as maturing at the wrong epoch and the transaction is built against it. A wrong withdrawable amount, rate source or input_type header index makes the native DAO script reject the phase-two transaction.","sources":[{"repo":"toastmanAu/daowow","hash":"89740f6119","date":"2026-11-13"}],"tests":[{"repo":"toastmanAu/daowow","hash":"89740f6119","files":["apps/web/test/dao-tx.test.js"]}],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"other/occupied-capacity-minimum-for-every-output","area":"other","title":"Occupied capacity minimum for every output","lesson":"Every output must hold at least its occupied capacity: (8 for the capacity field + 33 + lock args length, plus 33 + type args length if a type script is present, plus data length) × 10^8 shannons. That is 61 CKB for a plain secp256k1 lock with 20 byte args and 63 CKB for a JoyID lock. A fixed payout or fee output set below the recipient lock's minimum is rejected, so choose a constant at or above the largest minimum among the locks you accept.","note":"","patterns":[],"concepts":["Capacity and cell size","Transaction building and fees"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-11-14","last_touched":"2026-11-15","level":"basic","why":"A fee or payout output set below the recipient lock's occupied capacity is rejected, so the whole transaction cannot be built or submitted.","sources":[{"repo":"psawyerberlin/dead-man-switch","hash":"168076140b","date":"2026-11-15"},{"repo":"toastmanAu/daowow","hash":"61246b140b","date":"2026-11-14"}],"tests":[{"repo":"psawyerberlin/dead-man-switch","hash":"168076140b","files":["acceptance/aiworker-dms-core/wiring.test.mjs","acceptance/aiworker-dms-e2e/wiring.test.mjs","acceptance/aiworker-dms-notifier/wiring.test.mjs","acceptance/aiworker-dms-ui/wiring.test.mjs"]},{"repo":"toastmanAu/daowow","hash":"61246b140b","files":["apps/web/test/claim-codec.test.js"]}],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"other/recognizing-a-nervos-dao-deposit-cell-not-a-withdrawing-one","area":"other","title":"Recognizing a Nervos DAO deposit cell (not a withdrawing one)","lesson":"Treat a cell as a Nervos DAO deposit only if its type script exactly matches the DAO type script and its data is exactly 8 zero bytes. The DAO type script has code hash 0x82d76d1b75fe2fd9a27dfbaa65a039221a380d76c926f378d3f81cf3e7e13f2e, hash_type type and empty args. A phase one withdrawing cell has the same type script but a nonzero block number in its 8 data bytes, so it fails this check, as do data of any other length and look alike type scripts.","note":"joined with the ckb-service-runner card teaching the same check","patterns":["prefer: return self.exact_dao_type and self.data == DEPOSIT_DATA"],"concepts":["Indexer queries and cell collection","Data encoding (molecule, hex, bigints)"],"applies_to":[],"status":"current","evidence":"L1","first_seen":"2026-10-08","last_touched":"2026-10-20","level":"working","why":"Without the exact type and data check, look alike scripts and phase one withdrawing cells are counted as live deposits, so stake or voting weight survives a withdrawal or can be faked.","sources":[{"repo":"poshboytl/omavote","hash":"c78f62c758","date":"2026-10-08"},{"repo":"ckb-service-runner/ckb-service-runner","hash":"88bc6efdf2","date":"2026-10-20"}],"tests":[{"repo":"ckb-service-runner/ckb-service-runner","hash":"88bc6efdf2","files":["acceptance/a7/p3.test.mjs"]}],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"other/recompute-occupied-capacity-when-a-state-cell-grows-in-a-tra","area":"other","title":"Recompute occupied capacity when a state cell grows in a transition","lesson":"When a transaction replaces a cell with one holding larger data (here 101 to 207 bytes under the same type script), compute the new occupied floor as 8 + data length + lock (32 code hash + 1 hash type + args) + type (32 + 1 + args) bytes in CKB, and top up from another input if the old capacity falls short (312 CKB input vs a 318 CKB floor here). If the type script also requires output capacity >= input capacity, use the larger of the two bounds rather than shrinking to the floor.","note":"adds top up and max(floor, input capacity) rule beyond the occupied capacity formula lesson","patterns":["prefer: const ledgerCapacity = floor > inCap ? floor : inCap;"],"concepts":["Capacity and cell size","Transaction building and fees"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-09-25","last_touched":"2026-09-25","level":"working","why":"Reusing the old cell's 312 CKB for a 207-byte replacement leaves the output below its 318 CKB occupied floor, so the node rejects the transaction. Shrinking a well-funded cell down to that floor would instead fail the type script's out_cap >= in_cap check.","sources":[{"repo":"toastmanAu/daowow","hash":"aedaacdebb","date":"2026-09-25"}],"tests":[{"repo":"toastmanAu/daowow","hash":"aedaacdebb","files":["apps/web/test/genesis-tx.test.js"]}],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"other/restrict-script-hashtype-to-data-type-data1-data2-when-loadi","area":"other","title":"Restrict script hashType to data, type, data1, data2 when loading config","lesson":"CKB hash_type encodes as data=0, type=1, data1=2, data2=4 (no value 3), so a config loader should reject any hashType string outside data/type/data1/data2 rather than map it loosely. A wrong code hash or hash type makes cell discovery watch the wrong cells and silently return empty results.","note":"hash_type validation, not covered","patterns":["prefer: const HASH_TYPES = Object.freeze([\"data\", \"type\", \"data1\", \"data2\"]);"],"concepts":["Cell deps and script lookup","Data encoding (molecule, hex, bigints)"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-09-18","last_touched":"2026-09-18","level":"working","why":"A loosely parsed hashType can silently land on a real but wrong hash type, so discovery watches the wrong cells and returns an empty result that looks like a round that has not opened yet.","sources":[{"repo":"toastmanAu/daowow","hash":"8543256feb","date":"2026-09-18"}],"tests":[{"repo":"toastmanAu/daowow","hash":"8543256feb","files":["apps/web/test/manifest.test.js"]}],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"other/strict-validation-of-molecule-table-headers-in-hand-written","area":"other","title":"Strict validation of molecule table headers in hand written decoders","lesson":"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.","note":"table header validation, distinct from WitnessArgs encoding lesson","patterns":["prefer: n = first // 4 - 1"],"concepts":["Data encoding (molecule, hex, bigints)"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-10-19","last_touched":"2026-10-19","level":"working","why":"Without these header checks, truncated, padded or extra-field cell data gets sliced into wrong field values instead of being rejected, so the decoder trusts malformed on-chain data.","sources":[{"repo":"ckb-service-runner/csr-network-monitor","hash":"fd8e11e423","date":"2026-10-19"}],"tests":[],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"scripts/24-bit-epoch-number-overflow","area":"scripts","title":"24-bit epoch number overflow","lesson":"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.","note":"","patterns":[],"concepts":["Since and time locks"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-11-17","last_touched":"2026-11-17","level":"working","why":"A round whose draw epoch is past 0xFFFFFF would accept tickets but could never be sealed or drawn, so the participants' funds could not be returned through the draw.","sources":[{"repo":"toastmanAu/daowow","hash":"c12ab944c2","date":"2026-11-17"},{"repo":"toastmanAu/daowow","hash":"b137728aeb","date":"2026-11-17"}],"tests":[{"repo":"toastmanAu/daowow","hash":"c12ab944c2","files":["apps/web/test/codec.test.js","crates/daowow-core/tests/gen_vectors.rs"]},{"repo":"toastmanAu/daowow","hash":"b137728aeb","files":["tests/integration/tests/round_validation.rs","tests/integration/tests/security_refunds.rs","tests/integration/tests/security_seal.rs"]}],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"scripts/absolute-epoch-since-needs-the-0x20-metric-flag-in-the-top-b","area":"scripts","title":"Absolute epoch since needs the 0x20 metric flag in the top byte","lesson":"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.","note":"Builder side rule for setting the epoch flag.","patterns":["prefer: { previousOutput: shard.outPoint, since: ABSOLUTE_EPOCH_FLAG | epoch }"],"concepts":["Since and time locks"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-09-25","last_touched":"2026-09-25","level":"working","why":"Without the flag the node treats an epoch number as a long-past block number. The intended epoch lower bound is then not enforced by the node, and the input is either unlocked early or refused by a script that checks the metric.","sources":[{"repo":"toastmanAu/daowow","hash":"5bac7beee9","date":"2026-09-25"},{"repo":"toastmanAu/daowow","hash":"23c42c73ce","date":"2026-09-23"}],"tests":[{"repo":"toastmanAu/daowow","hash":"5bac7beee9","files":["apps/web/test/freeze-tx.test.js"]},{"repo":"toastmanAu/daowow","hash":"23c42c73ce","files":["apps/web/test/entry-tx.test.js"]}],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"scripts/assert-the-specific-script-error-code-in-ckb-testtool-reject","area":"scripts","title":"Assert the specific script error code in ckb-testtool rejection tests","lesson":"In ckb-testtool tests, checking only that `context.verify_tx(&tx, MAX_CYCLES)` returns an error lets a test keep passing even if the targeted check is deleted from the script, because a badly built transaction usually fails for several reasons. This commit matches the script's exit code in the error string instead (`err.contains(\"error code {code} \")`), one constant per error discriminant of the script.","note":"","patterns":[],"concepts":["Testing and devnet"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-11-05","last_touched":"2026-11-05","level":"working","why":null,"sources":[{"repo":"CECILIA-MULANDI/zk-Lock","hash":"402fe11913","date":"2026-11-05"}],"tests":[{"repo":"CECILIA-MULANDI/zk-Lock","hash":"402fe11913","files":["sdk/ts/test/bound.test.ts","sdk/ts/test/encode.test.ts","tests/src/lib.rs","tests/src/tests.rs","tests/src/tests_bound.rs"]}],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"wrong","against_commit":true}},{"id":"scripts/check-that-a-derived-successor-type-args-match-the-spent-cel","area":"scripts","title":"Check that a derived successor type args match the spent cell's type args","lesson":"When a successor cell's type args are derived from other data (such as a config commitment) instead of copied from the spent input, compare them with the input cell's own type args before building. A mismatch (for example a config cell paired with a shard from another round) puts the input's type script group in the transaction with no output, so the type script runs as a burn and typically fails with an opaque error code. Read output.type.args during cell discovery and throw a clear client error on mismatch.","note":"","patterns":[],"concepts":["Transaction building and fees","Cell deps and script lookup"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-09-23","last_touched":"2026-09-23","level":"working","why":"A shard paired with a config from another round builds a transaction the contract rejects as BadState with no explanation of the cause.","sources":[{"repo":"toastmanAu/daowow","hash":"6fba1339e0","date":"2026-09-23"}],"tests":[{"repo":"toastmanAu/daowow","hash":"6fba1339e0","files":["apps/web/test/codec.test.js","apps/web/test/discovery.test.js","apps/web/test/entry-tx.test.js"]}],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"partly right","against_commit":true}},{"id":"scripts/cheque-lock-receiver-path-must-return-the-cell-s-capacity-to","area":"scripts","title":"Cheque lock receiver path must return the cell's capacity to the sender","lesson":"When a Cheque lock cell (RFC 0039) is spent on the receiver path, rule 1.b.ii requires the Cheque cell's CKB capacity to go back to the sender's lock. An output paying that CKB to the receiver fails with Cheque error 8 (SenderCapacityNotSame). So the Cheque lock cannot be used to deliver plain CKB to the receiver, and in this project's tests it also blocked an owner placed in the receiver role from reclaiming their own CKB.","note":"","patterns":["assert!(err.to_string().contains(\"error code 8\"), \"expected Cheque error 8, got: {err}\");"],"concepts":["Testing and devnet","Capacity and cell size"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-11-09","last_touched":"2026-11-09","level":"working","why":"A claim transaction that pays the Cheque cell's CKB to the receiver is rejected with Cheque error 8, so a design that counts on the Cheque lock to hand plain CKB to the receiver cannot work.","sources":[{"repo":"salmansarwarr/Tranfr","hash":"d9a32aa6bc","date":"2026-11-09"}],"tests":[{"repo":"salmansarwarr/Tranfr","hash":"d9a32aa6bc","files":["tests/src/composition.rs","tests/src/lib.rs"]}],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"scripts/cheque-lock-sender-withdrawal-requires-exact-since-0xa000000","area":"scripts","title":"Cheque lock sender withdrawal requires exact since 0xA000000000000006","lesson":"The deployed Cheque lock (RFC 0039) accepts a sender withdrawal only when the Cheque input's since is exactly 0xA000000000000006 (relative epoch, 6 epochs after the cell was committed). A since of 0 fails with Cheque error 11 (WithdrawChequeInputSinceError), so the sender cannot reclaim for about 24h after each create or renew.","note":"","patterns":["prefer: const CHEQUE_SENDER_SINCE: u64 = 0xA000_0000_0000_0006;"],"concepts":["Since and time locks","Testing and devnet"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-11-09","last_touched":"2026-11-09","level":"working","why":"A sender withdrawal built with since 0 (or any other value) is rejected by the Cheque lock with error 11, and the sender cannot reclaim the cell until 6 epochs after it was committed.","sources":[{"repo":"salmansarwarr/Tranfr","hash":"69c024281b","date":"2026-11-09"}],"tests":[{"repo":"salmansarwarr/Tranfr","hash":"69c024281b","files":["tests/src/composition.rs"]}],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"scripts/ckb-blake160-is-the-first-20-bytes-of-the-32-byte-ckbhash","area":"scripts","title":"CKB blake160 is the first 20 bytes of the 32 byte ckbhash","lesson":"CKB blake160, used for lock args and pubkey hashes, is the first 20 bytes of the 32 byte blake2b digest personalized with \"ckb-default-hash\". A blake2b hasher configured with a 20 byte output length gives a different value, because the digest length is part of blake2b's parameter block. Always hash to 32 bytes and then truncate.","note":"","patterns":["avoid: let mut hasher = blake2b_ref::Blake2bBuilder::new(20).personal(b\"ckb-default-hash\").build();"],"concepts":["Data encoding (molecule, hex, bigints)","Witnesses and signatures"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-10-09","last_touched":"2026-10-09","level":"basic","why":"Lock args derived from a 20 byte blake2b digest do not match the pubkey hash that the secp256k1 blake160 lock checks, so cells sent to that lock cannot be unlocked.","sources":[{"repo":"Tactus-Labs/tactus-o1","hash":"1bbd9e5e25","date":"2026-10-09"}],"tests":[{"repo":"Tactus-Labs/tactus-o1","hash":"1bbd9e5e25","files":["crates/tactus-ordering-script/tests/hash_oracle.rs"]}],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"scripts/ckb-vm2-read-and-inherited-fds-syscalls-take-a-length-pointe","area":"scripts","title":"CKB VM2 READ and INHERITED_FDS syscalls take a length pointer and return status in a0","lesson":"In CKB VM2, READ takes (fd, buffer_addr, length_addr) and INHERITED_FDS takes (buffer_addr, length_addr), with *length_addr set to the buffer capacity before the ecall. The syscall returns only a status in a0 (0 on success) and writes the delivered byte count or fd count back through length_addr, so never treat a0 as the payload. After checking a0, handle short pipe reads by looping or failing explicitly, and bounds-check an INHERITED_FDS index against the smaller of the returned count and the capacity you passed.","note":"","patterns":["prefer: // READ takes (fd, buffer_addr, length_addr): the scheduler writes the payload to the buffer and the delivered byte count back through length_addr, with SUCCESS in a0."],"concepts":["Other"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-10-29","last_touched":"2026-10-29","level":"advanced","why":"A bare ecall passes garbage in a1/a2 and returns the status word as if it were the data, so the script reads wrong values or faults.","sources":[{"repo":"CellScript-Labs/CellScript","hash":"96ceedad95","date":"2026-10-29"}],"tests":[{"repo":"CellScript-Labs/CellScript","hash":"96ceedad95","files":["services/registry-api/test/sql-registry-store.test.ts","tests/deferred_ckb_semantics.rs","tests/examples.rs"]}],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"scripts/ckb-std-c-shim-needs-a-risc-v-c-toolchain-clang-in-ci","area":"scripts","title":"ckb-std C shim needs a RISC-V C toolchain (clang) in CI","lesson":"ckb-std compiles a C shim for riscv64imac-unknown-none-elf via cc-rs, which by default looks for riscv64-unknown-elf-gcc and fails with ToolNotFound when that toolchain is missing in CI. Pointing cc-rs at clang and llvm-ar (which can target RISC-V) lets the contract build without the GCC cross toolchain.","note":"","patterns":[],"concepts":["Testing and devnet"],"applies_to":[],"status":"current","evidence":"L2","first_seen":"2026-11-02","last_touched":"2026-11-02","level":"working","why":"Without a RISC-V C compiler configured, cc-rs cannot find riscv64-unknown-elf-gcc. The contract build fails with ToolNotFound on every CI run, so the contract tests never run.","sources":[{"repo":"LusoCryptoLabs/Liquid-Cells","hash":"d65e94160e","date":"2026-11-02"}],"tests":[],"related":[],"confirmed":{"by":"LusoCryptoLabs","role":"owner","date":"2026-11-19"},"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"scripts/ckb-testtool-runs-scripts-only-so-node-transaction-verifiers","area":"scripts","title":"ckb-testtool runs scripts only, so node transaction verifiers must be added in tests","lesson":"ckb-testtool's Context::verify_tx runs scripts only, so a test can pass with a transaction the node rejects. Build a Consensus from the bundled mainnet chain spec and run ckb-verification's NonContextualTransactionVerifier, CapacityVerifier and DaoScriptSizeVerifier, plus DaoCalculator::transaction_fee for DAO withdraw balance, and add your own checks for inputs below occupied capacity, a cell spent twice and a malformed since (time-dependent maturity can be skipped). Run these on rejected transactions too, so a rejection test fails only for the script rule it targets, or explicitly names the node rule it overlaps.","note":"","patterns":["prefer: let spec = ChainSpec::load_from(&Resource::bundled(\"specs/mainnet.toml\".to_string())).expect(\"mainnet spec\");"],"concepts":["Testing and devnet","Capacity and cell size"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-11-02","last_touched":"2026-11-02","level":"working","why":"Without the node verifiers, fixtures can build transactions the node would reject (an output below occupied capacity, outputs exceeding inputs), so passing or rejection tests prove nothing about the scripts.","sources":[{"repo":"ickb/contracts","hash":"5d7ff56387","date":"2026-11-02"}],"tests":[{"repo":"ickb/contracts","hash":"5d7ff56387","files":["scripts/tests/Cargo.toml","scripts/tests/mainnet/ickb_mainnet.py","scripts/tests/src/tests.rs","scripts/tests/src/tests/fixtures.rs","scripts/tests/src/tests/fuzz.rs"]}],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"scripts/close-spawn-pipe-descriptors-when-an-ipc-channel-is-freed","area":"scripts","title":"Close spawn pipe descriptors when an IPC channel is freed","lesson":"A pipe fd created by ckb_pipe or inherited through spawn stays live until ckb_close is called on it, and the VM limits how many descriptors can be live at once. Code that creates channels repeatedly must therefore close both pipe ends when finished. In ckb-script-ipc, csi_free_channel did not close them before PR #32; it now closes the library-owned pipe fds, and the peer's ckb_read then returns CKB_OTHER_END_CLOSED.","note":"","patterns":[],"concepts":["Other"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-11-09","last_touched":"2026-11-09","level":"working","why":"Without closing, a script that repeatedly opens channels leaks pipe descriptors and hits the VM's descriptor limit (the test cycles 160 fds with only four live), so later ckb_pipe calls fail.","sources":[{"repo":"XuJiandong/ckb-script-ipc","hash":"216f11cf86","date":"2026-11-09"}],"tests":[{"repo":"XuJiandong/ckb-script-ipc","hash":"216f11cf86","files":["c/tests/client.c","c/tests/regression.c","c/tests/server.c","crates/ckb-script-ipc/tests/generate.rs","tests/src/tests_c_impl.rs"]}],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"scripts/comparing-packed-epoch-values","area":"scripts","title":"Comparing packed epoch values","lesson":"Decode epochs into (number, index, length) before comparing them. Compare the fractional parts by cross-multiplying (index_a*length_b vs index_b*length_a), because epoch length varies and raw packed integers don't order correctly.","note":"","patterns":["term_over = tip_n > term_n or (tip_n == term_n and tip_i*term_l >= term_i*tip_l); since = hex(0x2000000000000000 | epoch)"],"concepts":["Since and time locks"],"applies_to":[],"status":"current","evidence":"L1","first_seen":"2026-11-18","last_touched":"2026-11-18","level":"working","why":"Without decoding, a test or script judges epoch maturity wrongly, because the packed layout puts length and index above the epoch number. The daowow test would then expect an Immature refusal after the savings term had already ended.","sources":[{"repo":"toastmanAu/daowow","hash":"3bc8a826da","date":"2026-11-18"},{"repo":"salmansarwarr/Tranfr","hash":"1a6b06df4e","date":"2026-10-01"}],"tests":[{"repo":"toastmanAu/daowow","hash":"3bc8a826da","files":["tests/devnet/reorg_history.py","tests/devnet/test_round_creation.py"]},{"repo":"salmansarwarr/Tranfr","hash":"1a6b06df4e","files":["tests/src/tests.rs"]}],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"scripts/creation-witness-for-an-output-type-script-goes-in-witnessar","area":"scripts","title":"Creation witness for an output type script goes in WitnessArgs.output_type","lesson":"A type script that checks a newly created output can read its proof from WitnessArgs.output_type, but the script decides which witness to read: tactus-o1's state proof script loads absolute witness 0 (Source::Input, index 0), not a witness matched to the output index. If that witness is also the first witness of the secp lock group, put the proof in its output_type field next to the 65 byte lock placeholder, and it is covered by the lock signature because the sighash keeps the other WitnessArgs fields and zeroes only the lock.","note":"","patterns":[],"concepts":["Witnesses and signatures"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-10-10","last_touched":"2026-10-10","level":"working","why":"If the proof is added after signing, or put in a separate witness the lock does not hash, the signature either fails to verify or does not commit to the proof the type script checks.","sources":[{"repo":"Tactus-Labs/tactus-o1","hash":"766983ff21","date":"2026-10-10"}],"tests":[],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"partly right","against_commit":true}},{"id":"scripts/delegating-script-validation-via-exec-to-a-hash-bound-cell-d","area":"scripts","title":"Delegating script validation via exec to a hash bound cell dep","lesson":"This lifecycle type script stores a 32 byte data hash in its args, scans cell deps with load_cell_data_hash to find exactly one match (rejecting duplicates), then calls ckb_std syscalls::exec on that dep, which keeps the current Script context (GroupInput, GroupOutput, args) for the child. Because exec only returns when it fails, any code after the call must return an error instead of falling through to success.","note":"","patterns":["prefer: let _ = syscalls::exec(parent, Source::CellDep, 0, 0, &[]); Err(Error::Exec)"],"concepts":["Cell deps and script lookup","Type ID and upgrades"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-10-04","last_touched":"2026-10-04","level":"working","why":"If code after exec falls through to success, a failed exec (for example a missing or invalid dep at that index) lets the transaction pass with no child validation at all, and without the uniqueness check an ambiguous dep set picks an unintended executable.","sources":[{"repo":"CellScript-Labs/CellScript","hash":"6616384b1b","date":"2026-10-04"}],"tests":[{"repo":"CellScript-Labs/CellScript","hash":"6616384b1b","files":["contracts/zk-private-counter/tests/admission.rs","contracts/zk-private-counter/tests/application.rs","contracts/zk-private-counter/tests/node.rs","contracts/zk-private-counter/tests/support/mod.rs"]}],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"scripts/disable-overflow-checks-for-ckb-std-when-using-its-dummy-ato","area":"scripts","title":"Disable overflow checks for ckb-std when using its dummy-atomic polyfills","lesson":"When a release profile sets overflow-checks = true and ckb-std (here =1.1.0 with the dummy-atomic feature) supplies the single-thread __atomic polyfills, add a per-package override turning overflow checks off for ckb-std. Atomic read/modify/write arithmetic is defined to wrap, so checked arithmetic in those polyfills would panic instead of wrapping.","note":"","patterns":["prefer: [profile.release.package.ckb-std] overflow-checks = false"],"concepts":["Other"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-10-07","last_touched":"2026-10-07","level":"advanced","why":"With workspace-wide overflow checks, wrapping atomic arithmetic inside ckb-std's polyfills could trap instead of wrapping and abort the guest.","sources":[{"repo":"CellScript-Labs/AgoraSeal","hash":"0ec10d11b3","date":"2026-10-07"}],"tests":[{"repo":"CellScript-Labs/AgoraSeal","hash":"0ec10d11b3","files":["crates/protocol/tests/replay.rs"]}],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"partly right","against_commit":true}},{"id":"scripts/enable-molecule-bytes-vec-so-ckb-std-scripts-contain-no-atom","area":"scripts","title":"Enable molecule bytes_vec so ckb-std scripts contain no atomic instructions","lesson":"With ckb-std 0.16, molecule's default Bytes uses the external bytes crate, which emits lr.d/sc.d atomic instructions that the CKB VM rejects, so the built lock script was not executable on chain. Adding molecule 0.8 with default-features = false and features = [\"bytes_vec\"] to the script crate makes feature unification swap in molecule's Vec-backed Bytes, and the commit reports the artifact then had zero atomic instructions.","note":"","patterns":["prefer: molecule = { version = \"0.8\", default-features = false, features = [\"bytes_vec\"] }"],"concepts":["Other"],"applies_to":[],"status":"current","evidence":"L2","first_seen":"2026-09-30","last_touched":"2026-10-22","level":"working","why":"Without the bytes_vec feature, the external bytes crate's atomic refcounting compiles into the RISC-V script, so the CKB VM cannot execute the deployed script and cells locked by it cannot be unlocked on chain.","sources":[{"repo":"wraith-protocol/contracts","hash":"2cba86fa1f","date":"2026-09-30"},{"repo":"LusoCryptoLabs/vortx-swap","hash":"e180fff173","date":"2026-10-22"}],"tests":[{"repo":"wraith-protocol/contracts","hash":"2cba86fa1f","files":["ckb/integration-tests/tests/lock_integration.rs"]},{"repo":"LusoCryptoLabs/vortx-swap","hash":"e180fff173","files":["scripts/e2e/aggregator-otx.mjs","scripts/e2e/concurrency.mjs","scripts/e2e/otx-joyid-real.mjs","scripts/e2e/otx-testnet.mjs","scripts/e2e/run.mjs"]}],"related":[],"confirmed":{"by":"LusoCryptoLabs","role":"owner","date":"2026-11-19"},"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"scripts/handle-none-from-ckb-sdk-since-extract-metric-for-invalid-si","area":"scripts","title":"Handle None from ckb_sdk Since::extract_metric for invalid since values","lesson":"A raw since u64 can carry the reserved metric flag 0b11 (e.g. 0x6000_0000_0000_0000), for which ckb_sdk::Since::extract_metric() returns None, and a timestamp metric value can exceed what chrono can represent. Code that formats since values received from RPC should handle both cases instead of unwrapping, as ckb-cli now does by printing \"invalid since\" or \"invalid\".","note":"","patterns":["avoid: let (ty, inner_value) = since.extract_metric().unwrap();"],"concepts":["Since and time locks","Data encoding (molecule, hex, bigints)"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-11-09","last_touched":"2026-11-09","level":"working","why":"Calling unwrap on extract_metric or on chrono conversions makes a tool panic when it is given a since value with the reserved 0b11 metric flag or a huge timestamp, so it fails instead of showing the value.","sources":[{"repo":"nervosnetwork/ckb-cli","hash":"ccca1c9c37","date":"2026-11-09"}],"tests":[],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"scripts/iterating-group-inputs-and-outputs-with-ckb-std-until-indexo","area":"scripts","title":"Iterating group inputs and outputs with ckb-std until IndexOutOfBound","lesson":"In a ckb-std script, walk the cells of a source with the high-level loaders, for example load_cell_type_hash(i, Source::GroupInput) or load_cell_lock_hash(j, Source::Output), in an index loop. Break on Err(SysError::IndexOutOfBound), and return a script error code for any other SysError. Accumulate the u64 capacities you load in a u128 so that a sum over many cells cannot overflow.","note":"","patterns":["prefer: Err(SysError::IndexOutOfBound) => break,"],"concepts":["Capacity and cell size","Cell deps and script lookup"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-11-08","last_touched":"2026-11-08","level":"working","why":"Without the IndexOutOfBound break the loop has no clean end condition, and treating every load error as the end of the list would hide real syscall failures.","sources":[{"repo":"salmansarwarr/Tranfr","hash":"66f9fc460d","date":"2026-11-08"}],"tests":[{"repo":"salmansarwarr/Tranfr","hash":"66f9fc460d","files":["sdk/tests/client.test.ts","sdk/tests/scaffold.test.ts","tests/src/tests.rs"]}],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"scripts/keep-other-witnessargs-fields-when-signing-sighash-all-in-te","area":"scripts","title":"Keep other WitnessArgs fields when signing sighash_all in tests","lesson":"When a test signer for the secp256k1 sighash_all lock fills the first witness of a script group, it should parse the existing WitnessArgs (for example one with data in output_type) and replace only the lock field: zeroed to 65 bytes while hashing, then set to the signature. Building a fresh WitnessArgs drops output_type or input_type data that a type script reads, and sighash_all hashes the whole first witness with only the lock zeroed, so those fields must already be in place when hashing.","note":"","patterns":["prefer: let zero_lock = existing.clone().as_builder().lock(Some(Bytes::from(vec![0u8; 65])).pack()).build();"],"concepts":["Witnesses and signatures","Testing and devnet"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-10-20","last_touched":"2026-10-20","level":"working","why":"A signer that writes a fresh WitnessArgs silently drops the data a type script reads from output_type or input_type, here the stake owner's consent signature, so the registry script rejects the transaction. If those fields were added after signing instead, the sighash_all signature would no longer match.","sources":[{"repo":"ckb-service-runner/ckb-service-runner","hash":"84f510ccfb","date":"2026-10-20"}],"tests":[{"repo":"ckb-service-runner/ckb-service-runner","hash":"84f510ccfb","files":["acceptance/a8/p1.test.mjs","contracts/csr-contract-tests/tests/job.rs","contracts/csr-contract-tests/tests/registry.rs"]}],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"scripts/median-time-vs-tip-timestamp-for-deadlines","area":"scripts","title":"Median time vs tip timestamp for deadlines","lesson":"On-chain since checks use the median time of past blocks, but clients often use the tip header's timestamp, and the two can diverge widely after devnet time travel. Compute deadlines from max(ceil(tipMs/1000), medianSeconds) so minimum-term checks hold on both sides.","note":"","patterns":["deadline = medianSeconds() + term  →  deadline = max(ceil(tipMs/1000), medianSeconds()) + term"],"concepts":["Since and time locks","Testing and devnet"],"applies_to":[],"status":"current","evidence":"L1","first_seen":"2026-11-15","last_touched":"2026-11-15","level":"working","why":"If the deadline is computed from the median time alone, a client that measures the minimum term from the tip timestamp rejects the deadline as too short. This happens after devnet time travel, when the tip runs far ahead of the median.","sources":[{"repo":"psawyerberlin/ckb-revocable-timelock","hash":"6c847e2bf8","date":"2026-11-15"},{"repo":"toastmanAu/openswap","hash":"f6365e0bd6","date":"2026-10-29"},{"repo":"toastmanAu/openswap","hash":"06072bd809","date":"2026-10-29"}],"tests":[{"repo":"toastmanAu/openswap","hash":"f6365e0bd6","files":["sdk/test/v2-vm-bridge.ts","solver/test/v2.test.ts"]},{"repo":"toastmanAu/openswap","hash":"06072bd809","files":["frontend/test/pool-wallet-helper.ts","frontend/test/pools.spec.ts","sdk/test/frontend-review.test.ts"]}],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"scripts/minimum-capacity-of-a-cell-depends-on-its-lock-args-length","area":"scripts","title":"Minimum capacity of a cell depends on its lock args length","lesson":"A cell with no type and no data needs at least 8 (capacity) + 32 (code hash) + 1 (hash type) + args length in CKB: 61 CKB for a secp256k1_blake160 lock (20-byte args), 63 CKB for a JoyID lock with 22-byte args. A contract that knows a recipient lock only by hash cannot measure it, so a hardcoded floor for the fee output must be at least the largest lock it may face on each network, and a test should measure the real lock against it. Otherwise the fee output cannot be built.","note":"","patterns":[],"concepts":["Capacity and cell size"],"applies_to":[],"status":"current","evidence":"L2","first_seen":"2026-10-30","last_touched":"2026-10-30","level":"working","why":"If a contract hardcodes a capacity floor below what the recipient lock actually occupies, it demands an output too small for consensus to accept, so the fee output cannot be built and the operation that requires it (here registration) can never succeed.","sources":[{"repo":"LusoCryptoLabs/cells-contracts","hash":"16290d959f","date":"2026-10-30"},{"repo":"LusoCryptoLabs/cells-contracts","hash":"011f33b57a","date":"2026-10-30"}],"tests":[],"related":[],"confirmed":{"by":"LusoCryptoLabs","role":"owner","date":"2026-11-19"},"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"scripts/molecule-hash-type-byte-values","area":"scripts","title":"Molecule hash_type byte values","lesson":"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.","note":"","patterns":["const HASH_TYPE_DATA2: u8 = 2; // wrong, 2 is data1; correct value is 4"],"concepts":["Data encoding (molecule, hex, bigints)","Indexer queries and cell collection","Testing and devnet"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-11-15","last_touched":"2026-11-15","level":"working","why":"With data2 encoded as 2, the service built a data1 script that matched no cell, so its Node Cell query found nothing and every run reported dropped; the mock chain used the same constant on both sides and never caught it.","sources":[{"repo":"psawyerberlin/ckb-revocable-timelock","hash":"a37fb85ada","date":"2026-11-15"}],"tests":[],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"scripts/parse-raw-ckb-blocks-with-from-compatible-slice-to-accept-bl","area":"scripts","title":"Parse raw CKB blocks with from_compatible_slice to accept BlockV1 extension","lesson":"Serialized CKB blocks may be BlockV1, which appends a consensus extension field after the Block molecule fields, so a strict packed::BlockReader::from_slice can reject them. This commit parses block bytes with ckb-gen-types 1.1.1 packed::BlockReader::from_compatible_slice, which accepts the extra field while still exposing header() and transactions().","note":"","patterns":["prefer: packed::BlockReader::from_compatible_slice(bytes).map_err(|_| Error::Encoding)?;"],"concepts":["Data encoding (molecule, hex, bigints)"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-10-07","last_touched":"2026-10-07","level":"working","why":"Without the compatible reader, any serialized block that carries the BlockV1 extension fails to parse, so the replay aborts with an encoding error instead of reading the header and transactions.","sources":[{"repo":"CellScript-Labs/AgoraSeal","hash":"d0032d7b71","date":"2026-10-07"}],"tests":[{"repo":"CellScript-Labs/AgoraSeal","hash":"d0032d7b71","files":["crates/protocol/tests/replay.rs"]}],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"scripts/partial-load-of-a-cell-s-type-script-header-to-match-code-ha","area":"scripts","title":"Partial load of a cell's type Script header to match code_hash and hash_type","lesson":"In a ckb-std script you can load a cell's type script into a fixed 49 byte buffer with syscalls::load_cell_by_field(..., CellField::Type), then compare code_hash at bytes 16..48 and hash_type at byte 48 of the molecule Script table, without allocating for args. A short buffer returns Err(SysError::LengthNotEnough) yet still fills the buffer, so treat that error like Ok, and treat ItemMissing as a cell with no type script.","note":"","patterns":["prefer: Ok(_) | Err(SysError::LengthNotEnough(_)) => { if b[16..48] == script.code_hash().as_slice()[..] && b[48] == script.hash_type().as_slice()[0]"],"concepts":["Data encoding (molecule, hex, bigints)","Cell deps and script lookup"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-10-07","last_touched":"2026-10-07","level":"advanced","why":"Loading the full type Script of every input and output allocates for arbitrary, attacker-sized args, and treating LengthNotEnough as a failure would wrongly reject cells whose script header was in fact read correctly.","sources":[{"repo":"wamimi/noir-ckb-verifier","hash":"6930573c90","date":"2026-10-07"}],"tests":[],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"scripts/passing-a-pipe-to-a-spawned-child-script-via-a-zero-terminat","area":"scripts","title":"Passing a pipe to a spawned child script via a zero-terminated inherited_fds list","lesson":"When a lock spawns a verifier script from a cell dep with ckb-std 1.1.0 syscalls::spawn, it creates a pipe and passes the read fd in SpawnArgs.inherited_fds as an array ending in 0. After writing the full request, the parent closes write_fd so the child's read returns 0 or OtherEndClosed (end of input), then uses syscalls::wait(pid) == 0 as the verification result.","note":"","patterns":[],"concepts":["Cell deps and script lookup","Other"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-10-22","last_touched":"2026-10-22","level":"advanced","why":"If the parent never closes the write end, the child's final end-of-input read cannot return 0 or OtherEndClosed, so the verifier rejects the request as malformed or blocks waiting for data.","sources":[{"repo":"toastmanAu/ckb-crypto-agile-account-reference-v0.1","hash":"36e7a89d70","date":"2026-10-22"}],"tests":[{"repo":"toastmanAu/ckb-crypto-agile-account-reference-v0.1","hash":"36e7a89d70","files":["crates/host/tests/abi_v1_conformance.rs","crates/host/tests/config.rs","crates/host/tests/encoding.rs","crates/host/tests/identity.rs","demo/test/browser/demo.spec.ts"]}],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"partly right","against_commit":true}},{"id":"scripts/place-a-script-s-raw-witness-at-the-index-of-the-input-it-va","area":"scripts","title":"Place a script's raw witness at the index of the input it validates","lesson":"When a type script reads its proof with load_witness(index, Source::Input) for its own input, the builder must put that raw witness at exactly that input's index. This commit puts the ledger cell at input 0 so its proof is witness 0, and pads the remaining witnesses with \"0x\" so witnesses.length equals inputs.length and a later funding/signing step appends rather than displaces it.","note":"","patterns":["prefer: witnesses: [hex0x(ledgerWitness.encodeLedgerWitness(records)), ...entryCells.map(() => \"0x\"), \"0x\"]"],"concepts":["Witnesses and signatures","Transaction building and fees"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-09-25","last_touched":"2026-09-25","level":"working","why":"If the proof sits at any other witness index, the type script's load_witness(index, Source::Input) reads the wrong or empty bytes and the transaction is refused. An unpadded witness list also lets a later funding or signing step shift or overwrite the proof slot.","sources":[{"repo":"toastmanAu/daowow","hash":"25c2b9e5ad","date":"2026-09-25"}],"tests":[{"repo":"toastmanAu/daowow","hash":"25c2b9e5ad","files":["apps/web/test/aggregate-tx.test.js","apps/web/test/entry-codec.test.js"]}],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"scripts/porting-the-sighash-all-signing-message-into-a-rust-lock-scr","area":"scripts","title":"Porting the sighash_all signing message into a Rust lock script","lesson":"To reproduce secp256k1_blake160_sighash_all's message in a ckb-std lock, hash with ckb blake2b: tx hash, then the first GroupInput witness parsed as WitnessArgs with its lock field zero filled (same length) and u64 LE length prefixed, then the other GroupInput witnesses, then every Source::Input witness at index >= the total input count (each length prefixed). The commit counts inputs by probing load_input_since until IndexOutOfBound.","note":"","patterns":["prefer: let modified = witness_args.as_builder().lock(Some(zeroed_lock).pack()).build();"],"concepts":["Witnesses and signatures"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-09-29","last_touched":"2026-09-29","level":"working","why":"If any step differs (wrong lock zeroing length, missing u64 LE length prefixes, or skipping the group or extra witnesses), the computed message will not match what standard sighash_all signers produce, so valid signatures fail to verify or extra witnesses go unsigned.","sources":[{"repo":"salmansarwarr/Tranfr","hash":"ed87f9da80","date":"2026-09-29"}],"tests":[],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"scripts/raw-cell-deps-indexes-match-source-celldep-only-before-the-f","area":"scripts","title":"Raw cell_deps indexes match Source::CellDep only before the first dep group","lesson":"When a script reads the raw transaction's cell_deps (via load_transaction) and uses a position there as a Source::CellDep index for load_cell_type_hash or load_cell_data, the mapping holds only for the leading run of dep_type code entries, because dep groups expand into their member cells and shift later indexes. This vote script restricts its proposal and deposit lookups to that direct prefix and lets wallet dep groups follow it.","note":"","patterns":["prefer: .take_while(|dep| dep.dep_type().as_slice() == [0])"],"concepts":["Cell deps and script lookup"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-10-07","last_touched":"2026-10-07","level":"advanced","why":"Once a dep group sits before the wanted dep, a raw cell_deps position reads a different resolved cell, so the script checks the wrong proposal or deposit data, or fails.","sources":[{"repo":"CellScript-Labs/AgoraSeal","hash":"b7b2ae50dd","date":"2026-10-07"}],"tests":[{"repo":"CellScript-Labs/AgoraSeal","hash":"b7b2ae50dd","files":["crates/protocol/tests/reference_vote_vm.rs","crates/protocol/tests/replay.rs","crates/protocol/tests/treasury_vm.rs"]}],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"partly right","against_commit":true}},{"id":"scripts/read-cell-data-hash-from-the-consensus-data-hash-field-inste","area":"scripts","title":"Read cell data hash from the consensus DATA_HASH field instead of hashing loaded data","lesson":"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.","note":"","patterns":[],"concepts":["Data encoding (molecule, hex, bigints)","Capacity and cell size"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-10-27","last_touched":"2026-10-27","level":"working","why":"A script that hashes loaded data in a fixed 512-byte buffer fails on any cell whose data is longer than the buffer.","sources":[{"repo":"CellScript-Labs/CellScript","hash":"0ca9f6f345","date":"2026-10-27"}],"tests":[{"repo":"CellScript-Labs/CellScript","hash":"0ca9f6f345","files":["tests/artifact_checker/bounded_admission.rs","tests/runtime_read_bounds.rs","tests/stack_layout.rs","tests/syntax_combo/matrix.toml"]}],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"partly right","against_commit":true}},{"id":"scripts/recognising-a-nervos-dao-deposit-cell-referenced-as-a-stake","area":"scripts","title":"Recognising a Nervos DAO deposit cell referenced as a stake cell dep","lesson":"A Nervos DAO deposit cell has the DAO type script (code hash 0x82d76d1b75fe2fd9a27dfbaa65a039221a380d76c926f378d3f81cf3e7e13f2e, hash_type type, empty args) and 8 zero bytes of data; a withdrawing cell has the same type script but the deposit block number as data. A contract that accepts one as a cell dep must check code hash, hash_type, empty args and data == 8 zero bytes, since the DAO script does not run for a dep. For the same reason a ckb_testtool test can create such cells directly with the DAO type script and zero data, without deploying the DAO binary.","note":"","patterns":[],"concepts":["Cell deps and script lookup","Testing and devnet"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-10-20","last_touched":"2026-10-20","level":"working","why":"Without these checks, a withdrawing DAO cell or a lookalike cell under another type script could be accepted as a stake, because nothing re-validates a cell that is only referenced as a dep.","sources":[{"repo":"ckb-service-runner/ckb-service-runner","hash":"29943dd9ff","date":"2026-10-20"}],"tests":[{"repo":"ckb-service-runner/ckb-service-runner","hash":"29943dd9ff","files":["acceptance/a7/p1.test.mjs","contracts/csr-contract-tests/tests/float.rs","contracts/csr-contract-tests/tests/harness.rs","contracts/csr-contract-tests/tests/job.rs","contracts/csr-contract-tests/tests/registry.rs"]}],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"scripts/relative-block-number-since-uses-top-byte-0x80-not-the-absol","area":"scripts","title":"Relative block number since uses top byte 0x80, not the absolute epoch 0x20","lesson":"Under RFC 0017 since encoding, bit 63 marks relative and bits 61 to 62 select the metric (00 is block number), so a relative block count is RELATIVE_BLOCK_FLAG (0x8000000000000000) OR the count, and 256 blocks becomes 0x8000000000000100. In this commit the type script checks since >> 56 == 0x80, so reusing the absolute epoch form (top byte 0x20) is rejected on chain with an error code that does not name the since as the cause.","note":"","patterns":["prefer: return RELATIVE_BLOCK_FLAG | n;"],"concepts":["Since and time locks"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-10-02","last_touched":"2026-10-02","level":"working","why":"If the absolute epoch flag 0x20 is reused where the script expects a relative block number, the transaction is refused on chain with a generic script error that does not point at the since.","sources":[{"repo":"toastmanAu/daowow","hash":"b4f8a6f1e4","date":"2026-10-02"},{"repo":"toastmanAu/daowow","hash":"cb3c9ed950","date":"2026-10-02"}],"tests":[{"repo":"toastmanAu/daowow","hash":"b4f8a6f1e4","files":["apps/web/test/entropy-tx.test.js"]},{"repo":"toastmanAu/daowow","hash":"cb3c9ed950","files":["apps/web/test/lifecycle-rules.test.js"]}],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"partly right","against_commit":true}},{"id":"scripts/separate-builds-for-test-only-contract-constants","area":"scripts","title":"Separate builds for test-only contract constants","lesson":"Put test variants that change protocol constants behind a Cargo feature, built as a separate binary with its own code hash and deployment file. Client deployment parsing and deploy scripts should reject that variant on mainnet. Off-chain code should read the constant from the deployment rather than hardcode the default.","note":"","patterns":["#[cfg(feature=\"drill\")] const GRACE_SECONDS: u64 = 600; build into separate target dir/output path; parseDeployment throws if network_id==0 && (drill || grace_seconds!=86400); heartbeatJob(..., graceSeconds(d))"],"concepts":["Testing and devnet","Cell deps and script lookup","Type ID and upgrades"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-11-16","last_touched":"2026-11-16","level":"working","why":"If off-chain code assumes the default constant while the deployed script enforces the test value, heartbeat jobs are funded for the wrong term. A test binary could also be wired into a mainnet deployment by mistake.","sources":[{"repo":"psawyerberlin/ckb-revocable-timelock","hash":"d9c36e998b","date":"2026-11-16"}],"tests":[{"repo":"psawyerberlin/ckb-revocable-timelock","hash":"d9c36e998b","files":["client/test/chain.test.ts","client/test/tx.test.ts"]}],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"partly right","against_commit":true}},{"id":"scripts/treat-an-absent-witnessargs-lock-as-a-load-failure-in-ckb-st","area":"scripts","title":"Treat an absent WitnessArgs.lock as a load failure in ckb-std lock scripts","lesson":"With ckb-std, `load_witness_args(0, Source::GroupInput)` can succeed while `WitnessArgs.lock` is an empty BytesOpt, so call `lock().to_opt()` and return an error on None before reading `raw_data()`. The commit's ckb-testtool tests check both a missing witness and a WitnessArgs with no lock field, and both fail with the load witness error.","note":"","patterns":["prefer: let lock_opt = witness_args.lock().to_opt().ok_or(ERR_LOAD_WITNESS)?;"],"concepts":["Witnesses and signatures","Data encoding (molecule, hex, bigints)"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-09-25","last_touched":"2026-09-25","level":"working","why":"A WitnessArgs whose lock field is absent still deserializes successfully, so a script that only checks the load result will either panic on unwrap or run its signature logic against missing data instead of rejecting with a clear error code.","sources":[{"repo":"salmansarwarr/Tranfr","hash":"6c38d8aa68","date":"2026-09-25"}],"tests":[{"repo":"salmansarwarr/Tranfr","hash":"6c38d8aa68","files":["tests/src/tests.rs"]}],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"scripts/type-script-group-membership-and-group-witness-index-derived","area":"scripts","title":"Type Script group membership and group witness index derived from the full script hash","lesson":"When locating a Type Script group off chain, match input and output cells by the blake2b hash of the complete Script (code_hash, hash_type, args), never by code hash alone. By convention (RFC 22 for lock groups), a group's witness sits at the transaction index of its first input, or of its first output if the group has no inputs. CKB does not enforce this: the script picks which witness it reads, and which WitnessArgs field (input_type or output_type) holds the data is the protocol's own choice.","note":"","patterns":["prefer: output.type_script.as_ref().is_some_and(|script| hash(script.bytes) == selected_hash)"],"concepts":["Witnesses and signatures","Transaction building and fees"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-10-09","last_touched":"2026-10-09","level":"working","why":"If cells are matched by code hash alone, cells whose Type Scripts differ only in args or hash_type land in the group, so the off chain tool computes the wrong group members, cardinality and witness index compared with what the CKB VM executes.","sources":[{"repo":"CellScript-Labs/CellScript","hash":"dca23a27d0","date":"2026-10-09"}],"tests":[{"repo":"CellScript-Labs/CellScript","hash":"dca23a27d0","files":["tests/frozen_interface.rs","tests/policy_artifact_checker.rs"]}],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"scripts/use-raw-data-not-as-slice-when-parsing-a-packed-bytes-witnes","area":"scripts","title":"Use raw_data(), not as_slice(), when parsing a packed::Bytes witness","lesson":"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.","note":"","patterns":["prefer: is_secp_sighash_placeholder_witness(&witness.raw_data())"],"concepts":["Data encoding (molecule, hex, bigints)","Witnesses and signatures"],"applies_to":[],"status":"current","evidence":"L2","first_seen":"2026-10-29","last_touched":"2026-10-29","level":"working","why":"A placeholder check run over as_slice() includes the 4 byte molecule length header, so it never matches; Fiber's funding witness merge therefore failed to swap its own placeholder for the peer's real signature, which the new test asserts.","sources":[{"repo":"nervosnetwork/fiber","hash":"11846d65fe","date":"2026-10-29"},{"repo":"LusoCryptoLabs/ckb-script-pitfalls","hash":"3a5b53d279","date":"2026-10-29"}],"tests":[{"repo":"nervosnetwork/fiber","hash":"11846d65fe","files":["crates/fiber-lib/src/fiber/tests/channel.rs"]},{"repo":"LusoCryptoLabs/ckb-script-pitfalls","hash":"3a5b53d279","files":["code/tests/tests/pitfalls.rs"]}],"related":[],"confirmed":{"by":"LusoCryptoLabs","role":"owner","date":"2026-11-19"},"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"spore/finding-a-spore-or-cluster-by-id-through-the-indexer-s-get-t","area":"spore","title":"Finding a spore or cluster by id through the indexer's get_transactions","lesson":"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.","note":"Lookup by id via get_transactions, includes melted spores.","patterns":["prefer: { script: { code_hash: k.codeHash, hash_type: k.hashType, args: h }, script_type: \"type\", script_search_mode: \"exact\" }, \"asc\", \"0x1\""],"concepts":["Indexer queries and cell collection"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-10-30","last_touched":"2026-10-30","level":"working","why":"Looking a spore up through live cells alone (get_cells) misses spores that were melted, so a valid spore id would come back as not found.","sources":[{"repo":"wildanrhmn/ckb-devnet-explorer","hash":"2cd7e3c6cd","date":"2026-10-30"}],"tests":[],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"spore/set-cobuild-true-when-injecting-offckb-devnet-spore-scripts","area":"spore","title":"Set cobuild: true when injecting OffCKB devnet Spore scripts into createSpore","lesson":"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.","note":"cobuild: true needed for OffCKB devnet Spore scripts.","patterns":[],"concepts":["Cell deps and script lookup","Testing and devnet"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-10-28","last_touched":"2026-10-28","level":"working","why":"The OffCKB export carries no protocol mode, so a SporeScriptInfoLike copied straight from it leaves out the cobuild flag that the deployed Spore V2 binary's semantics call for.","sources":[{"repo":"Akane-CN/spark-verify","hash":"7c14d44c54","date":"2026-10-28"}],"tests":[{"repo":"Akane-CN/spark-verify","hash":"7c14d44c54","files":["tests/showcase-producer.test.ts"]}],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"tooling/absence-of-on-chain-references-does-not-mean-a-code-cell-is","area":"tooling","title":"Absence of on-chain references does not mean a code cell is safe to consume","lesson":"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.","note":"","patterns":["prefer: digest = hashlib.blake2b(path.read_bytes(), digest_size=32, person=b\"ckb-default-hash\").hexdigest()"],"concepts":["Type ID and upgrades","Indexer queries and cell collection","Cell deps and script lookup"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-09-20","last_touched":"2026-09-20","level":"working","why":"Reclaiming every unreferenced code cell would have consumed the current dao-lock deployment and forced a pointless redeploy, and consuming a code cell cannot be undone.","sources":[{"repo":"toastmanAu/daowow","hash":"c099737a3e","date":"2026-09-20"}],"tests":[],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"partly right","against_commit":true}},{"id":"tooling/charging-load-program-bytes-as-cycles-when-building-a-custom","area":"tooling","title":"Charging load_program bytes as cycles when building a custom ckb-vm machine","lesson":"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.","note":"","patterns":["prefer: machine.add_cycles_no_checking(transferred_byte_cycles(bytes))?;"],"concepts":["Testing and devnet","Other"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-11-03","last_touched":"2026-11-03","level":"advanced","why":"A hand-built ckb-vm machine that skips charging the loaded program bytes reports fewer cycles than on-chain verification does (the fib example showed 1361 instead of 3364), so cycle estimates and limits based on it are wrong.","sources":[{"repo":"nervosnetwork/ckb-standalone-debugger","hash":"e41bf0d75f","date":"2026-11-03"}],"tests":[{"repo":"nervosnetwork/ckb-standalone-debugger","hash":"e41bf0d75f","files":["ckb-debugger/tests/test_command.rs"]}],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"tooling/ckb-node-script-debug-logs-may-use-ckb-script-verify-target","area":"tooling","title":"CKB node script debug logs may use ckb_script::verify target, not only ckb-script","lesson":"When filtering a CKB node's run.log or log subscription for contract debug output (ckb_debug / debug! syscalls), records can come with target `ckb_script` or a `ckb_script::` submodule such as `ckb_script::verify` rather than the legacy `ckb-script` target. For those targets, match only messages containing `DEBUG OUTPUT:`, because the same target also emits ordinary verification lines.","note":"","patterns":["prefer: const isCkbScriptTarget = entry.target === 'ckb_script' || entry.target.startsWith('ckb_script::'); return isCkbScriptTarget && entry.message.includes('DEBUG OUTPUT:');"],"concepts":["Testing and devnet"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-10-08","last_touched":"2026-10-08","level":"working","why":"A log filter that matches only the `ckb-script` target silently drops contract debug output that the node emits under `ckb_script::verify`, so developers see no script logs at all; matching the module target without the `DEBUG OUTPUT:` marker would flood them with ordinary verification lines instead.","sources":[{"repo":"ckb-devrel/offckb","hash":"d510dae013","date":"2026-10-08"}],"tests":[{"repo":"ckb-devrel/offckb","hash":"d510dae013","files":["tests/logs-command.test.ts","tests/logs.test.ts","tests/node-quiet-mode.test.ts"]}],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"tooling/ckb-cli-deploy-gen-txs-does-not-check-the-block-size-limit","area":"tooling","title":"ckb-cli deploy gen-txs does not check the block size limit","lesson":"`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.","note":"","patterns":["prefer: const BLOCK_SIZE_LIMIT = 597000; const estimate = total + OVERHEAD_BASE + OVERHEAD_PER_CELL * files.length;"],"concepts":["Transaction building and fees","Capacity and cell size"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-09-18","last_touched":"2026-09-18","level":"working","why":"The deployer signs a transaction that gen-txs reported as successful, and only learns at broadcast that the node refuses it with ExceededMaximumBlockBytes because the combined binaries push it past the 597,000 byte block size limit.","sources":[{"repo":"toastmanAu/daowow","hash":"c9e4a38181","date":"2026-09-18"}],"tests":[],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"tooling/ckb-cli-deploy-info-file-layout-for-offline-multisig-signing","area":"tooling","title":"ckb-cli deploy info file layout for offline multisig signing","lesson":"A `ckb-cli deploy` info file is JSON with snake_case JSON-RPC transactions `cell_tx` and `dep_group_tx` (either may be null), `used_input_txs` (previous transactions by hash, so inputs resolve offline), signature maps `cell_tx_signatures` and `dep_group_tx_signatures` (lock args to a list of 65-byte signatures), and `deployment.multisig_config` with `sighash_addresses`, `require_first_n`, `threshold` and `lock_code_hash`. Each member address is a full-format sighash address whose args are the member's key hash; the list can be empty when the default config is used, so check for that before building the multisig script.","note":"","patterns":[],"concepts":["Transaction building and fees","Witnesses and signatures"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-11-08","last_touched":"2026-11-08","level":"working","why":"A tool that misreads this layout cannot resolve inputs offline from used_input_txs and cannot match collected signatures to the right transaction and lock args. If it ignores that ckb-cli's default config has no sighash_addresses, it ends up building a multisig script with no members.","sources":[{"repo":"ILE-Labs/ckb-msig","hash":"fc8f3736ab","date":"2026-11-08"}],"tests":[],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"tooling/ckb-cli-needs-skip-check-to-sign-and-send-transactions-with","area":"tooling","title":"ckb-cli needs --skip-check to sign and send transactions with custom locks","lesson":"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.","note":"Joined with toastmanAu/daowow@6f4cb48641.","patterns":["prefer: --from-account ${OPERATOR_LOCK_ARG} --add-signatures --skip-check"],"concepts":["Witnesses and signatures","Transaction building and fees"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-09-26","last_touched":"2026-09-26","level":"working","why":"Without --skip-check on sign-inputs, ckb-cli leaves the signatures map and witness empty, and the node rejects the transaction with -2 ERROR_ENCODING when the secp lock reads an unsigned witness.","sources":[{"repo":"toastmanAu/daowow","hash":"4f6e7addae","date":"2026-09-26"},{"repo":"toastmanAu/daowow","hash":"6f4cb48641","date":"2026-09-25"}],"tests":[],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"tooling/ckb-cli-tx-init-overwrites-an-existing-tx-file-with-an-empty","area":"tooling","title":"ckb-cli tx init overwrites an existing tx file with an empty skeleton","lesson":"`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`.","note":"","patterns":["prefer: fs.writeFileSync(outFile, JSON.stringify({ transaction: tx, multisig_configs: {}, signatures: {} }, null, 2));"],"concepts":["Transaction building and fees","Witnesses and signatures"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-09-23","last_touched":"2026-09-23","level":"working","why":"Running `tx init` on a prepared transaction file replaces it with an empty skeleton and still reports success, so the transaction is lost and the later steps produce no result.","sources":[{"repo":"toastmanAu/daowow","hash":"8925a30900","date":"2026-09-23"}],"tests":[],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"tooling/ckb-cli-tx-sign-inputs-stores-signatures-in-the-file-s-signa","area":"tooling","title":"ckb-cli tx sign-inputs stores signatures in the file's signatures map, not witness 0","lesson":"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.","note":"","patterns":["prefer: const recorded = Object.entries(doc.signatures ?? {}).find(([arg]) => arg.toLowerCase() === expectedLockArg);"],"concepts":["Witnesses and signatures","Transaction building and fees"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-09-23","last_touched":"2026-09-23","level":"working","why":"A pre-send checker that looks only at witness 0 reports a properly signed ckb-cli tx file as unsigned, because the signature lives in the file's signatures map until `tx send` assembles it.","sources":[{"repo":"toastmanAu/daowow","hash":"f7d6061a31","date":"2026-09-23"}],"tests":[],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"tooling/ckb-debugger-verifies-one-script-group-per-run","area":"tooling","title":"ckb-debugger verifies one script group per run","lesson":"`full` is a VM mode, and by default ckb-debugger runs only input 0's lock, which may be an always-success lock. To check a whole transaction, enumerate every input lock, input type and output type group, run each with --script-group-type/--cell-type/--cell-index, and sum the cycles. Pair each accepted case with a control that must fail with an exact error code.","note":"","patterns":["spawn ckb-debugger --tx-file mock.json (no group selection) and treat exit 0 as the whole tx passing"],"concepts":["Testing and devnet","Transaction building and fees"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-11-14","last_touched":"2026-11-14","level":"working","why":"Running ckb-debugger on a mock tx without selecting script groups only executes input 0's lock, so a test can pass on an always-success lock (634 cycles) while the contract scripts never run, and the cycle budget is mismeasured.","sources":[{"repo":"toastmanAu/daowow","hash":"234509881c","date":"2026-11-14"}],"tests":[{"repo":"toastmanAu/daowow","hash":"234509881c","files":["apps/web/test/claim-debugger.test.js"]}],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"tooling/ckb-vm-js-0-2-0-npm-checks-header-hash-instead-of-rejecting","area":"tooling","title":"ckb-vm-js 0.2.0 (npm) checks header hash instead of rejecting the field","lesson":"With ckb-vm-js 0.2.0 from npm, verifyScriptGroup accepts an RPC header in context.tip_header that carries its own hash only when that hash matches the recomputed one, and fails with \"header hash does not match\" otherwise (the earlier vendored build rejected any `hash` field as unknown). Dropping `hash` before passing RPC headers or transactions remains safe because the verifier recomputes it.","note":"No existing lesson covers how ckb-vm-js treats a hash field on RPC headers.","patterns":["prefer: const { hash: _, ...rest } = o as Record<string, unknown>;"],"concepts":["Testing and devnet","Data encoding (molecule, hex, bigints)"],"applies_to":[],"status":"current","evidence":"L2","first_seen":"2026-11-17","last_touched":"2026-11-17","level":"working","why":"If a header's hash field disagrees with the recomputed hash, verifyScriptGroup fails with a request error (\"header hash does not match\") rather than running the script, and builds from before npm 0.2.0 failed on any hash field at all.","sources":[{"repo":"LusoCryptoLabs/ckb-ward","hash":"d884042975","date":"2026-11-17"}],"tests":[{"repo":"LusoCryptoLabs/ckb-ward","hash":"d884042975","files":["tests/ckbvmjs.test.ts"]}],"related":[],"confirmed":{"by":"LusoCryptoLabs","role":"owner","date":"2026-11-19"},"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"tooling/decoding-invaliddepgroup-outpoints","area":"tooling","title":"Decoding InvalidDepGroup OutPoints","lesson":"InvalidDepGroup prints the OutPoint in molecule encoding: a 32-byte tx_hash followed by a 4-byte little-endian index. Reverse the index bytes, then match only dep_group cell_deps on both tx_hash and index.","note":"","patterns":["parse InvalidDepGroup(OutPoint(0x<64 hex><8 hex LE index>)), reverse the index bytes, match against dep_group cell_deps"],"concepts":["Cell deps and script lookup","Data encoding (molecule, hex, bigints)"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-11-16","last_touched":"2026-11-16","level":"working","why":"If the hex index is read as written, an index like 02000000 decodes as 0x2000000 instead of 2, and matching code cell deps as well wrongly blames a dep that shares the same outpoint, so the failing dependency group cannot be located.","sources":[{"repo":"Hanssen0-Alter-Ego/ckb-vm-js","hash":"9b881ea6dd","date":"2026-11-16"}],"tests":[{"repo":"Hanssen0-Alter-Ego/ckb-vm-js","hash":"9b881ea6dd","files":["tests/browser/workbench.spec.js","tests/js/guided.test.js"]}],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"tooling/derive-devnet-spore-and-system-script-cell-deps-from-a-fresh","area":"tooling","title":"Derive devnet Spore and system script cell deps from a fresh OffCKB export","lesson":"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.","note":"","patterns":[],"concepts":["Cell deps and script lookup","Testing and devnet"],"applies_to":[],"status":"current","evidence":"L1","first_seen":"2026-09-29","last_touched":"2026-09-29","level":"working","why":"Hardcoded devnet out points and code hashes go stale when the OffCKB devnet changes, so the CCC client and the Spore SDK end up pointing at wrong or missing cell deps and transactions fail.","sources":[{"repo":"LusoCryptoLabs/docs.nervos.org","hash":"2177e4046a","date":"2026-09-29"},{"repo":"nervosnetwork/docs.nervos.org","hash":"2177e4046a","date":"2026-09-29"}],"tests":[{"repo":"LusoCryptoLabs/docs.nervos.org","hash":"2177e4046a","files":["examples/dApp/create-dob/scripts/devnet-lumos-config.test.cjs","examples/dApp/create-dob/scripts/sync-devnet-system-scripts.test.cjs","examples/dApp/simple-lock/scripts/deploy.test.js","examples/dApp/simple-lock/tests/frontend-transaction.test.ts","examples/dApp/simple-transfer/scripts/sync-devnet-system-scripts.test.cjs"]},{"repo":"nervosnetwork/docs.nervos.org","hash":"2177e4046a","files":["examples/dApp/create-dob/scripts/devnet-lumos-config.test.cjs","examples/dApp/create-dob/scripts/sync-devnet-system-scripts.test.cjs","examples/dApp/simple-lock/scripts/deploy.test.js","examples/dApp/simple-lock/tests/frontend-transaction.test.ts","examples/dApp/simple-transfer/scripts/sync-devnet-system-scripts.test.cjs"]}],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"partly right","against_commit":true}},{"id":"tooling/devnet-commits-need-the-proposal-window","area":"tooling","title":"Devnet commits need the proposal window","lesson":"On a devnet a transaction is not committed as soon as you send it: it must be proposed in one block and committed in a later one inside the proposal window, so a fixed small number of mined blocks can still leave the old cell state. Before asserting, mine a couple of blocks at a time in a bounded loop and re-read the cell state until it equals the expected value or the retry limit is reached.","note":"","patterns":["send(tx); const after = await readState(); assert(after...) → loop { mine(2); re-read } until the state matches or N tries are used up"],"concepts":["Testing and devnet"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-11-15","last_touched":"2026-11-15","level":"working","why":"Without the bounded mine and re-read loop, the assertion can read the cell state before the Renew transaction is committed and fail with the old deadline, even though the transaction is valid.","sources":[{"repo":"psawyerberlin/ckb-revocable-timelock","hash":"6fc513b339","date":"2026-11-15"}],"tests":[],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"tooling/emit-shannon-u64-values-as-strings-in-cross-language-test-ve","area":"tooling","title":"Emit shannon u64 values as strings in cross-language test vectors","lesson":"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.","note":"","patterns":["prefer: \"principal_total\": oracle_shard.principal_total.to_string(),"],"concepts":["Testing and devnet","Data encoding (molecule, hex, bigints)"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-09-18","last_touched":"2026-09-18","level":"working","why":"Without string encoding, u64 amounts above 2^53 are silently rounded in the JSON oracle, so the JavaScript decoder gets pinned to a wrong value and its tests still pass.","sources":[{"repo":"toastmanAu/daowow","hash":"48f4c2f4e4","date":"2026-09-18"}],"tests":[{"repo":"toastmanAu/daowow","hash":"48f4c2f4e4","files":["crates/daowow-core/tests/gen_vectors.rs"]}],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"not CKB specific","against_commit":true}},{"id":"tooling/forcing-a-real-ckb-devnet-reorg-via-p2p-partition-rpcs","area":"tooling","title":"Forcing a real CKB devnet reorg via P2P partition RPCs","lesson":"To force a real reorg between two Dummy devnet nodes without truncate or submit_block, call set_network_active(false) and remove_node on both, let the main node commit its transactions, then on the peer spend one input that those transactions consume and mine a longer branch with generate_block. Reconnect with set_network_active(true) on both and add_node, and treat convergence as reached only when get_tip_header and tx_pool_info.tip_hash both equal the winning hash on both nodes. Because the peer branch spent that input, the orphan transactions stay out of the chain and the pool, and replaying one of them fails with TransactionFailedToResolve (code -301).","note":"","patterns":["prefer: rpc::call(\"tx_pool_info\", json!([]))?[\"tip_hash\"] == *expected"],"concepts":["Testing and devnet"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-10-10","last_touched":"2026-10-10","level":"advanced","why":"Without a conflicting spend on the winning branch, detached transactions can come back through the tx pool and be recommitted, so no rollback is observed. Without waiting for tx_pool_info.tip_hash, checks may run before the pool has processed the reorg.","sources":[{"repo":"Tactus-Labs/tactus-o1","hash":"f5b29e5e55","date":"2026-10-10"}],"tests":[],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"partly right","against_commit":true}},{"id":"tooling/identify-script-groups-by-type-and-hash","area":"tooling","title":"Identify script groups by type and hash","lesson":"In CKB the same script hash can be both a lock script group and a type script group in one transaction, and each group has its own input and output indices. When selecting or reporting a script group, for example from a verifier's group list, match on group type together with script hash, never on the hash alone.","note":"","patterns":[],"concepts":["Witnesses and signatures","Other"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-11-16","last_touched":"2026-11-16","level":"working","why":"Matching by hash alone can return the lock group's members when the type group was selected (or the reverse), so the tool reports the wrong inputs and outputs for the verified group.","sources":[{"repo":"Hanssen0-Alter-Ego/ckb-vm-js","hash":"dba4f30053","date":"2026-11-16"}],"tests":[{"repo":"Hanssen0-Alter-Ego/ckb-vm-js","hash":"dba4f30053","files":["tests/browser/workbench.spec.js","tests/js/guided.test.js"]}],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"tooling/matching-a-script-code-hash-to-its-code-cell-by-hash-type","area":"tooling","title":"Matching a Script code_hash to its code Cell by hash_type","lesson":"To check that a Script points at a given deployed code Cell, compare its code_hash with ckb blake2b256 of the Cell's output data when hash_type is data, data1 or data2 (0, 2, 4), and with the hash of that Cell's Type Script when hash_type is type (1). A type selection needs the code Cell to actually carry a Type Script, and other hash_type values are rejected.","note":"","patterns":["prefer: 0 | 2 | 4 => artifact, 1 => type_hash.ok_or_else(|| invalid(\"Type-hash selection has no actual code Cell Type Script\"))?,"],"concepts":["Cell deps and script lookup","Data encoding (molecule, hex, bigints)"],"applies_to":[],"status":"current","evidence":"L1","first_seen":"2026-10-09","last_touched":"2026-10-09","level":"working","why":"Comparing a code_hash against the wrong preimage, such as the ELF hash for a type-mode Script or a type hash for a data-mode Script, wrongly rejects a correct binding or accepts the wrong code Cell. A type selection also fails when the Cell has no Type Script.","sources":[{"repo":"CellScript-Labs/CellScript","hash":"8ea6105ecb","date":"2026-10-09"},{"repo":"salmansarwarr/Kirea-finance","hash":"ca92dc4ce1","date":"2026-10-06"}],"tests":[{"repo":"CellScript-Labs/CellScript","hash":"8ea6105ecb","files":["tests/policy_artifact_checker.rs"]}],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"tooling/mirror-on-chain-rules-off-chain-with-mutation-tests","area":"tooling","title":"Mirror on-chain rules off-chain with mutation tests","lesson":"A CKB script that refuses a transaction returns only an error code that names no rule, so port the contract's witness decoders to JS with the same refusals (bad version, truncation, trailing bytes, count or size limits). Check that they round-trip bytes produced by the Rust code. Before signing, run a checker that re-derives the contract's rules from the finished transaction, and pin each rule with a mutation test that breaks one field of a valid transaction and expects that rule's named reason.","note":"","patterns":["decode(bytes) throws on cut-short / trailing bytes / bad version like the Rust decoder; tests do `breakIt(clone(tx)); assert reasons.some(r => /expected/.test(r))`"],"concepts":["Testing and devnet","Data encoding (molecule, hex, bigints)","Since and time locks"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-11-13","last_touched":"2026-11-13","level":"working","why":"Without an off-chain mirror, a malformed witness or broken rule only shows up as an opaque script error code at submission, with no indication of which rule failed.","sources":[{"repo":"toastmanAu/daowow","hash":"330c212fcd","date":"2026-11-13"}],"tests":[{"repo":"toastmanAu/daowow","hash":"330c212fcd","files":["apps/web/test/entitlements.test.js","apps/web/test/payout-tx.test.js","apps/web/test/settlement-rules.test.js","tests/devnet/js_settlement.mjs","tests/devnet/js_settlement.py"]}],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"tooling/mock-syscalls-must-write-back-output-length","area":"tooling","title":"Mock syscalls must write back output length","lesson":"When a ckb-vm mock or fuzzing syscall layer implements inherited_fds, it must store the fd count back into length_addr with store64 after writing the fd buffer. Otherwise the script reads back the capacity it passed in and treats unwritten slots as fds. ckb-vm-contrib's fuzzing utils lacked this until v1.1.2.","note":"","patterns":["syscall handler writes data to the buffer but never calls machine.memory_mut().store64(&length_addr, wrote_length)"],"concepts":["Testing and devnet"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-11-16","last_touched":"2026-11-16","level":"advanced","why":"Without the write back, a script running under the mock sees the capacity it passed in as the fd count and diverges from real CKB behaviour.","sources":[{"repo":"nervosnetwork/ckb-vm-contrib","hash":"872b7a50ba","date":"2026-11-16"}],"tests":[],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"tooling/mock-transactions-must-expand-dep-group-members","area":"tooling","title":"Mock transactions must expand dep_group members","lesson":"In a ckb-debugger mock_info, list the dep_group cell with dep_type \"dep_group\" (data included) and also list each member out point as a separate cell dep with dep_type \"code\", with its data. Get the members by decoding the group cell's data as a molecule OutPoint vector: a u32 LE count, then per entry a 32-byte tx hash and a u32 LE index (36 bytes each), and check that the length is 4 + 36*count bytes.","note":"","patterns":["mockTxOf: for dep_group cell_deps, push the group cell and then push each member parsed from groupMembers(data) as dep_type 'code' into mock_info.cell_deps"],"concepts":["Testing and devnet","Cell deps and script lookup","Data encoding (molecule, hex, bigints)"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-11-14","last_touched":"2026-11-14","level":"working","why":"ckb-debugger resolves a dep group only from the cells listed in mock_info, so if the member cells are missing it cannot load the scripts the group points to and the dry run fails.","sources":[{"repo":"toastmanAu/daowow","hash":"b1ba07d485","date":"2026-11-14"}],"tests":[{"repo":"toastmanAu/daowow","hash":"b1ba07d485","files":["apps/web/test/dry-run-claims.test.js"]}],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"tooling/output-type-scripts-need-cell-deps-too-including-the-native","area":"tooling","title":"Output type scripts need cell deps too, including the native DAO type","lesson":"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.","note":"","patterns":["prefer: ...tx.outputs.map((o, i) => ({ where: `Outputs[${i}].Type`, script: o.type })),"],"concepts":["Cell deps and script lookup","Transaction building and fees"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-10-05","last_touched":"2026-10-05","level":"basic","why":"A DAO deposit built without the DAO type's code cell as a dep is rejected by the node with ScriptNotFound on Outputs[i].Type, and pre-send checks that look only at input locks pass it anyway.","sources":[{"repo":"toastmanAu/daowow","hash":"87eedee1ea","date":"2026-10-05"}],"tests":[{"repo":"toastmanAu/daowow","hash":"87eedee1ea","files":["apps/web/test/aggregate-tx.test.js"]}],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"tooling/pass-wasm-bytes-to-ckb-vm-js-createverifier-in-node","area":"tooling","title":"Pass wasm bytes to ckb-vm-js createVerifier in Node","lesson":"In Node, calling ckb-vm-js createVerifier() with no arguments fails with \"fetch failed\" because it cannot fetch its .wasm from a file URL. Read the bytes from the package's ckb-vm-js/wasm export (via import.meta.resolve and readFile) and pass them as createVerifier({ wasm }).","note":"New Node loading detail for ckb-vm-js wasm.","patterns":["prefer: return ckbVmJs({ verifier: await vmjs.createVerifier({ wasm }), rpcUrl });"],"concepts":["Testing and devnet"],"applies_to":[],"status":"current","evidence":"L2","first_seen":"2026-11-17","last_touched":"2026-11-17","level":"working","why":"Without the bytes, a Node service that relies on the default ckb-vm-js verifier fails at startup with \"fetch failed\", and tests that inject their own verifier never catch it.","sources":[{"repo":"LusoCryptoLabs/ckb-ward","hash":"f71b5b4d32","date":"2026-11-17"}],"tests":[{"repo":"LusoCryptoLabs/ckb-ward","hash":"f71b5b4d32","files":["tests/bind-server.test.ts"]}],"related":[],"confirmed":{"by":"LusoCryptoLabs","role":"owner","date":"2026-11-19"},"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"tooling/pin-js-cell-data-encoders-and-decoders-to-rust-generated-vec","area":"tooling","title":"Pin JS cell data encoders and decoders to Rust generated vectors","lesson":"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.","note":"Joined with toastmanAu/daowow@e08898943c.","patterns":["prefer: assert.strictEqual(got.minimumTickets, BigInt(f.minimum_tickets), \"minimumTickets\");"],"concepts":["Data encoding (molecule, hex, bigints)","Testing and devnet"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-09-18","last_touched":"2026-09-22","level":"working","why":"A JS codec checked only against its own expectations or a size check can read or write a neighbouring offset and still produce a plausible number of the right length, so the browser builds or reports cells the on chain script reads differently, and Number would silently round shannon amounts above 2^53.","sources":[{"repo":"toastmanAu/daowow","hash":"ff459d0294","date":"2026-09-18"},{"repo":"toastmanAu/daowow","hash":"e08898943c","date":"2026-09-22"}],"tests":[{"repo":"toastmanAu/daowow","hash":"ff459d0294","files":["apps/web/test/codec.test.js"]},{"repo":"toastmanAu/daowow","hash":"e08898943c","files":["apps/web/test/entry-codec.test.js","crates/daowow-core/tests/gen_vectors.rs"]}],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"tooling/port-ckb-s-sparse-merkle-tree-byte-for-byte","area":"tooling","title":"Port CKB's sparse-merkle-tree byte for byte","lesson":"nervosnetwork/sparse-merkle-tree folds runs of empty siblings into MergeWithZero nodes (merge byte 2; a normal merge uses byte 1 plus height and parent path), and bit 0 of a key is the low bit of byte 0. Compiled proofs use the opcodes 0x4c, 0x50, 0x51, 0x4f n (n=0 means 256) and 0x48. Test any off-chain port against vectors generated by the Rust code.","note":"","patterns":["Port smt merge/compile/compute_root byte for byte (MERGE_NORMAL=1, MERGE_ZEROS=2, parent_path clears bits 0..=height) and test it against Rust-generated root and proof vectors."],"concepts":["Data encoding (molecule, hex, bigints)","Testing and devnet"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-11-14","last_touched":"2026-11-14","level":"advanced","why":"A port that follows a textbook sparse Merkle tree, or gets the bit order or merge prefixes wrong, produces roots and proofs that the on-chain Rust verifier rejects.","sources":[{"repo":"toastmanAu/daowow","hash":"b2681e9fe0","date":"2026-11-14"}],"tests":[{"repo":"toastmanAu/daowow","hash":"b2681e9fe0","files":["apps/web/test/smt.test.js"]}],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"tooling/profile-spawned-scripts-with-the-right-elf-symbols","area":"tooling","title":"Profile spawned scripts with the right ELF symbols","lesson":"In ckb-debugger full mode with spawn, coverage, flamegraph and overlap analysis now use the ELF of the VM chosen with --vm-id instead of the root program. Pass an unstripped binary with --vm-symbols to get symbols and debug info.","note":"Older ckb-debugger versions profile spawned children with the root program's symbols, so their profiles are wrong.","patterns":["MachineFlamegraph::new(&verifier_program_elf) -> MachineFlamegraph::new(&machine_program_elf or --vm-symbols file)"],"concepts":["Testing and devnet"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-11-16","last_touched":"2026-11-16","level":"working","why":"Before this change, full-mode coverage, flamegraph and overlap reports for a spawned child VM were built from the root program's ELF. The child's addresses were resolved against the wrong symbols, so the profile of that script was misleading.","sources":[{"repo":"nervosnetwork/ckb-standalone-debugger","hash":"8cecb5dfac","date":"2026-11-16"}],"tests":[{"repo":"nervosnetwork/ckb-standalone-debugger","hash":"8cecb5dfac","files":["ckb-debugger/tests/test_command.rs"]}],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"tooling/release-asset-names-differ-per-ckb-tool","area":"tooling","title":"Release asset names differ per CKB tool","lesson":"ckb, ckb-cli and ckb-debugger use `<tool>_<tag>_<triple>[-portable].<ext>`, while fnn and ckb-light-client use `<tool>_<tag>-<arch>-<os>[-portable].tar.gz`. ckb-debugger ships .tar.gz on every OS with a `<stem>-sha256.txt` and has no x86_64 macOS build, and ckb-cli ships .zip on macOS and Windows with no sums file. Try an ordered list of candidate names, including portable variants, against the release's actual asset list.","note":"","patterns":[],"concepts":["Other"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-11-11","last_touched":"2026-11-14","level":"working","why":"A single fixed asset name returns nothing for fnn, ckb-light-client, zip-packaged ckb or ckb-cli, and portable-only builds, so the installer fails even though a usable binary is published.","sources":[{"repo":"steven3002/ckbup","hash":"c6cec9e80e","date":"2026-11-14"},{"repo":"steven3002/ckbup","hash":"090351a14a","date":"2026-11-11"}],"tests":[],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"partly right","against_commit":true}},{"id":"tooling/reset-devnets-instead-of-skewing-the-chain-clock","area":"tooling","title":"Reset devnets instead of skewing the chain clock","lesson":"Pushing devnet timestamps ahead leaves the chain clock skewed for every later run, which stalls services that compare the tip with wall time. Reset the devnet for each scenario. At the start, assert that |tip timestamp − now| is small, for example under 600 s.","note":"","patterns":["start-up step that advances median time +1h and mines blocks on a long-lived devnet -> reset the devnet and add a precondition asserting chain-clock skew < 600 s"],"concepts":["Testing and devnet","Since and time locks"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-11-15","last_touched":"2026-11-15","level":"working","why":"Without a reset and the precondition, a rerun on the same devnet starts with the chain clock hours or days ahead, so the runners idle and the scenario fails with timeouts instead of a clear message.","sources":[{"repo":"psawyerberlin/ckb-revocable-timelock","hash":"41facee756","date":"2026-11-15"}],"tests":[],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"partly right","against_commit":true}},{"id":"tooling/saved-transaction-test-vectors-go-stale-when-their-cell-deps","area":"tooling","title":"Saved transaction test vectors go stale when their cell deps are spent","lesson":"A saved CKB transaction lists its cell deps by out point. A replay that resolves those deps as live cells, as a node does when it verifies a new transaction, stops working once a lock upgrade or redeployment spends a dep cell, although neither the saved transaction nor the verifier changed. A replay test should tell that case (a dep that is no longer live) apart from a real verification failure, and skip the vector with a note instead of reporting a defect.","note":"","patterns":[],"concepts":["Testing and devnet","Cell deps and script lookup"],"applies_to":[],"status":"current","evidence":"L2","first_seen":"2026-11-09","last_touched":"2026-11-09","level":"working","why":"Without the check, every test on a vector whose dep cell was spent by an upgrade or redeployment fails, and that failure looks like a verifier bug even though the verifier is correctly refusing dead deps.","sources":[{"repo":"LusoCryptoLabs/ckb-ward","hash":"c47c417698","date":"2026-11-09"}],"tests":[{"repo":"LusoCryptoLabs/ckb-ward","hash":"c47c417698","files":["tests/vectors.test.ts"]}],"related":[],"confirmed":{"by":"LusoCryptoLabs","role":"owner","date":"2026-11-19"},"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"tooling/script-hash-type-selects-the-vm-version-data2-4-or-type-1-fo","area":"tooling","title":"Script hash_type selects the VM version: data2 (4) or type (1) for a VM2 target","lesson":"CKB picks the VM version from the Script hash_type: data (0) runs VM0, data1 (2) runs VM1, data2 (4) runs VM2, and type (1) runs the latest activated VM. Code deployed for VM2 and pinned by data hash must be referenced with hash_type data2. The same code hash with data or data1 still resolves to the same cell but runs under an older VM, so tooling should reject those hash types for a VM2 target rather than only checking that the code hash matches.","note":"","patterns":["prefer: \"ckb\" => Some(\"data2\"), \"ckb-type-hash\" => Some(\"type\"),"],"concepts":["Cell deps and script lookup","Type ID and upgrades"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-10-09","last_touched":"2026-10-09","level":"working","why":"A script whose code hash matches but whose hash_type is data or data1 still resolves to the code cell, yet it silently runs under an older VM than the code was built for.","sources":[{"repo":"CellScript-Labs/CellScript","hash":"35a9565b26","date":"2026-10-09"}],"tests":[{"repo":"CellScript-Labs/CellScript","hash":"35a9565b26","files":["tests/frozen_interface.rs","tests/policy_artifact_checker.rs"]}],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"tooling/separate-submit-and-commit-verification-environments","area":"tooling","title":"Separate submit and commit verification environments","lesson":"When verifying a transaction offline with ckb-script, use TxVerifyEnv::new_submit(&tip) for the submit phase. It evaluates since at tip number + 1 + proposal_window.closest, so it is more permissive than inclusion in the next block. For the commit phase, use TxVerifyEnv::new_commit(&candidate), where candidate is a header whose parent_hash is the real tip and whose number is tip + 1, and take median time from env.parent_hash() rather than tip.parent_hash().","note":"","patterns":["Treating tip_header as the candidate block and using TxVerifyEnv::new_commit(&tip) with median time taken from tip.parent_hash(), instead of separate submit and commit environments where the commit candidate is a verified direct child of the real tip."],"concepts":["Since and time locks","Testing and devnet"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-11-12","last_touched":"2026-11-12","level":"advanced","why":"Treating the tip as the candidate block evaluates block and median time since locks at the wrong height, so a transaction can be reported valid at submit and then be rejected as immature when it is actually committed.","sources":[{"repo":"Hanssen0-Alter-Ego/ckb-vm-js","hash":"ead067badf","date":"2026-11-12"}],"tests":[{"repo":"Hanssen0-Alter-Ego/ckb-vm-js","hash":"ead067badf","files":["tests/browser/manual.js","tests/browser/worker.spec.js","tests/js/types.ts"]}],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"tooling/shape-of-ckb-cli-deploy-sign-txs-output","area":"tooling","title":"Shape of ckb-cli deploy sign-txs output","lesson":"`ckb-cli deploy sign-txs` prints two maps, `cell_tx_signatures` and `dep_group_tx_signatures`, for the deploy info file's `cell_tx` and `dep_group_tx`. Each map goes from lock args (20 bytes, or 28 for multisig args with a since) to one 65 byte signature. It prints YAML-style text by default and a JSON object with `--output-format json`, and the YAML writer prints an empty map inline as `cell_tx_signatures: {}`, so a parser collecting multisig signatures must accept both shapes and the inline empty header.","note":"","patterns":["prefer: const HEADER = /^(cell_tx_signatures|dep_group_tx_signatures):\\s*(\\{\\s*\\})?$/;"],"concepts":["Witnesses and signatures","Data encoding (molecule, hex, bigints)"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-11-08","last_touched":"2026-11-08","level":"working","why":"A parser that expects only one output shape, or only block-style headers, misses sections or signatures. Collected signatures then get attached to the wrong deploy transaction or silently dropped.","sources":[{"repo":"ILE-Labs/ckb-msig","hash":"ba088f1884","date":"2026-11-08"}],"tests":[],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"tooling/use-bigint-for-uint64-rpc-quantities","area":"tooling","title":"Use BigInt for uint64 RPC quantities","lesson":"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.","note":"","patterns":["Number(value).toString(16) / parseInt(hex) for uint64 RPC fields → validate with /^[0-9]+$/, BigInt(value), check n < 1n<<64n, then `0x${n.toString(16)}`"],"concepts":["Data encoding (molecule, hex, bigints)"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-11-16","last_touched":"2026-11-16","level":"working","why":"Routing a cycles value such as 9007199254740993 through Number silently changes it, so the request sends a different max_cycles than the user typed, and values near 2^64 cannot be expressed at all.","sources":[{"repo":"Hanssen0-Alter-Ego/ckb-vm-js","hash":"26c8ff5d05","date":"2026-11-16"}],"tests":[{"repo":"Hanssen0-Alter-Ego/ckb-vm-js","hash":"26c8ff5d05","files":["tests/browser/workbench.spec.js","tests/js/workbench.test.js"]}],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"tooling/verify-header-deps-against-independently-fetched-headers-not","area":"tooling","title":"Verify header_deps against independently fetched headers, not against the tx's own list","lesson":"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.","note":"","patterns":["prefer: const h = await rpc.call(\"get_header_by_number\", [\"0x\" + n.toString(16)]);"],"concepts":["Since and time locks","Network and RPC reliability"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-10-02","last_touched":"2026-10-02","level":"working","why":"A checker that takes headers from the transaction's own header_deps would approve a transaction listing the wrong blocks, so wrong entropy inputs would reach the node marked safe to send.","sources":[{"repo":"toastmanAu/daowow","hash":"cc87c916af","date":"2026-10-02"}],"tests":[],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"tooling/wait-for-the-indexer-to-reach-the-block-before-truncating-th","area":"tooling","title":"Wait for the indexer to reach the block before truncating the devnet chain in reorg tests","lesson":"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.","note":"","patterns":["prefer: d.server_caught_up(n).await?;"],"concepts":["Testing and devnet","Indexer queries and cell collection"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-10-08","last_touched":"2026-10-08","level":"working","why":"If the devnet chain is truncated before the off-chain indexer has processed the inclusion block, the indexer never observes the rollback, so a reorg test waiting for one hangs until it times out on slow runners.","sources":[{"repo":"poshboytl/omavote","hash":"ef60e04b97","date":"2026-10-08"}],"tests":[],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"tooling/witnesses-do-not-follow-reordered-inputs","area":"tooling","title":"Witnesses do not follow reordered inputs","lesson":"Witnesses are matched to inputs by position: witness i belongs to input i, and a script reading GroupInput witnesses sees the witnesses at its group's input positions. Reordering inputs does not move the witnesses, so after reordering, check and rebuild the witness list so each input's position again holds the intended witness.","note":"","patterns":[],"concepts":["Witnesses and signatures","Transaction building and fees"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-11-16","last_touched":"2026-11-16","level":"working","why":"After an input reorder, a script group can read a witness meant for a different input, so verification can fail or check the wrong data.","sources":[{"repo":"Hanssen0-Alter-Ego/ckb-vm-js","hash":"476ad52aa5","date":"2026-11-16"}],"tests":[{"repo":"Hanssen0-Alter-Ego/ckb-vm-js","hash":"476ad52aa5","files":["tests/browser/workbench.spec.js","tests/js/guided.test.js"]}],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"wallets/address-balance-via-get-cells-capacity-with-snake-case-lock","area":"wallets","title":"Address balance via get_cells_capacity with snake_case lock script","lesson":"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.","note":"","patterns":["prefer: script: { code_hash: lock.codeHash, hash_type: lock.hashType, args: lock.args },"],"concepts":["Indexer queries and cell collection","Data encoding (molecule, hex, bigints)"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-10-15","last_touched":"2026-10-15","level":"working","why":"The node's JSON-RPC expects snake_case script fields, so passing the camelCase object that addressToScript returns gives an invalid params error and the balance lookup fails.","sources":[{"repo":"salmansarwarr/Kirea-finance","hash":"c6f16540fa","date":"2026-10-15"}],"tests":[],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"wallets/binding-an-off-chain-lock-proof-to-the-live-cell-deps-it-ran","area":"wallets","title":"Binding an off-chain lock proof to the live cell deps it ran with","lesson":"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.","note":"","patterns":["prefer: return { ok: true, fields, cycles: run.cycles, cellDeps };"],"concepts":["Cell deps and script lookup","Login and authorization"],"applies_to":[],"status":"current","evidence":"L2","first_seen":"2026-11-04","last_touched":"2026-11-04","level":"advanced","why":"Without the recorded out points, a binding keeps trusting a proof made under lock code or key cells that were later upgraded, rotated or recovered away.","sources":[{"repo":"LusoCryptoLabs/ckb-ward","hash":"e629115de9","date":"2026-11-04"}],"tests":[{"repo":"LusoCryptoLabs/ckb-ward","hash":"e629115de9","files":["tests/vectors.test.ts"]}],"related":[],"confirmed":{"by":"LusoCryptoLabs","role":"owner","date":"2026-11-19"},"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"wallets/count-only-empty-typeless-lock-cells-as-spendable-balance","area":"wallets","title":"Count only empty, typeless lock cells as spendable balance","lesson":"When computing a wallet's spendable balance from indexer cells under a lock, count only cells with empty output data and no type script as available. A cell with data or any type script (UDT, DOB, profile or attachment cells, not just your own type) holds state, so its capacity stays in the total but is reported as reserved, because spending it would destroy that state. In cemp-mobile this is `const hasData = cell.data !== \"0x\" && cell.data !== \"\"; const isProtocol = hasData || type !== null;`.","note":"","patterns":[],"concepts":["Indexer queries and cell collection","Capacity and cell size"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-10-31","last_touched":"2026-10-31","level":"working","why":"Without it, data-bearing or typed cells under the wallet's lock are counted as free capacity, so the available balance is overstated and spends or capacity checks can pick cells that hold protocol state.","sources":[{"repo":"toastmanAu/cemp-mobile","hash":"b432323bc3","date":"2026-10-31"}],"tests":[{"repo":"toastmanAu/cemp-mobile","hash":"b432323bc3","files":["packages/cemp-ckb/src/wallet.test.ts","packages/cemp-database/src/lifecycle.test.ts"]}],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"partly right","against_commit":true}},{"id":"wallets/dao-compensation-must-use-the-deposit-cell-s-occupied-capaci","area":"wallets","title":"DAO compensation must use the deposit cell's occupied capacity (102 CKB), not 61","lesson":"When calculating Nervos DAO max withdraw or compensation (here via the light client's nativeCalculateMaxWithdraw), pass the occupied capacity of the actual DAO deposit cell (102 CKB for a secp256k1 lock plus DAO type plus 8 bytes data), not the 61 CKB of a plain secp256k1 cell. Using 61 overstates the interest by (C - 61) / (C - 102), and the result no longer matches what the unlock transaction pays out.","note":"","patterns":["avoid: LightClientNative.nativeCalculateMaxWithdraw(origDepositHeader.dao, cellBlockHeader.dao, capacityShannons, 61_00000000L)"],"concepts":["Capacity and cell size"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-10-06","last_touched":"2026-10-06","level":"working","why":"Passing 61 CKB as the occupied capacity inflates every displayed DAO compensation by (C - 61) / (C - 102), so the wallet shows more interest than the unlock transaction actually pays out.","sources":[{"repo":"RaheemJnr/pocket-node","hash":"9c987c3f89","date":"2026-10-06"}],"tests":[{"repo":"RaheemJnr/pocket-node","hash":"9c987c3f89","files":["android/app/src/test/java/com/rjnr/pocketnode/data/gateway/DaoDepositReaderCompensationTest.kt","android/app/src/test/java/com/rjnr/pocketnode/data/gateway/GatewayRepositoryDaoUnlockTest.kt"]}],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"wallets/devnet-tests-need-a-real-secp256k1-lock-to-exercise-signing","area":"wallets","title":"Devnet tests need a real secp256k1 lock to exercise signing","lesson":"Under an always-success lock, a test never checks that the signature covers the witnesses. That matters most when contract data shares a WitnessArgs with the signature, for example in inputType. Move the test cells to a secp256k1 lock, using its code cell and dep group from genesis, and sign with ccc.SignerCkbPrivateKey. The 20-byte lock args need 6 more CKB of capacity than the 14-byte fixture args.","note":"","patterns":["Devnet tests that only used an always-success fixture lock. Now the cell is moved to a secp256k1 lock and the transaction is signed through the same app signing path."],"concepts":["Witnesses and signatures","Testing and devnet","Capacity and cell size"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-11-14","last_touched":"2026-11-14","level":"working","why":"Tests under an always-success lock pass even when the signed transaction would be rejected or when witness data such as inputType is not covered by the signature.","sources":[{"repo":"toastmanAu/daowow","hash":"5344cf9c6f","date":"2026-11-14"}],"tests":[{"repo":"toastmanAu/daowow","hash":"5344cf9c6f","files":["apps/web/test/app-shell.test.js","apps/web/test/model-copy.test.js","tests/devnet/js_claims.mjs","tests/devnet/js_claims.py","tests/devnet/test_js_lifecycle.py"]}],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"partly right","against_commit":true}},{"id":"wallets/do-not-detect-der-signatures-by-a-leading-0x30-byte","area":"wallets","title":"Do not detect DER signatures by a leading 0x30 byte","lesson":"When converting secp256k1 signatures to DER for a CKB contract (here the Perun channel script, which uses k256 and expects low-S), a 64 or 65 byte compact R||S(||V) signature can begin with 0x30 because R is arbitrary. Dispatch on the fixed lengths first, and parse anything else with a full asn1.Unmarshal that has no trailing bytes, followed by a check that R and S lie in [1, n).","note":"","patterns":["avoid: if len(sig) > 0 && sig[0] == 0x30 {"],"concepts":["Witnesses and signatures","Data encoding (molecule, hex, bigints)"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-11-10","last_touched":"2026-11-10","level":"working","why":"A compact signature whose R happens to start with 0x30 (about 1 in 256) was passed through untouched as if it were DER. That produced a malformed signature in the channel witness, which the contract cannot verify.","sources":[{"repo":"perun-network/perun-ckb-backend","hash":"aa7e377969","date":"2026-11-10"}],"tests":[{"repo":"perun-network/perun-ckb-backend","hash":"aa7e377969","files":["encoding/signature_test.go"]}],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"not CKB specific","against_commit":true}},{"id":"wallets/evm-owners-may-hold-omnilock-lock-args-with-auth-flag-0x12-n","area":"wallets","title":"EVM owners may hold Omnilock lock args with auth flag 0x12, not only 0x01","lesson":"When mapping an Ethereum address to the CKB lock scripts it controls, match Omnilock args 0x12 || addr20 || 0x00 (Ethereum displaying, used by CCC's EVM signer for new addresses) as well as 0x01 || addr20 || 0x00 and PW Lock args = addr20. Otherwise deposits held by CCC created EVM addresses are not recognised. The commit notes this is still pending confirmation in a wallet proof of concept.","note":"","patterns":["prefer: v.push(omni.with_args(omni_args(OMNILOCK_AUTH_ETHEREUM_DISPLAYING)));"],"concepts":["Witnesses and signatures","Login and authorization"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-10-08","last_touched":"2026-10-08","level":"working","why":"Without the 0x12 form, an EVM signature from a user whose deposit sits under a CCC-created Omnilock address fails the owner-lock match and is rejected, so that deposit is never counted.","sources":[{"repo":"poshboytl/omavote","hash":"dc90515eb4","date":"2026-10-08"}],"tests":[{"repo":"poshboytl/omavote","hash":"dc90515eb4","files":["crates/omavote-core/tests/vectors.rs"]}],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"wallets/joyid-lock-witness-outputtype-may-carry-a-subkey-proof-so-ty","area":"wallets","title":"JoyID lock witness outputType may carry a subkey proof, so type script data must move elsewhere","lesson":"When the funding wallet uses the JoyID lock, its WitnessArgs outputType may carry a subkey unlock proof, so do not put your own type script data in that witness's outputType. Place the type script action in another witness index and align the related output index with it. Size the fee estimate's signature placeholder for JoyID's larger witness (openswap uses 1000 bytes) instead of the 65 byte secp256k1 size.","note":"","patterns":["prefer: const stateIndex=wallet.witness?.kind==='joyid'?1n:0n;"],"concepts":["Witnesses and signatures","Transaction building and fees"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-10-22","last_touched":"2026-10-22","level":"working","why":"A JoyID subkey proof and the type script action would collide in the same outputType field, and a 65 byte placeholder underestimates the fee for the much larger JoyID witness.","sources":[{"repo":"toastmanAu/openswap","hash":"60e958bddc","date":"2026-10-22"}],"tests":[{"repo":"toastmanAu/openswap","hash":"60e958bddc","files":["frontend/test/activity.spec.ts","frontend/test/app.spec.ts","frontend/test/book.spec.ts","frontend/test/fixtures.ts","pool-model/test/model.test.ts"]}],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"wallets/joyid-signer-prices-fees-with-a-1-000-byte-signature-placeho","area":"wallets","title":"JoyID signer prices fees with a 1,000 byte signature placeholder","lesson":"With CCC and @ckb-ccc/joy-id, prepareTransaction fills the JoyID witness lock with a 1,000 byte placeholder before the fee is computed as ceil((serialized size + 4) x rate / 1000). The real signature is usually shorter (347 bytes in one testnet order), so the committed transaction is smaller and its measured rate is higher than the rate it was built at (7,278 against 5,000 shannons/KB). To recover the build rate, clone the transaction, set the JoyID witness lock back to 1,000 zero bytes, and compute the rate on that size, confirming with tx.estimateFee(rate) equal to the paid fee.","note":"","patterns":["prefer: witness.lock=ccc.hexFrom('00'.repeat(JOYID_PLACEHOLDER));priced.setWitnessArgs(at,witness);"],"concepts":["Transaction building and fees","Witnesses and signatures"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-10-30","last_touched":"2026-10-30","level":"working","why":"Measuring the fee rate on the signed transaction overstates the rate it was built at, so a fee policy check on a JoyID transaction would wrongly judge it as outside its rate range.","sources":[{"repo":"toastmanAu/openswap","hash":"3d6eb42a21","date":"2026-10-30"}],"tests":[],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"partly right","against_commit":true}},{"id":"wallets/joyid-sub-key-membership-is-checked-through-the-cota-aggrega","area":"wallets","title":"JoyID sub key membership is checked through the CoTA aggregator","lesson":"A JoyID passkey from a second device is a sub key, so deriving the JoyID lock from the signer's public key does not find the account. Given the account's address, call JoyID's CoTA aggregator method generate_subkey_unlock_smt with alg_index 1 (the passkey algorithm), pubkey_hash set to the first 20 bytes of ckbHash(pubkey) for the same pubkey bytes JoyID signs with, and lock_script set to the serialized lock; a non-empty result.unlock_entry means the key belongs to that account. The aggregator is trusted and its SMT proof is not checked against the chain, and the positive case was not run against a real sub key here.","note":"","patterns":["prefer: method: 'generate_subkey_unlock_smt', params: { alg_index: 1, pubkey_hash: ccc.hashCkb(pubkey).slice(0, 42), lock_script: ccc.hexFrom(lock.toBytes()) }"],"concepts":["Witnesses and signatures","Login and authorization"],"applies_to":[],"status":"current","evidence":"L2","first_seen":"2026-10-12","last_touched":"2026-10-12","level":"advanced","why":"A login check that only derives the JoyID lock from the signer's public key fails to recognise anyone signing with a sub key from a second device, so legitimate account holders are rejected.","sources":[{"repo":"LusoCryptoLabs/poi-onchain","hash":"a4455e3626","date":"2026-10-12"}],"tests":[],"related":[],"confirmed":{"by":"LusoCryptoLabs","role":"owner","date":"2026-11-19"},"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"wallets/joyid-sub-key-signatures-depend-on-the-live-cota-cell-dep-ho","area":"wallets","title":"JoyID sub key signatures depend on the live CoTA cell dep holding the sub key root","lesson":"A JoyID sub key (second device) signature is checked by the JoyID lock against the sub key root held in the account's CoTA cell, which the transaction carries as a cell dep. Adding a device spends that CoTA cell and creates a new one with a new root. Two separate things follow: a transaction that still lists the old CoTA out point has a cell dep that is no longer live, and the lock run against the old root data does not accept the sub key signature.","note":"JoyID specific: sub key root lives in the CoTA cell dep.","patterns":[],"concepts":["Cell deps and script lookup","Witnesses and signatures"],"applies_to":[],"status":"current","evidence":"L2","first_seen":"2026-11-06","last_touched":"2026-11-06","level":"advanced","why":"A sub key signature checked against a stale or spent CoTA cell is rejected, and a binding made before the device was added stops being valid from the block that spent the old CoTA cell.","sources":[{"repo":"LusoCryptoLabs/ckb-ward","hash":"8632fbb8e6","date":"2026-11-06"}],"tests":[{"repo":"LusoCryptoLabs/ckb-ward","hash":"8632fbb8e6","files":["tests/joyid-subkey.test.ts"]}],"related":[],"confirmed":{"by":"LusoCryptoLabs","role":"owner","date":"2026-11-19"},"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"wallets/joyid-sub-key-signing-needs-the-cota-aggregator-and-csp-allo","area":"wallets","title":"JoyID sub-key signing needs the COTA aggregator and CSP allowances","lesson":"If you strip external hosts from a CCC bundle or restrict CSP connect-src, keep CCC's COTA aggregator host (cota.nervina.dev) and allow it, because the JoyID signer calls it before signing for sub-key wallets. Also allow the RPC websocket hosts your CCC client uses, such as wss://testnet.ckb.dev.","note":"Low confidence: inferred from the commit message only. The diff showed just a rebuilt bundle.","patterns":[],"concepts":["Witnesses and signatures","Network and RPC reliability"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-11-16","last_touched":"2026-11-16","level":"working","why":"With the aggregator host stripped or blocked, JoyID sub-key wallets cannot sign transactions in the app.","sources":[{"repo":"psawyerberlin/ckb-revocable-timelock","hash":"86793bb5e1","date":"2026-11-16"}],"tests":[],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"wallets/keep-at-least-61-ckb-in-the-change-cell-when-sending-from-a","area":"wallets","title":"Keep at least 61 CKB in the change cell when sending from a secp256k1 wallet","lesson":"A plain secp256k1_blake160 cell occupies 61 CKB, so when a wallet sends X it must keep at least 61 CKB (the occupied capacity of its own lock) in the change cell, plus the fee, and refuse the send otherwise. The recipient output must also be at least the occupied capacity of the recipient's lock, never less than 61 CKB for a plain address. Enforce the change floor in the transaction builder, and use extra headroom (this runner uses threshold >= amount + 100) for automatic sweeps so fee and change always fit.","note":"","patterns":[],"concepts":["Capacity and cell size","Transaction building and fees"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-10-21","last_touched":"2026-10-21","level":"basic","why":"A transaction whose change or recipient output holds less than its occupied capacity (61 CKB for a plain secp256k1 cell) is rejected by the node, so the send fails.","sources":[{"repo":"ckb-service-runner/ckb-service-runner","hash":"d9c5c71728","date":"2026-10-21"}],"tests":[{"repo":"ckb-service-runner/ckb-service-runner","hash":"d9c5c71728","files":["acceptance/a8/p2.test.mjs","acceptance/a8/p3.test.mjs","acceptance/a8/p4.test.mjs"]}],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"partly right","against_commit":true}},{"id":"wallets/lock-code-hashes-differ-between-testnet-and-mainnet-for-omni","area":"wallets","title":"Lock code hashes differ between testnet and mainnet for Omnilock, JoyID, ACP and PW lock","lesson":"When identifying a wallet's lock by its code hash, Omnilock, JoyID, anyone-can-pay and PW lock have different code hashes on testnet and mainnet (per CCC's known scripts), while secp256k1 and multisig share one across networks. Code that compares against a single testnet hash will misclassify or fail to filter mainnet locks, so keep a hash per network (or look it up from the client's known scripts).","note":"","patterns":["avoid: if (lock.codeHash === OMNILOCK) {"],"concepts":["Cell deps and script lookup"],"applies_to":[],"status":"current","evidence":"L2","first_seen":"2026-11-08","last_touched":"2026-11-08","level":"working","why":"With only the testnet hashes, a mainnet Omnilock, JoyID, ACP or PW lock is not recognised, so it gets a generic 'lock 0x…' label and skips the lock-specific branches, such as reading the Omnilock mode flag or choosing what the wallet will show.","sources":[{"repo":"LusoCryptoLabs/ckb-ward","hash":"ba6ae6286b","date":"2026-11-08"}],"tests":[],"related":[],"confirmed":{"by":"LusoCryptoLabs","role":"owner","date":"2026-11-19"},"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"wallets/multisig-sighash-placeholder-lock-script-plus-m-zeroed-signa","area":"wallets","title":"Multisig sighash placeholder lock: script plus M zeroed signatures","lesson":"When computing the signing message for a secp256k1_blake160_multisig_all input, set the first witness's WitnessArgs.lock to the multisig script bytes followed by threshold × 65 zero bytes (a single key sighash lock uses just 65 zero bytes), and keep the inputType and outputType fields, before calling CCC's tx.getSignHashInfo(script, client). The same placeholder length must be used here as in the signed witness, otherwise the message differs from what the lock script hashes on chain.","note":"","patterns":["prefer: return `${group.config.script}${\"00\".repeat(SIGNATURE_BYTES * group.config.threshold)}`;"],"concepts":["Witnesses and signatures","Transaction building and fees"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-11-08","last_touched":"2026-11-08","level":"working","why":"If the placeholder lock has a different length or content from the final signed lock, the signers sign a message the on-chain multisig script never reproduces, so every signature fails verification.","sources":[{"repo":"ILE-Labs/ckb-msig","hash":"53b883bb9f","date":"2026-11-08"},{"repo":"ILE-Labs/ckb-msig","hash":"e07dc4d380","date":"2026-11-08"}],"tests":[{"repo":"ILE-Labs/ckb-msig","hash":"e07dc4d380","files":["test/ckb/addresses.test.ts","test/ckb/deployments.test.ts","test/ckb/embedded-check.test.ts","test/ckb/input-resolver.test.ts","test/ckb/lock-classifier.test.ts"]}],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"wallets/omnilock-owner-signing-needs-an-85-byte-zeroed-witness-lock","area":"wallets","title":"Omnilock owner signing needs an 85 byte zeroed witness lock placeholder","lesson":"For an Omnilock cell spent in owner (secp256k1) mode, the WitnessArgs.lock is an 85 byte OmniLockWitnessLock (a 20 byte molecule header 0x5500000010000000550000005500000041000000 plus the 65 byte signature), so the sighash digest must be computed with an 85 byte zeroed placeholder (e.g. CCC prepareSighashAllWitness(lock, 85, client)). A digest taken over the usual 65 byte secp256k1 placeholder does not verify, which the test confirms against a real testnet spend.","note":"","patterns":["prefer: const digest = await digestOf(onChain, lock, 85, client);"],"concepts":["Witnesses and signatures","Data encoding (molecule, hex, bigints)"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-10-23","last_touched":"2026-10-23","level":"working","why":"A sighash digest computed over a 65 byte placeholder differs from the one Omnilock verifies against the 85 byte OmniLockWitnessLock, so the signature does not verify and the spend fails.","sources":[{"repo":"officialcmg/ckb-keyway","hash":"5302b888c6","date":"2026-10-23"},{"repo":"officialcmg/ckb-keyway","hash":"b166ae14e5","date":"2026-10-23"}],"tests":[{"repo":"officialcmg/ckb-keyway","hash":"5302b888c6","files":["tests/omnilock-recovery.test.ts"]},{"repo":"officialcmg/ckb-keyway","hash":"b166ae14e5","files":["tests/user-wallet.test.ts"]}],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"wallets/one-placeholder-witness-per-input-when-all-inputs-share-one","area":"wallets","title":"One placeholder witness per input when all inputs share one lock","lesson":"In this deploy builder, several funding inputs all share the owner's lock. The signing witness (WitnessArgs) goes at index 0, and every other input gets an empty \"0x\" witness, so the witnesses list stays as long as the inputs list. That matches the secp256k1 sighash script group layout, where the first witness of the group carries the signature and covers the rest.","note":"","patterns":["prefer: tx[\"witnesses\"] = [c.witness()] + [\"0x\"] * (len(points) - 1)"],"concepts":["Witnesses and signatures","Transaction building and fees"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-11-05","last_touched":"2026-11-05","level":"working","why":"Without one witness slot per input, a multi-input transaction under one secp256k1 lock has no agreed place for the single group signature, so signing tools and the lock script's witness hashing see a layout that does not match the inputs.","sources":[{"repo":"wamimi/noir-ckb-verifier","hash":"74d5925942","date":"2026-11-05"}],"tests":[],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"wallets/placeholder-joyid-lock-args-are-22-bytes-when-quoting-capaci","area":"wallets","title":"Placeholder JoyID lock args are 22 bytes when quoting capacity","lesson":"When quoting capacity before a wallet is connected, use a placeholder lock shaped like the wallet you expect. A JoyID lock has 22 byte args, 2 bytes more than a secp256k1 lock's 20, so every cell carrying the user's lock needs 2 CKB more occupied capacity. Pass the placeholder (for example args of 22 zero bytes) to the same quote function used after connecting, so the pre-connect total is not lower than what a JoyID user will actually commit.","note":"","patterns":["prefer: const JOYID_SHAPED = { args: \"0x\" + \"00\".repeat(22) };"],"concepts":["Capacity and cell size","Transaction building and fees"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-11-10","last_touched":"2026-11-10","level":"working","why":"A placeholder sized like a 20 byte lock quotes a JoyID user a total that is too low by 2 CKB per cell they will own, so the figure they agreed to before connecting differs from what is actually built.","sources":[{"repo":"toastmanAu/daowow","hash":"538a4a02de","date":"2026-11-10"}],"tests":[{"repo":"toastmanAu/daowow","hash":"538a4a02de","files":["apps/web/test/app-shell.test.js","apps/web/test/entry-view.test.js","apps/web/test/model-entry-guard.test.js","apps/web/test/page-scripts.test.js"]}],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"wallets/release-a-stuck-signed-transaction-s-inputs-only-after-one-i","area":"wallets","title":"Release a stuck signed transaction's inputs only after one input is spent elsewhere","lesson":"A signed CKB transaction that is not committed (not pending, proposed or sent) is still valid and can be broadcast by anyone while all its inputs are live, so do not release its input reservations yet. Release them only after a committed-state live-cell check shows at least one input spent (a spend still in the tx pool does not count), and a second status check confirms the transaction still has not committed. A conflicting spend can still be reorganized away, so require the operator to acknowledge that risk.","note":"","patterns":["prefer: requireRecovery(spent>0,'all inputs are live; the signed transaction can still commit');"],"concepts":["Transaction building and fees","Indexer queries and cell collection","Network and RPC reliability"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-10-22","last_touched":"2026-10-22","level":"working","why":"If reservations are freed while the old signed transaction can still be broadcast, its inputs get reused for new transactions while the stale transaction may still land on chain.","sources":[{"repo":"toastmanAu/openswap","hash":"867f29770a","date":"2026-10-22"},{"repo":"toastmanAu/openswap","hash":"e7dd66cab6","date":"2026-10-22"}],"tests":[{"repo":"toastmanAu/openswap","hash":"867f29770a","files":["pool-sdk/test/funding-fixture.ts","pool-sdk/test/funding.test.ts","pool-sdk/test/recovery.test.ts"]},{"repo":"toastmanAu/openswap","hash":"e7dd66cab6","files":["solver/test/resolution.test.ts"]}],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"partly right","against_commit":true}},{"id":"wallets/secp256k1-sighash-lock-groups-cover-non-contiguous-later-gro","area":"wallets","title":"Secp256k1 sighash lock groups cover non contiguous later group witnesses","lesson":"With the bundled secp256k1 blake160 sighash lock, all inputs sharing the same lock form one group even when another owner's inputs sit between them. The signature goes in the witness at the group's first input index, and changing a later group witness (which leaves the tx hash unchanged) still fails verification at Inputs[first].Lock. So composed multi owner transactions must place one signature placeholder per lock group at its first input and finalize every group witness before signing.","note":"","patterns":["prefer: witnesses[first] = WitnessArgs::new_builder().lock(Some(Bytes::from(vec![0; 65])).pack())"],"concepts":["Witnesses and signatures","Transaction building and fees"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-10-09","last_touched":"2026-10-09","level":"working","why":"A composer that signs only a contiguous slice of witnesses, or edits a later group witness after signing, produces a signature that fails at Inputs[first].Lock even though the tx hash is unchanged.","sources":[{"repo":"toastmanAu/openswap","hash":"5d08496e7b","date":"2026-10-09"}],"tests":[],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"wallets/secp256k1-blake160-multisig-all-signature-matching-rules","area":"wallets","title":"secp256k1_blake160_multisig_all signature matching rules","lesson":"The system multisig lock (secp256k1_blake160_multisig_all) expects the witness to carry exactly M signatures (threshold), uses each member key at most once, and requires all of the first R keys (require_first_n) to be among them. A tool collecting partial signatures should dedupe per member key and check the first R are present before finalizing, since any M valid distinct signers that include the first R form a complete set.","note":"","patterns":["complete: thresholdMet && firstRPresent,"],"concepts":["Witnesses and signatures"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-11-08","last_touched":"2026-11-08","level":"working","why":"A collector that counts a repeated key's signature twice, or finalizes without all first R members, builds a witness the multisig lock rejects at verification.","sources":[{"repo":"ILE-Labs/ckb-msig","hash":"6a40714673","date":"2026-11-08"}],"tests":[],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"wallets/use-the-secp256k1-sighash-dep-group-not-the-bare-code-cell-a","area":"wallets","title":"Use the secp256k1 sighash dep group, not the bare code cell, as the lock dep","lesson":"When a hand-built transaction spends a secp256k1_blake160_sighash_all cell, it needs a cell dep for that lock. That dep should be the genesis dep group (dep_type dep_group), not the bare code cell in genesis tx0, because the lock also loads the secp256k1_data table from a second cell. With only the code cell, ScriptNotFound goes away but the lock then fails inside execution.","note":"","patterns":["prefer: return { out_point, dep_type: \"dep_group\" };"],"concepts":["Cell deps and script lookup","Transaction building and fees"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-09-24","last_touched":"2026-09-25","level":"working","why":"A transaction that carries only the bare sighash code cell as a dep gets past ScriptNotFound, but the lock then fails during execution because the secp256k1_data cell it loads is missing.","sources":[{"repo":"toastmanAu/daowow","hash":"0769cd4c24","date":"2026-09-24"},{"repo":"toastmanAu/daowow","hash":"6cfb40e238","date":"2026-09-25"}],"tests":[{"repo":"toastmanAu/daowow","hash":"6cfb40e238","files":["apps/web/test/aggregate-tx.test.js","apps/web/test/freeze-tx.test.js","apps/web/test/genesis-tx.test.js"]}],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}},{"id":"wallets/verifying-neuron-style-signed-messages-against-a-secp256k1-b","area":"wallets","title":"Verifying Neuron style signed messages against a secp256k1_blake160 lock","lesson":"To verify a Neuron \"Sign Message\" signature, hash with CKB Blake2b over UTF-8(\"Nervos Message:\" followed by the text), recover the compressed public key from the 65 byte r||s||v signature (v is 0 or 1, not 27/28), and accept the owner only if the lock has the exact code_hash and hash_type of the secp256k1_blake160 template and its args equal blake160 of the recovered key (comparing args alone is not enough). Neuron signs low-s; if you choose to also accept high-s, normalise s to n minus s and flip v before recovery, because some verify helpers (CCC's) reject high-s.","note":"","patterns":["prefer: return ckbHash(NERVOS_MESSAGE_PREFIX, utf8Encode(text));"],"concepts":["Witnesses and signatures","Data encoding (molecule, hex, bigints)"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-10-08","last_touched":"2026-10-08","level":"working","why":"Without the prefix and CKB Blake2b, recovery returns the wrong key, and comparing args alone lets a matching key claim a lock with a different code_hash or hash_type.","sources":[{"repo":"poshboytl/omavote","hash":"0f420a889c","date":"2026-10-08"},{"repo":"poshboytl/omavote","hash":"41374dfde5","date":"2026-10-08"}],"tests":[{"repo":"poshboytl/omavote","hash":"0f420a889c","files":["verifier-ts/test/adapter.test.ts","verifier-ts/test/builder.ts","verifier-ts/test/carrier.test.ts","verifier-ts/test/cli.test.ts","verifier-ts/test/input.test.ts"]},{"repo":"poshboytl/omavote","hash":"41374dfde5","files":["crates/omavote-core/tests/scenarios.rs"]}],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"partly right","against_commit":true}},{"id":"xudt/carry-type-script-and-data-into-the-output-when-spending-a-l","area":"xudt","title":"Carry type script and data into the output when spending a lock-only custody cell","lesson":"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.","note":"","patterns":["prefer: outputs: [{ lock: toLock, type: cell.cellOutput.type, capacity: cell.cellOutput.capacity }], outputsData: [cell.outputData],"],"concepts":["Transaction building and fees","Cell deps and script lookup","Witnesses and signatures"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-10-21","last_touched":"2026-10-21","level":"working","why":"Without it, the spend rebuilds the custody cell as plain capacity with empty data, so a UDT held in it is dropped. A typed cell's script would also lack its cell deps, which cannot be added once the transaction is signed.","sources":[{"repo":"salmansarwarr/Tranfr","hash":"49c840ddb0","date":"2026-10-21"}],"tests":[{"repo":"salmansarwarr/Tranfr","hash":"49c840ddb0","files":["sdk/tests/client.test.ts"]}],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"partly right","against_commit":true}},{"id":"xudt/full-balance-udt-burn-is-valid-for-sudt-and-plain-xudt","area":"xudt","title":"Full-balance UDT burn is valid for SUDT and plain xUDT","lesson":"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.","note":"","patterns":["avoid: if (destroyAmount === totalBalance) { throw new Error('Destroying the entire UDT balance may be rejected by the UDT script..."],"concepts":["Transaction building and fees","Capacity and cell size"],"applies_to":[],"status":"current","evidence":"L0","first_seen":"2026-10-08","last_touched":"2026-10-08","level":"working","why":"A guard that rejects destroyAmount === totalBalance blocks a burn that sUDT and plain xUDT accept, so users cannot clear their full token balance and must leave at least one token behind.","sources":[{"repo":"ckb-devrel/offckb","hash":"3c4aa19b95","date":"2026-10-08"}],"tests":[{"repo":"ckb-devrel/offckb","hash":"3c4aa19b95","files":["tests/sdk/ckb.udt.test.ts"]}],"related":[],"confirmed":null,"reproduced":null,"checked":{"date":"2026-11-19","verdict":"right","against_commit":true}}]}