@multiplatform.one/web3 7.23.1 → 7.24.0

package/README.md

@@ -22,8 +22,10 @@ Peers: `react`, `@tanstack/react-query`.
   `useBalance`, `useConnect`, `useSignMessage`, `useSwitchChain`, …)
 - **Components** — `ConnectKitButton`, `WalletButton`, `WalletAvatar`,
   `WalletStatus`, `NetworkSwitcher`
-- **Subpaths** — `./native` (WebView wallet bridge), `./connectkit`, `./vite`
-  and `./esbuild` (bundler plugins, below)
+- **Subpaths** — `./native` (WebView wallet bridge), `./connectkit`,
+  `./message` (the wallet sign-in messages), `./keycloak` (wallet login
+  against the Keycloak wallet SPI), `./vite` and `./esbuild` (bundler
+  plugins, below)
 
 ## Per-chain clients
 
@@ -34,12 +36,12 @@ or a provider's `request`. Every client shares
 verifiers take: EVM 0x hex, Solana base58, Sui base64, Bitcoin base64 BIP-322,
 GPG the armored signature plus the armored public key.
 
-| Hook / factory                                                                    | What it adds                                                                                                                                                                                                                                                                |
-| --------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `useEvmClient()` / `evmClient({ walletClient } \| { provider, account, chain })`  | viem `walletClient` + `publicClient`, `sendTransaction`, `writeContract`, `waitForTransactionReceipt`, `erc20.{transfer, approve, ensureAllowance, balanceOf, allowance, decimals}`, safe for tokens like USDT that return nothing or refuse a non-zero to non-zero approve |
-| `useSolanaClient()` / `solanaClient({ signer, rpcUrl?, chain? })` from `./solana` | web only: `@solana/kit` `rpc`, `signTransaction`, `signAndSendTransaction`, `sendTransaction`, `confirmTransaction`, `getBalance`, `transferSol`                                                                                                                            |
-| `useGpgSigner()` / `createGpgSigner()`                                            | the copy/paste GPG signer: `signMessage` parks a request with its terminal `command`; `submit(pasted, request)` resolves it only while `request` is still the pending one and the pasted signature covers its message                                                       |
-| `useSuiClient()`, `useBitcoinClient()`                                            | message signing only; `signTransaction` / `signPsbt` reject with `UnsupportedClientMethodError` until transactions land                                                                                                                                                     |
+| Hook / factory                                                                    | What it adds                                                                                                                                                                                                                                                                                                       |
+| --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `useEvmClient()` / `evmClient({ walletClient } \| { provider, account, chain })`  | viem `walletClient` + `publicClient`, `sendTransaction`, `writeContract`, `waitForTransactionReceipt`, `confirmTransaction`, `explorerTxUrl`, `erc20.{transfer, approve, ensureAllowance, balanceOf, allowance, decimals}`, safe for tokens like USDT that return nothing or refuse a non-zero to non-zero approve |
+| `useSolanaClient()` / `solanaClient({ signer, rpcUrl?, chain? })` from `./solana` | web only: `@solana/kit` `rpc`, `signTransaction`, `signAndSendTransaction`, `sendTransaction`, `confirmTransaction`, `getBalance`, `transferSol`                                                                                                                                                                   |
+| `useGpgSigner()` / `createGpgSigner()`                                            | the copy/paste GPG signer: `signMessage` parks a request with its terminal `command`; `submit(pasted, request)` resolves it only while `request` is still the pending one and the pasted signature covers its message                                                                                              |
+| `useSuiClient()`, `useBitcoinClient()`                                            | message signing only; `signTransaction` / `signPsbt` reject with `UnsupportedClientMethodError` until transactions land                                                                                                                                                                                            |
 
 ```tsx
 import { useEvmClient } from "@multiplatform.one/web3";
@@ -56,9 +58,13 @@ await sol?.confirmTransaction(sent!);
 
 `transferSol` returns the signature with the blockhash's `lastValidBlockHeight`,
 and `confirmTransaction` waits until the chain passes that height before it
-gives up. Its `SolanaConfirmationError` has `mayStillLand`: `false` means the
-transaction failed or expired and a retry is safe; `true` (only when there was
-no `lastValidBlockHeight` to judge by) means resending can pay twice.
+gives up. Its `SolanaConfirmationError` has a `reason` and `mayStillLand`.
+`failed` and `expired` set it `false`: the transaction will not land and a retry
+is safe. `timeout` (there was no `lastValidBlockHeight` to judge by) and `rpc`
+(a `getSignatureStatuses` or `getBlockHeight` poll failed, with the transport
+error as `cause`) set it `true`: resending can pay twice, so call
+`confirmTransaction` again on the same submission instead. `lastStatus` is the
+last `confirmationStatus` the poll saw, `null` when it never saw the signature.
 
 A Solana client runs over a byte-level `SolanaSigner`: `standardSolanaSigner`
 (Wallet Standard: Phantom, Solflare, Backpack), `injectedSolanaSigner` (what the
@@ -72,6 +78,107 @@ signs Solana through the WebView bridge, so the root never imports
 through `solanaMessageClient`, so a login page carries no kit.
 `tests/clients/importGraph.spec.ts` holds both lines, for native and web.
 
+### EVM payments: pending is not failed
+
+A sent transaction can sit in the mempool for minutes and still land. viem's
+receipt wait gives up after 180 s with an error that reads like a failure, so
+an app would offer "try again" and the user would pay twice. The EVM client
+never does that:
+
+- `waitForTransactionReceipt(hash)` and `confirmTransaction(hash)` wait with
+  no timeout. Pass `{ timeout }` for a deadline, which holds even while an
+  RPC call hangs. Running out rejects with
+  `ReceiptPendingError` (`hash`, `chainId`, `explorerUrl`, `nonce` once the
+  node has seen it, `mayStillLand: true`), never a generic error. A failing
+  RPC never ends the wait: it backs off, up to 30 s between polls, and
+  retries.
+- Pass `{ signal }` and abort it when the screen unmounts. A wait with no
+  timeout otherwise polls until the transaction settles, which for a dropped
+  one is forever. It rejects with `ReceiptWaitAbortedError`, an `AbortError`.
+- `confirmTransaction` also rejects a reverted receipt with
+  `TransactionRevertedError`. `waitForTransactionReceipt` still resolves it,
+  as it always has.
+- When another transaction takes the nonce, both reject with
+  `TransactionReplacedError`: `reason` is `cancelled` (the wallet's cancel),
+  `replaced` (a different transaction), or `unmatched` (the original was never
+  seen, so it could be a speed-up). A speed-up resolves with the faster copy's
+  receipt. The wait binary-searches the nonce's block however long it slept,
+  so resuming one far back needs an RPC that serves state that old, an
+  archive node. A chain's default public RPC often keeps only the last 128
+  blocks, and past that the wait stays pending.
+- `erc20.ensureAllowance` confirms its approvals the same way and takes the
+  same `timeout` and `signal`. `erc20.transfer` and `approve` return once the wallet sends,
+  and their rejections classify too.
+
+`classifyTxError(error)` sorts any of these, and viem's own errors, into what
+to show:
+
+| Kind            | Meaning                                                               | Show                                           |
+| --------------- | --------------------------------------------------------------------- | ---------------------------------------------- |
+| `user-rejected` | declined or cancelled in the wallet; nothing paid                     | "Cancelled", buy enabled                       |
+| `reverted`      | the contract refused it, in simulation or on chain; nothing paid      | the reason, buy enabled                        |
+| `pending`       | sent with no receipt yet, or its nonce went to what may be a speed-up | "Pending" with the explorer link, buy disabled |
+| `aborted`       | the app stopped waiting; the transaction is as pending as it was      | nothing; keep the pending hash                 |
+| `failed`        | anything else: no hash came back, or a different transaction won      | the error, buy enabled                         |
+
+`failed` with no hash usually means nothing was sent. A wallet that errors
+after the user approved may still have broadcast it, so tell the user to
+check the wallet's activity before paying again.
+
+Persist the hash from the moment the wallet returns it, and what `onTrack`
+hands over: the nonce once the node has seen the transaction, and a speed-up's
+hash when one replaces it. A wait resumed after a reload needs the nonce to
+notice a cancel or replacement that landed while the app was closed; without
+it, a transaction the node has forgotten stays pending. A speed-up the page
+never saw can't be told from a replacement after a reload, so it stays
+pending too. Refuse a second buy while one is pending:
+
+```tsx
+import { classifyTxError, useEvmClient } from "@multiplatform.one/web3";
+
+const evm = useEvmClient();
+const [pending, setPending] = usePersistedState<{ hash: Hash; nonce?: number } | null>("buy", null);
+
+async function settle(hash: Hash, nonce: number | undefined, signal: AbortSignal) {
+  try {
+    await evm.confirmTransaction(hash, { nonce, signal, onTrack: setPending });
+    setPending(null);
+    showPaid();
+  } catch (error) {
+    const kind = classifyTxError(error);
+    // aborted: unmounted, and the next mount resumes it. pending: superseded,
+    // maybe sped up, so keep it locked.
+    if (kind === "aborted" || kind === "pending") return;
+    setPending(null);
+    showFailure(kind, error);
+  }
+}
+
+// Every wait belongs to a mounted screen, and stops when it unmounts.
+useEffect(() => {
+  if (!evm || !pending) return;
+  const controller = new AbortController();
+  void settle(pending.hash, pending.nonce, controller.signal);
+  return () => controller.abort();
+}, [evm, pending?.hash]);
+
+async function buy() {
+  if (!evm || pending) return;
+  try {
+    await evm.erc20.ensureAllowance({ token: qcc, spender: store, amount });
+    const hash = await evm.writeContract({ address: store, abi, functionName: "buy", args: [id] });
+    setPending({ hash });
+  } catch (error) {
+    showFailure(classifyTxError(error), error);
+  }
+}
+```
+
+While `pending` is set, disable buy and link `evm.explorerTxUrl(pending.hash)`.
+The effect settles it on mount and after a reload; a "check again" button can
+remount it. When the client can't settle it, your backend, which sees the
+purchase land, is the one to release the lock.
+
 ### Solana on mobile (follow-up)
 
 The web path is done. A native app cannot reach Phantom through the WebView
@@ -155,6 +262,38 @@ export function App() {
 }
 ```
 
