@openzeppelin/miden-multisig-client 0.15.2 → 0.16.1

package/src/prover/config.test.ts

@@ -0,0 +1,90 @@
+import { readFileSync } from 'node:fs';
+import type { TransactionProver } from '@miden-sdk/miden-sdk';
+import { describe, expect, it } from 'vitest';
+import { resolveProverConfig } from './config.js';
+
+interface Fixtures {
+  attemptBudgets: Array<{ input: number | null; normalized: number }>;
+  endpoints: Array<{
+    input: string;
+    valid: boolean;
+    canonical?: string;
+  }>;
+}
+
+function fixtures(): Fixtures {
+  return JSON.parse(
+    readFileSync(
+      new URL(
+        '../../../../fixtures/miden-multisig-client/prover-policy-fixtures.json',
+        import.meta.url,
+      ),
+      'utf8',
+    ),
+  ) as Fixtures;
+}
+
+describe('resolveProverConfig', () => {
+  it('matches shared URL vectors', () => {
+    for (const fixture of fixtures().endpoints) {
+      const resolve = () => resolveProverConfig({ url: fixture.input }, null);
+      if (fixture.valid) {
+        expect(resolve().url, fixture.input).toBe(fixture.canonical);
+      } else {
+        expect(resolve, fixture.input).toThrow();
+      }
+    }
+  });
+
+  it('matches shared attempt-budget vectors for remote proving', () => {
+    for (const fixture of fixtures().attemptBudgets) {
+      const retry = fixture.input === null ? undefined : { maxAttempts: fixture.input };
+      const resolved = resolveProverConfig(
+        { url: 'https://prover.example', retry },
+        null,
+      );
+      expect(resolved.maxAttempts).toBe(fixture.normalized);
+    }
+  });
+
+  it.each([-1, 1.5, Number.NaN, Number.POSITIVE_INFINITY, 4_294_967_296])(
+    'rejects invalid maxAttempts value %s',
+    (maxAttempts) => {
+      expect(() =>
+        resolveProverConfig(
+          { url: 'https://prover.example', retry: { maxAttempts } },
+          null,
+        ),
+      ).toThrow('prover.retry.maxAttempts');
+    },
+  );
+
+  it('keeps an endpoint-less injected prover at one attempt without serializing it', () => {
+    const serialize = () => {
+      throw new Error('callback provers cannot be serialized');
+    };
+    const callback = {
+      endpoint: () => undefined,
+      serialize,
+    } as unknown as TransactionProver;
+
+    expect(resolveProverConfig({ retry: { maxAttempts: 5 } }, callback)).toMatchObject({
+      kind: 'injected',
+      maxAttempts: 1,
+    });
+  });
+
+  it('lets a custom remote URL override an injected local prover', () => {
+    const local = {
+      serialize: () => 'local',
+      endpoint: () => undefined,
+    } as unknown as TransactionProver;
+    expect(
+      resolveProverConfig({ url: 'https://prover.example' }, local),
+    ).toMatchObject({
+      kind: 'remote',
+      url: 'https://prover.example/',
+      maxAttempts: 2,
+    });
+  });
+});

package/src/prover/config.ts

