How to Run aMACI Operator Service on Dora Vota Mainnet (`vota-ash`)

The aMACI operator service is a unique feature offered by the Dora Factory Anonymous MACI protocol (aMACI). Running an aMACI operator means that you will run and tally an aMACI round for a community, and validate the round with zero-knowledge proofs.

The first batch of aMACI opearators will be Dora Vota mainnet validators. From the protocol’s frontend (opens in a new tab), users will be able to create aMACI rounds and select an aMACI operator.

Requirements

Hardware requirements

Basic configuration

CPU: 4 cores
Memory: 8 GB
Disk: 256 GB

Better configuration

CPU: 8 cores
Memory: 16 GB
Disk: 512 GB

Software requirements

Node.js (opens in a new tab) version >= 20
dorad (opens in a new tab) version = 0.4.0

Create an aMACI operator account

⚠️

We strongly recommend you create a new account which will be used later to register as an aMACI operator. It is prohibited to use the validator’s owner address as the aMACI operator address, because it may cause the aMACI operator to fail to process transactions.

export AMACI_OPERATOR=amaci-operator
dorad keys add $AMACI_OPERATOR

To initiate the operator, please prepare 1,000 DORA for your operator account to support the service, and monitor the balance of the account in a timely manner. Insufficient balance may affect the operation of the aMACI operator service.

⚠️

Please make sure you have backed up the MNEMONIC of this account which is the only method to recover it. Also, it will be used when initiating aMACI operator service.

Install the `maci` cli

npm install -g @dorafactory/maci-operator@1.4.0

How to use maci cli

Run the command maci in your terminal, it will show the version of your maci cli and the usage.

> maci
 
maci - MACI operator CLI v1.4.0
 
Usage:
  maci init <dir> [--zkey <path>] [--force]
  maci start <dir> [--zkey <path>]
  maci zkey download <dir> [--zkey <path>] [--force]
  maci set-operator identity <dir>
  maci set-operator maciPubKey <dir>
 
Options:
  -h, --help       Show this help message
  -v, --version    Show version number

Init your amaci operator with maci cli

Choose a new directory as the working directory for the amaci operator. All log files and data will be stored there.

maci init <WORK_PATH>

By default, this command generates data, log, and round directories and a config.toml file in the WORK_DIR.
It also downloads and extracts the zkey files into a zkey folder within your WORK_DIR.

If you want to customize the zkey path, you can run:

maci init <WORK_PATH> --zkey <ZKEY_PATH>

You can use --zkey to specify a custom zkey directory.
If the specified path does not contain the zkey folder, it will automatically download and extract the zkey files into ZKEY_PATH. If the zkey directory already exists in your specified directory, you will be asked whether you want to overwrite the download, choose y/n.

Configure and Register your aMACI operator service

Configure your amaci operator

All configurations for the amaci operator are based on the config.toml file generated through maci init. Please ensure that you have generated the corresponding config template file through maci init.

The config template file generated by maci init is as follows, where workPath and zkeyPath are the paths set during initialization.

# aMACI operator configuration (config.toml)
# Fill RPC/Indexer endpoints and identity. Both coordinatorPrivKey (MACI key) and mnemonic (operator wallet) must be set.
 
# Working directory for data, logs and caches
workPath = "xxxxx/test-data"
 
# RPC endpoint of chain (e.g., https://rpc.node:26657)
rpcEndpoint = ""
# Indexer endpoint (GraphQL)
indexerEndpoint = ""
# Deactivate recorder contract address(registryContract)
registryContract = ""
 
# Operator identity (set on registry via: amaci set-operator identity <workDir>)
identity = ""
 
# Filter rounds by code IDs (array of strings)
codeIds = [""]
 
# aMACI operator account mnemonic on vota chain.
# Please pay special attention that this operator must be used independently for the operator.
# Otherwise it will cause sequence conflicts. It is also necessary to monitor the account balance to ensure the operator can pay the on-chain fees.
# It is recommended to set an alert if it falls below 500 DORA and replenish funds in a timely manner.
mnemonic = ""
# operator MACI PrivKey(generated locally when set MACI key, do not share it)
coordinatorPrivKey = ""
 
