From b4537854b57ae334f213f4f16af4c43e168a4d90 Mon Sep 17 00:00:00 2001 From: NateWilliams2 Date: Mon, 22 Apr 2024 13:39:02 -0400 Subject: [PATCH] Refactor readme using template --- README.md | 172 ++++++++++++++++++++++------------- dockerfiles/vocone/README.md | 2 +- 2 files changed, 108 insertions(+), 66 deletions(-) diff --git a/README.md b/README.md index 562df660e..365115464 100644 --- a/README.md +++ b/README.md @@ -1,32 +1,65 @@ -# 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. +

+ +

+ +

+ + + + + + + + +

+ + +
+ Vocdoni is the first universally verifiable, censorship-resistant, anonymous, and self-sovereign governance protocol.
+ Our main aim is a trustless voting system where anyone can speak their voice and where everything is auditable.
+ We are engineering building blocks for a permissionless, private and censorship resistant democracy. +
+ Explore the developer portal ยป +
+

More About Us

+ Vocdoni Website + | + Web Application + | + Blockchain Explorer + | + MIT Law Publication + | + Contact Us +
+

Key Repositories

+ Vocdoni Node + | + Vocdoni SDK + | + UI Components + | + Application UI + | + Census3 +
-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. - +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: @@ -34,13 +67,10 @@ There are two operational modes available for the node: - 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 @@ -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 @@ -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. @@ -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. @@ -155,12 +153,35 @@ 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 @@ -168,6 +189,27 @@ 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 . + + --- [![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) diff --git a/dockerfiles/vocone/README.md b/dockerfiles/vocone/README.md index f5fad4e51..d5d712324 100644 --- a/dockerfiles/vocone/README.md +++ b/dockerfiles/vocone/README.md @@ -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/ ```