NCN CLI

The NCN CLI (Solana Governance Voter Snapshot CLI) is an operator-facing Rust tool for generating stake snapshots (ledger snapshot → MetaMerkleSnapshot) and interacting with the on-chain ncn-snapshot program: initializing config, managing the operator whitelist, casting and removing votes, finalizing ballots, setting tie-breakers, and inspecting on-chain state.

Operator startup (snapshot-first checklist)

If you are onboarding an operator, start from this flow before running voting commands:

1. Run and sync a validator/RPC machine to chain tip.
2. Use startup settings that keep snapshots available for NCN snapshot generation.
3. Generate a snapshot and MetaMerkle artifact.
4. Log the Merkle root/hash and verify outputs.
5. Upload to verifier service and fetch proof/meta endpoints to validate end-to-end availability.

Recommended validator/RPC startup settings

These values are the baseline used for NCN operator testing:

Installation

git clone https://github.com/solana-foundation/solana-governance.git
cd solana-governance
make install-ncn-cli 

Global Options

These options are available on all commands. Each can also be set via the matching environment variable.

Environment variable: NCN_SNAPSHOT_MAX_MB — max decompressed snapshot size in MiB (default: 256)

Snapshot Commands

snapshot-slot

Generates a Solana ledger snapshot for a specific target slot. Replays the validator bank up to --slot and writes a full snapshot into --backup-snapshots-dir. Requires --ledger-path and --full-snapshots-path (or defaults derived from --ledger-path).

ncn-cli \
  --ledger-path /mnt/ledger \
  --full-snapshots-path /mnt/ledger/full-snapshots \
  --backup-snapshots-dir /mnt/ledger/backup-snapshots \
  snapshot-slot --slot <SLOT>

Snapshot path flags

• --full-snapshots-path: Where the CLI reads full snapshots from.
• --backup-snapshots-dir: Where snapshot artifacts are copied/saved for backup.

generate-meta-merkle

Builds a MetaMerkleSnapshot from an existing full ledger snapshot. Loads the bank at --slot from --backup-snapshots-dir and emits a compressed meta_merkle-<slot>.zip containing the stake-weighted merkle tree used for on-chain voting.

ncn-cli \
  --ledger-path /mnt/ledger \
  --account-paths /mnt/accounts \
  --backup-snapshots-dir /mnt/ledger/backup-snapshots \
  generate-meta-merkle \
  --slot 300000000 \
  --save-path ./meta_merkle/

log-meta-merkle-hash

Prints the merkle root, snapshot hash, slot, and a signature over them from a MetaMerkleSnapshot file. Useful for sharing the snapshot identity with other operators before voting on-chain. --authority-path signs an off-chain message containing the snapshot slot and meta merkle root; no on-chain transaction is sent.

ncn-cli \
  --authority-path ~/.config/solana/id.json \
  log-meta-merkle-hash \
  --read-path ./meta_merkle-300000000.zip \
  --is-compressed true

await-snapshot

Waits for a target slot to pass and snapshots it from on-disk snapshots. Polls --snapshots-dir until a full + incremental snapshot pair covering --slot is available, copies them and the relevant ledger range into the backup directories, replays to produce a snapshot at --slot, and optionally generates the MetaMerkleSnapshot. This is the primary command used by automated operator infrastructure.

Important

Always create a new backup directory for --backup-snapshots-dir.
Do not point it to the source snapshots directory (for example, do not reuse /mnt/snapshots).

Initial setup (once)

# Create backup ledger directory
mkdir -p /mnt/ledger/gov-ledger-backup
mkdir -p /mnt/ledger/gov-ledger-backup/snapshots
 
# Copy genesis into backup ledger
cp /mnt/ledger/genesis.bin /mnt/ledger/gov-ledger-backup/genesis.bin

Run await-snapshot

