@ickb/sdk 1000.0.82 → 9001.0.0

package/src/send/sign_and_send_transaction.ts

@@ -0,0 +1,256 @@
+import { ccc } from "@ckb-ccc/core";
+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 {
+  /** Chain transaction hash computed from the signed transaction before broadcast. */
+  public readonly txHash: ccc.Hex;
+
+  /** Creates a hash-preserving broadcast error. */
+  constructor(txHash: ccc.Hex, options: ErrorOptions) {
+    super(`Transaction ${txHash} broadcast outcome is unresolved`, options);
+    this.name = "TransactionBroadcastError";
+    this.txHash = txHash;
+  }
+}
+
+/** Error from a send refused because the chain reached the transaction's broadcast deadline. */
+export class TransactionExpiredError extends Error {
+  /** The deadline and the tip epoch that reached it. */
+  public readonly epochs: { broadcastBefore: ccc.Epoch; tip: ccc.Epoch };
+
+  /** Creates the error for a deadline the tip has reached; nothing was sent. */
+  constructor(
+    epochs: { broadcastBefore: ccc.Epoch; tip: ccc.Epoch },
+    options?: ErrorOptions,
+  ) {
+    super("Transaction expired: the chain reached its broadcast deadline", options);
+    this.name = "TransactionExpiredError";
+    this.epochs = epochs;
+  }
+}
+
+/**
+ * Verifies the inputs against the chain, signs locally, records chain identity before
+ * RPC, then broadcasts without CCC's cache wrapper.
+ *
+ * @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?: 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();
+  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 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);
+
+  // The signature binds the bytes, so the node can only have accepted this exact
+  // transaction; its returned hash adds nothing and the local one stays the identity.
+  try {
+    await signer.client.sendTransactionNoCache(signed);
+  } catch (cause) {
+    // A duplicate submission of this exact transaction is already accepted.
+    if (
+      cause instanceof ccc.ErrorClientDuplicatedTransaction &&
+      cause.txHash === txHash
+    ) {
+      return txHash;
+    }
+    throw new TransactionBroadcastError(txHash, { cause });
+  }
+  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.
+function economicBody(tx: ccc.TransactionLike): ccc.Hex {
+  const { inputs, outputs, outputsData } = ccc.Transaction.from(tx);
+  return ccc.Transaction.from({ inputs, outputs, outputsData }).hash();
+}
+
+/**
+ * Returns the primary lock plus all signer address locks, deduplicated by script hash.
+ */
+export async function signerAccountLocks(
+  signer: ccc.Signer,
+  primaryLock: ccc.Script,
+): Promise<ccc.Script[]> {
+  return [
+    ...unique([
+      primaryLock,
+      ...(await signer.getAddressObjs()).map(({ script }) => script),
+    ]),
+  ];
+}

package/src/send/wait_transaction.ts

