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:

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:

// 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