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

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

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:

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:

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:

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:

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:

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