@thru/thru-sdk 0.0.4

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

@@ -0,0 +1,216 @@
+import { ConsensusStatus } from "./proto/thru/common/v1/consensus_pb";
+import { createThruClient } from "./sdk";
+
+const sdk = createThruClient({
+    // Configure the SDK to connect to the desired Thru cluster
+    // endpoint: "https://api.thru.network", // Example endpoint
+});
+
+const counterProgramAddress = 'taXP9YQR-M_1xg_jCh61aVpnMzAy0nqIfMA6waQXUMqfrL'
+const derivedAddress = 'taXu7Ka2B1UULjhCfyGb3MMJfHVMoA99Ii_KmgcYHHrsoY'
+const seed = 'count1'
+
+const feePayerAddress = 'takJg69_G9ESZ6IyEzYw97h8Xz6H-LdWTD7EF-qomr6Zv2'
+const feePayerPrivateKeyHex = '9429cacf4e1faa2524d42aeda5d6daa2eab4ca6b56854ad4da35437911d8176a'
+
+const DEFAULT_COMPUTE_UNITS = 300_000_000;
+const DEFAULT_STATE_UNITS = 10_000;
+const DEFAULT_MEMORY_UNITS = 10_000;
+const DEFAULT_EXPIRY_AFTER = 100;
+
+// Turn an unsigned integer into a little-endian hex string padded to byteLength bytes
+export function toLittleEndianHex(value: number | bigint, byteLength: number): string {
+    let v = typeof value === "bigint" ? value : BigInt(value);
+    const bytes = new Uint8Array(byteLength);
+    for (let i = 0; i < byteLength; i++) {
+        bytes[i] = Number(v & 0xffn);
+        v >>= 8n;
+    }
+    return Array.from(bytes, b => b.toString(16).padStart(2, "0")).join("");
+}
+
+// Convenience wrappers matching the screenshot
+export const u32ToHexLE = (value: number | bigint) => toLittleEndianHex(value, 4);
+export const u16ToHexLE = (value: number | bigint) => toLittleEndianHex(value, 2);
+
+
+const getIncrementCounterAccountInstructionDataHex = async () => {
+    const instructionCreate = u32ToHexLE(1)
+    const accountIndex = u16ToHexLE(2)
+    const instructionData = instructionCreate + accountIndex
+    return instructionData;
+}
+
+const accountDataToHex = (data: Uint8Array): string => {
+    let dataToHex = Array.from(data, b => b.toString(16).padStart(2, "0")).join("");
+    return dataToHex;
+}
+
+function hexToBytes(hex: string): Uint8Array {
+    const normalized = hex.startsWith("0x") ? hex.slice(2) : hex;
+    if (normalized.length % 2 !== 0) {
+        throw new Error("Private key hex must contain an even number of characters");
+    }
+    const bytes = new Uint8Array(normalized.length / 2);
+    for (let i = 0; i < normalized.length; i += 2) {
+        bytes[i / 2] = parseInt(normalized.substring(i, i + 2), 16);
+    }
+    return bytes;
+}
+
+const incrementCounterAccountInstruction = async () => {
+    const instructionDataHex = await getIncrementCounterAccountInstructionDataHex();
+    const feePayerPublicKey = sdk.helpers.decodeAddress(feePayerAddress);
+    const feePayerPrivateKey = hexToBytes(feePayerPrivateKeyHex);
+
+    const transaction = await sdk.transactions.build({
+        feePayer: {
+            publicKey: feePayerPublicKey,
+            privateKey: feePayerPrivateKey,
+        },
+        program: counterProgramAddress,
+        header: {
+            fee: 0n,
+            computeUnits: DEFAULT_COMPUTE_UNITS,
+            stateUnits: DEFAULT_STATE_UNITS,
+            memoryUnits: DEFAULT_MEMORY_UNITS,
+            expiryAfter: DEFAULT_EXPIRY_AFTER,
+        },
+        accounts: {
+            readWrite: [derivedAddress],
+        },
+        content: {
+            instructions: instructionDataHex,
+        },
+    })
+
+    await transaction.sign(feePayerPrivateKey);
+
+    const rawTransaction = transaction.toWire();
+
+    const submittedSignature = await sdk.transactions.send(rawTransaction);
+    console.log("Submitted transaction signature:", submittedSignature);
+
+    let finalized = false;
+    let executionUnits: number | undefined;
+
+    try {
+        for await (const update of sdk.transactions.track(submittedSignature, { timeoutMs: 60000 })) {
+            const consumed = update.executionResult?.consumedComputeUnits ?? 0;
+            const statusKey = ConsensusStatus[update.consensusStatus];
+            console.log("Track update:", statusKey, "consumed CU:", consumed);
+            if (update.executionResult) {
+                executionUnits = consumed;
+            }
+            if (
+                update.consensusStatus === ConsensusStatus.FINALIZED ||
+                update.consensusStatus === ConsensusStatus.CLUSTER_EXECUTED
+            ) {
+                finalized = true;
+                break;
+            }
+        }
+    } catch (err) {
+        console.warn("Track transaction stream ended with error:", err);
+    }
+
+    if (!finalized) {
+        console.warn("Transaction not finalized before timeout");
+    }
+    if (executionUnits !== undefined) {
+        console.log("Execution consumed compute units:", executionUnits);
+    }
+}
+
+
+async function main() {
+    const accountData1 = await sdk.accounts.get(derivedAddress);
+
+    if (accountData1.data) {
+        console.log("First Account Data:", accountDataToHex(accountData1.data.data));
+    }
+
+    await incrementCounterAccountInstruction();
+
+    await new Promise(resolve => setTimeout(resolve, 2000));
+
+    const accountData2 = await sdk.accounts.get(derivedAddress);
+
+    if (accountData2.data) {
+        console.log("Incremented Account Data:", accountDataToHex(accountData2.data.data));
+    }
+}
+
+console.log("Starting counter script");
+main()
+
+// function seedToHex32Padded(seed: string): string {
+//     const bytes = new TextEncoder().encode(seed);
+//     const padded = new Uint8Array(32);
+//     padded.set(bytes.slice(0, 32));
+//     return Array.from(padded, b => b.toString(16).padStart(2, "0")).join("");
+// }
+
+// const getCreateCounterAccountInstructionDataHex = async () => {
+//     const instructionCreate = u32ToHexLE(0)
+//     const accountIndex = u16ToHexLE(2)
+
+//     const blockHeight = await sdk.getBlockHeight();
+//     const stateProof = await sdk.generateStateProof({
+//         proofType: 1,
+//         address: derivedAddress,
+//         targetSlot: blockHeight.finalized
+//     })
+//     if (!stateProof.proof || stateProof.proof.proof.length === 0) {
+//         console.error("No state proof returned");
+//         return;
+//     }
+//     const stateProofSizeHex = u32ToHexLE(stateProof.proof.proof.length);
+//     const seedHex = seedToHex32Padded(seed);
+
+//     const stateProofHex = stateProof.proof.proof.reduce((acc, byte) => acc + byte.toString(16).padStart(2, "0"), "")
+
+//     console.log(instructionCreate, accountIndex, seedHex, stateProofSizeHex, stateProofHex)
+
+//     const instructionData = instructionCreate + accountIndex + seedHex + stateProofSizeHex + stateProofHex
+//     return instructionData;
+// }
+
+// const createCounterAccountInstruction = async () => {
+//     const instructionDataHex = await getCreateCounterAccountInstructionDataHex();
+//     console.log("Instruction Data Hex:", instructionDataHex);
+
+//     const feePayerPublicKey = sdk.decodeAddress(feePayerAddress);
+//     console.log("Fee Payer Public Key:", feePayerPublicKey);
+//     const feePayerPrivateKey = hexToBytes(feePayerPrivateKeyHex);
+
+//     const { rawTransaction, signature } = await sdk.buildAndSignTransaction({
+//         feePayer: {
+//             publicKey: feePayerPublicKey,
+//             privateKey: feePayerPrivateKey,
+//         },
+//         program: counterProgramAddress,
+//         header: {
+//             fee: 0n,
+//         },
+//         accounts: {
+//             readWrite: [derivedAddress],
+//         },
+//         content: {
+//             instructions: instructionDataHex,
+//         },
+//     });
+
+//     console.log("Local signature:", Array.from(signature, b => b.toString(16).padStart(2, "0")).join(""));
+
+//     const submittedSignature = await sdk.sendBuiltTransaction(rawTransaction);
+//     console.log("Submitted transaction signature:", submittedSignature);
+
+//     await new Promise(resolve => setTimeout(resolve, 4000));
+
+//     const submittedTransactionStatus = await sdk.getTransactionStatus(submittedSignature);
+//     console.log("Submitted transaction status:", submittedTransactionStatus);
+
+//     const submittedTransaction = await sdk.getTransaction(submittedSignature);
+//     console.log("Submitted transaction:", submittedTransaction);
+// }

