solidity-scale-codec 0.1.3 → 0.2.0

package/src/Xcm/v5/BodyId/BodyIdCodec.sol

@@ -0,0 +1,128 @@
+// SPDX-License-Identifier: Apache-2.0
+pragma solidity ^0.8.28;
+
+import {Bytes4} from "../../../Scale/Bytes.sol";
+import {Compact} from "../../../Scale/Compact.sol";
+import {BodyId, BodyIdType} from "./BodyId.sol";
+
+/// @title SCALE Codec for XCM v5 `BodyId`
+/// @notice SCALE-compliant encoder/decoder for the `BodyId` type.
+/// @dev SCALE reference: https://docs.polkadot.com/polkadot-protocol/basics/data-encoding
+/// @dev XCM v5 reference: https://paritytech.github.io/polkadot-sdk/master/staging_xcm/v5/index.html
+library BodyIdCodec {
+    error InvalidBodyIdLength();
+    error InvalidBodyIdType(uint8 bodyIdType);
+
+    /// @notice Encodes a `BodyId` into bytes.
+    /// @param bodyId The `BodyId` to encode.
+    /// @return SCALE-encoded byte sequence representing the `BodyId`.
+    function encode(BodyId memory bodyId) internal pure returns (bytes memory) {
+        return abi.encodePacked(uint8(bodyId.bodyIdType), bodyId.payload);
+    }
+
+    /// @notice Returns the number of bytes that a `BodyId` struct would occupy when SCALE-encoded, starting at a given offset in the data.
+    /// @param data The byte sequence containing the encoded `BodyId`.
+    /// @param offset The starting index in `data` from which to calculate the encoded size of the `BodyId`.
+    /// @return The number of bytes that the `BodyId` struct would occupy when SCALE-encoded.
+    function encodedSizeAt(
+        bytes memory data,
+        uint256 offset
+    ) internal pure returns (uint256) {
+        if (data.length < offset + 1) {
+            revert InvalidBodyIdLength();
+        }
+        uint8 bodyIdTypeValue = uint8(data[offset]);
+        BodyIdType bodyIdType = BodyIdType(bodyIdTypeValue);
+        uint256 payloadLength;
+        if (
+            bodyIdType == BodyIdType.Unit ||
+            bodyIdType == BodyIdType.Executive ||
+            bodyIdType == BodyIdType.Technical ||
+            bodyIdType == BodyIdType.Legislative ||
+            bodyIdType == BodyIdType.Judicial ||
+            bodyIdType == BodyIdType.Defense ||
+            bodyIdType == BodyIdType.Administration ||
+            bodyIdType == BodyIdType.Treasury
+        ) {
+            payloadLength = 0;
+        } else if (bodyIdType == BodyIdType.Moniker) {
+            payloadLength = 4;
+        } else if (bodyIdType == BodyIdType.Index) {
+            payloadLength = 4;
+        } else {
+            revert InvalidBodyIdType(bodyIdTypeValue);
+        }
+
+        if (data.length < offset + 1 + payloadLength) {
+            revert InvalidBodyIdLength();
+        }
+
+        return 1 + payloadLength;
+    }
+
+    /// @notice Decodes a `BodyId` from bytes starting at the beginning of the data.
+    /// @param data The byte sequence containing the encoded `BodyId`.
+    /// @return bodyId The decoded `BodyId`.
+    /// @return bytesRead The total number of bytes read from the input data to decode the `BodyId`.
+    function decode(
+        bytes memory data
+    ) internal pure returns (BodyId memory bodyId, uint256 bytesRead) {
+        return decodeAt(data, 0);
+    }
+
+    /// @notice Decodes a `BodyId` from bytes starting at a given offset.
+    /// @param data The byte sequence containing the encoded `BodyId`.
+    /// @param offset The starting index in `data` from which to decode the `BodyId`.
+    /// @return bodyId The decoded `BodyId`.
+    /// @return bytesRead The total number of bytes read from the input data to decode the `BodyId`.
+    function decodeAt(
+        bytes memory data,
+        uint256 offset
+    ) internal pure returns (BodyId memory bodyId, uint256 bytesRead) {
+        if (data.length < offset + 1) {
+            revert InvalidBodyIdLength();
+        }
+        uint8 bodyIdTypeValue = uint8(data[offset]);
+        BodyIdType bodyIdType = BodyIdType(bodyIdTypeValue);
+        uint256 payloadLength = encodedSizeAt(data, offset) - 1; // subtract 1 byte for the bodyIdType
+        bytes memory payload = new bytes(payloadLength);
+
+        for (uint256 i = 0; i < payloadLength; i++) {
+            payload[i] = data[offset + 1 + i];
+        }
+
+        bodyId = BodyId({bodyIdType: bodyIdType, payload: payload});
+        bytesRead = 1 + payloadLength;
+    }
+
+    /// @notice Helper function to decode a `BodyId` and extract the moniker name if the type is `Moniker`.
+    /// @param bodyId The `BodyId` to extract the moniker name from.
+    /// @return name The 4-byte name of the moniker if the `bodyIdType` is `Moniker`.
+    function asMoniker(
+        BodyId memory bodyId
+    ) internal pure returns (bytes4 name) {
+        if (bodyId.bodyIdType != BodyIdType.Moniker) {
+            revert InvalidBodyIdType(uint8(bodyId.bodyIdType));
+        }
+        return Bytes4.decode(bodyId.payload);
+    }
+
+    /// @notice Helper function to decode a `BodyId` and extract the index if the type is `Index`.
+    /// @param bodyId The `BodyId` to extract the index from.
+    /// @return idx The index of the body if the `bodyIdType` is `Index`.
+    function asIndex(BodyId memory bodyId) internal pure returns (uint32 idx) {
+        if (bodyId.bodyIdType != BodyIdType.Index) {
+            revert InvalidBodyIdType(uint8(bodyId.bodyIdType));
+        }
+        if (bodyId.payload.length != 4) {
+            revert InvalidBodyIdLength();
+        }
+        (uint256 decodedIndex, ) = Compact.decode(bodyId.payload);
+        if (decodedIndex > type(uint32).max) {
+            revert InvalidBodyIdLength();
+        }
+        unchecked {
+            idx = uint32(decodedIndex);
+        }
+    }
+}

