Classification: CONFIDENTIAL — DAO Core Team Only
Last Updated: 2026-07-25
Audit Status: Ready for external audit

1. Trust Model
2. Known Assumptions
3. Emergency Procedures
4. Bug Bounty Program
5. Role-Based Access Control
6. Security Features by Component
7. Threat Model
8. Dependencies & Supply Chain

graph TB
    subgraph "Trusted"
        A[DAO Admin Multi-Sig]
        B[Compliance Officer]
        C[Price Oracle Updater]
    end

    subgraph "Semi-Trusted"
        D[Utility Providers]
        E[Grid Administrator]
        F[Finance Wallets]
        G[Nonce Reset Authorities]
    end

    subgraph "Untrusted"
        H[End Users]
        I[IoT Devices]
        J[Ghost Sweeper Relayers]
    end

    A -->|governs| K((EquipChain Contract))
    B -->|legal freeze/unfreeze| K
    C -->|price feed| K
    D -->|manage streams| K
    E -->|tariff schedules| K
    F -->|multi-sig withdrawals| K
    G -->|nonce resets| K
    H -->|use service| K
    I -->|send usage data| K
    J -->|prune ghost streams| K

1. Ledger timestamps are monotonic and trusted — Soroban provides ledger timestamps that are cryptographically committed. The contract relies on these for all time-based calculations (peak hours, deadlines, cooldowns).

2. Ed25519 signatures are secure — The contract uses Soroban's built-in ed25519_verify. Security depends on the host function implementation and the device's key management.

3. Token contracts are Standard Asset Contracts (SAC) — All token interactions assume SAC-compliant contracts with standard transfer, balance, burn interfaces.

4. Cross-contract calls are atomic — Soroban guarantees atomic execution within a single contract invocation. No partial state updates.

5. Storage is durable — Contract instance storage persists across invocations. Temporary storage has TTL limitations.

1. Oracle is regularly updated — MAX_PRICE_AGE_SECONDS (300s) requires the price updater to push updates at least every 5 minutes.

2. Devices send heartbeats within threshold — HEARTBEAT_THRESHOLD_SECONDS (3600s) means devices must heartbeat at least hourly.

3. Providers monitor their streams — The contract emits events but relies on providers to detect and respond to anomalies.

4. Multi-sig coordination happens off-chain — The contract enforces thresholds but does not manage the off-chain coordination process.

For detailed runbooks covering 13 incident scenarios, see the full audit-ready runbook embedded in README.md. Key scenarios:

Level 1 (Immediate): DAO Admin → Compliance Officer
Level 2 (15 mins):  Grid Administrator → Finance Wallets
Level 3 (30 mins):  All Providers → Security Team
Level 4 (1 hour):   Community → Public Relations

EquipChain operates a bug bounty program for the contracts in this repository. Security researchers are encouraged to responsibly disclose vulnerabilities.

In Scope:

• All contract code in contracts/utility_contracts/src/
• All contract code in contracts/price_oracle/src/
• Build and deployment scripts

Out of Scope:

• Third-party dependencies (Soroban SDK, etc.)
• Infrastructure-level attacks on the Stellar network
• Phishing attacks on users
• Already documented issues

1. Report vulnerabilities to security@equipchain.io
2. Do not post details publicly until the fix is deployed
3. Allow 7 days for critical/high fixes before public disclosure
4. Include clear reproduction steps and impact analysis

Rewards are based on:

• Impact severity (financial loss, data breach, service disruption)
• Quality of the report (clear PoC, reproduction steps)
• Novelty of the attack vector

• Replay attack prevention via strictly incrementing u64 nonces
• +1 to +5 tolerance window for UDP jitter
• Multi-sig nonce reset for compromised devices
• Suspicious device auto-detection
• Full audit trail

• 24-hour notice period for tariff changes
• Cryptographic signature verification
• Grid administrator access control
• Temporary storage optimization
• Seamless rate interpolation across windows

• 90-day threshold before pruning
• Cryptographic archive hashes for integrity
• Gas bounty incentives for relayers
• Protection for streams with pending buffers
• Historical audit trail preservation

• Contract whitelisting with function-level permissions
• Call depth limits (max 5) to prevent reentrancy
• Gas limits per cross-contract call
• Rate limiting (10 calls per 60s window)
• Emergency disable capability

• Per-stream and global 24h rolling limits
• Anomalous activity event emission
• Admin multi-sig overrides for false positives
• Auto-reset at day boundaries

• Minimum 2, maximum 7 authorized signers
• Configurable approval threshold
• 48-hour timelock default (min 24h)
• 14-day proposal expiry
• Cancellation by proposer

• All dependencies are pinned to specific versions
• soroban-sdk is developed by Stellar Development Foundation — a trusted entity
• CI/CD pipeline verifies dependency integrity via Cargo.lock
• WASM binaries are reproducible from source
• No vendored or forked dependencies

This document is confidential. For authorized personnel only.