@zkproofport-app/sdk 0.5.0-beta.4 → 0.5.0-beta.6

package/README.md

@@ -177,6 +177,7 @@ Proves that a user has completed Coinbase KYC identity verification without reve
 | `scope` | `string` | Yes | Application-specific identifier (e.g., your domain). Ensures proof uniqueness per app. |
 | `userAddress` | `string` | No | Address to prove the attestation for. Omit it and the mobile app asks the user to connect a wallet. |
 | `rawTransaction` | `string` | No | Pre-fetched attestation transaction data. Omit it and the app fetches the attestation itself. |
+| `action` | `TypedAction` | No | One EIP-712 action for the wallet to sign and the proof to carry. Without one the wallet signs the request's signal hash. See [Which circuits take an action](#which-circuits-take-an-action). |
 
 ```typescript
 const relay = await sdk.createRelayRequest('coinbase_attestation', {
@@ -184,15 +185,19 @@ const relay = await sdk.createRelayRequest('coinbase_attestation', {
 });
 ```
 
+Its nullifier is `keccak(keccak(wallet ++ keccak("coinbase_attestation")) ++ scope)`:
+one wallet in one scope has exactly one nullifier.
+
 ### `coinbase_country_attestation`
 
-Proves a user's country based on Coinbase verification, supporting inclusion and exclusion checks, without revealing the actual country. Requires a wallet signer.
+Proves a user's country based on Coinbase verification, supporting inclusion and exclusion checks, without revealing the actual country. Requires a wallet signer. Like Coinbase KYC, it can authorize one EIP-712 action, and the attestation is confirmed unrevoked — for the very country being proved — right before proving (`attested_at`, checked against your clock).
 
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
 | `scope` | `string` | Yes | Application-specific identifier |
-| `countryList` | `string[]` | Yes | ISO 3166-1 alpha-2 country codes (e.g., `['US', 'KR']`) |
+| `countryList` | `string[]` | Yes | 1 to 10 upper-case ISO 3166-1 alpha-2 country codes (e.g., `['US', 'KR']`); anything else is refused when the request is created |
 | `isIncluded` | `boolean` | Yes | `true` = prove user IS from listed countries; `false` = prove user is NOT |
+| `action` | `TypedAction` | No | An EIP-712 action the wallet signs instead of the request's signal hash |
 | `userAddress` | `string` | No | Address to prove the attestation for (optional, as above) |
 | `rawTransaction` | `string` | No | Pre-fetched attestation transaction data (optional, as above) |
 
@@ -204,6 +209,24 @@ const relay = await sdk.createRelayRequest('coinbase_country_attestation', {
 });
 ```
 
+Its nullifier is `keccak(keccak(wallet ++ keccak("coinbase_country_attestation")) ++ scope)`.
+
+The list and the direction are public inputs the prover chooses; the wallet's
+signature does not cover them. `verifyResponseOnChain` and
+`verifyResponseOffChain` therefore compare them with the request this SDK
+instance created (relay or deep link) and refuse a proof made against any other
+list. A response the instance cannot place is refused; pass the request's
+condition explicitly in that case:
+
+```typescript
+await sdk.verifyResponseOnChain(response, provider, {
+  countryCondition: { countryList: ['US', 'KR'], isIncluded: true },
+});
+```
+
+`checkCountryListMatches(publicInputs, { countryList, isIncluded })` is the same
+check on its own (codes compared as a set, order does not matter).
+
 ### `oidc_domain_attestation`
 
 Prove email domain affiliation via OIDC Sign-In. The mobile app handles authentication and proof generation entirely on-device — the user's email is never revealed. No wallet signer is required.
@@ -263,7 +286,7 @@ const { deepLink } = await sdk.createRelayRequest(
 **An action is optional here.** Send one
 and the wallet signs EIP-712 typed data, so the person reads named fields and
 the proof carries what they approved. Send none and the wallet signs the
-request's signal hash, exactly as Coinbase KYC does. The circuit itself
+request's signal hash. Coinbase KYC branches the same way. The circuit itself
 branches, and it refuses a request that tries to be both: with an action the
 signal hash must be empty, without one the EIP-712 pair must be.
 
@@ -284,8 +307,8 @@ await sdk.createRelayRequest(
 ```
 
 Its public inputs are `signal_hash`, `domain_separator`, `action_hash`,
-`signer_list_merkle_root`, `scope`, `nullifier` — 64 bytes longer than the Coinbase layout it used to share. Anything holding the
-old offsets reads the Merkle root where the nullifier is.
+`signer_list_merkle_root`, `scope`, `nullifier`: Coinbase KYC's order without
+its final `attested_at`.
 
 One more difference worth knowing if you count people: its nullifier is
 `keccak(keccak(wallet ++ keccak("giwa_attestation")) ++ scope)`. The wallet and
