@kasufinance/kasu-sdk 2.7.1 → 2.8.0

package/README.md

@@ -225,8 +225,52 @@ await flow.acceptContract(); // signs it and carries on
 // or: flow.declineContract();  → phase 'declined', nothing submitted
 ```
 
+### One atomic transaction: the `depositBatch` port
+
+If your application can submit several calls as ONE atomic transaction (all
+apply or none does), supply the optional `depositBatch` port. When the
+allowance is short, the run then approves and deposits in a single batch
+instead of two transactions. You decide how the batch is sent; the SDK decides
+what is in it:
+
+```ts
+import { BatchRevertedError, type BatchCall } from '@kasufinance/kasu-sdk';
+
+const flow = kasu.flows.deposit({
+    signMessage,
+    generateContract,
+    getKycSignature,
+    depositBatch: async (calls: BatchCall[]) => {
+        // calls[0]: stableAsset.approve(LendingPoolManager, amount) — EXACT amount
+        // calls[1]: LendingPoolManager.requestDepositWithKyc(…) — value 0
+        const tx = await submitAtomically(calls); // your mechanism
+        return tx; // anything with wait()
+        // Known to revert? throw new BatchRevertedError('ClearingIsPending')
+    },
+});
+
+// …after acceptContract(), a batched run parks on `awaiting-authorise`:
+flow.authoriseTransfer(); // the lender's explicit go-ahead
+// or: flow.declineTransfer(); → error { step: 'request', reason: 'cancelled' }
+```
+
+- The batch path is taken only when the allowance is short, the port is
+  supplied and the chain's stable token is known (`kasu.flows.deposit()` fills
+  it from the chain config). Otherwise the run is exactly the two-transaction
+  pipeline.
+- A batch has no wallet prompt per call, so the run **parks for an explicit
+  authorisation** before any money moves. The agreement's TTL is checked again
+  after it, and the KYC signature is fetched only then.
+- `state.batched` is `true` from the first state of a batched run. It never
+  enters `approve`, so it counts as a three-step run (`stepTotal` 3).
+- Throw `BatchRevertedError(revertError)` when the batch is known to revert →
+  `{ step: 'request', reason: 'reverted', revertError }`. Any other throw is
+  read like a direct deposit's: a wallet rejection is `cancelled`, everything
+  else `failed`.
+
 **Phases** — `idle`, `generating-sign`, `generating-fetch`, `awaiting-accept`,
-`accepting-sign`, `approve`, `request-sign`, `request-confirm`, and the
+`accepting-sign`, `approve`, `awaiting-authorise` (batch path only),
+`request-sign`, `request-confirm`, and the
 terminal `success` / `declined` / `error`. Each maps to one of four steps
 (`generate`, `confirm`, `approve`, `request`); `stepIndex` and `stepTotal` are
 published because the approve step drops out of the sequence when the allowance

package/dist/bundle.cjs.js

@@ -25148,6 +25148,31 @@ function classifyWalletFailure(step, err) {
         : { step, reason: 'failed', error: err };
 }
 
+/**
+ * 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.
+ */
+class BatchRevertedError extends Error {
+    constructor(revertError, message) {
+        super(message !== null && message !== void 0 ? message : `DepositFlow: the batch reverted${revertError ? ` with ${revertError}` : ''}`);
+        this.name = 'BatchRevertedError';
+        this.revertError = revertError;
+        // Keeps `instanceof` honest under a down-levelled build.
+        Object.setPrototypeOf(this, BatchRevertedError.prototype);
+    }
+}
 /** Generated agreements are valid for five minutes upstream. */
 const CONTRACT_TTL_MS = 5 * 60 * 1000;
 /** What a run without a spender, from either source, fails with. */
@@ -25174,9 +25199,43 @@ const INITIAL$1 = {
     stepIndex: 0,
     stepTotal: 4,
     approvalRequired: true,
+    batched: false,
     contract: null,
     failure: null,
 };
+const ERC20 = IERC20MetadataAbi__factory.createInterface();
+const LENDING_POOL_MANAGER = ILendingPoolManagerAbi__factory.createInterface();
+/**
+ * The batch path's two calls, encoded by the SDK so no consumer has to: the
+ * EXACT-amount approve, then the very `requestDepositWithKyc` the default
+ * `deposit` port sends — `swapData` `'0x'`, no value. Both read `amount` from
+ * the same variable, so the batch cannot approve one figure and deposit
+ * another.
+ */
+function encodeDepositBatch(args) {
+    const { stableAsset, spender, input, depositData, kyc } = args;
+    return [
+        {
+            to: stableAsset,
+            data: ERC20.encodeFunctionData('approve', [spender, input.amount]),
+        },
+        {
+            to: spender,
+            data: LENDING_POOL_MANAGER.encodeFunctionData('requestDepositWithKyc', [
+                input.poolId,
+                input.trancheId,
+                input.amount,
+                '0x',
+                input.fixedTermConfigId,
+                depositData,
+                {
+                    blockExpiration: kyc.blockExpiration,
+                    signature: kyc.signature,
+                },
+            ]),
+        },
+    ];
+}
 /** 1-based badge position, with `approve` dropped when it is out of scope. */
 function stepIndexOf(step, approvalRequired) {
     const order = approvalRequired
@@ -25222,6 +25281,22 @@ function classifyRequest(err) {
     }
     return classifyWalletFailure('request', err);
 }
+/**
+ * A `depositBatch` rejection. A submitter that KNOWS the batch reverts says so
+ * with `BatchRevertedError`; anything else is read exactly as a direct
+ * deposit's throw is, so a non-wallet error can never become `cancelled`.
+ */
+function classifyBatch(err) {
+    if (err instanceof BatchRevertedError) {
+        return {
+            step: 'request',
+            reason: 'reverted',
+            revertError: err.revertError,
+            error: err,
+        };
+    }
+    return classifyRequest(err);
+}
 // ---------------------------------------------------------------------------
 // The flow
 // ---------------------------------------------------------------------------
@@ -25248,8 +25323,15 @@ class DepositFlow extends Flow {
          * A stale token simply is not the current generation.
          */
         this._acceptingFor = null;
+        /**
+         * The batch path's authorisation handshake. Same shape and lifetime as
+         * `_accept`: the run parks on it, `authoriseTransfer`, `declineTransfer`
+         * and `reset` settle it, and it is cleared the moment it settles.
+         */
+        this._authorise = null;
         this._ttlMs = (_a = opts === null || opts === void 0 ? void 0 : opts.contractTtlMs) !== null && _a !== void 0 ? _a : CONTRACT_TTL_MS;
         this._defaultSpender = opts === null || opts === void 0 ? void 0 : opts.spender;
+        this._stableAsset = opts === null || opts === void 0 ? void 0 : opts.stableAsset;
         // Called through the ports object, never captured off it: a consumer
         // whose clock is a method on its own object keeps its `this`.
         this._now = () => { var _a, _b; return (_b = (_a = _ports.now) === null || _a === void 0 ? void 0 : _a.call(_ports)) !== null && _b !== void 0 ? _b : Date.now(); };
@@ -25311,6 +25393,33 @@ class DepositFlow extends Flow {
         this._accept = null;
         bridge.settle({ kind: 'declined' });
     }
+    /**
+     * Batch path: authorise the single transaction that approves and deposits,
+     * and resume the parked run. A no-op when nothing is parked on
+     * `awaiting-authorise`, so a double tap cannot submit twice.
+     *
+     * The batch has no wallet prompt per call, so this is the lender's
+     * explicit consent to the transfer — call it only from their action.
+     */
+    authoriseTransfer() {
+        const bridge = this._authorise;
+        if (!bridge)
+            return;
+        this._authorise = null;
+        bridge.settle({ kind: 'authorised' });
+    }
+    /**
+     * Batch path: refuse the transfer. The run ends on `error` with `{ step:
+     * 'request', reason: 'cancelled' }` and nothing is submitted. A no-op when
+     * nothing is parked on `awaiting-authorise`.
+     */
+    declineTransfer() {
+        const bridge = this._authorise;
+        if (!bridge)
+            return;
+        this._authorise = null;
+        bridge.settle({ kind: 'declined' });
+    }
     /** True only while THIS generation is waiting on the acceptance signature. */
     _isAccepting() {
         return (this._acceptingFor !== null &&
@@ -25322,6 +25431,9 @@ class DepositFlow extends Flow {
         this._accept = null;
         this._acceptingFor = null;
         bridge === null || bridge === void 0 ? void 0 : bridge.settle({ kind: 'abandoned' });
+        const authorise = this._authorise;
+        this._authorise = null;
+        authorise === null || authorise === void 0 ? void 0 : authorise.settle({ kind: 'abandoned' });
     }
     // -----------------------------------------------------------------------
     _run(input, token) {
@@ -25329,6 +25441,7 @@ class DepositFlow extends Flow {
             var _a;
             this._accept = null;
             this._acceptingFor = null;
+            this._authorise = null;
             const ports = this._ports;
             const owner = input.userAddress.toLowerCase();
             // 0. The spender, from the input or from the chain config the facade
@@ -25349,21 +25462,32 @@ class DepositFlow extends Flow {
             //    live, never cached: an exact-amount approval is fully consumed by
             //    the deposit it paid for, so a stale allowance is exactly the value
             //    that would wrongly skip the approve and revert the deposit.
-            let approvalRequired = true;
+            let allowanceShort = true;
             try {
                 const allowance = yield ports.readAllowance(owner, spender);
-                approvalRequired = allowance.lt(input.amount);
+                allowanceShort = allowance.lt(input.amount);
             }
             catch (_b) {
                 // A read failure is not a reason to skip an approval. Assume one is
                 // needed: the cost is a redundant approve, the alternative is a
                 // reverted deposit.
-                approvalRequired = true;
+                allowanceShort = true;
             }
             if (!this._store.isCurrent(token))
                 return;
+            // The path is chosen HERE, with the allowance, so the badge is right
+            // from the first state the lender sees. Batch only when there is an
+            // approval to fold in, a port to submit it, and a known token to
+            // approve on — never a guessed one. A batched run never enters the
+            // `approve` step, so every badge counts it as a three-step run.
+            const stableAsset = this._stableAsset;
+            const batched = allowanceShort &&
+                typeof ports.depositBatch === 'function' &&
+                !!stableAsset;
+            const approvalRequired = allowanceShort && !batched;
             // 2. Generate — sign the auth message.
-            this._store.patch(Object.assign({ approvalRequired, phase: 'generating-sign' }, badgeFor('generate', approvalRequired)), token);
+            this._store.patch(Object.assign({ approvalRequired,
+                batched, phase: 'generating-sign' }, badgeFor('generate', approvalRequired)), token);
             const timestamp = this._now();
             const signedMessage = buildAuthMessage(input, owner, timestamp);
             let signature;
@@ -25465,6 +25589,18 @@ class DepositFlow extends Flow {
                 });
                 return;
             }
+            if (batched && stableAsset) {
+                yield this._runBatch({
+                    token,
+                    input,
+                    owner,
+                    spender,
+                    stableAsset,
+                    depositData,
+                    contract,
+                });
+                return;
+            }
             // 6. Approve — the EXACT amount, never `MaxUint256`. House rule: an
             //    unlimited allowance outlives the deposit it was granted for, and a
             //    later exploit of the spender would drain a wallet that has long
@@ -25528,6 +25664,108 @@ class DepositFlow extends Flow {
             this._store.patch(Object.assign({ phase: 'success' }, badgeFor('request', approvalRequired)), token);
         });
     }
+    /**
+     * The batch path, from the accepted agreement to the receipt.
+     *
+     * 1. PARK on `awaiting-authorise`. A batch puts no wallet prompt in front
+     *    of each call, so the flow waits for an explicit authorisation before
+     *    any money moves. `declineTransfer()` ends it as `cancelled`.
+     * 2. Re-check the TTL: the lender may have idled on the authorisation as
+     *    long as they did on the agreement.
+     * 3. Only now fetch the KYC signature — it has a block expiration of its
+     *    own, and an authorisation left open must not spend it.
+     * 4. Encode both calls and hand them to `depositBatch`; then the receipt.
+     */
+    _runBatch(args) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const { token, input, owner, spender, stableAsset, depositData } = args;
+            const ports = this._ports;
+            // A batched run is a three-step run on every badge.
+            const approvalRequired = false;
+            // Every settler clears the handshake before settling it, so there is
+            // nothing to clear here — and clearing it anyway could drop the
+            // handshake of a NEWER run that `reset(); start()` already parked.
+            const outcome = yield new Promise((resolve) => {
+                this._authorise = { settle: resolve };
+                this._store.patch(Object.assign({ phase: 'awaiting-authorise' }, badgeFor('request', approvalRequired)), token);
+            });
+            if (!this._store.isCurrent(token))
+                return;
+            if (outcome.kind === 'declined') {
+                this._fail(token, approvalRequired, {
+                    step: 'request',
+                    reason: 'cancelled',
+                });
+                return;
+            }
+            if (outcome.kind !== 'authorised')
+                return;
+            if (this._now() > args.contract.timestamp + this._ttlMs) {
+                this._fail(token, approvalRequired, {
+                    step: 'request',
+                    reason: 'contract-expired',
+                });
+                return;
+            }
+            this._store.patch(Object.assign({ phase: 'request-sign' }, badgeFor('request', approvalRequired)), token);
+            // The consumer's backend, so `failed` — never `cancelled` — exactly as
+            // on the two-transaction path.
+            let kyc;
+            try {
+                const kycParams = yield ports.buildKycParams(owner);
+                kyc = yield ports.getKycSignature(kycParams);
+            }
+            catch (err) {
+                this._fail(token, approvalRequired, {
+                    step: 'request',
+                    reason: 'failed',
+                    error: err,
+                });
+                return;
+            }
+            if (!this._store.isCurrent(token))
+                return;
+            // Encoded from values a backend returned (the KYC signature), so a
+            // shape the coder refuses is a failure the consumer can render, not a
+            // rejection out of a `start()` that promises it has none.
+            let calls;
+            try {
+                calls = encodeDepositBatch({
+                    stableAsset,
+                    spender,
+                    input,
+                    depositData,
+                    kyc,
+                });
+            }
+            catch (err) {
+                this._fail(token, approvalRequired, {
+                    step: 'request',
+                    reason: 'failed',
+                    error: err,
+                });
+                return;
+            }
+            try {
+                // Called through the ports object, so a port that is a method
+                // keeps its `this`. Its presence decided the path; a consumer
+                // that removed it since gets a `failed`, not a crash.
+                if (typeof ports.depositBatch !== 'function') {
+                    throw new Error('DepositFlow: the depositBatch port is gone');
+                }
+                const tx = yield ports.depositBatch(calls);
+                this._store.patch(Object.assign({ phase: 'request-confirm' }, badgeFor('request', approvalRequired)), token);
+                yield tx.wait();
+            }
+            catch (err) {
+                this._fail(token, approvalRequired, classifyBatch(err));
+                return;
+            }
+            if (!this._store.isCurrent(token))
+                return;
+            this._store.patch(Object.assign({ phase: 'success' }, badgeFor('request', approvalRequired)), token);
+        });
+    }
     _fail(token, approvalRequired, failure) {
         this._store.patch(Object.assign({ phase: 'error', failure }, badgeFor(failure.step, approvalRequired)), token);
     }
@@ -25680,11 +25918,18 @@ class FlowsFacade {
      * an address whose only wrong value grants an approval to the wrong
      * contract.
      */
-    _spender) {
+    _spender, 
+    /**
+     * This chain's stable token address — the target of the batch path's
+     * approve. `undefined` for a hand-built config without `stableAsset`,
+     * in which case a run never batches: it does not guess a token.
+     */
+    _stableAsset) {
         this._deposits = _deposits;
         this._erc20 = _erc20;
         this._isReadOnly = _isReadOnly;
         this._spender = _spender;
+        this._stableAsset = _stableAsset;
     }
     /**
      * A deposit pipeline. `readAllowance`, `approve`, `deposit` and
@@ -25697,9 +25942,13 @@ class FlowsFacade {
      * delete the default it was meant to keep, and
      * `approve: sponsoredGas ? sponsoredApprove : undefined` is exactly how a
      * consumer writes a conditional override.
+     *
+     * `depositBatch` has NO default: how several calls become one atomic
+     * transaction is the application's business. Supplying it lets a run
+     * whose allowance is short approve and deposit in one batch.
      */
     deposit(ports, opts) {
-        var _a, _b, _c, _d, _e;
+        var _a, _b, _c, _d, _e, _f;
         return new DepositFlow({
             signMessage: ports.signMessage,
             generateContract: ports.generateContract,
@@ -25714,12 +25963,14 @@ class FlowsFacade {
                 return yield this._erc20().approve(spender, amount);
             })),
             deposit: (_d = ports.deposit) !== null && _d !== void 0 ? _d : ((params) => this._deposits.deposit(params)),
+            depositBatch: ports.depositBatch,
             now: ports.now,
         }, {
             contractTtlMs: opts === null || opts === void 0 ? void 0 : opts.contractTtlMs,
             // Per key here too, for the same reason the ports are: an
             // explicit `spender: undefined` must not delete the default.
             spender: (_e = opts === null || opts === void 0 ? void 0 : opts.spender) !== null && _e !== void 0 ? _e : this._spender,
+            stableAsset: (_f = opts === null || opts === void 0 ? void 0 : opts.stableAsset) !== null && _f !== void 0 ? _f : this._stableAsset,
         });
     }
     /**
@@ -26480,6 +26731,7 @@ class PortfolioFacade {
  */
 class Kasu {
     constructor(sdk, chainConfig, signerOrProvider, configOverrides) {
+        var _a;
         this._sdk = sdk;
         this._chainConfig = chainConfig;
         this._signerOrProvider = signerOrProvider;
@@ -26491,7 +26743,7 @@ class Kasu {
         const isReadOnly = !ethers.Signer.isSigner(signerOrProvider);
         this.deposits = new DepositsFacade(sdk.UserLending, chainConfig.chainId.toString(), isReadOnly);
         this.portfolio = new PortfolioFacade(sdk.DataService, sdk.UserLending, sdk.Portfolio);
-        this.flows = new FlowsFacade(this.deposits, () => erc20Of(chainConfig, signerOrProvider), isReadOnly, chainConfig.contracts.LendingPoolManager);
+        this.flows = new FlowsFacade(this.deposits, () => erc20Of(chainConfig, signerOrProvider), isReadOnly, chainConfig.contracts.LendingPoolManager, (_a = stableAssetOf(chainConfig)) === null || _a === void 0 ? void 0 : _a.address);
     }
     /**
      * Create a Kasu instance with built-in chain config.
@@ -27155,6 +27407,7 @@ function getTrancheDisplayName(trancheName, pool) {
 exports.APXIUM = APXIUM;
 exports.AU_ALPHA3 = AU_ALPHA3;
 exports.AU_MIN_CUMULATIVE_BY_STABLE = AU_MIN_CUMULATIVE_BY_STABLE;
+exports.BatchRevertedError = BatchRevertedError;
 exports.CHAIN_CONFIGS = CHAIN_CONFIGS;
 exports.CLEARING_WINDOW_SECONDS = CLEARING_WINDOW_SECONDS;
 exports.CONTRACT_TTL_MS = CONTRACT_TTL_MS;