Add BRC-X: Fixed-Width State in a Covenant's Own Locking Script - #225
Merged
sirdeggen merged 2 commits intoAug 28, 2026
Merged
Conversation
Defines how a covenant carries mutable state inside its own locking script, as a run of fixed-width data pushes readable at constant offsets — by the covenant itself and by any third party holding only the script. The layout is self-describing: for every field, the push opcode that precedes the data is numerically equal to the field's width. A reader holding only the list of widths can walk the state and verify the script agrees with it at every step. Already carried by three covenant families on mainnet (a live counter, a battery, a racing shell — 2, 9 and 13 fields), and read ACROSS the boundary by a fourth covenant that shares no code with them: a fuel depot locates the owner field inside a racing car's script in order to refuel it, validating every push opcode as it walks. That is the interoperability case, in production. Section 10 is a complete worked example — the reading and writing opcodes in full, with hex, emitted by a conforming implementation and verified through a script interpreter. Every figure in the document was checked against the deployed scripts rather than derived.
The figures described a car that is no longer the one being raced. Both now read off the public car minted 2026-08-16, e918fa438f2cab12127fbd9377022868ad35904da2146816e552b26482b11c6a — 1,744 B, the size its own runbook records for the car actually being raced. The shell's lock has grown as rules were added: deployed cars measure 1,636 B, 1,674 B and 1,744 B across 15-16 August, and MAX_FEE is baked into the lock, so a car is self-contained and races under the constants it was born with. The quoted 1,672 B matches no deployed car - the nearest is 1,674 B. The quoted opening bytes, with a zeroed driver field, do match three earlier deployments, a genesis car being an empty shell, so that line described a superseded car rather than an invented one. The self-describing invariant was re-walked across all three deployed sizes and holds in every case, which is the claim the section actually makes. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
sun-dive
force-pushed
the
add-covenant-state-layout
branch
from
August 17, 2026 09:54
5272248 to
36a3673
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This pull request:
Proposes a new standard by creating a new markdown file in the appropriate directory and requests discussion and assignment of a BRC number
Summary
Defines how a covenant carries mutable state inside its own locking script — a run of fixed-width data pushes, readable at constant offsets by the covenant itself and by any third party holding only the script.
The layout is self-describing: for every field, the push opcode preceding the data is numerically equal to that field's width. A reader holding only the list of widths can walk the state and verify the script agrees at every step.
This documents an existing convention rather than proposing a new one. Three covenant families carry state this way on mainnet — a live counter, a battery and a racing shell, with 2, 9 and 13 fields — and a fourth reads it across the boundary: a fuel depot locates the owner field inside a racing car's script in order to refuel it, validating every push opcode as it walks, sharing no code with the car. That interoperability case is what the standard exists to make possible for anyone else.
Section 10 is a complete worked example — the reading and writing opcodes in full, with hex, emitted by a conforming implementation and verified through a script interpreter.
Related: BRC-226 uses the same self-reconstruction technique with an immutable template, so it needs no field layout; this covers the case where the script must legitimately differ between spends.
Filed as BRC-X for number assignment.