package/src/Xcm/v5/BodyPart/BodyPart.sol

@@ -0,0 +1,105 @@
+// SPDX-License-Identifier: Apache-2.0
+pragma solidity ^0.8.28;
+
+import {Compact} from "../../../Scale/Compact.sol";
+
+/// @dev Discriminant for the different types of BodyParts in XCM v5. Each variant corresponds to a specific structure of the payload.
+enum BodyPartType {
+    /// @custom:variant The body's declaration, under whatever means it decides.
+    Voice,
+    /// @custom:variant A given number of members of the body.
+    Members,
+    /// @custom:variant A given number of members of the body, out of some larger caucus.
+    Fraction,
+    /// @custom:variant No less than the given proportion of members of the body.
+    AtLeastProportion,
+    /// @custom:variant More than the given proportion of members of the body.
+    MoreThanProportion
+}
+
+/// @notice A part of a pluralistic body.
+struct BodyPart {
+    /// @custom:property The type of BodyPart, which determines how to interpret the payload. See `BodyPartType` enum for possible values.
+    BodyPartType bodyPartType;
+    /// @custom:property For Members, this will hold the count. For Fraction, AtLeastProportion, and MoreThanProportion, this will hold the encoded Proportion struct. For Voice, this will be empty.
+    bytes payload;
+}
+
+/// @notice Parameters for the `Members` variant.
+struct MembersParams {
+    /// @custom:property The number of members in the body part.
+    uint32 count;
+}
+
+// ============ Factory Functions ============
+
+/// @notice Creates a `BodyPart` struct representing a `Voice` body part.
+/// @return A `BodyPart` with the `Voice` variant.
+function voice() pure returns (BodyPart memory) {
+    return BodyPart({bodyPartType: BodyPartType.Voice, payload: ""});
+}
+
+/// @notice Creates a `BodyPart` struct representing a `Members` body part with the given count.
+/// @param params Parameters for the members variant.
+/// @return A `BodyPart` with the `Members` variant and the count encoded in the payload.
+function members(MembersParams memory params) pure returns (BodyPart memory) {
+    return
+        BodyPart({
+            bodyPartType: BodyPartType.Members,
+            payload: Compact.encode(params.count)
+        });
+}
+
+/// @notice Creates a `BodyPart` struct representing a `Fraction` body part with the given proportion.
+/// @param nominator The numerator of the proportion, representing the number of members in favor.
+/// @param denominator The denominator of the proportion, representing the total number of members considered.
+/// @return A `BodyPart` with the `Fraction` variant and the encoded proportion in the payload.
+function fraction(
+    uint32 nominator,
+    uint32 denominator
+) pure returns (BodyPart memory) {
+    return
+        BodyPart({
+            bodyPartType: BodyPartType.Fraction,
+            payload: abi.encodePacked(
+                Compact.encode(nominator),
+                Compact.encode(denominator)
+            )
+        });
+}
+
+/// @notice Creates a `BodyPart` struct representing an `AtLeastProportion` body part with the given proportion.
+/// @param nominator The numerator of the proportion, representing the minimum number of members in favor.
+/// @param denominator The denominator of the proportion, representing the total number of members considered.
+/// @return A `BodyPart` with the `AtLeastProportion` variant and the encoded proportion in the payload.
+function atLeastProportion(
+    uint32 nominator,
+    uint32 denominator
+) pure returns (BodyPart memory) {
+    return
+        BodyPart({
+            bodyPartType: BodyPartType.AtLeastProportion,
+            payload: abi.encodePacked(
+                Compact.encode(nominator),
+                Compact.encode(denominator)
+            )
+        });
+}
+
+/// @notice Creates a `BodyPart` struct representing a `MoreThanProportion` body part with the given proportion.
+/// @param nominator The numerator of the proportion, representing the minimum number of members in favor.
+/// @param denominator The denominator of the proportion, representing the total number of members considered.
+/// @return A `BodyPart` with the `MoreThanProportion` variant and the encoded proportion in the payload.
+function moreThanProportion(
+    uint32 nominator,
+    uint32 denominator
+) pure returns (BodyPart memory) {
+    return
+        BodyPart({
+            bodyPartType: BodyPartType.MoreThanProportion,
+            payload: abi.encodePacked(
+                Compact.encode(nominator),
+                Compact.encode(denominator)
+            )
+        });
+}

