Skip to content

script

Directory actions

More options

Directory actions

More options

Latest commit

 

History

History

script

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
artifacts
artifacts
 
 
contracts
contracts
 
 
src
src
 
 
.env.example
.env.example
 
 
.gitignore
.gitignore
 
 
README.md
README.md
 
 
package.json
package.json
 
 
tsconfig.json
tsconfig.json
 
 
yarn.lock
yarn.lock
 
 

README.md

Vocdoni DAVINCI SDK - Script Example

A comprehensive end-to-end demonstration of the Vocdoni DAVINCI SDK showcasing the complete privacy-preserving voting process using zero-knowledge proofs.

Table of Contents

Overview

This script demonstrates a complete voting workflow using the Vocdoni DAVINCI SDK, including:

  • Privacy-Preserving Voting: Uses zk-SNARKs to ensure vote privacy while maintaining verifiability
  • Multi-Question Elections: Creates an election with two questions (favorite color and transportation preference)
  • Smart Contract Integration: Interacts with Ethereum smart contracts
  • Complete Lifecycle: From census creation to result tallying
  • Cryptographic Operations: Handles encryption, proof generation, and verification

Key Technologies

  • zk-SNARKs: Zero-knowledge proofs for private voting
  • Ethereum: Smart contract deployment and interaction
  • Vocdoni Sequencer: Off-chain vote processing and aggregation
  • TypeScript: Type-safe development environment

Prerequisites

Before running this script, ensure you have:

Software Requirements

  • Node.js (v18 or higher)
  • Yarn package manager
  • Git for cloning repositories

Blockchain Requirements

  • Ethereum Wallet with a private key
  • Testnet ETH for transaction fees (on the blockchain the sequencer is using)
  • RPC Provider (Infura, Alchemy, or similar)

API Access

  • Vocdoni API Endpoint (development or production)

Installation

  1. Clone the repository (if not already done):

    git clone https://github.com/vocdoni/davinci-sdk.git
cd davinci-sdk

  2. Install root dependencies and build:

    yarn install && yarn build

  3. Navigate to the script example:

    cd examples/script

  4. Install script dependencies:

    yarn install

Configuration

  1. Copy the environment template:

    cp .env.example .env

  2. Configure environment variables in .env:

    # Sequencer API endpoint (e.g., https://sequencer-dev.davinci.vote)
SEQUENCER_API_URL=

# Census API endpoint (e.g., https://c3-dev.davinci.vote)
CENSUS_API_URL=

# RPC endpoint for blockchain transactions (get from Infura, Alchemy, etc.)
# The chain is determined by the sequencer configuration
RPC_URL=https://sepolia.infura.io/v3/YOUR_PROJECT_ID

# Private key for transaction signing (without 0x prefix)
PRIVATE_KEY=your_private_key_here

# (optional) CSP private key for CSP census operations (without 0x prefix)
# If not provided, a random private key will be generated
CSP_PRIVATE_KEY=

Environment Variables Explained

Variable Description Required Example
SEQUENCER_API_URL Vocdoni sequencer API endpoint ✅ https://sequencer1.davinci.vote
CENSUS_API_URL Vocdoni census API endpoint ✅ https://census1.davinci.vote
RPC_URL Blockchain RPC URL ✅ https://sepolia.infura.io/v3/...
PRIVATE_KEY Wallet private key (no 0x) ✅ abcd1234...
ORGANIZATION_REGISTRY_ADDRESS Custom org registry address ❌ 0x1234...
PROCESS_REGISTRY_ADDRESS Custom process registry address ❌ 0x5678...
FORCE_SEQUENCER_ADDRESSES Use addresses from sequencer info ❌ true or false

New Feature: Force Sequencer Addresses

The script now includes a new environment variable FORCE_SEQUENCER_ADDRESSES that allows you to force the use of contract addresses from the sequencer's info endpoint instead of using environment variables or default addresses.

