feat(credits): add balance verification endpoint

[syed-ghufran-hassan]

• Add verify_balance function to enable credit availability checks without modifying state. This improves UX by allowing callers to validate sufficient credits before attempting spend operations, reducing failed transactions and providing audit visibility through balance verification events.

Summary by CodeRabbit

• New Features

  • Added a new balance verification entrypoint to check whether a user has sufficient credits for a requested amount.

• Improvements

  • Strengthened credit spending validation by introducing an explicit balance check and recording verification requests to prevent duplicate processing.

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds a verify_balance public entrypoint to contracts/profile/src/credits.rs that checks a user's stored credit balance against a requested amount, enforces caller/pause/idempotency invariants, emits a BalanceVerified event, and returns a boolean. Also adds clarifying comments to the spend function's insufficient-credits check.

Changes

Credits Verification and Spend Flow

Layer / File(s)	Summary
New verify_balance entrypoint contracts/profile/src/credits.rs	Adds verify_balance(env, user, amount, op_id) -> Result<bool, Error> that validates the events-contract caller, unpaused state, and op_id idempotency; loads the profile (returning ProfileNotFound if absent); computes has_sufficient = credits >= amount; emits BalanceVerified event; marks op_id as seen; returns the boolean.
spend insufficient-credits documentation contracts/profile/src/credits.rs	Adds explanatory comment and whitespace formatting around the existing insufficient-credits check that loads the profile and returns Error::InsufficientCredits when profile.credits < amount; no behavioral changes to the control flow.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Poem

🐇 A new way to verify what credits remain,
With op_id idempotency—no dupes to maintain,
Events emit the truth: do you have enough?
And spend's guard now wears comments more buff,
Clear logic, clear path, a profile well-read,
This hop through the contracts is steady ahead! ✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 66.67% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'feat(credits): add balance verification endpoint' directly and accurately describes the main change: adding a new verify_balance endpoint to the credits module.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@contracts/profile/src/credits.rs`:
- Around line 75-88: The profile loading and credit verification logic is
duplicated in the credit handling function. The storage::get_profile call and
the profile.credits check appear twice consecutively, with the first profile
binding immediately shadowed by the second. This wastes a redundant storage read
and creates confusion. Remove the first instance of the duplicated profile
loading and insufficient credits check block, keeping only one occurrence of
storage::get_profile and the credits validation.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 804ec8c1-5686-4616-9097-5e637b49d7f2

📥 Commits

Reviewing files that changed from the base of the PR and between d3a32bd and 37a549f.

📒 Files selected for processing (1)

• contracts/profile/src/credits.rs

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

contracts/profile/src/credits.rs (1)

79-83: ⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Comment is misleading relative to implementation.

Line 79 says “Use verify_balance logic directly,” but this block does not invoke verify_balance; it reimplements the check inline. Please reword the comment (or call a shared helper) to avoid drift/confusion.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@contracts/profile/src/credits.rs` around lines 79 - 83, The comment on line
79 stating "Use verify_balance logic directly" is misleading because the code
reimplements the balance check inline rather than calling a verify_balance
helper function. Either update the comment to accurately describe the inline
reimplementation of the balance check (comparing profile.credits against
amount), or refactor the code to call a shared verify_balance helper function
and update the comment accordingly to reflect the actual implementation being
used.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Outside diff comments:
In `@contracts/profile/src/credits.rs`:
- Around line 79-83: The comment on line 79 stating "Use verify_balance logic
directly" is misleading because the code reimplements the balance check inline
rather than calling a verify_balance helper function. Either update the comment
to accurately describe the inline reimplementation of the balance check
(comparing profile.credits against amount), or refactor the code to call a
shared verify_balance helper function and update the comment accordingly to
reflect the actual implementation being used.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 9edef42c-4552-4f01-9b2d-2a1c42b4c89f

📥 Commits

Reviewing files that changed from the base of the PR and between 37a549f and 9dbf968.

📒 Files selected for processing (1)

• contracts/profile/src/credits.rs