@thru/thru-sdk 0.1.15 → 0.1.19

package/thru-ts-client-sdk/transactions/__tests__/TransactionBuilder.test.ts

@@ -0,0 +1,411 @@
+import { describe, it, expect } from "vitest";
+import { TransactionBuilder } from "../TransactionBuilder";
+import { Transaction } from "../Transaction";
+import { generateTestPubkey, generateTestAddress } from "../../__tests__/helpers/test-utils";
+import type { BuildTransactionParams } from "../types";
+
+describe("TransactionBuilder", () => {
+  const createBuilder = () => new TransactionBuilder();
+
+  const createMinimalParams = (): BuildTransactionParams => {
+    return {
+      feePayer: {
+        publicKey: generateTestPubkey(0x01),
+      },
+      program: generateTestPubkey(0x02),
+      header: {
+        fee: 1n,
+        nonce: 2n,
+        startSlot: 3n,
+      },
+    };
+  };
+
+  const createPrivateKey = (): Uint8Array => {
+    // Ed25519 private key is 32 bytes (seed), but we need to generate a valid one
+    // For testing, we'll use a 32-byte array
+    const privateKey = new Uint8Array(32);
+    privateKey.fill(0x42);
+    return privateKey;
+  };
+
+  describe("build", () => {
+    it("should build transaction with minimal params", () => {
+      const builder = createBuilder();
+      const params = createMinimalParams();
+      
+      const transaction = builder.build(params);
+      
+      expect(transaction).toBeInstanceOf(Transaction);
+      expect(transaction.feePayer).toEqual(params.feePayer.publicKey);
+      expect(transaction.program).toEqual(params.program);
+      expect(transaction.fee).toBe(params.header.fee);
+      expect(transaction.nonce).toBe(params.header.nonce);
+      expect(transaction.startSlot).toBe(params.header.startSlot);
+    });
+
+    it("should build transaction with all header fields", () => {
+      const builder = createBuilder();
+      const params: BuildTransactionParams = {
+        ...createMinimalParams(),
+        header: {
+          fee: 10n,
+          nonce: 20n,
+          startSlot: 30n,
+          expiryAfter: 100,
+          computeUnits: 300_000_000,
+          stateUnits: 10_000,
+          memoryUnits: 10_000,
+          flags: 1,
+        },
+      };
+      
+      const transaction = builder.build(params);
+      
+      expect(transaction.fee).toBe(10n);
+      expect(transaction.nonce).toBe(20n);
+      expect(transaction.startSlot).toBe(30n);
+      expect(transaction.expiryAfter).toBe(100);
+      expect(transaction.requestedComputeUnits).toBe(300_000_000);
+      expect(transaction.requestedStateUnits).toBe(10_000);
+      expect(transaction.requestedMemoryUnits).toBe(10_000);
+      expect(transaction.flags).toBe(1);
+    });
+
+    it("should accept program as Uint8Array", () => {
+      const builder = createBuilder();
+      const program = generateTestPubkey(0x02);
+      const params: BuildTransactionParams = {
+        ...createMinimalParams(),
+        program,
+      };
+      
+      const transaction = builder.build(params);
+      
+      expect(transaction.program).toEqual(program);
+    });
+
+    it("should accept program as ta- address string", () => {
+      const builder = createBuilder();
+      const programAddress = generateTestAddress(0x02);
+      const params: BuildTransactionParams = {
+        ...createMinimalParams(),
+        program: programAddress,
+      };
+      
+      const transaction = builder.build(params);
+      
+      expect(transaction.program.length).toBe(32);
+    });
+
+    it("should accept program as hex string", () => {
+      const builder = createBuilder();
+      const programBytes = generateTestPubkey(0x02);
+      const hexString = Array.from(programBytes)
+        .map(b => b.toString(16).padStart(2, "0"))
+        .join("");
+      const params: BuildTransactionParams = {
+        ...createMinimalParams(),
+        program: hexString,
+      };
+      
+      const transaction = builder.build(params);
+      
+      expect(transaction.program).toEqual(programBytes);
+    });
+
+    it("should normalize and sort accounts", () => {
+      const builder = createBuilder();
+      const account1 = generateTestPubkey(0x03);
+      const account2 = generateTestPubkey(0x04);
+      const account3 = generateTestPubkey(0x02);
+      
+      const params: BuildTransactionParams = {
+        ...createMinimalParams(),
+        accounts: {
+          readWriteAccounts: [account1, account2, account3],
+        },
+      };
+      
+      const transaction = builder.build(params);
+      
+      expect(transaction.readWriteAccounts).toHaveLength(3);
+      // Should be sorted
+      expect(transaction.readWriteAccounts[0]).toEqual(account3); // 0x02
+      expect(transaction.readWriteAccounts[1]).toEqual(account1); // 0x03
+      expect(transaction.readWriteAccounts[2]).toEqual(account2); // 0x04
+    });
+
+    it("should deduplicate accounts", () => {
+      const builder = createBuilder();
+      const account1 = generateTestPubkey(0x03);
+      const account1Duplicate = new Uint8Array(account1);
+      
+      const params: BuildTransactionParams = {
+        ...createMinimalParams(),
+        accounts: {
+          readWriteAccounts: [account1, account1Duplicate],
+        },
+      };
+      
+      const transaction = builder.build(params);
+      
+      expect(transaction.readWriteAccounts).toHaveLength(1);
+      expect(transaction.readWriteAccounts[0]).toEqual(account1);
+    });
+
+    it("should handle read-only accounts", () => {
+      const builder = createBuilder();
+      const readOnlyAccount = generateTestPubkey(0x05);
+      
+      const params: BuildTransactionParams = {
+        ...createMinimalParams(),
+        accounts: {
+          readOnlyAccounts: [readOnlyAccount],
+        },
+      };
+      
+      const transaction = builder.build(params);
+      
+      expect(transaction.readOnlyAccounts).toHaveLength(1);
+      expect(transaction.readOnlyAccounts[0]).toEqual(readOnlyAccount);
+    });
+
+    it("should handle both read-write and read-only accounts", () => {
+      const builder = createBuilder();
+      const rwAccount = generateTestPubkey(0x03);
+      const roAccount = generateTestPubkey(0x04);
+      
+      const params: BuildTransactionParams = {
+        ...createMinimalParams(),
+        accounts: {
+          readWriteAccounts: [rwAccount],
+          readOnlyAccounts: [roAccount],
+        },
+      };
+      
+      const transaction = builder.build(params);
+      
+      expect(transaction.readWriteAccounts).toHaveLength(1);
+      expect(transaction.readOnlyAccounts).toHaveLength(1);
+    });
+
+    it("should handle instruction data as Uint8Array", () => {
+      const builder = createBuilder();
+      const instructionData = new Uint8Array([0x01, 0x02, 0x03]);
+      
+      const params: BuildTransactionParams = {
+        ...createMinimalParams(),
+        instructionData,
+      };
+      
+      const transaction = builder.build(params);
+      
+      expect(transaction.instructionData).toEqual(instructionData);
+    });
+
+    it("should handle instruction data as hex string", () => {
+      const builder = createBuilder();
+      const instructionBytes = new Uint8Array([0x01, 0x02, 0x03]);
+      const hexString = Array.from(instructionBytes)
+        .map(b => b.toString(16).padStart(2, "0"))
+        .join("");
+      
+      const params: BuildTransactionParams = {
+        ...createMinimalParams(),
+        instructionData: hexString,
+      };
+      
+      const transaction = builder.build(params);
+      
+      expect(transaction.instructionData).toEqual(instructionBytes);
+    });
+
+    it("should set fee payer proof flag when proof is provided", () => {
+      const builder = createBuilder();
+      const proof = new Uint8Array(64);
+      proof.fill(0x42);
+      
+      const params: BuildTransactionParams = {
+        ...createMinimalParams(),
+        header: {
+          fee: 1n,
+          nonce: 2n,
+          startSlot: 3n,
+          flags: 0,
+        },
+        proofs: {
+          feePayerStateProof: proof,
+        },
+      };
+      
+      const transaction = builder.build(params);
+      
+      // Flag should be set (FLAG_HAS_FEE_PAYER_PROOF = 1 << 0 = 1)
+      expect(transaction.flags & 1).toBe(1);
+    });
+
+    it("should not set fee payer proof flag when proof is not provided", () => {
+      const builder = createBuilder();
+      const params: BuildTransactionParams = {
+        ...createMinimalParams(),
+        header: {
+          fee: 1n,
+          nonce: 2n,
+          startSlot: 3n,
+          flags: 0,
+        },
+      };
+      
+      const transaction = builder.build(params);
+      
+      expect(transaction.flags & 1).toBe(0);
+    });
+
+    it("should preserve custom flags when proof is provided", () => {
+      const builder = createBuilder();
+      const proof = new Uint8Array(64);
+      proof.fill(0x42);
+      
+      const params: BuildTransactionParams = {
+        ...createMinimalParams(),
+        header: {
+          fee: 1n,
+          nonce: 2n,
+          startSlot: 3n,
+          flags: 2, // Custom flag
+        },
+        proofs: {
+          feePayerStateProof: proof,
+        },
+      };
+      
+      const transaction = builder.build(params);
+      
+      // Should have both custom flag (2) and proof flag (1) = 3
+      expect(transaction.flags).toBe(3);
+    });
+
+    it("should store fee payer state proof", () => {
+      const builder = createBuilder();
+      const proof = new Uint8Array(64);
+      proof.fill(0x42);
+      
+      const params: BuildTransactionParams = {
+        ...createMinimalParams(),
+        proofs: {
+          feePayerStateProof: proof,
+        },
+      };
+      
+      const transaction = builder.build(params);
+      
+      expect(transaction.feePayerStateProof).toEqual(proof);
+    });
+
+    it("should store fee payer account meta raw", () => {
+      const builder = createBuilder();
+      const metaRaw = new Uint8Array(32);
+      metaRaw.fill(0x43);
+      
+      const params: BuildTransactionParams = {
+        ...createMinimalParams(),
+        proofs: {
+          feePayerAccountMetaRaw: metaRaw,
+        },
+      };
+      
+      const transaction = builder.build(params);
+      
+      expect(transaction.feePayerAccountMetaRaw).toEqual(metaRaw);
+    });
+  });
+
+  describe("buildAndSign", () => {
+    it("should build and sign transaction", async () => {
+      const builder = createBuilder();
+      const privateKey = createPrivateKey();
+      const publicKey = generateTestPubkey(0x01);
+      const params: BuildTransactionParams = {
+        feePayer: {
+          publicKey,
+          privateKey,
+        },
+        program: generateTestPubkey(0x02),
+        header: {
+          fee: 1n,
+          nonce: 2n,
+          startSlot: 3n,
+        },
+      };
+      
+      const result = await builder.buildAndSign(params);
+      
+      expect(result.transaction).toBeInstanceOf(Transaction);
+      expect(result.signature).toBeInstanceOf(Uint8Array);
+      expect(result.signature.length).toBe(64);
+      expect(result.rawTransaction).toBeInstanceOf(Uint8Array);
+      expect(result.rawTransaction.length).toBeGreaterThan(0);
+    });
+
+    it("should throw error when private key is missing", async () => {
+      const builder = createBuilder();
+      const params: BuildTransactionParams = {
+        ...createMinimalParams(),
+        // No privateKey
+      };
+      
+      await expect(builder.buildAndSign(params)).rejects.toThrow(
+        "Fee payer private key is required to sign the transaction"
+      );
+    });
+
+    it("should include signature in raw transaction", async () => {
+      const builder = createBuilder();
+      const privateKey = createPrivateKey();
+      const publicKey = generateTestPubkey(0x01);
+      const params: BuildTransactionParams = {
+        feePayer: {
+          publicKey,
+          privateKey,
+        },
+        program: generateTestPubkey(0x02),
+        header: {
+          fee: 1n,
+          nonce: 2n,
+          startSlot: 3n,
+        },
+      };
+      
+      const result = await builder.buildAndSign(params);
+      
+      // Signature should be in first 64 bytes of raw transaction
+      const signatureInRaw = result.rawTransaction.slice(0, 64);
+      expect(signatureInRaw).toEqual(result.signature);
+    });
+
+    it("should create valid wire format", async () => {
+      const builder = createBuilder();
+      const privateKey = createPrivateKey();
+      const publicKey = generateTestPubkey(0x01);
+      const params: BuildTransactionParams = {
+        feePayer: {
+          publicKey,
+          privateKey,
+        },
+        program: generateTestPubkey(0x02),
+        header: {
+          fee: 1n,
+          nonce: 2n,
+          startSlot: 3n,
+        },
+      };
+      
+      const result = await builder.buildAndSign(params);
+      
+      // Should have at least header size (176 bytes)
+      expect(result.rawTransaction.length).toBeGreaterThanOrEqual(176);
+    });
+  });
+});
+

