feat: buy quote monotonicity tests, supply invariants, read-only docs, sell underflow error (#157 #165 #167 #174)

[ijeoma270]

Fixes #157
Fixes #165
Fixes #167
Fixes #174

What changed

#157 — Buy quote monotonicity tests (tests/buy_quote_monotonicity.rs)

Since the key price is fixed on-chain, the quote is deterministic regardless of how many buys have occurred. 11 tests verify:

• Identical consecutive calls return identical quotes
• Quote unchanged after 1, 5, or 20 buys
• Quote unchanged across multiple distinct buyers (small range)
• total_amount = price + creator_fee + protocol_fee invariant holds
• total_amount ≥ price always holds (fees are additive on buy path)
• Stability at price=1 (dust) and large price values (1,000,000)

#167 — Total supply invariant tests after mixed trades (tests/supply_invariants.rs)

11 tests asserting supply conservation rules across all mixed buy/sell sequences:

• Single buy → sell returns supply to zero
• Buy-two-sell-one conserves supply at 1
• Alternating buy/sell sequences end at 0
• Sum of per-holder balances equals get_total_key_supply
• Three-participant mixed trade with partial sells
• Supply never goes below zero after all keys sold
• Creator isolation (trades on creator A don't affect creator B)
• Holder count mirrors supply conservation (decrements on last key sold, stable when holder still holds)

#165 — Read-only method docs (docs/read-only-methods.md)

New reference document covering every get_* / is_* entrypoint:

• get_buy_quote / get_sell_quote: field semantics, total_amount formula for buy vs sell, underflow guard
• get_total_key_supply, get_creator_supply, get_key_balance, get_holder_key_count
• get_creator, get_creator_details, get_key_name, get_key_symbol, is_creator_registered
• Fee views: get_protocol_fee_view, get_fee_config, get_creator_fee_config, get_creator_fee_bps, get_creator_treasury_share, get_creator_fee_recipient, is_protocol_config_initialized
• Protocol-level: get_protocol_state_version, get_key_decimals, get_treasury_address, get_protocol_admin, get_protocol_fee_recipient
• Units/precision section: raw i128 integers, 10^7 decimals, bps summing to 10000
• Linked from README.md

#174 — Explicit SellUnderflow error variant (src/lib.rs, src/quote_view_errors.rs, tests/sell_underflow.rs)

• Added ContractError::SellUnderflow = 10 to the error enum
• Remapped all three checked_sub underflow sites in sell_key (balance, supply, holder_count) from ContractError::Overflow to ContractError::SellUnderflow
• Added ERR_SELL_UNDERFLOW = "sell_underflow" constant to quote_view_errors.rs
• 11 targeted unit tests: discriminant is 10, does not alias Overflow or InsufficientBalance, zero-balance produces InsufficientBalance (not SellUnderflow), normal sells succeed without the error, supply/balance decremented correctly, error constant string matches

How to test

cargo test --workspace

[drips-wave]

@ijeoma270 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