package/src/Xcm/v5/BodyPart/BodyPartCodec.sol

@@ -0,0 +1,134 @@
+// SPDX-License-Identifier: Apache-2.0
+pragma solidity ^0.8.28;
+
+import {Compact} from "../../../Scale/Compact.sol";
+import {BodyPart, BodyPartType} from "./BodyPart.sol";
+
+/// @title SCALE Codec for XCM v5 `BodyPart`
+/// @notice SCALE-compliant encoder/decoder for the `BodyPart` type.
+/// @dev SCALE reference: https://docs.polkadot.com/polkadot-protocol/basics/data-encoding
+/// @dev XCM v5 reference: https://paritytech.github.io/polkadot-sdk/master/staging_xcm/v5/index.html
+library BodyPartCodec {
+    error InvalidBodyPartLength();
+    error InvalidBodyPartType(uint8 bodyPartType);
+    error InvalidBodyPartPayload();
+
+    /// @notice Encodes a `BodyPart` struct into bytes.
+    /// @param bodyPart The `BodyPart` struct to encode.
+    /// @return SCALE-encoded byte sequence representing the `BodyPart`.
+    function encode(
+        BodyPart memory bodyPart
+    ) internal pure returns (bytes memory) {
+        return abi.encodePacked(uint8(bodyPart.bodyPartType), bodyPart.payload);
+    }
+
+    /// @notice Returns the number of bytes that a `BodyPart` struct would occupy when SCALE-encoded.
+    /// @param data The byte sequence containing the encoded `BodyPart`.
+    /// @param offset The starting index in `data` from which to calculate the encoded size of the `BodyPart`.
+    /// @return The number of bytes that the `BodyPart` struct would occupy when SCALE-encoded.
+    function encodedSizeAt(
+        bytes memory data,
+        uint256 offset
+    ) internal pure returns (uint256) {
+        if (offset >= data.length) revert InvalidBodyPartLength();
+
+        uint8 bodyPartType = uint8(data[offset]);
+        uint256 payloadLength;
+        if (bodyPartType == uint8(BodyPartType.Voice)) {
+            payloadLength = 0;
+        } else if (bodyPartType == uint8(BodyPartType.Members)) {
+            payloadLength = Compact.encodedSizeAt(data, offset + 1);
+        } else if (
+            bodyPartType == uint8(BodyPartType.Fraction) ||
+            bodyPartType == uint8(BodyPartType.AtLeastProportion) ||
+            bodyPartType == uint8(BodyPartType.MoreThanProportion)
+        ) {
+            uint256 innerLength = Compact.encodedSizeAt(data, offset + 1);
+            payloadLength =
+                innerLength +
+                Compact.encodedSizeAt(data, offset + 1 + innerLength);
+        } else {
+            revert InvalidBodyPartType(bodyPartType);
+        }
+
+        if (data.length < offset + 1 + payloadLength) {
+            revert InvalidBodyPartLength();
+        }
+
+        return 1 + payloadLength;
+    }
+
+    /// @notice Decodes a `BodyPart` struct from bytes starting at the beginning of the data.
+    /// @param data The byte sequence containing the encoded `BodyPart`.
+    /// @return bodyPart The decoded `BodyPart` struct.
+    /// @return bytesRead The total number of bytes read from the input data to decode the `BodyPart`.
+    function decode(
+        bytes memory data
+    ) internal pure returns (BodyPart memory bodyPart, uint256 bytesRead) {
+        return decodeAt(data, 0);
+    }
+
+    /// @notice Decodes a `BodyPart` struct from bytes starting at a given offset.
+    /// @param data The byte sequence containing the encoded `BodyPart`.
+    /// @param offset The starting index in `data` from which to decode the `BodyPart`.
+    /// @return bodyPart The decoded `BodyPart` struct.
+    /// @return bytesRead The total number of bytes read from the input data to decode the `BodyPart`.
+    function decodeAt(
+        bytes memory data,
+        uint256 offset
+    ) internal pure returns (BodyPart memory bodyPart, uint256 bytesRead) {
+        if (offset >= data.length) revert InvalidBodyPartLength();
+
+        uint8 bodyPartType = uint8(data[offset]);
+        uint256 payloadLength = encodedSizeAt(data, offset) - 1; // total size minus 1 byte for the bodyPartType
+
+        bytes memory payload = new bytes(payloadLength);
+        for (uint256 i = 0; i < payloadLength; i++) {
+            payload[i] = data[offset + 1 + i];
+        }
+
+        bodyPart = BodyPart({
+            bodyPartType: BodyPartType(bodyPartType),
+            payload: payload
+        });
+        bytesRead = 1 + payloadLength;
+    }
+
+    /// @notice Decodes a `Members` body part to extract the member count.
+    /// @param bodyPart The `BodyPart` struct to decode, which must be of type `Members`.
+    /// @return count The number of members encoded in the body part's payload.
+    function asMembers(
+        BodyPart memory bodyPart
+    ) internal pure returns (uint32 count) {
+        if (bodyPart.bodyPartType != BodyPartType.Members) {
+            revert InvalidBodyPartType(uint8(bodyPart.bodyPartType));
+        }
+        (uint256 decodedCount, ) = Compact.decode(bodyPart.payload);
+        count = uint32(decodedCount);
+    }
+
+    /// @notice Decodes a `Fraction`, `AtLeastProportion`, or `MoreThanProportion` body part to extract the nominator and denominator.
+    /// @param bodyPart The `BodyPart` struct to decode, which must be of type `Fraction`, `AtLeastProportion`, or `MoreThanProportion`.
+    /// @return nominator The numerator of the proportion encoded in the body part's payload.
+    /// @return denominator The denominator of the proportion encoded in the body part's payload.
+    function asProportion(
+        BodyPart memory bodyPart
+    ) internal pure returns (uint32 nominator, uint32 denominator) {
+        if (
+            bodyPart.bodyPartType != BodyPartType.Fraction &&
+            bodyPart.bodyPartType != BodyPartType.AtLeastProportion &&
+            bodyPart.bodyPartType != BodyPartType.MoreThanProportion
+        ) {
+            revert InvalidBodyPartType(uint8(bodyPart.bodyPartType));
+        }
+        (uint256 decodedNominator, uint256 offset) = Compact.decode(
+            bodyPart.payload
+        );
+        (uint256 decodedDenominator, ) = Compact.decodeAt(
+            bodyPart.payload,
+            offset
+        );
+        nominator = uint32(decodedNominator);
+        denominator = uint32(decodedDenominator);
+    }
+}

