@openzeppelin/miden-multisig-client 0.15.2 → 0.16.1

package/src/client.test.ts

@@ -55,6 +55,10 @@ vi.mock('./account/index.js', () => ({
 const mockFetch = vi.fn();
 vi.stubGlobal('fetch', mockFetch);
 
+const GUARDIAN_URL = 'http://localhost:3000';
+const MIDEN_RPC = 'http://localhost:57291';
+const CLIENT_CONFIG = { guardianEndpoint: GUARDIAN_URL, midenRpcEndpoint: MIDEN_RPC };
+
 describe('MultisigClient', () => {
   let webClient: any;
   let mockSigner: Signer;
@@ -83,27 +87,75 @@ describe('MultisigClient', () => {
   });
 
   describe('constructor', () => {
-    it('should create client with default GUARDIAN endpoint', () => {
-      const client = new MultisigClient(webClient);
+    it('should create client when both endpoints are supplied', () => {
+      const client = new MultisigClient(webClient, CLIENT_CONFIG);
       expect(client).toBeInstanceOf(MultisigClient);
     });
 
     it('should create client with custom GUARDIAN endpoint', () => {
-      const client = new MultisigClient(webClient, { guardianEndpoint: 'http://custom:8080' });
+      const client = new MultisigClient(webClient, {
+        guardianEndpoint: 'http://custom:8080',
+        midenRpcEndpoint: MIDEN_RPC,
+      });
       expect(client).toBeInstanceOf(MultisigClient);
     });
+
+    it('throws when the config object is omitted', () => {
+      expect(() => new (MultisigClient as any)(webClient)).toThrow(
+        'missing required configuration: midenRpcEndpoint',
+      );
+    });
+
+    it.each([undefined, null, 42, '', '   '])(
+      'throws before any network or store access when midenRpcEndpoint is %j',
+      (endpoint) => {
+        expect(
+          () =>
+            new MultisigClient(webClient, {
+              guardianEndpoint: GUARDIAN_URL,
+              midenRpcEndpoint: endpoint as any,
+            }),
+        ).toThrow('missing required configuration: midenRpcEndpoint');
+        expect(mockFetch).not.toHaveBeenCalled();
+        expect(webClient.accounts.get).not.toHaveBeenCalled();
+        expect(webClient.accounts.insert).not.toHaveBeenCalled();
+      },
+    );
+
+    it.each([undefined, null, 42, '', '   '])(
+      'throws before any network or store access when guardianEndpoint is %j',
+      (endpoint) => {
+        expect(
+          () =>
+            new MultisigClient(webClient, {
+              guardianEndpoint: endpoint as any,
+              midenRpcEndpoint: MIDEN_RPC,
+            }),
+        ).toThrow('missing required configuration: guardianEndpoint');
+        expect(mockFetch).not.toHaveBeenCalled();
+        expect(webClient.accounts.get).not.toHaveBeenCalled();
+        expect(webClient.accounts.insert).not.toHaveBeenCalled();
+      },
+    );
+
+    it('rejects a blank endpoint passed to setGuardianEndpoint', () => {
+      const client = new MultisigClient(webClient, CLIENT_CONFIG);
+      expect(() => client.setGuardianEndpoint('   ')).toThrow(
+        'missing required configuration: guardianEndpoint',
+      );
+    });
   });
 
   describe('guardianClient getter', () => {
     it('should expose GUARDIAN client for getting pubkey', () => {
-      const client = new MultisigClient(webClient);
+      const client = new MultisigClient(webClient, CLIENT_CONFIG);
       expect(client.guardianClient).toBeDefined();
     });
   });
 
   describe('create', () => {
     it('should create multisig and return Multisig instance', async () => {
-      const client = new MultisigClient(webClient);
+      const client = new MultisigClient(webClient, CLIENT_CONFIG);
 
       const config = {
         threshold: 2,
@@ -120,7 +172,7 @@ describe('MultisigClient', () => {
     });
 
     it('should set signer on GUARDIAN client', async () => {
-      const client = new MultisigClient(webClient);
+      const client = new MultisigClient(webClient, CLIENT_CONFIG);
 
       const config = {
         threshold: 1,
@@ -133,7 +185,7 @@ describe('MultisigClient', () => {
     });
 
     it('binds the signer auth key to the created account when supported', async () => {
-      const client = new MultisigClient(webClient);
+      const client = new MultisigClient(webClient, CLIENT_CONFIG);
       const bindAccountKey = vi.fn().mockResolvedValue(undefined);
       const bindingSigner = {
         ...mockSigner,
@@ -152,7 +204,7 @@ describe('MultisigClient', () => {
 
   describe('load', () => {
     it('should load existing multisig account and detect config', async () => {
-      const client = new MultisigClient(webClient);
+      const client = new MultisigClient(webClient, CLIENT_CONFIG);
 
       // Mock getState response
       mockFetch.mockResolvedValueOnce({
@@ -181,7 +233,7 @@ describe('MultisigClient', () => {
     });
 
     it('should throw if account not found on GUARDIAN', async () => {
-      const client = new MultisigClient(webClient);
+      const client = new MultisigClient(webClient, CLIENT_CONFIG);
 
       mockFetch.mockResolvedValueOnce({
         ok: false,
@@ -196,7 +248,7 @@ describe('MultisigClient', () => {
     });
 
     it('should allow registerOnGuardian after load without explicit initial state', async () => {
-      const client = new MultisigClient(webClient);
+      const client = new MultisigClient(webClient, CLIENT_CONFIG);
 
       mockFetch.mockResolvedValueOnce({
         ok: true,
@@ -227,7 +279,7 @@ describe('MultisigClient', () => {
     });
 
     it('binds the signer auth key after loading an account when supported', async () => {
-      const client = new MultisigClient(webClient);
+      const client = new MultisigClient(webClient, CLIENT_CONFIG);
       const bindAccountKey = vi.fn().mockResolvedValue(undefined);
       const bindingSigner = {
         ...mockSigner,
@@ -289,7 +341,7 @@ describe('MultisigClient', () => {
     }
 
     it('returns one (accountId, state) pair when lookup matches a single account', async () => {
-      const client = new MultisigClient(webClient);
+      const client = new MultisigClient(webClient, CLIENT_CONFIG);
       const signer = makeLookupCapableSigner();
       const accountId = '0x7bfb0f38b0fafa103f86a805594170';
 
@@ -311,7 +363,7 @@ describe('MultisigClient', () => {
     });
 
     it('returns multiple (accountId, state) pairs when one commitment authorizes several accounts', async () => {
-      const client = new MultisigClient(webClient);
+      const client = new MultisigClient(webClient, CLIENT_CONFIG);
       const signer = makeLookupCapableSigner();
       const accountA = '0xaaa1';
       const accountB = '0xbbb2';
@@ -328,7 +380,7 @@ describe('MultisigClient', () => {
     });
 
     it('returns empty array when no account authorizes the commitment', async () => {
-      const client = new MultisigClient(webClient);
+      const client = new MultisigClient(webClient, CLIENT_CONFIG);
       const signer = makeLookupCapableSigner();
 
       mockServerLookupResponse([]);
@@ -341,7 +393,7 @@ describe('MultisigClient', () => {
     });
 
     it('throws a clear error when the signer does not implement signLookupMessage', async () => {
-      const client = new MultisigClient(webClient);
+      const client = new MultisigClient(webClient, CLIENT_CONFIG);
       // mockSigner from the outer beforeEach lacks signLookupMessage.
       await expect(client.recoverByKey(mockSigner)).rejects.toThrow(/signLookupMessage/);
       expect(mockFetch).not.toHaveBeenCalled();

package/src/client.ts

@@ -11,8 +11,13 @@ import type { StateObject } from '@openzeppelin/guardian-client';
 import { Multisig } from './multisig.js';
 import { createMultisigAccount } from './account/index.js';
 import { AccountInspector } from './inspector.js';
-import { getRawMidenClient, resolveMidenRpcEndpoint } from './raw-client.js';
+import { getRawMidenClient, requireConfigValue, requireMidenRpcEndpoint } from './raw-client.js';
 import type { MultisigConfig, Signer } from './types.js';
+import {
+  resolveProverConfig,
+  type ProverConfig,
+  type ResolvedProverConfig,
+} from './prover/config.js';
 
 interface AccountKeyBindingSigner {
   bindAccountKey?(midenClient: MidenClient, accountId: string): Promise<void>;
@@ -33,10 +38,16 @@ async function bindSignerAccountKey(
  * Configuration for MultisigClient.
  */
 export interface MultisigClientConfig {
-  /** GUARDIAN server endpoint */
-  guardianEndpoint?: string;
-  /** Miden node RPC endpoint used for state commitment verification */
-  midenRpcEndpoint?: string;
+  /** GUARDIAN server endpoint. Required — there is no default. */
+  guardianEndpoint: string;
+  /**
+   * Miden node RPC endpoint used for proposal execution and state
+   * commitment verification. Required — must point at the same network as
+   * the injected `MidenClient`; there is no default.
+   */
+  midenRpcEndpoint: string;
+  /** Multisig-owned remote prover override and proof retry policy. */
+  prover?: ProverConfig;
 }
 
 /**
@@ -66,6 +77,10 @@ export interface RecoveredAccount {
  * const client = new MultisigClient(midenClient, {
  *   guardianEndpoint: 'http://localhost:3000',
  *   midenRpcEndpoint: 'https://rpc.devnet.miden.io',
+ *   prover: {
+ *     url: 'https://prover.example',
+ *     retry: { maxAttempts: 4 },
+ *   },
  * });
  *
  * // Get GUARDIAN pubkey for config
@@ -79,21 +94,27 @@ export interface RecoveredAccount {
 export class MultisigClient {
   private readonly midenClient: MidenClient;
   private readonly midenRpcEndpoint: string;
+  private readonly proverConfig: ResolvedProverConfig;
   private _guardianClient: GuardianHttpClient;
 
-  constructor(midenClient: MidenClient, config: MultisigClientConfig = {}) {
+  constructor(midenClient: MidenClient, config: MultisigClientConfig) {
     this.midenClient = midenClient;
-    this.midenRpcEndpoint = resolveMidenRpcEndpoint(config.midenRpcEndpoint);
-    this._guardianClient = new GuardianHttpClient(config.guardianEndpoint ?? 'http://localhost:3000');
+    this.midenRpcEndpoint = requireMidenRpcEndpoint(config?.midenRpcEndpoint);
+    this.proverConfig = resolveProverConfig(config?.prover, midenClient.defaultProver);
+    this._guardianClient = new GuardianHttpClient(
+      requireConfigValue('guardianEndpoint', config?.guardianEndpoint),
+    );
   }
 
   /**
    * Change the GUARDIAN endpoint.
-   * 
+   *
    * @param endpoint - The new GUARDIAN server endpoint URL
    */
   setGuardianEndpoint(endpoint: string): void {
-    this._guardianClient = new GuardianHttpClient(endpoint);
+    this._guardianClient = new GuardianHttpClient(
+      requireConfigValue('guardianEndpoint', endpoint),
+    );
   }
 
   /**
@@ -153,7 +174,8 @@ export class MultisigClient {
       signer,
       this.midenClient,
       undefined,
-      this.midenRpcEndpoint
+      this.midenRpcEndpoint,
+      this.proverConfig,
     );
   }
 
@@ -205,7 +227,8 @@ export class MultisigClient {
       signer,
       this.midenClient,
       accountId,
-      this.midenRpcEndpoint
+      this.midenRpcEndpoint,
+      this.proverConfig,
     );
   }
 }

package/src/connectivity.test.ts

@@ -0,0 +1,67 @@
+import { describe, it, expect } from 'vitest';
+import { GuardianHttpError } from '@openzeppelin/guardian-client';
+import { isLikelyNetworkError, toUserFacingError } from './connectivity.js';
+
+describe('isLikelyNetworkError', () => {
+  it('flags codeless transport failures', () => {
+    for (const m of [
+      'Failed to fetch',
+      'NetworkError when attempting to fetch resource',
+      'Load failed',
+      'The operation was aborted',
+      'request timed out',
+      'connection refused',
+      'getaddrinfo ENOTFOUND guardian.example',
+    ]) {
+      expect(isLikelyNetworkError(new TypeError(m))).toBe(true);
+    }
+  });
+
+  it('does not flag semantic errors', () => {
+    expect(isLikelyNetworkError(new Error('account is paused'))).toBe(false);
+    expect(isLikelyNetworkError(new Error('insufficient signatures'))).toBe(false);
+  });
+});
+
+describe('toUserFacingError', () => {
+  it('uses the server code + user-safe message when Guardian was reached', () => {
+    const body = JSON.stringify({
+      code: 'account_paused',
+      message: "This account is paused and can't approve transactions right now.",
+      meta: { retryable: false },
+    });
+    const result = toUserFacingError(new GuardianHttpError(409, 'Conflict', body));
+    expect(result.code).toBe('account_paused');
+    expect(result.userMessage).toContain('paused');
+    expect(result.category).toBeUndefined();
+  });
+
+  it('classifies a codeless transport failure as connectivity', () => {
+    const result = toUserFacingError(new TypeError('Failed to fetch'));
+    expect(result.code).toBeUndefined();
+    expect(result.category).toBe('unreachable');
+    expect(result.userMessage).toContain("Can't reach Guardian");
+    // The raw transport text is never the primary message.
+    expect(result.userMessage).not.toContain('Failed to fetch');
+  });
+
+  it('classifies timeouts and aborts as the timeout category', () => {
+    for (const m of ['request timed out', 'The operation was aborted']) {
+      const result = toUserFacingError(new Error(m));
+      expect(result.category).toBe('timeout');
+      expect(result.userMessage).toContain("Can't reach Guardian");
+    }
+  });
+
+  it('treats a reachable proxy 5xx with no Guardian body as connectivity', () => {
+    const result = toUserFacingError(new GuardianHttpError(502, 'Bad Gateway', '<html>nope</html>'));
+    expect(result.category).toBe('unreachable');
+    expect(result.userMessage).toContain("Can't reach Guardian");
+  });
+
+  it('falls back to a generic message for unknown non-Guardian errors', () => {
+    const result = toUserFacingError(new Error('totally unexpected'));
+    expect(result.userMessage).toBe('Something went wrong. Please try again.');
+    expect(result.userMessage).not.toContain('totally unexpected');
+  });
+});

package/src/connectivity.ts

@@ -0,0 +1,111 @@
+/**
+ * Classification for codeless transport failures (feature
+ * `009-human-readable-errors`, User Story 3).
+ *
+ * When Guardian *is* reached, errors arrive as a {@link GuardianHttpError}
+ * carrying the server's stable `code` and user-safe `message` — use those.
+ * When Guardian is *not* reached (connection refused, DNS, timeout, TLS, or a
+ * proxy 5xx with no Guardian body) no error object exists, so the wallet-facing
+ * client must classify the failure and supply a friendly connectivity message
+ * rather than surfacing raw `"Failed to fetch"` / `"NetworkError"` text.
+ *
+ * The detection is intentionally string-matching, mirroring the 0xMiden/wallet
+ * `connectivity-classify.ts` heuristic: fetch / DOMException / TypeError each
+ * surface failures with different shapes, so the message string is the only
+ * stable join key.
+ */
+import { GuardianHttpError } from '@openzeppelin/guardian-client';
+
+/**
+ * Connectivity category for a codeless transport failure:
+ * - `network` — the browser/OS reports no connectivity at all
+ *   (`navigator.onLine === false`); the problem is on the user's side.
+ * - `timeout` — the request was sent but timed out or was aborted.
+ * - `unreachable` — everything else: Guardian (or an intermediary) could not
+ *   be reached or did not answer with a Guardian error object.
+ */
+export type ConnectivityCategory = 'network' | 'unreachable' | 'timeout';
+
+const CONNECTIVITY_MESSAGE = "Can't reach Guardian right now. Check your connection and try again.";
+const GENERIC_MESSAGE = 'Something went wrong. Please try again.';
+
+/**
+ * `navigator.onLine` is unreliable as a positive signal, but a `false` means
+ * the browser/OS is certain there is no connectivity — categorize as
+ * `network` rather than `unreachable` (mirrors the wallet's
+ * `isDefinitelyOffline`). Guarded for non-browser (Node) contexts.
+ */
+function isDefinitelyOffline(): boolean {
+  if (typeof navigator === 'undefined') return false;
+  if (typeof navigator.onLine !== 'boolean') return false;
+  return navigator.onLine === false;
+}
+
+/** Classify a codeless transport failure into a {@link ConnectivityCategory}. */
+function classifyTransportError(err: unknown): ConnectivityCategory {
+  if (isDefinitelyOffline()) return 'network';
+  const message = (err as { message?: string } | null | undefined)?.message ?? String(err ?? '');
+  const lower = message.toLowerCase();
+  if (lower.includes('timeout') || lower.includes('timed out') || lower.includes('abort')) {
+    return 'timeout';
+  }
+  return 'unreachable';
+}
+
+/**
+ * Does this error look like a codeless transport/connectivity failure (vs a
+ * semantic Guardian error)? String heuristic — see module docs.
+ */
+export function isLikelyNetworkError(err: unknown): boolean {
+  const message = (err as { message?: string } | null | undefined)?.message ?? String(err ?? '');
+  const lower = message.toLowerCase();
+  if (lower.includes('failed to fetch')) return true;
+  if (lower.includes('networkerror')) return true;
+  if (lower.includes('network error')) return true;
+  if (lower.includes('load failed')) return true;
+  if (lower.includes('abort')) return true;
+  if (lower.includes('timeout') || lower.includes('timed out')) return true;
+  if (lower.includes('connection')) return true;
+  if (lower.includes('econnrefused') || lower.includes('enotfound')) return true;
+  if (lower.includes('dns')) return true;
+  return false;
+}
+
+/** A normalized, wallet-displayable view of any error thrown by a Guardian call. */
+export interface UserFacingError {
+  /** Stable Guardian error code, when the server was reached. */
+  code?: string;
+  /** Connectivity category, when this was a codeless transport failure. */
+  category?: ConnectivityCategory;
+  /** Short message safe to display verbatim in a wallet UI. */
+  userMessage: string;
+  /** The original error, for logging/diagnostics. */
+  cause: unknown;
+}
+
+/**
+ * Normalize any error thrown by a Guardian call into a user-facing shape.
+ *
+ * - A {@link GuardianHttpError} with a parsed `{ code, message }` → the
+ *   server's stable code + user-safe message (feature 009).
+ * - A reachable host that returned no Guardian error object (e.g. a proxy 5xx
+ *   with an HTML body) → treated as a connectivity failure.
+ * - A codeless transport rejection (server never reached) → classified and
+ *   given the generic connectivity message; the raw transport text is never
+ *   surfaced as the primary message.
+ */
+export function toUserFacingError(err: unknown): UserFacingError {
+  if (err instanceof GuardianHttpError) {
+    if (err.code && err.userMessage) {
+      return { code: err.code, userMessage: err.userMessage, cause: err };
+    }
+    if (err.status >= 500) {
+      return { category: 'unreachable', userMessage: CONNECTIVITY_MESSAGE, cause: err };
+    }
+    return { userMessage: GENERIC_MESSAGE, cause: err };
+  }
+  if (isLikelyNetworkError(err)) {
+    return { category: classifyTransportError(err), userMessage: CONNECTIVITY_MESSAGE, cause: err };
+  }
+  return { userMessage: GENERIC_MESSAGE, cause: err };
+}

package/src/index.ts

@@ -20,10 +20,15 @@
  * // Create a signer
  * const signer = new FalconSigner(secretKey);
  *
- * // Create multisig client
+ * // Create multisig client. Both endpoints are required; midenRpcEndpoint
+ * // must point at the same network as the injected MidenClient.
  * const client = new MultisigClient(midenClient, {
  *   guardianEndpoint: 'http://localhost:3000',
  *   midenRpcEndpoint: 'https://rpc.devnet.miden.io',
+ *   prover: {
+ *     url: 'https://prover.example',
+ *     retry: { maxAttempts: 4 },
+ *   },
  * });
  *
  * // Get GUARDIAN pubkey for config
@@ -44,6 +49,7 @@ export {
   type MultisigClientConfig,
   type RecoveredAccount,
 } from './client.js';
+export type { ProverConfig, ProverRetryPolicy } from './prover/config.js';
 export { lookupAuthDigest } from './lookupAuth.js';
 export { Multisig, type AccountState } from './multisig.js';
 export { AccountInspector, type DetectedMultisigConfig, type VaultBalance } from './inspector.js';
@@ -54,9 +60,25 @@ export {
   buildUpdateGuardianTransactionRequest,
   buildConsumeNotesTransactionRequest,
   buildP2idTransactionRequest,
+  parseP2idNoteType,
+  p2idNoteTypeToMetadata,
+  type P2idTransactionOptions,
 } from './transaction.js';
 
 export { GuardianHttpClient, GuardianHttpError } from '@openzeppelin/guardian-client';
+export type { GuardianErrorMeta } from '@openzeppelin/guardian-client';
+// Typed error-code vocabulary (issue #318): branch on GuardianErrorCode,
+// never on message text; unknown wire codes surface via rawCode.
+export {
+  GUARDIAN_ERROR_CODES,
+  isGuardianErrorCode,
+  normalizeGuardianErrorCode,
+} from '@openzeppelin/guardian-client';
+export type { GuardianErrorCode } from '@openzeppelin/guardian-client';
+
+// Codeless transport-failure classification (feature 009, User Story 3).
+export { isLikelyNetworkError, toUserFacingError } from './connectivity.js';
+export type { ConnectivityCategory, UserFacingError } from './connectivity.js';
 
 export {
   FalconSigner,
@@ -84,6 +106,8 @@ export {
   MAX_CONSUME_NOTES_METADATA_BYTES,
   isConsumeNotesV1,
   isConsumeNotesV2,
+  isP2idNoteVisibility,
+  type P2idNoteVisibility,
 } from './types/proposal.js';
 
 export {