Merge pull request #417 from ava-labs/pause-readme

Upgrades README improvements

contracts/src/Teleporter/upgrades/README.md

@@ -27,7 +27,7 @@ In the `TeleporterRegistry` contract, the `latestVersion` state variable returns
 - Version zero is an invalid version, and is used to indicate that a `TeleporterMessenger` contract has not been registered yet.
 - Once a version number is registered in the registry, it cannot be changed, but a previous registered protocol address can be added to the registry with a new version. This is especially important in the case of a rollback to a previous Teleporter version, in which case the previous Teleporter contract address would need to be registered with a new version to the registry.
 
-## Integrating `TeleporterRegistry` with `TeleporterUpgradeable`
+## Integrating `TeleporterUpgradeable` into a dApp
 
 <div align="center">
   <img src="./upgrade-uml.png?raw=true" alt="Upgrade UML diagram"/>
@@ -76,17 +76,7 @@ contract ExampleApp is
 }
 ```
 
-### TeleporterUpgradeable utility
-
-#### Initialization
-
-The `TeleporterUpgradeable` contract constructor saves the Teleporter registry in a state variable used by the inheriting contract, and initializes a `minTeleporterVersion` to the highest `TeleporterMessenger` version registered in `TeleporterRegistry`. `minTeleporterVersion` is used to allow dApp's to specify the Teleporter versions allowed to interact with it.
-
-#### Updating `minTeleporterVersion`
-
-The `TeleporterUpgradeable.updateMinTeleporterVersion` function updates the `minTeleporterVersion` used to check which Teleporter versions can deliver messages to the dApp, and emits the `MinTeleporterVersionUpdated` event. The `updateMinTeleporterVersion` function should **ONLY** be called by the dApp when it completes delivery of messages from the old Teleporter contract, and now wants to update the `minTeleporterVersion` to only allow the new Teleporter version. By default, `updateMinTeleporterVersion` can only be called with a version greater than the current `minTeleporterVersion` and less than `latestVersion` in the Teleporter registry. So once this function is called, the dApp will no longer be able to receive messages from the old Teleporter contract version, unless the old version's Teleporter address was registered in the registry again with a new version.
-
-#### Checking Teleporter upgrade access
+### Checking Teleporter upgrade access
 
 To prevent anyone from calling the dApp's `updateMinTeleporterVersion`, which would disallow messages from old Teleporter versions from being received, this function should be safeguarded with access controls. All contracts deriving from `TeleporterUpgradeable` will need to implement `TeleporterUpgradeable._checkTeleporterUpgradeAccess`. For example, [TeleporterOwnerUpgrade](./TeleporterOwnerUpgradeable.sol) is an abstract contract that inherits `TeleporterUpgradeable`, and implements `_checkTeleporterUpgradeAccess` to check whether the caller is the owner.
 
@@ -107,7 +97,7 @@ Another example would be a dApp that has different roles and priveleges. `_check
     }
 ```
 
-#### Sending with specific Teleporter version
+### Sending with specific Teleporter version
 
 For sending messages with the Teleporter registry, dapps should use `TeleporterUpgradeable._getTeleporterMessenger`. This function by default extends `TeleporterRegistry.getLatestTeleporter`, using the latest version, and adds an extra check on whether the latest Teleporter address is paused. If the dApp wants to send a message through a specific Teleporter version, it can override `_getTeleporterMessenger()` to use the specific Teleporter version with `TeleporterRegistry.getTeleporterFromVersion`.
 
@@ -137,18 +127,79 @@ Using specific version:
         ITeleporterMessenger teleporterMessenger = _getTeleporterMessenger();
 ```
 
-#### Receiving from specific Teleporter versions
+### Receiving from specific Teleporter versions
 
 `TeleporterUpgradeable` also provides an initial implementation of [ITeleporterReceiver.receiveTeleporterMessage](../ITeleporterReceiver.sol) that ensures `_msgSender` is a `TeleporterMessenger` contract with a version greater than or equal to `minTeleporterVersion`. This supports the case where a dApp wants to upgrade to a new version of the `TeleporterMessenger` contract, but still wants to be able to receive messages from the old Teleporter contract.The dApp can override `_receiveTeleporterMessage` to implement its own logic for receiving messages from Teleporter contracts.
 
-#### Pausing Teleporter version interactions
+## Managing a TeleporterUpgradeable dApp
 
-Dapps that inherit from `TeleporterUpgradeable` can pause Teleporter interactions by calling `TeleporterUpgradeable.pauseTeleporterAddress`. This function prevents the contract from interacting with the paused Teleporter address when sending or receiving Teleporter messages.
+dApps that implement `TeleporterUpgradeable` automatically use the latest Teleporter version registered with the `TeleporterRegistry`. Interaction with underlying `TeleporterMessenger` versions can be managed by setting the minimum Teleporter version, and pausing and unpausing specific versions.
 
