@openzeppelin/miden-multisig-client 0.16.1 → 0.17.0-rc.1

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),
+  };
+}

package/src/rpc/errors.test.ts

@@ -0,0 +1,69 @@
+import { readFileSync } from 'node:fs';
+import { describe, expect, it } from 'vitest';
+import { isTransientRpcError } 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/rpc-policy-fixtures.json',
+        import.meta.url,
+      ),
+      'utf8',
+    ),
+  ) as Fixtures;
+}
+
+describe('isTransientRpcError', () => {
+  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(isTransientRpcError(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(isTransientRpcError(error)).toBe(false);
+  });
+
+  it('recognizes numeric gRPC status codes', () => {
+    expect(isTransientRpcError({ code: 14, message: 'unavailable' })).toBe(true);
+    expect(isTransientRpcError({ code: 3, message: 'timeout text' })).toBe(false);
+  });
+
+  it('keeps permanent status evidence ahead of transport wording', () => {
+    expect(
+      isTransientRpcError({
+        code: 'FailedPrecondition',
+        message: 'transport error while checking preconditions',
+      }),
+    ).toBe(false);
+  });
+
+  it('reads grpc code wording out of plain message text', () => {
+    expect(isTransientRpcError(new Error('grpc code: InvalidArgument; request timeout'))).toBe(
+      false,
+    );
+    expect(isTransientRpcError(new Error('grpc code: Unavailable'))).toBe(true);
+  });
+});

package/src/rpc/errors.ts

@@ -0,0 +1,12 @@
+import { isTransientError } from '../retry/classify.js';
+
+/**
+ * The node's transport layer renders dropped connections with wording the
+ * prover policy deliberately rejects, so these extras apply to node-RPC
+ * classification only. Guarded by the negative classification fixtures.
+ */
+const RPC_TRANSPORT_SIGNALS = ['connection error', 'transport error'];
+
+export function isTransientRpcError(error: unknown): boolean {
+  return isTransientError(error, RPC_TRANSPORT_SIGNALS);
+}

package/src/rpc/retry.test.ts

