# 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
You can locally host your own Census3 service by first building this code:
```sh
go build -o census3 ./cmd/census3
```
Then you can run the binary with the following possible options:
```sh
./census3 --help
Usage of ./census3:
--adminToken string the admin UUID token for the API
--connectKey string connect group key for IPFS connect
--dataDir string data directory for persistent storage (default "~/.census3")
--logLevel string log level (debug, info, warn, error) (default "info")
--port int HTTP port for the API (default 7788)
--scannerCoolDown duration the time to wait before next scanner iteration (default 2m0s)
--initialTokens string path of the initial tokens json file
--web3Providers string the list of URLs of available web3 providers
--gitcoinEndpoint string Gitcoin Passport API access token
--gitcoinCooldown duration Gitcoin Passport API cooldown (default 6h0m0s)
--poapAPIEndpoint string POAP API endpoint
--poapAuthToken string POAP API access token
```
Example:
```sh
./census3 --web3Providers https://goerli.rpcendpoint.io/,https://mainnet.rpcendpoint.io/ --logLevel debug
# or just:
# go run ./cmd/census3 --web3Providers https://goerli.rpcendpoint.io/,https://mainnet.rpcendpoint.io/ --logLevel debug
```
#### Using Docker
1. Create your config file using the [`.env` file](example.env) as a template and save it the root.
```sh
# Domain name for TLS
DOMAIN=your.own.domain.xyz
# A web3 endpoint provider
CENSUS3_WEB3PROVIDERS="https://rpc-endoint.example1.com,https://rpc-endoint.example2.com"
# Internal port for the service (80 and 443 are used by traefik)
CENSUS3_PORT=7788
# Log level (info, debug, warning, error)
CENSUS3_LOGLEVEL="debug"
# IPFS connect key for discovering nodes
# CONNECT_KEY=yourIPFSConnectKey
CENSUS3_CONNECTKEY="census3key"
# Internal data folder
CENSUS3_DATADIR="./.census3"
# Scanner cooldown duration
CENSUS3_SCANNERCOOLDOWN="20s"
# UUID admin token for protected endpoints
CENSUS3_ADMINTOKENS="UUID"
# POAP API configuration
CENSUS3_POAPAPIENDPOINT="poapAPIEndpoint"
CENSUS3_POAPAUTHTOKEN="yourPOAPAuthToken"
# Gitcoin API configuration
CENSUS3_GITCOINAPIENDPOINT="gitcoinAPIEndpoint"
CENSUS3_INITIALTOKENS="/app/initial_tokens.json"
```
2. Run the services with `docker compose`:
```sh
docker compose up -d
```
## 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
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
curl -X POST \
--json '{"ID": "0xFE67A4450907459c3e1FFf623aA927dD4e28c67a", "type": "erc20", "chainID": 1}' \
http://localhost:7788/api/tokens
```
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
```
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": 
