From c58d1e551082c7d187a30a008853a42b78fdae36 Mon Sep 17 00:00:00 2001 From: Canh Trinh Date: Thu, 19 Sep 2024 11:27:02 -0400 Subject: [PATCH 1/6] chore: adding skeleton for integration.md file --- doc/INTEGRATION.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) create mode 100644 doc/INTEGRATION.md diff --git a/doc/INTEGRATION.md b/doc/INTEGRATION.md new file mode 100644 index 000000000..84678703d --- /dev/null +++ b/doc/INTEGRATION.md @@ -0,0 +1,16 @@ +## UNDER CONSTRUCTION + +To cover: +* contract components: + 1. infra contracts + - router, service registry, multisig, coordinator, etc + - should not be touched unless needed + - specific use cases where PRs to these contracts may be needed in coordination with Interop Labs team (e.g. address validation, new msg ID types, new signature schemes, etc) + 2. chain-specific contracts + - voting verifier, gateway, multisig prover + - mention that the ones we have in this repo are there for reference and can be used (as integrator's own peril, appreciating they're for reference only) + 3. ampd + - for any custom chain, need to do a PR to this repo + - suggestion that plugin is forthcoming +* step-by-step instructions: + - we can move a lot of what is already in the public docs, here: https://docs.axelar.dev/dev/amplifier/chain-integration/introduction/#integration-process \ No newline at end of file From 640caa937447fd3448fb087c2a0f247adb2a1250 Mon Sep 17 00:00:00 2001 From: Canh Trinh Date: Mon, 30 Sep 2024 22:38:37 -0400 Subject: [PATCH 2/6] feat: refactored version of integration doc --- doc/INTEGRATION.md | 105 ++++++++++++++++++++++++++++++++++++++------- 1 file changed, 89 insertions(+), 16 deletions(-) diff --git a/doc/INTEGRATION.md b/doc/INTEGRATION.md index 84678703d..1cbc741e0 100644 --- a/doc/INTEGRATION.md +++ b/doc/INTEGRATION.md @@ -1,16 +1,89 @@ -## UNDER CONSTRUCTION - -To cover: -* contract components: - 1. infra contracts - - router, service registry, multisig, coordinator, etc - - should not be touched unless needed - - specific use cases where PRs to these contracts may be needed in coordination with Interop Labs team (e.g. address validation, new msg ID types, new signature schemes, etc) - 2. chain-specific contracts - - voting verifier, gateway, multisig prover - - mention that the ones we have in this repo are there for reference and can be used (as integrator's own peril, appreciating they're for reference only) - 3. ampd - - for any custom chain, need to do a PR to this repo - - suggestion that plugin is forthcoming -* step-by-step instructions: - - we can move a lot of what is already in the public docs, here: https://docs.axelar.dev/dev/amplifier/chain-integration/introduction/#integration-process \ No newline at end of file +# Axelar Amplifier Integration Guide + +This document provides an overview of the contracts on Axelar Amplifier protocol and outlines the steps required to integrate a chain. The document only covers the Amplifier contracts; a comprehensive list on other required components for the integration of a chain into Amplifier can be found in the [Axelar Amplifier Public Docs](https://docs.axelar.dev/dev/amplifier/chain-integration/introduction/). + +--- + +## Amplifier Contracts Overview + +To connect your chain to the Axelar network via the Interchain Amplifier, you will need to deploy or configure the following three contracts on Amplifier, and the configuration of `ampd`, as outlined below: + +### Chain-Specific Amplifier Contracts + +**Gateway** + +A contract on Amplifier that will forward incoming messages to the chain's correspoding verifier contract to check the validity of a transaction and forwards verified transactions onto the Amplifier router. It also receives messages from other chains to be processed by the multisig prover. +Most integrators will begin by using or customizing this Gateway Contract. +[Gateway Documentation](../doc/src/contracts/gateway.md) + +**Voting Verifier** + +A contract on Amplifier protocol that verifies the validity of transactions on your chain. Most integrators will begin by using or customizing a Voting Verifier or can be customized to your needs for cases such as verification via ZK Proof. + +A Voting Verifier must be supported by a Verifier Set will need to support the chain and vote on the truth of source chain transactions. + +[Voting Verifier Documentation](../doc/src/contracts/voting_verifier.md) + +**Multisig Prover** + +The prover contract is responsible for transforming gateway messages into a payload that is ready to be sent to the destination gateway. + +[Multisig Prover Documentation](../doc/src/contracts/multisig_prover.md) + + +### ampd + +Ampd is the off chain daemon responsible for voting and signing within the amplifier protocol. The daemon listens to the Axelar blockchain for specific events, connects to external blockchains via JSON-RPC, and uses [tofnd](https://github.com/axelarnetwork/tofnd) for signing transactions and batches of messages + + +### Infrastructure Contracts + +These core contracts manage essential infrastructure logic for the protocol and typically do not require modification. If your chain does require the modificaiton of any of these contracts, please let us know by filing a Github issue to this repository to create a pull request to be merged. + +**Coordinator** + +Manages coordination between contracts in the Amplifier system. [Coordinator Documentation](../doc/src/contracts/coordinator.md) + +**Multisig** + +Facilitates verifier signing sessions that is leveraged by the multisig prover contract. The Multisig contract currently supports ECDSA and ED25519 signature schemes. [Multisig Documentation](../doc/src/contracts/multisig.md) + +**Rewards** + +Manages verifier rewards. [Rewards Documentation](../doc/src/contracts/rewards.md) + +**Router** + +Routes messages between gateway contracts connected in the Amplifier ecosystem, and responsible for performing various administrative functions for chain. [Router Documentation](../doc/src/contracts/router.md) + +**Service Registry** + +Registers and tracks the pool of verifiers that support each and every Amplifier chain. [Service Registry Documentation](../doc/src/contracts/service_registry.md) + +## Integration Steps + +### 1. Deploy and instantiate the chain-specific contracts + +The very first step is to deploy and instantiate the chain-specific contracts. This repository has reference contracts for each: [**Gateway**](../contracts/gateway), [**Voting Verifier**](../contracts/voting-verifier), and [**Multisig Prover**](../contracts/multisig-prover), and these reference contracts have been used in many of the initial chains live on Amplifier today. + +However, it is up to the integrator to determine how to best utilize the reference contracts, whether that may be by using the reference contracts we expose as is, maintaining a fork, or something else. It is important to note that these reference contracts are under active development and may change at any time, so integrators should be aware of the specific implementation and version of any reference contracts should they decide to use them. + +### 2. Configure `ampd` + +If your chain is **not EVM-compatible**, you will need to implement an **ampd** module that Amplifier can use to communicate with your chain. Using the [ampd EVM module](../ampd/src/evm) as a design template, you will have to fork this repository and create a pull request to merge into the main repository. + +If your chain is **EVM-compatible**, you can use the existing **ampd** module for EVM chains: [ampd EVM module](../ampd/src/evm), and there is nothing to do from your side. + +### 3. Configure a verifier set + +If your verifier contract is a voting verifier, the chain must be supported by a verifier set. Testnet/mainnet has a global set of ~30 verifiers that will need to support your chain. + +To facilitate verifier onboarding to support your chain, please follow the guide laid out in [this page - link TBD](). + +### 4. Fund rewards pools + +Create rewards pools for your verifier and multisig prover contracts. These rewards pools incentivize verifiers to support your chain. Instructions on how to create and fund rewards pools can be found [here](https://docs.axelar.dev/dev/amplifier/add-rewards). + +## Testing + +## Deployment From 52c915d2621171ad808a85346d1747e458b00962 Mon Sep 17 00:00:00 2001 From: Canh Trinh Date: Thu, 3 Oct 2024 19:57:19 -0400 Subject: [PATCH 3/6] Update doc/INTEGRATION.md Co-authored-by: CJ Cobb <46455409+cjcobb23@users.noreply.github.com> --- doc/INTEGRATION.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/INTEGRATION.md b/doc/INTEGRATION.md index 1cbc741e0..d0bb2461e 100644 --- a/doc/INTEGRATION.md +++ b/doc/INTEGRATION.md @@ -46,7 +46,7 @@ Manages coordination between contracts in the Amplifier system. [Coordinator Doc **Multisig** -Facilitates verifier signing sessions that is leveraged by the multisig prover contract. The Multisig contract currently supports ECDSA and ED25519 signature schemes. [Multisig Documentation](../doc/src/contracts/multisig.md) +Facilitates verifier signing sessions which is leveraged by the multisig prover contract. The Multisig contract currently supports ECDSA and ED25519 signature schemes. [Multisig Documentation](../doc/src/contracts/multisig.md) **Rewards** From 61f7be92541eb57bf826be20e63dc77bc14ba37f Mon Sep 17 00:00:00 2001 From: Canh Trinh Date: Thu, 3 Oct 2024 19:57:39 -0400 Subject: [PATCH 4/6] Update doc/INTEGRATION.md Co-authored-by: CJ Cobb <46455409+cjcobb23@users.noreply.github.com> --- doc/INTEGRATION.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/INTEGRATION.md b/doc/INTEGRATION.md index d0bb2461e..d631d5f9a 100644 --- a/doc/INTEGRATION.md +++ b/doc/INTEGRATION.md @@ -50,7 +50,7 @@ Facilitates verifier signing sessions which is leveraged by the multisig prover **Rewards** -Manages verifier rewards. [Rewards Documentation](../doc/src/contracts/rewards.md) +Keeps track of verifier participation in various on chain events and distributes rewards accordingly. [Rewards Documentation](../doc/src/contracts/rewards.md) **Router** From fdac83529e16a23dcc3371f5bdda32f7fc4d29c7 Mon Sep 17 00:00:00 2001 From: Canh Trinh Date: Thu, 3 Oct 2024 23:19:21 -0400 Subject: [PATCH 5/6] feat: addressing latest PR comments --- doc/INTEGRATION.md | 49 ++++++++++++++++++---------------------------- 1 file changed, 19 insertions(+), 30 deletions(-) diff --git a/doc/INTEGRATION.md b/doc/INTEGRATION.md index d631d5f9a..e8ab2cc84 100644 --- a/doc/INTEGRATION.md +++ b/doc/INTEGRATION.md @@ -16,15 +16,15 @@ A contract on Amplifier that will forward incoming messages to the chain's corre Most integrators will begin by using or customizing this Gateway Contract. [Gateway Documentation](../doc/src/contracts/gateway.md) -**Voting Verifier** +**Verifier** A contract on Amplifier protocol that verifies the validity of transactions on your chain. Most integrators will begin by using or customizing a Voting Verifier or can be customized to your needs for cases such as verification via ZK Proof. -A Voting Verifier must be supported by a Verifier Set will need to support the chain and vote on the truth of source chain transactions. +A Voting Verifier must be supported by a Verifier Set that will need to support the chain and vote on the truth of source chain transactions. [Voting Verifier Documentation](../doc/src/contracts/voting_verifier.md) -**Multisig Prover** +**Prover** The prover contract is responsible for transforming gateway messages into a payload that is ready to be sent to the destination gateway. @@ -33,32 +33,21 @@ The prover contract is responsible for transforming gateway messages into a payl ### ampd -Ampd is the off chain daemon responsible for voting and signing within the amplifier protocol. The daemon listens to the Axelar blockchain for specific events, connects to external blockchains via JSON-RPC, and uses [tofnd](https://github.com/axelarnetwork/tofnd) for signing transactions and batches of messages +Ampd is the off chain daemon that listens to the Axelar blockchain for specific events, connects to external blockchains via JSON-RPC, and uses [tofnd](https://github.com/axelarnetwork/tofnd) for signing transactions and batches of messages ### Infrastructure Contracts -These core contracts manage essential infrastructure logic for the protocol and typically do not require modification. If your chain does require the modificaiton of any of these contracts, please let us know by filing a Github issue to this repository to create a pull request to be merged. +These core contracts manage essential infrastructure logic for the protocol and typically do not require modification. If your chain does require the modificaiton of any of these contracts, please either file a Github issue or create a pull request with the requested changes to accommodate your chain. -**Coordinator** +There is only one instance of each of these contracts in the protocol; any changes to these contracts must go through an upgrade of the contracts that via Axelar governance. -Manages coordination between contracts in the Amplifier system. [Coordinator Documentation](../doc/src/contracts/coordinator.md) - -**Multisig** - -Facilitates verifier signing sessions which is leveraged by the multisig prover contract. The Multisig contract currently supports ECDSA and ED25519 signature schemes. [Multisig Documentation](../doc/src/contracts/multisig.md) - -**Rewards** - -Keeps track of verifier participation in various on chain events and distributes rewards accordingly. [Rewards Documentation](../doc/src/contracts/rewards.md) - -**Router** - -Routes messages between gateway contracts connected in the Amplifier ecosystem, and responsible for performing various administrative functions for chain. [Router Documentation](../doc/src/contracts/router.md) - -**Service Registry** - -Registers and tracks the pool of verifiers that support each and every Amplifier chain. [Service Registry Documentation](../doc/src/contracts/service_registry.md) +A description of each infrastructure contract can be found as follows: +* [Coordinator](../doc/src/contracts/coordinator.md) +* [Multisig](../doc/src/contracts/multisig.md) +* [Rewards](../doc/src/contracts/rewards.md) +* [Router](../doc/src/contracts/router.md) +* [Service Registry](../doc/src/contracts/service_registry.md) ## Integration Steps @@ -70,20 +59,20 @@ However, it is up to the integrator to determine how to best utilize the referen ### 2. Configure `ampd` -If your chain is **not EVM-compatible**, you will need to implement an **ampd** module that Amplifier can use to communicate with your chain. Using the [ampd EVM module](../ampd/src/evm) as a design template, you will have to fork this repository and create a pull request to merge into the main repository. +If your chain is **not EVM-compatible**, you will need to implement an **ampd** module that Amplifier can use to communicate with your chain. Using the [ampd EVM module](../ampd/src/evm) as a design template. + +NOTE: any modifications you make to `ampd` to support your chain will need to be upstreamed and merged back into the main repository. If your chain is **EVM-compatible**, you can use the existing **ampd** module for EVM chains: [ampd EVM module](../ampd/src/evm), and there is nothing to do from your side. ### 3. Configure a verifier set -If your verifier contract is a voting verifier, the chain must be supported by a verifier set. Testnet/mainnet has a global set of ~30 verifiers that will need to support your chain. - -To facilitate verifier onboarding to support your chain, please follow the guide laid out in [this page - link TBD](). +The chain must be supported by a verifier set. Testnet and mainnet will have an initial set of ~30 verifiers globally that can support your chain. ### 4. Fund rewards pools -Create rewards pools for your verifier and multisig prover contracts. These rewards pools incentivize verifiers to support your chain. Instructions on how to create and fund rewards pools can be found [here](https://docs.axelar.dev/dev/amplifier/add-rewards). +Create rewards pools for your verifier and multisig prover contracts. These rewards pools incentivize verifiers to support your chain. Please refer to the [rewards contract](../contracts/rewards/src/) for more info. -## Testing +## Testing and Deployment -## Deployment +Once your contracts are deployed, you can test them, along with the external smart contracts deployed to your chain, on the public devnet. Please refer to the public [developer documentation](https://docs.axelar.dev/dev/amplifier/chain-integration/integrate-a-chain/) for the latest information on the public devnet and example deployment scripts to get you started. \ No newline at end of file From 11ad71142083475b7da4012fbd6b8940d0afd93b Mon Sep 17 00:00:00 2001 From: Canh Trinh Date: Thu, 3 Oct 2024 23:26:38 -0400 Subject: [PATCH 6/6] chore: minor formatting on integration docs --- doc/INTEGRATION.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/doc/INTEGRATION.md b/doc/INTEGRATION.md index e8ab2cc84..161fb871b 100644 --- a/doc/INTEGRATION.md +++ b/doc/INTEGRATION.md @@ -13,12 +13,13 @@ To connect your chain to the Axelar network via the Interchain Amplifier, you wi **Gateway** A contract on Amplifier that will forward incoming messages to the chain's correspoding verifier contract to check the validity of a transaction and forwards verified transactions onto the Amplifier router. It also receives messages from other chains to be processed by the multisig prover. -Most integrators will begin by using or customizing this Gateway Contract. +Most integrators will begin by using or customizing [this](../contracts/gateway/) Gateway Contract. + [Gateway Documentation](../doc/src/contracts/gateway.md) **Verifier** -A contract on Amplifier protocol that verifies the validity of transactions on your chain. Most integrators will begin by using or customizing a Voting Verifier or can be customized to your needs for cases such as verification via ZK Proof. +A contract on Amplifier protocol that verifies the validity of transactions on your chain. Most integrators will begin by using or customizing a Voting Verifier (such as [this](../contracts/voting-verifier/) one) or can be customized to your needs for cases such as verification via ZK Proof. A Voting Verifier must be supported by a Verifier Set that will need to support the chain and vote on the truth of source chain transactions. @@ -26,7 +27,7 @@ A Voting Verifier must be supported by a Verifier Set that will need to support **Prover** -The prover contract is responsible for transforming gateway messages into a payload that is ready to be sent to the destination gateway. +The prover contract is responsible for transforming gateway messages into a payload that is ready to be sent to the destination gateway. Most integrators will begin by using or customizing a multisig prover, such as [this](../contracts/multisig-prover/) one. [Multisig Prover Documentation](../doc/src/contracts/multisig_prover.md)