@valve-tech/trueblocks-sdk 0.10.1 → 0.11.1

package/AGENTS.md

@@ -0,0 +1,225 @@
+# AGENTS.md
+
+Terse reference for AI agents (Claude Code, Cursor, Aider, etc.) integrating
+`@valve-tech/trueblocks-sdk`. The full README is for humans; this file is for
+agents that need to ground their work in the package's actual surface
+quickly.
+
+(For contributor-facing notes — codegen pipeline, file map,
+clean-room rule, test pattern — see `INTERNALS.md` in the package
+root, not shipped in the npm tarball.)
+
+## What this package does
+
+Typed TypeScript HTTP client to a running [TrueBlocks](https://trueblocks.io)
+`chifra daemon`. Same verb surface as the upstream Go SDK, delivered
+as `fetch`-based REST calls — no Go runtime, no subprocess spawning,
+browser/mobile safe.
+
+54 methods total: 18 base methods (one per chifra HTTP endpoint) +
+36 narrowed variant accessors on the polymorphic ones (e.g.
+`client.blocks.logs(...)` returns `Log[]` instead of the polymorphic
+`(Block | LightBlock | Log | …)[]` union).
+
+**No peer dependencies.** Uses `globalThis.fetch` (Node 18+, every
+modern browser).
+
+**Prerequisite:** a running `chifra daemon` somewhere this client
+can reach over HTTP. This package does NOT bundle or invoke chifra —
+the user installs `trueblocks-core` separately and indexes the chains
+they care about. If they can't run chifra, this package isn't for
+them.
+
+## Public API
+
+All exports live under `src/index.ts`. Single subpath; no sub-exports.
+
+```ts
+import {
+  createTrueblocksClient,             // primary constructor
+  TrueblocksError,                    // typed error class
+  // verb-machinery exports (rare to import directly)
+  createVerbs,
+  makeVerb,
+  // types
+  type CreateTrueblocksClientOptions,
+  type TrueblocksClient,
+  type FetchFn,
+  type RequestFn,
+  type Query,
+  type Response,
+  type VerbFn,
+  type Verbs,
+  type IsRequiredQuery,
+  // raw OpenAPI types (escape hatch when the verb wrapper isn't enough)
+  type components,
+  type operations,
+  type paths,
+} from '@valve-tech/trueblocks-sdk'
+```
+
+## Three things you must know
+
+| | |
+|---|---|
+| **Constructor** | `createTrueblocksClient({ baseUrl: 'http://localhost:8080' })` returns a `TrueblocksClient` with one method per chifra endpoint. Optional `fetch` override for testing or custom transport. |
+| **Verb shape** | Every chifra HTTP endpoint is a typed method on the client. Method names match the chifra CLI verbs (`list`, `export`, `blocks`, `transactions`, etc.). |
+| **Polymorphic vs variant** | Base methods return the OpenAPI polymorphic union (useful when flag combinations are constructed at runtime). Variants (`client.blocks.logs(...)`) preselect a flag and narrow the return type to the single concrete shape that flag produces. Mirrors the Go SDK's `XxxOptions.XxxFlag()` pattern. |
+
+## The verb surface (54 methods)
+
+| Group | Method | Endpoint | Variants |
+|---|---|---|---|
+| Accounts | `client.list(...)` | `GET /list` | — |
+| Accounts | `client.export(...)` | `GET /export` | `.appearances` `.receipts` `.logs` `.approvals` `.traces` `.neighbors` `.statements` `.transfers` `.assets` `.balances` `.withdrawals` `.count` |
+| Accounts | `client.monitors(...)` | `GET /monitors` | — |
+| Accounts | `client.names(...)` | `GET /names` | — |
+| Accounts | `client.abis(...)` | `GET /abis` | — |
+| Chain Data | `client.blocks(...)` | `GET /blocks` | `.hashes` `.uncles` `.traces` `.uniq` `.logs` `.withdrawals` `.count` |
+| Chain Data | `client.transactions(...)` | `GET /transactions` | `.traces` `.uniq` `.logs` |
+| Chain Data | `client.receipts(...)` | `GET /receipts` | — |
+| Chain Data | `client.logs(...)` | `GET /logs` | — |
+| Chain Data | `client.traces(...)` | `GET /traces` | `.count` |
+| Chain State | `client.when(...)` | `GET /when` | — |
+| Chain State | `client.state(...)` | `GET /state` | `.call` |
+| Chain State | `client.tokens(...)` | `GET /tokens` | — |
+| Admin | `client.config(...)` | `GET /config` | — |
+| Admin | `client.status(...)` | `GET /status` | — |
+| Admin | `client.chunks(...)` | `GET /chunks` | `.manifest` `.index` `.blooms` `.pins` `.addresses` `.appearances` `.stats` |
+| Admin | `client.init(...)` | `GET /init` | — |
+| Other | `client.slurp(...)` | `GET /slurp` | `.appearances` `.count` |
+
+`client.send(...)` (`chifra send`) is NOT exposed — the upstream
+OpenAPI spec doesn't currently cover it, and this package is
+codegen-driven so unspec'd endpoints are not in the surface. To send
+transactions, use a wallet library (viem/ethers/wagmi) or
+`@valve-tech/wallet-adapter` directly.
+
+## Polymorphic vs variant — when to use which
+
+```ts
+// Polymorphic — narrow at the call site:
+const result = await client.blocks({ blocks: ['18000000'], logs: true })
+// result.data is (Block | LightBlock | Log | …)[]
+if (result.data[0]?.address) {
+  // narrowed to Log
+}
+
+// Variant — concrete return type, no narrowing needed:
+const result = await client.blocks.logs({ blocks: ['18000000'] })
+// result.data is Log[]
+result.data[0]?.address  // ✓ already narrowed
+```
+
+Use the variant when the flag is known statically. Use the polymorphic
+shape when flag combinations are computed at runtime (e.g. building a
+chifra query from a UI toggle).
+
+## Errors
+
+Every chifra-side failure throws a `TrueblocksError`:
+
+```ts
+try {
+  await client.status()
+} catch (err) {
+  if (err instanceof TrueblocksError) {
+    err.path        // chifra endpoint that failed (e.g. '/status')
+    err.status      // HTTP status if applicable
+  }
+}
+```
+
+No silent fallbacks: if the daemon returns an error or an unexpected
+shape, you get a typed throw.
+
+## Pitfalls (read these)
+
+1. **Forgetting the daemon prerequisite.** This package is a *client* —
+   it talks to a running `chifra daemon`. If `baseUrl` doesn't have a
+   chifra serving on the other end, every call throws a
+   `TrueblocksError` with a connection failure. The package can't help
+   the user install or run chifra; redirect them to
+   https://trueblocks.io/docs/install/install-core/.
+
+2. **Calling `client.send(...)`.** It doesn't exist — chifra's send
+   surface isn't in the upstream OpenAPI spec, so it's not in the
+   typed client. To send a transaction, use viem/ethers/wagmi or
+   `@valve-tech/wallet-adapter`. Use trueblocks-sdk for the *read*
+   side (history, receipts, traces, balances).
+
+3. **Mixing `client.blocks(...)` polymorphic with branch-by-shape
+   logic.** When the result is the polymorphic union, narrow with a
+   type guard or an `if (data[0]?.specificField)` check. Use the
+   variant accessor (`client.blocks.logs(...)`) instead if the
+   polymorphism isn't load-bearing — it removes the narrowing
+   ceremony.
+
+4. **Treating `client.list(...)` results as full transactions.**
+   `list` returns *appearances* (lightweight pointers — `bn`/`tx_id`/
+   `address` triples), not full transactions or receipts. To go from
+   appearance to data, follow up with `client.transactions(...)` /
+   `client.receipts(...)`.
+
+5. **Calling `client.export(...)` without `addrs`.** Most `export`
+   variants are address-scoped — the request shape will be a TS
+   error if `addrs` is required, but worth flagging because the
+   error message points at the codegen'd schema, not the
+   human-readable docs.
+
+6. **Building URLs by hand to add a flag the SDK doesn't expose.**
+   The codegen'd types reflect the spec — every flag the spec
+   declares is on the verb method's `Query` type. If something
+   appears missing, check the chifra version pinned in
+   `scripts/codegen.mjs` (in the source repo) — the spec may be
+   newer than the pin.
+
+7. **bigint vs string at numeric boundaries.** Generated types
+   carry whatever the spec said (often `string` for safety —
+   block numbers, gas, fees can exceed 2^53). The verb wrappers
+   convert at the boundary where appropriate, but always-string
+   fields stay strings. Test before assuming a `bigint` arrived.
+
+8. **No retry / backoff built in.** The client makes one fetch call
+   per verb invocation. If the user wants retries, they wrap the
+   call themselves or pass a custom `fetch` that retries.
+
+## Composition
+
+trueblocks-sdk is read-side history/state. It composes with:
+
+- **`@valve-tech/wallet-adapter`** — for the write/send side, since
+  the SDK doesn't expose `send`.
+- **`@valve-tech/tx-tracker`** — for live per-tx state-machine work.
+  trueblocks gives you historical reads; tx-tracker watches
+  in-flight txs as they confirm. Different layers, complementary.
+- **`@valve-tech/chain-source`** — for raw block/mempool streams.
+  trueblocks is server-side indexed history; chain-source is local
+  RPC observation.
+
+## When to skip this package
+
+- **No running chifra daemon.** Use viem/ethers directly against an
+  RPC. Chifra's value is precomputed indexes (appearances,
+  monitors); without the daemon, this package is just an HTTP
+  client to an endpoint that won't respond.
+- **Live in-flight tx tracking.** Use `@valve-tech/tx-tracker`.
+  trueblocks is for historical reads, not push-style observation
+  of new chain events.
+- **Sending transactions.** Use a wallet library (or
+  `@valve-tech/wallet-adapter`). chifra's send surface isn't
+  exposed here.
+
+## Skills (for AI agents)
+
+`skills/` ships in the npm tarball. If you're an AI agent working in a
+project that has installed this package, look in
+`node_modules/@valve-tech/trueblocks-sdk/skills/trueblocks-sdk-integration/SKILL.md`
+for trigger conditions, anti-pattern flags, and integration recipes.
+
+## Verifying provenance
+
+```bash
+npm view @valve-tech/trueblocks-sdk@latest --json | jq .dist.attestations
+npm audit signatures
+```

