aldabra

Rust-native Cardano lite wallet with an MCP-server interface. Built for LLM-first usage — send/receive ADA + native assets, mint, Plutus script interaction, Conway governance, and a full Agora-on-Cardano DAO client.

Named for the Aldabra giant tortoise: long-lived, defended, slow but unstoppable.

What it does

Wallet primitives. Address derivation (CIP-1852), balance + UTXO queries, ADA + native-asset transfers, multi-sig partial signing, encrypted-at-rest mnemonic.
Minting. CIP-25 + CIP-68 native assets, custom timelock / multisig policies, unsigned-tx flows for cold signing.
Plutus V3. Spending script-locked UTXOs with redeemers, reference scripts, inline datum support.
Stake + Conway governance. Pool delegation, DRep registration
- deregistration, vote delegation, DRep vote casting on governance actions.
DAO. Agora-on-Cardano client — register multiple DAOs, view stakes, create + cosign + vote on proposals, advance state-machine, retract votes, destroy stakes.
Escrow. Two-party agreement-with-veto Plutus V3 validator with off-chain builders for the full open / deposit / agree / veto / settle / refund lifecycle.

Architecture

Cargo workspace with four crates:

Crate	Responsibility
`aldabra-core`	Pure crypto + types. Mnemonic → root key (CIP-3), root → payment + stake keys (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 default implementation.
`aldabra-dao`	Off-chain side of the Agora DAO + escrow validators. Codecs + unsigned-tx builders.
`aldabra-mcp`	Binary. MCP server speaking stdio. Wires the other crates together and exposes tools to the LLM client.

            ┌─────────────────────────────┐
LLM client  │       aldabra-mcp (bin)     │  stdio
─────────►  │   tool handlers, lifecycle  │  ────►
            └──────────┬──────────────────┘
                       │
              ┌────────┼────────┐
              ▼        ▼        ▼
       ┌──────────┐ ┌──────┐ ┌─────────┐
       │  -core   │ │-chain│ │  -dao   │
       │ keys/sig │ │ Koios│ │ Agora/  │
       │          │ │      │ │ escrow  │
       └──────────┘ └──────┘ └─────────┘

Build

# Requires rustc 1.75+
cargo build --release

For the Plutus validators (escrow) you also need Aiken:

cd aiken-escrow
aiken build       # produces plutus.json blueprint

Run

# Smoke test (does nothing useful standalone — needs an MCP client)
./target/release/aldabra

# As an MCP server registered with Claude Code, add to ~/.claude.json:
#   "aldabra": {
#     "command": "/path/to/aldabra",
#     "env": {
#       "ALDABRA_DATA": "/path/to/wallet-data-dir",
#       "ALDABRA_NETWORK": "preprod",
#       "ALDABRA_KOIOS_BASE": "https://preprod.koios.rest/api/v1"
#     }
#   }

Bootstrap a wallet on first run by setting ALDABRA_BOOTSTRAP=new or ALDABRA_BOOTSTRAP=import in env — the binary prompts for a passphrase, generates or imports a mnemonic, and writes an age-encrypted mnemonic.age to ALDABRA_DATA.

Configuration

Environment variables consumed at startup:

Var	Required	Default	Notes
`ALDABRA_DATA`	yes	—	Directory holding `mnemonic.age`. Must exist; bootstrap before first MCP run.
`ALDABRA_NETWORK`	no	`preprod`	One of `mainnet`, `preview`, `preprod`.
`ALDABRA_KOIOS_BASE`	no	public Koios for the chosen network	Override to point at a self-hosted Koios.
`ALDABRA_PASSPHRASE`	yes	—	Unlocks `mnemonic.age`. Source from a docker secret or systemd `EnvironmentFile` — never commit it.
`ALDABRA_BOOTSTRAP`	no	(unset)	Set to `new` or `import` to enter bootstrap mode on next launch.
`ALDABRA_MAX_SEND_LOVELACE`	no	mainnet 10 ADA / preprod\|preview 100 tADA	Hard cap on lovelace flowing to any non-self destination. Enforced by every tool that signs or submits; pass `force=true` per-tool to override.
`ALDABRA_SAFE_READS_ROOT`	no	`$ALDABRA_DATA/scripts/`	Sandbox dir for the `reference_script_path` / `policy_cbor_path` tool args. Files outside this dir (canonical) are refused. Created with 0o700 at startup if missing.

MCP tools

The server exposes ~40 tools across four prefixes. A summary:

wallet_* — read (address/balance/utxos/network/stake_address), send (with optional inline datum for script locks), mint, Plutus script spending, stake delegation, Conway governance (vote delegation, DRep operations).
chain_* — read-only Koios passthroughs (tx info, address info, pool list/info, epoch params, asset info, account info, tip).
dao_* — Agora DAO client. Multi-DAO via config files. Live reads (governor state, stake list, my stake) plus the full write set: proposal create / cosign / vote / advance / retract-votes / stake-destroy.
escrow_* — two-party agreement-with-veto escrow. Build unsigned txs for open / deposit / agree / veto / settle / refund-timeout.

Every write tool produces an unsigned tx for the caller to sign + submit. No tool ever holds private keys outside the in-memory derived-key scope.

Security model

Mnemonic source: interactive bootstrap on first run, paste once or generate, encrypted at rest with age. Never written to disk in plaintext.
Derived keys: in-memory only, ZeroizeOnDrop on every container.
Network exposure: stdio MCP transport — the binary never opens a TCP listener. Only the spawning client process can talk to it.
Multi-network: safe to point at preprod for development; the same binary handles mainnet when you flip ALDABRA_NETWORK.

Status

Wallet + governance paths exercised on mainnet. DAO + escrow paths exercised end-to-end on preprod; the escrow validator has had a code review but no third-party security audit. Treat the escrow flows as use-at-own-risk until external review lands — see aiken-escrow/README.md for the WIP threat model.

Contributing

Issues and pull requests are welcome. Before opening a PR, run cargo fmt, cargo clippy --all-targets, and cargo test. Changes that touch the on-chain validator (aiken-escrow/) or the signing path (aldabra-core) should spell out the security reasoning in the PR description.

License

Licensed under the GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later). See LICENSE for the full text.

Dependencies of note

txpipe/pallas — Rust Cardano primitives. Aldabra uses a fork on the feat-aux-data branch that adds auxiliary_data + voting_procedures support to pallas-txbuilder. PR upstream pending.
Aiken — Plutus V3 validator language used for the escrow contract.
modelcontextprotocol/rust-sdk (rmcp) — MCP server framework.
age — at-rest encryption.

7.4 KiB Raw Blame History