package/thru-ts-client-sdk/transactions/__tests__/utils.test.ts

@@ -0,0 +1,214 @@
+import { decodeAddress } from "@thru/helpers";
+import { describe, expect, it } from "vitest";
+import { generateTestAddress, generateTestPubkey } from "../../__tests__/helpers/test-utils";
+import {
+    normalizeAccountList,
+    parseAccountIdentifier,
+    parseInstructionData,
+    resolveProgramIdentifier,
+} from "../utils";
+
+describe("transaction utils", () => {
+  describe("normalizeAccountList", () => {
+    it("should return empty array for empty input", () => {
+      const result = normalizeAccountList([]);
+      expect(result).toEqual([]);
+    });
+
+    it("should return single account unchanged", () => {
+      const account = generateTestPubkey(0x01);
+      const result = normalizeAccountList([account]);
+      
+      expect(result).toHaveLength(1);
+      expect(result[0]).toEqual(account);
+    });
+
+    it("should deduplicate accounts", () => {
+      const account1 = generateTestPubkey(0x01);
+      const account2 = generateTestPubkey(0x02);
+      const account1Duplicate = new Uint8Array(account1);
+      
+      const result = normalizeAccountList([account1, account2, account1Duplicate]);
+      
+      expect(result).toHaveLength(2);
+      expect(result[0]).toEqual(account1);
+      expect(result[1]).toEqual(account2);
+    });
+
+    it("should sort accounts", () => {
+      const account1 = generateTestPubkey(0x02);
+      const account2 = generateTestPubkey(0x01);
+      const account3 = generateTestPubkey(0x03);
+      
+      const result = normalizeAccountList([account1, account2, account3]);
+      
+      expect(result).toHaveLength(3);
+      // Should be sorted
+      expect(result[0]).toEqual(account2); // 0x01
+      expect(result[1]).toEqual(account1); // 0x02
+      expect(result[2]).toEqual(account3); // 0x03
+    });
+
+    it("should throw error for too many accounts", () => {
+      const accounts = Array.from({ length: 1025 }, () => generateTestPubkey());
+      
+      expect(() => normalizeAccountList(accounts)).toThrow("Too many accounts provided: 1025 (max 1024)");
+    });
+
+    it("should throw error for invalid account length", () => {
+      const invalidAccount = new Uint8Array(31); // Should be 32
+      
+      expect(() => normalizeAccountList([invalidAccount])).toThrow("Account addresses must contain 32 bytes");
+    });
+  });
+
+  describe("resolveProgramIdentifier", () => {
+    it("should accept Uint8Array with 32 bytes", () => {
+      const program = generateTestPubkey(0x01);
+      const result = resolveProgramIdentifier(program);
+      
+      expect(result).toEqual(program);
+      expect(result).not.toBe(program); // Should be a copy
+    });
+
+    it("should accept ta- prefixed address string", () => {
+      const address = generateTestAddress(0x01);
+      const result = resolveProgramIdentifier(address);
+      
+      expect(result.length).toBe(32);
+      const decoded = decodeAddress(address);
+      expect(result).toEqual(decoded);
+    });
+
+    it("should accept hex string", () => {
+      const programBytes = generateTestPubkey(0x01);
+      const hexString = Array.from(programBytes)
+        .map(b => b.toString(16).padStart(2, "0"))
+        .join("");
+      
+      const result = resolveProgramIdentifier(hexString);
+      
+      expect(result.length).toBe(32);
+      expect(result).toEqual(programBytes);
+    });
+
+    it("should throw error for Uint8Array with wrong length", () => {
+      const invalidProgram = new Uint8Array(31);
+      
+      expect(() => resolveProgramIdentifier(invalidProgram)).toThrow("Program public key must contain 32 bytes");
+    });
+
+    it("should throw error for invalid string format", () => {
+      expect(() => resolveProgramIdentifier("invalid-format")).toThrow("Unsupported program identifier format");
+    });
+
+    it("should throw error for hex string with wrong length", () => {
+      const shortHex = "0123"; // Too short
+      
+      expect(() => resolveProgramIdentifier(shortHex)).toThrow("Hex-encoded program key must contain 32 bytes");
+    });
+  });
+
+  describe("parseAccountIdentifier", () => {
+    it("should accept Uint8Array with 32 bytes", () => {
+      const account = generateTestPubkey(0x01);
+      const result = parseAccountIdentifier(account, "testField");
+      
+      expect(result).toEqual(account);
+      expect(result).not.toBe(account); // Should be a copy
+    });
+
+    it("should accept ta- prefixed address string", () => {
+      const address = generateTestAddress(0x01);
+      const result = parseAccountIdentifier(address, "testField");
+      
+      expect(result.length).toBe(32);
+      const decoded = decodeAddress(address);
+      expect(result).toEqual(decoded);
+    });
+
+    it("should accept hex string", () => {
+      const accountBytes = generateTestPubkey(0x01);
+      const hexString = Array.from(accountBytes)
+        .map(b => b.toString(16).padStart(2, "0"))
+        .join("");
+      
+      const result = parseAccountIdentifier(hexString, "testField");
+      
+      expect(result.length).toBe(32);
+      expect(result).toEqual(accountBytes);
+    });
+
+    it("should throw error for Uint8Array with wrong length", () => {
+      const invalidAccount = new Uint8Array(31);
+      
+      expect(() => parseAccountIdentifier(invalidAccount, "testField")).toThrow("testField must contain 32 bytes");
+    });
+
+    it("should throw error for invalid string format", () => {
+      expect(() => parseAccountIdentifier("invalid-format", "testField")).toThrow(
+        "testField must be a 32-byte value, ta-address, or 64-character hex string"
+      );
+    });
+
+    it("should include field name in error message", () => {
+      const invalidAccount = new Uint8Array(31);
+      
+      expect(() => parseAccountIdentifier(invalidAccount, "myCustomField")).toThrow("myCustomField must contain 32 bytes");
+    });
+  });
+
+  describe("parseInstructionData", () => {
+    it("should return undefined for undefined input", () => {
+      const result = parseInstructionData(undefined);
+      expect(result).toBeUndefined();
+    });
+
+    it("should accept Uint8Array", () => {
+      const data = new Uint8Array([0x01, 0x02, 0x03]);
+      const result = parseInstructionData(data);
+      
+      expect(result).toEqual(data);
+      expect(result).not.toBe(data); // Should be a copy
+    });
+
+    it("should accept empty Uint8Array", () => {
+      const data = new Uint8Array(0);
+      const result = parseInstructionData(data);
+      
+      expect(result).toEqual(data);
+    });
+
+    it("should accept hex string", () => {
+      const dataBytes = new Uint8Array([0x01, 0x02, 0x03]);
+      const hexString = Array.from(dataBytes)
+        .map(b => b.toString(16).padStart(2, "0"))
+        .join("");
+      
+      const result = parseInstructionData(hexString);
+      
+      expect(result).toEqual(dataBytes);
+    });
+
+    it("should accept empty hex string", () => {
+      const result = parseInstructionData("");
+      
+      expect(result).toBeInstanceOf(Uint8Array);
+      expect(result?.length).toBe(0);
+    });
+
+    it("should throw error for invalid string format", () => {
+      expect(() => parseInstructionData("not-hex")).toThrow("Instruction data must be provided as hex string or Uint8Array");
+    });
+
+    it("should handle large instruction data", () => {
+      const largeData = new Uint8Array(1000);
+      largeData.fill(0x42);
+      const result = parseInstructionData(largeData);
+      
+      expect(result).toEqual(largeData);
+      expect(result?.length).toBe(1000);
+    });
+  });
+});
+