package/CHANGELOG.md

@@ -6,6 +6,29 @@ this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/).
 
+## [0.11.1] — 2026-05-11
+
+### Notes
+
+- Synchronized release — no changes to this package. Republished at
+  0.11.1 alongside the rest of the toolkit; the substantive fix is
+  in `@valve-tech/tx-tracker` (upgrade-path crash on the first
+  block tick after upgrading a persistent store from ≤0.10 to
+  0.11.0). See `@valve-tech/tx-tracker`'s CHANGELOG for details.
+
+## [0.11.0] — 2026-05-11
+
+### Notes
+
+- Synchronized release — no changes to this package. Bumped in
+  lockstep with the rest of the toolkit alongside the v0.11.0
+  feature work in `@valve-tech/gas-oracle` (20-block ring lifecycle,
+  reorg detection, gap bridging), `@valve-tech/tx-tracker` (audit
+  fixes — durable rehydrate, retention enforcement, replaced-by
+  dedup, receipt-poll race, helper extraction), `@valve-tech/
+  wallet-adapter` (five wallet bridge examples), and
+  `@valve-tech/chain-source` (canonical-owner docs for wire types).
+
 ## [0.10.1] — 2026-05-08
 
 **First successful npm publish at the v0.10.x line.** v0.10.0's

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@valve-tech/trueblocks-sdk",
-  "version": "0.10.1",
+  "version": "0.11.1",
   "description": "Typed TypeScript HTTP client to a running TrueBlocks chifra daemon. Wraps chifra's REST surface (the same one served by `chifra daemon`) with TS types generated from the upstream OpenAPI spec; no Go runtime, no shelling-out.",
   "license": "MIT",
   "homepage": "https://github.com/valve-tech/evm-toolkit/tree/main/packages/trueblocks-sdk#readme",