@@ -0,0 +1,78 @@
+import { TransactionProver } from '@miden-sdk/miden-sdk';
+
+export interface ProverRetryPolicy {
+  maxAttempts?: number;
+}
+
+export interface ProverConfig {
+  url?: string;
+  retry?: ProverRetryPolicy;
+}
+
+export interface ResolvedProverConfig {
+  readonly kind: 'injected' | 'remote';
+  readonly url?: string;
+  readonly maxAttempts: number;
+  createProver(): TransactionProver | undefined;
+}
+
+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('prover.retry.maxAttempts must be an integer between 0 and 4294967295');
+  }
+  return Math.max(1, value);
+}
+
+function normalizeUrl(value: string): string {
+  const trimmed = value.trim();
+  let parsed: URL;
+  try {
+    parsed = new URL(trimmed);
+  } catch {
+    throw new Error('prover.url must be an absolute HTTP(S) URL with a host');
+  }
+  if (!['http:', 'https:'].includes(parsed.protocol) || parsed.hostname === '') {
+    throw new Error('prover.url must be an absolute HTTP(S) URL with a host');
+  }
+  return parsed.href;
+}
+
+export function resolveProverConfig(
+  config: ProverConfig | undefined,
+  defaultProver: TransactionProver | null,
+): ResolvedProverConfig {
+  const maxAttempts = normalizeMaxAttempts(config?.retry?.maxAttempts);
+
+  if (config?.url !== undefined) {
+    const url = normalizeUrl(config.url);
+    return {
+      kind: 'remote',
+      url,
+      maxAttempts,
+      createProver: () => TransactionProver.newRemoteProver(url),
+    };
+  }
+
+  const endpoint = defaultProver?.endpoint();
+  if (defaultProver === null || endpoint === undefined) {
+    return {
+      kind: 'injected',
+      maxAttempts: 1,
+      createProver: () => undefined,
+    };
+  }
+
+  const descriptor = defaultProver.serialize();
+  return {
+    kind: 'remote',
+    url: endpoint,
+    maxAttempts,
+    createProver: () => TransactionProver.deserialize(descriptor),
+  };
+}

package/src/prover/errors.test.ts

@@ -0,0 +1,53 @@
+import { readFileSync } from 'node:fs';
+import { describe, expect, it } from 'vitest';
+import { isTransientProverError } from './errors.js';
+
+interface FixtureError {
+  code?: string;
+  status?: number;
+  message: string;
+  cause?: FixtureError;
+}
+
+interface Fixtures {
+  classifications: Array<{
+    name: string;
+    chain: FixtureError[];
+    transient: boolean;
+  }>;
+}
+
+function fixtures(): Fixtures {
+  return JSON.parse(
+    readFileSync(
+      new URL(
+        '../../../../fixtures/miden-multisig-client/prover-policy-fixtures.json',
+        import.meta.url,
+      ),
+      'utf8',
+    ),
+  ) as Fixtures;
+}
+
+describe('isTransientProverError', () => {
+  it('matches every shared classification vector', () => {
+    for (const fixture of fixtures().classifications) {
+      const error = fixture.chain.reduceRight<FixtureError | undefined>(
+        (cause, item) => ({ ...item, cause }),
+        undefined,
+      );
+      expect(isTransientProverError(error), fixture.name).toBe(fixture.transient);
+    }
+  });
+
+  it('stops safely on cyclic cause graphs', () => {
+    const error: FixtureError = { code: 'Unknown', message: 'not retryable' };
+    error.cause = error;
+    expect(isTransientProverError(error)).toBe(false);
+  });
+
+  it('recognizes numeric gRPC status codes', () => {
+    expect(isTransientProverError({ code: 14, message: 'unavailable' })).toBe(true);
+    expect(isTransientProverError({ code: 3, message: 'timeout text' })).toBe(false);
+  });
+});

package/src/prover/errors.ts

@@ -0,0 +1,178 @@
+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;
+}
+
+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);
+}

package/src/prover/retry.test.ts

@@ -0,0 +1,38 @@
+import { readFileSync } from 'node:fs';
+import { describe, expect, it } from 'vitest';
+import { retryDelay } from './retry.js';
+
+interface Fixtures {
+  delays: Array<{ retryIndex: number; unitRandom: number; delayMs: number }>;
+}
+
+function fixtures(): Fixtures {
+  return JSON.parse(
+    readFileSync(
+      new URL(
+        '../../../../fixtures/miden-multisig-client/prover-policy-fixtures.json',
+        import.meta.url,
+      ),
+      'utf8',
+    ),
+  ) as Fixtures;
+}
+
+describe('retryDelay', () => {
+  it('matches every shared delay vector', () => {
+    for (const fixture of fixtures().delays) {
+      expect(retryDelay(fixture.retryIndex, fixture.unitRandom)).toBe(fixture.delayMs);
+    }
+  });
+
+  it('remains capped after numeric overflow', () => {
+    expect(retryDelay(Number.MAX_SAFE_INTEGER, 0.5)).toBe(8_000);
+  });
+
+  it.each([Number.NaN, Number.POSITIVE_INFINITY, Number.NEGATIVE_INFINITY])(
+    'uses neutral jitter for non-finite randomness',
+    (unitRandom) => {
+      expect(retryDelay(0, unitRandom)).toBe(500);
+    },
+  );
+});

