Introduce the Sway-Libs Book

.docs/book/.gitignore

@@ -0,0 +1 @@
+book

.docs/book/README.md

@@ -0,0 +1,28 @@
+## Installation
+
+If you wish to alter the documentation presented in this book then follow the following instructions.
+
+1. Install [Rust](https://www.rust-lang.org/tools/install) if it's not installed.
+2. Install [mdbook](https://rust-lang.github.io/mdBook/).
+
+   ```bash
+   cargo install mdbook
+   ```
+
+3. To [build](https://rust-lang.github.io/mdBook/cli/build.html) the book make sure that you are in `/.docs/book` and run
+
+   ```bash
+   mdbook build
+   ```
+
+4. To develop the book in real time, in the browser, run
+
+   ```bash
+   mdbook serve --open
+   ```
+
+## How to edit the book
+
+Each page is written in markdown so there's not much to learn specifically for `mdbook` but you're free to read their documentation for additional information.
+
+If you wish to add a new page then it must be listed in the [SUMMARY.md](src/SUMMARY.md).

.docs/book/src/SUMMARY.md

@@ -0,0 +1,23 @@
+# Summary
+
+- [Getting Started](./documentation/getting_started/index.md)
+  - [Running Tests](./documentation/getting_started/running_tests.md)
+- [Libraries](./documentation/libraries/index.md)
+  - [Asset Libraries](./documentation/libraries/asset/index.md)
+    - [Asset Library](./documentation/libraries/asset/asset/index.md)
+      - [Base](./documentation/libraries/asset/asset/base.md)
+      - [Supply](./documentation/libraries/asset/asset/supply.md)
+      - [Metadata](./documentation/libraries/asset/asset/metadata.md)
+  - [Access Control and Secutiry Libraries](./documentation/libraries/access_security/index.md)
+    - [Admin Library](./documentation/libraries/access_security/admin/index.md)
+    - [Ownership Library](./documentation/libraries/access_security/ownership/index.md)
+    - [Pausable Library](./documentation/libraries/access_security/pausable/index.md)
+    - [Reentrancy Guard Library](./documentation/libraries/access_security/reentrancy/index.md)
+  - [Cryptography Libraries](./documentation/libraries/cryptography/index.md)
+    - [Bytecode Library](./documentation/libraries/cryptography/bytecode/index.md)
+    - [Merkle Library](./documentation/libraries/cryptography/merkle/index.md)
+  - [Math Libraries](./documentation/libraries/math/index.md)
+    - [Fixed Point Number Library](./documentation/libraries/math/fixed_point/index.md)
+    - [Signed Integers Library](./documentation/libraries/math/signed_integers/index.md)
+  - [Data Structure Libraries](./documentation/libraries/data_structures/index.md)
+    - [Queue Library](./documentation/libraries/data_structures/queue/index.md)

.docs/book/src/documentation/getting_started/index.md

@@ -0,0 +1,73 @@
+# Getting Started
+
+## Adding Sway Libs as a Dependency
+
+To import any library, the following dependency should be added to the project's `Forc.toml` file under `[dependencies]`.
+
+```sway
+sway_libs = { git = "https://github.com/FuelLabs/sway-libs", tag = "v0.1.0" }
+```
+
+For reference, here is a complete `Forc.toml` file:
+
+```sway
+[project]
+authors = ["Fuel Labs <[email protected]>"]
+entry = "main.sw"
+license = "Apache-2.0"
+name = "MyProject"
+
+[dependencies]
+sway_libs = { git = "https://github.com/FuelLabs/sway-libs", tag = "v0.1.0" }
+```
+
+> **NOTE:** Be sure to set the tag to the latest release.
+
+## Importing Sway Libs to Your Project
+
+Once Sway Libs is a dependency to your project, you may then import a library in your Sway Smart Contract as so:
+
+```sway
+use sway_libs::<library>::<library_function>;
+```
+
+For example, to import the `only_owner()` from the Ownership Library, use the following statement at the top of your Sway file:
+
+```sway
+use sway_libs::ownership::only_owner;
+```
+
+> **NOTE:**
+> All projects currently use `forc v0.50.0`, `fuels-rs v0.53.0` and `fuel-core 0.22.0`.
+
+## Using Sway Libs
+
+Once the library you require has been imported to your project, you may call or use any functions and structures the library provides.
+
+In the following example, we import the Pausable Library and implement the `Pausable` abi with it's associated functions.
+
+```sway
+use sway_libs::pausable::{_is_paused, _pause, _unpause, Pausable};
+
+// Implement the Pausable ABI for our contract
+impl Pausable for Contract {
+    #[storage(write)]
+    fn pause() {
+        _pause(); // Call the provided pause function.
+    }
+
+    #[storage(write)]
+    fn unpause() {
+        _unpause(); // Call the provided unpause function.
+    }
+
+    #[storage(read)]
+    fn is_paused() -> bool {
+        _is_paused() // Call the provided is paused function.
+    }
+}
+```
+
+Any instructions related to using a specific library should be found within the README.md of that library.
+
+For implementation details on the libraries please see the [Sway Libs Docs](https://fuellabs.github.io/sway-libs/master/sway_libs/).

.docs/book/src/documentation/getting_started/running_tests.md

@@ -0,0 +1,22 @@
+# Running Tests
+
+There are two sets of tests that should be run: inline tests and sdk-harness tests.
+
+In order to run the inline tests, make sure you are in the `libs/` folder of this repository `sway-libs/libs/<you are here>`.
+
+Run the tests:
+
+```bash
+forc test
+```
+
+Once these tests have passed, make sure you are in the `tests/` folder of this repository `sway-libs/tests/<you are here>`.
+
+Run the tests:
+
+```bash
+forc test && cargo test
+```
+
+> **NOTE:**
+> This may take a while depending on your hardware, future improvements to Sway will decrease build times. After this has been run once, indiviual test projects may be built on their own to save time.

.docs/book/src/documentation/libraries/access_security/admin/index.md

@@ -0,0 +1,103 @@
+# Admin Library
+
+The Admin library provides a way to block users without an "adimistrative status" from calling functions within a contract. The Admin Library differs from the [Ownership Library](../ownership/index.md) as multiple users may have adimistrative status. The Admin Library is often used when needing administrative calls on a contract that involve multiple users or a whitelist.
+
+This library extends the [Ownership Library](../ownership/index.md). The Ownership library must be imported and used to enable the Admin library. Only the contract's owner may add and remove administrative users. 
+
+For implementation details on the Admin Library please see the [Sway Libs Docs](https://fuellabs.github.io/sway-libs/master/sway_libs/admin/index.html).
+
+# Using the Library
+
+## Importing the Admin Library
+
+In order to use the Admin Library, Sway Libs must be added to the `Forc.toml` file and then imported into your Sway project. To add Sway Libs as a dependency to the `Forc.toml` file in your project please see the [Getting Started](../../../getting_started/index.md).
+
+To import the Admin Library, be sure to include both the Admin and Ownership Libraries in your import statements.
+
+```sway
+use sway_libs::{admin::*, ownership::*};
+```
+
+## Integrating the Admin Library into the Ownership Library
+
+To use the Admin library, be sure to set a contract owner for your contract. The following demonstrates setting a contract owner using the [Ownership Library](../ownership/).
+
+```sway
+use sway_libs::{admin::add_admin, ownership::initialize_ownership};
+
+#[storage(read, write)]
+fn my_constructor(new_owner: Identity) {
+    initialize_ownership(new_owner);
+}
+
+#[storage(read, write)]
+fn add_a_admin(new_admin: Identity) {
+    // Can only be called by contract's owner set in the constructor above.
+    add_admin(new_admin);
+}
+```
+
+## Basic Functionality
+
+### Adding an Admin
+
+To add a new admin to a contract, call the `add_admin()` function.
+
+```sway
+#[storage(read, write)]
+fn add_a_admin(new_admin: Identity) {
+    // Can only be called by contract's owner.
+    add_admin(new_admin);
+}
+```
+> **NOTE** Only the contract's owner may call this function. Please see the example above to set a contract owner.
+
+### Removing an Admin
+
+To remove an admin from a contract, call the `remove_admin()` function.
+
+```sway
+#[storage(read, write)]
+fn remove_a_admin(old_admin: Identity) {
+    // Can only be called by contract's owner.
+    remove_admin(old_admin);
+}
+```
+
+> **NOTE** Only the contract's owner may call this function. Please see the example above to set a contract owner.
+
+### Applying Restrictions
+
+To restrict a function to only an admin, call the `only_admin()` function.
+
+```sway
+#[storage(read)]
+fn only_owner_may call() {
+    only_admin();
+    // Only an admin may reach this line.
+}
+```
+
+> **NOTE:** Admins and the contract's owner are independent of one another. `only_admin()` will revert if called by the contract's owner.
+
+To restrict a function to only an admin or the contract's owner, call the `only_owner_or_admin()` function.
+
+```sway
+#[storage(read)]
+fn both_owner_or_admin_may_call() {
+    only_owner_or_admin();
+    // Only an admin may reach this line.
+}
+```
+
+### Checking Admin Status
+
+To check the administrative privledges of a user, call the `is_admin()` function.
+
+```sway
+#[storage(read)]
+fn check_if_admin(admin: Identity) {
+    let status = is_admin(admin);
+    assert(status);
+}
+```

.docs/book/src/documentation/libraries/access_security/index.md

@@ -0,0 +1,21 @@
+# Access Control and Security Libraries
+
+Access Control and Security Libraries are any libraries that are built and intended to provide additional saftey when developing smart contracts.
+
+For implementation details on the libraries please see the [Sway Libs Docs](https://fuellabs.github.io/sway-libs/master/sway_libs/).
+
+## Ownership Library
+
+The [Ownership](./ownership/index.md) Library is used to apply restrictions on functions such that only a **single** user may call them.
+
+## Admin Library
+
+The [Admin](./admin/index.md) Library is used to apply restrictions on functions such that only a select few users may call them like a whitelist.
+
+## Pausable Library
+
+The [Pausable](./pausable/index.md) Library allows contracts to implement an emergency stop mechanism.
+
+## Reentrancy Guard Library
+
+The [Reentrancy Guard](./reentrancy/index.md) Library is used to detect and prevent reentrancy attacks.

.docs/book/src/documentation/libraries/access_security/ownership/index.md

@@ -0,0 +1,72 @@
+# Ownership Library
+
+The Ownership Library provides a way to block anyone other than a **single** "owner" from calling functions. The Ownership Library is often used when needing administrative calls on a contract by a single user.
+
+For implementation details on the Ownership Library please see the [Sway Libs Docs](https://fuellabs.github.io/sway-libs/master/sway_libs/ownership/index.html).
+
+# Using the Library
+
+## Importing the Ownership Library
+
+In order to use the Ownership library, Sway Libs and [Sway Standards]() must be added to the `Forc.toml` file and then imported into your Sway project. To add Sway Libs as a dependency to the `Forc.toml` file in your project please see the [Getting Started](../../../getting_started/index.md). To add Sway Standards as a dependency please see the [Sway Standards Book]().
+
+To import the Ownership Library and [SRC-5](https://github.com/FuelLabs/sway-standards/blob/master/SRCs/src-5.md) Standard to your Sway Smart Contract, add the following to your Sway file:
+
+```sway
+use sway_libs::ownership::*;
+use standards::src5::*;
+```
+
+## Integrating the Ownership Library into the SRC-5 Standard
+
+To implement the [SRC-5](https://github.com/FuelLabs/sway-standards/blob/master/SRCs/src-5.md) standard with the Ownership library, be sure to add the Sway Standards dependency to your contract. The following demonstrates the integration of the Ownership library with the SRC-5 standard.
+
+```sway
+use sway_libs::ownership::_owner;
+use standards::src_5::{State, SRC5};
+
+impl SRC5 for Contract {
+    #[storage(read)]
+    fn owner() -> State {
+        _owner()
+    }
+}
+```
+
+> **NOTE** A constructor method must be implemented to initialize the owner.
+
+## Basic Functionality
+
+### Setting a Contract Owner
+
+Once imported, the Ownership Library's functions will be available. To use them initialize the owner for your contract by calling the `initialize_ownership()` function in your own constructor method.
+
+```sway
+#[storage(read, write)]
+fn my_constructor(new_owner: Identity) {
+    initialize_ownership(new_owner);
+}
+```
+
+### Applying Restrictions
+
+To restrict a function to only the owner, call the `only_owner()` function.
+
+```sway
+#[storage(read)]
+fn only_owner_may_call() {
+    only_owner();
+    // Only the contract's owner may reach this line.
+}
+```
+
+### Checking the Ownership Status
+
+To return the ownership state from storage, call the `_owner()` function.
+
+```sway
+#[storage(read)]
+fn get_owner_state() {
+    let owner: State = _owner();
+}
+```