+## Keycloak direct login and onboarding
+
+`kc.directGrant({ clientId })` trades a wallet signature for tokens without a
+browser. A brand-new user, or a realm that later adds a required profile
+field, has required actions Keycloak cannot run on a direct grant: it answers
+400 "Account is not fully set up", which `login()` rejects as
+`ProfileIncompleteError` and `useDirectLogin` reports as
+`status: "profile-incomplete"`. Open the `url` of `kc.browserLoginUrl({
+clientId, redirectUri })` in the system browser or a WebView page, where
+Keycloak shows its own onboarding form, then call `signIn()` again once it
+redirects back.
+
+`browserLoginUrl` draws a fresh `state` and a PKCE S256 verifier on every call
+and returns `{ url, state, codeVerifier }`. Keep `state` and accept the
+redirect only when it matches; `codeVerifier` is for a caller that exchanges
+the code at `kc.tokenUrl`. The client needs `standardFlowEnabled` and the
+redirect URI registered exactly, with no wildcard. A direct-grant client does
+not qualify: mpo's `siwe-public` and `siws-public` have `standardFlowEnabled:
+false`, so mpo's realm carries a separate public client, `wallet-onboarding`
+(PKCE S256 required, redirect URIs `http://localhost:8000/wallet`,
+`http://localhost:3456/wallet` and `multiplatform-one://wallet`). The wallet
+screen in `features/wallet` takes this path on its own.
+
+```tsx
+const { status, signIn } = useDirectLogin(grant);
+if (status === "profile-incomplete") {
+  const login = kc.browserLoginUrl({ clientId: "wallet-onboarding", redirectUri: "app://auth" });
+  await saveState(login.state);
+  await Linking.openURL(login.url);
+}
+```
+
 ## License
 
 Apache-2.0

