@openzeppelin/miden-multisig-client 0.16.1 → 0.16.2

package/src/prover/errors.ts

@@ -1,178 +1,10 @@
-type ErrorRecord = {
-  cause?: unknown;
-  code?: unknown;
-  status?: unknown;
-  statusCode?: unknown;
-  message?: unknown;
-};
-
-type StructuredEvidence = 'transient' | 'permanent' | 'indeterminate';
-
-const TRANSIENT_GRPC = new Set([
-  'cancelled',
-  'canceled',
-  'deadlineexceeded',
-  'unavailable',
-  'resourceexhausted',
-]);
-
-const PERMANENT_GRPC = new Set([
-  'invalidargument',
-  'failedprecondition',
-  'permissiondenied',
-  'unauthenticated',
-  'notfound',
-  'alreadyexists',
-  'outofrange',
-  'unimplemented',
-  'aborted',
-  'internal',
-  'dataloss',
-]);
-
-const TRANSIENT_HTTP = new Set([408, 429, 502, 503, 504]);
-const NUMERIC_GRPC_CODES = new Map<number, string>([
-  [0, 'ok'],
-  [1, 'cancelled'],
-  [2, 'unknown'],
-  [3, 'invalidargument'],
-  [4, 'deadlineexceeded'],
-  [5, 'notfound'],
-  [6, 'alreadyexists'],
-  [7, 'permissiondenied'],
-  [8, 'resourceexhausted'],
-  [9, 'failedprecondition'],
-  [10, 'aborted'],
-  [11, 'outofrange'],
-  [12, 'unimplemented'],
-  [13, 'internal'],
-  [14, 'unavailable'],
-  [15, 'dataloss'],
-  [16, 'unauthenticated'],
-]);
-
-function normalizeCode(value: unknown): string | undefined {
-  if (typeof value === 'number') {
-    return NUMERIC_GRPC_CODES.get(value);
-  }
-  return typeof value === 'string' ? value.replaceAll(/[\s_-]/g, '').toLowerCase() : undefined;
-}
-
-function grpcEvidence(value: unknown): StructuredEvidence | undefined {
-  const code = normalizeCode(value);
-  if (code === undefined) {
-    return undefined;
-  }
-  if (TRANSIENT_GRPC.has(code)) {
-    return 'transient';
-  }
-  if (PERMANENT_GRPC.has(code)) {
-    return 'permanent';
-  }
-  if (code === 'unknown' || code === 'ok') {
-    return 'indeterminate';
-  }
-  return undefined;
-}
-
-function httpEvidence(value: unknown): StructuredEvidence | undefined {
-  if (typeof value !== 'number' || !Number.isInteger(value) || value < 400 || value > 599) {
-    return undefined;
-  }
-  return TRANSIENT_HTTP.has(value) ? 'transient' : 'permanent';
-}
-
-function httpMessageEvidence(message: string): StructuredEvidence | undefined {
-  let hasTransient = false;
-  for (const match of message.matchAll(
-    /(?:\bhttp(?:\s+status)?|\bstatus\s*:?)\s*(\d{3})\b/g,
-  )) {
-    const evidence = httpEvidence(Number(match[1]));
-    if (evidence === 'permanent') {
-      return 'permanent';
-    }
-    hasTransient ||= evidence === 'transient';
-  }
-  return hasTransient ? 'transient' : undefined;
-}
-
-function flattenedTransient(message: string): boolean {
-  return [
-    'cancelled',
-    'canceled',
-    'deadline exceeded',
-    'timeout',
-    'unavailable',
-    'resource exhausted',
-    'request timeout',
-    'too many requests',
-    'rate limited',
-    'rate limit',
-    'bad gateway',
-    'service unavailable',
-    'gateway timeout',
-    'i/o timeout',
-    'io timeout',
-    'connection reset',
-    'broken pipe',
-  ].some((signal) => message.includes(signal));
-}
-
-function asRecord(value: unknown): ErrorRecord | undefined {
-  return typeof value === 'object' && value !== null ? value as ErrorRecord : undefined;
-}
+import { isTransientError } from '../retry/classify.js';
 
