@kasufinance/kasu-sdk 2.8.0 → 2.10.1

package/dist/flows/batch-errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"batch-errors.js","sourceRoot":"","sources":["../../src/flows/batch-errors.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;;;;;;;;;GAaG;AACH,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IAGzC,YAAY,WAAmB,EAAE,OAAgB;QAC7C,KAAK,CACD,OAAO,aAAP,OAAO,cAAP,OAAO,GACH,kCACI,WAAW,CAAC,CAAC,CAAC,SAAS,WAAW,EAAE,CAAC,CAAC,CAAC,EAC3C,EAAE,CACT,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;QACjC,IAAI,CAAC,WAAW,GAAG,WAAW,CAAC;QAC/B,yDAAyD;QACzD,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,kBAAkB,CAAC,SAAS,CAAC,CAAC;IAC9D,CAAC;CACJ;AAiBD;;;;;;;;;;;;GAYG;AACH,MAAM,OAAO,oBAAqB,SAAQ,KAAK;IAI3C,YACI,IAAY,EACZ,OAA+B,EAC/B,OAA6B;QAE7B,KAAK,CAAC,oBAAoB,OAAO,KAAK,IAAI,GAAG,CAAC,CAAC;QAC/C,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;QACnC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,uDAAuD;QACvD,IAAI,OAAO,IAAI,OAAO,IAAI,OAAO,EAAE,CAAC;YAChC,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,OAAO,EAAE;gBACjC,KAAK,EAAE,OAAO,CAAC,KAAK;gBACpB,UAAU,EAAE,KAAK;gBACjB,QAAQ,EAAE,IAAI;gBACd,YAAY,EAAE,IAAI;aACrB,CAAC,CAAC;QACP,CAAC;QACD,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,oBAAoB,CAAC,SAAS,CAAC,CAAC;IAChE,CAAC;CACJ;AAED;;;GAGG;AACH,MAAM,OAAO,iBAAkB,SAAQ,oBAAoB;IACvD,YAAY,IAAY,EAAE,OAA6B;QACnD,KAAK,CAAC,IAAI,EAAE,SAAS,EAAE,OAAO,CAAC,CAAC;QAChC,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;QAChC,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,iBAAiB,CAAC,SAAS,CAAC,CAAC;IAC7D,CAAC;CACJ;AAED,wFAAwF;AACxF,MAAM,UAAU,cAAc,CAAC,GAAY;IACvC,OAAO,GAAG,YAAY,oBAAoB,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC;AACpE,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,0BAA0B,CAAC,GAAY;IACnD,OAAO,CACH,GAAG,YAAY,kBAAkB,IAAI,cAAc,CAAC,GAAG,CAAC,KAAK,QAAQ,CACxE,CAAC;AACN,CAAC"}

package/dist/flows/batch-submission.d.ts

