sonr/cmd/vault/README.md

Vault - WebAssembly Vault Plugin

Vault is a WebAssembly-based vault system for the Sonr blockchain that provides secure, isolated execution of cryptographic operations. Built using the Extism framework, Vault enables secure multi-party computation (MPC) and vault management within a sandboxed WebAssembly environment.

Overview

Vault serves as a cryptographic vault system that:

• Provides secure enclave-based key generation and management
• Supports multi-chain transaction signing (Cosmos, EVM)
• Implements WebAuthn-based authentication
• Offers secure import/export functionality via IPFS
• Enables isolated execution through WebAssembly

Architecture

Core Components

• MPC Enclave: Multi-party computation system for secure key operations
• Vault Management: Create, unlock, and manage cryptographic vaults
• IPFS Integration: Secure backup and restore of encrypted vault data
• WebAuthn Support: Passwordless authentication for vault operations
• Multi-Chain Support: Transaction signing for different blockchain networks

Build Configuration

Vault is built specifically for WebAssembly:

//go:build js && wasm
// +build js,wasm

API Reference

Core Enclave Operations

generate

//go:wasmexport generate
func generate() int32

Creates a new MPC enclave and returns the enclave data and public key.

Input: GenerateRequest

{
  "id": "string"
}

Output: GenerateResponse

{
  "data": "EnclaveData",
  "public_key": "[]byte"
}

refresh

//go:wasmexport refresh
func refresh() int32

Refreshes an existing enclave with new cryptographic material.

Input: RefreshRequest

{
  "enclave": "EnclaveData"
}

Output: RefreshResponse

{
  "okay": "bool",
  "data": "EnclaveData"
}

sign

//go:wasmexport sign
func sign() int32

Signs a message using the enclave's private key.

Input: SignRequest

{
  "message": "[]byte",
  "enclave": "EnclaveData"
}

Output: SignResponse

{
  "signature": "[]byte"
}

verify

//go:wasmexport verify
func verify() int32

Verifies a signature against a message and public key.

Input: VerifyRequest

{
  "public_key": "[]byte",
  "message": "[]byte",
  "signature": "[]byte"
}

Output: VerifyResponse

{
  "valid": "bool"
}

Vault Import/Export Operations

export

//go:wasmexport export
func export() int32

Encrypts and exports vault data to IPFS, returning a Content ID (CID).

Input: ExportRequest

{
  "enclave": "EnclaveData",
  "password": "[]byte"
}

Output: ExportResponse

{
  "cid": "string",
  "success": "bool"
}

import

//go:wasmexport import
func importVault() int32

Retrieves and decrypts vault data from IPFS using a CID and password.

Input: ImportRequest

{
  "cid": "string",
  "password": "[]byte"
}

Output: ImportResponse

{
  "enclave": "EnclaveData",
  "success": "bool"
}

Advanced Vault Operations

create_vault_enclave

//go:wasmexport create_vault_enclave
func createVaultEnclave() int32

Creates a new vault enclave with advanced configuration options.

Input: EnclaveConfig

{
  "vault_id": "string",
  "key_derivation_method": "string",
  "encryption_algorithm": "string",
  "signing_algorithm": "string",
  "webauthn_enabled": "bool",
  "auto_lock_timeout": "int64",
  "key_rotation_interval": "int64",
  "supported_chains": ["string"],
  "max_concurrent_ops": "int",
  "memory_limit": "uint64"
}

unlock_vault_enclave

//go:wasmexport unlock_vault_enclave
func unlockVaultEnclave() int32

Unlocks a vault enclave, optionally using WebAuthn authentication.

lock_vault_enclave

//go:wasmexport lock_vault_enclave
func lockVaultEnclave() int32

Locks a vault enclave to prevent unauthorized access.

rotate_vault_key

//go:wasmexport rotate_vault_key
func rotateVaultKey() int32

Rotates the cryptographic keys within a vault enclave.

Multi-Chain Transaction Signing

sign_cosmos_transaction

//go:wasmexport sign_cosmos_transaction
func signCosmosTransaction() int32

Signs transactions for Cosmos SDK-based blockchains.

sign_evm_transaction

//go:wasmexport sign_evm_transaction
func signEvmTransaction() int32

Signs transactions for Ethereum Virtual Machine compatible chains.

sign_message

//go:wasmexport sign_message
func signMessage() int32

Signs arbitrary messages using the vault's private key.

