@thru/thru-sdk 0.0.4

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

@@ -0,0 +1,48 @@
+import { Transaction } from "./Transaction";
+import type { BuildTransactionParams, SignedTransactionResult, TransactionAccountsInput } from "./types";
+import { normalizeAccountList, resolveProgramIdentifier } from "./utils";
+
+const FLAG_HAS_FEE_PAYER_PROOF = 1 << 0;
+
+export class TransactionBuilder {
+    build(params: BuildTransactionParams): Transaction {
+        const program = resolveProgramIdentifier(params.program);
+        const accounts = this.normalizeAccounts(params.accounts);
+        const instructions = params.content?.instructions;
+        const proofs = params.content?.proofs;
+        const baseFlags = params.header.flags ?? 0;
+        const flags = proofs?.feePayerStateProof ? baseFlags | FLAG_HAS_FEE_PAYER_PROOF : baseFlags;
+
+        return new Transaction({
+            feePayer: params.feePayer.publicKey,
+            program,
+            header: {
+                ...params.header,
+                flags,
+            },
+            accounts,
+            instructions,
+            proofs,
+        });
+    }
+
+    async buildAndSign(params: BuildTransactionParams): Promise<SignedTransactionResult> {
+        if (!params.feePayer.privateKey) {
+            throw new Error("Fee payer private key is required to sign the transaction");
+        }
+        const transaction = this.build(params);
+        const signature = await transaction.sign(params.feePayer.privateKey);
+        const rawTransaction = transaction.toWire();
+        return { transaction, signature, rawTransaction };
+    }
+
+    private normalizeAccounts(accounts?: TransactionAccountsInput): TransactionAccountsInput | undefined {
+        if (!accounts) {
+            return undefined;
+        }
+        return {
+            readWriteAccounts: normalizeAccountList(accounts.readWriteAccounts ?? []),
+            readOnlyAccounts: normalizeAccountList(accounts.readOnlyAccounts ?? []),
+        };
+    }
+}

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

