@thru/abi-utils 0.1.36

package/dist/index.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Derives the ABI seed bytes from a program account pubkey.
+ *
+ * Algorithm:
+ * 1. Get program account bytes (32 bytes)
+ * 2. Append "_abi_account" suffix (12 bytes)
+ * 3. SHA256 hash the combined 44 bytes
+ * 4. Return the 32-byte hash as the seed
+ *
+ * @param programAccountBytes - The 32-byte program account public key
+ * @returns 32-byte seed for PDA derivation
+ */
+declare function deriveAbiSeed(programAccountBytes: Uint8Array): Promise<Uint8Array>;
+/**
+ * Derives a program address (PDA) from a seed and program ID.
+ *
+ * This implements the Thru PDA derivation algorithm:
+ * 1. Combine seed + program ID bytes
+ * 2. SHA256 hash the combined bytes
+ * 3. Return as the derived address
+ *
+ * @param seed - The 32-byte seed
+ * @param programId - The program ID bytes (32 bytes)
+ * @param ephemeral - Whether to derive an ephemeral address (affects prefix byte)
+ * @returns The derived 32-byte address
+ */
+declare function deriveProgramAddress(seed: Uint8Array, programId: Uint8Array, ephemeral?: boolean): Promise<Uint8Array>;
+/**
+ * Derives the ABI account address for a given program account.
+ *
+ * @param programAccount - The program account address (ta-prefixed string or 32-byte array)
+ * @param abiManagerProgramId - The ABI manager program ID (ta-prefixed string or 32-byte array)
+ * @param ephemeral - Whether to derive an ephemeral address
+ * @returns The derived ABI account address as a ta-prefixed string
+ */
+declare function deriveAbiAddress(programAccount: string | Uint8Array, abiManagerProgramId: string | Uint8Array, ephemeral?: boolean): Promise<string>;
+
+/**
+ * ABI account state values
+ */
+declare const ABI_STATE: {
+    readonly OPEN: 0;
+    readonly FINALIZED: 1;
+};
+type AbiAccountState = (typeof ABI_STATE)[keyof typeof ABI_STATE];
+/**
+ * Parsed header from an ABI account's on-chain data
+ */
+interface AbiAccountHeader {
+    /** The program meta account this ABI is associated with */
+    programMetaAccount: Uint8Array;
+    /** Revision number (incremented on each upgrade) */
+    revision: bigint;
+    /** Account state: OPEN (0) or FINALIZED (1) */
+    state: AbiAccountState;
+    /** Size of the ABI content in bytes */
+    contentSize: number;
+}
+/**
+ * Full ABI account data including parsed YAML content
+ */
+interface AbiAccountData extends AbiAccountHeader {
+    /** Raw ABI YAML content bytes */
+    contentBytes: Uint8Array;
+    /** ABI YAML content as string */
+    content: string;
+}
+
+/**
+ * Size of the ABI account header in bytes:
+ * - 32 bytes: program_meta_acc (pubkey)
+ * - 8 bytes: revision (u64)
+ * - 1 byte: state (u8)
+ * - 4 bytes: content_sz (u32)
+ * Total: 45 bytes
+ */
+declare const ABI_ACCOUNT_HEADER_SIZE: number;
+/**
+ * Parses the header from ABI account data.
+ *
+ * @param data - Raw account data bytes
+ * @returns Parsed header
+ * @throws If data is too small for the header
+ */
+declare function parseAbiAccountHeader(data: Uint8Array): AbiAccountHeader;
+/**
+ * Parses the full ABI account data including content.
+ *
+ * @param data - Raw account data bytes
+ * @returns Parsed header and content
+ * @throws If data is too small or content size exceeds available data
+ */
+declare function parseAbiAccountData(data: Uint8Array): AbiAccountData;
+
+export { ABI_ACCOUNT_HEADER_SIZE, ABI_STATE, type AbiAccountData, type AbiAccountHeader, type AbiAccountState, deriveAbiAddress, deriveAbiSeed, deriveProgramAddress, parseAbiAccountData, parseAbiAccountHeader };

package/dist/index.js