package/src/prover/retry.ts

@@ -0,0 +1,46 @@
+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);
+}
+
+export async function proveWithRetry(
+  execution: TransactionExecution,
+  config: ResolvedProverConfig,
+  runtime: RetryRuntime = productionRetryRuntime,
+): Promise<TransactionProof> {
+  for (let attempt = 0; attempt < config.maxAttempts; attempt += 1) {
+    try {
+      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');
+}

package/src/prover/test-node.d.ts

@@ -0,0 +1,6 @@
+declare module 'node:fs' {
+  export function readFileSync(
+    path: URL,
+    encoding: 'utf8',
+  ): string;
+}

package/src/prover/workflow.test.ts

@@ -0,0 +1,109 @@
+import type {
+  AccountId,
+  MidenClient,
+  TransactionProver,
+  TransactionRequest,
+} 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 { ProverWorkflow } from './workflow.js';
+
+function asType<T>(value: unknown): T {
+  return value as T;
+}
+
+describe('ProverWorkflow', () => {
+  it('executes once, retries proof with fresh provers, submits once, and applies once', async () => {
+    const transient = Object.assign(new Error('temporarily unavailable'), {
+      code: 'Unavailable',
+    });
+    const apply = vi.fn().mockResolvedValue({});
+    const submit = vi.fn().mockResolvedValue({ apply });
+    const prove = vi.fn().mockRejectedValueOnce(transient).mockResolvedValueOnce({ submit });
+    const execution = { marker: 'unchanged', prove };
+    const executeRequest = vi.fn().mockResolvedValue(execution);
+    const client = {
+      transactions: { executeRequest },
+    };
+    const provers: TransactionProver[] = [];
+    const config: ResolvedProverConfig = {
+      kind: 'remote',
+      url: 'https://prover.example/',
+      maxAttempts: 2,
+      createProver: () => {
+        const prover = asType<TransactionProver>({});
+        provers.push(prover);
+        return prover;
+      },
+    };
+    const runtime: RetryRuntime = {
+      sleep: vi.fn().mockResolvedValue(undefined),
+      unitRandom: () => 0.5,
+    };
+    const workflow = new ProverWorkflow(
+      asType<MidenClient>(client),
+      config,
+      runtime,
+    );
+
+    await workflow.submit(
+      asType<AccountId>({}),
+      asType<TransactionRequest>({}),
+    );
+
+    expect(executeRequest).toHaveBeenCalledTimes(1);
+    expect(prove).toHaveBeenCalledTimes(2);
+    expect(provers).toHaveLength(2);
+    expect(provers[0]).not.toBe(provers[1]);
+    expect(submit).toHaveBeenCalledTimes(1);
+    expect(apply).toHaveBeenCalledTimes(1);
+    expect(runtime.sleep).toHaveBeenCalledTimes(1);
+  });
+
+  it('returns the final original error without sleeping after exhaustion', async () => {
+    const first = Object.assign(new Error('unavailable'), { code: 'Unavailable' });
+    const final = Object.assign(new Error('deadline exceeded'), {
+      code: 'DeadlineExceeded',
+    });
+    const prove = vi.fn().mockRejectedValueOnce(first).mockRejectedValueOnce(final);
+    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: 2,
+        createProver: () => asType<TransactionProver>({}),
+      },
+      runtime,
+    );
+
+    await expect(
+      workflow.submit(asType<AccountId>({}), asType<TransactionRequest>({})),
+    ).rejects.toBe(final);
+    expect(prove).toHaveBeenCalledTimes(2);
+    expect(runtime.sleep).toHaveBeenCalledTimes(1);
+  });
+
+  it('uses the injected prover directly when no cloneable remote override exists', async () => {
+    const apply = vi.fn().mockResolvedValue({});
+    const submit = vi.fn().mockResolvedValue({ apply });
+    const prove = vi.fn().mockResolvedValue({ submit });
+    const client = {
+      transactions: { executeRequest: vi.fn().mockResolvedValue({ prove }) },
+    };
+    const workflow = new ProverWorkflow(asType<MidenClient>(client), {
+      kind: 'injected',
+      maxAttempts: 1,
+      createProver: () => undefined,
+    });
+
+    await workflow.submit(asType<AccountId>({}), asType<TransactionRequest>({}));
+
+    expect(prove).toHaveBeenCalledWith();
+  });
+});

