@openzeppelin/guardian-client 0.15.2 → 0.16.1

package/src/http.test.ts

@@ -81,18 +81,17 @@ describe('GuardianHttpClient', () => {
         statusText: 'Conflict',
         text: async () =>
           JSON.stringify({
-            success: false,
             code: 'GUARDIAN_ACCOUNT_RELEASED',
-            error: 'Account was released',
-            retryable: false,
-            released_at: '2026-07-06T10:00:00Z',
+            message: 'This account has moved to a different guardian. Reconnect it to continue.',
+            meta: { retryable: false, released_at: '2026-07-06T10:00:00Z' },
           }),
       });
 
       const error = await client.getPubkey().catch((e) => e);
       expect(error).toBeInstanceOf(GuardianHttpError);
       expect(error.status).toBe(409);
-      expect(error.code).toBe('GUARDIAN_ACCOUNT_RELEASED');
+      expect(error.code).toBe('account_released');
+      expect(error.rawCode).toBe('GUARDIAN_ACCOUNT_RELEASED');
       expect(error.releasedAt).toBe('2026-07-06T10:00:00Z');
     });
 
@@ -103,9 +102,9 @@ describe('GuardianHttpClient', () => {
         statusText: 'Not Found',
         text: async () =>
           JSON.stringify({
-            success: false,
             code: 'account_not_found',
-            error: "Account '0xabc' not found",
+            message: "We couldn't find that. It may have been completed or removed.",
+            meta: { retryable: false },
           }),
       });
 
@@ -457,6 +456,175 @@ describe('GuardianHttpClient', () => {
     });
   });
 
