# aldabra

Rust-native Cardano lite wallet with an MCP-server interface — built
for LLM-first usage (send, receive, mint, Plutus interaction).

> **Status: Phase 1 scaffold (2026-05-04).** Compiles, structure in
> place, real wallet primitives still landing. See `ROADMAP.md`.

## Why

The existing Cardano MCP servers are either read-only doc gateways
([Jimmyh-world/Cardano_MCP](https://github.com/Jimmyh-world/Cardano_MCP))
or built on Blockfrost ([web3-mcp](https://github.com/strangelove-ventures/web3-mcp))
which is a centralized API we deliberately don't depend on. Sulkta
runs its own Koios + Ogmios endpoints on Rackham; we want a wallet
that talks directly to those.

Also: it's the first Sulkta Rust project — useful as a workout for
crafting-table's Rust toolchain (per `Sulkta-Coop/lucy-infra`
`spec-crafting-table.md`).

## Architecture

Three crates in a Cargo workspace:

| Crate | Responsibility |
|---|---|
| `aldabra-core` | Pure crypto + types. Mnemonic → root key (CIP-3), root → payment + stake key (CIP-1852), address construction, signing. **No I/O, no network.** This is the security boundary. |
| `aldabra-chain` | Pluggable backends for chain queries. `ChainBackend` trait, with Koios as the phase-1 implementation. Ogmios + submission paths in phase 2. |
| `aldabra-mcp` | Binary. MCP server speaking stdio. Glues core + chain together, exposes tools to the LLM client. |

```
            ┌─────────────────────────────┐
LLM client  │       aldabra-mcp (bin)      │  stdio
─────────►  │   tool handlers, lifecycle  │  ────►
            └──────────┬──────────────────┘
                       │
              ┌────────┴────────┐
              ▼                 ▼
       ┌──────────────┐  ┌──────────────┐
       │ aldabra-core  │  │ aldabra-chain │
       │ keys, sign   │  │ Koios/Ogmios │
       └──────────────┘  └──────────────┘
```

## MCP tools (target)

Phase 1:
- `wallet.address` — derived base address at account 0, index 0
- `wallet.balance` — ADA + native asset balance at the wallet's address
- `wallet.utxos`   — list UTXOs

Phase 2:
- `wallet.send`   — build, sign, submit a payment (ADA or native)
- `wallet.tx_status` — poll a submitted tx hash

Phase 3:
- `wallet.mint`   — mint a CIP-25 / CIP-68 native asset
- `wallet.policy.create` — generate a policy script (timelock, multisig)

Phase 4:
- `wallet.script.attach`   — attach an inline datum + reference script
- `wallet.script.spend`    — spend a Plutus-locked UTXO with redeemer
- `wallet.stake.delegate`  — delegate to a pool

## Build

```bash
# Local (requires rustc 1.75+)
cargo build --release

# Through crafting-table (preferred — validates the toolchain there)
crafting-table build aldabra
```

## Run

```bash
# Direct invocation (smoke test only — does nothing useful in phase 1)
./target/release/aldabra

# As an MCP server registered with Claude Code:
# add to ~/.claude.json:
#   "aldabra": {
#     "command": "/path/to/aldabra",
#     "env": {
#       "ALDABRA_DATA": "/mnt/cache/appdata/aldabra"
#     }
#   }
```

## Security model

- **Mnemonic source:** interactive bootstrap on first run, paste once, encrypted at
  rest with [age](https://github.com/FiloSottile/age). Never written to disk in
  plaintext.
- **Derived keys:** in-memory only, `ZeroizeOnDrop` on every container.
- **Network exposure:** stdio MCP transport — never opens a TCP socket.
  Only the spawning client process can reach it.
- **Multi-network:** mainnet by default, but `--network preview` /
  `--network preprod` for testing without real ADA.

## See also

- `ROADMAP.md` — phased buildout
- `docs/architecture.md` — deeper design notes
- [txpipe/pallas](https://github.com/txpipe/pallas) — the Rust Cardano
  building blocks we depend on
- [Emurgo/cardano-serialization-lib](https://github.com/Emurgo/cardano-serialization-lib) —
  reference TX builder if pallas-txbuilder doesn't cover something
- [modelcontextprotocol/rust-sdk](https://github.com/modelcontextprotocol/rust-sdk) —
  rmcp, the Rust MCP server SDK we use