Kayos
489b58cc1e
Repo skeleton for sulkta-wallet, the rust-native cardano lite wallet
with MCP server interface. Builds end-to-end, types in place,
real cardano primitives land next pass.
Crates:
wallet-core — pure crypto + types. mnemonic, key derivation,
signing. No I/O. Security boundary.
wallet-chain — pluggable backends. ChainBackend trait, Koios
client (stub for now). Ogmios + submit in phase 2.
wallet-mcp — the binary. stdio MCP transport via rmcp.
Phase plan in ROADMAP.md, threat model in docs/architecture.md.
This is also Cobb's first Rust project + a real-world workout for
crafting-table's rust toolchain.
112 lines
4.3 KiB
Markdown
112 lines
4.3 KiB
Markdown
# sulkta-wallet
|
|
|
|
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 |
|
|
|---|---|
|
|
| `wallet-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. |
|
|
| `wallet-chain` | Pluggable backends for chain queries. `ChainBackend` trait, with Koios as the phase-1 implementation. Ogmios + submission paths in phase 2. |
|
|
| `wallet-mcp` | Binary. MCP server speaking stdio. Glues core + chain together, exposes tools to the LLM client. |
|
|
|
|
```
|
|
┌─────────────────────────────┐
|
|
LLM client │ wallet-mcp (bin) │ stdio
|
|
─────────► │ tool handlers, lifecycle │ ────►
|
|
└──────────┬──────────────────┘
|
|
│
|
|
┌────────┴────────┐
|
|
▼ ▼
|
|
┌──────────────┐ ┌──────────────┐
|
|
│ wallet-core │ │ wallet-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 sulkta-wallet
|
|
```
|
|
|
|
## Run
|
|
|
|
```bash
|
|
# Direct invocation (smoke test only — does nothing useful in phase 1)
|
|
./target/release/sulkta-wallet
|
|
|
|
# As an MCP server registered with Claude Code:
|
|
# add to ~/.claude.json:
|
|
# "sulkta-wallet": {
|
|
# "command": "/path/to/sulkta-wallet",
|
|
# "env": {
|
|
# "SULKTA_WALLET_DATA": "/mnt/cache/appdata/sulkta-wallet"
|
|
# }
|
|
# }
|
|
```
|
|
|
|
## 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
|