Document the oracle-resolution and dispute-attack threat model and security architecture

[greatest0fallt1me]

Description

The repo has security notes (docs/security/ATTACK-VECTORS.md, docs/security/SECURITY_CONSIDERATIONS.md) but lacks a single, code-grounded threat model tying the oracle and dispute subsystems' defenses to their implementations. With weighted-consensus, per-market staleness config, and dispute rate-limiting in flight, a consolidated threat-model document will keep contributors and auditors aligned. This issue adds that document, citing real modules and error codes.

Requirements and context

• Oracle defenses to document: sequential multi-source fetch + majority consensus (OracleIntegrationManager in contracts/predictify-hybrid/src/oracles.rs, threshold DEFAULT_CONSENSUS_THRESHOLD = 66), staleness validation (validate_oracle_data -> Error::OracleStale, DEFAULT_MAX_STALENESS_SECS, per-market EventOracleValidationConfig), confidence bounds (Error::OracleConfidenceTooWide), and the oracle whitelist (OracleWhitelist).
• Dispute defenses to document: minimum stake (MIN_DISPUTE_STAKE), the voting window, stake-weighted tally with exact-tie -> oracle-stands, and double-dispute prevention (Error::AlreadyDisputed); note the absence of dispute rate-limiting as a known gap (tracked separately).
• Each documented threat (oracle manipulation, stale-price exploitation, dispute griefing/spam, tie manipulation) must reference the concrete defense and the relevant Error variant in contracts/predictify-hybrid/src/err.rs.
• Non-functional: the doc must live under docs/security/, link from docs/README.md, and avoid duplicating ATTACK-VECTORS.md (cross-reference instead).

Acceptance criteria

• A new docs/security/THREAT_MODEL.md (or similarly named) enumerates oracle and dispute threats with mitigations.
• Each threat cites the implementing module/function and the relevant Error variant.
• Known gaps (e.g. missing dispute rate-limiting) are listed and cross-linked to their tracking issues.
• The document is linked from docs/README.md and references (not duplicates) ATTACK-VECTORS.md and SECURITY_CONSIDERATIONS.md.
• A maintainer can trace each claimed defense to real code via the citations.

Suggested execution

1. Fork the repo and create a branch — git checkout -b feature/threat-model-doc.
2. Implement changes — add docs/security/THREAT_MODEL.md; update docs/README.md index.
3. Write/extend tests — documentation only; verify all cited symbols exist via grep against contracts/predictify-hybrid/src.
4. Test and commit

cargo fmt --all -- --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test -p predictify-hybrid

Example commit message

docs: add oracle and dispute threat-model and security-architecture document

Guidelines

Documentation coverage of all oracle/dispute defenses is expected; keep every citation verifiable against the source. Cross-reference API_DOCUMENTATION.md (Security Features, Oracle/Dispute Management). Timeframe: 96 hours.

[DevSolex]

Hi Maintainer,

I’m a smart contract and full-stack developer and would love to contribute to this issue. I’m an experienced contributor with hands-on expertise in Rust, Soroban, Cairo, and TypeScript.

I’m passionate about building secure, scalable blockchain solutions, with a strong emphasis on writing clean and maintainable code. Based on the scope of this issue, I’m confident I can deliver a complete solution within 24 hours of assignment.

I’d greatly appreciate the opportunity to contribute and help move this forward.