package/dist/cjs/clients/evm.cjs

@@ -22,10 +22,98 @@ var __toCommonJS = mod => __copyProps(__defProp({}, "__esModule", {
 }), mod);
 var evm_exports = {};
 __export(evm_exports, {
+  ReceiptPendingError: () => ReceiptPendingError,
+  ReceiptWaitAbortedError: () => ReceiptWaitAbortedError,
+  TransactionReplacedError: () => TransactionReplacedError,
+  TransactionRevertedError: () => TransactionRevertedError,
+  classifyTxError: () => classifyTxError,
   evmClient: () => evmClient
 });
 module.exports = __toCommonJS(evm_exports);
 var import_viem = require("viem");
+class ReceiptPendingError extends Error {
+  constructor(hash, chainId, options) {
+    super(`${options.label ?? "transaction"} ${hash} on chain ${chainId} ${options.detail}; it may still land, so do not resend it`, {
+      cause: options.cause
+    });
+    this.hash = hash;
+    this.chainId = chainId;
+    this.name = "ReceiptPendingError";
+    this.explorerUrl = options.explorerUrl;
+    this.nonce = options.nonce;
+  }
+  hash;
+  chainId;
+  mayStillLand = true;
+  explorerUrl;
+  /** Known once the node has seen the transaction. Keep it with the hash to resume the wait. */
+  nonce;
+}
+class ReceiptWaitAbortedError extends Error {
+  constructor(hash, chainId, nonce, cause) {
+    super(`stopped waiting for transaction ${hash} on chain ${chainId}`, {
+      cause
+    });
+    this.hash = hash;
+    this.chainId = chainId;
+    this.nonce = nonce;
+    this.name = "AbortError";
+  }
+  hash;
+  chainId;
+  nonce;
+  mayStillLand = true;
+}
+class TransactionRevertedError extends Error {
+  constructor(receipt, chainId, label = "transaction") {
+    super(`${label} ${receipt.transactionHash} reverted in block ${receipt.blockNumber}`);
+    this.receipt = receipt;
+    this.chainId = chainId;
+    this.name = "TransactionRevertedError";
+    this.hash = receipt.transactionHash;
+  }
+  receipt;
+  chainId;
+  mayStillLand = false;
+  hash;
+}
+class TransactionReplacedError extends Error {
+  constructor(hash, chainId, reason, replacement) {
+    super(`transaction ${hash} was ${reason === "unmatched" ? "superseded" : reason}${replacement ? ` by ${replacement.transactionHash}` : ""}: another transaction took its nonce`);
+    this.hash = hash;
+    this.chainId = chainId;
+    this.reason = reason;
+    this.replacement = replacement;
+    this.name = "TransactionReplacedError";
+  }
+  hash;
+  chainId;
+  reason;
+  replacement;
+  mayStillLand = false;
+}
+function causes(error) {
+  const chain = [];
+  for (let e = error; e && typeof e === "object" && chain.length < 16; e = e.cause) {
+    if (chain.includes(e)) break;
+    chain.push(e);
+  }
+  return chain;
+}
+function classifyTxError(error) {
+  const chain = causes(error);
+  const pendingAt = chain.findIndex(e => e.mayStillLand === true || e.name === "WaitForTransactionReceiptTimeoutError" || e.name === "TransactionReplacedError" && e.reason === "unmatched");
+  const abortedAt = chain.findIndex(e => e.name === "AbortError" && typeof e.mayStillLand === "boolean");
+  if (abortedAt >= 0 && (pendingAt < 0 || abortedAt <= pendingAt)) return "aborted";
+  if (pendingAt >= 0) return "pending";
+  if (chain.some(e => e.name === "UserRejectedRequestError" || e.code === 4001 || e.name === "TransactionReplacedError" && e.reason === "cancelled")) {
+    return "user-rejected";
+  }
+  if (chain.some(e => e.name === "ContractFunctionRevertedError" || e.name === "ExecutionRevertedError" || e.receipt?.status === "reverted")) {
+    return "reverted";
+  }
+  return "failed";
+}
 const erc20WriteAbi = [{
   type: "function",
   name: "transfer",
@@ -86,16 +174,208 @@ function evmClient(config) {
       chain
     });
   };
