Motivation
The motivation for IBC rate limiting comes from empirical observations of blockchain bridge hacks where rate limits would have massively reduced the stolen amount of assets:- Polynetwork Bridge Hack ($611 million) - Details
- BNB Bridge Hack ($586 million) - Details
- Wormhole Bridge Hack ($326 million) - Details
- Nomad Bridge Hack ($190 million) - Details
- Harmony Bridge Hack ($100 million) - Details
- Dragonberry IBC bug (amount at risk undisclosed, but discovered by Neutron core developers)
Rate Limiting Architecture
The system consists of two components:1. IBC Rate Limit Module (Go Middleware)
- Minimal IBC middleware that intercepts IBC packets
- Contract integration forwards packet data to CosmWasm contract
- Failure handling automatically reverts failed transfers
- Governance management of contract address parameter
2. Rate Limiting Contract (CosmWasm)
- Rate limiting logic implemented in upgradeable CosmWasm contract
- Contract-specific behavior varies by implementation
- Governance upgradeable without chain upgrades
Contract-Dependent Behavior: The actual rate limiting strategy (quotas, time periods, flow tracking, token handling, etc.) is entirely determined by the CosmWasm contract implementation. Different contracts may implement completely different approaches.
Key Features
Bridge Security
Prevents catastrophic fund loss from bridge exploits by enabling rate limiting controls.
Minimal Middleware
Lightweight packet forwarding without implementing rate limiting logic in consensus code.
Governance Managed
Contract address can be updated through governance proposals without chain upgrades.
Flexible Implementation
Rate limiting strategy is determined by the CosmWasm contract, enabling diverse approaches.
Module Implementation
The Go module provides the minimal middleware interface:- Packet Forwarding: Sends packet information to the configured contract for send/receive operations
- Failure Handling: Automatically calls contract’s undo function when packets fail
- Parameter Management: Manages the contract address parameter through governance
- Error Handling: Distinguishes rate limit errors from other contract errors based on error message content
Separation of Concerns: The Go module handles IBC packet interception and forwarding, while the CosmWasm contract implements all rate limiting logic. This enables flexible rate limiting strategies without consensus code changes.
Contract Message Interface
The module sends standardized sudo messages to the contract:send_packet
Sent when an IBC packet is being transmitted from Neutron.recv_packet
Sent when an IBC packet is being received by Neutron.undo_send
Sent when a packet send fails and needs to be reverted.Message Structure: The module forwards complete packet information including sequence, source/destination channels, token data, and timeout information. How the contract processes this information depends on the contract’s implementation.
Module Behavior
When Contract Address is Set
- All IBC transfers are forwarded to the contract for approval
- If contract returns error containing “rate limit exceeded”, transfer is blocked
- Failed packets automatically trigger undo_send message to contract
- Other contract errors return generic contract error
When Contract Address is Empty
- All IBC transfers proceed normally without any rate limiting
- Module acts as transparent pass-through middleware
Usage Strategy
Current Implementation
- Manual Configuration: All rate limiting policies must be configured manually through governance
- Contract Deployment: Governance must deploy and configure the CosmWasm contract separately