@kasufinance/kasu-sdk 2.7.1 → 2.10.0

package/src/domain/fixed-term.ts

@@ -0,0 +1,115 @@
+import { TrancheData } from '../services/DataService/types';
+
+/**
+ * Fixed-term deposits. A fixed-term config locks a deposit for N epochs in
+ * exchange for a fixed rate. The configs ride on `TrancheData.fixedTermConfig`;
+ * `'0'` is the variable-rate sentinel (no lock) that `requestDepositWithKyc`
+ * takes as `fixedTermConfigId`.
+ *
+ * Numbers only. Turning a lock into "12 months" or "3 weeks" is copy, and
+ * stays in each application — what lives here is the arithmetic both of those
+ * strings have to agree on, so a selector and a details table can never state
+ * one term two ways.
+ */
+
+/** One fixed-term config, exactly as `TrancheData` carries it. */
+export type FixedTermConfig = TrancheData['fixedTermConfig'][number];
+
+/**
+ * One epoch's nominal length in days. A lock is counted in epochs, and the
+ * loan-agreement text states its term from the same 7-day epoch.
+ */
+export const DAYS_PER_EPOCH = 7;
+
+/**
+ * The average calendar month, 365.25 / 12. A lock is counted in epochs, so a
+ * "12-month" term is 52 epochs = 364 days, and only the average-month divisor
+ * lands that on 12 (364 / 30.4375 = 11.96 → 12).
+ */
+export const DAYS_PER_MONTH = 30.4375;
+
+/**
+ * The shortest lock stated in months. Below it a term reads in weeks or days,
+ * so nothing may claim a month count for it — a 3-epoch lock is 21 days, which
+ * the average-month divisor would otherwise round UP to one month.
+ */
+export const MIN_DAYS_FOR_MONTHS = 30;
+
+/**
+ * `'0'`, empty or absent is the variable-rate sentinel, not a fixed term.
+ * Every surface that tags a rate "variable" or "fixed" must derive the tag
+ * through this, so no screen can hardcode a tag that contradicts the rate
+ * beside it.
+ */
+export function isFixedTermConfigId(
+    configId: string | null | undefined,
+): boolean {
+    if (configId == null) return false;
+    const trimmed = configId.trim();
+    return trimmed !== '' && trimmed !== '0';
+}
+
+/**
+ * The fixed-term configs this wallet may actually select on a tranche: a
+ * config open to `Everyone`, or an `AllowlistedOnly` config whose allowlist
+ * names the wallet. Anything else is dropped (hide-ineligible): the contract
+ * refuses a deposit into an allowlisted config from a wallet that is not on
+ * it, so offering one is offering a transaction that reverts.
+ *
+ * Address matching is case-insensitive. An allowlist entry whose
+ * `isAllowlisted` is `false` is a wallet that was REMOVED — the subgraph keeps
+ * the entity and flips the flag — so it does not count. An entry that carries
+ * no flag at all counts by its presence, which is how every entry read before
+ * 2.9.0 arrived (the query did not select the field).
+ *
+ * `address` `null` / `undefined` — no wallet yet — sees only the `Everyone`
+ * configs. Order is the tranche's own.
+ */
+export function availableFixedTermConfigs(
+    tranche: Pick<TrancheData, 'fixedTermConfig'> | null | undefined,
+    address: string | null | undefined,
+): FixedTermConfig[] {
+    if (!tranche) return [];
+    const lower = address?.toLowerCase();
+    return tranche.fixedTermConfig.filter(
+        (config) =>
+            config.fixedTermDepositStatus === 'Everyone' ||
+            (lower != null &&
+                lower !== '' &&
+                config.fixedTermDepositAllowlist.some(
+                    (entry) =>
+                        (entry.isAllowlisted as boolean | undefined) !==
+                            false && entry.userId.toLowerCase() === lower,
+                )),
+    );
+}
+
+/**
+ * A lock's length in days: `epochLockDuration × 7`.
+ *
+ * FAILS CLOSED: an unparseable, non-finite, zero or negative epoch count
+ * returns `NaN`, never `0` — a zero-day lock is not a term, and a consumer
+ * that rendered it would state one.
+ *
+ * @param epochLockDuration the config's `epochLockDuration`, a decimal string.
+ */
+export function lockDurationDays(epochLockDuration: string): number {
+    const epochs = parseFloat(epochLockDuration);
+    if (!Number.isFinite(epochs) || epochs <= 0) return NaN;
+    return epochs * DAYS_PER_EPOCH;
+}
+
+/**
+ * A lock in WHOLE months, or `null` when the epoch count is not a positive
+ * number or the lock is shorter than `MIN_DAYS_FOR_MONTHS`.
+ *
+ * Unlike a year-rounding formatter it never rolls up into years: a 104-epoch
+ * lock is 24 months. A consumer that states years does that conversion in its
+ * own words.
+ */
+export function lockDurationMonths(epochLockDuration: string): number | null {
+    const days = lockDurationDays(epochLockDuration);
+    if (Number.isNaN(days) || days < MIN_DAYS_FOR_MONTHS) return null;
+    const months = Math.round(days / DAYS_PER_MONTH);
+    return months > 0 ? months : null;
+}

