@kasufinance/kasu-sdk 2.7.1 → 2.10.0

package/README.md

@@ -100,13 +100,14 @@ a read-only `Kasu.create({ chain: 'plume' })` throws — pass your own provider
 read its history.
 
 Every entry lives in `CHAIN_CONFIGS`, including contract addresses, subgraph
-URLs, the stable asset and public RPC defaults:
+URLs, the stable asset, public RPC defaults and the block explorer:
 
 ```ts
-import { CHAIN_CONFIGS } from '@kasufinance/kasu-sdk';
+import { CHAIN_CONFIGS, explorerTxUrl } from '@kasufinance/kasu-sdk';
 
 CHAIN_CONFIGS.base.stableAsset; // { address, symbol, name, decimals, currencyCode }
 CHAIN_CONFIGS.xdc.rpcUrls; // starting preference only — override with your own
+explorerTxUrl(CHAIN_CONFIGS.base, txHash); // https://basescan.org/tx/0x… — throws on a malformed hash
 ```
 
 You can also pass a whole `ChainConfigEntry` instead of a chain key.
@@ -115,10 +116,11 @@ You can also pass a whole `ChainConfigEntry` instead of a chain key.
 
 | Facade            | Methods                                                                                                                 | Purpose                         |
 | ----------------- | ----------------------------------------------------------------------------------------------------------------------- | ------------------------------- |
-| `kasu.strategies` | `getAll()`, `getVisible()`, `getById()`, `getPlatformStats()`, `getPerformanceFeePercent()`, `calculateDepositLimits()` | Browse pools, APY, capacity     |
+| `kasu.strategies` | `getAll()`, `getVisible()`, `getById()`, `getPlatformStats()`, `getPerformanceFeePercent()`, `calculateDepositLimits()`, `getRiskPerformance(poolId)`, `getOriginator(poolId)` | Browse pools, APY, capacity, risk, originator |
 | `kasu.deposits`   | `deposit()`, `withdraw()`, `withdrawMax()`, `buildKycParams()`, `isClearingPending()`                                   | Submit transactions             |
 | `kasu.portfolio`  | `getPositions()`, `getTransactionHistory()`, `getRequestStates()`                                                       | Lender balances, yield, history |
 | `kasu.flows`      | `deposit(ports)`, `withdraw(ports?)`                                                                                    | Headless transaction pipelines  |
+| `kasu.calls`      | `requestWithdrawal(params)`, `cancelDepositRequest(poolId, dNftId)`, `cancelWithdrawalRequest(poolId, wNftId)`, `withdrawAtExpiry(poolId, lockId)` | Encoded calls for a sponsored relay (read, then encode — never sends) |
 
 On the instance itself: `kasu.connect(signer)`, `kasu.isReadOnly`,
 `kasu.provider`, `kasu.chainConfig`, `kasu.isLiteDeployment`, and
@@ -142,7 +144,10 @@ application formats them in its own design system and language.
 | Tranches             | `trancheHasCapacity`, `poolAllTranchesFull`, `derivePoolStatus`, `trancheRiskRank`, `compareTrancheSeniority`, `pickDefaultTrancheId`, `trancheApyBounds`, `netTrancheApyBounds`, `MIN_TRANCHE_CAPACITY` |
 | Deposit bounds       | `resolveDepositBounds`, `resolveBoundShortcuts`, `isBelowMinimumCapacity`, `parseTrancheBound`, `floorToCents`, `ceilToCents`                                                                            |
 | Pools                | `selectVisiblePools`, `poolMaxApy`, `pickHighestYieldTranche`, `maxNetRateCeiling`                                                                                                                       |
-| Partners             | `getCreditOriginator`, `getInstitutionalLender`, `APXIUM`, `INVOICEMATE`, `RIXON_CAPITAL`                                                                                                                |
+| Partners             | `getCreditOriginator`, `getInstitutionalLender`, `getStrategyRegion`, `APXIUM`, `INVOICEMATE`, `RIXON_CAPITAL` (each with a `region`)                                                                  |
+| Fixed term           | `availableFixedTermConfigs`, `isFixedTermConfigId`, `lockDurationDays`, `lockDurationMonths`, `DAYS_PER_EPOCH`, `DAYS_PER_MONTH`, `MIN_DAYS_FOR_MONTHS`                                               |
+| Yields               | `weeklyInterest`, `dailyInterest`, `accruedInterest`, `projectedAnnualEarnings`, `weightedAverageApy`, `SECONDS_PER_WEEK` — NET of the performance fee                                               |
+| Batch proof          | `validateDepositBatchCalls`, `proveDepositInReceipt`, `DepositBatchMismatchError`, `ENTRY_POINT_V07`                                                                                                   |
 | Tranche display name | `getTrancheDisplayName`, `UPPER_MEZZANINE`                                                                                                                                                               |
 | Requests             | `deriveRequestState`, `submissionEvents`, `countSubmissions`, `firstSubmissionTimestamp`, `isCycleClosed`                                                                                                |
 | Settlement           | `computeSettlementWindow`, `nextCycleBoundary`, `deriveCycleDates`, `CLEARING_WINDOW_SECONDS`                                                                                                            |
