External interop design docs #1136

batconjurer · 2025-12-12T13:58:38Z

Why this should be merged

A rough draft of the design docs for external interop. Currently only covers the avalanche-> external direction.

How this works

How this was tested

How is this documented

geoff-vball

I still have one file left to go, but leaving this feedback now

lib/forge-std

docs/external-interop/origin_avalanche/summary.md

docs/external-interop/origin_avalanche/validator_set_registry.md

mdelle1 · 2025-12-15T22:04:13Z

docs/external-interop/origin_avalanche/relayer_changes.md

+`AvalancheValidatorSetRegistry` contracts, new validator sets will need to be relayed periodically.
+
+## Updating Validator sets
+


I think this paragraph is technically dense and can be expanded a bit for clarity to readers. It seems like here there are 2 main pieces which should be explicitly broken up either in list or paragraph format:

The ValidatorSetUpdater component which is responsible for data synchronization, i.e., continuously monitoring the P-chain and updating AvalancheValidatorSetRegistry contracts. I think it would help to explain the trust assumptions for the updater. You can say that it must provide a valid proof, e.g. in the form of an aggregate BLS signature, for updating the validator set.

The Relayer. I don't think this paragraph should start with "Before signing messages,..." rather it should explicitly say what the relayer does. For example:

"The Relayer is responsible for delivering an ICM message from an Avalanche L1 to an external EVM chain (specified in the message). The Relayer first queries the destination registry contract on the external chain to determine the P-chain height that was last registered for the source Avalanche L1. This ensures the relayer signs the message using the correct, currently active set of validators for that L1. Once this occurs, the Relayer collects the signatures from the relevant validators..."

Yeah, tbh I just repurposed Linguan's design doc and put it in here as a placeholder since this should be part of the design doc. I can try to clean it up, but at some point someone with more context should flesh it out.

Yeah I'm also happy to flesh it out myself. Should I make a PR into this branch or just push commits directly to this PR?

I would like to see this merged and then this can be addressed with PRs to main

mdelle1 · 2025-12-16T14:58:23Z

docs/external-interop/origin_avalanche/relayer_changes.md

+External EVM chains need to verify ICM messages from Avalanche L1s by checking validator signatures.
+
+
+The `ValidatorSetUpdater` component polls P-chain at configurable intervals. On each iteration it performs the following:


I think for symmetry this step-by-step should also be present for the Relayer

Hopefully some enterprising individual will flesh that out.

mdelle1 · 2025-12-16T15:07:17Z

docs/external-interop/origin_avalanche/summary.md

+Communication between Avalanche L1 (the so-called _"internal interoperability"_) uses the [ICM protocol](../../../icm-contracts/contracts/teleporter/README.md) 
+which is handled by a set of `Teleporter` contracts. Further protocols can be built on top of `Teleporter`, but this is 
+out of scope for this design doc. The goal external interoperability is to support `Teleporter` contracts on external EVM 
+chains to leverage existing protocols. This will require changes to the `TeleporterMessenger` contracts which will be 


I was under the impression that these would be a new class of TeleporterMessenger contracts?

Well, it could be. I had initially tried to go with slight modifications of existing contracts that would have full backwards compatibility (or as close to full as possible). I have come to realize in the past 36 hours that there isn't alignment on this at all. So we need to make some sort of decision on this and I could update the docs accordingly.

docs/external-interop/origin_avalanche/summary.md

Co-authored-by: Geoff Stuart <[email protected]> Signed-off-by: Jacob Turner <[email protected]>

Co-authored-by: mdelle1 <[email protected]> Signed-off-by: Jacob Turner <[email protected]>

docs/external-interop/origin_avalanche/summary.md

Co-authored-by: Michael Kaplan <[email protected]> Signed-off-by: Jacob Turner <[email protected]>

geoff-vball · 2026-01-07T19:30:36Z

docs/external-interop/icm_message_authentication.md

