Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

fix doc links #487

Merged
merged 5 commits into from
Aug 9, 2024
Merged

fix doc links #487

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
8fef9ff
fix doc links
cam-schultz Aug 8, 2024
ea3b7cd
document resending messages
cam-schultz Aug 8, 2024
210de7e
clarify Warp resigning
cam-schultz Aug 8, 2024
d3bea42
Merge branch 'main' into fix-docs
cam-schultz Aug 9, 2024
416a4e8
remove table of contents
cam-schultz Aug 9, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 8 additions & 12 deletions contracts/teleporter/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,15 +1,5 @@
# Teleporter Protocol

- [Teleporter Protocol](#teleporter-protocol)
- [Overview](#overview)
- [Data Flow](#data-flow)
- [Properties](#properties)
- [Fees](#fees)
- [Message Receipts and Fee Redemption](#message-receipts-and-fee-redemption)
- [Required Interface](#required-interface)
- [Teleporter Contract Deployment](#teleporter-contract-deployment)
- [Message Delivery and Execution](#message-delivery-and-execution)

## Overview

Teleporter is a messaging protocol built on top of [Avalanche Warp Messaging (AWM)](https://docs.avax.network/learn/avalanche/awm) that provides a developer-friendly interface for sending and receiving cross-chain messages from within the EVM.
Expand All @@ -28,7 +18,7 @@ The `ITeleporterReceiver` interface provides a single method. All contracts that
## Data Flow

<div align="center">
<img src="../../../resources/TeleporterDataFlowDiagram.png?raw=true"/>
<img src="../../resources/TeleporterDataFlowDiagram.png?raw=true"/>
</div>

## Properties
Expand Down Expand Up @@ -69,9 +59,15 @@ Teleporter is able to ensure that messages are considered delivered even if thei

Note that due to [EIP-150](https://eips.ethereum.org/EIPS/eip-150), the lesser of 63/64<sup>ths</sup> of the remaining gas and the `requiredGasLimit` will be provided to the code executed using `evm.Call()`. This creates an edge case where sufficient gas is provided by the relayer at time of the `requiredGasLimit` check, but less than the `requiredGasLimit` is provided for the message execution. In such a case, the message execution may fail due to having less than the `requiredGasLimit` available, but the message would still be considered received. Such a case is only possible if the remaining 1/64<sup>th</sup> of the `requiredGasLimit` is sufficient for executing the remaining logic of `receiveCrossChainMessage` so that the top level transaction does not also revert. Based on the current implementation, a message must have a `requiredGasLimit` of over 1,200,000 gas for this to be possible. In order to avoid this case entirely, it is recommended for applications sending Teleporter messages to add a buffer to the `requiredGasLimit` such that 63/64<sup>ths</sup> of the value passed is sufficient for the message execution.

## Resending a Message

If the sending Subnet's validator set changes, then it's possible for the receiving Subnet to reject the underlying Warp message due to insufficient signing stake. For example, suppose Subnet A has 5 validators with equal stake weight who all sign a Teleporter message sent to Subnet B. 100% of Subnet A's stake has signed the message. Also suppose Subnet B requires 67% of the sending Subnet's stake to have signed a given Warp message in order for it to be accepted. Before the message can be delivered, however, 5 _more_ validators are added to Subnet A's validator set (all with the same stake weight as the original validators), meaning that the Teleporter message was signed by _only 50%_ of Subnet A's stake. Subnet B will reject this message.

Once sent on chain, Warp messages cannot be re-signed by a new validator set in such a scenario. Teleporter, however, does support re-signing via the function `retrySendCrossChainMessage`, which can be called for any message that has not been acknowledged as delivered to its destination. Under the hood, this packages the Teleporter message into a brand new Warp message that is re-signed by the current validator set.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this part is a little unclear. I think it would be more accurate to say that validators that were not online when the message was sent are not able to sign it, because we don't bootstrap validators.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

To me, this reads well and is a clear explanation of the scenario. I am fine with adding Geoff's summary up top and leaving the detailed explanation in as an example scenario.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I tried a handful of variations that mentioned bootstrapping, but IMO they were all less clear than this description of "if the validator set changes, then signature verification may fail". This example isn't meant to be exhaustive, just to illustrate how Teleporter handles such a scenario.


## Teleporter Messenger Contract Deployment

**Do not deploy the `TeleporterMessenger` contract using `forge create`**. The `TeleporterMessenger` contract must be deployed to the same contract address on every chain. To achieve this, the contract can be deployed using a static transaction that uses Nick's method as documented in [this guide](https://github.com/ava-labs/teleporter/blob/main/utils/contract-deployment/README.md). Alternatively, if creating a new Subnet, the contract can be pre-allocated with the proper address and state in the new chain's [genesis file](https://docs.avax.network/build/subnet/upgrade/customize-a-subnet#setting-the-genesis-allocation).
**Do not deploy the `TeleporterMessenger` contract using `forge create`**. The `TeleporterMessenger` contract must be deployed to the same contract address on every chain. To achieve this, the contract can be deployed using a static transaction that uses Nick's method as documented in [this guide](../..//utils/contract-deployment/README.md). Alternatively, if creating a new Subnet, the contract can be pre-allocated with the proper address and state in the new chain's [genesis file](https://docs.avax.network/build/subnet/upgrade/customize-a-subnet#setting-the-genesis-allocation).

As an example, to include `TeleporterMessenger` `v1.0.0` in the genesis file, include the following values in the `alloc` settings, as documented at the link above. The `storage` values included below correspond to the two contract values that are initialized as part of the default constructor of `TeleporterMessenger`. These are the `ReentrancyGuard` values set in this [abstract contract](../utilities/ReentrancyGuards.sol). Future versions of `TeleporterMessenger` may require different storage value intializations.
```json
Expand Down
4 changes: 2 additions & 2 deletions contracts/teleporter/registry/UPGRADING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@
# Upgrading Teleporter

This document outlines the high-level steps necessary to upgrade Teleporter as a subnet operator, a relayer operator, and a dApp admin. As a reference, the [Teleporter Registry test suite](../../../../tests/flows/teleporter_registry.go) implements the steps described in a test environment.
This document outlines the high-level steps necessary to upgrade Teleporter as a subnet operator, a relayer operator, and a dApp admin. As a reference, the [Teleporter Registry test suite](../../../tests/flows/teleporter_registry.go) implements the steps described in a test environment.

## Register a New Teleporter Version

Once a new Teleporter contract instance is [deployed](../../../../utils/contract-deployment/README.md), the `addProtocolVersion` method of [TeleporterRegistry.sol](./TeleporterRegistry.sol) must be called. This method is only callable if the associated Warp message was sent via an off-chain Warp message, which is provided by a validator's chain config.
Once a new Teleporter contract instance is [deployed](../../../utils/contract-deployment/README.md), the `addProtocolVersion` method of [TeleporterRegistry.sol](./TeleporterRegistry.sol) must be called. This method is only callable if the associated Warp message was sent via an off-chain Warp message, which is provided by a validator's chain config.

The steps to do so are as follows:

Expand Down