package/src/domain/index.ts

@@ -37,6 +37,25 @@ export {
 } from './au-minimum';
 export type { AuMinimumInput } from './au-minimum';
 
+export {
+    DepositBatchMismatchError,
+    ENTRY_POINT_V07,
+    proveDepositInReceipt,
+    proveUserOperationInReceipt,
+    validateDepositBatchCalls,
+} from './batch-proof';
+export type {
+    DepositBatchCall,
+    DepositBatchExpectation,
+    DepositProof,
+    DepositProofExpectation,
+    ReceiptLike,
+    ReceiptLog,
+    UserOperationProof,
+    UserOperationProofExpectation,
+    ValidatedDepositBatch,
+} from './batch-proof';
+
 export {
     ceilToCents,
     floorToCents,
@@ -49,10 +68,25 @@ export {
 } from './deposit-bounds';
 export type { BoundShortcuts, DepositBounds } from './deposit-bounds';
 
+export { explorerAddressUrl, explorerTxUrl } from './explorer-urls';
+export type { ExplorerConfig } from './explorer-urls';
+
+export {
+    availableFixedTermConfigs,
+    DAYS_PER_EPOCH,
+    DAYS_PER_MONTH,
+    isFixedTermConfigId,
+    lockDurationDays,
+    lockDurationMonths,
+    MIN_DAYS_FOR_MONTHS,
+} from './fixed-term';
+export type { FixedTermConfig } from './fixed-term';
+
 export {
     APXIUM,
     getCreditOriginator,
     getInstitutionalLender,
+    getStrategyRegion,
     INVOICEMATE,
     RIXON_CAPITAL,
 } from './partners';
@@ -88,6 +122,7 @@ export {
 export type { BestTranche } from './pools';
 
 export {
+    cancelDeadline,
     countSubmissions,
     deriveRequestState,
     firstSubmissionTimestamp,
@@ -116,6 +151,17 @@ export type {
     SettlementWindowState,
 } from './settlement';
 
+export {
+    encodeCancelDepositCall,
+    encodeCancelWithdrawalCall,
+    encodeRequestWithdrawalCall,
+    encodeWithdrawAtExpiryCall,
+    SPONSORED_CALL_KINDS,
+    SPONSORED_CALL_SELECTORS,
+    SponsoredCallInputError,
+} from './sponsored-calls';
+export type { SponsoredCall, SponsoredCallKind } from './sponsored-calls';
+
 export { getTrancheDisplayName, UPPER_MEZZANINE } from './tranche-display-name';
 
 export {
@@ -141,3 +187,13 @@ export {
     isUserRejected,
 } from './wallet-errors';
 export type { WalletFailure } from './wallet-errors';
+
+export {
+    accruedInterest,
+    dailyInterest,
+    projectedAnnualEarnings,
+    SECONDS_PER_WEEK,
+    weeklyInterest,
+    weightedAverageApy,
+} from './yields';
+export type { InterestSlice, PoolAccrual } from './yields';

package/src/domain/partners.ts

@@ -7,19 +7,36 @@
 export interface StrategyPartner {
     name: string;
     url: string;
+    /**
+     * The region of the strategies this partner takes part in, as every Kasu
+     * surface names it. For a credit originator it is THE strategy's region —
+     * `getStrategyRegion` reads it from here — and it is the word that goes
+     * into the wallet-signed loan-agreement message, so it must never be
+     * stated from anywhere else.
+     *
+     * Apxium originates in Australia. InvoiceMate (PayFi) funds cross-border
+     * payment corridors no single jurisdiction names, so its region is a
+     * SCOPE — `'Global'` — rather than a country: naming one would be a claim
+     * about where its End Borrowers sit. Rixon Capital is the senior lender in
+     * Apxium's Australian strategies.
+     */
+    region: string;
 }
 
 export const APXIUM: StrategyPartner = {
     name: 'Apxium',
     url: 'https://www.apxium.com/',
+    region: 'Australia',
 };
 export const INVOICEMATE: StrategyPartner = {
     name: 'InvoiceMate',
     url: 'https://invoicemate.net/',
+    region: 'Global',
 };
 export const RIXON_CAPITAL: StrategyPartner = {
     name: 'Rixon Capital',
     url: 'https://rixon.capital/',
+    region: 'Australia',
 };
 
 /**
@@ -64,3 +81,21 @@ export function getInstitutionalLender(
 ): StrategyPartner | null {
     return originator.name === APXIUM.name ? RIXON_CAPITAL : null;
 }
+
+/**
+ * The strategy's region — `'Australia'` for the Apxium family, `'Global'` for
+ * PayFi — derived from its credit originator, exactly as every surface that
+ * states a region must derive it.
+ *
+ * LOAD-BEARING ON THE MONEY PATH: this is the `region` a lender's wallet signs
+ * in the loan-agreement message (`buildLoanAgreementSignMessage`). The backend
+ * rebuilds that message from whatever region the client sends and treats it
+ * as display-only, so nothing but this function keeps the signed word equal to
+ * the word on screen. Never state a region from a constant — that is how a
+ * PayFi lender came to pick "Global · Junior" and sign "Australia".
+ *
+ * Replace the inference with a per-pool field (in the SDK) when one ships.
+ */
+export function getStrategyRegion(pool: PoolNameSignal): string {
+    return getCreditOriginator(pool).region;
+}

package/src/domain/requests.ts

@@ -4,6 +4,8 @@ import {
     UserRequestEvent,
 } from '../services/UserLending/types';
 
+import { deriveCycleDates } from './settlement';
+
 /**
  * The lending-request view model, as CODES.
  *
@@ -239,6 +241,41 @@ export function isCycleClosed(request: Pick<UserRequest, 'canCancel'>): boolean
     return !request.canCancel;
 }
 
+/**
+ * Until when can THIS request still be cancelled? — unix seconds, or `null`
+ * when it cannot be cancelled at all, or when no epoch boundary is loaded.
+ *
+ * The answer is the next cycle close (`deriveCycleDates(...).close`): the
+ * clearing window opens there, and the contract refuses a cancel while the
+ * pool's clearing is pending (`CannotCancelRequestIfClearingIsPending`).
+ * Inside a window whose clearing already ENDED, a still-cancellable request is
+ * queued for the next cycle, so its deadline is next week's close — which is
+ * exactly what `deriveCycleDates` rolls forward to.
+ *
+ * `null` unless the request is BOTH:
+ *
+ * - `canCancel` — the SDK's per-pool signal (see `isCycleClosed`);
+ * - live: `statusCode` `pending`, or `partial` (a partly-filled withdrawal
+ *   whose remainder is back in the queue — a resolved partial has
+ *   `canCancel: false`). A cancelled, forced, reallocated, rejected or complete
+ *   request has nothing left to cancel, whatever `canCancel` says.
+ *
+ * `canCancel` is read ONCE, when the request was fetched. A request held
+ * across a cycle boundary (`nextCycleBoundary`) must be refetched before this
+ * is shown again — the deadline is a hint, the contract is the gate.
+ */
+export function cancelDeadline(
+    request: Pick<RequestState, 'canCancel' | 'statusCode'>,
+    nextEpochStart: number | undefined,
+    nowSeconds: number,
+): number | null {
+    if (!request.canCancel) return null;
+    if (request.statusCode !== 'pending' && request.statusCode !== 'partial') {
+        return null;
+    }
+    return deriveCycleDates(nextEpochStart, nowSeconds)?.close ?? null;
+}
+
 const isCancelled = (events: UserRequestEvent[]): boolean =>
     events.some((e) => e.requestType === 'Cancelled');
 

package/src/domain/sponsored-calls.ts

@@ -0,0 +1,213 @@
+import { BigNumber, BigNumberish, constants, utils } from 'ethers';
+
+import { ILendingPoolManagerAbi__factory } from '../contracts/factories/ILendingPoolManagerAbi__factory';
+
+/**
+ * The single-call `LendingPoolManager` requests a sponsored relay may carry,
+ * encoded by the SDK so no application hand-builds calldata or hand-maps the
+ * relay's `kind` for them.
+ *
+ * Every function here is PURE: addresses and ids in, `{ kind, call }` out.
+ * Reading the chain (the shares a withdrawal is for) is the facade's job —
+ * `kasu.calls` — and sending is the application's.
+ *
+ * Each call is `{ to, data }` and nothing else: no `value` (none of these
+ * functions is payable), no `from` (the manager acts for `msg.sender`, the
+ * lender's own account, which is why none of them takes a user argument).
+ * `data` is ethers' ABI encoding, which is canonical by construction — the
+ * relay re-encodes what it decodes and refuses anything that differs, so a
+ * hand-tweaked blob never gets through, and an SDK-built one always matches.
+ */
+
+/**
+ * The relay's name for each shape. Carried beside the call so the app posts
+ * `kind` from the SDK, never from a table of its own — a request declaring the
+ * wrong kind is refused (`invalid_calls`), so a hand-mapped table that drifts
+ * turns into a lender who cannot withdraw.
+ */
+export const SPONSORED_CALL_KINDS = [
+    /** `LendingPoolManager.requestWithdrawal(pool, tranche, shares)`. */
+    'withdrawal',
+    /** `LendingPoolManager.cancelDepositRequest(pool, dNftID)`. */
+    'cancel_deposit',
+    /** `LendingPoolManager.cancelWithdrawalRequest(pool, wNftID)`. */
+    'cancel_withdrawal',
+    /** `LendingPoolManager.requestFixedTermDepositWithdrawal(pool, lockId)`. */
+    'withdraw_at_expiry',
+] as const;
+
+export type SponsoredCallKind = (typeof SPONSORED_CALL_KINDS)[number];
+
+/** One encoded call and the relay `kind` that names its shape. */
+export interface SponsoredCall {
+    kind: SponsoredCallKind;
+    /**
+     * Exactly `{ to, data }` — structurally the flows' `BatchCall`. Post it as
+     * the relay's single call; do not add keys to it.
+     */
+    call: { to: string; data: string };
+}
+
+/**
+ * Widened to the plain `Interface`: the typechain one overloads
+ * `encodeFunctionData` per literal name, and the name here comes from
+ * `FUNCTION_OF`.
+ */
+const LENDING_POOL_MANAGER: utils.Interface =
+    ILendingPoolManagerAbi__factory.createInterface();
+
+/** The `LendingPoolManager` function behind each kind. */
+const FUNCTION_OF: Readonly<Record<SponsoredCallKind, string>> = Object.freeze({
+    withdrawal: 'requestWithdrawal',
+    cancel_deposit: 'cancelDepositRequest',
+    cancel_withdrawal: 'cancelWithdrawalRequest',
+    withdraw_at_expiry: 'requestFixedTermDepositWithdrawal',
+});
+
+/**
+ * The 4-byte selector of each kind's function, DERIVED from the generated
+ * `ILendingPoolManager` ABI — never typed in by hand, so an ABI change moves
+ * it and the cross-check spec against the relay's own pins goes red.
+ */
+export const SPONSORED_CALL_SELECTORS: Readonly<
+    Record<SponsoredCallKind, string>
+> = Object.freeze({
+    withdrawal: LENDING_POOL_MANAGER.getSighash(FUNCTION_OF.withdrawal),
+    cancel_deposit: LENDING_POOL_MANAGER.getSighash(FUNCTION_OF.cancel_deposit),
+    cancel_withdrawal: LENDING_POOL_MANAGER.getSighash(
+        FUNCTION_OF.cancel_withdrawal,
+    ),
+    withdraw_at_expiry: LENDING_POOL_MANAGER.getSighash(
+        FUNCTION_OF.withdraw_at_expiry,
+    ),
+});
+
+/**
+ * What an encoder throws for an input it will not encode. `code` names the
+ * argument; the message names no party, so a wallet-rejection classifier can
+ * never read it as something the lender did. Nothing has been sent when this
+ * is thrown.
+ */
+export class SponsoredCallInputError extends Error {
+    readonly code: string;
+
+    constructor(code: string) {
+        super(`Sponsored call input refused (${code})`);
+        this.name = 'SponsoredCallInputError';
+        this.code = code;
+        Object.setPrototypeOf(this, SponsoredCallInputError.prototype);
+    }
+}
+
+const ADDRESS_RE = /^0x[0-9a-fA-F]{40}$/;
+
+function assertAddress(value: unknown, code: string): asserts value is string {
+    if (typeof value !== 'string' || !ADDRESS_RE.test(value)) {
+        throw new SponsoredCallInputError(code);
+    }
+}
+
+/** A uint256 — an NFT or lock id. Zero is a valid id as far as encoding goes. */
+function toUint256(value: BigNumberish, code: string): BigNumber {
+    let parsed: BigNumber;
+    try {
+        parsed = BigNumber.from(value);
+    } catch {
+        throw new SponsoredCallInputError(code);
+    }
+    if (parsed.isNegative() || parsed.gt(constants.MaxUint256)) {
+        throw new SponsoredCallInputError(code);
+    }
+    return parsed;
+}
+
+function encode(
+    kind: SponsoredCallKind,
+    lendingPoolManager: string,
+    args: readonly unknown[],
+): SponsoredCall {
+    return {
+        kind,
+        call: {
+            to: lendingPoolManager,
+            data: LENDING_POOL_MANAGER.encodeFunctionData(
+                FUNCTION_OF[kind],
+                args,
+            ),
+        },
+    };
+}
+
+/**
+ * `requestWithdrawal(poolId, trancheId, shares)` — `withdrawal`.
+ *
+ * `shares` are tranche SHARES, not assets: `kasu.calls.requestWithdrawal`
+ * converts an asset amount (or `'max'`) into them exactly as
+ * `UserLending.requestWithdrawalInAsset` / `requestWithdrawalMax` do. Zero
+ * shares is refused here: the contract reverts on it
+ * (`RequestWithdrawSharesAreZero`) and the relay refuses it before that.
+ */
+export function encodeRequestWithdrawalCall(
+    lendingPoolManager: string,
+    poolId: string,
+    trancheId: string,
+    shares: BigNumberish,
+): SponsoredCall {
+    assertAddress(lendingPoolManager, 'lending-pool-manager');
+    assertAddress(poolId, 'pool');
+    assertAddress(trancheId, 'tranche');
+    const amount = toUint256(shares, 'shares');
+    if (amount.isZero()) throw new SponsoredCallInputError('zero-shares');
+    return encode('withdrawal', lendingPoolManager, [
+        poolId,
+        trancheId,
+        amount,
+    ]);
+}
+
+/** `cancelDepositRequest(poolId, dNftId)` — `cancel_deposit`. */
+export function encodeCancelDepositCall(
+    lendingPoolManager: string,
+    poolId: string,
+    dNftId: BigNumberish,
+): SponsoredCall {
+    assertAddress(lendingPoolManager, 'lending-pool-manager');
+    assertAddress(poolId, 'pool');
+    return encode('cancel_deposit', lendingPoolManager, [
+        poolId,
+        toUint256(dNftId, 'nft-id'),
+    ]);
+}
+
+/** `cancelWithdrawalRequest(poolId, wNftId)` — `cancel_withdrawal`. */
+export function encodeCancelWithdrawalCall(
+    lendingPoolManager: string,
+    poolId: string,
+    wNftId: BigNumberish,
+): SponsoredCall {
+    assertAddress(lendingPoolManager, 'lending-pool-manager');
+    assertAddress(poolId, 'pool');
+    return encode('cancel_withdrawal', lendingPoolManager, [
+        poolId,
+        toUint256(wNftId, 'nft-id'),
+    ]);
+}
+
+/**
+ * `requestFixedTermDepositWithdrawal(poolId, fixedTermDepositId)` —
+ * `withdraw_at_expiry`. The contract function takes the pool and the LOCK id
+ * only (no tranche): the manager forwards to the fixed-term contract on the
+ * lender's behalf, which knows the lock's tranche.
+ */
+export function encodeWithdrawAtExpiryCall(
+    lendingPoolManager: string,
+    poolId: string,
+    fixedTermDepositId: BigNumberish,
+): SponsoredCall {
+    assertAddress(lendingPoolManager, 'lending-pool-manager');
+    assertAddress(poolId, 'pool');
+    return encode('withdraw_at_expiry', lendingPoolManager, [
+        poolId,
+        toUint256(fixedTermDepositId, 'lock-id'),
+    ]);
+}