fix(escrow): address issues #706 #707 #708 #709

[k-deejah]

closes #706 (instructions.rs) — create_escrow_multi: add is_token_allowed() check
before persisting the escrow so that the token allowlist is enforced
consistently with create_escrow_internal. Returns TokenNotAllowed when
the allowlist is enabled and the token is not present. is_token_allowed
is a no-op when the allowlist is disabled, so existing deployments are
unaffected.

closes #707 (internal.rs) — tally_votes: expand doc comment with detailed deadlock
scenario analysis (threshold=N unanimous split, M-of-N split where all
voters have cast), reference issue #707 (supersedes #667), and enumerate
three concrete on-chain escape hatch designs: admin timelock override,
expiration-based majority-rules fallback, and DAO escalation mechanism.

closes #708 (internal.rs) — payout_basket_tokens: replace the implicit index-0
skip with an explicit value-based filter against EscrowData.token. The
function now loads the escrow to obtain the primary token address and
skips any basket entry whose token field matches by value, making the
primary-token invariant explicit and safe against future reordering of
save_basket_tokens call sites.

closes #709 (admin.rs) — emergency_drain: add detailed doc comment explaining the
dual-signature requirement (buyer + seller), the liveness risk it creates
when a party is unresponsive, and a recommended admin-controlled timelock
override path for a future contract upgrade.

Pull Request Checklist

Thank you for contributing! Please review the following checklist to ensure your PR is ready for review.

Summary

• Provide a clear and concise description of the changes.
• Link to any related issues using Fixes #issue or Related to #issue.

Testing

• All new code is covered by unit tests where applicable.
• Existing tests pass locally (cargo test).
• Added tests for edge cases and error conditions.
• Updated any integration tests if necessary.

Documentation

• Updated README.md if changes affect users.
• Updated docstrings/comments for new/modified functions.
• Added examples or updated existing examples if applicable.

Code Quality

• Follows the project's coding style and conventions.
• No commented-out code or debug statements left in the codebase.
• Variables and functions are named descriptively.
• Code is properly formatted (cargo fmt).
• No new clippy warnings (cargo clippy).

Breaking Changes

• If this PR introduces breaking changes, describe them and provide migration steps.
• Updated version in Cargo.toml if appropriate (following semver).

Additional Notes

• Any other relevant information for reviewers.

Please ensure all checkboxes are checked before requesting a review.

[drips-wave]

@k-deejah 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