solidity-scale-codec 0.1.3 → 0.2.0

package/src/Xcm/v5/Junction/JunctionCodec.sol

@@ -0,0 +1,329 @@
+// SPDX-License-Identifier: Apache-2.0
+pragma solidity ^0.8.28;
+
+import {BodyId} from "../BodyId/BodyId.sol";
+import {BodyIdCodec} from "../BodyId/BodyIdCodec.sol";
+import {BodyPart} from "../BodyPart/BodyPart.sol";
+import {BodyPartCodec} from "../BodyPart/BodyPartCodec.sol";
+import {NetworkId} from "../NetworkId/NetworkId.sol";
+import {NetworkIdCodec} from "../NetworkId/NetworkIdCodec.sol";
+import {Bytes32} from "../../../Scale/Bytes.sol";
+import {Address} from "../../../Scale/Address.sol";
+import {Compact} from "../../../Scale/Compact.sol";
+import {
+    Junction,
+    JunctionType,
+    AccountId32Params,
+    PluralityParams,
+    AccountIndex64Params,
+    AccountKey20Params,
+    GeneralKeyParams
+} from "./Junction.sol";
+
+/// @title SCALE Codec for XCM v5 `Junction`
+/// @notice SCALE-compliant encoder/decoder for the `Junction` 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 JunctionCodec {
+    error InvalidJunctionLength();
+    error InvalidJunctionType(uint8 jType);
+    error InvalidJunctionPayload();
+
+    /// @notice Encodes a `Junction` struct into a byte array suitable for SCALE encoding.
+    /// @param junction The `Junction` struct to encode.
+    /// @return A byte array representing the SCALE-encoded junction, including its type and payload.
+    function encode(
+        Junction memory junction
+    ) internal pure returns (bytes memory) {
+        return abi.encodePacked(uint8(junction.jType), junction.payload);
+    }
+
+    /// @notice Returns the number of bytes that a `Junction` struct would occupy when SCALE-encoded, starting from the specified offset.
+    /// @param data The byte array containing the SCALE-encoded junction data.
+    /// @param offset The byte offset to start calculating from.
+    /// @return The number of bytes that the `Junction` struct would occupy when SCALE-encoded, including the type and payload.
+    function encodedSizeAt(
+        bytes memory data,
+        uint256 offset
+    ) internal pure returns (uint256) {
+        if (offset >= data.length) revert InvalidJunctionLength();
+        uint8 jType;
+        assembly {
+            jType := shr(248, mload(add(add(data, 32), offset)))
+        }
+        uint256 payloadLength;
+        ++offset; // Move past the type byte
+        if (jType == uint8(JunctionType.Parachain)) {
+            payloadLength = Compact.encodedSizeAt(data, offset);
+        } else if (jType == uint8(JunctionType.AccountId32)) {
+            payloadLength = _innerNetworkIdSize(data, offset) + 32; // for the account ID;
+        } else if (jType == uint8(JunctionType.AccountIndex64)) {
+            payloadLength = _innerNetworkIdSize(data, offset);
+            payloadLength += Compact.encodedSizeAt(
+                data,
+                offset + payloadLength
+            ); // for the account index
+        } else if (jType == uint8(JunctionType.AccountKey20)) {
+            payloadLength = _innerNetworkIdSize(data, offset) + 20; // for the account key;
+        } else if (jType == uint8(JunctionType.PalletInstance)) {
+            payloadLength = 1;
+        } else if (jType == uint8(JunctionType.GeneralIndex)) {
+            payloadLength = Compact.encodedSizeAt(data, offset);
+        } else if (jType == uint8(JunctionType.GeneralKey)) {
+            if (offset >= data.length) revert InvalidJunctionLength();
+            uint8 length = uint8(data[offset]);
+            payloadLength = 1 + length; // 1 byte for the length + the key bytes
+        } else if (
+            jType == uint8(JunctionType.OnlyChild) ||
+            jType == uint8(JunctionType.GlobalConsensus)
+        ) {
+            payloadLength = 0;
+        } else if (jType == uint8(JunctionType.Plurality)) {
+            uint256 innerLength = BodyIdCodec.encodedSizeAt(data, offset);
+            payloadLength =
+                innerLength +
+                BodyPartCodec.encodedSizeAt(data, offset + innerLength);
+        } else {
+            revert InvalidJunctionType(jType);
+        }
+
+        return 1 + payloadLength; // 1 byte for the type + payload length
+    }
+
+    /// @notice Decodes a byte array into a `Junction` struct, starting from the specified offset.
+    /// @param data The byte array containing the SCALE-encoded junction data.
+    /// @return junction A `Junction` struct representing the decoded junction, including its type and payload.
+    /// @return bytesRead The total number of bytes read during decoding, including the type and payload.
+    function decode(
+        bytes memory data
+    ) internal pure returns (Junction memory junction, uint256 bytesRead) {
+        return decodeAt(data, 0);
+    }
+
+    /// @notice Decodes a byte array into a `Junction` struct, starting from the specified offset.
+    /// @param data The byte array containing the SCALE-encoded junction data.
+    /// @param offset The byte offset to start decoding from.
+    /// @return junction A `Junction` struct representing the decoded junction, including its type and payload.
+    /// @return bytesRead The total number of bytes read during decoding, including the type and payload.
+    function decodeAt(
+        bytes memory data,
+        uint256 offset
+    ) internal pure returns (Junction memory junction, uint256 bytesRead) {
+        if (offset >= data.length) revert InvalidJunctionLength();
+        uint8 jType;
+        assembly {
+            jType := shr(248, mload(add(add(data, 32), offset)))
+        }
+        uint256 payloadLength = encodedSizeAt(data, offset) - 1; // Subtract 1 byte for the type
+        bytes memory payload = new bytes(payloadLength);
+        for (uint256 i = 0; i < payloadLength; i++) {
+            payload[i] = data[offset + 1 + i];
+        }
+        junction = Junction({jType: JunctionType(jType), payload: payload});
+        bytesRead = 1 + payload.length;
+    }
+
+    /// @notice Decodes a `Parachain` junction from a given `Junction` struct, extracting the parachain ID.
+    /// @param junction The `Junction` struct to decode, which should represent a `Parachain` junction.
+    /// @return parachainId The ID of the parachain extracted from the junction's payload.
+    function asParachain(
+        Junction memory junction
+    ) internal pure returns (uint32 parachainId) {
+        if (junction.jType != JunctionType.Parachain)
+            revert InvalidJunctionType(uint8(junction.jType));
+        if (junction.payload.length != 4) revert InvalidJunctionPayload();
+        (uint256 decodedParachain, ) = Compact.decode(junction.payload);
+        if (decodedParachain > type(uint32).max) {
+            revert InvalidJunctionPayload();
+        }
+        unchecked {
+            parachainId = uint32(decodedParachain);
+        }
+    }
+
+    /// @notice Decodes an `AccountId32` junction from a given `Junction` struct, extracting the network information and account ID.
+    /// @param junction The `Junction` struct to decode, which should represent an `AccountId32` junction.
+    /// @return params An `AccountId32Params` struct containing the decoded network information and account ID.
+    function asAccountId32(
+        Junction memory junction
+    ) internal pure returns (AccountId32Params memory params) {
+        if (junction.jType != JunctionType.AccountId32)
+            revert InvalidJunctionType(uint8(junction.jType));
+        if (junction.payload.length != 33 && junction.payload.length != 34)
+            revert InvalidJunctionPayload();
+        bool hasNetwork = junction.payload[0] != 0;
+        uint256 offset = 1;
+        NetworkId memory network;
+        uint256 bytesRead;
+        if (hasNetwork) {
+            (network, bytesRead) = NetworkIdCodec.decodeAt(
+                junction.payload,
+                offset
+            );
+            offset += bytesRead;
+        }
+        bytes32 id = Bytes32.decodeAt(junction.payload, offset);
+        return
+            AccountId32Params({
+                hasNetwork: hasNetwork,
+                network: network,
+                id: id
+            });
+    }
+
+    /// @notice Decodes an `AccountIndex64` junction from a given `Junction` struct, extracting the network information and account index.
+    /// @param junction The `Junction` struct to decode, which should represent an `AccountIndex64` junction.
+    /// @return params An `AccountIndex64Params` struct containing the decoded network information and account index.
+    function asAccountIndex64(
+        Junction memory junction
+    ) internal pure returns (AccountIndex64Params memory params) {
+        if (junction.jType != JunctionType.AccountIndex64)
+            revert InvalidJunctionType(uint8(junction.jType));
+        if (junction.payload.length != 9 && junction.payload.length != 10)
+            revert InvalidJunctionPayload();
+        bool hasNetwork = junction.payload[0] != 0;
+        uint256 offset = 1;
+        NetworkId memory network;
+        uint256 bytesRead;
+        if (hasNetwork) {
+            (network, bytesRead) = NetworkIdCodec.decodeAt(
+                junction.payload,
+                offset
+            );
+            offset += bytesRead;
+        }
+        (uint256 decodedIndex, ) = Compact.decodeAt(junction.payload, offset);
+        if (decodedIndex > type(uint64).max) {
+            revert InvalidJunctionPayload();
+        }
+        uint64 index;
+        unchecked {
+            index = uint64(decodedIndex);
+        }
+        return
+            AccountIndex64Params({
+                hasNetwork: hasNetwork,
+                network: network,
+                index: index
+            });
+    }
+
+    /// @notice Decodes an `AccountKey20` junction from a given `Junction` struct, extracting the network information and account key.
+    /// @param junction The `Junction` struct to decode, which should represent an `AccountKey20` junction.
+    /// @return params An `AccountKey20Params` struct containing the decoded network information and account key.
+    function asAccountKey20(
+        Junction memory junction
+    ) internal pure returns (AccountKey20Params memory params) {
+        if (junction.jType != JunctionType.AccountKey20)
+            revert InvalidJunctionType(uint8(junction.jType));
+        if (junction.payload.length != 21 && junction.payload.length != 22)
+            revert InvalidJunctionPayload();
+        bool hasNetwork = junction.payload[0] != 0;
+        uint256 offset = 1;
+        NetworkId memory network;
+        uint256 bytesRead;
+        if (hasNetwork) {
+            (network, bytesRead) = NetworkIdCodec.decodeAt(
+                junction.payload,
+                offset
+            );
+            offset += bytesRead;
+        }
+        address key = Address.decodeAt(junction.payload, offset);
+        return
+            AccountKey20Params({
+                hasNetwork: hasNetwork,
+                network: network,
+                key: key
+            });
+    }
+
+    /// @notice Decodes a `PalletInstance` junction from a given `Junction` struct, extracting the pallet instance index.
+    /// @param junction The `Junction` struct to decode, which should represent a `PalletInstance` junction.
+    /// @return instance The index of the pallet instance extracted from the junction's payload.
+    function asPalletInstance(
+        Junction memory junction
+    ) internal pure returns (uint8 instance) {
+        if (junction.jType != JunctionType.PalletInstance)
+            revert InvalidJunctionType(uint8(junction.jType));
+        if (junction.payload.length != 1) revert InvalidJunctionPayload();
+        return uint8(junction.payload[0]);
+    }
+
+    /// @notice Decodes a `GeneralIndex` junction from a given `Junction` struct, extracting the general index.
+    /// @param junction The `Junction` struct to decode, which should represent a `GeneralIndex` junction.
+    /// @return index The general index extracted from the junction's payload.
+    function asGeneralIndex(
+        Junction memory junction
+    ) internal pure returns (uint128 index) {
+        if (junction.jType != JunctionType.GeneralIndex)
+            revert InvalidJunctionType(uint8(junction.jType));
+        if (junction.payload.length == 0) revert InvalidJunctionPayload();
+        (uint256 decodedIndex, ) = Compact.decode(junction.payload);
+        if (decodedIndex > type(uint128).max) {
+            revert InvalidJunctionPayload();
+        }
+        unchecked {
+            index = uint128(decodedIndex);
+        }
+    }
+
+    /// @notice Decodes a `GeneralKey` junction from a given `Junction` struct, extracting the key.
+    /// @param junction The `Junction` struct to decode, which should represent a `GeneralKey` junction.
+    /// @return params A `GeneralKeyParams` struct containing the length and key extracted from the junction's payload.
+    function asGeneralKey(
+        Junction memory junction
+    ) internal pure returns (GeneralKeyParams memory params) {
+        if (junction.jType != JunctionType.GeneralKey)
+            revert InvalidJunctionType(uint8(junction.jType));
+        if (junction.payload.length == 0) revert InvalidJunctionPayload();
+        uint8 length = uint8(junction.payload[0]);
+        if (length == 0 || length > 32 || junction.payload.length != length + 1)
+            revert InvalidJunctionPayload();
+        bytes32 key = Bytes32.decodeAt(junction.payload, 1);
+        return GeneralKeyParams({length: length, key: key});
+    }
+
+    /// @notice Decodes a `Plurality` junction from a given `Junction` struct, extracting the body ID and body part.
+    /// @param junction The `Junction` struct to decode, which should represent a `Plurality` junction.
+    /// @return params A `PluralityParams` struct containing the body ID and body part extracted from the junction's payload.
+    function asPlurality(
+        Junction memory junction
+    ) internal pure returns (PluralityParams memory params) {
+        if (junction.jType != JunctionType.Plurality)
+            revert InvalidJunctionType(uint8(junction.jType));
+        if (junction.payload.length == 0) revert InvalidJunctionPayload();
+        uint256 offset = 0;
+        BodyId memory id;
+        uint256 bytesRead;
+        (id, bytesRead) = BodyIdCodec.decodeAt(junction.payload, offset);
+        offset += bytesRead;
+        BodyPart memory part;
+        (part, bytesRead) = BodyPartCodec.decodeAt(junction.payload, offset);
+        return PluralityParams({id: id, part: part});
+    }
+
+    /// @notice Decodes an `GlobalConsensus` junction from a given `Junction` struct and extracts the `NetworkId`.
+    /// @param junction The `Junction` struct to decode, which should represent a `GlobalConsensus` junction.
+    /// @return networkId The `NetworkId` extracted from the junction's payload, representing the global network's consensus.
+    function asGlobalConsensus(
+        Junction memory junction
+    ) internal pure returns (NetworkId memory networkId) {
+        if (junction.jType != JunctionType.GlobalConsensus)
+            revert InvalidJunctionType(uint8(junction.jType));
+        (networkId, ) = NetworkIdCodec.decode(junction.payload);
+    }
+
+    function _innerNetworkIdSize(
+        bytes memory data,
+        uint256 offset
+    ) private pure returns (uint256) {
+        if (offset >= data.length) revert InvalidJunctionLength();
+        bool hasNetwork = data[offset] != 0;
+        uint256 size = 1; // for the hasNetwork byte
+        if (hasNetwork) {
+            size += NetworkIdCodec.encodedSizeAt(data, offset + size);
+        }
+        return size;
+    }
+}

