• KERI wallets focus on the foundational layer of storing cryptographic keys and maintaining key event logs for AID management
• ACDC wallets extend this foundation with emphasis on storing verifiable credentials and managing credential presentation workflows

This layered approach reflects KERI's modular design philosophy, where core identifier management (KERI) provides the trust basis for higher-level credential operations (ACDC).

Key Features & Capabilities

Storage Capabilities

KERI wallets provide comprehensive storage for:

• Private keys: Encrypted storage of signing and encryption keys
• Public keys: Associated public key material for verification
• Key event logs (KELs): Complete history of key state changes
• Key event receipt logs (KERLs): Witnessed versions of KELs with receipt signatures
• Hashes and pointers: Cryptographic digests and references to external data
• ACDC credentials: Verifiable credentials in Authentic Chained Data Container format
• Schemas: JSON schemas defining credential structures
• Metadata: Associated data for identifiers, credentials, and relationships

Agency Functionality

Beyond passive storage, KERI wallets provide agency - active functional capabilities including:

• Cryptographic signing: Generating digital signatures for key events and credentials
• Invoicing (receiving): Accepting incoming credentials and messages
• Sending: Transmitting credentials and establishing connections
• Virtual credential management: Issuing, presenting, and verifying ACDCs
• Delegation handling: Managing delegated identifiers and authority chains
• OOBI resolution: Discovering and verifying out-of-band introductions
• Witness coordination: Interacting with witness pools for key event receipting

Security Architecture

Encryption at Rest: All sensitive data in KERI wallets is encrypted using passcodes or other authentication mechanisms. The default encryption approach uses password-based key derivation to protect the keystore and associated databases.

Separation of Concerns: By maintaining separate databases for keys, events, and credentials, KERI wallets enable:

• Different security policies for different data types
• Optimized backup and recovery strategies
• Granular access control for different wallet operations
• Reduced attack surface through data isolation

Multi-signature Support: KERI wallets support multi-signature configurations where multiple key pairs must cooperate to authorize operations, enabling:

• Threshold signature schemes (e.g., 2-of-3 signatures required)
• Weighted multi-sig with fractional voting power
• Group identifiers with distributed control

Installation & Setup

Sparán Desktop Wallet

Sparán is the reference GUI wallet implementation for KERI, providing a graphical alternative to the command-line kli tool.

Prerequisites:

• macOS, Windows, or Linux operating system
• Python 3.10 or higher
• uv package manager (installed via curl -LsSf https://astral.sh/uv/install.sh | sh)

Installation:

# Clone the repository
git clone https://github.com/keri-foundation/wallet.git
cd wallet

# Setup dependencies
make setup

# Run the wallet
uv run flet run main.py

Development Mode:

export WALLET_ENVIRONMENT=development
uv run flet run main.py
# Or use the convenience command:
make dev

Required Services:

Before running Sparán, two supporting services must be started:

1. Witness Pool (from KERIpy repository):

kli witness demo

This starts a sample set of six witnesses for testing.

2. vLEI Server (from vLEI repository):

vLEI-server -s ./schema/acdc -c ./samples/acdc/ -o ./samples/oobis/

This serves ACDC credential schemas and sample credentials.

Environment Configuration:

Sparán supports multiple deployment environments through the WALLET_ENVIRONMENT variable:

• production: Production GLEIF infrastructure
• staging: Staging environment for testing
• development: Local development with test witnesses

Configuration files are located in src/app/config/ with environment-specific settings for witness endpoints, schema servers, and network parameters.

Browser-Based Wallets

Signify Browser Extension (in development) will provide browser-integrated wallet functionality:

• Management of KERI AIDs directly in the browser
• User approval workflows for signing operations
• Consent mechanisms for credential exchanges
• Integration with web applications via browser extension APIs

KERIMask (planned) aims to provide MetaMask-like functionality for KERI:

• Browser extension architecture
• Connection to KERIA servers
• AID control from the browser interface

Mobile Wallets

Veridian Wallet (Cardano Foundation):

• Native Android and iOS applications
• Mobile-optimized identifier management
• Credential presentation workflows
• Integration with mobile biometric authentication

Command-Line Interface

The KERI Command Line Interface (kli) provides wallet functionality through terminal commands:

# Create a new wallet (habitat)
kli init --name alice --passcode 0123456789abcdefghijk

# Create an AID
kli incept --name alice --alias alice-aid

# List identifiers in wallet
kli status --name alice

# Export wallet data
kli export --name alice --output alice-backup.json

The --name parameter references a named Habitat (conceptually similar to a wallet) for performing operations, allowing management of multiple identifier contexts.

Usage & API

KERIA Agent API

KERIA (KERI Agent in the cloud) exposes wallet functionality through three HTTP interfaces:

1. Boot Interface: Agent worker initialization

POST /boot
Content-Type: application/json

{
  "name": "agent-name",
  "passcode": "secure-passcode",
  "salt": "random-salt-value"
}

2. Admin Interface: REST API for wallet operations

# Create identifier
POST /identifiers
Content-Type: application/json
Signature-Input: ...

{
  "name": "my-identifier",
  "wits": ["witness-1-oobi", "witness-2-oobi"],
  "toad": 2
}

# List credentials
GET /credentials
Signature-Input: ...

# Present credential
POST /presentations
Content-Type: application/json
Signature-Input: ...

{
  "credential": "credential-said",
  "recipient": "verifier-aid"
}

3. KERI Protocol Interface: CESR over HTTP for protocol interactions

POST /
Content-Type: application/cesr+json

{CESR-encoded key event or receipt}

SignifyPy Client Library

SignifyPy provides Python bindings for interacting with KERIA agents:

from signify.app.clienting import SignifyClient

# Initialize client
client = SignifyClient(passcode="secure-passcode", tier="low")

# Boot agent
await client.boot()

# Create identifier
aid = await client.identifiers().create(
    name="my-identifier",
    wits=["witness-oobi-1", "witness-oobi-2"],
    toad=2
)

# Issue credential
credential = await client.credentials().issue(
    issuer=aid["prefix"],
    schema="schema-said",
    data={"LEI": "123456789012345678"},
    recipient="recipient-aid"
)

# List credentials
creds = await client.credentials().list()

# Present credential
await client.ipex().present(
    credential=credential["sad"]["d"],
    recipient="verifier-aid"
)

SignifyTS Client Library

SignifyTS provides TypeScript/JavaScript bindings:

import { Signify } from 'signify-ts';

// Initialize client
const client = new Signify();
await client.boot();
await client.connect(
  'http://localhost:3901',
  'my-passcode',
  Tier.low
);

// Create identifier
const result = await client.identifiers().create('my-aid', {
  wits: ['witness-oobi-1', 'witness-oobi-2'],
  toad: 2
});

// Issue credential
const credential = await client.credentials().issue({
  issuer: result.prefix,
  schema: 'schema-said',
  data: { LEI: '123456789012345678' },
  recipient: 'recipient-aid'
});

// Present credential
await client.ipex().present(
  credential.sad.d,
  'verifier-aid'
);

Wallet Data Structures

KERI wallets store data in structured formats:

Keystore Structure (encrypted LMDB database):

/usr/local/var/keri/
  ks/
    {wallet-name}/
      key.db      # Encrypted private keys
      db/         # Key event logs
      reg/        # Credential registries
      esc/        # Escrow databases

Habitat Configuration:

{
  "name": "alice",
  "salt": "0AAkG1BmB7xnXBxo2Aasxrq9",
  "pidx": 0,
  "tier": "low",
  "temp": false
}

Related Implementations

Python Ecosystem

KERIpy (reference implementation):

• Core KERI protocol in Python
• kli command-line interface
• LMDB-based keystore
• Full KERI, ACDC, and CESR support

KERIA (cloud agent):

• Multi-tenant agent server
• REST API for wallet operations
• Built on KERIpy foundation
• Supports remote key management

SignifyPy (client library):

• Python client for KERIA
• Async/await API design
• Credential issuance and presentation
• IPEX protocol support

TypeScript/JavaScript Ecosystem

SignifyTS (client library):

• TypeScript/JavaScript client for KERIA
• Browser and Node.js compatible
• Promise-based API
• Full IPEX support

Signify Browser Extension (in development):

• Browser-integrated wallet
• Web application integration
• User consent workflows

Rust Ecosystem

KERIox (Rust implementation):

• Rust-based KERI protocol
• Performance-optimized
• Memory-safe implementation
• Alternative to KERIpy

Mobile Ecosystem

Veridian Wallet (Cardano Foundation):

• Native iOS and Android apps
• Mobile-optimized UX
• Biometric authentication
• QR code scanning for OOBIs

KERIml (Swift implementation):

• iOS-native KERI protocol
• Swift language implementation
• Mobile wallet foundation

Desktop GUI

Sparán (KERI Foundation):

• Cross-platform desktop wallet
• Flet/Flutter-based UI
• Local identifier management
• Alternative to command-line tools

Implementation Notes

Security Considerations

Passcode Strength: Wallet encryption relies on user-provided passcodes. Implementations should:

• Enforce minimum passcode length (recommended: 20+ characters)
• Support key stretching (PBKDF2, Argon2)
• Provide entropy estimation feedback
• Enable hardware security module (HSM) integration

Key Rotation: Wallets must support KERI's pre-rotation mechanism:

• Store next key digests securely
• Maintain rotation history in KEL
• Support partial rotation for custodial scenarios
• Enable reserve rotation for enhanced security

Backup and Recovery: Critical wallet data includes:

• Encrypted keystore (contains private keys)
• Salt values (for key derivation)
• KEL databases (event history)
• Credential databases (issued/received ACDCs)

Backup strategies should consider:

• Encrypted backup files
• Multi-device synchronization
• Recovery seed phrases (BIP-39 compatible)
• Social recovery mechanisms

Multi-Signature Wallets

KERI wallets support sophisticated multi-signature configurations:

Threshold Signatures:

{
  "kt": "2",  // Current threshold: 2 signatures required
  "k": ["key1", "key2", "key3"],  // 3 signing keys
  "nt": "2",  // Next threshold
  "n": ["digest1", "digest2", "digest3"]  // Next key digests
}

Weighted Multi-Sig:

{
  "kt": ["1/2", "1/2", "1/2"],  // Fractional weights
  "k": ["key1", "key2", "key3"],
  "nt": ["1/2", "1/2", "1/2"],
  "n": ["digest1", "digest2", "digest3"]
}

Custodial vs Non-Custodial

Non-Custodial Wallets:

• User maintains direct control of private keys
• Keys stored on user's device
• User responsible for backup and recovery
• Examples: Sparán, Veridian, browser extensions

Custodial Wallets:

• Third party holds private keys
• KERIA agents can provide custodial services
• Partial rotation enables custodial signing with user rotation authority
• User retains ultimate control through rotation keys

Witness Integration

Wallets must coordinate with witness pools:

Witness Configuration:

# Configure witnesses during AID creation
await client.identifiers().create(
    name="my-aid",
    wits=[
        "http://witness1.example.com/oobi/witness1-aid",
        "http://witness2.example.com/oobi/witness2-aid",
        "http://witness3.example.com/oobi/witness3-aid"
    ],
    toad=2  # Threshold of accountable duplicity
)

Witness Rotation:

# Rotate witness pool
await client.identifiers().rotate(
    name="my-aid",
    wits=[
        "http://witness4.example.com/oobi/witness4-aid",
        "http://witness5.example.com/oobi/witness5-aid"
    ],
    toad=1
)

Credential Management

Wallets handle complete credential lifecycles:

Issuance:

1. Create credential data structure
2. Generate SAID for credential
3. Sign credential with issuer AID
4. Anchor to issuer's KEL via interaction event
5. Register in transaction event log (TEL)
6. Transmit to holder via IPEX

Presentation:

1. Receive presentation request
2. Select matching credentials
3. Apply selective disclosure (if supported)
4. Generate presentation ACDC
5. Sign presentation
6. Transmit to verifier via IPEX

Verification:

1. Receive presentation
2. Verify ACDC structure and SAID
3. Verify issuer signatures
4. Check issuer AID key state
5. Verify credential status in TEL
6. Validate schema compliance
7. Check presentation signatures

Performance Optimization

Database Indexing: Wallets should index:

• AIDs by alias and prefix
• Credentials by schema, issuer, and issuee
• Key events by sequence number
• Witnesses by AID

Caching Strategies:

• Cache resolved OOBIs
• Cache verified key states
• Cache credential schemas
• Cache witness endpoints

Batch Operations:

• Batch witness queries
• Batch credential verifications
• Batch OOBI resolutions

Interoperability

KERI wallets should support:

Standard Formats:

• CESR encoding for all primitives
• JSON serialization for ACDCs
• CBOR for compact transmission
• MessagePack for efficient storage

Protocol Support:

• KERI protocol (key events, receipts)
• ACDC protocol (credentials)
• IPEX protocol (issuance/presentation)
• OOBI protocol (discovery)

DID Methods:

• did:keri for KERI-native DIDs
• did:webs for web-based KERI DIDs
• did:web for traditional web DIDs

Testing and Development

Test Environments:

• Local witness pools (kli witness demo)
• Test schema servers
• Mock credential issuers
• Simulated verifiers

Development Tools:

• kli for command-line testing
• KERIA for agent testing
• Signify clients for integration testing
• Browser developer tools for extension testing

Credential Lifecycle Management

Issuance Workflow:

1. Validate credential schema
2. Generate SAID for credential
3. Create anchoring interaction event
4. Register in TEL
5. Transmit via IPEX
6. Store in credential database

Presentation Workflow:

1. Receive presentation request
2. Match credentials to request
3. Apply selective disclosure if needed
4. Generate presentation ACDC
5. Sign with holder AID
6. Transmit to verifier

Verification Workflow:

1. Verify ACDC structure
2. Validate SAID integrity
3. Check issuer signatures
4. Verify issuer key state
5. Check TEL status
6. Validate schema compliance

Performance Optimization

Caching Strategy:

• Cache resolved OOBIs (24-hour TTL recommended)
• Cache verified key states (invalidate on rotation)
• Cache credential schemas (long TTL)
• Cache witness endpoints (update on rotation)

Indexing Requirements:

• Index AIDs by prefix and alias
• Index credentials by schema SAID
• Index credentials by issuer AID
• Index key events by sequence number
• Index witnesses by AID

Batch Operations:

• Batch witness queries to reduce network overhead
• Batch credential verifications
• Batch OOBI resolutions
• Use connection pooling for HTTP requests

Interoperability Standards

Encoding Support:

• CESR for all cryptographic primitives
• JSON for ACDC credentials
• CBOR for compact transmission
• MessagePack for efficient storage

Protocol Compliance:

• Full KERI protocol support (inception, rotation, interaction)
• ACDC protocol for credentials
• IPEX protocol for issuance/presentation
• OOBI protocol for discovery

DID Method Support:

• did:keri for native KERI identifiers
• did:webs for web-based KERI identifiers
• did:web for traditional web DIDs

Error Handling

Key Event Validation:

• Verify event signatures
• Check sequence number continuity
• Validate digest chains
• Detect duplicity

Credential Validation:

• Verify SAID integrity
• Check schema compliance
• Validate issuer signatures
• Verify TEL status

Network Resilience:

• Implement retry logic with exponential backoff
• Handle witness unavailability
• Queue operations during network outages
• Provide offline mode for read operations

Testing Requirements

Unit Tests:

• Key generation and storage
• Event signing and verification
• Credential issuance and presentation
• Database operations

Integration Tests:

• Witness coordination
• OOBI resolution
• Multi-signature workflows
• Credential lifecycle

End-to-End Tests:

• Complete issuance workflows
• Presentation exchanges
• Multi-party scenarios
• Error recovery

Platform-Specific Considerations

Desktop (Sparán):

• Use native file system for database storage
• Integrate with OS keychain for passcode storage
• Support multiple wallet profiles
• Provide backup/restore UI

Browser Extensions:

• Use browser storage APIs (IndexedDB)
• Implement content script injection
• Handle cross-origin requests
• Provide user consent workflows

Mobile (Veridian):

• Use secure enclave for key storage
• Integrate biometric authentication
• Optimize for battery life
• Support QR code scanning for OOBIs

Cloud Agents (KERIA):

• Implement multi-tenancy
• Use database per agent
• Provide REST API
• Support webhook notifications