<!DOCTYPE HTML>
<html lang="en" class="sidebar-visible no-js light">
<head>
<!-- Book generated using mdBook -->
<meta charset="UTF-8">
<title>Encrypted Balance - Zero Network Documentation</title>
<!-- Custom HTML head -->
<meta content="text/html; charset=utf-8" http-equiv="Content-Type">
<meta name="description" content="">
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta name="theme-color" content="#ffffff" />
<link rel="icon" href="favicon.svg">
<link rel="shortcut icon" href="favicon.png">
<link rel="stylesheet" href="css/variables.css">
<link rel="stylesheet" href="css/general.css">
<link rel="stylesheet" href="css/chrome.css">
<link rel="stylesheet" href="css/print.css" media="print">
<!-- Fonts -->
<link rel="stylesheet" href="FontAwesome/css/font-awesome.css">
<link rel="stylesheet" href="fonts/fonts.css">
<!-- Highlight.js Stylesheets -->
<link rel="stylesheet" href="highlight.css">
<link rel="stylesheet" href="tomorrow-night.css">
<link rel="stylesheet" href="ayu-highlight.css">
<!-- Custom theme stylesheets -->
<!-- MathJax -->
<script async src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
</head>
<body>
<!-- Provide site root to javascript -->
<script>
var path_to_root = "";
var default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? "navy" : "light";
</script>
<!-- Work around some values being stored in localStorage wrapped in quotes -->
<script>
try {
var theme = localStorage.getItem('mdbook-theme');
var sidebar = localStorage.getItem('mdbook-sidebar');
if (theme.startsWith('"') && theme.endsWith('"')) {
localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
}
if (sidebar.startsWith('"') && sidebar.endsWith('"')) {
localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
}
} catch (e) { }
</script>
<!-- Set the theme before any content is loaded, prevents flash -->
<script>
var theme;
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
if (theme === null || theme === undefined) { theme = default_theme; }
var html = document.querySelector('html');
html.classList.remove('no-js')
html.classList.remove('light')
html.classList.add(theme);
html.classList.add('js');
</script>
<!-- Hide / unhide sidebar before it is displayed -->
<script>
var html = document.querySelector('html');
var sidebar = 'hidden';
if (document.body.clientWidth >= 1080) {
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
sidebar = sidebar || 'visible';
}
html.classList.remove('sidebar-visible');
html.classList.add("sidebar-" + sidebar);
</script>
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
<div class="sidebar-scrollbox">
<ol class="chapter"><li class="chapter-item expanded "><a href="0_0_zero_network.html"><strong aria-hidden="true">1.</strong> Zero Network</a></li><li class="chapter-item expanded "><a href="1_0_overview.html"><strong aria-hidden="true">2.</strong> Overview</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="1_1_what_is_privacy.html"><strong aria-hidden="true">2.1.</strong> What is Privacy</a></li><li class="chapter-item expanded "><a href="1_2_hide_transfer_amount.html"><strong aria-hidden="true">2.2.</strong> Hide Transfer Amount</a></li><li class="chapter-item expanded "><a href="1_3_gas_limit.html"><strong aria-hidden="true">2.3.</strong> Gas Limit</a></li><li class="chapter-item expanded "><a href="1_4_zero_knowledge_scheme.html"><strong aria-hidden="true">2.4.</strong> Zero Knowledge Scheme</a></li><li class="chapter-item expanded "><a href="1_5_transaction_constraints.html"><strong aria-hidden="true">2.5.</strong> Transaction Constraints</a></li></ol></li><li class="chapter-item expanded "><a href="2_0_transaction_constraints.html"><strong aria-hidden="true">3.</strong> Transaction Constraints</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="2_1_confidential_transfer.html"><strong aria-hidden="true">3.1.</strong> Confidential Transfer</a></li><li class="chapter-item expanded "><a href="2_2_confidential_smart_contract.html"><strong aria-hidden="true">3.2.</strong> Confidential Smart Contract</a></li></ol></li><li class="chapter-item expanded "><a href="3_0_primitive.html"><strong aria-hidden="true">4.</strong> Primitive</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="3_1_crypto.html"><strong aria-hidden="true">4.1.</strong> Crypto</a></li><li class="chapter-item expanded "><a href="3_2_jubjub.html"><strong aria-hidden="true">4.2.</strong> Jubjub</a></li><li class="chapter-item expanded "><a href="3_3_bls12_381.html"><strong aria-hidden="true">4.3.</strong> Bls12 381</a></li><li class="chapter-item expanded "><a href="3_4_elgamal.html"><strong aria-hidden="true">4.4.</strong> ElGamal</a></li><li class="chapter-item expanded "><a href="3_5_pairing.html"><strong aria-hidden="true">4.5.</strong> Pairing</a></li></ol></li><li class="chapter-item expanded "><a href="4_0_pallet.html"><strong aria-hidden="true">5.</strong> Pallet</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="4_1_plonk.html"><strong aria-hidden="true">5.1.</strong> Plonk</a></li><li class="chapter-item expanded "><a href="4_2_encrypted_balance.html" class="active"><strong aria-hidden="true">5.2.</strong> Encrypted Balance</a></li><li class="chapter-item expanded "><a href="4_3_confidential_transfer.html"><strong aria-hidden="true">5.3.</strong> Confidential Transfer</a></li></ol></li><li class="chapter-item expanded "><a href="5_0_related_tools.html"><strong aria-hidden="true">6.</strong> Related Tools</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="5_1_stealth_address.html"><strong aria-hidden="true">6.1.</strong> Stealth Address</a></li><li class="chapter-item expanded "><a href="5_2_pedersen_commitment.html"><strong aria-hidden="true">6.2.</strong> Pedersen Commitment</a></li><li class="chapter-item expanded "><a href="5_3_non_interactive_zero_knowlege_proof.html"><strong aria-hidden="true">6.3.</strong> Non Interactive Zero Knowledge Proof</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="5_3_1_qap.html"><strong aria-hidden="true">6.3.1.</strong> QAP</a></li><li class="chapter-item expanded "><a href="5_3_2_polynomial_commitment.html"><strong aria-hidden="true">6.3.2.</strong> Polynomial Commitment</a></li><li class="chapter-item expanded "><a href="5_3_3_homomorphic_encryption.html"><strong aria-hidden="true">6.3.3.</strong> Homomorphic Encryption</a></li></ol></li></ol></li><li class="chapter-item expanded "><a href="6_0_tutorial.html"><strong aria-hidden="true">7.</strong> Tutorial</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="6_1_plonk_pallet.html"><strong aria-hidden="true">7.1.</strong> pallet-plonk</a></li><li class="chapter-item expanded "><a href="6_2_confidential_transfer.html"><strong aria-hidden="true">7.2.</strong> confidential_transfer</a></li></ol></li><li class="chapter-item expanded "><a href="7_0_frequent_errors.html"><strong aria-hidden="true">8.</strong> Frequent Errors</a></li></ol>
</div>
<div id="sidebar-resize-handle" class="sidebar-resize-handle"></div>
</nav>
<div id="page-wrapper" class="page-wrapper">
<div class="page">
<div id="menu-bar-hover-placeholder"></div>
<div id="menu-bar" class="menu-bar sticky bordered">
<div class="left-buttons">
<button id="sidebar-toggle" class="icon-button" type="button" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
<i class="fa fa-bars"></i>
</button>
<button id="theme-toggle" class="icon-button" type="button" title="Change theme" aria-label="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="theme-list">
<i class="fa fa-paint-brush"></i>
</button>
<ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu">
<li role="none"><button role="menuitem" class="theme" id="light">Light (default)</button></li>
<li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li>
<li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li>
<li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li>
<li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li>
</ul>
<button id="search-toggle" class="icon-button" type="button" title="Search. (Shortkey: s)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="S" aria-controls="searchbar">
<i class="fa fa-search"></i>
</button>
</div>
<h1 class="menu-title">Zero Network Documentation</h1>
<div class="right-buttons">
<a href="print.html" title="Print this book" aria-label="Print this book">
<i id="print-button" class="fa fa-print"></i>
</a>
</div>
</div>
<div id="search-wrapper" class="hidden">
<form id="searchbar-outer" class="searchbar-outer">
<input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
</form>
<div id="searchresults-outer" class="searchresults-outer hidden">
<div id="searchresults-header" class="searchresults-header"></div>
<ul id="searchresults">
</ul>
</div>
</div>
<!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
<script>
document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
});
</script>
<div id="content" class="content">
<main>
<h1 id="encrypted-balances-module"><a class="header" href="#encrypted-balances-module">Encrypted Balances Module</a></h1>
<p>The Balances module provides functionality for handling accounts and balances.</p>
<ul>
<li><a href="https://docs.rs/pallet-balances/latest/pallet_balances/trait.Trait.html"><code>balances::Trait</code></a></li>
<li><a href="https://docs.rs/pallet-balances/latest/pallet_balances/enum.Call.html"><code>Call</code></a></li>
<li><a href="https://docs.rs/pallet-balances/latest/pallet_balances/struct.Module.html"><code>Module</code></a></li>
</ul>
<h2 id="overview"><a class="header" href="#overview">Overview</a></h2>
<p>The Balances module provides functions for:</p>
<ul>
<li>Getting and setting free balances.</li>
<li>Retrieving total, reserved and unreserved balances.</li>
<li>Repatriating a reserved balance to a beneficiary account that exists.</li>
<li>Transferring a balance between accounts (when not reserved).</li>
<li>Slashing an account balance.</li>
<li>Account creation and removal.</li>
<li>Managing total issuance.</li>
<li>Setting and managing locks.</li>
</ul>
<h3 id="terminology"><a class="header" href="#terminology">Terminology</a></h3>
<ul>
<li>
<p><strong>Existential Deposit:</strong> The minimum balance required to create or keep an account open. This prevents
"dust accounts" from filling storage. When the free plus the reserved balance (i.e. the total balance)
fall below this, then the account is said to be dead; and it loses its functionality as well as any
prior history and all information on it is removed from the chain's state.
No account should ever have a total balance that is strictly between 0 and the existential
deposit (exclusive). If this ever happens, it indicates either a bug in this module or an
erroneous raw mutation of storage.</p>
</li>
<li>
<p><strong>Total Issuance:</strong> The total number of units in existence in a system.</p>
</li>
<li>
<p><strong>Reaping an account:</strong> The act of removing an account by resetting its nonce. Happens after its
total balance has become zero (or, strictly speaking, less than the Existential Deposit).</p>
</li>
<li>
<p><strong>Free Balance:</strong> The portion of a balance that is not reserved. The free balance is the only
balance that matters for most operations.</p>
</li>
<li>
<p><strong>Reserved Balance:</strong> Reserved balance still belongs to the account holder, but is suspended.
Reserved balance can still be slashed, but only after all the free balance has been slashed.</p>
</li>
<li>
<p><strong>Imbalance:</strong> A condition when some funds were credited or debited without equal and opposite accounting
(i.e. a difference between total issuance and account balances). Functions that result in an imbalance will
return an object of the <code>Imbalance</code> trait that can be managed within your runtime logic. (If an imbalance is
simply dropped, it should automatically maintain any book-keeping such as total issuance.)</p>
</li>
<li>
<p><strong>Lock:</strong> A freeze on a specified amount of an account's free balance until a specified block number. Multiple
locks always operate over the same funds, so they "overlay" rather than "stack".</p>
</li>
</ul>
<h3 id="implementations"><a class="header" href="#implementations">Implementations</a></h3>
<p>The Balances module provides implementations for the following traits. If these traits provide the functionality
that you need, then you can avoid coupling with the Balances module.</p>
<ul>
<li><a href="https://docs.rs/frame-support/latest/frame_support/traits/trait.Currency.html"><code>Currency</code></a>: Functions for dealing with a
fungible assets system.</li>
<li><a href="https://docs.rs/frame-support/latest/frame_support/traits/trait.ReservableCurrency.html"><code>ReservableCurrency</code></a>:
Functions for dealing with assets that can be reserved from an account.</li>
<li><a href="https://docs.rs/frame-support/latest/frame_support/traits/trait.LockableCurrency.html"><code>LockableCurrency</code></a>: Functions for
dealing with accounts that allow liquidity restrictions.</li>
<li><a href="https://docs.rs/frame-support/latest/frame_support/traits/trait.Imbalance.html"><code>Imbalance</code></a>: Functions for handling
imbalances between total issuance in the system and account balances. Must be used when a function
creates new funds (e.g. a reward) or destroys some funds (e.g. a system fee).</li>
<li><a href="https://docs.rs/frame-support/latest/frame_support/traits/trait.IsDeadAccount.html"><code>IsDeadAccount</code></a>: Determiner to say whether a
given account is unused.</li>
</ul>
<h2 id="interface"><a class="header" href="#interface">Interface</a></h2>
<h3 id="dispatchable-functions"><a class="header" href="#dispatchable-functions">Dispatchable Functions</a></h3>
<ul>
<li><code>transfer</code> - Transfer some liquid free balance to another account.</li>
<li><code>set_balance</code> - Set the balances of a given account. The origin of this call must be root.</li>
</ul>
<h2 id="usage"><a class="header" href="#usage">Usage</a></h2>
<p>The following examples show how to use the Balances module in your custom module.</p>
<h3 id="examples-from-the-frame"><a class="header" href="#examples-from-the-frame">Examples from the FRAME</a></h3>
<p>The Contract module uses the <code>Currency</code> trait to handle gas payment, and its types inherit from <code>Currency</code>:</p>
<pre><pre class="playground"><code class="language-rust"><span class="boring">#![allow(unused)]
</span><span class="boring">fn main() {
</span>use frame_support::traits::Currency;
pub type BalanceOf<T> = <<T as Config>::Currency as Currency<<T as frame_system::Config>::AccountId>>::Balance;
pub type NegativeImbalanceOf<T> = <<T as Config>::Currency as Currency<<T as frame_system::Config>::AccountId>>::NegativeImbalance;
<span class="boring">}</span></code></pre></pre>
<p>The Staking module uses the <code>LockableCurrency</code> trait to lock a stash account's funds:</p>
<pre><pre class="playground"><code class="language-rust"><span class="boring">#![allow(unused)]
</span><span class="boring">fn main() {
</span>use frame_support::traits::{WithdrawReasons, LockableCurrency};
use sp_runtime::traits::Bounded;
pub trait Config: frame_system::Config {
type Currency: LockableCurrency<Self::AccountId, Moment=Self::BlockNumber>;
}
fn update_ledger<T: Config>(
controller: &T::AccountId,
ledger: &StakingLedger<T>
) {
T::Currency::set_lock(
STAKING_ID,
&ledger.stash,
ledger.total,
WithdrawReasons::all()
);
// <Ledger<T>>::insert(controller, ledger); // Commented out as we don't have access to Staking's storage here.
}
<span class="boring">}</span></code></pre></pre>
<h2 id="genesis-config"><a class="header" href="#genesis-config">Genesis config</a></h2>
<p>The Balances module depends on the <a href="https://docs.rs/pallet-balances/latest/pallet_balances/struct.GenesisConfig.html"><code>GenesisConfig</code></a>.</p>
<h2 id="assumptions"><a class="header" href="#assumptions">Assumptions</a></h2>
<ul>
<li>Total issued balanced of all accounts should be less than <code>Config::Balance::max_value()</code>.</li>
</ul>
<p>License: Apache-2.0</p>
</main>
<nav class="nav-wrapper" aria-label="Page navigation">
<!-- Mobile navigation buttons -->
<a rel="prev" href="4_1_plonk.html" class="mobile-nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
<i class="fa fa-angle-left"></i>
</a>
<a rel="next" href="4_3_confidential_transfer.html" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
<i class="fa fa-angle-right"></i>
</a>
<div style="clear: both"></div>
</nav>
</div>
</div>
<nav class="nav-wide-wrapper" aria-label="Page navigation">
<a rel="prev" href="4_1_plonk.html" class="nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
<i class="fa fa-angle-left"></i>
</a>
<a rel="next" href="4_3_confidential_transfer.html" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
<i class="fa fa-angle-right"></i>
</a>
</nav>
</div>
<script>
window.playground_copyable = true;
</script>
<script src="elasticlunr.min.js" charset="utf-8"></script>
<script src="mark.min.js" charset="utf-8"></script>
<script src="searcher.js" charset="utf-8"></script>
<script src="clipboard.min.js" charset="utf-8"></script>
<script src="highlight.js" charset="utf-8"></script>
<script src="book.js" charset="utf-8"></script>
<!-- Custom JS scripts -->
</body>
</html>
