@kasufinance/kasu-sdk 2.8.0 → 2.10.0

package/src/domain/yields.ts

@@ -0,0 +1,189 @@
+/**
+ * Forward-looking interest on a lender's CURRENT balances — the figures a
+ * portfolio shows as "weekly", "daily" and the moving part of "lifetime"
+ * interest, and the "≈ $Y a year" line beside a lend amount.
+ *
+ * Every figure is NET of the platform performance fee, the way the chain
+ * credits it: `LendingPool._applyTrancheInterest` mints the lender
+ * `interest × (1 − performanceFee)` at each cycle close, and only that net
+ * amount ever reaches the balance. A gross projection would out-run what the
+ * next close actually credits.
+ *
+ * Units: balances and results are display units of the deployment's stable
+ * asset (not base units); rates are 0..1 fractions; `feePercent` is a
+ * PERCENTAGE IN 0..100 — see `netEffectiveApy`.
+ */
+
+/**
+ * Seconds in one epoch's nominal week. The per-epoch rate covers exactly this
+ * window, and the accrual spreads an epoch's interest across it.
+ */
+export const SECONDS_PER_WEEK = 604_800;
+
+/** One slice of a position that earns at a single rate. */
+export interface InterestSlice {
+    /** The lender's current balance in this slice, in stable display units. */
+    balance: number;
+    /**
+     * The RAW per-epoch rate the chain applies to this slice at each close,
+     * as a 0..1 fraction (`0.00285` ≈ 0.285% an epoch) — the subgraph's
+     * `TrancheData.interestRate` or a fixed-term config's
+     * `epochInterestRate`. Never derived from an APY.
+     *
+     * NON-FINITE means UNKNOWN, not zero. A zero is a genuinely zero
+     * configured rate and contributes a real 0; the two must stay
+     * distinguishable.
+     */
+    epochRate: number;
+}
+
+/** One pool's contribution to the current cycle's accrual. */
+export interface PoolAccrual {
+    /** That pool's projected net interest for one epoch (`weeklyInterest`). */
+    weeklyInterest: number;
+    /** Unix SECONDS at which THAT pool last cleared a cycle. */
+    clearingTimestamp: number;
+}
+
+function isUsableFeePercent(feePercent: number | null): feePercent is number {
+    return (
+        feePercent !== null &&
+        Number.isFinite(feePercent) &&
+        feePercent >= 0 &&
+        feePercent <= 100
+    );
+}
+
+/**
+ * Interest the slices accrue over ONE epoch, net of the fee.
+ *
+ * ```
+ * weekly = Σ(slice.balance × slice.epochRate) × (1 − feePercent / 100)
+ * ```
+ *
+ * **The rate is the raw per-epoch one, never the APY.** An APY is that rate
+ * already compounded over `EPOCHS_IN_YEAR`; dividing it by 365 charges a day
+ * of compounded annual growth to a single day and overstates it.
+ *
+ * FAILS CLOSED, returning `null` rather than a wrong number:
+ * - a `null`, non-finite or out-of-domain fee — a fee-less projection dressed
+ *   up as the lender's net earnings is the failure this guards;
+ * - any slice with a POSITIVE balance and a non-finite rate — skipping it
+ *   would return a silently partial total, quietly missing that slice.
+ *
+ * Non-finite and non-positive BALANCES are skipped: a slice with nothing in it
+ * earns nothing whatever its rate, so it cannot hide earnings. A portfolio
+ * with nothing lent is therefore a legitimate `0`, never `null`.
+ */
+export function weeklyInterest(
+    slices: readonly InterestSlice[],
+    feePercent: number | null,
+): number | null {
+    if (!isUsableFeePercent(feePercent)) return null;
+    let gross = 0;
+    for (const slice of slices) {
+        if (!Number.isFinite(slice.balance) || slice.balance <= 0) continue;
+        if (!Number.isFinite(slice.epochRate)) return null;
+        gross += slice.balance * slice.epochRate;
+    }
+    return gross * (1 - feePercent / 100);
+}
+
+/**
+ * A day's share of the epoch's net interest: a seventh of it, NOT a
+ * de-compounded daily rate. The chain mints interest once per epoch, so
+ * nothing compounds within the cycle and the accrual is linear across it.
+ *
+ * Fails closed with its input: `null` or non-finite → `null`.
+ */
+export function dailyInterest(weekly: number | null): number | null {
+    if (weekly === null || !Number.isFinite(weekly)) return null;
+    return weekly / 7;
+}
+
+/**
+ * Interest accrued since each pool's OWN last cycle close — the moving part
+ * of lifetime interest (lifetime = settled on chain + this).
+ *
+ * ```
+ * accrued = Σ_pool  weekly_pool × clamp(now − clearing_pool, 0, 604 800) / 604 800
+ * ```
+ *
+ * **Per pool, because pools clear independently.** One shared anchor accrues
+ * a stale pool's share from a close it never had, and when another pool
+ * clears it drops the total by the stale pool's whole weekly share. Anchored
+ * per pool, the total is monotonic across any single pool's clearing: that
+ * pool swaps its accrued share for a capitalised one, and no other term moves.
+ *
+ * **The one-epoch cap is load-bearing.** Clearings are not exactly weekly,
+ * and `weeklyInterest` is per EPOCH, so extrapolating past seven days would
+ * promise interest the close will not credit; a late clearing under-reports
+ * instead. The low clamp makes a close ahead of the local clock zero, never
+ * negative.
+ *
+ * A non-finite term contributes nothing; a non-finite `nowSeconds` accrues
+ * nothing. Callers fail closed upstream by not offering an accrual for a pool
+ * whose weekly interest or anchor is unknown.
+ */
+export function accruedInterest(
+    accruals: readonly PoolAccrual[],
+    nowSeconds: number,
+): number {
+    if (!Number.isFinite(nowSeconds)) return 0;
+    let accrued = 0;
+    for (const { weeklyInterest: weekly, clearingTimestamp } of accruals) {
+        if (!Number.isFinite(weekly) || !Number.isFinite(clearingTimestamp)) {
+            continue;
+        }
+        const elapsed = Math.min(
+            Math.max(nowSeconds - clearingTimestamp, 0),
+            SECONDS_PER_WEEK,
+        );
+        accrued += (weekly * elapsed) / SECONDS_PER_WEEK;
+    }
+    return accrued;
+}
+
+/**
+ * What `amount` earns in a year at a NET rate — the "≈ $Y a year" line.
+ * Feed it `netEffectiveApy(...)`, never a gross APY: the result is a lender's
+ * earnings, so the fee must already be off the rate.
+ *
+ * FAILS CLOSED: a non-finite or negative amount or rate returns `NaN`, which
+ * the consumer renders as "no figure" — exactly what `netEffectiveApy`
+ * returns when the fee is unknown, so that state carries straight through.
+ *
+ * @param amount display units of the stable asset.
+ * @param netApy the net effective annual rate as a 0..1 fraction.
+ */
+export function projectedAnnualEarnings(
+    amount: number,
+    netApy: number,
+): number {
+    if (!Number.isFinite(amount) || amount < 0) return NaN;
+    if (!Number.isFinite(netApy) || netApy < 0) return NaN;
+    return amount * netApy;
+}
+
+/**
+ * Balance-weighted average APY across slices, skipping non-finite and
+ * non-positive balances and non-finite rates; `0` when nothing carries a
+ * positive balance. Whatever basis goes in comes out — feed it NET rates for
+ * an average effective (net) rate.
+ */
+export function weightedAverageApy(
+    slices: readonly { balance: number; apy: number }[],
+): number {
+    let totalBalance = 0;
+    let weighted = 0;
+    for (const slice of slices) {
+        if (!Number.isFinite(slice.balance) || !Number.isFinite(slice.apy)) {
+            continue;
+        }
+        if (slice.balance <= 0) continue;
+        totalBalance += slice.balance;
+        weighted += slice.balance * slice.apy;
+    }
+    if (totalBalance <= 0) return 0;
+    return weighted / totalBalance;
+}

