407 lines
8.9 KiB
Markdown
407 lines
8.9 KiB
Markdown
# 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). |