Skip to content

Commit

Permalink
Extend Pausable TTL (#22)
Browse files Browse the repository at this point in the history 
* re-export burnable and mintable and review docs

* extend ttl of Pausable instance and modify docs
  • Loading branch information
@brozorec
brozorec authored Jan 29, 2025
1 parent 890a9b3 commit cefb6e9
Show file tree
Hide file tree
Showing 15 changed files with 58 additions and 56 deletions.
5 changes: 4 additions & 1 deletion contracts/utils/pausable/src/lib.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -55,7 +55,10 @@ mod storage;

pub use crate::{
pausable::{emit_paused, emit_unpaused, Pausable, PausableClient, PausableError},
storage::{pause, paused, unpause, when_not_paused, when_paused},
storage::{
pause, paused, unpause, when_not_paused, when_paused, INSTANCE_EXTEND_AMOUNT,
INSTANCE_TTL_THRESHOLD,
},
};

mod test;
17 changes: 7 additions & 10 deletions contracts/utils/pausable/src/pausable.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,8 +10,7 @@ pub trait Pausable {
///
/// # Notes
///
/// We expect you to use the [`crate::storage::paused()`] function from
/// the `storage` module when implementing this function.
/// We recommend using [`crate::paused()`] when implementing this function.
fn paused(e: &Env) -> bool;

/// Triggers `Paused` state.
Expand All @@ -23,8 +22,8 @@ pub trait Pausable {
///
/// # Errors
///
/// If the contract is in `Paused` state, then the error
/// [`PausableError::EnforcedPause`] is thrown.
/// * [`PausableError::EnforcedPause`] - Occurs when the contract is already
/// in `Paused` state.
///
/// # Events
///
Expand All @@ -33,8 +32,7 @@ pub trait Pausable {
///
/// # Notes
///
/// We expect you to use the [`crate::storage::pause()`] function from
/// the `storage` module.
/// We recommend using [`crate::pause()`] when implementing this function.
fn pause(e: &Env, caller: Address);

/// Triggers `Unpaused` state.
Expand All @@ -46,8 +44,8 @@ pub trait Pausable {
///
/// # Errors
///
/// If the contract is in `Unpaused` state, then the error
/// [`PausableError::ExpectedPause`] is thrown.
/// * [`PausableError::ExpectedPause`] - Occurs when the contract is already
/// in `Unpaused` state.
///
/// # Events
///
Expand All @@ -56,8 +54,7 @@ pub trait Pausable {
///
/// # Notes
///
/// We expect you to use the [`crate::storage::unpause()`] function
/// from the `storage` module.
/// We recommend using [`crate::unpause()`] when implementing this function.
fn unpause(e: &Env, caller: Address);
}

Expand Down
44 changes: 23 additions & 21 deletions contracts/utils/pausable/src/storage.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,20 +2,24 @@ use soroban_sdk::{panic_with_error, symbol_short, Address, Env, Symbol};

use crate::{emit_paused, emit_unpaused, pausable::PausableError};

// Same values as in Stellar Asset Contract (SAC) implementation:
// https://github.com/stellar/rs-soroban-env/blob/main/soroban-env-host/src/builtin_contracts/stellar_asset_contract/storage_types.rs
pub const DAY_IN_LEDGERS: u32 = 17280;

pub const INSTANCE_EXTEND_AMOUNT: u32 = 7 * DAY_IN_LEDGERS;
pub const INSTANCE_TTL_THRESHOLD: u32 = INSTANCE_EXTEND_AMOUNT - DAY_IN_LEDGERS;

/// Indicates whether the contract is in `Paused` state.
pub(crate) const PAUSED: Symbol = symbol_short!("PAUSED");
pub const PAUSED: Symbol = symbol_short!("PAUSED");

/// Returns true if the contract is paused, and false otherwise.
///
/// # Arguments
///
/// * `e` - Access to Soroban environment.
///
/// # Notes
///
/// no authentication is required for this function.
pub fn paused(e: &Env) -> bool {
// if not paused, consider default false (unpaused)
e.storage().instance().extend_ttl(INSTANCE_TTL_THRESHOLD, INSTANCE_EXTEND_AMOUNT);
e.storage().instance().get(&PAUSED).unwrap_or(false)
}

Expand All @@ -28,8 +32,8 @@ pub fn paused(e: &Env) -> bool {
///
/// # Errors
///
/// If the contract is in `Paused` state, then the error
/// [`PausableError::EnforcedPause`] is thrown.
/// * [`PausableError::EnforcedPause`] - Occurs when the contract is already in
/// `Paused` state.
///
/// # Events
///
Expand All @@ -38,7 +42,7 @@ pub fn paused(e: &Env) -> bool {
///
/// # Notes
///
/// Authentication is required for this function.
/// Authorization for `caller` is required.
pub fn pause(e: &Env, caller: &Address) {
caller.require_auth();
when_not_paused(e);
Expand All @@ -55,8 +59,8 @@ pub fn pause(e: &Env, caller: &Address) {
///
/// # Errors
///
/// If the contract is in `Unpaused` state, then the error
/// [`PausableError::ExpectedPause`] is thrown.
/// * [`PausableError::ExpectedPause`] - Occurs when the contract is already in
/// `Unpaused` state.
///
/// # Events
///
Expand All @@ -65,50 +69,48 @@ pub fn pause(e: &Env, caller: &Address) {
///
/// # Notes
///
/// Authentication is required for this function.
/// Authorization for `caller` is required.
pub fn unpause(e: &Env, caller: &Address) {
caller.require_auth();
when_paused(e);
e.storage().instance().set(&PAUSED, &false);
emit_unpaused(e, caller);
}

/// Helper to make a function callable only when the contract is NOT
/// paused.
/// Helper to make a function callable only when the contract is NOT paused.
///
/// # Arguments
///
/// * `e` - Access to Soroban environment.
///
/// # Errors
///
/// If the contract is in the `Paused` state, then the error
/// [`PausableError::EnforcedPause`] is thrown.
/// * [`PausableError::EnforcedPause`] - Occurs when the contract is already in
/// `Paused` state.
///
/// # Notes
///
/// No authentication is required for this function.
/// No authorization is required.
pub fn when_not_paused(e: &Env) {
if paused(e) {
panic_with_error!(e, PausableError::EnforcedPause)
}
}

/// Helper to make a function callable
/// only when the contract is paused.
/// Helper to make a function callable only when the contract is paused.
///
/// # Arguments
///
/// * `e` - Access to Soroban environment.
///
/// # Errors
///
/// If the contract is in `Unpaused` state, then the error
/// [`PausableError::ExpectedPause`] is thrown.
/// * [`PausableError::ExpectedPause`] - Occurs when the contract is already in
/// `Unpaused` state.
///
/// # Notes
///
/// No authentication is required for this function.
/// No authorization is required.
pub fn when_paused(e: &Env) {
if !paused(e) {
panic_with_error!(e, PausableError::ExpectedPause)
Expand Down
4 changes: 2 additions & 2 deletions contracts/utils/pausable/test_snapshots/test/errors_pause_when_paused.1.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -45,7 +45,7 @@
},
"ext": "v0"
},
4095
120960
]
],
[
Expand Down Expand Up @@ -99,7 +99,7 @@
},
"ext": "v0"
},
4095
120960
]
]
]
Expand Down
4 changes: 2 additions & 2 deletions contracts/utils/pausable/test_snapshots/test/errors_unpause_when_not_paused.1.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -45,7 +45,7 @@
},
"ext": "v0"
},
4095
120960
]
],
[
Expand Down Expand Up @@ -99,7 +99,7 @@
},
"ext": "v0"
},
4095
120960
]
]
]
Expand Down
4 changes: 2 additions & 2 deletions contracts/utils/pausable/test_snapshots/test/initial_state.1.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -46,7 +46,7 @@
},
"ext": "v0"
},
4095
120960
]
],
[
Expand All @@ -67,7 +67,7 @@
},
"ext": "v0"
},
4095
120960
]
]
]
Expand Down
4 changes: 2 additions & 2 deletions contracts/utils/pausable/test_snapshots/test/pause_works.1.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -69,7 +69,7 @@
},
"ext": "v0"
},
4095
120960
]
],
[
Expand Down Expand Up @@ -123,7 +123,7 @@
},
"ext": "v0"
},
4095
120960
]
]
]
Expand Down
4 changes: 2 additions & 2 deletions contracts/utils/pausable/test_snapshots/test/unpause_works.1.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -69,7 +69,7 @@
},
"ext": "v0"
},
4095
120960
]
],
[
Expand Down Expand Up @@ -123,7 +123,7 @@
},
"ext": "v0"
},
4095
120960
]
]
]
Expand Down
4 changes: 2 additions & 2 deletions contracts/utils/pausable/test_snapshots/test/when_not_paused_works.1.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -46,7 +46,7 @@
},
"ext": "v0"
},
4095
120960
]
],
[
Expand All @@ -67,7 +67,7 @@
},
"ext": "v0"
},
4095
120960
]
]
]
Expand Down
4 changes: 2 additions & 2 deletions contracts/utils/pausable/test_snapshots/test/when_paused_works.1.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -69,7 +69,7 @@
},
"ext": "v0"
},
4095
120960
]
],
[
Expand Down Expand Up @@ -123,7 +123,7 @@
},
"ext": "v0"
},
4095
120960
]
]
]
Expand Down
4 changes: 2 additions & 2 deletions examples/pausable/test_snapshots/test/errors_increment_when_paused.1.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -131,7 +131,7 @@
},
"ext": "v0"
},
4095
120960
]
],
[
Expand All @@ -152,7 +152,7 @@
},
"ext": "v0"
},
4095
120960
]
]
]
Expand Down
4 changes: 2 additions & 2 deletions examples/pausable/test_snapshots/test/errors_unpause_unauthorized.1.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -131,7 +131,7 @@
},
"ext": "v0"
},
4095
120960
]
],
[
Expand All @@ -152,7 +152,7 @@
},
"ext": "v0"
},
4095
120960
]
]
]
Expand Down
4 changes: 2 additions & 2 deletions examples/pausable/test_snapshots/test/initial_state.1.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -72,7 +72,7 @@
},
"ext": "v0"
},
4095
120960
]
],
[
Expand All @@ -93,7 +93,7 @@
},
"ext": "v0"
},
4095
120960
]
]
]
Expand Down
4 changes: 2 additions & 2 deletions examples/pausable/test_snapshots/test/pause_works.1.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -131,7 +131,7 @@
},
"ext": "v0"
},
4095
120960
]
],
[
Expand All @@ -152,7 +152,7 @@
},
"ext": "v0"
},
4095
120960
]
]
]
Expand Down
Loading

0 comments on commit cefb6e9

Please sign in to comment.