[IBCGO-10] Rate Limting Overview and Setting Limits

docs/docs/04-middleware/03-rate-limit-middleware/01-overview.md

@@ -0,0 +1,30 @@
+---
+title: Overview
+sidebar_label: Overview
+sidebar_position: 1
+slug: /apps/rate-limit-middleware/overview
+---
+
+# Overview
+
+Learn about rate limit middleware, a middleware that can be used in combination with token transfers (ICS-20) to control the amount of in and outflows of assets in a certain time period. 
+
+## What is Rate Limit Middleware?
+
+The rate limit middleware enforces rate limits on IBC token transfers coming into and out of a chain. It supports: 
+
+- **Risk Mitigation:** In case of a bug exploit, attack or economic failure of a connected chain, it limits the impact to the in/outflow specified for a given time period. 
+- **Token Filtering:** Through the use of a blacklist, the middleware can completely block tokens entering or leaving a domain, relevant for complicance or giving asset issuers greater control over the domains token can be sent to. 
+- **Uninterupted Packet Flow:** When desired, rate limits can be bypassed by using the whitelist, to avoid any restriction on asset in or outflows. 
+
+## How it works
+
+The rate limiting middleware determines whether tokens can flow into or out of a chain. The middleware does this by: 
+
+1. Check transfer limits for an asset (Quota): When tokens are recieved or sent, the middleware determines whether the amount of tokens flowing in or out have exceeded the limit. 
+
+2. Track in or outflow: When tokens enter or leave the chain, the amount transferred is tracked in state
+
+3. Block or allow token flow: Dependent on the limit, the middleware will either allow the tokens to pass through or block the tokens.
+
+4. Handle failures: If the packet timesout or fails to be delivered, the middleware ensures limits are correctly recorded. 

docs/docs/04-middleware/03-rate-limit-middleware/02-integration.md

@@ -0,0 +1,10 @@
+---
+title: Integration
+sidebar_label: Integration
+sidebar_position: 2
+slug: /apps/rate-limit-middleware/integration
+---
+
+# Integration
+
+This section should be completed once the middleware wiring approach is finalised. 

docs/docs/04-middleware/03-rate-limit-middleware/03-setting-limits.md

@@ -0,0 +1,22 @@
+---
+title: Setting Rate Limits
+sidebar_label: Setting Rate Limits
+sidebar_position: 3
+slug: /apps/rate-limit-middleware/setting-rate-limits
+---
+
+# Setting Rate Limits
+
+Rate limits are set through a governance-gated authority on a per denom, and per channel / client basis. To add a rate limit, the [`MsgAddRateLimit`](https://github.com/cosmos/ibc-go/blob/main/modules/apps/rate-limiting/types/msgs.go#L26-L34) message must be executed which includes: 
+
+- Denom: the asset that the rate limit should be applied to
+- ChannelOrClientId: the channelID for use with IBC classic connections, or the clientID for use with IBC v2 connections
+- MaxPercentSend: the outflow threshold as a percentage of the `channelValue`. More explicitly, a packet being sent would exceed the threshold quota if: (Outflow - Inflow + Packet Amount) / channelValue is greater than MaxPercentSend
+- MaxPercentRecv: the inflow threshold as a percentage of the `channelValue`
+- DurationHours: the length of time, after which the rate limits reset
+
+## Updating, Removing or Resetting Rate Limits
+
+- If rate limits were set to be too low or high for a given channel/client, they can be updated with [`MsgUpdateRateLimit`](https://github.com/cosmos/ibc-go/blob/main/modules/apps/rate-limiting/types/msgs.go#L81-L89). 
+- If rate limits are no longer needed, they can be removed with [`MsgRemoveRateLimit`](https://github.com/cosmos/ibc-go/blob/main/modules/apps/rate-limiting/types/msgs.go#L136-L141).
+- If the flow counter needs to be resent for a given rate limit, it is possible to do so with [`MsgResetRateLimit`](https://github.com/cosmos/ibc-go/blob/main/modules/apps/rate-limiting/types/msgs.go#L169-L174).

docs/docs/04-middleware/03-rate-limit-middleware/_category_.json

@@ -0,0 +1,5 @@
+{
+  "label": "Rate Limit Middleware",
+  "position": 3,
+  "link": null
+}