Unit 7: the singleton wrapper

[EvanWinget]

Unit 7, second puzzle: the singleton wrapper, written in the v0 language, resequenced ahead of the payment pool and the async offer (Evan, 2026-08-22). Tooling and vectors only: nothing in spec/ or python/bitlisp/ changes.

What this PR is, honestly

Three things landed, in decreasing order of value:

1. A finding about the vocabulary. Chia's singleton_top_layer does not port. A Bitcoin txid commits input outpoints and output scripts but never input scripts, so proving "my parent sat at a singleton scriptPubKey" needs two transaction preimages, and recognizing that scriptPubKey needs the taproot tweak, which no VM operator performs (secp_verify is Schnorr-only). Both facts apply equally to a fungible asset token's lineage proof.
2. Reusable machinery. puzzles/lib/tx-wire.blib rebuilds a transaction's non-witness serialization from fields with canonical compact-size prefixes, the two-preimage lineage proof, the output-index rule, and the condition morph. All of it is what the asset token benchmark (BAT1 if it becomes a standard) needs.
3. The singleton itself, whose value on Bitcoin is thin: Ark, Lightning, vaults, and payment pools get identity from their root outpoint and authority from signatures, and a funded imitation is self-funded. The doc's "Is a singleton worth having on Bitcoin" section says so, with a census of the vendored Chia corpora showing every Chia use is a token, an identity, or a coin governing other coins.

The construction keeps one scriptPubKey per lineage and commits the state in a zero-value OP_RETURN output of the creating transaction, whose payload is the tree hash of (inner program hash, child amount, child output index). The census also found no Chia dependent needs the puzzle hash to move with the inner puzzle, so the constant scriptPubKey is the better shape on Chia's own evidence, not a compromise. The taproot-tweak operator is flagged for the Phase 4 gate against condition-record decision 3, which declined it on an objection this puzzle answers.

The token benchmark is a capability-and-risk study, not a goal: BitLisp does not want fungible asset tokens on Bitcoin. It wants to know what the vocabulary can build and what that exposes, and to say so before anyone discovers it after deployment.

The review pass (folded in as the last commit)

Ten verified findings, three of them holes: an ending spend left its slot refillable (a hijack), placement hung on the parent's input index (any observer could brick a lineage, and a substituted child stayed live), and a curried internal key would have let a key holder bypass the inner program. Fixes: the ending spend claims a zero-payload state output, the state output commits (inner hash, amount, index) and the owner inner program seals the outputs, and the NUMS point is a wrapper constant. The rest: odd CREATE_OUTPUT_TAPROOT rejected, scriptPubKey derived rather than supplied, list.blib, serializer guarantee stated precisely with empty lists rejected, cost leaks closed, missing negative tests and serialization boundaries added.

Review guide

Read in this order. Each step says what to check and how long it should take.

1. docs/puzzles/singleton.md, sections 1 to 3 (10 minutes). Read "Is a singleton worth having on Bitcoin" as the record of the value question. Check the funded-imitation table against your own sense of Ark, Lightning, vaults, and pools: the claim is that an imitation hurts only the faker in every one of them. Then "Why the Chia construction does not port directly": two facts, the txid's contents and the missing tweak. If either fact is wrong the whole design is wrong, so this is the place to push.

