@myzonerocks/pact 0.1.3 → 0.1.4

package/dist/src/router.js

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

package/dist/src/wire.js

@@ -1,4 +1,5 @@
 import { Money } from "./money.js";
+import { stateName } from "./state.js";
 import { CanonicalWriter } from "./canonical.js";
 // The wire codec serializes messages for transport. It is distinct from the
 // canonical signing preimage: signing binds a fixed subset of fields under a
@@ -126,7 +127,14 @@ class WireReader {
         }
         const view = new DataView(this.buf.buffer, this.buf.byteOffset + this.pos, 8);
         this.pos += 8;
-        return Number(view.getBigUint64(0, false));
+        const value = view.getBigUint64(0, false);
+        // A value above 2^53 cannot be held exactly in a JS number, so reject it
+        // rather than decode a Go or Dart value into a silently different one. Every
+        // real field here — millisecond timestamps, ordinals, latency — fits easily.
+        if (value > BigInt(Number.MAX_SAFE_INTEGER)) {
+            throw new Error("pact: u64 field exceeds the exact-integer range");
+        }
+        return Number(value);
     }
     money() {
         const minor = this.str();
@@ -204,11 +212,20 @@ export function decodeAuthorization(b) {
     r.requireDone();
     return auth;
 }
+// stateFromOrdinal rejects an ordinal outside the known states rather than pass
+// an out-of-range number through as a State, so a corrupt wire byte cannot decode
+// to a nonexistent state.
+function stateFromOrdinal(n) {
+    if (!(n in stateName)) {
+        throw new Error(`pact: unknown settlement state ordinal ${n}`);
+    }
+    return n;
+}
 export function decodeSettlement(b) {
     const r = new WireReader(b);
     const settlement = {
         intentId: r.str(),
-        state: r.u64(),
+        state: stateFromOrdinal(r.u64()),
         adapterId: r.str(),
         providerTxRef: r.str(),
         onchainTxHash: r.str(),

package/dist/test/erc20.test.js

@@ -16,22 +16,39 @@ function signerVerifier(identity) {
     const signer = Ed25519Signer.fromSeed(identity, seed);
     return { signer, verifier: new Ed25519Verifier(new Map([[identity, signer.publicKey]])) };
 }
+const usdcToken = "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48";
+const recipient = "0x00000000000000000000000000000000000000aa";
 // FakeChain records the calls it is asked to broadcast and returns a receipt the
-// test controls, so the leg runs with no chain and no key.
+// test controls, so the leg runs with no chain and no key. The receipt defaults
+// to a deep, matching transfer so a settlement confirms; a test overrides fields
+// to model a revert, a shallow success, or a mismatched transfer.
 class FakeChain {
     calls = [];
     ids = counter();
     status = "success";
+    head = 100;
+    minedBlock = 1;
+    token = usdcToken;
+    to = recipient;
+    amount = 1000000n;
     async send(call) {
         this.calls.push(call);
         return this.ids();
     }
     async receipt(_txHash) {
-        return { status: this.status, blockTimestampMs: 1_700_000_005_000 };
+        return {
+            status: this.status,
+            blockNumber: this.minedBlock,
+            blockTimestampMs: 1_700_000_005_000,
+            tokenAddress: this.token,
+            to: this.to,
+            amount: this.amount,
+        };
+    }
+    async blockNumber() {
+        return this.head;
     }
 }
-const usdcToken = "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48";
-const recipient = "0x00000000000000000000000000000000000000aa";
 describe("erc20 transfer calldata", () => {
     it("encodes selector, padded address, and 32-byte amount", () => {
         // 1_000_000 minor units of a 6-decimal token is one whole token: 0xf4240.
@@ -49,7 +66,7 @@ describe("erc20 direct corridor", () => {
     const now = 1_700_000_000_000;
     function build(chain) {
         const { signer, verifier } = signerVerifier("alice");
-        const leg = new Erc20Leg({ token: usdcToken, currency: "USDC", chain, ids: counter() });
+        const leg = new Erc20Leg({ token: usdcToken, currency: "USDC", chain, ids: counter(), decimals: 6 });
         const client = new Client({ payIn: [leg], payOut: [leg], verifier, clock: () => now, idGen: counter() });
         return { signer, leg, client };
     }
@@ -78,34 +95,12 @@ describe("erc20 direct corridor", () => {
         expect(chain.calls[0].to).toBe(usdcToken);
         expect(chain.calls[0].data).toBe(transferCalldata(recipient, 1000000n));
     });
-    it("only refunds by counter-transfer", async () => {
+    it("advertises no refund and refuses to refund or reverse", async () => {
         const chain = new FakeChain();
         const { leg } = build(chain);
-        await leg.collect("intent-1", {
-            id: "q",
-            intentId: "intent-1",
-            payInAdapterId: "erc20",
-            payInRail: "erc20",
-            payOutAdapterId: "erc20",
-            payOutRail: "erc20",
-            bridgeId: "passthrough",
-            srcAmount: Money.parse("USDC", 6, "1000000"),
-            dstAmount: Money.parse("USDC", 6, "1000000"),
-            fees: Money.parse("USDC", 6, "0"),
-            fxRate: "1",
-            expiresAt: 0,
-            providerQuoteRef: "",
-            latencyEstimateMs: 0,
-        }, {
-            intentId: "intent-1",
-            quoteId: "q",
-            signerIdentity: "",
-            signedAt: 0,
-            signature: new Uint8Array(0),
-        }, recipient);
-        await expect(leg.refundIn("intent-1", RefundKind.Full, "x")).rejects.toThrow();
-        const settlement = await leg.refundIn("intent-1", RefundKind.CounterTransfer, "returning funds");
-        expect(settlement.state).toBe(State.Refunded);
+        expect(leg.payInCapabilities().refunds).toBe(RefundKind.None);
+        await expect(leg.refundIn("intent-1", RefundKind.CounterTransfer, Money.parse("USDC", 6, "1000000"), "x")).rejects.toThrow();
+        await expect(leg.reverseOut("intent-1", "x")).rejects.toThrow();
     });
     it("fails the intent when the transaction reverts", async () => {
         const chain = new FakeChain();
@@ -129,3 +124,72 @@ describe("erc20 direct corridor", () => {
         expect(event.state).toBe(State.Failed);
     });
 });
+describe("erc20 on-chain confirmation", () => {
+    it("settles a deep, matching transfer", async () => {
+        const chain = new FakeChain();
+        chain.head = 100;
+        chain.minedBlock = 90;
+        const leg = new Erc20Leg({ token: usdcToken, currency: "USDC", chain, ids: counter(), decimals: 6, minConfirmations: 3 });
+        const quote = {
+            id: "q", intentId: "intent-1", payInAdapterId: "erc20", payInRail: "erc20",
+            payOutAdapterId: "erc20", payOutRail: "erc20", bridgeId: "passthrough",
+            srcAmount: Money.parse("USDC", 6, "1000000"), dstAmount: Money.parse("USDC", 6, "1000000"),
+            fees: Money.parse("USDC", 6, "0"), fxRate: "1", expiresAt: 0, providerQuoteRef: "", latencyEstimateMs: 0,
+        };
+        await leg.disburse("intent-1", quote, recipient);
+        const event = await leg.settlementEvent("intent-1");
+        expect(event.state).toBe(State.Settled);
+    });
+    it("stays submitted until the transfer is deep enough", async () => {
+        const chain = new FakeChain();
+        chain.head = 91;
+        chain.minedBlock = 90; // only two blocks deep, below the three required
+        const leg = new Erc20Leg({ token: usdcToken, currency: "USDC", chain, ids: counter(), decimals: 6, minConfirmations: 3 });
+        const quote = {
+            id: "q", intentId: "intent-1", payInAdapterId: "erc20", payInRail: "erc20",
+            payOutAdapterId: "erc20", payOutRail: "erc20", bridgeId: "passthrough",
+            srcAmount: Money.parse("USDC", 6, "1000000"), dstAmount: Money.parse("USDC", 6, "1000000"),
+            fees: Money.parse("USDC", 6, "0"), fxRate: "1", expiresAt: 0, providerQuoteRef: "", latencyEstimateMs: 0,
+        };
+        await leg.disburse("intent-1", quote, recipient);
+        const event = await leg.settlementEvent("intent-1");
+        expect(event.state).toBe(State.Submitted);
+    });
+    it("does not settle a transfer to the wrong recipient", async () => {
+        const chain = new FakeChain();
+        chain.head = 100;
+        chain.minedBlock = 90;
+        chain.to = "0x00000000000000000000000000000000000000bb";
+        const leg = new Erc20Leg({ token: usdcToken, currency: "USDC", chain, ids: counter(), decimals: 6, minConfirmations: 3 });
+        const quote = {
+            id: "q", intentId: "intent-1", payInAdapterId: "erc20", payInRail: "erc20",
+            payOutAdapterId: "erc20", payOutRail: "erc20", bridgeId: "passthrough",
+            srcAmount: Money.parse("USDC", 6, "1000000"), dstAmount: Money.parse("USDC", 6, "1000000"),
+            fees: Money.parse("USDC", 6, "0"), fxRate: "1", expiresAt: 0, providerQuoteRef: "", latencyEstimateMs: 0,
+        };
+        await leg.disburse("intent-1", quote, recipient);
+        const event = await leg.settlementEvent("intent-1");
+        expect(event.state).toBe(State.Failed);
+    });
+});
+describe("erc20 token scale", () => {
+    const wrongScaleQuote = {
+        id: "q", intentId: "intent-1", payInAdapterId: "erc20", payInRail: "erc20",
+        payOutAdapterId: "erc20", payOutRail: "erc20", bridgeId: "passthrough",
+        // Priced in cents against a six-decimal token: the wrong scale entirely.
+        srcAmount: Money.parse("USDC", 2, "500"), dstAmount: Money.parse("USDC", 2, "500"),
+        fees: Money.parse("USDC", 2, "0"), fxRate: "1", expiresAt: 0, providerQuoteRef: "", latencyEstimateMs: 0,
+    };
+    it("refuses a collect whose exponent does not match the token decimals", async () => {
+        const chain = new FakeChain();
+        const leg = new Erc20Leg({ token: usdcToken, currency: "USDC", chain, ids: counter(), decimals: 6 });
+        await expect(leg.collect("intent-1", wrongScaleQuote, { signerRef: "", signature: "", nonce: "" }, recipient)).rejects.toThrow();
+        expect(chain.calls.length).toBe(0);
+    });
+    it("refuses a disburse whose exponent does not match the token decimals", async () => {
+        const chain = new FakeChain();
+        const leg = new Erc20Leg({ token: usdcToken, currency: "USDC", chain, ids: counter(), decimals: 6 });
+        await expect(leg.disburse("intent-1", wrongScaleQuote, recipient)).rejects.toThrow();
+        expect(chain.calls.length).toBe(0);
+    });
+});

package/dist/test/fake.d.ts

@@ -0,0 +1,29 @@
+import { RefundKind } from "../src/adapter.js";
+import type { Money } from "../src/money.js";
+import type { Quote, Authorization, Settlement } from "../src/message.js";
+import type { RateSource, EscrowVault } from "../src/bridge.js";
+import type { PayInLeg, PayOutLeg, PayInCapabilities, PayOutCapabilities, CollectResult, DisburseResult } from "../src/leg.js";
+export declare class FakeLeg implements PayInLeg, PayOutLeg {
+    readonly id: string;
+    private readonly rail;
+    private readonly currency;
+    private readonly ids;
+    failPayout: boolean;
+    constructor(id: string, rail: string, currency: string, ids: () => string);
+    payInCapabilities(): PayInCapabilities;
+    collect(_intentId: string, quote: Quote, _auth: Authorization, _deliverTo: string): Promise<CollectResult>;
+    refundIn(intentId: string, _kind: RefundKind, _amount: Money, reason: string): Promise<Settlement>;
+    payOutCapabilities(): PayOutCapabilities;
+    disburse(_intentId: string, _quote: Quote, _recipientRef: string): Promise<DisburseResult>;
+    reverseOut(intentId: string, reason: string): Promise<Settlement>;
+    private terminal;
+}
+export declare class FakeRates implements RateSource {
+    private readonly table;
+    constructor(table: Record<string, string>);
+    rate(from: string, to: string): Promise<string>;
+}
+export declare class FakeVault implements EscrowVault {
+    hold(intentId: string, _amount: Money): Promise<string>;
+    release(_intentId: string): Promise<void>;
+}

package/dist/test/fake.js

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

package/dist/test/lifecycle.test.js

@@ -4,7 +4,7 @@ import { Money } from "../src/money.js";
 import { State } from "../src/state.js";
 import { isDirect } from "../src/message.js";
 import { UsdcBridge } from "../src/bridge.js";
-import { FakeLeg, FakeRates, FakeVault } from "../src/fake.js";
+import { FakeLeg, FakeRates, FakeVault } from "./fake.js";
 import { Ed25519Signer, Ed25519Verifier } from "../src/signing.js";
 import { fromHex } from "../src/crypto.js";
 function counter() {
@@ -61,6 +61,33 @@ describe("corridor lifecycle", () => {
         expect(states).toEqual([State.Draft, State.Quoted, State.Authorized, State.Submitted, State.Settled]);
         expect(client.head(intent.id)).toBeDefined();
     });
+    it("refunds a settled intent with an explicit amount and refuses an over-refund", async () => {
+        const { signer, verifier } = signerVerifier("alice");
+        const wallet = new FakeLeg("wallet", "wallet", "USD", counter());
+        const client = new Client({ payIn: [wallet], payOut: [wallet], verifier, clock: () => now, idGen: counter() });
+        const intent = client.createIntent({
+            senderRef: "alice",
+            recipientRef: "bob",
+            amount: Money.parse("USD", 2, "1500"),
+            expiresAt: now + 600_000,
+            allowedRails: ["wallet"],
+        });
+        const quotes = await client.quoteOptions(intent, [{ payInAdapterId: "wallet", currency: "USD", exponent: 2 }]);
+        const quote = await client.select(quotes, signer.identity());
+        const auth = await client.authorize(intent, quote, signer);
+        await client.initiate(intent, quote, auth);
+        await client.advance(intent.id, "wallet", { intentId: intent.id, state: State.Settled, providerTxRef: "", onchainTxHash: "", reason: "", settledAt: 0 });
+        // A refund over the funded source amount is refused.
+        await expect(client.refund(intent.id, Money.parse("USD", 2, "9999"), "too much")).rejects.toThrow();
+        // The wallet leg refunds only in full, so a partial refund is refused.
+        await expect(client.refund(intent.id, Money.parse("USD", 2, "700"), "partial")).rejects.toThrow();
+        // A full refund settles the intent to refunded.
+        const { state } = await client.refund(intent.id, quote.srcAmount, "changed mind");
+        expect(state).toBe(State.Refunded);
+        // A second refund is an idempotent no-op that echoes the refunded state.
+        const again = await client.refund(intent.id, quote.srcAmount, "again");
+        expect(again.state).toBe(State.Refunded);
+    });
     // A bridged corridor: the payer funds in USD by card, a USDC bridge converts to
     // KES, and an M-Pesa leg delivers to the recipient.
     it("settles a bridged card-USD to USDC to mpesa-KES corridor end to end", async () => {
@@ -195,14 +222,15 @@ describe("corridor lifecycle", () => {
         const client = new Client({
             payIn: [new FakeLeg("wallet", "wallet", "USD", counter())],
             verifier,
-            clock: () => 1,
+            // The clock sits well past the intent's deadline, so it is genuinely expired.
+            clock: () => 2_000_000,
             idGen: counter(),
         });
         const intent = client.createIntent({
             senderRef: "a",
             recipientRef: "b",
             amount: Money.parse("USD", 2, "100"),
-            expiresAt: 0,
+            expiresAt: 1000,
             allowedRails: ["wallet"],
         });
         client.expire(intent.id);

package/dist/test/money.test.d.ts

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

package/dist/test/money.test.js

@@ -0,0 +1,27 @@
+import { describe, it, expect } from "vitest";
+import { Money } from "../src/money.js";
+import { parseRate } from "../src/bridge.js";
+describe("money parse grammar", () => {
+    it("rejects hex, signed, whitespaced, and zero-padded amounts", () => {
+        for (const bad of ["0x10", " 5", "5 ", "+5", "-5", "007", "", "1.5", "1e3"]) {
+            expect(() => Money.parse("USD", 2, bad)).toThrow();
+        }
+    });
+    it("accepts a bare non-negative integer", () => {
+        for (const ok of ["0", "5", "1000000000000000000000"]) {
+            expect(Money.parse("USD", 2, ok).minor()).toBe(ok);
+        }
+    });
+});
+describe("rate parse grammar", () => {
+    it("rejects a sign, a radix prefix, whitespace, and leading zeros", () => {
+        for (const bad of ["0x10", " 1.5", "+1", "-1", "01", "1.", ".5", ""]) {
+            expect(() => parseRate(bad)).toThrow();
+        }
+    });
+    it("accepts an integer or fixed-point rate, including a leading-zero decimal", () => {
+        for (const ok of ["0", "129", "1.45", "0.5"]) {
+            expect(() => parseRate(ok)).not.toThrow();
+        }
+    });
+});

package/dist/test/mpesa.test.js

@@ -5,7 +5,7 @@ import { State } from "../src/state.js";
 import { isDirect } from "../src/message.js";
 import { RefundKind } from "../src/adapter.js";
 import { UsdcBridge } from "../src/bridge.js";
-import { FakeLeg, FakeRates, FakeVault } from "../src/fake.js";
+import { FakeLeg, FakeRates, FakeVault } from "./fake.js";
 import { Ed25519Signer, Ed25519Verifier } from "../src/signing.js";
 import { fromHex } from "../src/crypto.js";
 import { MpesaLeg, ErrUnknownCheckout, normalizePhone, } from "../src/adapters/mpesa.js";
@@ -19,22 +19,34 @@ function signerVerifier(identity) {
     return { signer, verifier: new Ed25519Verifier(new Map([[identity, signer.publicKey]])) };
 }
 // FakeDaraja is an in-memory stand-in for Daraja so the leg runs end to end with
-// no network and no credentials.
+// no network and no credentials. queryResults maps a checkout id to the outcome
+// Daraja would report back; a checkout with no entry answers as still processing,
+// standing in for a push the payer never approved.
 class FakeDaraja {
     lastPush;
     lastB2C;
+    queryResults = new Map();
     ids;
     constructor(ids) {
         this.ids = ids;
     }
     async stkPush(params) {
         this.lastPush = params;
-        return { merchantRequestId: this.ids(), checkoutRequestId: this.ids(), responseCode: "0" };
+        const checkout = this.ids();
+        // By default a push confirms as a success, so the happy path settles; a test
+        // overrides queryResults to model other outcomes.
+        if (!this.queryResults.has(checkout)) {
+            this.queryResults.set(checkout, { resultCode: 0, resultDesc: "", pending: false });
+        }
+        return { merchantRequestId: this.ids(), checkoutRequestId: checkout, responseCode: "0" };
     }
     async b2cPayment(params) {
         this.lastB2C = params;
         return { conversationId: this.ids(), responseCode: "0" };
     }
+    async query(checkoutRequestId) {
+        return this.queryResults.get(checkoutRequestId) ?? { resultCode: 0, resultDesc: "", pending: true };
+    }
 }
 function buildLeg(api) {
     return new MpesaLeg({
@@ -95,9 +107,9 @@ describe("mpesa whole-shilling guard", () => {
     });
 });
 describe("mpesa unknown checkout", () => {
-    it("rejects a callback whose checkout id it never started", () => {
+    it("rejects a callback whose checkout id it never started", async () => {
         const leg = buildLeg(new FakeDaraja(counter("tx")));
-        expect(() => leg.parseWebhook(successCallback("never-started", "ABC"), {})).toThrow(ErrUnknownCheckout);
+        await expect(leg.parseWebhook(successCallback("never-started", "ABC"), {})).rejects.toThrow(ErrUnknownCheckout);
     });
 });
 describe("mpesa pay-out", () => {
@@ -158,13 +170,13 @@ describe("mpesa pay-in", () => {
         const collected = await leg.collect("intent-1", q, emptyAuth, "0711000111");
         expect(api.lastPush.accountReference).toBe("intent-1");
         expect(api.lastPush.payerPhone).toBe("254711000111");
-        const events = leg.parseWebhook(successCallback(collected.providerRef, "QGR7XYZ123"), {});
+        const events = await leg.parseWebhook(successCallback(collected.providerRef, "QGR7XYZ123"), {});
         expect(events).toHaveLength(1);
         expect(events[0].state).toBe(State.Settled);
         expect(events[0].intentId).toBe("intent-1");
         expect(events[0].providerTxRef).toBe("QGR7XYZ123");
         // A refund is a business-to-customer counter-transfer back to the payer.
-        await leg.refundIn("intent-1", RefundKind.CounterTransfer, "returning funds");
+        await leg.refundIn("intent-1", RefundKind.CounterTransfer, Money.parse("KES", 0, "1500"), "returning funds");
         expect(api.lastB2C.phone).toBe("254711000111");
         expect(api.lastB2C.amount).toBe(1500);
     });
@@ -173,8 +185,29 @@ describe("mpesa pay-in", () => {
         const leg = buildLeg(api);
         const q = quote({ srcAmount: kes("1500"), fees: kes("0") });
         const collected = await leg.collect("intent-1", q, emptyAuth, "0711000111");
-        const events = leg.parseWebhook(failureCallback(collected.providerRef), {});
+        // The payer cancelled: the authenticated query is what reports the failure.
+        api.queryResults.set(collected.providerRef, { resultCode: 1032, resultDesc: "Request cancelled by user", pending: false });
+        const events = await leg.parseWebhook(failureCallback(collected.providerRef), {});
         expect(events).toHaveLength(1);
         expect(events[0].state).toBe(State.Failed);
     });
+    it("settles nothing for a forged success on a push the payer never approved", async () => {
+        const api = new FakeDaraja(counter("tx"));
+        const leg = buildLeg(api);
+        const q = quote({ srcAmount: kes("1500"), fees: kes("0") });
+        const collected = await leg.collect("intent-1", q, emptyAuth, "0711000111");
+        // The payer has not approved, so Daraja is still processing this checkout.
+        api.queryResults.set(collected.providerRef, { resultCode: 0, resultDesc: "", pending: true });
+        const events = await leg.parseWebhook(successCallback(collected.providerRef, "FORGEDRCPT"), {});
+        expect(events).toHaveLength(0);
+    });
+    it("settles nothing when the callback amount differs from the authorized quote", async () => {
+        const api = new FakeDaraja(counter("tx"));
+        const leg = buildLeg(api);
+        const q = quote({ srcAmount: kes("5000"), fees: kes("0") });
+        const collected = await leg.collect("intent-1", q, emptyAuth, "0711000111");
+        // Daraja confirms success, but the callback body claims only 1500 was paid.
+        api.queryResults.set(collected.providerRef, { resultCode: 0, resultDesc: "", pending: false });
+        await expect(leg.parseWebhook(successCallback(collected.providerRef, "QGR7XYZ123"), {})).rejects.toThrow();
+    });
 });