@openzeppelin/guardian-client 0.16.2 → 0.17.0-rc.2

package/src/conversion.test.ts

@@ -454,6 +454,21 @@ describe('conversion', () => {
       expect(result.salt).toBe(original.salt);
     });
 
+    it('chainAnchor survives roundtrip as chain_anchor on the wire', () => {
+      const original: ProposalMetadata = {
+        proposalType: 'add_signer',
+        targetThreshold: 2,
+        signerCommitments: ['0xabc'],
+        chainAnchor: 'bW9jay1jaGFpbi1hbmNob3I=',
+      };
+
+      const server = toServerProposalMetadata(original);
+      expect(server.chain_anchor).toBe('bW9jay1jaGFpbi1hbmNob3I=');
+
+      const result = fromServerProposalMetadata(server);
+      expect(result.chainAnchor).toBe('bW9jay1jaGFpbi1hbmNob3I=');
+    });
+
     it('p2id noteType survives roundtrip as note_type on the wire (issue #322)', () => {
       const original: ProposalMetadata = {
         proposalType: 'p2id',
@@ -469,5 +484,24 @@ describe('conversion', () => {
       const result = fromServerProposalMetadata(server);
       expect(result.noteType).toBe('private');
     });
+
+    it('p2ide heights survive roundtrip as reclaim_height/timelock_height on the wire (issue #366)', () => {
+      const original: ProposalMetadata = {
+        proposalType: 'p2id',
+        recipientId: '0xrecipient',
+        faucetId: '0xfaucet',
+        amount: '1000',
+        reclaimHeight: 12345,
+        timelockHeight: 700,
+      };
+
+      const server = toServerProposalMetadata(original);
+      expect(server.reclaim_height).toBe(12345);
+      expect(server.timelock_height).toBe(700);
+
+      const result = fromServerProposalMetadata(server);
+      expect(result.reclaimHeight).toBe(12345);
+      expect(result.timelockHeight).toBe(700);
+    });
   });
 });

package/src/conversion.ts

@@ -6,6 +6,9 @@ import type {
   DeltaProposalRequest,
   DeltaStatus,
   ExecutionDelta,
+  HistoryEntry,
+  HistoryNote,
+  HistoryPage,
   LookupResponse,
   ProposalSignature,
   ProposalMetadata,
@@ -20,6 +23,9 @@ import type {
   ServerDeltaProposalRequest,
   ServerDeltaStatus,
   ServerExecutionDelta,
+  ServerHistoryEntry,
+  ServerHistoryNote,
+  ServerHistoryPage,
   ServerLookupResponse,
   ServerProposalSignature,
   ServerProposalMetadata,
@@ -109,6 +115,9 @@ export function fromServerProposalMetadata(server: ServerProposalMetadata): Prop
     faucetId: server.faucet_id,
     amount: server.amount,
     noteType: server.note_type,
+    chainAnchor: server.chain_anchor,
+    reclaimHeight: server.reclaim_height,
+    timelockHeight: server.timelock_height,
   };
 }
 
@@ -221,6 +230,9 @@ export function toServerProposalMetadata(meta: ProposalMetadata): ServerProposal
     faucet_id: meta.faucetId,
     amount: meta.amount,
     note_type: meta.noteType,
+    chain_anchor: meta.chainAnchor,
+    reclaim_height: meta.reclaimHeight,
+    timelock_height: meta.timelockHeight,
   };
 }
 
@@ -266,3 +278,37 @@ export function toServerExecutionDelta(delta: ExecutionDelta): ServerExecutionDe
     status: toServerDeltaStatus(delta.status),
   };
 }
+
+function fromServerHistoryNote(server: ServerHistoryNote): HistoryNote {
+  return {
+    noteId: server.note_id,
+    tag: server.tag,
+    noteType: server.note_type,
+    assets: server.assets.map((asset) => ({
+      assetId: asset.asset_id,
+      kind: asset.kind,
+      amount: asset.amount,
+    })),
+    sender: server.sender,
+    recipient: server.recipient,
+  };
+}
+
+export function fromServerHistoryEntry(server: ServerHistoryEntry): HistoryEntry {
+  return {
+    nonce: server.nonce,
+    status: server.status,
+    timestamp: server.timestamp,
+    newCommitment: server.new_commitment ?? undefined,
+    inputNotes: server.input_notes.map(fromServerHistoryNote),
+    outputNotes: server.output_notes.map(fromServerHistoryNote),
+    decodeWarnings: server.decode_warnings ?? [],
+  };
+}
+
+export function fromServerHistoryPage(server: ServerHistoryPage): HistoryPage {
+  return {
+    entries: server.items.map(fromServerHistoryEntry),
+    nextCursor: server.next_cursor ?? undefined,
+  };
+}

package/src/error-codes.ts

@@ -15,6 +15,7 @@ export const GUARDIAN_ERROR_CODES = [
   'account_paused',
   'account_released',
   'authentication_failed',
+  'authentication_replay',
   'authorization_failed',
   'candidate_landed',
   'commitment_mismatch',

package/src/http.test.ts

@@ -232,6 +232,52 @@ describe('GuardianHttpClient', () => {
 
       await expect(client.configure(request)).rejects.toThrow('No signer configured');
     });
+
+    it('retries a configure replay rejection with fresh authentication', async () => {
+      client.setSigner(mockSigner);
+      const signRequest = mockSigner.signRequest;
+      if (!signRequest) {
+        throw new Error('test signer must implement signRequest');
+      }
+      const signRequestMock = vi.mocked(signRequest);
+      signRequestMock.mockImplementation(
+        (_accountId, timestamp) => `0x${timestamp.toString(16).padStart(128, '0')}`
+      );
+      mockFetch
+        .mockResolvedValueOnce({
+          ok: false,
+          headers: new Headers(),
+          status: 401,
+          statusText: 'Unauthorized',
+          text: async () =>
+            JSON.stringify({
+              code: 'authentication_replay',
+              message: 'Guardian received this request out of order. Please try again.',
+              meta: { retryable: true },
+            }),
+        })
+        .mockResolvedValueOnce({
+          ok: true,
+          json: async () => ({ success: true, message: 'Account configured' }),
+        });
+
+      await client.configure({
+        accountId: '0x' + 'd'.repeat(30),
+        auth: {
+          MidenFalconRpo: {
+            cosigner_commitments: ['0x' + 'e'.repeat(64)],
+          },
+        },
+        initialState: { data: 'base64data', accountId: '0x' + 'd'.repeat(30) },
+      });
+
+      expect(mockFetch).toHaveBeenCalledTimes(2);
+      const timestamps = mockFetch.mock.calls.map((call) =>
+        Number((call[1].headers as Record<string, string>)['x-timestamp'])
+      );
+      expect(timestamps[1]).toBeGreaterThan(timestamps[0]);
+      expect(signRequestMock).toHaveBeenCalledTimes(2);
+    });
   });
 
   describe('getState', () => {
@@ -848,6 +894,136 @@ describe('GuardianHttpClient', () => {
     });
   });
 
