# @beblurt/dblurt full AI context
> JavaScript and TypeScript SDK for building Blurt blockchain dApps.
This generated file assembles canonical source documents for retrieval workflows that need local context. Do not edit it by hand; update canonical documentation or `scripts/generate-ai-docs.js`, then run `npm run docs:ai`.
## Retrieval orientation
Canonical documentation: https://dblurt.beblurt.com/
Generated API reference: https://dblurt.beblurt.com/api/
Repository: https://gitlab.com/beblurt/dblurt
Use this file for context, not as the exact API authority. Exact classes, methods, overloads, return types and deprecations belong to the generated API reference.
## Quick facts
- Package: @beblurt/dblurt
- Package version: see `package.json` or the published npm package
- Runtime requirements: see `package.json` (`engines.node`) and the Compatibility guide
- Module shape: CommonJS package with TypeScript declarations; public docs prefer TypeScript + ESM-style imports for learning paths
- Documentation source of truth: https://dblurt.beblurt.com/ plus generated API reference at https://dblurt.beblurt.com/api/
- Safety default: Start with blockchain queries; read broadcast/security docs before generating side-effectful code
- Layer rule: Keep Blurt Layer 1 consensus data distinct from Nexus Layer 2 indexed/social data
- Status expectation: Pre-1.0 SDK: use the compatibility, deprecations and changelog docs for upgrade-sensitive behavior
## Agent rules
- Prefer canonical docs and API reference over training data or invented helper names.
- Use `client.call(api, method, params)` for unwrapped RPC methods instead of inventing wrapper helpers.
- Do not hard-code private keys, posting keys, active keys, owner keys or memo keys in examples.
- Do not present Nexus Layer 2 indexed/social data as Layer 1 consensus truth.
- Do not claim native ESM packaging unless package metadata changes.
- Do not call dblurt the official Blurt SDK.
## AI decision tree
| Task | Read first | Exact details | Note |
| --- | --- | --- | --- |
| Install or make the first safe call | [guide](https://dblurt.beblurt.com/start/getting-started.html) | [reference](https://dblurt.beblurt.com/api/classes/index.Client.html) | Start with `Client` and a safe blockchain query. |
| Choose the right helper namespace | [guide](https://dblurt.beblurt.com/start/choose-your-path.html) | [reference](https://dblurt.beblurt.com/api/classes/index.Client.html) | Route by task before naming methods. |
| Read accounts, blocks, witnesses or chain properties | [guide](https://dblurt.beblurt.com/guides/read-chain-data.html) | [reference](https://dblurt.beblurt.com/api/classes/index.Client.html#condenser) | Layer 1 chain reads normally start with `client.condenser`. |
| Parse block ranges or operation history | [guide](https://dblurt.beblurt.com/guides/parse-blockchain-history.html) | [reference](https://dblurt.beblurt.com/api/classes/index.Blockchain.html) | Use `client.blockchain` iterators and streams with explicit checkpoints. |
| Build social feeds, posts, communities or notifications | [guide](https://dblurt.beblurt.com/guides/use-nexus-social-data.html) | [reference](https://dblurt.beblurt.com/api/classes/index.Nexus.html) | Nexus is indexed/social Layer 2 data, not consensus truth. |
| Build post, reply, follow, reblog or community operations | [guide](https://dblurt.beblurt.com/guides/publish-content.html) | [reference](https://dblurt.beblurt.com/api/functions/index.buildPostOperation.html) | Builders create operations; broadcasting is a separate safety decision. |
| Encrypt/decrypt memos or work with keys | [guide](https://dblurt.beblurt.com/guides/memo-and-key-utilities.html) | [reference](https://dblurt.beblurt.com/api/functions/index.encodeMemo.html) | Memo keys encrypt/decrypt; broadcast authorities sign transactions. |
| Sign or broadcast a transaction | [guide](https://dblurt.beblurt.com/guides/broadcast-safely.html) | [reference](https://dblurt.beblurt.com/api/classes/index.Client.html#broadcast) | Read authority and key guidance first. |
| Handle timeouts, RPC errors or retryability | [guide](https://dblurt.beblurt.com/guides/handle-errors.html) | [reference](https://dblurt.beblurt.com/api/functions/index.classifyError.html) | Classify before retrying or changing endpoints. |
| Use the SDK in browser or bundlers | [guide](https://dblurt.beblurt.com/guides/runtime-and-browser.html) | [reference](https://dblurt.beblurt.com/reference/compatibility.html) | Check bundle and signing constraints before browser examples. |
| Need exact method names, options or return types | [guide](https://dblurt.beblurt.com/reference/api.html) | [reference](https://dblurt.beblurt.com/api/) | Use generated API reference for exact details. |
## Common API entry points
- [`Client`](https://dblurt.beblurt.com/api/classes/index.Client.html): Main SDK entry point and helper namespace container.
- [`ClientOptions`](https://dblurt.beblurt.com/api/interfaces/index.ClientOptions.html): Endpoint, timeout and failover options for client construction.
- [`client.condenser`](https://dblurt.beblurt.com/api/classes/index.Client.html#condenser): Common Layer 1 reads such as accounts, content, witnesses and chain properties.
- [`client.database`](https://dblurt.beblurt.com/api/classes/index.Client.html#database): Appbase database API calls.
- [`client.blockchain`](https://dblurt.beblurt.com/api/classes/index.Client.html#blockchain): Block ranges, block streams and operation iteration.
- [`Blockchain`](https://dblurt.beblurt.com/api/classes/index.Blockchain.html): Layer 1 block and operation parsing helpers.
- [`Nexus` / `client.nexus`](https://dblurt.beblurt.com/api/classes/index.Nexus.html): Nexus indexed/social views for posts, communities, profiles and notifications.
- [`ReadModels` / `client.read`](https://dblurt.beblurt.com/api/classes/index.ReadModels.html): Higher-level account, witness, vote and social summaries.
- [`Asset`](https://dblurt.beblurt.com/api/classes/index.Asset.html): Parse, validate, format and manipulate symbol-preserving asset values.
- [`Price`](https://dblurt.beblurt.com/api/classes/index.Price.html): Convert between two supplied asset symbols using an explicit price pair.
- [`buildPostOperation`](https://dblurt.beblurt.com/api/functions/index.buildPostOperation.html): Construct a post operation without signing or broadcasting.
- [`buildDeleteCommentOperation`](https://dblurt.beblurt.com/api/functions/index.buildDeleteCommentOperation.html): Construct a delete_comment operation without signing or broadcasting.
- [`encodeMemo` / `decodeMemo`](https://dblurt.beblurt.com/api/functions/index.encodeMemo.html): Encrypt and decrypt Blurt memo strings.
- [`client.transactionStatus`](https://dblurt.beblurt.com/api/classes/index.Client.html#transactionstatus): Check transaction status after broadcast when public nodes expose transaction_status_api.
- [`classifyError`](https://dblurt.beblurt.com/api/functions/index.classifyError.html): Classify SDK, timeout, transport and RPC errors.
- [`validatePostingAuthority`](https://dblurt.beblurt.com/api/functions/index.validatePostingAuthority.html): Validate whether a key satisfies posting authority.
- [`Client.broadcast`](https://dblurt.beblurt.com/api/classes/index.Client.html#broadcast): Signing and broadcasting surface; use only after reading safety guidance.
- [`client.call(api, method, params)`](https://dblurt.beblurt.com/api/classes/index.Client.html#call): Escape hatch for unwrapped RPC methods; use instead of hallucinating wrappers.
## Included canonical sources
- [Getting started](#getting-started): Install the SDK and make a safe first Blurt blockchain call.
- [Choose your path](#choose-your-path): Pick the right helper family for your application workflow.
- [Blurt mental model](#blurt-mental-model): Core Blurt concepts through the dblurt SDK lens.
- [Layer 1 and Nexus Layer 2](#layer-1-and-nexus-layer-2): How consensus chain data differs from indexed social data.
- [For Hive/Steem developers](#for-hive-steem-developers): Comparative orientation for developers coming from Hive, Steem or Graphene-family SDKs.
- [Accounts and authorities](#accounts-and-authorities): Account authority, key and least-privilege concepts.
- [Blockchain queries vs broadcast operations](#blockchain-queries-vs-broadcast-operations): The safe learning path from reads to side effects.
- [site/learn/assets-operations-transactions.md](#site-learn-assets-operations-transactions-md): Canonical repository documentation source.
- [Read chain data](#read-chain-data): Use Layer 1 helpers for accounts, blocks, witnesses and chain properties.
- [Use Nexus social data](#use-nexus-social-data): Build social/community views using indexed data.
- [Parse blockchain history](#parse-blockchain-history): Iterate block ranges, full blocks and operation streams.
- [Publish content](#publish-content): Build content operations before deciding how to broadcast them.
- [Social actions](#social-actions): Build follow, mute, reblog and community action operations.
- [Broadcast safely](#broadcast-safely): Sign and broadcast with explicit key and side-effect boundaries.
- [Memo and key utilities](#memo-and-key-utilities): Work with Blurt keys, signatures and encrypted memos.
- [Read models](#read-models): High-level account, witness, vote and social summaries.
- [Handle errors](#handle-errors): Error taxonomy and retry behavior.
- [Runtime and browser](#runtime-and-browser): Understand Node.js, browser and bundle constraints.
- [RPC endpoints and failover](#rpc-endpoints-and-failover): Configure endpoint lists and failure behavior.
- [TypeScript](#typescript): Preferred TypeScript and ESM-style usage.
- [Recipes index](#recipes-index): Task-oriented workflows and safety levels.
- [Read account summary](#read-account-summary): Read account, stake and social summary data.
- [List account posts](#list-account-posts): Read recent posts for an account using Nexus social data.
- [Estimate vote value](#estimate-vote-value): Estimate current vote value from existing primitives.
- [Parse recent blocks](#parse-recent-blocks): Bounded block parsing with `client.blockchain.getBlocks()`.
- [Read account history](#read-account-history): Audit account and virtual operation history.
- [Build post operation](#build-post-operation): Construct content operations without broadcasting.
- [Sign and broadcast vote](#sign-and-broadcast-vote): Safety-focused side-effectful vote workflow.
- [Handle retryable errors](#handle-retryable-errors): Classify timeout, transport and RPC errors.
- [API reference landing](#api-reference-landing): Human router to exact API details.
- [Compatibility](#compatibility): Runtime and browser support model.
- [Deprecations](#deprecations): Deprecated APIs and compatibility lifecycle guidance.
- [Errors](#errors): Error taxonomy and retryability guidance.
- [Package exports](#package-exports): Import and runtime compatibility details.
- [Executable examples catalog](#executable-examples-catalog): Repository examples with metadata and validation status.
- [AI context overview](#ai-context-overview): How AI assistants should route to canonical docs.
- [AI coding rules](#ai-coding-rules): Durable coding constraints for assistants.
- [AI pitfalls](#ai-pitfalls): Common mistakes assistants should avoid.
- [AI security constraints](#ai-security-constraints): Key, authority, browser and broadcast safety constraints.
- [Repository agent instructions](#repository-agent-instructions): Minimal coding-agent workflow rules.
- [Security policy](#security-policy): Responsible disclosure and maintainer security expectations.
---
## Getting started
Source: site/start/getting-started.md
Canonical URL: https://dblurt.beblurt.com/start/getting-started.html
Purpose: Install the SDK and make a safe first Blurt blockchain call.
# Getting started
This guide gets a Node.js project connected to Blurt with a safe blockchain query workflow.
It deliberately does not use private keys and does not broadcast transactions. First learn to read, then learn authorities and signing.
## Prerequisites
You need:
- Node.js supported by the package metadata;
- a project with npm;
- network access to Blurt RPC endpoints.
For runtime support details, see [Compatibility](../reference/compatibility.md).
## 1. Install
```bash
npm install @beblurt/dblurt
```
## 2. Create a client
```ts
import { Client } from '@beblurt/dblurt';
const rpcList = [
'https://rpc.blurt.blog',
'https://blurt-rpc.saboin.com',
'https://rpc.beblurt.com',
'https://blurtrpc.dagobert.uk',
'https://rpc.drakernoise.com'
];
const client = new Client(rpcList, {
timeout: 15_000,
failoverThreshold: 3
});
```
Why an endpoint list? Blockchain RPC endpoints can lag, fail or be temporarily unreachable. A list lets the SDK fail over instead of making your app depend on one URL.
Endpoint strategy is explained later in [RPC endpoints and failover](../guides/rpc-endpoints-and-failover.md).
## 3. Read current chain state
```ts
const props = await client.condenser.getDynamicGlobalProperties();
console.log({
head: props.head_block_number,
irreversible: props.last_irreversible_block_num,
time: props.time
});
```
This is a Layer 1 read. It asks a Blurt RPC node for dynamic global properties such as head block and last irreversible block.
The head block is the latest block known by the endpoint. The last irreversible block is the safer reference when a workflow needs stable history.
## 4. Load an account
```ts
async function loadAccount(name: string) {
const accounts = await client.condenser.getAccounts([name]);
return accounts[0];
}
const account = await loadAccount('beblurt');
if (!account) {
console.log('account not found');
} else {
console.log(account.name);
console.log(account.balance);
console.log(account.vesting_shares);
}
```
Account state is also Layer 1 data. It includes balances, authorities and other chain account fields exposed by the RPC API.
## 5. Query social data with Nexus
```ts
const posts = await client.nexus.getRankedPosts({
sort: 'trending',
limit: 10,
tag: 'blurt',
observer: null
});
for (const post of posts) {
console.log(`${post.author}/${post.permlink}: ${post.title}`);
}
```
This is a Nexus Layer 2 query. It is useful for building social interfaces because Nexus exposes ranked and indexed views. Do not treat it as replacing Layer 1 consensus state.
## 6. API details
Use the API reference when you need exact signatures:
- [`Client`](/api/classes/index.Client.html)
- [`ClientOptions`](/api/interfaces/index.ClientOptions.html)
- [`Nexus.getRankedPosts`](/api/classes/index.Nexus.html#getRankedPosts)
## 7. What you learned
You have now used three important surfaces:
| Goal | Surface | Layer |
| --- | --- | --- |
| Create an SDK client | `new Client(...)` | SDK |
| Read chain properties | `client.condenser` | Blurt Layer 1 |
| Read account state | `client.condenser` | Blurt Layer 1 |
| Read ranked social posts | `client.nexus` | Nexus Layer 2 |
## Next steps
- Learn the domain vocabulary: [Blurt mental model](../learn/blurt-mental-model.md)
- Understand Layer 1 vs indexed social data: [Layer 1 and Nexus Layer 2](../learn/layer-1-and-nexus.md)
- Pick the right helper family: [Choose your path](./choose-your-path.md)
- Browse task examples: [Recipes](../recipes/index.md)
- Use exact API details: [API reference](../reference/api.md)
::: tip Blockchain queries first
You do not need a private key for any example on this page. Private keys appear only in signing and broadcast workflows.
:::
---
## Choose your path
Source: site/start/choose-your-path.md
Canonical URL: https://dblurt.beblurt.com/start/choose-your-path.html
Purpose: Pick the right helper family for your application workflow.
# Choose your path
`dblurt` has several helper families because Blurt applications do several different jobs. Start from your goal, then choose the API surface.
If you need exact method signatures, go to the [API reference](../reference/api.md). This page helps you decide where to start.
## I want to make my first blockchain query
Use `Client` plus `client.condenser`.
```ts
import { Client } from '@beblurt/dblurt';
const client = new Client(rpcList);
const props = await client.condenser.getDynamicGlobalProperties();
console.log(props.head_block_number);
```
Next: [Getting started](./getting-started.md).
## I want account, content, witness or block data
Use Layer 1 helpers.
| Goal | Start with | Why |
| --- | --- | --- |
| Account state, balances, authorities | `client.condenser.getAccounts()` | common Layer 1 account read |
| Content by author/permlink | `client.condenser.getContent()` | canonical chain content object |
| Active votes | `client.condenser.getActiveVotes()` | Layer 1 vote data |
| Witness details | `client.condenser.getWitnessByAccount()` | witness data is Layer 1 |
| Block ranges or operation streams | `client.blockchain` | higher-level iteration helpers |
| Appbase database methods | `client.database` | direct database API wrappers |
| Account or virtual operation history | `client.accountHistory` | object-param history helpers |
Concept: [Blurt mental model](../learn/blurt-mental-model.md). Task guides: [Read chain data](../guides/read-chain-data.md) and [Parse blockchain history](../guides/parse-blockchain-history.md).
## I want ranked feeds, communities, profiles or notifications
Use `client.nexus`.
Nexus is the right starting point for social/indexed views:
- trending/hot/created post lists;
- account post lists;
- communities;
- profiles;
- discussions;
- notifications;
- referrals.
```ts
const posts = await client.nexus.getRankedPosts({
sort: 'trending',
limit: 10,
tag: 'blurt',
observer: null
});
```
Concept: [Layer 1 and Nexus Layer 2](../learn/layer-1-and-nexus.md). Task guide: [Use Nexus social data](../guides/use-nexus-social-data.md).
## I want to parse blocks or operations
Use `client.blockchain` when your application needs to iterate block ranges or operation streams.
```ts
for await (const block of client.blockchain.getBlocks({ from, to })) {
console.log(block.transactions.length);
}
```
Task guide: [Parse blockchain history](../guides/parse-blockchain-history.md).
## I want application-ready summaries
Use `client.read` when you want structured read models rather than raw RPC objects.
Read models compose lower-level helpers into data structures for common application needs such as account summaries, stake, social graph summaries, witness summaries and vote-value estimates.
Read models are still SDK data models. They are not natural-language summaries, UI components or app policy.
Task guide: [Read models](../guides/read-models.md).
## I want to build an operation without broadcasting
Use operation builders.
Examples include content builders and social `custom_json` builders. They return operation payloads that applications can preview, test, confirm, externally sign or broadcast later.
```ts
import { buildPostOperation } from '@beblurt/dblurt';
const operation = buildPostOperation({
author: 'alice',
title: 'Hello Blurt',
body: 'Body text',
tags: ['blurt', 'sdk']
});
```
Task guides: [Publish content](../guides/publish-content.md) and [Social actions](../guides/social-actions.md).
## I want to sign or broadcast a transaction
Use `client.broadcast`, but only after you understand authorities and side effects.
Broadcasting requires a private key satisfying the operation's authority. Once a transaction is accepted by the chain, it has real effects.
Learn first:
1. [Accounts and authorities](../learn/accounts-and-authorities.md)
2. [Blockchain queries vs broadcast operations](../learn/blockchain-queries-vs-broadcast-operations.md)
3. [Broadcast safely](../guides/broadcast-safely.md)
## I want to use a raw RPC method
Use `client.call(api, method, params)` when a JSON-RPC method is not wrapped by a helper.
```ts
const result = await client.call('database_api', 'get_dynamic_global_properties', []);
```
Use this when you know the backing API method and want direct access without waiting for a helper wrapper.
## I want browser or TypeScript guidance
Use these paths:
- [Runtime and browser](../guides/runtime-and-browser.md) for browser bundle and runtime expectations.
- [TypeScript](../guides/typescript.md) for imports, public types and strict-mode usage.
- [Compatibility](../reference/compatibility.md) for support/validation status.
## API symbol shortcuts
Common API reference entry points:
- [`Client`](/api/classes/index.Client.html)
- [`Nexus`](/api/classes/index.Nexus.html)
- [`ReadModels`](/api/classes/index.ReadModels.html)
- [`buildPostOperation`](/api/functions/index.buildPostOperation.html)
- [`classifyError`](/api/functions/index.classifyError.html)
## I want exact API details
Use [API reference](../reference/api.md).
Concept pages explain choices and workflows. The API reference owns exact classes, methods, parameters, return types, overloads and deprecation annotations.
---
## Blurt mental model
Source: site/learn/blurt-mental-model.md
Canonical URL: https://dblurt.beblurt.com/learn/blurt-mental-model.html
Purpose: Core Blurt concepts through the dblurt SDK lens.
# Blurt mental model
Before choosing APIs, learn the words the SDK uses. `dblurt` is easier to use when you distinguish chain concepts from SDK helper names.
This page is conceptual. Exact TypeScript shapes are in the [API reference](../reference/api.md).
## The shortest model
```text
A Blurt block contains transactions.
A transaction contains operations.
Operations change or query Layer 1 state.
Authorities decide which keys can sign actions.
Nexus indexes social views derived from chain data.
```
## Layer 1
Blurt Layer 1 is the blockchain consensus layer. It is responsible for canonical chain data:
- blocks;
- transactions;
- operations;
- accounts;
- authorities;
- balances and assets;
- witnesses;
- irreversible history;
- virtual operations emitted by protocol processing.
In `dblurt`, Layer 1 reads are usually accessed through `client.condenser`, `client.database`, `client.accountHistory` and `client.blockchain`. Layer 1 writes go through signed transactions prepared and submitted with broadcast helpers.
## Blocks and finality
A block is an ordered unit of chain history. Developer docs should distinguish:
| Concept | Meaning | When to care |
| --- | --- | --- |
| Head block | latest block known by an RPC node | live dashboards and recent state |
| Reversible block | recent block that may be affected by fork resolution | avoid treating it as final |
| Last irreversible block | block considered irreversible by consensus | history scans and correctness-sensitive reads |
When an example prints both head and irreversible heights, it is showing live chain status. When a workflow requires stable history, prefer irreversible block ranges.
## Transactions and operations
A transaction is the signed payload submitted to the chain.
An operation is one action inside that transaction.
Examples of operations include:
- vote;
- comment/post;
- transfer;
- custom JSON social actions;
- account updates;
- witness votes.
Use “operation” when explaining what action is being performed. Use “transaction” when explaining the signed container submitted to Layer 1.
## Virtual operations
Virtual operations are emitted by protocol processing rather than directly signed by a user.
They are useful for account history and reward-related workflows. Do not describe them as user-submitted transactions.
## Accounts
A Blurt account is a Layer 1 identity and state container. It may include:
- account name;
- liquid balances;
- vesting shares;
- authorities;
- metadata;
- social/content relationships exposed through Layer 1 or indexed through Nexus.
Account state from Layer 1 and profile/community views from Nexus should be described separately.
## Authorities
Authorities define which keys or accounts can authorize actions.
| Authority | Typical meaning |
| --- | --- |
| owner | recovery and highest-risk account control |
| active | financial and account-management actions |
| posting | social actions such as votes/comments where supported |
| memo | memo encryption/decryption, not transaction authority |
Learn authorities before signing anything: [Accounts and authorities](./accounts-and-authorities.md).
## Assets
A blockchain asset is an amount with a symbol and precision. Do not treat asset strings as plain numbers without preserving symbol and precision semantics.
For example, a liquid balance and vesting-related amount may both be asset-like values but they do not mean the same thing.
## Witnesses
Witnesses are Layer 1 block producers and governance participants.
Witness-related reads and votes belong to Layer 1. Do not present witness data as a Nexus concept.
## RPC endpoints
A node is a server exposing Blurt RPC APIs. An RPC endpoint is the URL your application calls.
One endpoint response is not the entire network. Endpoints can lag, fail or differ temporarily, so production applications should think deliberately about endpoint choice and failover.
## Nexus and Bridge
Nexus is Layer 2 indexing/social infrastructure for Blurt applications. Bridge is the API style used for those social/indexed views.
In `dblurt`, wrapped Nexus/Bridge helpers live under `client.nexus`.
Nexus may expose:
- profiles;
- communities;
- ranked posts;
- discussions;
- notifications;
- referrals;
- indexed social views.
Nexus is useful for discovery and social interfaces. It should not be described as changing Layer 1 meaning.
## Where to go next
- [Layer 1 and Nexus Layer 2](./layer-1-and-nexus.md)
- [Accounts and authorities](./accounts-and-authorities.md)
- [Blockchain queries vs broadcast operations](./blockchain-queries-vs-broadcast-operations.md)
- [Choose your path](../start/choose-your-path.md)
---
## Layer 1 and Nexus Layer 2
Source: site/learn/layer-1-and-nexus.md
Canonical URL: https://dblurt.beblurt.com/learn/layer-1-and-nexus.html
Purpose: How consensus chain data differs from indexed social data.
# Layer 1 and Nexus Layer 2
The most important `dblurt` documentation boundary is the difference between Blurt Layer 1 and Nexus Layer 2.
```text
Layer 1 records canonical chain events and state.
Nexus indexes and presents application-friendly social views.
```
If you remember only one rule, remember that Nexus helps applications discover and present data; it does not replace Layer 1 consensus truth.
## Why this distinction exists
Blockchain applications often need two different kinds of data:
1. canonical chain state, such as account balances, authorities, blocks and signed operations;
2. application-friendly social views, such as ranked feeds, profiles, communities and notification lists.
Raw Layer 1 RPC APIs are the right source for the first category. Indexed Layer 2 APIs are often better for the second category.
`dblurt` exposes both because Blurt applications commonly need both.
## Blurt Layer 1
Blurt Layer 1 is the consensus chain. It is responsible for:
- blocks and irreversible history;
- transactions and operations;
- account state and authorities;
- balances and assets;
- witnesses and governance;
- virtual operations and protocol-derived effects.
Typical `dblurt` surfaces:
| Surface | Use it for |
| --- | --- |
| `client.condenser` | common chain reads: accounts, content, witnesses, history-compatible calls |
| `client.database` | appbase database methods such as config/version/account lists |
| `client.accountHistory` | account and block operation history envelopes |
| `client.blockchain` | high-level block and operation iteration |
| `client.broadcast` | signed Layer 1 transaction workflows |
| `client.call` | unwrapped JSON-RPC methods |
Use Layer 1 when correctness depends on canonical chain state.
## Nexus Layer 2
Nexus indexes and exposes social/query views that are more convenient for applications than raw chain data.
Typical `client.nexus` use cases:
- ranked feeds;
- account post lists;
- post/discussion views;
- communities and subscriptions;
- profile summaries;
- notifications and unread counts;
- referral account views.
Nexus data is application-friendly. It can be the right surface for discovery and UI flows, but it has indexer semantics and should be treated as Layer 2.
## Trust and freshness
Layer 1 and Nexus have different trust questions.
| Question | Prefer |
| --- | --- |
| What is this account's authority? | Layer 1 |
| Can this key sign a posting action? | Layer 1 authority data |
| What is the current liquid balance? | Layer 1 |
| What posts are trending in a tag? | Nexus |
| What communities match a topic? | Nexus |
| What exact operation was included in a block? | Layer 1 |
| What profile metadata should my social UI show? | Nexus, with Layer 1 validation if security-sensitive |
When a workflow starts with Nexus discovery and ends with a security-sensitive action, validate the relevant Layer 1 state before signing or broadcasting.
## Helper routing examples
### Read canonical account state
```ts
const accounts = await client.condenser.getAccounts(['beblurt']);
const account = accounts[0];
```
### Read ranked social posts
```ts
const posts = await client.nexus.getRankedPosts({
sort: 'trending',
limit: 10,
tag: 'blurt',
observer: null
});
```
### Use Nexus to discover, Layer 1 to verify
A social app might use Nexus to find a post in a ranked feed, then use Layer 1 helpers to read the canonical content object or active votes when exact chain state matters.
```text
Nexus ranked feed -> choose author/permlink -> Layer 1 content/vote read if needed
```
## API symbols
- [`Nexus`](/api/classes/index.Nexus.html)
- [`Nexus.getRankedPosts`](/api/classes/index.Nexus.html#getRankedPosts)
- [`Nexus.getAccountPosts`](/api/classes/index.Nexus.html#getAccountPosts)
- [`NexusRankedPostsQuery`](/api/interfaces/index.NexusRankedPostsQuery.html)
- [`NexusAccountPostsQuery`](/api/interfaces/index.NexusAccountPostsQuery.html)
## Compatibility policy for Nexus helpers
New code should prefer typed option objects for pagination-heavy Nexus helpers because they make filters, cursors and observer semantics explicit.
Historical positional Nexus signatures remain legacy-supported. They are not deprecated at this time.
The misspelled `listPopComunities` helper remains supported for backward compatibility but is deprecated in favor of `listPopCommunities`.
See [Deprecations](../reference/deprecations.md) for lifecycle policy and [API reference](../reference/api.md) for exact overloads.
## Common mistakes
- Treating Nexus as the source of consensus truth.
- Using a ranked feed result as proof of chain finality.
- Assuming a profile/community view has the same trust model as account authority data.
- Showing exact API parameter tables in concept docs instead of linking to the API reference.
## Where to go next
- [Use Nexus social data](../guides/use-nexus-social-data.md)
- [Read chain data](../guides/read-chain-data.md)
- [Choose your path](../start/choose-your-path.md)
- [API reference](../reference/api.md)
---
## For Hive/Steem developers
Source: site/learn/for-hive-steem-developers.md
Canonical URL: https://dblurt.beblurt.com/learn/for-hive-steem-developers.html
Purpose: Comparative orientation for developers coming from Hive, Steem or Graphene-family SDKs.
# For Hive and Steem developers
If you already know Hive, Steem or another Graphene-family chain, `dblurt` will feel familiar in several places, but the safest path is to treat Blurt as its own chain and `dblurt` as its own SDK.
This page gives orientation, not a mechanical compatibility matrix. Exact method signatures belong in the [API reference](../reference/api.md).
## What transfers well
Several mental models carry over:
| Familiar concept | Blurt / `dblurt` orientation |
| --- | --- |
| Accounts | Blurt accounts remain Layer 1 identities with authorities, balances, metadata and social/content relationships. |
| Operations | Transactions still contain ordered operations such as votes, comments, transfers, account updates and custom JSON payloads. |
| Authorities | Owner, active, posting and memo roles remain useful, but you should still verify the required authority per operation. |
| Witnesses | Witnesses remain Layer 1 block producers and governance participants. |
| Custom JSON | Social actions such as follow, mute and reblog are represented as `custom_json` conventions. |
| Account history | Historical and virtual operations remain important for audits, rewards and indexers. |
Start with the [Blurt mental model](./blurt-mental-model.md) if any of those concepts are unclear in Blurt-specific terms.
## What you should not assume
Do not copy assumptions from another chain or SDK without checking Blurt and `dblurt` directly.
| Do not assume | Use instead |
| --- | --- |
| Hive/Steem RPC method coverage is wrapped one-for-one | Use `client.condenser`, `client.database`, `client.accountHistory`, `client.blockchain`, `client.nexus`, or the raw `client.call(api, method, params)` escape hatch. |
| A helper exists because another SDK has it | Check the [API reference](../reference/api.md) or use `client.call()` for unwrapped RPC methods. |
| Resource Credits are the normal transaction-cost model | Blurt uses explicit fees. Do not present RC as the main user cost model. |
| Nexus data is Layer 1 consensus data | Treat Nexus as Layer 2 indexed/social data; validate against Layer 1 when the decision is security-sensitive. |
| A historical operation type is currently accepted by mainnet | Check deprecations and current Layer 1 behavior. Some compatibility helpers remain callable but are deprecated. |
| Browser signing is safe because the SDK can run in browsers | Browser key custody has separate security risks. Prefer wallet-mediated signing when possible. |
## API surface translation
Use this map when porting an integration or checking where a familiar workflow belongs.
| If you are looking for... | Start with... | Notes |
| --- | --- | --- |
| Chain properties, accounts, content, witnesses, proposal reads | `client.condenser` | Common Layer 1 query workflows. |
| Appbase-style database calls | `client.database` or `client.call('database_api', method, params)` | `dblurt` intentionally does not wrap every database method. |
| Block ranges and operation scans | `client.blockchain` | Higher-level iteration helpers over Layer 1 blocks and operations. |
| Account or virtual operation history | `client.accountHistory` and `client.condenser.getAccountHistory()` | Choose by parameter shape and workflow. |
| Ranked posts, profiles, communities, notifications | `client.nexus` | Nexus is Layer 2 indexed/social infrastructure. |
| Follow, mute, reblog, community subscription actions | social operation builders and `client.broadcast` helpers | These build `custom_json` operations. |
| Content publishing | content builders such as `buildPostOperation()` plus broadcast helpers when you are ready to sign. |
| Raw method not wrapped by the SDK | `client.call(api, method, params)` | Prefer this over inventing a helper name. |
## Porting checklist
When moving code from a Hive/Steem integration:
1. **Reconfirm the RPC namespace and method.** If `dblurt` does not wrap it, use `client.call()` with the Blurt RPC method shape.
2. **Reconfirm operation support.** Operation interfaces may exist for history compatibility even when a current-chain workflow is deprecated.
3. **Reconfirm authorities.** Use posting for social operations where valid, active for financial/account-management operations, and owner only when the operation requires it.
4. **Reconfirm asset handling.** Preserve symbol and precision with `Asset`; do not convert asset strings into plain JavaScript numbers for signing-critical logic.
5. **Reconfirm Layer 1 vs Nexus.** Use Layer 1 for consensus-sensitive state and Nexus for indexed/social discovery.
6. **Reconfirm broadcast retry behavior.** A timeout after broadcast is ambiguous; keep the transaction id and check status where available instead of blindly retrying side-effectful submissions.
## Deprecated compatibility surfaces
Some APIs remain callable for compatibility but should not be presented as current Blurt workflows.
Examples include:
- `BroadcastAPI.accountWitnessProxy()` — current Blurt Layer 1 rejects witness proxies after hardfork 0.8;
- `BroadcastAPI.claimAccount()` and `BroadcastAPI.createClaimedAccount()` — current Blurt Layer 1 rejects claimed-account tickets after hardfork 0.2;
- `Nexus.listPopComunities()` — historical misspelling retained in favor of `listPopCommunities()`.
See [Deprecations](../reference/deprecations.md) for the current lifecycle policy.
## Recommended learning path
If you know the ecosystem but not this SDK, use this order:
1. [Choose your path](../start/choose-your-path.md)
2. [Layer 1 and Nexus Layer 2](./layer-1-and-nexus.md)
3. [Accounts and authorities](./accounts-and-authorities.md)
4. [Read chain data](../guides/read-chain-data.md)
5. [Broadcast safely](../guides/broadcast-safely.md)
6. [API reference](../reference/api.md)
The goal is not to relearn every blockchain concept. The goal is to avoid carrying the wrong assumptions into Blurt-specific code.
---
## Accounts and authorities
Source: site/learn/accounts-and-authorities.md
Canonical URL: https://dblurt.beblurt.com/learn/accounts-and-authorities.html
Purpose: Account authority, key and least-privilege concepts.
# Accounts and authorities
Blurt accounts are not just names. They hold state and authorities that define which keys or accounts can authorize actions.
You should understand authorities before signing or broadcasting anything with `dblurt`.
## Accounts
A Blurt account is a Layer 1 identity and state container. Depending on the RPC method, account data may include:
- account name;
- balances;
- vesting shares;
- posting/active/owner authorities;
- metadata;
- voting mana or related chain state;
- recovery and governance fields.
Read account state from Layer 1 when correctness matters:
```ts
const accounts = await client.condenser.getAccounts(['beblurt']);
const account = accounts[0];
```
Nexus profile data may enrich social UI, but Layer 1 account authority data is the source for signing decisions.
## Authorities
An authority describes which keys or accounts can approve actions.
| Authority | Typical use | Documentation rule |
| --- | --- | --- |
| owner | recovery and highest-risk account control | avoid in normal app flows |
| active | value-moving or account-management actions | use only when required |
| posting | social actions such as votes/comments where supported | prefer for social workflows |
| memo | memo encryption/decryption | not a transaction authority |
The safest application uses the least powerful authority that can perform the intended action.
## Least privilege
Least privilege means:
- do not ask for an active key when a posting key is enough;
- do not ask for an owner key in normal application flows;
- do not treat a memo key as authorization to broadcast;
- warn users when a high-privilege key is being used for a low-privilege workflow;
- validate authority assumptions before broadcasting.
## What the SDK can validate
`dblurt` includes authority-validation primitives for posting-key workflows.
They can answer questions such as:
- does this key satisfy this authority object?
- does this key satisfy the account's posting authority?
- is the key actually an active or owner key being used where posting would be safer?
- does delegated posting authority satisfy the threshold?
Conceptually:
```text
key + Layer 1 authority data -> validation result
```
The validation helpers do not broadcast, store private keys or replace application policy.
## What the SDK cannot decide for you
Applications remain responsible for:
- storing keys safely;
- choosing whether to accept a high-privilege key;
- presenting confirmations to users;
- enforcing business or moderation policy;
- deciding which RPC endpoints are trusted;
- handling ambiguous broadcast failures.
`dblurt` can provide protocol-shaped evidence. Your application decides what to do with it.
## Authority and operation examples
| Operation family | Typical authority |
| --- | --- |
| vote/comment/social custom JSON | posting |
| transfer | active |
| account management | active or owner depending on operation |
| memo encryption/decryption | memo key, not broadcast authority |
Always verify the exact operation before signing. If a guide does not state the authority, treat that as missing documentation rather than permission to guess.
## Private key handling
Do not hard-code private keys in examples, source code or tests.
Use environment variables, encrypted storage, wallet integrations or user-controlled signing flows:
```ts
import { PrivateKey } from '@beblurt/dblurt';
const rawKey = process.env.BLURT_POSTING_KEY;
if (!rawKey) {
throw new Error('Set BLURT_POSTING_KEY before signing');
}
const key = PrivateKey.fromString(rawKey);
```
Browser signing is especially sensitive because XSS, malicious extensions or compromised dependencies can access key material handled by the page.
## API symbols
- [`validatePostingAuthority`](/api/functions/index.validatePostingAuthority.html)
- [`validateAccountAuthority`](/api/functions/index.validateAccountAuthority.html)
- [`evaluateAuthorityForKey`](/api/functions/index.evaluateAuthorityForKey.html)
## Where to go next
- [Blockchain queries vs broadcast operations](./blockchain-queries-vs-broadcast-operations.md)
- [Broadcast safely](../guides/broadcast-safely.md)
- [API reference](../reference/api.md)
---
## Blockchain queries vs broadcast operations
Source: site/learn/blockchain-queries-vs-broadcast-operations.md
Canonical URL: https://dblurt.beblurt.com/learn/blockchain-queries-vs-broadcast-operations.html
Purpose: The safe learning path from reads to side effects.
# Blockchain queries vs broadcast operations
`dblurt` supports both blockchain query workflows and signed broadcast workflows. They should not be introduced at the same time.
The documentation learning path is intentionally blockchain queries first.
## Blockchain query workflows
Blockchain query workflows ask RPC endpoints for data. They do not require private keys and do not change chain state.
Examples:
- read current chain properties;
- load an account;
- inspect a block;
- read a post;
- query ranked Nexus posts;
- list communities;
- estimate vote value from public data.
Typical surfaces:
- `client.condenser`;
- `client.database`;
- `client.accountHistory`;
- `client.blockchain`;
- `client.nexus`;
- `client.read`;
- `client.tools` for local calculations.
Blockchain query examples are the best first copy-paste path because they avoid key handling and irreversible effects.
## Operation-building workflows
Operation builders create Layer 1 operation payloads without broadcasting them.
They are useful for:
- previews;
- tests;
- dry-run style UI;
- external signing;
- confirmation flows;
- building a transaction later.
Example:
```ts
import { buildPostOperation } from '@beblurt/dblurt';
const operation = buildPostOperation({
author: 'alice',
title: 'Hello Blurt',
body: 'Body text',
tags: ['blurt']
});
```
This returns an operation. It does not sign and does not broadcast.
## Broadcast workflows
Broadcast workflows prepare, sign and submit transactions to Blurt Layer 1.
They require:
- explicit user intent;
- the correct authority;
- private key handling;
- trusted endpoint strategy;
- confirmation of accounts, amounts, permlinks and memo text;
- error handling for ambiguous network failures.
Once accepted by the chain, broadcast transactions have real effects.
## The three-stage safety model
Use this model in application design:
```text
1. Read data
No key. No side effect.
2. Build operation
No key required. Preview exact payload.
3. Sign and broadcast
Key required. Real chain effect.
```
Docs and examples should make clear which stage they are in.
## Why README and getting started stay blockchain query
A landing page should help a developer succeed quickly without asking for secrets.
That is why the first-run path reads chain data and Nexus views but does not show copy-paste broadcast code. Broadcasting belongs in a safety-focused guide after the reader understands authorities.
## Before broadcasting
Before calling `client.broadcast`, confirm:
1. the user intended the action;
2. the operation payload is correct;
3. the required authority is known;
4. the key satisfies that authority;
5. high-privilege keys are avoided when possible;
6. the endpoint list is trusted;
7. the UI can handle success, failure and ambiguity.
## Where to go next
- [Accounts and authorities](./accounts-and-authorities.md)
- [Publish content](../guides/publish-content.md)
- [Social actions](../guides/social-actions.md)
- [Broadcast safely](../guides/broadcast-safely.md)
- [Handle errors](../guides/handle-errors.md)
---
## site/learn/assets-operations-transactions.md
Source: site/learn/assets-operations-transactions.md
Canonical URL: https://gitlab.com/beblurt/dblurt/-/blob/main/site/learn/assets-operations-transactions.md
Purpose: Canonical repository documentation source.
# Assets, operations and transactions
This page explains the Layer 1 data structures that matter when building with `@beblurt/dblurt`: assets, operations, transactions, blocks and virtual operations.
It is a conceptual guide, not an API reference. Use it to reason correctly about Blurt workflows, then use the [API reference](../reference/api.md) for exact TypeScript shapes.
## The short model
```text
asset amount + symbol/precision
operation one Layer 1 action
transaction signed payload containing one or more operations
block ordered container of transactions
virtual op protocol-emitted history entry, not directly signed by a user
```
A developer mistake in one of these distinctions can create broken accounting, unsafe signing UX or incorrect blockchain parsing.
## Assets
An asset is not just a number. It is an amount with a symbol and precision.
Examples you may see in Blurt workflows include liquid BLURT balances, savings balances, vesting shares and reward balances.
`@beblurt/dblurt` exports an `Asset` class from `src/chain/asset.ts` for parsing, formatting, validating and doing simple same-symbol arithmetic on asset values. It also exports `Price` for converting between two asset symbols when a price pair is supplied.
```ts
import { Asset, Price } from '@beblurt/dblurt';
const balance = Asset.fromString('1.000 BLURT', 'BLURT');
const total = balance.add('2.500 BLURT');
console.log(total.toString()); // 3.500 BLURT
const price = new Price(Asset.fromString('1.000 BLURT'), Asset.fromString('10.000 VESTS'));
console.log(price.convert(Asset.fromString('2.000 BLURT')).toString());
```
Documentation and application rules:
- use `Asset.fromString()` or `Asset.from()` when you need SDK-owned parsing/validation;
- pass an explicit symbol when constructing from a number; the legacy numeric default is not a Blurt documentation pattern;
- preserve the symbol and precision when displaying values;
- do not parse an asset string as a unitless number without knowing the symbol;
- do not mix liquid BLURT, savings and vesting values as if they were the same thing;
- use `Asset.add()`, `subtract()`, `multiply()` and `divide()` only with compatible symbols;
- use `Asset.min()` / `Asset.max()` only for same-symbol comparisons;
- use `Price.convert()` only when the supplied pair is correct for your workflow;
- use SDK helpers or explicit conversion logic where the code already provides it;
- keep fiat conversion, formatting policy and UI labels outside the SDK data model unless a helper explicitly documents them.
## Operations
An operation is a single Layer 1 action.
Examples include:
- comment/post/reply operations;
- votes;
- transfers;
- custom JSON social actions;
- witness votes;
- account and authority changes.
Use “operation” when discussing the action being performed. Operation builders such as `buildPostOperation()` create operation payloads without signing or broadcasting.
## Transactions
A transaction is a signed Layer 1 payload containing one or more operations.
Transactions add:
- expiration;
- reference block data;
- signatures;
- one or more operations.
Use “transaction” when discussing the signed payload submitted to the chain. A transaction can include multiple operations, and the required signatures must satisfy every operation in it.
## Broadcast operations
Broadcasting sends a signed transaction to a Blurt RPC endpoint.
That is the side-effect boundary:
```text
build operation -> inspect/confirm -> sign transaction -> broadcast transaction
```
Do not ask users for private keys just to build or inspect an operation. Key handling belongs only in signing and broadcast workflows.
See [Broadcast safely](../guides/broadcast-safely.md).
## Blocks
A block is an ordered unit of Layer 1 chain history. It contains transactions, and transactions contain operations.
For parsing workflows, track the block height you processed and decide whether you need latest head blocks or irreversible blocks.
| Block concept | Meaning | Use it for |
| --- | --- | --- |
| Head block | Latest block known by an RPC node | live dashboards and low-stakes monitoring |
| Reversible block | Recent block that may be affected by fork resolution | only when your workflow accepts reorg handling |
| Last irreversible block | Block considered irreversible by consensus | indexing, accounting, replay and durable parsing |
For block parsing, see [Parse blockchain history](../guides/parse-blockchain-history.md).
## Virtual operations
Virtual operations are emitted by protocol processing. They are Layer 1-derived history entries, but they are not directly signed by a user as normal operations.
Use them for understanding protocol effects such as rewards or derived account-history entries. Do not present them as user-submitted transactions.
## Correct terminology
| Say | When |
| --- | --- |
| blockchain query | asking an RPC endpoint for data |
| operation | individual Layer 1 action |
| transaction | signed payload containing operations |
| broadcast operation | submitting a signed transaction to Layer 1 |
| blockchain parsing | iterating blocks or operations to build an index, audit trail or processor |
| virtual operation | protocol-emitted history entry |
## Asset API details
Use the API reference for exact constructor behavior and method signatures:
- [`Asset`](/api/classes/index.Asset.html)
- [`Price`](/api/classes/index.Price.html)
- [`AssetSymbol`](/api/types/index.AssetSymbol.html)
- [`examples/node/asset-and-price.cjs`](https://gitlab.com/beblurt/dblurt/-/blob/main/examples/node/asset-and-price.cjs)
## Related docs
- [Blurt mental model](./blurt-mental-model.md)
- [Layer 1 and Nexus Layer 2](./layer-1-and-nexus.md)
- [Blockchain queries vs broadcast operations](./blockchain-queries-vs-broadcast-operations.md)
- [Read chain data](../guides/read-chain-data.md)
- [Parse blockchain history](../guides/parse-blockchain-history.md)
- [Publish content](../guides/publish-content.md)
- [Social actions](../guides/social-actions.md)
---
## Read chain data
Source: site/guides/read-chain-data.md
Canonical URL: https://dblurt.beblurt.com/guides/read-chain-data.html
Purpose: Use Layer 1 helpers for accounts, blocks, witnesses and chain properties.
# Read chain data
Use this guide when your application needs Blurt Layer 1 data: accounts, content, blocks, witnesses, proposals, chain properties or account history.
Layer 1 queries ask a Blurt RPC node for consensus data. They do not require private keys, and they do not broadcast operations. That makes them the safest place to start before adding signing or broadcast workflows.
## When to use Layer 1 reads
Use Layer 1 helpers when you need data that comes directly from the Blurt blockchain:
| Need | Start with | Why |
| --- | --- | --- |
| Current head block, irreversible block or chain time | `client.condenser.getDynamicGlobalProperties()` | Smallest useful connectivity and chain-state query. |
| Account balances, authorities or vesting state | `client.condenser.getAccounts()` | Account state is Layer 1 data. |
| Content object by author/permlink | `client.condenser.getContent()` | Retrieves the chain content object. |
| Active votes on content | `client.condenser.getActiveVotes()` | Reads vote records for one content item. |
| Witness information | `client.condenser.getWitnessByAccount()` | Reads witness state by account name. |
| Block headers, blocks or operation streams | `client.blockchain` helpers | Higher-level iteration around block ranges. |
| Virtual/account operation history | `client.accountHistory` or condenser history helpers | Reads account operation history and virtual operation envelopes. |
| Appbase methods without a helper | `client.call(api, method, params)` | Generic JSON-RPC escape hatch. |
If you are choosing between Layer 1 and Nexus, read [Layer 1 and Nexus Layer 2](../learn/layer-1-and-nexus.md) first.
## Create a client
```ts
import { Client } from '@beblurt/dblurt';
const client = new Client([
'https://rpc.blurt.blog',
'https://rpc.beblurt.com',
'https://blurt-rpc.saboin.com'
], {
timeout: 15_000,
failoverThreshold: 3
});
```
Use more than one endpoint when your application should tolerate temporary node failures. Endpoint behavior is covered in [RPC endpoints and failover](./rpc-endpoints-and-failover.md).
## Read current chain state
```ts
const props = await client.condenser.getDynamicGlobalProperties();
console.log({
head: props.head_block_number,
irreversible: props.last_irreversible_block_num,
time: props.time
});
```
Use `last_irreversible_block_num` when a workflow needs a more stable reference point than the latest head block.
## Load account state
```ts
const [account] = await client.condenser.getAccounts(['beblurt']);
if (!account) {
throw new Error('account not found');
}
console.log({
name: account.name,
balance: account.balance,
vesting: account.vesting_shares,
postingAuthorities: account.posting.key_auths.length
});
```
Account data includes balances, authorities and chain fields returned by the RPC API. If you need an application-ready account summary, use [Read models](./read-models.md) or the [Read account summary](../recipes/read-account-summary.md) recipe.
## Read content and votes
```ts
const post = await client.condenser.getContent('megadrive', 'a-declaration-is-more-than-a-post-it-is-a-public-commitment');
const votes = await client.condenser.getActiveVotes(post.author, post.permlink);
console.log({
title: post.title,
votes: votes.length
});
```
This reads the Layer 1 content object and its active vote records. For discovery flows such as ranked feeds or community pages, use Nexus first, then fetch Layer 1 content only when your workflow needs the chain object.
## Iterate blocks deliberately
Use `client.blockchain` for bounded block or operation iteration. For parser/indexer workflows, continue with [Parse blockchain history](./parse-blockchain-history.md).
```ts
import { BlockchainMode } from '@beblurt/dblurt';
const latest = await client.blockchain.getCurrentBlockNum(BlockchainMode.Irreversible);
const blockNumbers = await client.blockchain.getBlockNumbers({
from: latest - 2,
to: latest,
mode: BlockchainMode.Irreversible
});
console.log(blockNumbers);
```
Keep iteration bounded in examples, dashboards and background jobs. Large scans should have explicit limits, retry behavior and persistence outside the SDK.
## Use generic RPC calls only when needed
When a method is not wrapped by a helper, use `client.call(api, method, params)` instead of inventing a helper name.
```ts
const version = await client.call('database_api', 'get_version', []);
console.log(version.blockchain_version);
```
The generic call surface is useful, but it does not replace the typed helper families. Prefer helpers when they exist.
## Safety and correctness notes
- Layer 1 reads do not require private keys.
- Do not ask for keys in a page or example that only queries blockchain data.
- Use Nexus for indexed social discovery; use Layer 1 helpers for canonical chain objects.
- Prefer irreversible block mode for examples and replay-style tools.
- Use bounded ranges for block and operation iteration.
- Treat RPC endpoints as network dependencies; configure timeouts and endpoint lists intentionally.
## Validated examples
- [`examples/node/read-head-block.cjs`](https://gitlab.com/beblurt/dblurt/-/blob/main/examples/node/read-head-block.cjs)
- [`examples/node/read-account.cjs`](https://gitlab.com/beblurt/dblurt/-/blob/main/examples/node/read-account.cjs)
- [`examples/node/read-post.cjs`](https://gitlab.com/beblurt/dblurt/-/blob/main/examples/node/read-post.cjs)
- [`examples/node/read-active-votes.cjs`](https://gitlab.com/beblurt/dblurt/-/blob/main/examples/node/read-active-votes.cjs)
- [`examples/node/read-block-operations.cjs`](https://gitlab.com/beblurt/dblurt/-/blob/main/examples/node/read-block-operations.cjs)
- [Read account history recipe](../recipes/read-account-history.md)
- [`examples/node/stream-block-numbers.cjs`](https://gitlab.com/beblurt/dblurt/-/blob/main/examples/node/stream-block-numbers.cjs)
## API details
Use the API reference for exact method signatures, options and return types:
- [`Client`](/api/classes/index.Client.html)
- [`Client.condenser`](/api/classes/index.Client.html#condenser)
- [`Client.blockchain`](/api/classes/index.Client.html#blockchain)
- [`Client.call`](/api/classes/index.Client.html#call)
---
## Use Nexus social data
Source: site/guides/use-nexus-social-data.md
Canonical URL: https://dblurt.beblurt.com/guides/use-nexus-social-data.html
Purpose: Build social/community views using indexed data.
# Use Nexus social data
Use this guide when your application needs Blurt social views that are easier to consume from Nexus: ranked posts, account feeds, communities, profiles, notifications, referrals and discussion-oriented data.
Nexus is an indexed/social Layer 2 view derived from Blurt blockchain activity. It is excellent for discovery and application screens, but it is not the Layer 1 consensus source. When exact chain state matters, route back to Layer 1 helpers.
## When Nexus is the right surface
| Need | Use | Notes |
| --- | --- | --- |
| Trending, hot, created or payout feeds | `client.nexus.getRankedPosts()` | Good first choice for discovery pages. |
| Posts by account, blog, comments, replies or feed | `client.nexus.getAccountPosts()` | Use option objects for pagination-heavy code. |
| Community lists and community details | `client.nexus.listCommunities()`, `getCommunity()` | Useful for topic discovery and community screens. |
| Profiles | `client.nexus.getProfile()` | Indexed profile view, not a replacement for Layer 1 account authority data. |
| Notifications | `accountNotifications()`, `unreadNotifications()` | Application-facing notification views. |
| Referrals | `referralAccounts()`, `referralAccountsCount()` | Referral/affiliate lookup helpers. |
| Full chain object | Layer 1 helpers, not Nexus | Use `client.condenser` when consensus fields matter. |
For the conceptual boundary, read [Layer 1 and Nexus Layer 2](../learn/layer-1-and-nexus.md).
## Query ranked posts
```ts
const posts = await client.nexus.getRankedPosts({
sort: 'trending',
tag: 'blurt',
limit: 10,
observer: null
});
for (const post of posts) {
console.log(post.author, post.permlink, post.title);
}
```
Prefer option objects for new code because they make filters, cursors and observer semantics explicit.
The historical positional form remains supported for compatibility, but it is harder to read once pagination or nullable cursors are involved.
## List account posts
```ts
const posts = await client.nexus.getAccountPosts({
account: 'beblurt',
sort: 'posts',
limit: 5,
observer: null
});
console.log(posts.map((post) => post.title));
```
Use account-post queries for profile pages, post histories, comments, replies and feed-like surfaces. For pagination, carry the last item cursor according to the helper's option type and the API reference.
## Discover communities
```ts
const communities = await client.nexus.listCommunities({
query: 'blurt',
limit: 10,
observer: null
});
for (const community of communities) {
console.log(community.name, community.title);
}
```
```ts
const community = await client.nexus.getCommunity('blurt-101010', null);
console.log(community.title);
```
Community names such as `blurt-101010` are identifiers. Display titles are user-facing labels and can change independently.
## Load a profile
```ts
const profile = await client.nexus.getProfile('beblurt', null);
console.log(profile.name);
```
Use profiles for social presentation. Use Layer 1 account data when you need balances, authorities or protocol account state.
## Understand observer values
Many Nexus helpers accept an `observer` value. The observer can affect visibility, muted content, subscription context or account-specific presentation.
Use `null` when you want a neutral public view:
```ts
const post = await client.nexus.getPost('author', 'permlink', null);
```
Use an account name only when your application intentionally wants observer-aware data.
## Trust and freshness model
Nexus data is indexed. That has product benefits and tradeoffs:
- it is convenient for social screens and discovery;
- it can combine and normalize data for applications;
- it may lag the latest Layer 1 block;
- it should not be described as Layer 1 consensus truth;
- it should be cross-checked with Layer 1 helpers when your workflow depends on exact chain state.
A common pattern is:
```text
1. Use Nexus to discover the post, account, community or feed item.
2. Use Layer 1 helpers only if your workflow needs canonical chain fields.
3. Use broadcast helpers only after user intent, authority and key handling are explicit.
```
## Compatibility notes
- Positional Nexus signatures remain supported for existing consumers.
- Option objects are preferred for new code with filters, observer values or pagination.
- `listPopComunities` remains available with its historical spelling but is deprecated.
- New code should use `listPopCommunities`.
## Validated examples
- [`examples/node/read-nexus-ranked-posts.cjs`](https://gitlab.com/beblurt/dblurt/-/blob/main/examples/node/read-nexus-ranked-posts.cjs)
- [`examples/node/read-nexus-community.cjs`](https://gitlab.com/beblurt/dblurt/-/blob/main/examples/node/read-nexus-community.cjs)
- [`examples/node/read-post.cjs`](https://gitlab.com/beblurt/dblurt/-/blob/main/examples/node/read-post.cjs)
- [`examples/node/read-account-summary.cjs`](https://gitlab.com/beblurt/dblurt/-/blob/main/examples/node/read-account-summary.cjs)
## API details
Use the API reference for exact option shapes, pagination fields, overloads and return types:
- [`Client.nexus`](/api/classes/index.Client.html#nexus)
- [`Nexus`](/api/classes/index.Nexus.html)
- [`NexusRankedPostsQuery`](/api/interfaces/index.NexusRankedPostsQuery.html)
- [`NexusAccountPostsQuery`](/api/interfaces/index.NexusAccountPostsQuery.html)
---
## Parse blockchain history
Source: site/guides/parse-blockchain-history.md
Canonical URL: https://dblurt.beblurt.com/guides/parse-blockchain-history.html
Purpose: Iterate block ranges, full blocks and operation streams.
# Parse blockchain history
Blockchain parsing is the workflow of iterating Layer 1 blocks or operations to build an index, audit log, monitor, synchronizer or replay tool.
`@beblurt/dblurt` exposes this through `client.blockchain`: `getBlockNumbers()`, `getBlocks()`, `getBlockStream()`, `getOperations()` and `getOperationsStream()`.
Use this guide when your code needs more than a single blockchain query.
## Choose the parsing surface
| Goal | Use | Why |
| --- | --- | --- |
| Persist block heights only | `getBlockNumbers()` | smallest payload and easiest checkpointing |
| Inspect full blocks with transactions | `getBlocks()` | async iterator for block processors |
| Pipe blocks into Node stream tooling | `getBlockStream()` | stream integration for existing Node pipelines |
| Process flattened applied operations | `getOperations()` | async iterator over operations in block order |
| Pipe operations into Node stream tooling | `getOperationsStream()` | stream integration for operation consumers |
For exact options and return types, use the [API reference](../reference/api.md).
## Use irreversible mode by default
Most parsers should start with irreversible blocks. Latest-head parsing can see blocks that later change during fork resolution.
```ts
import { BlockchainMode, Client } from '@beblurt/dblurt';
const client = new Client(['https://rpc.blurt.blog']);
const latest = await client.blockchain.getCurrentBlockNum(BlockchainMode.Irreversible);
```
Use latest mode only when your application explicitly handles reorg risk.
## Parse a bounded block range
Keep examples and jobs bounded unless you are building a long-running daemon.
```ts
import { BlockchainMode, Client } from '@beblurt/dblurt';
const client = new Client(['https://rpc.blurt.blog']);
const irreversible = await client.blockchain.getCurrentBlockNum(BlockchainMode.Irreversible);
for await (const block of client.blockchain.getBlocks({
from: irreversible - 3,
to: irreversible - 1,
mode: BlockchainMode.Irreversible
})) {
console.log(block.witness, block.transactions.length);
}
```
The range is inclusive. Store the last successfully processed block number in your application so a parser can resume safely.
## Parse operations instead of whole blocks
If your parser cares about actions rather than block metadata, use the operation iterator.
```ts
for await (const operation of client.blockchain.getOperations({
from: irreversible - 3,
to: irreversible - 1,
mode: BlockchainMode.Irreversible
})) {
console.log(operation.op[0]);
}
```
Operations are yielded in block order. If your application needs transaction context, parse whole blocks and inspect transactions directly.
## Use Node streams when the rest of your pipeline is stream-based
`getBlockStream()` and `getOperationsStream()` expose the same parsing model as Node readable streams.
```ts
const stream = client.blockchain.getBlockStream({
from: irreversible - 3,
to: irreversible - 1,
mode: BlockchainMode.Irreversible
});
stream.on('data', (block) => {
console.log(block.block_id);
});
stream.on('error', (error) => {
console.error(error);
});
```
Prefer async iterators for new code unless your application already uses Node stream composition.
## Long-running parsers
A production parser should define these policies outside the SDK:
- checkpoint storage;
- replay window;
- endpoint trust and failover;
- retry/backoff behavior;
- duplicate handling;
- reorg policy if using latest blocks;
- observability and alerting;
- idempotent writes to your own index/database.
The SDK helps fetch blocks and operations. It does not own your indexer state machine.
## Query retries vs broadcast retries
Blockchain parsing uses data queries, so bounded retries and endpoint failover are usually acceptable. Do not reuse parsing retry logic for broadcast operations. Broadcast failures can be ambiguous after submission.
See [RPC endpoints and failover](./rpc-endpoints-and-failover.md) and [Broadcast safely](./broadcast-safely.md).
## Validated example
The current executable example demonstrates the smallest parsing primitive, block-number streaming:
- [`examples/node/stream-block-numbers.cjs`](https://gitlab.com/beblurt/dblurt/-/blob/main/examples/node/stream-block-numbers.cjs)
Use this guide for the higher-level block and operation parsing workflows.
## Related docs
- [Assets, operations and transactions](../learn/assets-operations-transactions.md)
- [Read chain data](./read-chain-data.md)
- [RPC endpoints and failover](./rpc-endpoints-and-failover.md)
- [Handle errors](./handle-errors.md)
## API details
- [`Client.blockchain`](/api/classes/index.Client.html#blockchain)
- [`Blockchain`](/api/classes/index.Blockchain.html)
- [`BlockchainMode`](/api/enums/index.BlockchainMode.html)
- [`BlockchainStreamOptions`](/api/interfaces/index.BlockchainStreamOptions.html)
---
## Publish content
Source: site/guides/publish-content.md
Canonical URL: https://dblurt.beblurt.com/guides/publish-content.html
Purpose: Build content operations before deciding how to broadcast them.
# Publish content
Publishing content on Blurt starts with a `comment` operation. `@beblurt/dblurt` provides content builders so applications can construct posts, replies and updates before deciding how they will be signed or broadcast.
This guide is about building content operations. For signing and submission, read [Broadcast safely](./broadcast-safely.md).
## The workflow
```text
collect draft -> build operation -> preview/confirm -> sign/broadcast later
```
Operation builders are pure local helpers. They do not ask for private keys and do not broadcast transactions.
## Top-level posts
```ts
import { buildPostOperation } from '@beblurt/dblurt';
const operation = buildPostOperation({
author: 'alice',
title: 'Hello Blurt',
body: 'Body text',
tags: ['blurt', 'sdk'],
app: 'my-app/1.0'
});
console.log(operation[0]); // comment
console.log(operation[1]); // operation payload
```
A top-level post uses the first normalized tag as the operation category. The builder returns a normal Layer 1 `comment` operation tuple.
## Replies
```ts
import { buildReplyOperation } from '@beblurt/dblurt';
const operation = buildReplyOperation({
author: 'alice',
parentAuthor: 'bob',
parentPermlink: 'hello-blurt',
body: 'Thanks for the post!',
app: 'my-app/1.0'
});
```
Replies have a parent author and parent permlink. They do not need a title.
## Updates
```ts
import { buildUpdateOperation } from '@beblurt/dblurt';
const operation = buildUpdateOperation({
author: 'alice',
permlink: 'hello-blurt',
title: 'Updated title',
body: 'Updated body',
tags: ['blurt', 'sdk'],
app: 'my-app/1.0'
});
```
Updates should be based on caller-supplied identity fields. Do not guess the author or permlink in the SDK layer.
## Metadata and tags
The builders normalize tags and construct `json_metadata` using ecosystem conventions. There is no Layer 1 protocol rule that this SDK should present as a universal content policy.
Application policy remains outside the builder:
- moderation rules;
- tag allow/deny lists;
- title/body validation beyond SDK input checks;
- attribution footers;
- confirmation UX;
- account/key ownership checks.
## Delete content
Blurt Layer 1 has a `delete_comment` operation for deleting content by author and permlink.
Use `buildDeleteCommentOperation()` when you want the same preview/external-signing pattern as the publish, reply and update builders:
```ts
import { buildDeleteCommentOperation } from '@beblurt/dblurt';
const operation = buildDeleteCommentOperation({
author: 'alice',
permlink: 'hello-blurt'
});
```
For direct broadcast, use the dedicated broadcast helper after user confirmation and posting-authority key handling:
```ts
await client.broadcast.deleteComment({
author: 'alice',
permlink: 'hello-blurt'
}, postingKey);
```
The underlying operation remains the Layer 1 tuple:
```ts
import { type DeleteCommentOperation } from '@beblurt/dblurt';
const operation: DeleteCommentOperation = ['delete_comment', {
author: 'alice',
permlink: 'hello-blurt'
}];
```
Do not present deletion as a draft/update. It is a separate broadcast operation with side effects and should go through the same confirmation and authority checks as other broadcast operations.
## Preview before broadcast
A good publishing UI shows users the content operation before signing:
```ts
const [, payload] = operation;
console.log({
author: payload.author,
permlink: payload.permlink,
title: payload.title,
parentAuthor: payload.parent_author,
parentPermlink: payload.parent_permlink
});
```
Only after confirmation should the application enter a signing or broadcast flow.
## Validated example
- [`examples/node/build-post-operation.cjs`](https://gitlab.com/beblurt/dblurt/-/blob/main/examples/node/build-post-operation.cjs)
## Related docs
- [Assets, operations and transactions](../learn/assets-operations-transactions.md)
- [Social actions](./social-actions.md)
- [Broadcast safely](./broadcast-safely.md)
- [Build post operation recipe](../recipes/build-post-operation.md)
- [`buildDeleteCommentOperation`](/api/functions/index.buildDeleteCommentOperation.html)
- [`DeleteCommentOperation`](/api/interfaces/index.DeleteCommentOperation.html)
## API details
- [`buildPostOperation`](/api/functions/index.buildPostOperation.html)
- [`buildReplyOperation`](/api/functions/index.buildReplyOperation.html)
- [`buildUpdateOperation`](/api/functions/index.buildUpdateOperation.html)
---
## Social actions
Source: site/guides/social-actions.md
Canonical URL: https://dblurt.beblurt.com/guides/social-actions.html
Purpose: Build follow, mute, reblog and community action operations.
# Social actions
Social actions such as follow, mute, reblog and community subscriptions are represented as Layer 1 `custom_json` operations.
`@beblurt/dblurt` exposes builders for preview/external-signing workflows and broadcast helpers for direct side-effectful workflows.
## Builder or broadcast helper?
| Need | Use |
| --- | --- |
| Preview an operation before signing | builder function |
| Hand an operation to a wallet or external signer | builder function |
| Test operation payload construction | builder function |
| Submit directly with a key your app controls | `client.broadcast` helper |
Builders do not require private keys. Broadcast helpers do.
## Builder coverage
The SDK exports builders for the currently supported social/custom JSON operation families:
| Action | Builder | Broadcast helper |
| --- | --- | --- |
| generic custom JSON | `buildCustomJsonOperation()` | `client.broadcast.customJson()` |
| follow | `buildFollowOperation()` | `client.broadcast.follow()` |
| unfollow | `buildUnfollowOperation()` | `client.broadcast.unfollow()` |
| mute | `buildMuteOperation()` | `client.broadcast.mute()` |
| unmute | `buildUnmuteOperation()` | `client.broadcast.unmute()` |
| reblog | `buildReblogOperation()` | `client.broadcast.reblog()` / `reblurt()` |
| undo reblog | `buildUndoReblogOperation()` | `client.broadcast.undoReblog()` |
| community subscribe | `buildCommunitySubscribeOperation()` | `client.broadcast.communitySubscribe()` |
| community unsubscribe | `buildCommunityUnsubscribeOperation()` | `client.broadcast.communityUnsubscribe()` |
| notification read marker | `buildReadNotificationOperation()` | `client.broadcast.readNotification()` |
## Follow and mute
```ts
import { buildFollowOperation } from '@beblurt/dblurt';
const follow = buildFollowOperation({
follower: 'alice',
following: 'bob'
});
console.log(follow);
```
Use mute/unmute builders when your application needs the corresponding social relationship operation. Keep display policy and confirmation text in your application.
## Reblog
```ts
import { buildReblogOperation } from '@beblurt/dblurt';
const reblog = buildReblogOperation({
account: 'alice',
author: 'bob',
permlink: 'hello-blurt'
});
```
Reblog operations refer to the account performing the action and the content being shared.
## Community subscriptions
Community actions are also custom JSON operations. They should be presented as social/community actions, not as generic opaque JSON when users are confirming them.
```ts
import { buildCommunitySubscribeOperation } from '@beblurt/dblurt';
const operation = buildCommunitySubscribeOperation({
account: 'alice',
community: 'blurt-101010'
});
```
## Notification read markers
Notification read markers are useful for application state, but they still produce an operation payload. Make sure the user/account context is clear before signing.
## Direct broadcast helpers
For direct submission, use the broadcast helper only after your key-handling path is safe:
```ts
const confirmation = await client.broadcast.follow('alice', 'bob', postingKey);
console.log(confirmation.id);
```
Read [Broadcast safely](./broadcast-safely.md) before adding direct broadcast code.
## Layer boundary
Social action builders produce Layer 1 operations. Nexus can help discover posts, profiles or communities, but Nexus does not broadcast actions or define Layer 1 authority.
A typical flow is:
```text
Nexus discovers a post/community -> builder constructs operation -> user confirms -> wallet/signing flow broadcasts
```
## Related docs
- [Use Nexus social data](./use-nexus-social-data.md)
- [Publish content](./publish-content.md)
- [Broadcast safely](./broadcast-safely.md)
- [Accounts and authorities](../learn/accounts-and-authorities.md)
## API details
- [`buildCustomJsonOperation`](/api/functions/index.buildCustomJsonOperation.html)
- [`buildFollowOperation`](/api/functions/index.buildFollowOperation.html)
- [`buildUnfollowOperation`](/api/functions/index.buildUnfollowOperation.html)
- [`buildMuteOperation`](/api/functions/index.buildMuteOperation.html)
- [`buildUnmuteOperation`](/api/functions/index.buildUnmuteOperation.html)
- [`buildReblogOperation`](/api/functions/index.buildReblogOperation.html)
- [`buildUndoReblogOperation`](/api/functions/index.buildUndoReblogOperation.html)
- [`buildCommunitySubscribeOperation`](/api/functions/index.buildCommunitySubscribeOperation.html)
- [`buildCommunityUnsubscribeOperation`](/api/functions/index.buildCommunityUnsubscribeOperation.html)
- [`buildReadNotificationOperation`](/api/functions/index.buildReadNotificationOperation.html)
- [`Client.broadcast`](/api/classes/index.Client.html#broadcast)
---
## Broadcast safely
Source: site/guides/broadcast-safely.md
Canonical URL: https://dblurt.beblurt.com/guides/broadcast-safely.html
Purpose: Sign and broadcast with explicit key and side-effect boundaries.
# Broadcast safely
Broadcast operations submit signed transactions to Blurt Layer 1. They can change account state, create content, vote, transfer funds, update custom JSON and perform other irreversible actions.
Use this guide before adding `client.broadcast` to an application. If you only need blockchain data, use [Read chain data](./read-chain-data.md) or [Use Nexus social data](./use-nexus-social-data.md) instead.
## The broadcast boundary
A safe application keeps three stages separate:
```text
1. Query blockchain data
No private key. No chain change.
2. Build an operation
Local payload construction. Still no broadcast.
3. Sign and broadcast
Private key or wallet approval required. Real chain effect.
```
Do not collapse these stages in user interfaces. Let users inspect what will be signed and broadcast.
## Authority selection
Different operations require different authorities.
| Operation family | Typical authority | Examples |
| --- | --- | --- |
| Social/content actions | posting | vote, comment, delete comment, follow, reblog, community subscribe |
| Funds and account-sensitive actions | active | transfer, vesting, delegation, savings, escrow, proposals |
| Witness and governance actions | active/owner by operation | witness vote/proxy/update, witness properties, proposal create/vote/remove |
| Account recovery / ownership changes | owner or recovery-account authority | recovery request, recovery confirmation, recovery-account change |
| Memo decryption/encryption | memo key | not a broadcast authority |
Use the least powerful authority that satisfies the operation. Read [Accounts and authorities](../learn/accounts-and-authorities.md) before asking users for keys.
## Never hard-code private keys
Private keys are application secrets. Do not commit them, paste them into examples, or bake them into browser bundles.
Prefer:
- wallet integrations;
- user-controlled signing flows;
- environment variables for local scripts;
- encrypted stores for backend services;
- short-lived explicit approval flows.
Avoid:
- source-code key literals;
- logging private keys or signed payloads with secrets;
- asking for active/owner keys when posting authority is enough;
- browser signing flows without an XSS and supply-chain threat model.
## Build before broadcasting
Use operation builders when your application needs previews, tests or external signing.
```ts
import { buildPostOperation } from '@beblurt/dblurt';
const operation = buildPostOperation({
author: 'alice',
title: 'Hello Blurt',
body: 'Body text',
tags: ['blurt', 'sdk']
});
console.log(operation);
```
This creates a Layer 1 operation. It does not sign and does not broadcast.
Builders are useful when you want to show the exact operation payload before handing it to a wallet or signing workflow.
## Broadcast a vote
This example shows the shape of a direct broadcast workflow. It assumes your application already has a safe key-handling path.
```ts
import { Client, PrivateKey } from '@beblurt/dblurt';
const client = new Client(['https://rpc.blurt.blog']);
const key = PrivateKey.fromString(process.env.BLURT_POSTING_KEY ?? '');
const confirmation = await client.broadcast.vote({
voter: 'alice',
author: 'bob',
permlink: 'hello-blurt',
weight: 10_000
}, key);
console.log(confirmation.id);
```
For application code, validate all identities and the vote weight before signing.
## Broadcast custom JSON
Social helpers such as follows, reblogs and community actions are `custom_json` operations.
```ts
const confirmation = await client.broadcast.follow('alice', 'bob', key);
console.log(confirmation.id);
```
For custom application payloads, use `customJson` directly:
```ts
await client.broadcast.customJson({
required_auths: [],
required_posting_auths: ['alice'],
id: 'my-app',
json: JSON.stringify({ action: 'ping', ts: Date.now() })
}, key);
```
Keep custom JSON payloads deterministic and inspectable before signing.
## Broadcast helper families
`client.broadcast` provides first-class helpers for the Layer 1 operation families normal applications are likely to own:
| Workflow | Helpers |
| --- | --- |
| Content | `comment()`, `commentOptions()`, `deleteComment()` |
| Voting/social custom JSON | `vote()`, `follow()`, `unfollow()`, `mute()`, `unmute()`, `reblog()`, `undoReblog()`, community helpers |
| Funds and vesting | `transfer()`, `transferToVesting()`, `withdrawVesting()`, `setWithdrawVestingRoute()`, `delegateVestingShares()` |
| Savings | `transferToSavings()`, `transferFromSavings()`, `cancelTransferFromSavings()` |
| Escrow | `escrowTransfer()`, `escrowApprove()`, `escrowDispute()`, `escrowRelease()` |
| Account recovery | `requestAccountRecovery()`, `recoverAccount()`, `changeRecoveryAccount()` |
| Witness management | `accountWitnessVote()`, `witnessUpdate()`, `witnessSetProperties()` |
| Deprecated compatibility | `accountWitnessProxy()`, `claimAccount()`, `createClaimedAccount()` remain serializable, but current Blurt Layer 1 evaluators reject them after hardfork activation; see [Deprecations](../reference/deprecations.md). |
| Governance proposals | `createProposal()`, `updateProposalVotes()`, `removeProposal()` |
Use `sendOperations()` when you need to submit a valid Layer 1 operation that intentionally has no dedicated helper.
## Prepare and sign without broadcasting
Some applications need to prepare and sign before submitting through a separate channel.
```ts
const transaction = await client.broadcast.prepareTransaction([
['vote', {
voter: 'alice',
author: 'bob',
permlink: 'hello-blurt',
weight: 10_000
}]
]);
const signed = client.broadcast.sign(transaction, key);
console.log(signed.signatures);
```
This still handles sensitive signing material. Treat it as a high-risk path even if submission happens later.
## Ambiguous failures
Broadcast failures are different from failed blockchain queries.
If a network timeout happens after submission, the transaction may have been:
- accepted and included;
- rejected by the node;
- still propagating;
- never received by the endpoint.
Applications should retain and surface enough local context to help users reconcile the result. Do not blindly retry a broadcast operation as if it were an ordinary data query.
When public RPC nodes expose `transaction_status_api`, use `client.transactionStatus.findTransaction(confirmation.id)` to check a transaction id after broadcast. Status lookup is an observation step; it does not make a retry automatically safe.
## Timeout and retry semantics
Treat broadcast timeouts as ambiguous. A timeout after submission is not proof that the transaction failed and not proof that it succeeded.
Recommended application behavior:
1. keep the locally generated transaction id;
2. show the user that the result is unknown;
3. query transaction status where the selected RPC endpoint exposes `transaction_status_api`;
4. avoid automatic duplicate broadcasts unless the application has a protocol-aware idempotency plan.
`client.transactionStatus.findTransaction(id)` is an observation helper, not a retry policy. Applications still own duplicate-submission, UX and reconciliation decisions.
## Before you broadcast
Check all of the following:
1. The user intended the action.
2. The operation payload is visible or otherwise auditable.
3. The operation uses the least powerful authority.
4. The signing key or wallet belongs to the expected account.
5. The endpoint list is trusted.
6. The UI can explain success, rejection and ambiguous network failures.
7. The application has a plan for duplicate submissions and retries.
## Related docs
- [Accounts and authorities](../learn/accounts-and-authorities.md)
- [Blockchain queries vs broadcast operations](../learn/blockchain-queries-vs-broadcast-operations.md)
- [Publish content](./publish-content.md)
- [Social actions](./social-actions.md)
- [Handle errors](./handle-errors.md)
- [Security policy](https://gitlab.com/beblurt/dblurt/-/blob/main/SECURITY.md)
## API details
Use the API reference for exact method signatures and transaction types:
- [`Client.broadcast`](/api/classes/index.Client.html#broadcast)
- [`buildPostOperation`](/api/functions/index.buildPostOperation.html)
- [`PrivateKey`](/api/classes/index.PrivateKey.html)
---
## Memo and key utilities
Source: site/guides/memo-and-key-utilities.md
Canonical URL: https://dblurt.beblurt.com/guides/memo-and-key-utilities.html
Purpose: Work with Blurt keys, signatures and encrypted memos.
# Memo and key utilities
Use this guide when your application needs to work directly with Blurt keys, signatures or encrypted transfer memos.
For broadcast authority choices, read [Accounts and authorities](../learn/accounts-and-authorities.md) and [Broadcast safely](./broadcast-safely.md). For exact API signatures, use the API reference.
## Key classes
`@beblurt/dblurt` exports the protocol key and signature classes used by transaction signing and memo encryption:
```ts
import { PrivateKey, PublicKey, Signature } from '@beblurt/dblurt';
const privateKey = PrivateKey.fromString(process.env.BLURT_POSTING_KEY ?? '');
const publicKey = privateKey.createPublic();
console.log(publicKey.toString());
```
Use the key role that matches the workflow:
| Key role | Typical use |
| --- | --- |
| posting | content, votes and social custom JSON |
| active | transfers, vesting, savings, proposals and other account/fund operations |
| owner | recovery and ownership changes |
| memo | encrypted transfer memos |
A memo key is not a broadcast authority. It is used for memo encryption/decryption.
## Plain and encrypted memos
Layer 1 transfer operations carry a `memo` string. Applications decide whether the memo is plain text or encrypted.
`encodeMemo()` follows the Blurt convention that only memos beginning with `#` are encrypted. Plain memos are returned unchanged.
```ts
import { encodeMemo } from '@beblurt/dblurt';
const encrypted = encodeMemo(
'#invoice 1234',
senderPrivateMemoKey,
receiverPublicMemoKey
);
```
`decodeMemo()` decrypts memos beginning with `#`. Plain memos are returned unchanged.
```ts
import { decodeMemo } from '@beblurt/dblurt';
const plain = decodeMemo(encrypted, receiverPrivateMemoKey);
```
## Legacy memo security limitations
Encrypted memos use the legacy Blurt/Graphene-compatible memo format. Keep compatibility expectations separate from modern encryption guarantees:
- memo encryption is not a replacement for transaction authorization;
- memo keys encrypt and decrypt, while active/posting/owner keys authorize operations;
- applications should treat malformed encrypted memos as untrusted input and handle decode failures explicitly;
- do not build new high-security messaging protocols on top of the legacy memo format without a separate authenticated design.
`decodeMemo()` returns plain memos unchanged, but encrypted memos beginning with `#` must decode successfully before an application treats the result as trusted plaintext.
## Transfer workflow
When broadcasting a transfer with an encrypted memo:
1. Resolve the recipient's public memo key from account data.
2. Encrypt the memo locally with `encodeMemo()`.
3. Put the encrypted string in the transfer operation's `memo` field.
4. Sign the transfer with the required active authority.
```ts
const [receiver] = await client.condenser.getAccounts(['bob']);
const memo = encodeMemo('#payment for invoice 1234', senderMemoKey, receiver.memo_key);
await client.broadcast.transfer({
from: 'alice',
to: 'bob',
amount: '1.000 BLURT',
memo
}, activeKey);
```
## Verification notes
- Store private keys in application-controlled secret storage or wallet-controlled flows.
- Do not log private keys.
- Do not assume a transfer memo is encrypted unless it starts with `#` and decodes successfully.
- Keep memo encryption separate from broadcast signing: memo keys encrypt/decrypt; active keys authorize transfers.
## API details
- [`PrivateKey`](/api/classes/index.PrivateKey.html)
- [`PublicKey`](/api/classes/index.PublicKey.html)
- [`Signature`](/api/classes/index.Signature.html)
- [`encodeMemo`](/api/functions/index.encodeMemo.html)
- [`decodeMemo`](/api/functions/index.decodeMemo.html)
- [`cryptoUtils`](/api/variables/index.cryptoUtils.html)
---
## Read models
Source: site/guides/read-models.md
Canonical URL: https://dblurt.beblurt.com/guides/read-models.html
Purpose: High-level account, witness, vote and social summaries.
# Read models
Read models are higher-level SDK data models built from lower-level Layer 1 and Nexus helpers.
Use `client.read` when your application wants structured summaries without turning raw RPC objects into UI-specific presentation text.
## What read models are for
| Need | Start with |
| --- | --- |
| account, stake and reward summary | `client.read.getAccountSummary()` |
| outgoing delegation summary | `client.read.getOutgoingDelegationSummary()` |
| social graph counts and samples | `client.read.getSocialGraphSummary()` |
| witness summary | `client.read.getWitnessSummary()` |
| current vote-value estimate | `client.read.estimateVoteValue()` |
Read models are still data models. They do not own UI copy, translations, fiat formatting, ranking policy or application-specific recommendations.
## Account summary
```ts
const summary = await client.read.getAccountSummary('beblurt');
console.log({
account: summary.name,
balance: summary.balance,
mana: summary.mana_percent
});
```
Use this when an application needs a practical account overview and does not want to assemble every field manually from raw RPC responses.
## Vote value estimate
```ts
const vote = await client.read.estimateVoteValue('beblurt', 100);
console.log(vote.vote_value_blurt);
```
Vote value depends on current mana and chain economics. Treat it as a snapshot, not a permanent value.
## Why not put this in Nexus?
Nexus is an indexed/social Layer 2 surface. Read models can compose Layer 1 helpers, Nexus helpers and local calculations depending on the model.
The distinction is:
- `client.nexus` gives indexed social views;
- `client.condenser`, `client.database`, `client.blockchain` give Layer 1 data;
- `client.read` gives SDK-owned data models composed from existing primitives.
## What read models do not do
They do not:
- broadcast operations;
- sign transactions;
- mutate chain state;
- produce natural-language summaries;
- hide source-layer distinctions;
- replace the API reference for exact return types.
## Validated example
- [`examples/node/read-account-summary.cjs`](https://gitlab.com/beblurt/dblurt/-/blob/main/examples/node/read-account-summary.cjs)
- [`examples/node/estimate-vote-value.cjs`](https://gitlab.com/beblurt/dblurt/-/blob/main/examples/node/estimate-vote-value.cjs)
## Related docs
- [Read chain data](./read-chain-data.md)
- [Use Nexus social data](./use-nexus-social-data.md)
- [Read account summary recipe](../recipes/read-account-summary.md)
- [Estimate vote value recipe](../recipes/estimate-vote-value.md)
## API details
- [`ReadModels`](/api/classes/index.ReadModels.html)
- [`Client.read`](/api/classes/index.Client.html#read)
---
## Handle errors
Source: site/guides/handle-errors.md
Canonical URL: https://dblurt.beblurt.com/guides/handle-errors.html
Purpose: Error taxonomy and retry behavior.
# Handle errors
`@beblurt/dblurt` preserves historical error names and messages for compatibility while adding structured classification metadata for applications that need safer retry and display decisions.
Use this guide when deciding whether to retry, fail over, surface validation feedback or stop a workflow.
## Classify first
```ts
import { classifyError, isDBlurtError } from '@beblurt/dblurt';
try {
await client.condenser.getAccounts(['beblurt']);
} catch (error) {
const metadata = classifyError(error);
if (metadata.retryable) {
// retry or fail over according to your policy
}
if (isDBlurtError(error)) {
console.error(metadata.category, metadata.code);
}
}
```
Avoid string-matching arbitrary error messages when stable classification metadata is available.
## Error categories
| Category | Typical meaning | Common action |
| --- | --- | --- |
| `validation` | SDK input rejected before RPC/broadcast | ask caller/user to fix input |
| `timeout` | request exceeded configured timeout | retry/fail over if workflow is a blockchain query |
| `transport` | network or HTTP-level failure | retry/fail over if safe |
| `rpc_application` | RPC node returned an application error | inspect code/data; retry only when justified |
| `serialization` | signing/serialization failed | fix payload/key handling |
| `unknown` | not recognized | fail safely and log non-sensitive context |
Exact metadata fields belong to the API reference.
## Query retries vs broadcast retries
Blockchain queries can often be retried with bounded backoff because they do not submit transactions.
Broadcast operations are different. A timeout after submission may be ambiguous. The transaction may have been accepted, rejected, still propagating or never received.
| Workflow | Retry posture |
| --- | --- |
| blockchain query | retry/fail over when `retryable` and bounded |
| blockchain parsing | retry from last checkpoint when safe |
| operation builder | fix validation input; retry is usually not useful |
| broadcast operation | do not blindly retry; reconcile transaction context first |
## Validation errors
Validation errors are useful for user correction:
```ts
import { ValidationError } from '@beblurt/dblurt';
if (error instanceof ValidationError) {
console.error(error.field, error.path);
}
```
Do not include private keys, signed payloads with sensitive context or secret environment values in logs.
## RPC errors
RPC application errors come from a Blurt RPC endpoint. Preserve the distinction between:
- a method or payload rejected by the node;
- a transport problem reaching the node;
- a timeout waiting for the response;
- a mismatched or malformed JSON-RPC response.
This distinction matters for retry policy and user-facing messages.
## Validated example
- [`examples/node/classify-retryable-error.cjs`](https://gitlab.com/beblurt/dblurt/-/blob/main/examples/node/classify-retryable-error.cjs)
## Related docs
- [Handle retryable errors recipe](../recipes/handle-retryable-errors.md)
- [RPC endpoints and failover](./rpc-endpoints-and-failover.md)
- [Broadcast safely](./broadcast-safely.md)
- [Parse blockchain history](./parse-blockchain-history.md)
- [Errors reference](../reference/errors.md)
## API details
- [`classifyError`](/api/functions/index.classifyError.html)
- [`isDBlurtError`](/api/functions/index.isDBlurtError.html)
- [`ValidationError`](/api/classes/index.ValidationError.html)
---
## Runtime and browser
Source: site/guides/runtime-and-browser.md
Canonical URL: https://dblurt.beblurt.com/guides/runtime-and-browser.html
Purpose: Understand Node.js, browser and bundle constraints.
# Runtime and browser
Use this guide to decide how to load `@beblurt/dblurt` in Node.js, browser bundles and direct browser experiments.
Runtime support is owned by `package.json` and validated by CI. This page explains how to use the documented surfaces without turning package metadata into a second compatibility table.
## Runtime requirements
Check the canonical metadata first:
- `package.json` `engines.node` owns the Node.js baseline;
- `package.json` `types` and `typings` own declaration entrypoints;
- `package.json` `browser` owns browser bundler remapping;
- `package.json` `browserslist` owns browser feature expectations.
For the current support model, use [Compatibility](../reference/compatibility.md).
## Node.js usage
Install from npm:
```bash
npm install @beblurt/dblurt
```
Use TypeScript + ESM-style imports in new examples and modern app code:
```ts
import { Client } from '@beblurt/dblurt';
const client = new Client(['https://rpc.blurt.blog']);
const props = await client.condenser.getDynamicGlobalProperties();
console.log(props.head_block_number);
```
CommonJS remains a compatibility surface. Use [Package exports](../reference/package-exports.md) when you need runtime entrypoint details.
## Browser usage through a bundler
For browser applications built with modern bundlers, install from npm and import normally:
```ts
import { Client } from '@beblurt/dblurt';
const client = new Client(['https://rpc.blurt.blog']);
const version = await client.call('database_api', 'get_version', []);
console.log(version.blockchain_version);
```
The package browser mapping points browser-oriented builds away from the Node entrypoint. Your bundler is still responsible for dependency resolution, minification and security controls.
## Direct browser experiments
For quick experiments, the browser bundle is available from UNPKG:
```html
```
Use `@latest` only for experiments and demos. Pin an exact package version in production CDN usage.
For a complete browser file, see [`examples/browser/unpkg.html`](https://gitlab.com/beblurt/dblurt/-/blob/main/examples/browser/unpkg.html).
## Self-hosting the browser bundle
Production browser applications should consider self-hosting the bundle or using Subresource Integrity with a pinned CDN asset. The generated runtime bundle is intended to be usable under a strict Content Security Policy without `unsafe-eval`; maintainers verify this with the CSP runtime check before release.
After installing the package, serve:
```text
node_modules/@beblurt/dblurt/dist/dblurt.js
node_modules/@beblurt/dblurt/dist/dblurt.d.ts
```
Example:
```html
```
## Required browser features
Browser targets are defined by package metadata. The current browser expectation includes:
- `fetch`;
- `AbortController`.
Do not infer support for every browser or browser-like runtime. React Native, unusual WebViews and constrained embedded browsers need explicit validation before they are documented as supported.
## Browser security model
Browser apps are exposed to XSS, malicious dependencies, compromised CDN assets and user-device risks. A strict CSP is recommended, but it does not replace normal key-custody and dependency controls.
For blockchain query screens, a browser flow can be straightforward: create a client, query public RPC endpoints and render the result.
For signing or broadcast workflows, browser code becomes security-sensitive:
- do not hard-code private keys;
- do not store high-privilege keys in local storage;
- prefer wallet/user-controlled signing flows;
- protect against XSS before handling secrets;
- make the operation payload visible before signing;
- avoid active/owner authority unless the operation requires it.
Read [Broadcast safely](./broadcast-safely.md) and [Accounts and authorities](../learn/accounts-and-authorities.md) before adding browser signing.
## RPC endpoint considerations
Browsers can only call endpoints that permit the request through CORS and network policy. Provide an ordered endpoint list when reliability matters:
```ts
const client = new Client([
'https://rpc.blurt.blog',
'https://rpc.beblurt.com',
'https://blurt-rpc.saboin.com'
], {
timeout: 15_000,
failoverThreshold: 3
});
```
Do not accept arbitrary user-provided RPC URLs in production browser or backend services without a threat model. See [RPC endpoints and failover](./rpc-endpoints-and-failover.md).
## Related docs
- [Compatibility](../reference/compatibility.md)
- [Package exports](../reference/package-exports.md)
- [TypeScript](./typescript.md)
- [RPC endpoints and failover](./rpc-endpoints-and-failover.md)
- [Broadcast safely](./broadcast-safely.md)
## API details
Use the API reference for exact constructor options and runtime-facing types:
- [`Client`](/api/classes/index.Client.html)
- [`ClientOptions`](/api/interfaces/index.ClientOptions.html)
---
## RPC endpoints and failover
Source: site/guides/rpc-endpoints-and-failover.md
Canonical URL: https://dblurt.beblurt.com/guides/rpc-endpoints-and-failover.html
Purpose: Configure endpoint lists and failure behavior.
# RPC endpoints and failover
`Client` accepts one Blurt RPC endpoint or an ordered endpoint list. Use this guide when your application needs resilient blockchain queries or broadcast operations across node outages, timeouts or temporary endpoint failures.
Endpoint strategy is application policy. The SDK provides timeout and failover behavior, but your application still decides which endpoints are trusted and how much retry behavior is acceptable.
## Configure an endpoint list
```ts
import { Client } from '@beblurt/dblurt';
const client = new Client([
'https://rpc.blurt.blog',
'https://rpc.beblurt.com',
'https://blurt-rpc.saboin.com'
], {
timeout: 15_000,
failoverThreshold: 3,
consoleOnFailover: true
});
```
Use multiple endpoints when your application should survive one node being unavailable. Keep the list ordered by your trust and reliability preference.
## What failover does
The currently validated behavior includes:
- the first healthy endpoint remains sticky across repeated successful calls;
- timeout failures can move the client to the next endpoint;
- `client.currentAddress` reflects the active endpoint;
- `timeout: 0` remains a compatibility-sensitive no-immediate-timeout path on healthy local endpoints;
- FC-style JSON-RPC application errors map to the public `RPCError` shape;
- JSON-RPC responses with mismatched ids are rejected.
Do not assume every HTTP status, timeout or JSON-RPC application error should be retried the same way. Broadcast operations need stricter handling than ordinary blockchain queries.
## Client options
| Option | Default owner | Use it for |
| --- | --- | --- |
| `timeout` | SDK default; see API details | Bounding a single RPC request. |
| `failoverThreshold` | SDK default; see API details | Limiting retry/failover rounds. |
| `consoleOnFailover` | SDK default; see API details | Debugging endpoint switching during development. |
| `backoff` | SDK transport behavior | Custom retry delay calculation. |
| `chainId` | Blurt mainnet default | Non-mainnet or custom-chain use. |
| `addressPrefix` | Blurt mainnet default | Non-mainnet or custom-prefix use. |
Exact defaults and option types belong to the [API reference](../reference/api.md), not this guide.
## Query retries vs broadcast retries
Blockchain queries can often be retried with bounded backoff because they do not submit a transaction.
Broadcast operations are different. A timeout after submission can be ambiguous: the transaction may have been accepted, rejected, still propagating or never received.
Use this policy:
| Workflow | Retry guidance |
| --- | --- |
| Blockchain query | Bounded retry/failover is usually reasonable. |
| Local operation builder | Retry is not relevant; fix the input. |
| Broadcast operation | Do not blindly retry; preserve local transaction context and reconcile status. |
See [Broadcast safely](./broadcast-safely.md) before retrying broadcast operations.
## Endpoint trust
RPC endpoints can affect what your application sees. A malicious, stale or misconfigured endpoint can:
- return stale chain state;
- fail selectively;
- delay responses;
- influence reference data used when preparing transactions;
- cause confusing UX around account balances, votes or broadcast status.
Use trusted HTTPS endpoints in production. Server-side applications should not accept arbitrary user-provided RPC URLs without allowlisting and network egress controls.
## Browser considerations
Browser clients also depend on CORS, network reachability and the user environment. An endpoint that works in Node.js may not be usable from a browser page.
For browser apps:
- prefer endpoints known to support browser requests;
- set reasonable timeouts;
- show users when endpoint failover occurs only if it helps them act;
- avoid handling private keys in browser code unless your threat model supports it.
See [Runtime and browser](./runtime-and-browser.md).
## Operational monitoring
For node health monitoring outside the SDK, see the Blurt node checker:
Operational monitoring can inform endpoint lists, but the SDK does not automatically choose endpoints from that project.
## Example: bounded query with failover
```ts
const props = await client.condenser.getDynamicGlobalProperties();
console.log({
endpoint: client.currentAddress,
head: props.head_block_number,
irreversible: props.last_irreversible_block_num
});
```
This confirms which endpoint served the query and what chain state it reported.
## Related docs
- [Read chain data](./read-chain-data.md)
- [Handle errors](./handle-errors.md)
- [Broadcast safely](./broadcast-safely.md)
- [Runtime and browser](./runtime-and-browser.md)
- [Security policy](https://gitlab.com/beblurt/dblurt/-/blob/main/SECURITY.md)
## API details
Use the API reference for exact option names, default behavior and types:
- [`Client`](/api/classes/index.Client.html)
- [`ClientOptions`](/api/interfaces/index.ClientOptions.html)
- [`classifyError`](/api/functions/index.classifyError.html)
---
## TypeScript
Source: site/guides/typescript.md
Canonical URL: https://dblurt.beblurt.com/guides/typescript.html
Purpose: Preferred TypeScript and ESM-style usage.
# TypeScript
`@beblurt/dblurt` ships TypeScript declarations for the public package surface. Use this guide for import style, typed clients, examples and the boundary between guide-level explanations and exact API reference details.
For new documentation and application examples, prefer TypeScript with ESM-style imports.
## Install and import
```bash
npm install @beblurt/dblurt
```
```ts
import { Client } from '@beblurt/dblurt';
const client = new Client(['https://rpc.blurt.blog']);
```
Package metadata owns the declaration entrypoints. Do not copy the current package version or compiler smoke-test version into documentation; use `package.json` and CI validation as the source of truth.
## A typed blockchain query
```ts
import { Client, type ExtendedAccount } from '@beblurt/dblurt';
const client = new Client(['https://rpc.blurt.blog']);
async function loadAccount(name: string): Promise {
const accounts = await client.condenser.getAccounts([name]);
return accounts[0];
}
const account = await loadAccount('beblurt');
console.log(account?.balance);
```
This example uses a Layer 1 account query and does not require any private key.
## Prefer option objects for complex helpers
Some helpers support historical positional signatures for compatibility. For new code, prefer option objects when a helper has pagination, nullable cursors, filters or observer values.
```ts
const posts = await client.nexus.getRankedPosts({
sort: 'trending',
tag: 'blurt',
limit: 10,
observer: null
});
```
Option objects make call sites easier to review and safer to change.
## Use exported enums and types
Import exported enums and types instead of passing undocumented string values.
```ts
import { BlockchainMode } from '@beblurt/dblurt';
const irreversible = await client.blockchain.getCurrentBlockNum(BlockchainMode.Irreversible);
console.log(irreversible);
```
When exact literal unions, overloads or option fields matter, use the API reference rather than copying the shape into a guide.
## Type-only imports
Use `type` imports when a symbol is only used at compile time:
```ts
import { Client, type ExtendedAccount } from '@beblurt/dblurt';
```
This keeps application code clear and avoids implying that type-only symbols are runtime values.
## Error typing
`classifyError` lets applications inspect stable metadata without depending on string matching.
```ts
import { classifyError, isDBlurtError } from '@beblurt/dblurt';
try {
await client.condenser.getAccounts(['beblurt']);
} catch (error) {
const metadata = classifyError(error);
if (metadata.retryable) {
// retry or fail over according to your application policy
}
if (isDBlurtError(error)) {
console.error(error.category, error.code);
}
}
```
Do not log private keys, signed transactions with sensitive context or user secrets in error handlers.
## CommonJS compatibility
The package still supports CommonJS consumers. Keep CommonJS examples on compatibility pages rather than guide pages, and use [Package exports](../reference/package-exports.md) when you need runtime entrypoint details.
The preferred learning path remains TypeScript + ESM-style imports.
## What this page intentionally does not duplicate
This guide does not duplicate:
- all exported interfaces;
- constructor overloads;
- every Nexus option object;
- operation tuple shapes;
- generated method signatures;
- compiler-version promises not declared in package metadata.
Those details belong to the generated API reference and package metadata.
## Validation path
The documentation validation command compiles the TypeScript example path without emitting output:
```bash
npm run docs:check
```
Project tests also verify that the public declaration bundle is present and that test-framework ambient types do not leak into published declarations.
## Validated examples
- [`examples/typescript/read-account.ts`](https://gitlab.com/beblurt/dblurt/-/blob/main/examples/typescript/read-account.ts)
- [`examples/typescript/build-operations.ts`](https://gitlab.com/beblurt/dblurt/-/blob/main/examples/typescript/build-operations.ts)
## Related docs
- [Package exports](../reference/package-exports.md)
- [Compatibility](../reference/compatibility.md)
- [Runtime and browser](./runtime-and-browser.md)
- [Read chain data](./read-chain-data.md)
- [Use Nexus social data](./use-nexus-social-data.md)
## API details
Use the API reference for exact exports, method signatures and option types:
- [API reference](../reference/api.md)
- [`Client`](/api/classes/index.Client.html)
- [`ClientOptions`](/api/interfaces/index.ClientOptions.html)
- [`BlockchainMode`](/api/enums/index.BlockchainMode.html)
- [`classifyError`](/api/functions/index.classifyError.html)
---
## Recipes index
Source: site/recipes/index.md
Canonical URL: https://dblurt.beblurt.com/recipes/
Purpose: Task-oriented workflows and safety levels.
# Recipes
Recipes are task-focused pages that show how to accomplish common jobs with `dblurt`.
They are intentionally different from API reference pages. A recipe should explain the task, safety level and decision points. The API reference remains the source for exact signatures, overloads and return types.
## Safety levels
| Level | Meaning | Where it appears |
| --- | --- | --- |
| `blockchain-query` | Calls public RPC APIs and does not sign or broadcast. | First-run examples, account reads, Nexus reads, read models. |
| `static` | Runs locally without network calls. | Operation builders, error classification examples. |
| `side-effectful` | Signs or broadcasts a transaction. | Isolated safety-focused recipes only. |
The default learning path is blockchain queries first. Side-effectful recipes must link back to [Accounts and authorities](../learn/accounts-and-authorities.md) and [Blockchain queries vs broadcast operations](../learn/blockchain-queries-vs-broadcast-operations.md).
## Recommended first recipes
| Recipe | Safety | Validated source |
| --- | --- | --- |
| [Read account summary](./read-account-summary.md) | blockchain-query | [`examples/node/read-account-summary.cjs`](https://gitlab.com/beblurt/dblurt/-/blob/main/examples/node/read-account-summary.cjs) |
| [List account posts](./list-account-posts.md) | blockchain-query | [`examples/node/read-nexus-ranked-posts.cjs`](https://gitlab.com/beblurt/dblurt/-/blob/main/examples/node/read-nexus-ranked-posts.cjs) and Nexus helpers |
| [Estimate vote value](./estimate-vote-value.md) | blockchain-query | [`examples/node/estimate-vote-value.cjs`](https://gitlab.com/beblurt/dblurt/-/blob/main/examples/node/estimate-vote-value.cjs) |
| [Parse recent blocks](./parse-recent-blocks.md) | blockchain-query | [`examples/node/stream-block-numbers.cjs`](https://gitlab.com/beblurt/dblurt/-/blob/main/examples/node/stream-block-numbers.cjs), [`examples/node/read-blocks-with-helper.cjs`](https://gitlab.com/beblurt/dblurt/-/blob/main/examples/node/read-blocks-with-helper.cjs), [`examples/node/read-operations-with-helper.cjs`](https://gitlab.com/beblurt/dblurt/-/blob/main/examples/node/read-operations-with-helper.cjs) |
| [Read account history](./read-account-history.md) | blockchain-query | [`examples/node/read-account-history.cjs`](https://gitlab.com/beblurt/dblurt/-/blob/main/examples/node/read-account-history.cjs) |
| [Handle retryable errors](./handle-retryable-errors.md) | static | [`examples/node/classify-retryable-error.cjs`](https://gitlab.com/beblurt/dblurt/-/blob/main/examples/node/classify-retryable-error.cjs) |
| [Build post operation](./build-post-operation.md) | static | [`examples/node/build-post-operation.cjs`](https://gitlab.com/beblurt/dblurt/-/blob/main/examples/node/build-post-operation.cjs) |
| [Sign and broadcast vote](./sign-and-broadcast-vote.md) | side-effectful | intentionally no copy-paste live example yet |
## Source examples
The repository keeps executable examples under [`examples/`](https://gitlab.com/beblurt/dblurt/-/tree/main/examples). Each listed example declares:
- purpose;
- runtime;
- safety level;
- validation level;
- required RPC capability;
- expected output.
`npm run docs:check` validates example metadata and runs blockchain-query/static Node examples unless live examples are explicitly skipped.
## When to use a recipe
Use recipes when you know the task you want to perform. Use Start and Learn pages when you are still building the mental model. Use the [API reference](../reference/api.md) when you need exact method details.
---
## Read account summary
Source: site/recipes/read-account-summary.md
Canonical URL: https://dblurt.beblurt.com/recipes/read-account-summary.html
Purpose: Read account, stake and social summary data.
# Read account summary
Use this recipe when an application needs a compact account view rather than raw RPC objects.
For exact types and method signatures, use the [API reference](../reference/api.md). This page explains why the read model exists and how to use it safely.
## Safety
Safety level: `blockchain-query`.
This recipe reads public account, profile, mana and chain data. It does not require a private key and does not broadcast a transaction.
## Why use a read model?
Raw account data is useful, but application screens often need a grouped summary:
- account identity and activity;
- wallet and stake information;
- follower/following counts;
- witness-vote count;
- lifetime reward totals.
`client.read.getAccountSummary()` composes existing Layer 1 and Nexus reads into a structured SDK data model. It does not create UI text, calculate fiat prices or make application policy decisions.
## Example
```ts
import { Client } from '@beblurt/dblurt';
const client = new Client(rpcList, { timeout: 15_000, failoverThreshold: 3 });
const summary = await client.read.getAccountSummary('beblurt');
console.log({
account: summary.account.name,
mana: summary.account.mana_percent,
balance: summary.wallet.balance.toString(),
vestingToBlurt: summary.wallet.vesting_to_blurt
});
```
## API symbols
- [`ReadModels.getAccountSummary`](/api/classes/index.ReadModels.html#getAccountSummary)
- [`AccountReadModel`](/api/interfaces/index.AccountReadModel.html)
## Validated source
Executable source: [`examples/node/read-account-summary.cjs`](https://gitlab.com/beblurt/dblurt/-/blob/main/examples/node/read-account-summary.cjs).
Run locally from the repository:
```bash
node examples/node/read-account-summary.cjs beblurt
```
This example is included in `npm run docs:check`.
## What to verify in your app
- Choose an endpoint strategy suitable for your app.
- Treat Nexus profile fields as indexed social context, not as a replacement for Layer 1 authorities.
- Format balances and stake in the UI layer.
- Handle missing accounts and transport failures.
Related: [Blurt mental model](../learn/blurt-mental-model.md), [Layer 1 and Nexus Layer 2](../learn/layer-1-and-nexus.md), [Read models guide](../guides/read-models.md).
---
## List account posts
Source: site/recipes/list-account-posts.md
Canonical URL: https://dblurt.beblurt.com/recipes/list-account-posts.html
Purpose: Read recent posts for an account using Nexus social data.
# List account posts
Use this recipe when you need social or indexed post lists for an account or feed-like surface.
Nexus is the right starting point for social discovery. Layer 1 remains the source for canonical operation and authority data.
## Safety
Safety level: `blockchain-query`.
This recipe queries Nexus/Bridge data. It does not require a private key and does not broadcast.
## Choose the query shape
For new code, prefer option-object Nexus calls when a helper supports them. Option objects make cursors, filters, sort modes and observer behavior explicit.
Conceptually:
```ts
const posts = await client.nexus.getAccountPosts({
account: 'beblurt',
sort: 'posts',
limit: 10,
observer: null
});
```
For ranked discovery rather than one account's posts:
```ts
const posts = await client.nexus.getRankedPosts({
sort: 'trending',
limit: 10,
tag: 'blurt',
observer: null
});
```
## Why Nexus?
A social UI usually wants already-indexed views such as:
- account post lists;
- ranked feeds;
- community pages;
- discussion trees;
- profile summaries.
Those are application-friendly views. If the next step is security-sensitive, verify the relevant Layer 1 state before signing or broadcasting.
## Validated source
Related executable source: [`examples/node/read-nexus-ranked-posts.cjs`](https://gitlab.com/beblurt/dblurt/-/blob/main/examples/node/read-nexus-ranked-posts.cjs).
Run locally from the repository:
```bash
node examples/node/read-nexus-ranked-posts.cjs
```
This example is included in `npm run docs:check`.
## Pagination rule
When a Nexus method exposes cursor parameters, treat the cursor as part of the query state. Keep sort, filters, observer and cursor together so pagination does not accidentally switch views.
## Compatibility note
Historical positional Nexus signatures remain supported. New documentation should prefer corrected names and option-object forms when available. The misspelled `listPopComunities` helper is retained for compatibility but new docs should use `listPopCommunities`.
Related: [Layer 1 and Nexus Layer 2](../learn/layer-1-and-nexus.md), [Use Nexus social data](../guides/use-nexus-social-data.md), [Deprecations](../reference/deprecations.md).
---
## Estimate vote value
Source: site/recipes/estimate-vote-value.md
Canonical URL: https://dblurt.beblurt.com/recipes/estimate-vote-value.html
Purpose: Estimate current vote value from existing primitives.
# Estimate vote value
Use this recipe when a curator, dashboard or author-facing app needs an approximate current upvote value.
Vote value is a snapshot. It depends on account mana, vote weight and current chain reward data.
## Safety
Safety level: `blockchain-query`.
This recipe reads public chain data and performs local calculations. It does not vote and does not require a private key.
## Example
```ts
import { Client } from '@beblurt/dblurt';
const client = new Client(rpcList, { timeout: 15_000, failoverThreshold: 3 });
const estimate = await client.read.estimateVoteValue('beblurt', 100);
console.log({
account: estimate.account,
weight: estimate.weight_percent,
mana: estimate.current_mana_percent,
blurt: estimate.vote_value_blurt
});
```
## What the value means
The returned value is an SDK estimate in BLURT for the current account mana and selected vote weight. It is not a promise of final payout and does not include fiat formatting.
Applications should explain that:
- mana changes after voting and regenerates over time;
- reward pool state changes;
- post timing and chain rules can affect final outcomes;
- fiat conversion is outside the SDK read model.
## API symbols
- [`ReadModels.estimateVoteValue`](/api/classes/index.ReadModels.html#estimateVoteValue)
- [`VoteValueReadModel`](/api/interfaces/index.VoteValueReadModel.html)
## Validated source
Executable source: [`examples/node/estimate-vote-value.cjs`](https://gitlab.com/beblurt/dblurt/-/blob/main/examples/node/estimate-vote-value.cjs).
Run locally from the repository:
```bash
node examples/node/estimate-vote-value.cjs beblurt 100
```
This example is included in `npm run docs:check`.
Related: [Read models](../guides/read-models.md), [Accounts and authorities](../learn/accounts-and-authorities.md), [API reference](../reference/api.md).
---
## Parse recent blocks
Source: site/recipes/parse-recent-blocks.md
Canonical URL: https://dblurt.beblurt.com/recipes/parse-recent-blocks.html
Purpose: Bounded block parsing with `client.blockchain.getBlocks()`.
# Parse recent blocks
Safety: `blockchain-query`
This recipe shows the shape of a bounded blockchain parser. Use it when you want to inspect recent irreversible blocks without broadcasting anything.
For the complete workflow and production design notes, read [Parse blockchain history](../guides/parse-blockchain-history.md).
```ts
import { BlockchainMode, Client } from '@beblurt/dblurt';
const client = new Client(['https://rpc.blurt.blog']);
const irreversible = await client.blockchain.getCurrentBlockNum(BlockchainMode.Irreversible);
for await (const block of client.blockchain.getBlocks({
from: irreversible - 3,
to: irreversible - 1,
mode: BlockchainMode.Irreversible
})) {
console.log({
witness: block.witness,
transactions: block.transactions.length
});
}
```
Validated examples:
- [`examples/node/stream-block-numbers.cjs`](https://gitlab.com/beblurt/dblurt/-/blob/main/examples/node/stream-block-numbers.cjs)
- [`examples/node/read-blocks-with-helper.cjs`](https://gitlab.com/beblurt/dblurt/-/blob/main/examples/node/read-blocks-with-helper.cjs)
- [`examples/node/read-operations-with-helper.cjs`](https://gitlab.com/beblurt/dblurt/-/blob/main/examples/node/read-operations-with-helper.cjs)
## Why this is bounded
The parser uses an explicit `from` and `to` range so it finishes. Long-running parsers should persist checkpoints, handle retries deliberately and define whether they process irreversible or latest blocks.
## Operation parsing variant
```ts
for await (const operation of client.blockchain.getOperations({
from: irreversible - 3,
to: irreversible - 1,
mode: BlockchainMode.Irreversible
})) {
console.log(operation.op[0]);
}
```
Use [Handle errors](./handle-retryable-errors.md) for retry classification and [RPC endpoints and failover](../guides/rpc-endpoints-and-failover.md) for endpoint behavior.
---
## Read account history
Source: site/recipes/read-account-history.md
Canonical URL: https://dblurt.beblurt.com/recipes/read-account-history.html
Purpose: Audit account and virtual operation history.
# Read account history
Safety: `blockchain-query`
Use this recipe when you need an account-centered audit trail: transfers, votes, comments, rewards and other operations that touched one account.
For block-centered parsing, use [Parse recent blocks](./parse-recent-blocks.md) or [Parse blockchain history](../guides/parse-blockchain-history.md).
## Read recent account operations
```ts
import { Client } from '@beblurt/dblurt';
const client = new Client(['https://rpc.blurt.blog']);
const history = await client.condenser.getAccountHistory('alice', -1, 20);
for (const [index, entry] of history) {
console.log(index, entry.op[0]);
}
```
`getAccountHistory()` is useful when the account is the primary filter. It returns operation entries newest/oldest according to the supplied start and limit parameters owned by the Layer 1 condenser API.
## Inspect operations in a block
```ts
const { ops } = await client.accountHistory.getOpsInBlock(61_000_000, false);
for (const operation of ops) {
console.log(operation.block, operation.op[0]);
}
```
Use `only_virtual: true` when you want protocol-generated virtual operations only:
```ts
const { ops } = await client.accountHistory.getOpsInBlock(61_000_000, true);
```
## Page virtual operations
`enumVirtualOps()` reads protocol-generated effects across a block range. It is useful for indexers that care about rewards, power-down fills, proposal payments and producer rewards.
```ts
let blockRangeBegin = 61_000_000;
let operationBegin: number | undefined;
const page = await client.accountHistory.enumVirtualOps({
block_range_begin: blockRangeBegin,
block_range_end: blockRangeBegin + 100,
operation_begin: operationBegin,
limit: 100
});
console.log(page.ops.length);
blockRangeBegin = page.next_block_range_begin;
operationBegin = page.next_operation_begin;
```
Persist both cursors if your parser resumes later.
## Choosing account history or block parsing
| Task | Use |
| --- | --- |
| Show one account's recent actions | `client.condenser.getAccountHistory()` |
| Audit all operations in a known block | `client.accountHistory.getOpsInBlock()` |
| Page virtual operations across blocks | `client.accountHistory.enumVirtualOps()` |
| Build a bounded block/operation parser | `client.blockchain.getBlocks()` / `getOperations()` |
## Related docs
- [Read chain data](../guides/read-chain-data.md)
- [Parse blockchain history](../guides/parse-blockchain-history.md)
- [Handle retryable errors](./handle-retryable-errors.md)
- [`AccountHistoryAPI`](/api/classes/index.AccountHistoryAPI.html)
- [`CondenserAPI.getAccountHistory`](/api/classes/index.CondenserAPI.html#getAccountHistory)
---
## Build post operation
Source: site/recipes/build-post-operation.md
Canonical URL: https://dblurt.beblurt.com/recipes/build-post-operation.html
Purpose: Construct content operations without broadcasting.
# Build post operation
Use this recipe when you want to construct a post operation locally before deciding how it will be signed or broadcast.
Operation builders are useful for previews, tests, external signing and confirmation flows.
## Safety
Safety level: `static`.
This recipe does not require a private key, does not call RPC and does not broadcast. It only builds an operation payload.
## Example
```ts
import { buildPostOperation } from '@beblurt/dblurt';
const operation = buildPostOperation({
author: 'alice',
title: 'Hello Blurt',
body: 'Draft body',
tags: ['blurt', 'sdk']
});
console.log(operation);
```
The returned operation can be reviewed, tested, included in a transaction later or passed to a separate signing flow.
## Why build separately?
Separating construction from broadcast lets applications:
- preview the exact operation;
- validate fields before asking for a key;
- show a user confirmation screen;
- unit test generated operations;
- delegate signing to another component.
## API symbols
- [`buildPostOperation`](/api/functions/index.buildPostOperation.html)
- [`PostOperationOptions`](/api/interfaces/index.PostOperationOptions.html)
- [`ValidationError`](/api/classes/index.ValidationError.html)
## Validated source
Executable static source: [`examples/node/build-post-operation.cjs`](https://gitlab.com/beblurt/dblurt/-/blob/main/examples/node/build-post-operation.cjs).
Run locally from the repository:
```bash
node examples/node/build-post-operation.cjs
```
This example is included in `npm run docs:check`.
## Before broadcasting
Before this operation is signed and broadcast, the application must confirm:
- author account;
- generated permlink;
- title/body/metadata;
- required authority;
- user intent;
- endpoint strategy.
Related: [Blockchain queries vs broadcast operations](../learn/blockchain-queries-vs-broadcast-operations.md), [Publish content](../guides/publish-content.md), [API reference](../reference/api.md).
---
## Sign and broadcast vote
Source: site/recipes/sign-and-broadcast-vote.md
Canonical URL: https://dblurt.beblurt.com/recipes/sign-and-broadcast-vote.html
Purpose: Safety-focused side-effectful vote workflow.
# Sign and broadcast vote
This recipe is intentionally isolated from the blockchain query learning path because it is side-effectful.
A vote broadcast changes Layer 1 state. Do not copy a signing/broadcast snippet into an application until the authority, key handling and confirmation flow are understood.
## Safety
Safety level: `side-effectful`.
This page does not provide a runnable live example yet. Phase 4 keeps side-effectful examples isolated and non-executable until the maintainer approves a dedicated broadcast safety pattern.
Read first:
- [Accounts and authorities](../learn/accounts-and-authorities.md)
- [Blockchain queries vs broadcast operations](../learn/blockchain-queries-vs-broadcast-operations.md)
- [Broadcast safely](../guides/broadcast-safely.md)
## Conceptual flow
```text
1. Read target post/account data.
2. Build or inspect the vote operation.
3. Confirm voter, author, permlink and weight with the user.
4. Validate that the key satisfies the required authority.
5. Sign and broadcast once.
6. If the network response is ambiguous, inspect chain state before retrying.
```
## Non-runnable sketch
```ts
// Sketch only. Do not paste into production without your own key handling.
import { Client, PrivateKey } from '@beblurt/dblurt';
const client = new Client(rpcList);
const key = PrivateKey.fromString(process.env.BLURT_POSTING_KEY);
await client.broadcast.vote(
{ voter: 'alice', author: 'bob', permlink: 'post-permlink', weight: 10000 },
key
);
```
## Why no executable example yet?
A safe executable broadcast example needs decisions that are larger than a recipe page:
- environment-variable names;
- test account expectations;
- whether to use testnet or mainnet;
- duplicate-vote handling;
- key validation before broadcast;
- chain-state verification after broadcast;
- docs-check behavior so CI never performs side effects.
Until those are approved, broadcast documentation should remain conceptual and safety-gated.
Related: [Accounts and authorities](../learn/accounts-and-authorities.md), [Broadcast safely](../guides/broadcast-safely.md), [Handle retryable errors](./handle-retryable-errors.md).
---
## Handle retryable errors
Source: site/recipes/handle-retryable-errors.md
Canonical URL: https://dblurt.beblurt.com/recipes/handle-retryable-errors.html
Purpose: Classify timeout, transport and RPC errors.
# Handle retryable errors
Use this recipe when an application needs to decide whether retrying an operation may be appropriate.
`dblurt` exposes typed error metadata so applications can classify errors without parsing human messages.
## Safety
Safety level: `static` for the example. Real retry logic may wrap blockchain query or broadcast calls, so your application must still consider side effects.
## Retry does not mean safe
`retryable: true` means the error category looks transient, such as timeout or transport failure. It does not mean every operation is safe to repeat.
Use different policies:
| Workflow | Retry posture |
| --- | --- |
| Blockchain query | retry is usually reasonable with backoff |
| Static local operation builder | retry is rarely relevant |
| Broadcast after ambiguous network failure | do not blindly re-submit without checking chain state |
## Example
```ts
import { classifyError } from '@beblurt/dblurt';
try {
await client.condenser.getDynamicGlobalProperties();
} catch (error) {
const metadata = classifyError(error);
if (metadata.retryable) {
// Apply bounded retry/backoff policy here.
}
console.error(metadata.category, metadata.code);
}
```
## API symbols
- [`classifyError`](/api/functions/index.classifyError.html)
- [`DBlurtErrorMetadata`](/api/interfaces/index.DBlurtErrorMetadata.html)
## Validated source
Executable static source: [`examples/node/classify-retryable-error.cjs`](https://gitlab.com/beblurt/dblurt/-/blob/main/examples/node/classify-retryable-error.cjs).
Run locally from the repository:
```bash
node examples/node/classify-retryable-error.cjs
```
This example is included in `npm run docs:check`.
Related: [Handle errors](../guides/handle-errors.md), [Blockchain queries vs broadcast operations](../learn/blockchain-queries-vs-broadcast-operations.md), [Error reference](../reference/errors.md).
---
## API reference landing
Source: site/reference/api.md
Canonical URL: https://dblurt.beblurt.com/reference/api.html
Purpose: Human router to exact API details.
# API reference
Use the API reference when you already know which `dblurt` capability you need and want exact details: classes, methods, options, return values, overloads and deprecation notes.
If you are still deciding what to use, start with [Choose your path](../start/choose-your-path.md). If you want a task-oriented flow, use [Recipes](../recipes/index.md).
## Start here by goal
| Goal | Learn the workflow | API details |
| --- | --- | --- |
| Create a client and choose endpoints | [Getting started](../start/getting-started.md) | [`Client`](/api/classes/index.Client.html), [`ClientOptions`](/api/interfaces/index.ClientOptions.html) |
| Choose a helper namespace | [Choose your path](../start/choose-your-path.md) | [`Client`](/api/classes/index.Client.html) |
| Read Layer 1 data | [Read chain data](../guides/read-chain-data.md) | [`Client.condenser`](/api/classes/index.Client.html#condenser), [`Client.database`](/api/classes/index.Client.html#database), [`Client.blockchain`](/api/classes/index.Client.html#blockchain) |
| Read Nexus social/indexed data | [Use Nexus social data](../guides/use-nexus-social-data.md) | [`Nexus`](/api/classes/index.Nexus.html), [`NexusRankedPostsQuery`](/api/interfaces/index.NexusRankedPostsQuery.html), [`NexusAccountPostsQuery`](/api/interfaces/index.NexusAccountPostsQuery.html) |
| Use high-level read models | [Read models](../guides/read-models.md) | [`ReadModels`](/api/classes/index.ReadModels.html), [`AccountReadModel`](/api/interfaces/index.AccountReadModel.html), [`VoteValueReadModel`](/api/interfaces/index.VoteValueReadModel.html) |
| Build content operations | [Build post operation](../recipes/build-post-operation.md) | [`buildPostOperation`](/api/functions/index.buildPostOperation.html), [`PostOperationOptions`](/api/interfaces/index.PostOperationOptions.html) |
| Classify errors | [Handle retryable errors](../recipes/handle-retryable-errors.md) | [`classifyError`](/api/functions/index.classifyError.html), [`DBlurtErrorMetadata`](/api/interfaces/index.DBlurtErrorMetadata.html) |
| Validate authorities | [Accounts and authorities](../learn/accounts-and-authorities.md) | [`validatePostingAuthority`](/api/functions/index.validatePostingAuthority.html), [`validateAccountAuthority`](/api/functions/index.validateAccountAuthority.html) |
| Sign and broadcast | [Broadcast safely](../guides/broadcast-safely.md) | [`Client.broadcast`](/api/classes/index.Client.html#broadcast) |
## What to use this page for
Use this page as a bridge from concepts and recipes to exact API details.
Good reasons to open an API symbol page:
- checking the exact option names for a method;
- confirming return types;
- finding overloads;
- checking whether an API is deprecated;
- following source links while debugging;
- verifying exported types for TypeScript code.
## Keep concepts and API details separate
Concept pages explain how to think about Blurt and `dblurt`. Recipes show how to complete tasks. API symbol pages answer precise questions about a class, function, method or type.
When in doubt:
```text
Still learning the feature? Read Learn or Guides.
Trying to complete a task? Use Recipes.
Need exact signatures? Use API reference.
```
---
## Compatibility
Source: site/reference/compatibility.md
Canonical URL: https://dblurt.beblurt.com/reference/compatibility.html
Purpose: Runtime and browser support model.
# Compatibility
This page records compatibility policy for developers using `dblurt`.
## Runtime support
The package metadata is canonical for runtime requirements:
- `engines.node` defines the supported Node.js floor;
- `types` / `typings` define TypeScript declaration entrypoints;
- `browser` defines browser bundle substitutions;
- `browserslist` describes browser capability expectations.
Do not assume support for a runtime that is not represented by package metadata or validation.
## API compatibility
`dblurt` is pre-1.0, but public API compatibility still matters.
Current documentation policy:
- additive APIs should be introduced through concept/task docs when they change how developers think about the SDK;
- exact method and type details belong in the [API reference](./api.md);
- legacy supported APIs should remain visible;
- deprecated APIs should point to replacements;
- positional Nexus overloads remain compatibility surfaces unless a future release intentionally changes that policy;
- examples should prefer new and corrected forms.
## Generated artifacts
Some repository directories are build outputs and should not be edited by hand. This is mostly a maintainer concern, but it matters if you are contributing documentation or API changes.
| Artifact | Meaning |
| --- | --- |
| `docs/` | API reference output |
| `lib/` | compiled library output |
| `dist/` | browser bundle output |
| `site/.vitepress/dist/` | documentation site output |
Related references:
- [API reference](./api.md)
- [Deprecations](./deprecations.md)
- [Runtime and browser](../guides/runtime-and-browser.md)
---
## Deprecations
Source: site/reference/deprecations.md
Canonical URL: https://dblurt.beblurt.com/reference/deprecations.html
Purpose: Deprecated APIs and compatibility lifecycle guidance.
# Deprecations
This page explains deprecated and legacy-supported APIs in practical terms.
## Current deprecated public API
### `BroadcastAPI.accountWitnessProxy`
Status: deprecated but still callable as a compatibility surface.
Current Blurt Layer 1 source rejects witness proxies after hardfork 0.8 in `account_witness_proxy_evaluator`. New code should use direct witness voting through [`BroadcastAPI.accountWitnessVote`](/api/classes/index.BroadcastAPI.html#accountWitnessVote) instead.
The helper remains serializable so historical/testnet/compatibility callers see a protocol-shaped operation, but current mainnet applications should not present witness proxying as an available workflow.
### `BroadcastAPI.claimAccount` and `BroadcastAPI.createClaimedAccount`
Status: deprecated but still callable as compatibility surfaces.
Current Blurt Layer 1 source rejects `claim_account` and `create_claimed_account` after hardfork 0.2 in their evaluators. New code should use account-creation flows supported by current chain rules instead of claimed-account tickets.
The helpers remain serializable for compatibility, but current mainnet applications should not advertise them as supported account onboarding workflows.
### `Nexus.listPopComunities`
Status: deprecated but still supported.
Use the correctly spelled [`Nexus.listPopCommunities`](/api/classes/index.Nexus.html#listPopCommunities) instead.
The historical misspelling [`Nexus.listPopComunities`](/api/classes/index.Nexus.html#listPopComunities) remains available for backward compatibility. It should not be used in new code.
## Compatibility rule
Deprecated does not mean removed.
For `dblurt`, a deprecated API remains callable until there is a deliberate maintainer decision to remove it in a future compatibility-breaking release. New documentation and examples should use the replacement API.
## Overload guidance
Nexus methods with pagination or observer context may support both legacy positional signatures and newer option-object signatures.
New code should prefer option-object forms when available because they keep query state together:
```ts
await client.nexus.getRankedPosts({
sort: 'trending',
tag: 'blurt',
limit: 10,
observer: null
});
```
Existing positional signatures remain compatibility surfaces unless a future release intentionally changes that policy.
Related API details:
- [`Nexus`](/api/classes/index.Nexus.html)
- [`Nexus.getRankedPosts`](/api/classes/index.Nexus.html#getRankedPosts)
- [`Nexus.getAccountPosts`](/api/classes/index.Nexus.html#getAccountPosts)
- [`NexusRankedPostsQuery`](/api/interfaces/index.NexusRankedPostsQuery.html)
- [`NexusAccountPostsQuery`](/api/interfaces/index.NexusAccountPostsQuery.html)
---
## Errors
Source: site/reference/errors.md
Canonical URL: https://dblurt.beblurt.com/reference/errors.html
Purpose: Error taxonomy and retryability guidance.
# Errors
`dblurt` exposes typed error metadata so applications can respond to error categories and retryability without parsing human-readable messages.
## Error model
The important application-facing metadata is:
| Field | Meaning |
| --- | --- |
| `category` | Broad error family such as validation, transport, timeout or RPC application error. |
| `code` | Stable SDK code such as `DBLURT_TIMEOUT`. |
| `retryable` | Whether the error category appears transient. This is not permission to blindly repeat side-effectful operations. |
| `field` / `path` | Optional SDK validation location. |
| `rpc_code` / `rpc_data` | Optional JSON-RPC application error details. |
Exact API shape: [`DBlurtErrorMetadata`](/api/interfaces/index.DBlurtErrorMetadata.html).
## Main APIs
- [`DBlurtError`](/api/classes/index.DBlurtError.html)
- [`SerializationError`](/api/classes/index.SerializationError.html)
- [`ValidationError`](/api/classes/index.ValidationError.html)
- [`RpcApplicationError`](/api/classes/index.RpcApplicationError.html)
- [`classifyError`](/api/functions/index.classifyError.html)
- [`isDBlurtError`](/api/functions/index.isDBlurtError.html)
## Retry guidance
`retryable: true` means the failure appears transient. It does not mean every operation is safe to retry.
| Workflow | Retry posture |
| --- | --- |
| Blockchain query | bounded retry/backoff is usually reasonable. |
| Local operation builder | retry is usually irrelevant; fix the input. |
| Broadcast with ambiguous network result | inspect chain state before resubmitting. |
See [Handle retryable errors](../recipes/handle-retryable-errors.md) for a task-oriented example.
---
## Package exports
Source: site/reference/package-exports.md
Canonical URL: https://dblurt.beblurt.com/reference/package-exports.html
Purpose: Import and runtime compatibility details.
# Package exports
This page helps you find the main package-level APIs. It is a routing aid, not a complete export index.
## Primary import
Prefer TypeScript + ESM-style named imports in new documentation and new applications:
```ts
import { Client } from '@beblurt/dblurt';
```
CommonJS remains supported where compatibility requires it:
```js
const { Client } = require('@beblurt/dblurt');
```
## Runtime entrypoints
The package metadata defines:
| Field | Purpose |
| --- | --- |
| `main` | CommonJS/Node runtime entry. |
| `types` / `typings` | TypeScript declaration entry. |
| `browser` | Browser bundle substitutions. |
| `files` | Package contents published to npm. |
Use `package.json` as the canonical source for exact package metadata.
## Important exported families
| Family | Examples | API details |
| --- | --- | --- |
| Client | `Client`, `ClientOptions` | [`Client`](/api/classes/index.Client.html), [`ClientOptions`](/api/interfaces/index.ClientOptions.html) |
| Errors | `ValidationError`, `classifyError` | [Errors](./errors.md) |
| Content builders | `buildPostOperation`, `buildReplyOperation` | [`buildPostOperation`](/api/functions/index.buildPostOperation.html) |
| Social builders | follow/reblog/community custom JSON builders | [API reference](./api.md) |
| Authority validation | posting/account authority helpers | [`validatePostingAuthority`](/api/functions/index.validatePostingAuthority.html) |
| Read models | `client.read` / `ReadModels` | [`ReadModels`](/api/classes/index.ReadModels.html) |
For the complete export list, use the [API reference](./api.md).
---
## Executable examples catalog
Source: examples/README.md
Canonical URL: https://gitlab.com/beblurt/dblurt/-/blob/main/examples/README.md
Purpose: Repository examples with metadata and validation status.
# dblurt examples
Examples are first-class product assets for `@beblurt/dblurt`.
They are designed for humans and AI assistants:
- complete enough to copy;
- explicit about runtime and safety;
- linked from guides;
- validated where possible;
- blockchain query by default.
## Safety levels
| Level | Meaning |
| --- | --- |
| `blockchain-query` | Performs RPC reads only. No signing. No broadcast. |
| `static` | Does not perform network calls. |
| `manual` | Requires a browser or manual environment. |
Broadcast examples are intentionally not part of the initial example set.
## Validation levels
| Level | Meaning |
| --- | --- |
| `run` | Can be executed directly. |
| `compile` | Should compile but may not run as-is. |
| `manual` | Requires manual browser interaction. |
## Examples
| Example | Concept | Runtime | Safety | Validation | Required RPC | Expected output |
| --- | --- | --- | --- | --- | --- | --- |
| [`node/read-head-block.cjs`](./node/read-head-block.cjs) | current Layer 1 chain state | Node.js >=18 | blockchain-query | run | condenser_api | JSON containing `head`, `irreversible`, `time` |
| [`node/read-block-operations.cjs`](./node/read-block-operations.cjs) | Layer 1 block operation inspection | Node.js >=18 | blockchain-query | run | condenser_api | block number, operation count and first operation types |
| [`node/read-account.cjs`](./node/read-account.cjs) | Layer 1 account state | Node.js >=18 | blockchain-query | run | condenser_api | account name, balances and posting key count |
| [`node/read-post.cjs`](./node/read-post.cjs) | Nexus discovery + Layer 1 content read | Node.js >=18 | blockchain-query | run | bridge + condenser_api | post identity, title and body length |
| [`node/read-active-votes.cjs`](./node/read-active-votes.cjs) | active votes for a post | Node.js >=18 | blockchain-query | run | bridge + condenser_api | post identity and vote count |
| [`node/read-witness.cjs`](./node/read-witness.cjs) | witness information | Node.js >=18 | blockchain-query | run | condenser_api | witness owner, signing key, votes and URL |
| [`node/read-account-history.cjs`](./node/read-account-history.cjs) | account operation history | Node.js >=18 | blockchain-query | run | condenser_api | account name and small history summary |
| [`node/stream-block-numbers.cjs`](./node/stream-block-numbers.cjs) | bounded blockchain iteration | Node.js >=18 | blockchain-query | run | condenser_api | three irreversible block numbers |
| [`node/read-blocks-with-helper.cjs`](./node/read-blocks-with-helper.cjs) | bounded block parsing helper | Node.js >=18 | blockchain-query | run | condenser_api | returned irreversible block numbers |
| [`node/read-operations-with-helper.cjs`](./node/read-operations-with-helper.cjs) | bounded operation parsing helper | Node.js >=18 | blockchain-query | run | condenser_api | operation count and first operation types |
| [`node/read-nexus-ranked-posts.cjs`](./node/read-nexus-ranked-posts.cjs) | Nexus social/indexed query | Node.js >=18 | blockchain-query | run | bridge | ranked post identities |
| [`node/read-nexus-community.cjs`](./node/read-nexus-community.cjs) | Nexus community discovery | Node.js >=18 | blockchain-query | run | bridge | community name, title and subscriber count |
| [`node/read-account-summary.cjs`](./node/read-account-summary.cjs) | high-level account read model | Node.js >=18 | blockchain-query | run | condenser_api + bridge | account, wallet, reward and social summary fields |
| [`node/estimate-vote-value.cjs`](./node/estimate-vote-value.cjs) | vote-value read model | Node.js >=18 | blockchain-query | run | condenser_api | account, weight, mana and estimated BLURT vote value |
| [`node/build-post-operation.cjs`](./node/build-post-operation.cjs) | local content operation builder | Node.js >=18 | static | run | none | comment operation tuple fields |
| [`node/asset-and-price.cjs`](./node/asset-and-price.cjs) | local Asset and Price helpers | Node.js >=18 | static | run | none | formatted assets and converted value |
| [`node/classify-retryable-error.cjs`](./node/classify-retryable-error.cjs) | typed error taxonomy | Node.js >=18 | static | run | none | classified retryable timeout metadata |
| [`node/generic-call.cjs`](./node/generic-call.cjs) | unwrapped RPC call | Node.js >=18 | blockchain-query | run | database_api | API version data |
| [`typescript/read-account.ts`](./typescript/read-account.ts) | typed consumer compile path | TypeScript / Node.js >=18 | blockchain-query | compile | condenser_api when executed | account summary for a configured account |
| [`typescript/build-operations.ts`](./typescript/build-operations.ts) | typed local operation builders | TypeScript / Node.js >=18 | static | compile | none | operation tuple names when executed after compilation |
| [`browser/unpkg.html`](./browser/unpkg.html) | browser bundle read | Browser with fetch and AbortController | blockchain-query | manual | condenser_api | page text with current head block or an error |
## Running Node examples from the repository
Build first if needed:
```bash
npm run build
```
Then run selected examples:
```bash
node examples/node/read-head-block.cjs
node examples/node/read-block-operations.cjs
node examples/node/read-account.cjs
node examples/node/read-post.cjs
node examples/node/read-nexus-ranked-posts.cjs
node examples/node/read-nexus-community.cjs
node examples/node/read-account-summary.cjs
node examples/node/estimate-vote-value.cjs
node examples/node/stream-block-numbers.cjs
node examples/node/read-blocks-with-helper.cjs
node examples/node/read-operations-with-helper.cjs
node examples/node/build-post-operation.cjs
node examples/node/asset-and-price.cjs
node examples/node/classify-retryable-error.cjs
node examples/node/generic-call.cjs
```
The examples use a small loader so they work both:
- from this repository checkout; and
- after installing `@beblurt/dblurt` in a consumer project.
`examples/_load-dblurt.cjs` is an internal repository-validation helper. User-facing examples should still demonstrate the normal public package import style:
```js
const { Client } = require('@beblurt/dblurt');
```
Do not document `_load-dblurt.cjs` as an application pattern.
## TypeScript validation
`npm run docs:check` compiles the TypeScript example without emitting output. A direct local check can use:
```bash
npx tsc --noEmit --target ES2020 --module commonjs --moduleResolution node examples/typescript/read-account.ts
npx tsc --noEmit --target ES2020 --module commonjs --moduleResolution node examples/typescript/build-operations.ts
```
The example catalog above is intentionally checked against the files under `examples/` so new examples cannot be added without being listed.
## Source of truth
For conceptual explanations, read `../guide/`.
For AI generation rules, read `../ai/`.
For exact API signatures, use generated TypeDoc under `../docs/`.
## Future structure
If signing and broadcast examples are added later, keep the initial blockchain query examples clearly separated from higher-risk flows. A future layout may use:
```text
examples/
readonly/
signing/
broadcast/
```
Do not add broadcast examples until the safety rules, required authorities and validation mode are explicit.
---
## AI context overview
Source: ai/README.md
Canonical URL: https://gitlab.com/beblurt/dblurt/-/blob/main/ai/README.md
Purpose: How AI assistants should route to canonical docs.
# AI context for dblurt
This directory is a thin AI-specific context layer for assistants that generate, review or modify `@beblurt/dblurt` code.
It is not a second manual. Human explanations remain canonical in `guide/`. Reusable code remains canonical in `examples/`.
## Directory name decision
The directory is currently named `ai/` because it is short, discoverable, neutral across tools, and matches the user-facing purpose: AI assistant context. Alternatives were considered:
| Name | Advantage | Drawback |
| --- | --- | --- |
| `context/` | generic, broad | ambiguous; could mean runtime context or project context |
| `assistant/` | human-readable | less common; sounds like one tool/persona |
| `knowledge/` | durable framing | vague; may attract duplicated guide content |
| `skills/` | close to agent ecosystems | conflicts with generated `SKILL.md` concepts and Hermes-style skills |
| `ai/` | concise, discoverable, tool-neutral | slightly broad; requires rules to prevent becoming a second guide |
Recommendation: keep `ai/` for now. Reconsider only if a future tool requires a specific directory convention.
## Start here
| Need | Canonical source |
| --- | --- |
| Package overview | `../README.md` |
| First human learning path | `../guide/getting-started.md` |
| Domain vocabulary | `../guide/BLOCKCHAIN_MODEL.md` |
| API surface routing | `../guide/api-guide.md` |
| Layer 1 / Nexus details | `../guide/nexus.md` |
| Code generation constraints | `./coding-rules.md` |
| Common mistakes | `./pitfalls.md` |
| Security constraints | `./security-constraints.md` |
| Repository workflow | `../AGENTS.md` and `../guide/maintainer-workflows.md` |
| Reusable examples | `../examples/README.md` |
## Operational rules
- Identify the layer before selecting a helper: Blurt Layer 1, Nexus Layer 2 or local utility.
- Prefer existing examples over invented snippets.
- Keep human explanations in `../guide/`, executable examples in `../examples/`, and AI-only constraints in `../ai/`.
- Run `npm run docs:check` after documentation, example or AI-context changes when practical.
- If behavior is not proven by docs, source, tests or live validation, label it as unverified.
## AI context rules
- Link to canonical docs; do not copy them.
- Prefer `examples/` over invented snippets.
- Treat `guide/BLOCKCHAIN_MODEL.md` as the semantic vocabulary source.
- `../llms.txt` is the public AI-readable docs index; `../llms-full.txt` is assembled from canonical sources by `npm run docs:ai`.
- Do not edit generated directories such as `docs/`, `lib/`, `dist/`, `coverage/` or `public/`.
- Do not edit generated retrieval files by hand; update canonical docs or `scripts/generate-ai-docs.js`, then rerun `npm run docs:ai`.
---
## AI coding rules
Source: ai/coding-rules.md
Canonical URL: https://gitlab.com/beblurt/dblurt/-/blob/main/ai/coding-rules.md
Purpose: Durable coding constraints for assistants.
# AI coding constraints
Durable constraints for generating or reviewing `@beblurt/dblurt` code.
For human explanations, use `../guide/`. For exact API shape, use generated TypeDoc or source declarations. For domain terms, use `../guide/BLOCKCHAIN_MODEL.md`.
## Package and module constraints
- Package name: `@beblurt/dblurt`.
- Runtime contract is defined by `package.json` `engines.node`; see `../guide/runtime-compatibility.md`.
- Package shape is defined by `package.json` `main`, `types`/`typings`, and `browser` fields.
- Browser support uses the generated bundle and browser mapping; see `../guide/browser.md`.
- Do not claim native ESM packaging unless `package.json` changes to prove it.
## Canonical import patterns
Consumer CommonJS:
```js
const { Client } = require('@beblurt/dblurt');
```
Consumer ESM through Node.js CommonJS interop:
```js
import { Client } from '@beblurt/dblurt';
```
Repository-local examples may use a loader fallback so they run before the package is installed as `@beblurt/dblurt`.
## Layer constraints
- Blurt Layer 1 is chain truth.
- Nexus is Layer 2 indexed/social data.
- Do not present Nexus data as consensus data.
- Use `../guide/BLOCKCHAIN_MODEL.md` for terms such as block, transaction, operation, virtual operation, authority, witness, asset, memo, community and discussion.
## API surface routing
Use `../guide/api-guide.md` as the source of truth.
| Need | Use |
| --- | --- |
| Chain/account/content reads | `client.condenser` |
| Appbase database calls | `client.database` |
| Account history / operations | `client.accountHistory` |
| Block iteration helpers | `client.blockchain` |
| Nexus social/indexed views | `client.nexus` |
| Local calculations/serialization helpers | `client.tools` |
| Signing/broadcasting | `client.broadcast` with security review |
| Unwrapped RPC method | `client.call(api, method, params)` |
## Example constraints
- Prefer blockchain query examples first.
- Include complete imports and client construction.
- Use expected output shapes, not invented live chain values.
- Link to `../examples/README.md` when an example exists.
- Do not hard-code private keys or credentials.
- Do not add broadcast code unless the user explicitly asks for it and safety requirements are clear.
## Validation constraints
- Node examples should run when possible.
- TypeScript examples should compile when possible.
- If validation was not run, say so explicitly.
---
## AI pitfalls
Source: ai/pitfalls.md
Canonical URL: https://gitlab.com/beblurt/dblurt/-/blob/main/ai/pitfalls.md
Purpose: Common mistakes assistants should avoid.
# AI pitfalls
Common mistakes assistants must avoid when working with `@beblurt/dblurt`.
## Identity mistakes
- Do not call dblurt the official Blurt SDK.
- Do not confuse Blurt with Steem, Hive or other Graphene-family chains.
- Do not assume APIs from other SDKs exist in dblurt.
## Domain mistakes
- Do not confuse a transaction with an operation. A transaction contains one or more operations.
- Do not confuse virtual operations with user-signed operations. Virtual operations are emitted by chain processing.
- Do not present Nexus Layer 2 indexed/social data as Layer 1 consensus truth.
- Do not treat tags, communities and discussions as equivalent concepts.
Use `../guide/BLOCKCHAIN_MODEL.md` for domain vocabulary.
## Runtime mistakes
- Do not claim native ESM packaging unless package metadata changes.
- Do not assume React Native support unless validated and documented.
- Do not assume every browser is supported; use `../guide/runtime-compatibility.md` and `../guide/browser.md`.
## API hallucinations
- Do not invent helper methods.
- Check `../guide/api-guide.md`, generated TypeDoc under `../docs/`, or source declarations before naming a method.
- Use `client.call(api, method, params)` for unwrapped RPC methods instead of inventing wrappers.
## Repository mistakes
- Do not hand-edit `docs/`; it is generated by TypeDoc.
- Do not hand-edit `lib/`, `dist/` or `coverage/`.
- Do not hand-edit generated AI retrieval files such as `llms.txt` or `llms-full.txt`; update canonical docs or `scripts/generate-ai-docs.js`, then run `npm run docs:ai`.
## Example mistakes
- Prefer examples in `../examples/` over ad-hoc snippets.
- Do not include fake successful output for live RPC calls.
- Use output shapes or clearly labeled sample output.
---
## AI security constraints
Source: ai/security-constraints.md
Canonical URL: https://gitlab.com/beblurt/dblurt/-/blob/main/ai/security-constraints.md
Purpose: Key, authority, browser and broadcast safety constraints.
# AI security constraints
Security constraints for assistants generating or reviewing `@beblurt/dblurt` code.
Canonical human guides:
- `../guide/broadcast.md`
- `../guide/crypto.md`
- `../guide/browser.md`
- `../guide/security-guide.md`
- `../architecture/SECURITY_ARCHITECTURE.md`
## Private keys
Never hard-code private keys, memo keys, active keys, posting keys or owner keys.
Use environment variables or explicit placeholders:
```js
const postingKey = process.env.BLURT_POSTING_KEY;
if (!postingKey) {
throw new Error('Set BLURT_POSTING_KEY before signing');
}
```
## Authorities
- Posting authority is normally used for social actions such as votes/comments.
- Active authority is required for higher-risk actions such as transfers.
- Owner authority is highly sensitive and should not appear in normal examples.
- Memo keys are for memo encryption/decryption, not transaction authority.
Confirm exact authority requirements with `../guide/broadcast.md` or source/tests before generating action examples.
## Blockchain queries first
For learning flows, generate blockchain query examples first.
Broadcasting examples must be explicit about:
- required authority;
- environment variables;
- account names;
- irreversible side effects;
- validation performed or not performed.
## Browser safety
Browser applications must not silently embed private keys.
Prefer wallet/user-controlled flows or clearly marked secure input flows.
Warn about XSS and supply-chain risk when browser code signs transactions.
---
## Repository agent instructions
Source: AGENTS.md
Canonical URL: https://gitlab.com/beblurt/dblurt/-/blob/main/AGENTS.md
Purpose: Minimal coding-agent workflow rules.
# AGENTS.md
Minimal entry point for AI coding agents working in `@beblurt/dblurt`.
## Identity
`@beblurt/dblurt` is a JavaScript/TypeScript SDK for Blurt applications. It is not documented here as the official Blurt SDK.
## Repository map
| Path | Role |
| --- | --- |
| `README.md` | human landing page |
| `guide/` | canonical human documentation |
| `guide/BLOCKCHAIN_MODEL.md` | canonical domain vocabulary |
| `ai/` | thin AI context and constraints |
| `examples/` | executable/readable product examples |
| `architecture/` | reference vision and durable decisions |
| `docs/` | generated TypeDoc output; do not hand-edit |
| `lib/`, `dist/`, `coverage/` | generated build/test output; do not hand-edit |
## Basic commands
```bash
npm run typecheck
npm run lint
npm test
npm run docs:check
npm run docs
```
If live public RPC endpoints are unavailable, run the documentation check without live examples:
```bash
DBLURT_DOCS_CHECK_SKIP_LIVE_EXAMPLES=1 npm run docs:check
```
## Rules
- Preserve runtime behavior, public APIs and package semantics unless explicitly asked.
- Do not edit generated output by hand.
- Do not hard-code private keys or credentials.
- Do not commit, push, tag, publish, release or change deployment/CI without explicit authorization.
- If a validation command fails, report the exact failure instead of inventing successful output.
Read `guide/maintainer-workflows.md`, `ai/README.md` and `guide/BLOCKCHAIN_MODEL.md` for details.
---
## Security policy
Source: SECURITY.md
Canonical URL: https://gitlab.com/beblurt/dblurt/-/blob/main/SECURITY.md
Purpose: Responsible disclosure and maintainer security expectations.
# Security policy
This project handles blockchain signing, transaction construction and memo helpers. Please report suspected security issues responsibly.
## Supported version
Security review targets the active `main` branch and the latest published npm version when applicable. Do not hand-maintain a version number here; the repository version is defined by `package.json` and the published version is defined by the npm registry.
## What to report
Please report issues such as:
- private-key exposure or unsafe key handling in SDK code;
- transaction serialization or signing errors;
- asset amount precision or rounding errors that affect signed transactions;
- memo encryption/decryption vulnerabilities beyond known legacy-format limitations;
- JSON-RPC response handling issues that can mislead applications;
- package distribution, build artifact or dependency supply-chain risks;
- browser bundle issues that materially affect key safety.
Do not include real private keys, seed phrases or account secrets in reports.
## Known architectural limitations
Some risks are protocol or application-boundary limitations rather than direct SDK bugs. They are still important, but they may require documentation, application controls or future protocol-compatible designs rather than immediate SDK changes.
Known categories include:
- public RPC endpoints are untrusted unless the application chooses and secures them;
- Nexus Layer 2 data is indexed/query data, not Layer 1 consensus truth;
- browser signing is high risk without wallet/user-controlled signing flows;
- legacy encrypted memo format should not be treated as modern authenticated encryption;
- password-derived keys from legacy login semantics are not a modern password KDF.
See [`architecture/SECURITY_ARCHITECTURE.md`](./architecture/SECURITY_ARCHITECTURE.md) for the project security architecture.
## Reporting channel
If the hosting platform provides a private security advisory or confidential issue workflow for this repository, use that first.
If no private workflow is available, contact the maintainers through the repository's normal project channels and request a private security contact before sharing exploit details.
Do not open a public issue containing exploit details, live private keys or instructions that could immediately harm users.
## Maintainer handling expectations
Maintainers should:
1. acknowledge receipt when possible;
2. classify whether the report is an implementation bug, architectural weakness, accepted protocol limitation, application concern or operational recommendation;
3. reproduce with tests or a minimal proof where safe;
4. decide whether a fix, documentation update, release advisory or no-code clarification is appropriate;
5. avoid publishing exploit details until users have a reasonable mitigation path.
## Release guidance
Before publishing a security-sensitive release, maintainers should run the side-effect-free release preflight:
```bash
npm run release:check
```
For npm publication, also perform dependency/security audit and package-content review in an environment where audit tooling is available. `release:check` includes runtime CSP scanning and a packed-package consumer smoke test, but it does not replace maintainer review of generated artifacts or release provenance.