Skip to content

Commit

Permalink
Create Examples and Integrate Into Docs (#238)
Browse files Browse the repository at this point in the history 
## Type of change

<!--Delete points that do not apply-->

- Improvement (refactoring, restructuring repository, cleaning tech
debt, ...)
- Documentation

## Changes

The following changes have been made:

- Creates example projects for each library in an `examples/` folder
- Updates Sway-Libs book to use example projects over inline docs
- Adds examples to CI

## Related Issues

<!--Delete everything after the "#" symbol and replace it with a number.
No spaces between hash and number-->

Closes #228
  • Loading branch information
@bitzoic
bitzoic committed Apr 26, 2024
1 parent 5b773d6 commit e490fa7
Show file tree
Hide file tree
Showing 55 changed files with 1,208 additions and 516 deletions.
34 changes: 34 additions & 0 deletions .github/workflows/ci.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -136,3 +136,37 @@ jobs:
- name: Build sway-libs docs
run: |
forc doc --manifest-path libs
build-examples:
runs-on: ubuntu-latest
steps:
- name: Checkout repository
uses: actions/checkout@v3

- name: Install Rust toolchain
uses: dtolnay/rust-toolchain@master
with:
toolchain: ${{ env.RUST_VERSION }}
components: rustfmt

- name: Init cache
uses: Swatinem/rust-cache@v2

- name: Install Fuel toolchain
uses: FuelLabs/action-fuel-toolchain@v0.6.0
with:
name: my-toolchain
components: forc@${{ env.FORC_VERSION }}, fuel-core@${{ env.CORE_VERSION }}

- name: Check Sway formatting
run: forc fmt --path examples --check

- name: Check Rust formatting
run: cargo fmt --manifest-path examples/Cargo.toml --verbose --check

- name: Build All Examples
run: forc build --path examples --release

- name: Cargo Test Examples
run: |
cargo test --manifest-path examples/Cargo.toml
47 changes: 8 additions & 39 deletions docs/book/src/admin/index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,26 +13,15 @@ In order to use the Admin Library, Sway Libs must be added to the `Forc.toml` fi
To import the Admin Library, be sure to include both the Admin and Ownership Libraries in your import statements.

```sway
use sway_libs::{admin::*, ownership::*};
{{#include ../../../../examples/admin/src/main.sw:import}}
```

## Integrating the Admin Library into the Ownership Library

To use the Admin library, be sure to set a contract owner for your contract. The following demonstrates setting a contract owner using the [Ownership Library](../ownership/).

```sway
use sway_libs::{admin::add_admin, ownership::initialize_ownership};
#[storage(read, write)]
fn my_constructor(new_owner: Identity) {
initialize_ownership(new_owner);
}
#[storage(read, write)]
fn add_a_admin(new_admin: Identity) {
// Can only be called by contract's owner set in the constructor above.
add_admin(new_admin);
}
{{#include ../../../../examples/admin/src/owner_integration.sw:ownership_integration}}
```

## Basic Functionality
Expand All @@ -42,25 +31,17 @@ fn add_a_admin(new_admin: Identity) {
To add a new admin to a contract, call the `add_admin()` function.

```sway
#[storage(read, write)]
fn add_a_admin(new_admin: Identity) {
// Can only be called by contract's owner.
add_admin(new_admin);
}
{{#include ../../../../examples/admin/src/main.sw:add_admin}}
```

> **NOTE** Only the contract's owner may call this function. Please see the example above to set a contract owner.
### Removing an Admin

To remove an admin from a contract, call the `remove_admin()` function.
To remove an admin from a contract, call the `revoke_admin()` function.

```sway
#[storage(read, write)]
fn remove_a_admin(old_admin: Identity) {
// Can only be called by contract's owner.
remove_admin(old_admin);
}
{{#include ../../../../examples/admin/src/main.sw:remove_admin}}
```

> **NOTE** Only the contract's owner may call this function. Please see the example above to set a contract owner.
Expand All @@ -70,33 +51,21 @@ fn remove_a_admin(old_admin: Identity) {
To restrict a function to only an admin, call the `only_admin()` function.

```sway
#[storage(read)]
fn only_owner_may call() {
only_admin();
// Only an admin may reach this line.
}
{{#include ../../../../examples/admin/src/main.sw:only_admin}}
```

> **NOTE:** Admins and the contract's owner are independent of one another. `only_admin()` will revert if called by the contract's owner.
To restrict a function to only an admin or the contract's owner, call the `only_owner_or_admin()` function.

```sway
#[storage(read)]
fn both_owner_or_admin_may_call() {
only_owner_or_admin();
// Only an admin may reach this line.
}
{{#include ../../../../examples/admin/src/main.sw:both_admin}}
```

### Checking Admin Status

To check the administrative privileges of a user, call the `is_admin()` function.

```sway
#[storage(read)]
fn check_if_admin(admin: Identity) {
let status = is_admin(admin);
assert(status);
}
{{#include ../../../../examples/admin/src/main.sw:check_admin}}
```
111 changes: 6 additions & 105 deletions docs/book/src/asset/base.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,27 +9,15 @@ In order to use the Asset Library, Sway Libs and [Sway Standards](https://github
To import the Asset Library Base Functionality and [SRC-20](https://github.com/FuelLabs/sway-standards/blob/master/SRCs/src-20.md) Standard to your Sway Smart Contract, add the following to your Sway file:

```sway
use sway_libs::asset::base::*;
use standards::src20::*;
{{#include ../../../../examples/asset/base_docs/src/main.sw:import}}
```

## Integration with the SRC-20 Standard

The [SRC-20](https://github.com/FuelLabs/sway-standards/blob/master/SRCs/src-20.md) definition states that the following abi implementation is required for any Native Asset on Fuel:

```sway
abi SRC20 {
#[storage(read)]
fn total_assets() -> u64;
#[storage(read)]
fn total_supply(asset: AssetId) -> Option<u64>;
#[storage(read)]
fn name(asset: AssetId) -> Option<String>;
#[storage(read)]
fn symbol(asset: AssetId) -> Option<String>;
#[storage(read)]
fn decimals(asset: AssetId) -> Option<u8>;
}
{{#include ../../../../examples/asset/base_docs/src/main.sw:src20_abi}}
```

The Asset Library has the following complimentary functions for each function in the `SRC20` abi:
Expand All @@ -43,14 +31,7 @@ The Asset Library has the following complimentary functions for each function in
The following ABI and functions are also provided to set your [SRC-20](https://github.com/FuelLabs/sway-standards/blob/master/SRCs/src-20.md) standard storage values:

```sway
abi SetAssetAttributes {
#[storage(write)]
fn set_name(asset: AssetId, name: String);
#[storage(write)]
fn set_symbol(asset: AssetId, symbol: String);
#[storage(write)]
fn set_decimals(asset: AssetId, decimals: u8);
}
{{#include ../../../../examples/asset/base_docs/src/main.sw:set_attributes}}
```

- `_set_name()`
Expand All @@ -64,103 +45,23 @@ abi SetAssetAttributes {
Once imported, the Asset Library's base functionality should be available. To use them, be sure to add the storage block bellow to your contract which enables the [SRC-20](https://github.com/FuelLabs/sway-standards/blob/master/SRCs/src-20.md) standard.

```sway
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 {},
}
{{#include ../../../../examples/asset/base_docs/src/main.sw:src20_storage}}
```

## Implementing the SRC-20 Standard with the Asset Library

To use the Asset Library's base functionly, simply pass the `StorageKey` from the prescribed storage block. The example below shows the implementation of the [SRC-20](https://github.com/FuelLabs/sway-standards/blob/master/SRCs/src-20.md) standard in combination with the Asset Library with no user defined restrictions or custom functionality.

```sway
use sway_libs::asset::base::{
_total_assets,
_total_supply,
_name,
_symbol,
_decimals
};
use standards::src20::SRC20;
use std::{string::String, storage::storage_string::*};
// The SRC-20 storage block
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 {},
}
// Implement the SRC-20 Standard for this contract
impl SRC20 for Contract {
#[storage(read)]
fn total_assets() -> u64 {
// Pass the `total_assets` StorageKey to `_total_assets()` from the Asset Library.
_total_assets(storage.total_assets)
}
#[storage(read)]
fn total_supply(asset: AssetId) -> Option<u64> {
// Pass the `total_supply` StorageKey to `_total_supply()` from the Asset Library.
_total_supply(storage.total_supply, asset)
}
#[storage(read)]
fn name(asset: AssetId) -> Option<String> {
// Pass the `name` StorageKey to `_name_()` from the Asset Library.
_name(storage.name, asset)
}
#[storage(read)]
fn symbol(asset: AssetId) -> Option<String> {
// Pass the `symbol` StorageKey to `_symbol_()` function from the Asset Library.
_symbol(storage.symbol, asset)
}
#[storage(read)]
fn decimals(asset: AssetId) -> Option<u8> {
// Pass the `decimals` StorageKey to `_decimals_()` function from the Asset Library.
_decimals(storage.decimals, asset)
}
}
{{#include ../../../../examples/asset/basic_src20/src/main.sw:basic_src20}}
```

## Setting an Asset's SRC-20 Attributes

To set some the asset attributes for an Asset, use the `SetAssetAttributes` ABI provided by the Asset Library. The example below shows the implementation of the `SetAssetAttributes` ABI with no user defined restrictions or custom functionality. It is recommended that the [Ownership Library](../ownership/index.md) is used in conjunction with the `SetAssetAttributes` ABI to ensure only a single user has permissions to set an Asset's attributes.

```sway
use sway_libs::asset::base::*;
use std::{string::String, storage::storage_string::*};
storage {
name: StorageMap<AssetId, StorageString> = StorageMap {},
symbol: StorageMap<AssetId, StorageString> = StorageMap {},
decimals: StorageMap<AssetId, u8> = StorageMap {},
}
impl SetAssetAttributes for Contract {
#[storage(write)]
fn set_name(asset: AssetId, name: String) {
_set_name(storage.name, asset, name);
}
#[storage(write)]
fn set_symbol(asset: AssetId, symbol: String) {
_set_symbol(storage.symbol, asset, symbol);
}
#[storage(write)]
fn set_decimals(asset: AssetId, decimals: u8) {
_set_decimals(storage.decimals, asset, decimals);
}
}
{{#include ../../../../examples/asset/setting_src20_attributes/src/main.sw:setting_src20_attributes}}
```

> **NOTE** The `_set_name()`, `_set_symbol()`, and `_set_decimals()` functions will set the attributes of an asset *unconditionally*. External checks should be applied to restrict the setting of attributes.
Loading

0 comments on commit e490fa7

Please sign in to comment.