@kasufinance/kasu-sdk 2.8.0 → 2.10.1

package/src/flows/deposit-flow.ts

@@ -16,6 +16,7 @@ import {
 } from '../domain/wallet-errors';
 import { DepositParams, KycParams } from '../facade/types';
 
+import { BatchRevertedError, BatchSubmissionError } from './batch-errors';
 import { Flow } from './flow';
 import { WaitableTransaction } from './observable';
 
@@ -167,7 +168,19 @@ export type DepositFailure =
           revertError: string;
           error: unknown;
       }
-    | { step: 'request'; reason: 'contract-expired' };
+    | { 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;
+      };
 
 // ---------------------------------------------------------------------------
 // Ports
@@ -184,38 +197,9 @@ export interface BatchCall {
     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 class BatchRevertedError extends Error {
-    readonly revertError: string;
-
-    constructor(revertError: string, message?: string) {
-        super(
-            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);
-    }
-}
+// `BatchRevertedError` lives in `./batch-errors` beside the submission
+// errors, and is re-exported here so every existing import keeps working.
+export { BatchRevertedError };
 
 /** What the KYC signing service hands back. */
 export interface KycSignature {
@@ -604,6 +588,16 @@ function classifyRequest(err: unknown): DepositFailure {
  * deposit's throw is, so a non-wallet error can never become `cancelled`.
  */
 function classifyBatch(err: unknown): DepositFailure {
+    // A submission outcome is read FIRST and taken at its word. It must never
+    // reach the revert-data walk below: that walk follows `cause`, and an
+    // ambiguous outcome whose cause happens to carry revert bytes would read
+    // as `reverted` or `insufficient-balance` — "nothing was deposited, try
+    // again" — on a batch that may have moved the money.
+    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',

package/src/flows/index.ts

@@ -10,12 +10,38 @@
  * Every application drove its own copy of the deposit pipeline before this, and
  * the copies had already started to differ.
  */
+export {
+    BatchPendingError,
+    BatchRevertedError,
+    batchOutcomeOf,
+    BatchSubmissionError,
+    isDefinitivelyNotSubmitted,
+} from './batch-errors';
+export type { BatchSubmissionOutcome } from './batch-errors';
+
+export {
+    checkBatchOutcome,
+    DEFAULT_BATCH_POLLING_POLICY,
+    submitBatch,
+    submitSponsoredCall,
+} from './batch-submission';
+export type {
+    BatchPollingPolicy,
+    BatchStatusRead,
+    BatchSubmission,
+    BatchSubmissionPorts,
+    ExecutedCall,
+    ProvenBatch,
+    SponsoredCallSubmission,
+    SponsoredCallSubmissionPorts,
+    SubmitBatchCall,
+} from './batch-submission';
+
 export { Flow } from './flow';
 export { FlowStore } from './observable';
 export type { WaitableTransaction } from './observable';
 
 export {
-    BatchRevertedError,
     CONTRACT_TTL_MS,
     DepositFlow,
     INVALID_ACCEPTANCE_SIGNATURE_MESSAGE,
@@ -38,7 +64,12 @@ export type {
     LoanAgreementRequest,
 } from './deposit-flow';
 
-export { NO_KYC_PARAMS_MESSAGE, WithdrawFlow } from './withdraw-flow';
+export {
+    NO_KYC_PARAMS_MESSAGE,
+    NO_WITHDRAWAL_ENCODER_MESSAGE,
+    NOT_A_WITHDRAWAL_CALL_MESSAGE,
+    WithdrawFlow,
+} from './withdraw-flow';
 export type {
     WithdrawFailure,
     WithdrawFlowInput,

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/Portfolio/portfolio.ts

@@ -113,6 +113,20 @@ export class Portfolio {
                     investedAmount * parseFloat(tranche.interestRate);
 
                 for (const fixedDeposits of tranche.fixedLoans) {
+                    // A matured lock's principal is already inside
+                    // `investedAmount`: getPortfolioLendingData subtracts only
+                    // the LOCKED loans from the tranche balance. Its lifetime
+                    // yield is earned and stays counted (the tranche's own
+                    // lifetime had every lock's yield taken out), but its
+                    // amount must not be added to the investment, weekly or
+                    // APY sums a second time.
+                    if (!fixedDeposits.isLocked) {
+                        totalYieldEarned += parseFloat(
+                            fixedDeposits.yieldEarnings.lifetime,
+                        );
+                        continue;
+                    }
+
                     const ftdConfig = tranche.fixedTermConfig.find(
                         (ftd) => ftd.configId === fixedDeposits.configId,
                     );

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,