Revise README for Stacks with detailed features and resources #551
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.
Description
User story
As a new or returning Stacks developer, I want a clear, up-to-date overview of Stacks’ capabilities, upgrades, and ecosystem so that I can quickly understand what Stacks offers today and how to build on it with confidence.
This pull request modernizes the Stacks README to reflect the significant protocol, ecosystem, and developer experience changes that have occurred since the early Stacks releases.
The existing README was written several years ago and no longer accurately represents the current state of the Stacks blockchain. Since then, major developments such as sBTC, the Nakamoto upgrade, Clarity language advancements, and subnet-based scaling have been introduced.
Updating the README improves:
First-time developer onboarding
Accuracy of protocol representation
Discoverability of current documentation and tooling
Expanded the introduction to clearly describe Stacks as a Bitcoin-settled smart contract layer
Updated and clarified Stacks’ core features and design principles
Added sections covering:
sBTC and Bitcoin programmability
The Nakamoto upgrade and Bitcoin finality
Clarity language evolution
Subnets as a scaling solution
Refreshed links to current documentation, tooling, and ecosystem resources
Improved structure and readability for both new and experienced developers
Developers get a clearer understanding of:
How Bitcoin integrates with Stacks today
Which features are production-ready
Where to find accurate and current resources
Reduces confusion caused by outdated references
Improves onboarding speed and confidence for developers evaluating Stacks
No application logic or APIs are affected.
Stacks documentation: https://docs.stacks.co/
sBTC overview: https://stacks.co/sbtc
Stacks Improvement Proposals (SIPs): https://github.com/stacksgov/sips
Clarity documentation: https://book.clarity-lang.org/
No related issue number; this PR addresses documentation freshness and clarity.
Use case:
A developer visiting the repository README should be able to:
Understand what Stacks is in under 5 minutes
Identify how Bitcoin is used (settlement, sBTC, PoX)
Locate the correct documentation to start building
Acceptance criteria
README accurately reflects current Stacks architecture
All referenced links are valid and point to maintained resources
No outdated protocol claims remain
Content is readable without prior Stacks knowledge
No code samples included, as this PR is documentation-only.