smom-dbis-138/docs/deployment/MAINNET_TETHER_AND_TRANSACTION_MIRROR.md

Mainnet Tether and Transaction Mirror Implementation

Date: 2025-12-11 Status: Ready for Deployment

---

📋 Overview

This document describes the implementation of:

1. MainnetTether - Anchors Chain-138 state proofs to Ethereum Mainnet (Kaleido-style)
2. TransactionMirror - Mirrors Chain-138 transactions to Mainnet for Etherscan visibility

---

🔗 MainnetTether Contract

Purpose

Following Kaleido's pattern, the MainnetTether contract:

• Stores signed state proofs from Chain-138 validators
• Creates immutable, verifiable records of Chain-138 state on Mainnet
• Anchors Chain-138 state at regular intervals
• Provides security and transparency through public verification
• Prevents collusion by requiring collective validator signatures

Contract Details

File: contracts/tether/MainnetTether.sol Deployment Script: script/DeployMainnetTether.s.sol Status: ✅ Ready for deployment

Key Features

• State Proof Storage: Stores block number, hash, state root, and validator signatures
• Replay Protection: Prevents duplicate state proofs
• Block Anchoring: Tracks all anchored blocks
• Admin Control: Pausable with admin-only functions
• Query Functions: Easy lookup of anchored state proofs

Deployment

# Set admin address (multisig recommended)
export TETHER_ADMIN=0x...

# Deploy to Mainnet
forge script script/DeployMainnetTether.s.sol \
  --rpc-url $ETH_MAINNET_RPC_URL \
  --private-key $PRIVATE_KEY \
  --broadcast \
  --verify

# Update .env
echo "MAINNET_TETHER_ADDRESS=<deployed_address>" >> .env

Usage

Anchor State Proof

// Called by off-chain service that collects validator signatures
tether.anchorStateProof(
    blockNumber,        // Chain-138 block number
    blockHash,          // Chain-138 block hash
    stateRoot,          // Chain-138 state root
    previousBlockHash,  // Previous block hash
    timestamp,          // Block timestamp
    signatures,         // Collective validator signatures
    validatorCount      // Number of validators
);

Query State Proof

// Check if block is anchored
bool anchored = tether.isAnchored(blockNumber);

// Get state proof details
StateProof memory proof = tether.getStateProof(blockNumber);

---

🔍 TransactionMirror Contract

Purpose

The TransactionMirror contract:

• Logs all Chain-138 transactions as events on Mainnet
• Makes Chain-138 transactions searchable on Etherscan
• Provides transparency and auditability
• Enables cross-chain transaction visibility

Contract Details

File: contracts/mirror/TransactionMirror.sol Deployment Script: script/DeployTransactionMirror.s.sol Status: ✅ Ready for deployment

Key Features

• Transaction Logging: Stores transaction details (hash, from, to, value, etc.)
• Event Emission: Emits indexed events for Etherscan searchability
• Batch Support: Can mirror multiple transactions in one call
• Replay Protection: Prevents duplicate transaction mirroring
• Query Functions: Easy lookup of mirrored transactions

Deployment

# Set admin address (multisig recommended)
export MIRROR_ADMIN=0x...

# Deploy to Mainnet
forge script script/DeployTransactionMirror.s.sol \
  --rpc-url $ETH_MAINNET_RPC_URL \
  --private-key $PRIVATE_KEY \
  --broadcast \
  --verify

# Update .env
echo "TRANSACTION_MIRROR_ADDRESS=<deployed_address>" >> .env

Usage

Mirror Single Transaction

// Called by off-chain service that monitors Chain-138
mirror.mirrorTransaction(
    txHash,          // Chain-138 transaction hash
    from,            // Sender address
    to,              // Recipient address
    value,           // Value transferred
    blockNumber,     // Chain-138 block number
    blockTimestamp,  // Block timestamp
    gasUsed,         // Gas used
    success,         // Transaction success status
    data             // Transaction data (optional)
);

Mirror Batch Transactions

// Mirror multiple transactions at once (more gas efficient)
mirror.mirrorBatchTransactions(
    txHashes,        // Array of transaction hashes
    froms,           // Array of sender addresses
    tos,             // Array of recipient addresses
    values,          // Array of values
    blockNumbers,    // Array of block numbers
    blockTimestamps, // Array of timestamps
    gasUseds,        // Array of gas used
    successes,       // Array of success statuses
    datas            // Array of transaction data
);

Query Mirrored Transaction

// Check if transaction is mirrored
bool mirrored = mirror.isMirrored(txHash);

