Update chain ID format

[Gudahtt]

Description

The chain ID is now formatted internally as a 0x-prefixed hex string. This was chosen as the internal format for these reasons:

• It allows arbitrarily large chain IDs, unlike number
• It can be validated at runtime, unlike decimal strings
• It can be disambiguated from decimal strings and numbers at compile-time using the Hex type, unlike decimal strings
• It is serializable as JSON, unlike BigInt

However, to improve readability we will use the toHex helper function rather than string literals, letting us read chain IDs in the source code as decimal numbers or strings.

Changes

@metamask/address-book-controller

• BREAKING: The addressBook state property is now keyed by Hex chain ID rather than string, and the chainId property of each address book entry is also Hex rather than string.
  • This requires a state migration
• BREAKING: The methods delete and set now except the chain ID as Hex rather than as a decimal string
• CHANGED: Add @metamask/utils dependency

@metamask/assets-controllers

• BREAKING: Update @metamask/network-controller peerDependency
• BREAKING: Change format of chain ID in state to 0x-prefixed hex string
  • The functions isTokenDetectionSupportedForNetwork and formatIconUrlWithProxy now expect a chain ID as type Hex rather than as a decimal string
  • The assets contract controller now expects the chainId configuration entry and constructor parameter as type Hex rather than decimal string
  • The NFT controller now expects the chainId configuration entry and constructor parameter as type Hex rather than decimal string
  • The NFT controller methods addNft, checkAndUpdateSingleNftOwnershipStatus, findNftByAddressAndTokenId, updateNft, and resetNftTransactionStatusByTransactionId now expect the chain ID to be type Hex rather than a decimal string
  • The NFT controller state properties allNftContracts and allNfts are now keyed by address and Hex chain ID, rather than by address and decimal string chain ID
    • This requires a state migration
  • The NFT detection controller now expects the chainId configuration entry and constructor parameter as type Hex rather than decimal string
  • The token detection controller now expects the chainId configuration entry as type Hex rather than decimal string
  • The token list controller now expects the chainId constructor parameter as type Hex rather than decimal string
  • The token list controller state property tokensChainsCache is now keyed by Hex chain ID rather than by decimal string chain ID.
    • This requires a state migration
  • The token rates controller now expects the chainId configuration entry and constructor parameter as type Hex rather than decimal string
  • The token rates controller chainId setter now expects the chain ID as Hex rather than as a decimal string
  • The tokens controller now expects the chainId configuration entry and constructor parameter as type Hex rather than decimal string
  • The tokens controller addDetectedTokens method now accepts the chainId property of the detectionDetails parameter to be of type Hex rather than decimal string.
  • The tokens controller state properties allTokens, allIgnoredTokens, and allDetectedTokens are now keyed by chain ID in Hex format rather than decimal string.
    • This requires a state migration

@metamask/controller-utils

• BREAKING: The isSafeChainId parameter chainId is now type Hex rather than number
• BREAKING: The ChainId enum and the GANACHE_CHAIN_ID constant are now formatted as 0x-prefixed hex strings rather than as decimal strings.

@metamask/ens-controller

• BREAKING: Update @metamask/network-controller peerDependency
• BREAKING: The ensEntries state property is now keyed by Hex chain ID rather than string, and the chainId property of each ENS entry is also Hex rather than string.
  • This requires a state migration
• BREAKING: The methods get, set, and delete have been updated to accept and return chain IDs as 0x-prefixed hex strings, rather than decimal strings.

@metamask/gas-fee-controller

• BREAKING: Update @metamask/network-controller peerDependency
• BREAKING: The getChainId constructor parameter now expects a Hex return type rather than a decimal string
• CHANGED: Add @metamask/utils dependency

@metamask/message-manager

• BREAKING: The getCurrentChainId constructor parameter for each message manager now expects a Hex return type rather than a decimal string
  • Note that while every message manager class accepts this as a constructor parameter, it's only used by the TypedMessageManager at the moment.

@metamask/network-controller

