@kasufinance/kasu-sdk 2.6.0 → 2.7.0

package/src/domain/wallet-errors.ts

@@ -8,37 +8,125 @@
  * enumerated once here.
  *
  * Lifted from kasu-ui's `src/lib/web3/is-user-rejected.ts` and kasu-mobile's
- * `src/features/lending/lib/errors.ts`.
+ * `src/features/lending/lib/errors.ts` — and now the UNION of the two, so
+ * neither app has to keep a wrapper on top of this one.
  */
 
 /**
  * Did the lender reject the request in their wallet?
  *
- * Providers surface a rejection in different shapes:
+ * Providers surface a rejection in different shapes, and the union of them is
+ * the point of this function existing once:
  *   - MetaMask and most EIP-1193 wallets: `code: 4001`
+ *   - Coinbase Wallet and ethers v5: `code: 'ACTION_REJECTED'`
+ *   - viem: a `UserRejectedRequestError` name
  *   - WalletConnect and some Privy paths: `Error('User rejected the request')`
- *   - ethers v5 wraps it as `ACTION_REJECTED`
- *   - Coinbase Wallet sometimes: `code: 'ACTION_REJECTED'` as a string
+ *   - a provider error WRAPPED by another layer, carrying the real code and
+ *     message on a nested `error` — the shape Privy's embedded wallet
+ *     surfaces on Expo, where the outer object says nothing useful
+ *   - ethers' own `reason` field, which is often the only place the text lands
+ *   - a PLAIN OBJECT carrying `message`, which `String(err)` would read as
+ *     `"[object Object]"`
  *
- * This is kasu-ui's implementation verbatim. kasu-mobile's copy additionally
- * reads a nested `error.code` / `error.message`, an ethers `reason`, and the
- * words "request rejected" / "declined"; a consumer that needs those shapes
- * should keep its own check on top rather than assume they are covered here.
+ * Previously kasu-ui's implementation verbatim, with kasu-mobile keeping its
+ * own superset on top. That is precisely the drift this layer exists to stop —
+ * a rejection kasu-mobile recognised and kasu-ui did not was reported to the
+ * same lender as a failure on one app and a cancellation on the other. The
+ * union lives here; the mobile wrapper goes.
+ *
+ * ## The text is read for a SUBJECT, not for a keyword
+ *
+ * The words alone are not the signal. "Declined" and "request rejected" are
+ * also what a rate limiter, a risk engine and a KYC decision say, and those
+ * arrive wrapped in exactly the same envelope a wallet error does — ethers'
+ * `SERVER_ERROR` around `-32603` carries the upstream body on a nested
+ * `error.message`, so `{ error: { message: 'request rejected: rate limit
+ * exceeded' } }` is an RPC refusing to serve us, not a lender refusing to
+ * sign. Reporting one as the other tells a lender they cancelled something
+ * they never saw, and DROPS the real error on the floor.
+ *
+ * So a rejection is a machine-readable wallet code, or a sentence that names
+ * the party who did it: "user rejected", "declined by the user", "cancelled by
+ * the wallet". A bare "declined" is not a rejection, whatever else is on the
+ * envelope.
+ *
+ * Within that rule, being generous is the safe direction: calling a genuine
+ * fault a cancellation costs a lender one retry, while calling a deliberate
+ * rejection a failure sends them to support to report a bug that does not
+ * exist.
  */
 export function isUserRejected(err: unknown): boolean {
     if (!err) return false;
     if (typeof err === 'object') {
-        const code = (err as { code?: unknown }).code;
-        if (code === 4001 || code === 'ACTION_REJECTED') return true;
+        const e = err as {
+            code?: unknown;
+            error?: { code?: unknown } | null;
+        };
+        if (isRejectionCode(e.code)) return true;
+        // A wrapped provider error: the outer layer's code is its own, the
+        // inner one is the wallet's.
+        if (isRejectionCode(e.error?.code)) return true;
     }
-    const msg = err instanceof Error ? err.message : String(err);
-    const lower = msg.toLowerCase();
-    return (
-        lower.includes('user rejected') ||
-        lower.includes('user denied') ||
-        lower.includes('rejected the request') ||
-        lower.includes('action_rejected')
-    );
+    const lower = rejectionText(err).toLowerCase();
+    return USER_REJECTION_PATTERNS.some((pattern) => pattern.test(lower));
+}
+
+function isRejectionCode(code: unknown): boolean {
+    return code === 4001 || code === 'ACTION_REJECTED';
+}
+
+/**
+ * The wordings that name the wallet or the person at it.
+ *
+ * Each one carries a SUBJECT — the identifier a wallet library uses, or the
+ * verb with the party who performed it. That is what separates a lender
+ * pressing Reject from a server declining to answer, and it is why none of
+ * these is a bare "declined" or "rejected".
+ */
+const USER_REJECTION_PATTERNS: readonly RegExp[] = [
+    // Machine-readable markers that only a wallet layer emits, arriving as
+    // text because something in between stringified the error.
+    /action_rejected/,
+    /user_rejected/,
+    /userrejectedrequest/,
+    // "the user did it", in the orders the wallets write it.
+    /user\s+(?:has\s+)?(?:rejected|denied|declined|refused|cancell?ed)/,
+    /(?:rejected|denied|declined|refused|cancell?ed)\s+by\s+(?:the\s+)?(?:user|wallet|signer|owner)/,
+    // The wallet as the subject, which is how some embedded wallets word it.
+    /(?:wallet|signer)\s+(?:rejected|denied|declined|refused)/,
+];
+
+/**
+ * Every place a wallet might have put the words: the message, ethers' `reason`,
+ * the error's `name` (viem puts the whole signal there), and a wrapped error's
+ * own three. Joined rather than picked, because which one carries the text
+ * depends on how many layers wrapped it.
+ *
+ * A separator is used rather than a bare space: two fields must not be able to
+ * form a phrase across the join that neither of them said.
+ */
+function rejectionText(err: unknown): string {
+    if (typeof err !== 'object' || err === null) return String(err);
+    const e = err as {
+        message?: unknown;
+        reason?: unknown;
+        name?: unknown;
+        error?: {
+            message?: unknown;
+            reason?: unknown;
+            name?: unknown;
+        } | null;
+    };
+    return [
+        e.message,
+        e.reason,
+        e.name,
+        e.error?.message,
+        e.error?.reason,
+        e.error?.name,
+    ]
+        .filter((part): part is string => typeof part === 'string')
+        .join(' | ');
 }
 
 /**
@@ -54,3 +142,32 @@ export function isUnpredictableGas(err: unknown): boolean {
     if (!err || typeof err !== 'object') return false;
     return (err as { code?: unknown }).code === 'UNPREDICTABLE_GAS_LIMIT';
 }
+
+/** A step that failed, as a code plus whether the lender chose it. */
+export type WalletFailure<Step> =
+    | { step: Step; reason: 'cancelled' }
+    | { step: Step; reason: 'failed'; error: unknown };
+
+/**
+ * The `cancelled` / `failed` split, for a WALLET call on any step of any flow.
+ *
+ * A lender who pressed Reject is not a fault. Reporting one as the other is
+ * how a support queue fills with people who did exactly what they meant to.
+ *
+ * Generic in the step so both flows share one implementation — it was
+ * duplicated byte-for-byte in each of them, which is the same drift this
+ * layer exists to stop, one level up.
+ *
+ * Only pass it an error a WALLET produced. An HTTP port's throw is always a
+ * `failed`: the lender's wallet was not involved in it, so a backend that
+ * happens to word a refusal "declined" must never be shown to them as
+ * something they did.
+ */
+export function classifyWalletFailure<Step>(
+    step: Step,
+    err: unknown,
+): WalletFailure<Step> {
+    return isUserRejected(err)
+        ? { step, reason: 'cancelled' }
+        : { step, reason: 'failed', error: err };
+}

