@multiplatform.one/web3 7.23.2 → 7.25.0

package/src/clients/solana.spec.ts

@@ -274,6 +274,122 @@ describe("confirmTransaction against the blockhash lifetime", () => {
   });
 });
 
+describe("confirmTransaction when a poll fails", () => {
+  const outage = () => new Error("fetch failed: 503 Service Unavailable");
+
+  // Each RPC method answers from its script in order; a function entry throws.
+  function flaky(script: {
+    statuses: (({ confirmationStatus: string } | null) | (() => never))[];
+    heights?: (bigint | (() => never))[];
+  }) {
+    const statuses = [...script.statuses];
+    const heights = [...(script.heights ?? [])];
+    const answer = <T>(queue: (T | (() => never))[]) => {
+      const next = queue.length > 1 ? queue.shift() : queue[0];
+      return typeof next === "function" ? (next as () => never)() : next;
+    };
+    return {
+      getSignatureStatuses: vi.fn(() => ({
+        send: async () => ({ value: [answer(statuses) ?? null] }),
+      })),
+      getBlockHeight: vi.fn(() => ({ send: async () => answer(heights) })),
+    } as unknown as Rpc<SolanaRpcApi> & {
+      getSignatureStatuses: ReturnType<typeof vi.fn>;
+      getBlockHeight: ReturnType<typeof vi.fn>;
+    };
+  }
+
+  const confirm = (rpc: Rpc<SolanaRpcApi>, lastValidBlockHeight?: bigint) =>
+    solanaClient({ signer: mockSigner(), rpc })
+      .confirmTransaction({ signature: "sig" as never, lastValidBlockHeight }, { pollMs: 0 })
+      .catch((e: unknown) => e);
+
+  it("wraps a getSignatureStatuses failure, saying the transaction may still land", async () => {
+    const cause = outage();
+    const error = await confirm(
+      flaky({
+        statuses: [
+          () => {
+            throw cause;
+          },
+        ],
+      }),
+    );
+    expect(error).toBeInstanceOf(SolanaConfirmationError);
+    expect(error).toMatchObject({ reason: "rpc", mayStillLand: true, lastStatus: null, cause });
+    expect((error as Error).message).toMatch(
+      /getSignatureStatuses failed \(fetch failed: 503 Service Unavailable\).*may still land, so do not resend/,
+    );
+  });
+
+  it("wraps a getBlockHeight failure and carries the last status the poll saw", async () => {
+    const cause = outage();
+    const rpc = flaky({
+      statuses: [{ confirmationStatus: "processed" }],
+      heights: [
+        5n,
+        () => {
+          throw cause;
+        },
+      ],
+    });
+    const error = await confirm(rpc, 10n);
+    expect(error).toBeInstanceOf(SolanaConfirmationError);
+    expect(error).toMatchObject({
+      reason: "rpc",
+      mayStillLand: true,
+      lastStatus: "processed",
+      cause,
+    });
+    expect((error as Error).message).toMatch(/getBlockHeight failed/);
+    expect(rpc.getBlockHeight).toHaveBeenCalledTimes(2);
+  });
+
+  it("wraps a method that throws before it sends", async () => {
+    const cause = new TypeError("rpc transport closed");
+    const rpc = {
+      getSignatureStatuses: () => {
+        throw cause;
+      },
+    } as unknown as Rpc<SolanaRpcApi>;
+    const error = await confirm(rpc);
+    expect(error).toMatchObject({ reason: "rpc", mayStillLand: true, cause });
+  });
+
+  it("reports a failed final check past the blockhash as rpc, never as expired", async () => {
+    const rpc = flaky({
+      statuses: [
+        null,
+        () => {
+          throw outage();
+        },
+      ],
+      heights: [11n],
+    });
+    const error = await confirm(rpc, 10n);
+    expect(error).toMatchObject({ reason: "rpc", mayStillLand: true });
+    expect(error).not.toMatchObject({ reason: "expired" });
+  });
+
+  it("confirms the same submission once the RPC recovers, without sending it again", async () => {
+    const rpc = flaky({
+      statuses: [
+        () => {
+          throw outage();
+        },
+        { confirmationStatus: "confirmed" },
+      ],
+    });
+    const client = solanaClient({ signer: mockSigner(), rpc });
+    const submission = { signature: "sig" as never, lastValidBlockHeight: 10n };
+    await expect(client.confirmTransaction(submission, { pollMs: 0 })).rejects.toMatchObject({
+      reason: "rpc",
+      mayStillLand: true,
+    });
+    await expect(client.confirmTransaction(submission, { pollMs: 0 })).resolves.toBeUndefined();
+  });
+});
+
 describe("transferSol", () => {
   const blockhash = b58(new Uint8Array(32).fill(4));
 

package/src/clients/solana.ts

@@ -91,29 +91,38 @@ export interface SolanaSubmission {
   lastValidBlockHeight?: bigint;
 }
 
-export type SolanaConfirmationFailure = "failed" | "expired" | "timeout";
+export type SolanaConfirmationFailure = "failed" | "expired" | "timeout" | "rpc";
+
+export type SolanaCommitmentStatus = "processed" | "confirmed" | "finalized";
 
 /**
  * confirmTransaction's failure. `mayStillLand` is the part a caller acts on:
- * resending while it is true can pay twice.
+ * resending while it is true can pay twice. `rpc` means a status or block
+ * height poll failed, which says nothing about the transaction, so confirm the
+ * same submission again rather than sending a new one.
  */
 export class SolanaConfirmationError extends Error {
   readonly mayStillLand: boolean;
+  /** The last confirmationStatus the poll saw, or null when it never saw the signature. */
+  readonly lastStatus: SolanaCommitmentStatus | null;
   constructor(
     readonly signature: Signature,
     readonly reason: SolanaConfirmationFailure,
     detail: string,
+    options: { lastStatus?: SolanaCommitmentStatus | null; cause?: unknown } = {},
   ) {
-    const mayStillLand = reason === "timeout";
+    const mayStillLand = reason === "timeout" || reason === "rpc";
     super(
       `solana transaction ${signature} ${detail}; ${
         mayStillLand
           ? "it may still land, so do not resend it until its blockhash expires"
           : "it will not land, so it is safe to retry"
       }`,
+      { cause: options.cause },
     );
     this.name = "SolanaConfirmationError";
     this.mayStillLand = mayStillLand;
+    this.lastStatus = options.lastStatus ?? null;
   }
 }
 
@@ -141,8 +150,9 @@ export interface SolanaClient extends ChainClient<"solana"> {
   /**
    * Resolves once the transaction reaches `commitment`. Rejects with
    * SolanaConfirmationError: `failed` (it landed and errored), `expired` (block
-   * height passed lastValidBlockHeight without it, safe to retry) or `timeout`
-   * (no lastValidBlockHeight to judge by, so it may still land).
+   * height passed lastValidBlockHeight without it, safe to retry), `timeout`
+   * (no lastValidBlockHeight to judge by, so it may still land) or `rpc` (a
+   * poll failed, so it may still land; confirm it again).
    */
   confirmTransaction(
     submission: SolanaSubmission | Signature,
@@ -206,7 +216,7 @@ const lastValidBlockHeightOf = (transaction: Transaction | Uint8Array): bigint |
 
 type SignatureStatus = {
   err: unknown;
-  confirmationStatus: "processed" | "confirmed" | "finalized" | null;
+  confirmationStatus: SolanaCommitmentStatus | null;
 } | null;
 
 const reached = (status: SignatureStatus, commitment: "confirmed" | "finalized") =>
@@ -251,21 +261,6 @@ export function solanaClient(config: SolanaClientConfig): SolanaClient {
     return { signature: await broadcast(await signer.signTransaction(wire)), lastValidBlockHeight };
   };
 
-  const statusOf = async (signature: Signature): Promise<SignatureStatus> => {
-    const { value } = await rpc
-      .getSignatureStatuses([signature], { searchTransactionHistory: true })
-      .send();
-    const status = value[0] as SignatureStatus;
-    if (status?.err) {
-      throw new SolanaConfirmationError(
-        signature,
-        "failed",
-        `failed on chain: ${JSON.stringify(status.err, (_, v) => (typeof v === "bigint" ? `${v}` : v))}`,
-      );
-    }
-    return status;
-  };
-
   return {
     family: "solana",
     address: owner,
@@ -290,28 +285,53 @@ export function solanaClient(config: SolanaClientConfig): SolanaClient {
         pollMs = 500,
       } = options;
       const deadline = Date.now() + timeoutMs;
+      let lastStatus: SolanaCommitmentStatus | null = null;
+      const fail = (reason: SolanaConfirmationFailure, detail: string, cause?: unknown) =>
+        new SolanaConfirmationError(signature, reason, detail, { lastStatus, cause });
+      const poll = async <T>(method: string, call: () => Promise<T>): Promise<T> => {
+        try {
+          return await call();
+        } catch (error) {
+          throw fail(
+            "rpc",
+            `was not confirmed: ${method} failed (${error instanceof Error ? error.message : String(error)})`,
+            error,
+          );
+        }
+      };
+      const statusOf = async (): Promise<SignatureStatus> => {
+        const { value } = await poll("getSignatureStatuses", () =>
+          rpc.getSignatureStatuses([signature], { searchTransactionHistory: true }).send(),
+        );
+        const status = value[0] as SignatureStatus;
+        if (status?.confirmationStatus) lastStatus = status.confirmationStatus;
+        if (status?.err) {
+          throw fail(
+            "failed",
+            `failed on chain: ${JSON.stringify(status.err, (_, v) => (typeof v === "bigint" ? `${v}` : v))}`,
+          );
+        }
+        return status;
+      };
       for (;;) {
-        if (reached(await statusOf(signature), commitment)) return;
+        if (reached(await statusOf(), commitment)) return;
         if (lastValidBlockHeight !== undefined) {
-          const height = await rpc.getBlockHeight({ commitment }).send();
+          const height = await poll("getBlockHeight", () =>
+            rpc.getBlockHeight({ commitment }).send(),
+          );
           if (height > lastValidBlockHeight) {
             // It can no longer be included, but it may have been in the last valid block.
-            const status = await statusOf(signature);
+            const status = await statusOf();
             if (reached(status, commitment)) return;
             if (!status) {
-              throw new SolanaConfirmationError(
-                signature,
+              throw fail(
                 "expired",
                 `expired: block height ${height} passed ${lastValidBlockHeight}`,
               );
             }
           }
         } else if (Date.now() > deadline) {
-          throw new SolanaConfirmationError(
-            signature,
-            "timeout",
-            `not ${commitment} after ${timeoutMs}ms`,
-          );
+          throw fail("timeout", `not ${commitment} after ${timeoutMs}ms`);
         }
         await sleep(pollMs);
       }

package/src/connectkit/GpgProvider.tsx

@@ -0,0 +1,16 @@
+import { GpgProvider as BaseGpgProvider, type GpgConfig } from "@multiplatform.one/gpg";
+import type { ComponentProps } from "react";
+import { buildWalletMessage } from "../message";
+
+type GpgProviderProps = Omit<ComponentProps<typeof BaseGpgProvider>, "buildMessage"> &
+  Partial<Pick<GpgConfig, "buildMessage">>;
+
+const buildGpgMessage = ({ nonce }: { nonce: string }) => buildWalletMessage("gpg", { nonce });
+
+/**
+ * `@multiplatform.one/gpg`'s GpgProvider, signing mpo web3's GPG message
+ * (`buildWalletMessage("gpg")` on the page's host) unless given a builder.
+ */
+export function GpgProvider({ buildMessage = buildGpgMessage, ...props }: GpgProviderProps) {
+  return <BaseGpgProvider {...props} buildMessage={buildMessage} />;
+}

package/src/connectkit/adapters/BitcoinAdapter.ts

@@ -14,6 +14,7 @@
 // pick the "payment" (native-segwit) account; if a wallet's active address is
 // taproot (`bc1p…`) the server rejects it.
 
+import { buildWalletMessage } from "../../message";
 import type { SignInMessageOptions, WalletAdapter, WalletAddress } from "./types";
 
 interface UnisatProvider {
@@ -89,22 +90,10 @@ export class BitcoinAdapter implements WalletAdapter {
   /** Build the canonical SIWB message the Java BitcoinMessage parser accepts. */
   async buildMessage(opts: SignInMessageOptions): Promise<string> {
     if (!this.address) throw new Error("connect a Bitcoin wallet first");
-    const domain = opts.domain ?? window.location.host;
-    const uri = opts.uri ?? window.location.origin;
-    const issuedAt = opts.issuedAt ?? new Date().toISOString();
-    const statement = opts.statement ?? "Sign in With Bitcoin.";
-    return (
-      `${domain} wants you to sign in with your Bitcoin account:\n` +
-      `${this.address}\n` +
-      `\n` +
-      `${statement}\n` +
-      `\n` +
-      `URI: ${uri}\n` +
-      `Version: 1\n` +
-      `Chain ID: bitcoin\n` +
-      `Nonce: ${opts.nonce}\n` +
-      `Issued At: ${issuedAt}`
-    );
+    return buildWalletMessage("btc", {
+      ...opts,
+      address: this.address,
+    });
   }
 
   /** BIP-322 simple signature (base64) — submitted as keycloak's username. */

package/src/connectkit/adapters/EthereumAdapter.ts

@@ -10,6 +10,7 @@
 // checksummed address, so we checksum via viem's getAddress (already bundled).
 
 import { getAddress } from "viem";
+import { buildWalletMessage } from "../../message";
 import type { SignInMessageOptions, WalletAdapter, WalletAddress } from "./types";
 
 interface Eip1193Provider {
@@ -58,23 +59,11 @@ export class EthereumAdapter implements WalletAdapter {
   /** Build the canonical EIP-4361 message the Java SiweUtil/moonstoneid verifies. */
   async buildMessage(opts: SignInMessageOptions): Promise<string> {
     if (!this.address) throw new Error("connect an EVM wallet first");
-    const domain = opts.domain ?? window.location.host;
-    const uri = opts.uri ?? window.location.origin;
-    const issuedAt = opts.issuedAt ?? new Date().toISOString();
-    const statement = opts.statement ?? "Sign in With Ethereum.";
-    const chainId = this.networkId ?? 1;
-    return (
-      `${domain} wants you to sign in with your Ethereum account:\n` +
-      `${this.address}\n` +
-      `\n` +
-      `${statement}\n` +
-      `\n` +
-      `URI: ${uri}\n` +
-      `Version: 1\n` +
-      `Chain ID: ${chainId}\n` +
-      `Nonce: ${opts.nonce}\n` +
-      `Issued At: ${issuedAt}`
-    );
+    return buildWalletMessage("eth", {
+      ...opts,
+      address: this.address,
+      chainId: this.networkId ?? 1,
+    });
   }
 
   /** personal_sign — returns the 0x hex signature, submitted as keycloak's username. */

package/src/connectkit/adapters/SolanaAdapter.ts

@@ -11,6 +11,7 @@
 // (A future system-browser / Mobile-Wallet-Adapter path — the Solana analogue
 // of a relay — would be a separate adapter, same as the Ethereum gap.)
 
+import { buildWalletMessage } from "../../message";
 import type { SignInMessageOptions, WalletAdapter, WalletAddress } from "./types";
 
 const BASE58_ALPHABET = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";
@@ -84,22 +85,10 @@ export class SolanaAdapter implements WalletAdapter {
   /** Build the canonical SIWS message the Java SiwsMessage parser accepts. */
   async buildMessage(opts: SignInMessageOptions): Promise<string> {
     if (!this.address) throw new Error("connect a Solana wallet first");
-    const domain = opts.domain ?? window.location.host;
-    const uri = opts.uri ?? window.location.origin;
-    const issuedAt = opts.issuedAt ?? new Date().toISOString();
-    const statement = opts.statement ?? "Sign in With Solana.";
-    return (
-      `${domain} wants you to sign in with your Solana account:\n` +
-      `${this.address}\n` +
-      `\n` +
-      `${statement}\n` +
-      `\n` +
-      `URI: ${uri}\n` +
-      `Version: 1\n` +
-      `Chain ID: solana:mainnet\n` +
-      `Nonce: ${opts.nonce}\n` +
-      `Issued At: ${issuedAt}`
-    );
+    return buildWalletMessage("sol", {
+      ...opts,
+      address: this.address,
+    });
   }
 
   /** Sign the UTF-8 message bytes; returns the base58 ed25519 signature. */

package/src/connectkit/adapters/SuiAdapter.ts

@@ -11,6 +11,7 @@
 // from `sui:signPersonalMessage`), password = base64(message); the message's
 // address line is the 0x Sui address (blake2b256(flag||pubkey)).
 
+import { buildWalletMessage } from "../../message";
 import type { SignInMessageOptions, WalletAdapter, WalletAddress } from "./types";
 
 interface StandardWallet {
@@ -99,22 +100,10 @@ export class SuiAdapter implements WalletAdapter {
   /** Build the canonical SIWU message the Java SuiMessage parser accepts. */
   async buildMessage(opts: SignInMessageOptions): Promise<string> {
     if (!this.address) throw new Error("connect a Sui wallet first");
-    const domain = opts.domain ?? window.location.host;
-    const uri = opts.uri ?? window.location.origin;
-    const issuedAt = opts.issuedAt ?? new Date().toISOString();
-    const statement = opts.statement ?? "Sign in With Sui.";
-    return (
-      `${domain} wants you to sign in with your Sui account:\n` +
-      `${this.address}\n` +
-      `\n` +
-      `${statement}\n` +
-      `\n` +
-      `URI: ${uri}\n` +
-      `Version: 1\n` +
-      `Chain ID: sui:mainnet\n` +
-      `Nonce: ${opts.nonce}\n` +
-      `Issued At: ${issuedAt}`
-    );
+    return buildWalletMessage("sui", {
+      ...opts,
+      address: this.address,
+    });
   }
 
   /** Sui's serialized signature (flag||sig||pubkey, base64) — submitted as keycloak's username. */

package/src/connectkit/connectors/createWalletMessage.ts

@@ -1,4 +1,4 @@
-import { buildWalletMessage, type SignerFamily } from "../adapters/messages";
+import { buildWalletMessage, type SignerFamily } from "../../message";
 import { ecosystemBySyntheticChainId } from "./syntheticChains";
 
 /** Derive the signer family from the (possibly synthetic) chainId of the active connector. */

package/src/connectkit/index.ts

@@ -26,12 +26,12 @@ export type { SIWESession, SIWEConfig } from "./siwe";
 // Sign-In With GPG (SIWG) — a separate, connection-free signer that opens the SAME
 // modal to a GPG screen. Pulls in NO wagmi/viem; destined for a standalone gpg package.
 export {
-  GpgProvider,
   useGpg,
   GpgStatusState,
   GPG_NONCE_QUERY_KEY,
   SignInWithGpgButton,
 } from "@multiplatform.one/gpg";
+export { GpgProvider } from "./GpgProvider";
 export type { GpgConfig } from "@multiplatform.one/gpg";
 
 export { ConnectKitProvider } from "./web3Provider";
@@ -88,11 +88,7 @@ export {
 // The unified sign-in message layer: ONE source of truth for the SIWx message per
 // signer family, and a chain-agnostic createMessage to plug into SIWEConfig so all
 // chains sign in through ConnectKit's single signIn().
-export {
-  buildWalletMessage,
-  type SignerFamily,
-  type WalletMessageOptions,
-} from "./adapters/messages";
+export { buildWalletMessage, type SignerFamily, type WalletMessageOptions } from "../message";
 export {
   createWalletMessage,
   familyFromChainId,

package/src/connectkit/openConnector/modal.spec.tsx

@@ -8,11 +8,11 @@ import { connect } from "wagmi/actions";
 import { mock } from "wagmi/connectors";
 import { mainnet } from "wagmi/chains";
 import { routes, useContext } from "@multiplatform.one/connectkit";
-import { GpgProvider } from "@multiplatform.one/gpg";
 
 import {
   ConnectKitProvider,
   DEFAULT_DESKTOP_OPEN_CONNECTOR_FALLBACK_MS,
+  GpgProvider,
   useModal,
   type Web3ConnectKitOptions,
 } from "..";

package/src/connectkit/siwe/SIWEContext.tsx

@@ -46,10 +46,14 @@ export type SIWEConfig = {
     password: string;
     message: string;
   }) => Promise<boolean | void> | boolean | void;
+  // Called with a listener on mount; the provider refetches its nonce whenever
+  // the listener fires (e.g. keycloakWallet's resetNonce after a direct grant
+  // or registration consumed the nonce). Returns the unsubscribe.
+  subscribeNonceReset?: (listener: () => void) => () => void;
 };
 
-export type SIWEContextValue = Required<Omit<SIWEConfig, "onSign">> &
-  Pick<SIWEConfig, "onSign"> & {
+export type SIWEContextValue = Required<Omit<SIWEConfig, "onSign" | "subscribeNonceReset">> &
+  Pick<SIWEConfig, "onSign" | "subscribeNonceReset"> & {
     nonce: ReturnType<typeof useQuery<string | null>>;
     session: ReturnType<typeof useQuery<SIWESession | null>>;
     status: StatusState;

package/src/connectkit/siwe/SIWEProvider.tsx

@@ -1,7 +1,7 @@
 import { ReactNode, useContext, useEffect, useState } from "react";
 import { useAccount, useAccountEffect, useSignMessage } from "wagmi";
 import { getAddress } from "viem";
-import { useQuery } from "@tanstack/react-query";
+import { useQuery, useQueryClient } from "@tanstack/react-query";
 
 import { Context as ConnectKitContext } from "@multiplatform.one/connectkit";
 import { SIWEContext, SIWEConfig, StatusState, SIWESession } from "./SIWEContext";
@@ -46,6 +46,7 @@ export const SIWEProvider = ({
     throw new Error("ConnectKitProvider must be mounted inside SIWEProvider.");
   }
 
+  const queryClient = useQueryClient();
   const nonce = useQuery({
     queryKey: [SIWE_NONCE_QUERY_KEY],
     queryFn: () => siweConfig.getNonce(),
@@ -60,6 +61,15 @@ export const SIWEProvider = ({
     staleTime: Infinity,
   });
 
+  const { subscribeNonceReset } = siweConfig;
+  const refetchNonce = nonce.refetch;
+  useEffect(() => {
+    if (!subscribeNonceReset) return;
+    return subscribeNonceReset(() => {
+      void refetchNonce();
+    });
+  }, [subscribeNonceReset, refetchNonce]);
+
   const session = useQuery({
     queryKey: [SIWE_SESSION_QUERY_KEY],
     queryFn: () => siweConfig.getSession(),
@@ -118,16 +128,23 @@ export const SIWEProvider = ({
       if (!address) throw new Error("No address found");
       if (!chainId) throw new Error("No chainId found");
 
-      if (!nonce.data) {
+      setStatus(StatusState.LOADING);
+
+      // Read the query live, not this render's `nonce`: right after a reset
+      // its data is the nonce the server just dropped, so wait for the refetch.
+      const nonceState = queryClient.getQueryState<string>([SIWE_NONCE_QUERY_KEY]);
+      const nonceValue =
+        nonceState?.fetchStatus === "fetching"
+          ? (await nonce.refetch({ cancelRefetch: false })).data
+          : nonceState?.data;
+      if (!nonceValue) {
         throw new Error("Could not fetch nonce");
       }
 
-      setStatus(StatusState.LOADING);
-
       const message = await siweConfig.createMessage({
         address,
         chainId,
-        nonce: nonce?.data,
+        nonce: nonceValue,
       });
 
       // Ask user to sign message with their wallet. wallet (non-EVM) connectors can't

package/src/index.ts

@@ -3,6 +3,8 @@ export {
   WalletProvider,
   useWeb3Config,
   defaultChains,
+  useWalletBridge,
+  type WalletBridgeContextValue,
   type WalletProviderProps,
   type Web3Config,
 } from "./providers";
@@ -64,6 +66,9 @@ export { mainnet, polygon, optimism, arbitrum, base, sepolia } from "wagmi/chain
 // Bridge (Hermes-safe; shared by web + the native WebView host)
 export * from "./bridge";
 
+// The one wallet sign-in message builder (Hermes-safe)
+export * from "./message";
+
 // Per-chain clients (EVM on viem, GPG signer, Solana/Sui/Bitcoin message signing;
 // the Solana kit client is the web-only ./solana subpath)
 export * from "./clients";

package/src/keycloak/KeycloakWalletLogin.native.tsx

@@ -0,0 +1,7 @@
+import type { KeycloakWalletLoginProps } from "./KeycloakWalletLogin";
+
+export type { KeycloakWalletLoginProps };
+
+export function KeycloakWalletLogin(_props: KeycloakWalletLoginProps): null {
+  throw new Error("KeycloakWalletLogin is web only; a native app signs in with useDirectLogin");
+}