@kasufinance/kasu-sdk 2.7.1 → 2.10.0

package/src/flows/withdraw-flow.ts

@@ -1,8 +1,10 @@
 import { BigNumber } from 'ethers';
 
-import { classifyWalletFailure } from '../domain/wallet-errors';
+import { SponsoredCall } from '../domain/sponsored-calls';
+import { classifyWalletFailure, isUserRejected } from '../domain/wallet-errors';
 import { KycParams } from '../facade/types';
 
+import { BatchRevertedError, BatchSubmissionError } from './batch-errors';
 import { Flow } from './flow';
 import { WaitableTransaction } from './observable';
 
@@ -29,6 +31,28 @@ import { WaitableTransaction } from './observable';
  * flow.subscribe(render);
  * await flow.start({ poolId, trancheId, amount: 'max', userAddress });
  * ```
+ *
+ * ## The sponsored path (2.10.0)
+ *
+ * Supply `submitCall` and the run never touches `withdraw` / `withdrawMax`:
+ * it encodes the ONE `requestWithdrawal` call itself (`encodeWithdrawal`,
+ * which `kasu.flows.withdraw()` defaults to `kasu.calls.requestWithdrawal`)
+ * and hands it to the port, whose `wait()` settles it. `state.sponsored` says
+ * which path this flow runs, from its first state.
+ *
+ * A submitted call's outcome is read with the batch path's taxonomy, and at
+ * its word: `BatchRevertedError` → `reverted`; `BatchSubmissionError` → its
+ * own outcome (`failed`, `pending`, `already-submitted`); a WALLET rejection
+ * (`isUserRejected`) thrown by `submitCall` itself → `cancelled`, exactly as a
+ * raw `depositBatch` throw is read — the lender declined to sign, nothing was
+ * posted; ANY other throw from `submitCall`, and every throw from `wait()`
+ * that is not one of the typed errors, → `pending`. The SDK cannot know
+ * whether an unrecognised error left before or after the call was accepted,
+ * and calling that `failed` invites a second withdrawal request.
+ * `submitSponsoredCall` is the port body that already speaks this; note that
+ * a rejection raised INSIDE its `post` is wrapped as `pending` (the 2.9.0
+ * rule for `post`), so sign in `submitCall` before calling it when the app
+ * wants `cancelled`.
  */
 
 // ---------------------------------------------------------------------------
@@ -52,7 +76,31 @@ export type WithdrawStep = 'kyc' | 'request';
 
 export type WithdrawFailure =
     | { step: WithdrawStep; reason: 'cancelled' }
-    | { step: WithdrawStep; reason: 'failed'; error: unknown };
+    | { step: WithdrawStep; reason: 'failed'; error: unknown }
+    | {
+          /**
+           * Sponsored path only: the call is KNOWN to revert (or reverted) —
+           * nothing was requested. `revertError` is the contract's error name
+           * (`'CannotProcessRequestIfClearingIsPending'`,
+           * `'InsufficientSharesBalance'`, …) or `''`.
+           */
+          step: 'request';
+          reason: 'reverted';
+          revertError: string;
+          error: unknown;
+      }
+    | {
+          /**
+           * Sponsored path only — NOT failures. `pending`: the call was, or
+           * may have been, accepted and nothing proves whether it ran; never
+           * render it as a failure, which invites a second request.
+           * `already-submitted`: the port refused it because an earlier one
+           * was proven.
+           */
+          step: 'request';
+          reason: 'pending' | 'already-submitted';
+          error: unknown;
+      };
 
 // ---------------------------------------------------------------------------
 // Ports, input, state
@@ -63,9 +111,7 @@ export interface WithdrawPorts {
      * Build the Nexera KYC params for the pre-check. Defaults to
      * `kasu.deposits.buildKycParams`, exactly as the deposit flow's does.
      */
-    buildKycParams?(
-        userAddress: `0x${string}`,
-    ): KycParams | Promise<KycParams>;
+    buildKycParams?(userAddress: `0x${string}`): KycParams | Promise<KycParams>;
     /**
      * Exchange those params for a signature at the consumer's own backend, and
      * so verify the lender's KYC BEFORE the wallet is opened — a lapsed one
@@ -90,6 +136,33 @@ export interface WithdrawPorts {
         trancheId: string,
         userAddress: string,
     ): Promise<WaitableTransaction>;
+    /**
+     * Submit ONE encoded call through a sponsored submitter (a gas-sponsoring
+     * relay) and return a handle whose `wait()` settles it. Supplying it is
+     * what turns the sponsored path on; it has no default, because how a call
+     * is relayed is the application's business. Post `call.kind` and
+     * `[call.call]` exactly as given — `submitSponsoredCall` does this, with
+     * the polling and the receipt proof.
+     *
+     * Throw `BatchRevertedError` for a known revert and
+     * `BatchSubmissionError(code, 'failed')` ONLY when nothing was sent. A
+     * wallet rejection thrown here (the lender declined to sign the call,
+     * `isUserRejected`) is `cancelled`; any other throw — here or from
+     * `wait()` — is read as `pending`.
+     */
+    submitCall?(call: SponsoredCall): Promise<WaitableTransaction>;
+    /**
+     * Encode the withdrawal for `submitCall`. Defaults (in
+     * `kasu.flows.withdraw()`) to `kasu.calls.requestWithdrawal`, which
+     * converts the amount to shares exactly as `withdraw` / `withdrawMax`
+     * do. Only read when `submitCall` is supplied.
+     */
+    encodeWithdrawal?(params: {
+        poolId: string;
+        trancheId: string;
+        amount: BigNumber | 'max';
+        userAddress: string;
+    }): Promise<SponsoredCall>;
 }
 
 export interface WithdrawFlowInput {
@@ -99,10 +172,11 @@ export interface WithdrawFlowInput {
      * The amount in BASE units, or the literal `'max'`.
      *
      * `'max'` is not "the balance as I last read it": it routes to the
-     * all-shares contract call, which resolves the balance on chain at
-     * execution. Deciding max-ness from a number the consumer read a moment ago
-     * is how dust gets stranded in a tranche, so the decision is a code, made
-     * by the consumer, and carried here intact.
+     * all-shares request, whose share count is the lender's tranche
+     * `balanceOf`, read by the SDK at submission rather than converted from
+     * an asset figure. Deciding max-ness from a number the consumer read a
+     * moment ago is how dust gets stranded in a tranche, so the decision is a
+     * code, made by the consumer, and carried here intact.
      */
     amount: BigNumber | 'max';
     userAddress: `0x${string}`;
@@ -113,6 +187,11 @@ export interface WithdrawState {
     step: WithdrawStep | null;
     /** True when this run routed through the all-shares call. */
     isMax: boolean;
+    /**
+     * True when this flow submits through `submitCall` — fixed when the flow
+     * is built, so it is right from the first state, `idle` included.
+     */
+    sponsored: boolean;
     failure: WithdrawFailure | null;
 }
 
@@ -120,6 +199,7 @@ const INITIAL: WithdrawState = {
     phase: 'idle',
     step: null,
     isMax: false,
+    sponsored: false,
     failure: null,
 };
 
@@ -127,13 +207,57 @@ const INITIAL: WithdrawState = {
 export const NO_KYC_PARAMS_MESSAGE =
     'WithdrawFlow: getKycSignature was supplied without buildKycParams; build the flow with kasu.flows.withdraw() or pass both';
 
+/** What a sponsored run with no `encodeWithdrawal` to call fails with. */
+export const NO_WITHDRAWAL_ENCODER_MESSAGE =
+    'WithdrawFlow: submitCall was supplied without encodeWithdrawal; build the flow with kasu.flows.withdraw() or pass both';
+
+/** What a sponsored run fails with when the encoder returned another kind of call. */
+export const NOT_A_WITHDRAWAL_CALL_MESSAGE =
+    'WithdrawFlow: encodeWithdrawal returned a call that is not a withdrawal';
+
+/**
+ * A `submitCall` / `wait()` rejection, read with the batch path's taxonomy. A
+ * submission outcome is taken at its word FIRST — never through the wallet
+ * classifier, which would read a relay's "request rejected" as the lender's
+ * own doing. Then, from `submitCall` only, a wallet rejection is `cancelled`:
+ * the lender declined to sign and nothing was posted — the same reading a raw
+ * `depositBatch` throw gets. From `wait()` the call has already left, so a
+ * rejection-worded error there is as ambiguous as any other. Everything
+ * unrecognised is `pending`: it may have left.
+ */
+function classifySponsored(
+    err: unknown,
+    from: 'submit' | 'wait',
+): WithdrawFailure {
+    if (err instanceof BatchSubmissionError) {
+        return err.outcome === 'failed'
+            ? { step: 'request', reason: 'failed', error: err }
+            : { step: 'request', reason: err.outcome, error: err };
+    }
+    if (err instanceof BatchRevertedError) {
+        return {
+            step: 'request',
+            reason: 'reverted',
+            revertError: err.revertError,
+            error: err,
+        };
+    }
+    if (from === 'submit' && isUserRejected(err)) {
+        return { step: 'request', reason: 'cancelled' };
+    }
+    return { step: 'request', reason: 'pending', error: err };
+}
+
 // ---------------------------------------------------------------------------
 // The flow
 // ---------------------------------------------------------------------------
 
 export class WithdrawFlow extends Flow<WithdrawState, WithdrawFlowInput> {
     constructor(private readonly _ports: WithdrawPorts) {
-        super(INITIAL);
+        super({
+            ...INITIAL,
+            sponsored: typeof _ports.submitCall === 'function',
+        });
     }
 
     protected async _run(
@@ -172,6 +296,11 @@ export class WithdrawFlow extends Flow<WithdrawState, WithdrawFlowInput> {
             if (!this._store.isCurrent(token)) return;
         }
 
+        if (ports.submitCall) {
+            await this._runSponsored(input, token, isMax);
+            return;
+        }
+
         // 2. The submission. This one IS a wallet call, so it keeps the
         //    `cancelled` / `failed` split.
         this._store.patch(
@@ -207,4 +336,84 @@ export class WithdrawFlow extends Flow<WithdrawState, WithdrawFlowInput> {
 
         this._store.patch({ phase: 'success' }, token);
     }
+
+    /**
+     * 2'. The sponsored submission: encode, re-check the run, submit, settle.
+     *
+     * The encode reads the chain (the shares), so a run abandoned during it
+     * must stop BEFORE `submitCall` — nothing has been sent yet, and an
+     * abandoned run must never send. A throw while encoding is `failed`:
+     * nothing left. After `submitCall` is called, only the taxonomy decides.
+     */
+    private async _runSponsored(
+        input: WithdrawFlowInput,
+        token: number,
+        isMax: boolean,
+    ): Promise<void> {
+        const ports = this._ports;
+        // Only reached when `submitCall` is supplied; narrows it for below.
+        if (!ports.submitCall) return;
+        this._store.patch(
+            { phase: 'request-sign', step: 'request', isMax },
+            token,
+        );
+
+        let call: SponsoredCall;
+        try {
+            if (!ports.encodeWithdrawal) {
+                throw new Error(NO_WITHDRAWAL_ENCODER_MESSAGE);
+            }
+            call = await ports.encodeWithdrawal({
+                poolId: input.poolId,
+                trancheId: input.trancheId,
+                amount: input.amount,
+                userAddress: input.userAddress,
+            });
+            if (
+                (call as Partial<SponsoredCall> | null)?.kind !== 'withdrawal'
+            ) {
+                throw new Error(NOT_A_WITHDRAWAL_CALL_MESSAGE);
+            }
+        } catch (err) {
+            this._store.patch(
+                {
+                    phase: 'error',
+                    failure: { step: 'request', reason: 'failed', error: err },
+                },
+                token,
+            );
+            return;
+        }
+        if (!this._store.isCurrent(token)) return;
+
+        let tx: WaitableTransaction;
+        try {
+            tx = await ports.submitCall(call);
+        } catch (err) {
+            this._store.patch(
+                { phase: 'error', failure: classifySponsored(err, 'submit') },
+                token,
+            );
+            return;
+        }
+        // The call has left. A run abandoned meanwhile stops HERE, without
+        // `wait()`: nothing it could learn would be published, and a sponsored
+        // `wait()` is minutes of polling against the submitter, not a cheap
+        // receipt read. The submission itself cannot be taken back.
+        if (!this._store.isCurrent(token)) return;
+        this._store.patch({ phase: 'request-confirm' }, token);
+
+        try {
+            await tx.wait();
+        } catch (err) {
+            this._store.patch(
+                { phase: 'error', failure: classifySponsored(err, 'wait') },
+                token,
+            );
+            return;
+        }
+        if (!this._store.isCurrent(token)) return;
+
+        this._store.patch({ phase: 'success' }, token);
+    }
 }

package/src/services/DataService/queries.ts

@@ -53,6 +53,7 @@ export const getPoolOverviewQuery = (ids?: string[]): string => gql`
                         fixedTermDepositStatus
                         fixedTermDepositAllowlist{
                             id
+                            isAllowlisted
                             user{
                                 id
                             }

package/src/services/UserLending/user-lending.ts

@@ -278,17 +278,50 @@ export class UserLending {
         );
     }
 
