Skip to content

Commit

Permalink
Token library documentation (#4834)
Browse files Browse the repository at this point in the history 
## Description


## Checklist

- [ ] I have linked to any relevant issues.
- [ ] I have commented my code, particularly in hard-to-understand
areas.
- [ ] I have updated the documentation where relevant (API docs, the
reference, and the Sway book).
- [ ] I have added tests that prove my fix is effective or that my
feature works.
- [ ] I have added (or requested a maintainer to add) the necessary
`Breaking*` or `New Feature` labels where relevant.
- [ ] I have done my best to ensure that my PR adheres to [the Fuel Labs
Code Review
Standards](https://github.com/FuelLabs/rfcs/blob/master/text/code-standards/external-contributors.md).
- [ ] I have requested a review from the relevant team or maintainers.
  • Loading branch information
@SwayStar123
SwayStar123 authored Jul 20, 2023
1 parent 1b0f4c2 commit b62d604
Showing 1 changed file with 106 additions and 90 deletions.
196 changes: 106 additions & 90 deletions sway-lib-std/src/token.sw
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,27 +13,29 @@ use ::outputs::{Output, output_amount, output_count, output_type};
/// to `to` by calling either `force_transfer_to_contract` or
/// `transfer_to_address`, depending on the type of `Identity`.
///
/// > **_WARNING:_**
/// >
/// > If the `to` Identity is a contract, this will transfer coins to the contract even with no way to retrieve them
/// > (i.e: no withdrawal functionality on the receiving contract), possibly leading to
/// > the **_PERMANENT LOSS OF COINS_** if not used with care.
/// # Additional Information
///
/// If the `to` Identity is a contract, this will transfer coins to the contract even with no way to retrieve them
/// (i.e: no withdrawal functionality on the receiving contract), possibly leading to
/// the **_PERMANENT LOSS OF COINS_** if not used with care.
///
/// ### Arguments
/// # Arguments
///
/// * `amount` - The amount of tokens to mint.
/// * `to` - The `Identity` to which to send the tokens.
/// * `amount`: [u64] - The amount of tokens to mint.
/// * `to`: [Identity] - The recipient identity.
///
/// ### Examples
/// # Examples
///
/// ```sway
/// use std::{constants::ZERO_B256, token::mint_to};
///
/// // replace the zero Address/ContractId with your desired Address/ContractId
/// let to_address = Identity::Address(Address::from(ZERO_B256));
/// let to_contract_id = Identity::ContractId(ContractId::from(ZERO_B256));
/// mint_to(500, to_address);
/// mint_to(500, to_contract_id);
/// fn foo() {
/// // replace the zero Address/ContractId with your desired Address/ContractId
/// let to_address = Identity::Address(Address::from(ZERO_B256));
/// let to_contract_id = Identity::ContractId(ContractId::from(ZERO_B256));
/// mint_to(500, to_address);
/// mint_to(500, to_contract_id);
/// }
/// ```
pub fn mint_to(amount: u64, to: Identity) {
mint(amount);
Expand All @@ -43,25 +45,27 @@ pub fn mint_to(amount: u64, to: Identity) {
/// Mint `amount` coins of the current contract's `asset_id` and send them
/// UNCONDITIONALLY to the contract at `to`.
///
/// > **_WARNING:_**
/// >
/// > This will transfer coins to a contract even with no way to retrieve them
/// > (i.e: no withdrawal functionality on the receiving contract), possibly leading to
/// > the **_PERMANENT LOSS OF COINS_** if not used with care.
/// # Additional Information
///
/// This will transfer coins to a contract even with no way to retrieve them
/// (i.e: no withdrawal functionality on the receiving contract), possibly leading to
/// the **_PERMANENT LOSS OF COINS_** if not used with care.
///
/// ### Arguments
/// # Arguments
///
/// * `amount` - The amount of tokens to mint.
/// * `to` - The `ContractId` to which to send the tokens.
/// * `amount`: [u64] - The amount of tokens to mint.
/// * `to`: [ContractId] - The recipient contract.
///
/// ### Examples
/// # Examples
///
/// ```sway
/// use std::{constants::ZERO_B256, token::mint_to_contract};
///
/// // replace the zero ContractId with your desired ContractId
/// let to = ContractId::from(ZERO_B256);
/// mint_to_contract(500, to);
/// fn foo() {
/// // replace the zero ContractId with your desired ContractId
/// let to = ContractId::from(ZERO_B256);
/// mint_to_contract(500, to);
/// }
/// ```
pub fn mint_to_contract(amount: u64, to: ContractId) {
mint(amount);
Expand All @@ -71,19 +75,21 @@ pub fn mint_to_contract(amount: u64, to: ContractId) {
/// Mint `amount` coins of the current contract's `asset_id` and send them to
/// the Address `to`.
///
/// ### Arguments
/// # Arguments
///
/// * `amount` - The amount of tokens to mint.
/// * `to` - The `Address` to which to send the tokens.
/// * `amount`: [u64] - The amount of tokens to mint.
/// * `to`: [Address] - The recipient address.
///
/// ### Examples
/// # Examples
///
/// ```sway
/// use std::{constants::ZERO_B256, token::mint_to_address};
///
/// // replace the zero Address with your desired Address
/// let to = Address::from(ZERO_B256);
/// mint_to_address(500, to);
/// fn foo() {
/// // replace the zero Address with your desired Address
/// let to = Address::from(ZERO_B256);
/// mint_to_address(500, to);
/// }
/// ```
pub fn mint_to_address(amount: u64, to: Address) {
mint(amount);
Expand All @@ -92,16 +98,18 @@ pub fn mint_to_address(amount: u64, to: Address) {

/// Mint `amount` coins of the current contract's `asset_id`. The newly minted tokens are owned by the current contract.
///
/// ### Arguments
/// # Arguments
///
/// * `amount` - The amount of tokens to mint.
/// * `amount`: [u64] - The amount of tokens to mint.
///
/// ### Examples
/// # Examples
///
/// ```sway
/// use std::token::mint;
///
/// mint(500);
/// fn foo() {
/// mint(500);
/// }
/// ```
pub fn mint(amount: u64) {
asm(r1: amount) {
Expand All @@ -111,20 +119,22 @@ pub fn mint(amount: u64) {

/// Burn `amount` coins of the current contract's `asset_id`. Burns them from the balance of the current contract.
///
/// ### Arguments
/// # Arguments
///
/// * `amount` - The amount of tokens to burn.
/// * `amount`: [u64] - The amount of tokens to burn.
///
/// ### Reverts
/// # Panics
///
/// Reverts if the contract balance is less than `amount`.
/// * When the contract balance is less than `amount`.
///
/// ### Examples
/// # Examples
///
/// ```sway
/// use std::token::burn;
///
/// burn(500);
/// fn foo() {
/// burn(500);
/// }
/// ```
pub fn burn(amount: u64) {
asm(r1: amount) {
Expand All @@ -136,34 +146,36 @@ pub fn burn(amount: u64) {
/// to `to` by calling either `force_transfer_to_contract` or
/// `transfer_to_address`, depending on the type of `Identity`.
///
/// > **_WARNING:_**
/// >
/// > If the `to` Identity is a contract this may transfer coins to the contract even with no way to retrieve them
/// > (i.e. no withdrawal functionality on receiving contract), possibly leading
/// > to the **_PERMANENT LOSS OF COINS_** if not used with care.
/// # Additional Information
///
/// If the `to` Identity is a contract this may transfer coins to the contract even with no way to retrieve them
/// (i.e. no withdrawal functionality on receiving contract), possibly leading
/// to the **_PERMANENT LOSS OF COINS_** if not used with care.
///
/// ### Arguments
/// # Arguments
///
/// * `amount` - The amount of tokens to transfer.
/// * `asset_id` - The `AssetId` of the token to transfer.
/// * `to` - The `Identity` of the recipient.
/// * `amount`: [u64] - The amount of tokens to transfer.
/// * `asset_id`: [AssetId] - The token to transfer.
/// * `to`: [Identity] - The recipient identity.
///
/// ### Reverts
/// # Panics
///
/// * If `amount` is greater than the contract balance for `asset_id`.
/// * If `amount` is equal to zero.
/// * If there are no free variable outputs when transferring to an `Address`.
/// * When `amount` is greater than the contract balance for `asset_id`.
/// * When `amount` is equal to zero.
/// * When there are no free variable outputs when transferring to an `Address`.
///
/// ### Examples
/// # Examples
///
/// ```sway
/// use std::{constants::{BASE_ASSET_ID, ZERO_B256}, token::transfer};
///
/// // replace the zero Address/ContractId with your desired Address/ContractId
/// let to_address = Identity::Address(Address::from(ZERO_B256));
/// let to_contract_id = Identity::ContractId(ContractId::from(ZERO_B256));
/// transfer(500, BASE_ASSET_ID, to_address);
/// transfer(500, BASE_ASSET_ID, to_contract_id);
/// fn foo() {
/// // replace the zero Address/ContractId with your desired Address/ContractId
/// let to_address = Identity::Address(Address::from(ZERO_B256));
/// let to_contract_id = Identity::ContractId(ContractId::from(ZERO_B256));
/// transfer(500, BASE_ASSET_ID, to_address);
/// transfer(500, BASE_ASSET_ID, to_contract_id);
/// }
/// ```
pub fn transfer(amount: u64, asset_id: AssetId, to: Identity) {
match to {
Expand All @@ -175,31 +187,33 @@ pub fn transfer(amount: u64, asset_id: AssetId, to: Identity) {
/// UNCONDITIONAL transfer of `amount` coins of type `asset_id` to
/// the contract at `to`.
///
/// > **_WARNING:_**
/// >
/// > This will transfer coins to a contract even with no way to retrieve them
/// > (i.e. no withdrawal functionality on receiving contract), possibly leading
/// > to the **_PERMANENT LOSS OF COINS_** if not used with care.
/// # Additional Information
///
/// This will transfer coins to a contract even with no way to retrieve them
/// (i.e. no withdrawal functionality on receiving contract), possibly leading
/// to the **_PERMANENT LOSS OF COINS_** if not used with care.
///
/// ### Arguments
/// # Arguments
///
/// * `amount` - The amount of tokens to transfer.
/// * `asset_id` - The `AssetId` of the token to transfer.
/// * `to` - The `ContractId` of the recipient contract.
/// * `amount`: [u64] - The amount of tokens to transfer.
/// * `asset_id`: [AssetId] - The token to transfer.
/// * `to`: [ContractId] - The recipient contract.
///
/// ### Reverts
/// # Reverts
///
/// * If `amount` is greater than the contract balance for `asset_id`.
/// * If `amount` is equal to zero.
/// * When `amount` is greater than the contract balance for `asset_id`.
/// * When `amount` is equal to zero.
///
/// ### Examples
/// # Examples
///
/// ```sway
/// use std::{constants::{BASE_ASSET_ID, ZERO_B256}, token::force_transfer_to_contract};
///
/// // replace the zero ContractId with your desired ContractId
/// let to_contract_id = ContractId::from(ZERO_B256);
/// force_transfer_to_contract(500, BASE_ASSET_ID, to_contract_id);
/// fn foo() {
/// // replace the zero ContractId with your desired ContractId
/// let to_contract_id = ContractId::from(ZERO_B256);
/// force_transfer_to_contract(500, BASE_ASSET_ID, to_contract_id);
/// }
/// ```
pub fn force_transfer_to_contract(amount: u64, asset_id: AssetId, to: ContractId) {
asm(r1: amount, r2: asset_id.value, r3: to.value) {
Expand All @@ -210,26 +224,28 @@ pub fn force_transfer_to_contract(amount: u64, asset_id: AssetId, to: ContractId
/// Transfer `amount` coins of type `asset_id` and send them to
/// the address `to`.
///
/// ### Arguments
/// # Arguments
///
/// * `amount` - The amount of tokens to transfer.
/// * `asset_id` - The `AssetId` of the token to transfer.
/// * `to` - The `Address` of the recipient user.
/// * `amount`: [u64] - The amount of tokens to transfer.
/// * `asset_id`: [AssetId] - The token to transfer.
/// * `to`: [Address] - The recipient address.
///
/// ### Reverts
/// # Panics
///
/// * If `amount` is greater than the contract balance for `asset_id`.
/// * If `amount` is equal to zero.
/// * If there are no free variable outputs.
/// * When `amount` is greater than the contract balance for `asset_id`.
/// * When `amount` is equal to zero.
/// * When there are no free variable outputs.
///
/// ### Examples
/// # Examples
///
/// ```sway
/// use std::{constants::{BASE_ASSET_ID, ZERO_B256}, token::transfer_to_address};
///
/// // replace the zero Address with your desired Address
/// let to_address = Address::from(ZERO_B256);
/// transfer_to_address(500, BASE_ASSET_ID, to_address);
/// fn foo() {
/// // replace the zero Address with your desired Address
/// let to_address = Address::from(ZERO_B256);
/// transfer_to_address(500, BASE_ASSET_ID, to_address);
/// }
/// ```
pub fn transfer_to_address(amount: u64, asset_id: AssetId, to: Address) {
// maintain a manual index as we only have `while` loops in sway atm:
Expand Down

0 comments on commit b62d604

Please sign in to comment.