How-to

This guide provides instructions for configuring and managing the IBC Rate Limit module. The module itself only manages the contract address parameter - all rate limiting functionality is handled by the CosmWasm contract.

Module Configuration

The IBC Rate Limit module has a single parameter that specifies which CosmWasm contract handles rate limiting decisions.

Checking Current Parameters

To check the current contract address parameter via REST:

curl https://rpc.neutron.org/neutron/ibc-rate-limit/v1beta1/params

Sample response:

{
  "params": {
    "contract_address": "neutron1abcdef..."
  }
}

Updating the Contract Address

To update the contract address, governance must submit an update-params proposal:

neutron tx gov submit-proposal update-params proposal.json --from=<key> --chain-id=<chain-id>

Example proposal.json:

{
  "title": "IBC Rate Limit Contract Address Update",
  "description": "Update the contract address for the IBC Rate Limit module",
  "messages": [
    {
      "@type": "/neutron.ibcratelimit.v1beta1.MsgUpdateParams",
      "authority": "neutron10d07y265gmmuvt4z0w9aw880jnsr700j7g7ejq",
      "params": {
        "contract_address": "neutron1newaddress..."
      }
    }
  ],
  "deposit": "10000000untrn"
}

Clearing the Contract Address

To disable rate limiting by clearing the contract address:

{
  "title": "Disable IBC Rate Limiting",
  "description": "Clear the contract address to disable rate limiting",
  "messages": [
    {
      "@type": "/neutron.ibcratelimit.v1beta1.MsgUpdateParams",
      "authority": "neutron10d07y265gmmuvt4z0w9aw880jnsr700j7g7ejq",
      "params": {
        "contract_address": ""
      }
    }
  ],
  "deposit": "10000000untrn"
}

Module Behavior

When Contract Address is Set

When a valid contract address is configured:

1. Send Operations: The module forwards packet information to the contract via send_packet message
2. Receive Operations: The module forwards packet information to the contract via recv_packet message
3. Failed Packets: The module automatically calls the contract's undo_send function
4. Rate Limit Exceeded: If the contract returns an error containing "rate limit exceeded", the transfer is blocked

When Contract Address is Empty

When no contract address is configured:

• All IBC transfers proceed normally without any rate limiting
• The module acts as a pass-through middleware with no additional functionality

Error Handling

The module handles various error scenarios:

Rate Limit Exceeded

Error: rate limit exceeded for channel-0 and denom untrn

This error occurs when the contract rejects a transfer due to rate limit constraints.

Contract Error

Error: contract error: <contract-specific message>

This error occurs when the contract returns an error that doesn't contain "rate limit exceeded".

Bad Revert Events

If the module fails to call the contract's undo function for failed packets, it emits a bad_revert event:

{
  "type": "bad_revert",
  "attributes": [
    {"key": "module", "value": "rate-limited-ibc"},
    {"key": "failure_type", "value": "acknowledgment"},
    {"key": "packet", "value": "<packet-data>"},
    {"key": "acknowledgement", "value": "<ack-data>"}
  ]
}

Contract Requirements

For a CosmWasm contract to work with this module, it must implement the following sudo message handlers:

Required Sudo Messages

1. send_packet: Handle outgoing packet information
2. recv_packet: Handle incoming packet information
3. undo_send: Handle failed packet reversals

The contract should return an error containing "rate limit exceeded" to block transfers.

Monitoring and Debugging

Module Events

Monitor these events for module-specific issues:

• bad_revert: Indicates the module failed to notify the contract about a failed packet

Contract Logs

Monitor contract logs for rate limiting decisions and any contract-specific events.

Parameter Changes

Monitor governance proposals for contract address updates:

neutron query gov proposals --status voting_period

Best Practices

1. Test Contract Integration: Always test contract behavior in a test environment before governance updates
2. Monitor Events: Set up monitoring for bad_revert events to detect contract communication issues
3. Governance Coordination: Coordinate contract address updates with contract deployments
4. Emergency Procedures: Have procedures ready to clear the contract address if needed to restore transfer functionality