@@ -0,0 +1,223 @@
+import { DepositProof, DepositProofExpectation, ReceiptLike, UserOperationProof, UserOperationProofExpectation } from '../domain/batch-proof';
+import { SponsoredCall } from '../domain/sponsored-calls';
+import { WaitableTransaction } from './observable';
+/**
+ * Submitting a sponsored atomic deposit batch, from the accepted calls to a
+ * PROVEN deposit — the polling policy and the outcome taxonomy, and nothing
+ * else. No relay vendor, no URL, no wallet: the app's ports do the I/O, and
+ * this decides what each answer MEANS.
+ *
+ * The one rule everything here serves: **an ambiguous result is never
+ * reported as failed.** "Failed" tells a lender to try again, and a batch that
+ * may already have moved the money must never invite a second deposit.
+ */
+/** One call of the batch. Structurally `BatchCall`. */
+export interface SubmitBatchCall {
+    to: string;
+    data: string;
+}
+/**
+ * One read of the submitted batch's status, already NORMALISED by the app's
+ * port — the vendor's status vocabulary stays in the app.
+ */
+export type BatchStatusRead = 
+/** Mined: a transaction hash exists. */
+{
+    kind: 'mined';
+    txHash: string;
+    userOperationHash?: string | null;
+}
+/** The vendor says, definitively, that it reverted: nothing deposited. */
+ | {
+    kind: 'reverted';
+}
+/**
+ * Final for the vendor but silent about the deposit, or the status read
+ * was refused: stop polling, outcome UNKNOWN (→ pending).
+ */
+ | {
+    kind: 'unknown';
+    code: string;
+}
+/** Not there yet, replaced, or a transient failure: ask again. */
+ | {
+    kind: 'again';
+    userOperationHash?: string | null;
+};
+export interface BatchSubmissionPorts<R extends ReceiptLike = ReceiptLike> {
+    /**
+     * Hand the batch to the submitter; resolve with its transaction id once it
+     * is ACCEPTED.
+     *
+     * Throw `BatchRevertedError` when it is known to revert, and
+     * `BatchSubmissionError(code, 'failed')` ONLY when nothing was sent — no
+     * session, a refusal before broadcast. Any other throw is read as
+     * PENDING: this cannot know whether an unrecognised error left before or
+     * after the batch was accepted. Resending the same signed request after an
+     * ambiguous answer is the port's business (it owns the wire protocol).
+     */
+    post(calls: readonly SubmitBatchCall[]): Promise<{
+        transactionId: string;
+    }>;
+    /** One status read. A throw is treated as `{ kind: 'again' }`. */
+    getStatus(transactionId: string): Promise<BatchStatusRead>;
+    /**
+     * The mined receipt. Bound it with a timeout of your own; a throw is
+     * PENDING (`receipt_unavailable`) — the batch was mined, its receipt was
+     * just not readable.
+     */
+    getReceipt(txHash: string): Promise<R>;
+    /** ms epoch. */
+    now(): number;
+    sleep(ms: number): Promise<void>;
+}
+export interface BatchPollingPolicy {
+    /** Delay before the second status read (the first is immediate). */
+    initialMs: number;
+    /** Ceiling on the delay between reads. */
+    maxMs: number;
+    /** Multiplier applied to the delay after each read, ≥ 1. */
+    backoff: number;
+    /** Stop polling — PENDING, never failed — after this long. */
+    timeoutMs: number;
+}
+/**
+ * First read at once, then 3 s backing off ×1.5 to a 10 s ceiling, for up to
+ * 10 minutes. Running out of time is PENDING: the batch was accepted and may
+ * still land.
+ */
+export declare const DEFAULT_BATCH_POLLING_POLICY: Readonly<BatchPollingPolicy>;
+/** A proven deposit: the `deposited` proof and the receipt it was read from. */
+export interface ProvenBatch<R extends ReceiptLike = ReceiptLike> {
+    proof: Extract<DepositProof, {
+        kind: 'deposited';
+    }>;
+    receipt: R;
+    txHash: string;
+}
+/** What `submitBatch` resolves with once the batch is accepted. */
+export interface BatchSubmission<R extends ReceiptLike = ReceiptLike> extends WaitableTransaction {
+    transactionId: string;
+    /**
+     * Polls to a mined receipt and proves the deposit in it. Resolves ONLY on
+     * a proven deposit. Rejects with `BatchRevertedError` when it definitively
+     * did not deposit, and with `BatchPendingError` for everything else.
+     */
+    wait(): Promise<ProvenBatch<R>>;
+}
+/**
+ * Submit `calls` and return once the submitter ACCEPTED them; `wait()` then
+ * polls and proves. Use it as the body of a `DepositFlow` `depositBatch`
+ * port, after `validateDepositBatchCalls` and the app's own signing:
+ *
+ * ```ts
+ * depositBatch: (calls) => {
+ *     const { tranche, amount } = validateDepositBatchCalls(calls, expected);
+ *     return submitBatch(
+ *         // `pendingPool`: the strategy's pending pool, so only ITS
+ *         // `DepositRequested` can prove the deposit.
+ *         { calls, expect: { lender, tranche, amount, pendingPool } },
+ *         { post, getStatus, getReceipt, now: Date.now, sleep },
+ *     );
+ * },
+ * ```
+ *
+ * | what happened                                        | outcome                                  |
+ * | ---------------------------------------------------- | ---------------------------------------- |
+ * | `post` throws `BatchRevertedError`                   | rethrown — reverted, nothing deposited   |
+ * | `post` throws `BatchSubmissionError`                 | rethrown with its own outcome            |
+ * | `post` throws anything else                          | `BatchPendingError('post_unknown')`      |
+ * | `post` resolves without a transaction id             | `BatchPendingError('malformed_answer')`  |
+ * | status `reverted`                                    | `BatchRevertedError('')`                 |
+ * | status `unknown`                                     | `BatchPendingError(code)`                |
+ * | polling runs out of time                             | `BatchPendingError('status_timeout')`    |
+ * | receipt unreadable                                   | `BatchPendingError('receipt_unavailable')` |
+ * | receipt: user operation reverted                     | `BatchRevertedError(revertError)`        |
+ * | receipt: this deposit not shown                      | `BatchPendingError('deposit_unproven:<reason>')` |
+ * | receipt: this lender's deposit, tranche and amount   | resolves `ProvenBatch`                   |
+ *
+ * Nothing on this path ever produces a `failed` outcome: by the time a batch
+ * has been posted, only a revert proves that nothing was deposited.
+ */
+export declare function submitBatch<R extends ReceiptLike = ReceiptLike>(input: {
+    calls: readonly SubmitBatchCall[];
+    /** What the receipt must show — see `proveDepositInReceipt`. */
+    expect: Omit<DepositProofExpectation, 'userOperationHash'>;
+}, ports: BatchSubmissionPorts<R>, policy?: Partial<BatchPollingPolicy>): Promise<BatchSubmission<R>>;
+/**
+ * What became of an earlier submission that ended PENDING — ONE status read,
+ * no polling — for an app's guard against lending twice:
+ *
+ * - `deposited` — mined, and the receipt proves the deposit;
+ * - `not-deposited` — definitively reverted (vendor status or the user
+ *   operation's own flag);
+ * - `unknown` — anything else, including a read or receipt that failed.
+ *
+ * Only `not-deposited` may let a new lend proceed unprompted; `deposited`
+ * means the lender is told the earlier one landed (`already-submitted`).
+ */
+export declare function checkBatchOutcome<R extends ReceiptLike = ReceiptLike>(transactionId: string, expect: Omit<DepositProofExpectation, 'userOperationHash'>, ports: Pick<BatchSubmissionPorts<R>, 'getStatus' | 'getReceipt'>): Promise<'deposited' | 'not-deposited' | 'unknown'>;
+/**
+ * `BatchSubmissionPorts` for ONE sponsored call: the same status, receipt and
+ * clock ports — a relay client written for the deposit batch serves both —
+ * with a `post` that receives the call together with its relay `kind`, so the
+ * app never maps one from the other.
+ */
+export interface SponsoredCallSubmissionPorts<R extends ReceiptLike = ReceiptLike> extends Omit<BatchSubmissionPorts<R>, 'post'> {
+    /**
+     * Hand the call to the submitter (`kind` and `[call]` in the relay's
+     * body); resolve with its transaction id once it is ACCEPTED. The same
+     * throw rules as `BatchSubmissionPorts.post`: `BatchRevertedError` when
+     * it is known to revert, `BatchSubmissionError(code, 'failed')` ONLY when
+     * nothing was sent, anything else is read as PENDING.
+     */
+    post(call: SponsoredCall): Promise<{
+        transactionId: string;
+    }>;
+}
+/** An executed call: the `executed` proof and the receipt it was read from. */
+export interface ExecutedCall<R extends ReceiptLike = ReceiptLike> {
+    proof: Extract<UserOperationProof, {
+        kind: 'executed';
+    }>;
+    receipt: R;
+    txHash: string;
+}
+/** What `submitSponsoredCall` resolves with once the call is accepted. */
+export interface SponsoredCallSubmission<R extends ReceiptLike = ReceiptLike> extends WaitableTransaction {
+    transactionId: string;
+    /**
+     * Polls to a mined receipt and proves the sender's operation EXECUTED.
+     * Rejects with `BatchRevertedError` when it definitively did not, and
+     * with `BatchPendingError` for everything else.
+     */
+    wait(): Promise<ExecutedCall<R>>;
+}
+/**
+ * `submitBatch` for ONE sponsored `LendingPoolManager` call — the body of a
+ * `WithdrawFlow` `submitCall` port, and of an app's cancel or
+ * withdraw-at-expiry action. Same post, same polling policy, same outcome
+ * table; the proof is `proveUserOperationInReceipt` (the sender's operation
+ * succeeded) instead of the deposit proof, and an unproven receipt is
+ * `call_unproven:<reason>`.
+ *
+ * ```ts
+ * submitCall: (call) =>
+ *     submitSponsoredCall(
+ *         { call, expect: { sender: lender } },
+ *         { post: (c) => postToMyRelay(c.kind, [c.call]), getStatus, getReceipt, now, sleep },
+ *     ),
+ * ```
+ *
+ * The call is checked against its kind before anything is posted — a known
+ * kind, exactly `{ to, data }`, and `data` opening with that kind's selector —
+ * and a mismatch is `BatchSubmissionError('call_mismatch', 'failed')`: nothing
+ * was sent. Build calls with `kasu.calls`, and this never fires.
+ *
+ * As on the deposit path, nothing after the post ever produces `failed`.
+ */
+export declare function submitSponsoredCall<R extends ReceiptLike = ReceiptLike>(input: {
+    call: SponsoredCall;
+    /** Whose operation must have executed — see `proveUserOperationInReceipt`. */
+    expect: Omit<UserOperationProofExpectation, 'userOperationHash'>;
+}, ports: SponsoredCallSubmissionPorts<R>, policy?: Partial<BatchPollingPolicy>): Promise<SponsoredCallSubmission<R>>;

