# Rate Limiting Documentation

## Overview

This document describes rate limiting mechanisms for the trustless bridge system to prevent spam and bound tail risk.

## Current State

### Basic Rate Limiting

- Epoch-based rate limiting (if implemented)
- Per-relayer limits
- Configurable limits

## Rate Limiting Strategies

### 1. Per-Relayer Limits

**Current**: Max claims per epoch (e.g., 100 per hour)

**Enhancement**: More sophisticated limits
```solidity
mapping(address => RateLimit) public rateLimits;

struct RateLimit {
    uint256 maxClaimsPerHour;
    uint256 maxClaimsPerDay;
    uint256 currentHourCount;
    uint256 currentDayCount;
    uint256 lastReset;
}
```

### 2. Per-Deposit-Amount Limits

**Purpose**: Prevent large deposit spam

**Implementation**:
```solidity
mapping(address => mapping(uint256 => uint256)) public amountLimits; // relayer => amount tier => count

// Tier 1: < 1 ETH
// Tier 2: 1-10 ETH
// Tier 3: > 10 ETH
```

### 3. Dynamic Rate Limiting

**Purpose**: Adjust based on network conditions

**Implementation**:
```solidity
function getRateLimit(address relayer) public view returns (uint256) {
    uint256 baseLimit = 100;
    uint256 gasMultiplier = gasPrice > 100 gwei ? 2 : 1;
    return baseLimit * gasMultiplier;
}
```

## Spam Prevention

### 1. Minimum Deposit Amounts

**Purpose**: Prevent dust attacks

**Implementation**:
```solidity
uint256 public constant MIN_DEPOSIT = 0.001 ether;

function submitClaim(...) external {
    require(amount >= MIN_DEPOSIT, "Amount too small");
    // ...
}
```

### 2. Cooldown Periods

**Purpose**: Prevent rapid-fire attacks

**Implementation**:
```solidity
mapping(address => uint256) public lastClaimTime;
uint256 public constant COOLDOWN = 60 seconds;

function submitClaim(...) external {
    require(block.timestamp >= lastClaimTime[msg.sender] + COOLDOWN, "Cooldown active");
    lastClaimTime[msg.sender] = block.timestamp;
    // ...
}
```

### 3. Reputation System

**Purpose**: Penalize repeat offenders

**Implementation**:
```solidity
mapping(address => uint256) public violationCount;
mapping(address => uint256) public cooldownMultiplier;

function submitClaim(...) external {
    uint256 cooldown = COOLDOWN * (1 + cooldownMultiplier[msg.sender]);
    require(block.timestamp >= lastClaimTime[msg.sender] + cooldown, "Cooldown active");
    // ...
}
```

## Testing

### Test Suite

Create `test/bridge/trustless/RateLimiting.t.sol`:
- Test rate limit enforcement
- Test cooldown periods
- Test spam prevention
- Test edge cases

## Recommendations

### Phase 1: Basic Enhancement

1. Implement per-relayer limits
2. Add minimum deposit amounts
3. Add cooldown periods

### Phase 2: Advanced Features

4. Dynamic rate limiting
5. Reputation system
6. Tiered limits

## References

- Contracts: `contracts/bridge/trustless/`
- Test Suite: `test/bridge/trustless/RateLimiting.t.sol`