go/sonr
1
0
Fork 0
mirror of https://github.com/sonr-io/sonr.git synced 2026-08-02 17:31:39 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: remove hway documentation

Browse Source
This commit is contained in:
Prad Nukala
2025-10-21 12:30:42 -04:00
parent c49fead1d8
commit 3769d11f9f
2 changed files with 0 additions and 380 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/reference/concepts/hway.mdx
-375
View File
@@ -1,375 +0,0 @@
---
title: "Highway Service"
sidebarTitle: "Hway Overview"
description: "High-performance task processing service for Sonr's decentralized vault system"
icon: "play"
---
# 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
```bash
# Build and install the Highway service
make install
# Or build directly
cd cmd/hway
go build -o hway .
```
### Running the Service
```bash
# 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
```go
// 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
```go
// Sign a message
type SignRequest struct {
Message []byte `json:"message"`
Enclave *mpc.EnclaveData `json:"enclave"`
}
type SignResponse struct {
Signature []byte `json:"signature"`
}
```
### Signature Verification
```go
// 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
```go
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
```go
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
```go
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:
```go
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:
```go
const redisAddr = "127.0.0.1:6379"
```
### Worker Configuration
```go
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
```go
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**:
```go
// In internal/vault/tasks/types.go
const TypeNewOperation = "vault:new_operation"
```
2. **Create payload structures**:
```go
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**:
```go
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**:
```go
// 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:
```bash
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
docs/reference/modules/dwn.mdx
-5
View File
@@ -141,12 +141,7 @@ snrd tx dwn broadcast-tx my-vault "transaction-bytes" --from alice
## Building and Testing
### Building the Motor Client
```bash
# Build the motor WASM client
make -C x/dwn motr
# Run unit tests
make -C x/dwn test