package/thru-ts-client-sdk/create-account.ts

@@ -0,0 +1,78 @@
+import { getPublicKeyAsync } from "@noble/ed25519";
+import { ConsensusStatus } from "./proto/thru/common/v1/consensus_pb";
+import { createThruClient } from "./sdk";
+
+const sdk = createThruClient({
+    // endpoint: "https://api.thru.network", // Set to your cluster endpoint.
+});
+
+// Replace with the account you want to create and its 32-byte private key.
+const targetAccountPrivateKeyHex = "da0abd760d32d319ad11069d2d56f8c61b03f28d4096947c5117a54f427e4d60";
+const targetAccountAddress = sdk.helpers.encodeAddress(await getPublicKeyAsync(targetAccountPrivateKeyHex))
+
+function hexToBytes(hex: string): Uint8Array {
+    const normalized = hex.startsWith("0x") ? hex.slice(2) : hex;
+    if (normalized.length % 2 !== 0) {
+        throw new Error("Private key hex must contain an even number of characters");
+    }
+    const bytes = new Uint8Array(normalized.length / 2);
+    for (let i = 0; i < normalized.length; i += 2) {
+        bytes[i / 2] = parseInt(normalized.substring(i, i + 2), 16);
+    }
+    return bytes;
+}
+
+async function fetchAccountSnapshot(label: string, address: string): Promise<void> {
+    try {
+        const account = await sdk.accounts.get(address);
+        const consensus = account.consensusStatus != null
+            ? ConsensusStatus[account.consensusStatus]
+            : "UNKNOWN";
+        const slot = account.versionContext?.slot ?? 0n;
+        const balance = account.meta?.balance ?? 0n;
+        const stateCounter = account.meta?.stateCounter ?? 0n;
+
+        console.log(
+            `${label} account status: consensus=${consensus}, slot=${slot.toString()}, balance=${balance.toString()}, stateCounter=${stateCounter.toString()}`,
+        );
+    } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        console.log(`${label} account lookup failed: ${message}`);
+    }
+}
+
+async function run(): Promise<void> {
+    console.log("Preparing create account transaction");
+
+    await fetchAccountSnapshot("Pre-create", targetAccountAddress);
+
+    const feePayerPublicKey = sdk.helpers.decodeAddress(targetAccountAddress);
+    const feePayerPrivateKey = hexToBytes(targetAccountPrivateKeyHex);
+
+    const transaction = await sdk.accounts.create({
+        publicKey: feePayerPublicKey
+    })
+
+    await transaction.sign(feePayerPrivateKey);
+
+    const rawTransaction = transaction.toWire();
+
+    console.log("Submitting transaction");
+    const submittedSignature = await sdk.transactions.send(rawTransaction);
+    // Allow some time for the cluster to reflect the new account state.
+    await new Promise(resolve => setTimeout(resolve, 2_000));
+    const transactionStatus = await sdk.transactions.getStatus(submittedSignature);
+    console.log("Submitted transaction status:", transactionStatus);
+    console.log("Submitted transaction signature:", submittedSignature);
+
+    // await trackTransaction(submittedSignature);
+
+    // Allow some time for the cluster to reflect the new account state.
+    await new Promise(resolve => setTimeout(resolve, 2_000));
+
+    await fetchAccountSnapshot("Post-create", targetAccountAddress);
+}
+
+run().catch(error => {
+    console.error("Create account script failed:", error);
+});

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