@@ -0,0 +1,95 @@
+import { strict as assert } from "node:assert";
+import test from "node:test";
+
+import { Transaction } from "../Transaction";
+
+const HEADER_WITHOUT_SIGNATURE_SIZE = 176 - 64;
+const PUBKEY_LEN = 32;
+
+function makeKey(value: number): Uint8Array {
+    return new Uint8Array(Array.from({ length: PUBKEY_LEN }, () => value & 0xff));
+}
+
+test("Transaction serializes header and payload correctly", () => {
+    const feePayer = makeKey(1);
+    const program = makeKey(2);
+    const rwAccounts = [makeKey(3), makeKey(4)];
+    const instructions = new Uint8Array([0xaa, 0xbb, 0xcc]);
+
+    const tx = new Transaction({
+        feePayer,
+        program,
+        header: {
+            fee: 10n,
+            nonce: 20n,
+            startSlot: 30n,
+            expiryAfter: 40,
+            computeUnits: 50,
+            stateUnits: 60,
+            memoryUnits: 70,
+            flags: 1,
+        },
+        accounts: {
+            readWriteAccounts: rwAccounts,
+            readOnlyAccounts: [],
+        },
+        instructions,
+    });
+
+    const unsignedWire = tx.toWire();
+    const expectedLength = 176 + rwAccounts.length * PUBKEY_LEN + instructions.length;
+    assert.equal(unsignedWire.length, expectedLength);
+    assert(unsignedWire.subarray(0, 64).every((byte) => byte === 0), "signature prefix should be zero before signing");
+
+    const forSigning = tx.toWireForSigning();
+    const expectedSigningLength = HEADER_WITHOUT_SIGNATURE_SIZE + rwAccounts.length * PUBKEY_LEN + instructions.length;
+    assert.equal(forSigning.length, expectedSigningLength);
+
+    const headerView = new DataView(forSigning.buffer, forSigning.byteOffset, HEADER_WITHOUT_SIGNATURE_SIZE);
+    assert.equal(headerView.getUint8(0), 1); // version
+    assert.equal(headerView.getUint8(1), 1); // flags
+    assert.equal(headerView.getUint16(2, true), rwAccounts.length);
+    assert.equal(headerView.getUint16(4, true), 0); // readonly count
+    assert.equal(headerView.getUint16(6, true), instructions.length);
+    assert.equal(headerView.getUint32(8, true), 50);
+    assert.equal(headerView.getUint16(12, true), 60);
+    assert.equal(headerView.getUint16(14, true), 70);
+    assert.equal(Number(headerView.getBigUint64(16, true)), 10);
+    assert.equal(Number(headerView.getBigUint64(24, true)), 20);
+    assert.equal(Number(headerView.getBigUint64(32, true)), 30);
+    assert.equal(headerView.getUint32(40, true), 40);
+
+    const rwStart = HEADER_WITHOUT_SIGNATURE_SIZE;
+    assert.deepEqual(forSigning.subarray(rwStart, rwStart + PUBKEY_LEN), rwAccounts[0]);
+    assert.deepEqual(forSigning.subarray(rwStart + PUBKEY_LEN, rwStart + PUBKEY_LEN * 2), rwAccounts[1]);
+
+    const instructionStart = rwStart + rwAccounts.length * PUBKEY_LEN;
+    assert.deepEqual(forSigning.subarray(instructionStart), instructions);
+});
+
+test("Transaction signing populates signature in wire output", async () => {
+    const feePayer = makeKey(9);
+    const program = makeKey(10);
+    const privateKey = new Uint8Array(Array.from({ length: 32 }, (_, idx) => idx + 1));
+
+    const tx = new Transaction({
+        feePayer,
+        program,
+        header: {
+            fee: 1n,
+            nonce: 2n,
+            startSlot: 3n,
+        },
+    });
+
+    const signature = await tx.sign(privateKey);
+    assert.equal(signature.length, 64);
+
+    const storedSignature = tx.getSignature();
+    assert(storedSignature);
+    assert.deepEqual(signature, storedSignature);
+
+    const wire = tx.toWire();
+    assert.deepEqual(wire.subarray(0, 64), signature);
+    assert.deepEqual(wire.subarray(64, 64 + 32), feePayer);
+});

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

@@ -0,0 +1,3 @@
+export * from "./Transaction";
+export * from "./TransactionBuilder";
+export * from "./types";

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

@@ -0,0 +1,64 @@
+import type { BytesLike } from "../modules/helpers";
+
+export type Bytes32 = Uint8Array;
+export type Bytes64 = Uint8Array;
+
+export type AccountAddress = Bytes32;
+
+export type ProgramIdentifier = BytesLike;
+
+export interface ResourceLimits {
+    computeUnits?: number;
+    stateUnits?: number;
+    memoryUnits?: number;
+}
+
+export interface OptionalProofs {
+    feePayerStateProof?: Uint8Array;
+    feePayerAccountMetaRaw?: Uint8Array;
+}
+
+export interface TransactionHeaderInput extends ResourceLimits {
+    fee: bigint;
+    nonce: bigint;
+    startSlot: bigint;
+    expiryAfter?: number;
+    flags?: number;
+}
+
+export interface TransactionAccountsInput {
+    readWriteAccounts?: AccountAddress[];
+    readOnlyAccounts?: AccountAddress[];
+}
+
+export interface TransactionContentInput {
+    instructions?: Uint8Array;
+    proofs?: OptionalProofs;
+}
+
+export interface FeePayerInput {
+    publicKey: AccountAddress;
+    privateKey?: Bytes32;
+}
+
+export interface BuildTransactionParams {
+    feePayer: FeePayerInput;
+    program: ProgramIdentifier;
+    header: TransactionHeaderInput;
+    accounts?: TransactionAccountsInput;
+    content?: TransactionContentInput;
+}
+
+export interface BuiltTransactionResult {
+    transaction: TransactionLike;
+}
+
+export interface SignedTransactionResult extends BuiltTransactionResult {
+    signature: Bytes64;
+    rawTransaction: Uint8Array;
+}
+
+// Forward declaration to avoid circular imports in type layer
+export interface TransactionLike {
+    toWire(): Uint8Array;
+}

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

