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 »
Vocdoni Website | Web Application | Blockchain Explorer | MIT Law Publication | Contact Us
Vocdoni Node | Vocdoni SDK | UI Components | Application UI | 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) 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.
The best place to learn about interacting with the Census3 Service is the developer portal.
You can run the Census3 service locally for testing or deploy it yourself.
You can locally host your own Census3 service by first building this code:
go build -o census3 ./cmd/census3Then you can run the binary with the following possible options:
./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 tokenExample:
./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- Create your config file using the
.envfile as a template and save it the root.
# 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"- Run the services with
docker compose:
docker compose up -dThe Census3 usage and API is documented at the developer portal. We recommend reading this documentation before trying to run your own examples.
The following shows a basic example for creating a Census3 census using a locally-running instance:
- Start the API service on
localhost:7788with a web3 provider formainnet - Register a new
erc20token frommainnet (chainId: 1)by its contract address:
curl -X POST \
--json '{"ID": "0xFE67A4450907459c3e1FFf623aA927dD4e28c67a", "type": "erc20", "chainID": 1}' \
http://localhost:7788/api/tokens- 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:
curl -X GET \
http://localhost:7788/api/tokens/0xFE67A4450907459c3e1FFf623aA927dD4e28c67a- When the token reaches
syncedstatus (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 thetoken.defaultStrategy(from the token info endpoint):
curl -X POST \
--json '{"strategyID": <strategyId>, "anonymous": true}" \
http://localhost:7788/api/censuses- The previous request will return a
queueIdwhich identifies the census creation and publication processes on the API queue. Census publication will be completed in the background. We can check if the task is done and whether it raised an error or was successfully completed:
curl -X GET \
http://localhost:7788/censuses/queue/<queueId>You can also automatically run this example using the example.sh file:
sh ./example.sh
-> creating token...
Ok
-> created, waiting 4m to token scan
-> getting token info...
{"id":"0xFE67A4450907459c3e1FFf623aA927dD4e28c67a","type":"erc20","decimals":18,"startBlock":16976695,"symbol":"NEXT","totalSupply":"1000000000000000000000000000","name":"Connext","status":{"atBlock":18092468,"synced":true,"progress":100},"size":644,"defaultStrategy":1,"chainID":1}
-> enter the strategyId:
1
-> creating census...
{"queueId":"cd234ba75988e04e1e7a3234e48ff4033633142f"}
-> waiting 1m to census publication
-> enter the enqueue census:
cd234ba75988e04e1e7a3234e48ff4033633142f
{"done":true,"error":null,"census":{"censusId":1,"strategyId":1,"merkleRoot":"73368af290f4d0dfcb25b12060184bb3e5ad4147c5e8639de6729800c3629509","uri":"ipfs://bafybeiehspu3xrpshzjcvexl52u756cwfjobcwjz7ol4as44zfpvnlchsu","size":644,"weight":"5180125781955736442164650279357953853238828163172892166520872906800","anonymous":true}}You can see the Census3 API in use with the Vocdoni SDK at the SDK's census3 example
The Census3 service is WIP. Please beware that it can be broken at any time if the release is alpha or beta. We encourage you to review this repository and the developer portal for any changes.
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.
This repository is licensed under the GNU Affero General Public License v3.0.
Vocdoni Census3 Service
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/>.