package/src/Xcm/v5/Junctions/Junctions.sol

@@ -0,0 +1,12 @@
+// SPDX-License-Identifier: Apache-2.0
+pragma solidity ^0.8.28;
+
+import {Junction} from "../Junction/Junction.sol";
+
+/// @dev The `Junctions` struct represents a sequence of up to 8 `Junction` items, prefixed by a count.
+struct Junctions {
+    /// @custom:property Represents the enum discriminant, 0 = Here, 1 = X1, ..., 8 = X8
+    uint8 count;
+    /// @custom:property // The actual junction data
+    Junction[] items;
+}

package/src/Xcm/v5/Junctions/JunctionsCodec.sol

@@ -0,0 +1,120 @@
+// SPDX-License-Identifier: Apache-2.0
+pragma solidity ^0.8.28;
+
+import {Junction} from "../Junction/Junction.sol";
+import {JunctionCodec} from "../Junction/JunctionCodec.sol";
+import {Junctions} from "./Junctions.sol";
+
+/// @title SCALE Codec for XCM v5 `Junctions`
+/// @notice SCALE-compliant encoder/decoder for the `Junctions` 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 JunctionsCodec {
+    error InvalidJunctionsLength(uint8 count);
+    error InvalidJunctionsCount(uint8 count);
+
+    /// @notice Creates a `Here` junctions struct.
+    function here() internal pure returns (Junctions memory) {
+        return Junctions({count: 0, items: new Junction[](0)});
+    }
+
+    /// @notice Creates a `Junctions` struct with the given junctions.
+    function junction(
+        Junction[] memory junctions
+    ) internal pure returns (Junctions memory) {
+        if (junctions.length == 0) {
+            return here();
+        }
+        if (junctions.length > 8) {
+            revert InvalidJunctionsCount(uint8(junctions.length));
+        }
+        return Junctions({count: uint8(junctions.length), items: junctions});
+    }
+
+    /// @notice Encodes a Junctions struct into bytes.
+    /// @param junctions The Junctions struct to encode.
+    /// @return SCALE-encoded byte sequence representing the Junctions.
+    function encode(
+        Junctions memory junctions
+    ) internal pure returns (bytes memory) {
+        if (junctions.count > 8) {
+            revert InvalidJunctionsCount(junctions.count);
+        }
+        if (junctions.items.length != junctions.count) {
+            revert InvalidJunctionsLength(junctions.count);
+        }
+
+        bytes memory encoded = abi.encodePacked(junctions.count);
+        for (uint8 i = 0; i < junctions.count; i++) {
+            encoded = abi.encodePacked(
+                encoded,
+                JunctionCodec.encode(junctions.items[i])
+            );
+        }
+        return encoded;
+    }
+
+    /// @notice Returns the number of bytes that a `Junctions` struct would occupy when SCALE-encoded.
+    /// @param data The byte sequence containing the encoded `Junctions`.
+    /// @param offset The starting index in `data` from which to calculate the encoded size of the `Junctions`.
+    /// @return The number of bytes that the `Junctions` struct would occupy when SCALE-encoded.
+    function encodedSizeAt(
+        bytes memory data,
+        uint256 offset
+    ) internal pure returns (uint256) {
+        if (offset >= data.length) {
+            revert InvalidJunctionsLength(0);
+        }
+        uint8 count = uint8(data[offset]);
+        if (count > 8) {
+            revert InvalidJunctionsCount(count);
+        }
+        uint256 size = 1; // for the count byte
+        uint256 pos = offset + 1;
+        for (uint8 i = 0; i < count; i++) {
+            uint256 inner = JunctionCodec.encodedSizeAt(data, pos);
+            size += inner;
+            pos += inner;
+        }
+        return size;
+    }
+
+    /// @notice Decodes bytes into a Junctions struct.
+    /// @param data The byte array to decode.
+    /// @return junctions The decoded Junctions struct.
+    function decode(
+        bytes memory data
+    ) internal pure returns (Junctions memory junctions, uint256 bytesRead) {
+        return decodeAt(data, 0);
+    }
+
+    /// @notice Decodes bytes into a Junctions struct starting from a specific offset.
+    /// @param data The byte array to decode.
+    /// @param offset The byte offset to start decoding from.
+    /// @return junctions The decoded Junctions struct.
+    /// @return bytesRead The total number of bytes read during decoding.
+    function decodeAt(
+        bytes memory data,
+        uint256 offset
+    ) internal pure returns (Junctions memory junctions, uint256 bytesRead) {
+        if (offset >= data.length) revert InvalidJunctionsLength(0);
+
+        uint8 count = uint8(data[offset]);
+        if (count > 8) revert InvalidJunctionsCount(count);
+
+        Junction[] memory items = new Junction[](count);
+        uint256 pos = offset + 1;
+
+        for (uint8 i = 0; i < count; i++) {
+            (Junction memory item, uint256 itemBytes) = JunctionCodec.decodeAt(
+                data,
+                pos
+            );
+            items[i] = item;
+            pos += itemBytes;
+        }
+
+        junctions = Junctions({count: count, items: items});
+        bytesRead = pos - offset;
+    }
+}

