@latticexyz/protocol-parser 2.0.0-alpha.1.222

package/src/errors.ts

@@ -0,0 +1,64 @@
+import { MUDError } from "@latticexyz/common/errors";
+import { Hex } from "viem";
+import { StaticAbiType, staticAbiTypeToByteLength } from "./staticAbiTypes";
+
+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: 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((a, b) => a + b, 0));
+  if (summedLength !== totalByteLength) {
+    throw new PackedCounterLengthMismatchError(data, totalByteLength, summedLength);
+  }
+
+  return { totalByteLength, fieldByteLengths };
+}

package/src/hexToSchema.test.ts

@@ -0,0 +1,40 @@
+import { describe, expect, it } from "vitest";
+import { hexToSchema } from "./hexToSchema";
+
+describe("hexToSchema", () => {
+  it("decodes schema hex data to schema", () => {
+    expect(hexToSchema("0x0001010060000000000000000000000000000000000000000000000000000000")).toStrictEqual({
+      staticDataLength: 1,
+      staticFields: ["bool"],
+      dynamicFields: [],
+      isEmpty: false,
+      schemaData: "0x0001010060000000000000000000000000000000000000000000000000000000",
+    });
+    expect(hexToSchema("0x0001010160c20000000000000000000000000000000000000000000000000000")).toStrictEqual({
+      staticDataLength: 1,
+      staticFields: ["bool"],
+      dynamicFields: ["bool[]"],
+      isEmpty: false,
+      schemaData: "0x0001010160c20000000000000000000000000000000000000000000000000000",
+    });
+    expect(hexToSchema("0x002402045f2381c3c4c500000000000000000000000000000000000000000000")).toStrictEqual({
+      staticDataLength: 36,
+      staticFields: ["bytes32", "int32"],
+      dynamicFields: ["uint256[]", "address[]", "bytes", "string"],
+      isEmpty: false,
+      schemaData: "0x002402045f2381c3c4c500000000000000000000000000000000000000000000",
+    });
+  });
+
+  it("throws if schema hex data is not bytes32", () => {
+    expect(() => hexToSchema("0x002502045f2381c3c4c5")).toThrow(
+      'Hex value "0x002502045f2381c3c4c5" has length of 20, but expected length of 64 for a schema.'
+    );
+  });
+
+  it("throws if schema static field lengths do not match", () => {
+    expect(() => hexToSchema("0x002502045f2381c3c4c500000000000000000000000000000000000000000000")).toThrow(
+      'Schema "0x002502045f2381c3c4c500000000000000000000000000000000000000000000" static data length (37) did not match the summed length of all static fields (36). Is `staticAbiTypeToByteLength` up to date with Solidity schema types?'
+    );
+  });
+});

package/src/hexToSchema.ts

@@ -0,0 +1,41 @@
+import { Hex, hexToNumber, sliceHex } from "viem";
+import { Schema } from "./common";
+import { StaticAbiType, staticAbiTypeToByteLength } from "./staticAbiTypes";
+import { DynamicAbiType } from "./dynamicAbiTypes";
+import { schemaAbiTypes } from "./schemaAbiTypes";
+import { InvalidHexLengthForSchemaError, SchemaStaticLengthMismatchError } from "./errors";
+
+export function hexToSchema(data: Hex): Schema {
+  if (data.length !== 66) {
+    throw new InvalidHexLengthForSchemaError(data);
+  }
+
+  const staticDataLength = hexToNumber(sliceHex(data, 0, 2));
+  const numStaticFields = hexToNumber(sliceHex(data, 2, 3));
+  const numDynamicFields = hexToNumber(sliceHex(data, 3, 4));
+  const staticFields: StaticAbiType[] = [];
+  const dynamicFields: DynamicAbiType[] = [];
+
+  for (let i = 4; i < 4 + numStaticFields; i++) {
+    const schemaTypeIndex = hexToNumber(sliceHex(data, i, i + 1));
+    staticFields.push(schemaAbiTypes[schemaTypeIndex] as StaticAbiType);
+  }
+  for (let i = 4 + numStaticFields; i < 4 + numStaticFields + numDynamicFields; i++) {
+    const schemaTypeIndex = hexToNumber(sliceHex(data, i, i + 1));
+    dynamicFields.push(schemaAbiTypes[schemaTypeIndex] as DynamicAbiType);
+  }
+
+  // validate static data length
+  const actualStaticDataLength = staticFields.reduce((acc, fieldType) => acc + staticAbiTypeToByteLength[fieldType], 0);
+  if (actualStaticDataLength !== staticDataLength) {
+    throw new SchemaStaticLengthMismatchError(data, staticDataLength, actualStaticDataLength);
+  }
+
+  return {
+    staticDataLength,
+    staticFields,
+    dynamicFields,
+    isEmpty: data === "0x",
+    schemaData: data,
+  };
+}

