Doko: Bitcoin Vault with CTV and CSFS

Doko implements Bitcoin vaults using Taproot (P2TR), OP_CHECKTEMPLATEVERIFY (CTV) for covenants, and OP_CHECKSIGFROMSTACK (CSFS) for delegation. It's built for Mutinynet signet, which activates CTV and CSFS.

Disclaimer: This is an experimental project for educational purposes.

How It Works

Basic Vault (CTV-Only)

Funds go into a vault UTXO locked by CTV to a specific "trigger" tx template. Anyone can broadcast that trigger tx, moving funds to a conditional UTXO with two paths:

• Hot path: Wait CSV blocks (e.g., 144), then spend with a hot key sig.
• Cold path: Immediate CTV spend to a cold address: no sig, no wait.

┌──────────────┐    CTV    ┌──────────────┐    IF/ELSE    ┌──────────────┐
│    Vault     │ ────────► │   Trigger    │ ────────────► │  Final       │
│   (P2TR)     │           │   (P2TR)     │               │ Destination  │
└──────────────┘           └──────────────┘               └──────────────┘
   Covenant                   Conditional                   Hot or Cold
   Protection                 Spending                        Wallet

The lifecycle:

                    🏦 VAULT LIFECYCLE FLOW

┌─────────────────────────────────────────────────────────────────┐
│                        STEP 1: DEPOSIT                          │
└─────────────────────────────────────────────────────────────────┘

         Fund with Bitcoin
              │
              ▼
    ┌─────────────────┐     📍 Taproot P2TR Address
    │   Vault UTXO    │     🔒 CTV Script: <trigger_hash> OP_CTV
    │ (Taproot P2TR)  │     🔑 NUMS Internal Key (no key-path spend)
    └─────────┬───────┘
              │ Anyone can trigger (script-path spend)
              ▼

┌─────────────────────────────────────────────────────────────────┐
│                       STEP 2: TRIGGER                           │
└─────────────────────────────────────────────────────────────────┘

    ┌─────────────────┐     🚀 Broadcasts Trigger Transaction
    │   Trigger TX    │     ✅ CTV validates exact template match
    │ (CTV-enforced)  │     💸 Fee: ~1000 sats
    └─────────┬───────┘
              │
              ▼
    ┌─────────────────┐     📍 Taproot P2TR Address
    │  Trigger UTXO   │     🔀 Script: IF <csv> CSV <hot_key> CHECKSIG
    │ (Conditional)   │            ELSE <cold_hash> CTV ENDIF
    └─────┬─────┬─────┘
          │     │
          │     └─────────────────────────┐
          ▼                               ▼

┌─────────────────────────────────────────────────────────────────┐
│                    STEP 3A: HOT PATH                            │
└─────────────────────────────────────────────────────────────────┘

    ┌──────────────┐        ⏰ Wait CSV Delay (e.g., 144 blocks)
    │  🔥 Hot Path │        🔑 Requires Hot Key Signature
    │   N blocks   │        📨 Sequence: CSV delay value
    │ + signature  │        💸 Fee: ~1000 sats
    └──────┬───────┘
           │
           ▼
    ┌──────────────┐        📍 Hot Wallet P2TR Address
    │ Hot Wallet   │        ✅ Normal withdrawal complete
    │  (Final)     │
    └──────────────┘

┌─────────────────────────────────────────────────────────────────┐
│                   STEP 3B: COLD PATH                            │
└─────────────────────────────────────────────────────────────────┘

    ┌──────────────┐        🚨 EMERGENCY RESPONSE
    │ ❄️ Cold Path │        ⚡ Immediate (no delay)
    │  Immediate   │        🔒 CTV enforced template
    │ CTV sweep    │        💸 Fee: ~1000 sats
    └──────┬───────┘
           │
           ▼
    ┌──────────────┐        📍 Cold Wallet P2TR Address
    │ Cold Storage │        🛡️ Funds secured from attack
    │  (Emergency) │
    └──────────────┘

Vault script: <trigger_hash> OP_CTV

Trigger script:

OP_IF
    <csv> OP_CSV OP_DROP <hot_pubkey> OP_CHECKSIG
OP_ELSE
    <cold_hash> OP_CTV
OP_ENDIF

In the implementation we use a NUMS internal key to force script spends only.

Hybrid Vault (CTV + CSFS)

