Table of Contents

• About
• Why Anvil Vault?
• Getting Started
  • Installation
  • Quick Start
  • Examples
• Packages
  • Core Packages
  • Framework Adapters
• Security Considerations
• Error Handling
• Getting Help

About

@ada-anvil/vault is a comprehensive custodial wallet solution for Cardano.

Why Anvil Vault?

• Hierarchical Deterministic (HD) Wallets: Generate unlimited addresses from a single seed phrase, following Cardano's CIP-1852 standard
• Message & Transaction Signing: Sign blockchain transactions and messages with full CIP-8 and CIP-30 compliance
• Type-Safe Blockchain Integration: Comprehensive TypeScript wrappers around Cardano Serialization Library (CSL)
• Framework Agnostic: Drop-in adapters for Express.js and Hono
• Modern Error Handling: Type-safe Result patterns using trynot

Getting Started

Installation

npm install @ada-anvil/vault

Quick Start

See the Vault Quick Start Guide for a complete walkthrough.

Examples

For complete working examples:

• Express Example - Full Express.js integration
• Hono Example - Full Hono integration

Packages

Anvil Vault is composed of specialized packages:

Core Packages

@ada-anvil/vault

• Core vault orchestration for key derivation, address generation, and signing operations
• CIP-1852 compliant derivation with flexible strategies

[!WARNING] Peer Dependencies - @emurgo/cardano-message-signing-nodejs-gc: COSE signing implementation - @emurgo/cardano-serialization-lib-nodejs-gc: Cardano cryptography

@ada-anvil/vault/csl

• Type-safe wrappers around Cardano Serialization Library
• Derivation, address generation, signing, verification, parsing, and network utilities

[!WARNING] Peer Dependencies - @emurgo/cardano-serialization-lib-nodejs-gc: Cardano cryptography

@ada-anvil/vault/cms

• Cardano Message Signing (CIP-8/CIP-30) using COSE
• Sign and verify wallet messages

[!WARNING] Peer Dependencies - @emurgo/cardano-message-signing-nodejs-gc: COSE signing implementation

@ada-anvil/vault/bip39

• BIP-39 mnemonic generation and entropy parsing

[!WARNING] Peer Dependencies - bip39: BIP-39 mnemonic operations and wordlist management

@ada-anvil/vault/handler

• Framework-agnostic HTTP handler builder and derivation utilities

@ada-anvil/vault/utils

• Shared utilities for error handling, validation, parsing, and helper types

Framework Adapters

@ada-anvil/vault/express

• Adapter to use handlers with Express.js

@ada-anvil/vault/hono

• Adapter to use handlers with Hono

Security Considerations

Root Key Management

[!WARNING] Your root key is the master secret that controls all wallets. If compromised, an attacker can access all user funds.

• Never hardcode root keys in your source code or configuration files
• Store root keys in dedicated key management systems
• Use different keys per environment

Derivation Strategies (User Address Generation)

How you generate user addresses directly impacts security and privacy.

Payment Keys (Spending Addresses)

• Never use constant derivation in production - this generates the same address for all users, creating a security and privacy vulnerability
• Always use unique derivation with scrambling - this ensures each user gets cryptographically isolated addresses
• The pool strategy was designed for stake keys (see below)

Stake Keys (Reward Addresses)

• Use pool derivation for stake keys - this allows you to consolidate all users' staking rewards to a set of addresses for easier management. Each user is deterministically assigned one of the available addresses
• Pool derivation is safe for stake keys because they don't control spendable funds

Error Handling

All functions return Result types from the trynot library for consistent, type-safe error handling:

import { isOk, unwrap } from "trynot";

const result = await vault.getWallet({ userId: "user123" });

if (isOk(result)) {
  console.log(result.addresses.base.bech32);
}

// Or unwrap (throws on error)
const unwrapped = unwrap(await vault.getWallet({ userId: "user123" }));

Getting Help

• Issues: GitHub Issues
• Discord: Join our Discord
• Documentation: Individual package READMEs for detailed API docs
• Examples: See examples/ for complete working examples