solidity-scale-codec 0.1.3 → 0.3.0

package/src/Scale/Bytes/Bytes8.sol

@@ -0,0 +1,53 @@
+// SPDX-License-Identifier: Apache-2.0
+pragma solidity ^0.8.28;
+
+/// @title Scale Codec for the `bytes8` type.
+/// @notice SCALE-compliant encoder/decoder for the `bytes8` type.
+/// @dev SCALE reference: https://docs.polkadot.com/polkadot-protocol/basics/data-encoding
+library Bytes8 {
+    error InvalidBytes8Length();
+
+    /// @notice Encodes an `bytes8` into SCALE format.
+    /// @param value The `bytes8` to encode.
+    /// @return SCALE-encoded byte sequence.
+    function encode(bytes8 value) internal pure returns (bytes memory) {
+        return abi.encodePacked(value);
+    }
+
+    /// @notice Returns the number of bytes that a `bytes8` would occupy when SCALE-encoded.
+    /// @param data The byte sequence containing the encoded `bytes8`.
+    /// @param offset The starting index in `data` from which to calculate the encoded size of the `bytes8`.
+    /// @return The number of bytes that the `bytes8` would occupy when SCALE-encoded.
+    function encodedSizeAt(
+        bytes memory data,
+        uint256 offset
+    ) internal pure returns (uint256) {
+        if (data.length < offset + 8) {
+            revert InvalidBytes8Length();
+        }
+        return 8;
+    }
+
+    /// @notice Decodes SCALE-encoded bytes into an `bytes8`.
+    /// @param data The SCALE-encoded byte sequence.
+    /// @return The decoded `bytes8`.
+    function decode(bytes memory data) internal pure returns (bytes8) {
+        return decodeAt(data, 0);
+    }
+
+    /// @notice Decodes an `bytes8` from SCALE format at the specified offset.
+    /// @param data The SCALE-encoded byte sequence.
+    /// @param offset The byte offset to start decoding from.
+    /// @return value The decoded `bytes8`.
+    function decodeAt(
+        bytes memory data,
+        uint256 offset
+    ) internal pure returns (bytes8 value) {
+        if (data.length < offset + 8) {
+            revert InvalidBytes8Length();
+        }
+        assembly {
+            value := mload(add(add(data, 32), offset))
+        }
+    }
+}

package/src/Scale/Bytes.sol

@@ -0,0 +1,8 @@
+// SPDX-License-Identifier: Apache-2.0
+pragma solidity ^0.8.28;
+
+import {Bytes2} from "./Bytes/Bytes2.sol";
+import {Bytes4} from "./Bytes/Bytes4.sol";
+import {Bytes8} from "./Bytes/Bytes8.sol";
+import {Bytes16} from "./Bytes/Bytes16.sol";
+import {Bytes32} from "./Bytes/Bytes32.sol";

package/src/Scale/Compact/Compact.sol

@@ -43,6 +43,35 @@ library Compact {
         }
     }
 
+    /// @notice Returns the number of bytes that the Compact-encoded value at the given offset occupies
+    /// @param data The byte sequence containing the Compact-encoded value
+    /// @param offset The byte offset to start reading from
+    /// @return size The total number of bytes occupied by the Compact-encoded value, including the header byte
+    /// @dev Reverts if the offset is out of bounds or if the header byte indicates an invalid encoding mode
+    function encodedSizeAt(
+        bytes memory data,
+        uint256 offset
+    ) internal pure returns (uint256 size) {
+        if (offset >= data.length) revert OffsetOutOfBounds();
+        uint8 header;
+        assembly {
+            header := shr(248, mload(add(add(data, 32), offset)))
+        }
+        uint8 mode = header & 0x03;
+        if (mode == MODE_SINGLE) {
+            size = 1;
+        } else if (mode == MODE_TWO) {
+            size = 2;
+        } else if (mode == MODE_FOUR) {
+            size = 4;
+        } else {
+            uint8 m = (header >> 2) + 4;
+            size = 1 + m;
+        }
+
+        if (data.length < offset + size) revert OffsetOutOfBounds();
+    }
+
     ///@notice Decodes a uint256 value from SCALE Compact format
     /// @dev Reverts if the encoding is invalid or non-canonical, or if the decoded value exceeds uint256 range
     /// @param data The Compact-encoded byte sequence
