@zkproofport-app/sdk 0.2.15 → 0.3.0

package/dist/index.js

@@ -84,6 +84,16 @@ const CIRCUIT_METADATA = {
         publicInputsCount: 148,
         publicInputNames: ['pubkey_modulus_limbs', 'domain', 'scope', 'nullifier', 'provider'],
     },
+    arc_eligibility: {
+        name: 'Arc Eligibility',
+        description: 'Prove eligibility and authorize one EIP-712 action, for an Arc gate',
+        // 6 x `pub [u8; 32]` in arc-eligibility/src/main.nr, flattened to bytes.
+        // Read off the compiled ABI rather than counted: signal_hash 0-31,
+        // domain_separator 32-63, action_hash 64-95, signer_list_merkle_root
+        // 96-127, scope 128-159, nullifier 160-191.
+        publicInputsCount: 192,
+        publicInputNames: ['signal_hash', 'domain_separator', 'action_hash', 'signer_list_merkle_root'],
+    },
     // Planned circuit — the identifier is reserved and the circuit exists, but it
     // is not officially supported yet. See CIRCUIT_SUPPORT_STATUS in ./circuits.
     // Forked from coinbase_attestation and shares its four public inputs, so the
@@ -323,6 +333,292 @@ const OIDC_DOMAIN_ATTESTATION_PUBLIC_INPUT_LAYOUT = {
     DOMAIN_END: 82,
 };
 
