vocdoni-node

This repository contains a set of libraries and tools for the Vocdoni decentralized protocol, as described in the documentation. It is written in golang and comprises the core of Vocdoni's distributed node architecture. 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.

The latest release is available at https://github.com/vocdoni/vocdoni-node/tree/v1.10.1

Table of Contents

• Getting Started
• Reference
• Examples
• Contributing
• License

Getting Started

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.

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.22 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 --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. Once the node has finished the blockchain sync process, you can connect query the API at this address.

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

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 name to the Vocdoni team so they can upgrade your node to validator.

Reference

Vocdoni Node provides a core API with which anyone can interact with the Vocdoni protocol. This REST API is documented at our developer portal. You can also generate these API docs by following the instructions in https://github.com/vocdoni/vocdoni-node/blob/main/api/docs/README.md.

This API is abstracted by the Vocdoni SDK, a typescript library that facilitates integration with vocdoni-node.

The overall design of the Vocdoni Protocol is documented as well. This provides a high-level specification of much of the functionality of vocdoni-node.

Additional lower-level documentation and guidance is provided in the README files for many of the libraries in this repository, especially for internal tools. An example of this is the statedb package.

Examples

Vocdoni Node is an extensive library and protocol with many different elements.

You can see example usage of many of the components in the test folder.

We have also created a standalone node configuration called vocone to be used for testing. You can see how to build vocone and run a full end-to-end example in the corresponding dockerfile folder. You can also just build and run vocone and use it to locally test the API or other vocdoni node functionality.

Contributing

While we welcome contributions from the community, we do not track all of our issues on Github and we may not have the resources to onboard developers and review complex pull requests. That being said, there are multiple ways you can get involved with the project.

Please review our development guidelines.

Testing

The test suite for this repo is an all-in-one compose file to bootstrap a minimal testing environment. To do a voting process test, follow the examples mentioned in the included dockerfiles/testsuite/README.md:

cd dockerfiles/testsuite
cat README.md
bash start_test.sh # creates the environment and runs all tests

License

This repository is licensed under the GNU Affero General Public License v3.0.

Vocdoni Node core library
Copyright (C) 2024 Vocdoni Association

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU Affero General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License
along with this program.  If not, see <https://www.gnu.org/licenses/>.