package/thru-ts-client-sdk/transactions/types.ts

@@ -31,11 +31,20 @@ export interface TransactionAccountsInput {
     readOnlyAccounts?: AccountAddress[];
 }
 
-export interface TransactionContentInput {
-    instructions?: Uint8Array;
-    proofs?: OptionalProofs;
+/**
+ * Builder context provided to instruction data functions.
+ * Contains all transaction accounts in their final sorted order and helper functions
+ * for looking up account indexes.
+ */
+export interface TransactionBuilderContext {
+    /** All accounts in final transaction order: [feePayer, program, ...readWrite, ...readOnly] */
+    accounts: AccountAddress[];
+    /** Get the index of an account by its public key. Throws if account is not found in transaction. */
+    getAccountIndex: (pubkey: AccountAddress) => number;
 }
 
+
+
 export interface FeePayerInput {
     publicKey: AccountAddress;
     privateKey?: Bytes32;
@@ -46,7 +55,8 @@ export interface BuildTransactionParams {
     program: ProgramIdentifier;
     header: TransactionHeaderInput;
     accounts?: TransactionAccountsInput;
-    content?: TransactionContentInput;
+    instructionData?: BytesLike;
+    proofs?: OptionalProofs;
 }
 
 export interface BuiltTransactionResult {

package/vitest.config.ts

@@ -0,0 +1,31 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    environment: "jsdom",
+    globals: true, // Enable describe, it, expect globally
+    include: ["thru-ts-client-sdk/**/*.{test,spec}.{ts,tsx}"],
+    exclude: [
+      "**/node_modules/**",
+      "**/dist/**",
+      "**/proto/**",
+      "**/test-scripts/**",
+    ],
+    // Don't fail when no tests are found (useful during development)
+    passWithNoTests: true,
+    coverage: {
+      provider: "v8",
+      reporter: ["text", "json", "html"],
+      include: ["thru-ts-client-sdk/**/*.ts"],
+      exclude: [
+        "**/__tests__/**",
+        "**/proto/**",
+        "**/dist/**",
+        "**/test-scripts/**",
+        "**/*.test.ts",
+        "**/*.spec.ts",
+      ],
+    },
+  },
+});
+