smom-dbis-138/docs/bridge/trustless/INTEGRATION.md

Trustless Bridge Integration Guide

Overview

This guide explains how to integrate with the trustless bridge system as a user, relayer, challenger, or liquidity provider.

For Users: Depositing and Receiving Funds

Depositing from ChainID 138

1. Deposit Native ETH:

// On ChainID 138
Lockbox138 lockbox = Lockbox138(LOCKBOX138_ADDRESS);
bytes32 nonce = keccak256(abi.encodePacked(recipient, block.timestamp));
uint256 depositId = lockbox.depositNative{value: amount}(recipient, nonce);

2. Deposit ERC-20 Token (WETH):

// On ChainID 138
IERC20(token).approve(LOCKBOX138_ADDRESS, amount);
uint256 depositId = lockbox.depositERC20(token, amount, recipient, nonce);

3. Wait for Relayer: A relayer will submit your claim to Ethereum (typically within minutes)

4. Receive on Ethereum: After challenge window (30 min), funds are available on Ethereum

Receiving Funds on Ethereum

Funds are automatically available after:

• Claim is submitted by relayer
• Challenge window expires (30 minutes) without challenge
• Claim is finalized

For Relayers: Submitting Claims

Setup

1. Deploy Relayer Service: See services/relayer/trustless-bridge-relayer/

2. Configure Environment:

export CHAIN138_RPC_URL="https://rpc.d-bis.org"
export ETHEREUM_RPC_URL="https://eth.llamarpc.com"
export LOCKBOX138_ADDRESS="0x..."
export INBOX_ETH_ADDRESS="0x..."
export BOND_MANAGER_ADDRESS="0x..."
export RELAYER_PRIVATE_KEY="0x..."

3. Fund Relayer Address: Ensure relayer has sufficient ETH for:
   • Gas fees
   • Bonds (110% of deposit amount, minimum 1 ETH)

Running the Relayer

cd services/relayer/trustless-bridge-relayer
npm install
npm start

The relayer will:

• Monitor Deposit events on ChainID 138
• Submit claims to InboxETH on Ethereum
• Post required bonds automatically
• Earn relay fees (if configured)

Economics

• Costs: Gas fees + bonds (returned after finalization)
• Revenue: Relay fees (future feature)
• Risk: Bond slashed if claim is fraudulent

For Challengers: Monitoring and Challenging

Setup

1. Deploy Challenger Service: See services/challenger/trustless-bridge-challenger/

2. Configure Environment:

export CHAIN138_RPC_URL="https://rpc.d-bis.org"
export ETHEREUM_RPC_URL="https://eth.llamarpc.com"
export LOCKBOX138_ADDRESS="0x..."
export INBOX_ETH_ADDRESS="0x..."
export CHALLENGE_MANAGER_ADDRESS="0x..."
export CHALLENGER_PRIVATE_KEY="0x..."

3. Fund Challenger Address: Need ETH for gas fees

Running the Challenger

cd services/challenger/trustless-bridge-challenger
npm install
npm start

The challenger will:

• Monitor ClaimSubmitted events on Ethereum
• Verify claims against source chain (ChainID 138)
• Submit challenges with fraud proofs when invalid claims detected
• Earn 50% of slashed bond as reward

Economics

• Costs: Gas fees for challenges
• Revenue: 50% of slashed bond
• Incentive: Economic reward for detecting fraud

For Liquidity Providers: Providing Liquidity

Providing ETH Liquidity

// On Ethereum
LiquidityPoolETH pool = LiquidityPoolETH(LIQUIDITY_POOL_ADDRESS);
pool.provideLiquidity{value: amount}(LiquidityPoolETH.AssetType.ETH);

Providing WETH Liquidity

// On Ethereum
IERC20(weth).approve(LIQUIDITY_POOL_ADDRESS, amount);
pool.depositWETH(amount);

Withdrawing Liquidity

// Withdraw ETH
pool.withdrawLiquidity(amount, LiquidityPoolETH.AssetType.ETH);

// Withdraw WETH
pool.withdrawLiquidity(amount, LiquidityPoolETH.AssetType.WETH);

Note: Withdrawals may be blocked if they would violate minimum liquidity ratio (110% of pending claims).

Economics

• Revenue: 5 bps (0.05%) fee on bridge amounts
• Risk: Locked liquidity while claims are pending
• Returns: Based on bridge volume and fee rate

For Developers: Integrating Swap Functionality

Using BridgeSwapCoordinator

// After claim is finalized
BridgeSwapCoordinator coordinator = BridgeSwapCoordinator(COORDINATOR_ADDRESS);
uint256 stablecoinAmount = coordinator.bridgeAndSwap(
    depositId,
    recipient,
    LiquidityPoolETH.AssetType.ETH, // or WETH
    USDT_ADDRESS, // or USDC/DAI
    amountOutMin, // Slippage protection
    "" // Optional route data for 1inch
);

Direct Swap Usage

// Swap ETH/WETH to stablecoin
SwapRouter router = SwapRouter(SWAP_ROUTER_ADDRESS);
uint256 stablecoinAmount = router.swapToStablecoin(
    LiquidityPoolETH.AssetType.ETH,
    USDT_ADDRESS,
    amountIn,
    amountOutMin,
    "" // Optional 1inch route data
);

Security Considerations

1. Bonds: Relayers must post bonds exceeding deposit amount (110%)
2. Challenge Window: 30 minutes for fraud detection
3. Liquidity Ratio: Minimum 110% must remain in pool
4. Slippage: Always use amountOutMin for swaps

Monitoring

Key Events to Monitor

• Deposit (Lockbox138): New deposits on ChainID 138
• ClaimSubmitted (InboxETH): New claims on Ethereum
• ClaimChallenged (ChallengeManager): Claims being challenged
• FraudProven (ChallengeManager): Fraud detected, bond slashed
• ClaimFinalized (ChallengeManager): Claim finalized, ready for release
• BridgeSwapExecuted (BridgeSwapCoordinator): Bridge + swap completed

Useful Queries

// Check claim status
(bool exists, bool finalized, bool challenged, uint256 windowEnd) = 
    inbox.getClaimStatus(depositId);

// Check bond status
(address relayer, uint256 amount, bool slashed, bool released) = 
    bondManager.getBond(depositId);

// Check liquidity pool stats
(uint256 total, uint256 pending, uint256 available) = 
    liquidityPool.getPoolStats(LiquidityPoolETH.AssetType.ETH);