@latticexyz/protocol-parser 0.0.0-indexing-20230707130424

package/src/decodeKeyTuple.test.ts

@@ -0,0 +1,37 @@
+import { describe, expect, it } from "vitest";
+import { decodeKeyTuple } from "./decodeKeyTuple";
+
+describe("decodeKeyTuple", () => {
+  it("can decode bool key tuple", () => {
+    expect(
+      decodeKeyTuple({ staticFields: ["bool"], dynamicFields: [] }, [
+        "0x0000000000000000000000000000000000000000000000000000000000000000",
+      ])
+    ).toStrictEqual([false]);
+    expect(
+      decodeKeyTuple({ staticFields: ["bool"], dynamicFields: [] }, [
+        "0x0000000000000000000000000000000000000000000000000000000000000001",
+      ])
+    ).toStrictEqual([true]);
+  });
+
+  it("can decode complex key tuple", () => {
+    expect(
+      decodeKeyTuple({ staticFields: ["uint256", "int32", "bytes16", "address", "bool", "int8"], dynamicFields: [] }, [
+        "0x000000000000000000000000000000000000000000000000000000000000002a",
+        "0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffd6",
+        "0x1234000000000000000000000000000000000000000000000000000000000000",
+        "0x000000000000000000000000ffffffffffffffffffffffffffffffffffffffff",
+        "0x0000000000000000000000000000000000000000000000000000000000000001",
+        "0x0000000000000000000000000000000000000000000000000000000000000003",
+      ])
+    ).toStrictEqual([
+      42n,
+      -42,
+      "0x12340000000000000000000000000000",
+      "0xFFfFfFffFFfffFFfFFfFFFFFffFFFffffFfFFFfF",
+      true,
+      3,
+    ]);
+  });
+});

package/src/decodeKeyTuple.ts

@@ -0,0 +1,11 @@
+import { Hex, decodeAbiParameters } from "viem";
+import { StaticPrimitiveType } from "@latticexyz/schema-type";
+import { Schema } from "./common";
+
+// key tuples are encoded in the same way as abi.encode, so we can decode them with viem
+
+export function decodeKeyTuple(keySchema: Schema, keyTuple: readonly Hex[]): StaticPrimitiveType[] {
+  return keyTuple.map(
+    (key, index) => decodeAbiParameters([{ type: keySchema.staticFields[index] }], key)[0] as StaticPrimitiveType
+  );
+}

package/src/decodeRecord.test.ts

@@ -0,0 +1,13 @@
+import { describe, expect, it } from "vitest";
+import { decodeRecord } from "./decodeRecord";
+
+describe("decodeRecord", () => {
+  it("can decode hex to record values", () => {
+    const schema = { staticFields: ["uint32", "uint128"], dynamicFields: ["uint32[]", "string"] } as const;
+    const values = decodeRecord(
+      schema,
+      "0x0000000100000000000000000000000000000002000000000000130000000008000000000b0000000000000000000000000000000000000300000004736f6d6520737472696e67"
+    );
+    expect(values).toStrictEqual([1, 2n, [3, 4], "some string"]);
+  });
+});

package/src/decodeRecord.ts

