Question answered by this guide: what domain vocabulary should humans and AI assistants use when reasoning about Blurt, dblurt and Nexus?
This is the canonical semantic reference for @beblurt/dblurt documentation. It defines concepts, boundaries and terminology. It is not an API reference and it is not a protocol specification.
For helper selection, see API guide. For Nexus API behavior, see Nexus Layer 2. For exact TypeScript signatures, use the generated TypeDoc reference under docs/.
Blurt Layer 1 is the source of chain truth.
Nexus Layer 2 indexes, enriches and exposes social/query views derived from Layer 1 data and additional indexing logic. Nexus must not be described as changing Layer 1 meaning.
Use this rule whenever documentation or examples compare Layer 1 and Nexus:
Layer 1 records canonical chain events and state.
Nexus indexes and presents application-friendly views over chain/social data.
Layer 1 is the Blurt blockchain consensus layer.
It is responsible for:
In dblurt, Layer 1 data is primarily accessed through:
client.condenser;client.database;client.accountHistory;client.blockchain;client.broadcast for signed actions;client.call for unwrapped RPC methods.A block is an ordered unit of Layer 1 chain history.
A block typically contains:
Documentation should not invent block fields. Use generated TypeDoc, source declarations, tests or Layer 1 RPC responses for exact shapes.
For developer documentation, distinguish these states:
| Concept | Meaning | Documentation rule |
|---|---|---|
| Head block | Latest block known by an RPC node | Useful for live reads, but may still be reversible. |
| Reversible block | Recent block that may still be affected by fork resolution | Avoid presenting as final when correctness matters. |
| Last irreversible block | Block considered irreversible by consensus | Prefer this for workflows that need stable history. |
RPC nodes may expose both head and last irreversible block numbers in dynamic global properties.
When examples only demonstrate live reads, it is acceptable to print both head and irreversible heights. When examples imply finality, they must explain which height is used.
A transaction is a signed Layer 1 payload containing one or more operations.
A transaction is not the same as an operation.
Important properties:
Use “transaction” when discussing the signed payload submitted to the chain. Use “operation” when discussing the individual action inside that payload.
A signature proves that the transaction was authorized by a key satisfying the required authority for its operations.
Documentation rules:
An operation is a single Layer 1 action inside a transaction.
Examples include social actions, transfers, account updates, witness votes and custom JSON operations.
Operations are the correct level for explaining “what action is being performed”. Transactions are the correct level for explaining “what signed payload was submitted”.
Operations have two ordering contexts:
Do not imply that independently broadcast transactions preserve application-level ordering unless that behavior is proven by chain inclusion data.
When documenting account history or block operation helpers, be explicit about whether ordering is:
A virtual operation is emitted by Layer 1 processing rather than directly signed by a user as a normal operation.
Use virtual operations for explaining protocol-generated effects such as rewards or derived history entries.
Do not describe virtual operations as user-submitted transactions.
Virtual operations may appear in account history or operation history APIs. They are still Layer 1-derived history, but their origin is protocol processing rather than a signed operation payload.
An account is a Layer 1 identity and state container.
An account may have:
Account data from Layer 1 and profile/community data from Nexus should be distinguished.
Authority defines which keys/accounts can authorize actions.
Common authority categories:
Documentation and examples must not hard-code private keys.
When writing examples, name the required authority explicitly. If the authority requirement is not verified, say so instead of guessing.
A witness is a Layer 1 block producer / governance participant.
Witness-related data belongs to Layer 1. Use witness APIs and Layer 1 helper surfaces when documenting witness queries or votes.
Witness concepts include:
Do not present witness data as a Nexus concept.
A node is a server exposing Blurt RPC APIs.
An RPC endpoint is the URL used by Client to reach a node.
Documentation rules:
An asset is an amount with a symbol and precision.
Examples in Blurt contexts may include liquid balances and vesting-related assets. Do not treat asset strings as plain numbers without preserving symbol/precision semantics.
Rewards are protocol-derived economic effects.
They may appear in account balances, reward funds, payout statistics, or virtual operations depending on the API surface.
When exact chain truth matters, prefer Layer 1 data. Nexus may expose indexed or aggregated views that are useful for social applications but should not be described as consensus state.
Blurt-family APIs and helper names may refer to bandwidth, resource usage, mana or related chain economics depending on the feature.
Documentation rule:
A memo is message data associated with supported transfer-style operations.
Encrypted memos use memo keys. Memo keys are not active/posting transaction authority.
Security rules:
Nexus is Layer 2 indexing/social infrastructure for Blurt applications.
In dblurt, Nexus is accessed through client.nexus and Bridge-style API calls.
Nexus may expose:
Nexus should be described as indexed/query data, not consensus truth.
Bridge is the API namespace/protocol style used by Nexus-style social endpoints.
In dblurt docs, Bridge and Nexus are often related:
Use client.nexus for wrapped Bridge/Nexus helper methods.
A community is a Nexus/Bridge social grouping concept.
Communities are useful for application-level discovery and organization. Do not treat community metadata as Layer 1 consensus metadata unless a specific Layer 1 operation/record proves that relationship.
A tag is a content classification/discovery label.
Tags can appear in discussion queries and social indexing flows. Tags are not equivalent to communities.
A discussion is a social/content view around posts and replies.
Layer 1 can expose content/discussion-style data through condenser-compatible APIs. Nexus can expose enriched or ranked social views.
When documenting discussions, specify whether the data comes from Layer 1 helpers such as client.condenser or Nexus helpers such as client.nexus.
Examples:
| Developer need | Prefer | Why |
|---|---|---|
| Exact account state | Layer 1 | consensus data |
| Latest block number | Layer 1 | consensus chain state |
| Irreversible history | Layer 1 | stable chain state |
| Broadcast vote/comment/transfer | Layer 1 | signed transaction path |
| Ranked posts | Nexus | indexed/social ranking |
| Community context | Nexus | application/social view |
| Notifications | Nexus | indexed user-facing view |
AI assistants should load this guide before generating explanations involving blockchain semantics.
If a term is not defined here, assistants should: