feat: capabilities() bitmap

[Osifowora]

Closes #716

Description

Exposes contract capabilities as a u64 bitmap via a new capabilities() entrypoint. Clients can discover which features are available without inspecting the Wasm binary or relying on version-number heuristics. Each publicly-advertised contract feature occupies one bit in the returned u64.

This is a pure read — it performs no storage writes and emits no events, so it's safe to call at any time on any network (testnet, mainnet, future).

Changes

contracts/predictify-hybrid/src/capabilities.rs (new)

• capability sub-module: 26 named bit constants (VERSIONING, BETTING, DISPUTES, ORACLE_INTEGRATION, etc.) with full rustdoc
• capability_name() helper: Maps a single capability bit to its human-readable name
• capabilities() function: Returns the full capabilities bitmap as a u64 by bitwise-OR-ing all active capability flags
• 7 internal unit tests: non-zero bitmap, known capabilities set, reserved bits zero, capability_name known/unknown/multi-bit, determinism, repeated calls (no panics)

contracts/predictify-hybrid/src/lib.rs

• Added pub mod capabilities; module declaration (public so clients can import named constants)
• Added capabilities(env: Env) -> u64 entrypoint in #[contractimpl], delegating to crate::capabilities::capabilities(&env)

contracts/predictify-hybrid/src/test.rs

• Updated test_capabilities_list_and_no_state_change: now uses u64 bitmap with named capability::* constants instead of Vec<String> comparison
  • Verifies 10 known capability bits are set
  • Verifies bits 26–63 are zero (reserved)
  • Verifies no storage/event state change
• Updated test_version_and_capabilities_after_upgrade: now uses u64 bitmap assertions with named constants

docs/CAPABILITIES.md (new)

• Entrypoint signature and return value documentation
• Full bit assignment table (26 capabilities, bits 0–25)
• Client-side examples in both Rust/Soroban SDK and TypeScript/Stellar SDK
• Compatibility notes (adding/removing/renumbering bits)

Bit Assignments

Bit	Mask	Capability
0	0x0000_0000_0001	Versioning
1	0x0000_0000_0002	Upgrade management
2	0x0000_0000_0004	Query functions
3	0x0000_0000_0008	Market management
4	0x0000_0000_0010	Betting
5	0x0000_0000_0020	Disputes
6	0x0000_0000_0040	Oracle integration
7	0x0000_0000_0080	Governance
8	0x0000_0000_0100	Analytics
9	0x0000_0000_0200	Monitoring
10	0x0000_0000_0400	Fee management
11	0x0000_0000_0800	Audit trail
12	0x0000_0000_1000	Circuit breaker
13	0x0000_0000_2000	Rate limiting
14	0x0000_0000_4000	Event archive
15	0x0000_0000_8000	Metadata commitment
16	0x0000_0001_0000	Batch operations
17	0x0000_0002_0000	Recovery
18	0x0000_0004_0000	Multi-admin/multisig
19	0x0000_0008_0000	Statistics
20	0x0000_0010_0000	Token registry
21	0x0000_0020_0000	Event visibility
22	0x0000_0040_0000	Claim idempotency
23	0x0000_0080_0000	Bet cancellation
24	0x0000_0100_0000	Fee withdrawal
25	0x0000_0200_0000	Payout distribution

Bits 26–63 are reserved for future capabilities (read as 0).

[drips-wave]

@Osifowora Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits