Feature/storage maintenance

[jessie-hash-pixel]

Storage Maintenance: Cleanup, Snapshots, Integrity Checksums & Batch Revoke

Summary

This PR implements four storage maintenance features for the IP Registry contract. Each feature is delivered as its own commit with implementation, tests, and documentation.

Branch: feature/storage-maintenance → main

---

Changes

closes #440
closes #441
closes #442
closes #443

Commit 1 — Cleanup Expired/Revoked Commitments (90a52d7)

Automatically clean up expired or revoked commitments to free storage.

Adds cleanup_revoked_commitment(ip_id) which permanently removes a revoked IP record and its CommitmentOwner index entry from persistent ledger storage. Only the record owner may call this, and the IP must already be revoked. The owner's ID list is updated atomically and a cleanup event is emitted.

Why: Soroban persistent storage has rent costs. Leaving revoked records on-chain indefinitely wastes ledger space and increases rent fees for the contract. This gives owners a way to reclaim that space after revoking.

---

Commit 2 — Periodic Snapshots for Disaster Recovery (44b4576)

Create periodic snapshots of all commitments for disaster recovery.

Adds create_snapshot(caller) and get_snapshot(snapshot_id). Each snapshot is a CommitmentSnapshot record containing:

• snapshot_id — monotonically increasing identifier
• timestamp — ledger timestamp at creation
• total_count — number of IPs committed at snapshot time
• checksum — sha256 of the NextId counter as a lightweight state fingerprint

Admin-only creation. Snapshots are stored in persistent storage and retrievable by ID indefinitely.

Why: Provides a recoverable reference point for the registry state. Operators can compare snapshot total_count and checksum against live state to detect divergence after an incident.

---

Commit 3 — Cryptographic Checksum Integrity Verification (8a5a9b7)

Verify commitment data integrity using cryptographic checksums.

Adds compute_integrity_checksum(caller) and verify_integrity_checksum(). The checksum is sha256 over the concatenation of all active (non-revoked) commitment hashes in ID order, stored under CommitmentChecksumV2. Revoked commitments are excluded, so revoking an IP changes the checksum. verify_integrity_checksum() recomputes and compares — returns true if they match or no checksum has been stored yet.

Why: Detects silent data corruption or unauthorized state mutations between checkpoints. Complements the existing IpCommitmentChecksum (which used an empty preimage) with a real iterative checksum over live data.

---

Commit 4 — Batch Expire Commitments (3a758f5)

Expire multiple commitments in a single transaction.

Adds batch_revoke_commitments(owner, ip_ids) which revokes a list of IP commitments atomically in one transaction. The caller must own every IP in the list — if any check fails the entire transaction panics. Each revoked IP emits a revoked event and an immutable audit entry. Returns the count of IPs revoked.

Why: Owners with many IPs (e.g. a company winding down a product line) would otherwise need one transaction per IP to revoke. Batching reduces gas costs and simplifies client-side tooling.

---

Files Changed

File	Description
contracts/ip_registry/src/lib.rs	New DataKey variants, CommitmentSnapshot struct, four new contract methods, require_is_revoked helper
contracts/ip_registry/src/test.rs	New trait method declarations, 12 new tests across all four features
docs/storage-maintenance.md	New documentation page covering all four features with usage examples

+559 lines, 0 deletions across 3 files.

---

Tests

12 new tests added to contracts/ip_registry/src/test.rs:

Test	Feature
test_cleanup_revoked_commitment_removes_record	Cleanup
test_cleanup_non_revoked_panics	Cleanup
test_create_and_get_snapshot	Snapshots
test_snapshot_ids_are_sequential	Snapshots
test_get_snapshot_nonexistent_returns_none	Snapshots
test_compute_and_verify_integrity_checksum	Integrity
test_verify_integrity_checksum_no_stored_returns_true	Integrity
test_checksum_excludes_revoked_commitments	Integrity
test_batch_revoke_commitments_marks_all_revoked	Batch revoke
test_batch_revoke_returns_correct_count	Batch revoke
test_batch_revoke_already_revoked_panics	Batch revoke
test_batch_revoke_wrong_owner_panics	Batch revoke

---

Checklist

• Each issue has its own commit
• All new functions have doc comments
• Auth checks enforced on all mutating functions
• Events emitted for all state changes
• Audit trail entries appended where applicable (batch_revoke_commitments)
• TTL extended on all new persistent storage writes
• Documentation added (docs/storage-maintenance.md)
• No existing tests removed or modified

[drips-wave]

@jessie-hash-pixel 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