package/src/facade/calls.ts

@@ -0,0 +1,135 @@
+import { BigNumber, BigNumberish } from 'ethers';
+
+import {
+    encodeCancelDepositCall,
+    encodeCancelWithdrawalCall,
+    encodeRequestWithdrawalCall,
+    encodeWithdrawAtExpiryCall,
+    SponsoredCall,
+    SponsoredCallInputError,
+} from '../domain/sponsored-calls';
+import { UserLending } from '../services/UserLending/user-lending';
+
+const ADDRESS_RE = /^0x[0-9a-fA-F]{40}$/;
+
+/** What `kasu.calls.requestWithdrawal` takes — `WithdrawFlowInput`'s shape. */
+export interface RequestWithdrawalCallParams {
+    poolId: string;
+    trancheId: string;
+    /**
+     * Base units of the stable asset, or `'max'` for every share the lender
+     * holds in the tranche. Same code as `WithdrawFlowInput.amount`.
+     */
+    amount: BigNumber | 'max';
+    /** The lender — whose shares `'max'` reads. The relay sends as them. */
+    userAddress: string;
+}
+
+/**
+ * Encoded, ready-to-sponsor `LendingPoolManager` calls — read, then encode,
+ * NEVER send. Each returns `{ kind, call }`: post `kind` and `[call]` to a
+ * sponsored relay (or `submitSponsoredCall`), unchanged.
+ *
+ * ```ts
+ * const { kind, call } = kasu.calls.cancelDepositRequest(poolId, dNftId);
+ * ```
+ *
+ * `call.to` is always THIS chain's `LendingPoolManager`, from the chain
+ * config — the same address the deposit flow approves and calls — so no app
+ * supplies the one argument whose wrong value the relay refuses outright.
+ *
+ * Works on a read-only instance: the only chain access is the share read a
+ * withdrawal needs, and nothing is signed or sent here.
+ */
+export class CallsFacade {
+    constructor(
+        private readonly _userLending: UserLending,
+        private readonly _lendingPoolManager: string,
+    ) {}
+
+    /**
+     * `requestWithdrawal(pool, tranche, shares)` for an asset amount or
+     * `'max'`, converted into shares exactly as the direct path does it
+     * (`UserLending.requestWithdrawalInAsset` / `requestWithdrawalMax`): the
+     * tranche's `convertToShares(amount)`, or the lender's whole
+     * `balanceOf(userAddress)`, read now.
+     *
+     * Rejects with `SponsoredCallInputError` — before anything is sent — for
+     * a non-positive amount, a malformed address, or a conversion that comes
+     * to ZERO shares (an empty position, or dust below one share), which the
+     * contract would revert and the relay refuses.
+     */
+    async requestWithdrawal(
+        params: RequestWithdrawalCallParams,
+    ): Promise<SponsoredCall> {
+        const { poolId, trancheId, amount, userAddress } = params;
+        if (typeof userAddress !== 'string' || !ADDRESS_RE.test(userAddress)) {
+            throw new SponsoredCallInputError('user');
+        }
+        if (typeof poolId !== 'string' || !ADDRESS_RE.test(poolId)) {
+            throw new SponsoredCallInputError('pool');
+        }
+        if (typeof trancheId !== 'string' || !ADDRESS_RE.test(trancheId)) {
+            throw new SponsoredCallInputError('tranche');
+        }
+        let shares: BigNumber;
+        if (amount === 'max') {
+            // Lowercased, as `WithdrawFlow` hands `withdrawMax` the address.
+            shares = await this._userLending.getWithdrawalSharesMax(
+                trancheId,
+                userAddress.toLowerCase(),
+            );
+        } else {
+            if (!BigNumber.isBigNumber(amount) || amount.lte(0)) {
+                throw new SponsoredCallInputError('non-positive-amount');
+            }
+            shares = await this._userLending.getWithdrawalSharesForAssets(
+                trancheId,
+                amount,
+            );
+        }
+        return encodeRequestWithdrawalCall(
+            this._lendingPoolManager,
+            poolId,
+            trancheId,
+            shares,
+        );
+    }
+
+    /** `cancelDepositRequest(pool, dNftId)` — the pending deposit's NFT id. */
+    cancelDepositRequest(poolId: string, dNftId: BigNumberish): SponsoredCall {
+        return encodeCancelDepositCall(
+            this._lendingPoolManager,
+            poolId,
+            dNftId,
+        );
+    }
+
+    /** `cancelWithdrawalRequest(pool, wNftId)` — the pending withdrawal's NFT id. */
+    cancelWithdrawalRequest(
+        poolId: string,
+        wNftId: BigNumberish,
+    ): SponsoredCall {
+        return encodeCancelWithdrawalCall(
+            this._lendingPoolManager,
+            poolId,
+            wNftId,
+        );
+    }
+
+    /**
+     * `requestFixedTermDepositWithdrawal(pool, fixedTermDepositId)` — what
+     * `UserLending.withdrawAtExpiry(pool, lockId)` sends: the pool and the
+     * LOCK id, no tranche.
+     */
+    withdrawAtExpiry(
+        poolId: string,
+        fixedTermDepositId: BigNumberish,
+    ): SponsoredCall {
+        return encodeWithdrawAtExpiryCall(
+            this._lendingPoolManager,
+            poolId,
+            fixedTermDepositId,
+        );
+    }
+}

