lithium-cli 0.1.4

# lithium-cli

CLI miner and operations tool for [Litium (LI)](https://cyb.ai) on the Bostrom blockchain.

Mines LI tokens by solving UniversalHash proof-of-work challenges and submitting proofs on-chain. Also provides commands for querying contract state, managing staking, referrals, and transfers.

## Install

```bash
cargo install --git https://github.com/cyberia-to/lithium-cli.git
```

Or build from source:

```bash
git clone https://github.com/cyberia-to/lithium-cli.git
cd lithium-cli
cargo build --release
# binary at target/release/lithium
```

## Quick Start

```bash
# Create a wallet
lithium wallet new

# Check mining window status
lithium status

# Start mining (uses all CPU cores, auto difficulty)
lithium mine

# Start mining with specific settings
lithium mine --threads 4 --difficulty 12 --referrer bostrom1...
```

## Commands

### Mining

```
lithium mine [OPTIONS]
```

Continuous mining loop: generates random challenges, solves them locally using the UniversalHash algorithm, and submits valid proofs to the litium-mine contract.

| Flag | Default | Description |
|------|---------|-------------|
| `--mine-contract` | mainnet address | litium-mine contract |
| `-d, --difficulty` | `0` (contract min) | Leading zero bits |
| `-t, --threads` | all cores | CPU worker threads |
| `--batch-size` | `4096` | Hashes per batch |
| `--max-batches` | `0` (unlimited) | Max batches per challenge |
| `--max-proofs` | `0` (unlimited) | Stop after N proofs |
| `--referrer` | none | Referrer address (first proof only) |
| `--gas-limit` | `2000000` | Gas per proof TX |

### Wallet

```bash
lithium wallet new           # Create new wallet (encrypted keystore)
lithium wallet address       # Show address
lithium wallet import              # Import from mnemonic (prompted securely)
lithium wallet export        # Show mnemonic
```

### Queries

```bash
lithium status                          # Mining window status + block height
lithium stats                           # Global mining stats (proofs, miners, rewards)
lithium stats --address bostrom1...     # + per-miner stats
lithium emission                        # Emission rate breakdown
lithium burn-stats                      # Transfer burn accounting
lithium referral --address bostrom1...  # Referral info for address
lithium stake-info --address bostrom1...# Staking info for address
```

### Transactions

```bash
lithium claim-referral       # Claim referral rewards
lithium claim-staking        # Claim staking rewards
lithium claim-unbonding      # Claim matured unbonding
lithium transfer --to bostrom1... --amount 1000000
```

### Manual Proof Submission

```bash
lithium send --hash <hex> --nonce <n> --timestamp <unix> \
  --challenge <hex> --difficulty <bits>
```

## Global Options

| Flag | Default | Description |
|------|---------|-------------|
| `--rpc` | `https://rpc.bostrom.cybernode.ai` | Tendermint RPC endpoint |
| `--lcd` | `https://lcd.bostrom.cybernode.ai` | LCD/REST endpoint |
| `--chain-id` | `bostrom` | Chain ID |
| `--fee` | `0` | Fee in uboot (Bostrom supports zero-fee) |
| `--wallet` | `~/.uhash/wallet.json` | Wallet keystore path |
| `--json` | off | Machine-readable JSON output |

## JSON Output

All commands support `--json` for scripting. Mining emits newline-delimited JSON events:

```json
{"event":"session_start","miner":"bostrom1...","difficulty":12,"threads":8}
{"event":"proof_found","nonce":42,"hash":"00ab...","total_hashes":8192}
{"event":"proof_submitted","tx_hash":"A1B2...","proofs_total":1}
```

## Architecture

Single binary crate with four modules:

- **`main.rs`** -- CLI argument parsing and command dispatch
- **`rpc.rs`** -- Bostrom LCD client (queries, TX signing, broadcast)
- **`contract_types.rs`** -- Serde types for all modular litium contracts
- **`deployments.rs`** -- Mainnet contract addresses from embedded TOML

Queries and transactions are routed to the correct modular contract automatically:

| Contract | CLI Commands |
|----------|-------------|
| litium-core | `burn-stats`, `transfer` |
| litium-mine | `status`, `stats`, `emission`, `mine`, `send` |
| litium-stake | `stake-info`, `claim-staking`, `claim-unbonding` |
| litium-refer | `referral`, `claim-referral` |

Mining uses [uhash-prover](https://github.com/cyberia-to/uhash) for the UniversalHash CPU solver and [uhash-cli](https://github.com/cyberia-to/uhash) for wallet management.

## Contracts

| Contract | Role |
|----------|------|
| litium-core | CW-20 token, transfer burn accounting |
| litium-mine | Proof verification, reward calculation, difficulty adjustment, emission |
| litium-stake | LI staking, unbonding, reward distribution |
| litium-refer | Referral tracking and rewards |
| litium-wrap | CW-20 to native TokenFactory bridge |

Mainnet addresses are embedded in `deployments/bostrom-mainnet.toml` and used as CLI defaults.

## License

Apache-2.0