@@ -0,0 +1,61 @@
+import { StaticPrimitiveType, DynamicPrimitiveType, staticAbiTypeToByteLength } from "@latticexyz/schema-type";
+import { Hex, sliceHex } from "viem";
+import { Schema } from "./common";
+import { decodeDynamicField } from "./decodeDynamicField";
+import { decodeStaticField } from "./decodeStaticField";
+import { hexToPackedCounter } from "./hexToPackedCounter";
+import { staticDataLength } from "./staticDataLength";
+
+export function decodeRecord(schema: Schema, data: Hex): readonly (StaticPrimitiveType | DynamicPrimitiveType)[] {
+  const values: (StaticPrimitiveType | DynamicPrimitiveType)[] = [];
+
+  let bytesOffset = 0;
+  schema.staticFields.forEach((fieldType) => {
+    const fieldByteLength = staticAbiTypeToByteLength[fieldType];
+    const value = decodeStaticField(fieldType, sliceHex(data, bytesOffset, bytesOffset + fieldByteLength));
+    bytesOffset += fieldByteLength;
+    values.push(value);
+  });
+
+  // Warn user if static data length doesn't match the schema, because data corruption might be possible.
+  const schemaStaticDataLength = staticDataLength(schema.staticFields);
+  const actualStaticDataLength = bytesOffset;
+  if (actualStaticDataLength !== schemaStaticDataLength) {
+    console.warn(
+      "Decoded static data length does not match schema's expected static data length. Data may get corrupted. Is `getStaticByteLength` outdated?",
+      {
+        expectedLength: schemaStaticDataLength,
+        actualLength: actualStaticDataLength,
+        bytesOffset,
+      }
+    );
+  }
+
+  if (schema.dynamicFields.length > 0) {
+    const dataLayout = hexToPackedCounter(sliceHex(data, bytesOffset, bytesOffset + 32));
+    bytesOffset += 32;
+
+    schema.dynamicFields.forEach((fieldType, i) => {
+      const dataLength = dataLayout.fieldByteLengths[i];
+      const value = decodeDynamicField(fieldType, sliceHex(data, bytesOffset, bytesOffset + dataLength));
+      bytesOffset += dataLength;
+      values.push(value);
+    });
+
+    // Warn user if dynamic data length doesn't match the schema, because data corruption might be possible.
+    const actualDynamicDataLength = bytesOffset - 32 - actualStaticDataLength;
+    // TODO: refactor this so we don't break for bytes offsets >UINT40
+    if (BigInt(actualDynamicDataLength) !== dataLayout.totalByteLength) {
+      console.warn(
+        "Decoded dynamic data length does not match data layout's expected data length. Data may get corrupted. Did the data layout change?",
+        {
+          expectedLength: dataLayout.totalByteLength,
+          actualLength: actualDynamicDataLength,
+          bytesOffset,
+        }
+      );
+    }
+  }
+
+  return values;
+}

package/src/decodeStaticField.test-d.ts

@@ -0,0 +1,40 @@
+import { assertType, describe, it } from "vitest";
+import { Hex } from "viem";
+import { decodeStaticField } from "./decodeStaticField";
+
+describe("decodeStaticField", () => {
+  it("returns a boolean for bool ABI type", () => {
+    assertType<boolean>(decodeStaticField("bool", "0x"));
+  });
+
+  it("returns a number or bigint for uint ABI types", () => {
+    assertType<number>(decodeStaticField("uint8", "0x"));
+    assertType<number>(decodeStaticField("uint16", "0x"));
+    assertType<number>(decodeStaticField("uint32", "0x"));
+    assertType<number>(decodeStaticField("uint48", "0x"));
+    assertType<bigint>(decodeStaticField("uint56", "0x"));
+    assertType<bigint>(decodeStaticField("uint128", "0x"));
+    assertType<bigint>(decodeStaticField("uint256", "0x"));
+  });
+
+  it("returns a number or bigint for int ABI types", () => {
+    assertType<number>(decodeStaticField("int8", "0x"));
+    assertType<number>(decodeStaticField("int16", "0x"));
+    assertType<number>(decodeStaticField("int32", "0x"));
+    assertType<number>(decodeStaticField("int48", "0x"));
+    assertType<bigint>(decodeStaticField("int56", "0x"));
+    assertType<bigint>(decodeStaticField("int128", "0x"));
+    assertType<bigint>(decodeStaticField("int256", "0x"));
+  });
+
+  it("returns a hex for bytes ABI types", () => {
+    assertType<Hex>(decodeStaticField("bytes1", "0x"));
+    assertType<Hex>(decodeStaticField("bytes2", "0x"));
+    assertType<Hex>(decodeStaticField("bytes8", "0x"));
+    assertType<Hex>(decodeStaticField("bytes32", "0x"));
+  });
+
+  it("returns a hex for address ABI type", () => {
+    assertType<Hex>(decodeStaticField("address", "0x"));
+  });
+});

package/src/decodeStaticField.test.ts

