@kasufinance/kasu-sdk 2.7.0 → 2.8.0

package/dist/flows/deposit-flow.d.ts

@@ -45,16 +45,41 @@ import { WaitableTransaction } from './observable';
  * 8. **`request-sign` / `request-confirm`** — KYC signature, then the deposit,
  *    then the receipt.
  *
+ * ## The batch path
+ *
+ * A consumer that can submit several calls as ONE atomic transaction supplies
+ * the optional `depositBatch` port. When the allowance is short, that port is
+ * present and the stable token is known, steps 7 and 8 become one: the SDK
+ * encodes `approve(spender, amount)` and `requestDepositWithKyc(...)` itself
+ * and hands both to the port. Because a batch has no wallet prompt per call,
+ * the run first PARKS on `awaiting-authorise` until the consumer calls
+ * `authoriseTransfer()` (or `declineTransfer()`) — nothing moves money
+ * without an explicit authorisation. The TTL is checked again after it, and
+ * the KYC signature is fetched only then, because it carries a block
+ * expiration of its own. Without the port, or with the allowance already
+ * sufficient, the run is exactly the two-transaction pipeline above.
+ *
  * ## Failure codes
  *
  * A wallet rejection (`isUserRejected`) is `'cancelled'` — the lender changed
  * their mind, and telling them something broke would be a lie. Only a WALLET
  * call is ever classified that way: the HTTP ports are always `'failed'`,
  * because a backend that words a refusal "declined" did not involve the