ncn-cli \
  await-snapshot \
  --scan-interval 1 \
  --slot <SLOT> \
  --snapshots-dir /mnt/ledger/snapshots \
  --backup-snapshots-dir /mnt/ledger/gov-ledger-backup/snapshots \
  --backup-ledger-dir /mnt/ledger/gov-ledger-backup \
  --agave-ledger-tool-path /home/sol/.local/share/solana/install/active_release/bin/agave-ledger-tool \
  --ledger-path /mnt/ledger \
  --generate-meta-merkle

Program Config Commands

init-program-config

Initializes the on-chain ProgramConfig singleton. Must be run once per deployment. The signer of --authority-path becomes the initial program authority and is recorded as ProgramConfig.authority. --svmgov-program-id binds which svmgov governance program is allowed to open ballot boxes (it is verified in init_ballot_box when a proposal reaches consensus and CPIs in); source it from networks.toml’s svmgov_program_id.

ncn-cli \
  --payer-path ~/.config/solana/id.json \
  --authority-path ~/.config/solana/id.json \
  --rpc-url https://api.devnet.solana.com \
  init-program-config \
  --svmgov-program-id <PUBKEY>

update-program-config

Updates mutable fields on the on-chain ProgramConfig. All arguments are optional; only the provided fields are updated. --authority-path must be the current program authority (enforced by has_one = authority on ProgramConfig). Updating --proposed-authority starts a two-step authority handover that must be completed via finalize-proposed-authority.

ncn-cli \
  --payer-path ~/.config/solana/id.json \
  --authority-path ~/.config/solana/id.json \
  --rpc-url https://api.devnet.solana.com \
  update-program-config \
  --min-consensus-threshold-bps 6667 \
  --vote-duration 86400 \
  --tie-breaker-admin <PUBKEY> \
  --proposed-authority <PUBKEY> \
  --svmgov-program-id <PUBKEY>

finalize-proposed-authority

Completes a pending two-step authority handover. --authority-path must be the proposed authority previously staged via update-program-config --proposed-authority; the on-chain constraint requires signer == proposed_authority. On success the signer becomes the active program authority and proposed_authority is cleared.

ncn-cli \
  --payer-path <PATH_TO_PAYER_KEYPAIR> \
  --authority-path <PATH_TO_PROPOSED_AUTHORITY_KEYPAIR> \
  --rpc-url <RPC_URL> \
  finalize-proposed-authority

update-operator-whitelist

Adds or removes operator pubkeys from the on-chain whitelist. Only whitelisted operators are allowed to cast votes. --authority-path must be the current program authority (enforced by has_one = authority on ProgramConfig).

# Add operators
ncn-cli \
  --payer-path <PATH_TO_PAYER_KEYPAIR> \
  --authority-path <PATH_TO_AUTHORITY_KEYPAIR> \
  --rpc-url <RPC_URL> \
  update-operator-whitelist \
  -a <PUBKEY1>,<PUBKEY2>,<PUBKEY3>
 
# Remove operators
ncn-cli \
  --payer-path <PATH_TO_PAYER_KEYPAIR> \
  --authority-path <PATH_TO_AUTHORITY_KEYPAIR> \
  --rpc-url https://api.devnet.solana.com \
  update-operator-whitelist \
  -r PUBKEY_OLD
 
# Both at once
ncn-cli \
  --payer-path ~/.config/solana/id.json \
  --authority-path ~/.config/solana/id.json \
  --rpc-url https://api.devnet.solana.com \
  update-operator-whitelist \
  -a PUBKEY_NEW \
  -r PUBKEY_OLD

Voting Commands

cast-vote

Casts an operator vote on a ballot box using an explicit Merkle root and snapshot hash. Prefer cast-vote-from-snapshot when voting from a local snapshot. --authority-path signs as a whitelisted operator; the handler verifies the signer appears in ProgramConfig.whitelisted_operators before recording the vote in the BallotBox.