package/src/facade/deposits.ts

@@ -2,6 +2,7 @@ import { ContractTransaction } from 'ethers';
 
 import { UserLending } from '../services/UserLending/user-lending';
 
+import { READ_ONLY_MESSAGE } from './read-only';
 import { DepositParams, KycParams, WithdrawParams } from './types';
 
 /**
@@ -32,9 +33,7 @@ export class DepositsFacade {
      */
     private assertWritable(): void {
         if (this._isReadOnly) {
-            throw new Error(
-                'Kasu: this instance is read-only; call kasu.connect(signer) first',
-            );
+            throw new Error(READ_ONLY_MESSAGE);
         }
     }
 

package/src/facade/flows.ts

@@ -0,0 +1,172 @@
+import { BigNumber } from 'ethers';
+
+import type { IERC20MetadataAbi } from '../contracts';
+import {
+    DepositFlow,
+    DepositFlowOptions,
+    DepositPorts,
+    WaitableTransaction,
+    WithdrawFlow,
+    WithdrawPorts,
+} from '../flows';
+
+import { DepositsFacade } from './deposits';
+import { READ_ONLY_MESSAGE } from './read-only';
+import { KycParams } from './types';
+
+/**
+ * The ports a consumer MUST supply for a deposit, plus optional overrides for
+ * the ones the SDK can serve itself.
+ *
+ * The three required ones all reach the application's own backend or wallet:
+ * the SDK has no opinion on how a lender signs, which proxy the agreements
+ * service sits behind, or where the KYC signature is fetched — and it must not
+ * learn any of them, because it is a public package.
+ */
+export type DepositFlowPortOverrides = Pick<
+    DepositPorts,
+    'signMessage' | 'generateContract' | 'getKycSignature'
+> &
+    Partial<DepositPorts>;
+
+/**
+ * Every withdraw port has an SDK default except `getKycSignature`, which has
+ * no default at all and which turns the KYC pre-check on by being supplied.
+ */
+export type WithdrawFlowPortOverrides = Partial<WithdrawPorts>;
+
+/**
+ * Builds `DepositFlow` / `WithdrawFlow` instances wired to THIS Kasu instance:
+ * its chain's stable token, its `LendingPoolManager`, its signer.
+ *
+ * ```ts
+ * const flow = kasu.connect(signer).flows.deposit({
+ *   signMessage: (m) => signer.signMessage(m),
+ *   generateContract: (req) => postToMyProxy(req),
+ *   getKycSignature: (p) => postToMyBackend(p),
+ * });
+ * ```
+ *
+ * A flow built from a read-only instance constructs fine and reads fine — the
+ * write ports throw `READ_ONLY_MESSAGE` when the run reaches them, exactly as
+ * `kasu.deposits.deposit` does. Constructing is not the mistake; submitting is.
+ *
+ * It holds the `DepositsFacade` and NOTHING the facade already owns: no
+ * `UserLending`, no chain id, no signer. Two paths to one behaviour is how the
+ * KYC params a flow built came to differ from the ones `kasu.deposits`
+ * built — the same class of drift the flows themselves exist to end.
+ */
+export class FlowsFacade {
+    constructor(
+        private readonly _deposits: DepositsFacade,
+        /**
+         * The chain's stable token, bound to whatever the Kasu instance holds.
+         * A factory rather than a contract: it is one `new Contract`, and a
+         * cached binding would outlive the config it was built from.
+         */
+        private readonly _erc20: () => IERC20MetadataAbi,
+        /** The read-only flag `Kasu` already computed — never re-derived here. */
+        private readonly _isReadOnly: boolean,
+        /**
+         * The ERC-20 spender every deposit run approves: this chain's
+         * `LendingPoolManager`, which is the only contract the default deposit
+         * port calls. Passed to the flow so a consumer never has to hand-wire
+         * an address whose only wrong value grants an approval to the wrong
+         * contract.
+         */
+        private readonly _spender: string,
+    ) {}
+
+    /**
+     * A deposit pipeline. `readAllowance`, `approve`, `deposit` and
+     * `buildKycParams` default to the SDK's own implementations; pass any of
+     * them to override (kasu-ui approves through its sponsored-gas path, for
+     * one).
+     *
+     * Each default is applied per key with `??`, not by spreading `ports` over
+     * them: `{ ...defaults, ...ports }` lets an EXPLICITLY undefined value
+     * delete the default it was meant to keep, and
+     * `approve: sponsoredGas ? sponsoredApprove : undefined` is exactly how a
+     * consumer writes a conditional override.
+     */
+    deposit(
+        ports: DepositFlowPortOverrides,
+        opts?: DepositFlowOptions,
+    ): DepositFlow {
+        return new DepositFlow(
+            {
+                signMessage: ports.signMessage,
+                generateContract: ports.generateContract,
+                getKycSignature: ports.getKycSignature,
+                buildKycParams:
+                    ports.buildKycParams ??
+                    ((userAddress: `0x${string}`): KycParams =>
+                        this._deposits.buildKycParams(userAddress)),
+                readAllowance:
+                    ports.readAllowance ??
+                    ((owner: string, spender: string): Promise<BigNumber> =>
+                        this._erc20().allowance(owner, spender)),
+                approve:
+                    ports.approve ??
+                    (async (
+                        spender: string,
+                        amount: BigNumber,
+                    ): Promise<WaitableTransaction> => {
+                        this._assertWritable();
+                        // The EXACT amount the flow asked for. Nothing here
+                        // rounds it up, and nothing here substitutes
+                        // MaxUint256.
+                        return await this._erc20().approve(spender, amount);
+                    }),
+                deposit:
+                    ports.deposit ??
+                    ((params): Promise<WaitableTransaction> =>
+                        this._deposits.deposit(params)),
+                now: ports.now,
+            },
+            {
+                contractTtlMs: opts?.contractTtlMs,
+                // Per key here too, for the same reason the ports are: an
+                // explicit `spender: undefined` must not delete the default.
+                spender: opts?.spender ?? this._spender,
+            },
+        );
+    }
+
+    /**
+     * A withdrawal pipeline. Both write ports and `buildKycParams` default to
+     * this instance; supplying `getKycSignature` turns the KYC pre-check on.
+     * Defaults are applied per key, for the reason `deposit()` gives.
+     */
+    withdraw(ports: WithdrawFlowPortOverrides = {}): WithdrawFlow {
+        return new WithdrawFlow({
+            buildKycParams:
+                ports.buildKycParams ??
+                ((userAddress: `0x${string}`): KycParams =>
+                    this._deposits.buildKycParams(userAddress)),
+            getKycSignature: ports.getKycSignature,
+            withdraw:
+                ports.withdraw ??
+                ((params): Promise<WaitableTransaction> =>
+                    this._deposits.withdraw({
+                        poolId: params.poolId,
+                        trancheId: params.trancheId,
+                        amount: params.amount,
+                    })),
+            withdrawMax:
+                ports.withdrawMax ??
+                ((
+                    poolId: string,
+                    trancheId: string,
+                    userAddress: string,
+                ): Promise<WaitableTransaction> =>
+                    this._deposits.withdrawMax(poolId, trancheId, userAddress)),
+        });
+    }
+
+    private _assertWritable(): void {
+        if (this._isReadOnly) {
+            throw new Error(READ_ONLY_MESSAGE);
+        }
+    }
+}

