Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -101,7 +101,7 @@ const test = testWithStacks({

- [`CONTRIBUTING.md`](CONTRIBUTING.md) — dev workflow, changesets, commit conventions, releasing
- [`docs/understanding-playstacks.md`](docs/understanding-playstacks.md) — how it works, architecture, why it's easy
- [`docs/playstacks.md`](docs/playstacks.md) — full technical spec and roadmap
- [`docs/playstacks.md`](docs/playstacks.md) — full technical spec
- [`examples/zest/`](examples/zest/) — Zest Protocol supply + withdraw (mainnet)
- [`examples/satoshai/`](examples/satoshai/) — SatoshAI login flow (mainnet)
- [`apps/test-dapp/`](apps/test-dapp/) — self-contained test dApp exercising all wallet methods
Expand Down
100 changes: 2 additions & 98 deletions docs/playstacks.md
Original file line number Diff line number Diff line change
Expand Up @@ -129,8 +129,8 @@ test('shows error when user rejects transaction', async ({ page, stacks }) => {
| `stx_signMessage` | Sign plaintext message | ✅ v0.2 |
| `stx_signStructuredMessage` | Sign typed/structured message (SIP-018) | ✅ v0.2 |
| `stx_signTransaction` | Sign raw transaction hex | ✅ v0.2 |
| `stx_deployContract` | Sign + broadcast contract deployment | v0.3 |
| `signPsbt` | Bitcoin PSBT signing | v0.5 |
| `stx_deployContract` | Sign + broadcast contract deployment | [planned](https://github.com/satoshai-dev/playstacks/issues/2) |
| `signPsbt` | Bitcoin PSBT signing | [planned](https://github.com/satoshai-dev/playstacks/issues/7) |

### Wallet compatibility

Expand Down Expand Up @@ -351,99 +351,3 @@ Showcases against real production dApps. These prove Playstacks works in the wil

- **`examples/zest/`** — Zest Protocol lending flow on mainnet (supply + withdraw STX, on-chain confirmation)
- **`examples/satoshai/`** — SatoshAI login flow on mainnet (connect → sign auth message → terminal access)

---

## Roadmap

### v0.1 — MVP ✅

Core library with full E2E flow working on mainnet against Zest Protocol.

- [x] Project scaffolding (pnpm, TypeScript, tsup, vitest)
- [x] Config + network resolution (mainnet / testnet / devnet / custom URL)
- [x] Key manager: private key hex → STX address + public key
- [x] Mnemonic / seed phrase support via `@stacks/wallet-sdk`
- [x] Multiple account derivation from a single mnemonic (`accountIndex`)
- [x] Fee estimator with multiplier + max cap
- [x] Mock provider: Node-side handler + browser-side injection script
- [x] Wallet compatibility: `@stacks/connect` v8, Xverse (StacksProvider + XverseProviders)
- [x] Playwright fixtures: `testWithStacks()`
- [x] Supported methods: `getAddresses`, `wallet_connect`, `stx_callContract`, `stx_transferStx`
- [x] Post-conditions support in contract calls
- [x] `waitForTx()` — poll for tx confirmation with configurable timeout
- [x] `callReadOnly()` — read contract state for on-chain assertions
- [x] `getBalance()`, `getNonce()` — account state helpers
- [x] `wallet.rejectNext()` — test wallet rejection flows
- [x] `wallet.lastTxId()` — access last broadcast transaction ID
- [x] Unit test suite (29 tests, expanded to 42 in v0.2)
- [x] E2E reference: Zest Protocol supply flow on mainnet

**Deliverable**: Working package. Full E2E tests for Zest Protocol — connect wallet, supply STX, confirm on-chain.

### v0.2 — Message & Transaction Signing ✅

Pure signing methods — no broadcasting, no devnet needed. Also ships the test dApp scaffold.

- [x] `stx_signMessage` — sign plaintext messages (Stacks message hash prefix + RSV signature)
- [x] `stx_signStructuredMessage` — sign SIP-018 structured messages
- [x] `stx_signTransaction` — sign arbitrary transaction hex
- [x] Xverse 3-address format in `getAddresses` (BTC payment, BTC ordinals, STX)
- [x] `rejectNext()` skips read-only methods so rejection flag isn't consumed by background polling
- [x] Message hash helper (`message-hash.ts`) — Stacks plaintext message hashing with Bitcoin varint encoding
- [x] Test dApp (`apps/test-dapp/`) — Vite + vanilla TypeScript with pages for connect and all three signing methods
- [x] E2E specs for connect, sign-message, sign-structured, sign-transaction against the test dApp
- [x] 13 new unit tests (message hash + all 3 signing methods), bringing total to 42
- [x] Real-world example: `examples/satoshai/` — full login flow against app.satoshai.io
- [x] Real-world example: `examples/zest/` — withdraw test to complement supply test
- [x] Re-export `cvToHex` from `@stacks/transactions`

**Deliverable**: Full Stacks signing coverage. Test dApp running. 42 unit tests. Two real-world examples working.

### v0.3 — Deploy & Nonce Management

Contract deployment support and automatic nonce tracking for sequential transactions.

- `stx_deployContract` — sign + broadcast Clarity contract deployments
- Automatic nonce management — sequential transactions in a single test get incrementing nonces without waiting for confirmation
- Test dApp deploy page + E2E spec against Clarinet devnet
- E2E spec: send 3 sequential txs in one test, all confirm on devnet
- Devnet CI setup — Clarinet devnet in GitHub Actions for automated E2E runs

**Deliverable**: Deploy + multi-tx flows work. Devnet E2E pipeline running in CI.

### v0.4 — Multi-Account

Test multi-user scenarios within a single test.

- Account switching mid-test — change the active wallet identity without reconnecting
- Multi-account fixtures — configure multiple wallets from a single mnemonic
- Test dApp multi-account page + E2E spec showing two users interacting with the same contract
- Example scenario: user A supplies STX, user B borrows against it

**Deliverable**: Multi-user E2E testing. Two-sided dApp flows covered.

### v0.5 — Bitcoin / sBTC Support

Complete Bitcoin L1 + Stacks L2 coverage.

- `signPsbt` — Bitcoin PSBT signing via `bitcoinjs-lib`
- sBTC deposit / withdraw flow support
- Bitcoin address derivation (segwit, taproot) from the same key
- Integration with Bitcoin regtest / testnet4
- Helpers for sBTC bridge interactions

**Deliverable**: Test flows that span both Bitcoin and Stacks (sBTC deposits, taproot vaults).

### v1.0 — Stable Release

Ship it.

- API stabilization and breaking change review
- Docs site (`apps/docs`) — API reference, getting started guide, examples
- CI/CD: GitHub Actions for lint, typecheck, unit tests, publish
- npm publish as `playstacks`
- Performance: connection pooling, parallel test support
- Community: announce on Stacks Discord, forum post, Twitter thread

**Deliverable**: Published package on npm. Docs site live. Production users.