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(...)`

```solidity
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

```typescript
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**:
   ```bash
   npm install ethers@^6.0.0
   npm install dotenv
   ```

2. **Configure environment variables**:
   ```bash
   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**