Merge branch 'main' into feat/governance-quorum-requirement

Author: Unclebaffa

PR_DESCRIPTION.md

@@ -1,62 +1,39 @@
-## Summary
+# Add unit tests for pause blocking sell transactions
+
+Closes #727
 
-Fixes the TTL extension logic so that a `TTL_EXTENDED_EVENT_NAME` event is only emitted when the creator's storage TTL actually needs extension (remaining TTL drops below `TTL_EXTENSION_THRESHOLD`). Adds an integration test confirming no event is emitted when TTL is healthy.
+## Summary
 
-Closes #<!-- TODO: insert issue number -->
+Add dedicated integration tests confirming the emergency pause correctly blocks sell transactions and verifies that all contract state remains consistent after blocked sell attempts.
 
-## Problem
+## Motivation
 
-The `extend_creator_ttl` function unconditionally emitted a `ttl_ext` event on every successful buy or sell, even when the creator's storage TTL was already well above the minimum threshold. This polluted event logs with noisy, unnecessary events that indexers and off-chain consumers had to filter out.
+The emergency pause mechanism was originally tested primarily for buy transactions. While some existing tests touch sell under pause, there was no focused test suite that comprehensively validates the sell-pause lifecycle against all three acceptance criteria from the issue. This PR fills that gap with a dedicated test file.
 
 ## Changes
 
-### `creator-keys/src/lib.rs`
+### New file: `creator-keys/tests/pause_blocks_sell_transactions.rs`
 
-- **Added `TTL_EXTENSION_THRESHOLD` constant** (`100` ledgers) — the minimum remaining TTL below which a TTL extension event is emitted.
-- **Added `DataKey::CreatorTtlLiveUntil(creator)`** — a per-creator `u32` recording the absolute live-until ledger the contract last set for the creator profile key. The Soroban SDK does not expose TTL reads to contract code, so this tracked value is what `extend_creator_ttl` uses to decide whether to emit the event.
-- **Modified `extend_creator_ttl`** to:
-  1. Derive the remaining TTL from `CreatorTtlLiveUntil` and evaluate `ttl::should_extend(remaining, TTL_EXTENSION_THRESHOLD)`.
-  2. Always call `extend_ttl` on all creator-scoped storage keys — the Soroban SDK call is a no-op when TTL is already healthy, preserving the existing on-chain behavior.
-  3. Only publish the `TTL_EXTENDED_EVENT_NAME` event when the check above returns `true`, then update the tracked live-until.
-- **Write-time TTL alignment**: new entries start with the network-default TTL, which can be much shorter than `CREATOR_TTL_LEDGERS` on fresh networks. `register_creator` now forces the full `CREATOR_TTL_LEDGERS` window on the creator profile, curve preset, and tracked live-until; `set_key_price`, the buy path, and dividend settlement grant the same full window to `KeyPrice`, `KeyBalance(creator, holder)`, and the dividend checkpoint/pending keys.
+Five new integration tests covering every acceptance criterion:
 
-### `creator-keys/tests/ttl_extension_on_buy.rs`
+| Test | Acceptance Criterion |
+|---|---|
+| `test_sell_panics_with_protocol_paused_when_contract_is_paused` | Sell panics with `ProtocolPaused` when paused |
+| `test_sell_succeeds_after_resume` | Sell succeeds immediately after unpause |
+| `test_holder_count_unchanged_after_blocked_sell` | Holder count, supply, and key balance unchanged after blocked sell |
+| `test_supply_unchanged_after_blocked_sell_with_multiple_holders` | Multi-holder variant — both holders' state unchanged after concurrent blocked sells |
+| `test_full_pause_lifecycle` | End-to-end: buy → pause → blocked sell (state verified) → unpause → successful sell (state verified) |
 
-- **Added `test_no_ttl_extension_event_when_ttl_healthy`** integration test that:
-  - Registers a creator with TTL at max (~6.3M ledgers remaining).
-  - Asserts TTL ≥ 2× `TTL_EXTENSION_THRESHOLD`.
-  - Executes a buy without advancing the ledger.
-  - Asserts **no** `ttl_ext` event is present among emitted events.
-  - Asserts a `buy` event **is** present confirming the transaction succeeded.
-  - Asserts creator storage TTL is unchanged after the buy.
+## Acceptance Criteria Verification
 
-## Acceptance Criteria
+- ✅ **Sell panics with `contract_paused` when paused** — `test_sell_panics_with_protocol_paused_when_contract_is_paused` asserts `Err(Ok(ContractError::ProtocolPaused))` on sell attempt while paused.
+- ✅ **Sell succeeds after resume** — `test_sell_succeeds_after_resume` pauses, unpauses, then confirms sell returns the correct new supply.
+- ✅ **State unchanged after blocked sell** — `test_holder_count_unchanged_after_blocked_sell` and `test_supply_unchanged_after_blocked_sell_with_multiple_holders` snapshot `supply`, `holder_count`, and `key_balance` before the blocked sell and assert all are identical afterward.
 
-| Criteria | Status |
-|---|---|
-| No TTL extension event emitted when TTL is above threshold | ✅ |
-| Buy event present confirming transaction succeeded | ✅ |
-| Creator storage TTL unchanged after the buy | ✅ |
-| Test uses a TTL value at least 2× the extension threshold | ✅ |
-| Existing tests continue to pass | ✅ |
-
-## Testing
-
-- [x] `cargo fmt --all -- --check`
-- [x] `cargo clippy --workspace --all-targets -- -D warnings`
-- [x] `cargo test --workspace`
-
-**Note:** All existing TTL tests (`test_buy_extends_creator_ttl`, `test_ttl_extension_event_topics_and_payload`, `test_ttl_not_extended_when_already_high`, `test_sell_extends_creator_ttl_after_successful_sell`, `test_failed_sell_does_not_extend_creator_ttl`) remain compatible because:
-- They advance the ledger to near expiry before the first buy, so `should_extend` returns `true` and the event is still emitted.
-- The second-buy-same-ledger scenario doesn't assert event presence/absence on the second buy.
-- `extend_ttl` SDK calls happen unconditionally — only event emission is gated.
-
-## Checklist
-
-- [x] Linked issue or backlog item
-- [x] Added or updated `creator-keys` unit/integration tests for every changed contract behavior, including failure paths for new or reachable `ContractError` variants
-- [ ] Ran `cargo fmt --all -- --check`, `cargo clippy --workspace --all-targets -- -D warnings`, and `cargo test --workspace`, or explained exactly why a command was not run
-- [x] Reviewed persistent storage changes against `docs/storage-key-invariants.md`; any storage layout change includes a migration/backward-compatibility note
-- [x] Confirmed event names, topic order, payload field order, and field meanings remain compatible with `docs/contract-event-conventions.md`, or documented the breaking change and versioning plan
-- [x] Updated docs for any changed public contract interface, read-only method, event schema, storage behavior, fee logic, or deployment workflow
-- [x] Scope stays limited to one contract concern and does not include unrelated formatting, lockfile, generated artifact, or dependency changes
+## CI Pre-Checks
+
+All local CI checks pass:
+- ✅ `cargo build` — compiles cleanly
+- ✅ `cargo test` — all tests pass (including the 5 new ones)
+- ✅ `cargo test --test pause_blocks_sell_transactions` — 5/5 passed
+- ✅ No new clippy warnings introduced by this change

creator-keys/src/events.rs

@@ -666,6 +666,16 @@ pub const WHITELIST_DISABLED_EVENT_NAME: Symbol = symbol_short!("wl_dis");
 pub const ADDRESS_WHITELISTED_EVENT_NAME: Symbol = symbol_short!("wl_add");
 pub const ADDRESS_REMOVED_EVENT_NAME: Symbol = symbol_short!("wl_rem");
 pub const KEYS_BURNED_EVENT_NAME: Symbol = symbol_short!("burned");
+pub const SELF_FREEZE_APPLIED_EVENT_NAME: Symbol = symbol_short!("sf_add");
+pub const SELF_FREEZE_LIFTED_EVENT_NAME: Symbol = symbol_short!("sf_del");
+
+#[derive(Clone, Debug, Eq, PartialEq)]
+#[contracttype]
+pub struct SelfFreezeEvent {
+    pub key_id: Address,
+    pub wallet: Address,
+    pub quantity: u32,
+}
 
 #[derive(Clone, Debug, Eq, PartialEq)]
 #[contracttype]