+  describe('abandonCandidate', () => {
+    it('should record an abandon intent and map the response to camelCase', async () => {
+      client.setSigner(mockSigner);
+
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({
+          account_id: '0x' + 'a'.repeat(30),
+          nonce: 7,
+          state: 'pending',
+          abandon_requested_at: '2026-07-14T12:00:00Z',
+        }),
+      });
+
+      const result = await client.abandonCandidate('0x' + 'a'.repeat(30), 7);
+
+      expect(result).toEqual({
+        accountId: '0x' + 'a'.repeat(30),
+        nonce: 7,
+        state: 'pending',
+        abandonRequestedAt: '2026-07-14T12:00:00Z',
+      });
+
+      // Wire format is snake_case
+      expect(mockFetch).toHaveBeenCalledWith(
+        'http://localhost:3000/delta/candidate/abandon',
+        expect.objectContaining({
+          method: 'POST',
+          body: JSON.stringify({
+            account_id: '0x' + 'a'.repeat(30),
+            nonce: 7,
+          }),
+        })
+      );
+    });
+
+    it('surfaces 409 GUARDIAN_CANDIDATE_LANDED with a parseable error envelope', async () => {
+      client.setSigner(mockSigner);
+
+      mockFetch.mockResolvedValueOnce({
+        ok: false,
+        status: 409,
+        statusText: 'Conflict',
+        text: async () =>
+          JSON.stringify({
+            code: 'GUARDIAN_CANDIDATE_LANDED',
+            message: "This transaction already went through, so it can't be abandoned.",
+            meta: { retryable: false },
+          }),
+      });
+
+      const error = await client
+        .abandonCandidate('0x' + 'a'.repeat(30), 7)
+        .catch((e) => e);
+      expect(error).toBeInstanceOf(GuardianHttpError);
+      expect(error.status).toBe(409);
+      expect(error.code).toBe('candidate_landed');
+      expect(error.rawCode).toBe('GUARDIAN_CANDIDATE_LANDED');
+    });
+
+    it('surfaces 404 delta_not_found when no candidate exists at the nonce', async () => {
+      client.setSigner(mockSigner);
+
+      mockFetch.mockResolvedValueOnce({
+        ok: false,
+        status: 404,
+        statusText: 'Not Found',
+        text: async () =>
+          JSON.stringify({
+            code: 'delta_not_found',
+            message: "We couldn't find that. It may have been completed or removed.",
+            meta: { retryable: false },
+          }),
+      });
+
+      const error = await client
+        .abandonCandidate('0x' + 'a'.repeat(30), 7)
+        .catch((e) => e);
+      expect(error).toBeInstanceOf(GuardianHttpError);
+      expect(error.status).toBe(404);
+      expect(error.code).toBe('delta_not_found');
+    });
+  });
+
+  describe('abandonStatus', () => {
+    const serverDelta = (status: object) => ({
+      account_id: '0x' + 'a'.repeat(30),
+      nonce: 7,
+      prev_commitment: '0x' + 'b'.repeat(64),
+      delta_payload: { tx_summary: { data: 'base64summary' }, signatures: [] },
+      status,
+    });
+
+    it('classifies a still-pending candidate as waiting', async () => {
+      client.setSigner(mockSigner);
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: async () =>
+          serverDelta({ status: 'candidate', timestamp: '2026-07-14T12:00:00Z' }),
+      });
+      expect(await client.abandonStatus('0x' + 'a'.repeat(30), 7)).toBe('waiting');
+    });
+
+    it('classifies a canonicalized delta as landed', async () => {
+      client.setSigner(mockSigner);
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: async () =>
+          serverDelta({ status: 'canonical', timestamp: '2026-07-14T12:00:00Z' }),
+      });
+      expect(await client.abandonStatus('0x' + 'a'.repeat(30), 7)).toBe('landed');
+    });
+
+    it('classifies a retained delta as retained, not abandoned (issue #345)', async () => {
+      // The Guardian gave up verifying and released the account, but the
+      // on-chain outcome is still uncertain: 'retained' means "unlocked
+      // but unresolved" — reporting it as 'abandoned' would wrongly
+      // imply the transaction definitively did not land.
+      client.setSigner(mockSigner);
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: async () =>
+          serverDelta({
+            status: 'retained',
+            timestamp: '2026-07-14T12:00:00Z',
+            reason: 'retry_exhausted',
+          }),
+      });
+      expect(await client.abandonStatus('0x' + 'a'.repeat(30), 7)).toBe('retained');
+    });
+
+    it('classifies a client-abandoned discard as abandoned', async () => {
+      client.setSigner(mockSigner);
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: async () =>
+          serverDelta({
+            status: 'discarded',
+            timestamp: '2026-07-14T12:00:00Z',
+            reason: 'client_abandoned',
+          }),
+      });
+      expect(await client.abandonStatus('0x' + 'a'.repeat(30), 7)).toBe('abandoned');
+    });
+
+    it('classifies a reasonless discard and a missing delta as unexpected', async () => {
+      client.setSigner(mockSigner);
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: async () =>
+          serverDelta({ status: 'discarded', timestamp: '2026-07-14T12:00:00Z' }),
+      });
+      expect(await client.abandonStatus('0x' + 'a'.repeat(30), 7)).toBe('unexpected');
+
+      mockFetch.mockResolvedValueOnce({
+        ok: false,
+        status: 404,
+        statusText: 'Not Found',
+        text: async () =>
+          JSON.stringify({
+            code: 'delta_not_found',
+            message: "We couldn't find that. It may have been completed or removed.",
+            meta: { retryable: false },
+          }),
+      });
+      expect(await client.abandonStatus('0x' + 'a'.repeat(30), 7)).toBe('unexpected');
+    });
+  });
+
   describe('signDeltaProposal', () => {
     it('should sign a delta proposal', async () => {
       client.setSigner(mockSigner);
@@ -825,6 +993,27 @@ describe('GuardianHttpError', () => {
     expect(error.name).toBe('GuardianHttpError');
   });
 
+  it('parses a { code, message, meta } body into structured accessors (feature 009)', () => {
+    const body = JSON.stringify({
+      code: 'rate_limit_exceeded',
+      message: 'Too many requests — please try again shortly.',
+      meta: { retryable: true, retry_after_secs: 30 },
+    });
+    const error = new GuardianHttpError(429, 'Too Many Requests', body);
+    expect(error.code).toBe('rate_limit_exceeded');
+    expect(error.userMessage).toBe('Too many requests — please try again shortly.');
+    expect(error.meta?.retryable).toBe(true);
+    expect(error.meta?.retryAfterSecs).toBe(30); // snake_case → camelCase
+  });
+
+  it('leaves accessors undefined for a non-JSON / non-conforming body', () => {
+    const plain = new GuardianHttpError(502, 'Bad Gateway', 'upstream exploded');
+    expect(plain.code).toBeNull();
+    expect(plain.releasedAt).toBeNull();
+    expect(plain.userMessage).toBeUndefined();
+    expect(plain.meta).toBeUndefined();
+  });
+
   describe('error envelope contract (account-paused path)', () => {
     let client: GuardianHttpClient;
     beforeEach(() => {
@@ -835,15 +1024,18 @@ describe('GuardianHttpError', () => {
     it('surfaces 409 GUARDIAN_ACCOUNT_PAUSED with a parseable error envelope on pushDeltaProposal', async () => {
       client.setSigner(mockSigner);
 
-      // The server's GuardianError::AccountPaused → IntoResponse contract.
-      // Locks client/server in lockstep: a regression to the legacy
+      // The server's GuardianError::AccountPaused → IntoResponse contract,
+      // reshaped to { code, message, meta } (feature 009). Locks client/server
+      // in lockstep: a regression to the legacy { success, error, paused_* } or
       // "(400, {delta: {account_id: 'error text'}})" shape would break this.
       const envelope = {
-        success: false,
         code: 'GUARDIAN_ACCOUNT_PAUSED',
-        error: 'Account is paused: compliance review',
-        paused_at: '2026-05-20T10:00:00Z',
-        paused_reason: 'compliance review',
+        message: "This account is paused and can't approve transactions right now.",
+        meta: {
+          retryable: false,
+          paused_at: '2026-05-20T10:00:00Z',
+          paused_reason: 'compliance review',
+        },
       };
 
       mockFetch.mockResolvedValueOnce({
@@ -864,26 +1056,37 @@ describe('GuardianHttpError', () => {
         .catch((e) => e as GuardianHttpError);
 
       expect(error).toBeInstanceOf(GuardianHttpError);
-      expect((error as GuardianHttpError).status).toBe(409);
-
-      const parsed = JSON.parse((error as GuardianHttpError).body);
-      expect(parsed.success).toBe(false);
-      expect(parsed.code).toBe('GUARDIAN_ACCOUNT_PAUSED');
-      expect(typeof parsed.error).toBe('string');
-      expect(parsed.paused_at).toBe('2026-05-20T10:00:00Z');
-      expect(parsed.paused_reason).toBe('compliance review');
-      // Negative assertion: legacy "stuff error into delta.account_id" shape.
+      const e = error as GuardianHttpError;
+      expect(e.status).toBe(409);
+
+      // Structured accessors parsed from { code, message, meta } (feature 009).
+      expect(e.code).toBe('account_paused');
+      expect(e.rawCode).toBe('GUARDIAN_ACCOUNT_PAUSED');
+      expect(typeof e.userMessage).toBe('string');
+      expect(e.userMessage).not.toContain('compliance review'); // sanitized
+      expect(e.meta?.retryable).toBe(false);
+      expect(e.meta?.pausedAt).toBe('2026-05-20T10:00:00Z');
+      expect(e.meta?.pausedReason).toBe('compliance review');
+
+      const parsed = JSON.parse(e.body);
+      // Legacy fields gone; not a domain object.
+      expect(parsed.success).toBeUndefined();
+      expect(parsed.error).toBeUndefined();
       expect(parsed.delta).toBeUndefined();
     });
 
     it('surfaces 401 AUTHENTICATION_FAILED with a parseable error envelope', async () => {
       client.setSigner(mockSigner);
       const envelope = {
-        success: false,
         code: 'authentication_failed',
-        error: 'Invalid signature',
+        message: 'Your session has expired. Please sign in again.',
+        meta: { retryable: false },
       };
-      mockFetch.mockResolvedValueOnce({
+      // `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,
         status: 401,
         statusText: 'Unauthorized',
@@ -899,10 +1102,12 @@ describe('GuardianHttpError', () => {
         .catch((e) => e as GuardianHttpError);
 
       expect(error).toBeInstanceOf(GuardianHttpError);
-      expect((error as GuardianHttpError).status).toBe(401);
-      const parsed = JSON.parse((error as GuardianHttpError).body);
-      expect(parsed.success).toBe(false);
-      expect(parsed.code).toBe('authentication_failed');
+      const e = error as GuardianHttpError;
+      expect(e.status).toBe(401);
+      expect(e.code).toBe('authentication_failed');
+      expect(typeof e.userMessage).toBe('string');
+      const parsed = JSON.parse(e.body);
+      expect(parsed.success).toBeUndefined();
       expect(parsed.delta).toBeUndefined();
     });
   });

package/src/http.ts

@@ -1,4 +1,10 @@
+import {
+  type GuardianErrorCode,
+  normalizeGuardianErrorCode,
+} from './error-codes.js';
 import type {
+  AbandonCandidateResponse,
+  AbandonStatus,
   ConfigureRequest,
   ConfigureResponse,
   DeltaObject,
@@ -16,6 +22,8 @@ import type {
 } from './types.js';
 import { RequestAuthPayload } from './auth-request.js';
 import type {
+  ServerAbandonCandidateRequest,
+  ServerAbandonCandidateResponse,
   ServerDeltaObject,
   ServerDeltaProposalResponse,
   ServerLookupResponse,
@@ -38,21 +46,105 @@ import {
 } from './conversion.js';
 
 /**
- * Error thrown by the GUARDIAN HTTP client.
+ * Structured machine-readable side-data on a GUARDIAN error
+ * (feature `009-human-readable-errors`). `retryable` is always present.
+ */
+export interface GuardianErrorMeta {
+  retryable: boolean;
+  retryAfterSecs?: number;
+  missingPermissions?: string[];
+  pausedAt?: string;
+  pausedReason?: string | null;
+  releasedAt?: string;
+}
+
+interface ParsedGuardianError {
+  /** Typed code, or `null` when the wire code is outside the known vocabulary. */
+  code: GuardianErrorCode | null;
+  /** Verbatim wire code, kept even when it does not narrow to the union. */
+  rawCode: string;
+  message: string;
+  meta: GuardianErrorMeta;
+}
+
+/**
+ * Parse a GUARDIAN error body `{ code, message, meta }` (feature 009),
+ * mapping the server's snake_case `meta` fields to camelCase. Returns
+ * `undefined` for non-JSON or non-conforming bodies — including a missing
+ * `meta` or a non-boolean `meta.retryable`, which the contract requires;
+ * treating those as conforming would silently misclassify retryability for
+ * bodies from older servers or intermediary proxies.
+ */
+function parseGuardianErrorBody(body: string): ParsedGuardianError | undefined {
+  let json: unknown;
+  try {
+    json = JSON.parse(body);
+  } catch {
+    return undefined;
+  }
+  if (typeof json !== 'object' || json === null) return undefined;
+  const obj = json as Record<string, unknown>;
+  if (typeof obj.code !== 'string' || typeof obj.message !== 'string') return undefined;
+
+  if (typeof obj.meta !== 'object' || obj.meta === null || Array.isArray(obj.meta)) {
+    return undefined;
+  }
+  const rawMeta = obj.meta as Record<string, unknown>;
+  if (typeof rawMeta.retryable !== 'boolean') return undefined;
+  const code = normalizeGuardianErrorCode(obj.code);
+  const meta: GuardianErrorMeta = { retryable: rawMeta.retryable };
+  if (
+    typeof rawMeta.retry_after_secs === 'number' &&
+    Number.isInteger(rawMeta.retry_after_secs) &&
+    rawMeta.retry_after_secs >= 0
+  ) {
+    meta.retryAfterSecs = rawMeta.retry_after_secs;
+  }
+  if (Array.isArray(rawMeta.missing_permissions)) {
+    meta.missingPermissions = rawMeta.missing_permissions.filter(
+      (x): x is string => typeof x === 'string'
+    );
+  }
+  if (typeof rawMeta.paused_at === 'string') meta.pausedAt = rawMeta.paused_at;
+  if (typeof rawMeta.released_at === 'string') meta.releasedAt = rawMeta.released_at;
+  if (typeof rawMeta.paused_reason === 'string' || rawMeta.paused_reason === null) {
+    meta.pausedReason = rawMeta.paused_reason as string | null;
+  }
+  return { code, rawCode: obj.code, message: obj.message, meta };
+}
+
+/**
+ * Error thrown by the GUARDIAN HTTP client. Parses the `{ code, message, meta }`
+ * error body (feature 009): branch on {@link code}, display {@link userMessage}.
  */
 export class GuardianHttpError extends Error {
   /**
-   * Stable machine-readable error code from the server's JSON error
-   * envelope (e.g. `GUARDIAN_ACCOUNT_RELEASED`, `GUARDIAN_ACCOUNT_PAUSED`,
-   * `commitment_mismatch`), or `null` when the body is not a JSON
-   * envelope. Callers SHOULD branch on this rather than on `body` text
-   * or the HTTP status alone.
+   * Typed, compiler-checked Guardian error code (issue #318), normalized to
+   * snake_case (e.g. `account_paused`, `account_released`,
+   * `commitment_mismatch`). `null` when the body is not a conforming JSON
+   * envelope OR the server emitted a code outside this client's known
+   * vocabulary — in the latter case {@link rawCode} still carries the
+   * verbatim wire string. Branch on this rather than on `body` text or the
+   * HTTP status alone; comparing against a non-member literal is a type
+   * error, so typos are caught at compile time.
    */
-  public readonly code: string | null;
+  public readonly code: GuardianErrorCode | null;
+  /**
+   * Verbatim wire code as the server sent it (e.g.
+   * `GUARDIAN_ACCOUNT_PAUSED`), including codes a newer server may emit
+   * that this client does not know. `null` only when the body carried no
+   * conforming envelope. For logging/telemetry; branch on {@link code}.
+   */
+  public readonly rawCode: string | null;
+  /** Short, user-safe message — safe to display verbatim in a wallet UI. */
+  readonly userMessage?: string;
+  /** Structured side-data (`retryable`, `retryAfterSecs`, …). */
+  readonly meta?: GuardianErrorMeta;
   /**
    * RFC 3339 UTC timestamp at which the guardian released the account
-   * after it switched to a different guardian. Present only when
-   * `code === 'GUARDIAN_ACCOUNT_RELEASED'` (HTTP 409); the account is
+   * after it switched to a different guardian. Convenience accessor for
+   * `meta.releasedAt`; present only when `code === 'account_released'`
+   * (wire form `GUARDIAN_ACCOUNT_RELEASED`, HTTP 409); the account is
    * terminal on this server until re-onboarded via `configure`.
    */
   public readonly releasedAt: string | null;
@@ -62,26 +154,17 @@ export class GuardianHttpError extends Error {
     public readonly statusText: string,
     public readonly body: string
   ) {
-    super(`GUARDIAN HTTP error ${status}: ${statusText} - ${body}`);
+    // Only the parsed, user-safe message is folded into Error.message; the
+    // raw body (which may carry backend/proxy internals) stays on the `body`
+    // field for diagnostics only.
+    const parsed = parseGuardianErrorBody(body);
+    super(`GUARDIAN HTTP error ${status}: ${statusText}${parsed ? ` - ${parsed.message}` : ''}`);
     this.name = 'GuardianHttpError';
-    let code: string | null = null;
-    let releasedAt: string | null = null;
-    try {
-      const parsed: unknown = JSON.parse(body);
-      if (parsed !== null && typeof parsed === 'object') {
-        const record = parsed as Record<string, unknown>;
-        if (typeof record['code'] === 'string') {
-          code = record['code'];
-        }
-        if (typeof record['released_at'] === 'string') {
-          releasedAt = record['released_at'];
-        }
-      }
-    } catch {
-      // Non-JSON body (e.g. proxy HTML error page): keep raw `body` only.
-    }
-    this.code = code;
-    this.releasedAt = releasedAt;
+    this.code = parsed?.code ?? null;
+    this.rawCode = parsed?.rawCode ?? null;
+    this.userMessage = parsed?.message;
+    this.meta = parsed?.meta;
+    this.releasedAt = parsed?.meta.releasedAt ?? null;
   }
 }
 
@@ -206,6 +289,75 @@ export class GuardianHttpClient {
     };
   }
 
+  /**
+   * Request abandonment of a pending canonicalization candidate whose
+   * transaction will never land on-chain (issue #319).
+   *
+   * Records an abandon *intent* (`202 Accepted`): the delta stays a
+   * candidate — the account stays locked — until the guardian's worker
+   * confirms over the abandon quarantine that the transaction did not
+   * land, then discards the delta as `client_abandoned` and releases the
+   * account (typically well under a minute). Poll {@link abandonStatus}
+   * for the resolution. Refused with `GUARDIAN_CANDIDATE_LANDED` (409)
+   * when the transaction actually landed. Retries are idempotent and
+   * preserve the original request timestamp.
+   */
+  async abandonCandidate(accountId: string, nonce: number): Promise<AbandonCandidateResponse> {
+    const serverRequest: ServerAbandonCandidateRequest = { account_id: accountId, nonce };
+    const response = await this.fetchAuthenticated('/delta/candidate/abandon', {
+      method: 'POST',
+      body: JSON.stringify(serverRequest),
+    }, accountId, serverRequest);
+    const server = (await response.json()) as ServerAbandonCandidateResponse;
+    return {
+      accountId: server.account_id,
+      nonce: server.nonce,
+      state: server.state,
+      abandonRequestedAt: server.abandon_requested_at,
+    };
+  }
+
+  /**
+   * Poll the resolution of an abandon request made with
+   * {@link abandonCandidate}: `'waiting'` while the quarantine runs,
+   * `'landed'` if the transaction landed after all (the delta
+   * canonicalized), `'abandoned'` once the delta is discarded as
+   * client-abandoned and the account released, `'retained'` when the
+   * guardian stopped verifying and released the account but the
+   * on-chain outcome is still uncertain (reconciliation may promote the
+   * delta until its retention TTL expires — sync and check chain before
+   * replacing it), `'unexpected'` for any state no abandon flow
+   * produces (including a missing delta).
+   */
+  async abandonStatus(accountId: string, nonce: number): Promise<AbandonStatus> {
+    let delta: DeltaObject;
+    try {
+      delta = await this.getDelta(accountId, nonce);
+    } catch (e) {
+      if (e instanceof GuardianHttpError && e.code === 'delta_not_found') {
+        return 'unexpected';
+      }
+      throw e;
+    }
+    switch (delta.status.status) {
+      case 'candidate':
+        return 'waiting';
+      case 'canonical':
+        return 'landed';
+      // The Guardian gave up verifying and released the account (issue
+      // #345): unlocked, but unresolved — deliberately distinct from
+      // 'abandoned', which would wrongly imply the transaction did not
+      // land.
+      case 'retained':
+        return 'retained';
+      case 'discarded':
+        return delta.status.reason === 'client_abandoned' ? 'abandoned' : 'unexpected';
+      default:
+        return 'unexpected';
+    }
+  }
+
+
   async signDeltaProposal(request: SignProposalRequest): Promise<DeltaObject> {
     const serverRequest = toServerSignProposalRequest(request);
     const response = await this.fetchAuthenticated('/delta/proposal', {
@@ -352,7 +504,16 @@ export class GuardianHttpClient {
         },
       });
     } catch (err) {
-      if (retries > 0 && err instanceof GuardianHttpError && err.body.includes('Replay attack')) {
+      // 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.
+      if (
+        retries > 0 &&
+        err instanceof GuardianHttpError &&
+        err.code === 'authentication_failed'
+      ) {
         await new Promise((resolve) => setTimeout(resolve, 50));
         return this.fetchAuthenticated(path, init, accountId, requestPayload, retries - 1);
       }

package/src/index.ts

@@ -1,7 +1,16 @@
 export { GuardianHttpClient, GuardianHttpError } from './http.js';
+export type { GuardianErrorMeta } from './http.js';
+export {
+  GUARDIAN_ERROR_CODES,
+  isGuardianErrorCode,
+  normalizeGuardianErrorCode,
+} from './error-codes.js';
+export type { GuardianErrorCode } from './error-codes.js';
 export { RequestAuthPayload } from './auth-request.js';
 
 export type {
+  AbandonCandidateResponse,
+  AbandonStatus,
   Signer,
   FalconSignature,
   EcdsaSignature,

package/src/server-types.ts

@@ -21,7 +21,8 @@ export type ServerDeltaStatus =
   | { status: 'pending'; timestamp: string; proposer_id: string; cosigner_sigs: ServerCosignerSignature[] }
   | { status: 'candidate'; timestamp: string }
   | { status: 'canonical'; timestamp: string }
-  | { status: 'discarded'; timestamp: string };
+  | { status: 'retained'; timestamp: string; reason?: 'retry_exhausted' | 'diverged' }
+  | { status: 'discarded'; timestamp: string; reason?: string };
 
 export type ServerProposalType =
   | 'add_signer'
@@ -54,6 +55,8 @@ export interface ServerProposalMetadata {
   recipient_id?: string;
   faucet_id?: string;
   amount?: string;
+  /** P2ID note visibility, "public" or "private" (issue #322). Absent => public. */
+  note_type?: string;
 }
 
 export interface ServerDeltaObject {
@@ -137,6 +140,18 @@ export interface ServerProposalsResponse {
   proposals: ServerDeltaObject[];
 }
 
+export interface ServerAbandonCandidateRequest {
+  account_id: string;
+  nonce: number;
+}
+
+export interface ServerAbandonCandidateResponse {
+  account_id: string;
+  nonce: number;
+  state: 'pending' | 'abandoned' | 'retained';
+  abandon_requested_at?: string;
+}
+
 export interface ServerSignProposalRequest {
   account_id: string;
   commitment: string;