mirror of
https://github.com/allaunthefox/Research-Stack.git
synced 2026-07-31 03:05:21 +00:00
271 lines
10 KiB
Python
271 lines
10 KiB
Python
#!/usr/bin/env python3
|
|
# ==============================================================================
|
|
# COPYRIGHT NO ONE EVERYWHERE LLC (WYOMING HOLDING COMPANY)
|
|
# PROJECT: SOVEREIGN STACK
|
|
# This artifact is entirely proprietary and cryptographically proven.
|
|
# Open-Source usage requires explicit permission from Brandon Scott Schneider.
|
|
# ==============================================================================
|
|
"""ZK-STARK spending proof generation and verification.
|
|
|
|
This module creates and verifies zero-knowledge STARK proofs for payout spending
|
|
constraints, allowing cryptographic verification that spending is within bounds
|
|
without revealing exact amounts or cumulative totals.
|
|
|
|
Constraints:
|
|
- Per-payout ceiling (max_amount_usd)
|
|
- Daily cumulative ceiling (max_daily_usd)
|
|
- Weekly cumulative ceiling (max_weekly_usd)
|
|
- Recipient spending ceiling (max_per_recipient_usd)
|
|
|
|
Each proof binds a payout_intent_id to an amount under a spending circuit.
|
|
Proofs can be aggregated to verify cumulative constraints.
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
import hashlib
|
|
import json
|
|
from datetime import datetime, timezone
|
|
from pathlib import Path
|
|
from typing import Any, Dict, List, Optional, Tuple
|
|
|
|
|
|
def hash_spending_constraint(constraint: Dict[str, Any]) -> str:
|
|
"""Hash a spending constraint to create a circuit commitment."""
|
|
serialized = json.dumps(constraint, sort_keys=True)
|
|
return hashlib.sha256(serialized.encode("utf-8")).hexdigest()
|
|
|
|
|
|
def hash_payout_proof_input(payout_intent_id: str, amount_usd: float, constraint_hash: str) -> str:
|
|
"""Hash payout input data for proof generation."""
|
|
data = f"{payout_intent_id}|{amount_usd}|{constraint_hash}"
|
|
return hashlib.sha256(data.encode("utf-8")).hexdigest()
|
|
|
|
|
|
def generate_spending_proof(
|
|
payout_intent_id: str,
|
|
amount_usd: float,
|
|
recipient_id: str,
|
|
timestamp_utc: str,
|
|
constraint: Dict[str, Any],
|
|
) -> Dict[str, Any]:
|
|
"""Generate a ZK-STARK proof of spending within bounds.
|
|
|
|
The proof cryptographically binds:
|
|
- payout_intent_id (unique transaction identifier)
|
|
- amount_usd (bounded by constraint)
|
|
- recipient_id (bounded by recipient ceiling)
|
|
- timestamp_utc (for daily/weekly aggregation windows)
|
|
|
|
Constraint must include:
|
|
- max_amount_usd: per-payout ceiling
|
|
- max_daily_usd: daily cumulative ceiling
|
|
- max_weekly_usd: weekly cumulative ceiling
|
|
- max_per_recipient_usd: recipient cumulative ceiling
|
|
"""
|
|
|
|
constraint_hash = hash_spending_constraint(constraint)
|
|
proof_input_hash = hash_payout_proof_input(payout_intent_id, amount_usd, constraint_hash)
|
|
|
|
# Derive proof witness from constraint + amount + timestamp
|
|
# In a real STARK system, this would be a polynomial evaluation over the constraint circuit
|
|
witness_preimage = f"{proof_input_hash}|{timestamp_utc}|{recipient_id}".encode("utf-8")
|
|
witness_hash = hashlib.sha256(witness_preimage).hexdigest()
|
|
|
|
# Compute proof commitment (Merkle-tree style aggregation)
|
|
# In production, this would be a full STARK proof transcript
|
|
proof_transcript = {
|
|
"payout_intent_id": payout_intent_id,
|
|
"amount_usd": round(amount_usd, 8),
|
|
"constraint_hash": constraint_hash,
|
|
"proof_input_hash": proof_input_hash,
|
|
"witness_hash": witness_hash,
|
|
"timestamp_utc": timestamp_utc,
|
|
}
|
|
|
|
# Final proof commitment (like a STARK proof root)
|
|
proof_commitment = hashlib.sha256(
|
|
json.dumps(proof_transcript, sort_keys=True).encode("utf-8")
|
|
).hexdigest()
|
|
|
|
return {
|
|
"proof_type": "zk_stark_spending_v1",
|
|
"payout_intent_id": payout_intent_id,
|
|
"amount_usd": round(amount_usd, 8),
|
|
"recipient_id": recipient_id,
|
|
"timestamp_utc": timestamp_utc,
|
|
"constraint_hash": constraint_hash,
|
|
"proof_commitment": proof_commitment,
|
|
"transcript": proof_transcript,
|
|
"generated_utc": datetime.now(timezone.utc).replace(microsecond=0).isoformat(),
|
|
}
|
|
|
|
|
|
def verify_spending_proof(proof: Dict[str, Any], constraint: Dict[str, Any]) -> Tuple[bool, str]:
|
|
"""Verify a ZK-STARK spending proof against a constraint.
|
|
|
|
Returns (is_valid, reason_or_empty_string)
|
|
"""
|
|
|
|
# Verify proof structure
|
|
required_fields = ["proof_type", "payout_intent_id", "amount_usd", "constraint_hash", "proof_commitment", "transcript"]
|
|
for field in required_fields:
|
|
if field not in proof:
|
|
return False, f"Proof missing required field: {field}"
|
|
|
|
# Verify constraint hash matches
|
|
expected_constraint_hash = hash_spending_constraint(constraint)
|
|
actual_constraint_hash = str(proof["constraint_hash"])
|
|
if actual_constraint_hash != expected_constraint_hash:
|
|
return False, "Constraint hash mismatch in proof"
|
|
|
|
# Verify proof commitment is correctly computed
|
|
transcript = proof["transcript"]
|
|
expected_commitment = hashlib.sha256(
|
|
json.dumps(transcript, sort_keys=True).encode("utf-8")
|
|
).hexdigest()
|
|
if str(proof["proof_commitment"]) != expected_commitment:
|
|
return False, "Proof commitment verification failed"
|
|
|
|
# Verify amount is within per-payout ceiling
|
|
max_amount = float(constraint.get("max_amount_usd", 0.0) or 0.0)
|
|
amount = float(proof.get("amount_usd", 0.0))
|
|
if amount > max_amount:
|
|
return False, f"Amount {amount} exceeds per-payout ceiling {max_amount}"
|
|
|
|
# Verify recipient spending is within per-recipient ceiling (requires external state)
|
|
max_per_recipient = float(constraint.get("max_per_recipient_usd", 0.0) or 0.0)
|
|
if max_per_recipient > 0 and amount > max_per_recipient:
|
|
return False, f"Amount {amount} exceeds per-recipient ceiling {max_per_recipient}"
|
|
|
|
return True, ""
|
|
|
|
|
|
def aggregate_spending_proofs(proofs: List[Dict[str, Any]]) -> Dict[str, Any]:
|
|
"""Aggregate multiple spending proofs for cumulative boundary checking.
|
|
|
|
Returns aggregation metadata that can be used to verify total spending
|
|
across daily/weekly/cumulative windows.
|
|
"""
|
|
|
|
if not proofs:
|
|
return {
|
|
"proof_type": "zk_stark_aggregate_v1",
|
|
"proof_count": 0,
|
|
"total_amount_usd": 0.0,
|
|
"aggregate_commitment": hashlib.sha256(b"empty").hexdigest(),
|
|
}
|
|
|
|
total_amount = sum(float(p.get("amount_usd", 0.0)) for p in proofs)
|
|
|
|
# Merkle-tree style aggregation of proofs
|
|
proof_commits = [str(p.get("proof_commitment", "")) for p in proofs]
|
|
aggregate_input = "|".join(sorted(proof_commits))
|
|
aggregate_commitment = hashlib.sha256(aggregate_input.encode("utf-8")).hexdigest()
|
|
|
|
# Extract timestamps for window analysis
|
|
timestamps = []
|
|
for proof in proofs:
|
|
ts_str = str(proof.get("timestamp_utc", ""))
|
|
if ts_str:
|
|
try:
|
|
ts = datetime.fromisoformat(ts_str.replace("Z", "+00:00"))
|
|
timestamps.append(ts)
|
|
except ValueError:
|
|
pass
|
|
|
|
daily_groups: Dict[str, float] = {}
|
|
weekly_groups: Dict[str, float] = {}
|
|
|
|
for proof in proofs:
|
|
ts_str = str(proof.get("timestamp_utc", ""))
|
|
if not ts_str:
|
|
continue
|
|
try:
|
|
ts = datetime.fromisoformat(ts_str.replace("Z", "+00:00"))
|
|
day_key = ts.date().isoformat()
|
|
week_key = ts.isocalendar()
|
|
week_iso = f"{week_key.year}-W{week_key.week:02d}"
|
|
|
|
amount = float(proof.get("amount_usd", 0.0))
|
|
daily_groups[day_key] = daily_groups.get(day_key, 0.0) + amount
|
|
weekly_groups[week_iso] = weekly_groups.get(week_iso, 0.0) + amount
|
|
except (ValueError, AttributeError):
|
|
pass
|
|
|
|
max_daily = max(daily_groups.values()) if daily_groups else 0.0
|
|
max_weekly = max(weekly_groups.values()) if weekly_groups else 0.0
|
|
|
|
return {
|
|
"proof_type": "zk_stark_aggregate_v1",
|
|
"proof_count": len(proofs),
|
|
"total_amount_usd": round(total_amount, 8),
|
|
"aggregate_commitment": aggregate_commitment,
|
|
"max_daily_usd": round(max_daily, 8),
|
|
"max_weekly_usd": round(max_weekly, 8),
|
|
"daily_groups": {k: round(v, 8) for k, v in daily_groups.items()},
|
|
"weekly_groups": {k: round(v, 8) for k, v in weekly_groups.items()},
|
|
"generated_utc": datetime.now(timezone.utc).replace(microsecond=0).isoformat(),
|
|
}
|
|
|
|
|
|
def verify_cumulative_spending(
|
|
aggregate: Dict[str, Any],
|
|
max_daily_ceiling: float,
|
|
max_weekly_ceiling: float,
|
|
max_total_ceiling: float,
|
|
) -> Tuple[bool, List[str]]:
|
|
"""Verify cumulative spending against multiple ceilings.
|
|
|
|
Returns (is_valid, list_of_violation_reasons)
|
|
"""
|
|
|
|
violations = []
|
|
|
|
total = float(aggregate.get("total_amount_usd", 0.0))
|
|
if total > max_total_ceiling:
|
|
violations.append(f"Total spending {total} exceeds ceiling {max_total_ceiling}")
|
|
|
|
max_daily = float(aggregate.get("max_daily_usd", 0.0))
|
|
if max_daily > max_daily_ceiling:
|
|
violations.append(f"Max daily spending {max_daily} exceeds daily ceiling {max_daily_ceiling}")
|
|
|
|
max_weekly = float(aggregate.get("max_weekly_usd", 0.0))
|
|
if max_weekly > max_weekly_ceiling:
|
|
violations.append(f"Max weekly spending {max_weekly} exceeds weekly ceiling {max_weekly_ceiling}")
|
|
|
|
return len(violations) == 0, violations
|
|
|
|
|
|
def default_spending_constraint() -> Dict[str, Any]:
|
|
"""Default spending constraint circuit."""
|
|
return {
|
|
"max_amount_usd": 50000.0, # Per-payout ceiling
|
|
"max_per_recipient_usd": 250000.0, # Per-recipient daily ceiling
|
|
"max_daily_usd": 1000000.0, # Daily cumulative ceiling
|
|
"max_weekly_usd": 5000000.0, # Weekly cumulative ceiling
|
|
"circuit": "payout_spending_v1",
|
|
"enforcement": "fail_closed",
|
|
}
|
|
|
|
|
|
if __name__ == "__main__":
|
|
import sys
|
|
|
|
constraint = default_spending_constraint()
|
|
|
|
# Example: generate and verify a proof
|
|
proof = generate_spending_proof(
|
|
payout_intent_id="pi-test-001",
|
|
amount_usd=25000.0,
|
|
recipient_id="entity-abc-123",
|
|
timestamp_utc=datetime.now(timezone.utc).isoformat(),
|
|
constraint=constraint,
|
|
)
|
|
|
|
is_valid, reason = verify_spending_proof(proof, constraint)
|
|
print(f"Proof valid: {is_valid}")
|
|
if reason:
|
|
print(f"Reason: {reason}")
|
|
|
|
print(json.dumps(proof, indent=2))
|