Fungible Resource Manager

This document offers a description of the design and implementation of the Fungible Resource Manager blueprint. Additionally, this document provides an API reference for all its methods, functions and events.

Background

In Radix, a Resource is a native concept used to implement use-cases typically associated with “tokens” or “assets”. You can learn more about its high-level design at Resources.

A “Fungible Resource” is a kind of Resource operating on arbitrary quantities, which can be split and combined freely (i.e. its units do not have distinct identity nor individual metadata). Detailed behaviors of all units of a specific Fungible Resource is defined by its Fungible Resource Manager. This includes the rules for:

the Resource’s maximum divisibility,
minting and burning the Resource’s units,
freezing and recalling the Resource from Vaults,
tracking the Resource’s total supply.

Many functionalities of a Fungible Resource are implemented by Fungible Vault, Fungible Bucket and Fungible Proof, which are separate Native Blueprints (covered in detail by their respective documentation pages). The sections below focus on the FungibleResourceManager Blueprint itself.

Optional Features

Not every Fungible Resource needs to satisfy the same set of use-cases. For this reason, the set of blueprint Features which can be optionally present on a FungibleResourceManager instance is quite broad:

track_total_supply - whether the total supply of the Resource should be tracked,
vault_freeze - whether a Vault holding the Resource can ever be frozen,
vault_recall - whether the Resource can ever be recalled from a Vault,
mint - whether more of the Resource (above initial supply) can ever be minted,
burn - whether the Resource can ever be burned.

On-ledger State

The FungibleResourceManager blueprint defines two fields:

divisibility, holding an integer in the inclusive range [0, 18], denoting a number of decimal places that the Resource can be split into. In other words: a precision of fixed-point fractional operations performed on the Resource’s amounts.
total_supply (only present if the track_total_supply Feature is enabled), holds an automatically-maintained amount of all units in circulation at any moment (i.e. minted so far and not burned yet).

API Reference

Functions

`create`

Defines a new fungible Resource (i.e. creates its Manager).

Name	`create`
Type	Function
Callable By	Public
Arguments	`owner_role` - OwnerRole: The owner’s access rule (possibly `None`). `track_total_supply` - `bool`: Whether to enable the supply-tracking feature. `divisibility` - `u8`: The Resource unit’s divisibility (see its definition). `resource_roles` - FungibleResourceRoles: The set of rules for all roles, including the optional ones (which cause their respective features to be enabled). `metadata` - `ModuleConfig<MetadataInit>`: Configuration of metadata roles and the initial metadata values. `address_reservation` - `Option<GlobalAddressReservation>`: An optional reservation of the global address.
Returns	`ResourceAddress`: A de-facto identifier of the newly-created Resource; its Manager’s address.

`create_with_initial_supply`

Defines a new fungible Resource (i.e. creates its Manager) in the same way as create does, and simultaneously mints the requested amount.

This variant is useful e.g. for creating a fixed supply of a non-mintable Resource.

Name	`create_with_initial_supply`
Type	Function
Callable By	Public
Arguments	`owner_role` - OwnerRole: The owner’s access rule (possibly `None`). `track_total_supply` - `bool`: Whether to enable the supply-tracking feature. `divisibility` - `u8`: The Resource unit’s divisibility (see its definition). `initial_supply` - `Decimal`: The amount to initially mint. `resource_roles` - FungibleResourceRoles: The set of rules for all roles, including the optional ones (which cause their respective features to be enabled). `metadata` - `ModuleConfig<MetadataInit>`: Configuration of metadata roles and the initial metadata values. `address_reservation` - `Option<GlobalAddressReservation>`: An optional reservation of the global address.
Returns	A tuple containing: `ResourceAddress`: A de-facto identifier of the newly-created Resource; its Manager’s address. `FungibleBucket`: A bucket with the entire initially-minted supply of the Resource.

Methods

`mint`

Creates the requested amount of the Resource.

Note: the mint feature must be enabled on the Resource Manager.

Name	`mint`
Type	Method
Callable By	Public - requires the `minter` role.
Arguments	`amount` - `Decimal`: An amount to mint.
Returns	`FungibleBucket`: A bucket with the newly-minted amount.

`burn`

Destroys the given bucket of the Resource.

Note: the burn feature must be enabled on the Resource Manager.

Name	`burn`
Type	Method
Callable By	Public - requires the `burner` role.
Arguments	`bucket` - `FungibleBucket`: A bucket with the amount to burn.
Returns	Nothing

`package_burn`

Destroys the given bucket of the Resource, in the same way as burn does. This is an internal method needed to allow burning Resources from a Vault.

Note: the burn feature must be enabled on the Resource Manager.

Name	`package_burn`
Type	Method
Callable By	Own package only.
Arguments	`bucket` - `FungibleBucket`: A bucket with the amount to burn.
Returns	Nothing

`create_empty_vault`

Creates a new empty Vault tailored for storing the managed Resource and supporting the features configured on this Resource Manager.

Name	`create_empty_vault`
Type	Method
Callable By	Public
Arguments	None
Returns	`Own`: The address of the created Vault.

`create_empty_bucket`

Creates a new empty Fungible Bucket tailored for holding the managed Resource.

Name	`create_empty_bucket`
Type	Method
Callable By	Public
Arguments	None
Returns	`FungibleBucket`: The created Bucket.

`get_resource_type`

Queries the managed Resource’s type.

Name	`get_resource_type`
Type	Method
Callable By	Public
Arguments	None
Returns	`ResourceType`: For a fungible Resource Manager this will always be `ResourceType::Fungible`, containing the Resource’s configured `divisibility`.

`get_total_supply`

Queries the total amount of all units of this Resource currently in circulation.

Note: the track_total_supply feature must be enabled on the Resource Manager.

Name	`get_total_supply`
Type	Method
Callable By	Public
Arguments	None
Returns	`Decimal`: The total supply amount.

`amount_for_withdrawal`

Converts the input amount to an actual withdrawal amount, taking the Resource’s configured divisibility and the given rounding mode into account.

Name	`amount_for_withdrawal`
Type	Method
Callable By	Public
Arguments	`request_amount` - `Decimal`: The approximate, requested amount. `withdraw_strategy` - `WithdrawStrategy`: either `Exact`, which returns the `request_amount` unchanged, or one of the RoundingModes to be applied.
Returns	`Decimal`: The actual, withdrawable amount.

`drop_empty_bucket`

Drops the given empty Fungible Bucket.

Note: passing a non-empty Bucket will result in an error.

Name	`drop_empty_bucket`
Type	Method
Callable By	Public
Arguments	`bucket` - `FungibleBucket`: The bucket to drop.
Returns	Nothing

Events

A FungibleResourceManager component instance can be a source of the following events:

`VaultCreationEvent`

{
  // The ID of the created Vault.
  vault_id: NodeId
}

Emitted when a new Vault for the managed Resource is created (i.e. on create_empty_vault API call).

`MintFungibleResourceEvent`

{
  // The minted amount.
  amount: Decimal,
}

Emitted when some amount of the managed Resource is minted (i.e. on the explicit mint API call, but also on create_with_initial_supply).

`BurnFungibleResourceEvent`

{
  // The burned amount.
  amount: Decimal
}

Emitted when some amount of the managed Resource is burned (i.e. on the explicit burn/package_burn API calls, but also internally when burning the transaction fees).