fix: correct same-tx CAS idiom in spend_vault docs and example

[kosedogus]

A same-tx allowance<T>() read cannot serve as a CAS guard, the shared Vault is locked for the whole tx, so the read trivially matches and EUnexpectedAllowance never fires on a mismatch.

• Docs now say to derive expected from an earlier (off-chain / prior-tx) read,
• direct_delegation::change_budget takes expected: u64 from the caller instead of self-reading,
• A new test pinning the stale-read abort.
  Library code unchanged (comment-only); 177/177 tests pass.

Summary by CodeRabbit

• Bug Fixes

  • Improved allowance update safety: concurrent spends won’t be overwritten. When the provided expected value is stale (or the allowance entry is absent), the update now aborts instead of clobbering a newer spend.

• Documentation

  • Clarified set_allowance CAS “Lifecycle” behavior, including how same-transaction and cross-transaction check-then-act scenarios can fail safely.

• Examples & Tests

  • Updated the direct delegation budget-change example to pass an expected pre-read value.
  • Added a negative test asserting abort on stale expected values.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: d1b2a230-f911-4eb9-a695-60fff2452603

📥 Commits

Reviewing files that changed from the base of the PR and between d0380ee and baf8c86.

📒 Files selected for processing (2)

• contracts/allowance/examples/spend_vault/tests/direct_delegation_tests.move
• contracts/allowance/sources/spend_vault.move

✅ Files skipped from review due to trivial changes (1)

• contracts/allowance/sources/spend_vault.move

🚧 Files skipped from review as they are similar to previous changes (1)

• contracts/allowance/examples/spend_vault/tests/direct_delegation_tests.move

---

📝 Walkthrough

Walkthrough

change_budget now takes a caller-provided expected allowance value and uses it as the CAS guard. The lifecycle example, tests, README, and module docs were updated to describe and verify stale-expected abort behavior.

Changes

CAS-guarded change_budget update

Layer / File(s)	Summary
change_budget signature and implementation contracts/allowance/examples/spend_vault/direct_delegation.move	change_budget<T> now accepts expected before new_budget and passes it to set_allowance as option::some(expected) instead of reading the current allowance on-chain.
Test updates and new abort test contracts/allowance/examples/spend_vault/tests/direct_delegation_tests.move	Tx 4 now uses the pre-read remaining value 250, and a new test checks that a stale expected value 400 aborts with EUnexpectedAllowance.
CAS guard documentation contracts/allowance/README.md, contracts/allowance/sources/spend_vault.move	README and module docs now describe abort-on-stale-expected CAS behavior, including cross-tx check-then-act requirements and absent-entry aborts.

Estimated code review effort: 2 (Simple) | ~12 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Owner
  participant DirectDelegation
  participant SpendVault

  Owner->>DirectDelegation: change_budget(expected, new_budget, ...)
  DirectDelegation->>SpendVault: set_allowance(cap_id, option::some(expected), new_budget, ...)
  SpendVault-->>SpendVault: compare expected vs current remaining
  alt expected matches
    SpendVault-->>DirectDelegation: allowance updated
  else stale expected
    SpendVault-->>DirectDelegation: abort EUnexpectedAllowance
  end

Loading

Possibly related PRs

• OpenZeppelin/contracts-sui#402: Both PRs touch the change_budget flow and its CAS guarding via spend_vault::set_allowance in the same example file.

Suggested reviewers: bidzyyys, immrsd, ericnordelo, 0xNeshi

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main change: correcting the CAS idiom in spend_vault docs and the example.
Description check	✅ Passed	The description explains the change well and covers tests, but it omits the issue reference and PR checklist from the template.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
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.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/allowance-cas-idiom-docs

---

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.}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 96.68%. Comparing base (779a9d2) to head (baf8c86).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #455      +/-   ##
==========================================
+ Coverage   96.62%   96.68%   +0.05%     
==========================================
  Files          34       34              
  Lines        3405     3405              
  Branches      793      794       +1     
==========================================
+ Hits         3290     3292       +2     
  Misses         70       70              
+ Partials       45       43       -2     

Flag	Coverage Δ
contracts/access	65.46% <ø> (ø)
contracts/allowance	52.40% <ø> (ø)
contracts/finance	26.07% <ø> (ø)
contracts/timelock	54.57% <ø> (ø)
contracts/utils	44.09% <ø> (ø)
math/core	87.12% <ø> (+0.14%)	⬆️
math/fixed_point	63.70% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[ericnordelo]

LGTM!

[bidzyyys]

LGTM

[bidzyyys]

Review — allowance

• ⚪ spend_vault.move:98, 661-662 — new doc prose uses em dashes (—), which STYLEGUIDE.md:255 forbids in all prose/comments/docs (the file had none before this PR) → replace each — with a regular -.
• ⚪ examples/spend_vault/tests/direct_delegation_tests.move:210 — same em-dash violation in the new test's comment → replace — with -.