@@ -0,0 +1,28 @@
+# Authenticating ICM Messages
+
+Authenticating ICM messages will be handled by contracts implementing the `IMessageVerifier` interface, as described in the [Teleporter architecture](teleporter_contracts.md). The `Teleporter` protocol is complelely agnostic to the details of how messages are authenticated. It is up to applications to decide how to authenticate messages.


I think this paragraph should be changed to reflect the two different proposals. In the first proposal, in a sense it's not up to applications how to authenticate messages (though it is, based on which TeleporterMessenger instance they use). In either case the TeleporterMessenger contract is agnostic to the details of how messages are authenticated, but in one it is tied to a specific authentication scheme, and in the other it is not.

geoff-vball · 2026-01-08T15:43:20Z

docs/external-interop/icm_message_authentication.md

+
+When a TeleporterV2 contract receives a message, it checks if it originated from the same contract address as its own. If so, it knows that it is part of the same scheme and can verify the message using the hard-coded `IMessageVerifier` implementation.
+
+Note that an `IMesssageVerifier` implementation for a particular scheme may need to perform different logic depending on which chain it lives. So a switch statement should be included in its logic to dispatch to the right method depending on which chain it is being called. While many of the code paths will be dead on each chain, it means that the same code is deployed on-chain for a particular scheme. The same is true of `IMessageSender` implementations.


I don't think you need to change anything here - just wanted to sketch this out. The switch statement could honestly be in the constructor of a function, leaving the execution path be the same code, but calling different contracts ex: (pseudocode)

IMessageSender[] public immutable messageSenders constructor() { if isEth { messageSenders = <hard-coded list> } else { messageSenders = <other hard-coded list> } } sendMessage(TeleporterMessage calldata message) { for messageSender in messageSenders { messageSender.sendMessage(message); } }

geoff-vball · 2026-01-08T15:54:14Z

docs/external-interop/teleporter_contracts.md

@@ -0,0 +1,134 @@
+Teleporter is a protocol of interoperability messaging primitives that provides at most one delivery of authenticated ICM messages.  For interoperability between Avalanche L1s and a description of the actual protocol, see [here](../../icm-contracts/contracts/teleporter/README.md). We wish to extend this protocol to external EVM chains, but we cannot use the current contract (`ITeleporterMessenger`). Here we describe the new contracts we will need and the overall architecture.


This file seems like duplication of docs/external-interop/icm_message_authentication.md? We should try to maintain a single source of truth, and just linking other docs where appropriate.

batconjurer requested a review from a team as a code owner December 12, 2025 13:58

batconjurer requested review from geoff-vball, iansuvak, mdelle1, michaelkaplan13 and ylg-avalabs December 12, 2025 13:58

batconjurer force-pushed the bat/doc/external-interop branch from e1cced2 to d47960c Compare December 12, 2025 14:00

geoff-vball reviewed Dec 12, 2025

View reviewed changes

batconjurer force-pushed the bat/doc/external-interop branch 4 times, most recently from ac0f4d2 to 3a10beb Compare December 15, 2025 15:27

mdelle1 reviewed Dec 15, 2025

View reviewed changes

mdelle1 reviewed Dec 16, 2025

View reviewed changes

docs/external-interop/origin_avalanche/summary.md Outdated Show resolved Hide resolved

mdelle1 reviewed Dec 16, 2025

View reviewed changes

docs/external-interop/origin_avalanche/summary.md Outdated Show resolved Hide resolved

mdelle1 reviewed Dec 16, 2025

View reviewed changes

docs/external-interop/origin_avalanche/summary.md Outdated Show resolved Hide resolved

mdelle1 reviewed Dec 16, 2025

View reviewed changes

docs/external-interop/origin_avalanche/summary.md Outdated Show resolved Hide resolved

mdelle1 reviewed Dec 16, 2025

View reviewed changes

docs/external-interop/origin_avalanche/summary.md Outdated Show resolved Hide resolved

mdelle1 reviewed Dec 16, 2025

View reviewed changes

docs/external-interop/origin_avalanche/summary.md Outdated Show resolved Hide resolved

batconjurer and others added 3 commits December 17, 2025 12:03

