feat: address normalizer (#2041)

* feat: normalize addresses WIP

* fix: wrap error

* docs: update method call

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

---------

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Author: chris-de-leon-cll

chains/evm/deployment/v1_0_0/adapters/address_normalizer.go

@@ -0,0 +1,21 @@
+package adapters
+
+import (
+	"fmt"
+
+	"github.com/ethereum/go-ethereum/common"
+
+	deployapi "github.com/smartcontractkit/chainlink-ccip/deployment/deploy"
+)
+
+var _ deployapi.AddressNormalizer = (*EVMAddressNormalizer)(nil)
+
+// EVMAddressNormalizer provides EIP-55 checksummed hex for datastore-aligned EVM lookups.
+type EVMAddressNormalizer struct{}
+
+func (EVMAddressNormalizer) NormalizeAddress(addr string) (string, error) {
+	if !common.IsHexAddress(addr) {
+		return "", fmt.Errorf("address %q is not a valid hex address", addr)
+	}
+	return common.HexToAddress(addr).Hex(), nil
+}

chains/evm/deployment/v1_0_0/adapters/init.go

@@ -18,4 +18,5 @@ func init() {
 	mcmsreaderapi.GetRegistry().RegisterMCMSReader(chain_selectors.FamilyEVM, &EVMMCMSReader{})
 	tokensapi.GetTokenAdapterRegistry().RegisterTokenAdapter(chain_selectors.FamilyEVM, v, &EVMTokenBase{})
 	feesapi.GetRegistry().RegisterFeeResolver(chain_selectors.FamilyEVM, &EVMFeeResolver{})
+	deployapi.GetAddressNormalizerRegistry().RegisterAddressNormalizer(chain_selectors.FamilyEVM, &EVMAddressNormalizer{})
 }

chains/solana/deployment/v1_0_0/adapters/address_normalizer.go

@@ -0,0 +1,22 @@
+package adapters
+
+import (
+	"fmt"
+
+	"github.com/gagliardetto/solana-go"
+
+	deployapi "github.com/smartcontractkit/chainlink-ccip/deployment/deploy"
+)
+
+var _ deployapi.AddressNormalizer = (*SolanaAddressNormalizer)(nil)
+
+// SolanaAddressNormalizer provides canonical base58 for datastore-aligned SVM lookups.
+type SolanaAddressNormalizer struct{}
+
+func (SolanaAddressNormalizer) NormalizeAddress(addr string) (string, error) {
+	pubKey, err := solana.PublicKeyFromBase58(addr)
+	if err != nil {
+		return "", fmt.Errorf("failed to parse address '%s' as base58 Solana public key: %w", addr, err)
+	}
+	return pubKey.String(), nil
+}

chains/solana/deployment/v1_0_0/adapters/init.go

@@ -3,9 +3,11 @@ package adapters
 import (
 	chainsel "github.com/smartcontractkit/chain-selectors"
 
+	deployapi "github.com/smartcontractkit/chainlink-ccip/deployment/deploy"
 	"github.com/smartcontractkit/chainlink-ccip/deployment/fees"
 )
 
 func init() {
 	fees.GetRegistry().RegisterFeeResolver(chainsel.FamilySolana, &SolanaFeeResolver{})
+	deployapi.GetAddressNormalizerRegistry().RegisterAddressNormalizer(chainsel.FamilySolana, &SolanaAddressNormalizer{})
 }

chains/solana/deployment/v1_6_0/sequences/tokens.go

@@ -22,8 +22,6 @@ import (
 	"github.com/smartcontractkit/chainlink-deployments-framework/deployment"
 	"github.com/smartcontractkit/chainlink-deployments-framework/operations"
 	cldf_ops "github.com/smartcontractkit/chainlink-deployments-framework/operations"
-
-	tokensapi "github.com/smartcontractkit/chainlink-ccip/deployment/tokens"
 )
 
 func (a *SolanaAdapter) ConfigureTokenForTransfersSequence() *cldf_ops.Sequence[tokenapi.ConfigureTokenForTransfersInput, sequences.OnChainOutput, cldf_chain.BlockChains] {
@@ -470,7 +468,7 @@ func (a *SolanaAdapter) DeployToken() *cldf_ops.Sequence[tokenapi.DeployTokenInp
 				}
 				var premint uint64 = 0
 				if input.PreMint != nil {
-					value := tokensapi.ScaleTokenAmount(new(big.Int).SetUint64(*input.PreMint), input.Decimals)
+					value := tokenapi.ScaleTokenAmount(new(big.Int).SetUint64(*input.PreMint), input.Decimals)
 					if !value.IsUint64() {
 						return sequences.OnChainOutput{}, fmt.Errorf("pre-mint amount is too large after scaling by decimals: %s", value.String())
 					}

deployment/deploy/product.go

@@ -112,3 +112,61 @@ type LaneVersionResolver interface {
 	IsSupportedChain(e cldf.Environment, chainSel uint64) bool
 	DeriveLaneVersionsForChain(e cldf.Environment, chainSel uint64) (map[uint64]*semver.Version, []*semver.Version, error)
 }
+
+// AddressNormalizer canonicalizes VM-specific address strings so datastore lookups
+// and config parsing behave consistently across deployments (same role as versioning
+// of pool contracts is orthogonal).
+type AddressNormalizer interface {
+	NormalizeAddress(address string) (string, error)
+}
+
+type addressNormalizerID string
+
+func newAddressNormalizerID(chainFamily string) addressNormalizerID {
+	return addressNormalizerID(chainFamily)
+}
+
+// AddressNormalizerRegistry maps chain family strings to address normalizers.
+// It is analogous to FeeAdapterRegistry's family-keyed FeeResolver slot.
+type AddressNormalizerRegistry struct {
+	mu sync.Mutex
+	m  map[addressNormalizerID]AddressNormalizer
+}
+
+func newAddressNormalizerRegistry() *AddressNormalizerRegistry {
+	return &AddressNormalizerRegistry{
+		m: make(map[addressNormalizerID]AddressNormalizer),
+	}
+}
+
+var (
+	addressNormalizerSingleton *AddressNormalizerRegistry
+	addressNormalizerOnce      sync.Once
+)
+
+// GetAddressNormalizerRegistry returns the singleton address normalizer registry.
+func GetAddressNormalizerRegistry() *AddressNormalizerRegistry {
+	addressNormalizerOnce.Do(func() {
+		addressNormalizerSingleton = newAddressNormalizerRegistry()
+	})
+	return addressNormalizerSingleton
+}
+
+// RegisterAddressNormalizer registers normalizer for chainFamily if not already set.
+func (r *AddressNormalizerRegistry) RegisterAddressNormalizer(chainFamily string, n AddressNormalizer) {
+	id := newAddressNormalizerID(chainFamily)
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	if _, exists := r.m[id]; !exists {
+		r.m[id] = n
+	}
+}
+
+// GetAddressNormalizer returns the AddressNormalizer registered for chainFamily.
+func (r *AddressNormalizerRegistry) GetAddressNormalizer(chainFamily string) (AddressNormalizer, bool) {
+	id := newAddressNormalizerID(chainFamily)
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	a, ok := r.m[id]
+	return a, ok
+}

deployment/docs/implementing-adapters.md

@@ -167,6 +167,14 @@ func (a *MyChainAdapter) DeriveTokenPoolCounterpart(e Environment, chainSelector
 }
 ```
 
+#### AddressNormalizer (config and datastore addresses)
+
+Some changesets normalize user-supplied address strings before datastore lookups. That logic lives on **`deploy.AddressNormalizer`** in **`deployment/deploy`**, registered on **`deploy.GetAddressNormalizerRegistry()`** and keyed **only by chain family** (not by token adapter semver).
+
+- Implement the interface in **`chains/<family>/deployment/v1_0_0/adapters/address_normalizer.go`** (see EVM and Solana in this repo).
+- Register once from that package’s **`init()`** with **`deploy.GetAddressNormalizerRegistry().RegisterAddressNormalizer(chain_selectors.Family..., &MyAddressNormalizer{})`** (first registration wins).
+- Optionally embed the normalizer on your **`TokenAdapter`** so the type still satisfies **`AddressNormalizer`** when useful; cross-package callers that only have a chain selector should use the family-keyed registry (as **`deployment/tokens`** does via **`chain_selectors.GetSelectorFamily`**).
+
 #### 4.4 FeeAdapter, MCMSReader, TransferOwnershipAdapter, CurseAdapter, CurseSubjectAdapter
 
 Follow the same pattern -- see [Interfaces Reference](interfaces.md) for the full method signatures.

deployment/tokens/configure_tokens_for_transfers.go

@@ -95,7 +95,22 @@ func processTokenConfigForChain(e deployment.Environment, mcmsRegistry *changese
 	reports := make([]cldf_ops.Report[any, any], 0)
 	ds := datastore.NewMemoryDataStore()
 
+	var err error
 	for selector, token := range cfg {
+		token.TokenPoolRef, err = TryNormalizeAddressRef(selector, token.TokenPoolRef)
+		if err != nil {
+			return nil, nil, nil, fmt.Errorf("failed to normalize token pool ref address for chain selector %d: %w", selector, err)
+		}
+		token.TokenRef, err = TryNormalizeAddressRef(selector, token.TokenRef)
+		if err != nil {
+			return nil, nil, nil, fmt.Errorf("failed to normalize token ref address for chain selector %d: %w", selector, err)
+		}
+		token.RegistryRef, err = TryNormalizeAddressRef(selector, token.RegistryRef)
+		if err != nil {
+			return nil, nil, nil, fmt.Errorf("failed to normalize registry ref address for chain selector %d: %w", selector, err)
+		}
+		cfg[selector] = token
+
 		tokenPool, err := datastore_utils.FindAndFormatRef(e.DataStore, token.TokenPoolRef, selector, datastore_utils.FullRef)
 		if err != nil {
 			return nil, nil, nil, fmt.Errorf("failed to resolve token pool ref on chain with selector %d: %w", selector, err)
@@ -201,7 +216,11 @@ func convertRemoteChainConfig(
 	}
 
 	if inCfg.RemotePool != nil {
-		fullRemotePoolRef, err := datastore_utils.FindAndFormatRef(e.DataStore, *inCfg.RemotePool, remoteChainSelector, datastore_utils.FullRef)
+		remotePoolRef, err := TryNormalizeAddressRef(remoteChainSelector, *inCfg.RemotePool)
+		if err != nil {
+			return outCfg, fmt.Errorf("failed to normalize remote pool ref address for remote chain selector %d: %w", remoteChainSelector, err)
+		}
+		fullRemotePoolRef, err := datastore_utils.FindAndFormatRef(e.DataStore, remotePoolRef, remoteChainSelector, datastore_utils.FullRef)
 		if err != nil {
 			return outCfg, fmt.Errorf("failed to resolve remote pool ref %s: %w", datastore_utils.SprintRef(*inCfg.RemotePool), err)
 		}
@@ -215,7 +234,11 @@ func convertRemoteChainConfig(
 		}
 		// Can either provide the token reference directly or derive it from the pool reference.
 		if inCfg.RemoteToken != nil {
-			outCfg.RemoteToken, err = datastore_utils.FindAndFormatRef(e.DataStore, *inCfg.RemoteToken, remoteChainSelector, remoteAdapter.AddressRefToBytes)
+			remoteTokenRef, normErr := TryNormalizeAddressRef(remoteChainSelector, *inCfg.RemoteToken)
+			if normErr != nil {
+				return outCfg, fmt.Errorf("failed to normalize remote token ref address for remote chain selector %d: %w", remoteChainSelector, normErr)
+			}
+			outCfg.RemoteToken, err = datastore_utils.FindAndFormatRef(e.DataStore, remoteTokenRef, remoteChainSelector, remoteAdapter.AddressRefToBytes)
 			if err != nil {
 				e.Logger.Warnf("failed to resolve remote token ref %s: %v. Will attempt to derive remote token address from pool reference", datastore_utils.SprintRef(*inCfg.RemoteToken), err)
 				outCfg.RemoteToken, err = remoteAdapter.DeriveTokenAddress(e, remoteChainSelector, fullRemotePoolRef)
@@ -240,30 +263,46 @@ func convertRemoteChainConfig(
 		}
 	}
 	for _, ccvRef := range inCfg.OutboundCCVs {
-		fullCCVRef, err := datastore_utils.FindAndFormatRef(e.DataStore, ccvRef, chainSelector, datastore_utils.FullRef)
+		ref, err := TryNormalizeAddressRef(chainSelector, ccvRef)
+		if err != nil {
+			return outCfg, fmt.Errorf("failed to normalize outbound CCV ref address for chain selector %d: %w", chainSelector, err)
+		}
+		fullCCVRef, err := datastore_utils.FindAndFormatRef(e.DataStore, ref, chainSelector, datastore_utils.FullRef)
 		if err != nil {
-			return outCfg, fmt.Errorf("failed to resolve outbound CCV ref %s: %w", datastore_utils.SprintRef(ccvRef), err)
+			return outCfg, fmt.Errorf("failed to resolve outbound CCV ref %s: %w", datastore_utils.SprintRef(ref), err)
 		}
 		outCfg.OutboundCCVs = append(outCfg.OutboundCCVs, fullCCVRef.Address)
 	}
 	for _, ccvRef := range inCfg.InboundCCVs {
-		fullCCVRef, err := datastore_utils.FindAndFormatRef(e.DataStore, ccvRef, chainSelector, datastore_utils.FullRef)
+		ref, err := TryNormalizeAddressRef(chainSelector, ccvRef)
+		if err != nil {
+			return outCfg, fmt.Errorf("failed to normalize inbound CCV ref address for chain selector %d: %w", chainSelector, err)
+		}
+		fullCCVRef, err := datastore_utils.FindAndFormatRef(e.DataStore, ref, chainSelector, datastore_utils.FullRef)
 		if err != nil {
-			return outCfg, fmt.Errorf("failed to resolve inbound CCV ref %s: %w", datastore_utils.SprintRef(ccvRef), err)
+			return outCfg, fmt.Errorf("failed to resolve inbound CCV ref %s: %w", datastore_utils.SprintRef(ref), err)
 		}
 		outCfg.InboundCCVs = append(outCfg.InboundCCVs, fullCCVRef.Address)
 	}
 	for _, ccvRef := range inCfg.OutboundCCVsToAddAboveThreshold {
-		fullCCVRef, err := datastore_utils.FindAndFormatRef(e.DataStore, ccvRef, chainSelector, datastore_utils.FullRef)
+		ref, err := TryNormalizeAddressRef(chainSelector, ccvRef)
 		if err != nil {
-			return outCfg, fmt.Errorf("failed to resolve outbound CCV to add above threshold ref %s: %w", datastore_utils.SprintRef(ccvRef), err)
+			return outCfg, fmt.Errorf("failed to normalize outbound CCV-above-threshold ref address for chain selector %d: %w", chainSelector, err)
+		}
+		fullCCVRef, err := datastore_utils.FindAndFormatRef(e.DataStore, ref, chainSelector, datastore_utils.FullRef)
+		if err != nil {
+			return outCfg, fmt.Errorf("failed to resolve outbound CCV to add above threshold ref %s: %w", datastore_utils.SprintRef(ref), err)
 		}
 		outCfg.OutboundCCVsToAddAboveThreshold = append(outCfg.OutboundCCVsToAddAboveThreshold, fullCCVRef.Address)
 	}
 	for _, ccvRef := range inCfg.InboundCCVsToAddAboveThreshold {
-		fullCCVRef, err := datastore_utils.FindAndFormatRef(e.DataStore, ccvRef, chainSelector, datastore_utils.FullRef)
+		ref, err := TryNormalizeAddressRef(chainSelector, ccvRef)
+		if err != nil {
+			return outCfg, fmt.Errorf("failed to normalize inbound CCV-above-threshold ref address for chain selector %d: %w", chainSelector, err)
+		}
+		fullCCVRef, err := datastore_utils.FindAndFormatRef(e.DataStore, ref, chainSelector, datastore_utils.FullRef)
 		if err != nil {
-			return outCfg, fmt.Errorf("failed to resolve inbound CCV to add above threshold ref %s: %w", datastore_utils.SprintRef(ccvRef), err)
+			return outCfg, fmt.Errorf("failed to resolve inbound CCV to add above threshold ref %s: %w", datastore_utils.SprintRef(ref), err)
 		}
 		outCfg.InboundCCVsToAddAboveThreshold = append(outCfg.InboundCCVsToAddAboveThreshold, fullCCVRef.Address)
 	}

deployment/tokens/migrate_lock_release_pool_liquidity.go

@@ -75,11 +75,20 @@ func makeMigrationApply(_ *TokenAdapterRegistry, mcmsRegistry *changesets.MCMSRe
 				return cldf.ChangesetOutput{}, fmt.Errorf("migration[%d]: adapter for family '%s' version '%s' does not support liquidity migration", i, family, migration.NewPoolRef.Version)
 			}
 
-			oldPoolRef, err := datastore_utils.FindAndFormatRef(e.DataStore, migration.OldPoolRef, migration.ChainSelector, datastore_utils.FullRef)
+			oldRef, err := TryNormalizeAddressRef(migration.ChainSelector, migration.OldPoolRef)
+			if err != nil {
+				return cldf.ChangesetOutput{}, fmt.Errorf("migration[%d]: failed to normalize old pool ref address: %w", i, err)
+			}
+			newRef, err := TryNormalizeAddressRef(migration.ChainSelector, migration.NewPoolRef)
+			if err != nil {
+				return cldf.ChangesetOutput{}, fmt.Errorf("migration[%d]: failed to normalize new pool ref address: %w", i, err)
+			}
+
+			oldPoolRef, err := datastore_utils.FindAndFormatRef(e.DataStore, oldRef, migration.ChainSelector, datastore_utils.FullRef)
 			if err != nil {
 				return cldf.ChangesetOutput{}, fmt.Errorf("migration[%d]: failed to resolve old pool ref: %w", i, err)
 			}
-			newPoolRef, err := datastore_utils.FindAndFormatRef(e.DataStore, migration.NewPoolRef, migration.ChainSelector, datastore_utils.FullRef)
+			newPoolRef, err := datastore_utils.FindAndFormatRef(e.DataStore, newRef, migration.ChainSelector, datastore_utils.FullRef)
 			if err != nil {
 				return cldf.ChangesetOutput{}, fmt.Errorf("migration[%d]: failed to resolve new pool ref: %w", i, err)
 			}
@@ -96,11 +105,19 @@ func makeMigrationApply(_ *TokenAdapterRegistry, mcmsRegistry *changesets.MCMSRe
 
 			var setPoolConfig *MigrationSetPoolConfig
 			if migration.RegistryRef != nil && migration.TokenRef != nil {
-				registryRef, err := datastore_utils.FindAndFormatRef(e.DataStore, *migration.RegistryRef, migration.ChainSelector, datastore_utils.FullRef)
+				regRef, err := TryNormalizeAddressRef(migration.ChainSelector, *migration.RegistryRef)
+				if err != nil {
+					return cldf.ChangesetOutput{}, fmt.Errorf("migration[%d]: failed to normalize registry ref address: %w", i, err)
+				}
+				tokRef, err := TryNormalizeAddressRef(migration.ChainSelector, *migration.TokenRef)
+				if err != nil {
+					return cldf.ChangesetOutput{}, fmt.Errorf("migration[%d]: failed to normalize token ref address for setPool: %w", i, err)
+				}
+				registryRef, err := datastore_utils.FindAndFormatRef(e.DataStore, regRef, migration.ChainSelector, datastore_utils.FullRef)
 				if err != nil {
 					return cldf.ChangesetOutput{}, fmt.Errorf("migration[%d]: failed to resolve registry ref: %w", i, err)
 				}
-				tokenRef, err := datastore_utils.FindAndFormatRef(e.DataStore, *migration.TokenRef, migration.ChainSelector, datastore_utils.FullRef)
+				tokenRef, err := datastore_utils.FindAndFormatRef(e.DataStore, tokRef, migration.ChainSelector, datastore_utils.FullRef)
 				if err != nil {
 					return cldf.ChangesetOutput{}, fmt.Errorf("migration[%d]: failed to resolve token ref: %w", i, err)
 				}

deployment/tokens/rate_limits.go

@@ -104,6 +104,14 @@ func setTokenPoolRateLimitsApply() func(cldf.Environment, TPRLInput) (cldf.Chang
 			if !exists {
 				return cldf.ChangesetOutput{}, fmt.Errorf("no TokenPoolAdapter registered for chain family '%s'", family)
 			}
+			config.TokenPoolRef, err = TryNormalizeAddressRef(selector, config.TokenPoolRef)
+			if err != nil {
+				return cldf.ChangesetOutput{}, fmt.Errorf("failed to normalize token pool ref address on chain selector %d: %w", selector, err)
+			}
+			config.TokenRef, err = TryNormalizeAddressRef(selector, config.TokenRef)
+			if err != nil {
+				return cldf.ChangesetOutput{}, fmt.Errorf("failed to normalize token ref address on chain selector %d: %w", selector, err)
+			}
 			tokenPool, err := datastore_utils.FindAndFormatRef(e.DataStore, config.TokenPoolRef, selector, datastore_utils.FullRef)
 			if err != nil {
 				return cldf.ChangesetOutput{}, fmt.Errorf("failed to resolve token pool ref on chain with selector %d: %w", selector, err)
@@ -151,17 +159,26 @@ func setTokenPoolRateLimitsApply() func(cldf.Environment, TPRLInput) (cldf.Chang
 					return cldf.ChangesetOutput{}, fmt.Errorf("no inputs provided for remote chain with selector %d to chain with selector %d", selector, remoteSelector)
 				}
 
+				counterpart.TokenPoolRef, err = TryNormalizeAddressRef(remoteSelector, counterpart.TokenPoolRef)
+				if err != nil {
+					return cldf.ChangesetOutput{}, fmt.Errorf("failed to normalize counterpart token pool ref address on chain selector %d: %w", remoteSelector, err)
+				}
+				counterpart.TokenRef, err = TryNormalizeAddressRef(remoteSelector, counterpart.TokenRef)
+				if err != nil {
+					return cldf.ChangesetOutput{}, fmt.Errorf("failed to normalize counterpart token ref address on chain selector %d: %w", remoteSelector, err)
+				}
+
 				remoteTokenPool, err := datastore_utils.FindAndFormatRef(e.DataStore, counterpart.TokenPoolRef, remoteSelector, datastore_utils.FullRef)
 				if err != nil {
 					return cldf.ChangesetOutput{}, fmt.Errorf("failed to resolve token pool ref on chain with selector %d: %w", remoteSelector, err)
 				}
 				remoteTokenBytes, err := datastore_utils.FindAndFormatRef(e.DataStore, counterpart.TokenRef, remoteSelector, counterPartAdapter.AddressRefToBytes)
 				if err != nil {
-					return cldf.ChangesetOutput{}, fmt.Errorf("failed to resolve token ref on chain with selector %d: %w", selector, err)
+					return cldf.ChangesetOutput{}, fmt.Errorf("failed to resolve token ref on chain with selector %d: %w", remoteSelector, err)
 				}
 				remoteDecimals, err := counterPartAdapter.DeriveTokenDecimals(e, remoteSelector, remoteTokenPool, remoteTokenBytes)
 				if err != nil {
-					return cldf.ChangesetOutput{}, fmt.Errorf("failed to get token decimals for token on chain with selector %d: %w", selector, err)
+					return cldf.ChangesetOutput{}, fmt.Errorf("failed to get token decimals for token on chain with selector %d: %w", remoteSelector, err)
 				}
 				tprlRemote.OutboundRateLimiterConfig, tprlRemote.InboundRateLimiterConfig = GenerateTPRLConfigs(inputs.RateLimit, remoteInputs.RateLimit, decimals, remoteDecimals, family, tokenPool.Version)
 				rateLimitReport, err := cldf_ops.ExecuteSequence(