package/src/hexToTableSchema.ts

@@ -0,0 +1,14 @@
+import { Hex, sliceHex } from "viem";
+import { TableSchema } from "./common";
+import { hexToSchema } from "./hexToSchema";
+
+export function hexToTableSchema(data: Hex): TableSchema {
+  const valueSchema = hexToSchema(sliceHex(data, 0, 32));
+  const keySchema = hexToSchema(sliceHex(data, 32, 64));
+  return {
+    keySchema,
+    valueSchema,
+    isEmpty: data === "0x",
+    schemaData: data,
+  };
+}

package/src/index.ts

@@ -0,0 +1,14 @@
+export * from "./abiTypesToSchema";
+export * from "./abiTypesToSchemaData";
+export * from "./abiTypeToDefaultValue";
+export * from "./common";
+export * from "./decodeDynamicField";
+export * from "./decodeKeyTuple";
+export * from "./decodeStaticField";
+export * from "./dynamicAbiTypes";
+export * from "./errors";
+export * from "./hexToPackedCounter";
+export * from "./hexToSchema";
+export * from "./hexToTableSchema";
+export * from "./schemaAbiTypes";
+export * from "./staticAbiTypes";

package/src/schemaAbiTypes.ts

@@ -0,0 +1,211 @@
+import { AbiType } from "abitype";
+import { TupleSplit } from "./utils";
+
+// Keep this array in sync with SchemaType.sol enum
+
+export const schemaAbiTypes = [
+  "uint8",
+  "uint16",
+  "uint24",
+  "uint32",
+  "uint40",
+  "uint48",
+  "uint56",
+  "uint64",
+  "uint72",
+  "uint80",
+  "uint88",
+  "uint96",
+  "uint104",
+  "uint112",
+  "uint120",
+  "uint128",
+  "uint136",
+  "uint144",
+  "uint152",
+  "uint160",
+  "uint168",
+  "uint176",
+  "uint184",
+  "uint192",
+  "uint200",
+  "uint208",
+  "uint216",
+  "uint224",
+  "uint232",
+  "uint240",
+  "uint248",
+  "uint256",
+  "int8",
+  "int16",
+  "int24",
+  "int32",
+  "int40",
+  "int48",
+  "int56",
+  "int64",
+  "int72",
+  "int80",
+  "int88",
+  "int96",
+  "int104",
+  "int112",
+  "int120",
+  "int128",
+  "int136",
+  "int144",
+  "int152",
+  "int160",
+  "int168",
+  "int176",
+  "int184",
+  "int192",
+  "int200",
+  "int208",
+  "int216",
+  "int224",
+  "int232",
+  "int240",
+  "int248",
+  "int256",
+  "bytes1",
+  "bytes2",
+  "bytes3",
+  "bytes4",
+  "bytes5",
+  "bytes6",
+  "bytes7",
+  "bytes8",
+  "bytes9",
+  "bytes10",
+  "bytes11",
+  "bytes12",
+  "bytes13",
+  "bytes14",
+  "bytes15",
+  "bytes16",
+  "bytes17",
+  "bytes18",
+  "bytes19",
+  "bytes20",
+  "bytes21",
+  "bytes22",
+  "bytes23",
+  "bytes24",
+  "bytes25",
+  "bytes26",
+  "bytes27",
+  "bytes28",
+  "bytes29",
+  "bytes30",
+  "bytes31",
+  "bytes32",
+  "bool",
+  "address",
+  "uint8[]",
+  "uint16[]",
+  "uint24[]",
+  "uint32[]",
+  "uint40[]",
+  "uint48[]",
+  "uint56[]",
+  "uint64[]",
+  "uint72[]",
+  "uint80[]",
+  "uint88[]",
+  "uint96[]",
+  "uint104[]",
+  "uint112[]",
+  "uint120[]",
+  "uint128[]",
+  "uint136[]",
+  "uint144[]",
+  "uint152[]",
+  "uint160[]",
+  "uint168[]",
+  "uint176[]",
+  "uint184[]",
+  "uint192[]",
+  "uint200[]",
+  "uint208[]",
+  "uint216[]",
+  "uint224[]",
+  "uint232[]",
+  "uint240[]",
+  "uint248[]",
+  "uint256[]",
+  "int8[]",
+  "int16[]",
+  "int24[]",
+  "int32[]",
+  "int40[]",
+  "int48[]",
+  "int56[]",
+  "int64[]",
+  "int72[]",
+  "int80[]",
+  "int88[]",
+  "int96[]",
+  "int104[]",
+  "int112[]",
+  "int120[]",
+  "int128[]",
+  "int136[]",
+  "int144[]",
+  "int152[]",
+  "int160[]",
+  "int168[]",
+  "int176[]",
+  "int184[]",
+  "int192[]",
+  "int200[]",
+  "int208[]",
+  "int216[]",
+  "int224[]",
+  "int232[]",
+  "int240[]",
+  "int248[]",
+  "int256[]",
+  "bytes1[]",
+  "bytes2[]",
+  "bytes3[]",
+  "bytes4[]",
+  "bytes5[]",
+  "bytes6[]",
+  "bytes7[]",
+  "bytes8[]",
+  "bytes9[]",
+  "bytes10[]",
+  "bytes11[]",
+  "bytes12[]",
+  "bytes13[]",
+  "bytes14[]",
+  "bytes15[]",
+  "bytes16[]",
+  "bytes17[]",
+  "bytes18[]",
+  "bytes19[]",
+  "bytes20[]",
+  "bytes21[]",
+  "bytes22[]",
+  "bytes23[]",
+  "bytes24[]",
+  "bytes25[]",
+  "bytes26[]",
+  "bytes27[]",
+  "bytes28[]",
+  "bytes29[]",
+  "bytes30[]",
+  "bytes31[]",
+  "bytes32[]",
+  "bool[]",
+  "address[]",
+  "bytes",
+  "string",
+] as const satisfies readonly AbiType[];
+
+export type SchemaAbiType = (typeof schemaAbiTypes)[number];
+
+// These are defined here to keep the index position (98) consolidated, since we use it both in runtime code and type definition
+export const staticAbiTypes = schemaAbiTypes.slice(0, 98) as any as TupleSplit<typeof schemaAbiTypes, 98>[0];
+export const dynamicAbiTypes = schemaAbiTypes.slice(98) as any as TupleSplit<typeof schemaAbiTypes, 98>[1];