@@ -74,15 +103,20 @@ library Compact {
             value = uint256(header) >> 2;
             bytesRead = 1;
         } else if (mode == MODE_TWO) {
-            value = uint256(LittleEndianU16.fromLE(data, offset)) >> 2;
+            if (data.length < offset + 2) revert OffsetOutOfBounds();
+            value =
+                uint256(LittleEndianU16.fromLittleEndian(data, offset)) >> 2;
             bytesRead = 2;
         } else if (mode == MODE_FOUR) {
-            value = uint256(LittleEndianU32.fromLE(data, offset)) >> 2;
+            if (data.length < offset + 4) revert OffsetOutOfBounds();
+            value =
+                uint256(LittleEndianU32.fromLittleEndian(data, offset)) >> 2;
             bytesRead = 4;
         } else {
             uint8 m = (header >> 2) + 4;
             if (m > 32) revert ValueOutOfRange();
-            value = LittleEndianU256.fromLE(data, offset + 1);
+            if (data.length < offset + 1 + m) revert OffsetOutOfBounds();
+            value = LittleEndianU256.fromLittleEndian(data, offset + 1);
             if (m < 32) {
                 value &= (uint256(1) << (uint256(m) * 8)) - 1; // zero out bytes beyond m
             }

package/src/Scale/Signed/I128.sol

@@ -16,6 +16,17 @@ library I128 {
         return abi.encodePacked(toLittleEndian(value));
     }
 
+    /// @notice Returns the number of bytes that a `int128` would occupy when SCALE-encoded.
+    /// @param data The byte sequence containing the encoded `int128`.
+    /// @param offset The starting index in `data` from which to calculate the encoded size of the `int128`.
+    /// @return The number of bytes that the `int128` would occupy when SCALE-encoded.
+    function encodedSizeAt(
+        bytes memory data,
+        uint256 offset
+    ) internal pure returns (uint256) {
+        return U128.encodedSizeAt(data, offset);
+    }
+
     /// @notice Decodes SCALE-encoded bytes into an `int128`.
     /// @param data The SCALE-encoded byte sequence.
     /// @return The decoded `int128`.

package/src/Scale/Signed/I16.sol

@@ -16,6 +16,17 @@ library I16 {
         return abi.encodePacked(toLittleEndian(value));
     }
 
+    /// @notice Returns the number of bytes that a `int16` would occupy when SCALE-encoded.
+    /// @param data The byte sequence containing the encoded `int16`.
+    /// @param offset The starting index in `data` from which to calculate the encoded size of the `int16`.
+    /// @return The number of bytes that the `int16` would occupy when SCALE-encoded.
+    function encodedSizeAt(
+        bytes memory data,
+        uint256 offset
+    ) internal pure returns (uint256) {
+        return U16.encodedSizeAt(data, offset);
+    }
+
     /// @notice Decodes SCALE-encoded bytes into an `int16`.
     /// @param data The SCALE-encoded byte sequence.
     /// @return The decoded `int16`.

package/src/Scale/Signed/I256.sol

@@ -16,6 +16,17 @@ library I256 {
         return abi.encodePacked(toLittleEndian(value));
     }
 
+    /// @notice Returns the number of bytes that a `int256` would occupy when SCALE-encoded.
+    /// @param data The byte sequence containing the encoded `int256`.
+    /// @param offset The starting index in `data` from which to calculate the encoded size of the `int256`.
+    /// @return The number of bytes that the `int256` would occupy when SCALE-encoded.
+    function encodedSizeAt(
+        bytes memory data,
+        uint256 offset
+    ) internal pure returns (uint256) {
+        return U256.encodedSizeAt(data, offset);
+    }
+
     /// @notice Decodes SCALE-encoded bytes into an `int256`.
     /// @param data The SCALE-encoded byte sequence.
     /// @return The decoded `int256`.

package/src/Scale/Signed/I32.sol

@@ -16,6 +16,17 @@ library I32 {
         return abi.encodePacked(toLittleEndian(value));
     }
 
+    /// @notice Returns the number of bytes that a `int32` would occupy when SCALE-encoded.
+    /// @param data The byte sequence containing the encoded `int32`.
+    /// @param offset The starting index in `data` from which to calculate the encoded size of the `int32`.
+    /// @return The number of bytes that the `int32` would occupy when SCALE-encoded.
+    function encodedSizeAt(
+        bytes memory data,
+        uint256 offset
+    ) internal pure returns (uint256) {
+        return U32.encodedSizeAt(data, offset);
+    }
+
     /// @notice Decodes SCALE-encoded bytes into an `int32`.
     /// @param data The SCALE-encoded byte sequence.
     /// @return The decoded `int32`.

package/src/Scale/Signed/I64.sol

@@ -16,6 +16,17 @@ library I64 {
         return abi.encodePacked(toLittleEndian(value));
     }
 
+    /// @notice Returns the number of bytes that a `int64` would occupy when SCALE-encoded.
+    /// @param data The byte sequence containing the encoded `int64`.
+    /// @param offset The starting index in `data` from which to calculate the encoded size of the `int64`.
+    /// @return The number of bytes that the `int64` would occupy when SCALE-encoded.
+    function encodedSizeAt(
+        bytes memory data,
+        uint256 offset
+    ) internal pure returns (uint256) {
+        return U64.encodedSizeAt(data, offset);
+    }
+
     /// @notice Decodes SCALE-encoded bytes into an `int64`.
     /// @param data The SCALE-encoded byte sequence.
     /// @return The decoded `int64`.

package/src/Scale/Signed/I8.sol

@@ -16,6 +16,17 @@ library I8 {
         return abi.encodePacked(toLittleEndian(value));
     }
 
+    /// @notice Returns the number of bytes that a `int8` would occupy when SCALE-encoded.
+    /// @param data The byte sequence containing the encoded `int8`.
+    /// @param offset The starting index in `data` from which to calculate the encoded size of the `int8`.
+    /// @return The number of bytes that the `int8` would occupy when SCALE-encoded.
+    function encodedSizeAt(
+        bytes memory data,
+        uint256 offset
+    ) internal pure returns (uint256) {
+        return U8.encodedSizeAt(data, offset);
+    }
+
     /// @notice Decodes SCALE-encoded bytes into an `int8`.
     /// @param data The SCALE-encoded byte sequence.
     /// @return The decoded `int8`.

package/src/Scale/Unsigned/U128.sol

@@ -16,6 +16,20 @@ library U128 {
         return abi.encodePacked(toLittleEndian(value));
     }
 
+    /// @notice Returns the number of bytes that a `uint128` would occupy when SCALE-encoded.
+    /// @param data The byte sequence containing the encoded `uint128`.
+    /// @param offset The starting index in `data` from which to calculate the encoded size of the `uint128`.
+    /// @return The number of bytes that the `uint128` would occupy when SCALE-encoded.
+    function encodedSizeAt(
+        bytes memory data,
+        uint256 offset
+    ) internal pure returns (uint256) {
+        if (data.length < offset + 16) {
+            revert InvalidU128Length();
+        }
+        return 16;
+    }
+
     /// @notice Decodes SCALE-encoded bytes into an `uint128`.
     /// @param data The SCALE-encoded byte sequence.
     /// @return The decoded `uint128`.
@@ -32,7 +46,7 @@ library U128 {
         uint256 offset
     ) internal pure returns (uint128 value) {
         if (data.length < offset + 16) revert InvalidU128Length();
-        return LittleEndianU128.fromLE(data, offset);
+        return LittleEndianU128.fromLittleEndian(data, offset);
     }
 
     /// @notice Converts an `uint128` to little-endian bytes16
@@ -41,6 +55,6 @@ library U128 {
     function toLittleEndian(
         uint128 value
     ) internal pure returns (bytes16 result) {
-        return LittleEndianU128.toLE(value);
+        return LittleEndianU128.toLittleEndian(value);
     }
 }

package/src/Scale/Unsigned/U16.sol

@@ -16,6 +16,20 @@ library U16 {
         return abi.encodePacked(toLittleEndian(value));
     }
 
+    /// @notice Returns the number of bytes that a `uint16` would occupy when SCALE-encoded.
+    /// @param data The byte sequence containing the encoded `uint16`.
+    /// @param offset The starting index in `data` from which to calculate the encoded size of the `uint16`.
+    /// @return The number of bytes that the `uint16` would occupy when SCALE-encoded.
+    function encodedSizeAt(
+        bytes memory data,
+        uint256 offset
+    ) internal pure returns (uint256) {
+        if (data.length < offset + 2) {
+            revert InvalidU16Length();
+        }
+        return 2;
+    }
+
     /// @notice Decodes SCALE-encoded bytes into an `uint16`.
     /// @param data The SCALE-encoded byte sequence.
     /// @return The decoded `uint16`.
@@ -32,7 +46,7 @@ library U16 {
         uint256 offset
     ) internal pure returns (uint16 value) {
         if (data.length < offset + 2) revert InvalidU16Length();
-        return LittleEndianU16.fromLE(data, offset);
+        return LittleEndianU16.fromLittleEndian(data, offset);
     }
 
     /// @notice Converts an `uint16` to little-endian bytes2
@@ -41,6 +55,6 @@ library U16 {
     function toLittleEndian(
         uint16 value
     ) internal pure returns (bytes2 result) {
-        return LittleEndianU16.toLE(value);
+        return LittleEndianU16.toLittleEndian(value);
     }
 }

package/src/Scale/Unsigned/U256.sol

@@ -16,6 +16,20 @@ library U256 {
         return abi.encodePacked(toLittleEndian(value));
     }
 
+    /// @notice Returns the number of bytes that a `uint256` would occupy when SCALE-encoded.
+    /// @param data The byte sequence containing the encoded `uint256`.
+    /// @param offset The starting index in `data` from which to calculate the encoded size of the `uint256`.
+    /// @return The number of bytes that the `uint256` would occupy when SCALE-encoded.
+    function encodedSizeAt(
+        bytes memory data,
+        uint256 offset
+    ) internal pure returns (uint256) {
+        if (data.length < offset + 32) {
+            revert InvalidU256Length();
+        }
+        return 32;
+    }
+
     /// @notice Decodes SCALE-encoded bytes into an `uint256`.
     /// @param data The SCALE-encoded byte sequence.
     /// @return The decoded `uint256`.
@@ -32,7 +46,7 @@ library U256 {
         uint256 offset
     ) internal pure returns (uint256 value) {
         if (data.length < offset + 32) revert InvalidU256Length();
-        return LittleEndianU256.fromLE(data, offset);
+        return LittleEndianU256.fromLittleEndian(data, offset);
     }
 
     /// @notice Converts an `uint256` to little-endian bytes32
@@ -41,6 +55,6 @@ library U256 {
     function toLittleEndian(
         uint256 value
     ) internal pure returns (bytes32 result) {
-        return LittleEndianU256.toLE(value);
+        return LittleEndianU256.toLittleEndian(value);
     }
 }

package/src/Scale/Unsigned/U32.sol

@@ -16,6 +16,20 @@ library U32 {
         return abi.encodePacked(toLittleEndian(value));
     }
 
+    /// @notice Returns the number of bytes that a `uint32` would occupy when SCALE-encoded.
+    /// @param data The byte sequence containing the encoded `uint32`.
+    /// @param offset The starting index in `data` from which to calculate the encoded size of the `uint32`.
+    /// @return The number of bytes that the `uint32` would occupy when SCALE-encoded.
+    function encodedSizeAt(
+        bytes memory data,
+        uint256 offset
+    ) internal pure returns (uint256) {
+        if (data.length < offset + 4) {
+            revert InvalidU32Length();
+        }
+        return 4;
+    }
+
     /// @notice Decodes SCALE-encoded bytes into an `uint32`.
     /// @param data The SCALE-encoded byte sequence.
     /// @return The decoded `uint32`.
@@ -32,7 +46,7 @@ library U32 {
         uint256 offset
     ) internal pure returns (uint32 value) {
         if (data.length < offset + 4) revert InvalidU32Length();
-        return LittleEndianU32.fromLE(data, offset);
+        return LittleEndianU32.fromLittleEndian(data, offset);
     }
 
     /// @notice Converts an `uint32` to little-endian bytes4
@@ -41,6 +55,6 @@ library U32 {
     function toLittleEndian(
         uint32 value
     ) internal pure returns (bytes4 result) {
-        return LittleEndianU32.toLE(value);
+        return LittleEndianU32.toLittleEndian(value);
     }
 }

package/src/Scale/Unsigned/U64.sol

@@ -16,6 +16,20 @@ library U64 {
         return abi.encodePacked(toLittleEndian(value));
     }
 
+    /// @notice Returns the number of bytes that a `uint64` would occupy when SCALE-encoded.
+    /// @param data The byte sequence containing the encoded `uint64`.
+    /// @param offset The starting index in `data` from which to calculate the encoded size of the `uint64`.
+    /// @return The number of bytes that the `uint64` would occupy when SCALE-encoded.
+    function encodedSizeAt(
+        bytes memory data,
+        uint256 offset
+    ) internal pure returns (uint256) {
+        if (data.length < offset + 8) {
+            revert InvalidU64Length();
+        }
+        return 8;
+    }
+
     /// @notice Decodes SCALE-encoded bytes into an `uint64`.
     /// @param data The SCALE-encoded byte sequence.
     /// @return The decoded `uint64`.
@@ -32,7 +46,7 @@ library U64 {
         uint256 offset
     ) internal pure returns (uint64 value) {
         if (data.length < offset + 8) revert InvalidU64Length();
-        return LittleEndianU64.fromLE(data, offset);
+        return LittleEndianU64.fromLittleEndian(data, offset);
     }
 
     /// @notice Converts an `uint64` to little-endian bytes8
@@ -41,6 +55,6 @@ library U64 {
     function toLittleEndian(
         uint64 value
     ) internal pure returns (bytes8 result) {
-        return LittleEndianU64.toLE(value);
+        return LittleEndianU64.toLittleEndian(value);
     }
 }

package/src/Scale/Unsigned/U8.sol

@@ -16,6 +16,20 @@ library U8 {
         return abi.encodePacked(toLittleEndian(value));
     }
 
+    /// @notice Returns the number of bytes that a `uint8` would occupy when SCALE-encoded.
+    /// @param data The byte sequence containing the encoded `uint8`.
+    /// @param offset The starting index in `data` from which to calculate the encoded size of the `uint8`.
+    /// @return The number of bytes that the `uint8` would occupy when SCALE-encoded.
+    function encodedSizeAt(
+        bytes memory data,
+        uint256 offset
+    ) internal pure returns (uint256) {
+        if (data.length < offset + 1) {
+            revert InvalidU8Length();
+        }
+        return 1;
+    }
+
     /// @notice Decodes SCALE-encoded bytes into an `uint8`.
     /// @param data The SCALE-encoded byte sequence.
     /// @return The decoded `uint8`.
@@ -32,13 +46,13 @@ library U8 {
         uint256 offset
     ) internal pure returns (uint8 value) {
         if (data.length < offset + 1) revert InvalidU8Length();
-        return LittleEndianU8.fromLE(data, offset);
+        return LittleEndianU8.fromLittleEndian(data, offset);
     }
 
     /// @notice Converts an `uint8` to little-endian bytes1
     /// @param value The unsigned 8-bit integer to convert.
     /// @return result Little-endian byte representation of the input value.
     function toLittleEndian(uint8 value) internal pure returns (bytes1 result) {
-        return LittleEndianU8.toLE(value);
+        return LittleEndianU8.toLittleEndian(value);
     }
 }

