Libraries

Libraries in Sway are files used to define new common behavior.

The most prominent example of this is the Sway Standard Library that is made implicitly available to all Forc projects created using forc new.

Writing Libraries

Libraries are defined using the library keyword at the beginning of a file, followed by a name so that they can be imported.

library;

// library code

A good reference library to use when learning library design is the Sway Standard Library. For example, the standard library offers an implementation of enum Option<T> which is a generic type that represents either the existence of a value using the variant Some(..) or a value's absence using the variant None. The Sway file implementing Option<T> has the following structure:

The library keyword:

library;

A use statement that imports revert from another library inside the standard library:

use ::revert::revert;

The enum definition which starts with the keyword pub to indicate that this Option<T> is publically available outside the option library:

pub enum Option<T> {
    // variants
}

An impl block that implements some methods for Option<T>:

impl<T> Option<T> {

    fn is_some(self) -> bool {
        // body of is_some
    }

    // other methods
}

Now that the library option is fully written, and because Option<T> is defined with the pub keyword, we are now able to import Option<T> using use std::option::Option; from any Sway project and have access to all of its variants and methods. That being said, Option is automatically available in the standard library prelude so you never actually have to import it manually.

Libraries are composed of just a Forc.toml file and a src directory, unlike contracts which usually contain a tests directory and a Cargo.toml file as well. An example of a library's Forc.toml:

[project]
authors = ["Fuel Labs <contact@fuel.sh>"]
entry = "lib.sw"
license = "Apache-2.0"
name = "my_library"

[dependencies]

which denotes the authors, an entry file, the name by which it can be imported, and any dependencies.

For large libraries, it is recommended to have a lib.sw entry point re-export all other sub-libraries.

The mod keyword registers a submodule, making its items (such as functions and structs) accessible from the parent library. If used at the top level it will refer to a file in the src folder and in other cases in a folder named after the library in which it is defined.

For example, the lib.sw of the standard library looks like:

library;

mod block;
mod storage;
mod constants;
mod vm;
// .. Other deps

with other libraries contained in the src folder, like the vm library (inside of src/vm.sw):

library;

mod evm;
// ...

and it's own sub-library evm located in src/vm/evm.sw:

library;

// ...

Using Libraries

There are two types of Sway libraries, based on their location and how they can be imported.

Internal Libraries

Internal libraries are located within the project's src directory alongside main.sw or in the appropriate folders as shown below:

$ tree
.
├── Cargo.toml
├── Forc.toml
└── src
    ├── internal_lib.sw
    ├── main.sw
    └── internal_lib
        └── nested_lib.sw

As internal_lib is an internal library, it can be imported into main.sw as follows:

Use the mod keyword followed by the library name to make the internal library a dependancy
Use the use keyword with a :: separating the name of the library and the imported item(s)

mod internal_lib; // Assuming the library name in `internal_lib.sw` is `internal_lib`

use internal_lib::mint;

// `mint` from `internal_library` is now available in this file

External Libraries

External libraries are located outside the main src directory as shown below:

$ tree
.
├── my_project
│   ├── Cargo.toml
│   ├── Forc.toml
│   └─── src
│       └── main.sw
│
└── external_lib
    ├── Cargo.toml
    ├── Forc.toml
    └─── src
        └── lib.sw

As external_lib is outside the src directory of my_project, it needs to be added as a dependency in the Forc.toml file of my_project, by adding the library path in the dependencies section as shown below, before it can be imported:

[dependencies]
external_library = { path = "../external_library" }

Once the library dependency is added to the toml file, you can import items from it as follows:

Make sure the item you want imported are declared with the pub keyword (if applicable, for instance: pub fn mint() {})
Use the use keyword to selectively import items from the library

use external_library::mint;

// `mint` from `external_library` is now available in this file

Wildcard imports using * are supported, but it is generally recommended to use explicit imports where possible.

Note: the standard library is implicitly available to all Forc projects, that is, you are not required to manually specify std as an explicit dependency in Forc.toml.

Reference Sway Libraries

The repository sway-libs is a collection of external libraries that you can import and make use of in your Fuel applications. These libraries are meant to be learning references of common use-cases valuable for dapp development.

Some Sway Libraries to try out:

Example

You can import and use a Sway Library such as the NFT library just like any other external library.

use sway_libs::nft::{
    mint,
    transfer,
    owner_of,
    approve,
};

Once imported, you can use the following basic functionality of the library in your smart contract:

Minting tokens
Transfering tokens
Retrieving owner of a token
Approving users to transfer a token

The Sway Programming Language