Kayos 489b58cc1e phase 1 scaffold: cargo workspace + 3 crates + roadmap + architecture

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.

2026-05-04 10:02:32 -07:00

4.3 KiB

Raw Blame History

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) or built on Blockfrost (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

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

# Through crafting-table (preferred — validates the toolchain there)
crafting-table build sulkta-wallet

Run

# 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. 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.

4.3 KiB Raw Blame History