Documentation for balances module

srml/balances/src/lib.rs

@@ -14,13 +14,131 @@
 // You should have received a copy of the GNU General Public License
 // along with Substrate.  If not, see <http://www.gnu.org/licenses/>.
 
-//! Balances: Handles setting and retrieval of free balance,
-//! retrieving total balance, reserve and unreserve balance,
-//! repatriating a reserved balance to a beneficiary account that exists,
-//! transfering a balance between accounts (when not reserved),
-//! slashing an account balance, account removal, rewards,
-//! lookup of an index to reclaim an account (when not balance not reserved),
-//! increasing total stake.
+//! # Balances Module
+//!
+//! ## Overview
+//!
+//! The balances module provides functions for:
+//!
+//! - Getting and setting free balance
+//! - Retrieving total, reserved, and unreserved balances
+//! - Repatriating a reserved balance to a beneficiary account that exists
+//! - Transfering a balance between accounts (when not reserved)
+//! - Slashing an account balance
+//! - Account removal
+//! - Lookup of an index to reclaim an account
+//! - Increasing or decreasing total stake
+//! - Setting and removing locks on chains that implement `LockableCurrency`
+//!
+//! ### Terminology
+//!
+//! - **Existential Deposit:** The existential deposit is the minimum balance required to create or keep an account open. This prevents "dust accounts" from filling storage.
+//! - **Stake:** The total amount of tokens in existence in a system.
+//! - **Reaping an account:** The act of removing an account by resetting its nonce, setting its balance to zero, and removing from storage.
+//! - **Free Balance:** The free balance is the only balance that matters for most operations. When this balance falls below the existential deposit, the account is reaped.
+//! - **Reserved Balance:** Reserved balance still belongs to the account holder, but is suspended. Reserved balance can still be slashed, but only after all of free balance has been slashed. If the reserved balance falls below the existential deposit then it will be deleted.
+//! - **Locks:** Locks enable the runtime to lock an account's balance until a specified block number. Only runtimes that implement the `LockableCurrency` trait allow this.
+//!
+//! ## Interface
+//!
+//! ### Types
+//!
+//! - Balance
+//! - OnFreeBalanceZero
+//! - OnNewAccount
+//! - Event
+//!
+//! These are [associated types](https://doc.rust-lang.org/book/ch19-03-advanced-traits.html#specifying-placeholder-types-in-trait-definitions-with-associated-types) and must be implemented in your `runtime/src/lib.rs`. For example:
+//!
+//! ```ignore
+//! impl balances::Trait for Runtime {
+//! 	/// The type for recording an account's balance.
+//! 	type Balance = u128;
+//! 	/// What to do if an account's free balance gets zeroed.
+//! 	type OnFreeBalanceZero = ();
+//! 	/// What to do if a new account is created.
+//! 	type OnNewAccount = Indices;
+//! 	/// The uniquitous event type.
+//! 	type Event = Event;
+//! }
+//! ```
+//!
+//! ### Dispatchable Functions
+//!
+//! The `Call` enum is documented here: https://crates.parity.io/srml_balances/enum.Call.html
+//!
+//! <!-- TODO: Add link to rust docs (https://github.com/paritytech/substrate-developer-hub/issues/24) -->
+//!
+//! - `transfer` - Transfer some liquid free balance to another staker.
+//! - `set_balance` - Set the balances of a given account. Only dispatchable by a user with root privileges.
+//!
+//! ### Public Functions
+//!
+//! <!-- TODO: Add link to rust docs (https://github.com/paritytech/substrate-developer-hub/issues/24) -->
+//!
+//! See the [module](https://crates.parity.io/srml_balances/struct.Module.html) for details on publicly available functions.
+//!
+//! **Note:** When using the publicly exposed functions, you (the runtime developer) are responsible for implementing any necessary checks (e.g. that the sender is the signer) before calling a function that will affect storage.
+//!
+//! ## Usage
+//!
+//! The following examples show how to use the balances module in your custom module.
+//!
+//! ### Import and Balance Transfer
+//!
+//! Import the `balances` module and derive your module configuration trait with the balances trait. You can now call functions from the module.
+//!
+//! ```ignore
+//! use support::{decl_module, dispatch::Result};
+//! use system::ensure_signed;
+//!
+//! pub trait Trait: balances::Trait {}
+//!
+//! decl_module! {
+//! 	pub struct Module<T: Trait> for enum Call where origin: T::Origin {
+//! 		fn transfer_proxy(origin, to: T::AccountId, value: T::Balance) -> Result {
+//! 			let sender = ensure_signed(origin)?;
+//! 			<balances::Module<T>>::make_transfer(&sender, &to, value)?;
+//!
+//! 			Ok(())
+//! 		}
+//! 	}
+//! }
+//! ```
+//!
+//! ### Real Use Example
+//!
+//! Use the `free_balance` function (from the `Currency` trait) in the `staking` module:
+//!
+//! ```ignore
+//! fn bond_extra(origin, max_additional: BalanceOf<T>) {
+//! 	let controller = ensure_signed(origin)?;
+//! 	let mut ledger = Self::ledger(&controller).ok_or("not a controller")?;
+//! 	let stash_balance = T::Currency::free_balance(&ledger.stash);
+//!
+//! 	if stash_balance > ledger.total {
+//! 		let extra = (stash_balance - ledger.total).min(max_additional);
+//! 		ledger.total += extra;
+//! 		ledger.active += extra;
+//! 		Self::update_ledger(&controller, ledger);
+//! 	}
+//! }
+//! ```
+//!
+//! ## Genesis config
+//!
+//! Configuration is in `<your-node-name>/src/chain_spec.rs`. The following storage items are configurable:
+//! 
+//! - `TotalIssuance`
+//! - `ExistentialDeposit`
+//! - `TransferFee`
+//! - `CreationFee`
+//! - `Vesting`
+//! - `FreeBalance`
+//!
+//! ## Related Modules
+//!
+//! The balances module depends on the [`system`](https://crates.parity.io/srml_system/index.html) and [`srml_support`](https://crates.parity.io/srml_support/index.html) modules as well as Substrate Core libraries and the Rust standard library.
 
 #![cfg_attr(not(feature = "std"), no_std)]
 
