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

Feat/1285 es ucan formatting (#1302)

Browse Source 
* feat: Add Enclave Usage Examples

* feat(es/ucan): Add comprehensive integration tests

- Create integration.test.ts with full UCAN token lifecycle testing
- Cover end-to-end token creation, parsing, and validation
- Test capability attenuation and delegation chains
- Validate multi-algorithm support and timestamp scenarios
- Implement error recovery and performance test scenarios

🤖 Generated with Claude Code

Co-Authored-By: Claude <noreply@anthropic.com>

* No commit suggestions generated

* No commit suggestions generated

* chore: Remove migrated components and add migration documentation

Removed all code and references for components that have been moved to separate repositories:

**Moved to sonr-io/hway:**
- bridge/ - HTTP service with OAuth2/OIDC/WebAuthn handlers
- cmd/hway/ - Highway service binary
- internal/migrations/ - PostgreSQL schema migrations

**Moved to sonr-io/motr:**
- cmd/motr/ - Motor worker service (WASM vault operations)
- cmd/vault/ - Vault CLI tool
- crypto/ - Comprehensive cryptographic library
- packages/ - TypeScript SDK packages (es, sdk, ui, com, pkl)
- web/auth/ - Authentication web application
- web/dash/ - Dashboard web application

**Updated Configuration:**
- Makefile: Removed build/test/release targets for moved components
- CLAUDE.md: Simplified to focus on core blockchain components
- devbox.json: Removed scripts for moved services
- docker-compose.yml: Removed hway, postgres, redis, auth, dash services
- .github/scopes.yml: Removed CI scopes for migrated components
- .goreleaser.yml: Updated release configuration

**Added Migration Documentation:**
- MIGRATE_HWAY.md: Comprehensive Highway service architecture and migration guide
- MIGRATE_MOTR.md: Comprehensive Motor/Worker/Vault architecture and migration guide

These migration documents provide complete context for setting up the new repositories including architecture diagrams, component breakdowns, API documentation, and migration checklists.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

* No commit suggestions generated

* chore: Remove contracts references and documentation

Removed all references to the contracts directory that was migrated to a separate repository.

**Changes:**
- .gitignore: Removed contract-specific ignore patterns for DAO and wSNR contracts
- .gitignore: Removed hway and motr binary references (already migrated)
- .rgignore: Removed contracts, chains, and crypto directory references
- docs/reference/contracts/: Removed DAO.mdx and wSNR.mdx documentation files

This completes the cleanup of migrated components from the repository.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

* docs: add crypto library migration documentation

Added comprehensive migration documentation for the crypto library that was
moved to sonr-io/crypto repository. This documentation provides complete context
for understanding the cryptographic primitives and protocols used throughout
the Sonr ecosystem.

## Key Documentation Added

### MIGRATE_CRYPTO.md
Complete documentation of the crypto library covering:

**Core Cryptographic Primitives**
- Elliptic curve implementations (Ed25519, Secp256k1, P-256, BLS12-381, Pallas/Vesta)
- Native curve arithmetic with optimized field operations
- Pairing-friendly curves for BLS signatures

**Multi-Party Computation (MPC)**
- MPC enclave for vault key generation and management
- Threshold cryptography (TECDSA, TED25519 with FROST protocol)
- Distributed Key Generation (DKG) via Gennaro and FROST protocols
- Secret sharing schemes (Shamir, Feldman VSS, Pedersen VSS)

**Digital Signature Schemes**
- BLS signatures with aggregation support
- BBS+ signatures for selective disclosure
- Schnorr signatures (standard and Mina/NEM variants)
- ECDSA with deterministic nonce generation

**Zero-Knowledge Proofs**
- Bulletproofs for range proofs
- Inner Product Arguments (IPA)
- Batch verification support

**Advanced Cryptographic Protocols**
- Cryptographic accumulators for set membership proofs
- Paillier homomorphic encryption
- Oblivious Transfer (OT) protocols
- Verifiable Random Functions (VRF)

**Key Management & Identity**
- DID key management with multi-chain support
- Multi-algorithm public key handling
- Wallet address derivation (Bitcoin, Ethereum, Cosmos, Solana, etc.)

**UCAN Integration**
- User-Controlled Authorization Networks
- Capability delegation and attenuation
- JWT-based capability tokens
- MPC-enabled UCAN signing

**Security Utilities**
- AEAD encryption (AES-GCM, AES-SIV)
- Argon2 key derivation
- ECIES encryption
- Secure memory handling

### MIGRATE_MOTR.md Updates
Updated Motor migration documentation to clarify that the crypto library
is now a separate external dependency at github.com/sonr-io/crypto v1.0.1

## Repository Context

The crypto library has been successfully migrated to its own repository
and is published as a Go module. It serves as the foundational cryptographic
layer for:
- Sonr blockchain (snrd) - DID signatures, vault operations
- Highway service (hway) - UCAN token signing, WebAuthn
- Motor/Worker (motr) - MPC vault operations, threshold signatures

## Integration Impact

All Sonr ecosystem components now depend on the external crypto library:
```go
require github.com/sonr-io/crypto v1.0.1
```

The migration enables independent versioning and maintenance of cryptographic
primitives while maintaining security and compatibility across the ecosystem.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

* No commit suggestions generated

* No commit suggestions generated

* No commit suggestions generated

---------

Co-authored-by: Claude <noreply@anthropic.com>
This commit is contained in:
Prad Nukala
2025-10-10 11:47:18 -04:00
committed by GitHub
co-authored by Claude
parent 7570d67787
commit 40eadc995e
1306 changed files with 2854 additions and 316038 deletions
Download Patch File Download Diff File Expand all files Collapse all files
MIGRATE_MOTR.md
+653
View File
@@ -0,0 +1,653 @@
# Motor (motr) Migration Context
> **Repository Migration**: `sonr-io/sonr` → `sonr-io/motr`
> **Components Moved**: `cmd/motr/`, `cmd/vault/`, `packages/`, `web/`
> **Note**: The `crypto/` library was moved to its own repository at `sonr-io/crypto`
## Overview
Motor (formerly "motr") is a multi-purpose WebAssembly service that provides:
1. **Worker**: WASM-based cryptographic vault operations (formerly "vault")
2. **Payment Gateway**: W3C Payment Handler API compliant payment processing
3. **TypeScript SDK**: Browser and Node.js client libraries for vault and payment operations
4. **Web Applications**: Authentication and dashboard web apps
The name "Motor" reflects its role as the execution engine powering secure operations in the Sonr ecosystem.
## Repository Structure
```
sonr-io/motr/
├── worker/ # WASM vault operations (Go → WASM)
│ ├── main.go # Entrypoint with WASM exports
│ ├── vault/ # Vault operation implementations
│ └── mpc/ # Multi-party computation
│
├── server/ # HTTP server mode (Go)
│ ├── main.go # HTTP/Payment Gateway server
│ ├── handlers/ # Payment & OIDC handlers
│ └── middleware/ # Security & rate limiting
│
├── packages/ # TypeScript SDK and libraries
│ ├── es/ # @motr/es - Core SDK
│ │ ├── client/ # Vault client
│ │ ├── worker/ # Service worker integration
│ │ ├── plugin/ # Plugin system
│ │ └── codec/ # Encoding/signing utilities
│ │
│ ├── sdk/ # @motr/sdk - High-level SDK
│ ├── ui/ # @motr/ui - UI components
│ └── com/ # @motr/com - Common utilities
│
└── web/ # Web applications
├── auth/ # Authentication app
└── dash/ # Dashboard app
```
## Dependencies
Motor depends on the **Sonr Cryptography Library** (`github.com/sonr-io/crypto`), which was moved to its own repository. See MIGRATE_CRYPTO.md for details on the crypto library.
## Component 1: Worker (WASM Vault)
**Technology**: Go 1.24.4 → WebAssembly via TinyGo
**Runtime**: Extism (WebAssembly plugin host)
**Purpose**: Secure cryptographic operations in sandboxed environment
### Architecture
```
┌──────────────────────────────────────────────┐
│ Host Application │
│ (Browser, Node.js, or Highway) │
└───────────────┬──────────────────────────────┘
│
▼
┌───────────────┐
│ Extism │ ◄─── WASM Runtime
│ Runtime │
└───────┬───────┘
│
▼
┌───────────────────────────────────────────────┐
│ worker.wasm (Motor Worker) │
├───────────────────────────────────────────────┤
│ │
│ ┌──────────────┐ ┌──────────────┐ │
│ │ Vault │ │ MPC │ │
│ │ Operations │ │ Enclave │ │
│ └──────────────┘ └──────────────┘ │
│ │
│ ┌──────────────────────────────────┐ │
│ │ Crypto Primitives │ │
│ │ (Ed25519, ECDSA, BLS, etc.) │ │
│ └──────────────────────────────────┘ │
│ │
└───────────────────────────────────────────────┘
```
### WASM Exports (Go Functions)
All exported functions follow the Extism PDK pattern:
#### Core Vault Operations
```go
//go:wasmexport generate
func generate() int32
// Creates new MPC enclave with key generation
// Input: GenerateRequest{id: string}
// Output: GenerateResponse{data: EnclaveData, public_key: []byte}
//go:wasmexport refresh
func refresh() int32
// Refreshes enclave cryptographic material
// Input: RefreshRequest{enclave: EnclaveData}
// Output: RefreshResponse{okay: bool, data: EnclaveData}
//go:wasmexport sign
func sign() int32
// Signs arbitrary message with vault key
// Input: SignRequest{message: []byte, enclave: EnclaveData}
// Output: SignResponse{signature: []byte}
//go:wasmexport verify
func verify() int32
// Verifies signature against public key
// Input: VerifyRequest{public_key: []byte, message: []byte, signature: []byte}
// Output: VerifyResponse{valid: bool}
```
#### Multi-Chain Transaction Signing
```go
//go:wasmexport sign_cosmos_transaction
func signCosmosTransaction() int32
// Signs Cosmos SDK transaction
// Input: CosmosSignRequest{chain_id, account_number, sequence, tx_bytes}
// Output: SignedTransaction{signature, signed_doc}
//go:wasmexport sign_evm_transaction
func signEvmTransaction() int32
// Signs Ethereum/EVM transaction
// Input: EVMSignRequest{chain_id, nonce, tx_data, gas_limit}
// Output: SignedTransaction{v, r, s, raw_tx}
//go:wasmexport sign_message
func signMessage() int32
// Signs arbitrary message (EIP-191/EIP-712)
// Input: MessageSignRequest{message, encoding_type}
// Output: MessageSignature{signature, recovery_id}
```
#### Vault Import/Export (IPFS)
```go
//go:wasmexport export
func export() int32
// Exports encrypted vault to IPFS
// Input: ExportRequest{enclave: EnclaveData, password: []byte}
// Output: ExportResponse{cid: string, success: bool}
//go:wasmexport import
func import() int32
// Imports encrypted vault from IPFS
// Input: ImportRequest{cid: string, password: []byte}
// Output: ImportResponse{enclave: EnclaveData, success: bool}
```
#### WebAuthn Integration
```go
//go:wasmexport create_vault_enclave
func createVaultEnclave() int32
// Creates vault with WebAuthn configuration
// Input: VaultConfig{vault_id, webauthn_enabled, auto_lock_timeout}
// Output: VaultEnclave{enclave_data, webauthn_credentials}
//go:wasmexport unlock_vault
func unlockVault() int32
// Unlocks vault with WebAuthn or password
// Input: UnlockRequest{vault_id, auth_method, credentials}
// Output: UnlockResponse{success, session_token}
//go:wasmexport lock_vault
func lockVault() int32
// Locks vault and clears sensitive data
// Input: LockRequest{vault_id}
// Output: LockResponse{success}
```
#### Health & Monitoring
```go
//go:wasmexport get_vault_health
func getVaultHealth() int32
// Returns vault health status
// Output: EnclaveHealth{vault_id, status, last_activity, key_rotation_due}
//go:wasmexport get_version
func getVersion() int32
// Returns worker version and capabilities
// Output: VersionInfo{version, supported_chains, features}
```
### MPC Enclave Structure
```go
type EnclaveData struct {
ID string `json:"id"`
PublicKey []byte `json:"public_key"`
PrivateKeyShare []byte `json:"private_key_share"` // Encrypted
Threshold uint32 `json:"threshold"`
Parties uint32 `json:"parties"`
ChainID string `json:"chain_id"`
CreatedAt int64 `json:"created_at"`
LastRefresh int64 `json:"last_refresh"`
Metadata map[string]string `json:"metadata"`
}
```
**Note**: Motor relies on the Sonr Cryptography Library (`github.com/sonr-io/crypto`) for all cryptographic operations. The crypto library provides comprehensive primitives including Ed25519, ECDSA, BLS signatures, MPC, threshold cryptography, and more. See `MIGRATE_CRYPTO.md` for the complete crypto library documentation.
### Build Configuration
```bash
# Build WASM module with TinyGo
tinygo build -o worker.wasm -target wasi \
-no-debug \
-opt 2 \
-scheduler none \
./worker/main.go
# Optimize with wasm-opt
wasm-opt -O3 -o worker.optimized.wasm worker.wasm
# Build with Extism toolchain
extism compile worker.wasm -o worker.plugin.wasm
```
### IPFS Integration
```go
// IPFS Configuration
const (
IPFSStorageEndpoint = "http://127.0.0.1:5001/api/v0/add"
IPFSRetrievalEndpoint = "http://127.0.0.1:5001/api/v0/cat"
IPFSGateway = "https://ipfs.did.run/ipfs/"
)
// Export vault to IPFS
func ExportToIPFS(enclave *EnclaveData, password []byte) (cid string, error) {
// 1. Serialize enclave data
// 2. Encrypt with AES-256-GCM using password
// 3. Upload to IPFS
// 4. Return content ID (CID)
}
```
## Component 2: Server (Payment Gateway)
**Technology**: Go 1.24.4 HTTP Server
**Framework**: `go-wasm-http-server` (can run as service worker or HTTP)
**Purpose**: Payment processing and OIDC authorization
### Features
#### W3C Payment Handler API
- Payment request processing
- Card validation (Luhn algorithm, CVV, expiry)
- PCI DSS compliant tokenization
- Transaction signing with HMAC-SHA256
- AES-256-GCM encryption for card data
- Refund processing
- Audit logging
#### OIDC Authorization Server
- Full OpenID Connect provider
- Discovery endpoint
- Authorization with PKCE
- Token endpoint (JWT generation)
- UserInfo endpoint
- JWKS endpoint
- Refresh tokens
#### Security
- Rate limiting (100 req/min per client)
- Origin validation
- Security headers (CSP, X-Frame-Options)
- CORS configuration
- Secure token generation
- Card number masking
### API Endpoints
```
POST /api/payment/process - Process payment
POST /api/payment/validate - Validate payment method
POST /api/payment/refund - Process refund
GET /.well-known/openid-configuration
GET /oauth2/authorize
POST /oauth2/token
GET /oauth2/userinfo
GET /oauth2/jwks
```
## Component 3: TypeScript SDK (`packages/`)
**Purpose**: Browser and Node.js integration for Motor services
### Package Structure
#### `@motr/es` (Core SDK)
**Client Module** (`client/`):
- `VaultClient`: Main vault operations client
- `VaultClientWithIPFS`: IPFS-enabled vault client
- RPC/REST API integration
- Transaction broadcasting
**Worker Module** (`worker/`):
- `MotorServiceWorkerManager`: Service worker lifecycle
- `MotorClient`: HTTP client for Motor API
- Payment gateway client
- OIDC client integration
**Plugin Module** (`plugin/`):
- Plugin loading and caching
- WASM module verification
- Enclave storage (IndexedDB, localStorage)
- IPFS pinning integration
**Codec Module** (`codec/`):
- Address encoding (Bech32, EIP-55)
- Key management
- Transaction signing
- Signature verification
- Message serialization
**Auth Module** (`auth/`):
- WebAuthn registration
- WebAuthn authentication
- Credential management
- Passkey integration
**Generated Protobufs** (`protobufs/`):
- Cosmos SDK types
- Sonr blockchain types
- IBC types
- CosmWasm types
#### `@motr/sdk` (High-Level SDK)
- Simplified API wrappers
- Common operation helpers
- Error handling utilities
- TypeScript type definitions
#### `@motr/ui` (UI Components)
- React components for vault operations
- WebAuthn UI flows
- Payment forms
- Dashboard widgets
#### `@motr/com` (Common Utilities)
- Validation helpers
- Formatting utilities
- Type definitions
- Constants
### Usage Examples
```typescript
// Initialize vault client
import { createVaultClient } from '@motr/es';
const client = await createVaultClient({
rpcUrl: 'http://localhost:26657',
restUrl: 'http://localhost:1317',
});
// Generate vault
const vault = await client.generate({ id: 'my-vault' });
// Sign message
const signature = await client.sign({
message: new Uint8Array([1, 2, 3]),
enclave: vault.data,
});
// Export to IPFS
const cid = await client.export({
enclave: vault.data,
password: new Uint8Array([/* password */]),
});
```
```typescript
// Service worker integration
import { registerMotorServiceWorker } from '@motr/es';
const registration = await registerMotorServiceWorker({
workerUrl: '/worker.js',
scope: '/motor',
});
// Use in browser
const plugin = await createMotorPlugin({
auto_register_worker: true,
prefer_service_worker: true,
});
await plugin.processPayment({
amount: 100.00,
currency: 'USD',
method: 'card',
});
```
## Component 4: Web Applications
### Authentication App (`web/auth/`)
**Framework**: Next.js 14+
**Purpose**: WebAuthn registration and OIDC flows
**Features**:
- Passkey registration UI
- Login flows
- Session management
- OIDC client implementation
- WebAuthn ceremony handling
**Tech Stack**:
- Next.js (App Router)
- React 18
- TailwindCSS
- Fumadocs (documentation)
- Sonr UI components
### Dashboard App (`web/dash/`)
**Framework**: Next.js 14+
**Purpose**: Vault management and blockchain interaction
**Features**:
- Vault creation and management
- Transaction signing UI
- DID document viewer
- DWN record browser
- Token management
- Network switcher
**Tech Stack**:
- Next.js (App Router)
- React 18
- TailwindCSS
- @motr/sdk for blockchain interaction
- Charts and visualizations
### Shared Configuration
Both apps use:
- `@motr/ui` for shared components
- `@motr/sdk` for blockchain operations
- Environment-based configuration
- SSR/SSG optimization
- Edge runtime compatibility
## Build & Development
### Worker (WASM)
```bash
# Build worker WASM
make worker
# Or with TinyGo directly
tinygo build -o worker.wasm -target wasi ./worker/main.go
```
### Server (Payment Gateway)
```bash
# Build server
go build -o motr-server ./server/main.go
# Run server
./motr-server --port 8080
```
### TypeScript SDK
```bash
# Install dependencies
pnpm install
# Build all packages
pnpm -r build
# Build specific package
pnpm --filter @motr/es build
# Run tests
pnpm test
# Generate from protobufs
cd packages/es
pnpm gen:protobufs
```
### Web Applications
```bash
# Development
pnpm --filter @motr/auth dev
pnpm --filter @motr/dash dev
# Build
pnpm --filter @motr/auth build
pnpm --filter @motr/dash build
# Production
pnpm --filter @motr/auth start
```
## Testing Strategy
### Go (Worker)
```bash
# Unit tests
go test ./worker/...
go test ./server/...
# With race detection
go test -race ./...
# Coverage
go test -cover ./...
```
### TypeScript (SDK/Apps)
```bash
# Unit tests
pnpm test
# E2E tests
pnpm test:e2e
# Type checking
pnpm typecheck
```
### Integration Tests
```bash
# Requires Motor server running
INTEGRATION=true pnpm test
```
## Configuration
### Worker Environment Variables
```bash
# WASM runtime configuration (via Extism)
CHAIN_ID=sonr-testnet-1
PASSWORD=default-password
IPFS_GATEWAY=https://ipfs.did.run/ipfs/
```
### SDK Configuration
```typescript
interface MotorConfig {
// RPC endpoints
rpcUrl: string;
restUrl: string;
// IPFS
ipfsGateways: string[];
enableIPFSPersistence: boolean;
// Service worker
workerUrl: string;
preferServiceWorker: boolean;
// Security
timeout: number;
maxRetries: number;
}
```
### Web App Environment Variables
```bash
# Common
NODE_ENV=production
NEXT_PUBLIC_CHAIN_ID=sonr-testnet-1
# Auth App
NEXT_PUBLIC_AUTH_URL=http://localhost:3100
NEXT_PUBLIC_WEBAUTHN_RP_ID=localhost
NEXT_PUBLIC_WEBAUTHN_RP_NAME="Sonr Auth"
# Dashboard App
NEXT_PUBLIC_RPC_ENDPOINT=http://localhost:26657
NEXT_PUBLIC_REST_ENDPOINT=http://localhost:1317
NEXT_PUBLIC_IPFS_GATEWAY=https://ipfs.io/ipfs/
```
## Migration Checklist
When setting up the new `sonr-io/motr` repository:
### Worker
- [ ] Copy `cmd/vault/` → `worker/`
- [ ] Update import paths to use `github.com/sonr-io/crypto`
- [ ] Create `worker/go.mod` with crypto dependency
- [ ] Setup TinyGo build scripts
- [ ] Add WASM optimization pipeline
- [ ] Document export functions and types
- [ ] Create test suite for WASM functions
### Server
- [ ] Copy `cmd/motr/` → `server/`
- [ ] Update payment gateway handlers
- [ ] Configure OIDC provider
- [ ] Setup rate limiting
- [ ] Add monitoring/metrics
- [ ] Create Dockerfile
- [ ] Document API endpoints
### TypeScript SDK
- [ ] Copy `packages/` directory
- [ ] Update package names to `@motr/*`
- [ ] Setup pnpm workspace
- [ ] Configure build pipeline (tsup/rollup)
- [ ] Setup Biome for linting/formatting
- [ ] Generate types from protobuf
- [ ] Create comprehensive tests
- [ ] Setup Changesets for versioning
- [ ] Publish to npm registry
### Web Applications
- [ ] Copy `web/` directory
- [ ] Update dependencies to use `@motr/*`
- [ ] Configure environment variables
- [ ] Setup build and deployment
- [ ] Create Docker images
- [ ] Add E2E tests
- [ ] Document user flows
### General
- [ ] Create monorepo structure
- [ ] Setup CI/CD pipelines
- [ ] Configure release automation
- [ ] Create API documentation
- [ ] Write migration guide
- [ ] Setup npm organization (@motr)
- [ ] Configure security scanning
- [ ] Setup monitoring and logging
## Related Documentation
- TinyGo: https://tinygo.org/
- Extism: https://extism.org/
- W3C Payment Handler API: https://www.w3.org/TR/payment-handler/
- WebAuthn: https://www.w3.org/TR/webauthn/
- IPFS: https://docs.ipfs.tech/
- Next.js: https://nextjs.org/
- pnpm Workspaces: https://pnpm.io/workspaces