# zenithd Commands

Complete command reference for the zenithd blockchain node, including installation, configuration, querying, and network management.


## Installation and Setup

### Building from Source
```bash
# 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
```bash
# Build without installing
make build

# Build for Linux
make build-linux

# Check dependencies
make go.sum
```

## Node Initialization and Management

### Initialize Node
```bash
# 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
```bash
# 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
```bash
# 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:

```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# Get detailed status
zenithd status --output json | jq

# Check consensus state
zenithd query consensus-state

# Monitor mempool
zenithd query mempool
```

## Examples

### Complete Node Setup
```bash
# 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
```bash
# 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](../api/zenithd.md).