@@ -0,0 +1,227 @@
+import { ccc } from "@ckb-ccc/core";
+import { jsonRpcRequestor } from "../utils/utils.ts";
+
+const MAX_TIMEOUT_MS = 2_147_483_647;
+const DEFAULT_TIMEOUT_MS = 60_000;
+const DEFAULT_INTERVAL_MS = 2_000;
+
+/** Error reported when CKB gives a terminal non-committed transaction status. */
+export class TransactionWaitError extends Error {
+  /** Hash of the transaction that reached a terminal status. */
+  public readonly txHash: ccc.Hex;
+  /** Terminal status reported by the node. */
+  public readonly status: string;
+  /** Optional rejection reason reported by the node. */
+  public readonly reason: string | undefined;
+
+  /** Creates an error from a transaction hash and terminal node status. */
+  constructor(
+    txHash: ccc.Hex,
+    options: ErrorOptions & { status: string; reason?: string },
+  ) {
+    const { status, reason } = options;
+    const detail = reason === undefined ? status : `${status}: ${reason}`;
+    super(`Transaction ${txHash} ended with status ${detail}`, options);
+    this.name = "TransactionWaitError";
+    this.txHash = txHash;
+    this.status = status;
+    this.reason = reason;
+  }
+}
+
+/** One bounded observation window for an already-broadcast transaction. */
+export interface WaitTransactionOptions {
+  /** Absolute budget in milliseconds for the whole wait. Defaults to 60000. */
+  timeout?: number;
+  /** Delay in milliseconds between polls. Defaults to 2000. */
+  interval?: number;
+  /** Stops waiting, including on in-flight operations; their transports may still finish. */
+  signal?: AbortSignal;
+}
+
+/**
+ * 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.
+ * 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
+ * from exact committed reads.
+ */
+export async function waitTransaction(
+  client: ccc.Client,
+  txHashLike: ccc.HexLike,
+  options: WaitTransactionOptions = {},
+): Promise<void> {
+  const {
+    timeout = DEFAULT_TIMEOUT_MS,
+    interval = DEFAULT_INTERVAL_MS,
+    signal,
+  } = options;
+  validateWaitOptions(timeout, interval);
+  // Normalized before the window opens so a malformed hash cannot leave a timer
+  // or abort listener installed outside the try/finally that closes them.
+  const txHash = ccc.hexFrom(txHashLike);
+  signal?.throwIfAborted();
+
+  const budget = openWaitWindow(timeout, signal);
+  try {
+    for (;;) {
+      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;
+      }
+      if (Date.now() + interval >= budget.deadline) {
+        throw budget.timeoutError;
+      }
+      await pollingSleep(interval, budget);
+    }
+  } finally {
+    budget.close();
+  }
+}
+
+interface WaitWindow {
+  deadline: number;
+  timeoutError: ccc.ErrorClientWaitTransactionTimeout;
+  stopped: Promise<never>;
+  throwIfStopped: () => void;
+  close: () => void;
+}
+
+function validateWaitOptions(timeout: number, interval: number): void {
+  assertCount(interval, "interval");
+  assertCount(timeout, "timeout");
+  // A single unarmed timer owns the whole window, so the budget must fit one.
+  if (timeout > MAX_TIMEOUT_MS) {
+    throw new RangeError(`timeout must not exceed ${String(MAX_TIMEOUT_MS)} ms`);
+  }
+}
+
+function assertCount(value: number, name: string): void {
+  if (!Number.isSafeInteger(value) || value < 0) {
+    throw new RangeError(`${name} must be a non-negative safe integer`);
+  }
+}
+
+function openWaitWindow(timeout: number, signal: AbortSignal | undefined): WaitWindow {
+  const stop = Promise.withResolvers<never>();
+  const timeoutError = new ccc.ErrorClientWaitTransactionTimeout(timeout);
+  const timer = setTimeout(() => {
+    stop.reject(timeoutError);
+  }, timeout);
+  const onAbort = (): void => {
+    stop.reject(abortReason(signal));
+  };
+  signal?.addEventListener("abort", onAbort, { once: true });
+  // Only the operation currently racing this window consumes its rejection.
+  void stop.promise.catch(ignoreSettlement);
+  return {
+    deadline: Date.now() + timeout,
+    timeoutError,
+    stopped: stop.promise,
+    throwIfStopped: (): void => {
+      // Only a promise currently racing the window observes its rejection, so
+      // an abort landing outside a race has to be read from the signal itself.
+      if (signal?.aborted === true) {
+        throw abortReason(signal);
+      }
+    },
+    close: (): void => {
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", onAbort);
+    },
+  };
+}
+
+function ignoreSettlement(): void {
+  // Deliberately empty: the racing caller owns the outcome.
+}
+
+function abortReason(signal: AbortSignal | undefined): Error {
+  return signal?.reason instanceof Error
+    ? signal.reason
+    : new Error("Transaction wait aborted", { cause: signal?.reason });
+}
+
+async function within<T>(operation: () => Promise<T>, budget: WaitWindow): Promise<T> {
+  if (Date.now() >= budget.deadline) {
+    throw budget.timeoutError;
+  }
+  const running = operation();
+  // The operation is not cancelled, so a settlement arriving after the window
+  // closed must stay handled rather than surface as an unhandled one.
+  void running.catch(ignoreSettlement);
+  const result = await Promise.race([running, budget.stopped]);
+  // An operation that settles in the same turn as an abort can win the race, so
+  // cancellation is decided before the result is accepted.
+  budget.throwIfStopped();
+  // An operation that blocks the event loop past the deadline starves the
+  // window timer, so its overdue result must not win the race.
+  if (Date.now() >= budget.deadline) {
+    throw budget.timeoutError;
+  }
+  return result;
+}
+
+async function pollingSleep(interval: number, budget: WaitWindow): Promise<void> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const sleeping = new Promise<void>((resolve) => {
+    timer = setTimeout(resolve, interval);
+  });
+  try {
+    await Promise.race([sleeping, budget.stopped]);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function isCommitted(
+  client: ccc.Client,
+  txHash: ccc.Hex,
+  budget: WaitWindow,
+): Promise<boolean> {
+  const requestor = jsonRpcRequestor(client);
+  // 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 (status === "rejected") {
+    throw new TransactionWaitError(txHash, { status, reason });
+  }
+  return status === "committed";
+}
+
+/** 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,
+  };
+}