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**:
```solidity
// 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)**:
```solidity
// 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**:
```bash
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

```bash
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**:
```bash
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

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

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

### Providing WETH Liquidity

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

### Withdrawing Liquidity

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

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

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

```solidity
// 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);
```