Skip to main content

Configuration

This document covers configuration guidance for the zkIdentity attestor, frontend, and supporting services. Configuration is managed through environment variables.

warning

Never commit environment files containing production secrets to version control. Use .env.example files as templates and manage production secrets through your deployment platform's secrets management.

Attestor Configuration​

The attestor requires configuration for the following areas:

Core Settings​

  • Server port and bind address: Where the attestor HTTP server listens.
  • Log level: Controls verbosity (debug, info, warn, error).
  • Environment: development, staging, or production.
  • TEE mode: production (real TEE) or simulation (development only).

Webhook Configuration​

  • Base URL: The public URL where KYC providers can reach the attestor's webhook endpoints.
  • Webhook secret: A shared secret for verifying webhook authenticity.

Provider API Keys​

Credentials for each enabled KYC provider:

  • Smile ID: Partner ID, API Key, Signature Key, and environment (sandbox/production).
  • Plaid: Client ID, Secret Key, and environment (sandbox/development/production).

Blockchain Configuration​

  • Arbitrum RPC URL: Endpoint for the Arbitrum L2 network.
  • Attestor wallet: Private key or keystore for signing rollup submissions.
  • Cartesi rollup URL: Endpoint for the Cartesi rollup node.
  • DApp contract address: Address of the deployed zkIdentity Cartesi DApp.

IPFS Configuration​

  • Pinata API credentials: API Key, API Secret, and/or JWT token.
  • Gateway URL: IPFS gateway for retrieval.

ZK Proof Configuration​

  • zkFetch settings: Timeout, retry count, and retry delay for proof generation.

Frontend Configuration​

  • Application URL: Public URL for the frontend.
  • Attestor URL: Where the frontend connects to the attestor API.
  • Privy App ID: Privy application ID for wallet connection (supports MetaMask, WalletConnect, email, social login).
  • Provider flags: Which providers are enabled in the UI.

Configuration by Environment​

Development​

  • TEE mode: simulation
  • Provider environments: sandbox
  • Blockchain: testnet (e.g., Arbitrum Sepolia)
  • Log level: debug

Staging​

  • TEE mode: production
  • Provider environments: sandbox
  • Blockchain: testnet
  • Log level: info

Production​

  • TEE mode: production
  • Provider environments: production
  • Blockchain: Arbitrum mainnet
  • Log level: warn

Configuration Validation​

The attestor validates all configuration on startup. If required variables are missing or invalid, it will log specific errors and exit with a non-zero status code.

Secrets Rotation​

Provider API Keys​

Provider API keys can be rotated without downtime:

  1. Obtain new credentials from the provider dashboard.
  2. Update the environment variables.
  3. Restart the attestor (in-progress sessions will complete with old keys from memory).

Attestor Wallet​

The attestor wallet private key can be rotated, but the new wallet must:

  1. Be funded with ETH on Arbitrum.
  2. Be registered as an authorized submitter in the Cartesi DApp (if access control is enabled).

Webhook Secret​

When rotating the webhook secret:

  1. Update the webhook secret in the attestor configuration.
  2. Update the webhook signature verification configuration in each provider's dashboard.
  3. Restart the attestor.
  • Prerequisites -- What you need before configuring.
  • Provider Setup -- Detailed provider integration configuration.
  • Testing -- Verify your configuration with sandbox testing.