Core Functionalities

This section details Khedra's primary technical functionalities, explaining how each core feature is implemented and the technical approaches used.

Control Service

Service Management Interface

The Control Service exposes a minimal HTTP interface for pausing and unpausing supported services (scraper, monitor) and for reporting their pause status.

Technical Implementation

Implemented functions:

Pause a pausable service
Unpause a pausable service
Report paused / running status

Scope: does not provide start/stop/restart, runtime config mutation, or metrics collection.

// Simplified Control Service interface
type ControlService struct {
    serviceManager *ServiceManager
    httpServer     *http.Server
    logger         *slog.Logger
}

type ServiceStatus struct {
    Name        string
    State       ServiceState
    LastStarted time.Time
    Uptime      time.Duration
    Metrics     map[string]interface{}
}

type ServiceState int
const (
    StateStopped ServiceState = iota
    StateStarting
    StateRunning
    StatePausing
    StatePaused
    StateStopping
)

Management Endpoints (Implemented)

GET /isPaused — status for all services
GET /isPaused?name={service} — status for one service
GET /pause?name={service|all} — pause service(s)
GET /unpause?name={service|all} — unpause service(s)

Mutating operations currently use GET.

Pausable Services

Only services implementing the Pauser interface can be paused:

Scraper: Blockchain indexing service (pausable)
Monitor: Address monitoring service (pausable)

Non‑pausable services: control, api, ipfs (if enabled). The monitor service is disabled by default but is pausable when enabled.

Service Coordination

Coordination is limited to toggling internal paused state.

Blockchain Indexing

The Unchained Index (High-Level Overview)

The Unchained Index implementation resides in upstream TrueBlocks libraries. This repository configures and invokes indexing.

Technical Implementation

The index is implemented as a specialized data structure with these key characteristics:

Bloom Filter Front-End: A probabilistic data structure that quickly determines if an address might appear in a block
Address-to-Appearance Mapping: Maps each address to a list of its appearances
Chunked Storage: Divides the index into manageable chunks (typically 1,000,000 blocks per chunk)
Versioned Format: Includes version metadata to handle format evolution

Internal storage specifics are handled upstream and not duplicated here.

Indexing Process (Conceptual)

High level only: batches of blocks are processed, appearances extracted, and persisted through the underlying TrueBlocks indexing subsystem; batch size and sleep are configured in config.yaml.

Performance Optimizations

Parallel Processing: Multiple blocks processed concurrently
Bloom Filters: Fast negative lookups to avoid unnecessary disk access
Binary Encoding: Compact storage format for index data
Caching: Frequently accessed index portions kept in memory

Address Monitoring (Experimental / Limited)

Monitor Implementation

The monitoring system currently provides service enablement/disablement and pause control; advanced notification features are outside this repository.

Technical Implementation

Monitors are implemented using these components:

Monitor Registry: Central store of all monitored addresses
Address Index: Fast lookup structure for monitored addresses
Activity Tracker: Records and timestamps address activity
Notification Manager: Handles alert distribution based on configuration

Implementation structs are managed upstream.

Monitoring Process

Registration: Add addresses to the monitor registry
Block Processing: As new blocks are processed, check for monitored addresses
Activity Detection: When a monitored address appears, record the activity
Notification: Based on configuration, send notifications via configured channels
State Update: Update the monitor's state with the new activity