package/dist/flows/batch-submission.js

@@ -0,0 +1,321 @@
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import { proveDepositInReceipt, proveUserOperationInReceipt, } from '../domain/batch-proof';
+import { SPONSORED_CALL_KINDS, SPONSORED_CALL_SELECTORS, } from '../domain/sponsored-calls';
+import { BatchPendingError, BatchRevertedError, BatchSubmissionError, } from './batch-errors';
+/**
+ * First read at once, then 3 s backing off ×1.5 to a 10 s ceiling, for up to
+ * 10 minutes. Running out of time is PENDING: the batch was accepted and may
+ * still land.
+ */
+export const DEFAULT_BATCH_POLLING_POLICY = Object.freeze({
+    initialMs: 3000,
+    maxMs: 10000,
+    backoff: 1.5,
+    timeoutMs: 10 * 60 * 1000,
+});
+function resolvePolicy(policy) {
+    var _a, _b, _c, _d;
+    const resolved = {
+        initialMs: (_a = policy === null || policy === void 0 ? void 0 : policy.initialMs) !== null && _a !== void 0 ? _a : DEFAULT_BATCH_POLLING_POLICY.initialMs,
+        maxMs: (_b = policy === null || policy === void 0 ? void 0 : policy.maxMs) !== null && _b !== void 0 ? _b : DEFAULT_BATCH_POLLING_POLICY.maxMs,
+        backoff: (_c = policy === null || policy === void 0 ? void 0 : policy.backoff) !== null && _c !== void 0 ? _c : DEFAULT_BATCH_POLLING_POLICY.backoff,
+        timeoutMs: (_d = policy === null || policy === void 0 ? void 0 : policy.timeoutMs) !== null && _d !== void 0 ? _d : DEFAULT_BATCH_POLLING_POLICY.timeoutMs,
+    };
+    const { initialMs, maxMs, backoff, timeoutMs } = resolved;
+    if (!(Number.isFinite(initialMs) && initialMs > 0) ||
+        !(Number.isFinite(maxMs) && maxMs >= initialMs) ||
+        !(Number.isFinite(backoff) && backoff >= 1) ||
+        !(Number.isFinite(timeoutMs) && timeoutMs > 0)) {
+        throw new TypeError('submitBatch: invalid polling policy');
+    }
+    return resolved;
+}
+/**
+ * Submit `calls` and return once the submitter ACCEPTED them; `wait()` then
+ * polls and proves. Use it as the body of a `DepositFlow` `depositBatch`
+ * port, after `validateDepositBatchCalls` and the app's own signing:
+ *
+ * ```ts
+ * depositBatch: (calls) => {
+ *     const { tranche, amount } = validateDepositBatchCalls(calls, expected);
+ *     return submitBatch(
+ *         // `pendingPool`: the strategy's pending pool, so only ITS
+ *         // `DepositRequested` can prove the deposit.
+ *         { calls, expect: { lender, tranche, amount, pendingPool } },
+ *         { post, getStatus, getReceipt, now: Date.now, sleep },
+ *     );
+ * },
+ * ```
+ *
+ * | what happened                                        | outcome                                  |
+ * | ---------------------------------------------------- | ---------------------------------------- |
+ * | `post` throws `BatchRevertedError`                   | rethrown — reverted, nothing deposited   |
+ * | `post` throws `BatchSubmissionError`                 | rethrown with its own outcome            |
+ * | `post` throws anything else                          | `BatchPendingError('post_unknown')`      |
+ * | `post` resolves without a transaction id             | `BatchPendingError('malformed_answer')`  |
+ * | status `reverted`                                    | `BatchRevertedError('')`                 |
+ * | status `unknown`                                     | `BatchPendingError(code)`                |
+ * | polling runs out of time                             | `BatchPendingError('status_timeout')`    |
+ * | receipt unreadable                                   | `BatchPendingError('receipt_unavailable')` |
+ * | receipt: user operation reverted                     | `BatchRevertedError(revertError)`        |
+ * | receipt: this deposit not shown                      | `BatchPendingError('deposit_unproven:<reason>')` |
+ * | receipt: this lender's deposit, tranche and amount   | resolves `ProvenBatch`                   |
+ *
+ * Nothing on this path ever produces a `failed` outcome: by the time a batch
+ * has been posted, only a revert proves that nothing was deposited.
+ */
+export function submitBatch(input, ports, policy) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const resolved = resolvePolicy(policy);
+        const transactionId = yield postOnce(() => ports.post(input.calls));
+        let settled = null;
+        return {
+            transactionId,
+            // Memoised: a second `wait()` reads the same outcome instead of
+            // polling the submitter twice.
+            wait: () => (settled !== null && settled !== void 0 ? settled : (settled = settle(transactionId, input.expect, ports, resolved))),
+        };
+    });
+}
+/**
+ * The post, and what its answer means: the transaction id, or the error the
+ * outcome table names. Shared by both submitters, so the two cannot come to
+ * disagree about which throws are ambiguous.
+ */
+function postOnce(post) {
+    return __awaiter(this, void 0, void 0, function* () {
+        let accepted;
+        try {
+            accepted = yield post();
+        }
+        catch (err) {
+            if (err instanceof BatchRevertedError)
+                throw err;
+            if (err instanceof BatchSubmissionError)
+                throw err;
+            throw new BatchPendingError('post_unknown', { cause: err });
+        }
+        const transactionId = accepted === null || accepted === void 0 ? void 0 : accepted.transactionId;
+        if (typeof transactionId !== 'string' || transactionId === '') {
+            throw new BatchPendingError('malformed_answer');
+        }
+        return transactionId;
+    });
+}
+function readStatus(ports, transactionId) {
+    return __awaiter(this, void 0, void 0, function* () {
+        try {
+            return yield ports.getStatus(transactionId);
+        }
+        catch (_a) {
+            return { kind: 'again' };
+        }
+    });
+}
+/** Poll until a mined hash, or a typed reason there will not be one. */
+function waitForMined(transactionId, ports, policy) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a;
+        const deadline = ports.now() + policy.timeoutMs;
+        let userOperationHash = null;
+        let delay = policy.initialMs;
+        for (;;) {
+            const read = yield readStatus(ports, transactionId);
+            switch (read.kind) {
+                case 'mined':
+                    if (typeof read.txHash !== 'string' || read.txHash === '') {
+                        break; // a malformed "mined" is not an answer; ask again
+                    }
+                    return {
+                        txHash: read.txHash,
+                        userOperationHash: (_a = read.userOperationHash) !== null && _a !== void 0 ? _a : userOperationHash,
+                    };
+                case 'reverted':
+                    throw new BatchRevertedError('');
+                case 'unknown':
+                    throw new BatchPendingError(read.code);
+                case 'again':
+                    if (read.userOperationHash) {
+                        userOperationHash = read.userOperationHash;
+                    }
+                    break;
+                default:
+                    // A read the port did not normalise: not an answer.
+                    break;
+            }
+            if (ports.now() + delay > deadline) {
+                throw new BatchPendingError('status_timeout');
+            }
+            yield ports.sleep(delay);
+            delay = Math.min(policy.maxMs, Math.round(delay * policy.backoff));
+        }
+    });
+}
+/** Poll to a mined hash and read its receipt; a receipt read that throws is PENDING. */
+function minedReceipt(transactionId, ports, policy) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const mined = yield waitForMined(transactionId, ports, policy);
+        try {
+            return {
+                receipt: yield ports.getReceipt(mined.txHash),
+                txHash: mined.txHash,
+                userOperationHash: mined.userOperationHash,
+            };
+        }
+        catch (err) {
+            throw new BatchPendingError('receipt_unavailable', { cause: err });
+        }
+    });
+}
+function settle(transactionId, expect, ports, policy) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const mined = yield minedReceipt(transactionId, ports, policy);
+        let proof;
+        try {
+            proof = proveDepositInReceipt(mined.receipt, Object.assign(Object.assign({}, expect), { userOperationHash: mined.userOperationHash }));
+        }
+        catch (err) {
+            // A receipt the proof cannot even read proves nothing either way.
+            throw new BatchPendingError('deposit_unproven', { cause: err });
+        }
+        if (proof.kind === 'reverted')
+            throw new BatchRevertedError(proof.revertError);
+        if (proof.kind === 'unproven') {
+            // The proof's reason rides in the code: "no-user-operation" (the hash
+            // is not this lender's operation at all) and "no-deposit-requested"
+            // (the operation ran and shows no deposit) are the two things an
+            // operator reading the alert needs to tell apart first.
+            throw new BatchPendingError(`deposit_unproven:${proof.reason}`);
+        }
+        return { proof, receipt: mined.receipt, txHash: mined.txHash };
+    });
+}
+/**
+ * What became of an earlier submission that ended PENDING — ONE status read,
+ * no polling — for an app's guard against lending twice:
+ *
+ * - `deposited` — mined, and the receipt proves the deposit;
+ * - `not-deposited` — definitively reverted (vendor status or the user
+ *   operation's own flag);
+ * - `unknown` — anything else, including a read or receipt that failed.
+ *
+ * Only `not-deposited` may let a new lend proceed unprompted; `deposited`
+ * means the lender is told the earlier one landed (`already-submitted`).
+ */
+export function checkBatchOutcome(transactionId, expect, ports) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a;
+        let read;
+        try {
+            read = yield ports.getStatus(transactionId);
+        }
+        catch (_b) {
+            return 'unknown';
+        }
+        if (read.kind === 'reverted')
+            return 'not-deposited';
+        if (read.kind !== 'mined' || typeof read.txHash !== 'string') {
+            return 'unknown';
+        }
+        try {
+            const receipt = yield ports.getReceipt(read.txHash);
+            const proof = proveDepositInReceipt(receipt, Object.assign(Object.assign({}, expect), { userOperationHash: (_a = read.userOperationHash) !== null && _a !== void 0 ? _a : null }));
+            if (proof.kind === 'deposited')
+                return 'deposited';
+            if (proof.kind === 'reverted')
+                return 'not-deposited';
+            return 'unknown';
+        }
+        catch (_c) {
+            return 'unknown';
+        }
+    });
+}
+/**
+ * `submitBatch` for ONE sponsored `LendingPoolManager` call — the body of a
+ * `WithdrawFlow` `submitCall` port, and of an app's cancel or
+ * withdraw-at-expiry action. Same post, same polling policy, same outcome
+ * table; the proof is `proveUserOperationInReceipt` (the sender's operation
+ * succeeded) instead of the deposit proof, and an unproven receipt is
+ * `call_unproven:<reason>`.
+ *
+ * ```ts
+ * submitCall: (call) =>
+ *     submitSponsoredCall(
+ *         { call, expect: { sender: lender } },
+ *         { post: (c) => postToMyRelay(c.kind, [c.call]), getStatus, getReceipt, now, sleep },
+ *     ),
+ * ```
+ *
+ * The call is checked against its kind before anything is posted — a known
+ * kind, exactly `{ to, data }`, and `data` opening with that kind's selector —
+ * and a mismatch is `BatchSubmissionError('call_mismatch', 'failed')`: nothing
+ * was sent. Build calls with `kasu.calls`, and this never fires.
+ *
+ * As on the deposit path, nothing after the post ever produces `failed`.
+ */
+export function submitSponsoredCall(input, ports, policy) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const resolved = resolvePolicy(policy);
+        if (!isWellFormedSponsoredCall(input.call)) {
+            throw new BatchSubmissionError('call_mismatch', 'failed');
+        }
+        const transactionId = yield postOnce(() => ports.post(input.call));
+        let settled = null;
+        return {
+            transactionId,
+            wait: () => (settled !== null && settled !== void 0 ? settled : (settled = settleCall(transactionId, input.expect, ports, resolved))),
+        };
+    });
+}
+function isWellFormedSponsoredCall(value) {
+    if (value === null || typeof value !== 'object')
+        return false;
+    const { kind, call } = value;
+    if (typeof kind !== 'string' ||
+        !SPONSORED_CALL_KINDS.includes(kind)) {
+        return false;
+    }
+    if (call === null || typeof call !== 'object')
+        return false;
+    const keys = Object.keys(call);
+    if (keys.length !== 2 || !keys.includes('to') || !keys.includes('data')) {
+        return false;
+    }
+    const { to, data } = call;
+    return (typeof to === 'string' &&
+        /^0x[0-9a-fA-F]{40}$/.test(to) &&
+        typeof data === 'string' &&
+        /^0x(?:[0-9a-fA-F]{2})*$/.test(data) &&
+        data
+            .toLowerCase()
+            .startsWith(SPONSORED_CALL_SELECTORS[kind]));
+}
+function settleCall(transactionId, expect, ports, policy) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const mined = yield minedReceipt(transactionId, ports, policy);
+        let proof;
+        try {
+            proof = proveUserOperationInReceipt(mined.receipt, Object.assign(Object.assign({}, expect), { userOperationHash: mined.userOperationHash }));
+        }
+        catch (err) {
+            throw new BatchPendingError('call_unproven', { cause: err });
+        }
+        if (proof.kind === 'reverted') {
+            throw new BatchRevertedError(proof.revertError);
+        }
+        if (proof.kind === 'unproven') {
+            throw new BatchPendingError(`call_unproven:${proof.reason}`);
+        }
+        return { proof, receipt: mined.receipt, txHash: mined.txHash };
+    });
+}
+//# sourceMappingURL=batch-submission.js.map

