Skip to content

Security: arcbjorn/crosspay

Security

docs/SECURITY.md

CrossPay Protocol Security Documentation

Security Architecture Overview

CrossPay Protocol implements a multi-layered security model combining:

  • Zama FHE for cryptographic privacy
  • Symbiotic Validators for consensus security
  • Risk-Stratified Vaults for economic security
  • Role-Based Access Control for operational security

Threat Model

Assets at Risk

  1. User Funds: ETH and ERC20 tokens in escrow
  2. Validator Stakes: Bonded ETH securing the network
  3. Vault Deposits: Risk-tranched liquidity pools
  4. Private Data: Encrypted payment amounts and metadata

Attack Vectors

  1. Smart Contract Vulnerabilities: Reentrancy, overflow, access control
  2. Cryptographic Attacks: FHE key compromise, signature forgery
  3. Validator Attacks: Collusion, censorship, griefing
  4. Economic Attacks: Vault manipulation, slashing abuse
  5. Privacy Attacks: Disclosure bypass, correlation analysis

Security Assumptions

Cryptographic Assumptions

  • Zama FHE scheme remains secure against chosen-plaintext attacks
  • ECDSA signatures cannot be forged without private key knowledge
  • Ethereum's consensus layer provides finality guarantees
  • Random number generation is unpredictable and unbiased

Network Assumptions

  • At least 67% of validators are honest and responsive
  • Network partitions resolve within validation timeout periods
  • Smart contract execution environment is not compromised
  • Oracle data feeds remain accurate and manipulation-resistant

Economic Assumptions

  • Validator slashing penalties exceed potential attack profits
  • Vault participants act rationally to maximize risk-adjusted returns
  • Gas costs make spam attacks economically infeasible
  • Token price stability prevents manipulation of yield calculations

Security Controls

Access Control Matrix

Role ConfidentialPayments RelayValidator TrancheVault Analytics
DEFAULT_ADMIN_ROLE Pause, role mgmt Pause, thresholds Pause, fees -
COMPLIANCE_ROLE Emergency disclosure - - -
AUDITOR_ROLE Request disclosure - - Read-only
VALIDATOR_ROLE - Sign validations - -
Owner Contract admin Slash, validation Vault admin -

Input Validation

  • All user addresses validated against zero address
  • Payment amounts checked for minimum thresholds
  • Signature verification before processing
  • Deadline enforcement on time-sensitive operations
  • Tranche deposit limits enforced

State Protection

  • ReentrancyGuard on all external state-changing functions
  • Pausable emergency stops across all contracts
  • Overflow protection via Solidity 0.8+ built-ins
  • Safe ERC20 transfers to handle non-standard tokens

Known Limitations

Zama FHE Privacy

  • Encrypted amounts revealed during contract execution for transfers
  • Homomorphic operations limited to addition/comparison
  • Client-side encryption keys must be managed securely
  • Gas costs significantly higher for encrypted operations

Validator Network

  • Requires minimum 3 validators for basic security
  • No protection against coordinated 67%+ validator attacks
  • Signature aggregation increases gas costs linearly with validators
  • Network assumes honest majority without stake weighting

Tranche Vault

  • Slashing waterfall may not fully cover extreme losses
  • Yield calculations vulnerable to flash loan manipulation
  • No protection against coordinated vault drain attacks
  • Rebalancing requires manual intervention

Emergency Procedures

Incident Response Plan

  1. Detection: Automated monitoring alerts on anomalous behavior
  2. Assessment: Evaluate severity and potential impact
  3. Containment: Activate emergency pause on affected contracts
  4. Recovery: Execute recovery procedures based on incident type
  5. Post-Mortem: Document lessons learned and update controls

Emergency Controls

  • emergencyPause() on all contracts halts operations
  • slashValidator() removes malicious validators
  • emergencyCancel() refunds grant pools if needed
  • Multi-sig admin controls prevent single points of failure

Recovery Mechanisms

  • Time-locked withdrawals allow dispute resolution
  • Insurance fund covers small slashing events
  • Validator exit mechanisms prevent forced participation
  • Disclosure controls balance privacy with compliance

Audit Checklist

Smart Contract Security

  • All functions use appropriate access controls
  • Reentrancy protection on state-changing functions
  • Integer overflow protection verified
  • External calls handled safely with proper error handling
  • Emergency pause mechanisms tested
  • Upgrade mechanisms secured with time locks

Cryptographic Security

  • FHE operations audited by Zama team
  • Signature verification logic reviewed
  • Key management procedures documented
  • Randomness sources evaluated for bias
  • Privacy guarantees formally verified

Economic Security

  • Game theory analysis of validator incentives
  • Slashing economics prevent profitable attacks
  • Vault yield calculations audited for manipulation
  • Fee structures reviewed for economic sustainability
  • Oracle manipulation resistance verified

Operational Security

  • Multi-sig procedures documented and tested
  • Key management practices established
  • Incident response procedures tested
  • Monitoring and alerting systems operational
  • Backup and recovery procedures validated

Invariants

Contract Invariants

  • Total vault assets always equal sum of tranche balances plus insurance fund
  • Validator stake always matches on-chain balance
  • Payment escrow balance equals sum of pending payment amounts
  • Encrypted balances can only be revealed through authorized disclosure

System Invariants

  • Active validator count never drops below minimum threshold
  • Validation requests expire within configured timeout
  • Slashing always follows waterfall order (Junior → Mezzanine → Senior)
  • Privacy settings cannot be retroactively modified

Testing Coverage

Unit Tests

  • All contract functions tested with edge cases
  • Access control boundaries verified
  • Error conditions properly handled
  • State transitions validated

Integration Tests

  • Cross-contract interactions tested
  • End-to-end payment flows verified
  • Validator consensus mechanisms validated
  • Privacy disclosure workflows tested

Security Tests

  • Reentrancy attack scenarios
  • Integer overflow/underflow attempts
  • Access control bypass attempts
  • Economic attack simulations

Deployment Security

Contract Deployment

  • Use deterministic deployment for consistent addresses
  • Verify contract source code on block explorers
  • Initialize contracts with secure default parameters
  • Transfer ownership to multi-sig wallet immediately

Infrastructure Security

  • Validator nodes run on hardened systems
  • Private keys stored in hardware security modules
  • Network traffic encrypted and authenticated
  • Regular security updates and monitoring

Incident Categories

Critical (P0)

  • Funds at immediate risk of loss
  • Privacy completely compromised
  • Validator network consensus failure
  • Contract upgrade controls compromised

High (P1)

  • Partial fund loss possible
  • Privacy partially compromised
  • Individual validator compromise
  • Service degradation affecting users

Medium (P2)

  • Temporary service disruption
  • Non-critical data exposure
  • Performance degradation
  • Configuration errors

Low (P3)

  • Minor UI/UX issues
  • Documentation errors
  • Non-security-related bugs
  • Monitoring gaps

Contact Information

For security issues:

  • Critical Issues: Immediate disclosure to development team
  • Non-Critical Issues: Standard GitHub issue reporting
  • Responsible Disclosure: 90-day disclosure timeline for vulnerabilities

This document should be reviewed and updated with each major protocol upgrade.

There aren’t any published security advisories