-    async requestWithdrawalInAsset(
-        lendingPool: string,
+    /**
+     * The tranche shares a withdrawal of `assetAmount` requests — the
+     * tranche's own `convertToShares`, read now. `requestWithdrawalInAsset`
+     * and the sponsored `kasu.calls.requestWithdrawal` both use this, so the
+     * two paths cannot convert differently.
+     */
+    async getWithdrawalSharesForAssets(
         tranche: string,
         assetAmount: BigNumberish,
-    ): Promise<ContractTransaction> {
+    ): Promise<BigNumber> {
         const trancheContract: ILendingPoolTrancheAbi =
             ILendingPoolTrancheAbi__factory.connect(
                 tranche,
                 this._signerOrProvider,
             );
-        const shareAmount = await trancheContract.convertToShares(assetAmount);
+        return await trancheContract.convertToShares(assetAmount);
+    }
+
+    /**
+     * Every tranche share `user` holds — what a max withdrawal requests
+     * (`balanceOf(user)` on the tranche, read now). Shared by
+     * `requestWithdrawalMax` and the sponsored `kasu.calls.requestWithdrawal`.
+     */
+    async getWithdrawalSharesMax(
+        tranche: string,
+        user: string,
+    ): Promise<BigNumber> {
+        const trancheContract: ILendingPoolTrancheAbi =
+            ILendingPoolTrancheAbi__factory.connect(
+                tranche,
+                this._signerOrProvider,
+            );
+        return await trancheContract['balanceOf(address)'](user);
+    }
+
+    async requestWithdrawalInAsset(
+        lendingPool: string,
+        tranche: string,
+        assetAmount: BigNumberish,
+    ): Promise<ContractTransaction> {
+        const shareAmount = await this.getWithdrawalSharesForAssets(
+            tranche,
+            assetAmount,
+        );
 
         return await this._lendingPoolManagerAbi.requestWithdrawal(
             lendingPool,
@@ -311,12 +344,7 @@ export class UserLending {
         tranche: string,
         user: string,
     ): Promise<ContractTransaction> {
-        const trancheContract: ILendingPoolTrancheAbi =
-            ILendingPoolTrancheAbi__factory.connect(
-                tranche,
-                this._signerOrProvider,
-            );
-        const userShares = await trancheContract['balanceOf(address)'](user);
+        const userShares = await this.getWithdrawalSharesMax(tranche, user);
 
         return await this._lendingPoolManagerAbi.requestWithdrawal(
             lendingPool,