fix(vault): drop unimplemented capability bits, add entrypoint-mappin…

[Anadudev]

Closes #1116

Drop unimplemented features from vault capabilities

Summary

capabilities.rs previously advertised six bits for features that have
no vault entrypoint today. Integrators that feature-detect via
capabilities() would receive 1 for a missing entrypoint, leading to
runtime failures and eroding trust in the capability contract (bits must
be stable and truthful).

This PR audits every bit against CalloraVault's public functions,
clears bits for missing features (keeping their positions permanently
reserved so they are never reassigned), adds a comprehensive test suite
that maps every set bit to at least one existing client method, and
updates docs/CAPABILITIES.md to match.

---

Affected modules

File	Role
contracts/vault/src/capabilities.rs	Bit-flag definitions and ALL_CAPABILITIES constant
contracts/vault/src/test_capabilities.rs	New test suite (29 tests)
contracts/vault/src/lib.rs	Added mod test_capabilities; declaration
contracts/vault/src/test_value_conservation.rs	Added missing Events as _ import
docs/CAPABILITIES.md	Bit registry and integration guide

---

What changed and why

capabilities.rs

The six reserved-bit constants are kept as named sentinels so their
bit positions can never be accidentally reused in a future version:

Bit 6  - CAP_OFFERING_METADATA   (reserved, cleared)
Bit 7  - CAP_PRICE_REGISTRY      (reserved, cleared)
Bit 12 - CAP_REVENUE_POOL        (reserved, cleared)
Bit 13 - CAP_RATE_LIMIT          (reserved, cleared)
Bit 14 - CAP_ADMIN_BROADCAST     (reserved, cleared)
Bit 16 - CAP_SLIPPAGE_GUARD      (reserved, cleared)

ALL_CAPABILITIES now ORs together only the 12 bits that
correspond to callable vault entrypoints:

0x0000_0000_0002_8F3F
  Bits set: 0 1 2 3 4 5 8 9 10 11 15 17

All doc-comments on reserved constants explicitly state:

• the bit position is permanently reserved
• the constant is always 0 in capabilities()
• the feature that was formerly planned (for auditability)

test_capabilities.rs (new - 29 tests)

Category	Tests
Exact mask assertion	capabilities_equals_exact_expected_mask, capabilities_equals_all_capabilities_constant
Each supported bit IS set (12 tests)	cap_deposit_is_set, cap_withdraw_is_set, ... cap_upgrade_is_set
Each reserved bit IS cleared (6 tests)	cap_offering_metadata_is_cleared, cap_price_registry_is_cleared, ... cap_slippage_guard_is_cleared
Bit-position stability	bit_positions_are_stable - locks every constant to its hex value
Entrypoint mapping	every_set_capability_maps_to_callable_vault_entrypoint - calls the real client method for every set bit
Edge/invariant	capabilities_is_idempotent, capabilities_available_before_init, reserved_bits_are_zero, all_reserved_bits_are_cleared_in_all_capabilities, all_supported_bits_match_all_capabilities_decomposition, all_capabilities_bits_are_power_of_two_distinct

lib.rs

Added the #[cfg(test)] mod test_capabilities; declaration so the new
module is compiled and exercised by cargo test.

docs/CAPABILITIES.md

• Updated the active mask header from the stale value to 0x0000_0000_0002_8F3F.
• Updated the bit-registry table: reserved bits are marked *(reserved)* - no entrypoint implemented with status reserved (cleared).
• Updated the TypeScript constant block: reserved constants annotated with // Reserved (cleared).
• Added a Stability guarantee section documenting the reserved-bit contract.

---

Criteria mapping

Acceptance criterion	Where addressed
Every set bit corresponds to a callable vault entrypoint	every_set_capability_maps_to_callable_vault_entrypoint test; ALL_CAPABILITIES definition
Bits for removed features are documented as reserved	capabilities.rs doc-comments; CAPABILITIES.md bit-registry table
test_capabilities.rs compiles and asserts the exact mask	capabilities_equals_exact_expected_mask + EXPECTED_EXACT_MASK = 0x0000_0000_0002_8F3F
CAPABILITIES.md matches the mask	Header and TypeScript block updated to 0x28F3F

---

Security and failure-mode analysis

• No entrypoint removed. Only the bitmap constant is corrected. On-chain behaviour of every existing function is unchanged.
• Reserved positions never reassigned. Constants for cleared bits are retained as compile-time sentinels. Any future PR that tries to re-OR them into ALL_CAPABILITIES will immediately fail the all_reserved_bits_are_cleared_in_all_capabilities test.
• capabilities() is a pure view. It reads a compile-time constant; no state, auth, or external calls are involved. There is no surface for reentrancy, front-running, or access-control bypass.
• Integrator impact. Integrators that previously observed a 1 for a reserved bit and attempted to call a non-existent entrypoint would already have encountered a runtime trap. Clearing the bit is strictly safer: a 0 tells integrators the feature is absent before they attempt the call.

---

Test run

cargo test -p callora-vault capabilities

running 29 tests
test test_capabilities::all_capabilities_bits_are_power_of_two_distinct ... ok
test test_capabilities::all_reserved_bits_are_cleared_in_all_capabilities ... ok
test test_capabilities::all_supported_bits_match_all_capabilities_decomposition ... ok
test test_capabilities::bit_positions_are_stable ... ok
test test_capabilities::cap_admin_broadcast_is_cleared ... ok
test test_capabilities::cap_authorized_caller_is_set ... ok
test test_capabilities::cap_batch_deduct_is_set ... ok
test test_capabilities::cap_depositor_allowlist_is_set ... ok
test test_capabilities::cap_deposit_is_set ... ok
test test_capabilities::cap_deduct_is_set ... ok
test test_capabilities::cap_offering_metadata_is_cleared ... ok
test test_capabilities::cap_pause_is_set ... ok
test test_capabilities::cap_price_registry_is_cleared ... ok
test test_capabilities::cap_rate_limit_is_cleared ... ok
test test_capabilities::cap_request_idempotency_is_set ... ok
test test_capabilities::cap_revenue_pool_is_cleared ... ok
test test_capabilities::cap_settlement_is_set ... ok
test test_capabilities::cap_slippage_guard_is_cleared ... ok
test test_capabilities::cap_two_step_admin_is_set ... ok
test test_capabilities::cap_two_step_ownership_is_set ... ok
test test_capabilities::cap_upgrade_is_set ... ok
test test_capabilities::cap_withdraw_is_set ... ok
test test_capabilities::capabilities_available_before_init ... ok
test test_capabilities::capabilities_equals_all_capabilities_constant ... ok
test test_capabilities::capabilities_equals_exact_expected_mask ... ok
test test_capabilities::capabilities_is_idempotent ... ok
test test_capabilities::capabilities_returns_nonzero ... ok
test test_capabilities::every_set_capability_maps_to_callable_vault_entrypoint ... ok
test test_capabilities::reserved_bits_are_zero ... ok

test result: ok. 29 passed; 0 failed; 0 ignored

---

Non-goals

• No typo-only or formatting-only changes.
• No unrelated refactors, dependency upgrades, or broad rewrites.
• No safeguards removed or validation weakened.

[drips-wave]

@Anadudev 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