@myzonerocks/pact 0.1.0

package/src/canonical.ts

@@ -0,0 +1,94 @@
+import { Money } from "./money.js";
+import { sha256 } from "./crypto.js";
+
+const encoder = new TextEncoder();
+
+// CanonicalWriter builds a deterministic, length-delimited byte string. It is the
+// one encoder every signed and hashed preimage is built with, mirrored
+// field-for-field across the SDKs. Protobuf is deliberately not used here: its
+// serialization is not canonical across runtimes, so a signature over protobuf
+// bytes would not verify between implementations.
+export class CanonicalWriter {
+  private readonly parts: Uint8Array[] = [];
+  private length = 0;
+
+  private push(part: Uint8Array): void {
+    this.parts.push(part);
+    this.length += part.length;
+  }
+
+  // bytes writes a 4-byte big-endian length followed by the raw bytes.
+  bytes(b: Uint8Array): this {
+    const header = new Uint8Array(4);
+    new DataView(header.buffer).setUint32(0, b.length, false);
+    this.push(header);
+    this.push(b);
+    return this;
+  }
+
+  str(s: string): this {
+    return this.bytes(encoder.encode(s));
+  }
+
+  u64(n: number | bigint): this {
+    const b = new Uint8Array(8);
+    new DataView(b.buffer).setBigUint64(0, BigInt(n), false);
+    this.push(b);
+    return this;
+  }
+
+  money(m: Money): this {
+    this.str(m.minor());
+    this.str(m.currency);
+    this.u64(m.exponent);
+    return this;
+  }
+
+  list(xs: readonly string[]): this {
+    this.u64(xs.length);
+    for (const x of xs) {
+      this.str(x);
+    }
+    return this;
+  }
+
+  // stringMap writes a length then each entry, keys sorted ascending by UTF-8
+  // byte value so the encoding never depends on insertion order. The sort is on
+  // encoded bytes, not on UTF-16 code units, to match the other SDKs exactly.
+  stringMap(kv: Readonly<Record<string, string>>): this {
+    const keys = Object.keys(kv).sort(compareUtf8);
+    this.u64(keys.length);
+    for (const k of keys) {
+      this.str(k);
+      this.str(kv[k] as string);
+    }
+    return this;
+  }
+
+  preimage(): Uint8Array {
+    const out = new Uint8Array(this.length);
+    let offset = 0;
+    for (const part of this.parts) {
+      out.set(part, offset);
+      offset += part.length;
+    }
+    return out;
+  }
+}
+
+function compareUtf8(a: string, b: string): number {
+  const ab = encoder.encode(a);
+  const bb = encoder.encode(b);
+  const n = Math.min(ab.length, bb.length);
+  for (let i = 0; i < n; i++) {
+    const diff = (ab[i] as number) - (bb[i] as number);
+    if (diff !== 0) return diff;
+  }
+  return ab.length - bb.length;
+}
+
+// hashPreimage is the SHA-256 of a preimage. Every message hash and receipt is
+// derived through it.
+export function hashPreimage(preimage: Uint8Array): Uint8Array {
+  return sha256(preimage);
+}

package/src/client.ts