@@ -0,0 +1,17 @@
+import { ConsensusStatus } from "./proto/thru/common/v1/consensus_pb";
+import { AccountView } from "./proto/thru/core/v1/account_pb";
+import { BlockView } from "./proto/thru/core/v1/block_pb";
+import { TransactionView } from "./proto/thru/core/v1/transaction_pb";
+
+export const DEFAULT_HOST = "http://74.118.142.189:8080";
+
+export const DEFAULT_ACCOUNT_VIEW = AccountView.FULL;
+export const DEFAULT_BLOCK_VIEW = BlockView.FULL;
+export const DEFAULT_TRANSACTION_VIEW = TransactionView.FULL;
+export const DEFAULT_MIN_CONSENSUS = ConsensusStatus.UNSPECIFIED;
+
+export const DEFAULT_FEE = 1n;
+export const DEFAULT_COMPUTE_UNITS = 300_000_000;
+export const DEFAULT_STATE_UNITS = 10_000;
+export const DEFAULT_MEMORY_UNITS = 10_000;
+export const DEFAULT_EXPIRY_AFTER = 100;

package/thru-ts-client-sdk/get-height.ts

@@ -0,0 +1,52 @@
+/* Polyfill XMLHttpRequest for Node.js */
+import { createClient } from "@connectrpc/connect";
+
+import { createGrpcWebTransport } from "@connectrpc/connect-web";
+import { GetHeightRequestSchema, QueryService } from './proto/thru/services/v1/query_service_pb';
+
+import { create } from "@bufbuild/protobuf";
+
+/* Example script to get the current block height from a Thru node */
+async function getBlockHeight(hostUrl: string): Promise<void> {
+  /* Create the gRPC client */
+  const transport = createGrpcWebTransport({
+    baseUrl: hostUrl,
+  });
+  const client = createClient(QueryService, transport);
+
+
+  try {
+    /* Create an empty request */
+    const request = create(GetHeightRequestSchema);
+
+    /* Call the GetHeight RPC method */
+    const response = await client.getHeight(request);
+
+    /* Extract height information from the response */
+    const finalized = response.finalized;
+    const locallyExecuted = response.locallyExecuted;
+    const clusterExecuted = response.clusterExecuted;
+
+    /* Display the results */
+    console.log('=== Block Height ===');
+    console.log(`Finalized:        ${finalized}`);
+    console.log(`Locally Executed: ${locallyExecuted}`);
+    console.log(`Cluster Executed: ${clusterExecuted}`);
+  } catch (err) {
+    console.error('Error fetching block height:', err);
+    throw err;
+  }
+}
+
+/* Main execution */
+const DEFAULT_HOST = 'http://74.118.142.189:8080';
+
+console.log(`Connecting to Thru node at ${DEFAULT_HOST}...`);
+
+getBlockHeight(DEFAULT_HOST)
+  .then(() => {
+    console.log('\nSuccess!');
+  })
+  .catch((err) => {
+    console.error('\nFailed to get block height:', err);
+  });

