Skip to content

Commit

Permalink
Refactor readme using template
Browse files Browse the repository at this point in the history
  • Loading branch information
@NateWilliams2 @p4u
NateWilliams2 authored and p4u committed Apr 23, 2024
1 parent 974089f commit b453785
Show file tree
Hide file tree
Showing 2 changed files with 108 additions and 66 deletions.
172 changes: 107 additions & 65 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,46 +1,76 @@
# vocdoni-node

[![GoDoc](https://godoc.org/go.vocdoni.io/dvote?status.svg)](https://godoc.org/go.vocdoni.io/dvote)
[![Go Report Card](https://goreportcard.com/badge/go.vocdoni.io/dvote)](https://goreportcard.com/report/go.vocdoni.io/dvote)
[![Coverage Status](https://coveralls.io/repos/github/vocdoni/vocdoni-node/badge.svg)](https://coveralls.io/github/vocdoni/vocdoni-node)

[![Join Discord](https://img.shields.io/badge/discord-join%20chat-blue.svg)](https://discord.gg/xFTh8Np2ga)
[![Twitter Follow](https://img.shields.io/twitter/follow/vocdoni.svg?style=social&label=Follow)](https://twitter.com/vocdoni)

This repository contains a set of libraries and tools for the **Vocdoni** decentralized protocol, as described [in the documentation](https://developer.vocdoni.io/protocol/overview).

If you want to build on top of the Vocdoni protocol, you can visit the [developer portal](https://developer.vocdoni.io)

A good summary of the whole Vocdoni architecture can be found in [this paper](https://law.mit.edu/pub/remotevotingintheageofcryptography)

## 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.
<p align="center" width="100%">
<img src="https://developer.vocdoni.io/img/vocdoni_logotype_full_white.svg" />
</p>

<p align="center" width="100%">
<a href="https://github.com/vocdoni/vocdoni-node/commits/main/"><img src="https://img.shields.io/github/commit-activity/m/vocdoni/vocdoni-node" /></a>
<a href="https://github.com/vocdoni/vocdoni-node/issues"><img src="https://img.shields.io/github/issues/vocdoni/vocdoni-node" /></a>
<a href="https://github.com/vocdoni/vocdoni-node/actions/workflows/main.yml/"><img src="https://github.com/vocdoni/vocdoni-node/actions/workflows/main.yml/badge.svg" /></a>
<a href="https://godoc.org/go.vocdoni.io/dvote"><img src="https://godoc.org/go.vocdoni.io/dvote?status.svg"></a>
<a href="https://goreportcard.com/report/go.vocdoni.io/dvote"><img src="https://goreportcard.com/badge/go.vocdoni.io/dvote"></a>
<a href="https://coveralls.io/github/vocdoni/vocdoni-node"><img src="https://coveralls.io/repos/github/vocdoni/vocdoni-node/badge.svg"></a>
<a href="https://discord.gg/xFTh8Np2ga"><img src="https://img.shields.io/badge/discord-join%20chat-blue.svg" /></a>
<a href="https://twitter.com/vocdoni"><img src="https://img.shields.io/twitter/follow/vocdoni.svg?style=social&label=Follow" /></a>
</p>


<div align="center">
Vocdoni is the first universally verifiable, censorship-resistant, anonymous, and self-sovereign governance protocol. <br />
Our main aim is a trustless voting system where anyone can speak their voice and where everything is auditable. <br />
We are engineering building blocks for a permissionless, private and censorship resistant democracy.
<br />
<a href="https://developer.vocdoni.io/"><strong>Explore the developer portal »</strong></a>
<br />
<h3>More About Us</h3>
<a href="https://vocdoni.io">Vocdoni Website</a>
|
<a href="https://vocdoni.app">Web Application</a>
|
<a href="https://explorer.vote/">Blockchain Explorer</a>
|
<a href="https://law.mit.edu/pub/remotevotingintheageofcryptography/release/1">MIT Law Publication</a>
|
<a href="https://chat.vocdoni.io">Contact Us</a>
<br />
<h3>Key Repositories</h3>
<a href="https://github.com/vocdoni/vocdoni-node">Vocdoni Node</a>
|
<a href="https://github.com/vocdoni/vocdoni-sdk/">Vocdoni SDK</a>
|
<a href="https://github.com/vocdoni/ui-components">UI Components</a>
|
<a href="https://github.com/vocdoni/ui-scaffold">Application UI</a>
|
<a href="https://github.com/vocdoni/census3">Census3</a>
</div>

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.
# vocdoni-node

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.
This repository contains a set of libraries and tools for the **Vocdoni** decentralized protocol, as described [in the documentation](https://developer.vocdoni.io/protocol).
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.

<img src="https://raw.githubusercontent.com/vocdoni/vocdoni-node/main/assets/vocdoni_logo.svg?sanitize=true&raw=true" />
The latest release is available at https://github.com/vocdoni/vocdoni-node/tree/v1.10.1

### Table of Contents
- [Getting Started](#getting-started)
- [Reference](#reference)
- [Examples](#examples)
- [Contributing](#contributing)
- [License](#license)

## vocdoni node

The Vocdoni node is equipped with all the necessary components to operate a node on the decentralized Vocdoni protocol blockchain.
## 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
### 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
Expand All @@ -52,7 +82,7 @@ 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
./node --mode=gateway --logLevel=info
```

#### Docker
Expand All @@ -67,7 +97,7 @@ 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`.
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.

Expand All @@ -77,39 +107,7 @@ To stop the container:
docker compose down
```

#### Connecting

Once the node has finished the blockchain sync process, you can connect query the API:

`$ curl http://127.0.0.1:9090/v2/chain/info`

```json
{
"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](https://developer.vocdoni.io)

## Miner mode
### 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.

Expand Down Expand Up @@ -155,19 +153,63 @@ At this point **if you want your node to become validator**, you need to extract

`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.
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](https://developer.vocdoni.io/vocdoni-api/vocdoni-api). 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](https://developer.vocdoni.io/sdk), a typescript library that facilitates integration with vocdoni-node.

## Testing
The overall design of the Vocdoni Protocol is [documented](https://developer.vocdoni.io/protocol) as well. This provides a high-level specification of much of the functionality of vocdoni-node.

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:
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](https://github.com/vocdoni/vocdoni-node/blob/main/statedb/README.md) 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](https://github.com/vocdoni/vocdoni-node/tree/main/test) folder.

We have also created a standalone node configuration called [vocone](https://github.com/vocdoni/vocdoni-node/tree/main/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](https://github.com/vocdoni/vocdoni-node/blob/main/dockerfiles/vocone/README.md). 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](https://developer.vocdoni.io/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`:

```bash
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.](./LICENSE)

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/>.


---

[![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-v1.4%20adopted-ff69b4.svg)](code-of-conduct.md) [![License: AGPL v3](https://img.shields.io/badge/License-AGPL%20v3-blue.svg)](https://www.gnu.org/licenses/agpl-3.0)
2 changes: 1 addition & 1 deletion dockerfiles/vocone/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ docker compose up -d

Ports 80 and 9090 are now serving the voconi API.

For runing a voting test:
For running a voting test:
```
go run ./cmd/end2endtest --host=http://localhost/v2 --logLevel=debug --votes=100 --faucet=http://localhost/v2/faucet/dev/
```

0 comments on commit b453785

Please sign in to comment.