package/src/Xcm/Types/Version.sol

@@ -0,0 +1,5 @@
+// SPDX-License-Identifier: Apache-2.0
+pragma solidity ^0.8.28;
+
+/// @notice A version of XCM.
+type Version is uint32;

package/src/Xcm/VersionedXcm/VersionedXcm.sol

@@ -0,0 +1,27 @@
+// SPDX-License-Identifier: Apache-2.0
+pragma solidity ^0.8.28;
+
+import {Xcm as XcmV5} from "../v5/Xcm/Xcm.sol";
+import {XcmCodec as XcmV5Codec} from "../v5/Xcm/XcmCodec.sol";
+
+/// @notice The XCM versions supported by this package.
+enum XcmVersion {
+    _unsupported_V2,
+    _unsupported_V3,
+    V5
+}
+
+/// @notice A single XCM message, together with its version code.
+struct VersionedXcm {
+    /// @custom:property The version of the XCM message.
+    XcmVersion version;
+    /// @custom:property The XCM message, encoded according to its version.
+    bytes xcm;
+}
+
+/// @notice Creates a `VersionedXcm` with version `V5` from an `XcmV5` struct.
+/// @param xcm The `XcmV5` struct to wrap.
+/// @return A `VersionedXcm` with version `V5` and the ABI-encoded `xcm` as its payload.
+function v5(XcmV5 memory xcm) pure returns (VersionedXcm memory) {
+    return VersionedXcm({version: XcmVersion.V5, xcm: XcmV5Codec.encode(xcm)});
+}

