BitStory Protocol (BS)

BitStory is a minimal, fully on-chain messaging protocol for Bitcoin.

• All messages are UTF-8 JSON objects stored entirely on-chain (typically in OP_RETURN outputs).
• No hash-only anchors, no sidechains, no external canonical storage.
• Identity is derived from recoverable secp256k1 signatures.
• Three message types:
  • PO — post (human-readable message)
  • PF — profile (author metadata)
  • PG — page (long-form canonical content)

This repository contains:

• The BitStory whitepaper
• The JSON wire format specification
• An HTTP API specification for indexers (e.g. bitstory.org)
• Example BitStory messages as JSON
• Reference clients (Python, JS)

---

Quick JSON Overview

Every BitStory message is a compact JSON object with at least:

• p — protocol identifier, always "BS"
• t — type, one of "PO", "PF", "PG"
• a — author handle (UTF-8)
• s — recoverable ECDSA signature (130 hex chars)

Example PO post (pretty-printed for readability):

{
  "p": "BS",
  "t": "PO",
  "a": "satoshi",
  "c": "Hello, Bitcoin!",
  "s": "00abc123def456...130chars"
}

Example PG page:

{
  "p": "BS",
  "t": "PG",
  "a": "mf",
  "ti": "Bitstory Manifesto",
  "c": "Full UTF-8 content…",
  "s": "..."
}

Example PF profile:

{
  "p": "BS",
  "t": "PF",
  "a": "mf",
  "b": "Writing Bitcoin history.",
  "s": "..."
}

On-chain, these objects are typically minified (no spaces or newlines) to save bytes.

---

Versioning (PROFILE and PAGE)

BitStory supports simple on-chain versioning for profiles and pages:

• PF (profile): one public key has one active profile at any point in time. The latest PF message on-chain (by block height) is considered canonical for that key; previous profiles remain part of the historical record and can be exposed as history.
• PG (page): pages are identified by (pubkey, title). A single key can publish multiple pages with different titles. To update a page, publish a new PG with the same title and the same signing key; the latest version becomes canonical, older versions remain accessible as history.

Indexers are expected to group PF messages by recovered pubkey, and PG messages by (pubkey, ti) to reconstruct both the current state and full version history.

---

Specifications

• JSON format: spec/json-format.md
• HTTP API (for indexers): spec/api.md
• Whitepaper: whitepaper/BitStory_Whitepaper_V1.0.pdf (or latest)

---

Reference Clients

• Python reference client: client/python/bitstory_client.py
• JavaScript reference client: client/js/bitstory_client.mjs

These clients:

• build PO, PF, and PG messages with the correct schema,
• canonicalize JSON (sorted keys, no whitespace, s excluded),
• sign messages with a recoverable secp256k1 signature,
• verify messages and recover the compressed public key.

They do not handle UTXOs, wallets or transaction building; they are focused on format + crypto only.

---

Contributing, Issues & PRs

Contributions are welcome.

If you:

• find inconsistencies in the spec,
• want to propose additional fields,
• have concerns about versioning or indexing,
• or want to add reference implementations in other languages,

please open an Issue describing the problem or suggestion as clearly as possible, ideally referencing the relevant sections of the spec.

For code or spec changes:

1. Fork the repository.
2. Create a branch for your change.
3. Update or add tests / examples if applicable.
4. Open a Pull Request with a clear description and rationale.

The goal of BitStory is to remain minimal and stable. Changes that add unnecessary complexity or ambiguity are likely to be rejected; changes that clarify the protocol or improve interoperability are encouraged.

---

License

Unless otherwise specified, this project is released under the MIT License.
See LICENSE for details.