ncn-cli \
  --payer-path ~/.config/solana/id.json \
  --authority-path ~/.config/solana/id.json \
  --rpc-url https://api.devnet.solana.com \
  cast-vote \
  --snapshot-slot 300000000 \
  --root <BASE58_ROOT> \
  --hash <BASE58_HASH>

cast-vote-from-snapshot

Casts an operator vote using a local MetaMerkleSnapshot file. Reads the root and computes the snapshot hash from --read-path, then submits the vote. --authority-path signs as a whitelisted operator; the handler verifies the signer appears in ProgramConfig.whitelisted_operators before recording the vote in the BallotBox.

ncn-cli \
  --payer-path ~/.config/solana/id.json \
  --authority-path ~/.config/solana/id.json \
  --rpc-url https://api.devnet.solana.com \
  cast-vote-from-snapshot \
  --snapshot-slot 300000000 \
  --read-path ./meta_merkle-300000000.zip \
  --is-compressed true

remove-vote

Removes the caller’s vote from a BallotBox. Only permitted before consensus is reached and before the vote window expires. --authority-path must be the operator that originally cast the vote; the handler removes only that signer’s tally entry.

ncn-cli \
  --payer-path ~/.config/solana/id.json \
  --authority-path ~/.config/solana/id.json \
  --rpc-url https://api.devnet.solana.com \
  remove-vote --snapshot-slot <SLOT>

set-tie-breaker

Resolves a stalled ballot by writing an explicit winning ballot. The provided --root / --hash are not required to match any cast ballot. --authority-path must be the tie-breaker admin recorded in ProgramConfig (enforced by has_one = tie_breaker_admin).

# Set tie-breaking result if consensus was not reached
# Note: Can set any ballot value, not limited to existing ballots
ncn-cli \
  --payer-path ~/.config/solana/id.json \
  --authority-path ~/.config/solana/id.json \
  --rpc-url https://api.devnet.solana.com \
  set-tie-breaker --snapshot-slot <SLOT> \
  --root <MERKLE_ROOT> --hash <SNAPSHOT_HASH>

reset-ballot-box

Resets a bricked BallotBox. Permitted only when the ballot box’s vote window has not yet expired, consensus has not been reached, and ballot tallies are at their maximum capacity. Clears tallies so voting can restart. --authority-path must be the tie-breaker admin recorded in ProgramConfig (enforced by has_one = tie_breaker_admin).

ncn-cli \
  --payer-path ~/.config/solana/id.json \
  --authority-path ~/.config/solana/id.json \
  --rpc-url https://api.devnet.solana.com \
  reset-ballot-box --snapshot-slot <SLOT>

finalize-ballot

Finalizes the winning ballot for a snapshot slot. Closes voting for --snapshot-slot once consensus has been reached (or the vote window has expired with a clear winner) and writes the ConsensusResult PDA. The on-chain instruction is permissionless, so --payer-path is used purely as the fee payer for the new PDA and does not need to hold any privileged role. The --authority-path is not used for this command.

ncn-cli \
  --payer-path ~/.config/solana/id.json \
  --rpc-url https://api.devnet.solana.com \
  finalize-ballot --snapshot-slot <SLOT>

Read / Inspection Commands

Use these commands when you only want to inspect on-chain state (no transactions are sent).

• Use status for a quick all-in-one health check for a slot.
• Use get-* commands for focused machine/operator-readable outputs.
• Use log if you prefer the older generic account lookup flow.

log

Dumps the raw Debug representation of an on-chain account. Selects the account type via --ty; some types require additional arguments such as --snapshot-slot and/or --vote-account.

# View ProgramConfig
ncn-cli \
  --rpc-url https://api.devnet.solana.com log \
  --ty program-config
 
# View a BallotBox
ncn-cli \
  --rpc-url https://api.devnet.solana.com log \
  --ty ballot-box --snapshot-slot <SLOT>
 
# View a ConsensusResult
ncn-cli \
  --rpc-url https://api.devnet.solana.com log \
  --ty consensus-result --snapshot-slot <SLOT>
 
