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

package/src/http.ts

@@ -28,6 +28,12 @@ import type {
   CanonicalNonce,
 } from './types.js';
 import { RequestAuthPayload } from './auth-request.js';
+import { fromServerExecution, fromServerExecutionCapability } from './execution.js';
+import type {
+  ProposalExecution,
+  ServerCurrentExecution,
+  ServerProposalExecution,
+} from './execution.js';
 import type {
   ServerAbandonCandidateRequest,
   ServerAbandonCandidateResponse,
@@ -84,6 +90,33 @@ export interface GuardianErrorMeta {
    * `code === 'signature_scheme_not_allowed'`.
    */
   allowedSchemes?: string[];
+  /**
+   * The proposal whose execution holds the account. Present only when
+   * `code === 'execution_conflict'`.
+   */
+  blockingProposalId?: string;
+  /**
+   * The proposal type GUARDIAN refuses to execute because the client that finishes its
+   * follow-up work must execute it. Present only when `code === 'proposal_executes_locally'`.
+   */
+  proposalType?: string;
+  /**
+   * Why GUARDIAN leaves the proposal to local execution. Present only when
+   * `code === 'proposal_executes_locally'`: `switch_guardian` for a guardian switch.
+   */
+  reason?: LocalExecutionReason;
+}
+
+/** Why GUARDIAN refuses to execute a proposal and leaves it to local execution. */
+export type LocalExecutionReason = 'switch_guardian';
+
+function localExecutionReason(value: unknown): LocalExecutionReason | undefined {
+  switch (value) {
+    case 'switch_guardian':
+      return value;
+    default:
+      return undefined;
+  }
 }
 
 interface ParsedGuardianError {
@@ -142,6 +175,12 @@ function parseGuardianErrorBody(body: string): ParsedGuardianError | undefined {
   ) {
     meta.allowedSchemes = rawMeta.allowed_schemes;
   }
+  if (typeof rawMeta.blocking_proposal_id === 'string') {
+    meta.blockingProposalId = rawMeta.blocking_proposal_id;
+  }
+  if (typeof rawMeta.proposal_type === 'string') meta.proposalType = rawMeta.proposal_type;
+  const reason = localExecutionReason(rawMeta.reason);
+  if (reason !== undefined) meta.reason = reason;
   if (typeof rawMeta.paused_reason === 'string' || rawMeta.paused_reason === null) {
     meta.pausedReason = rawMeta.paused_reason as string | null;
   }
@@ -301,8 +340,8 @@ export class GuardianHttpClient {
 
   /**
    * Sign session-eligible requests (reads, proposal list/get, proposal
-   * create/sign) with a registered delegated signer instead of the wallet.
-   * Every other route, including `configure`, `pushDelta`,
+   * create/sign, `pushDelta`) with a registered delegated signer instead of
+   * the wallet. Every other route, including `configure`,
    * `abandonCandidate`, account lookup and `revokeAllSessions`, uses the
    * wallet signer. Pass `null` to stop using the session.
    */
@@ -434,6 +473,9 @@ export class GuardianHttpClient {
       environment: data.environment,
       startedAt: data.started_at,
       uptimeSeconds: data.uptime_seconds,
+      ...(data.execution === undefined || data.execution === null
+        ? {}
+        : { execution: fromServerExecutionCapability(data.execution) }),
       ...(data.sessions
         ? {
             sessions: {
@@ -532,6 +574,48 @@ export class GuardianHttpClient {
     };
   }
 
+  /**
+   * Ask Guardian to prove and submit a threshold-met proposal. Resolves once the request is
+   * accepted; poll {@link getDeltaProposalExecution} for the outcome. Repeating the request while
+   * the execution runs returns it with `newlyAccepted: false`.
+   *
+   * Signed by the session while one is set, over the payload tagged as `ExecuteDeltaProposal`:
+   * the body names the same fields as a status read, and the tag keeps a signed read from
+   * authenticating an execution request.
+   */
+  async executeDeltaProposal(accountId: string, proposalId: string): Promise<ProposalExecution> {
+    const serverRequest = {
+      account_id: accountId,
+      proposal_id: proposalId,
+    };
+    const response = await this.fetchSigned('/delta/proposal/execution', {
+      method: 'POST',
+      body: JSON.stringify(serverRequest),
+    }, accountId, RequestAuthPayload.forOperation('ExecuteDeltaProposal', serverRequest), 'session');
+    return fromServerExecution((await response.json()) as ServerProposalExecution);
+  }
+
+  /** The latest execution attempt of a proposal. */
+  async getDeltaProposalExecution(accountId: string, proposalId: string): Promise<ProposalExecution> {
+    const requestQuery = { account_id: accountId, proposal_id: proposalId };
+    const params = new URLSearchParams(requestQuery);
+    const response = await this.fetchAuthenticated(`/delta/proposal/execution?${params}`, {
+      method: 'GET',
+    }, accountId, requestQuery, 'session');
+    return fromServerExecution((await response.json()) as ServerProposalExecution);
+  }
+
+  /** The account's in-flight execution, or `null`. A finished execution is not in flight. */
+  async getCurrentExecution(accountId: string): Promise<ProposalExecution | null> {
+    const requestQuery = { account_id: accountId };
+    const params = new URLSearchParams(requestQuery);
+    const response = await this.fetchAuthenticated(`/delta/execution/current?${params}`, {
+      method: 'GET',
+    }, accountId, requestQuery, 'session');
+    const server = (await response.json()) as ServerCurrentExecution;
+    return server.execution === null ? null : fromServerExecution(server.execution);
+  }
+
   /**
    * Request abandonment of a pending canonicalization candidate whose
    * transaction will never land on-chain (issue #319).
@@ -544,9 +628,22 @@ export class GuardianHttpClient {
    * for the resolution. Refused with `GUARDIAN_CANDIDATE_LANDED` (409)
    * when the transaction actually landed. Retries are idempotent and
    * preserve the original request timestamp.
+   *
+   * `proposalId` names the transaction: its summary's commitment, which
+   * is the proposal id of a multisig proposal. A Guardian execution can
+   * archive the delta and take its nonce; the abandon then still answers
+   * for this transaction.
    */
-  async abandonCandidate(accountId: string, nonce: number): Promise<AbandonCandidateResponse> {
-    const serverRequest: ServerAbandonCandidateRequest = { account_id: accountId, nonce };
+  async abandonCandidate(
+    accountId: string,
+    nonce: number,
+    proposalId: string,
+  ): Promise<AbandonCandidateResponse> {
+    const serverRequest: ServerAbandonCandidateRequest = {
+      account_id: accountId,
+      nonce,
+      proposal_id: proposalId,
+    };
     // Abandoning changes the account's canonical chain: always the wallet.
     const response = await this.fetchAuthenticated('/delta/candidate/abandon', {
       method: 'POST',
@@ -558,6 +655,7 @@ export class GuardianHttpClient {
       nonce: server.nonce,
       state: server.state,
       abandonRequestedAt: server.abandon_requested_at,
+      commitment: server.commitment,
     };
   }
 
@@ -572,8 +670,14 @@ export class GuardianHttpClient {
    * delta until its retention TTL expires — sync and check chain before
    * replacing it), `'unexpected'` for any state no abandon flow
    * produces (including a missing delta).
+   *
+   * `commitment` is the one {@link abandonCandidate} returned. Another
+   * delta can take the nonce (a Guardian execution archives the abandoned
+   * one): once it is canonical the abandoned transaction can no longer
+   * land (`'abandoned'`), and while it is a candidate the nonce is still
+   * contested (`'waiting'`).
    */
-  async abandonStatus(accountId: string, nonce: number): Promise<AbandonStatus> {
+  async abandonStatus(accountId: string, nonce: number, commitment: string): Promise<AbandonStatus> {
     let delta: DeltaObject;
     try {
       delta = await this.getDelta(accountId, nonce);
@@ -583,6 +687,16 @@ export class GuardianHttpClient {
       }
       throw e;
     }
+    if (delta.newCommitment?.toLowerCase() !== commitment.toLowerCase()) {
+      switch (delta.status.status) {
+        case 'canonical':
+          return 'abandoned';
+        case 'candidate':
+          return 'waiting';
+        default:
+          return 'unexpected';
+      }
+    }
     switch (delta.status.status) {
       case 'candidate':
         return 'waiting';
@@ -612,13 +726,30 @@ export class GuardianHttpClient {
     return fromServerDeltaObject(server);
   }
 
+  /**
+   * Push a delta for Guardian's acknowledgement. Signed by the session while
+   * one is set: Guardian acknowledges a multisig delta only once its
+   * proposal carries enough verified cosigner approvals, which the wallet
+   * signs. A Guardian that takes this route only from the wallet (an older
+   * release, or an account without a multisig state) answers
+   * `wallet_signature_required`, and the wallet signs the push again; the
+   * session stays in use for every other route.
+   */
   async pushDelta(delta: ExecutionDelta): Promise<PushDeltaResponse> {
     const serverDelta = toServerExecutionDelta(delta);
-    // Guardian's ACK commits the account to this transition: always the wallet.
-    const response = await this.fetchAuthenticated('/delta', {
-      method: 'POST',
-      body: JSON.stringify(serverDelta),
-    }, delta.accountId, serverDelta);
+    const init = { method: 'POST', body: JSON.stringify(serverDelta) };
+    const response = await this.fetchAuthenticated(
+      '/delta',
+      init,
+      delta.accountId,
+      serverDelta,
+      'session'
+    ).catch((err: unknown) => {
+      if (err instanceof GuardianHttpError && err.code === 'wallet_signature_required') {
+        return this.fetchAuthenticated('/delta', init, delta.accountId, serverDelta, 'wallet');
+      }
+      throw err;
+    });
     const server = (await response.json()) as ServerPushDeltaResponse;
     return {
       accountId: server.account_id,
@@ -753,11 +884,20 @@ export class GuardianHttpClient {
     init: RequestInit,
     accountId: string,
     requestPayload: unknown,
-    mode: AuthMode = 'wallet',
+    mode: AuthMode = 'wallet'
+  ): Promise<Response> {
+    return this.fetchSigned(path, init, accountId, RequestAuthPayload.fromRequest(requestPayload), mode);
+  }
+
+  private async fetchSigned(
+    path: string,
+    init: RequestInit,
+    accountId: string,
+    authPayload: RequestAuthPayload,
+    mode: AuthMode,
     retries = 2
   ): Promise<Response> {
     const timestamp = this.nextTimestamp();
-    const authPayload = RequestAuthPayload.fromRequest(requestPayload);
     const session = mode === 'session' ? this.getSession() : null;
     const headers = session
       ? authHeaders(
@@ -799,7 +939,7 @@ export class GuardianHttpClient {
         err.code === 'authentication_replay'
       ) {
         await new Promise((resolve) => setTimeout(resolve, 50));
-        return this.fetchAuthenticated(path, init, accountId, requestPayload, mode, retries - 1);
+        return this.fetchSigned(path, init, accountId, authPayload, mode, retries - 1);
       }
       throw err;
     }

package/src/index.ts

@@ -1,5 +1,5 @@
 export { GuardianHttpClient, GuardianHttpError } from './http.js';
-export type { GuardianErrorMeta } from './http.js';
+export type { GuardianErrorMeta, LocalExecutionReason } from './http.js';
 export {
   GUARDIAN_ERROR_CODES,
   isGuardianErrorCode,
@@ -7,6 +7,38 @@ export {
 } from './error-codes.js';
 export type { GuardianErrorCode } from './error-codes.js';
 export { RequestAuthPayload } from './auth-request.js';
+export type { SignedOperation } from './auth-request.js';
+export {
+  ENVELOPE_FORMAT_VERSION,
+  PROTOCOL_LINE,
+  decodeTransactionRequestEnvelope,
+  sealTransactionRequest,
+} from './request-envelope.js';
+export type { TransactionRequestEnvelope } from './request-envelope.js';
+export {
+  EXECUTION_FAILURE_CODES,
+  EXECUTION_STATES,
+  EXECUTION_UNAVAILABLE_REASONS,
+  EXPIRATION_BOUNDS,
+  FOREIGN_ACCOUNT_UNAVAILABLE_REASONS,
+  PLAIN_EXECUTION_FAILURE_CODES,
+  REQUEST_INVALID_REASONS,
+  fromServerExecution,
+  fromServerExecutionCapability,
+  isTerminalExecutionState,
+} from './execution.js';
+export type {
+  ExecutionFailure,
+  ExecutionFailureCode,
+  ExecutionState,
+  ExecutionUnavailableReason,
+  ExpirationBound,
+  ForeignAccountUnavailableReason,
+  PlainExecutionFailureCode,
+  ProposalExecution,
+  RequestInvalidReason,
+  ServerExecutionCapability,
+} from './execution.js';
 
 export type {
   AbandonCandidateResponse,
@@ -18,6 +50,7 @@ export type {
   SignatureScheme,
   CosignerSignature,
   AuthConfig,
+  MidenCosignerConfig,
   CanonicalNonce,
   DeltaStatus,
   DeltaObject,

package/src/request-envelope.test.ts

@@ -0,0 +1,30 @@
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { describe, it, expect } from 'vitest';
+import { sealTransactionRequest } from './request-envelope.js';
+
+describe('sealTransactionRequest', () => {
+  it('produces the envelope the Rust SDK and the server produce for the same bytes', async () => {
+    const envelope = await sealTransactionRequest(new TextEncoder().encode('abc'));
+    expect(envelope).toEqual({
+      format_version: 1,
+      protocol_line: '0.17',
+      checksum: '0xba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad',
+      bytes: 'YWJj',
+    });
+  });
+});
+
+describe('the shared envelope fixture', () => {
+  it('seals to the envelope the Rust SDK and the server produce', async () => {
+    const fixture = JSON.parse(
+      readFileSync(
+        join(dirname(fileURLToPath(import.meta.url)), '../../../fixtures/miden-multisig-client/request-envelope.json'),
+        'utf8',
+      ),
+    );
+    const bytes = Uint8Array.from(Buffer.from(fixture.bytes_hex, 'hex'));
+    expect(await sealTransactionRequest(bytes)).toEqual(fixture.sealed);
+  });
+});

package/src/request-envelope.ts

@@ -0,0 +1,68 @@
+/**
+ * The envelope a Guardian-executable proposal stores its serialized `TransactionRequest` in.
+ * Mirrors `guardian_shared::request_envelope`; the same bytes seal to the same envelope in both
+ * SDKs.
+ */
+
+export const ENVELOPE_FORMAT_VERSION = 1;
+
+/** The Miden protocol line requests are serialized for, as `MAJOR.MINOR`. */
+export const PROTOCOL_LINE = '0.17';
+
+/** Wire form: snake_case, exactly as the server stores it. */
+export interface TransactionRequestEnvelope {
+  format_version: number;
+  protocol_line: string;
+  /** `0x`-prefixed lowercase SHA-256 of the raw bytes. */
+  checksum: string;
+  /** Base64 of the raw bytes. */
+  bytes: string;
+}
+
+function toBase64(bytes: Uint8Array): string {
+  let binary = '';
+  for (const byte of bytes) {
+    binary += String.fromCharCode(byte);
+  }
+  return btoa(binary);
+}
+
+async function sha256Hex(bytes: Uint8Array): Promise<string> {
+  const digest = new Uint8Array(await globalThis.crypto.subtle.digest('SHA-256', new Uint8Array(bytes)));
+  return `0x${Array.from(digest, (byte) => byte.toString(16).padStart(2, '0')).join('')}`;
+}
+
+/** Wraps freshly serialized request bytes for storage with a proposal. */
+export async function sealTransactionRequest(bytes: Uint8Array): Promise<TransactionRequestEnvelope> {
+  return {
+    format_version: ENVELOPE_FORMAT_VERSION,
+    protocol_line: PROTOCOL_LINE,
+    checksum: await sha256Hex(bytes),
+    bytes: toBase64(bytes),
+  };
+}
+
+function envelopeField<T>(record: Record<string, unknown>, key: keyof TransactionRequestEnvelope, accepts: (value: unknown) => value is T): T {
+  const value = record[key];
+  if (!accepts(value)) {
+    throw new Error(`Guardian returned a transaction request envelope with an invalid ${key}: ${JSON.stringify(value)}`);
+  }
+  return value;
+}
+
+const isString = (value: unknown): value is string => typeof value === 'string';
+const isFormatVersion = (value: unknown): value is number => Number.isSafeInteger(value) && (value as number) >= 0;
+
+/** Decodes a stored envelope as the server returns it, refusing a missing or mistyped field. */
+export function decodeTransactionRequestEnvelope(value: unknown): TransactionRequestEnvelope {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+    throw new Error(`Guardian returned a transaction request envelope that is not an object: ${JSON.stringify(value)}`);
+  }
+  const record = value as Record<string, unknown>;
+  return {
+    format_version: envelopeField(record, 'format_version', isFormatVersion),
+    protocol_line: envelopeField(record, 'protocol_line', isString),
+    checksum: envelopeField(record, 'checksum', isString),
+    bytes: envelopeField(record, 'bytes', isString),
+  };
+}

package/src/server-types.ts

@@ -1,3 +1,6 @@
+import type { TransactionRequestEnvelope } from './request-envelope.js';
+import type { ServerExecutionCapabilityWire } from './execution.js';
+
 export interface ServerFalconSignature {
   scheme: 'falcon';
   signature: string;
@@ -43,6 +46,11 @@ export interface ServerProposalMetadata {
   target_threshold?: number;
   required_signatures?: number;
   signer_commitments?: string[];
+  /**
+   * Target signer schemes (`"falcon"` / `"ecdsa"`), index-aligned with
+   * `signer_commitments` (issue #563). Proposer-supplied and stored as sent.
+   */
+  signer_schemes?: string[];
   target_procedure?: string;
   salt?: string;
   description?: string;
@@ -78,6 +86,7 @@ export interface ServerDeltaObject {
     data?: string;
     signatures?: Array<{ signer_id: string; signature: ServerProposalSignature }>;
     metadata?: ServerProposalMetadata;
+    transaction_request?: TransactionRequestEnvelope;
   };
   ack_sig?: string;
   ack_pubkey?: string;
@@ -121,7 +130,13 @@ export interface ServerCanonicalNonceResponse {
 
 export type ServerAuthConfig =
   | { MidenFalconRpo: { cosigner_commitments: string[] } }
-  | { MidenEcdsa: { cosigner_commitments: string[] } };
+  | { MidenEcdsa: { cosigner_commitments: string[] } }
+  | {
+      Miden: {
+        cosigners: { commitment: string; scheme: 'falcon' | 'ecdsa' }[];
+        guardian_scheme: 'falcon' | 'ecdsa';
+      };
+    };
 
 export interface ServerConfigureRequest {
   account_id: string;
@@ -143,6 +158,7 @@ export interface ServerDeltaProposalRequest {
     tx_summary: { data: string };
     signatures: Array<{ signer_id: string; signature: ServerProposalSignature }>;
     metadata?: ServerProposalMetadata;
+    transaction_request?: TransactionRequestEnvelope;
   };
 }
 
@@ -158,6 +174,7 @@ export interface ServerProposalsResponse {
 export interface ServerAbandonCandidateRequest {
   account_id: string;
   nonce: number;
+  proposal_id: string;
 }
 
 export interface ServerAbandonCandidateResponse {
@@ -165,6 +182,7 @@ export interface ServerAbandonCandidateResponse {
   nonce: number;
   state: 'pending' | 'abandoned' | 'retained';
   abandon_requested_at?: string;
+  commitment: string;
 }
 
 export interface ServerSignProposalRequest {
@@ -185,6 +203,7 @@ export interface ServerStatusResponse {
   environment: string;
   started_at: string;
   uptime_seconds: number;
+  execution?: ServerExecutionCapabilityWire | null;
   sessions?: {
     max_ttl_seconds: number;
   };

package/src/types.ts

@@ -1,4 +1,7 @@
+import type { TransactionRequestEnvelope } from './request-envelope.js';
+
 import type { RequestAuthPayload } from './auth-request.js';
+import type { ServerExecutionCapability } from './execution.js';
 
 export interface Signer {
   readonly commitment: string;
@@ -153,6 +156,12 @@ export type ProposalSignature = FalconSignature | EcdsaSignature;
 
 export type SignatureScheme = 'falcon' | 'ecdsa';
 
+/** One cosigner of a {@link AuthConfig} `Miden` auth and the scheme Guardian verifies its signatures under. */
+export interface MidenCosignerConfig {
+  commitment: string;
+  scheme: SignatureScheme;
+}
+
 export type AuthConfig =
   | {
       MidenFalconRpo: {
@@ -163,6 +172,18 @@ export type AuthConfig =
       MidenEcdsa: {
         cosigner_commitments: string[];
       };
+    }
+  /**
+   * Cosigners that each carry their own scheme, and the GUARDIAN's scheme
+   * (issue #563). Send it only for an account whose cosigners and GUARDIAN
+   * do not all share one scheme; servers before #563 reject it, and the
+   * single-scheme variants keep serving the accounts that do.
+   */
+  | {
+      Miden: {
+        cosigners: MidenCosignerConfig[];
+        guardian_scheme: SignatureScheme;
+      };
     };
 
 export interface CosignerSignature {
@@ -206,6 +227,15 @@ export interface ProposalMetadata {
   targetThreshold?: number;
   requiredSignatures?: number;
   signerCommitments?: string[];
+  /**
+   * Target signer schemes (`"falcon"` / `"ecdsa"`), index-aligned with
+   * `signerCommitments`, for an update-signers proposal whose signers do not
+   * all share one scheme (issue #563). Absent => every target signer keeps the
+   * proposer's scheme. GUARDIAN stores the proposer's values as sent, so a
+   * consumer validates them, as it validates the rest of the metadata against
+   * the transaction summary, before relying on them.
+   */
+  signerSchemes?: string[];
   targetProcedure?: string;
   salt?: string;
   description?: string;
@@ -245,6 +275,8 @@ export interface DeltaObject {
     txSummary: { data: string };
     signatures: Array<{ signerId: string; signature: ProposalSignature }>;
     metadata?: ProposalMetadata;
+    /** The request a Guardian-executable proposal stores. Absent on a self-executed one. */
+    transactionRequest?: TransactionRequestEnvelope;
   };
   ackSig?: string;
   ackPubkey?: string;
@@ -268,6 +300,7 @@ export interface StateObject {
   stateJson: { data: string };
   createdAt: string;
   updatedAt: string;
+  /** `falcon` or `ecdsa` when the account's cosigners and GUARDIAN share that scheme, `mixed` when they do not. */
   authScheme?: string;
 }
 
@@ -310,6 +343,11 @@ export interface StatusResponse {
   environment: string;
   startedAt: string;
   uptimeSeconds: number;
+  /**
+   * Whether the server accepts Guardian execution requests. Absent on a Guardian that predates
+   * Guardian execution: it does not offer it.
+   */
+  execution?: ServerExecutionCapability;
   /** Present on every Guardian that accepts session grants; absent on older servers. */
   sessions?: SessionsStatus;
 }
@@ -321,6 +359,8 @@ export interface DeltaProposalRequest {
     txSummary: { data: string };
     signatures: Array<{ signerId: string; signature: ProposalSignature }>;
     metadata?: ProposalMetadata;
+    /** The request a Guardian-executable proposal stores. Omit for a self-executed one. */
+    transactionRequest?: TransactionRequestEnvelope;
   };
 }
 
@@ -357,13 +397,22 @@ export interface AbandonCandidateResponse {
    * return the original timestamp; absent once resolved.
    */
   abandonRequestedAt?: string;
+  /**
+   * The abandoned delta's `new_commitment`. Another delta can later take
+   * the same nonce (a Guardian execution archives the abandoned one), so
+   * pass this to `abandonStatus` to poll for this delta.
+   */
+  commitment: string;
 }
 
 /**
  * Resolution of an abandon request, as observed via the delta feed.
  * `'retained'` means the account slot is released but the on-chain
  * outcome is still uncertain — "unlocked but unresolved", never to be
- * read as "the transaction did not land".
+ * read as "the transaction did not land". When another delta has taken
+ * the nonce, `'abandoned'` means it is canonical (the abandoned
+ * transaction can no longer land) and `'waiting'` that it is still a
+ * candidate.
  */
 export type AbandonStatus = 'waiting' | 'landed' | 'abandoned' | 'retained' | 'unexpected';