package/thru-ts-client-sdk/modules/accounts.ts

@@ -0,0 +1,137 @@
+import { create } from "@bufbuild/protobuf";
+
+import type { ThruClientContext } from "../core/client";
+import { DEFAULT_ACCOUNT_VIEW, DEFAULT_MIN_CONSENSUS } from "../defaults";
+import { ConsensusStatus, VersionContext } from "../proto/thru/common/v1/consensus_pb";
+import type { Filter } from "../proto/thru/common/v1/filters_pb";
+import type { PageRequest } from "../proto/thru/common/v1/pagination_pb";
+import { Account, AccountView, DataSlice, RawAccount } from "../proto/thru/core/v1/account_pb";
+import { StateProofType } from "../proto/thru/core/v1/state_pb";
+import {
+    GetAccountRequestSchema,
+    GetRawAccountRequestSchema,
+    ListOwnedAccountsRequestSchema,
+    ListOwnedAccountsResponse,
+} from "../proto/thru/services/v1/query_service_pb";
+import type { Transaction } from "../transactions/Transaction";
+import { TransactionBuilder } from "../transactions/TransactionBuilder";
+import { getBlockHeight } from "./height";
+import type { BytesLike } from "./helpers";
+import { toPubkey } from "./helpers";
+import { generateStateProof } from "./proofs";
+
+export interface CreateAccountOptions {
+    /** The new account's public key (fee payer). */
+    publicKey: BytesLike;
+}
+
+
+export interface AccountQueryOptions {
+    view?: AccountView;
+    versionContext?: VersionContext;
+    minConsensus?: ConsensusStatus;
+    dataSlice?: DataSlice;
+}
+
+export interface RawAccountQueryOptions {
+    view?: AccountView;
+    versionContext?: VersionContext;
+    minConsensus?: ConsensusStatus;
+}
+
+export interface ListOwnedAccountsOptions {
+    view?: AccountView;
+    versionContext?: VersionContext;
+    filter?: Filter;
+    page?: PageRequest;
+    minConsensus?: ConsensusStatus;
+}
+
+export function getAccount(
+    ctx: ThruClientContext,
+    address: BytesLike,
+    options: AccountQueryOptions = {},
+): Promise<Account> {
+    const request = create(GetAccountRequestSchema, {
+        address: toPubkey(address, "address"),
+        view: options.view ?? DEFAULT_ACCOUNT_VIEW,
+        versionContext: options.versionContext,
+        minConsensus: options.minConsensus ?? DEFAULT_MIN_CONSENSUS,
+        dataSlice: options.dataSlice,
+    });
+    return ctx.query.getAccount(request);
+}
+
+export function getRawAccount(
+    ctx: ThruClientContext,
+    address: BytesLike,
+    options: RawAccountQueryOptions = {},
+): Promise<RawAccount> {
+    const request = create(GetRawAccountRequestSchema, {
+        address: toPubkey(address, "address"),
+        view: options.view ?? DEFAULT_ACCOUNT_VIEW,
+        versionContext: options.versionContext,
+        minConsensus: options.minConsensus ?? DEFAULT_MIN_CONSENSUS,
+    });
+    return ctx.query.getRawAccount(request);
+}
+
+export function listOwnedAccounts(
+    ctx: ThruClientContext,
+    owner: BytesLike,
+    options: ListOwnedAccountsOptions = {},
+): Promise<ListOwnedAccountsResponse> {
+    const request = create(ListOwnedAccountsRequestSchema, {
+        owner: toPubkey(owner, "owner"),
+        view: options.view ?? DEFAULT_ACCOUNT_VIEW,
+        versionContext: options.versionContext,
+        filter: options.filter,
+        page: options.page,
+        minConsensus: options.minConsensus ?? DEFAULT_MIN_CONSENSUS,
+    });
+    return ctx.query.listOwnedAccounts(request);
+}
+
+export async function createAccount(
+    ctx: ThruClientContext,
+    options: CreateAccountOptions,
+): Promise<Transaction> {
+    const feePayer = toPubkey(options.publicKey, "publicKey").value;
+
+    const height = await getBlockHeight(ctx);
+    const startSlot = height.finalized;
+
+    const proofResponse = await generateStateProof(ctx, {
+        address: options.publicKey,
+        proofType: StateProofType.CREATING,
+        targetSlot: startSlot,
+    });
+
+    const proofBytes = proofResponse.proof?.proof;
+    if (!proofBytes || proofBytes.length === 0) {
+        throw new Error("State proof generation returned empty proof");
+    }
+
+    const program = new Uint8Array(32);
+    program[31] = 0x02;
+
+    const builder = new TransactionBuilder();
+    const transaction = builder.build({
+        feePayer: { publicKey: feePayer },
+        program,
+        header: {
+            fee: 0n,
+            nonce: 0n,
+            startSlot,
+            expiryAfter: 100,
+            computeUnits: 10_000,
+            memoryUnits: 10_000,
+            stateUnits: 10_000,
+        },
+        content: {
+            proofs: { feePayerStateProof: proofBytes }
+        }
+    });
+
+    return transaction;
+}

