OSx zkVoting Plugin

The OSx zkVoting Plugin is a decentralized voting system that leverages zero-knowledge proofs generated by RISC Zero's zkVM in Rust. This plugin is designed to be integrated with the OSx platform, providing a secure and transparent way for users to participate in voting processes.

Overview

The OSx zkVoting Plugin ensures the integrity of votes through storage proofs on EVM chains. The plugin allows for voting with tokens that do not follow the governance standards and supports custom delegation mechanisms. Additionally, it is built in a way that allows external parties to add custom strategies.

Architecture

The OSx zkVoting Plugin is composed of several key components, each playing a crucial role in the voting process. Below is an overview of the architecture:

1. OSx Plugin: Located in the /contracts directory, this component contains the smart contracts that interact with the Ethereum blockchain. These contracts handle the submission and verification of proofs, as well as the tallying of votes.

2. Guest Code: Found in the methods library, the guest code is responsible for generating zero-knowledge proofs. This code runs within RISC Zero's zkVM and ensures that the proofs are generated securely and correctly.

3. Host Code: The host code, which prepares the necessary inputs for the proofs (such as storage proofs), is responsible for calling the guest program to generate the proof. Once the proof is generated, the host code submits it to the blockchain. This code is also responsible for managing interactions with the guest code and is located in the main project directory.

4. Strategies: Strategies are implemented in both the guest and host code. Due to current architectural limitations, these strategies must be replicated in both directories. However, efforts are underway to optimize this process in the future.

5. Tests: Unit tests for each strategy are located within their respective directories, ensuring that each component functions correctly in isolation. Integration tests, which test the entire system as a whole, are located in the root directory.

6. Server: A server component, located in the server directory, facilitates communication between the frontend application and the host code. This server allows users to interact with the voting system through a web interface, making it easier to participate in the voting process.

This modular architecture ensures that each component can be developed, tested, and maintained independently, while still working together to provide a secure and transparent voting system.

Dependencies

First, [install Rust] and [Foundry], and then restart your terminal.

# Install Rust
curl https://sh.rustup.rs -sSf | sh
# Install Foundry
curl -L https://foundry.paradigm.xyz | bash

Next, you will need to install the cargo risczero tool. We'll use [cargo binstall][cargo-binstall] to get cargo-risczero installed, and then install the risc0 toolchain. See [RISC Zero installation] for more details.

cargo install cargo-binstall
cargo binstall cargo-risczero
cargo risczero install

Now you have all the tools you need to develop and deploy an application with [RISC Zero].

Configuring Environment Variables

Bonsai

With the Bonsai proving service, you can produce a [Groth16 SNARK proof] that is verifiable on-chain. You can get started by setting the following environment variables with your API key and associated URL. Note: To request an API key complete the form here.

export BONSAI_API_KEY="YOUR_API_KEY" # see form linked above
export BONSAI_API_URL="BONSAI_URL" # provided with your api key

For the rest of the needed .env, you can find the information in the .env.example file in the root directory, just copy and paste it as .env and add your variables. Finally, you can export the environment variables with:

source .env

Deploy Your Application

When deploying the contract, you'll need to make a very small change. Go to the files ImageID.sol and Elf.sol and you'll have to change the solidity version to 0.8.17. This will be fixed in an upcoming release.

Test your strategies

Just run the following:

cargo test -- --nocapture

This will run a full integration test and the unit tests.

If you want to test just the unit tests you can run the following:

cargo test -p apps -- --nocapture

DAO Config String

When deploying a DAO, you need to set the governance settings for the plugin. These settings include the assets that will make up the census, the delegation mechanisms, and the execution strategy. This configuration is stored as a JSON string in the contract when being deployed.

The format of this JSON string is as follows:

{
  "votingProtocolVersion": "string",
  "assets": [
    {
      "contract": "address",
      "chainId": "number",
      "votingPowerStrategy": "string",
      "delegation": {
        "contract": "address",
        "strategy": "string"
      }
    }
  ],
  "executionStrategy": "string"
}

Example

Here is an example of a DAO Config String:

{
  "votingProtocolVersion": "1.0",
  "assets": [
    {
      "contract": "0x1234567890abcdef1234567890abcdef12345678",
      "chainId": 1,
      "votingPowerStrategy": "BalanceOf",
      "delegation": {
        "contract": "0xabcdefabcdefabcdefabcdefabcdefabcdef",
        "strategy": "SplitDelegation"
      }
    }
  ],
  "executionStrategy": "MajorityVoting"
}