@@ -0,0 +1,94 @@
+// src/derivation.ts
+import { decodeAddress, encodeAddress } from "@thru/helpers";
+var ABI_SEED_SUFFIX = "_abi_account";
+async function deriveAbiSeed(programAccountBytes) {
+  if (programAccountBytes.length !== 32) {
+    throw new Error(`Expected 32-byte program account, got ${programAccountBytes.length} bytes`);
+  }
+  const suffixBytes = new TextEncoder().encode(ABI_SEED_SUFFIX);
+  const combined = new Uint8Array(programAccountBytes.length + suffixBytes.length);
+  combined.set(programAccountBytes, 0);
+  combined.set(suffixBytes, programAccountBytes.length);
+  const hashBuffer = await crypto.subtle.digest("SHA-256", combined);
+  return new Uint8Array(hashBuffer);
+}
+async function deriveProgramAddress(seed, programId, ephemeral = false) {
+  if (seed.length !== 32) {
+    throw new Error(`Expected 32-byte seed, got ${seed.length} bytes`);
+  }
+  if (programId.length !== 32) {
+    throw new Error(`Expected 32-byte program ID, got ${programId.length} bytes`);
+  }
+  const combined = new Uint8Array(seed.length + programId.length);
+  combined.set(seed, 0);
+  combined.set(programId, seed.length);
+  const hashBuffer = await crypto.subtle.digest("SHA-256", combined);
+  const result = new Uint8Array(hashBuffer);
+  if (ephemeral) {
+    result[0] = result[0] | 128;
+  } else {
+    result[0] = result[0] & 127;
+  }
+  return result;
+}
+async function deriveAbiAddress(programAccount, abiManagerProgramId, ephemeral = false) {
+  const programAccountBytes = typeof programAccount === "string" ? decodeAddress(programAccount) : programAccount;
+  const abiManagerBytes = typeof abiManagerProgramId === "string" ? decodeAddress(abiManagerProgramId) : abiManagerProgramId;
+  const seed = await deriveAbiSeed(programAccountBytes);
+  const abiAccountBytes = await deriveProgramAddress(seed, abiManagerBytes, ephemeral);
+  return encodeAddress(abiAccountBytes);
+}
+
+// src/types.ts
+var ABI_STATE = {
+  OPEN: 0,
+  FINALIZED: 1
+};
+
+// src/parser.ts
+var ABI_ACCOUNT_HEADER_SIZE = 32 + 8 + 1 + 4;
+function parseAbiAccountHeader(data) {
+  if (data.length < ABI_ACCOUNT_HEADER_SIZE) {
+    throw new Error(
+      `ABI account data too small: ${data.length} bytes, expected at least ${ABI_ACCOUNT_HEADER_SIZE}`
+    );
+  }
+  const view = new DataView(data.buffer, data.byteOffset, data.byteLength);
+  const programMetaAccount = data.slice(0, 32);
+  const revision = view.getBigUint64(32, true);
+  const stateRaw = data[40];
+  const state = stateRaw === ABI_STATE.FINALIZED ? ABI_STATE.FINALIZED : ABI_STATE.OPEN;
+  const contentSize = view.getUint32(41, true);
+  return {
+    programMetaAccount,
+    revision,
+    state,
+    contentSize
+  };
+}
+function parseAbiAccountData(data) {
+  const header = parseAbiAccountHeader(data);
+  const expectedSize = ABI_ACCOUNT_HEADER_SIZE + header.contentSize;
+  if (data.length < expectedSize) {
+    throw new Error(
+      `ABI account data incomplete: ${data.length} bytes, expected ${expectedSize} (header + ${header.contentSize} content bytes)`
+    );
+  }
+  const contentBytes = data.slice(ABI_ACCOUNT_HEADER_SIZE, ABI_ACCOUNT_HEADER_SIZE + header.contentSize);
+  const content = new TextDecoder().decode(contentBytes);
+  return {
+    ...header,
+    contentBytes,
+    content
+  };
+}
+export {
+  ABI_ACCOUNT_HEADER_SIZE,
+  ABI_STATE,
+  deriveAbiAddress,
+  deriveAbiSeed,
+  deriveProgramAddress,
+  parseAbiAccountData,
+  parseAbiAccountHeader
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/derivation.ts","../src/types.ts","../src/parser.ts"],"sourcesContent":["import { decodeAddress, encodeAddress } from \"@thru/helpers\";\n\n/**\n * Suffix appended to program account bytes for ABI seed derivation\n */\nconst ABI_SEED_SUFFIX = \"_abi_account\";\n\n/**\n * Derives the ABI seed bytes from a program account pubkey.\n *\n * Algorithm:\n * 1. Get program account bytes (32 bytes)\n * 2. Append \"_abi_account\" suffix (12 bytes)\n * 3. SHA256 hash the combined 44 bytes\n * 4. Return the 32-byte hash as the seed\n *\n * @param programAccountBytes - The 32-byte program account public key\n * @returns 32-byte seed for PDA derivation\n */\nexport async function deriveAbiSeed(programAccountBytes: Uint8Array): Promise<Uint8Array> {\n  if (programAccountBytes.length !== 32) {\n    throw new Error(`Expected 32-byte program account, got ${programAccountBytes.length} bytes`);\n  }\n\n  // Combine program account bytes with suffix\n  const suffixBytes = new TextEncoder().encode(ABI_SEED_SUFFIX);\n  const combined = new Uint8Array(programAccountBytes.length + suffixBytes.length);\n  combined.set(programAccountBytes, 0);\n  combined.set(suffixBytes, programAccountBytes.length);\n\n  // SHA256 hash\n  const hashBuffer = await crypto.subtle.digest(\"SHA-256\", combined);\n  return new Uint8Array(hashBuffer);\n}\n\n/**\n * Derives a program address (PDA) from a seed and program ID.\n *\n * This implements the Thru PDA derivation algorithm:\n * 1. Combine seed + program ID bytes\n * 2. SHA256 hash the combined bytes\n * 3. Return as the derived address\n *\n * @param seed - The 32-byte seed\n * @param programId - The program ID bytes (32 bytes)\n * @param ephemeral - Whether to derive an ephemeral address (affects prefix byte)\n * @returns The derived 32-byte address\n */\nexport async function deriveProgramAddress(\n  seed: Uint8Array,\n  programId: Uint8Array,\n  ephemeral: boolean = false\n): Promise<Uint8Array> {\n  if (seed.length !== 32) {\n    throw new Error(`Expected 32-byte seed, got ${seed.length} bytes`);\n  }\n  if (programId.length !== 32) {\n    throw new Error(`Expected 32-byte program ID, got ${programId.length} bytes`);\n  }\n\n  // Combine seed + program ID\n  const combined = new Uint8Array(seed.length + programId.length);\n  combined.set(seed, 0);\n  combined.set(programId, seed.length);\n\n  // SHA256 hash\n  const hashBuffer = await crypto.subtle.digest(\"SHA-256\", combined);\n  const result = new Uint8Array(hashBuffer);\n\n  // Set the ephemeral bit in the first byte if needed\n  // Ephemeral addresses have bit 0x80 set in the first byte\n  if (ephemeral) {\n    result[0] = result[0] | 0x80;\n  } else {\n    result[0] = result[0] & 0x7f;\n  }\n\n  return result;\n}\n\n/**\n * Derives the ABI account address for a given program account.\n *\n * @param programAccount - The program account address (ta-prefixed string or 32-byte array)\n * @param abiManagerProgramId - The ABI manager program ID (ta-prefixed string or 32-byte array)\n * @param ephemeral - Whether to derive an ephemeral address\n * @returns The derived ABI account address as a ta-prefixed string\n */\nexport async function deriveAbiAddress(\n  programAccount: string | Uint8Array,\n  abiManagerProgramId: string | Uint8Array,\n  ephemeral: boolean = false\n): Promise<string> {\n  // Convert string addresses to bytes\n  const programAccountBytes = typeof programAccount === \"string\"\n    ? decodeAddress(programAccount)\n    : programAccount;\n\n  const abiManagerBytes = typeof abiManagerProgramId === \"string\"\n    ? decodeAddress(abiManagerProgramId)\n    : abiManagerProgramId;\n\n  // Derive the seed\n  const seed = await deriveAbiSeed(programAccountBytes);\n\n  // Derive the PDA\n  const abiAccountBytes = await deriveProgramAddress(seed, abiManagerBytes, ephemeral);\n\n  // Encode as ta-prefixed address\n  return encodeAddress(abiAccountBytes);\n}\n","/**\n * ABI account state values\n */\nexport const ABI_STATE = {\n  OPEN: 0x00,\n  FINALIZED: 0x01,\n} as const;\n\nexport type AbiAccountState = (typeof ABI_STATE)[keyof typeof ABI_STATE];\n\n/**\n * Parsed header from an ABI account's on-chain data\n */\nexport interface AbiAccountHeader {\n  /** The program meta account this ABI is associated with */\n  programMetaAccount: Uint8Array;\n  /** Revision number (incremented on each upgrade) */\n  revision: bigint;\n  /** Account state: OPEN (0) or FINALIZED (1) */\n  state: AbiAccountState;\n  /** Size of the ABI content in bytes */\n  contentSize: number;\n}\n\n/**\n * Full ABI account data including parsed YAML content\n */\nexport interface AbiAccountData extends AbiAccountHeader {\n  /** Raw ABI YAML content bytes */\n  contentBytes: Uint8Array;\n  /** ABI YAML content as string */\n  content: string;\n}\n","import type { AbiAccountHeader, AbiAccountData, AbiAccountState } from \"./types\";\nimport { ABI_STATE } from \"./types\";\n\n/**\n * Size of the ABI account header in bytes:\n * - 32 bytes: program_meta_acc (pubkey)\n * - 8 bytes: revision (u64)\n * - 1 byte: state (u8)\n * - 4 bytes: content_sz (u32)\n * Total: 45 bytes\n */\nexport const ABI_ACCOUNT_HEADER_SIZE = 32 + 8 + 1 + 4;\n\n/**\n * Parses the header from ABI account data.\n *\n * @param data - Raw account data bytes\n * @returns Parsed header\n * @throws If data is too small for the header\n */\nexport function parseAbiAccountHeader(data: Uint8Array): AbiAccountHeader {\n  if (data.length < ABI_ACCOUNT_HEADER_SIZE) {\n    throw new Error(\n      `ABI account data too small: ${data.length} bytes, expected at least ${ABI_ACCOUNT_HEADER_SIZE}`\n    );\n  }\n\n  const view = new DataView(data.buffer, data.byteOffset, data.byteLength);\n\n  // program_meta_acc: bytes 0-31 (32 bytes)\n  const programMetaAccount = data.slice(0, 32);\n\n  // revision: bytes 32-39 (8 bytes, little-endian u64)\n  const revision = view.getBigUint64(32, true);\n\n  // state: byte 40 (1 byte)\n  const stateRaw = data[40];\n  const state: AbiAccountState = stateRaw === ABI_STATE.FINALIZED\n    ? ABI_STATE.FINALIZED\n    : ABI_STATE.OPEN;\n\n  // content_sz: bytes 41-44 (4 bytes, little-endian u32)\n  const contentSize = view.getUint32(41, true);\n\n  return {\n    programMetaAccount,\n    revision,\n    state,\n    contentSize,\n  };\n}\n\n/**\n * Parses the full ABI account data including content.\n *\n * @param data - Raw account data bytes\n * @returns Parsed header and content\n * @throws If data is too small or content size exceeds available data\n */\nexport function parseAbiAccountData(data: Uint8Array): AbiAccountData {\n  const header = parseAbiAccountHeader(data);\n\n  const expectedSize = ABI_ACCOUNT_HEADER_SIZE + header.contentSize;\n  if (data.length < expectedSize) {\n    throw new Error(\n      `ABI account data incomplete: ${data.length} bytes, expected ${expectedSize} (header + ${header.contentSize} content bytes)`\n    );\n  }\n\n  const contentBytes = data.slice(ABI_ACCOUNT_HEADER_SIZE, ABI_ACCOUNT_HEADER_SIZE + header.contentSize);\n  const content = new TextDecoder().decode(contentBytes);\n\n  return {\n    ...header,\n    contentBytes,\n    content,\n  };\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@thru/abi-utils",
+  "version": "0.1.36",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "dependencies": {
+    "@thru/helpers": "0.1.36"
+  },
+  "devDependencies": {
+    "@types/node": "^24.10.1",
+    "tsup": "^8.5.0",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.4"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest watch",
+    "clean": "rm -rf dist"
+  }
+}

