@trustware/sdk-staging 1.1.12-staging.5 → 1.1.12-staging.7

package/README.md

@@ -39,20 +39,32 @@ The current widget flow is:
 
 ## Installation
 
-Supports React `18.2+` and `19`.
-
 ```bash
 npm install @trustware/sdk
 # or
 pnpm add @trustware/sdk
 ```
 
+Supports React `18.2+` and `19`.
+
 ## Main Exports
 
 - `TrustwareProvider`
+- `useTrustware`
 - `TrustwareWidget`
 - `Trustware`
-- `useTrustware`
+- `TrustwareError`
+- `RateLimitError`
+- `assertValidPostHook`
+- `walletManager`
+- `useWalletDetection`
+- `useWalletInfo`
+- `connectDetectedWallet`
+- `WagmiBridge`
+- `useWagmi`
+- `useEIP1193`
+- `WALLETS`
+- `./identity`, `./validation/address`, `./types`, `./constants`
 
 ## Quick Start
 
@@ -102,6 +114,7 @@ type TrustwareConfigOptions = {
     toChain: string;
     toToken: string;
     fromToken?: string;
+    fromChain?: string;
     fromAddress?: string;
     toAddress?: string;
     defaultSlippage?: number;
@@ -156,10 +169,14 @@ type TrustwareConfigOptions = {
 - `routes.toChain`: destination chain key or chain id string.
 - `routes.toToken`: destination token address or registry token identifier.
 - `routes.fromToken`: optional source token preference.
+- `routes.fromChain`: optional source chain preference.
 - `routes.fromAddress`: optional source wallet override.
 - `routes.toAddress`: optional destination address override.
 - `routes.defaultSlippage`: optional slippage percentage. Defaults to `1`.
 
+Chain and token fields are strings, including numeric chain ids — `"8453"`, not
+`8453`.
+
 ### Route Options
 
 - `routes.options.routeRefreshMs`: auto-refresh cadence for route previews.
@@ -169,14 +186,15 @@ type TrustwareConfigOptions = {
 
 ### Other Config Groups
 
-- `autoDetectProvider`: enables Trustware-managed wallet discovery.
+- `autoDetectProvider`: enables Trustware-managed wallet discovery. Defaults to
+  `false` — set it to `true` if you are not attaching a wallet yourself.
 - `theme`: widget color mode — `"light" | "dark" | "system"` (default
   `"system"`). Switch it at runtime with `Trustware.setTheme("dark")`.
 - `messages`: top-level copy overrides.
-- `retry`: API retry and rate-limit behavior.
+- `retry`: rate-limit observability callbacks — see [Rate Limiting](#rate-limiting).
 - `walletConnect`: WalletConnect overrides.
 - `features`: feature rollout controls, including swap-mode token selection constraints.
-- `onError`, `onSuccess`, `onEvent`: lifecycle callbacks.
+- `onError`, `onSuccess`, `onEvent`: lifecycle callbacks — see [Events](#events).
 
 ## Widget Usage Patterns
 
@@ -204,7 +222,7 @@ Use this mode when:
 
 ### 2. Widget With a Host-Managed Wallet
 
-Use this when your app already controls wallet connection through Wagmi, Viem, or another adapter.
+Use this when your app already controls wallet connection through Wagmi or another adapter.
 
 ```tsx
 import { useMemo } from "react";
@@ -250,11 +268,9 @@ Use this mode when:
 
 ```tsx
 import { useRef } from "react";
-import {
-  TrustwareProvider,
-  TrustwareWidget,
-  type TrustwareWidgetRef,
-} from "@trustware/sdk";
+import { TrustwareProvider, TrustwareWidget } from "@trustware/sdk";
+// The widget's prop and ref types live on the widget entry, not the root barrel.
+import type { TrustwareWidgetRef } from "@trustware/sdk/react";
 
 export function ControlledWidget() {
   const widgetRef = useRef<TrustwareWidgetRef>(null);
@@ -277,12 +293,17 @@ export function ControlledWidget() {
 
 Current widget props:
 
-- `theme?: "light" | "dark" | "system"`
+- `theme?: "light" | "dark" | "system"` — initial mode only; `Trustware.setTheme()` drives it afterwards
 - `initialStep?: "home" | "select-token" | "crypto-pay" | "processing" | "success" | "error"`
-- `defaultOpen?: boolean`
+- `defaultOpen?: boolean` — defaults to `true`, which is what you want for inline usage
+- `style?: React.CSSProperties` — merged onto the widget shell
 - `onOpen?: () => void`
 - `onClose?: () => void`
-- `showThemeToggle?: boolean`
+- `showThemeToggle?: boolean` — defaults to `true`
+
+And the ref (`TrustwareWidgetRef`): `open()`, `close()`, `isOpen()`. `close()`
+asks for confirmation first if a transaction is in flight, so it is safe to wire
+straight to a dismiss button.
 
 ### 4. Headless Core API
 
@@ -355,10 +376,73 @@ Trustware.setDestinationAddress("0xDestination...");
 
 ## Headless / Core Notes
 
+`Trustware` is a plain object, not a class or an event emitter — there is no
+`Trustware.on()`. Events reach you through `config.onEvent`.
+
+**Lifecycle and config**
+
+- `Trustware.init(config)` loads the config and validates the API key once.
 - `Trustware.getConfig()` returns the resolved config.
-- `Trustware.getWallet()` and `Trustware.getAddress()` expose the active wallet.
+- `Trustware.setTheme(mode)` / `getTheme()` switch the widget's color mode at runtime.
+- `Trustware.setDestinationAddress/Chain/Token()` update the route defaults in place.
+
+**Wallets**
+
 - `Trustware.useWallet(wallet)` attaches a wallet imperatively.
+- `Trustware.getWallet()` and `Trustware.getAddress()` expose the active wallet.
 - `Trustware.autoDetect()` can still be used if you want SDK-managed discovery outside the widget.
+- `Trustware.getIdentity()` / `resolveAddressForChain()` / `addIdentityAddress()` handle
+  multi-chain identities, so an EVM address and a Solana address can belong to one user.
+
+**Routes, status and balances**
+
+- `buildRoute`, `buildDepositAddress` — build a route, or an address to deposit into.
+- `submitReceipt`, `submitStepReceipt`, `sendRouteTransaction`, `runTopUp` — execution.
+- `getStatus`, `pollStatus` — read a transaction through to a terminal state.
+- `getBalances`, `getBalancesByAddress`, `getBalancesByAddressStream`.
+- `useChains`, `useTokens` — React hooks over the chain and token registries.
+- `validateAddressForChain`, `validateRouteAddresses` — check addresses before you spend a request.
+
+There is no `getQuote`: the estimate is part of the route, on
+`route.route?.estimate` and `route.finalExchangeRate`.
+
+### Provider Context
+
+`useTrustware()` returns `{ status, errors, core, emitError, emitSuccess,
+emitEvent, revalidate }`. `status` is `"idle" | "initializing" | "ready" |
+"error"` — gate anything that calls the API on `"ready"`. `core` is the same
+`Trustware` facade, handed to you so you don't have to import it separately, and
+`revalidate()` re-runs init after a failure (an API key arriving late, for
+instance).
+
+## Smart Accounts
+
+For ERC-4337 flows, `@trustware/sdk/smart-account` sends a route as a user
+operation rather than a wallet transaction:
+
+```ts
+import {
+  createTrustwareSmartAccountClient,
+  sendRouteAsUserOperation,
+} from "@trustware/sdk/smart-account";
+```
+
+It is a separate entry point on purpose — 65 KB gzipped, and nothing pulls it in
+unless you import it.
+
+## Events
+
+`config.onEvent` receives a discriminated `TrustwareEvent`:
+
+- `error`
+- `transaction_started`
+- `transaction_success`
+- `wallet_connected`
+- `token_page_loaded`
+- `token_page_error`
+- `balance_stream_chunk`
+- `balance_stream_fallback`
+- `swap_route_changed`
 
 ## Rate Limiting
 

package/dist/constants.cjs

@@ -30,7 +30,7 @@ __export(constants_exports, {
 });
 module.exports = __toCommonJS(constants_exports);
 var SDK_NAME = "@trustware/sdk";
-var SDK_VERSION = "1.1.12-staging.5";
+var SDK_VERSION = "1.1.12-staging.7";
 var API_ROOT = "https://bv-staging-api.trustware.io";
 var GTM_ID = "GTM-TZDGNCXB";
 var API_PREFIX = "/api";

package/dist/constants.mjs

@@ -1,6 +1,6 @@
 // src/constants.ts
 var SDK_NAME = "@trustware/sdk";
-var SDK_VERSION = "1.1.12-staging.5";
+var SDK_VERSION = "1.1.12-staging.7";
 var API_ROOT = "https://bv-staging-api.trustware.io";
 var GTM_ID = "GTM-TZDGNCXB";
 var API_PREFIX = "/api";

package/dist/core.cjs

@@ -83,7 +83,7 @@ var init_constants = __esm({
   "src/constants.ts"() {
     "use strict";
     SDK_NAME = "@trustware/sdk";
-    SDK_VERSION = "1.1.12-staging.5";
+    SDK_VERSION = "1.1.12-staging.7";
     API_ROOT = "https://bv-staging-api.trustware.io";
     API_PREFIX = "/api";
     WALLETCONNECT_PROJECT_ID = "72ea74c400f5111d43aea638d7d83a24";
@@ -307,6 +307,104 @@ var init_chains = __esm({
   }
 });
 
+// src/wallets/chainParams.ts
+function chainParamsFor(chainId) {
+  return registered.get(chainId) ?? BUILTIN_CHAIN_PARAMS[chainId];
+}
+function registerChainParams(chainId, params) {
+  registered.set(chainId, params);
+}
+function usableRpcUrls(chain) {
+  const candidates = [
+    ...Array.isArray(chain.rpcList) ? chain.rpcList : [],
+    ...chain.rpc ? [chain.rpc] : []
+  ];
+  const seen = /* @__PURE__ */ new Set();
+  const out = [];
+  for (const raw of candidates) {
+    const url = String(raw ?? "").trim();
+    if (!/^https?:\/\//i.test(url) || seen.has(url)) continue;
+    seen.add(url);
+    out.push(url);
+  }
+  return out;
+}
+function chainParamsFromChainDef(chain) {
+  const chainType = String(
+    chain.chainType ?? chain.type ?? "evm"
+  ).toLowerCase();
+  if (chainType !== "evm") return void 0;
+  const numericId = Number(chain.chainId ?? chain.id);
+  if (!Number.isSafeInteger(numericId) || numericId <= 0) return void 0;
+  const rpcUrls = usableRpcUrls(chain);
+  if (rpcUrls.length === 0) return void 0;
+  const native = chain.nativeCurrency;
+  const symbol = String(native?.symbol ?? "").trim();
+  if (!symbol) return void 0;
+  const decimals = Number(native?.decimals);
+  const chainName = String(
+    chain.networkName ?? chain.axelarChainName ?? chain.networkIdentifier ?? ""
+  ).trim();
+  const explorers = (chain.blockExplorerUrls ?? []).filter(
+    (u) => /^https?:\/\//i.test(String(u ?? ""))
+  );
+  return {
+    chainIdHex: `0x${numericId.toString(16)}`,
+    chainName: chainName || `Chain ${numericId}`,
+    rpcUrls,
+    nativeCurrency: {
+      name: String(native?.name ?? symbol),
+      symbol,
+      decimals: Number.isFinite(decimals) ? decimals : 18
+    },
+    ...explorers.length > 0 ? { blockExplorerUrls: explorers } : {}
+  };
+}
+var BUILTIN_CHAIN_PARAMS, registered;
+var init_chainParams = __esm({
+  "src/wallets/chainParams.ts"() {
+    "use strict";
+    BUILTIN_CHAIN_PARAMS = {
+      1: {
+        chainIdHex: "0x1",
+        chainName: "Ethereum",
+        rpcUrls: ["https://eth.llamarpc.com"],
+        nativeCurrency: { name: "Ether", symbol: "ETH", decimals: 18 },
+        blockExplorerUrls: ["https://etherscan.io"]
+      },
+      137: {
+        chainIdHex: "0x89",
+        chainName: "Polygon",
+        rpcUrls: ["https://polygon-rpc.com"],
+        nativeCurrency: { name: "POL", symbol: "POL", decimals: 18 },
+        blockExplorerUrls: ["https://polygonscan.com"]
+      },
+      8453: {
+        chainIdHex: "0x2105",
+        chainName: "Base",
+        rpcUrls: ["https://mainnet.base.org"],
+        nativeCurrency: { name: "Ether", symbol: "ETH", decimals: 18 },
+        blockExplorerUrls: ["https://basescan.org"]
+      },
+      42161: {
+        chainIdHex: "0xa4b1",
+        chainName: "Arbitrum One",
+        rpcUrls: ["https://arb1.arbitrum.io/rpc"],
+        nativeCurrency: { name: "Ether", symbol: "ETH", decimals: 18 },
+        blockExplorerUrls: ["https://arbiscan.io"]
+      },
+      43114: {
+        chainIdHex: "0xa86a",
+        chainName: "Avalanche C-Chain",
+        rpcUrls: ["https://api.avax.network/ext/bc/C/rpc"],
+        nativeCurrency: { name: "Avalanche", symbol: "AVAX", decimals: 18 },
+        blockExplorerUrls: ["https://snowtrace.io"]
+      }
+    };
+    registered = /* @__PURE__ */ new Map();
+  }
+});
+
 // src/registry.ts
 function getChainAliases(chain) {
   const values = [
@@ -351,6 +449,7 @@ var init_registry = __esm({
     "use strict";
     init_store();
     init_chains();
+    init_chainParams();
     NATIVE = "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE";
     PAGE_CACHE_TTL_MS = 5 * 60 * 1e3;
     PAGE_CACHE_LIMIT = 100;
@@ -429,6 +528,10 @@ var init_registry = __esm({
         for (const alias of getChainAliases(normalized)) {
           this._chainAliases.set(alias, canonicalKey);
         }
+        const addParams = chainParamsFromChainDef(normalized);
+        if (addParams) {
+          registerChainParams(Number(normalized.chainId ?? canonical), addParams);
+        }
       }
       storeTokenForAlias(chainKey, token) {
         const key = tokenKey(token);
@@ -2006,7 +2109,7 @@ var init_balances = __esm({
 
 // src/wallets/eipWallets.ts
 async function addThenSwitch(eth, chainId) {
-  const p = CHAIN_PARAMS[chainId];
+  const p = chainParamsFor(chainId);
   if (!p) throw new Error(`Unknown chain ${chainId} (no params to add)`);
   await eth.request({ method: "wallet_addEthereumChain", params: [p] });
   await eth.request({
@@ -2034,7 +2137,7 @@ function useEIP1193(eth) {
     async switchChain(chainId) {
       if (switching) return;
       switching = true;
-      const hex = CHAIN_PARAMS[chainId]?.chainIdHex ?? `0x${chainId.toString(16)}`;
+      const hex = chainParamsFor(chainId)?.chainIdHex ?? `0x${chainId.toString(16)}`;
       try {
         await eth.request({
           method: "wallet_switchEthereumChain",
@@ -2043,7 +2146,6 @@ function useEIP1193(eth) {
       } catch (e2) {
         if (e2?.code === 4902) {
           await addThenSwitch(eth, chainId);
-        } else if (e2?.code === 4001) {
         } else {
           throw e2;
         }
@@ -2054,47 +2156,10 @@ function useEIP1193(eth) {
     request: (args) => eth.request(args)
   };
 }
-var CHAIN_PARAMS;
 var init_eipWallets = __esm({
   "src/wallets/eipWallets.ts"() {
     "use strict";
-    CHAIN_PARAMS = {
-      1: {
-        chainIdHex: "0x1",
-        chainName: "Ethereum",
-        rpcUrls: ["https://eth.llamarpc.com"],
-        nativeCurrency: { name: "Ether", symbol: "ETH", decimals: 18 },
-        blockExplorerUrls: ["https://etherscan.io"]
-      },
-      137: {
-        chainIdHex: "0x89",
-        chainName: "Polygon",
-        rpcUrls: ["https://polygon-rpc.com"],
-        nativeCurrency: { name: "POL", symbol: "POL", decimals: 18 },
-        blockExplorerUrls: ["https://polygonscan.com"]
-      },
-      8453: {
-        chainIdHex: "0x2105",
-        chainName: "Base",
-        rpcUrls: ["https://mainnet.base.org"],
-        nativeCurrency: { name: "Ether", symbol: "ETH", decimals: 18 },
-        blockExplorerUrls: ["https://basescan.org"]
-      },
-      42161: {
-        chainIdHex: "0xa4b1",
-        chainName: "Arbitrum One",
-        rpcUrls: ["https://arb1.arbitrum.io/rpc"],
-        nativeCurrency: { name: "Ether", symbol: "ETH", decimals: 18 },
-        blockExplorerUrls: ["https://arbiscan.io"]
-      },
-      43114: {
-        chainIdHex: "0xa86a",
-        chainName: "Avalanche C-Chain",
-        rpcUrls: ["https://api.avax.network/ext/bc/C/rpc"],
-        nativeCurrency: { name: "Avalanche", symbol: "AVAX", decimals: 18 },
-        blockExplorerUrls: ["https://snowtrace.io"]
-      }
-    };
+    init_chainParams();
   }
 });
 
@@ -6319,6 +6384,25 @@ function backendChainId(chain, fallback) {
 function sleep2(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
+async function ensureWalletOnChain(wallet, target) {
+  if (!Number.isSafeInteger(target) || target <= 0) {
+    throw new Error(`Invalid chain id: ${target}`);
+  }
+  if (await wallet.getChainId() === target) return;
+  let switchError;
+  try {
+    await wallet.switchChain(target);
+  } catch (e2) {
+    switchError = e2;
+  }
+  if (await wallet.getChainId() === target) return;
+  if (switchError && isUserRejected(switchError)) {
+    throw switchError;
+  }
+  throw new Error(
+    `Wallet is on the wrong network. Switch to chain ${target} and try again.`
+  );
+}
 async function sendEvmTx(w, tx) {
   if (w.type === "eip1193") {
     const from = await w.getAddress();
@@ -6345,19 +6429,37 @@ async function sendEvmTx(w, tx) {
   });
   return response.hash;
 }
-async function waitForTxConfirmation(chainId, txHash) {
-  const timeoutMs = 12e4;
-  const intervalMs = 2e3;
+async function waitForEvmTxConfirmation(chainId, txHash, label, options = {}) {
+  const {
+    readStatus = getEVMTxStatus,
+    timeoutMs = 12e4,
+    intervalMs = 2e3,
+    notFoundGraceMs = NOT_FOUND_GRACE_MS
+  } = options;
   const started = Date.now();
+  let notFoundSince = null;
   while (Date.now() - started < timeoutMs) {
-    const status = await getEVMTxStatus({ chainId, txHash });
+    const status = await readStatus({ chainId, txHash });
     if (status.status === "success") return;
     if (status.status === "reverted") {
-      throw new Error("Approval transaction reverted");
+      throw new Error(`${label} transaction reverted`);
+    }
+    if (status.status === "not_found") {
+      notFoundSince ?? (notFoundSince = Date.now());
+      if (Date.now() - notFoundSince >= notFoundGraceMs) {
+        throw new Error(
+          `${label} transaction ${txHash} was not found on chain ${chainId}. It may have been sent on a different network \u2014 check your wallet's selected network and try again.`
+        );
+      }
+    } else {
+      notFoundSince = null;
     }
     await sleep2(intervalMs);
   }
-  throw new Error("Timed out waiting for approval confirmation");
+  throw new Error(`Timed out waiting for ${label.toLowerCase()} confirmation`);
+}
+function waitForApprovalConfirmation(chainId, txHash, options) {
+  return waitForEvmTxConfirmation(chainId, txHash, "Approval", options);
 }
 function requiredApprovalAmount(planAmountWei, routeAmountWei) {
   if (planAmountWei >= UNLIMITED_APPROVAL_FLOOR && routeAmountWei !== void 0 && routeAmountWei > 0n) {
@@ -6397,17 +6499,22 @@ async function ensureApprovals(w, approvals, fallbackChainId, intentId, routeAmo
       functionName: "approve",
       args: [spender, amountWei]
     });
+    const approvalChainId = Number(chainId);
+    if (!Number.isSafeInteger(approvalChainId) || approvalChainId <= 0) {
+      throw new Error(`Approval has an invalid chain id: ${chainId}`);
+    }
+    await ensureWalletOnChain(w, approvalChainId);
     const hash = await sendEvmTx(w, {
       to: tokenAddress,
       data,
       value: 0n,
-      chainId: Number.isFinite(Number(chainId)) ? Number(chainId) : void 0
+      chainId: approvalChainId
     });
     if (intentId) {
       void submitStepReceipt(intentId, stepIndex, hash).catch(() => {
       });
     }
-    await waitForTxConfirmation(chainId, hash);
+    await waitForApprovalConfirmation(chainId, hash);
   }
 }
 function isUserRejected(e2) {
@@ -6434,15 +6541,14 @@ async function sendRouteTransaction(b, fallbackChainId, options) {
         validatedSponsorship = b.sponsorship;
       }
     }
-    if (Number.isFinite(target)) {
-      const current = await w.getChainId();
-      if (current !== target) {
-        try {
-          await w.switchChain(target);
-        } catch {
-        }
-      }
+    if (!Number.isSafeInteger(target) || target <= 0) {
+      throw new Error(
+        `Route is missing a usable chain id (got ${String(
+          txReq.chainId ?? fallbackChainId
+        )}).`
+      );
     }
+    await ensureWalletOnChain(w, target);
     if (!validatedSponsorship && !options?.approvalsEnsured) {
       await ensureApprovals(
         w,
@@ -6548,7 +6654,7 @@ async function runTopUp(params) {
     }
   }
 }
-var import_viem2, erc20ApproveAbi, UNLIMITED_APPROVAL_FLOOR;
+var import_viem2, erc20ApproveAbi, NOT_FOUND_GRACE_MS, UNLIMITED_APPROVAL_FLOOR;
 var init_tx = __esm({
   "src/core/tx.ts"() {
     "use strict";
@@ -6559,6 +6665,7 @@ var init_tx = __esm({
     erc20ApproveAbi = (0, import_viem2.parseAbi)([
       "function approve(address spender, uint256 amount) returns (bool)"
     ]);
+    NOT_FOUND_GRACE_MS = 2e4;
     UNLIMITED_APPROVAL_FLOOR = 1n << 255n;
   }
 });