README.md

📚 Predictify Contracts Documentation

Welcome to the Predictify Contracts documentation! This directory contains comprehensive documentation for the Predictify Hybrid prediction market smart contract system.

📁 Documentation Structure

🚀 API Documentation

Complete API reference for Predictify Hybrid contract, including:

• Contract functions and their parameters
• Return types and error handling
• Integration examples
• Client usage patterns
• ReflectorAsset Coverage Matrix - Comprehensive asset testing and validation
• Token and Asset Management - Multi-asset and SAC Token support documentation
• Query Implementation Guide - Paginated query API, PagedResult<T>, security notes, and integrator quick-start
  • NEW: Dashboard Statistics Queries - Platform aggregates, market metrics, leaderboards with stable field versioning

🔒 Security Documentation

Comprehensive security documentation and guidelines:

• Attack Vectors - Known attack vectors and mitigation strategies
• Audit Checklist - Security audit requirements and checklist
• Soroban SDK Workspace Audit - Workspace Soroban SDK target, verification steps, and audit notes for Protocol 25 alignment
• Security Best Practices - Development and deployment security guidelines
• Security Considerations - Important security considerations for the system
• Security Testing Guide - Executable security checklist mapped to automated tests

⛽ Gas Optimization Documentation

Complete gas optimization and cost analysis:

• Gas Benchmarking - Performance benchmarks and metrics
• Gas Case Studies - Real-world gas optimization examples
• Gas Cost Analysis - Detailed cost breakdown and analysis
• Gas Monitoring - Tools and techniques for monitoring gas usage
• Gas Optimization - Strategies and best practices for gas optimization
• Gas Testing Guidelines - Testing procedures for gas optimization
• Gas Troubleshooting - Common gas-related issues and solutions

🛠️ Operations Documentation

Operational procedures and incident management:

• Incident Response - Incident response procedures and protocols

📋 Contract Documentation

Implementation-specific documentation for the Predictify Hybrid contract:

• Types System - Comprehensive type system and data structures
• Voting System - Voting mechanism and dispute resolution

💰 Claims Documentation

Claim idempotency and payout tracking:

• Claim Idempotency Guide - Comprehensive guide to idempotent winnings claims

🎯 Quick Start

1. For Developers: Start with API Documentation
2. For Dashboard Integrators: Review Dashboard Statistics Queries in the Query Implementation Guide
3. For Contract Contributors: Review Contract Documentation
4. For Security Auditors: Review Security Documentation
5. For Gas Optimization: Check Gas Optimization
6. For Operations: Read Incident Response

📊 Dashboard Statistics Queries

NEW: The Query Implementation Guide now includes comprehensive Dashboard Statistics Queries with:

• Platform-Level Aggregates - get_dashboard_statistics() for TVL, active users, and total metrics
• Per-Market Metrics - get_market_statistics() for consensus strength and volatility
• Category Analytics - get_category_statistics() for filtered market data
• User Leaderboards - get_top_users_by_winnings() and get_top_users_by_win_rate() for rankings

All response types use stable V1 versioning for forward compatibility without breaking changes.

Use cases: Dashboard display, analytics filtering, leaderboard rendering, TVL tracking

🔗 Related Resources

• Main Project README - Project overview and setup instructions
• Contracts Directory - Source code for all smart contracts
• Predictify Hybrid: Reproducible WASM Builds & Checksums
• GitHub Repository - Source code repository

📝 Contributing to Documentation

When adding new documentation:

1. Choose the appropriate category based on the content type
2. Follow the naming convention (UPPERCASE_WITH_UNDERSCORES.md)
3. Update this index to include the new document
4. Add cross-references to related documents where appropriate

🏷️ Documentation Categories

• API: Contract interfaces, function references, and integration guides
• Contracts: Implementation-specific documentation for contract systems
• Security: Security audits, best practices, and threat analysis
• Gas: Performance optimization, cost analysis, and monitoring
• Operations: Deployment, maintenance, and incident management

---

Last updated: 2026-03-30 For questions or suggestions about documentation, please open an issue in the repository.