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: refresh README + Nextra index + LLM key docs list (issue #391)

Browse Source 
- README.md: replace stale 'Bridge UI → Bridge Server → MPC Nodes' diagram
    with the v1.1.x topology (inlined UI, direct threshold integration,
    layered cosigners). Remove dead links to docs that v1.1.12 deleted
    (MPC-GO-INTEGRATION, CI-CD-DOCKER-IMAGES). Add pointer to issue #392
    for the new bridge dev.

  - docs/LLM.md: refresh 'Key Documentation Files' list to remove the
    deleted MPC-GO/DEPLOYMENT/MIGRATION-TO-GO references; document the
    Nextra site path (`docs/pages/*.mdx`); reframe the migration-files
    history as a v1.1.12 deletion event with the commit hash.

  - docs/content/docs/index.mdx: refresh the architecture diagram inside
    the Nextra site itself so the public docs match the new topology.
    Add the protocol class table (classical vs PQ-safe lattice) and the
    optional-layered-cosigners line. The diagram now matches LLM.md and
    the top-level README — three places, one story.

Closes the remainder of #391.
This commit is contained in:
zeekay
2026-05-22 00:07:59 -07:00
parent 8c195080f9
commit 5ced993961
3 changed files with 91 additions and 39 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+34 -7
View File
@@ -113,14 +113,34 @@ cd app/bridge && pnpm dev
## Architecture
```
Bridge UI → Bridge Server → MPC Nodes → Blockchain Networks
↓
KMS + Lux ID + Consul
Tenant app (Lux, Hanzo, Zoo, …)
imports @luxfi/bridge + @<org>/brand
│
▼
@luxfi/bridge (pkg/bridge)
Bridge UI inlined under src/app/
Direct deps: @hanzo/gui, @luxfi/threshold, wagmi, viem
│
┌───────┴────────┐
▼ ▼
app/server @luxfi/threshold
Express+Prisma MPC SDK (also consumed by app/server)
│
▼
m-chain (public MPC, 2-of-3 threshold)
+ optional private cluster (treasury fees)
+ optional layered cosigners (Utila / Fireblocks)
```
See [`docs/LLM.md`](docs/LLM.md) for the full topology, MPC protocol list
(`cggmp21`, `frost`, `bls`, `doerner`, `pulsar`, `corona`, `magnetar`),
layered-cosigner pattern, and explorer-migration plan.
## Key Features
- **MPC Security**: 2-of-3 threshold signatures
- **MPC Security**: 2-of-3 threshold signatures (also PQ-safe lattice variants)
- **Layered cosigners** (since SDK v1.0.3): optional Utila / Fireblocks
cosign on top of native MPC for institutional flows
- **Multi-Chain**: Support for EVM and non-EVM chains
- **Unified Auth**: Lux ID (Casdoor) integration
- **Key Management**: Secure key storage in KMS
@@ -145,9 +165,16 @@ make down # Stop infrastructure
## Documentation
- [MPC Go Integration](docs/MPC-GO-INTEGRATION.md)
- [Lux ID Integration](docs/LUX-ID-INTEGRATION.md)
- [CI/CD Docker Images](docs/CI-CD-DOCKER-IMAGES.md)
- [`docs/LLM.md`](docs/LLM.md) — canonical AI/onboarding doc: architecture,
package layout, MPC topology, runtime config, publishing status, layered
cosigners, explorer migration plan
- [`docs/LUX-ID-INTEGRATION.md`](docs/LUX-ID-INTEGRATION.md) — Lux ID
(Casdoor) auth integration
- [`pkg/bridge/README.md`](pkg/bridge/README.md) — consumer-facing SDK
README (`mountBridge`, `BridgeConfig`, all config blocks)
For the new bridge dev: [issue #392](https://github.com/luxfi/bridge/issues/392)
is the entry point — read order, repo map, open issues by priority.
## Tips
docs/LLM.md
+15 -9
View File
@@ -431,17 +431,23 @@ nats-top -s localhost:4223
## Documentation
### Comprehensive Documentation Site
- **Location**: `/Users/z/work/lux/bridge/docs/content/docs/index.mdx`
- **Build**: `cd docs && npm run build`
- **View**: `cd docs && npm run dev` → http://localhost:3001
- **Status**: ✅ Built successfully (November 2024)
### Comprehensive Documentation Site (Nextra)
- **Location**: `~/work/lux/bridge/docs/` (Next.js + Nextra)
- **Pages**: `docs/pages/*.mdx`
- **Build**: `cd docs && pnpm install && pnpm build`
- **Dev**: `cd docs && pnpm dev` → http://localhost:3000
### Key Documentation Files
- `docs/MPC-GO-INTEGRATION.md` - MPC setup and configuration
- `docs/LUX-ID-INTEGRATION.md` - Authentication integration
- `docs/DEPLOYMENT.md` - Production deployment guide
- `docs/MIGRATION-TO-GO-MPC.md` - Migration from Docker to Go
- `docs/LLM.md` — this file, canonical AI/onboarding doc (single source of truth)
- `docs/LUX-ID-INTEGRATION.md` — Casdoor-based unified auth integration
- `pkg/bridge/README.md` — consumer-facing SDK docs (`mountBridge`, `BridgeConfig`)
- Top-level `README.md` — quick-start + architecture pointer (kept consistent with this file)
The legacy migration .md files (BRIDGE-STATUS, LOCAL-SETUP, the four MPC
migration notes, DEPLOYMENT, CI-CD-DOCKER-IMAGES) were deleted in v1.1.12
(commit `b04e805`, issue #391) — they described an architecture from
before the SDK rationalization and confused new readers. Migration
history lives in `git log` and the GH release notes.
## Context for All AI Assistants
docs/content/docs/index.mdx
+42 -23
View File
@@ -17,39 +17,58 @@ The Lux Bridge architecture consists of several interconnected layers:
```
┌─────────────────────────────────────────────────────────────┐
│ Bridge UI │
│ (React/Next.js Frontend) │
└──────────────────────────┬──────────────────────────────────┘
│
┌──────────────────────────▼──────────────────────────────────┐
│ Bridge Server │
│ (API & Business Logic) │
└──────────────────────────┬──────────────────────────────────┘
│
┌──────────────────────────▼──────────────────────────────────┐
│ MPC Node Network │
│ (3-node threshold signature) │
└──────────────────────────┬──────────────────────────────────┘
│
┌──────────────────────────▼──────────────────────────────────┐
│ Infrastructure Services │
│ (KMS, Lux ID, NATS, Consul, PostgreSQL) │
└──────────────────────────┬──────────────────────────────────┘
│
┌──────────────────────────▼──────────────────────────────────┐
│ Blockchain Networks │
│ (Lux, Ethereum, BSC, Polygon, Arbitrum, zkSync, etc) │
│ Tenant app (Lux, Hanzo, Zoo, …) — ~120 LOC Vite SPA │
│ imports @luxfi/bridge + @<org>/brand │
└────────────────────────┬────────────────────────────────────┘
│
┌────────────────────────▼────────────────────────────────────┐
│ @luxfi/bridge — public SDK (pkg/bridge) │
│ Bridge UI INLINED under src/app/ (no lazy workspace deps) │
│ Direct deps: @hanzo/gui (Tamagui), @luxfi/threshold, │
│ wagmi, viem, @tanstack/react-query │
└─────────────┬────────────────────────────┬──────────────────┘
│ │
┌─────────────▼──────────────┐ ┌─────────▼──────────────────┐
│ app/server │ │ @luxfi/threshold (T-Chain) │
│ Bridge API │ │ MPC threshold-sign SDK │
│ Express + Prisma │ │ (consumed by BOTH the │
│ api.bridge.lux.network │ │ bridge SDK + app/server) │
└─────────────┬──────────────┘ └─────────┬──────────────────┘
│ │
┌─────────────▼──────────────┐ ┌─────────▼──────────────────┐
│ Infrastructure │ │ m-chain — public MPC │
│ KMS, Lux ID (Casdoor), │ │ 2-of-3 threshold network │
│ NATS, Consul, PostgreSQL │ │ + optional private cluster │
└─────────────┬──────────────┘ │ + optional layered cosign │
│ │ (Utila / Fireblocks) │
│ └────────────────────────────┘
┌─────────────▼───────────────────────────────────────────────┐
│ Blockchain Networks │
│ (Lux, Ethereum, BSC, Polygon, Arbitrum, zkSync, etc) │
└─────────────────────────────────────────────────────────────┘
```
### Multi-Party Computation (MPC)
The bridge employs a 2-of-3 threshold signature scheme using MPC technology:
The bridge employs a 2-of-3 threshold signature scheme using MPC technology.
Native protocol set (`BridgeMPCConfig.protocol`):
| Class | Protocols |
|---|---|
| Classical ECDSA | `cggmp21` (default), `doerner` |
| Classical EdDSA | `frost` |
| Classical BLS | `bls` |
| **PQ-safe lattice** | `pulsar`, `corona`, `magnetar` |
The last three are post-quantum-safe and leaderless by construction.
- **Distributed Key Generation**: Private keys are never fully reconstructed
- **Threshold Signatures**: Any 2 of 3 nodes can sign transactions
- **No Single Point of Failure**: Compromise of one node doesn't affect security
- **Cryptographic Validation**: All operations verified through zero-knowledge proofs
- **Optional layered cosigners** (since SDK v1.0.3): Utila or Fireblocks
as additional cosigners on top of native MPC; backend enforces 2-of-2
(native + listed) before releasing settlement
### Security Model