2. The lineage diagram, "The lineage proof", and "The state output" (8 minutes). The chain argument: an outpoint is spent once, so one transaction creates any singleton's child, and that transaction's one tagged state output names the child by amount and index. The induction step is the parent check: a coin at the lineage scriptPubKey can only be spent by running this program (the internal key is the NUMS constant, no key path), so a transaction that spent one spent a genuine singleton. Ask two things: can a funded fake at spk_L ever be spent (no, the input it names is neither the launcher nor a coin at spk_L), and can an observer who re-assembles a broadcast spend end up with a live coin of their own (no, every misplacement is a dead coin, and the ending state's zero payload means an ended slot cannot be refilled).

3. puzzles/lib/tx-wire.blib (5 minutes). The claim to check: the byte string it builds parses back, under Bitcoin's parser, to exactly the fields it was built from. Canonical compact-size (Core rejects non-canonical), width checks on every fixed field. test_wire_serialization_matches_model compares it to the model's Transaction.txid across the compact-size widths the model reaches.

4. puzzles/singleton/singleton.bl (15 minutes). Read the top comment, then bottom up: the assert block of domain guards, spend (names the scriptPubKey, txid, and inner hash once), emit (parent proven, state proven, the three self asserts, then the morph). Four things to verify against the doc: parent-proven handles the launcher case by outpoint equality and everything else through the grandparent's txid, index, and script; state-proven requires exactly one tagged output whose payload hashes this coin's (inner hash, amount, index); morph raises on a second odd output, on none, and on an odd CREATE_OUTPUT_TAPROOT, and turns the -113 marker into the zero-payload ending state output; INTERNAL_KEY is a constant. END_AMOUNT is singleton_top_layer's own escape value, not CAT's melt.

5. puzzles/singleton/owner-inner.bl (3 minutes). The simplest useful inner program. The signature covers the next inner hash, the amount, the extra conditions, and the outputs hash, bound to the coin's outpoint, and the program emits SEAL_OUTPUTS: that seal is what makes a signing owner's placement immutable while fee inputs still attach.

6. "Chia correspondence" and "Adversarial cases" (5 minutes). Five recorded divergences. The one to weigh: placement is committed, not created. With a signing owner nothing is exposed. For an inner program with a public path and no signer, the assembler can end the lineage (a brick) but never redirect it. Chia's exact coin creation has no brick vector.

7. "Authoring observations across the vault and the singleton" (5 minutes). Eight patterns, none implemented. The decision they set up is let first, with the domain-guard blocks as the typing evidence for the v1 gate. Nothing to approve here, only to read.

8. Tests and vectors (5 minutes, mostly commands). python/tests/test_singleton_puzzles.py builds the lifecycle through the transaction model so every txid is real, reproduces each adversarial case with its error code, and recomputes every pinned program, solution, and conditions field from source. Skim test_lifecycle, test_substituted_child_is_dead_and_so_is_the_displaced_one, test_ended_lineage_cannot_be_refilled, and test_fee_input_prepended_keeps_spend_valid, then run the commands below.

Authorizing sections

• CONDITIONS.md entries CREATE_OUTPUT, ASSERT_MY_TAPROOT, ASSERT_MY_AMOUNT, ASSERT_MY_OUTPOINT, ASSERT_SIG_MY_OUTPOINT, SEAL_OUTPUTS (and its author guidance on composing a seal into a signed message).
• VALIDATION.md transaction view (the txid derivation the library reproduces byte for byte), rules 1, 2, 4, and 8.
• VM.md section 4: the operator table, secp_verify Schnorr-only being the fact that decides the construction.
• docs/lang/language.md and docs/lang/curry.md for the surfaces consumed, including computed defconstant for the state tag length.

Commits in order

1. docs: the singleton wrapper design, unit 7 resequenced singleton-second
2. puzzles: the singleton wrapper, the owner inner program, and the wire serialization library
3. vectors: pin the singleton lifecycle and its lineage, state, and morph failures
4. tests: compile-and-run coverage for the singleton puzzles
5. docs: the singleton's value on Bitcoin, the Chia census, and eight authoring observations
6. docs: the token benchmark is a capability-and-risk study, not a goal
7. review fold-ins: committed placement, the ending state output, the fixed internal key, sealed owner spends

Verify independently

.venv/bin/pytest python/tests -q                      # 809 passed
.venv/bin/python tools/run_vectors.py                 # 38 files, 1108 cases, 0 failures
PATH=".venv/bin:$PATH" ci/lint/lint.sh                # all checks passed

# the pinned mod hashes
.venv/bin/bitlisp-compile -T puzzles/singleton/singleton.bl -I puzzles/lib -I puzzles/singleton
.venv/bin/bitlisp-compile -T puzzles/singleton/owner-inner.bl -I puzzles/lib -I puzzles/singleton

Every vector case was executed against the VM and the validator at generation, and every adversarial case is reproduced live in the test suite with its exact error code.