@@ -108,15 +226,15 @@ pub struct BalanceLock<Balance, BlockNumber> {
 
 decl_storage! {
 	trait Store for Module<T: Trait> as Balances {
-		/// The total amount of stake on the system.
+		/// The total amount of stake in the system.
 		pub TotalIssuance get(total_issuance) build(|config: &GenesisConfig<T>| {
 			config.balances.iter().fold(Zero::zero(), |acc: T::Balance, &(_, n)| acc + n)
 		}): T::Balance;
-		/// The minimum amount allowed to keep an account open.
+		/// The minimum amount required to keep an account open.
 		pub ExistentialDeposit get(existential_deposit) config(): T::Balance;
 		/// The fee required to make a transfer.
 		pub TransferFee get(transfer_fee) config(): T::Balance;
-		/// The fee required to create an account. At least as big as ReclaimRebate.
+		/// The fee required to create an account.
 		pub CreationFee get(creation_fee) config(): T::Balance;
 
 		/// Information regarding the vesting of a given account.
@@ -143,15 +261,18 @@ decl_storage! {
 
 		/// The 'free' balance of a given account.
 		///
-		/// This is the only balance that matters in terms of most operations on tokens. It is
-		/// alone used to determine the balance when in the contract execution environment. When this
+		/// This is the only balance that matters in terms of most operations on tokens. It
+		/// alone is used to determine the balance when in the contract execution environment. When this
 		/// balance falls below the value of `ExistentialDeposit`, then the 'current account' is
 		/// deleted: specifically `FreeBalance`. Furthermore, `OnFreeBalanceZero` callback
-		/// is invoked, giving a chance to external modules to cleanup data associated with
+		/// is invoked, giving a chance to external modules to clean up data associated with
 		/// the deleted account.
 		///
+		/// This is orthogonal to the `Bondage` value that an account has, a high value of which
+		/// makes even the `free_balance` unspendable.
+		///
 		/// `system::AccountNonce` is also deleted if `ReservedBalance` is also zero (it also gets
-		/// collapsed to zero if it ever becomes less than `ExistentialDeposit`.
+		/// collapsed to zero if it ever becomes less than `ExistentialDeposit`.)
 		pub FreeBalance get(free_balance) build(|config: &GenesisConfig<T>| config.balances.clone()): map T::AccountId => T::Balance;
 
 		/// The amount of the balance of a given account that is externally reserved; this can still get
@@ -165,7 +286,7 @@ decl_storage! {
 		/// is deleted: specifically, `ReservedBalance`.
 		///
 		/// `system::AccountNonce` is also deleted if `FreeBalance` is also zero (it also gets
-		/// collapsed to zero if it ever becomes less than `ExistentialDeposit`.
+		/// collapsed to zero if it ever becomes less than `ExistentialDeposit`.)
 		pub ReservedBalance get(reserved_balance): map T::AccountId => T::Balance;
 
 		/// Any liquidity locks on some account balances.
@@ -182,6 +303,13 @@ decl_module! {
 		fn deposit_event<T>() = default;
 
 		/// Transfer some liquid free balance to another staker.
+		///
+		/// `transfer` will set the `FreeBalance` of the sender and receiver.
+		/// It will decrease the total stake of the system by the `TransferFee`.
+		/// If the sender's account is below the existential deposit as a result
+		/// of the transfer, the account will be reaped.
+		///
+		/// The dispatch origin for this call must be `Signed` by the transactor.
 		pub fn transfer(
 			origin,
 			dest: <T::Lookup as StaticLookup>::Source,
@@ -193,6 +321,13 @@ decl_module! {
 		}
 
 		/// Set the balances of a given account.
+		///
+		/// This will alter `FreeBalance` and `ReservedBalance` in storage.
+		/// If the new free or reserved balance is below the existential deposit, 
+		/// it will also decrease the total stake of the system (`TotalIssuance`)
+		/// and reset the account nonce (`system::AccountNonce`).
+		///
+		/// The dispatch origin for this call is `root`.
 		fn set_balance(
 			who: <T::Lookup as StaticLookup>::Source,
 			#[compact] free: T::Balance,
@@ -205,7 +340,7 @@ decl_module! {
 	}
 }
 
-// For funding methods, see Currency trait
+// For funding methods, see `Currency` trait
 impl<T: Trait> Module<T> {
 
 	/// Get the amount that is currently being vested and cannot be transfered out of this account.
@@ -217,10 +352,11 @@ impl<T: Trait> Module<T> {
 		}
 	}
 
-	/// Set the free balance of an account to some new value.
+	/// Set the reserved balance of an account to some new value. Will enforce `ExistentialDeposit`
+	/// law, annulling the account as needed.
 	///
-	/// Will enforce ExistentialDeposit law, anulling the account as needed.
-	/// In that case it will return `AccountKilled`.
+	/// Doesn't do any preparatory work for creating a new account, so should only be used when it
+	/// is known that the account already exists.
 	pub fn set_reserved_balance(who: &T::AccountId, balance: T::Balance) -> UpdateBalanceOutcome {
 		if balance < Self::existential_deposit() {
 			<ReservedBalance<T>>::insert(who, balance);
@@ -232,15 +368,13 @@ impl<T: Trait> Module<T> {
 		}
 	}
 
-	/// Set the free balance of an account to some new value. Will enforce ExistentialDeposit
-	/// law anulling the account as needed.
+	/// Set the free balance of an account to some new value. Will enforce `ExistentialDeposit`
+	/// law, annulling the account as needed.
 	///
 	/// Doesn't do any preparatory work for creating a new account, so should only be used when it
 	/// is known that the account already exists.
-	///
-	/// Returns if the account was successfully updated or update has led to killing of the account.
 	pub fn set_free_balance(who: &T::AccountId, balance: T::Balance) -> UpdateBalanceOutcome {
-		// Commented out for no - but consider it instructive.
+		// Commented out for now - but consider it instructive.
 		// assert!(!Self::total_balance(who).is_zero());
 		if balance < Self::existential_deposit() {
 			<FreeBalance<T>>::insert(who, balance);
@@ -252,25 +386,16 @@ impl<T: Trait> Module<T> {
 		}
 	}
 
-	/// Set the free balance on an account to some new value.
+	/// Set the free balance on an account to some new value. Will enforce `ExistentialDeposit`
+	/// law, annulling the account as needed.
 	///
-	/// Same as [`set_free_balance`], but will create a new account.
+	/// Same as `set_free_balance`, but will create a new account.
 	///
-	/// Returns if the account was successfully updated or update has led to killing of the account.
+	/// # NOTES
 	///
-	/// [`set_free_balance`]: #method.set_free_balance
+	/// See documentation on `FreeBalance` and `ReservedBalance` storage items for their differences
 	pub fn set_free_balance_creating(who: &T::AccountId, balance: T::Balance) -> UpdateBalanceOutcome {
 		let ed = <Module<T>>::existential_deposit();
-		// If the balance is too low, then the account is reaped.
-		// NOTE: There are two balances for every account: `reserved_balance` and
-		// `free_balance`. This contract subsystem only cares about the latter: whenever
-		// the term "balance" is used *here* it should be assumed to mean "free balance"
-		// in the rest of the module.
-		// Free balance can never be less than ED. If that happens, it gets reduced to zero
-		// and the account information relevant to this subsystem is deleted (i.e. the
-		// account is reaped).
-		// NOTE: This is orthogonal to the `Bondage` value that an account has, a high
-		// value of which makes even the `free_balance` unspendable.
 		if balance < ed {
 			Self::set_free_balance(who, balance);
 			UpdateBalanceOutcome::AccountKilled
@@ -284,7 +409,14 @@ impl<T: Trait> Module<T> {
 		}
 	}
 
-	/// Transfer some liquid free balance to another staker.
+	/// Transfer some liquid free balance from one account to another.
+	///
+	/// Enforces `ExistentialDeposit` law, reaping the sender's account if its balance is
+	/// too low as a result of the transfer.
+	///
+	/// # NOTES
+	///
+	/// Will create a new account for the destination if the account does not exist.
 	pub fn make_transfer(transactor: &T::AccountId, dest: &T::AccountId, value: T::Balance) -> Result {
 		let from_balance = Self::free_balance(transactor);
 		let to_balance = Self::free_balance(dest);
@@ -327,6 +459,7 @@ impl<T: Trait> Module<T> {
 		Self::deposit_event(RawEvent::NewAccount(who.clone(), balance.clone()));
 	}
 
+	/// Remove an account whose balance is below the existential deposit.
 	fn reap_account(who: &T::AccountId) {
 		<system::AccountNonce<T>>::remove(who);
 		Self::deposit_event(RawEvent::ReapedAccount(who.clone()));
@@ -355,13 +488,14 @@ impl<T: Trait> Module<T> {
 		}
 	}
 
-	/// Increase TotalIssuance by Value.
+	/// Increase stake by `value`.
 	pub fn increase_total_stake_by(value: T::Balance) {
 		if let Some(v) = <Module<T>>::total_issuance().checked_add(&value) {
 			<TotalIssuance<T>>::put(v);
 		}
 	}
-	/// Decrease TotalIssuance by Value.
+
+	/// Decrease stake by `value`.
 	pub fn decrease_total_stake_by(value: T::Balance) {
 		if let Some(v) = <Module<T>>::total_issuance().checked_sub(&value) {
 			<TotalIssuance<T>>::put(v);

srml/contract/src/lib.rs

@@ -319,7 +319,7 @@ decl_event! {
 
 decl_storage! {
 	trait Store for Module<T: Trait> as Contract {
-		/// The fee required to create a contract. At least as big as staking's ReclaimRebate.
+		/// The fee required to create a contract.
 		ContractFee get(contract_fee) config(): T::Balance = T::Balance::sa(21);
 		/// The fee charged for a call into a contract.
 		CallBaseFee get(call_base_fee) config(): T::Gas = T::Gas::sa(135);