API guide

Question answered by this guide: which dblurt API surface should I use, and where is the executable example?

Client is the main entrypoint.

const { Client } = require('@beblurt/dblurt');
const client = new Client(rpcList);

For canonical blockchain terminology, read Blockchain model. For exact signatures, use generated TypeDoc from the TypeScript source.

Pick the right surface

Need	Use	Layer	Backing API	Executable example
Current head / irreversible block	`client.condenser.getDynamicGlobalProperties()` or `client.blockchain`	Layer 1	`condenser_api`	`read-head-block.cjs`
Account balances / authorities / chain account state	`client.condenser.getAccounts()`	Layer 1	`condenser_api.get_accounts`	`read-account.cjs`
Account/stake/governance/social summaries	`client.read.getAccountSummary()`, `getOutgoingDelegationSummary()`, `getSocialGraphSummary()`, `getWitnessSummary()`, `estimateVoteValue()`	Layer 1 + optional Nexus profile	existing condenser/Nexus/tool primitives	TypeDoc / contract tests
Posting-authority validation for a key	`validatePostingAuthority()` or `client.condenser.validatePostingAuthority()`	Layer 1 helper	`condenser_api.get_accounts` when fetched	TypeDoc / contract tests
Social/community custom JSON preview	`buildFollowOperation()`, `buildReblogOperation()`, `buildCommunitySubscribeOperation()` and related builders	Layer 1 operation builder	local `custom_json` operation construction	TypeDoc / contract tests
Post/comment operation preview	`buildPostOperation()`, `buildReplyOperation()`, `buildUpdateOperation()`, metadata/permlink helpers	Layer 1 operation builder	local `comment` operation construction	TypeDoc / contract tests
Post/comment chain object	`client.condenser.getContent()`	Layer 1	`condenser_api.get_content`	`read-post.cjs`
Votes on a post/comment	`client.condenser.getActiveVotes()`	Layer 1	`condenser_api.get_active_votes`	`read-active-votes.cjs`
Operations in a block	`client.condenser.getOperations()`	Layer 1	`condenser_api.get_ops_in_block`	`read-block-operations.cjs`
Account operation history	`client.condenser.getAccountHistory()`	Layer 1	`condenser_api.get_account_history`	`read-account-history.cjs`
Witness information	`client.condenser.getWitnessByAccount()`	Layer 1	`condenser_api.get_witness_by_account`	`read-witness.cjs`
Bounded block iteration	`client.blockchain.getBlockNumbers()` / `getBlocks()`	Layer 1 helper	`condenser_api` helpers	`stream-block-numbers.cjs`
Ranked/social post discovery	`client.nexus.getRankedPosts()` / `getAccountPosts()` with typed option objects or positional compatibility	Nexus Layer 2	`bridge.get_ranked_posts`, `bridge.get_account_posts`	`read-nexus-ranked-posts.cjs`
Community discovery/details	`client.nexus.listCommunities()` / `getCommunity()`	Nexus Layer 2	`bridge`	`read-nexus-community.cjs`
Unwrapped RPC method	`client.call(api, method, params)`	depends on API	JSON-RPC 2.0 appbase	`generic-call.cjs`
Typed consumer compile path	package TypeScript declarations	local package surface	TypeScript	`read-account.ts`

Helper families

Helper	Layer	Purpose	Notes
`client.condenser`	Blurt Layer 1	compatibility API for accounts, blocks, content, discussions, witnesses, proposals	best first stop for read-only chain data
`client.database`	Blurt Layer 1	appbase database API calls such as config/version/account lists	use when an appbase method is not exposed through condenser helpers
`client.accountHistory`	Blurt Layer 1	account-history API object-param helpers	useful for virtual operations and block-operation envelopes
`client.broadcast`	Blurt Layer 1	prepare/sign/broadcast operations	has side effects; read Broadcasting before use
`client.blockchain`	Blurt Layer 1 helper	high-level block/operation iterators	prefer irreversible mode for examples and replay tools
`client.nexus`	Nexus Layer 2	Bridge/Nexus social and indexed views	discovery layer; not Layer 1 consensus truth
`client.read`	Layer 1/Nexus composition	structured read models for account, stake, social graph, witnesses and vote value	data models only; no natural-language/LLM formatting or fiat pricing
`client.tools`	Utility	local calculations / helper serialization	not a replacement for chain reads

Layer distinction

Layer	Source	Typical dblurt surface	Trust model
Blurt Layer 1	Core Blurt RPC nodes	`condenser`, `database`, `accountHistory`, `broadcast`, `blockchain`	canonical chain data
Nexus Layer 2	Bridge/Nexus indexer exposed through RPC nodes	`nexus`	indexed/social views derived from chain data

When exact chain state matters, treat Blurt Layer 1 as the source of truth. Use Nexus to discover or enrich social views, then use Layer 1 helpers when you need canonical chain objects.

Generic RPC calls

Use client.call(api, method, params) when a method is not wrapped by a helper.

const result = await client.call('database_api', 'get_dynamic_global_properties', []);

The canonical wire request is JSON-RPC 2.0 appbase style:

{
  "id": 0,
  "jsonrpc": "2.0",
  "method": "database_api.get_dynamic_global_properties",
  "params": []
}

See ../examples/node/generic-call.cjs for a runnable example.

Error taxonomy

dblurt preserves the historical Error.name and message behavior for existing thrown errors while adding typed metadata for consumers that need structured handling.

import { classifyError, isDBlurtError, ValidationError } from '@beblurt/dblurt';

try {
    // SDK call, operation builder, signing flow, or RPC call
} catch (error) {
    const metadata = classifyError(error);
    if (metadata.retryable) {
        // retry, fail over, or surface a transient-network hint
    }
    if (isDBlurtError(error) && error.category === 'validation') {
        // field/path can guide user correction
    }
}

Stable metadata includes category, code and retryable, with optional safe details such as rpc_code, rpc_data, field, path, cause_code, cause_name and cause_message. The first implemented categories are rpc_application, serialization, validation, transport, timeout and unknown. Private key material and sensitive signing data are not included in metadata.

Common pitfalls

Do not treat Nexus responses as Layer 1 consensus objects.
Do not use broadcast helpers in examples unless the side effects and required authority are explicit.
Do not pass string values for BlockchainMode; use the exported enum.
Do not assume every account is a witness; discover witnesses first when needed.
Do not copy examples/_load-dblurt.cjs into applications. It is a repository-validation helper only.