Skip to content

BLOCKCHAIN_SETUP.md

Latest commit

 

History

History
381 lines (275 loc) · 8.27 KB

BLOCKCHAIN_SETUP.md

File metadata and controls

381 lines (275 loc) · 8.27 KB

CompZ Real Blockchain Setup Guide

This guide shows you how to connect CompZ SDK to the real Zcash blockchain for production-grade compliance attestation.

🎯 Overview

CompZ can operate in two modes:

Mode Description Blockchain Setup Time
Demo Mode Uses hosted gateway (placeholder) Testnet via gateway 30 seconds
Self-Hosted Your own Zcash node Real testnet/mainnet 2-4 hours

For real blockchain integration, use Self-Hosted mode.

📦 Prerequisites

  • Docker & Docker Compose installed
  • 100GB+ free disk space (for blockchain sync)
  • Stable internet connection
  • CompZ SDK installed: pip install -e .

🚀 Quick Start: Real Zcash Testnet

Step 1: Start Zcash Node

# Start Zcash testnet node
cd /Users/satyamsinghal/Desktop/Products/CompZ
docker-compose up -d zcashd

# Check logs
docker logs -f compz-zcashd

Wait for sync (2-4 hours for testnet):

# Check sync status
docker exec compz-zcashd zcash-cli -testnet getblockchaininfo

Look for "blocks" and "headers" - when they match, you're synced!

Step 2: Generate Z-Address

# Generate a new shielded address
docker exec compz-zcashd zcash-cli -testnet z_getnewaddress sapling

# Example output: ztestsapling1abc123...xyz789

Save this address! You'll need it in your .env file.

Step 3: Fund Your Address

Get testnet ZEC from a faucet:

Check balance:

docker exec compz-zcashd zcash-cli -testnet z_getbalance "ztestsapling1..."

Step 4: Configure CompZ

Create .env file:

cp .env.example .env

Edit .env:

# Self-Hosted Mode Configuration
ZCASH_RPC_URL=http://localhost:18232
ZCASH_RPC_USER=compz
ZCASH_RPC_PASS=compz_secure_password_change_this
ZCASH_DEFAULT_ADDRESS=ztestsapling1abc123...xyz789  # Your address from Step 2
ZCASH_TESTNET=true

Step 5: Test Real Blockchain Integration

from compz import CompZClient

# Initialize with self-hosted mode
client = CompZClient(
    rpc_url="http://localhost:18232",
    rpc_user="compz",
    rpc_pass="compz_secure_password_change_this",
    default_address="ztestsapling1abc123...xyz789",
    testnet=True
)

# Anchor to REAL Zcash blockchain
compliance_data = {
    "repo_id": "myorg/myrepo",
    "risk_score": 25.5,
    "timestamp": "2024-11-26T14:00:00Z"
}

result = client.anchor(compliance_data)
print(f"Anchored to blockchain: {result.txid}")
print(f"View on explorer: {result.explorer_url}")

🔍 What Happens On-Chain?

When you call client.anchor():

  1. Normalize your compliance data to canonical JSON
  2. Hash with SHA-256 → 0xabc123...
  3. Create memo → compz:v1:0xabc123...
  4. Send shielded transaction to your own address with memo
  5. Return TXID → Transaction is now immutable on Zcash blockchain

Verify On Explorer:

Testnet: https://explorer.testnet.z.cash/tx/YOUR_TXID

The memo field contains your compliance hash!

🔐 How Blockchain Verification Works

# Verify compliance data against blockchain
result = client.verify(compliance_data, txid)

if result.valid:
    print("✅ Data matches blockchain!")
    print(f"On-chain hash: {result.onchain_hash}")
    print(f"Confirmations: {result.confirmations}")
else:
    print("❌ Data has been tampered with!")
    print(f"Reason: {result.reason}")

What happens:

  1. SDK recomputes hash from your data
  2. Fetches transaction from blockchain using TXID
  3. Extracts memo from shielded transaction
  4. Compares hashes

Result: Cryptographic proof that data hasn't changed since anchoring!

🏭 Production: Mainnet Setup

Switch to Mainnet:

1. Update zcash.conf:

# Change testnet=1 to:
testnet=0

2. Restart node:

docker-compose down
docker-compose up -d zcashd

3. Wait for mainnet sync (24-48 hours)

4. Generate mainnet address:

docker exec compz-zcashd zcash-cli z_getnewaddress sapling

