From ac76b72366df18d6f5a75c2767643e359886436c Mon Sep 17 00:00:00 2001 From: Luke Rohenaz Date: Fri, 4 Sep 2026 17:09:44 -0400 Subject: [PATCH] =?UTF-8?q?docs:=20propose=20BRC-179=20Bitcom=20=E2=80=94?= =?UTF-8?q?=20Universal=20Bitcoin=20Computer:=20Decentralized=20Protocol?= =?UTF-8?q?=20Registry=20and=20Composition?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 1 + SUMMARY.md | 1 + scripts/0179.md | 267 ++++++++++++++++++++++++++++++++++++++++++++++ scripts/README.md | 1 + 4 files changed, 270 insertions(+) create mode 100644 scripts/0179.md diff --git a/README.md b/README.md index 100a9bbf..4ade6e51 100644 --- a/README.md +++ b/README.md @@ -238,6 +238,7 @@ BRC | Standard 174 | [Consensus-Unique Name Tokens — Identity Binding and Verified Resolution](./tokens/0174.md) 176 | [BSV-21 — Validity Proofs](./tokens/0176.md) 177 | [Wallet-Enforced Expiry for `noSend` Actions](./wallet/0177.md) +179 | [Bitcom — Universal Bitcoin Computer: Decentralized Protocol Registry and Composition](./scripts/0179.md) 190 | [Access Gates for Metanet Rooms](./apps/0190.md) 210 | [Derived Collectibles](./apps/0210.md) 218 | [Chat-Native Command Grammar for the Metanet](./apps/0218.md) diff --git a/SUMMARY.md b/SUMMARY.md index 11501cf9..4a7f9f88 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -108,6 +108,7 @@ * [Pay to Push Drop](./scripts/0048.md) * [Bitcoin Script ASM Format](./scripts/0106.md) * [Bitcoin Script to and from Bitcoin BASIC — a compiler and a decompiler](./scripts/0173.md) +* [Bitcom — Universal Bitcoin Computer: Decentralized Protocol Registry and Composition](./scripts/0179.md) ## Tokens diff --git a/scripts/0179.md b/scripts/0179.md new file mode 100644 index 00000000..dbd342cf --- /dev/null +++ b/scripts/0179.md @@ -0,0 +1,267 @@ +# BRC-179: Bitcom — Universal Bitcoin Computer: Decentralized Protocol Registry and Composition + +Open Protocol Labs (info@opl.dev) + +**Original protocol author:** [_unwriter](https://github.com/unwriter) + +**BRC editor:** Luke Rohenaz (luke@opl.dev) + +**Contributors:** Gal Buki (torusJKL) — "$" admin mode ("Bitcom as OS"); Rangel Wulff — extensible protocol / pipeline inspiration; Steve Shadders — transformation and markup protocol ideas; Kurt Wuckert Jr. (kurt@opl.dev), David Case (dcase@opl.dev), Michael Boyd (root@opl.dev), Dan Wagner (dan@opl.dev) + +## Status and Scope + +This is a draft codification of an existing protocol, not a new wire format. Original protocol attribution is distinguished from BRC editorial attribution; contributor acknowledgments do not imply endorsement of this transcription. Existing identifiers and payloads remain unchanged. Clarifications describe the scope of the documented profile; incompatible extensions require a separate proposal. + +## Abstract + +Bitcom is a set of conventions, introduced by _unwriter in early 2019, for creating, identifying, administering, and composing application-layer OP_RETURN protocols on Bitcoin SV without any central registry. A protocol is identified by an ordinary Bitcoin P2PKH address generated by its creator; the address serves as a collision-resistant namespace prefix, and control of the corresponding private key authorizes namespace administration. Bitcom additionally defines an admin command convention (a `$` push datum, authenticated by spending from the account's own address) for registering accounts and publishing protocol metadata on-chain, a pipeline convention (push data `|`) for composing multiple protocols within a single OP_RETURN output, and an on-chain schema publication scheme so that protocol semantics are machine-readable. + +Address prefixes and pipeline composition are used by B, MAP, AIP, and BAP. Sections 1, 2, and 4 document those conventions. Sections 3, 5, and 6 preserve historical administration, schema, and routing designs for context; they do not establish a complete interoperable registry or resolver profile, and implementing them is not a prerequisite for using a prefix or pipeline. + +## Motivation + +Before Bitcom, OP_RETURN protocols identified themselves with short arbitrary "magic" prefixes (for example, Memo's `0x6d01`-style two-byte codes). Arbitrary prefixes have two problems: + +1. **Collision.** Nothing prevents two protocols from choosing the same prefix, and short prefixes make accidental collision likely as the number of protocols grows. +2. **Central registration.** Avoiding collisions otherwise requires a curated registry — a central point of failure and human politics, at odds with a permissionless network that must support an unbounded number of protocols. + +Central registries were in fact attempted — for example the Bitcoin Cash protocol repository, a CSV file on GitHub to which developers submitted 4-byte prefixes. The original documentation identifies four problems with that model: a high barrier to creating protocols, a manual process that cannot be automated (protocols could not programmatically create protocols), centralization and its politics, and no fundamental fix (nothing stops collisions with unlisted or defiant prefixes). + +Bitcom solves both problems by deriving the namespace from Bitcoin itself: generating a fresh keypair yields an address whose accidental collision probability is negligible under the cryptographic assumptions used for address generation, and whose private key doubles as an ownership credential for administering the protocol. Registration is self-service — announcing the address on-chain from the address itself — and administration happens purely through ordinary transactions. As the original documentation puts it: "Nobody owns Bitcom. It's just an open convention you can use to build your application protocols." + +Larger data-carrier allowances made the overhead of address identifiers easier to accommodate. The on-chain identifier is the Base58Check text, typically 34 bytes, not its 25-byte decoded representation. A longer prefix still has a byte and fee cost; it does not prevent deliberate reuse of another protocol's identifier. + +The composition and schema conventions extend the same philosophy — drawn explicitly from the Unix design tradition — to protocol interoperability: each protocol stays minimal and single-purpose, protocols are composed through a pipeline rather than by growing monolithic specifications, and each protocol's push-data semantics can be published on-chain in machine-readable form. + +## Specification + +The key words "MUST", "SHOULD", and "MAY" in this document are to be interpreted as described in RFC 2119. + +### 1. Protocol Identifier + +A Bitcom protocol is identified by a Bitcoin P2PKH address, encoded in Base58Check, generated by the protocol's creator. + +- The creator generates an ordinary keypair. The resulting address is the protocol's identifier and namespace prefix. No third party is involved; the account is announced on-chain with `$ useradd` (Section 3.2). +- Uniqueness follows from the collision resistance of address generation; no central allocation is needed. +- The holder of the corresponding private key is the protocol's **admin**. Administrative actions (Section 3) are authenticated by demonstrating control of this key. +- In the Unix filesystem metaphor, each account is a root folder named by its address, and the account's metadata files (Section 3.3) live inside it. + +For example, the B protocol is identified by the address `19HxigV4QyBv3tHpQVcUEQyq1pzZVdoAut`. + +#### 1.1 String Identifiers in Practice (Informative) + +Several deployed protocols adopt Bitcom's data format (Section 2) and pipeline composition (Section 4) while using a plain human-readable UTF-8 string as the protocol identifier instead of an address. The original RUN token protocol used the string `run`; the Sigma signing protocol uses the string `SIGMA`. Consumers identify these protocols by exact string match. + +Such protocols deliberately forfeit what the address-as-prefix rule provides: there is no collision resistance beyond the string's distinctiveness, and — with no underlying keypair — no provable ownership, no authenticated `$` administration, and no route enablement. They nonetheless compose cleanly in pipelines alongside address-identified protocols, and indexers built on the positional push-data model handle both identically. + +### 2. Protocol Data Format + +A transaction output invoking a Bitcom-style protocol is a data-carrier output in which the first push datum after `OP_RETURN` is the protocol's address, encoded as a UTF-8 string: + +``` +OP_RETURN + + + + ... +``` + +All push data following the protocol address are defined by that protocol's own specification. Bitcom itself imposes no structure on them beyond the conventions in Sections 3–5. + +**Note on OP_FALSE OP_RETURN:** Bitcom predates the Genesis upgrade. Original Bitcom-era transactions used a bare `OP_RETURN`. Post-Genesis transactions use the `OP_FALSE OP_RETURN` false-return template ([BRC-18](./0018.md)); the Bitcom conventions apply identically, with the protocol address as the first push datum after `OP_RETURN`. Indexers supporting historical data SHOULD recognize both forms. + +### 3. Admin Commands (Historical, Informative) + +Bitcom defines administrative commands for registering an account and publishing metadata into its namespace. An admin transaction is a data-carrier output whose **first push datum is `$`** (a single UTF-8 dollar sign), followed by a command and its arguments: + +``` +OP_RETURN + $ + + +``` + +#### 3.1 Identification and Authentication + +The account an admin command acts upon is identified by the transaction's **funding input**: admin transactions are sent from the protocol address itself, and verifiers and indexers attribute a `$` command to the address of the spending input (in BitDB query terms, `in.e.a`). Because only the private key holder can spend from the address, this simultaneously authenticates the action. Transactions matching the `$` syntax whose inputs do not spend from the claimed account MUST NOT be treated as administrative actions of that account — as the original documentation notes, anyone can push a random address into an OP_RETURN, but "we can just check the sender info to see that the sending address matches." + +#### 3.2 `useradd` — Register an Account + +Generating a keypair creates a potential namespace, but the account exists on the network only once it is announced on-chain: + +``` +OP_RETURN $ useradd
+``` + +where `
` is the account's own address (the transaction is funded from that same address, per Section 3.1). Once confirmed, the sender provably owns that address space. + +#### 3.3 `echo` — Write a Metadata File + +Writes content to a named virtual file in the account's root (note the Unix `>` redirection is spelled `to`): + +``` +OP_RETURN $ echo to +``` + +Conventional filenames include `description` (a human-readable protocol description) and `schema.json` (Section 5). The design intends later writes to replace the indexed value. It does not specify a complete ordering, conflict, or reorganization policy. + +#### 3.4 `cat` — Assign On-Chain Content to a File + +Assigns previously published on-chain content, referenced by a `bit://` URI (Section 6), to a filename in the account's root: + +``` +OP_RETURN $ cat bit:/// to +``` + +This allows large documents (for example a README stored via the B protocol) to be attached to a protocol by reference rather than inline. The import is logical, not physical; retrieval is performed by indexers. + +#### 3.5 `route` — Decentralized Endpoint Routing + +The `route` commands connect on-chain protocol identifiers to off-chain service endpoints, enabling `bit://` URI resolution (Section 6). + +**`route enable`** — performed by the protocol admin only. Opens a route pattern for service providers to implement: + +``` +OP_RETURN $ route enable +``` + +**`route add`** — performed by any service provider. Advertises an endpoint implementing an enabled route: + +``` +OP_RETURN $ route add +``` + +Example: + +``` +OP_RETURN $ route add 19HxigV4QyBv3tHpQVcUEQyq1pzZVdoAut /:tx https://media.bitcoinfiles.org/{{tx}} +``` + +Providers SHOULD use a separate service account for `route add` rather than the protocol admin account; the admin account should only enable routes. + +Route matchers follow the pattern language of route-parser: `:name` captures a parameter up to `/`, `?`, or end of string; `*name` captures a splat up to `?` or end of string; `(...)` denotes an optional group (which may nest); anything else is a literal. The endpoint template instantiates captured variables into a static URI. Both `{{tx}}`-style and `${tx}`-style template variables appear in the original documentation (the website and the 0.1.0 release notes respectively); resolvers processing historical transactions should be aware both spellings exist on-chain. + +A provider's claimed affiliation with a protocol is not proven by `route add` alone; consumers MAY require additional verification schemes (such as the Bitcoin Sticker Protocol) before trusting an advertised endpoint. + +#### 3.6 Embedded Admin Mode ("Bitcom as OS") + +A later design iteration, proposed by torusJKL and adopted in the Bitcoin Script Schema proposal, embeds the admin layer *inside* a protocol's own prefix namespace rather than treating Bitcom as a standalone protocol — "an OS that gets installed into protocols." In this form the protocol address precedes the `$`: + +``` +OP_RETURN + + $ + + +``` + +Authentication is unchanged: the transaction is funded from the protocol address (Section 3.1), with the output additionally carrying the address as its first push datum. Schema publication (Section 5) is specified in this embedded form. Indexers supporting Bitcom SHOULD recognize both the plain form (`$` first, Sections 3.2–3.5) and the embedded form (address first). + +#### 3.7 Client-Side Commands + +The original Bitcom CLI and its successor shell bitsh also implemented purely local commands (`init` for keypair generation into a `.bit` file, `whoami`, `ls`, `history`). These manage client-side state and produce no on-chain footprint; they are informative only. + +### 4. Pipeline Composition + +Multiple protocols MAY be composed within a single OP_RETURN output using the push datum `|` (a single UTF-8 pipe character) as a separator: + +``` +OP_RETURN + + | + + | + +``` + +Semantics, following the Unix pipeline: + +1. Each segment begins with a protocol address and is interpreted by that protocol's specification. +2. Order is significant. A particular composition may define how one segment relates to the next. Bitcom supplies no universal object model, execution engine, or canonical ordering for arbitrary combinations. +3. Segments are recorded together in one output. This establishes co-location, not authentication, signature coverage, authorization, or finality; each companion protocol and application supplies those rules. +4. The original design places a producer such as B before protocols that consume its content. An application profile must define the meaning of other orders; readers must not reorder the recorded fields. + +A separator is a complete push whose payload is exactly `7c`; a pipe byte embedded within a longer payload is not a separator. The convention defines no escape for a payload consisting only of `7c`. Applications requiring that literal value need a separately agreed representation; parsers must not silently escape, drop, or reinterpret it. Unsupported segments may be retained as opaque bytes; their semantics must not be guessed. + +Example — store a file, attach video metadata, and assign admin rights, using three separate protocols in one atomic output: + +``` +OP_RETURN + 19HxigV4QyBv3tHpQVcUEQyq1pzZVdoAut [DATA] video/mp4 | + 1EKrfyTD6UoXR85vpfxZ7e8h2h8C5XEroy video.mp4 60 | + 1M16gTfEL8f6SkXnTzBepF56KDNG9Qka7Y SET ADMIN +``` + +This convention lets each protocol remain minimal — new capabilities are added by piping into additional protocols rather than by extending a base protocol and accumulating technical debt. The pipeline convention does not strictly require the address-prefix convention, but the two are designed to be used together. + +### 5. Schema Publication (Historical, Informative) + +The historical proposal recommends publishing a machine-readable schema describing the meaning of its push data, so that indexers and applications can interpret protocol transactions without relying on prose documentation. The schema scheme is based on the BitDB transaction serialization format, in which output push data are addressed positionally (`out.s1` is the first push datum as a UTF-8 string, `out.s2` the second, and so on; `out.h2` is the second push datum as hex). + +A schema is a JSON document: + +```json +{ + "v": 1, + "s": { + "out.s2": "{{blob}}", + "out.s3": "{{mediatype}}" + } +} +``` + +- `v` — schema scheme version number. +- `s` — schema description: a mapping from positional push-data selectors to attribute names. Values wrapped in `{{ }}` are attribute variables; unwrapped values are static literals used for pattern matching. A protocol with multiple message patterns expresses `s` as an array of such mappings, with static literals (for example `"out.h2": "01"`) selecting which pattern applies. + +The schema is published on-chain in the protocol's own namespace using the `$ echo` command in embedded admin form (Section 3.6): + +``` +OP_RETURN + 19HxigV4QyBv3tHpQVcUEQyq1pzZVdoAut + $ + echo + {"v":1,"s":{"out.s2":"{{blob}}","out.s3":"{{mediatype}}"}} + to + schema.json +``` + +A schema publication records an immutable candidate interface description; it does not by itself settle version selection or supersede an existing implementation. Consumers locate it by querying for the protocol address with the `$` / `echo` / `to` / `schema.json` pattern (authenticated per Section 3.1) and then parse protocol transactions accordingly. + +### 6. The `bit://` URI Scheme (Historical, Informative) + +Objects published under Bitcom protocols are referenced with the generic URI form: + +``` +bit:/// +``` + +For example, a file stored with the B protocol is referenced as `bit://19HxigV4QyBv3tHpQVcUEQyq1pzZVdoAut/`. Resolution is decentralized: any service provider that has advertised an endpoint for a matching enabled route (Section 3.5) can serve the referenced object, and clients choose among advertised providers. + +The original documentation states that where a protocol has its own shorthand URI scheme, the `bit://` form points to the same content — "the `bit://19HxigV4QyBv3tHpQVcUEQyq1pzZVdoAut` prefix part is equivalent to `b://`" — and recommends the `bit://` scheme going forward. This equivalence is of referent, not of resolution mechanism: a protocol's own scheme may be served by dedicated gateways independent of the route advertisements in Section 3.5. + +### 7. Security and Ownership Considerations + +- The protocol private key is the sole root of administrative authority. Loss of the key means permanent loss of the ability to publish or update protocol metadata; compromise of the key means an attacker can publish authentic-looking metadata. Protocol creators SHOULD protect the protocol key accordingly and SHOULD NOT reuse it for other purposes. +- None of these conventions are consensus-enforced. They are interoperability conventions: anything can be written on-chain, and it is verifiers and indexers that give authenticated admin actions their meaning by applying the checks in Section 3.1. +- Route advertisements are open by design; endpoint trust is a client-side decision (Section 3.5). + +For historical admin processing, an indexer must verify the spending authorization and its commitment to the administrative output, not merely trust an address string returned by a remote indexer. Mixed input owners, signature hash modes that omit outputs, conflicting writes, and reorganization handling require an explicit application profile; the historical descriptions do not settle these cases. A published schema is untrusted data, not executable code or authority to change a protocol retroactively. Route consumers must validate returned transaction content and apply endpoint-fetching controls, including protection against redirects or routes into private networks. + +## Implementations + +- **Bitcom CLI** — the original `bitcom` npm package (`bit` command), building and broadcasting the transactions described here: https://github.com/unwriter/Bitcom +- **bitsh** — interactive shell ("Bash for Bitcom") with HD wallet support under `~/.bitcom`: https://github.com/interplanaria/bitsh +- **bit** — the `bit://` URI scheme and routing implementation: https://github.com/interplanaria/bit +- **B protocol** — the canonical example protocol whose prefix was generated under this convention: https://github.com/unwriter/B +- Other protocols that follow the Bitcom address-prefix and pipeline conventions include B (`19HxigV4QyBv3tHpQVcUEQyq1pzZVdoAut`), MAP (`1PuQa7K62MiKCtssSLKy1kh56WWU7MtUR5`), AIP (`15PciHG22SNLQJXMoSUaWVi7WSqc7hCfva`), and BAP (`1BAPSuaPnfGnSBM3GLV9yhxUdYe4vGbdMT`), with parsers and indexers such as bpu, bob, bmap, and bmap-api built on the positional push-data model of Section 5. + +## References + +- Bitcom repository (README and 0.1.0 release notes): https://github.com/unwriter/Bitcom +- "Bitcom as OS" (admin mode design, proposed by torusJKL): https://github.com/unwriter/Bitcom/issues/1 +- "Bitcom Unix Pipeline" (pipeline design and inspirations): https://github.com/unwriter/Bitcom/issues/2 +- "Bitcoin Script Schema" (on-chain schema publication): https://github.com/unwriter/Bitcom/issues/3 +- Original Bitcom website documentation (archived): https://web.archive.org/web/20211209081820/https://bitcom.bitdb.network/#/ +- route-parser pattern language: https://github.com/rcs/route-parser +- [BRC-18: Pay to False Return](./0018.md) +- [BRC-13: TXO — Transaction Object Format](../transactions/0013.md) (positional push-data serialization used by the schema scheme) diff --git a/scripts/README.md b/scripts/README.md index e20dda5d..31488bf4 100644 --- a/scripts/README.md +++ b/scripts/README.md @@ -16,3 +16,4 @@ BRC | Standard 48 | [Pay to Push Drop](./0048.md) 106 | [Bitcoin Script ASM Format](./0106.md) 173 | [Bitcoin Script to and from Bitcoin BASIC — a compiler and a decompiler](./0173.md) +179 | [Bitcom — Universal Bitcoin Computer: Decentralized Protocol Registry and Composition](./0179.md)