@thru/sdk

Open-source TypeScript SDK for the Thru RISC-V Layer-1 blockchain: typed RPC client, transaction builder, keys and crypto, protobufs, and ABI reflection.

The SDK exposes rich domain models (blocks, accounts, transactions, events, proofs) that hide the underlying protobuf transport.

Installation

npm install @thru/sdk

TypeScript Configuration

For optimal import resolution, use modern module resolution:

{
  "compilerOptions": {
    "moduleResolution": "bundler",
    "module": "ESNext",
    "target": "ES2020",
    "isolatedModules": true
  }
}

If you rely on Node’s ESM support without a bundler, use "moduleResolution": "nodenext".

Basic Usage

import { createThruClient } from "@thru/sdk";
import {
  Account,
  Block,
  ChainEvent,
  ConsensusStatus,
  Transaction,
  TransactionStatusSnapshot,
} from "@thru/sdk";

const thru = createThruClient({
  baseUrl: "https://rpc.alphanet.thru.org",
});

// Fetch the latest finalized block
const height = await thru.blocks.getBlockHeight();
const latestBlock: Block = await thru.blocks.get({ slot: height.finalized });
console.log(latestBlock.header.blockHash);

// Fetch an account – returns the Account domain object
const account: Account = await thru.accounts.get("taExampleAddress...");
console.log(account.meta?.balance);

// Build, sign, submit, and track a transaction
const { rawTransaction } = await thru.transactions.buildAndSign({
  feePayer: {
    publicKey: "taFeePayerAddress...",
    privateKey: feePayerSecretKeyBytes,
  },
  program: programIdentifierBytes,
});

// Submit and track with one RPC so no live tracking update can be missed.
for await (const update of thru.transactions.sendAndTrack(rawTransaction, {
  timeoutMs: 60_000,
})) {
  console.log(update.status, update.executionResult?.consumedComputeUnits);
  if (
    update.executionResult ||
    update.consensusStatus === ConsensusStatus.FINALIZED ||
    update.consensusStatus === ConsensusStatus.CLUSTER_EXECUTED
  ) {
    break;
  }
}

Client Configuration

createThruClient accepts advanced transport options so you can customize networking, interceptors, and default call behaviour:

const thru = createThruClient({
  baseUrl: "https://rpc.alphanet.thru.org",
  transportOptions: {
    useBinaryFormat: false,
    defaultTimeoutMs: 10_000,
  },
  interceptors: [authInterceptor],
  callOptions: {
    timeoutMs: 5_000,
    headers: [["x-team", "sdk"]],
  },
});

• transportOptions are passed to createGrpcWebTransport. Provide custom fetch implementations, JSON/binary options, or merge additional interceptors.
• interceptors let you append cross-cutting logic (auth, metrics) without re-implementing transports.
• callOptions act as defaults for every RPC. You can set timeouts, headers, or a shared AbortSignal, and each module call merges in per-request overrides.

Legacy transaction signing

RFC-8032 is always the default. Networks that have not completed the signing cutover can opt into the pre-cutover outer-transaction signature scheme:

import {
  createThruClient,
  TransactionSigningScheme,
} from "@thru/sdk";

const thru = createThruClient({
  baseUrl: "https://legacy-rpc.example",
  transactionSigningScheme: TransactionSigningScheme.Legacy,
});

For manually built transactions, transaction.legacySign(privateKey) is the explicit compatibility equivalent of the RFC-8032-only transaction.sign(privateKey). The schemes are not interchangeable, and the SDK never retries with legacy signing automatically.

Domain Models

The SDK revolves around immutable domain classes. They copy mutable buffers, expose clear invariants, and provide conversion helpers where needed.

| API surface | Domain class | | --- | --- | | Blocks | Block, BlockHeader, BlockFooter | | Accounts | Account, AccountMeta, AccountData | | Transactions | Transaction, TransactionStatusSnapshot, TrackTransactionUpdate | | Events | ChainEvent | | Proofs | StateProof | | Height | HeightSnapshot | | Node version | VersionInfo |