package/src/facade/chain-configs.ts

@@ -59,6 +59,7 @@ export const CHAIN_CONFIGS: Record<'base' | 'xdc' | 'xdc-usdc' | 'plume', ChainC
             'https://base-rpc.publicnode.com',
             'https://mainnet.base.org',
         ],
+        blockExplorerUrl: 'https://basescan.org',
     },
 
     xdc: {
@@ -99,6 +100,7 @@ export const CHAIN_CONFIGS: Record<'base' | 'xdc' | 'xdc-usdc' | 'plume', ChainC
             currencyCode: 'AUD',
         },
         rpcUrls: XDC_RPC_URLS,
+        blockExplorerUrl: 'https://xdcscan.com',
     },
 
     'xdc-usdc': {
@@ -132,6 +134,7 @@ export const CHAIN_CONFIGS: Record<'base' | 'xdc' | 'xdc-usdc' | 'plume', ChainC
             currencyCode: 'USD',
         },
         rpcUrls: XDC_RPC_URLS,
+        blockExplorerUrl: 'https://xdcscan.com',
     },
 
     plume: {
@@ -174,6 +177,8 @@ export const CHAIN_CONFIGS: Record<'base' | 'xdc' | 'xdc-usdc' | 'plume', ChainC
         // pointing at an endpoint nobody maintains. Pass your own
         // `signerOrProvider` to read the frozen history.
         rpcUrls: [],
+        // The explorer still serves the frozen history.
+        blockExplorerUrl: 'https://explorer.plume.org',
         retired: true,
     },
 };

