diff --git a/README.md b/README.md index 100a9bbf..3c1aa96f 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) +189 | [MAP State Resolution over a 1Sat Chain](./scripts/0189.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..cf21cc9a 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) +* [MAP State Resolution over a 1Sat Chain](./scripts/0189.md) ## Tokens diff --git a/scripts/0189.md b/scripts/0189.md new file mode 100644 index 00000000..efce5aaf --- /dev/null +++ b/scripts/0189.md @@ -0,0 +1,211 @@ +# BRC-189: 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, segment order, then command order across `:::`; 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. + +This is a proposed state-resolution profile, not a change to MAP wire encoding. The interoperable substrate specified here is the BRC-159 1Sat chain. Other authorization and ordering models require a separately specified profile. + +## Motivation + +Three specifications meet at this gap and none of them fills it. + +BRC-182 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." + +The inspected SET-only resolver provides a useful starting point: 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 link output in the selected record chain, including links that contain no MAP data. Its sequence number is its zero-based position from the origin. Only MAP instruction sets (protocol segments, BRC-182 §3) on that output contribute writes. A link with no applicable instruction sets leaves the state unchanged. + +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. + +Readers MUST parse script opcodes and recognize MAP prefixes only at supported data-carrier/protocol segment boundaries, never by searching arbitrary payload bytes or inscription content. + +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. + +An accepted chain has a structural order independent of timestamps. Competing spends can produce different candidate chains, and a reorganization can change the accepted tip or remove revisions. A resolver MUST bind its result to the selected tip outpoint, distinguish provisional from confirmed chain state, and invalidate/recompute results when its accepted chain changes. It MUST NOT merge competing branches. Missing ancestry, invalid spends or unavailable MAP-bearing link outputs MUST produce an incomplete/error result, not an apparently complete state assembled by skipping the missing revisions. + +#### 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. SELECT and CLEAR still address transactions, not individual outputs: a target matching the current revision's txid never applies, even if another output of that transaction occurred earlier. For another txid, SELECT applies when at least one earlier revision has that txid; CLEAR suppresses every earlier revision of this record with that txid. Neither operation affects later revisions. This rule is a proposed extension for alternate substrates, not historical MAP consensus. + +#### 3.3 Within one output + +An output may carry several protocols in a BRC-179 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 instruction set (one protocol segment), commands separated by `:::` apply in order, first to last. +3. Within one command, arguments apply in push order. + +#### 3.3.1 Carrier and command grammar + +For this profile, the carrier begins at the first `OP_RETURN` at conditional nesting depth zero, after decoding Script opcodes and push lengths. A leading `OP_FALSE` is not MAP data. Bytes inside pushed content are never opcodes, and `OP_RETURN` inside an inscription's conditional envelope does not begin this carrier. After the carrier, all fields MUST be data pushes (`OP_0`, direct pushes, or `PUSHDATA1/2/4`). Small-integer opcodes other than `OP_0` are not substituted for pushed bytes. Truncated pushes, malformed conditional nesting, or non-push carrier opcodes produce an error/incomplete result for the revision; they MUST NOT yield a complete state with guessed boundaries. No carrier means no MAP writes. + +Split the decoded pushes on the exact one-byte value `7c` (`|`), then recognize a MAP segment only if its first push equals the ASCII MAP identifier. Split that segment's remaining pushes on the exact bytes `3a3a3a` (`:::`). Empty command groups are no-ops. Separators cannot simultaneously be literal keys or values in this profile; use a separately defined application encoding when such values are needed. + +A command group begins with its case-sensitive ASCII command word. `SELECT` is a prefix within a group: exactly one txid argument followed by a command word and that command's arguments. Context persists into later groups. Count SELECT prefixes at group starts to enforce section 5.1's segment-wide single-SELECT rule; occurrences inside ordinary data arguments are data, not instructions. A nested `SELECT` in place of the selected command is malformed and invalidates context. Recognized command arities are: SET zero or more complete pairs; ADD and DELETE one key and at least one value; REMOVE one or more keys; CLEAR one or more txids. Unknown commands or insufficient arguments are ignored as a command, without resetting valid context. A bare or malformed SELECT invalidates context for the rest of its segment. + +SELECT and CLEAR txids are exactly 64 ASCII hexadecimal characters; comparisons lowercase them without changing the signed or stored Script bytes. SELECT must name an earlier revision to apply here. For CLEAR, invalid, unknown, current and future targets individually have no effect; other valid earlier targets in that command still apply. Empty keys and values are byte strings and remain distinct from one-byte zero, spaces and undecodable UTF-8. + +#### 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. The MAP text profile uses UTF-8; this reducer retains the raw push bytes so no decoding or normalization can silently change keys or values. Consumer text validation does not alter the underlying byte state. 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 command 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: + +- A command with no active `SELECT` context addresses the record the revision belongs to for `SET`, `ADD`, and `CLEAR`. `REMOVE` and `DELETE` require an explicit `SELECT` context; omission is malformed. This profile does not introduce implicit-context removal commands. +- A `SELECT` whose `` is the transaction of an earlier revision of the same record also addresses the record. This is the form BRC-182 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. + +A MAP segment begins with the current-record context. A valid `SELECT` establishes context for its following command and subsequent `:::`-separated commands in that segment, matching MAP; context resets at the next protocol segment or output. A context naming another record causes its commands to be ignored for this record, never retargeted to the current record. Multiple SELECT commands in one segment are malformed in this profile and invalidate the entire segment, including all commands and CLEAR effects before the second SELECT. This segment-wide rule takes precedence over section 6's command-local recovery; parsing must finish before any effects are committed. + +`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 not a function of the accumulated state alone. To resolve a prefix ending at revision n, first parse each segment completely, reject segment-wide errors, and determine each command's record applicability in forward order using its active SELECT context (section 5.1). Ignore commands addressing another record, including CLEAR. Only then: + +1. Start with an empty set of suppressed revisions. Visit revisions n through 0 in reverse order. +2. Skip a suppressed revision completely, including any `CLEAR` it contains. Otherwise, each valid `CLEAR` in that revision adds its earlier target revisions to the suppressed set. Unknown, same-revision, and later targets have no effect. +3. Fold the non-suppressed revisions forward from the empty state using sections 5.1–5.5; their `CLEAR` commands have already been accounted for. + +The result after every revision MUST equal this algorithm on that prefix. Clearing a revision removes all of its contributions, including its clearing effects: `r0: SET x a; r1: CLEAR tx0; r2: CLEAR tx1` resolves at r2 to `x=[a]`. Two active revisions clearing the same target keep it suppressed until both clearing revisions are suppressed. Clears never alter the chain, custody or historical transaction bytes. Implementations MAY optimize recomputation but MUST preserve these results. This backward-effect rule is a new profile decision, not verified deployed behavior. + +#### 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 + +A command 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 commands in the same output still apply. A malformed SELECT invalidates its context for the remainder of that MAP segment, so a later context-dependent command cannot accidentally target the default record. + +A `SET` with an unmatched final key is malformed and MUST be ignored as a whole command, consistent with BRC-182's complete-pair grammar. Other well-formed commands in the segment are unaffected, subject to the segment-wide SELECT rule. No partial-pair recovery is defined. + +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. + +**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 inspected decoder accepts complete pairs from an odd-length SET; this profile rejects that command instead. The deployed MAP decoder also normalizes NUL and literal `\\u0000` sequences into spaces; this profile deliberately preserves bytes instead. Applications migrating cached string states MUST reconstruct from raw output data rather than assuming those caches preserve byte identity. The inspected resolver is implementation evidence for the SET-only subset, not evidence of full conformance. Its parser and error handling must be checked against this profile before claiming compatibility; no claim is made that deployed corpora exclude other commands. Full-profile readers MUST NOT silently report a SET-only result as the resolved state when other commands occur. No independent interoperable implementation of the full profile is identified here. + +### 9. Conformance and resource bounds + +The worked example in section 5.7 and the following edge cases specify results +without requiring a particular software package: + +| Input at a revision | Result | +|---|---| +| `SET x a dangling` | Ignore the entire malformed SET; prior state survives | +| `SET x a ::: ADD x b a` | `x=[a,b]` | +| `r0: SET x a; r1: CLEAR tx0; r2: CLEAR tx1` | At r2, `x=[a]` | +| SELECT names an unrelated transaction | Ignore commands in that context for this record | +| Two SELECT prefixes in one segment | Ignore that entire segment, including earlier CLEAR effects | +| Missing ancestor or malformed Script carrier | Incomplete/error; no complete state | + + +A full-profile resolver implements all six commands, ordered sets, context validation, malformed-command handling and backward suppression. A SET-only reader MUST identify itself as such and MUST report unsupported profile features when present. Implementations MAY limit history length or work, but MUST report a limit/incomplete result instead of returning a truncated state as complete. + +## 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 + +- [1sat-stack at 589884a](https://github.com/b-open-io/1sat-stack/blob/589884a6a445a57b62e79057d27040660bdaec37/pkg/ordfs/ordfs.go) — `pkg/ordfs`: the inspected SET-only 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-182 — *MAP — Magic Attribute Protocol*. The six commands, the `:::` command separator within an instruction set, 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-181 — *AIP — Author Identity Protocol*. One available authorization model; not required by this BRC. +- 5: BRC-183 — *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 e20dda5d..94af04e3 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) +189 | [MAP State Resolution over a 1Sat Chain](./0189.md)