package/src/derivation.ts

@@ -0,0 +1,111 @@
+import { decodeAddress, encodeAddress } from "@thru/helpers";
+
+/**
+ * Suffix appended to program account bytes for ABI seed derivation
+ */
+const ABI_SEED_SUFFIX = "_abi_account";
+
+/**
+ * Derives the ABI seed bytes from a program account pubkey.
+ *
+ * Algorithm:
+ * 1. Get program account bytes (32 bytes)
+ * 2. Append "_abi_account" suffix (12 bytes)
+ * 3. SHA256 hash the combined 44 bytes
+ * 4. Return the 32-byte hash as the seed
+ *
+ * @param programAccountBytes - The 32-byte program account public key
+ * @returns 32-byte seed for PDA derivation
+ */
+export async function deriveAbiSeed(programAccountBytes: Uint8Array): Promise<Uint8Array> {
+  if (programAccountBytes.length !== 32) {
+    throw new Error(`Expected 32-byte program account, got ${programAccountBytes.length} bytes`);
+  }
+
+  // Combine program account bytes with suffix
+  const suffixBytes = new TextEncoder().encode(ABI_SEED_SUFFIX);
+  const combined = new Uint8Array(programAccountBytes.length + suffixBytes.length);
+  combined.set(programAccountBytes, 0);
+  combined.set(suffixBytes, programAccountBytes.length);
+
+  // SHA256 hash
+  const hashBuffer = await crypto.subtle.digest("SHA-256", combined);
+  return new Uint8Array(hashBuffer);
+}
+
+/**
+ * Derives a program address (PDA) from a seed and program ID.
+ *
+ * This implements the Thru PDA derivation algorithm:
+ * 1. Combine seed + program ID bytes
+ * 2. SHA256 hash the combined bytes
+ * 3. Return as the derived address
+ *
+ * @param seed - The 32-byte seed
+ * @param programId - The program ID bytes (32 bytes)
+ * @param ephemeral - Whether to derive an ephemeral address (affects prefix byte)
+ * @returns The derived 32-byte address
+ */
+export async function deriveProgramAddress(
+  seed: Uint8Array,
+  programId: Uint8Array,
+  ephemeral: boolean = false
+): Promise<Uint8Array> {
+  if (seed.length !== 32) {
+    throw new Error(`Expected 32-byte seed, got ${seed.length} bytes`);
+  }
+  if (programId.length !== 32) {
+    throw new Error(`Expected 32-byte program ID, got ${programId.length} bytes`);
+  }
+
+  // Combine seed + program ID
+  const combined = new Uint8Array(seed.length + programId.length);
+  combined.set(seed, 0);
+  combined.set(programId, seed.length);
+
+  // SHA256 hash
+  const hashBuffer = await crypto.subtle.digest("SHA-256", combined);
+  const result = new Uint8Array(hashBuffer);
+
+  // Set the ephemeral bit in the first byte if needed
+  // Ephemeral addresses have bit 0x80 set in the first byte
+  if (ephemeral) {
+    result[0] = result[0] | 0x80;
+  } else {
+    result[0] = result[0] & 0x7f;
+  }
+
+  return result;
+}
+
+/**
+ * Derives the ABI account address for a given program account.
+ *
+ * @param programAccount - The program account address (ta-prefixed string or 32-byte array)
+ * @param abiManagerProgramId - The ABI manager program ID (ta-prefixed string or 32-byte array)
+ * @param ephemeral - Whether to derive an ephemeral address
+ * @returns The derived ABI account address as a ta-prefixed string
+ */
+export async function deriveAbiAddress(
+  programAccount: string | Uint8Array,
+  abiManagerProgramId: string | Uint8Array,
+  ephemeral: boolean = false
+): Promise<string> {
+  // Convert string addresses to bytes
+  const programAccountBytes = typeof programAccount === "string"
+    ? decodeAddress(programAccount)
+    : programAccount;
+
+  const abiManagerBytes = typeof abiManagerProgramId === "string"
+    ? decodeAddress(abiManagerProgramId)
+    : abiManagerProgramId;
+
+  // Derive the seed
+  const seed = await deriveAbiSeed(programAccountBytes);
+
+  // Derive the PDA
+  const abiAccountBytes = await deriveProgramAddress(seed, abiManagerBytes, ephemeral);
+
+  // Encode as ta-prefixed address
+  return encodeAddress(abiAccountBytes);
+}