package/src/Xcm/v5/Constants.sol

@@ -0,0 +1,15 @@
+// SPDX-License-Identifier: Apache-2.0
+pragma solidity ^0.8.28;
+
+import {HintType} from "./Hint/Hint.sol";
+
+// Maximum number of items we expect in a single Assets value.
+uint64 constant MAX_ITEMS_IN_ASSETS = 20;
+// Maximum number of PalletsInfo entries we expect in a single `PalletsInfo` value.
+uint32 constant MAX_PALLETS_INFO = 64;
+// Maximum number of entries in `InitiateTransfer.assets` (BoundedVec<AssetTransferFilter, MaxAssetTransferFilters> in Rust).
+uint32 constant MAX_ASSET_TRANSFER_FILTERS = 6;
+// Maximum length of a pallet name in bytes.
+uint32 constant MAX_PALLET_NAME_LEN = 48;
+// Maximum number of hints in a `SetHints` instruction, equal to the number of variants in the `Hint` enum.
+uint32 constant HINT_NUM_VARIANTS = uint32(type(HintType).max) + 1;

package/src/Xcm/v5/Fungibility/Fungibility.sol

@@ -0,0 +1,60 @@
+// SPDX-License-Identifier: Apache-2.0
+pragma solidity ^0.8.28;
+
+import {Compact} from "../../../Scale/Compact.sol";
+import {AssetInstance} from "../AssetInstance/AssetInstance.sol";
+import {AssetInstanceCodec} from "../AssetInstance/AssetInstanceCodec.sol";
+
+/// @dev Discriminant for the different types of Fungibility in XCM v5.
+enum FungibilityType {
+    /// @custom:variant A fungible asset; we record a number of units, as a `uint128` in the inner item.
+    Fungible,
+    /// @custom:variant A non-fungible asset. We record the instance identifier in the inner item. Only one asset of each instance identifier may ever be in existence at once.
+    NonFungible
+}
+
+/// @notice Classification of whether an asset is fungible or not, along with a mandatory amount or instance.
+struct Fungibility {
+    /// @custom:property The type of fungibility, determining how to interpret the payload. See `FungibilityType` enum for possible values.
+    FungibilityType fType;
+    /// @custom:property The encoded payload containing the fungibility data, whose structure depends on the `fType`.
+    bytes payload;
+}
+
+/// @notice Parameters for the `Fungible` variant.
+struct FungibleParams {
+    /// @custom:property The number of units of the fungible asset.
+    uint128 amount;
+}
+
+/// @notice Parameters for the `NonFungible` variant.
+struct NonFungibleParams {
+    /// @custom:property The specific non-fungible asset instance.
+    AssetInstance instance;
+}
+
+// ============ Factory Functions ============
+
+/// @notice Creates a `Fungibility` struct representing a fungible asset with the given amount.
+/// @param params Parameters for the fungible variant.
+function fungible(
+    FungibleParams memory params
+) pure returns (Fungibility memory) {
+    return
+        Fungibility({
+            fType: FungibilityType.Fungible,
+            payload: Compact.encode(params.amount)
+        });
+}
+
+/// @notice Creates a `Fungibility` struct representing a non-fungible asset with the given instance identifier.
+/// @param params Parameters for the non-fungible variant.
+function nonFungible(
+    NonFungibleParams memory params
+) pure returns (Fungibility memory) {
+    return
+        Fungibility({
+            fType: FungibilityType.NonFungible,
+            payload: AssetInstanceCodec.encode(params.instance)
+        });
+}

