@fatsolutions/cairo-abi-codec 0.0.1

package/README.md

@@ -0,0 +1,157 @@
+# @fatsolutions/cairo-abi-codec
+
+Type-safe encode/decode for Cairo structs and enums to Starknet calldata.
+
+## Installation
+
+```bash
+pnpm add @fatsolutions/cairo-abi-codec
+```
+
+## Quick Start
+
+```typescript
+import { CairoOption, CairoOptionVariant, CairoCustomEnum } from "starknet";
+import { createTypedCodec, type AbiType } from "@fatsolutions/cairo-abi-codec";
+
+const abi = [
+  {
+    type: "struct",
+    name: "MyStruct",
+    members: [
+      { name: "id", type: "core::integer::u64" },
+      { name: "value", type: "core::felt252" },
+    ],
+  },
+] as const;
+
+const codec = createTypedCodec(abi);
+
+// Struct names are autocompleted, data is type-checked against the ABI
+type MyStruct = AbiType<typeof abi, "MyStruct">;
+
+const data: MyStruct = { id: 1n, value: 42n };
+const encoded = codec.encode("MyStruct", data);
+// => ['1', '42']
+
+const decoded = codec.decode("MyStruct", encoded);
+// => { id: 1n, value: 42n }
+```
+
+## Structs with Options
+
+Include the `Option` enum definition in your ABI:
+
+```typescript
+const abi = [
+  {
+    type: "struct",
+    name: "MyStruct",
+    members: [
+      { name: "id", type: "core::integer::u64" },
+      { name: "maybe_value", type: "core::option::Option::<core::integer::u64>" },
+    ],
+  },
+  {
+    type: "enum",
+    name: "core::option::Option::<core::integer::u64>",
+    variants: [
+      { name: "Some", type: "core::integer::u64" },
+      { name: "None", type: "()" },
+    ],
+  },
+] as const;
+
+const codec = createTypedCodec(abi);
+
+// AbiType infers: { id: bigint; maybe_value: CairoOption<bigint> }
+const data = {
+  id: 1n,
+  maybe_value: new CairoOption(CairoOptionVariant.Some, 42n),
+};
+
+codec.encode("MyStruct", data);
+// => ['1', '0', '42']
+```
+
+## Enums
+
+Custom enums encode/decode as `CairoCustomEnum`:
+
+```typescript
+const abi = [
+  {
+    type: "enum",
+    name: "Action",
+    variants: [
+      { name: "Move", type: "core::integer::u64" },
+      { name: "Stop", type: "()" },
+    ],
+  },
+] as const;
+
+const codec = createTypedCodec(abi);
+
+const encoded = codec.encode("Action", new CairoCustomEnum({ Move: 42n }));
+// => ['0', '42']
+
+const decoded = codec.decode("Action", encoded);
+decoded.activeVariant(); // => 'Move'
+decoded.unwrap();        // => 42n
+```
+
+## ContractAddress
+
+Decoded `ContractAddress` fields are automatically formatted as `0x`-prefixed, zero-padded 64-char hex strings. This applies in all positions: top-level struct members, nested structs, Options, Arrays, and custom enum variants.
+
+```typescript
+const decoded = codec.decode("Transfer", calldata);
+decoded.sender; // => '0x049d36570d4e46f48e99674bd3fcc84644ddd6b96f7c741b1562b82f9e004dc7'
+```
+
+## ABI Narrowing
+
+Use `narrowAbi` to filter a full contract ABI down to specific types, preserving type information:
+
+```typescript
+import { narrowAbi, createTypedCodec } from "@fatsolutions/cairo-abi-codec";
+
+const subset = narrowAbi(fullContractAbi, ["MyStruct", "MyEnum"] as const);
+const codec = createTypedCodec(subset);
+```
+
+## API
+
+### `createTypedCodec(abi)`
+
+Creates a reusable codec with `encode` and `decode` methods. Best when encoding/decoding multiple types from the same ABI.
+
+### `encodeTyped(abi, typeName, data)`
+
+One-off encoding. Creates the codec internally.
+
+### `decodeTyped(abi, typeName, calldata)`
+
+One-off decoding. Creates the codec internally.
+
+### `AbiType<TAbi, TName>`
+
+Type utility to extract the TypeScript type for a struct or enum from the ABI.
+
+### `narrowAbi(abi, names)`
+
+Filters an ABI to only the named struct/enum entries, preserving the const tuple type.
+
+## Important Notes
+
+- **Use `as const`** on your ABI for type inference to work
+- Integer types (`u64`, `u128`, `u256`, `felt252`) resolve to `bigint`
+- `Option<T>` resolves to `CairoOption<T>`, custom enums to `CairoCustomEnum`
+- `ContractAddress` decodes to `0x`-prefixed hex strings (64 chars, zero-padded)
+
+## Build & Test
+
+```bash
+pnpm run build    # tsc -> dist/
+pnpm test         # node:test with --experimental-strip-types
+```