package/thru-ts-client-sdk/modules/blocks.ts

@@ -0,0 +1,75 @@
+import { create } from "@bufbuild/protobuf";
+
+import type { ThruClientContext } from "../core/client";
+import { DEFAULT_BLOCK_VIEW, DEFAULT_MIN_CONSENSUS } from "../defaults";
+import { ConsensusStatus } from "../proto/thru/common/v1/consensus_pb";
+import type { Filter } from "../proto/thru/common/v1/filters_pb";
+import type { PageRequest } from "../proto/thru/common/v1/pagination_pb";
+import { Block, BlockView, RawBlock } from "../proto/thru/core/v1/block_pb";
+import {
+    GetBlockRequestSchema,
+    GetRawBlockRequestSchema,
+    ListBlocksRequestSchema,
+    ListBlocksResponse,
+} from "../proto/thru/services/v1/query_service_pb";
+import { isSlotSelector } from "../utils/utils";
+import type { BlockSelector } from "./helpers";
+import { toBlockHash } from "./helpers";
+
+export interface BlockQueryOptions {
+    view?: BlockView;
+    minConsensus?: ConsensusStatus;
+}
+
+export interface RawBlockQueryOptions {
+    minConsensus?: ConsensusStatus;
+}
+
+export interface ListBlocksOptions {
+    filter?: Filter;
+    page?: PageRequest;
+    view?: BlockView;
+    minConsensus?: ConsensusStatus;
+}
+
+export function getBlock(
+    ctx: ThruClientContext,
+    selector: BlockSelector,
+    options: BlockQueryOptions = {},
+): Promise<Block> {
+    const request = create(GetBlockRequestSchema, {
+        selector: isSlotSelector(selector)
+            ? { case: "slot", value: typeof selector.slot === "bigint" ? selector.slot : BigInt(selector.slot) }
+            : { case: "blockHash", value: toBlockHash(selector.blockHash) },
+        view: options.view ?? DEFAULT_BLOCK_VIEW,
+        minConsensus: options.minConsensus ?? DEFAULT_MIN_CONSENSUS,
+    });
+    return ctx.query.getBlock(request);
+}
+
+export function getRawBlock(
+    ctx: ThruClientContext,
+    selector: BlockSelector,
+    options: RawBlockQueryOptions = {},
+): Promise<RawBlock> {
+    const request = create(GetRawBlockRequestSchema, {
+        selector: isSlotSelector(selector)
+            ? { case: "slot", value: typeof selector.slot === "bigint" ? selector.slot : BigInt(selector.slot) }
+            : { case: "blockHash", value: toBlockHash(selector.blockHash) },
+        minConsensus: options.minConsensus ?? DEFAULT_MIN_CONSENSUS,
+    });
+    return ctx.query.getRawBlock(request);
+}
+
+export function listBlocks(
+    ctx: ThruClientContext,
+    options: ListBlocksOptions = {},
+): Promise<ListBlocksResponse> {
+    const request = create(ListBlocksRequestSchema, {
+        filter: options.filter,
+        page: options.page,
+        view: options.view ?? DEFAULT_BLOCK_VIEW,
+        minConsensus: options.minConsensus ?? DEFAULT_MIN_CONSENSUS,
+    });
+    return ctx.query.listBlocks(request);
+}

