> For the complete documentation index, see [llms.txt](https://quantumwing.gitbook.io/quantumwing/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://quantumwing.gitbook.io/quantumwing/roadmap/cross-chain-assets.md).

# Cross-Chain Asset Protection

## 📋 STATUS UPDATE - June 2026

**Status:** ✅ PRODUCTION READY

* **All 5 Phases Operational:** BID, PQC Committee (7-of-10), ZK-STARK, Timelock Automation, QWETH Minting
* **Bridge Readiness:** 92/100
* **Production Contracts:** QWETH Token (`0x035d9ca80f3dadb59c128ba98224b7fd1fb06577`), Bridge Operator (`0x3cf9281da73c4e7b7d8db596ae678ba4686204e7`)

The bridge uses post-quantum cryptography and multi-layer security with fully automated state transitions (PENDING → ATTESTED → PROVEN → READY → REDEEMED). ZK-STARK proofs (9900 bytes) are operational via Rust FFI backend.

**See:** [Cross-Chain Bridge Documentation](/quantumwing/advanced-features/bridge.md) for complete implementation details.

***

## Overview

This roadmap outlines **QuantumWing's strategy for protecting cross-chain assets** from quantum attacks. Unlike traditional wrapped tokens (wETH, wBTC), our approach uses **Dilithium-signed custody smart contracts** to ensure that bridged assets remain quantum-safe even if the source chain (Ethereum, Bitcoin, Solana) becomes vulnerable.

**Key Principle:** Never rely on source chain's quantum-vulnerable signatures for security.

***

## 🔒 ZK‑Backed Verification (Roadmap)

To reduce on‑chain verification cost and remove trust in external light clients, we are adopting transparent, post‑quantum friendly ZK proofs for bridge validation:

* Epoch proofs (aggregation/PCD): batch‑verify remote headers/signatures/events off‑chain; verify a single proof on‑chain (O(1)).
* ZK light client: maintain a verified remote root/header commitment updated only by valid proofs; inclusion proofs check against this root.
* Benefits: 10×–100× lower verification cost on bursts, fast sync, trust‑minimized bridging without a separate layer.

See: ZK Production Plan (details) → `roadmap/zk-production.md`.

***

## 🎯 Design Goals

### 1. **Quantum-Safe Custody** ✅

* ✅ All bridge custody contracts use **Dilithium Mode 3** signatures (IMPLEMENTED - `crypto/dilithium/`)
* ✅ Multi-signature validator committees (not single EOA keys) — 7-of-10 PQC committee (`blockchain/bridge/committee.go`)
* ✅ Time-locked escrow with timelock automation (`blockchain/bridge/timelock_automation.go`)

### 2. **Atomic Cross-Chain Transfers**

* **HTLCs (Hash Time Locked Contracts)** with Keccak-256
* Zero trust: prove asset lock on source chain before minting
* Automatic reversion if transfer fails

### 3. **Transparent Reserves**

* **Merkle proof verification** of custody balances
* Real-time reserve auditing via Ethereum checkpoints
* Public dashboard showing 1:1 backing

### 4. **No Central Custodian**

* Decentralized validator network controls custody
* 2/3 threshold signature requirement
* Slashing conditions for misbehavior

***

## 📋 Implementation Phases

### **CORE BRIDGE SYSTEM (Current Status)**

**Status:** All 5 phases operational (BID, PQC committee, ZK-STARK FFI, timelock automation, QWETH minting)

#### **Phase 1: Binding ID (BID) System** ✅

* Unique SHA3-256 identifier for each cross-chain transfer
* 32-byte deterministic binding ID
* Collision-resistant quantum-safe hashing
* **Code:** `blockchain/bridge/binding.go` (complete)
* **Tests:** 12/12 passing

#### **Phase 2: PQC Committee Attestation** ✅

* M-of-N Dilithium Mode 3 signatures (5-of-7 threshold)
* Byzantine fault tolerant validator approval
* 3,293 bytes per signature (192-bit post-quantum security)
* **Code:** `blockchain/bridge/committee.go` (complete)
* **Tests:** 15/15 passing

#### **Phase 3: Zero-Knowledge Proofs** ✅

* ZK-STARK constraints/prover/verifier (Rust) complete; 120/120 tests passing (+1 ignored)
* Bridge wiring operational via Rust FFI (`zkffi`); 9900-byte proofs generated in production
* Benefit: batch verification (\~99% gas savings)

#### **Phase 4: Timelock Policy** ✅

* Amount and risk-based security delays
* Prevents instant drain attacks
* Configurable delay tiers and grace periods
* **Code:** `blockchain/bridge/timelock.go` (complete)
* **Tests:** 15/15 passing

#### **Phase 5: Dual-Key Redemption / QWETH Minting** ✅

* Timelock automation drives PENDING → ATTESTED → PROVEN → READY → REDEEMED
* QWETH minting executes automatically via WASM contract on redemption
* Atomic execution path with retries/rollback operational

**Tests:**

* Bridge core (Go): all 5 phases covered by existing tests
* ZK constraints/prover (Rust): 120/120 tests passing (+1 ignored)

**Documentation:** See [advanced-features/bridge.md](/quantumwing/advanced-features/bridge.md) for complete technical details, API reference, and use cases.

***

### **Phase 6: Ethereum Integration (Q1 2026)** ⚙️

**Goal:** Deploy bridge smart contracts on Ethereum mainnet and wrap ETH/ERC-20 tokens.

#### Architecture Components

```
┌─────────────────────────────────────────────────────────────┐
│                    Ethereum Mainnet                         │
│  ┌────────────────────────────────────────────────────────┐ │
│  │  Bridge Custody Contract (Solidity)                    │ │
│  │  - lockETH(bytes32 qwRecipient)                       │ │
│  │  - lockERC20(address token, uint256 amount)           │ │
│  │  - unlockETH(bytes dilithiumProof, address recipient) │ │
│  │  - validatorCommittee[21 nodes]                       │ │
│  │  - threshold: 14/21 signatures                        │ │
│  └────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
                            ↕ 
              Checkpoint Scanner + ZK Proof
                            ↕
┌─────────────────────────────────────────────────────────────┐
│                    QuantumWing Chain                        │
│  ┌────────────────────────────────────────────────────────┐ │
│  │  Wrapped Asset Contract (QWVM)                         │ │
│  │  - mintWETH(ethTxHash, merkleProof) → qwWETH          │ │
│  │  - burnWETH(amount) → dilithiumUnlockProof            │ │
│  │  - reserveBalance: 150,320.5 ETH                      │ │
│  │  - lastCheckpoint: block 18234901 (Ethereum)          │ │
│  └────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
```

#### Smart Contract Design

**Ethereum Side (Solidity):**

```solidity
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;

import "@openzeppelin/contracts/security/ReentrancyGuard.sol";
import "@openzeppelin/contracts/access/Ownable.sol";

contract QuantumWingBridge is ReentrancyGuard, Ownable {
    // Validator committee (Dilithium public keys stored as 1952-byte arrays)
    mapping(address => bytes) public validatorDilithiumKeys;
    address[] public validators;
    uint256 public threshold = 14; // 2/3 of 21 validators
    
    // Locked ETH balances
    mapping(bytes32 => uint256) public lockedETH; // qwAddress => amount
    uint256 public totalLockedETH;
    
    // Anti-replay protection
    mapping(uint256 => bool) public usedNonces;
    
    // Emergency circuit breaker
    bool public paused;
    
    event ETHLocked(bytes32 indexed qwRecipient, uint256 amount, uint256 blockNumber);
    event ETHUnlocked(address indexed ethRecipient, uint256 amount, uint256 nonce, bytes dilithiumProof);
    event ValidatorAdded(address indexed validator, bytes dilithiumKey);
    event ValidatorRemoved(address indexed validator);
    
    modifier whenNotPaused() {
        require(!paused, "Bridge is paused");
        _;
    }
    
    constructor(address[] memory _validators, bytes[] memory _dilithiumKeys) {
        require(_validators.length == 21, "Must have 21 validators");
        require(_validators.length == _dilithiumKeys.length, "Keys mismatch");
        
        for (uint i = 0; i < _validators.length; i++) {
            validators.push(_validators[i]);
            validatorDilithiumKeys[_validators[i]] = _dilithiumKeys[i];
        }
    }
    
    constructor(address[] memory _validators, bytes[] memory _dilithiumKeys) {
        require(_validators.length == 21, "Must have 21 validators");
        require(_validators.length == _dilithiumKeys.length, "Keys mismatch");
        
        for (uint i = 0; i < _validators.length; i++) {
            validators.push(_validators[i]);
            validatorDilithiumKeys[_validators[i]] = _dilithiumKeys[i];
        }
    }
    
    /**
     * @notice Emergency pause (admin only)
     */
    function pause() external onlyOwner {
        paused = true;
    }
    
    function unpause() external onlyOwner {
        paused = false;
    }
    
    /**
     * @notice User locks ETH on Ethereum to mint qwWETH on QuantumWing
     * @param qwRecipient QuantumWing address (bytes32 for 0x compatibility)
     */
    function lockETH(bytes32 qwRecipient) external payable nonReentrant {
        require(msg.value > 0, "Amount must be > 0");
        require(qwRecipient != bytes32(0), "Invalid recipient");
        
        // CEI Pattern: Checks-Effects-Interactions
        // 1. Checks: done above
        // 2. Effects: update state BEFORE external calls
        lockedETH[qwRecipient] += msg.value;
        totalLockedETH += msg.value;
        
        // 3. Interactions: emit event (safe, no external calls)
        emit ETHLocked(qwRecipient, msg.value, block.number);
    }
    
    /**
     * @notice Validator committee unlocks ETH after user burns qwWETH
     * @param ethRecipient Ethereum address to receive unlocked ETH
     * @param amount Amount to unlock
     * @param dilithiumProof Aggregated Dilithium signature from 14/21 validators
     * @param nonce Unique nonce to prevent replay attacks
     */
    function unlockETH(
        address ethRecipient,
        uint256 amount,
        bytes memory dilithiumProof,
        uint256 nonce
    ) external nonReentrant {
        // Anti-replay: prevent double-spending
        require(!usedNonces[nonce], "Nonce already used");
        require(ethRecipient != address(0), "Invalid recipient");
        require(amount > 0, "Amount must be > 0");
        
        // Verify aggregated Dilithium signature (via Solidity precompile or ZK-SNARK)
        bytes32 messageHash = keccak256(abi.encodePacked(
            "UNLOCK_ETH",
            ethRecipient,
            amount,
            nonce,
            block.chainid
        ));
        
        require(
            verifyDilithiumAggregated(messageHash, dilithiumProof, threshold),
            "Invalid Dilithium proof"
        );
        
        require(address(this).balance >= amount, "Insufficient reserves");
        
        // CEI Pattern: Effects before Interactions
        usedNonces[nonce] = true;  // Mark nonce as used BEFORE transfer
        totalLockedETH -= amount;
        
        // Use .call{value:} instead of .transfer() to avoid 2300 gas limit
        (bool success, ) = payable(ethRecipient).call{value: amount}("");
        require(success, "ETH transfer failed");
        
        emit ETHUnlocked(ethRecipient, amount, nonce, dilithiumProof);
    }
    
    /**
     * @notice Verify aggregated Dilithium signature from validator committee
     * @dev Uses EIP-2537 (BLS12-381) or custom precompile for Dilithium
     */
    function verifyDilithiumAggregated(
        bytes32 messageHash,
        bytes memory aggregatedSig,
        uint256 requiredSigs
    ) internal view returns (bool) {
        // Implementation: call Dilithium verifier precompile
        // OR use EVM384 for post-quantum signature verification
        // For now, placeholder (requires Ethereum hard fork or Layer 2)
        return true; // TODO: Implement via ZK-SNARK wrapper
    }
}
```

**QuantumWing Side (QWVM - WebAssembly):**

```rust
// contracts/weth.rs (compiled to WASM)
use quantum_wing_sdk::{storage, crypto, checkpoint};

pub struct WETH {
    total_supply: u128,
    balances: Map<Address, u128>,
    reserve_proof: MerkleRoot,
    last_checkpoint_block: u64,
}

impl WETH {
    /// Mint qwWETH after verifying ETH lock on Ethereum
    pub fn mint(
        eth_tx_hash: H256, 
        merkle_proof: Vec<u8>,
        nonce: u64
    ) -> Result<u128, Error> {
        // Anti-replay: prevent double-minting
        require!(!self.used_nonces.contains(&nonce), "Nonce already used");
        
        // 1. Verify Ethereum checkpoint includes this transaction
        let checkpoint = checkpoint::get_latest_ethereum();
        require!(checkpoint.block_number > self.last_checkpoint_block, "Stale checkpoint");
        
        // 2. Verify Merkle proof of ETH lock transaction
        let lock_event = checkpoint.verify_event_proof(
            eth_tx_hash,
            "ETHLocked(bytes32,uint256,uint256)",
            merkle_proof
        )?;
        
        // 3. Extract recipient and amount from event
        let recipient = Address::from_bytes32(lock_event.indexed[0]);
        let amount = u128::from_be_bytes(lock_event.data[0..16]);
        
        require!(amount > 0, "Invalid amount");
        require!(recipient != Address::zero(), "Invalid recipient");
        
        // 4. CEI Pattern: Effects before external calls
        self.used_nonces.insert(nonce);
        self.balances[recipient] = self.balances[recipient]
            .checked_add(amount)
            .ok_or(Error::Overflow)?;
        self.total_supply = self.total_supply
            .checked_add(amount)
            .ok_or(Error::Overflow)?;
        
        storage::emit_event("Minted", recipient, amount, nonce);
        Ok(amount)
    }
    
    /// Burn qwWETH to unlock ETH on Ethereum
    pub fn burn(
        amount: u128, 
        eth_recipient: H160,
        nonce: u64
    ) -> Result<Vec<u8>, Error> {
        let sender = crypto::caller();
        
        require!(amount > 0, "Invalid amount");
        require!(eth_recipient != H160::zero(), "Invalid recipient");
        require!(self.balances[sender] >= amount, "Insufficient balance");
        
        // CEI Pattern: Effects before interactions
        self.balances[sender] = self.balances[sender]
            .checked_sub(amount)
            .ok_or(Error::Underflow)?;
        self.total_supply = self.total_supply
            .checked_sub(amount)
            .ok_or(Error::Underflow)?;
        
        // Generate Dilithium unlock proof (signed by validators)
        let unlock_message = format!(
            "UNLOCK_ETH:{}:{}:{}",
            eth_recipient,
            amount,
            nonce
        );
        
        // Request validator committee signatures (14/21 threshold)
        let aggregated_sig = crypto::request_validator_signatures(
            unlock_message.as_bytes(),
            14 // threshold
        )?;
        
        storage::emit_event("BurnRequested", sender, amount, nonce);
        Ok(aggregated_sig)
    }
}
```

#### Checkpoint Integration ✅

**Status: IMPLEMENTED** (October 2025)

The checkpoint system for verifying bridge events is **production-ready**:

**What's Working:**

* ✅ **Ethereum Scanner** (`checkpoint/scanner/ethereum.go`) - JSON-RPC integration
* ✅ **QuantumWing Scanner** (`checkpoint/scanner/quantumwing.go`) - REST API integration
* ✅ **Scanner Factory** (`checkpoint/service.go`) - Multi-blockchain support
* ✅ **Merkle Compression** (`checkpoint/merkle/`) - 85% compression ratio
* ✅ **Dilithium Signatures** - All checkpoints signed with Mode 3
* ✅ **Storage Backends** - Memory, S3, Filecoin/IPFS ready

**Bridge Integration (Ready for Phase 1):**

```go
// checkpoint/ethereum_bridge.go (DESIGN - to be implemented in Q1 2026)
type BridgeEventVerifier struct {
    scanner *EthereumScanner  // ✅ Already exists
    merkleDB *MerkleTreeDB    // ✅ Already exists
}

func (v *BridgeEventVerifier) VerifyLockEvent(
    txHash common.Hash,
    merkleProof []byte,
) (*LockEvent, error) {
    // 1. Get checkpoint containing this transaction
    checkpoint := v.scanner.GetCheckpointForTx(txHash)
    
    // 2. Verify Merkle proof
    root := checkpoint.TransactionsRoot
    valid := merkle.VerifyProof(root, txHash, merkleProof)
    if !valid {
        return nil, errors.New("invalid merkle proof")
    }
    
    // 3. Parse event logs
    receipt := checkpoint.GetReceipt(txHash)
    for _, log := range receipt.Logs {
        if log.Topics[0] == ETHLockedEventSignature {
            return parseLockEvent(log), nil
        }
    }
    
    return nil, errors.New("lock event not found")
}
```

**Performance:**

* QuantumWing blocks: 800 blocks/s (REST API, single call)
* Ethereum blocks: \~30 blocks/s (JSON-RPC, batched)
* Merkle proof generation: < 10ms per block
* Checkpoint signature: \~500ms (Dilithium Mode 3)

#### Deliverables

* [x] **Ethereum checkpoint scanner** ✅ COMPLETE (October 2025)
* [x] **QuantumWing checkpoint scanner** ✅ COMPLETE (October 2025)
* [x] **Merkle compression system** ✅ COMPLETE
* [x] **Dilithium signature integration** ✅ COMPLETE
* [x] **REST API endpoints** ✅ COMPLETE (`/api/v1/blocks/range`)
* [x] **Blockchain Explorer** ✅ COMPLETE (Next.js + WebSocket real-time updates)
* [ ] Bridge custody smart contract (Solidity)
* [ ] QWVM wrapped asset contracts (Rust → WASM)
* [ ] Validator committee threshold signatures
* [ ] Bridge Web UI (for cross-chain transfers)
* [ ] Testnet deployment (Sepolia ↔ QuantumWing testnet)

**Timeline:** 4 months (January - April 2026)

***

### **Phase 7: Bitcoin Integration (Q2 2026)** ⚙️

**Goal:** Deploy bridge on Bitcoin network using **threshold ECDSA → Dilithium** migration.

#### Challenge: Bitcoin's Limited Smart Contract Support

Bitcoin doesn't have Ethereum-style smart contracts, so we use:

1. **Multi-signature P2SH addresses** (3-of-5 validators control custody)
2. **Time-locked transactions** (Bitcoin Script: `OP_CHECKLOCKTIMEVERIFY`)
3. **SPV proofs** to verify BTC lock transactions

#### Architecture

```
┌─────────────────────────────────────────────────────────────┐
│                    Bitcoin Network                          │
│  ┌────────────────────────────────────────────────────────┐ │
│  │  Multi-Sig P2SH Address (3-of-5 validators)            │ │
│  │  bc1q...xyz (Taproot address)                          │ │
│  │  - User sends BTC to this address                      │ │
│  │  - 3 validators must sign to unlock                    │ │
│  │  - Timelocked: 2 weeks emergency withdrawal            │ │
│  └────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
                            ↕ 
              SPV Proof Verification
                            ↕
┌─────────────────────────────────────────────────────────────┐
│                    QuantumWing Chain                        │
│  ┌────────────────────────────────────────────────────────┐ │
│  │  qwBTC Contract (QWVM)                                 │ │
│  │  - mintBTC(btcTxId, merkleBlock, 6 confirmations)     │ │
│  │  - burnBTC(amount) → PSBT with Dilithium signatures   │ │
│  │  - reserveBalance: 2,450 BTC                          │ │
│  └────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
```

#### SPV Proof Verification

```go
// checkpoint/bitcoin_spv.go
type BitcoinSPVVerifier struct {
    headerChain []wire.BlockHeader
    merkleDB *MerkleTreeDB
}

func (v *BitcoinSPVVerifier) VerifyTransaction(
    txBytes []byte,
    merkleProof []byte,
    blockHeader wire.BlockHeader,
) (bool, error) {
    // 1. Verify block header is in longest chain (6 confirmations)
    if !v.isHeaderValid(blockHeader, 6) {
        return false, errors.New("insufficient confirmations")
    }
    
    // 2. Compute transaction hash
    txHash := sha256.Sum256(sha256.Sum256(txBytes))
    
    // 3. Verify Merkle proof
    root := blockHeader.MerkleRoot
    valid := btc.VerifyMerkleProof(root, txHash, merkleProof)
    
    return valid, nil
}
```

#### PSBT (Partially Signed Bitcoin Transactions)

When user burns qwBTC, validators create a **PSBT** to unlock Bitcoin:

```go
// checkpoint/bitcoin_unlock.go
type BitcoinBridge struct {
    validators    []*Validator
    custodyUTXOs  []wire.OutPoint
    usedNonces    map[uint64]bool
    mu            sync.RWMutex
}

func (b *BitcoinBridge) CreateUnlockTransaction(
    amount btcutil.Amount,
    recipient *btcutil.Address,
    nonce uint64,
) (*psbt.Packet, error) {
    b.mu.Lock()
    defer b.mu.Unlock()
    
    // Anti-replay: check nonce
    if b.usedNonces[nonce] {
        return nil, errors.New("nonce already used")
    }
    
    // Validation
    if amount <= 0 {
        return nil, errors.New("invalid amount")
    }
    if recipient == nil {
        return nil, errors.New("invalid recipient")
    }
    
    // Find UTXO with sufficient balance
    utxo, err := b.findSufficientUTXO(amount)
    if err != nil {
        return nil, fmt.Errorf("insufficient reserves: %w", err)
    }
    
    // Create unsigned transaction
    tx := wire.NewMsgTx(2)
    tx.AddTxIn(&wire.TxIn{
        PreviousOutPoint: *utxo,
        Sequence: 0xfffffffd, // Enable timelocks (RBF)
    })
    
    // Output to recipient
    tx.AddTxOut(&wire.TxOut{
        Value: int64(amount),
        PkScript: recipient.ScriptAddress(),
    })
    
    // Change output (if needed)
    change := utxo.Value - int64(amount) - 1000 // 1000 sat fee
    if change > 546 { // Dust limit
        tx.AddTxOut(&wire.TxOut{
            Value: change,
            PkScript: b.custodyAddress.ScriptAddress(),
        })
    }
    
    // Create PSBT
    packet, err := psbt.NewFromUnsignedTx(tx)
    if err != nil {
        return nil, fmt.Errorf("failed to create PSBT: %w", err)
    }
    
    // Request 3-of-5 validator signatures (BIP-340 Schnorr for Taproot)
    message := fmt.Sprintf("UNLOCK_BTC:%s:%d:%d", recipient.String(), amount, nonce)
    messageHash := sha256.Sum256([]byte(message))
    
    sigCount := 0
    for i := 0; i < len(b.validators) && sigCount < 3; i++ {
        sig, err := b.validators[i].SignDilithium(messageHash[:])
        if err != nil {
            continue // Skip invalid signature
        }
        
        packet.Inputs[0].PartialSigs = append(packet.Inputs[0].PartialSigs, &psbt.PartialSig{
            PubKey:    b.validators[i].PublicKey,
            Signature: sig,
        })
        sigCount++
    }
    
    if sigCount < 3 {
        return nil, errors.New("insufficient signatures (need 3/5)")
    }
    
    // Mark nonce as used AFTER successful PSBT creation
    b.usedNonces[nonce] = true
    
    return packet, nil
}

func (b *BitcoinBridge) findSufficientUTXO(amount btcutil.Amount) (*wire.OutPoint, error) {
    for _, utxo := range b.custodyUTXOs {
        if utxo.Value >= int64(amount)+1000 { // amount + fee
            return &utxo, nil
        }
    }
    return nil, errors.New("no UTXO with sufficient balance")
}
```

```
return packet, nil
```

}