Adds a CSFS path for delegation alongside CTV. Vault UTXO has a two-leaf Taproot tree:

• Leaf 1: CTV to trigger (same as basic).
• Leaf 2: CSFS to verify a sig over a message, allowing delegated spends (e.g., treasurer signs off for ops team).

                              🏦 HYBRID VAULT STRUCTURE
                              (Multi-Path Taproot P2TR)

                     ┌──────────────────────────────────┐
                     │      Hybrid Vault UTXO (P2TR)    │
                     │        (NUMS Internal Key:       |
                     |        Script-Spend Only)        │
                     └─────────────────┬────────────────┘
                                       │ Script-Path Spend
                                       ▼
                  ┌────────────────────┴────────────────────┐
                  │                                         │
                  ▼                                         ▼
   ┌──────────────────────────────┐          ┌──────────────────────────────┐
   │ Path 1: CTV Covenant Script  │          │  Path 2: CSFS Delegation     │
   │ (<trigger_hash> OP_CTV)      │          │(<sig> <msg> <pubkey> OP_CSFS)│
   └──────────────┬───────────────┘          └──────────────┬───────────────┘
                  │ Spends to...                            │ Spends to...
                  ▼                                         ▼
   ┌──────────────────────────────┐          ┌──────────────────────────────┐
   │    Trigger Transaction       │          │ Delegated Spend Transaction  │
   │  (CTV-Enforced Template)     │          │  (Treasurer authorizes Ops)  │
   └──────────────┬───────────────┘          └──────────────────────────────┘
                  │ Creates...
                  ▼
   ┌──────────────────────────────┐
   │      Trigger UTXO (P2TR)     │
   │ (Conditional IF/ELSE Script) │
   └──────────────┬───────────────┘
                  │ Spends via...
                  ▼
         ┌────────┴────────┐
         │                 │
         ▼                 ▼
┌─────────────────┐   ┌─────────────────┐
│   🔥 HOT PATH   │   │   ❄️ COLD PATH  │
│   (IF Branch)   │   │  (ELSE Branch)  │
└────────┬────────┘   └────────┬────────┘
         │                     │
         ▼                     ▼
┌─────────────────┐   ┌─────────────────┐
│ <csv> OP_CSV    │   │ <cold_hash>     │
│<hot> OP_CHECKSIG│   │   OP_CTV        │
└────────┬────────┘   └────────┬────────┘
         │                     │
         ▼                     ▼
┌─────────────────┐   ┌─────────────────┐
│   Hot Wallet    │   │  Cold Storage   │
│  (Normal Spend) │   │(Emergency Sweep)│
└─────────────────┘   └─────────────────┘

And the tree:

Hybrid Vault (P2TR)
├── CTV Covenant Path (Depth 1)
│   ├── Hot withdrawal (CSV + signature)
│   └── Cold recovery (CTV immediate)
└── CSFS Delegation Path (Depth 1)
    └── Message signature verification

Transaction Details

1. Setup: Gen hot/cold keys. Compute trigger and cold tx templates. Build Taproot addresses.

2. Fund: Send to vault P2TR. Locked by CTV.

3. Trigger: Broadcast exact trigger tx. Witness: script + control block.

4. Hot spend: After CSV, sig with hot key, sequence >= CSV. Witness: sig + TRUE + script + control.

5. Cold spend: Broadcast exact cold tx. Witness: FALSE + script + control.

6. CSFS delegate (hybrid): Spend vault directly with CSFS-verified sig. No trigger needed.

Try it

CLI demos:

# See available commands: cargo run -- auto-demo --help
cargo run -- auto-demo --vault-type simple --scenario cold-recovery
cargo run -- auto-demo --vault-type hybrid --scenario csfs-delegation
cargo run -- auto-demo --vault-type hybrid --scenario cold-recovery
cargo run -- auto-demo --vault-type hybrid --scenario hot-withdrawal

TUI dashboard:

# TUI dashboard to monitor vaults

## Run the dashboard for the simple vault type (CTV only)
cargo run -- dashboard --vault-type simple

## Run the dashboard for the hybrid vault type (CTV + CSFS)
cargo run -- dashboard --vault-type hybrid

Monitors chain, broadcasts txs, tracks balances. Works on Mutinynet.

License

This project is licensed under the MIT License.