Lux Teleport - Zero-Knowledge MPC Cross-Chain Bridge

Overview

Lux Teleport is a cross-chain bridge protocol using Multi-Party Compute (MPC) nodes for decentralized oracle operations and threshold signature-based asset transfers. It features zero-knowledge privacy -- signers do not know details about assets being teleported. Built as a pnpm monorepo with Solidity contracts, TypeScript API/MPC services, and a frontend app.

Quick reference

Hard requirements

1. ALWAYS use github.com/luxfi/* references -- NEVER go-ethereum or luxfi
2. Use EIP-712 typed data signing for all bridge signatures
3. Derive all claim fields from on-chain logs -- NEVER from request parameters
4. Use spawn() for MPC process invocation -- NEVER exec() (shell injection risk)

Architecture

teleport/
├── contracts/           # Solidity smart contracts
│   └── contracts/
│       ├── Bridge.sol         # Main bridge (EIP-712, role-based)
│       ├── ERC20B.sol         # Bridgeable token
│       └── IBridgeToken.sol   # Token interface
├── api/                 # Bridge API service (TypeScript)
│   └── src/
│       └── bridge.ts          # POST endpoints, event parsing
├── mpc/                 # MPC signing service (TypeScript)
│   └── src/
│       └── teleporter.ts      # Secure MPC signing
├── app/                 # Frontend UI
├── multi-party-ecdsa/   # Rust MPC library (git submodule, GG18/GG20)
├── package.json         # Root workspace config
└── pnpm-workspace.yaml  # Workspace: app, api, mpc, contracts

Smart Contracts

Bridge.sol

Main bridge contract with EIP-712 domain TeleportBridge version 1:

• Roles: ADMIN_ROLE (token whitelist, oracle management), ORACLE_ROLE (MPC signers), PAUSER_ROLE (emergency)
• Replay protection: claimId = keccak256(abi.encode(...all claim fields...)) -- NOT signature bytes
• Token whitelisting: Only admin-approved tokens can be bridged
• Fee caps: Maximum 10% fee rate

// Burn tokens with committed destination (all data in event)
function bridgeBurn(
    address token, uint256 amount,
    uint256 toChainId, address recipient, bool vault
) external returns (bytes32 burnId);

// Mint tokens with EIP-712 signature verification
function bridgeMint(
    ClaimData calldata claim, bytes calldata signature
) external returns (bytes32 claimId);

ERC20B.sol

Bridgeable ERC20 token with BRIDGE_ROLE for mint/burn access, Pausable for emergency freeze.

API Service

TypeScript service at api/src/bridge.ts:

Security: POST-only for sensitive data, rate limiting (100 req/15 min/IP), Helmet headers, strict hex validation.

MPC Service

TypeScript service at mpc/src/teleporter.ts:

• Invokes Rust multi-party-ecdsa binaries via spawn() (not exec)
• GG18/GG20 keygen via gg18_keygen_client binary
• Strict hex validation: /^[0-9a-f]\{64\}$/i
• Bounded retries with exponential backoff (max 3)
• Graceful SIGTERM shutdown

Keygen Setup

cd ./target/release/examples/
./gg20_sm_manager  # Start signing manager on port 8000

# Each party in separate terminal:
./gg18_keygen_client http://yourIP:port keys1.store
./gg18_keygen_client http://yourIP:port keys2.store
./gg18_keygen_client http://yourIP:port keys3.store

One-file quickstart

Build

git clone https://github.com/luxfi/teleport.git
cd teleport

# Contracts
cd contracts && pnpm install && pnpm build

# API
cd api && pnpm install && pnpm build

# MPC
cd mpc && pnpm install && pnpm build

Run

# Start MPC node
npm run node

# Requires: MongoDB, Rust (for multi-party-ecdsa), Node.js 18+

Test

cd contracts && pnpm test   # 36 passing tests
cd api && pnpm test
cd mpc && pnpm test

Configuration

api/settings.json

{
  "RPC": { "<chainId>": "<rpc_url>" },
  "Bridges": { "<chainName>": "<address>" },
  "AllowedTokens": { "<token>": { "<chain>": "<address>" } },
  "DB": "<mongodb_password>",
  "SigningManagers": { "0": "<url>" },
  "KeyStore": { "0": "<filename>" }
}

mpc/settings.json

{
  "RPC": { "<chainId>": "<rpc_url>" },
  "Teleporter": { "<chainName>": "<address>" },
  "MPCPeers": { "0": "<host>, <ip>" },
  "KeyStore": { "0": "<filename>" },
  "SMTimeout": "1"
}

Security Model

Privacy Layer (v1.2.0+)

Extends Teleport with fully private bridging:

• FHE encrypted amounts: Pedersen commitments + FHE via luxfi/fhe
• Bulletproof range proofs: Verify amounts without revealing values (BN254 precompiles)
• ZNote: UTXO-style shielded notes for X-Chain integration
• Z-Chain AMM: Homomorphic private swaps (encrypted reserves, encrypted orders)
• Dark pools: MEV-resistant hidden order matching

Privacy Contracts

EVM Precompiles

Bridge uses BN254 precompiles (EIP-1108) for ZK verification, active from genesis on Lux:

BLS12-381 (EIP-2537) available via Prague upgrade for Quasar consensus proofs.

Roadmap

Troubleshooting

Related Skills

• lux/lux-mpc.md -- Go-based MPC daemon (newer, production)
• lux/lux-threshold.md -- Threshold signature library
• lux/lux-bridge.md -- Bridge infrastructure
• lux/lux-fhe.md -- FHE primitives for privacy layer