@zkproofport-app/sdk 0.2.0 → 0.2.2

package/README.md

@@ -159,6 +159,19 @@ interface WalletSigner {
 
 Any ethers v5/v6 `Signer` is compatible.
 
+#### About challenge-signature
+
+The challenge-signature mechanism was developed **for relay nonce replay prevention**. Each challenge is one-time use and consumed immediately. The signer's recovered address is recorded as `clientId` in relay server logs, which helps the relay operator track requests.
+
+For server-side or headless environments, using an ephemeral random wallet is fine. A persistent wallet (fixed private key) is **not recommended** as it adds unnecessary key management overhead with no functional benefit.
+
+```typescript
+import { Wallet } from 'ethers';
+
+// Server-side: ephemeral wallet per request
+sdk.setSigner(Wallet.createRandom());
+```
+
 ### Step 3: Create Request (via Relay)
 
 `createRelayRequest` authenticates with the relay (challenge-signature), creates a tracked proof request, and returns a deep link.
@@ -281,6 +294,41 @@ if (result.status === 'completed') {
 const verification = await sdk.verifyResponseOnChain(response);
 ```
 
+### Step 7: Extract Scope and Nullifier
+
+After verification, extract the scope and nullifier from the public inputs:
+
+```typescript
+if (result.status === 'completed') {
+  // Extract scope — the keccak256 hash of the scope string you provided
+  const scope = sdk.extractScope(result.publicInputs, result.circuit);
+
+  // Extract nullifier — a unique, deterministic hash per user + scope
+  // Same user with the same scope always produces the same nullifier
+  const nullifier = sdk.extractNullifier(result.publicInputs, result.circuit);
+
+  console.log('Scope:', scope);       // '0x7a6b70726f...'
+  console.log('Nullifier:', nullifier); // '0xabc123...'
+}
+```
+
+The **nullifier** serves as a privacy-preserving user identifier:
+- Deterministic: same user + same scope = same nullifier (enables duplicate detection)
+- Privacy-preserving: the wallet address is never revealed
+- Scope-bound: different scopes produce different nullifiers for the same user
+
+**Standalone utility functions** are also available for use outside the SDK class:
+
+```typescript
+import {
+  extractScopeFromPublicInputs,
+  extractNullifierFromPublicInputs,
+} from '@zkproofport-app/sdk';
+
+const scope = extractScopeFromPublicInputs(publicInputs, 'coinbase_attestation');
+const nullifier = extractNullifierFromPublicInputs(publicInputs, 'coinbase_attestation');
+```
+
 ## Complete Example
 
 End-to-end integration using the relay flow:

package/dist/ProofportSDK.d.ts

@@ -893,5 +893,27 @@ export declare class ProofportSDK {
      * ```
      */
     extractScope(publicInputs: string[], circuit: CircuitType): string | null;
+    /**
+     * Extracts the nullifier (bytes32) from proof public inputs.
+     *
+     * The nullifier is a unique, deterministic hash derived from the user's attestation
+     * and scope. It serves as a privacy-preserving user identifier — the same user
+     * with the same scope always produces the same nullifier, enabling duplicate
+     * detection without revealing the wallet address.
+     *
+     * @param publicInputs - Array of hex-encoded field elements from proof result
+     * @param circuit - Circuit type that produced the public inputs
+     * @returns Nullifier as hex string (bytes32), or null if publicInputs too short
+     *
+     * @example
+     * ```typescript
+     * const result = await sdk.waitForProof(relay.requestId);
+     * if (result.status === 'completed') {
+     *   const nullifier = sdk.extractNullifier(result.publicInputs, result.circuit);
+     *   console.log('Nullifier:', nullifier); // '0xabc123...'
+     * }
+     * ```
+     */
+    extractNullifier(publicInputs: string[], circuit: CircuitType): string | null;
 }
 export default ProofportSDK;

package/dist/constants.d.ts

@@ -145,6 +145,8 @@ export declare const COINBASE_ATTESTATION_PUBLIC_INPUT_LAYOUT: {
     readonly MERKLE_ROOT_END: 63;
     readonly SCOPE_START: 64;
     readonly SCOPE_END: 95;
+    readonly NULLIFIER_START: 96;
+    readonly NULLIFIER_END: 127;
 };
 /**
  * Coinbase Country Attestation circuit public input layout (byte offsets).
@@ -178,4 +180,6 @@ export declare const COINBASE_COUNTRY_PUBLIC_INPUT_LAYOUT: {
     readonly IS_INCLUDED: 85;
     readonly SCOPE_START: 86;
     readonly SCOPE_END: 117;
+    readonly NULLIFIER_START: 118;
+    readonly NULLIFIER_END: 149;
 };

package/dist/index.d.ts

@@ -26,4 +26,6 @@
  * ```
  */
 export { ProofportSDK, default } from './ProofportSDK';
+export { extractScopeFromPublicInputs, extractNullifierFromPublicInputs, } from './verifier';
+export { COINBASE_ATTESTATION_PUBLIC_INPUT_LAYOUT, COINBASE_COUNTRY_PUBLIC_INPUT_LAYOUT, } from './constants';
 export type { CircuitType, ProofRequestStatus, CoinbaseKycInputs, CoinbaseCountryInputs, CircuitInputs, ProofRequest, ProofResponse, QRCodeOptions, VerifierContract, ProofportConfig, ChallengeResponse, WalletSigner, RelayProofRequest, RelayProofResult, SDKEnvironment, } from './types';

package/dist/index.esm.js

@@ -135,6 +135,69 @@ const DEFAULT_REQUEST_EXPIRY_MS = 10 * 60 * 1000;
  * ```
  */
 const MAX_QR_DATA_SIZE = 2953; // Version 40 with L error correction
+/**
+ * Coinbase Attestation circuit public input layout (byte offsets).
+ * Defines the byte positions of each field in the flattened public inputs array.
+ *
+ * Public inputs are packed as bytes32 values:
+ * - signal_hash: bytes 0-31
+ * - merkle_root: bytes 32-63
+ * - scope: bytes 64-95
+ *
+ * @example
+ * ```typescript
+ * const publicInputs = response.publicInputs;
+ * const signalHash = publicInputs.slice(
+ *   COINBASE_ATTESTATION_PUBLIC_INPUT_LAYOUT.SIGNAL_HASH_START,
+ *   COINBASE_ATTESTATION_PUBLIC_INPUT_LAYOUT.SIGNAL_HASH_END + 1
+ * );
+ * ```
+ */
+const COINBASE_ATTESTATION_PUBLIC_INPUT_LAYOUT = {
+    SIGNAL_HASH_START: 0,
+    SIGNAL_HASH_END: 31,
+    MERKLE_ROOT_START: 32,
+    MERKLE_ROOT_END: 63,
+    SCOPE_START: 64,
+    SCOPE_END: 95,
+    NULLIFIER_START: 96,
+    NULLIFIER_END: 127,
+};
+/**
+ * Coinbase Country Attestation circuit public input layout (byte offsets).
+ * Defines the byte positions of each field in the flattened public inputs array.
+ *
+ * Public inputs are packed as bytes32 values:
+ * - signal_hash: bytes 0-31
+ * - merkle_root: bytes 32-63
+ * - country_list: bytes 64-83 (20 bytes for 10 countries)
+ * - country_list_length: byte 84
+ * - is_included: byte 85
+ * - scope: bytes 86-117
+ *
+ * @example
+ * ```typescript
+ * const publicInputs = response.publicInputs;
+ * const countryList = publicInputs.slice(
+ *   COINBASE_COUNTRY_PUBLIC_INPUT_LAYOUT.COUNTRY_LIST_START,
+ *   COINBASE_COUNTRY_PUBLIC_INPUT_LAYOUT.COUNTRY_LIST_END + 1
+ * );
+ * ```
+ */
+const COINBASE_COUNTRY_PUBLIC_INPUT_LAYOUT = {
+    SIGNAL_HASH_START: 0,
+    SIGNAL_HASH_END: 31,
+    MERKLE_ROOT_START: 32,
+    MERKLE_ROOT_END: 63,
+    COUNTRY_LIST_START: 64,
+    COUNTRY_LIST_END: 83,
+    COUNTRY_LIST_LENGTH: 84,
+    IS_INCLUDED: 85,
+    SCOPE_START: 86,
+    SCOPE_END: 117,
+    NULLIFIER_START: 118,
+    NULLIFIER_END: 149,
+};
 
 /**
  * Deep Link utilities for ZKProofport SDK
@@ -3727,6 +3790,39 @@ function extractScopeFromPublicInputs(publicInputsHex, circuit) {
     const scopeFields = publicInputsHex.slice(start, end + 1);
     return reconstructBytes32FromFields(scopeFields);
 }
+/**
+ * Extracts the nullifier (bytes32) from public inputs based on circuit type.
+ *
+ * The nullifier is a unique, deterministic hash derived from the user's attestation
+ * and scope. It serves as a privacy-preserving user identifier — the same user
+ * with the same scope always produces the same nullifier, enabling duplicate
+ * detection without revealing the wallet address.
+ *
+ * @param publicInputsHex - Array of hex-encoded field elements
+ * @param circuit - Circuit type (defaults to coinbase_attestation)
+ * @returns Nullifier as hex string (bytes32), or null if publicInputs too short
+ *
+ * @example
+ * ```typescript
+ * const nullifier = extractNullifierFromPublicInputs(publicInputs, 'coinbase_attestation');
+ * console.log(nullifier); // '0xabc123...'
+ * ```
+ */
+function extractNullifierFromPublicInputs(publicInputsHex, circuit) {
+    let start, end;
+    if (circuit === 'coinbase_country_attestation') {
+        start = 118;
+        end = 149;
+    }
+    else {
+        start = 96;
+        end = 127;
+    }
+    if (publicInputsHex.length <= end)
+        return null;
+    const nullifierFields = publicInputsHex.slice(start, end + 1);
+    return reconstructBytes32FromFields(nullifierFields);
+}
 /** @internal Reconstruct a bytes32 value from 32 individual field elements */
 function reconstructBytes32FromFields(fields) {
     if (fields.length !== 32) {
@@ -4907,7 +5003,31 @@ class ProofportSDK {
     extractScope(publicInputs, circuit) {
         return extractScopeFromPublicInputs(publicInputs, circuit);
     }
+    /**
+     * Extracts the nullifier (bytes32) from proof public inputs.
+     *
+     * The nullifier is a unique, deterministic hash derived from the user's attestation
+     * and scope. It serves as a privacy-preserving user identifier — the same user
+     * with the same scope always produces the same nullifier, enabling duplicate
+     * detection without revealing the wallet address.
+     *
+     * @param publicInputs - Array of hex-encoded field elements from proof result
+     * @param circuit - Circuit type that produced the public inputs
+     * @returns Nullifier as hex string (bytes32), or null if publicInputs too short
+     *
+     * @example
+     * ```typescript
+     * const result = await sdk.waitForProof(relay.requestId);
+     * if (result.status === 'completed') {
+     *   const nullifier = sdk.extractNullifier(result.publicInputs, result.circuit);
+     *   console.log('Nullifier:', nullifier); // '0xabc123...'
+     * }
+     * ```
+     */
+    extractNullifier(publicInputs, circuit) {
+        return extractNullifierFromPublicInputs(publicInputs, circuit);
+    }
 }
 
-export { ProofportSDK, ProofportSDK as default };
+export { COINBASE_ATTESTATION_PUBLIC_INPUT_LAYOUT, COINBASE_COUNTRY_PUBLIC_INPUT_LAYOUT, ProofportSDK, ProofportSDK as default, extractNullifierFromPublicInputs, extractScopeFromPublicInputs };
 //# sourceMappingURL=index.esm.js.map