@@ -0,0 +1,94 @@
+import { describe, expect, it } from "vitest";
+import { decodeStaticField } from "./decodeStaticField";
+
+describe("decodeStaticField", () => {
+  it("can decode bool", () => {
+    expect(decodeStaticField("bool", "0x00")).toBe(false);
+    expect(decodeStaticField("bool", "0x01")).toBe(true);
+
+    expect(() => decodeStaticField("bool", "0x0")).toThrow(
+      'Hex value "0x0" has length of 1, but expected length of 2 for bool type.'
+    );
+    expect(() => decodeStaticField("bool", "0x1")).toThrow(
+      'Hex value "0x1" has length of 1, but expected length of 2 for bool type.'
+    );
+    expect(() => decodeStaticField("bool", "0x000")).toThrow(
+      'Hex value "0x000" is an odd length (3). It must be an even length.'
+    );
+    expect(() => decodeStaticField("bool", "0x001")).toThrow(
+      'Hex value "0x001" is an odd length (3). It must be an even length.'
+    );
+    expect(() => decodeStaticField("bool", "0x0000")).toThrow(
+      'Hex value "0x0000" has length of 4, but expected length of 2 for bool type.'
+    );
+    expect(() => decodeStaticField("bool", "0x0001")).toThrow(
+      'Hex value "0x0001" has length of 4, but expected length of 2 for bool type.'
+    );
+  });
+
+  it("can decode uint8", () => {
+    expect(decodeStaticField("uint8", "0x00")).toBe(0);
+    expect(decodeStaticField("uint8", "0x01")).toBe(1);
+    expect(decodeStaticField("uint8", "0xff")).toBe(255);
+  });
+
+  it("can decode uint256", () => {
+    expect(decodeStaticField("uint256", "0x0000000000000000000000000000000000000000000000000000000000000000")).toBe(0n);
+    expect(decodeStaticField("uint256", "0x0000000000000000000000000000000000000000000000000000000000000001")).toBe(1n);
+    expect(decodeStaticField("uint256", "0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff")).toBe(
+      115792089237316195423570985008687907853269984665640564039457584007913129639935n
+    );
+    expect(decodeStaticField("uint256", "0xfffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffe")).toBe(
+      115792089237316195423570985008687907853269984665640564039457584007913129639934n
+    );
+  });
+
+  it("can decode int8", () => {
+    expect(decodeStaticField("int8", "0x00")).toBe(0);
+    expect(decodeStaticField("int8", "0x01")).toBe(1);
+    expect(decodeStaticField("int8", "0x7f")).toBe(127);
+    expect(decodeStaticField("int8", "0x80")).toBe(-128);
+    expect(decodeStaticField("int8", "0x81")).toBe(-127);
+    expect(decodeStaticField("int8", "0xff")).toBe(-1);
+  });
+
+  it("can decode int256", () => {
+    expect(decodeStaticField("int256", "0x0000000000000000000000000000000000000000000000000000000000000000")).toBe(0n);
+    expect(decodeStaticField("int256", "0x0000000000000000000000000000000000000000000000000000000000000001")).toBe(1n);
+    expect(decodeStaticField("int256", "0x7fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff")).toBe(
+      57896044618658097711785492504343953926634992332820282019728792003956564819967n
+    );
+    expect(decodeStaticField("int256", "0x8000000000000000000000000000000000000000000000000000000000000000")).toBe(
+      -57896044618658097711785492504343953926634992332820282019728792003956564819968n
+    );
+    expect(decodeStaticField("int256", "0x8000000000000000000000000000000000000000000000000000000000000001")).toBe(
+      -57896044618658097711785492504343953926634992332820282019728792003956564819967n
+    );
+    expect(decodeStaticField("int256", "0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff")).toBe(-1n);
+  });
+
+  it("can decode bytes", () => {
+    expect(decodeStaticField("bytes1", "0x01")).toBe("0x01");
+    expect(decodeStaticField("bytes2", "0x0001")).toBe("0x0001");
+    expect(decodeStaticField("bytes8", "0xff00ff00ff00ff00")).toBe("0xff00ff00ff00ff00");
+    expect(decodeStaticField("bytes32", "0x0000000000000000000000000000000000000000000000000000000000000001")).toBe(
+      "0x0000000000000000000000000000000000000000000000000000000000000001"
+    );
+  });
+
+  it("can decode address", () => {
+    expect(decodeStaticField("address", "0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266")).toBe(
+      "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266"
+    );
+    expect(decodeStaticField("address", "0xffffffffffffffffffffffffffffffffffffffff")).toBe(
+      "0xFFfFfFffFFfffFFfFFfFFFFFffFFFffffFfFFFfF"
+    );
+
+    expect(() => decodeStaticField("address", "0x00")).toThrow(
+      'Hex value "0x00" has length of 2, but expected length of 40 for address type.'
+    );
+    expect(() => decodeStaticField("address", "0xffffffffffffffffffffffffffffffffffffffffff")).toThrow(
+      'Hex value "0xffffffffffffffffffffffffffffffffffffffffff" has length of 42, but expected length of 40 for address type.'
+    );
+  });
+});

