@myzonerocks/pact 0.1.2 → 0.1.4

package/dist/src/client.js

@@ -7,8 +7,9 @@ import { intentHash, quoteHash, authorizationHash, corridorReceipt, isDirect, BR
 import { authorize as signAuthorization, verifyAuthorization } from "./signing.js";
 import { PassThroughBridge } from "./bridge.js";
 import { railInList, isInteractivePayInLeg } from "./leg.js";
-import { route, PolicyKind, NoQuoteError, isExpired } from "./router.js";
-import { permissiveKyc, allowRisk, withinLimits } from "./compliance.js";
+import { RefundKind } from "./adapter.js";
+import { route, PolicyKind, NoQuoteError, isExpired, maxFundingOptions } from "./router.js";
+import { permissiveKyc, allowRisk, withinLimits, strictSignerAuthorizer, } from "./compliance.js";
 import { MemoryLedger, eventReceipt } from "./ledger.js";
 export function systemClock() {
     return Date.now();
@@ -29,6 +30,7 @@ export class Client {
     verifier;
     kyc;
     risk;
+    signerAuth;
     clock;
     idGen;
     skew;
@@ -49,6 +51,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;
@@ -56,6 +59,11 @@ export class Client {
     }
     // createIntent mints an intent and records it as a draft.
     createIntent(spec) {
+        // 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 = {
             id: this.idGen(),
             senderRef: spec.senderRef,
@@ -74,6 +82,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, funding) {
+        if (funding.length > maxFundingOptions) {
+            throw new Error(`pact: ${funding.length} funding options exceed the maximum of ${maxFundingOptions}`);
+        }
         const quotes = [];
         let lastErr;
         for (const f of funding) {
@@ -186,11 +197,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}`);
         }
@@ -208,10 +225,23 @@ export class Client {
     // ledger.
     async initiate(intent, quote, auth) {
         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);
@@ -233,9 +263,15 @@ export class Client {
     // server-side into escrow, and the leg must offer interactive collection.
     async interactiveInitiate(intent, quote, auth) {
         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)}`);
@@ -272,14 +308,14 @@ export class Client {
         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 = {
                 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(),
             };
@@ -316,11 +352,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;
         try {
             converted = await bridge.convert(intent.id, collected.received, intent.amount.currency, intent.amount.exponent);
@@ -328,6 +385,17 @@ 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));
@@ -358,14 +426,14 @@ export class Client {
     // binding both legs and the FX into the linked receipt.
     settleBridged(intentId, quote, authHash, events) {
         const inRef = payInRef(events);
-        const { payOut: outRef, bridge: bridgeRef } = disburseRefs(events);
+        const { payOut: outRef, bridge: bridgeRef, delivered } = disburseRefs(events);
         const 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(),
         };
@@ -381,15 +449,78 @@ 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 = {
             intentId,
             state: State.Refunded,
             adapterId: quote.payInAdapterId,
             providerTxRef: "",
             onchainTxHash: "",
-            receiptHash: corridorReceipt(authHash, "", "", quote.fxRate, "", State.Refunded),
+            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, amount, reason) {
+        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 = {
+            intentId,
+            state: State.Refunded,
+            adapterId: quote.payInAdapterId,
+            providerTxRef: "",
+            onchainTxHash: "",
+            receiptHash: corridorReceipt(authHash, "", "", amount, "", State.Refunded),
             reason,
             settledAt: this.clock(),
         };
@@ -403,7 +534,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(),
         };
@@ -414,12 +547,21 @@ export class Client {
         return { settlement: finished, state };
     }
     finish(intentId, state, 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) {
+        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,
@@ -475,25 +617,44 @@ function collectResult(events) {
         if (e.collect)
             return e.collect;
     }
-    return { providerRef: "", received: Money.create("", 0, 0n) };
+    return { providerRef: "", received: Money.zero() };
 }
 function payInRef(events) {
     return collectResult(events).providerRef;
 }
-// disburseRefs returns the pay-out provider reference and the bridge receipt
-// reference recorded on the disbursing step.
+// 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) {
     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)
+            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, full) {
+    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
 // event, if any, so an idempotent no-op can echo the outcome already reached.

package/dist/src/compliance.d.ts

@@ -13,6 +13,10 @@ export interface KycProvider {
 }
 export declare const permissiveKyc: KycProvider;
 export declare function withinLimits(status: KycStatus, quote: Quote): boolean;
+export interface SignerAuthorizer {
+    authorized(signerIdentity: string, senderRef: string): boolean;
+}
+export declare const strictSignerAuthorizer: SignerAuthorizer;
 export interface RiskDecision {
     allow: boolean;
     reason: string;

package/dist/src/compliance.js

@@ -6,8 +6,9 @@ export const permissiveKyc = {
     },
 };
 // 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, quote) {
     const cap = status.limits.perPayment;
     if (!cap)
@@ -16,9 +17,15 @@ export function withinLimits(status, quote) {
         return quote.srcAmount.cmp(cap) <= 0;
     }
     catch {
-        return true;
+        return false;
     }
 }
+// strictSignerAuthorizer is the default: the signer must be the sender.
+export const strictSignerAuthorizer = {
+    authorized(signerIdentity, senderRef) {
+        return signerIdentity === senderRef;
+    },
+};
 export const allowRisk = {
     evaluate() {
         return { allow: true, reason: "" };

package/dist/src/crypto.js

@@ -25,7 +25,10 @@ export function ed25519Sign(privateKey, message) {
     return new Uint8Array(nodeSign(null, Buffer.from(message), privateKey));
 }
 export function ed25519Verify(publicKeyRaw, message, signature) {
-    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/dist/src/index.d.ts

@@ -11,6 +11,5 @@ export { type KycProvider, type KycStatus, type KycLimits, type RiskHook, type R
 export { PolicyKind, type Policy, route, isExpired, NoQuoteError } from "./router.js";
 export { MemoryLedger, eventReceipt, chainLeaf, IdempotencyConflictError, type Ledger, type LedgerEvent, type Transition, } from "./ledger.js";
 export { Client, type ClientConfig, type IntentSpec, type Funding, type Clock, type IdGen, systemClock, randomId, recipientDestination, } from "./client.js";
-export { FakeLeg, FakeRates, FakeVault } from "./fake.js";
 export { WireKind, type WireMessage, encodeIntent, encodeQuote, encodeAuthorization, encodeSettlement, encodeMessage, decodeMessage, decodeIntent, decodeQuote, decodeAuthorization, decodeSettlement, } from "./wire.js";
 export { PAYLOAD_VERSION, encodePayload, decodePayload, isPayload, NotPayloadError, UnsupportedPayloadVersionError, } from "./payload.js";

package/dist/src/index.js

@@ -11,6 +11,5 @@ export { permissiveKyc, allowRisk, withinLimits, } from "./compliance.js";
 export { PolicyKind, route, isExpired, NoQuoteError } from "./router.js";
 export { MemoryLedger, eventReceipt, chainLeaf, IdempotencyConflictError, } from "./ledger.js";
 export { Client, systemClock, randomId, recipientDestination, } from "./client.js";
-export { FakeLeg, FakeRates, FakeVault } from "./fake.js";
 export { WireKind, encodeIntent, encodeQuote, encodeAuthorization, encodeSettlement, encodeMessage, decodeMessage, decodeIntent, decodeQuote, decodeAuthorization, decodeSettlement, } from "./wire.js";
 export { PAYLOAD_VERSION, encodePayload, decodePayload, isPayload, NotPayloadError, UnsupportedPayloadVersionError, } from "./payload.js";

package/dist/src/ledger.d.ts

@@ -30,15 +30,19 @@ export interface Transition {
 export declare class IdempotencyConflictError extends Error {
     constructor();
 }
+export interface ApplyResult {
+    event: LedgerEvent;
+    created: boolean;
+}
 export interface Ledger {
-    apply(t: Transition): LedgerEvent;
+    apply(t: Transition): ApplyResult;
     state(intentId: string): State;
     events(intentId: string): LedgerEvent[];
     head(intentId: string): Uint8Array | undefined;
 }
 export declare class MemoryLedger implements Ledger {
     private readonly byIntent;
-    apply(t: Transition): LedgerEvent;
+    apply(t: Transition): ApplyResult;
     state(intentId: string): State;
     events(intentId: string): LedgerEvent[];
     head(intentId: string): Uint8Array | undefined;

package/dist/src/ledger.js

@@ -19,7 +19,7 @@ export class MemoryLedger {
         for (const e of history) {
             if (e.state === t.to) {
                 if (bytesEqual(e.payloadHash, t.payloadHash))
-                    return e;
+                    return { event: e, created: false };
                 throw new IdempotencyConflictError();
             }
         }
@@ -46,7 +46,7 @@ export class MemoryLedger {
             ...(t.bridge ? { bridge: t.bridge } : {}),
         };
         this.byIntent.set(t.intentId, [...history, event]);
-        return event;
+        return { event, created: true };
     }
     state(intentId) {
         const history = this.byIntent.get(intentId);

package/dist/src/leg.d.ts

@@ -15,7 +15,7 @@ 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(intentId: string, kind: RefundKind, amount: Money, reason: string): Promise<Settlement>;
 }
 export interface PayInPreparation {
     providerRef: string;

package/dist/src/message.d.ts

@@ -52,4 +52,4 @@ export interface Settlement {
     settledAt: number;
 }
 export declare function receiptHash(authHash: Uint8Array, providerTxRef: string, state: State): Uint8Array;
-export declare function corridorReceipt(authHash: Uint8Array, payInProviderRef: string, payOutProviderRef: string, fxRate: string, bridgeReceiptRef: string, state: State): Uint8Array;
+export declare function corridorReceipt(authHash: Uint8Array, payInProviderRef: string, payOutProviderRef: string, amount: Money, bridgeReceiptRef: string, state: State): Uint8Array;

package/dist/src/message.js

@@ -72,16 +72,19 @@ export function receiptHash(authHash, providerTxRef, state) {
         .str(stateName[state])
         .preimage());
 }
-// 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.
-export function corridorReceipt(authHash, payInProviderRef, payOutProviderRef, fxRate, bridgeReceiptRef, state) {
+// 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, payInProviderRef, payOutProviderRef, amount, bridgeReceiptRef, state) {
     return hashPreimage(new CanonicalWriter()
         .str(domain("corridor"))
         .bytes(authHash)
         .str(payInProviderRef)
         .str(payOutProviderRef)
-        .str(fxRate)
+        .money(amount)
         .str(bridgeReceiptRef)
         .str(stateName[state])
         .preimage());

package/dist/src/money.d.ts

@@ -3,6 +3,7 @@ export declare class Money {
     readonly exponent: number;
     private readonly amount;
     private constructor();
+    static zero(): Money;
     static create(currency: string, exponent: number, amount: bigint): Money;
     static parse(currency: string, exponent: number, minor: string): Money;
     minor(): string;

package/dist/src/money.js

@@ -13,6 +13,13 @@ export class Money {
         this.exponent = exponent;
         this.amount = amount;
     }
+    // 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() {
+        return new Money("", 0, 0n);
+    }
     static create(currency, exponent, amount) {
         if (!currencyPattern.test(currency)) {
             throw new Error("pact: currency must match [A-Z0-9]{1,16}");
@@ -26,10 +33,18 @@ export class Money {
         return new Money(currency, exponent, amount);
     }
     // 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, exponent, minor) {
-        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/dist/src/protocol.d.ts

@@ -1,4 +1,5 @@
 export declare const ID = "pact";
 export declare const VERSION = "1";
 export declare function domain(kind: string): string;
+export declare function idempotencyKey(ref: string, step: string): string;
 export declare const DEFAULT_SKEW_MILLIS = 120000;

package/dist/src/protocol.js

@@ -10,6 +10,14 @@ const domainPrefix = `${ID}/${VERSION}/`;
 export function domain(kind) {
     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, step) {
+    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/dist/src/router.d.ts

@@ -13,4 +13,6 @@ export declare class NoQuoteError extends Error {
     constructor(reason: string);
 }
 export declare function isExpired(deadline: number, now: number, skew: number): boolean;
+export declare const maxQuotes = 256;
+export declare const maxFundingOptions = 64;
 export declare function route(quotes: Quote[], policy: Policy, kyc: KycStatus, now: number, skew: number): Quote;