Health and Monitoring

get_vault_health

//go:wasmexport get_vault_health
func getVaultHealth() int32

Returns the health status of a vault enclave.

Output: EnclaveHealth

{
  "vault_id": "string",
  "status": "string",
  "last_activity": "int64",
  "key_rotation_due": "bool",
  "attestation_valid": "bool"
}

Configuration

Environment Variables

Motor supports configuration through Extism variables:

• chain_id: Blockchain network identifier (default: "sonr-testnet-1")
• password: Default password for enclave operations (default: "password")
• gateway: IPFS gateway URL (default: "https://ipfs.did.run/ipfs/")

Access these via helper functions:

func GetChainID() string
func GetPassword() []byte
func GetGateway() string

IPFS Integration

Motor integrates with IPFS for secure vault backup and restore:

• Storage Endpoint: http://127.0.0.1:5001/api/v0/add
• Retrieval Endpoint: http://127.0.0.1:5001/api/v0/cat
• Data Format: Encrypted vault data stored as content-addressed objects
• Security: All vault data is encrypted before IPFS storage

Security Features

Enclave Isolation

• WebAssembly sandbox provides memory isolation
• Secure execution environment prevents side-channel attacks
• Attestation mechanisms ensure enclave integrity

Authentication

• WebAuthn support for passwordless authentication
• Challenge-response authentication flows
• Automatic vault locking with configurable timeouts

Key Management

• Multi-party computation for enhanced security
• Automatic key rotation with configurable intervals
• Secure key derivation and storage

Data Protection

• AES encryption for sensitive data
• Password-based encryption for import/export
• Secure memory handling within WASM environment

Usage Examples

Basic Enclave Operations

// Generate new enclave
const generateReq = { id: "my-vault" };
const result = call_wasm_function("generate", generateReq);

// Sign a message
const signReq = {
  message: new Uint8Array([1, 2, 3, 4]),
  enclave: result.data,
};
const signature = call_wasm_function("sign", signReq);

Vault Management

// Create vault with configuration
const config = {
  vault_id: "user-vault-001",
  webauthn_enabled: true,
  auto_lock_timeout: 300,
  supported_chains: ["cosmos", "ethereum"],
};
const vault = call_wasm_function("create_vault_enclave", config);

// Sign Cosmos transaction
const cosmosReq = {
  vault_id: "user-vault-001",
  chain_type: "cosmos",
  chain_id: "cosmoshub-4",
  message: transactionBytes,
};
const cosmosResult = call_wasm_function("sign_cosmos_transaction", cosmosReq);

Import/Export Operations

// Export vault to IPFS
const exportReq = {
  enclave: vaultData,
  password: new Uint8Array([
    /* password bytes */
  ]),
};
const exportResult = call_wasm_function("export", exportReq);
console.log("Vault exported to CID:", exportResult.cid);

// Import vault from IPFS
const importReq = {
  cid: "QmXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXx",
  password: new Uint8Array([
    /* password bytes */
  ]),
};
const importResult = call_wasm_function("import", importReq);

Building and Deployment

Prerequisites

• Go 1.24.4+
• Extism runtime
• IPFS node (for import/export functionality)

Build Commands

# Build WebAssembly module
GOOS=js GOARCH=wasm go build -o motr.wasm main.go

# Build via Makefile
make motr

Integration

Motor is designed to be integrated with:

• Highway Service: PostgreSQL-backed HTTP API
• Sonr Blockchain: Cosmos SDK-based blockchain node
• IPFS Network: Decentralized storage system
• WebAuthn Infrastructure: Passwordless authentication

Error Handling

All functions return int32 status codes:

• 0: Success
• 1: Error (details available via pdk.SetError)

Error information is logged using Extism's logging system:

pdk.Log(pdk.LogError, "Error message")
pdk.Log(pdk.LogInfo, "Info message")

Dependencies

Core Dependencies

• github.com/extism/go-pdk: WebAssembly plugin development kit
• github.com/sonr-io/sonr/crypto/mpc: Multi-party computation library

Cryptographic Libraries

• filippo.io/edwards25519: Edwards25519 elliptic curve
• github.com/btcsuite/btcd/btcec/v2: Bitcoin cryptography
• github.com/consensys/gnark-crypto: Zero-knowledge proof cryptography

License

Motor is part of the Sonr blockchain project. See the project's main license for terms and conditions.