docs: resolve issues 895-898 documentation updates

[benjaminjohnsonfin-afk]

Summary

Documentation updates addressing technical gaps and clarity improvements across multiple docs:

• Update docs/threat-model.md to close out the #781 treasury-trustline note #895: Resolve treasury-trustline issue in threat-model.md (PR fix(#831-#834): staleness boundary tests, full lifecycle cross-contra… #942 fix confirmed)
• Reconcile docs/api-reference.md with the currently-stubbed handlers #896: Mark stubbed API handlers in api-reference.md for clarity
• Add a "known limitations" section to docs/atomic-swap.md #897: Add known limitations section to atomic-swap.md documenting disabled test modules
• Update docs/commitment-scheme.md with the partial-disclosure differential-test invariant #898: Enhance commitment-scheme.md with differential test invariant and performance benchmarks

Changes Made

Issue #895 - threat-model.md

• Updated bond forfeiture destination from placeholder to actual protocol treasury
• Changed status from "⚠️ Partially mitigated" to "✅ Mitigated"
• Added PR fix(#831-#834): staleness boundary tests, full lifecycle cross-contra… #942 reference

Issue #896 - api-reference.md

• Added "Not yet implemented" markers for stubbed API handlers:
  • batch_commit_ip (line 752 in handlers.rs)
  • verify_commitment (line 167 in handlers.rs)
  • transfer_ip (line 138 in handlers.rs)
  • get_ip (line 117 in handlers.rs)
• Clarifies contract functionality exists but REST API integration is pending

Issue #897 - atomic-swap.md

• Added "Known Limitations / Test Coverage Gaps" section
• Documents currently-disabled test modules: tests, regression_tests, benchmarks
• Lists recently re-enabled test suites with associated fix issues (Re-enable batch_swap_features_tests.rs and fix the underlying treasury bug #825, Consolidate hardcoded protocol treasury address across contract and tests #831, Add explicit test for validate_upgrade-equivalent logic in upgrade.rs #832, Dispute resolution is a single-key instant ruling with none of the threat model's documented safeguards implemented #781, Audit and fix the arbitration_tests.rs re-enable for full correctness #830, Re-enable prop_tests.rs (property-based tests) #828, Re-enable chaos_tests.rs #829)
• Clarifies implications for integrators regarding test coverage

Issue #898 - commitment-scheme.md

• Enhanced differential invariant section (Add differential test between zk_commitment and verify_commitment #818) with performance benchmarks
• Added CPU instruction budgets for both verification paths:
  • SHA-256 full-reveal: ≤200,000 instructions
  • ZK Schnorr (single): ≤5,000,000 instructions
  • ZK Schnorr (batch of 10): ≤50,000,000 instructions
• Added guidance for choosing between privacy-focused vs performance-optimized paths

Closes #895
Closes #896
Closes #897
Closes #898

[drips-wave]

@benjaminjohnsonfin-afk 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