Add a contract-existence reader (contract_exists) to avoid panicking probe calls

[mikewheeleer]

Add a contract-existence reader (contract_exists) to avoid panicking probe calls

Description

The only way to check whether a contract_id exists today is to call get_contract, which panics with ContractNotFound for unknown ids (per contracts/escrow/src/lib.rs). Clients and indexers iterating an id range must catch panics or pre-know the range, which is awkward and wasteful.

This issue adds a cheap, non-panicking contract_exists(contract_id) -> bool so callers can probe ids safely.

Requirements and context

• Repository scope: Talenttrust/Talenttrust-Contracts only.
• Add contract_exists returning env.storage().persistent().has(&DataKey::Contract(contract_id)).
• Do not extend TTL on a pure existence probe (document this), so probing cannot be abused to keep entries alive.
• Add a companion get_next_contract_id() reader so indexers know the allocation high-water mark.
• Document both readers.

Suggested execution

• Fork the repo and create a branch
• git checkout -b feature/contracts-existence-reader
• Implement changes
  • Write code in: contracts/escrow/src/lib.rs.
  • Write comprehensive tests in: contracts/escrow/src/test/contract_id_allocation.rs.
  • Add documentation: add both readers to the entrypoint reference under docs/escrow.
  • Include NatSpec-style doc comments (///) on both readers.
  • Validate security: existence probe does not mutate or extend TTL.
• Test and commit

Test and commit

• Run cargo fmt --all -- --check, cargo build, and cargo test.
• Cover existing id, missing id, and next-id high-water mark.
• Include the full cargo test output in the PR description.

Example commit message

feat: add contract_exists and get_next_contract_id readers

Guidelines

• Minimum 95 percent test coverage for impacted modules.
• Clear, reviewer-focused documentation.
• Timeframe: 96 hours.

Community & contribution rewards

• 💬 Join the TalentTrust community on Discord for questions, reviews, and faster merges: https://discord.gg/WqnGpcPx
• ⭐ This is a GrantFox OSS / Official Campaign task and may be rewarded. When your PR is merged you'll be prompted to rate the project — if this issue and the maintainers helped you ship, we'd be grateful for a 5-star rating. Clear questions in Discord and tidy, well-tested PRs are the fastest path to a merge and a reward.

[esenyidaniel-hash]

@esenyidaniel-hash has applied to work on this issue as part of the Stellar Wave Program's 6th wave.

Please can I be assign this issue to work on?

ℹ️ Repo Maintainers: To accept this application, review their application or assign @esenyidaniel-hash to this issue.

[grantfox-oss]

🦊 GrantFox — @esenyidaniel-hash has been assigned to this issue as part of the Official Campaign campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #560)
2. Your PR will be reviewed by the Talenttrust maintainers

Good luck! Track your progress on GrantFox.

[drips-wave]

Congratulations, @esenyidaniel-hash! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on June 30, 2026.

🧑‍💻 @esenyidaniel-hash: Please resolve the issue such that the repo's maintainers have enough time to review your contribution before the due date. You'll earn Points for completing the issue on-time, which will make you eligible for a share of the Stellar Wave Program's reward pool.

Warning

When opening a PR, please link it to this issue to ensure it gets tracked accurately. Points are awarded when this issue is marked as completed by the maintainer.

🤠 Repo maintainers: Please keep an eye on the contributor's progress and review their work before the due date. You can manage this issue, including adjusting its complexity and points, here.

🌊 Happy Wave 🌊