All classes are exported from the root package for easy access:

import { Block, Account, ChainEvent } from "@thru/sdk";

Primitives

Pubkey and Signature wrap the 32-byte Ed25519 public key and 64-byte signature primitives, respectively. They centralize validation, conversion, and proto interop so you can work with either Thru-formatted strings (ta... / ts...), hex, or raw bytes without sprinkling helpers throughout your app.

import { Pubkey, Signature } from "@thru/sdk";

const payer = Pubkey.from("taDs2...");          // accepts ta string, hex, or Uint8Array
const sig = Signature.from("ts8Lk...");         // accepts ts string, hex, or Uint8Array

payer.toBytes();           // defensive copy
payer.toThruFmt();         // "ta..." string
payer.toProtoPubkey();     // thru.common.v1.Pubkey
payer.toProtoTaPubkey();   // thru.common.v1.TaPubkey

sig.toBytes();
sig.toThruFmt();          // "ts..." string
sig.toProtoSignature();   // thru.common.v1.Signature
sig.toProtoTsSignature(); // thru.common.v1.TsSignature

// Helper namespace now returns these domain objects:
const parsed = sdk.helpers.createPubkey("taFeePayerAddress...");
const signature = sdk.helpers.createSignature(sigBytes);

The bound client accepts either raw bytes or the new primitives; call .toBytes() on Pubkey/Signature when you need to interop with legacy code.

View Options

When fetching resources, you can control which parts of the resource are returned using view options. This allows you to optimize network usage by only fetching the data you need.

AccountView

Controls which sections of account resources are returned:

import { AccountView } from "@thru/sdk";

// Fetch only the account address (lightweight existence check)
const account = await thru.accounts.get(address, {
  view: AccountView.PUBKEY_ONLY,
});

// Fetch only account metadata (balance, flags, owner, etc.)
const account = await thru.accounts.get(address, {
  view: AccountView.META_ONLY,
});

// Fetch only account data bytes (program data)
const account = await thru.accounts.get(address, {
  view: AccountView.DATA_ONLY,
});

// Fetch everything: address, metadata, and data (default)
const account = await thru.accounts.get(address, {
  view: AccountView.FULL,
});

| View Option | Returns | Use Case | | --- | --- | --- | | AccountView.PUBKEY_ONLY | Only the account address | Quick existence check | | AccountView.META_ONLY | address + meta (balance, flags, owner, dataSize, seq, nonce) | Display account summary without data | | AccountView.DATA_ONLY | address + data (raw bytes) | Fetch program data without metadata | | AccountView.FULL | address + meta + data | Complete account information |

BlockView

Controls how much of a block resource is returned:

import { BlockView } from "@thru/sdk";

// Fetch only block header (slot, hash, producer, etc.)
const block = await thru.blocks.get({ slot }, {
  view: BlockView.HEADER_ONLY,
});

// Fetch header and footer (execution status)
const block = await thru.blocks.get({ slot }, {
  view: BlockView.HEADER_AND_FOOTER,
});

// Fetch only block body (transactions)
const block = await thru.blocks.get({ slot }, {
  view: BlockView.BODY_ONLY,
});

// Fetch everything: header, body, and footer (default)
const block = await thru.blocks.get({ slot }, {
  view: BlockView.FULL,
});

| View Option | Returns | Use Case | | --- | --- | --- | | BlockView.HEADER_ONLY | Only block header (metadata) | Display block summary without transactions | | BlockView.HEADER_AND_FOOTER | header + footer (execution status) | Check execution status without transactions | | BlockView.BODY_ONLY | Only block body (transactions) | Fetch transactions without header metadata | | BlockView.FULL | header + body + footer | Complete block information |

TransactionView

Controls how much of a transaction resource is returned:

import { TransactionView } from "@thru/sdk";

