@zkproofport-app/sdk 0.3.1 → 0.4.0

package/dist/index.js

@@ -84,28 +84,24 @@ 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
-    // count is the byte-flattened total (4 x [u8; 32] = 128), matching the
-    // COINBASE_ATTESTATION_PUBLIC_INPUT_LAYOUT indices below. The
-    // coinbase_attestation entry above reports a legacy logical count of 2 and is
-    // left as-is for backwards compatibility.
+    // Forked from coinbase_attestation, then given the EIP-712 pair and a
+    // branch: with an action the wallet signs the typed data and signal_hash is
+    // zero; without one it signs signal_hash and the pair is zero. Read off the
+    // compiled ABI (6 x [u8; 32] = 192): signal_hash 0-31, domain_separator
+    // 32-63, action_hash 64-95, signer_list_merkle_root 96-127, scope 128-159,
+    // nullifier 160-191.
+    //
+    // signal_hash is NOT part of this circuit's nullifier: a nullifier derived
+    // from a public input nobody signs and nothing constrains would let one
+    // wallet mint as many nullifiers as it likes; here the secret is the address
+    // plus a constant compiled into the circuit.
     giwa_attestation: {
         name: 'GIWA Attestation',
-        description: 'Prove GIWA identity verification (planned — not officially supported yet)',
-        publicInputsCount: 128,
-        publicInputNames: ['signal_hash', 'signer_list_merkle_root', 'scope', 'nullifier'],
+        description: 'Prove GIWA identity verification, optionally authorizing one EIP-712 action (planned — not officially supported yet)',
+        publicInputsCount: 192,
+        publicInputNames: ['signal_hash', 'domain_separator', 'action_hash', 'signer_list_merkle_root', 'scope', 'nullifier'],
     },
     // Korea Mobile ID (mDL) circuits. Planned — not officially supported yet.
     // Counts are byte-flattened field totals from the compiled circuit ABIs:
@@ -172,11 +168,6 @@ const RPC_ENDPOINTS = {
     84532: 'https://sepolia.base.org', // Base Sepolia
     8453: 'https://mainnet.base.org', // Base Mainnet
     91342: 'https://sepolia-rpc.giwa.io', // GIWA Sepolia
-    // Arc Testnet. The arc_eligibility verifier is deployed here and nowhere
-    // else, and this line was missing on 2026-09-12 — the circuit shipped, a
-    // phone produced a valid proof, and on-chain verification answered "No RPC
-    // endpoint configured for chain 5042002", which reads like the proof's fault.
-    5042002: 'https://rpc.testnet.arc.io', // Arc Testnet
 };
 /**
  * Default proof request expiration time in milliseconds.
@@ -384,8 +375,6 @@ const CIRCUIT_IDS = Object.freeze({
     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. */