package/dist/encoder.d.ts

@@ -0,0 +1,32 @@
+import { type Abi } from "starknet";
+/**
+ * Encodes a Cairo struct to calldata without needing a full contract ABI.
+ *
+ * @param structAbi - Array of ABI type definitions (structs, enums) needed to encode the data
+ * @param structType - The name of the root struct type to encode
+ * @param data - The data to encode
+ * @returns Encoded calldata as string array
+ */
+export declare function encodeStruct(structAbi: Abi, structType: string, data: unknown): string[];
+/**
+ * Decodes calldata back into a structured object.
+ *
+ * @param structAbi - Array of ABI type definitions (structs, enums) needed to decode the data
+ * @param structType - The name of the root struct type to decode
+ * @param calldata - The encoded calldata string array
+ * @returns Decoded struct data
+ */
+export declare function decodeStruct(structAbi: Abi, structType: string, calldata: string[]): unknown;
+/**
+ * Creates a reusable encoder/decoder for a specific struct type.
+ * Useful when encoding/decoding multiple instances of the same struct.
+ */
+export declare function createStructCodec(structAbi: Abi, structType: string): {
+    encode(data: unknown): string[];
+    decode(calldata: string[]): unknown;
+};
+/**
+ * @deprecated Use `createStructCodec` instead.
+ */
+export declare function createStructEncoder(structAbi: Abi, structType: string): (data: unknown) => string[];
+//# sourceMappingURL=encoder.d.ts.map

package/dist/encoder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"encoder.d.ts","sourceRoot":"","sources":["../src/encoder.ts"],"names":[],"mappings":"AAAA,OAAO,EAAY,KAAK,GAAG,EAAgB,MAAM,UAAU,CAAC;AAqB5D;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAC1B,SAAS,EAAE,GAAG,EACd,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,OAAO,GACZ,MAAM,EAAE,CAGV;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAC1B,SAAS,EAAE,GAAG,EACd,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,EAAE,GACjB,OAAO,CAIT;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,GAAG,EAAE,UAAU,EAAE,MAAM;iBAInD,OAAO,GAAG,MAAM,EAAE;qBAGd,MAAM,EAAE,GAAG,OAAO;EAItC;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,GAAG,EAAE,UAAU,EAAE,MAAM,UAZrD,OAAO,KAAG,MAAM,EAAE,CAelC"}

package/dist/encoder.js

@@ -0,0 +1,67 @@
+import { CallData } from "starknet";
+function wrapAbi(structAbi, structType) {
+    return [
+        {
+            type: "interface",
+            name: "__Wrapper__",
+            items: [
+                {
+                    type: "function",
+                    name: "__encode__",
+                    inputs: [{ name: "data", type: structType }],
+                    outputs: [{ type: structType }],
+                    state_mutability: "external",
+                },
+            ],
+        },
+        ...structAbi,
+    ];
+}
+/**
+ * Encodes a Cairo struct to calldata without needing a full contract ABI.
+ *
+ * @param structAbi - Array of ABI type definitions (structs, enums) needed to encode the data
+ * @param structType - The name of the root struct type to encode
+ * @param data - The data to encode
+ * @returns Encoded calldata as string array
+ */
+export function encodeStruct(structAbi, structType, data) {
+    const callData = new CallData(wrapAbi(structAbi, structType));
+    return callData.compile("__encode__", [data]);
+}
+/**
+ * Decodes calldata back into a structured object.
+ *
+ * @param structAbi - Array of ABI type definitions (structs, enums) needed to decode the data
+ * @param structType - The name of the root struct type to decode
+ * @param calldata - The encoded calldata string array
+ * @returns Decoded struct data
+ */
+export function decodeStruct(structAbi, structType, calldata) {
+    const callData = new CallData(wrapAbi(structAbi, structType));
+    const result = callData.parse("__encode__", calldata);
+    return result;
+}
+/**
+ * Creates a reusable encoder/decoder for a specific struct type.
+ * Useful when encoding/decoding multiple instances of the same struct.
+ */
+export function createStructCodec(structAbi, structType) {
+    const callData = new CallData(wrapAbi(structAbi, structType));
+    return {
+        encode(data) {
+            return callData.compile("__encode__", [data]);
+        },
+        decode(calldata) {
+            return callData.parse("__encode__", calldata);
+        },
+    };
+}
+/**
+ * @deprecated Use `createStructCodec` instead.
+ */
+export function createStructEncoder(structAbi, structType) {
+    const codec = createStructCodec(structAbi, structType);
+    return codec.encode;
+}
+//# sourceMappingURL=encoder.js.map

