SDK

A TypeScript SDK for secure multi-party computation (MPC) and blockchain operations using the Vultisig protocol. Build secure, decentralized applications with threshold signature schemes and multi-chain support.

Features

🔐 Multi-Party Computation (MPC) - Secure threshold signatures using DKLS and Schnorr protocols
🏦 Fast Vault - Server-assisted 2-of-2 vault for quick setup and instant signing
🛡️ Secure Vault - Multi-device N-of-M threshold signing with mobile device pairing
📲 QR Code Pairing - Pair with Vultisig mobile apps (iOS/Android) for vault creation and signing
🌐 Multi-Chain Support - Bitcoin, Ethereum, Solana, THORChain, and 40+ blockchains
🔗 Address Derivation - Generate addresses across multiple blockchain networks
📱 Cross-Platform - Works in browsers, Node.js, and Electron (React Native coming soon)
🔒 Vault Management - Import, export, encrypt, and decrypt vault keyshares
🔑 Seedphrase Import - Import existing BIP39 mnemonics with automatic chain discovery
🌍 WASM Integration - High-performance cryptographic operations via WebAssembly

Installation

npm install @vultisig/sdk

Quick Start

1. Initialize the SDK

import { Vultisig, MemoryStorage } from '@vultisig/sdk'

const sdk = new Vultisig({
  storage: new MemoryStorage()
})

// Initialize WASM modules
await sdk.initialize()

2. Create a Fast Vault (Server-Assisted)

// Create a new vault using VultiServer
const vaultId = await sdk.createFastVault({
  name: "My Secure Wallet",
  email: "[email protected]",
  password: "SecurePassword123!",
});

// User will receive a verification code via email
const code = "1234"; // Get from user input
const vault = await sdk.verifyVault(vaultId, code);

3. Derive Blockchain Addresses

// Derive addresses for different blockchain networks
const btcAddress = await vault.address("Bitcoin");
const ethAddress = await vault.address("Ethereum");
const solAddress = await vault.address("Solana");

console.log("BTC:", btcAddress); // bc1q...
console.log("ETH:", ethAddress); // 0x...
console.log("SOL:", solAddress); // 9WzD...

4. Create a Secure Vault (Multi-Device)

// Create a secure vault with 2-of-3 threshold
const { vault, vaultId, sessionId } = await sdk.createSecureVault({
  name: "Team Wallet",
  devices: 3,                    // Total number of devices
  threshold: 2,                  // Optional: defaults to ceil((devices+1)/2)
  password: "optional-password", // Optional: encrypt the vault
  onQRCodeReady: (qrPayload) => {
    // Display this QR code for other devices to scan with Vultisig app
    displayQRCode(qrPayload);
  },
  onDeviceJoined: (deviceId, totalJoined, required) => {
    console.log(`Device joined: ${totalJoined}/${required}`);
  },
  onProgress: (step) => {
    console.log(`${step.step}: ${step.message}`);
  }
});

console.log("Vault created:", vault.name);

5. Sign with Secure Vault

// Signing requires coordination with other devices
await vault.sign(transactionPayload, {
  onQRCodeReady: (qrPayload) => {
    // Display QR for devices to join the signing session
    displayQRCode(qrPayload);
  },
  onDeviceJoined: (deviceId, total, required) => {
    console.log(`Signing: ${total}/${required} devices ready`);
  },
  onProgress: (step) => {
    console.log(`Signing progress: ${step.message}`);
  }
});

6. Import/Export Vaults

// Check if a vault file is encrypted
const isEncrypted = await sdk.isVaultFileEncrypted(file);

// Import vault from file
const vault = await sdk.addVault(file, isEncrypted ? "password" : undefined);

// Export vault to backup format (as Blob)
const backupBlob = await vault.export("BackupPassword123!");

// Or export as base64 string
const backupBase64 = await vault.exportAsBase64("BackupPassword123!");

7. Create Vault from Seedphrase

Import an existing wallet from a BIP39 mnemonic. Supports all 10 BIP39 languages with automatic detection:

// Validate the seedphrase first (auto-detects language)
const validation = await sdk.validateSeedphrase(mnemonic)
if (!validation.valid) {
  console.error(validation.error)
  return
}
console.log(`Detected language: ${validation.detectedLanguage}`) // 'english', 'japanese', etc.

// Discover which chains have balances
const chains = await sdk.discoverChainsFromSeedphrase(
  mnemonic,
  [Chain.Bitcoin, Chain.Ethereum, Chain.THORChain],
  (progress) => console.log(`${progress.chain}: ${progress.phase}`)
)