# Interval between deactivate tasks (ms)
deactivateInterval = 60000
# Log level: error | warn | info | debug
logLevel = "info"
# Metrics server port(default: 3001)
metricsPort = 3001
 
# Path to zkey folder containing circuit packs (2-1-1-5_v3, 4-2-2-25_v3)
zkeyPath = "xxxx/zkey"
 
# Prover configuration
[prover]
# Enable pipeline submission (1 to enable)
pipeline = 1
# Number of concurrent prover workers
concurrency = 2
# Persist proofs/inputs in chunks (0 = use the number of concurrency)
saveChunk = 0
 
# Submission batch sizes (0 = use saveChunk if > 0, otherwise concurrency)
[prover.submitBatch]
msg = 0
tally = 0
deactivate = 0

Step 1: Configure your `config.toml`

Enter the rpc url (It ensures that you can use a stable and continuous RPC services, it is recommended that you use your validator RPC or stable full node RPC) into the rpcEndpoint field in your config.toml file.
Enter the indexer url with https://vota-api.dorafactory.org into the indexerEndpoint field in your config.toml file.
Enter the contract address with dora1smg5qp5trjdkcekdjssqpjehdjf6n4cjss0clyvqcud3t3u3948s8rmgg4 into the registryContract field in your config.toml file.
Enter the identity with your Keybase ID into the identity field in your config.toml file.
Enter the code id with ["93","95","103","118","121","123","128"] into the codeIds field in your config.toml file.
Enter the mnemonic of the previously generated aMACI operator account into the mnemonic field in your config.toml file.

We will use the Keybase ID as your operator identity here. The Keybase ID is a 16-digit string that is generated with a keybase.io (opens in a new tab) account. It’s a cryptographically secure method of verifying your identity across multiple online networks. The Keybase API allows us to retrieve your Keybase avatar and other public info.

Register your amaci operator

⚠️

If you have already registered as an amaci operator, you can skip this section.

Step 1: Register your amaci operator identity

maci set-operator identity <WORK_PATH>

This command will register your amaci operator according to the identity you set in config.toml.

Step 2: Register your amaci operator pub key

⚠️

If you are starting and registering the amaci operator for the first time, you can directly generate a public and private key for the amaci operator using maci cli, and the private key will be saved in coordinatorPrivKey of config.toml.

📌Please back up the generated public and private keys.

maci set-operator maciPubKey <WORK_PATH>

This command will first generate your MACI private key locally, fill it into the coordinatorPrivKey field of config.toml. and register the public key on the chain through the RPC address set in your config.toml.

The format of the public key:

X: 16429304017412205675820866000313944904446810339972042319485432996531286181952
Y: 5572999208344294573488778747734990567557173306854827005273539480127951622273

Setup aMACI operator service

Start your operator with maci cli

maci start <WORK_PATH>

If the service started successfully, the log will output your aMACI operator’s information and download some necessary zkey files. Like this:

[2025-05-16 17:17:54.940] [INFO] [INIT]  Init your coordinator info
.......
.......
.......
[2025-05-16 17:17:55.000] [INFO] [INIT]  code id list: ["93","95","103","118","121","123","128"]
[2025-05-16 17:17:55.000] [INFO] [INIT]  Check your required zkey files🧐🧐🧐🧐
[2025-05-16 17:17:55.004] [INFO] [METRICS]  Metrics server started on port 3001
.......
.......
.......

What is the aMACI operator service doing?

The aMACI operator service periodically checks aMACI rounds that need to be processed on the vota-ash mainnet.
The aMACI operator service logs processed aMACI round information and other data in the /amaci-operator/work directory.

Snapshot Vota Incentivized Testnet

How to Run aMACI Operator Service on Dora Vota Mainnet (vota-ash)