@forgezero/runtime 0.1.0

package/dist/finance/chain-addresses.js

@@ -0,0 +1,462 @@
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined")
+    return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+
+// src/finance/money.ts
+class MoneyError extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "MoneyError";
+  }
+}
+var ASSETS = [
+  { code: "USDT", decimals: 6 },
+  { code: "USDC", decimals: 6 },
+  { code: "BTC", decimals: 8 },
+  { code: "ETH", decimals: 18 },
+  { code: "BNB", decimals: 18 },
+  { code: "EUR", decimals: 2 },
+  { code: "USD", decimals: 2 }
+];
+var REGISTRY = new Map(ASSETS.map((asset) => [asset.code, asset]));
+function defineAsset(spec) {
+  if (spec.decimals < 0 || spec.decimals > 30 || !Number.isInteger(spec.decimals)) {
+    throw new MoneyError("UNKNOWN_ASSET", `${spec.code}: decimals must be an integer 0–30.`);
+  }
+  REGISTRY.set(spec.code, spec);
+}
+function assetSpec(code) {
+  const spec = REGISTRY.get(code);
+  if (!spec)
+    throw new MoneyError("UNKNOWN_ASSET", `Unknown asset "${code}". Call defineAsset first.`);
+  return spec;
+}
+var money = (units, asset) => {
+  assetSpec(asset);
+  return { units, asset };
+};
+var zero = (asset) => money(0n, asset);
+function parseAmount(value, asset) {
+  const spec = assetSpec(asset);
+  const text = value.trim();
+  if (!/^-?\d+(\.\d+)?$/.test(text)) {
+    throw new MoneyError("NOT_FINITE", `"${value}" is not a plain decimal amount.`);
+  }
+  const negative = text.startsWith("-");
+  const [whole, fraction = ""] = text.replace("-", "").split(".");
+  if (fraction.length > spec.decimals) {
+    throw new MoneyError("PRECISION_LOSS", `${asset} has ${spec.decimals} decimals; "${value}" has ${fraction.length}.`);
+  }
+  const padded = fraction.padEnd(spec.decimals, "0");
+  const units = BigInt(whole + padded);
+  return { units: negative ? -units : units, asset };
+}
+function formatAmount(amount, options = {}) {
+  const spec = assetSpec(amount.asset);
+  const negative = amount.units < 0n;
+  const digits = (negative ? -amount.units : amount.units).toString().padStart(spec.decimals + 1, "0");
+  const whole = digits.slice(0, digits.length - spec.decimals);
+  let fraction = spec.decimals === 0 ? "" : digits.slice(digits.length - spec.decimals);
+  if (options.trim && fraction)
+    fraction = fraction.replace(/0+$/, "");
+  return `${negative ? "-" : ""}${whole}${fraction ? `.${fraction}` : ""}`;
+}
+function sameAsset(a, b) {
+  if (a.asset !== b.asset) {
+    throw new MoneyError("ASSET_MISMATCH", `Cannot combine ${a.asset} and ${b.asset}.`);
+  }
+}
+function add(a, b) {
+  sameAsset(a, b);
+  return { units: a.units + b.units, asset: a.asset };
+}
+function subtract(a, b) {
+  sameAsset(a, b);
+  return { units: a.units - b.units, asset: a.asset };
+}
+var negate = (amount) => ({ units: -amount.units, asset: amount.asset });
+var abs = (amount) => ({
+  units: amount.units < 0n ? -amount.units : amount.units,
+  asset: amount.asset
+});
+var isZero = (amount) => amount.units === 0n;
+var isNegative = (amount) => amount.units < 0n;
+function compare(a, b) {
+  sameAsset(a, b);
+  return a.units < b.units ? -1 : a.units > b.units ? 1 : 0;
+}
+var equals = (a, b) => a.asset === b.asset && a.units === b.units;
+var ROUNDING = ["down", "up", "half-up"];
+function divideRounded(numerator, denominator, mode) {
+  if (denominator === 0n)
+    throw new MoneyError("DIVIDE_BY_ZERO", "Division by zero.");
+  const negative = numerator < 0n !== denominator < 0n;
+  const a = numerator < 0n ? -numerator : numerator;
+  const b = denominator < 0n ? -denominator : denominator;
+  const quotient = a / b;
+  const remainder = a % b;
+  if (remainder === 0n)
+    return negative ? -quotient : quotient;
+  let result = quotient;
+  if (mode === "up")
+    result += 1n;
+  else if (mode === "half-up" && remainder * 2n >= b)
+    result += 1n;
+  return negative ? -result : result;
+}
+function mulRate(amount, rate, mode = "down") {
+  if (!/^-?\d+(\.\d+)?$/.test(rate.trim())) {
+    throw new MoneyError("NOT_FINITE", `"${rate}" is not a plain decimal rate.`);
+  }
+  const [whole, fraction = ""] = rate.trim().replace("-", "").split(".");
+  const scale = 10n ** BigInt(fraction.length);
+  const scaled = BigInt(whole + fraction) * (rate.trim().startsWith("-") ? -1n : 1n);
+  return { units: divideRounded(amount.units * scaled, scale, mode), asset: amount.asset };
+}
+function convert(amount, to, rate, mode = "down") {
+  const from = assetSpec(amount.asset);
+  const target = assetSpec(to);
+  const asTarget = mulRate({ units: amount.units, asset: to }, rate, mode);
+  const shift = target.decimals - from.decimals;
+  if (shift === 0)
+    return asTarget;
+  if (shift > 0)
+    return { units: asTarget.units * 10n ** BigInt(shift), asset: to };
+  return { units: divideRounded(asTarget.units, 10n ** BigInt(-shift), mode), asset: to };
+}
+function allocate(amount, parts) {
+  if (parts < 1)
+    throw new MoneyError("NOT_FINITE", "Cannot allocate into fewer than one part.");
+  const each = divideRounded(amount.units, BigInt(parts), "down");
+  const allocated = Array.from({ length: parts }, () => each);
+  let remainder = amount.units - each * BigInt(parts);
+  const step = remainder < 0n ? -1n : 1n;
+  for (let index = 0;remainder !== 0n; index = (index + 1) % parts) {
+    allocated[index] += step;
+    remainder -= step;
+  }
+  return allocated.map((units) => ({ units, asset: amount.asset }));
+}
+function toStep(amount, step, mode = "down") {
+  const stepUnits = parseAmount(step, amount.asset).units;
+  if (stepUnits <= 0n)
+    throw new MoneyError("NOT_FINITE", "A step must be positive.");
+  return { units: divideRounded(amount.units, stepUnits, mode) * stepUnits, asset: amount.asset };
+}
+var VERSION = "0.1.0";
+
+// src/finance/custody.ts
+import { keccak_256 } from "@noble/hashes/sha3.js";
+var hex = (bytes) => [...bytes].map((b) => b.toString(16).padStart(2, "0")).join("");
+var bytes = (value) => {
+  const bare = value.replace(/^0x/i, "");
+  if (bare.length % 2)
+    throw new CustodyError("MALFORMED", `Not byte-aligned: ${value}`);
+  const out = new Uint8Array(bare.length / 2);
+  for (let i = 0;i < out.length; i++)
+    out[i] = parseInt(bare.slice(i * 2, i * 2 + 2), 16);
+  return out;
+};
+var concat = (...parts) => {
+  const out = new Uint8Array(parts.reduce((n, p) => n + p.length, 0));
+  let at = 0;
+  for (const part of parts) {
+    out.set(part, at);
+    at += part.length;
+  }
+  return out;
+};
+
+class CustodyError extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "CustodyError";
+  }
+}
+var assertAddress = (value, what) => {
+  if (!/^0x[0-9a-fA-F]{40}$/.test(value)) {
+    throw new CustodyError("NOT_AN_ADDRESS", `${what} is not an address: ${value}`);
+  }
+  return value;
+};
+function toChecksumAddress(address) {
+  const bare = assertAddress(address, "address").slice(2).toLowerCase();
+  const digest = hex(keccak_256(new TextEncoder().encode(bare)));
+  let out = "0x";
+  for (let i = 0;i < bare.length; i++) {
+    out += parseInt(digest[i], 16) >= 8 ? bare[i].toUpperCase() : bare[i];
+  }
+  return out;
+}
+function saltFor(namespace, key) {
+  return `0x${hex(keccak_256(new TextEncoder().encode(`${namespace}:${key}`)))}`;
+}
+function depositAddress(args) {
+  assertAddress(args.factory, "factory");
+  const salt = bytes(args.salt);
+  if (salt.length !== 32)
+    throw new CustodyError("MALFORMED", "A salt is 32 bytes.");
+  const initCodeHash = bytes(args.proxyInitCodeHash);
+  if (initCodeHash.length !== 32)
+    throw new CustodyError("MALFORMED", "An init code hash is 32 bytes.");
+  const digest = keccak_256(concat(Uint8Array.of(255), bytes(args.factory), salt, initCodeHash));
+  return toChecksumAddress(`0x${hex(digest.slice(12))}`);
+}
+var keccakText = (value) => keccak_256(new TextEncoder().encode(value));
+var word = (value) => {
+  const raw = typeof value === "bigint" ? value.toString(16) : value.replace(/^0x/i, "");
+  return bytes(raw.padStart(64, "0"));
+};
+var DOMAIN_TYPEHASH = keccakText("EIP712Domain(string name,string version,uint256 chainId,address verifyingContract)");
+var WITHDRAW_TYPEHASH = keccakText("Withdraw(address token,address to,uint256 amount,uint256 nonce)");
+function domainSeparator(args) {
+  assertAddress(args.vault, "vault");
+  return `0x${hex(keccak_256(concat(DOMAIN_TYPEHASH, keccakText("ForgeZeroColdVault"), keccakText("1"), word(args.chainId), word(args.vault))))}`;
+}
+function withdrawDigest(args) {
+  assertAddress(args.to, "to");
+  assertAddress(args.token, "token");
+  const structHash = keccak_256(concat(WITHDRAW_TYPEHASH, word(args.token), word(args.to), word(args.amount), word(args.nonce)));
+  const separator = bytes(domainSeparator({ chainId: args.chainId, vault: args.vault }));
+  return `0x${hex(keccak_256(concat(Uint8Array.of(25, 1), separator, structHash)))}`;
+}
+function orderSignatures(signatures) {
+  const seen = new Set;
+  for (const entry of signatures) {
+    const key = assertAddress(entry.signer, "signer").toLowerCase();
+    if (seen.has(key)) {
+      throw new CustodyError("BAD_THRESHOLD", `${entry.signer} signed twice; that is one approval.`);
+    }
+    seen.add(key);
+  }
+  return [...signatures].sort((a, b) => BigInt(a.signer) < BigInt(b.signer) ? -1 : 1).map((entry) => entry.signature);
+}
+var VERSION2 = "0.1.0";
+
+// src/finance/chain.ts
+class ChainError extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "ChainError";
+  }
+}
+var ADDRESS_SCHEMES = ["evm", "bitcoin", "tron", "solana"];
+var SCHEME_PATTERNS = {
+  evm: /^0x[a-fA-F0-9]{40}$/,
+  bitcoin: /^(bc1[a-z0-9]{25,62}|[13][a-km-zA-HJ-NP-Z1-9]{25,34})$/,
+  tron: /^T[a-zA-Z0-9]{33}$/,
+  solana: /^[1-9A-HJ-NP-Za-km-z]{32,44}$/
+};
+function validateAddress(address, chain) {
+  if (!SCHEME_PATTERNS[chain.scheme].test(address.trim())) {
+    throw new ChainError("BAD_ADDRESS", `"${address.slice(0, 12)}…" is not a valid ${chain.label} address. Check you have not pasted an address for a different chain — that is the mistake that cannot be undone.`);
+  }
+}
+function assertChain(chain) {
+  if (chain.confirmations.length === 0) {
+    throw new ChainError("BAD_CONFIRMATIONS", `${chain.key} declares no confirmation depth.`);
+  }
+  if (chain.confirmations[0].aboveUsd !== 0) {
+    throw new ChainError("BAD_CONFIRMATIONS", `${chain.key} must have a band starting at 0, or small transfers match no rule.`);
+  }
+  let previous = -1;
+  for (const band of chain.confirmations) {
+    if (band.aboveUsd <= previous) {
+      throw new ChainError("BAD_CONFIRMATIONS", `${chain.key} bands must ascend; ${band.aboveUsd} follows ${previous}.`);
+    }
+    if (!Number.isInteger(band.confirmations) || band.confirmations < 1) {
+      throw new ChainError("BAD_CONFIRMATIONS", `${chain.key} band above $${band.aboveUsd} needs at least one confirmation.`);
+    }
+    previous = band.aboveUsd;
+  }
+}
+function confirmationsFor(chain, usdValue) {
+  let depth = chain.confirmations[0].confirmations;
+  for (const band of chain.confirmations) {
+    if (usdValue >= band.aboveUsd)
+      depth = band.confirmations;
+  }
+  return depth;
+}
+var estimatedSeconds = (chain, usdValue) => confirmationsFor(chain, usdValue) * chain.blockSeconds;
+function createChainRegistry(args) {
+  for (const chain of args.chains)
+    assertChain(chain);
+  const chains = new Map(args.chains.map((chain) => [chain.key, chain]));
+  return {
+    all: () => [...chains.values()].filter((chain) => chain.enabled),
+    byKey(key) {
+      const chain = chains.get(key);
+      if (!chain)
+        throw new ChainError("UNKNOWN_CHAIN", `No chain "${key}" is configured.`);
+      return chain;
+    },
+    assetsOn: (chain) => args.assets.filter((asset) => asset.chain === chain && asset.enabled),
+    chainsFor: (asset) => args.assets.filter((entry) => entry.asset === asset && entry.enabled).map((entry) => chains.get(entry.chain)).filter((chain) => chain?.enabled === true),
+    asset(chain, asset) {
+      const entry = args.assets.find((row) => row.chain === chain && row.asset === asset);
+      if (!entry) {
+        throw new ChainError("UNKNOWN_ASSET", `${asset} is not configured on ${chain}.`);
+      }
+      assetSpec(asset);
+      return entry;
+    },
+    explorerTx: (chain, hash) => {
+      const spec = chains.get(chain);
+      return spec ? `${spec.explorerTx}${hash}` : hash;
+    },
+    explorerAddress: (chain, address) => {
+      const spec = chains.get(chain);
+      return spec ? `${spec.explorerAddress}${address}` : address;
+    },
+    validate(chain, address) {
+      validateAddress(address, this.byKey(chain));
+    }
+  };
+}
+var SEED_CHAINS = [
+  {
+    key: "bsc",
+    label: "BNB Smart Chain",
+    scheme: "evm",
+    chainId: 56,
+    nativeAsset: "BNB",
+    blockSeconds: 3,
+    confirmations: [
+      { aboveUsd: 0, confirmations: 15 },
+      { aboveUsd: 1e4, confirmations: 30 },
+      { aboveUsd: 1e5, confirmations: 60 }
+    ],
+    explorerTx: "https://bscscan.com/tx/",
+    explorerAddress: "https://bscscan.com/address/",
+    enabled: true
+  },
+  {
+    key: "ethereum",
+    label: "Ethereum",
+    scheme: "evm",
+    chainId: 1,
+    nativeAsset: "ETH",
+    blockSeconds: 12,
+    confirmations: [
+      { aboveUsd: 0, confirmations: 12 },
+      { aboveUsd: 50000, confirmations: 32 }
+    ],
+    explorerTx: "https://etherscan.io/tx/",
+    explorerAddress: "https://etherscan.io/address/",
+    enabled: true
+  },
+  {
+    key: "tron",
+    label: "Tron",
+    scheme: "tron",
+    nativeAsset: "TRX",
+    blockSeconds: 3,
+    confirmations: [{ aboveUsd: 0, confirmations: 20 }],
+    explorerTx: "https://tronscan.org/#/transaction/",
+    explorerAddress: "https://tronscan.org/#/address/",
+    enabled: true
+  }
+];
+var SEED_CHAIN_ASSETS = [
+  { chain: "bsc", asset: "BNB", minDeposit: "0.001", enabled: true },
+  {
+    chain: "bsc",
+    asset: "USDT",
+    contract: "0x55d398326f99059ff775485246999027b3197955",
+    minDeposit: "1",
+    enabled: true
+  },
+  { chain: "ethereum", asset: "ETH", minDeposit: "0.005", enabled: true },
+  {
+    chain: "ethereum",
+    asset: "USDT",
+    contract: "0xdac17f958d2ee523a2206206994597c13d831ec7",
+    minDeposit: "20",
+    enabled: true
+  },
+  {
+    chain: "tron",
+    asset: "USDT",
+    contract: "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
+    minDeposit: "1",
+    enabled: true
+  }
+];
+
+// src/finance/chain-addresses.ts
+var COUNTERFACTUAL_SCHEMES = ["evm"];
+
+class AddressError extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "AddressError";
+  }
+}
+var DEPOSIT_NAMESPACE = "deposit";
+var depositSaltFor = (args) => saltFor(DEPOSIT_NAMESPACE, `${args.chain}:${args.owner}`);
+function deriveDepositAddress(args) {
+  if (!args.owner?.trim()) {
+    throw new AddressError("MALFORMED", "An owner key is required to derive an address.");
+  }
+  if (!COUNTERFACTUAL_SCHEMES.includes(args.chain.scheme)) {
+    throw new AddressError("SCHEME_UNSUPPORTED", `${args.chain.label} uses ${args.chain.scheme} addressing, which has no counterfactual derivation here. ` + "Deriving one with the EVM formula would produce an address on no chain at all.");
+  }
+  if (!args.chain.enabled) {
+    throw new AddressError("CHAIN_DISABLED", `${args.chain.label} is not accepting deposits.`);
+  }
+  if (args.deployment.chain !== args.chain.key) {
+    throw new AddressError("MISSING_DEPLOYMENT", `That deployment belongs to ${args.deployment.chain}, not ${args.chain.key}.`);
+  }
+  try {
+    return depositAddress({
+      factory: args.deployment.factory,
+      salt: depositSaltFor({ chain: args.chain.key, owner: args.owner }),
+      proxyInitCodeHash: args.deployment.proxyInitCodeHash
+    });
+  } catch (cause) {
+    if (cause instanceof CustodyError) {
+      throw new AddressError("MALFORMED", `That deployment cannot derive an address: ${cause.message}`);
+    }
+    throw cause;
+  }
+}
+var create2Address = depositAddress;
+function depositAddressBook(args) {
+  const book = new Map;
+  for (const owner of args.owners) {
+    const address = deriveDepositAddress({ ...args, owner });
+    book.set(address.toLowerCase(), owner);
+  }
+  return book;
+}
+var ownerOfAddress = (book, address) => book.get(address.trim().toLowerCase()) ?? null;
+function assertDerivationMatches(args) {
+  if (args.derived.toLowerCase() !== args.reportedByChain.trim().toLowerCase()) {
+    throw new AddressError("MALFORMED", `Derived ${args.derived} but the factory reports ${args.reportedByChain}. ` + "The init code hash is stale — every address derived from it is unreachable.");
+  }
+}
+export {
+  validateAddress,
+  toChecksumAddress,
+  ownerOfAddress,
+  deriveDepositAddress,
+  depositSaltFor,
+  depositAddressBook,
+  create2Address,
+  assertDerivationMatches,
+  COUNTERFACTUAL_SCHEMES,
+  AddressError
+};

