Martinh/ntt config update (#160)

* steps to config rate limit * add queue details * grammarly check * add details about pausing contract * Apply suggestions from code review Co-authored-by: Erin Shaben <[email protected]> --------- Co-authored-by: Ilaria <[email protected]> Co-authored-by: Erin Shaben <[email protected]>
wormhole-foundation · Dec 6, 2024 · 6862950 · 6862950
1 parent 3be413c
commit 6862950
Show file tree

Hide file tree

Showing 2 changed files with 89 additions and 4 deletions.
diff --git a/build/contract-integrations/native-token-transfers/configuration/access-control.md b/build/contract-integrations/native-token-transfers/configuration/access-control.md
@@ -12,6 +12,25 @@ NTT can be paused on a particular chain by updating the `paused` parameter on th
 - **Owner** - full control over NTT contracts, can perform administrative functions. Has the ability to un-pause contracts if they have been paused
 - **Pauser** - can pause NTT contracts to halt token transfers temporarily. This role is crucial for responding quickly to adverse events without a prolonged governance process. Cannot un-pause contracts
 
+You may verify the current owner, pauser, and paused status of the NTT Manager contract on the `deployment.json` file in your NTT project directory.
+
+```json
+{
+    "network": "Testnet",
+    "chains": {
+        "Sepolia": {
+            "version": "1.1.0",
+            "mode": "burning",
+            "paused": true, // set to true to pause the contract
+            "owner": "0x0088DFAC40029f266e0FF62B82E47A07467A0345",
+            "manager": "0x5592809cf5352a882Ad5E9d435C6B7355B716357",
+            //...
+            "pauser": "0x0088DFAC40029f266e0FF62B82E47A07467A0345"
+        }
+    }
+}
+```
+
 !!! note
     While the `Pauser` can pause contracts, the ability to un-pause contracts is callable only by the `Owner`.
 

diff --git a/build/contract-integrations/native-token-transfers/configuration/rate-limiting.md b/build/contract-integrations/native-token-transfers/configuration/rate-limiting.md
@@ -7,22 +7,88 @@ description: Learn about rate limits in Wormhole NTT by configuring send/receive
 
 The Native Token Transfer (NTT) framework provides configurable per-chain rate limits for sending and receiving token transfers. Integrators can manage these limits via their own governance processes to quickly adapt to on-chain activity.
 
-If a transfer is rate-limited on the source chain and queueing is enabled via `shouldQueue = true`, the transfer is placed into an outbound queue and can be released after the duration of the rate limit expires.
+If a transfer is rate-limited on the source chain and queueing is enabled via `shouldQueue = true`, the transfer is placed into an outbound queue and can be released after the rate limit expires.
 
 You can configure the following limits on every chain where NTT is deployed directly using the manager:
 
 - **Sending limit** - a single outbound limit for sending tokens from the chain
-- **Per-chain receiving limits** - the maximum receiving limit, which can be configured on a per-chain basis. For example, allowing `100` tokens to be received from Ethereum, but only 50 tokens to be received from Arbitrum
+- **Per-chain receiving limits** - the maximum receiving limit, which can be configured on a per-chain basis. For example, allowing 100 tokens to be received from Ethereum but only 50 tokens to be received from Arbitrum
 
 Rate limits are replenished every second over a fixed duration. While the default duration is 24 hours, the value is configurable at contract creation. Rate-limited transfers on the destination chain are added to an inbound queue with a similar release delay.
 
+## Update Rate Limits
+
+To configure or update the sending and receiving rate limits, follow these steps:
+
+1. **Locate the deployment file** - open the `deployment.json` file in your NTT project directory. This file contains the configuration for your deployed contracts
+
+2. **Modify the limits section** - for each chain, locate the limits field and update the outbound and inbound values as needed
+
+    ```json
+    "limits": {
+        "outbound": "1000.000000000000000000",
+        "inbound": {
+            "Ethereum": "100.000000000000000000",
+            "Arbitrum": "50.000000000000000000"
+        }
+    }
+    ```
+
+     - **`outbound`** - sets the maximum tokens allowed to leave the chain
+     - **`inbound`** - configures per-chain receiving limits for tokens arriving from specific chains
+
+3. **Push the configuration** - use the NTT CLI to synchronize the updated configuration with the blockchain
+
+    ```bash
+    ntt push
+    ```
+
+4. **Verify the changes** - after pushing, confirm the new rate limits by checking the deployment status
+
+    ```bash
+    ntt status
+    ```
+
+???- note "`deployment.json` example"
+    ```json
+    {
+        "network": "Testnet",
+        "chains": {
+            "Sepolia": {
+                "version": "1.1.0",
+                "mode": "burning",
+                "paused": false,
+                "owner": "0x0088DFAC40029f266e0FF62B82E47A07467A0345",
+                "manager": "0x5592809cf5352a882Ad5E9d435C6B7355B716357",
+                "token": "0x5CF5D6f366eEa7123BeECec1B7c44B2493569995",
+                "transceivers": {
+                    "threshold": 1,
+                    "wormhole": {
+                        "address": "0x91D4E9629545129D427Fd416860696a9659AD6a1",
+                        "pauser": "0x0088DFAC40029f266e0FF62B82E47A07467A0345"
+                    }
+                },
+                "limits": {
+                    "outbound": "184467440737.095516150000000000",
+                    "inbound": {
+                        "ArbitrumSepolia": "500.000000000000000000"
+                    }
+                },
+                "pauser": "0x0088DFAC40029f266e0FF62B82E47A07467A0345"
+            }
+        }
+    }
+    ```
+
 ## Queuing Mechanism
 
 When a transfer exceeds the rate limit, it is held in a queue and can be released after the set rate limit duration has expired. The sending and receiving queuing behavior is as follows:
 
 - **Sending** - if an outbound transfer violates rate limits, users can either revert and try again later or queue their transfer. Users must return after the queue duration has expired to complete sending their transfer
-- **Receiving** - if an inbound transfer violates rate limits, it is held in a queue. Users or relayers must return after the queue duration has expired to complete receiving their transfer on the destination chain
-
+- **Receiving** - if an inbound transfer violates rate limits, it is in a queue. Users or relayers must return after the queue duration has expired to complete receiving their transfer on the destination chain
+
+Queuing is configured dynamically during each transfer by passing the `shouldQueue` parameter to the [`transfer` function](https://github.com/wormhole-foundation/native-token-transfers/blob/5e7ceaef9a5e7eaa13e823a67c611dc684cc0c1d/evm/src/NttManager/NttManager.sol#L171-L182){target=\_blank} in the `NttManager` contract.
+
 ## Cancel Flows
 
 If users bridge frequently between a given source chain and destination chain, the capacity could be exhausted quickly. Loss of capacity can leave other users rate-limited, potentially delaying their transfers.  The outbound transfer cancels the inbound rate limit on the source chain to avoid unintentional delays. This allows for refilling the inbound rate limit by an amount equal to the outbound transfer amount and vice-versa, with the inbound transfer canceling the outbound rate limit on the destination chain and refilling the outbound rate limit with an amount.