Implement Bitcoin Shield Privacy Pool#1
Open
philip-hue wants to merge 8 commits into
Open
Conversation
…d constants - Added state variables: `merkle-root`, `next-leaf-index`, `contract-paused`, and `total-deposited`. - Defined SIP-010 trait for fungible token compatibility. - Introduced error constants for robust error handling. - Configured privacy pool parameters, including Merkle tree height and deposit limits. - Established contract ownership and default values for critical constants.
- Implemented `deposit-records` map to store deposit details, including leaf index, block height, depositor, and amount. - Added `nullifier-status` map to track nullifier usage and withdrawal details. - Introduced `merkle-nodes` map to store Merkle tree node hashes by level and index. - Created private helper functions for input validation: - `is-valid-token` to validate fungible token instances. - `is-valid-commitment` to ensure commitments are non-zero and within valid length. - `is-valid-nullifier` to validate nullifiers with similar checks.
…pers - Implemented `is-valid-proof` to validate zero-knowledge proof structures. - Added `is-contract-owner` to verify contract ownership for restricted actions. - Created `toggle-contract-pause` to enable pausing and resuming contract operations. - Developed internal helper functions for Merkle tree management: - `combine-hashes` to compute hash of two nodes. - `is-valid-node-hash?` to validate non-zero node hashes. - `get-merkle-node` to retrieve a node hash from the Merkle tree. - `set-merkle-node` to store a node hash in the Merkle tree.
- Implemented `update-merkle-parent` to compute and set parent node hashes in the Merkle tree based on sibling relationships. - Added `verify-proof-step` to validate individual steps in a Merkle proof by combining hashes and checking validity. - Developed `verify-merkle-proof` to validate a complete Merkle proof against a given root, ensuring the integrity of the proof.
…state management - Added `make-deposit` function to handle user deposits securely: - Validates token, commitment, and deposit amount. - Ensures the contract is not paused and the Merkle tree has capacity. - Transfers tokens from the user to the contract with error handling. - Updates the Merkle tree: - Sets the leaf node with the user's commitment. - Updates parent nodes across multiple levels for consistency. - Records deposit details in the `deposit-records` map, including: - Commitment, leaf index, block height, depositor, and amount. - Updates global state variables: - Increments `next-leaf-index`. - Updates `total-deposited` with the deposit amount.
…d token transfer - Added `process-withdrawal` function to handle secure withdrawals: - Validates inputs, including token, nullifier, proof, and withdrawal amount. - Ensures the contract is not paused and the nullifier is unused. - Verifies the Merkle proof to confirm the withdrawal's validity. - Marks the nullifier as used and records withdrawal details in `nullifier-status` map. - Transfers the specified token amount to the recipient with error handling.
…t management - Implemented `admin-recovery` function: - Allows the contract owner to recover tokens in emergency situations. - Validates token, recipient, and recovery amount. - Transfers tokens securely with error handling. - Added read-only functions for contract state inspection: - `get-contract-status`: Returns contract pause status, total deposited amount, and next leaf index. - `get-current-root`: Retrieves the current Merkle root. - `check-nullifier-status`: Checks the status of a given nullifier. - `get-deposit-details`: Fetches deposit details for a specific commitment. - Initialized contract state variables in the `begin` block: - Sets default values for `merkle-root`, `next-leaf-index`, `contract-paused`, and `total-deposited`.
…cy pool - Detailed overview of Bitcoin Shield's purpose, features, and architecture. - Explained privacy-preserving mechanisms, including ZK-SNARK withdrawals and Merkle tree-based commitments. - Provided technical specifications, including cryptographic components and performance characteristics. - Documented deposit and withdrawal flows with example Clarity code. - Outlined security model, trust assumptions, and protection mechanisms. - Included error reference table for troubleshooting common issues. - Added maintenance and administration guidelines, including emergency procedures and upgrade steps. - Addressed frequently asked questions about auditing, admin controls, fees, and Merkle tree capacity. - Contributing section with steps for feature development and submission requirements.
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.
Overview
This PR introduces Bitcoin Shield - a zero-knowledge privacy pool implementation for the Stacks blockchain that enables confidential transactions while maintaining Bitcoin-level security guarantees. The implementation combines Merkle tree commitments with zk-SNARK proofs to separate transaction origins from destinations.
Key Features
Core Privacy Infrastructure
Technical Implementation
Safety Features
Documentation
Notes for Reviewers
process-withdrawalproof verification logicnullifier-status)Security Warning: This implementation contains privileged functions (pause/recovery) that should be removed in production deployments using multi-sig controls.