+  // --- getDeltaHistory (issue #413) -----
+
+  describe('getDeltaHistory', () => {
+    const accountId = '0x' + 'a'.repeat(30);
+
+    const serverPage = {
+      items: [
+        {
+          nonce: 5,
+          status: 'canonical',
+          timestamp: '2026-08-01T12:00:05Z',
+          new_commitment: '0x' + 'c'.repeat(64),
+          input_notes: [],
+          output_notes: [
+            {
+              note_id: '0x' + 'd'.repeat(64),
+              tag: 'p2id',
+              note_type: 'public',
+              assets: [
+                { asset_id: '0x' + 'e'.repeat(30), kind: 'fungible', amount: '100' },
+              ],
+              sender: accountId,
+              recipient: '0x' + 'f'.repeat(30),
+            },
+          ],
+        },
+        {
+          nonce: 4,
+          status: 'canonical',
+          timestamp: '2026-08-01T12:00:04Z',
+          new_commitment: null,
+          input_notes: [],
+          output_notes: [],
+          decode_warnings: [{ section: 'tx_summary', reason: 'malformed_tx_summary' }],
+        },
+      ],
+      next_cursor: 'opaque-cursor',
+    };
+
+    it('returns a camelCase page and maps notes and warnings', async () => {
+      client.setSigner(mockSigner);
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: async () => serverPage,
+      });
+
+      const result = await client.getDeltaHistory(accountId, { limit: 2 });
+
+      expect(result.nextCursor).toBe('opaque-cursor');
+      expect(result.entries).toHaveLength(2);
+      expect(result.entries[0].nonce).toBe(5);
+      expect(result.entries[0].newCommitment).toBe('0x' + 'c'.repeat(64));
+      expect(result.entries[0].decodeWarnings).toEqual([]);
+      expect(result.entries[0].status).toBe('canonical');
+      expect(result.entries[0].outputNotes[0]).toEqual({
+        noteId: '0x' + 'd'.repeat(64),
+        tag: 'p2id',
+        noteType: 'public',
+        assets: [{ assetId: '0x' + 'e'.repeat(30), kind: 'fungible', amount: '100' }],
+        sender: accountId,
+        recipient: '0x' + 'f'.repeat(30),
+      });
+      expect(result.entries[1].newCommitment).toBeUndefined();
+      expect(result.entries[1].decodeWarnings).toEqual([
+        { section: 'tx_summary', reason: 'malformed_tx_summary' },
+      ]);
+
+      expect(mockFetch).toHaveBeenCalledWith(
+        `http://localhost:3000/delta/history?account_id=${accountId}&limit=2`,
+        expect.objectContaining({
+          method: 'GET',
+          headers: expect.objectContaining({
+            'x-pubkey': mockSigner.publicKey,
+          }),
+        })
+      );
+    });
+
+    it('signs the same key set it sends: omitted options stay omitted', async () => {
+      client.setSigner(mockSigner);
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({ items: [], next_cursor: null }),
+      });
+
+      const result = await client.getDeltaHistory(accountId);
+
+      expect(result.entries).toEqual([]);
+      expect(result.nextCursor).toBeUndefined();
+      expect(mockFetch).toHaveBeenCalledWith(
+        `http://localhost:3000/delta/history?account_id=${accountId}`,
+        expect.anything()
+      );
+      // The signed payload must byte-match the server's canonical JSON
+      // of its query struct: only account_id when limit/cursor are
+      // omitted, and limit as a string when present.
+      const signRequest = mockSigner.signRequest as ReturnType<typeof vi.fn>;
+      const lastCall = signRequest.mock.calls.at(-1);
+      if (lastCall === undefined) {
+        throw new Error('Expected signRequest to be called');
+      }
+      const authPayload = lastCall[2];
+      expect(authPayload.toCanonicalJson()).toBe(JSON.stringify({ account_id: accountId }));
+    });
+
+    it('passes the cursor through query and signed payload', async () => {
+      client.setSigner(mockSigner);
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({ items: [], next_cursor: null }),
+      });
+
+      await client.getDeltaHistory(accountId, { limit: 10, cursor: 'abc123' });
+
+      expect(mockFetch).toHaveBeenCalledWith(
+        `http://localhost:3000/delta/history?account_id=${accountId}&limit=10&cursor=abc123`,
+        expect.anything()
+      );
+      const signRequest = mockSigner.signRequest as ReturnType<typeof vi.fn>;
+      const lastCall = signRequest.mock.calls.at(-1);
+      if (lastCall === undefined) {
+        throw new Error('Expected signRequest to be called');
+      }
+      const authPayload = lastCall[2];
+      expect(authPayload.toCanonicalJson()).toBe(
+        JSON.stringify({ account_id: accountId, cursor: 'abc123', limit: '10' })
+      );
+    });
+  });
+
   // --- lookupAccountByKeyCommitment -----
 
   describe('lookupAccountByKeyCommitment', () => {
@@ -1114,17 +1290,13 @@ describe('GuardianHttpError', () => {
       expect(parsed.delta).toBeUndefined();
     });
 
-    it('surfaces 401 AUTHENTICATION_FAILED with a parseable error envelope', async () => {
+    it('does not retry a terminal 401 authentication_failed rejection', async () => {
       client.setSigner(mockSigner);
       const envelope = {
         code: 'authentication_failed',
-        message: 'Your session has expired. Please sign in again.',
+        message: 'Guardian could not authenticate this request.',
         meta: { retryable: false },
       };
-      // `authentication_failed` triggers the replay-retry path (the specific
-      // "Replay attack" detail is sanitized off the wire in feature 009, so we
-      // retry on the auth code). Use a persistent mock so the retries resolve
-      // and the final attempt throws the typed error.
       mockFetch.mockResolvedValue({
         ok: false,
         headers: new Headers(),
@@ -1146,9 +1318,103 @@ describe('GuardianHttpError', () => {
       expect(e.status).toBe(401);
       expect(e.code).toBe('authentication_failed');
       expect(typeof e.userMessage).toBe('string');
+      expect(mockFetch).toHaveBeenCalledTimes(1);
       const parsed = JSON.parse(e.body);
       expect(parsed.success).toBeUndefined();
       expect(parsed.delta).toBeUndefined();
     });
+
+    it('retries an authentication_replay rejection with a fresh timestamp and signature', async () => {
+      client.setSigner(mockSigner);
+      const signRequest = mockSigner.signRequest;
+      if (!signRequest) {
+        throw new Error('test signer must implement signRequest');
+      }
+      const signRequestMock = vi.mocked(signRequest);
+      signRequestMock.mockClear();
+      const signatureForTimestamp = (_accountId: string, timestamp: number) =>
+        `0x${timestamp.toString(16).padStart(128, '0')}`;
+      signRequestMock
+        .mockImplementationOnce(signatureForTimestamp)
+        .mockImplementationOnce(signatureForTimestamp);
+      const replayResponse = {
+        ok: false,
+        headers: new Headers(),
+        status: 401,
+        statusText: 'Unauthorized',
+        text: async () =>
+          JSON.stringify({
+            code: 'authentication_replay',
+            message: 'Guardian received this request out of order. Please try again.',
+            meta: { retryable: true },
+          }),
+      };
+      const serverResponse = {
+        delta: {
+          account_id: '0x' + 'a'.repeat(30),
+          nonce: 1,
+          prev_commitment: '0x' + 'b'.repeat(64),
+          delta_payload: { tx_summary: { data: '' }, signatures: [] },
+          status: {
+            status: 'pending',
+            timestamp: '2024-01-01T00:00:00Z',
+            proposer_id: '0x' + 'c'.repeat(64),
+            cosigner_sigs: [],
+          },
+        },
+        commitment: '0x' + 'd'.repeat(64),
+      };
+      mockFetch
+        .mockResolvedValueOnce(replayResponse)
+        .mockResolvedValueOnce({ ok: true, json: async () => serverResponse });
+
+      const result = await client.pushDeltaProposal({
+        accountId: '0x' + 'a'.repeat(30),
+        nonce: 1,
+        deltaPayload: { txSummary: { data: '' }, signatures: [] },
+      });
+
+      expect(result.commitment).toBe('0x' + 'd'.repeat(64));
+      expect(mockFetch).toHaveBeenCalledTimes(2);
+      const timestamps = mockFetch.mock.calls.map((call) =>
+        Number((call[1].headers as Record<string, string>)['x-timestamp'])
+      );
+      const signatures = mockFetch.mock.calls.map(
+        (call) => (call[1].headers as Record<string, string>)['x-signature']
+      );
+      expect(timestamps[1]).toBeGreaterThan(timestamps[0]);
+      expect(signatures[1]).not.toBe(signatures[0]);
+      expect(signRequestMock).toHaveBeenCalledTimes(2);
+    });
+
+    it('gives up after exhausting the bounded replay retry budget', async () => {
+      client.setSigner(mockSigner);
+      mockFetch.mockResolvedValue({
+        ok: false,
+        headers: new Headers(),
+        status: 401,
+        statusText: 'Unauthorized',
+        text: async () =>
+          JSON.stringify({
+            code: 'authentication_replay',
+            message: 'Guardian received this request out of order. Please try again.',
+            meta: { retryable: true },
+          }),
+      });
+
+      const error = await client
+        .pushDeltaProposal({
+          accountId: '0x' + 'a'.repeat(30),
+          nonce: 1,
+          deltaPayload: { txSummary: { data: '' }, signatures: [] },
+        })
+        .catch((e) => e as GuardianHttpError);
+
+      expect(error).toBeInstanceOf(GuardianHttpError);
+      const e = error as GuardianHttpError;
+      expect(e.code).toBe('authentication_replay');
+      expect(e.meta?.retryable).toBe(true);
+      expect(mockFetch).toHaveBeenCalledTimes(3);
+    });
   });
 });

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,
@@ -452,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, {
@@ -542,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;
+}