docs: add docs re current stxo design #1830

Roasbeef · 2025-10-01T01:12:31Z

No description provided.

gemini-code-assist · 2025-10-01T01:12:46Z

Summary of Changes

Hello @Roasbeef, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly enhances the documentation for the Taproot Assets protocol by introducing a detailed guide to the Spent Transaction Output (STXO) proof system. The newly added stxo_design.md comprehensively explains the cryptographic foundations, data structures, and operational lifecycle of STXO proofs. This documentation clarifies how assets are proven to be validly spent and protected against double-spending through the integration of burn keys and a two-level Merkle-Sum Sparse Merkle Tree, providing essential insights for developers and users into the protocol's security and integrity mechanisms.

Highlights

Comprehensive Documentation: A new stxo_design.md file has been added, providing an in-depth explanation of the Spent Transaction Output (STXO) proof system in Taproot Assets.
Core STXO Concept: The document details how STXO proofs ensure assets are validly consumed and not double-spent, using minimal asset representations with provably unspendable "burn keys" within the Merkle-Sum Sparse Merkle Tree (MS-SMT) structure.
Burn Key Cryptography: It elaborates on the deterministic derivation of burn keys from PrevIDs, utilizing a taproot-style tweak of a Nothing-Up-My-Sleeve (NUMS) point to guarantee uniqueness and unspendability.
Commitment Tree Integration: The documentation explains the two-level MS-SMT architecture, illustrating how STXO assets are managed within a dedicated EmptyGenesisID namespace for efficient insertion, retrieval, and proof generation.
Lifecycle and Verification: The process of STXO proof creation during asset transfer initiation, the IsTransferRoot decision, and the subsequent generation and verification of inclusion and exclusion proofs are thoroughly described.
Security Guarantees: The document highlights the security properties provided by STXO proofs, including prevention of double-spending and replay attacks, burn key unspendability, and collision resistance.
Versioning and Compatibility: It outlines the TransitionV0 and TransitionV1 versions, clarifying that STXO proofs are mandatory for TransitionV1 transfer root assets, and discusses backward compatibility and downgrade mechanisms.
Special Case Handling: Specific scenarios like genesis asset minting, split transactions, consolidation transfers, and burn transactions are addressed, detailing how STXO proofs are applied or exempted.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	`/gemini review`	Performs a code review for the current pull request in its current state.
Pull Request Summary	`/gemini summary`	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	`/gemini help`	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

gemini-code-assist

Code Review

This pull request adds a comprehensive design document for the STXO proof system. The document is well-structured and detailed. I've provided a few suggestions to improve clarity, fix typos, and correct minor inaccuracies in diagrams and code snippets to make the documentation even better.

gemini-code-assist · 2025-10-01T01:14:32Z

docs/stxo_design.md

+        +Asset Asset
+        +TaprootProof InclusionProof
+        +[]TaprootProof ExclusionProofs
+        +[]AltLeaf_Asset_ AltLeaves


In the Mermaid diagram, the class name AltLeaf_Asset_ appears to be a typo. Based on the Go type []asset.AltLeaf[asset.Asset], a more accurate representation would be []AltLeaf<Asset>.

Suggested change

+[]AltLeaf_Asset_ AltLeaves

+[]AltLeaf<Asset> AltLeaves

gemini-code-assist · 2025-10-01T01:14:33Z

docs/stxo_design.md

+
+    Proof --> TaprootProof : has
+    TaprootProof --> CommitmentProof : contains
+    CommitmentProof --> Asset_STXO : STXOProofs map to


The relationship CommitmentProof --> Asset_STXO : STXOProofs map to in the Mermaid diagram is a bit misleading. The STXOProofs field is a map from a serialized key to a commitment.Proof, not directly to an Asset_STXO. A more accurate label would clarify that the proofs are used to prove the inclusion or exclusion of the STXO asset.

Suggested change

CommitmentProof --> Asset_STXO : STXOProofs map to

CommitmentProof --> Asset_STXO : STXOProofs prove

gemini-code-assist · 2025-10-01T01:14:33Z

docs/stxo_design.md