- * lender's wallet. A reverted gas estimate on the request step
- * (`isUnpredictableGas`) is `'insufficient-balance'` — nothing was refused, the
- * transaction simply cannot succeed as composed. Everything else is `'failed'`
- * and carries the original error for the consumer's crash reporter.
+ * lender's wallet. A revert on the request step is read for WHAT reverted: a
+ * protocol error the ABI declares is `'reverted'` with the name, and only a
+ * token balance or allowance failure — or a revert nothing can decode — stays
+ * `'insufficient-balance'`. Everything else is `'failed'` and carries the
+ * original error for the consumer's crash reporter.
+ *
+ * ## Both signatures are checked before they are used
+ *
+ * A wallet is not obliged to hand back 65 bytes, and `encodeDepositData` will
+ * not catch one that does not: `defaultAbiCoder` encodes any even-length hex
+ * as `bytes`, `0x` included, so a malformed acceptance signature becomes a
+ * `depositData` blob that is broadcast, mined, and then can never be verified
+ * by the agreements service. Both personal signs are therefore length-checked
+ * where they are taken, and a bad one fails the step it was taken on rather
+ * than the one it would eventually have broken.
  *
  * ```ts
  * const flow = new DepositFlow(ports);
@@ -68,7 +93,12 @@ import { WaitableTransaction } from './observable';
  * Where the run is. `success`, `declined` and `error` are terminal; everything
  * else is in flight.
  */
-export type DepositPhase = 'idle' | 'generating-sign' | 'generating-fetch' | 'awaiting-accept' | 'accepting-sign' | 'approve' | 'request-sign' | 'request-confirm' | 'success' | 'declined' | 'error';
+export type DepositPhase = 'idle' | 'generating-sign' | 'generating-fetch' | 'awaiting-accept' | 'accepting-sign' | 'approve'
+/**
+ * Batch path only: the run is PARKED until `authoriseTransfer()` or
+ * `declineTransfer()`. Step `request`.
+ */
+ | 'awaiting-authorise' | 'request-sign' | 'request-confirm' | 'success' | 'declined' | 'error';
 /**
  * The four steps a lender sees as a badge. `approve` drops out of the sequence
  * when the allowance already covers the deposit, which is why `stepIndex` and
@@ -93,11 +123,55 @@ export type DepositFailure = {
     step: 'request';
     reason: 'insufficient-balance';
     error: unknown;
+} | {
+    step: 'request';
+    reason: 'reverted';
+    /**
+     * The custom error the contract reverted with, exactly as the ABI
+     * declares it — `'ClearingIsPending'`, `'LendingPoolIsStopped'`,
+     * `'UserNotKycd'`, and the rest of
+     * `ILendingPoolManagerAbi` / `IKasuAllowListAbi`.
+     *
+     * Render `reverted` with generic copy and special-case only the
+     * names you have words for: a contract upgrade can add an error, and
+     * a consumer that assumed the set was closed would have nothing to
+     * show for the new one.
+     */
+    revertError: string;
+    error: unknown;
 } | {
     step: 'request';
     reason: 'contract-expired';
 };
 export type { WaitableTransaction };
+/**
+ * One call of an atomic batch: a target and its ABI-encoded calldata. No
+ * value — neither call the deposit batch makes sends the native token.
+ */
+export interface BatchCall {
+    to: string;
+    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 declare class BatchRevertedError extends Error {
+    readonly revertError: string;
+    constructor(revertError: string, message?: string);
+}
 /** What the KYC signing service hands back. */
 export interface KycSignature {
     signature: string;
@@ -190,10 +264,34 @@ export interface DepositPorts {
     approve(spender: string, amount: BigNumber): Promise<WaitableTransaction>;
     /** `requestDepositWithKyc`. Defaults to `kasu.deposits.deposit`. */
     deposit(params: DepositParams): Promise<WaitableTransaction>;
+    /**
+     * OPTIONAL, and with no default: submit several calls as ONE atomic
+     * transaction — all of them apply, or none does. How is the consumer's
+     * business; the SDK owns what goes in and in which order.
+     *
+     * When supplied, the allowance is short and the flow knows the stable
+     * token (`DepositFlowOptions.stableAsset`), the run takes the batch path:
+     * it parks on `awaiting-authorise`, then hands this port exactly two calls
+     * —
+     *
+     * 0. `stableAsset.approve(spender, amount)` — the EXACT deposit amount,
+     *    never `MaxUint256`;
+     * 1. `spender.requestDepositWithKyc(pool, tranche, amount, '0x',
+     *    fixedTermConfigId, depositData, { blockExpiration, signature })` —
+     *    the call the default `deposit` port makes.
+     *
+     * and neither `approve` nor `deposit` is called. Resolve with something
+     * whose `wait()` settles when the batch is mined. Throw
+     * `BatchRevertedError` when the batch is known to revert.
+     */
+    depositBatch?(calls: BatchCall[]): Promise<WaitableTransaction>;
     /** ms-epoch clock. Defaults to `Date.now`; injected so the TTL is testable. */
     now?(): number;
 }
-/** Construction options. `kasu.flows.deposit()` fills `spender` in. */
+/**
+ * Construction options. `kasu.flows.deposit()` fills `spender` and
+ * `stableAsset` in.
+ */
 export interface DepositFlowOptions {
     /** Agreement validity window; defaults to `CONTRACT_TTL_MS`. */
     contractTtlMs?: number;
@@ -204,6 +302,17 @@ export interface DepositFlowOptions {
      * deposit port calls.
      */
     spender?: string;
+    /**
+     * The ERC-20 the deposit is paid in — the target of the batch path's
+     * approve call. `kasu.flows.deposit()` passes this chain's
+     * `stableAsset.address`.
+     *
+     * Without it the batch path is never taken, even when `depositBatch` is
+     * supplied: an approve encoded against a guessed token is an approval
+     * granted on the wrong contract inside a transaction that then reverts.
+     * The run falls back to the `approve` and `deposit` ports instead.
+     */
+    stableAsset?: string;
 }
 export interface DepositFlowInput {
     poolId: string;
@@ -241,10 +350,24 @@ export interface DepositState {
     step: DepositStep | null;
     /** 1-based badge position of `step`; `0` while idle. */
     stepIndex: number;
-    /** `4`, or `3` when the allowance already covers the deposit. */
+    /**
+     * `4`, or `3` when the allowance already covers the deposit or the run
+     * is batched.
+     */
     stepTotal: number;
-    /** Whether the approve step is in scope for this run. */
+    /**
+     * Whether the separate approve STEP is in scope for this run. `false`
+     * on a batched run too: its approval rides inside the request step's
+     * single transaction, so it never enters `approve` and counts as a
+     * three-step run on every badge.
+     */
     approvalRequired: boolean;
+    /**
+     * Whether this run approves and deposits as ONE atomic batch through the
+     * `depositBatch` port. Decided by the allowance pre-check, before the
+     * first signature, and `false` on every two-transaction run.
+     */
+    batched: boolean;
     /** The generated agreement, from `generating-fetch` onwards. */
     contract: GenerateContractResponse | null;
     /** Set with `phase: 'error'`, cleared by `reset()`. */
@@ -254,10 +377,15 @@ export interface DepositState {
 export declare const CONTRACT_TTL_MS: number;
 /** What a run without a spender, from either source, fails with. */
 export declare const NO_SPENDER_MESSAGE = "DepositFlow: no ERC-20 spender; build the flow with kasu.flows.deposit() or pass `spender` on the input";
+/** What a malformed auth signature fails the generate step with. */
+export declare const INVALID_AUTH_SIGNATURE_MESSAGE = "DepositFlow: the wallet returned a malformed authentication signature; expected 65 bytes of 0x-prefixed hex";
+/** What a malformed acceptance signature fails the confirm step with. */
+export declare const INVALID_ACCEPTANCE_SIGNATURE_MESSAGE = "DepositFlow: the wallet returned a malformed acceptance signature; expected 65 bytes of 0x-prefixed hex";
 export declare class DepositFlow extends Flow<DepositState, DepositFlowInput> {
     private readonly _ports;
     private readonly _ttlMs;
     private readonly _defaultSpender;
+    private readonly _stableAsset;
     private readonly _now;
     /**
      * The accept handshake. The run parks on this promise; `acceptContract`,
@@ -277,6 +405,12 @@ export declare class DepositFlow extends Flow<DepositState, DepositFlowInput> {
      * A stale token simply is not the current generation.
      */
     private _acceptingFor;
+    /**
+     * 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.
+     */
+    private _authorise;
     constructor(_ports: DepositPorts, opts?: DepositFlowOptions);
     /**
      * Sign the agreement and resume the parked run. A no-op when nothing is
@@ -292,10 +426,38 @@ export declare class DepositFlow extends Flow<DepositState, DepositFlowInput> {
      * out of a prompt that never answers.
      */
     declineContract(): void;
+    /**
+     * 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(): void;
+    /**
+     * 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(): void;
     /** True only while THIS generation is waiting on the acceptance signature. */
     private _isAccepting;
     /** `reset()`: unpark the abandoned run and drop its handshake. */
     protected _onAbandon(): void;
     protected _run(input: DepositFlowInput, token: number): Promise<void>;
+    /**
+     * 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.
+     */
+    private _runBatch;
     private _fail;
 }