package/src/staticAbiTypes.test-d.ts

@@ -0,0 +1,58 @@
+import { describe, expectTypeOf, it } from "vitest";
+import { StaticAbiTypeToPrimitiveType } from "./staticAbiTypes";
+import { Hex } from "viem";
+
+describe("StaticAbiTypeToPrimitiveType", () => {
+  it("maps uint8 to number", () => {
+    expectTypeOf<StaticAbiTypeToPrimitiveType<"uint8">>().toBeNumber();
+  });
+  it("maps uint32 to number", () => {
+    expectTypeOf<StaticAbiTypeToPrimitiveType<"uint32">>().toBeNumber();
+  });
+  it("maps uint48 to number", () => {
+    expectTypeOf<StaticAbiTypeToPrimitiveType<"uint48">>().toBeNumber();
+  });
+  it("maps uint56 to number", () => {
+    expectTypeOf<StaticAbiTypeToPrimitiveType<"uint56">>().toMatchTypeOf<bigint>();
+  });
+  it("maps uint256 to number", () => {
+    expectTypeOf<StaticAbiTypeToPrimitiveType<"uint256">>().toMatchTypeOf<bigint>();
+  });
+
+  it("maps int8 to number", () => {
+    expectTypeOf<StaticAbiTypeToPrimitiveType<"int8">>().toBeNumber();
+  });
+  it("maps int32 to number", () => {
+    expectTypeOf<StaticAbiTypeToPrimitiveType<"int32">>().toBeNumber();
+  });
+  it("maps int48 to number", () => {
+    expectTypeOf<StaticAbiTypeToPrimitiveType<"int48">>().toBeNumber();
+  });
+  it("maps int56 to number", () => {
+    expectTypeOf<StaticAbiTypeToPrimitiveType<"int56">>().toMatchTypeOf<bigint>();
+  });
+  it("maps int256 to number", () => {
+    expectTypeOf<StaticAbiTypeToPrimitiveType<"int256">>().toMatchTypeOf<bigint>();
+  });
+
+  it("maps bytes1 to hex", () => {
+    expectTypeOf<StaticAbiTypeToPrimitiveType<"bytes1">>().toMatchTypeOf<Hex>();
+  });
+  it("maps bytes2 to hex", () => {
+    expectTypeOf<StaticAbiTypeToPrimitiveType<"bytes2">>().toMatchTypeOf<Hex>();
+  });
+  it("maps bytes8 to hex", () => {
+    expectTypeOf<StaticAbiTypeToPrimitiveType<"bytes8">>().toMatchTypeOf<Hex>();
+  });
+  it("maps bytes32 to hex", () => {
+    expectTypeOf<StaticAbiTypeToPrimitiveType<"bytes32">>().toMatchTypeOf<Hex>();
+  });
+
+  it("maps bool to boolean", () => {
+    expectTypeOf<StaticAbiTypeToPrimitiveType<"bool">>().toBeBoolean();
+  });
+
+  it("maps address to hex", () => {
+    expectTypeOf<StaticAbiTypeToPrimitiveType<"address">>().toMatchTypeOf<Hex>();
+  });
+});