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

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;
@@ -113,6 +122,18 @@ export interface ServerStateObject {
   auth_scheme?: string;
 }
 
+export interface ServerQueuedCandidate {
+  nonce: number;
+  prev_commitment: string;
+  new_commitment: string;
+}
+
+export interface ServerStateTail {
+  state: ServerStateObject;
+  queue: ServerQueuedCandidate[];
+  accepts_submissions: boolean;
+}
+
 export interface ServerCanonicalNonceResponse {
   account_id: string;
   nonce: number;
@@ -121,7 +142,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 +170,8 @@ export interface ServerDeltaProposalRequest {
     tx_summary: { data: string };
     signatures: Array<{ signer_id: string; signature: ServerProposalSignature }>;
     metadata?: ServerProposalMetadata;
+    transaction_request?: TransactionRequestEnvelope;
+    base_commitment?: string;
   };
 }
 
@@ -158,6 +187,7 @@ export interface ServerProposalsResponse {
 export interface ServerAbandonCandidateRequest {
   account_id: string;
   nonce: number;
+  proposal_id: string;
 }
 
 export interface ServerAbandonCandidateResponse {
@@ -165,6 +195,7 @@ export interface ServerAbandonCandidateResponse {
   nonce: number;
   state: 'pending' | 'abandoned' | 'retained';
   abandon_requested_at?: string;
+  commitment: string;
 }
 
 export interface ServerSignProposalRequest {
@@ -185,8 +216,10 @@ export interface ServerStatusResponse {
   environment: string;
   started_at: string;
   uptime_seconds: number;
+  execution?: ServerExecutionCapabilityWire | null;
   sessions?: {
     max_ttl_seconds: number;
+    request_auth_version?: number;
   };
 }
 
@@ -209,6 +242,7 @@ export interface ServerCreateSessionRequest {
 export interface ServerCreateSessionResponse {
   signer_commitment: string;
   expires_at: string;
+  request_auth_version?: number;
 }
 
 export interface ServerRevokeSessionResponse {

package/src/session-request.test.ts

@@ -0,0 +1,178 @@
+import { readFileSync } from 'node:fs';
+import { describe, expect, it } from 'vitest';
+import {
+  SESSION_TIMESTAMP_MAX_AHEAD_MS,
+  SessionTimestamps,
+  WriteSequencer,
+  isSessionWrite,
+  SESSION_REQUEST_AUTH_FORMAT,
+  SESSION_REQUEST_VERSION,
+  SessionOperation,
+  sessionRequestEnvelope,
+  type SessionTransport,
+} from './session-request.js';
+
+interface RequestVector {
+  name: string;
+  transport: number;
+  operation: number;
+  request_word_hex: string;
+  envelope_hex: string;
+}
+
+interface Fixture {
+  auth_format: string;
+  version: number;
+  operations: Array<{ id: number; name: string; replay_policy: string }>;
+  vectors: RequestVector[];
+}
+
+const fixture = JSON.parse(
+  readFileSync(
+    new URL('../../../crates/shared/tests/fixtures/session_request_vectors.json', import.meta.url),
+    'utf8'
+  )
+) as Fixture;
+
+const fromHex = (hex: string): Uint8Array =>
+  Uint8Array.from(Buffer.from(hex.replace(/^0x/, ''), 'hex'));
+
+describe('session request envelope', () => {
+  it('matches the Rust format, version and operation registry', () => {
+    expect(SESSION_REQUEST_AUTH_FORMAT).toBe(fixture.auth_format);
+    expect(SESSION_REQUEST_VERSION).toBe(fixture.version);
+    expect(
+      Object.entries(SessionOperation).map(([name, id]) => ({ id, name }))
+    ).toEqual(fixture.operations.map(({ id, name }) => ({ id, name })));
+  });
+
+  it('classifies writes as the Rust registry does', () => {
+    for (const { id, name, replay_policy } of fixture.operations) {
+      expect(isSessionWrite(id as SessionOperation), name).toBe(replay_policy === 'write');
+    }
+  });
+
+  it('encodes every vector byte for byte', () => {
+    for (const vector of fixture.vectors) {
+      const envelope = sessionRequestEnvelope(
+        vector.transport as SessionTransport,
+        vector.operation as SessionOperation,
+        fromHex(vector.request_word_hex)
+      );
+      expect(Buffer.from(envelope).toString('hex'), vector.name).toBe(
+        vector.envelope_hex.replace(/^0x/, '')
+      );
+    }
+  });
+
+  it('refuses a request word of the wrong length', () => {
+    expect(() =>
+      sessionRequestEnvelope(1, SessionOperation.GetState, new Uint8Array(31))
+    ).toThrow();
+  });
+});
+
+describe('SessionTimestamps', () => {
+  const NOW = 1_800_000_000_000;
+
+  it('gives equal clock readings distinct timestamps', async () => {
+    const timestamps = new SessionTimestamps(() => NOW);
+    expect(await timestamps.next('0xa')).toBe(NOW);
+    expect(await timestamps.next('0xa')).toBe(NOW + 1);
+  });
+
+  it('keeps accounts independent', async () => {
+    const timestamps = new SessionTimestamps(() => NOW);
+    for (let i = 0; i < 500; i++) {
+      await timestamps.next('0xa');
+    }
+    expect(await timestamps.next('0xb')).toBe(NOW);
+  });
+
+  it('waits instead of running more than a second ahead of the clock', async () => {
+    let now = NOW;
+    const timestamps = new SessionTimestamps(() => now);
+    for (let i = 0; i <= SESSION_TIMESTAMP_MAX_AHEAD_MS; i++) {
+      await timestamps.next('0xa');
+    }
+    const pending = timestamps.next('0xa');
+    now = NOW + 1;
+    expect(await pending).toBe(NOW + SESSION_TIMESTAMP_MAX_AHEAD_MS + 1);
+  });
+
+  it('never gives two waiting callers the same timestamp', async () => {
+    let now = NOW;
+    const timestamps = new SessionTimestamps(() => now);
+    for (let i = 0; i <= SESSION_TIMESTAMP_MAX_AHEAD_MS; i++) {
+      await timestamps.next('0xa');
+    }
+    const waiting = Array.from({ length: 50 }, () => timestamps.next('0xa'));
+    const ticker = setInterval(() => {
+      now += 1;
+    }, 1);
+    const issued = await Promise.all(waiting);
+    clearInterval(ticker);
+    expect(new Set(issued).size).toBe(issued.length);
+    for (const timestamp of issued) {
+      expect(timestamp).toBeGreaterThan(NOW + SESSION_TIMESTAMP_MAX_AHEAD_MS);
+    }
+  });
+
+  it('restarts from the clock when it steps back instead of waiting', async () => {
+    let now = NOW;
+    const timestamps = new SessionTimestamps(() => now);
+    expect(await timestamps.next('0xa')).toBe(NOW);
+    now = NOW - 10 * 60 * 1000;
+    expect(await timestamps.next('0xa')).toBe(now);
+    expect(await timestamps.next('0xa')).toBe(now + 1);
+  });
+
+  it('jumps near the ahead limit after a replay rejection', async () => {
+    const timestamps = new SessionTimestamps(() => NOW);
+    expect(await timestamps.next('0xa')).toBe(NOW);
+    const retried = await timestamps.next('0xa', true);
+    expect(retried).toBeGreaterThan(NOW + 1_000 - 200 - 1);
+    expect(retried).toBeLessThanOrEqual(NOW + 1_000);
+    expect(await timestamps.next('0xb')).toBe(NOW);
+  });
+});
+
+describe('WriteSequencer', () => {
+  it('runs writes to one account one at a time and keeps going after a failure', async () => {
+    const sequencer = new WriteSequencer();
+    const order: string[] = [];
+    let releaseFirst!: () => void;
+    const first = sequencer.run('0xa', async () => {
+      order.push('first start');
+      await new Promise<void>((resolve) => (releaseFirst = resolve));
+      order.push('first end');
+      throw new Error('first failed');
+    });
+    const second = sequencer.run('0xa', async () => {
+      order.push('second');
+      return 2;
+    });
+    const otherAccount = sequencer.run('0xb', async () => {
+      order.push('other account');
+      return 3;
+    });
+
+    expect(await otherAccount).toBe(3);
+    expect(order).toEqual(['first start', 'other account']);
+    releaseFirst();
+    await expect(first).rejects.toThrow('first failed');
+    expect(await second).toBe(2);
+    expect(order).toEqual(['first start', 'other account', 'first end', 'second']);
+  });
+
+  it('classifies only the four write operations as writes', () => {
+    expect(
+      Object.values(SessionOperation).filter((operation) => isSessionWrite(operation))
+    ).toEqual([
+      SessionOperation.PushDelta,
+      SessionOperation.PushDeltaProposal,
+      SessionOperation.SignDeltaProposal,
+      SessionOperation.ExecuteDeltaProposal,
+    ]);
+  });
+});

package/src/session-request.ts

@@ -0,0 +1,191 @@
+/**
+ * Version 2 session request envelope (mirror of
+ * `crates/shared/src/session_request.rs`). A session key signs a fixed
+ * 62-byte envelope that binds the transport and the operation in addition to
+ * the account, timestamp and payload of the `AuthRequestMessage` word, so a
+ * request signed for one route is never accepted on another:
+ *
+ * `"GUARDIAN_SESSION_REQUEST" 0x00 || u16be(2) || u8(transport) ||
+ * u16be(operation) || request word (32 bytes)`
+ *
+ * P-256 signs these bytes with SHA-256: WebCrypto
+ * `sign({ name: 'ECDSA', hash: 'SHA-256' }, key, envelope)`.
+ */
+
+/** `x-auth-format` value of a version 2 session request. */
+export const SESSION_REQUEST_AUTH_FORMAT = 'session-v2';
+
+/** The envelope version this client signs. */
+export const SESSION_REQUEST_VERSION = 2;
+
+/** Length of an encoded envelope. */
+export const SESSION_REQUEST_ENVELOPE_LENGTH = 62;
+
+const DOMAIN = new TextEncoder().encode('GUARDIAN_SESSION_REQUEST\0');
+
+/** How a request reaches Guardian. This client always uses HTTP. */
+export const SessionTransport = {
+  Http: 1,
+  Grpc: 2,
+} as const;
+export type SessionTransport = (typeof SessionTransport)[keyof typeof SessionTransport];
+
+/** Every per-account operation a session may sign. Ids are permanent. */
+export const SessionOperation = {
+  GetState: 1,
+  GetCanonicalNonce: 2,
+  GetDelta: 3,
+  GetDeltaSince: 4,
+  GetDeltaHistory: 5,
+  GetDeltaProposals: 6,
+  GetDeltaProposal: 7,
+  PushDelta: 8,
+  PushDeltaProposal: 9,
+  SignDeltaProposal: 10,
+  ExecuteDeltaProposal: 11,
+  GetDeltaProposalExecution: 12,
+  GetCurrentExecution: 13,
+  GetStateTail: 14,
+} as const;
+export type SessionOperation = (typeof SessionOperation)[keyof typeof SessionOperation];
+
+const WRITE_OPERATIONS: ReadonlySet<SessionOperation> = new Set([
+  SessionOperation.PushDelta,
+  SessionOperation.PushDeltaProposal,
+  SessionOperation.SignDeltaProposal,
+  SessionOperation.ExecuteDeltaProposal,
+]);
+
+/** Whether Guardian checks `operation` under the strict write floor. */
+export function isSessionWrite(operation: SessionOperation): boolean {
+  return WRITE_OPERATIONS.has(operation);
+}
+
+/** The bytes a session key signs for one per-account request. */
+export function sessionRequestEnvelope(
+  transport: SessionTransport,
+  operation: SessionOperation,
+  requestWord: Uint8Array
+): Uint8Array<ArrayBuffer> {
+  if (requestWord.length !== 32) {
+    throw new Error(`Request word must be 32 bytes, got ${requestWord.length}`);
+  }
+  const envelope = new Uint8Array(SESSION_REQUEST_ENVELOPE_LENGTH);
+  envelope.set(DOMAIN, 0);
+  envelope[25] = (SESSION_REQUEST_VERSION >> 8) & 0xff;
+  envelope[26] = SESSION_REQUEST_VERSION & 0xff;
+  envelope[27] = transport;
+  envelope[28] = (operation >> 8) & 0xff;
+  envelope[29] = operation & 0xff;
+  envelope.set(requestWord, 30);
+  return envelope;
+}
+
+/**
+ * Guardian does not support the session request format this client signs.
+ * Terminal: the session is kept, nothing is retried and the wallet does not
+ * sign instead.
+ */
+export class UnsupportedAuthVersionError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'UnsupportedAuthVersionError';
+  }
+}
+
+/**
+ * Throws {@link UnsupportedAuthVersionError} unless a Guardian reports the
+ * session request version this client signs: such a server would refuse
+ * every session request.
+ */
+export function assertSupportedSessionPolicy(policy: { requestAuthVersion?: number }): void {
+  if (policy.requestAuthVersion !== SESSION_REQUEST_VERSION) {
+    throw new UnsupportedAuthVersionError(
+      `Guardian reports session request version ${policy.requestAuthVersion ?? 'none'}, ` +
+        `this client signs version ${SESSION_REQUEST_VERSION}`
+    );
+  }
+}
+
+/** How far a session request timestamp may run ahead of the local clock. */
+export const SESSION_TIMESTAMP_MAX_AHEAD_MS = 1_000;
+
+/**
+ * A next timestamp this far ahead of the local clock means the clock stepped
+ * back, so minting restarts from the clock instead of waiting the step out.
+ */
+export const SESSION_CLOCK_STEP_BACK_MS = 5_000;
+
+/**
+ * After a replay rejection the next timestamp jumps to within this much below
+ * the ahead limit, at random, so it clears a floor an earlier page or tab of
+ * the same session left, and two of them stop colliding.
+ */
+export const SESSION_REPLAY_JUMP_SPREAD_MS = 200;
+
+/**
+ * Strictly increasing request timestamps per account, shared by every client
+ * using one session, so two otherwise identical requests are never the same
+ * signed bytes. Accounts are independent: a burst on one does not push
+ * another's timestamps ahead of the clock.
+ */
+export class SessionTimestamps {
+  private readonly last = new Map<string, number>();
+
+  constructor(private readonly now: () => number = Date.now) {}
+
+  /**
+   * The next timestamp for `accountId`, waiting while it would run more than a
+   * second ahead. `afterReplay` jumps it near that limit first (see
+   * `SESSION_REPLAY_JUMP_SPREAD_MS`).
+   */
+  async next(accountId: string, afterReplay = false): Promise<number> {
+    if (afterReplay) {
+      const jump =
+        this.now() +
+        SESSION_TIMESTAMP_MAX_AHEAD_MS -
+        Math.floor(Math.random() * SESSION_REPLAY_JUMP_SPREAD_MS);
+      this.last.set(accountId, Math.max(this.last.get(accountId) ?? -Infinity, jump - 1));
+    }
+    for (;;) {
+      const now = this.now();
+      let last = this.last.get(accountId) ?? -Infinity;
+      if (last - now > SESSION_CLOCK_STEP_BACK_MS) {
+        last = now - 1;
+      }
+      const next = Math.max(now, last + 1);
+      const ahead = next - now;
+      if (ahead <= SESSION_TIMESTAMP_MAX_AHEAD_MS) {
+        this.last.set(accountId, next);
+        return next;
+      }
+      await new Promise((resolve) => setTimeout(resolve, ahead - SESSION_TIMESTAMP_MAX_AHEAD_MS));
+    }
+  }
+}
+
+/**
+ * Runs a session's writes to one account one at a time, from minting the
+ * timestamp through the last replay retry, so they reach Guardian in
+ * timestamp order and never lose the strict write floor to each other. Writes
+ * to other accounts and all reads run freely.
+ */
+export class WriteSequencer {
+  private readonly tails = new Map<string, Promise<unknown>>();
+
+  run<T>(accountId: string, write: () => Promise<T>): Promise<T> {
+    const previous = this.tails.get(accountId) ?? Promise.resolve();
+    const result = previous.then(write);
+    const tail = result.then(
+      () => undefined,
+      () => undefined,
+    );
+    this.tails.set(accountId, tail);
+    void tail.then(() => {
+      if (this.tails.get(accountId) === tail) {
+        this.tails.delete(accountId);
+      }
+    });
+    return result;
+  }
+}

package/src/types.ts

@@ -1,4 +1,8 @@
+import type { SessionOperation, WriteSequencer } from './session-request.js';
+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;
@@ -92,7 +96,7 @@ export type SessionEndReason = 'logout' | 'expired' | 'revoked' | 'rejected';
 
 /**
  * Signs session-eligible requests on behalf of a wallet after a session grant
- * was registered. Requests carry `x-auth-format: session`.
+ * was registered. Requests carry `x-auth-format: session-v2`.
  */
 export interface SessionRequestSigner {
   /** Hex SEC1-compressed P-256 session public key, sent as `x-pubkey`. */
@@ -104,7 +108,21 @@ export interface SessionRequestSigner {
   readonly signerCommitment: string;
   /** Unix seconds. */
   readonly expiresAt: number;
+  /**
+   * The next request timestamp (Unix ms) for `accountId`: strictly increasing
+   * per account for this session, never more than a second ahead of the
+   * clock, and jumped near that limit when `afterReplay` (see
+   * `SessionTimestamps`).
+   */
+  nextTimestamp(accountId: string, afterReplay: boolean): Promise<number>;
+  /** Orders this session's writes per account; shared by every client using it. */
+  readonly writeSequencer: WriteSequencer;
+  /**
+   * Sign the version 2 envelope (see `sessionRequestEnvelope`) of this
+   * request over HTTP as `operation`.
+   */
   signRequest(
+    operation: SessionOperation,
     accountId: string,
     timestamp: number,
     requestPayload: RequestAuthPayload
@@ -125,14 +143,25 @@ export interface CreateSessionRequest {
   grant: SessionGrantFields;
 }
 
-export interface CreateSessionResponse {
+/** How a Guardian expects session requests to be signed. */
+export interface SessionRequestPolicy {
+  /**
+   * The session request envelope version; this client signs 2, under which
+   * each signed session read is admitted once, within 60 s of server time,
+   * except the canonical nonce poll, accepted every time within 60 s behind
+   * and 30 s ahead.
+   */
+  requestAuthVersion: number;
+}
+
+export interface CreateSessionResponse extends SessionRequestPolicy {
   signerCommitment: string;
   /** RFC 3339 UTC. */
   expiresAt: string;
 }
 
 /** Session parameters a Guardian advertises on `GET /status`. */
-export interface SessionsStatus {
+export interface SessionsStatus extends Partial<SessionRequestPolicy> {
   /** Grants may expire at most this many seconds after registration. */
   maxTtlSeconds: number;
 }
@@ -153,6 +182,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 +198,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 +253,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 +301,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,9 +326,51 @@ 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;
 }
 
+/** A queued candidate the queue tail replays (`GET /state/tail`). */
+export interface QueuedCandidate {
+  /** The account nonce the candidate's transaction leaves the account at. */
+  nonce: number;
+  /** The state it builds on: the canonical state for the oldest, the previous candidate's `newCommitment` after it. */
+  prevCommitment: string;
+  /** The state it leaves the account at. */
+  newCommitment: string;
+}
+
+/**
+ * The queue tail (`GET /state/tail`, issue #517): the state a new delta or
+ * proposal must build on while the account's candidate queue holds
+ * candidates, and the candidates that lead to it.
+ */
+export interface StateTail {
+  /**
+   * The canonical state with every queued candidate applied, shaped as
+   * `getState` returns a state; the canonical state itself when nothing is
+   * queued. Not on chain until the queued candidates land.
+   */
+  state: StateObject;
+  /**
+   * The queued candidates, oldest first: the first builds on the canonical
+   * state, each later one on the one before it, and the last one's
+   * `newCommitment` is the tail's commitment. Empty when nothing is queued.
+   */
+  queue: QueuedCandidate[];
+  /**
+   * Whether the queue takes a delta or proposal built on this tail now.
+   * False while the queue is full (at the default depth of 1, whenever
+   * anything is queued), while the tail changes the account's signers or
+   * guardian key, or while its newest candidate was queued by a server before
+   * 0.19.0 under a label other than its nonce: a submission on the tail then
+   * gets `conflict_pending_delta`, so wait for the queue to drain and read
+   * again. True holds only at this read: the tail can move before the push,
+   * and the account's status and the proposal limits still apply.
+   */
+  acceptsSubmissions: boolean;
+}
+
 /**
  * Head of the latest canonical state (`GET /state/nonce`): the account
  * nonce carried by the state GUARDIAN holds as canonical and that state's
@@ -310,6 +410,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 +426,17 @@ 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;
+    /**
+     * Commitment of the state the summary was built on (issue #517). GUARDIAN
+     * 0.19.0 and later record the proposal only when it is the queue tail,
+     * refusing a base another queued candidate claimed with
+     * `conflict_pending_delta` and an unknown one with `commitment_mismatch`.
+     * Omit it to be judged by the nonce alone; earlier servers store it with
+     * the payload and ignore it.
+     */
+    baseCommitment?: string;
   };
 }
 
@@ -357,13 +473,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';