@openzeppelin/guardian-client 0.16.1 → 0.17.0-rc.1

package/src/http.ts

@@ -11,6 +11,8 @@ import type {
   DeltaProposalRequest,
   DeltaProposalResponse,
   ExecutionDelta,
+  HistoryOptions,
+  HistoryPage,
   LookupResponse,
   PubkeyResponse,
   PushDeltaResponse,
@@ -26,6 +28,7 @@ import type {
   ServerAbandonCandidateResponse,
   ServerDeltaObject,
   ServerDeltaProposalResponse,
+  ServerHistoryPage,
   ServerLookupResponse,
   ServerProposalsResponse,
   ServerPubkeyResponse,
@@ -37,6 +40,7 @@ import type {
 import {
   fromServerConfigureResponse,
   fromServerDeltaObject,
+  fromServerHistoryPage,
   fromServerLookupResponse,
   fromServerStateObject,
   toServerConfigureRequest,
@@ -149,10 +153,13 @@ export class GuardianHttpError extends Error {
    */
   public readonly releasedAt: string | null;
 
+  private readonly headerRetryAfterSecs?: number;
+
   constructor(
     public readonly status: number,
     public readonly statusText: string,
-    public readonly body: string
+    public readonly body: string,
+    retryAfterHeader?: string | null
   ) {
     // Only the parsed, user-safe message is folded into Error.message; the
     // raw body (which may carry backend/proxy internals) stays on the `body`
@@ -165,7 +172,37 @@ export class GuardianHttpError extends Error {
     this.userMessage = parsed?.message;
     this.meta = parsed?.meta;
     this.releasedAt = parsed?.meta.releasedAt ?? null;
+    this.headerRetryAfterSecs = parseRetryAfterSeconds(retryAfterHeader);
+  }
+
+  /**
+   * Whether the server marked this error safe to retry: `meta.retryable`
+   * from the envelope, falling back to the status class (429 rejections
+   * happen before any handler runs). Mirrors the Rust client's
+   * `ClientError::is_retryable`.
+   */
+  isRetryable(): boolean {
+    return this.meta?.retryable ?? this.status === 429;
   }
+
+  /**
+   * Server-provided backoff hint in seconds: the `Retry-After` header,
+   * falling back to `meta.retryAfterSecs`. Unparseable values mean no
+   * hint. Mirrors the Rust client's `ClientError::retry_after`.
+   */
+  retryAfterSecs(): number | undefined {
+    return this.headerRetryAfterSecs ?? this.meta?.retryAfterSecs;
+  }
+}
+
+// Decimal digits only, mirroring the Rust client's `parse::<u64>()`: no
+// signs, exponents, hex, or empty strings (`Number('')` is 0).
+function parseRetryAfterSeconds(header: string | null | undefined): number | undefined {
+  if (typeof header !== 'string') return undefined;
+  const trimmed = header.trim();
+  if (!/^\d+$/.test(trimmed)) return undefined;
+  const secs = Number(trimmed);
+  return Number.isSafeInteger(secs) ? secs : undefined;
 }
 
 /**
@@ -419,6 +456,33 @@ export class GuardianHttpClient {
     return fromServerDeltaObject(server);
   }
 
+  /**
+   * Fetch one page of the account's canonical delta history
+   * (issue #413), newest-first by nonce, with decoded input/output
+   * note summaries. Pass `options.cursor` from a previous page's
+   * `nextCursor` to resume; an absent `nextCursor` on the result means
+   * the feed is exhausted. Read-only: served while the account is
+   * paused. Only transactions pushed through Guardian appear.
+   */
+  async getDeltaHistory(accountId: string, options: HistoryOptions = {}): Promise<HistoryPage> {
+    // Signed payload and query string must carry the same values: the
+    // server signs the canonical JSON of its query struct, where limit
+    // stays a string and omitted parameters are omitted keys.
+    const requestPayload: Record<string, string> = { account_id: accountId };
+    if (options.limit !== undefined) {
+      requestPayload.limit = options.limit.toString();
+    }
+    if (options.cursor !== undefined) {
+      requestPayload.cursor = options.cursor;
+    }
+    const params = new URLSearchParams(requestPayload);
+    const response = await this.fetchAuthenticated(`/delta/history?${params}`, {
+      method: 'GET',
+    }, accountId, requestPayload);
+    const server = (await response.json()) as ServerHistoryPage;
+    return fromServerHistoryPage(server);
+  }
+
   private async fetch(path: string, init: RequestInit): Promise<Response> {
     const url = `${this.baseUrl}${path}`;
     const response = await fetch(url, {
@@ -431,7 +495,12 @@ export class GuardianHttpClient {
 
     if (!response.ok) {
       const body = await response.text();
-      throw new GuardianHttpError(response.status, response.statusText, body);
+      throw new GuardianHttpError(
+        response.status,
+        response.statusText,
+        body,
+        response.headers.get('Retry-After')
+      );
     }
 
     return response;
@@ -504,15 +573,16 @@ export class GuardianHttpClient {
         },
       });
     } catch (err) {
-      // Replay rejections (stale timestamp) are transient: retry once with a
-      // fresh timestamp. The specific "Replay attack" detail is now sanitized
-      // off the wire (feature 009), so branch on the stable auth code instead.
-      // Retrying a genuine auth failure is harmless — one extra attempt that
-      // also fails — and only happens when a retry budget remains.
+      // Replay rejections are transient: the request was correctly signed
+      // but lost the server's per-signer timestamp CAS. Retry with a fresh
+      // timestamp and signature, branching only on the dedicated
+      // `authentication_replay` code (issue #367); terminal authentication
+      // failures (invalid signature, clock outside the skew window) are
+      // never retried.
       if (
         retries > 0 &&
         err instanceof GuardianHttpError &&
-        err.code === 'authentication_failed'
+        err.code === 'authentication_replay'
       ) {
         await new Promise((resolve) => setTimeout(resolve, 50));
         return this.fetchAuthenticated(path, init, accountId, requestPayload, retries - 1);

package/src/index.ts

@@ -34,4 +34,14 @@ export type {
   SignProposalRequest,
   LookupAccount,
   LookupResponse,
+  HistoryDecodeSection,
+  HistoryDecodeWarning,
+  HistoryEntry,
+  HistoryEntryStatus,
+  HistoryNote,
+  HistoryNoteAsset,
+  HistoryNoteTag,
+  HistoryNoteVisibility,
+  HistoryOptions,
+  HistoryPage,
 } from './types.js';

package/src/server-types.ts

@@ -57,6 +57,12 @@ export interface ServerProposalMetadata {
   amount?: string;
   /** P2ID note visibility, "public" or "private" (issue #322). Absent => public. */
   note_type?: string;
+  /** Base64-serialized Miden `ChainAnchor` pinning the proposal's reference block. */
+  chain_anchor?: string;
+  /** P2IDE reclaim block height (issue #366). Presence of either height means a P2IDE note. */
+  reclaim_height?: number;
+  /** P2IDE timelock block height (issue #366). */
+  timelock_height?: number;
 }
 
 export interface ServerDeltaObject {
@@ -179,3 +185,40 @@ export interface ServerLookupAccount {
 export interface ServerLookupResponse {
   accounts: ServerLookupAccount[];
 }
+
+// --- Delta history (issue #413) ---
+
+export interface ServerHistoryNoteAsset {
+  asset_id: string;
+  kind: 'fungible' | 'non_fungible';
+  amount?: string;
+}
+
+export interface ServerHistoryNote {
+  note_id: string;
+  tag: 'p2id' | 'p2ide' | 'pswap' | 'mint' | 'burn' | 'custom';
+  note_type: 'public' | 'private';
+  assets: ServerHistoryNoteAsset[];
+  sender?: string;
+  recipient?: string;
+}
+
+export interface ServerHistoryDecodeWarning {
+  section: 'tx_summary' | 'metadata' | 'input_notes' | 'output_notes' | 'vault' | 'storage';
+  reason: string;
+}
+
+export interface ServerHistoryEntry {
+  nonce: number;
+  status: 'canonical';
+  timestamp: string;
+  new_commitment: string | null;
+  input_notes: ServerHistoryNote[];
+  output_notes: ServerHistoryNote[];
+  decode_warnings?: ServerHistoryDecodeWarning[];
+}
+
+export interface ServerHistoryPage {
+  items: ServerHistoryEntry[];
+  next_cursor: string | null;
+}

package/src/types.ts

@@ -105,6 +105,17 @@ export interface ProposalMetadata {
   amount?: string;
   /** P2ID note visibility, "public" or "private" (issue #322). Absent => public. */
   noteType?: string;
+  /**
+   * Base64-serialized Miden `ChainAnchor` pinning the reference block the
+   * proposal's transaction summary was built at. Since protocol 0.16 the
+   * signed summary binds the reference block commitment, so cosigners and the
+   * executor need this anchor to reproduce the summary the proposer signed.
+   */
+  chainAnchor?: string;
+  /** P2IDE reclaim block height (issue #366). Presence of either height means a P2IDE note. */
+  reclaimHeight?: number;
+  /** P2IDE timelock block height (issue #366). */
+  timelockHeight?: number;
 }
 
 export interface DeltaObject {
@@ -244,3 +255,90 @@ export interface LookupAccount {
 export interface LookupResponse {
   accounts: LookupAccount[];
 }
+
+/** Note classification decoded from the on-chain note script. */
+export type HistoryNoteTag = 'p2id' | 'p2ide' | 'pswap' | 'mint' | 'burn' | 'custom';
+
+/** On-chain note visibility from the note metadata. */
+export type HistoryNoteVisibility = 'public' | 'private';
+
+/** Which section of the persisted payload failed to decode. */
+export type HistoryDecodeSection =
+  | 'tx_summary'
+  | 'metadata'
+  | 'input_notes'
+  | 'output_notes'
+  | 'vault'
+  | 'storage';
+
+/**
+ * Delta lifecycle status of a history entry. Only `canonical` is
+ * emitted today; the set widens if the feed gains a status filter.
+ */
+export type HistoryEntryStatus = 'canonical';
+
+/**
+ * One decoded asset inside a history note. `amount` is a base-10
+ * string for fungible assets, absent for non-fungible ones.
+ */
+export interface HistoryNoteAsset {
+  assetId: string;
+  kind: 'fungible' | 'non_fungible';
+  amount?: string;
+}
+
+/**
+ * One decoded note attached to a history entry. `sender` / `recipient`
+ * are account IDs when the note script exposes them.
+ */
+export interface HistoryNote {
+  noteId: string;
+  tag: HistoryNoteTag;
+  /** On-chain visibility from the note metadata. */
+  noteType: HistoryNoteVisibility;
+  assets: HistoryNoteAsset[];
+  sender?: string;
+  recipient?: string;
+}
+
+/**
+ * Why a history entry's note sections are empty: the persisted payload
+ * could not be decoded server-side (schema drift). The entry itself is
+ * still returned.
+ */
+export interface HistoryDecodeWarning {
+  section: HistoryDecodeSection;
+  reason: string;
+}
+
+/** One canonical transaction in an account's history (issue #413). */
+export interface HistoryEntry {
+  nonce: number;
+  /** Delta lifecycle status; always `canonical` today. */
+  status: HistoryEntryStatus;
+  /** RFC 3339 UTC timestamp at which the delta became canonical. */
+  timestamp: string;
+  /**
+   * Account commitment after this transaction; `undefined` when the
+   * stored row predates commitment recording.
+   */
+  newCommitment?: string;
+  inputNotes: HistoryNote[];
+  outputNotes: HistoryNote[];
+  decodeWarnings: HistoryDecodeWarning[];
+}
+
+/** One page of canonical delta history, newest-first by nonce. */
+export interface HistoryPage {
+  entries: HistoryEntry[];
+  /** Opaque resume token; `undefined` when the feed is exhausted. */
+  nextCursor?: string;
+}
+
+/** Options for `getDeltaHistory`. */
+export interface HistoryOptions {
+  /** Page size in `[1, 500]`; server default 50 when omitted. */
+  limit?: number;
+  /** Opaque `nextCursor` from a previous page. */
+  cursor?: string;
+}