@@ -32,7 +32,9 @@
   },
   "files": [
     "dist",
+    "skills",
     "README.md",
+    "AGENTS.md",
     "CHANGELOG.md",
     "LICENSE"
   ],

package/skills/trueblocks-sdk-integration/SKILL.md

@@ -0,0 +1,228 @@
+---
+name: trueblocks-sdk-integration
+description: Integrate `@valve-tech/trueblocks-sdk` — typed TypeScript HTTP client to a running TrueBlocks `chifra daemon` — into a dapp, indexer, analytics tool, or backend. Use when the user wants to query historical chain data via chifra (`list` appearances, `export` receipts/logs/transfers/balances, `blocks` / `transactions` / `receipts` / `traces` / `logs` reads, `monitors` / `names` / `abis` lookups, `when` / `state` / `tokens` chain-state queries, or `chunks` / `init` / `config` / `status` admin endpoints), is asking how to wire a chifra daemon URL into TS code, needs to discriminate the polymorphic `client.blocks(...)` return vs use a variant accessor like `client.blocks.logs(...)`, or sees imports from `@valve-tech/trueblocks-sdk`. Also fires for "how do I get all transfers for an address", "list ERC-20 holders", "address appearances", "decode receipts via chifra", or questions about `TrueblocksError`, the `baseUrl` option, the `fetch` override, the 54-method/36-variant surface, or why `client.send(...)` doesn't exist (the upstream OpenAPI spec doesn't cover chifra's send surface — that's intentional). Skip when the user wants to SEND transactions (delegate to wallet-adapter-integration — chifra's send isn't in the typed surface), wants live in-flight tx tracking via push/poll (delegate to tx-tracker-integration — trueblocks is historical reads, not live observation), wants raw RPC block/mempool streams (delegate to chain-source-integration), or doesn't have a running chifra daemon and isn't planning to install trueblocks-core (the SDK requires it; recommend they install or use a different read source like viem `client.getLogs` / The Graph / Alchemy enhanced APIs).
+---
+
+# Integrating `@valve-tech/trueblocks-sdk`
+
+Typed TypeScript HTTP client to a running TrueBlocks `chifra daemon`.
+Same verb surface as the upstream Go SDK, delivered as `fetch`-based
+REST calls. This skill is for AI agents working in a project that
+imports the package — especially helping the user pick the right verb
++ variant for what they're trying to read.
+
+## Hard prerequisite — flag this first
+
+The user **must** have a running `chifra daemon` reachable from their
+runtime. This package is a CLIENT, not a server. It does NOT bundle,
+spawn, or install chifra. If the user doesn't have chifra running,
+no amount of TS-side configuration helps.
+
+Before recommending integration code, confirm:
+- [ ] User has installed `trueblocks-core` (https://trueblocks.io/docs/install/install-core/).
+- [ ] User has indexed the chain(s) they care about (`chifra init`).
+- [ ] User has the daemon running (`chifra daemon`) and knows the URL
+      it's serving on (default `http://localhost:8080`).
+
+If any of these are unclear, ASK before writing code. A working
+client wired to a non-running daemon throws `TrueblocksError` on
+every call — frustrating, and the SDK can't help.
+
+## Decision tree: which verb to use
+
+```
+What does the user want to know?
+├── "Which transactions involve this address?"
+│       → client.list({ addrs: [address] })            (lightweight appearances)
+│
+├── "Full transactions / receipts / logs / transfers / balances for this address"
+│       → client.export(...) + the variant they want:
+│             .receipts / .logs / .transfers / .balances / .approvals / etc.
+│
+├── "Block X" / "blocks N..M"
+│       → client.blocks({ blocks: [...] }) + variant:
+│             .logs / .uncles / .traces / .withdrawals / .uniq / .count
+│
+├── "Transaction by hash"
+│       → client.transactions({ transactions: [...] }) + variant:
+│             .traces / .uniq / .logs
+│
+├── "Receipt(s) by hash"
+│       → client.receipts({ transactions: [...] })
+│
+├── "When did block X happen / what block was at timestamp T"
+│       → client.when({ blocks: [...] | timestamps: [...] })
+│
+├── "Read contract state / call view function"
+│       → client.state({ addrs, parts }) or client.state.call({ addrs, call })
+│
+├── "Token balances / transfers"
+│       → client.tokens({ addrs, blocks }) or client.export.balances(...)
+│
+├── "Daemon status / config / chunks"
+│       → client.status() / client.config() / client.chunks(...)
+│
+└── "Send a transaction"
+    → NOT in this SDK. Delegate to wallet-adapter-integration.
+```
+
+## How to recognize this package in the user's code
+
+```ts
+import {
+  createTrueblocksClient,
+  TrueblocksError,
+} from '@valve-tech/trueblocks-sdk'
+```
+
+`package.json` will show `"@valve-tech/trueblocks-sdk": "^0.10.x"`. No peer deps.
+
+## Canonical setup
+
+```ts
+import { createTrueblocksClient, TrueblocksError } from '@valve-tech/trueblocks-sdk'
+
+const client = createTrueblocksClient({
+  baseUrl: process.env.CHIFRA_URL ?? 'http://localhost:8080',
+  // optional: pass a custom fetch for retry/auth/logging
+  // fetch: myCustomFetch,
+})
+
+try {
+  const status = await client.status()
+  if (!status.is_responding) {
+    throw new Error('chifra daemon not ready')
+  }
+} catch (err) {
+  if (err instanceof TrueblocksError) {
+    console.error('chifra error', err.path, err.status, err.message)
+  }
+  throw err
+}
+```
+
+## Polymorphic vs variant — the most-likely-to-confuse decision
+
+`client.blocks(...)` (polymorphic) returns a union of every shape the
+flag combination COULD produce:
+
+```ts
+const result = await client.blocks({ blocks: ['18000000'], logs: true })
+// result.data is (Block | LightBlock | Log | Withdrawal | …)[]
+// — narrow with a type guard before accessing fields
+```
+
+`client.blocks.logs(...)` (variant) preselects the `logs` flag and
+narrows to the single concrete shape:
+
+```ts
+const result = await client.blocks.logs({ blocks: ['18000000'] })
+// result.data is Log[] — no narrowing needed
+```
+
+Use the variant when the flag is known at code-time. Use the
+polymorphic when flag combinations are computed at runtime (UI toggles,
+config-driven queries).
+
+## Anti-patterns to flag
+
+When reviewing user code, watch for these and suggest fixes:
+
+1. **Calling `client.send(...)`.** Doesn't exist. Chifra's send
+   surface isn't in the upstream OpenAPI spec, so it's not in the
+   typed client. Redirect: use viem / ethers / wagmi or
+   `@valve-tech/wallet-adapter` for the write side. Trueblocks is
+   read-only history.
+
+2. **No daemon URL guard.** A `createTrueblocksClient({ baseUrl })`
+   call to a non-running daemon doesn't fail at construction — it
+   fails on the first verb call. Add a `client.status()` probe at
+   startup if your code path needs early failure (boot, healthcheck,
+   smoke test).
+
+3. **Treating `client.list(...)` results as full transactions.**
+   `list` returns *appearances* — lightweight pointers (`bn`,
+   `tx_id`, `address`). To get full data, chain through
+   `client.transactions(...)` or `client.export(...)`:
+   ```ts
+   const apps = await client.list({ addrs: [address] })
+   const txs = await client.transactions({
+     transactions: apps.data.map(a => `${a.bn}.${a.tx_id}`),
+   })
+   ```
+
+4. **Polymorphic `client.blocks(...)` when a variant exists.** If
+   the flag is known statically, use the variant — narrower types,
+   no in-place narrowing required:
+   ```ts
+   // ❌ then narrows in user code
+   const r = await client.blocks({ blocks, logs: true })
+   const logs = (r.data as Log[]).filter(...)
+
+   // ✅ already narrowed
+   const r = await client.blocks.logs({ blocks })
+   r.data.filter(...)
+   ```
+
+5. **`client.export(...)` without `addrs`.** Most export variants
+   are address-scoped — TS will catch missing `addrs`, but the
+   error points at the generated schema. Reframe: "you need to
+   pass `addrs: [...]`".
+
+6. **Hand-building URLs to access a missing flag.** The codegen'd
+   types reflect the OpenAPI spec at the pinned chifra commit. If
+   a flag appears missing, check the spec version — chifra may
+   have advanced past the pin. The SDK doesn't expose runtime
+   escape-hatch URL building (deliberately, to keep the surface
+   typed).
+
+7. **bigint vs string at numeric boundaries.** Generated types
+   carry the spec's choice (often `string` for safety — block
+   numbers, gas, fees can exceed 2^53). The verb wrappers
+   convert at the boundary where appropriate, but always-string
+   fields stay strings. Don't `BigInt(field)` without checking
+   the type.
+
+8. **No retry / backoff for flaky daemon connections.** The
+   client makes one fetch call per verb. If the daemon is
+   intermittent, wrap the call (or pass a `fetch` override that
+   retries):
+   ```ts
+   createTrueblocksClient({
+     baseUrl,
+     fetch: async (url, init) => {
+       for (let attempt = 0; attempt < 3; attempt++) {
+         try { return await fetch(url, init) }
+         catch (e) { if (attempt === 2) throw e; await sleep(100 * 2**attempt) }
+       }
+       throw new Error('unreachable')
+     },
+   })
+   ```
+
+9. **Querying chains the daemon hasn't indexed.** chifra serves
+   only chains the user has run `chifra init` for. If they ask
+   about a new chain (e.g. they indexed mainnet but query
+   PulseChain), every call returns empty / errors. Confirm
+   indexed chains via `client.config()` if uncertain.
+
+## When to skip this package
+
+- **Sending transactions** — use wallet-adapter / viem / ethers.
+- **Live in-flight tx state-machine** — use `@valve-tech/tx-tracker`
+  (trueblocks is historical reads, not push observation).
+- **Raw block/mempool streams** — use `@valve-tech/chain-source`.
+- **No chifra daemon and not installing one** — recommend viem
+  `client.getLogs` / The Graph / Alchemy enhanced APIs / Etherscan
+  API instead. Don't try to make trueblocks work without its server.
+
+## Where to find more
+
+- Full API + types: `node_modules/@valve-tech/trueblocks-sdk/AGENTS.md`
+- Human-facing docs: `node_modules/@valve-tech/trueblocks-sdk/README.md`
+- Compiled output: `node_modules/@valve-tech/trueblocks-sdk/dist/`
+- Upstream chifra docs: https://trueblocks.io/docs/
+- Sibling skills:
+  - wallet-adapter-integration for the write/send side
+  - tx-tracker-integration for live tx watching
+  - chain-source-integration for raw RPC streams