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

package/src/http.test.ts

@@ -1,6 +1,13 @@
 import { readFileSync } from 'node:fs';
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
 import { GuardianHttpClient, GuardianHttpError } from './http.js';
+import { RequestAuthPayload } from './auth-request.js';
+import {
+  SessionOperation,
+  SessionTimestamps,
+  UnsupportedAuthVersionError,
+  WriteSequencer,
+} from './session-request.js';
 import type { Signer, ConfigureResponse, StateObject, DeltaObject, DeltaProposalResponse, SessionRequestSigner } from './types.js';
 
 // Mock fetch globally
@@ -129,6 +136,7 @@ describe('GuardianHttpClient', () => {
           environment: 'devnet',
           started_at: '2026-06-17T10:00:00Z',
           uptime_seconds: 3600,
+          execution: { enabled: true },
         }),
       });
 
@@ -141,6 +149,7 @@ describe('GuardianHttpClient', () => {
         environment: 'devnet',
         startedAt: '2026-06-17T10:00:00Z',
         uptimeSeconds: 3600,
+        execution: { enabled: true },
       });
       expect(mockFetch).toHaveBeenCalledWith(
         'http://localhost:3000/status',
@@ -153,6 +162,60 @@ describe('GuardianHttpClient', () => {
       );
     });
 