+
+```go
+// MakeSpentAsset creates an Alt Leaf with the minimal asset based on the
+// PrevId of the witness.


There's a typo in the code comment. PrevId should be PrevID to be consistent with the witness.PrevID field used in the code.

Suggested change

// PrevId of the witness.

// PrevID of the witness.

gemini-code-assist · 2025-10-01T01:14:33Z

docs/stxo_design.md

+The critical decision is the `IsTransferRoot` check. An asset is a transfer root
+if it has at least one `PrevWitness` with a non-nil `PrevID`. This distinguishes
+transfer roots from genesis assets (no previous witnesses) and split leaves
+(created from a split commitment, don't reference inputs directly). Only


Using "don't" is a bit informal for technical documentation. It's generally better to use the full phrase "do not" for clarity and consistency.

Suggested change

(created from a split commitment, don't reference inputs directly). Only

(created from a split commitment, do not reference inputs directly). Only

gemini-code-assist · 2025-10-01T01:14:33Z

docs/stxo_design.md

+
+```go
+// CollectSTXO returns the assets spent by the given output asset in the form
+// of a minimal assets that can be used to create an STXO commitment.


There's a grammatical error in the comment. "a minimal assets" should be "minimal assets" since the function returns a slice.

Suggested change

// of a minimal assets that can be used to create an STXO commitment.

// of minimal assets that can be used to create an STXO commitment.

gemini-code-assist · 2025-10-01T01:14:33Z

docs/stxo_design.md

