CKB Pulse
Lessons

What CKB learned

Start here · Glossary · Test yourself · Feed

CCC (TypeScript SDK)

33 lessons found. All lessons

Page 1 of 3

CCC client cache can keep dropped transactions; check status without cacheWorkingFrom one fix

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.

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.

#Network and RPC reliability #Transaction building and fees · Sources (1) · 2026-11-17

Registering NervosDao on devnetWorkingSeen again

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'}}]}.

#Cell deps and script lookup #Testing and devnet · Sources (2) · 2026-11-15

Use findCellsOnChain for shared live stateWorkingFrom one fix

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.

Medium confidence.

#Indexer queries and cell collection · Sources (1) · 2026-11-15

Wallet discovery with SignersControllerWorkingFrom one fix

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.

Medium confidence.

#Witnesses and signatures #Login and authorization · Sources (1) · 2026-11-12

Sign a prepared transaction without broadcasting via CCC signOnlyTransactionWorkingFrom one fix

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).

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

Classifying sendTransaction failures before dropping a pending CKB transactionWorkingFrom one fix

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.

#Network and RPC reliability #Transaction building and fees · Sources (1) · 2026-11-08

Parsing snake_case JSON-RPC transactions in CCCWorkingReproduced

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.

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

CCC EVM and Bitcoin signers pass the exact signed text through signMessageRawWorkingChecked by the owner

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.

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

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

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

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

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

CCC EVM signer exposes several lock addresses via getAddressObjsWorkingChecked by the owner

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.

#Indexer queries and cell collection #Login and authorization · Sources (1) · 2026-11-06

Locate the signing witness slot instead of hardcoding its indexWorkingFrom one fix

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.

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

completeFeeBy adds change instead of shrinking outputs, breaking output bound proofsWorkingFrom one fix

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.

#Transaction building and fees #Witnesses and signatures #Capacity and cell size · Sources (1) · 2026-11-04

Page 1 of 3

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