for (const result of chains) {
  if (result.hasBalance) {
    console.log(`${result.chain}: ${result.balance} ${result.symbol}`)
  }
}

// Create FastVault from seedphrase (requires email verification)
const vaultId = await sdk.createFastVaultFromSeedphrase({
  mnemonic,
  name: 'Imported Wallet',
  email: '[email protected]',
  password: 'SecurePassword123!',
  discoverChains: true, // Auto-enable chains with balances
  onProgress: (step) => console.log(step.message)
})

// Verify with email code
const vault = await sdk.verifyVault(vaultId, verificationCode)

Supported Blockchains

The SDK supports address derivation and operations for 40+ blockchain networks:

Network

Chain ID

Description

Bitcoin

bitcoin

Bitcoin mainnet

Ethereum

ethereum

Ethereum mainnet

Solana

solana

Solana mainnet

THORChain

thorchain

THORChain mainnet

Polygon

polygon

Polygon (MATIC)

Avalanche

avalanche

Avalanche C-Chain

BSC

bsc

Binance Smart Chain

Arbitrum

arbitrum

Arbitrum One

Optimism

optimism

Optimism mainnet

Cosmos

cosmos

Cosmos Hub

Litecoin

litecoin

Litecoin mainnet

Dogecoin

dogecoin

Dogecoin mainnet

...

And many more

Vault Types

The SDK supports two vault types for different security and usability requirements:

Feature

Fast Vault

Secure Vault

Threshold

2-of-2

N-of-M (configurable)

Setup

Server-assisted, instant

Multi-device, requires pairing

Signing

Instant via VultiServer

Requires device coordination

Use Cases

Personal wallets, quick setup

Team wallets, high security, custody

Device Pairing

None required

QR code with Vultisig mobile app

Password

Required

Optional

When to Use Each Type

Fast Vault - Best for:

Individual users wanting quick setup
Development and testing
Situations where server-assisted signing is acceptable

Secure Vault - Best for:

Team or organizational wallets
High-value assets requiring multi-party approval
Scenarios requiring configurable thresholds (2-of-3, 3-of-5, etc.)
Maximum security without server dependency during signing

Framework Integration Example

The SDK works with any JavaScript framework. Here's a React example:

React Component Example

import { Vultisig, MemoryStorage } from '@vultisig/sdk'
import type { VaultBase } from '@vultisig/sdk'
import { useState, useEffect } from 'react'

function VaultApp() {
  const [sdk] = useState(() => new Vultisig({ storage: new MemoryStorage() }))
  const [vault, setVault] = useState<VaultBase | null>(null)
  const [addresses, setAddresses] = useState<Record<string, string>>({})

  useEffect(() => {
    // Initialize SDK on component mount
    sdk.initialize().catch(console.error)
  }, [sdk])

  const createVault = async () => {
    try {
      const vaultId = await sdk.createFastVault({
        name: 'My Wallet',
        email: '[email protected]',
        password: 'SecurePassword123!'
      })

      // User receives verification code via email
      const code = prompt('Enter verification code from email:')
      const vault = await sdk.verifyVault(vaultId, code!)
      setVault(vault)
    } catch (error) {
      console.error('Vault creation failed:', error)
    }
  }

  const deriveAddresses = async () => {
    if (!vault) return

    const chains = ['Bitcoin', 'Ethereum', 'Solana']
    const results: Record<string, string> = {}

    for (const chain of chains) {
      try {
        results[chain] = await vault.address(chain)
      } catch (error) {
        console.error(`Failed to derive ${chain} address:`, error)
      }
    }

    setAddresses(results)
  }

  return (
    <div>
      <h1>Vultisig SDK Demo</h1>

      {!vault && (
        <button onClick={createVault}>
          Create Fast Vault
        </button>
      )}

      {vault && (
        <div>
          <h2>Vault: {vault.name}</h2>
          <p>Local Party: {vault.localPartyId}</p>

          <button onClick={deriveAddresses}>
            Derive Addresses
          </button>

          {Object.keys(addresses).length > 0 && (
            <div>
              <h3>Addresses</h3>
              {Object.entries(addresses).map(([chain, address]) => (
                <div key={chain}>
                  <strong>{chain.toUpperCase()}:</strong> {address}
                </div>
              ))}
            </div>
          )}
        </div>
      )}
    </div>
  )
}

