solidity-scale-codec 0.3.3 → 1.0.0

package/CHANGELOG.md

@@ -7,15 +7,49 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 [Unreleased]
 
+## Version 1.0.0
+
+### Added
+
+- `BytesUtils.sol`, a new utility library for byte manipulation, including functions for copying byte arrays. - [#3](https://github.com/LucasGrasso/solidity-scale-codec/pull/3)
+- `UnsignedUtils.sol`, a new utility library for safely converting `uint256` values to smaller unsigned integer types (`uint8`, `uint16`, `uint32`, `uint64`, `uint128`) with overflow checks. - [#3](https://github.com/LucasGrasso/solidity-scale-codec/pull/3)
+- `XcmBuilder.sol`, a new utility library for constructing XCM messages in a more ergonomic way, with functions for building various XCM instructions. - [#3](https://github.com/LucasGrasso/solidity-scale-codec/pull/3)
+- Added `parent()` helper function in `Location.sol` to create a `Location` struct representing the parent location (one level up in the hierarchy). - [#93618bf](https://github.com/LucasGrasso/solidity-scale-codec/commit/93618bf)
+- Added `fromAsset(Asset)` and `fromAssets(Asset[])` helper functions in `Assets.sol` to construct `Assets` values ergonomically from a single asset or an array. - [#dd79e86](https://github.com/LucasGrasso/solidity-scale-codec/commit/dd79e86)
+
+### Changed
+
+- For every enum equivalent, rename `Type` suffix to `Variant` for better clarity and consistency. - [#3](https://github.com/LucasGrasso/solidity-scale-codec/pull/3)
+- Type Checking with `UnsignedUtils` in all codecs to ensure safe downcasting of `uint256` to smaller unsigned integer types, preventing potential overflow issues and improving robustness. - [#3](https://github.com/LucasGrasso/solidity-scale-codec/pull/3)
+- DRY with `BytesUtils.copy` in all codecs to replace manual byte copying loops, improving code readability, maintainability, and gas efficiency. - [#3](https://github.com/LucasGrasso/solidity-scale-codec/pull/3)
+- Removed unnecessary length checks at the beginning of decoding functions since `encodedSizeAt` and `BytesUtils.copy` will handle those checks and revert if data is insufficient, simplifying the code and centralizing error handling. - [#3](https://github.com/LucasGrasso/solidity-scale-codec/pull/3)
+- Moved helper `Junction` functions to outside of the codec. - [#b91bdfa](https://github.com/LucasGrasso/solidity-scale-codec/commit/b91bdfa24472fe931ee5dd6625ae2b4796d23248)
+
+### Fixed
+
+- Inconsistencies in Xcm Codec libraries:
+  - `decode`, `decodeAt` functions not returning `bytesRead` in some codecs. - [#3](https://github.com/LucasGrasso/solidity-scale-codec/pull/3)
+  - Now returning `{Variant}Params` structs in `as{Variant}` decoding functions for consistency and better ergonomics. - [#3](https://github.com/LucasGrasso/solidity-scale-codec/pull/3)
+- Inconsistencies in Xcm Instruction factory functions:
+  - Some factory functions were taking individual parameters instead of `{Variant}Params` structs, leading to less consistent and ergonomic API. - [#3](https://github.com/LucasGrasso/solidity-scale-codec/pull/3)
+- Now checking Variant bounds when calling `decodeAt` at all enum equivalents. - [#3](https://github.com/LucasGrasso/solidity-scale-codec/pull/3)
+- Optional encoding in `Junction` factory functions was not correctly implemented, leading to incorrect encoding when `hasNetwork` was false. - [#93618bf](https://github.com/LucasGrasso/solidity-scale-codec/commit/93618bf)
+
+## Version 0.3.4
+
+### Changed
+
+- Move Definitions to website docs - [#f57c914](https://github.com/LucasGrasso/solidity-scale-codec/commit/7e88534930cdb8ac47b5f16a02f2203c588a7e7f)
+
 ## Version 0.3.3
 
-## Changed
+### Changed
 
 - Homepage for the docsite - [#fcbac35](https://github.com/LucasGrasso/solidity-scale-codec/commit/757cddcce6d9f7a82f9535471c86f0cffa878956)
 
 ## Version 0.3.2
 
-## Changed
+### Changed
 
 - Better Changelog - [#288b3e9](https://github.com/LucasGrasso/solidity-scale-codec/commit/288b3e966ff1d030b7e50dcc40d0610cd30b201c)
 

package/README.md

@@ -22,7 +22,7 @@ This library provides a Highly-Modular implementation of SCALE in solidity.
 | `Compact` | A "compact" or general integer encoding is sufficient for encoding large integers (up to 2\*\*536) and is more efficient at encoding most values than the fixed-width version. (Though for single-byte values, the fixed-width integer is never worse.) | `0`     | `0x00`     |
 | `Arrays`  | A collection of same-typed values is encoded, prefixed with a compact encoding of the number of items, followed by each item's encoding concatenated in turn. Currently `[uintN]`,`[intN]`, `[bool]` are supported.                                     | `[1,0]` | `0x080100` |
 
-See the [Definitions](DEFINITIONS.md) for more details on the encoding of different types.
+See the [Definitions](https://lucasgrasso.github.io/solidity-scale-codec/Definitions.html) for more details on the encoding of different types.
 
 ## Usage
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "solidity-scale-codec",
-  "version": "0.3.3",
+  "version": "1.0.0",
   "description": "Solidity implementation of scale-codec.",
   "keywords": [
     "solidity",
@@ -47,7 +47,7 @@
     "hardhat": "^3.0.15",
     "prettier": "^3.8.1",
     "prettier-plugin-solidity": "^2.2.1",
-    "solidity-doc-generator": "^1.1.1",
+    "solidity-doc-generator": "^1.2.1",
     "typescript": "~5.8.0",
     "viem": "^2.40.3",
     "vitepress": "^1.6.4",

package/src/Utils/BytesUtils.sol

@@ -0,0 +1,26 @@
+// SPDX-License-Identifier: Apache-2.0
+pragma solidity ^0.8.28;
+
+/// @notice Utility functions for working with byte arrays, such as copying segments of bytes.
+library BytesUtils {
+    error InvalidBounds();
+
+    /// @notice Copies a segment of bytes from a source byte array.
+    /// @param src The source byte array from which to copy.
+    /// @param from The starting index in the source array from which to begin copying.
+    /// @param count The number of bytes to copy from the source array.
+    function copy(
+        bytes memory src,
+        uint256 from,
+        uint256 count
+    ) internal pure returns (bytes memory) {
+        if (src.length < from + count) {
+            revert InvalidBounds();
+        }
+        bytes memory result = new bytes(count);
+        for (uint256 i = 0; i < count; i++) {
+            result[i] = src[from + i];
+        }
+        return result;
+    }
+}

package/src/Utils/UnsignedUtils.sol

@@ -0,0 +1,52 @@
+// SPDX-License-Identifier: Apache-2.0
+pragma solidity ^0.8.28;
+
+/// @notice Utility functions for safely downcasting `uint256` values to smaller unsigned integer types.
+library UnsignedUtils {
+    error NumberTooLarge(uint256 value, uint256 max);
+
+    function toU8(uint256 value) internal pure returns (uint8) {
+        if (value > type(uint8).max) {
+            revert NumberTooLarge(value, type(uint8).max);
+        }
+        unchecked {
+            return uint8(value);
+        }
+    }
+
+    function toU16(uint256 value) internal pure returns (uint16) {
+        if (value > type(uint16).max) {
+            revert NumberTooLarge(value, type(uint16).max);
+        }
+        unchecked {
+            return uint16(value);
+        }
+    }
+
+    function toU32(uint256 value) internal pure returns (uint32) {
+        if (value > type(uint32).max) {
+            revert NumberTooLarge(value, type(uint32).max);
+        }
+        unchecked {
+            return uint32(value);
+        }
+    }
+
+    function toU64(uint256 value) internal pure returns (uint64) {
+        if (value > type(uint64).max) {
+            revert NumberTooLarge(value, type(uint64).max);
+        }
+        unchecked {
+            return uint64(value);
+        }
+    }
+
+    function toU128(uint256 value) internal pure returns (uint128) {
+        if (value > type(uint128).max) {
+            revert NumberTooLarge(value, type(uint128).max);
+        }
+        unchecked {
+            return uint128(value);
+        }
+    }
+}

package/src/Xcm/VersionedXcm/VersionedXcm.sol

@@ -6,8 +6,11 @@ import {XcmCodec as XcmV5Codec} from "../v5/Xcm/XcmCodec.sol";
 
 /// @notice The XCM versions supported by this package.
 enum XcmVersion {
-    _unsupported_V2,
+    _reserved0,
+    _reserved1,
+    _reserved2,
     _unsupported_V3,
+    _unsupported_V4,
     V5
 }
 

package/src/Xcm/VersionedXcm/VersionedXcmCodec.sol

@@ -67,4 +67,15 @@ library VersionedXcmCodec {
             revert UnsupportedXcmVersion(version);
         }
     }
+
+    /// @notice Converts a `VersionedXcm` to an `XcmV5` struct, if it is of version `V5`.
+    /// @param versionedXcm The `VersionedXcm` to convert.
+    /// @return xcm The decoded `XcmV5` struct contained in the `VersionedXcm`.
+    function asV5(
+        VersionedXcm memory versionedXcm
+    ) internal pure returns (XcmV5 memory xcm) {
+        if (versionedXcm.version != XcmVersion.V5)
+            revert UnsupportedXcmVersion(versionedXcm.version);
+        (xcm, ) = XcmV5Codec.decode(versionedXcm.xcm);
+    }
 }

package/src/Xcm/v3/MaybeErrorCode/MaybeErrorCode.sol

@@ -5,7 +5,7 @@ import {U8Arr} from "../../../Scale/Array.sol";
 import {MAX_DISPATCH_ERROR_LEN} from "../Constants.sol";
 
 /// @notice Discriminant for the `MaybeErrorCode` enum.
-enum MaybeErrorCodeType {
+enum MaybeErrorCodeVariant {
     /// @custom:variant No error occurred.
     Success,
     /// @custom:variant An error occurred, containing the dispatch error bytes.
@@ -16,9 +16,9 @@ enum MaybeErrorCodeType {
 
 /// @notice The result of a `Transact` dispatch, either success or an error code.
 struct MaybeErrorCode {
-    /// @custom:property The type of the result. See `MaybeErrorCodeType` enum for possible values.
-    MaybeErrorCodeType meType;
-    /// @custom:property The SCALE-encoded dispatch error bytes. Only meaningful when `meType` is `Error` or `TruncatedError`. Max length is MAX_DISPATCH_ERROR_LEN (128 bytes).
+    /// @custom:property The type of the result. See `MaybeErrorCodeVariant` enum for possible values.
+    MaybeErrorCodeVariant variant;
+    /// @custom:property The SCALE-encoded dispatch error bytes. Only meaningful when `variant` is `Error` or `TruncatedError`. Max length is MAX_DISPATCH_ERROR_LEN (128 bytes).
     bytes payload;
 }
 
@@ -39,7 +39,8 @@ struct TruncatedErrorParams {
 /// @notice Creates a `Success` MaybeErrorCode.
 /// @return A `MaybeErrorCode` struct representing success.
 function success() pure returns (MaybeErrorCode memory) {
-    return MaybeErrorCode({meType: MaybeErrorCodeType.Success, payload: ""});
+    return
+        MaybeErrorCode({variant: MaybeErrorCodeVariant.Success, payload: ""});
 }
 
 /// @notice Creates an `Error` MaybeErrorCode with the given dispatch error bytes.
@@ -50,7 +51,7 @@ function error(ErrorParams memory params) pure returns (MaybeErrorCode memory) {
         revert MaybeErrorCodeTooLong(params.errorBytes.length);
     return
         MaybeErrorCode({
-            meType: MaybeErrorCodeType.Error,
+            variant: MaybeErrorCodeVariant.Error,
             payload: U8Arr.encode(params.errorBytes)
         });
 }
@@ -65,7 +66,7 @@ function truncatedError(
         revert MaybeErrorCodeTooLong(params.errorBytes.length);
     return
         MaybeErrorCode({
-            meType: MaybeErrorCodeType.TruncatedError,
+            variant: MaybeErrorCodeVariant.TruncatedError,
             payload: U8Arr.encode(params.errorBytes)
         });
 }

package/src/Xcm/v3/MaybeErrorCode/MaybeErrorCodeCodec.sol

@@ -2,7 +2,8 @@
 pragma solidity ^0.8.28;
 
 import {U8Arr} from "../../../Scale/Array.sol";
-import {MaybeErrorCode, MaybeErrorCodeType} from "./MaybeErrorCode.sol";
+import {MaybeErrorCode, MaybeErrorCodeVariant} from "./MaybeErrorCode.sol";
+import {BytesUtils} from "../../../Utils/BytesUtils.sol";
 
 /// @title SCALE Codec for XCM v3 `MaybeErrorCode`
 /// @notice SCALE-compliant encoder/decoder for the `MaybeErrorCode` type.
@@ -10,7 +11,7 @@ import {MaybeErrorCode, MaybeErrorCodeType} from "./MaybeErrorCode.sol";
 /// @dev XCM v3 reference: https://paritytech.github.io/polkadot-sdk/master/staging_xcm/v3/index.html
 library MaybeErrorCodeCodec {
     error InvalidMaybeErrorCodeLength();
-    error InvalidMaybeErrorCodeType(uint8 meType);
+    error InvalidMaybeErrorCodeVariant(uint8 variant);
 
     /// @notice Encodes a `MaybeErrorCode` struct into SCALE bytes.
     /// @param me The `MaybeErrorCode` struct to encode.
@@ -18,7 +19,7 @@ library MaybeErrorCodeCodec {
     function encode(
         MaybeErrorCode memory me
     ) internal pure returns (bytes memory) {
-        return abi.encodePacked(uint8(me.meType), me.payload);
+        return abi.encodePacked(uint8(me.variant), me.payload);
     }
 
     /// @notice Returns the number of bytes that a `MaybeErrorCode` would occupy when SCALE-encoded.
@@ -30,16 +31,16 @@ library MaybeErrorCodeCodec {
         uint256 offset
     ) internal pure returns (uint256) {
         if (data.length < offset + 1) revert InvalidMaybeErrorCodeLength();
-        uint8 meType = uint8(data[offset]);
-        if (meType == uint8(MaybeErrorCodeType.Success)) {
+        uint8 variant = uint8(data[offset]);
+        if (variant == uint8(MaybeErrorCodeVariant.Success)) {
             return 1;
         } else if (
-            meType == uint8(MaybeErrorCodeType.Error) ||
-            meType == uint8(MaybeErrorCodeType.TruncatedError)
+            variant == uint8(MaybeErrorCodeVariant.Error) ||
+            variant == uint8(MaybeErrorCodeVariant.TruncatedError)
         ) {
             return 1 + U8Arr.encodedSizeAt(data, offset + 1);
         } else {
-            revert InvalidMaybeErrorCodeType(meType);
+            revert InvalidMaybeErrorCodeVariant(variant);
         }
     }
 
@@ -63,17 +64,15 @@ library MaybeErrorCodeCodec {
         uint256 offset
     ) internal pure returns (MaybeErrorCode memory me, uint256 bytesRead) {
         if (data.length < offset + 1) revert InvalidMaybeErrorCodeLength();
-        uint8 meType = uint8(data[offset]);
-        if (meType > uint8(MaybeErrorCodeType.TruncatedError))
-            revert InvalidMaybeErrorCodeType(meType);
+        uint8 variant = uint8(data[offset]);
+        if (variant > uint8(type(MaybeErrorCodeVariant).max)) {
+            revert InvalidMaybeErrorCodeVariant(variant);
+        }
         uint256 size = encodedSizeAt(data, offset);
         uint256 payloadLength = size - 1;
-        bytes memory payload = new bytes(payloadLength);
-        for (uint256 i = 0; i < payloadLength; ++i) {
-            payload[i] = data[offset + 1 + i];
-        }
+        bytes memory payload = BytesUtils.copy(data, offset + 1, payloadLength);
         me = MaybeErrorCode({
-            meType: MaybeErrorCodeType(meType),
+            variant: MaybeErrorCodeVariant(variant),
             payload: payload
         });
         bytesRead = size;
@@ -86,9 +85,9 @@ library MaybeErrorCodeCodec {
         MaybeErrorCode memory me
     ) internal pure returns (uint8[] memory errorBytes) {
         if (
-            me.meType != MaybeErrorCodeType.Error &&
-            me.meType != MaybeErrorCodeType.TruncatedError
-        ) revert InvalidMaybeErrorCodeType(uint8(me.meType));
+            me.variant != MaybeErrorCodeVariant.Error &&
+            me.variant != MaybeErrorCodeVariant.TruncatedError
+        ) revert InvalidMaybeErrorCodeVariant(uint8(me.variant));
         (errorBytes, ) = U8Arr.decode(me.payload);
     }
 }

package/src/Xcm/v5/AssetFilter/AssetFilter.sol

@@ -7,7 +7,7 @@ import {WildAsset} from "../WildAsset/WildAsset.sol";
 import {WildAssetCodec} from "../WildAsset/WildAssetCodec.sol";
 
 /// @notice Discriminant for the type of asset filter being specified in an `AssetFilter`.
-enum AssetFilterType {
+enum AssetFilterVariant {
     /// @custom:variant Specify the filter as being everything contained by the given `Assets` inner.
     Definite,
     /// @custom:variant Specify the filter as the given `WildAsset` wildcard.
@@ -16,9 +16,9 @@ enum AssetFilterType {
 
 /// @notice `Asset` collection, defined either by a number of `Assets` or a single wildcard.
 struct AssetFilter {
-    /// @custom:property The type of asset filter, determining how to interpret the payload. See `AssetFilterType` enum for possible values.
-    AssetFilterType afType;
-    /// @custom:property The encoded payload containing the asset filter data, whose structure depends on the `afType`.
+    /// @custom:property The type of asset filter, determining how to interpret the payload. See `AssetFilterVariant` enum for possible values.
+    AssetFilterVariant variant;
+    /// @custom:property The encoded payload containing the asset filter data, whose structure depends on the `variant`.
     bytes payload;
 }
 
@@ -31,7 +31,7 @@ struct DefiniteParams {
 /// @notice Parameters for the `Wild` variant.
 struct WildParams {
     /// @custom:property The wildcard asset selector.
-    WildAsset wA;
+    WildAsset wildAsset;
 }
 
 // ============ Factory Functions ============
@@ -44,7 +44,7 @@ function definite(
 ) pure returns (AssetFilter memory) {
     return
         AssetFilter({
-            afType: AssetFilterType.Definite,
+            variant: AssetFilterVariant.Definite,
             payload: AssetsCodec.encode(params.assets)
         });
 }
@@ -55,7 +55,7 @@ function definite(
 function wild(WildParams memory params) pure returns (AssetFilter memory) {
     return
         AssetFilter({
-            afType: AssetFilterType.Wild,
-            payload: WildAssetCodec.encode(params.wA)
+            variant: AssetFilterVariant.Wild,
+            payload: WildAssetCodec.encode(params.wildAsset)
         });
 }

package/src/Xcm/v5/AssetFilter/AssetFilterCodec.sol

@@ -5,7 +5,13 @@ import {Assets} from "../Assets/Assets.sol";
 import {AssetsCodec} from "../Assets/AssetsCodec.sol";
 import {WildAsset} from "../WildAsset/WildAsset.sol";
 import {WildAssetCodec} from "../WildAsset/WildAssetCodec.sol";
-import {AssetFilter, AssetFilterType} from "./AssetFilter.sol";
+import {
+    AssetFilter,
+    AssetFilterVariant,
+    DefiniteParams,
+    WildParams
+} from "./AssetFilter.sol";
+import {BytesUtils} from "../../../Utils/BytesUtils.sol";
 
 /// @title SCALE Codec for XCM v5 `AssetFilter`
 /// @notice SCALE-compliant encoder/decoder for the `AssetFilter` type.
@@ -13,8 +19,7 @@ import {AssetFilter, AssetFilterType} from "./AssetFilter.sol";
 /// @dev XCM v5 reference: https://paritytech.github.io/polkadot-sdk/master/staging_xcm/v5/index.html
 library AssetFilterCodec {
     error InvalidAssetFilterLength();
-    error InvalidAssetFilterType(uint8 afType);
-    error InvalidAssetFilterPayload();
+    error InvalidAssetFilterVariant(uint8 variant);
 
     /// @notice Encodes an `AssetFilter` struct into a SCALE-compliant byte array.
     /// @param assetFilter The `AssetFilter` struct to encode.
@@ -22,7 +27,8 @@ library AssetFilterCodec {
     function encode(
         AssetFilter memory assetFilter
     ) internal pure returns (bytes memory) {
-        return abi.encodePacked(uint8(assetFilter.afType), assetFilter.payload);
+        return
+            abi.encodePacked(uint8(assetFilter.variant), assetFilter.payload);
     }
 
     /// @notice Returns the number of bytes that a `AssetFilter` struct would occupy when SCALE-encoded.
@@ -36,22 +42,27 @@ library AssetFilterCodec {
         if (data.length < offset + 1) {
             revert InvalidAssetFilterLength();
         }
-        uint8 afType = uint8(data[offset]);
-        if (afType == uint8(AssetFilterType.Definite)) {
+        uint8 variant = uint8(data[offset]);
+        if (variant == uint8(AssetFilterVariant.Definite)) {
             return 1 + AssetsCodec.encodedSizeAt(data, offset + 1);
-        } else if (afType == uint8(AssetFilterType.Wild)) {
+        } else if (variant == uint8(AssetFilterVariant.Wild)) {
             return 1 + WildAssetCodec.encodedSizeAt(data, offset + 1);
         } else {
-            revert InvalidAssetFilterType(afType);
+            revert InvalidAssetFilterVariant(variant);
         }
     }
 
     /// @notice Decodes an `AssetFilter` struct from a SCALE-encoded byte array starting at the beginning of the data.
     /// @param data The byte sequence containing the encoded `AssetFilter`.
     /// @return assetFilter The decoded `AssetFilter` struct.
+    /// @return bytesRead The total number of bytes read from `data` to decode the `AssetFilter`.
     function decode(
         bytes memory data
-    ) internal pure returns (AssetFilter memory) {
+    )
+        internal
+        pure
+        returns (AssetFilter memory assetFilter, uint256 bytesRead)
+    {
         return decodeAt(data, 0);
     }
 
@@ -59,47 +70,49 @@ library AssetFilterCodec {
     /// @param data The byte sequence containing the encoded `AssetFilter`.
     /// @param offset The starting index in `data` from which to decode the `AssetFilter`.
     /// @return assetFilter The decoded `AssetFilter` struct.
+    /// @return bytesRead The total number of bytes read from `data` to decode the `AssetFilter`.
     function decodeAt(
         bytes memory data,
         uint256 offset
-    ) internal pure returns (AssetFilter memory assetFilter) {
-        if (data.length < offset + 1) {
-            revert InvalidAssetFilterLength();
-        }
-        uint8 afType = uint8(data[offset]);
-        uint256 payloadLength = encodedSizeAt(data, offset) - 1; // Subtract 1 byte for the afType
-        if (data.length < offset + 1 + payloadLength) {
-            revert InvalidAssetFilterLength();
-        }
-        bytes memory payload = new bytes(payloadLength);
-        for (uint256 i = 0; i < payloadLength; i++) {
-            payload[i] = data[offset + 1 + i];
-        }
-        assetFilter.afType = AssetFilterType(afType);
+    )
+        internal
+        pure
+        returns (AssetFilter memory assetFilter, uint256 bytesRead)
+    {
+        uint256 payloadLength = encodedSizeAt(data, offset) - 1; // Subtract 1 byte for the variant
+        uint8 variant = uint8(data[offset]);
+        bytes memory payload = BytesUtils.copy(data, offset + 1, payloadLength);
+        assetFilter.variant = AssetFilterVariant(variant);
         assetFilter.payload = payload;
+        bytesRead = 1 + payloadLength;
     }
 
     /// @notice Extracs the inner `Assets` collection. Reverts if the `AssetFilter` is not of the `Definite` variant.
     /// @param assetFilter The `AssetFilter` struct to decode, which must have the `Definite` variant.
-    /// @return assets The `Assets` collection contained within the `AssetFilter` if it is of the `Definite` variant.
+    /// @return params A `DefiniteParams` struct containing the decoded `Assets` collection.
     function asDefinite(
         AssetFilter memory assetFilter
-    ) internal pure returns (Assets memory assets) {
-        if (assetFilter.afType != AssetFilterType.Definite) {
-            revert InvalidAssetFilterPayload();
-        }
-        (assets, ) = AssetsCodec.decode(assetFilter.payload);
+    ) internal pure returns (DefiniteParams memory params) {
+        _assertVariant(assetFilter, AssetFilterVariant.Definite);
+        (params.assets, ) = AssetsCodec.decode(assetFilter.payload);
     }
 
     /// @notice Extracts the inner `WildAsset` wildcard. Reverts if the `AssetFilter` is not of the `Wild` variant.
     /// @param assetFilter The `AssetFilter` struct to decode, which must have the `Wild` variant.
-    /// @return wA The `WildAsset` wildcard contained within the `AssetFilter` if it is of the `Wild` variant.
+    /// @return params A `WildParams` struct containing the decoded `WildAsset` wildcard.
     function asWild(
         AssetFilter memory assetFilter
-    ) internal pure returns (WildAsset memory wA) {
-        if (assetFilter.afType != AssetFilterType.Wild) {
-            revert InvalidAssetFilterPayload();
+    ) internal pure returns (WildParams memory params) {
+        _assertVariant(assetFilter, AssetFilterVariant.Wild);
+        (params.wildAsset, ) = WildAssetCodec.decode(assetFilter.payload);
+    }
+
+    function _assertVariant(
+        AssetFilter memory assetFilter,
+        AssetFilterVariant expected
+    ) private pure {
+        if (assetFilter.variant != expected) {
+            revert InvalidAssetFilterVariant(uint8(assetFilter.variant));
         }
-        (wA, ) = WildAssetCodec.decode(assetFilter.payload);
     }
 }

package/src/Xcm/v5/AssetInstance/AssetInstance.sol

@@ -13,7 +13,7 @@ using Bytes16 for bytes16;
 using Bytes32 for bytes32;
 
 /// @dev Discriminant for the different types of AssetInstances in XCM v5.
-enum AssetInstanceType {
+enum AssetInstanceVariant {
     /// @custom:variant Used if the non-fungible asset class has only one instance.
     Undefined,
     /// @custom:variant A compact index up to 2^128 - 1.
@@ -30,16 +30,16 @@ enum AssetInstanceType {
 
 /// @notice A general identifier for an instance of a non-fungible asset class.
 struct AssetInstance {
-    /// @custom:property The type of asset instance, determining how to interpret the payload. See `AssetInstanceType` enum for possible values.
-    AssetInstanceType iType;
-    /// @custom:property The encoded payload containing the asset instance data, whose structure depends on the `iType`.
+    /// @custom:property The type of asset instance, determining how to interpret the payload. See `AssetInstanceVariant` enum for possible values.
+    AssetInstanceVariant variant;
+    /// @custom:property The encoded payload containing the asset instance data, whose structure depends on the `variant`.
     bytes payload;
 }
 
 /// @notice Parameters for the `Index` variant.
 struct IndexParams {
     /// @custom:property The compact index value.
-    uint128 idx;
+    uint128 index;
 }
 
 /// @notice Parameters for the `Array4` variant.
@@ -73,7 +73,7 @@ struct Array32Params {
 function undefined() pure returns (AssetInstance memory) {
     return
         AssetInstance({
-            iType: AssetInstanceType.Undefined,
+            variant: AssetInstanceVariant.Undefined,
             payload: new bytes(0)
         });
 }
@@ -82,8 +82,9 @@ function undefined() pure returns (AssetInstance memory) {
 /// @param params Parameters for the index variant.
 /// @return An `AssetInstance` struct with type `Index` and the provided index value encoded in the payload.
 function index(IndexParams memory params) pure returns (AssetInstance memory) {
-    bytes memory payload = Compact.encode(params.idx);
-    return AssetInstance({iType: AssetInstanceType.Index, payload: payload});
+    bytes memory payload = Compact.encode(params.index);
+    return
+        AssetInstance({variant: AssetInstanceVariant.Index, payload: payload});
 }
 
 /// @notice Creates an `Array4` asset instance with the given 4-byte data.
@@ -94,7 +95,7 @@ function array4(
 ) pure returns (AssetInstance memory) {
     return
         AssetInstance({
-            iType: AssetInstanceType.Array4,
+            variant: AssetInstanceVariant.Array4,
             payload: params.data.encode()
         });
 }
@@ -107,7 +108,7 @@ function array8(
 ) pure returns (AssetInstance memory) {
     return
         AssetInstance({
-            iType: AssetInstanceType.Array8,
+            variant: AssetInstanceVariant.Array8,
             payload: params.data.encode()
         });
 }
@@ -120,7 +121,7 @@ function array16(
 ) pure returns (AssetInstance memory) {
     return
         AssetInstance({
-            iType: AssetInstanceType.Array16,
+            variant: AssetInstanceVariant.Array16,
             payload: params.data.encode()
         });
 }
@@ -133,7 +134,7 @@ function array32(
 ) pure returns (AssetInstance memory) {
     return
         AssetInstance({
-            iType: AssetInstanceType.Array32,
+            variant: AssetInstanceVariant.Array32,
             payload: params.data.encode()
         });
 }