package/src/Xcm/v5/Fungibility/FungibilityCodec.sol

@@ -0,0 +1,128 @@
+// SPDX-License-Identifier: Apache-2.0
+pragma solidity ^0.8.28;
+
+import {Compact} from "../../../Scale/Compact.sol";
+import {AssetInstance} from "../AssetInstance/AssetInstance.sol";
+import {AssetInstanceCodec} from "../AssetInstance/AssetInstanceCodec.sol";
+import {Fungibility, FungibilityType} from "./Fungibility.sol";
+
+/// @title SCALE Codec for XCM v5 `Fungibility`
+/// @notice SCALE-compliant encoder/decoder for the `Fungibility` type.
+/// @dev SCALE reference: https://docs.polkadot.com/polkadot-protocol/basics/data-encoding
+/// @dev XCM v5 reference: https://paritytech.github.io/polkadot-sdk/master/staging_xcm/v5/index.html
+library FungibilityCodec {
+    error InvalidFungibilityLength();
+    error InvalidFungibilityType(uint8 fType);
+    error InvalidFungibilityPayload();
+
+    /// @notice Encodes a `Fungibility` struct into bytes.
+    /// @param fungibility The `Fungibility` struct to encode.
+    /// @return SCALE-encoded byte sequence representing the `Fungibility`.
+    function encode(
+        Fungibility memory fungibility
+    ) internal pure returns (bytes memory) {
+        return abi.encodePacked(uint8(fungibility.fType), fungibility.payload);
+    }
+
+    /// @notice Returns the number of bytes that a `Fungibility` struct would occupy when SCALE-encoded, starting at a given offset in the data.
+    /// @param data The byte sequence containing the encoded `Fungibility`.
+    /// @param offset The starting index in `data` from which to calculate the encoded size of the `Fungibility`.
+    /// @return The number of bytes that the `Fungibility` struct would occupy when SCALE-encoded, starting at the given offset.
+    function encodedSizeAt(
+        bytes memory data,
+        uint256 offset
+    ) internal pure returns (uint256) {
+        if (data.length < offset + 1) {
+            revert InvalidFungibilityLength();
+        }
+        uint8 fType = uint8(data[offset]);
+        uint256 payloadLength;
+        ++offset;
+        if (fType == uint8(FungibilityType.Fungible)) {
+            payloadLength = Compact.encodedSizeAt(data, offset);
+        } else if (fType == uint8(FungibilityType.NonFungible)) {
+            payloadLength = AssetInstanceCodec.encodedSizeAt(data, offset);
+        } else {
+            revert InvalidFungibilityType(fType);
+        }
+
+        if (data.length < offset + payloadLength) {
+            revert InvalidFungibilityLength();
+        }
+
+        return 1 + payloadLength;
+    }
+
+    /// @notice Decodes a `Fungibility` instance from bytes starting at the beginning of the data.
+    /// @param data The byte sequence containing the encoded `Fungibility`.
+    /// @return fungibility The decoded `Fungibility` struct.
+    /// @return bytesRead The total number of bytes read from the input data to decode the `Fungibility`.
+    function decode(
+        bytes memory data
+    )
+        internal
+        pure
+        returns (Fungibility memory fungibility, uint256 bytesRead)
+    {
+        return decodeAt(data, 0);
+    }
+
+    /// @notice Decodes a `Fungibility` instance from bytes starting at a given offset.
+    /// @param data The byte sequence containing the encoded `Fungibility`.
+    /// @param offset The starting index in `data` from which to decode the `Fungibility`.
+    /// @return fungibility The decoded `Fungibility` struct.
+    /// @return bytesRead The total number of bytes read from the input data to decode the `Fungibility`.
+    function decodeAt(
+        bytes memory data,
+        uint256 offset
+    )
+        internal
+        pure
+        returns (Fungibility memory fungibility, uint256 bytesRead)
+    {
+        if (data.length < offset + 1) {
+            revert InvalidFungibilityLength();
+        }
+        uint8 fType = uint8(data[offset]);
+        uint256 payloadLength = encodedSizeAt(data, offset) - 1; // subtract 1 byte for the fType
+        bytes memory payload = new bytes(payloadLength);
+        for (uint256 i = 0; i < payloadLength; i++) {
+            payload[i] = data[offset + 1 + i];
+        }
+
+        return (
+            Fungibility({fType: FungibilityType(fType), payload: payload}),
+            1 + payloadLength
+        );
+    }
+
+    /// @notice Decodes a `Fungibility` struct representing a fungible asset and extracts the amount.
+    /// @param fungibility The `Fungibility` struct to decode, which must have `fType` equal to `FungibilityType.Fungible`.
+    /// @return amount The number of units of the fungible asset, as a `uint128`.
+    function asFungible(
+        Fungibility memory fungibility
+    ) internal pure returns (uint128 amount) {
+        if (fungibility.fType != FungibilityType.Fungible) {
+            revert InvalidFungibilityType(uint8(fungibility.fType));
+        }
+        (uint256 decodedAmount, ) = Compact.decode(fungibility.payload);
+        if (decodedAmount > type(uint128).max) {
+            revert InvalidFungibilityPayload();
+        }
+        unchecked {
+            amount = uint128(decodedAmount);
+        }
+    }
+
+    /// @notice Decodes a `Fungibility` struct representing a non-fungible asset and extracts the instance identifier.
+    /// @param fungibility The `Fungibility` struct to decode, which must have `fType` equal to `FungibilityType.NonFungible`.
+    /// @return instance The `AssetInstance` struct identifying the specific instance of the non-fungible asset.
+    function asNonFungible(
+        Fungibility memory fungibility
+    ) internal pure returns (AssetInstance memory instance) {
+        if (fungibility.fType != FungibilityType.NonFungible) {
+            revert InvalidFungibilityType(uint8(fungibility.fType));
+        }
+        (instance, ) = AssetInstanceCodec.decode(fungibility.payload);
+    }
+}

