This document provides comprehensive security information for the Grant Stream Contracts protocol. It serves as the primary security reference for auditors, developers, and governance participants.

1. Security Architecture
2. Critical Security Functions
3. Threat Model
4. Security Controls
5. Audit History
6. Incident Response
7. Security Best Practices

The Grant Stream protocol implements multiple security layers:

• Access Control: Role-based permissions with admin, oracle, and recipient roles
• Double-Approval System: Dual authorization for high-value milestone payouts
• Reentrancy Protection: Manual guards preventing recursive calls
• Circuit Breakers: Oracle price deviation and TVL velocity limits
• Legal Compliance: On-chain legal document signatures
• Emergency Controls: Pause/resume, rate changes, and token rescue

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Admin Role    │    │   Oracle Role   │    │  Recipient Role │
│   (God Mode)    │    │ (KPI Updates)   │    │  (Withdrawals)  │
└─────────────────┘    └─────────────────┘    └─────────────────┘
         │                       │                       │
         └───────────────────────┼───────────────────────┘
                                 │
                    ┌─────────────────┐
                    │  Grant Stream   │
                    │    Contract     │
                    └─────────────────┘
                                 │
         ┌───────────────────────┼───────────────────────┐
         │                       │                       │
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│  Token Contracts │    │  Circuit Breaker│    │  Legal/Compliance│
│   (Transfers)    │    │   (Protection)  │    │   (Signatures)   │
└─────────────────┘    └─────────────────┘    └─────────────────┘

• Impact: Full protocol control, fund redirection
• Likelihood: Medium (depends on key management)
• Mitigations: Multi-sig, HSM/MPC, rotation procedures

• Impact: Incorrect KPI multipliers, payment manipulation
• Likelihood: Medium
• Mitigations: Price deviation checks, sanity oracle, heartbeat monitoring

• Impact: State manipulation, double withdrawals
• Likelihood: Low (protected by manual guards)
• Mitigations: Non-reentrant guards, temporary storage locks

• Impact: Large fund drains, price manipulation
• Likelihood: Low
• Mitigations: Multiple independent checks, admin overrides

• Impact: Unauthorized high-value payouts, single point compromise
• Likelihood: Low (requires dual compromise)
• Mitigations: Separate approver roles, time windows, audit logging

• Impact: Regulatory violations, fund streaming without agreements
• Mitigations: On-chain signature requirements, legal hash storage

• Impact: Incorrect calculations, fund loss
• Mitigations: Checked arithmetic, comprehensive testing

• Impact: Transfer failures, accounting errors
• Mitigations: Token allowlist, integration testing

1. Role-Based Permissions

   • Admin: Full protocol control
   • Oracle: KPI multiplier updates
   • Recipient: Withdrawals and rage quits

2. Authentication Requirements

   • require_auth() for all privileged operations
   • Role-specific validation functions

3. Multi-Sig Recommendations

   • Minimum 2-of-3 for admin operations
   • Separate keys for different functions

4. Double-Approval System

   • Dual authorization for high-value payouts
   • Configurable value thresholds
   • Time-based approval windows
   • Separate approver roles (admin + oracle)

// Implementation in reentrancy.rs
pub fn reentrancy_enter(env: &Env) {
    if env.storage().temporary().has(&GuardKey::NonReentrant) {
        panic_with_error!(env, REENTRANT_ERROR_CODE);
    }
    env.storage().temporary().set(&GuardKey::NonReentrant, &true);
}

// Usage pattern
pub fn withdraw(env: Env, grant_id: u64, amount: i128) -> Result<(), Error> {
    nonreentrant!(env, {
        // Function logic here
    })
}

1. Oracle Price Deviation Guard

   • 50% deviation threshold
   • Sanity oracle confirmation required
   • Automatic freeze on suspicious prices

2. TVL Velocity Limit

   • 20% drain threshold in 6-hour window
   • Soft pause on breach
   • Admin verification required to resume

1. Document Hashing

   • Legal document CID storage
   • Signature requirements
   • Streaming prevention until compliance

2. Validator Tax

   • 5% ecosystem tax allocation
   • Separate accounting for validator shares
   • Transparent reporting

1. Critical: Fund loss, protocol compromise
2. High: Service disruption, security control bypass
3. Medium: Operational issues, partial functionality loss
4. Low: Minor bugs, cosmetic issues

1. Immediate protocol pause via admin functions
2. Multi-sig emergency meeting
3. Public disclosure within 24 hours
4. Patch deployment and testing
5. Gradual protocol resume

1. Admin assessment within 1 hour
2. Temporary mitigation deployment
3. Full investigation within 24 hours
4. Public disclosure if user impact

• Security Team: security@grantstream.org
• Admin Multi-sig: [Contact information in secure vault]
• Oracle Provider: [Contact information in secure vault]

1. Code Review Requirements

   • All changes require 2 reviewer approval
   • Security-sensitive code requires security team review
   • Automated security testing in CI/CD

2. Testing Standards

   • 95% code coverage required

   • Fuzz testing for all arithmetic operations
   • Integration testing with external contracts

3. Deployment Procedures

   • Multi-environment testing (dev → staging → prod)
   • Gradual rollout with monitoring
   • Automated rollback capabilities

1. Key Management

   • Hardware security modules (HSM) for private keys
   • Multi-party computation (MPC) for critical operations
   • Regular key rotation (quarterly)

2. Monitoring

   • 24/7 security monitoring
   • Real-time alerting for suspicious activities
   • Regular security audits and penetration testing

3. Governance

   • Documented change management procedures
   • Emergency response playbooks
   • Regular security training

1. Recommendations for Users

   • Use hardware wallets for large amounts
   • Verify all transactions before signing
   • Monitor grant statuses regularly

2. Educational Resources

   • Security best practices documentation
   • Tutorial videos and guides
   • Community support channels

Detailed mapping of all security-sensitive functions to their requirements and audit status. See AUDIT_READY.rs for the complete mapping.

Comprehensive threat models including attack trees and risk assessments for each protocol component.

Alignment with relevant security standards and regulatory requirements.

Key performance indicators for security posture and incident response effectiveness.

Last Updated: 2024-12-19
Next Review: 2025-01-19
Security Team: security@grantstream.org