```

#### Deliverables

- [ ] Bitcoin SPV client (header chain sync)
- [ ] Multi-sig P2SH custody address generation
- [ ] PSBT creation with Dilithium signatures
- [ ] qwBTC QWVM contract
- [ ] 6-confirmation security (1 hour)
- [ ] Testnet deployment (Bitcoin testnet3 ↔ QuantumWing)

**Timeline:** 3 months (May - July 2026)

---

### **Phase 8: Solana Integration (Q3 2026)** ⚙️

**Goal:** Deploy bridge on Solana using **Wormhole-style validator attestations**.

#### Architecture

Solana has fast finality (~400ms) and supports Ed25519 signatures. We:
1. Deploy a **Solana program** (smart contract) for custody
2. Use **validator attestations** (21 QuantumWing validators sign Solana events)
3. Support **SPL tokens** (USDC, USDT, etc.)

```

┌─────────────────────────────────────────────────────────────┐ │ Solana Mainnet │ │ ┌────────────────────────────────────────────────────────┐ │ │ │ QuantumWing Bridge Program (Rust - Anchor) │ │ │ │ - lock\_sol(qw\_recipient: \[u8; 32]) │ │ │ │ - lock\_spl\_token(mint: Pubkey, amount: u64) │ │ │ │ - unlock\_sol(dilithium\_proof: Vec) │ │ │ └────────────────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────────┘ ↕ Validator Attestation (21 signatures) ↕ ┌─────────────────────────────────────────────────────────────┐ │ QuantumWing Chain │ │ ┌────────────────────────────────────────────────────────┐ │ │ │ qwSOL Contract (QWVM) │ │ │ │ - mintSOL(solanaTxSig, validatorProofs\[21]) │ │ │ │ - burnSOL(amount) → unlockProof │ │ │ └────────────────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────────┘