package/dist/encoder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"encoder.js","sourceRoot":"","sources":["../src/encoder.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAA0B,MAAM,UAAU,CAAC;AAE5D,SAAS,OAAO,CAAC,SAAc,EAAE,UAAkB;IACjD,OAAO;QACL;YACE,IAAI,EAAE,WAAW;YACjB,IAAI,EAAE,aAAa;YACnB,KAAK,EAAE;gBACL;oBACE,IAAI,EAAE,UAAU;oBAChB,IAAI,EAAE,YAAY;oBAClB,MAAM,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC;oBAC5C,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC;oBAC/B,gBAAgB,EAAE,UAAU;iBAC7B;aACF;SACF;QACD,GAAG,SAAS;KACb,CAAC;AACJ,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,YAAY,CAC1B,SAAc,EACd,UAAkB,EAClB,IAAa;IAEb,MAAM,QAAQ,GAAG,IAAI,QAAQ,CAAC,OAAO,CAAC,SAAS,EAAE,UAAU,CAAC,CAAC,CAAC;IAC9D,OAAO,QAAQ,CAAC,OAAO,CAAC,YAAY,EAAE,CAAC,IAAI,CAAY,CAAa,CAAC;AACvE,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,YAAY,CAC1B,SAAc,EACd,UAAkB,EAClB,QAAkB;IAElB,MAAM,QAAQ,GAAG,IAAI,QAAQ,CAAC,OAAO,CAAC,SAAS,EAAE,UAAU,CAAC,CAAC,CAAC;IAC9D,MAAM,MAAM,GAAG,QAAQ,CAAC,KAAK,CAAC,YAAY,EAAE,QAAQ,CAAC,CAAC;IACtD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAAC,SAAc,EAAE,UAAkB;IAClE,MAAM,QAAQ,GAAG,IAAI,QAAQ,CAAC,OAAO,CAAC,SAAS,EAAE,UAAU,CAAC,CAAC,CAAC;IAE9D,OAAO;QACL,MAAM,CAAC,IAAa;YAClB,OAAO,QAAQ,CAAC,OAAO,CAAC,YAAY,EAAE,CAAC,IAAI,CAAY,CAAa,CAAC;QACvE,CAAC;QACD,MAAM,CAAC,QAAkB;YACvB,OAAO,QAAQ,CAAC,KAAK,CAAC,YAAY,EAAE,QAAQ,CAAC,CAAC;QAChD,CAAC;KACF,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,mBAAmB,CAAC,SAAc,EAAE,UAAkB;IACpE,MAAM,KAAK,GAAG,iBAAiB,CAAC,SAAS,EAAE,UAAU,CAAC,CAAC;IACvD,OAAO,KAAK,CAAC,MAAM,CAAC;AACtB,CAAC"}

package/dist/typed-encoder.d.ts

