@ickb/sdk 9000.0.1 → 9001.0.0

package/src/send/sign_and_send_transaction.ts

@@ -1,6 +1,7 @@
 import { ccc } from "@ckb-ccc/core";
-import { cccA } from "@ckb-ccc/core/advanced";
-import { unique } from "../utils/utils.ts";
+import { assertFresh, type BroadcastDeadline } from "../dao.ts";
+import { jsonRpcRequestor, unique } from "../utils/utils.ts";
+import { verifiedClient } from "../utils/verified_client.ts";
 
 /** Error from a broadcast whose outcome is unknown; the local transaction hash is retained. */
 export class TransactionBroadcastError extends Error {
@@ -32,49 +33,59 @@ export class TransactionExpiredError extends Error {
 }
 
 /**
- * Signs locally, records chain identity before RPC, then broadcasts without
- * CCC's cache wrapper.
+ * Verifies the inputs against the chain, signs locally, records chain identity before
+ * RPC, then broadcasts without CCC's cache wrapper.
  *
- * @remarks The connector must not alter the economic body it was handed: the
- * ordered inputs, outputs and outputs data are compared against a digest taken
- * before signing, so in-place mutation cannot evade the check. Witnesses and
- * cell/header dependency preparation stay signer-owned. The fee ceiling values
- * inputs from the pre-sign transaction rather than connector-supplied metadata,
- * while measuring the signed bytes. When `broadcastBefore` is given, one fresh tip
- * is read after the signature and the fee check, and the send is refused with
- * `TransactionExpiredError` once the tip's epoch has reached it: a withdrawal
- * request that commits after its claim locks the deposit for another cycle, and a
- * wallet may hold the signature for a while.
- * `recordTxHash` is called after these checks and before the send RPC starts. A
- * node that already holds this exact transaction is an acceptance; any other send
- * failure remains ambiguous and throws `TransactionBroadcastError`. The client
- * cache is never marked: later attempts rebuild from exact committed reads.
+ * @remarks Nothing is signed unless every cell attached to an input equals the output
+ * its creating transaction made, a bare `OutPoint` being valued from that output, and the
+ * signer kept the ordered inputs, outputs and outputs data.
+ * Nothing is sent when the chain would take more fee than `plannedFee`, the fee completion
+ * priced, `tx.estimateFee(feeRate)` at its rate. That fee is measured from verified values,
+ * a phase-2 DAO input proven in its request block with `get_transaction_proof`, so the
+ * client must be JSON-RPC. When `broadcastBefore` is given, the send is refused with
+ * `TransactionExpiredError` once a fresh tip reaches it.
+ * `recordTxHash` runs before the send RPC, for a caller that must record the hash before a
+ * send that may never answer; every later failure carries it as `TransactionBroadcastError`. A node already holding this exact transaction
+ * is an acceptance; any other send failure throws `TransactionBroadcastError`. Why each
+ * check exists: SDK README, Signing and broadcast.
  */
 export async function signAndSendTransaction(
   signer: ccc.Signer,
   tx: ccc.TransactionLike,
+  plannedFee: ccc.Num,
   recordTxHash?: (txHash: ccc.Hex) => void,
-  broadcastBefore?: ccc.Epoch,
+  broadcastBefore?: BroadcastDeadline,
 ): Promise<ccc.Hex> {
   // Transaction.from reuses Transaction instances, which a signer may mutate in place.
   const requested = ccc.Transaction.from(tx).clone();
   const requestedBody = economicBody(requested);
+  // The checks read through a verified client, whatever client the signer holds.
+  const client = verifiedClient(signer.client);
+  const inputs = await verifiedInputs(client, requested.inputs);
   const signed = await signer.signTransaction(tx);
   if (economicBody(signed) !== requestedBody) {
     throw new Error("Signer altered the transaction inputs, outputs or outputs data");
   }
   const txHash = signed.hash();
-  // CCC trusts input cell metadata already attached to the connector-controlled result.
-  const feeTransaction = signed.clone();
-  feeTransaction.inputs = requested.inputs;
-  const feeRate = await feeTransaction.getFeeRate(signer.client);
-  if (feeRate > cccA.DEFAULT_MAX_FEE_RATE) {
-    throw new ccc.ErrorClientMaxFeeRateExceeded(cccA.DEFAULT_MAX_FEE_RATE, feeRate);
+  const fee = await verifiedFee(client, signed, inputs);
+  // A plain JavaScript caller of the earlier signature passes undefined or its recordTxHash
+  // here: numFrom throws on undefined, and on a function either throws or reads 0n. A bare
+  // comparison of a bigint with either is false and would skip the check.
+  const planned = ccc.numFrom(plannedFee);
+  if (fee > planned) {
+    throw new Error(
+      `Transaction ${txHash} pays ${String(fee)} shannons of fee, more than the ${String(planned)} planned`,
+    );
   }
   if (broadcastBefore !== undefined) {
-    const { epoch } = await signer.client.getTipHeader();
-    if (broadcastBefore.compare(epoch) <= 0) {
-      throw new TransactionExpiredError({ broadcastBefore, tip: epoch });
+    const tip = await client.getTipHeader();
+    assertFresh(tip, broadcastBefore.tipMaxAgeMs);
+    const { epoch } = tip;
+    if (broadcastBefore.epoch.compare(epoch) <= 0) {
+      throw new TransactionExpiredError({
+        broadcastBefore: broadcastBefore.epoch,
+        tip: epoch,
+      });
     }
   }
   recordTxHash?.(txHash);
@@ -96,6 +107,131 @@ export async function signAndSendTransaction(
   return txHash;
 }
 
+// The default lock signs each input as its OutPoint only, never the cell behind it, so
+// the capacity, lock, type and data attached to an input are a node's claim: a node
+// understating a plain cell's capacity or a UDT amount would turn the difference into
+// fee or a burn on a transaction that passes every other check. The verified client reads
+// the cell from its creating transaction, whose hash certifies its body.
+async function verifiedInputs(
+  client: ccc.Client,
+  inputs: readonly ccc.CellInput[],
+): Promise<ccc.Cell[]> {
+  return Promise.all(
+    inputs.map(async (input) => {
+      const outPoint = input.previousOutput.toHex();
+      const cell = await client.getCell(input.previousOutput);
+      if (cell === undefined) {
+        throw new Error(`Input ${outPoint} is not an output of a known transaction`);
+      }
+      if (
+        (input.cellOutput !== undefined && !cell.cellOutput.eq(input.cellOutput)) ||
+        (input.outputData !== undefined && input.outputData !== cell.outputData)
+      ) {
+        throw new Error(
+          `Input ${outPoint} differs from the cell its transaction created`,
+        );
+      }
+      return cell;
+    }),
+  );
+}
+
+// The fee the chain will take: the verified inputs' capacity, plus the interest a phase-2
+// DAO input collects, less the outputs. Completion priced that interest through the
+// signer's client at whatever header the node named, so a lower rate there shortened the
+// change; the miner would keep the difference under any fee-rate ceiling. A node names
+// which block created a cell; the chain values it at headers the transaction names in its
+// deps, the deposit header at the number the cell's data records and the request header
+// at the block that committed the request, which the node must prove
+// (assertCommittedIn), once per request transaction. The deposit header is then the one
+// the cell's data numbers and the request header the real request block, so dao.c's own
+// rules settle the rest on chain.
+async function verifiedFee(
+  client: ccc.Client,
+  signed: ccc.Transaction,
+  inputs: readonly ccc.Cell[],
+): Promise<ccc.Num> {
+  const deps = new Set(signed.headerDeps);
+  const proven = new Set<string>();
+  let capacity = ccc.Zero;
+  for (const cell of inputs) {
+    capacity += cell.cellOutput.capacity;
+    const { depositHeader, withdrawHeader } = await cell.getNervosDaoInfo(client);
+    if (withdrawHeader === undefined) {
+      continue;
+    }
+    if (!deps.has(depositHeader.hash) || !deps.has(withdrawHeader.hash)) {
+      throw new Error(
+        `Input ${cell.outPoint.toHex()} is valued at a header the transaction does not name`,
+      );
+    }
+    const { txHash } = cell.outPoint;
+    if (!proven.has(`${txHash}${withdrawHeader.hash}`)) {
+      await assertCommittedIn(client, txHash, withdrawHeader);
+      proven.add(`${txHash}${withdrawHeader.hash}`);
+    }
+    capacity += ccc.calcDaoProfit(cell.capacityFree, depositHeader, withdrawHeader);
+  }
+  return capacity - signed.getOutputsCapacity();
+}
+
+/**
+ * Refuses unless the node proves `txHash` is among the transactions of `header`'s block.
+ * An outpoint names its transaction, not the block that committed it, so a phase-2 input
+ * valued at the request header the node names could otherwise be valued at another
+ * request block of the same transaction. The proof is a Merkle path from the transaction
+ * hash to the header's transactions root, which the header's own hash binds.
+ */
+async function assertCommittedIn(
+  client: ccc.Client,
+  txHash: ccc.Hex,
+  header: ccc.ClientBlockHeader,
+): Promise<void> {
+  const requestor = jsonRpcRequestor(client);
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion, no-restricted-syntax -- the node's answer, checked field by field in isCommittedIn.
+  const proof = (await requestor.request("get_transaction_proof", [
+    [txHash],
+    header.hash,
+  ])) as TransactionProof;
+  if (!isCommittedIn(txHash, header, proof)) {
+    throw new Error(`Transaction ${txHash} is not proven in block ${header.hash}`);
+  }
+}
+
+/** The node's `get_transaction_proof` answer for one transaction, the fields checked. */
+export interface TransactionProof {
+  witnesses_root: ccc.Hex;
+  proof: { indices: readonly ccc.Hex[]; lemmas: readonly ccc.Hex[] };
+}
+
+/**
+ * Whether `proof` is a path from `txHash` to `header`'s transactions root. CKB builds that
+ * root over two subtrees, `blake2b(raw transactions root || witnesses root)`, each a
+ * complete binary Merkle tree whose node at position `i` has its parent at `(i - 1) / 2`
+ * and is a left child when `i` is odd; the index is the leaf's position and the lemmas are
+ * its siblings bottom up.
+ */
+export function isCommittedIn(
+  txHash: ccc.Hex,
+  header: ccc.ClientBlockHeader,
+  { witnesses_root: witnessesRoot, proof }: TransactionProof,
+): boolean {
+  const [index, ...extra] = proof.indices;
+  if (index === undefined || extra.length > 0) {
+    return false;
+  }
+  let node = txHash;
+  let position = Number(index);
+  for (const lemma of proof.lemmas) {
+    if (position === 0) {
+      return false;
+    }
+    node = position % 2 === 1 ? ccc.hashCkb(node, lemma) : ccc.hashCkb(lemma, node);
+    position = (position - 1) >> 1;
+  }
+  return position === 0 && ccc.hashCkb(node, witnessesRoot) === header.transactionsRoot;
+}
+
 // Hashing a body-only transaction reuses CCC serialization to freeze the ordered
 // inputs, outputs and outputs data, while ignoring signer-owned witnesses and
 // the cell/header deps a connector may still have to prepare.

package/src/send/wait_transaction.ts

@@ -1,5 +1,5 @@
 import { ccc } from "@ckb-ccc/core";
-import { jsonRpcRequestor, rawTransactionStatus } from "../utils/utils.ts";
+import { jsonRpcRequestor } from "../utils/utils.ts";
 
 const MAX_TIMEOUT_MS = 2_147_483_647;
 const DEFAULT_TIMEOUT_MS = 60_000;
@@ -40,15 +40,16 @@ export interface WaitTransactionOptions {
 }
 
 /**
- * Observes one already-broadcast transaction for a single bounded window and returns
- * it once the node reports it committed.
+ * Observes one already-broadcast transaction for a single bounded window and resolves
+ * once the node reports it committed.
  *
  * @remarks Stack waits at depth zero. Actors rebuild next turn; the app can reopen a
  * window on the same hash without signing again. Callers needing deeper confirmation
  * must observe it separately.
- * Clients with a JSON-RPC requestor, the connector's composed client included, poll
- * `get_transaction` verbosity 1 directly because CCC's typed response discards a null
- * transaction body, including its rejection status. Body reads separately bypass the cache.
+ * The status is polled with raw `get_transaction` verbosity 1, since CCC's typed response
+ * discards a null transaction body and its rejection status; the client must be JSON-RPC,
+ * the connector's composed client included. The body is never read: no caller uses it,
+ * and the same node's word on it would verify nothing.
  * Timeout and abort also apply while awaiting client
  * operations, but the in-flight client operation receives no abort signal and may
  * finish after this function rejects. Nothing here mutates the client cache: later attempts rebuild
@@ -58,7 +59,7 @@ export async function waitTransaction(
   client: ccc.Client,
   txHashLike: ccc.HexLike,
   options: WaitTransactionOptions = {},
-): Promise<ccc.ClientTransactionResponse> {
+): Promise<void> {
   const {
     timeout = DEFAULT_TIMEOUT_MS,
     interval = DEFAULT_INTERVAL_MS,
@@ -71,15 +72,13 @@ export async function waitTransaction(
   signal?.throwIfAborted();
 
   const budget = openWaitWindow(timeout, signal);
-  const poll = { client, txHash, budget };
   try {
     for (;;) {
-      const committed = await readCommittedTransaction(poll);
-      if (committed !== undefined) {
+      if (await isCommitted(client, txHash, budget)) {
         // An abort synchronized into the gap between the last read and this
         // return must not resolve the wait successfully.
         budget.throwIfStopped();
-        return committed;
+        return;
       }
       if (Date.now() + interval >= budget.deadline) {
         throw budget.timeoutError;
@@ -99,18 +98,6 @@ interface WaitWindow {
   close: () => void;
 }
 
-interface WaitPoll {
-  client: ccc.Client;
-  txHash: ccc.Hex;
-  budget: WaitWindow;
-}
-
-interface TransactionStatus {
-  status: string | undefined;
-  reason: string | undefined;
-  response?: ccc.ClientTransactionResponse;
-}
-
 function validateWaitOptions(timeout: number, interval: number): void {
   assertCount(interval, "interval");
   assertCount(timeout, "timeout");
@@ -198,74 +185,43 @@ async function pollingSleep(interval: number, budget: WaitWindow): Promise<void>
   }
 }
 
-async function readCommittedTransaction(
-  poll: WaitPoll,
-): Promise<ccc.ClientTransactionResponse | undefined> {
-  const status = await readTransactionStatus(poll);
-  assertNotRejected(poll.txHash, status);
-  if (status.status !== "committed") {
-    return undefined;
-  }
-
-  const response = status.response ?? (await readTransactionBody(poll));
-  if (response === undefined) {
-    return undefined;
-  }
-  assertNotRejected(poll.txHash, {
-    status: response.status,
-    reason: response.reason,
-  });
-  // Only a body that itself reports commitment counts: an uncached read may lag
-  // or disagree with the status poll, and any other status is not commitment.
-  return response.status === "committed" && response.blockNumber !== undefined
-    ? response
-    : undefined;
-}
-
-async function readTransactionStatus(poll: WaitPoll): Promise<TransactionStatus> {
-  const { client, txHash, budget } = poll;
+async function isCommitted(
+  client: ccc.Client,
+  txHash: ccc.Hex,
+  budget: WaitWindow,
+): Promise<boolean> {
   const requestor = jsonRpcRequestor(client);
-  if (requestor !== undefined) {
-    // Raw verbosity-1 polling keeps a status-only rejection that CCC's typed
-    // transaction response discards (its body is null, so CCC returns nothing).
-    return rawTransactionStatus(
-      await within(
-        async () => requestor.request("get_transaction", [txHash, "0x1"]),
-        budget,
-      ),
-    );
-  }
-
-  const response = await readTransactionBody(poll);
-  return response === undefined
-    ? { status: undefined, reason: undefined }
-    : { status: response.status, reason: response.reason, response };
-}
-
-async function readTransactionBody(
-  poll: WaitPoll,
-): Promise<ccc.ClientTransactionResponse | undefined> {
-  const response = await within(
-    async () => poll.client.getTransactionNoCache(poll.txHash),
-    poll.budget,
+  // Raw verbosity-1 polling keeps a status-only rejection that CCC's typed transaction
+  // response discards (its body is null, so CCC returns nothing).
+  const { status, reason } = rawTransactionStatus(
+    await within(
+      async () => requestor.request("get_transaction", [txHash, "0x1"]),
+      budget,
+    ),
   );
-  if (response === undefined) {
-    return undefined;
-  }
-  try {
-    // A generic client may return an unvalidated shape, and a body that cannot
-    // be normalized is not evidence of commitment: keep the window polling.
-    return ccc.ClientTransactionResponse.from(response);
-  } catch {
-    return undefined;
+  if (status === "rejected") {
+    throw new TransactionWaitError(txHash, { status, reason });
   }
+  return status === "committed";
 }
 
-function assertNotRejected(txHash: ccc.Hex, status: TransactionStatus): void {
-  if (status.status === "rejected") {
-    throw new TransactionWaitError(txHash, {
-      status: status.status,
-      reason: status.reason,
-    });
-  }
+/** A node's raw `get_transaction` status record (verbosity 1), the fields read here. */
+function rawTransactionStatus(response: unknown): {
+  status: string | undefined;
+  reason: string | undefined;
+} {
+  const record =
+    typeof response === "object" &&
+    response !== null &&
+    "tx_status" in response &&
+    typeof response.tx_status === "object" &&
+    response.tx_status !== null
+      ? response.tx_status
+      : {};
+  return {
+    status:
+      "status" in record && typeof record.status === "string" ? record.status : undefined,
+    reason:
+      "reason" in record && typeof record.reason === "string" ? record.reason : undefined,
+  };
 }

package/src/udt.ts

@@ -1,7 +1,6 @@
 import { ccc, mol } from "@ckb-ccc/core";
 import { isDaoDeposit } from "./dao.ts";
 import { CheckedUint128LE, CheckedUint32LE, CheckedUint64LE } from "./utils/codec.ts";
-import { transactionHeaders } from "./utils/transaction_header.ts";
 import type { ExchangeRatio } from "./utils/utils.ts";
 
 const ickbXudtTypeOccupiedSize = 69;
@@ -57,11 +56,8 @@ export class IckbUdt {
   /** The iCKB xUDT type script. */
   public readonly script: ccc.Script;
 
-  /** Out point of the xUDT code cell used by this iCKB token. */
-  public readonly udtCode: ccc.OutPoint;
-
-  /** Out point of the iCKB Logic code cell required by this token. */
-  public readonly logicCode: ccc.OutPoint;
+  /** The iCKB dep group, which also carries the xUDT and iCKB Logic code cells. */
+  public readonly cellDeps: ccc.CellDep[];
 
   /** Logic script whose hash is embedded in this iCKB xUDT type script. */
   public readonly logicScript: ccc.Script;
@@ -71,21 +67,18 @@ export class IckbUdt {
 
   /** Creates an instance of IckbUdt from its code and script references. */
   constructor({
-    code,
     script,
-    logicCode,
+    cellDeps,
     logicScript,
     daoScript,
   }: {
-    code: ccc.OutPointLike;
     script: ccc.ScriptLike;
-    logicCode: ccc.OutPointLike;
+    cellDeps: ccc.CellDepLike[];
     logicScript: ccc.ScriptLike;
     daoScript: ccc.ScriptLike;
   }) {
     this.script = ccc.Script.from(script);
-    this.udtCode = ccc.OutPoint.from(code);
-    this.logicCode = ccc.OutPoint.from(logicCode);
+    this.cellDeps = cellDeps.map((cellDep) => ccc.CellDep.from(cellDep));
     this.logicScript = ccc.Script.from(logicScript);
     this.daoScript = ccc.Script.from(daoScript);
   }
@@ -132,101 +125,48 @@ export class IckbUdt {
   }
 
   /**
-   * Adds iCKB-specific cell dependencies to a transaction.
-   *
-   * Adds individual code deps (not dep group) for:
-   * - xUDT code cell (this.udtCode)
-   * - iCKB Logic code cell (this.logicCode)
-   *
-   * @param txLike - The transaction to add cell deps to.
-   * @returns The transaction with cell deps added.
+   * iCKB carried by the transaction's inputs: xUDT balances plus receipt value, minus the
+   * first-phase deposits it re-mints. Receipts and deposits take the value the state read
+   * gave them at their deposit headers; a protocol input missing from `protocolCells` is
+   * a builder bug and throws, since iCKB Logic would refuse whatever it was valued at.
    */
-  public addCellDeps(txLike: ccc.TransactionLike): ccc.Transaction {
-    const tx = ccc.Transaction.from(txLike);
-    addCodeDep(tx, this.udtCode);
-    addCodeDep(tx, this.logicCode);
-    return tx;
-  }
-
-  /**
-   * iCKB carried by the transaction's inputs: xUDT balances plus receipt value,
-   * minus the first-phase deposits it re-mints. Final withdrawal inputs carry none.
-   * The protocol cells are valued at their deposit headers, each read once.
-   */
-  public async inputBalance(tx: ccc.Transaction, client: ccc.Client): Promise<ccc.Num> {
-    const cells = await Promise.all(
-      tx.inputs.map(async (input) => {
-        try {
-          return await input.getCell(client);
-        } catch (error) {
-          throw new Error(`Failed to load input cell ${input.previousOutput.toHex()}`, {
-            cause: error,
-          });
-        }
-      }),
-    );
-    const valued = cells.map((cell) => this.protocolValue(cell));
-    const headers = await transactionHeaders(
-      client,
-      valued.flatMap((value) => (value === undefined ? [] : [value.txHash])),
+  public async inputBalance(
+    tx: ccc.Transaction,
+    client: ccc.Client,
+    protocolCells: readonly ProtocolCell[],
+  ): Promise<ccc.Num> {
+    const values = new Map(
+      protocolCells.map(({ cell, udtValue }) => [cell.outPoint.toHex(), udtValue]),
     );
     let balance = ccc.Zero;
-    for (const [index, cell] of cells.entries()) {
-      const value = valued[index];
+    for (const input of tx.inputs) {
+      const cell = await input.getCell(client);
       if (this.isUdt(cell)) {
-        balance += decodeUdtBalance(cell.outputData);
-      } else if (value !== undefined) {
-        // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- every protocol cell's hash was read above.
-        const header = headers.get(value.txHash)!;
-        balance += value.sign * ickbValue(value.amount, header) * value.quantity;
+        balance += ccc.udtBalanceFrom(cell.outputData);
+        continue;
+      }
+      const sign = this.protocolSign(cell);
+      if (sign === 0n) {
+        continue;
       }
+      const value = values.get(cell.outPoint.toHex());
+      if (value === undefined) {
+        throw new Error(
+          `iCKB input ${cell.outPoint.toHex()} has no value from the state read`,
+        );
+      }
+      balance += sign * value;
     }
     return balance;
   }
 
-  /** What a protocol input (receipt or first-phase deposit) is worth once its header is known. */
-  private protocolValue(
-    cell: ccc.CellAny,
-  ):
-    | { txHash: ccc.Hex; amount: ccc.FixedPoint; quantity: bigint; sign: bigint }
-    | undefined {
-    if (this.isUdt(cell) || cell.outPoint === undefined) {
-      return undefined;
-    }
+  /** 1 for a receipt, -1 for a first-phase iCKB deposit, 0 for any other cell. */
+  private protocolSign(cell: ccc.Cell): bigint {
     const { type, lock } = cell.cellOutput;
     if (type !== undefined && this.logicScript.eq(type)) {
-      let receipt: ReturnType<typeof decodeReceiptData>;
-      try {
-        receipt = decodeReceiptData(cell.outputData);
-      } catch (error) {
-        throw new Error(
-          `Invalid iCKB receipt payload at ${cell.outPoint.toHex()}: ${cell.outputData}`,
-          { cause: error },
-        );
-      }
-      return {
-        txHash: cell.outPoint.txHash,
-        amount: receipt.depositAmount,
-        quantity: receipt.depositQuantity,
-        sign: 1n,
-      };
-    }
-    if (this.logicScript.eq(lock) && isDaoDeposit(cell, this.daoScript)) {
-      return {
-        txHash: cell.outPoint.txHash,
-        amount: cell.capacityFree,
-        quantity: 1n,
-        sign: -1n,
-      };
+      return 1n;
     }
-    return undefined;
-  }
-
-  /** iCKB the transaction's outputs require. */
-  public outputBalance(tx: ccc.Transaction): ccc.Num {
-    return Array.from(tx.outputCells).reduce((required, cell) => {
-      return this.isUdt(cell) ? required + decodeUdtBalance(cell.outputData) : required;
-    }, ccc.Zero);
+    return this.logicScript.eq(lock) && isDaoDeposit(cell, this.daoScript) ? -1n : 0n;
   }
 
   /** Adds the iCKB change output when the surplus is positive; zero needs no output. */
@@ -238,17 +178,6 @@ export class IckbUdt {
   }
 }
 
-function decodeUdtBalance(data: ccc.BytesLike): ccc.Num {
-  return CheckedUint128LE.decode(ccc.bytesFrom(data).slice(0, udtDataSize));
-}
-
-function addCodeDep(tx: ccc.Transaction, outPoint: ccc.OutPoint): void {
-  if (tx.cellDeps.some((dep) => dep.depType === "code" && dep.outPoint.eq(outPoint))) {
-    return;
-  }
-  tx.addCellDeps({ outPoint, depType: "code" });
-}
-
 /**
  * Calculates iCKB value for unoccupied CKB capacity at a deposit header.
  *
@@ -260,7 +189,7 @@ export function ickbValue(
   ckbUnoccupiedCapacity: ccc.FixedPoint,
   header: ccc.ClientBlockHeader,
 ): ccc.FixedPoint {
-  let ickbAmount = convert(true, ckbUnoccupiedCapacity, ickbAccountingRatio(header));
+  let ickbAmount = udtFromCkb(ckbUnoccupiedCapacity, ickbAccountingRatio(header));
   if (ICKB_DEPOSIT_CAP < ickbAmount) {
     // Apply a 10% discount for the amount exceeding the soft iCKB cap per deposit.
     ickbAmount -= (ickbAmount - ICKB_DEPOSIT_CAP) / 10n;
@@ -269,25 +198,22 @@ export function ickbValue(
   return ickbAmount;
 }
 
-/**
- * Converts between CKB and iCKB based on an explicit ratio.
- *
- * @param isCkb2Udt - A boolean indicating the direction of conversion (CKB to iCKB or vice versa).
- * @param amount - The amount to convert.
- * @param ratio - The CKB and iCKB scales to use.
- * @returns The converted amount in the target unit as a `ccc.FixedPoint`.
- */
-export function convert(
-  isCkb2Udt: boolean,
-  amount: ccc.FixedPoint,
-  ratio: ExchangeRatio,
-): ccc.FixedPoint {
-  if (ratio.ckbScale <= 0n || ratio.udtScale <= 0n) {
+/** The iCKB worth `amount` CKB at `ratio`, rounded down. */
+export function udtFromCkb(amount: ccc.FixedPoint, ratio: ExchangeRatio): ccc.FixedPoint {
+  assertPositive(ratio);
+  return (amount * ratio.ckbScale) / ratio.udtScale;
+}
+
+/** The CKB worth `amount` iCKB at `ratio`, rounded down. */
+export function ckbFromUdt(amount: ccc.FixedPoint, ratio: ExchangeRatio): ccc.FixedPoint {
+  assertPositive(ratio);
+  return (amount * ratio.udtScale) / ratio.ckbScale;
+}
+
+function assertPositive({ ckbScale, udtScale }: ExchangeRatio): void {
+  if (ckbScale <= 0n || udtScale <= 0n) {
     throw new Error("Exchange ratio scales must be positive");
   }
-  return isCkb2Udt
-    ? (amount * ratio.ckbScale) / ratio.udtScale
-    : (amount * ratio.udtScale) / ratio.ckbScale;
 }
 
 /**
@@ -315,3 +241,9 @@ export function ickbExchangeRatio(header: ccc.ClientBlockHeader): ExchangeRatio
     udtScale: header.dao.ar + depositCapacityDelta,
   };
 }
+
+/** A receipt or iCKB deposit with the iCKB value the state read gave it. */
+export interface ProtocolCell {
+  cell: ccc.Cell;
+  udtValue: ccc.Num;
+}