Master (#1262)

* clear * feat: Add everything * fix: Commenht
2026-08-02 17:31:39 +00:00 · 2025-10-03 14:45:52 -04:00
parent 43b4a11c06
commit 13e6c3e84d
1935 changed files with 655061 additions and 40058 deletions
@@ -0,0 +1,375 @@
+---
+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
@@ -0,0 +1,114 @@
+---
+title: "Motr WASM Light-Node"
+sidebarTitle: "Motr Overview"
+description: "Learn how to use the Motor WASM plugin as an MPC-based UCAN source for decentralized token operations"
+icon: "play"
+---
+
+# Motor WASM Plugin: UCAN Source
+
+The Motor WASM plugin is a WebAssembly-based plugin that provides Multi-Party Computation (MPC) powered UCAN (User-Controlled Authorization Networks) token generation and management.
+
+## Overview
+
+The Motor plugin enables secure, decentralized token creation and management through an MPC-based architecture. It provides the following key capabilities:
+
+- Secure token generation
+- MPC-based signing
+- Flexible UCAN token creation
+- Integrated enclave management
+
+## Environment Configuration
+
+To use the Motor plugin, you need to set the following PDK environment variables:
+
+```json
+{
+  "chain_id": "sonr-testnet-1",  // Blockchain network
+  "enclave": { ... },            // MPC enclave configuration
+  "vault_config": { ... }        // Optional vault configuration
+}
+```
+
+## UCAN Token Creation
+
+### Creating Origin Tokens
+
+```go
+type NewOriginTokenRequest struct {
+    AudienceDID  string                   // Target DID
+    Attenuations []map[string]any // Optional restrictions
+    Facts        []string                 // Additional claims
+    NotBefore    int64                    // Token activation time
+    ExpiresAt    int64                    // Token expiration time
+}
+```
+
+Example usage:
+
+```go
+request := NewOriginTokenRequest{
+    AudienceDID: "did:example:target-did",
+    Attenuations: []{
+        {"capability": "read", "resource": "/data"}
+    },
+    Facts: ["authenticated_user"],
+    NotBefore: time.Now().Unix(),
+    ExpiresAt: time.Now().Add(24 * time.Hour).Unix()
+}
+```
+
+### Creating Attenuated Tokens
+
+```go
+type NewAttenuatedTokenRequest struct {
+    ParentToken  string                   // Previous token to derive from
+    AudienceDID  string                   // Target DID
+    Attenuations []map[string]any // Token restrictions
+    Facts        []string                 // Additional claims
+    NotBefore    int64                    // Token activation time
+    ExpiresAt    int64                    // Token expiration time
+}
+```
+
+## Signing and Verification
+
+The Motor plugin provides methods for data signing and verification:
+
+```go
+// Sign data using MPC enclave
+func SignData(data []byte) (signature []byte, err error)
+
+// Verify signed data
+func VerifyData(data, signature []byte) (valid bool, err error)
+```
+
+## Error Handling
+
+The plugin returns structured error responses with detailed error messages:
+
+```go
+type UCANTokenResponse struct {
+    Token   string  // Generated token
+    Issuer  string  // Token issuer DID
+    Address string  // Blockchain address
+    Error   string  // Error message (if any)
+}
+```
+
+## Best Practices
+
+1. Always validate the enclave before generating tokens
+2. Use the shortest possible token lifetime
+3. Implement granular attenuations
+4. Validate tokens before using them
+
+## Security Considerations
+
+- MPC ensures no single party controls the entire signing process
+- Tokens are cryptographically signed using distributed key shares
+- Supports multiple key types: Ed25519, Secp256k1, RSA
+
+## Advanced Configuration
+
+For advanced MPC enclave configurations, refer to the DWN configuration documentation.
@@ -0,0 +1,36 @@
+---
+title: The Blockchain for Self-Sovereign Identity
+sidebarTitle: Sonr Overview
+description: A deep dive into Sonr's novel approach to personal data ownership and control.
+icon: play
+---
+
+In a world rapidly approaching the era of quantum computing, traditional cryptographic methods face unprecedented challenges. The burden of securing digital identity can no longer rest solely on the user. Sonr is designed to simplify the user experience while providing far greater security over personal data. We achieve this by incorporating the following concepts into our identity primitive.
+
+## Core Concepts
+
+<CardGroup>
+  <Card title="Multi-Party Computation (MPC)">
+    We eliminate the need for users to manage private keys directly. Instead, we
+    use rotating key shares with the DKLS algorithm to construct digital
+    signatures, distributing trust and removing single points of failure.
+  </Card>
+  <Card title="Identifier Accumulators">
+    Accounts on Sonr are anonymous and private by default. We employ
+    zero-knowledge accumulators to achieve this, allowing for verifiable claims
+    without revealing underlying identities.
+  </Card>
+  <Card title="On-Chain Wallet Interface">
+    The public key of a Sonr Account is encoded with bech32 and persisted
+    on-chain. This makes accounts highly resilient and resolvable across all
+    validator nodes, creating a robust digital profile.
+  </Card>
+</CardGroup>
+
+By combining these concepts, we achieve a portable, interoperable, and secure identifier that we define as a **Sonr Account**.
+
+## The Sonr Approach to Identity
+
+The Sonr platform approaches user authentication with the understanding that a user's identity is multi-dimensional and must be safeguarded with the utmost integrity. This is achieved through the implementation of **Decentralized Identifiers (DIDs)** and **Multi-Party Computation (MPC)**, creating a robust framework for identity management.
+
+DIDs are a cornerstone of the Sonr identity system, providing a verifiable and self-sovereign identity that users control entirely. This decentralized identity is not just a static entity but a dynamic one, capable of interfacing securely with various facets of the Sonr ecosystem. The MPC component further enhances security by ensuring that the private keys, the quintessential element of user authentication, are never fully exposed, even during the authentication process.
@@ -0,0 +1,82 @@
+---
+title: $SNR Economics
+description: "The role of tokenomics in the Sonr ecosystem is twofold: it provides a medium of exchange and serves as a reward mechanism for validators. The platform's native tokens are used to facilitate transactions, secure network integrity, and incentivize behaviors that contribute to the network's longevity and reliability."
+sidebarTitle: "Design Model"
+icon: "star"
+---
+
+<Note>
+The Sonr platform has implemented a sophisticated token handling and treasury process designed to ensure the stability and sustainability of the SNR token. This process is critical in managing the economics of the Sonr ecosystem and ensuring its long-term viability.
+</Note>
+
+## Key Economic Processes
+
+<CardGroup>
+  <Card title="Buyback Process for Non-SNR Payments">
+    When payments are made in currencies other than SNR, the Sonr system
+    initiates a buyback process. This approach involves using the received
+    non-SNR currency to purchase SNR tokens from the open market. This mechanism
+    supports the demand and market value of SNR tokens and ensures a consistent
+    influx of SNR into the system, reinforcing its utility and circulation
+    within the ecosystem.
+  </Card>
+  <Card title="Contribution to SNR Fee Pool">
+    The SNR tokens acquired through the buyback process are contributed to the
+    SNR fee pool. This pool plays a pivotal role in the ecosystem, as it is
+    utilized for various operational purposes, including network transaction
+    fees, rewards for validators, and other ecosystem incentives. This
+    continuous replenishment of the fee pool ensures the smooth operation and
+    sustainability of the network's economic activities.
+  </Card>
+  <Card title="Allocation to the Treasury">
+    Half of the unvested tokens, representing 50% of the total, are allocated to
+    the Sonr treasury. This treasury acts as a strategic reserve, supporting the
+    long-term objectives of the Sonr ecosystem. Funds from the treasury can be
+    utilized for various purposes, including development initiatives, marketing
+    efforts, community growth, and other activities that align with Sonr’s
+    strategic goals and contribute to the overall growth and success of the
+    platform.
+  </Card>
+  <Card title="Scaling Inflation Rewards">
+    To ensure the equitable distribution of incentives and maintain a balanced
+    economic model, Sonr has implemented a system where inflation rewards scale
+    relative to the authentic growth of its user base. This approach means that
+    as the number of genuine users on the platform increases, so do the
+    inflation rewards. This scaling mechanism aligns the incentives with actual
+    platform usage, fostering an environment where growth in the user base
+    directly contributes to the overall health and stability of the token
+    economy.
+  </Card>
+</CardGroup>
+
+
+
+
+
+
+## Validator Incentives
+
+Validators play a pivotal role in the network, responsible for processing authentication requests and maintaining the blockchain's integrity. They are incentivized through a task claiming process based on a first-come-first-serve mechanism and are remunerated via transaction fees and token rewards. This incentive structure ensures the high performance and reliability of services within the network.
+
+<CardGroup>
+  <Card title="Task Claiming">
+    Validators select tasks from the Order Stack on a first-come-first-serve
+    basis, ensuring a fair and efficient distribution of work.
+  </Card>
+  <Card title="Delivery and Payment">
+    If a validator successfully delivers a service request, they proceed to the
+    payment process. The payment is provided with a vesting schedule, aligning
+    the validators' incentives with the long-term health of the network.
+  </Card>
+  <Card title="Slashing Conditions">
+    In instances where a validator fails to deliver on a service request, a
+    slashing condition is triggered. This condition serves as a deterrent
+    against poor performance and ensures the reliability of services within the
+    network.
+  </Card>
+  <Card title="Consequences of Failure">
+    Failure to deliver a service results in the slashing and burning of the
+    validator's staked SNR tokens. This punitive measure reinforces the
+    commitment of validators to fulfill their tasks diligently and efficiently.
+  </Card>
+</CardGroup>