@@ -0,0 +1,52 @@
+import type { Abi, ExtractAbiStructNames, ExtractAbiEnumNames, StringToPrimitiveType } from "abi-wan-kanabi/kanabi";
+export type { Abi, ExtractAbiStructNames, ExtractAbiEnumNames } from "abi-wan-kanabi/kanabi";
+/** Union of all struct and enum type names in the ABI. */
+export type ExtractAbiTypeNames<TAbi extends Abi> = ExtractAbiStructNames<TAbi> | ExtractAbiEnumNames<TAbi>;
+export type ExtractAbiType<TAbi extends Abi, K extends ExtractAbiTypeNames<TAbi>> = Extract<TAbi[number], {
+    type: "struct" | "enum";
+    name: K;
+}>;
+export type FilterTuple<T extends readonly any[], Match> = T extends readonly [infer Head, ...infer Tail] ? Head extends Match ? [Head, ...FilterTuple<Tail, Match>] : FilterTuple<Tail, Match> : [];
+export type NarrowedAbi<TAbi extends Abi, TNames extends readonly ExtractAbiTypeNames<TAbi>[]> = FilterTuple<TAbi, {
+    name: TNames[number];
+}>;
+export declare function narrowAbi<TAbi extends Abi, const TNames extends readonly ExtractAbiTypeNames<TAbi>[]>(abi: TAbi, names: TNames): FilterTuple<TAbi, {
+    name: TNames[number];
+}>;
+/**
+ * Gets the TypeScript type for a struct or enum defined in the ABI.
+ * starknet.js configures abi-wan-kanabi to use CairoOption<T> for Options
+ * and CairoCustomEnum for custom enums via module declaration merging.
+ */
+export type AbiType<TAbi extends Abi, TName extends ExtractAbiTypeNames<TAbi>> = StringToPrimitiveType<TAbi, TName>;
+/** @deprecated Use `AbiType` instead. */
+export type StructType<TAbi extends Abi, TStructName extends ExtractAbiStructNames<TAbi>> = StringToPrimitiveType<TAbi, TStructName>;
+/**
+ * Creates a type-safe codec for structs and enums defined in an ABI.
+ * Uses abi-wan-kanabi for type inference.
+ *
+ * @example
+ * const codec = createTypedCodec(abi);
+ * const encoded = codec.encode("MyStruct", myData);
+ * const decoded = codec.decode("MyStruct", encoded);
+ * const enumEncoded = codec.encode("Direction", myEnum);
+ */
+export declare function createTypedCodec<TAbi extends Abi>(abi: TAbi): {
+    encode<TName extends ExtractAbiTypeNames<TAbi>>(typeName: TName, data: AbiType<TAbi, TName>): string[];
+    decode<TName extends ExtractAbiTypeNames<TAbi>>(typeName: TName, calldata: string[]): AbiType<TAbi, TName>;
+};
+/**
+ * One-off type-safe encoding.
+ */
+export declare function encodeTyped<TAbi extends Abi, TName extends ExtractAbiTypeNames<TAbi>>(abi: TAbi, typeName: TName, data: AbiType<TAbi, TName>): string[];
+/**
+ * One-off type-safe decoding.
+ */
+export declare function decodeTyped<TAbi extends Abi, TName extends ExtractAbiTypeNames<TAbi>>(abi: TAbi, typeName: TName, calldata: string[]): AbiType<TAbi, TName>;
+/** @deprecated Use `createTypedCodec` instead. */
+export declare const createTypedEncoder: typeof createTypedCodec;
+/** @deprecated Use `encodeTyped` instead. */
+export declare const encodeStructTyped: typeof encodeTyped;
+/** @deprecated Use `decodeTyped` instead. */
+export declare const decodeStructTyped: typeof decodeTyped;
+//# sourceMappingURL=typed-encoder.d.ts.map

package/dist/typed-encoder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"typed-encoder.d.ts","sourceRoot":"","sources":["../src/typed-encoder.ts"],"names":[],"mappings":"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"}

package/dist/typed-encoder.js