package/src/Xcm/v5/Location/Location.sol

@@ -0,0 +1,12 @@
+// SPDX-License-Identifier: Apache-2.0
+pragma solidity ^0.8.28;
+
+import {Junctions} from "../Junctions/Junctions.sol";
+
+/// @notice A relative path between state-bearing consensus systems.
+struct Location {
+    /// @custom:property The number of parent junctions at the beginning of this Location.
+    uint8 parents;
+    /// @custom:property The interior (i.e. non-parent) junctions that this Location contains. See `Junctions` struct for details.
+    Junctions interior;
+}

package/src/Xcm/v5/Location/LocationCodec.sol

@@ -0,0 +1,68 @@
+// SPDX-License-Identifier: Apache-2.0
+pragma solidity ^0.8.28;
+
+import {Junctions} from "../Junctions/Junctions.sol";
+import {JunctionsCodec} from "../Junctions/JunctionsCodec.sol";
+import {Location} from "./Location.sol";
+
+/// @title SCALE Codec for XCM v5 `Location`
+/// @notice SCALE-compliant encoder/decoder for the `Location` 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 LocationCodec {
+    error InvalidLocationLength();
+
+    /// @notice Encodes a `Location` struct into bytes.
+    /// @param location The `Location` struct to encode.
+    /// @return SCALE-encoded byte sequence representing the `Location`.
+    function encode(
+        Location memory location
+    ) internal pure returns (bytes memory) {
+        bytes memory encodedInterior = JunctionsCodec.encode(location.interior);
+        return abi.encodePacked(location.parents, encodedInterior);
+    }
+
+    /// @notice Returns the number of bytes that a `Location` struct would occupy when SCALE-encoded.
+    /// @param data The byte sequence containing the encoded `Location`.
+    /// @param offset The starting index in `data` from which to calculate the encoded size of the `Location`.
+    /// @return The number of bytes that the `Location` struct would occupy when SCALE-encoded.
+    function encodedSizeAt(
+        bytes memory data,
+        uint256 offset
+    ) internal pure returns (uint256) {
+        if (data.length < offset + 1) {
+            revert InvalidLocationLength();
+        }
+        uint256 interiorSize = JunctionsCodec.encodedSizeAt(data, offset + 1);
+        return 1 + interiorSize;
+    }
+
+    /// @notice Decodes a `Location` struct from bytes starting at the beginning of the data.
+    /// @param data The byte sequence containing the encoded `Location`.
+    /// @return location The decoded `Location` struct.
+    /// @return bytesRead The total number of bytes read from `data` to decode the `Location`.
+    function decode(
+        bytes memory data
+    ) internal pure returns (Location memory location, uint256 bytesRead) {
+        return decodeAt(data, 0);
+    }
+
+    /// @notice Decodes a `Location` struct from bytes starting at a given offset.
+    /// @param data The byte sequence containing the encoded `Location`.
+    /// @param offset The starting index in `data` from which to decode the `Location`.
+    /// @return location The decoded `Location` struct.
+    /// @return bytesRead The total number of bytes read from `data` to decode the `Location`.
+    function decodeAt(
+        bytes memory data,
+        uint256 offset
+    ) internal pure returns (Location memory location, uint256 bytesRead) {
+        if (data.length < offset + 1) {
+            revert InvalidLocationLength();
+        }
+        uint8 parents = uint8(data[offset]);
+        (Junctions memory interior, uint256 interiorBytesRead) = JunctionsCodec
+            .decodeAt(data, offset + 1);
+        location = Location({parents: parents, interior: interior});
+        bytesRead = 1 + interiorBytesRead;
+    }
+}