package/src/facade/flows.ts

@@ -10,6 +10,7 @@ import {
     WithdrawPorts,
 } from '../flows';
 
+import { CallsFacade } from './calls';
 import { DepositsFacade } from './deposits';
 import { READ_ONLY_MESSAGE } from './read-only';
 import { KycParams } from './types';
@@ -30,8 +31,9 @@ export type DepositFlowPortOverrides = Pick<
     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.
+ * Every withdraw port has an SDK default except `getKycSignature` and
+ * `submitCall`, which have no default at all: supplying `getKycSignature`
+ * turns the KYC pre-check on, supplying `submitCall` the sponsored path.
  */
 export type WithdrawFlowPortOverrides = Partial<WithdrawPorts>;
 
@@ -81,6 +83,13 @@ export class FlowsFacade {
          * in which case a run never batches: it does not guess a token.
          */
         private readonly _stableAsset?: string,
+        /**
+         * This instance's call encoders — the sponsored withdraw path's
+         * default `encodeWithdrawal`. Optional so a hand-built facade keeps
+         * constructing; without it a sponsored run fails (`failed`, nothing
+         * sent) unless the consumer passes `encodeWithdrawal` itself.
+         */
+        private readonly _calls?: CallsFacade,
     ) {}
 
     /**
@@ -148,6 +157,9 @@ export class FlowsFacade {
     /**
      * A withdrawal pipeline. Both write ports and `buildKycParams` default to
      * this instance; supplying `getKycSignature` turns the KYC pre-check on.
+     * Supplying `submitCall` turns the sponsored path on, and its encoder
+     * defaults to `kasu.calls.requestWithdrawal` on this instance — which
+     * reads, never writes, so it works on a read-only instance too.
      * Defaults are applied per key, for the reason `deposit()` gives.
      */
     withdraw(ports: WithdrawFlowPortOverrides = {}): WithdrawFlow {
@@ -173,9 +185,18 @@ export class FlowsFacade {
                     userAddress: string,
                 ): Promise<WaitableTransaction> =>
                     this._deposits.withdrawMax(poolId, trancheId, userAddress)),
