[CT-13] Build DocumentExistenceCheckEndpoint

[mftee]

Problem

The only way to check whether a document hash exists on-chain is through the full verify endpoint, which queries Stellar and returns a large response. There is no lightweight existence check for use in high-frequency polling scenarios.

Proposed Solution

Create a document existence check endpoint inside contract/module/exists/ that returns a minimal boolean response.

Acceptance Criteria

• GET /module/exists/:hash returns a JSON object with exists (bool) and cached (bool) fields only — no transaction details
• Checks the Redis cache first using the same key as the verify endpoint
• Falls back to a Stellar account data_attr lookup if the cache misses
• Caches positive results (exists=true) with no TTL (document existence is permanent)
• Caches negative results (exists=false) with a 60-second TTL to allow for recent submissions to appear
• Validates hash format using HashValidator::validate_sha256 — returns 400 for invalid input
• Implementation files live inside contract/module/exists/

[adelekevictor12]

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

Please, I want to work on this issue
I have fallen in love with this

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

[Israel-light]

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

I’d like to work on this issue because it involves creating a lightweight document existence check endpoint optimized for high-frequency polling use cases.

I’m currently learning how backend systems balance performance and correctness using caching strategies like Redis alongside external data lookups. This issue is a good opportunity for me to implement a cache-first API pattern and understand how to reduce load on full verification endpoints while maintaining accurate results.

I understand the requirements around validating the hash format, checking Redis cache first, falling back to Stellar account data when needed, and properly caching both positive and negative results according to the specified TTL rules. I will ensure the endpoint remains minimal and efficient as described.

I’d like to take this on and implement a clean, performant solution.

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

[Zeemnew]

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

Hello maintainer, I would love to work on this issue

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

[rohitmulani63-ops]

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

Hey Maintainer

I can work on this one

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

[Ibinola]

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

I have reviewed the SMALDA contract layer in detail. The verify pipeline at lib.rs:322-367 shows the pattern — Redis cache check via CacheBackend, StellarClient::verify_hash fallback (Horizon /transactions?memo=), and result caching with 3600s TTL. The TypeScript stellar.service.ts already implements the data_attr lookup pattern (buildDataKey + account check) which is the lightweight path this issue requires.

I will implement the DocumentExistenceCheckEndpoint by:

1. Creating contract/module/exists/ with ExistenceResponse { exists: bool, cached: bool }
2. Validating :hash via HashValidator::validate_sha256 — returning 400 on invalid input
3. Checking Redis first with the same key as the verify endpoint (normalized hash) — cache hit returns { exists, cached: true }
4. On cache miss: loading the Stellar account and checking data_attr for a key built from the hash (buildDataKey pattern from stellar.service.ts), which avoids parsing transactions
5. Caching positive results (exists=true) with no TTL, negative results (exists=false) with 60s TTL
6. Registering the route at GET /module/exists/:hash in the app() router

This gives a sub-200-byte response with a single Redis hop on cache hit — ideal for high-frequency polling.

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

[drips-wave]

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

🧑‍💻 @Ibinola: 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 🌊

[grantfox-oss]

🦊 GrantFox — @Ibinola has been assigned to this issue!

Next steps:

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

Good luck! Track your progress on GrantFox.

[grantfox-oss]

🎉 This issue has been marked as completed on GrantFox!

@Ibinola's PR #592 was approved and merged by @mftee.

🏆 @Ibinola: You earned 35 FoxPoints for this contribution! Your current tier: Explorer (611 total points). Track your full progress on GrantFox.

👏 Great work, @Ibinola! Keep contributing to CodeGirlsInc.