KBRD Envelopes & BIP340 Signatures on Kaspa Boards

How do you store and verify structured data like a social media post on a UTXO blockchain like Kaspa? The protocol itself supports attaching an arbitrary byte array to every transaction—the payload field. But raw bytes are meaningless without structure and proof of authorship.

Kaspa Forge's Boards solve this by defining a precise encoding format called the KBRD envelope and securing it with a BIP340 Schnorr signature. This combination creates an immutable, verifiable, and parseable on-chain post. It's a fundamental piece of the Kaspa on-chain data protocol stack we use.

The Problem: Structured Data on a UTXO Chain

A Kaspa transaction is a collection of inputs (UTXOs being spent) and outputs (new UTXOs being created). Optionally, it can carry a payload—up to 1 KB of arbitrary data. This payload is often used for messages, but without a standard, it's just a blob of bytes. To build a reliable system like a public board, we need three guarantees: 1. Structure: A way to parse different fields (text, author key, flags) from the payload bytes. 2. Authenticity: Cryptographic proof that the data was submitted by the owner of a specific key. 3. Integrity: Proof that the data wasn't altered in transit.

The KBRD envelope and BIP340 signature provide exactly these guarantees directly at the transaction level.

How the Mechanism Works: KBRD Envelope Anatomy

Think of a KBRD envelope as a standardized shipping container for your post. It has a fixed header that tells the indexer how to unpack the contents. The format has evolved (v1 and v2), but the core principles are the same.

A simplified, conceptual view of a KBRD v2 envelope prefix (the part that gets signed) looks like this:

[0x01, 0x02] // KBRD magic bytes + version (e.g., 0x02 for v2)
[32 bytes]   // Ephemeral Public Key (authorship key, compressed, x-only)
[16 bytes]   // Recovery Nonce (for seed-based key derivation in v2)
[1 byte]     // Flags (bitfield: e.g., `has_image`, `is_reply`)
[2 bytes]    // Board Slug Length (n)
[n bytes]    // Board Slug (UTF-8, e.g., "/tech/")
[2 bytes]    // Text Length (m)
[m bytes]    // Post Text (UTF-8)
[32 bytes]   // Image SHA-256 Hash (optional, present if `has_image` flag set)
[32 bytes]   // Reply-To Transaction ID (optional, present if `is_reply` flag set)

This prefix defines the data. The ephemeral_pk is a one-time public key generated for the post. It's not linked to your main wallet key, providing a layer of pseudonymity. The recovery_nonce in v2 allows you to later derive the corresponding private key deterministically from your seed, enabling tip collection without storing random keys.

Signing with BIP340

The signature doesn't cover the *entire* envelope prefix. Instead, the process is: 1. Compute message_hash = SHA-256(KBRD_prefix_bytes). 2. Sign this 32-byte hash using the BIP340 Schnorr signature scheme with the private key corresponding to the ephemeral_pk.

// Conceptual signing step (Rust-like pseudo-code)
let prefix_bytes = serialize(kbrd_prefix); // The structured bytes above
let message_hash = sha256(&prefix_bytes);
let signature = secp256k1_schnorr_sign(message_hash, author_sk); // author_sk for ephemeral_pk

The final transaction payload is simply the concatenation of the KBRD prefix and the 64-byte BIP340 signature.

Verification: Permissionless and Deterministic

This is the key strength of the on-chain data protocol. Anyone can take a Kaspa transaction from the BlockDAG, extract its payload, and verify it: 1. Parse the last 64 bytes as the signature. 2. The preceding bytes form the prefix. 3. Compute message_hash = SHA-256(prefix). 4. Parse the ephemeral_pk from the start of the prefix (bytes 2-33). 5. Verify signature against message_hash and ephemeral_pk.

If verification passes, the data in the prefix is guaranteed to be exactly as the author intended, and it's permanently committed to the blockchain.

How Kaspa Forge Uses It: The Full Pipeline

The KBRD envelope isn't an abstract spec; it's the live backbone of our Boards product.

1. Sealing a Post in Desk: When you write a post in the Kaspa Forge Desk, the local WASM code constructs the KBRD v2 prefix with your message, chosen board slug, and a fresh ephemeral_pk. It then deterministically BIP340-signs the prefix hash with the corresponding author_sk (derived from your profile seed). The Desk wallet then builds a standard Kaspa transaction, funds it with your existing UTXOs, attaches the sealed KBRD payload, and broadcasts it.

2. Indexing the Chain: Our indexer (board-indexer) continuously polls Kaspa nodes via gRPC for new blocks. For each transaction, it checks the payload for the KBRD magic bytes. If found, it performs the BIP340 verification described above. Only *verified* posts are considered for indexing. The indexer then applies its policy layer: it deterministically ranks posts by (daa_score, txid) using the block's Difficulty Adjustment Algorithm score, resolves reply trees, parks early replies to pending parents, and stores the clean data in a local database. This is where the separation is clear: the immutable transaction data is the source of truth; the indexed view is a derived, rebuildable projection.

3. Serving and Moderation: The web application reads from the indexer's database. Moderation actions—like hiding a post for NSFW content—only affect this read projection. The signed KBRD envelope in the BlockDAG remains untouched. A viewer can independently verify the post's existence and content by fetching the transaction from any archival node.

4. Tips and Claim Keys: The ephemeral_pk inside the KBRD envelope serves as a valid Kaspa P2PK address. Tips are sent directly to this address. To collect them, the Desk uses the deterministic derivation path ("board/anon/<recovery_nonce>") to rebuild the author_sk from the seed, proving ownership and sweeping the funds into the user's main wallet—a process that relies entirely on the on-chain commitment.

Trade-offs and Current Boundaries

This system is powerful, but it comes with trade-offs and inherent limitations.

• Data vs. Policy: The core trade-off is clear. On-chain data (the KBRD envelope + signature) is immutable, permanent, and verifiable by anyone. The indexer's view is mutable and policy-dependent. A post removed from the Kaspa Forge boards view still exists, verifiably signed, in the BlockDAG. This is by design.
• Payload Size: Kaspa's transaction payload limit (typically 1 KB) constrains the size of text and data. Images are not stored on-chain; their SHA-256 hashes are, linking to off-chain storage.
• Replay Protection & Identity: An envelope signature binds the data to the ephemeral_pk, not to a specific transaction. The indexer implements an envelope-replay guard (env_hash) to prevent the same signed envelope from being rebroadcast in a new transaction to impersonate or bump a thread.
• DAA Score Non-Determinism: A transaction can appear in multiple parallel DAG blocks with different daa_scores, affecting its sort order. The indexer resolves this by taking the *minimum* observed daa_score for a given txid, converging the live view with a from-scratch rebuild. Deep reorgs could, in theory, cause minor ordering hiccups, but these are bounded by Kaspa's rapid block rate and GHOSTDAG security.
• Indexer as a Necessary Lens: Without an indexer, the raw on-chain data is a firehose of unsorted, disconnected transactions. The indexer's job—verification, ordering, threading—is what makes Boards usable. This means the user experience is tied to the reliability and honesty of the indexer operator (Kaspa Forge in this case), though the raw data remains independently auditable.

This architecture ensures that Kaspa Boards are built on a foundation of verifiable on-chain truth. The KBRD envelope provides the structure, and BIP340 provides the cryptographic seal, creating a robust standard for data on the Kaspa BlockDAG.