package/src/Xcm/v5/Hint/Hint.sol

@@ -0,0 +1,40 @@
+// SPDX-License-Identifier: Apache-2.0
+pragma solidity ^0.8.28;
+
+import {Location} from "../Location/Location.sol";
+import {LocationCodec} from "../Location/LocationCodec.sol";
+
+/// @notice Discriminant for the `Hint` enum.
+enum HintType {
+    /// @custom:variant Set asset claimer for all the trapped assets during the execution.
+    AssetClaimer
+}
+
+/// @notice A hint for XCM execution, changing the behaviour of the XCM program.
+struct Hint {
+    /// @custom:property The type of the hint. See `HintType` enum for possible values.
+    HintType hType;
+    /// @custom:property The SCALE-encoded payload of the hint. Structure depends on `hType`.
+    bytes payload;
+}
+
+/// @notice Parameters for the `AssetClaimer` variant.
+struct AssetClaimerParams {
+    /// @custom:property The claimer location.
+    Location location;
+}
+
+// ============ Factory Functions ============
+
+/// @notice Creates an `AssetClaimer` hint.
+/// @param params Parameters for the asset-claimer variant.
+/// @return A `Hint` struct representing the `AssetClaimer` hint.
+function assetClaimer(
+    AssetClaimerParams memory params
+) pure returns (Hint memory) {
+    return
+        Hint({
+            hType: HintType.AssetClaimer,
+            payload: LocationCodec.encode(params.location)
+        });
+}