Opstream

Opstream is a lightweight Bitcoin-native event stream protocol for collections, assets, memberships, and application state that can be reconstructed from ordinary Bitcoin transactions.

The core claim is narrow and practical: protocol state can be rebuilt by replaying valid transactions tied to one public operator address. Databases, APIs, wallets, and applications are convenience layers around that stream, not the source of truth.

An Opstream implementation defines how events are recognized, validated, ordered, and applied. Bitcoin provides the durable transaction history; Opstream provides the replay model that makes that history usable as state.

Bitcoin NFT and asset systems commonly require broad indexing surfaces: global inscription scans, marketplace-specific APIs, fragile off-chain databases, or application-owned state that cannot be independently replayed.

Those approaches make small collections expensive to operate and difficult to verify. Builders often inherit heavy infrastructure requirements before they can ship a simple mint, transfer, membership, or access-control primitive.

Opstream narrows the indexing surface to one public operator address. A compliant indexer follows that address, parses matching protocol events, validates them against collection rules, and reconstructs state without scanning every wallet, Ordinal, Atomical, or inscription.

The framework is not a single collection. It is a protocol pattern for building replayable Bitcoin applications with small, auditable transaction rules.

Bitcoin already provides ordering, permanence, timestamps, replication, and immutability. Opstream does not attempt to recreate consensus, simulate a virtual machine, or control transaction inclusion.

Instead, the protocol defines a recognition layer. A transaction either satisfies the collection's event format and validation rules or it does not. Compliant indexers recognize canonical events and ignore invalid ones.

This separation keeps the system modest. Bitcoin remains the final publication layer, while Opstream gives builders a deterministic way to translate a subset of transactions into application state.

The operator address is the canonical event stream. Every valid transaction must include a payment to that address, creating a compact public anchor for the collection or application.

An indexer does not need to discover every possible participant address. It starts from one known address, fetches its transaction history, extracts valid protocol payloads, sorts them, and replays state.

This model also gives creators a native fee mechanism. The same output that anchors indexing can satisfy the collection's configured operator payment requirement.

Standard Opstream transactions use deterministic output positions so parsers do not depend on marketplace heuristics, wallet-specific conventions, or ambiguous payload discovery.

The default layout places the operator payment first, the protocol JSON second, and the owner or receiver anchor third. Additional outputs are available for extensions, payload references, or other collection-defined data.

Creator-defined fees can vary by collection. The important rule is that the indexer can verify the configured amount and address deterministically.

Opstream supports protocol-level creator fees by requiring valid mint, transfer, or extension operations to pay the operator address. The fee is part of transaction validity for that collection.

This is not smart-contract enforcement and it does not depend on marketplace enforcement. Bitcoin will still accept transactions that do not follow Opstream rules.

The enforcement boundary is canonical recognition. Compliant indexers recognize only transactions that satisfy the collection's fee rules, output layout, namespace, and operation semantics.

Each event carries a small JSON envelope in OP_RETURN. The starter default mirrors the current environment-driven configuration: OPSTREAM_PROTOCOL, OPSTREAM_COLLECTION, and OPSTREAM_COLLECTION_DISPLAY_NAME.

The p field identifies the protocol family. The op field identifies the operation. The name field identifies the collection namespace. Collection-specific extensions may add fields such as id, amt, metadata references, permissions, or application data.

Indexers should reject malformed JSON and ignore envelopes that do not match the configured protocol and collection namespace.

Opstream is operation-oriented. A deploy operation can announce a namespace, a mint operation can create an asset, and a transfer operation can move ownership or fractional balances.

Future implementations can define burn, freeze, metadata update, access, staking, permission, governance, or application-specific operations. Unsupported operations are ignored by canonical indexers unless a collection explicitly adopts them.

The examples below are generic protocol examples. A production collection should publish its supported operations, fee rules, output requirements, and extension fields.

Opstream events are not merely passive inscriptions. They are replayable state transitions whose effects are derived from transaction validity, event order, and the current replayed state.

Ownership is not trusted from a database row. It is computed by replaying deploys, mints, transfers, and other supported operations in canonical order.

Invalid events are ignored by compliant indexers. A malformed transfer, an insufficient balance, a missing owner anchor, or an underpaid operator output does not modify canonical state.

The current simple fractional model treats one NFT as one hundred units. A complete owner has 100 units. A partial owner may hold any validated balance within that unit set.

A transfer with amt equal to 47 moves 47 units to the receiver and leaves 53 units with the sender, assuming the sender previously held all 100 units.

