@kasufinance/kasu-sdk 2.7.0 → 2.7.1

package/README.md

@@ -147,7 +147,8 @@ application formats them in its own design system and language.
 | Requests             | `deriveRequestState`, `submissionEvents`, `countSubmissions`, `firstSubmissionTimestamp`, `isCycleClosed`                                                                                                |
 | Settlement           | `computeSettlementWindow`, `nextCycleBoundary`, `deriveCycleDates`, `CLEARING_WINDOW_SECONDS`                                                                                                            |
 | Loan contract        | `encodeDepositData`, `buildContractVersionType`, `buildLoanAgreementSignMessage`, `buildLegacyContractRequestMessage`, `buildFullNameRequestMessage`, `formatSignTimestampUtc`, `parseFormattedMessage`, `asContractType` |
-| Wallet errors        | `isUserRejected`, `isUnpredictableGas`                                                                                                                                                                   |
+| Wallet errors        | `isUserRejected`, `isUnpredictableGas`, `classifyWalletFailure`                                                                                                                                          |
+| Revert errors        | `decodeRevert`, `extractRevertData` — the bytes a reverted call came back with, read as the custom error the contract named                                                                              |
 | AU minimum           | `auMinimumRemaining`, `isAustralianKyc`, `auThresholdFor`, `isAuMinimumExempt`, `parseMinorUnits`, `AU_ALPHA3`, `AU_MIN_CUMULATIVE_BY_STABLE`                                                            |
 
 Three rules worth knowing:
@@ -239,14 +240,51 @@ type DepositFailure =
     | { step: DepositStep; reason: 'cancelled' } // isUserRejected
     | { step: DepositStep; reason: 'failed'; error: unknown }
     | { step: 'request'; reason: 'insufficient-balance'; error: unknown }