+    it('reports why the server does not offer execution', async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({
+          status: 'ok',
+          version: '0.1.0',
+          git_commit: 'abc123def456',
+          environment: 'devnet',
+          started_at: '2026-06-17T10:00:00Z',
+          uptime_seconds: 3600,
+          execution: { enabled: false, reason: 'prover_not_configured' },
+        }),
+      });
+
+      const status = await client.getStatus();
+
+      expect(status.execution).toEqual({ enabled: false, reason: 'prover_not_configured' });
+    });
+
+    it('reads a status without an execution capability as not offering execution', async () => {
+      const base = {
+        status: 'ok',
+        version: '0.18.2',
+        git_commit: 'abc123def456',
+        environment: 'devnet',
+        started_at: '2026-06-17T10:00:00Z',
+        uptime_seconds: 3600,
+        sessions: { max_ttl_seconds: 28800 },
+      };
+      mockFetch.mockResolvedValueOnce({ ok: true, json: async () => base });
+      const status = await client.getStatus();
+      expect(status).not.toHaveProperty('execution');
+      expect(status.sessions).toEqual({ maxTtlSeconds: 28800 });
+
+      mockFetch.mockResolvedValueOnce({ ok: true, json: async () => ({ ...base, execution: null }) });
+      await expect(client.getStatus()).resolves.not.toHaveProperty('execution');
+    });
+
+    it('refuses a status whose execution capability names an unknown reason', async () => {
+      const base = {
+        status: 'ok',
+        version: '0.1.0',
+        git_commit: 'abc123def456',
+        environment: 'devnet',
+        started_at: '2026-06-17T10:00:00Z',
+        uptime_seconds: 3600,
+      };
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({ ...base, execution: { enabled: false, reason: 'gone_fishing' } }),
+      });
+      await expect(client.getStatus()).rejects.toThrow(/unknown execution unavailable reason/);
+    });
+
     it('should throw GuardianHttpError on non-ok response', async () => {
       mockFetch.mockResolvedValueOnce({
         ok: false,
@@ -223,6 +286,38 @@ describe('GuardianHttpClient', () => {
       );
     });
 
+    it('sends a per-signer-scheme Miden auth as the server reads it (issue #563)', async () => {
+      client.setSigner(mockSigner);
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({ success: true, message: 'Account configured', ack_pubkey: '0x' + 'c'.repeat(66) }),
+      });
+      const auth = {
+        Miden: {
+          cosigners: [
+            { commitment: '0x' + 'e'.repeat(64), scheme: 'falcon' as const },
+            { commitment: '0x' + 'f'.repeat(64), scheme: 'ecdsa' as const },
+          ],
+          guardian_scheme: 'ecdsa' as const,
+        },
+      };
+      await client.configure({
+        accountId: '0x' + 'd'.repeat(30),
+        auth,
+        initialState: { data: 'base64data', accountId: '0x' + 'd'.repeat(30) },
+      });
+      const body = JSON.parse(mockFetch.mock.calls[0][1].body as string);
+      expect(body.auth).toEqual({
+        Miden: {
+          cosigners: [
+            { commitment: '0x' + 'e'.repeat(64), scheme: 'falcon' },
+            { commitment: '0x' + 'f'.repeat(64), scheme: 'ecdsa' },
+          ],
+          guardian_scheme: 'ecdsa',
+        },
+      });
+    });
+
     it('should throw error when no signer configured', async () => {
       const request = {
         accountId: '0x' + 'd'.repeat(30),
@@ -354,6 +449,143 @@ describe('GuardianHttpClient', () => {
     });
   });
 
+  describe('getStateTail', () => {
+    const accountId = '0x' + 'a'.repeat(30);
+    const serverState = {
+      account_id: accountId,
+      commitment: '0x' + 'c'.repeat(64),
+      state_json: { data: 'tail' },
+      created_at: '2024-01-01T00:00:00Z',
+      updated_at: '2024-01-02T00:00:00Z',
+      auth_scheme: 'falcon',
+    };
+
+    it('reads the tail and its queue, signed over the account query', async () => {
+      client.setSigner(mockSigner);
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({
+          state: serverState,
+          queue: [
+            {
+              nonce: 5,
+              prev_commitment: '0x' + 'b'.repeat(64),
+              new_commitment: '0x' + 'c'.repeat(64),
+            },
+          ],
+          accepts_submissions: false,
+        }),
+      });
+
+      const tail = await client.getStateTail(accountId);
+
+      expect(tail).toEqual({
+        state: {
+          accountId,
+          commitment: '0x' + 'c'.repeat(64),
+          stateJson: { data: 'tail' },
+          createdAt: '2024-01-01T00:00:00Z',
+          updatedAt: '2024-01-02T00:00:00Z',
+          authScheme: 'falcon',
+        },
+        queue: [
+          {
+            nonce: 5,
+            prevCommitment: '0x' + 'b'.repeat(64),
+            newCommitment: '0x' + 'c'.repeat(64),
+          },
+        ],
+        acceptsSubmissions: false,
+      });
+      expect(mockFetch).toHaveBeenCalledWith(
+        `http://localhost:3000/state/tail?account_id=${accountId}`,
+        expect.objectContaining({ method: 'GET' })
+      );
+      expect(mockSigner.signRequest).toHaveBeenCalledWith(
+        accountId,
+        expect.any(Number),
+        expect.objectContaining({ canonicalJson: JSON.stringify({ account_id: accountId }), tag: '' }),
+      );
+    });
+
+    it('reads an empty queue as the canonical state', async () => {
+      client.setSigner(mockSigner);
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({ state: serverState, queue: [], accepts_submissions: true }),
+      });
+
+      const tail = await client.getStateTail(accountId);
+
+      expect(tail.queue).toEqual([]);
+      expect(tail.state.commitment).toBe('0x' + 'c'.repeat(64));
+      expect(tail.acceptsSubmissions).toBe(true);
+    });
+
+    it('rejects a tail that does not say whether it accepts submissions', async () => {
+      client.setSigner(mockSigner);
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({ state: serverState, queue: [] }),
+      });
+
+      await expect(client.getStateTail(accountId)).rejects.toThrow(
+        'Invalid accepts_submissions from server'
+      );
+    });
+
+    it('surfaces an older server without the route as a 404', async () => {
+      client.setSigner(mockSigner);
+      mockFetch.mockResolvedValueOnce({
+        ok: false,
+        headers: new Headers(),
+        status: 404,
+        statusText: 'Not Found',
+        text: async () => '',
+      });
+
+      const error = await client.getStateTail(accountId).catch((e) => e);
+      expect(error).toBeInstanceOf(GuardianHttpError);
+      expect(error.status).toBe(404);
+    });
+
+    it('surfaces a queue with no tail to serve as a pending conflict', async () => {
+      client.setSigner(mockSigner);
+      mockFetch.mockResolvedValueOnce({
+        ok: false,
+        headers: new Headers(),
+        status: 409,
+        statusText: 'Conflict',
+        text: async () =>
+          JSON.stringify({
+            code: 'conflict_pending_delta',
+            message: 'A delta is already pending for this account',
+            meta: { retryable: true },
+          }),
+      });
+
+      const error = await client.getStateTail(accountId).catch((e) => e);
+      expect(error).toBeInstanceOf(GuardianHttpError);
+      expect(error.code).toBe('conflict_pending_delta');
+    });
+
+    it('rejects a queued nonce the client cannot represent', async () => {
+      client.setSigner(mockSigner);
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({
+          state: serverState,
+          queue: [{ nonce: 2 ** 53, prev_commitment: '0x1', new_commitment: '0x2' }],
+          accepts_submissions: false,
+        }),
+      });
+
+      await expect(client.getStateTail(accountId)).rejects.toThrow(
+        'Invalid queued candidate nonce'
+      );
+    });
+  });
+
   describe('getState', () => {
     it('uses the existing signed headers with an EIP-712 format selector', async () => {
       const signer: Signer = {
@@ -485,6 +717,30 @@ describe('GuardianHttpClient', () => {
   });
 
   describe('getDeltaProposal', () => {
+    it('keeps the stored transaction request of a Guardian-executable proposal', async () => {
+      client.setSigner(mockSigner);
+      const envelope = { format_version: 1, protocol_line: '0.17', checksum: '0x' + 'd'.repeat(64), bytes: 'AQID' };
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({
+          account_id: '0x' + 'a'.repeat(30),
+          nonce: 1,
+          prev_commitment: '0x' + 'b'.repeat(64),
+          delta_payload: { tx_summary: { data: 'base64summary' }, signatures: [], transaction_request: envelope },
+          status: {
+            status: 'pending',
+            timestamp: '2024-01-01T00:00:00Z',
+            proposer_id: '0x' + 'c'.repeat(64),
+            cosigner_sigs: [],
+          },
+        }),
+      });
+
+      const proposal = await client.getDeltaProposal('0x' + 'a'.repeat(30), '0x' + 'e'.repeat(64));
+
+      expect(proposal.deltaPayload.transactionRequest).toEqual(envelope);
+    });
+
     it('should get a single delta proposal by commitment', async () => {
       client.setSigner(mockSigner);
 
@@ -652,6 +908,106 @@ describe('GuardianHttpClient', () => {
     });
   });
 
+  describe('Guardian execution', () => {
+    const account = '0x' + 'a'.repeat(30);
+    const serverExecution = {
+      account_id: account,
+      proposal_id: '0xproposal',
+      state: 'pending',
+      newly_accepted: true,
+      proposal_exists: true,
+      ignored_signatures: 1,
+      updated_at: '2026-09-30T12:00:00Z',
+    };
+
+    it('requests execution with a snake_case body and maps the envelope', async () => {
+      client.setSigner(mockSigner);
+      mockFetch.mockResolvedValueOnce({ ok: true, json: async () => serverExecution });
+
+      const execution = await client.executeDeltaProposal(account, '0xproposal');
+
+      expect(execution).toEqual({
+        accountId: account,
+        proposalId: '0xproposal',
+        state: 'pending',
+        error: null,
+        deltaNonce: null,
+        newlyAccepted: true,
+        proposalExists: true,
+        ignoredSignatures: 1,
+        updatedAt: '2026-09-30T12:00:00Z',
+      });
+      expect(mockFetch).toHaveBeenCalledWith(
+        'http://localhost:3000/delta/proposal/execution',
+        expect.objectContaining({
+          method: 'POST',
+          body: JSON.stringify({
+            account_id: account,
+            proposal_id: '0xproposal',
+          }),
+        })
+      );
+    });
+
+    it('signs the execution request tagged as ExecuteDeltaProposal, and its status read untagged', async () => {
+      client.setSigner(mockSigner);
+      const signRequest = vi.mocked(mockSigner.signRequest!);
+      signRequest.mockClear();
+      mockFetch
+        .mockResolvedValueOnce({ ok: true, json: async () => serverExecution })
+        .mockResolvedValueOnce({ ok: true, json: async () => serverExecution });
+
+      await client.executeDeltaProposal(account, '0xproposal');
+      await client.getDeltaProposalExecution(account, '0xproposal');
+
+      const body = { account_id: account, proposal_id: '0xproposal' };
+      const [execute, read] = signRequest.mock.calls.map((call) => call[2].toBytes());
+      expect(execute).toEqual(RequestAuthPayload.forOperation('ExecuteDeltaProposal', body).toBytes());
+      expect(read).toEqual(RequestAuthPayload.fromRequest(body).toBytes());
+      expect(execute).not.toEqual(read);
+    });
+
+    it('reads an execution and the in-flight one by query', async () => {
+      client.setSigner(mockSigner);
+      mockFetch
+        .mockResolvedValueOnce({ ok: true, json: async () => ({ ...serverExecution, state: 'submitted', delta_nonce: 3 }) })
+        .mockResolvedValueOnce({ ok: true, json: async () => ({ execution: null }) });
+
+      const status = await client.getDeltaProposalExecution(account, '0xproposal');
+      expect(status.state).toBe('submitted');
+      expect(status.deltaNonce).toBe(3);
+      expect(await client.getCurrentExecution(account)).toBeNull();
+
+      expect(mockFetch.mock.calls[0][0]).toBe(
+        `http://localhost:3000/delta/proposal/execution?account_id=${account}&proposal_id=0xproposal`
+      );
+      expect(mockFetch.mock.calls[1][0]).toBe(
+        `http://localhost:3000/delta/execution/current?account_id=${account}`
+      );
+    });
+
+    it('surfaces a synchronous refusal as a typed code', async () => {
+      client.setSigner(mockSigner);
+      mockFetch.mockResolvedValueOnce({
+        ok: false,
+        headers: new Headers(),
+        status: 409,
+        statusText: 'Conflict',
+        text: async () =>
+          JSON.stringify({
+            code: 'GUARDIAN_PROPOSAL_NOT_READY',
+            message: 'This transaction still needs more signatures.',
+            meta: { retryable: false },
+          }),
+      });
+
+      const error = await client.executeDeltaProposal(account, '0xproposal').catch((e) => e);
+      expect(error).toBeInstanceOf(GuardianHttpError);
+      expect(error.code).toBe('proposal_not_ready');
+      expect(error.rawCode).toBe('GUARDIAN_PROPOSAL_NOT_READY');
+    });
+  });
+
   describe('abandonCandidate', () => {
     it('should record an abandon intent and map the response to camelCase', async () => {
       client.setSigner(mockSigner);
@@ -663,16 +1019,18 @@ describe('GuardianHttpClient', () => {
           nonce: 7,
           state: 'pending',
           abandon_requested_at: '2026-07-14T12:00:00Z',
+          commitment: '0x' + 'c'.repeat(64),
         }),
       });
 
-      const result = await client.abandonCandidate('0x' + 'a'.repeat(30), 7);
+      const result = await client.abandonCandidate('0x' + 'a'.repeat(30), 7, '0x' + 'b'.repeat(64));
 
       expect(result).toEqual({
         accountId: '0x' + 'a'.repeat(30),
         nonce: 7,
         state: 'pending',
         abandonRequestedAt: '2026-07-14T12:00:00Z',
+        commitment: '0x' + 'c'.repeat(64),
       });
 
       // Wire format is snake_case
@@ -683,6 +1041,7 @@ describe('GuardianHttpClient', () => {
           body: JSON.stringify({
             account_id: '0x' + 'a'.repeat(30),
             nonce: 7,
+            proposal_id: '0x' + 'b'.repeat(64),
           }),
         })
       );
@@ -705,7 +1064,7 @@ describe('GuardianHttpClient', () => {
       });
 
       const error = await client
-        .abandonCandidate('0x' + 'a'.repeat(30), 7)
+        .abandonCandidate('0x' + 'a'.repeat(30), 7, '0x' + 'b'.repeat(64))
         .catch((e) => e);
       expect(error).toBeInstanceOf(GuardianHttpError);
       expect(error.status).toBe(409);
@@ -730,7 +1089,7 @@ describe('GuardianHttpClient', () => {
       });
 
       const error = await client
-        .abandonCandidate('0x' + 'a'.repeat(30), 7)
+        .abandonCandidate('0x' + 'a'.repeat(30), 7, '0x' + 'b'.repeat(64))
         .catch((e) => e);
       expect(error).toBeInstanceOf(GuardianHttpError);
       expect(error.status).toBe(404);
@@ -739,10 +1098,12 @@ describe('GuardianHttpClient', () => {
   });
 
   describe('abandonStatus', () => {
+    const abandoned = '0x' + 'c'.repeat(64);
     const serverDelta = (status: object) => ({
       account_id: '0x' + 'a'.repeat(30),
       nonce: 7,
       prev_commitment: '0x' + 'b'.repeat(64),
+      new_commitment: abandoned,
       delta_payload: { tx_summary: { data: 'base64summary' }, signatures: [] },
       status,
     });
@@ -754,7 +1115,7 @@ describe('GuardianHttpClient', () => {
         json: async () =>
           serverDelta({ status: 'candidate', timestamp: '2026-07-14T12:00:00Z' }),
       });
-      expect(await client.abandonStatus('0x' + 'a'.repeat(30), 7)).toBe('waiting');
+      expect(await client.abandonStatus('0x' + 'a'.repeat(30), 7, abandoned)).toBe('waiting');
     });
 
     it('classifies a canonicalized delta as landed', async () => {
@@ -764,7 +1125,19 @@ describe('GuardianHttpClient', () => {
         json: async () =>
           serverDelta({ status: 'canonical', timestamp: '2026-07-14T12:00:00Z' }),
       });
-      expect(await client.abandonStatus('0x' + 'a'.repeat(30), 7)).toBe('landed');
+      expect(await client.abandonStatus('0x' + 'a'.repeat(30), 7, abandoned)).toBe('landed');
+    });
+
+    it('compares commitments ignoring hex case', async () => {
+      client.setSigner(mockSigner);
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({
+          ...serverDelta({ status: 'canonical', timestamp: '2026-07-14T12:00:00Z' }),
+          new_commitment: abandoned.toUpperCase().replace('0X', '0x'),
+        }),
+      });
+      expect(await client.abandonStatus('0x' + 'a'.repeat(30), 7, abandoned)).toBe('landed');
     });
 
     it('classifies a retained delta as retained, not abandoned (issue #345)', async () => {
@@ -782,7 +1155,7 @@ describe('GuardianHttpClient', () => {
             reason: 'retry_exhausted',
           }),
       });
-      expect(await client.abandonStatus('0x' + 'a'.repeat(30), 7)).toBe('retained');
+      expect(await client.abandonStatus('0x' + 'a'.repeat(30), 7, abandoned)).toBe('retained');
     });
 
     it('classifies a client-abandoned discard as abandoned', async () => {
@@ -796,7 +1169,7 @@ describe('GuardianHttpClient', () => {
             reason: 'client_abandoned',
           }),
       });
-      expect(await client.abandonStatus('0x' + 'a'.repeat(30), 7)).toBe('abandoned');
+      expect(await client.abandonStatus('0x' + 'a'.repeat(30), 7, abandoned)).toBe('abandoned');
     });
 
     it('classifies a reasonless discard and a missing delta as unexpected', async () => {
@@ -806,7 +1179,7 @@ describe('GuardianHttpClient', () => {
         json: async () =>
           serverDelta({ status: 'discarded', timestamp: '2026-07-14T12:00:00Z' }),
       });
-      expect(await client.abandonStatus('0x' + 'a'.repeat(30), 7)).toBe('unexpected');
+      expect(await client.abandonStatus('0x' + 'a'.repeat(30), 7, abandoned)).toBe('unexpected');
 
       mockFetch.mockResolvedValueOnce({
         ok: false,
@@ -820,7 +1193,45 @@ describe('GuardianHttpClient', () => {
             meta: { retryable: false },
           }),
       });
-      expect(await client.abandonStatus('0x' + 'a'.repeat(30), 7)).toBe('unexpected');
+      expect(await client.abandonStatus('0x' + 'a'.repeat(30), 7, abandoned)).toBe('unexpected');
+    });
+
+    it('classifies another delta at the nonce by its status, never as landed', async () => {
+      // A Guardian execution archives the abandoned delta and takes its
+      // nonce: its canonical delta means the abandoned transaction can no
+      // longer land.
+      const successor = '0x' + 'd'.repeat(64);
+      client.setSigner(mockSigner);
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({
+          ...serverDelta({ status: 'canonical', timestamp: '2026-07-14T12:00:00Z' }),
+          new_commitment: successor,
+        }),
+      });
+      expect(await client.abandonStatus('0x' + 'a'.repeat(30), 7, abandoned)).toBe('abandoned');
+
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({
+          ...serverDelta({ status: 'candidate', timestamp: '2026-07-14T12:00:00Z' }),
+          new_commitment: successor,
+        }),
+      });
+      expect(await client.abandonStatus('0x' + 'a'.repeat(30), 7, abandoned)).toBe('waiting');
+
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({
+          ...serverDelta({
+            status: 'retained',
+            timestamp: '2026-07-14T12:00:00Z',
+            reason: 'retry_exhausted',
+          }),
+          new_commitment: successor,
+        }),
+      });
+      expect(await client.abandonStatus('0x' + 'a'.repeat(30), 7, abandoned)).toBe('unexpected');
     });
   });
 
