# How Vilna Works

Vilna provides a comprehensive platform for enterprise-grade crypto asset management, combining cutting-edge security with powerful monitoring capabilities. The platform consists of three interconnected modules that work together to provide complete control over digital assets.

## Platform Architecture


```mermaid
graph TB
    subgraph "Module 1: MPC Key Management (Optional)"
        KG[Key Generation with CGGMP]
        SHARD[Key Shards Distribution]
        MPC[MPC Infrastructure]
        XPUB_MPC[Extended Public Key Export]
    end
    
    subgraph "External Sources"
        XPUB_EXT[Existing xPub Keys<br/>Hardware Wallets<br/>Software Wallets<br/>Third-party Services]
    end
    
    subgraph "Module 2: Vilna Core"
        MON[Address Monitoring]
        GEN[Wallet Generation]
        NOT[Real-time Notifications]
        HIST[Transaction History]
        BAL[Balance Tracking]
    end
    
    subgraph "Module 3: Transaction Processing"
        INIT[Transaction Initiation]
        SIM[Transaction Simulation]
        SIGN[Secure Signing]
        BROAD[Broadcasting]
    end
    
    KG --> SHARD
    SHARD --> MPC
    MPC --> XPUB_MPC
    XPUB_MPC --> GEN
    XPUB_EXT --> GEN
    GEN --> MON
    MON --> NOT
    MON --> HIST
    MON --> BAL
    BAL --> INIT
    INIT --> SIM
    SIM --> SIGN
    SIGN --> BROAD
```

**Key Integration Flexibility**: Vilna supports multiple approaches for key management. While Module 1 provides enterprise-grade MPC key generation and management, you can also import existing xPub keys from any source - hardware wallets (Ledger, Trezor), software wallets, or third-party custody services. This flexibility allows organizations to integrate Vilna with their existing infrastructure while maintaining the option to upgrade to MPC-based security when needed.

## Module 1: MPC Key Management

### Secure Key Generation with Sharding

Vilna implements the CGGMP (Canetti-Gennaro-Goldfeder-Makriyannis-Peled) algorithm for threshold signature generation, providing institutional-grade security for private key management.


```mermaid
graph LR
    subgraph "Key Generation Process"
        A[Initialize CGGMP Protocol] --> B[Generate Key Shards]
        B --> C[Distribute to Parties]
        C --> D[Derive xPub Key]
        D --> E[Import to Vilna]
    end
```

**Key Features:**

- **Distributed Key Generation**: Private keys are never assembled in one place
- **Threshold Signatures**: Require m-of-n parties to sign transactions
- **No Single Point of Failure**: Key shards stored across multiple secure locations
- **MPC Infrastructure**: Vilna provides secure communication channels between shards


**Use Cases:**

- Institutional custody solutions
- Multi-party wallet management
- High-security collection operations
- Regulatory compliance requirements


## Module 2: Vilna Core Platform

### Comprehensive Asset Monitoring and Management

The core Vilna platform provides real-time blockchain monitoring, wallet generation, and comprehensive data analytics.


```mermaid
graph LR
    subgraph "Your Input"
        XPUB[Extended Public Keys]
        ADDR[Individual Addresses]
    end
    
    subgraph "Vilna Services"
        MON[24/7 Monitoring]
        GEN[Address Generation]
        ALERT[Alert System]
        DATA[Data Analytics]
    end
    
    subgraph "Your Access"
        API[REST API]
        WEB[Web Dashboard]
        WH[Webhooks]
        EMAIL[Email Alerts]
    end
    
    XPUB --> GEN
    ADDR --> MON
    GEN --> MON
    MON --> ALERT
    MON --> DATA
    ALERT --> WH
    ALERT --> EMAIL
    DATA --> API
    DATA --> WEB
```

**Core Capabilities:**

### Wallet Generation

- Generate unlimited addresses from xPub keys
- Support for multiple blockchain networks
- HD wallet standards compliance (BIP32/44/84)
- Automatic address indexing and tracking


### Real-time Monitoring

- 24/7 blockchain monitoring
- Instant detection of incoming/outgoing transactions
- Multi-chain support
- Custom alert thresholds


### Notifications & Alerts

- Webhook notifications for system integration
- Email alerts for critical events
- Customizable notification rules
- Real-time push notifications


### Data & Analytics

- Complete transaction history
- Real-time balance tracking
- Advanced filtering and search
- Export capabilities for reporting


## Module 3: Transaction Processing & Signing

### Secure Transaction Management

Vilna's transaction module provides a secure, hardware-wallet-like experience for initiating and signing transactions, with advanced simulation capabilities.


```mermaid
sequenceDiagram
    participant User
    participant Vilna
    participant Device
    participant Blockchain
    
    User->>Vilna: Initiate Transaction
    Vilna->>Vilna: Build Transaction
    Vilna->>User: Transaction Simulation
    User->>User: Review Simulation
    User->>Vilna: Confirm Intent
    Vilna->>Device: Send Raw Transaction
    Device->>Device: Sign with Key Shard
    Device->>Vilna: Return Signature
    Vilna->>Blockchain: Broadcast Transaction
    Blockchain->>Vilna: Confirmation
    Vilna->>User: Transaction Complete
```

**Transaction Types:**

- **Simple Transfers**: Send assets to addresses
- **Swap Operations**: Exchange between tokens
- **Smart Contract Interactions**: DeFi operations
- **Batch Transactions**: Multiple operations in one transaction


**Security Features:**

- **Transaction Simulation**: Preview exactly what will happen before signing
- **Secure Transport**: Encrypted communication channels
- **Hardware-like Security**: Similar to Ledger/Trezor cold wallet approach
- **Multi-signature Support**: Require multiple approvals for high-value transactions


**Simulation Details:**
Before any transaction is signed, Vilna provides:

- Exact gas/fee calculations
- Balance changes preview
- Smart contract effects visualization
- Risk assessment and warnings
- Approval requirements display


## Integration Scenarios

### Scenario 1: Exchange Platform


```
1. Generate deposit addresses for users (Module 2)
2. Monitor all addresses for deposits (Module 2)
3. Aggregate funds to hot wallet (Module 3)
4. Process withdrawals with MPC signing (Modules 1 & 3)
```

### Scenario 2: Corporate Fund Management


```
1. Create multi-sig collection system with CGGMP (Module 1)
2. Track all corporate wallets (Module 2)
3. Execute approved transactions (Module 3)
4. Generate compliance reports (Module 2)
```

### Scenario 3: Payment Processor


```
1. Generate unique invoice addresses (Module 2)
2. Monitor for customer payments (Module 2)
3. Automatic settlement processing (Module 3)
4. Real-time payment notifications (Module 2)
```

## Getting Started

### Step 1: Key Management Setup

Choose your key management approach:

- **MPC Setup**: Initialize CGGMP protocol for maximum security (Module 1)
- **Import Existing xPub**: Use extended public keys from hardware wallets, software wallets, or any other source
- **Add Individual Addresses**: Monitor existing blockchain addresses without xPub


### Step 2: Configure Monitoring

- Set up notification channels (webhooks, email)
- Configure alert thresholds
- Define monitoring rules


### Step 3: Transaction Processing

- Set up signing devices/services
- Configure transaction policies
- Test with simulation mode


## Security Architecture


```mermaid
graph TD
    subgraph "Security Layers"
        L1[MPC Key Sharding - Never expose full private key]
        L2[Encrypted Communication - All data in transit encrypted]
        L3[Transaction Simulation - Preview before signing]
        L4[Multi-signature Support - Multiple approvals required]
        L5[Audit Logging - Complete transaction history]
    end
    
    L1 --> L2
    L2 --> L3
    L3 --> L4
    L4 --> L5
```

## API Integration

All three modules are accessible through our unified REST API:


```http
# Module 1: MPC Operations
POST /api/v1/mpc/initialize
GET  /api/v1/mpc/status

# Module 2: Core Platform
POST /api/v1/wallets/generate
GET  /api/v1/addresses/{address}/balance
GET  /api/v1/addresses/{address}/transactions
POST /api/v1/webhooks/configure

# Module 3: Transaction Processing
POST /api/v1/transactions/create
POST /api/v1/transactions/simulate
POST /api/v1/transactions/sign
POST /api/v1/transactions/broadcast
```

## Next Steps

- [Quick Start Guide](/guides/quickstart) - Get up and running in minutes
- [API Reference](/apis/spec) - Complete API documentation
- [Notification Channels](/guides/channels) - Configure alerts and webhooks