package/src/decodeStaticField.ts

@@ -0,0 +1,145 @@
+import { Hex, getAddress, hexToBigInt, hexToBool } from "viem";
+import { assertExhaustive } from "@latticexyz/common/utils";
+import {
+  StaticAbiType,
+  StaticAbiTypeToPrimitiveType,
+  staticAbiTypeToByteLength,
+  staticAbiTypeToDefaultValue,
+} from "@latticexyz/schema-type";
+import { InvalidHexLengthError, InvalidHexLengthForStaticFieldError } from "./errors";
+
+export function decodeStaticField<
+  TAbiType extends StaticAbiType,
+  TPrimitiveType extends StaticAbiTypeToPrimitiveType<TAbiType>
+>(abiType: TAbiType, data: Hex): TPrimitiveType {
+  if (data.length > 3 && data.length % 2 !== 0) {
+    throw new InvalidHexLengthError(data);
+  }
+
+  const dataSize = (data.length - 2) / 2;
+  if (dataSize !== staticAbiTypeToByteLength[abiType]) {
+    throw new InvalidHexLengthForStaticFieldError(abiType, data);
+  }
+
+  switch (abiType) {
+    case "uint8":
+    case "uint16":
+    case "uint24":
+    case "uint32":
+    case "uint40":
+    case "uint48":
+    case "uint56":
+    case "uint64":
+    case "uint72":
+    case "uint80":
+    case "uint88":
+    case "uint96":
+    case "uint104":
+    case "uint112":
+    case "uint120":
+    case "uint128":
+    case "uint136":
+    case "uint144":
+    case "uint152":
+    case "uint160":
+    case "uint168":
+    case "uint176":
+    case "uint184":
+    case "uint192":
+    case "uint200":
+    case "uint208":
+    case "uint216":
+    case "uint224":
+    case "uint232":
+    case "uint240":
+    case "uint248":
+    case "uint256":
+    case "int8":
+    case "int16":
+    case "int24":
+    case "int32":
+    case "int40":
+    case "int48":
+    case "int56":
+    case "int64":
+    case "int72":
+    case "int80":
+    case "int88":
+    case "int96":
+    case "int104":
+    case "int112":
+    case "int120":
+    case "int128":
+    case "int136":
+    case "int144":
+    case "int152":
+    case "int160":
+    case "int168":
+    case "int176":
+    case "int184":
+    case "int192":
+    case "int200":
+    case "int208":
+    case "int216":
+    case "int224":
+    case "int232":
+    case "int240":
+    case "int248":
+    case "int256": {
+      const value = hexToBigInt(data, { signed: abiType.startsWith("int") });
+      const defaultValueType = typeof staticAbiTypeToDefaultValue[abiType];
+      if (defaultValueType === "number") {
+        return Number(value) as TPrimitiveType;
+      }
+      if (defaultValueType === "bigint") {
+        return value as TPrimitiveType;
+      }
+      throw new Error(`Unexpected default value type (${defaultValueType}) for ABI type (${abiType})`);
+    }
+
+    case "bytes1":
+    case "bytes2":
+    case "bytes3":
+    case "bytes4":
+    case "bytes5":
+    case "bytes6":
+    case "bytes7":
+    case "bytes8":
+    case "bytes9":
+    case "bytes10":
+    case "bytes11":
+    case "bytes12":
+    case "bytes13":
+    case "bytes14":
+    case "bytes15":
+    case "bytes16":
+    case "bytes17":
+    case "bytes18":
+    case "bytes19":
+    case "bytes20":
+    case "bytes21":
+    case "bytes22":
+    case "bytes23":
+    case "bytes24":
+    case "bytes25":
+    case "bytes26":
+    case "bytes27":
+    case "bytes28":
+    case "bytes29":
+    case "bytes30":
+    case "bytes31":
+    case "bytes32": {
+      return data as TPrimitiveType;
+    }
+
+    case "bool": {
+      return hexToBool(data) as TPrimitiveType;
+    }
+
+    case "address": {
+      return getAddress(data) as TPrimitiveType;
+    }
+  }
+
+  return assertExhaustive(abiType, `Unsupported static ABI type: ${abiType}`);
+}

