Merge remote-tracking branch 'origin/main' into update-docs

.github/ISSUE_TEMPLATE/feature_spec.md

@@ -1,6 +1,6 @@
 ---
 name: Feature specification
-about: Discussion on design and implementation of new features for teleporter-token-bridge.
+about: Discussion on design and implementation of new features for avalanche-interchain-token-transfer.
 title: ""
 labels: enhancement
 assignees: ""

.github/workflows/abi_bindings_checker.yml

@@ -11,10 +11,10 @@ on:
 jobs:
   abi_binding:
     name: abi_binding
-    runs-on: ubuntu-20.04
+    runs-on: ubuntu-22.04
 
     steps:
-      - name: Checkout teleporter-token-bridge repository
+      - name: Checkout avalanche-interchain-token-transfer repository
         uses: actions/checkout@v4
         with:
           submodules: recursive

.github/workflows/gomod_checker.yml

@@ -11,7 +11,7 @@ on:
 jobs:
   gomod_check:
     name: Check go.mod
-    runs-on: ubuntu-20.04
+    runs-on: ubuntu-22.04
 
     steps:
       - uses: actions/checkout@v4

.github/workflows/linter.yml

@@ -10,7 +10,7 @@ on:
 
 jobs:
   solhint:
-    runs-on: ubuntu-20.04
+    runs-on: ubuntu-22.04
     steps:
       - name: Checkout teleporter
         uses: actions/checkout@v4
@@ -26,7 +26,7 @@ jobs:
         run: ./scripts/lint.sh --sol-lint
 
   format-solidity:
-    runs-on: ubuntu-20.04
+    runs-on: ubuntu-22.04
     timeout-minutes: 10
     steps:
       - name: Checkout repository and submodules

.github/workflows/snyk.yml

@@ -8,7 +8,7 @@ on:
       - "dependabot/**"
 jobs:
   golang-snyk:
-    runs-on: ubuntu-20.04
+    runs-on: ubuntu-22.04
     steps:
       - name: Checkout repositories and submodules
         uses: actions/checkout@v4
@@ -30,7 +30,7 @@ jobs:
         run: |
           sed -i 's/"security-severity": "undefined"/"security-severity": "0"/g' snyk.sarif
 
-      - name: Upload result to GitHub Code Scanning
+      - name: Upload result to Github Code Scanning
         uses: github/codeql-action/upload-sarif@v3
         with:
           sarif_file: snyk.sarif

.github/workflows/test.yml

@@ -10,7 +10,7 @@ on:
 
 jobs:
   solidity-unit-tests:
-    runs-on: ubuntu-20.04
+    runs-on: ubuntu-22.04
     timeout-minutes: 10
     steps:
       - name: Checkout repository and submodules
@@ -28,7 +28,7 @@ jobs:
           forge test -vvv
 
   go-unit-tests:
-    runs-on: ubuntu-20.04
+    runs-on: ubuntu-22.04
 
     steps:
       - name: Checkout repositories and submodules
@@ -53,7 +53,7 @@ jobs:
 
   e2e_tests:
     name: e2e_tests
-    runs-on: ubuntu-20.04
+    runs-on: ubuntu-22.04
     steps:
       - name: Checkout repositories and submodules
         uses: actions/checkout@v4

.golangci.yml

@@ -3,15 +3,14 @@
 run:
   timeout: 3m
   tests: true
-  # skip auto-generated files.
-  skip-dirs:
-    - "abi-bindings/go"
-  skip-files:
-    - ".*mock.*"
 
 issues:
   # Maximum count of issues with the same text. Set to 0 to disable. Default is 3.
   max-same-issues: 0
+  exclude-dirs:
+    - "abi-bindings/go"
+  exclude-files:
+    - ".*mock.*"
 
 linters:
   disable-all: true

README.md

@@ -1,29 +1,27 @@
-# Teleporter Token Bridge
+# Avalanche Interchain Token Transfer (ICTT)
 
-## Status
+## Upgradeability
 
-Please note that `teleporter-token-bridge` is still under active development and should not be used in production. The code is not yet audited and will be subject to active changes.
-
-The token bridges are currently not able to handle upgrades. This means if new versions are deployed, the collateral locked into existing bridges will not be able to be migrated over to the new deployed versions.
+The avalanche-interchain-token-transfer contracts are non-upgradeable and cannot be changed once it is deployed. This provides immutability to the contracts, and ensures that the contract's behavior at each address is unchanging.
 
 ## Overview
 