@@ -1185,3 +1195,245 @@ pub struct RoyaltyUpdatedEvent {
 pub fn royalty_updated_topics(creator: &Address) -> (Symbol, Address) {
     (ROYALTY_UPDATED_EVENT_NAME, creator.clone())
 }
+
+/// Event name for the protocol trade fee collected on a buy or sell.
+pub const FEE_COLLECTED_EVENT_NAME: Symbol = symbol_short!("fee_coll");
+
+/// Event name for a sell rejected by the anti-flash-trade lockup window.
+pub const LOCKUP_BLOCKED_EVENT_NAME: Symbol = symbol_short!("lck_blk");
+
+/// Stable fee collection event payload for downstream indexers.
+///
+/// Event shape:
+/// - topics: `(FEE_COLLECTED_EVENT_NAME, treasury)`
+/// - data: `FeeCollectedEvent`
+///
+/// Emitted on every buy and sell once the protocol trade fee is configured,
+/// carrying the deducted amount and the treasury address that received it.
+#[derive(Clone, Debug, Eq, PartialEq)]
+#[contracttype]
+pub struct FeeCollectedEvent {
+    /// Treasury address that received the fee.
+    pub treasury: Address,
+    /// Fee amount deducted from the trade.
+    pub amount: i128,
+    /// Ledger sequence number at the time of the trade.
+    pub ledger: u32,
+}
+
+/// Shared fee collected event topics tuple.
+pub fn fee_collected_topics(treasury: &Address) -> (Symbol, Address) {
+    (FEE_COLLECTED_EVENT_NAME, treasury.clone())
+}
+
+/// Stable lockup-blocked event payload for downstream indexers.
+///
+/// Event shape:
+/// - topics: `(LOCKUP_BLOCKED_EVENT_NAME, creator_id, seller)`
+/// - data: `LockupBlockedEvent`
+///
+/// Emitted when a sell is rejected because the seller's most recent buy for
+/// this creator falls inside the configured lockup window.
+#[derive(Clone, Debug, Eq, PartialEq)]
+#[contracttype]
+pub struct LockupBlockedEvent {
+    /// Creator whose keys the seller attempted to sell.
+    pub creator_id: Address,
+    /// Seller whose sale was rejected.
+    pub seller: Address,
+    /// Ledger timestamp of the seller's most recent buy.
+    pub last_buy_timestamp: u64,
+    /// Timestamp at which the lockup expires (exclusive).
+    pub unlock_at: u64,
+    /// Ledger timestamp at rejection.
+    pub current_timestamp: u64,
+}
+
+/// Shared lockup blocked event topics tuple.
+pub fn lockup_blocked_topics(creator: &Address, seller: &Address) -> (Symbol, Address, Address) {
+    (LOCKUP_BLOCKED_EVENT_NAME, creator.clone(), seller.clone())
+}
+
+/// Event name for a new staking position created via `stake_keys_locked`.
+pub const STAKE_EVENT_NAME: Symbol = symbol_short!("stake");
+
+/// Event name for a lock period extension via `stake_extend`.
+pub const STAKE_EXTENDED_EVENT_NAME: Symbol = symbol_short!("stk_ext");
+
+/// Event name for an early (pre-maturity) unstake via `early_unstake`.
+pub const EARLY_UNSTAKE_EVENT_NAME: Symbol = symbol_short!("stk_chl");
+
+/// Event name for a reward claim at/after maturity via `claim_stake_reward`.
+pub const STAKE_REWARD_CLAIMED_EVENT_NAME: Symbol = symbol_short!("stk_clm");
+
+/// Stable stake event payload for downstream indexers.
+///
+/// Event shape:
+/// - topics: `(STAKE_EVENT_NAME, creator_id, holder, stake_id)`
+/// - data: `StakeEvent`
+#[derive(Clone, Debug, Eq, PartialEq)]
+#[contracttype]
+pub struct StakeEvent {
+    /// Creator whose keys are staked.
+    pub creator_id: Address,
+    /// Staker that locked the keys.
+    pub holder: Address,
+    /// Sequential position id for the `(creator, holder)` pair.
+    pub stake_id: u32,
+    /// Number of keys locked.
+    pub amount: u32,
+    /// Ledger sequence at which the position matures.
+    pub unlock_ledger: u32,
+}
+
+/// Shared stake event topics tuple.
+pub fn stake_topics(creator: &Address, holder: &Address, stake_id: u32) -> (Symbol, Address, Address, u32) {
+    (STAKE_EVENT_NAME, creator.clone(), holder.clone(), stake_id)
+}
+
+/// Stable stake-extend event payload for downstream indexers.
+///
+/// Event shape:
+/// - topics: `(STAKE_EXTENDED_EVENT_NAME, creator_id, holder, stake_id)`
+/// - data: `StakeExtendedEvent`
+#[derive(Clone, Debug, Eq, PartialEq)]
+#[contracttype]
+pub struct StakeExtendedEvent {
+    /// Creator whose keys are staked.
+    pub creator_id: Address,
+    /// Staker that locked the keys.
+    pub holder: Address,
+    /// Extended position id.
+    pub stake_id: u32,
+    /// New maturity ledger sequence after the extension.
+    pub unlock_ledger: u32,
+    /// Additional ledgers appended to the lock period.
+    pub additional_ledgers: u32,
+}
+
+/// Shared stake-extend event topics tuple.
+pub fn stake_extended_topics(
+    creator: &Address,
+    holder: &Address,
+    stake_id: u32,
+) -> (Symbol, Address, Address, u32) {
+    (STAKE_EXTENDED_EVENT_NAME, creator.clone(), holder.clone(), stake_id)
+}
+
+/// Stable early-unstake event payload for downstream indexers.
+///
+/// Event shape:
+/// - topics: `(EARLY_UNSTAKE_EVENT_NAME, creator_id, holder, stake_id)`
+/// - data: `EarlyUnstakeEvent`
+#[derive(Clone, Debug, Eq, PartialEq)]
+#[contracttype]
+pub struct EarlyUnstakeEvent {
+    /// Creator whose keys were staked.
+    pub creator_id: Address,
+    /// Staker that closed the position.
+    pub holder: Address,
+    /// Closed position id.
+    pub stake_id: u32,
+    /// Keys released back to the holder's liquid balance.
+    pub amount: u32,
+    /// Pro-rata reward entitlement removed from the pool.
+    pub forgone_reward: i128,
+    /// Penalty retained in the pool.
+    pub penalty: i128,
+    /// Ledger sequence at which the position was closed.
+    pub ledger: u32,
+}
+
+/// Shared early-unstake event topics tuple.
+pub fn early_unstake_topics(
+    creator: &Address,
+    holder: &Address,
+    stake_id: u32,
+) -> (Symbol, Address, Address, u32) {
+    (EARLY_UNSTAKE_EVENT_NAME, creator.clone(), holder.clone(), stake_id)
+}
+
+/// Stable stake-reward-claim event payload for downstream indexers.
+///
+/// Event shape:
+/// - topics: `(STAKE_REWARD_CLAIMED_EVENT_NAME, creator_id, holder, stake_id)`
+/// - data: `StakeRewardClaimedEvent`
+#[derive(Clone, Debug, Eq, PartialEq)]
+#[contracttype]
+pub struct StakeRewardClaimedEvent {
+    /// Creator whose keys were staked.
+    pub creator_id: Address,
+    /// Staker that closed the position.
+    pub holder: Address,
+    /// Closed position id.
+    pub stake_id: u32,
+    /// Keys released back to the holder's liquid balance.
+    pub amount: u32,
+    /// Reward paid out from the pool.
+    pub reward: i128,
+    /// Ledger sequence at which the position matured.
+    pub unlock_ledger: u32,
+    /// Ledger sequence at which the reward was claimed.
+    pub ledger: u32,
+}
+
+/// Shared stake-reward-claim event topics tuple.
+pub fn stake_reward_claimed_topics(
+    creator: &Address,
+    holder: &Address,
+    stake_id: u32,
+) -> (Symbol, Address, Address, u32) {
+    (STAKE_REWARD_CLAIMED_EVENT_NAME, creator.clone(), holder.clone(), stake_id)
+}
+
+
+// ============================================================================
+// Launch Penalty (#798)
+// ============================================================================
+
+/// Event name for launch penalty applied on sell.
+pub const LAUNCH_PENALTY_APPLIED_EVENT_NAME: Symbol = symbol_short!("lnch_pnl");
+
+/// Stable launch penalty applied event payload for downstream indexers.
+#[derive(Clone, Debug, Eq, PartialEq)]
+#[contracttype]
+pub struct LaunchPenaltyAppliedEvent {
+    /// Address of the creator whose key was sold.
+    pub creator_id: Address,
+    /// Address of the seller.
+    pub seller: Address,
+    /// Launch penalty basis points applied.
+    pub penalty_bps: u32,
+    /// Penalty amount deducted from proceeds.
+    pub penalty_amount: i128,
+    /// Ledger sequence at the time of the sale.
+    pub ledger: u32,
+}
+
+/// Shared launch penalty applied event topics tuple.
+pub fn launch_penalty_applied_topics(
+    creator: &Address,
+    seller: &Address,
+) -> (Symbol, Address, Address) {
+    (LAUNCH_PENALTY_APPLIED_EVENT_NAME, creator.clone(), seller.clone())
+}
+
+/// Event name for set_launch_penalty.
+pub const LAUNCH_PENALTY_SET_EVENT_NAME: Symbol = symbol_short!("lnch_set");
+
+/// Stable set launch penalty event payload for downstream indexers.
+#[derive(Clone, Debug, Eq, PartialEq)]
+#[contracttype]
+pub struct LaunchPenaltySetEvent {
+    /// Address of the creator.
+    pub creator_id: Address,
+    /// New penalty basis points.
+    pub penalty_bps: u32,
+    /// Ledger sequence at the time of the update.
+    pub ledger: u32,
+}
+
+/// Shared set launch penalty event topics tuple.
+pub fn launch_penalty_set_topics(creator: &Address) -> (Symbol, Address) {
+    (LAUNCH_PENALTY_SET_EVENT_NAME, creator.clone())
+}