@@ -414,8 +403,11 @@ const CIRCUIT_SUPPORT_STATUS = Object.freeze({
     coinbase_attestation: 'supported',
     coinbase_country_attestation: 'supported',
     oidc_domain_attestation: 'supported',
-    arc_eligibility: 'experimental',
-    giwa_attestation: 'planned',
+    // Experimental, not planned: the circuit is built, its verifier is
+    // deployed on GIWA Sepolia and the demo requests it. What keeps it out of
+    // 'supported' is that it is testnet-only, so the app offers it behind
+    // Developer Mode and reads its files from main rather than a release tag.
+    giwa_attestation: 'experimental',
     mdl_kr_ownership: 'planned',
     mdl_kr_age: 'planned',
     mdl_kr_region: 'planned',
@@ -444,7 +436,6 @@ 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',
@@ -473,12 +464,11 @@ const SUPPORTED_CIRCUIT_IDS = Object.freeze(ALL_CIRCUIT_IDS.filter((id) => CIRCU
 /**
  * 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.
+ * `giwa_attestation` is in this state. 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 a testnet (GIWA Sepolia). 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'));
@@ -527,44 +517,72 @@ function getCircuitSupportStatus(circuit) {
     }
     return CIRCUIT_SUPPORT_STATUS[circuit];
 }
-/**
- * Whether a circuit's relay request must carry a wallet signature.
+const CIRCUIT_ACTION_BINDING = {
+    coinbase_attestation: 'none',
+    coinbase_country_attestation: 'none',
+    // The signature lives inside the identity token; no wallet, no action.
+    oidc_domain_attestation: 'none',
+    // Branches in-circuit: with an action the wallet signs the typed data,
+    // without one it personal_signs the request's signal hash.
+    giwa_attestation: 'optional',
+    mdl_kr_ownership: 'none',
+    mdl_kr_age: 'none',
+    mdl_kr_region: 'none',
+};
+/*
+ * The union is declared above rather than derived from the table's values.
  *
- * 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.
+ * Deriving it narrowed the type to whatever the table happens to hold today --
+ * 'none' | 'optional' -- and TypeScript then called every `=== 'required'`
+ * check impossible. The publish typecheck caught it; `rollup` and `vitest` did
+ * not. 'required' is a state a circuit can legitimately be in (an EIP-712 path
+ * and nothing else), so the union says so and the table is checked against it.
+ */
+/**
+ * How this circuit treats an action, or an error naming the id that is not one.
  *
- * `satisfies` and not an annotation, so a circuit added above is a compile
- * error here until somebody decides which it is.
+ * No default: a circuit nobody has classified must not inherit 'none', which
+ * would silently drop an action a dapp meant to bind.
  */
+function circuitActionBinding(circuit) {
+    const binding = CIRCUIT_ACTION_BINDING[circuit];
+    if (!binding) {
+        throw new Error(`Unknown circuit '${circuit}'. Expected: ${ALL_CIRCUIT_IDS.join(', ')}`);
+    }
+    return binding;
+}
 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,
+    // A GIWA-attested wallet signing an EIP-712 action (or its signal hash).
+    // This read `false` while the circuit had always verified a wallet signature
+    // -- it sat under the Web2 comment above and was never revisited. A request
+    // for it would have reached the relay with no signer.
+    giwa_attestation: true,
 };
 
 const ADDRESS = /^0x[0-9a-fA-F]{40}$/;
 /**
  * The reason the value is not a usable action, or `null` when it is one.
  *
+ * Structural validation only, not application authorization policy. Consumers
+ * (e.g. EligibilityGate) must independently enforce the expected chain, verifying
+ * contract, actor, action parameters, nonce and deadline as applicable.
+ * EIP-712 signs only fields declared in types, not extra message properties.
+ *
  * 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.';
+        return 'action is required. 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.';
@@ -1120,8 +1138,7 @@ function validateProofRequest(request) {
         return { valid: false, error: 'Missing circuit type' };
     }
     // 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
+    // had missed circuits, so a link for one was refused as an invalid type
     // while every other layer accepted it.
     if (!isCircuitId(request.circuit)) {
         return {
@@ -1176,14 +1193,24 @@ 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' };
+    // The action, decided by the circuit's own entry rather than by naming a
+    // circuit here, so every action-capable circuit is checked the same way.
+    {
+        const action = request.inputs?.action;
+        const binding = circuitActionBinding(request.circuit);
+        if (binding === 'none') {
+            if (action !== undefined) {
+                return {
+                    valid: false,
+                    error: `${request.circuit} has no action inputs, so an action sent with it would not be proved. Refusing rather than dropping it.`,
+                };
+            }
         }
-        const actionError = validateTypedAction(inputs.action);
-        if (actionError) {
-            return { valid: false, error: actionError };
+        else if (binding === 'required' || action !== undefined) {
+            const actionError = validateTypedAction(action);
+            if (actionError) {
+                return { valid: false, error: actionError };
+            }
         }
     }
     // Check expiry
@@ -1459,7 +1486,7 @@ function getVerifierContract(providerOrSigner, verifier) {
 function getDefaultProvider(chainId) {
     const rpcUrl = RPC_ENDPOINTS[chainId];
     if (!rpcUrl) {
-        throw new Error(`No RPC endpoint configured for chain ${chainId}`);
+        throw new Error(`No RPC endpoint configured for chain ${chainId}. Known chains: ${Object.keys(RPC_ENDPOINTS).join(', ')}`);
     }
     return createJsonRpcProvider(rpcUrl);
 }
@@ -1608,7 +1635,7 @@ function getVerifierChainId(circuit, customVerifier) {
  *
  * 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
+ * Coinbase's offsets. For `giwa_attestation` 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
@@ -1617,14 +1644,14 @@ function getVerifierChainId(circuit, customVerifier) {
 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] },
+    // No longer Coinbase's layout. The GIWA circuit gained the EIP-712 pair, so
+    // it reads: signal_hash, domain_separator, action_hash, merkle root, then
+    // scope and nullifier 64 bytes further along than Coinbase.
+    giwa_attestation: { scope: [128, 159], nullifier: [160, 191] },
     // 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] },
@@ -3005,9 +3032,9 @@ class ProofportSDK {
      * ```
      */
     // 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.
+    // src/circuits.ts. A typed-out list here once missed a circuit, 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;
     }
@@ -3027,15 +3054,24 @@ 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})`);
+        // The action, per the circuit's entry in CIRCUIT_ACTION_BINDING. 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.
+        //
+        // The circuit id belongs in the table, not in the check.
+        {
+            const action = inputs.action;
+            const binding = circuitActionBinding(circuit);
+            if (binding === 'none' && action !== undefined) {
+                throw new Error(`${circuit} has no action inputs, so an action sent with it would not be proved. ` +
+                    'Remove it, or use a circuit that binds one.');
+            }
+            if (binding === 'required' || (binding === 'optional' && action !== undefined)) {
+                const actionError = validateTypedAction(action);
+                if (actionError) {
+                    throw new Error(`${actionError} (circuit: ${circuit})`);
+                }
             }
         }
         // Return target: validated before we burn a challenge, so a typo surfaces
@@ -3364,6 +3400,7 @@ class ProofportSDK {
 }
 
 exports.ALL_CIRCUIT_IDS = ALL_CIRCUIT_IDS;
+exports.CIRCUIT_ACTION_BINDING = CIRCUIT_ACTION_BINDING;
 exports.CIRCUIT_IDS = CIRCUIT_IDS;
 exports.CIRCUIT_SUPPORT_STATUS = CIRCUIT_SUPPORT_STATUS;
 exports.CIRCUIT_VK_PATHS = CIRCUIT_VK_PATHS;
@@ -3375,6 +3412,7 @@ exports.OIDC_DOMAIN_ATTESTATION_PUBLIC_INPUT_LAYOUT = OIDC_DOMAIN_ATTESTATION_PU
 exports.PLANNED_CIRCUIT_IDS = PLANNED_CIRCUIT_IDS;
 exports.ProofportSDK = ProofportSDK;
 exports.SUPPORTED_CIRCUIT_IDS = SUPPORTED_CIRCUIT_IDS;
+exports.circuitActionBinding = circuitActionBinding;
 exports.default = ProofportSDK;
 exports.extractDomainFromPublicInputs = extractDomainFromPublicInputs;
 exports.extractNullifierFromPublicInputs = extractNullifierFromPublicInputs;