package/src/Xcm/VersionedXcm/VersionedXcmCodec.sol

@@ -0,0 +1,70 @@
+// SPDX-License-Identifier: Apache-2.0
+pragma solidity ^0.8.28;
+
+import {VersionedXcm, XcmVersion} from "./VersionedXcm.sol";
+import {Xcm as XcmV5} from "../v5/Xcm/Xcm.sol";
+import {XcmCodec as XcmV5Codec} from "../v5/Xcm/XcmCodec.sol";
+
+library VersionedXcmCodec {
+    error InvalidVersionedXcmLength();
+    error UnsupportedXcmVersion(XcmVersion version);
+
+    /// @notice Encodes a `VersionedXcm` into bytes, using the appropriate encoding for its version.
+    /// @param versionedXcm The `VersionedXcm` to encode.
+    /// @return The encoded bytes of the `VersionedXcm`.
+    function encode(
+        VersionedXcm memory versionedXcm
+    ) internal pure returns (bytes memory) {
+        if (versionedXcm.version == XcmVersion.V5) {
+            return
+                abi.encodePacked(uint8(versionedXcm.version), versionedXcm.xcm);
+        } else {
+            revert UnsupportedXcmVersion(versionedXcm.version);
+        }
+    }
+
+    /// @notice Decodes a `VersionedXcm` from bytes, using the appropriate decoding for its version.
+    /// @param data The byte sequence containing the encoded `VersionedXcm`.
+    /// @return versionedXcm The decoded `VersionedXcm` struct.
+    /// @return bytesRead The number of bytes read from `data` to decode the `VersionedXcm`.
+    function decode(
+        bytes memory data
+    )
+        internal
+        pure
+        returns (VersionedXcm memory versionedXcm, uint256 bytesRead)
+    {
+        return decodeAt(data, 0);
+    }
+
+    /// @notice Decodes a `VersionedXcm` from bytes starting at a given offset, using the appropriate decoding for its version.
+    /// @param data The byte sequence containing the encoded `VersionedXcm`.
+    /// @param offset The starting index in `data` from which to decode the `VersionedXcm`.
+    /// @return versionedXcm The decoded `VersionedXcm` struct.
+    /// @return bytesRead The number of bytes read from `data` to decode the `VersionedXcm`.
+    function decodeAt(
+        bytes memory data,
+        uint256 offset
+    )
+        internal
+        pure
+        returns (VersionedXcm memory versionedXcm, uint256 bytesRead)
+    {
+        if (data.length < offset + 1) revert InvalidVersionedXcmLength();
+        XcmVersion version = XcmVersion(uint8(data[offset]));
+        uint256 xcmByteLength;
+        bytes memory xcmBytes;
+        if (version == XcmVersion.V5) {
+            xcmByteLength = XcmV5Codec.encodedSizeAt(data, offset + 1);
+            if (data.length < offset + 1 + xcmByteLength)
+                revert InvalidVersionedXcmLength();
+            xcmBytes = new bytes(xcmByteLength);
+            for (uint256 i = 0; i < xcmByteLength; i++)
+                xcmBytes[i] = data[offset + 1 + i];
+            versionedXcm = VersionedXcm({version: version, xcm: xcmBytes});
+            bytesRead = 1 + xcmByteLength;
+        } else {
+            revert UnsupportedXcmVersion(version);
+        }
+    }
+}

