Skip to content

ExecutionPlan.md

Latest commit

 

History

History
473 lines (350 loc) · 12.4 KB

ExecutionPlan.md

File metadata and controls

473 lines (350 loc) · 12.4 KB

CompZ Development & Implementation Plan

Privacy-Preserving Compliance SDK + Zcash Anchoring Module

Version 1.0 (Launch Edition)

1. Project Overview

CompZ is a lightweight, open-source compliance attestation SDK designed specifically for the Zcash privacy ecosystem.

It enables:

  1. Input of AI or rule-based compliance results
  2. Deterministic normalization
  3. SHA-256 hashing
  4. Anchoring the hash onto Zcash testnet/mainnet
  5. Zero-knowledge-style verification without revealing compliance data

CompZ integrates cleanly with:

  • CompliLedger
  • COMP-LEO
  • Any SBOM / SCA / Compliance engine

CompZ v1.0 includes:

  • ✔ Zcash attestation module
  • ✔ ComplianceResult schema
  • ✔ PCI/SOC2/FedRAMP mini-rule engine
  • ✔ CLI tools
  • ✔ REST API Gateway
  • ✔ End-to-end documentation
  • ✔ Example JSON & example Zcash txids

2. System Architecture

2.1 Dual-Mode SDK Architecture

CompZ operates in two modes to maximize accessibility and adoption:

┌─────────────────────────────────────────────────────────────┐
│                    COMPZ SDK (v1.0)                         │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  MODE 1: DEMO MODE (Zero Setup)                            │
│  ┌────────────────────────────────────────────┐            │
│  │  Developer's Application                   │            │
│  │  ├─ pip install compz                      │            │
│  │  ├─ client = CompZClient()  # No config!  │            │
│  │  └─ client.anchor(data)     # Just works  │            │
│  └──────────────┬─────────────────────────────┘            │
│                 │ HTTPS                                     │
│                 ▼                                           │
│      ┌──────────────────────┐                              │
│      │  CompZ Demo Gateway  │ ← Hosted by CompZ            │
│      │  (api.compz.dev)     │   (Rate-limited, testnet)    │
│      │  - Zcash testnet     │                              │
│      │  - Free tier         │                              │
│      │  - 100 calls/hour    │                              │
│      └──────────────────────┘                              │
│                                                             │
│  MODE 2: SELF-HOSTED (Production)                          │
│  ┌────────────────────────────────────────────┐            │
│  │  Developer's Infrastructure                │            │
│  │  ├─ docker-compose up                      │            │
│  │  ├─ Local Zcash node                       │            │
│  │  └─ Full control & privacy                 │            │
│  └────────────────────────────────────────────┘            │
│                                                             │
└─────────────────────────────────────────────────────────────┘

2.2 Flow Diagram

          ┌───────────────────────────────┐
          │   Compliance Engine (AI/Rule) │
          └───────────┬──────────────────┘
                      │ 
                      ▼  compliance_result.json
           normalize_json()  → canonical JSON
                      ▼
               hash_compliance()
                      ▼  SHA-256 deterministic hash
          ┌───────────▼────────────┐
          │   CompZ SDK Client     │
          │   (Dual-Mode)          │
          └───────────┬────────────┘
                      │  
                      ├─────────────────┬──────────────────┐
                      │                 │                  │
                DEMO MODE         SELF-HOSTED        ENTERPRISE
                      │                 │                  │
                      ▼                 ▼                  ▼
              CompZ Gateway      Local Zcash         Private Node
              (Public, Free)      (Docker)          (Full Control)
                      │                 │                  │
                      └─────────────────┴──────────────────┘
                                        │
                         Send Zcash tx w/ memo: compz:v1:<hash>
                                        ▼
                                    return txid
                                        ▼
                          verify_against_tx(txid, json)
                                        ▼
                           VALID / INVALID PROOF CHECK

2.3 Mode Comparison

Feature Demo Mode Self-Hosted Enterprise
Setup Time 30 seconds 30 minutes 1-2 hours
Infrastructure None needed Docker Custom VPS
Network Testnet only Test/Mainnet Mainnet
Rate Limits 100/hour Unlimited Unlimited
Privacy Gateway sees data Full privacy Full privacy
Cost Free $0.001/tx $0.001/tx
Best For Testing, demos Development Production

3. Core Requirements

3.1 Compliance JSON

Must be deterministic and schema-safe.

3.2 Normalization

CompZ uses canonical JSON:

  • Sorted keys (recursive)
  • Remove empty/null fields
  • UTF-8 NFC normalized
  • No whitespace
  • No timestamp drift
  • Remove UI/debug fields

3.3 Hashing

sha256(normalized_json).hex()

Prefixed as:

0x<hash>

4. Module Breakdown

4.1 models.py

class ComplianceResult(BaseModel):
    repo_id: str
    commit_hash: str
    frameworks: List[str]
    control_evaluations: List[dict]  # id/pass/reason
    risk_score: float
    timestamp: str  # ISO 8601

4.2 normalize.py

  • Canonical JSON
  • Stable key ordering
  • Remove empty fields
  • Remove _ui, _internal, _debug fields
  • UTF-8 strict encoding

4.3 hash.py

  • SHA-256 of normalized JSON
  • Returns hex string
  • Used for anchoring + verification

4.4 zcash_client.py

Supports:

  • Zcashd RPC
  • Lightwalletd gRPC

Functions:

send_transaction_with_memo(memo)
get_memo_by_txid(txid)

Features:

  • Transparent pool
  • Testnet by default
  • Valid memo encoding (≤ 512 bytes)

4.5 anchor.py

Pipeline:

  1. Normalize
  2. Hash
  3. Memo: compz:v1:<hash>
  4. Send Zcash transaction
  5. Return {hash, txid, network, timestamp}

4.6 verify.py

Steps:

  1. Recompute normalized hash
  2. Fetch tx from Zcash
  3. Extract memo
  4. Compare
  5. Return:
{
  "valid": true,
  "local_hash": "...",
  "onchain_hash": "...",
  "txid": "..."
}

4.7 evaluator.py

Rule engine for:

  • PCI DSS
  • SOC2 Security
  • FedRAMP Moderate

Outputs:

{
 "framework": "...",
 "total_controls": n,
 "passed": x,
 "failed": y,
 "controls": [...]
}

Merged into ComplianceResult.

5. Rule Sets Included (Minimal v1)

5.1 PCI DSS (5 controls)

Control Validation
PCI 1.1.1 firewall_rules exists
PCI 2.2 secure_defaults == true
PCI 3.4 encryption.enabled == true
PCI 8.2 mfa.enabled
PCI 10.2 logging.enabled

5.2 SOC2 – Security (5 controls)

Control Validation
CC1.1 access_policies exists
CC3.2 risk.assessment exists
CC6.1 change_control.process exists
CC7.1 monitoring.enabled
CC8.1 dr_plan exists

5.3 FedRAMP Moderate (8 controls)

ID Requirement
AC-2 accounts.managed == true
AC-3 access_controls.enforced
AU-2 audit.events_defined
AU-6 audit.review_process
CM-2 config.baseline exists
CM-6 config.settings exists
SC-13 crypto.enabled
SI-2 vuln.scanning_enabled

6. API Gateway

POST /api/compliance/analyze

Runs evaluator. Returns ComplianceResult.

POST /api/compliance/anchor

Runs CompZ Anchor. Returns {hash, txid}.

POST /api/compliance/verify

Verifies using JSON + txid. Returns {valid, reason, hash, onchain_hash}.

GET /api/status

Health indicator.

7. CLI Tools

compz-anchor file.json

Anchors compliance JSON to Zcash testnet.

compz-verify file.json <txid>

Verifies JSON against on-chain memo.

8. Dual-Mode Deployment Strategy

8.1 Demo Mode Infrastructure (Your VPS)

Requirements:

  • VPS: 2 vCPU, 4GB RAM, 100GB SSD (~$10-20/month)
  • Docker & Docker Compose
  • Domain name (e.g., api.compz.dev)
  • SSL certificate (Let's Encrypt)

Components:

  1. Zcash testnet node (zcashd in Docker)
  2. FastAPI gateway service
  3. Redis (rate limiting)
  4. Nginx (reverse proxy + SSL)

Setup Time: 1-2 hours (excluding node sync)

8.2 Self-Hosted Mode (User Infrastructure)

Requirements:

  • Docker & Docker Compose
  • 50-100GB storage
  • Environment variables

Setup:

docker-compose up -d
# Wait for sync (2-4 hours)
# Configure .env file
# Ready to use

9. Revised Engineering Timeline (2 Days)

Day 1 — Core SDK + Infrastructure

Morning (4 hours)

  • ✅ Project structure setup
  • ✅ Core models (Pydantic schemas)
  • ✅ normalize.py (canonical JSON)
  • ✅ hash.py (SHA-256)
  • ✅ Basic tests

Afternoon (4 hours)

  • ✅ CompZ client (dual-mode logic)
  • ✅ Zcash RPC client (self-hosted mode)
  • ✅ Demo mode stubs
  • ✅ VPS setup (start node sync)

Day 2 — Gateway + Polish

Morning (4 hours)

  • ✅ FastAPI gateway service
  • ✅ Rate limiting & security
  • ✅ Docker Compose setup
  • ✅ Deploy to VPS

Afternoon (4 hours)

  • ✅ CLI tools (compz-anchor, compz-verify)
  • ✅ Example scripts
  • ✅ Documentation
  • ✅ PyPI packaging

Evening (2 hours)

  • ✅ End-to-end testing
  • ✅ Demo video/screenshots
  • ✅ Launch checklist

10. Deliverables

Required

  • ✔ Public GitHub repo
  • ✔ Functional CompZ SDK
  • ✔ Working CLI
  • ✔ Example compliance JSON
  • ✔ PCI/SOC2/FedRAMP rule sets
  • ✔ Zcash testnet txids
  • ✔ API docs
  • ✔ Demo script

Optional

  • Web UI
  • Docker images
  • Integration testing suite

11. Risks & Mitigations

Risk Mitigation
Zcash RPC downtime Use trusted public testnet RPC providers
Memo parsing issues Use strict compz:v1:<hash> format
Hash mismatch Freeze canonical JSON logic
Zcash fees Use dust outputs & testnet faucet
Short timelines Limit controls to small, verifiable set

12. Developer Summary

Build CompZ as a standalone, open-source SDK with:

  • normalize.py
  • hash.py
  • evaluator.py
  • zcash_client.py
  • anchor.py
  • verify.py
  • CLI tools
  • Example JSON

Pipeline: Evaluator → normalize → hash → anchor (Zcash) → verify

Must be deterministic, stable, minimal, and Zcash-focused.