+    | {
+          step: 'request';
+          reason: 'reverted';
+          revertError: string; // e.g. 'ClearingIsPending'
+          error: unknown;
+      }
     | { step: 'request'; reason: 'contract-expired' }; // the 5-minute TTL
 ```
 
 A wallet rejection is `cancelled`, not a failure: the lender changed their
-mind, and telling them something broke would be a lie. A reverted gas estimate
-on the request step is `insufficient-balance` — nothing was refused, so a retry
-would only reproduce it. Everything else is `failed` and carries the original
-error for your crash reporter.
+mind, and telling them something broke would be a lie. Everything else is
+`failed` and carries the original error for your crash reporter.
+
+A revert on the request step is read for WHAT reverted. `requestDepositWithKyc`
+reverts for a family of reasons the ABI declares — `LendingPoolIsStopped`,
+`ClearingIsPending`, `InvalidTranche`, `UserNotKycd`, `UserBlocked`,
+`UserNotInAllowList`, `BlockExpired` — and none of them is a shortfall. Those
+come back as `reverted`, with `revertError` naming the contract error. Only a
+token balance or allowance failure, or revert data nothing can decode, is
+`insufficient-balance`.
+
+**Render `reverted` with generic copy and special-case only the names you have
+words for.** A contract upgrade can add an error, so treat the set as open: a
+consumer that assumed it was closed has nothing to show for a new one.
+`decodeRevert(err)` is exported if you want the same reading elsewhere.
+
+```ts
+if (failure.reason === 'reverted') {
+    switch (failure.revertError) {
+        case 'ClearingIsPending':
+            return t('deposit.error.clearing');
+        case 'UserNotKycd':
+            return t('deposit.error.kyc');
+        default:
+            return t('deposit.error.rejectedOnChain'); // generic
+    }
+}
+```
+
+**Both personal signs are length-checked where they are taken.** A wallet is
+not obliged to return 65 bytes and the ABI coder will not catch one that does
+not — `0x` encodes into `depositData` as happily as a real signature does, and
+the agreements service could then never verify the deposit. A malformed auth
+signature fails the `generate` step and a malformed acceptance signature fails
+`confirm`, both as `failed`, before anything is broadcast.
 
 Three guarantees worth knowing:
 

package/dist/bundle.cjs.js

@@ -20837,12 +20837,12 @@ function toURLEncodedForm(data, options) {
   });
 }
 
-const MAX_DEPTH = DEFAULT_FORM_DATA_MAX_DEPTH;
+const MAX_DEPTH$1 = DEFAULT_FORM_DATA_MAX_DEPTH;
 
 function throwIfDepthExceeded(index) {
-  if (index > MAX_DEPTH) {
+  if (index > MAX_DEPTH$1) {
     throw new AxiosError$1(
-      'FormData field is too deeply nested (' + index + ' levels). Max depth: ' + MAX_DEPTH,
+      'FormData field is too deeply nested (' + index + ' levels). Max depth: ' + MAX_DEPTH$1,
       AxiosError$1.ERR_FORM_DATA_DEPTH_EXCEEDED
     );
   }
@@ -24806,6 +24806,193 @@ function buildFullNameRequestMessage(address, timestampMs) {
     return `I request my full name for ${address.toLowerCase()} at ${timestampMs}.`;
 }
 
+// ---------------------------------------------------------------------------
+// The selector tables
+// ---------------------------------------------------------------------------
+/**
+ * OpenZeppelin v5's ERC-20 errors. They are not in either Kasu ABI because no
+ * Kasu contract declares them — they arrive from the TOKEN, through the
+ * manager's `transferFrom`, and they are the modern spelling of the string
+ * reverts below.
+ */
+const ERC20_ERROR_ABI = [
+    'error ERC20InsufficientBalance(address sender, uint256 balance, uint256 needed)',
+    'error ERC20InsufficientAllowance(address spender, uint256 allowance, uint256 needed)',
+];
+/**
+ * The protocol errors that mean the ERC-20 transfer failed rather than the
+ * protocol refusing.
+ *
+ * `SafeERC20FailedOperation` is OpenZeppelin's wrapper around a token call
+ * that returned false or reverted, which on this path IS the `transferFrom`;
+ * `AddressInsufficientBalance` is its native-value sibling. Both belong with
+ * the balance case, not with the pool conditions — a lender who sees one of
+ * them really does need to fund or re-approve.
+ */
+const ERC20_FAMILY_NAMES = new Set([
+    'AddressInsufficientBalance',
+    'ERC20InsufficientAllowance',
+    'ERC20InsufficientBalance',
+    'SafeERC20FailedOperation',
+]);
+/** Solidity's `Error(string)`, the selector every `require` reason arrives under. */
+const STRING_REVERT_SELECTOR = '0x08c379a0';
+/**
+ * The `require` reasons that are a balance or an allowance, across the token
+ * implementations in circulation: OpenZeppelin v4's sentences, and the
+ * shorthand the minimal implementations use.
+ */
+const ERC20_REASON_PATTERNS = [
+    /exceeds\s+balance/,
+    /exceeds\s+allowance/,
+    /insufficient\s+balance/,
+    /insufficient\s+allowance/,
+    /transfer_from_failed/,
+    /transferfrom\s+failed/,
+    /low-level\s+call\s+failed/,
+];
+/**
+ * selector → error name, built once on first use.
+ *
+ * Lazily, because a consumer that never sees a revert should not pay for three
+ * `Interface` constructions at import. The two Kasu tables are the GENERATED
+ * typechain ABIs, so this cannot drift from the contracts: regenerate the ABIs
+ * and the new errors are recognised with no edit here.
+ */
+let selectorTable = null;
+function selectors() {
+    if (selectorTable)
+        return selectorTable;
+    const table = new Map();
+    const interfaces = [
+        // The manager the deposit is called against, and the allow list it
+        // delegates the KYC and block-window checks to.
+        ILendingPoolManagerAbi__factory.createInterface(),
+        IKasuAllowListAbi__factory.createInterface(),
+        new ethers.ethers.utils.Interface(ERC20_ERROR_ABI),
+    ];
+    for (const iface of interfaces) {
+        for (const fragment of Object.values(iface.errors)) {
+            // First writer wins: the same name declared by both ABIs is the
+            // same selector, so the duplicate would be a no-op anyway.
+            const sighash = iface.getSighash(fragment);
+            if (!table.has(sighash))
+                table.set(sighash, fragment.name);
+        }
+    }
+    selectorTable = table;
+    return table;
+}
+// ---------------------------------------------------------------------------
+// Getting the bytes out of the envelope
+// ---------------------------------------------------------------------------
+/**
+ * How deep to look for the revert data. Providers nest it differently —
+ * ethers' own error wraps the provider's, which wraps the RPC body — and a
+ * bound is what keeps a self-referencing error object from being walked
+ * forever.
+ */
+const MAX_DEPTH = 6;
+/** The keys ethers and the providers under it put a wrapped error on. */
+const NESTED_KEYS = [
+    'data',
+    'error',
+    'originalError',
+    'info',
+    'cause',
+    'body',
+];
+/** At least a 4-byte selector, and a whole number of bytes. */
+function isRevertData(value) {
+    return (value.length >= 10 &&
+        value.length % 2 === 0 &&
+        /^0x[0-9a-fA-F]+$/.test(value));
+}
+/**
+ * Find the revert data on an error, wherever the provider left it.
+ *
+ * ethers v5 raises `UNPREDICTABLE_GAS_LIMIT` with the provider's own error
+ * attached, and each provider nests the bytes one layer differently:
+ * `error.data`, `error.error.data`, `error.data.originalError.data`, or only
+ * inside the JSON `body` of a `SERVER_ERROR`. Rather than enumerate the
+ * products, walk a fixed set of keys to a fixed depth and take the first value
+ * that is shaped like revert data.
+ */
+function extractRevertData(err) {
+    return walk(err, 0);
+}
+function walk(node, depth) {
+    if (node == null || depth > MAX_DEPTH)
+        return null;
+    if (typeof node === 'string') {
+        if (isRevertData(node))
+            return node;
+        // A `SERVER_ERROR`'s body: the RPC's JSON reply, verbatim.
+        if (!node.startsWith('{'))
+            return null;
+        try {
+            return walk(JSON.parse(node), depth + 1);
+        }
+        catch (_a) {
+            return null;
+        }
+    }
+    if (typeof node !== 'object')
+        return null;
+    const record = node;
+    for (const key of NESTED_KEYS) {
+        const found = walk(record[key], depth + 1);
+        if (found)
+            return found;
+    }
+    return null;
+}
+// ---------------------------------------------------------------------------
+// Decoding
+// ---------------------------------------------------------------------------
+/**
+ * Decode a failed call's revert into the error the contract named, or `null`
+ * when there is nothing recognisable to name.
+ *
+ * `null` is the honest answer for an unknown selector, an unrelated `require`
+ * string, or an error with no revert data at all — the caller keeps whatever
+ * it did before rather than inventing a diagnosis from bytes it cannot read.
+ */
+function decodeRevert(err) {
+    const data = extractRevertData(err);
+    if (!data)
+        return null;
+    const selector = data.slice(0, 10).toLowerCase();
+    if (selector === STRING_REVERT_SELECTOR) {
+        const reason = decodeStringRevert(data);
+        if (reason === null)
+            return null;
+        return isErc20Reason(reason)
+            ? { name: 'Error', family: 'erc20', reason }
+            : null;
+    }
+    const name = selectors().get(selector);
+    if (!name)
+        return null;
+    return {
+        name,
+        family: ERC20_FAMILY_NAMES.has(name) ? 'erc20' : 'protocol',
+    };
+}
+function decodeStringRevert(data) {
+    try {
+        const [reason] = ethers.ethers.utils.defaultAbiCoder.decode(['string'], `0x${data.slice(10)}`);
+        return reason;
+    }
+    catch (_a) {
+        return null;
+    }
+}
+function isErc20Reason(reason) {
+    const lower = reason.toLowerCase();
+    return ERC20_REASON_PATTERNS.some((pattern) => pattern.test(lower));
+}
+
 /**
  * Wallet and RPC error predicates — pure functions over `unknown`.
  *
@@ -24965,6 +25152,22 @@ function classifyWalletFailure(step, err) {
 const CONTRACT_TTL_MS = 5 * 60 * 1000;
 /** What a run without a spender, from either source, fails with. */
 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. */
+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. */
+const INVALID_ACCEPTANCE_SIGNATURE_MESSAGE = 'DepositFlow: the wallet returned a malformed acceptance signature; expected 65 bytes of 0x-prefixed hex';
+/**
+ * Is this an EIP-191 personal sign, in the only shape the protocol accepts?
+ *
+ * 65 bytes — `r`, `s`, `v` — 0x-prefixed. Nothing downstream checks it: the
+ * ABI coder takes any even-length hex as `bytes`, so `'0x'` and a 64-byte
+ * string both encode happily into a `depositData` the agreements service then
+ * cannot verify against anything. The check has to happen where the signature
+ * is taken, which is here.
+ */
+function isPersonalSignature(signature) {
+    return ethers.utils.isHexString(signature, 65);
+}
 const INITIAL$1 = {
     phase: 'idle',
     step: null,
@@ -24989,13 +25192,32 @@ function badgeFor(step, approvalRequired) {
     };
 }
 /**
- * The request step has a third outcome. `UNPREDICTABLE_GAS_LIMIT` here is
- * almost always `transferFrom` reverting on a balance that cannot cover the
- * deposit, and it takes precedence: nothing was refused by the lender, so
- * inviting a retry would just reproduce it.
+ * The request step's extra outcomes, in the order the evidence supports.
+ *
+ * A revert is read for WHAT reverted before it is read as a shortfall.
+ * `requestDepositWithKyc` reverts for a whole family of declared reasons —
+ * `LendingPoolIsStopped`, `ClearingIsPending`, `UserNotKycd`, `UserBlocked`,
+ * `UserNotInAllowList`, `InvalidTranche`, `BlockExpired` — and every one of
+ * them used to arrive as `insufficient-balance`, which told a fully funded
+ * lender to top up a wallet that was never short while their pool was simply
+ * mid-clearing. So: a decoded protocol error is `reverted` and names itself.
+ *
+ * Only a token balance or allowance failure — or revert data nothing can
+ * decode, on the `UNPREDICTABLE_GAS_LIMIT` ethers raises for a failed gas
+ * estimate — is still `insufficient-balance`, which is the case that reason
+ * was named for and the one where topping up is genuinely the answer.
  */
 function classifyRequest(err) {
-    if (isUnpredictableGas(err)) {
+    const revert = decodeRevert(err);
+    if ((revert === null || revert === void 0 ? void 0 : revert.family) === 'protocol') {
+        return {
+            step: 'request',
+            reason: 'reverted',
+            revertError: revert.name,
+            error: err,
+        };
+    }
+    if (revert !== null || isUnpredictableGas(err)) {
         return { step: 'request', reason: 'insufficient-balance', error: err };
     }
     return classifyWalletFailure('request', err);
@@ -25047,6 +25269,18 @@ class DepositFlow extends Flow {
             this._store.patch(Object.assign({ phase: 'accepting-sign' }, badgeFor('confirm', this._store.state.approvalRequired)), token);
             try {
                 const signature = yield this._ports.signMessage(contract.contractMessage);
+                // Checked HERE, not at the encoder: this is the signature the
+                // agreements service verifies the deposit against, and a wallet
+                // that returned something other than 65 bytes has not signed
+                // anything. Failing the confirm step names the step that produced
+                // it; letting it through would put an unverifiable blob on chain.
+                if (!isPersonalSignature(signature)) {
+                    bridge.settle({
+                        kind: 'failed',
+                        error: new Error(INVALID_ACCEPTANCE_SIGNATURE_MESSAGE),
+                    });
+                    return;
+                }
                 bridge.settle({ kind: 'accepted', signature });
             }
             catch (err) {
@@ -25140,6 +25374,18 @@ class DepositFlow extends Flow {
                 this._fail(token, approvalRequired, classifyWalletFailure('generate', err));
                 return;
             }
+            // The same EIP-191 shape as the acceptance, and the same reason to
+            // check it: kasu-backend verifies this one to decide whether to issue
+            // an agreement at all, so a malformed signature is a 4xx that says
+            // nothing about which step produced it. Named here instead.
+            if (!isPersonalSignature(signature)) {
+                this._fail(token, approvalRequired, {
+                    step: 'generate',
+                    reason: 'failed',
+                    error: new Error(INVALID_AUTH_SIGNATURE_MESSAGE),
+                });
+                return;
+            }
             if (!this._store.isCurrent(token))
                 return;
             // 3. Generate — POST the request.
@@ -25196,12 +25442,29 @@ class DepositFlow extends Flow {
                 });
                 return;
             }
-            const depositData = encodeDepositData({
-                signature: outcome.signature,
-                timestamp: contract.timestamp,
-                contractVersion: contract.contractVersion,
-                contractType: asContractType(contract.contractType),
-            });
+            // The acceptance signature is already known to be 65 bytes, but the
+            // encoder also reads `timestamp`, `contractVersion` and
+            // `contractType` off a response the SDK did not produce. `start()`
+            // promises it does not reject, so anything that throws in here becomes
+            // a failure the consumer can render rather than an unhandled rejection
+            // in an application that was told it never had to catch one.
+            let depositData;
+            try {
+                depositData = encodeDepositData({
+                    signature: outcome.signature,
+                    timestamp: contract.timestamp,
+                    contractVersion: contract.contractVersion,
+                    contractType: asContractType(contract.contractType),
+                });
+            }
+            catch (err) {
+                this._fail(token, approvalRequired, {
+                    step: 'request',
+                    reason: 'failed',
+                    error: err,
+                });
+                return;
+            }
             // 6. Approve — the EXACT amount, never `MaxUint256`. House rule: an
             //    unlimited allowance outlives the deposit it was granted for, and a
             //    later exploit of the spender would drain a wallet that has long
@@ -26901,6 +27164,8 @@ exports.EPOCHS_IN_YEAR = EPOCHS_IN_YEAR;
 exports.Flow = Flow;
 exports.FlowStore = FlowStore;
 exports.FlowsFacade = FlowsFacade;
+exports.INVALID_ACCEPTANCE_SIGNATURE_MESSAGE = INVALID_ACCEPTANCE_SIGNATURE_MESSAGE;
+exports.INVALID_AUTH_SIGNATURE_MESSAGE = INVALID_AUTH_SIGNATURE_MESSAGE;
 exports.INVOICEMATE = INVOICEMATE;
 exports.Kasu = Kasu;
 exports.KasuSdk = KasuSdk;
@@ -26930,11 +27195,13 @@ exports.classifyWalletFailure = classifyWalletFailure;
 exports.compareTrancheSeniority = compareTrancheSeniority;
 exports.computeSettlementWindow = computeSettlementWindow;
 exports.countSubmissions = countSubmissions;
+exports.decodeRevert = decodeRevert;
 exports.deriveCycleDates = deriveCycleDates;
 exports.derivePoolStatus = derivePoolStatus;
 exports.deriveRequestState = deriveRequestState;
 exports.encodeDepositData = encodeDepositData;
 exports.epochRateToApy = epochRateToApy;
+exports.extractRevertData = extractRevertData;
 exports.fetchUnusedPoolIds = fetchUnusedPoolIds;
 exports.firstSubmissionTimestamp = firstSubmissionTimestamp;
 exports.floorToCents = floorToCents;