package/src/index.ts

@@ -0,0 +1,4 @@
+export { deriveAbiAddress, deriveAbiSeed, deriveProgramAddress } from "./derivation";
+export type { AbiAccountHeader, AbiAccountData, AbiAccountState } from "./types";
+export { ABI_STATE } from "./types";
+export { parseAbiAccountHeader, parseAbiAccountData, ABI_ACCOUNT_HEADER_SIZE } from "./parser";

package/src/parser.ts

@@ -0,0 +1,78 @@
+import type { AbiAccountHeader, AbiAccountData, AbiAccountState } from "./types";
+import { ABI_STATE } from "./types";
+
+/**
+ * Size of the ABI account header in bytes:
+ * - 32 bytes: program_meta_acc (pubkey)
+ * - 8 bytes: revision (u64)
+ * - 1 byte: state (u8)
+ * - 4 bytes: content_sz (u32)
+ * Total: 45 bytes
+ */
+export const ABI_ACCOUNT_HEADER_SIZE = 32 + 8 + 1 + 4;
+
+/**
+ * Parses the header from ABI account data.
+ *
+ * @param data - Raw account data bytes
+ * @returns Parsed header
+ * @throws If data is too small for the header
+ */
+export function parseAbiAccountHeader(data: Uint8Array): AbiAccountHeader {
+  if (data.length < ABI_ACCOUNT_HEADER_SIZE) {
+    throw new Error(
+      `ABI account data too small: ${data.length} bytes, expected at least ${ABI_ACCOUNT_HEADER_SIZE}`
+    );
+  }
+
+  const view = new DataView(data.buffer, data.byteOffset, data.byteLength);
+
+  // program_meta_acc: bytes 0-31 (32 bytes)
+  const programMetaAccount = data.slice(0, 32);
+
+  // revision: bytes 32-39 (8 bytes, little-endian u64)
+  const revision = view.getBigUint64(32, true);
+
+  // state: byte 40 (1 byte)
+  const stateRaw = data[40];
+  const state: AbiAccountState = stateRaw === ABI_STATE.FINALIZED
+    ? ABI_STATE.FINALIZED
+    : ABI_STATE.OPEN;
+
+  // content_sz: bytes 41-44 (4 bytes, little-endian u32)
+  const contentSize = view.getUint32(41, true);
+
+  return {
+    programMetaAccount,
+    revision,
+    state,
+    contentSize,
+  };
+}
+
+/**
+ * Parses the full ABI account data including content.
+ *
+ * @param data - Raw account data bytes
+ * @returns Parsed header and content
+ * @throws If data is too small or content size exceeds available data
+ */
+export function parseAbiAccountData(data: Uint8Array): AbiAccountData {
+  const header = parseAbiAccountHeader(data);
+
+  const expectedSize = ABI_ACCOUNT_HEADER_SIZE + header.contentSize;
+  if (data.length < expectedSize) {
+    throw new Error(
+      `ABI account data incomplete: ${data.length} bytes, expected ${expectedSize} (header + ${header.contentSize} content bytes)`
+    );
+  }
+
+  const contentBytes = data.slice(ABI_ACCOUNT_HEADER_SIZE, ABI_ACCOUNT_HEADER_SIZE + header.contentSize);
+  const content = new TextDecoder().decode(contentBytes);
+
+  return {
+    ...header,
+    contentBytes,
+    content,
+  };
+}

