CKB KeyWayDocs

Core concepts

The minimum CKB and Fiber model needed to use KeyWay correctly.

Account, node, and channel

These are separate pieces of state:

ConceptWhat it isWhere it lives
CKB accountThe on-chain identity and cells controlled through the Lit PKP, and with account recovery on, also by the user's backups.Recoverable from the authenticated email identity.
Fiber nodeThe networking process that creates invoices, finds routes, and updates channels.A persistent native process on KeyWay's servers (hosted), or WebAssembly in the page (browser).
Channel databaseThe latest off-chain state for the user's Fiber channels.The hosted node's durable volume, or IndexedDB for a browser node.

Logging in recovers the CKB identity. useFiber().start() then connects to the user's hosted node, the default. An optional browser node has its own node identity and channel database, which stays in local IndexedDB during use and can move to the next device through KeyWay's encrypted explicit-logout handoff. The two kinds of node don't share channel state.

Relays are not channels

When KeyWay starts, it connects to public testnet relays. Relay connections provide network reachability and gossip; they do not lock funds and do not give the user payment capacity.

useFiber().openChannel() separately negotiates and funds a channel with a channel peer. That channel places capacity into the Fiber graph.

On-chain and Fiber balances

  • On-chain balance is the sum of live CKB cells controlled by the account's lock script.
  • Fiber balance is the sum of canSend across ready channels, per asset: CKB channels and token channels are counted separately.
  • Opening a channel moves funds from ordinary cells into a channel funding cell. A token channel also locks some CKB as a reserve.
  • Fiber payments update channel states off-chain rather than broadcasting one CKB transaction per payment.

Routed payments

A payment can cross several public channels:

sender -> channel peer -> other public nodes -> receiver's channel peer -> receiver

Every hop must have enough outbound liquidity. A route may exist for 1 CKB and fail for 999 CKB because route existence and route capacity are different questions. Use estimatePayment() to check a specific amount.

Browser node

With an optional browser node, one user has both an account identity and a local node identity. Closing the tab stops that node. Explicit logout encrypts and uploads its channel database so the next device can restore it before Fiber starts.

Do not treat IndexedDB as disposable cache. It contains the off-chain channel state needed to resume the node safely.

Hosted node

The hosted node is the default (fiberNode="hosted"). It keeps a dedicated native Fiber process and channel database online outside the browser lifecycle. The React API is the same, but the node runs on KeyWay's servers, which hold that node's key and channel state, so KeyWay takes on a larger custody and availability role. Existing browser channels are not moved to a hosted node.

For how each kind of node handles keys, approvals and force-closed channels, see Fiber node.

On this page