How it works:

  1. When FORCE_SEQUENCER_ADDRESSES=false (default):

    • The script will first check for PROCESS_REGISTRY_ADDRESS and ORGANIZATION_REGISTRY_ADDRESS in environment variables
    • If not found, it will fall back to the default deployed addresses

  2. When FORCE_SEQUENCER_ADDRESSES=true:

    • The script will fetch contract addresses from the sequencer's /info endpoint
    • It will use the process and organization addresses from the sequencer response
    • If the sequencer doesn't provide valid addresses, the script will throw an error
    • Environment variables and default addresses are ignored when this flag is set

Benefits:

  • Dynamic Configuration: Contract addresses are automatically retrieved from the sequencer
  • Environment Consistency: Ensures the script uses the same contract addresses that the sequencer is configured to use
  • Reduced Configuration: No need to manually specify contract addresses in environment variables

Getting Required Values

RPC URL

  1. Sign up at Infura or Alchemy
  2. Create a new project
  3. Copy the RPC endpoint URL for the network your sequencer is using

Private Key

  1. Export from MetaMask: Settings → Security & Privacy → Reveal Private Key
  2. ⚠️ Security Warning: Never share your private key or commit it to version control

Testnet ETH

  • Get free testnet ETH from the appropriate faucet for your network
  • You'll need ~0.01 ETH for transaction fees

Usage

Run the complete demonstration:

yarn start

The script will execute all 19 steps automatically, taking approximately 5-10 minutes to complete.

Expected Output

The script provides detailed console output with:

  • ✅ Success indicators for completed steps
  • ℹ️ Information messages for ongoing processes
  • 🚀 Progress indicators for major phases
  • 📊 Final election results

When FORCE_SEQUENCER_ADDRESSES=true, you'll see output like:

ℹ FORCE_SEQUENCER_ADDRESSES is enabled - will use contract addresses from sequencer info endpoint
ℹ Using PROCESS_REGISTRY_ADDRESS from sequencer info: 0x1234...
ℹ Using ORGANIZATION_REGISTRY_ADDRESS from sequencer info: 0x5678...

When FORCE_SEQUENCER_ADDRESSES=false, you'll see:

ℹ FORCE_SEQUENCER_ADDRESSES is disabled - will use environment variables or default addresses
ℹ Using default process registry address: 0xabcd...
ℹ Using default organization registry address: 0xefgh...

What the Script Does

The script performs a complete end-to-end voting process in 19 steps:

Phase 1: API Setup & Census Creation (Steps 1-6)

  1. Ping API - Verify connection to Vocdoni sequencer
  2. Fetch Info - Get zk-circuit URLs and contract addresses
  3. Create Census - Initialize a new voter registry
  4. Add Participants - Register 10 test voters with weights
  5. Verify Participants - Confirm all voters were added
  6. Fetch Census Root - Get Merkle root and size

Phase 2: Election Setup (Steps 7-10)

  1. Push Metadata - Upload election information and questions
  2. Create Process - Initialize voting process via sequencer
  3. Deploy On-Chain - Register process on Ethereum
  4. Verify On-Chain - Confirm smart contract state

Phase 3: Vote Generation & Submission (Steps 11-17)

  1. Generate Proof Inputs - Create zk-SNARK inputs for each voter
  2. Generate Proofs - Compute zero-knowledge proofs
  3. Wait for Process - Ensure voting is ready
  4. Submit Votes - Send encrypted votes with proofs
  5. Check Vote Status - Verify submission success
  6. Wait for Processing - Allow votes to be settled
  7. Verify Votes - Confirm all votes were recorded

Phase 4: Results & Completion (Steps 18-19)

  1. End Process - Close voting and trigger result calculation
  2. Show Results - Display final tallied results

Process Flow

graph TD
    A[Start Script] --> B[Setup API Connection]
    B --> C[Create Census]
    C --> D[Add 10 Test Participants]
    D --> E[Create Election Metadata]
    E --> F[Initialize Voting Process]
    F --> G[Deploy Smart Contract]
    G --> H[Generate zk-SNARK Proofs]
    H --> I[Submit Encrypted Votes]
    I --> J[Wait for Vote Processing]
    J --> K[End Voting Process]
    K --> L[Calculate & Display Results]
    L --> M[Complete ✅]

    style A fill:#e1f5fe
    style M fill:#c8e6c9
    style H fill:#fff3e0
    style I fill:#fff3e0
