@zkproofport-app/sdk 0.1.3-beta.1 → 0.2.1

package/README.md

@@ -5,17 +5,15 @@
 
 TypeScript SDK for requesting zero-knowledge proofs from the [ZKProofport](https://zkproofport.com) mobile app and verifying them on-chain.
 
-> **Beta** — Currently deployed on **Base Sepolia (testnet)** only. APIs may change before the stable release.
-
 ## How It Works
 
 ```
 ┌──────────────┐     ┌─────────┐     ┌──────────────┐     ┌──────────────────┐
 │ Your Web App │────>│   SDK   │────>│ Relay Server │────>│ ZKProofport App  │
 │              │     │         │     │              │     │                  │
-│              │     │ login + │     │ issues ID,   │     │ - Connects wallet│
-│              │     │ create  │     │ tracks state │     │ - Fetches data   │
-│              │     │ request │     │              │     │ - Generates proof│
+│              │     │ setSigner│    │ issues ID,   │     │ - Connects wallet│
+│              │     │ + create │    │ tracks state │     │ - Fetches data   │
+│              │     │ request  │    │              │     │ - Generates proof│
 └──────┬───────┘     └─────────┘     └──────┬───────┘     └────────┬─────────┘
        │                                    │                      │
        │                                    │<─────────────────────┘
@@ -24,18 +22,18 @@ TypeScript SDK for requesting zero-knowledge proofs from the [ZKProofport](https
        │  v
        │  ┌──────────────────────────────────────────────────┐
        │  │  SDK receives result (WebSocket / polling)       │
-       │  │  (proof, publicInputs, nullifier, status)        │
+       │  │  (proof, publicInputs, status)                    │
        │  └─────────────────────┬────────────────────────────┘
        │                        │
        v                        v
 ┌──────────────┐     ┌──────────────────┐     ┌───────────────────┐
 │  Verify      │────>│  On-chain verify  │────>│  Access granted   │
-│  on-chain    │     │  (Base Sepolia)   │     │  or denied        │
+│  on-chain    │     │  (Base Mainnet)   │     │  or denied        │
 └──────────────┘     └──────────────────┘     └───────────────────┘
 ```
 
-1. Your app authenticates with the relay and creates a proof request via the SDK
-2. The relay issues a tracked request ID and returns a deep link
+1. Your app sets a wallet signer and creates a proof request via the SDK
+2. The SDK authenticates with the relay using challenge-signature (EIP-191) and gets a tracked request ID
 3. The SDK displays a QR code (desktop) or opens the deep link (mobile)
 4. The user opens the ZKProofport app, which generates the ZK proof
 5. The proof result flows back through the relay to your app via WebSocket (or polling)
@@ -44,11 +42,9 @@ TypeScript SDK for requesting zero-knowledge proofs from the [ZKProofport](https
 ## Installation
 
 ```bash
-npm install @zkproofport-app/sdk@beta
+npm install @zkproofport-app/sdk
 ```
 
-> Published under the `beta` dist-tag. Use `@beta` to install.
-
 **Peer dependency (required for on-chain verification):**
 
 ```bash
@@ -59,12 +55,15 @@ npm install ethers
 
 ```typescript
 import { ProofportSDK } from '@zkproofport-app/sdk';
+import { BrowserProvider } from 'ethers';
 
 // 1. Initialize
 const sdk = ProofportSDK.create();
 
-// 2. Authenticate
-await sdk.login({ clientId: 'your-client-id', apiKey: 'your-api-key' });
+// 2. Set wallet signer (ethers v6 Signer)
+const provider = new BrowserProvider(window.ethereum);
+const signer = await provider.getSigner();
+sdk.setSigner(signer);
 
 // 3. Create proof request via relay
 const relay = await sdk.createRelayRequest('coinbase_attestation', {
@@ -97,7 +96,7 @@ Proves that a user has completed Coinbase KYC identity verification without reve
 
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
-| `scope` | `string` | Yes | Application-specific identifier (e.g., your domain). Generates a unique nullifier per app to prevent cross-app tracking. |
+| `scope` | `string` | Yes | Application-specific identifier (e.g., your domain). Ensures proof uniqueness per app. |
 
 ```typescript
 const relay = await sdk.createRelayRequest('coinbase_attestation', {
@@ -135,29 +134,47 @@ import { ProofportSDK } from '@zkproofport-app/sdk';
 const sdk = ProofportSDK.create();
 ```
 
-`ProofportSDK.create()` returns an SDK instance pre-configured with the relay server, verifier contracts, and nullifier registry. No manual configuration is needed.
+`ProofportSDK.create()` returns an SDK instance pre-configured with the relay server and verifier contracts. No configuration needed.
 
-### Step 2: Authenticate
+### Step 2: Set Wallet Signer
 
-Authenticate with the relay server using your client credentials. The SDK stores the JWT token internally for subsequent requests.
+The SDK uses challenge-signature authentication (EIP-191). Set a wallet signer that can sign messages:
 
 ```typescript
-await sdk.login({
-  clientId: process.env.CLIENT_ID,
-  apiKey: process.env.API_KEY,
-});
+import { BrowserProvider } from 'ethers';
+
+const provider = new BrowserProvider(window.ethereum);
+const signer = await provider.getSigner();
+sdk.setSigner(signer);
+```
+
+The `WalletSigner` interface requires two methods:
 
-// Check auth status at any time
-sdk.isAuthenticated(); // true
-sdk.getAuthToken();    // AuthToken object
-sdk.logout();          // Clear stored token
+```typescript
+interface WalletSigner {
+  signMessage(message: string): Promise<string>;
+  getAddress(): Promise<string>;
+}
 ```
 
-Get your `clientId` and `apiKey` from the [ZKProofport Dashboard](https://zkproofport.com).
+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` is the **recommended** method. The relay server issues a tracked request ID, manages credits, and builds the deep link with the relay callback URL.
+`createRelayRequest` authenticates with the relay (challenge-signature), creates a tracked proof request, and returns a deep link.
 
 ```typescript
 const relay = await sdk.createRelayRequest('coinbase_attestation', {
@@ -201,7 +218,7 @@ await sdk.renderQRCodeToCanvas(canvasElement, relay.deepLink, { width: 400 });
 const { size, withinLimit } = sdk.checkQRCodeSize(relay.deepLink);
 ```
 
-**Mobile:** On mobile browsers, you can redirect directly to the deep link instead of showing a QR code:
+**Mobile:** On mobile browsers, redirect directly to the deep link instead of showing a QR code:
 
 ```typescript
 if (ProofportSDK.isMobile()) {
@@ -277,44 +294,22 @@ if (result.status === 'completed') {
 const verification = await sdk.verifyResponseOnChain(response);
 ```
 
-### Step 7: Check Nullifier (Optional)
-
-Nullifiers prevent the same user from submitting duplicate proofs for the same scope. The SDK is pre-configured with the nullifier registry contract.
-
-```typescript
-// Extract nullifier from proof result
-const nullifier = sdk.extractNullifier(result.publicInputs, result.circuit);
-const scope = sdk.extractScope(result.publicInputs, result.circuit);
-
-// Check if already used
-const isDuplicate = await sdk.checkNullifier(nullifier);
-if (isDuplicate) {
-  console.log('This user has already submitted a proof for this scope');
-}
-
-// Get registration details
-const info = await sdk.getNullifierDetails(nullifier);
-if (info) {
-  console.log('Registered at:', new Date(info.registeredAt * 1000));
-  console.log('Circuit:', info.circuitId);
-  console.log('Scope:', info.scope);
-}
-```
-
 ## Complete Example
 
 End-to-end integration using the relay flow:
 
 ```typescript
 import { ProofportSDK } from '@zkproofport-app/sdk';
+import { BrowserProvider } from 'ethers';
 
 async function verifyUser() {
-  // Initialize and authenticate
+  // Initialize
   const sdk = ProofportSDK.create();
-  await sdk.login({
-    clientId: process.env.CLIENT_ID,
-    apiKey: process.env.API_KEY,
-  });
+
+  // Set wallet signer
+  const provider = new BrowserProvider(window.ethereum);
+  const signer = await provider.getSigner();
+  sdk.setSigner(signer);
 
   // Create proof request via relay
   const relay = await sdk.createRelayRequest('coinbase_attestation', {
@@ -357,24 +352,24 @@ async function verifyUser() {
 }
 ```
 
-## Advanced Usage
+## Configuration
 
-### Nullifier Duplicate Detection
+`ProofportSDK.create()` returns a fully configured SDK instance. No manual configuration is needed for standard usage.
 
-All nullifier operations are instance methods on the SDK:
+For advanced scenarios (e.g., custom verifier deployments), pass a `ProofportConfig`:
 
 ```typescript
-const nullifier = sdk.extractNullifier(publicInputs, circuit);
-const isDuplicate = await sdk.checkNullifier(nullifier);
-const details = await sdk.getNullifierDetails(nullifier);
+const sdk = new ProofportSDK({
+  relayUrl: 'https://relay.zkproofport.app',
+  verifiers: {
+    coinbase_attestation: {
+      verifierAddress: '0x...',
+      chainId: 8453,
+    },
+  },
+});
 ```
 
-## Configuration
-
-`ProofportSDK.create()` returns a fully configured SDK instance. No manual configuration is needed for standard usage.
-
-For advanced scenarios (e.g., custom verifier deployments), see the `ProofportConfig` type exported by the SDK.
-
 ## Types Reference
 
 All 15 exported types:
@@ -391,8 +386,8 @@ import type {
   QRCodeOptions,
   VerifierContract,
   ProofportConfig,
-  AuthCredentials,
-  AuthToken,
+  ChallengeResponse,
+  WalletSigner,
   RelayProofRequest,
   RelayProofResult,
   SDKEnvironment,
@@ -407,31 +402,25 @@ import type {
 | `CoinbaseCountryInputs` | Inputs for `coinbase_country_attestation` (`{ scope, countryList, isIncluded, ... }`) |
 | `CircuitInputs` | Union: `CoinbaseKycInputs \| CoinbaseCountryInputs` |
 | `ProofRequest` | Proof request object with `requestId`, `circuit`, `inputs`, metadata, and expiry |
-| `ProofResponse` | Proof response with `status`, `proof`, `publicInputs`, `nullifier`, `verifierAddress`, `chainId` |
+| `ProofResponse` | Proof response with `status`, `proof`, `publicInputs`, `verifierAddress`, `chainId` |
 | `QRCodeOptions` | QR customization: `width`, `margin`, `darkColor`, `lightColor`, `errorCorrectionLevel` |
 | `VerifierContract` | Verifier contract info: `{ address, chainId, abi }` |
-| `ProofportConfig` | SDK configuration (for advanced usage only) |
-| `AuthCredentials` | Login credentials: `{ clientId, apiKey }` |
-| `AuthToken` | JWT token: `{ token, clientId, dappId, tier, expiresIn, expiresAt }` |
+| `ProofportConfig` | SDK configuration: `{ scheme?, relayUrl?, verifiers? }` |
+| `ChallengeResponse` | Challenge from relay: `{ challenge, expiresAt }` |
+| `WalletSigner` | Signer interface: `{ signMessage(msg), getAddress() }` |
 | `RelayProofRequest` | Relay response: `{ requestId, deepLink, status, pollUrl }` |
-| `RelayProofResult` | Relay result: `{ requestId, status, proof?, publicInputs?, nullifier?, circuit?, error? }` |
-| `SDKEnvironment` | SDK environment preset |
+| `RelayProofResult` | Relay result: `{ requestId, status, proof?, publicInputs?, circuit?, error? }` |
+| `SDKEnvironment` | Environment preset (not needed for normal usage) |
 
 ## Error Handling
 
-All async SDK methods throw standard `Error` objects. Common error scenarios:
+All async SDK methods throw standard `Error` objects:
 
 ```typescript
-try {
-  await sdk.login({ clientId: 'bad-id', apiKey: 'bad-key' });
-} catch (err) {
-  // "Authentication failed: HTTP 401"
-}
-
 try {
   await sdk.createRelayRequest('coinbase_attestation', { scope: 'app.com' });
 } catch (err) {
-  // "Not authenticated. Call login() first."
+  // "Signer not set. Call setSigner() first."
 }
 
 try {
@@ -441,19 +430,12 @@ try {
 }
 ```
 
-Relay request validation errors:
+## Networks
 
-```typescript
-try {
-  await sdk.createRelayRequest('coinbase_country_attestation', {
-    scope: 'app.com',
-    countryList: [],
-    isIncluded: true,
-  });
-} catch (err) {
-  // Relay or input validation error
-}
-```
+| Network | Chain ID | Status |
+|---------|----------|--------|
+| Base Mainnet | 8453 | Production |
+| Base Sepolia | 84532 | Testnet |
 
 ## Development
 

package/dist/ProofportSDK.d.ts

@@ -42,7 +42,6 @@ export declare class ProofportSDK {
     private pendingRequests;
     private signer;
     private relayUrl;
-    private nullifierRegistry?;
     private socket;
     /**
      * Creates a new ProofportSDK instance.
@@ -874,27 +873,6 @@ export declare class ProofportSDK {
      * Disconnects the Socket.IO connection if active.
      */
     disconnect(): void;
-    /**
-     * Extracts the nullifier from proof public inputs.
-     *
-     * The nullifier is a bytes32 value derived from the user's address and scope,
-     * used to prevent duplicate proof submissions. Each user+scope combination
-     * produces a unique nullifier.
-     *
-     * @param publicInputs - Array of public input hex strings from proof response
-     * @param circuit - Circuit type to determine field positions
-     * @returns Nullifier as hex string (0x...), or null if inputs are insufficient
-     *
-     * @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);
-     * }
-     * ```
-     */
-    extractNullifier(publicInputs: string[], circuit: CircuitType): string | null;
     /**
      * Extracts the scope from proof public inputs.
      *
@@ -915,57 +893,5 @@ export declare class ProofportSDK {
      * ```
      */
     extractScope(publicInputs: string[], circuit: CircuitType): string | null;
-    /**
-     * Checks if a nullifier is already registered on-chain.
-     *
-     * Queries the ZKProofportNullifierRegistry contract to determine if the
-     * nullifier has been used before. Used to prevent duplicate proof submissions.
-     *
-     * Requires `nullifierRegistry` in SDK config.
-     *
-     * @param nullifier - Nullifier hex string from extractNullifier()
-     * @param provider - Optional ethers provider (defaults to public RPC for configured chain)
-     * @returns True if nullifier is already registered
-     * @throws Error if nullifierRegistry is not configured
-     *
-     * @example
-     * ```typescript
-     * const sdk = ProofportSDK.create({
-     *   relayUrl: 'https://relay.zkproofport.app',
-     *   nullifierRegistry: { address: '0x...', chainId: 8453 }
-     * });
-     *
-     * const nullifier = sdk.extractNullifier(publicInputs, circuit);
-     * const isDuplicate = await sdk.checkNullifier(nullifier);
-     * ```
-     */
-    checkNullifier(nullifier: string, provider?: any): Promise<boolean>;
-    /**
-     * Gets detailed information about a registered nullifier from on-chain registry.
-     *
-     * Retrieves the registration timestamp, scope, and circuit ID for a nullifier.
-     * Returns null if the nullifier is not registered.
-     *
-     * Requires `nullifierRegistry` in SDK config.
-     *
-     * @param nullifier - Nullifier hex string from extractNullifier()
-     * @param provider - Optional ethers provider (defaults to public RPC for configured chain)
-     * @returns Nullifier info or null if not registered
-     * @throws Error if nullifierRegistry is not configured
-     *
-     * @example
-     * ```typescript
-     * const info = await sdk.getNullifierDetails(nullifier);
-     * if (info) {
-     *   console.log('Registered at:', new Date(info.registeredAt * 1000));
-     *   console.log('Circuit:', info.circuitId);
-     * }
-     * ```
-     */
-    getNullifierDetails(nullifier: string, provider?: any): Promise<{
-        registeredAt: number;
-        scope: string;
-        circuitId: string;
-    } | null>;
 }
 export default ProofportSDK;

package/dist/constants.d.ts

@@ -128,7 +128,6 @@ export declare const MAX_QR_DATA_SIZE = 2953;
  * - signal_hash: bytes 0-31
  * - merkle_root: bytes 32-63
  * - scope: bytes 64-95
- * - nullifier: bytes 96-127
  *
  * @example
  * ```typescript
@@ -146,8 +145,6 @@ 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).
@@ -160,7 +157,6 @@ export declare const COINBASE_ATTESTATION_PUBLIC_INPUT_LAYOUT: {
  * - country_list_length: byte 84
  * - is_included: byte 85
  * - scope: bytes 86-117
- * - nullifier: bytes 118-149
  *
  * @example
  * ```typescript
@@ -182,42 +178,4 @@ 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;
 };
-/**
- * V1 NullifierRegistry contract ABI (DEPRECATED).
- *
- * This is the legacy nullifier registry interface.
- * Use ZKPROOFPORT_NULLIFIER_REGISTRY_ABI for new integrations.
- *
- * @deprecated Use ZKPROOFPORT_NULLIFIER_REGISTRY_ABI instead. This is the V1 NullifierRegistry ABI.
- */
-export declare const NULLIFIER_REGISTRY_ABI: string[];
-/**
- * ZKProofportNullifierRegistry contract ABI (V2).
- *
- * This is the current nullifier registry interface with relayer-only registration.
- * Public view functions allow checking nullifier status and verifying proofs without registration.
- *
- * Key functions:
- * - `isNullifierRegistered`: Check if a nullifier has been used
- * - `getNullifierInfo`: Get registration details for a nullifier
- * - `verifyOnly`: Verify a proof without registering the nullifier
- *
- * Note: Registration functions (verifyAndRegister) are relayer-only and not exposed in this ABI.
- *
- * @example
- * ```typescript
- * import { Contract } from 'ethers';
- *
- * const registry = new Contract(
- *   registryAddress,
- *   ZKPROOFPORT_NULLIFIER_REGISTRY_ABI,
- *   provider
- * );
- *
- * const isUsed = await registry.isNullifierRegistered(nullifier);
- * ```
- */
-export declare const ZKPROOFPORT_NULLIFIER_REGISTRY_ABI: string[];