Document canonicalization in CAIP2 and CAIP10 libraries (OpenZeppelin…

…#5319)

Signed-off-by: Hadrien Croubois <[email protected]>

contracts/utils/CAIP10.sol

@@ -13,6 +13,12 @@ import {CAIP2} from "./CAIP2.sol";
  * account_id:        chain_id + ":" + account_address
  * chain_id:          [-a-z0-9]{3,8}:[-_a-zA-Z0-9]{1,32} (See {CAIP2})
  * account_address:   [-.%a-zA-Z0-9]{1,128}
+ *
+ * WARNING: According to [CAIP-10's canonicalization section](https://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/caip-10.md#canonicalization),
+ * the implementation remains at the developer's discretion. Please note that case variations may introduce ambiguity.
+ * For example, when building hashes to identify accounts or data associated to them, multiple representations of the
+ * same account would derive to different hashes. For EVM chains, we recommend using checksummed addresses for the
+ * "account_address" part. They can be generated onchain using {Strings-toChecksumHexString}.
  */
 library CAIP10 {
     using Strings for address;

contracts/utils/CAIP2.sol

@@ -12,6 +12,11 @@ import {Strings} from "./Strings.sol";
  * chain_id:    namespace + ":" + reference
  * namespace:   [-a-z0-9]{3,8}
  * reference:   [-_a-zA-Z0-9]{1,32}
+ *
+ * WARNING: In some cases, multiple CAIP-2 identifiers may all be valid representation of a single chain.
+ * For EVM chains, it is recommended to use `eip155:xxx` as the canonical representation (where `xxx` is
+ * the EIP-155 chain id). Consider the possible ambiguity when processing CAIP-2 identifiers or when using them
+ * in the context of hashes.
  */
 library CAIP2 {
     using Strings for uint256;