README
¶
vocdoni-node
This repository contains a set of libraries and tools for the Vocdoni decentralized protocol, as described in the documentation.
If you want to build on top of the Vocdoni protocol, you can visit the developer portal
A good summary of the whole Vocdoni architecture can be found in this paper
Vocdoni
Vocdoni is a universally verifiable, censorship-resistant, and anonymous self-sovereign governance protocol, designed with the scalability and ease-of-use to supply all kind of voting needs.
Our main aim is a trustless voting system, where anyone can speak their voice and where everything can be audited. We are engineering building blocks for a permissionless, private and censorship resistant democracy.
We intend the algorithms, systems, and software that we build to be a useful contribution toward making violence in these cryptonetworks impossible by protecting users privacy with cryptography. In particular, our aim is to provide the necessary tooling for the political will of network participants to translate outwardly into real political capital, without sacrificing privacy.
vocdoni node
The Vocdoni node is equipped with all the necessary components to operate a node on the decentralized Vocdoni protocol blockchain.
There are two operational modes available for the node:
-
Gateway: This mode runs a full block validation node and serves as an access point for the API and other services.
-
Miner: In this mode, the node can validate blocks or run as a full node. It does not offer external services but can propose and validate new blocks.
Gateway mode
The gateway mode is the most frequently used and likely the one you need.
Vocdoni-node is uniquely designed to run all components within a single process, giving full control and eliminating the need for local RPC or IPC connections. This is in contrast to other projects, as Vocdoni-node incorporates go-ethereum, go-ipfs, and tendermint directly as GoLang libraries.
To run a Vocdoni-node as a gateway, it's recommended to have at least 4 GiB of RAM and 40 GiB of disk space.
Compile and run
Compile from source in a golang environment (Go>1.21 required):
git clone https://github.com/vocdoni/vocdoni-node.git -b release-lts-1
cd vocdoni-node
go build ./cmd/node
./node --help
./node --mode=gateway --chain=lts --logLevel=info
Docker
You can run vocdoni node as a standalone container with docker compose (recommended).
It is recommended to also start watchtower
to automatically update the container when a new version is released.
git clone https://github.com/vocdoni/vocdoni-node.git -b release-lts-1
cd vocdoni-node/dockerfiles/vocdoninode
cp env.example env # see env file for config options
COMPOSE_PROFILES=watchtower docker compose up -d
All data will be stored in the shared volume run
and the API will be available at http://127.0.0.1:9090/v2
.
If the computer has the port 443 available and mapped to a public IP, you might want to enable TLS support (HTTPS) using letsencrypt by setting the environment variable VOCDONI_TLS_DOMAIN=your.domain.io
in the env
file.
To stop the container:
docker compose down
Connecting
Once the node has finished the blockchain fast sync process, you can connect query the API:
$ curl http://127.0.0.1:9090/v2/chain/info
{
"chainId": "test-chain-1",
"blockTime": [
12000,
12000,
11650,
0,
0
],
"electionCount": 61,
"organizationCount": 18,
"genesisTime": "2023-02-28T22:40:43.668920539Z",
"height": 1546,
"syncing": false,
"blockTimestamp": 1683056444,
"transactionCount": 418935,
"validatorCount": 4,
"voteCount": 51201,
"cicuitConfigurationTag": "dev",
"maxCensusSize": 10000
}
API methods, SDK and documentation can be found at the developer portal
Miner mode
Miners, also known as validators, play a crucial role in proposing and validating new blocks on the blockchain, ensuring the network operates correctly.
The process of becoming a validator is selective to mitigate the risk of malicious activity. Although the role is not currently compensated, those interested in supporting the open-source protocol are encouraged to apply.
To become a validator, there is a manual verification process in place. If you're interested, please follow these steps and reach out to our team via Discord or email for further instructions.
Generate a private key: hexdump -n 32 -e '4/4 "%08x" 1 ""' /dev/urandom
Clone and prepare environment:
git clone https://github.com/vocdoni/vocdoni-node.git -b release-lts-1
cd vocdoni-node/dockerfiles/vocdoninode
echo "VOCDONI_NODE_TAG=release-lts-1" > .env
Create the config env
file.
VOCDONI_DATADIR=/app/run
VOCDONI_MODE=miner
VOCDONI_CHAIN=lts
VOCDONI_LOGLEVEL=info
VOCDONI_VOCHAIN_LOGLEVEL=error
VOCDONI_DEV=True
VOCDONI_ENABLEAPI=False
VOCDONI_ENABLERPC=False
VOCDONI_LISTENHOST=0.0.0.0
VOCDONI_LISTENPORT=9090
VOCDONI_VOCHAIN_MINERKEY=<YOUR_HEX_PRIVATE_KEY>
VOCDONI_VOCHAIN_MEMPOOLSIZE=20000
VOCDONI_METRICS_ENABLED=True # if you want prometheus metrics enabled
VOCDONI_METRICS_REFRESHINTERVAL=5
Finally start the container: COMPOSE_PROFILES=watchtower docker compose up -d
You can monitor the log output: docker compose logs -f vocdoninode
Fetch the validator key
At this point if you want your node to become validator, you need to extract the public key from the logs:
docker compose logs vocdoninode | grep publicKey
.
Provide the public key and a fancy name to the Vocdoni team so they can upgrade your node to validator.
Testing
The test suite is an all-in-one compose file to bootstrap a minimal testing testing environment. To do a voting process test, follow the examples mentioned in the included README:
cd dockerfiles/testsuite
cat README.md
bash start_test.sh # creates the environment and runs all tests
Directories
¶
Path | Synopsis |
---|---|
cmd
|
|
Package crypto contains cryptographic interfaces used in the vocdoni project.
|
Package crypto contains cryptographic interfaces used in the vocdoni project. |
ethereum
Package ethereum provides cryptographic operations used in go-dvote related to ethereum.
|
Package ethereum provides cryptographic operations used in go-dvote related to ethereum. |
nacl
Package nacl implements encryption and decryption using anonymous sealed boxes, depending on golang.org/x/crypto/nacl/box.
|
Package nacl implements encryption and decryption using anonymous sealed boxes, depending on golang.org/x/crypto/nacl/box. |
zk
Package zk provides utilities around the zkSNARK (Groth16) tooling.
|
Package zk provides utilities around the zkSNARK (Groth16) tooling. |
zk/prover
prover package abstracts the logic and types of go-rapidsnark (https://github.com/iden3/go-rapidsnark) to support basic operations for the rest of vocdoni-node project.
|
prover package abstracts the logic and types of go-rapidsnark (https://github.com/iden3/go-rapidsnark) to support basic operations for the rest of vocdoni-node project. |
Package data provides an abstraction layer for distributed data storage providers (currently only IPFS)
|
Package data provides an abstraction layer for distributed data storage providers (currently only IPFS) |
ipfs/ipfsconnect
Package ipfsconnect provides a service to maintain persistent connections (PersistPeers) between two or more IPFS nodes
|
Package ipfsconnect provides a service to maintain persistent connections (PersistPeers) between two or more IPFS nodes |
Package statedb contains the implementation of StateDB, a database backed structure that holds the state of the blockchain indexed by version (each version corresponding to the state at each block).
|
Package statedb contains the implementation of StateDB, a database backed structure that holds the state of the blockchain indexed by version (each version corresponding to the state at each block). |
test
|
|
arbo
Package arbo implements a Merkle Tree compatible with the circomlib implementation of the MerkleTree, following the specification from https://docs.iden3.io/publications/pdfs/Merkle-Tree.pdf and https://eprint.iacr.org/2018/955.
|
Package arbo implements a Merkle Tree compatible with the circomlib implementation of the MerkleTree, following the specification from https://docs.iden3.io/publications/pdfs/Merkle-Tree.pdf and https://eprint.iacr.org/2018/955. |
Package vochain provides all the functions for creating and managing a vocdoni voting blockchain
|
Package vochain provides all the functions for creating and managing a vocdoni voting blockchain |
ist
Package ist provides the Internal State Transition (IST) mechanism for Vochain.
|
Package ist provides the Internal State Transition (IST) mechanism for Vochain. |
state/electionprice
Package electionprice provides a mechanism for calculating the price of an election based on its characteristics.
|
Package electionprice provides a mechanism for calculating the price of an election based on its characteristics. |