Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/natureloved/DeadMan-Vault/llms.txt

Use this file to discover all available pages before exploring further.

A Deadman Vault is a treasury continuity instrument — you lock USDCx on-chain and assign beneficiaries who receive it automatically if you stop checking in. Creating one is a two-phase process: first the server provisions a vault record in the database and generates a dedicated keeper keypair, then you sign a single on-chain USDCx transfer from your own wallet to fund the keeper. From that point forward, the keeper — a server-held key — handles every FlowVault contract call on your behalf. No further wallet signatures are required until your next heartbeat check-in.

​
Prerequisites

  • A Stacks wallet — Leather or Xverse (one extension only; having both installed causes a StacksProvider conflict)
  • Testnet USDCx to lock in the vault
  • Testnet STX in your wallet for gas on the deposit transaction
Deadman Vault is currently running on Stacks testnet only. The keeper uses a custodial pattern — the server holds an encrypted private key per vault. Never use mainnet funds or store real assets until a non-custodial architecture ships. See the project README for details on the testnet-only custodial keeper design.

​
Creation flow

1

Navigate to /create and connect your wallet

Open /create in your browser. On the first step you will see a Connect Stacks Wallet button. Click it — your wallet extension (Leather or Xverse) will open an authentication dialog. Once approved, your truncated Stacks address appears in green and the Next button becomes active.If the wallet popup never appears, check that you have exactly one Stacks wallet extension enabled in chrome://extensions. Multiple extensions compete over window.StacksProvider and silently block the connection.
2

Configure your vault

Fill in the Configure Vault form:
FieldRequiredNotes
Vault NameNoA human-readable label shown on your dashboard (e.g. “My Legacy Vault”)
Deposit AmountYesAmount of USDCx to lock; must be greater than 0
Heartbeat IntervalYesHow often you must check in before the vault triggers (see options below)
Your EmailYesUsed to send warning notifications before a missed check-in triggers succession
Heartbeat interval options:
LabelValue
7 days7
14 days14
1 month30
2 months60
3 months90
6 months180
1 year365
2 years730
Your email is the only channel through which the system can warn you before a missed check-in triggers vault succession. It is required.
3

Add beneficiaries

Add between 1 and 5 beneficiaries. Each beneficiary record requires:
  • Stacks address — a valid SP… or ST… address on testnet
  • Name — a display name
  • Allocation percent — their share of the vault (integer; all beneficiaries must sum to exactly 100)
  • Email (optional) — for claim-ready notification emails
  • Vesting days (optional) — if set, funds are withheld until triggeredAt + vestingDays days after the vault triggers; set to 0 for immediate lump-sum release
Allocation percentages must sum to exactly 100. The form will show the running total and block submission if the total is off.
4

Write an optional message

The Personal Message step lets you leave a note that beneficiaries will see on their claim page. This is stored server-side and shown on /claim/[vaultId] and /status/[vaultId] when the vault is triggered. The field is optional — leave it blank to skip.
5

Review your configuration

The final Review & Deposit screen summarises:
  • Total deposit in USDCx
  • Heartbeat interval in days
  • Number of beneficiaries
  • Total allocation percentage
Confirm everything looks correct before clicking Create Vault. The button label changes in real time as the submission progresses through four stages: Preparing vault… → Confirm in wallet… → Confirming on-chain (may take ~30s)… → back to Create Vault on completion.
6

Server provisions vault record (Phase 1)

When you click Create Vault, the button immediately changes to Preparing vault… while the app calls POST /api/vaults with your configuration. The server:
  1. Validates that allocations total 100% and all beneficiary addresses are valid Stacks addresses.
  2. Generates a new keeper keypair (generateKeeperAccount).
  3. Inserts a vault record into the database with status: "funding", your keeper address, and the AES-encrypted keeper private key.
  4. Inserts one beneficiary row per beneficiary you added.
  5. Fires a best-effort background call to fund the keeper address with testnet STX for gas.
  6. Returns { vaultId, keeperAddress } to the client.
Once Phase 1 succeeds the button advances to Confirm in wallet…
7

Sign the USDCx deposit in your wallet

Your wallet extension opens with a pre-built SIP-010 transfer transaction: it sends your full deposit amount of USDCx from your address to the keeper address returned in the previous step. This is the only transaction you sign during vault creation. Review the amount and recipient, then confirm.The call uses PostConditionMode.Allow and targets the usdcx contract at ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM. After you confirm, the wallet returns a txId.If your wallet doesn’t respond within 45 seconds the app surfaces an error prompting you to check for conflicting wallet extensions.
8

Server activates vault on-chain (Phase 2)

The app immediately calls POST /api/vaults/[id]/fund with the txId from your wallet. The server:
  1. Decrypts the keeper private key.
  2. Instantiates a FlowVault client (flowvault-v2 contract at STD7QG84VQQ0C35SZM2EYTHZV4M8FQ0R7YNSQWPD) with the keeper as the signer.
  3. Reads the current Stacks block height.
  4. Computes deadlineBlock = currentBlock + heartbeatIntervalDays × 144 (144 blocks ≈ 1 day on Stacks).
  5. Calls setRoutingRules on the FlowVault contract with the lock amount and deadline block.
  6. Calls deposit to lock the USDCx.
  7. Updates the vault record in the database with status: "active", heartbeat_deadline_block, and the on-chain txId.
On success the app redirects you to /dashboard?vaultId=[id].
On-chain confirmation can take up to ~30 seconds. The button shows Confirming on-chain (may take ~30s)… during this window. Do not close the tab.

​
Two-phase creation summary

Browser                     Server                  Stacks chain
──────────────────────────────────────────────────────────────────
POST /api/vaults ──────────► Create DB record
                              Generate keeper keypair
                              Return { vaultId, keeperAddress }

Sign USDCx transfer ──────────────────────────────► SIP-010 transfer
(wallet popup)                                       to keeperAddress

POST /api/vaults/[id]/fund ─► Decrypt keeper key
                              setRoutingRules ──────► FlowVault contract
                              deposit ──────────────► FlowVault contract
                              Update DB status → active

​
Next steps

Once your vault status is active, you need to check in periodically to keep it alive.

Performing a Heartbeat Check-In

Learn how to sign a 0.01 USDCx heartbeat transfer to extend your vault’s deadline.

Build docs developers (and LLMs) love

Get started for freeTalk to us