Document and reconcile the published query API against the QueryManager gap analysis

[greatest0fallt1me]

Description

contracts/predictify-hybrid/src/queries.rs carries an in-code "Gap Analysis (2026-04-23)" doc-comment listing getters that are missing or inconsistent versus the published API spec (for example get_oracle_resolution, get_dispute_stats, list_proposals, get_config, and the stubbed query_contract_state metrics). API_DOCUMENTATION.md does not clearly mark which of these are implemented today. This issue reconciles the two so integrators know exactly what is callable.

Requirements and context

• Source of truth in code: the Gap Analysis block at the top of contracts/predictify-hybrid/src/queries.rs and the actual pub fn set on QueryManager (e.g. query_admin_role, query_has_permission, query_user_balance, query_market_pool, query_contract_state, the paged variants get_all_markets_paged / query_user_bets_paged).
• API_DOCUMENTATION.md has a "Query Functions" section (line ~249) that must be updated to mark each listed getter as Implemented / Stubbed / Planned, matching reality.
• Where a getter exists in disputes.rs, oracles.rs, or governance.rs but is not surfaced via QueryManager, note the actual call path so integrators are not misled.
• Cross-link the stubbed-metrics items (query_user_balance, query_market_pool, query_contract_state) to their implementation issue.
• Non-functional: documentation must be accurate at time of writing; include the verification method (grep against source) so it can be re-checked.

Acceptance criteria

• API_DOCUMENTATION.md "Query Functions" marks each getter from the Gap Analysis as Implemented, Stubbed, or Planned.
• Getters that live outside QueryManager are documented with their real call path.
• Stubbed-metric fields are flagged and linked to the relevant implementation issue.
• The queries.rs Gap Analysis doc-comment is updated to match the reconciled documentation (or dated/superseded).
• Every documented function name is verified to exist in the source.

Suggested execution

1. Fork the repo and create a branch — git checkout -b feature/query-api-reconciliation.
2. Implement changes — update API_DOCUMENTATION.md and the Gap Analysis doc-comment in contracts/predictify-hybrid/src/queries.rs.
3. Write/extend tests — documentation only; verify each name with grep -n "pub fn <name>" 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: reconcile query API documentation with QueryManager gap analysis

Guidelines

Documentation must cover every getter named in the Gap Analysis with a verifiable status. Keep doc-comments and API_DOCUMENTATION.md (Query Functions) in sync. 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.