@myzonerocks/pact 0.1.3 → 0.1.6

package/src/ledger.ts

@@ -49,11 +49,19 @@ export class IdempotencyConflictError extends Error {
   }
 }
 
+// ApplyResult carries the appended event and whether this call actually appended
+// it (created) or found the step already recorded and returned the existing one,
+// so a caller can claim a step before a side effect and abort if it did not win.
+export interface ApplyResult {
+  event: LedgerEvent;
+  created: boolean;
+}
+
 // Ledger is the append-only store of payment history. The kernel ships an
 // in-memory reference; durable backends implement the same interface and must
 // preserve the same event order, receipts, and Merkle head.
 export interface Ledger {
-  apply(t: Transition): LedgerEvent;
+  apply(t: Transition): ApplyResult;
   state(intentId: string): State;
   events(intentId: string): LedgerEvent[];
   head(intentId: string): Uint8Array | undefined;
@@ -65,14 +73,14 @@ const zeroLeaf = new Uint8Array(32);
 export class MemoryLedger implements Ledger {
   private readonly byIntent = new Map<string, LedgerEvent[]>();
 
-  apply(t: Transition): LedgerEvent {
+  apply(t: Transition): ApplyResult {
     const history = this.byIntent.get(t.intentId) ?? [];
 
     // A repeat of the same step is a no-op returning the first result; the same
     // step with a different payload is a conflict.
     for (const e of history) {
       if (e.state === t.to) {
-        if (bytesEqual(e.payloadHash, t.payloadHash)) return e;
+        if (bytesEqual(e.payloadHash, t.payloadHash)) return { event: e, created: false };
         throw new IdempotencyConflictError();
       }
     }
@@ -102,7 +110,7 @@ export class MemoryLedger implements Ledger {
       ...(t.bridge ? { bridge: t.bridge } : {}),
     };
     this.byIntent.set(t.intentId, [...history, event]);
-    return event;
+    return { event, created: true };
   }
 
   state(intentId: string): State {

package/src/leg.ts

@@ -33,7 +33,10 @@ export interface PayInLeg {
   id: string;
   payInCapabilities(): PayInCapabilities;
   collect(intentId: string, quote: Quote, auth: Authorization, deliverTo: string): Promise<CollectResult>;
-  refundIn(intentId: string, kind: RefundKind, reason: string): Promise<Settlement>;
+  // refundIn returns amount to the payer. The amount is explicit so a leg can
+  // honour a partial refund, not only a full one; a leg that can refund at all
+  // must return exactly it.
+  refundIn(intentId: string, kind: RefundKind, amount: Money, reason: string): Promise<Settlement>;
 }
 
 // PayInPreparation is what an interactive pay-in leg hands back so the payer can

package/src/message.ts

@@ -153,14 +153,17 @@ export function receiptHash(authHash: Uint8Array, providerTxRef: string, state:
   );
 }
 
-// corridorReceipt binds both legs of a bridged corridor and the FX rate into one
-// commitment, so the payer can prove they funded X and the recipient can prove
-// they received Y as a single transaction, without revealing anything else.
+// corridorReceipt binds both legs of a bridged corridor and the amount that
+// actually moved into one commitment, so the payer can prove they funded X and
+// the recipient can prove they received Y as a single transaction, without
+// revealing anything else. The amount is the value the corridor really delivered
+// on settle or returned on refund — not the quoted rate, which the conversion may
+// not have matched — so the receipt attests the outcome, not the plan.
 export function corridorReceipt(
   authHash: Uint8Array,
   payInProviderRef: string,
   payOutProviderRef: string,
-  fxRate: string,
+  amount: Money,
   bridgeReceiptRef: string,
   state: State,
 ): Uint8Array {
@@ -170,7 +173,7 @@ export function corridorReceipt(
       .bytes(authHash)
       .str(payInProviderRef)
       .str(payOutProviderRef)
-      .str(fxRate)
+      .money(amount)
       .str(bridgeReceiptRef)
       .str(stateName[state])
       .preimage(),

package/src/money.ts

@@ -12,6 +12,14 @@ export class Money {
     private readonly amount: bigint,
   ) {}
 
+  // zero is the empty-currency, zero-amount sentinel used where a corridor moved
+  // no value — a failure receipt, or an absent bridge result. It is not a valid
+  // wire amount (an empty currency never parses), only an internal placeholder,
+  // and it encodes canonically as minor "0", currency "", exponent 0.
+  static zero(): Money {
+    return new Money("", 0, 0n);
+  }
+
   static create(currency: string, exponent: number, amount: bigint): Money {
     if (!currencyPattern.test(currency)) {
       throw new Error("pact: currency must match [A-Z0-9]{1,16}");
@@ -26,10 +34,18 @@ export class Money {
   }
 
   // parse builds Money from a decimal-ASCII minor-unit string, the form used on
-  // the wire.
+  // the wire. The grammar is a bare non-negative integer — no sign, no radix
+  // prefix, no whitespace, no leading zeros — pinned identically across every SDK
+  // so two participants never disagree on whether a message is valid or on the
+  // value it decodes to.
   static parse(currency: string, exponent: number, minor: string): Money {
-    if (!/^\d+$/.test(minor)) {
-      throw new Error(`pact: ${minor} is not a base-10 integer`);
+    // Bound the length so an untrusted string can't force a huge bigint parse
+    // before capability limits ever see it; eighty digits is far past any amount.
+    if (minor.length > 80) {
+      throw new Error("pact: amount has more than 80 digits");
+    }
+    if (!/^(0|[1-9][0-9]*)$/.test(minor)) {
+      throw new Error(`pact: ${minor} is not a canonical base-10 integer`);
     }
     return Money.create(currency, exponent, BigInt(minor));
   }

package/src/protocol.ts

@@ -14,6 +14,15 @@ export function domain(kind: string): string {
   return domainPrefix + kind;
 }
 
+// idempotencyKey binds a provider mutation to one protocol step so a retry reuses
+// the same key and the provider deduplicates it into a single side effect. ref is
+// the stable reference the step acts on (the intent id, or a provider object id);
+// step names the operation. Every adapter derives its provider idempotency key
+// this way, so the same (ref, step) always maps to the same key.
+export function idempotencyKey(ref: string, step: string): string {
+  return `${ID}:${ref}:${step}`;
+}
+
 // DEFAULT_SKEW_MILLIS is the tolerated clock difference when deciding whether an
 // intent or quote has expired.
 export const DEFAULT_SKEW_MILLIS = 120_000;

package/src/router.ts

@@ -28,28 +28,52 @@ export function isExpired(deadline: number, now: number, skew: number): boolean
   return deadline + skew <= now;
 }
 
+// maxQuotes and maxFundingOptions bound the lists the router ranks and the client
+// quotes over, so a caller (or an adapter-supplied list forwarded through one)
+// cannot force unbounded work. The limits are generous next to any real corridor.
+export const maxQuotes = 256;
+export const maxFundingOptions = 64;
+
 // route selects one quote deterministically. It first discards quotes that are
 // expired against now or that exceed the identity's KYC limit, then ranks the
 // survivors by the policy. Ties break by pay-in adapter, then pay-out adapter,
 // then quote id, so the choice is total and stable and never depends on input
 // order or randomness.
 export function route(quotes: Quote[], policy: Policy, kyc: KycStatus, now: number, skew: number): Quote {
+  if (quotes.length > maxQuotes) {
+    throw new NoQuoteError(`quote set of ${quotes.length} exceeds the maximum of ${maxQuotes}`);
+  }
   const eligible = quotes.filter((q) => !isExpired(q.expiresAt, now, skew) && withinLimits(kyc, q));
   if (eligible.length === 0) {
     throw new NoQuoteError("all quotes expired or over limit");
   }
+  // Ranking by cost compares source amounts, which is meaningful only in one
+  // currency: the router holds no rate to weigh a dollar against a shilling. A
+  // mixed-currency set would otherwise fall through to the id tie-break and
+  // quietly crown a costlier quote, so it is refused rather than mis-ranked.
+  if (policy.kind === PolicyKind.Cheapest && spansSourceCurrencies(eligible)) {
+    throw new NoQuoteError("cannot rank by cost across source currencies without a common rate");
+  }
   const rank = rankFn(policy);
   eligible.sort((a, b) => {
     const primary = rank(a, b);
     if (primary !== 0) return primary;
-    if (a.payInAdapterId !== b.payInAdapterId) return a.payInAdapterId < b.payInAdapterId ? -1 : 1;
-    if (a.payOutAdapterId !== b.payOutAdapterId) return a.payOutAdapterId < b.payOutAdapterId ? -1 : 1;
-    if (a.id !== b.id) return a.id < b.id ? -1 : 1;
-    return 0;
+    const byPayIn = compareUtf8(a.payInAdapterId, b.payInAdapterId);
+    if (byPayIn !== 0) return byPayIn;
+    const byPayOut = compareUtf8(a.payOutAdapterId, b.payOutAdapterId);
+    if (byPayOut !== 0) return byPayOut;
+    return compareUtf8(a.id, b.id);
   });
   return eligible[0] as Quote;
 }
 
+// spansSourceCurrencies reports whether the quotes carry more than one distinct
+// source currency, the case a cost ranking cannot resolve without a rate.
+function spansSourceCurrencies(quotes: Quote[]): boolean {
+  const first = quotes[0]!.srcAmount.currency;
+  return quotes.some((q) => q.srcAmount.currency !== first);
+}
+
 function rankFn(policy: Policy): (a: Quote, b: Quote) => number {
   switch (policy.kind) {
     case PolicyKind.Fastest:
@@ -81,6 +105,22 @@ function cmpNumber(a: number, b: number): number {
   return a < b ? -1 : a > b ? 1 : 0;
 }
 
+// compareUtf8 orders two strings by their UTF-8 byte encoding, so the tie-break
+// agrees with the Go SDK. A plain string comparison orders by UTF-16 code unit,
+// which disagrees for characters above U+FFFF and would break determinism across
+// languages on a non-ASCII adapter id.
+const utf8Encoder = new TextEncoder();
+function compareUtf8(a: string, b: string): number {
+  if (a === b) return 0;
+  const ab = utf8Encoder.encode(a);
+  const bb = utf8Encoder.encode(b);
+  const n = Math.min(ab.length, bb.length);
+  for (let i = 0; i < n; i++) {
+    if (ab[i] !== bb[i]) return ab[i]! < bb[i]! ? -1 : 1;
+  }
+  return ab.length < bb.length ? -1 : ab.length > bb.length ? 1 : 0;
+}
+
 // cmpMoney orders two quotes by source amount. Amounts in different currencies
 // are treated as incomparable and reported equal, deferring to the tie-break so
 // the router never throws on a mixed-currency quote set.

package/src/state.ts

@@ -52,7 +52,9 @@ const transitions: Record<State, ReadonlySet<State>> = {
   [State.Held]: new Set([State.Disbursing, State.Refunding, State.Expired]),
   [State.Disbursing]: new Set([State.Settled, State.Failed, State.Refunding]),
   [State.Refunding]: new Set([State.Refunded, State.Failed]),
-  [State.Settled]: new Set([State.Refunded]),
+  // A settled intent refunds through the same refunding step a bridged unwind uses,
+  // so the refund is claimed before any money moves and cannot fire twice.
+  [State.Settled]: new Set([State.Refunding, State.Refunded]),
   [State.Failed]: new Set(),
   [State.Expired]: new Set(),
   [State.Refunded]: new Set(),

package/src/wire.ts

@@ -1,5 +1,5 @@
 import { Money } from "./money.js";
-import { State } from "./state.js";
+import { State, stateName } from "./state.js";
 import { CanonicalWriter } from "./canonical.js";
 import type { Intent, Quote, Authorization, Settlement } from "./message.js";
 
@@ -146,7 +146,14 @@ class WireReader {
     }
     const view = new DataView(this.buf.buffer, this.buf.byteOffset + this.pos, 8);
     this.pos += 8;
-    return Number(view.getBigUint64(0, false));
+    const value = view.getBigUint64(0, false);
+    // A value above 2^53 cannot be held exactly in a JS number, so reject it
+    // rather than decode a Go or Dart value into a silently different one. Every
+    // real field here — millisecond timestamps, ordinals, latency — fits easily.
+    if (value > BigInt(Number.MAX_SAFE_INTEGER)) {
+      throw new Error("pact: u64 field exceeds the exact-integer range");
+    }
+    return Number(value);
   }
 
   money(): Money {
@@ -231,11 +238,21 @@ export function decodeAuthorization(b: Uint8Array): Authorization {
   return auth;
 }
 
+// stateFromOrdinal rejects an ordinal outside the known states rather than pass
+// an out-of-range number through as a State, so a corrupt wire byte cannot decode
+// to a nonexistent state.
+function stateFromOrdinal(n: number): State {
+  if (!(n in stateName)) {
+    throw new Error(`pact: unknown settlement state ordinal ${n}`);
+  }
+  return n as State;
+}
+
 export function decodeSettlement(b: Uint8Array): Settlement {
   const r = new WireReader(b);
   const settlement: Settlement = {
     intentId: r.str(),
-    state: r.u64() as State,
+    state: stateFromOrdinal(r.u64()),
     adapterId: r.str(),
     providerTxRef: r.str(),
     onchainTxHash: r.str(),

package/src/fake.ts

@@ -1,96 +0,0 @@
-import { State } from "./state.js";
-import { RefundKind } from "./adapter.js";
-import type { Money } from "./money.js";
-import type { Quote, Authorization, Settlement } from "./message.js";
-import type { RateSource, EscrowVault } from "./bridge.js";
-import type {
-  PayInLeg,
-  PayOutLeg,
-  PayInCapabilities,
-  PayOutCapabilities,
-  CollectResult,
-  DisburseResult,
-} from "./leg.js";
-
-// FakeLeg is a deterministic, in-memory pay-in and pay-out leg. It settles
-// instantly with no network and implements both sides so a test can build a
-// direct corridor from one leg or a bridged corridor from two. failPayout makes
-// its disburse fail so a test can exercise the escrow-unwind path.
-export class FakeLeg implements PayInLeg, PayOutLeg {
-  failPayout = false;
-
-  constructor(
-    readonly id: string,
-    private readonly rail: string,
-    private readonly currency: string,
-    private readonly ids: () => string,
-  ) {}
-
-  payInCapabilities(): PayInCapabilities {
-    return { rails: [this.rail], currencies: [this.currency], refunds: RefundKind.Full };
-  }
-
-  // collect takes the payer's funds. received is the net the bridge converts —
-  // the source the payer paid less the corridor fees.
-  async collect(_intentId: string, quote: Quote, _auth: Authorization, _deliverTo: string): Promise<CollectResult> {
-    return { providerRef: this.ids(), received: quote.srcAmount.sub(quote.fees) };
-  }
-
-  async refundIn(intentId: string, _kind: RefundKind, reason: string): Promise<Settlement> {
-    return this.terminal(intentId, reason);
-  }
-
-  payOutCapabilities(): PayOutCapabilities {
-    return { rails: [this.rail], currencies: [this.currency], reversible: false };
-  }
-
-  async disburse(_intentId: string, _quote: Quote, _recipientRef: string): Promise<DisburseResult> {
-    if (this.failPayout) {
-      throw new Error("fake: payout failed");
-    }
-    return { providerRef: this.ids() };
-  }
-
-  async reverseOut(intentId: string, reason: string): Promise<Settlement> {
-    return this.terminal(intentId, reason);
-  }
-
-  private terminal(intentId: string, reason: string): Settlement {
-    return {
-      intentId,
-      state: State.Refunded,
-      adapterId: this.id,
-      providerTxRef: this.ids(),
-      onchainTxHash: "",
-      receiptHash: new Uint8Array(0),
-      reason,
-      settledAt: 0,
-    };
-  }
-}
-
-// FakeRates is an in-memory rate source keyed by "FROM:TO", standing in for a
-// price feed so a bridge can be tested without a live market.
-export class FakeRates implements RateSource {
-  constructor(private readonly table: Record<string, string>) {}
-
-  async rate(from: string, to: string): Promise<string> {
-    const rate = this.table[`${from}:${to}`];
-    if (rate === undefined) {
-      throw new Error(`fake: no rate for ${from}:${to}`);
-    }
-    return rate;
-  }
-}
-
-// FakeVault is an in-memory escrow that records holds and releases, standing in
-// for the custody a real bridge relies on.
-export class FakeVault implements EscrowVault {
-  async hold(intentId: string, _amount: Money): Promise<string> {
-    return `escrow-${intentId}`;
-  }
-
-  async release(_intentId: string): Promise<void> {
-    // Nothing to release in memory.
-  }
-}