# View a MetaMerkleProof
ncn-cli \
  --rpc-url https://api.devnet.solana.com log \
  --ty proof \
  --snapshot-slot <SLOT> \
  --vote-account <VOTE_ACCOUNT_PUBKEY>

Focused read commands

get-program-config

Prints the on-chain ProgramConfig singleton.

ncn-cli \
  --rpc-url https://api.devnet.solana.com \
  get-program-config

get-operator-whitelist

Prints the operator whitelist from ProgramConfig.

ncn-cli \
  --rpc-url https://api.devnet.solana.com \
  get-operator-whitelist

get-ballot

Prints the on-chain BallotBox for a snapshot slot, including tallies and operator votes.

ncn-cli \
  --rpc-url https://api.devnet.solana.com \
  get-ballot \
  --snapshot-slot <SLOT>

get-operator-vote

Prints a single operator’s vote within a ballot box.

ncn-cli \
  --rpc-url https://api.devnet.solana.com \
  get-operator-vote \
  --snapshot-slot <SLOT> \
  --operator <OPERATOR_PUBKEY>

get-consensus-result

Prints the ConsensusResult PDA for a snapshot slot.

ncn-cli \
  --rpc-url https://api.devnet.solana.com \
  get-consensus-result \
  --snapshot-slot <SLOT>

get-proof

Prints the MetaMerkleProof PDA for a vote account.

ncn-cli \
  --rpc-url https://api.devnet.solana.com \
  get-proof \
  --snapshot-slot <SLOT> \
  --vote-account <VOTE_ACCOUNT_PUBKEY>

ballot-exists

Checks whether a BallotBox exists for a snapshot slot.

ncn-cli \
  --rpc-url https://api.devnet.solana.com \
  ballot-exists \
  --snapshot-slot <SLOT>

status

Prints a combined status report: program config, ballot box, and consensus result for a snapshot slot.

ncn-cli \
  --rpc-url https://api.devnet.solana.com \
  --cluster mainnet \
  status \
  --snapshot-slot <SLOT>

Typical Operator Workflow

# 1. Wait for target slot and generate snapshot
ncn-cli \
  await-snapshot \
  --scan-interval <INTERVAL_IN_MINUTES> \
  --slot <SLOT> \
  --snapshots-dir /mnt/ledger/snapshots \
  --backup-snapshots-dir /mnt/ledger/gov-ledger-backup/snapshots \
  --backup-ledger-dir /mnt/ledger/gov-ledger-backup \
  --agave-ledger-tool-path /home/sol/.local/share/solana/install/active_release/bin/agave-ledger-tool \
  --ledger-path /mnt/ledger \
  --generate-meta-merkle
 
# 2. (Optional) Verify the snapshot looks correct
ncn-cli \
  --authority-path <PATH_TO_AUTHORITY_KEYPAIR> \
  log-meta-merkle-hash \
  --read-path <PATH_TO_META_MERKLE_FILE> \
  --is-compressed true
 
# 3. Upload to verifier service (via HTTP POST /upload)
 
# 4. Cast vote on-chain
ncn-cli \
  --payer-path <PATH_TO_PAYER_KEYPAIR> \
  --authority-path <PATH_TO_AUTHORITY_KEYPAIR> \
  --rpc-url https://api.mainnet-beta.solana.com \
  cast-vote-from-snapshot \
  --snapshot-slot <SLOT> \
  --read-path <PATH_TO_META_MERKLE_FILE> \
  --is-compressed true
 
# 5. Check consensus
ncn-cli \
  --rpc-url <RPC_URL> log \
  --ty ballot-box --snapshot-slot <SLOT>
 
# 6. Finalize once consensus is reached (permissionless; --authority-path is not used)
ncn-cli \
  --payer-path <PATH_TO_PAYER_KEYPAIR> \
  --rpc-url <RPC_URL> \
  finalize-ballot --snapshot-slot <SLOT>