solvoid 1.2.0 → 1.3.0

package/README.md

@@ -1,312 +1,170 @@
+# SolVoid: Institutional-Grade Privacy Infrastructure for Solana
+
 <div align="center">
-  <br />
-  <pre>
-███████╗ ██████╗ ██╗     ██╗   ██╗ ██████╗ ██╗██████╗ 
-██╔════╝██╔═══██╗██║     ██║   ██║██╔═══██╗██║██╔══██╗
-███████╗██║   ██║██║     ██║   ██║██║   ██║██║██║  ██║
-╚════██║██║   ██║██║     ╚██╗ ██╔╝██║   ██║██║██║  ██║
-███████║╚██████╔╝███████╗ ╚████╔╝ ╚██████╔╝██║██████╔╝
-╚══════╝ ╚═════╝ ╚══════╝  ╚═══╝   ╚═════╝ ╚═╝╚═════╝ 
-  </pre>
-
-  <h3><b>SolVoid Protocol: The Enterprise Sovereign Privacy Layer</b></h3>
-  <p><i>Next-Generation Zero-Knowledge Privacy Lifecycle Management (PLM) for the Solana Ecosystem</i></p>
-
-  <p>
-    <a href="https://github.com/brainless3178/SolVoid/actions"><img src="https://img.shields.io/github/actions/workflow/status/brainless3178/SolVoid/privacy.yml?branch=main&style=for-the-badge&logo=github&label=CI/CD%20Pipeline" alt="Build Status"></a>
-    <a href="https://codecov.io/gh/brainless3178/SolVoid"><img src="https://img.shields.io/badge/ZK%20Circuit%20Coverage-98%25-brightgreen?style=for-the-badge&logo=codecov&label=ZK%20Circuit%20Coverage" alt="Code Coverage"></a>
-    <a href="https://github.com/brainless3178/SolVoid/releases"><img src="https://img.shields.io/badge/Production-v1.2.0-blue?style=for-the-badge&logo=github" alt="Version"></a>
-    <a href="./LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow?style=for-the-badge&logo=github" alt="License"></a>
-  </p>
-  <p>
-    <a href="https://solana.com"><img src="https://img.shields.io/badge/Solana-Mainnet--Beta%20Ready-black?style=for-the-badge&logo=solana" alt="Solana Compatibility"></a>
-    <a href="./docs"><img src="https://img.shields.io/badge/Documentation-Stripe--Grade-green?style=for-the-badge&logo=gitbook" alt="Docs Status"></a>
-    <a href="https://github.com/brainless3178/SolVoid/security/advisories"><img src="https://img.shields.io/badge/Security-Cryptographic%20Verified-brightgreen?style=for-the-badge&logo=dependabot" alt="Security Status"></a>
-    <a href="https://discord.gg/solvoid"><img src="https://img.shields.io/badge/Discord-Audit%20Live-5865F2?style=for-the-badge&logo=discord&logoColor=white" alt="Discord"></a>
-  </p>
-
-  <p align="center">
-    <strong>SolVoid</strong> is a high-performance, non-custodial privacy protocol that provides a decentralized identity-abstraction layer on the Solana blockchain.
-    <br />
-    It utilizes <b>Groth16 Zero-Knowledge SNARKs</b> and <b>Poseidon-3 Hashing</b> to deliver institutional-grade anonymity at sub-second speeds.
-  </p>
+  <img src="./solvoid_assets.png" alt="SolVoid Architecture Infographic" width="800">
 </div>
 