@@ -0,0 +1,190 @@
+import { CallData, CairoOption, CairoCustomEnum, CairoResult, } from "starknet";
+export function narrowAbi(abi, names) {
+    return abi.filter((item) => (item.type === "struct" || item.type === "enum") &&
+        names.includes(item.name));
+}
+// ============================================================================
+// Internal Helpers
+// ============================================================================
+function buildWrappedAbi(abi) {
+    return [
+        {
+            type: "interface",
+            name: "__Wrapper__",
+            items: [
+                {
+                    type: "function",
+                    name: "__codec__",
+                    inputs: [{ name: "data", type: "__PLACEHOLDER__" }],
+                    outputs: [{ type: "__PLACEHOLDER__" }],
+                    state_mutability: "external",
+                },
+            ],
+        },
+        ...abi,
+    ];
+}
+function patchAbi(wrappedAbi, structName) {
+    return wrappedAbi.map((item) => {
+        if (item.type === "interface" && item.name === "__Wrapper__") {
+            return {
+                ...item,
+                items: item.items.map((fn) => ({
+                    ...fn,
+                    inputs: [{ name: "data", type: structName }],
+                    outputs: [{ type: structName }],
+                })),
+            };
+        }
+        return item;
+    });
+}
+const ADDRESS_TYPES = new Set([
+    "core::starknet::contract_address::ContractAddress",
+    "core::starknet::eth_address::EthAddress",
+]);
+function toChecksumAddress(value) {
+    return "0x" + BigInt(value).toString(16).padStart(64, "0");
+}
+/**
+ * Build a lookup of struct and enum member/variant types from the ABI.
+ */
+function buildTypeMap(abi) {
+    const typeMap = new Map();
+    for (const entry of abi) {
+        if (entry.type === "struct" && "members" in entry) {
+            const members = new Map();
+            for (const m of entry.members) {
+                members.set(m.name, m.type);
+            }
+            typeMap.set(entry.name, { kind: "struct", members });
+        }
+        else if (entry.type === "enum" && "variants" in entry) {
+            const variants = new Map();
+            for (const v of entry.variants) {
+                variants.set(v.name, v.type);
+            }
+            typeMap.set(entry.name, { kind: "enum", variants });
+        }
+    }
+    return typeMap;
+}
+const OPTION_RE = /^core::option::Option::<(.+)>$/;
+const RESULT_RE = /^core::result::Result::<(.+),\s*(.+)>$/;
+const ARRAY_RE = /^core::array::(?:Array|Span)::<(.+)>$/;
+function extractInnerType(cairoType) {
+    let m = OPTION_RE.exec(cairoType);
+    if (m)
+        return { wrapper: "option", inner: [m[1]] };
+    m = RESULT_RE.exec(cairoType);
+    if (m)
+        return { wrapper: "result", inner: [m[1], m[2]] };
+    m = ARRAY_RE.exec(cairoType);
+    if (m)
+        return { wrapper: "array", inner: [m[1]] };
+    return null;
+}
+/**
+ * Recursively walk a decoded value and transform address fields
+ * from bigint/number to 0x-prefixed, zero-padded hex strings.
+ * Handles structs, Options, Results, CustomEnums, and arrays.
+ */
+function transformAddresses(value, cairoType, typeMap) {
+    // Direct address type
+    if (ADDRESS_TYPES.has(cairoType)) {
+        return toChecksumAddress(value);
+    }
+    // Generic wrappers: Option<T>, Result<T,E>, Array<T>
+    const generic = extractInnerType(cairoType);
+    if (generic) {
+        if (generic.wrapper === "option" && value instanceof CairoOption) {
+            if (value.isNone())
+                return value;
+            const inner = transformAddresses(value.unwrap(), generic.inner[0], typeMap);
+            return new CairoOption(0, inner); // 0 = Some
+        }
+        if (generic.wrapper === "result" && value instanceof CairoResult) {
+            if (value.isOk()) {
+                const inner = transformAddresses(value.unwrap(), generic.inner[0], typeMap);
+                return new CairoResult(0, inner); // 0 = Ok
+            }
+            const inner = transformAddresses(value.unwrap(), generic.inner[1], typeMap);
+            return new CairoResult(1, inner); // 1 = Err
+        }
+        if (generic.wrapper === "array" && Array.isArray(value)) {
+            return value.map((el) => transformAddresses(el, generic.inner[0], typeMap));
+        }
+    }
+    const info = typeMap.get(cairoType);
+    if (!info || typeof value !== "object" || value === null)
+        return value;
+    // Struct: transform each member
+    if (info.kind === "struct") {
+        const result = {};
+        for (const [key, val] of Object.entries(value)) {
+            const memberType = info.members.get(key);
+            result[key] = memberType ? transformAddresses(val, memberType, typeMap) : val;
+        }
+        return result;
+    }
+    // Custom enum (CairoCustomEnum): transform the active variant's data
+    if (info.kind === "enum" && value instanceof CairoCustomEnum) {
+        const active = value.activeVariant();
+        const variantType = info.variants.get(active);
+        if (variantType && variantType !== "()") {
+            const transformed = transformAddresses(value.unwrap(), variantType, typeMap);
+            return new CairoCustomEnum({ [active]: transformed });
+        }
+        return value;
+    }
+    return value;
+}
+// ============================================================================
+// Type-Safe Codec
+// ============================================================================
+/**
+ * Creates a type-safe codec for structs and enums defined in an ABI.
+ * Uses abi-wan-kanabi for type inference.
+ *
+ * @example
+ * const codec = createTypedCodec(abi);
+ * const encoded = codec.encode("MyStruct", myData);
+ * const decoded = codec.decode("MyStruct", encoded);
+ * const enumEncoded = codec.encode("Direction", myEnum);
+ */
+export function createTypedCodec(abi) {
+    const wrappedAbi = buildWrappedAbi(abi);
+    const typeMap = buildTypeMap(abi);
+    return {
+        encode(typeName, data) {
+            const patchedAbi = patchAbi(wrappedAbi, typeName);
+            const callData = new CallData(patchedAbi);
+            return callData.compile("__codec__", [data]);
+        },
+        decode(typeName, calldata) {
+            const patchedAbi = patchAbi(wrappedAbi, typeName);
+            const callData = new CallData(patchedAbi);
+            const raw = callData.parse("__codec__", calldata);
+            return transformAddresses(raw, typeName, typeMap);
+        },
+    };
+}
+/**
+ * One-off type-safe encoding.
+ */
+export function encodeTyped(abi, typeName, data) {
+    return createTypedCodec(abi).encode(typeName, data);
+}
+/**
+ * One-off type-safe decoding.
+ */
+export function decodeTyped(abi, typeName, calldata) {
+    return createTypedCodec(abi).decode(typeName, calldata);
+}
+/** @deprecated Use `createTypedCodec` instead. */
+export const createTypedEncoder = createTypedCodec;
+/** @deprecated Use `encodeTyped` instead. */
+export const encodeStructTyped = encodeTyped;
+/** @deprecated Use `decodeTyped` instead. */
+export const decodeStructTyped = decodeTyped;
+//# sourceMappingURL=typed-encoder.js.map