Loading

Understanding the Output

Console Output Sections

Step Progress

[Step 1] Ping the HTTP API
✔ API reachable

[Step 2] Fetch zk‐circuit & on‐chain contract info
   circuitUrl: https://...
   contracts: {...}

Vote Generation

   • 0x1234... votes:
     Q1: Blue (choice array: [0, 1, 0, 0])
     Q2: Car (choice array: [1, 0, 0, 0])
   • 0x1234... → voteId=0xabcd...

Final Results

Election Results:

Question 1: What is your favorite color?
Red (0):              2
Blue (1):             3
Green (2):            1
Yellow (3):           4

Question 2: What is your preferred transportation?
Car (0):              4
Bike (1):             2
Public Transport (2): 1
Walking (3):          3

Key Metrics

  • Participants: 10 test voters with weighted voting power
  • Questions: 2 multiple-choice questions with 4 options each
  • Vote Privacy: All votes are encrypted and use zero-knowledge proofs
  • Verification: Every vote is cryptographically verified

Architecture

Zero-Knowledge Proof System

The script uses zk-SNARKs (Zero-Knowledge Succinct Non-Interactive Arguments of Knowledge) to ensure:

  • Privacy: Vote choices remain secret
  • Integrity: Votes cannot be tampered with
  • Verifiability: Anyone can verify vote validity without seeing the content

Smart Contract Integration

graph LR
    A[Voter] --> B[zk-SNARK Proof]
    B --> C[Vocdoni Sequencer]
    C --> D[Ethereum Smart Contract]
    D --> E[On-Chain Results]

    style B fill:#fff3e0
    style C fill:#e8f5e8
    style D fill:#e3f2fd
Loading

Data Flow

  1. Census Creation: Merkle tree of eligible voters
  2. Vote Encryption: Votes encrypted with election public key
  3. Proof Generation: zk-SNARK proves vote validity without revealing content
  4. Sequencer Processing: Off-chain aggregation and verification
  5. On-Chain Settlement: Final results published to Ethereum

Troubleshooting

Common Issues

"SEQUENCER_API_URL environment variable is required"

  • Cause: Missing or empty .env file
  • Solution: Copy .env.example to .env and configure variables

"insufficient funds for intrinsic transaction cost"

  • Cause: Not enough testnet ETH for gas fees
  • Solution: Get more testnet ETH from the appropriate faucet for your network

"Process not ready yet, checking again in 10 seconds..."

  • Cause: Normal behavior - process initialization takes time
  • Solution: Wait for the process to become ready (usually 30-60 seconds)

"Proof verification failed"

  • Cause: zk-SNARK circuit or input issues
  • Solution: Check API connectivity and try again

"Invalid process registry address from sequencer"

  • Cause: FORCE_SEQUENCER_ADDRESSES=true but sequencer doesn't provide valid addresses
  • Solution:
    • Check sequencer configuration
    • Set FORCE_SEQUENCER_ADDRESSES=false to use environment variables or defaults
    • Manually set PROCESS_REGISTRY_ADDRESS and ORGANIZATION_REGISTRY_ADDRESS

Connection timeout errors

  • Cause: Network issues or API downtime
  • Solution:
    • Check internet connection
    • Verify SEQUENCER_API_URL and CENSUS_API_URL are correct
    • Try again later if API is down

Debug Tips

  1. Enable verbose logging: The script already provides detailed output
  2. Check transaction status: Use the appropriate block explorer for your network to verify transactions
  3. Verify API status: Test API connectivity with curl $SEQUENCER_API_URL/ping
  4. Check balances: Ensure wallet has sufficient testnet ETH

Getting Help

If you encounter issues:

  1. Check the troubleshooting section above
  2. Review the console output for specific error messages
  3. Verify all prerequisites are met
  4. Check the Vocdoni documentation

Additional Resources

Documentation

Community

Related Examples

Technical Resources

Support

For issues and questions:

For enterprise support and custom integrations, contact us at info@vocdoni.io.

Note: This is a demonstration script for development and testing purposes. For production use, implement proper error handling, security measures, and user interface components.