package/src/prover/workflow.ts

@@ -0,0 +1,19 @@
+import type { AccountId, MidenClient, TransactionRequest } from '@miden-sdk/miden-sdk';
+import type { ResolvedProverConfig } from './config.js';
+import type { RetryRuntime } from './retry.js';
+import { proveWithRetry } from './retry.js';
+
+export class ProverWorkflow {
+  constructor(
+    private readonly client: MidenClient,
+    private readonly config: ResolvedProverConfig,
+    private readonly runtime?: RetryRuntime,
+  ) {}
+
+  async submit(accountId: AccountId, request: TransactionRequest): Promise<void> {
+    const execution = await this.client.transactions.executeRequest(accountId, request);
+    const proof = await proveWithRetry(execution, this.config, this.runtime);
+    const submission = await proof.submit();
+    await submission.apply();
+  }
+}

package/src/raw-client.test.ts

@@ -14,7 +14,7 @@ import {
   compileTxScript,
   getRawMidenClient,
   getTransactionProver,
-  resolveMidenRpcEndpoint,
+  requireConfigValue,
 } from './raw-client.js';
 
 describe('raw-client', () => {
@@ -22,8 +22,46 @@ describe('raw-client', () => {
     mockCreateClient.mockReset();
   });
 
-  it('defaults RPC endpoint resolution to devnet', () => {
-    expect(resolveMidenRpcEndpoint()).toBe('https://rpc.devnet.miden.io');
+  it.each([undefined, null, 42, {}, []])(
+    'rejects non-string configuration value %j consistently',
+    (value) => {
+      expect(() => requireConfigValue('guardianEndpoint', value)).toThrow(
+        'missing required configuration: guardianEndpoint',
+      );
+    },
+  );
+
+  it('trims surrounding whitespace from configuration values', () => {
+    expect(requireConfigValue('guardianEndpoint', '  http://localhost:3000\n')).toBe(
+      'http://localhost:3000',
+    );
+  });
+
+  it('rejects shadow client creation without an RPC endpoint', async () => {
+    const client = {
+      accounts: {},
+      sync: vi.fn(),
+      defaultProver: null,
+      storeIdentifier: vi.fn(() => 'browser-db'),
+    };
+
+    await expect(getRawMidenClient(client as any)).rejects.toThrow(
+      'missing required configuration: midenRpcEndpoint',
+    );
+    await expect(getRawMidenClient(client as any, '   ')).rejects.toThrow(
+      'missing required configuration: midenRpcEndpoint',
+    );
+    expect(mockCreateClient).not.toHaveBeenCalled();
+  });
+
+  it('returns an injected raw web client without needing an endpoint', async () => {
+    const rawClient = {
+      executeTransaction: vi.fn(),
+      proveTransaction: vi.fn(),
+    };
+
+    await expect(getRawMidenClient(rawClient as any)).resolves.toBe(rawClient);
+    expect(mockCreateClient).not.toHaveBeenCalled();
   });
 
   it('returns the default prover from a public MidenClient', () => {