Skip to content

Conversation

@aabxtract
Copy link

Description

User story

As a developer or Bitcoin-native user evaluating Stacks, I want a clear and up-to-date explanation of the role of the STX token so that I can understand how Stacks remains decentralized in the sBTC and Nakamoto era without confusing STX for an application-level currency.

This pull request updates the STX README to reflect how STX is used today, following the Nakamoto upgrade and the rollout of sBTC.

  1. Motivation for change

The existing README explains why STX exists, but it reflects an earlier phase of the network where STX was more visible at the application layer.

Since then:

sBTC enables BTC-native application usage

Users can interact with apps primarily in BTC

STX has shifted toward an infrastructure and security role

Without an update, readers may incorrectly assume STX is intended to compete with BTC or act as the dominant ecosystem currency.

  1. What was changed

Rewrote the README to reflect the current role of STX in the ecosystem

Clarified that STX:

Secures decentralized block production

Secures the sBTC peg via signer incentives

Coordinates long-term network security through Stacking

Explicitly distinguished application-level usage (BTC / sBTC) from protocol-level incentives (STX)

Improved structure, readability, and neutrality for Bitcoin-native audiences

Updated links and references for clarity and relevance

  1. How does this impact application developers

Reduces confusion about whether apps should be built around STX or BTC

Helps developers understand:

When STX is required (protocol/security layer)

When BTC/sBTC should be used (application layer)

Improves onboarding for Bitcoin-native developers evaluating Stacks

No APIs, contracts, or runtime behavior are affected.

  1. Link to relevant issues and documentation

Stacks whitepaper: https://stacks.co/stacks.pdf

sBTC overview: https://stacks.co/sbtc

Bitcoin L2 trilemma discussion: https://x.com/muneeb/status/1717542872545628394

Related FAQ: https://github.com/stacks-network/stacks/blob/master/stacks-l2.md

No related issue; this PR addresses documentation accuracy and clarity.

  1. Examples of use cases and acceptance criteria

Use case

A developer reading the README should be able to:

Understand why STX exists without assuming it is a user-facing currency

See how BTC remains the economic center of the ecosystem

Understand the decentralization tradeoffs involved

Acceptance criteria

README accurately reflects post-sBTC, post-Nakamoto architecture

No outdated assumptions about STX being required for app usage

Clear separation between protocol incentives and application economics

Language remains neutral and Bitcoin-aligned

No code samples included (documentation-only change).

Type of Change

New feature

Bug fix

API reference / documentation update

Other

Does this introduce a breaking change?

No.
This PR updates documentation only and does not change any APIs, protocol behavior, or application logic.

Are documentation updates required?

Link to documentation updates:
This PR is the documentation update.

Testing information

Is testing required for this change?

No (documentation-only change)

Affected code paths

None

Things to watch out for when reviewing

Accuracy of protocol descriptions

Neutrality of language for Bitcoin-native readers

Correctness of referenced links

Checklist

Code is commented where needed (N/A — documentation)

Unit test coverage for new or modified code paths (N/A)

npm run test passes (N/A)

Changelog is updated (not applicable for docs-only change)

Tag 1 of @person1 or @Person2

Expanded the explanation of the STX token's role in Stacks, detailing its necessity for decentralization, incentives for sequencers and validators, and its relationship with BTC and sBTC.
@CLAassistant
Copy link

CLA assistant check
Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
You have signed the CLA already but the status is still pending? Let us recheck it.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants