# Lithium CLI
CLI miner for Lithium (LI) proof-of-work tokens on the Bostrom blockchain (Cosmos SDK). Interacts with 5 modular CosmWasm contracts: litium-core, litium-mine, litium-stake, litium-refer, litium-wrap.
## Build & Test
```bash
cargo build --release # binary: target/release/lithium
cargo test # all tests (uses httpmock for HTTP mocking)
cargo test rpc::tests # RPC module only
```
IMPORTANT: Always run `cargo test` after modifying `rpc.rs` or `contract_types.rs` — there are 16 tests covering LCD response parsing, contract queries, and TX commit logic.
## Architecture
```
src/main.rs – CLI (clap derive), command dispatch, all handlers
src/rpc.rs – RpcClient: LCD/RPC queries, TX signing, broadcast, polling
src/contract_types.rs – Serde types mirroring on-chain CosmWasm JSON schemas
src/deployments.rs – Mainnet contract addresses (embedded TOML via OnceLock)
deployments/ – TOML files with contract addresses per network
```
This is a single-binary, ~2000-line codebase. Keep it flat — do not introduce new modules or crates without good reason.
## Non-Obvious Conventions
- `String` for all Uint128 fields in contract types (Cosmos JSON convention, not Rust integers)
- Timestamp offset: subtract 5 seconds before submitting proofs to avoid "timestamp in future" chain rejection
- Gas limit for mine TX is 2,000,000 (other TXs use 600K–1.6M) — do not lower mine gas
- TX broadcast uses SYNC mode, then polls LCD every 800ms for up to 30 seconds for commit confirmation
- Sequence number is cached locally and auto-retried once on mismatch — do not add additional retry logic
- Mining `--json` output is newline-delimited JSON events (session_start, proof_found, proof_submitted) — no progress bars
## Gotchas
- Bostrom uses zero-fee transactions (default fee: 0 boot). Do not add minimum fee checks.
- Contract addresses are embedded at compile time via `include_str!("../deployments/bostrom-mainnet.toml")`. After changing addresses, you must rebuild.
- The wallet keystore lives at `~/.uhash/wallet.json` and is managed by the `uhash-cli` crate — do not reimplement key management.
- All serde enums use `#[serde(rename_all = "snake_case")]` to match CosmWasm JSON. Missing this breaks contract queries silently.
## Bostrom MCP Server
Use `bostrom-mcp` (v0.5.0) for querying on-chain contract state and verifying lithium CLI behavior. 89 tools: 45 read + 44 write.
Key lithium tools for this project:
- `li_mine_state` — full mine state: config, seed, difficulty, stats, epoch, proofs, emission
- `li_mine_config` — difficulty, base reward, period duration, target proofs
- `li_difficulty` — current difficulty, min profitable, window proof count
- `li_emission` — emission breakdown: mining, staking, referral
- `li_reward_estimate` — estimate LI reward for a given difficulty
- `li_mine_stats` / `li_miner_stats` — aggregate and per-miner stats
- `li_stake_info` / `li_total_staked` — staking state
- `li_referral_info` / `li_referrer_of` — referral data
- `li_core_config` / `li_burn_stats` / `li_total_minted` — token state
- `li_verify_proof` — dry-run verify a proof without submitting
- `li_recent_proofs` — recent proof submission transactions
- `economy_balances` — all token balances for an address
When debugging contract queries or verifying CLI output, cross-check against the MCP tools above rather than guessing at expected on-chain state.
## Design References
Well-architected mining CLIs and Rust CLI tools to study for patterns:
- **[ore-cli](https://github.com/regolith-labs/ore-cli)** (~1.5k stars) — Closest analogue: Rust PoW mining CLI for Solana. Clean `args.rs` + `command/` + `send/` + `utils/` layout. Study for: subcommand structure, TX retry, priority fees, mining loop design.
- **[drillx](https://github.com/regolith-labs/drillx)** (~110 stars) — Standalone PoW hash library (Equix-based). Shows how to separate the hash algorithm into its own crate for testability.
- **[xmrig](https://github.com/xmrig/xmrig)** (~9.8k stars) — Production multi-algo CPU/GPU miner (C++). Reference for: thread pool management, hashrate reporting, config hierarchies, pool failover.
- **[mithril](https://github.com/Ragnaroek/mithril)** (~250 stars) — Pure Rust Monero miner. Study for: `worker/worker_pool.rs` pattern, metrics module, multi-armed bandit auto-tuning for hardware params, TOML config.
- **[ripgrep](https://github.com/BurntSushi/ripgrep)** (~60k stars) — Gold standard Rust CLI architecture. Workspace with facade crate coordinating sub-crates. Study for: parallel execution, streaming I/O, error handling.
- **[starship](https://github.com/starship/starship)** (~54k stars) — Modular Rust CLI using clap + serde + TOML. Study for: trait-based module registry pattern (useful if adding multi-chain support).