@vocdoni/davinci-contracts

# Vocdoni DAVINCI Contracts **DISCLAIMER**: The **code** in this repository is a **work-in-progress** and it is not meant to be used in production environments. [![License: AGPL v3](https://img.shields.io/badge/License-AGPL%20v3-blue.svg)](https://www.gnu.org/licenses/agpl-3.0) [![Version](https://img.shields.io/badge/version-0.0.37-brightgreen.svg)](https://github.com/vocdoni/davinci-contracts/releases) Smart contracts powering DAVINCI's (Decentralized Autonomous Vote Integrity Network with Cryptographic Inference) digital voting protocol - a cutting-edge voting system that leverages zero-knowledge proofs and blockchain technology to enable secure, verifiable, coercion-resistant, and anonymous digital voting. ## 📋 Table of Contents - [Overview](#overview) - [Architecture](#architecture) - [Installation](#installation) - [Development](#development) - [Testing](#testing) - [Deployment](#deployment) - [Documentation](#documentation) - [Contributing](#contributing) - [License](#license) ## 🔍 Overview The Vocdoni DAVINCI contracts work together with a set of sequencers that implement a specialized zkRollup system that enables secure digital voting with complete privacy guarantees. The system uses multiple layers of cryptographic proofs: - **Identity Proofs**: Voters prove their right to participate via identity proofs - **Vote Proofs**: Voters prove their ballot is valid without revealing choices - **State Transition Proofs**: Prove correct vote aggregation and state updates - **Results Proofs**: Final tally is proven correct while maintaining vote privacy ## 🏗️ Architecture ### Core Components 1. **ProcessRegistry**: Handles voting process lifecycle, state transitions, and results 2. **ZK Verifiers**: On-chain verification of zkSNARK proofs for state transitions and results 3. **Process ID Library**: Utilities for generating unique process identifiers ### Deployed libraries - **Sepolia** - PoseidonT3: `0x1464bD48D1635E9B9F65cFd629d8E9f507A952dD` - PoseidonT4: `0xd747896B912C1585b04007c103D10A04e71bfb25` - **Arbitrum** - PoseidonT3: `0xE17D701EA8f34022F97fC2Ec68c73D42bF99D0BD` - PoseidonT4: `0x2DaF913D423128258b2F378E320F9D9D3Be5eCf5` - BlobsLib: `0xca08064a83C7Bea0DB7514eE37F6f4a193b2B53c` - ProcessIdLib: `0xDda6c75d32c375946C8ae9be41B2F3539dB1118A` - StateRootLib: `0x808276962217AD1ED3af7D51bFc791903CAd9389` ## 📦 Installation ### Prerequisites - [Node.js](https://nodejs.org/) >= 16.0.0 - [Foundry](https://getfoundry.sh/) - [Git](https://git-scm.com/) - [Abigen](https://geth.ethereum.org/docs/tools/abigen) - [jq](https://jqlang.org/) ### Setup 1. Clone the repository: ```bash git clone https://github.com/vocdoni/davinci-contracts.git cd davinci-contracts ``` 2. Install dependencies: ```bash npm install forge install ``` 3. Set up environment variables: ```bash cp .env.example .env # Edit .env with your configuration ``` 4. Build the project: ```bash ./build_all.sh ``` ## 🛠️ Development ### Building ```bash # Clean and build everything ./build_all.sh # Or build individually forge build npx hardhat compile ``` ### Code Quality ```bash # Linting npm run lint:sol npm run prettier # Security analysis npm run slither npm run mythril ``` ### TypeScript Support The project includes TypeScript bindings: ```bash npm run typechain ``` ### Go Bindings Generate Go bindings for contract integration: ```bash ./go_bind.sh ``` ## 🧪 Testing Run the comprehensive test suite: ```bash # Run all tests forge test # Run with verbosity forge test -vvv # Run specific test file forge test --match-path test/ProcessRegistry.t.sol # Gas reporting forge test --gas-report ``` ## 🚢 Deployment ### Local Development 1. Start a local node: ```bash anvil ``` 2. Deploy contracts: ```bash forge script script/DeployAll.s.sol --rpc-url http://localhost:8545 --broadcast ``` ### Testnet/Mainnet Deployment 1. Configure shared values in `.env` and chain-specific values in `.env.<chain>`. Shared `.env`: ```bash PRIVATE_KEY=your_deployment_key ETHERSCAN_API_KEY=your_explorer_key VERIFY_MODE=auto DEPLOY_CHAINS=base,sepolia ``` Chain file, for example `.env.base`: ```bash RPC_URL=your_rpc_endpoint CHAIN_ID=your_chain_id ACTIVATE_BLOBS=True # Optional: reuse already deployed libraries. # If any of these are unset or point to an address without bytecode, # deploy_all.sh will deploy that library and print export lines you can reuse. POSEIDON_T3_ADDRESS= POSEIDON_T4_ADDRESS= STATE_ROOT_LIB_ADDRESS= PROCESS_ID_LIB_ADDRESS= BLOBS_LIB_ADDRESS= ``` 2. Deploy: ```bash ./deploy_all.sh ``` `deploy_all.sh` loads `.env` first and then uses the currently exported single-chain variables. For direct single-chain use, source one chain file into your shell first or export the variables manually. ### Multi-Chain Deployment Use a shared `.env` plus one per-chain file for each target network. Shared `.env`: ```bash PRIVATE_KEY=your_deployment_key LOCALHOST_RPC_URL=http://127.0.0.1:8545 ETHERSCAN_API_KEY=your_explorer_key VERIFY_MODE=auto DEPLOY_CHAINS=base,sepolia,arbitrum ``` Per-chain `.env.<chain>` files, for example `.env.base`: ```bash CHAIN_ID=8453 RPC_URL=https://your-base-rpc ACTIVATE_BLOBS=False # Optional per-chain overrides ETHERSCAN_API_URL= POSEIDON_T3_ADDRESS= POSEIDON_T4_ADDRESS= STATE_ROOT_LIB_ADDRESS= PROCESS_ID_LIB_ADDRESS= BLOBS_LIB_ADDRESS= ``` Then run: ```bash ./deploy_all_contracts_to_all_chains.sh ``` The wrapper: 1. Loads shared values from `.env` 2. Clears chain-scoped deployment variables 3. Loads `.env.<chain>` for each chain listed in `DEPLOY_CHAINS` 4. Falls back to `.env-<chain>` if the dotted filename does not exist 5. Calls `./deploy_all.sh` once per chain This means old single-chain values left in `.env` will not bleed into multi-chain runs. `deploy_all.sh` resolves libraries in this order: 1. `PoseidonT3` 2. `PoseidonT4` 3. `StateRootLib` (linked against Poseidon) 4. `ProcessIdLib` 5. `BlobsLib` Then it deploys the main contracts with explicit linking for all of them. Verification behavior is controlled by `VERIFY_MODE`: - `auto`: disable verification on local chains (`31337`, `1337`), enable otherwise - `true`: always attempt verification - `false`: never verify ## 📚 Documentation - [Whitepaper](https://whitepaper.vocdoni.io) - [Introduction](docs/Intro.md) - [ProcessRegistry Documentation](docs/ProcessRegistry.md) ## 🤝 Contributing We welcome contributions! 1. Fork the repository 2. Create your feature branch (`git checkout -b feature/amazing-feature`) 3. Commit your changes (`git commit -m 'Add amazing feature'`) 4. Push to the branch (`git push origin feature/amazing-feature`) 5. Open a Pull Request ## 📜 License This project is licensed under the GNU Affero General Public License v3.0 - see the [LICENSE](LICENSE.md) file for details. ## 🔗 Links - [DAVINCI Website](https://davinci.vote) - [Vocdoni Website](https://vocdoni.io) - [Discord Community](https://chat.vocdoni.io) - [Twitter](https://twitter.com/vocdoni) ## 🙏 Acknowledgments Built with ❤️ by Vocdoni.