export default VaultApp

Configuration

SDK Configuration

const sdk = new Vultisig({
  autoInit: true, // Automatically initialize WASM modules on creation
  serverUrl: "https://api.vultisig.com", // Custom VultiServer endpoint
  relayUrl: "https://relay.vultisig.com", // Custom relay endpoint
});

WASM Files

The SDK requires three WASM files to be available in your application's public directory:

wallet-core.wasm - Trust Wallet Core for address derivation
dkls.wasm - ECDSA threshold signatures (DKLS protocol)
schnorr.wasm - EdDSA threshold signatures (Schnorr protocol)

For bundled applications (Vite, webpack, etc.), place these files in the public/ directory.

API Reference

Core Methods

`initialize(): Promise<void>`

Initialize the SDK and load all WASM modules.

`createFastVault(options): Promise<string>`

Create a new vault using VultiServer assistance. Returns the vaultId.

Parameters:

options.name: string - Vault name
options.email: string - Email for verification
options.password: string - Vault encryption password

`verifyVault(vaultId, code): Promise<FastVault>`

Verify vault creation with email verification code. Returns the verified vault.

`createSecureVault(options): Promise<{ vault, vaultId, sessionId }>`

Create a multi-device secure vault with N-of-M threshold signing.

Parameters:

options.name: string - Vault name
options.devices: number - Number of devices participating (minimum 2)
options.threshold?: number - Signing threshold (defaults to ceil((devices+1)/2))
options.password?: string - Optional vault encryption password
options.onQRCodeReady?: (qrPayload: string) => void - Called when QR code is ready for device pairing
options.onDeviceJoined?: (deviceId: string, total: number, required: number) => void - Called when a device joins
options.onProgress?: (step: VaultCreationStep) => void - Called with creation progress updates

Returns:

vault: SecureVault - The created vault instance
vaultId: string - Unique vault identifier
sessionId: string - Session ID used for creation

`validateSeedphrase(mnemonic): Promise<SeedphraseValidation>`

Validate a BIP39 mnemonic phrase.

Returns:

valid: boolean - Whether the mnemonic is valid
wordCount: number - Number of words (12 or 24)
invalidWords?: string[] - Words not in BIP39 wordlist
error?: string - Error message if invalid

`discoverChainsFromSeedphrase(mnemonic, chains?, onProgress?): Promise<ChainDiscoveryResult[]>`

Discover chains with balances for a seedphrase.

Parameters:

mnemonic: string - BIP39 mnemonic phrase
chains?: Chain[] - Chains to scan (defaults to common chains)
onProgress?: (progress: ChainDiscoveryProgress) => void - Progress callback

`createFastVaultFromSeedphrase(options): Promise<string>`

Create a FastVault from a BIP39 seedphrase. Returns vaultId for email verification.

Parameters:

options.mnemonic: string - BIP39 mnemonic (12 or 24 words)
options.name: string - Vault name
options.email: string - Email for verification
options.password: string - Vault encryption password
options.discoverChains?: boolean - Auto-enable chains with balances
options.onProgress?: (step: VaultCreationStep) => void - Progress callback
options.onChainDiscovery?: (progress: ChainDiscoveryProgress) => void - Discovery callback

`createSecureVaultFromSeedphrase(options): Promise<{ vault, vaultId, sessionId }>`

Create a SecureVault from a BIP39 seedphrase with multi-device MPC.

Parameters:

options.mnemonic: string - BIP39 mnemonic (12 or 24 words)
options.name: string - Vault name
options.devices: number - Number of participating devices
options.threshold?: number - Signing threshold
options.password?: string - Optional encryption password
options.onQRCodeReady?: (qrPayload: string) => void - QR callback
options.onDeviceJoined?: (deviceId, total, required) => void - Device join callback

`joinSecureVault(qrPayload, options): Promise<{ vault, vaultId }>`

Join an existing SecureVault creation session. Auto-detects keygen vs seedphrase mode.

Parameters:

