@myzonerocks/pact 0.1.4 → 0.1.7

package/src/client.ts

@@ -1,5 +1,5 @@
 import { randomBytes } from "node:crypto";
-import { State } from "./state.js";
+import { State, stateName } from "./state.js";
 import { Money } from "./money.js";
 import { DEFAULT_SKEW_MILLIS, domain } from "./protocol.js";
 import { CanonicalWriter, hashPreimage } from "./canonical.js";
@@ -164,6 +164,9 @@ export class Client {
         continue;
       }
       try {
+        // Corridors are priced in order so the router sees a stable ranking, matching
+        // the other SDKs; the loop is bounded by the configured funding options.
+        // eslint-disable-next-line no-await-in-loop
         quotes.push(await this.composeQuote(intent, payInLeg, f));
       } catch (err) {
         lastErr = err;
@@ -289,11 +292,9 @@ export class Client {
   // 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);
-    if (!this.signerAuth.authorized(auth.signerIdentity, intent.senderRef)) {
-      throw new Error("pact: signer is not authorized to act for the intent's sender");
-    }
+  // resolvePayIn rejects an expired intent and returns the corridor's pay-in leg — the
+  // expiry-and-leg check the immediate and interactive starts share.
+  private resolvePayIn(intent: Intent, quote: Quote): PayInLeg {
     if (isExpired(intent.expiresAt, this.clock(), this.skew)) {
       throw new Error("pact: intent has expired");
     }
@@ -301,13 +302,28 @@ export class Client {
     if (!payInLeg) {
       throw new Error(`pact: no pay-in leg ${JSON.stringify(quote.payInAdapterId)}`);
     }
+    return payInLeg;
+  }
+
+  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");
+    }
+    const payInLeg = this.resolvePayIn(intent, quote);
 
     // 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;
+    const current = this.ledger.state(intent.id);
+    if (current === State.Submitted || current === State.Collecting) {
+      return current;
+    }
+    // Collection may only start from an authorized intent. Without this a replayed
+    // or out-of-order call would charge the payer through collect before the ledger
+    // rejected the transition, so the guard is enforced before any money moves.
+    if (current !== State.Authorized) {
+      throw new Error(`pact: cannot initiate an intent in state ${stateName[current]}; it must be authorized first`);
     }
 
     // A direct corridor collects straight to the recipient; a bridged one
@@ -338,16 +354,16 @@ export class Client {
     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)}`);
-    }
+    const payInLeg = this.resolvePayIn(intent, quote);
     if (!isInteractivePayInLeg(payInLeg)) {
       throw new Error(`pact: pay-in leg ${JSON.stringify(quote.payInAdapterId)} does not offer interactive collection`);
     }
+    // The provider intent may only be prepared from an authorized intent, so a
+    // replayed or out-of-order call cannot open a second collection.
+    const current = this.ledger.state(intent.id);
+    if (current !== State.Authorized) {
+      throw new Error(`pact: cannot initiate an intent in state ${stateName[current]}; it must be authorized first`);
+    }
     const preparation = await payInLeg.prepare(intent.id, quote, auth, recipientDestination(intent));
     // Record the same shape a direct collection would, so the confirming webhook
     // advances the corridor to settled through the unchanged pay-in path.
@@ -406,6 +422,31 @@ export class Client {
       return this.settleBridged(intentId, quote, authHash, events);
     }
 
+    // A refund reported out of band — an operator refunds in the provider's
+    // dashboard, say — is recorded against the settled intent so the ledger matches
+    // where the money actually is. The provider has already returned the funds, so
+    // this only claims the refunding step (once, so a duplicate webhook is a no-op)
+    // and records the refunded outcome; it moves no money itself.
+    if (event.state === State.Refunded && current === State.Settled) {
+      const { created } = this.ledger.apply({
+        intentId,
+        to: State.Refunding,
+        payloadHash: hashString(domain("refunding"), event.reason),
+      });
+      if (!created) return { settlement: lastSettlement(events), state: this.ledger.state(intentId) };
+      const settlement: Settlement = {
+        intentId,
+        state: State.Refunded,
+        adapterId,
+        providerTxRef: event.providerTxRef,
+        onchainTxHash: "",
+        receiptHash: corridorReceipt(authHash, "", event.providerTxRef, quote.srcAmount, "", State.Refunded),
+        reason: event.reason,
+        settledAt: this.clock(),
+      };
+      return this.finishAdvance(intentId, State.Refunded, settlement);
+    }
+
     // 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 };
@@ -521,6 +562,20 @@ export class Client {
     return this.finishAdvance(intentId, State.Settled, settlement);
   }
 
+  // claimRefund reserves the refunding step before any money moves. It returns the
+  // recorded outcome to echo when another refund already claimed the step, or null when
+  // this call won it and should proceed to move funds. Both refund paths go through it,
+  // so a refund is issued at most once however the calls race.
+  private claimRefund(intentId: string, reason: string): { settlement: Settlement; state: State } | null {
+    const { created } = this.ledger.apply({
+      intentId,
+      to: State.Refunding,
+      payloadHash: hashString(domain("refunding"), reason),
+    });
+    if (created) return null;
+    return { settlement: lastSettlement(this.ledger.events(intentId)), state: this.ledger.state(intentId) };
+  }
+
   // unwind refunds the payer from escrow when a bridged corridor cannot complete
   // its pay-out, moving to refunding then refunded.
   private async unwind(
@@ -529,11 +584,11 @@ export class Client {
     authHash: Uint8Array,
     reason: string,
   ): Promise<{ settlement: Settlement; state: State }> {
-    this.ledger.apply({
-      intentId,
-      to: State.Refunding,
-      payloadHash: hashString(domain("refunding"), reason),
-    });
+    // Claim the refund before moving money. A duplicate pay-out-failed webhook enters
+    // unwind twice; only the call that wins the refunding step may issue the counter-
+    // transfer, so the refund cannot fire a second time.
+    const echo = this.claimRefund(intentId, reason);
+    if (echo) return echo;
     const payInLeg = this.payIn.get(quote.payInAdapterId);
     if (payInLeg) {
       const kind = payInLeg.payInCapabilities().refunds;
@@ -601,6 +656,11 @@ export class Client {
       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);
+    // Claim the refunding step before moving money. Two overlapping refund calls both
+    // pass the settled check above; only the one that wins this step issues the return,
+    // so the payer is never refunded twice.
+    const echo = this.claimRefund(intentId, reason);
+    if (echo) return echo;
     await payInLeg.refundIn(intentId, kind, amount, reason);
     const settlement: Settlement = {
       intentId,

package/src/message.ts

@@ -60,9 +60,11 @@ export interface Quote {
   latencyEstimateMs: number;
 }
 
-export function quotePreimage(q: Quote): Uint8Array {
-  return new CanonicalWriter()
-    .str(domain("quote"))
+// writeQuoteFields appends a quote's fields to a writer in the one canonical order
+// shared by the signing preimage and the wire codec. The two callers differ only in
+// what frames the fields: the preimage prepends a domain tag, the wire form does not.
+export function writeQuoteFields(w: CanonicalWriter, q: Quote): CanonicalWriter {
+  return w
     .str(q.id)
     .str(q.intentId)
     .str(q.payInAdapterId)
@@ -76,8 +78,12 @@ export function quotePreimage(q: Quote): Uint8Array {
     .str(q.fxRate)
     .u64(q.expiresAt)
     .str(q.providerQuoteRef)
-    .u64(q.latencyEstimateMs)
-    .preimage();
+    .u64(q.latencyEstimateMs);
+}
+
+export function quotePreimage(q: Quote): Uint8Array {
+  const w = new CanonicalWriter().str(domain("quote"));
+  return writeQuoteFields(w, q).preimage();
 }
 
 export function quoteHash(q: Quote): Uint8Array {

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,6 +1,7 @@
 import { Money } from "./money.js";
 import { State, stateName } from "./state.js";
 import { CanonicalWriter } from "./canonical.js";
+import { writeQuoteFields } from "./message.js";
 import type { Intent, Quote, Authorization, Settlement } from "./message.js";
 
 // The wire codec serializes messages for transport. It is distinct from the
@@ -32,22 +33,7 @@ export function encodeIntent(i: Intent): Uint8Array {
 }
 
 export function encodeQuote(q: Quote): Uint8Array {
-  return new CanonicalWriter()
-    .str(q.id)
-    .str(q.intentId)
-    .str(q.payInAdapterId)
-    .str(q.payInRail)
-    .str(q.payOutAdapterId)
-    .str(q.payOutRail)
-    .str(q.bridgeId)
-    .money(q.srcAmount)
-    .money(q.dstAmount)
-    .money(q.fees)
-    .str(q.fxRate)
-    .u64(q.expiresAt)
-    .str(q.providerQuoteRef)
-    .u64(q.latencyEstimateMs)
-    .preimage();
+  return writeQuoteFields(new CanonicalWriter(), q).preimage();
 }
 
 export function encodeAuthorization(a: Authorization): Uint8Array {