-  const approveAndWait = async (token, spender, amount) => {
+  const explorer = chain.blockExplorers?.default.url.replace(/\/+$/, "");
+  const explorerTxUrl = hash => explorer ? `${explorer}/tx/${hash}` : void 0;
+  const missing = name => error => {
+    if (error?.name === name) return void 0;
+    throw error;
+  };
+  const getReceipt = hash => publicClient.getTransactionReceipt({
+    hash
+  }).catch(missing("TransactionReceiptNotFoundError"));
+  const getTransaction = hash => publicClient.getTransaction({
+    hash
+  }).catch(missing("TransactionNotFoundError"));
+  const sameAddress = (a, b) => !!a && !!b && a.toLowerCase() === b.toLowerCase();
+  const nonceBlock = async (count, nonce, taken, free) => {
+    let hi = taken;
+    let lo = -1n;
+    if (free !== void 0 && free < hi) lo = free;else {
+      for (let step = 1n; hi - step >= 0n; step *= 2n) {
+        const probe = hi - step;
+        if ((await count(probe)) <= nonce) {
+          lo = probe;
+          break;
+        }
+        hi = probe;
+      }
+    }
+    while (hi - lo > 1n) {
+      const mid = (lo + hi) / 2n;
+      if ((await count(mid)) > nonce) hi = mid;else lo = mid;
+    }
+    return {
+      block: hi,
+      free: lo >= 0n ? lo : void 0
+    };
+  };
+  const replacementReason = (taker, original) => {
+    if (original && sameAddress(taker.to, original.to) && taker.value === original.value && taker.input === original.input) {
+      return "repriced";
+    }
+    if (sameAddress(taker.to, taker.from) && taker.value === 0n) return "cancelled";
+    return original ? "replaced" : "unmatched";
+  };
+  const after = (ms, fire) => {
+    const step = 2 ** 31 - 1;
+    let cancel = () => {};
+    const arm = left => {
+      const id = setTimeout(() => left > step ? arm(left - step) : fire(), Math.min(left, step));
+      cancel = () => clearTimeout(id);
+    };
+    arm(Math.max(0, ms));
+    return () => cancel();
+  };
+  const backoff = failures => {
+    const ceiling = Math.min(3e4, Math.max(1, publicClient.pollingInterval) * 2 ** Math.min(failures - 1, 16));
+    return ceiling / 2 + Math.random() * ceiling / 2;
+  };
+  const waitForReceipt = async (hash, options = {}, label) => {
+    const {
+      signal
+    } = options;
+    const confirmations = BigInt(Math.max(1, options.confirmations ?? 1));
+    const {
+      timeout
+    } = options;
+    const deadline = timeout !== void 0 && Number.isFinite(timeout) && timeout > 0 ? Date.now() + timeout : void 0;
+    let target = hash;
+    let original;
+    let nonce = options.nonce;
+    let freeBlock;
+    let failures = 0;
+    let lastError;
+    const aborted = () => new ReceiptWaitAbortedError(hash, chain.id, nonce, signal?.reason);
+    const timedOut = () => new ReceiptPendingError(hash, chain.id, {
+      detail: `has no receipt after ${timeout} ms`,
+      explorerUrl: explorerTxUrl(hash),
+      nonce,
+      cause: lastError,
+      label
+    });
+    let ended = false;
+    const track = () => {
+      if (ended || signal?.aborted || nonce === void 0) return;
+      try {
+        options.onTrack?.({
+          hash: target,
+          nonce
+        });
+      } catch {}
+    };
+    if (signal?.aborted) throw aborted();
+    const guard = (promise, onStop = () => {}) => new Promise((resolve, reject) => {
+      let cancelTimer = () => {};
+      const cleanup = () => {
+        cancelTimer();
+        signal?.removeEventListener("abort", stop);
+      };
+      const give = error => {
+        cleanup();
+        onStop();
+        reject(error);
+      };
+      const stop = () => give(aborted());
+      promise.then(resolve, reject).finally(cleanup);
+      if (signal?.aborted) return stop();
+      signal?.addEventListener("abort", stop, {
+        once: true
+      });
+      if (deadline !== void 0) cancelTimer = after(deadline - Date.now(), () => give(timedOut()));
+    });
+    const rpc = call => {
+      if (ended || signal?.aborted) throw aborted();
+      return call();
+    };
+    const countAt = (address, blockNumber) => rpc(() => publicClient.getTransactionCount({
+      address,
+      blockNumber
+    }));
+    const poll = async () => {
+      const head = await rpc(() => publicClient.getBlockNumber({
+        cacheTime: 0
+      }));
+      const receipt = await rpc(() => getReceipt(target));
+      if (receipt) return head - receipt.blockNumber + 1n >= confirmations ? receipt : void 0;
+      if (!original) {
+        original = await rpc(() => getTransaction(target));
+        if (original && original.nonce !== nonce) {
+          nonce = original.nonce;
+          track();
+        }
+      }
+      if (nonce === void 0) return void 0;
+      const from = original?.from ?? account.address;
+      if ((await countAt(from, head)) <= nonce) {
+        freeBlock = head;
+        return void 0;
+      }
+      const found = await nonceBlock(n => countAt(from, n), nonce, head, freeBlock);
+      freeBlock = found.free;
+      const block = await rpc(() => publicClient.getBlock({
+        blockNumber: found.block,
+        includeTransactions: true
+      }));
+      const taker = block.transactions.find(tx => sameAddress(tx.from, from) && tx.nonce === nonce);
+      if (!taker || taker.hash === target) {
+        if (!taker) freeBlock = void 0;
+        return void 0;
+      }
+      const reason = replacementReason(taker, original);
+      if (reason === "repriced") {
+        target = taker.hash;
+        original = taker;
+        track();
+        return void 0;
+      }
+      if (head - found.block + 1n < confirmations) return void 0;
+      const replacement = await rpc(() => getReceipt(taker.hash));
+      throw new TransactionReplacedError(hash, chain.id, reason, replacement);
+    };
+    try {
+      for (;;) {
+        try {
+          const receipt = await guard(poll());
+          if (receipt) return receipt;
+          failures = 0;
+        } catch (error) {
+          if (error instanceof TransactionReplacedError || error instanceof ReceiptWaitAbortedError || error instanceof ReceiptPendingError) {
+            throw error;
+          }
+          lastError = error;
+          failures++;
+        }
+        if (deadline !== void 0 && Date.now() >= deadline) throw timedOut();
+        const pause = failures ? backoff(failures) : publicClient.pollingInterval;
+        let wake = () => {};
+        await guard(new Promise(resolve => {
+          wake = after(pause, () => resolve(void 0));
+        }), () => wake());
+      }
+    } finally {
+      ended = true;
+    }
+  };
+  const confirmTransaction = async (hash, options, label) => {
+    const receipt = await waitForReceipt(hash, options, label);
+    if (receipt.status !== "success") throw new TransactionRevertedError(receipt, chain.id, label);
+    return receipt;
+  };
+  const approveAndWait = async (token, spender, amount, options) => {
+    if (options.signal?.aborted) {
+      throw Object.assign(new Error("stopped before sending the approval", {
+        cause: options.signal.reason
+      }), {
+        name: "AbortError",
+        mayStillLand: false
+      });
+    }
     const hash = await erc20.approve({
       token,
       spender,
       amount
     });
-    const receipt = await publicClient.waitForTransactionReceipt({
-      hash
-    });
-    if (receipt.status !== "success") throw new Error(`approve ${hash} reverted`);
+    await confirmTransaction(hash, options, "approve");
     return hash;
   };
   const erc20 = {
@@ -137,12 +417,20 @@ function evmClient(config) {
     async ensureAllowance({
       token,
       spender,
-      amount
+      amount,
+      timeout,
+      signal
     }) {
       const current = await erc20.allowance(token, spender);
       if (current >= amount) return null;
-      if (current > 0n) await approveAndWait(token, spender, 0n);
-      return approveAndWait(token, spender, amount);
+      if (current > 0n) await approveAndWait(token, spender, 0n, {
+        timeout,
+        signal
+      });
+      return approveAndWait(token, spender, amount, {
+        timeout,
+        signal
+      });
     }
   };
   return {
@@ -163,9 +451,9 @@ function evmClient(config) {
       ...parameters
     }),
     writeContract,
-    waitForTransactionReceipt: hash => publicClient.waitForTransactionReceipt({
-      hash
-    }),
+    waitForTransactionReceipt: (hash, options) => waitForReceipt(hash, options),
+    confirmTransaction: (hash, options) => confirmTransaction(hash, options),
+    explorerTxUrl,
     erc20
   };
 }