@@ -1423,6 +1834,84 @@ describe('GuardianHttpError', () => {
       expect(e.meta?.allowedSchemes).toEqual(['ecdsa']);
     });
 
+    it('surfaces the blocking proposal of an execution conflict as meta.blockingProposalId', async () => {
+      client.setSigner(mockSigner);
+      const blocking = '0x' + 'b'.repeat(64);
+      mockFetch.mockResolvedValueOnce({
+        ok: false,
+        headers: new Headers(),
+        status: 409,
+        statusText: 'Conflict',
+        text: async () =>
+          JSON.stringify({
+            code: 'GUARDIAN_EXECUTION_CONFLICT',
+            message: 'Another proposal is executing on this account.',
+            meta: { retryable: false, blocking_proposal_id: blocking },
+          }),
+      });
+
+      const error = await client
+        .executeDeltaProposal('0x' + 'a'.repeat(30), '0x' + 'c'.repeat(64))
+        .catch((e) => e as GuardianHttpError);
+
+      expect(error).toBeInstanceOf(GuardianHttpError);
+      const e = error as GuardianHttpError;
+      expect(e.code).toBe('execution_conflict');
+      expect(e.isRetryable()).toBe(false);
+      expect(e.meta?.blockingProposalId).toBe(blocking);
+    });
+
+    it('surfaces a refused switch_guardian execution as proposal_executes_locally with meta.proposalType', async () => {
+      client.setSigner(mockSigner);
+      mockFetch.mockResolvedValueOnce({
+        ok: false,
+        headers: new Headers(),
+        status: 409,
+        statusText: 'Conflict',
+        text: async () =>
+          JSON.stringify({
+            code: 'GUARDIAN_PROPOSAL_EXECUTES_LOCALLY',
+            message: 'A guardian switch is executed by the wallet that finishes the handoff.',
+            meta: { retryable: false, proposal_type: 'switch_guardian', reason: 'switch_guardian' },
+          }),
+      });
+
+      const error = await client
+        .executeDeltaProposal('0x' + 'a'.repeat(30), '0x' + 'c'.repeat(64))
+        .catch((e) => e as GuardianHttpError);
+
+      expect(error).toBeInstanceOf(GuardianHttpError);
+      const e = error as GuardianHttpError;
+      expect(e.status).toBe(409);
+      expect(e.code).toBe('proposal_executes_locally');
+      expect(e.rawCode).toBe('GUARDIAN_PROPOSAL_EXECUTES_LOCALLY');
+      expect(e.isRetryable()).toBe(false);
+      expect(e.meta?.proposalType).toBe('switch_guardian');
+      expect(e.meta?.reason).toBe('switch_guardian');
+    });
+
+    it('drops a meta.reason outside the known vocabulary', async () => {
+      client.setSigner(mockSigner);
+      mockFetch.mockResolvedValueOnce({
+        ok: false,
+        headers: new Headers(),
+        status: 409,
+        statusText: 'Conflict',
+        text: async () =>
+          JSON.stringify({
+            code: 'GUARDIAN_PROPOSAL_EXECUTES_LOCALLY',
+            message: 'Execute it from your wallet instead.',
+            meta: { retryable: false, proposal_type: 'p2id', reason: 'private_note' },
+          }),
+      });
+
+      const e = (await client
+        .executeDeltaProposal('0x' + 'a'.repeat(30), '0x' + 'c'.repeat(64))
+        .catch((error) => error)) as GuardianHttpError;
+
+      expect(e.meta?.reason).toBeUndefined();
+    });
+
     it('omits meta.allowedSchemes rather than exposing a partial list when an element is malformed', async () => {
       client.setSigner(mockSigner);
       mockFetch.mockResolvedValueOnce({
@@ -1647,8 +2136,13 @@ describe('GuardianHttpClient sessions', () => {
   let session: SessionRequestSigner;
 
   function sessionExpiringIn(seconds: number): SessionRequestSigner {
+    const timestamps = new SessionTimestamps();
     return {
       publicKey: sessionPublicKey,
+      nextTimestamp: vi.fn((accountId: string, afterReplay: boolean) =>
+        timestamps.next(accountId, afterReplay)
+      ),
+      writeSequencer: new WriteSequencer(),
       signerCommitment: mockSigner.commitment,
       expiresAt: Math.floor(Date.now() / 1000) + seconds,
       signRequest: vi.fn().mockReturnValue('0x' + 'd'.repeat(128)),
@@ -1688,11 +2182,14 @@ describe('GuardianHttpClient sessions', () => {
     const calls: Array<[string, () => Promise<unknown>]> = [
       ['getState', () => client.getState(accountId)],
       ['getCanonicalNonce', () => client.getCanonicalNonce(accountId)],
+      ['getStateTail', () => client.getStateTail(accountId)],
       ['getDelta', () => client.getDelta(accountId, 1)],
       ['getDeltaSince', () => client.getDeltaSince(accountId, 1)],
       ['getDeltaHistory', () => client.getDeltaHistory(accountId)],
       ['getDeltaProposals', () => client.getDeltaProposals(accountId)],
       ['getDeltaProposal', () => client.getDeltaProposal(accountId, '0x' + 'e'.repeat(64))],
+      ['getDeltaProposalExecution', () => client.getDeltaProposalExecution(accountId, '0xproposal')],
+      ['getCurrentExecution', () => client.getCurrentExecution(accountId)],
       [
         'pushDeltaProposal',
         () =>
@@ -1717,10 +2214,26 @@ describe('GuardianHttpClient sessions', () => {
       // Only the request headers matter; the empty body may fail to parse.
       mockFetch.mockResolvedValueOnce({ ok: true, json: async () => ({}) });
       await call().catch(() => undefined);
-      expect(lastHeaders()['x-auth-format'], name).toBe('session');
+      expect(lastHeaders()['x-auth-format'], name).toBe('session-v2');
       expect(lastHeaders()['x-pubkey'], name).toBe(sessionPublicKey);
     }
     expect(session.signRequest).toHaveBeenCalledTimes(calls.length);
+    expect(session.nextTimestamp).toHaveBeenCalledTimes(calls.length);
+    expect(vi.mocked(session.nextTimestamp).mock.calls.every(([id]) => id === accountId)).toBe(true);
+    expect(vi.mocked(session.signRequest).mock.calls.map(([operation]) => operation)).toEqual([
+      SessionOperation.GetState,
+      SessionOperation.GetCanonicalNonce,
+      SessionOperation.GetStateTail,
+      SessionOperation.GetDelta,
+      SessionOperation.GetDeltaSince,
+      SessionOperation.GetDeltaHistory,
+      SessionOperation.GetDeltaProposals,
+      SessionOperation.GetDeltaProposal,
+      SessionOperation.GetDeltaProposalExecution,
+      SessionOperation.GetCurrentExecution,
+      SessionOperation.PushDeltaProposal,
+      SessionOperation.SignDeltaProposal,
+    ]);
     expect(mockSigner.signRequest).not.toHaveBeenCalled();
   });
 
@@ -1750,12 +2263,41 @@ describe('GuardianHttpClient sessions', () => {
 
     expect(mockFetch).toHaveBeenCalledTimes(2);
     const [first, second] = mockFetch.mock.calls.map(([, init]) => init.headers);
-    expect(second['x-auth-format']).toBe('session');
+    expect(second['x-auth-format']).toBe('session-v2');
     expect(second['x-timestamp']).not.toBe(first['x-timestamp']);
     expect(session.signRequest).toHaveBeenCalledTimes(2);
     expect(client.getSession()).toBe(session);
   });
 
+  it('re-signs a push with the wallet when Guardian takes it only from the wallet', async () => {
+    client.setSession(session);
+    rejectWith('wallet_signature_required', 403);
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      json: async () => ({
+        account_id: '0xabc',
+        nonce: 1,
+        new_commitment: '0x' + 'd'.repeat(64),
+        ack_sig: '0x' + 'f'.repeat(128),
+      }),
+    });
+
+    const result = await client.pushDelta({
+      accountId: '0xabc',
+      nonce: 1,
+      prevCommitment: '0x' + 'b'.repeat(64),
+      deltaPayload: { data: 'AAAA' },
+      status: { status: 'pending', timestamp: '2026-01-01T00:00:00Z', proposerId: '0x01', cosignerSigs: [] },
+    });
+
+    expect(result.ackSig).toBe('0x' + 'f'.repeat(128));
+    const [first, second] = mockFetch.mock.calls.map(([, init]) => init.headers);
+    expect(first['x-auth-format']).toBe('session-v2');
+    expect(second['x-pubkey']).toBe(mockSigner.publicKey);
+    expect(client.getSession()).toBe(session);
+    expect(session.onEnded).not.toHaveBeenCalled();
+  });
+
   it('does not use a session granted by another wallet', async () => {
     client.setSession({ ...session, signerCommitment: '0x' + '9'.repeat(64) });
     expect(client.getSession()).toBeNull();
@@ -1777,7 +2319,7 @@ describe('GuardianHttpClient sessions', () => {
     expect(lastHeaders()).toMatchObject({
       'x-pubkey': sessionPublicKey,
       'x-signature': '0x' + 'd'.repeat(128),
-      'x-auth-format': 'session',
+      'x-auth-format': 'session-v2',
     });
     expect(session.signRequest).toHaveBeenCalledOnce();
     expect(mockSigner.signRequest).not.toHaveBeenCalled();
@@ -1801,7 +2343,44 @@ describe('GuardianHttpClient sessions', () => {
     expect(session.signRequest).not.toHaveBeenCalled();
   });
 
-  it('keeps pushDelta and abandonCandidate on the wallet while a session is set', async () => {
+  it('signs the execution request and its status reads with the session', async () => {
+    client.setSession(session);
+    const execution = {
+      account_id: '0xabc',
+      proposal_id: '0xproposal',
+      state: 'pending',
+      newly_accepted: true,
+      proposal_exists: true,
+      ignored_signatures: 0,
+      updated_at: '2026-09-30T12:00:00Z',
+    };
+    mockFetch
+      .mockResolvedValueOnce({ ok: true, json: async () => execution })
+      .mockResolvedValueOnce({ ok: true, json: async () => execution })
+      .mockResolvedValueOnce({ ok: true, json: async () => ({ execution }) });
+
+    await client.executeDeltaProposal('0xabc', '0xproposal');
+    expect(lastHeaders()['x-auth-format']).toBe('session-v2');
+    expect(vi.mocked(session.signRequest).mock.calls[0][0]).toBe(
+      SessionOperation.ExecuteDeltaProposal
+    );
+    expect(vi.mocked(session.signRequest).mock.calls[0][3].toBytes()).toEqual(
+      RequestAuthPayload.forOperation('ExecuteDeltaProposal', {
+        account_id: '0xabc',
+        proposal_id: '0xproposal',
+      }).toBytes(),
+    );
+
+    await client.getDeltaProposalExecution('0xabc', '0xproposal');
+    expect(lastHeaders()['x-auth-format']).toBe('session-v2');
+    await client.getCurrentExecution('0xabc');
+    expect(lastHeaders()['x-auth-format']).toBe('session-v2');
+
+    expect(mockSigner.signRequest).not.toHaveBeenCalled();
+    expect(session.signRequest).toHaveBeenCalledTimes(3);
+  });
+
+  it('signs pushDelta with the session and keeps abandonCandidate on the wallet', async () => {
     client.setSession(session);
     mockFetch.mockResolvedValueOnce({
       ok: true,
@@ -1827,8 +2406,11 @@ describe('GuardianHttpClient sessions', () => {
         cosignerSigs: [],
       },
     });
-    expect(lastHeaders()['x-pubkey']).toBe(mockSigner.publicKey);
-    expect(lastHeaders()['x-auth-format']).toBeUndefined();
+    expect(lastHeaders()).toMatchObject({
+      'x-pubkey': sessionPublicKey,
+      'x-auth-format': 'session-v2',
+    });
+    expect(session.signRequest).toHaveBeenCalledOnce();
 
     mockFetch.mockResolvedValueOnce({
       ok: true,
@@ -1837,12 +2419,13 @@ describe('GuardianHttpClient sessions', () => {
         nonce: 1,
         state: 'abandon_requested',
         abandon_requested_at: '2024-01-01T00:00:00Z',
+        commitment: '0x' + 'd'.repeat(64),
       }),
     });
-    await client.abandonCandidate('0xabc', 1);
+    await client.abandonCandidate('0xabc', 1, '0x' + 'b'.repeat(64));
     expect(lastHeaders()['x-pubkey']).toBe(mockSigner.publicKey);
     expect(lastHeaders()['x-auth-format']).toBeUndefined();
-    expect(session.signRequest).not.toHaveBeenCalled();
+    expect(session.signRequest).toHaveBeenCalledOnce();
   });
 
   it('revokes every session with a wallet signature and stops using the session', async () => {
@@ -1942,6 +2525,18 @@ describe('GuardianHttpClient sessions', () => {
     expect(session.onEnded).not.toHaveBeenCalled();
   });
 
+  it('keeps the session when the device clock is outside the timestamp window', async () => {
+    client.setSession(session);
+    rejectWith('timestamp_out_of_window');
+
+    await expect(client.getState('0xabc')).rejects.toMatchObject({
+      code: 'timestamp_out_of_window',
+    });
+    expect(client.getSession()).toBe(session);
+    expect(session.onEnded).not.toHaveBeenCalled();
+    expect(mockFetch).toHaveBeenCalledTimes(1);
+  });
+
   it('a late rejection of an old session ends it but leaves the new one in use', async () => {
     client.setSession(session);
     let respond!: (value: unknown) => void;
@@ -1990,10 +2585,143 @@ describe('GuardianHttpClient sessions', () => {
     expect(lastHeaders()['x-auth-format']).toBeUndefined();
   });
 
+  it('sends a session write to an account only after the previous one finished', async () => {
+    client.setSession(session);
+    let releaseFirst!: () => void;
+    const delta = {
+      account_id: '0xabc',
+      nonce: 1,
+      status: { status: 'pending', timestamp: '2026-01-01T00:00:00Z', proposer_id: '0x1', cosigner_sigs: [] },
+      delta_payload: {},
+      prev_commitment: '0x00',
+    };
+    mockFetch
+      .mockImplementationOnce(
+        () =>
+          new Promise((resolve) => {
+            releaseFirst = () => resolve({ ok: true, json: async () => ({ delta, commitment: '0x1' }) });
+          })
+      )
+      .mockResolvedValueOnce({ ok: true, json: async () => ({ delta, commitment: '0x2' }) });
+    const proposal = { accountId: '0xabc', nonce: 1, deltaPayload: { txSummary: { data: 'AAAA' }, signatures: [] } };
+
+    const first = client.pushDeltaProposal(proposal).catch(() => undefined);
+    const second = client.pushDeltaProposal(proposal).catch(() => undefined);
+    await new Promise((resolve) => setTimeout(resolve, 20));
+    expect(mockFetch).toHaveBeenCalledTimes(1);
+
+    releaseFirst();
+    await Promise.all([first, second]);
+    expect(mockFetch).toHaveBeenCalledTimes(2);
+    const [firstTimestamp, secondTimestamp] = mockFetch.mock.calls.map(
+      ([, init]) => Number(init.headers['x-timestamp'])
+    );
+    expect(secondTimestamp).toBeGreaterThan(firstTimestamp);
+  });
+
+  it('moves a write queued on a replaced session into the new session\'s turn', async () => {
+    const replacement = { ...sessionExpiringIn(3600), publicKey: '0x03' + 'f'.repeat(64) };
+    client.setSession(session);
+    const delta = {
+      account_id: '0xabc',
+      nonce: 1,
+      status: { status: 'pending', timestamp: '2026-01-01T00:00:00Z', proposer_id: '0x1', cosigner_sigs: [] },
+      delta_payload: {},
+      prev_commitment: '0x00',
+    };
+    const done = { ok: true, json: async () => ({ delta, commitment: '0x1' }) };
+    const releases: Array<() => void> = [];
+    mockFetch.mockImplementation(
+      () => new Promise((resolve) => releases.push(() => resolve(done)))
+    );
+    const proposal = { accountId: '0xabc', nonce: 1, deltaPayload: { txSummary: { data: 'AAAA' }, signatures: [] } };
+    const settle = () => new Promise((resolve) => setTimeout(resolve, 20));
+
+    const first = client.pushDeltaProposal(proposal).catch(() => undefined);
+    const queued = client.pushDeltaProposal(proposal).catch(() => undefined);
+    await settle();
+    client.setSession(replacement);
+    const onReplacement = client.pushDeltaProposal(proposal).catch(() => undefined);
+    await settle();
+    expect(mockFetch).toHaveBeenCalledTimes(2);
+
+    releases[0]();
+    await settle();
+    expect(mockFetch).toHaveBeenCalledTimes(2);
+
+    releases[1]();
+    await settle();
+    expect(mockFetch).toHaveBeenCalledTimes(3);
+    releases[2]();
+    await Promise.all([first, queued, onReplacement]);
+    expect(mockFetch.mock.calls.map(([, init]) => init.headers['x-pubkey'])).toEqual([
+      sessionPublicKey,
+      replacement.publicKey,
+      replacement.publicKey,
+    ]);
+    expect(session.signRequest).toHaveBeenCalledTimes(1);
+    mockFetch.mockReset();
+  });
+
+  it('does not order session reads', async () => {
+    client.setSession(session);
+    mockFetch.mockImplementation(() => new Promise(() => undefined));
+    void client.getState('0xabc');
+    void client.getState('0xabc');
+    await new Promise((resolve) => setTimeout(resolve, 20));
+    expect(mockFetch).toHaveBeenCalledTimes(2);
+    mockFetch.mockReset();
+  });
+
+  it('refuses a Guardian that does not report session request version 2', async () => {
+    for (const body of [
+      { signer_commitment: '0x11', expires_at: '2026-10-06T18:00:00+00:00' },
+      {
+        signer_commitment: '0x11',
+        expires_at: '2026-10-06T18:00:00+00:00',
+        request_auth_version: 3,
+      },
+    ]) {
+      mockFetch.mockResolvedValueOnce({ ok: true, json: async () => body });
+      await expect(
+        client.createSession({
+          scheme: 'falcon',
+          signature: '0x00',
+          grant: {
+            signerCommitment: '0x11',
+            sessionPublicKey: sessionPublicKey,
+            origin: '',
+            issuedAt: 0,
+            expiresAt: 1,
+            guardianCommitment: '0x22',
+            network: 'devnet',
+          },
+        })
+      ).rejects.toBeInstanceOf(UnsupportedAuthVersionError);
+    }
+  });
+
+  it('keeps the session and does not retry when Guardian refuses its request format', async () => {
+    client.setSession(session);
+    rejectWith('unsupported_auth_version', 400);
+
+    const error = await client.getState('0xabc').catch((err: unknown) => err);
+
+    expect(error).toBeInstanceOf(GuardianHttpError);
+    expect((error as GuardianHttpError).code).toBe('unsupported_auth_version');
+    expect(mockFetch).toHaveBeenCalledTimes(1);
+    expect(client.getSession()).toBe(session);
+    expect(session.onEnded).not.toHaveBeenCalled();
+  });
+
   it('posts a session grant in the server shape', async () => {
     mockFetch.mockResolvedValueOnce({
       ok: true,
-      json: async () => ({ signer_commitment: '0x11', expires_at: '2026-10-06T18:00:00+00:00' }),
+      json: async () => ({
+        signer_commitment: '0x11',
+        expires_at: '2026-10-06T18:00:00+00:00',
+        request_auth_version: 2,
+      }),
     });
 
     const created = await client.createSession({
@@ -2012,7 +2740,11 @@ describe('GuardianHttpClient sessions', () => {
       },
     });
 
-    expect(created).toEqual({ signerCommitment: '0x11', expiresAt: '2026-10-06T18:00:00+00:00' });
+    expect(created).toEqual({
+      signerCommitment: '0x11',
+      expiresAt: '2026-10-06T18:00:00+00:00',
+      requestAuthVersion: 2,
+    });
     const [url, init] = mockFetch.mock.calls[0];
     expect(url).toBe('http://localhost:3000/session');
     expect(init.method).toBe('POST');
@@ -2083,6 +2815,7 @@ describe('GuardianHttpClient sessions', () => {
         environment: 'devnet',
         started_at: '2026-10-06T00:00:00Z',
         uptime_seconds: 1,
+        execution: { enabled: true },
         sessions: { max_ttl_seconds: 28800 },
       }),
     });