package/src/Xcm/v3/Constants.sol

@@ -0,0 +1,5 @@
+// SPDX-License-Identifier: Apache-2.0
+pragma solidity ^0.8.28;
+
+// Maximum size of the encoded error code coming from a `Dispatch` result, used for `MaybeErrorCode`.
+uint32 constant MAX_DISPATCH_ERROR_LEN = 128;

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

@@ -0,0 +1,73 @@
+// SPDX-License-Identifier: Apache-2.0
+pragma solidity ^0.8.28;
+
+import {U8Arr} from "../../../Scale/Array.sol";
+import {MAX_DISPATCH_ERROR_LEN} from "../Constants.sol";
+
+/// @notice Discriminant for the `MaybeErrorCode` enum.
+enum MaybeErrorCodeType {
+    /// @custom:variant No error occurred.
+    Success,
+    /// @custom:variant An error occurred, containing the dispatch error bytes.
+    Error,
+    /// @custom:variant An error occurred but the error code was truncated to MAX_DISPATCH_ERROR_LEN bytes.
+    TruncatedError
+}
+
+/// @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).
+    bytes payload;
+}
+
+/// @notice Parameters for the `Error` variant.
+struct ErrorParams {
+    /// @custom:property Dispatch error bytes.
+    uint8[] errorBytes;
+}
+
+/// @notice Parameters for the `TruncatedError` variant.
+struct TruncatedErrorParams {
+    /// @custom:property Truncated dispatch error bytes.
+    uint8[] errorBytes;
+}
+
+// ============ Factory Functions ============
+
+/// @notice Creates a `Success` MaybeErrorCode.
+/// @return A `MaybeErrorCode` struct representing success.
+function success() pure returns (MaybeErrorCode memory) {
+    return MaybeErrorCode({meType: MaybeErrorCodeType.Success, payload: ""});
+}
+
+/// @notice Creates an `Error` MaybeErrorCode with the given dispatch error bytes.
+/// @param params Parameters for the error variant.
+/// @return A `MaybeErrorCode` struct representing the error.
+function error(ErrorParams memory params) pure returns (MaybeErrorCode memory) {
+    if (params.errorBytes.length > MAX_DISPATCH_ERROR_LEN)
+        revert MaybeErrorCodeTooLong(params.errorBytes.length);
+    return
+        MaybeErrorCode({
+            meType: MaybeErrorCodeType.Error,
+            payload: U8Arr.encode(params.errorBytes)
+        });
+}
+
+/// @notice Creates a `TruncatedError` MaybeErrorCode with the given dispatch error bytes.
+/// @param params Parameters for the truncated-error variant.
+/// @return A `MaybeErrorCode` struct representing the truncated error.
+function truncatedError(
+    TruncatedErrorParams memory params
+) pure returns (MaybeErrorCode memory) {
+    if (params.errorBytes.length > MAX_DISPATCH_ERROR_LEN)
+        revert MaybeErrorCodeTooLong(params.errorBytes.length);
+    return
+        MaybeErrorCode({
+            meType: MaybeErrorCodeType.TruncatedError,
+            payload: U8Arr.encode(params.errorBytes)
+        });
+}
+
+error MaybeErrorCodeTooLong(uint256 length);