package/src/encodeField.ts

@@ -0,0 +1,17 @@
+import { SchemaAbiType, arrayAbiTypeToStaticAbiType, isArrayAbiType } from "@latticexyz/schema-type";
+import { AbiParameterToPrimitiveType } from "abitype";
+import { Hex, encodePacked } from "viem";
+
+export function encodeField<TSchemaAbiType extends SchemaAbiType>(
+  fieldType: TSchemaAbiType,
+  value: AbiParameterToPrimitiveType<{ type: TSchemaAbiType }>
+): Hex {
+  if (isArrayAbiType(fieldType) && Array.isArray(value)) {
+    const staticFieldType = arrayAbiTypeToStaticAbiType(fieldType);
+    return encodePacked(
+      value.map(() => staticFieldType),
+      value
+    );
+  }
+  return encodePacked([fieldType], [value]);
+}

package/src/encodeKeyTuple.test.ts

@@ -0,0 +1,39 @@
+import { describe, expect, it } from "vitest";
+import { encodeKeyTuple } from "./encodeKeyTuple";
+
+describe("encodeKeyTuple", () => {
+  it("can encode bool key tuple", () => {
+    expect(encodeKeyTuple({ staticFields: ["bool"], dynamicFields: [] }, [false])).toStrictEqual([
+      "0x0000000000000000000000000000000000000000000000000000000000000000",
+    ]);
+    expect(
+      encodeKeyTuple(
+        {
+          staticFields: ["bool"],
+          dynamicFields: [],
+        },
+        [true]
+      )
+    ).toStrictEqual(["0x0000000000000000000000000000000000000000000000000000000000000001"]);
+  });
+
+  it("can encode complex key tuple", () => {
+    expect(
+      encodeKeyTuple({ staticFields: ["uint256", "int32", "bytes16", "address", "bool", "int8"], dynamicFields: [] }, [
+        42n,
+        -42,
+        "0x12340000000000000000000000000000",
+        "0xFFfFfFffFFfffFFfFFfFFFFFffFFFffffFfFFFfF",
+        true,
+        3,
+      ])
+    ).toStrictEqual([
+      "0x000000000000000000000000000000000000000000000000000000000000002a",
+      "0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffd6",
+      "0x1234000000000000000000000000000000000000000000000000000000000000",
+      "0x000000000000000000000000ffffffffffffffffffffffffffffffffffffffff",
+      "0x0000000000000000000000000000000000000000000000000000000000000001",
+      "0x0000000000000000000000000000000000000000000000000000000000000003",
+    ]);
+  });
+});

package/src/encodeKeyTuple.ts

@@ -0,0 +1,7 @@
+import { StaticPrimitiveType } from "@latticexyz/schema-type";
+import { Hex, encodeAbiParameters } from "viem";
+import { Schema } from "./common";
+
+export function encodeKeyTuple(keySchema: Schema, keyTuple: StaticPrimitiveType[]): Hex[] {
+  return keyTuple.map((key, index) => encodeAbiParameters([{ type: keySchema.staticFields[index] }], [key]));
+}

package/src/encodeRecord.test.ts

