Skip to content

docs: add pause-state semantics document distinguishing emergency vs creation pause #3

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
jessicanath wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: add pause-state semantics document distinguishing emergency vs creation pause #3

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 9 additions & 0 deletions contracts/stream/src/lib.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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;
Expand Down
2 changes: 2 additions & 0 deletions docs/events.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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).
10 changes: 10 additions & 0 deletions docs/maintainer-security-checklist.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
15 changes: 15 additions & 0 deletions docs/pause-semantics.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.