package/src/Xcm/v5/NetworkId/NetworkId.sol

@@ -0,0 +1,115 @@
+// SPDX-License-Identifier: Apache-2.0
+pragma solidity ^0.8.28;
+
+import {Compact} from "../../../Scale/Compact.sol";
+import {LittleEndianU64} from "../../../LittleEndian/LittleEndianU64.sol";
+
+/// @dev Discriminant for the different types of NetworkIds in XCM v5.
+enum NetworkIdType {
+    /// @custom:variant Network specified by the first 32 bytes of its genesis block.
+    ByGenesis,
+    /// @custom:variant Network defined by the first 32-bytes of the hash and number of some block it contains.
+    ByFork,
+    /// @custom:variant The Polkadot Relay Chain.
+    Polkadot,
+    /// @custom:variant The Kusama Relay Chain.
+    Kusama,
+    /// @custom:variant Reserved. Do not Use.
+    _Reserved4,
+    /// @custom:variant Reserved. Do not Use.
+    _Reserved5,
+    /// @custom:variant Reserved. Do not Use.
+    _Reserved6,
+    /// @custom:variant An Ethereum-based network, identified by its chain ID.
+    Ethereum,
+    /// @custom:variant The Bitcoin network.
+    BitcoinCore,
+    /// @custom:variant The Bitcoin Cash network.
+    BitcoinCash,
+    /// @custom:variant The Polkadot Bulletin Chain.
+    PolkadotBulletin
+}
+
+/// @notice Parameters for a `ByGenesis` network ID, containing the genesis block hash.
+struct ByForkParams {
+    /// @custom:property The block number of the block.
+    uint64 blockNumber;
+    /// @custom:property The hash of the block.
+    bytes32 blockHash;
+}
+
+/// @notice Parameters for an `Ethereum` network ID, containing the chain ID.
+struct EthereumParams {
+    /// @custom:property The chain ID of an Ethereum network.
+    uint64 chainId;
+}
+
+/// @notice Parameters for a `ByGenesis` network ID.
+struct ByGenesisParams {
+    /// @custom:property The 32-byte genesis block hash.
+    bytes32 genesisHash;
+}
+
+/// @dev Notice A global identifier of a data structure existing within consensus.
+struct NetworkId {
+    /// @custom:property The type of network ID, determining how to interpret the payload. See `NetworkIdType` enum for possible values.
+    NetworkIdType nType;
+    /// @custom:property The encoded payload containing the network identifier data, whose structure depends on the `nType`.
+    bytes payload;
+}
+
+using LittleEndianU64 for uint64;
+
+// ============ Factory Functions ============
+
+/// @notice Creates a `ByGenesis` network ID.
+/// @param params Parameters for the by-genesis variant.
+/// @return A `NetworkId` struct with type `ByGenesis` and the provided genesis hash as payload.
+function byGenesis(
+    ByGenesisParams memory params
+) pure returns (NetworkId memory) {
+    return
+        NetworkId({
+            nType: NetworkIdType.ByGenesis,
+            payload: abi.encodePacked(params.genesisHash)
+        });
+}
+
+/// @notice Creates a `ByFork` network ID.
+/// @param blockNumber The block number of the fork point.
+/// @param blockHash The 32-byte hash of the block at the fork point.
+/// @return A `NetworkId` struct with type `ByFork` and the provided block number and hash encoded in the payload.
+function byFork(
+    uint64 blockNumber,
+    bytes32 blockHash
+) pure returns (NetworkId memory) {
+    return
+        NetworkId({
+            nType: NetworkIdType.ByFork,
+            payload: abi.encodePacked(blockNumber.toLittleEndian(), blockHash)
+        });
+}
+
+/// @notice Creates a `Polkadot` network ID.
+/// @return A `NetworkId` struct with type `Polkadot` and an empty payload.
+function polkadot() pure returns (NetworkId memory) {
+    return NetworkId({nType: NetworkIdType.Polkadot, payload: ""});
+}
+
+/// @notice Creates a `Kusama` network ID.
+/// @return A `NetworkId` struct with type `Kusama` and an empty payload.
+function kusama() pure returns (NetworkId memory) {
+    return NetworkId({nType: NetworkIdType.Kusama, payload: ""});
+}
+
+/// @notice Creates an `Ethereum` network ID.
+/// @param params Parameters for the ethereum variant.
+function ethereum(
+    EthereumParams memory params
+) pure returns (NetworkId memory) {
+    return
+        NetworkId({
+            nType: NetworkIdType.Ethereum,
+            payload: Compact.encode(params.chainId)
+        });
+}