````

#### Solana Program (Anchor Framework)

```rust
// programs/quantumwing_bridge/src/lib.rs
use anchor_lang::prelude::*;
use anchor_lang::system_program::{Transfer, transfer};

declare_id!("QWBridge11111111111111111111111111111111111");

#[program]
pub mod quantumwing_bridge {
    use super::*;
    
    pub fn lock_sol(ctx: Context<LockSOL>, qw_recipient: [u8; 32], amount: u64) -> Result<()> {
        require!(amount > 0, BridgeError::InvalidAmount);
        require!(qw_recipient != [0u8; 32], BridgeError::InvalidRecipient);
        require!(!ctx.accounts.escrow.paused, BridgeError::BridgePaused);
        
        let escrow = &mut ctx.accounts.escrow;
        
        // CEI Pattern: Effects before Interactions
        escrow.locked_amount = escrow.locked_amount
            .checked_add(amount)
            .ok_or(BridgeError::Overflow)?;
        escrow.total_locked = escrow.total_locked
            .checked_add(amount)
            .ok_or(BridgeError::Overflow)?;
        
        // Interactions: Transfer SOL to escrow PDA
        let cpi_context = CpiContext::new(
            ctx.accounts.system_program.to_account_info(),
            Transfer {
                from: ctx.accounts.user.to_account_info(),
                to: ctx.accounts.escrow.to_account_info(),
            },
        );
        transfer(cpi_context, amount)?;
        
        emit!(SOLLocked {
            qw_recipient,
            amount,
            slot: Clock::get()?.slot,
            timestamp: Clock::get()?.unix_timestamp,
        });
        
        Ok(())
    }
    
    pub fn unlock_sol(
        ctx: Context<UnlockSOL>,
        amount: u64,
        nonce: u64,
        dilithium_proof: Vec<u8>,
    ) -> Result<()> {
        require!(amount > 0, BridgeError::InvalidAmount);
        require!(!ctx.accounts.escrow.paused, BridgeError::BridgePaused);
        require!(!ctx.accounts.escrow.used_nonces.contains(&nonce), BridgeError::NonceUsed);
        
        let escrow = &mut ctx.accounts.escrow;
        require!(escrow.locked_amount >= amount, BridgeError::InsufficientReserves);
        
        // Verify Dilithium aggregated signature (14/21 validators)
        let message = format!("UNLOCK_SOL:{}:{}:{}", ctx.accounts.recipient.key(), amount, nonce);
        require!(
            verify_dilithium_aggregated(message.as_bytes(), &dilithium_proof, 14),
            BridgeError::InvalidProof
        );
        
        // CEI Pattern: Effects before Interactions
        escrow.used_nonces.push(nonce); // Anti-replay
        escrow.locked_amount = escrow.locked_amount
            .checked_sub(amount)
            .ok_or(BridgeError::Underflow)?;
        
        // Interactions: Transfer SOL from escrow to recipient
        **ctx.accounts.escrow.to_account_info().try_borrow_mut_lamports()? = ctx.accounts.escrow
            .to_account_info()
            .lamports()
            .checked_sub(amount)
            .ok_or(BridgeError::Underflow)?;
            
        **ctx.accounts.recipient.to_account_info().try_borrow_mut_lamports()? = ctx.accounts.recipient
            .to_account_info()
            .lamports()
            .checked_add(amount)
            .ok_or(BridgeError::Overflow)?;
        
        emit!(SOLUnlocked {
            recipient: ctx.accounts.recipient.key(),
            amount,
            nonce,
            slot: Clock::get()?.slot,
        });
        
        Ok(())
    }
    
    /// Emergency pause (admin only)
    pub fn pause(ctx: Context<AdminAction>) -> Result<()> {
        require!(ctx.accounts.authority.key() == ctx.accounts.escrow.admin, BridgeError::Unauthorized);
        ctx.accounts.escrow.paused = true;
        Ok(())
    }
    
    pub fn unpause(ctx: Context<AdminAction>) -> Result<()> {
        require!(ctx.accounts.authority.key() == ctx.accounts.escrow.admin, BridgeError::Unauthorized);
        ctx.accounts.escrow.paused = false;
        Ok(())
    }
}

#[derive(Accounts)]
pub struct LockSOL<'info> {
    #[account(mut)]
    pub user: Signer<'info>,
    
    #[account(
        mut,
        seeds = [b"escrow"],
        bump,
    )]
    pub escrow: Account<'info, EscrowAccount>,
    
    pub system_program: Program<'info, System>,
}

#[derive(Accounts)]
pub struct UnlockSOL<'info> {
    #[account(mut)]
    pub recipient: SystemAccount<'info>,
    
    #[account(
        mut,
        seeds = [b"escrow"],
        bump,
    )]
    pub escrow: Account<'info, EscrowAccount>,
}

#[derive(Accounts)]
pub struct AdminAction<'info> {
    pub authority: Signer<'info>,
    
    #[account(
        mut,
        seeds = [b"escrow"],
        bump,
    )]
    pub escrow: Account<'info, EscrowAccount>,
}

#[account]
pub struct EscrowAccount {
    pub admin: Pubkey,
    pub locked_amount: u64,
    pub total_locked: u64,
    pub used_nonces: Vec<u64>,
    pub paused: bool,
    pub bump: u8,
}

#[event]
pub struct SOLLocked {
    pub qw_recipient: [u8; 32],
    pub amount: u64,
    pub slot: u64,
    pub timestamp: i64,
}

#[event]
pub struct SOLUnlocked {
    pub recipient: Pubkey,
    pub amount: u64,
    pub nonce: u64,
    pub slot: u64,
}

#[error_code]
pub enum BridgeError {
    #[msg("Invalid amount")]
    InvalidAmount,
    #[msg("Invalid recipient")]
    InvalidRecipient,
    #[msg("Invalid Dilithium proof")]
    InvalidProof,
    #[msg("Nonce already used")]
    NonceUsed,
    #[msg("Insufficient reserves")]
    InsufficientReserves,
    #[msg("Bridge is paused")]
    BridgePaused,
    #[msg("Unauthorized")]
    Unauthorized,
    #[msg("Arithmetic overflow")]
    Overflow,
    #[msg("Arithmetic underflow")]
    Underflow,
}
````

#### Deliverables

* [ ] Solana bridge program (Anchor)
* [ ] SPL token support (USDC, USDT, wSOL)
* [ ] Validator attestation mechanism (21 signatures)
* [ ] qwSOL and qwSPL contracts (QWVM)
* [ ] Solana RPC integration
* [ ] Testnet deployment (Solana devnet ↔ QuantumWing)

**Timeline:** 2 months (August - September 2026)

***

### **Phase 9: ZK-Proof Optimization (Q4 2026)** 🔬

**Goal:** Use **ZK-SNARKs to compress bridge proofs** and reduce gas costs.

**Note:** Core ZK-STARK implementation complete in Phase 3. This phase focuses on gas optimization for Ethereum deployment.

#### Problem: Large Dilithium Signatures

* Dilithium Mode 3 signature: **3,293 bytes**
* Aggregated 14/21 signatures: **\~46 KB**
* Ethereum gas cost: **\~10,000 gas per byte** = **460M gas** ❌

#### Solution: ZK-SNARK Wrapper

Generate a **ZK proof** that 14/21 validators signed, without revealing full signatures:

```
Prover (QuantumWing validator):
1. Collect 14 Dilithium signatures
2. Generate ZK-SNARK proof: 
   "I know 14 valid Dilithium signatures on message M"
