docs: Add Clarinet Configuration Guide #549
Open
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.
Here is the Pull Request content filled out for your Bonus Contribution.
You can copy and paste this directly into the PR description on GitHub.
Description
As a Stacks developer, I need clear and comprehensive documentation regarding the architectural shift to 24-word mnemonics in Clarinet so that I can configure my deployment environments securely and avoid confusing "bip39 errors" during upgrades.
This pull request introduces a new documentation module: "The Configuration Architecture of Clarinet," broken down into three focused guides.
Clarinet v2.15.0+ enforces 24-word mnemonics, formally deprecating raw private keys and 12-word phrases. This shift has created friction for developers migrating from legacy setups or other ecosystems (like Ethereum). The current documentation lacks a deep technical explanation of why this change occurred (HD derivation requirements for Simnet) and how to migrate securely.
Added three new extensive Markdown files to the documentation structure:
01-cryptographic-architecture.md: Explains the theoretical move to HD wallets, Simnet actor derivation, and 256-bit entropy.02-clarinet-configuration-guide.md: A practical reference forsettings.toml, including valid vs. invalid configuration patterns and troubleshooting for "bip39 errors."03-opsec-and-migration-workflows.md: Step-by-step guides for migrating from 12-to-24 words and handling secrets in CI/CD pipelines (GitHub Actions).It serves as a definitive resource for debugging deployment configuration errors. It reduces support tickets regarding "bip39 errors" and promotes better OpSec by documenting the
encrypted_mnemonicfeature and proper CI/CD injection methods.stacks-coresecurity standards.Error: bip39 errorcan consult02-clarinet-configuration-guide.mdto identify that their 12-word phrase is the cause.Type of Change
Does this introduce a breaking change?
No. This is a documentation-only update. It clarifies existing breaking changes in the Clarinet CLI tool but does not alter the code itself.
Are documentation updates required?
01-cryptographic-architecture.md,02-clarinet-configuration-guide.md, and03-opsec-and-migration-workflows.md.Testing information
Checklist
npm run testpasses (N/A)