docs: document single-writer transaction requirement

[QuantumExplorer]

Summary

• Documents the single-writer transaction constraint for GroveDb, addressing audit finding feat: Simple checkpoint #9 about optimistic transaction isolation gaps
• Adds doc comments to GroveDb struct, start_transaction, commit_transaction, rollback_transaction, the Storage trait, and RocksDbStorage struct
• Explains why this is a documentation issue rather than a code fix: Rust's type system already prevents the worst concurrent access patterns (!Sync on StorageBatch/MerkCache), RocksDB catches conflicting writes at commit time, and Dash Platform processes blocks sequentially

Analysis

GroveDb uses RocksDB's OptimisticTransactionDB which is Send + Sync, making GroveDb itself shareable across threads. However, there is no Mutex or RwLock enforcing single-writer access. The analysis found:

1. RocksDB level: OptimisticTransactionDB permits concurrent transactions but detects write conflicts at commit time (returning Busy/TryAgain)
2. Rust type system: StorageBatch uses RefCell (!Sync) and MerkCache uses UnsafeCell (!Sync), preventing sharing a single transaction's state across threads
3. GroveDb level: No application-level mutex, but in-memory Merk tree state (hashes, balancing, root propagation) built during a transaction cannot be cheaply unwound on commit failure
4. Dash Platform: Block processing is sequential, naturally satisfying the single-writer constraint

This is a design constraint that should be documented, not a code fix. Adding a Mutex would add unnecessary overhead for the primary use case and change the API contract.

Test plan

• cargo check -p grovedb -p grovedb-storage compiles cleanly
• cargo test --doc -p grovedb passes (3 doc tests including the start_transaction example)
• All pre-commit hooks pass (formatting, typos, etc.)

🤖 Generated with Claude Code

[coderabbitai]

Warning

Rate limit exceeded

@QuantumExplorer has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 2 minutes and 18 seconds before requesting another review.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 706b2188-9c57-4fbf-af67-8f63739985ff

📥 Commits

Reviewing files that changed from the base of the PR and between 6285dde and 54dce0b.

📒 Files selected for processing (3)

• grovedb/src/lib.rs
• storage/src/rocksdb_storage/storage.rs
• storage/src/storage.rs

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch docs/single-writer-transaction-requirement

---

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

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 90.70%. Comparing base (6285dde) to head (54dce0b).
⚠️ Report is 5 commits behind head on develop.

Additional details and impacted files

@@           Coverage Diff            @@
##           develop     #617   +/-   ##
========================================
  Coverage    90.70%   90.70%           
========================================
  Files          182      182           
  Lines        50734    50734           
========================================
  Hits         46016    46016           
  Misses        4718     4718           

Components	Coverage Δ
grovedb-core	88.80% <ø> (ø)
merk	92.05% <ø> (ø)
storage	86.37% <ø> (ø)
commitment-tree	96.41% <ø> (ø)
mmr	96.72% <ø> (ø)
bulk-append-tree	90.85% <ø> (ø)
element	97.55% <ø> (ø)

🚀 New features to boost your workflow:

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

[QuantumExplorer]

Yep