docs: add docs re current stxo design

[Roasbeef]

No description provided.

[gemini-code-assist]

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.

Footnotes

1. 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.

[coveralls]

Pull Request Test Coverage Report for Build 18387463468

Details

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

---

Files with Coverage Reduction	New Missed Lines	%
tapdb/multiverse.go	2	80.59%
tapdb/sqlc/transfers.sql.go	2	83.33%
universe/supplyverifier/manager.go	2	64.53%
itest/multisig.go	3	97.94%
universe/archive.go	3	81.01%
tapdb/assets_store.go	9	79.74%

Totals
Change from base Build 18359865357:	6.9%
Covered Lines:	63938
Relevant Lines:	113078

---

💛 - Coveralls

[GeorgeTsagk]

Read through it, LGTM

I understand that this has been generated with the aid of an agent -- perhaps we could distill it and make it a bit less verbose. Non-blocking though, just personal preference.

[ffranr]

I've scanned through this. It mostly looks ok I think.

I'm not sure if the codebase actually benefits from this sort of doc. It was generated with an agent + code + spec? In which case it seems like something that an agent could figure out on the fly. And the doc can go stale etc.

[jtobin]

I think this needs a bump to satisfy CI, or @Roasbeef feel free to just bypass that and merge.

[lightninglabs-deploy]

@Roasbeef, remember to re-request review from reviewers when ready