@@ -0,0 +1,134 @@
+import type { BytesLike } from "../modules/helpers";
+import { decodeAddress } from "../modules/helpers";
+import { hexToBytes, isHexString } from "../utils/utils";
+import type { AccountAddress, ProgramIdentifier } from "./types";
+
+const ACCOUNT_LIMIT = 1024;
+
+export function normalizeAccountList(accounts: AccountAddress[]): AccountAddress[] {
+    if (accounts.length === 0) {
+        return [];
+    }
+
+    if (accounts.length > ACCOUNT_LIMIT) {
+        throw new Error(`Too many accounts provided: ${accounts.length} (max ${ACCOUNT_LIMIT})`);
+    }
+
+    const deduped = dedupeAccountList(accounts);
+    return deduped;
+}
+
+function dedupeAccountList(accounts: AccountAddress[]): AccountAddress[] {
+    const seen = new Map<string, AccountAddress>();
+    for (const account of accounts) {
+        if (account.length !== 32) {
+            throw new Error("Account addresses must contain 32 bytes");
+        }
+
+        const key = toHex(account);
+        if (!seen.has(key)) {
+            seen.set(key, new Uint8Array(account));
+        }
+    }
+
+    return Array.from(seen.values()).sort(compareAccounts);
+}
+
+function compareAccounts(a: Uint8Array, b: Uint8Array): number {
+    for (let i = 0; i < 32; i++) {
+        if (a[i] !== b[i]) {
+            return a[i] - b[i];
+        }
+    }
+    return 0;
+}
+
+function toHex(bytes: Uint8Array): string {
+    let result = "";
+    for (let i = 0; i < bytes.length; i++) {
+        const hex = bytes[i].toString(16).padStart(2, "0");
+        result += hex;
+    }
+    return result;
+}
+
+export function resolveProgramIdentifier(identifier: ProgramIdentifier): AccountAddress {
+    if (identifier instanceof Uint8Array) {
+        if (identifier.length !== 32) {
+            throw new Error("Program public key must contain 32 bytes");
+        }
+        return copyAccount(identifier);
+    }
+
+    if (typeof identifier === "string") {
+        const parsed = parseProgramString(identifier);
+        if (parsed) {
+            return parsed;
+        }
+    }
+
+    throw new Error("Unsupported program identifier format");
+}
+
+function parseProgramString(value: string): AccountAddress | undefined {
+    if (value.startsWith("ta") && value.length === 46) {
+        return copyAccount(decodeAddress(value));
+    }
+    if (isHexString(value)) {
+        const bytes = hexToBytes(value);
+        if (bytes.length !== 32) {
+            throw new Error("Hex-encoded program key must contain 32 bytes");
+        }
+        return bytes;
+    }
+    return undefined;
+}
+
+function copyAccount(value: AccountAddress): AccountAddress {
+    if (value.length !== 32) {
+        throw new Error("Program public key must contain 32 bytes");
+    }
+    return new Uint8Array(value);
+}
+
+export function parseAccountIdentifier(value: BytesLike, field: string): AccountAddress {
+    if (value instanceof Uint8Array) {
+        if (value.length !== 32) {
+            throw new Error(`${field} must contain 32 bytes`);
+        }
+        return new Uint8Array(value);
+    }
+
+    if (typeof value === "string") {
+        if (value.startsWith("ta") && value.length === 46) {
+            return copyAccount(decodeAddress(value));
+        }
+        if (isHexString(value)) {
+            const bytes = hexToBytes(value);
+            if (bytes.length !== 32) {
+                throw new Error(`${field} hex string must decode to 32 bytes`);
+            }
+            return bytes;
+        }
+    }
+
+    throw new Error(`${field} must be a 32-byte value, ta-address, or 64-character hex string`);
+}
+
+export function parseInstructionData(value?: BytesLike): Uint8Array | undefined {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (value instanceof Uint8Array) {
+        return new Uint8Array(value);
+    }
+    if (typeof value === "string") {
+        if (value.length === 0) {
+            return new Uint8Array();
+        }
+        if (isHexString(value)) {
+            return hexToBytes(value);
+        }
+    }
+    throw new Error("Instruction data must be provided as hex string or Uint8Array");
+}

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

