MACI CLI

2.5.0 verified Sat May 09 auth: no javascript

Command-line interface for Minimal Anti-Collusion Infrastructure (MACI), version 2.5.0. MACI is a set of smart contracts and zero-knowledge proofs for on-chain voting that prevents bribery and coercion. This CLI provides tools for deploying, managing, and interacting with MACI instances. It captures commands for coordinator operations, user key generation, and contract deployment. Released under the MACI project, updated infrequently with new protocol iterations.

Common errors

error Error: Invalid private key ↓

cause Passing a Buffer object instead of a hex string.

fix

Convert using SerializedPrivateKey = privKey.serialize().

error TypeError: Cannot read properties of undefined (reading 'serialize') ↓

cause Attempting to serialize an already serialized key.

fix

Only call serialize() on Keypair objects, not on hex strings.

error Error: Contract not deployed ↓

cause Using CLI without deploying MACI contracts first.

fix

Run maci deploy or use hardhat tasks to deploy.

error Error: voting period not started ↓

cause Calling publish or tallyVotes outside the voting window.

fix

Check contract timestamps or wait until the voting period is active.

error Error: invalid proof ↓

cause Using zk-SNARK artifacts that do not match the deployed circuit.

fix

Ensure the circuit files (e.g., processMessages) are correctly generated and placed in the expected path.

Warnings

breaking MACI v2.0 uses a new key format. Old keys must be regenerated. ↓

fix Generate new keys using Keypair.generate() from maci-domainobjs.

breaking MACI v2.0 requires a fresh smart contract deployment. Not backward-compatible with v1.x. ↓

fix Deploy new contracts using CLI or hardhat tasks.

deprecated The old `create` subcommand is deprecated; use `signup` instead. ↓

fix Replace `create` with `signup`.

gotcha All private keys must be serialized as hex strings. Raw Buffer objects are not accepted. ↓

fix Use privKey.serialize() to get a hex string.

gotcha State leaf hashes differ between MACI v2.0 and v2.5.0. Tally results will fail if mismatched. ↓

fix Ensure your contract artifacts and CLI versions match exactly.

Install

npm install maci-cli

yarn add maci-cli

pnpm add maci-cli

Imports

default

wrong

import { maciCLI } from 'maci-cli'

correct

import maciCLI from 'maci-cli'

Default export provides the CLI entry point.

CLI

wrong

const CLI = require('maci-cli').CLI

correct

import { CLI } from 'maci-cli'

Named export 'CLI' is available for programmatic use.

Subcommands

wrong

import * as maciCLI from 'maci-cli'

correct

import { deployVkRegistry, setVerifyingKeys, signup, publish, tallyVotes, processMessages } from 'maci-cli'

Individual named exports for each subcommand; available since v2.5.0. Using wildcard import may clash with other MACI packages.

CLI
wrong
```
const maciCLI = require('maci-cli')
```
correct
```
const { CLI } = require('maci-cli')
```
CommonJS require works with named exports. Default export not applicable for CJS.

Quickstart

Shows how to use key CLI functions programmatically: generate keys, signup user, publish vote, process messages, and tally votes.

import { signup, publish, processMessages, tallyVotes } from 'maci-cli';
import { PrivKey, PubKey, Keypair } from 'maci-domainobjs';

async function main() {
  const keypair = new Keypair();
  const privKey = keypair.privKey.serialize();
  const pubKey = keypair.pubKey.serialize();
  await signup({ pubKey, privateKey: privKey });
  const vote = { voteOptionIndex: 1, voteWeight: 9 };
  await publish({ privateKey: privKey, vote, stateIndex: 1 });
  await processMessages();
  const result = await tallyVotes();
  console.log('Tally result:', result);
}
main().catch(console.error);