package/dist/flows/batch-submission.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"batch-submission.js","sourceRoot":"","sources":["../../src/flows/batch-submission.ts"],"names":[],"mappings":"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"}

package/dist/flows/deposit-flow.d.ts

@@ -1,6 +1,7 @@
 import { BigNumber } from 'ethers';
 import { GenerateContractResponse } from '../domain/loan-contract';
 import { DepositParams, KycParams } from '../facade/types';
+import { BatchRevertedError } from './batch-errors';
 import { Flow } from './flow';
 import { WaitableTransaction } from './observable';
 /**
@@ -142,6 +143,17 @@ export type DepositFailure = {
 } | {
     step: 'request';
     reason: 'contract-expired';
+} | {
+    step: 'request';
+    /**
+     * Batch path only — a `BatchSubmissionError` whose outcome is not
+     * `failed`. `pending`: the batch was, or may have been, accepted and
+     * nothing proves whether it deposited — NEVER render it as a
+     * failure, which invites a second deposit. `already-submitted`: an
+     * earlier submission was proven, so this one was refused.
+     */
+    reason: 'pending' | 'already-submitted';
+    error: unknown;
 };
 export type { WaitableTransaction };
 /**
@@ -152,26 +164,7 @@ export interface BatchCall {
     to: string;
     data: string;
 }
-/**
- * What a `depositBatch` port throws when it KNOWS the batch reverted — from a
- * simulation before sending, or from the submitter refusing to broadcast a
- * batch that would revert. The run ends `{ step: 'request', reason:
- * 'reverted', revertError }`.
- *
- * `revertError` is the custom error the contract named (`'ClearingIsPending'`,
- * `'UserNotKycd'`, …), exactly as the ABI declares it. Pass `''` when the
- * batch is known to revert but not why: the consumer then renders its generic
- * `reverted` copy, which is what an unknown name gets anyway.
- *
- * Any OTHER throw from the port is read the way a direct deposit's is — a
- * wallet rejection is `cancelled`, a decodable revert is `reverted`, and
- * everything else is `failed` with the error kept. A port that cannot tell is
- * better off throwing what it has than guessing a name.
- */
-export declare class BatchRevertedError extends Error {
-    readonly revertError: string;
-    constructor(revertError: string, message?: string);
-}
+export { BatchRevertedError };
 /** What the KYC signing service hands back. */
 export interface KycSignature {
     signature: string;