@myzonerocks/pact 0.1.2 → 0.1.4

package/dist/test/paypal.test.js

@@ -33,6 +33,10 @@ class FakePaypal {
         const id = this.ids();
         return { orderId: `order_${id}`, captureId: `capture_${id}`, status: "COMPLETED" };
     }
+    async createOrder(params) {
+        this.lastOrder = params;
+        return { id: `order_${this.ids()}`, status: "CREATED", approveUrl: "https://paypal.test/approve" };
+    }
     async sendPayout(params) {
         this.lastPayout = params;
         return { batchId: `batch_${this.ids()}`, status: "PENDING" };
@@ -76,18 +80,38 @@ describe("paypal major amount", () => {
     });
 });
 describe("paypal webhook verification", () => {
-    it("maps an authentic capture to a settled event and rejects an unverifiable one", async () => {
+    it("settles a matching capture, refuses an under-payment, and rejects an unverifiable one", async () => {
         const api = new FakePaypal(counter("tx"));
         const leg = buildLeg(api);
-        const payload = new TextEncoder().encode(`{"event_type":"PAYMENT.CAPTURE.COMPLETED","resource":{"id":"capture_1","custom_id":"pact:intent-1"}}`);
-        const events = await leg.parseWebhook(payload, { "PayPal-Transmission-Id": ["t1"] });
+        // Register what the intent was quoted to collect so the capture can be checked.
+        const zero = Money.parse("USD", 2, "0");
+        await leg.collect("intent-1", {
+            id: "q",
+            intentId: "intent-1",
+            payInAdapterId: "paypal",
+            payInRail: "paypal",
+            payOutAdapterId: "paypal",
+            payOutRail: "paypal",
+            bridgeId: "passthrough",
+            srcAmount: Money.parse("USD", 2, "1500"),
+            dstAmount: Money.parse("USD", 2, "1500"),
+            fees: zero,
+            fxRate: "1",
+            expiresAt: 0,
+            providerQuoteRef: "",
+            latencyEstimateMs: 0,
+        }, { intentId: "intent-1", quoteId: "q", signerIdentity: "", signedAt: 0, signature: new Uint8Array(0) }, "merchant@example.com");
+        const capture = (value, currency) => new TextEncoder().encode(`{"event_type":"PAYMENT.CAPTURE.COMPLETED","resource":{"id":"capture_1","custom_id":"pact:intent-1","amount":{"currency_code":"${currency}","value":"${value}"}}}`);
+        const events = await leg.parseWebhook(capture("15.00", "USD"), { "PayPal-Transmission-Id": ["t1"] });
         expect(events).toHaveLength(1);
         expect(events[0].state).toBe(State.Settled);
         expect(events[0].intentId).toBe("intent-1");
         expect(events[0].providerTxRef).toBe("capture_1");
+        // A signed capture for a smaller amount, riding a stolen custom_id, must not settle.
+        await expect(leg.parseWebhook(capture("0.01", "USD"), { "PayPal-Transmission-Id": ["t2"] })).rejects.toThrow();
         // PayPal reports the signature does not verify, so the payload is rejected.
         api.verify = false;
-        await expect(leg.parseWebhook(payload, {})).rejects.toThrow(ErrSignatureMismatch);
+        await expect(leg.parseWebhook(capture("15.00", "USD"), {})).rejects.toThrow(ErrSignatureMismatch);
     });
 });
 describe("paypal direct corridor", () => {
@@ -120,11 +144,33 @@ describe("paypal direct corridor", () => {
         // The order was created to the recipient payee for the gross amount.
         expect(api.lastOrder.payee).toBe("merchant@example.com");
         expect(api.lastOrder.value).toBe("15.00");
-        // A full refund is accepted and binds to the capture id; a partial refund is a
-        // shape PayPal does not express here.
-        await leg.refundIn(intent.id, RefundKind.Full, "changed mind");
+        // PayPal supports a full and a partial refund. A full refund names no amount.
+        await leg.refundIn(intent.id, RefundKind.Full, Money.parse("USD", 2, "1500"), "changed mind");
         expect(api.lastRefund.captureId).toBe(settlement.providerTxRef);
-        await expect(leg.refundIn(intent.id, RefundKind.Partial, "half")).rejects.toThrow();
+        expect(api.lastRefund.value).toBeUndefined();
+        // A partial refund names the amount to return in major units.
+        await leg.refundIn(intent.id, RefundKind.Partial, Money.parse("USD", 2, "700"), "half");
+        expect(api.lastRefund.value).toBe("7.00");
+        expect(api.lastRefund.currencyCode).toBe("USD");
+        // A counter-transfer is a shape the card rail does not express.
+        await expect(leg.refundIn(intent.id, RefundKind.CounterTransfer, Money.parse("USD", 2, "1500"), "wrong kind")).rejects.toThrow();
+    });
+});
+describe("paypal interactive pay-in", () => {
+    it("prepares an order to the recipient payee with our cut as a platform fee", async () => {
+        const api = new FakePaypal(counter("tx"));
+        const leg = buildLeg(api);
+        const prep = await leg.prepare("intent-1", quote({ srcAmount: Money.parse("USD", 2, "1500"), fees: Money.parse("USD", 2, "45") }), { intentId: "intent-1", quoteId: "q", signerIdentity: "alice", signature: new Uint8Array(0), signedAt: 0 }, "merchant@example.com");
+        expect(prep.providerRef).not.toBe("");
+        expect(prep.clientSecret).toBe(prep.providerRef);
+        expect(prep.method).toBe("paypal");
+        expect(api.lastOrder.payee).toBe("merchant@example.com");
+        expect(api.lastOrder.value).toBe("15.00");
+        expect(api.lastOrder.platformFee).toBe("0.45");
+        expect(api.lastOrder.referenceId).toBe("pact:intent-1");
+        // A zero fee omits the platform fee rather than sending "0.00".
+        await leg.prepare("intent-2", quote({ srcAmount: Money.parse("USD", 2, "1500"), fees: Money.parse("USD", 2, "0") }), { intentId: "intent-2", quoteId: "q", signerIdentity: "alice", signature: new Uint8Array(0), signedAt: 0 }, "merchant@example.com");
+        expect(api.lastOrder.platformFee).toBeUndefined();
     });
 });
 describe("paypal pay-out", () => {

package/dist/test/policy.test.js

@@ -1,7 +1,7 @@
 import { describe, it, expect } from "vitest";
 import { Client } from "../src/client.js";
 import { Money } from "../src/money.js";
-import { FakeLeg } from "../src/fake.js";
+import { FakeLeg } from "./fake.js";
 import { Ed25519Signer, Ed25519Verifier } from "../src/signing.js";
 import { fromHex } from "../src/crypto.js";
 import { Erc20Leg } from "../src/adapters/erc20.js";
@@ -31,7 +31,10 @@ class OkChain {
         return "0xtx";
     }
     async receipt() {
-        return { status: "success", blockTimestampMs: 0 };
+        return { status: "success", blockNumber: 0, blockTimestampMs: 0, tokenAddress: "", to: "", amount: 0n };
+    }
+    async blockNumber() {
+        return 0;
     }
 }
 const now = 1_700_000_000_000;
@@ -74,6 +77,7 @@ describe("tiered kyc and window risk policy", () => {
             currency: "USD",
             chain: new OkChain(),
             ids: counter(),
+            decimals: 2,
         });
         const client = new Client({
             payIn: [leg],

package/dist/test/router.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test/router.test.js

@@ -0,0 +1,52 @@
+import { describe, it, expect } from "vitest";
+import { route, PolicyKind, NoQuoteError } from "../src/router.js";
+import { Money } from "../src/money.js";
+const now = 1_700_000_000_000;
+const future = now + 1_000_000;
+const noKyc = { tier: "unverified", jurisdiction: "", limits: {} };
+function quote(id, adapter, rail, src) {
+    return {
+        id,
+        intentId: "i",
+        payInAdapterId: adapter,
+        payInRail: rail,
+        payOutAdapterId: adapter,
+        payOutRail: rail,
+        bridgeId: "passthrough",
+        srcAmount: src,
+        dstAmount: src,
+        fees: Money.create(src.currency, src.exponent, 0n),
+        fxRate: "1",
+        expiresAt: future,
+        providerQuoteRef: "",
+        latencyEstimateMs: 0,
+    };
+}
+describe("router cross-currency cost", () => {
+    const usd = quote("q-usd", "card", "card", Money.create("USD", 2, 1500n));
+    const kes = quote("q-kes", "mpesa", "mpesa", Money.create("KES", 0, 200000n));
+    it("refuses to rank by cost across source currencies", () => {
+        // The router holds no rate to weigh 1500 USD against 200000 KES, so it
+        // refuses rather than letting the id tie-break crown a costlier quote.
+        expect(() => route([usd, kes], { kind: PolicyKind.Cheapest }, noKyc, now, 0)).toThrow(NoQuoteError);
+    });
+    it("ranks a single-currency set by cost", () => {
+        const chosen = route([usd], { kind: PolicyKind.Cheapest }, noKyc, now, 0);
+        expect(chosen.id).toBe("q-usd");
+    });
+    it("ranks across currencies under a currency-agnostic policy", () => {
+        const chosen = route([usd, kes], { kind: PolicyKind.Fastest }, noKyc, now, 0);
+        expect(chosen).toBeDefined();
+    });
+});
+describe("router tie-break byte ordering", () => {
+    // U+F900 and U+10000 order one way by code point (UTF-8) and the opposite way
+    // by UTF-16 code unit; the tie-break must order by UTF-8 to match the Go SDK.
+    it("orders adapter ids by their UTF-8 bytes", () => {
+        const lo = quote("q-lo", "豈", "card", Money.create("USD", 2, 1500n));
+        const hi = quote("q-hi", "\u{10000}", "card", Money.create("USD", 2, 1500n));
+        const chosen = route([hi, lo], { kind: PolicyKind.Cheapest }, noKyc, now, 0);
+        // U+F900 < U+10000 by code point, so its adapter wins under UTF-8 ordering.
+        expect(chosen.payInAdapterId).toBe("豈");
+    });
+});

package/dist/test/stripe.test.js

@@ -173,10 +173,11 @@ describe("stripe direct card corridor", () => {
         // The captured intent carries the pact intent id and reached a captured status.
         const pi = await api.findPaymentIntent(intent.id);
         expect(pi.status).toBe("succeeded");
-        // Stripe supports partial reversal, so a full refund is accepted and a
-        // counter-transfer is a shape the card rail does not express.
-        await leg.refundIn(intent.id, RefundKind.Full, "changed mind");
-        await expect(leg.refundIn(intent.id, RefundKind.CounterTransfer, "wrong kind")).rejects.toThrow();
+        // Stripe supports a full and a partial reversal; a counter-transfer is a shape
+        // the card rail does not express.
+        await leg.refundIn(intent.id, RefundKind.Full, Money.parse("USD", 2, "1500"), "changed mind");
+        await leg.refundIn(intent.id, RefundKind.Partial, Money.parse("USD", 2, "500"), "partial");
+        await expect(leg.refundIn(intent.id, RefundKind.CounterTransfer, Money.parse("USD", 2, "1500"), "wrong kind")).rejects.toThrow();
     });
     it("prepares a payer-confirmed intent and settles on the confirming webhook", async () => {
         const { signer, verifier } = signerVerifier("alice");

package/dist/test/vectors.test.js

@@ -3,8 +3,9 @@ import { readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { dirname, join } from "node:path";
 import { Money } from "../src/money.js";
-import { stateName } from "../src/state.js";
-import { intentPreimage, intentHash, quotePreimage, quoteHash, signingPreimage, authorizationHash, receiptHash, } from "../src/message.js";
+import { parseRate } from "../src/bridge.js";
+import { stateName, canTransition } from "../src/state.js";
+import { intentPreimage, intentHash, quotePreimage, quoteHash, signingPreimage, authorizationHash, receiptHash, corridorReceipt, } from "../src/message.js";
 import { eventReceipt, chainLeaf } from "../src/ledger.js";
 import { Ed25519Signer, Ed25519Verifier } from "../src/signing.js";
 import { toHex, fromHex } from "../src/crypto.js";
@@ -45,6 +46,41 @@ function quoteFrom(j) {
 }
 const nameToState = Object.fromEntries(Object.entries(stateName).map(([s, name]) => [name, Number(s)]));
 describe("shared conformance vectors", () => {
+    it("matches the shared state transition table exactly", () => {
+        const spec = vectors.transitions;
+        expect(Object.keys(spec).length).toBeGreaterThan(0);
+        const names = Object.keys(nameToState);
+        // Every listed edge must be legal and every pair the spec omits must be
+        // refused, so the lifecycle cannot silently gain or lose a transition.
+        for (const fromName of Object.keys(spec)) {
+            const allowed = new Set(spec[fromName]);
+            for (const toName of names) {
+                expect(canTransition(nameToState[fromName], nameToState[toName])).toBe(allowed.has(toName));
+            }
+        }
+    });
+    it("accepts and rejects the shared boundary amounts and rates", () => {
+        for (const c of vectors.boundaries.money) {
+            let ok = true;
+            try {
+                Money.parse(c.currency, c.exponent, c.minor);
+            }
+            catch {
+                ok = false;
+            }
+            expect(ok, `money ${c.note}`).toBe(c.valid);
+        }
+        for (const c of vectors.boundaries.rate) {
+            let ok = true;
+            try {
+                parseRate(c.rate);
+            }
+            catch {
+                ok = false;
+            }
+            expect(ok, `rate ${c.note}`).toBe(c.valid);
+        }
+    });
     it("reproduces every intent preimage and hash", () => {
         for (const entry of vectors.intents) {
             const intent = intentFrom(entry.intent);
@@ -71,12 +107,22 @@ describe("shared conformance vectors", () => {
         expect(toHex(signature)).toBe(a.signature_hex);
         const verifier = new Ed25519Verifier(new Map([[a.signer_identity, signer.publicKey]]));
         expect(verifier.verify(a.signer_identity, preimage, signature)).toBe(true);
+        // The same message signed with an S shifted by the group order is a valid
+        // Ed25519 forgery unless the verifier rejects a non-canonical S. An
+        // authorization signature is a unique commitment, so the twin must be refused.
+        expect(verifier.verify(a.signer_identity, preimage, fromHex(a.malleable_signature_hex))).toBe(false);
     });
     it("reproduces the settlement receipt hash", () => {
         const r = vectors.receipt;
         const hash = receiptHash(fromHex(r.auth_hash_hex), r.provider_tx_ref, nameToState[r.state]);
         expect(toHex(hash)).toBe(r.receipt_hash_hex);
     });
+    it("reproduces the corridor receipt binding the delivered amount", () => {
+        const c = vectors.corridor_receipt;
+        const amount = Money.parse(c.amount.currency, c.amount.exponent, c.amount.amount);
+        const hash = corridorReceipt(fromHex(c.auth_hash_hex), c.pay_in_provider_ref, c.pay_out_provider_ref, amount, c.bridge_receipt_ref, nameToState[c.state]);
+        expect(toHex(hash)).toBe(c.receipt_hash_hex);
+    });
     it("reproduces every ledger leaf and the Merkle head", () => {
         const l = vectors.ledger;
         let prevLeaf = new Uint8Array(32);

package/dist/test/wire.test.js

@@ -90,6 +90,21 @@ describe("wire codec conformance and round-trips", () => {
         expect(decoded.state).toBe(State.Settled);
         expect(toHex(decoded.receiptHash)).toBe(w.receipt_hash_hex);
     });
+    it("rejects a settlement carrying an unknown state ordinal", () => {
+        const forged = {
+            intentId: "intent-0001",
+            state: 200,
+            adapterId: "stripe",
+            providerTxRef: "",
+            onchainTxHash: "",
+            receiptHash: new Uint8Array(),
+            reason: "",
+            settledAt: 0,
+        };
+        // Encoding accepts the out-of-range ordinal; decoding must refuse it rather
+        // than pass a nonexistent state through.
+        expect(() => decodeSettlement(encodeSettlement(forged))).toThrow();
+    });
     it("dispatches a tagged frame back to its type", () => {
         const intent = intentFrom(vectors.intents[0].intent);
         const frame = encodeMessage({ kind: WireKind.Intent, message: intent });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@myzonerocks/pact",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "TypeScript SDK for the PACT payment abstraction protocol",
   "license": "Apache-2.0",
   "repository": {

package/src/adapter.ts

@@ -26,7 +26,12 @@ export interface AdapterEvent {
 // WebhookParser is implemented by legs that receive provider callbacks. It is
 // server-side only and turns a raw payload plus its request headers into
 // normalized events. The headers carry the provider's signature, so the parser
-// can reject a payload it cannot authenticate.
+// can reject a payload it cannot authenticate. A leg whose callback is unsigned
+// may need an out-of-band confirmation call to authenticate it, so the result may
+// be a promise; a signed-webhook leg returns synchronously.
 export interface WebhookParser {
-  parseWebhook(raw: Uint8Array, headers: Record<string, string[]>): AdapterEvent[];
+  parseWebhook(
+    raw: Uint8Array,
+    headers: Record<string, string[]>,
+  ): AdapterEvent[] | Promise<AdapterEvent[]>;
 }

package/src/adapters/erc20.ts

@@ -6,6 +6,7 @@
 // moves the payer's tokens to a destination, as a pay-out leg it delivers tokens
 // to the recipient.
 import { State } from "../state.js";
+import type { Money } from "../money.js";
 import type { Quote, Authorization, Settlement } from "../message.js";
 import { RefundKind, type AdapterEvent } from "../adapter.js";
 import type {
@@ -27,10 +28,17 @@ export interface Call {
   data: string;
 }
 
-// ChainReceipt is the outcome of a broadcast transaction once mined.
+// ChainReceipt is a mined transaction: whether it succeeded, the block it landed
+// in and when, and the ERC-20 Transfer it emitted. The Transfer fields let a
+// settlement re-derive that the expected token, amount, and recipient actually
+// moved, rather than trusting the status flag alone.
 export interface ChainReceipt {
   status: "success" | "reverted" | "pending";
+  blockNumber: number;
   blockTimestampMs: number;
+  tokenAddress: string; // the contract that emitted the Transfer
+  to: string; // the Transfer recipient
+  amount: bigint; // the Transfer amount
 }
 
 // ChainClient is the on-chain surface the leg depends on. On a real client it
@@ -42,8 +50,16 @@ export interface ChainClient {
   // hash. Signing happens inside the client, never in the leg.
   send(call: Call): Promise<string>;
   receipt(txHash: string): Promise<ChainReceipt>;
+  // blockNumber reports the current chain head, so a settlement can measure how
+  // many confirmations a transfer has.
+  blockNumber(): Promise<number>;
 }
 
+// The confirmation depth a transfer must reach before it settles. A shallow
+// success can still be reorged out, so a settlement waits for enough blocks on
+// top of it.
+const defaultMinConfirmations = 12;
+
 export interface Erc20Config {
   id?: string;
   token: string; // the ERC-20 contract address
@@ -51,6 +67,13 @@ export interface Erc20Config {
   rail?: string;
   chain: ChainClient;
   ids: () => string;
+  // decimals is the token's on-chain decimal places. A transferred amount's
+  // exponent must equal it, so a quote priced at the wrong scale (cents against a
+  // six-decimal token) is refused rather than moving a wildly wrong amount.
+  decimals: number;
+  // The confirmation depth a transfer must reach before it settles. Omitted uses
+  // defaultMinConfirmations.
+  minConfirmations?: number;
 }
 
 // Erc20Leg settles a payment as an ERC-20 token transfer. Refunds are a
@@ -62,22 +85,45 @@ export class Erc20Leg implements PayInLeg, PayOutLeg {
   private readonly rail: string;
   private readonly chain: ChainClient;
   private readonly ids: () => string;
-  private readonly sent = new Map<string, string>();
+  private readonly decimals: number;
+  private readonly minConf: number;
+  // Each broadcast transfer and what it was meant to move, so a settlement can
+  // confirm the mined transaction really matches the payment.
+  private readonly sent = new Map<string, { txHash: string; to: string; amount: bigint }>();
 
   constructor(cfg: Erc20Config) {
     if (!cfg.token || !cfg.currency) {
       throw new Error("erc20: config requires a token address and currency");
     }
+    // The token address is fixed for the leg's lifetime, so validate it once here
+    // rather than discover a malformed contract address at the first transfer.
+    if (!/^[0-9a-f]{40}$/.test(normalizeAddress(cfg.token))) {
+      throw new Error(`erc20: token ${JSON.stringify(cfg.token)} is not a 20-byte address`);
+    }
     this.id = cfg.id ?? "erc20";
     this.token = cfg.token;
     this.currency = cfg.currency;
     this.rail = cfg.rail ?? "erc20";
     this.chain = cfg.chain;
     this.ids = cfg.ids;
+    this.decimals = cfg.decimals;
+    this.minConf = cfg.minConfirmations ?? defaultMinConfirmations;
+  }
+
+  // checkScale refuses an amount whose exponent does not match the token's
+  // decimals, so a quote priced at the wrong scale never moves the wrong number
+  // of tokens.
+  private checkScale(m: Money): void {
+    if (m.exponent !== this.decimals) {
+      throw new Error(`erc20: amount exponent ${m.exponent} does not match the token's ${this.decimals} decimals`);
+    }
   }
 
   payInCapabilities(): PayInCapabilities {
-    return { rails: [this.rail], currencies: [this.currency], refunds: RefundKind.CounterTransfer };
+    // A token collection is irreversible and the leg holds no custody to send the
+    // payer back, so it advertises no refund rather than a capability it cannot
+    // honour. An adopter that wires refund custody supplies a leg that offers one.
+    return { rails: [this.rail], currencies: [this.currency], refunds: RefundKind.None };
   }
 
   payOutCapabilities(): PayOutCapabilities {
@@ -88,68 +134,90 @@ export class Erc20Leg implements PayInLeg, PayOutLeg {
   // direct corridor, the escrow for a bridged one. received is the net a bridge
   // would convert: the source the payer paid less the corridor fees.
   async collect(intentId: string, quote: Quote, _auth: Authorization, deliverTo: string): Promise<CollectResult> {
+    this.checkScale(quote.srcAmount);
     const net = quote.srcAmount.sub(quote.fees);
+    // A repeat for the same intent returns the transfer already broadcast rather
+    // than sending the payer's tokens twice.
+    const prev = this.sent.get(intentId);
+    if (prev) {
+      return { providerRef: prev.txHash, received: net };
+    }
     const txHash = await this.transfer(deliverTo, net.value());
-    this.sent.set(intentId, txHash);
+    this.sent.set(intentId, { txHash, to: normalizeAddress(deliverTo), amount: net.value() });
     return { providerRef: txHash, received: net };
   }
 
   // disburse delivers the recipient's tokens.
   async disburse(intentId: string, quote: Quote, recipientRef: string): Promise<DisburseResult> {
-    const txHash = await this.transfer(recipientRef, quote.dstAmount.value());
-    this.sent.set(intentId, txHash);
+    this.checkScale(quote.dstAmount);
+    // A repeat for the same intent returns the transfer already broadcast rather
+    // than delivering the recipient's tokens twice.
+    const prev = this.sent.get(intentId);
+    if (prev) {
+      return { providerRef: prev.txHash };
+    }
+    const amount = quote.dstAmount.value();
+    const txHash = await this.transfer(recipientRef, amount);
+    this.sent.set(intentId, { txHash, to: normalizeAddress(recipientRef), amount });
     return { providerRef: txHash };
   }
 
-  // refundIn and reverseOut both answer with a counter-transfer, the only refund
-  // an irreversible token movement supports.
-  async refundIn(intentId: string, kind: RefundKind, reason: string): Promise<Settlement> {
-    if (kind !== RefundKind.CounterTransfer) {
-      throw new Error("erc20: a token transfer can only be refunded by counter-transfer");
-    }
-    return this.terminal(intentId, reason);
+  // refundIn refuses: an ERC-20 collection is irreversible and the leg holds no
+  // custody to counter-transfer the payer back, so it will not record a refund
+  // that moves no tokens. An adopter that wires refund custody supplies a leg
+  // that advertises and honours a refund.
+  async refundIn(_intentId: string, _kind: RefundKind, _amount: Money, _reason: string): Promise<Settlement> {
+    throw new Error("erc20: a token collection cannot be refunded in place; wire refund custody to return the payer");
   }
 
-  async reverseOut(intentId: string, reason: string): Promise<Settlement> {
-    return this.terminal(intentId, reason);
+  // reverseOut refuses, reporting the truth of the rail: a delivered token
+  // transfer cannot be pulled back.
+  async reverseOut(_intentId: string, _reason: string): Promise<Settlement> {
+    throw new Error("erc20: a delivered token transfer cannot be reversed");
   }
 
-  // settlementEvent reads the receipt for an intent's transaction and produces the
-  // event a host feeds back once the transfer confirms. Crypto has no webhook, so
-  // the host polls this instead.
+  // settlementEvent reads a broadcast transfer back from chain and reports its
+  // outcome. A token transfer has no webhook, so a host polls this. It settles
+  // only when the transaction is final: mined successfully, buried under the
+  // required confirmations, and carrying a Transfer of the configured token, in
+  // the amount that was sent, to the recipient it was sent to. A pending or
+  // shallow success stays submitted so the host keeps polling; a revert or a
+  // mismatch fails, so a dropped, reorged, or spoofed transfer never settles.
   async settlementEvent(intentId: string): Promise<AdapterEvent> {
-    const txHash = this.sent.get(intentId);
-    if (!txHash) {
+    const rec = this.sent.get(intentId);
+    if (!rec) {
       throw new Error("erc20: no broadcast transaction for intent");
     }
-    const receipt = await this.chain.receipt(txHash);
-    return {
-      intentId,
-      state: receiptState(receipt),
-      providerTxRef: txHash,
-      onchainTxHash: txHash,
-      reason: receipt.status === "reverted" ? "transaction reverted" : "",
-      settledAt: receipt.blockTimestampMs,
-    };
+    const receipt = await this.chain.receipt(rec.txHash);
+    const base = { intentId, providerTxRef: rec.txHash, onchainTxHash: rec.txHash, settledAt: 0 };
+    if (receipt.status === "reverted") {
+      return { ...base, state: State.Failed, reason: "transaction reverted" };
+    }
+    if (receipt.status !== "success") {
+      return { ...base, state: State.Submitted, reason: "" };
+    }
+    const head = await this.chain.blockNumber();
+    if (receipt.blockNumber === 0 || head < receipt.blockNumber || head - receipt.blockNumber + 1 < this.minConf) {
+      return { ...base, state: State.Submitted, reason: "" };
+    }
+    if (
+      !sameAddress(receipt.tokenAddress, this.token) ||
+      !sameAddress(receipt.to, rec.to) ||
+      receipt.amount !== rec.amount
+    ) {
+      return {
+        ...base,
+        state: State.Failed,
+        reason: "on-chain transfer does not match the expected token, recipient, or amount",
+      };
+    }
+    return { ...base, state: State.Settled, reason: "", settledAt: receipt.blockTimestampMs };
   }
 
   private async transfer(to: string, amount: bigint): Promise<string> {
     return this.chain.send({ to: this.token, data: transferCalldata(to, amount) });
   }
 
-  private terminal(intentId: string, reason: string): Settlement {
-    const txHash = this.sent.get(intentId) ?? "";
-    return {
-      intentId,
-      state: State.Refunded,
-      adapterId: this.id,
-      providerTxRef: txHash,
-      onchainTxHash: txHash,
-      receiptHash: new Uint8Array(0),
-      reason,
-      settledAt: 0,
-    };
-  }
 }
 
 // transferCalldata builds the ERC-20 transfer calldata: the selector, the
@@ -169,13 +237,12 @@ export function transferCalldata(recipient: string, amount: bigint): string {
   return "0x" + transferSelector + address.padStart(64, "0") + amountHex.padStart(64, "0");
 }
 
-function receiptState(receipt: ChainReceipt): State {
-  switch (receipt.status) {
-    case "success":
-      return State.Settled;
-    case "reverted":
-      return State.Failed;
-    default:
-      return State.Submitted;
-  }
+// normalizeAddress lowercases an EVM address and drops any 0x prefix, so two
+// spellings of the same address compare equal.
+function normalizeAddress(addr: string): string {
+  return addr.toLowerCase().replace(/^0x/, "");
+}
+
+function sameAddress(a: string, b: string): boolean {
+  return normalizeAddress(a) === normalizeAddress(b);
 }

package/src/adapters/http.ts

@@ -0,0 +1,14 @@
+// Shared HTTP settings for the network adapters. A provider call that never
+// answers must not hang the corridor forever, so every outbound request carries
+// the same deadline. The Go adapters bound their http.Client the same way.
+
+// httpTimeoutMs bounds how long an outbound provider request may run before it is
+// aborted. It matches the 30-second ceiling the Go adapters use.
+export const httpTimeoutMs = 30_000;
+
+// fetchWithTimeout issues a fetch that aborts once httpTimeoutMs elapses, so a
+// stalled provider surfaces as an error rather than an unbounded wait. A caller
+// that already supplies a signal is left untouched.
+export function fetchWithTimeout(url: string, init: RequestInit = {}): Promise<Response> {
+  return fetch(url, { signal: AbortSignal.timeout(httpTimeoutMs), ...init });
+}