docs: add docs for how burns work within the protocol and codebase #1786
+753
−0
Conversation
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
Roasbeef
added
documentation
Pull Request Test Coverage Report for Build 17600559753Details
💛 - Coveralls |
|
@ffranr: review reminder |
darioAnongba
reviewed
Oct 1, 2025
| ``` | ||
|
|
||
| When a burn request arrives, the system first performs comprehensive input | ||
| validation. The implementation supports both binary and hex string asset IDs, |
There was a problem hiding this comment.
Just adding a note that if this gets merged after #1812, then we should change asset IDs by asset IDs or group keys or similar.
Comment on lines
+112
to
+117
| Following initial validation, the system attempts to resolve the asset's group | ||
| membership. This resolution step, while currently limited in its application due | ||
| to the single-asset restriction, lays the groundwork for future group-based burn | ||
| operations. The system queries the asset store to identify whether the target | ||
| asset belongs to a group, information that becomes crucial for proper burn key | ||
| derivation and commitment management. |
There was a problem hiding this comment.
Whole paragraph becomes unnecessary if the PR goes after #1812
| preventing scenarios where insufficient funds or incorrect asset types might | ||
| lead to failed transactions. | ||
|
|
||
| Coin selection follows, utilizing the PreferMaxAmount strategy to minimize the |
There was a problem hiding this comment.
Suggested change
| Coin selection follows, utilizing the PreferMaxAmount strategy to minimize the | |
| Coin selection follows, utilizing the `PreferMaxAmount` strategy to minimize the |
Verbatim
Comment on lines
+170
to
+175
| firstPrevID := asset.PrevID{ | ||
| OutPoint: firstInput.AnchorPoint, | ||
| ID: firstInput.Asset.ID(), | ||
| ScriptKey: asset.ToSerialized(firstInput.Asset.ScriptKey.PubKey), | ||
| } | ||
| burnKey := asset.NewScriptKey(asset.DeriveBurnKey(firstPrevID)) |
There was a problem hiding this comment.
Suggested change
| firstPrevID := asset.PrevID{ | |
| OutPoint: firstInput.AnchorPoint, | |
| ID: firstInput.Asset.ID(), | |
| ScriptKey: asset.ToSerialized(firstInput.Asset.ScriptKey.PubKey), | |
| } | |
| burnKey := asset.NewScriptKey(asset.DeriveBurnKey(firstPrevID)) | |
| firstPrevID := pkt.Inputs[0].PrevID | |
| burnKey := asset.NewScriptKey(asset.DeriveBurnKey(firstPrevID)) |
I think we can omit the rest that doesn't seem relevant to the paragraph.
| transfers that might create tombstones. | ||
|
|
||
| Input commitment allocation represents one of the most complex aspects of the | ||
| burn process. The createFundedPacketWithInputs function maps selected |
There was a problem hiding this comment.
Suggested change
| burn process. The createFundedPacketWithInputs function maps selected | |
| burn process. The `createFundedPacketWithInputs` function maps selected |
Comment on lines
+195
to
+201
| The system enforces several critical constraints during execution. The full burn | ||
| prevention mechanism blocks attempts to burn all assets in an anchor output, | ||
| preventing the creation of empty outputs that would waste Bitcoin UTXO space. | ||
| The single packet restriction currently limits burns to one virtual packet, | ||
| effectively preventing group-based burns. These constraints, while limiting in | ||
| some scenarios, ensure system stability and prevent edge cases that could | ||
| compromise the burn mechanism's integrity. |
There was a problem hiding this comment.
Suggested change
| The system enforces several critical constraints during execution. The full burn | |
| prevention mechanism blocks attempts to burn all assets in an anchor output, | |
| preventing the creation of empty outputs that would waste Bitcoin UTXO space. | |
| The single packet restriction currently limits burns to one virtual packet, | |
| effectively preventing group-based burns. These constraints, while limiting in | |
| some scenarios, ensure system stability and prevent edge cases that could | |
| compromise the burn mechanism's integrity. |
Unnecessary paragraph after #1812
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
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.
No description provided.