@myzonerocks/pact 0.1.2 → 0.1.4

package/src/canonical.ts

@@ -26,6 +26,11 @@ export class CanonicalWriter {
     return this;
   }
 
+  // str writes a string as its raw UTF-8 bytes. No Unicode normalization is
+  // applied: the bytes are hashed as given, so two participants that compose the
+  // same text in different Unicode forms produce different hashes. Callers that
+  // need them to agree must normalize before building a message; string fields are
+  // otherwise treated as opaque bytes.
   str(s: string): this {
     return this.bytes(encoder.encode(s));
   }

package/src/client.ts

@@ -18,9 +18,17 @@ import {
 import { authorize as signAuthorization, verifyAuthorization, type Signer, type Verifier } from "./signing.js";
 import { PassThroughBridge, type Bridge, type ConvertResult } from "./bridge.js";
 import { railInList, isInteractivePayInLeg, type PayInLeg, type PayOutLeg, type CollectResult, type PayInPreparation } 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 { RefundKind, type AdapterEvent } from "./adapter.js";
+import { route, type Policy, PolicyKind, NoQuoteError, isExpired, maxFundingOptions } from "./router.js";
+import {
+  permissiveKyc,
+  allowRisk,
+  withinLimits,
+  strictSignerAuthorizer,
+  type KycProvider,
+  type RiskHook,
+  type SignerAuthorizer,
+} 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
@@ -50,6 +58,7 @@ export interface ClientConfig {
   verifier: Verifier;
   kyc?: KycProvider;
   risk?: RiskHook;
+  signerAuth?: SignerAuthorizer;
   clock?: Clock;
   idGen?: IdGen;
   skew?: number;
@@ -87,6 +96,7 @@ export class Client {
   private readonly verifier: Verifier;
   private readonly kyc: KycProvider;
   private readonly risk: RiskHook;
+  private readonly signerAuth: SignerAuthorizer;
   private readonly clock: Clock;
   private readonly idGen: IdGen;
   private readonly skew: number;
@@ -105,6 +115,7 @@ export class Client {
     this.verifier = cfg.verifier;
     this.kyc = cfg.kyc ?? permissiveKyc;
     this.risk = cfg.risk ?? allowRisk;
+    this.signerAuth = cfg.signerAuth ?? strictSignerAuthorizer;
     this.clock = cfg.clock ?? systemClock;
     this.idGen = cfg.idGen ?? randomId;
     this.skew = cfg.skew ?? DEFAULT_SKEW_MILLIS;
@@ -113,6 +124,11 @@ export class Client {
 
   // createIntent mints an intent and records it as a draft.
   createIntent(spec: IntentSpec): Intent {
+    // A zero deadline means "never expires", which would let an intent advance
+    // forever and bypass the liveness bound. Require a real deadline at creation.
+    if (!spec.expiresAt) {
+      throw new Error("pact: intent requires a non-zero expiry deadline");
+    }
     const intent: Intent = {
       id: this.idGen(),
       senderRef: spec.senderRef,
@@ -132,6 +148,9 @@ export class Client {
   // 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[]> {
+    if (funding.length > maxFundingOptions) {
+      throw new Error(`pact: ${funding.length} funding options exceed the maximum of ${maxFundingOptions}`);
+    }
     const quotes: Quote[] = [];
     let lastErr: unknown;
     for (const f of funding) {
@@ -242,11 +261,17 @@ export class Client {
     if (isExpired(quote.expiresAt, now, this.skew)) {
       throw new Error("pact: quote has expired");
     }
-    const status = await this.kyc.status(signer.identity());
+    // The signer must be allowed to act for the sender, and compliance is measured
+    // against the sender — the party actually funding the payment — not whoever
+    // holds the signing key.
+    if (!this.signerAuth.authorized(signer.identity(), intent.senderRef)) {
+      throw new Error("pact: signer is not authorized to act for the intent's sender");
+    }
+    const status = await this.kyc.status(intent.senderRef);
     if (!withinLimits(status, quote)) {
       throw new Error("pact: quote exceeds KYC limit");
     }
-    const decision = this.risk.evaluate(signer.identity(), intent, quote);
+    const decision = this.risk.evaluate(intent.senderRef, intent, quote);
     if (!decision.allow) {
       throw new Error(`pact: risk hook vetoed authorization: ${decision.reason}`);
     }
@@ -266,11 +291,25 @@ export class Client {
   // ledger.
   async initiate(intent: Intent, quote: Quote, auth: Authorization): Promise<State> {
     verifyAuthorization(auth, intent, quote, this.verifier);
+    if (!this.signerAuth.authorized(auth.signerIdentity, intent.senderRef)) {
+      throw new Error("pact: signer is not authorized to act for the intent's sender");
+    }
+    if (isExpired(intent.expiresAt, this.clock(), this.skew)) {
+      throw new Error("pact: intent has expired");
+    }
     const payInLeg = this.payIn.get(quote.payInAdapterId);
     if (!payInLeg) {
       throw new Error(`pact: no pay-in leg ${JSON.stringify(quote.payInAdapterId)}`);
     }
 
+    // A retry of an already-submitted corridor must not collect a second time. The
+    // pay-in leg carries its own provider idempotency for the narrow window where a
+    // collection completed but its record was lost.
+    const submitted = this.ledger.state(intent.id);
+    if (submitted === State.Submitted || submitted === State.Collecting) {
+      return submitted;
+    }
+
     // A direct corridor collects straight to the recipient; a bridged one
     // collects into escrow first.
     let deliverTo = recipientDestination(intent);
@@ -293,9 +332,15 @@ export class Client {
   // server-side into escrow, and the leg must offer interactive collection.
   async interactiveInitiate(intent: Intent, quote: Quote, auth: Authorization): Promise<{ preparation: PayInPreparation; state: State }> {
     verifyAuthorization(auth, intent, quote, this.verifier);
+    if (!this.signerAuth.authorized(auth.signerIdentity, intent.senderRef)) {
+      throw new Error("pact: signer is not authorized to act for the intent's sender");
+    }
     if (!isDirect(quote)) {
       throw new Error("pact: interactive pay-in is only available on a direct corridor");
     }
+    if (isExpired(intent.expiresAt, this.clock(), this.skew)) {
+      throw new Error("pact: intent has expired");
+    }
     const payInLeg = this.payIn.get(quote.payInAdapterId);
     if (!payInLeg) {
       throw new Error(`pact: no pay-in leg ${JSON.stringify(quote.payInAdapterId)}`);
@@ -333,14 +378,14 @@ export class Client {
     // 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 collected = collectResult(events);
       const settlement: Settlement = {
         intentId,
         state: State.Settled,
         adapterId: quote.payInAdapterId,
-        providerTxRef: ref,
+        providerTxRef: collected.providerRef,
         onchainTxHash: "",
-        receiptHash: corridorReceipt(authHash, ref, ref, quote.fxRate, "", State.Settled),
+        receiptHash: corridorReceipt(authHash, collected.providerRef, collected.providerRef, collected.received, "", State.Settled),
         reason: "",
         settledAt: this.clock(),
       };
@@ -384,11 +429,32 @@ export class Client {
       throw new Error(`pact: no bridge ${JSON.stringify(quote.bridgeId)}`);
     }
     const collected = collectResult(events);
-    this.ledger.apply({
+    // Claim the escrow hold before converting or disbursing. If a concurrent
+    // advance already claimed it, this call did not win, so abort rather than run
+    // the conversion and pay-out a second time.
+    const { created } = this.ledger.apply({
       intentId: intent.id,
       to: State.Held,
       payloadHash: hashString(domain("held"), collected.providerRef),
     });
+    if (!created) {
+      return { settlement: lastSettlement(events), state: this.ledger.state(intent.id) };
+    }
+    // An expired corridor must not convert at a stale rate; unwind the collection
+    // to a refund instead of driving it forward past its deadline.
+    if (isExpired(intent.expiresAt, this.clock(), this.skew)) {
+      return this.unwind(intent.id, quote, authHash, "intent expired before conversion");
+    }
+
+    // The pay-in must have collected at least the source net of fees; a short
+    // collection unwinds rather than disbursing the full quote against it.
+    try {
+      if (collected.received.cmp(quote.srcAmount.sub(quote.fees)) < 0) {
+        return this.unwind(intent.id, quote, authHash, "bridged corridor collected less than the quoted source amount");
+      }
+    } catch {
+      return this.unwind(intent.id, quote, authHash, "bridged corridor collected in an unexpected currency");
+    }
 
     let converted: ConvertResult;
     try {
@@ -396,6 +462,16 @@ export class Client {
     } catch (err) {
       return this.unwind(intent.id, quote, authHash, reasonOf(err));
     }
+    // Value must be conserved across the escrow: the conversion has to deliver at
+    // least the quoted destination amount before the pay-out is sent. A moved rate
+    // or a short conversion unwinds to a refund rather than draining escrow.
+    try {
+      if (converted.delivered.cmp(quote.dstAmount) < 0) {
+        return this.unwind(intent.id, quote, authHash, "bridged conversion delivered less than the quoted destination amount");
+      }
+    } catch {
+      return this.unwind(intent.id, quote, authHash, "bridged conversion delivered in an unexpected currency");
+    }
     let disbursed;
     try {
       disbursed = await payOutLeg.disburse(intent.id, quote, recipientDestination(intent));
@@ -431,14 +507,14 @@ export class Client {
     events: LedgerEvent[],
   ): { settlement: Settlement; state: State } {
     const inRef = payInRef(events);
-    const { payOut: outRef, bridge: bridgeRef } = disburseRefs(events);
+    const { payOut: outRef, bridge: bridgeRef, delivered } = 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),
+      receiptHash: corridorReceipt(authHash, inRef, outRef, delivered, bridgeRef, State.Settled),
       reason: "",
       settledAt: this.clock(),
     };
@@ -460,15 +536,79 @@ export class Client {
     });
     const payInLeg = this.payIn.get(quote.payInAdapterId);
     if (payInLeg) {
-      await payInLeg.refundIn(intentId, payInLeg.payInCapabilities().refunds, reason);
+      const kind = payInLeg.payInCapabilities().refunds;
+      // A pay-in rail that cannot refund in place leaves the corridor refunding
+      // for the operator to complete out of band, rather than recording a refund
+      // that never moved funds.
+      if (kind === RefundKind.None) {
+        throw new Error(`pact: pay-in leg ${JSON.stringify(quote.payInAdapterId)} cannot refund automatically; manual return required: ${reason}`);
+      }
+      await payInLeg.refundIn(intentId, kind, quote.srcAmount, reason);
+    }
+    // The escrow unwind returns the whole collection, so the receipt attests the
+    // source amount the payer funded as the amount refunded.
+    const settlement: Settlement = {
+      intentId,
+      state: State.Refunded,
+      adapterId: quote.payInAdapterId,
+      providerTxRef: "",
+      onchainTxHash: "",
+      receiptHash: corridorReceipt(authHash, "", "", quote.srcAmount, "", State.Refunded),
+      reason,
+      settledAt: this.clock(),
+    };
+    return this.finishAdvance(intentId, State.Refunded, settlement);
+  }
+
+  // refund returns funds to the payer for a settled intent. The amount is
+  // explicit, so a host can issue a partial refund, and it must be in the source
+  // currency and no greater than what the payer funded. The pay-in leg must
+  // advertise a refund it can honour — and a partial one for a partial amount.
+  // Like every advance it is keyed on the target state, so a second refund for the
+  // same intent is a no-op.
+  async refund(intentId: string, amount: Money, reason: string): 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 refund");
+    }
+    const { intent, quote, authorization: auth } = replayed;
+    const current = this.ledger.state(intentId);
+    // A refund is single-occurrence: once refunded, a repeat is an idempotent
+    // no-op that echoes the outcome rather than moving funds again.
+    if (current === State.Refunded) {
+      return { settlement: lastSettlement(events), state: current };
+    }
+    if (current !== State.Settled) {
+      throw new Error("pact: only a settled intent can be refunded");
+    }
+    if (amount.currency !== quote.srcAmount.currency || amount.exponent !== quote.srcAmount.exponent) {
+      throw new Error("pact: refund must be in the funded source currency");
     }
+    if (amount.value() <= 0n) {
+      throw new Error("pact: refund amount must be positive");
+    }
+    const over = amount.cmp(quote.srcAmount);
+    if (over > 0) {
+      throw new Error("pact: refund exceeds the amount funded");
+    }
+    const payInLeg = this.payIn.get(quote.payInAdapterId);
+    if (!payInLeg) {
+      throw new Error(`pact: no pay-in leg ${JSON.stringify(quote.payInAdapterId)}`);
+    }
+    const kind = refundKindFor(payInLeg.payInCapabilities().refunds, over === 0);
+    if (kind === undefined) {
+      throw new Error(`pact: pay-in leg ${JSON.stringify(quote.payInAdapterId)} cannot perform this refund`);
+    }
+    const authHash = authorizationHash(intentHash(intent), quoteHash(quote), auth.signerIdentity, auth.signedAt);
+    await payInLeg.refundIn(intentId, kind, amount, reason);
     const settlement: Settlement = {
       intentId,
       state: State.Refunded,
       adapterId: quote.payInAdapterId,
       providerTxRef: "",
       onchainTxHash: "",
-      receiptHash: corridorReceipt(authHash, "", "", quote.fxRate, "", State.Refunded),
+      receiptHash: corridorReceipt(authHash, "", "", amount, "", State.Refunded),
       reason,
       settledAt: this.clock(),
     };
@@ -488,7 +628,9 @@ export class Client {
       adapterId: quote.payInAdapterId,
       providerTxRef: "",
       onchainTxHash: "",
-      receiptHash: corridorReceipt(authHash, "", "", quote.fxRate, "", State.Failed),
+      // A pay-in that failed before escrow moved no value, so the receipt binds a
+      // zero amount alongside the failure.
+      receiptHash: corridorReceipt(authHash, "", "", Money.zero(), "", State.Failed),
       reason,
       settledAt: this.clock(),
     };
@@ -501,13 +643,22 @@ export class Client {
   }
 
   private finish(intentId: string, state: State, settlement: Settlement): Settlement {
-    const event = this.ledger.apply({ intentId, to: state, payloadHash: settlement.receiptHash, 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 records that an intent's deadline passed before it settled. It refuses
+  // to expire an intent whose deadline has not actually passed, so a caller cannot
+  // force a live payment to a terminal expired state.
   expire(intentId: string): void {
+    const recorded = this.ledger.events(intentId).find((e) => e.intent)?.intent;
+    if (!recorded) {
+      throw new Error("pact: intent has no recorded history to expire");
+    }
+    if (!isExpired(recorded.expiresAt, this.clock(), this.skew)) {
+      throw new Error("pact: intent has not reached its deadline");
+    }
     this.ledger.apply({
       intentId,
       to: State.Expired,
@@ -565,25 +716,46 @@ function collectResult(events: LedgerEvent[]): CollectResult {
   for (const e of events) {
     if (e.collect) return e.collect;
   }
-  return { providerRef: "", received: Money.create("", 0, 0n) };
+  return { providerRef: "", received: Money.zero() };
 }
 
 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 } {
+// disburseRefs returns the pay-out provider reference, the bridge receipt
+// reference, and the amount the bridge actually delivered, all recorded on the
+// disbursing step.
+function disburseRefs(events: LedgerEvent[]): { payOut: string; bridge: string; delivered: Money } {
   let payOut = "";
   let bridge = "";
+  let delivered = Money.zero();
   for (const e of events) {
     if (e.state === State.Disbursing) {
       if (e.settlement) payOut = e.settlement.providerTxRef;
-      if (e.bridge) bridge = e.bridge.receiptRef;
+      if (e.bridge) {
+        bridge = e.bridge.receiptRef;
+        delivered = e.bridge.delivered;
+      }
     }
   }
-  return { payOut, bridge };
+  return { payOut, bridge, delivered };
+}
+
+// refundKindFor maps a pay-in leg's advertised refund capability and whether the
+// refund is for the full funded amount to the kind the leg is handed, returning
+// undefined for a refund the rail cannot express.
+function refundKindFor(capability: RefundKind, full: boolean): RefundKind | undefined {
+  switch (capability) {
+    case RefundKind.CounterTransfer:
+      return RefundKind.CounterTransfer;
+    case RefundKind.Partial:
+      return full ? RefundKind.Full : RefundKind.Partial;
+    case RefundKind.Full:
+      return full ? RefundKind.Full : undefined;
+    default:
+      return undefined;
+  }
 }
 
 // lastSettlement returns the settlement recorded on an intent's most recent

package/src/compliance.ts

@@ -32,18 +32,35 @@ export const permissiveKyc: KycProvider = {
 };
 
 // withinLimits reports whether a quote's source amount is inside an identity's
-// per-payment cap. An absent cap or a currency mismatch is treated as no
-// applicable limit.
+// per-payment cap. An absent cap means no limit. A cap that cannot be compared to
+// the quote — because it is in a different currency — fails closed: the payment is
+// refused rather than slipped past by funding in a currency the cap can't measure.
 export function withinLimits(status: KycStatus, quote: Quote): boolean {
   const cap = status.limits.perPayment;
   if (!cap) return true;
   try {
     return quote.srcAmount.cmp(cap) <= 0;
   } catch {
-    return true;
+    return false;
   }
 }
 
+// SignerAuthorizer decides whether the identity that signed an authorization is
+// allowed to act for the intent's sender. The default requires them to be the
+// same party. A custodial host that signs for its users on one platform key
+// supplies its own, so it can attest that its signer speaks for a given sender —
+// and so compliance is measured against the party actually being charged.
+export interface SignerAuthorizer {
+  authorized(signerIdentity: string, senderRef: string): boolean;
+}
+
+// strictSignerAuthorizer is the default: the signer must be the sender.
+export const strictSignerAuthorizer: SignerAuthorizer = {
+  authorized(signerIdentity: string, senderRef: string): boolean {
+    return signerIdentity === senderRef;
+  },
+};
+
 // RiskDecision is the outcome of a RiskHook consultation.
 export interface RiskDecision {
   allow: boolean;

package/src/crypto.ts

@@ -42,7 +42,10 @@ export function ed25519Sign(privateKey: KeyObject, message: Uint8Array): Uint8Ar
 }
 
 export function ed25519Verify(publicKeyRaw: Uint8Array, message: Uint8Array, signature: Uint8Array): boolean {
-  if (publicKeyRaw.length !== 32) {
+  // A key or signature of the wrong length can never verify; reject it up front.
+  // The underlying verifier already rejects a non-canonical S, so a malleated
+  // signature never verifies.
+  if (publicKeyRaw.length !== 32 || signature.length !== 64) {
     return false;
   }
   const spki = Buffer.concat([spkiPublicPrefix, Buffer.from(publicKeyRaw)]);

package/src/index.ts

@@ -84,7 +84,6 @@ export {
   randomId,
   recipientDestination,
 } from "./client.js";
-export { FakeLeg, FakeRates, FakeVault } from "./fake.js";
 export {
   WireKind,
   type WireMessage,

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;