+            submitCall: ports.submitCall,
+            encodeWithdrawal: ports.encodeWithdrawal ?? this._defaultEncoder(),
         });
     }
 
+    /** `kasu.calls.requestWithdrawal`, when this facade was given the encoders. */
+    private _defaultEncoder(): WithdrawPorts['encodeWithdrawal'] {
+        const calls = this._calls;
+        if (!calls) return undefined;
+        return (params) => calls.requestWithdrawal(params);
+    }
+
     private _assertWritable(): void {
         if (this._isReadOnly) {
             throw new Error(READ_ONLY_MESSAGE);

package/src/facade/index.ts

@@ -6,6 +6,8 @@ export { StrategiesFacade } from './strategies';
 export { DepositsFacade } from './deposits';
 export { PortfolioFacade } from './user-portfolio';
 export { FlowsFacade } from './flows';
+export { CallsFacade } from './calls';
+export type { RequestWithdrawalCallParams } from './calls';
 export type {
     DepositFlowPortOverrides,
     WithdrawFlowPortOverrides,
@@ -35,4 +37,5 @@ export type {
     KycParams,
     UserPositions,
     PlatformStats,
+    StrategyRiskPerformance,
 } from './types';

package/src/facade/kasu.ts

@@ -6,6 +6,7 @@ import type { IERC20MetadataAbi } from '../contracts';
 import { KasuSdk } from '../kasu-sdk';
 import { SdkConfig, SdkConfigOptions } from '../sdk-config';
 
+import { CallsFacade } from './calls';
 import { CHAIN_CONFIGS } from './chain-configs';
 import { DepositsFacade } from './deposits';
 import { FlowsFacade } from './flows';
@@ -21,8 +22,8 @@ import { PortfolioFacade } from './user-portfolio';
 /**
  * High-level entry point for external integrators.
  *
- * Provides four domain facades — `strategies`, `deposits`, `portfolio`,
- * `flows` — and exposes the underlying `KasuSdk` services via `.services` for
+ * Provides five domain facades — `strategies`, `deposits`, `portfolio`,
+ * `flows`, `calls` — and exposes the underlying `KasuSdk` services via `.services` for
  * power-users.
  *
  * ```ts
@@ -49,6 +50,11 @@ export class Kasu {
     public readonly portfolio: PortfolioFacade;
     /** Headless deposit / withdraw state machines. */
     public readonly flows: FlowsFacade;
+    /**
+     * Encoded `LendingPoolManager` calls for a sponsored relay — withdraw,
+     * cancel, withdraw at expiry. Read, then encode; never sends.
+     */
+    public readonly calls: CallsFacade;
 
     private readonly _sdk: KasuSdk;
     private readonly _chainConfig: ChainConfigEntry;
@@ -74,6 +80,10 @@ export class Kasu {
         this.strategies = new StrategiesFacade(
             sdk.DataService,
             sdk.UserLending,
+            normaliseMapping(
+                configOverrides.poolMetadataMapping ??
+                    chainConfig.poolMetadataMapping,
+            ),
         );
 
         // Derived ONCE and handed to every facade that needs it. Each of them
@@ -93,12 +103,20 @@ export class Kasu {
             sdk.Portfolio,
         );
 
+        // The same `LendingPoolManager` the deposit flow approves and calls:
+        // the chain config's, which is what a relay allow-lists `to` against.
+        this.calls = new CallsFacade(
+            sdk.UserLending,
+            chainConfig.contracts.LendingPoolManager,
+        );
+
         this.flows = new FlowsFacade(
             this.deposits,
             () => erc20Of(chainConfig, signerOrProvider),
             isReadOnly,
             chainConfig.contracts.LendingPoolManager,
             stableAssetOf(chainConfig)?.address,
+            this.calls,
         );
     }
 
@@ -326,3 +344,14 @@ function resolveChainConfig(
     }
     return chain;
 }
+
+/** Lowercase both sides, so a lookup by any casing of a pool id matches. */
+function normaliseMapping(
+    mapping: Record<string, string> | undefined,
+): Record<string, string> {
+    const out: Record<string, string> = {};
+    for (const [from, to] of Object.entries(mapping ?? {})) {
+        out[from.toLowerCase()] = to.toLowerCase();
+    }
+    return out;
+}

package/src/facade/strategies.ts

@@ -1,6 +1,9 @@
 import { selectVisiblePools } from '../domain/pools';
 import { DataService } from '../services/DataService/data-service';
-import { PoolOverview } from '../services/DataService/types';
+import {
+    PoolDelegateProfileAndHistory,
+    PoolOverview,
+} from '../services/DataService/types';
 import { UserLending } from '../services/UserLending/user-lending';
 
 import {
@@ -8,6 +11,7 @@ import {
     FixedTermOption,
     PlatformStats,
     Strategy,
+    StrategyRiskPerformance,
     StrategyTranche,
 } from './types';
 
@@ -20,8 +24,82 @@ export class StrategiesFacade {
     constructor(
         private _dataService: DataService,
         private _userLending: UserLending,
+        /**
+         * Chain pool id → the pool id its CMS record is keyed by (XDC pools
+         * share their Base counterpart's editorial record). Lowercase keys.
+         */
+        private _poolMetadataMapping: Record<string, string> = {},
     ) {}
 
+    /**
+     * The pool's loss rate and first-loss capital, from its CMS
+     * risk-management record. `null` when the pool has no record.
+     *
+     * Each figure is a NUMBER or `null` — never a guess. The CMS returns
+     * "numeric" fields as a number, a numeric string, an empty string or
+     * null, and an empty string must not become a confident `0`: anything that
+     * is not a finite number reads as `null` (render "—"). `poolLossRate` is a
+     * 0..1 fraction.
+     *
+     * Requires `directusUrl`; without it the call rejects with
+     * `NO_DIRECTUS_URL_MESSAGE`, like every CMS-only read.
+     */
+    async getRiskPerformance(
+        poolId: string,
+    ): Promise<StrategyRiskPerformance | null> {
+        const metadataId = this._metadataIdOf(poolId);
+        const records = await this._dataService.getRiskManagement();
+        const record = records.find(
+            (r) => String(r.poolIdFK).toLowerCase() === metadataId,
+        );
+        if (!record) return null;
+        const performance = record.riskPerformance as
+            | Partial<Record<'poolLossRate' | 'firstLossCapital', unknown>>
+            | null
+            | undefined;
+        return {
+            poolLossRate: finiteOrNull(performance?.poolLossRate),
+            firstLossCapital: finiteOrNull(performance?.firstLossCapital),
+        };
+    }
+
+    /**
+     * The credit originator's profile and lending history for a pool — the
+     * CMS record whose `otherKASUPools` lists it. `null` when none does.
+     *
+     * Matched on the chain pool id, then on its metadata id, case-
+     * insensitively. The record is returned as the service maps it; its
+     * numeric fields are CMS-authored, so read them defensively.
+     *
+     * The service filters `otherKASUPools` through the CURRENT chain's
+     * subgraph with the CMS record's (Base-keyed) ids, so on an XDC
+     * deployment every profile lists no pools and this resolves `null` —
+     * the same answer kasu-ui's own lookup gives there today. The metadata
+     * candidate becomes live once the service resolves the mapping.
+     */
+    async getOriginator(
+        poolId: string,
+    ): Promise<PoolDelegateProfileAndHistory | null> {
+        const candidates = new Set([
+            poolId.toLowerCase(),
+            this._metadataIdOf(poolId),
+        ]);
+        const profiles =
+            await this._dataService.getPoolDelegateProfileAndHistory();
+        return (
+            profiles.find((profile) =>
+                profile.otherKASUPools.some((pool) =>
+                    candidates.has(String(pool.id).toLowerCase()),
+                ),
+            ) ?? null
+        );
+    }
+
+    private _metadataIdOf(poolId: string): string {
+        const lower = poolId.toLowerCase();
+        return (this._poolMetadataMapping[lower] ?? lower).toLowerCase();
+    }
+
     /**
      * Fetch all active lending strategies.
      *
@@ -96,13 +174,12 @@ export class StrategiesFacade {
     calculateDepositLimits(tranche: StrategyTranche): DepositLimits {
         const raw = tranche._raw;
         const min =
-            parseFloat(raw.minimumDeposit) < 1
-                ? '1'
-                : raw.minimumDeposit;
+            parseFloat(raw.minimumDeposit) < 1 ? '1' : raw.minimumDeposit;
 
-        const max = parseFloat(raw.maximumDeposit) > parseFloat(raw.poolCapacity)
-            ? raw.poolCapacity
-            : raw.maximumDeposit;
+        const max =
+            parseFloat(raw.maximumDeposit) > parseFloat(raw.poolCapacity)
+                ? raw.poolCapacity
+                : raw.maximumDeposit;
 
         return {
             min,
@@ -153,3 +230,17 @@ export class StrategiesFacade {
         };
     }
 }
+
+/**
+ * A CMS "numeric" field as a finite number, or `null`. An empty or blank
+ * string is UNAUTHORED, not zero.
+ */
+function finiteOrNull(value: unknown): number | null {
+    if (typeof value === 'number') return Number.isFinite(value) ? value : null;
+    if (typeof value === 'string') {
+        if (value.trim() === '') return null;
+        const numeric = Number(value);
+        return Number.isFinite(numeric) ? numeric : null;
+    }
+    return null;
+}

package/src/facade/types.ts

@@ -66,6 +66,13 @@ export interface ChainConfigEntry {
      * Empty on a retired deployment, which has no read-only default.
      */
     rpcUrls: string[];
+    /**
+     * Origin of the chain's block explorer, `https://…` with NO trailing
+     * slash (`https://basescan.org`). Never append a path to it by hand: build
+     * links with `explorerTxUrl` / `explorerAddressUrl`, which validate the
+     * hash or address first, so no app turns an unchecked string into a URL.
+     */
+    blockExplorerUrl: string;
     /**
      * True for a wound-down deployment kept only as frozen history. It has no
      * default RPC, so a read-only `Kasu.create` on it throws.
@@ -224,3 +231,15 @@ export interface UserPositions {
 // ---------------------------------------------------------------------------
 
 export type PlatformStats = LendingTotals;
+
+/**
+ * A strategy's risk figures, from its CMS risk-management record
+ * (`kasu.strategies.getRiskPerformance`). Each is `null` when unauthored or
+ * not a finite number — render "—", never `0`.
+ */
+export interface StrategyRiskPerformance {
+    /** Realised loss rate, a 0..1 fraction. */
+    poolLossRate: number | null;
+    /** First-loss capital, exactly as the CMS record authors it. */
+    firstLossCapital: number | null;
+}