docs: add security and best practices guide (modular assembly) - #1166
Merged
Conversation
Add docs/guides/security-best-practices.mdx, a how-to guide for DApp developers covering the operational and design-level security decisions not in the Compact language reference: threat model, viewing-key protection, derived-identity authentication over ownPublicKey(), access control, secret-key lifecycle, block-time deadlines, replay prevention, anonymity sets, and front-running mitigation. Register the new route in packages/tests/pipelines-urls.json. All Compact snippets compiled (compiler 0.31.1) and load-bearing behaviors executed against compact-runtime 0.16.0; viewing-key and on-chain visibility claims verified against ledger, indexer, and wallet source.
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Summary
Errors per inputErrors in docs/guides/security-best-practices.mdx
Redirects per inputRedirects in docs/guides/security-best-practices.mdx |
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
🚀 Preview Deployment✅ Deployment Ready 🔗 Preview URL: https://pr-1166-midnight-docs.vercel.app 📝 Latest commit: This preview updates automatically when you push new commits to this PR. |
Restructure docs/guides/security-best-practices.mdx into a task-oriented how-to: introduction, prerequisites, and four stepped procedures (authenticate a caller, restrict a circuit to a group, enforce a deadline, prevent replay), each ending in a verification step that runs an actual test proving the mitigation holds. Keep the threat-model table, viewing-key guidance, and pre-deployment checklist. Every verification test was executed with Vitest against compact-runtime 0.16.0 (4 files, 8 tests passing); every Compact snippet compiles with compiler 0.31.1.
oduameh
changed the title
…oving Add four sections to the security how-to: a "Validate inputs and arithmetic" procedure (Compact traps subtraction underflow and widens addition to prevent silent overflow), a "Let owners rotate a key" recovery procedure, guidance on designing for durable and bounded state (persistent vs transient hashes, unbounded Set/Map growth), and guidance on proving without leaking private data (the proof server sees your private witness inputs, so local proving keeps them on your machine). Expand the pre-deployment checklist accordingly. All new verification tests executed with Vitest against compact-runtime 0.16.0 (13 tests passing total); every snippet compiles with compiler 0.31.1. Viewing-key and proving-trust claims verified by source inspection of midnight-ledger, midnight-js, and the connector API.
nstanford5
requested changes
Jul 31, 2026
Rebuild the guide on the Red Hat modular documentation model: one monolith assembly composed of typed modules, each marked with a _mod-docs-content-type comment. Four concept modules explain threats and mechanisms, six procedure modules give numbered steps with a Verification section that runs a real test, and five reference modules provide lookup tables. Drop the Step component in favor of plain numbered procedure steps. Content and verification are unchanged from the prior pass: all Compact snippets compile with compiler 0.31.1, and the 13 Vitest tests still pass against compact-runtime 0.16.0.
oduameh
changed the title
Correctness fixes from review (nstanford5): - Clarify that disclose() does not publish a value on its own; a value becomes public only when it crosses a public position (ledger write, exported-circuit return, or contract-to-contract call). Update the on-chain visibility row and add a note. - Show that a secret can be supplied as a circuit argument (private by default), not only via a witness; witness != private state. Add a verified argument variant. - State the correct reason disclose() is required (writing a private value to a public position), not merely that the value is witness-derived. Also rewrite passive-voice, second-person, and weak-word constructions to active voice: 0 Vale errors.
nstanford5
approved these changes
Aug 4, 2026
Olanetsoft
approved these changes
Aug 4, 2026
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
3 participants
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.
No description provided.