# Core Platform

The Core Platform is the operational heart of Vilna, providing real-time blockchain monitoring, wallet generation, and comprehensive data analytics. It serves as the foundation for building any crypto-related application - from simple payment processors to complex DeFi platforms.

## Purpose and Capabilities

The Core Platform solves fundamental challenges in blockchain integration:

- **Wallet Management**: Generate and organize millions of addresses from a single xPub key
- **Real-time Monitoring**: Track blockchain activity across multiple networks simultaneously
- **Data Access**: Query historical transactions and current balances instantly
- **Event Notifications**: Receive alerts when specific blockchain events occur


## Architecture Components


```mermaid
graph TB
    subgraph "Input Layer"
        XPUB[xPub Keys]
        ADDR[Individual Addresses]
        IMPORT[Bulk Import]
    end
    
    subgraph "Processing Core"
        GEN[Address Generator]
        MON[Blockchain Monitor]
        INDEX[Data Indexer]
        CACHE[Balance Cache]
    end
    
    subgraph "Output Layer"
        WEBHOOK[Webhooks]
        API[REST API]
        EMAIL[Email Alerts]
        WS[WebSocket]
    end
    
    XPUB --> GEN
    GEN --> MON
    ADDR --> MON
    IMPORT --> MON
    MON --> INDEX
    INDEX --> CACHE
    INDEX --> WEBHOOK
    CACHE --> API
    INDEX --> EMAIL
    CACHE --> WS
```

## Real-World Use Cases

### Cryptocurrency Exchange

Exchanges need to manage millions of user deposit addresses while tracking all incoming transactions:


```mermaid
sequenceDiagram
    participant User
    participant Exchange
    participant Vilna
    participant Blockchain
    
    User->>Exchange: Request deposit address
    Exchange->>Vilna: Generate new address
    Vilna->>Exchange: Return unique address
    Exchange->>User: Display deposit address
    
    User->>Blockchain: Send funds
    Blockchain->>Vilna: Transaction detected
    Vilna->>Exchange: Webhook notification
    Exchange->>Exchange: Credit user account
```

**Implementation approach:**

1. Import exchange's xPub key using [`POST /xpubs`](/apis/spec#operation/createXpub)
2. Generate unique addresses per user with [`POST /addresses/generate/xpub/next`](/apis/spec#operation/generateNextAddress)
3. Set up webhook notifications for incoming transactions
4. Process deposits automatically when confirmations reach threshold


### Crypto Payment Gateway

Payment processors need to create unique addresses for each invoice and verify payments:

**Key requirements:**

- Generate payment addresses on demand
- Monitor for exact payment amounts
- Handle partial payments and overpayments
- Support multiple cryptocurrencies


**Solution with Vilna:**

- Use address generation API to create unique payment addresses
- Configure webhooks to receive payment notifications
- Query balance API to verify payment amounts
- Track transaction history for reconciliation


### DeFi Portfolio Tracker

DeFi platforms need to aggregate user positions across multiple protocols:

**Monitoring requirements:**

- Track user wallet balances across chains
- Monitor liquidity pool positions
- Calculate total portfolio value
- Detect DeFi protocol interactions


**Vilna enables:**

- Bulk import user addresses for monitoring
- Real-time balance tracking across all supported tokens
- Historical data for portfolio performance analysis
- Event notifications for position changes


## Core Functionalities

### Address Generation

Generate HD wallet addresses following BIP32/44/84 standards. The system maintains:

- Sequential address generation with gap limit handling
- Address labeling and metadata storage
- Automatic monitoring of all generated addresses
- Support for multiple derivation paths


Relevant API endpoints:

- [`POST /xpubs`](/apis/spec#operation/createXpub) - Import xPub keys
- [`POST /addresses/generate/xpub/next`](/apis/spec#operation/generateNextAddress) - Generate next address
- [`GET /addresses`](/apis/spec#operation/getAddresses) - List all addresses


### Blockchain Monitoring

The monitoring engine continuously scans multiple blockchains for activity on tracked addresses:

**Supported networks:**

- EVM chains (Ethereum, BSC, Polygon, Arbitrum, Optimism)
- Bitcoin and Bitcoin-compatible chains
- Layer 2 solutions
- Alternative chains (Solana, TON, etc.)


**Monitoring capabilities:**

- Transaction detection (pending and confirmed)
- Token transfers (ERC-20, BEP-20, SPL)
- NFT movements
- Smart contract interactions
- Internal transactions


### Notification System

Configure real-time alerts for blockchain events:

**Webhook notifications:**

- HTTP POST requests to your endpoints
- HMAC signature for security
- Automatic retry with exponential backoff
- Delivery status tracking


**Email alerts:**

- Customizable templates
- Threshold-based triggers
- Daily summary reports
- Critical event notifications


**Event types:**

- `transaction.pending` - Unconfirmed transaction detected
- `transaction.confirmed` - Transaction reached confirmation threshold
- `balance.changed` - Address balance updated
- `token.received` - ERC-20/BEP-20 token transfer detected


### Data Analytics

Access comprehensive blockchain data through the API:

**Balance queries:**

- Current balance per address
- Multi-token balance aggregation
- USD value calculation
- Balance history snapshots


**Transaction history:**

- Complete transaction records
- Advanced filtering options
- Token transfer details
- Gas usage analytics


Relevant API endpoints:

- [`GET /addresses/{address}/balances`](/apis/spec#operation/getAddressBalances) - Get current balances
- [`GET /transactions`](/apis/spec#operation/getTransactions) - Query transaction history


## Integration Patterns

### High-Volume Processing

For applications handling thousands of addresses:

1. Use bulk import for existing addresses
2. Implement webhook queuing for high-volume notifications
3. Cache balance data locally with periodic updates
4. Use pagination for large data queries


### Security Considerations

- **No private keys**: Core Platform operates in watch-only mode
- **HMAC verification**: Validate all webhook signatures
- **Rate limiting**: Implement appropriate throttling
- **Idempotency**: Handle duplicate notifications gracefully


### Performance Optimization

- **Batch operations**: Group multiple requests when possible
- **Webhook filtering**: Subscribe only to needed events
- **Local caching**: Store frequently accessed data
- **Efficient querying**: Use appropriate filters and pagination


## Comparison with Alternatives

### vs. Running Your Own Node

**Advantages:**

- No infrastructure maintenance required
- Multi-chain support without multiple nodes
- Built-in notification system
- Automatic token discovery


**When to use Vilna:**

- Need multi-chain support
- Want to focus on business logic
- Require reliable uptime without DevOps overhead


### vs. Other Blockchain APIs

**Unique features:**

- xPub-based address generation
- Unified API across all blockchains
- Custom notification rules
- Enterprise-grade reliability


## Getting Started

1. **Define your requirements**: Identify which blockchains and events you need to monitor
2. **Import addresses**: Use xPub keys for new addresses or bulk import existing ones
3. **Configure notifications**: Set up webhooks or email alerts for relevant events
4. **Integrate API**: Use the REST API for balance and transaction queries


For implementation details, refer to:

- [Quick Start Guide](/guides/quickstart) - Step-by-step setup instructions
- [API Reference](/apis/spec) - Complete API documentation
- [Notification Channels](/guides/channels) - Webhook and email configuration


## Next Steps

- [Architecture Overview](/guides/architecture-overview) - Understand the complete platform
- [Transaction Processing](/guides/transactions) - Learn about transaction creation and signing
- [MPC Key Management](/guides/mpc) - Explore advanced security options