Document not found (404)
+This URL is invalid, sorry. Please use the navigation bar or search to continue.
+ +This URL is invalid, sorry. Please use the navigation bar or search to continue.
+ +Through the use of StorageKeys, you may have nested storage collections such as storing a StorageString in a StorageMap<K, V>.
For example, here we have a few common nested storage types declared in a storage block:
storage {
+ nested_map_vec: StorageMap<u64, StorageVec<u8>> = StorageMap {},
+ nested_map_string: StorageMap<u64, StorageString> = StorageMap {},
+ nested_vec_bytes: StorageVec<StorageBytes> = StorageVec {},
+}
+Please note that storage initialization is needed to do this.
+++NOTE: When importing a storage type, please be sure to use the glob operator i.e.
+use std::storage::storage_vec::*.
StorageVec<T> in a StorageMap<K, V>The following demonstrates how to write to a StorageVec<T> that is nested in a StorageMap<T, V>:
// Setup and initialize storage for the StorageVec.
+ storage.nested_map_vec.try_insert(10, StorageVec {});
+
+ // Method 1: Push to the vec directly
+ storage.nested_map_vec.get(10).push(1u8);
+ storage.nested_map_vec.get(10).push(2u8);
+ storage.nested_map_vec.get(10).push(3u8);
+
+ // Method 2: First get the storage key and then push the values.
+ let storage_key_vec: StorageKey<StorageVec<u8>> = storage.nested_map_vec.get(10);
+ storage_key_vec.push(4u8);
+ storage_key_vec.push(5u8);
+ storage_key_vec.push(6u8);
+The following demonstrates how to read from a StorageVec<T> that is nested in a StorageMap<T, V>:
// Method 1: Access the StorageVec directly.
+ let stored_val1: u8 = storage.nested_map_vec.get(10).pop().unwrap();
+ let stored_val2: u8 = storage.nested_map_vec.get(10).pop().unwrap();
+ let stored_val3: u8 = storage.nested_map_vec.get(10).pop().unwrap();
+
+ // Method 2: First get the storage key and then access the value.
+ let storage_key: StorageKey<StorageVec<u8>> = storage.nested_map_vec.get(10);
+ let stored_val4: u8 = storage_key.pop().unwrap();
+ let stored_val5: u8 = storage_key.pop().unwrap();
+ let stored_val6: u8 = storage_key.pop().unwrap();
+StorageString in a StorageMap<K, V>The following demonstrates how to write to a StorageString that is nested in a StorageMap<T, V>:
// Setup and initialize storage for the StorageString.
+ storage.nested_map_string.try_insert(10, StorageString {});
+
+ // Method 1: Store the string directly.
+ let my_string = String::from_ascii_str("Fuel is blazingly fast");
+ storage.nested_map_string.get(10).write_slice(my_string);
+
+ // Method 2: First get the storage key and then write the value.
+ let my_string = String::from_ascii_str("Fuel is modular");
+ let storage_key: StorageKey<StorageString> = storage.nested_map_string.get(10);
+ storage_key.write_slice(my_string);
+The following demonstrates how to read from a StorageString that is nested in a StorageMap<T, V>:
// Method 1: Access the string directly.
+ let stored_string: String = storage.nested_map_string.get(10).read_slice().unwrap();
+
+ // Method 2: First get the storage key and then access the value.
+ let storage_key: StorageKey<StorageString> = storage.nested_map_string.get(10);
+ let stored_string: String = storage_key.read_slice().unwrap();
+StorageBytes in a StorageVec<T>The following demonstrates how to write to a StorageBytes that is nested in a StorageVec<T>:
// Setup and initialize storage for the StorageVec.
+ storage.nested_map_vec.try_insert(10, StorageVec {});
+
+ // Method 1: Push to the vec directly
+ storage.nested_map_vec.get(10).push(1u8);
+ storage.nested_map_vec.get(10).push(2u8);
+ storage.nested_map_vec.get(10).push(3u8);
+
+ // Method 2: First get the storage key and then push the values.
+ let storage_key_vec: StorageKey<StorageVec<u8>> = storage.nested_map_vec.get(10);
+ storage_key_vec.push(4u8);
+ storage_key_vec.push(5u8);
+ storage_key_vec.push(6u8);
+The following demonstrates how to read from a StorageBytes that is nested in a StorageVec<T>:
// Method 1: Access the StorageVec directly.
+ let stored_val1: u8 = storage.nested_map_vec.get(10).pop().unwrap();
+ let stored_val2: u8 = storage.nested_map_vec.get(10).pop().unwrap();
+ let stored_val3: u8 = storage.nested_map_vec.get(10).pop().unwrap();
+
+ // Method 2: First get the storage key and then access the value.
+ let storage_key: StorageKey<StorageVec<u8>> = storage.nested_map_vec.get(10);
+ let stored_val4: u8 = storage_key.pop().unwrap();
+ let stored_val5: u8 = storage_key.pop().unwrap();
+ let stored_val6: u8 = storage_key.pop().unwrap();
+If you want the values in storage to be positioned differently, for instance to avoid collisions with storage from another contract when loading code, you can use the namespace annotation to add a salt to the slot calculations.
+storage {
+ example_namespace {
+ foo: u64 = 0,
+ },
+It is possible to leverage FuelVM storage operations directly using the std::storage::storage_api::write and std::storage::storage_api::read functions provided in the standard library. With this approach, you will have to manually assign the internal key used for storage. An example is as follows:
contract;
+
+use std::storage::storage_api::{read, write};
+
+abi StorageExample {
+ #[storage(write)]
+ fn store_something(amount: u64);
+
+ #[storage(read)]
+ fn get_something() -> u64;
+}
+
+const STORAGE_KEY: b256 = 0x0000000000000000000000000000000000000000000000000000000000000000;
+
+impl StorageExample for Contract {
+ #[storage(write)]
+ fn store_something(amount: u64) {
+ write(STORAGE_KEY, 0, amount);
+ }
+
+ #[storage(read)]
+ fn get_something() -> u64 {
+ let value: Option<u64> = read::<u64>(STORAGE_KEY, 0);
+ value.unwrap_or(0)
+ }
+}
+++ +Note: Though these functions can be used for any data type, they should mostly be used for arrays because arrays are not yet supported in
+storageblocks. Note, however, that all data types can be used as types for keys and/or values inStorageMap<K, V>without any restrictions.
Sway provides the ability to declare a type alias to give an existing type another name. For this we use the type keyword. For example, we can create the alias Kilometers to u64 like so:
type Kilometers = u64;
+Now, the alias Kilometers is a synonym for u64. Note that Kilometers is not a separate new type. Values that have the type Kilometers will be treated the same as values of type u64:
let x: u64 = 5;
+ let y: Kilometers = 5;
+ assert(x + y == 10);
+Because Kilometers and u64 are the same type, we can add values of both types and we can pass Kilometers values to functions that take u64 parameters. However, using this method, we don’t get the type checking benefits that we get from introducing a separate new type called Kilometers. In other words, if we mix up Kilometers and i32 values somewhere, the compiler will not give us an error.
The main use case for type synonyms is to reduce repetition. For example, we might have a lengthy array type like this:
+[MyStruct<u64, b256>; 5]
+Writing this lengthy type in function signatures and as type annotations all over the code can be tiresome and error prone. Imagine having a project full of code like this:
+fn foo_long(array: [MyStruct<u64, b256>; 5]) -> [MyStruct<u64, b256>; 5] {
+ array
+}
+A type alias makes this code more manageable by reducing the repetition. Below, we’ve introduced an alias named MyArray for the verbose type and can replace all uses of the type with the shorter alias MyArray:
type MyArray = [MyStruct<u64, b256>; 5];
+
+fn foo_shorter(array: MyArray) -> MyArray {
+ array
+}
+This code is much easier to read and write! Choosing a meaningful name for a type alias can help communicate your intent as well.
+ +While many users will never have to touch assembly language while writing Sway code, it is a powerful tool that enables many advanced use-cases (e.g., optimizations, building libraries, etc).
+In Sway, the way we use assembly inline is to declare an asm block like this:
asm() {...}
+Declaring an asm block is similar to declaring a function.
+We can specify register names to operate on as arguments, we can perform assembly instructions within the block, and we can return a value by specifying a return register.
+Here's an example showing what this might look like:
pub fn add_1(num: u32) -> u32 {
+ asm(r1: num, r2) {
+ add r2 r1 one;
+ r2: u32
+ }
+}
+The return register is specified at the end of the asm block, after all the assembly instructions. It consists of the register name and an optional return type. In the above example, the return register name is r2 and the return type is u32.
+If the return type is omitted, it is u64 by default.
The return register itself is optional. If it is not specified, similar to functions, the returned value from the asm block will be unit, ().
An asm block can only return a single register. If you really need to return more than one value, you can modify a tuple. Here's an example showing how you can implement this for (u64, u64):
script;
+
+fn adder(a: u64, b: u64, c: u64) -> (u64, u64) {
+ let empty_tuple = (0u64, 0u64);
+ asm(output: empty_tuple, r1: a, r2: b, r3: c, r4, r5) {
+ add r4 r1 r2; // add a & b and put the result in r4
+ add r5 r2 r3; // add b & c and put the result in r5
+ sw output r4 i0; // store the word in r4 in output + 0 words
+ sw output r5 i1; // store the word in r5 in output + 1 word
+ output: (u64, u64) // return both values
+ }
+}
+
+fn main() -> bool {
+ let (first, second) = adder(1, 2, 3);
+ assert(first == 3);
+ assert(second == 5);
+ true
+}
+Note that this is contrived example meant to demonstrate the syntax; there's absolutely no need to use assembly to add integers!
+Note that in the above example:
+r1 with the value of num.r2 (you may choose any register names you want).add opcode to add one to the value of r1 and store it in r2.one is an example of a "reserved register", of which there are 16 in total. Further reading on this is linked below under "Semantics".r2 and specify the return type as being u32.An important note is that the ji and jnei opcodes are not available within an asm block. For those looking to introduce control flow to asm blocks, it is recommended to surround smaller chunks of asm with control flow (if, else, and while).
For examples of assembly in action, check out the Sway standard library.
+For a complete list of all instructions supported in the FuelVM: Instructions.
+And to learn more about the FuelVM semantics: Semantics.
+ +Associated types in Sway allow you to define placeholder types within a trait, which can be customized by concrete +implementations of that trait. These associated types are used to specify the return types of trait methods or to +define type relationships within the trait.
+Associated types are a powerful feature of Sway's trait system, enabling generic programming and abstraction over +types. They help improve code clarity and maintainability by allowing you to define generic traits without committing +to specific types.
+Associated types are declared within a trait using the type keyword. Here's the syntax for declaring an associated type:
+trait MyTrait {
+ type AssociatedType;
+}
+Concrete implementations of a trait with associated types must provide a specific type for each associated type +defined in the trait. Here's an example of implementing a trait with an associated type:
+struct MyStruct;
+
+impl MyTrait for MyStruct {
+ type AssociatedType = u32; // Implementing the associated type with u32
+}
+In this example, MyStruct implements MyTrait and specifies that the associated type AssociatedType is u32.
Associated types are used within trait methods or where the trait is used as a bound for generic functions or +structs. You can use the associated type like any other type. Here's an example:
+trait MyTrait {
+ type AssociatedType;
+
+ fn get_value(self) -> Self::AssociatedType;
+}
+
+struct MyStruct;
+
+impl MyTrait for MyStruct {
+ type AssociatedType = u32;
+
+ fn get_value(self) -> Self::AssociatedType {
+ 42
+ }
+}
+In this example, get_value is a trait method that returns an associated type AssociatedType.
Associated types are particularly useful in scenarios where you want to define traits that work with different +types of data structures or abstractions, allowing the implementer to specify the concrete types. Some common use cases include:
+In Sway, generic types follow a very similar pattern to those in Rust. Let's look at some example syntax, +starting with a generic function:
+fn noop<T>(argument: T) -> T {
+ argument
+}
+Here, the noop() function trivially returns exactly what was given to it. T is a type parameter, and it says
+that this function exists for all types T. More formally, this function could be typed as:
noop :: ∀T. T -> T
+Generic types are a way to refer to types in general, meaning without specifying a single type. Our noop function
+would work with any type in the language, so we don't need to specify noop(argument: u8) -> u8, noop(argument: u16) -> u16, etc.
One question that arises when dealing with generic types is: how does the assembly handle this? There are a few approaches to handling +generic types at the lowest level. Sway uses a technique called monomorphization. This +means that the generic function is compiled to a non-generic version for every type it is called on. In this way, generic functions are +purely shorthand for the sake of ergonomics.
+An important background to know before diving into trait constraints is that the where clause can be used to specify the required traits for the generic argument. So, when writing something like a HashMap you may
+want to specify that the generic argument implements a Hash trait.
fn get_hashmap_key<T>(key: T) -> b256
+ where T: Hash
+{
+ // Code within here can then call methods associated with the Hash trait on Key
+}
+Of course, our noop() function is not useful. Often, a programmer will want to declare functions over types which satisfy certain traits.
+For example, let's try to implement the successor function, successor(), for all numeric types.
fn successor<T>(argument: T)
+ where T: Add
+{
+ argument + 1
+}
+Run forc build, and you will get:
.. |
+ 9 | where T: Add
+10 | {
+11 | argument + 1
+ | ^ Mismatched types: expected type "T" but saw type "u64"
+12 | }
+13 |
+This is because we don't know for a fact that 1, which in this case defaulted to 1u64, actually can be added to T. What if T is f64? Or b256? What does it mean to add 1u64 in these cases?
We can solve this problem with another trait constraint. We can only find the successor of some value of type T if that type T defines some incrementor. Let's make a trait:
trait Incrementable {
+ /// Returns the value to add when calculating the successor of a value.
+ fn incrementor() -> Self;
+}
+Now, we can modify our successor() function:
fn successor<T>(argument: T)
+ where T: Add,
+ T: Incrementable
+{
+ argument + T::incrementor()
+}
+Just like functions, structs and enums can be generic. Let's take a look at the standard library version of Option<T>:
enum Option<T> {
+ Some: T,
+ None: (),
+}
+Just like an unconstrained generic function, this type exists for all (∀) types T. Result<T, E> is another example:
enum Result<T, E> {
+ Ok: T,
+ Err: E,
+}
+Both generic enums and generic structs can be trait constrained, as well. Consider this struct:
+struct Foo<T>
+ where T: Add
+{
+ field_one: T,
+}
+Similar to Rust, Sway has what is colloquially known as the turbofish. The turbofish looks like this: ::<> (see the little fish with bubbles behind it?). The turbofish is used to annotate types in a generic context. Say you have the following function:
fn foo<T, E>(t: T) -> Result<T, E> {
+ Ok(t)
+}
+In this code example, which is admittedly asinine, you can't possibly know what type E is. You'd need to provide the type manually, with a turbofish:
fn foo<T, E>(t: T) -> Result<T, E> {
+ Ok::<T, MyErrorType>(t)
+}
+It is also common to see the turbofish used on the function itself:
+fn main() {
+ foo::<Bar, Baz>()
+}
+At a high level, Sway allows you to define constraints, or restrictions, that +allow you to strike a balance between writing abstract and reusable code and +enforcing compile-time checks to determine if the abstract code that you've +written is correct.
+The "abstract and reusable" part largely comes from generic types and the +"enforcing compile-time checks" part largely comes from trait constraints. +Generic types can be used with functions, structs, and enums (as we have seen in +this book), but they can also be used with traits.
+Combining generic types with traits allows you to write abstract and reusable +traits that can be implemented for any number of data types.
+For example, imagine that you want to write a trait for converting between
+different types. This would be similar to Rust's Into and From traits. In
+Sway your conversion trait would look something like:
trait Convert<T> {
+ fn from(t: T) -> Self;
+}
+The trait Convert takes a generic type T. Convert has one method
+from, which takes one parameter of type T and returns a Self. This means
+that when you implement Convert for a data type, from will return the type
+of that data type but will take as input the type that you define as T. Here
+is an example:
struct Square {
+ width: u64,
+}
+
+struct Rectangle {
+ width: u64,
+ length: u64,
+}
+
+impl Convert<Square> for Rectangle {
+ fn from(t: Square) -> Self {
+ Self {
+ width: t.width,
+ length: t.width,
+ }
+ }
+}
+In this example, you have two different data types, Square and Rectangle.
+You know that all squares are rectangles and thus Square can convert into Rectangle (but not vice
+versa) and thus you can implement the conversion trait for those types.
If we want to call these methods we can do so by:
+fn main() {
+ let s = Square { width: 5 };
+ let r = Rectangle::from(s);
+}
+Trait constraints allow you to use generic types and traits to place constraints +on what abstract code you are willing to accept in your program as correct. +These constraints take the form of compile-time checks for correctness.
+If we wanted to use trait constraints with our Convert trait from the previous
+section we could do so like so:
fn into_rectangle<T>(t: T) -> Rectangle
+where
+ Rectangle: Convert<T>,
+{
+ Rectangle::from(t)
+}
+This function allows you to take any generic data type T and convert it to the
+type Rectangle as long as Convert<T> is implemented for Rectangle.
+Calling this function with a type T for which Convert<T> is not implemented
+for Rectangle will fail Sway's compile-time checks.
Advanced concepts.
+ + +The Never type ! represents the type of computations which never resolve to any value at all.
break, continue and return expressions also have type !. For example we are allowed to
+write:
let x: ! = {
+ return 123
+};
+Although the let is pointless here, it illustrates the meaning of !. Since x is never
+assigned a value (because return returns from the entire function), x can be given type
+Never. We could also replace return 123 with a revert() or a never-ending loop and this code
+would still be valid.
A more realistic usage of Never is in this code:
let num: u32 = match get_a_number() {
+ Some(num) => num,
+ None => break,
+};
+Both match arms must produce values of type [u32], but since break never produces a value
+at all we know it can never produce a value which isn't a [u32]. This illustrates another
+behaviour of the ! type - expressions with type ! will coerce into any other type.
Note that ! type coerces into any other type, another example of this would be:
let x: u32 = {
+ return 123
+};
+Regardless of the type of x, the return block of type Never will always coerce into x type.
fn foo() {
+ let num: u64 = match Option::None::<u64> {
+ Some(num) => num,
+ None => return,
+ };
+}
+A trait opts a type into a certain type of behavior or functionality that can be shared among types. This allows for easy reuse of code and generic programming. If you have ever used a typeclass in Haskell, a trait in Rust, or even an interface in Java, these are similar concepts.
+Let's take a look at some code:
+trait Compare {
+ fn equals(self, b: Self) -> bool;
+} {
+ fn not_equals(self, b: Self) -> bool {
+ !self.equals(b)
+ }
+}
+We have just declared a trait called Compare. After the name of the trait, there are two blocks of code (a block is code enclosed in { curly brackets }). The first block is the interface surface. The second block is the methods provided by the trait. If a type can provide the methods in the interface surface, then it gets access to the methods in the trait for free! What the above trait is saying is: if you can determine if two values are equal, then for free, you can determine that they are not equal. Note that trait methods have access to the methods defined in the interface surface.
The example below implements a Compare trait for u64 to check if two numbers are equal. Let's take a look at how that is done:
impl Compare for u64 {
+ fn equals(self, b: Self) -> bool {
+ self == b
+ }
+}
+The above snippet declares all of the methods in the trait Compare for the type u64. Now, we have access to both the equals and not_equals methods for u64, as long as the trait Compare is in scope.
When using multiple traits, scenarios often come up where one trait may require functionality from another trait. This is where supertraits come in as they allow you to require a trait when implementing another trait, i.e., a trait with a trait.
+A good example of this is the Ord trait of the core library of Sway. The Ord trait requires the Eq trait, so Eq is kept as a separate trait as one may decide to implement Eq
+without implementing other parts of the Ord trait.
+trait Eq {
+ fn equals(self, b: Self) -> bool;
+}
+
+trait Ord: Eq {
+ fn gte(self, b: Self) -> bool;
+}
+
+impl Ord for u64 {
+ fn gte(self, b: Self) -> bool {
+ // As `Eq` is a supertrait of `Ord`, `Ord` can access the equals method
+ self.equals(b) || self.gt(b)
+ }
+}
+To require a supertrait, add a : after the trait name and then list the traits you would like to require and separate them with a +.
ABIs can also have supertrait annotations:
+contract;
+
+struct Foo {}
+impl ABIsupertrait for Foo {
+ fn foo() {}
+}
+
+trait ABIsupertrait {
+ fn foo();
+}
+
+abi MyAbi : ABIsupertrait {
+ fn bar();
+} {
+ fn baz() {
+ Self::foo() // supertrait method usage
+ }
+}
+
+impl ABIsupertrait for Contract {
+ fn foo() {}
+}
+
+// The implementation of MyAbi for Contract must also implement ABIsupertrait
+impl MyAbi for Contract {
+ fn bar() {
+ Self::foo() // supertrait method usage
+ }
+}
+The implementation of MyAbi for Contract must also implement the ABIsupertrait trait. Methods in ABIsupertrait are not available externally, i.e. they're not actually contract methods, but they can be used in the actual contract methods, as shown in the example above.
ABI supertraits are intended to make contract implementations compositional, allowing combining orthogonal contract features using, for instance, libraries.
+In addition to supertraits, ABIs can have superABI annotations:
+contract;
+
+abi MySuperAbi {
+ fn foo();
+}
+
+abi MyAbi : MySuperAbi {
+ fn bar();
+}
+
+impl MySuperAbi for Contract {
+ fn foo() {}
+}
+
+// The implementation of MyAbi for Contract must also implement MySuperAbi
+impl MyAbi for Contract {
+ fn bar() {}
+}
+The implementation of MyAbi for Contract must also implement the MySuperAbi superABI. Methods in MySuperAbi will be part of the MyAbi contract interface, i.e. will be available externally (and hence cannot be called from other MyAbi contract methods).
SuperABIs are intended to make contract implementations compositional, allowing combining orthogonal contract features using, for instance, libraries.
+Traits can declare different kinds of associated items in their interface surface:
+ +Associated functions in traits consist of just function signatures. This indicates that each implementation of the trait for a given type must define all the trait functions.
+trait Trait {
+ fn associated_fn(self, b: Self) -> bool;
+}
+Associated constants are constants associated with a type.
+trait Trait {
+ const ID: u32 = 0;
+}
+The initializer expression of an associated constants in a trait definition may be omitted to indicate that each implementation of the trait for a given type must specify an initializer:
trait Trait {
+ const ID: u32;
+}
+Check the associated consts section on constants page.
Associated types in Sway allow you to define placeholder types within a trait, which can be customized by concrete +implementations of that trait. These associated types are used to specify the return types of trait methods or to +define type relationships within the trait.
+trait MyTrait {
+ type AssociatedType;
+}
+Check the associated types section on associated types page.
When writing generic code, you can constraint the choice of types for a generic argument by using the where keyword. The where keyword specifies which traits the concrete generic parameter must implement. In the below example, the function expects_some_trait can be called only if the parameter t is of a type that has SomeTrait implemented. To call the expects_both_traits, parameter t must be of a type that implements both SomeTrait and SomeOtherTrait.
trait SomeTrait { }
+trait SomeOtherTrait { }
+
+fn expects_some_trait<T>(t: T) where T: SomeTrait {
+ // ...
+}
+
+fn expects_some_other_trait<T>(t: T) where T: SomeOtherTrait {
+ // ...
+}
+
+fn expects_both_traits<T>(t: T) where T: SomeTrait + SomeOtherTrait {
+ // ...
+}
+Sway types can be classified in various ways according to their intrinsic properties. These classifications are represented as marker traits. Marker traits are implemented by the compiler and cannot be explicitly implemented in code.
+E.g., all types whose instances can be used in the panic expression automatically implement the Error marker trait. We can use that trait, e.g., to specify that a generic argument must be compatible with the panic expression:
fn panic_with_error<E>(err: E) where E: Error {
+ panic err;
+}
+++Note
+panicexpression and error types have not yet been implemented
All marker traits are defined in the core::marker module.
Often, libraries and APIs have interfaces that are abstracted over a type that implements a certain trait. It is up to the consumer of the interface to implement that trait for the type they wish to use with the interface. For example, let's take a look at a trait and an interface built off of it.
+library;
+
+pub enum Suit {
+ Hearts: (),
+ Diamonds: (),
+ Clubs: (),
+ Spades: (),
+}
+
+pub trait Card {
+ fn suit(self) -> Suit;
+ fn value(self) -> u8;
+}
+
+fn play_game_with_deck<T>(a: Vec<T>) where T: Card {
+ // insert some creative card game here
+}
+Now, if you want to use the function play_game_with_deck with your struct, you must implement Card for your struct. Note that the following code example assumes a dependency games has been included in the Forc.toml file.
script;
+
+use games::*;
+
+struct MyCard {
+ suit: Suit,
+ value: u8
+}
+
+impl Card for MyCard {
+ fn suit(self) -> Suit {
+ self.suit
+ }
+ fn value(self) -> u8 {
+ self.value
+ }
+}
+
+fn main() {
+ let mut i = 52;
+ let mut deck: Vec<MyCard> = Vec::with_capacity(50);
+ while i > 0 {
+ i = i - 1;
+ deck.push(MyCard { suit: generate_random_suit(), value: i % 4}
+ }
+ play_game_with_deck(deck);
+}
+
+fn generate_random_suit() -> Suit {
+ [ ... ]
+}
+Sway is fundamentally a blockchain language, and it offers a selection of types tailored for the blockchain use case.
+These are provided via the standard library (lib-std) which both add a degree of type-safety, as well as make the intention of the developer more clear.
Address TypeThe Address type is a type-safe wrapper around the primitive b256 type. Unlike the EVM, an address never refers to a deployed smart contract (see the ContractId type below). An Address can be either the hash of a public key (effectively an externally owned account if you're coming from the EVM) or the hash of a predicate. Addresses own UTXOs.
An Address is implemented as follows.
pub struct Address {
+ value: b256,
+}
+Casting between the b256 and Address types must be done explicitly:
let my_number: b256 = 0x000000000000000000000000000000000000000000000000000000000000002A;
+let my_address: Address = Address::from(my_number);
+let forty_two: b256 = my_address.into();
+ContractId TypeThe ContractId type is a type-safe wrapper around the primitive b256 type. A contract's ID is a unique, deterministic identifier analogous to a contract's address in the EVM. Contracts cannot own UTXOs but can own assets.
A ContractId is implemented as follows.
pub struct ContractId {
+ value: b256,
+}
+Casting between the b256 and ContractId types must be done explicitly:
let my_number: b256 = 0x000000000000000000000000000000000000000000000000000000000000002A;
+let my_contract_id: ContractId = ContractId::from(my_number);
+let forty_two: b256 = my_contract_id.into();
+ContractIdTo get the ContractId of a contract in an internal context use the ContractId::this() function:
impl MyContract for Contract {
+ fn foo() {
+ let this_contract_id: ContractId = ContractId::this();
+ }
+}
+Identity TypeThe Identity type is an enum that allows for the handling of both Address and ContractId types. This is useful in cases where either type is accepted, e.g., receiving funds from an identified sender, but not caring if the sender is an address or a contract.
An Identity is implemented as follows.
pub enum Identity {
+ Address: Address,
+ ContractId: ContractId,
+}
+Casting to an Identity must be done explicitly:
let raw_address: b256 = 0xddec0e7e6a9a4a4e3e57d08d080d71a299c628a46bc609aab4627695679421ca;
+ let my_identity: Identity = Identity::Address(Address::from(raw_address));
+A match statement can be used to return to an Address or ContractId as well as handle cases in which their execution differs.
let my_contract_id: ContractId = match my_identity {
+ Identity::ContractId(identity) => identity,
+ _ => revert(0),
+ };
+ match my_identity {
+ Identity::Address(address) => takes_address(address),
+ Identity::ContractId(contract_id) => takes_contract_id(contract_id),
+ };
+A common use case for Identity is for access control. The use of Identity uniquely allows both ContractId and Address to have access control inclusively.
let sender = msg_sender().unwrap();
+ require(
+ sender == storage
+ .owner
+ .read(),
+ MyError::UnauthorizedUser(sender),
+ );
+Every value in Sway is of a certain type. Although deep down, all values are just ones and zeroes in the underlying virtual machine, Sway needs to know what those ones and zeroes actually mean. This is accomplished with types.
+ + +Sway is a statically typed language. At compile time, the types of every value must be known. This does not mean you need to specify every single type: usually, the type can be reasonably inferred by the compiler.
+ +Sway has the following primitive types:
+() (unit type)u8 (8-bit unsigned integer)u16 (16-bit unsigned integer)u32 (32-bit unsigned integer)u64 (64-bit unsigned integer)u256 (256-bit unsigned integer)str[] (fixed-length string)str (string slices)bool (Boolean true or false)b256 (256 bits (32 bytes), i.e. a hash)All other types in Sway are built up of these primitive types, or references to these primitive types. You may notice that there are no signed integers—this is by design. In the blockchain domain that Sway occupies, floating-point values and negative numbers have smaller utility, so their implementation has been left up to libraries for specific use cases.
+ +The unit type, (), is a type that allows only one value, and thus, represents a value with no information. It is used to indicate the absence of a meaningful value, or the result of a function that performs an action, but does not return any data. The value of the unit type, called simply unit, has the same symbol as the unit type, (). Unit type in Sway serves a similar purpose as void in imperative languages like C or Java.
For example:
+fn returns_unit() -> () { // Here, `()` represent the unit type.
+ () // Here, `()` represents the single unit value of the unit type.
+}
+In Sway, if the function return type is not specified, it is () by default. Thus, the above example is semantically same as the following:
fn returns_unit() {
+}
+All of the unsigned integer types are numeric types.
+Numbers can be declared with binary syntax, hexadecimal syntax, base-10 syntax, and underscores for delineation. Let's take a look at the following valid numeric primitives:
+0xffffff // hexadecimal
+0b10101010 // binary
+10 // base-10
+100_000 // underscore delineated base-10
+0x1111_0000 // underscore delineated binary
+0xfff_aaa // underscore delineated hexadecimal
+The default numeric type is u64. The FuelVM's word size is 64 bits, and the cases where using a smaller numeric type saves space are minimal.
If a 64-bit or 256-bit arithmetic operation produces an overflow or an underflow, +computation gets reverted automatically by FuelVM.
+8/16/32-bit arithmetic operations are emulated using their 64-bit analogues with +additional overflow/underflow checks inserted, which generally results in +somewhat higher gas consumption.
+The same does not happen with 256-bit operations, including b256, which uses specialized operations and are as efficient as possible.
The boolean type (bool) has two potential values: true or false. Boolean values are typically used for conditional logic or validation, for example in if expressions. Booleans can be negated, or flipped, with the unary negation operator !.
For example:
+fn returns_false() -> bool {
+ let boolean_value: bool = true;
+ !boolean_value
+}
+In Sway, string literals are stored as variable length string slices. Which means that they are stored as a pointer to the actual string data and its length.
+ +let my_string: str = "fuel";
+String slices, because they contain pointers have limited usage. They cannot be used as constants, storage fields, or configurable constants, nor as main function arguments or returns.
+For these cases one must use string arrays, as described below.
+In Sway, static-length strings are a primitive type. This means that when you declare a string array, its size is a part of its type. This is necessary for the compiler to know how much memory to give for the storage of that data. The size of the string is denoted with square brackets.
+ +Let's take a look:
+let my_string: str[4] = __to_str_array("fuel");
+Because the string literal "fuel" is four letters, the type is str[4], denoting a static length of 4 characters. Strings default to UTF-8 in Sway.
As above, string literals are typed as string slices. So that is why the need for __to_str_array that convert them to string arrays at compile time.
Conversion during runtime can be done with from_str_array and try_as_str_array. The latter can fail, given that the specified string array must be big enough for the string slice content.
let a: str = "abcd";
+let b: str[4] = a.try_as_str_array().unwrap();
+let c: str = from_str_array(b);
+Compound types are types that group multiple values into one type. In Sway, we have arrays and tuples.
+A tuple is a general-purpose static-length aggregation of types. In more plain terms, a tuple is a single type that consists of an aggregate of zero or more types. The internal types that make up a tuple, and the tuple's arity, define the tuple's type.
+ +Let's take a look at some examples.
+let x: (u64, u64) = (0, 0);
+This is a tuple, denoted by parenthesized, comma-separated values. Note that the type annotation, (u64, u64), is similar in syntax to the expression which instantiates that type, (0, 0).
let x: (u64, bool) = (42, true);
+assert(x.1);
+In this example, we have created a new tuple type, (u64, bool), which is a composite of a u64 and a bool.
To access a value within a tuple, we use tuple indexing: x.1 stands for the first (zero-indexed, so the bool) value of the tuple. Likewise, x.0 would be the zeroth, u64 value of the tuple. Tuple values can also be accessed via destructuring.
struct Foo {}
+let x: (u64, Foo, bool) = (42, Foo {}, true);
+let (number, foo, boolean) = x;
+To create one-arity tuples, we will need to add a trailing comma:
+let x: u64 = (42); // x is of type u64
+let y: (u64) = (42); // y is of type u64
+let z: (u64,) = (42,); // z is of type (u64), i.e. a one-arity tuple
+let w: (u64) = (42,); // type error
+An array is similar to a tuple, but an array's values must all be of the same type. Arrays can hold arbitrary types including non-primitive types.
+ +An array is written as a comma-separated list inside square brackets:
+let x = [1, 2, 3, 4, 5];
+Arrays are allocated on the stack since their size is known. An array's size is always static, i.e. it cannot change. An array of five elements cannot become an array of six elements.
+Arrays can be iterated over, unlike tuples. An array's type is written as the type the array contains followed by the number of elements, semicolon-separated and within square brackets, e.g., [u64; 5]. To access an element in an array, use the array indexing syntax, i.e. square brackets.
Array elements can also be mutated if the underlying array is declared as mutable:
+let mut x = [1, 2, 3, 4, 5];
+x[0] = 0;
+script;
+
+struct Foo {
+ f1: u32,
+ f2: b256,
+}
+
+fn main() {
+ // Array of integers with type ascription
+ let array_of_integers: [u8; 5] = [1, 2, 3, 4, 5];
+
+ // Array of strings
+ let array_of_strings = ["Bob", "Jan", "Ron"];
+
+ // Array of structs
+ let array_of_structs: [Foo; 2] = [
+ Foo {
+ f1: 11,
+ f2: 0x1111111111111111111111111111111111111111111111111111111111111111,
+ },
+ Foo {
+ f1: 22,
+ f2: 0x2222222222222222222222222222222222222222222222222222222222222222,
+ },
+ ];
+
+ // Accessing an element of an array
+ let mut array_of_bools: [bool; 2] = [true, false];
+ assert(array_of_bools[0]);
+
+ // Mutating the element of an array
+ array_of_bools[1] = true;
+ assert(array_of_bools[1]);
+}
+Comments in Sway start with two slashes and continue until the end of the line. For comments that extend beyond a single line, you'll need to include // on each line.
// hello world
+// let's make a couple of lines
+// commented.
+You can also place comments at the ends of lines containing code.
+fn main() {
+ let baz = 8; // Eight is a lucky number
+}
+You can also do block comments
+fn main() {
+ /*
+ You can write on multiple lines
+ like this if you want
+ */
+ let baz = 8;
+}
+The logging library provides a generic log function that can be imported using use std::logging::log and used to log variables of any type. Each call to log appends a receipt to the list of receipts. There are two types of receipts that a log can generate: Log and LogData.
fn log_values(){
+ // Generates a Log receipt
+ log(42);
+
+ // Generates a LogData receipt
+ let string = "sway";
+ log(string);
+}
+Log ReceiptThe Log receipt is generated for non-reference types, namely bool, u8, u16, u32, and u64.
For example, logging an integer variable x that holds the value 42 using log(x) may generate the following receipt:
"Log": {
+ "id": "0000000000000000000000000000000000000000000000000000000000000000",
+ "is": 10352,
+ "pc": 10404,
+ "ra": 42,
+ "rb": 1018205,
+ "rc": 0,
+ "rd": 0
+}
+Note that ra will include the value being logged. The additional registers rc and rd will be zero when using log while rb may include a non-zero value representing a unique ID for the log instance. The unique ID is not meaningful on its own but allows the Rust and the TS SDKs to know the type of the data being logged, by looking up the log ID in the JSON ABI file.
LogData ReceiptLogData is generated for reference types which include all types except for non_reference types; and for non-reference types bigger than 64-bit integers, for example, u256;
For example, logging a b256 variable b that holds the value 0x1111111111111111111111111111111111111111111111111111111111111111 using log(b) may generate the following receipt:
"LogData": {
+ "data": "1111111111111111111111111111111111111111111111111111111111111111",
+ "digest": "02d449a31fbb267c8f352e9968a79e3e5fc95c1bbeaa502fd6454ebde5a4bedc",
+ "id": "0000000000000000000000000000000000000000000000000000000000000000",
+ "is": 10352,
+ "len": 32,
+ "pc": 10444,
+ "ptr": 10468,
+ "ra": 0,
+ "rb": 1018194
+}
+Note that data in the receipt above will include the value being logged as a hexadecimal. Similarly to the Log receipt, additional registers are written: ra will always be zero when using log, while rb will contain a unique ID for the log instance.
++ +Note +The Rust SDK exposes APIs that allow you to retrieve the logged values and display them nicely based on their types as indicated in the JSON ABI file.
+
The Sway Standard Library is the foundation of portable Sway software, a set of minimal shared abstractions for the broader Sway ecosystem. It offers core types, library-defined operations on language primitives, native asset management, blockchain contextual operations, access control, storage management, and support for types from other VMs, among many other things. Reference the standard library docs here.
+Result<T, E>Type Result is the type used for returning and propagating errors. It is an enum with two variants: Ok(T), representing success and containing a value, and Err(E), representing error and containing an error value. The T and E in this definition are type parameters, allowing Result to be generic and to be used with any types.
/// `Result` is a type that represents either success (`Ok`) or failure (`Err`).
+pub enum Result<T, E> {
+ /// Contains the success value.
+ Ok: T,
+ /// Contains the error value.
+ Err: E,
+}
+Functions return Result whenever errors are expected and recoverable.
Take the following example:
+script;
+
+enum MyContractError {
+ DivisionByZero: (),
+}
+
+fn divide(numerator: u64, denominator: u64) -> Result<u64, MyContractError> {
+ if (denominator == 0) {
+ return Err(MyContractError::DivisionByZero);
+ } else {
+ Ok(numerator / denominator)
+ }
+}
+
+fn main() -> Result<u64, str[4]> {
+ let result = divide(20, 2);
+ match result {
+ Ok(value) => Ok(value),
+ Err(MyContractError::DivisionByZero) => Err(__to_str_array("Fail")),
+ }
+}
+Option<T>Type Option represents an optional value: every Option is either Some and contains a value, or None, and does not. Option types are very common in Sway code, as they have a number of uses:
None can be used as an initializer.None is returned on error.The implementation of Option matches on the variant: if it's Ok it returns the inner value, if it's None, it reverts.
/// A type that represents an optional value, either `Some(val)` or `None`.
+pub enum Option<T> {
+ /// No value.
+ None: (),
+ /// Some value of type `T`.
+ Some: T,
+}
+Option is commonly paired with pattern matching to query the presence of a value and take action, allowing developers to choose how to handle the None case.
Below is an example that uses pattern matching to handle invalid divisions by 0 by returning an Option:
script;
+
+fn divide(numerator: u64, denominator: u64) -> Option<u64> {
+ if denominator == 0 {
+ None
+ } else {
+ Some(numerator / denominator)
+ }
+}
+
+fn main() {
+ let result = divide(6, 2);
+ // Pattern match to retrieve the value
+ match result {
+ // The division was valid
+ Some(x) => std::logging::log(x),
+ // The division was invalid
+ None => std::logging::log("Cannot divide by 0"),
+ }
+}
+Constants are similar to variables; however, there are a few differences:
+impl scope.mut keyword cannot be used with constants.const ID: u32 = 0;
+Constant initializer expressions can be quite complex, but they cannot use, for
+instance, assembly instructions, storage access, mutable variables, loops and
+return statements. Although, function calls, primitive types and compound data
+structures are perfectly fine to use:
fn bool_to_num(b: bool) -> u64 {
+ if b {
+ 1
+ } else {
+ 0
+ }
+}
+
+fn arr_wrapper(a: u64, b: u64, c: u64) -> [u64; 3] {
+ [a, b, c]
+}
+
+const ARR2 = arr_wrapper(bool_to_num(1) + 42, 2, 3);
+Associated constants are constants associated with a type and can be declared in an impl block or in a trait definition.
Associated constants declared inside a trait definition may omit their initializers to indicate that each implementation of the trait must specify those initializers.
The identifier is the name of the constant used in the path. The type is the type that the +definition has to implement.
+ +You can define an associated const directly in the interface surface of a trait:
script;
+
+trait ConstantId {
+ const ID: u32 = 0;
+}
+Alternatively, you can also declare it in the trait, and implement it in the interface of the +types implementing the trait.
+script;
+
+trait ConstantId {
+ const ID: u32;
+}
+
+struct Struct {}
+
+impl ConstantId for Struct {
+ const ID: u32 = 1;
+}
+
+fn main() -> u32 {
+ Struct::ID
+}
+impl self ConstantsConstants can also be declared inside non-trait impl blocks.
script;
+
+struct Point {
+ x: u64,
+ y: u64,
+}
+
+impl Point {
+ const ZERO: Point = Point { x: 0, y: 0 };
+}
+
+fn main() -> u64 {
+ Point::ZERO.x
+}
+Configurable constants are special constants that behave like regular constants in the sense that they cannot change during program execution, but they can be configured after the Sway program has been built. The Rust and TS SDKs allow updating the values of these constants by injecting new values for them directly in the bytecode without having to build the program again. These are useful for contract factories and behave somewhat similarly to immutable variables from languages like Solidity.
Configurable constants are declared inside a configurable block and require a type ascription and an initializer as follows:
configurable {
+ U8: u8 = 8u8,
+ BOOL: bool = true,
+ ARRAY: [u32; 3] = [253u32, 254u32, 255u32],
+ STR_4: str[4] = __to_str_array("fuel"),
+ STRUCT: StructWithGeneric<u8> = StructWithGeneric {
+ field_1: 8u8,
+ field_2: 16,
+ },
+ ENUM: EnumWithGeneric<bool> = EnumWithGeneric::VariantOne(true),
+}
+At most one configurable block is allowed in a Sway project. Moreover, configurable blocks are not allowed in libraries.
Configurable constants can be read directly just like regular constants:
+ fn return_configurables() -> (u8, bool, [u32; 3], str[4], StructWithGeneric<u8>) {
+ (U8, BOOL, ARRAY, STR_4, STRUCT)
+ }
+if expressionsSway supports if, else, and else if expressions that allow you to branch your code depending on conditions.
+ +For example:
+fn main() {
+ let number = 6;
+
+ if number % 4 == 0 {
+ // do something
+ } else if number % 3 == 0 {
+ // do something else
+ } else {
+ // do something else
+ }
+}
+if in a let statementLike Rust, ifs are expressions in Sway. What this means is you can use if expressions on the right side of a let statement to assign the outcome to a variable.
let my_data = if some_bool < 10 { foo() } else { bar() };
+Note that all branches of the if expression must return a value of the same type.
match expressionsSway supports advanced pattern matching through exhaustive match expressions. Unlike an if expression, a match expression asserts at compile time that all possible patterns have been matched. If you don't handle all the patterns, you will get compiler error indicating that your match expression is non-exhaustive.
The basic syntax of a match expression is as follows:
let result = match expression {
+ pattern1 => code_to_execute_if_expression_matches_pattern1,
+ pattern2 => code_to_execute_if_expression_matches_pattern2,
+ pattern3 | pattern4 => code_to_execute_if_expression_matches_pattern3_or_pattern4
+ ...
+ _ => code_to_execute_if_expression_matches_no_pattern,
+}
+Some examples of how you can use a match expression:
script;
+
+// helper functions for our example
+fn on_even(num: u64) {
+ // do something with even numbers
+}
+fn on_odd(num: u64) {
+ // do something with odd numbers
+}
+
+fn main(num: u64) -> u64 {
+ // Match as an expression
+ let is_even = match num % 2 {
+ 0 => true,
+ _ => false,
+ };
+
+ // Match as control flow
+ let x = 12;
+ match x {
+ 5 => on_odd(x),
+ _ => on_even(x),
+ };
+
+ // Match an enum
+ enum Weather {
+ Sunny: (),
+ Rainy: (),
+ Cloudy: (),
+ Snowy: (),
+ }
+ let current_weather = Weather::Sunny;
+ let avg_temp = match current_weather {
+ Weather::Sunny => 80,
+ Weather::Rainy => 50,
+ Weather::Cloudy => 60,
+ Weather::Snowy => 20,
+ };
+
+ let is_sunny = match current_weather {
+ Weather::Sunny => true,
+ Weather::Rainy | Weather::Cloudy | Weather::Snowy => false,
+ };
+
+ // match expression used for a return
+ let outside_temp = Weather::Sunny;
+ match outside_temp {
+ Weather::Sunny => 80,
+ Weather::Rainy => 50,
+ Weather::Cloudy => 60,
+ Weather::Snowy => 20,
+ }
+}
+whileThis is what a while loop looks like:
while counter < 10 {
+ counter = counter + 1;
+}
+You need the while keyword, some condition (value < 10 in this case) which will be evaluated each iteration, and a block of code inside the curly braces ({...}) to execute each iteration.
forThis is what a for loop that computes the sum of a vector of numbers looks like:
for element in vector.iter() {
+ sum += element;
+}
+You need the for keyword, some pattern that contains variable names such as element in this case, the ìn keyword followed by an iterator, and a block of code inside the curly braces ({...}) to execute each iteration. vector.iter() in the example above returns an iterator for the vector. In each iteration, the value of element is updated with the next value in the iterator until the end of the vector is reached and the for loop iteration ends.
Modifying the vector during iteration, by e.g. adding or removing elements, is a logical error and results in an undefined behavior:
// The behavior of this `for` loop is undefined because
+// the `vector` gets modified within the loop.
+for element in vector.iter() {
+ if element == 3 {
+ vector.push(6); // Modification of the vector!
+ }
+}
+break and continuebreak and continue keywords are available to use inside the body of a while or for loop. The purpose of the break statement is to break out of a loop early:
fn break_example() -> u64 {
+ let mut counter = 1;
+ let mut sum = 0;
+ let num = 10;
+ while true {
+ if counter > num {
+ break;
+ }
+ sum += counter;
+ counter += 1;
+ }
+ sum // 1 + 2 + .. + 10 = 55
+}
+The purpose of the continue statement is to skip a portion of a loop in an iteration and jump directly into the next iteration:
fn continue_example() -> u64 {
+ let mut counter = 0;
+ let mut sum = 0;
+ let num = 10;
+ while counter < num {
+ counter += 1;
+ if counter % 2 == 0 {
+ continue;
+ }
+ sum += counter;
+ }
+ sum // 1 + 3 + .. + 9 = 25
+}
+You can also use nested while loops if needed:
while condition_1 == true {
+ // do stuff...
+ while condition_2 == true {
+ // do more stuff...
+ }
+}
+Below are some common type conversions in Sway:
+ +Identity let identity_from_b256: Identity = Identity::Address(Address::from(b256_address));
+ let identity_from_address: Identity = Identity::Address(address);
+ let identity_from_contract_id: Identity = Identity::ContractId(contract_id);
+Identity to ContractId or Address match my_identity {
+ Identity::Address(address) => log(address),
+ Identity::ContractId(contract_id) => log(contract_id),
+ };
+ContractId or Address to b256 let b256_from_address: b256 = address.into();
+ let b256_from_contract_id: b256 = contract_id.into();
+b256 to ContractId or Address let address_from_b256: Address = Address::from(b256_address);
+ let contract_id_from_b256: ContractId = ContractId::from(b256_address);
+str to str[] let fuel_str: str = "fuel";
+ let fuel_str_array: str[4] = fuel_str.try_as_str_array().unwrap();
+str[] to str let fuel_str_array: str[4] = __to_str_array("fuel");
+ let fuel_str: str = from_str_array(fuel_str_array);
+u256 let u8_1: u8 = 2u8;
+ let u16_1: u16 = 2u16;
+ let u32_1: u32 = 2u32;
+ let u64_1: u64 = 2u64;
+ let b256_1: b256 = 0x0102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f20;
+
+ let u256_from_u8: u256 = u8_1.as_u256();
+ let u256_from_u16: u256 = u16_1.as_u256();
+ let u256_from_u32: u256 = u32_1.as_u256();
+ let u256_from_u64: u256 = u64_1.as_u256();
+ let u256_from_b256: u256 = b256_1.as_u256();
+u64 let u8_1: u8 = 2u8;
+ let u16_1: u16 = 2u16;
+ let u32_1: u32 = 2u32;
+ let u256_1: u256 = 0x0000000000000000000000000000000000000000000000000000000000000002u256;
+
+ let u64_from_u8: u64 = u8_1.as_u64();
+
+ let u64_from_u16: u64 = u16_1.as_u64();
+
+ let u64_from_u32: u64 = u32_1.as_u64();
+
+ let u64_from_u256: Option<u64> = <u64 as TryFrom<u256>>::try_from(u256_1);
+u32 let u8_1: u8 = 2u8;
+ let u16_1: u16 = 2u16;
+ let u64_1: u64 = 2;
+ let u256_1: u256 = 0x0000000000000000000000000000000000000000000000000000000000000002u256;
+
+ let u32_from_u8: u32 = u8_1.as_u32();
+
+ let u32_from_u16: u32 = u16_1.as_u32();
+
+ let u32_from_u64_1: Option<u32> = u64_1.try_as_u32();
+ let u32_from_u64_2: Option<u32> = <u32 as TryFrom<u64>>::try_from(u64_1);
+
+ let u32_from_u256: Option<u32> = <u32 as TryFrom<u256>>::try_from(u256_1);
+u16 let u8_1: u8 = 2u8;
+ let u32_1: u32 = 2u32;
+ let u64_1: u64 = 2;
+ let u256_1: u256 = 0x0000000000000000000000000000000000000000000000000000000000000002u256;
+
+ let u16_from_u8: u16 = u8_1.as_u16();
+
+ let u16_from_u32_1: Option<u16> = u32_1.try_as_u16();
+ let u16_from_u32_2: Option<u16> = <u16 as TryFrom<u32>>::try_from(u32_1);
+
+ let u16_from_u64_1: Option<u16> = u64_1.try_as_u16();
+ let u16_from_u64_2: Option<u16> = <u16 as TryFrom<u64>>::try_from(u64_1);
+
+ let u16_from_u256: Option<u16> = <u16 as TryFrom<u256>>::try_from(u256_1);
+u8 let u16_1: u16 = 2u16;
+ let u32_1: u32 = 2u32;
+ let u64_1: u64 = 2;
+ let u256_1: u256 = 0x0000000000000000000000000000000000000000000000000000000000000002u256;
+
+ let u8_from_u16_1: Option<u8> = u16_1.try_as_u8();
+ let u8_from_u16_2: Option<u8> = <u8 as TryFrom<u16>>::try_from(u16_1);
+
+ let u8_from_u32_1: Option<u8> = u32_1.try_as_u8();
+ let u8_from_u32_2: Option<u8> = <u8 as TryFrom<u32>>::try_from(u32_1);
+
+ let u8_from_u64_1: Option<u8> = u64_1.try_as_u8();
+ let u8_from_u64_2: Option<u8> = <u8 as TryFrom<u64>>::try_from(u64_1);
+
+ let u8_from_u256: Option<u8> = <u8 as TryFrom<u256>>::try_from(u256_1);
+Bytesuse std::{bytes::Bytes, bytes_conversions::{b256::*, u16::*, u256::*, u32::*, u64::*}};
+ let num = 5;
+ let little_endian_bytes: Bytes = num.to_le_bytes();
+ let big_endian_bytes: Bytes = num.to_be_bytes();
+Bytesuse std::{bytes::Bytes, bytes_conversions::{b256::*, u16::*, u256::*, u32::*, u64::*}};
+ let u16_from_le_bytes: u16 = u16::from_le_bytes(little_endian_bytes);
+ let u16_from_be_bytes: u16 = u16::from_be_bytes(big_endian_bytes);
+
+ let u32_from_le_bytes: u32 = u32::from_le_bytes(little_endian_bytes);
+ let u32_from_be_bytes: u32 = u32::from_be_bytes(big_endian_bytes);
+
+ let u64_from_le_bytes: u64 = u64::from_le_bytes(little_endian_bytes);
+ let u64_from_be_bytes: u64 = u64::from_be_bytes(big_endian_bytes);
+
+ let u256_from_le_bytes = u256::from_le_bytes(little_endian_bytes);
+ let u256_from_be_bytes = u256::from_be_bytes(big_endian_bytes);
+
+ let b256_from_le_bytes = b256::from_le_bytes(little_endian_bytes);
+ let b256_from_be_bytes = b256::from_be_bytes(big_endian_bytes);
+use std::array_conversions::{b256::*, u16::*, u256::*, u32::*, u64::*};
+ let u16_1: u16 = 2u16;
+ let u32_1: u32 = 2u32;
+ let u64_1: u64 = 2u64;
+ let u256_1: u256 = 0x0000000000000000000000000000000000000000000000000000000000000002u256;
+ let b256_1: b256 = 0x000000000000000000000000000000000000000000000000000000000000002A;
+ // little endian
+ let le_byte_array_from_u16: [u8; 2] = u16_1.to_le_bytes();
+ let le_byte_array_from_u32: [u8; 4] = u32_1.to_le_bytes();
+ let le_byte_array_from_u64: [u8; 8] = u64_1.to_le_bytes();
+ let le_byte_array_from_u256: [u8; 32] = u256_1.to_le_bytes();
+ let le_byte_array_from_b256: [u8; 32] = b256_1.to_le_bytes();
+ // big endian
+ let be_byte_array_from_u16: [u8; 2] = u16_1.to_be_bytes();
+ let be_byte_array_from_u32: [u8; 4] = u32_1.to_be_bytes();
+ let be_byte_array_from_u64: [u8; 8] = u64_1.to_be_bytes();
+ let be_byte_array_from_u256: [u8; 32] = u256_1.to_be_bytes();
+ let be_byte_array_from_b256: [u8; 32] = b256_1.to_be_bytes();
+use std::array_conversions::{b256::*, u16::*, u256::*, u32::*, u64::*};
+ let u16_byte_array: [u8; 2] = [2_u8, 1_u8];
+ let u32_byte_array: [u8; 4] = [4_u8, 3_u8, 2_u8, 1_u8];
+ let u64_byte_array: [u8; 8] = [8_u8, 7_u8, 6_u8, 5_u8, 4_u8, 3_u8, 2_u8, 1_u8];
+ let u256_byte_array: [u8; 32] = [
+ 32_u8, 31_u8, 30_u8, 29_u8, 28_u8, 27_u8, 26_u8, 25_u8, 24_u8, 23_u8, 22_u8,
+ 21_u8, 20_u8, 19_u8, 18_u8, 17_u8, 16_u8, 15_u8, 14_u8, 13_u8, 12_u8, 11_u8,
+ 10_u8, 9_u8, 8_u8, 7_u8, 6_u8, 5_u8, 4_u8, 3_u8, 2_u8, 1_u8,
+ ];
+ // little endian
+ let le_u16_from_byte_array: u16 = u16::from_le_bytes(u16_byte_array);
+ let le_u32_from_byte_array: u32 = u32::from_le_bytes(u32_byte_array);
+ let le_u64_from_byte_array: u64 = u64::from_le_bytes(u64_byte_array);
+ let le_u256_from_byte_array: u256 = u256::from_le_bytes(u256_byte_array);
+ let le_b256_from_byte_array: b256 = b256::from_le_bytes(u256_byte_array);
+ // big endian
+ let be_u16_from_byte_array: u16 = u16::from_be_bytes(u16_byte_array);
+ let be_u32_from_byte_array: u32 = u32::from_be_bytes(u32_byte_array);
+ let be_u64_from_byte_array: u64 = u64::from_be_bytes(u64_byte_array);
+ let be_u256_from_byte_array: u256 = u256::from_be_bytes(u256_byte_array);
+ let be_b256_from_byte_array: b256 = b256::from_be_bytes(u256_byte_array);
+Functions in Sway are declared with the fn keyword. Let's take a look:
fn equals(first_param: u64, second_param: u64) -> bool {
+ first_param == second_param
+}
+We have just declared a function named equals which takes two parameters: first_param and second_param. The parameters must both be 64-bit unsigned integers.
This function also returns a bool value, i.e. either true or false. This function returns true if the two given parameters are equal, and false if they are not. If we want to use this function, we can do so like this:
fn main() {
+ equals(5, 5); // evaluates to `true`
+ equals(5, 6); // evaluates to `false`
+}
+We can make a function parameter mutable by adding ref mut before the parameter name. This allows mutating the argument passed into the function when the function is called.
For example:
+fn increment(ref mut num: u32) {
+ let prev = num;
+ num = prev + 1u32;
+}
+This function is allowed to mutate its parameter num because of the mut keyword. In addition, the ref keyword instructs the function to modify the argument passed to it when the function is called, instead of modifying a local copy of it.
let mut num: u32 = 0;
+ increment(num);
+ assert(num == 1u32); // The function `increment()` modifies `num`
+Note that the variable num itself has to be declared as mutable for the above to compile.
++Note +It is not currently allowed to use
+mutwithoutrefor vice versa for a function parameter.
Similarly, ref mut can be used with more complex data types such as:
fn swap_tuple(ref mut pair: (u64, u64)) {
+ let temp = pair.0;
+ pair.0 = pair.1;
+ pair.1 = temp;
+}
+
+fn update_color(ref mut color: Color, new_color: Color) {
+ color = new_color;
+}
+We can then call these functions as shown below:
+ let mut tuple = (42, 24);
+ swap_tuple(tuple);
+ assert(tuple.0 == 24); // The function `swap_tuple()` modifies `tuple.0`
+ assert(tuple.1 == 42); // The function `swap_tuple()` modifies `tuple.1`
+ let mut color = Color::Red;
+ update_color(color, Color::Blue);
+ assert(match color {
+ Color::Blue => true,
+ _ => false,
+ }); // The function `update_color()` modifies the color to Blue
+++ +Note +The only place, in a Sway program, where the
+refkeyword is valid is before a mutable function parameter.
Sway is a programming language designed for the FuelVM. It is a statically typed, compiled language with type inference and traits. Sway aims to make smart contract development safer and more efficient through the use of strong static analysis and compiler feedback.
+Get started with the basics of Sway:
+ + +Methods are similar to functions in that we declare them with the fn keyword and they have parameters and return a value. However, unlike functions, Methods are defined within the context of a struct (or enum), and either refers to that type or mutates it. The first parameter of a method is always self, which represents the instance of the struct (or enum) the method is being called on.
Associated functions are very similar to methods, in that they are also defined in the context of a struct or enum, but they do not actually use any of the data in the struct and as a result do not take self as a parameter. Associated functions could be standalone functions, but they are included in a specific type for organizational or semantic reasons.
+Constructors are associated functions that construct, or in other words instantiate, new instances of a type. Their return type is always the type itself. E.g., public structs that have private fields must provide a public constructor, or otherwise they cannot be instantiated outside of the module in which they are declared.
+To declare methods and associated functions for a struct or enum, use an impl block. Here, impl is short for implementation.
script;
+
+struct Foo {
+ bar: u64,
+ baz: bool,
+}
+
+impl Foo {
+ // this is a _method_, as it takes `self` as a parameter.
+ fn is_baz_true(self) -> bool {
+ self.baz
+ }
+
+ // this is an _associated function_, since it does not take `self` as a parameter.
+ // it is at the same time a _constructor_ because it instantiates and returns
+ // a new instance of `Foo`.
+ fn new_foo(number: u64, boolean: bool) -> Foo {
+ Foo {
+ bar: number,
+ baz: boolean,
+ }
+ }
+}
+
+fn main() {
+ let foo = Foo::new_foo(42, true);
+ assert(foo.is_baz_true());
+}
+To call a method, simply use dot syntax: foo.iz_baz_true().
Similarly to free functions, methods and associated functions may accept ref mut parameters.
For example:
+struct Coordinates {
+ x: u64,
+ y: u64,
+}
+
+impl Coordinates {
+ fn move_right(ref mut self, distance: u64) {
+ self.x += distance;
+ }
+}
+and when called:
+ let mut point = Coordinates { x: 1, y: 1 };
+ point.move_right(5);
+ assert(point.x == 6);
+ assert(point.y == 1);
+Structs in Sway are a named grouping of types. You may also be familiar with structs via another name: product types. Sway does not make any significantly unique usages of structs; they are similar to most other languages which have structs. If you're coming from an object-oriented background, a struct is like the data attributes of an object.
+Those data attributes are called fields and can be either public or private.
+Private struct fields can be accessed only within the module in which their struct is declared. Public fields are accessible everywhere where the struct is accessible. This access control on the field level allows more fine grained encapsulation of data.
+ +To explain these concepts, let's take a look at the following example, in which we have a module called data_structures.
+In that module, we declare a struct named Foo with two fields. The first field is named bar, it is public and it accepts values of type u64. The second field is named baz, it is also public and it accepts bool values.
In a similar way, we define the structs Point, Line, and TupleInStruct. Since all those structs are public, and all their fields are public, they can be instantiated in other modules using the struct instantiation syntax as shown below.
On the other hand, the struct StructWithPrivateFields can be instantiated only within the data_structures module, because it contains private fields. To be able to create instances of such structs outside of the module in which they are declared, the struct must offer constructor associated functions.
// the _data_structures_ module
+library;
+
+// Declare a struct type
+pub struct Foo {
+ pub bar: u64,
+ pub baz: bool,
+}
+
+// Struct types for destructuring
+pub struct Point {
+ pub x: u64,
+ pub y: u64,
+}
+
+pub struct Line {
+ pub p1: Point,
+ pub p2: Point,
+}
+
+pub struct TupleInStruct {
+ pub nested_tuple: (u64, (u32, (bool, str))),
+}
+
+// Struct type instantiable only in the module _data_structures_
+pub struct StructWithPrivateFields {
+ pub public_field: u64,
+ private_field: u64,
+ other_private_field: u64,
+}
+In order to instantiate the struct we use struct instantiation syntax, which is very similar to the declaration syntax except with expressions in place of types.
+There are three ways to instantiate the struct.
+library;
+
+mod data_structures;
+use data_structures::{Foo, Line, Point, TupleInStruct};
+
+fn hardcoded_instantiation() -> Foo {
+ // Instantiate `foo` as `Foo`
+ let mut foo = Foo {
+ bar: 42,
+ baz: false,
+ };
+
+ // Access and write to "baz"
+ foo.baz = true;
+
+ // Return the struct
+ foo
+}
+
+fn variable_instantiation() -> Foo {
+ // Declare variables with the same names as the fields in `Foo`
+ let number = 42;
+ let truthness = false;
+
+ // Instantiate `foo` as `Foo`
+ let mut foo = Foo {
+ bar: number,
+ baz: truthness,
+ };
+
+ // Access and write to "baz"
+ foo.baz = true;
+
+ // Return the struct
+ foo
+}
+
+fn shorthand_instantiation() -> Foo {
+ // Declare variables with the same names as the fields in `Foo`
+ let bar = 42;
+ let baz = false;
+
+ // Instantiate `foo` as `Foo`
+ let mut foo = Foo { bar, baz };
+
+ // Access and write to "baz"
+ foo.baz = true;
+
+ // Return the struct
+ foo
+}
+
+fn struct_destructuring() {
+ let point1 = Point { x: 0, y: 0 };
+ // Destructure the values from the struct into variables
+ let Point { x, y } = point1;
+
+ let point2 = Point { x: 1, y: 1 };
+ // If you do not care about specific struct fields then use ".." at the end of your variable list
+ let Point { x, .. } = point2;
+
+ let line = Line {
+ p1: point1,
+ p2: point2,
+ };
+ // Destructure the values from the nested structs into variables
+ let Line {
+ p1: Point { x: x0, y: y0 },
+ p2: Point { x: x1, y: y1 },
+ } = line;
+ // You may also destructure tuples nested in structs and structs nested in tuples
+ let tuple_in_struct = TupleInStruct {
+ nested_tuple: (42u64, (42u32, (true, "ok"))),
+ };
+ let TupleInStruct {
+ nested_tuple: (a, (b, (c, d))),
+ } = tuple_in_struct;
+
+ let struct_in_tuple = (Point { x: 2, y: 4 }, Point { x: 3, y: 6 });
+ let (Point { x: x0, y: y0 }, Point { x: x1, y: y1 }) = struct_in_tuple;
+}
+++Note +You can mix and match all 3 ways to instantiate the struct at the same time. +Moreover, the order of the fields does not matter when instantiating however we encourage declaring the fields in alphabetical order and instantiating them in the same alphabetical order
+
Furthermore, multiple variables can be extracted from a struct using the destructuring syntax.
+++Note +This information is not vital if you are new to the language, or programming in general
+
Structs have zero memory overhead. What that means is that in memory, each struct field is laid out sequentially. No metadata regarding the struct's name or other properties is preserved at runtime. In other words, structs are compile-time constructs. This is the same in Rust, but different in other languages with runtimes like Java.
+Tuples are a basic static-length type which contain multiple different types within themselves. The type of a tuple is defined by the types of the values within it, and a tuple can contain basic types as well as structs and enums.
+You can access values directly by using the . syntax. Moreover, multiple variables can be extracted from a tuple using the destructuring syntax.
library;
+
+fn tuple() {
+ // You can declare the types yourself
+ let tuple1: (u8, bool, u64) = (100, false, 10000);
+
+ // Or have the types be inferred
+ let mut tuple2 = (5, true, ("Sway", 8));
+
+ // Retrieve values from tuples
+ let number = tuple1.0;
+ let sway = tuple2.2.1;
+
+ // Destructure the values from the tuple into variables
+ let (n1, truthness, n2) = tuple1;
+
+ // If you do not care about specific values then use "_"
+ let (_, truthness, _) = tuple2;
+
+ // Internally mutate the tuple
+ tuple2.1 = false;
+
+ // Or change the values all at once (must keep the same data types)
+ tuple2 = (9, false, ("Fuel", 99));
+}
+Enumerations, or enums, are also known as sum types. An enum is a type that could be one of several variants. To declare an enum, you enumerate all potential variants.
+ +Here, we have defined five potential colors. Each enum variant is just the color name. As there is no extra data associated with each variant, we say that each variant is of type (), or unit.
library;
+
+// Declare the enum
+enum Color {
+ Blue: (),
+ Green: (),
+ Red: (),
+ Silver: (),
+ Grey: (),
+}
+
+fn main() {
+ // To instantiate a variable with the value of an enum the syntax is
+ let blue = Color::Blue;
+ let silver = Color::Silver;
+}
+It is also possible to have an enum variant contain extra data. Take a look at this more substantial example, which combines struct declarations with enum variants:
+library;
+
+struct Item {
+ price: u64,
+ amount: u64,
+ id: u64,
+}
+
+enum MyEnum {
+ Item: Item,
+}
+
+fn main() {
+ let my_enum = MyEnum::Item(Item {
+ price: 5,
+ amount: 2,
+ id: 42,
+ });
+}
+It is possible to define enums of enums:
+library;
+
+pub enum Error {
+ StateError: StateError,
+ UserError: UserError,
+}
+
+pub enum StateError {
+ Void: (),
+ Pending: (),
+ Completed: (),
+}
+
+pub enum UserError {
+ InsufficientPermissions: (),
+ Unauthorized: (),
+}
+The preferred way to use enums is to use the individual (not nested) enums directly because they are easy to follow and the lines are short:
+library;
+
+use ::enum_of_enums::{StateError, UserError};
+
+fn preferred() {
+ let error1 = StateError::Void;
+ let error2 = UserError::Unauthorized;
+}
+If you wish to use the nested form of enums via the Error enum from the example above, then you can instantiate them into variables using the following syntax:
library;
+
+use ::enum_of_enums::{Error, StateError, UserError};
+
+fn avoid() {
+ let error1 = Error::StateError(StateError::Void);
+ let error2 = Error::UserError(UserError::Unauthorized);
+}
+Key points to note:
+Error enum++Note +This information is not vital if you are new to the language, or programming in general.
+
Enums do have some memory overhead. To know which variant is being represented, Sway stores a one-word (8-byte) tag for the enum variant. The space reserved after the tag is equivalent to the size of the largest enum variant. So, to calculate the size of an enum in memory, add 8 bytes to the size of the largest variant. For example, in the case of Color above, where the variants are all (), the size would be 8 bytes since the size of the largest variant is 0 bytes.
Variables in Sway are immutable by default. This means that, by default, once a variable is declared, its value cannot change. This is one of the ways how Sway encourages safe programming, and many modern languages have this same default.
+ +Let's take a look at variables in detail.
+Let's look at a variable declaration:
+let foo = 5;
+Great! We have just declared a variable, foo. What do we know about foo?
5.u64, a 64-bit unsigned integer.u64 is the default numeric type, and represents a 64-bit unsigned integer. See the section Built-in Types for more details.
We can also make a mutable variable. Let's take a look:
+let mut foo = 5;
+foo = 6;
+Now, foo is mutable, and the reassignment to the number 6 is valid. That is, we are allowed to mutate the variable foo to change its value.
When assigning to a mutable variable, the right-hand side of the assignment is evaluated before the left-hand side. In the below example, the mutable variable i will first be increased and the resulting value of 1 will be stored to array[1], thus resulting in array being changed to [0, 1, 0].
let mut array = [0, 0, 0];
+let mut i = 0;
+
+array[i] = {
+ i += 1;
+ i
+};
+A variable declaration can contain a type annotation. A type annotation serves the purpose of declaring the type, in addition to the value, of a variable.
+ +Let's take a look:
+let foo: u32 = 5;
+We have just declared the type of the variable foo as a u32, which is an unsigned 32-bit integer. Let's take a look at a few other type annotations:
let bar: str[4] = __to_str_array("sway");
+let baz: bool = true;
+If the value declared cannot be assigned to the declared type, there will be an error generated by the compiler.
+ + +Smart contracts require the ability to restrict access to and identify certain users or contracts. Unlike account-based blockchains, transactions in UTXO-based blockchains (i.e. Fuel) do not necessarily have a unique transaction sender. Additional logic is needed to handle this difference, and is provided by the standard library.
+ +msg_senderTo deliver an experience akin to the EVM's access control, the std library provides a msg_sender function, which identifies a unique caller based upon the call and/or transaction input data.
contract;
+
+abi MyOwnedContract {
+ fn receive(field_1: u64) -> bool;
+}
+
+const OWNER = Address::from(0x9ae5b658754e096e4d681c548daf46354495a437cc61492599e33fc64dcdc30c);
+
+impl MyOwnedContract for Contract {
+ fn receive(field_1: u64) -> bool {
+ let sender = msg_sender().unwrap();
+ if let Identity::Address(addr) = sender {
+ assert(addr == OWNER);
+ } else {
+ revert(0);
+ }
+
+ true
+ }
+}
+The msg_sender function works as follows:
Ok(Sender) is returned with the ContractId sender variant.Ok(Sender) is returned with the Address sender variant.Err(AuthError) is returned.Many contracts require some form of ownership for access control. The SRC-5 Ownership Standard has been defined to provide an interoperable interface for ownership within contracts.
+To accomplish this, use the Ownership Library to keep track of the owner. This allows setting and revoking ownership using the variants Some(..) and None respectively. This is better, safer, and more readable than using the Identity type directly where revoking ownership has to be done using some magic value such as b256::zero() or otherwise.
#[storage(read)]
+ fn only_owner() {
+ storage.owner.only_owner();
+ // Do stuff here
+ }
+Setting ownership can be done in one of two ways; During compile time or run time.
+storage {
+ owner: Ownership = Ownership::initialized(Identity::Address(Address::zero())),
+}
+ #[storage(write)]
+ fn set_owner(identity: Identity) {
+ storage.owner.set_ownership(identity);
+ }
+ #[storage(write)]
+ fn revoke_ownership() {
+ storage.owner.renounce_ownership();
+ }
+ #[storage(read)]
+ fn owner() -> State {
+ storage.owner.owner()
+ }
+Sway-Libs provides the following libraries to enable further access control.
+Smart contracts can be called by other contracts or scripts. In the FuelVM, this is done primarily with the call instruction.
Sway provides a nice way to manage callable interfaces with its ABI system. The Fuel ABI specification can be found here.
+Here is an example of a contract calling another contract in Sway. A script can call a contract in the same way.
+// ./contract_a.sw
+contract;
+
+abi ContractA {
+ fn receive(field_1: bool, field_2: u64) -> u64;
+}
+
+impl ContractA for Contract {
+ fn receive(field_1: bool, field_2: u64) -> u64 {
+ assert(field_1 == true);
+ assert(field_2 > 0);
+ return_45()
+ }
+}
+
+fn return_45() -> u64 {
+ 45
+}
+// ./contract_b.sw
+contract;
+
+use contract_a::ContractA;
+
+abi ContractB {
+ fn make_call();
+}
+
+const contract_id = 0x79fa8779bed2f36c3581d01c79df8da45eee09fac1fd76a5a656e16326317ef0;
+
+impl ContractB for Contract {
+ fn make_call() {
+ let x = abi(ContractA, contract_id);
+ let return_value = x.receive(true, 3); // will be 45
+ }
+}
+++Note: The ABI is for external calls only therefore you cannot define a method in the ABI and call it in the same contract. If you want to define a function for a contract, but keep it private so that only your contract can call it, you can define it outside of the
+impland call it inside the contract, similar to thereturn_45()function above.
All calls forward a gas stipend, and may additionally forward one native asset with the call.
+Here is an example of how to specify the amount of gas (gas), the asset ID of the native asset (asset_id), and the amount of the native asset (coins) to forward:
script;
+
+abi MyContract {
+ fn foo(field_1: bool, field_2: u64);
+}
+
+fn main() {
+ let x = abi(MyContract, 0x79fa8779bed2f36c3581d01c79df8da45eee09fac1fd76a5a656e16326317ef0);
+ let asset_id = 0x7777_7777_7777_7777_7777_7777_7777_7777_7777_7777_7777_7777_7777_7777_7777_7777;
+ x.foo {
+ gas: 5000, asset_id: asset_id, coins: 5000
+ }
+ (true, 3);
+}
+A common attack vector for smart contracts is re-entrancy. Similar to the EVM, the FuelVM allows for re-entrancy.
+A stateless re-entrancy guard is included in the sway-libs library. The guard will panic (revert) at run time if re-entrancy is detected.
contract;
+
+use reentrancy::reentrancy_guard;
+
+abi MyContract {
+ fn some_method();
+}
+
+impl ContractB for Contract {
+ fn some_method() {
+ reentrancy_guard();
+ // do something
+ }
+}
+Another way of avoiding re-entrancy-related attacks is to follow the so-called +CEI pattern. CEI stands for "Checks, Effects, Interactions", meaning that the +contract code should first perform safety checks, also known as +"pre-conditions", then perform effects, i.e. modify or read the contract storage +and execute external contract calls (interaction) only at the very end of the +function/method.
+Please see this blog post +for more detail on some vulnerabilities in case of storage modification after +interaction and this blog post for +more information on storage reads after interaction.
+The Sway compiler implements a check that the CEI pattern is not violated in the +user contract and issues warnings if that's the case.
+For example, in the following contract the CEI pattern is violated, because an +external contract call is executed before a storage write.
+contract;
+
+mod other_contract;
+
+use other_contract::*;
+use std::hash::*;
+
+abi MyContract {
+ #[storage(read, write)]
+ fn withdraw(external_contract_id: ContractId);
+}
+
+storage {
+ balances: StorageMap<Identity, u64> = StorageMap::<Identity, u64> {},
+}
+
+impl MyContract for Contract {
+ #[storage(read, write)]
+ fn withdraw(external_contract_id: ContractId) {
+ let sender = msg_sender().unwrap();
+ let bal = storage.balances.get(sender).try_read().unwrap_or(0);
+
+ assert(bal > 0);
+
+ // External call
+ let caller = abi(OtherContract, external_contract_id.into());
+ caller.external_call {
+ coins: bal,
+ }();
+
+ // Storage update _after_ external call
+ storage.balances.insert(sender, 0);
+ }
+}
+Here, other_contract is defined as follows:
library;
+
+abi OtherContract {
+ #[payable]
+ fn external_call();
+}
+The CEI pattern analyzer issues a warning as follows, pointing to the +interaction before a storage modification:
+warning
+ --> /path/to/contract/main.sw:28:9
+ |
+26 |
+27 | let caller = abi(OtherContract, external_contract_id.into());
+28 | caller.external_call { coins: bal }();
+ | _________-
+29 | |
+30 | | // Storage update _after_ external call
+31 | | storage.balances.insert(sender, 0);
+ | |__________________________________________- Storage write after external contract interaction in function or method "withdraw". Consider making all storage writes before calling another contract
+32 | }
+33 | }
+ |
+____
+In case there is a storage read after an interaction, the CEI analyzer will issue a similar warning.
+In addition to storage reads and writes after an interaction, the CEI analyzer reports analogous warnings about:
+tr and tro ASM instructions or library functions using them under the hood;bal instruction;__smo intrinsic function or the smo ASM instruction.While the Fuel contract calling paradigm is similar to the EVM's (using an ABI, forwarding gas and data), it differs in two key ways:
+Native assets: FuelVM calls can forward any native asset not just base asset.
+No data serialization: Contract calls in the FuelVM do not need to serialize data to pass it between contracts; instead they simply pass a pointer to the data. This is because the FuelVM has a shared global memory which all call frames can read from.
+When a contract is compiled, a special section called "contract selection" is also generated. This section checks if the contract call method matches any of the available ABI methods. If this fails, one of two possible actions will happen:
+1 - if no fallback function was specified, the contract will revert; +2 - otherwise, the fallback function will be called.
+For all intents and purposes the fallback function is considered a contract method, which means that it has all the limitations that other contract methods have. As the fallback function signature, the function cannot have arguments, but they can return anything.
+If for some reason the fallback function needs to returns different types, the intrinsic __contract_ret can be used.
contract;
+
+abi MyContract {
+ fn some_method();
+}
+
+impl ContractB for Contract {
+ fn some_method() {
+ }
+}
+
+#[fallback]
+fn fallback() {
+}
+You may still access the method selector and arguments to the call in the fallback.
+For instance, let's assume a function fn foobar(bool, u64) {} gets called on a contract that doesn't have it with arguments true and 42.
+It can execute the following fallback:
#[fallback]
+fn fallback() {
+ // the method selector is the first four bytes of sha256("foobar(bool,u64)")
+ // per https://fuellabs.github.io/fuel-specs/master/protocol/abi#function-selector-encoding
+ let method_selector = std::call_frames::first_param::<u64>();
+
+ // the arguments tuple is (true, 42)
+ let arguments = std::call_frames::second_param::<(bool, u64)>();
+}
+The std-lib includes a function called run_external that allows Sway contracts to execute arbitrary external Sway code.
This functionality enables features like upgradeable contracts and +proxies.
+Upgradeable contracts are designed to allow the logic of a smart contract to be updated after deployment.
+Consider this example proxy contract:
+#[namespace(my_storage_namespace)]
+storage {
+ target_contract: Option<ContractId> = None,
+}
+
+impl Proxy for Contract {
+ #[storage(write)]
+ fn set_target_contract(id: ContractId) {
+ storage.target_contract.write(Some(id));
+ }
+
+ #[storage(read)]
+ fn double_input(_value: u64) -> u64 {
+ let target = storage.target_contract.read().unwrap();
+ run_external(target)
+ }
+}
+The contract has two functions:
+set_target_contract updates the target_contract variable in storage with the ContractId of an external contract.double_input reads the target_contract from storage and uses it to run external code. If the target_contract has a function with the same name (double_input), the code in the external double_input function will run.
+In this case, the function will return a u64.Notice in the Proxy example above, the storage block has a namespace attribute. Using this attribute is considered a best practice for all proxy contracts in Sway, because it will prevent storage collisions with the implementation contract, as the implementation contract has access to both storage contexts.
Below is what an implementation contract could look like for this:
+storage {
+ value: u64 = 0,
+ // to stay compatible, this has to stay the same in the next version
+}
+
+impl Implementation for Contract {
+ #[storage(write)]
+ fn double_input(value: u64) -> u64 {
+ let new_value = value * 2;
+ storage.value.write(new_value);
+ new_value
+ }
+}
+This contract has one function called double_input, which calculates the input value times two, updates the value variable in storage, and returns the new value.
There are a couple of major differences between calling a contract directly and using the run_external method.
First, to use run_external, the ABI of the external contract is not required. The proxy contract has no knowledge of the external contract except for its ContractId.
Second, the storage context of the proxy contract is retained for the loaded code.
+This means that in the examples above, the value variable gets updated in the storage for the proxy contract.
For example, if you were to read the value variable by directly calling the implementation contract, you would get a different result than if you read it through the proxy contract.
+The proxy contract loads the code and executes it in its own context.
If the function name doesn't exist in the target contract but a fallback function does, the fallback function will be triggered.
++If there is no fallback function, the transaction will revert.
+
You can access function parameters for fallback functions using the call_frames module in the std-lib.
+For example, to access the _foo input parameter in the proxy function below, you can use the called_args method in the fallback function:
fn does_not_exist_in_the_target(_foo: u64) -> u64 {
+ run_external(TARGET)
+ }
+#[fallback]
+fn fallback() -> u64 {
+ use std::call_frames::*;
+ __log(3);
+ __log(called_method());
+ __log("double_value");
+ __log(called_method() == "double_value");
+ let foo = called_args::<u64>();
+ foo * 3
+}
+In this case, the does_not_exist_in_the_target function will return _foo * 3.
Some limitations of run_external function are:
run_external. You can only use the call stack within the call frame that contains run_external.The Sway standard library provides easy access to a selection of cryptographic hash functions (sha256 and EVM-compatible keccak256), and EVM-compatible secp256k1-based signature recovery operations.
script;
+
+use std::hash::*;
+
+impl Hash for Location {
+ fn hash(self, ref mut state: Hasher) {
+ match self {
+ Location::Earth => {
+ 0_u8.hash(state);
+ }
+ Location::Mars => {
+ 1_u8.hash(state);
+ }
+ }
+ }
+}
+
+impl Hash for Stats {
+ fn hash(self, ref mut state: Hasher) {
+ self.strength.hash(state);
+ self.agility.hash(state);
+ }
+}
+
+impl Hash for Person {
+ fn hash(self, ref mut state: Hasher) {
+ self.name.hash(state);
+ self.age.hash(state);
+ self.alive.hash(state);
+ self.location.hash(state);
+ self.stats.hash(state);
+ self.some_tuple.hash(state);
+ self.some_array.hash(state);
+ self.some_b256.hash(state);
+ }
+}
+
+const VALUE_A = 0x9280359a3b96819889d30614068715d634ad0cf9bba70c0f430a8c201138f79f;
+
+enum Location {
+ Earth: (),
+ Mars: (),
+}
+
+struct Person {
+ name: str,
+ age: u64,
+ alive: bool,
+ location: Location,
+ stats: Stats,
+ some_tuple: (bool, u64),
+ some_array: [u64; 2],
+ some_b256: b256,
+}
+
+struct Stats {
+ strength: u64,
+ agility: u64,
+}
+
+fn main() {
+ let zero = b256::min();
+ // Use the generic sha256 to hash some integers
+ let sha_hashed_u8 = sha256(u8::max());
+ let sha_hashed_u16 = sha256(u16::max());
+ let sha_hashed_u32 = sha256(u32::max());
+ let sha_hashed_u64 = sha256(u64::max());
+
+ // Or hash a b256
+ let sha_hashed_b256 = sha256(VALUE_A);
+
+ // You can hash booleans too
+ let sha_hashed_bool = sha256(true);
+
+ // Strings are not a problem either
+ let sha_hashed_str = sha256("Fastest Modular Execution Layer!");
+
+ // Tuples of any size work too
+ let sha_hashed_tuple = sha256((true, 7));
+
+ // As do arrays
+ let sha_hashed_array = sha256([4, 5, 6]);
+
+ // Enums work too
+ let sha_hashed_enum = sha256(Location::Earth);
+
+ // Complex structs are not a problem
+ let sha_hashed_struct = sha256(Person {
+ name: "John",
+ age: 9000,
+ alive: true,
+ location: Location::Mars,
+ stats: Stats {
+ strength: 10,
+ agility: 9,
+ },
+ some_tuple: (true, 8),
+ some_array: [17, 76],
+ some_b256: zero,
+ });
+
+ log(sha_hashed_u8);
+ log(sha_hashed_u16);
+ log(sha_hashed_u32);
+ log(sha_hashed_u64);
+ log(sha_hashed_b256);
+ log(sha_hashed_bool);
+ log(sha_hashed_str);
+ log(sha_hashed_tuple);
+ log(sha_hashed_array);
+ log(sha_hashed_enum);
+ log(sha_hashed_struct);
+
+ // Use the generic keccak256 to hash some integers
+ let keccak_hashed_u8 = keccak256(u8::max());
+ let keccak_hashed_u16 = keccak256(u16::max());
+ let keccak_hashed_u32 = keccak256(u32::max());
+ let keccak_hashed_u64 = keccak256(u64::max());
+
+ // Or hash a b256
+ let keccak_hashed_b256 = keccak256(VALUE_A);
+
+ // You can hash booleans too
+ let keccak_hashed_bool = keccak256(true);
+
+ // Strings are not a problem either
+ let keccak_hashed_str = keccak256("Fastest Modular Execution Layer!");
+
+ // Tuples of any size work too
+ let keccak_hashed_tuple = keccak256((true, 7));
+
+ // As do arrays
+ let keccak_hashed_array = keccak256([4, 5, 6]);
+
+ // Enums work too
+ let keccak_hashed_enum = keccak256(Location::Earth);
+
+ // Complex structs are not a problem
+ let keccak_hashed_struct = keccak256(Person {
+ name: "John",
+ age: 9000,
+ alive: true,
+ location: Location::Mars,
+ stats: Stats {
+ strength: 10,
+ agility: 9,
+ },
+ some_tuple: (true, 8),
+ some_array: [17, 76],
+ some_b256: zero,
+ });
+
+ log(keccak_hashed_u8);
+ log(keccak_hashed_u16);
+ log(keccak_hashed_u32);
+ log(keccak_hashed_u64);
+ log(keccak_hashed_b256);
+ log(keccak_hashed_bool);
+ log(keccak_hashed_str);
+ log(keccak_hashed_tuple);
+ log(keccak_hashed_array);
+ log(keccak_hashed_enum);
+ log(keccak_hashed_struct);
+}
+Fuel supports 3 asymmetric cryptographic signature schemes; Secp256k1, Secp256r1, and Ed25519.
Given a Signature and a sign Message, you can recover a PublicKey.
// Secp256rk1 Public Key Recovery
+ let secp256k1_signature: Signature = Signature::Secp256k1(Secp256k1::from((
+ 0x61f3caf4c0912cec69ff0b226638d397115c623a7f057914d48a7e4daf1cf6d8,
+ 0x2555de81cd3a40382d3d64eb1c77e463eea5a76d65ec85f283e0b3d568352678,
+ )));
+ let signed_message = Message::from(0xa13f4ab54057ce064d3dd97ac3ff30ed704e73956896c03650fe59b1a561fe15);
+ // A recovered public key pair.
+ let secp256k1_public_key = secp256k1_signature.recover(signed_message);
+ assert(secp256k1_public_key.is_ok());
+ assert(
+ secp256k1_public_key
+ .unwrap() == PublicKey::from((
+ 0x41a55558a3486b6ee3878f55f16879c0798afd772c1506de44aba90d29b6e65c,
+ 0x341ca2e0a3d5827e78d838e35b29bebe2a39ac30b58999e1138c9467bf859965,
+ )),
+ );
+
+ // Secp256r1 Public Key Recovery
+ let secp256r1_signature = Signature::Secp256r1(Secp256r1::from((
+ 0xbd0c9b8792876712afadbff382e1bf31c44437823ed761cc3600d0016de511ac,
+ 0x44ac566bd156b4fc71a4a4cb2655d3da360c695edb27dc3b64d621e122fea23d,
+ )));
+ let signed_message = Message::from(0x1e45523606c96c98ba970ff7cf9511fab8b25e1bcd52ced30b81df1e4a9c4323);
+ // A recovered public key pair.
+ let secp256r1_public_key = secp256r1_signature.recover(signed_message);
+ assert(secp256r1_public_key.is_ok());
+ assert(
+ secp256r1_public_key
+ .unwrap() == PublicKey::from((
+ 0xd6ea577a54ae42411fbc78d686d4abba2150ca83540528e4b868002e346004b2,
+ 0x62660ecce5979493fe5684526e8e00875b948e507a89a47096bc84064a175452,
+ )),
+ );
+Given a Signature and signed Message, you can recover a Fuel Address.
// Secp256k1 Address Recovery
+ let secp256k1_signature = Signature::Secp256k1(Secp256k1::from((
+ 0x61f3caf4c0912cec69ff0b226638d397115c623a7f057914d48a7e4daf1cf6d8,
+ 0x2555de81cd3a40382d3d64eb1c77e463eea5a76d65ec85f283e0b3d568352678,
+ )));
+ let signed_message = Message::from(0xa13f4ab54057ce064d3dd97ac3ff30ed704e73956896c03650fe59b1a561fe15);
+ // A recovered Fuel address.
+ let secp256k1_address = secp256k1_signature.address(signed_message);
+ assert(secp256k1_address.is_ok());
+ assert(
+ secp256k1_address
+ .unwrap() == Address::from(0x02844f00cce0f608fa3f0f7408bec96bfd757891a6fda6e1fa0f510398304881),
+ );
+
+ // Secp256r1 Address Recovery
+ let secp256r1_signature = Signature::Secp256r1(Secp256r1::from((
+ 0xbd0c9b8792876713afa8bf3383eebf31c43437823ed761cc3600d0016de5110c,
+ 0x44ac566bd156b4fc71a4a4cb2655d3dd360c695edb17dc3b64d611e122fea23d,
+ )));
+ let signed_message = Message::from(0xee45573606c96c98ba970ff7cf9511f1b8b25e6bcd52ced30b89df1e4a9c4323);
+ // A recovered Fuel address.
+ let secp256r1_address = secp256r1_signature.address(signed_message);
+ assert(secp256r1_address.is_ok());
+ assert(
+ secp256r1_address
+ .unwrap() == Address::from(0xb4a5fabee8cc852084b71f17107e9c18d682033a58967027af0ab01edf2f9a6a),
+ );
+
+Recovery of EVM addresses is also supported.
+ // Secp256k1 EVM Address Recovery
+ let secp256k1_signature = Signature::Secp256k1(Secp256k1::from((
+ 0xbd0c9b8792876713afa8bff383eebf31c43437823ed761cc3600d0016de5110c,
+ 0x44ac566bd156b4fc71a4a4cb2655d3dd360c695edb17dc3b64d611e122fea23d,
+ )));
+ let signed_message = Message::from(0xee45573606c96c98ba970ff7cf9511f1b8b25e6bcd52ced30b89df1e4a9c4323);
+ // A recovered EVM address.
+ let secp256k1_evm_address = secp256k1_signature.evm_address(signed_message);
+ assert(secp256k1_evm_address.is_ok());
+ assert(
+ secp256k1_evm_address
+ .unwrap() == EvmAddress::from(0x0000000000000000000000000ec44cf95ce5051ef590e6d420f8e722dd160ecb),
+ );
+
+ // Secp256r1 EVM Address Recovery
+ let secp256r1_signature = Signature::Secp256r1(Secp256r1::from((
+ 0x62CDC20C0AB6AA7B91E63DA9917792473F55A6F15006BC99DD4E29420084A3CC,
+ 0xF4D99AF28F9D6BD96BDAAB83BFED99212AC3C7D06810E33FBB14C4F29B635414,
+ )));
+ let signed_message = Message::from(0x290decd9548b62a8d60345a988386fc84ba6bc95484008f6362f93160ef3e563);
+ // A recovered EVM address.
+ let secp256r1_evm_address = secp256r1_signature.evm_address(signed_message);
+ assert(secp256r1_evm_address.is_ok());
+ assert(
+ secp256r1_evm_address
+ .unwrap() == EvmAddress::from(0x000000000000000000000000408eb2d97ef0beda0a33848d9e052066667cb00a),
+ );
+Given a Signature, PublicKey, and Message, you can verify that the message was signed using the public key.
// Secp256k1 Signature Verification
+ let secp256k1_signature = Signature::Secp256k1(Secp256k1::from((
+ 0x61f3caf4c0912cec69ff0b226638d397115c623a7f057914d48a7e4daf1cf6d8,
+ 0x2555de81cd3a40382d3d64eb1c77e463eea5a76d65ec85f283e0b3d568352678,
+ )));
+ let secp256k1_public_key = PublicKey::from((
+ 0x41a55558a3486b6ee3878f55f16879c0798afd772c1506de44aba90d29b6e65c,
+ 0x341ca2e0a3d5827e78d838e35b29bebe2a39ac30b58999e1138c9467bf859965,
+ ));
+ let signed_message = Message::from(0xa13f4ab54057ce064d3dd97ac3ff30ed704e73956896c03650fe59b1a561fe15);
+ // A verified public key
+ let secp256k1_verified = secp256k1_signature.verify(secp256k1_public_key, signed_message);
+ assert(secp256k1_verified.is_ok());
+
+ // Secp256r1 Signature Verification
+ let secp256r1_signature = Signature::Secp256r1(Secp256r1::from((
+ 0xbd0c9b8792876712afadbff382e1bf31c44437823ed761cc3600d0016de511ac,
+ 0x44ac566bd156b4fc71a4a4cb2655d3da360c695edb27dc3b64d621e122fea23d,
+ )));
+ let secp256r1_public_key = PublicKey::from((
+ 0xd6ea577a54ae42411fbc78d686d4abba2150ca83540528e4b868002e346004b2,
+ 0x62660ecce5979493fe5684526e8e00875b948e507a89a47096bc84064a175452,
+ ));
+ let signed_message = Message::from(0x1e45523606c96c98ba970ff7cf9511fab8b25e1bcd52ced30b81df1e4a9c4323);
+ // A verified public key
+ let secp256r1_verified = secp256r1_signature.verify(secp256r1_public_key, signed_message);
+ assert(secp256r1_verified.is_ok());
+
+ // Ed25519 Signature Verification
+ let ed25519_public_key = PublicKey::from(0x314fa58689bbe1da2430517de2d772b384a1c1d2e9cb87e73c6afcf246045b10);
+ let ed25519_signature = Signature::Ed25519(Ed25519::from((
+ 0xf38cef9361894be6c6e0eddec28a663d099d7ddff17c8077a1447d7ecb4e6545,
+ 0xf5084560039486d3462dd65a40c80a74709b2f06d450ffc5dc00345c6b2cdd00,
+ )));
+ let hashed_message = Message::from(sha256(b256::zero()));
+ // A verified public key
+ let ed25519_verified = ed25519_signature.verify(ed25519_public_key, hashed_message);
+ assert(ed25519_verified.is_ok());
+Given a Signature, Address, and Message, you can verify that the message was signed by the address.
// Secp256k1 Address Verification
+ let secp256k1_address = Address::from(0x02844f00cce0f608fa3f0f7408bec96bfd757891a6fda6e1fa0f510398304881);
+ let secp256k1_signature = Secp256k1::from((
+ 0x61f3caf4c0912cec69ff0b226638d397115c623a7f057914d48a7e4daf1cf6d8,
+ 0x2555de81cd3a40382d3d64eb1c77e463eea5a76d65ec85f283e0b3d568352678,
+ ));
+ let signed_message = Message::from(0xa13f4ab54057ce064d3dd97ac3ff30ed704e73956896c03650fe59b1a561fe15);
+ // A verified address
+ let secp256k1_verified = secp256k1_signature.verify_address(secp256k1_address, signed_message);
+ assert(secp256k1_verified.is_ok());
+
+ // Secp256r1 Address Verification
+ let secp256r1_address = Address::from(0xb4a5fabee8cc852084b71f17107e9c18d682033a58967027af0ab01edf2f9a6a);
+ let secp256r1_signature = Signature::Secp256r1(Secp256r1::from((
+ 0xbd0c9b8792876713afa8bf3383eebf31c43437823ed761cc3600d0016de5110c,
+ 0x44ac566bd156b4fc71a4a4cb2655d3dd360c695edb17dc3b64d611e122fea23d,
+ )));
+ let signed_message = Message::from(0xee45573606c96c98ba970ff7cf9511f1b8b25e6bcd52ced30b89df1e4a9c4323);
+ // A verified address
+ let secp256r1_verified = secp256r1_signature.verify_address(secp256r1_address, signed_message);
+ assert(secp256r1_verified.is_ok());
+
+Recovery of EVM addresses verification is also supported.
+ // Secp256k1 Address Verification
+ let secp256k1_evm_address = EvmAddress::from(0x0000000000000000000000000ec44cf95ce5051ef590e6d420f8e722dd160ecb);
+ let secp256k1_signature = Signature::Secp256k1(Secp256k1::from((
+ 0xbd0c9b8792876713afa8bff383eebf31c43437823ed761cc3600d0016de5110c,
+ 0x44ac566bd156b4fc71a4a4cb2655d3dd360c695edb17dc3b64d611e122fea23d,
+ )));
+ let signed_message = Message::from(0xee45573606c96c98ba970ff7cf9511f1b8b25e6bcd52ced30b89df1e4a9c4323);
+ // A recovered EVM address.
+ let secp256k1_verified = secp256k1_signature.verify_evm_address(secp256k1_evm_address, signed_message);
+ assert(secp256k1_verified.is_ok());
+
+ // Secp256r1 Address Verification
+ let secp256r1_evm_address = EvmAddress::from(0x000000000000000000000000408eb2d97ef0beda0a33848d9e052066667cb00a);
+ let secp256r1_signature = Signature::Secp256r1(Secp256r1::from((
+ 0x62CDC20C0AB6AA7B91E63DA9917792473F55A6F15006BC99DD4E29420084A3CC,
+ 0xF4D99AF28F9D6BD96BDAAB83BFED99212AC3C7D06810E33FBB14C4F29B635414,
+ )));
+ let signed_message = Message::from(0x290decd9548b62a8d60345a988386fc84ba6bc95484008f6362f93160ef3e563);
+ // A recovered EVM address.
+ let secp256r1_verified = secp256r1_signature.verify_evm_address(secp256r1_evm_address, signed_message);
+ assert(secp256r1_verified.is_ok());
+Addresses in Sway are similar to EVM addresses. The two major differences are:
+Contracts, on the other hand, are uniquely identified with a contract ID rather than an address. A contract's ID is also 32 bytes long and is calculated here.
+ +Sway is fundamentally a blockchain language. Because of this, it has some features and requirements that you may not have seen in general-purpose programming languages.
+These are also some concepts related to the FuelVM and Fuel ecosystem that you may utilize when writing Sway.
+ + +The FuelVM has built-in support for working with multiple assets.
+On the EVM, Ether is the native asset. As such, sending ETH to an address or contract is an operation built into the EVM, meaning it doesn't rely on the existence of a smart contract to update balances to track ownership as with ERC-20 tokens.
+On the FuelVM, all assets are native and the process for sending any native asset is the same.
+While you would still need a smart contract to handle the minting and burning of assets, the sending and receiving of these assets can be done independently of the asset contract.
+Just like the EVM however, Fuel has a standard that describes a standard API for Native Assets using the Sway Language. The ERC-20 equivalent for the Sway Language is the SRC-20; Native Asset Standard.
+++NOTE It is important to note that Fuel does not have tokens.
+
On the EVM, an ERC-721 token or NFT is a contract that contains multiple tokens which are non-fungible with one another.
+On the FuelVM, the ERC-721 equivalent is a Native Asset where each asset has a supply of one. This is defined in the SRC-20; Native Asset Standard under the Non-Fungible Asset Restrictions.
+In practice, this means all NFTs are treated the same as any other Native Asset on Fuel. When writing Sway code, no additional cases for handling non-fungible and fungible assets are required.
+An advantage Native Assets bring is that there is no need for token approvals; as with Ether on the EVM. With millions of dollars hacked every year due to misused token approvals, the FuelVM eliminates this attack vector.
+An "Asset" is a Native Asset on Fuel and has the associated AssetId type. Assets are distinguishable from one another. A "Coin" represents a singular unit of an Asset. Coins of the same Asset are not distinguishable from one another.
Fuel does not use tokens like other ecosystems such as Ethereum and uses Native Assets with a UTXO design instead.
+AssetId typeThe AssetId type represents any Native Asset on Fuel. An AssetId is used for interacting with an asset on the network.
The AssetId of any Native Asset on Fuel is calculated by taking the SHA256 hash digest of the originating ContractId that minted the asset and a SubId i.e. sha256((contract_id, sub_id)).
AssetIdThere are 3 ways to instantiate a new AssetId:
When a contract will only ever mint a single asset, it is recommended to use the DEFAULT_ASSET_ID sub id. This is referred to as the default asset of a contract.
To get the default asset from an internal contract call, call the default() function:
let asset_id: AssetId = AssetId::default();
+If a contract mints multiple assets or if the asset has been minted by an external contract, the new() function will be needed. The new() function takes the ContractId of the contract which minted the token as well as a SubId.
To create a new AssetId using a ContractId and SubId, call the new() function:
let my_contract_id: ContractId = ContractId::from(0x1000000000000000000000000000000000000000000000000000000000000000);
+ let my_sub_id: SubId = 0x2000000000000000000000000000000000000000000000000000000000000000;
+
+ let asset_id: AssetId = AssetId::new(my_contract_id, my_sub_id);
+In the case where the b256 value of an asset is already known, you may call the from() function with the b256 value.
let asset_id: AssetId = AssetId::from(0x0000000000000000000000000000000000000000000000000000000000000000);
+SubId typeThe SubId is used to differentiate between different assets that are created by the same contract. The SubId is a b256 value.
When creating a single new asset on Fuel, we recommend using the DEFAULT_SUB_ID or SubId::zero().
On the Fuel Network, the base asset is Ether. This is the only asset on the Fuel Network that does not have a SubId.
The Base Asset can be returned anytime by calling the base() function of the AssetId type.
let base_asset: AssetId = AssetId::base();
+To mint a new asset, the std::asset::mint() function must be called internally within a contract. A SubId and amount of coins must be provided. These newly minted coins will be owned by the contract which minted them. To mint another asset from the same contract, replace the DEFAULT_SUB_ID with your desired SubId.
mint(DEFAULT_SUB_ID, mint_amount);
+You may also mint an asset to a specific entity with the std::asset::mint_to() function. Be sure to provide a target Identity that will own the newly minted coins.
mint_to(target_identity, DEFAULT_SUB_ID, mint_amount);
+If you intend to allow external users to mint assets using your contract, the SRC-3; Mint and Burn Standard defines a standard API for minting assets. The Sway-Libs Asset Library also provides an additional library to support implementations of the SRC-3 Standard into your contract.
+To burn an asset, the std::asset::burn() function must be called internally from the contract which minted them. The SubId used to mint the coins and amount must be provided. The burned coins must be owned by the contract. When an asset is burned it doesn't exist anymore.
burn(DEFAULT_SUB_ID, burn_amount);
+If you intend to allow external users to burn assets using your contract, the SRC-3; Mint and Burn Standard defines a standard API for burning assets. The Sway-Libs Asset Library also provides an additional library to support implementations of the SRC-3 Standard into your contract.
+To internally transfer a Native Asset, the std::asset::transfer() function must be called. A target Identity or user must be provided as well as the AssetId of the asset and an amount.
transfer(target, asset_id, coins);
+To query for the Native Asset sent in a transaction, you may call the std::call_frames::msg_asset_id() function.
let amount = msg_asset_id();
+To query for the amount of coins sent in a transaction, you may call the std::context::msg_amount() function.
let amount = msg_amount();
+To internally check a contract's balance, call the std::context::this_balance() function with the corresponding AssetId.
this_balance(asset_id)
+To check the balance of an external contract, call the std::context::balance_of() function with the corresponding AssetId.
balance_of(target_contract, asset_id)
+++NOTE Due to the FuelVM's UTXO design, balances of
+Address's cannot be returned in the Sway Language. This must be done off-chain using the SDK.
By default, a contract may not receive a Native Asset in a contract call. To allow transferring of assets to the contract, add the #[payable] attribute to the function.
#[payable]
+ fn deposit() {
+ assert(msg_amount() > 0);
+ }
+There are a number of standards developed to enable further functionality for Native Assets and help cross contract functionality. Information on standards can be found in the Sway Standards Repo.
+We currently have the following standards for Native Assets:
+Additional Libraries have been developed to allow you to quickly create an deploy dApps that follow the Sway Standards.
+In this fully fleshed out example, we show a native asset contract which mints a single asset. This is the equivalent to the ERC-20 Standard use in Ethereum. Note there are no token approval functions.
+It implements the SRC-20; Native Asset, SRC-3; Mint and Burn, and SRC-5; Ownership standards. It does not use any external libraries.
+// ERC20 equivalent in Sway.
+contract;
+
+use standards::{
+ src3::SRC3,
+ src5::{
+ SRC5,
+ State,
+ AccessError,
+ },
+ src20::{
+ SetDecimalsEvent,
+ SetNameEvent,
+ SetSymbolEvent,
+ SRC20,
+ TotalSupplyEvent,
+ },
+};
+use std::{
+ asset::{
+ burn,
+ mint_to,
+ },
+ call_frames::msg_asset_id,
+ constants::DEFAULT_SUB_ID,
+ context::msg_amount,
+ string::String,
+ contract_id::ContractId
+};
+
+configurable {
+ DECIMALS: u8 = 9u8,
+ NAME: str[7] = __to_str_array("MyAsset"),
+ SYMBOL: str[5] = __to_str_array("MYTKN"),
+}
+
+storage {
+ total_supply: u64 = 0,
+ owner: State = State::Uninitialized,
+}
+
+// Native Asset Standard
+impl SRC20 for Contract {
+ #[storage(read)]
+ fn total_assets() -> u64 {
+ 1
+ }
+
+ #[storage(read)]
+ fn total_supply(asset: AssetId) -> Option<u64> {
+ if asset == AssetId::default() {
+ Some(storage.total_supply.read())
+ } else {
+ None
+ }
+ }
+
+ #[storage(read)]
+ fn name(asset: AssetId) -> Option<String> {
+ if asset == AssetId::default() {
+ Some(String::from_ascii_str(from_str_array(NAME)))
+ } else {
+ None
+ }
+ }
+
+ #[storage(read)]
+ fn symbol(asset: AssetId) -> Option<String> {
+ if asset == AssetId::default() {
+ Some(String::from_ascii_str(from_str_array(SYMBOL)))
+ } else {
+ None
+ }
+ }
+
+ #[storage(read)]
+ fn decimals(asset: AssetId) -> Option<u8> {
+ if asset == AssetId::default() {
+ Some(DECIMALS)
+ } else {
+ None
+ }
+ }
+}
+
+// Ownership Standard
+impl SRC5 for Contract {
+ #[storage(read)]
+ fn owner() -> State {
+ storage.owner.read()
+ }
+}
+
+// Mint and Burn Standard
+impl SRC3 for Contract {
+ #[storage(read, write)]
+ fn mint(recipient: Identity, sub_id: Option<SubId>, amount: u64) {
+ require(sub_id.is_some() && sub_id.unwrap() == DEFAULT_SUB_ID, "incorrect-sub-id");
+ require_access_owner();
+
+ let new_supply = storage.total_supply.read() + amount;
+ storage
+ .total_supply
+ .write(new_supply);
+ mint_to(recipient, DEFAULT_SUB_ID, amount);
+
+ TotalSupplyEvent::new(
+ AssetId::default(),
+ new_supply,
+ msg_sender().unwrap()
+ ).log();
+ }
+
+ #[storage(read, write)]
+ fn burn(sub_id: SubId, amount: u64) {
+ require(sub_id == DEFAULT_SUB_ID, "incorrect-sub-id");
+ require(msg_amount() >= amount, "incorrect-amount-provided");
+ require(
+ msg_asset_id() == AssetId::default(),
+ "incorrect-asset-provided",
+ );
+ require_access_owner();
+
+ let new_supply = storage.total_supply.read() - amount;
+ storage
+ .total_supply
+ .write(new_supply);
+ burn(DEFAULT_SUB_ID, amount);
+
+ TotalSupplyEvent::new(
+ AssetId::default(),
+ new_supply,
+ msg_sender().unwrap()
+ ).log();
+ }
+}
+
+abi SingleAsset {
+ #[storage(read, write)]
+ fn constructor(owner_: Identity);
+}
+
+impl SingleAsset for Contract {
+ #[storage(read, write)]
+ fn constructor(owner_: Identity) {
+ require(storage.owner.read() == State::Uninitialized, "owner-initialized");
+ storage.owner.write(State::Initialized(owner_));
+ }
+}
+
+#[storage(read)]
+fn require_access_owner() {
+ require(
+ storage.owner.read() == State::Initialized(msg_sender().unwrap()),
+ AccessError::NotOwner,
+ );
+}
+
+abi EmitSRC20Events {
+ fn emit_src20_events();
+}
+
+impl EmitSRC20Events for Contract {
+ fn emit_src20_events() {
+ // Metadata that is stored as a configurable should only be emitted once.
+ let asset = AssetId::default();
+ let sender = msg_sender().unwrap();
+ let name = Some(String::from_ascii_str(from_str_array(NAME)));
+ let symbol = Some(String::from_ascii_str(from_str_array(SYMBOL)));
+
+ SetNameEvent::new(asset, name, sender).log();
+ SetSymbolEvent::new(asset, symbol, sender).log();
+ SetDecimalsEvent::new(asset, DECIMALS, sender).log();
+ }
+}
+In this fully fleshed out example, we show a native asset contract which mints multiple assets. This is the equivalent to the ERC-1155 Standard use in Ethereum. Note there are no token approval functions.
+It implements the SRC-20; Native Asset, SRC-3; Mint and Burn, and SRC-5; Ownership standards. It does not use any external libraries.
+// ERC1155 equivalent in Sway.
+contract;
+
+use standards::{
+ src5::{
+ SRC5,
+ State,
+ AccessError
+ },
+ src20::{
+ SetDecimalsEvent,
+ SetNameEvent,
+ SetSymbolEvent,
+ SRC20,
+ TotalSupplyEvent,
+ }
+ src3::SRC3,
+};
+use std::{
+ asset::{
+ burn,
+ mint_to,
+ },
+ call_frames::msg_asset_id,
+ hash::{
+ Hash,
+ },
+ context::this_balance,
+ storage::storage_string::*,
+ string::String,
+ contract_id::ContractId
+};
+
+storage {
+ total_assets: u64 = 0,
+ total_supply: StorageMap<AssetId, u64> = StorageMap {},
+ name: StorageMap<AssetId, StorageString> = StorageMap {},
+ symbol: StorageMap<AssetId, StorageString> = StorageMap {},
+ decimals: StorageMap<AssetId, u8> = StorageMap {},
+ owner: State = State::Uninitialized,
+}
+
+// Native Asset Standard
+impl SRC20 for Contract {
+ #[storage(read)]
+ fn total_assets() -> u64 {
+ storage.total_assets.read()
+ }
+
+ #[storage(read)]
+ fn total_supply(asset: AssetId) -> Option<u64> {
+ storage.total_supply.get(asset).try_read()
+ }
+
+ #[storage(read)]
+ fn name(asset: AssetId) -> Option<String> {
+ storage.name.get(asset).read_slice()
+ }
+
+ #[storage(read)]
+ fn symbol(asset: AssetId) -> Option<String> {
+ storage.symbol.get(asset).read_slice()
+ }
+
+ #[storage(read)]
+ fn decimals(asset: AssetId) -> Option<u8> {
+ storage.decimals.get(asset).try_read()
+ }
+}
+
+// Mint and Burn Standard
+impl SRC3 for Contract {
+ #[storage(read, write)]
+ fn mint(recipient: Identity, sub_id: Option<SubId>, amount: u64) {
+ require(sub_id.is_some(), "Error: SubId is None");
+ require_access_owner();
+
+ let asset_id = AssetId::new(ContractId::this(), sub_id.unwrap());
+ let supply = storage.total_supply.get(asset_id).try_read();
+ if supply.is_none() {
+ storage.total_assets.write(storage.total_assets.try_read().unwrap_or(0) + 1);
+ }
+ let new_supply = supply.unwrap_or(0) + amount;
+ storage.total_supply.insert(asset_id, new_supply);
+ mint_to(recipient, sub_id, amount);
+
+ TotalSupplyEvent::new(
+ asset_id,
+ new_supply,
+ msg_sender().unwrap()
+ ).log();
+ }
+
+ #[storage(read, write)]
+ fn burn(sub_id: SubId, amount: u64) {
+ require_access_owner();
+ let asset_id = AssetId::new(ContractId::this(), sub_id);
+ require(this_balance(asset_id) >= amount, "not-enough-coins");
+
+ let supply = storage.total_supply.get(asset_id).try_read();
+ let new_supply = supply.unwrap_or(0) - amount;
+ storage.total_supply.insert(asset_id, new_supply);
+ burn(sub_id, amount);
+
+ TotalSupplyEvent::new(
+ asset_id,
+ new_supply,
+ msg_sender().unwrap()
+ ).log();
+ }
+}
+
+abi MultiAsset {
+ #[storage(read, write)]
+ fn constructor(owner_: Identity);
+
+ #[storage(read, write)]
+ fn set_name(asset: AssetId, name: Option<String>);
+
+ #[storage(read, write)]
+ fn set_symbol(asset: AssetId, symbol: Option<String>);
+
+ #[storage(read, write)]
+ fn set_decimals(asset: AssetId, decimals: u8);
+}
+
+impl MultiAsset for Contract {
+ #[storage(read, write)]
+ fn constructor(owner_: Identity) {
+ require(storage.owner.read() == State::Uninitialized, "owner-initialized");
+ storage.owner.write(State::Initialized(owner_));
+ }
+
+ #[storage(read, write)]
+ fn set_name(asset: AssetId, name: Option<String>) {
+ require_access_owner();
+ storage.name.insert(asset, StorageString {});
+ storage.name.get(asset).write_slice(name);
+
+ SetNameEvent::new(asset, name, msg_sender().unwrap()).log();
+ }
+
+ #[storage(read, write)]
+ fn set_symbol(asset: AssetId, symbol: Option<String>) {
+ require_access_owner();
+ storage.symbol.insert(asset, StorageString {});
+ storage.symbol.get(asset).write_slice(symbol);
+
+ SetSymbolEvent::new(asset, symbol, msg_sender().unwrap()).log();
+ }
+
+ #[storage(read, write)]
+ fn set_decimals(asset: AssetId, decimals: u8) {
+ require_access_owner();
+ storage.decimals.insert(asset, decimals);
+
+ SetDecimalsEvent::new(asset, decimals, msg_sender().unwrap()).log();
+ }
+}
+
+#[storage(read)]
+fn require_access_owner() {
+ require(
+ storage.owner.read() == State::Initialized(msg_sender().unwrap()),
+ AccessError::NotOwner,
+ );
+}
+A function is pure if it does not access any persistent storage. Conversely, the function is impure if it does access any storage. Naturally, as storage is only available in smart contracts, impure functions cannot be used in predicates, scripts, or libraries. A pure function cannot call an impure function.
+In Sway, functions are pure by default but can be opted into impurity via the storage function attribute. The storage attribute may take read and/or write arguments indicating which type of access the function requires.
The storage attribute without any arguments, #[storage()], indicates a pure function, and has the same effect as not having the attribute at all.
#[storage(read)]
+fn get_amount() -> u64 {
+ ...
+}
+
+#[storage(read, write)]
+fn increment_amount(increment: u64) -> u64 {
+ ...
+}
+
+fn a_pure_function() {
+ ...
+}
+
+#[storage()]
+fn also_a_pure_function() {
+ ...
+}
+++ + +Note: the
+#[storage(write)]attribute also permits a function to read from storage. This is due to the fact that partially writing a storage slot requires first reading the slot.
Impure functions which call other impure functions must have at least the same storage privileges or a superset of those for the function called. For example, to call a function with write access a caller must also have write access, or both read and write access. To call a function with read and write access the caller must also have both privileges.
+ +The storage attribute may also be applied to methods and associated functions, trait and ABI declarations.
A pure function gives you some guarantees: you will not incur excessive storage gas costs, the compiler can apply additional optimizations, and they are generally easy to reason about and audit.
+++ +Note: Purity does not provide an absolute guarantee that a storage access will not happen as a result of calling a pure function. E.g., it is possible for a pure function to call another contract, which can then call a write function in the original contract. The guarantee that the purity gives in this example is, that the original pure function itself does not change the storage, as well as that any function later called, that accesses storage, is clearly marked as impure.
+
A similar concept exists in Solidity. Note that Solidity refers to contract storage as contract state, and in the Sway/Fuel ecosystem, these two terms are largely interchangeable.
+ +When developing a smart contract, you will typically need some sort of persistent storage. In this case, persistent storage, often just called storage in this context, is a place where you can store values that are persisted inside the contract itself. This is in contrast to a regular value in memory, which disappears after the contract exits.
+Put in conventional programming terms, contract storage is like saving data to a hard drive. That data is saved even after the program that saved it exits. That data is persistent. Using memory is like declaring a variable in a program: it exists for the duration of the program and is non-persistent.
+Some basic use cases of storage include declaring an owner address for a contract and saving balances in a wallet.
+ +storage KeywordDeclaring variables in storage requires a storage block that contains a list of all your variables, their types, and their initial values. The initial value can be any expression that can be evaluated to a constant during compilation, as follows:
storage {
+ var1: u64 = 1,
+ var2: b256 = b256::zero(),
+ var3: Address = Address::zero(),
+ var4: Option<u8> = None,
+}
+To write into a storage variable, you need to use the storage keyword as follows:
storage.var1.write(42);
+ storage
+ .var2
+ .write(0x1111111111111111111111111111111111111111111111111111111111111111);
+ storage
+ .var3
+ .write(Address::from(0x1111111111111111111111111111111111111111111111111111111111111111));
+ storage.var4.write(Some(2u8));
+To read a storage variable, you also need to use the storage keyword. You may use read() or try_read(), however we recommend using try_read() for additional safety.
let var1: u64 = storage.var1.read();
+ let var2: b256 = storage.var2.try_read().unwrap_or(b256::zero());
+ let var3: Address = storage.var3.try_read().unwrap_or(Address::zero());
+ let var4: Option<u8> = storage.var4.try_read().unwrap_or(None);
+To store a struct in storage, each variable must be assigned in the storage block. This can be either my assigning the fields individually or using a public constructor that can be evaluated to a constant during compilation.
struct Type1 {
+ x: u64,
+ y: u64,
+}
+
+struct Type2 {
+ w: b256,
+ z: bool,
+}
+
+impl Type2 {
+ // a constructor that evaluates to a constant during compilation
+ fn default() -> Self {
+ Self {
+ w: 0x0000000000000000000000000000000000000000000000000000000000000000,
+ z: true,
+ }
+ }
+}
+
+storage {
+ var1: Type1 = Type1 { x: 0, y: 0 },
+ var2: Type2 = Type2::default(),
+}
+You may write to both fields of a struct and the entire struct as follows:
+ // Store individual fields
+ storage.var1.x.write(42);
+ storage.var1.y.write(77);
+
+ // Store an entire struct
+ let new_struct = Type2 {
+ w: 0x1111111111111111111111111111111111111111111111111111111111111111,
+ z: false,
+ };
+ storage.var2.write(new_struct);
+The same applies to reading structs from storage, where both the individual and struct as a whole may be read as follows:
+ let var1_x: u64 = storage.var1.x.try_read().unwrap_or(0);
+ let var1_y: u64 = storage.var1.y.try_read().unwrap_or(0);
+ let var2: Type2 = storage.var2.try_read().unwrap_or(Type2::default());
+We support the following common storage collections:
+StorageMap<K, V>StorageVec<T>StorageBytesStorageStringPlease note that these types are not initialized during compilation. This means that if you try to access a key from a storage map before the storage has been set, for example, the call will revert.
+Declaring these variables in storage requires a storage block as follows:
storage {
+ storage_map: StorageMap<u64, bool> = StorageMap {},
+ storage_vec: StorageVec<b256> = StorageVec {},
+ storage_string: StorageString = StorageString {},
+ storage_bytes: StorageBytes = StorageBytes {},
+}
+StorageMaps<K, V>Generic storage maps are available in the standard library as StorageMap<K, V> which have to be defined inside a storage block and allow you to call insert() and get() to insert values at specific keys and get those values respectively. Refer to Storage Maps for more information about StorageMap<K, V>.
Warning While the StorageMap<K, V> is currently included in the prelude, to use it the Hash trait must still be imported. This is a known issue and will be resolved.
use std::hash::Hash;
+
+use std::storage::storage_vec::*;
+
+use std::storage::storage_bytes::*;
+
+use std::storage::storage_string::*;
+
+storage {
+ storage_map: StorageMap<u64, bool> = StorageMap {},
+ storage_vec: StorageVec<b256> = StorageVec {},
+ storage_string: StorageString = StorageString {},
+ storage_bytes: StorageBytes = StorageBytes {},
+}
+
+abi StorageExample {
+ #[storage(write)]
+ fn store_map();
+ #[storage(read)]
+ fn get_map();
+ #[storage(write)]
+ fn store_vec();
+ #[storage(read, write)]
+ fn get_vec();
+ #[storage(write)]
+ fn store_string();
+ #[storage(read)]
+ fn get_string();
+ #[storage(write)]
+ fn store_bytes();
+ #[storage(read)]
+ fn get_bytes();
+}
+
+impl StorageExample for Contract {
+ #[storage(write)]
+ fn store_map() {
+ storage.storage_map.insert(12, true);
+ storage.storage_map.insert(59, false);
+
+ // try_insert() will only insert if a value does not already exist for a key.
+ let result = storage.storage_map.try_insert(103, true);
+ assert(result.is_ok());
+ }
+ #[storage(read)]
+ fn get_map() {
+ // Access directly
+ let stored_val1: bool = storage.storage_map.get(12).try_read().unwrap_or(false);
+
+ // First get the storage key and then access the value.
+ let storage_key2: StorageKey<bool> = storage.storage_map.get(59);
+ let stored_val2: bool = storage_key2.try_read().unwrap_or(false);
+
+ // Unsafely access the value.
+ let stored_val3: bool = storage.storage_map.get(103).read();
+ }
+
+ #[storage(write)]
+ fn store_vec() {
+ storage
+ .storage_vec
+ .push(0x1111111111111111111111111111111111111111111111111111111111111111);
+ storage
+ .storage_vec
+ .push(0x0000000000000000000000000000000000000000000000000000000000000001);
+ storage
+ .storage_vec
+ .push(0x0000000000000000000000000000000000000000000000000000000000000002);
+
+ // Set will overwrite the element stored at the given index.
+ storage.storage_vec.set(2, b256::zero());
+ }
+ #[storage(read, write)]
+ fn get_vec() {
+ // Method 1: Access the element directly
+ // Note: get() does not remove the element from the vec.
+ let stored_val1: b256 = storage.storage_vec.get(0).unwrap().try_read().unwrap_or(b256::zero());
+
+ // Method 2: First get the storage key and then access the value.
+ let storage_key2: StorageKey<b256> = storage.storage_vec.get(1).unwrap();
+ let stored_val2: b256 = storage_key2.try_read().unwrap_or(b256::zero());
+
+ // pop() will remove the last element from the vec.
+ let length: u64 = storage.storage_vec.len();
+ let stored_val3: b256 = storage.storage_vec.pop().unwrap();
+ assert(length != storage.storage_vec.len());
+ }
+
+ #[storage(write)]
+ fn store_string() {
+ let my_string = String::from_ascii_str("Fuel is blazingly fast");
+ storage.storage_string.write_slice(my_string);
+ }
+ #[storage(read)]
+ fn get_string() {
+ let stored_string: String = storage.storage_string.read_slice().unwrap();
+ }
+
+ #[storage(write)]
+ fn store_bytes() {
+ // Setup Bytes
+ let mut my_bytes = Bytes::new();
+ my_bytes.push(1u8);
+ my_bytes.push(2u8);
+ my_bytes.push(3u8);
+
+ // Write to storage
+ storage.storage_bytes.write_slice(my_bytes);
+ }
+ #[storage(read)]
+ fn get_bytes() {
+ let stored_bytes: Bytes = storage.storage_bytes.read_slice().unwrap();
+ }
+}
+To write to a storage map, call either the insert() or try_insert() functions as follows:
storage.storage_map.insert(12, true);
+ storage.storage_map.insert(59, false);
+
+ // try_insert() will only insert if a value does not already exist for a key.
+ let result = storage.storage_map.try_insert(103, true);
+ assert(result.is_ok());
+The following demonstrates how to read from a storage map:
+ // Access directly
+ let stored_val1: bool = storage.storage_map.get(12).try_read().unwrap_or(false);
+
+ // First get the storage key and then access the value.
+ let storage_key2: StorageKey<bool> = storage.storage_map.get(59);
+ let stored_val2: bool = storage_key2.try_read().unwrap_or(false);
+
+ // Unsafely access the value.
+ let stored_val3: bool = storage.storage_map.get(103).read();
+StorageVec<T>Generic storage vectors are available in the standard library as StorageVec<T> which have to be defined inside a storage block and allow you to call push() and pop() to push and pop values from a vector respectively. Refer to Storage Vector for more information about StorageVec<T>.
The following demonstrates how to import StorageVec<T>:
use std::storage::storage_vec::*;
+
+use std::storage::storage_bytes::*;
+
+use std::storage::storage_string::*;
+
+storage {
+ storage_map: StorageMap<u64, bool> = StorageMap {},
+ storage_vec: StorageVec<b256> = StorageVec {},
+ storage_string: StorageString = StorageString {},
+ storage_bytes: StorageBytes = StorageBytes {},
+}
+
+abi StorageExample {
+ #[storage(write)]
+ fn store_map();
+ #[storage(read)]
+ fn get_map();
+ #[storage(write)]
+ fn store_vec();
+ #[storage(read, write)]
+ fn get_vec();
+ #[storage(write)]
+ fn store_string();
+ #[storage(read)]
+ fn get_string();
+ #[storage(write)]
+ fn store_bytes();
+ #[storage(read)]
+ fn get_bytes();
+}
+
+impl StorageExample for Contract {
+ #[storage(write)]
+ fn store_map() {
+ storage.storage_map.insert(12, true);
+ storage.storage_map.insert(59, false);
+
+ // try_insert() will only insert if a value does not already exist for a key.
+ let result = storage.storage_map.try_insert(103, true);
+ assert(result.is_ok());
+ }
+ #[storage(read)]
+ fn get_map() {
+ // Access directly
+ let stored_val1: bool = storage.storage_map.get(12).try_read().unwrap_or(false);
+
+ // First get the storage key and then access the value.
+ let storage_key2: StorageKey<bool> = storage.storage_map.get(59);
+ let stored_val2: bool = storage_key2.try_read().unwrap_or(false);
+
+ // Unsafely access the value.
+ let stored_val3: bool = storage.storage_map.get(103).read();
+ }
+
+ #[storage(write)]
+ fn store_vec() {
+ storage
+ .storage_vec
+ .push(0x1111111111111111111111111111111111111111111111111111111111111111);
+ storage
+ .storage_vec
+ .push(0x0000000000000000000000000000000000000000000000000000000000000001);
+ storage
+ .storage_vec
+ .push(0x0000000000000000000000000000000000000000000000000000000000000002);
+
+ // Set will overwrite the element stored at the given index.
+ storage.storage_vec.set(2, b256::zero());
+ }
+ #[storage(read, write)]
+ fn get_vec() {
+ // Method 1: Access the element directly
+ // Note: get() does not remove the element from the vec.
+ let stored_val1: b256 = storage.storage_vec.get(0).unwrap().try_read().unwrap_or(b256::zero());
+
+ // Method 2: First get the storage key and then access the value.
+ let storage_key2: StorageKey<b256> = storage.storage_vec.get(1).unwrap();
+ let stored_val2: b256 = storage_key2.try_read().unwrap_or(b256::zero());
+
+ // pop() will remove the last element from the vec.
+ let length: u64 = storage.storage_vec.len();
+ let stored_val3: b256 = storage.storage_vec.pop().unwrap();
+ assert(length != storage.storage_vec.len());
+ }
+
+ #[storage(write)]
+ fn store_string() {
+ let my_string = String::from_ascii_str("Fuel is blazingly fast");
+ storage.storage_string.write_slice(my_string);
+ }
+ #[storage(read)]
+ fn get_string() {
+ let stored_string: String = storage.storage_string.read_slice().unwrap();
+ }
+
+ #[storage(write)]
+ fn store_bytes() {
+ // Setup Bytes
+ let mut my_bytes = Bytes::new();
+ my_bytes.push(1u8);
+ my_bytes.push(2u8);
+ my_bytes.push(3u8);
+
+ // Write to storage
+ storage.storage_bytes.write_slice(my_bytes);
+ }
+ #[storage(read)]
+ fn get_bytes() {
+ let stored_bytes: Bytes = storage.storage_bytes.read_slice().unwrap();
+ }
+}
+++NOTE: When importing the
+StorageVec<T>, please be sure to use the glob operator:use std::storage::storage_vec::*.
The following demonstrates how to write to a StorageVec<T>:
storage
+ .storage_vec
+ .push(0x1111111111111111111111111111111111111111111111111111111111111111);
+ storage
+ .storage_vec
+ .push(0x0000000000000000000000000000000000000000000000000000000000000001);
+ storage
+ .storage_vec
+ .push(0x0000000000000000000000000000000000000000000000000000000000000002);
+
+ // Set will overwrite the element stored at the given index.
+ storage.storage_vec.set(2, b256::zero());
+The following demonstrates how to read from a StorageVec<T>:
// Method 1: Access the element directly
+ // Note: get() does not remove the element from the vec.
+ let stored_val1: b256 = storage.storage_vec.get(0).unwrap().try_read().unwrap_or(b256::zero());
+
+ // Method 2: First get the storage key and then access the value.
+ let storage_key2: StorageKey<b256> = storage.storage_vec.get(1).unwrap();
+ let stored_val2: b256 = storage_key2.try_read().unwrap_or(b256::zero());
+
+ // pop() will remove the last element from the vec.
+ let length: u64 = storage.storage_vec.len();
+ let stored_val3: b256 = storage.storage_vec.pop().unwrap();
+ assert(length != storage.storage_vec.len());
+StorageBytesStorage of Bytes is available in the standard library as StorageBytes which have to be defined inside a storage block. StorageBytes cannot be manipulated in the same way a StorageVec<T> or StorageMap<K, V> can but stores bytes more efficiently thus reducing gas. Only the entirety of a Bytes may be read/written to storage. This means any changes would require loading the entire Bytes to the heap, making changes, and then storing it once again. If frequent changes are needed, a StorageVec<u8> is recommended.
The following demonstrates how to import StorageBytes:
use std::storage::storage_bytes::*;
+
+use std::storage::storage_string::*;
+
+storage {
+ storage_map: StorageMap<u64, bool> = StorageMap {},
+ storage_vec: StorageVec<b256> = StorageVec {},
+ storage_string: StorageString = StorageString {},
+ storage_bytes: StorageBytes = StorageBytes {},
+}
+
+abi StorageExample {
+ #[storage(write)]
+ fn store_map();
+ #[storage(read)]
+ fn get_map();
+ #[storage(write)]
+ fn store_vec();
+ #[storage(read, write)]
+ fn get_vec();
+ #[storage(write)]
+ fn store_string();
+ #[storage(read)]
+ fn get_string();
+ #[storage(write)]
+ fn store_bytes();
+ #[storage(read)]
+ fn get_bytes();
+}
+
+impl StorageExample for Contract {
+ #[storage(write)]
+ fn store_map() {
+ storage.storage_map.insert(12, true);
+ storage.storage_map.insert(59, false);
+
+ // try_insert() will only insert if a value does not already exist for a key.
+ let result = storage.storage_map.try_insert(103, true);
+ assert(result.is_ok());
+ }
+ #[storage(read)]
+ fn get_map() {
+ // Access directly
+ let stored_val1: bool = storage.storage_map.get(12).try_read().unwrap_or(false);
+
+ // First get the storage key and then access the value.
+ let storage_key2: StorageKey<bool> = storage.storage_map.get(59);
+ let stored_val2: bool = storage_key2.try_read().unwrap_or(false);
+
+ // Unsafely access the value.
+ let stored_val3: bool = storage.storage_map.get(103).read();
+ }
+
+ #[storage(write)]
+ fn store_vec() {
+ storage
+ .storage_vec
+ .push(0x1111111111111111111111111111111111111111111111111111111111111111);
+ storage
+ .storage_vec
+ .push(0x0000000000000000000000000000000000000000000000000000000000000001);
+ storage
+ .storage_vec
+ .push(0x0000000000000000000000000000000000000000000000000000000000000002);
+
+ // Set will overwrite the element stored at the given index.
+ storage.storage_vec.set(2, b256::zero());
+ }
+ #[storage(read, write)]
+ fn get_vec() {
+ // Method 1: Access the element directly
+ // Note: get() does not remove the element from the vec.
+ let stored_val1: b256 = storage.storage_vec.get(0).unwrap().try_read().unwrap_or(b256::zero());
+
+ // Method 2: First get the storage key and then access the value.
+ let storage_key2: StorageKey<b256> = storage.storage_vec.get(1).unwrap();
+ let stored_val2: b256 = storage_key2.try_read().unwrap_or(b256::zero());
+
+ // pop() will remove the last element from the vec.
+ let length: u64 = storage.storage_vec.len();
+ let stored_val3: b256 = storage.storage_vec.pop().unwrap();
+ assert(length != storage.storage_vec.len());
+ }
+
+ #[storage(write)]
+ fn store_string() {
+ let my_string = String::from_ascii_str("Fuel is blazingly fast");
+ storage.storage_string.write_slice(my_string);
+ }
+ #[storage(read)]
+ fn get_string() {
+ let stored_string: String = storage.storage_string.read_slice().unwrap();
+ }
+
+ #[storage(write)]
+ fn store_bytes() {
+ // Setup Bytes
+ let mut my_bytes = Bytes::new();
+ my_bytes.push(1u8);
+ my_bytes.push(2u8);
+ my_bytes.push(3u8);
+
+ // Write to storage
+ storage.storage_bytes.write_slice(my_bytes);
+ }
+ #[storage(read)]
+ fn get_bytes() {
+ let stored_bytes: Bytes = storage.storage_bytes.read_slice().unwrap();
+ }
+}
+++NOTE: When importing the
+StorageBytes, please be sure to use the glob operator:use std::storage::storage_bytes::*.
The following demonstrates how to write to a StorageBytes:
// Setup Bytes
+ let mut my_bytes = Bytes::new();
+ my_bytes.push(1u8);
+ my_bytes.push(2u8);
+ my_bytes.push(3u8);
+
+ // Write to storage
+ storage.storage_bytes.write_slice(my_bytes);
+The following demonstrates how to read from a StorageBytes:
let stored_bytes: Bytes = storage.storage_bytes.read_slice().unwrap();
+StorageStringStorage of String is available in the standard library as StorageString which have to be defined inside a storage block. StorageString cannot be manipulated in the same way a StorageVec<T> or StorageMap<K, V>. Only the entirety of a String may be read/written to storage.
The following demonstrates how to import StorageString:
use std::storage::storage_string::*;
+
+storage {
+ storage_map: StorageMap<u64, bool> = StorageMap {},
+ storage_vec: StorageVec<b256> = StorageVec {},
+ storage_string: StorageString = StorageString {},
+ storage_bytes: StorageBytes = StorageBytes {},
+}
+
+abi StorageExample {
+ #[storage(write)]
+ fn store_map();
+ #[storage(read)]
+ fn get_map();
+ #[storage(write)]
+ fn store_vec();
+ #[storage(read, write)]
+ fn get_vec();
+ #[storage(write)]
+ fn store_string();
+ #[storage(read)]
+ fn get_string();
+ #[storage(write)]
+ fn store_bytes();
+ #[storage(read)]
+ fn get_bytes();
+}
+
+impl StorageExample for Contract {
+ #[storage(write)]
+ fn store_map() {
+ storage.storage_map.insert(12, true);
+ storage.storage_map.insert(59, false);
+
+ // try_insert() will only insert if a value does not already exist for a key.
+ let result = storage.storage_map.try_insert(103, true);
+ assert(result.is_ok());
+ }
+ #[storage(read)]
+ fn get_map() {
+ // Access directly
+ let stored_val1: bool = storage.storage_map.get(12).try_read().unwrap_or(false);
+
+ // First get the storage key and then access the value.
+ let storage_key2: StorageKey<bool> = storage.storage_map.get(59);
+ let stored_val2: bool = storage_key2.try_read().unwrap_or(false);
+
+ // Unsafely access the value.
+ let stored_val3: bool = storage.storage_map.get(103).read();
+ }
+
+ #[storage(write)]
+ fn store_vec() {
+ storage
+ .storage_vec
+ .push(0x1111111111111111111111111111111111111111111111111111111111111111);
+ storage
+ .storage_vec
+ .push(0x0000000000000000000000000000000000000000000000000000000000000001);
+ storage
+ .storage_vec
+ .push(0x0000000000000000000000000000000000000000000000000000000000000002);
+
+ // Set will overwrite the element stored at the given index.
+ storage.storage_vec.set(2, b256::zero());
+ }
+ #[storage(read, write)]
+ fn get_vec() {
+ // Method 1: Access the element directly
+ // Note: get() does not remove the element from the vec.
+ let stored_val1: b256 = storage.storage_vec.get(0).unwrap().try_read().unwrap_or(b256::zero());
+
+ // Method 2: First get the storage key and then access the value.
+ let storage_key2: StorageKey<b256> = storage.storage_vec.get(1).unwrap();
+ let stored_val2: b256 = storage_key2.try_read().unwrap_or(b256::zero());
+
+ // pop() will remove the last element from the vec.
+ let length: u64 = storage.storage_vec.len();
+ let stored_val3: b256 = storage.storage_vec.pop().unwrap();
+ assert(length != storage.storage_vec.len());
+ }
+
+ #[storage(write)]
+ fn store_string() {
+ let my_string = String::from_ascii_str("Fuel is blazingly fast");
+ storage.storage_string.write_slice(my_string);
+ }
+ #[storage(read)]
+ fn get_string() {
+ let stored_string: String = storage.storage_string.read_slice().unwrap();
+ }
+
+ #[storage(write)]
+ fn store_bytes() {
+ // Setup Bytes
+ let mut my_bytes = Bytes::new();
+ my_bytes.push(1u8);
+ my_bytes.push(2u8);
+ my_bytes.push(3u8);
+
+ // Write to storage
+ storage.storage_bytes.write_slice(my_bytes);
+ }
+ #[storage(read)]
+ fn get_bytes() {
+ let stored_bytes: Bytes = storage.storage_bytes.read_slice().unwrap();
+ }
+}
+++NOTE: When importing the
+StorageString, please be sure to use the glob operator:use std::storage::storage_string::*.
The following demonstrates how to write to a StorageString:
let my_string = String::from_ascii_str("Fuel is blazingly fast");
+ storage.storage_string.write_slice(my_string);
+The following demonstrates how to read from a StorageString:
let stored_string: String = storage.storage_string.read_slice().unwrap();
+For more advanced storage techniques please refer to the Advanced Storage page.
+ +Sway’s standard library includes a number of very useful data structures called collections. Most other data types represent one specific value, but collections can contain multiple values. Unlike the built-in array and tuple types which are allocated on the "stack" and cannot grow in size, the data these collections point to is stored either on the "heap" or in contract "storage", which means the amount of data does not need to be known at compile time and can grow as the program runs. Each kind of collection has different capabilities and costs, and choosing an appropriate one for your current situation is a skill you’ll develop over time. In this chapter, we’ll discuss three collections that are used very often in Sway programs:
+A vector on the heap allows you to store a variable number of values next to each other.
+A StorageVec is similar to a vector on the heap but uses persistent storage.
A StorageMap allows you to associate a value with a particular key.
We’ll discuss how to create and update a vector, StorageVec, and StorageMap, as well as what makes each special.
Another important common collection is the storage map.
+ + +The type StorageMap<K, V> from the standard library stores a mapping of keys of type K to values of type V using a hashing function, which determines how it places these keys and values into storage slots. This is similar to Rust's HashMap<K, V> but with a few differences.
Storage maps are useful when you want to look up data not by using an index, as you can with vectors, but by using a key that can be of any type. For example, when building a ledger-based sub-currency smart contract, you could keep track of the balance of each wallet in a storage map in which each key is a wallet’s Address and the values are each wallet’s balance. Given an Address, you can retrieve its balance.
Similarly to StorageVec<T>, StorageMap<K, V> can only be used in a contract because only contracts are allowed to access persistent storage.
StorageMap<T> is included in the standard library prelude which means that there is no need to import it manually.
To create a new empty storage map, we have to declare the map in a storage block as follows:
map: StorageMap<Address, u64> = StorageMap::<Address, u64> {},
+Just like any other storage variable, two things are required when declaring a StorageMap: a type annotation and an initializer. The initializer is just an empty struct of type StorageMap because StorageMap<K, V> itself is an empty struct! Everything that is interesting about StorageMap<K, V> is implemented in its methods.
Storage maps, just like Vec<T> and StorageVec<T>, are implemented using generics which means that the StorageMap<K, V> type provided by the standard library can map keys of any type K to values of any type V. In the example above, we’ve told the Sway compiler that the StorageMap<K, V> in map will map keys of type Address to values of type u64.
To insert key-value pairs into a storage map, we can use the insert method.
For example:
+ #[storage(write)]
+ fn insert_into_storage_map() {
+ let addr1 = Address::from(0x0101010101010101010101010101010101010101010101010101010101010101);
+ let addr2 = Address::from(0x0202020202020202020202020202020202020202020202020202020202020202);
+
+ storage.map.insert(addr1, 42);
+ storage.map.insert(addr2, 77);
+ }
+Note two details here. First, in order to use insert, we need to first access the storage map using the storage keyword. Second, because insert requires writing into storage, a #[storage(write)] annotation is required on the ABI function that calls insert.
++ +Note +The storage annotation is also required for any private function defined in the contract that tries to insert into the map.
+
++Note +There is no need to add the
+mutkeyword when declaring aStorageMap<K, V>. All storage variables are mutable by default.
We can get a value out of the storage map by providing its key to the get method.
For example:
+ #[storage(read, write)]
+ fn get_from_storage_map() {
+ let addr1 = Address::from(0x0101010101010101010101010101010101010101010101010101010101010101);
+ let addr2 = Address::from(0x0202020202020202020202020202020202020202020202020202020202020202);
+
+ storage.map.insert(addr1, 42);
+ storage.map.insert(addr2, 77);
+
+ let value1 = storage.map.get(addr1).try_read().unwrap_or(0);
+ }
+Here, value1 will have the value that's associated with the first address, and the result will be 42. The get method returns an Option<V>; if there’s no value for that key in the storage map, get will return None. This program handles the Option by calling unwrap_or to set value1 to zero if map doesn't have an entry for the key.
Maps with multiple keys can be implemented using tuples as keys. For example:
+ map_two_keys: StorageMap<(b256, bool), b256> = StorageMap::<(b256, bool), b256> {},
+It is possible to nest storage maps as follows:
+ nested_map: StorageMap<u64, StorageMap<u64, u64>> = StorageMap::<u64, StorageMap<u64, u64>> {},
+The nested map can then be accessed as follows:
+ #[storage(read, write)]
+ fn access_nested_map() {
+ storage.nested_map.get(0).insert(1, 42);
+ storage.nested_map.get(2).insert(3, 24);
+
+ assert(storage.nested_map.get(0).get(1).read() == 42);
+ assert(storage.nested_map.get(0).get(0).try_read().is_none()); // Nothing inserted here
+ assert(storage.nested_map.get(2).get(3).read() == 24);
+ assert(storage.nested_map.get(2).get(2).try_read().is_none()); // Nothing inserted here
+ }
+The second collection type we’ll look at is StorageVec<T>. Just like vectors on the heap (i.e. Vec<T>), storage vectors allow you to store more than one value in a single data structure where each value is assigned an index and can only store values of the same type. However, unlike Vec<T>, the elements of a StorageVec are stored in persistent storage, and consecutive elements are not necessarily stored in storage slots that have consecutive keys.
In order to use StorageVec<T>, you must first import StorageVec as follows:
use std::storage::storage_vec::*;
+Another major difference between Vec<T> and StorageVec<T> is that StorageVec<T> can only be used in a contract because only contracts are allowed to access persistent storage.
StorageVecTo create a new empty StorageVec, we have to declare the vector in a storage block as follows:
v: StorageVec<u64> = StorageVec {},
+Just like any other storage variable, two things are required when declaring a StorageVec: a type annotation and an initializer. The initializer is just an empty struct of type StorageVec because StorageVec<T> itself is an empty struct! Everything that is interesting about StorageVec<T> is implemented in its methods.
Storage vectors, just like Vec<T>, are implemented using generics which means that the StorageVec<T> type provided by the standard library can hold any type. When we create a StorageVec to hold a specific type, we can specify the type within angle brackets. In the example above, we’ve told the Sway compiler that the StorageVec<T> in v will hold elements of the u64 type.
StorageVecTo add elements to a StorageVec, we can use the push method, as shown below:
#[storage(read, write)]
+ fn push_to_storage_vec() {
+ storage.v.push(5);
+ storage.v.push(6);
+ storage.v.push(7);
+ storage.v.push(8);
+ }
+Note two details here. First, in order to use push, we need to first access the vector using the storage keyword. Second, because push requires accessing storage, a storage annotation is required on the ABI function that calls push. While it may seem that #[storage(write)] should be enough here, the read annotation is also required because each call to push requires reading (and then updating) the length of the StorageVec which is also stored in persistent storage.
++ +Note +The storage annotation is also required for any private function defined in the contract that tries to push into the vector.
+
++Note +There is no need to add the
+mutkeyword when declaring aStorageVec<T>. All storage variables are mutable by default.
To read a value stored in a vector at a particular index, you can use the get method as shown below:
#[storage(read)]
+ fn read_from_storage_vec() {
+ let third = storage.v.get(2);
+ match third {
+ Some(third) => log(third.read()),
+ None => revert(42),
+ }
+ }
+Note three details here. First, we use the index value of 2 to get the third element because vectors are indexed by number, starting at zero. Second, we get the third element by using the get method with the index passed as an argument, which gives us an Option<StorageKey<T>>. Third, the ABI function calling get only requires the annotation #[storage(read)] as one might expect because get does not write to storage.
When the get method is passed an index that is outside the vector, it returns None without panicking. This is particularly useful if accessing an element beyond the range of the vector may happen occasionally under normal circumstances. Your code will then have logic to handle having either Some(element) or None. For example, the index could be coming as a contract method argument. If the argument passed is too large, the method get will return a None value, and the contract method may then decide to revert when that happens or return a meaningful error that tells the user how many items are in the current vector and give them another chance to pass a valid value.
Iterating over a storage vector is conceptually the same as iterating over a Vec<T>. The only difference is an additional call to read() to actually read the stored value.
#[storage(read)]
+ fn iterate_over_a_storage_vec() {
+ // Iterate over all the elements
+ // in turn using the `while` loop.
+ // **This approach is not recommended.**
+ // For iterating over all the elements
+ // in turn use the `for` loop instead.
+ let mut i = 0;
+ while i < storage.v.len() {
+ log(storage.v.get(i).unwrap().read());
+ i += 1;
+ }
+
+ // The preferred and most performant way
+ // to iterate over all the elements in turn is
+ // to use the `for` loop.
+ for elem in storage.v.iter() {
+ log(elem.read());
+ }
+
+ // Use the `while` loop only when more
+ // control over traversal is needed.
+ // E.g., in the below example we iterate
+ // the vector backwards, accessing only
+ // every second element.
+ let mut i = storage.v.len() - 1;
+ while 0 <= i {
+ log(storage.v.get(i).unwrap().read());
+ i -= 2;
+ }
+ }
+Note that modifying a vector during iteration, by e.g. adding or removing elements, is a logical error and results in an undefined behavior:
+Storage vectors, just like Vec<T>, can only store values that are the same type. Similarly to what we did for Vec<T> in the section Using an Enum to store Multiple Types, we can define an enum whose variants will hold the different value types, and all the enum variants will be considered the same type: that of the enum. This is shown below:
enum TableCell {
+ Int: u64,
+ B256: b256,
+ Boolean: bool,
+}
+Then we can declare a StorageVec in a storage block to hold that enum and so, ultimately, holds different types:
row: StorageVec<TableCell> = StorageVec {},
+We can now push different enum variants to the StorageVec as follows:
#[storage(read, write)]
+ fn push_to_multiple_types_storage_vec() {
+ storage.row.push(TableCell::Int(3));
+ storage
+ .row
+ .push(TableCell::B256(0x0101010101010101010101010101010101010101010101010101010101010101));
+ storage.row.push(TableCell::Boolean(true));
+ }
+Now that we’ve discussed some of the most common ways to use storage vectors, be sure to review the API documentation for all the many useful methods defined on StorageVec<T> by the standard library. For now, these can be found in the source code for StorageVec<T>. For example, in addition to push, a pop method removes and returns the last element, a remove method removes and returns the element at some chosen index within the vector, an insert method inserts an element at some chosen index within the vector, etc.
It is possible to nest storage vectors as follows:
+ nested_vec: StorageVec<StorageVec<u64>> = StorageVec {},
+The nested vector can then be accessed as follows:
+ #[storage(read, write)]
+ fn access_nested_vec() {
+ storage.nested_vec.push(StorageVec {});
+ storage.nested_vec.push(StorageVec {});
+
+ let mut inner_vec0 = storage.nested_vec.get(0).unwrap();
+ let mut inner_vec1 = storage.nested_vec.get(1).unwrap();
+
+ inner_vec0.push(0);
+ inner_vec0.push(1);
+
+ inner_vec1.push(2);
+ inner_vec1.push(3);
+ inner_vec1.push(4);
+
+ assert(inner_vec0.len() == 2);
+ assert(inner_vec0.get(0).unwrap().read() == 0);
+ assert(inner_vec0.get(1).unwrap().read() == 1);
+ assert(inner_vec0.get(2).is_none());
+
+ assert(inner_vec1.len() == 3);
+ assert(inner_vec1.get(0).unwrap().read() == 2);
+ assert(inner_vec1.get(1).unwrap().read() == 3);
+ assert(inner_vec1.get(2).unwrap().read() == 4);
+ assert(inner_vec1.get(3).is_none());
+ }
+The first collection type we’ll look at is Vec<T>, also known as a vector. Vectors allow you to store more than one value in a single data structure that puts all the values next to each other in memory. Vectors can only store values of the same type. They are useful when you have a list of items, such as the lines of text in a file or the prices of items in a shopping cart.
Vec<T> is included in the standard library prelude which means that there is no need to import it manually.
To create a new empty vector, we call the Vec::new function, as shown below:
let v: Vec<u64> = Vec::new();
+Note that we added a type annotation here. Because we aren’t inserting any values into this vector, the Sway compiler doesn’t know what kind of elements we intend to store. Vectors are implemented using generics which means that the Vec<T> type provided by the standard library can hold any type. When we create a vector to hold a specific type, we can specify the type within angle brackets. In the example above, we’ve told the Sway compiler that the Vec<T> in v will hold elements of the u64 type.
To create a vector and then add elements to it, we can use the push method, as shown below:
let mut v = Vec::new();
+
+ v.push(5);
+ v.push(6);
+ v.push(7);
+ v.push(8);
+As with any variable, if we want to be able to change its value, we need to make it mutable using the mut keyword, as discussed in the section Declaring a Variable. The numbers we place inside are all of type u64, and the Sway compiler infers this from the data, so we don’t need the Vec<u64> annotation.
To read a value stored in a vector at a particular index, you can use the get method as shown below:
let third = v.get(2);
+ match third {
+ Some(third) => log(third),
+ None => revert(42),
+ }
+Note two details here. First, we use the index value of 2 to get the third element because vectors are indexed by number, starting at zero. Second, we get the third element by using the get method with the index passed as an argument, which gives us an Option<T>.
When the get method is passed an index that is outside the vector, it returns None without panicking. This is particularly useful if accessing an element beyond the range of the vector may happen occasionally under normal circumstances. Your code will then have logic to handle having either Some(element) or None. For example, the index could be coming as a contract method argument. If the argument passed is too large, the method get will return a None value, and the contract method may then decide to revert when that happens or return a meaningful error that tells the user how many items are in the current vector and give them another chance to pass a valid value.
To access elements of a vector, we can iterate through the valid indices using a while loop and the len method as shown below:
let mut i = 0;
+ while i < v.len() {
+ log(v.get(i).unwrap());
+ i += 1;
+ }
+Note two details here. First, we use the method len which returns the length of the vector. Second, we call the method unwrap to extract the Option returned by get. We know that unwrap will not fail (i.e. will not cause a revert) because each index i passed to get is known to be smaller than the length of the vector.
The idiomatic and convenient way to access each element in a vector in turn, is to use the for loop in the combination with the iter method. The iter method returns an iterator that iterates over all the elements of the vector sequentially.
for elem in v.iter() {
+ log(elem);
+ }
+Note that modifying a vector during iteration, by e.g. adding or removing elements, is a logical error and results in an undefined behavior:
+ for elem in v.iter() {
+ log(elem);
+ if elem == 3 {
+ v.push(6); // Modification causes undefined behavior!
+ }
+ }
+Accessing vector elements via while loop should be used only when more control over traversal is needed. E.g., in the below example we iterate the vector backwards, accessing only every second element.
// Start from the end
+ let mut i = v.len() - 1;
+ while 0 <= i {
+ log(v.get(i).unwrap());
+ // Access every second element
+ i -= 2;
+ }
+Vectors can only store values that are the same type. This can be inconvenient; there are definitely use cases for needing to store a list of items of different types. Fortunately, the variants of an enum are defined under the same enum type, so when we need one type to represent elements of different types, we can define and use an enum!
+For example, say we want to get values from a row in a table in which some of the columns in the row contain integers, some b256 values, and some Booleans. We can define an enum whose variants will hold the different value types, and all the enum variants will be considered the same type: that of the enum. Then we can create a vector to hold that enum and so, ultimately, holds different types. We’ve demonstrated this below:
enum TableCell {
+ Int: u64,
+ B256: b256,
+ Boolean: bool,
+ }
+
+ let mut row = Vec::new();
+ row.push(TableCell::Int(3));
+ row.push(TableCell::B256(0x0101010101010101010101010101010101010101010101010101010101010101));
+ row.push(TableCell::Boolean(true));
+Now that we’ve discussed some of the most common ways to use vectors, be sure to review the API documentation for all the many useful methods defined on Vec<T> by the standard library. For now, these can be found in the source code for Vec<T>. For example, in addition to push, a pop method removes and returns the last element, a remove method removes and returns the element at some chosen index within the vector, an insert method inserts an element at some chosen index within the vector, etc.
The forc debug CLI enables debugging a live transaction on a running Fuel Client node.
First, we need a project to debug, so create a new project using
+forc new --script dbg_example && cd dbg_example
+And then add some content to src/main.sw, for example:
script;
+
+use std::logging::log;
+
+fn factorial(n: u64) -> u64 {
+ let mut result = 1;
+ let mut counter = 0;
+ while counter < n {
+ counter = counter + 1;
+ result = result * counter;
+ }
+ return result;
+}
+
+fn main() {
+ log::<u64>(factorial(5)); // 120
+}
+Now we are ready to build the project.
+forc build
+After this the resulting binary should be located at out/debug/dbg_example.bin. Because we are interested in the resulting bytecode, we can read that with:
forc parse-bytecode out/debug/dbg_example.bin
+We can recognize the main loop by observing the control flow. Looking around halfword 58-60, we can see:
+ half-word byte op raw
+ 58 232 MOVI { dst: 0x11, val: 5 } 72 44 00 05
+ 59 236 LT { dst: 0x10, lhs: 0x10, rhs: 0x11 } 16 41 04 40
+ 60 240 JNZF { cond_nz: 0x10, dynamic: 0x0, fixed: 81 } 76 40 00 51
+Here we can see our factorial(5) being set up with MOVI setting the value 5, followed by the LT comparison and conditional jump JNZF. The multiplication for our factorial happens at halfword 147 with MUL { dst: 0x10, lhs: 0x10, rhs: 0x11 }. Finally, we can spot our log statement at halfword 139 with the LOGD instruction.
We can start up the debug infrastructure. On a new terminal session run fuel-core run --db-type in-memory --debug; we need to have that running because it actually executes the program. Now we can fire up the debugger itself: forc-debug. Now if everything is set up correctly, you should see the debugger prompt (>>). You can use help command to list available commands.
The debugger supports tab completion to help you discover files in your current working directory (and its subdirectories):
+tx and press tab to recursively search for valid transaction JSON filesNow we would like to inspect the program while it's running. To do this, we first need to send the script to the executor, i.e. fuel-core. To do so, we need a transaction specification, tx.json. It looks something like this:
{
+ "Script": {
+ "body": {
+ "script_gas_limit": 1000000,
+ "script": [
+ 26, 240, 48, 0, 116, 0, 0, 2, 0, 0, 0, 0, 0, 0, 3, 96, 93, 255, 192, 1, 16, 255, 255, 0, 26, 236, 80, 0, 145, 0, 0, 184, 80, 67, 176, 80, 32, 248, 51, 0, 88, 251, 224, 2, 80, 251, 224, 4, 116, 0, 0, 37, 80, 71, 176, 40, 26, 233, 16, 0, 32, 248, 51, 0, 88, 251, 224, 2, 80, 251, 224, 4, 116, 0, 0, 136, 26, 71, 208, 0, 114, 72, 0, 24, 40, 237, 20, 128, 80, 79, 176, 120, 114, 68, 0, 24, 40, 79, 180, 64, 80, 71, 176, 160, 114, 72, 0, 24, 40, 69, 52, 128, 80, 71, 176, 96, 114, 72, 0, 24, 40, 69, 52, 128, 80, 75, 176, 64, 26, 233, 16, 0, 26, 229, 32, 0, 32, 248, 51, 0, 88, 251, 224, 2, 80, 251, 224, 4, 116, 0, 0, 144, 26, 71, 208, 0, 80, 75, 176, 24, 114, 76, 0, 16, 40, 73, 20, 192, 80, 71, 176, 144, 114, 76, 0, 16, 40, 69, 36, 192, 114, 72, 0, 16, 40, 65, 20, 128, 93, 69, 0, 1, 93, 65, 0, 0, 37, 65, 16, 0, 149, 0, 0, 63, 150, 8, 0, 0, 26, 236, 80, 0, 145, 0, 1, 88, 26, 87, 224, 0, 95, 236, 16, 42, 95, 236, 0, 41, 93, 67, 176, 41, 114, 68, 0, 5, 22, 65, 4, 64, 118, 64, 0, 81, 93, 67, 176, 42, 80, 71, 176, 200, 26, 233, 16, 0, 32, 248, 51, 0, 88, 251, 224, 2, 80, 251, 224, 4, 116, 0, 0, 87, 26, 71, 208, 0, 114, 72, 0, 24, 40, 237, 20, 128, 80, 71, 176, 160, 114, 72, 0, 24, 40, 71, 180, 128, 80, 75, 176, 24, 114, 76, 0, 24, 40, 73, 20, 192, 80, 71, 176, 88, 114, 76, 0, 24, 40, 69, 36, 192, 93, 83, 176, 11, 93, 79, 176, 12, 93, 71, 176, 13, 114, 72, 0, 8, 16, 73, 20, 128, 21, 73, 36, 192, 118, 72, 0, 1, 116, 0, 0, 7, 114, 72, 0, 2, 27, 73, 52, 128, 114, 76, 0, 8, 16, 77, 36, 192, 38, 76, 0, 0, 40, 29, 68, 64, 26, 80, 112, 0, 16, 73, 68, 64, 95, 73, 0, 0, 114, 64, 0, 8, 16, 65, 20, 0, 80, 71, 176, 112, 95, 237, 64, 14, 95, 237, 48, 15, 95, 237, 0, 16, 80, 67, 176, 48, 114, 72, 0, 24, 40, 65, 20, 128, 80, 71, 176, 136, 114, 72, 0, 24, 40, 69, 4, 128, 80, 67, 177, 8, 114, 72, 0, 24, 40, 65, 20, 128, 80, 71, 177, 48, 114, 72, 0, 24, 40, 69, 4, 128, 80, 67, 177, 48, 80, 71, 176, 240, 114, 72, 0, 24, 40, 69, 4, 128, 80, 67, 176, 224, 26, 233, 16, 0, 26, 229, 0, 0, 32, 248, 51, 0, 88, 251, 224, 2, 80, 251, 224, 4, 116, 0, 0, 56, 26, 67, 208, 0, 80, 71, 176, 72, 114, 72, 0, 16, 40, 69, 4, 128, 80, 67, 177, 32, 114, 72, 0, 16, 40, 65, 20, 128, 80, 71, 176, 184, 114, 72, 0, 16, 40, 69, 4, 128, 93, 67, 240, 0, 93, 71, 176, 23, 93, 75, 176, 24, 52, 1, 4, 82, 26, 244, 0, 0, 116, 0, 0, 8, 93, 67, 176, 41, 16, 65, 0, 64, 95, 237, 0, 41, 93, 67, 176, 42, 93, 71, 176, 41, 27, 65, 4, 64, 95, 237, 0, 42, 117, 0, 0, 91, 146, 0, 1, 88, 26, 249, 80, 0, 152, 8, 0, 0, 151, 0, 0, 63, 74, 248, 0, 0, 149, 0, 0, 15, 150, 8, 0, 0, 26, 236, 80, 0, 145, 0, 0, 72, 26, 67, 160, 0, 26, 71, 224, 0, 114, 72, 4, 0, 38, 72, 0, 0, 26, 72, 112, 0, 80, 79, 176, 24, 95, 237, 32, 3, 114, 72, 4, 0, 95, 237, 32, 4, 95, 236, 0, 5, 114, 72, 0, 24, 40, 237, 52, 128, 80, 75, 176, 48, 114, 76, 0, 24, 40, 75, 180, 192, 114, 76, 0, 24, 40, 65, 36, 192, 26, 245, 0, 0, 146, 0, 0, 72, 26, 249, 16, 0, 152, 8, 0, 0, 151, 0, 0, 15, 74, 248, 0, 0, 149, 0, 0, 63, 150, 8, 0, 0, 26, 236, 80, 0, 145, 0, 0, 104, 26, 67, 160, 0, 26, 71, 144, 0, 26, 75, 224, 0, 80, 79, 176, 80, 114, 80, 0, 24, 40, 77, 5, 0, 114, 64, 0, 24, 40, 237, 52, 0, 80, 67, 176, 40, 114, 76, 0, 24, 40, 67, 180, 192, 93, 79, 176, 5, 80, 65, 0, 16, 80, 83, 176, 64, 95, 237, 48, 8, 80, 77, 64, 8, 114, 84, 0, 8, 40, 77, 5, 64, 80, 67, 176, 24, 114, 76, 0, 16, 40, 65, 68, 192, 114, 76, 0, 16, 40, 69, 4, 192, 26, 245, 16, 0, 146, 0, 0, 104, 26, 249, 32, 0, 152, 8, 0, 0, 151, 0, 0, 63, 74, 248, 0, 0, 71, 0, 0, 0, 21, 6, 230, 244, 76, 29, 98, 145
+ ],
+ "script_data": [],
+ "receipts_root": "0000000000000000000000000000000000000000000000000000000000000000"
+ },
+ "policies": {
+ "bits": "MaxFee",
+ "values": [0, 0, 0, 0]
+ },
+ "inputs": [
+ {
+ "CoinSigned": {
+ "utxo_id": {
+ "tx_id": "c49d65de61cf04588a764b557d25cc6c6b4bc0d7429227e2a21e61c213b3a3e2",
+ "output_index": 18
+ },
+ "owner": "f1e92c42b90934aa6372e30bc568a326f6e66a1a0288595e6e3fbd392a4f3e6e",
+ "amount": 10599410012256088000,
+ "asset_id": "2cafad611543e0265d89f1c2b60d9ebf5d56ad7e23d9827d6b522fd4d6e44bc3",
+ "tx_pointer": {
+ "block_height": 0,
+ "tx_index": 0
+ },
+ "witness_index": 0,
+ "maturity": 0,
+ "predicate_gas_used": null,
+ "predicate": null,
+ "predicate_data": null
+ }
+ }
+ ],
+ "outputs": [],
+ "witnesses": [
+ {
+ "data": [156, 254, 34, 102, 65, 96, 133, 170, 254, 105, 147, 35, 196, 199, 179, 133, 132, 240, 208, 149, 11, 46, 30, 96, 44, 91, 121, 195, 145, 184, 159, 235, 117, 82, 135, 41, 84, 154, 102, 61, 61, 16, 99, 123, 58, 173, 75, 226, 219, 139, 62, 33, 41, 176, 16, 18, 132, 178, 8, 125, 130, 169, 32, 108]
+ }
+ ]
+ }
+}
+However, the key script should contain the actual bytecode to execute, i.e. the contents of out/debug/dbg_example.bin as a JSON array. The following command can be used to generate it:
python3 -c 'print(list(open("out/debug/dbg_example.bin", "rb").read()))'
+So now we replace the script array with the result, and save it as tx.json.
Now we can actually execute the script with an ABI to decode the log values:
+>> start_tx tx.json out/debug/dbg_example-abi.json
+
+Receipt: LogData { id: 0000000000000000000000000000000000000000000000000000000000000000, ra: 0, rb: 1515152261580153489, ptr: 67107840, len: 8, digest: d2b80ebb9ce633ad49a9ccfcc58ac7ad33a9ab4741529ae4247a3b07e8fa1c74, pc: 10924, is: 10368, data: Some(0000000000000078) }
+Decoded log value: 120, from contract: 0000000000000000000000000000000000000000000000000000000000000000
+Receipt: ReturnData { id: 0000000000000000000000000000000000000000000000000000000000000000, ptr: 67106816, len: 0, digest: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855, pc: 10564, is: 10368, data: Some() }
+Receipt: ScriptResult { result: Success, gas_used: 1273 }
+Terminated
+Looking at the output, we can see our factorial(5) result as the decoded log value of 120. The ABI has helped us decode the raw bytes (0000000000000078) into a meaningful value. It also tells us that the execution terminated without hitting any breakpoints. That's unsurprising, because we haven't set up any. We can do so with breakpoint command:
>> breakpoint 0
+
+>> start_tx tx.json out/debug/dbg_example-abi.json
+
+Receipt: ScriptResult { result: Success, gas_used: 0 }
+Stopped on breakpoint at address 0 of contract 0x0000000000000000000000000000000000000000000000000000000000000000
+Now we have stopped execution at the breakpoint on entry (address 0). We can now inspect the initial state of the VM.
>> register ggas
+
+reg[0x9] = 1000000 # ggas
+
+>> memory 0x10 0x8
+
+ 000010: db f3 63 c9 1c 7f ec 95
+However, that's not too interesting either, so let's just execute until the end, and then reset the VM to remove the breakpoints.
+>> continue
+
+Receipt: LogData { id: 0000000000000000000000000000000000000000000000000000000000000000, ra: 0, rb: 1515152261580153489, ptr: 67107840, len: 8, digest: d2b80ebb9ce633ad49a9ccfcc58ac7ad33a9ab4741529ae4247a3b07e8fa1c74, pc: 10924, is: 10368, data: Some(0000000000000078) }
+Decoded log value: 120, from contract: 0000000000000000000000000000000000000000000000000000000000000000
+Receipt: ReturnData { id: 0000000000000000000000000000000000000000000000000000000000000000, ptr: 67106816, len: 0, digest: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855, pc: 10564, is: 10368, data: Some() }
+Terminated
+
+>> reset
+Next, we will setup a breakpoint to check the state on each iteration of the while loop. For instance, if we'd like to see what numbers get multiplied together, we could set up a breakpoint before the operation. Looking at our bytecode we can see the main multiplication for our factorial happens at:
half-word byte op raw
+ 147 588 MUL { dst: 0x10, lhs: 0x10, rhs: 0x11 } 1b 41 04 40
+We can set a breakpoint on its address, at halfword-offset 147.
>>> breakpoint 147
+
+>> start_tx tx.json out/debug/dbg_example-abi.json
+
+Receipt: ScriptResult { result: Success, gas_used: 82 }
+Stopped on breakpoint at address 588 of contract 0x0000000000000000000000000000000000000000000000000000000000000000
+Now we can inspect the inputs to multiply. Looking at the specification tells us that the instruction MUL { dst: 0x10, lhs: 0x10, rhs: 0x11 } means reg[0x10] = reg[0x10] * reg[0x11]. So inspecting the inputs:
>> r 0x10 0x11
+reg[0x10] = 1 # reg16
+reg[0x11] = 1 # reg17
+So on the first round the numbers are 1 and 1, so we can continue to the next iteration with the c command:
>> c
+Stopped on breakpoint at address 588 of contract 0x0000000000000000000000000000000000000000000000000000000000000000
+
+>> r 0x10 0x11
+reg[0x10] = 1 # reg16
+reg[0x11] = 2 # reg17
+And the next one:
+>> c
+Stopped on breakpoint at address 588 of contract 0x0000000000000000000000000000000000000000000000000000000000000000
+
+>> r 0x10 0x11
+reg[0x10] = 2 # reg16
+reg[0x11] = 3 # reg17
+And fourth one:
+>> c
+Stopped on breakpoint at address 588 of contract 0x0000000000000000000000000000000000000000000000000000000000000000
+
+>> r 0x10 0x11
+reg[0x10] = 6 # reg16
+reg[0x11] = 4 # reg17
+And round 5:
+>> c
+Stopped on breakpoint at address 588 of contract 0x0000000000000000000000000000000000000000000000000000000000000000
+
+>> r 0x10 0x11
+reg[0x10] = 24 # reg16
+reg[0x11] = 5 # reg17
+At this point we can look at the values
+| 0x10 | 0x11 |
|---|---|
| 1 | 1 |
| 1 | 2 |
| 2 | 3 |
| 6 | 4 |
| 24 | 5 |
From this we can clearly see that the left side, register 0x10 is the result variable which accumulates the factorial calculation (1, 1, 2, 6, 24), and register 0x11 is the counter which increments from 1 to 5. Now the counter equals the given factorial function argument 5, and the loop terminates. So when we continue, the program finishes without encountering any more breakpoints:
>> c
+
+Receipt: LogData { id: 0000000000000000000000000000000000000000000000000000000000000000, ra: 0, rb: 1515152261580153489, ptr: 67107840, len: 8, digest: d2b80ebb9ce633ad49a9ccfcc58ac7ad33a9ab4741529ae4247a3b07e8fa1c74, pc: 10924, is: 10368, data: Some(0000000000000078) }
+Decoded log value: 120, from contract: 0000000000000000000000000000000000000000000000000000000000000000
+Receipt: ReturnData { id: 0000000000000000000000000000000000000000000000000000000000000000, ptr: 67106816, len: 0, digest: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855, pc: 10564, is: 10368, data: Some() }
+Terminated
+The forc debug plugin also enables line-by-line debugging of Sway unit tests in VSCode.
which forc-debug.
+It can be installed with fuelup component add forc-debug..vscode/launch.json file with the following contents:{
+ "version": "0.2.0",
+ "configurations": [
+ {
+ "type": "sway",
+ "request": "launch",
+ "name": "Debug Sway",
+ "program": "${file}"
+ }]
+}
+Given this example contract:
+contract;
+
+abi CallerContract {
+ fn test_false() -> bool;
+}
+
+impl CallerContract for Contract {
+ fn test_false() -> bool {
+ false
+ }
+}
+
+abi CalleeContract {
+ fn test_true() -> bool;
+}
+
+#[test]
+fn test_multi_contract_calls() {
+ let caller = abi(CallerContract, CONTRACT_ID);
+ let callee = abi(CalleeContract, callee::CONTRACT_ID);
+
+ let should_be_false = caller.test_false();
+ let should_be_true = callee.test_true();
+ assert(!should_be_false);
+ assert(should_be_true);
+}
+Within the sway file open in VSCode, you can set breakpoints on lines within the test or functions that it calls, and click Run -> Start Debugging to begin debugging the unit test.
+This will build the sway project and run it in debug mode. The debugger will stop the VM execution when a breakpoint is hit.
+The debug panel will show VM registers under the Variables tab, as well as the current VM opcode where execution is suspended. You can continue execution, or use the Step Over function to step forward, instruction by instruction.
+ +Forc provides tools for debugging both live transactions as well as Sway unit tests. +Debugging can be done via CLI or using the VSCode IDE.
+Unit testing refers to "in-language" test functions annotated with #[test]. Line-by-line
+debugging is available within the VSCode IDE.
Live transaction refers to the testing sending a transaction to a running Fuel Client
+node to exercise your Sway code. Instruction-by-instruction debugging is available in the forc debug CLI.
The following is a simple example of a contract which implements a counter. Both the initialize_counter() and increment_counter() ABI methods return the currently set value.
forc template --template-name counter my_counter_project
+contract;
+
+abi TestContract {
+ #[storage(write)]
+ fn initialize_counter(value: u64) -> u64;
+
+ #[storage(read, write)]
+ fn increment_counter(amount: u64) -> u64;
+}
+
+storage {
+ counter: u64 = 0,
+}
+
+impl TestContract for Contract {
+ #[storage(write)]
+ fn initialize_counter(value: u64) -> u64 {
+ storage.counter.write(value);
+ value
+ }
+
+ #[storage(read, write)]
+ fn increment_counter(amount: u64) -> u64 {
+ let incremented = storage.counter.read() + amount;
+ storage.counter.write(incremented);
+ incremented
+ }
+}
+The following commands can be used to build and deploy the contract. For a detailed tutorial, refer to Building and Deploying.
+# Build the contract
+forc build
+
+# Deploy the contract
+forc deploy --testnet
+FizzBuzzThis example is not the traditional FizzBuzz; instead it is the smart contract version! A script can call the fizzbuzz ABI method of this contract with some u64 value and receive back the result as an enum.
The format for custom structs and enums such as FizzBuzzResult will be automatically included in the ABI JSON so that off-chain code can handle the encoded form of the returned data.
contract;
+
+enum FizzBuzzResult {
+ Fizz: (),
+ Buzz: (),
+ FizzBuzz: (),
+ Other: u64,
+}
+
+abi FizzBuzz {
+ fn fizzbuzz(input: u64) -> FizzBuzzResult;
+}
+
+impl FizzBuzz for Contract {
+ fn fizzbuzz(input: u64) -> FizzBuzzResult {
+ if input % 15 == 0 {
+ FizzBuzzResult::FizzBuzz
+ } else if input % 3 == 0 {
+ FizzBuzzResult::Fizz
+ } else if input % 5 == 0 {
+ FizzBuzzResult::Buzz
+ } else {
+ FizzBuzzResult::Other(input)
+ }
+ }
+}
+Some basic example contracts to see how Sway and Forc work.
+ +Additional examples can be found in the Sway Applications repository.
+ +All contracts in Fuel can mint and burn their own native asset. Contracts can also receive and transfer any native asset including their own. Internal balances of all native assets pushed through calls or minted by the contract are tracked by the FuelVM and can be queried at any point using the balance_of function from the std library. Therefore, there is no need for any manual accounting of the contract's balances using persistent storage.
The std library provides handy methods for accessing Fuel's native asset operations.
In this example, we show a basic liquidity pool contract minting its own native asset LP asset.
+contract;
+
+use std::{
+ asset::{
+ mint_to,
+ transfer,
+ },
+ call_frames::msg_asset_id,
+ constants::DEFAULT_SUB_ID,
+ context::msg_amount,
+ hash::*,
+};
+
+abi LiquidityPool {
+ fn deposit(recipient: Address);
+ fn withdraw(recipient: Address);
+}
+
+const BASE_ASSET: AssetId = AssetId::from(0x9ae5b658754e096e4d681c548daf46354495a437cc61492599e33fc64dcdc30c);
+
+impl LiquidityPool for Contract {
+ fn deposit(recipient: Address) {
+ assert(msg_asset_id() == BASE_ASSET);
+ assert(msg_amount() > 0);
+
+ // Mint two times the amount.
+ let amount_to_mint = msg_amount() * 2;
+
+ // Mint some LP assets based upon the amount of the base asset.
+ mint_to(Identity::Address(recipient), DEFAULT_SUB_ID, amount_to_mint);
+ }
+
+ fn withdraw(recipient: Address) {
+ let asset_id = AssetId::default();
+ assert(msg_asset_id() == asset_id);
+ assert(msg_amount() > 0);
+
+ // Amount to withdraw.
+ let amount_to_transfer = msg_amount() / 2;
+
+ // Transfer base asset to recipient.
+ transfer(Identity::Address(recipient), BASE_ASSET, amount_to_transfer);
+ }
+}
+The Sway-Applications Repository contains end-to-end example applications that are written in Sway in order to demonstrate what can be built.
+The ABI declaration is a separate project from your ABI implementation. The project structure for the code should be organized as follows with the wallet_abi treated as an external library:
.
+├── wallet_abi
+│ ├── Forc.toml
+│ └── src
+│ └── main.sw
+└── wallet_smart_contract
+ ├── Forc.toml
+ └── src
+ └── main.sw
+It's also important to specify the source of the dependency within the project's Forc.toml file when using external libraries. Inside the wallet_smart_contract project, it requires a declaration like this:
[dependencies]
+wallet_abi = { path = "../wallet_abi/" }
+library;
+
+abi Wallet {
+ #[storage(read, write), payable]
+ fn receive_funds();
+
+ #[storage(read, write)]
+ fn send_funds(amount_to_send: u64, recipient_address: Address);
+}
+contract;
+
+use std::{asset::transfer, call_frames::msg_asset_id, context::msg_amount};
+
+use wallet_abi::Wallet;
+const OWNER_ADDRESS = Address::from(0x8900c5bec4ca97d4febf9ceb4754a60d782abbf3cd815836c1872116f203f861);
+
+storage {
+ balance: u64 = 0,
+}
+
+impl Wallet for Contract {
+ #[storage(read, write), payable]
+ fn receive_funds() {
+ if msg_asset_id() == AssetId::base() {
+ // If we received the base asset then keep track of the balance.
+ // Otherwise, we're receiving other native assets and don't care
+ // about our balance of coins.
+ storage.balance.write(storage.balance.read() + msg_amount());
+ }
+ }
+
+ #[storage(read, write)]
+ fn send_funds(amount_to_send: u64, recipient_address: Address) {
+ let sender = msg_sender().unwrap();
+ match sender {
+ Identity::Address(addr) => assert(addr == OWNER_ADDRESS),
+ _ => revert(0),
+ };
+
+ let current_balance = storage.balance.read();
+ assert(current_balance >= amount_to_send);
+
+ storage.balance.write(current_balance - amount_to_send);
+
+ // Note: `transfer()` is not a call and thus not an
+ // interaction. Regardless, this code conforms to
+ // checks-effects-interactions to avoid re-entrancy.
+ transfer(
+ Identity::Address(recipient_address),
+ AssetId::base(),
+ amount_to_send,
+ );
+ }
+}
+Usage: forc addr2line [OPTIONS] --sourcemap-path <SOURCEMAP_PATH> --opcode-index <OPCODE_INDEX>
+Options:
+-S, --search-dir <SEARCH_DIR>
Where to search for the project root [default: .]
+-g, --sourcemap-path <SOURCEMAP_PATH>
Source file mapping in JSON format
+-c, --context <CONTEXT>
How many lines of context to show [default: 2]
+-i, --opcode-index <OPCODE_INDEX>
Opcode index
+-v, --verbose...
Use verbose output
+-s, --silent
Silence all output
+-L, --log-level <LOG_LEVEL>
Set the log level
+-h, --help
Print help
+ +The output produced will depend on the project's program type.
+script, predicate and contract projects will produce their bytecode in binary format <project-name>.bin.
script projects will also produce a file containing the hash of the bytecode binary <project-name>-bin-hash (using fuel_cypto::Hasher).
predicate projects will also produce a file containing the root hash of the bytecode binary <project-name>-bin-root (using fuel_tx::Contract::root_from_code).
contract and library projects will also produce the public ABI in JSON format <project-name>-abi.json.
Usage: forc build [OPTIONS]
+Options:
+-p, --path <PATH>
Path to the project.
+If not specified, current working directory will be used.
+--offline
Offline mode.
+Prevents Forc from using the network when managing dependencies. Meaning it will only try to use previously downloaded dependencies.
+-t, --terse
Terse mode.
+Limited warning and error output.
+--output-directory <OUTPUT_DIRECTORY>
The directory in which Forc output artifacts are placed.
+By default, this is <project-root>/out.
--locked
Requires that the Forc.lock file is up-to-date.
+If the lock file is missing, or it needs to be updated, Forc will exit with an error.
+--ipfs-node <IPFS_NODE>
The IPFS node to use for fetching IPFS sources.
+[possible values: PUBLIC, LOCAL, <GATEWAY_URL>]
+--ast
Print the generated Sway AST (Abstract Syntax Tree)
+--dca-graph <DCA_GRAPH>
Print the computed Sway DCA (Dead Code Analysis) graph.
+DCA graph is printed to the specified path. If specified '' graph is printed to the stdout.
+--dca-graph-url-format <DCA_GRAPH_URL_FORMAT>
URL format to be used in the generated DCA graph .dot file.
+Variables {path}, {line}, and {col} can be used in the provided format. +An example for vscode would be: +"vscode://file/{path}:{line}:{col}"
+--asm <ASM>..>
Print the generated ASM (assembler).
+Values that can be combined:
+[possible values: virtual, allocated, abstract, final, all]
+--bytecode
Print the bytecode.
+This is the final output of the compiler.
+--ir <IR>..>
Print the generated Sway IR (Intermediate Representation).
+Values that can be combined:
+[possible values: initial, final, all, modified, inline, simplify-cfg, sroa, dce, fn-dce, fn-dedup-release, fn-dedup-debug, mem2reg, memcpyopt, const-folding, arg-demotion, const-demotion, ret-demotion, misc-demotion]
+--time-phases
Output the time elapsed over each part of the compilation process
+--profile
Profile the compilation process
+--reverse-order
Output build errors and warnings in reverse order
+-v, --verbose...
Use verbose output
+--metrics-outfile <METRICS_OUTFILE>
Output compilation metrics into the specified file
+-s, --silent
Silence all output
+--json-abi
Minify JSON ABI files.
+By default the JSON for ABIs is formatted for human readability. By using this option JSON output will be "minified", i.e. all on one line without whitespace.
+-L, --log-level <LOG_LEVEL>
Set the log level
+--json-storage-slots
Minify JSON storage slot files.
+By default the JSON for initial storage slots is formatted for human readability. By using this option JSON output will be "minified", i.e. all on one line without whitespace.
+-o, --output-bin <BIN_FILE>
Create a binary file at the provided path representing the final bytecode
+-g, --output-debug <DEBUG_FILE>
Create a file at the provided path containing debug information.
+If the file extension is .json, JSON format is used. Otherwise, an .elf file containing DWARF format is emitted.
+--build-profile <BUILD_PROFILE>
The name of the build profile to use
+[default: debug]
+--release
Use the release build profile.
+The release profile can be customized in the manifest file.
+--error-on-warnings
Treat warnings as errors
+--build-target <BUILD_TARGET>
Build target to use for code generation
+[default: fuel] +[possible values: fuel, evm]
+--tests
Also build all tests within the project
+--experimental <EXPERIMENTAL>
Comma separated list of all experimental features that will be enabled
+[possible values: new_encoding, storage_domains, references, error_type, partial_eq]
+--no-experimental <NO_EXPERIMENTAL>
Comma separated list of all experimental features that will be disabled
+[possible values: new_encoding, storage_domains, references, error_type, partial_eq]
+-h, --help
Print help (see a summary with '-h')
+-V, --version
Print version
+EXAMPLES:
+forc build
+forc build --path
forc build --path
Compile the sway files of the current project.
+$ forc build
+Compiled script "my-fuel-project".
+Bytecode size is 28 bytes.
+The output produced will depend on the project's program type. Building script, predicate and contract projects will produce their bytecode in binary format <project-name>.bin. Building contracts and libraries will also produce the public ABI in JSON format <project-name>-abi.json.
By default, these artifacts are placed in the out/ directory.
If a Forc.lock file did not yet exist, it will be created in order to pin each of the dependencies listed in Forc.toml to a specific commit or version.
This will essentially compile the packages without performing the final step of code generation, which is faster than running forc build.
+Usage: forc check [OPTIONS] [BUILD_TARGET]
+Arguments: +[BUILD_TARGET] +Build target to use for code generation
+[default: fuel] +[possible values: fuel, evm]
+Options:
+-p, --path <PATH>
Path to the project, if not specified, current working directory will be used
+--offline
Offline mode, prevents Forc from using the network when managing dependencies. Meaning it will only try to use previously downloaded dependencies
+--locked
Requires that the Forc.lock file is up-to-date. If the lock file is missing, or it needs to be updated, Forc will exit with an error
+-t, --terse
Terse mode. Limited warning and error output
+--disable-tests
Disable checking unit tests
+--ipfs-node <IPFS_NODE>
The IPFS Node to use for fetching IPFS sources.
+Possible values: PUBLIC, LOCAL, <GATEWAY_URL>
+--experimental <EXPERIMENTAL>
Comma separated list of all experimental features that will be enabled
+[possible values: new_encoding, storage_domains, references, error_type, partial_eq]
+--no-experimental <NO_EXPERIMENTAL>
Comma separated list of all experimental features that will be disabled
+[possible values: new_encoding, storage_domains, references, error_type, partial_eq]
+-v, --verbose...
Use verbose output
+-s, --silent
Silence all output
+-L, --log-level <LOG_LEVEL>
Set the log level
+-h, --help
Print help (see a summary with '-h')
+-V, --version
Print version
+EXAMPLES:
+forc check
+forc check --path
forc check --locked
+ +Usage: forc clean [OPTIONS]
+Options:
+-p, --path <PATH>
Path to the project, if not specified, current working directory will be used
+-v, --verbose...
Use verbose output
+-s, --silent
Silence all output
+-L, --log-level <LOG_LEVEL>
Set the log level
+-h, --help
Print help
+-V, --version
Print version
+EXAMPLES:
+forc clean
+forc clean --path
Usage: forc completions [OPTIONS] --target
Options:
+-T, --target <TARGET>
Specify shell to enable tab-completion for
+[possible values: zsh, bash, fish, powershell, elvish]
+For more info: https://fuellabs.github.io/sway/latest/forc/commands/forc_completions.html
+Possible values:
+-v, --verbose...
Use verbose output
+-s, --silent
Silence all output
+-L, --log-level <LOG_LEVEL>
Set the log level
+-h, --help
Print help (see a summary with '-h')
+Enable tab completion for Bash, Fish, Zsh, or PowerShell
+The script is output on stdout, allowing one to re-direct the
+output to the file of their choosing. Where you place the file
+will depend on which shell, and which operating system you are
+using. Your particular configuration may also determine where
+these scripts need to be placed.
Here are some common set ups for the three supported shells under +Unix and similar operating systems (such as GNU/Linux).
+Completion files are commonly stored in /etc/bash_completion.d/ for
+system-wide commands, but can be stored in
+~/.local/share/bash-completion/completions for user-specific commands.
+Run the command:
mkdir -p ~/.local/share/bash-completion/completions
+forc completions --shell=bash >> ~/.local/share/bash-completion/completions/forc
+This installs the completion script. You may have to log out and +log back in to your shell session for the changes to take effect.
+Homebrew stores bash completion files within the Homebrew directory.
+With the bash-completion brew formula installed, run the command:
mkdir -p $(brew --prefix)/etc/bash_completion.d
+forc completions --shell=bash > $(brew --prefix)/etc/bash_completion.d/forc.bash-completion
+Fish completion files are commonly stored in
+$HOME/.config/fish/completions. Run the command:
mkdir -p ~/.config/fish/completions
+forc completions --shell=fish > ~/.config/fish/completions/forc.fish
+This installs the completion script. You may have to log out and +log back in to your shell session for the changes to take effect.
+ZSH completions are commonly stored in any directory listed in
+your $fpath variable. To use these completions, you must either
+add the generated script to one of those directories, or add your
+own to this list.
Adding a custom directory is often the safest bet if you are
+unsure of which directory to use. First create the directory; for
+this example we'll create a hidden directory inside our $HOME
+directory:
mkdir ~/.zfunc
+Then add the following lines to your .zshrc just before
+compinit:
fpath+=~/.zfunc
+Now you can install the completions script using the following +command:
+forc completions --shell=zsh > ~/.zfunc/_forc
+You must then either log out and log back in, or simply run
+exec zsh
+for the new completions to take effect.
+Alternatively, you could save these files to the place of your
+choosing, such as a custom directory inside your $HOME. Doing so
+will require you to add the proper directives, such as sourceing
+inside your login script. Consult your shells documentation for
+how to add such directives.
The powershell completion scripts require PowerShell v5.0+ (which +comes with Windows 10, but can be downloaded separately for windows 7 +or 8.1).
+First, check if a profile has already been set
+Test-Path $profile
+If the above command returns False run the following
New-Item -path $profile -type file -force
+Now open the file provided by $profile (if you used the
+New-Item command it will be
+${env:USERPROFILE}\Documents\WindowsPowerShell\Microsoft.PowerShell_profile.ps1
Next, we either save the completions file into our profile, or +into a separate file and source it inside our profile. To save the +completions into our profile simply use
+forc completions --shell=powershell >> ${env:USERPROFILE}\Documents\WindowsPowerShell\Microsoft.PowerShell_profile.ps1
+Usage: forc contract-id [OPTIONS]
+Options:
+-p, --path <PATH>
Path to the project.
+If not specified, current working directory will be used.
+--offline
Offline mode.
+Prevents Forc from using the network when managing dependencies. Meaning it will only try to use previously downloaded dependencies.
+-t, --terse
Terse mode.
+Limited warning and error output.
+--output-directory <OUTPUT_DIRECTORY>
The directory in which Forc output artifacts are placed.
+By default, this is <project-root>/out.
--locked
Requires that the Forc.lock file is up-to-date.
+If the lock file is missing, or it needs to be updated, Forc will exit with an error.
+--ipfs-node <IPFS_NODE>
The IPFS node to use for fetching IPFS sources.
+[possible values: PUBLIC, LOCAL, <GATEWAY_URL>]
+--json-abi
Minify JSON ABI files.
+By default the JSON for ABIs is formatted for human readability. By using this option JSON output will be "minified", i.e. all on one line without whitespace.
+--json-storage-slots
Minify JSON storage slot files.
+By default the JSON for initial storage slots is formatted for human readability. By using this option JSON output will be "minified", i.e. all on one line without whitespace.
+--ast
Print the generated Sway AST (Abstract Syntax Tree)
+--dca-graph <DCA_GRAPH>
Print the computed Sway DCA (Dead Code Analysis) graph.
+DCA graph is printed to the specified path. If specified '' graph is printed to the stdout.
+--dca-graph-url-format <DCA_GRAPH_URL_FORMAT>
URL format to be used in the generated DCA graph .dot file.
+Variables {path}, {line}, and {col} can be used in the provided format. +An example for vscode would be: +"vscode://file/{path}:{line}:{col}"
+--asm <ASM>..>
Print the generated ASM (assembler).
+Values that can be combined:
+[possible values: virtual, allocated, abstract, final, all]
+--bytecode
Print the bytecode.
+This is the final output of the compiler.
+--ir <IR>..>
Print the generated Sway IR (Intermediate Representation).
+Values that can be combined:
+[possible values: initial, final, all, modified, inline, simplify-cfg, sroa, dce, fn-dce, fn-dedup-release, fn-dedup-debug, mem2reg, memcpyopt, const-folding, arg-demotion, const-demotion, ret-demotion, misc-demotion]
+--time-phases
Output the time elapsed over each part of the compilation process
+-v, --verbose...
Use verbose output
+--profile
Profile the compilation process
+-s, --silent
Silence all output
+-L, --log-level <LOG_LEVEL>
Set the log level
+--reverse-order
Output build errors and warnings in reverse order
+--metrics-outfile <METRICS_OUTFILE>
Output compilation metrics into the specified file
+-o, --output-bin <BIN_FILE>
Create a binary file at the provided path representing the final bytecode
+-g, --output-debug <DEBUG_FILE>
Create a file at the provided path containing debug information.
+If the file extension is .json, JSON format is used. Otherwise, an .elf file containing DWARF format is emitted.
+--build-profile <BUILD_PROFILE>
The name of the build profile to use
+[default: debug]
+--release
Use the release build profile.
+The release profile can be customized in the manifest file.
+--error-on-warnings
Treat warnings as errors
+--salt <SALT>
Added salt used to derive the contract ID.
+By default, this is 0x0000000000000000000000000000000000000000000000000000000000000000.
--experimental <EXPERIMENTAL>
Comma separated list of all experimental features that will be enabled
+[possible values: new_encoding, storage_domains, references, error_type, partial_eq]
+--no-experimental <NO_EXPERIMENTAL>
Comma separated list of all experimental features that will be disabled
+[possible values: new_encoding, storage_domains, references, error_type, partial_eq]
+-h, --help
Print help (see a summary with '-h')
+-V, --version
Print version
+EXAMPLES:
+forc contract-id
+forc contract-id --path
Usage: forc init [OPTIONS]
+Options:
+--path <PATH>
The directory in which the forc project will be initialized
+--contract
The default program type, excluding all flags or adding this flag creates a basic contract program
+--script
Create a package with a script target (src/main.sw)
+--predicate
Create a package with a predicate target (src/predicate.rs)
+--library
Create a package with a library target (src/lib.sw)
+--workspace
Adding this flag creates an empty workspace
+--name <NAME>
Set the package name. Defaults to the directory name
+-v, --verbose...
Use verbose output
+-s, --silent
Silence all output
+-L, --log-level <LOG_LEVEL>
Set the log level
+-h, --help
Print help
+-V, --version
Print version
+EXAMPLES:
+forc init --path
forc init --path
forc init --path
forc init --path
$ mkdir my-fuel-project
+$ cd my-fuel-project
+$ forc init
+$ tree
+.
+├── Forc.toml
+└── src
+ └── main.sw
+Forc.toml is the Forc manifest file, containing information about the project and dependencies.
A src/ directory is created, with a single main.sw Sway file in it.
Usage: forc new [OPTIONS]
Arguments:
+<PATH>
+The path at which the project directory will be created
+Options:
+--contract
The default program type. Excluding all flags or adding this flag creates a basic contract program
+--script
Adding this flag creates an empty script program
+--predicate
Adding this flag creates an empty predicate program
+--library
Adding this flag creates an empty library program
+--workspace
Adding this flag creates an empty workspace
+--name <NAME>
Set the package name. Defaults to the directory name
+-v, --verbose...
Use verbose output
+-s, --silent
Silence all output
+-L, --log-level <LOG_LEVEL>
Set the log level
+-h, --help
Print help
+-V, --version
Print version
+EXAMPLES:
+forc new --contract --name my_project
forc new --workspace --name my_workspace
forc new
forc new
$ forc new my-fuel-project
+$ cd my-fuel-project
+$ tree
+.
+├── Forc.toml
+└── src
+ └── main.sw
+Forc.toml is the Forc manifest file, containing information about the project and dependencies.
A src/ directory is created, with a single main.sw Sway file in it.
Usage: forc parse-bytecode [OPTIONS] <FILE_PATH>
+Arguments:
+<FILE_PATH>
+Options:
+-v, --verbose...
Use verbose output
+-s, --silent
Silence all output
+-L, --log-level <LOG_LEVEL>
Set the log level
+-h, --help
Print help
+-V, --version
Print version
+EXAMPLES:
+forc parse-bytecode
We can try this command with the initial project created using forc init, with the counter template:
forc new --template counter counter
+cd counter
+forc build -o obj
+counter$ forc parse-bytecode obj
+
+ half-word byte op raw notes
+ 0 0 JI(4) 90 00 00 04 conditionally jumps to byte 16
+ 1 4 NOOP 47 00 00 00
+ 2 8 Undefined 00 00 00 00 data section offset lo (0)
+ 3 12 Undefined 00 00 00 c8 data section offset hi (200)
+ 4 16 LW(63, 12, 1) 5d fc c0 01
+ 5 20 ADD(63, 63, 12) 10 ff f3 00
+ ...
+ ...
+ ...
+ 60 240 Undefined 00 00 00 00
+ 61 244 Undefined fa f9 0d d3
+ 62 248 Undefined 00 00 00 00
+ 63 252 Undefined 00 00 00 c8
+Prints information about each discovered plugin.
+Usage: forc plugins [OPTIONS]
+Options:
+-p, --paths
Prints the absolute path to each discovered plugin
+-d, --describe
Prints the long description associated with each listed plugin
+-v, --verbose...
Use verbose output
+-s, --silent
Silence all output
+-L, --log-level <LOG_LEVEL>
Set the log level
+-h, --help
Print help (see a summary with '-h')
+-V, --version
Print version
+EXAMPLES:
+forc plugins
+forc plugins --paths
+forc plugins --describe
+forc plugins --paths --describe
+ +Usage: forc predicate-root [OPTIONS]
+Options:
+-p, --path <PATH>
Path to the project.
+If not specified, current working directory will be used.
+--offline
Offline mode.
+Prevents Forc from using the network when managing dependencies. Meaning it will only try to use previously downloaded dependencies.
+-t, --terse
Terse mode.
+Limited warning and error output.
+--output-directory <OUTPUT_DIRECTORY>
The directory in which Forc output artifacts are placed.
+By default, this is <project-root>/out.
--locked
Requires that the Forc.lock file is up-to-date.
+If the lock file is missing, or it needs to be updated, Forc will exit with an error.
+--ipfs-node <IPFS_NODE>
The IPFS node to use for fetching IPFS sources.
+[possible values: PUBLIC, LOCAL, <GATEWAY_URL>]
+--json-abi
Minify JSON ABI files.
+By default the JSON for ABIs is formatted for human readability. By using this option JSON output will be "minified", i.e. all on one line without whitespace.
+--json-storage-slots
Minify JSON storage slot files.
+By default the JSON for initial storage slots is formatted for human readability. By using this option JSON output will be "minified", i.e. all on one line without whitespace.
+--ast
Print the generated Sway AST (Abstract Syntax Tree)
+--dca-graph <DCA_GRAPH>
Print the computed Sway DCA (Dead Code Analysis) graph.
+DCA graph is printed to the specified path. If specified '' graph is printed to the stdout.
+--dca-graph-url-format <DCA_GRAPH_URL_FORMAT>
URL format to be used in the generated DCA graph .dot file.
+Variables {path}, {line}, and {col} can be used in the provided format. +An example for vscode would be: +"vscode://file/{path}:{line}:{col}"
+--asm <ASM>..>
Print the generated ASM (assembler).
+Values that can be combined:
+[possible values: virtual, allocated, abstract, final, all]
+--bytecode
Print the bytecode.
+This is the final output of the compiler.
+--ir <IR>..>
Print the generated Sway IR (Intermediate Representation).
+Values that can be combined:
+[possible values: initial, final, all, modified, inline, simplify-cfg, sroa, dce, fn-dce, fn-dedup-release, fn-dedup-debug, mem2reg, memcpyopt, const-folding, arg-demotion, const-demotion, ret-demotion, misc-demotion]
+--time-phases
Output the time elapsed over each part of the compilation process
+-v, --verbose...
Use verbose output
+--profile
Profile the compilation process
+-s, --silent
Silence all output
+-L, --log-level <LOG_LEVEL>
Set the log level
+--reverse-order
Output build errors and warnings in reverse order
+--metrics-outfile <METRICS_OUTFILE>
Output compilation metrics into the specified file
+-o, --output-bin <BIN_FILE>
Create a binary file at the provided path representing the final bytecode
+-g, --output-debug <DEBUG_FILE>
Create a file at the provided path containing debug information.
+If the file extension is .json, JSON format is used. Otherwise, an .elf file containing DWARF format is emitted.
+--build-profile <BUILD_PROFILE>
The name of the build profile to use
+[default: debug]
+--release
Use the release build profile.
+The release profile can be customized in the manifest file.
+--error-on-warnings
Treat warnings as errors
+--experimental <EXPERIMENTAL>
Comma separated list of all experimental features that will be enabled
+[possible values: new_encoding, storage_domains, references, error_type, partial_eq]
+--no-experimental <NO_EXPERIMENTAL>
Comma separated list of all experimental features that will be disabled
+[possible values: new_encoding, storage_domains, references, error_type, partial_eq]
+-h, --help
Print help (see a summary with '-h')
+-V, --version
Print version
+EXAMPLES:
+forc predicate-root
+ +Usage: forc template [OPTIONS] <PROJECT_NAME>
+Arguments:
+<PROJECT_NAME>
+The name of the project that will be created
+Options:
+-u, --url <URL>
The template url, should be a git repo [default: https://github.com/fuellabs/sway]
+-t, --template-name <TEMPLATE_NAME>
The name of the template that needs to be fetched and used from git repo provided
+-v, --verbose...
Use verbose output
+-s, --silent
Silence all output
+-L, --log-level <LOG_LEVEL>
Set the log level
+-h, --help
Print help
+-V, --version
Print version
+EXAMPLES:
+forc template new-path --template-name option
+forc template --url https://github.com/owner/template/ --project_name my_example_project
+The command above fetches the HEAD of the template repo and searches for Forc.toml at the root of the fetched repo. It will fetch the repo and prepare a new Forc.toml with the new project name. Outputs everything to current_dir/project_name.
forc template --url https://github.com/FuelLabs/sway --template_name counter --project_name my_example_project
+The command above fetches the HEAD of the sway repo and searches for counter example inside it (there is an example called counter under sway/examples). It will fetch the counter example and prepare a new Forc.toml with the new project name. Outputs everything to current_dir/project_name.
NOTE: Previously this command was used to support Rust integration testing, however the provided behaviour served no benefit over running cargo test directly. The proposal to change the behaviour to support unit testing can be found at the following link: https://github.com/FuelLabs/sway/issues/1833
Sway unit tests are functions decorated with the #[test] attribute. Each test is compiled as a unique entry point for a single program and has access to the namespace of the module in which it is declared.
Unit tests decorated with the #[test(script)] attribute that are declared within contract projects may also call directly into their associated contract's ABI.
Upon successful compilation, test scripts are executed to their completion. A test is considered a failure in the case that a revert (rvrt) instruction is encountered during execution. Otherwise, it is considered a success.
Usage: forc test [OPTIONS] [FILTER]
+Arguments: +[FILTER] +When specified, only tests containing the given string will be executed
+Options:
+-p, --path <PATH>
Path to the project.
+If not specified, current working directory will be used.
+--offline
Offline mode.
+Prevents Forc from using the network when managing dependencies. Meaning it will only try to use previously downloaded dependencies.
+-t, --terse
Terse mode.
+Limited warning and error output.
+--output-directory <OUTPUT_DIRECTORY>
The directory in which Forc output artifacts are placed.
+By default, this is <project-root>/out.
--locked
Requires that the Forc.lock file is up-to-date.
+If the lock file is missing, or it needs to be updated, Forc will exit with an error.
+--ipfs-node <IPFS_NODE>
The IPFS node to use for fetching IPFS sources.
+[possible values: PUBLIC, LOCAL, <GATEWAY_URL>]
+--ast
Print the generated Sway AST (Abstract Syntax Tree)
+--dca-graph <DCA_GRAPH>
Print the computed Sway DCA (Dead Code Analysis) graph.
+DCA graph is printed to the specified path. If specified '' graph is printed to the stdout.
+--dca-graph-url-format <DCA_GRAPH_URL_FORMAT>
URL format to be used in the generated DCA graph .dot file.
+Variables {path}, {line}, and {col} can be used in the provided format. +An example for vscode would be: +"vscode://file/{path}:{line}:{col}"
+--asm <ASM>..>
Print the generated ASM (assembler).
+Values that can be combined:
+[possible values: virtual, allocated, abstract, final, all]
+--bytecode
Print the bytecode.
+This is the final output of the compiler.
+--ir <IR>..>
Print the generated Sway IR (Intermediate Representation).
+Values that can be combined:
+[possible values: initial, final, all, modified, inline, simplify-cfg, sroa, dce, fn-dce, fn-dedup-release, fn-dedup-debug, mem2reg, memcpyopt, const-folding, arg-demotion, const-demotion, ret-demotion, misc-demotion]
+--time-phases
Output the time elapsed over each part of the compilation process
+--profile
Profile the compilation process
+--reverse-order
Output build errors and warnings in reverse order
+-v, --verbose...
Use verbose output
+--metrics-outfile <METRICS_OUTFILE>
Output compilation metrics into the specified file
+-s, --silent
Silence all output
+--json-abi
Minify JSON ABI files.
+By default the JSON for ABIs is formatted for human readability. By using this option JSON output will be "minified", i.e. all on one line without whitespace.
+-L, --log-level <LOG_LEVEL>
Set the log level
+--json-storage-slots
Minify JSON storage slot files.
+By default the JSON for initial storage slots is formatted for human readability. By using this option JSON output will be "minified", i.e. all on one line without whitespace.
+-o, --output-bin <BIN_FILE>
Create a binary file at the provided path representing the final bytecode
+-g, --output-debug <DEBUG_FILE>
Create a file at the provided path containing debug information.
+If the file extension is .json, JSON format is used. Otherwise, an .elf file containing DWARF format is emitted.
+--build-profile <BUILD_PROFILE>
The name of the build profile to use
+[default: debug]
+--release
Use the release build profile.
+The release profile can be customized in the manifest file.
+--error-on-warnings
Treat warnings as errors
+--build-target <BUILD_TARGET>
Build target to use for code generation
+[default: fuel] +[possible values: fuel, evm]
+--pretty
Pretty-print the logs emitted from tests
+-l, --logs
Print Log and LogData receipts for tests
--raw-logs
Print the raw logs for tests
+--filter-exact
When specified, only the test exactly matching the given string will be executed
+--test-threads <TEST_THREADS>
Number of threads to utilize when running the tests. By default, this is the number of threads available in your system
+--experimental <EXPERIMENTAL>
Comma separated list of all experimental features that will be enabled
+[possible values: new_encoding, storage_domains, references, error_type, partial_eq]
+--no-experimental <NO_EXPERIMENTAL>
Comma separated list of all experimental features that will be disabled
+[possible values: new_encoding, storage_domains, references, error_type, partial_eq]
+-h, --help
Print help (see a summary with '-h')
+-V, --version
Print version
+EXAMPLES:
+forc test
+forc test $filter
+forc test --silent
+forc test --locked
+ +Usage: forc update [OPTIONS]
+Options:
+-p, --path <PATH>
Path to the project, if not specified, current working directory will be used
+-d <TARGET_DEPENDENCY>
Dependency to be updated. If not set, all dependencies will be updated
+-c, --check
Checks if the dependencies have newer versions. Won't actually perform the update, will output which ones are up-to-date and outdated
+--ipfs-node <IPFS_NODE>
The IPFS Node to use for fetching IPFS sources.
+Possible values: PUBLIC, LOCAL, <GATEWAY_URL>
+-v, --verbose...
Use verbose output
+-s, --silent
Silence all output
+-L, --log-level <LOG_LEVEL>
Set the log level
+-h, --help
Print help (see a summary with '-h')
+-V, --version
Print version
+EXAMPLES:
+forc update
+forc update -d std
+forc update --check
+ +Here are a list of commands available to forc:
+ + +Forc has a dependency management system which can pull packages using git and ipfs. This allows users to build and share Forc libraries.
If your Forc.toml doesn't already have a [dependencies] table, add one. Below, list the package name alongside its source. Currently, forc supports git, ipfs and path sources.
If a git source is specified, forc will fetch the git repository at the given URL and then search for a Forc.toml for a package with the given name anywhere inside the git repository.
The following example adds a library dependency named custom_lib. For git dependencies you may optionally specify a branch, tag, or rev (i.e. commit hash) reference.
[dependencies]
+custom_lib = { git = "https://github.com/FuelLabs/custom_lib", branch = "master" }
+# custom_lib = { git = "https://github.com/FuelLabs/custom_lib", tag = "v0.0.1" }
+# custom_lib = { git = "https://github.com/FuelLabs/custom_lib", rev = "87f80bdf323e2d64e213895d0a639ad468f4deff" }
+Depending on a local library using path:
[dependencies]
+custom_lib = { path = "../custom_lib" }
+For ipfs sources, forc will fetch the specified cid using either a local ipfs node or a public gateway. forc automatically tries to connect to local ipfs node. If it fails, it defaults to using https://ipfs.io/ as a gateway.
The following example adds a dependency with an ipfs source.
[dependencies]
+custom_lib = { ipfs = "QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG" }
+Once the package is added, running forc build will automatically download added dependencies.
To update dependencies in your Forc directory you can run forc update. For path and ipfs dependencies this will have no effect. For git dependencies with a branch reference, this will update the project to use the latest commit for the given branch.
Forc stands for Fuel Orchestrator. Forc provides a variety of tools and commands for developers working with the Fuel ecosystem, such as scaffolding a new project, formatting, running scripts, deploying contracts, testing contracts, and more. If you're coming from a Rust background, forc is similar to cargo.
+If you are new to Forc, see the Forc Project introduction section.
+For a comprehensive overview of the Forc CLI commands, see the Commands section.
+ +The Forc.toml (the manifest file) is a compulsory file for each package and it is written in [TOML] format. Forc.toml consists of the following fields:
[project] — Defines a sway project.
name — The name of the project.version — The version of the project.description — A description of the project.authors — The authors of the project.organization — The organization of the project.license — The project license.homepage — URL of the project homepage.repository — URL of the project source repository.documentation — URL of the project documentation.entry — The entry point for the compiler to start parsing from.
+implicit-std - Controls whether provided std version (with the current forc version) will get added as a dependency implicitly. Unless you know what you are doing, leave this as default.forc-version - The minimum forc version required for this project to work properly.metadata - Metadata for the project; can be used by tools which would like to store package configuration in Forc.toml.[dependencies] — Defines the dependencies.
[network] — Defines a network for forc to interact with.
url — URL of the network.[build-profile] - Defines the build profiles.
[patch] - Defines the patches.
[contract-dependencies] - Defines the contract dependencies.
[project] sectionAn example Forc.toml is shown below. Under [project] the following fields are optional:
authorsorganizationversiondescriptionhomepagerepositorydocumentationAlso for the following fields, a default value is provided so omitting them is allowed:
+entry - (default : main.sw )implicit-std - (default : true )[project]
+authors = ["user"]
+entry = "main.sw"
+description = "Wallet contract"
+version = "1.0.0"
+homepage = "https://example.com/"
+repository = "https://example.com/"
+documentation = "https://example.com/"
+organization = "Fuel_Labs"
+license = "Apache-2.0"
+name = "wallet_contract"
+
+[project.metadata]
+indexing = { namespace = "counter-contract", schema_path = "out/release/counter-contract-abi.json" }
+Forc.tomlThe [project.metadata] section provides a dedicated space for external tools and plugins to store their configuration in Forc.toml. The metadata key names are arbitrary and do not need to match the tool's name.
Metadata can be defined at two levels:
+Workspace level - defined in the workspace's root Forc.toml:
[workspace.metadata]
+my_tool = { shared_setting = "value" }
+Project level - defined in individual project's Forc.toml:
[project.metadata.any_name_here]
+option1 = "value"
+option2 = "value"
+
+[project.metadata.my_custom_config]
+setting1 = "value"
+setting2 = "value"
+Example for an indexing tool:
+[project.metadata.indexing]
+namespace = "counter-contract"
+schema_path = "out/release/counter-contract-abi.json"
+When both workspace and project metadata exist:
+Best Practices
+Forc.toml if tool can function without itImplementation Notes
+This allows for a streamlined developer experience while maintaining clear separation between core Forc functionality and third-party tools.
+Forc.toml metadata to read contract ABI JSON file.Forc.toml metadata to read contract ABI JSON file.[dependencies] sectionThe following fields can be provided with a dependency:
+version - Desired version of the dependencypath - The path of the dependency (if it is local)git - The URL of the git repo hosting the dependencybranch - The desired branch to fetch from the git repotag - The desired tag to fetch from the git reporev - The desired rev (i.e. commit hash) referencePlease see dependencies for details
+[network] sectionFor the following fields, a default value is provided so omitting them is allowed:
+URL - (default: http://127.0.0.1:4000)[build-profile.*] sectionThe [build-profile] tables provide a way to customize compiler settings such as debug options.
The following fields can be provided for a build-profile:
+print-ast - Whether to print out the generated AST or not, defaults to false.print-dca-graph - Whether to print out the computed Dead Code Analysis (DCA) graph (in GraphViz DOT format), defaults to false.print-dca-graph-url-format - The URL format to be used in the generated DOT file, an example for VS Code would be: vscode://file/{path}:{line}:{col}.print-ir - Whether to print out the generated Sway IR (Intermediate Representation) or not, defaults to false.print-asm - Whether to print out the generated ASM (assembler), defaults to false.terse - Terse mode. Limited warning and error output, defaults to false.time_phases - Whether to output the time elapsed over each part of the compilation process, defaults to false.include_tests - Whether or not to include test functions in parsing, type-checking, and code generation. This is set to true by invocations like forc test, but defaults to false.error_on_warnings - Whether to treat errors as warnings, defaults to false.There are two default [build-profile] available with every manifest file. These are debug and release profiles. If you want to override these profiles, you can provide them explicitly in the manifest file like the following example:
[project]
+authors = ["user"]
+entry = "main.sw"
+organization = "Fuel_Labs"
+license = "Apache-2.0"
+name = "wallet_contract"
+
+[build-profile.debug]
+print-asm = { virtual = false, allocated = false, final = true }
+print-ir = { initial = false, final = true, modified = false, passes = []}
+terse = false
+
+[build-profile.release]
+print-asm = { virtual = true, allocated = false, final = true }
+print-ir = { initial = true, final = false, modified = true, passes = ["dce", "sroa"]}
+terse = true
+Since release and debug are implicitly included in every manifest file, you can use them by just passing --release or by not passing anything (debug is default). For using a user defined build profile there is --build-profile <profile name> option available to the relevant commands. (For an example see forc-build)
Note that providing the corresponding CLI options (like --asm) will override the selected build profile. For example if you pass both --release and --asm all, release build profile is overridden and resulting build profile would have a structure like the following:
print-ast = false
+print-ir = { initial = false, final = false, modified = false, passes = []}
+print-asm = { virtual = true, allocated = true, final = true }
+terse = false
+time-phases = false
+include-tests = false
+error-on-warnings = false
+experimental-private-modules = false
+[patch] sectionThe [patch] section of Forc.toml can be used to override dependencies with other copies. The example provided below patches https://github.com/fuellabs/sway with the test branch of the same repo.
[project]
+authors = ["user"]
+entry = "main.sw"
+organization = "Fuel_Labs"
+license = "Apache-2.0"
+name = "wallet_contract"
+
+[dependencies]
+
+[patch.'https://github.com/fuellabs/sway']
+std = { git = "https://github.com/fuellabs/sway", branch = "test" }
+In the example above, std is patched with the test branch from std repo. You can also patch git dependencies with dependencies defined with a path.
[patch.'https://github.com/fuellabs/sway']
+std = { path = "/path/to/local_std_version" }
+Just like std or core you can also patch dependencies you declared with a git repo.
[project]
+authors = ["user"]
+entry = "main.sw"
+organization = "Fuel_Labs"
+license = "Apache-2.0"
+name = "wallet_contract"
+
+[dependencies]
+foo = { git = "https://github.com/foo/foo", branch = "master" }
+
+[patch.'https://github.com/foo']
+foo = { git = "https://github.com/foo/foo", branch = "test" }
+Note that each key after the [patch] is a URL of the source that is being patched.
[contract-dependencies] sectionThe [contract-dependencies] table can be used to declare contract dependencies for a Sway contract or script. Contract dependencies are the set of contracts that our contract or script may interact with. Declaring [contract-dependencies] makes it easier to refer to contracts in your Sway source code without having to manually update IDs each time a new version is deployed. Instead, we can use forc to pin and update contract dependencies just like we do for regular library dependencies.
Contracts declared under [contract-dependencies] are built and pinned just like regular [dependencies] however rather than importing each contract dependency's entire public namespace we instead import their respective contract IDs as CONTRACT_ID constants available via each contract dependency's namespace root. This means you can use a contract dependency's ID as if it were declared as a pub const in the root of the contract dependency package as demonstrated in the example below.
Entries under [contract-dependencies] can be declared in the same way that [dependencies] can be declared. That is, they can refer to the path or git source of another contract. Note that entries under [contract-dependencies] must refer to contracts and will otherwise produce an error.
Example Forc.toml:
[project]
+authors = ["user"]
+entry = "main.sw"
+organization = "Fuel_Labs"
+license = "Apache-2.0"
+name = "wallet_contract"
+
+[contract-dependencies]
+foo = { path = "../foo" }
+Example usage:
+script;
+
+fn main() {
+ let foo_id = foo::CONTRACT_ID;
+}
+Because the ID of a contract is computed deterministically, rebuilding the same contract would always result in the same contract ID. Since two contracts with the same contract ID cannot be deployed on the blockchain, a "salt" factor is needed to modify the contract ID. For each contract dependency declared under [contract-dependencies], salt can be specified. An example is shown below:
[contract-dependencies]
+foo = { path = "../foo", salt = "0x1000000000000000000000000000000000000000000000000000000000000000" }
+For contract dependencies that do not specify any value for salt, a default of all zeros for salt is implicitly applied.
Usage: forc call [OPTIONS] --abi
Arguments:
+<CONTRACT_ID> +The contract ID to call
+<FUNCTION> +The function selector to call. The function selector is the name of the function to call (e.g. "transfer"). It must be a valid selector present in the ABI file
+[FUNCTION_ARGS]... +Arguments to pass into the function to be called
+Options:
+--abi <ABI>
Path or URI to a JSON ABI file
+--node-url <NODE_URL>
The URL of the Fuel node to which we're submitting the transaction. If unspecified, checks the manifest's network table, then falls back to http://127.0.0.1:4000
You can also use --target, --devnet, --testnet, or --mainnet to specify the Fuel node.
[env: FUEL_NODE_URL=]
+--target <TARGET>
Preset configurations for using a specific target.
+You can also use --node-url, --devnet, --testnet, or --mainnet to specify the Fuel node.
Possible values are: [local, testnet, mainnet]
+--mainnet
Use preset configuration for mainnet.
+You can also use --node-url, --target, or --testnet to specify the Fuel node.
--testnet
Use preset configuration for testnet.
+You can also use --node-url, --target, or --mainnet to specify the Fuel node.
--devnet
Use preset configuration for devnet.
+You can also use --node-url, --target, or --testnet to specify the Fuel node.
--signing-key <SIGNING_KEY>
Derive an account from a secret key to make the call
+[env: SIGNING_KEY=]
+--wallet
Use forc-wallet to make the call
+--amount <AMOUNT>
Amount of native assets to forward with the call
+[default: 0]
+--asset-id <ASSET_ID>
Asset ID to forward with the call
+--gas-forwarded <GAS_FORWARDED>
Amount of gas to forward with the call
+--mode <MODE>
The execution mode to use for the call; defaults to dry-run; possible values: dry-run, simulate, live
+[default: dry-run]
+--gas-price <PRICE>
Gas price for the transaction
+--script-gas-limit <SCRIPT_GAS_LIMIT>
Gas limit for the transaction
+--max-fee <MAX_FEE>
Max fee for the transaction
+--tip <TIP>
The tip for the transaction
+--external-contracts <EXTERNAL_CONTRACTS>
The external contract addresses to use for the call If none are provided, the call will automatically populate external contracts by making a dry-run calls to the node, and extract the contract addresses based on the revert reason
+--output <OUTPUT>
The output format to use; possible values: default, raw
+[default: default]
+-h, --help
Print help (see a summary with '-h')
+-V, --version
Print version
+EXAMPLES:
+» forc call 0x0dcba78d7b09a1f77353f51367afd8b8ab94b5b2bb6c9437d9ba9eea47dede97
+--abi
./contract-abi.json
+get_balance 0x0087675439e10a8351b1d5e4cf9d0ea6da77675623ff6b16470b5e3c58998423
» forc call 0x0dcba78d7b09a1f77353f51367afd8b8ab94b5b2bb6c9437d9ba9eea47dede97
+--abi
./contract-abi.json
+get_name
» forc call 0x0dcba78d7b09a1f77353f51367afd8b8ab94b5b2bb6c9437d9ba9eea47dede97
+--abi
./contract-abi.json
+transfer 0xf8f8b6283d7fa5b672b530cbb84fcccb4ff8dc40f8176ef4544ddb1f1952ad07
--contracts
0xf8f8b6283d7fa5b672b530cbb84fcccb4ff8dc40f8176ef4544ddb1f1952ad07
+» forc call 0x0dcba78d7b09a1f77353f51367afd8b8ab94b5b2bb6c9437d9ba9eea47dede97
+--abi
./contract-abi.json
+add 1 2
--mode
simulate
+» forc call 0x0dcba78d7b09a1f77353f51367afd8b8ab94b5b2bb6c9437d9ba9eea47dede97
+--node-url
"http://127.0.0.1:4000/v1/graphql"
+--signing-key
0x...
+--abi
./contract-abi.json
+add 1 2
--mode
dry-run
+» forc call 0x0dcba78d7b09a1f77353f51367afd8b8ab94b5b2bb6c9437d9ba9eea47dede97
+--testnet
--wallet
--abi
./contract-abi.json
+add 1 2
--mode
live
+» forc call 0x0dcba78d7b09a1f77353f51367afd8b8ab94b5b2bb6c9437d9ba9eea47dede97
+--abi
./contract-abi.json
+transfer 0xf8f8b6283d7fa5b672b530cbb84fcccb4ff8dc40f8176ef4544ddb1f1952ad07
--mode
live
+--amount
100
+» forc call 0x0dcba78d7b09a1f77353f51367afd8b8ab94b5b2bb6c9437d9ba9eea47dede97
+--abi
./contract-abi.json
+transfer 0xf8f8b6283d7fa5b672b530cbb84fcccb4ff8dc40f8176ef4544ddb1f1952ad07
--amount
100
+--asset-id
0x0087675439e10a8351b1d5e4cf9d0ea6da77675623ff6b16470b5e3c58998423
+--live
Usage: forc deploy [OPTIONS] [SIGNING_KEY]
+Arguments: +[SIGNING_KEY] +Set the key to be used for signing
+Options:
+-p, --path <PATH>
Path to the project.
+If not specified, current working directory will be used.
+--offline
Offline mode.
+Prevents Forc from using the network when managing dependencies. Meaning it will only try to use previously downloaded dependencies.
+-t, --terse
Terse mode.
+Limited warning and error output.
+--output-directory <OUTPUT_DIRECTORY>
The directory in which Forc output artifacts are placed.
+By default, this is <project-root>/out.
--locked
Requires that the Forc.lock file is up-to-date.
+If the lock file is missing, or it needs to be updated, Forc will exit with an error.
+--ipfs-node <IPFS_NODE>
The IPFS node to use for fetching IPFS sources.
+[possible values: PUBLIC, LOCAL, <GATEWAY_URL>]
+--json-abi
Minify JSON ABI files.
+By default the JSON for ABIs is formatted for human readability. By using this option JSON output will be "minified", i.e. all on one line without whitespace.
+--json-storage-slots
Minify JSON storage slot files.
+By default the JSON for initial storage slots is formatted for human readability. By using this option JSON output will be "minified", i.e. all on one line without whitespace.
+--ast
Print the generated Sway AST (Abstract Syntax Tree)
+--dca-graph <DCA_GRAPH>
Print the computed Sway DCA (Dead Code Analysis) graph.
+DCA graph is printed to the specified path. If specified '' graph is printed to the stdout.
+--dca-graph-url-format <DCA_GRAPH_URL_FORMAT>
URL format to be used in the generated DCA graph .dot file.
+Variables {path}, {line}, and {col} can be used in the provided format. +An example for vscode would be: +"vscode://file/{path}:{line}:{col}"
+--asm <ASM>..>
Print the generated ASM (assembler).
+Values that can be combined:
+[possible values: virtual, allocated, abstract, final, all]
+--bytecode
Print the bytecode.
+This is the final output of the compiler.
+--ir <IR>..>
Print the generated Sway IR (Intermediate Representation).
+Values that can be combined:
+[possible values: initial, final, all, modified, inline, simplify-cfg, sroa, dce, fn-dce, fn-dedup-release, fn-dedup-debug, mem2reg, memcpyopt, const-folding, arg-demotion, const-demotion, ret-demotion, misc-demotion]
+--time-phases
Output the time elapsed over each part of the compilation process
+--profile
Profile the compilation process
+--reverse-order
Output build errors and warnings in reverse order
+--metrics-outfile <METRICS_OUTFILE>
Output compilation metrics into the specified file
+--gas-price <PRICE>
Gas price for the transaction
+--script-gas-limit <SCRIPT_GAS_LIMIT>
Gas limit for the transaction
+--max-fee <MAX_FEE>
Max fee for the transaction
+--tip <TIP>
The tip for the transaction
+--maturity <MATURITY>
Block height until which tx cannot be included
+[default: 0]
+--node-url <NODE_URL>
The URL of the Fuel node to which we're submitting the transaction. If unspecified, checks the manifest's network table, then falls back to http://127.0.0.1:4000
You can also use --target, --devnet, --testnet, or --mainnet to specify the Fuel node.
[env: FUEL_NODE_URL=]
+--target <TARGET>
Preset configurations for using a specific target.
+You can also use --node-url, --devnet, --testnet, or --mainnet to specify the Fuel node.
Possible values are: [local, testnet, mainnet]
+--mainnet
Use preset configuration for mainnet.
+You can also use --node-url, --target, or --testnet to specify the Fuel node.
--testnet
Use preset configuration for testnet.
+You can also use --node-url, --target, or --mainnet to specify the Fuel node.
--devnet
Use preset configuration for devnet.
+You can also use --node-url, --target, or --testnet to specify the Fuel node.
--salt <SALT>
Optional 256-bit hexadecimal literal(s) to redeploy contracts.
+For a single contract, use --salt <SALT>, eg.: forc deploy --salt 0x0000000000000000000000000000000000000000000000000000000000000001
For a workspace with multiple contracts, use --salt <CONTRACT_NAME>:<SALT> to specify a salt for each contract, eg.:
forc deploy --salt contract_a:0x0000000000000000000000000000000000000000000000000000000000000001 --salt contract_b:0x0000000000000000000000000000000000000000000000000000000000000002
+--default-salt
Generate a default salt (0x0000000000000000000000000000000000000000000000000000000000000000) for the contract. Useful for CI, to create reproducible deployments
+-o, --output-bin <BIN_FILE>
Create a binary file at the provided path representing the final bytecode
+-g, --output-debug <DEBUG_FILE>
Create a file at the provided path containing debug information.
+If the file extension is .json, JSON format is used. Otherwise, an .elf file containing DWARF format is emitted.
+--build-profile <BUILD_PROFILE>
The name of the build profile to use
+[default: release]
+--default-signer
Sign the transaction with default signer that is pre-funded by fuel-core. Useful for testing against local node
+--unsigned
Deprecated in favor of --default-signer
--submit-only
Submit the deployment transaction(s) without waiting for execution to complete
+--manual-signing
Sign the deployment transaction manually
+--override-storage-slots <JSON_FILE_PATH>
Override storage slot initialization.
+By default, storage slots are initialized with the values defined in the storage block in +the contract. You can override the initialization by providing the file path to a JSON file +containing the overridden values.
+The file format and key values should match the compiler-generated *-storage_slots.json file in the output
+directory of the compiled contract.
Example: forc deploy --override-storage-slots my_override.json
my_override.json: +[ +{ +"key": "<key from out/debug/storage_slots.json>", +"value": "0000000000000000000000000000000000000000000000000000000000000001" +} +]
+--experimental <EXPERIMENTAL>
Comma separated list of all experimental features that will be enabled
+[possible values: new_encoding, storage_domains, references, error_type, partial_eq]
+--no-experimental <NO_EXPERIMENTAL>
Comma separated list of all experimental features that will be disabled
+[possible values: new_encoding, storage_domains, references, error_type, partial_eq]
+--aws-kms-signer <AWS_KMS_SIGNER>
AWS KMS signer arn. If present forc-deploy will automatically use AWS KMS signer instead of forc-wallet
+-h, --help
Print help (see a summary with '-h')
+-V, --version
Print version
+EXAMPLES:
+forc deploy bc09bfa7a11a04ce42b0a5abf04fd437387ee49bf4561d575177e2946468b408
+forc deploy bc09bfa7a11a04ce42b0a5abf04fd437387ee49bf4561d575177e2946468b408 --path {path}
+forc deploy --node-url https://testnet.fuel.network/graphql
+You can use forc deploy, which triggers a contract deployment transaction and sends it to a running node.
Alternatively, you can deploy your Sway contract programmatically using fuels-rs, our Rust SDK.
+You can find an example within our fuels-rs book.
+ +Usage: forc run [OPTIONS] [SIGNING_KEY]
+Arguments: +[SIGNING_KEY] +Set the key to be used for signing
+Options:
+-p, --path <PATH>
Path to the project.
+If not specified, current working directory will be used.
+--offline
Offline mode.
+Prevents Forc from using the network when managing dependencies. Meaning it will only try to use previously downloaded dependencies.
+-t, --terse
Terse mode.
+Limited warning and error output.
+--output-directory <OUTPUT_DIRECTORY>
The directory in which Forc output artifacts are placed.
+By default, this is <project-root>/out.
--locked
Requires that the Forc.lock file is up-to-date.
+If the lock file is missing, or it needs to be updated, Forc will exit with an error.
+--ipfs-node <IPFS_NODE>
The IPFS node to use for fetching IPFS sources.
+[possible values: PUBLIC, LOCAL, <GATEWAY_URL>]
+--json-abi
Minify JSON ABI files.
+By default the JSON for ABIs is formatted for human readability. By using this option JSON output will be "minified", i.e. all on one line without whitespace.
+--json-storage-slots
Minify JSON storage slot files.
+By default the JSON for initial storage slots is formatted for human readability. By using this option JSON output will be "minified", i.e. all on one line without whitespace.
+--ast
Print the generated Sway AST (Abstract Syntax Tree)
+--dca-graph <DCA_GRAPH>
Print the computed Sway DCA (Dead Code Analysis) graph.
+DCA graph is printed to the specified path. If specified '' graph is printed to the stdout.
+--dca-graph-url-format <DCA_GRAPH_URL_FORMAT>
URL format to be used in the generated DCA graph .dot file.
+Variables {path}, {line}, and {col} can be used in the provided format. +An example for vscode would be: +"vscode://file/{path}:{line}:{col}"
+--asm <ASM>..>
Print the generated ASM (assembler).
+Values that can be combined:
+[possible values: virtual, allocated, abstract, final, all]
+--bytecode
Print the bytecode.
+This is the final output of the compiler.
+--ir <IR>..>
Print the generated Sway IR (Intermediate Representation).
+Values that can be combined:
+[possible values: initial, final, all, modified, inline, simplify-cfg, sroa, dce, fn-dce, fn-dedup-release, fn-dedup-debug, mem2reg, memcpyopt, const-folding, arg-demotion, const-demotion, ret-demotion, misc-demotion]
+--time-phases
Output the time elapsed over each part of the compilation process
+--profile
Profile the compilation process
+--reverse-order
Output build errors and warnings in reverse order
+--metrics-outfile <METRICS_OUTFILE>
Output compilation metrics into the specified file
+--gas-price <PRICE>
Gas price for the transaction
+--script-gas-limit <SCRIPT_GAS_LIMIT>
Gas limit for the transaction
+--max-fee <MAX_FEE>
Max fee for the transaction
+--tip <TIP>
The tip for the transaction
+--maturity <MATURITY>
Block height until which tx cannot be included
+[default: 0]
+-o, --output-bin <BIN_FILE>
Create a binary file at the provided path representing the final bytecode
+-g, --output-debug <DEBUG_FILE>
Create a file at the provided path containing debug information.
+If the file extension is .json, JSON format is used. Otherwise, an .elf file containing DWARF format is emitted.
+--build-profile <BUILD_PROFILE>
The name of the build profile to use
+[default: debug]
+--release
Use the release build profile.
+The release profile can be customized in the manifest file.
+--error-on-warnings
Treat warnings as errors
+--node-url <NODE_URL>
The URL of the Fuel node to which we're submitting the transaction. If unspecified, checks the manifest's network table, then falls back to http://127.0.0.1:4000
You can also use --target, --devnet, --testnet, or --mainnet to specify the Fuel node.
[env: FUEL_NODE_URL=]
+--target <TARGET>
Preset configurations for using a specific target.
+You can also use --node-url, --devnet, --testnet, or --mainnet to specify the Fuel node.
Possible values are: [local, testnet, mainnet]
+--mainnet
Use preset configuration for mainnet.
+You can also use --node-url, --target, or --testnet to specify the Fuel node.
--testnet
Use preset configuration for testnet.
+You can also use --node-url, --target, or --mainnet to specify the Fuel node.
--devnet
Use preset configuration for devnet.
+You can also use --node-url, --target, or --testnet to specify the Fuel node.
-d, --data <DATA>
Hex string of data to input to script
+--dry-run
Only craft transaction and print it out
+-r, --pretty-print
Pretty-print the outputs from the node
+--contract <CONTRACT>
32-byte contract ID that will be called during the transaction
+--simulate
Execute the transaction and return the final mutated transaction along with receipts (which includes whether the transaction reverted or not). The transaction is not inserted in the node's view of the blockchain, (i.e. it does not affect the chain state)
+--default-signer
Sign the transaction with default signer that is pre-funded by fuel-core. Useful for testing against local node
+--unsigned
Deprecated in favor of --default-signer
--args <ARGS>
Arguments to pass into main function with forc run
+--experimental <EXPERIMENTAL>
Comma separated list of all experimental features that will be enabled
+[possible values: new_encoding, storage_domains, references, error_type, partial_eq]
+--no-experimental <NO_EXPERIMENTAL>
Comma separated list of all experimental features that will be disabled
+[possible values: new_encoding, storage_domains, references, error_type, partial_eq]
+-h, --help
Print help (see a summary with '-h')
+-V, --version
Print version
+ +Usage: forc-submit [OPTIONS] <TX_PATH>
+Arguments:
+<TX_PATH> +Path to the Transaction that is to be submitted to the Fuel node.
+Paths to files ending with .json will be deserialized from JSON. Paths to files ending with .bin will be deserialized from bytes using the fuel_tx::Transaction::try_from_bytes constructor.
Options:
+--node-url <NODE_URL>
The URL of the Fuel node to which we're submitting the transaction. If unspecified, checks the manifest's network table, then falls back to http://127.0.0.1:4000
You can also use --target, --devnet, --testnet, or --mainnet to specify the Fuel node.
[env: FUEL_NODE_URL=]
+--target <TARGET>
Preset configurations for using a specific target.
+You can also use --node-url, --devnet, --testnet, or --mainnet to specify the Fuel node.
Possible values are: [local, testnet, mainnet]
+--mainnet
Use preset configuration for mainnet.
+You can also use --node-url, --target, or --testnet to specify the Fuel node.
--testnet
Use preset configuration for testnet.
+You can also use --node-url, --target, or --mainnet to specify the Fuel node.
--devnet
Use preset configuration for devnet.
+You can also use --node-url, --target, or --testnet to specify the Fuel node.
--await <AWAIT>
Whether or not to await confirmation that the transaction has been committed.
+When true, await commitment and output the transaction status. When false, do not await confirmation and simply output the transaction ID.
[default: true] +[possible values: true, false]
+--tx-status-json <JSON>
Output the resulting transaction status as JSON rather than the default output
+[default: false] +[possible values: true, false]
+-h, --help
Print help (see a summary with '-h')
+-V, --version
Print version
+EXAMPLES:
+forc submit {path}/mint.json
+forc submit {path}/mint.json --await true
+forc submit {path}/mint.json --tx-status-json true
+forc submit {path}/mint.json --testnet
+forc submit {path}/mint.json --target local
+ +The forc plugin for interacting with a Fuel node.
+Since transactions are going to require some gas, you need to sign them with an account that has enough coins to pay for them.
+We offer multiple ways to sign the transaction:
+forc-client which integrates with our CLI wallet, forc-wallet.forc-wallet to manually sign transactions, and copy the signed transaction back to forc-client.The easiest and recommended way to interact with deployed networks such as our testnets is option 1, using forc-client to sign your transactions which reads your default forc-wallet vault. For interacting with local node, we recommend using the second option, which leads forc-client to sign transactions with the private key that comes pre-funded in local environments.
If you've used forc-wallet before, you'll already have a secure, password-protected vault holding your private key written to your file-system. forc-client is compatible with forc-wallet such that it can read that vault by asking you your password and use your account to sign transactions.
Example:
+> forc deploy
+
+ Building /Users/yourname/test-projects/test-contract
+ Finished release [optimized + fuel] target(s) in 11.39s
+ Confirming transactions [deploy impl-contract]
+ Network: https://testnet.fuel.network
+ Wallet: /Users/yourname/.fuel/wallets/.wallet
+✔ Wallet password · ********
+? Wallet account ›
+❯ [0] fuel12pls73y9hnqdqthvduy2x44x48zt8s50pkerf32kq26f2afeqdwq6rj9ar - 0.002197245 ETH
+ [1] fuel1vzrm6kw9s3tv85gl25lpptsxrdguyzfhq6c8rk07tr6ft5g45nwqqh0uty - 0.001963631 ETH
+? Do you agree to sign 1 transaction? (y/n) › yes
+ Finished deploying impl-contract https://app.fuel.network/contract/0x94b712901f04332682d14c998a5fc5a078ed15321438f46d58d0383200cde43d
+ Deployed in block https://app.fuel.network/block/5958351
+As it can be seen from the example, forc-client asks for your password to decrypt the forc-wallet vault, and list your accounts so that you can select the one you want to fund the transaction with.
If you are not interacting with a deployed network, such as testnets, your local fuel-core environment can be structured such that it funds an account by default. Using --default-signer flag with forc-client binaries (run, deploy) will instruct forc-client to sign transactions with this pre-funded account. This makes it a useful command while working against a local node.
Example:
+> forc deploy --default-signer
+
+ Building /Users/test/test-projects/test-contract
+ Finished release [optimized + fuel] target(s) in 11.40s
+ Confirming transactions [deploy impl-contract]
+ Network: http://127.0.0.1:4000
+ Finished deploying impl-contract 0xf9fb08ef18ce226954270d6d4f67677d484b8782a5892b3d436572b405407544
+ Deployed in block 00000001
+This option is for creating the transaction first, signing it manually, and supplying the signed transaction back to forc-client. Since it requires multiple steps, it is more error-prone and not recommended for general use cases. Also this will be deprecated soon.
+forc deploy or forc run. To do so simply run forc deploy --manual-sign or forc run --manual-sign with your desired parameters. For a list of parameters please refer to the forc-deploy or forc-run section of the book. Once you run either command you will be asked the address of the wallet you are going to be signing with. After the address is given the transaction will be generated and you will be given a transaction ID. At this point CLI will actively wait for you to insert the signature.forc wallet sign --account <account_index> tx-id <transaction_id>. This will generate a signature.forc-deploy (or forc-run). Once the signature is provided, the signed transaction will be submitted.forc-walletaccounts command.forc wallet accounts
+account command.forc wallet account <account_index>
+++If you want to sign the transaction generated by
+forc-deployorforc-runwith an account funded by default once you start your local node, you can pass--default-signerto them. Please note that this will only work against your local node.+forc-deploy --default-signer ++forc-run --default-signer +
By default --default-signer flag would sign your transactions with the following private-key:
0xde97d8624a438121b86a1956544bd72ed68cd69f2c99555b08b1e8c51ffd511c
+By default, local is used for the target network. To interact with the latest testnet, use the --testnet flag. When this flag is passed, transactions created by forc-deploy will be sent to the latest testnet:
forc-deploy --testnet
+The same can be done to target mainnet:
+forc-deploy --mainnet
+It is also possible to pass the exact node URL while using forc-deploy or forc-run which can be done using --node-url flag:
forc-deploy --node-url https://mainnet.fuel.network
+Another alternative is the --target option, which provides useful aliases to all targets. For example if you want to deploy to testnet you can use:
forc-deploy --target testnet
+Since deploying and running projects on the testnet cost gas, you will need coins to pay for them. You can get some using the testnet faucet.
+For delayed transactions, you can use the --submit-only flag. This flag allows you to submit the transaction without waiting for its finalization.
One use case for this is multisig transactions, where a deployment transaction may stay in a pending state while waiting for all signatures.
+forc-deploy --submit-only
+forc-deploy saves the details of each deployment in the out/deployments folder within the project's root directory. Below is an example of a deployment artifact:
{
+ "transaction_id": "0xec27bb7a4c8a3b8af98070666cf4e6ea22ca4b9950a0862334a1830520012f5d",
+ "salt": "0x9e35d1d5ef5724f29e649a3465033f5397d3ebb973c40a1d76bb35c253f0dec7",
+ "network_endpoint": "http://127.0.0.1:4000",
+ "chain_id": 0,
+ "contract_id": "0x767eeaa7af2621e637f9785552620e175d4422b17d4cf0d76335c38808608a7b",
+ "deployment_size": 68,
+ "deployed_block_id": "0x915c6f372252be6bc54bd70df6362dae9bf750ba652bf5582d9b31c7023ca6cf"
+}
+forc-deploy supports deploying proxy contracts automatically if it is enabled in the Forc.toml of the contract.
[project]
+name = "test_contract"
+authors = ["Fuel Labs <contact@fuel.sh>"]
+entry = "main.sw"
+license = "Apache-2.0"
+implicit-std = false
+
+[proxy]
+enabled = true
+If there is no address field present under the proxy table, like the example above, forc will automatically create a proxy contract based on the SRC-14 implementation from sway-standards. After generating and deploying the proxy contract, the target is set to the current contract, and the owner of the proxy is set to the account that is signing the transaction for deployment.
This means that if you simply enable proxy in the Forc.toml, forc will automatically deploy a proxy contract for you and you do not need to do anything manually aside from signing the deployment transactions for the proxy contract. After deploying the proxy contract, the address is added into the address field of the proxy table.
If you want to update the target of an SRC-14 compliant proxy contract rather than deploying a new one, simply add its address in the address field, like the following example:
[project]
+name = "test_contract"
+authors = ["Fuel Labs <contact@fuel.sh>"]
+entry = "main.sw"
+license = "Apache-2.0"
+implicit-std = false
+
+[proxy]
+enabled = true
+address = "0xd8c4b07a0d1be57b228f4c18ba7bca0c8655eb6e9d695f14080f2cf4fc7cd946" # example proxy contract address
+If an address is present, forc calls into that contract to update its target instead of deploying a new contract. Since a new proxy deployment adds its own address into the Forc.toml automatically, you can simply enable the proxy once and after the initial deployment, forc will keep updating the target accordingly for each new deployment of the same contract.
For contracts over the maximum contract size limit (currently 100kB) defined by the network, forc-deploy will split the contract into chunks and deploy the contract with multiple transactions using the Rust SDK's loader contract functionality. Chunks that have already been deployed will be reused on subsequent deployments.
forc deploy now supports deploying scripts and predicates in addition to contracts. These are deployed as blobs with generated loaders for efficiency.
Scripts and predicates are deployed automatically when you run forc deploy on a project that contains them. The deployment process differs slightly from contract deployment:
After deployment, you'll find new files in your project's output directory:
+<script_name>-loader.bin<predicate_name>-loader.bin and <predicate_name>-loader-rootThe loader files contain the bytecode necessary to load and execute your script or predicate from the deployed blob.
+This new deployment method allows for more efficient storage and execution of scripts and predicates on the Fuel network.
+Note: Contracts are still deployed directly, not as blobs given that the contract size is under the maximum contract size limit defined by network (currently 100kB).
Usage: forc-crypto
Commands: +keccak256 Hashes the argument or file with this algorithm +sha256 Hashes the argument or file with this algorithm +address Converts an address to another format +get-public-key Get the public key from a message and its signature +new-key Creates a new key for use with fuel-core +parse-secret Parses a private key to view the associated public key +vanity Generate a vanity address +help Print this message or the help of the given subcommand(s)
+Options:
+-h, --help
Print help
+-V, --version
Print version
+EXAMPLES:
+forc crypto sha256 test
+forc crypto keccak256 test
+forc crypto sha256 {file}
+forc crypto keccak256 {file}
+forc crypto address fuel12e0xwx34nfp7jrzvn9mp5qkac3yvp7h8fx37ghl7klf82vv2wkys6wd523
+forc crypto new-key
+forc crypto new-key -k peering
+forc crypto new-key -k block-production
+forc crypto parse-secret "f5204427d0ab9a311266c96a377f7c329cb8a41b9088225b6fcf40eefb423e28"
+forc crypto parse-secret -k peering "f5204427d0ab9a311266c96a377f7c329cb8a41b9088225b6fcf40eefb423e28"
+forc crypto get-public-key
+0x1eff08081394b72239a0cf7ff6b499213dcb7a338bedbd75d072d504588ef27a1f74d5ceb2f111ec02ede097fb09ed00aa9867922ed39299dae0b1afc0fa8661
+"This is a message that is signed"
forc crypto vanity --starts-with "aaa"
+forc crypto vanity --ends-with "aaa"
+forc crypto vanity --starts-with "00" --ends-with "ff"
+forc crypto vanity --regex "^00.*ff$"
+ +Usage: forc-debug [OPTIONS] [API_URL]
+Arguments: +[API_URL] The URL of the Fuel Client GraphQL API [default: http://127.0.0.1:4000/graphql]
+Options:
+-s, --serve
Start the DAP server
+-h, --help
Print help
+-V, --version
Print version
+ +Usage: forc-doc [OPTIONS]
+Options:
+-p, --path <PATH>
Path to the project.
+If not specified, current working directory will be used.
+--document-private-items
Include non-public items in the documentation
+--open
Open the docs in a browser after building them
+--offline
Offline mode, prevents Forc from using the network when managing dependencies. Meaning it +will only try to use previously downloaded dependencies
+--locked
Requires that the Forc.lock file is up-to-date. If the lock file is missing, or it needs +to be updated, Forc will exit with an error
+--no-deps
Do not build documentation for dependencies
+--ipfs-node <IPFS_NODE>
The IPFS Node to use for fetching IPFS sources.
+Possible values: PUBLIC, LOCAL, <GATEWAY_URL>
+--experimental <EXPERIMENTAL>
Comma separated list of all experimental features that will be enabled
+[possible values: new_encoding, storage_domains, references, error_type, partial_eq]
+--no-experimental <NO_EXPERIMENTAL>
Comma separated list of all experimental features that will be disabled
+[possible values: new_encoding, storage_domains, references, error_type, partial_eq]
+-s, --silent
Silent mode. Don't output any warnings or errors to the command line
+-h, --help
Print help (see a summary with '-h')
+-V, --version
Print version
+EXAMPLES:
+forc doc
+forc doc --open
+forc doc --path {path}
+forc doc --document-private-items
+forc doc --offline
+ +Forc plugin for running the Fuel Block Explorer.
+forc-explore [OPTIONS] [SUBCOMMAND]
+-h, --help
Print help information
+-p, --port <PORT>
The port number at which the explorer will run on localhost [default: 3030]
+-V, --version
Print version information
+clean
Cleans up any existing state associated with the fuel block explorer
+help
Print this message or the help of the given subcommand(s)
+ +Usage: forc-fmt [OPTIONS]
+Options:
+-c, --check
Run in 'check' mode.
+0 if input is formatted correctly. - Exits with 1 and prints a diff if formatting is required.-p, --path <PATH>
Path to the project.
+If not specified, current working directory will be used.
+-f, --file <FILE>
Formats a single .sw file with the default settings. If not specified, current working directory will be formatted using a Forc.toml configuration
+-h, --help
Print help (see a summary with '-h')
+-V, --version
Print version
+EXAMPLES:
+forc fmt --check
+forc fmt -c
+forc fmt --file {path}/src/main.sw
+forc fmt -f {path}/src/main.sw
+forc fmt --path {path}
+forc fmt -p {path}
+ +Usage: forc-lsp
+Options:
+-h, --help
Print help
+-V, --version
Print version
+ +Usage: forc-migrate
Commands: +show Show the upcoming breaking change features and their migration steps +check Check the project for code that needs to be migrated +run Migrate the project +help Print this message or the help of the given subcommand(s)
+Options:
+-h, --help
Print help
+-V, --version
Print version
+Examples:
+forc migrate show
+forc migrate check
+forc migrate check --path {path}
+forc migrate run
+forc migrate run --path {path}
+forc migrate run --offline
+forc-migrate guides you through breaking changes between Sway versions. It fully or semiautomatically adapts your code, making it compatible with the next breaking change version of Sway.
forc-migrate migrates the code to the next breaking change version of Sway. That means, if you want to migrate to, e.g., Sway v0.67.0, you will need to use the latest v0.66.x version of the forc-migrate.
For example, let's say that your Sway project is on version v0.66.1, and that the latest v0.66 version is v0.66.42. You should first update your Fuel toolchain to version v0.66.42 of forc, and compile your project with that version:
fuelup component add forc@0.66.42
+Sway guarantees that all the versions with the same minor version, 0.66 in the above example, are compatible. That means that the latest patch version, 0.66.42 in the example, will correctly compile your project.
+Once you've installed the latest non-breaking version of forc-migrate, use the show command to make yourself familiar with the upcoming breaking changes:
forc migrate show
+A typical output of the show command will look like this:
Breaking change features:
+ - storage_domains (https://github.com/FuelLabs/sway/issues/6701)
+ - references (https://github.com/FuelLabs/sway/issues/5063)
+
+Migration steps (1 manual and 1 semiautomatic):
+storage_domains
+ [M] Review explicitly defined slot keys in storage declarations (`in` keywords)
+
+references
+ [S] Replace `ref mut` function parameters with `&mut`
+
+Experimental feature flags:
+- for Forc.toml: experimental = { storage_domains = true, references = true }
+- for CLI: --experimental storage_domains,references
+The output will contain:
+storage_domains and references in this example,The migration steps can be manual, semiautomatic, or fully automatic. They are marked in the output with [M], [S], and [A], respectively.
The show command will also provide experimental feature flags that will be needed during the migration, as explained in the next chapter.
Let's assume that we want to migrate a Sway project called my_project that depends on std and a third_party_lib.
First, we will go to the folder that contains my_project, e.g.: cd my_project. All of the upcoming CLI commands assume that we are running the forc-migrate tool within the my_project folder.
Before migrating the code, make sure that the project builds without any errors by running:
+forc build
+Next, let's check the project first. The check command will dry-run the migration steps. It will not do any changes in code, but will provide a detailed information of all the places in code that need to be either reviewed or changed during the migration process. The check command will also provide a rough time estimate for the migration.
forc migrate check
+The output of the check command will end in a summary of the migration effort, containing:
Migration effort:
+
+storage_domains
+ [M] Review explicitly defined slot keys in storage declarations (`in` keywords)
+ Occurrences: 3 Migration effort (hh::mm): ~00:06
+
+references
+ [S] Replace `ref mut` function parameters with `&mut`
+ Occurrences: 18 Migration effort (hh::mm): ~01:30
+
+Total migration effort (hh::mm): ~01:36
+Before the summary, instructions will be shown for each migration step. A typical instruction output for a single migration step will contain:
+info: [references] Replace `ref mut` function parameters with `&mut`
+ --> my_project/src/main.sw:30:51
+ |
+...
+30 | fn ref_mut_fn(ref mut x: u64) {}
+ | ---------
+...
+35 | fn another_ref_mut_fn(ref mut arg: S) {}
+ | -----------
+ |
+ = help: Migration will replace `ref mut` function parameters with `&mut`.
+ = help: E.g., `ref mut x: u64` will become `x: &mut u64`.
+ = help:
+ = help: After the migration, you will still need to:
+ = help: - change function callers, by adding `&mut` to passed parameters.
+ = help: - change function bodies, by dereferencing (`*`) parameters where needed.
+ = help:
+ = help: For a detailed migration guide see: https://github.com/FuelLabs/sway/issues/5063
+Before running the migrations on the project itself, first update the project dependencies to the versions that use the next Sway breaking change version.
+In our example, the my_project's Forc.toml file will have the [dependencies] section similar to this one:
[dependencies]
+std = { git = "https://github.com/FuelLabs/sway", tag = "v0.66.1" }
+third_party_lib = { git = "https://github.com/ThirdParty/swaylib", tag = "v1.0.0" }
+Assuming that the third_party_lib version compatible with Sway v0.67.0 is the version v2.0.0 we will end up in the following changes:
[dependencies]
+# Changed v0.66.1 -> v0.67.0
+std = { git = "https://github.com/FuelLabs/sway", tag = "v0.67.0" }
+# Changed v1.0.0 -> v2.0.0
+third_party_lib = { git = "https://github.com/ThirdParty/swaylib", tag = "v2.0.0" }
+Run forc build to make sure that the project still compiles. At this point, it is very likely that you will need to compile the project with the experimental features turned on. The reason is the likelihood that either the new std or the third_party_lib uses the new Sway features.
To compile the project with experimental features, you can take the feature flags from the forc migrate show output, and place them either in the [build-profile] section of the projects Forc.toml file, or pass them to forc build via the command line.
Experimental feature flags:
+- for Forc.toml: experimental = { storage_domains = true, references = true }
+- for CLI: --experimental storage_domains,references
+In the remaining part of this tutorial, we will be passing the feature flags via the command line. E.g.:
+forc build --experimental storage_domains,references
+Once the my_project successfully builds with updated dependencies, we can run the migration steps on it. E.g.:
forc migrate run --experimental storage_domains,references
+The run command will execute the migration steps, and guide you through the migration process. For each migration step, the output of the step can be one of the following:
| Step output | Meaning |
|---|---|
| Checked | The step is executed and does not require any changes in code. No action needed. |
| Review | The step suggests a manual code review. |
| Changing | The step is automatically changing the code. There might be additional manual actions needed. |
At the end of the run, the migration will either guide you to:
Continue the migration process by performing the manual actions and re-running the forc migrate run afterwards,Finished. At this point, your project will be compatible with the next breaking change version of Sway.forc migrate, same like forc fmt, does its best to preserve the positions of comments in the modified code. This is a challenging task, especially if migration steps remove parts of the code. It is a good practice to always diff the changes done within migration steps and check if the comments are placed where expected.
To migrate a workspace, you will need to migrate each workspace member separately, following the above procedure. The projects should be migrated in order of their dependencies.
+++Note: There is a know limitation when running
+forc migrateon projects that are listed as workspace members.forc migratewill run, but possibly not find all the occurrences in code that need to be migrated. Therefore, before running migrations on projects that are workspace members, remove them temporarily from the the list of workspacemembers.
There are some additional manual steps that might be needed after the migration.
+E.g., if tests use hardcoded contract IDs, those need to be changed, because the new version of Sway will, very likely, produce different bytecode.
+ +Plugins can be used to extend forc with new commands that go beyond the native commands mentioned in the previous chapter. While the Fuel ecosystem provides a few commonly useful plugins (forc-fmt, forc-client, forc-lsp, forc-explore), anyone can write their own!
Let's install a plugin, forc-explore, and see what's underneath the plugin:
cargo install forc-explore
+Check that we have installed forc-explore:
$ forc plugins
+Installed Plugins:
+forc-explore
+forc-explore runs the Fuel Network Explorer, which you can run and check out for yourself:
$ forc explore
+Fuel Network Explorer 0.1.1
+Running server on http://127.0.0.1:3030
+Server::run{addr=127.0.0.1:3030}: listening on http://127.0.0.1:3030
+You can visit http://127.0.0.1:3030 to check out the network explorer!
+Note that some plugin crates can also provide more than one command. For example, installing the forc-client plugin provides the forc deploy and forc run commands. This is achieved by specifying multiple [[bin]] targets within the forc-client manifest.
We encourage anyone to write and publish their own forc plugin to enhance their development experience.
Your plugin must be named in the format forc-<MY_PLUGIN> and you may use the above template as a starting point. You can use clap and add more subcommands, options and configurations to suit your plugin's needs.
A workspace is a collection of one or more packages, namely workspace members, that are managed together.
+The key points for workspaces are:
+forc commands available for a single package can also be used for a workspace, like forc build or forc deploy.Forc.lock file which resides in the root directory of the workspace.Workspace manifests are declared within Forc.toml files and support the following fields:
An empty workspace can be created with forc new --workspace or forc init --workspace.
members fieldThe members field defines which packages are members of the workspace:
[workspace]
+members = ["member1", "path/to/member2"]
+The members field accepts entries to be given in relative path with respect to the workspace root.
+Packages that are located within a workspace directory but are not contained within the members set are ignored.
[patch] sectionThe [patch] section can be used to override any dependency in the workspace dependency graph. The usage is the same with package level [patch] section and details can be seen here.
It is not allowed to declare patch table in member of a workspace if the workspace manifest file contains a patch table.
+Example:
+[workspace]
+members = ["member1", "path/to/member2"]
+
+
+[patch.'https://github.com/fuellabs/sway']
+std = { git = "https://github.com/fuellabs/sway", branch = "test" }
+In the above example each occurrence of std as a dependency in the workspace will be changed with std from test branch of sway repo.
forc commands that support workspacesforc build - Builds an entire workspace.forc deploy - Builds and deploys all deployable members (i.e, contracts) of the workspace in the correct order.forc run - Builds and runs all scripts of the workspace.forc check - Checks all members of the workspace.forc update - Checks and updates workspace level Forc.lock file that is shared between workspace members.forc clean - Cleans all output artifacts for each member of the workspace.forc fmt - Formats all members of a workspace.Welcome to the Sway programming language book 🌴.
+Q: Hi! What is Sway?
+Sway is a domain-specific programming language for implementing smart contracts on blockchain platforms, most notably for the Fuel Virtual Machine (Fuel VM).
+Heavily inspired by Rust's approach to systems programming, Sway aims to bring modern programming language features and tooling to smart contract development whilst retaining performance, fine grained control and making extensive use of static analysis to prevent common security issues.
+Q: What does "domain-specific" mean?
+Sway is specifically made to be used within a blockchain environment, which behaves very differently than traditional computers. +This domain specific design permits it to make the right decisions about trade-offs at every level of the stack, enabling you to write fast, secure and cost effective smart contracts with features suited to your specific needs.
+Q: Why not use Solidity?
+Solidity is a venerable pioneer but it suffers from being tied to a lot of the historical quirks of the EVM. +It lacks common features programmers have come to expect, has a relatively inexpressive type system, and it lacks a unified tooling ecosystem.
+In Sway, we let you design smart contracts with a full modern box of tools. +You get a fully featured language with generics, algebraic types and trait based polymorphism. +You also get an integrated, unified and easy to use toolchain with code completion LSP server, formatter, documentation generation and everything you need to run and deploy your contracts so that nothing comes between you and implementing what you want.
+Our expressive type system allows you to catch semantic mistakes, we provide good defaults and we do extensive static analysis checks (such as enforcing the Checks, Effects, Interactions pattern) so that you can make sure you write secure and correct code at compile time.
+Q: Why not use Rust?
+Whilst Rust is a great systems programming language (and Sway itself is written in Rust), it isn't suited for smart contract development.
+Rust shines because it can use zero-cost abstractions and its sophisticated borrow-checker memory model to achieve impressive runtime performance for complex programs without a garbage collector.
+On a blockchain, cost of execution and deployment is the scarce resource. +Memory usage is low and execution time is short. +This makes complex memory management in general much too expensive to be worthwhile and Rust's borrow checker a burden with no upside.
+General purpose programming languages in general are ill suited to this environment because their design has to assume execution on a general-purpose computing environment.
+Sway attempts to bring all the other advantages of Rust, including its modern type system, approach to safety and good defaults to smart contract developers by providing familiar syntax and features adapted to the specific needs of the blockchain environment.
+Q: I don't know Rust or Solidity. Can I still learn Sway?
+Yes! If you are familiar with the basics of programming, blockchain, and using a terminal you can build with Sway.
+Q: What can I build with Sway?
+You can build smart contracts and their components and libraries for them. +You can learn more about the different program types and how they fit together in the Program Types section.
+Q: Do I need to install anything?
+If you want to develop with Sway in your local environment, you need to install fuelup and your editor of choice that supports LSP, such as VSCode.
If you don't want to install anything just yet, you can use the Sway Playground to edit, compile, and deploy Sway code.
+Q: Where can I find example Sway code?
+You can find example applications built with Sway in the Sway Applications repository on GitHub. You can also find projects building on Fuel in the Fuel ecosystem home.
+Q: What is the standard library?
+The standard library, also referred to as std, is a library that offers core functions and helpers for developing in Sway. The standard library has its own reference documentation that has detailed information about each module in std.
Q: What are Sway standards?
+Similar to ERC standards for Ethereum and Solidity, Sway has its own SRC standards that help enable cross compatibility across different smart contracts. For more information on using a Sway Standard, you can check out the Sway-Standards Repository.
+Q: How can I make a token?
+Sway has multiple native assets. To mint a new native asset, check out the native assets page.
+Q: How can I make an NFT?
+You can find an example of an NFT contract in Sway in the Sway Applications repo.
+Q: How can I test Sway code?
+Sway provides unit testing, so you can test your Sway code with Sway. You can also use the Fuel Rust SDK or TypeScript SDK to test your Sway programs.
+Q: How can I deploy a contract?
+You can use the forc deploy command to deploy a contract. For a detailed guide on how to deploy a contract, refer to the quickstart guide.
Q: Is there a way to convert Solidity code to Sway?
+Yes! You can use the Solidity to Sway transpiler built in to the Sway Playground to convert Solidity code into Sway code. Note that the transpiler is still experimental, and may not work in every case.
+Q: How can I get help with Sway?
+If you run into an issue or have a question, post it on the Fuel forum so someone in the Fuel community can help.
+Q: Where should I get started?
+Ready to build? You can find step-by-step guides for how to build an application with Sway in the Fuel Developer Guides.
+Want to read? Get started by reading the Introduction and Basics sections of this book.
+ +The Sway Core Library, like the name suggests contains core operators and logic for the primitive types of the Sway programming language. These traits and methods are an extension of the primitive types u8, u16, u32, u64, u256, str[], str, bool and , b256 and can be used where appropriate.
The latest core library documentation can be found here. If the latest version is not compatible please refer to the appropriate tagged release.
+Core library functionalities do not need to be explicitly imported and will work out of the box after creating any new Sway project with forc new. The use keyword is simply not required.
Consider this example of using the modulo function for two like value types:
+let val_1 = 10;
+let val_2 = 2;
+let result = val_1 % val_2;
+The prelude contains a list of operations essential to all Sway programs. The latest version of the prelude can be found here.
+ + +To initialize a new project with Forc, use forc new:
forc new my-fuel-project
+Here is the project that Forc has initialized:
+ + +$ cd my-fuel-project
+$ tree .
+├── Forc.toml
+└── src
+ └── main.sw
+Forc.toml is the manifest file (similar to Cargo.toml for Cargo or package.json for Node), and defines project metadata such as the project name and dependencies.
For additional information on dependency management, see: here.
+[project]
+authors = ["User"]
+entry = "main.sw"
+license = "Apache-2.0"
+name = "my-fuel-project"
+
+[dependencies]
+Here are the contents of the only Sway file in the project, and the main entry point, src/main.sw:
contract;
+
+abi MyContract {
+ fn test_function() -> bool;
+}
+
+impl MyContract for Contract {
+ fn test_function() -> bool {
+ true
+ }
+}
+The project is a contract, one of four different project types. For additional information on different project types, see here.
+We now compile our project with forc build, passing the flag --asm final to view the generated assembly:
$ forc build --asm final
+...
+.program:
+ji i4
+noop
+DATA_SECTION_OFFSET[0..32]
+DATA_SECTION_OFFSET[32..64]
+lw $ds $is 1
+add $$ds $$ds $is
+lw $r0 $fp i73 ; load input function selector
+lw $r1 data_0 ; load fn selector for comparison
+eq $r2 $r0 $r1 ; function selector comparison
+jnzi $r2 i12 ; jump to selected function
+movi $$tmp i123 ; special code for mismatched selector
+rvrt $$tmp ; revert if no selectors matched
+ret $one
+.data:
+data_0 .word 559005003
+
+ Compiled contract "my-fuel-project".
+ Bytecode size is 60 bytes.
+The Fuel toolchain consists of several components.
+forc)The "Fuel Orchestrator" Forc is our equivalent of Rust's Cargo. It is the primary entry point for creating, building, testing, and deploying Sway projects.
+forc-lsp)The Sway Language Server forc-lsp is provided to expose features to IDEs. Installation instructions.
forc-fmt)A canonical formatter is provided with forc-fmt. Installation instructions. It can be run manually with
forc fmt
+The Visual Studio Code plugin will
+automatically format Sway files with forc-fmt on save, though you might have to explicitly set the Sway plugin as the
+default formatter, like this:
"[sway]": {
+ "editor.defaultFormatter": "FuelLabs.sway-vscode-plugin"
+}
+fuel-core)An implementation of the Fuel protocol, Fuel Core, is provided together with the Sway toolchain to form the Fuel toolchain. The Rust SDK will automatically start and stop an instance of the node during tests, so there is no need to manually run a node unless using Forc directly without the SDK.
+ +Fuel toolchainPlease visit the Fuel Installation Guide to install the Fuel toolchain binaries and prerequisites.
+Check out the Developer Quickstart Guide for a step-by-step guide on building a fullstack dapp on Fuel. The guide will walk you through writing a smart contract, setting up a wallet, and building a frontend to interact with your contract.
+ +To get started with Forc and Sway smart contract development, install the Fuel toolchain and Fuel full node and set up your first project.
+ + +Similar to Rust, Sway comes with its own standard library.
+The Sway Standard Library is the foundation of portable Sway software, a set of minimal shared abstractions for the broader Sway ecosystem. It offers core types, like Result<T, E> and Option<T>, library-defined operations on language primitives, native asset management, blockchain contextual operations, access control, storage management, and support for types from other VMs, among many other things.
The entire Sway standard library is a Forc project called std, and is available directly here. Navigate to the appropriate tagged release if the latest master is not compatible. You can find the latest std documentation here.
The standard library is made implicitly available to all Forc projects created using forc new. In other words, it is not required to manually specify std as an explicit dependency. Forc will automatically use the version of std that matches its version.
Importing items from the standard library can be done using the use keyword, just as importing items from any Sway project. For example:
use std::storage::storage_vec::*;
+This imports the StorageVec type into the current namespace.
Sway comes with a variety of things in its standard library. However, if you had to manually import every single thing that you used, it would be very verbose. But importing a lot of things that a program never uses isn't good either. A balance needs to be struck.
+The prelude is the list of things that Sway automatically imports into every Sway program. It's kept as small as possible, and is focused on things which are used in almost every single Sway program.
+The current version of the prelude lives in std::prelude, and re-exports the following:
std::address::Address, a wrapper around the b256 type representing a wallet address.std::contract_id::ContractId, a wrapper around the b256 type representing the ID of a contract.std::identity::Identity, an enum with two possible variants: Address: Address and ContractId: ContractId.std::vec::Vec, a growable, heap-allocated vector.std::storage::storage_key::*, contains the API for accessing a core::storage::StorageKey which describes a location in storage.std::storage::storage_map::*, a key-value mapping in contract storage.std::option::Option, an enum which expresses the presence or absence of a value.std::result::Result, an enum for functions that may succeed or fail.std::assert::assert, a function that reverts the VM if the condition provided to it is false.std::assert::assert_eq, a function that reverts the VM and logs its two inputs v1 and v2 if the condition v1 == v2 is false.std::assert::assert_ne, a function that reverts the VM and logs its two inputs v1 and v2 if the condition v1 != v2 is false.std::revert::require, a function that reverts the VM and logs a given value if the condition provided to it is false.std::revert::revert, a function that reverts the VM.std::logging::log, a function that logs arbitrary stack types.std::auth::msg_sender, a function that gets the Identity from which a call was made.Just like many other smart contract languages, usage standards have been developed to enable cross compatibility between smart contracts.
+For more information on using a Sway Standard, please refer to the Sway-Standards Repository.
+Address as a Soulbound Address for Soulbound Assets to become non-transferable.Libraries have also been developed to support Sway Standards. These can be in Sway-Libs.
+ +Source: code_actions
+Quickly generate boilerplate code and code comments for functions, structs, and ABIs.
+Source: completion.rs
+Suggests code to follow partially written statements for functions and variables.
+Jumps to the definition of a symbol from its usage.
+Locates all occurrences of a symbol throughout the project.
+Source: hover
+Provides documentation, compiler diagnostics, and reference links when hovering over functions and variables.
+Source: inlay_hints.rs
+Displays the implied type of a variable next to the variable name. Configurable in Settings.
+Source: rename.rs
+Renames a symbol everywhere in the workspace.
+Source: diagnostic.rs
+Displays compiler warnings and errors inline.
+Source: highlight.rs
+Highlights code based on type and context.
+Source: runnable.rs
+Shows a button above a runnable function or test.
+ +Welcome to the documentation for Sway LSP, the language server designed specifically for the Sway programming language. This documentation serves as a comprehensive guide to help you understand and utilize the powerful features provided by Sway LSP.
+Sway LSP is built on the Language Server Protocol (LSP), a standardized protocol for enabling rich programming language support in editor and IDE environments. It acts as a bridge between your favorite code editor or integrated development environment and the Sway programming language, offering advanced semantic analysis and a wide range of features to enhance your development experience.
+With Sway LSP, you can expect a seamless and efficient coding experience while working with the Sway programming language. It provides intelligent code completion, precise symbol navigation, type information, and other smart features that empower you to write clean and error-free code. By leveraging the power of Sway LSP, you can increase productivity, reduce debugging time, and write high-quality code with confidence.
+In this documentation, you will find detailed information about how to set up Sway LSP in your preferred code editor or IDE, configure its settings to match your coding style, and take advantage of its various features. We will guide you through the installation process, provide examples of typical configuration setups, and walk you through the usage of each feature supported by Sway LSP.
+Whether you are a beginner or an experienced Sway developer, this documentation aims to be your go-to resource for understanding and maximizing the capabilities of Sway LSP. So let's dive in and unlock the full potential of the Sway programming language with Sway LSP!
+ + +The Sway language server is contained in the forc-lsp binary, which is installed as part of the Fuel toolchain. Once installed, it can be used with a variety of IDEs. It must be installed for any of the IDE plugins to work.
++Note: There is no need to manually run
+forc-lsp(the plugin will automatically start it), however bothforcandforc-lspmust be in your$PATH. To check ifforcis in your$PATH, typeforc --helpin your terminal.
This is the best supported editor at the moment.
+You can install the latest release of the plugin from the marketplace.
+Note that we only support the most recent version of VS Code.
+Follow the documentation for sway.vim to install.
+Install helix and Sway LSP will work out of the box.
+Sway support is built into helix using tree-sitter-sway.
+Coming soon! Feel free to contribute.
+ +First, confirm you are running the most recent version:
+fuelup toolchain install latest
+fuelup update
+forc-lsp --version
+Second, confirm that your $PATH resolves to the forc-lsp binary in $HOME/.fuelup/bin.
which forc-lsp
+If you are experiencing slow performance, you can try the following:
+Follow the steps above to ensure you are running the most recent version.
+Then, make sure you only have the most recent version of the LSP server running.
+pkill forc-lsp
+Sway projects with ten or more Sway files are likely to have slower LSP performance. We are working on better support for large projects.
+In the meantime, if it's too slow, you can disable the LSP server entirely with the sway-lsp.diagnostic.disableLsp setting. The extension will still provide basic syntax highlighting, command palettes, as well as the Sway debugger, but all other language features will be disabled.
You can enable verbose logging of the LSP server.
+In VSCode, this is under the setting:
+"sway-lsp.trace.server": "verbose"
+Once enabled, you can find this in the output window under Sway Language Server.
+For other editors, see Installation for links to documentation.
+ +Welcome to the Sway programming language book 🌴.
+Q: Hi! What is Sway?
+Sway is a domain-specific programming language for implementing smart contracts on blockchain platforms, most notably for the Fuel Virtual Machine (Fuel VM).
+Heavily inspired by Rust's approach to systems programming, Sway aims to bring modern programming language features and tooling to smart contract development whilst retaining performance, fine grained control and making extensive use of static analysis to prevent common security issues.
+Q: What does "domain-specific" mean?
+Sway is specifically made to be used within a blockchain environment, which behaves very differently than traditional computers. +This domain specific design permits it to make the right decisions about trade-offs at every level of the stack, enabling you to write fast, secure and cost effective smart contracts with features suited to your specific needs.
+Q: Why not use Solidity?
+Solidity is a venerable pioneer but it suffers from being tied to a lot of the historical quirks of the EVM. +It lacks common features programmers have come to expect, has a relatively inexpressive type system, and it lacks a unified tooling ecosystem.
+In Sway, we let you design smart contracts with a full modern box of tools. +You get a fully featured language with generics, algebraic types and trait based polymorphism. +You also get an integrated, unified and easy to use toolchain with code completion LSP server, formatter, documentation generation and everything you need to run and deploy your contracts so that nothing comes between you and implementing what you want.
+Our expressive type system allows you to catch semantic mistakes, we provide good defaults and we do extensive static analysis checks (such as enforcing the Checks, Effects, Interactions pattern) so that you can make sure you write secure and correct code at compile time.
+Q: Why not use Rust?
+Whilst Rust is a great systems programming language (and Sway itself is written in Rust), it isn't suited for smart contract development.
+Rust shines because it can use zero-cost abstractions and its sophisticated borrow-checker memory model to achieve impressive runtime performance for complex programs without a garbage collector.
+On a blockchain, cost of execution and deployment is the scarce resource. +Memory usage is low and execution time is short. +This makes complex memory management in general much too expensive to be worthwhile and Rust's borrow checker a burden with no upside.
+General purpose programming languages in general are ill suited to this environment because their design has to assume execution on a general-purpose computing environment.
+Sway attempts to bring all the other advantages of Rust, including its modern type system, approach to safety and good defaults to smart contract developers by providing familiar syntax and features adapted to the specific needs of the blockchain environment.
+Q: I don't know Rust or Solidity. Can I still learn Sway?
+Yes! If you are familiar with the basics of programming, blockchain, and using a terminal you can build with Sway.
+Q: What can I build with Sway?
+You can build smart contracts and their components and libraries for them. +You can learn more about the different program types and how they fit together in the Program Types section.
+Q: Do I need to install anything?
+If you want to develop with Sway in your local environment, you need to install fuelup and your editor of choice that supports LSP, such as VSCode.
If you don't want to install anything just yet, you can use the Sway Playground to edit, compile, and deploy Sway code.
+Q: Where can I find example Sway code?
+You can find example applications built with Sway in the Sway Applications repository on GitHub. You can also find projects building on Fuel in the Fuel ecosystem home.
+Q: What is the standard library?
+The standard library, also referred to as std, is a library that offers core functions and helpers for developing in Sway. The standard library has its own reference documentation that has detailed information about each module in std.
Q: What are Sway standards?
+Similar to ERC standards for Ethereum and Solidity, Sway has its own SRC standards that help enable cross compatibility across different smart contracts. For more information on using a Sway Standard, you can check out the Sway-Standards Repository.
+Q: How can I make a token?
+Sway has multiple native assets. To mint a new native asset, check out the native assets page.
+Q: How can I make an NFT?
+You can find an example of an NFT contract in Sway in the Sway Applications repo.
+Q: How can I test Sway code?
+Sway provides unit testing, so you can test your Sway code with Sway. You can also use the Fuel Rust SDK or TypeScript SDK to test your Sway programs.
+Q: How can I deploy a contract?
+You can use the forc deploy command to deploy a contract. For a detailed guide on how to deploy a contract, refer to the quickstart guide.
Q: Is there a way to convert Solidity code to Sway?
+Yes! You can use the Solidity to Sway transpiler built in to the Sway Playground to convert Solidity code into Sway code. Note that the transpiler is still experimental, and may not work in every case.
+Q: How can I get help with Sway?
+If you run into an issue or have a question, post it on the Fuel forum so someone in the Fuel community can help.
+Q: Where should I get started?
+Ready to build? You can find step-by-step guides for how to build an application with Sway in the Fuel Developer Guides.
+Want to read? Get started by reading the Introduction and Basics sections of this book.
+To get started with Forc and Sway smart contract development, install the Fuel toolchain and Fuel full node and set up your first project.
+Fuel toolchainPlease visit the Fuel Installation Guide to install the Fuel toolchain binaries and prerequisites.
+Check out the Developer Quickstart Guide for a step-by-step guide on building a fullstack dapp on Fuel. The guide will walk you through writing a smart contract, setting up a wallet, and building a frontend to interact with your contract.
+The Fuel toolchain consists of several components.
+forc)The "Fuel Orchestrator" Forc is our equivalent of Rust's Cargo. It is the primary entry point for creating, building, testing, and deploying Sway projects.
+forc-lsp)The Sway Language Server forc-lsp is provided to expose features to IDEs. Installation instructions.
forc-fmt)A canonical formatter is provided with forc-fmt. Installation instructions. It can be run manually with
forc fmt
+The Visual Studio Code plugin will
+automatically format Sway files with forc-fmt on save, though you might have to explicitly set the Sway plugin as the
+default formatter, like this:
"[sway]": {
+ "editor.defaultFormatter": "FuelLabs.sway-vscode-plugin"
+}
+fuel-core)An implementation of the Fuel protocol, Fuel Core, is provided together with the Sway toolchain to form the Fuel toolchain. The Rust SDK will automatically start and stop an instance of the node during tests, so there is no need to manually run a node unless using Forc directly without the SDK.
+To initialize a new project with Forc, use forc new:
forc new my-fuel-project
+Here is the project that Forc has initialized:
+ + +$ cd my-fuel-project
+$ tree .
+├── Forc.toml
+└── src
+ └── main.sw
+Forc.toml is the manifest file (similar to Cargo.toml for Cargo or package.json for Node), and defines project metadata such as the project name and dependencies.
For additional information on dependency management, see: here.
+[project]
+authors = ["User"]
+entry = "main.sw"
+license = "Apache-2.0"
+name = "my-fuel-project"
+
+[dependencies]
+Here are the contents of the only Sway file in the project, and the main entry point, src/main.sw:
contract;
+
+abi MyContract {
+ fn test_function() -> bool;
+}
+
+impl MyContract for Contract {
+ fn test_function() -> bool {
+ true
+ }
+}
+The project is a contract, one of four different project types. For additional information on different project types, see here.
+We now compile our project with forc build, passing the flag --asm final to view the generated assembly:
$ forc build --asm final
+...
+.program:
+ji i4
+noop
+DATA_SECTION_OFFSET[0..32]
+DATA_SECTION_OFFSET[32..64]
+lw $ds $is 1
+add $$ds $$ds $is
+lw $r0 $fp i73 ; load input function selector
+lw $r1 data_0 ; load fn selector for comparison
+eq $r2 $r0 $r1 ; function selector comparison
+jnzi $r2 i12 ; jump to selected function
+movi $$tmp i123 ; special code for mismatched selector
+rvrt $$tmp ; revert if no selectors matched
+ret $one
+.data:
+data_0 .word 559005003
+
+ Compiled contract "my-fuel-project".
+ Bytecode size is 60 bytes.
+Similar to Rust, Sway comes with its own standard library.
+The Sway Standard Library is the foundation of portable Sway software, a set of minimal shared abstractions for the broader Sway ecosystem. It offers core types, like Result<T, E> and Option<T>, library-defined operations on language primitives, native asset management, blockchain contextual operations, access control, storage management, and support for types from other VMs, among many other things.
The entire Sway standard library is a Forc project called std, and is available directly here. Navigate to the appropriate tagged release if the latest master is not compatible. You can find the latest std documentation here.
The standard library is made implicitly available to all Forc projects created using forc new. In other words, it is not required to manually specify std as an explicit dependency. Forc will automatically use the version of std that matches its version.
Importing items from the standard library can be done using the use keyword, just as importing items from any Sway project. For example:
use std::storage::storage_vec::*;
+This imports the StorageVec type into the current namespace.
Sway comes with a variety of things in its standard library. However, if you had to manually import every single thing that you used, it would be very verbose. But importing a lot of things that a program never uses isn't good either. A balance needs to be struck.
+The prelude is the list of things that Sway automatically imports into every Sway program. It's kept as small as possible, and is focused on things which are used in almost every single Sway program.
+The current version of the prelude lives in std::prelude, and re-exports the following:
std::address::Address, a wrapper around the b256 type representing a wallet address.std::contract_id::ContractId, a wrapper around the b256 type representing the ID of a contract.std::identity::Identity, an enum with two possible variants: Address: Address and ContractId: ContractId.std::vec::Vec, a growable, heap-allocated vector.std::storage::storage_key::*, contains the API for accessing a core::storage::StorageKey which describes a location in storage.std::storage::storage_map::*, a key-value mapping in contract storage.std::option::Option, an enum which expresses the presence or absence of a value.std::result::Result, an enum for functions that may succeed or fail.std::assert::assert, a function that reverts the VM if the condition provided to it is false.std::assert::assert_eq, a function that reverts the VM and logs its two inputs v1 and v2 if the condition v1 == v2 is false.std::assert::assert_ne, a function that reverts the VM and logs its two inputs v1 and v2 if the condition v1 != v2 is false.std::revert::require, a function that reverts the VM and logs a given value if the condition provided to it is false.std::revert::revert, a function that reverts the VM.std::logging::log, a function that logs arbitrary stack types.std::auth::msg_sender, a function that gets the Identity from which a call was made.The Sway Core Library, like the name suggests contains core operators and logic for the primitive types of the Sway programming language. These traits and methods are an extension of the primitive types u8, u16, u32, u64, u256, str[], str, bool and , b256 and can be used where appropriate.
The latest core library documentation can be found here. If the latest version is not compatible please refer to the appropriate tagged release.
+Core library functionalities do not need to be explicitly imported and will work out of the box after creating any new Sway project with forc new. The use keyword is simply not required.
Consider this example of using the modulo function for two like value types:
+let val_1 = 10;
+let val_2 = 2;
+let result = val_1 % val_2;
+The prelude contains a list of operations essential to all Sway programs. The latest version of the prelude can be found here.
+core::primitives::*core::primitive_conversions::*core::raw_ptr::*core::raw_slice::*core::ops::*core::storage::*core::str::*core::codec::*Just like many other smart contract languages, usage standards have been developed to enable cross compatibility between smart contracts.
+For more information on using a Sway Standard, please refer to the Sway-Standards Repository.
+Address as a Soulbound Address for Soulbound Assets to become non-transferable.Libraries have also been developed to support Sway Standards. These can be in Sway-Libs.
+Some basic example contracts to see how Sway and Forc work.
+ +Additional examples can be found in the Sway Applications repository.
+The following is a simple example of a contract which implements a counter. Both the initialize_counter() and increment_counter() ABI methods return the currently set value.
forc template --template-name counter my_counter_project
+contract;
+
+abi TestContract {
+ #[storage(write)]
+ fn initialize_counter(value: u64) -> u64;
+
+ #[storage(read, write)]
+ fn increment_counter(amount: u64) -> u64;
+}
+
+storage {
+ counter: u64 = 0,
+}
+
+impl TestContract for Contract {
+ #[storage(write)]
+ fn initialize_counter(value: u64) -> u64 {
+ storage.counter.write(value);
+ value
+ }
+
+ #[storage(read, write)]
+ fn increment_counter(amount: u64) -> u64 {
+ let incremented = storage.counter.read() + amount;
+ storage.counter.write(incremented);
+ incremented
+ }
+}
+The following commands can be used to build and deploy the contract. For a detailed tutorial, refer to Building and Deploying.
+# Build the contract
+forc build
+
+# Deploy the contract
+forc deploy --testnet
+FizzBuzzThis example is not the traditional FizzBuzz; instead it is the smart contract version! A script can call the fizzbuzz ABI method of this contract with some u64 value and receive back the result as an enum.
The format for custom structs and enums such as FizzBuzzResult will be automatically included in the ABI JSON so that off-chain code can handle the encoded form of the returned data.
contract;
+
+enum FizzBuzzResult {
+ Fizz: (),
+ Buzz: (),
+ FizzBuzz: (),
+ Other: u64,
+}
+
+abi FizzBuzz {
+ fn fizzbuzz(input: u64) -> FizzBuzzResult;
+}
+
+impl FizzBuzz for Contract {
+ fn fizzbuzz(input: u64) -> FizzBuzzResult {
+ if input % 15 == 0 {
+ FizzBuzzResult::FizzBuzz
+ } else if input % 3 == 0 {
+ FizzBuzzResult::Fizz
+ } else if input % 5 == 0 {
+ FizzBuzzResult::Buzz
+ } else {
+ FizzBuzzResult::Other(input)
+ }
+ }
+}
+The ABI declaration is a separate project from your ABI implementation. The project structure for the code should be organized as follows with the wallet_abi treated as an external library:
.
+├── wallet_abi
+│ ├── Forc.toml
+│ └── src
+│ └── main.sw
+└── wallet_smart_contract
+ ├── Forc.toml
+ └── src
+ └── main.sw
+It's also important to specify the source of the dependency within the project's Forc.toml file when using external libraries. Inside the wallet_smart_contract project, it requires a declaration like this:
[dependencies]
+wallet_abi = { path = "../wallet_abi/" }
+library;
+
+abi Wallet {
+ #[storage(read, write), payable]
+ fn receive_funds();
+
+ #[storage(read, write)]
+ fn send_funds(amount_to_send: u64, recipient_address: Address);
+}
+contract;
+
+use std::{asset::transfer, call_frames::msg_asset_id, context::msg_amount};
+
+use wallet_abi::Wallet;
+const OWNER_ADDRESS = Address::from(0x8900c5bec4ca97d4febf9ceb4754a60d782abbf3cd815836c1872116f203f861);
+
+storage {
+ balance: u64 = 0,
+}
+
+impl Wallet for Contract {
+ #[storage(read, write), payable]
+ fn receive_funds() {
+ if msg_asset_id() == AssetId::base() {
+ // If we received the base asset then keep track of the balance.
+ // Otherwise, we're receiving other native assets and don't care
+ // about our balance of coins.
+ storage.balance.write(storage.balance.read() + msg_amount());
+ }
+ }
+
+ #[storage(read, write)]
+ fn send_funds(amount_to_send: u64, recipient_address: Address) {
+ let sender = msg_sender().unwrap();
+ match sender {
+ Identity::Address(addr) => assert(addr == OWNER_ADDRESS),
+ _ => revert(0),
+ };
+
+ let current_balance = storage.balance.read();
+ assert(current_balance >= amount_to_send);
+
+ storage.balance.write(current_balance - amount_to_send);
+
+ // Note: `transfer()` is not a call and thus not an
+ // interaction. Regardless, this code conforms to
+ // checks-effects-interactions to avoid re-entrancy.
+ transfer(
+ Identity::Address(recipient_address),
+ AssetId::base(),
+ amount_to_send,
+ );
+ }
+}
+All contracts in Fuel can mint and burn their own native asset. Contracts can also receive and transfer any native asset including their own. Internal balances of all native assets pushed through calls or minted by the contract are tracked by the FuelVM and can be queried at any point using the balance_of function from the std library. Therefore, there is no need for any manual accounting of the contract's balances using persistent storage.
The std library provides handy methods for accessing Fuel's native asset operations.
In this example, we show a basic liquidity pool contract minting its own native asset LP asset.
+contract;
+
+use std::{
+ asset::{
+ mint_to,
+ transfer,
+ },
+ call_frames::msg_asset_id,
+ constants::DEFAULT_SUB_ID,
+ context::msg_amount,
+ hash::*,
+};
+
+abi LiquidityPool {
+ fn deposit(recipient: Address);
+ fn withdraw(recipient: Address);
+}
+
+const BASE_ASSET: AssetId = AssetId::from(0x9ae5b658754e096e4d681c548daf46354495a437cc61492599e33fc64dcdc30c);
+
+impl LiquidityPool for Contract {
+ fn deposit(recipient: Address) {
+ assert(msg_asset_id() == BASE_ASSET);
+ assert(msg_amount() > 0);
+
+ // Mint two times the amount.
+ let amount_to_mint = msg_amount() * 2;
+
+ // Mint some LP assets based upon the amount of the base asset.
+ mint_to(Identity::Address(recipient), DEFAULT_SUB_ID, amount_to_mint);
+ }
+
+ fn withdraw(recipient: Address) {
+ let asset_id = AssetId::default();
+ assert(msg_asset_id() == asset_id);
+ assert(msg_amount() > 0);
+
+ // Amount to withdraw.
+ let amount_to_transfer = msg_amount() / 2;
+
+ // Transfer base asset to recipient.
+ transfer(Identity::Address(recipient), BASE_ASSET, amount_to_transfer);
+ }
+}
+The Sway-Applications Repository contains end-to-end example applications that are written in Sway in order to demonstrate what can be built.
+A Sway program itself has a type: it is either a contract, a predicate, a script, or a library. The first three of these things are all deployable to the blockchain. A library is simply a project designed for code reuse and is never directly deployed to the chain.
+Every Sway file must begin with a declaration of what type of program it is. A project can have many libraries within it, but only one contract, script, or predicate. Scripts and predicates require main functions to serve as entry points, while contracts instead publish an ABI. This chapter will go into detail about all of these various types of programs and what purposes they serve.
Contracts are used primarily for protocols or systems that operate within a fixed set of rules. A good example would be a staking contract or a decentralized exchange (also called a DEX).
+Scripts are used for complex on-chain interactions that won't persist. An example of this may be using a DEX and Lender to create a leveraged position (borrow, swap, re-collateralize) which is a complex transaction that would usually take multiple steps.
+Libraries are for code that is reusable and useful for handling common situations. A good example of this would be a library to handle fixed-point math or big number math.
+A smart contract is no different than a script or predicate in that it is a piece of bytecode that is deployed to the blockchain via a transaction. The main features of a smart contract that differentiate it from scripts or predicates are that it is callable and stateful. Put another way, a smart contract is analogous to a deployed API with some database state.
+ +The interface of a smart contract, also just called a contract, must be defined strictly with an ABI declaration. See this contract for an example.
+As with any Sway program, the program starts with a declaration of what program type it is. A contract must also either define or import an ABI declaration and implement it.
+ + +It is considered good practice to define your ABI in a separate library and import it into your contract. This allows callers of your contract to simply import the ABI directly and use it in their scripts to call your contract.
+ +Let's take a look at an ABI declaration in a library:
+library;
+
+abi Wallet {
+ #[storage(read, write), payable]
+ fn receive_funds();
+
+ #[storage(read, write)]
+ fn send_funds(amount_to_send: u64, recipient_address: Address);
+}
+Let's focus on the ABI declaration and inspect it line-by-line.
+abi Wallet {
+ #[storage(read, write), payable]
+ fn receive_funds();
+
+ #[storage(read, write)]
+ fn send_funds(amount_to_send: u64, recipient_address: Address);
+}
+In the first line, abi Wallet {, we declare the name of this Application Binary Interface, or ABI. We are naming this ABI Wallet. To import this ABI into either a script for calling or a contract for implementing, you would use
use wallet_abi::Wallet;
+In the second line,
+ #[storage(read, write), payable]
+ fn receive_funds();
+we are declaring an ABI method called receive_funds which, when called, should receive funds into this wallet. Note that we are simply defining an interface here, so there is no function body or implementation of the function. We only need to define the interface itself. In this way, ABI declarations are similar to trait declarations. This particular ABI method does not take any parameters.
In the third line,
+ #[storage(read, write)]
+ fn send_funds(amount_to_send: u64, recipient_address: Address);
+we are declaring another ABI method, this time called send_funds. It takes two parameters: the amount to send, and the address to send the funds to.
++Note: The ABI methods
+receive_fundsandsend_fundsalso require the annotation#[storage(read, write)]because their implementations require reading and writing a storage variable that keeps track of the wallet balance, as we will see shortly. Refer to Purity for more information on storage annotations.
Now that we've discussed how to define the interface, let's discuss how to use it. We will start by implementing the above ABI for a specific contract.
+Implementing an ABI for a contract is accomplished with impl <ABI name> for Contract syntax. The for Contract syntax can only be used to implement an ABI for a contract; implementing methods for a struct should use impl Foo syntax.
impl Wallet for Contract {
+ #[storage(read, write), payable]
+ fn receive_funds() {
+ if msg_asset_id() == AssetId::base() {
+ // If we received the base asset then keep track of the balance.
+ // Otherwise, we're receiving other native assets and don't care
+ // about our balance of coins.
+ storage.balance.write(storage.balance.read() + msg_amount());
+ }
+ }
+
+ #[storage(read, write)]
+ fn send_funds(amount_to_send: u64, recipient_address: Address) {
+ let sender = msg_sender().unwrap();
+ match sender {
+ Identity::Address(addr) => assert(addr == OWNER_ADDRESS),
+ _ => revert(0),
+ };
+
+ let current_balance = storage.balance.read();
+ assert(current_balance >= amount_to_send);
+
+ storage.balance.write(current_balance - amount_to_send);
+
+ // Note: `transfer()` is not a call and thus not an
+ // interaction. Regardless, this code conforms to
+ // checks-effects-interactions to avoid re-entrancy.
+ transfer(
+ Identity::Address(recipient_address),
+ AssetId::base(),
+ amount_to_send,
+ );
+ }
+}
+You may notice once again the similarities between traits and ABIs. And, indeed, as a bonus, you can define methods in addition to the interface surface of an ABI, just like a trait. These pre-implemented ABI methods automatically become available as part of the contract interface that implements the corresponding ABI.
+Note that the above implementation of the ABI follows the Checks, Effects, Interactions pattern.
+ContractId typeContracts have an associated ContractId type in Sway. The ContractId type allows for Sway programs to refer to contracts in the Sway language. Please refer to the ContractId section of the book for more information on ContractIds.
++Note: In most cases, calling a contract should be done from the Rust SDK or the TypeScript SDK which provide a more ergonomic UI for interacting with a contract. However, there are situations where manually writing a script to call a contract is required.
+
Now that we have defined our interface and implemented it for our contract, we need to know how to actually call our contract. Let's take a look at a contract call:
+script;
+
+use wallet_abi::Wallet;
+
+fn main() {
+ let contract_address = 0x9299da6c73e6dc03eeabcce242bb347de3f5f56cd1c70926d76526d7ed199b8b;
+ let caller = abi(Wallet, contract_address);
+ let amount_to_send = 200;
+ let recipient_address = Address::from(0x9299da6c73e6dc03eeabcce242bb347de3f5f56cd1c70926d76526d7ed199b8b);
+ caller
+ .send_funds {
+ gas: 10000,
+ coins: 0,
+ asset_id: b256::zero(),
+ }(amount_to_send, recipient_address);
+}
+The main new concept is the abi cast: abi(AbiName, contract_address). This returns a ContractCaller type which can be used to call contracts. The methods of the ABI become the methods available on this contract caller: send_funds and receive_funds. We then directly call the contract ABI method as if it was just a regular method. You also have the option of specifying the following special parameters inside curly braces right before the main list of parameters:
gas: a u64 that represents the gas being forwarded to the contract when it is called.coins: a u64 that represents how many coins are being forwarded with this call.asset_id: a b256 that represents the ID of the asset type of the coins being forwarded.Each special parameter is optional and assumes a default value when skipped:
+gas is the context gas (i.e. the content of the special register $cgas). Refer to the FuelVM specifications for more information about context gas.coins is 0.asset_id is b256::zero().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.
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:
library keyword:library;
+use statement that imports revert from another library inside the standard library:use ::revert::revert;
+enum definition which starts with the keyword pub to indicate that this Option<T> is publicly available outside the option library:pub enum Option<T> {
+ // variants
+}
+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;
+
+// ...
+There are two types of Sway libraries, based on their location and how they can be imported.
+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:
mod keyword followed by the library name to make the internal library a dependencyuse 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 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:
pub keyword (if applicable, for instance: pub fn mint() {})use keyword to selectively import items from the libraryuse 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
+stdas an explicit dependency inForc.toml.
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 implementations of common use-cases valuable for dapp development.
Some Sway Libraries to try out:
+ +You can import and use a Sway Library such as the Ownership library just like any other external library.
+use ownership::Ownership;
+Once imported, you can use the following basic functionality of the library in your smart contract:
+A script is runnable bytecode on the chain which executes once to perform some task. It does not represent ownership of any resources and it cannot be called by a contract. A script can return a single value of any type.
+Scripts are state-aware in that while they have no persistent storage (because they only exist during the transaction) they can call contracts and act based upon the returned values and results.
+This example script calls a contract:
+script;
+
+use wallet_abi::Wallet;
+
+fn main() {
+ let contract_address = 0x9299da6c73e6dc03eeabcce242bb347de3f5f56cd1c70926d76526d7ed199b8b;
+ let caller = abi(Wallet, contract_address);
+ let amount_to_send = 200;
+ let recipient_address = Address::from(0x9299da6c73e6dc03eeabcce242bb347de3f5f56cd1c70926d76526d7ed199b8b);
+ caller
+ .send_funds {
+ gas: 10000,
+ coins: 0,
+ asset_id: b256::zero(),
+ }(amount_to_send, recipient_address);
+}
+Scripts, similar to predicates, rely on a main() function as an entry point. You can call other functions defined in a script from the main() function or call another contract via an ABI cast.
An example use case for a script would be a router that trades funds through multiple decentralized exchanges to get the price for the input asset, or a script to re-adjust a Collateralized Debt Position via a flash loan.
+Unlike EVM transactions which can call a contract directly (but can only call a single contract), Fuel transactions execute a script, which may call zero or more contracts. The Rust and TypeScript SDKs provide functions to call contract methods as if they were calling contracts directly. Under the hood, the SDKs wrap all contract calls with scripts that contain minimal code to simply make the call and forward script data as call parameters.
+From the perspective of Sway, predicates are programs that return a Boolean value and which represent ownership of some resource upon execution to true. They have no access to contract storage. Here is a trivial predicate, which always evaluates to true:
+predicate;
+
+// All predicates require a main function which returns a Boolean value.
+fn main() -> bool {
+ true
+}
+The address of this predicate is 0xd19a5fe4cb9baf41ad9813f1a6fef551107c8e8e3f499a6e32bccbb954a74764. Any assets sent to this address can be unlocked or claimed by executing the predicate above as it always evaluates to true.
It does not need to be deployed to a blockchain because it only exists during a transaction. That being said, the predicate address is on-chain as the owner of one or more UTXOs.
+In Fuel, coins can be sent to a predicate's address(the bytecode root, calculated here).
+The coin UTXOs become spendable not on the provision of a valid signature, but rather if the supplied predicate both has a root that matches their owner, and evaluates to true.
If a predicate reverts, or tries to access impure VM opcodes, the evaluation is automatically false.
An analogy for predicates is rather than a traditional 12 or 24 word seed phrase that generates a private key and creates a valid signature, a predicate's code can be viewed as the private key. Anyone with the code may execute a predicate, but only when the predicate evaluates to true may the assets owned by that address be released.
+Predicates may introspect the transaction spending their coins (inputs, outputs, script bytecode, etc.) and may take runtime arguments, either or both of which may affect the evaluation of the predicate.
+It is important to note that predicates cannot read or write memory. They may however check the inputs and outputs of a transaction. For example in the OTC Predicate Swap Example, a user may specify they would like to swap asset1 for asset2 and with amount of 5. The user would then send asset1 to the predicate. Only when the predicate can verify that the outputs include 5 coins of asset2 being sent to the original user, may asset1 be transferred out of the predicate.
Because they don't have any side effects (they are pure), predicates cannot create receipts. Therefore, they cannot have logging or create a stack backtrace. This means that there is no native way to debug them aside from using a single-stepping debugger.
+As a workaround, the predicate can be written, tested, and debugged first as a script, and then changed back into a predicate.
Sway is a programming language designed for the FuelVM. It is a statically typed, compiled language with type inference and traits. Sway aims to make smart contract development safer and more efficient through the use of strong static analysis and compiler feedback.
+Get started with the basics of Sway:
+Variables in Sway are immutable by default. This means that, by default, once a variable is declared, its value cannot change. This is one of the ways how Sway encourages safe programming, and many modern languages have this same default.
+ +Let's take a look at variables in detail.
+Let's look at a variable declaration:
+let foo = 5;
+Great! We have just declared a variable, foo. What do we know about foo?
5.u64, a 64-bit unsigned integer.u64 is the default numeric type, and represents a 64-bit unsigned integer. See the section Built-in Types for more details.
We can also make a mutable variable. Let's take a look:
+let mut foo = 5;
+foo = 6;
+Now, foo is mutable, and the reassignment to the number 6 is valid. That is, we are allowed to mutate the variable foo to change its value.
When assigning to a mutable variable, the right-hand side of the assignment is evaluated before the left-hand side. In the below example, the mutable variable i will first be increased and the resulting value of 1 will be stored to array[1], thus resulting in array being changed to [0, 1, 0].
let mut array = [0, 0, 0];
+let mut i = 0;
+
+array[i] = {
+ i += 1;
+ i
+};
+A variable declaration can contain a type annotation. A type annotation serves the purpose of declaring the type, in addition to the value, of a variable.
+ +Let's take a look:
+let foo: u32 = 5;
+We have just declared the type of the variable foo as a u32, which is an unsigned 32-bit integer. Let's take a look at a few other type annotations:
let bar: str[4] = __to_str_array("sway");
+let baz: bool = true;
+If the value declared cannot be assigned to the declared type, there will be an error generated by the compiler.
+ +Every value in Sway is of a certain type. Although deep down, all values are just ones and zeroes in the underlying virtual machine, Sway needs to know what those ones and zeroes actually mean. This is accomplished with types.
+ + +Sway is a statically typed language. At compile time, the types of every value must be known. This does not mean you need to specify every single type: usually, the type can be reasonably inferred by the compiler.
+ +Sway has the following primitive types:
+() (unit type)u8 (8-bit unsigned integer)u16 (16-bit unsigned integer)u32 (32-bit unsigned integer)u64 (64-bit unsigned integer)u256 (256-bit unsigned integer)str[] (fixed-length string)str (string slices)bool (Boolean true or false)b256 (256 bits (32 bytes), i.e. a hash)All other types in Sway are built up of these primitive types, or references to these primitive types. You may notice that there are no signed integers—this is by design. In the blockchain domain that Sway occupies, floating-point values and negative numbers have smaller utility, so their implementation has been left up to libraries for specific use cases.
+ +The unit type, (), is a type that allows only one value, and thus, represents a value with no information. It is used to indicate the absence of a meaningful value, or the result of a function that performs an action, but does not return any data. The value of the unit type, called simply unit, has the same symbol as the unit type, (). Unit type in Sway serves a similar purpose as void in imperative languages like C or Java.
For example:
+fn returns_unit() -> () { // Here, `()` represent the unit type.
+ () // Here, `()` represents the single unit value of the unit type.
+}
+In Sway, if the function return type is not specified, it is () by default. Thus, the above example is semantically same as the following:
fn returns_unit() {
+}
+All of the unsigned integer types are numeric types.
+Numbers can be declared with binary syntax, hexadecimal syntax, base-10 syntax, and underscores for delineation. Let's take a look at the following valid numeric primitives:
+0xffffff // hexadecimal
+0b10101010 // binary
+10 // base-10
+100_000 // underscore delineated base-10
+0x1111_0000 // underscore delineated binary
+0xfff_aaa // underscore delineated hexadecimal
+The default numeric type is u64. The FuelVM's word size is 64 bits, and the cases where using a smaller numeric type saves space are minimal.
If a 64-bit or 256-bit arithmetic operation produces an overflow or an underflow, +computation gets reverted automatically by FuelVM.
+8/16/32-bit arithmetic operations are emulated using their 64-bit analogues with +additional overflow/underflow checks inserted, which generally results in +somewhat higher gas consumption.
+The same does not happen with 256-bit operations, including b256, which uses specialized operations and are as efficient as possible.
The boolean type (bool) has two potential values: true or false. Boolean values are typically used for conditional logic or validation, for example in if expressions. Booleans can be negated, or flipped, with the unary negation operator !.
For example:
+fn returns_false() -> bool {
+ let boolean_value: bool = true;
+ !boolean_value
+}
+In Sway, string literals are stored as variable length string slices. Which means that they are stored as a pointer to the actual string data and its length.
+ +let my_string: str = "fuel";
+String slices, because they contain pointers have limited usage. They cannot be used as constants, storage fields, or configurable constants, nor as main function arguments or returns.
+For these cases one must use string arrays, as described below.
+In Sway, static-length strings are a primitive type. This means that when you declare a string array, its size is a part of its type. This is necessary for the compiler to know how much memory to give for the storage of that data. The size of the string is denoted with square brackets.
+ +Let's take a look:
+let my_string: str[4] = __to_str_array("fuel");
+Because the string literal "fuel" is four letters, the type is str[4], denoting a static length of 4 characters. Strings default to UTF-8 in Sway.
As above, string literals are typed as string slices. So that is why the need for __to_str_array that convert them to string arrays at compile time.
Conversion during runtime can be done with from_str_array and try_as_str_array. The latter can fail, given that the specified string array must be big enough for the string slice content.
let a: str = "abcd";
+let b: str[4] = a.try_as_str_array().unwrap();
+let c: str = from_str_array(b);
+Compound types are types that group multiple values into one type. In Sway, we have arrays and tuples.
+A tuple is a general-purpose static-length aggregation of types. In more plain terms, a tuple is a single type that consists of an aggregate of zero or more types. The internal types that make up a tuple, and the tuple's arity, define the tuple's type.
+ +Let's take a look at some examples.
+let x: (u64, u64) = (0, 0);
+This is a tuple, denoted by parenthesized, comma-separated values. Note that the type annotation, (u64, u64), is similar in syntax to the expression which instantiates that type, (0, 0).
let x: (u64, bool) = (42, true);
+assert(x.1);
+In this example, we have created a new tuple type, (u64, bool), which is a composite of a u64 and a bool.
To access a value within a tuple, we use tuple indexing: x.1 stands for the first (zero-indexed, so the bool) value of the tuple. Likewise, x.0 would be the zeroth, u64 value of the tuple. Tuple values can also be accessed via destructuring.
struct Foo {}
+let x: (u64, Foo, bool) = (42, Foo {}, true);
+let (number, foo, boolean) = x;
+To create one-arity tuples, we will need to add a trailing comma:
+let x: u64 = (42); // x is of type u64
+let y: (u64) = (42); // y is of type u64
+let z: (u64,) = (42,); // z is of type (u64), i.e. a one-arity tuple
+let w: (u64) = (42,); // type error
+An array is similar to a tuple, but an array's values must all be of the same type. Arrays can hold arbitrary types including non-primitive types.
+ +An array is written as a comma-separated list inside square brackets:
+let x = [1, 2, 3, 4, 5];
+Arrays are allocated on the stack since their size is known. An array's size is always static, i.e. it cannot change. An array of five elements cannot become an array of six elements.
+Arrays can be iterated over, unlike tuples. An array's type is written as the type the array contains followed by the number of elements, semicolon-separated and within square brackets, e.g., [u64; 5]. To access an element in an array, use the array indexing syntax, i.e. square brackets.
Array elements can also be mutated if the underlying array is declared as mutable:
+let mut x = [1, 2, 3, 4, 5];
+x[0] = 0;
+script;
+
+struct Foo {
+ f1: u32,
+ f2: b256,
+}
+
+fn main() {
+ // Array of integers with type ascription
+ let array_of_integers: [u8; 5] = [1, 2, 3, 4, 5];
+
+ // Array of strings
+ let array_of_strings = ["Bob", "Jan", "Ron"];
+
+ // Array of structs
+ let array_of_structs: [Foo; 2] = [
+ Foo {
+ f1: 11,
+ f2: 0x1111111111111111111111111111111111111111111111111111111111111111,
+ },
+ Foo {
+ f1: 22,
+ f2: 0x2222222222222222222222222222222222222222222222222222222222222222,
+ },
+ ];
+
+ // Accessing an element of an array
+ let mut array_of_bools: [bool; 2] = [true, false];
+ assert(array_of_bools[0]);
+
+ // Mutating the element of an array
+ array_of_bools[1] = true;
+ assert(array_of_bools[1]);
+}
+The Sway Standard Library is the foundation of portable Sway software, a set of minimal shared abstractions for the broader Sway ecosystem. It offers core types, library-defined operations on language primitives, native asset management, blockchain contextual operations, access control, storage management, and support for types from other VMs, among many other things. Reference the standard library docs here.
+Result<T, E>Type Result is the type used for returning and propagating errors. It is an enum with two variants: Ok(T), representing success and containing a value, and Err(E), representing error and containing an error value. The T and E in this definition are type parameters, allowing Result to be generic and to be used with any types.
/// `Result` is a type that represents either success (`Ok`) or failure (`Err`).
+pub enum Result<T, E> {
+ /// Contains the success value.
+ Ok: T,
+ /// Contains the error value.
+ Err: E,
+}
+Functions return Result whenever errors are expected and recoverable.
Take the following example:
+script;
+
+enum MyContractError {
+ DivisionByZero: (),
+}
+
+fn divide(numerator: u64, denominator: u64) -> Result<u64, MyContractError> {
+ if (denominator == 0) {
+ return Err(MyContractError::DivisionByZero);
+ } else {
+ Ok(numerator / denominator)
+ }
+}
+
+fn main() -> Result<u64, str[4]> {
+ let result = divide(20, 2);
+ match result {
+ Ok(value) => Ok(value),
+ Err(MyContractError::DivisionByZero) => Err(__to_str_array("Fail")),
+ }
+}
+Option<T>Type Option represents an optional value: every Option is either Some and contains a value, or None, and does not. Option types are very common in Sway code, as they have a number of uses:
None can be used as an initializer.None is returned on error.The implementation of Option matches on the variant: if it's Ok it returns the inner value, if it's None, it reverts.
/// A type that represents an optional value, either `Some(val)` or `None`.
+pub enum Option<T> {
+ /// No value.
+ None: (),
+ /// Some value of type `T`.
+ Some: T,
+}
+Option is commonly paired with pattern matching to query the presence of a value and take action, allowing developers to choose how to handle the None case.
Below is an example that uses pattern matching to handle invalid divisions by 0 by returning an Option:
script;
+
+fn divide(numerator: u64, denominator: u64) -> Option<u64> {
+ if denominator == 0 {
+ None
+ } else {
+ Some(numerator / denominator)
+ }
+}
+
+fn main() {
+ let result = divide(6, 2);
+ // Pattern match to retrieve the value
+ match result {
+ // The division was valid
+ Some(x) => std::logging::log(x),
+ // The division was invalid
+ None => std::logging::log("Cannot divide by 0"),
+ }
+}
+Sway is fundamentally a blockchain language, and it offers a selection of types tailored for the blockchain use case.
+These are provided via the standard library (lib-std) which both add a degree of type-safety, as well as make the intention of the developer more clear.
Address TypeThe Address type is a type-safe wrapper around the primitive b256 type. Unlike the EVM, an address never refers to a deployed smart contract (see the ContractId type below). An Address can be either the hash of a public key (effectively an externally owned account if you're coming from the EVM) or the hash of a predicate. Addresses own UTXOs.
An Address is implemented as follows.
pub struct Address {
+ value: b256,
+}
+Casting between the b256 and Address types must be done explicitly:
let my_number: b256 = 0x000000000000000000000000000000000000000000000000000000000000002A;
+let my_address: Address = Address::from(my_number);
+let forty_two: b256 = my_address.into();
+ContractId TypeThe ContractId type is a type-safe wrapper around the primitive b256 type. A contract's ID is a unique, deterministic identifier analogous to a contract's address in the EVM. Contracts cannot own UTXOs but can own assets.
A ContractId is implemented as follows.
pub struct ContractId {
+ value: b256,
+}
+Casting between the b256 and ContractId types must be done explicitly:
let my_number: b256 = 0x000000000000000000000000000000000000000000000000000000000000002A;
+let my_contract_id: ContractId = ContractId::from(my_number);
+let forty_two: b256 = my_contract_id.into();
+ContractIdTo get the ContractId of a contract in an internal context use the ContractId::this() function:
impl MyContract for Contract {
+ fn foo() {
+ let this_contract_id: ContractId = ContractId::this();
+ }
+}
+Identity TypeThe Identity type is an enum that allows for the handling of both Address and ContractId types. This is useful in cases where either type is accepted, e.g., receiving funds from an identified sender, but not caring if the sender is an address or a contract.
An Identity is implemented as follows.
pub enum Identity {
+ Address: Address,
+ ContractId: ContractId,
+}
+Casting to an Identity must be done explicitly:
let raw_address: b256 = 0xddec0e7e6a9a4a4e3e57d08d080d71a299c628a46bc609aab4627695679421ca;
+ let my_identity: Identity = Identity::Address(Address::from(raw_address));
+A match statement can be used to return to an Address or ContractId as well as handle cases in which their execution differs.
let my_contract_id: ContractId = match my_identity {
+ Identity::ContractId(identity) => identity,
+ _ => revert(0),
+ };
+ match my_identity {
+ Identity::Address(address) => takes_address(address),
+ Identity::ContractId(contract_id) => takes_contract_id(contract_id),
+ };
+A common use case for Identity is for access control. The use of Identity uniquely allows both ContractId and Address to have access control inclusively.
let sender = msg_sender().unwrap();
+ require(
+ sender == storage
+ .owner
+ .read(),
+ MyError::UnauthorizedUser(sender),
+ );
+Below are some common type conversions in Sway:
+ +Identity let identity_from_b256: Identity = Identity::Address(Address::from(b256_address));
+ let identity_from_address: Identity = Identity::Address(address);
+ let identity_from_contract_id: Identity = Identity::ContractId(contract_id);
+Identity to ContractId or Address match my_identity {
+ Identity::Address(address) => log(address),
+ Identity::ContractId(contract_id) => log(contract_id),
+ };
+ContractId or Address to b256 let b256_from_address: b256 = address.into();
+ let b256_from_contract_id: b256 = contract_id.into();
+b256 to ContractId or Address let address_from_b256: Address = Address::from(b256_address);
+ let contract_id_from_b256: ContractId = ContractId::from(b256_address);
+str to str[] let fuel_str: str = "fuel";
+ let fuel_str_array: str[4] = fuel_str.try_as_str_array().unwrap();
+str[] to str let fuel_str_array: str[4] = __to_str_array("fuel");
+ let fuel_str: str = from_str_array(fuel_str_array);
+u256 let u8_1: u8 = 2u8;
+ let u16_1: u16 = 2u16;
+ let u32_1: u32 = 2u32;
+ let u64_1: u64 = 2u64;
+ let b256_1: b256 = 0x0102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f20;
+
+ let u256_from_u8: u256 = u8_1.as_u256();
+ let u256_from_u16: u256 = u16_1.as_u256();
+ let u256_from_u32: u256 = u32_1.as_u256();
+ let u256_from_u64: u256 = u64_1.as_u256();
+ let u256_from_b256: u256 = b256_1.as_u256();
+u64 let u8_1: u8 = 2u8;
+ let u16_1: u16 = 2u16;
+ let u32_1: u32 = 2u32;
+ let u256_1: u256 = 0x0000000000000000000000000000000000000000000000000000000000000002u256;
+
+ let u64_from_u8: u64 = u8_1.as_u64();
+
+ let u64_from_u16: u64 = u16_1.as_u64();
+
+ let u64_from_u32: u64 = u32_1.as_u64();
+
+ let u64_from_u256: Option<u64> = <u64 as TryFrom<u256>>::try_from(u256_1);
+u32 let u8_1: u8 = 2u8;
+ let u16_1: u16 = 2u16;
+ let u64_1: u64 = 2;
+ let u256_1: u256 = 0x0000000000000000000000000000000000000000000000000000000000000002u256;
+
+ let u32_from_u8: u32 = u8_1.as_u32();
+
+ let u32_from_u16: u32 = u16_1.as_u32();
+
+ let u32_from_u64_1: Option<u32> = u64_1.try_as_u32();
+ let u32_from_u64_2: Option<u32> = <u32 as TryFrom<u64>>::try_from(u64_1);
+
+ let u32_from_u256: Option<u32> = <u32 as TryFrom<u256>>::try_from(u256_1);
+u16 let u8_1: u8 = 2u8;
+ let u32_1: u32 = 2u32;
+ let u64_1: u64 = 2;
+ let u256_1: u256 = 0x0000000000000000000000000000000000000000000000000000000000000002u256;
+
+ let u16_from_u8: u16 = u8_1.as_u16();
+
+ let u16_from_u32_1: Option<u16> = u32_1.try_as_u16();
+ let u16_from_u32_2: Option<u16> = <u16 as TryFrom<u32>>::try_from(u32_1);
+
+ let u16_from_u64_1: Option<u16> = u64_1.try_as_u16();
+ let u16_from_u64_2: Option<u16> = <u16 as TryFrom<u64>>::try_from(u64_1);
+
+ let u16_from_u256: Option<u16> = <u16 as TryFrom<u256>>::try_from(u256_1);
+u8 let u16_1: u16 = 2u16;
+ let u32_1: u32 = 2u32;
+ let u64_1: u64 = 2;
+ let u256_1: u256 = 0x0000000000000000000000000000000000000000000000000000000000000002u256;
+
+ let u8_from_u16_1: Option<u8> = u16_1.try_as_u8();
+ let u8_from_u16_2: Option<u8> = <u8 as TryFrom<u16>>::try_from(u16_1);
+
+ let u8_from_u32_1: Option<u8> = u32_1.try_as_u8();
+ let u8_from_u32_2: Option<u8> = <u8 as TryFrom<u32>>::try_from(u32_1);
+
+ let u8_from_u64_1: Option<u8> = u64_1.try_as_u8();
+ let u8_from_u64_2: Option<u8> = <u8 as TryFrom<u64>>::try_from(u64_1);
+
+ let u8_from_u256: Option<u8> = <u8 as TryFrom<u256>>::try_from(u256_1);
+Bytesuse std::{bytes::Bytes, bytes_conversions::{b256::*, u16::*, u256::*, u32::*, u64::*}};
+ let num = 5;
+ let little_endian_bytes: Bytes = num.to_le_bytes();
+ let big_endian_bytes: Bytes = num.to_be_bytes();
+Bytesuse std::{bytes::Bytes, bytes_conversions::{b256::*, u16::*, u256::*, u32::*, u64::*}};
+ let u16_from_le_bytes: u16 = u16::from_le_bytes(little_endian_bytes);
+ let u16_from_be_bytes: u16 = u16::from_be_bytes(big_endian_bytes);
+
+ let u32_from_le_bytes: u32 = u32::from_le_bytes(little_endian_bytes);
+ let u32_from_be_bytes: u32 = u32::from_be_bytes(big_endian_bytes);
+
+ let u64_from_le_bytes: u64 = u64::from_le_bytes(little_endian_bytes);
+ let u64_from_be_bytes: u64 = u64::from_be_bytes(big_endian_bytes);
+
+ let u256_from_le_bytes = u256::from_le_bytes(little_endian_bytes);
+ let u256_from_be_bytes = u256::from_be_bytes(big_endian_bytes);
+
+ let b256_from_le_bytes = b256::from_le_bytes(little_endian_bytes);
+ let b256_from_be_bytes = b256::from_be_bytes(big_endian_bytes);
+use std::array_conversions::{b256::*, u16::*, u256::*, u32::*, u64::*};
+ let u16_1: u16 = 2u16;
+ let u32_1: u32 = 2u32;
+ let u64_1: u64 = 2u64;
+ let u256_1: u256 = 0x0000000000000000000000000000000000000000000000000000000000000002u256;
+ let b256_1: b256 = 0x000000000000000000000000000000000000000000000000000000000000002A;
+ // little endian
+ let le_byte_array_from_u16: [u8; 2] = u16_1.to_le_bytes();
+ let le_byte_array_from_u32: [u8; 4] = u32_1.to_le_bytes();
+ let le_byte_array_from_u64: [u8; 8] = u64_1.to_le_bytes();
+ let le_byte_array_from_u256: [u8; 32] = u256_1.to_le_bytes();
+ let le_byte_array_from_b256: [u8; 32] = b256_1.to_le_bytes();
+ // big endian
+ let be_byte_array_from_u16: [u8; 2] = u16_1.to_be_bytes();
+ let be_byte_array_from_u32: [u8; 4] = u32_1.to_be_bytes();
+ let be_byte_array_from_u64: [u8; 8] = u64_1.to_be_bytes();
+ let be_byte_array_from_u256: [u8; 32] = u256_1.to_be_bytes();
+ let be_byte_array_from_b256: [u8; 32] = b256_1.to_be_bytes();
+use std::array_conversions::{b256::*, u16::*, u256::*, u32::*, u64::*};
+ let u16_byte_array: [u8; 2] = [2_u8, 1_u8];
+ let u32_byte_array: [u8; 4] = [4_u8, 3_u8, 2_u8, 1_u8];
+ let u64_byte_array: [u8; 8] = [8_u8, 7_u8, 6_u8, 5_u8, 4_u8, 3_u8, 2_u8, 1_u8];
+ let u256_byte_array: [u8; 32] = [
+ 32_u8, 31_u8, 30_u8, 29_u8, 28_u8, 27_u8, 26_u8, 25_u8, 24_u8, 23_u8, 22_u8,
+ 21_u8, 20_u8, 19_u8, 18_u8, 17_u8, 16_u8, 15_u8, 14_u8, 13_u8, 12_u8, 11_u8,
+ 10_u8, 9_u8, 8_u8, 7_u8, 6_u8, 5_u8, 4_u8, 3_u8, 2_u8, 1_u8,
+ ];
+ // little endian
+ let le_u16_from_byte_array: u16 = u16::from_le_bytes(u16_byte_array);
+ let le_u32_from_byte_array: u32 = u32::from_le_bytes(u32_byte_array);
+ let le_u64_from_byte_array: u64 = u64::from_le_bytes(u64_byte_array);
+ let le_u256_from_byte_array: u256 = u256::from_le_bytes(u256_byte_array);
+ let le_b256_from_byte_array: b256 = b256::from_le_bytes(u256_byte_array);
+ // big endian
+ let be_u16_from_byte_array: u16 = u16::from_be_bytes(u16_byte_array);
+ let be_u32_from_byte_array: u32 = u32::from_be_bytes(u32_byte_array);
+ let be_u64_from_byte_array: u64 = u64::from_be_bytes(u64_byte_array);
+ let be_u256_from_byte_array: u256 = u256::from_be_bytes(u256_byte_array);
+ let be_b256_from_byte_array: b256 = b256::from_be_bytes(u256_byte_array);
+Functions in Sway are declared with the fn keyword. Let's take a look:
fn equals(first_param: u64, second_param: u64) -> bool {
+ first_param == second_param
+}
+We have just declared a function named equals which takes two parameters: first_param and second_param. The parameters must both be 64-bit unsigned integers.
This function also returns a bool value, i.e. either true or false. This function returns true if the two given parameters are equal, and false if they are not. If we want to use this function, we can do so like this:
fn main() {
+ equals(5, 5); // evaluates to `true`
+ equals(5, 6); // evaluates to `false`
+}
+We can make a function parameter mutable by adding ref mut before the parameter name. This allows mutating the argument passed into the function when the function is called.
For example:
+fn increment(ref mut num: u32) {
+ let prev = num;
+ num = prev + 1u32;
+}
+This function is allowed to mutate its parameter num because of the mut keyword. In addition, the ref keyword instructs the function to modify the argument passed to it when the function is called, instead of modifying a local copy of it.
let mut num: u32 = 0;
+ increment(num);
+ assert(num == 1u32); // The function `increment()` modifies `num`
+Note that the variable num itself has to be declared as mutable for the above to compile.
++Note +It is not currently allowed to use
+mutwithoutrefor vice versa for a function parameter.
Similarly, ref mut can be used with more complex data types such as:
fn swap_tuple(ref mut pair: (u64, u64)) {
+ let temp = pair.0;
+ pair.0 = pair.1;
+ pair.1 = temp;
+}
+
+fn update_color(ref mut color: Color, new_color: Color) {
+ color = new_color;
+}
+We can then call these functions as shown below:
+ let mut tuple = (42, 24);
+ swap_tuple(tuple);
+ assert(tuple.0 == 24); // The function `swap_tuple()` modifies `tuple.0`
+ assert(tuple.1 == 42); // The function `swap_tuple()` modifies `tuple.1`
+ let mut color = Color::Red;
+ update_color(color, Color::Blue);
+ assert(match color {
+ Color::Blue => true,
+ _ => false,
+ }); // The function `update_color()` modifies the color to Blue
+++Note +The only place, in a Sway program, where the
+refkeyword is valid is before a mutable function parameter.
Structs in Sway are a named grouping of types. You may also be familiar with structs via another name: product types. Sway does not make any significantly unique usages of structs; they are similar to most other languages which have structs. If you're coming from an object-oriented background, a struct is like the data attributes of an object.
+Those data attributes are called fields and can be either public or private.
+Private struct fields can be accessed only within the module in which their struct is declared. Public fields are accessible everywhere where the struct is accessible. This access control on the field level allows more fine grained encapsulation of data.
+ +To explain these concepts, let's take a look at the following example, in which we have a module called data_structures.
+In that module, we declare a struct named Foo with two fields. The first field is named bar, it is public and it accepts values of type u64. The second field is named baz, it is also public and it accepts bool values.
In a similar way, we define the structs Point, Line, and TupleInStruct. Since all those structs are public, and all their fields are public, they can be instantiated in other modules using the struct instantiation syntax as shown below.
On the other hand, the struct StructWithPrivateFields can be instantiated only within the data_structures module, because it contains private fields. To be able to create instances of such structs outside of the module in which they are declared, the struct must offer constructor associated functions.
// the _data_structures_ module
+library;
+
+// Declare a struct type
+pub struct Foo {
+ pub bar: u64,
+ pub baz: bool,
+}
+
+// Struct types for destructuring
+pub struct Point {
+ pub x: u64,
+ pub y: u64,
+}
+
+pub struct Line {
+ pub p1: Point,
+ pub p2: Point,
+}
+
+pub struct TupleInStruct {
+ pub nested_tuple: (u64, (u32, (bool, str))),
+}
+
+// Struct type instantiable only in the module _data_structures_
+pub struct StructWithPrivateFields {
+ pub public_field: u64,
+ private_field: u64,
+ other_private_field: u64,
+}
+In order to instantiate the struct we use struct instantiation syntax, which is very similar to the declaration syntax except with expressions in place of types.
+There are three ways to instantiate the struct.
+library;
+
+mod data_structures;
+use data_structures::{Foo, Line, Point, TupleInStruct};
+
+fn hardcoded_instantiation() -> Foo {
+ // Instantiate `foo` as `Foo`
+ let mut foo = Foo {
+ bar: 42,
+ baz: false,
+ };
+
+ // Access and write to "baz"
+ foo.baz = true;
+
+ // Return the struct
+ foo
+}
+
+fn variable_instantiation() -> Foo {
+ // Declare variables with the same names as the fields in `Foo`
+ let number = 42;
+ let truthness = false;
+
+ // Instantiate `foo` as `Foo`
+ let mut foo = Foo {
+ bar: number,
+ baz: truthness,
+ };
+
+ // Access and write to "baz"
+ foo.baz = true;
+
+ // Return the struct
+ foo
+}
+
+fn shorthand_instantiation() -> Foo {
+ // Declare variables with the same names as the fields in `Foo`
+ let bar = 42;
+ let baz = false;
+
+ // Instantiate `foo` as `Foo`
+ let mut foo = Foo { bar, baz };
+
+ // Access and write to "baz"
+ foo.baz = true;
+
+ // Return the struct
+ foo
+}
+
+fn struct_destructuring() {
+ let point1 = Point { x: 0, y: 0 };
+ // Destructure the values from the struct into variables
+ let Point { x, y } = point1;
+
+ let point2 = Point { x: 1, y: 1 };
+ // If you do not care about specific struct fields then use ".." at the end of your variable list
+ let Point { x, .. } = point2;
+
+ let line = Line {
+ p1: point1,
+ p2: point2,
+ };
+ // Destructure the values from the nested structs into variables
+ let Line {
+ p1: Point { x: x0, y: y0 },
+ p2: Point { x: x1, y: y1 },
+ } = line;
+ // You may also destructure tuples nested in structs and structs nested in tuples
+ let tuple_in_struct = TupleInStruct {
+ nested_tuple: (42u64, (42u32, (true, "ok"))),
+ };
+ let TupleInStruct {
+ nested_tuple: (a, (b, (c, d))),
+ } = tuple_in_struct;
+
+ let struct_in_tuple = (Point { x: 2, y: 4 }, Point { x: 3, y: 6 });
+ let (Point { x: x0, y: y0 }, Point { x: x1, y: y1 }) = struct_in_tuple;
+}
+++Note +You can mix and match all 3 ways to instantiate the struct at the same time. +Moreover, the order of the fields does not matter when instantiating however we encourage declaring the fields in alphabetical order and instantiating them in the same alphabetical order
+
Furthermore, multiple variables can be extracted from a struct using the destructuring syntax.
+++Note +This information is not vital if you are new to the language, or programming in general
+
Structs have zero memory overhead. What that means is that in memory, each struct field is laid out sequentially. No metadata regarding the struct's name or other properties is preserved at runtime. In other words, structs are compile-time constructs. This is the same in Rust, but different in other languages with runtimes like Java.
+Tuples are a basic static-length type which contain multiple different types within themselves. The type of a tuple is defined by the types of the values within it, and a tuple can contain basic types as well as structs and enums.
+You can access values directly by using the . syntax. Moreover, multiple variables can be extracted from a tuple using the destructuring syntax.
library;
+
+fn tuple() {
+ // You can declare the types yourself
+ let tuple1: (u8, bool, u64) = (100, false, 10000);
+
+ // Or have the types be inferred
+ let mut tuple2 = (5, true, ("Sway", 8));
+
+ // Retrieve values from tuples
+ let number = tuple1.0;
+ let sway = tuple2.2.1;
+
+ // Destructure the values from the tuple into variables
+ let (n1, truthness, n2) = tuple1;
+
+ // If you do not care about specific values then use "_"
+ let (_, truthness, _) = tuple2;
+
+ // Internally mutate the tuple
+ tuple2.1 = false;
+
+ // Or change the values all at once (must keep the same data types)
+ tuple2 = (9, false, ("Fuel", 99));
+}
+Enumerations, or enums, are also known as sum types. An enum is a type that could be one of several variants. To declare an enum, you enumerate all potential variants.
+ +Here, we have defined five potential colors. Each enum variant is just the color name. As there is no extra data associated with each variant, we say that each variant is of type (), or unit.
library;
+
+// Declare the enum
+enum Color {
+ Blue: (),
+ Green: (),
+ Red: (),
+ Silver: (),
+ Grey: (),
+}
+
+fn main() {
+ // To instantiate a variable with the value of an enum the syntax is
+ let blue = Color::Blue;
+ let silver = Color::Silver;
+}
+It is also possible to have an enum variant contain extra data. Take a look at this more substantial example, which combines struct declarations with enum variants:
+library;
+
+struct Item {
+ price: u64,
+ amount: u64,
+ id: u64,
+}
+
+enum MyEnum {
+ Item: Item,
+}
+
+fn main() {
+ let my_enum = MyEnum::Item(Item {
+ price: 5,
+ amount: 2,
+ id: 42,
+ });
+}
+It is possible to define enums of enums:
+library;
+
+pub enum Error {
+ StateError: StateError,
+ UserError: UserError,
+}
+
+pub enum StateError {
+ Void: (),
+ Pending: (),
+ Completed: (),
+}
+
+pub enum UserError {
+ InsufficientPermissions: (),
+ Unauthorized: (),
+}
+The preferred way to use enums is to use the individual (not nested) enums directly because they are easy to follow and the lines are short:
+library;
+
+use ::enum_of_enums::{StateError, UserError};
+
+fn preferred() {
+ let error1 = StateError::Void;
+ let error2 = UserError::Unauthorized;
+}
+If you wish to use the nested form of enums via the Error enum from the example above, then you can instantiate them into variables using the following syntax:
library;
+
+use ::enum_of_enums::{Error, StateError, UserError};
+
+fn avoid() {
+ let error1 = Error::StateError(StateError::Void);
+ let error2 = Error::UserError(UserError::Unauthorized);
+}
+Key points to note:
+Error enum++Note +This information is not vital if you are new to the language, or programming in general.
+
Enums do have some memory overhead. To know which variant is being represented, Sway stores a one-word (8-byte) tag for the enum variant. The space reserved after the tag is equivalent to the size of the largest enum variant. So, to calculate the size of an enum in memory, add 8 bytes to the size of the largest variant. For example, in the case of Color above, where the variants are all (), the size would be 8 bytes since the size of the largest variant is 0 bytes.
Methods are similar to functions in that we declare them with the fn keyword and they have parameters and return a value. However, unlike functions, Methods are defined within the context of a struct (or enum), and either refers to that type or mutates it. The first parameter of a method is always self, which represents the instance of the struct (or enum) the method is being called on.
Associated functions are very similar to methods, in that they are also defined in the context of a struct or enum, but they do not actually use any of the data in the struct and as a result do not take self as a parameter. Associated functions could be standalone functions, but they are included in a specific type for organizational or semantic reasons.
+Constructors are associated functions that construct, or in other words instantiate, new instances of a type. Their return type is always the type itself. E.g., public structs that have private fields must provide a public constructor, or otherwise they cannot be instantiated outside of the module in which they are declared.
+To declare methods and associated functions for a struct or enum, use an impl block. Here, impl is short for implementation.
script;
+
+struct Foo {
+ bar: u64,
+ baz: bool,
+}
+
+impl Foo {
+ // this is a _method_, as it takes `self` as a parameter.
+ fn is_baz_true(self) -> bool {
+ self.baz
+ }
+
+ // this is an _associated function_, since it does not take `self` as a parameter.
+ // it is at the same time a _constructor_ because it instantiates and returns
+ // a new instance of `Foo`.
+ fn new_foo(number: u64, boolean: bool) -> Foo {
+ Foo {
+ bar: number,
+ baz: boolean,
+ }
+ }
+}
+
+fn main() {
+ let foo = Foo::new_foo(42, true);
+ assert(foo.is_baz_true());
+}
+To call a method, simply use dot syntax: foo.iz_baz_true().
Similarly to free functions, methods and associated functions may accept ref mut parameters.
For example:
+struct Coordinates {
+ x: u64,
+ y: u64,
+}
+
+impl Coordinates {
+ fn move_right(ref mut self, distance: u64) {
+ self.x += distance;
+ }
+}
+and when called:
+ let mut point = Coordinates { x: 1, y: 1 };
+ point.move_right(5);
+ assert(point.x == 6);
+ assert(point.y == 1);
+Constants are similar to variables; however, there are a few differences:
+impl scope.mut keyword cannot be used with constants.const ID: u32 = 0;
+Constant initializer expressions can be quite complex, but they cannot use, for
+instance, assembly instructions, storage access, mutable variables, loops and
+return statements. Although, function calls, primitive types and compound data
+structures are perfectly fine to use:
fn bool_to_num(b: bool) -> u64 {
+ if b {
+ 1
+ } else {
+ 0
+ }
+}
+
+fn arr_wrapper(a: u64, b: u64, c: u64) -> [u64; 3] {
+ [a, b, c]
+}
+
+const ARR2 = arr_wrapper(bool_to_num(1) + 42, 2, 3);
+Associated constants are constants associated with a type and can be declared in an impl block or in a trait definition.
Associated constants declared inside a trait definition may omit their initializers to indicate that each implementation of the trait must specify those initializers.
The identifier is the name of the constant used in the path. The type is the type that the +definition has to implement.
+ +You can define an associated const directly in the interface surface of a trait:
script;
+
+trait ConstantId {
+ const ID: u32 = 0;
+}
+Alternatively, you can also declare it in the trait, and implement it in the interface of the +types implementing the trait.
+script;
+
+trait ConstantId {
+ const ID: u32;
+}
+
+struct Struct {}
+
+impl ConstantId for Struct {
+ const ID: u32 = 1;
+}
+
+fn main() -> u32 {
+ Struct::ID
+}
+impl self ConstantsConstants can also be declared inside non-trait impl blocks.
script;
+
+struct Point {
+ x: u64,
+ y: u64,
+}
+
+impl Point {
+ const ZERO: Point = Point { x: 0, y: 0 };
+}
+
+fn main() -> u64 {
+ Point::ZERO.x
+}
+Configurable constants are special constants that behave like regular constants in the sense that they cannot change during program execution, but they can be configured after the Sway program has been built. The Rust and TS SDKs allow updating the values of these constants by injecting new values for them directly in the bytecode without having to build the program again. These are useful for contract factories and behave somewhat similarly to immutable variables from languages like Solidity.
Configurable constants are declared inside a configurable block and require a type ascription and an initializer as follows:
configurable {
+ U8: u8 = 8u8,
+ BOOL: bool = true,
+ ARRAY: [u32; 3] = [253u32, 254u32, 255u32],
+ STR_4: str[4] = __to_str_array("fuel"),
+ STRUCT: StructWithGeneric<u8> = StructWithGeneric {
+ field_1: 8u8,
+ field_2: 16,
+ },
+ ENUM: EnumWithGeneric<bool> = EnumWithGeneric::VariantOne(true),
+}
+At most one configurable block is allowed in a Sway project. Moreover, configurable blocks are not allowed in libraries.
Configurable constants can be read directly just like regular constants:
+ fn return_configurables() -> (u8, bool, [u32; 3], str[4], StructWithGeneric<u8>) {
+ (U8, BOOL, ARRAY, STR_4, STRUCT)
+ }
+Comments in Sway start with two slashes and continue until the end of the line. For comments that extend beyond a single line, you'll need to include // on each line.
// hello world
+// let's make a couple of lines
+// commented.
+You can also place comments at the ends of lines containing code.
+fn main() {
+ let baz = 8; // Eight is a lucky number
+}
+You can also do block comments
+fn main() {
+ /*
+ You can write on multiple lines
+ like this if you want
+ */
+ let baz = 8;
+}
+The logging library provides a generic log function that can be imported using use std::logging::log and used to log variables of any type. Each call to log appends a receipt to the list of receipts. There are two types of receipts that a log can generate: Log and LogData.
fn log_values(){
+ // Generates a Log receipt
+ log(42);
+
+ // Generates a LogData receipt
+ let string = "sway";
+ log(string);
+}
+Log ReceiptThe Log receipt is generated for non-reference types, namely bool, u8, u16, u32, and u64.
For example, logging an integer variable x that holds the value 42 using log(x) may generate the following receipt:
"Log": {
+ "id": "0000000000000000000000000000000000000000000000000000000000000000",
+ "is": 10352,
+ "pc": 10404,
+ "ra": 42,
+ "rb": 1018205,
+ "rc": 0,
+ "rd": 0
+}
+Note that ra will include the value being logged. The additional registers rc and rd will be zero when using log while rb may include a non-zero value representing a unique ID for the log instance. The unique ID is not meaningful on its own but allows the Rust and the TS SDKs to know the type of the data being logged, by looking up the log ID in the JSON ABI file.
LogData ReceiptLogData is generated for reference types which include all types except for non_reference types; and for non-reference types bigger than 64-bit integers, for example, u256;
For example, logging a b256 variable b that holds the value 0x1111111111111111111111111111111111111111111111111111111111111111 using log(b) may generate the following receipt:
"LogData": {
+ "data": "1111111111111111111111111111111111111111111111111111111111111111",
+ "digest": "02d449a31fbb267c8f352e9968a79e3e5fc95c1bbeaa502fd6454ebde5a4bedc",
+ "id": "0000000000000000000000000000000000000000000000000000000000000000",
+ "is": 10352,
+ "len": 32,
+ "pc": 10444,
+ "ptr": 10468,
+ "ra": 0,
+ "rb": 1018194
+}
+Note that data in the receipt above will include the value being logged as a hexadecimal. Similarly to the Log receipt, additional registers are written: ra will always be zero when using log, while rb will contain a unique ID for the log instance.
++Note +The Rust SDK exposes APIs that allow you to retrieve the logged values and display them nicely based on their types as indicated in the JSON ABI file.
+
if expressionsSway supports if, else, and else if expressions that allow you to branch your code depending on conditions.
+ +For example:
+fn main() {
+ let number = 6;
+
+ if number % 4 == 0 {
+ // do something
+ } else if number % 3 == 0 {
+ // do something else
+ } else {
+ // do something else
+ }
+}
+if in a let statementLike Rust, ifs are expressions in Sway. What this means is you can use if expressions on the right side of a let statement to assign the outcome to a variable.
let my_data = if some_bool < 10 { foo() } else { bar() };
+Note that all branches of the if expression must return a value of the same type.
match expressionsSway supports advanced pattern matching through exhaustive match expressions. Unlike an if expression, a match expression asserts at compile time that all possible patterns have been matched. If you don't handle all the patterns, you will get compiler error indicating that your match expression is non-exhaustive.
The basic syntax of a match expression is as follows:
let result = match expression {
+ pattern1 => code_to_execute_if_expression_matches_pattern1,
+ pattern2 => code_to_execute_if_expression_matches_pattern2,
+ pattern3 | pattern4 => code_to_execute_if_expression_matches_pattern3_or_pattern4
+ ...
+ _ => code_to_execute_if_expression_matches_no_pattern,
+}
+Some examples of how you can use a match expression:
script;
+
+// helper functions for our example
+fn on_even(num: u64) {
+ // do something with even numbers
+}
+fn on_odd(num: u64) {
+ // do something with odd numbers
+}
+
+fn main(num: u64) -> u64 {
+ // Match as an expression
+ let is_even = match num % 2 {
+ 0 => true,
+ _ => false,
+ };
+
+ // Match as control flow
+ let x = 12;
+ match x {
+ 5 => on_odd(x),
+ _ => on_even(x),
+ };
+
+ // Match an enum
+ enum Weather {
+ Sunny: (),
+ Rainy: (),
+ Cloudy: (),
+ Snowy: (),
+ }
+ let current_weather = Weather::Sunny;
+ let avg_temp = match current_weather {
+ Weather::Sunny => 80,
+ Weather::Rainy => 50,
+ Weather::Cloudy => 60,
+ Weather::Snowy => 20,
+ };
+
+ let is_sunny = match current_weather {
+ Weather::Sunny => true,
+ Weather::Rainy | Weather::Cloudy | Weather::Snowy => false,
+ };
+
+ // match expression used for a return
+ let outside_temp = Weather::Sunny;
+ match outside_temp {
+ Weather::Sunny => 80,
+ Weather::Rainy => 50,
+ Weather::Cloudy => 60,
+ Weather::Snowy => 20,
+ }
+}
+whileThis is what a while loop looks like:
while counter < 10 {
+ counter = counter + 1;
+}
+You need the while keyword, some condition (value < 10 in this case) which will be evaluated each iteration, and a block of code inside the curly braces ({...}) to execute each iteration.
forThis is what a for loop that computes the sum of a vector of numbers looks like:
for element in vector.iter() {
+ sum += element;
+}
+You need the for keyword, some pattern that contains variable names such as element in this case, the ìn keyword followed by an iterator, and a block of code inside the curly braces ({...}) to execute each iteration. vector.iter() in the example above returns an iterator for the vector. In each iteration, the value of element is updated with the next value in the iterator until the end of the vector is reached and the for loop iteration ends.
Modifying the vector during iteration, by e.g. adding or removing elements, is a logical error and results in an undefined behavior:
// The behavior of this `for` loop is undefined because
+// the `vector` gets modified within the loop.
+for element in vector.iter() {
+ if element == 3 {
+ vector.push(6); // Modification of the vector!
+ }
+}
+break and continuebreak and continue keywords are available to use inside the body of a while or for loop. The purpose of the break statement is to break out of a loop early:
fn break_example() -> u64 {
+ let mut counter = 1;
+ let mut sum = 0;
+ let num = 10;
+ while true {
+ if counter > num {
+ break;
+ }
+ sum += counter;
+ counter += 1;
+ }
+ sum // 1 + 2 + .. + 10 = 55
+}
+The purpose of the continue statement is to skip a portion of a loop in an iteration and jump directly into the next iteration:
fn continue_example() -> u64 {
+ let mut counter = 0;
+ let mut sum = 0;
+ let num = 10;
+ while counter < num {
+ counter += 1;
+ if counter % 2 == 0 {
+ continue;
+ }
+ sum += counter;
+ }
+ sum // 1 + 3 + .. + 9 = 25
+}
+You can also use nested while loops if needed:
while condition_1 == true {
+ // do stuff...
+ while condition_2 == true {
+ // do more stuff...
+ }
+}
+Sway is fundamentally a blockchain language. Because of this, it has some features and requirements that you may not have seen in general-purpose programming languages.
+These are also some concepts related to the FuelVM and Fuel ecosystem that you may utilize when writing Sway.
+The Sway standard library provides easy access to a selection of cryptographic hash functions (sha256 and EVM-compatible keccak256), and EVM-compatible secp256k1-based signature recovery operations.
script;
+
+use std::hash::*;
+
+impl Hash for Location {
+ fn hash(self, ref mut state: Hasher) {
+ match self {
+ Location::Earth => {
+ 0_u8.hash(state);
+ }
+ Location::Mars => {
+ 1_u8.hash(state);
+ }
+ }
+ }
+}
+
+impl Hash for Stats {
+ fn hash(self, ref mut state: Hasher) {
+ self.strength.hash(state);
+ self.agility.hash(state);
+ }
+}
+
+impl Hash for Person {
+ fn hash(self, ref mut state: Hasher) {
+ self.name.hash(state);
+ self.age.hash(state);
+ self.alive.hash(state);
+ self.location.hash(state);
+ self.stats.hash(state);
+ self.some_tuple.hash(state);
+ self.some_array.hash(state);
+ self.some_b256.hash(state);
+ }
+}
+
+const VALUE_A = 0x9280359a3b96819889d30614068715d634ad0cf9bba70c0f430a8c201138f79f;
+
+enum Location {
+ Earth: (),
+ Mars: (),
+}
+
+struct Person {
+ name: str,
+ age: u64,
+ alive: bool,
+ location: Location,
+ stats: Stats,
+ some_tuple: (bool, u64),
+ some_array: [u64; 2],
+ some_b256: b256,
+}
+
+struct Stats {
+ strength: u64,
+ agility: u64,
+}
+
+fn main() {
+ let zero = b256::min();
+ // Use the generic sha256 to hash some integers
+ let sha_hashed_u8 = sha256(u8::max());
+ let sha_hashed_u16 = sha256(u16::max());
+ let sha_hashed_u32 = sha256(u32::max());
+ let sha_hashed_u64 = sha256(u64::max());
+
+ // Or hash a b256
+ let sha_hashed_b256 = sha256(VALUE_A);
+
+ // You can hash booleans too
+ let sha_hashed_bool = sha256(true);
+
+ // Strings are not a problem either
+ let sha_hashed_str = sha256("Fastest Modular Execution Layer!");
+
+ // Tuples of any size work too
+ let sha_hashed_tuple = sha256((true, 7));
+
+ // As do arrays
+ let sha_hashed_array = sha256([4, 5, 6]);
+
+ // Enums work too
+ let sha_hashed_enum = sha256(Location::Earth);
+
+ // Complex structs are not a problem
+ let sha_hashed_struct = sha256(Person {
+ name: "John",
+ age: 9000,
+ alive: true,
+ location: Location::Mars,
+ stats: Stats {
+ strength: 10,
+ agility: 9,
+ },
+ some_tuple: (true, 8),
+ some_array: [17, 76],
+ some_b256: zero,
+ });
+
+ log(sha_hashed_u8);
+ log(sha_hashed_u16);
+ log(sha_hashed_u32);
+ log(sha_hashed_u64);
+ log(sha_hashed_b256);
+ log(sha_hashed_bool);
+ log(sha_hashed_str);
+ log(sha_hashed_tuple);
+ log(sha_hashed_array);
+ log(sha_hashed_enum);
+ log(sha_hashed_struct);
+
+ // Use the generic keccak256 to hash some integers
+ let keccak_hashed_u8 = keccak256(u8::max());
+ let keccak_hashed_u16 = keccak256(u16::max());
+ let keccak_hashed_u32 = keccak256(u32::max());
+ let keccak_hashed_u64 = keccak256(u64::max());
+
+ // Or hash a b256
+ let keccak_hashed_b256 = keccak256(VALUE_A);
+
+ // You can hash booleans too
+ let keccak_hashed_bool = keccak256(true);
+
+ // Strings are not a problem either
+ let keccak_hashed_str = keccak256("Fastest Modular Execution Layer!");
+
+ // Tuples of any size work too
+ let keccak_hashed_tuple = keccak256((true, 7));
+
+ // As do arrays
+ let keccak_hashed_array = keccak256([4, 5, 6]);
+
+ // Enums work too
+ let keccak_hashed_enum = keccak256(Location::Earth);
+
+ // Complex structs are not a problem
+ let keccak_hashed_struct = keccak256(Person {
+ name: "John",
+ age: 9000,
+ alive: true,
+ location: Location::Mars,
+ stats: Stats {
+ strength: 10,
+ agility: 9,
+ },
+ some_tuple: (true, 8),
+ some_array: [17, 76],
+ some_b256: zero,
+ });
+
+ log(keccak_hashed_u8);
+ log(keccak_hashed_u16);
+ log(keccak_hashed_u32);
+ log(keccak_hashed_u64);
+ log(keccak_hashed_b256);
+ log(keccak_hashed_bool);
+ log(keccak_hashed_str);
+ log(keccak_hashed_tuple);
+ log(keccak_hashed_array);
+ log(keccak_hashed_enum);
+ log(keccak_hashed_struct);
+}
+Fuel supports 3 asymmetric cryptographic signature schemes; Secp256k1, Secp256r1, and Ed25519.
Given a Signature and a sign Message, you can recover a PublicKey.
// Secp256rk1 Public Key Recovery
+ let secp256k1_signature: Signature = Signature::Secp256k1(Secp256k1::from((
+ 0x61f3caf4c0912cec69ff0b226638d397115c623a7f057914d48a7e4daf1cf6d8,
+ 0x2555de81cd3a40382d3d64eb1c77e463eea5a76d65ec85f283e0b3d568352678,
+ )));
+ let signed_message = Message::from(0xa13f4ab54057ce064d3dd97ac3ff30ed704e73956896c03650fe59b1a561fe15);
+ // A recovered public key pair.
+ let secp256k1_public_key = secp256k1_signature.recover(signed_message);
+ assert(secp256k1_public_key.is_ok());
+ assert(
+ secp256k1_public_key
+ .unwrap() == PublicKey::from((
+ 0x41a55558a3486b6ee3878f55f16879c0798afd772c1506de44aba90d29b6e65c,
+ 0x341ca2e0a3d5827e78d838e35b29bebe2a39ac30b58999e1138c9467bf859965,
+ )),
+ );
+
+ // Secp256r1 Public Key Recovery
+ let secp256r1_signature = Signature::Secp256r1(Secp256r1::from((
+ 0xbd0c9b8792876712afadbff382e1bf31c44437823ed761cc3600d0016de511ac,
+ 0x44ac566bd156b4fc71a4a4cb2655d3da360c695edb27dc3b64d621e122fea23d,
+ )));
+ let signed_message = Message::from(0x1e45523606c96c98ba970ff7cf9511fab8b25e1bcd52ced30b81df1e4a9c4323);
+ // A recovered public key pair.
+ let secp256r1_public_key = secp256r1_signature.recover(signed_message);
+ assert(secp256r1_public_key.is_ok());
+ assert(
+ secp256r1_public_key
+ .unwrap() == PublicKey::from((
+ 0xd6ea577a54ae42411fbc78d686d4abba2150ca83540528e4b868002e346004b2,
+ 0x62660ecce5979493fe5684526e8e00875b948e507a89a47096bc84064a175452,
+ )),
+ );
+Given a Signature and signed Message, you can recover a Fuel Address.
// Secp256k1 Address Recovery
+ let secp256k1_signature = Signature::Secp256k1(Secp256k1::from((
+ 0x61f3caf4c0912cec69ff0b226638d397115c623a7f057914d48a7e4daf1cf6d8,
+ 0x2555de81cd3a40382d3d64eb1c77e463eea5a76d65ec85f283e0b3d568352678,
+ )));
+ let signed_message = Message::from(0xa13f4ab54057ce064d3dd97ac3ff30ed704e73956896c03650fe59b1a561fe15);
+ // A recovered Fuel address.
+ let secp256k1_address = secp256k1_signature.address(signed_message);
+ assert(secp256k1_address.is_ok());
+ assert(
+ secp256k1_address
+ .unwrap() == Address::from(0x02844f00cce0f608fa3f0f7408bec96bfd757891a6fda6e1fa0f510398304881),
+ );
+
+ // Secp256r1 Address Recovery
+ let secp256r1_signature = Signature::Secp256r1(Secp256r1::from((
+ 0xbd0c9b8792876713afa8bf3383eebf31c43437823ed761cc3600d0016de5110c,
+ 0x44ac566bd156b4fc71a4a4cb2655d3dd360c695edb17dc3b64d611e122fea23d,
+ )));
+ let signed_message = Message::from(0xee45573606c96c98ba970ff7cf9511f1b8b25e6bcd52ced30b89df1e4a9c4323);
+ // A recovered Fuel address.
+ let secp256r1_address = secp256r1_signature.address(signed_message);
+ assert(secp256r1_address.is_ok());
+ assert(
+ secp256r1_address
+ .unwrap() == Address::from(0xb4a5fabee8cc852084b71f17107e9c18d682033a58967027af0ab01edf2f9a6a),
+ );
+
+Recovery of EVM addresses is also supported.
+ // Secp256k1 EVM Address Recovery
+ let secp256k1_signature = Signature::Secp256k1(Secp256k1::from((
+ 0xbd0c9b8792876713afa8bff383eebf31c43437823ed761cc3600d0016de5110c,
+ 0x44ac566bd156b4fc71a4a4cb2655d3dd360c695edb17dc3b64d611e122fea23d,
+ )));
+ let signed_message = Message::from(0xee45573606c96c98ba970ff7cf9511f1b8b25e6bcd52ced30b89df1e4a9c4323);
+ // A recovered EVM address.
+ let secp256k1_evm_address = secp256k1_signature.evm_address(signed_message);
+ assert(secp256k1_evm_address.is_ok());
+ assert(
+ secp256k1_evm_address
+ .unwrap() == EvmAddress::from(0x0000000000000000000000000ec44cf95ce5051ef590e6d420f8e722dd160ecb),
+ );
+
+ // Secp256r1 EVM Address Recovery
+ let secp256r1_signature = Signature::Secp256r1(Secp256r1::from((
+ 0x62CDC20C0AB6AA7B91E63DA9917792473F55A6F15006BC99DD4E29420084A3CC,
+ 0xF4D99AF28F9D6BD96BDAAB83BFED99212AC3C7D06810E33FBB14C4F29B635414,
+ )));
+ let signed_message = Message::from(0x290decd9548b62a8d60345a988386fc84ba6bc95484008f6362f93160ef3e563);
+ // A recovered EVM address.
+ let secp256r1_evm_address = secp256r1_signature.evm_address(signed_message);
+ assert(secp256r1_evm_address.is_ok());
+ assert(
+ secp256r1_evm_address
+ .unwrap() == EvmAddress::from(0x000000000000000000000000408eb2d97ef0beda0a33848d9e052066667cb00a),
+ );
+Given a Signature, PublicKey, and Message, you can verify that the message was signed using the public key.
// Secp256k1 Signature Verification
+ let secp256k1_signature = Signature::Secp256k1(Secp256k1::from((
+ 0x61f3caf4c0912cec69ff0b226638d397115c623a7f057914d48a7e4daf1cf6d8,
+ 0x2555de81cd3a40382d3d64eb1c77e463eea5a76d65ec85f283e0b3d568352678,
+ )));
+ let secp256k1_public_key = PublicKey::from((
+ 0x41a55558a3486b6ee3878f55f16879c0798afd772c1506de44aba90d29b6e65c,
+ 0x341ca2e0a3d5827e78d838e35b29bebe2a39ac30b58999e1138c9467bf859965,
+ ));
+ let signed_message = Message::from(0xa13f4ab54057ce064d3dd97ac3ff30ed704e73956896c03650fe59b1a561fe15);
+ // A verified public key
+ let secp256k1_verified = secp256k1_signature.verify(secp256k1_public_key, signed_message);
+ assert(secp256k1_verified.is_ok());
+
+ // Secp256r1 Signature Verification
+ let secp256r1_signature = Signature::Secp256r1(Secp256r1::from((
+ 0xbd0c9b8792876712afadbff382e1bf31c44437823ed761cc3600d0016de511ac,
+ 0x44ac566bd156b4fc71a4a4cb2655d3da360c695edb27dc3b64d621e122fea23d,
+ )));
+ let secp256r1_public_key = PublicKey::from((
+ 0xd6ea577a54ae42411fbc78d686d4abba2150ca83540528e4b868002e346004b2,
+ 0x62660ecce5979493fe5684526e8e00875b948e507a89a47096bc84064a175452,
+ ));
+ let signed_message = Message::from(0x1e45523606c96c98ba970ff7cf9511fab8b25e1bcd52ced30b81df1e4a9c4323);
+ // A verified public key
+ let secp256r1_verified = secp256r1_signature.verify(secp256r1_public_key, signed_message);
+ assert(secp256r1_verified.is_ok());
+
+ // Ed25519 Signature Verification
+ let ed25519_public_key = PublicKey::from(0x314fa58689bbe1da2430517de2d772b384a1c1d2e9cb87e73c6afcf246045b10);
+ let ed25519_signature = Signature::Ed25519(Ed25519::from((
+ 0xf38cef9361894be6c6e0eddec28a663d099d7ddff17c8077a1447d7ecb4e6545,
+ 0xf5084560039486d3462dd65a40c80a74709b2f06d450ffc5dc00345c6b2cdd00,
+ )));
+ let hashed_message = Message::from(sha256(b256::zero()));
+ // A verified public key
+ let ed25519_verified = ed25519_signature.verify(ed25519_public_key, hashed_message);
+ assert(ed25519_verified.is_ok());
+Given a Signature, Address, and Message, you can verify that the message was signed by the address.
// Secp256k1 Address Verification
+ let secp256k1_address = Address::from(0x02844f00cce0f608fa3f0f7408bec96bfd757891a6fda6e1fa0f510398304881);
+ let secp256k1_signature = Secp256k1::from((
+ 0x61f3caf4c0912cec69ff0b226638d397115c623a7f057914d48a7e4daf1cf6d8,
+ 0x2555de81cd3a40382d3d64eb1c77e463eea5a76d65ec85f283e0b3d568352678,
+ ));
+ let signed_message = Message::from(0xa13f4ab54057ce064d3dd97ac3ff30ed704e73956896c03650fe59b1a561fe15);
+ // A verified address
+ let secp256k1_verified = secp256k1_signature.verify_address(secp256k1_address, signed_message);
+ assert(secp256k1_verified.is_ok());
+
+ // Secp256r1 Address Verification
+ let secp256r1_address = Address::from(0xb4a5fabee8cc852084b71f17107e9c18d682033a58967027af0ab01edf2f9a6a);
+ let secp256r1_signature = Signature::Secp256r1(Secp256r1::from((
+ 0xbd0c9b8792876713afa8bf3383eebf31c43437823ed761cc3600d0016de5110c,
+ 0x44ac566bd156b4fc71a4a4cb2655d3dd360c695edb17dc3b64d611e122fea23d,
+ )));
+ let signed_message = Message::from(0xee45573606c96c98ba970ff7cf9511f1b8b25e6bcd52ced30b89df1e4a9c4323);
+ // A verified address
+ let secp256r1_verified = secp256r1_signature.verify_address(secp256r1_address, signed_message);
+ assert(secp256r1_verified.is_ok());
+
+Recovery of EVM addresses verification is also supported.
+ // Secp256k1 Address Verification
+ let secp256k1_evm_address = EvmAddress::from(0x0000000000000000000000000ec44cf95ce5051ef590e6d420f8e722dd160ecb);
+ let secp256k1_signature = Signature::Secp256k1(Secp256k1::from((
+ 0xbd0c9b8792876713afa8bff383eebf31c43437823ed761cc3600d0016de5110c,
+ 0x44ac566bd156b4fc71a4a4cb2655d3dd360c695edb17dc3b64d611e122fea23d,
+ )));
+ let signed_message = Message::from(0xee45573606c96c98ba970ff7cf9511f1b8b25e6bcd52ced30b89df1e4a9c4323);
+ // A recovered EVM address.
+ let secp256k1_verified = secp256k1_signature.verify_evm_address(secp256k1_evm_address, signed_message);
+ assert(secp256k1_verified.is_ok());
+
+ // Secp256r1 Address Verification
+ let secp256r1_evm_address = EvmAddress::from(0x000000000000000000000000408eb2d97ef0beda0a33848d9e052066667cb00a);
+ let secp256r1_signature = Signature::Secp256r1(Secp256r1::from((
+ 0x62CDC20C0AB6AA7B91E63DA9917792473F55A6F15006BC99DD4E29420084A3CC,
+ 0xF4D99AF28F9D6BD96BDAAB83BFED99212AC3C7D06810E33FBB14C4F29B635414,
+ )));
+ let signed_message = Message::from(0x290decd9548b62a8d60345a988386fc84ba6bc95484008f6362f93160ef3e563);
+ // A recovered EVM address.
+ let secp256r1_verified = secp256r1_signature.verify_evm_address(secp256r1_evm_address, signed_message);
+ assert(secp256r1_verified.is_ok());
+When developing a smart contract, you will typically need some sort of persistent storage. In this case, persistent storage, often just called storage in this context, is a place where you can store values that are persisted inside the contract itself. This is in contrast to a regular value in memory, which disappears after the contract exits.
+Put in conventional programming terms, contract storage is like saving data to a hard drive. That data is saved even after the program that saved it exits. That data is persistent. Using memory is like declaring a variable in a program: it exists for the duration of the program and is non-persistent.
+Some basic use cases of storage include declaring an owner address for a contract and saving balances in a wallet.
+ +storage KeywordDeclaring variables in storage requires a storage block that contains a list of all your variables, their types, and their initial values. The initial value can be any expression that can be evaluated to a constant during compilation, as follows:
storage {
+ var1: u64 = 1,
+ var2: b256 = b256::zero(),
+ var3: Address = Address::zero(),
+ var4: Option<u8> = None,
+}
+To write into a storage variable, you need to use the storage keyword as follows:
storage.var1.write(42);
+ storage
+ .var2
+ .write(0x1111111111111111111111111111111111111111111111111111111111111111);
+ storage
+ .var3
+ .write(Address::from(0x1111111111111111111111111111111111111111111111111111111111111111));
+ storage.var4.write(Some(2u8));
+To read a storage variable, you also need to use the storage keyword. You may use read() or try_read(), however we recommend using try_read() for additional safety.
let var1: u64 = storage.var1.read();
+ let var2: b256 = storage.var2.try_read().unwrap_or(b256::zero());
+ let var3: Address = storage.var3.try_read().unwrap_or(Address::zero());
+ let var4: Option<u8> = storage.var4.try_read().unwrap_or(None);
+To store a struct in storage, each variable must be assigned in the storage block. This can be either my assigning the fields individually or using a public constructor that can be evaluated to a constant during compilation.
struct Type1 {
+ x: u64,
+ y: u64,
+}
+
+struct Type2 {
+ w: b256,
+ z: bool,
+}
+
+impl Type2 {
+ // a constructor that evaluates to a constant during compilation
+ fn default() -> Self {
+ Self {
+ w: 0x0000000000000000000000000000000000000000000000000000000000000000,
+ z: true,
+ }
+ }
+}
+
+storage {
+ var1: Type1 = Type1 { x: 0, y: 0 },
+ var2: Type2 = Type2::default(),
+}
+You may write to both fields of a struct and the entire struct as follows:
+ // Store individual fields
+ storage.var1.x.write(42);
+ storage.var1.y.write(77);
+
+ // Store an entire struct
+ let new_struct = Type2 {
+ w: 0x1111111111111111111111111111111111111111111111111111111111111111,
+ z: false,
+ };
+ storage.var2.write(new_struct);
+The same applies to reading structs from storage, where both the individual and struct as a whole may be read as follows:
+ let var1_x: u64 = storage.var1.x.try_read().unwrap_or(0);
+ let var1_y: u64 = storage.var1.y.try_read().unwrap_or(0);
+ let var2: Type2 = storage.var2.try_read().unwrap_or(Type2::default());
+We support the following common storage collections:
+StorageMap<K, V>StorageVec<T>StorageBytesStorageStringPlease note that these types are not initialized during compilation. This means that if you try to access a key from a storage map before the storage has been set, for example, the call will revert.
+Declaring these variables in storage requires a storage block as follows:
storage {
+ storage_map: StorageMap<u64, bool> = StorageMap {},
+ storage_vec: StorageVec<b256> = StorageVec {},
+ storage_string: StorageString = StorageString {},
+ storage_bytes: StorageBytes = StorageBytes {},
+}
+StorageMaps<K, V>Generic storage maps are available in the standard library as StorageMap<K, V> which have to be defined inside a storage block and allow you to call insert() and get() to insert values at specific keys and get those values respectively. Refer to Storage Maps for more information about StorageMap<K, V>.
Warning While the StorageMap<K, V> is currently included in the prelude, to use it the Hash trait must still be imported. This is a known issue and will be resolved.
use std::hash::Hash;
+
+use std::storage::storage_vec::*;
+
+use std::storage::storage_bytes::*;
+
+use std::storage::storage_string::*;
+
+storage {
+ storage_map: StorageMap<u64, bool> = StorageMap {},
+ storage_vec: StorageVec<b256> = StorageVec {},
+ storage_string: StorageString = StorageString {},
+ storage_bytes: StorageBytes = StorageBytes {},
+}
+
+abi StorageExample {
+ #[storage(write)]
+ fn store_map();
+ #[storage(read)]
+ fn get_map();
+ #[storage(write)]
+ fn store_vec();
+ #[storage(read, write)]
+ fn get_vec();
+ #[storage(write)]
+ fn store_string();
+ #[storage(read)]
+ fn get_string();
+ #[storage(write)]
+ fn store_bytes();
+ #[storage(read)]
+ fn get_bytes();
+}
+
+impl StorageExample for Contract {
+ #[storage(write)]
+ fn store_map() {
+ storage.storage_map.insert(12, true);
+ storage.storage_map.insert(59, false);
+
+ // try_insert() will only insert if a value does not already exist for a key.
+ let result = storage.storage_map.try_insert(103, true);
+ assert(result.is_ok());
+ }
+ #[storage(read)]
+ fn get_map() {
+ // Access directly
+ let stored_val1: bool = storage.storage_map.get(12).try_read().unwrap_or(false);
+
+ // First get the storage key and then access the value.
+ let storage_key2: StorageKey<bool> = storage.storage_map.get(59);
+ let stored_val2: bool = storage_key2.try_read().unwrap_or(false);
+
+ // Unsafely access the value.
+ let stored_val3: bool = storage.storage_map.get(103).read();
+ }
+
+ #[storage(write)]
+ fn store_vec() {
+ storage
+ .storage_vec
+ .push(0x1111111111111111111111111111111111111111111111111111111111111111);
+ storage
+ .storage_vec
+ .push(0x0000000000000000000000000000000000000000000000000000000000000001);
+ storage
+ .storage_vec
+ .push(0x0000000000000000000000000000000000000000000000000000000000000002);
+
+ // Set will overwrite the element stored at the given index.
+ storage.storage_vec.set(2, b256::zero());
+ }
+ #[storage(read, write)]
+ fn get_vec() {
+ // Method 1: Access the element directly
+ // Note: get() does not remove the element from the vec.
+ let stored_val1: b256 = storage.storage_vec.get(0).unwrap().try_read().unwrap_or(b256::zero());
+
+ // Method 2: First get the storage key and then access the value.
+ let storage_key2: StorageKey<b256> = storage.storage_vec.get(1).unwrap();
+ let stored_val2: b256 = storage_key2.try_read().unwrap_or(b256::zero());
+
+ // pop() will remove the last element from the vec.
+ let length: u64 = storage.storage_vec.len();
+ let stored_val3: b256 = storage.storage_vec.pop().unwrap();
+ assert(length != storage.storage_vec.len());
+ }
+
+ #[storage(write)]
+ fn store_string() {
+ let my_string = String::from_ascii_str("Fuel is blazingly fast");
+ storage.storage_string.write_slice(my_string);
+ }
+ #[storage(read)]
+ fn get_string() {
+ let stored_string: String = storage.storage_string.read_slice().unwrap();
+ }
+
+ #[storage(write)]
+ fn store_bytes() {
+ // Setup Bytes
+ let mut my_bytes = Bytes::new();
+ my_bytes.push(1u8);
+ my_bytes.push(2u8);
+ my_bytes.push(3u8);
+
+ // Write to storage
+ storage.storage_bytes.write_slice(my_bytes);
+ }
+ #[storage(read)]
+ fn get_bytes() {
+ let stored_bytes: Bytes = storage.storage_bytes.read_slice().unwrap();
+ }
+}
+To write to a storage map, call either the insert() or try_insert() functions as follows:
storage.storage_map.insert(12, true);
+ storage.storage_map.insert(59, false);
+
+ // try_insert() will only insert if a value does not already exist for a key.
+ let result = storage.storage_map.try_insert(103, true);
+ assert(result.is_ok());
+The following demonstrates how to read from a storage map:
+ // Access directly
+ let stored_val1: bool = storage.storage_map.get(12).try_read().unwrap_or(false);
+
+ // First get the storage key and then access the value.
+ let storage_key2: StorageKey<bool> = storage.storage_map.get(59);
+ let stored_val2: bool = storage_key2.try_read().unwrap_or(false);
+
+ // Unsafely access the value.
+ let stored_val3: bool = storage.storage_map.get(103).read();
+StorageVec<T>Generic storage vectors are available in the standard library as StorageVec<T> which have to be defined inside a storage block and allow you to call push() and pop() to push and pop values from a vector respectively. Refer to Storage Vector for more information about StorageVec<T>.
The following demonstrates how to import StorageVec<T>:
use std::storage::storage_vec::*;
+
+use std::storage::storage_bytes::*;
+
+use std::storage::storage_string::*;
+
+storage {
+ storage_map: StorageMap<u64, bool> = StorageMap {},
+ storage_vec: StorageVec<b256> = StorageVec {},
+ storage_string: StorageString = StorageString {},
+ storage_bytes: StorageBytes = StorageBytes {},
+}
+
+abi StorageExample {
+ #[storage(write)]
+ fn store_map();
+ #[storage(read)]
+ fn get_map();
+ #[storage(write)]
+ fn store_vec();
+ #[storage(read, write)]
+ fn get_vec();
+ #[storage(write)]
+ fn store_string();
+ #[storage(read)]
+ fn get_string();
+ #[storage(write)]
+ fn store_bytes();
+ #[storage(read)]
+ fn get_bytes();
+}
+
+impl StorageExample for Contract {
+ #[storage(write)]
+ fn store_map() {
+ storage.storage_map.insert(12, true);
+ storage.storage_map.insert(59, false);
+
+ // try_insert() will only insert if a value does not already exist for a key.
+ let result = storage.storage_map.try_insert(103, true);
+ assert(result.is_ok());
+ }
+ #[storage(read)]
+ fn get_map() {
+ // Access directly
+ let stored_val1: bool = storage.storage_map.get(12).try_read().unwrap_or(false);
+
+ // First get the storage key and then access the value.
+ let storage_key2: StorageKey<bool> = storage.storage_map.get(59);
+ let stored_val2: bool = storage_key2.try_read().unwrap_or(false);
+
+ // Unsafely access the value.
+ let stored_val3: bool = storage.storage_map.get(103).read();
+ }
+
+ #[storage(write)]
+ fn store_vec() {
+ storage
+ .storage_vec
+ .push(0x1111111111111111111111111111111111111111111111111111111111111111);
+ storage
+ .storage_vec
+ .push(0x0000000000000000000000000000000000000000000000000000000000000001);
+ storage
+ .storage_vec
+ .push(0x0000000000000000000000000000000000000000000000000000000000000002);
+
+ // Set will overwrite the element stored at the given index.
+ storage.storage_vec.set(2, b256::zero());
+ }
+ #[storage(read, write)]
+ fn get_vec() {
+ // Method 1: Access the element directly
+ // Note: get() does not remove the element from the vec.
+ let stored_val1: b256 = storage.storage_vec.get(0).unwrap().try_read().unwrap_or(b256::zero());
+
+ // Method 2: First get the storage key and then access the value.
+ let storage_key2: StorageKey<b256> = storage.storage_vec.get(1).unwrap();
+ let stored_val2: b256 = storage_key2.try_read().unwrap_or(b256::zero());
+
+ // pop() will remove the last element from the vec.
+ let length: u64 = storage.storage_vec.len();
+ let stored_val3: b256 = storage.storage_vec.pop().unwrap();
+ assert(length != storage.storage_vec.len());
+ }
+
+ #[storage(write)]
+ fn store_string() {
+ let my_string = String::from_ascii_str("Fuel is blazingly fast");
+ storage.storage_string.write_slice(my_string);
+ }
+ #[storage(read)]
+ fn get_string() {
+ let stored_string: String = storage.storage_string.read_slice().unwrap();
+ }
+
+ #[storage(write)]
+ fn store_bytes() {
+ // Setup Bytes
+ let mut my_bytes = Bytes::new();
+ my_bytes.push(1u8);
+ my_bytes.push(2u8);
+ my_bytes.push(3u8);
+
+ // Write to storage
+ storage.storage_bytes.write_slice(my_bytes);
+ }
+ #[storage(read)]
+ fn get_bytes() {
+ let stored_bytes: Bytes = storage.storage_bytes.read_slice().unwrap();
+ }
+}
+++NOTE: When importing the
+StorageVec<T>, please be sure to use the glob operator:use std::storage::storage_vec::*.
The following demonstrates how to write to a StorageVec<T>:
storage
+ .storage_vec
+ .push(0x1111111111111111111111111111111111111111111111111111111111111111);
+ storage
+ .storage_vec
+ .push(0x0000000000000000000000000000000000000000000000000000000000000001);
+ storage
+ .storage_vec
+ .push(0x0000000000000000000000000000000000000000000000000000000000000002);
+
+ // Set will overwrite the element stored at the given index.
+ storage.storage_vec.set(2, b256::zero());
+The following demonstrates how to read from a StorageVec<T>:
// Method 1: Access the element directly
+ // Note: get() does not remove the element from the vec.
+ let stored_val1: b256 = storage.storage_vec.get(0).unwrap().try_read().unwrap_or(b256::zero());
+
+ // Method 2: First get the storage key and then access the value.
+ let storage_key2: StorageKey<b256> = storage.storage_vec.get(1).unwrap();
+ let stored_val2: b256 = storage_key2.try_read().unwrap_or(b256::zero());
+
+ // pop() will remove the last element from the vec.
+ let length: u64 = storage.storage_vec.len();
+ let stored_val3: b256 = storage.storage_vec.pop().unwrap();
+ assert(length != storage.storage_vec.len());
+StorageBytesStorage of Bytes is available in the standard library as StorageBytes which have to be defined inside a storage block. StorageBytes cannot be manipulated in the same way a StorageVec<T> or StorageMap<K, V> can but stores bytes more efficiently thus reducing gas. Only the entirety of a Bytes may be read/written to storage. This means any changes would require loading the entire Bytes to the heap, making changes, and then storing it once again. If frequent changes are needed, a StorageVec<u8> is recommended.
The following demonstrates how to import StorageBytes:
use std::storage::storage_bytes::*;
+
+use std::storage::storage_string::*;
+
+storage {
+ storage_map: StorageMap<u64, bool> = StorageMap {},
+ storage_vec: StorageVec<b256> = StorageVec {},
+ storage_string: StorageString = StorageString {},
+ storage_bytes: StorageBytes = StorageBytes {},
+}
+
+abi StorageExample {
+ #[storage(write)]
+ fn store_map();
+ #[storage(read)]
+ fn get_map();
+ #[storage(write)]
+ fn store_vec();
+ #[storage(read, write)]
+ fn get_vec();
+ #[storage(write)]
+ fn store_string();
+ #[storage(read)]
+ fn get_string();
+ #[storage(write)]
+ fn store_bytes();
+ #[storage(read)]
+ fn get_bytes();
+}
+
+impl StorageExample for Contract {
+ #[storage(write)]
+ fn store_map() {
+ storage.storage_map.insert(12, true);
+ storage.storage_map.insert(59, false);
+
+ // try_insert() will only insert if a value does not already exist for a key.
+ let result = storage.storage_map.try_insert(103, true);
+ assert(result.is_ok());
+ }
+ #[storage(read)]
+ fn get_map() {
+ // Access directly
+ let stored_val1: bool = storage.storage_map.get(12).try_read().unwrap_or(false);
+
+ // First get the storage key and then access the value.
+ let storage_key2: StorageKey<bool> = storage.storage_map.get(59);
+ let stored_val2: bool = storage_key2.try_read().unwrap_or(false);
+
+ // Unsafely access the value.
+ let stored_val3: bool = storage.storage_map.get(103).read();
+ }
+
+ #[storage(write)]
+ fn store_vec() {
+ storage
+ .storage_vec
+ .push(0x1111111111111111111111111111111111111111111111111111111111111111);
+ storage
+ .storage_vec
+ .push(0x0000000000000000000000000000000000000000000000000000000000000001);
+ storage
+ .storage_vec
+ .push(0x0000000000000000000000000000000000000000000000000000000000000002);
+
+ // Set will overwrite the element stored at the given index.
+ storage.storage_vec.set(2, b256::zero());
+ }
+ #[storage(read, write)]
+ fn get_vec() {
+ // Method 1: Access the element directly
+ // Note: get() does not remove the element from the vec.
+ let stored_val1: b256 = storage.storage_vec.get(0).unwrap().try_read().unwrap_or(b256::zero());
+
+ // Method 2: First get the storage key and then access the value.
+ let storage_key2: StorageKey<b256> = storage.storage_vec.get(1).unwrap();
+ let stored_val2: b256 = storage_key2.try_read().unwrap_or(b256::zero());
+
+ // pop() will remove the last element from the vec.
+ let length: u64 = storage.storage_vec.len();
+ let stored_val3: b256 = storage.storage_vec.pop().unwrap();
+ assert(length != storage.storage_vec.len());
+ }
+
+ #[storage(write)]
+ fn store_string() {
+ let my_string = String::from_ascii_str("Fuel is blazingly fast");
+ storage.storage_string.write_slice(my_string);
+ }
+ #[storage(read)]
+ fn get_string() {
+ let stored_string: String = storage.storage_string.read_slice().unwrap();
+ }
+
+ #[storage(write)]
+ fn store_bytes() {
+ // Setup Bytes
+ let mut my_bytes = Bytes::new();
+ my_bytes.push(1u8);
+ my_bytes.push(2u8);
+ my_bytes.push(3u8);
+
+ // Write to storage
+ storage.storage_bytes.write_slice(my_bytes);
+ }
+ #[storage(read)]
+ fn get_bytes() {
+ let stored_bytes: Bytes = storage.storage_bytes.read_slice().unwrap();
+ }
+}
+++NOTE: When importing the
+StorageBytes, please be sure to use the glob operator:use std::storage::storage_bytes::*.
The following demonstrates how to write to a StorageBytes:
// Setup Bytes
+ let mut my_bytes = Bytes::new();
+ my_bytes.push(1u8);
+ my_bytes.push(2u8);
+ my_bytes.push(3u8);
+
+ // Write to storage
+ storage.storage_bytes.write_slice(my_bytes);
+The following demonstrates how to read from a StorageBytes:
let stored_bytes: Bytes = storage.storage_bytes.read_slice().unwrap();
+StorageStringStorage of String is available in the standard library as StorageString which have to be defined inside a storage block. StorageString cannot be manipulated in the same way a StorageVec<T> or StorageMap<K, V>. Only the entirety of a String may be read/written to storage.
The following demonstrates how to import StorageString:
use std::storage::storage_string::*;
+
+storage {
+ storage_map: StorageMap<u64, bool> = StorageMap {},
+ storage_vec: StorageVec<b256> = StorageVec {},
+ storage_string: StorageString = StorageString {},
+ storage_bytes: StorageBytes = StorageBytes {},
+}
+
+abi StorageExample {
+ #[storage(write)]
+ fn store_map();
+ #[storage(read)]
+ fn get_map();
+ #[storage(write)]
+ fn store_vec();
+ #[storage(read, write)]
+ fn get_vec();
+ #[storage(write)]
+ fn store_string();
+ #[storage(read)]
+ fn get_string();
+ #[storage(write)]
+ fn store_bytes();
+ #[storage(read)]
+ fn get_bytes();
+}
+
+impl StorageExample for Contract {
+ #[storage(write)]
+ fn store_map() {
+ storage.storage_map.insert(12, true);
+ storage.storage_map.insert(59, false);
+
+ // try_insert() will only insert if a value does not already exist for a key.
+ let result = storage.storage_map.try_insert(103, true);
+ assert(result.is_ok());
+ }
+ #[storage(read)]
+ fn get_map() {
+ // Access directly
+ let stored_val1: bool = storage.storage_map.get(12).try_read().unwrap_or(false);
+
+ // First get the storage key and then access the value.
+ let storage_key2: StorageKey<bool> = storage.storage_map.get(59);
+ let stored_val2: bool = storage_key2.try_read().unwrap_or(false);
+
+ // Unsafely access the value.
+ let stored_val3: bool = storage.storage_map.get(103).read();
+ }
+
+ #[storage(write)]
+ fn store_vec() {
+ storage
+ .storage_vec
+ .push(0x1111111111111111111111111111111111111111111111111111111111111111);
+ storage
+ .storage_vec
+ .push(0x0000000000000000000000000000000000000000000000000000000000000001);
+ storage
+ .storage_vec
+ .push(0x0000000000000000000000000000000000000000000000000000000000000002);
+
+ // Set will overwrite the element stored at the given index.
+ storage.storage_vec.set(2, b256::zero());
+ }
+ #[storage(read, write)]
+ fn get_vec() {
+ // Method 1: Access the element directly
+ // Note: get() does not remove the element from the vec.
+ let stored_val1: b256 = storage.storage_vec.get(0).unwrap().try_read().unwrap_or(b256::zero());
+
+ // Method 2: First get the storage key and then access the value.
+ let storage_key2: StorageKey<b256> = storage.storage_vec.get(1).unwrap();
+ let stored_val2: b256 = storage_key2.try_read().unwrap_or(b256::zero());
+
+ // pop() will remove the last element from the vec.
+ let length: u64 = storage.storage_vec.len();
+ let stored_val3: b256 = storage.storage_vec.pop().unwrap();
+ assert(length != storage.storage_vec.len());
+ }
+
+ #[storage(write)]
+ fn store_string() {
+ let my_string = String::from_ascii_str("Fuel is blazingly fast");
+ storage.storage_string.write_slice(my_string);
+ }
+ #[storage(read)]
+ fn get_string() {
+ let stored_string: String = storage.storage_string.read_slice().unwrap();
+ }
+
+ #[storage(write)]
+ fn store_bytes() {
+ // Setup Bytes
+ let mut my_bytes = Bytes::new();
+ my_bytes.push(1u8);
+ my_bytes.push(2u8);
+ my_bytes.push(3u8);
+
+ // Write to storage
+ storage.storage_bytes.write_slice(my_bytes);
+ }
+ #[storage(read)]
+ fn get_bytes() {
+ let stored_bytes: Bytes = storage.storage_bytes.read_slice().unwrap();
+ }
+}
+++NOTE: When importing the
+StorageString, please be sure to use the glob operator:use std::storage::storage_string::*.
The following demonstrates how to write to a StorageString:
let my_string = String::from_ascii_str("Fuel is blazingly fast");
+ storage.storage_string.write_slice(my_string);
+The following demonstrates how to read from a StorageString:
let stored_string: String = storage.storage_string.read_slice().unwrap();
+For more advanced storage techniques please refer to the Advanced Storage page.
+A function is pure if it does not access any persistent storage. Conversely, the function is impure if it does access any storage. Naturally, as storage is only available in smart contracts, impure functions cannot be used in predicates, scripts, or libraries. A pure function cannot call an impure function.
+In Sway, functions are pure by default but can be opted into impurity via the storage function attribute. The storage attribute may take read and/or write arguments indicating which type of access the function requires.
The storage attribute without any arguments, #[storage()], indicates a pure function, and has the same effect as not having the attribute at all.
#[storage(read)]
+fn get_amount() -> u64 {
+ ...
+}
+
+#[storage(read, write)]
+fn increment_amount(increment: u64) -> u64 {
+ ...
+}
+
+fn a_pure_function() {
+ ...
+}
+
+#[storage()]
+fn also_a_pure_function() {
+ ...
+}
+++ + +Note: the
+#[storage(write)]attribute also permits a function to read from storage. This is due to the fact that partially writing a storage slot requires first reading the slot.
Impure functions which call other impure functions must have at least the same storage privileges or a superset of those for the function called. For example, to call a function with write access a caller must also have write access, or both read and write access. To call a function with read and write access the caller must also have both privileges.
+ +The storage attribute may also be applied to methods and associated functions, trait and ABI declarations.
A pure function gives you some guarantees: you will not incur excessive storage gas costs, the compiler can apply additional optimizations, and they are generally easy to reason about and audit.
+++ +Note: Purity does not provide an absolute guarantee that a storage access will not happen as a result of calling a pure function. E.g., it is possible for a pure function to call another contract, which can then call a write function in the original contract. The guarantee that the purity gives in this example is, that the original pure function itself does not change the storage, as well as that any function later called, that accesses storage, is clearly marked as impure.
+
A similar concept exists in Solidity. Note that Solidity refers to contract storage as contract state, and in the Sway/Fuel ecosystem, these two terms are largely interchangeable.
+Addresses in Sway are similar to EVM addresses. The two major differences are:
+Contracts, on the other hand, are uniquely identified with a contract ID rather than an address. A contract's ID is also 32 bytes long and is calculated here.
+The FuelVM has built-in support for working with multiple assets.
+On the EVM, Ether is the native asset. As such, sending ETH to an address or contract is an operation built into the EVM, meaning it doesn't rely on the existence of a smart contract to update balances to track ownership as with ERC-20 tokens.
+On the FuelVM, all assets are native and the process for sending any native asset is the same.
+While you would still need a smart contract to handle the minting and burning of assets, the sending and receiving of these assets can be done independently of the asset contract.
+Just like the EVM however, Fuel has a standard that describes a standard API for Native Assets using the Sway Language. The ERC-20 equivalent for the Sway Language is the SRC-20; Native Asset Standard.
+++NOTE It is important to note that Fuel does not have tokens.
+
On the EVM, an ERC-721 token or NFT is a contract that contains multiple tokens which are non-fungible with one another.
+On the FuelVM, the ERC-721 equivalent is a Native Asset where each asset has a supply of one. This is defined in the SRC-20; Native Asset Standard under the Non-Fungible Asset Restrictions.
+In practice, this means all NFTs are treated the same as any other Native Asset on Fuel. When writing Sway code, no additional cases for handling non-fungible and fungible assets are required.
+An advantage Native Assets bring is that there is no need for token approvals; as with Ether on the EVM. With millions of dollars hacked every year due to misused token approvals, the FuelVM eliminates this attack vector.
+An "Asset" is a Native Asset on Fuel and has the associated AssetId type. Assets are distinguishable from one another. A "Coin" represents a singular unit of an Asset. Coins of the same Asset are not distinguishable from one another.
Fuel does not use tokens like other ecosystems such as Ethereum and uses Native Assets with a UTXO design instead.
+AssetId typeThe AssetId type represents any Native Asset on Fuel. An AssetId is used for interacting with an asset on the network.
The AssetId of any Native Asset on Fuel is calculated by taking the SHA256 hash digest of the originating ContractId that minted the asset and a SubId i.e. sha256((contract_id, sub_id)).
AssetIdThere are 3 ways to instantiate a new AssetId:
When a contract will only ever mint a single asset, it is recommended to use the DEFAULT_ASSET_ID sub id. This is referred to as the default asset of a contract.
To get the default asset from an internal contract call, call the default() function:
let asset_id: AssetId = AssetId::default();
+If a contract mints multiple assets or if the asset has been minted by an external contract, the new() function will be needed. The new() function takes the ContractId of the contract which minted the token as well as a SubId.
To create a new AssetId using a ContractId and SubId, call the new() function:
let my_contract_id: ContractId = ContractId::from(0x1000000000000000000000000000000000000000000000000000000000000000);
+ let my_sub_id: SubId = 0x2000000000000000000000000000000000000000000000000000000000000000;
+
+ let asset_id: AssetId = AssetId::new(my_contract_id, my_sub_id);
+In the case where the b256 value of an asset is already known, you may call the from() function with the b256 value.
let asset_id: AssetId = AssetId::from(0x0000000000000000000000000000000000000000000000000000000000000000);
+SubId typeThe SubId is used to differentiate between different assets that are created by the same contract. The SubId is a b256 value.
When creating a single new asset on Fuel, we recommend using the DEFAULT_SUB_ID or SubId::zero().
On the Fuel Network, the base asset is Ether. This is the only asset on the Fuel Network that does not have a SubId.
The Base Asset can be returned anytime by calling the base() function of the AssetId type.
let base_asset: AssetId = AssetId::base();
+To mint a new asset, the std::asset::mint() function must be called internally within a contract. A SubId and amount of coins must be provided. These newly minted coins will be owned by the contract which minted them. To mint another asset from the same contract, replace the DEFAULT_SUB_ID with your desired SubId.
mint(DEFAULT_SUB_ID, mint_amount);
+You may also mint an asset to a specific entity with the std::asset::mint_to() function. Be sure to provide a target Identity that will own the newly minted coins.
mint_to(target_identity, DEFAULT_SUB_ID, mint_amount);
+If you intend to allow external users to mint assets using your contract, the SRC-3; Mint and Burn Standard defines a standard API for minting assets. The Sway-Libs Asset Library also provides an additional library to support implementations of the SRC-3 Standard into your contract.
+To burn an asset, the std::asset::burn() function must be called internally from the contract which minted them. The SubId used to mint the coins and amount must be provided. The burned coins must be owned by the contract. When an asset is burned it doesn't exist anymore.
burn(DEFAULT_SUB_ID, burn_amount);
+If you intend to allow external users to burn assets using your contract, the SRC-3; Mint and Burn Standard defines a standard API for burning assets. The Sway-Libs Asset Library also provides an additional library to support implementations of the SRC-3 Standard into your contract.
+To internally transfer a Native Asset, the std::asset::transfer() function must be called. A target Identity or user must be provided as well as the AssetId of the asset and an amount.
transfer(target, asset_id, coins);
+To query for the Native Asset sent in a transaction, you may call the std::call_frames::msg_asset_id() function.
let amount = msg_asset_id();
+To query for the amount of coins sent in a transaction, you may call the std::context::msg_amount() function.
let amount = msg_amount();
+To internally check a contract's balance, call the std::context::this_balance() function with the corresponding AssetId.
this_balance(asset_id)
+To check the balance of an external contract, call the std::context::balance_of() function with the corresponding AssetId.
balance_of(target_contract, asset_id)
+++NOTE Due to the FuelVM's UTXO design, balances of
+Address's cannot be returned in the Sway Language. This must be done off-chain using the SDK.
By default, a contract may not receive a Native Asset in a contract call. To allow transferring of assets to the contract, add the #[payable] attribute to the function.
#[payable]
+ fn deposit() {
+ assert(msg_amount() > 0);
+ }
+There are a number of standards developed to enable further functionality for Native Assets and help cross contract functionality. Information on standards can be found in the Sway Standards Repo.
+We currently have the following standards for Native Assets:
+Additional Libraries have been developed to allow you to quickly create an deploy dApps that follow the Sway Standards.
+In this fully fleshed out example, we show a native asset contract which mints a single asset. This is the equivalent to the ERC-20 Standard use in Ethereum. Note there are no token approval functions.
+It implements the SRC-20; Native Asset, SRC-3; Mint and Burn, and SRC-5; Ownership standards. It does not use any external libraries.
+// ERC20 equivalent in Sway.
+contract;
+
+use standards::{
+ src3::SRC3,
+ src5::{
+ SRC5,
+ State,
+ AccessError,
+ },
+ src20::{
+ SetDecimalsEvent,
+ SetNameEvent,
+ SetSymbolEvent,
+ SRC20,
+ TotalSupplyEvent,
+ },
+};
+use std::{
+ asset::{
+ burn,
+ mint_to,
+ },
+ call_frames::msg_asset_id,
+ constants::DEFAULT_SUB_ID,
+ context::msg_amount,
+ string::String,
+ contract_id::ContractId
+};
+
+configurable {
+ DECIMALS: u8 = 9u8,
+ NAME: str[7] = __to_str_array("MyAsset"),
+ SYMBOL: str[5] = __to_str_array("MYTKN"),
+}
+
+storage {
+ total_supply: u64 = 0,
+ owner: State = State::Uninitialized,
+}
+
+// Native Asset Standard
+impl SRC20 for Contract {
+ #[storage(read)]
+ fn total_assets() -> u64 {
+ 1
+ }
+
+ #[storage(read)]
+ fn total_supply(asset: AssetId) -> Option<u64> {
+ if asset == AssetId::default() {
+ Some(storage.total_supply.read())
+ } else {
+ None
+ }
+ }
+
+ #[storage(read)]
+ fn name(asset: AssetId) -> Option<String> {
+ if asset == AssetId::default() {
+ Some(String::from_ascii_str(from_str_array(NAME)))
+ } else {
+ None
+ }
+ }
+
+ #[storage(read)]
+ fn symbol(asset: AssetId) -> Option<String> {
+ if asset == AssetId::default() {
+ Some(String::from_ascii_str(from_str_array(SYMBOL)))
+ } else {
+ None
+ }
+ }
+
+ #[storage(read)]
+ fn decimals(asset: AssetId) -> Option<u8> {
+ if asset == AssetId::default() {
+ Some(DECIMALS)
+ } else {
+ None
+ }
+ }
+}
+
+// Ownership Standard
+impl SRC5 for Contract {
+ #[storage(read)]
+ fn owner() -> State {
+ storage.owner.read()
+ }
+}
+
+// Mint and Burn Standard
+impl SRC3 for Contract {
+ #[storage(read, write)]
+ fn mint(recipient: Identity, sub_id: Option<SubId>, amount: u64) {
+ require(sub_id.is_some() && sub_id.unwrap() == DEFAULT_SUB_ID, "incorrect-sub-id");
+ require_access_owner();
+
+ let new_supply = storage.total_supply.read() + amount;
+ storage
+ .total_supply
+ .write(new_supply);
+ mint_to(recipient, DEFAULT_SUB_ID, amount);
+
+ TotalSupplyEvent::new(
+ AssetId::default(),
+ new_supply,
+ msg_sender().unwrap()
+ ).log();
+ }
+
+ #[storage(read, write)]
+ fn burn(sub_id: SubId, amount: u64) {
+ require(sub_id == DEFAULT_SUB_ID, "incorrect-sub-id");
+ require(msg_amount() >= amount, "incorrect-amount-provided");
+ require(
+ msg_asset_id() == AssetId::default(),
+ "incorrect-asset-provided",
+ );
+ require_access_owner();
+
+ let new_supply = storage.total_supply.read() - amount;
+ storage
+ .total_supply
+ .write(new_supply);
+ burn(DEFAULT_SUB_ID, amount);
+
+ TotalSupplyEvent::new(
+ AssetId::default(),
+ new_supply,
+ msg_sender().unwrap()
+ ).log();
+ }
+}
+
+abi SingleAsset {
+ #[storage(read, write)]
+ fn constructor(owner_: Identity);
+}
+
+impl SingleAsset for Contract {
+ #[storage(read, write)]
+ fn constructor(owner_: Identity) {
+ require(storage.owner.read() == State::Uninitialized, "owner-initialized");
+ storage.owner.write(State::Initialized(owner_));
+ }
+}
+
+#[storage(read)]
+fn require_access_owner() {
+ require(
+ storage.owner.read() == State::Initialized(msg_sender().unwrap()),
+ AccessError::NotOwner,
+ );
+}
+
+abi EmitSRC20Events {
+ fn emit_src20_events();
+}
+
+impl EmitSRC20Events for Contract {
+ fn emit_src20_events() {
+ // Metadata that is stored as a configurable should only be emitted once.
+ let asset = AssetId::default();
+ let sender = msg_sender().unwrap();
+ let name = Some(String::from_ascii_str(from_str_array(NAME)));
+ let symbol = Some(String::from_ascii_str(from_str_array(SYMBOL)));
+
+ SetNameEvent::new(asset, name, sender).log();
+ SetSymbolEvent::new(asset, symbol, sender).log();
+ SetDecimalsEvent::new(asset, DECIMALS, sender).log();
+ }
+}
+In this fully fleshed out example, we show a native asset contract which mints multiple assets. This is the equivalent to the ERC-1155 Standard use in Ethereum. Note there are no token approval functions.
+It implements the SRC-20; Native Asset, SRC-3; Mint and Burn, and SRC-5; Ownership standards. It does not use any external libraries.
+// ERC1155 equivalent in Sway.
+contract;
+
+use standards::{
+ src5::{
+ SRC5,
+ State,
+ AccessError
+ },
+ src20::{
+ SetDecimalsEvent,
+ SetNameEvent,
+ SetSymbolEvent,
+ SRC20,
+ TotalSupplyEvent,
+ }
+ src3::SRC3,
+};
+use std::{
+ asset::{
+ burn,
+ mint_to,
+ },
+ call_frames::msg_asset_id,
+ hash::{
+ Hash,
+ },
+ context::this_balance,
+ storage::storage_string::*,
+ string::String,
+ contract_id::ContractId
+};
+
+storage {
+ total_assets: u64 = 0,
+ total_supply: StorageMap<AssetId, u64> = StorageMap {},
+ name: StorageMap<AssetId, StorageString> = StorageMap {},
+ symbol: StorageMap<AssetId, StorageString> = StorageMap {},
+ decimals: StorageMap<AssetId, u8> = StorageMap {},
+ owner: State = State::Uninitialized,
+}
+
+// Native Asset Standard
+impl SRC20 for Contract {
+ #[storage(read)]
+ fn total_assets() -> u64 {
+ storage.total_assets.read()
+ }
+
+ #[storage(read)]
+ fn total_supply(asset: AssetId) -> Option<u64> {
+ storage.total_supply.get(asset).try_read()
+ }
+
+ #[storage(read)]
+ fn name(asset: AssetId) -> Option<String> {
+ storage.name.get(asset).read_slice()
+ }
+
+ #[storage(read)]
+ fn symbol(asset: AssetId) -> Option<String> {
+ storage.symbol.get(asset).read_slice()
+ }
+
+ #[storage(read)]
+ fn decimals(asset: AssetId) -> Option<u8> {
+ storage.decimals.get(asset).try_read()
+ }
+}
+
+// Mint and Burn Standard
+impl SRC3 for Contract {
+ #[storage(read, write)]
+ fn mint(recipient: Identity, sub_id: Option<SubId>, amount: u64) {
+ require(sub_id.is_some(), "Error: SubId is None");
+ require_access_owner();
+
+ let asset_id = AssetId::new(ContractId::this(), sub_id.unwrap());
+ let supply = storage.total_supply.get(asset_id).try_read();
+ if supply.is_none() {
+ storage.total_assets.write(storage.total_assets.try_read().unwrap_or(0) + 1);
+ }
+ let new_supply = supply.unwrap_or(0) + amount;
+ storage.total_supply.insert(asset_id, new_supply);
+ mint_to(recipient, sub_id, amount);
+
+ TotalSupplyEvent::new(
+ asset_id,
+ new_supply,
+ msg_sender().unwrap()
+ ).log();
+ }
+
+ #[storage(read, write)]
+ fn burn(sub_id: SubId, amount: u64) {
+ require_access_owner();
+ let asset_id = AssetId::new(ContractId::this(), sub_id);
+ require(this_balance(asset_id) >= amount, "not-enough-coins");
+
+ let supply = storage.total_supply.get(asset_id).try_read();
+ let new_supply = supply.unwrap_or(0) - amount;
+ storage.total_supply.insert(asset_id, new_supply);
+ burn(sub_id, amount);
+
+ TotalSupplyEvent::new(
+ asset_id,
+ new_supply,
+ msg_sender().unwrap()
+ ).log();
+ }
+}
+
+abi MultiAsset {
+ #[storage(read, write)]
+ fn constructor(owner_: Identity);
+
+ #[storage(read, write)]
+ fn set_name(asset: AssetId, name: Option<String>);
+
+ #[storage(read, write)]
+ fn set_symbol(asset: AssetId, symbol: Option<String>);
+
+ #[storage(read, write)]
+ fn set_decimals(asset: AssetId, decimals: u8);
+}
+
+impl MultiAsset for Contract {
+ #[storage(read, write)]
+ fn constructor(owner_: Identity) {
+ require(storage.owner.read() == State::Uninitialized, "owner-initialized");
+ storage.owner.write(State::Initialized(owner_));
+ }
+
+ #[storage(read, write)]
+ fn set_name(asset: AssetId, name: Option<String>) {
+ require_access_owner();
+ storage.name.insert(asset, StorageString {});
+ storage.name.get(asset).write_slice(name);
+
+ SetNameEvent::new(asset, name, msg_sender().unwrap()).log();
+ }
+
+ #[storage(read, write)]
+ fn set_symbol(asset: AssetId, symbol: Option<String>) {
+ require_access_owner();
+ storage.symbol.insert(asset, StorageString {});
+ storage.symbol.get(asset).write_slice(symbol);
+
+ SetSymbolEvent::new(asset, symbol, msg_sender().unwrap()).log();
+ }
+
+ #[storage(read, write)]
+ fn set_decimals(asset: AssetId, decimals: u8) {
+ require_access_owner();
+ storage.decimals.insert(asset, decimals);
+
+ SetDecimalsEvent::new(asset, decimals, msg_sender().unwrap()).log();
+ }
+}
+
+#[storage(read)]
+fn require_access_owner() {
+ require(
+ storage.owner.read() == State::Initialized(msg_sender().unwrap()),
+ AccessError::NotOwner,
+ );
+}
+Smart contracts require the ability to restrict access to and identify certain users or contracts. Unlike account-based blockchains, transactions in UTXO-based blockchains (i.e. Fuel) do not necessarily have a unique transaction sender. Additional logic is needed to handle this difference, and is provided by the standard library.
+ +msg_senderTo deliver an experience akin to the EVM's access control, the std library provides a msg_sender function, which identifies a unique caller based upon the call and/or transaction input data.
contract;
+
+abi MyOwnedContract {
+ fn receive(field_1: u64) -> bool;
+}
+
+const OWNER = Address::from(0x9ae5b658754e096e4d681c548daf46354495a437cc61492599e33fc64dcdc30c);
+
+impl MyOwnedContract for Contract {
+ fn receive(field_1: u64) -> bool {
+ let sender = msg_sender().unwrap();
+ if let Identity::Address(addr) = sender {
+ assert(addr == OWNER);
+ } else {
+ revert(0);
+ }
+
+ true
+ }
+}
+The msg_sender function works as follows:
Ok(Sender) is returned with the ContractId sender variant.Ok(Sender) is returned with the Address sender variant.Err(AuthError) is returned.Many contracts require some form of ownership for access control. The SRC-5 Ownership Standard has been defined to provide an interoperable interface for ownership within contracts.
+To accomplish this, use the Ownership Library to keep track of the owner. This allows setting and revoking ownership using the variants Some(..) and None respectively. This is better, safer, and more readable than using the Identity type directly where revoking ownership has to be done using some magic value such as b256::zero() or otherwise.
#[storage(read)]
+ fn only_owner() {
+ storage.owner.only_owner();
+ // Do stuff here
+ }
+Setting ownership can be done in one of two ways; During compile time or run time.
+storage {
+ owner: Ownership = Ownership::initialized(Identity::Address(Address::zero())),
+}
+ #[storage(write)]
+ fn set_owner(identity: Identity) {
+ storage.owner.set_ownership(identity);
+ }
+ #[storage(write)]
+ fn revoke_ownership() {
+ storage.owner.renounce_ownership();
+ }
+ #[storage(read)]
+ fn owner() -> State {
+ storage.owner.owner()
+ }
+Sway-Libs provides the following libraries to enable further access control.
+Smart contracts can be called by other contracts or scripts. In the FuelVM, this is done primarily with the call instruction.
Sway provides a nice way to manage callable interfaces with its ABI system. The Fuel ABI specification can be found here.
+Here is an example of a contract calling another contract in Sway. A script can call a contract in the same way.
+// ./contract_a.sw
+contract;
+
+abi ContractA {
+ fn receive(field_1: bool, field_2: u64) -> u64;
+}
+
+impl ContractA for Contract {
+ fn receive(field_1: bool, field_2: u64) -> u64 {
+ assert(field_1 == true);
+ assert(field_2 > 0);
+ return_45()
+ }
+}
+
+fn return_45() -> u64 {
+ 45
+}
+// ./contract_b.sw
+contract;
+
+use contract_a::ContractA;
+
+abi ContractB {
+ fn make_call();
+}
+
+const contract_id = 0x79fa8779bed2f36c3581d01c79df8da45eee09fac1fd76a5a656e16326317ef0;
+
+impl ContractB for Contract {
+ fn make_call() {
+ let x = abi(ContractA, contract_id);
+ let return_value = x.receive(true, 3); // will be 45
+ }
+}
+++Note: The ABI is for external calls only therefore you cannot define a method in the ABI and call it in the same contract. If you want to define a function for a contract, but keep it private so that only your contract can call it, you can define it outside of the
+impland call it inside the contract, similar to thereturn_45()function above.
All calls forward a gas stipend, and may additionally forward one native asset with the call.
+Here is an example of how to specify the amount of gas (gas), the asset ID of the native asset (asset_id), and the amount of the native asset (coins) to forward:
script;
+
+abi MyContract {
+ fn foo(field_1: bool, field_2: u64);
+}
+
+fn main() {
+ let x = abi(MyContract, 0x79fa8779bed2f36c3581d01c79df8da45eee09fac1fd76a5a656e16326317ef0);
+ let asset_id = 0x7777_7777_7777_7777_7777_7777_7777_7777_7777_7777_7777_7777_7777_7777_7777_7777;
+ x.foo {
+ gas: 5000, asset_id: asset_id, coins: 5000
+ }
+ (true, 3);
+}
+A common attack vector for smart contracts is re-entrancy. Similar to the EVM, the FuelVM allows for re-entrancy.
+A stateless re-entrancy guard is included in the sway-libs library. The guard will panic (revert) at run time if re-entrancy is detected.
contract;
+
+use reentrancy::reentrancy_guard;
+
+abi MyContract {
+ fn some_method();
+}
+
+impl ContractB for Contract {
+ fn some_method() {
+ reentrancy_guard();
+ // do something
+ }
+}
+Another way of avoiding re-entrancy-related attacks is to follow the so-called +CEI pattern. CEI stands for "Checks, Effects, Interactions", meaning that the +contract code should first perform safety checks, also known as +"pre-conditions", then perform effects, i.e. modify or read the contract storage +and execute external contract calls (interaction) only at the very end of the +function/method.
+Please see this blog post +for more detail on some vulnerabilities in case of storage modification after +interaction and this blog post for +more information on storage reads after interaction.
+The Sway compiler implements a check that the CEI pattern is not violated in the +user contract and issues warnings if that's the case.
+For example, in the following contract the CEI pattern is violated, because an +external contract call is executed before a storage write.
+contract;
+
+mod other_contract;
+
+use other_contract::*;
+use std::hash::*;
+
+abi MyContract {
+ #[storage(read, write)]
+ fn withdraw(external_contract_id: ContractId);
+}
+
+storage {
+ balances: StorageMap<Identity, u64> = StorageMap::<Identity, u64> {},
+}
+
+impl MyContract for Contract {
+ #[storage(read, write)]
+ fn withdraw(external_contract_id: ContractId) {
+ let sender = msg_sender().unwrap();
+ let bal = storage.balances.get(sender).try_read().unwrap_or(0);
+
+ assert(bal > 0);
+
+ // External call
+ let caller = abi(OtherContract, external_contract_id.into());
+ caller.external_call {
+ coins: bal,
+ }();
+
+ // Storage update _after_ external call
+ storage.balances.insert(sender, 0);
+ }
+}
+Here, other_contract is defined as follows:
library;
+
+abi OtherContract {
+ #[payable]
+ fn external_call();
+}
+The CEI pattern analyzer issues a warning as follows, pointing to the +interaction before a storage modification:
+warning
+ --> /path/to/contract/main.sw:28:9
+ |
+26 |
+27 | let caller = abi(OtherContract, external_contract_id.into());
+28 | caller.external_call { coins: bal }();
+ | _________-
+29 | |
+30 | | // Storage update _after_ external call
+31 | | storage.balances.insert(sender, 0);
+ | |__________________________________________- Storage write after external contract interaction in function or method "withdraw". Consider making all storage writes before calling another contract
+32 | }
+33 | }
+ |
+____
+In case there is a storage read after an interaction, the CEI analyzer will issue a similar warning.
+In addition to storage reads and writes after an interaction, the CEI analyzer reports analogous warnings about:
+tr and tro ASM instructions or library functions using them under the hood;bal instruction;__smo intrinsic function or the smo ASM instruction.While the Fuel contract calling paradigm is similar to the EVM's (using an ABI, forwarding gas and data), it differs in two key ways:
+Native assets: FuelVM calls can forward any native asset not just base asset.
+No data serialization: Contract calls in the FuelVM do not need to serialize data to pass it between contracts; instead they simply pass a pointer to the data. This is because the FuelVM has a shared global memory which all call frames can read from.
+When a contract is compiled, a special section called "contract selection" is also generated. This section checks if the contract call method matches any of the available ABI methods. If this fails, one of two possible actions will happen:
+1 - if no fallback function was specified, the contract will revert; +2 - otherwise, the fallback function will be called.
+For all intents and purposes the fallback function is considered a contract method, which means that it has all the limitations that other contract methods have. As the fallback function signature, the function cannot have arguments, but they can return anything.
+If for some reason the fallback function needs to returns different types, the intrinsic __contract_ret can be used.
contract;
+
+abi MyContract {
+ fn some_method();
+}
+
+impl ContractB for Contract {
+ fn some_method() {
+ }
+}
+
+#[fallback]
+fn fallback() {
+}
+You may still access the method selector and arguments to the call in the fallback.
+For instance, let's assume a function fn foobar(bool, u64) {} gets called on a contract that doesn't have it with arguments true and 42.
+It can execute the following fallback:
#[fallback]
+fn fallback() {
+ // the method selector is the first four bytes of sha256("foobar(bool,u64)")
+ // per https://fuellabs.github.io/fuel-specs/master/protocol/abi#function-selector-encoding
+ let method_selector = std::call_frames::first_param::<u64>();
+
+ // the arguments tuple is (true, 42)
+ let arguments = std::call_frames::second_param::<(bool, u64)>();
+}
+The std-lib includes a function called run_external that allows Sway contracts to execute arbitrary external Sway code.
This functionality enables features like upgradeable contracts and +proxies.
+Upgradeable contracts are designed to allow the logic of a smart contract to be updated after deployment.
+Consider this example proxy contract:
+#[namespace(my_storage_namespace)]
+storage {
+ target_contract: Option<ContractId> = None,
+}
+
+impl Proxy for Contract {
+ #[storage(write)]
+ fn set_target_contract(id: ContractId) {
+ storage.target_contract.write(Some(id));
+ }
+
+ #[storage(read)]
+ fn double_input(_value: u64) -> u64 {
+ let target = storage.target_contract.read().unwrap();
+ run_external(target)
+ }
+}
+The contract has two functions:
+set_target_contract updates the target_contract variable in storage with the ContractId of an external contract.double_input reads the target_contract from storage and uses it to run external code. If the target_contract has a function with the same name (double_input), the code in the external double_input function will run.
+In this case, the function will return a u64.Notice in the Proxy example above, the storage block has a namespace attribute. Using this attribute is considered a best practice for all proxy contracts in Sway, because it will prevent storage collisions with the implementation contract, as the implementation contract has access to both storage contexts.
Below is what an implementation contract could look like for this:
+storage {
+ value: u64 = 0,
+ // to stay compatible, this has to stay the same in the next version
+}
+
+impl Implementation for Contract {
+ #[storage(write)]
+ fn double_input(value: u64) -> u64 {
+ let new_value = value * 2;
+ storage.value.write(new_value);
+ new_value
+ }
+}
+This contract has one function called double_input, which calculates the input value times two, updates the value variable in storage, and returns the new value.
There are a couple of major differences between calling a contract directly and using the run_external method.
First, to use run_external, the ABI of the external contract is not required. The proxy contract has no knowledge of the external contract except for its ContractId.
Second, the storage context of the proxy contract is retained for the loaded code.
+This means that in the examples above, the value variable gets updated in the storage for the proxy contract.
For example, if you were to read the value variable by directly calling the implementation contract, you would get a different result than if you read it through the proxy contract.
+The proxy contract loads the code and executes it in its own context.
If the function name doesn't exist in the target contract but a fallback function does, the fallback function will be triggered.
++If there is no fallback function, the transaction will revert.
+
You can access function parameters for fallback functions using the call_frames module in the std-lib.
+For example, to access the _foo input parameter in the proxy function below, you can use the called_args method in the fallback function:
fn does_not_exist_in_the_target(_foo: u64) -> u64 {
+ run_external(TARGET)
+ }
+#[fallback]
+fn fallback() -> u64 {
+ use std::call_frames::*;
+ __log(3);
+ __log(called_method());
+ __log("double_value");
+ __log(called_method() == "double_value");
+ let foo = called_args::<u64>();
+ foo * 3
+}
+In this case, the does_not_exist_in_the_target function will return _foo * 3.
Some limitations of run_external function are:
run_external. You can only use the call stack within the call frame that contains run_external.Advanced concepts.
+Sway provides the ability to declare a type alias to give an existing type another name. For this we use the type keyword. For example, we can create the alias Kilometers to u64 like so:
type Kilometers = u64;
+Now, the alias Kilometers is a synonym for u64. Note that Kilometers is not a separate new type. Values that have the type Kilometers will be treated the same as values of type u64:
let x: u64 = 5;
+ let y: Kilometers = 5;
+ assert(x + y == 10);
+Because Kilometers and u64 are the same type, we can add values of both types and we can pass Kilometers values to functions that take u64 parameters. However, using this method, we don’t get the type checking benefits that we get from introducing a separate new type called Kilometers. In other words, if we mix up Kilometers and i32 values somewhere, the compiler will not give us an error.
The main use case for type synonyms is to reduce repetition. For example, we might have a lengthy array type like this:
+[MyStruct<u64, b256>; 5]
+Writing this lengthy type in function signatures and as type annotations all over the code can be tiresome and error prone. Imagine having a project full of code like this:
+fn foo_long(array: [MyStruct<u64, b256>; 5]) -> [MyStruct<u64, b256>; 5] {
+ array
+}
+A type alias makes this code more manageable by reducing the repetition. Below, we’ve introduced an alias named MyArray for the verbose type and can replace all uses of the type with the shorter alias MyArray:
type MyArray = [MyStruct<u64, b256>; 5];
+
+fn foo_shorter(array: MyArray) -> MyArray {
+ array
+}
+This code is much easier to read and write! Choosing a meaningful name for a type alias can help communicate your intent as well.
+Through the use of StorageKeys, you may have nested storage collections such as storing a StorageString in a StorageMap<K, V>.
For example, here we have a few common nested storage types declared in a storage block:
storage {
+ nested_map_vec: StorageMap<u64, StorageVec<u8>> = StorageMap {},
+ nested_map_string: StorageMap<u64, StorageString> = StorageMap {},
+ nested_vec_bytes: StorageVec<StorageBytes> = StorageVec {},
+}
+Please note that storage initialization is needed to do this.
+++NOTE: When importing a storage type, please be sure to use the glob operator i.e.
+use std::storage::storage_vec::*.
StorageVec<T> in a StorageMap<K, V>The following demonstrates how to write to a StorageVec<T> that is nested in a StorageMap<T, V>:
// Setup and initialize storage for the StorageVec.
+ storage.nested_map_vec.try_insert(10, StorageVec {});
+
+ // Method 1: Push to the vec directly
+ storage.nested_map_vec.get(10).push(1u8);
+ storage.nested_map_vec.get(10).push(2u8);
+ storage.nested_map_vec.get(10).push(3u8);
+
+ // Method 2: First get the storage key and then push the values.
+ let storage_key_vec: StorageKey<StorageVec<u8>> = storage.nested_map_vec.get(10);
+ storage_key_vec.push(4u8);
+ storage_key_vec.push(5u8);
+ storage_key_vec.push(6u8);
+The following demonstrates how to read from a StorageVec<T> that is nested in a StorageMap<T, V>:
// Method 1: Access the StorageVec directly.
+ let stored_val1: u8 = storage.nested_map_vec.get(10).pop().unwrap();
+ let stored_val2: u8 = storage.nested_map_vec.get(10).pop().unwrap();
+ let stored_val3: u8 = storage.nested_map_vec.get(10).pop().unwrap();
+
+ // Method 2: First get the storage key and then access the value.
+ let storage_key: StorageKey<StorageVec<u8>> = storage.nested_map_vec.get(10);
+ let stored_val4: u8 = storage_key.pop().unwrap();
+ let stored_val5: u8 = storage_key.pop().unwrap();
+ let stored_val6: u8 = storage_key.pop().unwrap();
+StorageString in a StorageMap<K, V>The following demonstrates how to write to a StorageString that is nested in a StorageMap<T, V>:
// Setup and initialize storage for the StorageString.
+ storage.nested_map_string.try_insert(10, StorageString {});
+
+ // Method 1: Store the string directly.
+ let my_string = String::from_ascii_str("Fuel is blazingly fast");
+ storage.nested_map_string.get(10).write_slice(my_string);
+
+ // Method 2: First get the storage key and then write the value.
+ let my_string = String::from_ascii_str("Fuel is modular");
+ let storage_key: StorageKey<StorageString> = storage.nested_map_string.get(10);
+ storage_key.write_slice(my_string);
+The following demonstrates how to read from a StorageString that is nested in a StorageMap<T, V>:
// Method 1: Access the string directly.
+ let stored_string: String = storage.nested_map_string.get(10).read_slice().unwrap();
+
+ // Method 2: First get the storage key and then access the value.
+ let storage_key: StorageKey<StorageString> = storage.nested_map_string.get(10);
+ let stored_string: String = storage_key.read_slice().unwrap();
+StorageBytes in a StorageVec<T>The following demonstrates how to write to a StorageBytes that is nested in a StorageVec<T>:
// Setup and initialize storage for the StorageVec.
+ storage.nested_map_vec.try_insert(10, StorageVec {});
+
+ // Method 1: Push to the vec directly
+ storage.nested_map_vec.get(10).push(1u8);
+ storage.nested_map_vec.get(10).push(2u8);
+ storage.nested_map_vec.get(10).push(3u8);
+
+ // Method 2: First get the storage key and then push the values.
+ let storage_key_vec: StorageKey<StorageVec<u8>> = storage.nested_map_vec.get(10);
+ storage_key_vec.push(4u8);
+ storage_key_vec.push(5u8);
+ storage_key_vec.push(6u8);
+The following demonstrates how to read from a StorageBytes that is nested in a StorageVec<T>:
// Method 1: Access the StorageVec directly.
+ let stored_val1: u8 = storage.nested_map_vec.get(10).pop().unwrap();
+ let stored_val2: u8 = storage.nested_map_vec.get(10).pop().unwrap();
+ let stored_val3: u8 = storage.nested_map_vec.get(10).pop().unwrap();
+
+ // Method 2: First get the storage key and then access the value.
+ let storage_key: StorageKey<StorageVec<u8>> = storage.nested_map_vec.get(10);
+ let stored_val4: u8 = storage_key.pop().unwrap();
+ let stored_val5: u8 = storage_key.pop().unwrap();
+ let stored_val6: u8 = storage_key.pop().unwrap();
+If you want the values in storage to be positioned differently, for instance to avoid collisions with storage from another contract when loading code, you can use the namespace annotation to add a salt to the slot calculations.
+storage {
+ example_namespace {
+ foo: u64 = 0,
+ },
+It is possible to leverage FuelVM storage operations directly using the std::storage::storage_api::write and std::storage::storage_api::read functions provided in the standard library. With this approach, you will have to manually assign the internal key used for storage. An example is as follows:
contract;
+
+use std::storage::storage_api::{read, write};
+
+abi StorageExample {
+ #[storage(write)]
+ fn store_something(amount: u64);
+
+ #[storage(read)]
+ fn get_something() -> u64;
+}
+
+const STORAGE_KEY: b256 = 0x0000000000000000000000000000000000000000000000000000000000000000;
+
+impl StorageExample for Contract {
+ #[storage(write)]
+ fn store_something(amount: u64) {
+ write(STORAGE_KEY, 0, amount);
+ }
+
+ #[storage(read)]
+ fn get_something() -> u64 {
+ let value: Option<u64> = read::<u64>(STORAGE_KEY, 0);
+ value.unwrap_or(0)
+ }
+}
+++Note: Though these functions can be used for any data type, they should mostly be used for arrays because arrays are not yet supported in
+storageblocks. Note, however, that all data types can be used as types for keys and/or values inStorageMap<K, V>without any restrictions.
In Sway, generic types follow a very similar pattern to those in Rust. Let's look at some example syntax, +starting with a generic function:
+fn noop<T>(argument: T) -> T {
+ argument
+}
+Here, the noop() function trivially returns exactly what was given to it. T is a type parameter, and it says
+that this function exists for all types T. More formally, this function could be typed as:
noop :: ∀T. T -> T
+Generic types are a way to refer to types in general, meaning without specifying a single type. Our noop function
+would work with any type in the language, so we don't need to specify noop(argument: u8) -> u8, noop(argument: u16) -> u16, etc.
One question that arises when dealing with generic types is: how does the assembly handle this? There are a few approaches to handling +generic types at the lowest level. Sway uses a technique called monomorphization. This +means that the generic function is compiled to a non-generic version for every type it is called on. In this way, generic functions are +purely shorthand for the sake of ergonomics.
+An important background to know before diving into trait constraints is that the where clause can be used to specify the required traits for the generic argument. So, when writing something like a HashMap you may
+want to specify that the generic argument implements a Hash trait.
fn get_hashmap_key<T>(key: T) -> b256
+ where T: Hash
+{
+ // Code within here can then call methods associated with the Hash trait on Key
+}
+Of course, our noop() function is not useful. Often, a programmer will want to declare functions over types which satisfy certain traits.
+For example, let's try to implement the successor function, successor(), for all numeric types.
fn successor<T>(argument: T)
+ where T: Add
+{
+ argument + 1
+}
+Run forc build, and you will get:
.. |
+ 9 | where T: Add
+10 | {
+11 | argument + 1
+ | ^ Mismatched types: expected type "T" but saw type "u64"
+12 | }
+13 |
+This is because we don't know for a fact that 1, which in this case defaulted to 1u64, actually can be added to T. What if T is f64? Or b256? What does it mean to add 1u64 in these cases?
We can solve this problem with another trait constraint. We can only find the successor of some value of type T if that type T defines some incrementor. Let's make a trait:
trait Incrementable {
+ /// Returns the value to add when calculating the successor of a value.
+ fn incrementor() -> Self;
+}
+Now, we can modify our successor() function:
fn successor<T>(argument: T)
+ where T: Add,
+ T: Incrementable
+{
+ argument + T::incrementor()
+}
+Just like functions, structs and enums can be generic. Let's take a look at the standard library version of Option<T>:
enum Option<T> {
+ Some: T,
+ None: (),
+}
+Just like an unconstrained generic function, this type exists for all (∀) types T. Result<T, E> is another example:
enum Result<T, E> {
+ Ok: T,
+ Err: E,
+}
+Both generic enums and generic structs can be trait constrained, as well. Consider this struct:
+struct Foo<T>
+ where T: Add
+{
+ field_one: T,
+}
+Similar to Rust, Sway has what is colloquially known as the turbofish. The turbofish looks like this: ::<> (see the little fish with bubbles behind it?). The turbofish is used to annotate types in a generic context. Say you have the following function:
fn foo<T, E>(t: T) -> Result<T, E> {
+ Ok(t)
+}
+In this code example, which is admittedly asinine, you can't possibly know what type E is. You'd need to provide the type manually, with a turbofish:
fn foo<T, E>(t: T) -> Result<T, E> {
+ Ok::<T, MyErrorType>(t)
+}
+It is also common to see the turbofish used on the function itself:
+fn main() {
+ foo::<Bar, Baz>()
+}
+A trait opts a type into a certain type of behavior or functionality that can be shared among types. This allows for easy reuse of code and generic programming. If you have ever used a typeclass in Haskell, a trait in Rust, or even an interface in Java, these are similar concepts.
+Let's take a look at some code:
+trait Compare {
+ fn equals(self, b: Self) -> bool;
+} {
+ fn not_equals(self, b: Self) -> bool {
+ !self.equals(b)
+ }
+}
+We have just declared a trait called Compare. After the name of the trait, there are two blocks of code (a block is code enclosed in { curly brackets }). The first block is the interface surface. The second block is the methods provided by the trait. If a type can provide the methods in the interface surface, then it gets access to the methods in the trait for free! What the above trait is saying is: if you can determine if two values are equal, then for free, you can determine that they are not equal. Note that trait methods have access to the methods defined in the interface surface.
The example below implements a Compare trait for u64 to check if two numbers are equal. Let's take a look at how that is done:
impl Compare for u64 {
+ fn equals(self, b: Self) -> bool {
+ self == b
+ }
+}
+The above snippet declares all of the methods in the trait Compare for the type u64. Now, we have access to both the equals and not_equals methods for u64, as long as the trait Compare is in scope.
When using multiple traits, scenarios often come up where one trait may require functionality from another trait. This is where supertraits come in as they allow you to require a trait when implementing another trait, i.e., a trait with a trait.
+A good example of this is the Ord trait of the core library of Sway. The Ord trait requires the Eq trait, so Eq is kept as a separate trait as one may decide to implement Eq
+without implementing other parts of the Ord trait.
+trait Eq {
+ fn equals(self, b: Self) -> bool;
+}
+
+trait Ord: Eq {
+ fn gte(self, b: Self) -> bool;
+}
+
+impl Ord for u64 {
+ fn gte(self, b: Self) -> bool {
+ // As `Eq` is a supertrait of `Ord`, `Ord` can access the equals method
+ self.equals(b) || self.gt(b)
+ }
+}
+To require a supertrait, add a : after the trait name and then list the traits you would like to require and separate them with a +.
ABIs can also have supertrait annotations:
+contract;
+
+struct Foo {}
+impl ABIsupertrait for Foo {
+ fn foo() {}
+}
+
+trait ABIsupertrait {
+ fn foo();
+}
+
+abi MyAbi : ABIsupertrait {
+ fn bar();
+} {
+ fn baz() {
+ Self::foo() // supertrait method usage
+ }
+}
+
+impl ABIsupertrait for Contract {
+ fn foo() {}
+}
+
+// The implementation of MyAbi for Contract must also implement ABIsupertrait
+impl MyAbi for Contract {
+ fn bar() {
+ Self::foo() // supertrait method usage
+ }
+}
+The implementation of MyAbi for Contract must also implement the ABIsupertrait trait. Methods in ABIsupertrait are not available externally, i.e. they're not actually contract methods, but they can be used in the actual contract methods, as shown in the example above.
ABI supertraits are intended to make contract implementations compositional, allowing combining orthogonal contract features using, for instance, libraries.
+In addition to supertraits, ABIs can have superABI annotations:
+contract;
+
+abi MySuperAbi {
+ fn foo();
+}
+
+abi MyAbi : MySuperAbi {
+ fn bar();
+}
+
+impl MySuperAbi for Contract {
+ fn foo() {}
+}
+
+// The implementation of MyAbi for Contract must also implement MySuperAbi
+impl MyAbi for Contract {
+ fn bar() {}
+}
+The implementation of MyAbi for Contract must also implement the MySuperAbi superABI. Methods in MySuperAbi will be part of the MyAbi contract interface, i.e. will be available externally (and hence cannot be called from other MyAbi contract methods).
SuperABIs are intended to make contract implementations compositional, allowing combining orthogonal contract features using, for instance, libraries.
+Traits can declare different kinds of associated items in their interface surface:
+ +Associated functions in traits consist of just function signatures. This indicates that each implementation of the trait for a given type must define all the trait functions.
+trait Trait {
+ fn associated_fn(self, b: Self) -> bool;
+}
+Associated constants are constants associated with a type.
+trait Trait {
+ const ID: u32 = 0;
+}
+The initializer expression of an associated constants in a trait definition may be omitted to indicate that each implementation of the trait for a given type must specify an initializer:
trait Trait {
+ const ID: u32;
+}
+Check the associated consts section on constants page.
Associated types in Sway allow you to define placeholder types within a trait, which can be customized by concrete +implementations of that trait. These associated types are used to specify the return types of trait methods or to +define type relationships within the trait.
+trait MyTrait {
+ type AssociatedType;
+}
+Check the associated types section on associated types page.
When writing generic code, you can constraint the choice of types for a generic argument by using the where keyword. The where keyword specifies which traits the concrete generic parameter must implement. In the below example, the function expects_some_trait can be called only if the parameter t is of a type that has SomeTrait implemented. To call the expects_both_traits, parameter t must be of a type that implements both SomeTrait and SomeOtherTrait.
trait SomeTrait { }
+trait SomeOtherTrait { }
+
+fn expects_some_trait<T>(t: T) where T: SomeTrait {
+ // ...
+}
+
+fn expects_some_other_trait<T>(t: T) where T: SomeOtherTrait {
+ // ...
+}
+
+fn expects_both_traits<T>(t: T) where T: SomeTrait + SomeOtherTrait {
+ // ...
+}
+Sway types can be classified in various ways according to their intrinsic properties. These classifications are represented as marker traits. Marker traits are implemented by the compiler and cannot be explicitly implemented in code.
+E.g., all types whose instances can be used in the panic expression automatically implement the Error marker trait. We can use that trait, e.g., to specify that a generic argument must be compatible with the panic expression:
fn panic_with_error<E>(err: E) where E: Error {
+ panic err;
+}
+++Note
+panicexpression and error types have not yet been implemented
All marker traits are defined in the core::marker module.
Often, libraries and APIs have interfaces that are abstracted over a type that implements a certain trait. It is up to the consumer of the interface to implement that trait for the type they wish to use with the interface. For example, let's take a look at a trait and an interface built off of it.
+library;
+
+pub enum Suit {
+ Hearts: (),
+ Diamonds: (),
+ Clubs: (),
+ Spades: (),
+}
+
+pub trait Card {
+ fn suit(self) -> Suit;
+ fn value(self) -> u8;
+}
+
+fn play_game_with_deck<T>(a: Vec<T>) where T: Card {
+ // insert some creative card game here
+}
+Now, if you want to use the function play_game_with_deck with your struct, you must implement Card for your struct. Note that the following code example assumes a dependency games has been included in the Forc.toml file.
script;
+
+use games::*;
+
+struct MyCard {
+ suit: Suit,
+ value: u8
+}
+
+impl Card for MyCard {
+ fn suit(self) -> Suit {
+ self.suit
+ }
+ fn value(self) -> u8 {
+ self.value
+ }
+}
+
+fn main() {
+ let mut i = 52;
+ let mut deck: Vec<MyCard> = Vec::with_capacity(50);
+ while i > 0 {
+ i = i - 1;
+ deck.push(MyCard { suit: generate_random_suit(), value: i % 4}
+ }
+ play_game_with_deck(deck);
+}
+
+fn generate_random_suit() -> Suit {
+ [ ... ]
+}
+Associated types in Sway allow you to define placeholder types within a trait, which can be customized by concrete +implementations of that trait. These associated types are used to specify the return types of trait methods or to +define type relationships within the trait.
+Associated types are a powerful feature of Sway's trait system, enabling generic programming and abstraction over +types. They help improve code clarity and maintainability by allowing you to define generic traits without committing +to specific types.
+Associated types are declared within a trait using the type keyword. Here's the syntax for declaring an associated type:
+trait MyTrait {
+ type AssociatedType;
+}
+Concrete implementations of a trait with associated types must provide a specific type for each associated type +defined in the trait. Here's an example of implementing a trait with an associated type:
+struct MyStruct;
+
+impl MyTrait for MyStruct {
+ type AssociatedType = u32; // Implementing the associated type with u32
+}
+In this example, MyStruct implements MyTrait and specifies that the associated type AssociatedType is u32.
Associated types are used within trait methods or where the trait is used as a bound for generic functions or +structs. You can use the associated type like any other type. Here's an example:
+trait MyTrait {
+ type AssociatedType;
+
+ fn get_value(self) -> Self::AssociatedType;
+}
+
+struct MyStruct;
+
+impl MyTrait for MyStruct {
+ type AssociatedType = u32;
+
+ fn get_value(self) -> Self::AssociatedType {
+ 42
+ }
+}
+In this example, get_value is a trait method that returns an associated type AssociatedType.
Associated types are particularly useful in scenarios where you want to define traits that work with different +types of data structures or abstractions, allowing the implementer to specify the concrete types. Some common use cases include:
+At a high level, Sway allows you to define constraints, or restrictions, that +allow you to strike a balance between writing abstract and reusable code and +enforcing compile-time checks to determine if the abstract code that you've +written is correct.
+The "abstract and reusable" part largely comes from generic types and the +"enforcing compile-time checks" part largely comes from trait constraints. +Generic types can be used with functions, structs, and enums (as we have seen in +this book), but they can also be used with traits.
+Combining generic types with traits allows you to write abstract and reusable +traits that can be implemented for any number of data types.
+For example, imagine that you want to write a trait for converting between
+different types. This would be similar to Rust's Into and From traits. In
+Sway your conversion trait would look something like:
trait Convert<T> {
+ fn from(t: T) -> Self;
+}
+The trait Convert takes a generic type T. Convert has one method
+from, which takes one parameter of type T and returns a Self. This means
+that when you implement Convert for a data type, from will return the type
+of that data type but will take as input the type that you define as T. Here
+is an example:
struct Square {
+ width: u64,
+}
+
+struct Rectangle {
+ width: u64,
+ length: u64,
+}
+
+impl Convert<Square> for Rectangle {
+ fn from(t: Square) -> Self {
+ Self {
+ width: t.width,
+ length: t.width,
+ }
+ }
+}
+In this example, you have two different data types, Square and Rectangle.
+You know that all squares are rectangles and thus Square can convert into Rectangle (but not vice
+versa) and thus you can implement the conversion trait for those types.
If we want to call these methods we can do so by:
+fn main() {
+ let s = Square { width: 5 };
+ let r = Rectangle::from(s);
+}
+Trait constraints allow you to use generic types and traits to place constraints +on what abstract code you are willing to accept in your program as correct. +These constraints take the form of compile-time checks for correctness.
+If we wanted to use trait constraints with our Convert trait from the previous
+section we could do so like so:
fn into_rectangle<T>(t: T) -> Rectangle
+where
+ Rectangle: Convert<T>,
+{
+ Rectangle::from(t)
+}
+This function allows you to take any generic data type T and convert it to the
+type Rectangle as long as Convert<T> is implemented for Rectangle.
+Calling this function with a type T for which Convert<T> is not implemented
+for Rectangle will fail Sway's compile-time checks.
While many users will never have to touch assembly language while writing Sway code, it is a powerful tool that enables many advanced use-cases (e.g., optimizations, building libraries, etc).
+In Sway, the way we use assembly inline is to declare an asm block like this:
asm() {...}
+Declaring an asm block is similar to declaring a function.
+We can specify register names to operate on as arguments, we can perform assembly instructions within the block, and we can return a value by specifying a return register.
+Here's an example showing what this might look like:
pub fn add_1(num: u32) -> u32 {
+ asm(r1: num, r2) {
+ add r2 r1 one;
+ r2: u32
+ }
+}
+The return register is specified at the end of the asm block, after all the assembly instructions. It consists of the register name and an optional return type. In the above example, the return register name is r2 and the return type is u32.
+If the return type is omitted, it is u64 by default.
The return register itself is optional. If it is not specified, similar to functions, the returned value from the asm block will be unit, ().
An asm block can only return a single register. If you really need to return more than one value, you can modify a tuple. Here's an example showing how you can implement this for (u64, u64):
script;
+
+fn adder(a: u64, b: u64, c: u64) -> (u64, u64) {
+ let empty_tuple = (0u64, 0u64);
+ asm(output: empty_tuple, r1: a, r2: b, r3: c, r4, r5) {
+ add r4 r1 r2; // add a & b and put the result in r4
+ add r5 r2 r3; // add b & c and put the result in r5
+ sw output r4 i0; // store the word in r4 in output + 0 words
+ sw output r5 i1; // store the word in r5 in output + 1 word
+ output: (u64, u64) // return both values
+ }
+}
+
+fn main() -> bool {
+ let (first, second) = adder(1, 2, 3);
+ assert(first == 3);
+ assert(second == 5);
+ true
+}
+Note that this is contrived example meant to demonstrate the syntax; there's absolutely no need to use assembly to add integers!
+Note that in the above example:
+r1 with the value of num.r2 (you may choose any register names you want).add opcode to add one to the value of r1 and store it in r2.one is an example of a "reserved register", of which there are 16 in total. Further reading on this is linked below under "Semantics".r2 and specify the return type as being u32.An important note is that the ji and jnei opcodes are not available within an asm block. For those looking to introduce control flow to asm blocks, it is recommended to surround smaller chunks of asm with control flow (if, else, and while).
For examples of assembly in action, check out the Sway standard library.
+For a complete list of all instructions supported in the FuelVM: Instructions.
+And to learn more about the FuelVM semantics: Semantics.
+The Never type ! represents the type of computations which never resolve to any value at all.
break, continue and return expressions also have type !. For example we are allowed to
+write:
let x: ! = {
+ return 123
+};
+Although the let is pointless here, it illustrates the meaning of !. Since x is never
+assigned a value (because return returns from the entire function), x can be given type
+Never. We could also replace return 123 with a revert() or a never-ending loop and this code
+would still be valid.
A more realistic usage of Never is in this code:
let num: u32 = match get_a_number() {
+ Some(num) => num,
+ None => break,
+};
+Both match arms must produce values of type [u32], but since break never produces a value
+at all we know it can never produce a value which isn't a [u32]. This illustrates another
+behaviour of the ! type - expressions with type ! will coerce into any other type.
Note that ! type coerces into any other type, another example of this would be:
let x: u32 = {
+ return 123
+};
+Regardless of the type of x, the return block of type Never will always coerce into x type.
fn foo() {
+ let num: u64 = match Option::None::<u64> {
+ Some(num) => num,
+ None => return,
+ };
+}
+Sway’s standard library includes a number of very useful data structures called collections. Most other data types represent one specific value, but collections can contain multiple values. Unlike the built-in array and tuple types which are allocated on the "stack" and cannot grow in size, the data these collections point to is stored either on the "heap" or in contract "storage", which means the amount of data does not need to be known at compile time and can grow as the program runs. Each kind of collection has different capabilities and costs, and choosing an appropriate one for your current situation is a skill you’ll develop over time. In this chapter, we’ll discuss three collections that are used very often in Sway programs:
+A vector on the heap allows you to store a variable number of values next to each other.
+A StorageVec is similar to a vector on the heap but uses persistent storage.
A StorageMap allows you to associate a value with a particular key.
We’ll discuss how to create and update a vector, StorageVec, and StorageMap, as well as what makes each special.
The first collection type we’ll look at is Vec<T>, also known as a vector. Vectors allow you to store more than one value in a single data structure that puts all the values next to each other in memory. Vectors can only store values of the same type. They are useful when you have a list of items, such as the lines of text in a file or the prices of items in a shopping cart.
Vec<T> is included in the standard library prelude which means that there is no need to import it manually.
To create a new empty vector, we call the Vec::new function, as shown below:
let v: Vec<u64> = Vec::new();
+Note that we added a type annotation here. Because we aren’t inserting any values into this vector, the Sway compiler doesn’t know what kind of elements we intend to store. Vectors are implemented using generics which means that the Vec<T> type provided by the standard library can hold any type. When we create a vector to hold a specific type, we can specify the type within angle brackets. In the example above, we’ve told the Sway compiler that the Vec<T> in v will hold elements of the u64 type.
To create a vector and then add elements to it, we can use the push method, as shown below:
let mut v = Vec::new();
+
+ v.push(5);
+ v.push(6);
+ v.push(7);
+ v.push(8);
+As with any variable, if we want to be able to change its value, we need to make it mutable using the mut keyword, as discussed in the section Declaring a Variable. The numbers we place inside are all of type u64, and the Sway compiler infers this from the data, so we don’t need the Vec<u64> annotation.
To read a value stored in a vector at a particular index, you can use the get method as shown below:
let third = v.get(2);
+ match third {
+ Some(third) => log(third),
+ None => revert(42),
+ }
+Note two details here. First, we use the index value of 2 to get the third element because vectors are indexed by number, starting at zero. Second, we get the third element by using the get method with the index passed as an argument, which gives us an Option<T>.
When the get method is passed an index that is outside the vector, it returns None without panicking. This is particularly useful if accessing an element beyond the range of the vector may happen occasionally under normal circumstances. Your code will then have logic to handle having either Some(element) or None. For example, the index could be coming as a contract method argument. If the argument passed is too large, the method get will return a None value, and the contract method may then decide to revert when that happens or return a meaningful error that tells the user how many items are in the current vector and give them another chance to pass a valid value.
To access elements of a vector, we can iterate through the valid indices using a while loop and the len method as shown below:
let mut i = 0;
+ while i < v.len() {
+ log(v.get(i).unwrap());
+ i += 1;
+ }
+Note two details here. First, we use the method len which returns the length of the vector. Second, we call the method unwrap to extract the Option returned by get. We know that unwrap will not fail (i.e. will not cause a revert) because each index i passed to get is known to be smaller than the length of the vector.
The idiomatic and convenient way to access each element in a vector in turn, is to use the for loop in the combination with the iter method. The iter method returns an iterator that iterates over all the elements of the vector sequentially.
for elem in v.iter() {
+ log(elem);
+ }
+Note that modifying a vector during iteration, by e.g. adding or removing elements, is a logical error and results in an undefined behavior:
+ for elem in v.iter() {
+ log(elem);
+ if elem == 3 {
+ v.push(6); // Modification causes undefined behavior!
+ }
+ }
+Accessing vector elements via while loop should be used only when more control over traversal is needed. E.g., in the below example we iterate the vector backwards, accessing only every second element.
// Start from the end
+ let mut i = v.len() - 1;
+ while 0 <= i {
+ log(v.get(i).unwrap());
+ // Access every second element
+ i -= 2;
+ }
+Vectors can only store values that are the same type. This can be inconvenient; there are definitely use cases for needing to store a list of items of different types. Fortunately, the variants of an enum are defined under the same enum type, so when we need one type to represent elements of different types, we can define and use an enum!
+For example, say we want to get values from a row in a table in which some of the columns in the row contain integers, some b256 values, and some Booleans. We can define an enum whose variants will hold the different value types, and all the enum variants will be considered the same type: that of the enum. Then we can create a vector to hold that enum and so, ultimately, holds different types. We’ve demonstrated this below:
enum TableCell {
+ Int: u64,
+ B256: b256,
+ Boolean: bool,
+ }
+
+ let mut row = Vec::new();
+ row.push(TableCell::Int(3));
+ row.push(TableCell::B256(0x0101010101010101010101010101010101010101010101010101010101010101));
+ row.push(TableCell::Boolean(true));
+Now that we’ve discussed some of the most common ways to use vectors, be sure to review the API documentation for all the many useful methods defined on Vec<T> by the standard library. For now, these can be found in the source code for Vec<T>. For example, in addition to push, a pop method removes and returns the last element, a remove method removes and returns the element at some chosen index within the vector, an insert method inserts an element at some chosen index within the vector, etc.
The second collection type we’ll look at is StorageVec<T>. Just like vectors on the heap (i.e. Vec<T>), storage vectors allow you to store more than one value in a single data structure where each value is assigned an index and can only store values of the same type. However, unlike Vec<T>, the elements of a StorageVec are stored in persistent storage, and consecutive elements are not necessarily stored in storage slots that have consecutive keys.
In order to use StorageVec<T>, you must first import StorageVec as follows:
use std::storage::storage_vec::*;
+Another major difference between Vec<T> and StorageVec<T> is that StorageVec<T> can only be used in a contract because only contracts are allowed to access persistent storage.
StorageVecTo create a new empty StorageVec, we have to declare the vector in a storage block as follows:
v: StorageVec<u64> = StorageVec {},
+Just like any other storage variable, two things are required when declaring a StorageVec: a type annotation and an initializer. The initializer is just an empty struct of type StorageVec because StorageVec<T> itself is an empty struct! Everything that is interesting about StorageVec<T> is implemented in its methods.
Storage vectors, just like Vec<T>, are implemented using generics which means that the StorageVec<T> type provided by the standard library can hold any type. When we create a StorageVec to hold a specific type, we can specify the type within angle brackets. In the example above, we’ve told the Sway compiler that the StorageVec<T> in v will hold elements of the u64 type.
StorageVecTo add elements to a StorageVec, we can use the push method, as shown below:
#[storage(read, write)]
+ fn push_to_storage_vec() {
+ storage.v.push(5);
+ storage.v.push(6);
+ storage.v.push(7);
+ storage.v.push(8);
+ }
+Note two details here. First, in order to use push, we need to first access the vector using the storage keyword. Second, because push requires accessing storage, a storage annotation is required on the ABI function that calls push. While it may seem that #[storage(write)] should be enough here, the read annotation is also required because each call to push requires reading (and then updating) the length of the StorageVec which is also stored in persistent storage.
++ +Note +The storage annotation is also required for any private function defined in the contract that tries to push into the vector.
+
++Note +There is no need to add the
+mutkeyword when declaring aStorageVec<T>. All storage variables are mutable by default.
To read a value stored in a vector at a particular index, you can use the get method as shown below:
#[storage(read)]
+ fn read_from_storage_vec() {
+ let third = storage.v.get(2);
+ match third {
+ Some(third) => log(third.read()),
+ None => revert(42),
+ }
+ }
+Note three details here. First, we use the index value of 2 to get the third element because vectors are indexed by number, starting at zero. Second, we get the third element by using the get method with the index passed as an argument, which gives us an Option<StorageKey<T>>. Third, the ABI function calling get only requires the annotation #[storage(read)] as one might expect because get does not write to storage.
When the get method is passed an index that is outside the vector, it returns None without panicking. This is particularly useful if accessing an element beyond the range of the vector may happen occasionally under normal circumstances. Your code will then have logic to handle having either Some(element) or None. For example, the index could be coming as a contract method argument. If the argument passed is too large, the method get will return a None value, and the contract method may then decide to revert when that happens or return a meaningful error that tells the user how many items are in the current vector and give them another chance to pass a valid value.
Iterating over a storage vector is conceptually the same as iterating over a Vec<T>. The only difference is an additional call to read() to actually read the stored value.
#[storage(read)]
+ fn iterate_over_a_storage_vec() {
+ // Iterate over all the elements
+ // in turn using the `while` loop.
+ // **This approach is not recommended.**
+ // For iterating over all the elements
+ // in turn use the `for` loop instead.
+ let mut i = 0;
+ while i < storage.v.len() {
+ log(storage.v.get(i).unwrap().read());
+ i += 1;
+ }
+
+ // The preferred and most performant way
+ // to iterate over all the elements in turn is
+ // to use the `for` loop.
+ for elem in storage.v.iter() {
+ log(elem.read());
+ }
+
+ // Use the `while` loop only when more
+ // control over traversal is needed.
+ // E.g., in the below example we iterate
+ // the vector backwards, accessing only
+ // every second element.
+ let mut i = storage.v.len() - 1;
+ while 0 <= i {
+ log(storage.v.get(i).unwrap().read());
+ i -= 2;
+ }
+ }
+Note that modifying a vector during iteration, by e.g. adding or removing elements, is a logical error and results in an undefined behavior:
+Storage vectors, just like Vec<T>, can only store values that are the same type. Similarly to what we did for Vec<T> in the section Using an Enum to store Multiple Types, we can define an enum whose variants will hold the different value types, and all the enum variants will be considered the same type: that of the enum. This is shown below:
enum TableCell {
+ Int: u64,
+ B256: b256,
+ Boolean: bool,
+}
+Then we can declare a StorageVec in a storage block to hold that enum and so, ultimately, holds different types:
row: StorageVec<TableCell> = StorageVec {},
+We can now push different enum variants to the StorageVec as follows:
#[storage(read, write)]
+ fn push_to_multiple_types_storage_vec() {
+ storage.row.push(TableCell::Int(3));
+ storage
+ .row
+ .push(TableCell::B256(0x0101010101010101010101010101010101010101010101010101010101010101));
+ storage.row.push(TableCell::Boolean(true));
+ }
+Now that we’ve discussed some of the most common ways to use storage vectors, be sure to review the API documentation for all the many useful methods defined on StorageVec<T> by the standard library. For now, these can be found in the source code for StorageVec<T>. For example, in addition to push, a pop method removes and returns the last element, a remove method removes and returns the element at some chosen index within the vector, an insert method inserts an element at some chosen index within the vector, etc.
It is possible to nest storage vectors as follows:
+ nested_vec: StorageVec<StorageVec<u64>> = StorageVec {},
+The nested vector can then be accessed as follows:
+ #[storage(read, write)]
+ fn access_nested_vec() {
+ storage.nested_vec.push(StorageVec {});
+ storage.nested_vec.push(StorageVec {});
+
+ let mut inner_vec0 = storage.nested_vec.get(0).unwrap();
+ let mut inner_vec1 = storage.nested_vec.get(1).unwrap();
+
+ inner_vec0.push(0);
+ inner_vec0.push(1);
+
+ inner_vec1.push(2);
+ inner_vec1.push(3);
+ inner_vec1.push(4);
+
+ assert(inner_vec0.len() == 2);
+ assert(inner_vec0.get(0).unwrap().read() == 0);
+ assert(inner_vec0.get(1).unwrap().read() == 1);
+ assert(inner_vec0.get(2).is_none());
+
+ assert(inner_vec1.len() == 3);
+ assert(inner_vec1.get(0).unwrap().read() == 2);
+ assert(inner_vec1.get(1).unwrap().read() == 3);
+ assert(inner_vec1.get(2).unwrap().read() == 4);
+ assert(inner_vec1.get(3).is_none());
+ }
+Another important common collection is the storage map.
+ + +The type StorageMap<K, V> from the standard library stores a mapping of keys of type K to values of type V using a hashing function, which determines how it places these keys and values into storage slots. This is similar to Rust's HashMap<K, V> but with a few differences.
Storage maps are useful when you want to look up data not by using an index, as you can with vectors, but by using a key that can be of any type. For example, when building a ledger-based sub-currency smart contract, you could keep track of the balance of each wallet in a storage map in which each key is a wallet’s Address and the values are each wallet’s balance. Given an Address, you can retrieve its balance.
Similarly to StorageVec<T>, StorageMap<K, V> can only be used in a contract because only contracts are allowed to access persistent storage.
StorageMap<T> is included in the standard library prelude which means that there is no need to import it manually.
To create a new empty storage map, we have to declare the map in a storage block as follows:
map: StorageMap<Address, u64> = StorageMap::<Address, u64> {},
+Just like any other storage variable, two things are required when declaring a StorageMap: a type annotation and an initializer. The initializer is just an empty struct of type StorageMap because StorageMap<K, V> itself is an empty struct! Everything that is interesting about StorageMap<K, V> is implemented in its methods.
Storage maps, just like Vec<T> and StorageVec<T>, are implemented using generics which means that the StorageMap<K, V> type provided by the standard library can map keys of any type K to values of any type V. In the example above, we’ve told the Sway compiler that the StorageMap<K, V> in map will map keys of type Address to values of type u64.
To insert key-value pairs into a storage map, we can use the insert method.
For example:
+ #[storage(write)]
+ fn insert_into_storage_map() {
+ let addr1 = Address::from(0x0101010101010101010101010101010101010101010101010101010101010101);
+ let addr2 = Address::from(0x0202020202020202020202020202020202020202020202020202020202020202);
+
+ storage.map.insert(addr1, 42);
+ storage.map.insert(addr2, 77);
+ }
+Note two details here. First, in order to use insert, we need to first access the storage map using the storage keyword. Second, because insert requires writing into storage, a #[storage(write)] annotation is required on the ABI function that calls insert.
++ +Note +The storage annotation is also required for any private function defined in the contract that tries to insert into the map.
+
++Note +There is no need to add the
+mutkeyword when declaring aStorageMap<K, V>. All storage variables are mutable by default.
We can get a value out of the storage map by providing its key to the get method.
For example:
+ #[storage(read, write)]
+ fn get_from_storage_map() {
+ let addr1 = Address::from(0x0101010101010101010101010101010101010101010101010101010101010101);
+ let addr2 = Address::from(0x0202020202020202020202020202020202020202020202020202020202020202);
+
+ storage.map.insert(addr1, 42);
+ storage.map.insert(addr2, 77);
+
+ let value1 = storage.map.get(addr1).try_read().unwrap_or(0);
+ }
+Here, value1 will have the value that's associated with the first address, and the result will be 42. The get method returns an Option<V>; if there’s no value for that key in the storage map, get will return None. This program handles the Option by calling unwrap_or to set value1 to zero if map doesn't have an entry for the key.
Maps with multiple keys can be implemented using tuples as keys. For example:
+ map_two_keys: StorageMap<(b256, bool), b256> = StorageMap::<(b256, bool), b256> {},
+It is possible to nest storage maps as follows:
+ nested_map: StorageMap<u64, StorageMap<u64, u64>> = StorageMap::<u64, StorageMap<u64, u64>> {},
+The nested map can then be accessed as follows:
+ #[storage(read, write)]
+ fn access_nested_map() {
+ storage.nested_map.get(0).insert(1, 42);
+ storage.nested_map.get(2).insert(3, 24);
+
+ assert(storage.nested_map.get(0).get(1).read() == 42);
+ assert(storage.nested_map.get(0).get(0).try_read().is_none()); // Nothing inserted here
+ assert(storage.nested_map.get(2).get(3).read() == 24);
+ assert(storage.nested_map.get(2).get(2).try_read().is_none()); // Nothing inserted here
+ }
+Sway aims to provide facilities for both unit testing and integration testing.
+Unit testing refers to "in-language" test functions annotated with #[test].
Integration testing refers to the testing of your Sway project's integration +within some wider application. You can add integration testing to your Sway+Rust +projects today using the cargo generate template and Rust SDK.
+ +Forc provides built-in support for building and executing tests for a package.
+Tests are written as free functions with the #[test] attribute.
For example:
+#[test]
+fn test_meaning_of_life() {
+ assert(6 * 7 == 42);
+}
+Each test function is ran as if it were the entry point for a +script. Tests "pass" if they return +successfully, and "fail" if they revert or vice versa while testing failure.
+If the project has failing tests forc test will exit with exit status 101.
We can build and execute all tests within a package with the following:
+forc test
+The output should look similar to this:
+ Compiled library "core".
+ Compiled library "std".
+ Compiled library "lib_single_test".
+ Bytecode size is 92 bytes.
+ Running 1 tests
+ test test_meaning_of_life ... ok (170.652µs)
+ Result: OK. 1 passed. 0 failed. Finished in 1.564996ms.
+Visit the forc test command reference to find
+the options available for forc test.
Forc supports testing failing cases for test functions declared with #[test(should_revert)].
For example:
+#[test(should_revert)]
+fn test_meaning_of_life() {
+ assert(6 * 6 == 42);
+}
+It is also possible to specify an expected revert code, like the following example.
+#[test(should_revert = "18446744073709486084")]
+fn test_meaning_of_life() {
+ assert(6 * 6 == 42);
+}
+Tests with #[test(should_revert)] are considered to be passing if they are reverting.
Unit tests can call contract functions an example for such calls can be seen below.
+contract;
+
+abi MyContract {
+ fn test_function() -> bool;
+}
+
+impl MyContract for Contract {
+ fn test_function() -> bool {
+ true
+ }
+}
+To test the test_function(), a unit test like the following can be written.
#[test]
+fn test_success() {
+ let caller = abi(MyContract, CONTRACT_ID);
+ let result = caller.test_function {}();
+ assert(result == true)
+}
+It is also possible to test failure with contract calls as well.
+#[test(should_revert)]
+fn test_fail() {
+ let caller = abi(MyContract, CONTRACT_ID);
+ let result = caller.test_function {}();
+ assert(result == false)
+}
+++ +Note: When running
+forc test, your contract will be built twice: first without unit tests in order to determine the contract's ID, then a second time with unit tests with theCONTRACT_IDprovided to their namespace. ThisCONTRACT_IDcan be used with theabicast to enable contract calls within unit tests.
Unit tests can call methods of external contracts if those contracts are added as contract dependencies, i.e. in the contract-dependencies section of the manifest file. An example of such calls is shown below:
contract;
+
+abi CallerContract {
+ fn test_false() -> bool;
+}
+
+impl CallerContract for Contract {
+ fn test_false() -> bool {
+ false
+ }
+}
+
+abi CalleeContract {
+ fn test_true() -> bool;
+}
+
+#[test]
+fn test_multi_contract_calls() {
+ let caller = abi(CallerContract, CONTRACT_ID);
+ let callee = abi(CalleeContract, callee::CONTRACT_ID);
+
+ let should_be_false = caller.test_false();
+ let should_be_true = callee.test_true();
+ assert(!should_be_false);
+ assert(should_be_true);
+}
+Example Forc.toml for contract above:
[project]
+authors = ["Fuel Labs <contact@fuel.sh>"]
+entry = "main.sw"
+license = "Apache-2.0"
+name = "caller"
+
+[dependencies]
+core = { path = "../../../sway-lib-core" }
+std = { path = "../../../sway-lib-std/" }
+
+[contract-dependencies]
+callee = { path = "../callee" }
+By default, all unit tests in your project are run in parallel. Note that this does not lead to any data races in storage because each unit test has its own storage space that is not shared by any other unit test.
+ +By default, forc test will use all the available threads in your system. To request that a specific number of threads be used, the flag --test-threads <val> can be provided to forc test.
forc test --test-threads 1
+Forc has some capacity to help decode logs returned from the unit tests. You can use this feature to decode raw logs into a human readable format.
+script;
+
+fn main() {}
+
+#[test]
+fn test_fn() {
+let a = 10;
+ log(a);
+ let b = 30;
+ log(b);
+ assert_eq(a, 10)
+ assert_eq(b, 30)
+}
+The example shown above is logging two different variables, a and b and their values are 10 and 30, respectively. Without log decoding printed log for this test with forc test --logs (--logs flag is required to see the logs for this example since the test is passing. Logs are silenced by default in passing tests, and can be enabled using the --logs flag.):
Finished debug [unoptimized + fuel] target(s) in 5.23s
+ Bytecode hash: 0x1cb1edc031691c5c08b50fd0f07b02431848ab81b325b72eb3fd233c67d6b548
+ Running 1 test, filtered 0 tests
+ test test_fn ... ok (38.875µs, 232 gas)
+[{"LogData":{"data":"000000000000000a","digest":"8d85f8467240628a94819b26bee26e3a9b2804334c63482deacec8d64ab4e1e7","id":"0000000000000000000000000000000000000000000000000000000000000000","is":10368,"len":8,"pc":11032,"ptr":67107840,"ra":0,"rb":0}},{"LogData":{"data":"000000000000001e","digest":"48a97e421546f8d4cae1cf88c51a459a8c10a88442eed63643dd263cef880c1c","id":"0000000000000000000000000000000000000000000000000000000000000000","is":10368,"len":8,"pc":11516,"ptr":67106816,"ra":0,"rb":1}}]
+This is not very easy to understand, it is possible to decode these logs with --decode flag, executing forc test --logs --decode:
Finished debug [unoptimized + fuel] target(s) in 5.23s
+ Bytecode hash: 0x1cb1edc031691c5c08b50fd0f07b02431848ab81b325b72eb3fd233c67d6b548
+ Running 1 test, filtered 0 tests
+ test test_fn ... ok (38.875µs, 232 gas)
+Decoded log value: 10, log rb: 0
+Decoded log value: 30, log rb: 1
+As it can be seen, the values are human readable and easier to understand which makes debugging much more easier.
+Note: This is an experimental feature and we are actively working on reporting variable names next to their values.
+ +A common use of Sway is for writing contracts or scripts that exist as part of a +wider Rust application. In order to test the interaction between our Sway code +and our Rust code we can add integration testing.
+To add Rust integration testing to a Forc project we can use the sway-test-rs
+cargo generate
+template.
+This template makes it easier for Sway developers to add the boilerplate required when
+setting up their Rust integration testing.
Let's add a Rust integration test to the fresh project we created in the introduction.
+To recap, here's what our empty project looks like:
+$ cd my-fuel-project
+$ tree .
+├── Forc.toml
+└── src
+ └── main.sw
+cargo generateWe're going to add a Rust integration test harness using a cargo generate
+template. Let's make sure we have the cargo generate command installed!
cargo install cargo-generate
+++Note: You can learn more about cargo generate by visiting the +cargo-generate repository.
+
Let's generate the default test harness with the following:
+cargo generate --init fuellabs/sway templates/sway-test-rs --name my-fuel-project --force
+--force forces your --name input to retain your desired casing for the {{project-name}}
+placeholder in the template. Otherwise, cargo-generate automatically converts it to kebab-case.
+With --force, this means that both my_fuel_project and my-fuel-project are valid project names,
+depending on your needs.
++_Note:
+templates/sway-test-rscan be replaced withtemplates/sway-script-test-rsortemplates/sway-predicate-test-rsto generate a test +harness for scripts and predicates respectively.
If all goes well, the output should look as follows:
+⚠️ Favorite `fuellabs/sway` not found in config, using it as a git repository: https://github.com/fuellabs/sway
+🤷 Project Name : my-fuel-project
+🔧 Destination: /home/user/path/to/my-fuel-project ...
+🔧 Generating template ...
+[1/3] Done: Cargo.toml
+[2/3] Done: tests/harness.rs
+[3/3] Done: tests
+🔧 Moving generated files into: `/home/user/path/to/my-fuel-project`...
+✨ Done! New project created /home/user/path/to/my-fuel-project
+Let's have a look at the result:
+$ tree .
+├── Cargo.toml
+├── Forc.toml
+├── build.rs
+├── src
+│ └── main.sw
+└── tests
+ └── harness.rs
+We have three new files!
+Cargo.toml is the manifest for our new test harness and specifies the
+required dependencies including fuels the Fuel Rust SDK.tests/harness.rs contains some boilerplate test code to get us started,
+though doesn't call any contract methods just yet.build.rs is a build script that compiles the Sway project with forc build
+whenever cargo test is run.Before running the tests, we need to build our contract so that the necessary
+ABI, storage and bytecode artifacts are available. We can do so with forc build:
$ forc build
+ Creating a new `Forc.lock` file. (Cause: lock file did not exist)
+ Adding core
+ Adding std git+https://github.com/fuellabs/sway?tag=v0.24.5#e695606d8884a18664f6231681333a784e623bc9
+ Created new lock file at /home/user/path/to/my-fuel-project/Forc.lock
+ Compiled library "core".
+ Compiled library "std".
+ Compiled contract "my-fuel-project".
+ Bytecode size is 60 bytes.
+At this point, our project should look like the following:
+$ tree
+├── Cargo.toml
+├── Forc.lock
+├── Forc.toml
+├── build.rs
+├── out
+│ └── debug
+│ ├── my-fuel-project-abi.json
+│ ├── my-fuel-project.bin
+│ └── my-fuel-project-storage_slots.json
+├── src
+│ └── main.sw
+└── tests
+ └── harness.rs
+We now have an out directory with our required JSON files!
++Note: This step may no longer be required in the future as we plan to +enable the integration testing to automatically build the artifacts as +necessary so that files like the ABI JSON are always up to date.
+
Now we're ready to build and run the default integration test.
+$ cargo test
+ Updating crates.io index
+ Compiling version_check v0.9.4
+ Compiling proc-macro2 v1.0.46
+ Compiling quote v1.0.21
+ ...
+ Compiling fuels v0.24.0
+ Compiling my-fuel-project v0.1.0 (/home/user/path/to/my-fuel-project)
+ Finished test [unoptimized + debuginfo] target(s) in 1m 03s
+ Running tests/harness.rs (target/debug/deps/integration_tests-373971ac377845f7)
+
+running 1 test
+test can_get_contract_id ... ok
+
+test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.36s
+++Note: The first time we run
+cargo test, cargo will spend some time +fetching and building the dependencies for Fuel's Rust SDK. This might take a +while, but only the first time!
If all went well, we should see some output that looks like the above!
+Now that we've learned how to setup Rust integration testing in our project, +let's try to write some of our own tests!
+First, let's update our contract code with a simple counter example:
+contract;
+
+abi TestContract {
+ #[storage(write)]
+ fn initialize_counter(value: u64) -> u64;
+
+ #[storage(read, write)]
+ fn increment_counter(amount: u64) -> u64;
+}
+
+storage {
+ counter: u64 = 0,
+}
+
+impl TestContract for Contract {
+ #[storage(write)]
+ fn initialize_counter(value: u64) -> u64 {
+ storage.counter.write(value);
+ value
+ }
+
+ #[storage(read, write)]
+ fn increment_counter(amount: u64) -> u64 {
+ let incremented = storage.counter.read() + amount;
+ storage.counter.write(incremented);
+ incremented
+ }
+}
+To test our initialize_counter and increment_counter contract methods from
+the Rust test harness, we could update our tests/harness.rs file with the
+following:
use fuels::{prelude::*, types::ContractId};
+
+// Load abi from json
+abigen!(Contract(
+ name = "MyContract",
+ abi = "out/debug/my-fuel-project-abi.json"
+));
+
+async fn get_contract_instance() -> (MyContract<WalletUnlocked>, ContractId) {
+ // Launch a local network and deploy the contract
+ let mut wallets = launch_custom_provider_and_get_wallets(
+ WalletsConfig::new(
+ Some(1), /* Single wallet */
+ Some(1), /* Single coin (UTXO) */
+ Some(1_000_000_000), /* Amount per coin */
+ ),
+ None,
+ None,
+ )
+ .await
+ .unwrap();
+ let wallet = wallets.pop().unwrap();
+
+ let id = Contract::load_from(
+ "./out/debug/my-fuel-project.bin",
+ LoadConfiguration::default().set_storage_configuration(
+ StorageConfiguration::load_from(
+ "./out/debug/my-fuel-project-storage_slots.json",
+ )
+ .unwrap(),
+ ),
+ )
+ .unwrap()
+ .deploy(&wallet, TxPolicies::default())
+ .await
+ .unwrap();
+
+ let instance = MyContract::new(id.clone(), wallet);
+
+ (instance, id.into())
+}
+
+#[tokio::test]
+async fn initialize_and_increment() {
+ let (contract_instance, _id) = get_contract_instance().await;
+ // Now you have an instance of your contract you can use to test each function
+
+ let result = contract_instance
+ .methods()
+ .initialize_counter(42)
+ .call()
+ .await
+ .unwrap();
+
+ assert_eq!(42, result.value);
+
+ // Call `increment_counter()` method in our deployed contract.
+ let result = contract_instance
+ .methods()
+ .increment_counter(10)
+ .call()
+ .await
+ .unwrap();
+
+ assert_eq!(52, result.value);
+}Let's build our project once more and run the test:
+forc build
+$ cargo test
+ Compiling my-fuel-project v0.1.0 (/home/mindtree/programming/sway/my-fuel-project)
+ Finished test [unoptimized + debuginfo] target(s) in 11.61s
+ Running tests/harness.rs (target/debug/deps/integration_tests-373971ac377845f7)
+
+running 1 test
+test initialize_and_increment ... ok
+
+test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 1.25s
+When cargo runs our test, our test uses the SDK to spin up a local in-memory +Fuel network, deploy our contract to it, and call the contract methods via the +ABI.
+You can add as many functions decorated with #[tokio::test] as you like, and
+cargo test will automatically test each of them!
Forc provides tools for debugging both live transactions as well as Sway unit tests. +Debugging can be done via CLI or using the VSCode IDE.
+Unit testing refers to "in-language" test functions annotated with #[test]. Line-by-line
+debugging is available within the VSCode IDE.
Live transaction refers to the testing sending a transaction to a running Fuel Client
+node to exercise your Sway code. Instruction-by-instruction debugging is available in the forc debug CLI.
The forc debug CLI enables debugging a live transaction on a running Fuel Client node.
First, we need a project to debug, so create a new project using
+forc new --script dbg_example && cd dbg_example
+And then add some content to src/main.sw, for example:
script;
+
+use std::logging::log;
+
+fn factorial(n: u64) -> u64 {
+ let mut result = 1;
+ let mut counter = 0;
+ while counter < n {
+ counter = counter + 1;
+ result = result * counter;
+ }
+ return result;
+}
+
+fn main() {
+ log::<u64>(factorial(5)); // 120
+}
+Now we are ready to build the project.
+forc build
+After this the resulting binary should be located at out/debug/dbg_example.bin. Because we are interested in the resulting bytecode, we can read that with:
forc parse-bytecode out/debug/dbg_example.bin
+We can recognize the main loop by observing the control flow. Looking around halfword 58-60, we can see:
+ half-word byte op raw
+ 58 232 MOVI { dst: 0x11, val: 5 } 72 44 00 05
+ 59 236 LT { dst: 0x10, lhs: 0x10, rhs: 0x11 } 16 41 04 40
+ 60 240 JNZF { cond_nz: 0x10, dynamic: 0x0, fixed: 81 } 76 40 00 51
+Here we can see our factorial(5) being set up with MOVI setting the value 5, followed by the LT comparison and conditional jump JNZF. The multiplication for our factorial happens at halfword 147 with MUL { dst: 0x10, lhs: 0x10, rhs: 0x11 }. Finally, we can spot our log statement at halfword 139 with the LOGD instruction.
We can start up the debug infrastructure. On a new terminal session run fuel-core run --db-type in-memory --debug; we need to have that running because it actually executes the program. Now we can fire up the debugger itself: forc-debug. Now if everything is set up correctly, you should see the debugger prompt (>>). You can use help command to list available commands.
The debugger supports tab completion to help you discover files in your current working directory (and its subdirectories):
+tx and press tab to recursively search for valid transaction JSON filesNow we would like to inspect the program while it's running. To do this, we first need to send the script to the executor, i.e. fuel-core. To do so, we need a transaction specification, tx.json. It looks something like this:
{
+ "Script": {
+ "body": {
+ "script_gas_limit": 1000000,
+ "script": [
+ 26, 240, 48, 0, 116, 0, 0, 2, 0, 0, 0, 0, 0, 0, 3, 96, 93, 255, 192, 1, 16, 255, 255, 0, 26, 236, 80, 0, 145, 0, 0, 184, 80, 67, 176, 80, 32, 248, 51, 0, 88, 251, 224, 2, 80, 251, 224, 4, 116, 0, 0, 37, 80, 71, 176, 40, 26, 233, 16, 0, 32, 248, 51, 0, 88, 251, 224, 2, 80, 251, 224, 4, 116, 0, 0, 136, 26, 71, 208, 0, 114, 72, 0, 24, 40, 237, 20, 128, 80, 79, 176, 120, 114, 68, 0, 24, 40, 79, 180, 64, 80, 71, 176, 160, 114, 72, 0, 24, 40, 69, 52, 128, 80, 71, 176, 96, 114, 72, 0, 24, 40, 69, 52, 128, 80, 75, 176, 64, 26, 233, 16, 0, 26, 229, 32, 0, 32, 248, 51, 0, 88, 251, 224, 2, 80, 251, 224, 4, 116, 0, 0, 144, 26, 71, 208, 0, 80, 75, 176, 24, 114, 76, 0, 16, 40, 73, 20, 192, 80, 71, 176, 144, 114, 76, 0, 16, 40, 69, 36, 192, 114, 72, 0, 16, 40, 65, 20, 128, 93, 69, 0, 1, 93, 65, 0, 0, 37, 65, 16, 0, 149, 0, 0, 63, 150, 8, 0, 0, 26, 236, 80, 0, 145, 0, 1, 88, 26, 87, 224, 0, 95, 236, 16, 42, 95, 236, 0, 41, 93, 67, 176, 41, 114, 68, 0, 5, 22, 65, 4, 64, 118, 64, 0, 81, 93, 67, 176, 42, 80, 71, 176, 200, 26, 233, 16, 0, 32, 248, 51, 0, 88, 251, 224, 2, 80, 251, 224, 4, 116, 0, 0, 87, 26, 71, 208, 0, 114, 72, 0, 24, 40, 237, 20, 128, 80, 71, 176, 160, 114, 72, 0, 24, 40, 71, 180, 128, 80, 75, 176, 24, 114, 76, 0, 24, 40, 73, 20, 192, 80, 71, 176, 88, 114, 76, 0, 24, 40, 69, 36, 192, 93, 83, 176, 11, 93, 79, 176, 12, 93, 71, 176, 13, 114, 72, 0, 8, 16, 73, 20, 128, 21, 73, 36, 192, 118, 72, 0, 1, 116, 0, 0, 7, 114, 72, 0, 2, 27, 73, 52, 128, 114, 76, 0, 8, 16, 77, 36, 192, 38, 76, 0, 0, 40, 29, 68, 64, 26, 80, 112, 0, 16, 73, 68, 64, 95, 73, 0, 0, 114, 64, 0, 8, 16, 65, 20, 0, 80, 71, 176, 112, 95, 237, 64, 14, 95, 237, 48, 15, 95, 237, 0, 16, 80, 67, 176, 48, 114, 72, 0, 24, 40, 65, 20, 128, 80, 71, 176, 136, 114, 72, 0, 24, 40, 69, 4, 128, 80, 67, 177, 8, 114, 72, 0, 24, 40, 65, 20, 128, 80, 71, 177, 48, 114, 72, 0, 24, 40, 69, 4, 128, 80, 67, 177, 48, 80, 71, 176, 240, 114, 72, 0, 24, 40, 69, 4, 128, 80, 67, 176, 224, 26, 233, 16, 0, 26, 229, 0, 0, 32, 248, 51, 0, 88, 251, 224, 2, 80, 251, 224, 4, 116, 0, 0, 56, 26, 67, 208, 0, 80, 71, 176, 72, 114, 72, 0, 16, 40, 69, 4, 128, 80, 67, 177, 32, 114, 72, 0, 16, 40, 65, 20, 128, 80, 71, 176, 184, 114, 72, 0, 16, 40, 69, 4, 128, 93, 67, 240, 0, 93, 71, 176, 23, 93, 75, 176, 24, 52, 1, 4, 82, 26, 244, 0, 0, 116, 0, 0, 8, 93, 67, 176, 41, 16, 65, 0, 64, 95, 237, 0, 41, 93, 67, 176, 42, 93, 71, 176, 41, 27, 65, 4, 64, 95, 237, 0, 42, 117, 0, 0, 91, 146, 0, 1, 88, 26, 249, 80, 0, 152, 8, 0, 0, 151, 0, 0, 63, 74, 248, 0, 0, 149, 0, 0, 15, 150, 8, 0, 0, 26, 236, 80, 0, 145, 0, 0, 72, 26, 67, 160, 0, 26, 71, 224, 0, 114, 72, 4, 0, 38, 72, 0, 0, 26, 72, 112, 0, 80, 79, 176, 24, 95, 237, 32, 3, 114, 72, 4, 0, 95, 237, 32, 4, 95, 236, 0, 5, 114, 72, 0, 24, 40, 237, 52, 128, 80, 75, 176, 48, 114, 76, 0, 24, 40, 75, 180, 192, 114, 76, 0, 24, 40, 65, 36, 192, 26, 245, 0, 0, 146, 0, 0, 72, 26, 249, 16, 0, 152, 8, 0, 0, 151, 0, 0, 15, 74, 248, 0, 0, 149, 0, 0, 63, 150, 8, 0, 0, 26, 236, 80, 0, 145, 0, 0, 104, 26, 67, 160, 0, 26, 71, 144, 0, 26, 75, 224, 0, 80, 79, 176, 80, 114, 80, 0, 24, 40, 77, 5, 0, 114, 64, 0, 24, 40, 237, 52, 0, 80, 67, 176, 40, 114, 76, 0, 24, 40, 67, 180, 192, 93, 79, 176, 5, 80, 65, 0, 16, 80, 83, 176, 64, 95, 237, 48, 8, 80, 77, 64, 8, 114, 84, 0, 8, 40, 77, 5, 64, 80, 67, 176, 24, 114, 76, 0, 16, 40, 65, 68, 192, 114, 76, 0, 16, 40, 69, 4, 192, 26, 245, 16, 0, 146, 0, 0, 104, 26, 249, 32, 0, 152, 8, 0, 0, 151, 0, 0, 63, 74, 248, 0, 0, 71, 0, 0, 0, 21, 6, 230, 244, 76, 29, 98, 145
+ ],
+ "script_data": [],
+ "receipts_root": "0000000000000000000000000000000000000000000000000000000000000000"
+ },
+ "policies": {
+ "bits": "MaxFee",
+ "values": [0, 0, 0, 0]
+ },
+ "inputs": [
+ {
+ "CoinSigned": {
+ "utxo_id": {
+ "tx_id": "c49d65de61cf04588a764b557d25cc6c6b4bc0d7429227e2a21e61c213b3a3e2",
+ "output_index": 18
+ },
+ "owner": "f1e92c42b90934aa6372e30bc568a326f6e66a1a0288595e6e3fbd392a4f3e6e",
+ "amount": 10599410012256088000,
+ "asset_id": "2cafad611543e0265d89f1c2b60d9ebf5d56ad7e23d9827d6b522fd4d6e44bc3",
+ "tx_pointer": {
+ "block_height": 0,
+ "tx_index": 0
+ },
+ "witness_index": 0,
+ "maturity": 0,
+ "predicate_gas_used": null,
+ "predicate": null,
+ "predicate_data": null
+ }
+ }
+ ],
+ "outputs": [],
+ "witnesses": [
+ {
+ "data": [156, 254, 34, 102, 65, 96, 133, 170, 254, 105, 147, 35, 196, 199, 179, 133, 132, 240, 208, 149, 11, 46, 30, 96, 44, 91, 121, 195, 145, 184, 159, 235, 117, 82, 135, 41, 84, 154, 102, 61, 61, 16, 99, 123, 58, 173, 75, 226, 219, 139, 62, 33, 41, 176, 16, 18, 132, 178, 8, 125, 130, 169, 32, 108]
+ }
+ ]
+ }
+}
+However, the key script should contain the actual bytecode to execute, i.e. the contents of out/debug/dbg_example.bin as a JSON array. The following command can be used to generate it:
python3 -c 'print(list(open("out/debug/dbg_example.bin", "rb").read()))'
+So now we replace the script array with the result, and save it as tx.json.
Now we can actually execute the script with an ABI to decode the log values:
+>> start_tx tx.json out/debug/dbg_example-abi.json
+
+Receipt: LogData { id: 0000000000000000000000000000000000000000000000000000000000000000, ra: 0, rb: 1515152261580153489, ptr: 67107840, len: 8, digest: d2b80ebb9ce633ad49a9ccfcc58ac7ad33a9ab4741529ae4247a3b07e8fa1c74, pc: 10924, is: 10368, data: Some(0000000000000078) }
+Decoded log value: 120, from contract: 0000000000000000000000000000000000000000000000000000000000000000
+Receipt: ReturnData { id: 0000000000000000000000000000000000000000000000000000000000000000, ptr: 67106816, len: 0, digest: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855, pc: 10564, is: 10368, data: Some() }
+Receipt: ScriptResult { result: Success, gas_used: 1273 }
+Terminated
+Looking at the output, we can see our factorial(5) result as the decoded log value of 120. The ABI has helped us decode the raw bytes (0000000000000078) into a meaningful value. It also tells us that the execution terminated without hitting any breakpoints. That's unsurprising, because we haven't set up any. We can do so with breakpoint command:
>> breakpoint 0
+
+>> start_tx tx.json out/debug/dbg_example-abi.json
+
+Receipt: ScriptResult { result: Success, gas_used: 0 }
+Stopped on breakpoint at address 0 of contract 0x0000000000000000000000000000000000000000000000000000000000000000
+Now we have stopped execution at the breakpoint on entry (address 0). We can now inspect the initial state of the VM.
>> register ggas
+
+reg[0x9] = 1000000 # ggas
+
+>> memory 0x10 0x8
+
+ 000010: db f3 63 c9 1c 7f ec 95
+However, that's not too interesting either, so let's just execute until the end, and then reset the VM to remove the breakpoints.
+>> continue
+
+Receipt: LogData { id: 0000000000000000000000000000000000000000000000000000000000000000, ra: 0, rb: 1515152261580153489, ptr: 67107840, len: 8, digest: d2b80ebb9ce633ad49a9ccfcc58ac7ad33a9ab4741529ae4247a3b07e8fa1c74, pc: 10924, is: 10368, data: Some(0000000000000078) }
+Decoded log value: 120, from contract: 0000000000000000000000000000000000000000000000000000000000000000
+Receipt: ReturnData { id: 0000000000000000000000000000000000000000000000000000000000000000, ptr: 67106816, len: 0, digest: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855, pc: 10564, is: 10368, data: Some() }
+Terminated
+
+>> reset
+Next, we will setup a breakpoint to check the state on each iteration of the while loop. For instance, if we'd like to see what numbers get multiplied together, we could set up a breakpoint before the operation. Looking at our bytecode we can see the main multiplication for our factorial happens at:
half-word byte op raw
+ 147 588 MUL { dst: 0x10, lhs: 0x10, rhs: 0x11 } 1b 41 04 40
+We can set a breakpoint on its address, at halfword-offset 147.
>>> breakpoint 147
+
+>> start_tx tx.json out/debug/dbg_example-abi.json
+
+Receipt: ScriptResult { result: Success, gas_used: 82 }
+Stopped on breakpoint at address 588 of contract 0x0000000000000000000000000000000000000000000000000000000000000000
+Now we can inspect the inputs to multiply. Looking at the specification tells us that the instruction MUL { dst: 0x10, lhs: 0x10, rhs: 0x11 } means reg[0x10] = reg[0x10] * reg[0x11]. So inspecting the inputs:
>> r 0x10 0x11
+reg[0x10] = 1 # reg16
+reg[0x11] = 1 # reg17
+So on the first round the numbers are 1 and 1, so we can continue to the next iteration with the c command:
>> c
+Stopped on breakpoint at address 588 of contract 0x0000000000000000000000000000000000000000000000000000000000000000
+
+>> r 0x10 0x11
+reg[0x10] = 1 # reg16
+reg[0x11] = 2 # reg17
+And the next one:
+>> c
+Stopped on breakpoint at address 588 of contract 0x0000000000000000000000000000000000000000000000000000000000000000
+
+>> r 0x10 0x11
+reg[0x10] = 2 # reg16
+reg[0x11] = 3 # reg17
+And fourth one:
+>> c
+Stopped on breakpoint at address 588 of contract 0x0000000000000000000000000000000000000000000000000000000000000000
+
+>> r 0x10 0x11
+reg[0x10] = 6 # reg16
+reg[0x11] = 4 # reg17
+And round 5:
+>> c
+Stopped on breakpoint at address 588 of contract 0x0000000000000000000000000000000000000000000000000000000000000000
+
+>> r 0x10 0x11
+reg[0x10] = 24 # reg16
+reg[0x11] = 5 # reg17
+At this point we can look at the values
+| 0x10 | 0x11 |
|---|---|
| 1 | 1 |
| 1 | 2 |
| 2 | 3 |
| 6 | 4 |
| 24 | 5 |
From this we can clearly see that the left side, register 0x10 is the result variable which accumulates the factorial calculation (1, 1, 2, 6, 24), and register 0x11 is the counter which increments from 1 to 5. Now the counter equals the given factorial function argument 5, and the loop terminates. So when we continue, the program finishes without encountering any more breakpoints:
>> c
+
+Receipt: LogData { id: 0000000000000000000000000000000000000000000000000000000000000000, ra: 0, rb: 1515152261580153489, ptr: 67107840, len: 8, digest: d2b80ebb9ce633ad49a9ccfcc58ac7ad33a9ab4741529ae4247a3b07e8fa1c74, pc: 10924, is: 10368, data: Some(0000000000000078) }
+Decoded log value: 120, from contract: 0000000000000000000000000000000000000000000000000000000000000000
+Receipt: ReturnData { id: 0000000000000000000000000000000000000000000000000000000000000000, ptr: 67106816, len: 0, digest: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855, pc: 10564, is: 10368, data: Some() }
+Terminated
+The forc debug plugin also enables line-by-line debugging of Sway unit tests in VSCode.
which forc-debug.
+It can be installed with fuelup component add forc-debug..vscode/launch.json file with the following contents:{
+ "version": "0.2.0",
+ "configurations": [
+ {
+ "type": "sway",
+ "request": "launch",
+ "name": "Debug Sway",
+ "program": "${file}"
+ }]
+}
+Given this example contract:
+contract;
+
+abi CallerContract {
+ fn test_false() -> bool;
+}
+
+impl CallerContract for Contract {
+ fn test_false() -> bool {
+ false
+ }
+}
+
+abi CalleeContract {
+ fn test_true() -> bool;
+}
+
+#[test]
+fn test_multi_contract_calls() {
+ let caller = abi(CallerContract, CONTRACT_ID);
+ let callee = abi(CalleeContract, callee::CONTRACT_ID);
+
+ let should_be_false = caller.test_false();
+ let should_be_true = callee.test_true();
+ assert(!should_be_false);
+ assert(should_be_true);
+}
+Within the sway file open in VSCode, you can set breakpoints on lines within the test or functions that it calls, and click Run -> Start Debugging to begin debugging the unit test.
+This will build the sway project and run it in debug mode. The debugger will stop the VM execution when a breakpoint is hit.
+The debug panel will show VM registers under the Variables tab, as well as the current VM opcode where execution is suspended. You can continue execution, or use the Step Over function to step forward, instruction by instruction.
+Welcome to the documentation for Sway LSP, the language server designed specifically for the Sway programming language. This documentation serves as a comprehensive guide to help you understand and utilize the powerful features provided by Sway LSP.
+Sway LSP is built on the Language Server Protocol (LSP), a standardized protocol for enabling rich programming language support in editor and IDE environments. It acts as a bridge between your favorite code editor or integrated development environment and the Sway programming language, offering advanced semantic analysis and a wide range of features to enhance your development experience.
+With Sway LSP, you can expect a seamless and efficient coding experience while working with the Sway programming language. It provides intelligent code completion, precise symbol navigation, type information, and other smart features that empower you to write clean and error-free code. By leveraging the power of Sway LSP, you can increase productivity, reduce debugging time, and write high-quality code with confidence.
+In this documentation, you will find detailed information about how to set up Sway LSP in your preferred code editor or IDE, configure its settings to match your coding style, and take advantage of its various features. We will guide you through the installation process, provide examples of typical configuration setups, and walk you through the usage of each feature supported by Sway LSP.
+Whether you are a beginner or an experienced Sway developer, this documentation aims to be your go-to resource for understanding and maximizing the capabilities of Sway LSP. So let's dive in and unlock the full potential of the Sway programming language with Sway LSP!
+ +The Sway language server is contained in the forc-lsp binary, which is installed as part of the Fuel toolchain. Once installed, it can be used with a variety of IDEs. It must be installed for any of the IDE plugins to work.
++Note: There is no need to manually run
+forc-lsp(the plugin will automatically start it), however bothforcandforc-lspmust be in your$PATH. To check ifforcis in your$PATH, typeforc --helpin your terminal.
This is the best supported editor at the moment.
+You can install the latest release of the plugin from the marketplace.
+Note that we only support the most recent version of VS Code.
+Follow the documentation for sway.vim to install.
+Install helix and Sway LSP will work out of the box.
+Sway support is built into helix using tree-sitter-sway.
+Coming soon! Feel free to contribute.
+Source: code_actions
+Quickly generate boilerplate code and code comments for functions, structs, and ABIs.
+Source: completion.rs
+Suggests code to follow partially written statements for functions and variables.
+Jumps to the definition of a symbol from its usage.
+Locates all occurrences of a symbol throughout the project.
+Source: hover
+Provides documentation, compiler diagnostics, and reference links when hovering over functions and variables.
+Source: inlay_hints.rs
+Displays the implied type of a variable next to the variable name. Configurable in Settings.
+Source: rename.rs
+Renames a symbol everywhere in the workspace.
+Source: diagnostic.rs
+Displays compiler warnings and errors inline.
+Source: highlight.rs
+Highlights code based on type and context.
+Source: runnable.rs
+Shows a button above a runnable function or test.
+First, confirm you are running the most recent version:
+fuelup toolchain install latest
+fuelup update
+forc-lsp --version
+Second, confirm that your $PATH resolves to the forc-lsp binary in $HOME/.fuelup/bin.
which forc-lsp
+If you are experiencing slow performance, you can try the following:
+Follow the steps above to ensure you are running the most recent version.
+Then, make sure you only have the most recent version of the LSP server running.
+pkill forc-lsp
+Sway projects with ten or more Sway files are likely to have slower LSP performance. We are working on better support for large projects.
+In the meantime, if it's too slow, you can disable the LSP server entirely with the sway-lsp.diagnostic.disableLsp setting. The extension will still provide basic syntax highlighting, command palettes, as well as the Sway debugger, but all other language features will be disabled.
You can enable verbose logging of the LSP server.
+In VSCode, this is under the setting:
+"sway-lsp.trace.server": "verbose"
+Once enabled, you can find this in the output window under Sway Language Server.
+For other editors, see Installation for links to documentation.
+The purpose of Sway Libraries is to contain libraries which users can import and use that are not part of the standard library.
+These libraries contain helper functions and other tools valuable to blockchain development.
+For more information on how to use a Sway-Libs library, please refer to the Sway-Libs Book.
+Asset Libraries are any libraries that use Native Assets on the Fuel Network.
+Access Control and Security Libraries are any libraries that are built and intended to provide additional safety when developing smart contracts.
+Cryptography Libraries are any libraries that provided cryptographic functionality beyond what the std-lib provides.
+Math Libraries are libraries which provide mathematic functions or number types that are outside of the std-lib's scope.
+Data Structure Libraries are libraries which provide complex data structures which unlock additional functionality for Smart Contracts.
+The Sway compiler supports a list of intrinsics that perform various low level operations that are useful for building libraries. Compiler intrinsics should rarely be used but are preferred over asm blocks because they are type-checked and are safer overall. Below is a list of all available compiler intrinsics:
__size_of_val<T>(val: T) -> u64
+Description: Return the size of type T in bytes.
Constraints: None.
+__size_of<T>() -> u64
+Description: Return the size of type T in bytes.
Constraints: None.
+__size_of_str_array<T>() -> u64
+Description: Return the size of type T in bytes. This intrinsic differs from __size_of in the case of "string arrays" where the actual length in bytes of the string is returned without padding the byte size to the next word alignment. When T is not a "string array" 0 is returned.
Constraints: None.
+__assert_is_str_array<T>()
+Description: Throws a compile error if type T is not a "string array".
Constraints: None.
+__to_str_array(s: str) -> str[N]
+Description: Converts a "string slice" to "string array" at compile time. Parameter "s" must be a string literal.
+Constraints: None.
+__is_reference_type<T>() -> bool
+Description: Returns true if T is a reference type and false otherwise.
Constraints: None.
+__is_str_array<T>() -> bool
+Description: Returns true if T is a string array and false otherwise.
Constraints: None.
+__eq<T>(lhs: T, rhs: T) -> bool
+Description: Returns whether lhs and rhs are equal.
Constraints: T is bool, u8, u16, u32, u64, u256, b256 or raw_ptr.
__gt<T>(lhs: T, rhs: T) -> bool
+Description: Returns whether lhs is greater than rhs.
Constraints: T is u8, u16, u32, u64, u256, b256.
__lt<T>(lhs: T, rhs: T) -> bool
+Description: Returns whether lhs is less than rhs.
Constraints: T is u8, u16, u32, u64, u256, b256.
__gtf<T>(index: u64, tx_field_id: u64) -> T
+Description: Returns transaction field with ID tx_field_id at index index, if applicable. This is a wrapper around FuelVM's gtf instruction. The resulting field is cast to T.
Constraints: None.
+__addr_of<T>(val: T) -> raw_ptr
+Description: Returns the address in memory where val is stored.
Constraints: T is a reference type.
__state_load_word(key: b256) -> u64
+Description: Reads and returns a single word from storage at key key.
Constraints: None.
+__state_load_quad(key: b256, ptr: raw_ptr, slots: u64) -> bool
+Description: Reads slots number of slots (b256 each) from storage starting at key key and stores them in memory starting at address ptr. Returns a Boolean describing whether all the storage slots were previously set.
Constraints: None.
+__state_store_word(key: b256, val: u64) -> bool
+Description: Stores a single word val into storage at key key. Returns a Boolean describing whether the store slot was previously set.
Constraints: None.
+__state_store_quad(key: b256, ptr: raw_ptr, slots: u64) -> bool
+Description: Stores slots number of slots (b256 each) starting at address ptr in memory into storage starting at key key. Returns a Boolean describing whether the first storage slot was previously set.
Constraints: None.
+__log<T>(val: T)
+Description: Logs value val.
Constraints: None.
+__add<T>(lhs: T, rhs: T) -> T
+Description: Adds lhs and rhs and returns the result.
Constraints: T is an integer type, i.e. u8, u16, u32, u64, u256.
__sub<T>(lhs: T, rhs: T) -> T
+Description: Subtracts rhs from lhs.
Constraints: T is an integer type, i.e. u8, u16, u32, u64, u256.
__mul<T>(lhs: T, rhs: T) -> T
+Description: Multiplies lhs by rhs.
Constraints: T is an integer type, i.e. u8, u16, u32, u64, u256.
__div<T>(lhs: T, rhs: T) -> T
+Description: Divides lhs by rhs.
Constraints: T is an integer type, i.e. u8, u16, u32, u64, u256.
__and<T>(lhs: T, rhs: T) -> T
+Description: Bitwise AND lhs and rhs.
Constraints: T is an integer type, i.e. u8, u16, u32, u64, u256, b256.
__or<T>(lhs: T, rhs: T) -> T
+Description: Bitwise OR lhs and rhs.
Constraints: T is an integer type, i.e. u8, u16, u32, u64, u256, b256.
__xor<T>(lhs: T, rhs: T) -> T
+Description: Bitwise XOR lhs and rhs.
Constraints: T is an integer type, i.e. u8, u16, u32, u64, u256, b256.
__mod<T>(lhs: T, rhs: T) -> T
+Description: Modulo of lhs by rhs.
Constraints: T is an integer type, i.e. u8, u16, u32, u64, u256.
__rsh<T>(lhs: T, rhs: u64) -> T
+Description: Logical right shift of lhs by rhs.
Constraints: T is an integer type, i.e. u8, u16, u32, u64, u256, b256.
__lsh<T>(lhs: T, rhs: u64) -> T
+Description: Logical left shift of lhs by rhs.
Constraints: T is an integer type, i.e. u8, u16, u32, u64, u256, b256.
__revert(code: u64)
+Description: Reverts with error code code.
Constraints: None.
+__ptr_add(ptr: raw_ptr, offset: u64)
+Description: Adds offset to the raw value of pointer ptr.
Constraints: None.
+__ptr_sub(ptr: raw_ptr, offset: u64)
+Description: Subtracts offset to the raw value of pointer ptr.
Constraints: None.
+__smo<T>(recipient: b256, data: T, coins: u64)
+Description: Sends a message data of arbitrary type T and coins amount of the base asset to address recipient.
Constraints: None.
+__not(op: T) -> T
+Description: Bitwise NOT of op
Constraints: T is an integer type, i.e. u8, u16, u32, u64, u256, b256.
__jmp_mem()
+Description: Jumps to MEM[$hp].
Constraints: None.
+__slice(item: &[T; N], start: u64, end: u64) -> &[T]
+__slice(item: &[T], start: u64, end: u64) -> &[T]
+__slice(item: &mut [T; N], start: u64, end: u64) -> &mut [T]
+__slice(item: &mut [T], start: u64, end: u64) -> &mut [T]
+Description: Slices an array or another slice.
+This intrinsic returns a reference to a slice containing the range of elements inside item.
+The mutability of reference is defined by the first parameter mutability.
Runtime bound checks are not generated, and must be done manually when and where appropriated. Compile time bound checks are done when possible.
+Constraints:
+item is an array or a slice;start is a literal, it must be smaller than item length;end is a literal, it must be smaller than or equal to item length;end must be greater than or equal to start__elem_at(item: &[T; N], index: u64) -> &T
+__elem_at(item: &[T], index: u64) -> &T
+__elem_at(item: &mut [T; N], index: u64) -> &mut T
+__elem_at(item: &mut [T], index: u64) -> &mut T
+Description: Returns a reference to the indexed element. The mutability of reference is defined by the first parameter mutability.
+Runtime bound checks are not generated, and must be done manually when and where appropriated. Compile time bound checks are done when possible.
+Constraints:
+item is a reference to an array or a reference to a slice;index is a literal, it must be smaller than item length;The Sway compiler supports a list of attributes that perform various operations that are useful for building, testing and documenting Sway programs. Below is a list of all available attributes:
+The #[allow(...)] attribute overrides checks so that violations will go unreported. The following checks can be disabled:
#[allow(dead_code)] disable checks for dead code;#[allow(deprecated)] disables checks for usage of deprecated structs, functions and other items.The #[doc(..)] attribute specifies documentation.
Line doc comments beginning with exactly three slashes ///, are interpreted as a special syntax for doc attributes. That is, they are equivalent to writing #[doc("...")] around the body of the comment, i.e., /// Foo turns into #[doc("Foo")]
Line comments beginning with //! are doc comments that apply to the module of the source file they are in. That is, they are equivalent to writing #![doc("...")] around the body of the comment. //! module level doc comments should be at the top of Sway files.
Documentation can be generated from doc attributes using forc doc.
The inline attribute suggests that a copy of the attributed function should be placed in the caller, rather than generating code to call the function where it is defined.
+++Note: The Sway compiler automatically inlines functions based on internal heuristics. Incorrectly inlining functions can make the program slower, so this attribute should be used with care.
+
The #[inline(never)] attribute suggests that an inline expansion should never be performed.
The #[inline(always)] attribute suggests that an inline expansion should always be performed.
++Note:
+#[inline(..)]in every form is a hint, with no requirements +on the language to place a copy of the attributed function in the caller.
The lack of #[payable] implies the method is non-payable. When calling an ABI method that is non-payable, the compiler emits an error if the amount of coins forwarded with the call is not guaranteed to be zero. Note that this is strictly a compile-time check and does not incur any runtime cost.
In Sway, functions are pure by default but can be opted into impurity via the storage function attribute. The storage attribute may take read and/or write arguments indicating which type of access the function requires.
The #[storage(read)] attribute indicates that a function requires read access to the storage.
The #[storage(write)] attribute indicates that a function requires write access to the storage.
More details in Purity.
+The #[test] attribute marks a function to be executed as a test.
The #[test(should_revert)] attribute marks a function to be executed as a test that should revert.
More details in Unit Testing.
+The #[deprecated] attribute marks an item as deprecated and makes the compiler emit a warning for every usage of the deprecated item. This warning can be disabled using #[allow(deprecated)].
It is possible to improve the warning message with #[deprecated(note = "your message")]
The #[fallback] attribute makes the compiler use the marked function as the contract call fallback function, which means that, when a contract is called, and the contract selection fails, the fallback function will be called instead.
In Sway, structs, traits, and enums are CapitalCase. Modules, variables, and functions are snake_case, constants are SCREAMING_SNAKE_CASE. The compiler will warn you if your capitalization is ever unidiomatic.
impl blocks need to be defined before any of the functions they define can be called. This includes sibling functions in the same impl declaration, i.e., functions in an impl can't call each other yet.storage block are not yet supported. See the Manual Storage Management section for details on how to use store and get from the standard library to manage storage slots directly. Note, however, that StorageMap<K, V> does support arbitrary types for K and V without any limitations.Sway code that contains any of the following behavior is considered undefined. +The compiler is allowed to treat undefined Sway code however it desires, +including removing it or replacing it with any other Sway code.
+This is not an exhaustive list, it may grow or shrink, there is no formal model +of Sway's semantics so there may be more behavior considered undefined. We +reserve the right to make some of the listed behavior defined in the future.
+raw_ptr and raw_slice.Iterators.This page outlines some of the critical differences between Sway and Solidity, and between the FuelVM and the EVM.
+The underlying virtual machine targeted by Sway is the FuelVM, specified here. Solidity targets the Ethereum Virtual Machine (EVM), specified here.
+Words in the FuelVM are 64 bits (8 bytes), rather than the 256 bits (32 bytes) of the EVM. Therefore, all primitive integers smaller and including u64 are stored in registers; u256, being bigger than the registers, and hashes (the b256 type) are not stored in registers but rather in memory. They are therefore pointers to a 32-byte memory region containing their data.
Only unsigned integers are provided as primitives: u8, u16, u32, u64, and u256. Signed integer arithmetic is not available in the FuelVM. Signed integers and signed integer arithmetic can be implemented in high-level libraries if needed.
Panics in the FuelVM (called "reverts" in Solidity and the EVM) are global, i.e. they cannot be caught. A panic will completely and unconditionally revert the stateful effects of a transaction, minus gas used.
+Math in the FuelVM is by default safe (i.e. any overflow or exception is a panic). Safety checks are performed natively in the VM implementation, rather than at the bytecode level like Solidity's default safe math.
+ +There is no practical code size limit to Sway contracts. The physical limit is governed by the VM_MAX_RAM VM parameter, which at the time of writing is 64 MiB.
Account types in the FuelVM have type-safe wrappers around primitive b256 hashes to clearly distinguish their respective types. The wrapper Address mirrors that of an EOA (Externally Owned Account) and has the ability to hold UTXOs in the context of the EVM. The other wrapper, ContractId, reflects that of a deployed contract in the EVM but cannot hold UTXOs.
Sway shares a lot with Rust, especially its syntax. Because they are so similar, you may be surprised or caught off guard when they differ. This page serves to outline, from a high level, some of the syntactic gotchas that you may encounter.
+In Rust, enums generally take one of three forms: unit variants, which have no inner data, struct variants, which contain named fields, and tuple variants, which contain within them a tuple of data. If you are unfamiliar with these terms, this is what they look like:
+// note to those skimming the docs: this is Rust syntax! Not Sway! Don't copy/paste this into a Sway program.
+
+enum Foo {
+ UnitVariant,
+ TupleVariant(u32, u64, bool),
+ StructVariant {
+ field_one: bool,
+ field_two: bool
+ }
+}In Sway, enums are simplified. Enums variants must all specify exactly one type. This type represents their interior data. This is actually isomorphic to what Rust offers, but with a different syntax. You can see the above enum but with Sway syntax below:
+// This is equivalent Sway syntax for the above Rust enum.
+enum Foo {
+ UnitVariant: (),
+ TupleVariant: (u32, u64, bool),
+ StructVariant: MyStruct,
+}
+
+struct MyStruct {
+ field_one: bool,
+ field_two: bool,
+}
+In Rust, the borrow checker implements Rust's ownership system
+In Sway, there is no borrow checker. This means there is no concept of ownership, borrowing, or lifetimes. Instead, objects are copied and moved similar to C++. Also Sway does not have any destructors nor Drop traits. This means allocated memory lives for the entire transaction and is not deallocated until the end of the transaction. A transaction may allocate up to 64 MB of memory.
Thanks for your interest in contributing to Sway! This document outlines the process for installing and setting up the Sway toolchain for development, as well as some conventions on contributing to Sway.
+If you run into any difficulties getting started, you can always ask questions on our Discourse.
+See the introduction section for instructions on installing and setting up the Sway toolchain.
+git clone https://github.com/FuelLabs/sway
+cd sway
+The following steps will run the sway test suite and ensure that everything is set up correctly.
+First, open a new terminal and start fuel-core with:
fuel-core
+Then open a second terminal, cd into the sway repo and run:
cargo run --bin test
+After the test suite runs, you should see:
+Tests passed.
+_n_ tests run (0 skipped)
+Congratulations! You've now got everything setup and are ready to start making contributions.
+There are many ways in which you may contribute to the Sway project, some of which involve coding knowledge and some which do not. A few examples include:
+Check out our Help Wanted, Sway Book or Good First Issue issues to find a suitable task.
+If you are planning something big, for example, related to multiple components or changes current behaviors, make sure to open an issue to discuss with us before starting on the implementation.
+This is a rough outline of what a contributor's workflow looks like:
+Thanks for your contributions!
+Pull requests should be linked to at least one issue in the same repo.
+If the pull request resolves the relevant issues, and you want GitHub to close these issues automatically after it merged into the default branch, you can use the syntax (KEYWORD #ISSUE-NUMBER) like this:
close #123
+If the pull request links an issue but does not close it, you can use the keyword ref like this:
ref #456
+Multiple issues should use full syntax for each issue and separate by a comma, like:
+close #123, ref #456
+The following list contains keywords that are reserved for current or +future use by the Sway language. As such, they cannot be used as +identifiers. Identifiers are names of functions, variables, +parameters, modules, constants, attributes, types or +traits, etc.
+The following is a list of keywords currently in use, with their +functionality described.
+as - rename items in use statements, e.g., use type::a as alias_nameabi - defines a smart contract ABI in a syntactically similar way to traitsbreak - exit a loop immediatelyconst - define constant itemscontinue - continue to the next loop iterationelse - used in conjunction with if conditions for control flow constructsenum - define an enumerationfalse - Boolean false literalfn- define a function or the function pointer typeif - branch based on the result of a conditional expressionimpl - implement inherent or trait functionalitylet - bind a variablematch - exhaustively match a value to patternsmod - define a modulemut - denote mutability in references, or pattern bindingspub - denote public visibility of Sway data structures, traits, or modulesref - bind by referencereturn - return early from a functionSelf - a type alias for the type we are defining or implementingself - method subjectstruct - define a structuretrait - define a traittrue - Boolean true literaltype - define a type alias or associated typeuse - bring symbols into scopewhere - specifies traits for generic typeswhile - loop conditionally based on the result of an expressionabstractasyncawaitbecomeboxdodynexternforinloopmacromoveoverrideprivstaticsupertrytypeofunsafeunsizedvirtualyieldKeywords associated with defining the type of Sway program to compile
+contract - analogous to a deployed API with some database statelibrary - Sway code that defines new common behaviorpredicate - programs that return a Boolean value and which represent ownership of some resource upon execution to truescript - a runnable bytecode on the chain, which executes once to perform a taskKeywords associated with defining the functionality of attributes
+allow - overrides checks that would otherwise result in errors or warningsdoc - specifies documentationinline - suggests that a copy of the attributed function should be placed in the caller, rather than generating code to call the function where it is definedpayable - implies method is payable for compile timestorage - declaration that contains a list of stored variablestest - marks a function to be executed as a testdeprecated - marks an item as deprecatedForc stands for Fuel Orchestrator. Forc provides a variety of tools and commands for developers working with the Fuel ecosystem, such as scaffolding a new project, formatting, running scripts, deploying contracts, testing contracts, and more. If you're coming from a Rust background, forc is similar to cargo.
+If you are new to Forc, see the Forc Project introduction section.
+For a comprehensive overview of the Forc CLI commands, see the Commands section.
+The Forc.toml (the manifest file) is a compulsory file for each package and it is written in [TOML] format. Forc.toml consists of the following fields:
[project] — Defines a sway project.
name — The name of the project.version — The version of the project.description — A description of the project.authors — The authors of the project.organization — The organization of the project.license — The project license.homepage — URL of the project homepage.repository — URL of the project source repository.documentation — URL of the project documentation.entry — The entry point for the compiler to start parsing from.
+implicit-std - Controls whether provided std version (with the current forc version) will get added as a dependency implicitly. Unless you know what you are doing, leave this as default.forc-version - The minimum forc version required for this project to work properly.metadata - Metadata for the project; can be used by tools which would like to store package configuration in Forc.toml.[dependencies] — Defines the dependencies.
[network] — Defines a network for forc to interact with.
url — URL of the network.[build-profile] - Defines the build profiles.
[patch] - Defines the patches.
[contract-dependencies] - Defines the contract dependencies.
[project] sectionAn example Forc.toml is shown below. Under [project] the following fields are optional:
authorsorganizationversiondescriptionhomepagerepositorydocumentationAlso for the following fields, a default value is provided so omitting them is allowed:
+entry - (default : main.sw )implicit-std - (default : true )[project]
+authors = ["user"]
+entry = "main.sw"
+description = "Wallet contract"
+version = "1.0.0"
+homepage = "https://example.com/"
+repository = "https://example.com/"
+documentation = "https://example.com/"
+organization = "Fuel_Labs"
+license = "Apache-2.0"
+name = "wallet_contract"
+
+[project.metadata]
+indexing = { namespace = "counter-contract", schema_path = "out/release/counter-contract-abi.json" }
+Forc.tomlThe [project.metadata] section provides a dedicated space for external tools and plugins to store their configuration in Forc.toml. The metadata key names are arbitrary and do not need to match the tool's name.
Metadata can be defined at two levels:
+Workspace level - defined in the workspace's root Forc.toml:
[workspace.metadata]
+my_tool = { shared_setting = "value" }
+Project level - defined in individual project's Forc.toml:
[project.metadata.any_name_here]
+option1 = "value"
+option2 = "value"
+
+[project.metadata.my_custom_config]
+setting1 = "value"
+setting2 = "value"
+Example for an indexing tool:
+[project.metadata.indexing]
+namespace = "counter-contract"
+schema_path = "out/release/counter-contract-abi.json"
+When both workspace and project metadata exist:
+Best Practices
+Forc.toml if tool can function without itImplementation Notes
+This allows for a streamlined developer experience while maintaining clear separation between core Forc functionality and third-party tools.
+Forc.toml metadata to read contract ABI JSON file.Forc.toml metadata to read contract ABI JSON file.[dependencies] sectionThe following fields can be provided with a dependency:
+version - Desired version of the dependencypath - The path of the dependency (if it is local)git - The URL of the git repo hosting the dependencybranch - The desired branch to fetch from the git repotag - The desired tag to fetch from the git reporev - The desired rev (i.e. commit hash) referencePlease see dependencies for details
+[network] sectionFor the following fields, a default value is provided so omitting them is allowed:
+URL - (default: http://127.0.0.1:4000)[build-profile.*] sectionThe [build-profile] tables provide a way to customize compiler settings such as debug options.
The following fields can be provided for a build-profile:
+print-ast - Whether to print out the generated AST or not, defaults to false.print-dca-graph - Whether to print out the computed Dead Code Analysis (DCA) graph (in GraphViz DOT format), defaults to false.print-dca-graph-url-format - The URL format to be used in the generated DOT file, an example for VS Code would be: vscode://file/{path}:{line}:{col}.print-ir - Whether to print out the generated Sway IR (Intermediate Representation) or not, defaults to false.print-asm - Whether to print out the generated ASM (assembler), defaults to false.terse - Terse mode. Limited warning and error output, defaults to false.time_phases - Whether to output the time elapsed over each part of the compilation process, defaults to false.include_tests - Whether or not to include test functions in parsing, type-checking, and code generation. This is set to true by invocations like forc test, but defaults to false.error_on_warnings - Whether to treat errors as warnings, defaults to false.There are two default [build-profile] available with every manifest file. These are debug and release profiles. If you want to override these profiles, you can provide them explicitly in the manifest file like the following example:
[project]
+authors = ["user"]
+entry = "main.sw"
+organization = "Fuel_Labs"
+license = "Apache-2.0"
+name = "wallet_contract"
+
+[build-profile.debug]
+print-asm = { virtual = false, allocated = false, final = true }
+print-ir = { initial = false, final = true, modified = false, passes = []}
+terse = false
+
+[build-profile.release]
+print-asm = { virtual = true, allocated = false, final = true }
+print-ir = { initial = true, final = false, modified = true, passes = ["dce", "sroa"]}
+terse = true
+Since release and debug are implicitly included in every manifest file, you can use them by just passing --release or by not passing anything (debug is default). For using a user defined build profile there is --build-profile <profile name> option available to the relevant commands. (For an example see forc-build)
Note that providing the corresponding CLI options (like --asm) will override the selected build profile. For example if you pass both --release and --asm all, release build profile is overridden and resulting build profile would have a structure like the following:
print-ast = false
+print-ir = { initial = false, final = false, modified = false, passes = []}
+print-asm = { virtual = true, allocated = true, final = true }
+terse = false
+time-phases = false
+include-tests = false
+error-on-warnings = false
+experimental-private-modules = false
+[patch] sectionThe [patch] section of Forc.toml can be used to override dependencies with other copies. The example provided below patches https://github.com/fuellabs/sway with the test branch of the same repo.
[project]
+authors = ["user"]
+entry = "main.sw"
+organization = "Fuel_Labs"
+license = "Apache-2.0"
+name = "wallet_contract"
+
+[dependencies]
+
+[patch.'https://github.com/fuellabs/sway']
+std = { git = "https://github.com/fuellabs/sway", branch = "test" }
+In the example above, std is patched with the test branch from std repo. You can also patch git dependencies with dependencies defined with a path.
[patch.'https://github.com/fuellabs/sway']
+std = { path = "/path/to/local_std_version" }
+Just like std or core you can also patch dependencies you declared with a git repo.
[project]
+authors = ["user"]
+entry = "main.sw"
+organization = "Fuel_Labs"
+license = "Apache-2.0"
+name = "wallet_contract"
+
+[dependencies]
+foo = { git = "https://github.com/foo/foo", branch = "master" }
+
+[patch.'https://github.com/foo']
+foo = { git = "https://github.com/foo/foo", branch = "test" }
+Note that each key after the [patch] is a URL of the source that is being patched.
[contract-dependencies] sectionThe [contract-dependencies] table can be used to declare contract dependencies for a Sway contract or script. Contract dependencies are the set of contracts that our contract or script may interact with. Declaring [contract-dependencies] makes it easier to refer to contracts in your Sway source code without having to manually update IDs each time a new version is deployed. Instead, we can use forc to pin and update contract dependencies just like we do for regular library dependencies.
Contracts declared under [contract-dependencies] are built and pinned just like regular [dependencies] however rather than importing each contract dependency's entire public namespace we instead import their respective contract IDs as CONTRACT_ID constants available via each contract dependency's namespace root. This means you can use a contract dependency's ID as if it were declared as a pub const in the root of the contract dependency package as demonstrated in the example below.
Entries under [contract-dependencies] can be declared in the same way that [dependencies] can be declared. That is, they can refer to the path or git source of another contract. Note that entries under [contract-dependencies] must refer to contracts and will otherwise produce an error.
Example Forc.toml:
[project]
+authors = ["user"]
+entry = "main.sw"
+organization = "Fuel_Labs"
+license = "Apache-2.0"
+name = "wallet_contract"
+
+[contract-dependencies]
+foo = { path = "../foo" }
+Example usage:
+script;
+
+fn main() {
+ let foo_id = foo::CONTRACT_ID;
+}
+Because the ID of a contract is computed deterministically, rebuilding the same contract would always result in the same contract ID. Since two contracts with the same contract ID cannot be deployed on the blockchain, a "salt" factor is needed to modify the contract ID. For each contract dependency declared under [contract-dependencies], salt can be specified. An example is shown below:
[contract-dependencies]
+foo = { path = "../foo", salt = "0x1000000000000000000000000000000000000000000000000000000000000000" }
+For contract dependencies that do not specify any value for salt, a default of all zeros for salt is implicitly applied.
A workspace is a collection of one or more packages, namely workspace members, that are managed together.
+The key points for workspaces are:
+forc commands available for a single package can also be used for a workspace, like forc build or forc deploy.Forc.lock file which resides in the root directory of the workspace.Workspace manifests are declared within Forc.toml files and support the following fields:
An empty workspace can be created with forc new --workspace or forc init --workspace.
members fieldThe members field defines which packages are members of the workspace:
[workspace]
+members = ["member1", "path/to/member2"]
+The members field accepts entries to be given in relative path with respect to the workspace root.
+Packages that are located within a workspace directory but are not contained within the members set are ignored.
[patch] sectionThe [patch] section can be used to override any dependency in the workspace dependency graph. The usage is the same with package level [patch] section and details can be seen here.
It is not allowed to declare patch table in member of a workspace if the workspace manifest file contains a patch table.
+Example:
+[workspace]
+members = ["member1", "path/to/member2"]
+
+
+[patch.'https://github.com/fuellabs/sway']
+std = { git = "https://github.com/fuellabs/sway", branch = "test" }
+In the above example each occurrence of std as a dependency in the workspace will be changed with std from test branch of sway repo.
forc commands that support workspacesforc build - Builds an entire workspace.forc deploy - Builds and deploys all deployable members (i.e, contracts) of the workspace in the correct order.forc run - Builds and runs all scripts of the workspace.forc check - Checks all members of the workspace.forc update - Checks and updates workspace level Forc.lock file that is shared between workspace members.forc clean - Cleans all output artifacts for each member of the workspace.forc fmt - Formats all members of a workspace.Forc has a dependency management system which can pull packages using git and ipfs. This allows users to build and share Forc libraries.
If your Forc.toml doesn't already have a [dependencies] table, add one. Below, list the package name alongside its source. Currently, forc supports git, ipfs and path sources.
If a git source is specified, forc will fetch the git repository at the given URL and then search for a Forc.toml for a package with the given name anywhere inside the git repository.
The following example adds a library dependency named custom_lib. For git dependencies you may optionally specify a branch, tag, or rev (i.e. commit hash) reference.
[dependencies]
+custom_lib = { git = "https://github.com/FuelLabs/custom_lib", branch = "master" }
+# custom_lib = { git = "https://github.com/FuelLabs/custom_lib", tag = "v0.0.1" }
+# custom_lib = { git = "https://github.com/FuelLabs/custom_lib", rev = "87f80bdf323e2d64e213895d0a639ad468f4deff" }
+Depending on a local library using path:
[dependencies]
+custom_lib = { path = "../custom_lib" }
+For ipfs sources, forc will fetch the specified cid using either a local ipfs node or a public gateway. forc automatically tries to connect to local ipfs node. If it fails, it defaults to using https://ipfs.io/ as a gateway.
The following example adds a dependency with an ipfs source.
[dependencies]
+custom_lib = { ipfs = "QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG" }
+Once the package is added, running forc build will automatically download added dependencies.
To update dependencies in your Forc directory you can run forc update. For path and ipfs dependencies this will have no effect. For git dependencies with a branch reference, this will update the project to use the latest commit for the given branch.
Here are a list of commands available to forc:
+Usage: forc addr2line [OPTIONS] --sourcemap-path <SOURCEMAP_PATH> --opcode-index <OPCODE_INDEX>
+Options:
+-S, --search-dir <SEARCH_DIR>
Where to search for the project root [default: .]
+-g, --sourcemap-path <SOURCEMAP_PATH>
Source file mapping in JSON format
+-c, --context <CONTEXT>
How many lines of context to show [default: 2]
+-i, --opcode-index <OPCODE_INDEX>
Opcode index
+-v, --verbose...
Use verbose output
+-s, --silent
Silence all output
+-L, --log-level <LOG_LEVEL>
Set the log level
+-h, --help
Print help
+The output produced will depend on the project's program type.
+script, predicate and contract projects will produce their bytecode in binary format <project-name>.bin.
script projects will also produce a file containing the hash of the bytecode binary <project-name>-bin-hash (using fuel_cypto::Hasher).
predicate projects will also produce a file containing the root hash of the bytecode binary <project-name>-bin-root (using fuel_tx::Contract::root_from_code).
contract and library projects will also produce the public ABI in JSON format <project-name>-abi.json.
Usage: forc build [OPTIONS]
+Options:
+-p, --path <PATH>
Path to the project.
+If not specified, current working directory will be used.
+--offline
Offline mode.
+Prevents Forc from using the network when managing dependencies. Meaning it will only try to use previously downloaded dependencies.
+-t, --terse
Terse mode.
+Limited warning and error output.
+--output-directory <OUTPUT_DIRECTORY>
The directory in which Forc output artifacts are placed.
+By default, this is <project-root>/out.
--locked
Requires that the Forc.lock file is up-to-date.
+If the lock file is missing, or it needs to be updated, Forc will exit with an error.
+--ipfs-node <IPFS_NODE>
The IPFS node to use for fetching IPFS sources.
+[possible values: PUBLIC, LOCAL, <GATEWAY_URL>]
+--ast
Print the generated Sway AST (Abstract Syntax Tree)
+--dca-graph <DCA_GRAPH>
Print the computed Sway DCA (Dead Code Analysis) graph.
+DCA graph is printed to the specified path. If specified '' graph is printed to the stdout.
+--dca-graph-url-format <DCA_GRAPH_URL_FORMAT>
URL format to be used in the generated DCA graph .dot file.
+Variables {path}, {line}, and {col} can be used in the provided format. +An example for vscode would be: +"vscode://file/{path}:{line}:{col}"
+--asm <ASM>..>
Print the generated ASM (assembler).
+Values that can be combined:
+[possible values: virtual, allocated, abstract, final, all]
+--bytecode
Print the bytecode.
+This is the final output of the compiler.
+--ir <IR>..>
Print the generated Sway IR (Intermediate Representation).
+Values that can be combined:
+[possible values: initial, final, all, modified, inline, simplify-cfg, sroa, dce, fn-dce, fn-dedup-release, fn-dedup-debug, mem2reg, memcpyopt, const-folding, arg-demotion, const-demotion, ret-demotion, misc-demotion]
+--time-phases
Output the time elapsed over each part of the compilation process
+--profile
Profile the compilation process
+--reverse-order
Output build errors and warnings in reverse order
+-v, --verbose...
Use verbose output
+--metrics-outfile <METRICS_OUTFILE>
Output compilation metrics into the specified file
+-s, --silent
Silence all output
+--json-abi
Minify JSON ABI files.
+By default the JSON for ABIs is formatted for human readability. By using this option JSON output will be "minified", i.e. all on one line without whitespace.
+-L, --log-level <LOG_LEVEL>
Set the log level
+--json-storage-slots
Minify JSON storage slot files.
+By default the JSON for initial storage slots is formatted for human readability. By using this option JSON output will be "minified", i.e. all on one line without whitespace.
+-o, --output-bin <BIN_FILE>
Create a binary file at the provided path representing the final bytecode
+-g, --output-debug <DEBUG_FILE>
Create a file at the provided path containing debug information.
+If the file extension is .json, JSON format is used. Otherwise, an .elf file containing DWARF format is emitted.
+--build-profile <BUILD_PROFILE>
The name of the build profile to use
+[default: debug]
+--release
Use the release build profile.
+The release profile can be customized in the manifest file.
+--error-on-warnings
Treat warnings as errors
+--build-target <BUILD_TARGET>
Build target to use for code generation
+[default: fuel] +[possible values: fuel, evm]
+--tests
Also build all tests within the project
+--experimental <EXPERIMENTAL>
Comma separated list of all experimental features that will be enabled
+[possible values: new_encoding, storage_domains, references, error_type, partial_eq]
+--no-experimental <NO_EXPERIMENTAL>
Comma separated list of all experimental features that will be disabled
+[possible values: new_encoding, storage_domains, references, error_type, partial_eq]
+-h, --help
Print help (see a summary with '-h')
+-V, --version
Print version
+EXAMPLES:
+forc build
+forc build --path
forc build --path
Compile the sway files of the current project.
+$ forc build
+Compiled script "my-fuel-project".
+Bytecode size is 28 bytes.
+The output produced will depend on the project's program type. Building script, predicate and contract projects will produce their bytecode in binary format <project-name>.bin. Building contracts and libraries will also produce the public ABI in JSON format <project-name>-abi.json.
By default, these artifacts are placed in the out/ directory.
If a Forc.lock file did not yet exist, it will be created in order to pin each of the dependencies listed in Forc.toml to a specific commit or version.
This will essentially compile the packages without performing the final step of code generation, which is faster than running forc build.
+Usage: forc check [OPTIONS] [BUILD_TARGET]
+Arguments: +[BUILD_TARGET] +Build target to use for code generation
+[default: fuel] +[possible values: fuel, evm]
+Options:
+-p, --path <PATH>
Path to the project, if not specified, current working directory will be used
+--offline
Offline mode, prevents Forc from using the network when managing dependencies. Meaning it will only try to use previously downloaded dependencies
+--locked
Requires that the Forc.lock file is up-to-date. If the lock file is missing, or it needs to be updated, Forc will exit with an error
+-t, --terse
Terse mode. Limited warning and error output
+--disable-tests
Disable checking unit tests
+--ipfs-node <IPFS_NODE>
The IPFS Node to use for fetching IPFS sources.
+Possible values: PUBLIC, LOCAL, <GATEWAY_URL>
+--experimental <EXPERIMENTAL>
Comma separated list of all experimental features that will be enabled
+[possible values: new_encoding, storage_domains, references, error_type, partial_eq]
+--no-experimental <NO_EXPERIMENTAL>
Comma separated list of all experimental features that will be disabled
+[possible values: new_encoding, storage_domains, references, error_type, partial_eq]
+-v, --verbose...
Use verbose output
+-s, --silent
Silence all output
+-L, --log-level <LOG_LEVEL>
Set the log level
+-h, --help
Print help (see a summary with '-h')
+-V, --version
Print version
+EXAMPLES:
+forc check
+forc check --path
forc check --locked
+Usage: forc clean [OPTIONS]
+Options:
+-p, --path <PATH>
Path to the project, if not specified, current working directory will be used
+-v, --verbose...
Use verbose output
+-s, --silent
Silence all output
+-L, --log-level <LOG_LEVEL>
Set the log level
+-h, --help
Print help
+-V, --version
Print version
+EXAMPLES:
+forc clean
+forc clean --path
Usage: forc completions [OPTIONS] --target
Options:
+-T, --target <TARGET>
Specify shell to enable tab-completion for
+[possible values: zsh, bash, fish, powershell, elvish]
+For more info: https://fuellabs.github.io/sway/latest/forc/commands/forc_completions.html
+Possible values:
+-v, --verbose...
Use verbose output
+-s, --silent
Silence all output
+-L, --log-level <LOG_LEVEL>
Set the log level
+-h, --help
Print help (see a summary with '-h')
+Enable tab completion for Bash, Fish, Zsh, or PowerShell
+The script is output on stdout, allowing one to re-direct the
+output to the file of their choosing. Where you place the file
+will depend on which shell, and which operating system you are
+using. Your particular configuration may also determine where
+these scripts need to be placed.
Here are some common set ups for the three supported shells under +Unix and similar operating systems (such as GNU/Linux).
+Completion files are commonly stored in /etc/bash_completion.d/ for
+system-wide commands, but can be stored in
+~/.local/share/bash-completion/completions for user-specific commands.
+Run the command:
mkdir -p ~/.local/share/bash-completion/completions
+forc completions --shell=bash >> ~/.local/share/bash-completion/completions/forc
+This installs the completion script. You may have to log out and +log back in to your shell session for the changes to take effect.
+Homebrew stores bash completion files within the Homebrew directory.
+With the bash-completion brew formula installed, run the command:
mkdir -p $(brew --prefix)/etc/bash_completion.d
+forc completions --shell=bash > $(brew --prefix)/etc/bash_completion.d/forc.bash-completion
+Fish completion files are commonly stored in
+$HOME/.config/fish/completions. Run the command:
mkdir -p ~/.config/fish/completions
+forc completions --shell=fish > ~/.config/fish/completions/forc.fish
+This installs the completion script. You may have to log out and +log back in to your shell session for the changes to take effect.
+ZSH completions are commonly stored in any directory listed in
+your $fpath variable. To use these completions, you must either
+add the generated script to one of those directories, or add your
+own to this list.
Adding a custom directory is often the safest bet if you are
+unsure of which directory to use. First create the directory; for
+this example we'll create a hidden directory inside our $HOME
+directory:
mkdir ~/.zfunc
+Then add the following lines to your .zshrc just before
+compinit:
fpath+=~/.zfunc
+Now you can install the completions script using the following +command:
+forc completions --shell=zsh > ~/.zfunc/_forc
+You must then either log out and log back in, or simply run
+exec zsh
+for the new completions to take effect.
+Alternatively, you could save these files to the place of your
+choosing, such as a custom directory inside your $HOME. Doing so
+will require you to add the proper directives, such as sourceing
+inside your login script. Consult your shells documentation for
+how to add such directives.
The powershell completion scripts require PowerShell v5.0+ (which +comes with Windows 10, but can be downloaded separately for windows 7 +or 8.1).
+First, check if a profile has already been set
+Test-Path $profile
+If the above command returns False run the following
New-Item -path $profile -type file -force
+Now open the file provided by $profile (if you used the
+New-Item command it will be
+${env:USERPROFILE}\Documents\WindowsPowerShell\Microsoft.PowerShell_profile.ps1
Next, we either save the completions file into our profile, or +into a separate file and source it inside our profile. To save the +completions into our profile simply use
+forc completions --shell=powershell >> ${env:USERPROFILE}\Documents\WindowsPowerShell\Microsoft.PowerShell_profile.ps1
+Usage: forc contract-id [OPTIONS]
+Options:
+-p, --path <PATH>
Path to the project.
+If not specified, current working directory will be used.
+--offline
Offline mode.
+Prevents Forc from using the network when managing dependencies. Meaning it will only try to use previously downloaded dependencies.
+-t, --terse
Terse mode.
+Limited warning and error output.
+--output-directory <OUTPUT_DIRECTORY>
The directory in which Forc output artifacts are placed.
+By default, this is <project-root>/out.
--locked
Requires that the Forc.lock file is up-to-date.
+If the lock file is missing, or it needs to be updated, Forc will exit with an error.
+--ipfs-node <IPFS_NODE>
The IPFS node to use for fetching IPFS sources.
+[possible values: PUBLIC, LOCAL, <GATEWAY_URL>]
+--json-abi
Minify JSON ABI files.
+By default the JSON for ABIs is formatted for human readability. By using this option JSON output will be "minified", i.e. all on one line without whitespace.
+--json-storage-slots
Minify JSON storage slot files.
+By default the JSON for initial storage slots is formatted for human readability. By using this option JSON output will be "minified", i.e. all on one line without whitespace.
+--ast
Print the generated Sway AST (Abstract Syntax Tree)
+--dca-graph <DCA_GRAPH>
Print the computed Sway DCA (Dead Code Analysis) graph.
+DCA graph is printed to the specified path. If specified '' graph is printed to the stdout.
+--dca-graph-url-format <DCA_GRAPH_URL_FORMAT>
URL format to be used in the generated DCA graph .dot file.
+Variables {path}, {line}, and {col} can be used in the provided format. +An example for vscode would be: +"vscode://file/{path}:{line}:{col}"
+--asm <ASM>..>
Print the generated ASM (assembler).
+Values that can be combined:
+[possible values: virtual, allocated, abstract, final, all]
+--bytecode
Print the bytecode.
+This is the final output of the compiler.
+--ir <IR>..>
Print the generated Sway IR (Intermediate Representation).
+Values that can be combined:
+[possible values: initial, final, all, modified, inline, simplify-cfg, sroa, dce, fn-dce, fn-dedup-release, fn-dedup-debug, mem2reg, memcpyopt, const-folding, arg-demotion, const-demotion, ret-demotion, misc-demotion]
+--time-phases
Output the time elapsed over each part of the compilation process
+-v, --verbose...
Use verbose output
+--profile
Profile the compilation process
+-s, --silent
Silence all output
+-L, --log-level <LOG_LEVEL>
Set the log level
+--reverse-order
Output build errors and warnings in reverse order
+--metrics-outfile <METRICS_OUTFILE>
Output compilation metrics into the specified file
+-o, --output-bin <BIN_FILE>
Create a binary file at the provided path representing the final bytecode
+-g, --output-debug <DEBUG_FILE>
Create a file at the provided path containing debug information.
+If the file extension is .json, JSON format is used. Otherwise, an .elf file containing DWARF format is emitted.
+--build-profile <BUILD_PROFILE>
The name of the build profile to use
+[default: debug]
+--release
Use the release build profile.
+The release profile can be customized in the manifest file.
+--error-on-warnings
Treat warnings as errors
+--salt <SALT>
Added salt used to derive the contract ID.
+By default, this is 0x0000000000000000000000000000000000000000000000000000000000000000.
--experimental <EXPERIMENTAL>
Comma separated list of all experimental features that will be enabled
+[possible values: new_encoding, storage_domains, references, error_type, partial_eq]
+--no-experimental <NO_EXPERIMENTAL>
Comma separated list of all experimental features that will be disabled
+[possible values: new_encoding, storage_domains, references, error_type, partial_eq]
+-h, --help
Print help (see a summary with '-h')
+-V, --version
Print version
+EXAMPLES:
+forc contract-id
+forc contract-id --path
Usage: forc init [OPTIONS]
+Options:
+--path <PATH>
The directory in which the forc project will be initialized
+--contract
The default program type, excluding all flags or adding this flag creates a basic contract program
+--script
Create a package with a script target (src/main.sw)
+--predicate
Create a package with a predicate target (src/predicate.rs)
+--library
Create a package with a library target (src/lib.sw)
+--workspace
Adding this flag creates an empty workspace
+--name <NAME>
Set the package name. Defaults to the directory name
+-v, --verbose...
Use verbose output
+-s, --silent
Silence all output
+-L, --log-level <LOG_LEVEL>
Set the log level
+-h, --help
Print help
+-V, --version
Print version
+EXAMPLES:
+forc init --path
forc init --path
forc init --path
forc init --path
$ mkdir my-fuel-project
+$ cd my-fuel-project
+$ forc init
+$ tree
+.
+├── Forc.toml
+└── src
+ └── main.sw
+Forc.toml is the Forc manifest file, containing information about the project and dependencies.
A src/ directory is created, with a single main.sw Sway file in it.
Usage: forc new [OPTIONS]
Arguments:
+<PATH>
+The path at which the project directory will be created
+Options:
+--contract
The default program type. Excluding all flags or adding this flag creates a basic contract program
+--script
Adding this flag creates an empty script program
+--predicate
Adding this flag creates an empty predicate program
+--library
Adding this flag creates an empty library program
+--workspace
Adding this flag creates an empty workspace
+--name <NAME>
Set the package name. Defaults to the directory name
+-v, --verbose...
Use verbose output
+-s, --silent
Silence all output
+-L, --log-level <LOG_LEVEL>
Set the log level
+-h, --help
Print help
+-V, --version
Print version
+EXAMPLES:
+forc new --contract --name my_project
forc new --workspace --name my_workspace
forc new
forc new
$ forc new my-fuel-project
+$ cd my-fuel-project
+$ tree
+.
+├── Forc.toml
+└── src
+ └── main.sw
+Forc.toml is the Forc manifest file, containing information about the project and dependencies.
A src/ directory is created, with a single main.sw Sway file in it.
Usage: forc parse-bytecode [OPTIONS] <FILE_PATH>
+Arguments:
+<FILE_PATH>
+Options:
+-v, --verbose...
Use verbose output
+-s, --silent
Silence all output
+-L, --log-level <LOG_LEVEL>
Set the log level
+-h, --help
Print help
+-V, --version
Print version
+EXAMPLES:
+forc parse-bytecode
We can try this command with the initial project created using forc init, with the counter template:
forc new --template counter counter
+cd counter
+forc build -o obj
+counter$ forc parse-bytecode obj
+
+ half-word byte op raw notes
+ 0 0 JI(4) 90 00 00 04 conditionally jumps to byte 16
+ 1 4 NOOP 47 00 00 00
+ 2 8 Undefined 00 00 00 00 data section offset lo (0)
+ 3 12 Undefined 00 00 00 c8 data section offset hi (200)
+ 4 16 LW(63, 12, 1) 5d fc c0 01
+ 5 20 ADD(63, 63, 12) 10 ff f3 00
+ ...
+ ...
+ ...
+ 60 240 Undefined 00 00 00 00
+ 61 244 Undefined fa f9 0d d3
+ 62 248 Undefined 00 00 00 00
+ 63 252 Undefined 00 00 00 c8
+Prints information about each discovered plugin.
+Usage: forc plugins [OPTIONS]
+Options:
+-p, --paths
Prints the absolute path to each discovered plugin
+-d, --describe
Prints the long description associated with each listed plugin
+-v, --verbose...
Use verbose output
+-s, --silent
Silence all output
+-L, --log-level <LOG_LEVEL>
Set the log level
+-h, --help
Print help (see a summary with '-h')
+-V, --version
Print version
+EXAMPLES:
+forc plugins
+forc plugins --paths
+forc plugins --describe
+forc plugins --paths --describe
+Usage: forc predicate-root [OPTIONS]
+Options:
+-p, --path <PATH>
Path to the project.
+If not specified, current working directory will be used.
+--offline
Offline mode.
+Prevents Forc from using the network when managing dependencies. Meaning it will only try to use previously downloaded dependencies.
+-t, --terse
Terse mode.
+Limited warning and error output.
+--output-directory <OUTPUT_DIRECTORY>
The directory in which Forc output artifacts are placed.
+By default, this is <project-root>/out.
--locked
Requires that the Forc.lock file is up-to-date.
+If the lock file is missing, or it needs to be updated, Forc will exit with an error.
+--ipfs-node <IPFS_NODE>
The IPFS node to use for fetching IPFS sources.
+[possible values: PUBLIC, LOCAL, <GATEWAY_URL>]
+--json-abi
Minify JSON ABI files.
+By default the JSON for ABIs is formatted for human readability. By using this option JSON output will be "minified", i.e. all on one line without whitespace.
+--json-storage-slots
Minify JSON storage slot files.
+By default the JSON for initial storage slots is formatted for human readability. By using this option JSON output will be "minified", i.e. all on one line without whitespace.
+--ast
Print the generated Sway AST (Abstract Syntax Tree)
+--dca-graph <DCA_GRAPH>
Print the computed Sway DCA (Dead Code Analysis) graph.
+DCA graph is printed to the specified path. If specified '' graph is printed to the stdout.
+--dca-graph-url-format <DCA_GRAPH_URL_FORMAT>
URL format to be used in the generated DCA graph .dot file.
+Variables {path}, {line}, and {col} can be used in the provided format. +An example for vscode would be: +"vscode://file/{path}:{line}:{col}"
+--asm <ASM>..>
Print the generated ASM (assembler).
+Values that can be combined:
+[possible values: virtual, allocated, abstract, final, all]
+--bytecode
Print the bytecode.
+This is the final output of the compiler.
+--ir <IR>..>
Print the generated Sway IR (Intermediate Representation).
+Values that can be combined:
+[possible values: initial, final, all, modified, inline, simplify-cfg, sroa, dce, fn-dce, fn-dedup-release, fn-dedup-debug, mem2reg, memcpyopt, const-folding, arg-demotion, const-demotion, ret-demotion, misc-demotion]
+--time-phases
Output the time elapsed over each part of the compilation process
+-v, --verbose...
Use verbose output
+--profile
Profile the compilation process
+-s, --silent
Silence all output
+-L, --log-level <LOG_LEVEL>
Set the log level
+--reverse-order
Output build errors and warnings in reverse order
+--metrics-outfile <METRICS_OUTFILE>
Output compilation metrics into the specified file
+-o, --output-bin <BIN_FILE>
Create a binary file at the provided path representing the final bytecode
+-g, --output-debug <DEBUG_FILE>
Create a file at the provided path containing debug information.
+If the file extension is .json, JSON format is used. Otherwise, an .elf file containing DWARF format is emitted.
+--build-profile <BUILD_PROFILE>
The name of the build profile to use
+[default: debug]
+--release
Use the release build profile.
+The release profile can be customized in the manifest file.
+--error-on-warnings
Treat warnings as errors
+--experimental <EXPERIMENTAL>
Comma separated list of all experimental features that will be enabled
+[possible values: new_encoding, storage_domains, references, error_type, partial_eq]
+--no-experimental <NO_EXPERIMENTAL>
Comma separated list of all experimental features that will be disabled
+[possible values: new_encoding, storage_domains, references, error_type, partial_eq]
+-h, --help
Print help (see a summary with '-h')
+-V, --version
Print version
+EXAMPLES:
+forc predicate-root
+NOTE: Previously this command was used to support Rust integration testing, however the provided behaviour served no benefit over running cargo test directly. The proposal to change the behaviour to support unit testing can be found at the following link: https://github.com/FuelLabs/sway/issues/1833
Sway unit tests are functions decorated with the #[test] attribute. Each test is compiled as a unique entry point for a single program and has access to the namespace of the module in which it is declared.
Unit tests decorated with the #[test(script)] attribute that are declared within contract projects may also call directly into their associated contract's ABI.
Upon successful compilation, test scripts are executed to their completion. A test is considered a failure in the case that a revert (rvrt) instruction is encountered during execution. Otherwise, it is considered a success.
Usage: forc test [OPTIONS] [FILTER]
+Arguments: +[FILTER] +When specified, only tests containing the given string will be executed
+Options:
+-p, --path <PATH>
Path to the project.
+If not specified, current working directory will be used.
+--offline
Offline mode.
+Prevents Forc from using the network when managing dependencies. Meaning it will only try to use previously downloaded dependencies.
+-t, --terse
Terse mode.
+Limited warning and error output.
+--output-directory <OUTPUT_DIRECTORY>
The directory in which Forc output artifacts are placed.
+By default, this is <project-root>/out.
--locked
Requires that the Forc.lock file is up-to-date.
+If the lock file is missing, or it needs to be updated, Forc will exit with an error.
+--ipfs-node <IPFS_NODE>
The IPFS node to use for fetching IPFS sources.
+[possible values: PUBLIC, LOCAL, <GATEWAY_URL>]
+--ast
Print the generated Sway AST (Abstract Syntax Tree)
+--dca-graph <DCA_GRAPH>
Print the computed Sway DCA (Dead Code Analysis) graph.
+DCA graph is printed to the specified path. If specified '' graph is printed to the stdout.
+--dca-graph-url-format <DCA_GRAPH_URL_FORMAT>
URL format to be used in the generated DCA graph .dot file.
+Variables {path}, {line}, and {col} can be used in the provided format. +An example for vscode would be: +"vscode://file/{path}:{line}:{col}"
+--asm <ASM>..>
Print the generated ASM (assembler).
+Values that can be combined:
+[possible values: virtual, allocated, abstract, final, all]
+--bytecode
Print the bytecode.
+This is the final output of the compiler.
+--ir <IR>..>
Print the generated Sway IR (Intermediate Representation).
+Values that can be combined:
+[possible values: initial, final, all, modified, inline, simplify-cfg, sroa, dce, fn-dce, fn-dedup-release, fn-dedup-debug, mem2reg, memcpyopt, const-folding, arg-demotion, const-demotion, ret-demotion, misc-demotion]
+--time-phases
Output the time elapsed over each part of the compilation process
+--profile
Profile the compilation process
+--reverse-order
Output build errors and warnings in reverse order
+-v, --verbose...
Use verbose output
+--metrics-outfile <METRICS_OUTFILE>
Output compilation metrics into the specified file
+-s, --silent
Silence all output
+--json-abi
Minify JSON ABI files.
+By default the JSON for ABIs is formatted for human readability. By using this option JSON output will be "minified", i.e. all on one line without whitespace.
+-L, --log-level <LOG_LEVEL>
Set the log level
+--json-storage-slots
Minify JSON storage slot files.
+By default the JSON for initial storage slots is formatted for human readability. By using this option JSON output will be "minified", i.e. all on one line without whitespace.
+-o, --output-bin <BIN_FILE>
Create a binary file at the provided path representing the final bytecode
+-g, --output-debug <DEBUG_FILE>
Create a file at the provided path containing debug information.
+If the file extension is .json, JSON format is used. Otherwise, an .elf file containing DWARF format is emitted.
+--build-profile <BUILD_PROFILE>
The name of the build profile to use
+[default: debug]
+--release
Use the release build profile.
+The release profile can be customized in the manifest file.
+--error-on-warnings
Treat warnings as errors
+--build-target <BUILD_TARGET>
Build target to use for code generation
+[default: fuel] +[possible values: fuel, evm]
+--pretty
Pretty-print the logs emitted from tests
+-l, --logs
Print Log and LogData receipts for tests
--raw-logs
Print the raw logs for tests
+--filter-exact
When specified, only the test exactly matching the given string will be executed
+--test-threads <TEST_THREADS>
Number of threads to utilize when running the tests. By default, this is the number of threads available in your system
+--experimental <EXPERIMENTAL>
Comma separated list of all experimental features that will be enabled
+[possible values: new_encoding, storage_domains, references, error_type, partial_eq]
+--no-experimental <NO_EXPERIMENTAL>
Comma separated list of all experimental features that will be disabled
+[possible values: new_encoding, storage_domains, references, error_type, partial_eq]
+-h, --help
Print help (see a summary with '-h')
+-V, --version
Print version
+EXAMPLES:
+forc test
+forc test $filter
+forc test --silent
+forc test --locked
+Usage: forc update [OPTIONS]
+Options:
+-p, --path <PATH>
Path to the project, if not specified, current working directory will be used
+-d <TARGET_DEPENDENCY>
Dependency to be updated. If not set, all dependencies will be updated
+-c, --check
Checks if the dependencies have newer versions. Won't actually perform the update, will output which ones are up-to-date and outdated
+--ipfs-node <IPFS_NODE>
The IPFS Node to use for fetching IPFS sources.
+Possible values: PUBLIC, LOCAL, <GATEWAY_URL>
+-v, --verbose...
Use verbose output
+-s, --silent
Silence all output
+-L, --log-level <LOG_LEVEL>
Set the log level
+-h, --help
Print help (see a summary with '-h')
+-V, --version
Print version
+EXAMPLES:
+forc update
+forc update -d std
+forc update --check
+Usage: forc template [OPTIONS] <PROJECT_NAME>
+Arguments:
+<PROJECT_NAME>
+The name of the project that will be created
+Options:
+-u, --url <URL>
The template url, should be a git repo [default: https://github.com/fuellabs/sway]
+-t, --template-name <TEMPLATE_NAME>
The name of the template that needs to be fetched and used from git repo provided
+-v, --verbose...
Use verbose output
+-s, --silent
Silence all output
+-L, --log-level <LOG_LEVEL>
Set the log level
+-h, --help
Print help
+-V, --version
Print version
+EXAMPLES:
+forc template new-path --template-name option
+forc template --url https://github.com/owner/template/ --project_name my_example_project
+The command above fetches the HEAD of the template repo and searches for Forc.toml at the root of the fetched repo. It will fetch the repo and prepare a new Forc.toml with the new project name. Outputs everything to current_dir/project_name.
forc template --url https://github.com/FuelLabs/sway --template_name counter --project_name my_example_project
+The command above fetches the HEAD of the sway repo and searches for counter example inside it (there is an example called counter under sway/examples). It will fetch the counter example and prepare a new Forc.toml with the new project name. Outputs everything to current_dir/project_name.
Plugins can be used to extend forc with new commands that go beyond the native commands mentioned in the previous chapter. While the Fuel ecosystem provides a few commonly useful plugins (forc-fmt, forc-client, forc-lsp, forc-explore), anyone can write their own!
Let's install a plugin, forc-explore, and see what's underneath the plugin:
cargo install forc-explore
+Check that we have installed forc-explore:
$ forc plugins
+Installed Plugins:
+forc-explore
+forc-explore runs the Fuel Network Explorer, which you can run and check out for yourself:
$ forc explore
+Fuel Network Explorer 0.1.1
+Running server on http://127.0.0.1:3030
+Server::run{addr=127.0.0.1:3030}: listening on http://127.0.0.1:3030
+You can visit http://127.0.0.1:3030 to check out the network explorer!
+Note that some plugin crates can also provide more than one command. For example, installing the forc-client plugin provides the forc deploy and forc run commands. This is achieved by specifying multiple [[bin]] targets within the forc-client manifest.
We encourage anyone to write and publish their own forc plugin to enhance their development experience.
Your plugin must be named in the format forc-<MY_PLUGIN> and you may use the above template as a starting point. You can use clap and add more subcommands, options and configurations to suit your plugin's needs.
The forc plugin for interacting with a Fuel node.
+Since transactions are going to require some gas, you need to sign them with an account that has enough coins to pay for them.
+We offer multiple ways to sign the transaction:
+forc-client which integrates with our CLI wallet, forc-wallet.forc-wallet to manually sign transactions, and copy the signed transaction back to forc-client.The easiest and recommended way to interact with deployed networks such as our testnets is option 1, using forc-client to sign your transactions which reads your default forc-wallet vault. For interacting with local node, we recommend using the second option, which leads forc-client to sign transactions with the private key that comes pre-funded in local environments.
If you've used forc-wallet before, you'll already have a secure, password-protected vault holding your private key written to your file-system. forc-client is compatible with forc-wallet such that it can read that vault by asking you your password and use your account to sign transactions.
Example:
+> forc deploy
+
+ Building /Users/yourname/test-projects/test-contract
+ Finished release [optimized + fuel] target(s) in 11.39s
+ Confirming transactions [deploy impl-contract]
+ Network: https://testnet.fuel.network
+ Wallet: /Users/yourname/.fuel/wallets/.wallet
+✔ Wallet password · ********
+? Wallet account ›
+❯ [0] fuel12pls73y9hnqdqthvduy2x44x48zt8s50pkerf32kq26f2afeqdwq6rj9ar - 0.002197245 ETH
+ [1] fuel1vzrm6kw9s3tv85gl25lpptsxrdguyzfhq6c8rk07tr6ft5g45nwqqh0uty - 0.001963631 ETH
+? Do you agree to sign 1 transaction? (y/n) › yes
+ Finished deploying impl-contract https://app.fuel.network/contract/0x94b712901f04332682d14c998a5fc5a078ed15321438f46d58d0383200cde43d
+ Deployed in block https://app.fuel.network/block/5958351
+As it can be seen from the example, forc-client asks for your password to decrypt the forc-wallet vault, and list your accounts so that you can select the one you want to fund the transaction with.
If you are not interacting with a deployed network, such as testnets, your local fuel-core environment can be structured such that it funds an account by default. Using --default-signer flag with forc-client binaries (run, deploy) will instruct forc-client to sign transactions with this pre-funded account. This makes it a useful command while working against a local node.
Example:
+> forc deploy --default-signer
+
+ Building /Users/test/test-projects/test-contract
+ Finished release [optimized + fuel] target(s) in 11.40s
+ Confirming transactions [deploy impl-contract]
+ Network: http://127.0.0.1:4000
+ Finished deploying impl-contract 0xf9fb08ef18ce226954270d6d4f67677d484b8782a5892b3d436572b405407544
+ Deployed in block 00000001
+This option is for creating the transaction first, signing it manually, and supplying the signed transaction back to forc-client. Since it requires multiple steps, it is more error-prone and not recommended for general use cases. Also this will be deprecated soon.
+forc deploy or forc run. To do so simply run forc deploy --manual-sign or forc run --manual-sign with your desired parameters. For a list of parameters please refer to the forc-deploy or forc-run section of the book. Once you run either command you will be asked the address of the wallet you are going to be signing with. After the address is given the transaction will be generated and you will be given a transaction ID. At this point CLI will actively wait for you to insert the signature.forc wallet sign --account <account_index> tx-id <transaction_id>. This will generate a signature.forc-deploy (or forc-run). Once the signature is provided, the signed transaction will be submitted.forc-walletaccounts command.forc wallet accounts
+account command.forc wallet account <account_index>
+++If you want to sign the transaction generated by
+forc-deployorforc-runwith an account funded by default once you start your local node, you can pass--default-signerto them. Please note that this will only work against your local node.+forc-deploy --default-signer ++forc-run --default-signer +
By default --default-signer flag would sign your transactions with the following private-key:
0xde97d8624a438121b86a1956544bd72ed68cd69f2c99555b08b1e8c51ffd511c
+By default, local is used for the target network. To interact with the latest testnet, use the --testnet flag. When this flag is passed, transactions created by forc-deploy will be sent to the latest testnet:
forc-deploy --testnet
+The same can be done to target mainnet:
+forc-deploy --mainnet
+It is also possible to pass the exact node URL while using forc-deploy or forc-run which can be done using --node-url flag:
forc-deploy --node-url https://mainnet.fuel.network
+Another alternative is the --target option, which provides useful aliases to all targets. For example if you want to deploy to testnet you can use:
forc-deploy --target testnet
+Since deploying and running projects on the testnet cost gas, you will need coins to pay for them. You can get some using the testnet faucet.
+For delayed transactions, you can use the --submit-only flag. This flag allows you to submit the transaction without waiting for its finalization.
One use case for this is multisig transactions, where a deployment transaction may stay in a pending state while waiting for all signatures.
+forc-deploy --submit-only
+forc-deploy saves the details of each deployment in the out/deployments folder within the project's root directory. Below is an example of a deployment artifact:
{
+ "transaction_id": "0xec27bb7a4c8a3b8af98070666cf4e6ea22ca4b9950a0862334a1830520012f5d",
+ "salt": "0x9e35d1d5ef5724f29e649a3465033f5397d3ebb973c40a1d76bb35c253f0dec7",
+ "network_endpoint": "http://127.0.0.1:4000",
+ "chain_id": 0,
+ "contract_id": "0x767eeaa7af2621e637f9785552620e175d4422b17d4cf0d76335c38808608a7b",
+ "deployment_size": 68,
+ "deployed_block_id": "0x915c6f372252be6bc54bd70df6362dae9bf750ba652bf5582d9b31c7023ca6cf"
+}
+forc-deploy supports deploying proxy contracts automatically if it is enabled in the Forc.toml of the contract.
[project]
+name = "test_contract"
+authors = ["Fuel Labs <contact@fuel.sh>"]
+entry = "main.sw"
+license = "Apache-2.0"
+implicit-std = false
+
+[proxy]
+enabled = true
+If there is no address field present under the proxy table, like the example above, forc will automatically create a proxy contract based on the SRC-14 implementation from sway-standards. After generating and deploying the proxy contract, the target is set to the current contract, and the owner of the proxy is set to the account that is signing the transaction for deployment.
This means that if you simply enable proxy in the Forc.toml, forc will automatically deploy a proxy contract for you and you do not need to do anything manually aside from signing the deployment transactions for the proxy contract. After deploying the proxy contract, the address is added into the address field of the proxy table.
If you want to update the target of an SRC-14 compliant proxy contract rather than deploying a new one, simply add its address in the address field, like the following example:
[project]
+name = "test_contract"
+authors = ["Fuel Labs <contact@fuel.sh>"]
+entry = "main.sw"
+license = "Apache-2.0"
+implicit-std = false
+
+[proxy]
+enabled = true
+address = "0xd8c4b07a0d1be57b228f4c18ba7bca0c8655eb6e9d695f14080f2cf4fc7cd946" # example proxy contract address
+If an address is present, forc calls into that contract to update its target instead of deploying a new contract. Since a new proxy deployment adds its own address into the Forc.toml automatically, you can simply enable the proxy once and after the initial deployment, forc will keep updating the target accordingly for each new deployment of the same contract.
For contracts over the maximum contract size limit (currently 100kB) defined by the network, forc-deploy will split the contract into chunks and deploy the contract with multiple transactions using the Rust SDK's loader contract functionality. Chunks that have already been deployed will be reused on subsequent deployments.
forc deploy now supports deploying scripts and predicates in addition to contracts. These are deployed as blobs with generated loaders for efficiency.
Scripts and predicates are deployed automatically when you run forc deploy on a project that contains them. The deployment process differs slightly from contract deployment:
After deployment, you'll find new files in your project's output directory:
+<script_name>-loader.bin<predicate_name>-loader.bin and <predicate_name>-loader-rootThe loader files contain the bytecode necessary to load and execute your script or predicate from the deployed blob.
+This new deployment method allows for more efficient storage and execution of scripts and predicates on the Fuel network.
+Note: Contracts are still deployed directly, not as blobs given that the contract size is under the maximum contract size limit defined by network (currently 100kB).
Usage: forc deploy [OPTIONS] [SIGNING_KEY]
+Arguments: +[SIGNING_KEY] +Set the key to be used for signing
+Options:
+-p, --path <PATH>
Path to the project.
+If not specified, current working directory will be used.
+--offline
Offline mode.
+Prevents Forc from using the network when managing dependencies. Meaning it will only try to use previously downloaded dependencies.
+-t, --terse
Terse mode.
+Limited warning and error output.
+--output-directory <OUTPUT_DIRECTORY>
The directory in which Forc output artifacts are placed.
+By default, this is <project-root>/out.
--locked
Requires that the Forc.lock file is up-to-date.
+If the lock file is missing, or it needs to be updated, Forc will exit with an error.
+--ipfs-node <IPFS_NODE>
The IPFS node to use for fetching IPFS sources.
+[possible values: PUBLIC, LOCAL, <GATEWAY_URL>]
+--json-abi
Minify JSON ABI files.
+By default the JSON for ABIs is formatted for human readability. By using this option JSON output will be "minified", i.e. all on one line without whitespace.
+--json-storage-slots
Minify JSON storage slot files.
+By default the JSON for initial storage slots is formatted for human readability. By using this option JSON output will be "minified", i.e. all on one line without whitespace.
+--ast
Print the generated Sway AST (Abstract Syntax Tree)
+--dca-graph <DCA_GRAPH>
Print the computed Sway DCA (Dead Code Analysis) graph.
+DCA graph is printed to the specified path. If specified '' graph is printed to the stdout.
+--dca-graph-url-format <DCA_GRAPH_URL_FORMAT>
URL format to be used in the generated DCA graph .dot file.
+Variables {path}, {line}, and {col} can be used in the provided format. +An example for vscode would be: +"vscode://file/{path}:{line}:{col}"
+--asm <ASM>..>
Print the generated ASM (assembler).
+Values that can be combined:
+[possible values: virtual, allocated, abstract, final, all]
+--bytecode
Print the bytecode.
+This is the final output of the compiler.
+--ir <IR>..>
Print the generated Sway IR (Intermediate Representation).
+Values that can be combined:
+[possible values: initial, final, all, modified, inline, simplify-cfg, sroa, dce, fn-dce, fn-dedup-release, fn-dedup-debug, mem2reg, memcpyopt, const-folding, arg-demotion, const-demotion, ret-demotion, misc-demotion]
+--time-phases
Output the time elapsed over each part of the compilation process
+--profile
Profile the compilation process
+--reverse-order
Output build errors and warnings in reverse order
+--metrics-outfile <METRICS_OUTFILE>
Output compilation metrics into the specified file
+--gas-price <PRICE>
Gas price for the transaction
+--script-gas-limit <SCRIPT_GAS_LIMIT>
Gas limit for the transaction
+--max-fee <MAX_FEE>
Max fee for the transaction
+--tip <TIP>
The tip for the transaction
+--maturity <MATURITY>
Block height until which tx cannot be included
+[default: 0]
+--node-url <NODE_URL>
The URL of the Fuel node to which we're submitting the transaction. If unspecified, checks the manifest's network table, then falls back to http://127.0.0.1:4000
You can also use --target, --devnet, --testnet, or --mainnet to specify the Fuel node.
[env: FUEL_NODE_URL=]
+--target <TARGET>
Preset configurations for using a specific target.
+You can also use --node-url, --devnet, --testnet, or --mainnet to specify the Fuel node.
Possible values are: [local, testnet, mainnet]
+--mainnet
Use preset configuration for mainnet.
+You can also use --node-url, --target, or --testnet to specify the Fuel node.
--testnet
Use preset configuration for testnet.
+You can also use --node-url, --target, or --mainnet to specify the Fuel node.
--devnet
Use preset configuration for devnet.
+You can also use --node-url, --target, or --testnet to specify the Fuel node.
--salt <SALT>
Optional 256-bit hexadecimal literal(s) to redeploy contracts.
+For a single contract, use --salt <SALT>, eg.: forc deploy --salt 0x0000000000000000000000000000000000000000000000000000000000000001
For a workspace with multiple contracts, use --salt <CONTRACT_NAME>:<SALT> to specify a salt for each contract, eg.:
forc deploy --salt contract_a:0x0000000000000000000000000000000000000000000000000000000000000001 --salt contract_b:0x0000000000000000000000000000000000000000000000000000000000000002
+--default-salt
Generate a default salt (0x0000000000000000000000000000000000000000000000000000000000000000) for the contract. Useful for CI, to create reproducible deployments
+-o, --output-bin <BIN_FILE>
Create a binary file at the provided path representing the final bytecode
+-g, --output-debug <DEBUG_FILE>
Create a file at the provided path containing debug information.
+If the file extension is .json, JSON format is used. Otherwise, an .elf file containing DWARF format is emitted.
+--build-profile <BUILD_PROFILE>
The name of the build profile to use
+[default: release]
+--default-signer
Sign the transaction with default signer that is pre-funded by fuel-core. Useful for testing against local node
+--unsigned
Deprecated in favor of --default-signer
--submit-only
Submit the deployment transaction(s) without waiting for execution to complete
+--manual-signing
Sign the deployment transaction manually
+--override-storage-slots <JSON_FILE_PATH>
Override storage slot initialization.
+By default, storage slots are initialized with the values defined in the storage block in +the contract. You can override the initialization by providing the file path to a JSON file +containing the overridden values.
+The file format and key values should match the compiler-generated *-storage_slots.json file in the output
+directory of the compiled contract.
Example: forc deploy --override-storage-slots my_override.json
my_override.json: +[ +{ +"key": "<key from out/debug/storage_slots.json>", +"value": "0000000000000000000000000000000000000000000000000000000000000001" +} +]
+--experimental <EXPERIMENTAL>
Comma separated list of all experimental features that will be enabled
+[possible values: new_encoding, storage_domains, references, error_type, partial_eq]
+--no-experimental <NO_EXPERIMENTAL>
Comma separated list of all experimental features that will be disabled
+[possible values: new_encoding, storage_domains, references, error_type, partial_eq]
+--aws-kms-signer <AWS_KMS_SIGNER>
AWS KMS signer arn. If present forc-deploy will automatically use AWS KMS signer instead of forc-wallet
+-h, --help
Print help (see a summary with '-h')
+-V, --version
Print version
+EXAMPLES:
+forc deploy bc09bfa7a11a04ce42b0a5abf04fd437387ee49bf4561d575177e2946468b408
+forc deploy bc09bfa7a11a04ce42b0a5abf04fd437387ee49bf4561d575177e2946468b408 --path {path}
+forc deploy --node-url https://testnet.fuel.network/graphql
+You can use forc deploy, which triggers a contract deployment transaction and sends it to a running node.
Alternatively, you can deploy your Sway contract programmatically using fuels-rs, our Rust SDK.
+You can find an example within our fuels-rs book.
+Usage: forc run [OPTIONS] [SIGNING_KEY]
+Arguments: +[SIGNING_KEY] +Set the key to be used for signing
+Options:
+-p, --path <PATH>
Path to the project.
+If not specified, current working directory will be used.
+--offline
Offline mode.
+Prevents Forc from using the network when managing dependencies. Meaning it will only try to use previously downloaded dependencies.
+-t, --terse
Terse mode.
+Limited warning and error output.
+--output-directory <OUTPUT_DIRECTORY>
The directory in which Forc output artifacts are placed.
+By default, this is <project-root>/out.
--locked
Requires that the Forc.lock file is up-to-date.
+If the lock file is missing, or it needs to be updated, Forc will exit with an error.
+--ipfs-node <IPFS_NODE>
The IPFS node to use for fetching IPFS sources.
+[possible values: PUBLIC, LOCAL, <GATEWAY_URL>]
+--json-abi
Minify JSON ABI files.
+By default the JSON for ABIs is formatted for human readability. By using this option JSON output will be "minified", i.e. all on one line without whitespace.
+--json-storage-slots
Minify JSON storage slot files.
+By default the JSON for initial storage slots is formatted for human readability. By using this option JSON output will be "minified", i.e. all on one line without whitespace.
+--ast
Print the generated Sway AST (Abstract Syntax Tree)
+--dca-graph <DCA_GRAPH>
Print the computed Sway DCA (Dead Code Analysis) graph.
+DCA graph is printed to the specified path. If specified '' graph is printed to the stdout.
+--dca-graph-url-format <DCA_GRAPH_URL_FORMAT>
URL format to be used in the generated DCA graph .dot file.
+Variables {path}, {line}, and {col} can be used in the provided format. +An example for vscode would be: +"vscode://file/{path}:{line}:{col}"
+--asm <ASM>..>
Print the generated ASM (assembler).
+Values that can be combined:
+[possible values: virtual, allocated, abstract, final, all]
+--bytecode
Print the bytecode.
+This is the final output of the compiler.
+--ir <IR>..>
Print the generated Sway IR (Intermediate Representation).
+Values that can be combined:
+[possible values: initial, final, all, modified, inline, simplify-cfg, sroa, dce, fn-dce, fn-dedup-release, fn-dedup-debug, mem2reg, memcpyopt, const-folding, arg-demotion, const-demotion, ret-demotion, misc-demotion]
+--time-phases
Output the time elapsed over each part of the compilation process
+--profile
Profile the compilation process
+--reverse-order
Output build errors and warnings in reverse order
+--metrics-outfile <METRICS_OUTFILE>
Output compilation metrics into the specified file
+--gas-price <PRICE>
Gas price for the transaction
+--script-gas-limit <SCRIPT_GAS_LIMIT>
Gas limit for the transaction
+--max-fee <MAX_FEE>
Max fee for the transaction
+--tip <TIP>
The tip for the transaction
+--maturity <MATURITY>
Block height until which tx cannot be included
+[default: 0]
+-o, --output-bin <BIN_FILE>
Create a binary file at the provided path representing the final bytecode
+-g, --output-debug <DEBUG_FILE>
Create a file at the provided path containing debug information.
+If the file extension is .json, JSON format is used. Otherwise, an .elf file containing DWARF format is emitted.
+--build-profile <BUILD_PROFILE>
The name of the build profile to use
+[default: debug]
+--release
Use the release build profile.
+The release profile can be customized in the manifest file.
+--error-on-warnings
Treat warnings as errors
+--node-url <NODE_URL>
The URL of the Fuel node to which we're submitting the transaction. If unspecified, checks the manifest's network table, then falls back to http://127.0.0.1:4000
You can also use --target, --devnet, --testnet, or --mainnet to specify the Fuel node.
[env: FUEL_NODE_URL=]
+--target <TARGET>
Preset configurations for using a specific target.
+You can also use --node-url, --devnet, --testnet, or --mainnet to specify the Fuel node.
Possible values are: [local, testnet, mainnet]
+--mainnet
Use preset configuration for mainnet.
+You can also use --node-url, --target, or --testnet to specify the Fuel node.
--testnet
Use preset configuration for testnet.
+You can also use --node-url, --target, or --mainnet to specify the Fuel node.
--devnet
Use preset configuration for devnet.
+You can also use --node-url, --target, or --testnet to specify the Fuel node.
-d, --data <DATA>
Hex string of data to input to script
+--dry-run
Only craft transaction and print it out
+-r, --pretty-print
Pretty-print the outputs from the node
+--contract <CONTRACT>
32-byte contract ID that will be called during the transaction
+--simulate
Execute the transaction and return the final mutated transaction along with receipts (which includes whether the transaction reverted or not). The transaction is not inserted in the node's view of the blockchain, (i.e. it does not affect the chain state)
+--default-signer
Sign the transaction with default signer that is pre-funded by fuel-core. Useful for testing against local node
+--unsigned
Deprecated in favor of --default-signer
--args <ARGS>
Arguments to pass into main function with forc run
+--experimental <EXPERIMENTAL>
Comma separated list of all experimental features that will be enabled
+[possible values: new_encoding, storage_domains, references, error_type, partial_eq]
+--no-experimental <NO_EXPERIMENTAL>
Comma separated list of all experimental features that will be disabled
+[possible values: new_encoding, storage_domains, references, error_type, partial_eq]
+-h, --help
Print help (see a summary with '-h')
+-V, --version
Print version
+Usage: forc-submit [OPTIONS] <TX_PATH>
+Arguments:
+<TX_PATH> +Path to the Transaction that is to be submitted to the Fuel node.
+Paths to files ending with .json will be deserialized from JSON. Paths to files ending with .bin will be deserialized from bytes using the fuel_tx::Transaction::try_from_bytes constructor.
Options:
+--node-url <NODE_URL>
The URL of the Fuel node to which we're submitting the transaction. If unspecified, checks the manifest's network table, then falls back to http://127.0.0.1:4000
You can also use --target, --devnet, --testnet, or --mainnet to specify the Fuel node.
[env: FUEL_NODE_URL=]
+--target <TARGET>
Preset configurations for using a specific target.
+You can also use --node-url, --devnet, --testnet, or --mainnet to specify the Fuel node.
Possible values are: [local, testnet, mainnet]
+--mainnet
Use preset configuration for mainnet.
+You can also use --node-url, --target, or --testnet to specify the Fuel node.
--testnet
Use preset configuration for testnet.
+You can also use --node-url, --target, or --mainnet to specify the Fuel node.
--devnet
Use preset configuration for devnet.
+You can also use --node-url, --target, or --testnet to specify the Fuel node.
--await <AWAIT>
Whether or not to await confirmation that the transaction has been committed.
+When true, await commitment and output the transaction status. When false, do not await confirmation and simply output the transaction ID.
[default: true] +[possible values: true, false]
+--tx-status-json <JSON>
Output the resulting transaction status as JSON rather than the default output
+[default: false] +[possible values: true, false]
+-h, --help
Print help (see a summary with '-h')
+-V, --version
Print version
+EXAMPLES:
+forc submit {path}/mint.json
+forc submit {path}/mint.json --await true
+forc submit {path}/mint.json --tx-status-json true
+forc submit {path}/mint.json --testnet
+forc submit {path}/mint.json --target local
+Usage: forc call [OPTIONS] --abi
Arguments:
+<CONTRACT_ID> +The contract ID to call
+<FUNCTION> +The function selector to call. The function selector is the name of the function to call (e.g. "transfer"). It must be a valid selector present in the ABI file
+[FUNCTION_ARGS]... +Arguments to pass into the function to be called
+Options:
+--abi <ABI>
Path or URI to a JSON ABI file
+--node-url <NODE_URL>
The URL of the Fuel node to which we're submitting the transaction. If unspecified, checks the manifest's network table, then falls back to http://127.0.0.1:4000
You can also use --target, --devnet, --testnet, or --mainnet to specify the Fuel node.
[env: FUEL_NODE_URL=]
+--target <TARGET>
Preset configurations for using a specific target.
+You can also use --node-url, --devnet, --testnet, or --mainnet to specify the Fuel node.
Possible values are: [local, testnet, mainnet]
+--mainnet
Use preset configuration for mainnet.
+You can also use --node-url, --target, or --testnet to specify the Fuel node.
--testnet
Use preset configuration for testnet.
+You can also use --node-url, --target, or --mainnet to specify the Fuel node.
--devnet
Use preset configuration for devnet.
+You can also use --node-url, --target, or --testnet to specify the Fuel node.
--signing-key <SIGNING_KEY>
Derive an account from a secret key to make the call
+[env: SIGNING_KEY=]
+--wallet
Use forc-wallet to make the call
+--amount <AMOUNT>
Amount of native assets to forward with the call
+[default: 0]
+--asset-id <ASSET_ID>
Asset ID to forward with the call
+--gas-forwarded <GAS_FORWARDED>
Amount of gas to forward with the call
+--mode <MODE>
The execution mode to use for the call; defaults to dry-run; possible values: dry-run, simulate, live
+[default: dry-run]
+--gas-price <PRICE>
Gas price for the transaction
+--script-gas-limit <SCRIPT_GAS_LIMIT>
Gas limit for the transaction
+--max-fee <MAX_FEE>
Max fee for the transaction
+--tip <TIP>
The tip for the transaction
+--external-contracts <EXTERNAL_CONTRACTS>
The external contract addresses to use for the call If none are provided, the call will automatically populate external contracts by making a dry-run calls to the node, and extract the contract addresses based on the revert reason
+--output <OUTPUT>
The output format to use; possible values: default, raw
+[default: default]
+-h, --help
Print help (see a summary with '-h')
+-V, --version
Print version
+EXAMPLES:
+» forc call 0x0dcba78d7b09a1f77353f51367afd8b8ab94b5b2bb6c9437d9ba9eea47dede97
+--abi
./contract-abi.json
+get_balance 0x0087675439e10a8351b1d5e4cf9d0ea6da77675623ff6b16470b5e3c58998423
» forc call 0x0dcba78d7b09a1f77353f51367afd8b8ab94b5b2bb6c9437d9ba9eea47dede97
+--abi
./contract-abi.json
+get_name
» forc call 0x0dcba78d7b09a1f77353f51367afd8b8ab94b5b2bb6c9437d9ba9eea47dede97
+--abi
./contract-abi.json
+transfer 0xf8f8b6283d7fa5b672b530cbb84fcccb4ff8dc40f8176ef4544ddb1f1952ad07
--contracts
0xf8f8b6283d7fa5b672b530cbb84fcccb4ff8dc40f8176ef4544ddb1f1952ad07
+» forc call 0x0dcba78d7b09a1f77353f51367afd8b8ab94b5b2bb6c9437d9ba9eea47dede97
+--abi
./contract-abi.json
+add 1 2
--mode
simulate
+» forc call 0x0dcba78d7b09a1f77353f51367afd8b8ab94b5b2bb6c9437d9ba9eea47dede97
+--node-url
"http://127.0.0.1:4000/v1/graphql"
+--signing-key
0x...
+--abi
./contract-abi.json
+add 1 2
--mode
dry-run
+» forc call 0x0dcba78d7b09a1f77353f51367afd8b8ab94b5b2bb6c9437d9ba9eea47dede97
+--testnet
--wallet
--abi
./contract-abi.json
+add 1 2
--mode
live
+» forc call 0x0dcba78d7b09a1f77353f51367afd8b8ab94b5b2bb6c9437d9ba9eea47dede97
+--abi
./contract-abi.json
+transfer 0xf8f8b6283d7fa5b672b530cbb84fcccb4ff8dc40f8176ef4544ddb1f1952ad07
--mode
live
+--amount
100
+» forc call 0x0dcba78d7b09a1f77353f51367afd8b8ab94b5b2bb6c9437d9ba9eea47dede97
+--abi
./contract-abi.json
+transfer 0xf8f8b6283d7fa5b672b530cbb84fcccb4ff8dc40f8176ef4544ddb1f1952ad07
--amount
100
+--asset-id
0x0087675439e10a8351b1d5e4cf9d0ea6da77675623ff6b16470b5e3c58998423
+--live
Usage: forc-crypto
Commands: +keccak256 Hashes the argument or file with this algorithm +sha256 Hashes the argument or file with this algorithm +address Converts an address to another format +get-public-key Get the public key from a message and its signature +new-key Creates a new key for use with fuel-core +parse-secret Parses a private key to view the associated public key +vanity Generate a vanity address +help Print this message or the help of the given subcommand(s)
+Options:
+-h, --help
Print help
+-V, --version
Print version
+EXAMPLES:
+forc crypto sha256 test
+forc crypto keccak256 test
+forc crypto sha256 {file}
+forc crypto keccak256 {file}
+forc crypto address fuel12e0xwx34nfp7jrzvn9mp5qkac3yvp7h8fx37ghl7klf82vv2wkys6wd523
+forc crypto new-key
+forc crypto new-key -k peering
+forc crypto new-key -k block-production
+forc crypto parse-secret "f5204427d0ab9a311266c96a377f7c329cb8a41b9088225b6fcf40eefb423e28"
+forc crypto parse-secret -k peering "f5204427d0ab9a311266c96a377f7c329cb8a41b9088225b6fcf40eefb423e28"
+forc crypto get-public-key
+0x1eff08081394b72239a0cf7ff6b499213dcb7a338bedbd75d072d504588ef27a1f74d5ceb2f111ec02ede097fb09ed00aa9867922ed39299dae0b1afc0fa8661
+"This is a message that is signed"
forc crypto vanity --starts-with "aaa"
+forc crypto vanity --ends-with "aaa"
+forc crypto vanity --starts-with "00" --ends-with "ff"
+forc crypto vanity --regex "^00.*ff$"
+Usage: forc-debug [OPTIONS] [API_URL]
+Arguments: +[API_URL] The URL of the Fuel Client GraphQL API [default: http://127.0.0.1:4000/graphql]
+Options:
+-s, --serve
Start the DAP server
+-h, --help
Print help
+-V, --version
Print version
+Usage: forc-doc [OPTIONS]
+Options:
+-p, --path <PATH>
Path to the project.
+If not specified, current working directory will be used.
+--document-private-items
Include non-public items in the documentation
+--open
Open the docs in a browser after building them
+--offline
Offline mode, prevents Forc from using the network when managing dependencies. Meaning it +will only try to use previously downloaded dependencies
+--locked
Requires that the Forc.lock file is up-to-date. If the lock file is missing, or it needs +to be updated, Forc will exit with an error
+--no-deps
Do not build documentation for dependencies
+--ipfs-node <IPFS_NODE>
The IPFS Node to use for fetching IPFS sources.
+Possible values: PUBLIC, LOCAL, <GATEWAY_URL>
+--experimental <EXPERIMENTAL>
Comma separated list of all experimental features that will be enabled
+[possible values: new_encoding, storage_domains, references, error_type, partial_eq]
+--no-experimental <NO_EXPERIMENTAL>
Comma separated list of all experimental features that will be disabled
+[possible values: new_encoding, storage_domains, references, error_type, partial_eq]
+-s, --silent
Silent mode. Don't output any warnings or errors to the command line
+-h, --help
Print help (see a summary with '-h')
+-V, --version
Print version
+EXAMPLES:
+forc doc
+forc doc --open
+forc doc --path {path}
+forc doc --document-private-items
+forc doc --offline
+Forc plugin for running the Fuel Block Explorer.
+forc-explore [OPTIONS] [SUBCOMMAND]
+-h, --help
Print help information
+-p, --port <PORT>
The port number at which the explorer will run on localhost [default: 3030]
+-V, --version
Print version information
+clean
Cleans up any existing state associated with the fuel block explorer
+help
Print this message or the help of the given subcommand(s)
+Usage: forc-fmt [OPTIONS]
+Options:
+-c, --check
Run in 'check' mode.
+0 if input is formatted correctly. - Exits with 1 and prints a diff if formatting is required.-p, --path <PATH>
Path to the project.
+If not specified, current working directory will be used.
+-f, --file <FILE>
Formats a single .sw file with the default settings. If not specified, current working directory will be formatted using a Forc.toml configuration
+-h, --help
Print help (see a summary with '-h')
+-V, --version
Print version
+EXAMPLES:
+forc fmt --check
+forc fmt -c
+forc fmt --file {path}/src/main.sw
+forc fmt -f {path}/src/main.sw
+forc fmt --path {path}
+forc fmt -p {path}
+Usage: forc-lsp
+Options:
+-h, --help
Print help
+-V, --version
Print version
+Usage: forc-migrate
Commands: +show Show the upcoming breaking change features and their migration steps +check Check the project for code that needs to be migrated +run Migrate the project +help Print this message or the help of the given subcommand(s)
+Options:
+-h, --help
Print help
+-V, --version
Print version
+Examples:
+forc migrate show
+forc migrate check
+forc migrate check --path {path}
+forc migrate run
+forc migrate run --path {path}
+forc migrate run --offline
+forc-migrate guides you through breaking changes between Sway versions. It fully or semiautomatically adapts your code, making it compatible with the next breaking change version of Sway.
forc-migrate migrates the code to the next breaking change version of Sway. That means, if you want to migrate to, e.g., Sway v0.67.0, you will need to use the latest v0.66.x version of the forc-migrate.
For example, let's say that your Sway project is on version v0.66.1, and that the latest v0.66 version is v0.66.42. You should first update your Fuel toolchain to version v0.66.42 of forc, and compile your project with that version:
fuelup component add forc@0.66.42
+Sway guarantees that all the versions with the same minor version, 0.66 in the above example, are compatible. That means that the latest patch version, 0.66.42 in the example, will correctly compile your project.
+Once you've installed the latest non-breaking version of forc-migrate, use the show command to make yourself familiar with the upcoming breaking changes:
forc migrate show
+A typical output of the show command will look like this:
Breaking change features:
+ - storage_domains (https://github.com/FuelLabs/sway/issues/6701)
+ - references (https://github.com/FuelLabs/sway/issues/5063)
+
+Migration steps (1 manual and 1 semiautomatic):
+storage_domains
+ [M] Review explicitly defined slot keys in storage declarations (`in` keywords)
+
+references
+ [S] Replace `ref mut` function parameters with `&mut`
+
+Experimental feature flags:
+- for Forc.toml: experimental = { storage_domains = true, references = true }
+- for CLI: --experimental storage_domains,references
+The output will contain:
+storage_domains and references in this example,The migration steps can be manual, semiautomatic, or fully automatic. They are marked in the output with [M], [S], and [A], respectively.
The show command will also provide experimental feature flags that will be needed during the migration, as explained in the next chapter.
Let's assume that we want to migrate a Sway project called my_project that depends on std and a third_party_lib.
First, we will go to the folder that contains my_project, e.g.: cd my_project. All of the upcoming CLI commands assume that we are running the forc-migrate tool within the my_project folder.
Before migrating the code, make sure that the project builds without any errors by running:
+forc build
+Next, let's check the project first. The check command will dry-run the migration steps. It will not do any changes in code, but will provide a detailed information of all the places in code that need to be either reviewed or changed during the migration process. The check command will also provide a rough time estimate for the migration.
forc migrate check
+The output of the check command will end in a summary of the migration effort, containing:
Migration effort:
+
+storage_domains
+ [M] Review explicitly defined slot keys in storage declarations (`in` keywords)
+ Occurrences: 3 Migration effort (hh::mm): ~00:06
+
+references
+ [S] Replace `ref mut` function parameters with `&mut`
+ Occurrences: 18 Migration effort (hh::mm): ~01:30
+
+Total migration effort (hh::mm): ~01:36
+Before the summary, instructions will be shown for each migration step. A typical instruction output for a single migration step will contain:
+info: [references] Replace `ref mut` function parameters with `&mut`
+ --> my_project/src/main.sw:30:51
+ |
+...
+30 | fn ref_mut_fn(ref mut x: u64) {}
+ | ---------
+...
+35 | fn another_ref_mut_fn(ref mut arg: S) {}
+ | -----------
+ |
+ = help: Migration will replace `ref mut` function parameters with `&mut`.
+ = help: E.g., `ref mut x: u64` will become `x: &mut u64`.
+ = help:
+ = help: After the migration, you will still need to:
+ = help: - change function callers, by adding `&mut` to passed parameters.
+ = help: - change function bodies, by dereferencing (`*`) parameters where needed.
+ = help:
+ = help: For a detailed migration guide see: https://github.com/FuelLabs/sway/issues/5063
+Before running the migrations on the project itself, first update the project dependencies to the versions that use the next Sway breaking change version.
+In our example, the my_project's Forc.toml file will have the [dependencies] section similar to this one:
[dependencies]
+std = { git = "https://github.com/FuelLabs/sway", tag = "v0.66.1" }
+third_party_lib = { git = "https://github.com/ThirdParty/swaylib", tag = "v1.0.0" }
+Assuming that the third_party_lib version compatible with Sway v0.67.0 is the version v2.0.0 we will end up in the following changes:
[dependencies]
+# Changed v0.66.1 -> v0.67.0
+std = { git = "https://github.com/FuelLabs/sway", tag = "v0.67.0" }
+# Changed v1.0.0 -> v2.0.0
+third_party_lib = { git = "https://github.com/ThirdParty/swaylib", tag = "v2.0.0" }
+Run forc build to make sure that the project still compiles. At this point, it is very likely that you will need to compile the project with the experimental features turned on. The reason is the likelihood that either the new std or the third_party_lib uses the new Sway features.
To compile the project with experimental features, you can take the feature flags from the forc migrate show output, and place them either in the [build-profile] section of the projects Forc.toml file, or pass them to forc build via the command line.
Experimental feature flags:
+- for Forc.toml: experimental = { storage_domains = true, references = true }
+- for CLI: --experimental storage_domains,references
+In the remaining part of this tutorial, we will be passing the feature flags via the command line. E.g.:
+forc build --experimental storage_domains,references
+Once the my_project successfully builds with updated dependencies, we can run the migration steps on it. E.g.:
forc migrate run --experimental storage_domains,references
+The run command will execute the migration steps, and guide you through the migration process. For each migration step, the output of the step can be one of the following:
| Step output | Meaning |
|---|---|
| Checked | The step is executed and does not require any changes in code. No action needed. |
| Review | The step suggests a manual code review. |
| Changing | The step is automatically changing the code. There might be additional manual actions needed. |
At the end of the run, the migration will either guide you to:
Continue the migration process by performing the manual actions and re-running the forc migrate run afterwards,Finished. At this point, your project will be compatible with the next breaking change version of Sway.forc migrate, same like forc fmt, does its best to preserve the positions of comments in the modified code. This is a challenging task, especially if migration steps remove parts of the code. It is a good practice to always diff the changes done within migration steps and check if the comments are placed where expected.
To migrate a workspace, you will need to migrate each workspace member separately, following the above procedure. The projects should be migrated in order of their dependencies.
+++Note: There is a know limitation when running
+forc migrateon projects that are listed as workspace members.forc migratewill run, but possibly not find all the occurrences in code that need to be migrated. Therefore, before running migrations on projects that are workspace members, remove them temporarily from the the list of workspacemembers.
There are some additional manual steps that might be needed after the migration.
+E.g., if tests use hardcoded contract IDs, those need to be changed, because the new version of Sway will, very likely, produce different bytecode.
+ +The Sway compiler supports a list of attributes that perform various operations that are useful for building, testing and documenting Sway programs. Below is a list of all available attributes:
+The #[allow(...)] attribute overrides checks so that violations will go unreported. The following checks can be disabled:
#[allow(dead_code)] disable checks for dead code;#[allow(deprecated)] disables checks for usage of deprecated structs, functions and other items.The #[doc(..)] attribute specifies documentation.
Line doc comments beginning with exactly three slashes ///, are interpreted as a special syntax for doc attributes. That is, they are equivalent to writing #[doc("...")] around the body of the comment, i.e., /// Foo turns into #[doc("Foo")]
Line comments beginning with //! are doc comments that apply to the module of the source file they are in. That is, they are equivalent to writing #![doc("...")] around the body of the comment. //! module level doc comments should be at the top of Sway files.
Documentation can be generated from doc attributes using forc doc.
The inline attribute suggests that a copy of the attributed function should be placed in the caller, rather than generating code to call the function where it is defined.
+++Note: The Sway compiler automatically inlines functions based on internal heuristics. Incorrectly inlining functions can make the program slower, so this attribute should be used with care.
+
The #[inline(never)] attribute suggests that an inline expansion should never be performed.
The #[inline(always)] attribute suggests that an inline expansion should always be performed.
++Note:
+#[inline(..)]in every form is a hint, with no requirements +on the language to place a copy of the attributed function in the caller.
The lack of #[payable] implies the method is non-payable. When calling an ABI method that is non-payable, the compiler emits an error if the amount of coins forwarded with the call is not guaranteed to be zero. Note that this is strictly a compile-time check and does not incur any runtime cost.
In Sway, functions are pure by default but can be opted into impurity via the storage function attribute. The storage attribute may take read and/or write arguments indicating which type of access the function requires.
The #[storage(read)] attribute indicates that a function requires read access to the storage.
The #[storage(write)] attribute indicates that a function requires write access to the storage.
More details in Purity.
+The #[test] attribute marks a function to be executed as a test.
The #[test(should_revert)] attribute marks a function to be executed as a test that should revert.
More details in Unit Testing.
+The #[deprecated] attribute marks an item as deprecated and makes the compiler emit a warning for every usage of the deprecated item. This warning can be disabled using #[allow(deprecated)].
It is possible to improve the warning message with #[deprecated(note = "your message")]
The #[fallback] attribute makes the compiler use the marked function as the contract call fallback function, which means that, when a contract is called, and the contract selection fails, the fallback function will be called instead.
The Sway compiler supports a list of intrinsics that perform various low level operations that are useful for building libraries. Compiler intrinsics should rarely be used but are preferred over asm blocks because they are type-checked and are safer overall. Below is a list of all available compiler intrinsics:
__size_of_val<T>(val: T) -> u64
+Description: Return the size of type T in bytes.
Constraints: None.
+__size_of<T>() -> u64
+Description: Return the size of type T in bytes.
Constraints: None.
+__size_of_str_array<T>() -> u64
+Description: Return the size of type T in bytes. This intrinsic differs from __size_of in the case of "string arrays" where the actual length in bytes of the string is returned without padding the byte size to the next word alignment. When T is not a "string array" 0 is returned.
Constraints: None.
+__assert_is_str_array<T>()
+Description: Throws a compile error if type T is not a "string array".
Constraints: None.
+__to_str_array(s: str) -> str[N]
+Description: Converts a "string slice" to "string array" at compile time. Parameter "s" must be a string literal.
+Constraints: None.
+__is_reference_type<T>() -> bool
+Description: Returns true if T is a reference type and false otherwise.
Constraints: None.
+__is_str_array<T>() -> bool
+Description: Returns true if T is a string array and false otherwise.
Constraints: None.
+__eq<T>(lhs: T, rhs: T) -> bool
+Description: Returns whether lhs and rhs are equal.
Constraints: T is bool, u8, u16, u32, u64, u256, b256 or raw_ptr.
__gt<T>(lhs: T, rhs: T) -> bool
+Description: Returns whether lhs is greater than rhs.
Constraints: T is u8, u16, u32, u64, u256, b256.
__lt<T>(lhs: T, rhs: T) -> bool
+Description: Returns whether lhs is less than rhs.
Constraints: T is u8, u16, u32, u64, u256, b256.
__gtf<T>(index: u64, tx_field_id: u64) -> T
+Description: Returns transaction field with ID tx_field_id at index index, if applicable. This is a wrapper around FuelVM's gtf instruction. The resulting field is cast to T.
Constraints: None.
+__addr_of<T>(val: T) -> raw_ptr
+Description: Returns the address in memory where val is stored.
Constraints: T is a reference type.
__state_load_word(key: b256) -> u64
+Description: Reads and returns a single word from storage at key key.
Constraints: None.
+__state_load_quad(key: b256, ptr: raw_ptr, slots: u64) -> bool
+Description: Reads slots number of slots (b256 each) from storage starting at key key and stores them in memory starting at address ptr. Returns a Boolean describing whether all the storage slots were previously set.
Constraints: None.
+__state_store_word(key: b256, val: u64) -> bool
+Description: Stores a single word val into storage at key key. Returns a Boolean describing whether the store slot was previously set.
Constraints: None.
+__state_store_quad(key: b256, ptr: raw_ptr, slots: u64) -> bool
+Description: Stores slots number of slots (b256 each) starting at address ptr in memory into storage starting at key key. Returns a Boolean describing whether the first storage slot was previously set.
Constraints: None.
+__log<T>(val: T)
+Description: Logs value val.
Constraints: None.
+__add<T>(lhs: T, rhs: T) -> T
+Description: Adds lhs and rhs and returns the result.
Constraints: T is an integer type, i.e. u8, u16, u32, u64, u256.
__sub<T>(lhs: T, rhs: T) -> T
+Description: Subtracts rhs from lhs.
Constraints: T is an integer type, i.e. u8, u16, u32, u64, u256.
__mul<T>(lhs: T, rhs: T) -> T
+Description: Multiplies lhs by rhs.
Constraints: T is an integer type, i.e. u8, u16, u32, u64, u256.
__div<T>(lhs: T, rhs: T) -> T
+Description: Divides lhs by rhs.
Constraints: T is an integer type, i.e. u8, u16, u32, u64, u256.
__and<T>(lhs: T, rhs: T) -> T
+Description: Bitwise AND lhs and rhs.
Constraints: T is an integer type, i.e. u8, u16, u32, u64, u256, b256.
__or<T>(lhs: T, rhs: T) -> T
+Description: Bitwise OR lhs and rhs.
Constraints: T is an integer type, i.e. u8, u16, u32, u64, u256, b256.
__xor<T>(lhs: T, rhs: T) -> T
+Description: Bitwise XOR lhs and rhs.
Constraints: T is an integer type, i.e. u8, u16, u32, u64, u256, b256.
__mod<T>(lhs: T, rhs: T) -> T
+Description: Modulo of lhs by rhs.
Constraints: T is an integer type, i.e. u8, u16, u32, u64, u256.
__rsh<T>(lhs: T, rhs: u64) -> T
+Description: Logical right shift of lhs by rhs.
Constraints: T is an integer type, i.e. u8, u16, u32, u64, u256, b256.
__lsh<T>(lhs: T, rhs: u64) -> T
+Description: Logical left shift of lhs by rhs.
Constraints: T is an integer type, i.e. u8, u16, u32, u64, u256, b256.
__revert(code: u64)
+Description: Reverts with error code code.
Constraints: None.
+__ptr_add(ptr: raw_ptr, offset: u64)
+Description: Adds offset to the raw value of pointer ptr.
Constraints: None.
+__ptr_sub(ptr: raw_ptr, offset: u64)
+Description: Subtracts offset to the raw value of pointer ptr.
Constraints: None.
+__smo<T>(recipient: b256, data: T, coins: u64)
+Description: Sends a message data of arbitrary type T and coins amount of the base asset to address recipient.
Constraints: None.
+__not(op: T) -> T
+Description: Bitwise NOT of op
Constraints: T is an integer type, i.e. u8, u16, u32, u64, u256, b256.
__jmp_mem()
+Description: Jumps to MEM[$hp].
Constraints: None.
+__slice(item: &[T; N], start: u64, end: u64) -> &[T]
+__slice(item: &[T], start: u64, end: u64) -> &[T]
+__slice(item: &mut [T; N], start: u64, end: u64) -> &mut [T]
+__slice(item: &mut [T], start: u64, end: u64) -> &mut [T]
+Description: Slices an array or another slice.
+This intrinsic returns a reference to a slice containing the range of elements inside item.
+The mutability of reference is defined by the first parameter mutability.
Runtime bound checks are not generated, and must be done manually when and where appropriated. Compile time bound checks are done when possible.
+Constraints:
+item is an array or a slice;start is a literal, it must be smaller than item length;end is a literal, it must be smaller than or equal to item length;end must be greater than or equal to start__elem_at(item: &[T; N], index: u64) -> &T
+__elem_at(item: &[T], index: u64) -> &T
+__elem_at(item: &mut [T; N], index: u64) -> &mut T
+__elem_at(item: &mut [T], index: u64) -> &mut T
+Description: Returns a reference to the indexed element. The mutability of reference is defined by the first parameter mutability.
+Runtime bound checks are not generated, and must be done manually when and where appropriated. Compile time bound checks are done when possible.
+Constraints:
+item is a reference to an array or a reference to a slice;index is a literal, it must be smaller than item length;Thanks for your interest in contributing to Sway! This document outlines the process for installing and setting up the Sway toolchain for development, as well as some conventions on contributing to Sway.
+If you run into any difficulties getting started, you can always ask questions on our Discourse.
+See the introduction section for instructions on installing and setting up the Sway toolchain.
+git clone https://github.com/FuelLabs/sway
+cd sway
+The following steps will run the sway test suite and ensure that everything is set up correctly.
+First, open a new terminal and start fuel-core with:
fuel-core
+Then open a second terminal, cd into the sway repo and run:
cargo run --bin test
+After the test suite runs, you should see:
+Tests passed.
+_n_ tests run (0 skipped)
+Congratulations! You've now got everything setup and are ready to start making contributions.
+There are many ways in which you may contribute to the Sway project, some of which involve coding knowledge and some which do not. A few examples include:
+Check out our Help Wanted, Sway Book or Good First Issue issues to find a suitable task.
+If you are planning something big, for example, related to multiple components or changes current behaviors, make sure to open an issue to discuss with us before starting on the implementation.
+This is a rough outline of what a contributor's workflow looks like:
+Thanks for your contributions!
+Pull requests should be linked to at least one issue in the same repo.
+If the pull request resolves the relevant issues, and you want GitHub to close these issues automatically after it merged into the default branch, you can use the syntax (KEYWORD #ISSUE-NUMBER) like this:
close #123
+If the pull request links an issue but does not close it, you can use the keyword ref like this:
ref #456
+Multiple issues should use full syntax for each issue and separate by a comma, like:
+close #123, ref #456
+The following list contains keywords that are reserved for current or +future use by the Sway language. As such, they cannot be used as +identifiers. Identifiers are names of functions, variables, +parameters, modules, constants, attributes, types or +traits, etc.
+The following is a list of keywords currently in use, with their +functionality described.
+as - rename items in use statements, e.g., use type::a as alias_nameabi - defines a smart contract ABI in a syntactically similar way to traitsbreak - exit a loop immediatelyconst - define constant itemscontinue - continue to the next loop iterationelse - used in conjunction with if conditions for control flow constructsenum - define an enumerationfalse - Boolean false literalfn- define a function or the function pointer typeif - branch based on the result of a conditional expressionimpl - implement inherent or trait functionalitylet - bind a variablematch - exhaustively match a value to patternsmod - define a modulemut - denote mutability in references, or pattern bindingspub - denote public visibility of Sway data structures, traits, or modulesref - bind by referencereturn - return early from a functionSelf - a type alias for the type we are defining or implementingself - method subjectstruct - define a structuretrait - define a traittrue - Boolean true literaltype - define a type alias or associated typeuse - bring symbols into scopewhere - specifies traits for generic typeswhile - loop conditionally based on the result of an expressionabstractasyncawaitbecomeboxdodynexternforinloopmacromoveoverrideprivstaticsupertrytypeofunsafeunsizedvirtualyieldKeywords associated with defining the type of Sway program to compile
+contract - analogous to a deployed API with some database statelibrary - Sway code that defines new common behaviorpredicate - programs that return a Boolean value and which represent ownership of some resource upon execution to truescript - a runnable bytecode on the chain, which executes once to perform a taskKeywords associated with defining the functionality of attributes
+allow - overrides checks that would otherwise result in errors or warningsdoc - specifies documentationinline - suggests that a copy of the attributed function should be placed in the caller, rather than generating code to call the function where it is definedpayable - implies method is payable for compile timestorage - declaration that contains a list of stored variablestest - marks a function to be executed as a testdeprecated - marks an item as deprecatedimpl blocks need to be defined before any of the functions they define can be called. This includes sibling functions in the same impl declaration, i.e., functions in an impl can't call each other yet.storage block are not yet supported. See the Manual Storage Management section for details on how to use store and get from the standard library to manage storage slots directly. Note, however, that StorageMap<K, V> does support arbitrary types for K and V without any limitations.Sway shares a lot with Rust, especially its syntax. Because they are so similar, you may be surprised or caught off guard when they differ. This page serves to outline, from a high level, some of the syntactic gotchas that you may encounter.
+In Rust, enums generally take one of three forms: unit variants, which have no inner data, struct variants, which contain named fields, and tuple variants, which contain within them a tuple of data. If you are unfamiliar with these terms, this is what they look like:
+// note to those skimming the docs: this is Rust syntax! Not Sway! Don't copy/paste this into a Sway program.
+
+enum Foo {
+ UnitVariant,
+ TupleVariant(u32, u64, bool),
+ StructVariant {
+ field_one: bool,
+ field_two: bool
+ }
+}In Sway, enums are simplified. Enums variants must all specify exactly one type. This type represents their interior data. This is actually isomorphic to what Rust offers, but with a different syntax. You can see the above enum but with Sway syntax below:
+// This is equivalent Sway syntax for the above Rust enum.
+enum Foo {
+ UnitVariant: (),
+ TupleVariant: (u32, u64, bool),
+ StructVariant: MyStruct,
+}
+
+struct MyStruct {
+ field_one: bool,
+ field_two: bool,
+}
+In Rust, the borrow checker implements Rust's ownership system
+In Sway, there is no borrow checker. This means there is no concept of ownership, borrowing, or lifetimes. Instead, objects are copied and moved similar to C++. Also Sway does not have any destructors nor Drop traits. This means allocated memory lives for the entire transaction and is not deallocated until the end of the transaction. A transaction may allocate up to 64 MB of memory.
This page outlines some of the critical differences between Sway and Solidity, and between the FuelVM and the EVM.
+The underlying virtual machine targeted by Sway is the FuelVM, specified here. Solidity targets the Ethereum Virtual Machine (EVM), specified here.
+Words in the FuelVM are 64 bits (8 bytes), rather than the 256 bits (32 bytes) of the EVM. Therefore, all primitive integers smaller and including u64 are stored in registers; u256, being bigger than the registers, and hashes (the b256 type) are not stored in registers but rather in memory. They are therefore pointers to a 32-byte memory region containing their data.
Only unsigned integers are provided as primitives: u8, u16, u32, u64, and u256. Signed integer arithmetic is not available in the FuelVM. Signed integers and signed integer arithmetic can be implemented in high-level libraries if needed.
Panics in the FuelVM (called "reverts" in Solidity and the EVM) are global, i.e. they cannot be caught. A panic will completely and unconditionally revert the stateful effects of a transaction, minus gas used.
+Math in the FuelVM is by default safe (i.e. any overflow or exception is a panic). Safety checks are performed natively in the VM implementation, rather than at the bytecode level like Solidity's default safe math.
+ +There is no practical code size limit to Sway contracts. The physical limit is governed by the VM_MAX_RAM VM parameter, which at the time of writing is 64 MiB.
Account types in the FuelVM have type-safe wrappers around primitive b256 hashes to clearly distinguish their respective types. The wrapper Address mirrors that of an EOA (Externally Owned Account) and has the ability to hold UTXOs in the context of the EVM. The other wrapper, ContractId, reflects that of a deployed contract in the EVM but cannot hold UTXOs.
In Sway, structs, traits, and enums are CapitalCase. Modules, variables, and functions are snake_case, constants are SCREAMING_SNAKE_CASE. The compiler will warn you if your capitalization is ever unidiomatic.
The purpose of Sway Libraries is to contain libraries which users can import and use that are not part of the standard library.
+These libraries contain helper functions and other tools valuable to blockchain development.
+For more information on how to use a Sway-Libs library, please refer to the Sway-Libs Book.
+Asset Libraries are any libraries that use Native Assets on the Fuel Network.
+Access Control and Security Libraries are any libraries that are built and intended to provide additional safety when developing smart contracts.
+Cryptography Libraries are any libraries that provided cryptographic functionality beyond what the std-lib provides.
+Math Libraries are libraries which provide mathematic functions or number types that are outside of the std-lib's scope.
+Data Structure Libraries are libraries which provide complex data structures which unlock additional functionality for Smart Contracts.
+Sway code that contains any of the following behavior is considered undefined. +The compiler is allowed to treat undefined Sway code however it desires, +including removing it or replacing it with any other Sway code.
+This is not an exhaustive list, it may grow or shrink, there is no formal model +of Sway's semantics so there may be more behavior considered undefined. We +reserve the right to make some of the listed behavior defined in the future.
+raw_ptr and raw_slice.Iterators.