+/**
+ * Canonical ZKProofport circuit identifiers.
+ *
+ * This module is the single source of truth for circuit IDs. Every other layer
+ * — the mobile app, the demo, the relay, server-side provers — reads its list
+ * from here instead of keeping a private copy that silently drifts.
+ *
+ * It has **no imports and no dependencies**, so it can be pulled in on its own:
+ *
+ * ```typescript
+ * import { CIRCUIT_IDS, isCircuitId } from '@zkproofport-app/sdk/circuits';
+ * ```
+ *
+ * The same names are also re-exported from the package root
+ * (`@zkproofport-app/sdk`) for callers that already import the SDK.
+ *
+ * ## Identifiers are canonical and case-sensitive
+ *
+ * Each ID is the circuit's `name` in its `Nargo.toml`, verbatim. The format is
+ * lowercase with underscores. Hyphenated spellings (`coinbase-kyc`,
+ * `mdl-kr-age`) are directory or UI route names in other repositories — they
+ * are **not** circuit IDs, and passing one produces a nullifier mismatch or a
+ * failed on-chain lookup rather than a clear error.
+ */
+/**
+ * Canonical circuit identifiers, keyed by a stable constant name.
+ *
+ * Prefer these constants over string literals so a rename is a compile error
+ * rather than a runtime surprise.
+ *
+ * @example
+ * ```typescript
+ * import { CIRCUIT_IDS } from '@zkproofport-app/sdk/circuits';
+ *
+ * const relay = await sdk.createRelayRequest(CIRCUIT_IDS.COINBASE_ATTESTATION, {
+ *   scope: 'myapp.com',
+ * });
+ * ```
+ */
+const CIRCUIT_IDS = Object.freeze({
+    /** Coinbase KYC attestation. Officially supported. */
+    COINBASE_ATTESTATION: 'coinbase_attestation',
+    /** Coinbase country attestation (inclusion / exclusion). Officially supported. */
+    COINBASE_COUNTRY_ATTESTATION: 'coinbase_country_attestation',
+    /** OIDC email-domain attestation. Officially supported. */
+    OIDC_DOMAIN_ATTESTATION: 'oidc_domain_attestation',
+    /** Arc eligibility: one EIP-712 action, authorized. Officially supported. */
+    ARC_ELIGIBILITY: 'arc_eligibility',
+    /** GIWA attestation. Planned — not officially supported yet. */
+    GIWA_ATTESTATION: 'giwa_attestation',
+    /** Korea Mobile ID ownership. Planned — not officially supported yet. */
+    MDL_KR_OWNERSHIP: 'mdl_kr_ownership',
+    /** Korea Mobile ID age threshold. Planned — not officially supported yet. */
+    MDL_KR_AGE: 'mdl_kr_age',
+    /** Korea Mobile ID si/do region. Planned — not officially supported yet. */
+    MDL_KR_REGION: 'mdl_kr_region',
+});
+/**
+ * Support status for every circuit.
+ *
+ * The record is exhaustive over {@link CircuitId}: adding an identifier without
+ * giving it a status is a compile error, so this list cannot drift from
+ * {@link CIRCUIT_IDS}.
+ *
+ * @example
+ * ```typescript
+ * import { CIRCUIT_SUPPORT_STATUS } from '@zkproofport-app/sdk/circuits';
+ *
+ * CIRCUIT_SUPPORT_STATUS.coinbase_attestation; // 'supported'
+ * CIRCUIT_SUPPORT_STATUS.mdl_kr_age;           // 'planned'
+ * ```
+ */
+const CIRCUIT_SUPPORT_STATUS = Object.freeze({
+    coinbase_attestation: 'supported',
+    coinbase_country_attestation: 'supported',
+    oidc_domain_attestation: 'supported',
+    arc_eligibility: 'experimental',
+    giwa_attestation: 'planned',
+    mdl_kr_ownership: 'planned',
+    mdl_kr_age: 'planned',
+    mdl_kr_region: 'planned',
+});
+/**
+ * Where each circuit's verification key FILE lives inside the
+ * `zkproofport/circuits` repository, relative to its root.
+ *
+ * Off-chain verification needs the verification key and nothing else — no
+ * circuit bytecode, no witness. The key is public by nature: it is what anyone
+ * checking a proof must already have, and the Solidity verifiers deployed
+ * on-chain embed the same key.
+ *
+ * NOTE THE TRAILING `/vk` TWICE. In that repository `target/vk` is a DIRECTORY
+ * holding `vk`, `vk_hash` and `SHA256SUMS`; the key itself is `target/vk/vk`.
+ * These paths were first copied here from the mobile app, which keeps the
+ * directory and the filename as two fields and joins them — so taking only the
+ * directory produced a URL that answers 404, and the first browser to try
+ * off-chain verification said "Could not fetch the verification key (HTTP 404)".
+ *
+ * Exhaustive over {@link CircuitId} on purpose. A new circuit whose key path is
+ * not listed here fails to compile rather than failing at verification time,
+ * where the only symptom would be a proof that cannot be checked.
+ */
+const CIRCUIT_VK_PATHS = Object.freeze({
+    coinbase_attestation: 'coinbase-attestation/target/vk/vk',
+    coinbase_country_attestation: 'coinbase-country-attestation/target/vk/vk',
+    oidc_domain_attestation: 'oidc-domain-attestation/target/vk/vk',
+    arc_eligibility: 'arc-eligibility/target/vk/vk',
+    giwa_attestation: 'giwa-attestation/target/vk/vk',
+    mdl_kr_ownership: 'mdl/kr-ownership/target/vk/vk',
+    mdl_kr_age: 'mdl/kr-age/target/vk/vk',
+    mdl_kr_region: 'mdl/kr-region/target/vk/vk',
+});
+/**
+ * Every canonical circuit identifier, in declaration order.
+ *
+ * Includes circuits that are still `planned`. Use {@link SUPPORTED_CIRCUIT_IDS}
+ * when you only want the ones that are officially supported today.
+ */
+const ALL_CIRCUIT_IDS = Object.freeze(Object.values(CIRCUIT_IDS));
+/**
+ * Circuits that are officially supported today: the two Coinbase circuits and
+ * OIDC domain attestation.
+ *
+ * Derived from {@link CIRCUIT_SUPPORT_STATUS}, so it cannot fall out of sync.
+ */
+const SUPPORTED_CIRCUIT_IDS = Object.freeze(ALL_CIRCUIT_IDS.filter((id) => CIRCUIT_SUPPORT_STATUS[id] === 'supported'));
+/**
+ * Circuits whose identifiers are reserved but which are not officially
+ * supported yet: GIWA attestation and the three Korea Mobile ID circuits.
+ *
+ * Derived from {@link CIRCUIT_SUPPORT_STATUS}, so it cannot fall out of sync.
+ */
+/**
+ * Circuits you can prove today, on a testnet, with everything subject to change.
+ *
+ * `arc_eligibility` is the reason this status exists. Calling it `planned`
+ * would be wrong — the circuit compiles, the verifier is deployed and a proof
+ * verifies against it — and calling it `supported` would be worse, because the
+ * only deployment is Arc Testnet, Circle has not published a mainnet chain id,
+ * and the public-input layout is still open. Neither existing word was true, so
+ * the honest move was a third word rather than picking the closer lie.
+ */
+const EXPERIMENTAL_CIRCUIT_IDS = Object.freeze(ALL_CIRCUIT_IDS.filter(id => CIRCUIT_SUPPORT_STATUS[id] === 'experimental'));
+const PLANNED_CIRCUIT_IDS = Object.freeze(ALL_CIRCUIT_IDS.filter((id) => CIRCUIT_SUPPORT_STATUS[id] === 'planned'));
+/**
+ * Narrows an unknown value to a canonical circuit identifier.
+ *
+ * Returns `false` for hyphenated route names such as `'coinbase-kyc'`, which
+ * are not circuit IDs.
+ *
+ * @example
+ * ```typescript
+ * isCircuitId('coinbase_attestation'); // true
+ * isCircuitId('coinbase-kyc');         // false
+ * ```
+ */
+function isCircuitId(value) {
+    return typeof value === 'string' && ALL_CIRCUIT_IDS.includes(value);
+}
+/**
+ * Narrows an unknown value to a circuit identifier that is officially supported
+ * today. Planned circuits return `false`.
+ *
+ * @example
+ * ```typescript
+ * isSupportedCircuitId('oidc_domain_attestation'); // true
+ * isSupportedCircuitId('mdl_kr_age');              // false — planned
+ * ```
+ */
+function isSupportedCircuitId(value) {
+    return isCircuitId(value) && CIRCUIT_SUPPORT_STATUS[value] === 'supported';
+}
+/**
+ * Returns the support status of a circuit.
+ *
+ * @param circuit - A canonical circuit identifier.
+ * @throws Error when the value is not a canonical circuit identifier.
+ *
+ * @example
+ * ```typescript
+ * getCircuitSupportStatus('giwa_attestation'); // 'planned'
+ * ```
+ */
+function getCircuitSupportStatus(circuit) {
+    if (!isCircuitId(circuit)) {
+        throw new Error(`Unknown circuit '${String(circuit)}'. Expected one of: ${ALL_CIRCUIT_IDS.join(', ')}`);
+    }
+    return CIRCUIT_SUPPORT_STATUS[circuit];
+}
+/**
+ * Whether a circuit's relay request must carry a wallet signature.
+ *
+ * The SDK checks this to fail fast — "Signer not set" locally beats a 401 from
+ * the relay two round trips later, with nothing saying which circuit needed
+ * what. The relay declares its OWN copy on purpose and does not import this
+ * one: it is a security boundary, and an auth policy that a published package
+ * can change is not a policy. A test in the relay asserts the two agree.
+ *
+ * `satisfies` and not an annotation, so a circuit added above is a compile
+ * error here until somebody decides which it is.
+ */
+const CIRCUIT_NEEDS_WALLET_SIGNATURE = {
+    coinbase_attestation: true,
+    coinbase_country_attestation: true,
+    // Same Coinbase-attested wallet as above; what changes is that it signs an
+    // EIP-712 action rather than signal_hash.
+    arc_eligibility: true,
+    // The signature is inside the OIDC identity token, checked by the prover.
+    oidc_domain_attestation: false,
+    // Web2 (OmniOne CX) flows with no wallet binding at all.
+    mdl_kr_ownership: false,
+    mdl_kr_age: false,
+    mdl_kr_region: false,
+    giwa_attestation: false,
+};
+
+const ADDRESS = /^0x[0-9a-fA-F]{40}$/;
+/**
+ * The reason the value is not a usable action, or `null` when it is one.
+ *
+ * A string rather than a boolean because every caller shows it to somebody —
+ * a dapp developer reading a validation error, or a person looking at the
+ * mobile app's demo screen.
+ */
+function validateTypedAction(value) {
+    if (value === undefined || value === null) {
+        return 'action is required for arc_eligibility. The circuit proves that a wallet authorised ONE EIP-712 action; there is nothing to prove without it.';
+    }
+    if (typeof value !== 'object' || Array.isArray(value)) {
+        return 'action must be an object.';
+    }
+    const a = value;
+    const d = a.domain;
+    if (!d || typeof d !== 'object') {
+        return 'action.domain is required.';
+    }
+    for (const k of ['name', 'version', 'verifyingContract']) {
+        if (typeof d[k] !== 'string' || !d[k]) {
+            return `action.domain.${k} must be a non-empty string.`;
+        }
+    }
+    if (typeof d.chainId !== 'number' || !Number.isInteger(d.chainId)) {
+        return 'action.domain.chainId must be an integer.';
+    }
+    if (!ADDRESS.test(d.verifyingContract)) {
+        return 'action.domain.verifyingContract must be a 20-byte hex address.';
+    }
+    if (!a.types || typeof a.types !== 'object' || Array.isArray(a.types)) {
+        return 'action.types is required.';
+    }
+    if (typeof a.primaryType !== 'string' || !a.primaryType) {
+        return 'action.primaryType is required.';
+    }
+    if (!(a.primaryType in a.types)) {
+        return `action.primaryType '${a.primaryType}' is not one of the structs in action.types.`;
+    }
+    if (!a.message || typeof a.message !== 'object' || Array.isArray(a.message)) {
+        return 'action.message is required.';
+    }
+    // Every field the struct declares must be present, or the wallet signs a
+    // different message than the one the caller described.
+    const fields = a.types[a.primaryType];
+    if (!Array.isArray(fields) || fields.length === 0) {
+        return `action.types.${a.primaryType} declares no fields.`;
+    }
+    const missing = fields
+        .map(f => f?.name)
+        .filter(n => typeof n === 'string' && !(n in a.message));
+    if (missing.length) {
+        return `action.message is missing: ${missing.join(', ')}`;
+    }
+    return null;
+}
+/** The action, or the reason it is not one. For text a person typed. */
+function parseTypedAction(text) {
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch (e) {
+        return { error: `Not valid JSON: ${e.message}` };
+    }
+    const error = validateTypedAction(raw);
+    return error ? { error } : { action: raw };
+}
+
 /**
  * Deep Link utilities for ZKProofport SDK
  */