@@ -225,8 +230,103 @@ await flow.acceptContract(); // signs it and carries on
 // or: flow.declineContract();  → phase 'declined', nothing submitted
 ```
 
+### One atomic transaction: the `depositBatch` port
+
+If your application can submit several calls as ONE atomic transaction (all
+apply or none does), supply the optional `depositBatch` port. When the
+allowance is short, the run then approves and deposits in a single batch
+instead of two transactions. You decide how the batch is sent; the SDK decides
+what is in it:
+
+```ts
+import { BatchRevertedError, type BatchCall } from '@kasufinance/kasu-sdk';
+
+const flow = kasu.flows.deposit({
+    signMessage,
+    generateContract,
+    getKycSignature,
+    depositBatch: async (calls: BatchCall[]) => {
+        // calls[0]: stableAsset.approve(LendingPoolManager, amount) — EXACT amount
+        // calls[1]: LendingPoolManager.requestDepositWithKyc(…) — value 0
+        const tx = await submitAtomically(calls); // your mechanism
+        return tx; // anything with wait()
+        // Known to revert? throw new BatchRevertedError('ClearingIsPending')
+    },
+});
+
+// …after acceptContract(), a batched run parks on `awaiting-authorise`:
+flow.authoriseTransfer(); // the lender's explicit go-ahead
+// or: flow.declineTransfer(); → error { step: 'request', reason: 'cancelled' }
+```
+
+- The batch path is taken only when the allowance is short, the port is
+  supplied and the chain's stable token is known (`kasu.flows.deposit()` fills
+  it from the chain config). Otherwise the run is exactly the two-transaction
+  pipeline.
+- A batch has no wallet prompt per call, so the run **parks for an explicit
+  authorisation** before any money moves. The agreement's TTL is checked again
+  after it, and the KYC signature is fetched only then.
+- `state.batched` is `true` from the first state of a batched run. It never
+  enters `approve`, so it counts as a three-step run (`stepTotal` 3).
+- Throw `BatchRevertedError(revertError)` when the batch is known to revert →
+  `{ step: 'request', reason: 'reverted', revertError }`. Throw a
+  `BatchSubmissionError` (or `BatchPendingError`) to report a submission
+  outcome: `pending` → `{ reason: 'pending' }`, `already-submitted` →
+  `{ reason: 'already-submitted' }`, `failed` → `{ reason: 'failed' }` — read
+  at its word, never through the revert decoder. Any other throw is read like a
+  direct deposit's: a wallet rejection is `cancelled`, everything else
+  `failed`.
+
+### Submitting a sponsored batch: `submitBatch` (2.9.0)
+
+For a submitter that relays the batch and is asked for its status later (a
+sponsored-gas relay, for one), `submitBatch` owns the polling policy, the
+receipt proof and the outcome taxonomy. Your ports do the I/O; the SDK decides
+what each answer means:
+
+```ts
+import {
+    submitBatch,
+    validateDepositBatchCalls,
+} from '@kasufinance/kasu-sdk';
+
+depositBatch: (calls) => {
+    // Before signing: the batch is exactly this run's deposit, or it throws.
+    const { tranche, amount } = validateDepositBatchCalls(calls, {
+        stableAsset, spender, poolId, trancheId, amount, fixedTermConfigId,
+    });
+    return submitBatch(
+        // `pendingPool` is the strategy's pending pool (`ILendingPool.pendingPool()`):
+        // with it, only THAT contract's `DepositRequested` can prove the deposit.
+        { calls, expect: { lender, tranche, amount, pendingPool } },
+        {
+            post: (calls) => postToMyRelay(calls), // → { transactionId }
+            getStatus: (id) => readMyRelayStatus(id), // normalised BatchStatusRead
+            getReceipt: (hash) => provider.waitForTransaction(hash, 1, 120_000),
+            now: Date.now,
+            sleep: (ms) => new Promise((r) => setTimeout(r, ms)),
+        },
+    );
+},
+```
+
+- **An ambiguous result is never reported as failed.** Once the batch has been
+  posted only a revert proves nothing was deposited; a timeout, an unreadable
+  receipt, an unknown status or an unrecognised `post` error is a
+  `BatchPendingError`, and the run ends `{ reason: 'pending' }`. Tell the
+  lender it may still be processing — never "try again".
+- `wait()` resolves only when `proveDepositInReceipt` finds THIS lender's
+  `DepositRequested` for the expected tranche AND amount inside their own user
+  operation — and, when `pendingPool` is given, emitted by that contract. A
+  handleOps receipt's `status` decides nothing.
+- Polling: first read at once, then 3 s ×1.5 to a 10 s ceiling, for 10 minutes
+  (`DEFAULT_BATCH_POLLING_POLICY`; pass a partial policy to override).
+- `checkBatchOutcome(transactionId, expect, ports)` is the one-read check for an
+  app's guard against lending twice after a `pending` run.
+
 **Phases** — `idle`, `generating-sign`, `generating-fetch`, `awaiting-accept`,
-`accepting-sign`, `approve`, `request-sign`, `request-confirm`, and the
+`accepting-sign`, `approve`, `awaiting-authorise` (batch path only),
+`request-sign`, `request-confirm`, and the
 terminal `success` / `declined` / `error`. Each maps to one of four steps
 (`generate`, `confirm`, `approve`, `request`); `stepIndex` and `stepTotal` are
 published because the approve step drops out of the sequence when the allowance
@@ -246,7 +346,12 @@ type DepositFailure =
           revertError: string; // e.g. 'ClearingIsPending'
           error: unknown;
       }
-    | { step: 'request'; reason: 'contract-expired' }; // the 5-minute TTL
+    | { step: 'request'; reason: 'contract-expired' } // the 5-minute TTL
+    | {
+          step: 'request';
+          reason: 'pending' | 'already-submitted'; // batch path only — NOT failures
+          error: unknown;
+      };
 ```
 
 A wallet rejection is `cancelled`, not a failure: the lender changed their