+/**
+ * Prover-policy classification: the shared classifier with no transport-text
+ * extras — a bare "connection error" from a prover is treated as its
+ * considered answer.
+ */
 export function isTransientProverError(error: unknown): boolean {
-  const seen = new Set<object>();
-  const messages: string[] = [];
-  let hasTransient = false;
-  let hasPermanent = false;
-  let current: unknown = error;
-
-  while (current !== undefined && current !== null) {
-    const record = asRecord(current);
-    if (record !== undefined) {
-      if (seen.has(record)) {
-        break;
-      }
-      seen.add(record);
-      for (const evidence of [
-        grpcEvidence(record.code),
-        httpEvidence(record.status),
-        httpEvidence(record.statusCode),
-      ]) {
-        hasTransient ||= evidence === 'transient';
-        hasPermanent ||= evidence === 'permanent';
-      }
-      if (typeof record.message === 'string') {
-        const message = record.message.toLowerCase();
-        messages.push(message);
-        const evidence = httpMessageEvidence(message);
-        hasTransient ||= evidence === 'transient';
-        hasPermanent ||= evidence === 'permanent';
-      } else {
-        const message = String(current).toLowerCase();
-        messages.push(message);
-        const evidence = httpMessageEvidence(message);
-        hasTransient ||= evidence === 'transient';
-        hasPermanent ||= evidence === 'permanent';
-      }
-      current = record.cause;
-    } else {
-      const message = String(current).toLowerCase();
-      messages.push(message);
-      const evidence = httpMessageEvidence(message);
-      hasTransient ||= evidence === 'transient';
-      hasPermanent ||= evidence === 'permanent';
-      break;
-    }
-  }
-
-  if (hasPermanent) {
-    return false;
-  }
-  if (hasTransient) {
-    return true;
-  }
-  return messages.some(flattenedTransient);
+  return isTransientError(error);
 }

package/src/prover/retry.test.ts

@@ -1,6 +1,6 @@
 import { readFileSync } from 'node:fs';
 import { describe, expect, it } from 'vitest';
