@openzeppelin/guardian-client 0.18.3 → 0.19.0-rc.2

package/src/http.ts

@@ -1,3 +1,8 @@
+import {
+  SESSION_REQUEST_AUTH_FORMAT,
+  SessionOperation,
+  isSessionWrite,
+} from './session-request.js';
 import {
   type GuardianErrorCode,
   normalizeGuardianErrorCode,
@@ -24,10 +29,17 @@ import type {
   SignatureScheme,
   Signer,
   StateObject,
+  StateTail,
   StatusResponse,
   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,
@@ -39,6 +51,7 @@ import type {
   ServerProposalsResponse,
   ServerPubkeyResponse,
   ServerStateObject,
+  ServerStateTail,
   ServerConfigureResponse,
   ServerCreateSessionResponse,
   ServerPushDeltaResponse,
@@ -55,6 +68,7 @@ import {
   fromServerHistoryPage,
   fromServerLookupResponse,
   fromServerStateObject,
+  fromServerStateTail,
   toServerConfigureRequest,
   toServerCreateSessionRequest,
   toServerDeltaProposalRequest,
@@ -84,6 +98,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 +183,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;
   }
@@ -242,6 +289,9 @@ function parseRetryAfterSeconds(header: string | null | undefined): number | und
  */
 const SESSION_EXPIRY_MARGIN_MS = 30_000;
 
+/** Replay rejections a request is re-signed and resent for. */
+const REPLAY_RETRIES = 2;
+
 /** Codes that end a session-signed request's session for good. */
 const SESSION_END_REASONS: Record<string, SessionEndReason> = {
   session_expired: 'expired',
@@ -253,13 +303,13 @@ const SESSION_END_REASONS: Record<string, SessionEndReason> = {
  * Which key signs a per-account request. Mirrors the server: requests are
  * wallet-signed unless the route is session-eligible.
  */
-type AuthMode = 'session' | 'wallet';
+type AuthMode = SessionOperation | 'wallet';
 
 function authHeaders(
   publicKey: string,
   signature: string,
   timestamp: number,
-  format?: 'eip712' | 'session'
+  format?: 'eip712' | typeof SESSION_REQUEST_AUTH_FORMAT
 ): Record<string, string> {
   return {
     'x-pubkey': publicKey,
@@ -301,8 +351,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,10 +484,16 @@ 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: {
               maxTtlSeconds: data.sessions.max_ttl_seconds,
+              ...(data.sessions.request_auth_version === undefined
+                ? {}
+                : { requestAuthVersion: data.sessions.request_auth_version }),
             },
           }
         : {}),
@@ -460,11 +516,35 @@ export class GuardianHttpClient {
     const params = new URLSearchParams(requestQuery);
     const response = await this.fetchAuthenticated(`/state?${params}`, {
       method: 'GET',
-    }, accountId, requestQuery, 'session');
+    }, accountId, requestQuery, SessionOperation.GetState);
     const server = (await response.json()) as ServerStateObject;
     return fromServerStateObject(server);
   }
 
+  /**
+   * The queue tail (`GET /state/tail`, issue #517): the state a new delta or
+   * proposal must build on, and the queued candidates that lead to it. With
+   * nothing queued it is the canonical state and `queue` is empty. Otherwise
+   * it is not on chain until the queued candidates land, and if one never
+   * does, the tail is abandoned with it. `acceptsSubmissions` is false while
+   * the queue would refuse anything built on the tail with
+   * `conflict_pending_delta` (a full queue, which at the default depth of 1 is
+   * any queue; a tail that changes the signers or the guardian key; a
+   * candidate a server before 0.19.0 queued under another label): wait for
+   * the queue to drain instead of building. Each read replays the queue on the
+   * server, so read it before building on the account; poll
+   * `getCanonicalNonce` instead. A server before 0.19.0 answers 404.
+   */
+  async getStateTail(accountId: string): Promise<StateTail> {
+    const requestQuery = { account_id: accountId };
+    const params = new URLSearchParams(requestQuery);
+    const response = await this.fetchAuthenticated(`/state/tail?${params}`, {
+      method: 'GET',
+    }, accountId, requestQuery, SessionOperation.GetStateTail);
+    const server = (await response.json()) as ServerStateTail;
+    return fromServerStateTail(server);
+  }
+
   /**
    * Nonce and commitment of the latest canonical state, without the state
    * blob (`GET /state/nonce`). A client can skip `getState` when the
@@ -477,7 +557,7 @@ export class GuardianHttpClient {
     const params = new URLSearchParams(requestQuery);
     const response = await this.fetchAuthenticated(`/state/nonce?${params}`, {
       method: 'GET',
-    }, accountId, requestQuery, 'session');
+    }, accountId, requestQuery, SessionOperation.GetCanonicalNonce);
     const server = (await response.json()) as ServerCanonicalNonceResponse;
     return fromServerCanonicalNonce(server);
   }
@@ -504,7 +584,7 @@ export class GuardianHttpClient {
     const params = new URLSearchParams(requestQuery);
     const response = await this.fetchAuthenticated(`/delta/proposal?${params}`, {
       method: 'GET',
-    }, accountId, requestQuery, 'session');
+    }, accountId, requestQuery, SessionOperation.GetDeltaProposals);
     const data = (await response.json()) as ServerProposalsResponse;
     return data.proposals.map(fromServerDeltaObject);
   }
@@ -514,7 +594,7 @@ export class GuardianHttpClient {
     const params = new URLSearchParams(requestQuery);
     const response = await this.fetchAuthenticated(`/delta/proposal/single?${params}`, {
       method: 'GET',
-    }, accountId, requestQuery, 'session');
+    }, accountId, requestQuery, SessionOperation.GetDeltaProposal);
     const data = (await response.json()) as ServerDeltaObject;
     return fromServerDeltaObject(data);
   }
@@ -524,7 +604,7 @@ export class GuardianHttpClient {
     const response = await this.fetchAuthenticated('/delta/proposal', {
       method: 'POST',
       body: JSON.stringify(serverRequest),
-    }, request.accountId, serverRequest, 'session');
+    }, request.accountId, serverRequest, SessionOperation.PushDeltaProposal);
     const server = (await response.json()) as ServerDeltaProposalResponse;
     return {
       delta: fromServerDeltaObject(server.delta),
@@ -532,6 +612,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), SessionOperation.ExecuteDeltaProposal);
+    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, SessionOperation.GetDeltaProposalExecution);
+    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, SessionOperation.GetCurrentExecution);
+    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 +666,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 +693,7 @@ export class GuardianHttpClient {
       nonce: server.nonce,
       state: server.state,
       abandonRequestedAt: server.abandon_requested_at,
+      commitment: server.commitment,
     };
   }
 
@@ -572,8 +708,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 +725,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';
@@ -607,18 +759,35 @@ export class GuardianHttpClient {
     const response = await this.fetchAuthenticated('/delta/proposal', {
       method: 'PUT',
       body: JSON.stringify(serverRequest),
-    }, request.accountId, serverRequest, 'session');
+    }, request.accountId, serverRequest, SessionOperation.SignDeltaProposal);
     const server = (await response.json()) as ServerDeltaObject;
     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,
+      SessionOperation.PushDelta
+    ).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,
@@ -642,7 +811,7 @@ export class GuardianHttpClient {
     const params = new URLSearchParams(requestQuery);
     const response = await this.fetchAuthenticated(`/delta?${params}`, {
       method: 'GET',
-    }, accountId, requestPayload, 'session');
+    }, accountId, requestPayload, SessionOperation.GetDelta);
     const server = (await response.json()) as ServerDeltaObject;
     return fromServerDeltaObject(server);
   }
@@ -659,7 +828,7 @@ export class GuardianHttpClient {
     const params = new URLSearchParams(requestQuery);
     const response = await this.fetchAuthenticated(`/delta/since?${params}`, {
       method: 'GET',
-    }, accountId, requestPayload, 'session');
+    }, accountId, requestPayload, SessionOperation.GetDeltaSince);
     const server = (await response.json()) as ServerDeltaObject;
     return fromServerDeltaObject(server);
   }
@@ -686,7 +855,7 @@ export class GuardianHttpClient {
     const params = new URLSearchParams(requestPayload);
     const response = await this.fetchAuthenticated(`/delta/history?${params}`, {
       method: 'GET',
-    }, accountId, requestPayload, 'session');
+    }, accountId, requestPayload, SessionOperation.GetDeltaHistory);
     const server = (await response.json()) as ServerHistoryPage;
     return fromServerHistoryPage(server);
   }
@@ -753,20 +922,65 @@ export class GuardianHttpClient {
     init: RequestInit,
     accountId: string,
     requestPayload: unknown,
-    mode: AuthMode = 'wallet',
-    retries = 2
+    mode: AuthMode = 'wallet'
   ): Promise<Response> {
-    const timestamp = this.nextTimestamp();
-    const authPayload = RequestAuthPayload.fromRequest(requestPayload);
-    const session = mode === 'session' ? this.getSession() : null;
-    const headers = session
+    return this.fetchSigned(path, init, accountId, RequestAuthPayload.fromRequest(requestPayload), mode);
+  }
+
+  private async fetchSigned(
+    path: string,
+    init: RequestInit,
+    accountId: string,
+    authPayload: RequestAuthPayload,
+    mode: AuthMode
+  ): Promise<Response> {
+    for (;;) {
+      const session = mode === 'wallet' ? null : this.getSession();
+      const response =
+        session && mode !== 'wallet' && isSessionWrite(mode)
+          ? await session.writeSequencer.run(accountId, () =>
+              this.sendSigned(path, init, accountId, authPayload, mode, session)
+            )
+          : await this.sendSigned(path, init, accountId, authPayload, mode, session);
+      if (response) {
+        return response;
+      }
+    }
+  }
+
+  /**
+   * Signs with `session` (the wallet when null) and retries replay
+   * rejections. Returns null, without sending, once `session` is no longer
+   * this client's session: a session write only ever signs within the write
+   * turn of the session it holds, and the caller starts over with the
+   * current one.
+   */
+  private async sendSigned(
+    path: string,
+    init: RequestInit,
+    accountId: string,
+    authPayload: RequestAuthPayload,
+    mode: AuthMode,
+    session: SessionRequestSigner | null,
+    retries = REPLAY_RETRIES
+  ): Promise<Response | null> {
+    if (session && this.getSession() !== session) {
+      return null;
+    }
+    const timestamp = session
+      ? await session.nextTimestamp(accountId, retries < REPLAY_RETRIES)
+      : this.nextTimestamp();
+    const headers = session && mode !== 'wallet'
       ? authHeaders(
           session.publicKey,
-          await session.signRequest(accountId, timestamp, authPayload),
+          await session.signRequest(mode, accountId, timestamp, authPayload),
           timestamp,
-          'session'
+          SESSION_REQUEST_AUTH_FORMAT
         )
       : await this.walletAuthHeaders(accountId, timestamp, authPayload);
+    if (session && this.getSession() !== session) {
+      return null;
+    }
 
     try {
       return await this.fetch(path, {
@@ -799,7 +1013,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.sendSigned(path, init, accountId, authPayload, mode, session, 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,52 @@ export {
 } from './error-codes.js';
 export type { GuardianErrorCode } from './error-codes.js';
 export { RequestAuthPayload } from './auth-request.js';
+export {
+  SESSION_REQUEST_AUTH_FORMAT,
+  SESSION_REQUEST_ENVELOPE_LENGTH,
+  SESSION_REQUEST_VERSION,
+  SESSION_TIMESTAMP_MAX_AHEAD_MS,
+  SessionOperation,
+  SessionTimestamps,
+  WriteSequencer,
+  isSessionWrite,
+  SessionTransport,
+  UnsupportedAuthVersionError,
+  assertSupportedSessionPolicy,
+  sessionRequestEnvelope,
+} from './session-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,11 +64,14 @@ export type {
   SignatureScheme,
   CosignerSignature,
   AuthConfig,
+  MidenCosignerConfig,
   CanonicalNonce,
   DeltaStatus,
   DeltaObject,
   ExecutionDelta,
   StateObject,
+  StateTail,
+  QueuedCandidate,
   ProposalType,
   ProposalMetadata,
   ConfigureRequest,

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 { PROTOCOL_LINE, sealTransactionRequest } from './request-envelope.js';
+
+describe('sealTransactionRequest', () => {
+  it('seals bytes with this SDK\'s protocol line, checksum and base64 body', 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 shared vector for this SDK\'s protocol line', 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[PROTOCOL_LINE]);
+  });
+});

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, apart from the protocol line each one declares.
+ */
+
+export const ENVELOPE_FORMAT_VERSION = 1;
+
+/** The Miden protocol line this SDK serializes requests for, as `MAJOR.MINOR`: that of its web SDK pin. */
+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),
+  };
+}