ZK Proof Native to EVM Bridge

A bridge service that monitors ZK proof submissions on the Telos Native chain and automatically bridges them to the Telos EVM via the EOSIO EVM smart contract.

Overview

This system consists of:

1. NativeChainMonitor - Monitors Telos Native for proof submissions to snarkbabybv1::submit
2. ProofBridge Contract - Solidity contract on Telos EVM that receives bridged proofs
3. ProofBridge Service - Node.js service that bridges proofs from Native to EVM

Features

• ✅ Monitors Telos Native chain for ZK proof submissions
• ✅ Automatically bridges proofs to Telos EVM
• ✅ Prevents duplicate processing with transaction tracking
• ✅ Graceful error handling and recovery
• ✅ State persistence for reliable restarts
• ✅ Configurable monitoring parameters

Installation

# Clone and install dependencies
npm install

# Copy configuration template
cp config.json.example config.json

# Edit configuration with your settings
nano config.json

Configuration

Edit config.json with your settings:

{
  "NATIVE_ENDPOINT": "https://mainnet.telos.net",
  "BRIDGE_PRIVATE_KEY": "your_telos_native_private_key",
  "BRIDGE_EVM_PRIVATE_KEY": "0x...",
  "BRIDGE_ACCOUNT": "your_telos_account",
  "EVM_CHAIN_ID": 40,
  "PROOF_BRIDGE_CONTRACT_ADDRESS": "0x...",
  "TARGET_CONTRACT": "snarkbabybv1",
  "TARGET_ACTION": "submit"
}

Setup Steps

1. Deploy the ProofBridge Contract

# Install Hardhat for contract deployment
npm install --save-dev hardhat @nomiclabs/hardhat-ethers

# Compile and deploy the contract (requires Hardhat setup)
npm run deploy-contract

2. Fund the Bridge Wallet

# Fund with 10 TLOS (default)
npm run fund-bridge

# Fund with custom amount
npm run fund-bridge 25.0000

3. Start the Bridge Service

npm start

Hyperion Integration

The system now uses Hyperion v2 API (https://mainnet.telos.net/v2) for efficient monitoring:

• Direct Action Filtering: Queries only snarkbabybv1::submit actions
• Global Sequence Tracking: Uses Hyperion's global_sequence for reliable state
• Batch Processing: Processes up to 100 actions per request
• Better Performance: No need to scan entire blocks

Hyperion Query Example

GET https://mainnet.telos.net/v2/history/get_actions
?account=snarkbabybv1
&action.name=submit
&limit=100
&sort=desc
&after=<last_global_sequence>

Usage

Starting the Service

npm start

Checking Bridge Wallet Balance

npm run check-balance

Monitoring Logs

The service will log:

• New proof submissions detected
• Bridge transactions submitted
• Error conditions and recovery

Architecture

Native Chain Monitor

• Polls Telos Native for new blocks
• Scans transactions for snarkbabybv1::submit actions
• Extracts proof data and metadata
• Emits events for the bridge service

Bridge Service

• Listens for proof events from the monitor
• Creates EVM transactions calling submitBridgedProof()
• Submits transactions via eosio.evm contract
• Tracks processed transactions to prevent duplicates

EVM Contract

• Stores bridged proofs with metadata
• Prevents duplicate submissions
• Provides verification status tracking
• Emits events for proof submissions

Smart Contract Interface

function submitBridgedProof(
    bytes calldata _proofBytes,
    string calldata _nativeAccount,
    string calldata _nativeTxHash
) external onlyBridgeOperator

Error Handling

The service includes robust error handling:

• Network connectivity issues
• Failed transactions (retries)
• Invalid proof data
• Insufficient bridge wallet balance
• State file corruption recovery

Monitoring

Key metrics to monitor:

• Bridge wallet balance
• Processing lag (blocks behind)
• Failed bridge attempts
• Duplicate transaction attempts

Security Considerations

• Bridge operator private keys should be secured
• Regular monitoring of bridge wallet balance
• Contract owner controls for emergency stops
• Audit proof verification logic before production

Development

Project Structure

├── src/
│   ├── main.js              # Entry point
│   ├── nativeMonitor.js     # Native chain monitoring
│   └── proofBridge.js       # Bridge logic
├── contracts/
│   └── ProofBridge.sol      # EVM contract
├── scripts/
│   ├── deployContract.js    # Contract deployment
│   ├── fundBridge.js        # Bridge wallet funding
│   └── checkBalance.js      # Balance checking
└── config.json.example      # Configuration template

Running in Development

npm run dev  # Runs with Node.js inspector for debugging

Troubleshooting

Common Issues

Bridge wallet not found:

npm run fund-bridge  # Creates and funds the wallet

Insufficient gas:

• Check bridge wallet balance
• Increase funding amount

Missed transactions:

• Check monitor-state.json for last processed block
• Manually set START_BLOCK in config if needed

Contract deployment issues:

• Ensure OpenZeppelin contracts are installed
• Verify EVM chain ID matches network
• Check bridge operator address in constructor

License

MIT