@kasufinance/kasu-sdk 2.6.0 → 2.7.0

package/src/flows/flow.ts

@@ -0,0 +1,108 @@
+import { FlowStore } from './observable';
+
+/**
+ * The run lifecycle both flows share: one run at a time, every transition
+ * published, and a `reset()` that is safe to call in the middle of one.
+ *
+ * `DepositFlow` and `WithdrawFlow` each carried their own copy of this — the
+ * re-entrancy guard, the `try/finally` around the run, `state`, `isRunning`,
+ * `subscribe`, `reset`. Two copies of a guard is two places for a guard to be
+ * wrong, on the money path, which is the same reason the pipelines themselves
+ * moved out of the applications.
+ *
+ * ## The guard and the run token are separate, and both matter
+ *
+ * `_runToken` is the re-entrancy guard: claimed synchronously, before the
+ * first `await`, so a double tap cannot launch two pipelines. The store's
+ * `generation` is the abandonment mechanism: an in-flight run holds the value
+ * it claimed, and every `patch` and `isCurrent` checkpoint it makes after
+ * `reset()` is dropped.
+ *
+ * `reset()` releases the guard IMMEDIATELY rather than waiting for the
+ * abandoned run to notice. It has to: a run parked on a wallet prompt that
+ * never answers is a promise that may never settle, and a consumer that has
+ * left that screen must be able to start a new run in the same tick. The
+ * abandoned run's `finally` therefore releases the guard only if it still
+ * holds it — by then a NEW run may own it, and clearing it there would let a
+ * third run start alongside the second.
+ */
+export abstract class Flow<S, I> {
+    protected readonly _store: FlowStore<S>;
+
+    /**
+     * The token of the run currently holding the guard, or `null` when none
+     * does. Not a boolean: releasing the guard has to be attributable to the
+     * run that claimed it.
+     */
+    private _runToken: number | null = null;
+
+    protected constructor(initial: S) {
+        this._store = new FlowStore<S>(initial);
+    }
+
+    /** The current state. Every transition is also published to `subscribe`. */
+    get state(): S {
+        return this._store.state;
+    }
+
+    /** True while a run is in flight, including while parked. */
+    get isRunning(): boolean {
+        return this._runToken !== null;
+    }
+
+    /**
+     * Observe every transition. Returns the unsubscribe function.
+     *
+     * The listener is not called on subscribe; read `state` for the value it
+     * starts from.
+     */
+    subscribe(listener: (state: S) => void): () => void {
+        return this._store.subscribe(listener);
+    }
+
+    /**
+     * Run the pipeline. Resolves when it reaches a terminal phase — it does
+     * not reject, because every outcome a consumer can act on is in `state`.
+     *
+     * A second call while one is in flight is a no-op: one submission per
+     * intent, however many times the button is pressed.
+     */
+    async start(input: I): Promise<void> {
+        if (this._runToken !== null) return;
+        this._store.reset();
+        const token = this._store.beginRun();
+        this._runToken = token;
+        try {
+            await this._run(input, token);
+        } finally {
+            if (this._runToken === token) this._runToken = null;
+        }
+    }
+
+    /**
+     * Back to `idle`, abandoning any run in flight: its remaining transitions
+     * are dropped, whatever it is parked on is unparked, and the guard is
+     * released at once so `start()` is accepted in the SAME tick. Subscribers
+     * are kept — the consumer watching the last run is the one watching the
+     * next.
+     */
+    reset(): void {
+        this._runToken = null;
+        // Bump the generation BEFORE unparking, so the abandoned run's next
+        // checkpoint already reads as superseded.
+        this._store.reset();
+        this._onAbandon();
+    }
+
+    /**
+     * Hook for a flow that parks: unpark it. Called by `reset()` after the
+     * generation has been bumped, so anything the abandoned run does with the
+     * result is dropped.
+     */
+    protected _onAbandon(): void {
+        // A flow with nothing parked has nothing to unpark.
+    }
+
+    /** The pipeline itself. `token` is this run's; check it after every await. */
+    protected abstract _run(input: I, token: number): Promise<void>;
+}

package/src/flows/index.ts

