lux/bridge
2
0
Fork 0
mirror of https://github.com/luxfi/bridge.git synced 2026-09-24 00:26:46 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: delete 8 stale migration / status / setup .md files (issue #391)

Browse Source 
Delete the leftover Rust→Go MPC migration notes and the Docker Compose
deployment guide. Those describe an architecture from before the SDK
rationalization and confuse new readers (e.g. LOCAL-SETUP.md was still
claiming images weren't published yet; MPC-MODERNIZATION-SUMMARY.md was
a celebration page for migration work that finished long ago).

  - BRIDGE-STATUS.md
  - LOCAL-SETUP.md
  - MPC-GO-INTEGRATION.md
  - MPC-INTEGRATION-COMPLETE.md
  - MPC-MODERNIZATION-SUMMARY.md
  - MIGRATION-TO-GO-MPC.md
  - DEPLOYMENT.md           (GG18 → CGG21MP migration; both pre-CGGMP21)
  - CI-CD-DOCKER-IMAGES.md  (described pre-self-hosted-runner workflow)

Migration history is in git log + GH releases. Live setup lives in
docs/LLM.md (now the single canonical AI/onboarding doc) plus the
top-level README.md.

Kept:
  - docs/LLM.md         (canonical source of truth, refreshed in v1.1.11)
  - docs/LUX-ID-INTEGRATION.md (still applicable; Casdoor-based auth)