package/src/types.ts

@@ -0,0 +1,33 @@
+/**
+ * ABI account state values
+ */
+export const ABI_STATE = {
+  OPEN: 0x00,
+  FINALIZED: 0x01,
+} as const;
+
+export type AbiAccountState = (typeof ABI_STATE)[keyof typeof ABI_STATE];
+
+/**
+ * Parsed header from an ABI account's on-chain data
+ */
+export interface AbiAccountHeader {
+  /** The program meta account this ABI is associated with */
+  programMetaAccount: Uint8Array;
+  /** Revision number (incremented on each upgrade) */
+  revision: bigint;
+  /** Account state: OPEN (0) or FINALIZED (1) */
+  state: AbiAccountState;
+  /** Size of the ABI content in bytes */
+  contentSize: number;
+}
+
+/**
+ * Full ABI account data including parsed YAML content
+ */
+export interface AbiAccountData extends AbiAccountHeader {
+  /** Raw ABI YAML content bytes */
+  contentBytes: Uint8Array;
+  /** ABI YAML content as string */
+  content: string;
+}

package/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "declaration": true,
+    "declarationMap": true,
+    "outDir": "./dist",
+    "rootDir": "./src"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}

package/tsup.config.ts

@@ -0,0 +1,9 @@
+import { defineConfig } from "tsup";
+
+export default defineConfig({
+  entry: ["src/index.ts"],
+  format: ["esm"],
+  dts: true,
+  clean: true,
+  sourcemap: true,
+});

package/vitest.config.ts

@@ -0,0 +1,7 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    passWithNoTests: true,
+  },
+});