package/src/facade/index.ts

@@ -5,6 +5,14 @@ export { Kasu } from './kasu';
 export { StrategiesFacade } from './strategies';
 export { DepositsFacade } from './deposits';
 export { PortfolioFacade } from './user-portfolio';
+export { FlowsFacade } from './flows';
+export type {
+    DepositFlowPortOverrides,
+    WithdrawFlowPortOverrides,
+} from './flows';
+
+// The one refusal every write path shares
+export { READ_ONLY_MESSAGE } from './read-only';
 
 // Chain configurations
 export { CHAIN_CONFIGS } from './chain-configs';

package/src/facade/kasu.ts

@@ -1,11 +1,14 @@
 import { Provider } from '@ethersproject/providers';
 import { providers, Signer } from 'ethers';
 
+import { IERC20MetadataAbi__factory } from '../contracts';
+import type { IERC20MetadataAbi } from '../contracts';
 import { KasuSdk } from '../kasu-sdk';
 import { SdkConfig, SdkConfigOptions } from '../sdk-config';
 
 import { CHAIN_CONFIGS } from './chain-configs';
 import { DepositsFacade } from './deposits';
+import { FlowsFacade } from './flows';
 import { StrategiesFacade } from './strategies';
 import {
     ChainConfigEntry,
@@ -18,8 +21,9 @@ import { PortfolioFacade } from './user-portfolio';
 /**
  * High-level entry point for external integrators.
  *
- * Provides three domain facades — `strategies`, `deposits`, `portfolio` — and
- * exposes the underlying `KasuSdk` services via `.services` for power-users.
+ * Provides four domain facades — `strategies`, `deposits`, `portfolio`,
+ * `flows` — and exposes the underlying `KasuSdk` services via `.services` for
+ * power-users.
  *
  * ```ts
  * import { Kasu } from '@kasufinance/kasu-sdk';
@@ -43,6 +47,8 @@ export class Kasu {
     public readonly deposits: DepositsFacade;
     /** User positions, yields, transaction history. */
     public readonly portfolio: PortfolioFacade;
+    /** Headless deposit / withdraw state machines. */
+    public readonly flows: FlowsFacade;
 
     private readonly _sdk: KasuSdk;
     private readonly _chainConfig: ChainConfigEntry;
@@ -70,10 +76,15 @@ export class Kasu {
             sdk.UserLending,
         );
 
+        // Derived ONCE and handed to every facade that needs it. Each of them
+        // re-deriving `Signer.isSigner` is how two facades come to disagree
+        // about whether the same instance can write.
+        const isReadOnly = !Signer.isSigner(signerOrProvider);
+
         this.deposits = new DepositsFacade(
             sdk.UserLending,
             chainConfig.chainId.toString(),
-            !Signer.isSigner(signerOrProvider),
+            isReadOnly,
         );
 
         this.portfolio = new PortfolioFacade(
@@ -81,6 +92,13 @@ export class Kasu {
             sdk.UserLending,
             sdk.Portfolio,
         );
+
+        this.flows = new FlowsFacade(
+            this.deposits,
+            () => erc20Of(chainConfig, signerOrProvider),
+            isReadOnly,
+            chainConfig.contracts.LendingPoolManager,
+        );
     }
 
     /**
@@ -241,6 +259,28 @@ function rpcUrlsOf(chainConfig: ChainConfigEntry): string[] {
     return (chainConfig as { rpcUrls?: string[] }).rpcUrls ?? [];
 }
 
+/**
+ * The chain's stable token, bound to whatever this instance holds.
+ *
+ * Built per call rather than cached: it is one `new Contract`, and a cached
+ * binding would outlive the signer a `connect()` replaced. A config with no
+ * `stableAsset` (a hand-written entry from before 2.5.0) throws here rather
+ * than inside ethers, naming the two ports that make the flow work without
+ * one.
+ */
+function erc20Of(
+    chainConfig: ChainConfigEntry,
+    signerOrProvider: Provider | Signer,
+): IERC20MetadataAbi {
+    const address = stableAssetOf(chainConfig)?.address;
+    if (!address) {
+        throw new Error(
+            'Kasu: this chain config has no stableAsset; pass readAllowance and approve ports explicitly',
+        );
+    }
+    return IERC20MetadataAbi__factory.connect(address, signerOrProvider);
+}
+
 /**
  * The read-only provider used when the caller passes no `signerOrProvider`.
  *

package/src/facade/read-only.ts

@@ -0,0 +1,13 @@
+/**
+ * The refusal every write path shares when the instance holds a Provider
+ * rather than a Signer.
+ *
+ * One constant, because the message's job is to name the fix — `kasu.connect`
+ * — and three near-identical wordings across the facades would be three
+ * different pieces of advice for one problem. ethers' own
+ * "sending a transaction requires a signer" arrives several frames deeper,
+ * after the params have been encoded, and says nothing about how to get a
+ * signer onto THIS object.
+ */
+export const READ_ONLY_MESSAGE =
+    'Kasu: this instance is read-only; call kasu.connect(signer) first';