@@ -0,0 +1,18 @@
+import { describe, expect, it } from "vitest";
+import { encodeRecord } from "./encodeRecord";
+
+describe("encodeRecord", () => {
+  it("can encode a schema and record values to hex", () => {
+    const schema = { staticFields: ["uint32", "uint128"], dynamicFields: ["uint32[]", "string"] } as const;
+    const hex = encodeRecord(schema, [1, 2n, [3, 4], "some string"]);
+    expect(hex).toBe(
+      "0x0000000100000000000000000000000000000002000000000000130000000008000000000b0000000000000000000000000000000000000300000004736f6d6520737472696e67"
+    );
+  });
+
+  it("should not include the packed dynamic lengths if there are no dynamic fields", () => {
+    const schema = { staticFields: ["uint32", "uint128"], dynamicFields: [] } as const;
+    const hex = encodeRecord(schema, [1, 2n]);
+    expect(hex).toBe("0x0000000100000000000000000000000000000002");
+  });
+});

package/src/encodeRecord.ts

@@ -0,0 +1,30 @@
+import { StaticPrimitiveType, DynamicPrimitiveType } from "@latticexyz/schema-type";
+import { Hex } from "viem";
+import { encodeField } from "./encodeField";
+import { Schema } from "./common";
+
+export function encodeRecord(schema: Schema, values: readonly (StaticPrimitiveType | DynamicPrimitiveType)[]): Hex {
+  const staticValues = values.slice(0, schema.staticFields.length) as readonly StaticPrimitiveType[];
+  const dynamicValues = values.slice(schema.staticFields.length) as readonly DynamicPrimitiveType[];
+
+  const staticData = staticValues
+    .map((value, i) => encodeField(schema.staticFields[i], value).replace(/^0x/, ""))
+    .join("");
+
+  if (schema.dynamicFields.length === 0) return `0x${staticData}`;
+
+  const dynamicDataItems = dynamicValues.map((value, i) =>
+    encodeField(schema.dynamicFields[i], value).replace(/^0x/, "")
+  );
+
+  const dynamicFieldByteLengths = dynamicDataItems.map((value) => value.length / 2);
+  const dynamicTotalByteLength = dynamicFieldByteLengths.reduce((total, length) => total + BigInt(length), 0n);
+
+  const dynamicData = dynamicDataItems.join("");
+
+  const packedCounter = `${encodeField("uint56", dynamicTotalByteLength).replace(/^0x/, "")}${dynamicFieldByteLengths
+    .map((length) => encodeField("uint40", length).replace(/^0x/, ""))
+    .join("")}`.padEnd(64, "0");
+
+  return `0x${staticData}${packedCounter}${dynamicData}`;
+}

package/src/errors.ts

@@ -0,0 +1,64 @@
+import { Hex } from "viem";
+import { MUDError } from "@latticexyz/common/errors";
+import { StaticAbiType, staticAbiTypeToByteLength } from "@latticexyz/schema-type";
+
+export class InvalidHexLengthError extends MUDError {
+  override name = "InvalidHexValueError";
+  constructor(value: Hex) {
+    super(`Hex value "${value}" is an odd length (${value.length - 2}). It must be an even length.`);
+  }
+}
+
+export class InvalidHexLengthForSchemaError extends MUDError {
+  override name = "InvalidHexLengthForSchemaError";
+  constructor(value: Hex) {
+    super(`Hex value "${value}" has length of ${value.length - 2}, but expected length of 64 for a schema.`);
+  }
+}
+
+export class InvalidHexLengthForPackedCounterError extends MUDError {
+  override name = "InvalidHexLengthForPackedCounterError";
+  constructor(value: Hex) {
+    super(`Hex value "${value}" has length of ${value.length - 2}, but expected length of 64 for a packed counter.`);
+  }
+}
+
+export class InvalidHexLengthForStaticFieldError extends MUDError {
+  override name = "InvalidHexLengthForStaticFieldError";
+  constructor(abiType: StaticAbiType, value: Hex) {
+    super(
+      `Hex value "${value}" has length of ${value.length - 2}, but expected length of ${
+        staticAbiTypeToByteLength[abiType] * 2
+      } for ${abiType} type.`
+    );
+  }
+}
+
+export class InvalidHexLengthForArrayFieldError extends MUDError {
+  override name = "InvalidHexLengthForArrayFieldError";
+  constructor(abiType: StaticAbiType, value: Hex) {
+    super(
+      `Hex value "${value}" has length of ${value.length - 2}, but expected a multiple of ${
+        staticAbiTypeToByteLength[abiType] * 2
+      } for ${abiType}[] type.`
+    );
+  }
+}
+
+export class SchemaStaticLengthMismatchError extends MUDError {
+  override name = "SchemaStaticLengthMismatchError";
+  constructor(schemaData: Hex, definedLength: number, summedLength: number) {
+    super(
+      `Schema "${schemaData}" static data length (${definedLength}) did not match the summed length of all static fields (${summedLength}). Is \`staticAbiTypeToByteLength\` up to date with Solidity schema types?`
+    );
+  }
+}
+
+export class PackedCounterLengthMismatchError extends MUDError {
+  override name = "PackedCounterLengthMismatchError";
+  constructor(packedCounterData: Hex, definedLength: bigint, summedLength: bigint) {
+    super(
+      `PackedCounter "${packedCounterData}" total bytes length (${definedLength}) did not match the summed length of all field byte lengths (${summedLength}).`
+    );
+  }
+}

