From 00cc88ab7bb6664d5044f4f5164d29b1ffe3361f Mon Sep 17 00:00:00 2001 From: jessicanath Date: Wed, 27 May 2026 21:19:06 +0000 Subject: [PATCH] docs: add pause-state semantics document distinguishing emergency vs creation pause --- contracts/stream/src/lib.rs | 9 +++++++++ docs/events.md | 2 ++ docs/maintainer-security-checklist.md | 10 ++++++++++ docs/pause-semantics.md | 15 +++++++++++++++ 4 files changed, 36 insertions(+) create mode 100644 docs/maintainer-security-checklist.md create mode 100644 docs/pause-semantics.md diff --git a/contracts/stream/src/lib.rs b/contracts/stream/src/lib.rs index c179565c..fa7719ba 100644 --- a/contracts/stream/src/lib.rs +++ b/contracts/stream/src/lib.rs @@ -1,3 +1,12 @@ +//! Fluxora Stream Contract +//! +//! This contract implements the core streaming logic, including pause-state semantics. +//! There are three pause levels: +//! - GlobalEmergencyPaused: Blocks creation, modifications, and all withdrawals. +//! - CreationPaused: Blocks only new stream creation. +//! - StreamPaused (individual): Blocks withdrawals for a specific stream. +//! +//! For detailed pause-state semantics, see `docs/pause-semantics.md`. #![no_std] mod accrual; diff --git a/docs/events.md b/docs/events.md index f4e96506..39534701 100644 --- a/docs/events.md +++ b/docs/events.md @@ -348,3 +348,5 @@ Commit message suggestion: `docs: add event schema and topics for indexers` If you change event topics or payloads in the contract, update this document and include updated example snapshots in the PR. + +For events related to protocol pauses (`paused_ctl`, `pr_pause`, `pr_resume`), see [Pause-State Semantics](./pause-semantics.md). diff --git a/docs/maintainer-security-checklist.md b/docs/maintainer-security-checklist.md new file mode 100644 index 00000000..26d5c76c --- /dev/null +++ b/docs/maintainer-security-checklist.md @@ -0,0 +1,10 @@ +# Maintainer Security Checklist + +This checklist is for protocol maintainers handling emergency scenarios. + +## Incident Response +1. Identify the scope of the incident. +2. Determine the appropriate pause level. +3. Apply the pause. See [Pause-State Semantics](./pause-semantics.md) for details on `GlobalEmergencyPaused` vs `CreationPaused`. +4. Investigate and patch the vulnerability. +5. Deploy a fix and/or lift the pause. diff --git a/docs/pause-semantics.md b/docs/pause-semantics.md new file mode 100644 index 00000000..8b67f754 --- /dev/null +++ b/docs/pause-semantics.md @@ -0,0 +1,15 @@ +# Pause-State Semantics + +The Fluxora protocol features multiple levels of pauses to handle emergency scenarios gracefully without unnecessarily disrupting unaffected parts of the system. + +## Pause Levels + +| Pause State | Scope | Blocked Operations | Allowed Operations | Notes | +|-------------|-------|--------------------|--------------------|-------| +| `GlobalEmergencyPaused` | Entire Contract | Stream creation, modification, and all withdrawals. | `cancel_stream`, admin functions, queries. | Used during severe protocol-wide incidents. Paused streams *continue to accrue* tokens in the background, but withdrawals are blocked. | +| `CreationPaused` | New Streams Only | Stream creation (`create_stream`). | Withdrawals, top-ups, cancellations, stream modifications. | Used when deprecating a contract version or restricting growth while allowing existing users to exit. | +| `StreamPaused` (Individual) | Single Stream | Withdrawals from that specific stream. | Top-ups, cancellation, other streams' operations. | Used by stream admins to pause a specific stream. The paused stream *continues to accrue* time elapsed and tokens, but the recipient cannot withdraw while paused. | + +## Important Considerations +- **Accrual Continues**: Pausing a stream (whether globally or individually) **does not** pause the stream's time or token accrual. The tokens continue to vest according to the schedule. A pause only blocks the *withdrawal* of those tokens. +- **Cancellation**: `cancel_stream` is typically allowed even during a global pause to let users forcefully exit the contract and retrieve un-streamed funds, but they may not be able to withdraw accrued funds until the global pause is lifted.