package/dist/typed-encoder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"typed-encoder.js","sourceRoot":"","sources":["../src/typed-encoder.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,QAAQ,EACR,WAAW,EACX,eAAe,EACf,WAAW,GAGZ,MAAM,UAAU,CAAC;AAmClB,MAAM,UAAU,SAAS,CAGvB,GAAS,EAAE,KAAa;IAExB,OAAO,GAAG,CAAC,MAAM,CACf,CAAC,IAAI,EAAgD,EAAE,CACrD,CAAC,IAAI,CAAC,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,IAAI,KAAK,MAAM,CAAC;QAC/C,KAA2B,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CACH,CAAC;AACpD,CAAC;AAmBD,+EAA+E;AAC/E,mBAAmB;AACnB,+EAA+E;AAE/E,SAAS,eAAe,CAAmB,GAAS;IAClD,OAAO;QACL;YACE,IAAI,EAAE,WAAoB;YAC1B,IAAI,EAAE,aAAa;YACnB,KAAK,EAAE;gBACL;oBACE,IAAI,EAAE,UAAmB;oBACzB,IAAI,EAAE,WAAW;oBACjB,MAAM,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,iBAAiB,EAAE,CAAC;oBACnD,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,iBAAiB,EAAE,CAAC;oBACtC,gBAAgB,EAAE,UAAmB;iBACtC;aACF;SACF;QACD,GAAG,GAAG;KACP,CAAC;AACJ,CAAC;AAED,SAAS,QAAQ,CACf,UAA8C,EAC9C,UAAkB;IAElB,OAAO,UAAU,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE;QAC7B,IAAI,IAAI,CAAC,IAAI,KAAK,WAAW,IAAI,IAAI,CAAC,IAAI,KAAK,aAAa,EAAE,CAAC;YAC7D,OAAO;gBACL,GAAG,IAAI;gBACP,KAAK,EAAE,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;oBAC7B,GAAG,EAAE;oBACL,MAAM,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC;oBAC5C,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC;iBAChC,CAAC,CAAC;aACJ,CAAC;QACJ,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC,CAAC,CAAC;AACL,CAAC;AAED,MAAM,aAAa,GAAG,IAAI,GAAG,CAAC;IAC5B,mDAAmD;IACnD,yCAAyC;CAC1C,CAAC,CAAC;AAEH,SAAS,iBAAiB,CAAC,KAA+B;IACxD,OAAO,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC;AAC7D,CAAC;AAMD;;GAEG;AACH,SAAS,YAAY,CAAC,GAAgB;IACpC,MAAM,OAAO,GAAG,IAAI,GAAG,EAAoB,CAAC;IAC5C,KAAK,MAAM,KAAK,IAAI,GAAG,EAAE,CAAC;QACxB,IAAI,KAAK,CAAC,IAAI,KAAK,QAAQ,IAAI,SAAS,IAAI,KAAK,EAAE,CAAC;YAClD,MAAM,OAAO,GAAG,IAAI,GAAG,EAAkB,CAAC;YAC1C,KAAK,MAAM,CAAC,IAAI,KAAK,CAAC,OAAO,EAAE,CAAC;gBAC9B,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;YAC9B,CAAC;YACD,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC,CAAC;QACvD,CAAC;aAAM,IAAI,KAAK,CAAC,IAAI,KAAK,MAAM,IAAI,UAAU,IAAI,KAAK,EAAE,CAAC;YACxD,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAkB,CAAC;YAC3C,KAAK,MAAM,CAAC,IAAI,KAAK,CAAC,QAAQ,EAAE,CAAC;gBAC/B,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;YAC/B,CAAC;YACD,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,CAAC;QACtD,CAAC;IACH,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,MAAM,SAAS,GAAG,gCAAgC,CAAC;AACnD,MAAM,SAAS,GAAG,wCAAwC,CAAC;AAC3D,MAAM,QAAQ,GAAG,uCAAuC,CAAC;AAEzD,SAAS,gBAAgB,CAAC,SAAiB;IACzC,IAAI,CAAC,GAAG,SAAS,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IAClC,IAAI,CAAC;QAAE,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IACnD,CAAC,GAAG,SAAS,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IAC9B,IAAI,CAAC;QAAE,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IACzD,CAAC,GAAG,QAAQ,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IAC7B,IAAI,CAAC;QAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IAClD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;GAIG;AACH,SAAS,kBAAkB,CACzB,KAAc,EACd,SAAiB,EACjB,OAA8B;IAE9B,sBAAsB;IACtB,IAAI,aAAa,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC;QACjC,OAAO,iBAAiB,CAAC,KAAiC,CAAC,CAAC;IAC9D,CAAC;IAED,qDAAqD;IACrD,MAAM,OAAO,GAAG,gBAAgB,CAAC,SAAS,CAAC,CAAC;IAC5C,IAAI,OAAO,EAAE,CAAC;QACZ,IAAI,OAAO,CAAC,OAAO,KAAK,QAAQ,IAAI,KAAK,YAAY,WAAW,EAAE,CAAC;YACjE,IAAI,KAAK,CAAC,MAAM,EAAE;gBAAE,OAAO,KAAK,CAAC;YACjC,MAAM,KAAK,GAAG,kBAAkB,CAAC,KAAK,CAAC,MAAM,EAAE,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;YAC5E,OAAO,IAAI,WAAW,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC,WAAW;QAC/C,CAAC;QACD,IAAI,OAAO,CAAC,OAAO,KAAK,QAAQ,IAAI,KAAK,YAAY,WAAW,EAAE,CAAC;YACjE,IAAI,KAAK,CAAC,IAAI,EAAE,EAAE,CAAC;gBACjB,MAAM,KAAK,GAAG,kBAAkB,CAAC,KAAK,CAAC,MAAM,EAAE,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;gBAC5E,OAAO,IAAI,WAAW,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC,SAAS;YAC7C,CAAC;YACD,MAAM,KAAK,GAAG,kBAAkB,CAAC,KAAK,CAAC,MAAM,EAAE,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;YAC5E,OAAO,IAAI,WAAW,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC,UAAU;QAC9C,CAAC;QACD,IAAI,OAAO,CAAC,OAAO,KAAK,OAAO,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;YACxD,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,kBAAkB,CAAC,EAAE,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC;QAC9E,CAAC;IACH,CAAC;IAED,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;IACpC,IAAI,CAAC,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IAEvE,gCAAgC;IAChC,IAAI,IAAI,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;QAC3B,MAAM,MAAM,GAA4B,EAAE,CAAC;QAC3C,KAAK,MAAM,CAAC,GAAG,EAAE,GAAG,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAgC,CAAC,EAAE,CAAC;YAC1E,MAAM,UAAU,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YACzC,MAAM,CAAC,GAAG,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,kBAAkB,CAAC,GAAG,EAAE,UAAU,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC;QAChF,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,qEAAqE;IACrE,IAAI,IAAI,CAAC,IAAI,KAAK,MAAM,IAAI,KAAK,YAAY,eAAe,EAAE,CAAC;QAC7D,MAAM,MAAM,GAAG,KAAK,CAAC,aAAa,EAAE,CAAC;QACrC,MAAM,WAAW,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QAC9C,IAAI,WAAW,IAAI,WAAW,KAAK,IAAI,EAAE,CAAC;YACxC,MAAM,WAAW,GAAG,kBAAkB,CAAC,KAAK,CAAC,MAAM,EAAE,EAAE,WAAW,EAAE,OAAO,CAAC,CAAC;YAC7E,OAAO,IAAI,eAAe,CAAC,EAAE,CAAC,MAAM,CAAC,EAAE,WAAW,EAAE,CAAC,CAAC;QACxD,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC;AAED,+EAA+E;AAC/E,kBAAkB;AAClB,+EAA+E;AAG/E;;;;;;;;;GASG;AACH,MAAM,UAAU,gBAAgB,CAAmB,GAAS;IAC1D,MAAM,UAAU,GAAG,eAAe,CAAC,GAAG,CAAC,CAAC;IACxC,MAAM,OAAO,GAAG,YAAY,CAAC,GAA6B,CAAC,CAAC;IAE5D,OAAO;QACL,MAAM,CACJ,QAAe,EACf,IAA0B;YAE1B,MAAM,UAAU,GAAG,QAAQ,CAAC,UAAU,EAAE,QAAQ,CAAC,CAAC;YAClD,MAAM,QAAQ,GAAG,IAAI,QAAQ,CAAC,UAAU,CAAC,CAAC;YAC1C,OAAO,QAAQ,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC,IAAI,CAAY,CAAa,CAAC;QACtE,CAAC;QAED,MAAM,CACJ,QAAe,EACf,QAAkB;YAElB,MAAM,UAAU,GAAG,QAAQ,CAAC,UAAU,EAAE,QAAQ,CAAC,CAAC;YAClD,MAAM,QAAQ,GAAG,IAAI,QAAQ,CAAC,UAAU,CAAC,CAAC;YAC1C,MAAM,GAAG,GAAG,QAAQ,CAAC,KAAK,CAAC,WAAW,EAAE,QAAQ,CAAC,CAAC;YAClD,OAAO,kBAAkB,CAAC,GAAG,EAAE,QAAQ,EAAE,OAAO,CAAyB,CAAC;QAC5E,CAAC;KACF,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,WAAW,CAGzB,GAAS,EAAE,QAAe,EAAE,IAA0B;IACtD,OAAO,gBAAgB,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;AACtD,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,WAAW,CAGzB,GAAS,EAAE,QAAe,EAAE,QAAkB;IAC9C,OAAO,gBAAgB,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;AAC1D,CAAC;AAED,kDAAkD;AAClD,MAAM,CAAC,MAAM,kBAAkB,GAAG,gBAAgB,CAAC;AACnD,6CAA6C;AAC7C,MAAM,CAAC,MAAM,iBAAiB,GAAG,WAAW,CAAC;AAC7C,6CAA6C;AAC7C,MAAM,CAAC,MAAM,iBAAiB,GAAG,WAAW,CAAC"}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@fatsolutions/cairo-abi-codec",
+  "version": "0.0.1",
+  "description": "Encode/decode arbitrary Cairo structs to calldata",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fatlabsxyz/cairo-abi-codec.git"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "type": "module",
+  "main": "dist/typed-encoder.js",
+  "types": "dist/typed-encoder.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/typed-encoder.d.ts",
+      "default": "./dist/typed-encoder.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "starknet",
+    "cairo",
+    "encoding",
+    "calldata",
+    "abi"
+  ],
+  "author": "",
+  "license": "ISC",
+  "devDependencies": {
+    "@changesets/cli": "^2.30.0",
+    "@tsconfig/node22": "^22.0.5",
+    "@types/node": "^25.5.0",
+    "typescript": "^6.0.2"
+  },
+  "dependencies": {
+    "abi-wan-kanabi": "^2.2.4",
+    "starknet": "^9.4.2"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "node --test --experimental-strip-types 'src/**/*.test.ts'",
+    "changeset": "changeset",
+    "changeset:publish": "changeset publish",
+    "changeset:version": "changeset version && pnpm install --ignore-scripts"
+  }
+}