qrPayload: string - QR code content from initiator (vultisig://...)
options.mnemonic?: string - Required for seedphrase-based sessions, ignored for keygen
options.devices: number - Number of participating devices (required)
options.password?: string - Optional encryption password
options.onProgress?: (step: VaultCreationStep) => void - Progress callback
options.onDeviceJoined?: (deviceId, total, required) => void - Device join callback

`vault.address(chain): Promise<string>`

Derive a blockchain address for the given chain (called on Vault instance).

`addVault(file, password?): Promise<Vault>`

Import a vault from a backup file.

`vault.export(password?): Promise<Blob>`

Export a vault to encrypted backup format as a Blob (called on Vault instance).

`vault.exportAsBase64(password?): Promise<string>`

Export a vault to encrypted backup format as a base64 string (called on Vault instance).

`secureVault.sign(payload, options?): Promise<SigningResult>`

Sign a transaction with a SecureVault (requires device coordination).

Parameters:

payload: SigningPayload - Transaction data to sign
options.signal?: AbortSignal - Optional signal to cancel the signing operation
options.onQRCodeReady?: (qrPayload: string) => void - Called when QR code is ready for device pairing
options.onDeviceJoined?: (deviceId: string, total: number, required: number) => void - Called when a device joins
options.onProgress?: (step: SigningStep) => void - Called with signing progress updates

`secureVault.signBytes(options, signingOptions?): Promise<SigningResult>`

Sign arbitrary bytes with a SecureVault.

Parameters:

options.chain: string - Chain for signature algorithm selection
options.messages: (Uint8Array | Buffer | string)[] - Messages to sign (hex strings or bytes)
signingOptions.signal?: AbortSignal - Optional signal to cancel the operation

Utility Methods

`isVaultFileEncrypted(file): Promise<boolean>`

Check if a vault backup file is encrypted.

`validateVault(vault): VaultValidationResult`

Validate vault structure and integrity.

`getVaultDetails(vault): VaultDetails`

Get vault metadata and information.

Error Handling

The SDK throws descriptive errors that you can catch and handle:

try {
  const vault = await sdk.createFastVault({
    name: "Test Vault",
    email: "invalid-email",
    password: "123",
  });
} catch (error) {
  if (error.message.includes("email")) {
    console.error("Invalid email address");
  } else if (error.message.includes("password")) {
    console.error("Password too weak");
  } else {
    console.error("Vault creation failed:", error);
  }
}

Examples

See the /examples directory for complete sample applications:

Browser Example - Complete web application with vault creation, import, and address derivation
Node.js Example - Server-side vault operations and blockchain interactions

Requirements

Node.js 20+
Modern browser with WebAssembly support
Electron 20+ (for desktop applications)
Network access for VultiServer communication (for Fast Vault features)

Security Considerations

Private Keys: The SDK uses threshold signatures - private keys are never stored in a single location
Encryption: Vault keyshares are encrypted using AES-GCM with user-provided passwords
Server Trust: Fast Vaults use VultiServer as one party in the MPC protocol
Secure Vault Independence: Secure Vaults only use the relay server for coordination, not signing
Configurable Thresholds: Secure Vaults support custom M-of-N thresholds for multi-party approval
WASM Integrity: Ensure WASM files are served from trusted sources

Development

Prerequisites

Node.js 20+
Yarn 4.x

Setup

This SDK is part of a monorepo. Always install dependencies from the root directory:

# Clone the repository
git clone https://github.com/vultisig/vultisig-sdk.git
cd vultisig-sdk

# IMPORTANT: Install from root (sets up all workspace packages)
yarn install

Building

The SDK bundles functionality from workspace packages (packages/core/ and packages/lib/) into a single distributable package.

# Build the SDK (from root directory)
yarn workspace @vultisig/sdk build

This creates the distributable package in packages/sdk/dist/ with all dependencies bundled.

Testing

# Run tests (from root directory)
yarn workspace @vultisig/sdk test

Development Workflow

Make changes to SDK code in packages/sdk/src/ or workspace packages in packages/core//packages/lib/
Build: yarn workspace @vultisig/sdk build
Test: yarn workspace @vultisig/sdk test
Lint: yarn lint (from root)

Project Structure

packages/sdk/
├── src/                # SDK source code
│   ├── chains/        # Address derivation and chain management
│   ├── mpc/           # Multi-party computation logic
│   ├── vault/         # Vault creation and management
│   ├── server/        # Fast vault server integration
│   └── wasm/          # WASM module management
├── tests/             # Test suite
└── package.json       # SDK package configuration

# Workspace packages (bundled into SDK)
packages/core/         # Core blockchain functionality
packages/lib/          # Shared libraries and utilities

Contributing

Fork the repository
Install dependencies from root: yarn install
Make your changes in packages/sdk/src/ or workspace packages
Run tests: yarn workspace @vultisig/sdk test
Build: yarn workspace @vultisig/sdk build
Submit a pull request

License

MIT License - see LICENSE file for details.

Support

Built with ❤️ by the Vultisig team

PreviousExtension Integration NextSDK Implementation Guide

Last updated 9 hours ago

Was this helpful?

hashtagFeatures

hashtagInstallation

hashtagQuick Start

hashtag1. Initialize the SDK

hashtag2. Create a Fast Vault (Server-Assisted)

hashtag3. Derive Blockchain Addresses

hashtag4. Create a Secure Vault (Multi-Device)

hashtag5. Sign with Secure Vault

hashtag6. Import/Export Vaults

hashtag7. Create Vault from Seedphrase

hashtagSupported Blockchains

hashtagVault Types

hashtagWhen to Use Each Type

hashtagFramework Integration Example

hashtagReact Component Example

hashtagConfiguration

hashtagSDK Configuration

hashtagWASM Files

hashtagAPI Reference

hashtagCore Methods

hashtaginitialize(): Promise<void>

hashtagcreateFastVault(options): Promise<string>

hashtagverifyVault(vaultId, code): Promise<FastVault>

hashtagcreateSecureVault(options): Promise<{ vault, vaultId, sessionId }>

hashtagvalidateSeedphrase(mnemonic): Promise<SeedphraseValidation>

hashtagdiscoverChainsFromSeedphrase(mnemonic, chains?, onProgress?): Promise<ChainDiscoveryResult[]>

hashtagcreateFastVaultFromSeedphrase(options): Promise<string>

hashtagcreateSecureVaultFromSeedphrase(options): Promise<{ vault, vaultId, sessionId }>

hashtagjoinSecureVault(qrPayload, options): Promise<{ vault, vaultId }>

hashtagvault.address(chain): Promise<string>

hashtagaddVault(file, password?): Promise<Vault>

hashtagvault.export(password?): Promise<Blob>

hashtagvault.exportAsBase64(password?): Promise<string>

hashtagsecureVault.sign(payload, options?): Promise<SigningResult>

hashtagsecureVault.signBytes(options, signingOptions?): Promise<SigningResult>

hashtagUtility Methods

hashtagisVaultFileEncrypted(file): Promise<boolean>

hashtagvalidateVault(vault): VaultValidationResult

hashtaggetVaultDetails(vault): VaultDetails

hashtagError Handling

hashtagExamples

hashtagRequirements

hashtagSecurity Considerations

hashtagDevelopment

hashtagPrerequisites

hashtagSetup

hashtagBuilding

hashtagTesting

hashtagDevelopment Workflow

hashtagProject Structure

hashtagContributing

hashtagLicense

hashtagSupport

Features

Installation

Quick Start

1. Initialize the SDK

2. Create a Fast Vault (Server-Assisted)

3. Derive Blockchain Addresses

4. Create a Secure Vault (Multi-Device)

5. Sign with Secure Vault

6. Import/Export Vaults

7. Create Vault from Seedphrase

Supported Blockchains

Vault Types

When to Use Each Type

Framework Integration Example

React Component Example

Configuration

SDK Configuration

WASM Files

API Reference

Core Methods

`initialize(): Promise<void>`

`createFastVault(options): Promise<string>`

`verifyVault(vaultId, code): Promise<FastVault>`

`createSecureVault(options): Promise<{ vault, vaultId, sessionId }>`

`validateSeedphrase(mnemonic): Promise<SeedphraseValidation>`

`discoverChainsFromSeedphrase(mnemonic, chains?, onProgress?): Promise<ChainDiscoveryResult[]>`

`createFastVaultFromSeedphrase(options): Promise<string>`

`createSecureVaultFromSeedphrase(options): Promise<{ vault, vaultId, sessionId }>`

`joinSecureVault(qrPayload, options): Promise<{ vault, vaultId }>`

`vault.address(chain): Promise<string>`

`addVault(file, password?): Promise<Vault>`

`vault.export(password?): Promise<Blob>`

`vault.exportAsBase64(password?): Promise<string>`

`secureVault.sign(payload, options?): Promise<SigningResult>`

`secureVault.signBytes(options, signingOptions?): Promise<SigningResult>`

Utility Methods

`isVaultFileEncrypted(file): Promise<boolean>`

`validateVault(vault): VaultValidationResult`

`getVaultDetails(vault): VaultDetails`

Error Handling

Examples

Requirements

Security Considerations

Development

Prerequisites

Setup

Building

Testing

Development Workflow

Project Structure

Contributing

License

Support