// Get transaction details
MirroredTransaction memory tx = mirror.getTransaction(txHash);

---

🔄 Integration with Off-Chain Services

State Proof Anchoring Service

An off-chain service should:

1. Monitor Chain-138 blocks
2. Collect validator signatures for each block
3. Call anchorStateProof() on MainnetTether at regular intervals (e.g., every 6 hours)
4. Handle retries and error cases

Transaction Mirroring Service

An off-chain service should:

1. Monitor Chain-138 for new transactions
2. Extract transaction details
3. Call mirrorTransaction() or mirrorBatchTransactions() on TransactionMirror
4. Batch transactions for gas efficiency
5. Handle retries and error cases

Example Service Architecture

Chain-138 Network
  ↓
Off-Chain Monitor Service
  ├─→ State Proof Collector → MainnetTether.anchorStateProof()
  └─→ Transaction Monitor → TransactionMirror.mirrorTransaction()
  ↓
Ethereum Mainnet
  ├─→ MainnetTether (state proofs)
  └─→ TransactionMirror (transaction logs)
  ↓
Etherscan (public visibility)

---

📊 Benefits

MainnetTether Benefits

1. Security: Immutable record of Chain-138 state on Mainnet
2. Transparency: Publicly verifiable state proofs
3. Integrity: Prevents state manipulation
4. Auditability: Historical state records
5. Trust: Validator signatures provide consensus proof

TransactionMirror Benefits

1. Visibility: All Chain-138 transactions visible on Etherscan
2. Searchability: Indexed events enable easy searching
3. Transparency: Public audit trail
4. Cross-Chain: Unified view across chains
5. Compliance: Meets regulatory transparency requirements

---

⚙️ Configuration

Environment Variables

Add to .env:

# MainnetTether
TETHER_ADMIN=0x...  # Multisig recommended
MAINNET_TETHER_ADDRESS=  # Set after deployment

# TransactionMirror
MIRROR_ADMIN=0x...  # Multisig recommended (can be same as TETHER_ADMIN)
TRANSACTION_MIRROR_ADDRESS=  # Set after deployment

Recommended Settings

• Admin Addresses: Use multisig wallets (Gnosis Safe recommended)
• Anchoring Frequency: Every 6 hours (configurable)
• Mirroring Frequency: Real-time or batch every block
• Gas Optimization: Use batch functions when possible

---

🚀 Deployment Plan

Step 1: Deploy MainnetTether

forge script script/DeployMainnetTether.s.sol \
  --rpc-url $ETH_MAINNET_RPC_URL \
  --private-key $PRIVATE_KEY \
  --broadcast \
  --verify

Step 2: Deploy TransactionMirror

forge script script/DeployTransactionMirror.s.sol \
  --rpc-url $ETH_MAINNET_RPC_URL \
  --private-key $PRIVATE_KEY \
  --broadcast \
  --verify

Step 3: Set Up Off-Chain Services

1. Deploy state proof anchoring service
2. Deploy transaction mirroring service
3. Configure monitoring and alerting
4. Test with small batches

Step 4: Verify on Etherscan

1. Verify both contracts on Etherscan
2. Test transaction mirroring
3. Verify events are visible
4. Test state proof anchoring

---

📝 Gas Estimates

MainnetTether

• Deployment: 1,200,000 gas ($30-50 at current prices)
• anchorStateProof(): ~150,000-300,000 gas (depends on signature size)

TransactionMirror

• Deployment: 1,000,000 gas ($25-40 at current prices)
• mirrorTransaction(): ~80,000-120,000 gas per transaction
• mirrorBatchTransactions(): ~50,000 + (60,000 * count) gas (more efficient)

---

⚠️ Important Notes

1. Admin Security: Use multisig for admin addresses
2. Gas Costs: Monitor gas costs for frequent operations
3. Off-Chain Services: Critical for functionality - ensure high availability
4. Replay Protection: Built-in, but verify in testing
5. Pausability: Can pause in emergency situations
6. Testing: Test thoroughly on testnet before mainnet deployment

---

🔗 Related Contracts

• MirrorManager: Address registry (separate from TransactionMirror)
• TwoWayTokenBridge: Token bridging (separate from state anchoring)
• CCIPWETH9Bridge/CCIPWETH10Bridge: Existing CCIP bridges

---

📚 References

• Kaleido Tether Documentation
• Etherscan Event Search
• Foundry Deployment Guide

---

Last Updated: 2025-12-11 Status: Contracts ready, deployment pending