Skip to content

Commit f2c446d

Browse files
RensRRensR
committed
Merge branch 'main' into merge-main-into-develop
2 parents 64dd61a + f588f8d commit f2c446d

File tree

76 files changed

+9550
-466
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

76 files changed

+9550
-466
lines changed

‎chains/evm/deployment/docs/_category_.yaml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
label: "EVM Implementation"
2+
position: 2

‎chains/evm/deployment/docs/adapter.md‎

Lines changed: 182 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,182 @@
1+
---
2+
title: "EVMAdapter Reference"
3+
sidebar_label: "Adapter"
4+
sidebar_position: 2
5+
---
6+
7+
# EVMAdapter Reference
8+
9+
The `EVMAdapter` is a stateless struct that implements all required shared interfaces for the EVM chain family.
10+
11+
**Source:** [v1_6_0/sequences/adapter.go](../v1_6_0/sequences/adapter.go)
12+
13+
For the interfaces it implements, see [Interfaces Reference](../../../../deployment/docs/interfaces.md).
14+
15+
---
16+
17+
## Struct Definition
18+
19+
```go
20+
type EVMAdapter struct{}
21+
```
22+
23+
The EVM adapter is intentionally stateless -- all state is resolved from the DataStore and environment at execution time.
24+
25+
---
26+
27+
## Registration
28+
29+
### Main Adapter (`sequences/adapter.go`)
30+
31+
**Source:** [v1_6_0/sequences/adapter.go](../v1_6_0/sequences/adapter.go)
32+
33+
```go
34+
func init() {
35+
v, _ := semver.NewVersion("1.6.0")
36+
37+
laneapi.GetLaneAdapterRegistry().RegisterLaneAdapter(chain_selectors.FamilyEVM, v, &EVMAdapter{})
38+
deployapi.GetRegistry().RegisterDeployer(chain_selectors.FamilyEVM, v, &EVMAdapter{})
39+
deployapi.GetTransferOwnershipRegistry().RegisterAdapter(chain_selectors.FamilyEVM, v, &EVMAdapter{})
40+
mcmsreaderapi.GetRegistry().RegisterMCMSReader(chain_selectors.FamilyEVM, &EVMAdapter{})
41+
tokensapi.GetTokenAdapterRegistry().RegisterTokenAdapter(chain_selectors.FamilyEVM, v, &EVMAdapter{})
42+
lanes.GetPingPongAdapterRegistry().RegisterPingPongAdapter(chain_selectors.FamilyEVM, v, &EVMAdapter{})
43+
}
44+
```
45+
46+
### Separate Adapters (`adapters/init.go`)
47+
48+
**Source:** [v1_6_0/adapters/init.go](../v1_6_0/adapters/init.go)
49+
50+
```go
51+
func init() {
52+
// Curse adapter
53+
fastcurse.GetCurseRegistry().RegisterNewCurse(fastcurse.CurseRegistryInput{
54+
CursingFamily: chain_selectors.FamilyEVM,
55+
CursingVersion: semver.MustParse("1.6.0"),
56+
CurseAdapter: NewCurseAdapter(),
57+
CurseSubjectAdapter: NewCurseAdapter(),
58+
})
59+
60+
// Lane migration adapters
61+
deploy.GetLaneMigratorRegistry().RegisterRampUpdater(chain_selectors.FamilyEVM, semver.MustParse("1.6.0"), &LaneMigrater{})
62+
deploy.GetLaneMigratorRegistry().RegisterRouterUpdater(chain_selectors.FamilyEVM, semver.MustParse("1.2.0"), &RouterUpdater{})
63+
}
64+
```
65+
66+
---
67+
68+
## Interface Implementations
69+
70+
### Deployer
71+
72+
| Method | Delegates To |
73+
|--------|-------------|
74+
| `DeployChainContracts()` | `DeployChainContracts` sequence |
75+
| `DeployMCMS()` | v1.0.0 MCMS deployer |
76+
| `FinalizeDeployMCMS()` | v1.0.0 MCMS finalize (no-op for EVM) |
77+
| `SetOCR3Config()` | OCR3 configuration sequence |
78+
| `GrantAdminRoleToTimelock()` | Timelock admin role sequence |
79+
80+
EVM delegates MCMS deployment to the v1.0.0 implementation since MCMS contracts are version-agnostic on EVM.
81+
82+
### LaneAdapter
83+
84+
| Method | Behavior |
85+
|--------|----------|
86+
| `GetOnRampAddress()` | Looks up OnRamp v1.6.0 from DataStore |
87+
| `GetOffRampAddress()` | Looks up OffRamp v1.6.0 from DataStore |
88+
| `GetRouterAddress()` | Looks up Router from DataStore |
89+
| `GetFQAddress()` | Looks up latest FeeQuoter (v1.6.0 -- v1.7.0 range) |
90+
| `ConfigureLaneLegAsSource()` | OnRamp dest config + FeeQuoter dest config + price updates |
91+
| `ConfigureLaneLegAsDest()` | OffRamp source config + Router ramp updates |
92+
93+
All `Get*Address` methods return 20-byte EVM addresses.
94+
95+
### TokenAdapter
96+
97+
| Method | Behavior |
98+
|--------|----------|
99+
| `AddressRefToBytes()` | Hex-decodes the address string to bytes |
100+
| `DeriveTokenAddress()` | Reads token address from the pool contract on-chain |
101+
| `DeriveTokenDecimals()` | Reads decimals from the token contract on-chain |
102+
| `DeriveTokenPoolCounterpart()` | Returns tokenPool unchanged (no PDA derivation needed on EVM) |
103+
| `ConfigureTokenForTransfersSequence()` | Registers token + sets remote chain configs |
104+
| `ManualRegistration()` | Registers customer token via proposeAdministrator |
105+
| `SetTokenPoolRateLimits()` | Sets inbound/outbound rate limits |
106+
| `DeployToken()` | Deploys ERC20 BurnMint token |
107+
| `DeployTokenPoolForToken()` | Deploys token pool for existing token |
108+
| `UpdateAuthorities()` | Transfers token/pool ownership to timelock |
109+
110+
### TokenPriceProvider (Optional)
111+
112+
```go
113+
func (e *EVMAdapter) GetDefaultTokenPrices() map[datastore.ContractType]*big.Int
114+
```
115+
116+
Returns a default price of $20 per token (18 decimals) for WETH and LINK.
117+
118+
### TransferOwnershipAdapter
119+
120+
| Method | Behavior |
121+
|--------|----------|
122+
| `InitializeTimelockAddress()` | No-op on EVM (timelock resolved at execution time) |
123+
| `SequenceTransferOwnershipViaMCMS()` | Calls `transferOwnership()` on each contract |
124+
| `SequenceAcceptOwnership()` | Calls `acceptOwnership()` on each contract |
125+
| `ShouldAcceptOwnershipWithTransferOwnership()` | Returns `false` (two-step ownership on EVM) |
126+
127+
### MCMSReader
128+
129+
| Method | Behavior |
130+
|--------|----------|
131+
| `GetChainMetadata()` | Reads MCM starting op count from on-chain |
132+
| `GetTimelockRef()` | Resolves RBACTimelock AddressRef from DataStore |
133+
| `GetMCMSRef()` | Resolves ProposerManyChainMultiSig AddressRef |
134+
135+
---
136+
137+
## Specialized Adapters
138+
139+
### CurseAdapter (`adapters/fastcurse.go`)
140+
141+
Implements `CurseAdapter` and `CurseSubjectAdapter` for EVM RMN operations.
142+
143+
- `Initialize()` -- loads RMNRemote contract address
144+
- `IsSubjectCursedOnChain()` -- calls `isCursed(subject)` on RMNRemote
145+
- `Curse()` / `Uncurse()` -- returns sequences that call `curse()`/`uncurse()` on RMNRemote
146+
- `SelectorToSubject()` -- converts chain selector to 16-byte curse subject
147+
- `SubjectToSelector()` -- reverses the conversion
148+
149+
### FeeAdapter (`adapters/fees.go`)
150+
151+
Implements `FeeAdapter` for EVM fee configuration.
152+
153+
- `SetTokenTransferFee()` -- returns sequence that calls `applyTokenTransferFeeConfigUpdates` on FeeQuoter
154+
- `GetOnchainTokenTransferFeeConfig()` -- reads current fee config from FeeQuoter
155+
- `GetDefaultTokenTransferFeeConfig()` -- returns sensible defaults
156+
157+
### ConfigImporter (`adapters/configimport.go`)
158+
159+
Implements `ConfigImporter` for importing existing on-chain state into the DataStore.
160+
161+
### LaneMigrater (`adapters/lanemigrator.go`)
162+
163+
Implements `RampUpdateInRouter` and `RouterUpdateInRamp` for lane migration scenarios.
164+
165+
---
166+
167+
## EVM Utilities
168+
169+
### Address Conversion (`utils/datastore/datastore.go`)
170+
171+
```go
172+
func ToByteArray(ref datastore.AddressRef) ([]byte, error) // Hex string -> bytes
173+
func ToEVMAddress(ref datastore.AddressRef) (common.Address, error) // Hex string -> common.Address
174+
func ToPaddedEVMAddress(ref datastore.AddressRef) ([]byte, error) // 32-byte left-padded
175+
```
176+
177+
### Contract Introspection (`utils/common.go`)
178+
179+
```go
180+
func TypeAndVersion(addr common.Address, client bind.ContractBackend) (string, *semver.Version, error)
181+
func ValidateEVMAddress(addr string, fieldName string) error
182+
```