@@ -0,0 +1,605 @@
+import { randomBytes } from "node:crypto";
+import { State } from "./state.js";
+import { Money } from "./money.js";
+import { DEFAULT_SKEW_MILLIS, domain } from "./protocol.js";
+import { CanonicalWriter, hashPreimage } from "./canonical.js";
+import {
+  intentHash,
+  quoteHash,
+  authorizationHash,
+  corridorReceipt,
+  isDirect,
+  BRIDGE_PASSTHROUGH,
+  type Intent,
+  type Quote,
+  type Authorization,
+  type Settlement,
+} from "./message.js";
+import { authorize as signAuthorization, verifyAuthorization, type Signer, type Verifier } from "./signing.js";
+import { PassThroughBridge, type Bridge, type ConvertResult } from "./bridge.js";
+import { railInList, type PayInLeg, type PayOutLeg, type CollectResult } from "./leg.js";
+import type { AdapterEvent } from "./adapter.js";
+import { route, type Policy, PolicyKind, NoQuoteError, isExpired } from "./router.js";
+import { permissiveKyc, allowRisk, withinLimits, type KycProvider, type RiskHook } from "./compliance.js";
+import { MemoryLedger, eventReceipt, type Ledger, type LedgerEvent } from "./ledger.js";
+
+// Clock returns the current time in Unix milliseconds; IdGen returns a fresh
+// collision-resistant identifier. Both are injectable so tests and replay can
+// pin them.
+export type Clock = () => number;
+export type IdGen = () => string;
+
+export function systemClock(): number {
+  return Date.now();
+}
+
+export function randomId(): string {
+  return Buffer.from(randomBytes(16)).toString("hex");
+}
+
+// ClientConfig assembles a Client. Legs, a ledger, and a verifier are required;
+// the remaining fields fall back to safe defaults. escrowRef is where a bridged
+// corridor's pay-in leg deposits, before the bridge converts and the pay-out leg
+// disburses.
+export interface ClientConfig {
+  payIn?: PayInLeg[];
+  payOut?: PayOutLeg[];
+  bridges?: Bridge[];
+  ledger?: Ledger;
+  policy?: Policy;
+  verifier: Verifier;
+  kyc?: KycProvider;
+  risk?: RiskHook;
+  clock?: Clock;
+  idGen?: IdGen;
+  skew?: number;
+  escrowRef?: string;
+}
+
+export interface IntentSpec {
+  senderRef: string;
+  recipientRef: string;
+  amount: Money;
+  memo?: string;
+  expiresAt: number;
+  allowedRails?: string[];
+  metadata?: Record<string, string>;
+}
+
+// Funding is a payer's chosen way to pay: which pay-in leg and in what currency.
+// The chat UI collects it when the payer picks an option.
+export interface Funding {
+  payInAdapterId: string;
+  currency: string;
+  exponent: number;
+}
+
+// Client is the corridor orchestrator a host embeds. It mints intents, composes
+// corridor quotes across legs and bridges, authorizes with the host's signer,
+// and runs collect -> convert -> disburse, folding each step into the ledger. It
+// never holds funds and never touches transport.
+export class Client {
+  private readonly payIn = new Map<string, PayInLeg>();
+  private readonly payOut = new Map<string, PayOutLeg>();
+  private readonly bridges = new Map<string, Bridge>();
+  private readonly ledger: Ledger;
+  private readonly policy: Policy;
+  private readonly verifier: Verifier;
+  private readonly kyc: KycProvider;
+  private readonly risk: RiskHook;
+  private readonly clock: Clock;
+  private readonly idGen: IdGen;
+  private readonly skew: number;
+  private readonly escrowRef: string;
+  private readonly subscribers: Array<(event: LedgerEvent) => void> = [];
+
+  constructor(cfg: ClientConfig) {
+    for (const l of cfg.payIn ?? []) this.payIn.set(l.id, l);
+    for (const l of cfg.payOut ?? []) this.payOut.set(l.id, l);
+    for (const b of cfg.bridges ?? []) this.bridges.set(b.id, b);
+    if (this.bridges.size === 0) {
+      this.bridges.set(BRIDGE_PASSTHROUGH, new PassThroughBridge());
+    }
+    this.ledger = cfg.ledger ?? new MemoryLedger();
+    this.policy = cfg.policy ?? { kind: PolicyKind.Cheapest };
+    this.verifier = cfg.verifier;
+    this.kyc = cfg.kyc ?? permissiveKyc;
+    this.risk = cfg.risk ?? allowRisk;
+    this.clock = cfg.clock ?? systemClock;
+    this.idGen = cfg.idGen ?? randomId;
+    this.skew = cfg.skew ?? DEFAULT_SKEW_MILLIS;
+    this.escrowRef = cfg.escrowRef ?? "";
+  }
+
+  // createIntent mints an intent and records it as a draft.
+  createIntent(spec: IntentSpec): Intent {
+    const intent: Intent = {
+      id: this.idGen(),
+      senderRef: spec.senderRef,
+      recipientRef: spec.recipientRef,
+      amount: spec.amount,
+      memo: spec.memo ?? "",
+      expiresAt: spec.expiresAt,
+      allowedRails: spec.allowedRails ?? [],
+      metadata: spec.metadata ?? {},
+    };
+    this.ledger.apply({ intentId: intent.id, to: State.Draft, payloadHash: intentHash(intent), intent });
+    return intent;
+  }
+
+  // quoteOptions composes a corridor quote for each way the payer offered to fund
+  // the payment. For every funding option it finds a bridge that can reach the
+  // recipient's currency and a pay-out leg that can deliver it, prices the whole
+  // corridor, and returns the options for the payer to choose among.
+  async quoteOptions(intent: Intent, funding: Funding[]): Promise<Quote[]> {
+    const quotes: Quote[] = [];
+    let lastErr: unknown;
+    for (const f of funding) {
+      const payInLeg = this.payIn.get(f.payInAdapterId);
+      if (!payInLeg) {
+        lastErr = new Error(`pact: no pay-in leg ${JSON.stringify(f.payInAdapterId)}`);
+        continue;
+      }
+      if (!containsOrEmpty(payInLeg.payInCapabilities().currencies, f.currency)) {
+        lastErr = new Error(`pact: pay-in leg ${JSON.stringify(f.payInAdapterId)} does not fund ${f.currency}`);
+        continue;
+      }
+      try {
+        quotes.push(await this.composeQuote(intent, payInLeg, f));
+      } catch (err) {
+        lastErr = err;
+      }
+    }
+    if (quotes.length === 0) {
+      if (lastErr instanceof Error) throw lastErr;
+      throw new NoQuoteError("no fundable corridor");
+    }
+    return quotes;
+  }
+
+  // composeQuote prices one corridor: a pay-out leg delivers the recipient's
+  // currency, a bridge plans the source needed from the payer's currency, and the
+  // leg and bridge fees are summed into what the payer pays.
+  private async composeQuote(intent: Intent, payInLeg: PayInLeg, f: Funding): Promise<Quote> {
+    const payOutLeg = this.pickPayOut(intent);
+    const bridge = this.pickBridge(f.currency, intent.amount.currency);
+
+    const bridged = await bridge.quote(intent.amount, f.currency, f.exponent);
+    const src = bridged.srcAmount.add(bridged.fee);
+    return {
+      id: this.idGen(),
+      intentId: intent.id,
+      payInAdapterId: payInLeg.id,
+      payInRail: firstRail(payInLeg.payInCapabilities().rails),
+      payOutAdapterId: payOutLeg.id,
+      payOutRail: this.payOutRail(payOutLeg, intent),
+      bridgeId: bridge.id,
+      srcAmount: src,
+      dstAmount: intent.amount,
+      fees: bridged.fee,
+      fxRate: bridged.fxRate,
+      expiresAt: intent.expiresAt,
+      providerQuoteRef: "",
+      latencyEstimateMs: 0,
+    };
+  }
+
+  // pickPayOut finds a pay-out leg that delivers the recipient's currency on an
+  // allowed rail.
+  private pickPayOut(intent: Intent): PayOutLeg {
+    for (const leg of this.payOut.values()) {
+      const caps = leg.payOutCapabilities();
+      if (!containsOrEmpty(caps.currencies, intent.amount.currency)) continue;
+      if (this.payOutRail(leg, intent) !== "") return leg;
+    }
+    throw new NoQuoteError("no pay-out leg for the recipient's currency and rails");
+  }
+
+  // payOutRail returns the rail this leg would use for the intent, or empty if
+  // none of the intent's allowed rails are served.
+  private payOutRail(leg: PayOutLeg, intent: Intent): string {
+    const caps = leg.payOutCapabilities();
+    if (intent.allowedRails.length === 0) return firstRail(caps.rails);
+    for (const rail of intent.allowedRails) {
+      if (railInList(caps.rails, rail)) return rail;
+    }
+    return "";
+  }
+
+  // pickBridge selects a bridge that converts the payer's currency to the
+  // recipient's. Same-currency prefers pass-through; otherwise a converting
+  // bridge.
+  private pickBridge(srcCurrency: string, dstCurrency: string): Bridge {
+    if (srcCurrency === dstCurrency) {
+      const passThrough = this.bridges.get(BRIDGE_PASSTHROUGH);
+      if (passThrough) return passThrough;
+    }
+    for (const b of this.bridges.values()) {
+      if (b.id !== BRIDGE_PASSTHROUGH) return b;
+    }
+    const passThrough = this.bridges.get(BRIDGE_PASSTHROUGH);
+    if (passThrough && srcCurrency === dstCurrency) return passThrough;
+    throw new NoQuoteError(`no bridge from ${srcCurrency} to ${dstCurrency}`);
+  }
+
+  // select applies the configured policy to a set of corridor quotes.
+  async select(quotes: Quote[], identity: string): Promise<Quote> {
+    const status = await this.kyc.status(identity);
+    return route(quotes, this.policy, status, this.clock(), this.skew);
+  }
+
+  // authorize records the chosen corridor, runs the risk hook, signs the sender's
+  // commitment, and records the authorization, advancing draft -> quoted ->
+  // authorized.
+  async authorize(intent: Intent, quote: Quote, signer: Signer): Promise<Authorization> {
+    if (quote.intentId !== intent.id) {
+      throw new Error("pact: quote does not belong to intent");
+    }
+    const now = this.clock();
+    if (isExpired(intent.expiresAt, now, this.skew)) {
+      throw new Error("pact: intent has expired");
+    }
+    if (isExpired(quote.expiresAt, now, this.skew)) {
+      throw new Error("pact: quote has expired");
+    }
+    const status = await this.kyc.status(signer.identity());
+    if (!withinLimits(status, quote)) {
+      throw new Error("pact: quote exceeds KYC limit");
+    }
+    const decision = this.risk.evaluate(signer.identity(), intent, quote);
+    if (!decision.allow) {
+      throw new Error(`pact: risk hook vetoed authorization: ${decision.reason}`);
+    }
+
+    this.ledger.apply({ intentId: intent.id, to: State.Quoted, payloadHash: quoteHash(quote), quote });
+    const auth = signAuthorization(intent, quote, signer, now);
+    const authHash = authorizationHash(intentHash(intent), quoteHash(quote), auth.signerIdentity, auth.signedAt);
+    this.ledger.apply({ intentId: intent.id, to: State.Authorized, payloadHash: authHash, authorization: auth });
+    return auth;
+  }
+
+  // initiate starts a corridor and returns its in-flight state. It verifies the
+  // authorization, kicks off the pay-in leg, records the state, and returns
+  // immediately — it does not wait for the provider to confirm. Settlement is
+  // driven forward by advance as provider events arrive, so no promise or
+  // connection is held open per payment and durable state lives only in the
+  // ledger.
+  async initiate(intent: Intent, quote: Quote, auth: Authorization): Promise<State> {
+    verifyAuthorization(auth, intent, quote, this.verifier);
+    const payInLeg = this.payIn.get(quote.payInAdapterId);
+    if (!payInLeg) {
+      throw new Error(`pact: no pay-in leg ${JSON.stringify(quote.payInAdapterId)}`);
+    }
+
+    // A direct corridor collects straight to the recipient; a bridged one
+    // collects into escrow first.
+    let deliverTo = recipientDestination(intent);
+    let to = State.Submitted;
+    if (!isDirect(quote)) {
+      deliverTo = this.escrowRef;
+      to = State.Collecting;
+    }
+    const collected = await payInLeg.collect(intent.id, quote, auth, deliverTo);
+    this.ledger.apply({ intentId: intent.id, to, payloadHash: submitHash(collected.providerRef), collect: collected });
+    return to;
+  }
+
+  // advance resumes a corridor when a provider event arrives — a webhook, a
+  // callback, a chain receipt, already normalized into an AdapterEvent. It reads
+  // the corridor's state from the ledger, interprets the event against it, and
+  // moves it forward one hop. It returns the terminal settlement once reached and
+  // the resulting state. Advancing the same step twice is idempotent, so a
+  // duplicated webhook settles once.
+  async advance(intentId: string, adapterId: string, event: AdapterEvent): Promise<{ settlement: Settlement; state: State }> {
+    const events = this.ledger.events(intentId);
+    const replayed = replay(events);
+    if (!replayed) {
+      throw new Error("pact: intent has no recorded authorization to advance");
+    }
+    const { intent, quote, authorization: auth } = replayed;
+    const authHash = authorizationHash(intentHash(intent), quoteHash(quote), auth.signerIdentity, auth.signedAt);
+    const current = this.ledger.state(intentId);
+    const failed = event.state === State.Failed;
+    const fromPayIn = adapterId === quote.payInAdapterId;
+    const fromPayOut = adapterId === quote.payOutAdapterId;
+
+    // A direct corridor's pay-in confirms and it settles.
+    if (fromPayIn && current === State.Submitted) {
+      if (failed) return this.recordFailure(intentId, authHash, quote, event.reason);
+      const ref = payInRef(events);
+      const settlement: Settlement = {
+        intentId,
+        state: State.Settled,
+        adapterId: quote.payInAdapterId,
+        providerTxRef: ref,
+        onchainTxHash: "",
+        receiptHash: corridorReceipt(authHash, ref, ref, quote.fxRate, "", State.Settled),
+        reason: "",
+        settledAt: this.clock(),
+      };
+      return this.finishAdvance(intentId, State.Settled, settlement);
+    }
+
+    // A bridged corridor's pay-in confirms; hold, convert, and kick off the
+    // pay-out.
+    if (fromPayIn && current === State.Collecting) {
+      // Nothing has entered escrow, so a failure here is a plain failure.
+      if (failed) return this.recordFailure(intentId, authHash, quote, event.reason);
+      return this.holdAndDisburse(intent, quote, authHash, events);
+    }
+
+    // The pay-out confirms and the corridor settles, or fails and unwinds.
+    if (fromPayOut && current === State.Disbursing) {
+      if (failed) return this.unwind(intentId, quote, authHash, event.reason);
+      return this.settleBridged(intentId, quote, authHash, events);
+    }
+
+    // Any other event — a duplicate webhook, or one for a phase already past — is
+    // a no-op. This is what makes a re-delivered provider callback settle once.
+    return { settlement: lastSettlement(events), state: current };
+  }
+
+  // holdAndDisburse records the escrow hold, converts through the bridge, and
+  // kicks off the pay-out leg, leaving the corridor disbursing until its pay-out
+  // confirms.
+  private async holdAndDisburse(
+    intent: Intent,
+    quote: Quote,
+    authHash: Uint8Array,
+    events: LedgerEvent[],
+  ): Promise<{ settlement: Settlement; state: State }> {
+    const payOutLeg = this.payOut.get(quote.payOutAdapterId);
+    if (!payOutLeg) {
+      throw new Error(`pact: no pay-out leg ${JSON.stringify(quote.payOutAdapterId)}`);
+    }
+    const bridge = this.bridges.get(quote.bridgeId);
+    if (!bridge) {
+      throw new Error(`pact: no bridge ${JSON.stringify(quote.bridgeId)}`);
+    }
+    const collected = collectResult(events);
+    this.ledger.apply({
+      intentId: intent.id,
+      to: State.Held,
+      payloadHash: hashString(domain("held"), collected.providerRef),
+    });
+
+    let converted: ConvertResult;
+    try {
+      converted = await bridge.convert(intent.id, collected.received, intent.amount.currency, intent.amount.exponent);
+    } catch (err) {
+      return this.unwind(intent.id, quote, authHash, reasonOf(err));
+    }
+    let disbursed;
+    try {
+      disbursed = await payOutLeg.disburse(intent.id, quote, recipientDestination(intent));
+    } catch (err) {
+      return this.unwind(intent.id, quote, authHash, reasonOf(err));
+    }
+    const marker: Settlement = {
+      intentId: intent.id,
+      state: State.Disbursing,
+      adapterId: payOutLeg.id,
+      providerTxRef: disbursed.providerRef,
+      onchainTxHash: "",
+      receiptHash: new Uint8Array(0),
+      reason: "",
+      settledAt: 0,
+    };
+    this.ledger.apply({
+      intentId: intent.id,
+      to: State.Disbursing,
+      payloadHash: hashString(domain("disburse"), disbursed.providerRef),
+      settlement: marker,
+      bridge: converted,
+    });
+    return { settlement: emptySettlement(), state: State.Disbursing };
+  }
+
+  // settleBridged closes out a bridged corridor once its pay-out has confirmed,
+  // binding both legs and the FX into the linked receipt.
+  private settleBridged(
+    intentId: string,
+    quote: Quote,
+    authHash: Uint8Array,
+    events: LedgerEvent[],
+  ): { settlement: Settlement; state: State } {
+    const inRef = payInRef(events);
+    const { payOut: outRef, bridge: bridgeRef } = disburseRefs(events);
+    const settlement: Settlement = {
+      intentId,
+      state: State.Settled,
+      adapterId: quote.payOutAdapterId,
+      providerTxRef: outRef,
+      onchainTxHash: "",
+      receiptHash: corridorReceipt(authHash, inRef, outRef, quote.fxRate, bridgeRef, State.Settled),
+      reason: "",
+      settledAt: this.clock(),
+    };
+    return this.finishAdvance(intentId, State.Settled, settlement);
+  }
+
+  // unwind refunds the payer from escrow when a bridged corridor cannot complete
+  // its pay-out, moving to refunding then refunded.
+  private async unwind(
+    intentId: string,
+    quote: Quote,
+    authHash: Uint8Array,
+    reason: string,
+  ): Promise<{ settlement: Settlement; state: State }> {
+    this.ledger.apply({
+      intentId,
+      to: State.Refunding,
+      payloadHash: hashString(domain("refunding"), reason),
+    });
+    const payInLeg = this.payIn.get(quote.payInAdapterId);
+    if (payInLeg) {
+      await payInLeg.refundIn(intentId, payInLeg.payInCapabilities().refunds, reason);
+    }
+    const settlement: Settlement = {
+      intentId,
+      state: State.Refunded,
+      adapterId: quote.payInAdapterId,
+      providerTxRef: "",
+      onchainTxHash: "",
+      receiptHash: corridorReceipt(authHash, "", "", quote.fxRate, "", State.Refunded),
+      reason,
+      settledAt: this.clock(),
+    };
+    return this.finishAdvance(intentId, State.Refunded, settlement);
+  }
+
+  // recordFailure marks a pay-in that failed before any escrow was taken.
+  private recordFailure(
+    intentId: string,
+    authHash: Uint8Array,
+    quote: Quote,
+    reason: string,
+  ): { settlement: Settlement; state: State } {
+    const settlement: Settlement = {
+      intentId,
+      state: State.Failed,
+      adapterId: quote.payInAdapterId,
+      providerTxRef: "",
+      onchainTxHash: "",
+      receiptHash: corridorReceipt(authHash, "", "", quote.fxRate, "", State.Failed),
+      reason,
+      settledAt: this.clock(),
+    };
+    return this.finishAdvance(intentId, State.Failed, settlement);
+  }
+
+  private finishAdvance(intentId: string, state: State, settlement: Settlement): { settlement: Settlement; state: State } {
+    const finished = this.finish(intentId, state, settlement);
+    return { settlement: finished, state };
+  }
+
+  private finish(intentId: string, state: State, settlement: Settlement): Settlement {
+    const event = this.ledger.apply({ intentId, to: state, payloadHash: settlement.receiptHash, settlement });
+    this.notify(event);
+    return settlement;
+  }
+
+  // expire records that an intent's deadline passed before it settled.
+  expire(intentId: string): void {
+    this.ledger.apply({
+      intentId,
+      to: State.Expired,
+      payloadHash: eventReceipt(0, intentId, State.Expired, new Uint8Array(0)),
+    });
+  }
+
+  subscribe(handler: (event: LedgerEvent) => void): void {
+    this.subscribers.push(handler);
+  }
+
+  history(intentId: string): LedgerEvent[] {
+    return this.ledger.events(intentId);
+  }
+
+  state(intentId: string): State {
+    return this.ledger.state(intentId);
+  }
+
+  head(intentId: string): Uint8Array | undefined {
+    return this.ledger.head(intentId);
+  }
+
+  private notify(event: LedgerEvent): void {
+    for (const h of this.subscribers) h(event);
+  }
+}
+
+// recipientDestination is the rail-specific handle the pay-out lands on — a
+// crypto address, a phone number — carried in metadata, falling back to the
+// generic recipient reference.
+export function recipientDestination(intent: Intent): string {
+  const d = intent.metadata["recipient_destination"];
+  return d ? d : intent.recipientRef;
+}
+
+// replay reconstructs the intent, quote, and authorization from the ledger so a
+// corridor can resume without the caller holding them.
+function replay(events: LedgerEvent[]): { intent: Intent; quote: Quote; authorization: Authorization } | undefined {
+  let intent: Intent | undefined;
+  let quote: Quote | undefined;
+  let authorization: Authorization | undefined;
+  for (const e of events) {
+    if (e.intent) intent = e.intent;
+    if (e.quote) quote = e.quote;
+    if (e.authorization) authorization = e.authorization;
+  }
+  if (!intent || !quote || !authorization) return undefined;
+  return { intent, quote, authorization };
+}
+
+// collectResult returns what the pay-in leg recorded, or an empty result if none
+// is present.
+function collectResult(events: LedgerEvent[]): CollectResult {
+  for (const e of events) {
+    if (e.collect) return e.collect;
+  }
+  return { providerRef: "", received: Money.create("", 0, 0n) };
+}
+
+function payInRef(events: LedgerEvent[]): string {
+  return collectResult(events).providerRef;
+}
+
+// disburseRefs returns the pay-out provider reference and the bridge receipt
+// reference recorded on the disbursing step.
+function disburseRefs(events: LedgerEvent[]): { payOut: string; bridge: string } {
+  let payOut = "";
+  let bridge = "";
+  for (const e of events) {
+    if (e.state === State.Disbursing) {
+      if (e.settlement) payOut = e.settlement.providerTxRef;
+      if (e.bridge) bridge = e.bridge.receiptRef;
+    }
+  }
+  return { payOut, bridge };
+}
+
+// lastSettlement returns the settlement recorded on an intent's most recent
+// event, if any, so an idempotent no-op can echo the outcome already reached.
+function lastSettlement(events: LedgerEvent[]): Settlement {
+  for (let i = events.length - 1; i >= 0; i--) {
+    const e = events[i] as LedgerEvent;
+    if (e.settlement) return e.settlement;
+  }
+  return emptySettlement();
+}
+
+function emptySettlement(): Settlement {
+  return {
+    intentId: "",
+    state: State.Unspecified,
+    adapterId: "",
+    providerTxRef: "",
+    onchainTxHash: "",
+    receiptHash: new Uint8Array(0),
+    reason: "",
+    settledAt: 0,
+  };
+}
+
+function reasonOf(cause: unknown): string {
+  return cause instanceof Error ? cause.message : String(cause);
+}
+
+function containsOrEmpty(xs: string[], target: string): boolean {
+  return xs.length === 0 || xs.includes(target);
+}
+
+function firstRail(rails: string[]): string {
+  return rails.length === 0 ? "" : (rails[0] as string);
+}
+
+// submitHash commits to a provider reference so a step carries a payload distinct
+// from every other.
+function submitHash(providerRef: string): Uint8Array {
+  return hashString(domain("submit"), providerRef);
+}
+
+function hashString(domainTag: string, value: string): Uint8Array {
+  return hashPreimage(new CanonicalWriter().str(domainTag).str(value).preimage());
+}