// Fetch only transaction signature
const tx = await thru.transactions.get(signature, {
  view: TransactionView.SIGNATURE_ONLY,
});

// Fetch only transaction header (signature, fee payer, etc.)
const tx = await thru.transactions.get(signature, {
  view: TransactionView.HEADER_ONLY,
});

// Fetch header and body (instructions)
const tx = await thru.transactions.get(signature, {
  view: TransactionView.HEADER_AND_BODY,
});

// Fetch everything: header, body, and execution results (default)
const tx = await thru.transactions.get(signature, {
  view: TransactionView.FULL,
});

| View Option | Returns | Use Case | | --- | --- | --- | | TransactionView.SIGNATURE_ONLY | Only transaction signature | Quick existence check | | TransactionView.HEADER_ONLY | Only transaction header (signature, fee payer, compute budget) | Display transaction summary without instructions | | TransactionView.HEADER_AND_BODY | header + body (instructions) | Fetch transaction without execution results | | TransactionView.FULL | header + body + execution results | Complete transaction information |

Note: If no view is specified, the default is FULL for all resource types.

Streaming APIs

Every streaming endpoint yields an async iterable of domain models:

// Blocks
for await (const { block } of thru.streaming.streamBlocks()) {
  console.log(block.header.slot);
}

// Account updates
for await (const { update } of thru.streaming.streamAccountUpdates("taAddress")) {
  if (update.kind === "snapshot") {
    console.log(update.snapshot.account.meta?.balance);
  }
}

// Events
for await (const { event } of thru.streaming.streamEvents()) {
  console.log((event as ChainEvent).timestampNs);
}

// Transaction tracking for an existing signature. This is a live stream; when
// submitting a raw transaction yourself, prefer transactions.sendAndTrack().
for await (const update of thru.streaming.trackTransaction(signature)) {
  console.log(update.status, update.executionResult?.consumedComputeUnits);
}

Filters

Server-side filtering is supported everywhere via CEL expressions:

import { Filter, FilterParamValue } from "@thru/sdk";

const ownerFilter = new Filter({
  expression: "account.meta.owner.value == params.owner",
  params: {
    owner: FilterParamValue.pubkey("taExampleAddress..."),
    min_balance: FilterParamValue.uint(1_000_000n),
  },
});

const accounts = await thru.accounts.list({ filter: ownerFilter });

Accepted parameter kinds:

• stringValue
• bytesValue
• boolValue
• intValue
• doubleValue
• uintValue
• pubkeyValue
• signatureValue
• taPubkeyValue
• tsSignatureValue

Functions that take filters:

• List APIs: thru.accounts.list, thru.blocks.list, thru.transactions.listForAccount
• Streams: thru.streaming.streamBlocks, thru.streaming.streamAccountUpdates, thru.streaming.streamTransactions, thru.streaming.streamEvents

Use the helper constructors on FilterParamValue to safely build parameters from raw bytes, ta/ts-encoded strings, or simple numbers.

Modules Overview

• thru.blocks — fetch/stream blocks and height snapshots
• thru.accounts — read account state or build create-account transactions
• thru.transactions — build, sign, submit, track, and inspect transactions
• thru.events — query event history
• thru.proofs — generate state proofs
• thru.consensus — build version contexts and stringify consensus states
• thru.streaming — streaming wrappers for blocks, accounts, transactions, events
• thru.helpers — address, signature, and block-hash conversion helpers

The public surface is fully domain-based; reaching for lower-level protobuf structures is no longer necessary.

Streaming helpers

Async iterable utilities make it easier to consume streaming APIs:

import { collectStream, firstStreamValue } from "@thru/sdk";

const updates = await collectStream(thru.streaming.streamBlocks({ startSlot: height.finalized }), {
  limit: 5,
});

const firstEvent = await firstStreamValue(thru.streaming.streamEvents());

collectStream gathers values (optionally respecting AbortSignals), firstStreamValue returns the first item, and forEachStreamValue lets you run async handlers for each streamed update.