@@ -329,14 +352,16 @@ circuit names are special:
 
 | What the circuit does with an action | Circuits |
 |---|---|
-| Signs it when present, signs the signal hash when not | `giwa_attestation`, `dojang_playground` |
-| Has no action inputs — sending one is refused, not ignored | Coinbase KYC, Coinbase country, OIDC domain |
+| Signs it when present, signs the signal hash when not | `coinbase_attestation`, `coinbase_country_attestation`, `giwa_attestation`, `dojang_playground` |
+| Has no action inputs — sending one is refused, not ignored | OIDC domain |
 
 ```typescript
 import { circuitActionBinding } from '@zkproofport-app/sdk';
 
 circuitActionBinding('giwa_attestation');  // 'optional'
-circuitActionBinding('coinbase_attestation'); // 'none'
+circuitActionBinding('coinbase_attestation'); // 'optional'
+circuitActionBinding('coinbase_country_attestation'); // 'optional'
+circuitActionBinding('oidc_domain_attestation'); // 'none'
 ```
 
 Sending an action to a circuit that cannot prove one is an error rather than a
@@ -615,7 +640,7 @@ When you are done, `sdk.disconnect()` closes any open socket.
   status: 'completed',
   circuit: 'coinbase_attestation',
   proof: '0x1f8b0a…',                       // proof bytes, opaque
-  publicInputs: ['0x00…2f', '0x00…a1', …],  // ordered — 128 entries for this circuit
+  publicInputs: ['0x00…2f', '0x00…a1', …],  // ordered — 193 entries for this circuit
   verifierAddress: '0x…',                   // the verifier the app reports (checked, not trusted)
   chainId: …,                               // the network the app reports (checked, not trusted)
   deepLink: 'zkproofport://proof-request?data=…',
@@ -729,7 +754,7 @@ For OIDC domain proofs the SDK first checks what the proof says about the sign-i
 
 The SDK also checks that the proof was made with a signing key Google or Microsoft actually publishes. That key is part of the proof's public inputs, so a proof made with a self-generated key would otherwise pass the contract. The SDK fetches the provider's published keys, caches them as the provider's own cache headers allow, and returns `{ valid: false, error }` when the key is not among them or the keys cannot be fetched. Every verify method does this; there is nothing to call separately.
 
-For Coinbase KYC, Coinbase country and GIWA proofs the SDK checks that the attestation's signer belongs to the published signer set: the proof carries the root of the signer list it was made against, and a proof made against any other list is refused with `{ valid: false, error }`. This too runs in every verify method.
+For Coinbase KYC, Coinbase country and GIWA proofs the SDK checks that the attestation's signer belongs to the published signer set: the proof carries the root of the signer list it was made against, and a proof made against any other list is refused with `{ valid: false, error }`. A Coinbase KYC proof also names the time its attestation was confirmed unrevoked; it must be within the last 15 minutes (and not more than 5 minutes ahead of your clock), so verify a Coinbase KYC proof when you receive it rather than re-verifying a stored one later. This too runs in every verify method.
 
 The one limit: a proof made with a key the provider has already withdrawn, which this process never saw while it was published, cannot be checked and is refused. Keys seen while published stay acceptable for 1 hour after they were last listed.
 
