+ 
+
+ 
+ 
+ 
+ 
+
+ 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 » +
+
+
+
+# census3
+
+Census3 is an API service which facilitates the creation of Vocdoni censuses whose eligible voters are defined by token-holders of some cryptocurrency token(s). The service has a list of registered tokens whose holder addresses and balances it keeps updated in real time.
+
+The Census3 service then uses this token-holder information to create a merkle tree census (compatible with [Vocdoni](https://vocdoni.io/)) according to some given eligibility criteria.
+
+This code is written in golang and is meant to be used in conjunction with other Vocdoni tools, such as the [API](https://developer.vocdoni.io/vocdoni-api/vocdoni-api).
+
+The best place to learn about interacting with the Census3 Service is the [developer portal](https://developer.vocdoni.io/).
+
+### Table of Contents
+- [Getting Started](#getting-started)
+- [Reference](#reference)
+- [Examples](#examples)
+- [Preview](#preview)
+- [Disclaimer](#disclaimer)
+- [Contributing](#contributing)
+- [License](#license)
+
+
+## Getting Started
+
+You can run the Census3 service locally for testing or deploy it yourself.
#### Using the CLI
-1. Build the project:
+You can locally host your own Census3 service by first building this code:
```sh
go build -o census3 ./cmd/census3
```
-2. Run the CLI:
-
+Then you can run the binary with the following possible options:
```sh
./census3 --help
Usage of ./census3:
@@ -128,9 +134,15 @@ CENSUS3_INITIALTOKENS="/app/initial_tokens.json"
docker compose up -d
```
-### Basic example
+## Reference
+
+The Census3 usage and API is documented at the [developer portal](https://developer.vocdoni.io/protocol/census/on-chain/census3#api-defintion). We recommend reading this documentation before trying to run your own examples.
+
+## Examples
-0. Starts the API service on `localhost:7788` with a web3 provider for `mainnet`
+The following shows a basic example for creating a Census3 census using a locally-running instance:
+
+0. Start the API service on `localhost:7788` with a web3 provider for `mainnet`
1. Register a new `erc20` token from `mainnet (chainId: 1)` by its contract address:
```sh
@@ -139,25 +151,25 @@ curl -X POST \
http://localhost:7788/api/tokens
```
-2. Wait to that the API service completes the token sync. It could take up to 10-20 minutes, even more, based on the number of holders and transactions. You can check the token sync status getting the token info:
+1. Wait for the API service to complete the token synchronization. It could take up to 10-20 minutes, even more, based on the number of holders and transactions (for this reason, high-traffic tokens like ETH are infeasible). You can check the token sync status by fetching the token info:
```sh
curl -X GET \
http://localhost:7788/api/tokens/0xFE67A4450907459c3e1FFf623aA927dD4e28c67a
```
-3. When the API ends, and the token reaches `synced` status (`token.status.synced = true`), its time to create a new census based on the default token strategy. This strategy is created during the token registration and just contains the holders of this token. To create the census with token holders, you need to know the `token.defaultStrategy` (from token info endpoint):
+1. When the token reaches `synced` status (`token.status.synced = true`), you can create a new census based on the default token strategy. This strategy is created during the token registration and just contains the holders of the token. To create the census with token holders, you need to know the `token.defaultStrategy` (from the token info endpoint):
```sh
curl -X POST \
--json '{"strategyID": + 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 ++