feat(governance-token): add voting checkpoint history and latest chec…

contracts/governance-token/Cargo.toml

@@ -6,7 +6,6 @@ publish = false
 
 [dependencies]
 soroban-sdk = "25.0.2"
-stellarcade-shared = { path = "../shared" }
 
 [dev-dependencies]
 soroban-sdk = { version = "25.0.2", features = ["testutils"] }

contracts/governance-token/README.md

@@ -4,8 +4,8 @@ This contract implements the governance token for the StellarCade platform. It p
 
 ## Methods
 
-### `init(admin: Address, token_config: TokenConfig)`
-Initializes the contract with an admin address and token configuration.
+### `init(admin: Address, name: String, symbol: String, decimals: u32)`
+Initializes the contract with an admin address and token configuration. Requires admin authorization.
 
 ### `mint(to: Address, amount: i128)`
 Mints new tokens to the specified address. Requires admin authorization.
@@ -19,14 +19,32 @@ Transfers tokens from one address to another. Requires authorization from the se
 ### `total_supply() -> i128`
 Returns the current total supply of tokens.
 
-### `balance_of(owner: Address) -> i128`
+### `balance(owner: Address) -> i128`
 Returns the token balance of the specified owner.
 
+### `latest_checkpoint(holder: Address) -> Option<Checkpoint>`
+Returns the most recent voting checkpoint for `holder`, or `None` if the holder has no recorded history. A checkpoint captures the holder's balance at a specific ledger sequence number.
+
+### `checkpoint_history(holder: Address, limit: u32) -> Vec<Checkpoint>`
+Returns up to `limit` most-recent checkpoints for `holder`, ordered oldest-first. `limit` is capped at 50. Returns an empty list for unknown holders.
+
+### `checkpoint_at_ledger(holder: Address, ledger: u32) -> Option<Checkpoint>`
+Returns the most recent checkpoint at or before `ledger` for `holder`. Intended for snapshot-based vote weighting — pass a proposal's `start_ledger` to get the holder's balance at that point in time. Returns `None` for unknown holders or if no checkpoint precedes the requested ledger.
+
+## Checkpoint Behavior
+
+- A `Checkpoint { ledger, balance }` is written whenever a holder's balance changes (mint, burn, or transfer).
+- Checkpoints are ordered by ledger sequence (ascending) and the list is oldest-first.
+- If two balance changes occur within the same ledger, the existing entry for that ledger is overwritten rather than duplicated.
+- At most 50 checkpoints are retained per holder; the oldest entry is evicted when the cap is reached.
+- Querying an unknown holder via either accessor returns a deterministic empty/`None` result — never an ambiguous zero state.
+
 ## Storage
 
 - `Admin`: The address with administrative privileges.
 - `TotalSupply`: Current total number of tokens in circulation.
 - `Balances`: Mapping of addresses to their respective token balances.
+- `Checkpoints(Address)`: Per-holder ordered list of `Checkpoint` entries (bounded to 50).
 
 ## Events