@thru/abi-utils 0.1.38 → 0.2.1

package/dist/index.d.ts

@@ -1,39 +1,27 @@
 /**
- * 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
+ * Builds the ABI meta body for an official ABI (program account).
  */
-declare function deriveAbiSeed(programAccountBytes: Uint8Array): Promise<Uint8Array>;
+declare function abiMetaBodyForProgram(programBytes: Uint8Array): 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
+ * Derives the ABI meta seed from ABI meta kind + body.
+ */
+declare function deriveAbiMetaSeed(kind: number, body: Uint8Array): Promise<Uint8Array>;
+/**
+ * Derives the ABI account seed from ABI meta kind + body.
+ */
+declare function deriveAbiAccountSeed(kind: number, body: Uint8Array): Promise<Uint8Array>;
+/**
+ * Derives a program-defined account address (owner || ephemeral || seed).
  */
 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
+ * Derives the ABI meta account address (as a ta-prefixed string).
+ */
+declare function deriveAbiMetaAddress(kind: number, body: Uint8Array, abiManagerProgramId: string | Uint8Array, ephemeral?: boolean): Promise<string>;
+/**
+ * Derives the ABI account address (as a ta-prefixed string).
  */
-declare function deriveAbiAddress(programAccount: string | Uint8Array, abiManagerProgramId: string | Uint8Array, ephemeral?: boolean): Promise<string>;
+declare function deriveAbiAddress(kind: number, body: Uint8Array, abiManagerProgramId: string | Uint8Array, ephemeral?: boolean): Promise<string>;
 
 /**
  * ABI account state values
@@ -47,8 +35,8 @@ 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;
+    /** The ABI meta account this ABI is associated with */
+    abiMetaAccount: Uint8Array;
     /** Revision number (incremented on each upgrade) */
     revision: bigint;
     /** Account state: OPEN (0) or FINALIZED (1) */
