Skip to content

Conversation

@jadonamite
Copy link

@jadonamite jadonamite commented Dec 30, 2025

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.

  1. Motivation for change:
    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.
  2. What was changed:
    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 for settings.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).
  1. How does this impact application developers:
    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_mnemonic feature and proper CI/CD injection methods.
  2. Link to relevant issues and documentation:
  • Addresses confusion around "bip39 error" in Clarinet v2.15.0+.
  • Relates to stacks-core security standards.
  1. Provide examples of use cases with code samples:
  • Troubleshooting: A developer encountering Error: bip39 error can consult 02-clarinet-configuration-guide.md to identify that their 12-word phrase is the cause.
  • Configuration Reference: The docs provide copy-pasteable valid TOML:
[accounts.deployer]
# 24-word mnemonic is MANDATORY
mnemonic = "abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon art"
derivation = "m/44'/5757'/0'/0/0"

Type of Change

  • API reference/documentation update

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?

  • Link to documentation updates: This PR is the documentation update. Added 01-cryptographic-architecture.md, 02-clarinet-configuration-guide.md, and 03-opsec-and-migration-workflows.md.

Testing information

  1. Is testing required for this change? No code changes were made.
  2. If it’s a bug fix, list steps to reproduce the bug: N/A.
  3. Briefly mention affected code paths: None.
  4. List other affected projects if possible: None.
  5. Things to watch out for when testing: Verify that Markdown tables and code blocks render correctly in the GitHub UI.

Checklist

  • Code is commented where needed (N/A)
  • Unit test coverage for new or modified code paths (N/A)
  • npm run test passes (N/A)
  • Changelog is updated
  • Tag 1 of @maintainer

This document provides a comprehensive guide on configuring Clarinet, including setup, troubleshooting, and security practices for project metadata and execution credentials.
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.

1 participant