diff --git a/docs/architecture/03-token_economics.md b/docs/architecture/03-token_economics.md index e69de29bb..cafe1f68c 100644 --- a/docs/architecture/03-token_economics.md +++ b/docs/architecture/03-token_economics.md @@ -0,0 +1,43 @@ +# Token Economics + +BNB remains the main utility token on Greenfield. + +BNB can be transferred from BSC to Greenfield blockchain, and vice versa. It is used as: + +- Staking token. It can be used to self-delegate and delegate as stake, which can earn gas rewards and may suffer slash for improper behaviors. +- Gas token. It can be used to pay the gas to submit transactions on the Greenfield blockchain, which includes Greenfield local transactions or + cross-chain transactions between Greenfield and BSC. This is charged at the time of transaction submission and dispatched to + Greenfield validators, and potentially Greenfield Storage Providers for some transactions. Fee distribution is done in-protocol and + a protocol specification is [described here](https://github.com/bnb-chain/greenfield-cosmos-sdk/blob/master/docs/spec/fee_distribution/f1_fee_distr.pdf). +- Storage service fee token. It can be used to pay fees for the object storage and download bandwidth data package. This is charged + as time goes on and dispatched to Greenfield Storage Providers. +- Governance token. BNB holders may govern the Greenfield by voting on proposals with their staked BNB (not day 1). + +No initial donors, foundation, or company will get funds in the genesis setup. + +## Genesis Setup +BNB is transferred from BSC to Greenfield as the first cross-chain action. The initial validator set and storage provider +of Greenfield at the genesis will first lock a certain amount of BNB into the "Greenfield Token Hub" contract on BSC. This contract +is used as part of the native bridge for BNB transferring after the genesis. These initial locked BNB will be used as +the self-stake of validators, the deposit of storage provider and early days gas fees. + +The initial BNB allocation on greenfield is around 1M BNB. (TODO: not finalized) + +## Circulation Model +There is no inflation of BNB in greenfield. Due to the dual chain structure, cross chain transfer is implemented to +enable BNB flow between Greenfield and Smart Chain bi-directionally. The total circulation of BNB on Greenfield is volatile. + +Greenfield use Lock/Unlock mechanism to ensure the total circulation of BNB on both chain is always less than the initial +total supply: +1. The transfer-out blockchain will lock the amount from source owner addresses into a module account or smart contract. +2. The transfer-in blockchain will unlock the amount from module account or contract and send it to target addresses. +3. Both networks will never mint BNB. + +Refer to [cross chain model](./07-cross-chain.md) to get more details about the mechanism. + +## How to Participate in the Ecosystem +- [Become A Validator](../tutorial/09-validator-staking.md): validators secure the Greenfield by validating and relaying transactions, + proposing, verifying and finalizing blocks. +- [Become A Storage Provider](../tutorial/07-storage-provider.md): SPs store the objects' real data, i.e. the payload data. and get paid + by providing storage services. +- [Store/Manage Data](../tutorial/06-storage.md): store and manage your data in a decentralized way, control and own it all by yourself. diff --git a/docs/tutorial/05-bank.md b/docs/tutorial/05-bank.md index e69de29bb..1fe2274ec 100644 --- a/docs/tutorial/05-bank.md +++ b/docs/tutorial/05-bank.md @@ -0,0 +1,151 @@ +# Using gnfd command to interact with bank module + +## Abstract +The bank module is responsible for handling BNB transfers between +accounts and module accounts. + +In addition, the bank module tracks and provides query support for the total +supply of BNB in the application. + +## Quick Start + +``` +## Start a local cluster +$ bash ./deployment/localup/localup.sh all 3 +$ alias gnfd="./build/bin/gnfd" +$ receiver=0x32Ff14Fa1547314b95991976DB432F9Aa648A423 +## query the balance of receiver +$ gnfd q bank balances $receiver --node tcp://127.0.0.1:26750 +## send 500bnb to the receiver (note the decimal of BNB is 18) +$ gnfd tx bank send validator0 $receiver 500bnb --home ./deployment/localup/.local/validator0 --keyring-backend test --node http://localhost:26750 -b block -y +## query the balance of receiver again +$ gnfd q bank balances $receiver --node tcp://127.0.0.1:26750 +## try send some token that does not exit, error is expected. +$ gnfd tx bank send validator0 $receiver 500bnb --home ./deployment/localup/.local/validator0 --keyring-backend test --node http://localhost:26750 -b block -y +## try multi send, send each 500bnb to both receiver and receiver2 +$ receiver2=0x6d6247501b822fd4eaa76fcb64baea360279497f +$ gnfd tx bank multi-send validator0 $receiver $receiver2 500bnb --home ./deployment/localup/.local/validator0 --keyring-backend test --node http://localhost:26750 -b block -y --gas 500000 +## query the metadata of BNB +$ gnfd q bank denom-metadata --node tcp://127.0.0.1:26750 +## query the total supply of BNB +$ gnfd q bank total --denom bnb --node tcp://127.0.0.1:26750 +``` + +## Detailed CLI + +A user can query and interact with the `bank` module using the CLI. + +### Query + +The `query` commands allow users to query `bank` state. + +```sh +gnfd query bank --help +``` + +#### balances + +The `balances` command allows users to query account balances by address. + +```sh +gnfd query bank balances [address] [flags] +``` + +Example: + +```sh +gnfd query bank balances bnb.. +``` + +Example Output: + +```yml +balances: +- amount: "1000000000" + denom: bnb +pagination: + next_key: null + total: "0" +``` + +#### denom-metadata + +The `denom-metadata` command allows users to query metadata for coin denominations. A user can query metadata for a single denomination using the `--denom` flag or all denominations without it. + +```sh +gnfd query bank denom-metadata [flags] +``` + +Example: + +```sh +gnfd query bank denom-metadata --denom bnb +``` + +Example Output: + +```yml +metadatas: + - base: wei + denom_units: + - aliases: + - ether + denom: weibnb + exponent: 0 + - aliases: + - gwei + denom: gweibnb + exponent: 9 + - aliases: [] + denom: bnb + exponent: 18 + description: The native staking token of the Greenfield. + display: bnb + name: "" + symbol: "" + uri: "" + uri_hash: "" +``` + +#### total + +The `total` command allows users to query the total supply of coins. A user can query the total supply for a single coin using the `--denom` flag or all coins without it. + +```sh +gnfd query bank total [flags] +``` + +Example: + +```sh +gnfd query bank total --denom bnb +``` + +Example Output: + +```yml +amount: "1000000000000000800000000000" +denom: bnb +``` + +### Transactions + +The `tx` commands allow users to interact with the `bank` module. + +```sh +gnfd tx bank --help +``` + +#### send + +The `send` command allows users to send funds from one account to another. + +```sh +gnfd tx bank send [from_key_or_address] [to_address] [amount] [flags] +``` + +Example: + +```sh +gnfd tx bank send addr1.. addr2.. 100bnb +``` \ No newline at end of file