@thru/sdk 0.2.22

package/README.abi.md

@@ -0,0 +1,112 @@
+# @thru/sdk/abi – WASM-backed ABI reflection
+
+This package is now a thin TypeScript wrapper around the Rust `abi_reflect`
+runtime. We compile the Rust crate to WebAssembly, ship both Node + bundler
+targets, and expose a small async API for reflecting ABI YAML + binary payloads.
+All layout math and validation run inside the Rust engine so TypeScript stays
+lightweight and automatically inherits IR upgrades.
+
+---
+
+## Quick start
+
+```ts
+import { ensureWasmLoaded, formatReflection, reflect } from "@thru/sdk/abi";
+import tokenAbi from "./abi/token_program.abi.yaml?raw";
+
+async function example() {
+  await ensureWasmLoaded(); // formatter + reflector live inside WASM
+
+  const payload = new Uint8Array([0x01, 0, 0, 0, 0, 0, 0, 0]);
+  const reflection = await reflect(tokenAbi, "TokenInstruction", {
+    type: "binary",
+    value: payload,
+  });
+
+  console.log(reflection.value); // JSON emitted by abi_reflect
+
+  // Collapse the verbose JSON tree into something human-readable
+  const formatted = formatReflection(reflection);
+  console.log(formatted.value.payload.variant); // "initialize_mint"
+}
+
+example();
+```
+
+* The ABI text **must already be flattened** (imports resolved). The Rust
+  resolver enforces this.
+* Results are JSON blobs straight from `serde_json`. They include the full type
+  info + value trees used by the CLI tooling.
+
+---
+
+## Public API
+
+| Function | Description |
+| --- | --- |
+| `reflect(abi: string, typeName: string, payload: { type: "binary", value: BinaryLike } \| { type: "hex", value: string })` | Reflects binary data (or hex) and returns the parsed JSON payload. |
+| `formatReflection(raw: JsonValue)` | Delegates to the WASM formatter to collapse verbose JSON trees. Requires `ensureWasmLoaded()` (or any prior call to `reflect`) before use. |
+| `buildLayoutIr(abi: string)` | Runs the shared Layout IR builder and returns the serialized IR document (schema version, per-type expressions, parameters). |
+| `ensureWasmLoaded()` | Preloads the WASM bindings for callers that want to pay the initialization cost up-front. `reflect` calls it lazily. |
+
+All helpers are async, because loading + instantiating the WASM module can touch
+the filesystem (Node) or issue dynamic imports (bundlers).
+
+---
+
+## WASM workflow
+
+The generated artifacts are staged under `web/packages/sdk/wasm/abi/{bundler,node,web}`
+before package builds. They are ignored in git, but copied into `dist/abi/wasm`
+so published packages work without a local Rust toolchain. When `abi_reflect` or
+the shared IR changes, rebuild everything with:
+
+```bash
+# From repo root
+pnpm --filter @thru/sdk run build:wasm
+```
+
+That script runs `wasm-pack build` three times (bundler + node + web targets) inside
+`rpc/abi/abi_reflect_wasm`, then copies the fresh outputs into
+`web/packages/sdk/wasm/abi`. The regular `pnpm --filter @thru/sdk build` step runs
+`tsup` and copies those WASM folders into `dist/abi/wasm` so published packages
+resolve the dynamic imports automatically.
+
+When developing inside the monorepo, Vitest loads the TypeScript sources
+directly. The runtime detects when it is executing from `src/` and reaches for
+`../wasm`, so make sure the synced artifacts exist before running the tests.
+
+---
+
+## Testing
+
+```bash
+pnpm --filter @thru/sdk test
+```
+
+Vitest exercises both `reflectHex` and `reflectBinary` against the
+`SimpleStruct` compliance ABI plus `buildLayoutIr` to ensure the WASM bridge is
+wired correctly. If you tweak the Rust runtime, rerun `pnpm build:wasm` so the
+tests pick up the updated binaries.
+
+---
+
+## Development notes
+
+* The TypeScript surface intentionally stays tiny; we no longer export the old
+  decoder/resolver classes. Future code should talk to the WASM bridge instead
+  of re-implementing reflection logic in JS.
+* Browser vs. Node detection happens in `src/wasmBridge.ts`. Node loads the
+  `wasm/node` build via `createRequire`, while bundlers dynamically import the
+  `wasm/bundler` module.
+* The JSON shape returned by `reflect*` matches `abi_reflect`'s CLI output, so
+  parity debugging can use the `abi-reflect` CLI under `rpc/abi/abi_reflect`.
+* Layout IR consumers can feed `buildLayoutIr` into caches or ship a prebuilt
+  snapshot alongside the WASM runtime to guard against future schema changes.
+
+---
+
+Questions? Ping the thru-net ABI team (same folks maintaining
+`rpc/abi/abi_reflect`). Whenever you extend the Rust reflection engine or shared IR,
+regenerate the WASM artifacts and mention the change in `enums-fam-impl.md` so
+tooling consumers know which version to depend on.

package/README.md

@@ -0,0 +1,342 @@
+# @thru/sdk
+
+Typed TypeScript/JavaScript client for talking to the Thru blockchain. The SDK exposes rich domain models (blocks, accounts, transactions, events, proofs) that hide the underlying protobuf transport.
+
+## Installation
+
+```bash
+npm install @thru/sdk
+```
+
+### TypeScript Configuration
+
+For optimal import resolution, use modern module resolution:
+
+```json
+{
+  "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
+
+```ts
+import { createThruClient } from "@thru/sdk";
+import {
+  Account,
+  Block,
+  ChainEvent,
+  Transaction,
+  TransactionStatusSnapshot,
+} from "@thru/sdk";
+
+const thru = createThruClient({
+  baseUrl: "https://grpc-web.alphanet.thruput.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, signature } = await thru.transactions.buildAndSign({
+  feePayer: {
+    publicKey: "taFeePayerAddress...",
+    privateKey: feePayerSecretKeyBytes,
+  },
+  program: programIdentifierBytes,
+});
+await thru.transactions.send(rawTransaction);
+
+// Track the transaction – emits domain snapshots
+for await (const update of thru.streaming.trackTransaction(signature)) {
+  console.log(update.status, update.executionResult?.consumedComputeUnits);
+  if (update.statusCode === ConsensusStatus.FINALIZED) break;
+}
+```
+
+## Client Configuration
+
+`createThruClient` accepts advanced transport options so you can customize networking, interceptors, and default call behaviour:
+
+```ts
+const thru = createThruClient({
+  baseUrl: "https://grpc-web.alphanet.thruput.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.
+
+## 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:
+
+```ts
+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.
+
+```ts
+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:
+
+```ts
+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:
+
+```ts
+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:
+
+```ts
+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:
+
+```ts
+// 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 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:
+
+```ts
+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:
+
+```ts
+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 `AbortSignal`s), `firstStreamValue` returns the first item, and `forEachStreamValue` lets you run async handlers for each streamed update.