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 2 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
13 changes: 7 additions & 6 deletions contracts/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,16 +1,17 @@
## Teleporter Messenger Contract
This directory contains Solidity contracts implementing the Teleporter messaging protocol.
## Avalanche Warp Messaging Contracts
This directory contains Solidity contracts that utilize Avalanche Warp Messaging for a variety of cross-chain workflows. This includes:
- Governance contracts for authenticating messages directly from validators using Warp
- Mock contracts used for testing
- Teleporter contracts for sending cross-chain messages using the Teleporter protocol
- General purpose utilities that are used by the above applications

This directory is set up as a [Foundry](https://github.com/foundry-rs/foundry) project. Use the `scripts/install_foundry.sh` to install the correct version of the ava-labs fork of foundry. Further documentation about given contracts can be found in`src/teleporter/`.
This directory is set up as a [Foundry](https://github.com/foundry-rs/foundry) project. Use the `scripts/install_foundry.sh` to install the correct version of the ava-labs fork of foundry. Further documentation about given contracts can be found in`contracts/teleporter/`.

## Building and Running
- To compile the contracts run `forge build` from this directory.
- Similarly, to run unit tests, run `forge test`.
- See additional testing and deployment options [here](https://book.getfoundry.sh/forge/).

## Deployment
iansuvak marked this conversation as resolved.
Show resolved Hide resolved
**Do not deploy using `forge create`**. See [this guide](https://github.com/ava-labs/teleporter/blob/main/utils/contract-deployment/README.md) on how to properly deploy the `TeleporterMessenger` contract to your Subnet.

## Generate documentation
- Documentation can be generated by running `forge doc --build` from this repository. By default, this will generate documentation to `contracts/docs/`, and an HTML book to `contracts/docs/book/`. It's also possible to serve this book locally by running `forge doc --serve <PORT>`.

11 changes: 9 additions & 2 deletions contracts/teleporter/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@
- [Required Interface](#required-interface)
- [Teleporter Contract Deployment](#teleporter-contract-deployment)
- [Message Delivery and Execution](#message-delivery-and-execution)
- [Resending a Message](#resending-a-message)
Copy link
Collaborator

Choose a reason for hiding this comment

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

Nit: Github provides an outline/table of contents by default. Can we remove the manual one while we're here so it doesn't fall out of date in the future?

image

Copy link
Contributor Author

Choose a reason for hiding this comment

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

100%


## Overview

Expand All @@ -28,7 +29,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 @@ -65,10 +66,16 @@ Teleporter messages are delivered by calling the `receiveTeleporterMessage` func

## Teleporter Contract Deployment

The `TeleporterMessenger` contract must be deployed to the same contract address on every chain. This is acheived using Nick's keyless transaction method as described [here](../../../utils/contract-deployment/README.md). As a result, Warp messages sent from the resulting contract address are ensured to have the same payload format as defined by the contract itself.
The `TeleporterMessenger` contract must be deployed to the same contract address on every chain. This is acheived using Nick's keyless transaction method as described [here](../../utils/contract-deployment/README.md). As a result, Warp messages sent from the resulting contract address are ensured to have the same payload format as defined by the contract itself.

## Message Delivery and Execution

Teleporter is able to ensure that messages are considered delivered even if their execution fails (i.e. reverts) by using `evm.Call()` with a pre-defined gas limit to execute the message payload. This gas limit is specified by each message in the call to `sendCrossChainMessage`. Relayers must provide at least enough gas for the sub-call in addition to the standard gas used by a call to `receiveCrossChainMessage`. In the event that a message execution runs out of gas or reverts for any other reason, the hash of the message payload is stored by the receiving Teleporter contract instance. This allows for the message execution to be retried in the future, with possibly a higher gas limit by calling `retryMessageExecution`. Importantly, a message is still considered delivered on its destination chain even if its execution fails. This allows the relayer of the message to redeem their reward for deliverying the message, because they have no control on whether or not its execution will succeed or not so long as they provide sufficient gas to meet the specified `requiredGasLimit`.

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.

The Warp protocol does not support re-signing in such a scenario, but Teleporter does. `retrySendCrossChainMessage` 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 might be misunderstanding but isn't this behavior specific to the way that signable Warp messages are being handled right now? I.e. in the future there could be messages that are signable regardless of when the validator joined. The Teleporter comment still stands and I agree that we should mention retrySendCrossChainMessage but I don't think that the statement about Warp protocol as a whole is true in general.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Fair point. We should think of a better way to distinguish Warp messages that are sent at a point in time (with a specific validator set's aggregate signature) versus a Warp message that's constructed on demand (with the current validator set's signature). I've rephrased it to make it clear that we're talking about Warp messages sent on chain.

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