diff --git a/README.md b/README.md index 6f57a61f..b40e440a 100644 --- a/README.md +++ b/README.md @@ -236,6 +236,7 @@ BRC | Standard 226 | [Miner-Enforced Resale-Royalty Covenant Tokens (OP_PUSH_TX)](./tokens/0226.md) 227 | [Frictionless On-Chain Onboarding via Pre-Funded Claimable Tokens](./apps/0227.md) 228 | [Unlinkable Payments under the Identity Paradigm](./payments/0228.md) +514 | [MAP State Resolution over a 1Sat Chain](./scripts/0514.md) ## License diff --git a/SUMMARY.md b/SUMMARY.md index e7191d44..1572e6f6 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -104,6 +104,7 @@ * [Bare Multi-Signature](./scripts/0047.md) * [Pay to Push Drop](./scripts/0048.md) * [Bitcoin Script ASM Format](./scripts/0106.md) +* [MAP State Resolution over a 1Sat Chain](./scripts/0514.md) ## Tokens diff --git a/scripts/0514.md b/scripts/0514.md new file mode 100644 index 00000000..bf12d155 --- /dev/null +++ b/scripts/0514.md @@ -0,0 +1,174 @@ +# BRC-514: MAP State Resolution over a 1Sat Chain + +Open Protocol Labs (info@opl.dev) + +**Authors:** Luke Rohenaz (luke@opl.dev) + +**Contributors:** David Case (dcase@opl.dev) — the deployed resolver in `1sat-stack` + +## Abstract + +MAP[1](#footnote-1) writes attributes onto outputs. A record written more than once has several revisions and, until now, no defined present value. This BRC defines **state resolution**: the fold that turns a record's ordered revisions into one resolved key/value state. Revisions apply in chain order, origin to tip; within one output, script order, then `:::` order; within one command, push order — with later writes overriding earlier ones per command semantics. The fold is defined for all six MAP commands: `SET`, `ADD`, `SELECT`, `REMOVE`, `DELETE`, and `CLEAR`. The 1Sat chain[2](#footnote-2) is the canonical revision sequence. + +Authorization is out of scope. This BRC resolves state over a record's authorized writes; it does not decide which writes are authorized. + +## Motivation + +Three specifications meet at this gap and none of them fills it. + +BRC-503 defines MAP's commands over a shared keyspace, and its one context mechanism — `SELECT ` — addresses a *transaction*. It says nothing about combining a record's writes across many transactions over time. BRC-159 defines the 1Sat chain — origin, transfer, tip — and says nothing about the meaning of MAP data carried on it. BRC-160 twice defers the question of which revision on a chain governs, once to "application or content-resolution specs" and again as "an application concern, not fixed by this BRC." + +Implementations answered the question years ago, and answered it the same way: walk the chain from origin to tip, merge each revision's MAP data as you go, let the last write win. That rule is deployed — the OrdFS resolver in `1sat-stack` computes exactly this fold over a sequence-indexed chain — but it is written down nowhere. Any specification that says "the MAP value in effect at the tip" is citing a definition that does not exist, and the orderings inside the rule (several commands in one output, repeated keys in one command) are exactly where independent implementations diverge. + +This BRC writes the rule down. It is deliberately general: it resolves the state of *any* MAP key for *any* consumer. Consumer specifications define their own keys and layer their own validity rules on top of the resolved state; they do not redefine the fold. + +## Specification + +The key words MUST, MUST NOT, SHOULD, SHOULD NOT, and MAY are to be interpreted as described in RFC 2119[3](#footnote-3). + +### 1. Records, revisions, and resolved state + +A **record** is the unit whose MAP state is resolved. Under the canonical substrate (section 3) a record is a 1Sat token, identified by its BRC-159 origin outpoint. + +A **revision** is one authorized write to a record: an output carrying one or more MAP instruction sets (BRC-503 §3) that address the record. A record's revisions form an ordered sequence, numbered from 0 at the origin. + +The **resolved state** of a record at revision *n* is the result of folding revisions 0 through *n* in order (section 5). "The state in effect at the tip" — or any equivalent phrase in a consumer specification — means the resolved state at the record's latest revision. + +### 2. Authorization is out of scope + +Which writes are authorized belongs to whatever system owns the record: BRC-159 spend authority for a 1Sat token, an identity signature such as AIP[4](#footnote-4) or Sigma[5](#footnote-5), or another model entirely. This BRC takes the set of authorized writes as given and defines only how they combine. + +Two rules follow, and they are the only ones this document states about authorization: + +- An indexer MUST NOT fold an unauthorized instruction set into a record's state. MAP has no ownership model of its own — `SELECT ` lets any transaction name any earlier one — so an indexer that folds without an authorization gate lets anyone rewrite anyone's record. +- An indexer MUST document which authorization model it enforces. + +### 3. Revision order + +Resolution is defined only over a totally ordered revision sequence. This section fixes the order at every level, outermost first. + +#### 3.1 The canonical substrate: the 1Sat chain + +The 1Sat chain (BRC-159) is the canonical sequencing substrate. A record's revisions are the links of its chain, in chain order — origin first, tip last. Under spend authority the authorized-write set and the chain coincide, so no further ordering rule is needed: each transfer is at most one revision, and its position in the sequence is its position in the chain. + +Each link contributes the MAP instruction sets carried **on the link's own output** — the 1-satoshi output itself, typically after an `OP_RETURN` following the lock[6](#footnote-6). MAP data anywhere else in the same transaction is not part of this record's resolution. In particular, a data-carrier output elsewhere in the transaction whose `SELECT` names a transaction in the record's chain is not a revision of the record and MUST NOT be folded. + +Chain order is the spend graph, so it is total, structural, and stable: it does not depend on block timestamps or confirmation order, and a reorg cannot reorder it. + +#### 3.2 Other substrates + +A system that authorizes writes by another model MUST supply its own total order over the record's revisions — for example, confirmation order with an in-block tiebreak — and MUST document it. The fold (section 5) is unchanged. When such a substrate admits more than one MAP-bearing output of a single transaction as revisions of the same record, those outputs apply in output index order, lowest first. + +#### 3.3 Within one output + +An output may carry several protocols in a BRC-500 pipeline and several MAP commands per protocol segment: + +1. Protocol segments apply in script order. If more than one MAP segment appears in one output, the later segment's writes fold after the earlier segment's. +2. Within one MAP segment, instruction sets separated by `:::` apply in order, first to last. +3. Within one instruction set, arguments apply in push order. + +#### 3.4 Repeated keys in one command + +A `SET` may repeat key/value pairs. If the same key appears more than once in one `SET`, the last pair wins. Writers SHOULD NOT repeat a key within one command. + +### 4. State model + +The resolved state is a map from key to value list. Every key holds an ordered set of one or more byte-string values: + +- `SET` makes the list a single member. +- `ADD` appends members. +- Value equality, everywhere it is tested (`ADD` dedup, `DELETE` matching), is byte equality of the raw pushes. +- A key with no members is absent from the state. There are no tombstones: a removed key is indistinguishable from one never written. + +Whether a given key is *meant* to hold one value or many is a schema property of that key, defined by the consumer specification that owns it. Resolution does not police cardinality. Representations that render single-member lists as scalars and multi-member lists as arrays (the deployed JSON form does this) are conforming as long as the fold beneath is as specified here. + +### 5. The fold + +Resolution starts from the empty state at revision 0 and applies each instruction set in the order of section 3. Each command transforms the accumulated state as follows. + +#### 5.1 Context: `SELECT` + +`SELECT ` names the record a command addresses. Within a revision sequence: + +- An instruction set with no `SELECT` addresses the record the revision belongs to. This follows MAP's own rule — omitting `SELECT` makes the current transaction the context — and the current transaction *is* a revision of the record. +- A `SELECT` whose `` is the transaction of an earlier revision of the same record also addresses the record. This is the form BRC-503 requires for `REMOVE` and `DELETE`. +- A `SELECT` naming any other transaction does not address this record and MUST be ignored by this record's resolution. + +`SELECT` changes no state by itself, and it does not time-travel: the command following it operates on the accumulated state at the point in the fold where the revision sits, whichever earlier revision the txid names. + +#### 5.2 `SET [ ...]` + +For each pair, in order: the key's value list becomes the single named value, replacing any prior list wholesale. `SET` on a key that held many members (an `ADD`-built list) discards them all. + +#### 5.3 `ADD [ ...]` + +Appends the named values to the key's list, in push order. If the key is absent, `ADD` creates the list. A value already present in the list is left where it is and not appended again. `ADD` on a key last written by `SET` appends to that single-member list; the `SET` value keeps its position at the head. + +#### 5.4 `REMOVE [ ...]` (with `SELECT`) + +Deletes each named key from the state entirely, whatever its member count. `REMOVE` of an absent key does nothing. + +#### 5.5 `DELETE [ ...]` (with `SELECT`) + +Removes each named value from the key's list, by byte equality. Values not present do nothing. If the list becomes empty, the key leaves the state. `DELETE` applies identically to a single-member list written by `SET`. + +#### 5.6 `CLEAR [ ...]` + +Voids the writes carried by the named transactions: the record's resolution proceeds as if the instruction sets those transactions contributed to this record had never appeared in the sequence. The same context constraint as `SELECT` applies — a named txid that is not the transaction of an earlier revision of this record is ignored for this record's resolution. + +`CLEAR` is scoped per record. A transaction may carry revisions of several records (BRC-159 allows several tokens in one transaction); a `CLEAR` naming it voids, for each record being resolved, only that record's writes. + +`CLEAR` is the one command whose effect is not a function of the accumulated state alone. An indexer MAY implement it by re-folding the sequence with the named revisions skipped; the result MUST equal that re-fold. A `CLEAR` is itself part of a revision, applies at its position in the order, and can name only transactions that already exist. + +#### 5.7 Worked example + +One record, four revisions: + +| Rev | Instruction sets | Resolved state after | +|-----|------------------|----------------------| +| 0 | `SET name Genesis ::: ADD tags a b` | `name=[Genesis] tags=[a,b]` | +| 1 | `ADD tags b c` | `name=[Genesis] tags=[a,b,c]` (duplicate `b` not re-appended) | +| 2 | `SELECT DELETE tags a ::: SET title Renamed` | `name=[Genesis] tags=[b,c] title=[Renamed]` | +| 3 | `CLEAR ` | `name=[Genesis] tags=[a,b,c]` (revision 2's writes voided; revisions 0 and 1 stand) | + +### 6. Malformed data and partial application + +An instruction set that cannot be parsed as one of the six commands — an unknown command word, a `SELECT` with no following command, an `ADD` with no values — MUST be ignored as a unit. Other instruction sets in the same output, before or after it, still apply. + +A `SET` whose final key has no value applies its complete pairs and ignores the trailing key. This is the deployed behavior and it keeps a truncated write from discarding the pairs that did arrive intact. + +Resolution is key-agnostic: it stores what authorized commands write, unknown keys included. Key-specific validity — value grammars, cardinality, meaning — belongs to the consumer specification that owns the key, which MAY disregard invalid values *when reading* the resolved state. Consumer-level filtering MUST NOT alter the resolved state itself: an invalid value under one consumer's grammar is still resolved state visible to every other consumer. + +### 7. Resolution at a point, and history + +An indexer MUST resolve a record's current state (the fold over all revisions). It SHOULD resolve the state at any earlier revision — the fold over revisions 0 through *n* — addressed by sequence number; the deployed resolver does. An indexer SHOULD be able to emit the record's history as the ordered list of `(revision outpoint, instruction sets)`; this is a projection over the same sequence, not a separate structure. + +### 8. Deployed practice and what this document adds + +This BRC is part documentation and part first specification. The line between them: + +**Documented — deployed today** in the OrdFS resolver of `1sat-stack` (`pkg/ordfs`): the canonical substrate (a per-origin sequence index over chain links, with content, MAP, and parent entries per link); revision = the chain-link output's own MAP data and nothing else in the transaction; the chain-order fold with per-key last-write-wins; piped MAP segments in one output merged in script order; sequence-addressed historical resolution; and the partial-`SET` rule of section 6. + +**Specified first here**: the fold semantics of `ADD`, `DELETE`, `REMOVE`, `SELECT`, and `CLEAR` (the deployed resolver folds `SET` only and ignores the other commands); the ordered-set value model with byte-equality dedup; the `:::` ordering rule (the deployed parser reads only the first command of a segment); and the within-transaction rule of section 3.2 for non-canonical substrates. + +The deployed resolver is an incomplete implementation of this specification rather than a divergent one: on every command it applies, it matches this fold. It becomes non-conforming only for chains that carry list or removal commands, which the corpora it serves have so far not used. Implementations SHOULD converge on the full command set as writers adopt it. + +## Security considerations + +- **Fold only authorized writes.** The entire resolution is downstream of the authorization gate (section 2). An indexer that folds every syntactically valid MAP command it finds gives every network participant write access to every record. +- **`CLEAR` and `SELECT` reach backward.** Both commands name earlier transactions. The context constraint (sections 5.1, 5.6) confines their reach to the record's own revision sequence; without it, one transaction could void or edit unrelated records. +- **Resolved state is claims, not proof.** The fold establishes what a record's authorized writers said, in what order. Whether any of it is true is an application concern. + +## Implementations + +- [b-open-io/1sat-stack](https://github.com/b-open-io/1sat-stack) — `pkg/ordfs`: the deployed resolver. `OriginStore` maintains the per-origin sequence index; `loadMergedMap` computes the chain-order fold; resolution is addressable by sequence. +- [docs.1satordinals.com](https://docs.1satordinals.com) + +## References + +- 1: BRC-503 — *MAP — Magic Attribute Protocol*. The six commands, the `:::` instruction-set separator, and the shared keyspace. Canonical repository: https://github.com/opldotdev/MAP +- 2: [BRC-159](../tokens/0159.md) — *1Sat Ordinals — Single-Satoshi Tokens and Origin Tracking*. Origin, sat ordering, transfer, tip and burn. +- 3: Bradner, S. (1997). *Key words for use in RFCs to Indicate Requirement Levels*. RFC 2119. https://www.rfc-editor.org/rfc/rfc2119 +- 4: BRC-502 — *AIP — Author Identity Protocol*. One available authorization model; not required by this BRC. +- 5: BRC-504 — *Sigma — Transaction-Bound Script Signatures*. One available authorization model; not required by this BRC. +- 6: [BRC-160](../tokens/0160.md) — *1Sat Ordinals — Inscription Envelopes*. The metadata pattern for MAP after `OP_RETURN` on a spendable 1Sat output. diff --git a/scripts/README.md b/scripts/README.md index 1dd609c9..930e0f3b 100644 --- a/scripts/README.md +++ b/scripts/README.md @@ -15,3 +15,4 @@ BRC | Standard 47 | [Bare Multi-Signature](./0047.md) 48 | [Pay to Push Drop](./0048.md) 106 | [Bitcoin Script ASM Format](./0106.md) +514 | [MAP State Resolution over a 1Sat Chain](./0514.md)