-Teleporter token bridge is an application that allows users to transfer tokens between Subnets. The bridge is a set of smart contracts that are deployed across multiple Subnets, and leverages [Teleporter](https://github.com/ava-labs/teleporter) for cross-chain communication.
+Avalanche Interchain Token Transfer (ICTT) is an application that allows users to transfer tokens between Subnets. The implementation is a set of smart contracts that are deployed across multiple Subnets, and leverages [Teleporter](https://github.com/ava-labs/teleporter) for cross-chain communication.
 
-Each bridge instance consists of one "hub" contract and at least one but possibly many "spoke" contracts. Each hub contract instance manages one asset to be bridged out to spoke instances. The hub contract lives on the Subnet where the asset to be bridged exists and locks that asset as collateral to be bridged to other Subnets. The spoke contracts, each of which has a single specified hub contract, live on other Subnets that want to import the asset bridged by their specified hub. The token bridges are designed to be permissionless: anyone can register compatible spoke instances to allow for bridging tokens from the hub instance to that new spoke. The hub contract keeps track of token balances bridged to each spoke instance, and it handles returning the original tokens back to the user when assets are bridged back to the hub instance. Spoke instances are registered with their hub contract via a Teleporter message upon creation.
+Each token transferrer instance consists of one "home" contract and at least one but possibly many "remote" contracts. Each home contract instance manages one asset to be transferred out to `TokenRemote` instances. The home contract lives on the Subnet where the asset to be transferred exists. A transfer consists of locking the asset as collateral on the home Subnet and minting a representation of the asset on the remote Subnet. The remote contracts, each of which has a single specified home contract, live on other Subnets that want to import the asset transferred by their specified home. The token transferrers are designed to be permissionless: anyone can register compatible `TokenRemote` instances to allow for transferring tokens from the `TokenHome` instance to that new `TokenRemote` instance. The home contract keeps track of token balances transferred to each `TokenRemote` instance, and handles returning the original tokens back to the user when assets are transferred back to the `TokenHome` instance. `TokenRemote` instances are registered with their home contract via a Teleporter message upon creation.
 
-Hub contract instances specify the asset to be bridged as either an ERC20 token or the Subnet's native token, and they allow for transferring the token to any registered spoke instances. The token representation on the spoke chain can also either be an ERC20 or native token, allowing users to have any combination of ERC20 and native tokens between hub and spoke chains:
+Home contract instances specify the asset to be transferred as either an ERC20 token or the Subnet's native token, and they allow for transferring the token to any registered `TokenRemote` instances. The token representation on the remote chain can also either be an ERC20 or native token, allowing users to have any combination of ERC20 and native tokens between home and remote chains:
 
 - `ERC20` -> `ERC20`
 - `ERC20` -> `Native`
 - `Native` -> `ERC20`
 - `Native` -> `Native`
 
-The spoke tokens are designed to have compatibility with the token bridge on the hub chain by default, and they allow custom logic to be implemented in addition. For example, developers can inherit and extend the `ERC20TokenSpoke` contract to add additional functionality, such as a custom minting, burning, or transfer logic.
+The remote tokens are designed to have compatibility with the token transferrer on the home chain by default, and they allow custom logic to be implemented in addition. For example, developers can inherit and extend the `ERC20TokenRemote` contract to add additional functionality, such as a custom minting, burning, or transfer logic.
 
-The token bridge also supports "multi-hop" transfers, where tokens can be transferred between spoke chains. To illustrate, consider two spokes _S<sub>a</sub>_ and _S<sub>b</sub>_ that are both connected to the same hub _H_. A multi-hop transfer from _S<sub>a</sub>_ to _S<sub>b</sub>_ first gets routed from _S<sub>a</sub>_ to _H_, where spoke balances are updated, and then _H_ automatically routes the transfer on to _S<sub>b</sub>_.
+The token transferrer also supports "multi-hop" transfers, where tokens can be transferred between remote chains. To illustrate, consider two remotes _R<sub>a</sub>_ and _R<sub>b</sub>_ that are both connected to the same home _H_. A multi-hop transfer from _R<sub>a</sub>_ to _R<sub>b</sub>_ first gets routed from _R<sub>a</sub>_ to _H_, where remote balances are updated, and then _H_ automatically routes the transfer on to _R<sub>b</sub>_.
 
-In addition to supporting basic token transfers, the token bridge contracts offer a `sendAndCall` interface for bridging tokens and using them in a smart contract interaction all within a single Teleporter message. If the call to the recipient smart contract fails, the bridged tokens are sent to a fallback recipient address on the destination chain of the transfer. The `sendAndCall` interface enables the direct use of bridged tokens in dApps on other chains, such as performing swaps, using the tokens to pay for fees when invoking services, etc.
+In addition to supporting basic token transfers, the token transferrer contracts offer a `sendAndCall` interface for transferring tokens and using them in a smart contract interaction all within a single Teleporter message. If the call to the recipient smart contract fails, the transferred tokens are sent to a fallback recipient address on the destination chain of the transfer. The `sendAndCall` interface enables the direct use of transferred tokens in dApps on other chains, such as performing swaps, using the tokens to pay for fees when invoking services, etc.
 
 A breakdown of the structure of the contracts that implement this function can be found under `./contracts` [here](./contracts/README.md).
 
@@ -40,7 +38,7 @@ A breakdown of the structure of the contracts that implement this function can b
 
 ## Structure
 
-- `contracts/` is a Foundry project that includes the implementation of the token bridge contracts and Solidity unit tests
+- `contracts/` is a Foundry project that includes the implementation of the token transferrer contracts and Solidity unit tests
 - `scripts/` includes various bash utility scripts
 - `tests/` includes integration tests for the contracts in `contracts/`, written using the [Ginkgo](https://onsi.github.io/ginkgo/) testing framework.
 
@@ -58,27 +56,27 @@ Unit test coverage of the contracts can be viewed using `forge coverage`:
 ```
 $ forge coverage
 [⠢] Compiling...
-[⠔] Compiling 78 files with 0.8.18
-[⠘] Solc 0.8.18 finished in 5.51s
+[⠒] Compiling 78 files with 0.8.18
+[⠆] Solc 0.8.18 finished in 3.92s
 Compiler run successful!
 Analysing contracts...
 Running tests...
 | File                                        | % Lines           | % Statements      | % Branches        | % Funcs         |
 |---------------------------------------------|-------------------|-------------------|-------------------|-----------------|
-| src/TokenHub/ERC20TokenHub.sol              | 100.00% (16/16)   | 100.00% (19/19)   | 100.00% (4/4)     | 100.00% (6/6)   |
-| src/TokenHub/NativeTokenHub.sol             | 100.00% (14/14)   | 100.00% (16/16)   | 100.00% (2/2)     | 100.00% (6/6)   |
-| src/TokenHub/TokenHub.sol                   | 100.00% (135/135) | 100.00% (159/159) | 100.00% (84/84)   | 100.00% (15/15) |
-| src/TokenSpoke/ERC20TokenSpoke.sol          | 100.00% (20/20)   | 100.00% (22/22)   | 100.00% (4/4)     | 100.00% (7/7)   |
-| src/TokenSpoke/NativeTokenSpoke.sol         | 100.00% (39/39)   | 100.00% (48/48)   | 100.00% (8/8)     | 100.00% (12/12) |
-| src/TokenSpoke/TokenSpoke.sol               | 100.00% (81/81)   | 100.00% (102/102) | 100.00% (56/56)   | 100.00% (15/15) |
+| src/TokenHome/ERC20TokenHome.sol              | 100.00% (16/16)   | 100.00% (19/19)   | 100.00% (4/4)     | 100.00% (6/6)   |
+| src/TokenHome/NativeTokenHome.sol             | 100.00% (14/14)   | 100.00% (16/16)   | 100.00% (2/2)     | 100.00% (6/6)   |
+| src/TokenHome/TokenHome.sol                   | 100.00% (135/135) | 100.00% (159/159) | 100.00% (84/84)   | 100.00% (15/15) |
+| src/TokenRemote/ERC20TokenRemote.sol          | 100.00% (27/27)   | 100.00% (31/31)   | 100.00% (8/8)     | 100.00% (8/8)   |
+| src/TokenRemote/NativeTokenRemote.sol         | 100.00% (46/46)   | 100.00% (57/57)   | 100.00% (12/12)   | 100.00% (13/13) |
+| src/TokenRemote/TokenRemote.sol               | 100.00% (76/76)   | 100.00% (94/94)   | 100.00% (52/52)   | 100.00% (14/14) |
 | src/WrappedNativeToken.sol                  | 100.00% (6/6)     | 100.00% (6/6)     | 100.00% (0/0)     | 100.00% (3/3)   |
 | src/mocks/ExampleERC20Decimals.sol          | 100.00% (1/1)     | 100.00% (1/1)     | 100.00% (0/0)     | 100.00% (1/1)   |
 | src/mocks/MockERC20SendAndCallReceiver.sol  | 100.00% (5/5)     | 100.00% (5/5)     | 100.00% (4/4)     | 100.00% (2/2)   |
 | src/mocks/MockNativeSendAndCallReceiver.sol | 100.00% (4/4)     | 100.00% (4/4)     | 100.00% (4/4)     | 100.00% (2/2)   |
 | src/utils/CallUtils.sol                     | 100.00% (8/8)     | 100.00% (9/9)     | 100.00% (6/6)     | 100.00% (2/2)   |
 | src/utils/SafeWrappedNativeTokenDeposit.sol | 100.00% (5/5)     | 100.00% (8/8)     | 100.00% (2/2)     | 100.00% (1/1)   |
 | src/utils/TokenScalingUtils.sol             | 100.00% (8/8)     | 100.00% (14/14)   | 100.00% (2/2)     | 100.00% (4/4)   |
-| Total                                       | 100.00% (342/342) | 100.00% (413/413) | 100.00% (176/176) | 100.00% (76/76) |
+| Total                                       | 100.00% (351/351) | 100.00% (423/423) | 100.00% (180/180) | 100.00% (77/77) |
 ```
 
 ## E2E tests
@@ -95,28 +93,28 @@ Then run the following command from the root of the repository:
 
 ### Run specific E2E tests
 
-To run a specific E2E test, specify the environment variable `GINKGO_FOCUS`, which will then look for test descriptions that match the provided input. For example, to run the `Bridge an ERC20 token between two Subnets` test:
+To run a specific E2E test, specify the environment variable `GINKGO_FOCUS`, which will then look for test descriptions that match the provided input. For example, to run the `Transfer an ERC20 token between two Subnets` test:
 
 ```bash
-GINKGO_FOCUS="Bridge an ERC20 token between two Subnets" ./scripts/e2e_test.sh
+GINKGO_FOCUS="Transfer an ERC20 token between two Subnets" ./scripts/e2e_test.sh
 ```
 
 A substring of the full test description can be used as well:
 
 ```bash
-GINKGO_FOCUS="Bridge an ERC20 token" ./scripts/e2e_test.sh
+GINKGO_FOCUS="Transfer an ERC20 token" ./scripts/e2e_test.sh
 ```
 
-The E2E tests also supports `GINKGO_LABEL_FILTER`, making it easy to group test cases and run them together. For example, to run all `ERC20TokenHub` E2E tests:
+The E2E tests also supports `GINKGO_LABEL_FILTER`, making it easy to group test cases and run them together. For example, to run all `ERC20TokenHome` E2E tests:
 
 ```go
-	ginkgo.It("Bridge an ERC20 token between two Subnets",
-		ginkgo.Label(erc20TokenHubLabel, erc20TokenSpokeLabel),
+	ginkgo.It("Transfer an ERC20 token between two Subnets",
+		ginkgo.Label(erc20TokenHomeLabel, erc20TokenRemoteLabel),
 		func() {
-			flows.ERC20TokenHubERC20TokenSpoke(LocalNetworkInstance)
+			flows.ERC20TokenHomeERC20TokenRemote(LocalNetworkInstance)
 		})
 ```
 
 ```bash
-GINKGO_LABEL_FILTER="ERC20TokenHub" ./scripts/e2e_test.sh
+GINKGO_LABEL_FILTER="ERC20TokenHome" ./scripts/e2e_test.sh
 ```

SECURITY.md

@@ -15,3 +15,7 @@ Please refer to the [Bug Bounty Page](https://hackenproof.com/avalanche) for the
 ## Supported Versions
 
 Please use the most recently released version to perform testing and to validate security issues.
+
+## Audit Reports
+
+All complete audit reports for `avalanche-interchain-token-transfer` can be found in the [audits](./audits/) directory.