Documentation for assets module

srml/assets/README.adoc

@@ -0,0 +1,108 @@
+# Assets Module
+
+## Overview
+
+The assets module provides functionality for asset management of fungible asset classes with a fixed supply, including:
+
+* Asset Issuance
+* Asset Transfer
+* Asset Destruction
+
+The SRML Support Module implements the `Currency` trait abstraction over the SRML Assets Module's fungible assets system.
+
+### Types
+
+* `AssetId`: `u32`
+
+## Public Interface
+
+### Supported Origins
+
+**signed** - Used to issue, transfer, and destroy an asset holding.
+
+### Public Immutable functions (getters)
+
+#### `balance(id: AssetId, who: T::AccountId) -> T::Balance`
+
+#### `total_supply(id: AssetId) -> T::Balance`
+
+### Public Mutable functions (changing state)
+
+#### `issue(origin, total: T::Balance)`
+
+#### `transfer(origin, id: AssetId, target: <T::Lookup as StaticLookup>::Source, amount: T::Balance)`
+
+#### `destroy(origin, id: AssetId)`
+
+### Events:
+
+#### `Issued(AssetId, AccountId, Balance)`
+
+#### `Transferred(AssetId, AccountId, AccountId, Balance)`
+
+#### `Destroyed(AssetId, AccountId, Balance)`
+
+## Usage
+
+The following example shows how to use the Asset Module in your custom module to query an account's asset holding, and query the total supply of an asset and an account's asset holding balance.
+
+**1. Import Asset Module and Types**
+
+Import the `assets` module and derive your custom module configuration traits from the `assets` module trait.
+
+```rust
+use assets;
+
+pub trait Trait: assets::Trait { }
+```
+
+**2. Import Accounts**
+
+```rust
+const ALICE: u64 = 1;
+const BOB: u64 = 2;
+
+// Initial Asset ID is 0
+let initial_asset_id: u32 = <assets::Module<T>>::next_asset_id();
+const FIXED_SUPPLY: u64 = 100;
+```
+
+**3. Issue a new Fungible Asset to an Account**
+
+Issue the `total` amount of a new class of fungible asset with a fixed supply of units to a signed sender's (`origin`) account (i.e. Alice) and trigger the `Issued` event that contains the generated `AssetId`.
+
+```rust
+<assets::Module<T>>::issue(Origin::signed(&ALICE), FIXED_SUPPLY);
+```
+
+**4. Transfer a Fungible Asset between Accounts**
+
+Transfer a signed sender's (i.e. Alice) account holding of an asset's `AssetId` to a `target` recipient account (i.e. Bob) using the public call `transfer`. It only triggers the `Transferred` event if the transfer is valid.
+
+```rust
+<assets::Module<T>>::transfer(Origin::signed(&ALICE), initial_asset_id, BOB, FIXED_SUPPLY);
+```
+
+**5. Destroy the Fungible Asset holding of an Account**
+
+Destroy a signed sender's (i.e. Alice) entire account holding of a fungible asset and trigger the `Destroyed` event if they have a non-zero balance.
+
+```rust
+<assets::Module<T>>::destroy(Origin::signed(&ALICE), initial_asset_id);
+```
+
+**6. Query the Fungible Asset holding of an Account**
+
+Query an account's holding balance (i.e. Alice) of a fungible asset by calling the asset module's `balance` function.
+
+```rust
+let balance = <assets::Module<T>>::balance(initial_asset_id, Origin::signed(&ALICE));
+```
+
+**7. Query the Total Supply of a Fungible Asset**
+
+Query the total supply of a fungible asset that has been issued by calling the asset module's `total_supply` function.
+
+```rust
+let total_supply = <assets::Module<T>>::total_supply(initial_asset_id);
+```