@@ -0,0 +1,45 @@
+/**
+ * Flows: the headless money-path state machines.
+ *
+ * `domain/` holds rules that are pure functions. These are the same idea one
+ * level up — a rule that unfolds over time, with side effects the consumer
+ * injects as ports. They own the ORDER of a deposit and a withdrawal, the
+ * guards around them, and the codes that describe where a run got to. They own
+ * no UI, no framework, no network and no words.
+ *
+ * Every application drove its own copy of the deposit pipeline before this, and
+ * the copies had already started to differ.
+ */
+export { Flow } from './flow';
+export { FlowStore } from './observable';
+export type { WaitableTransaction } from './observable';
+
+export {
+    CONTRACT_TTL_MS,
+    DepositFlow,
+    NO_SPENDER_MESSAGE,
+} from './deposit-flow';
+export type {
+    ContractMessageRequest,
+    DepositFailure,
+    DepositFlowInput,
+    DepositFlowOptions,
+    DepositPhase,
+    DepositPorts,
+    DepositState,
+    DepositStep,
+    GenerateContractRequest,
+    KycSignature,
+    LegacyContractRequest,
+    LoanAgreementRequest,
+} from './deposit-flow';
+
+export { NO_KYC_PARAMS_MESSAGE, WithdrawFlow } from './withdraw-flow';
+export type {
+    WithdrawFailure,
+    WithdrawFlowInput,
+    WithdrawPhase,
+    WithdrawPorts,
+    WithdrawState,
+    WithdrawStep,
+} from './withdraw-flow';

package/src/flows/observable.ts

@@ -0,0 +1,97 @@
+/**
+ * The tiny observable-state kernel both flows are built on.
+ *
+ * Deliberately not a framework store: no React, no signals, no dependency.
+ * A flow is a long asynchronous run that has to publish every transition to
+ * whatever is rendering it, and has to be able to abandon a run that the
+ * consumer walked away from. That is the whole requirement, and it is 60 lines.
+ *
+ * The `generation` counter is the abandonment mechanism. `reset()` bumps it;
+ * an in-flight run captured the previous value, so every later `patch` it
+ * attempts is dropped and every `isCurrent` checkpoint tells it to stop. It is
+ * what makes `reset()` safe to call mid-flight — the run cannot resurrect a
+ * dead state or, worse, drive the UI back into a phase the consumer has left.
+ */
+export class FlowStore<S> {
+    private _state: S;
+    private _generation = 0;
+    private readonly _listeners = new Set<(state: S) => void>();
+
+    constructor(private readonly _initial: S) {
+        this._state = _initial;
+    }
+
+    get state(): S {
+        return this._state;
+    }
+
+    /** The run token an in-flight pipeline captures at `start()`. */
+    get generation(): number {
+        return this._generation;
+    }
+
+    /** False once `reset()` (or a later `start()`) has superseded `token`. */
+    isCurrent(token: number): boolean {
+        return this._generation === token;
+    }
+
+    /**
+     * Subscribe to every transition. Returns the unsubscribe function; calling
+     * it twice is harmless.
+     *
+     * Listeners are NOT called on subscribe — read `state` for the current
+     * value. A listener that throws is not allowed to break the pipeline or
+     * starve the listeners registered after it, so throws are swallowed.
+     */
+    subscribe(listener: (state: S) => void): () => void {
+        this._listeners.add(listener);
+        return () => {
+            this._listeners.delete(listener);
+        };
+    }
+
+    /**
+     * Merge `next` into the state and notify, unless `token` names a
+     * superseded run.
+     */
+    patch(next: Partial<S>, token?: number): void {
+        if (token !== undefined && !this.isCurrent(token)) return;
+        this._state = { ...this._state, ...next };
+        for (const listener of [...this._listeners]) {
+            try {
+                listener(this._state);
+            } catch {
+                // A consumer's rendering fault is its own problem; the pipeline
+                // owns real money and keeps going.
+            }
+        }
+    }
+
+    /**
+     * Back to the initial state, abandoning any in-flight run.
+     *
+     * Subscribers are kept: the consumer that was watching the last run is the
+     * one that will watch the next.
+     */
+    reset(): void {
+        this._generation += 1;
+        this.patch(this._initial);
+    }
+
+    /** Claim the next run token. Any earlier run is abandoned. */
+    beginRun(): number {
+        this._generation += 1;
+        return this._generation;
+    }
+}
+
+/**
+ * Anything with a `wait()` — an ethers `ContractTransaction`, or a fake.
+ *
+ * Lives beside the store rather than in either flow: both submit transactions
+ * through their own ports, and neither of them should have to import the
+ * other's file to say so.
+ */
+export interface WaitableTransaction {
+    wait(): Promise<unknown>;
+}