----
-
-## 🔱 Executive Vision
-
-In the landscape of hyper-transparent blockchain architectures, **SolVoid** represents the critical transition from "Public-by-Default" to "Private-by-Choice." The protocol is engineered to neutralize the risks of on-chain telemetry, MEV-sandwich attacks, and transaction graph heuristics. By decoupling asset ownership from transaction history, SolVoid empowers individuals and institutions to execute sensitive financial maneuvers with the speed of Solana and the secrecy of Zero-Knowledge.
-
----
-
-## 🧭 Master Table of Contents
-
-1.  [Core Value Propositions](#-core-value-propositions)
-2.  [Exhaustive Feature Matrix](#-exhaustive-feature-matrix)
-3.  [Deep-Dive Architecture](#-deep-dive-architecture)
-    -   [ZK-SNARK Circuit Topology](#zk-snark-circuit-topology)
-    -   [The Poseidon-3 Hash Standard](#the-poseidon-3-hash-standard)
-    -   [On-Chain State Management](#on-chain-state-management)
-4.  [Privacy Ghost Score Diagnostics](#-privacy-ghost-score-diagnostics)
-5.  [Command-Line Interface (CLI) Master Reference](#-command-line-interface-cli-master-reference)
-6.  [Shadow Relayer Infrastructure](#-shadow-relayer-infrastructure)
-7.  [Operational Setup & Lifecycle](#-operational-setup--lifecycle)
-8.  [Security, Validation & Testing](#-security-validation--testing)
-    -   [The Shell Script Index](#the-shell-script-index)
-9.  [Master Strategic Roadmap](#-master-strategic-roadmap)
-10. [Repository Directory Blueprint](#-repository-directory-blueprint)
-11. [Governance & Strategic Contributions](#-governance--strategic-contributions)
-12. [Glossary of Cryptographic Terms](#-glossary-of-cryptographic-terms)
-
----
-
-## 💎 Core Value Propositions
-
--   **Unlinkable Anonymity**: Complete decoupling of funding sources from destination wallets via Merkle-tree based shielding.
--   **Hardware-Accelerated Privacy**: Optimized for Solana’s runtime, achieving verification costs below 200,000 Compute Units.
--   **Zero-Knowledge Integrity**: Pure cryptographic proof of ownership without revealing the source deposit (Secret/Nullifier).
--   **Anti-Heuristic Engine**: Native defense against transaction timing and volume analysis via the Ghost Scoring diagnostics.
-
----
-
-## ✨ Exhaustive Feature Matrix
+[![Protocol Status](https://img.shields.io/badge/Protocol-Beta-cyan.svg)](https://solvoid.io)
+[![License: MIT](https://img.shields.io/badge/License-MIT-gray.svg)](https://opensource.org/licenses/MIT)
+[![Security: ZK-Optimized](https://img.shields.io/badge/Security-ZK--Optimized-blue.svg)](./ZK_REFERENCE.md)
 
-| Domain | Capability | Technical Detail | Status |
-| :--- | :--- | :--- | :---: |
-| **Shielding** | **ZK-Commitment Pool** | Fixed-depth (20) Merkle Tree supporting 1M+ deposits. | ✅ |
-| **Withdrawal** | **Groth16 Verification** | Sub-600ms proof generation on-device via WASM/SDK. | ✅ |
-| **Diagnostics** | **Privacy Ghost Score** | 4-pillar metadata audit (Linkage, Temporal, Volume, Entropy). | ✅ |
-| **Infrastructure**| **Shadow Relayer 2.0** | Gasless & IP-anonymous transaction broadcasting. | ✅ |
-| **Emergency** | **Atomic Rescue** | <2s scripted migration for compromised private keys. | ✅ |
-| **Identity** | **ZK-Signed Badges** | Portable personal privacy credentials without revealing the URI. | ✅ |
-| **Scanners** | **Ultimate Privacy Scan** | Resilience suite using 40+ RPCs with IP-rotation. | ✅ |
+SolVoid is a high-performance, non-custodial privacy protocol designed for the Solana ecosystem. By leveraging **Groth16 Zero-Knowledge Proofs** and circuit-optimized **Poseidon-3 hashing**, SolVoid enables cryptographically unlinkable asset transfers and identity obfuscation with sub-second latency.
 
 ---
 
-## 🧬 Deep-Dive Architecture
+## 🏛 Technical Architecture
 
-SolVoid is not a single tool, but a synergistic ecosystem of cryptographic primitives and on-chain state managers.
+SolVoid orchestrates a multi-layered privacy lifecycle (PLM) that decouples on-chain identities from their transaction history while maintaining full protocol verifiability.
 
+### Operational Data Flow
 ```mermaid
 graph TD
-    subgraph "Local Secure Environment (WASM)"
-        A[User Input] -->|Secret Generation| B(Poseidon Hash)
-        B -->|Commitment| C{Circom Prover}
-        C -->|Groth16 Proof| D[Signed Payload]
-    end
-
-    subgraph "Distributed Networking"
-        D -->|Anonymous Broadcast| E[Shadow Relayer Node]
-        E -->|Transaction Forwarding| F[Solana Mainnet]
-    end
-
-    subgraph "Solana Smart Contract (Anchor)"
-        F --> G[Merkle Tree State]
-        G -->|Root Validation| H[Verifier Module]
-        H -->|Nullifier Check| I[Fund Release]
-    end
-
-    I -->|Private Funds| J[New Stealth Address]
+    A[Identity Layer] -->|Shielding Transaction| B(ZK-Prover Engine)
+    B -->|Groth16 Witness| C{SolVoid Vault}
+    C -->|Commitment Stored| D[Merkle Tree State]
+    E[Anonymity Recovery] -->|Withdrawal Request| F(Shadow Relayer)
+    F -->|Onion Routing| G(On-chain Verifier)
+    G -->|Proof Validated| H[Fresh Destination Address]
+    D -.->|Membership Proof| G
 ```
 
-### ZK-SNARK Circuit Topology
-Our circuits are written in **Circom 2.1**, employing a Groth16 proving scheme on the **BN254** elliptic curve. This ensures maximum compatibility with Solana's forthcoming ZK precompiles while maintaining current operational efficiency through our custom Rust verifier.
-
-### The Poseidon-3 Hash Standard
-We use **Poseidon-3**, a Sponge-construction hash function optimized specifically for R1CS (Rank-1 Constraint Systems). 
--   **Efficiency**: Reduces constraints from ~20,000 (Keccak) to **~210** per field element.
--   **Security**: Provides 128-bit security against all known algebraic attacks.
-
-### On-Chain State Management
-The SolVoid program manages a sliding window of **100 Merkle Roots**. This allows users to generate proofs against slightly older state, mitigating the risk of "Root Drift" where a proof becomes invalid because someone else deposited simultaneously.
-
 ---
 
-## 👻 Privacy Ghost Score Diagnostics
-
-The **Ghost Score** is the heartbeat of the SolVoid ecosystem. It provides an objective numerical rank (0-100) of your wallet's anonymity.
+## � Project Lifecycle & Orchestration
 
--   **Linkage Score**: Identifies direct and N-hop paths to centralized exchanges (CEX) or known identifiers.
--   **Temporal Analysis**: Detects "human" rhythms in transaction timing (e.g., repeating daily patterns).
--   **Volume Profiling**: Flagging of round-number deposits (e.g., exactly 10.0 SOL) which are easier to track.
+### 1. Environment & Deployment Hub
+The foundation for building, testing, and deploying the SolVoid protocol.
 
 ```bash
-# Execute deep-scan and generate shareable ZK-signed badge
-solvoid-scan ghost <MY_ADDRESS> --badge --share --json
-```
-
----
-
-## 🔧 Command-Line Interface (CLI) Master Reference
-
-The `solvoid-scan` CLI is a production-grade binary for privacy management.
-
-#### Core Operational Commands
--   `solvoid-scan shield <amount>`: The primary ingress. Converts native SOL to a ZK-Commitment.
--   `solvoid-scan withdraw <secret> <nullifier> <recipient> <amount>`: The primary egress. Reclaims funds anonymously.
--   `solvoid-scan ghost <address>`: Generates the Ghost Score report and visual terminal art.
--   `solvoid-scan protect <address>`: Active monitoring mode for identifying real-time privacy leaks.
--   `solvoid-scan rescue <wallet>`: Atomic "nuke" option for high-speed mitigation of key leaks.
-
-#### Protocol Administration
--   `solvoid-scan admin trigger-emergency <mult> <reason>`: Globally scale protocol fees (1x-10x).
--   `solvoid-scan admin disable-emergency`: Restore baseline fee economics.
--   `solvoid-scan admin pause`: Trigger Circuit Breaker to halt all withdrawals.
--   `solvoid-scan admin resume`: Lift Circuit Breaker and resume protocol operations.
-
-#### Global Flags & Automation
-| Flag | Description | Default |
-| :--- | :--- | :--- |
-| `--rpc <URL>` | Override standard Solana RPC endpoints. | Mainnet-Beta |
-| `--program <ID>` | Override the default SolVoid Program ID. | `Fg6Pa...` |
-| `--relayer <URL>` | Target a specific Shadow Relayer instance. | `http://localhost:3000` |
-| `--dry-run` | Perform an atomic simulation without spending gas. | `false` |
-| `--json` | Output all results in raw JSON format for CI/CD. | `false` |
-
----
-
-## 🛰 Shadow Relayer Infrastructure
-
-The **Shadow Relayer** is a critical component for achieving network-level anonymity.
-
-> **TIP**  
-> Use the Relayer to avoid "Gas Linkage." If you fund your new recipient wallet with gas from an exchange, you have nullified your privacy. The Relayer solves this by paying the gas for you and deducting a small bounty from the withdrawal.
+# Repository Initialization
+git clone https://github.com/brainless3178/SolVoid.git
+cd SolVoid
+npm install
 
-### Relayer Endpoints
--   `GET /health`: Node status and network metrics.
--   `POST /register`: Onboarding for new relay nodes.
--   `POST /relay`: The primary submission point for ZK-signed transactions.
--   `POST /encrypt-route`: Prepares multi-hop onion-routed payloads.
+# ZK Cryptographic Pipeline
+# Compiles circuits and generates proving/verification keys
+./scripts/build-zk.sh
 
----
+# On-Chain Program Lifecycle (Anchor)
+anchor build
+anchor deploy --provider.cluster devnet
 
-## 🚀 Operational Setup & Lifecycle
+# Quality Assurance Suite
+npm test               # Execute full test matrix
+npm run lint           # Static code analysis
+npm run dashboard:dev  # Launch local UI environment
+```
 
-### 1. Requirements
-- **Node.js**: v18.0.0+ (Recommended: v20 LTS)
-- **Rust/Cargo**: 1.75.0+
-- **Solana CLI**: Latest Stable
-- **Hardware**: AVX2 support (optional, for faster local proving)
+### 2. CLI Command Specification (`solvoid`)
+The primary interface for protocol interaction, auditing, and emergency response.
 
-### 2. Deployment Flow
+#### **Surgical Shielding (Deposit)**
 ```bash
-# Clone Enterprise Repository
-git clone https://github.com/brainless3178/SolVoid.git
-cd solvoid
-
-# Install Critical Dependencies
-npm install && npm run build
+solvoid shield <amount>
+```
+*   **Args**: `<amount>` (SOL to shield)
+*   **Protocol Action**: Generates `Secret` and `Nullifier` keys and commits hashed state to the Merkle tree.
 
-# Configure Environment
-cp .env.example .env
+#### **Unlinkable Withdrawal**
+```bash
+solvoid withdraw <secret> <nullifier> <recipient> <amount> [options]
 ```
+| Option | Description | Default |
+|:---|:---|:---|
+| `--relayer <url>`| Target Shadow Relayer endpoint | `.env` default |
+| `--rpc <url>`    | Override default Solana RPC | `.env` default |
 
-### 3. Local Ceremony (Optional)
-For highly secure local environments, run a personal MPC ceremony:
+#### **Privacy Ghost Score (Audit)**
 ```bash
-./scripts/run-ceremony.sh
+solvoid ghost <address> [options]
 ```
+| Option | Description |
+|:---|:---|
+| `--badge`      | Generate a ZK-verified Privacy Badge artifact |
+| `--share`      | Generate social metadata for X/Discord platforms |
+| `--verify <p>` | Cryptographically validate an external privacy proof |
+| `--json`       | Return raw audit data for programmatic ingestion |
+
+#### **Atomic Rescue (MEV Protection)**
+```bash
+solvoid rescue <wallet> [options]
+```
+| Option | Description |
+|:---|:---|
+| `--to <addr>`    | Specified recovery destination address |
+| `--auto-generate`| Initialize a fresh, secure remediation wallet |
+| `--jito-bundle`  | Utilize Jito-Solana MEV bundles for atomic execution |
+| `--emergency`    | Priority fee escalation for sub-2s critical rotation |
+| `--dry-run`      | Simulate orchestration without network broadcast |
+| `--monitor`      | Activate real-time post-remediation threat alerts |
+
+#### **Protocol Administration (Emergency Controls)**
+```bash
+solvoid admin <command> [args]
+```
+| Command | Action |
+|:---|:---|
+| `pause`               | Trigger the ZK Circuit Breaker to suspend withdrawals |
+| `resume`              | Reset breaker and resume protocol operations |
+| `trigger-emergency`   | Escalates protocol-wide fee multipliers (x1-x10) |
+| `disable-emergency`   | Resets protocol fees to baseline state |
 
 ---
 
-## 🛡 Security, Validation & Testing
+### 3. SDK Integration Patterns
+A professional integration layer for third-party dApps and services.
 
-SolVoid employs a "Defense in Depth" strategy, validated by a massive suite of specialized shell scripts in `/scripts`.
+```typescript
+import { SolVoidClient } from 'solvoid';
 
-### The Shell Script Index
-| Script | Documentation |
-| :--- | :--- |
-| `./scripts/run-security-tests.sh` | **The Master Suite**: Runs every validation mentioned below. |
-| `./scripts/verify-hash-consistency.sh` | Confirms Poseidon-3 parity across Rust, TS, and Circom logic. |
-| `./scripts/vault-balance-protection.sh` | Simulates "phantom withdrawal" attacks to verify vault safety. |
-| `./scripts/nullifier-validation-test.sh` | Verifies the impossibility of double-spending. |
-| `./scripts/test-emergency-procedures.sh` | Stress-tests the speed and effectiveness of the Atomic Rescue. |
-| `./scripts/arithmetic-safety-test.sh` | Probes for overflows and field-element collisions. |
-| `./scripts/rust-dependency-audit.sh` | Performs a deep audit of the cargo dependency tree for CVEs. |
+// 1. Client Orchestration
+const client = new SolVoidClient(config, wallet);
 
-### Testing Lifecycle
-```bash
-# Run unit tests for SDK and CLI
-npm run test:unit
+// 2. Surgical Shielding
+const { commitmentData } = await client.shield(1.5 * LAMPORTS_PER_SOL);
 
-# Run full integration tests with local validator
-npm run test:integration
+// 3. Privacy Auditing
+const passport = await client.getPassport(address);
+console.log(`Ghost Score: ${passport.overallScore}/100`);
 
-# Execute 100% security validation suite
-./scripts/security-validation.sh
+// 4. Low-level Proof Generation
+const proof = await client.prepareWithdrawal(secret, nullifier, ...);
 ```
 
 ---
 
-## 🗺 Master Strategic Roadmap
-
-### Phase 1: Foundation (Current Status: ✅ COMPLETED)
-- [x] Merkle Tree Core Logic (Depth 20)
-- [x] Poseidon-3 Sponge Construction Hashing
-- [x] Groth16 Proving Engine (Browser & Node)
-- [x] Multi-platform SDK for dApp developers
-
-### Phase 2: Visibility (Current Status: ✅ COMPLETED)
-- [x] Privacy Ghost Scoring Diagnostics
-- [x] Shadow Relayer Alpha Deployment
-- [x] CLI Automation Tools & Binary Releases
-- [x] ZK-Signed Privacy Badges
+### 4. Shadow Relayer API Specification
+Technical endpoints for the decentralized relay network.
 
-### Phase 3: Expansion (Timeline: Q2 2026)
-- [ ] **SPL Token Support**: Shielding for USDC, BONK, and JupSOL.
-- [ ] **Decentralized Relayer Incentives**: Governance-managed relayer rewards.
-- [ ] **On-chain MPC Ceremony**: Official ceremony for Mainnet-Beta Proving Keys.
-- [ ] **Onion Routing**: Layered network anonymity via the Relayer Mesh.
+| Endpoint | Method | Functional Requirement |
+|:---|:---|:---|
+| `/status` | `GET` | Health monitoring & protocol metrics |
+| `/commitments` | `GET` | Multi-hop Merkle state synchronization |
+| `/relay` | `POST` | `transaction` (base64) & `hops` (onion routing depth 1-5) |
 
 ---
 
-## 📂 Repository Directory Blueprint
-
-```text
-.
-├── programs/           # Anchor-based Solana Smart Contracts (Rust)
-├── circuits/           # Circom 2.1 source files & ZK Proving keys
-├── sdk/                # TypeScript SDK for frontend & backend integration
-├── cli/                # Source code for the solvoid-scan binary
-├── relayer/            # Shadow Relayer Node source (Node.js/Express)
-├── dashboard/          # Next.js 15 Web interface
-├── scripts/            # Over 30+ production shell scripts for DevOps/Security
-├── bin/                # Compiled CLI executables
-└── docs/               # Technical Specifications & Manuals
-```
-
----
+## � Key Ecosystem Infrastructure
 
-## 🤝 Governance & Strategic Contributions
-
-We welcome contributions from cryptographers, security researchers, and developers.
-
-1.  **Read** the [Security Policy](./SECURITY.md).
-2.  **Review** our [Contributing Guidelines][contributing].
-3.  **Submit** an issue using the provided templates.
-4.  **Open** a Pull Request against the `develop` branch.
+*   **Groth16 ZK-SNARKs**: High-performance proving implementation on the **BN254 curve**.
+*   **Poseidon-3 Hashing**: Standardized sponge construction for 100% parity across Rust, TS, and Circom.
+*   **Jito-MEV Integration**: Advanced front-running protection for critical asset rotations.
+*   **Data Integrity Enforcement (DIE)**: Zod-powered schema validation at every operational boundary.
+*   **Global Dashboard**: Institutional Next.js interface providing real-time technical telemetry.
 
 ---
 
-## 📚 Glossary of Cryptographic Terms
+## 📖 Project Documentation
 
--   **BN254**: The barreto-naehrig elliptic curve used for SNARKs.
--   **R1CS**: Rank-1 Constraint System; the mathematical representation of our circuits.
--   **Nullifier**: A unique serial number for a deposit, kept secret until withdrawal.
--   **Commitment**: The hash of (Secret + Nullifier + Amount), stored on-chain.
--   **Circuit**: A specialized piece of logic that defines what the ZK proof proves.
+- **Core:** [DOCS.md](DOCS.md) | [ZK_REFERENCE.md](ZK_REFERENCE.md) | [GHOST_REFERENCE.md](GHOST_REFERENCE.md)
+- **Integration:** [SDK_REFERENCE.md](SDK_REFERENCE.md) | [CLI_REFERENCE.md](CLI_REFERENCE.md) | [API_REFERENCE.md](API_REFERENCE.md)
+- **Ops:** [CICD_REFERENCE.md](CICD_REFERENCE.md) | [SYSTEM_STATUS.md](SYSTEM_STATUS.md) | [DEPLOYMENT.md](DEPLOYMENT.md)
 
 ---
 
-<p align="center">
-  <b>Built for the Solana Privacy Hackathon 2026.</b><br />
-  SolVoid is an open-source contribution to the global right to financial anonymity.
-</p>
-
-<div align="center">
-  <a href="#-solvoid-protocol-the-enterprise-sovereign-privacy-layer"><b>↑ BACK TO TOP ↑</b></a>
-</div>
+## 🔒 Security Compliance
+- **Status:** Experimental Beta
+- **Policy:** Refer to [SECURITY.md](SECURITY.md) for disclosure protocols.
 
-[commands-docs]: ./COMMANDS.md
-[contributing]: ./CONTRIBUTING.md
+---
+*Engineering-First. Privacy-Preserving. Solana-Native.*

package/SECURITY.md

@@ -1,39 +1,42 @@
-#  Security Policy
+# Security Standards: Protocol Integrity & Disclosure
 
-## Security Disclosure
+## Vulnerability Disclosure Policy
 
-Privacy is a human right, but software security is a continuous process. If you discover a vulnerability in SolVoid, we ask that you disclose it to us responsibly so we can protect our users.
+The SolVoid project recognizes that protocol security is an ongoing engineering process. In the event of vulnerability identification, we prioritize responsible, coordinated disclosure to ensure the continuous protection of the collective anonymity set.
 
-### Reporting a Vulnerability
-- **Email:** [security@solvoid.io] (Placeholder)
-- **Encryption:** Please use our PGP key (Link placeholder) to encrypt sensitive reports.
-- **Process:** We will acknowledge your report within 48 hours and provide a timeline for a fix. We ask that you do not disclose the vulnerability publicly until we have released a patch.
+### Reporting Methodology
+- **Communication Channel:** [security@solvoid.io] (Contact registry placeholder).
+- **Cryptographic Protection:** Encrypt all sensitive disclosures using the project's PGP identifier (Link placeholder).
+- **Response Protocol:** The engineering team will acknowledge reports within 48 hours and establish a remediation timeline. We request that reporters maintain confidentiality until a verified patch has been deployed across the network.
 
 ---
 
-##  Security Best Practices for Users
-1. **Never share your Secret or Nullifier.** These are the only keys to your anonymous funds. If lost or stolen, your funds are gone.
-2. **Use a Fresh Wallet for Withdrawals.** To maintain privacy, ensure your destination address has no previous on-chain links to your identity.
-3. **Verify the Domain.** Always ensure you are using the official `solvoid.io` dashboard or a verified local build of the SDK/CLI.
-4. **Network Fees.** If not using a relayer, be aware that funding a fresh wallet with SOL for gas can compromise your privacy via timing or source-analysis.
+## Technical Security Best Practices
+
+1. **Primitive Sequestration:** The secret and nullifier keys constitute the sole access vectors for shielded liquidity. Execution of the protocol implies user responsibility for the secure, off-chain storage of these cryptographical primitives.
+2. **Identity Decoupling:** To maintain maximum anonymity, withdrawal destination addresses should have zero historical on-chain linkage to the depositor's primary identity.
+3. **Environment Verification:** Verify the integrity of the local build or ensure the use of the canonical `solvoid.io` interface to mitigate man-in-the-middle or phishing attacks.
+4. **Gas Funding Risks:** When not utilizing the Shadow Relayer network, funding a fresh destination wallet with SOL gas may introduce timing-based or graph-based linkage vulnerabilities.
 
 ---
 
-##  Known Security Considerations (Brutal Honesty)
-1. **Un-audited Code:** As of the current version, this protocol has **NOT** undergone a professional security audit.
-2. **Trusted Setup:** The current ceremony files are for testing. A production-grade Multi-Party Computation (MPC) trusted setup is required before Mainnet launch.
-3. **Draft Circuits:** Some constraints in the `withdraw.circom` are undergoing refinement to prevent potential edge-case under-constraints.
-4. **Relayer Trust:** While relayers cannot steal funds (thanks to ZK binding), they could theoretically log user IP addresses or refuse to broadcast transactions (DoS).
+## Critical Security Considerations & Risk Factors
+
+1. **Audit Status:** The current protocol implementation has **not** undergone a third-party security audit. Usage is restricted to experimental or testing environments.
+2. **Proving Ceremony Requirements:** Proving keys currently in use are intended for development cycles. A production-grade Multi-Party Computation (MPC) ceremony is mandatory before Mainnet architectural finalization.
+3. **Circuit Constraints:** Circom circuit constraints are undergoing continuous peer review and refinement to ensure comprehensive boundary coverage.
+4. **Relayer Trust Model:** Relayer entities are restricted by ZK-bindings from asset theft, but retain the capacity for IP logging or localized Denial of Service (DoS).
 
 ---
 
-##  Supported Versions
-| Version | Supported |
-|---------|-----------|
-| 0.2.x   |  Beta    |
-| 0.1.x   |  Legacy  |
+## Version Support Matrix
+
+| Specification | Support Status | Maintenance Type |
+|---------------|----------------|------------------|
+| 0.2.x         | Active         | Feature/Security |
+| 0.1.x         | Deprecated     | Critical Fixes   |
 
 ---
 
-##  Bug Bounty
-We are currently operating a "Friendly Hacker" program. Critical vulnerabilities reported responsibly may be eligible for rewards in future protocol development funds.
+## Bug Bounty Initiative
+We operate a "Coordinated Vulnerability Research" program. Reports of critical vulnerabilities that adhere to disclosure requirements are prioritized for retroactive rewards as the protocol ecosystem matures.

package/dist/cli/commands/ghost.d.ts

@@ -1,11 +1,11 @@
 import { Command } from 'commander';
 /**
- * Register the ghost command with the CLI program
- * This is a non-breaking addition to your existing CLI
+ * Registry for the Privacy Ghost Score command suite.
+ * Provides visual privacy metrics and ZK-verified reputation artifacts.
  */
 export declare function registerGhostCommand(program: Command): void;
 /**
- * Add helper text for the ghost command
+ * Provides technical documentation for the ghost command module.
  */
 export declare function getGhostCommandHelp(): string;
 //# sourceMappingURL=ghost.d.ts.map

package/dist/cli/commands/ghost.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ghost.d.ts","sourceRoot":"","sources":["../../../cli/commands/ghost.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAQpC;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,OAAO,QA4EpD;AAsED;;GAEG;AACH,wBAAgB,mBAAmB,IAAI,MAAM,CAwC5C"}
+{"version":3,"file":"ghost.d.ts","sourceRoot":"","sources":["../../../cli/commands/ghost.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAQpC;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,OAAO,QAsEpD;AAoED;;GAEG;AACH,wBAAgB,mBAAmB,IAAI,MAAM,CA2B5C"}