Adding a rought draft of the external-interop design docs

dabf60a

Update docs/external-interop/origin_avalanche/summary.md

b9c7a7f

Co-authored-by: Geoff Stuart <[email protected]> Signed-off-by: Jacob Turner <[email protected]>

Apply suggestions from code review

2f01e02

Co-authored-by: Geoff Stuart <[email protected]> Signed-off-by: Jacob Turner <[email protected]>

batconjurer force-pushed the bat/doc/external-interop branch from b627712 to 2f01e02 Compare December 17, 2025 11:03

batconjurer and others added 3 commits December 17, 2025 12:21

Apply suggestions from code review

39a01ad

Co-authored-by: mdelle1 <[email protected]> Signed-off-by: Jacob Turner <[email protected]>

fixup! Update abi bindings

4fec986

Adding details for configurable authentication mechanisms

9888bc2

michaelkaplan13 reviewed Dec 18, 2025

View reviewed changes

docs/external-interop/origin_avalanche/summary.md Outdated Show resolved Hide resolved

michaelkaplan13 reviewed Dec 18, 2025

View reviewed changes

docs/external-interop/origin_avalanche/summary.md Outdated Show resolved Hide resolved

michaelkaplan13 reviewed Dec 18, 2025

View reviewed changes

docs/external-interop/origin_avalanche/summary.md Outdated Show resolved Hide resolved

michaelkaplan13 reviewed Dec 18, 2025

View reviewed changes

docs/external-interop/origin_avalanche/summary.md Outdated Show resolved Hide resolved

batconjurer and others added 3 commits December 19, 2025 10:45

Update docs/external-interop/origin_avalanche/summary.md

dffe2fd

Co-authored-by: Michael Kaplan <[email protected]> Signed-off-by: Jacob Turner <[email protected]>

Addressing review comments

5425b3a

Updating docs from notion discussions

7adb790

batconjurer requested review from geoff-vball, mdelle1 and michaelkaplan13 January 7, 2026 15:29

geoff-vball reviewed Jan 8, 2026

View reviewed changes

		`AvalancheValidatorSetRegistry` contracts, new validator sets will need to be relayed periodically.

		## Updating Validator sets

		External EVM chains need to verify ICM messages from Avalanche L1s by checking validator signatures.


		The `ValidatorSetUpdater` component polls P-chain at configurable intervals. On each iteration it performs the following:

		@@ -0,0 +1,28 @@
		# Authenticating ICM Messages

		Authenticating ICM messages will be handled by contracts implementing the `IMessageVerifier` interface, as described in the [Teleporter architecture](teleporter_contracts.md). The `Teleporter` protocol is complelely agnostic to the details of how messages are authenticated. It is up to applications to decide how to authenticate messages.


		When a TeleporterV2 contract receives a message, it checks if it originated from the same contract address as its own. If so, it knows that it is part of the same scheme and can verify the message using the hard-coded `IMessageVerifier` implementation.

		Note that an `IMesssageVerifier` implementation for a particular scheme may need to perform different logic depending on which chain it lives. So a switch statement should be included in its logic to dispatch to the right method depending on which chain it is being called. While many of the code paths will be dead on each chain, it means that the same code is deployed on-chain for a particular scheme. The same is true of `IMessageSender` implementations.

		@@ -0,0 +1,134 @@
		Teleporter is a protocol of interoperability messaging primitives that provides at most one delivery of authenticated ICM messages. For interoperability between Avalanche L1s and a description of the actual protocol, see [here](../../icm-contracts/contracts/teleporter/README.md). We wish to extend this protocol to external EVM chains, but we cannot use the current contract (`ITeleporterMessenger`). Here we describe the new contracts we will need and the overall architecture.

External interop design docs #1136

Are you sure you want to change the base?

External interop design docs #1136

Conversation

batconjurer commented Dec 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Why this should be merged

How this works

How this was tested

How is this documented

Uh oh!

geoff-vball left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

batconjurer commented Dec 12, 2025 •

edited

Loading