@@ -0,0 +1,8 @@
+import { BytesLike } from "../modules/helpers";
+import { StateProofType } from "../proto/thru/core/v1/state_pb";
+
+export type GenerateStateProofOptions = {
+    address?: BytesLike;
+    proofType: StateProofType;
+    targetSlot: bigint;
+}

package/thru-ts-client-sdk/utils/utils.ts

@@ -0,0 +1,70 @@
+
+const BASE64_URL_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
+const BASE64_URL_MAP = new Int16Array(256).fill(-1);
+for (let i = 0; i < BASE64_URL_ALPHABET.length; i++) {
+    BASE64_URL_MAP[BASE64_URL_ALPHABET.charCodeAt(i)] = i;
+}
+
+export type BytesLike = string | Uint8Array;
+export type BlockSelector = { slot: number | bigint } | { blockHash: BytesLike };
+
+export function decodeBase64(value: string): Uint8Array {
+    if (value.length === 0) {
+        return new Uint8Array();
+    }
+    const atobFn = globalThis.atob;
+    if (!atobFn) {
+        throw new Error("Base64 decoding requires window.atob support");
+    }
+    const binary = atobFn(value);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) {
+        bytes[i] = binary.charCodeAt(i);
+    }
+    return bytes;
+}
+
+export function isSlotSelector(selector: BlockSelector): selector is { slot: number | bigint } {
+    return "slot" in selector;
+}
+
+export function ensureBytes(value: BytesLike | undefined, field: string): Uint8Array {
+    if (value instanceof Uint8Array) {
+        if (value.length === 0) {
+            throw new Error(`${field} cannot be empty`);
+        }
+        return value;
+    }
+    if (typeof value === "string") {
+        if (value.length === 0) {
+            throw new Error(`${field} cannot be empty`);
+        }
+        return decodeBase64(value);
+    }
+    throw new Error(`${field} is required`);
+}
+
+export function maskForBits(bits: number): number {
+    return bits === 0 ? 0 : (1 << bits) - 1;
+}
+
+export function isHexString(value: string): boolean {
+    const normalized = value.startsWith("0x") ? value.slice(2) : value;
+    return normalized.length % 2 === 0 && normalized.length > 0 && /^[0-9a-fA-F]+$/.test(normalized);
+}
+
+export function hexToBytes(value: string): Uint8Array {
+    const normalized = value.startsWith("0x") ? value.slice(2) : value;
+    if (normalized.length % 2 !== 0) {
+        throw new Error("Hex string must contain an even number of characters");
+    }
+    const bytes = new Uint8Array(normalized.length / 2);
+    for (let i = 0; i < normalized.length; i += 2) {
+        const byte = parseInt(normalized.slice(i, i + 2), 16);
+        if (Number.isNaN(byte)) {
+            throw new Error("Hex string contains invalid characters");
+        }
+        bytes[i / 2] = byte;
+    }
+    return bytes;
+}

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./thru-ts-client-sdk",
+  },
+  "include": ["thru-ts-client-sdk/**/*"],
+  "exclude": ["node_modules", "dist", "thru-ts-client-sdk/**/__tests__/**"]
+}

package/tsup.config.ts

@@ -0,0 +1,10 @@
+import { defineConfig } from 'tsup';
+
+export default defineConfig({
+  entry: ['thru-ts-client-sdk/sdk.ts'],
+  format: ['esm'],
+  dts: true,
+  sourcemap: true,
+  clean: true,
+  treeshake: true,
+});