package/thru-ts-client-sdk/modules/events.ts

@@ -0,0 +1,20 @@
+import { create } from "@bufbuild/protobuf";
+
+import type { ThruClientContext } from "../core/client";
+import type { VersionContext } from "../proto/thru/common/v1/consensus_pb";
+import { Event, GetEventRequestSchema } from "../proto/thru/services/v1/query_service_pb";
+
+export interface GetEventOptions {
+    versionContext?: VersionContext;
+}
+
+export function getEvent(ctx: ThruClientContext, eventId: string, options: GetEventOptions = {}): Promise<Event> {
+    if (!eventId) {
+        throw new Error("eventId is required");
+    }
+    const request = create(GetEventRequestSchema, {
+        eventId,
+        versionContext: options.versionContext,
+    });
+    return ctx.query.getEvent(request);
+}

package/thru-ts-client-sdk/modules/height.ts

@@ -0,0 +1,9 @@
+import { create } from "@bufbuild/protobuf";
+
+import type { ThruClientContext } from "../core/client";
+import { GetHeightRequestSchema, GetHeightResponse } from "../proto/thru/services/v1/query_service_pb";
+
+export function getBlockHeight(ctx: ThruClientContext): Promise<GetHeightResponse> {
+    const request = create(GetHeightRequestSchema);
+    return ctx.query.getHeight(request);
+}