From d0c6ca6f812db7c6a8df6b226227adf7d6363b4c Mon Sep 17 00:00:00 2001
From: Anadudev <anadudev@gmail.com>
Date: Mon, 31 Aug 2026 09:13:33 +0100
Subject: [PATCH 1/2] feat(sdk): surface typed contract error taxonomy
 end-to-end (#404)

---
 frontend/app/holder/page.tsx             |  19 +++--
 frontend/lib/__tests__/contracts.test.ts |  39 ++++++++-
 frontend/lib/contracts.ts                |  85 +++++++++++++++---
 frontend/packages/sdk/src/index.test.ts  |  24 ++++++
 frontend/packages/sdk/src/index.ts       | 104 +++++++++++++++++++++--
 5 files changed, 240 insertions(+), 31 deletions(-)

diff --git a/frontend/app/holder/page.tsx b/frontend/app/holder/page.tsx
index f7ab8186..8f436bbf 100644
--- a/frontend/app/holder/page.tsx
+++ b/frontend/app/holder/page.tsx
@@ -34,7 +34,8 @@ import {
   submitProofs,
   MAX_BATCH_SIZE,
   parseContractError,
-  type ContractError,
+  ContractError,
+  isRetryableContractError,
   type ProofSubmissionParams,
 } from "@/lib/contracts";
 import {
@@ -1020,7 +1021,7 @@ function ProofFlow({
           toast.error("Proof timed out — please try again.");
           return;
         }
-        const parsed = parseContractError((e as Error).message);
+        const parsed = e instanceof ContractError ? e : parseContractError((e as Error).message);
         setError(parsed);
         setErrorPhase("proving");
         setStage("error");
@@ -1073,7 +1074,7 @@ function ProofFlow({
       addEvent("verified", { txHash: hash });
       toast.success(`Proof confirmed on-chain for ${cred.title}`, { txHash: hash });
     } catch (e) {
-      const parsed = parseContractError((e as Error).message);
+      const parsed = e instanceof ContractError ? e : parseContractError((e as Error).message);
       setError(parsed);
       setErrorPhase("submitting");
       setStage("error");
@@ -1287,8 +1288,8 @@ function ProofFlow({
                 )}
               </div>
             )}
-            {/* Retry submission without re-proving when the proof exists */}
-            {errorPhase === "submitting" && proof && (
+            {/* Retry submission without re-proving when the proof exists and error is retryable */}
+            {errorPhase === "submitting" && proof && error && isRetryableContractError(error) && (
               <button
                 className="btn btn-primary"
                 style={{ marginTop: "1rem", width: "100%" }}
@@ -1406,7 +1407,7 @@ function BatchProofFlow({
             return next;
           });
           setBatchStage("error");
-          const parsed = parseContractError((e as Error).message);
+          const parsed = e instanceof ContractError ? e : parseContractError((e as Error).message);
           setBatchError(parsed);
           toast.error(`Proof generation failed for ${cred.title}: ${parsed.friendly}`);
           return;
@@ -1443,7 +1444,7 @@ function BatchProofFlow({
             return next;
           });
           setBatchStage("error");
-          const parsed = parseContractError((e as Error).message);
+          const parsed = e instanceof ContractError ? e : parseContractError((e as Error).message);
           setBatchError(parsed);
           toast.error(`Proof generation failed for ${cred.title}: ${parsed.friendly}`);
           return;
@@ -1512,8 +1513,8 @@ function BatchProofFlow({
 
         toast.success(`Confirmed ${creds.length} proofs on-chain`, { txHash: hash });
       })
-      .catch((e: any) => {
-        const parsed = parseContractError((e as Error).message);
+      .catch((e: unknown) => {
+        const parsed = e instanceof ContractError ? e : parseContractError((e as Error).message);
         setBatchError(parsed);
         setBatchStage("error");
         toast.error(`Batch submission failed: ${parsed.friendly}`);
diff --git a/frontend/lib/__tests__/contracts.test.ts b/frontend/lib/__tests__/contracts.test.ts
index 660facb4..c8d09a68 100644
--- a/frontend/lib/__tests__/contracts.test.ts
+++ b/frontend/lib/__tests__/contracts.test.ts
@@ -2,7 +2,7 @@ import { describe, it, expect, vi } from "vitest";
 
 vi.mock("../wallet", () => ({ signTx: vi.fn() }));
 
-import { parseContractError, PROOF_REGISTRY_ERRORS } from "../contracts";
+import { parseContractError, PROOF_REGISTRY_ERRORS, ContractError, isRetryableContractError } from "../contracts";
 
 // ── ProofRegistry Error enum coverage ────────────────────────────────────────
 //
@@ -49,17 +49,23 @@ describe("parseContractError", () => {
       const raw = `Error(Contract, #${code})`;
       const result = parseContractError(raw);
 
+      // Typed error instance — callers can instanceof-check
+      expect(result).toBeInstanceOf(ContractError);
+      expect(result).toBeInstanceOf(Error);
+      expect(result.name).toBe("ContractError");
+
       expect(result.code).toBe(code);
       expect(result.raw).toBe(raw);
       expect(result.friendly).toBe(PROOF_REGISTRY_ERRORS[code]);
       // Friendly message must never fall back to the raw "Contract error #N." default.
-      expect(result.friendly).not.toMatch(/^Contract error #\d+\.$/);
+      expect(result.friendly).not.toMatch(/^Contract error #\d+\.$/)
     });
 
     it("returns code and a fallback message for an unknown contract error code", () => {
       const raw = "Error(Contract, #99)";
       const result = parseContractError(raw);
 
+      expect(result).toBeInstanceOf(ContractError);
       expect(result.code).toBe(99);
       expect(result.friendly).toBe("Contract error #99.");
       expect(result.raw).toBe(raw);
@@ -163,3 +169,32 @@ describe("parseContractError", () => {
     });
   });
 });
+
+// ── isRetryableContractError ──────────────────────────────────────────────────
+
+describe("isRetryableContractError", () => {
+  it("returns true for code 11 (SubmissionsPaused) — admin may un-pause", () => {
+    const e = parseContractError("Error(Contract, #11)");
+    expect(isRetryableContractError(e)).toBe(true);
+  });
+
+  it("returns true when code is null (network / transient)", () => {
+    const e = parseContractError("some unexpected rpc error");
+    expect(isRetryableContractError(e)).toBe(true);
+  });
+
+  it.each([1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 12] as const)(
+    "returns false for deterministic code %i",
+    (code) => {
+      const e = parseContractError(`Error(Contract, #${code})`);
+      expect(isRetryableContractError(e)).toBe(false);
+    },
+  );
+
+  it("ContractError is instanceof Error", () => {
+    const e = parseContractError("Error(Contract, #2)");
+    expect(e).toBeInstanceOf(Error);
+    expect(e).toBeInstanceOf(ContractError);
+    expect(e.name).toBe("ContractError");
+  });
+});
diff --git a/frontend/lib/contracts.ts b/frontend/lib/contracts.ts
index 33234d2f..2f0e7082 100644
--- a/frontend/lib/contracts.ts
+++ b/frontend/lib/contracts.ts
@@ -72,29 +72,84 @@ export const PROOF_REGISTRY_ERRORS: Record<number, string> = {
   12: "Invalid expiry — the credential expiry is either in the past or too far in the future. Re-issue with a valid validity window.",
 };
 
-export interface ContractError {
-  friendly: string;
-  code: number | null;
-  raw: string;
+/**
+ * A typed, instanceof-checkable error thrown whenever a Soroban contract panic
+ * is detected during proof submission. Callers can:
+ *
+ *   - Branch on `e instanceof ContractError` to distinguish contract panics
+ *     from network / wallet errors.
+ *   - Read `e.code` to handle specific error codes programmatically.
+ *   - Use `isRetryableContractError(e)` to decide whether to show a retry
+ *     button or a terminal failure state.
+ */
+export class ContractError extends Error {
+  /** Numeric discriminant from the Soroban Error enum, or null for non-contract errors. */
+  readonly code: number | null;
+  /** Human-readable message looked up from PROOF_REGISTRY_ERRORS, or a generic fallback. */
+  readonly friendly: string;
+  /** The original raw error string from the RPC / SDK. */
+  readonly raw: string;
+
+  constructor(friendly: string, code: number | null, raw: string) {
+    super(friendly);
+    this.name = "ContractError";
+    this.code = code;
+    this.friendly = friendly;
+    this.raw = raw;
+    // Restore the prototype chain in envs that transpile classes to ES5.
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}
+
+/**
+ * Returns `true` when the error condition may resolve on its own and the
+ * caller is safe to retry the same submission:
+ *
+ *   - SubmissionsPaused (#11): the admin may un-pause; retry later.
+ *   - Unknown codes / network-level errors (no code): transient RPC blips.
+ *
+ * Returns `false` for deterministic failures where re-submitting the same
+ * proof will always produce the same error:
+ *   - VerificationFailed (#2): the ZK proof is cryptographically invalid.
+ *   - NotAuthorized (#3): wrong wallet signature.
+ *   - IssuerNotTrusted (#4): issuer not registered for this type.
+ *   - IssuerKeyMismatch (#5): credential signed with a key no longer on-chain.
+ *   - NotInitialized (#1), BatchTooLarge (#7), BatchEmpty (#8),
+ *     DuplicateCredentialType (#9), AggregateLayoutInvalid (#10),
+ *     InvalidExpiry (#12): caller must fix the submission before retrying.
+ */
+export function isRetryableContractError(e: ContractError): boolean {
+  // SubmissionsPaused: retryable — the admin may un-pause.
+  if (e.code === 11) return true;
+  // Deterministic contract errors: retrying will always fail.
+  if (e.code !== null) return false;
+  // No code: network / auth-level transient error — allow retry.
+  return true;
 }
 
+/**
+ * Parse a raw RPC/SDK error string into a typed {@link ContractError}.
+ *
+ * This is the single conversion point between the wire representation
+ * (`Error(Contract, #N)`) and the typed error taxonomy.
+ */
 export function parseContractError(raw: string): ContractError {
   const match = raw.match(/Error\(Contract,\s*#(\d+)\)/);
   if (match) {
     const code = parseInt(match[1]);
-    return {
+    return new ContractError(
+      PROOF_REGISTRY_ERRORS[code] ?? `Contract error #${code}.`,
       code,
-      friendly: PROOF_REGISTRY_ERRORS[code] ?? `Contract error #${code}.`,
       raw,
-    };
+    );
   }
   if (raw.includes("Error(Auth")) {
-    return { code: null, friendly: "Wallet authorisation failed — approve the transaction in your wallet.", raw };
+    return new ContractError("Wallet authorisation failed — approve the transaction in your wallet.", null, raw);
   }
   if (raw.includes("Error(WasmVm")) {
-    return { code: null, friendly: "Contract execution failed — the proof or inputs were malformed.", raw };
+    return new ContractError("Contract execution failed — the proof or inputs were malformed.", null, raw);
   }
-  return { code: null, friendly: raw, raw };
+  return new ContractError(raw, null, raw);
 }
 
 export interface VerificationStatus {
@@ -148,7 +203,7 @@ async function sendAndConfirm(
       typeof (sent.errorResult as { toXDR?: (f: string) => string }).toXDR === "function"
         ? (sent.errorResult as { toXDR: (f: string) => string }).toXDR("hex")
         : String(sent.errorResult);
-    throw new Error(`${label} rejected: ${errHex}`);
+    throw parseContractError(`${label} rejected: ${errHex}`);
   }
 
   const start = Date.now();
@@ -169,7 +224,8 @@ async function sendAndConfirm(
     }
   }
   if (result.status !== "SUCCESS") {
-    throw new Error(`Transaction ${sent.hash} did not succeed (${result.status}).`);
+    const raw = `Transaction ${sent.hash} did not succeed (${result.status}).`;
+    throw parseContractError(raw);
   }
   return sent.hash;
 }
@@ -318,7 +374,7 @@ export async function submitProofs(params: {
       typeof (sent.errorResult as { toXDR?: (f: string) => string }).toXDR === "function"
         ? (sent.errorResult as { toXDR: (f: string) => string }).toXDR("hex")
         : String(sent.errorResult);
-    throw new Error(`Batch submission rejected: ${errHex}`);
+    throw parseContractError(`Batch submission rejected: ${errHex}`);
   }
 
   function isBadUnionSwitch(e: unknown): boolean {
@@ -343,7 +399,8 @@ export async function submitProofs(params: {
     }
   }
   if (result.status !== "SUCCESS") {
-    throw new Error(`Batch transaction ${sent.hash} did not succeed (${result.status}).`);
+    const raw = `Batch transaction ${sent.hash} did not succeed (${result.status}).`;
+    throw parseContractError(raw);
   }
   return sent.hash;
 }
diff --git a/frontend/packages/sdk/src/index.test.ts b/frontend/packages/sdk/src/index.test.ts
index 1b13f54a..76680388 100644
--- a/frontend/packages/sdk/src/index.test.ts
+++ b/frontend/packages/sdk/src/index.test.ts
@@ -29,6 +29,9 @@ import {
   InvalidAddressError,
   RpcError,
   TimeoutError,
+  ContractError,
+  PROOF_REGISTRY_ERRORS,
+  isRetryableContractError,
   StellarCred,
   withRetry,
 } from "./index";
@@ -42,9 +45,30 @@ describe("error taxonomy exports", () => {
     expect(StellarCred.RpcError).toBe(RpcError);
     expect(StellarCred.TimeoutError).toBe(TimeoutError);
     expect(StellarCred.InvalidAddressError).toBe(InvalidAddressError);
+    expect(StellarCred.ContractError).toBe(ContractError);
+    expect(StellarCred.PROOF_REGISTRY_ERRORS).toBe(PROOF_REGISTRY_ERRORS);
+    expect(StellarCred.isRetryableContractError).toBe(isRetryableContractError);
     expect(new ConfigError().name).toBe("ConfigError");
     expect(new RpcError().name).toBe("RpcError");
     expect(new InvalidAddressError().name).toBe("InvalidAddressError");
+    const contractErr = new ContractError("Proof verification failed", 2, "Error(Contract, #2)");
+    expect(contractErr).toBeInstanceOf(Error);
+    expect(contractErr).toBeInstanceOf(ContractError);
+    expect(contractErr.name).toBe("ContractError");
+    expect(contractErr.code).toBe(2);
+    expect(contractErr.friendly).toBe("Proof verification failed");
+    expect(contractErr.raw).toBe("Error(Contract, #2)");
+  });
+
+  it("isRetryableContractError distinguishes retryable vs terminal codes", () => {
+    const pausedErr = new ContractError("Submissions paused", 11, "Error(Contract, #11)");
+    expect(isRetryableContractError(pausedErr)).toBe(true);
+
+    const netErr = new ContractError("network failed", null, "raw network error");
+    expect(isRetryableContractError(netErr)).toBe(true);
+
+    const verifyErr = new ContractError("Verification failed", 2, "Error(Contract, #2)");
+    expect(isRetryableContractError(verifyErr)).toBe(false);
   });
 });
 
diff --git a/frontend/packages/sdk/src/index.ts b/frontend/packages/sdk/src/index.ts
index ec941f09..35c9ebdd 100644
--- a/frontend/packages/sdk/src/index.ts
+++ b/frontend/packages/sdk/src/index.ts
@@ -193,12 +193,6 @@ export class InvalidAddressError extends Error {
   }
 }
 
-/**
- * Error thrown when an RPC / contract-simulation call fails (network,
- * timeout at the transport layer, simulation error, etc.). Only surfaces
- * when `{ throwOnError: true }` is passed — distinguishing "couldn't check"
- * from "not verified" (`false`).
- */
 export class RpcError extends Error {
   /** Underlying transport / simulation failure, when available. */
   cause?: unknown;
@@ -211,6 +205,101 @@ export class RpcError extends Error {
   }
 }
 
+/**
+ * The canonical mapping from ProofRegistry Soroban error-enum discriminants
+ * to human-readable messages.
+ *
+ * This table is the **single source of truth** for code→message translation.
+ * It mirrors the Rust `Error` enum in `contracts/proof_registry/src/lib.rs`
+ * exactly — every variant that exists there must have an entry here.
+ *
+ * Codes:
+ *   1  NotInitialized
+ *   2  VerificationFailed
+ *   3  NotAuthorized
+ *   4  IssuerNotTrusted
+ *   5  IssuerKeyMismatch
+ *   6  ProofNotFound
+ *   7  BatchTooLarge
+ *   8  BatchEmpty
+ *   9  DuplicateCredentialType
+ *   10 AggregateLayoutInvalid
+ *   11 SubmissionsPaused
+ *   12 InvalidExpiry
+ */
+export const PROOF_REGISTRY_ERRORS: Record<number, string> = {
+  1: "Contracts not initialised — check that all contract IDs are set in the environment.",
+  2: "Proof verification failed — the ZK proof is invalid or was generated against the wrong circuit VK.",
+  3: "Not authorised — wallet signature missing or wrong account.",
+  4: "Issuer not trusted — the issuer address isn't registered for this credential type.",
+  5: "Issuer key mismatch — this credential was signed with a key that doesn't match what's registered on-chain. Re-issue the credential and try again.",
+  6: "Proof not found — no on-chain proof exists for this holder and credential type.",
+  7: "Batch too large — reduce the number of proofs and try again.",
+  8: "Batch is empty — include at least one proof submission.",
+  9: "Duplicate credential type — the batch contains two proofs for the same claim type. Remove the duplicate and try again.",
+  10: "Aggregate proof layout invalid — the number of credentials or public inputs don't match the expected format. Re-generate the aggregate proof.",
+  11: "Submissions paused — the protocol admin has temporarily halted new proof submissions. Try again later.",
+  12: "Invalid expiry — the credential expiry is either in the past or too far in the future. Re-issue with a valid validity window.",
+};
+
+/**
+ * A typed, instanceof-checkable error that wraps a Soroban contract panic
+ * surfaced during proof submission. SDK consumers can:
+ *
+ *   - Branch on `e instanceof ContractError` to distinguish contract panics
+ *     from network / wallet errors.
+ *   - Read `e.code` to handle specific error codes programmatically.
+ *   - Use `isRetryableContractError(e)` to decide whether to offer a retry.
+ *
+ * @example
+ * ```ts
+ * import StellarCred, { ContractError, isRetryableContractError } from "@stellarcred/sdk";
+ *
+ * try {
+ *   await submitProof(...);
+ * } catch (e) {
+ *   if (e instanceof ContractError) {
+ *     console.error(`Contract error #${e.code}: ${e.friendly}`);
+ *     const canRetry = isRetryableContractError(e);
+ *   }
+ * }
+ * ```
+ */
+export class ContractError extends Error {
+  /** Numeric discriminant from the Soroban Error enum, or null for non-contract errors. */
+  readonly code: number | null;
+  /** Human-readable message looked up from {@link PROOF_REGISTRY_ERRORS}, or a generic fallback. */
+  readonly friendly: string;
+  /** The original raw error string from the RPC / SDK. */
+  readonly raw: string;
+
+  constructor(friendly: string, code: number | null, raw: string) {
+    super(friendly);
+    this.name = "ContractError";
+    this.code = code;
+    this.friendly = friendly;
+    this.raw = raw;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}
+
+/**
+ * Returns `true` when the error condition may resolve on its own and the
+ * caller is safe to retry the same submission.
+ *
+ * Retryable:
+ *   - SubmissionsPaused (#11): the admin may un-pause; retry later.
+ *   - No code (network / auth-level transient errors): RPC blips.
+ *
+ * Terminal (retrying with the same proof will always fail):
+ *   - Any other known contract error code.
+ */
+export function isRetryableContractError(e: ContractError): boolean {
+  if (e.code === 11) return true;   // SubmissionsPaused — try again later
+  if (e.code !== null) return false; // any other known contract panic is deterministic
+  return true;                       // no code = network/transient
+}
+
 /** The credential types StellarCred supports. Matches the contract Symbols. */
 export const CLAIM_TYPES = ["kyc", "age", "income", "jurisdiction", "funds", "accreditation"] as const;
 /**
@@ -1097,10 +1186,13 @@ export const StellarCred = {
   parseReturnParams,
   watchClaim,
   CLAIM_TYPES,
+  PROOF_REGISTRY_ERRORS,
   TimeoutError,
   ConfigError,
   InvalidAddressError,
   RpcError,
+  ContractError,
+  isRetryableContractError,
 };
 export default StellarCred;
 

From 12ebe5137d396424be17e93cd0939559eb0b9e34 Mon Sep 17 00:00:00 2001
From: Anadudev <anadudev@gmail.com>
Date: Mon, 31 Aug 2026 09:34:18 +0100
Subject: [PATCH 2/2] fix(holder): instantiate ContractError in proof timeout
 handler

---
 frontend/app/holder/page.tsx | 11 ++++++-----
 1 file changed, 6 insertions(+), 5 deletions(-)

diff --git a/frontend/app/holder/page.tsx b/frontend/app/holder/page.tsx
index 8f436bbf..54558648 100644
--- a/frontend/app/holder/page.tsx
+++ b/frontend/app/holder/page.tsx
@@ -1010,12 +1010,13 @@ function ProofFlow({
         // ProofTimeoutError gets a distinct user-visible message — half the
         // point is that stalled provers fail visibly, not as a generic error.
         if (e instanceof ProofTimeoutError) {
-          setError({
-            code: null,
-            friendly:
+          setError(
+            new ContractError(
               "Proof generation timed out. The prover took too long — this can happen on slow devices or with large circuits. Please try again.",
-            raw: e.message,
-          });
+              null,
+              e.message,
+            ),
+          );
           setErrorPhase("timeout");
           setStage("error");
           toast.error("Proof timed out — please try again.");