5. Buy real ZEC and send to your address:

  • Purchase from exchange (Coinbase, Kraken, etc.)
  • Send to your shielded address
  • Each transaction costs 0.0001 ZEC ($0.003)

6. Update .env:

ZCASH_TESTNET=false
ZCASH_DEFAULT_ADDRESS=zs1abc123...xyz789  # Mainnet address

⚡ Transaction Costs

Network Cost per Anchor Total for 1000 Anchors
Testnet FREE (faucet) FREE
Mainnet 0.0001 ZEC ($0.003) 0.1 ZEC ($3)

Compare to alternatives:

  • Ethereum: $5-50 per transaction
  • Bitcoin: $1-10 per transaction
  • Zcash: $0.003 per transaction ✅

🛠️ Troubleshooting

Node not syncing:

# Check peers
docker exec compz-zcashd zcash-cli -testnet getpeerinfo

# Restart node
docker-compose restart zcashd

Insufficient funds:

# Check balance
docker exec compz-zcashd zcash-cli -testnet z_getbalance "YOUR_ADDRESS"

# Get more from faucet

Can't see memo:

The memo is in the shielded transaction. You need:

  1. Viewing key or spending key
  2. Use z_viewtransaction RPC command

CompZ SDK handles this automatically!

📊 Monitoring

Check Node Status:

# Blockchain info
docker exec compz-zcashd zcash-cli -testnet getblockchaininfo

# Wallet info
docker exec compz-zcashd zcash-cli -testnet getwalletinfo

# Network info
docker exec compz-zcashd zcash-cli -testnet getnetworkinfo

View Recent Transactions:

docker exec compz-zcashd zcash-cli -testnet z_listreceivedbyaddress "YOUR_ADDRESS"

🔄 CI/CD Integration

GitHub Actions Example:

name: Compliance Anchor

on:
  push:
    branches: [main]

jobs:
  anchor:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Run security scan
        run: ./scan.sh
      
      - name: Anchor to blockchain
        env:
          ZCASH_RPC_URL: ${{ secrets.ZCASH_RPC_URL }}
          ZCASH_RPC_USER: ${{ secrets.ZCASH_RPC_USER }}
          ZCASH_RPC_PASS: ${{ secrets.ZCASH_RPC_PASS }}
          ZCASH_DEFAULT_ADDRESS: ${{ secrets.ZCASH_ADDRESS }}
        run: |
          pip install compz
          compz anchor compliance_result.json -o anchor_result.json
          
      - name: Save TXID
        run: |
          TXID=$(jq -r '.txid' anchor_result.json)
          echo "TXID: $TXID" >> $GITHUB_STEP_SUMMARY

🎓 Architecture Deep Dive

Why Shielded Transactions?

CompZ uses Zcash shielded transactions (not transparent):

  • ✅ Privacy: Transaction amounts hidden
  • ✅ Memo field: 512 bytes for your hash
  • ✅ Encryption: Only you can read the memo
  • ✅ Immutable: Can't be changed once confirmed

Transaction Flow:

Your App
   ↓
CompZ SDK (normalize → hash)
   ↓
Zcash RPC (z_sendmany)
   ↓
Local Zcash Node
   ↓
Zcash Network (shielded pool)
   ↓
Blockchain (immutable record)
   ↓
Block Explorer (public verification)

Data Privacy Guarantee:

❌ NOT on blockchain: Your actual compliance data
✅ ON blockchain: SHA-256 hash (cryptographic fingerprint)

Result: Public verifiability + Private data!

🌐 Public vs Private Verification

Public Verification:

Anyone with TXID can verify:

curl https://explorer.testnet.z.cash/api/tx/YOUR_TXID

Private Verification:

Only you can read memo (requires viewing key):

docker exec compz-zcashd zcash-cli -testnet z_viewtransaction YOUR_TXID

CompZ SDK handles both automatically!

📈 Scaling

For high-volume anchoring:

  1. Run multiple nodes (load balancing)
  2. Use LightwalletD (faster sync)
  3. Batch transactions (coming soon)
  4. Consider enterprise gateway (contact us)

🆘 Support

✅ You're Ready!

You now have:

  • ✅ Real Zcash node running
  • ✅ Funded testnet address
  • ✅ CompZ SDK configured
  • ✅ Ready to anchor to blockchain

Next: Run the example in examples/self_hosted_example.py