@@ -885,7 +910,7 @@ const domain = extractDomainFromPublicInputs(publicInputs, 'oidc_domain_attestat
 // domain: 'example.com', or null if the circuit doesn't match or inputs are insufficient
 ```
 
-Omitting the circuit argument falls back to the `coinbase_attestation` layout, which is why the examples above always pass it explicitly.
+The circuit argument is required: the layout differs per circuit, and an omitted or unknown circuit id throws an error naming the known ones.
 
 ## Complete Example
 
@@ -1011,7 +1036,7 @@ import type {
 | `CircuitType` | Alias of `CircuitId`. Kept as the name used throughout `ProofRequest`, `ProofResponse` and the SDK methods |
 | `ProofRequestStatus` | `'pending' \| 'completed' \| 'error' \| 'cancelled'` — the status on a `ProofResponse` |
 | `CoinbaseKycInputs` | Inputs for `coinbase_attestation`: `{ scope, userAddress?, rawTransaction? }` |
-| `CoinbaseCountryInputs` | Inputs for `coinbase_country_attestation`: `{ scope, countryList, isIncluded, userAddress?, rawTransaction? }` |
+| `CoinbaseCountryInputs` | Inputs for `coinbase_country_attestation`: `{ scope, countryList, isIncluded, action?, userAddress?, rawTransaction? }` |
 | `OidcDomainInputs` | Inputs for `oidc_domain_attestation`: `{ domain, scope, provider? }` |
 | `ActionBoundInputs` | Inputs for the circuits that can bind an EIP-712 action: `{ scope, action?, userAddress?, rawTransaction? }`. Whether the action is required is the circuit's property, in `CIRCUIT_ACTION_BINDING` — optional for `giwa_attestation` and `dojang_playground` |
 | `GiwaAttestationInputs` | Alias of `ActionBoundInputs`, for `giwa_attestation` |
@@ -1055,7 +1080,7 @@ import {
 Two rules hold for every table below:
 
 - **Every number is an index into `publicInputs`, and `_END` is inclusive.** Slice with `slice(START, END + 1)`.
-- **One entry is one field element, not one 32-byte value.** A `bytes32` such as a scope or a nullifier is spread over 32 consecutive entries, each holding a single byte in its low byte: `publicInputs[64] === '0x00…2f'` is the byte `0x2f`. Rebuild it by concatenating those 32 low bytes. The one exception is the OIDC RSA modulus, whose 18 entries each hold a 128-bit limb.
+- **One entry is one field element, not one 32-byte value.** A `bytes32` such as a scope or a nullifier is spread over 32 consecutive entries, each holding a single byte in its low byte: `publicInputs[128] === '0x00…2f'` is the byte `0x2f`. Rebuild it by concatenating those 32 low bytes. The one exception is the OIDC RSA modulus, whose 18 entries each hold a 128-bit limb.
 
 ```typescript
 const L = COINBASE_ATTESTATION_PUBLIC_INPUT_LAYOUT;
@@ -1067,28 +1092,34 @@ const toBytes32 = (fields: string[]): string =>
 const signalHash = toBytes32(publicInputs.slice(L.SIGNAL_HASH_START, L.SIGNAL_HASH_END + 1));
 ```
 
-### `coinbase_attestation` — 128 entries
+### `coinbase_attestation` — 193 entries
 
 | Index | Constants | Circuit field | What it is |
 |-------|-----------|---------------|------------|
-| 0–31 | `SIGNAL_HASH_START` / `_END` | `signal_hash` | `bytes32` anti-replay challenge for the request |
-| 32–63 | `MERKLE_ROOT_START` / `_END` | `signer_list_merkle_root` | `bytes32` root of the Coinbase attestation-signer list the proof was checked against |
-| 64–95 | `SCOPE_START` / `_END` | `scope` | `bytes32` — `keccak256` of your scope string. Compare it (Step 8) |
-| 96–127 | `NULLIFIER_START` / `_END` | `nullifier` | `bytes32`, unique per user and scope |
+| 0–31 | `SIGNAL_HASH_START` / `_END` | `signal_hash` | `bytes32` anti-replay challenge for the request; zero when the wallet signed an EIP-712 action |
+| 32–63 | `DOMAIN_SEPARATOR_START` / `_END` | `domain_separator` | EIP-712 domain separator of the signed action; zero without one |
+| 64–95 | `ACTION_HASH_START` / `_END` | `action_hash` | EIP-712 struct hash of the signed action; zero without one |
+| 96–127 | `MERKLE_ROOT_START` / `_END` | `signer_list_merkle_root` | `bytes32` root of the Coinbase attestation-signer list the proof was checked against |
+| 128–159 | `SCOPE_START` / `_END` | `scope` | `bytes32` — `keccak256` of your scope string. Compare it (Step 8) |
+| 160–191 | `NULLIFIER_START` / `_END` | `nullifier` | `bytes32`, unique per wallet and scope |
+| 192 | `ATTESTED_AT` | `attested_at` | Unix seconds at which the attestation was confirmed unrevoked; checked against your clock by every verify method |
 
-### `coinbase_country_attestation` — 150 entries
+### `coinbase_country_attestation` — 215 entries
 
 | Index | Constants | Circuit field | What it is |
 |-------|-----------|---------------|------------|
-| 0–31 | `SIGNAL_HASH_START` / `_END` | `signal_hash` | `bytes32` anti-replay challenge |
-| 32–63 | `MERKLE_ROOT_START` / `_END` | `signer_list_merkle_root` | `bytes32` signer-list root |
-| 64–83 | `COUNTRY_LIST_START` / `_END` | `country_list` | 10 slots of 2 ASCII bytes, one byte per entry — entries 64–65 are the first code, 66–67 the second, and so on, in the order you sent them. Only the first `country_list_length` slots are meaningful; the rest are zero |
-| 84 | `COUNTRY_LIST_LENGTH` | `country_list_length` | How many of those 10 slots count |
-| 85 | `IS_INCLUDED` | `is_included` | `1` = the user **is** in the list, `0` = the user is **not** |
-| 86–117 | `SCOPE_START` / `_END` | `scope` | `bytes32` scope hash |
-| 118–149 | `NULLIFIER_START` / `_END` | `nullifier` | `bytes32`, unique per user and scope |
-
-The country list and the `is_included` flag are public inputs, which means the proof is only as strong as the list it was proved against. Read indices 64–85 back and confirm they are the list and the direction you asked for; a valid proof against a different list is still a valid proof.
+| 0–31 | `SIGNAL_HASH_START` / `_END` | `signal_hash` | `bytes32` anti-replay challenge; zero when the wallet signed an EIP-712 action |
+| 32–63 | `DOMAIN_SEPARATOR_START` / `_END` | `domain_separator` | EIP-712 domain separator of the signed action; zero without one |
+| 64–95 | `ACTION_HASH_START` / `_END` | `action_hash` | EIP-712 struct hash of the signed action; zero without one |
+| 96–127 | `MERKLE_ROOT_START` / `_END` | `signer_list_merkle_root` | `bytes32` signer-list root |
+| 128–147 | `COUNTRY_LIST_START` / `_END` | `country_list` | 10 slots of 2 ASCII bytes, one byte per entry — entries 128–129 are the first code, 130–131 the second, and so on, in the order you sent them. Only the first `country_list_length` slots are meaningful; the rest are zero |
+| 148 | `COUNTRY_LIST_LENGTH` | `country_list_length` | How many of those 10 slots count |
+| 149 | `IS_INCLUDED` | `is_included` | `1` = the user **is** in the list, `0` = the user is **not** |
+| 150–181 | `SCOPE_START` / `_END` | `scope` | `bytes32` scope hash |
+| 182–213 | `NULLIFIER_START` / `_END` | `nullifier` | `bytes32`, unique per wallet and scope |
+| 214 | `ATTESTED_AT` | `attested_at` | Unix seconds at which the attestation was confirmed unrevoked; checked against your clock by every verify method |
+
+The country list and the `is_included` flag are public inputs, which means the proof is only as strong as the list it was proved against. The `verifyResponse*` methods compare them with your request (above); if you verify through another path, call `checkCountryListMatches` or read indices 128–149 back yourself — a valid proof against a different list is still a valid proof.
 
 ### `oidc_domain_attestation` — 214 entries
 

package/dist/ProofportSDK.d.ts

@@ -3,7 +3,7 @@
  */
 import type { ProofRequest, ProofResponse, CircuitType, CircuitInputs, ProofportConfig, QRCodeOptions, ChallengeResponse, WalletSigner, RelayProofRequest, RelayProofResult } from './types';
 import { type OffChainVerifyOptions } from './offChainVerifier';
-import { type OidcRequestContext } from './verifier';
+import { type CountryCondition, type OidcRequestContext } from './verifier';
 import type { SDKEnvironment } from './types';
 /**
  * Main SDK class for interacting with the ZKProofport mobile app.
@@ -51,6 +51,12 @@ export declare class ProofportSDK {
     private relayRequests;
     /** Bound on {@link relayRequests}; a dApp that verifies later can pass the request explicitly. */
     static readonly MAX_REMEMBERED_RELAY_REQUESTS = 1000;
+    /**
+     * requestId -> the country list and direction of the Coinbase Country relay
+     * requests this instance created, so verifyResponse* can hold the proof to
+     * them. Bounded like {@link relayRequests}.
+     */
+    private countryRequests;
     private signer;
     private relayUrl;
     private socket;
@@ -494,6 +500,7 @@ export declare class ProofportSDK {
     verifyOnChain(circuit: CircuitType, proof: string, publicInputs: string[], providerOrSigner?: any, options?: {
         request?: OidcRequestContext;
         signerVariant?: string;
+        countryCondition?: CountryCondition;
     }): Promise<{
         valid: boolean;
         error?: string;
@@ -509,6 +516,17 @@ export declare class ProofportSDK {
     private oidcRequestFor;
     /** @internal Remember a relay request's scope for verifyResponse*. */
     private rememberRelayRequest;
+    /**
+     * The country list and direction a `coinbase_country_attestation` response
+     * must have been proved against: the one the caller passed, else the relay
+     * request this instance created under the response's requestId, else the
+     * deep-link request still pending under it. `{ error }` when there is none:
+     * the proof's list is the prover's choice, so a response this SDK cannot
+     * place is refused rather than accepted for whatever list it carries.
+     */
+    private countryConditionFor;
+    /** @internal Remember a Coinbase Country relay request's list and direction for verifyResponse*. */
+    private rememberCountryRequest;
     /**
      * The verifier for a circuit: the one the dApp configured, otherwise the
      * pinned deployment on the chain this SDK's environment verifies that
@@ -527,6 +545,10 @@ export declare class ProofportSDK {
      * @param options.request - For `oidc_domain_attestation`: the `{ scope, requestId }`
      *   the response answers. Not needed for a relay request this SDK instance
      *   created; an OIDC response this instance cannot place is refused without it.
+     * @param options.countryCondition - For `coinbase_country_attestation`: the
+     *   `{ countryList, isIncluded }` the request asked for. Not needed for a
+     *   request this SDK instance created (relay or deep link); a Country response
+     *   this instance cannot place is refused without it.
      *
      * @returns Promise resolving to verification result with valid boolean and optional error message
      *
@@ -555,6 +577,7 @@ export declare class ProofportSDK {
      */
     verifyResponseOnChain(response: ProofResponse, providerOrSigner?: any, options?: {
         request?: OidcRequestContext;
+        countryCondition?: CountryCondition;
     }): Promise<{
         valid: boolean;
         error?: string;

package/dist/constants.d.ts

@@ -83,7 +83,7 @@ export declare const DEEP_LINK_HOSTS: {
  * ```typescript
  * const metadata = CIRCUIT_METADATA['coinbase_attestation'];
  * console.log(metadata.name); // "Coinbase KYC"
- * console.log(metadata.publicInputsCount); // 128
+ * console.log(metadata.publicInputsCount); // 193
  * ```
  */
 export declare const CIRCUIT_METADATA: Record<CircuitType, {
@@ -123,4 +123,4 @@ export declare const DEFAULT_REQUEST_EXPIRY_MS: number;
  * ```
  */
 export declare const MAX_QR_DATA_SIZE = 2953;
-export { VERIFIER_ABI, RPC_ENDPOINTS, COINBASE_ATTESTATION_PUBLIC_INPUT_LAYOUT, COINBASE_COUNTRY_PUBLIC_INPUT_LAYOUT, OIDC_DOMAIN_ATTESTATION_PUBLIC_INPUT_LAYOUT, } from '@zkproofport-app/core';
+export { VERIFIER_ABI, RPC_ENDPOINTS, COINBASE_ATTESTATION_PUBLIC_INPUT_LAYOUT, COINBASE_COUNTRY_PUBLIC_INPUT_LAYOUT, COINBASE_COUNTRY_PUBLIC_INPUT_COUNT, OIDC_DOMAIN_ATTESTATION_PUBLIC_INPUT_LAYOUT, } from '@zkproofport-app/core';

package/dist/index.d.ts

@@ -34,7 +34,7 @@ export { PINNED_VERIFIERS, PINNED_VARIANT_VERIFIERS, getPinnedVerifier, getPinne
 export type { PinnedVerifier } from './verifier';
 export { checkOidcPolicy, deriveOidcNonceBinding, oidcAudienceHash, OIDC_ALLOWED_AUDIENCES, OIDC_NONCE_DOMAIN, OIDC_NOW_MAX_AGE_SECONDS, OIDC_NOW_MAX_FUTURE_SECONDS, OIDC_V1_PUBLIC_INPUT_COUNT, OIDC_V2_PUBLIC_INPUT_COUNT, } from './verifier';
 export type { OidcRequestContext, OidcAudience, OidcNonceMode } from './verifier';
-export { COINBASE_ATTESTATION_PUBLIC_INPUT_LAYOUT, COINBASE_COUNTRY_PUBLIC_INPUT_LAYOUT, OIDC_DOMAIN_ATTESTATION_PUBLIC_INPUT_LAYOUT, } from './constants';
+export { COINBASE_ATTESTATION_PUBLIC_INPUT_LAYOUT, COINBASE_COUNTRY_PUBLIC_INPUT_LAYOUT, COINBASE_COUNTRY_PUBLIC_INPUT_COUNT, OIDC_DOMAIN_ATTESTATION_PUBLIC_INPUT_LAYOUT, } from './constants';
 export type { CircuitId, CircuitSupportStatus, SignerVariant, CircuitPackage } from './circuits';
 export { CIRCUIT_ACTION_BINDING, circuitActionBinding, } from './circuits';
 export type { CircuitActionBinding } from './circuits';

package/dist/index.esm.js

@@ -1,5 +1,5 @@
-import { checkProofIssuer, parseProofForOnChain, verifyProofOnChain, getPinnedVerifier, extractScopeFromPublicInputs, extractNullifierFromPublicInputs, extractDomainFromPublicInputs } from '@zkproofport-app/core';
-export { COINBASE_ATTESTATION_PUBLIC_INPUT_LAYOUT, COINBASE_COUNTRY_PUBLIC_INPUT_LAYOUT, OIDC_ALLOWED_AUDIENCES, OIDC_DOMAIN_ATTESTATION_PUBLIC_INPUT_LAYOUT, OIDC_NONCE_DOMAIN, OIDC_NOW_MAX_AGE_SECONDS, OIDC_NOW_MAX_FUTURE_SECONDS, OIDC_V1_PUBLIC_INPUT_COUNT, OIDC_V2_PUBLIC_INPUT_COUNT, PINNED_VARIANT_VERIFIERS, PINNED_VERIFIERS, checkOidcPolicy, deriveOidcNonceBinding, extractDomainFromPublicInputs, extractNullifierFromPublicInputs, extractScopeFromPublicInputs, getPinnedVariantVerifier, getPinnedVerifier, oidcAudienceHash } from '@zkproofport-app/core';
+import { countryListError, checkProofIssuer, parseProofForOnChain, verifyProofOnChain, getPinnedVerifier, extractScopeFromPublicInputs, extractNullifierFromPublicInputs, extractDomainFromPublicInputs } from '@zkproofport-app/core';
+export { COINBASE_ATTESTATION_PUBLIC_INPUT_LAYOUT, COINBASE_COUNTRY_PUBLIC_INPUT_COUNT, COINBASE_COUNTRY_PUBLIC_INPUT_LAYOUT, OIDC_ALLOWED_AUDIENCES, OIDC_DOMAIN_ATTESTATION_PUBLIC_INPUT_LAYOUT, OIDC_NONCE_DOMAIN, OIDC_NOW_MAX_AGE_SECONDS, OIDC_NOW_MAX_FUTURE_SECONDS, OIDC_V1_PUBLIC_INPUT_COUNT, OIDC_V2_PUBLIC_INPUT_COUNT, PINNED_VARIANT_VERIFIERS, PINNED_VERIFIERS, checkOidcPolicy, deriveOidcNonceBinding, extractDomainFromPublicInputs, extractNullifierFromPublicInputs, extractScopeFromPublicInputs, getPinnedVariantVerifier, getPinnedVerifier, oidcAudienceHash } from '@zkproofport-app/core';
 import { isCircuitId, ALL_CIRCUIT_IDS, circuitActionBinding, resolveSignerVariant, getCircuitPackage, CIRCUIT_NEEDS_WALLET_SIGNATURE } from '@zkproofport-app/core/circuits';
 export { ALL_CIRCUIT_IDS, CIRCUIT_ACTION_BINDING, CIRCUIT_IDS, CIRCUIT_PACKAGES, CIRCUIT_SUPPORT_STATUS, CIRCUIT_VK_PATHS, EXPERIMENTAL_CIRCUIT_IDS, PLANNED_CIRCUIT_IDS, SIGNER_VARIANTS, SUPPORTED_CIRCUIT_IDS, circuitActionBinding, evmProofByteLength, getCircuitPackage, getCircuitSupportStatus, isCircuitId, isSignerVariant, isSupportedCircuitId, resolveSignerVariant, signerVariantsOf } from '@zkproofport-app/core/circuits';
 import { validateTypedAction } from '@zkproofport-app/core/typedAction';
@@ -90,27 +90,32 @@ const DEEP_LINK_HOSTS = {
  * ```typescript
  * const metadata = CIRCUIT_METADATA['coinbase_attestation'];
  * console.log(metadata.name); // "Coinbase KYC"
- * console.log(metadata.publicInputsCount); // 128
+ * console.log(metadata.publicInputsCount); // 193
  * ```
  */
 const CIRCUIT_METADATA = {
     coinbase_attestation: {
         name: 'Coinbase KYC',
-        description: 'Prove Coinbase identity verification',
-        // 4 x `pub [u8; 32]` in coinbase-attestation/src/main.nr, flattened to
-        // bytes: signal_hash, signer_list_merkle_root, scope, nullifier.
-        // Read 2 here until 2026-09-04, which was wrong under any reading —
-        // the circuit has never had two public inputs, logical or flattened.
-        publicInputsCount: 128,
-        publicInputNames: ['signal_hash', 'signer_list_merkle_root'],
+        description: 'Prove Coinbase identity verification, optionally authorizing one EIP-712 action',
+        // Coinbase KYC v2 (coinbase-attestation-v2/src/main.nr): GIWA's six
+        // `pub [u8; 32]` in its order, then `attested_at: pub u64` = 193 fields.
+        // signal_hash 0-31, domain_separator 32-63, action_hash 64-95,
+        // signer_list_merkle_root 96-127, scope 128-159, nullifier 160-191,
+        // attested_at 192. v1's 128 fields are refused on every verify path.
+        publicInputsCount: 193,
+        publicInputNames: ['signal_hash', 'domain_separator', 'action_hash', 'signer_list_merkle_root', 'scope', 'nullifier', 'attested_at'],
     },
     coinbase_country_attestation: {
         name: 'Coinbase Country',
-        description: 'Prove Coinbase country verification',
-        // 32 + 32 + (10 x 2) + 1 + 1 + 32 + 32 = 150, counted off
-        // coinbase-country-attestation/src/main.nr. Read 14 until 2026-09-04.
-        publicInputsCount: 150,
-        publicInputNames: ['signal_hash', 'signer_list_merkle_root', 'country_list', 'country_list_length', 'is_included'],
+        description: 'Prove Coinbase country verification, optionally authorizing one EIP-712 action',
+        // Coinbase Country v2 (coinbase-country-attestation-v2/src/main.nr):
+        // signal_hash 0-31, domain_separator 32-63, action_hash 64-95,
+        // signer_list_merkle_root 96-127, country_list 128-147 (10 x 2 bytes),
+        // country_list_length 148, is_included 149, scope 150-181,
+        // nullifier 182-213, attested_at 214 = 215 fields. v1's 150 fields are
+        // refused on every verify path.
+        publicInputsCount: 215,
+        publicInputNames: ['signal_hash', 'domain_separator', 'action_hash', 'signer_list_merkle_root', 'country_list', 'country_list_length', 'is_included', 'scope', 'nullifier', 'attested_at'],
     },
     oidc_domain_attestation: {
         name: 'OIDC Domain',
@@ -639,11 +644,9 @@ function validateProofRequest(request) {
         if (inputs.userAddress && !/^0x[a-fA-F0-9]{40}$/.test(inputs.userAddress)) {
             return { valid: false, error: 'Invalid userAddress format' };
         }
-        if (!inputs.countryList || !Array.isArray(inputs.countryList) || inputs.countryList.length === 0) {
-            return { valid: false, error: 'countryList is required and must be a non-empty array' };
-        }
-        if (!inputs.countryList.every(c => typeof c === 'string')) {
-            return { valid: false, error: 'countryList must contain only strings' };
+        const listError = countryListError(inputs.countryList);
+        if (listError) {
+            return { valid: false, error: listError };
         }
         if (typeof inputs.isIncluded !== 'boolean') {
             return { valid: false, error: 'isIncluded is required and must be a boolean' };
@@ -3937,7 +3940,7 @@ async function verifyProofOffChain(circuit, proof, publicInputs, options = {}) {
     // their trust anchor as a public input the prover chooses. For OIDC that is
     // the RSA key -- see core's oidcProviderKeys. Checked here so a dApp that
     // verifies off-chain gets the same answer as one that verifies on-chain.
-    const issuer = await checkProofIssuer(circuit, publicInputs, { request: options.request });
+    const issuer = await checkProofIssuer(circuit, publicInputs, { request: options.request, countryCondition: options.countryCondition });
     if (!issuer.ok) {
         return { valid: false, error: issuer.error };
     }
@@ -4097,6 +4100,12 @@ class ProofportSDK {
          * {@link ProofportSDK.MAX_REMEMBERED_RELAY_REQUESTS}.
          */
         this.relayRequests = new Map();
+        /**
+         * requestId -> the country list and direction of the Coinbase Country relay
+         * requests this instance created, so verifyResponse* can hold the proof to
+         * them. Bounded like {@link relayRequests}.
+         */
+        this.countryRequests = new Map();
         this.signer = null;
         this.socket = null;
         /**
@@ -4228,6 +4237,15 @@ class ProofportSDK {
         if (typeof inputs.isIncluded !== 'boolean') {
             throw new Error('isIncluded is required for coinbase_country_attestation circuit');
         }
+        const listError = countryListError(inputs.countryList);
+        if (listError)
+            throw new Error(`${listError} (circuit: coinbase_country_attestation)`);
+        // Coinbase Country v2 binds an action or none, like Coinbase KYC v2.
+        if (inputs.action !== undefined) {
+            const actionError = validateTypedAction(inputs.action);
+            if (actionError)
+                throw new Error(`${actionError} (circuit: coinbase_country_attestation)`);
+        }
         const request = {
             requestId: generateRequestId(),
             circuit: 'coinbase_country_attestation',
@@ -4628,6 +4646,7 @@ class ProofportSDK {
         return verifyProofOnChain(circuit, parsedProof, providerOrSigner, this.verifierTarget(circuit), undefined, {
             request: options.request,
             signerVariant: options.signerVariant,
+            countryCondition: options.countryCondition,
         });
     }
     /**
@@ -4668,6 +4687,43 @@ class ProofportSDK {
             this.relayRequests.delete(oldest);
         }
     }
+    /**
+     * The country list and direction a `coinbase_country_attestation` response
+     * must have been proved against: the one the caller passed, else the relay
+     * request this instance created under the response's requestId, else the
+     * deep-link request still pending under it. `{ error }` when there is none:
+     * the proof's list is the prover's choice, so a response this SDK cannot
+     * place is refused rather than accepted for whatever list it carries.
+     */
+    countryConditionFor(response, explicit) {
+        if (explicit !== undefined)
+            return { condition: explicit };
+        const remembered = this.countryRequests.get(response.requestId);
+        if (remembered)
+            return { condition: remembered };
+        const pending = this.pendingRequests.get(response.requestId);
+        const inputs = pending?.circuit === 'coinbase_country_attestation' ? pending.inputs : undefined;
+        if (inputs && Array.isArray(inputs.countryList) && typeof inputs.isIncluded === 'boolean') {
+            return { condition: { countryList: [...inputs.countryList], isIncluded: inputs.isIncluded } };
+        }
+        return {
+            error: `No Coinbase Country request ${JSON.stringify(response.requestId)} was created by this SDK instance, so the ` +
+                "proof's country list cannot be checked against what was asked. Pass { countryCondition: { countryList, " +
+                'isIncluded } } -- the list and direction of the request you created.',
+        };
+    }
+    /** @internal Remember a Coinbase Country relay request's list and direction for verifyResponse*. */
+    rememberCountryRequest(requestId, inputs) {
+        const i = inputs;
+        if (typeof requestId !== 'string' || !i || !Array.isArray(i.countryList) || typeof i.isIncluded !== 'boolean')
+            return;
+        this.countryRequests.delete(requestId);
+        this.countryRequests.set(requestId, { countryList: [...i.countryList], isIncluded: i.isIncluded });
+        while (this.countryRequests.size > ProofportSDK.MAX_REMEMBERED_RELAY_REQUESTS) {
+            const oldest = this.countryRequests.keys().next().value;
+            this.countryRequests.delete(oldest);
+        }
+    }
     /**
      * The verifier for a circuit: the one the dApp configured, otherwise the
      * pinned deployment on the chain this SDK's environment verifies that
@@ -4696,6 +4752,10 @@ class ProofportSDK {
      * @param options.request - For `oidc_domain_attestation`: the `{ scope, requestId }`
      *   the response answers. Not needed for a relay request this SDK instance
      *   created; an OIDC response this instance cannot place is refused without it.
+     * @param options.countryCondition - For `coinbase_country_attestation`: the
+     *   `{ countryList, isIncluded }` the request asked for. Not needed for a
+     *   request this SDK instance created (relay or deep link); a Country response
+     *   this instance cannot place is refused without it.
      *
      * @returns Promise resolving to verification result with valid boolean and optional error message
      *
@@ -4733,6 +4793,13 @@ class ProofportSDK {
                 return { valid: false, error: found.error };
             request = found.request;
         }
+        let countryCondition;
+        if (response.circuit === 'coinbase_country_attestation') {
+            const found = this.countryConditionFor(response, options.countryCondition);
+            if ('error' in found)
+                return { valid: false, error: found.error };
+            countryCondition = found.condition;
+        }
         const parsedProof = parseProofForOnChain(response.proof, response.publicInputs, response.publicInputs.length);
         // The response's verifierAddress and chainId are a claim to check, never
         // the contract to call: whoever wrote the response would otherwise pick
@@ -4741,7 +4808,7 @@ class ProofportSDK {
         return verifyProofOnChain(response.circuit, parsedProof, providerOrSigner, this.verifierTarget(response.circuit), {
             verifierAddress: response.verifierAddress,
             chainId: response.chainId,
-        }, { request, signerVariant: response.signerVariant });
+        }, { request, signerVariant: response.signerVariant, countryCondition });
     }
     /**
      * Verifies a proof response off-chain, against the circuit's verification key.
@@ -4778,7 +4845,14 @@ class ProofportSDK {
                 return { valid: false, error: found.error };
             request = found.request;
         }
-        return verifyProofOffChain(response.circuit, response.proof, response.publicInputs, { ...options, request, signerVariant: response.signerVariant });
+        let countryCondition;
+        if (response.circuit === 'coinbase_country_attestation') {
+            const found = this.countryConditionFor(response, options?.countryCondition);
+            if ('error' in found)
+                return { valid: false, error: found.error };
+            countryCondition = found.condition;
+        }
+        return verifyProofOffChain(response.circuit, response.proof, response.publicInputs, { ...options, request, countryCondition, signerVariant: response.signerVariant });
     }
     // ============ Utility Methods ============
     /**
@@ -5156,6 +5230,16 @@ class ProofportSDK {
                 }
             }
         }
+        // A Coinbase Country list the circuit would refuse is refused here, before a
+        // challenge is burned, as createProofRequest does.
+        if (circuit === 'coinbase_country_attestation') {
+            const c = inputs;
+            const listError = countryListError(c.countryList);
+            if (listError)
+                throw new Error(`${listError} (circuit: ${circuit})`);
+            if (typeof c.isIncluded !== 'boolean')
+                throw new Error('isIncluded is required for coinbase_country_attestation 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) {
@@ -5211,6 +5295,8 @@ class ProofportSDK {
         }
         const created = await response.json();
         this.rememberRelayRequest(created.requestId, scope);
+        if (circuit === 'coinbase_country_attestation')
+            this.rememberCountryRequest(created.requestId, inputs);
         return created;
     }
     /**