-import { retryDelay } from './retry.js';
+import { retryDelay } from '../retry/runtime.js';
 
 interface Fixtures {
   delays: Array<{ retryIndex: number; unitRandom: number; delayMs: number }>;

package/src/prover/retry.ts

@@ -1,46 +1,21 @@
 import type { TransactionExecution, TransactionProof } from '@miden-sdk/miden-sdk';
 import type { ResolvedProverConfig } from './config.js';
 import { isTransientProverError } from './errors.js';
-
-const BASE_DELAY_MS = 500;
-const MAX_DELAY_MS = 8_000;
-
-export interface RetryRuntime {
-  sleep(delayMs: number): Promise<void>;
-  unitRandom(): number;
-}
-
-export const productionRetryRuntime: RetryRuntime = {
-  sleep: (delayMs) => new Promise((resolve) => setTimeout(resolve, delayMs)),
-  unitRandom: () => Math.random(),
-};
-
-export function retryDelay(retryIndex: number, unitRandom: number): number {
-  const exponent = Math.min(retryIndex, 1023);
-  const raw = BASE_DELAY_MS * 2 ** exponent;
-  const finiteRandom = Number.isFinite(unitRandom) ? unitRandom : 0.5;
-  const boundedRandom = Math.min(Math.max(finiteRandom, 0), 1 - Number.EPSILON);
-  return Math.min(Math.floor(raw * (0.75 + boundedRandom * 0.5)), MAX_DELAY_MS);
-}
+import type { RetryRuntime } from '../retry/runtime.js';
+import { productionRetryRuntime, retryTransient } from '../retry/runtime.js';
 
 export async function proveWithRetry(
   execution: TransactionExecution,
   config: ResolvedProverConfig,
   runtime: RetryRuntime = productionRetryRuntime,
 ): Promise<TransactionProof> {
-  for (let attempt = 0; attempt < config.maxAttempts; attempt += 1) {
-    try {
+  return retryTransient(
+    async () => {
       const prover = config.createProver();
-      return prover === undefined
-        ? await execution.prove()
-        : await execution.prove({ prover });
-    } catch (error) {
-      if (!isTransientProverError(error) || attempt + 1 >= config.maxAttempts) {
-        throw error;
-      }
-      await runtime.sleep(retryDelay(attempt, runtime.unitRandom()));
-    }
-  }
-
-  throw new Error('unreachable prover retry state');
+      return prover === undefined ? await execution.prove() : await execution.prove({ prover });
+    },
+    config.maxAttempts,
+    isTransientProverError,
+    runtime,
+  );
 }

package/src/prover/workflow.test.ts

@@ -6,7 +6,7 @@ import type {
 } from '@miden-sdk/miden-sdk';
 import { describe, expect, it, vi } from 'vitest';
 import type { ResolvedProverConfig } from './config.js';
-import type { RetryRuntime } from './retry.js';
+import type { RetryRuntime } from '../retry/runtime.js';
 import { ProverWorkflow } from './workflow.js';
 
 function asType<T>(value: unknown): T {
@@ -89,6 +89,37 @@ describe('ProverWorkflow', () => {
     expect(runtime.sleep).toHaveBeenCalledTimes(1);
   });
 
+  it('never re-submits when submission fails with transient-looking wording', async () => {
+    const rateLimited = Object.assign(new Error('Too Many Requests!'), {
+      code: 'ResourceExhausted',
+    });
+    const submit = vi.fn().mockRejectedValue(rateLimited);
+    const prove = vi.fn().mockResolvedValue({ submit });
+    const client = {
+      transactions: { executeRequest: vi.fn().mockResolvedValue({ prove }) },
+    };
+    const runtime: RetryRuntime = {
+      sleep: vi.fn().mockResolvedValue(undefined),
+      unitRandom: () => 0.5,
+    };
+    const workflow = new ProverWorkflow(
+      asType<MidenClient>(client),
+      {
+        kind: 'remote',
+        maxAttempts: 5,
+        createProver: () => asType<TransactionProver>({}),
+      },
+      runtime,
+    );
+
+    await expect(
+      workflow.submit(asType<AccountId>({}), asType<TransactionRequest>({})),
+    ).rejects.toBe(rateLimited);
+    expect(prove).toHaveBeenCalledTimes(1);
+    expect(submit).toHaveBeenCalledTimes(1);
+    expect(runtime.sleep).not.toHaveBeenCalled();
+  });
+
   it('uses the injected prover directly when no cloneable remote override exists', async () => {
     const apply = vi.fn().mockResolvedValue({});
     const submit = vi.fn().mockResolvedValue({ apply });

package/src/prover/workflow.ts

@@ -1,6 +1,6 @@
 import type { AccountId, MidenClient, TransactionRequest } from '@miden-sdk/miden-sdk';
 import type { ResolvedProverConfig } from './config.js';
-import type { RetryRuntime } from './retry.js';
+import type { RetryRuntime } from '../retry/runtime.js';
 import { proveWithRetry } from './retry.js';
 
 export class ProverWorkflow {

package/src/retry/classify.ts

@@ -0,0 +1,220 @@
+/**
+ * Transient/permanent error classification shared by the prover and node-RPC
+ * retry policies, mirroring `is_transient_error_with` in the Rust
+ * `guardian-shared` crate: the whole cause chain is walked accumulating
+ * evidence, permanent evidence anywhere vetoes transient anywhere, and the
+ * transient-wording fallback fires only when no status-level evidence exists
+ * in any link. Behavior is pinned by the cross-SDK fixture corpus.
+ */
+
+type ErrorRecord = {
+  cause?: unknown;
+  code?: unknown;
+  status?: unknown;
+  statusCode?: unknown;
+  message?: unknown;
+};
+
+type StructuredEvidence = 'transient' | 'permanent' | 'indeterminate';
+
+const TRANSIENT_GRPC = new Set([
+  'cancelled',
+  'canceled',
+  'deadlineexceeded',
+  'unavailable',
+  'resourceexhausted',
+]);
+
+const PERMANENT_GRPC = new Set([
+  'invalidargument',
+  'failedprecondition',
+  'permissiondenied',
+  'unauthenticated',
+  'notfound',
+  'alreadyexists',
+  'outofrange',
+  'unimplemented',
+  'aborted',
+  'internal',
+  'dataloss',
+]);
+
+const TRANSIENT_HTTP = new Set([408, 429, 502, 503, 504]);
+const NUMERIC_GRPC_CODES = new Map<number, string>([
+  [0, 'ok'],
+  [1, 'cancelled'],
+  [2, 'unknown'],
+  [3, 'invalidargument'],
+  [4, 'deadlineexceeded'],
+  [5, 'notfound'],
+  [6, 'alreadyexists'],
+  [7, 'permissiondenied'],
+  [8, 'resourceexhausted'],
+  [9, 'failedprecondition'],
+  [10, 'aborted'],
+  [11, 'outofrange'],
+  [12, 'unimplemented'],
+  [13, 'internal'],
+  [14, 'unavailable'],
+  [15, 'dataloss'],
+  [16, 'unauthenticated'],
+]);
+
+const GRPC_MESSAGE_TOKENS: ReadonlyArray<{ token: string; evidence: StructuredEvidence }> = [
+  ...[...TRANSIENT_GRPC].map((code) => ({ token: `grpccode${code}`, evidence: 'transient' as const })),
+  ...[...PERMANENT_GRPC].map((code) => ({ token: `grpccode${code}`, evidence: 'permanent' as const })),
+];
+
+function normalizeCode(value: unknown): string | undefined {
+  if (typeof value === 'number') {
+    return NUMERIC_GRPC_CODES.get(value);
+  }
+  return typeof value === 'string' ? value.replaceAll(/[\s_-]/g, '').toLowerCase() : undefined;
+}
+
+function grpcEvidence(value: unknown): StructuredEvidence | undefined {
+  const code = normalizeCode(value);
+  if (code === undefined) {
+    return undefined;
+  }
+  if (TRANSIENT_GRPC.has(code)) {
+    return 'transient';
+  }
+  if (PERMANENT_GRPC.has(code)) {
+    return 'permanent';
+  }
+  if (code === 'unknown' || code === 'ok') {
+    return 'indeterminate';
+  }
+  return undefined;
+}
+
+function httpEvidence(value: unknown): StructuredEvidence | undefined {
+  if (typeof value !== 'number' || !Number.isInteger(value) || value < 400 || value > 599) {
+    return undefined;
+  }
+  return TRANSIENT_HTTP.has(value) ? 'transient' : 'permanent';
+}
+
+function httpMessageEvidence(message: string): StructuredEvidence | undefined {
+  let hasTransient = false;
+  for (const match of message.matchAll(
+    /(?:\bhttp(?:\s+status)?|\bstatus)(?:\s+code)?\s*:?\s*(\d{3})\b/g,
+  )) {
+    const evidence = httpEvidence(Number(match[1]));
+    if (evidence === 'permanent') {
+      return 'permanent';
+    }
+    hasTransient ||= evidence === 'transient';
+  }
+  return hasTransient ? 'transient' : undefined;
+}
+
+function grpcMessageEvidence(message: string): StructuredEvidence | undefined {
+  const normalized = message.replaceAll(/[^a-z0-9]/g, '');
+  let hasTransient = false;
+  for (const { token, evidence } of GRPC_MESSAGE_TOKENS) {
+    if (normalized.includes(token)) {
+      if (evidence === 'permanent') {
+        return 'permanent';
+      }
+      hasTransient ||= evidence === 'transient';
+    }
+  }
+  return hasTransient ? 'transient' : undefined;
+}
+
+/**
+ * Last-resort transient wording, consulted only when the whole chain carried
+ * no status-level evidence. Guarded by the negative classification fixtures
+ * (server rejections must never match) — extend with care.
+ */
+function flattenedTransient(message: string): boolean {
+  return [
+    'cancelled',
+    'canceled',
+    'deadline exceeded',
+    'timeout',
+    'unavailable',
+    'resource exhausted',
+    'request timeout',
+    'too many requests',
+    'rate limited',
+    'rate limit',
+    'bad gateway',
+    'service unavailable',
+    'gateway timeout',
+    'i/o timeout',
+    'io timeout',
+    'connection reset',
+    'broken pipe',
+  ].some((signal) => message.includes(signal));
+}
+
+function asRecord(value: unknown): ErrorRecord | undefined {
+  return typeof value === 'object' && value !== null ? value as ErrorRecord : undefined;
+}
+
+/**
+ * Walks the error's cause chain and reports whether every piece of evidence
+ * points at a transient failure. `extraTransientSignals` extends the
+ * transient-wording fallback for one policy without leaking into others,
+ * under the same permanent-wins rule.
+ */
+export function isTransientError(
+  error: unknown,
+  extraTransientSignals: readonly string[] = [],
+): boolean {
+  const seen = new Set<object>();
+  const messages: string[] = [];
+  let hasTransient = false;
+  let hasPermanent = false;
+  let current: unknown = error;
+
+  const recordMessage = (message: string): void => {
+    messages.push(message);
+    for (const evidence of [httpMessageEvidence(message), grpcMessageEvidence(message)]) {
+      hasTransient ||= evidence === 'transient';
+      hasPermanent ||= evidence === 'permanent';
+    }
+  };
+
+  while (current !== undefined && current !== null) {
+    const record = asRecord(current);
+    if (record !== undefined) {
+      if (seen.has(record)) {
+        break;
+      }
+      seen.add(record);
+      for (const evidence of [
+        grpcEvidence(record.code),
+        httpEvidence(record.status),
+        httpEvidence(record.statusCode),
+      ]) {
+        hasTransient ||= evidence === 'transient';
+        hasPermanent ||= evidence === 'permanent';
+      }
+      recordMessage(
+        typeof record.message === 'string'
+          ? record.message.toLowerCase()
+          : String(current).toLowerCase(),
+      );
+      current = record.cause;
+    } else {
+      recordMessage(String(current).toLowerCase());
+      break;
+    }
+  }
+
+  if (hasPermanent) {
+    return false;
+  }
+  if (hasTransient) {
+    return true;
+  }
+  return messages.some(
+    (message) =>
+      flattenedTransient(message) ||
+      extraTransientSignals.some((signal) => message.includes(signal)),
+  );
+}

package/src/retry/runtime.ts

@@ -0,0 +1,45 @@
+const BASE_DELAY_MS = 500;
+const MAX_DELAY_MS = 8_000;
+
+export interface RetryRuntime {
+  sleep(delayMs: number): Promise<void>;
+  unitRandom(): number;
+}
+
+export const productionRetryRuntime: RetryRuntime = {
+  sleep: (delayMs) => new Promise((resolve) => setTimeout(resolve, delayMs)),
+  unitRandom: () => Math.random(),
+};
+
+export function retryDelay(retryIndex: number, unitRandom: number): number {
+  const exponent = Math.min(retryIndex, 1023);
+  const raw = BASE_DELAY_MS * 2 ** exponent;
+  const finiteRandom = Number.isFinite(unitRandom) ? unitRandom : 0.5;
+  const boundedRandom = Math.min(Math.max(finiteRandom, 0), 1 - Number.EPSILON);
+  return Math.min(Math.floor(raw * (0.75 + boundedRandom * 0.5)), MAX_DELAY_MS);
+}
+
+/**
+ * Runs `operation` under an attempt budget: the budget is consulted before
+ * the error is classified, transient failures back off with `retryDelay`,
+ * and permanent failures or the final attempt rethrow the error unchanged.
+ */
+export async function retryTransient<T>(
+  operation: () => Promise<T>,
+  maxAttempts: number,
+  isTransient: (error: unknown) => boolean,
+  runtime: RetryRuntime,
+): Promise<T> {
+  for (let attempt = 0; attempt < maxAttempts; attempt += 1) {
+    try {
+      return await operation();
+    } catch (error) {
+      if (attempt + 1 >= maxAttempts || !isTransient(error)) {
+        throw error;
+      }
+      await runtime.sleep(retryDelay(attempt, runtime.unitRandom()));
+    }
+  }
+
+  throw new Error('unreachable retry state');
+}

package/src/rpc/config.test.ts

@@ -0,0 +1,45 @@
+import { readFileSync } from 'node:fs';
+import { describe, expect, it } from 'vitest';
+import { resolveRpcConfig } from './config.js';
+
+interface Fixtures {
+  attemptBudgets: Array<{ input: number | null; normalized: number }>;
+}
+
+function fixtures(): Fixtures {
+  return JSON.parse(
+    readFileSync(
+      new URL(
+        '../../../../fixtures/miden-multisig-client/rpc-policy-fixtures.json',
+        import.meta.url,
+      ),
+      'utf8',
+    ),
+  ) as Fixtures;
+}
+
+describe('resolveRpcConfig', () => {
+  it('matches shared attempt-budget vectors', () => {
+    for (const fixture of fixtures().attemptBudgets) {
+      const retry = fixture.input === null ? undefined : { maxAttempts: fixture.input };
+      expect(resolveRpcConfig({ retry }).maxAttempts).toBe(fixture.normalized);
+    }
+  });
+
+  it('defaults to one retry when no config is given', () => {
+    expect(resolveRpcConfig(undefined).maxAttempts).toBe(2);
+  });
+
+  it('treats an explicit single attempt as a full opt-out', () => {
+    expect(resolveRpcConfig({ retry: { maxAttempts: 1 } }).maxAttempts).toBe(1);
+  });
+
+  it.each([-1, 1.5, Number.NaN, Number.POSITIVE_INFINITY, 4_294_967_296])(
+    'rejects invalid maxAttempts value %s',
+    (maxAttempts) => {
+      expect(() => resolveRpcConfig({ retry: { maxAttempts } })).toThrow(
+        'rpc.retry.maxAttempts',
+      );
+    },
+  );
+});

package/src/rpc/config.ts

@@ -0,0 +1,30 @@
+export interface RpcRetryPolicy {
+  maxAttempts?: number;
+}
+
+export interface RpcConfig {
+  retry?: RpcRetryPolicy;
+}
+
+export interface ResolvedRpcConfig {
+  readonly maxAttempts: number;
+}
+
+const DEFAULT_MAX_ATTEMPTS = 2;
+const MAX_U32 = 4_294_967_295;
+
+function normalizeMaxAttempts(value: number | undefined): number {
+  if (value === undefined) {
+    return DEFAULT_MAX_ATTEMPTS;
+  }
+  if (!Number.isFinite(value) || !Number.isInteger(value) || value < 0 || value > MAX_U32) {
+    throw new Error('rpc.retry.maxAttempts must be an integer between 0 and 4294967295');
+  }
+  return Math.max(1, value);
+}
+
+export function resolveRpcConfig(config: RpcConfig | undefined): ResolvedRpcConfig {
+  return {
+    maxAttempts: normalizeMaxAttempts(config?.retry?.maxAttempts),
+  };
+}