@@ -501,9 +797,22 @@ function parseProofResponseUrl(url) {
         if (!requestId || !status) {
             return null;
         }
+        // A missing or unrecognised circuit is a REJECTION, not a default.
+        //
+        // This used to fall back to `coinbase_attestation`. A callback carrying a
+        // country or OIDC proof, or a circuit this build has never heard of, was
+        // then handed to the caller labelled Coinbase KYC -- the parse succeeded,
+        // the label was wrong, and nothing downstream could tell. Whoever reads
+        // `response.circuit` decides which verifier and which public-input layout
+        // to use, so the wrong label is a proof checked against another circuit's
+        // bytes.
+        const circuit = urlObj.searchParams.get('circuit');
+        if (!circuit || !isCircuitId(circuit)) {
+            return null;
+        }
         const response = {
             requestId,
-            circuit: urlObj.searchParams.get('circuit') || 'coinbase_attestation',
+            circuit,
             status,
         };
         if (status === 'completed') {
@@ -805,15 +1114,15 @@ function validateProofRequest(request) {
     if (!request.circuit) {
         return { valid: false, error: 'Missing circuit type' };
     }
-    if (![
-        'coinbase_attestation',
-        'coinbase_country_attestation',
-        'oidc_domain_attestation',
-        'mdl_kr_ownership',
-        'mdl_kr_age',
-        'mdl_kr_region',
-    ].includes(request.circuit)) {
-        return { valid: false, error: `Invalid circuit type: ${request.circuit}` };
+    // The list is the SDK's own, not a copy. The copy that used to sit here
+    // named six circuits and had missed two — `giwa_attestation` and
+    // `arc_eligibility` — so a link for either was refused as an invalid type
+    // while every other layer accepted it.
+    if (!isCircuitId(request.circuit)) {
+        return {
+            valid: false,
+            error: `Invalid circuit type: ${request.circuit}. Expected one of: ${ALL_CIRCUIT_IDS.join(', ')}`,
+        };
     }
     if (!request.callbackUrl) {
         return { valid: false, error: 'Missing callbackUrl' };
@@ -862,6 +1171,16 @@ function validateProofRequest(request) {
             return { valid: false, error: mdlError };
         }
     }
+    else if (request.circuit === 'arc_eligibility') {
+        const inputs = request.inputs;
+        if (inputs.userAddress && !/^0x[a-fA-F0-9]{40}$/.test(inputs.userAddress)) {
+            return { valid: false, error: 'Invalid userAddress format' };
+        }
+        const actionError = validateTypedAction(inputs.action);
+        if (actionError) {
+            return { valid: false, error: actionError };
+        }
+    }
     // Check expiry
     if (request.expiresAt && Date.now() > request.expiresAt) {
         return { valid: false, error: 'Request has expired' };
@@ -1145,7 +1464,7 @@ function getDefaultProvider(chainId) {
  * This function resolves the verifier contract from SDK config or proof response,
  * connects to the blockchain, and calls the verify() method with the proof and public inputs.
  *
- * @param circuit - The canonical circuit identifier (e.g., "coinbase_attestation")
+ * @param circuit - The canonical circuit identifier. REQUIRED.
  * @param parsedProof - Parsed proof object containing proofHex and publicInputsHex
  * @param providerOrSigner - Optional ethers.js Provider or Signer instance. If not provided, uses default RPC for the chain
  * @param customVerifier - Optional custom verifier contract config (takes priority over responseVerifier)
@@ -1243,7 +1562,7 @@ function requireVerifier(circuit, verifier) {
 /**
  * Get verifier contract address for a circuit.
  *
- * @param circuit - The canonical circuit identifier (e.g., "coinbase_attestation")
+ * @param circuit - The canonical circuit identifier. REQUIRED.
  * @param customVerifier - Optional custom verifier contract config
  * @returns Verifier contract address as hex string
  * @throws Error if no verifier is configured for the circuit
@@ -1260,7 +1579,7 @@ function getVerifierAddress(circuit, customVerifier) {
 /**
  * Get chain ID for a circuit's verifier contract.
  *
- * @param circuit - The canonical circuit identifier (e.g., "coinbase_attestation")
+ * @param circuit - The canonical circuit identifier. REQUIRED.
  * @param customVerifier - Optional custom verifier contract config
  * @returns Chain ID number (e.g., 11155111 for Sepolia, 84532 for Base Sepolia)
  * @throws Error if no verifier is configured for the circuit
@@ -1274,6 +1593,55 @@ function getVerifierAddress(circuit, customVerifier) {
 function getVerifierChainId(circuit, customVerifier) {
     return requireVerifier(circuit, customVerifier).chainId;
 }
+/**
+ * Where `scope` and `nullifier` sit in each circuit's public inputs.
+ *
+ * Keyed by `CircuitId`, which is the point: adding a circuit to the SDK makes
+ * this object a compile error until somebody opens that circuit's `fn main`
+ * and writes its offsets down. Nothing here can be inferred from the proof —
+ * the public inputs are a flat array of bytes with no framing.
+ *
+ * It replaced an `if / else if / else` chain whose final `else` handed every
+ * unrecognised circuit — and every call that named no circuit at all —
+ * Coinbase's offsets. For `arc_eligibility` that is not a near miss: its
+ * public inputs are signal_hash, domain_separator, action_hash, merkle root,
+ * scope, nullifier, so the nullifier slot under Coinbase's offsets holds the
+ * MERKLE ROOT, a value identical for every user. Duplicate detection built on
+ * it would report one person.
+ */
+const PUBLIC_INPUT_OFFSETS = Object.freeze({
+    // signal_hash, signer_list_merkle_root, scope, nullifier
+    coinbase_attestation: { scope: [64, 95], nullifier: [96, 127] },
+    // Same four fields in the same order as Coinbase.
+    giwa_attestation: { scope: [64, 95], nullifier: [96, 127] },
+    // country_list, country_list_length and is_included sit before scope.
+    coinbase_country_attestation: { scope: [86, 117], nullifier: [118, 149] },
+    // pubkey_modulus_limbs and the bounded domain sit before scope.
+    oidc_domain_attestation: { scope: [83, 114], nullifier: [115, 146] },
+    // signal_hash, domain_separator, action_hash, merkle root, then the pair.
+    arc_eligibility: { scope: [128, 159], nullifier: [160, 191] },
+    // The Korea mDL circuits open with the pair; signal_hash is commented out.
+    mdl_kr_ownership: { scope: [0, 31], nullifier: [32, 63] },
+    mdl_kr_age: { scope: [0, 31], nullifier: [32, 63] },
+    mdl_kr_region: { scope: [0, 31], nullifier: [32, 63] },
+});
+/**
+ * The offsets for a circuit, or an error naming what was asked for.
+ *
+ * Throwing is the whole point. A caller that omits the circuit, or names one
+ * this SDK has never heard of, is asking a question with no answer; returning
+ * a guess produced a scope and a nullifier that belong to different bytes and
+ * looked exactly like real ones.
+ */
+function offsetsFor(circuit) {
+    if (circuit === undefined) {
+        throw new Error(`A circuit id is required to read public inputs: the layout differs per circuit and cannot be inferred from the proof. Pass one of: ${ALL_CIRCUIT_IDS.join(', ')}`);
+    }
+    if (!isCircuitId(circuit)) {
+        throw new Error(`Unknown circuit '${circuit}'. Expected one of: ${ALL_CIRCUIT_IDS.join(', ')}`);
+    }
+    return PUBLIC_INPUT_OFFSETS[circuit];
+}
 /**
  * Extract scope value from public inputs array.
  *
@@ -1291,24 +1659,7 @@ function getVerifierChainId(circuit, customVerifier) {
  * ```
  */
 function extractScopeFromPublicInputs(publicInputsHex, circuit) {
-    let start, end;
-    if (circuit === 'coinbase_country_attestation') {
-        start = 86;
-        end = 117;
-    }
-    else if (circuit === 'oidc_domain_attestation') {
-        start = 83;
-        end = 114;
-    }
-    else if (circuit !== undefined && circuit.startsWith('mdl_kr_')) {
-        // All Korea mDL circuits: scope [0..31], nullifier_value [32..63]
-        start = 0;
-        end = 31;
-    }
-    else {
-        start = 64;
-        end = 95;
-    }
+    const [start, end] = offsetsFor(circuit).scope;
     if (publicInputsHex.length <= end)
         return null;
     const scopeFields = publicInputsHex.slice(start, end + 1);
@@ -1323,7 +1674,10 @@ function extractScopeFromPublicInputs(publicInputsHex, circuit) {
  * detection without revealing the wallet address.
  *
  * @param publicInputsHex - Array of hex-encoded field elements
- * @param circuit - Circuit type (defaults to coinbase_attestation)
+ * @param circuit - Circuit id. REQUIRED: the layout differs per circuit and
+ *   cannot be inferred from the proof. It used to default to
+ *   `coinbase_attestation`, which returned the right-shaped bytes read from
+ *   the wrong place for every other circuit.
  * @returns Nullifier as hex string (bytes32), or null if publicInputs too short
  *
  * @example
@@ -1333,24 +1687,7 @@ function extractScopeFromPublicInputs(publicInputsHex, circuit) {
  * ```
  */
 function extractNullifierFromPublicInputs(publicInputsHex, circuit) {
-    let start, end;
-    if (circuit === 'coinbase_country_attestation') {
-        start = 118;
-        end = 149;
-    }
-    else if (circuit === 'oidc_domain_attestation') {
-        start = 115;
-        end = 146;
-    }
-    else if (circuit !== undefined && circuit.startsWith('mdl_kr_')) {
-        // All Korea mDL circuits: scope [0..31], nullifier_value [32..63]
-        start = 32;
-        end = 63;
-    }
-    else {
-        start = 96;
-        end = 127;
-    }
+    const [start, end] = offsetsFor(circuit).nullifier;
     if (publicInputsHex.length <= end)
         return null;
     const nullifierFields = publicInputsHex.slice(start, end + 1);
@@ -1400,174 +1737,6 @@ function reconstructBytes32FromFields(fields) {
     return '0x' + bytes;
 }
 
-/**
- * Canonical ZKProofport circuit identifiers.
- *
- * This module is the single source of truth for circuit IDs. Every other layer
- * — the mobile app, the demo, the relay, server-side provers — reads its list
- * from here instead of keeping a private copy that silently drifts.
- *
- * It has **no imports and no dependencies**, so it can be pulled in on its own:
- *
- * ```typescript
- * import { CIRCUIT_IDS, isCircuitId } from '@zkproofport-app/sdk/circuits';
- * ```
- *
- * The same names are also re-exported from the package root
- * (`@zkproofport-app/sdk`) for callers that already import the SDK.
- *
- * ## Identifiers are canonical and case-sensitive
- *
- * Each ID is the circuit's `name` in its `Nargo.toml`, verbatim. The format is
- * lowercase with underscores. Hyphenated spellings (`coinbase-kyc`,
- * `mdl-kr-age`) are directory or UI route names in other repositories — they
- * are **not** circuit IDs, and passing one produces a nullifier mismatch or a
- * failed on-chain lookup rather than a clear error.
- */
-/**
- * Canonical circuit identifiers, keyed by a stable constant name.
- *
- * Prefer these constants over string literals so a rename is a compile error
- * rather than a runtime surprise.
- *
- * @example
- * ```typescript
- * import { CIRCUIT_IDS } from '@zkproofport-app/sdk/circuits';
- *
- * const relay = await sdk.createRelayRequest(CIRCUIT_IDS.COINBASE_ATTESTATION, {
- *   scope: 'myapp.com',
- * });
- * ```
- */
-const CIRCUIT_IDS = Object.freeze({
-    /** Coinbase KYC attestation. Officially supported. */
-    COINBASE_ATTESTATION: 'coinbase_attestation',
-    /** Coinbase country attestation (inclusion / exclusion). Officially supported. */
-    COINBASE_COUNTRY_ATTESTATION: 'coinbase_country_attestation',
-    /** OIDC email-domain attestation. Officially supported. */
-    OIDC_DOMAIN_ATTESTATION: 'oidc_domain_attestation',
-    /** GIWA attestation. Planned — not officially supported yet. */
-    GIWA_ATTESTATION: 'giwa_attestation',
-    /** Korea Mobile ID ownership. Planned — not officially supported yet. */
-    MDL_KR_OWNERSHIP: 'mdl_kr_ownership',
-    /** Korea Mobile ID age threshold. Planned — not officially supported yet. */
-    MDL_KR_AGE: 'mdl_kr_age',
-    /** Korea Mobile ID si/do region. Planned — not officially supported yet. */
-    MDL_KR_REGION: 'mdl_kr_region',
-});
-/**
- * Support status for every circuit.
- *
- * The record is exhaustive over {@link CircuitId}: adding an identifier without
- * giving it a status is a compile error, so this list cannot drift from
- * {@link CIRCUIT_IDS}.
- *
- * @example
- * ```typescript
- * import { CIRCUIT_SUPPORT_STATUS } from '@zkproofport-app/sdk/circuits';
- *
- * CIRCUIT_SUPPORT_STATUS.coinbase_attestation; // 'supported'
- * CIRCUIT_SUPPORT_STATUS.mdl_kr_age;           // 'planned'
- * ```
- */
-const CIRCUIT_SUPPORT_STATUS = Object.freeze({
-    coinbase_attestation: 'supported',
-    coinbase_country_attestation: 'supported',
-    oidc_domain_attestation: 'supported',
-    giwa_attestation: 'planned',
-    mdl_kr_ownership: 'planned',
-    mdl_kr_age: 'planned',
-    mdl_kr_region: 'planned',
-});
-/**
- * Where each circuit's verification key lives inside the `zkproofport/circuits`
- * repository, relative to its root.
- *
- * Off-chain verification needs the verification key and nothing else — no
- * circuit bytecode, no witness. The key is public by nature: it is what anyone
- * checking a proof must already have, and the Solidity verifiers deployed
- * on-chain embed the same key.
- *
- * Exhaustive over {@link CircuitId} on purpose. A new circuit whose key path is
- * not listed here fails to compile rather than failing at verification time,
- * where the only symptom would be a proof that cannot be checked.
- */
-const CIRCUIT_VK_PATHS = Object.freeze({
-    coinbase_attestation: 'coinbase-attestation/target/vk',
-    coinbase_country_attestation: 'coinbase-country-attestation/target/vk',
-    oidc_domain_attestation: 'oidc-domain-attestation/target/vk',
-    giwa_attestation: 'giwa-attestation/target/vk',
-    mdl_kr_ownership: 'mdl/kr-ownership/target/vk',
-    mdl_kr_age: 'mdl/kr-age/target/vk',
-    mdl_kr_region: 'mdl/kr-region/target/vk',
-});
-/**
- * Every canonical circuit identifier, in declaration order.
- *
- * Includes circuits that are still `planned`. Use {@link SUPPORTED_CIRCUIT_IDS}
- * when you only want the ones that are officially supported today.
- */
-const ALL_CIRCUIT_IDS = Object.freeze(Object.values(CIRCUIT_IDS));
-/**
- * Circuits that are officially supported today: the two Coinbase circuits and
- * OIDC domain attestation.
- *
- * Derived from {@link CIRCUIT_SUPPORT_STATUS}, so it cannot fall out of sync.
- */
-const SUPPORTED_CIRCUIT_IDS = Object.freeze(ALL_CIRCUIT_IDS.filter((id) => CIRCUIT_SUPPORT_STATUS[id] === 'supported'));
-/**
- * Circuits whose identifiers are reserved but which are not officially
- * supported yet: GIWA attestation and the three Korea Mobile ID circuits.
- *
- * Derived from {@link CIRCUIT_SUPPORT_STATUS}, so it cannot fall out of sync.
- */
-const PLANNED_CIRCUIT_IDS = Object.freeze(ALL_CIRCUIT_IDS.filter((id) => CIRCUIT_SUPPORT_STATUS[id] === 'planned'));
-/**
- * Narrows an unknown value to a canonical circuit identifier.
- *
- * Returns `false` for hyphenated route names such as `'coinbase-kyc'`, which
- * are not circuit IDs.
- *
- * @example
- * ```typescript
- * isCircuitId('coinbase_attestation'); // true
- * isCircuitId('coinbase-kyc');         // false
- * ```
- */
-function isCircuitId(value) {
-    return typeof value === 'string' && ALL_CIRCUIT_IDS.includes(value);
-}
-/**
- * Narrows an unknown value to a circuit identifier that is officially supported
- * today. Planned circuits return `false`.
- *
- * @example
- * ```typescript
- * isSupportedCircuitId('oidc_domain_attestation'); // true
- * isSupportedCircuitId('mdl_kr_age');              // false — planned
- * ```
- */
-function isSupportedCircuitId(value) {
-    return isCircuitId(value) && CIRCUIT_SUPPORT_STATUS[value] === 'supported';
-}
-/**
- * Returns the support status of a circuit.
- *
- * @param circuit - A canonical circuit identifier.
- * @throws Error when the value is not a canonical circuit identifier.
- *
- * @example
- * ```typescript
- * getCircuitSupportStatus('giwa_attestation'); // 'planned'
- * ```
- */
-function getCircuitSupportStatus(circuit) {
-    if (!isCircuitId(circuit)) {
-        throw new Error(`Unknown circuit '${String(circuit)}'. Expected one of: ${ALL_CIRCUIT_IDS.join(', ')}`);
-    }
-    return CIRCUIT_SUPPORT_STATUS[circuit];
-}
-
 /**
  * Off-chain proof verification — checking a proof against its verification key,
  * with no chain, no RPC, and no gas.
@@ -2765,11 +2934,83 @@ class ProofportSDK {
         }
         return await response.json();
     }
+    /**
+     * Creates a proof request through the relay server.
+     *
+     * This is the recommended way to create proof requests. The relay server:
+     * - Issues a server-side requestId (validated by the mobile app)
+     * - Tracks request status in Redis
+     * - Builds the deep link with relay callback URL
+     * - Stores inputs hash for deep link integrity verification
+     *
+     * @param circuit - Circuit type identifier
+     * @param inputs - Circuit-specific inputs
+     * @param options - Request options (message, dappName, dappIcon, nonce, returnScheme)
+     * @param options.returnScheme - Which app the ZKProofport app should switch back
+     *   to once it has finished. Put **your own** deep link scheme here — the bare
+     *   scheme your app registers, e.g. `'mydapp://'`. Only a native app has an
+     *   answer to this question; a web app omits the option entirely, because
+     *   opening its https origin would launch a new browser tab on a fresh page
+     *   rather than return the user to the tab they started from.
+     *
+     *   This is intentionally **not** a URL and not a return address: no path, query
+     *   string or fragment is accepted, and the ZKProofport app never sends the proof
+     *   there. The proof still comes back to you the same way it always did — over the
+     *   relay, via `waitForProof()` / `waitForResult()`. `returnScheme` only answers
+     *   "which app should come back to the foreground", exactly like the
+     *   `redirect.native` value a wallet uses to hand control back after signing.
+     *
+     *   **Omit it and the SDK decides for you.** When the request is created from a
+     *   page running in Chrome for iOS (`CriOS`) or Firefox for iOS (`FxiOS`), the
+     *   SDK fills in `'googlechrome://'` or `'firefox://'` by itself: opening either
+     *   scheme bare brings that browser forward without navigating, so the user lands
+     *   back on the tab they were already reading. Every other browser sends nothing,
+     *   because nothing safe exists to send — Safari has no such scheme, and Brave
+     *   and Arc are indistinguishable from Safari on iOS, so guessing would eject the
+     *   user into the wrong browser.
+     *   On Android nothing is needed at all: the ZKProofport app brings itself to the
+     *   back and the browser resumes exactly as it was. When no target is sent and
+     *   none can be inferred, the ZKProofport app tells the user the proof was
+     *   delivered and lets them switch back themselves.
+     *
+     *   There is no auto-switch on proof failure; only on success and on the user
+     *   declining the request.
+     *
+     *   Rejected with an error before the request is sent: empty or whitespace values,
+     *   anything longer than 128 characters, values carrying a host/path/query/fragment
+     *   (including https origins such as `'https://myapp.com'`), and the `http:`,
+     *   `file:`, `data:`, `javascript:`, `intent:`, `tel:`, `sms:`, `mailto:` families.
+     * @returns Promise resolving to RelayProofRequest with requestId, deepLink, pollUrl
+     * @throws Error if signer not set, returnScheme is malformed, or the relay request fails
+     *
+     * @example
+     * ```typescript
+     * const sdk = ProofportSDK.create();
+     * sdk.setSigner(signer);
+     *
+     * const relay = await sdk.createRelayRequest('coinbase_attestation', {
+     *   scope: 'myapp.com'
+     * }, { dappName: 'My DApp', returnScheme: 'mydapp://' });
+     *
+     * // Generate QR code from relay deep link
+     * const qr = await sdk.generateQRCode(relay.deepLink);
+     *
+     * // Wait for proof (WebSocket primary, polling fallback)
+     * const result = await sdk.waitForProof(relay.requestId);
+     * ```
+     */
+    // Which circuits need a wallet signature, from the one record in
+    // src/circuits.ts. The typed-out pair that used to sit here had missed
+    // arc_eligibility, so a dapp calling createRelayRequest() for it with no
+    // signer got no local error and a relay 401 two round trips later.
+    static needsWalletSignature(circuit) {
+        return CIRCUIT_NEEDS_WALLET_SIGNATURE[circuit] === true;
+    }
     async createRelayRequest(circuit, inputs, options = {}) {
         if (!this.relayUrl) {
             throw new Error('relayUrl is required. Set it in ProofportSDK config.');
         }
-        const needsSignature = ProofportSDK.WALLET_SIGNATURE_CIRCUITS.includes(circuit);
+        const needsSignature = ProofportSDK.needsWalletSignature(circuit);
         if (needsSignature && !this.signer) {
             throw new Error('Signer not set. Call setSigner() first. Wallet signature is required for this circuit.');
         }
@@ -2781,6 +3022,17 @@ class ProofportSDK {
                 throw new Error(`${mdlError} (circuit: ${circuit})`);
             }
         }
+        // arc_eligibility: the action is what the proof binds to, so a request
+        // without a usable one cannot be honoured. Checked here, before a
+        // challenge is burned, because the alternative is a refusal from inside
+        // the mobile app -- a screen the dapp developer never sees, reached after
+        // the person has already scanned a QR code.
+        if (circuit === 'arc_eligibility') {
+            const actionError = validateTypedAction(inputs.action);
+            if (actionError) {
+                throw new Error(`${actionError} (circuit: ${circuit})`);
+            }
+        }
         // Return target: validated before we burn a challenge, so a typo surfaces
         // as a local error instead of a relay 400 on the second round trip.
         if (options.returnScheme !== undefined) {
@@ -3105,76 +3357,6 @@ class ProofportSDK {
         return extractDomainFromPublicInputs(publicInputs, circuit);
     }
 }
-/**
- * Creates a proof request through the relay server.
- *
- * This is the recommended way to create proof requests. The relay server:
- * - Issues a server-side requestId (validated by the mobile app)
- * - Tracks request status in Redis
- * - Builds the deep link with relay callback URL
- * - Stores inputs hash for deep link integrity verification
- *
- * @param circuit - Circuit type identifier
- * @param inputs - Circuit-specific inputs
- * @param options - Request options (message, dappName, dappIcon, nonce, returnScheme)
- * @param options.returnScheme - Which app the ZKProofport app should switch back
- *   to once it has finished. Put **your own** deep link scheme here — the bare
- *   scheme your app registers, e.g. `'mydapp://'`. Only a native app has an
- *   answer to this question; a web app omits the option entirely, because
- *   opening its https origin would launch a new browser tab on a fresh page
- *   rather than return the user to the tab they started from.
- *
- *   This is intentionally **not** a URL and not a return address: no path, query
- *   string or fragment is accepted, and the ZKProofport app never sends the proof
- *   there. The proof still comes back to you the same way it always did — over the
- *   relay, via `waitForProof()` / `waitForResult()`. `returnScheme` only answers
- *   "which app should come back to the foreground", exactly like the
- *   `redirect.native` value a wallet uses to hand control back after signing.
- *
- *   **Omit it and the SDK decides for you.** When the request is created from a
- *   page running in Chrome for iOS (`CriOS`) or Firefox for iOS (`FxiOS`), the
- *   SDK fills in `'googlechrome://'` or `'firefox://'` by itself: opening either
- *   scheme bare brings that browser forward without navigating, so the user lands
- *   back on the tab they were already reading. Every other browser sends nothing,
- *   because nothing safe exists to send — Safari has no such scheme, and Brave
- *   and Arc are indistinguishable from Safari on iOS, so guessing would eject the
- *   user into the wrong browser.
- *   On Android nothing is needed at all: the ZKProofport app brings itself to the
- *   back and the browser resumes exactly as it was. When no target is sent and
- *   none can be inferred, the ZKProofport app tells the user the proof was
- *   delivered and lets them switch back themselves.
- *
- *   There is no auto-switch on proof failure; only on success and on the user
- *   declining the request.
- *
- *   Rejected with an error before the request is sent: empty or whitespace values,
- *   anything longer than 128 characters, values carrying a host/path/query/fragment
- *   (including https origins such as `'https://myapp.com'`), and the `http:`,
- *   `file:`, `data:`, `javascript:`, `intent:`, `tel:`, `sms:`, `mailto:` families.
- * @returns Promise resolving to RelayProofRequest with requestId, deepLink, pollUrl
- * @throws Error if signer not set, returnScheme is malformed, or the relay request fails
- *
- * @example
- * ```typescript
- * const sdk = ProofportSDK.create();
- * sdk.setSigner(signer);
- *
- * const relay = await sdk.createRelayRequest('coinbase_attestation', {
- *   scope: 'myapp.com'
- * }, { dappName: 'My DApp', returnScheme: 'mydapp://' });
- *
- * // Generate QR code from relay deep link
- * const qr = await sdk.generateQRCode(relay.deepLink);
- *
- * // Wait for proof (WebSocket primary, polling fallback)
- * const result = await sdk.waitForProof(relay.requestId);
- * ```
- */
-// Circuits that require wallet signature (used as circuit input)
-ProofportSDK.WALLET_SIGNATURE_CIRCUITS = [
-    'coinbase_attestation',
-    'coinbase_country_attestation',
-];
 
 exports.ALL_CIRCUIT_IDS = ALL_CIRCUIT_IDS;
 exports.CIRCUIT_IDS = CIRCUIT_IDS;
@@ -3182,6 +3364,7 @@ exports.CIRCUIT_SUPPORT_STATUS = CIRCUIT_SUPPORT_STATUS;
 exports.CIRCUIT_VK_PATHS = CIRCUIT_VK_PATHS;
 exports.COINBASE_ATTESTATION_PUBLIC_INPUT_LAYOUT = COINBASE_ATTESTATION_PUBLIC_INPUT_LAYOUT;
 exports.COINBASE_COUNTRY_PUBLIC_INPUT_LAYOUT = COINBASE_COUNTRY_PUBLIC_INPUT_LAYOUT;
+exports.EXPERIMENTAL_CIRCUIT_IDS = EXPERIMENTAL_CIRCUIT_IDS;
 exports.MDL_KR_PUBLIC_INPUT_LAYOUT = MDL_KR_PUBLIC_INPUT_LAYOUT;
 exports.OIDC_DOMAIN_ATTESTATION_PUBLIC_INPUT_LAYOUT = OIDC_DOMAIN_ATTESTATION_PUBLIC_INPUT_LAYOUT;
 exports.PLANNED_CIRCUIT_IDS = PLANNED_CIRCUIT_IDS;
@@ -3194,5 +3377,7 @@ exports.extractScopeFromPublicInputs = extractScopeFromPublicInputs;
 exports.getCircuitSupportStatus = getCircuitSupportStatus;
 exports.isCircuitId = isCircuitId;
 exports.isSupportedCircuitId = isSupportedCircuitId;
+exports.parseTypedAction = parseTypedAction;
+exports.validateTypedAction = validateTypedAction;
 exports.verifyProofOffChain = verifyProofOffChain;
 //# sourceMappingURL=index.js.map