aether

# Aether (AETH)

Aether is a sovereign, staking-free proof-of-work blockchain built on Cosmos SDK and CometBFT. Validators are selected by real, tracked **native mining work** — not bonded capital — and account transactions require **ML-DSA-44 (Dilithium2 / FIPS 204)** signatures from genesis.

**Technical design:** see the full [Technical Whitepaper](docs/WHITEPAPER.md).

> **Warning: no independent security audit.** This is early-stage software. Do not use it with funds you cannot afford to lose. See [Known Issues and Technical Debt](../../wiki/Known-Issues-and-Technical-Debt) and the security review materials in this repo for an honest account of what has and has not been independently reviewed.

Design history, live-verification notes, and locked architectural decisions are tracked in the [project wiki](../../wiki).

## AI agents: start here

Agents use the same accounts and transactions as people: there is no AI-only lane. **Testnet only: use disposable keys, never anything of value.**

```bash
go install github.com/whoyoujoshin/aether/cmd/agentmcp@latest   # Go 1.25+
agentmcp init   # new key, testnet funds, and the MCP config for Claude / Cursor / any MCP client
```

No Go? `agentmcp` is in every platform's archive on the [releases page](../../releases). `@latest` is the newest tested release; `@main` has unreleased changes.

That gives the agent a spend-capped wallet as MCP tools: balance, send, invoice and wait-for-payment, paying for HTTP 402 APIs, and the service directory (full list and guarantees in [AI agent wallet](#ai-agent-wallet-mcp)).

| | |
|--|--|
| Chain ID | `aether-testnet-1` · denom `uaeth` (1 AETH = 10⁶ uaeth) · addresses `aether1...` |
| RPC / gRPC | `https://rpc.157-245-252-221.sslip.io` / `grpc.157-245-252-221.sslip.io:443` (TLS; plain `157.245.252.221:26657`/`:9090` still work) |
| Faucet | `curl -X POST https://faucet.157-245-252-221.sslip.io/request -H 'Content-Type: application/json' -d '{"address":"aether1..."}'` |
| Explorer | `https://explorer.157-245-252-221.sslip.io/agents` · balance: `/api/address?addr=aether1...` · this card as JSON: `/api/agents` |

Let an agent spend from your account with a chain-enforced cap instead of holding funds: [agent permissions](#on-chain-agent-permissions-xauthz-xfeegrant). Sell to agents: [paid APIs](#paid-apis-x402). See one agent pay another for a tool call, live, in [docs/AGENT_DEMO.md](docs/AGENT_DEMO.md). A prompt to check an agent is set up (the address is a test counterparty run by the project):

> Using the aether-wallet tools: get your address and balance. If you have under 1 AETH, call request_testnet_funds and wait until your balance shows it. Then send 0.001 AETH to aether1cdugwhxk9cktjsemm6yjrd6xtfsq9wkjvnef03ml4u6ltuv7edcs0eyjds with idempotencyKey "aether-smoke-1", wait for the transaction to confirm, and report its hash and https://explorer.157-245-252-221.sslip.io/tx/<hash>.

## Current status

| Area | Status |
|------|--------|
| Core PoW (Scrypt), difficulty retarget, height-based reward decay and tail emission | Built, tested, live-verified |
| Epoch Top-K validator selection (no staking module) | Built, tested, live-verified |
| Validator bonding, equivocation slashing, escrow release | Built, tested, live-verified |
| Downtime / liveness detection (distinct from equivocation) | Built, tested, live-verified |
| Ancestor validation | Built, tested, live-verified |
| AuxPoW (LTC/DOGE-family merged mining) | Built, tested, live-verified |
| Post-quantum account signatures (ML-DSA-44), mandatory from genesis | Built, tested, live-verified |
| Governance (deposit, tenure-weighted voting, treasury execution) | Built, tested, live-verified |
| `uaeth` / `aether` bech32 prefix | Built, migrated, live-verified |
| Wallet library and CLI | Built, tested, live-verified |
| Testnet faucet and block explorer | Built, live, deployed with seed node |
| **Public testnet** | **Live** — see below |
| Account abstraction, native IBC | Not built |
| Independent professional security audit | Not yet performed |

See [Known Issues and Technical Debt](../../wiki/Known-Issues-and-Technical-Debt) and [Roadmap](../../wiki/Roadmap).

## Why staking-free, and why post-quantum?

Aether has no `x/staking` module. The active validator set is the Top-K miners by **epoch native work**. AuxPoW can earn rewards and retarget difficulty but does **not** count toward Top-K standing.

Every account transaction must use ML-DSA-44 from genesis (no classical fallback), enforced by `PostQuantumDecorator`. CometBFT consensus keys remain ed25519. Details: [docs/WHITEPAPER.md](docs/WHITEPAPER.md) and the wiki decision records.

## Public testnet

| | |
|--|--|
| **Chain ID** | `aether-testnet-1` |
| **Seed** | `dfa6aae4b7bfd5b0eb1e22fabbae3e83a475b938@157.245.252.221:26656` |
| **RPC** | `https://rpc.157-245-252-221.sslip.io` (plain `http://157.245.252.221:26657` still works) |
| **gRPC** | `grpc.157-245-252-221.sslip.io:443`, TLS (plain `157.245.252.221:9090` still works) |
| **Faucet** | `https://faucet.157-245-252-221.sslip.io/request` — `POST` JSON `{"address":"aether1..."}` |
| **Explorer** | `https://explorer.157-245-252-221.sslip.io` |
| **Genesis** | [`testnet/genesis.json`](testnet/genesis.json) |

### Connecting a node

```bash
aetherd init <your-moniker> --chain-id aether-testnet-1
```

Replace `config/genesis.json` with [`testnet/genesis.json`](testnet/genesis.json), set in `config/config.toml`:

```toml
seeds = "dfa6aae4b7bfd5b0eb1e22fabbae3e83a475b938@157.245.252.221:26656"
```

Then:

```bash
aetherd start
```

To expose RPC/gRPC publicly (defaults bind localhost only), before start:

```toml
# config/config.toml, [rpc]
laddr = "tcp://0.0.0.0:26657"
```

```toml
# config/app.toml, [grpc]
address = "0.0.0.0:9090"
```

This is an early-stage public network — not audited, subject to resets. Use only disposable test funds.

**Historical note:** for roughly the first ~10 hours, `timeout_commit` remained near CometBFT’s ~5s default instead of the intended ~60s, so height grew faster than wall-clock age (~7,000 blocks in that window). Fixed live; not a consensus/security failure — disclosed for operators interpreting height vs age.

## Quick start (single-node devnet)

```bash
# Build
go build ./...
go install -mod=mod ./cmd/aetherd

# Initialize (once, or after full reset)
aetherd init mynode --chain-id aether-testnet-1

# Start (foreground)
aetherd start
```

Second terminal:

```bash
aetherd query pow difficulty
aetherd query pow block-reward
aetherd query pow active-validators
aetherd query pow current-epoch
aetherd query governance params
aetherd query governance proposals

# ML-DSA-44 key (no special flags)
aetherd keys add mywallet --keyring-backend test

# Mine a valid native PoW nonce against live state
go run ./cmd/powminer --miner <your-bech32-address>
# then run the aetherd tx pow submit command it prints
```

**Keys:** each account is one ML-DSA-44 keypair — no HD multi-account derivation from a mnemonic.  
**Addresses / denom:** `aether1...` bech32; `uaeth` base unit (1 aeth = 1_000_000 uaeth).

Binary home defaults to `~/.aether`.

## Wallet

```bash
go run ./cmd/wallet create mywallet --keyring-backend test
go run ./cmd/wallet balance mywallet --grpc localhost:9090
go run ./cmd/wallet send mywallet <recipient> 1000000uaeth --keyring-backend test --grpc localhost:9090 --chain-id aether-testnet-1
```

`balance` and `send` accept a bech32 address or keyring account name.

## Faucet

```bash
go run ./cmd/faucet --from faucet --chain-id aether-testnet-1 --keyring-backend test
```

```bash
curl -X POST http://localhost:8080/request \
  -H 'Content-Type: application/json' \
  -d '{"address":"aether1..."}'
```

Requires a funded key named `faucet` in the configured keyring.

## Block explorer

```bash
go run ./cmd/explorer --grpc localhost:9090 --rpc http://localhost:26657 --port 8081
```

Open `http://localhost:8081`.

To redeploy the live explorer from `main`, run `bash scripts/deploy-explorer.sh` as root on the server that hosts it. It builds while the old version keeps serving, keeps backups, restarts `aether-explorer` and rolls back if the new one doesn't answer.

## AI agent wallet (MCP)

An MCP server exposing wallet operations as tool calls, so an AI agent can pay and get paid directly instead of only a human clicking through a UI.

**Quick start (testnet):**

```bash
go install github.com/whoyoujoshin/aether/cmd/agentmcp@latest   # or, in a clone: go install ./cmd/agentmcp
agentmcp init
```

`init` creates the agent's account (showing its recovery phrase once), asks the testnet faucet for funds, waits until they arrive and prints the exact `claude mcp add ...` command and the JSON config block for Claude Desktop and other MCP clients. Run it again to reuse the same account. `--faucet <url>` points it at another faucet, `--no-faucet` skips funding; it takes the same `--grpc`, `--rpc`, `--chain-id` and `--keyring-dir` flags as the server (on `aether-testnet-1`, `--grpc` and `--rpc` default to the public node). Once running, the agent can top itself up with the `request_testnet_funds` tool (testnet only; `FAUCET_RATE_LIMITED` means wait).

**Claude Desktop without Go:** download `aether-wallet.mcpb` from the [latest release](../../releases) and open it. Claude Desktop asks for the spending limits and a keyring folder; the agent creates its account on first use and funds it with `request_testnet_funds`. The same bundle runs on Windows, macOS (Intel and Apple Silicon) and Linux. Its MCP Registry name is `io.github.whoyoujoshin/aether-wallet`.

To run the server by hand:

```bash
go run ./cmd/agentmcp --grpc localhost:9090 --rpc http://localhost:26657 --chain-id aether-testnet-1 \
    --per-tx-limit 1000000 --daily-limit 5000000 \
    [--granter <your-address> [--fee-granter <your-address>]]
```

Built for how agents actually fail:

- **No double payments on retry.** `send_aeth` requires an `idempotencyKey`; a retry with the same key re-sends t