• BREAKING: The providerConfig type and state property have changed. The chainId property is now a 0x-prefixed hex string rather than a decimal string.
  • This requires a state migration
  • This affects the return value of the NetworkController:getProviderConfig and NetworkController:getState actions.
• BREAKING: The NetworkConfiguration type and the networkConfigurations state property have changed. The chainId property on each configuration is now a 0x-prefixed hex string rather than a decimal string.
  • This requires a state migration
  • This change affects the upsertNetworkConfiguration method, which takes a network configuration as the first parameter
  • This affects the return value of the NetworkController:getState action

@metamask/signature-controller

• BREAKING: The constructor option getCurrentChainId now expects a Hex return value rather than string
• CHANGED: Add @metamask/utils dependency

@metamask/transaction-controller

• BREAKING: Update @metamask/network-controller dependency
  • This affects the getNetworkState and onNetworkStateChange constructor parameters
• BREAKING: Change format of chain ID in state to 0x-prefixed hex string
  • The chainId property of the Transaction type has been changed from a number to a 0x-prefixed hex string
  • The chainId property of the TransactionMeta type has been changed from a decimal string to a 0x-prefixed hex string, and the transaction property has been updated along with the Transaction type (as described above).
  • The state property transactions is an array of TransactionMeta objects, so it has changed according to the description above.
    • This requires a state migration: each entry should have the chainId property converted from a decimal string to a 0x-prefixed hex string, and the transaction.chainId property changed from a number to a 0x-prefixed hex string.
  • The addTransaction and estimateGas methods now expect the first parameter (transaction) to use the 0x-prefixed hex string format for the chainId property.
  • The updateTransaction method now expects the transactionMeta parameter to use the 0x-prefixed hex string format for the chainId property (and for the nested transaction.chainId property)
• CHANGED: Add @metamask/utils dependency

References

Closes #1209

Checklist

• I've updated the test suite for new or updated code as appropriate
• I've updated documentation for new or updated code as appropriate (note: this will usually be JSDoc)
• I've highlighted breaking changes using the "BREAKING" category above as appropriate

[mcmire]

Suggestions for the changelog:

@metamask/address-book-controller

• The addressBook state property is not only keyed by Hex chain ID rather than string, but also each address book entry has a Hex chain ID instead of a string — not sure if that's worth pointing out

@metamask/assets-controller

• NftController: Is addNft affected?

@metamask/ens-controller

• Similar to AddressBookController — the entries have a Hex chainId as well as being keyed by them

@metamask/transaction-controller

• The signature of the sign configuration option changed — the transaction argument must contain a Hex chain ID

[mcmire]

Can this still be undefined? I see this in TypedMessageManager.addUnapprovedMessageAsync:

      const currentChainId = this.getCurrentChainId?.();
      validateTypedSignMessageDataV3V4(messageParams, currentChainId);

[Gudahtt]

Yep! It's declared here as optional though.

[mcmire]

Undefined and optional are the same now, but I'm wondering whether they will be the same when we enable exactOptionalPropertyTypes (assuming we want to revive this PR).

That said, maybe it's the caller's responsibility to not pass this argument if it doesn't need to, so your change makes sense. Never mind!

[Gudahtt]

Hmm. yeah OK, I can switch it back to | undefined instead to make that switch easier.

[Gudahtt]

Updated in 4407595

[Gudahtt]

That said, maybe it's the caller's responsibility to not pass this argument if it doesn't need to, so your change makes sense. Never mind!

This was my first thought as well, but in this case it seems more ergonomic to always expect this to be passed in IMO.

[mcmire]

Looks good, other than the suggestions I made for the changelog.

[Gudahtt]

Great catch on the address book/ens entries, I have updated the changelog accordingly.

NftController: Is addNft affected?

Yes, it's affected via the fourth parameter, which contains a chain ID

The signature of the sign configuration option changed — the transaction argument must contain a Hex chain ID

I thought the same thing at first, but it's not affected. That accepts a TypedTransaction, which is a union of various types from within @ethereumjs/tx. One of them is called Transaction but it's different than the Transaction type we edited here.

That type has always accepted a 0x-prefixed hex string, so no change was needed.

[mcmire]

Looks good!