package/dist/finance/chain-deposits.d.ts

@@ -0,0 +1,193 @@
+import { type Transaction } from './ledger';
+import { type Money } from './money';
+import { type ChainSpec } from './chain';
+/**
+ * Walking a chain for deposits, and crediting each exactly once.
+ *
+ * Three failures in this loop decide whether an exchange is solvent, and each
+ * one is silent:
+ *
+ *   THE CURSOR      advanced past a batch that failed halfway, and the deposits
+ *                   in the rest of that batch are never looked at again. Nobody
+ *                   notices until a customer asks.
+ *   THE KEY         a credit keyed on anything but the transfer's own identity
+ *                   double-credits the moment a range is replayed — and every
+ *                   chain integration eventually replays a range.
+ *   THE DEPTH       credited before the confirmation depth, so a reorg takes the
+ *                   transaction away and leaves the credit behind.
+ *
+ * Everything here is arranged so that getting one of them wrong is a type error
+ * or a failing test rather than a quiet loss.
+ *
+ * ## Why this holds no I/O
+ *
+ * `@forgezero/runtime` has no credentials and no network. A chain reader is
+ * injected, so the same scanner runs against a real RPC endpoint, a replay of
+ * archived blocks, or a fixture — and the tests exercise the actual reorg and
+ * retry paths rather than a mock of them.
+ */
+export declare class DepositError extends Error {
+    readonly code: 'BAD_RANGE' | 'BAD_CURSOR' | 'UNKNOWN_ASSET' | 'MALFORMED';
+    constructor(code: 'BAD_RANGE' | 'BAD_CURSOR' | 'UNKNOWN_ASSET' | 'MALFORMED', message: string);
+}
+/**
+ * How far this chain has been walked.
+ *
+ * `scannedTo` is the last block whose deposits are FULLY accounted for. It is
+ * the only field that may not be advanced optimistically: everything else here
+ * is reporting, and this one is the record of what has been looked at.
+ */
+export interface DepositCursor {
+    chain: string;
+    /** Last fully-processed block. Exclusive of nothing — this block is done. */
+    scannedTo: number;
+    /** Set when a pass failed, so the next one can report a stall rather than a gap. */
+    lastErrorAtMs?: number;
+    lastErrorReason?: string;
+}
+/** One inbound transfer, as a chain reader reports it. */
+export interface ChainTransfer {
+    txHash: string;
+    /**
+     * Position within the transaction.
+     *
+     * Part of the identity, not decoration: one transaction can pay several
+     * deposit addresses, and keying on the hash alone would credit the first and
+     * treat the rest as duplicates of it.
+     */
+    logIndex: number;
+    blockNumber: number;
+    /** Whatever case the chain reported. Never compared directly — see below. */
+    to: string;
+    asset: string;
+    /** Smallest unit, as a string so no precision is lost crossing JSON. */
+    units: string;
+}
+/**
+ * What a chain reader must provide.
+ *
+ * `head` is separate from `transfersIn` because the depth check needs the tip
+ * as of the same pass. Reading it per transfer would let the tip move mid-pass
+ * and credit two transfers in one block at two different depths.
+ */
+export interface ChainReader {
+    head(): Promise<number>;
+    transfersIn(range: {
+        fromBlock: number;
+        toBlock: number;
+    }): Promise<readonly ChainTransfer[]>;
+}
+/** What one pass did. Returned rather than logged, so a caller can assert on it. */
+export interface ScanReport {
+    chain: string;
+    fromBlock: number;
+    toBlock: number;
+    head: number;
+    /** Transfers that matched a watched address. */
+    matched: number;
+    /** Credited this pass — matched, deep enough, and not already seen. */
+    credited: number;
+    /** Matched but not yet deep enough. Deliberately left for a later pass. */
+    pending: number;
+    /** Matched, deep enough, and already credited. The idempotency key working. */
+    duplicates: number;
+    /** Matched but below the chain's minimum. Not worth the gas to sweep. */
+    dust: number;
+    transactions: readonly Transaction[];
+    cursor: DepositCursor;
+}
+/**
+ * The identity of a transfer, and therefore of its credit.
+ *
+ * `chain:txHash:logIndex`, lowercased. Every part is load-bearing: the chain
+ * because two chains can produce the same hash in principle and the same hash
+ * string in a test for certain; the hash because it is the transfer; the log
+ * index because one transaction can pay several addresses.
+ *
+ * This becomes the ledger transaction's `reference`, which is also the queue's
+ * `dedupeKey` — so the same value that stops a double credit stops a double
+ * delivery, and there is nothing to keep in step.
+ */
+export declare const depositReference: (args: {
+    chain: string;
+    txHash: string;
+    logIndex: number;
+}) => string;
+/**
+ * Is this transfer deep enough to believe?
+ *
+ * The depth required comes from the transfer's USD value, so a large deposit
+ * waits longer than a small one — a single number is too shallow at one end and
+ * too slow at the other, and it is always the large one that costs money.
+ */
+export declare function isConfirmed(args: {
+    chain: ChainSpec;
+    transfer: ChainTransfer;
+    head: number;
+    usdValue: number;
+}): boolean;
+/**
+ * Turn a confirmed transfer into a balanced ledger transaction.
+ *
+ * From an `external` account to the owner's `available` bucket — so the money
+ * arrives from outside the system rather than appearing, and the trial balance
+ * still sums to zero. A deposit that credited a user without debiting anything
+ * would balance only by ignoring it.
+ */
+export declare function creditDeposit(args: {
+    chain: string;
+    transfer: ChainTransfer;
+    owner: string;
+    amount: Money;
+    atMs: number;
+}): Transaction;
+/** Everything a pass needs that is not the chain itself. */
+export interface ScanContext {
+    chain: ChainSpec;
+    reader: ChainReader;
+    /** Lowercased address → owner key. Built by `depositAddressBook`. */
+    addresses: Map<string, string>;
+    /** Already-credited references. The idempotency check. */
+    seen: (reference: string) => boolean | Promise<boolean>;
+    /** What one unit of an asset is worth, for the depth band and the dust floor. */
+    usdValueOf: (amount: Money) => number;
+    /** Below this, sweeping costs more gas than the deposit is worth. */
+    minDepositUsd?: number;
+    /** How many blocks one pass may cover. Bounded so a pass cannot run forever. */
+    batchSize?: number;
+    atMs: number;
+}
+/**
+ * One pass. Reads a bounded range, credits what is ready, advances the cursor.
+ *
+ * The cursor advances ONLY when the whole range has been accounted for. Anything
+ * thrown propagates with the cursor untouched, so the next pass reads the same
+ * range again — which is safe precisely because the reference makes a repeat
+ * credit a no-op. Advancing first and reconciling later is the shape that loses
+ * money, because the evidence of what was missed is the thing that was skipped.
+ */
+export declare function scanOnce(cursor: DepositCursor, context: ScanContext): Promise<ScanReport>;
+/**
+ * Replay a range without touching the cursor.
+ *
+ * Not optional. Every chain integration eventually needs to replay: a reader
+ * that silently returned an empty page, an asset added after the fact, an
+ * incident where the credits are known to be incomplete. Because the reference
+ * is the transfer's own identity, replaying a range that was already handled
+ * produces duplicates in the report and no new transactions — which is what
+ * makes running it safe enough to actually reach for.
+ */
+export declare function rescanRange(range: {
+    fromBlock: number;
+    toBlock: number;
+}, context: ScanContext): Promise<ScanReport>;
+/**
+ * Where a chain's cursor starts.
+ *
+ * From the CURRENT head rather than from zero, because a new integration has no
+ * business replaying the chain's entire history — and `rescanRange` exists for
+ * the case where it does.
+ */
+export declare const cursorFrom: (chain: string, block: number) => DepositCursor;
+/** Human-readable, for a boot log or an operator screen. */
+export declare const describeScan: (report: ScanReport) => string;