-`pauseTeleporterAddress` can only be called by addresses with the dApp's upgrade access, checked through `TeleporterUpgradeable._checkTeleporterUpgradeAccess`.
+The following sections include example `cast send` commands for issuing transactions that call contract functions. See the [Foundry Book](https://book.getfoundry.sh/reference/cast/cast-send) for details on how to issue transactions using common wallet options.
+
+### Managing the Minimum Teleporter version
+
+The `TeleporterUpgradeable` contract constructor saves the Teleporter registry in a state variable used by the inheriting dApp contract, and initializes a `minTeleporterVersion` to the highest `TeleporterMessenger` version registered in `TeleporterRegistry`. `minTeleporterVersion` is used to allow dApp's to specify the Teleporter versions allowed to interact with it.
+
+#### Updating `minTeleporterVersion`
+
+The `TeleporterUpgradeable.updateMinTeleporterVersion` function updates the `minTeleporterVersion` used to check which Teleporter versions can be used for sending and receiving messages. **Once the `minTeleporterVersion` is increased, any undelivered messages sent by other chains using older versions of Teleporter will never be able to be received**. The `updateMinTeleporterVersion` function can only be called with a version greater than the current `minTeleporterVersion` and less than `latestVersion` in the Teleporter registry.
+
+> Example: Update the minimum Teleporter version to 2
+>```
+>cast send <DAPP_ADDRESS> "updateMinTeleporterVersion(uint256)" 2 
+>```
+
+### Pausing Teleporter version interactions
+
+dApps that inherit from `TeleporterUpgradeable` can pause Teleporter interactions by calling `TeleporterUpgradeable.pauseTeleporterAddress`. This function prevents the dApp contract from interacting with the paused Teleporter address when sending or receiving Teleporter messages.
+
+`pauseTeleporterAddress` can only be called by addresses with the dApps upgrade access, checked through `TeleporterUpgradeable._checkTeleporterUpgradeAccess`.
+
+The Teleporter address corresponding to a Teleporter version can be fetched from the registry with `TeleporterRegistry.getAddressFromVersion`
+
+> Example: Pause Teleporter version 3
+>```
+>versionThreeAddress=$(cast call <REGISTRY_ADDRESS> "getAddressFromVersion(uint256)(address)" 3)
+>cast send <DAPP_ADDRESS> "pauseTeleporterAddress(address)" $versionThreeAddress
+>```
+
+#### Pause all Teleporter interactions
+
+To pause all Teleporter interactions, `TeleporterUpgradeable.pauseTeleporterAddress` must be called for every Teleporter version from the `minTeleporterVersion` to the latest Teleporter version registered in `TeleporterRegistry`. Note that there may be gaps in Teleporter versions registered with `TeleporterRegistry`, but they will always be in increasing order. The latest Teleporter version can be obtained by inspecting the public variable `TeleporterRegistry.latestVersion`. The `minTeleporterVersion` can be obtained by calling `TeleporterUpgradeable.getMinTeleporterVersion`.
+
+> Example: Pause all registered Teleporter versions
+>```
+># Fetch the minimum Teleporter version
+>minVersion=$(cast call <DAPP_ADDRESS> "getMinTeleporterVersion()(uint256)")
+>
+># Fetch the latest registered version
+>latestVersion=$(cast call <REGISTRY_ADDRESS> "latestVersion()(uint256)")
+>
+># Pause all registered versions
+>for ((version=minVersion; version<=latestVersion; version++))
+>do
+>  # Fetch the version address if it's registered
+>  versionAddress=$(cast call <REGISTRY_ADDRESS> "getAddressFromVersion(uint256)(address)" $version)
+>
+>  if [ $? -eq 0 ]; then
+>    # If cast call is successful, proceed to cast send
+>    cast send <DAPP_ADDRESS> "pauseTeleporterAddress(address)" $versionAddress
+>  else
+>    # If cast call fails, print an error message and skip to the next iteration
+>    echo "Version $version not registered. Skipping."
+>  fi
+>done
+>```
 
 #### Unpausing Teleporter version interactions
 
 As with pausing, dapps can unpause Teleporter interactions by calling `TeleporterUpgradeable.unpauseTeleporterAddress`. This unpause function allows receiving Teleporter message from the unpaused Teleporter address, and also enables the sending of messages through the unpaused Teleporter address in `_getTeleporterMessenger()`. Unpausing is also only allowed by addresses with the dApp's upgrade access.
 
 Note that receiving Teleporter messages is still governed by the `minTeleporterVersion` check, so even if a Teleporter address is unpaused, the dApp will not receive messages from the unpaused Teleporter address if the Teleporter version is less than `minTeleporterVersion`.
+
+> Example: Unpause Teleporter version 3
+>```
+>versionThreeAddress=$(cast call <REGISTRY_ADDRESS> "getAddressFromVersion(uint256)(address)" 3)
+>cast send <DAPP_ADDRESS> "unpauseTeleporterAddress(address)" $versionThreeAddress
+>```