@@ -328,7 +433,57 @@ const checked = kasu.flows.withdraw({
 ```
 
 `'max'` is a code you pass, not a balance you read: it routes to the all-shares
-call, which resolves the balance on chain at execution.
+request, whose share count the SDK reads (`balanceOf`) at submission instead of
+converting an asset figure — so no dust is stranded.
+
+### Sponsored withdraw and cancel (2.10.0)
+
+`kasu.calls` encodes the single `LendingPoolManager` calls a gas-sponsoring
+relay carries. Each returns `{ kind, call }`: post `kind` and `[call]` exactly
+as given — the relay judges the call by its kind, so never map one yourself.
+
+```ts
+import { submitSponsoredCall } from '@kasufinance/kasu-sdk';
+
+const ports = {
+    post: ({ kind, call }) => postToMyRelay({ kind, calls: [call] }), // → { transactionId }
+    getStatus: (id) => readMyRelayStatus(id), // normalised BatchStatusRead
+    getReceipt: (hash) => provider.waitForTransaction(hash, 1, 120_000),
+    now: Date.now,
+    sleep: (ms) => new Promise((r) => setTimeout(r, ms)),
+};
+
+// Withdraw: the flow encodes the call (shares from convertToShares, or the
+// whole balanceOf for 'max') and submits it through your port.
+const flow = kasu.flows.withdraw({
+    submitCall: (call) =>
+        submitSponsoredCall({ call, expect: { sender: lender } }, ports),
+});
+flow.state.sponsored; // true, from the first state
+await flow.start({ poolId, trancheId, amount: 'max', userAddress: lender });
+
+// Cancel: encode, then submit the same way.
+const cancel = kasu.calls.cancelDepositRequest(poolId, dNftId);
+const submission = await submitSponsoredCall(
+    { call: cancel, expect: { sender: lender } },
+    ports,
+);
+await submission.wait(); // resolves only when the lender's operation executed
+```
+
+- `submitSponsoredCall` is `submitBatch` for one call: the same polling policy
+  and outcome table, with `proveUserOperationInReceipt` as the proof — the
+  lender's own operation, from the EntryPoint, with `success` set. A reverted
+  operation is `BatchRevertedError`; anything unproven is `BatchPendingError`.
+- On the sponsored path a withdrawal's failure can also be `{ reason:
+  'reverted', revertError }` and `{ reason: 'pending' | 'already-submitted' }`.
+  A wallet rejection thrown by `submitCall` (the lender declined to sign) is
+  `cancelled`. Any other throw from `submitCall` or `wait()` the SDK does not
+  recognise is `pending` — it may have left, so never tell the lender to try
+  again. A throw while encoding (a share read, an empty position) is `failed`:
+  nothing was sent.
+- `cancelDeadline(requestState, nextEpochStart, nowSeconds)` is the "cancel
+  until" instant for a pending request (the next cycle close), or `null`.
 
 ## Low-level `KasuSdk`