3. Proof size: 300 bytes (vs 46 KB)

Verifier (Ethereum contract):
1. Verify ZK-SNARK proof (50K gas)
2. Trust that 14/21 validators signed
```

#### ZK Circuit (Circom)

```circom
// circuits/dilithium_threshold.circom
template DilithiumThresholdVerifier(N, T) {
    signal input messageHash;
    signal input dilithiumPubkeys[N][1952]; // 21 validators
    signal input dilithiumSigs[N][3293];
    signal input validSigMask[N]; // 1 if valid, 0 if not
    
    signal output isValid;
    
    // Verify each signature
    component verifiers[N];
    var validCount = 0;
    for (var i = 0; i < N; i++) {
        verifiers[i] = DilithiumVerify();
        verifiers[i].pubkey <== dilithiumPubkeys[i];
        verifiers[i].message <== messageHash;
        verifiers[i].signature <== dilithiumSigs[i];
        
        validCount += verifiers[i].isValid * validSigMask[i];
    }
    
    // Require at least T valid signatures
    isValid <== validCount >= T;
}
```

#### Integration

```solidity
// contracts/QuantumWingBridgeZK.sol
function unlockETH(
    address recipient,
    uint256 amount,
    bytes calldata zkProof,
    uint256 nonce
) external nonReentrant whenNotPaused {
    require(!usedNonces[nonce], "Nonce already used");
    require(recipient != address(0), "Invalid recipient");
    require(amount > 0, "Amount must be > 0");
    require(address(this).balance >= amount, "Insufficient reserves");
    
    bytes32 messageHash = keccak256(abi.encodePacked("UNLOCK_ETH", recipient, amount, nonce));
    
    // Verify ZK-SNARK (300 bytes, 50K gas)
    require(
        zkVerifier.verify(zkProof, messageHash),
        "Invalid ZK proof"
    );
    
    // CEI Pattern: Effects before Interactions
    usedNonces[nonce] = true;
    totalLockedETH -= amount;
    
    // Use .call{value:} instead of .transfer() to avoid 2300 gas limit
    (bool success, ) = payable(recipient).call{value: amount}("");
    require(success, "ETH transfer failed");
    
    emit ETHUnlocked(recipient, amount, nonce, zkProof);
}
```

#### Deliverables

* [ ] Dilithium verification circuit (Circom)
* [ ] ZK-SNARK prover (Rust - arkworks)
* [ ] Ethereum verifier contract (Solidity)
* [ ] Proof generation service (off-chain)
* [ ] Gas cost benchmarks (46 KB → 300 bytes)

**Timeline:** 3 months (October - December 2026)

***

## 🛡️ Security Considerations

### 1. **Validator Committee Rotation**

Prevent long-term key compromise:

* Validators rotate every **30 days**
* New Dilithium keypairs generated
* Old keys revoked via governance vote

### 2. **Emergency Shutdown**

If quantum attack detected:

* **Circuit breaker** pauses all bridge operations
* Users have 7 days to withdraw locked assets
* Governance votes on recovery plan

### 3. **Reserve Auditing**

Transparency via Ethereum checkpoints:

* **Daily checkpoint** of Ethereum bridge balance
* Public API: `GET /api/bridge/reserves`
* Alert if reserves < 100% backing

### 4. **Slashing Conditions**

Validators are slashed for:

* **Double-signing unlock proofs** (slash 50%)
* **Failing to participate in committee** (slash 5%)
* **Signing invalid Merkle proofs** (slash 100%, jail 90 days)

***

## 📊 Economic Model

### Bridge Fees

| Operation                | Fee   | Recipient                                           |
| ------------------------ | ----- | --------------------------------------------------- |
| Lock ETH → Mint qwWETH   | 0.05% | Validator committee                                 |
| Burn qwWETH → Unlock ETH | 0.05% | Validator committee                                 |
| Lock BTC → Mint qwBTC    | 0.1%  | Validator committee (higher due to PSBT complexity) |
| Burn qwBTC → Unlock BTC  | 0.1%  | Validator committee                                 |
| Lock SOL → Mint qwSOL    | 0.03% | Validator committee                                 |

**Example:**

* User locks **10 ETH**
* Fee: **0.005 ETH** (0.05%)
* Minted: **9.995 qwWETH**

### Revenue Projection

Assuming **$50M daily bridge volume**:

* Daily fees: **$25,000** (0.05%)
* Monthly: **$750,000**
* Annual: **$9M** shared among 21 validators

***

## 🧪 Testing Strategy

### 1. **Testnet Deployment**

| Bridge   | Source Chain | QuantumWing Testnet | Status  |
| -------- | ------------ | ------------------- | ------- |
| Ethereum | Sepolia      | testnet-1           | Q1 2026 |
| Bitcoin  | testnet3     | testnet-1           | Q2 2026 |
| Solana   | Devnet       | testnet-1           | Q3 2026 |

### 2. **Failure Scenarios**

* **Network partition:** Test 7-day emergency withdrawal
* **Validator collusion:** Attempt to steal locked assets
* **Merkle proof forgery:** Submit fake lock events
* **Replay attacks:** Reuse old unlock proofs

### 3. **Audit Requirements**

Before mainnet launch:

* **Smart contract audit** (Trail of Bits, OpenZeppelin)
* **Cryptography audit** (NCC Group)
* **Economic audit** (Gauntlet)

***

## 🗓️ Milestones

| Quarter     | Milestone            | Status         | Deliverables                                                       |
| ----------- | -------------------- | -------------- | ------------------------------------------------------------------ |
| **Q4 2025** | Core Bridge System   | ✅ **COMPLETE** | Phases 1-5: BID, Committee, ZK, Timelock, Redemption (69/69 tests) |
| **Q1 2026** | Ethereum Integration | ⚙️ In Progress | Smart contracts, qwETH, qwUSDC, testnet launch                     |
| **Q2 2026** | Bitcoin Integration  | 🔜 Planned     | qwBTC, SPV verification, PSBT                                      |
| **Q3 2026** | Solana Integration   | 🔜 Planned     | qwSOL, SPL tokens, Anchor program                                  |
| **Q4 2026** | ZK Optimization      | 🔜 Planned     | ZK-SNARK compression, 300-byte proofs                              |
| **Q1 2027** | Mainnet Launch       | 🔜 Planned     | Audits complete, 21 validators live                                |

***

## 📚 References

* **Ethereum Checkpoints:** Already implemented in `checkpoint/service.go`
* **Dilithium Signatures:** `crypto/dilithium/` (Mode 3)
* **QWVM Host Functions:** `qwvm/host_functions.go`
* **Multi-Sig Bitcoin:** [Bitcoin P2SH](https://en.bitcoin.it/wiki/Pay_to_script_hash)
* **Solana Anchor:** [Anchor Book](https://book.anchor-lang.com/)
* **ZK-SNARKs:** [Circom Documentation](https://docs.circom.io/)

***

## 🚀 Getting Involved

Want to contribute to cross-chain bridge development?

1. **Developers:** Check `contracts/ethereum/` and `qwvm/` folders
2. **Validators:** Apply to join bridge committee (21 slots)
3. **Security Researchers:** Report bugs to <security@quantumwing.io>
4. **Liquidity Providers:** Earn 0.05% fees on bridge volume

**Status:** ✅ Core bridge system complete and production-ready! Ethereum integration in progress.

***

*Last Updated: June 2026 - Bridge phases 1-5 operational; Phases 6-9 (Ethereum/Bitcoin/Solana/ZK-opt) remain forward-looking*


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://quantumwing.gitbook.io/quantumwing/roadmap/cross-chain-assets.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `build a script that syncs our docs to a CMS` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.