Enhance Bitcoin finality documentation in Stacks #1804
Conversation
Expanded on the concept of Bitcoin finality in Stacks, detailing its implications, mechanisms, and recent upgrades. Added sections on transaction types, security implications, and future developments post-Nakamoto upgrade.
There was a problem hiding this comment.
Pull request overview
This pull request significantly enhances the Bitcoin finality documentation for Stacks, expanding it from approximately 50 lines to 246 lines. The update provides comprehensive coverage of how Stacks achieves 100% Bitcoin finality through the Nakamoto upgrade, including detailed explanations of technical mechanisms, security implications, and real-world applications.
Changes:
- Expanded technical explanation of Bitcoin finality mechanisms, including tenure-based mining and indexed block hash construction
- Added comprehensive sections on sBTC integration with Bitcoin finality, including current status and operational details
- Documented post-Nakamoto network performance metrics, ongoing optimizations (SIP-034, transaction replay), and future development roadmap
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| **Transaction Replay Feature** | ||
| - Designed to replay transactions orphaned by Bitcoin reorgs | ||
| - Ensures transactions aren't lost due to Bitcoin chain reorganizations | ||
| - Currently in testing phase as of Q4 2025 |
There was a problem hiding this comment.
The status "Currently in testing phase as of Q4 2025" appears outdated. Since this document is dated January 2026 (as stated in line 246), this should be updated to reflect the current status of the Transaction Replay Feature, or reworded to indicate when it was in testing (e.g., "Was in testing phase during Q4 2025" or "Entered testing phase in Q4 2025").
| - Currently in testing phase as of Q4 2025 | |
| - Was in testing phase during Q4 2025 |
|
|
||
| ### Technical Documentation | ||
| - [Nakamoto Upgrade Overview](../nakamoto-upgrade/) | ||
| - [Proof-of-Transfer (PoX) Mechanism](../consensus/) |
There was a problem hiding this comment.
The link to the Proof-of-Transfer mechanism appears to be incorrect. There is no ../consensus/ directory. Based on the repository structure, the correct link should likely be ../stacks-101/proof-of-transfer.md which contains the documentation for the Proof-of-Transfer (PoX) mechanism.
| - [Proof-of-Transfer (PoX) Mechanism](../consensus/) | |
| - [Proof-of-Transfer (PoX) Mechanism](../stacks-101/proof-of-transfer.md) |
| ## Resources | ||
|
|
||
| ### Technical Documentation | ||
| - [Nakamoto Upgrade Overview](../nakamoto-upgrade/) |
There was a problem hiding this comment.
The link to the Nakamoto Upgrade Overview appears to be incorrect. From the current location (docs/learn/block-production/), the path ../nakamoto-upgrade/ would point to docs/learn/nakamoto-upgrade/ which doesn't exist. The correct link should be ../../reference/nakamoto-upgrade/ since the nakamoto-upgrade directory is located in docs/reference/.
| - [Nakamoto Upgrade Overview](../nakamoto-upgrade/) | |
| - [Nakamoto Upgrade Overview](../../reference/nakamoto-upgrade/) |
|
|
||
| ### sBTC Status (January 2026) | ||
|
|
||
| **Deposits**: Live since December 17, 2024 |
There was a problem hiding this comment.
The deposit date is inconsistent with other documentation. The file docs/learn/sbtc/sbtc-faq.md states "sBTC deposits first went live on December 16, 2024" (line 82), but this document states "December 17, 2024". Please verify which date is correct and update both files to be consistent.
| ### Satoshi Upgrades (2025-2026) | ||
|
|
||
| Research is ongoing into: | ||
| - **Dual Stacking**: BTC and STX staking for enhanced yield (launched July 2025) |
There was a problem hiding this comment.
The Dual Stacking launch date is inconsistent with other documentation. The file docs/learn/dual-stacking/faq.md states "Dual Stacking launches November 2025" (line 39), but this document states "launched July 2025". Please verify which date is correct and update both files to be consistent.
1 participant
Expanded on the concept of Bitcoin finality in Stacks, detailing its implications, mechanisms, and recent upgrades. Added sections on transaction types, security implications, and future developments post-Nakamoto upgrade.
Description
Describe the changes that were made in this pull request. When possible start with the motivations behind the change.