@@ -68,7 +56,7 @@ interface AbiAccountData extends AbiAccountHeader {
 
 /**
  * Size of the ABI account header in bytes:
- * - 32 bytes: program_meta_acc (pubkey)
+ * - 32 bytes: abi_meta_acc (pubkey)
  * - 8 bytes: revision (u64)
  * - 1 byte: state (u8)
  * - 4 bytes: content_sz (u32)
@@ -92,4 +80,4 @@ declare function parseAbiAccountHeader(data: Uint8Array): AbiAccountHeader;
  */
 declare function parseAbiAccountData(data: Uint8Array): AbiAccountData;
 
-export { ABI_ACCOUNT_HEADER_SIZE, ABI_STATE, type AbiAccountData, type AbiAccountHeader, type AbiAccountState, deriveAbiAddress, deriveAbiSeed, deriveProgramAddress, parseAbiAccountData, parseAbiAccountHeader };
+export { ABI_ACCOUNT_HEADER_SIZE, ABI_STATE, type AbiAccountData, type AbiAccountHeader, type AbiAccountState, abiMetaBodyForProgram, deriveAbiAccountSeed, deriveAbiAddress, deriveAbiMetaAddress, deriveAbiMetaSeed, deriveProgramAddress, parseAbiAccountData, parseAbiAccountHeader };

package/dist/index.js

@@ -1,17 +1,42 @@
 // 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`);
+var ABI_META_BODY_SIZE = 96;
+var ABI_ACCOUNT_SUFFIX = "_abi_account";
+var ABI_ACCOUNT_SUFFIX_BYTES = new TextEncoder().encode(ABI_ACCOUNT_SUFFIX);
+function concatBytes(...chunks) {
+  const total = chunks.reduce((sum, chunk) => sum + chunk.length, 0);
+  const out = new Uint8Array(total);
+  let offset = 0;
+  for (const chunk of chunks) {
+    out.set(chunk, offset);
+    offset += chunk.length;
   }
-  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 out;
+}
+async function sha256Bytes(data) {
+  const hashBuffer = await crypto.subtle.digest("SHA-256", data);
   return new Uint8Array(hashBuffer);
 }
+function abiMetaBodyForProgram(programBytes) {
+  if (programBytes.length !== 32) {
+    throw new Error(`Expected 32-byte program account, got ${programBytes.length} bytes`);
+  }
+  const body = new Uint8Array(ABI_META_BODY_SIZE);
+  body.set(programBytes, 0);
+  return body;
+}
+async function deriveAbiMetaSeed(kind, body) {
+  if (body.length !== ABI_META_BODY_SIZE) {
+    throw new Error(`Expected ${ABI_META_BODY_SIZE}-byte ABI meta body, got ${body.length} bytes`);
+  }
+  return sha256Bytes(concatBytes(new Uint8Array([kind]), body));
+}
+async function deriveAbiAccountSeed(kind, body) {
+  if (body.length !== ABI_META_BODY_SIZE) {
+    throw new Error(`Expected ${ABI_META_BODY_SIZE}-byte ABI meta body, got ${body.length} bytes`);
+  }
+  return sha256Bytes(concatBytes(new Uint8Array([kind]), body, ABI_ACCOUNT_SUFFIX_BYTES));
+}
 async function deriveProgramAddress(seed, programId, ephemeral = false) {
   if (seed.length !== 32) {
     throw new Error(`Expected 32-byte seed, got ${seed.length} bytes`);
@@ -19,24 +44,20 @@ async function deriveProgramAddress(seed, programId, ephemeral = false) {
   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;
+  const flag = new Uint8Array([ephemeral ? 1 : 0]);
+  return sha256Bytes(concatBytes(programId, flag, seed));
+}
+async function deriveAbiMetaAddress(kind, body, abiManagerProgramId, ephemeral = false) {
+  const abiManagerBytes = typeof abiManagerProgramId === "string" ? decodeAddress(abiManagerProgramId) : abiManagerProgramId;
+  const seed = await deriveAbiMetaSeed(kind, body);
+  const addressBytes = await deriveProgramAddress(seed, abiManagerBytes, ephemeral);
+  return encodeAddress(addressBytes);
 }
-async function deriveAbiAddress(programAccount, abiManagerProgramId, ephemeral = false) {
-  const programAccountBytes = typeof programAccount === "string" ? decodeAddress(programAccount) : programAccount;
+async function deriveAbiAddress(kind, body, abiManagerProgramId, ephemeral = false) {
   const abiManagerBytes = typeof abiManagerProgramId === "string" ? decodeAddress(abiManagerProgramId) : abiManagerProgramId;
-  const seed = await deriveAbiSeed(programAccountBytes);
-  const abiAccountBytes = await deriveProgramAddress(seed, abiManagerBytes, ephemeral);
-  return encodeAddress(abiAccountBytes);
+  const seed = await deriveAbiAccountSeed(kind, body);
+  const addressBytes = await deriveProgramAddress(seed, abiManagerBytes, ephemeral);
+  return encodeAddress(addressBytes);
 }
 
 // src/types.ts
@@ -54,13 +75,13 @@ function parseAbiAccountHeader(data) {
     );
   }
   const view = new DataView(data.buffer, data.byteOffset, data.byteLength);
-  const programMetaAccount = data.slice(0, 32);
+  const abiMetaAccount = 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,
+    abiMetaAccount,
     revision,
     state,
     contentSize
@@ -85,8 +106,11 @@ function parseAbiAccountData(data) {
 export {
   ABI_ACCOUNT_HEADER_SIZE,
   ABI_STATE,
+  abiMetaBodyForProgram,
+  deriveAbiAccountSeed,
   deriveAbiAddress,
-  deriveAbiSeed,
+  deriveAbiMetaAddress,
+  deriveAbiMetaSeed,
   deriveProgramAddress,
   parseAbiAccountData,
   parseAbiAccountHeader

package/dist/index.js.map

@@ -1 +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":[]}
+{"version":3,"sources":["../src/derivation.ts","../src/types.ts","../src/parser.ts"],"sourcesContent":["import { decodeAddress, encodeAddress } from \"@thru/helpers\";\n\nconst ABI_META_BODY_SIZE = 96;\nconst ABI_ACCOUNT_SUFFIX = \"_abi_account\";\nconst ABI_ACCOUNT_SUFFIX_BYTES = new TextEncoder().encode(ABI_ACCOUNT_SUFFIX);\n\nfunction concatBytes(...chunks: Uint8Array[]): Uint8Array {\n  const total = chunks.reduce((sum, chunk) => sum + chunk.length, 0);\n  const out = new Uint8Array(total);\n  let offset = 0;\n  for (const chunk of chunks) {\n    out.set(chunk, offset);\n    offset += chunk.length;\n  }\n  return out;\n}\n\nasync function sha256Bytes(data: Uint8Array): Promise<Uint8Array> {\n  const hashBuffer = await crypto.subtle.digest(\"SHA-256\", data as BufferSource);\n  return new Uint8Array(hashBuffer);\n}\n\n/**\n * Builds the ABI meta body for an official ABI (program account).\n */\nexport function abiMetaBodyForProgram(programBytes: Uint8Array): Uint8Array {\n  if (programBytes.length !== 32) {\n    throw new Error(`Expected 32-byte program account, got ${programBytes.length} bytes`);\n  }\n  const body = new Uint8Array(ABI_META_BODY_SIZE);\n  body.set(programBytes, 0);\n  return body;\n}\n\n/**\n * Derives the ABI meta seed from ABI meta kind + body.\n */\nexport async function deriveAbiMetaSeed(kind: number, body: Uint8Array): Promise<Uint8Array> {\n  if (body.length !== ABI_META_BODY_SIZE) {\n    throw new Error(`Expected ${ABI_META_BODY_SIZE}-byte ABI meta body, got ${body.length} bytes`);\n  }\n  return sha256Bytes(concatBytes(new Uint8Array([kind]), body));\n}\n\n/**\n * Derives the ABI account seed from ABI meta kind + body.\n */\nexport async function deriveAbiAccountSeed(kind: number, body: Uint8Array): Promise<Uint8Array> {\n  if (body.length !== ABI_META_BODY_SIZE) {\n    throw new Error(`Expected ${ABI_META_BODY_SIZE}-byte ABI meta body, got ${body.length} bytes`);\n  }\n  return sha256Bytes(concatBytes(new Uint8Array([kind]), body, ABI_ACCOUNT_SUFFIX_BYTES));\n}\n\n/**\n * Derives a program-defined account address (owner || ephemeral || seed).\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  const flag = new Uint8Array([ephemeral ? 1 : 0]);\n  return sha256Bytes(concatBytes(programId, flag, seed));\n}\n\n/**\n * Derives the ABI meta account address (as a ta-prefixed string).\n */\nexport async function deriveAbiMetaAddress(\n  kind: number,\n  body: Uint8Array,\n  abiManagerProgramId: string | Uint8Array,\n  ephemeral: boolean = false\n): Promise<string> {\n  const abiManagerBytes = typeof abiManagerProgramId === \"string\"\n    ? decodeAddress(abiManagerProgramId)\n    : abiManagerProgramId;\n  const seed = await deriveAbiMetaSeed(kind, body);\n  const addressBytes = await deriveProgramAddress(seed, abiManagerBytes, ephemeral);\n  return encodeAddress(addressBytes);\n}\n\n/**\n * Derives the ABI account address (as a ta-prefixed string).\n */\nexport async function deriveAbiAddress(\n  kind: number,\n  body: Uint8Array,\n  abiManagerProgramId: string | Uint8Array,\n  ephemeral: boolean = false\n): Promise<string> {\n  const abiManagerBytes = typeof abiManagerProgramId === \"string\"\n    ? decodeAddress(abiManagerProgramId)\n    : abiManagerProgramId;\n  const seed = await deriveAbiAccountSeed(kind, body);\n  const addressBytes = await deriveProgramAddress(seed, abiManagerBytes, ephemeral);\n  return encodeAddress(addressBytes);\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 ABI meta account this ABI is associated with */\n  abiMetaAccount: 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: abi_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  // abi_meta_acc: bytes 0-31 (32 bytes)\n  const abiMetaAccount = 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    abiMetaAccount,\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

@@ -1,6 +1,6 @@
 {
   "name": "@thru/abi-utils",
-  "version": "0.1.38",
+  "version": "0.2.1",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -11,7 +11,7 @@
     }
   },
   "dependencies": {
-    "@thru/helpers": "0.1.38"
+    "@thru/helpers": "0.2.1"
   },
   "devDependencies": {
     "@types/node": "^24.10.1",
@@ -23,6 +23,7 @@
     "build": "tsup",
     "dev": "tsup --watch",
     "test": "vitest run",
+    "test:run": "vitest run",
     "test:watch": "vitest watch",
     "clean": "rm -rf dist"
   }

package/src/derivation.ts

@@ -1,50 +1,59 @@
 import { decodeAddress, encodeAddress } from "@thru/helpers";
 
+const ABI_META_BODY_SIZE = 96;
+const ABI_ACCOUNT_SUFFIX = "_abi_account";
+const ABI_ACCOUNT_SUFFIX_BYTES = new TextEncoder().encode(ABI_ACCOUNT_SUFFIX);
+
+function concatBytes(...chunks: Uint8Array[]): Uint8Array {
+  const total = chunks.reduce((sum, chunk) => sum + chunk.length, 0);
+  const out = new Uint8Array(total);
+  let offset = 0;
+  for (const chunk of chunks) {
+    out.set(chunk, offset);
+    offset += chunk.length;
+  }
+  return out;
+}
+
+async function sha256Bytes(data: Uint8Array): Promise<Uint8Array> {
+  const hashBuffer = await crypto.subtle.digest("SHA-256", data as BufferSource);
+  return new Uint8Array(hashBuffer);
+}
+
 /**
- * Suffix appended to program account bytes for ABI seed derivation
+ * Builds the ABI meta body for an official ABI (program account).
  */
-const ABI_SEED_SUFFIX = "_abi_account";
+export function abiMetaBodyForProgram(programBytes: Uint8Array): Uint8Array {
+  if (programBytes.length !== 32) {
+    throw new Error(`Expected 32-byte program account, got ${programBytes.length} bytes`);
+  }
+  const body = new Uint8Array(ABI_META_BODY_SIZE);
+  body.set(programBytes, 0);
+  return body;
+}
 
 /**
- * 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
+ * Derives the ABI meta seed from ABI meta kind + body.
  */
-export async function deriveAbiSeed(programAccountBytes: Uint8Array): Promise<Uint8Array> {
-  if (programAccountBytes.length !== 32) {
-    throw new Error(`Expected 32-byte program account, got ${programAccountBytes.length} bytes`);
+export async function deriveAbiMetaSeed(kind: number, body: Uint8Array): Promise<Uint8Array> {
+  if (body.length !== ABI_META_BODY_SIZE) {
+    throw new Error(`Expected ${ABI_META_BODY_SIZE}-byte ABI meta body, got ${body.length} bytes`);
   }
+  return sha256Bytes(concatBytes(new Uint8Array([kind]), body));
+}
 
-  // 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 the ABI account seed from ABI meta kind + body.
+ */
+export async function deriveAbiAccountSeed(kind: number, body: Uint8Array): Promise<Uint8Array> {
+  if (body.length !== ABI_META_BODY_SIZE) {
+    throw new Error(`Expected ${ABI_META_BODY_SIZE}-byte ABI meta body, got ${body.length} bytes`);
+  }
+  return sha256Bytes(concatBytes(new Uint8Array([kind]), body, ABI_ACCOUNT_SUFFIX_BYTES));
 }
 
 /**
- * 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
+ * Derives a program-defined account address (owner || ephemeral || seed).
  */
 export async function deriveProgramAddress(
   seed: Uint8Array,
@@ -58,54 +67,40 @@ export async function deriveProgramAddress(
     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;
-  }
+  const flag = new Uint8Array([ephemeral ? 1 : 0]);
+  return sha256Bytes(concatBytes(programId, flag, seed));
+}
 
-  return result;
+/**
+ * Derives the ABI meta account address (as a ta-prefixed string).
+ */
+export async function deriveAbiMetaAddress(
+  kind: number,
+  body: Uint8Array,
+  abiManagerProgramId: string | Uint8Array,
+  ephemeral: boolean = false
+): Promise<string> {
+  const abiManagerBytes = typeof abiManagerProgramId === "string"
+    ? decodeAddress(abiManagerProgramId)
+    : abiManagerProgramId;
+  const seed = await deriveAbiMetaSeed(kind, body);
+  const addressBytes = await deriveProgramAddress(seed, abiManagerBytes, ephemeral);
+  return encodeAddress(addressBytes);
 }
 
 /**
- * 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
+ * Derives the ABI account address (as a ta-prefixed string).
  */
 export async function deriveAbiAddress(
-  programAccount: string | Uint8Array,
+  kind: number,
+  body: 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);
+  const seed = await deriveAbiAccountSeed(kind, body);
+  const addressBytes = await deriveProgramAddress(seed, abiManagerBytes, ephemeral);
+  return encodeAddress(addressBytes);
 }

package/src/index.ts

@@ -1,4 +1,11 @@
-export { deriveAbiAddress, deriveAbiSeed, deriveProgramAddress } from "./derivation";
+export {
+  abiMetaBodyForProgram,
+  deriveAbiAddress,
+  deriveAbiAccountSeed,
+  deriveAbiMetaAddress,
+  deriveAbiMetaSeed,
+  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

@@ -3,7 +3,7 @@ import { ABI_STATE } from "./types";
 
 /**
  * Size of the ABI account header in bytes:
- * - 32 bytes: program_meta_acc (pubkey)
+ * - 32 bytes: abi_meta_acc (pubkey)
  * - 8 bytes: revision (u64)
  * - 1 byte: state (u8)
  * - 4 bytes: content_sz (u32)
@@ -27,8 +27,8 @@ export function parseAbiAccountHeader(data: Uint8Array): AbiAccountHeader {
 
   const view = new DataView(data.buffer, data.byteOffset, data.byteLength);
 
-  // program_meta_acc: bytes 0-31 (32 bytes)
-  const programMetaAccount = data.slice(0, 32);
+  // abi_meta_acc: bytes 0-31 (32 bytes)
+  const abiMetaAccount = data.slice(0, 32);
 
   // revision: bytes 32-39 (8 bytes, little-endian u64)
   const revision = view.getBigUint64(32, true);
@@ -43,7 +43,7 @@ export function parseAbiAccountHeader(data: Uint8Array): AbiAccountHeader {
   const contentSize = view.getUint32(41, true);
 
   return {
-    programMetaAccount,
+    abiMetaAccount,
     revision,
     state,
     contentSize,

package/src/types.ts

@@ -12,8 +12,8 @@ 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;
+  /** The ABI meta account this ABI is associated with */
+  abiMetaAccount: Uint8Array;
   /** Revision number (incremented on each upgrade) */
   revision: bigint;
   /** Account state: OPEN (0) or FINALIZED (1) */