docs: README polish before v0.2.0 - #118
Merged
Merged
Conversation
Three improvements ahead of cutting v0.2.0:
1) Header rewrite — lead with value prop. The opening line now names
the use case ("Write deterministic Go tests for upcoming Bitcoin
soft forks…") and a new "Why this exists" paragraph names the
pain point: stock Core doesn't know the new opcodes, Inquisition
does, this library wraps either. Features list reordered so
soft-fork support and time-warp lead, then everyday wallet/tx
features.
2) Soft-fork section reorder — lead with the helpers, not the manual
loop. The first snippet now shows the canonical
SupportsBIP + MineUntilActiveBIP pattern that downstream consumers
should copy. ListDeployments and WarpTime get their own short
examples. The manual VBParams + DeploymentStatus polling loop is
demoted to an "Underneath" subsection so devs don't copy the
harder pattern by accident. Worked-example links promoted to a
visible bulleted list.
3) Troubleshooting expanded with the friction surfaced during Phase 6:
- macOS ulimit -n 4096 (FD exhaustion is the most common failure)
- Variant() returning Unknown
- generatetoaddress "time-too-old" from uint32 block-timestamp cap
- Inquisition's strict 3-field -vbparams + BIP54 coinbase rules
- BIP9 LOCKED_IN-before-FAILED evaluation order, with the
-blockversion=0x20000000 workaround
No code changes; ai-check green.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
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
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
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.
Summary
Three small README improvements before tagging v0.2.0. No code changes.
1. Header / value prop
Opening line now names the use case ("Write deterministic Go tests for upcoming Bitcoin soft forks…") and a new Why this exists paragraph explains the pain point (stock Core doesn't know the new opcodes, Inquisition does, this library wraps either). Features list reordered so soft-fork + time-warp lead, then everyday wallet/tx features.
2. Soft-fork section reorder
Now leads with the typed helpers (
SupportsBIP+MineUntilActiveBIP) that consumers should copy, not the manualfor status != Active { rt.Warp(144) }polling loop. The polling loop demoted to an "Underneath" subsection.ListDeploymentsandWarpTimeget their own short snippets. Worked-example links promoted to a visible bulleted list.3. Troubleshooting expanded
Adds the friction we actually surfaced during Phase 6 development:
ulimit -n 4096(most common failure mode)Variant()returningUnknowngeneratetoaddress"time-too-old" from the uint32 block-timestamp cap (year 2106)-vbparams+ BIP54 coinbase rules-blockversion=0x20000000workaroundTest plan
make ai-checkgreen.🤖 Generated with Claude Code