Highway Service (hway)

Highway is a high-performance task processing service for Sonr's decentralized vault system. It provides asynchronous, durable execution of cryptographic operations using WebAssembly enclaves and Redis-backed job queues.

Overview

Highway acts as a distributed task processor that handles secure cryptographic operations for the Sonr blockchain ecosystem. It leverages:

• Asynq for reliable job queue management with Redis
• Proto.Actor for actor-based concurrency
• WebAssembly enclaves for secure cryptographic operations
• IPFS integration for decentralized storage

Quick Start

Prerequisites

• Redis server running on 127.0.0.1:6379
• Go 1.24.4 or later

Installation

# Build and install the Highway service
make install

# Or build directly
cd cmd/hway
go build -o hway .

Running the Service

# Start the Highway service
./hway

The service will connect to Redis and begin processing vault tasks with the following configuration:

• Concurrency: 10 workers
• Queue Priorities:
  • critical: 6 workers
  • default: 3 workers
  • low: 1 worker

Architecture

Highway implements a multi-layered architecture for secure task processing:

�����������������    ������������������    �����������������
   Task Queue    ����  Highway Service ����  Vault Actor    
   (Redis)              (Asynq)             (Proto.Actor)   
�����������������    ������������������    �����������������
                                                        
                                                        �
                                               �����������������
                                                 WASM Enclave   
                                                  (Extism)      
                                               �����������������

Core Components

1. Task Processing Layer (main.go)

   • Asynq server configuration
   • Task routing and worker management
   • Redis connection handling

2. Actor System (internal/vault/plugin/actor.go)

   • Proto.Actor based concurrency
   • Behavioral state management
   • Lifecycle management for WASM plugins

3. Plugin Interface (internal/vault/plugin/plugin.go)

   • WebAssembly plugin abstraction
   • Secure cryptographic operations
   • Type-safe method calls

4. Task Definitions (internal/vault/tasks/)

   • Task type definitions
   • Payload serialization
   • Task processing logic

Supported Operations

Highway supports the following cryptographic operations through its vault system:

Key Generation

// Generate a new cryptographic key pair
type GenerateRequest struct {
    ID string `json:"id"`
}

type GenerateResponse struct {
    Data      *mpc.EnclaveData `json:"data"`
    PublicKey []byte           `json:"public_key"`
}

Digital Signatures

// Sign a message
type SignRequest struct {
    Message []byte           `json:"message"`
    Enclave *mpc.EnclaveData `json:"enclave"`
}

type SignResponse struct {
    Signature []byte `json:"signature"`
}

Signature Verification

// Verify a signature
type VerifyRequest struct {
    PublicKey []byte `json:"public_key"`
    Message   []byte `json:"message"`
    Signature []byte `json:"signature"`
}

type VerifyResponse struct {
    Valid bool `json:"valid"`
}

Vault Management

Export to IPFS

type ExportRequest struct {
    Enclave  *mpc.EnclaveData `json:"enclave,omitempty"`
    Password []byte           `json:"password,omitempty"`
}

type ExportResponse struct {
    CID     string `json:"cid,omitempty"`
    Success bool   `json:"success"`
}

Import from IPFS

type ImportRequest struct {
    CID      string `json:"cid,omitempty"`
    Password []byte `json:"password,omitempty"`
}

type ImportResponse struct {
    Enclave *mpc.EnclaveData `json:"enclave,omitempty"`
    Success bool             `json:"success"`
}

Vault Refresh

type RefreshRequest struct {
    Enclave *mpc.EnclaveData `json:"enclave,omitempty"`
}

type RefreshResponse struct {
    Okay bool             `json:"okay"`
    Data *mpc.EnclaveData `json:"data,omitempty"`
}

Task Management

Creating Tasks

Tasks are created using the Asynq task creation utilities:

import "github.com/sonr-io/sonr/internal/vault/tasks"

// Create a vault generation task
task, err := tasks.NewVaultGenerateTask(userID)
if err != nil {
    return err
}

// Enqueue the task
client := asynq.NewClient(asynq.RedisClientOpt{Addr: "127.0.0.1:6379"})
info, err := client.Enqueue(task)

Task Types

Highway currently supports the following task types:

• vault:generate - Generate new cryptographic key pairs

Additional task types can be registered by:

1. Defining the task type constant in internal/vault/tasks/types.go
2. Creating appropriate payload and response structures
3. Implementing the task processor
4. Registering the handler in main.go

Configuration

Redis Configuration

Highway connects to Redis using the following default settings:

const redisAddr = "127.0.0.1:6379"

Worker Configuration

asynq.Config{
    Concurrency: 10,
    Queues: map[string]int{
        "critical": 6,  // High priority tasks
        "default":  3,  // Normal priority tasks
        "low":      1,  // Low priority tasks
    },
}

Actor System Configuration

const KRequestTimeout = 20 * time.Second

Security Model

Highway implements a multi-layered security approach:

1. WebAssembly Isolation: All cryptographic operations run in WASM enclaves
2. Actor Encapsulation: Each vault actor maintains isolated state
3. Encrypted Storage: Vault data is encrypted before IPFS storage
4. Password Protection: Additional password layer for import/export operations
5. Request Validation: All requests undergo validation before processing

Development

Adding New Task Types

1. Define the task type:

   // In internal/vault/tasks/types.go
   const TypeNewOperation = "vault:new_operation"

2. Create payload structures:

   type NewOperationPayload struct {
       Field1 string `json:"field1"`
       Field2 int    `json:"field2"`
   }
   
   func NewNewOperationTask(field1 string, field2 int) (*asynq.Task, error) {
       payload, err := json.Marshal(NewOperationPayload{
           Field1: field1,
           Field2: field2,
       })
       if err != nil {
           return nil, err
       }
       return asynq.NewTask(TypeNewOperation, payload), nil
   }

3. Implement the processor:

   func (processor *VaultProcessor) ProcessNewOperation(ctx context.Context, t *asynq.Task) error {
       var p NewOperationPayload
       if err := json.Unmarshal(t.Payload(), &p); err != nil {
           return fmt.Errorf("json.Unmarshal failed: %v: %w", err, asynq.SkipRetry)
       }
   
       // Process the task
       // ...
   
       return nil
   }

4. Register the handler:

   // In main.go
   mux.Handle(tasks.TypeNewOperation, tasks.NewVaultProcessor())

Testing

Highway includes comprehensive test suites for:

• Task processing logic
• Actor system behavior
• WASM plugin integration
• Redis queue operations

Run tests with:

make test-vaults

Monitoring and Observability

Highway provides detailed logging for:

• Task processing events
• Actor lifecycle management
• Plugin operation results
• Error conditions and recovery

All logs use structured logging with slog for consistent formatting and filtering.

Performance Considerations

• Concurrency: Adjust worker count based on CPU cores and workload
• Queue Priorities: Balance task priorities according to business requirements
• Redis Memory Usage: Monitor Redis memory consumption with large task volumes
• WASM Performance: Plugin operations are CPU-intensive; size workers accordingly

Troubleshooting

Common Issues

Redis Connection Failed

could not run server: dial tcp 127.0.0.1:6379: connect: connection refused

• Ensure Redis server is running on the configured address
• Check Redis configuration and network connectivity

Plugin Load Failed

failed to create enclave host: plugin load error

• Verify WASM plugin file exists and is accessible
• Check plugin manifest configuration
• Review Extism runtime requirements

Actor Initialization Failed

Enclave actor failed to start

• Review plugin loading prerequisites
• Check system memory and resource availability
• Verify Proto.Actor system configuration

Related Documentation

• Sonr Blockchain Documentation
• Motor WASM Plugin