Explicit account compression and restoration

Compression is built into the normal client. No separate compression package, transport adapter, or program factory is needed. Canonical compression, multicall and uploader addresses are defaults; programAddresses provides optional overrides for private deployments.

import { createThruClient, CompressionError } from '@thru/sdk';

const sdk = createThruClient({ baseUrl });
const statuses = await sdk.compression.getAccountStatuses({ accounts });

try {
  const result = await sdk.compression.decompressAccounts({
    accounts,
    feePayer: { publicKey, privateKey }, // Same convention as buildAndSign.
    fee: 0n,
  });
  // Build and sign the application transaction AFTER restoration succeeds.
  // Prerequisite transactions may have advanced this payer's nonce.
} catch (error) {
  if (error instanceof CompressionError) {
    // NOT_READY includes details.retrySlot when known.
    // Preserve details.result (partial progress, signatures, upload handles).
    // TRANSACTION_UNCERTAIN must be reconciled before further submissions.
  }
  throw error; // Do not continue with the application transaction on failure.
}

Wallet callers use the existing transaction-intent signing flow. The wallet receives base64 instruction data and account addresses, and returns base64 signed transaction bytes. It never receives an SDK Transaction or exposes private keys:

const context = await wallet.getSigningContext();
await sdk.compression.decompressAccounts({
  accounts,
  feePayer: { publicKey: context.feePayerPublicKey },
  walletAddress,
  signTransaction: intent => wallet.signTransaction(intent),
});
// Now prepare and sign the application intent as usual.

For an existing signing session, use feePayer: { publicKey: session.publicKey }, walletAddress: session.walletAddress, and signTransaction: intent => session.signTransaction(intent) instead. The selected wallet address is not the managed fee payer. If wallet/session fallback changes the payer, the helper rejects before submitting: refresh the signing context and retry explicitly. The helper validates the signed passkey wrapper and nested instruction. Wallet intents currently use fee 0; keypair calls retain the SDK fee default unless overridden. Upload authority is the wallet account for wallet calls and the payer for keypair calls. Large wallet restores stage their proof in an upload account so variable passkey envelopes cannot invalidate proof pointers.

Small restorations batch through multicall; large images use temporary uploads. Successful earlier steps remain committed if later steps fail. Cooldown returns NOT_READY promptly. cleanupUploads({ uploads, feePayer, ... }) can retry cleanup from error.details.result.uploads; wallet cleanup also takes the wallet address and intent callback. Handles retain their uploader address across configuration changes. Unresolved submissions block cleanup that might destroy staging still needed by a pending restoration.

Each SDK client serializes compression operations per fee payer and remembers uncertain submissions across calls. Supply a stable journal with async load() and save(pending | undefined) to survive process/page restarts; store the pending signature, nonce and validity slot durably before sending. Scope the journal to one network and payer, and reuse it on subsequent calls or a new client. It must not contain private keys. sdk.compression.reconcilePending({ feePayer: { publicKey }, journal }) only reads chain/journal state and never signs. Do not discard a pending record to bypass uncertainty, or share the payer with concurrent application submissions. An advanced nonce with a missing execution result remains unresolved, even after expiry.

The compression service uses sdk.compression.compressAccount({ account, feePayer: { publicKey, privateKey }, fee: 0n, journal }). It handles eligibility, rate limits and scan checkpoints; the SDK handles the actual transaction and its reconciliation. Decompression is explicit and caller-funded. Existing build/sign/send APIs never automatically restore or retry application transactions.

Shared instruction codecs live in thru-ts-client-sdk/domain/programs and are re-exported by @thru/programs, so the SDK does not depend on that package. Regenerate them with node scripts/generate-compression-codecs.mjs (set THRU_ABI_BIN if the ABI CLI is not at its repository default path), and verify reproducibility with --check. The script reads the canonical ABI sources; the re-export shims in @thru/programs should not receive duplicate generated code.