+// The firstPrevID must be the PrevID from the first input that is being spent
+// by the virtual transaction that contains the burn.
+func DeriveBurnKey(firstPrevID PrevID) *btcec.PublicKey {


The comment The firstPrevID must be the PrevID from the first input that is being spent is confusing, as this function is called for each input's PrevID. The parameter name firstPrevID is also misleading. Consider renaming it to prevID for clarity.

Suggested change

// The firstPrevID must be the PrevID from the first input that is being spent

// by the virtual transaction that contains the burn.

func DeriveBurnKey(firstPrevID PrevID) *btcec.PublicKey {

// The prevID must be the PrevID from an input that is being spent

// by the virtual transaction that contains the burn.

func DeriveBurnKey(prevID PrevID) *btcec.PublicKey {

gemini-code-assist · 2025-10-01T01:14:33Z

docs/stxo_design.md

+    _ = wire.WriteOutPoint(&b, 0, 0, &firstPrevID.OutPoint)
+    _, _ = b.Write(firstPrevID.ID[:])
+    _, _ = b.Write(firstPrevID.ScriptKey.SchnorrSerialized())


To complete the renaming of firstPrevID to prevID suggested for the function signature, please update its usage here as well.

Suggested change

_ = wire.WriteOutPoint(&b, 0, 0, &firstPrevID.OutPoint)

_, _ = b.Write(firstPrevID.ID[:])

_, _ = b.Write(firstPrevID.ScriptKey.SchnorrSerialized())

_ = wire.WriteOutPoint(&b, 0, 0, &prevID.OutPoint)

_, _ = b.Write(prevID.ID[:])

_, _ = b.Write(prevID.ScriptKey.SchnorrSerialized())

gemini-code-assist · 2025-10-01T01:14:33Z

docs/stxo_design.md

+
+    F --> G[ComputeTaprootOutputKey<br/>NUMSKey, Data]
+
+    G --> H["TapTweak = SHA256<br/>TapTweak/elements concat NUMSKey concat Data"]


The formula for TapTweak in the diagram is a simplification of the actual tagged hash mechanism used in Taproot. A more accurate representation would be TaggedHash('TapTweak', NUMSKey || Data), which clarifies that a specific tagged hash function is used.

Suggested change

G --> H["TapTweak = SHA256<br/>TapTweak/elements concat NUMSKey concat Data"]

G --> H["TapTweak = TaggedHash('TapTweak', NUMSKey || Data)"]

gemini-code-assist · 2025-10-01T01:14:33Z

docs/stxo_design.md

+### Split Transactions
+
+Split transactions exhibit nuanced STXO behavior. One input asset is divided
+into multiple outputs. The split root contains a `SplitCommitmentRoot`, a merkle


For consistency with other parts of the document (like "Merkle-Sum Sparse Merkle Tree"), "merkle tree" should be capitalized as "Merkle tree".

Suggested change

into multiple outputs. The split root contains a `SplitCommitmentRoot`, a merkle

into multiple outputs. The split root contains a `SplitCommitmentRoot`, a Merkle

coveralls · 2025-10-01T01:38:06Z

Pull Request Test Coverage Report for Build 18148030519

Details

0 of 0 changed or added relevant lines in 0 files are covered.
19 unchanged lines in 6 files lost coverage.
Overall coverage increased (+6.9%) to 56.515%

Files with Coverage Reduction	New Missed Lines	%
tapdb/assets_common.go	2	78.34%
tapdb/sqlc/transfers.sql.go	2	82.65%
tapgarden/custodian.go	2	77.02%
universe/supplyverifier/manager.go	2	64.53%
tapdb/universe.go	4	81.04%
tapdb/assets_store.go	7	79.41%

Totals
Change from base Build 18145713853:	6.9%
Covered Lines:	63782
Relevant Lines:	112859

💛 - Coveralls

docs: add docs re current stxo design

2393c38

gemini-code-assist bot reviewed Oct 1, 2025

View reviewed changes

levmi assigned Roasbeef Oct 2, 2025

levmi added this to Taproot-Assets Project Board Oct 2, 2025

github-project-automation bot moved this to 🆕 New in Taproot-Assets Project Board Oct 2, 2025

levmi moved this from 🆕 New to 🏗 In progress in Taproot-Assets Project Board Oct 2, 2025

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

docs: add docs re current stxo design #1830

docs: add docs re current stxo design #1830

Roasbeef commented Oct 1, 2025

Uh oh!

gemini-code-assist bot commented Oct 1, 2025

Uh oh!

gemini-code-assist bot left a comment

Uh oh!

gemini-code-assist bot Oct 1, 2025

Uh oh!

gemini-code-assist bot Oct 1, 2025

Uh oh!

gemini-code-assist bot Oct 1, 2025

Uh oh!

gemini-code-assist bot Oct 1, 2025

Uh oh!

gemini-code-assist bot Oct 1, 2025

Uh oh!

gemini-code-assist bot Oct 1, 2025

Uh oh!

gemini-code-assist bot Oct 1, 2025

Uh oh!

gemini-code-assist bot Oct 1, 2025

Uh oh!

gemini-code-assist bot Oct 1, 2025

Uh oh!

coveralls commented Oct 1, 2025

Uh oh!

Uh oh!

	CommitmentProof --> Asset_STXO : STXOProofs map to
	CommitmentProof --> Asset_STXO : STXOProofs prove

	(created from a split commitment, don't reference inputs directly). Only
	(created from a split commitment, do not reference inputs directly). Only

	// of a minimal assets that can be used to create an STXO commitment.
	// of minimal assets that can be used to create an STXO commitment.


		F --> G[ComputeTaprootOutputKey<br/>NUMSKey, Data]

		G --> H["TapTweak = SHA256<br/>TapTweak/elements concat NUMSKey concat Data"]

	G --> H["TapTweak = SHA256<br/>TapTweak/elements concat NUMSKey concat Data"]
	G --> H["TapTweak = TaggedHash('TapTweak', NUMSKey \|\| Data)"]

	into multiple outputs. The split root contains a `SplitCommitmentRoot`, a merkle
	into multiple outputs. The split root contains a `SplitCommitmentRoot`, a Merkle

docs: add docs re current stxo design #1830

Are you sure you want to change the base?

docs: add docs re current stxo design #1830

Conversation

Roasbeef commented Oct 1, 2025

Uh oh!

gemini-code-assist bot commented Oct 1, 2025

Summary of Changes

Highlights

Footnotes

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

gemini-code-assist bot Oct 1, 2025

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Oct 1, 2025

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Oct 1, 2025

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Oct 1, 2025

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Oct 1, 2025

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Oct 1, 2025

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Oct 1, 2025

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Oct 1, 2025

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Oct 1, 2025

Choose a reason for hiding this comment

Uh oh!

coveralls commented Oct 1, 2025

Pull Request Test Coverage Report for Build 18148030519

Details

💛 - Coveralls

Uh oh!

Uh oh!