A future direction is Bitcoin-like divisibility where one NFT equals 100,000,000 units. That model would allow 8-decimal fractional ownership while preserving the same replay principle.

OP_RETURN and additional outputs can carry structured data, metadata, media payload references, or collection-specific extensions.

Each collection decides how much media or metadata is placed directly on-chain and how much is referenced externally. The protocol does not require every asset to use the same media encoding strategy.

For long-lived collections, the critical requirement is replayability. If an event depends on external metadata, the collection should document how clients resolve, verify, and preserve that reference.

The replay engine is the heart of an Opstream implementation. It fetches operator-address transactions, parses payloads, validates them, sorts canonical events, applies mints and transfers, and writes the resulting state to a cache.

Canonical ordering should use block height, block time, and transaction id. Mempool views can be useful for previews, but confirmed ordering is the basis for canonical state.

Mint identifiers can be deterministic when they are assigned from replay order. A full rebuild should produce the same identifiers, ownership balances, and event validity results.

A compliant indexer should verify that the operator payment exists and meets the configured amount, the OP_RETURN JSON is valid, the protocol and collection namespace match config, and the operation is supported.

Mint and transfer events should also verify that the owner or receiver anchor is present. Transfers must verify sender authority and sufficient balance before modifying state.

Duplicate events must be ignored and replay must be idempotent. Production systems also need confirmation policies, reorg handling, raw transaction retention, and explicit behavior for mempool-only events.

Opstream is designed for lightweight micro-indexers. A minimal production indexer needs one operator address, one Bitcoin transaction API, one parser, one replay engine, one cache database, and one scheduler.

The indexer can be small because it is not responsible for discovering the entire Bitcoin asset universe. Its task is to rebuild one stream accurately and repeatedly.

Supabase in the starter is a cache for application reads and dashboard views. It is not the canonical state source. If the database is lost, corrupted, or migrated, the indexer should be able to rebuild from Bitcoin history.

The database is a rebuildable cache. It exists to make application reads fast, power user interfaces, record indexer runs, and expose API responses without replaying the chain on every request.

A typical implementation can model events, mints, ownerships, indexer state, and indexer runs. The exact schema is an implementation detail as long as canonical state can be reconstructed from raw transaction history.

Production operators should preserve raw transaction data or enough transaction context to audit every accepted and rejected event.

A builder can launch an Opstream collection by forking the starter, choosing an operator address, choosing a collection namespace, configuring fee and anchor values, deploying the cache, and running a backfill.

The launch process should include at least one test mint and one test transfer. Those transactions should be replayed from scratch to confirm that the indexer and UI agree with canonical state.

The checklist below is intentionally operational. It describes the minimum decisions a collection needs before public use.

This repository provides the practical application layer for an Opstream-style collection: wallet connection, mint transaction creation, transfer flow, broadcast APIs, indexer refresh and backfill endpoints, Supabase-backed cache reads, and environment-driven collection configuration.

The starter is deliberately configurable. Builders should replace placeholder media and metadata with real collection assets, publish their collection rules, and ensure their operator address and fee values are final before launch.

No starter database, API route, or wallet component should be treated as canonical by itself. They are conveniences around the replayable Bitcoin event stream.

Indexers must treat malformed JSON, unexpected output layouts, invalid fee payments, unsupported operations, duplicate events, insufficient transfer balances, and ambiguous sender evidence as non-canonical.

Reorgs and mempool ambiguity require explicit policy. A transaction visible in the mempool is not equivalent to a confirmed event, and a confirmed event can move during a chain reorganization.

External Bitcoin APIs can fail, disagree, or omit data. Production indexers should preserve raw transaction data, support full rebuilds, log rejected events, and make database corruption recoverable through replay.

The operator-address event stream pattern extends beyond NFTs. It can be used for memberships, ticketing, access control, digital identity, fractional assets, governance, reputation, and replayable application state.

The common requirement is that each application defines a small set of valid operations and a deterministic replay function. Once those rules are public, independent indexers can reconstruct the same state.

This makes Opstream most useful where builders want Bitcoin permanence without imposing global indexing requirements on every client.

Opstream rests on three pillars: operator-address event streams, deterministic transaction layouts, and replay-driven state reconstruction.

Those pillars keep the protocol small enough for independent builders to operate while preserving a clear distinction between canonical Bitcoin history and convenience infrastructure.

Bitcoin remains canonical. Opstream makes state easier to build, index, replay, and use.