docs: document CommonDataKey storage separation, cover pause key with tests

[Rafiat30]

Closes #573

Summary

The issue reported that governance_contract::DataKey and settlement_contract::DataKey each declared their own Paused variant, duplicating the pause-key name across the workspace and inviting confusion about whether the two contracts shared a keyspace.

The duplicate Paused (and RecoveryAddress / PendingRecovery / Threshold) variants had already been removed from both contracts' local DataKey enums in an earlier merged commit (refactor: deduplicate common data keys and use shared threshold), which routed all reads/writes through bettapay_common::storage::is_paused / set_paused, operating on CommonDataKey::Paused. So as of main, CommonDataKey::Paused is already the single declaration of the pause key in the workspace — verified with:

$ grep -rn "Paused" --include="*.rs" . | grep -v target
# only hits: CommonDataKey::Paused in bettapay_common/src/storage.rs,
# and GovernanceError::Paused / SettlementError::Paused, which are
# unrelated *error* variants, not storage keys.

What the issue's acceptance criteria still called for — "Document storage separation" — was not done, and there were no tests exercising the shared key directly. This PR closes that gap.

Changes

Modified files

• bettapay_common/src/storage.rs — expanded the module-level doc comment with a new "Storage separation" section explaining precisely what sharing CommonDataKey does and doesn't mean: Soroban instance storage is one ledger entry per contract instance, so governance_contract's CommonDataKey::Paused and settlement_contract's CommonDataKey::Paused are two independent booleans in two independent ledger entries. CommonDataKey only fixes the wire shape of the key, not the data. Reworded the SCVal-compatibility note into a historical note now that the duplicate variants are gone.
• bettapay_common/src/lib.rs — updated the crate-level module summary for storage to match (drops a reference to a read_admin helper that isn't part of this crate, lists the keys CommonDataKey actually owns).
• governance_contract/src/lib.rs and settlement_contract/src/types.rs — fixed a stale comment above each contract's local DataKey enum. It previously read "Admin, RecoveryAddress, PendingRecovery, and Paused live in CommonDataKey", which is wrong: Admin stays local to each contract (stored as a multisig Vec<Address>, which CommonDataKey doesn't own) and Threshold — which does live in CommonDataKey — was missing from the list. Corrected to "RecoveryAddress, PendingRecovery, Paused, and Threshold live in CommonDataKey... Admin stays local...".

New files (test snapshots, auto-generated by the Soroban test harness)

• bettapay_common/test_snapshots/storage/tests/is_paused_defaults_to_false_and_round_trips_via_common_data_key.1.json
• bettapay_common/test_snapshots/storage/tests/two_contract_instances_have_independent_paused_flags.1.json

Test files

• bettapay_common/src/storage.rs (#[cfg(test)] mod tests) — added:
  • is_paused_defaults_to_false_and_round_trips_via_common_data_key: registers a dummy contract, confirms is_paused reads back false when nothing has been written yet (i.e. a missing CommonDataKey::Paused entry is "unpaused", not a panic), then round-trips set_paused(true) / set_paused(false) through is_paused.
  • two_contract_instances_have_independent_paused_flags: registers two separate dummy contract instances (standing in for a governance-like and a settlement-like contract), pauses one via CommonDataKey::Paused, and asserts the other instance's is_paused() is unaffected — this is the direct demonstration of "storage separation" called out in the issue.

Both use a small #[contract] struct DummyContract; test fixture, since Env::as_contract needs a real registered contract address to exercise instance-storage helpers.

How to test

cargo test --workspace

All 190 tests pass. To run just the new/relevant tests:

cargo test -p bettapay_common --lib storage::tests

running 4 tests
test storage::tests::primary_admin_returns_first_entry ... ok
test storage::tests::primary_admin_returns_none_for_empty_list ... ok
test storage::tests::two_contract_instances_have_independent_paused_flags ... ok
test storage::tests::is_paused_defaults_to_false_and_round_trips_via_common_data_key ... ok

test result: ok. 4 passed; 0 failed; 0 ignored; 0 measured; 3 filtered out; finished in 0.02s

[drips-wave]

@Rafiat30 Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits