smom-dbis-138/docs/operations/RELAYER_GUIDE.md

# Relayer Operations Guide

## Overview

This guide explains how to become a relayer and operate the trustless bridge system. Relayers monitor deposits on ChainID 138 and submit claims on Ethereum Mainnet.

## Becoming a Relayer

### Requirements

1. **Ethereum Wallet**: Wallet with ETH for gas fees and bonds
2. **Monitoring Infrastructure**: Ability to monitor ChainID 138 events
3. **Sufficient Capital**: ETH for posting bonds (110% of deposit amount, minimum 1 ETH)
4. **Technical Knowledge**: Understanding of blockchain, smart contracts, and bridge mechanics

### Setup Steps

1. **Deploy Monitoring Service**:
   - Set up event monitoring for `Lockbox138` on ChainID 138
   - Monitor `Deposit` events
   - Track deposit IDs and details

2. **Prepare Bond Capital**:
   - Ensure sufficient ETH balance
   - Calculate bond requirements: `bond = max(depositAmount * 1.1, 1 ETH)`
   - Maintain reserve for multiple concurrent claims

3. **Test on Testnet**:
   - Deploy to testnet first
   - Test claim submission
   - Verify bond posting and release
   - Practice emergency procedures

## Relayer Operations

### Monitoring Deposits

**Event to Monitor**: `Deposit` event from `Lockbox138` contract

**Event Structure**:
```solidity
event Deposit(
    uint256 indexed depositId,
    address indexed asset,
    uint256 amount,
    address indexed recipient,
    bytes32 nonce,
    address depositor,
    uint256 timestamp
);
```

**Monitoring Process**:
1. Listen for `Deposit` events on ChainID 138
2. Extract deposit details (depositId, asset, amount, recipient)
3. Verify deposit is legitimate
4. Calculate required bond
5. Submit claim on Ethereum Mainnet

### Submitting Claims

**Function**: `InboxETH.submitClaim()`

**Parameters**:
- `depositId`: Deposit ID from ChainID 138
- `asset`: Asset address (address(0) for native ETH)
- `amount`: Deposit amount
- `recipient`: Recipient address on Ethereum
- `proof`: Optional proof data (reserved for future light client)

**Process**:
```solidity
// Calculate required bond
uint256 requiredBond = bondManager.getRequiredBond(amount);

// Submit claim with bond
inbox.submitClaim{value: requiredBond}(
    depositId,
    asset,
    amount,
    recipient,
    ""
);
```

**Gas Optimization**:
- Batch multiple claims if possible
- Use optimal gas prices
- Monitor gas price trends
- Consider Layer 2 for lower costs

### Bond Management

**Bond Requirements**:
- Bond = max(depositAmount * 1.1, 1 ETH)
- Bond is locked until claim is finalized or challenged
- If challenged and fraud proven, bond is slashed (50% to challenger, 50% burned)
- If not challenged, bond is released after finalization

**Best Practices**:
- Maintain sufficient bond capital
- Monitor bond utilization
- Track bond release times
- Plan for bond requirements

### Claim Finalization

**Process**:
1. Wait for challenge window to expire (30 minutes default)
2. Call `ChallengeManager.finalizeClaim(depositId)`
3. Release bond via `BondManager.releaseBond(depositId)`
4. Funds are available in liquidity pool for recipient

**Automation**:
- Set up automated finalization
- Monitor challenge window expiration
- Automate bond release

## Best Practices

### 1. Security

- **Verify Deposits**: Always verify deposits exist on source chain
- **Monitor Challenges**: Watch for challenges to your claims
- **Bond Management**: Never submit claims without sufficient bond
- **Private Keys**: Secure private keys, use hardware wallets

### 2. Performance

- **Fast Submission**: Submit claims quickly to be first relayer
- **Gas Optimization**: Optimize gas usage
- **Monitoring**: Efficient event monitoring
- **Automation**: Automate routine tasks

### 3. Risk Management

- **Bond Sizing**: Understand bond requirements
- **Fraud Risk**: Only submit legitimate claims
- **Liquidity Risk**: Monitor liquidity pool status
- **Gas Risk**: Monitor gas prices

## Economics

### Costs

- **Gas Fees**: For submitting claims and finalizing
- **Bond Capital**: Locked until finalization
- **Infrastructure**: Monitoring and automation costs

### Revenue

- **Relayer Fees**: Currently none (future: optional fees)
- **First Mover**: Being first relayer may provide advantages

### Profitability

- Calculate: Revenue - Costs - Risk
- Consider gas prices, bond requirements, competition
- Monitor market conditions

## Troubleshooting

### Claim Rejected

- **Check Bond**: Ensure sufficient bond posted
- **Verify Deposit**: Verify deposit exists on source chain
- **Check Parameters**: Verify all parameters are correct
- **Review Errors**: Check error messages

### Bond Slashed

- **Investigate**: Understand why challenge succeeded
- **Review Process**: Improve deposit verification
- **Prevent Future**: Enhance monitoring and verification

### High Gas Costs

- **Wait**: Consider waiting for lower gas prices
- **Batch**: Batch multiple claims if possible
- **Layer 2**: Consider Layer 2 solutions

## Monitoring

### Key Metrics

- **Claims Submitted**: Total claims submitted
- **Success Rate**: Percentage of successful claims
- **Bond Utilization**: Amount of capital locked in bonds
- **Gas Costs**: Average gas costs per claim
- **Finalization Time**: Time to finalize claims

### Alerts

- **Failed Claims**: Alert on failed claim submissions
- **Challenges**: Alert when claims are challenged
- **Bond Issues**: Alert on bond-related issues
- **Gas Prices**: Alert on high gas prices

## References

- Contract Addresses: `docs/bridge/trustless/`
- Architecture: `docs/bridge/trustless/ARCHITECTURE.md`
- Security: `docs/bridge/trustless/SECURITY.md`