feature/827-snapshot-token

[benedictworks-home]

Summary

This pull request implements Issue #827 — [Cookbook] Create Snapshot Token, establishing a robust, production-grade Soroban fungible token with point-of-time balance snapshotting capabilities. It is located at examples/tokens/04-snapshot-token/ and registered inside the tokens category.

Features Implemented

1. Base Token Functionality: Complete SEP-41-like fungible token representation including initialize, mint (restricted to admin), transfer, and standard metadata queries (name, symbol, decimals, total_supply, balance).
2. Monotonically Increasing Snapshots: High-security snapshot creation via create_snapshot(caller) restricted to the token administrator using caller.require_auth(). Returns a monotonically incrementing ID and publishes snapshot events.
3. Sparse-Snapshot Storage Pattern: Optimized storage that prevents unbounded state growth. History is recorded lazily: accounts only record their pre-change balance when a transaction crosses a new snapshot boundary. Inactive accounts require zero additional storage.
4. Historical Balance Queries: Accurate point-of-time queries via balance_at_snapshot(account, snapshot_id). Includes highly robust resolution that perfectly addresses critical edge cases:
   • No Activity After Snapshot: Correctly returns the closest preceding recorded balance (or current balance) if no transfers occurred after the snapshot.
   • Never-Held Tokens: Returns 0 (and not an error) for valid snapshot IDs if the account has no transaction history.
   • Invalid Snapshot IDs: Returns SnapshotTokenError::SnapshotNotFound if querying snapshot IDs that were never created.

Test Suite (13 robust tests in src/test.rs)

1. test_initialization — Verifies correct contract metadata, admin, zero supply, and initial snapshot counter.
2. test_mint_admin — Verifies admin can mint and receiver's balance updates correctly.
3. test_mint_invalid_amount — Verifies negative/zero mint amounts fail.
4. test_transfer_success — Verifies standard balance transfer correctness and sender auth.
5. test_transfer_insufficient_balance — Verifies transfer fails when balance is too low.
6. test_snapshot_id_incrementing — Verifies monotonically incrementing snapshot IDs on successive admin creations.
7. test_create_snapshot_not_authorized — Verifies non-admin caller receives NotAuthorized on create_snapshot.
8. test_balance_at_snapshot_no_activity — Verifies the critical "no-activity" edge case returns the correct snapshot-time balance.
9. test_balance_at_snapshot_change_before — Verifies balance at snapshot includes changes occurring prior to creation.
10. test_balance_at_snapshot_unaffected_by_subsequent — Verifies balance at snapshot remains completely unaffected by transfers occurring after creation.
11. test_multi_snapshot_complex — Comprehensive multi-snapshot, multi-account, multi-transfer scenario verifying correct independent historical records.
12. test_query_non_existent_snapshot — Verifies querying invalid snapshot IDs returns SnapshotNotFound.
13. test_query_user_with_no_history — Verifies querying valid snapshot balance for a new address returns 0.

Documentation & Category Index

• Created a comprehensive 04-snapshot-token/README.md including the contract interface, the sparse-snapshot mechanism design details, step-by-step build & test guide, concrete DAO governance walkthrough, and design notes.
• Updated examples/tokens/README.md to reference this new snapshot token cookbook recipe.

Verification Commands Run

All tests run, format checks, lints, and optimized WASM contract compilation are 100% green:

• cargo fmt --check --manifest-path examples/tokens/04-snapshot-token/Cargo.toml -> Passed
• cargo clippy --manifest-path examples/tokens/04-snapshot-token/Cargo.toml --all-targets -- -D warnings -> Passed (0 warnings/errors)
• cargo test --manifest-path examples/tokens/04-snapshot-token/Cargo.toml -> Passed (13 passed, 0 failed)
• cargo build --target wasm32v1-none --release --manifest-path examples/tokens/04-snapshot-token/Cargo.toml -> Passed (Successfully compiled optimized contract WASM)
  Implementation & Design Detail Review
  Crate Location: Exactly at examples/tokens/04-snapshot-token/ containing Cargo.toml, README.md, src/lib.rs, and src/test.rs.
  Existing Token Sibling Examples: No sibling token examples (01-03) existed inside examples/tokens/ yet when I started. Therefore, this crate was implemented as a fully complete and standalone SEP-41-style token with governance-focused snapshot functionality.
  Access-Control Decision: Restricted to admin-only via caller.require_auth(). Allowing arbitrary callers to take snapshots would facilitate contract state griefing (arbitrary creation of snapshot boundaries, bloating maps and storage).
  No-Activity Edge-Case Behavior: Resolved by searching the sorted snapshot history Map<u32, i128>. We search for the smallest key k such that k >= snapshot_id. If such an entry exists, its value is the correct historical balance at snapshot_id. If no entry exists, the user has had no transactions since snapshot_id, so their historical balance at snapshot_id equals their current balance. Tested explicitly in test_balance_at_snapshot_no_activity.
  Modern Compilation Target: For modern soroban-sdk versions inside Rust 1.82+, compiling for standard wasm32-unknown-unknown raises issues due to unsupported default reference-types and multi-value features. Thus, the crate was successfully built for release using the recommended wasm32v1-none target (cargo build --target wasm32v1-none --release).

Closes #518

[drips-wave]

@benedictworks-home 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