@kasufinance/kasu-sdk 2.6.0 → 2.7.1

package/src/domain/revert-errors.ts

@@ -0,0 +1,248 @@
+import { ethers } from 'ethers';
+
+import { IKasuAllowListAbi__factory } from '../contracts/factories/IKasuAllowListAbi__factory';
+import { ILendingPoolManagerAbi__factory } from '../contracts/factories/ILendingPoolManagerAbi__factory';
+
+/**
+ * Revert decoding — turn the bytes a failed call came back with into the name
+ * the contract actually reverted with.
+ *
+ * `isUnpredictableGas` says only THAT the call would revert. That was enough
+ * while the answer was always the same one: a `transferFrom` failing on a
+ * balance that cannot cover the deposit. It is not enough any more, because
+ * `requestDepositWithKyc` reverts for a whole family of reasons the ABI
+ * declares and the lender can do nothing about — the pool is stopped, the pool
+ * is mid-clearing, their KYC lapsed, they are not on the allow list, the
+ * allow-list signature's block window closed. Every one of those was reported
+ * as "insufficient balance", so a fully funded lender was told to top up a
+ * wallet that was never short.
+ *
+ * The revert data carries the answer. This module extracts it from whatever
+ * envelope the provider wrapped it in and matches the 4-byte selector against
+ * the custom errors the protocol declares.
+ *
+ * Pure, like everything else in `domain/`: bytes in, a name out. It never
+ * decides what a lender is shown — `DepositFlow` maps the name to a code and
+ * the application maps the code to its own words.
+ */
+
+// ---------------------------------------------------------------------------
+// What a decoded revert is
+// ---------------------------------------------------------------------------
+
+/**
+ * Which family a recognised revert belongs to, because the two are acted on
+ * differently.
+ *
+ * `erc20` is the case `insufficient-balance` was named for and still means:
+ * the token transfer itself failed, so the lender genuinely has to fund or
+ * re-approve. `protocol` is everything else the protocol declares — a
+ * condition of the pool or the lender's standing, which topping up cannot fix.
+ */
+export type RevertFamily = 'protocol' | 'erc20';
+
+export interface DecodedRevert {
+    /** The custom error's name, exactly as the ABI declares it. */
+    name: string;
+    family: RevertFamily;
+    /** The reason of a `require(..., "…")` revert, when it was one. */
+    reason?: string;
+}
+
+// ---------------------------------------------------------------------------
+// The selector tables
+// ---------------------------------------------------------------------------
+
+/**
+ * OpenZeppelin v5's ERC-20 errors. They are not in either Kasu ABI because no
+ * Kasu contract declares them — they arrive from the TOKEN, through the
+ * manager's `transferFrom`, and they are the modern spelling of the string
+ * reverts below.
+ */
+const ERC20_ERROR_ABI = [
+    'error ERC20InsufficientBalance(address sender, uint256 balance, uint256 needed)',
+    'error ERC20InsufficientAllowance(address spender, uint256 allowance, uint256 needed)',
+];
+
+/**
+ * The protocol errors that mean the ERC-20 transfer failed rather than the
+ * protocol refusing.
+ *
+ * `SafeERC20FailedOperation` is OpenZeppelin's wrapper around a token call
+ * that returned false or reverted, which on this path IS the `transferFrom`;
+ * `AddressInsufficientBalance` is its native-value sibling. Both belong with
+ * the balance case, not with the pool conditions — a lender who sees one of
+ * them really does need to fund or re-approve.
+ */
+const ERC20_FAMILY_NAMES: ReadonlySet<string> = new Set([
+    'AddressInsufficientBalance',
+    'ERC20InsufficientAllowance',
+    'ERC20InsufficientBalance',
+    'SafeERC20FailedOperation',
+]);
+
+/** Solidity's `Error(string)`, the selector every `require` reason arrives under. */
+const STRING_REVERT_SELECTOR = '0x08c379a0';
+
+/**
+ * The `require` reasons that are a balance or an allowance, across the token
+ * implementations in circulation: OpenZeppelin v4's sentences, and the
+ * shorthand the minimal implementations use.
+ */
+const ERC20_REASON_PATTERNS: readonly RegExp[] = [
+    /exceeds\s+balance/,
+    /exceeds\s+allowance/,
+    /insufficient\s+balance/,
+    /insufficient\s+allowance/,
+    /transfer_from_failed/,
+    /transferfrom\s+failed/,
+    /low-level\s+call\s+failed/,
+];
+
+/**
+ * selector → error name, built once on first use.
+ *
+ * Lazily, because a consumer that never sees a revert should not pay for three
+ * `Interface` constructions at import. The two Kasu tables are the GENERATED
+ * typechain ABIs, so this cannot drift from the contracts: regenerate the ABIs
+ * and the new errors are recognised with no edit here.
+ */
+let selectorTable: Map<string, string> | null = null;
+
+function selectors(): Map<string, string> {
+    if (selectorTable) return selectorTable;
+    const table = new Map<string, string>();
+    const interfaces = [
+        // The manager the deposit is called against, and the allow list it
+        // delegates the KYC and block-window checks to.
+        ILendingPoolManagerAbi__factory.createInterface(),
+        IKasuAllowListAbi__factory.createInterface(),
+        new ethers.utils.Interface(ERC20_ERROR_ABI),
+    ];
+    for (const iface of interfaces) {
+        for (const fragment of Object.values(iface.errors)) {
+            // First writer wins: the same name declared by both ABIs is the
+            // same selector, so the duplicate would be a no-op anyway.
+            const sighash = iface.getSighash(fragment);
+            if (!table.has(sighash)) table.set(sighash, fragment.name);
+        }
+    }
+    selectorTable = table;
+    return table;
+}
+
+// ---------------------------------------------------------------------------
+// Getting the bytes out of the envelope
+// ---------------------------------------------------------------------------
+
+/**
+ * How deep to look for the revert data. Providers nest it differently —
+ * ethers' own error wraps the provider's, which wraps the RPC body — and a
+ * bound is what keeps a self-referencing error object from being walked
+ * forever.
+ */
+const MAX_DEPTH = 6;
+
+/** The keys ethers and the providers under it put a wrapped error on. */
+const NESTED_KEYS = [
+    'data',
+    'error',
+    'originalError',
+    'info',
+    'cause',
+    'body',
+] as const;
+
+/** At least a 4-byte selector, and a whole number of bytes. */
+function isRevertData(value: string): boolean {
+    return (
+        value.length >= 10 &&
+        value.length % 2 === 0 &&
+        /^0x[0-9a-fA-F]+$/.test(value)
+    );
+}
+
+/**
+ * Find the revert data on an error, wherever the provider left it.
+ *
+ * ethers v5 raises `UNPREDICTABLE_GAS_LIMIT` with the provider's own error
+ * attached, and each provider nests the bytes one layer differently:
+ * `error.data`, `error.error.data`, `error.data.originalError.data`, or only
+ * inside the JSON `body` of a `SERVER_ERROR`. Rather than enumerate the
+ * products, walk a fixed set of keys to a fixed depth and take the first value
+ * that is shaped like revert data.
+ */
+export function extractRevertData(err: unknown): string | null {
+    return walk(err, 0);
+}
+
+function walk(node: unknown, depth: number): string | null {
+    if (node == null || depth > MAX_DEPTH) return null;
+    if (typeof node === 'string') {
+        if (isRevertData(node)) return node;
+        // A `SERVER_ERROR`'s body: the RPC's JSON reply, verbatim.
+        if (!node.startsWith('{')) return null;
+        try {
+            return walk(JSON.parse(node), depth + 1);
+        } catch {
+            return null;
+        }
+    }
+    if (typeof node !== 'object') return null;
+    const record = node as Record<string, unknown>;
+    for (const key of NESTED_KEYS) {
+        const found = walk(record[key], depth + 1);
+        if (found) return found;
+    }
+    return null;
+}
+
+// ---------------------------------------------------------------------------
+// Decoding
+// ---------------------------------------------------------------------------
+
+/**
+ * Decode a failed call's revert into the error the contract named, or `null`
+ * when there is nothing recognisable to name.
+ *
+ * `null` is the honest answer for an unknown selector, an unrelated `require`
+ * string, or an error with no revert data at all — the caller keeps whatever
+ * it did before rather than inventing a diagnosis from bytes it cannot read.
+ */
+export function decodeRevert(err: unknown): DecodedRevert | null {
+    const data = extractRevertData(err);
+    if (!data) return null;
+    const selector = data.slice(0, 10).toLowerCase();
+
+    if (selector === STRING_REVERT_SELECTOR) {
+        const reason = decodeStringRevert(data);
+        if (reason === null) return null;
+        return isErc20Reason(reason)
+            ? { name: 'Error', family: 'erc20', reason }
+            : null;
+    }
+
+    const name = selectors().get(selector);
+    if (!name) return null;
+    return {
+        name,
+        family: ERC20_FAMILY_NAMES.has(name) ? 'erc20' : 'protocol',
+    };
+}
+
+function decodeStringRevert(data: string): string | null {
+    try {
+        const [reason] = ethers.utils.defaultAbiCoder.decode(
+            ['string'],
+            `0x${data.slice(10)}`,
+        ) as [string];
+        return reason;
+    } catch {
+        return null;
+    }
+}
+
+function isErc20Reason(reason: string): boolean {
+    const lower = reason.toLowerCase();
+    return ERC20_REASON_PATTERNS.some((pattern) => pattern.test(lower));
+}

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';