@openzeppelin/guardian-client 0.18.2 → 0.19.0-rc.1

package/src/error-codes.ts

@@ -2,10 +2,8 @@
  * Typed vocabulary of Guardian's stable, machine-readable error codes
  * (issue #318). Mirrors `GuardianError::code()` in
  * `crates/server/src/error.rs` — a drift-guard test asserts the two stay in
- * sync. The four codes the server emits in SCREAMING_SNAKE wire form
- * (`GUARDIAN_ACCOUNT_PAUSED`, `GUARDIAN_ACCOUNT_RELEASED`,
- * `GUARDIAN_INSUFFICIENT_OPERATOR_PERMISSION`, `GUARDIAN_CANDIDATE_LANDED`)
- * are normalized to snake_case here so the union has one consistent shape; use
+ * sync. The codes the server emits in SCREAMING_SNAKE wire form (see
+ * `WIRE_ALIASES`) are normalized to snake_case here so the union has one consistent shape; use
  * {@link normalizeGuardianErrorCode} at the wire boundary.
  */
 export const GUARDIAN_ERROR_CODES = [
@@ -14,6 +12,7 @@ export const GUARDIAN_ERROR_CODES = [
   'account_not_found',
   'account_paused',
   'account_released',
+  'account_request_capacity_exceeded',
   'authentication_failed',
   'authentication_replay',
   'authorization_failed',
@@ -24,6 +23,9 @@ export const GUARDIAN_ERROR_CODES = [
   'conflict_pending_proposal',
   'data_unavailable',
   'delta_not_found',
+  'execution_busy',
+  'execution_conflict',
+  'execution_not_found',
   'insufficient_operator_permission',
   'insufficient_signatures',
   'invalid_account_id',
@@ -40,7 +42,12 @@ export const GUARDIAN_ERROR_CODES = [
   'network_error',
   'pending_proposals_limit',
   'proposal_already_signed',
+  'proposal_executes_locally',
+  'proposal_missing_transaction_request',
   'proposal_not_found',
+  'proposal_not_ready',
+  'proposal_request_too_large',
+  'proving_unavailable',
   'rate_limit_exceeded',
   'rpc_unavailable',
   'rpc_validation_failed',
@@ -50,6 +57,7 @@ export const GUARDIAN_ERROR_CODES = [
   'signer_not_authorized',
   'signing_error',
   'state_not_found',
+  'state_not_on_chain',
   'storage_error',
   'unsupported_evm_chain',
   'unsupported_for_network',
@@ -75,6 +83,15 @@ const WIRE_ALIASES: Readonly<Record<string, GuardianErrorCode>> = {
   GUARDIAN_ACCOUNT_RELEASED: 'account_released',
   GUARDIAN_INSUFFICIENT_OPERATOR_PERMISSION: 'insufficient_operator_permission',
   GUARDIAN_CANDIDATE_LANDED: 'candidate_landed',
+  GUARDIAN_PROVING_UNAVAILABLE: 'proving_unavailable',
+  GUARDIAN_PROPOSAL_MISSING_TRANSACTION_REQUEST: 'proposal_missing_transaction_request',
+  GUARDIAN_PROPOSAL_EXECUTES_LOCALLY: 'proposal_executes_locally',
+  GUARDIAN_PROPOSAL_NOT_READY: 'proposal_not_ready',
+  GUARDIAN_EXECUTION_CONFLICT: 'execution_conflict',
+  GUARDIAN_EXECUTION_BUSY: 'execution_busy',
+  GUARDIAN_EXECUTION_NOT_FOUND: 'execution_not_found',
+  GUARDIAN_PROPOSAL_REQUEST_TOO_LARGE: 'proposal_request_too_large',
+  GUARDIAN_ACCOUNT_REQUEST_CAPACITY_EXCEEDED: 'account_request_capacity_exceeded',
 };
 
 /** Type guard narrowing an arbitrary string to {@link GuardianErrorCode}. */

package/src/execution.test.ts

@@ -0,0 +1,145 @@
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { describe, it, expect } from 'vitest';
+import {
+  EXECUTION_FAILURE_CODES,
+  EXECUTION_STATES,
+  EXECUTION_UNAVAILABLE_REASONS,
+  EXPIRATION_BOUNDS,
+  FOREIGN_ACCOUNT_UNAVAILABLE_REASONS,
+  REQUEST_INVALID_REASONS,
+  fromServerExecution,
+  fromServerExecutionCapability,
+  isTerminalExecutionState,
+  type ServerProposalExecution,
+} from './execution.js';
+
+const executionRs = readFileSync(
+  join(dirname(fileURLToPath(import.meta.url)), '../../../crates/shared/src/execution.rs'),
+  'utf8'
+);
+
+function snake(variant: string): string {
+  return variant.replace(/([a-z0-9])([A-Z])/g, '$1_$2').toLowerCase();
+}
+
+function rustVariants(enumName: string): string[] {
+  const start = executionRs.indexOf(`pub enum ${enumName} {`);
+  expect(start, `${enumName} is defined in guardian-shared`).toBeGreaterThan(-1);
+  const body = executionRs.slice(start, executionRs.indexOf('}', start));
+  return [...body.matchAll(/^\s+([A-Z][A-Za-z]+)[,(]/gm)].map((m) => m[1]);
+}
+
+function envelope(overrides: Partial<ServerProposalExecution>): ServerProposalExecution {
+  return {
+    account_id: '0xacc',
+    proposal_id: '0xprop',
+    state: 'pending',
+    newly_accepted: false,
+    proposal_exists: true,
+    ignored_signatures: 0,
+    updated_at: '2026-09-30T12:00:00Z',
+    ...overrides,
+  };
+}
+
+describe('drift guard against guardian_shared::execution', () => {
+  it('the states and meta value sets match the Rust enums', () => {
+    expect([...EXECUTION_STATES]).toEqual(rustVariants('ExecutionState').map(snake));
+    expect([...REQUEST_INVALID_REASONS]).toEqual(rustVariants('RequestInvalidReason').map(snake));
+    expect([...EXPIRATION_BOUNDS]).toEqual(rustVariants('ExpirationBound').map(snake));
+    expect([...FOREIGN_ACCOUNT_UNAVAILABLE_REASONS]).toEqual(
+      rustVariants('ForeignAccountUnavailableReason').map(snake)
+    );
+  });
+
+  it('the execution-unavailable reasons match the server enum', () => {
+    const configRs = readFileSync(
+      join(dirname(fileURLToPath(import.meta.url)), '../../../crates/server/src/config/execution.rs'),
+      'utf8'
+    );
+    const body = configRs.slice(configRs.indexOf('pub enum ExecutionUnavailable {'));
+    const variants = [...body.slice(0, body.indexOf('\n}')).matchAll(/^\s{4}([A-Z][A-Za-z]+),$/gm)].map((m) => m[1]);
+    expect([...EXECUTION_UNAVAILABLE_REASONS]).toEqual(variants.map(snake));
+  });
+
+  it('the failure codes match ExecutionFailureCode::as_str', () => {
+    const start = executionRs.indexOf('pub fn as_str(&self) -> &\'static str {', executionRs.indexOf('impl ExecutionFailureCode'));
+    const body = executionRs.slice(start, executionRs.indexOf('pub fn meta', start));
+    const rustCodes = [...body.matchAll(/"(GUARDIAN_EXECUTION_[A-Z_]+)"/g)].map((m) => m[1]);
+    expect([...EXECUTION_FAILURE_CODES].sort()).toEqual(rustCodes.sort());
+  });
+
+  it('never carries the codes the design withdrew', () => {
+    for (const withdrawn of ['ANCHOR_EXPIRED', 'NO_FINITE_EXPIRATION', 'FOREIGN_INPUTS_UNSUPPORTED']) {
+      expect(EXECUTION_FAILURE_CODES.some((code) => code.endsWith(withdrawn))).toBe(false);
+    }
+  });
+});
+
+describe('fromServerExecution', () => {
+  it('decodes a failure with its typed meta', () => {
+    const execution = fromServerExecution(
+      envelope({
+        state: 'failed',
+        proposal_exists: false,
+        error: {
+          code: 'GUARDIAN_EXECUTION_EXPIRATION_REACHED',
+          message: 'expired',
+          meta: { bound: 'transaction' },
+        },
+      })
+    );
+    expect(execution.error).toEqual({
+      code: 'GUARDIAN_EXECUTION_EXPIRATION_REACHED',
+      message: 'expired',
+      bound: 'transaction',
+    });
+    expect(execution.proposalExists).toBe(false);
+  });
+
+  it('refuses an unknown state, an unknown reason and a failure without its error', () => {
+    expect(() => fromServerExecution(envelope({ state: 'queued' }))).toThrow();
+    expect(() =>
+      fromServerExecution(
+        envelope({
+          state: 'failed',
+          error: { code: 'GUARDIAN_EXECUTION_REQUEST_INVALID', message: 'x', meta: { reason: 'other' } },
+        })
+      )
+    ).toThrow();
+    expect(() => fromServerExecution(envelope({ state: 'failed' }))).toThrow();
+  });
+
+  it('maps nothing in flight and an absent nonce to null', () => {
+    expect(fromServerExecution(envelope({})).deltaNonce).toBeNull();
+    expect(fromServerExecution(envelope({ delta_nonce: 4 })).deltaNonce).toBe(4);
+  });
+});
+
+describe('isTerminalExecutionState', () => {
+  it('matches ExecutionState::is_terminal', () => {
+    expect(EXECUTION_STATES.filter(isTerminalExecutionState)).toEqual(['committed', 'failed']);
+  });
+});
+
+describe('fromServerExecutionCapability', () => {
+  it('decodes both shapes', () => {
+    expect(fromServerExecutionCapability({ enabled: true })).toEqual({ enabled: true });
+    expect(fromServerExecutionCapability({ enabled: false, reason: 'disabled' })).toEqual({
+      enabled: false,
+      reason: 'disabled',
+    });
+  });
+
+  it('refuses an unknown reason, a missing field and a reason on an enabled capability', () => {
+    expect(() => fromServerExecutionCapability({ enabled: false, reason: 'gone_fishing' })).toThrow(
+      /unknown execution unavailable reason/
+    );
+    expect(() => fromServerExecutionCapability({ enabled: false })).toThrow(/unknown execution unavailable reason/);
+    expect(() => fromServerExecutionCapability({ enabled: 'yes' })).toThrow(/boolean enabled/);
+    expect(() => fromServerExecutionCapability('yes' as never)).toThrow(/malformed execution capability/);
+    expect(() => fromServerExecutionCapability({ enabled: true, reason: 'disabled' })).toThrow(/with a reason/);
+  });
+});

package/src/execution.ts

@@ -0,0 +1,206 @@
+/**
+ * Guardian execution of threshold-met proposals, as the base client reports it. Mirrors the
+ * `guardian_shared::execution` vocabulary; drift-guard tests keep the two in step.
+ */
+
+/** The five reported states. Closed: adding one is a breaking change. */
+export const EXECUTION_STATES = ['pending', 'proving', 'submitted', 'committed', 'failed'] as const;
+export type ExecutionState = (typeof EXECUTION_STATES)[number];
+
+/** Whether the execution has finished, one way or the other. Mirrors `ExecutionState::is_terminal`. */
+export function isTerminalExecutionState(state: ExecutionState): boolean {
+  switch (state) {
+    case 'committed':
+    case 'failed':
+      return true;
+    case 'pending':
+    case 'proving':
+    case 'submitted':
+      return false;
+    default: {
+      const unreachable: never = state;
+      throw new Error(`Unknown execution state: ${String(unreachable)}`);
+    }
+  }
+}
+
+export const REQUEST_INVALID_REASONS = [
+  'bound_block_not_declared',
+  'auth_args_missing',
+  'approval_expiration_missing',
+  'input_notes_not_pinned',
+  'too_many_declared_blocks',
+] as const;
+export type RequestInvalidReason = (typeof REQUEST_INVALID_REASONS)[number];
+
+export const EXPIRATION_BOUNDS = ['approval', 'transaction'] as const;
+export type ExpirationBound = (typeof EXPIRATION_BOUNDS)[number];
+
+export const FOREIGN_ACCOUNT_UNAVAILABLE_REASONS = ['private', 'unavailable'] as const;
+export type ForeignAccountUnavailableReason = (typeof FOREIGN_ACCOUNT_UNAVAILABLE_REASONS)[number];
+
+/** Why a server does not offer Guardian execution, as `GET /status` reports it. */
+export const EXECUTION_UNAVAILABLE_REASONS = ['prover_not_configured', 'disabled', 'canonicalization_disabled'] as const;
+export type ExecutionUnavailableReason = (typeof EXECUTION_UNAVAILABLE_REASONS)[number];
+
+/**
+ * Whether the server accepts Guardian execution requests. It reflects the server's configuration,
+ * not whether its prover is reachable right now.
+ */
+export type ServerExecutionCapability = { enabled: true } | { enabled: false; reason: ExecutionUnavailableReason };
+
+/** The capability as `GET /status` sends it, before validation. */
+export interface ServerExecutionCapabilityWire {
+  enabled: unknown;
+  reason?: unknown;
+}
+
+/** Failure codes that carry no structured meta. */
+export const PLAIN_EXECUTION_FAILURE_CODES = [
+  'GUARDIAN_EXECUTION_BINDING_MISMATCH',
+  'GUARDIAN_EXECUTION_STATE_MISMATCH',
+  'GUARDIAN_EXECUTION_REQUEST_CODEC',
+  'GUARDIAN_EXECUTION_PROTOCOL_MISMATCH',
+  'GUARDIAN_EXECUTION_CHAIN_BEHIND',
+  'GUARDIAN_EXECUTION_CHAIN_INCONSISTENT',
+  'GUARDIAN_EXECUTION_NODE_UNAVAILABLE',
+  'GUARDIAN_EXECUTION_INSUFFICIENT_FEE',
+  'GUARDIAN_EXECUTION_INSUFFICIENT_SIGNATURES',
+  'GUARDIAN_EXECUTION_PROVING_FAILED',
+  'GUARDIAN_EXECUTION_SEALING_FAILED',
+  'GUARDIAN_EXECUTION_ACKNOWLEDGEMENT_FAILED',
+  'GUARDIAN_EXECUTION_EXPIRATION_BEYOND_HORIZON',
+  'GUARDIAN_EXECUTION_ACCOUNT_INADMISSIBLE',
+  'GUARDIAN_EXECUTION_SUBMISSION_REJECTED',
+  'GUARDIAN_EXECUTION_SUBMISSION_NOT_PROCESSED',
+  'GUARDIAN_EXECUTION_CANDIDATE_DISCARDED',
+  'GUARDIAN_EXECUTION_EXPIRED',
+  'GUARDIAN_EXECUTION_LEASE_EXPIRED',
+  'GUARDIAN_EXECUTION_ABANDONED',
+] as const;
+export type PlainExecutionFailureCode = (typeof PLAIN_EXECUTION_FAILURE_CODES)[number];
+
+/** Why an execution failed, discriminated by `code`; codes with meta carry it typed. */
+export type ExecutionFailure =
+  | { code: 'GUARDIAN_EXECUTION_REQUEST_INVALID'; message: string; reason: RequestInvalidReason }
+  | { code: 'GUARDIAN_EXECUTION_EXPIRATION_REACHED'; message: string; bound: ExpirationBound }
+  | {
+      code: 'GUARDIAN_EXECUTION_FOREIGN_ACCOUNT_UNAVAILABLE';
+      message: string;
+      reason: ForeignAccountUnavailableReason;
+    }
+  | { code: PlainExecutionFailureCode; message: string };
+
+export type ExecutionFailureCode = ExecutionFailure['code'];
+
+export const EXECUTION_FAILURE_CODES: readonly ExecutionFailureCode[] = [
+  ...PLAIN_EXECUTION_FAILURE_CODES,
+  'GUARDIAN_EXECUTION_REQUEST_INVALID',
+  'GUARDIAN_EXECUTION_EXPIRATION_REACHED',
+  'GUARDIAN_EXECUTION_FOREIGN_ACCOUNT_UNAVAILABLE',
+];
+
+/** One execution of a proposal, identified by `(accountId, proposalId)`. */
+export interface ProposalExecution {
+  accountId: string;
+  proposalId: string;
+  state: ExecutionState;
+  /** Present exactly when `state` is `'failed'`. */
+  error: ExecutionFailure | null;
+  /** The delta nonce the execution committed to, once it crossed the no-retry boundary. */
+  deltaNonce: number | null;
+  /** Whether this request started the execution, rather than finding it already running. */
+  newlyAccepted: boolean;
+  /** Whether the proposal is still stored. A fact, not retry advice. */
+  proposalExists: boolean;
+  /** Stored signatures the server ignored as invalid, duplicate or not from a cosigner. */
+  ignoredSignatures: number;
+  updatedAt: string;
+}
+
+export interface ServerExecutionError {
+  code: string;
+  message: string;
+  meta?: Record<string, unknown>;
+}
+
+export interface ServerProposalExecution {
+  account_id: string;
+  proposal_id: string;
+  state: string;
+  error?: ServerExecutionError;
+  delta_nonce?: number;
+  newly_accepted: boolean;
+  proposal_exists: boolean;
+  ignored_signatures: number;
+  updated_at: string;
+}
+
+export interface ServerCurrentExecution {
+  execution: ServerProposalExecution | null;
+}
+
+function member<T extends string>(values: readonly T[], value: unknown, what: string): T {
+  if (typeof value === 'string' && (values as readonly string[]).includes(value)) {
+    return value as T;
+  }
+  throw new Error(`Guardian returned an unknown ${what}: ${JSON.stringify(value)}`);
+}
+
+/**
+ * Decodes a `GET /status` capability the server sent, refusing a missing flag or an unknown
+ * reason. A status without one does not offer Guardian execution.
+ */
+export function fromServerExecutionCapability(server: ServerExecutionCapabilityWire): ServerExecutionCapability {
+  if (typeof server !== 'object' || server === null) {
+    throw new Error(`Guardian returned a malformed execution capability: ${JSON.stringify(server)}`);
+  }
+  if (server.enabled === true) {
+    if (server.reason !== undefined) {
+      throw new Error(`Guardian returned an enabled execution capability with a reason: ${JSON.stringify(server.reason)}`);
+    }
+    return { enabled: true };
+  }
+  if (server.enabled === false) {
+    return { enabled: false, reason: member(EXECUTION_UNAVAILABLE_REASONS, server.reason, 'execution unavailable reason') };
+  }
+  throw new Error(`Guardian returned an execution capability without a boolean enabled: ${JSON.stringify(server.enabled)}`);
+}
+
+function fromServerFailure(error: ServerExecutionError): ExecutionFailure {
+  const { code, message, meta } = error;
+  switch (code) {
+    case 'GUARDIAN_EXECUTION_REQUEST_INVALID':
+      return { code, message, reason: member(REQUEST_INVALID_REASONS, meta?.reason, 'request reason') };
+    case 'GUARDIAN_EXECUTION_EXPIRATION_REACHED':
+      return { code, message, bound: member(EXPIRATION_BOUNDS, meta?.bound, 'expiration bound') };
+    case 'GUARDIAN_EXECUTION_FOREIGN_ACCOUNT_UNAVAILABLE':
+      return {
+        code,
+        message,
+        reason: member(FOREIGN_ACCOUNT_UNAVAILABLE_REASONS, meta?.reason, 'foreign account reason'),
+      };
+    default:
+      return { code: member(PLAIN_EXECUTION_FAILURE_CODES, code, 'execution failure code'), message };
+  }
+}
+
+/** Decodes the wire envelope, refusing any state, code or meta outside the vocabulary. */
+export function fromServerExecution(server: ServerProposalExecution): ProposalExecution {
+  const state = member(EXECUTION_STATES, server.state, 'execution state');
+  const error = server.error ? fromServerFailure(server.error) : null;
+  if ((state === 'failed') !== (error !== null)) {
+    throw new Error(`Guardian returned an execution in state '${state}' ${error ? 'with' : 'without'} an error`);
+  }
+  return {
+    accountId: server.account_id,
+    proposalId: server.proposal_id,
+    state,
+    error,
+    deltaNonce: server.delta_nonce ?? null,
+    newlyAccepted: server.newly_accepted,
+    proposalExists: server.proposal_exists,
+    ignoredSignatures: server.ignored_signatures,
+    updatedAt: server.updated_at,
+  };
+}