package/src/hexToPackedCounter.test.ts

@@ -0,0 +1,34 @@
+import { describe, expect, it } from "vitest";
+import { hexToPackedCounter } from "./hexToPackedCounter";
+
+describe("hexToPackedCounter", () => {
+  it("decodes hex data to packed counter", () => {
+    expect(hexToPackedCounter("0x0000000000008000000000200000000020000000004000000000000000000000"))
+      .toMatchInlineSnapshot(`
+      {
+        "fieldByteLengths": [
+          32,
+          32,
+          64,
+          0,
+          0,
+        ],
+        "totalByteLength": 128n,
+      }
+    `);
+  });
+
+  it("throws if schema hex data is not bytes32", () => {
+    expect(() => hexToPackedCounter("0x01234")).toThrowErrorMatchingInlineSnapshot(
+      '"Hex value \\"0x01234\\" has length of 5, but expected length of 64 for a packed counter."'
+    );
+  });
+
+  it("throws if packed counter total byte length doesn't match summed byte length of fields", () => {
+    expect(() =>
+      hexToPackedCounter("0x0000000000004000000000200000000020000000004000000000000000000000")
+    ).toThrowErrorMatchingInlineSnapshot(
+      '"PackedCounter \\"0x0000000000004000000000200000000020000000004000000000000000000000\\" total bytes length (64) did not match the summed length of all field byte lengths (128)."'
+    );
+  });
+});

package/src/hexToPackedCounter.ts

@@ -0,0 +1,31 @@
+import { Hex, sliceHex } from "viem";
+import { decodeStaticField } from "./decodeStaticField";
+import { decodeDynamicField } from "./decodeDynamicField";
+import { InvalidHexLengthForPackedCounterError, PackedCounterLengthMismatchError } from "./errors";
+
+// Keep this logic in sync with PackedCounter.sol
+
+// - First 7 bytes (uint56) are used for the total byte length of the dynamic data
+// - The next 5 byte (uint40) sections are used for the byte length of each field, in the same order as the schema's dynamic fields
+
+// We use byte lengths rather than item counts so that, on chain, we can slice without having to get the schema first (and thus the field lengths of each dynamic type)
+
+export function hexToPackedCounter(data: Hex): {
+  totalByteLength: bigint;
+  fieldByteLengths: readonly number[];
+} {
+  if (data.length !== 66) {
+    throw new InvalidHexLengthForPackedCounterError(data);
+  }
+  const totalByteLength = decodeStaticField("uint56", sliceHex(data, 0, 7));
+
+  // TODO: use schema to make sure we only parse as many as we need (rather than zeroes at the end)?
+  const fieldByteLengths = decodeDynamicField("uint40[]", sliceHex(data, 7));
+
+  const summedLength = BigInt(fieldByteLengths.reduce((total, length) => total + length, 0));
+  if (summedLength !== totalByteLength) {
+    throw new PackedCounterLengthMismatchError(data, totalByteLength, summedLength);
+  }
+
+  return { totalByteLength, fieldByteLengths };
+}