docs mvp

docs/command-reference/index.md

@@ -0,0 +1,45 @@
+# Command Reference
+
+Complete reference for command-line tools and operations in the Zenith ecosystem.
+
+## Available Commands
+
+- [zenithd](zenithd.md) - Main blockchain node commands
+- [urbit](urbit.md) - Urbit-related operations
+
+## Quick Reference
+
+### Common zenithd Commands
+```bash
+# Start node
+zenithd start
+
+# Query participants  
+zenithd query onboarding participants
+
+# Process attestations
+zenithd process-participants <input.json> <output.json>
+```
+
+### Development Commands
+```bash
+# Build and install
+make install
+
+# Initialize testnet
+./scripts/init.sh
+
+# Generate protobuf
+make proto-gen
+```
+
+### Deployment Commands  
+```bash
+# Deploy with Ansible
+ansible-playbook stage0-site.yml -e "mode=start"
+
+# Using laconic-so
+laconic-so deployment --dir deployment start
+```
+
+For detailed command documentation, see the individual reference pages.

docs/command-reference/urbit.md

@@ -0,0 +1,401 @@
+# Urbit Commands
+
+Command reference for Urbit operations relevant to Zenith network participation, including ship management, desk installation, and network configuration.
+
+!!! info "Official Urbit Documentation"
+    For comprehensive Urbit command reference, see the [official Urbit documentation](https://urbit.org/using/os/dojo). This page focuses on Zenith-specific usage patterns.
+
+## Installation and Setup
+
+### Urbit Binary Installation
+```bash
+# Linux installation
+curl -L https://urbit.org/install-linux | bash
+
+# macOS installation  
+curl -L https://urbit.org/install-macos | bash
+
+# Verify installation
+./urbit --version
+```
+
+### Ship Boot and Management
+```bash
+# Boot new ship with keyfile
+./urbit -w <ship-name> -k <keyfile>
+
+# Boot existing ship
+./urbit <pier-directory>
+
+# Boot with specific port
+./urbit -p 8080 <pier-directory>
+
+# Boot in daemon mode (background)
+./urbit -d <pier-directory>
+```
+
+## Zenith-Specific Configuration
+
+### Zenith Desk Installation
+```bash
+# Inside Urbit dojo (ship command line)
+# Install zenith desk (commands may vary based on current implementation)
+|install ~zod %zenith
+
+# Mount desk for development
+|mount %zenith
+
+# Sync desk updates  
+|sync %zenith
+```
+
+### Network Configuration
+```bash
+# Configure connection to Zenith network
+# (Specific configuration commands to be documented)
+
+# Set network endpoints
+# (Configuration details to be documented)
+```
+
+## Ship Management Commands
+
+### Inside Urbit Dojo
+The Urbit dojo is the command-line interface within your ship. Access it by running your ship and using the prompt.
+
+#### Basic Ship Operations
+```urbit
+# Check ship status
++trouble
+
+# Check network connectivity
+.^(@ud %j /=local=/bound)
+
+# List installed desks
++trouble %desk
+
+# Check pier information
++trouble %pier
+```
+
+#### Desk Management
+```urbit
+# List available desks
+|show %desks
+
+# Install desk from remote ship
+|install ~<ship> %<desk>
+
+# Update desk
+|sync %<desk>
+
+# Mount desk to Unix filesystem
+|mount %<desk>
+
+# Commit changes from Unix filesystem
+|commit %<desk>
+```
+
+#### Network Operations
+```urbit
+# Check network connections
+.^(path %j /=local=/bound)
+
+# Reset network connection
+|reset
+
+# Clear ship cache
+|reset %networking
+```
+
+### Ship Maintenance
+```urbit
+# Check ship health
++trouble
+
+# Pack ship (optimize storage)
+|pack
+
+# Backup ship state
+# (Performed at Unix level, not in dojo)
+
+# Update ship runtime
+|ota ~zod %kids
+```
+
+## Zenith Integration Commands
+
+!!! warning "Development Status"
+    Zenith-specific Urbit commands are under development. Check the [Zenith desk repository](https://github.com/Zenith-Foundation/zenith-desk) for current command reference.
+
+### Transaction Submission
+```urbit
+# Submit transaction to star (conceptual)
+:zenith|submit-tx <transaction-data>
+
+# Check transaction status
+:zenith|tx-status <tx-id>
+```
+
+### Network Participation
+```urbit
+# Check Zenith network status
+:zenith|network-status
+
+# Configure star connection
+:zenith|set-star ~<star-ship>
+
+# View participation status
+:zenith|my-status
+```
+
+### Application Interaction
+```urbit
+# List Zenith applications
+:zenith|list-apps
+
+# Launch Zenith application
+:zenith|launch <app-name>
+
+# Check application status
+:zenith|app-status <app-name>
+```
+
+## Development Commands
+
+### Desk Development
+```urbit
+# Create new desk
+|new-desk %my-desk
+
+# Copy existing desk  
+|new-desk %my-desk our %base
+
+# Publish desk changes
+|public %my-desk
+
+# Set desk permissions
+|perms %my-desk [%read %self]
+```
+
+### Testing and Debugging
+```urbit
+# Test desk functionality
+:test %my-desk
+
+# Debug desk issues
++trouble %desk %my-desk
+
+# View desk files
++ls %/my-desk
+```
+
+## Administrative Operations
+
+### Ship Security
+```urbit
+# Change ship password
+|pass <new-password>
+
+# Generate new authentication code
+|code
+
+# List active sessions
++sessions
+
+# Revoke session
++revoke <session-id>
+```
+
+### System Configuration
+```urbit
+# Set ship timezone
+|timezone 'US/Pacific'
+
+# Configure HTTP settings
+|http-server %start
+
+# Set CORS permissions
+|cors-approve '<domain>'
+```
+
+### Backup and Recovery
+```bash
+# Backup ship at Unix level (ship must be stopped)
+tar -czf ship-backup-$(date +%Y%m%d).tar.gz <pier-directory>
+
+# Restore ship from backup
+tar -xzf ship-backup-<date>.tar.gz
+
+# Boot restored ship
+./urbit <restored-pier-directory>
+```
+
+## Network Integration
+
+### Star-Planet Communication
+```urbit
+# Check sponsorship status
+.^(unit ship %j /=sponsor=/our)
+
+# Request sponsorship from star
+# (Typically handled through Urbit Bridge)
+
+# Configure network routing
+# (Usually automatic, but can be debugged)
+```
+
+### Galaxy-Star Communication
+```urbit
+# Check galaxy connection
+.^(unit ship %j /=galaxy=/our)
+
+# Verify routing to galaxy
++ping ~<galaxy>
+
+# Check network routes
+.^(set ship %j /=peers=)
+```
+
+## Monitoring and Diagnostics
+
+### Performance Monitoring
+```urbit
+# Check ship memory usage
++heap
+
+# Monitor network activity
++verb %j
+
+# Check event log
++vats
+
+# Performance statistics
++mass
+```
+
+### Network Diagnostics
+```urbit
+# Test connectivity to specific ship
++ping ~<target-ship>
+
+# Check NAT configuration
+.^(@p %j /=local=/nat)
+
+# Network trace information
++verb %ames
+```
+
+### Log Analysis
+```bash
+# View ship logs (Unix level)
+tail -f <pier-directory>/.urb/log
+
+# Filter for specific events
+grep "zenith" <pier-directory>/.urb/log
+
+# Analyze network events
+grep "ames" <pier-directory>/.urb/log
+```
+
+## Troubleshooting
+
+### Common Issues
+
+#### Ship Boot Problems
+```urbit
+# Reset ship networking
+|reset %networking
+
+# Clear caches
+|meld
+
+# Rebuild from checkpoint
+|pack
+```
+
+#### Network Connectivity
+```urbit
+# Test basic connectivity
++ping ~zod
+
+# Reset network stack
+|reset
+
+# Check firewall and port configuration
+# (Performed at Unix level)
+```
+
+#### Desk Installation Issues
+```urbit
+# Clear desk cache
+|reset %clay
+
+# Reinstall desk
+|nuke %<desk>
+|install ~<source> %<desk>
+```
+
+### Performance Issues
+```urbit
+# Optimize ship storage
+|pack
+
+# Clear unnecessary data
+|meld
+
+# Monitor resource usage
++mass
+```
+
+## Integration Examples
+
+### Zenith Network Participation
+```bash
+# 1. Boot ship with proper configuration
+./urbit -p 8080 my-ship
+
+# 2. Install zenith desk (in dojo)
+|install ~zod %zenith
+
+# 3. Configure network connection
+:zenith|configure <network-settings>
+
+# 4. Submit attestation (conceptual)
+:zenith|attest <attestation-data>
+```
+
+### Development Workflow
+```bash
+# 1. Mount desk for development
+|mount %zenith
+
+# 2. Edit files in Unix
+nano <pier>/zenith/<file>
+
+# 3. Commit changes
+|commit %zenith
+
+# 4. Test functionality
+:test %zenith
+```
+
+## Resources
+
+### Official Documentation
+- **Urbit Documentation**: [urbit.org/using](https://urbit.org/using)
+- **Dojo Reference**: [urbit.org/using/os/dojo](https://urbit.org/using/os/dojo)
+- **Developer Guide**: [urbit.org/guides/core/hoon-school](https://urbit.org/guides/core/hoon-school)
+
+### Zenith-Specific Resources
+- **Zenith Desk**: [GitHub Repository](https://github.com/Zenith-Foundation/zenith-desk)
+- **Integration Guide**: [App Development](../documentation/app-development.md)
+- **Network Participation**: [Roles & Responsibilities](../overview/roles-responsibilities.md)
+
+### Community Support
+- **Urbit Community**: Official support channels and forums
+- **Zenith Developers**: Zenith-specific development support
+- **Stack Overflow**: Programming questions and solutions
+
+!!! note "Evolving Commands"
+    Zenith-specific Urbit commands are actively being developed. Check the latest desk releases and documentation for updated command reference and usage patterns.

docs/command-reference/zenithd.md

@@ -0,0 +1,407 @@
+# 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).