docs: Add Clarinet Configuration Guide#549
Open
jadonamite wants to merge 1 commit intostacks-network:masterfrom
Open
docs: Add Clarinet Configuration Guide#549jadonamite wants to merge 1 commit intostacks-network:masterfrom
jadonamite wants to merge 1 commit intostacks-network:masterfrom
Conversation
This document provides a comprehensive guide on configuring Clarinet, including setup, troubleshooting, and security practices for project metadata and execution credentials.
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
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)