@@ -0,0 +1,144 @@
+import { readFileSync } from 'node:fs';
+import { describe, expect, it, vi } from 'vitest';
+import { resolveRpcConfig } from './config.js';
+import { retryRpcRead } from './retry.js';
+import type { RetryRuntime } from '../retry/runtime.js';
+import { retryDelay } from '../retry/runtime.js';
+
+interface Fixtures {
+  delays: Array<{ retryIndex: number; unitRandom: number; delayMs: number }>;
+}
+
+function fixtures(): Fixtures {
+  return JSON.parse(
+    readFileSync(
+      new URL(
+        '../../../../fixtures/miden-multisig-client/rpc-policy-fixtures.json',
+        import.meta.url,
+      ),
+      'utf8',
+    ),
+  ) as Fixtures;
+}
+
+function recordingRuntime(): RetryRuntime & { sleeps: number[] } {
+  const sleeps: number[] = [];
+  return {
+    sleeps,
+    sleep: (delayMs) => {
+      sleeps.push(delayMs);
+      return Promise.resolve();
+    },
+    unitRandom: () => 0.5,
+  };
+}
+
+function rateLimitError(): Error {
+  return Object.assign(new Error('Too Many Requests!'), {
+    code: 'ResourceExhausted',
+  });
+}
+
+describe('retryRpcRead', () => {
+  it('matches every shared delay vector', () => {
+    for (const fixture of fixtures().delays) {
+      expect(retryDelay(fixture.retryIndex, fixture.unitRandom)).toBe(fixture.delayMs);
+    }
+  });
+
+  it('waits out rate limiting and returns the eventual result', async () => {
+    const runtime = recordingRuntime();
+    const operation = vi
+      .fn()
+      .mockRejectedValueOnce(rateLimitError())
+      .mockRejectedValueOnce(rateLimitError())
+      .mockResolvedValueOnce('synced');
+
+    const result = await retryRpcRead(
+      operation,
+      resolveRpcConfig({ retry: { maxAttempts: 3 } }),
+      runtime,
+    );
+
+    expect(result).toBe('synced');
+    expect(operation).toHaveBeenCalledTimes(3);
+    expect(runtime.sleeps).toEqual([retryDelay(0, 0.5), retryDelay(1, 0.5)]);
+  });
+
+  it('throws a permanent error immediately without sleeping', async () => {
+    const runtime = recordingRuntime();
+    const permanent = Object.assign(new Error('malformed account id'), {
+      code: 'InvalidArgument',
+    });
+    const operation = vi.fn().mockRejectedValue(permanent);
+
+    await expect(
+      retryRpcRead(operation, resolveRpcConfig({ retry: { maxAttempts: 5 } }), runtime),
+    ).rejects.toBe(permanent);
+    expect(operation).toHaveBeenCalledTimes(1);
+    expect(runtime.sleeps).toEqual([]);
+  });
+
+  it('rethrows the final upstream error unchanged after budget exhaustion', async () => {
+    const runtime = recordingRuntime();
+    const final = Object.assign(new Error('still rate limited'), {
+      code: 'ResourceExhausted',
+    });
+    const operation = vi
+      .fn()
+      .mockRejectedValueOnce(rateLimitError())
+      .mockRejectedValueOnce(final);
+
+    await expect(
+      retryRpcRead(operation, resolveRpcConfig({ retry: { maxAttempts: 2 } }), runtime),
+    ).rejects.toBe(final);
+    expect(operation).toHaveBeenCalledTimes(2);
+    expect(runtime.sleeps).toHaveLength(1);
+  });
+
+  it('retries a transient read once under the default config', async () => {
+    const runtime = recordingRuntime();
+    const operation = vi
+      .fn()
+      .mockRejectedValueOnce(rateLimitError())
+      .mockResolvedValueOnce('synced');
+
+    await expect(retryRpcRead(operation, resolveRpcConfig(undefined), runtime)).resolves.toBe(
+      'synced',
+    );
+    expect(operation).toHaveBeenCalledTimes(2);
+    expect(runtime.sleeps).toHaveLength(1);
+  });
+
+  it('never retries under an explicit single-attempt config', async () => {
+    const runtime = recordingRuntime();
+    const operation = vi.fn().mockRejectedValue(rateLimitError());
+
+    await expect(
+      retryRpcRead(operation, resolveRpcConfig({ retry: { maxAttempts: 1 } }), runtime),
+    ).rejects.toThrow('Too Many Requests!');
+    expect(operation).toHaveBeenCalledTimes(1);
+    expect(runtime.sleeps).toEqual([]);
+  });
+
+  it('completes 64 concurrent reads against a rate-limited node', async () => {
+    const runtime = recordingRuntime();
+    let rejected = 0;
+    const operation = () => {
+      if (rejected < 40) {
+        rejected += 1;
+        return Promise.reject(rateLimitError());
+      }
+      return Promise.resolve('synced');
+    };
+
+    const results = await Promise.all(
+      Array.from({ length: 64 }, () =>
+        retryRpcRead(operation, resolveRpcConfig({ retry: { maxAttempts: 4 } }), runtime),
+      ),
+    );
+
+    expect(results).toEqual(Array.from({ length: 64 }, () => 'synced'));
+    expect(rejected).toBe(40);
+  });
+});

package/src/rpc/retry.ts

@@ -0,0 +1,12 @@
+import type { ResolvedRpcConfig } from './config.js';
+import { isTransientRpcError } from './errors.js';
+import type { RetryRuntime } from '../retry/runtime.js';
+import { productionRetryRuntime, retryTransient } from '../retry/runtime.js';
+
+export async function retryRpcRead<T>(
+  operation: () => Promise<T>,
+  config: ResolvedRpcConfig,
+  runtime: RetryRuntime = productionRetryRuntime,
+): Promise<T> {
+  return retryTransient(operation, config.maxAttempts, isTransientRpcError, runtime);
+}

package/src/transaction/index.ts

@@ -1,4 +1,10 @@
-export { executeForSummary } from './summary.js';
+export {
+  chainAnchorFromBase64,
+  chainAnchorToBase64,
+  executeForSummary,
+  executeForSummaryAt,
+  summarySalt,
+} from './summary.js';
 export { buildUpdateSignersTransactionRequest } from './updateSigners.js';
 export { buildUpdateProcedureThresholdTransactionRequest } from './updateProcedureThreshold.js';
 export { buildUpdateGuardianTransactionRequest } from './updateGuardian.js';