package/src/flows/withdraw-flow.ts

@@ -0,0 +1,210 @@
+import { BigNumber } from 'ethers';
+
+import { classifyWalletFailure } from '../domain/wallet-errors';
+import { KycParams } from '../facade/types';
+
+import { Flow } from './flow';
+import { WaitableTransaction } from './observable';
+
+/**
+ * The withdrawal pipeline, headless — the small sibling of `DepositFlow`.
+ *
+ * Much less happens here, and that is the point of it being separate: no loan
+ * agreement, no approval (the lender is handing tranche shares back, not
+ * granting a spend), no on-chain KYC payload. What survives is the shape both
+ * applications need — an observable phase, one `'max'`-aware submission, and
+ * the same `cancelled` / `failed` split, so a lender who pressed Reject is
+ * never told something broke.
+ *
+ * The run lifecycle — the re-entrancy guard, `state`, `isRunning`,
+ * `subscribe`, `reset` — is `Flow`'s, shared with the deposit pipeline. It was
+ * a second copy here until 2.7.0, which is two places for one guard to be
+ * wrong.
+ *
+ * Same house rules as the deposit flow: no React, no copy, no I/O of its own.
+ * `state` carries codes; the consumer owns every word a lender reads.
+ *
+ * ```ts
+ * const flow = new WithdrawFlow(ports);
+ * flow.subscribe(render);
+ * await flow.start({ poolId, trancheId, amount: 'max', userAddress });
+ * ```
+ */
+
+// ---------------------------------------------------------------------------
+// Codes
+// ---------------------------------------------------------------------------
+
+export type WithdrawPhase =
+    | 'idle'
+    | 'checking-kyc'
+    | 'request-sign'
+    | 'request-confirm'
+    | 'success'
+    | 'error';
+
+/**
+ * `kyc` only exists when the consumer supplies `getKycSignature`. kasu-mobile
+ * does, to fail early and legibly when a lender's KYC has lapsed rather than
+ * let the on-chain call revert; kasu-ui does not.
+ */
+export type WithdrawStep = 'kyc' | 'request';
+
+export type WithdrawFailure =
+    | { step: WithdrawStep; reason: 'cancelled' }
+    | { step: WithdrawStep; reason: 'failed'; error: unknown };
+
+// ---------------------------------------------------------------------------
+// Ports, input, state
+// ---------------------------------------------------------------------------
+
+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>;
+    /**
+     * 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
+     * surfaces as `{ step: 'kyc' }` instead of an opaque revert. The
+     * withdrawal call itself does not carry the signature.
+     *
+     * Supplying this port is what turns the pre-check on; there is no default,
+     * because the SDK does not know the application's backend. This is the
+     * same pair the deposit flow uses, rather than the opaque `ensureKyc` of
+     * earlier drafts, so one KYC pre-check exists across both money paths.
+     */
+    getKycSignature?(params: KycParams): Promise<unknown>;
+    /** `requestWithdrawalInAsset`. Defaults to `kasu.deposits.withdraw`. */
+    withdraw(params: {
+        poolId: string;
+        trancheId: string;
+        amount: BigNumber;
+    }): Promise<WaitableTransaction>;
+    /** `requestWithdrawalMax`. Defaults to `kasu.deposits.withdrawMax`. */
+    withdrawMax(
+        poolId: string,
+        trancheId: string,
+        userAddress: string,
+    ): Promise<WaitableTransaction>;
+}
+
+export interface WithdrawFlowInput {
+    poolId: string;
+    trancheId: string;
+    /**
+     * 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.
+     */
+    amount: BigNumber | 'max';
+    userAddress: `0x${string}`;
+}
+
+export interface WithdrawState {
+    phase: WithdrawPhase;
+    step: WithdrawStep | null;
+    /** True when this run routed through the all-shares call. */
+    isMax: boolean;
+    failure: WithdrawFailure | null;
+}
+
+const INITIAL: WithdrawState = {
+    phase: 'idle',
+    step: null,
+    isMax: false,
+    failure: null,
+};
+
+/** What a KYC pre-check with no `buildKycParams` to call fails with. */
+export const NO_KYC_PARAMS_MESSAGE =
+    'WithdrawFlow: getKycSignature was supplied without buildKycParams; build the flow with kasu.flows.withdraw() or pass both';
+
+// ---------------------------------------------------------------------------
+// The flow
+// ---------------------------------------------------------------------------
+
+export class WithdrawFlow extends Flow<WithdrawState, WithdrawFlowInput> {
+    constructor(private readonly _ports: WithdrawPorts) {
+        super(INITIAL);
+    }
+
+    protected async _run(
+        input: WithdrawFlowInput,
+        token: number,
+    ): Promise<void> {
+        const ports = this._ports;
+        const isMax = input.amount === 'max';
+
+        // 1. The optional KYC pre-check: build the params, exchange them for a
+        //    signature. Both ports reach the application's own backend, so a
+        //    throw here is ALWAYS `failed` — running it through the wallet
+        //    rejection classifier would let a backend's "Declined" be reported
+        //    to a lender as something they did, with the real error dropped.
+        if (ports.getKycSignature) {
+            this._store.patch(
+                { phase: 'checking-kyc', step: 'kyc', isMax },
+                token,
+            );
+            try {
+                if (!ports.buildKycParams) {
+                    throw new Error(NO_KYC_PARAMS_MESSAGE);
+                }
+                const params = await ports.buildKycParams(input.userAddress);
+                await ports.getKycSignature(params);
+            } catch (err) {
+                this._store.patch(
+                    {
+                        phase: 'error',
+                        failure: { step: 'kyc', reason: 'failed', error: err },
+                    },
+                    token,
+                );
+                return;
+            }
+            if (!this._store.isCurrent(token)) return;
+        }
+
+        // 2. The submission. This one IS a wallet call, so it keeps the
+        //    `cancelled` / `failed` split.
+        this._store.patch(
+            { phase: 'request-sign', step: 'request', isMax },
+            token,
+        );
+        try {
+            const tx =
+                input.amount === 'max'
+                    ? await ports.withdrawMax(
+                          input.poolId,
+                          input.trancheId,
+                          input.userAddress.toLowerCase(),
+                      )
+                    : await ports.withdraw({
+                          poolId: input.poolId,
+                          trancheId: input.trancheId,
+                          amount: input.amount,
+                      });
+            this._store.patch({ phase: 'request-confirm' }, token);
+            await tx.wait();
+        } catch (err) {
+            this._store.patch(
+                {
+                    phase: 'error',
+                    failure: classifyWalletFailure('request', err),
+                },
+                token,
+            );
+            return;
+        }
+        if (!this._store.isCurrent(token)) return;
+
+        this._store.patch({ phase: 'success' }, token);
+    }
+}

package/src/index.ts

@@ -67,3 +67,10 @@ export * from './facade';
 // only: no copy, no locale. See `src/domain/index.ts`.
 // ---------------------------------------------------------------------------
 export * from './domain';
+
+// ---------------------------------------------------------------------------
+// Flows — the headless deposit / withdraw state machines. No React, no copy,
+// no I/O of their own: every side effect is an injected port and every
+// observable state is a code. See `src/flows/index.ts`.
+// ---------------------------------------------------------------------------
+export * from './flows';

package/src/services/DataService/data-service.ts

@@ -547,7 +547,6 @@ export class DataService {
         const poolDelegateProfileAndHistoryDirectus: PoolDelegateProfileAndHistoryDirectus[] =
             (await this._directus.request(
                 readItems('PoolDelegateProfileAndHistory', {
-                    // @ts-ignore Directus' deep-fields typing is fragile across versions
                     fields: ['*', { otherPools: ['*'] }],
                 }),
             )) as unknown as PoolDelegateProfileAndHistoryDirectus[];

package/dist/domain/au-minimum.test.d.ts

@@ -1 +0,0 @@
-export {};