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

Task 2: Off-Chain State Anchoring Service - Implementation Guide

Date: 2025-01-18
Status: ⏳ TEMPLATE CREATED
Priority: 🔴 CRITICAL

Overview

Off-chain service to collect state proofs from ChainID 138 validators and submit them to MainnetTether contract on Ethereum Mainnet.

Architecture

┌─────────────────┐
│ ChainID 138 RPC │
│  (Blockchain)   │
└────────┬────────┘
         │
         │ Monitor blocks
         │ Collect signatures
         │
         ▼
┌─────────────────────────┐
│ State Anchoring Service │
│  (Off-chain Service)    │
└────────┬────────────────┘
         │
         │ Aggregate proofs
         │ Submit to Mainnet
         │
         ▼
┌─────────────────┐
│ MainnetTether   │
│  (Mainnet)      │
└─────────────────┘

Service Requirements

1. ChainID 138 Block Monitoring

• Monitor new blocks on ChainID 138
• Extract block number, hash, state root
• Track previous block hash
• Record block timestamp

2. Validator Signature Collection

• Collect signatures from ChainID 138 validators
• Aggregate multiple validator signatures
• Verify signature validity
• Count number of validators that signed

3. State Proof Aggregation

• Combine block data with validator signatures
• Create state proof structure
• Calculate proof hash for indexing
• Prepare data for Mainnet submission

4. MainnetTether Interaction

• Submit anchorStateProof() calls to MainnetTether
• Handle replay protection (check if proof exists)
• Monitor transaction success/failure
• Retry on failure with exponential backoff

5. Monitoring and Logging

• Log all state proof submissions
• Monitor submission success rate
• Alert on failures
• Track submission frequency

Contract Interface

MainnetTether Contract

Address: 0x15DF1D5BFDD8Aa4b380445D4e3E9B38d34283619

Function: anchorStateProof(...)

function anchorStateProof(
    uint256 blockNumber,
    bytes32 blockHash,
    bytes32 stateRoot,
    bytes32 previousBlockHash,
    uint256 timestamp,
    bytes memory signatures,
    uint256 validatorCount
) external whenNotPaused

Parameters:

• blockNumber: Chain-138 block number
• blockHash: Chain-138 block hash
• stateRoot: Chain-138 state root
• previousBlockHash: Previous block hash
• timestamp: Block timestamp
• signatures: Aggregated validator signatures (bytes)
• validatorCount: Number of validators that signed

Implementation Template

Node.js/TypeScript Implementation

import { ethers } from 'ethers';
import { MainnetTether__factory } from './contracts';

class StateAnchoringService {
  private chain138Provider: ethers.Provider;
  private mainnetProvider: ethers.Provider;
  private mainnetWallet: ethers.Wallet;
  private tetherContract: MainnetTether;
  
  constructor(
    chain138Rpc: string,
    mainnetRpc: string,
    privateKey: string
  ) {
    this.chain138Provider = new ethers.JsonRpcProvider(chain138Rpc);
    this.mainnetProvider = new ethers.JsonRpcProvider(mainnetRpc);
    this.mainnetWallet = new ethers.Wallet(privateKey, this.mainnetProvider);
    this.tetherContract = MainnetTether__factory.connect(
      '0x15DF1D5BFDD8Aa4b380445D4e3E9B38d34283619',
      this.mainnetWallet
    );
  }

  async monitorBlocks() {
    // Monitor new blocks on ChainID 138
    this.chain138Provider.on('block', async (blockNumber) => {
      await this.processBlock(blockNumber);
    });
  }

  async processBlock(blockNumber: number) {
    // 1. Get block data
    const block = await this.chain138Provider.getBlock(blockNumber);
    
    // 2. Collect validator signatures
    const signatures = await this.collectSignatures(blockNumber);
    
    // 3. Check replay protection
    const exists = await this.tetherContract.stateProofs(blockNumber);
    if (exists.blockNumber > 0) {
      console.log(`State proof already exists for block ${blockNumber}`);
      return;
    }
    
    // 4. Submit state proof
    await this.submitStateProof({
      blockNumber,
      blockHash: block.hash,
      stateRoot: block.stateRoot,
      previousBlockHash: block.parentHash,
      timestamp: block.timestamp,
      signatures: this.aggregateSignatures(signatures),
      validatorCount: signatures.length
    });
  }

  async collectSignatures(blockNumber: number): Promise<Signature[]> {
    // Collect signatures from ChainID 138 validators
    // Implementation depends on validator signature format
    // Return array of validator signatures
  }

  async submitStateProof(proof: StateProof) {
    try {
      const tx = await this.tetherContract.anchorStateProof(
        proof.blockNumber,
        proof.blockHash,
        proof.stateRoot,
        proof.previousBlockHash,
        proof.timestamp,
        proof.signatures,
        proof.validatorCount
      );
      
      await tx.wait();
      console.log(`State proof anchored: Block ${proof.blockNumber}`);
    } catch (error) {
      console.error(`Failed to anchor state proof: ${error}`);
      // Implement retry logic
    }
  }
}

Deployment Steps

1. Set up service environment:

   npm install ethers@^6.0.0
   npm install dotenv
   

2. Configure environment variables:

   CHAIN138_RPC_URL=https://rpc-http-pub.d-bis.org
   MAINNET_RPC_URL=https://eth.llamarpc.com
   PRIVATE_KEY=<wallet-private-key>
   TETHER_ADDRESS=0x15DF1D5BFDD8Aa4b380445D4e3E9B38d34283619
   

3. Implement validator signature collection (depends on ChainID 138 validator setup)

4. Test service locally:

   • Test block monitoring
   • Test signature collection
   • Test Mainnet submission

5. Deploy service:

   • Deploy to server/container
   • Set up monitoring
   • Configure alerts

Next Steps

1. Research ChainID 138 validator signature format
2. Implement signature collection mechanism
3. Set up service infrastructure
4. Test with testnet/mainnet
5. Deploy and monitor

---

Status: ⏳ TEMPLATE CREATED - AWAITING IMPLEMENTATION