Introduce the Pausable Library

README.md

@@ -38,6 +38,7 @@ These libraries contain helper functions and other tools valuable to blockchain
 - [Fixed Point Number](./libs/fixed_point/) is an interface to implement fixed-point numbers.
 - [Queue](./libs/queue/) is a linear data structure that provides First-In-First-Out (FIFO) operations. 
 - [Token](./libs/token/) provides helper functions for the [SRC-20](https://github.com/FuelLabs/sway-standards/tree/master/standards/src_20), [SRC-3](https://github.com/FuelLabs/sway-standards/tree/master/standards/src_3), and [SRC-7](https://github.com/FuelLabs/sway-standards/tree/master/standards/src_7) standards.
+- [Pausable](./libs/pausable/) allows contracts to implement an emergency stop mechanism.
 
 ## Using a library
 

libs/Forc.toml

@@ -3,6 +3,7 @@ members = [
   "fixed_point",
   "merkle_proof",
   "ownership",
+  "pausable",
   "queue",
   "reentrancy",
   "signed_integers",

libs/pausable/Forc.toml

@@ -0,0 +1,5 @@
+[project]
+authors = ["Fuel Labs <[email protected]>"]
+entry = "lib.sw"
+license = "Apache-2.0"
+name = "pausable"

libs/pausable/README.md

@@ -0,0 +1,103 @@
+<p align="center">
+    <picture>
+        <source media="(prefers-color-scheme: dark)" srcset=".docs/pausable-logo-dark-theme.png">
+        <img alt="pausable_logo_light" width="400px" src=".docs/pausable-logo-light-theme.png">
+    </picture>
+</p>
+
+# Overview
+
+The Pausable library allows contracts to implement an emergency stop mechanism. This can be useful for scenarios such as having an emergency switch to freeze all transactions in the event of a large bug.
+
+> **NOTE** It is highly encouraged to use the [Ownership Library](../ownership/) in combination with the Pausable Library to ensure that only a single administrative user has the ability to pause your contract.
+
+More information can be found in the [specification](./SPECIFICATION.md).
+
+# Using the Library
+
+## Getting Started
+
+In order to use the Pausable library it must be added to the `Forc.toml` file and then imported into your Sway project. To add Pausable as a dependency to the `Forc.toml` file in your project please see the [README.md](../../README.md).
+
+You may import the Pausable library's functionalities like so:
+
+```sway
+use pausable::*;
+```
+
+Be sure to add the storage block bellow to your contract which enables the library.
+
+```sway
+storage {
+    paused: bool = false,
+}
+```
+
+## Basic Functionality
+
+Once imported, the Pausable library's functions should be available. Using the Pausable Library is as simple as calling your desired function.
+
+The Pausable Library has two states:
+
+- `Paused`
+- `Unpaused`
+
+By default, your contract will start in the `Unpaused` state. To pause your contract, you may call the `_pause()` function. The example below provides a basic pausable contract using the Pausable Library's `Pausable` abi without any restrictions such as an administrator.
+
+```sway
+use pausable::{_is_paused, _pause, _unpause, Pausable};
+
+storage {
+    paused: bool = false,
+}
+
+impl Pausable for Contract {
+    #[storage(write)]
+    fn pause() {
+        _pause(storage.paused);
+    }
+
+    #[storage(write)]
+    fn unpause() {
+        _unpause(storage.paused);
+    }
+
+    #[storage(read)]
+    fn is_paused() -> bool {
+        _is_paused(storage.paused)
+    }
+}
+```
+
+## Requiring A State
+
+When developing a contract, you may want to lock functions down to a specific state. To do this, you may call either of the `require_paused()` or `require_not_paused()` functions. The example below shows these functions in use.
+
+```sway
+use pausable::{require_not_paused, require_paused};
+
+storage {
+    paused: bool = false,
+}
+
+abi MyAbi {
+    #[storage(read)]
+    fn require_paused_state();
+    #[storage(read)]
+    fn require_not_paused_state();
+}
+
+impl MyAbi for Contract {
+    #[storage(read)]
+    fn require_paused_state() {
+        require_paused(storage.paused);
+        // This comment will only ever be reached if the contract is in the paused state
+    }
+
+    #[storage(read)]
+    fn require_not_paused_state() {
+        require_not_paused(storage.paused);
+        // This comment will only ever be reached if the contract is in the unpaused state
+    }
+}
+```

libs/pausable/SPECIFICATION.md

@@ -0,0 +1,31 @@
+# Overview
+
+This document provides an overview of the Pausable library.
+
+It outlines the use cases, i.e. specification, and describes how to implement the library.
+
+## Use Cases
+
+The Pausable library can be used anytime a contract needs a basic paused and unpased state, such as in the case of an emergency when a major bug is found.
+
+## Public Functions
+
+### `_pause()`
+
+This function will unconditionally set the contract to the paused state.
+
+### `_unpause()`
+
+This function will unconditionally set the contract to the unpaused state.
+
+### `_is_paused()`
+
+This function will return whether the contract is in the paused state.
+
+### `require_paused()`
+
+This function will ensure the contract is in the paused state before continuing.
+
+### `require_not_paused()`
+
+This function will ensure the contract is in the unpaused state before continuing.