Closes part of #391.
This commit is contained in:
zeekay
2026-05-21 19:02:48 -07:00
parent 5807b86a16
commit 2b9f8995e5
8 changed files with 0 additions and 1286 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/BRIDGE-STATUS.md
-81
View File
@@ -1,81 +0,0 @@
# Lux Bridge MPC Integration - Current Status
## ✅ What's Running
### MPC Nodes (Local)
- **node0**: Running on http://localhost:8080 ✅
- **node1**: Running on http://localhost:8081 ✅
- **node2**: Running on http://localhost:8082 ✅
- Status: All nodes are ready and accepting MPC requests
### Infrastructure (Docker)
- **NATS**: nats://localhost:4223 ✅
- **Consul**: http://localhost:8501 ✅
- **PostgreSQL**: localhost:5433 ✅
## 🚀 Next Steps
### Option 1: Run Bridge Locally (Recommended for now)
1. **Bridge Server**:
```bash
cd app/server
pnpm install
pnpm dev
```
2. **Bridge UI**:
```bash
cd app/bridge
pnpm install
pnpm dev
```
### Option 2: Build and Use Docker Images
The compose files are configured to use `ghcr.io/luxfi` images, but they need to be built and pushed first:
```bash
# Build images (UI build context is repo root — pnpm workspace
# resolves @luxfi/bridge to the sibling pkg/bridge package).
docker build -t ghcr.io/luxfi/bridge-mpc:latest ./mpc-service
docker build -t ghcr.io/luxfi/bridge-server:latest ./app/server
docker build -t ghcr.io/luxfi/bridge-ui:latest -f app/bridge/Dockerfile .
# Push to registry (requires login)
docker push ghcr.io/luxfi/bridge-mpc:latest
docker push ghcr.io/luxfi/bridge-server:latest
docker push ghcr.io/luxfi/bridge-ui:latest
# Then run
make up
```
## 📝 Summary
The MPC integration is complete and functional:
- ✅ MPC nodes are running locally with the pre-built binaries
- ✅ All infrastructure services are running in Docker
- ✅ Configuration files use ghcr.io/luxfi images (ready for when images are published)
- ✅ Local development setup is working
## 🛠️ Useful Commands
```bash
# Check MPC nodes
ps aux | grep lux-mpc
# View MPC logs
tail -f logs/node*.log
# Check infrastructure
docker compose -f compose-infra.yml ps
# Stop infrastructure
docker compose -f compose-infra.yml down
# Stop MPC nodes
./stop-mpc-local.sh
```
The bridge is ready for development with secure multi-party computation!
docs/CI-CD-DOCKER-IMAGES.md
-108
View File
@@ -1,108 +0,0 @@
# CI/CD Docker Images Documentation
## Overview
The Lux Bridge project uses GitHub Actions to automatically build and push Docker images to GitHub Container Registry (ghcr.io) whenever changes are pushed to the main branch.
## Docker Images Built
The CI/CD pipeline builds three main Docker images:
1. **MPC Service**: `ghcr.io/luxfi/lux-mpc:latest`
2. **Bridge Server**: `ghcr.io/luxfi/bridge-server:latest`
3. **Bridge UI**: `ghcr.io/luxfi/bridge-ui:latest`
## Workflow Configuration
The workflow is defined in `.github/workflows/build-and-push.yml` and:
- Triggers on push to `main` branch
- Triggers on changes to relevant directories
- Can be manually triggered via workflow_dispatch
- Builds multi-platform images (linux/amd64, linux/arm64)
- Uses GitHub's built-in GITHUB_TOKEN for authentication
## Image Tags
Each image is tagged with:
- `latest` - for the main branch
- `main-<sha>` - specific commit on main
- `pr-<number>` - for pull requests
- Branch name - for feature branches
## Using the Images
### Development (compose.yml)
```yaml
services:
mpc-node-0:
image: ghcr.io/luxfi/lux-mpc:latest
bridge-server:
image: ghcr.io/luxfi/bridge-server:latest
bridge-ui:
image: ghcr.io/luxfi/bridge-ui:latest
```
### Local Development (compose.local.yml)
For local development without Docker images, use:
```bash
make up # Starts infrastructure only
# Then run services locally
```
## Manual Build and Push
To manually build and push images:
```bash
# Build all images
make build
# Push to registry (requires login)
make push
```
## GitHub Container Registry Access
Images are public and can be pulled without authentication:
```bash
docker pull ghcr.io/luxfi/lux-mpc:latest
docker pull ghcr.io/luxfi/bridge-server:latest
docker pull ghcr.io/luxfi/bridge-ui:latest
```
## Troubleshooting
### Image Not Found
If you get "manifest unknown" errors:
1. Check if the workflow has run successfully
2. Verify image names match exactly
3. Use `compose.local.yml` for local development
### Build Failures
Common issues:
- Missing dependencies in Dockerfile
- Incorrect build context paths
- Network issues during build
### Local Testing
Test the build locally:
```bash
# MPC Service
docker build -f app/mpc-service/Dockerfile .
# Bridge Server
docker build -f app/server/Dockerfile app/server/
# Bridge UI (build context is repo root — pnpm workspace)
docker build -f app/bridge/Dockerfile .
```
## Security
- Images are scanned for vulnerabilities by GitHub
- Use specific tags in production, not `latest`
- Regularly update base images
- Follow least-privilege principles in Dockerfiles
docs/DEPLOYMENT.md
-226
View File
@@ -1,226 +0,0 @@
# Bridge Deployment Guide
This guide covers the deployment of the Lux Bridge ecosystem using Docker Compose and the migration from GG18 to CGG21MP MPC protocol.
## Quick Start
### Local Development
```bash
# Start local development environment
make up
# or
make dev
# View logs
make logs
# Stop services
make down
```
### Production Deployment
#### Mainnet
```bash
# Set environment variables
cp .env.example .env.mainnet
# Edit .env.mainnet with production values
# Start mainnet deployment
make mainnet
# Monitor services
make logs
```
#### Testnet
```bash
# Start testnet deployment
make testnet
```
## Architecture
The bridge consists of:
- **3 MPC Nodes**: Threshold signature nodes (2-of-3)
- **Bridge Server**: API server handling bridge operations
- **Bridge UI**: Web interface for users
- **Infrastructure**: NATS, Consul, PostgreSQL
- **Monitoring**: Prometheus & Grafana
## Docker Images
All images are hosted on GitHub Container Registry:
- `ghcr.io/luxfi/bridge-mpc:latest`
- `ghcr.io/luxfi/bridge-server:latest`
- `ghcr.io/luxfi/bridge-ui:latest`
### Building Images
```bash
# Build all images with multi-platform support
make build
# Push to registry (requires login)
make login
make push
```
## MPC Key Management
### Exporting Keys
```bash
# Export keys from running deployment
make export-keys
# Keys will be saved to exports/mpc-keys/
```
### Migration from GG18 to CGG21MP
The bridge supports migration from the legacy GG18 protocol to the newer CGG21MP protocol.
```bash
# Run migration tool
./scripts/migrate-mpc-keys.sh
# Options:
# 1. Export keys from current deployment
# 2. Analyze exported keys
# 3. Create new CGG21MP wallet
# 4. Show sweep instructions
# 5. Full migration (all steps)
```
#### Migration Process
1. **Export existing GG18 keys** from Kubernetes or Docker deployment
2. **Create new CGG21MP wallet** with fresh keys
3. **Sweep funds** from old GG18 address to new CGG21MP address
4. **Update configuration** to use new wallet
### Kubernetes to Docker Migration
If migrating from a Kubernetes deployment:
```bash
# Export from K8s
kubectl exec <mpc-pod> -- cat /data/mpc/keys/node_key.json > old-keys.json
# Import to Docker
docker cp old-keys.json bridge-mpc-0:/data/mpc/keys/
```
## Configuration
### Environment Variables
Key environment variables for each service:
#### MPC Nodes
- `NODE_ID`: Unique identifier for the node
- `MPC_THRESHOLD`: Signature threshold (2)
- `MPC_TOTAL_NODES`: Total nodes (3)
- `MPC_PROTOCOL`: Protocol version (CGG21MP)
#### Bridge Server
- `DATABASE_URL`: PostgreSQL connection string
- `NATS_URL`: NATS messaging server
- `CONSUL_URL`: Consul service discovery
- `NETWORK`: Network type (mainnet/testnet)
### Network Configuration
- **Mainnet**: Production network with TLS, monitoring, backups
- **Testnet**: Testing network with debug logging, faucet
- **Local**: Development with hot-reloading
## Security
### Best Practices
1. **Never commit keys** - Use `.gitignore` patterns
2. **Use TLS in production** - Certificates in `certs/`
3. **Secure PostgreSQL** - Strong passwords, SSL mode
4. **Network isolation** - Use Docker networks
5. **Regular backups** - Automated backup service
### Backup and Recovery
```bash
# Create full backup
make backup
# Backups include:
# - PostgreSQL database
# - MPC key material
# - Configuration files
```
## Monitoring
### Prometheus Metrics
- Available at: `http://localhost:9094`
- Metrics exported by all services
- Custom dashboards for MPC operations
### Grafana Dashboards
- Available at: `http://localhost:3002`
- Default login: admin/admin (change in production)
- Pre-configured dashboards for:
- MPC node health
- Bridge transactions
- System resources
## Troubleshooting
### Common Issues
1. **MPC nodes not syncing**
```bash
# Check consul status
docker exec bridge-consul consul members
# Check NATS connectivity
docker exec bridge-nats nats-server --help
```
2. **Database connection issues**
```bash
# Check PostgreSQL
docker exec bridge-postgres pg_isready
# View logs
docker logs bridge-postgres
```
3. **Key export failures**
```bash
# Check file permissions
docker exec bridge-mpc-0 ls -la /data/mpc/keys/
# Verify node is running
docker ps | grep mpc
```
### Debug Mode
```bash
# Start with debug logging
LOG_LEVEL=debug docker compose up
# Attach to container
docker exec -it bridge-mpc-0 sh
```
## CI/CD
GitHub Actions workflow automatically:
1. Builds multi-platform images (amd64, arm64)
2. Runs tests
3. Pushes to ghcr.io/luxfi registry
4. Tags with branch name and commit SHA
Triggered on:
- Push to main branch
- Pull requests
- Manual workflow dispatch
## Support
For issues or questions:
1. Check logs: `make logs`
2. Review configuration
3. Open GitHub issue
4. Contact team on Discord
docs/LOCAL-SETUP.md
-82
View File
@@ -1,82 +0,0 @@
# Local Bridge Setup with MPC
Since the ghcr.io Docker images are not yet published, here's how to run the bridge locally with the MPC nodes.
## Current Status
✅ **MPC Nodes are already running locally!**
- node0: http://localhost:8080
- node1: http://localhost:8081
- node2: http://localhost:8082
The nodes are configured and ready to accept MPC requests.
## Quick Start
### 1. Keep MPC Nodes Running
The MPC nodes are already running from our previous setup. You can verify with:
```bash
ps aux | grep lux-mpc
```
### 2. Start Infrastructure Services
Since Docker networking is having issues, run these locally:
```bash
# Start NATS (if not running)
docker run -d --name nats -p 4222:4222 -p 8222:8222 nats:latest -js
# Start Consul (if not running)
consul agent -dev -client=0.0.0.0
```
### 3. Start Bridge Server
```bash
cd app/server
pnpm install
pnpm dev
```
### 4. Start Bridge UI
```bash
cd app/bridge
pnpm install
pnpm dev
```
## Alternative: Fix Docker Images
To use the proper Docker setup, the ghcr.io images need to be built and pushed:
1. **Login to GitHub Container Registry**:
```bash
echo $GITHUB_TOKEN | docker login ghcr.io -u USERNAME --password-stdin
```
2. **Build and Push Images**:
```bash
# Build images locally first (UI build context is repo root — pnpm
# workspace resolves @luxfi/bridge to the sibling pkg/bridge package).
docker build -t ghcr.io/luxfi/bridge-mpc:latest ./mpc-service
docker build -t ghcr.io/luxfi/bridge-server:latest ./app/server
docker build -t ghcr.io/luxfi/bridge-ui:latest -f app/bridge/Dockerfile .
# Push to registry
docker push ghcr.io/luxfi/bridge-mpc:latest
docker push ghcr.io/luxfi/bridge-server:latest
docker push ghcr.io/luxfi/bridge-ui:latest
```
3. **Then use Docker Compose**:
```bash
make up
```
## Current Infrastructure
- **NATS**: Already running on port 4222
- **Consul**: Already running on port 8500
- **MPC Nodes**: Running locally with the lux-mpc binary
- **Database**: Can use existing PostgreSQL or run: `docker run -d -p 5432:5432 -e POSTGRES_PASSWORD=bridge postgres`
The bridge is ready for development and testing!
docs/MIGRATION-TO-GO-MPC.md
-233
View File
@@ -1,233 +0,0 @@
# Migration Guide: Rust MPC to Go-based Lux MPC
This guide documents the migration from the legacy Rust-based MPC implementation to the modern Go-based Lux MPC.
## Overview
The Lux Bridge is migrating from KZen's `multi-party-ecdsa` (Rust) to Lux MPC (Go) for improved:
- Performance (30% faster signatures)
- Maintainability (single language stack)
- Features (key resharing, batch signing)
- Integration (native Consul/NATS support)
## Architecture Changes
### Before (Rust MPC)
```
Bridge Server → Spawns Rust Process → File-based Keys → Manual Coordination
```
### After (Go MPC)
```
Bridge Server → NATS Messages → Consul Service Discovery → Distributed Keys
```
## Migration Steps
### 1. Deploy New Infrastructure
```bash
# Start new MPC infrastructure
./launch-mpc-bridge.sh start local
# Verify services
docker-compose -f docker-compose.mpc.yaml ps
```
### 2. Initialize MPC Keys
```bash
# Run initialization script
./scripts/init-mpc.sh
# Verify in Consul UI
open http://localhost:8500/ui/dc1/kv/bridge/mpc/
```
### 3. Update Bridge Code
The bridge server now uses the new MPC service:
```typescript
// OLD: app/server/src/domain/mpc.ts
import { getSigFromMpcOracleNetwork } from "./mpc"
// NEW: app/server/src/domain/mpc-modern.ts
import { getSigFromMpcOracleNetwork } from "./mpc-modern"
```
### 4. Test Integration
```bash
# Run E2E tests
./launch-mpc-bridge.sh test
# Monitor logs
./launch-mpc-bridge.sh logs
```
### 5. Remove Old Rust Code
Once verified, remove legacy components:
```bash
# Remove old MPC nodes directory
rm -rf mpc-nodes/
# Remove old Docker configs
rm docker-compose.old.yaml
rm -rf k8s.examples/
# Clean up old dependencies
cd app/server
npm uninstall child_process
```
## Key Differences
### Signing Process
**Old (Rust)**:
```typescript
// Spawn process for each signature
const cmd = `./target/release/examples/gg18_sign_client ${params}`
await exec(cmd)
```
**New (Go)**:
```typescript
// Send message via NATS
await bridgeMPC.generateMPCSignature(signData)
```
### Key Storage
**Old**: Files on disk (`keys.store`)
**New**: Encrypted in Consul KV store
### Service Discovery
**Old**: Hardcoded node addresses
**New**: Dynamic via Consul
## Configuration Changes
### Environment Variables
Add to your `.env`:
```env
# NATS Configuration
NATS_URL=nats://localhost:4222
# Consul Configuration
CONSUL_URL=http://localhost:8500
# MPC Settings
MPC_THRESHOLD=2
MPC_TOTAL_NODES=3
MPC_KEY_PREFIX=bridge/mpc
```
### Docker Compose
Use the new `docker-compose.mpc.yaml` instead of the old setup.
### Kubernetes
Apply the new manifests:
```bash
kubectl apply -f k8s/mpc-deployment.yaml
```
## Monitoring
### Health Checks
```bash
# Check MPC network status
curl http://localhost:3000/api/v1/mpc/status | jq
# Check individual nodes
curl http://localhost:8080/health
curl http://localhost:8081/health
curl http://localhost:8082/health
```
### Metrics
Access Grafana dashboards:
- URL: http://localhost:3002
- User: admin
- Pass: admin
## Rollback Plan
If issues arise:
1. **Stop new services**:
```bash
./launch-mpc-bridge.sh stop local
```
2. **Restore old configuration**:
```bash
git checkout origin/main -- mpc-nodes/
git checkout origin/main -- docker-compose.yaml
```
3. **Restart old services**:
```bash
docker-compose up -d
```
## Verification Checklist
- [ ] All MPC nodes are healthy in Consul
- [ ] Test signatures are generated successfully
- [ ] E2E tests pass
- [ ] No errors in bridge server logs
- [ ] Monitoring dashboards show normal metrics
- [ ] Cross-chain transfers work correctly
## Troubleshooting
### MPC nodes not registering
```bash
# Check Consul
docker logs bridge-consul
# Check NATS
docker logs bridge-nats
```
### Signature generation fails
```bash
# Check MPC node logs
docker logs bridge-mpc-0
docker logs bridge-mpc-1
docker logs bridge-mpc-2
```
### Key initialization issues
```bash
# Clear and reinitialize
curl -X DELETE http://localhost:8500/v1/kv/bridge/mpc?recurse=true
./scripts/init-mpc.sh
```
## Benefits After Migration
1. **Performance**: 30% faster signature generation
2. **Reliability**: Automatic failover with Consul
3. **Scalability**: Easy to add more MPC nodes
4. **Monitoring**: Built-in metrics and health checks
5. **Security**: Encrypted key storage in Consul
6. **Maintenance**: Single Go codebase
## Support
For issues or questions:
- Check logs: `./launch-mpc-bridge.sh logs`
- Consul UI: http://localhost:8500
- NATS Monitor: http://localhost:8222
- Grafana: http://localhost:3002
docs/MPC-GO-INTEGRATION.md
-267
View File
@@ -1,267 +0,0 @@
# MPC Go Integration Guide
## Overview
The Lux Bridge uses the `github.com/luxfi/mpc` package directly via Go tooling, eliminating the need for separate Docker containers or service implementations. This provides a cleaner, more integrated approach to running MPC nodes.
## Installation
### Prerequisites
- Go 1.22 or later
- Access to infrastructure services (NATS, Consul, KMS, Lux ID)
### Installing MPC Tools
```bash
# Install all MPC tools
make install-mpc
# Or manually install individual tools
go install github.com/luxfi/mpc/cmd/lux-mpc@latest
go install github.com/luxfi/mpc/cmd/lux-mpc-keygen@latest
go install github.com/luxfi/mpc/cmd/lux-mpc-cli@latest
```
## Architecture
### MPC Network
- **3 nodes** for 2-of-3 threshold signatures
- **HTTP API** on ports 6000-6002
- **gRPC** on ports 9090-9092
- **NATS** for inter-node communication
- **Consul** for service discovery
- **KMS** for secure key storage
- **Lux ID** for authentication
### Integration with Bridge
```
Bridge UI → Bridge Server → MPC Nodes → Blockchain Networks
↓
KMS + Lux ID
```
## Running MPC Network
### 1. Start Infrastructure
```bash
# Start all infrastructure services
make up
# This launches:
# - Lux ID (Casdoor) - Port 8000
# - KMS (Vault) - Port 8200
# - NATS - Port 4223
# - Consul - Port 8501
# - PostgreSQL - Port 5433
# - Lux ID DB - Port 5434
```
### 2. Start MPC Nodes
```bash
# Start the 3-node MPC network
make start-mpc-nodes
# This runs:
# - mpc-node-0 on ports 6000 (HTTP) and 9090 (gRPC)
# - mpc-node-1 on ports 6001 (HTTP) and 9091 (gRPC)
# - mpc-node-2 on ports 6002 (HTTP) and 9092 (gRPC)
```
### 3. Check Status
```bash
# Check MPC node status
lux-mpc-cli status --url http://localhost:6000
# View logs
tail -f logs/mpc-node-0.log
tail -f logs/mpc-node-1.log
tail -f logs/mpc-node-2.log
```
### 4. Stop Network
```bash
# Stop MPC nodes
make stop-mpc-nodes
# Stop infrastructure
make down
```
## Configuration
### Environment Variables
```bash
# NATS Configuration
NATS_URL=nats://localhost:4223
# Consul Configuration
CONSUL_URL=http://localhost:8501
# KMS Configuration
KMS_URL=http://localhost:8200
KMS_TOKEN=myroot
KMS_PROJECT_ID=mpc-bridge
KMS_SECRET_PATH=/mpc
# Lux ID Configuration
LUXID_URL=http://localhost:8000
LUXID_CLIENT_ID=mpc-node-{id}
LUXID_CLIENT_SECRET=mpc-secret
```
### Configuration Files
- `config/mpc/config.yaml` - Main MPC configuration
- `config/mpc/peers.json` - Peer identities
- `data/mpc/node{0,1,2}/` - Node data directories
## Key Management
### Key Generation
```bash
# Generate new MPC keys
lux-mpc-keygen --threshold 2 --total 3
# Generate peer configuration
lux-mpc-cli generate-peers --number 3 --output config/mpc/peers.json
```
### Key Storage
Keys are stored in two locations:
1. **Local**: `data/mpc/node{id}/keys/`
2. **KMS**: Encrypted and stored in Vault at `/mpc/{node-id}/key-share`
## Operations
### Bridge Operations
```bash
# Initiate key generation for a new wallet
lux-mpc-cli keygen --wallet bridge-ethereum --threshold 2
# Request signature
lux-mpc-cli sign --wallet bridge-ethereum --message "0x..."
# List active sessions
lux-mpc-cli sessions --url http://localhost:6000
```
### Monitoring
```bash
# Check node health
curl http://localhost:6000/health
# View Consul services
consul catalog services
# Check NATS connections
nats-sub -s nats://localhost:4223 "bridge.mpc.>"
```
## Security
### Authentication Flow
1. MPC nodes authenticate with Lux ID
2. Obtain JWT tokens for API access
3. Use machine identity for service-to-service auth
### Key Security
- Keys never exist in complete form
- Threshold signatures require 2 of 3 nodes
- All keys encrypted at rest in KMS
- Audit logging for all operations
## Troubleshooting
### Common Issues
1. **MPC tools not found**
```bash
# Add Go bin to PATH
export PATH="$PATH:$(go env GOPATH)/bin"
```
2. **Connection failures**
- Check infrastructure services are running with `docker ps`
- Verify network connectivity
- Check firewall rules
3. **Key generation fails**
- Ensure all 3 nodes are running
- Check NATS connectivity on port 4223
- Verify Consul registration on port 8501
4. **Identity file errors**
- Generate identity files: `lux-mpc-cli generate-identity --node nodeX --peers config/mpc/peers.json --output-dir data/mpc/nodeX`
- Ensure all nodes have access to all identity files
- Check file permissions
### Debug Mode
```bash
# Run with debug logging
LOG_LEVEL=debug make start-mpc-nodes
# Enable verbose output
lux-mpc-cli --verbose status
```
## Development
### Building from Source
```bash
# Clone MPC repository
git clone https://github.com/luxfi/mpc.git
cd mpc
# Build all binaries
make build
# Run tests
make test
```
### Integration Testing
```bash
# Run MPC integration tests
cd test && ./test-mpc-e2e.sh
# Test bridge integration
./test-bridge-integration.sh
```
## Migration from Docker
If migrating from the Docker-based setup:
1. Stop all Docker containers
2. Install MPC tools via `go install`
3. Copy any existing keys from Docker volumes
4. Start MPC nodes with the new setup
5. Verify operations with test transactions
## Benefits of Go Integration
1. **Simplified Deployment** - No Docker overhead
2. **Direct Integration** - Use MPC as a Go library
3. **Better Performance** - Native binaries
4. **Easier Development** - Standard Go tooling
5. **Unified Codebase** - Single repository for all MPC code
## Future Enhancements
- Automated key rotation
- Multi-region deployment
- Hardware security module integration
- Advanced monitoring and alerting
docs/MPC-INTEGRATION-COMPLETE.md
-135
View File
@@ -1,135 +0,0 @@
# MPC Integration Complete - Lux Bridge
## Summary
The MPC (Multi-Party Computation) integration for the Lux Bridge has been successfully completed. The bridge now uses a modern Go-based MPC implementation with threshold signatures for secure cross-chain operations.
## What Was Done
### 1. Infrastructure Setup ✅
- **Docker Compose Files**: Updated all compose files to use `ghcr.io/luxfi` images
- `compose.yml` - Local development
- `compose.mainnet.yml` - Production mainnet deployment
- `compose.testnet.yml` - Testnet deployment
- **Makefile**: Created comprehensive Makefile for easy deployment
- `make up` - Start local development
- `make mainnet` - Deploy to mainnet
- `make testnet` - Deploy to testnet
### 2. MPC Components ✅
- **MPC Service**: Go-based implementation in `mpc-service/`
- **Integration Layer**: TypeScript wrappers in `app/server/src/domain/`
- `mpc-service.ts` - Modern MPC service wrapper
- `mpc-bridge.ts` - Bridge-specific integration
- `mpc-modern.ts` - Drop-in replacement
- **Local Binaries**: Pre-built MPC binaries available
- `lux-mpc` - Main MPC node binary
- `lux-mpc-cli` - CLI management tool
### 3. Scripts Created ✅
- **start-mpc-local.sh**: Start MPC nodes locally without Docker
- **stop-mpc-local.sh**: Stop local MPC nodes
- **build-mpc-docker.sh**: Build Docker image with local dependencies
- **scripts/init-mpc.sh**: Initialize MPC keys (already existed)
### 4. Configuration ✅
- **config.yaml**: Main configuration file
- **peers.json**: Peer configuration
- **Identity Files**: Generated for node0, node1, node2
## Current Status
### ✅ Working
- All infrastructure components configured
- Docker Compose files use ghcr.io/luxfi images
- MPC nodes can be started locally
- Identity generation working
- NATS and Consul integration functional
- Node0 running successfully
### ⚠️ Known Issues
- MPC nodes showing high CPU usage
- Health endpoints not responding on expected ports
- May need HTTP server configuration
## Quick Start
### Using Docker (Recommended)
```bash
# Start everything
make up
# View logs
make logs
# Stop everything
make down
```
### Using Local Binaries
```bash
# Start MPC nodes locally
./start-mpc-local.sh
# Initialize keys
./scripts/init-mpc.sh
# Stop nodes
./stop-mpc-local.sh
```
### Production Deployment
```bash
# Deploy to mainnet
make mainnet
# Deploy to testnet
make testnet
```
## Architecture
```
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Bridge UI │────▶│ Bridge Server │────▶│ MPC Nodes │
│ (React/Next.js) │ │ (TypeScript) │ │ (Go/Rust) │
└─────────────────┘ └─────────────────┘ └─────────────────┘
│ │
▼ ▼
┌─────────────┐ ┌─────────────┐
│ PostgreSQL │ │ NATS │
└─────────────┘ └─────────────┘
│
▼
┌─────────────┐
│ Consul │
└─────────────┘
```
## Key Features
1. **Threshold Signatures**: 2-of-3 threshold for security
2. **Protocol Support**: ECDSA and EdDSA
3. **Service Discovery**: Consul-based node discovery
4. **Message Queue**: NATS for reliable messaging
5. **Monitoring**: Prometheus and Grafana integration
6. **Multi-Environment**: Local, testnet, and mainnet configs
## Next Steps
1. **Performance Optimization**: Investigate high CPU usage
2. **HTTP Server**: Ensure health endpoints are properly configured
3. **Testing**: Run comprehensive E2E tests
4. **Documentation**: Update user-facing documentation
5. **CI/CD**: Ensure GitHub Actions properly build and push images
## Resources
- [MPC Documentation](/mpc-service/README.md)
- [Bridge Documentation](/CLAUDE.md)
- [Deployment Guide](/DEPLOYMENT.md)
- [Migration Guide](/MIGRATION-TO-GO-MPC.md)
---
*Integration completed on August 3, 2025*
docs/MPC-MODERNIZATION-SUMMARY.md
-154
View File
@@ -1,154 +0,0 @@
# Lux Bridge MPC Modernization - Complete Summary
## What We've Accomplished
We've successfully modernized the Lux Bridge by replacing the legacy Rust-based MPC implementation with a modern Go-based solution using Lux MPC. This provides better performance, maintainability, and integration with the Lux ecosystem.
## Key Components Created
### 1. Bridge MPC Service (`app/server/src/services/mpc-service.ts`)
- Modern TypeScript service using NATS and Consul
- Distributed key management with automatic service discovery
- Threshold signature coordination
- Health monitoring and status reporting
### 2. Bridge MPC Integration (`app/server/src/domain/mpc-bridge.ts`)
- Drop-in replacement for old MPC calls
- Maintains API compatibility
- Async signature generation with proper error handling
- Session management and timeout protection
### 3. Modern MPC API (`app/server/src/domain/mpc-modern.ts`)
- Direct replacement for old `mpc.ts`
- Same function signatures for easy migration
- Enhanced error handling and logging
### 4. Docker Infrastructure (`docker-compose.mpc.yaml`)
- Complete containerized setup with:
- NATS for messaging
- Consul for service discovery
- 3 MPC nodes (2-of-3 threshold)
- PostgreSQL database
- Prometheus + Grafana monitoring
- Bridge server and UI
### 5. Kubernetes Deployment (`k8s/mpc-deployment.yaml`)
- Production-ready K8s manifests
- StatefulSets for MPC nodes
- Persistent storage for keys
- Load balancers for external access
- TLS ingress configuration
### 6. Initialization Scripts
- `scripts/init-mpc.sh` - Automated MPC key generation
- `launch-mpc-bridge.sh` - One-command deployment
### 7. Comprehensive Testing (`test/e2e/mpc-integration.test.ts`)
- Full E2E test suite
- Security tests (replay protection)
- Performance benchmarks
- Concurrent request handling
## Architecture Benefits
### Before (Rust MPC)
```
Node.js → Spawn Rust Process → File I/O → Manual Coordination
↓
Slow & Error-prone
```
### After (Go MPC)
```
Node.js → NATS Message → Consul Discovery → Distributed MPC
↓
Fast & Reliable
```
## Performance Improvements
1. **30% Faster Signatures**: CGG21 protocol vs old GG18
2. **No Process Spawning**: Direct message passing
3. **Parallel Processing**: Concurrent signature generation
4. **Better Resource Usage**: Shared memory vs separate processes
## Security Enhancements
1. **Encrypted Key Storage**: Keys in Consul with encryption
2. **Service Authentication**: Mutual TLS between nodes
3. **Replay Protection**: Transaction hash tracking
4. **Threshold Security**: 2-of-3 signatures required
## How to Deploy
### Local Development
```bash
# Start everything
./launch-mpc-bridge.sh start local
# Initialize MPC keys
./launch-mpc-bridge.sh init
# Run tests
./launch-mpc-bridge.sh test
```
### Production (Kubernetes)
```bash
# Deploy to K8s
./launch-mpc-bridge.sh start k8s
# Check status
kubectl get pods -n lux-bridge
```
## Migration Path
1. **Deploy new infrastructure** alongside existing Rust nodes
2. **Run in shadow mode** to compare signatures
3. **Gradually route traffic** to new implementation
4. **Monitor metrics** in Grafana
5. **Decommission old nodes** once verified
## What's Next
The bridge is now ready for:
- Production deployment
- Performance testing at scale
- Integration with other Lux services
- Additional security audits
## Files Changed/Added
### New Files Created:
- `/app/server/src/services/mpc-service.ts`
- `/app/server/src/domain/mpc-bridge.ts`
- `/app/server/src/domain/mpc-modern.ts`
- `/app/server/src/domain/lux-mpc.ts`
- `/docker-compose.mpc.yaml`
- `/k8s/mpc-deployment.yaml`
- `/scripts/init-mpc.sh`
- `/launch-mpc-bridge.sh`
- `/test/e2e/mpc-integration.test.ts`
- `/deployments/bridge/` (directory with configs)
- `/MIGRATION-TO-GO-MPC.md`
- `/MPC-MODERNIZATION-SUMMARY.md`
### Lux MPC Files:
- `/pkg/bridge/compatibility.go`
- `/cmd/lux-mpc-bridge/main.go`
- Various deployment configs
## Conclusion
The Lux Bridge now has a modern, scalable, and secure MPC implementation that's fully integrated with the Lux ecosystem. The old Rust-based system can be safely decommissioned once the new system is validated in production.
Key advantages:
- ✅ Better performance (30% faster)
- ✅ Easier maintenance (single language)
- ✅ Enhanced security (encrypted storage)
- ✅ Better monitoring (Prometheus/Grafana)
- ✅ Cloud-native (K8s ready)
- ✅ Fully tested (E2E suite)
The bridge is ready for the future of cross-chain operations!