‎chains/evm/deployment/docs/index.md‎

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
---
2+
title: "EVM Implementation"
3+
sidebar_label: "Overview"
4+
sidebar_position: 1
5+
---
6+
7+
# EVM Deployment Implementation
8+
9+
This documentation covers the EVM-specific implementation of the CCIP Deployment Tooling API. The EVM adapter is the most comprehensive reference implementation, supporting contract versions from v1.0.0 through v1.6.5.
10+
11+
For the shared interfaces this implementation fulfills, see [Interfaces Reference](../../../../deployment/docs/interfaces.md). For the shared types, see [Types Reference](../../../../deployment/docs/types.md).
12+
13+
---
14+
15+
## Package Layout
16+
17+
```
18+
chains/evm/deployment/
19+
├── utils/
20+
│ ├── common.go # Address/version utilities
21+
│ ├── datastore/
22+
│ │ └── datastore.go # EVM address format conversions
23+
│ └── operations/
24+
│ └── contract/
25+
│ ├── read.go # NewRead operation pattern
26+
│ ├── write.go # NewWrite operation pattern
27+
│ ├── deploy.go # NewDeploy operation pattern
28+
│ └── function.go # FunctionInput struct
29+
├── v1_0_0/ # Core infrastructure (MCMS, Router basics)
30+
│ ├── adapters/
31+
│ ├── operations/
32+
│ └── sequences/
33+
├── v1_2_0/ # Router enhancements
34+
│ ├── adapters/
35+
│ └── operations/
36+
├── v1_5_0/ # Token support
37+
│ ├── adapters/
38+
│ ├── changesets/
39+
│ ├── operations/
40+
│ └── sequences/
41+
├── v1_5_1/ # Token pool patch
42+
│ ├── operations/
43+
│ └── sequences/
44+
├── v1_6_0/ # Complete implementation
45+
│ ├── adapters/ # Registration + specialized adapters
46+
│ ├── operations/ # All contract operations
47+
│ ├── sequences/ # All sequence compositions
48+
│ └── testadapter/ # Test utilities
49+
├── v1_6_1/ # Operations + sequences
50+
├── v1_6_2/ # Operations only
51+
├── v1_6_3/ # Operations only
52+
└── v1_6_5/ # Operations only
53+
```
54+
55+
## Version Support
56+
57+
| Version | Scope | Contents |
58+
|---------|-------|----------|
59+
| **v1.0.0** | Core infrastructure | MCMS deployment, Router, WETH, LINK |
60+
| **v1.2.0** | Router updates | Router operations for lane migration |
61+
| **v1.5.0** | Token support | Token pools, token admin registry |
62+
| **v1.5.1** | Token pool patch | LockRelease pool enhancements |
63+
| **v1.6.0** | Complete implementation | Full adapter, all contracts, all sequences |
64+
| **v1.6.1 -- v1.6.5** | Incremental updates | Additional operations and sequences |
65+
66+
The v1.6.0 version is the primary implementation that registers the `EVMAdapter` with all shared registries. Newer versions add operations and sequences that build upon the v1.6.0 foundation.
67+
68+
## Documentation
69+
70+
- [EVMAdapter Reference](adapter.md) -- adapter struct, interface implementations, registration
71+
- [Operations Reference](operations.md) -- operation framework and all contract operations
72+
- [Sequences Reference](sequences.md) -- all sequences and EVM-specific changesets

0 commit comments

Comments
 (0)