8.9 KiB
8.9 KiB
zenithd Commands
Complete command reference for the zenithd blockchain node, including installation, configuration, querying, and network management.
Installation and Setup
Building from Source
# Clone repository
git clone git@github.com:Zenith-Foundation/zenithd.git
cd zenithd
# Install the zenithd binary
make install
# Verify installation
zenithd version
Development Build
# Build without installing
make build
# Build for Linux
make build-linux
# Check dependencies
make go.sum
Node Initialization and Management
Initialize Node
# Initialize and start a local testnet
./scripts/init.sh
# Start fresh (removes all data)
./scripts/init.sh clean
# Initialize without starting (for configuration)
./scripts/init.sh --bare
Start Node
# Start with default configuration
zenithd start
# Start with Azimuth watcher endpoint
zenithd start --azimuth-watcher-endpoint <endpoint>
# Start in galaxy mode with Janus server
zenithd start --janus-node-mode galaxy --janus-config /path/to/janus-config.yaml
# Start in star mode with Janus server
zenithd start --janus-node-mode star --janus-config /path/to/janus-config.yaml
# Configure server address
zenithd start --zenith-server-address localhost:9473
Node Status
# Check node status
zenithd status
# Check sync status (with jq formatting)
zenithd status | jq .sync_info
# Get node ID and address
zenithd cometbft show-node-id
Participant Management
Process Participants
Verify participant attestations during stage transitions:
# Verify all participants' ownership claims
zenithd process-participants <chain-state-file> <verified-output-file>
# Example
zenithd process-participants ./chain-state.json ./verified-participants.json
This command:
- Checks cryptographic signatures from both Ethereum and Cosmos accounts
- Verifies Azimuth point ownership through the Azimuth watcher
- Outputs only verified participants for network initialization
Genesis Management
# Export chain state
zenithd export | jq > chain-state.json
# Add verified participants to genesis
zenithd genesis add-zenith-genesis-accounts <verified-participants-json> <coin>[,<coin>...]
# Example
zenithd genesis add-zenith-genesis-accounts ./verified-participants.json '100000$Z'
# Populate sponsorship index from verified participants
zenithd genesis populate-sponsorship \
--participants-file ./verified-participants.json \
--eth-block-hash <eth-block-hash> \
--azimuth-watcher-endpoint <endpoint>
# Create treasury allocations from config
zenithd genesis create-treasury --config /path/to/treasury-config.toml
Query Commands
Onboarding Module
# List all participants
zenithd query onboarding participants
# Get specific participant by zenith address
zenithd query onboarding get-participant-by-address <address>
# Get participants by point
zenithd query onboarding get-participants-by-point <point>
# Get module parameters
zenithd query onboarding params
Scry Oracle Module
# Get complete binding information for a path
zenithd query scryoracle get-binding-by-path <path>
# Get path to hash mappings for a path prefix
zenithd query scryoracle get-bindings-by-path-prefix <path-prefix>
# Get path to hash mappings added at a block number
zenithd query scryoracle get-bindings-by-block-number <block-number> <path-prefix>
# Get path to hash mappings added in a block range
zenithd query scryoracle get-bindings-in-block-range <from-block> <to-block> <path-prefix>
Zenith Module
# Get Zenith address for a given point / Urbit id
zenithd query zenith get-address-by-point <point>
# Get balances for Zenith address of a given point / Urbit id
zenithd query zenith get-balances-by-point <point>
# Get sponsorship details for a given point / Urbit id
zenithd query zenith get-sponsorship-by-point <point>
# Get the latest ETH block height as seen by Zenith
zenithd query zenith get-eth-height
# Get module parameters
zenithd query zenith params
Treasury Module
# Get treasury distribution (optionally filtered by category)
zenithd query immutabletreasury distribution
# Get allocations for a specific address (optionally filtered by point)
zenithd query immutabletreasury allocations-by-address <address> [point]
# Get accrual state for a specific address and point
zenithd query immutabletreasury accrual-state <address> <point>
# Get all accrual states for an address
zenithd query immutabletreasury accrual-states <address>
# Get claim state for a specific address
zenithd query immutabletreasury claim-state <address>
# Get claimable amount for a specific address
zenithd query immutabletreasury claimable-amount <address>
# Get balance yet to be accrued for a specific address
zenithd query immutabletreasury balance-yet-to-be-accrued <address>
# Get balance yet to be unlocked for a specific address
zenithd query immutabletreasury balance-yet-to-be-unlocked <address>
# Get current block rewards state
zenithd query immutabletreasury block-rewards-state
# Get module parameters
zenithd query immutabletreasury params
Standard Cosmos SDK Queries
# Account information
zenithd query account <address>
# Token balances
zenithd query bank balances <address>
# Validator information
zenithd query staking validators
# Delegation information
zenithd query staking delegations <delegator-address>
# Governance proposals
zenithd query gov proposals
Transaction Commands
Standard Transactions
# Send tokens
zenithd tx bank send <from-key-name> <to-address> <amount> --fees <fee-amount>
# Delegate tokens
zenithd tx staking delegate <validator-address> <amount> --from <key-name>
# Submit governance proposal
zenithd tx gov submit-proposal <proposal-json> --from <key-name>
# Vote on proposal
zenithd tx gov vote <proposal-id> yes --from <key-name>
Key Management
Create and Manage Keys
# Add new key
zenithd keys add <key-name>
# List keys
zenithd keys list
# Show key address
zenithd keys show <key-name> --address
# Export key
zenithd keys export <key-name>
# Import key
zenithd keys import <key-name> <key-file>
Configuration
Environment Variables
# External data sources
export AZIMUTH_WATCHER_ENDPOINT=<azimuth-watcher-endpoint>
# Chain configuration
export CHAIN_ID="zenith-testnet-stage0"
export ONBOARDING_ENABLED=true
export ENABLE_STALLED_ETH_HEIGHT_SLASHING=true
# Janus configuration
export JANUS_NODE_MODE=galaxy # or "star" or ""
export JANUS_CONFIG=/path/to/janus-config.yaml
Configuration Files
# Initialize configuration
zenithd init <node-name> --chain-id <chain-id>
# Edit configuration
nano ~/.zenithd/config/config.toml
nano ~/.zenithd/config/app.toml
Development Commands
Protobuf Development
# Generate all protobuf code
make proto-gen
# Full protobuf workflow (format, lint, generate)
make proto-all
# Format protobuf files
make proto-format
# Lint protobuf files
make proto-lint
# Generate Swagger documentation
make proto-swagger-gen
Testing
# Run all tests
go test ./...
# Run tests with verbose output
go test -v ./...
# Run specific test package
go test ./x/onboarding
# Run with race detector
go test -race ./...
Network Operations
Validator Operations
# Create validator
zenithd tx staking create-validator \
--amount=<stake-amount> \
--pubkey=$(zenithd cometbft show-validator) \
--moniker="<validator-name>" \
--chain-id=<chain-id> \
--from=<key-name>
# Edit validator
zenithd tx staking edit-validator \
--moniker="<new-name>" \
--website="<website>" \
--from=<key-name>
Node Connection
# Add persistent peers
zenithd config set config.p2p.persistent_peers "<peer1>,<peer2>"
# Connect to specific node
zenithd config set config.p2p.seeds "<seed-node>"
Troubleshooting
Common Issues
# Reset node data (dangerous!)
zenithd unsafe-reset-all
# Check node logs
journalctl -u zenithd -f
# Validate genesis file
zenithd validate-genesis
# Check configuration
zenithd config validate
Debug Information
# Get detailed status
zenithd status --output json | jq
# Check consensus state
zenithd query consensus-state
# Monitor mempool
zenithd query mempool
Examples
Complete Node Setup
# 1. Install
make install
# 2. Initialize
zenithd init mynode --chain-id zenith-testnet
# 3. Configure
export AZIMUTH_WATCHER_ENDPOINT="https://azimuth.dev.vdb.to/graphql"
# 4. Start
zenithd start
Query Participant Information
# Check if address is onboarded
zenithd query onboarding get-participant-by-address zenith1abc...
# Get their address by point
zenithd query zenith get-address-by-point 123
# Get their balances by point
zenithd query zenith get-balances-by-point 123
# Check their token balance by address
zenithd query bank balances zenith1abc...
HTTP RPC/API Queries
For HTTP/REST API queries and the Janus Server API, see the zenithd API Reference.