diff --git a/x/bank/atlas/atlas-v0.39.1.md b/x/bank/atlas/atlas-v0.39.1.md new file mode 100644 index 0000000000..ef34e02e00 --- /dev/null +++ b/x/bank/atlas/atlas-v0.39.1.md @@ -0,0 +1,208 @@ +# x/bank + +The `x/bank` module is responsible for handling multi-asset coin transfers between +accounts and tracking special-case pseudo-transfers which must work differently +with particular kinds of accounts. + +## Usage + +1. Import the module. + + ```go + import ( + "github.com/cosmos/cosmos-sdk/x/bank" + ) + ``` + +2. Add `AppModuleBasic` to your `ModuleBasics`. + + ```go + var ( + ModuleBasics = module.NewBasicManager( + // ... + bank.AppModuleBasic{}, + } + ) + ``` + +3. Create the module's parameter subspace in your application constructor. + + ```go + func NewApp(...) *App { + // ... + app.subspaces[bank.ModuleName] = app.ParamsKeeper.Subspace(bank.DefaultParamspace) + } + ``` + +4. Create the keeper. Note, the `x/bank` module depends on the `x/auth` module + and a list of blacklisted account addresses which funds are not allowed to be + sent to. Your application will need to define this method based your needs. + + ```go + func NewApp(...) *App { + // ... + app.BankKeeper = bank.NewBaseKeeper( + app.AccountKeeper, app.subspaces[bank.ModuleName], app.BlacklistedAccAddrs(), + ) + } + ``` + +5. Add the `x/bank` module to the app's `ModuleManager`. + + ```go + func NewApp(...) *App { + // ... + app.mm = module.NewManager( + // ... + bank.NewAppModule(app.BankKeeper, app.AccountKeeper), + // ... + ) + } + ``` + +6. Set the `x/bank` module genesis order. + + ```go + func NewApp(...) *App { + // ... + app.mm.SetOrderInitGenesis(..., bank.ModuleName, ...) + } + ``` + +7. Add the `x/bank` module to the simulation manager (if you have one set). + + ```go + func NewApp(...) *App { + // ... + app.sm = module.NewSimulationManager( + // ... + bank.NewAppModule(app.BankKeeper, app.AccountKeeper), + // ... + ) + } + +## Genesis + +The `x/bank` module defines its genesis state as follows: + +```go +type GenesisState struct { + SendEnabled bool `json:"send_enabled" yaml:"send_enabled"` +} +``` + +The `SendEnabled` parameter determines if transfers are enabled or disabled +entirely on the chain. This can be used to start a network without enabling +transfers while ensuring critical network functionality is operating as expected. + +## Messages + +### `MsgSend` + +The `x/bank` module allows for transfer of funds from a source account to a +destination account. + +```go +type MsgSend struct { + FromAddress sdk.AccAddress `json:"from_address" yaml:"from_address"` + ToAddress sdk.AccAddress `json:"to_address" yaml:"to_address"` + Amount sdk.Coins `json:"amount" yaml:"amount"` +} +``` + +### `MsgMultiSend` + +The `x/bank` module also allows for multiple inputs and outputs. The sum of all +inputs must be equivalent to the sum of all outputs. + +```go +type Input struct { + Address sdk.AccAddress `json:"address" yaml:"address"` + Coins sdk.Coins `json:"coins" yaml:"coins"` +} + +type Output struct { + Address sdk.AccAddress `json:"address" yaml:"address"` + Coins sdk.Coins `json:"coins" yaml:"coins"` +} + +type MsgMultiSend struct { + Inputs []Input `json:"inputs" yaml:"inputs"` + Outputs []Output `json:"outputs" yaml:"outputs"` +} +``` + +## Client + +### CLI + +The `x/bank` supports the following transactional commands. + +1. Send tokens via a `MsgSend` message. + + ```shell + $ tx send [from_key_or_address] [to_address] [amount] [...flags] + ``` + +Note, the `x/bank` module does not natively support constructing a `MsgMultiSend` +message. This type of message must be constructed manually, but it may be signed +and broadcasted via the CLI. + +### REST + +The `x/bank` supports various query API endpoints and a `MsgSend` construction +endpoint. + +1. Construct an unsigned `MsgSend` transaction. + + | Method | Path | + | :----- | :----------------------- | + | `POST` | `/bank/accounts/{address}/transfers` | + + Sample payload: + + ```json + { + "base_req": { + "chain_id": "chain-foo", + "from": "cosmos1u3fneykx9carelvurc6av22vpjvptytj9wklk0", + "memo": "memo", + "fees": [ + { + "denom": "stake", + "amount": "25000" + } + ] + }, + "amount": [ + { + "denom": "stake", + "amount": "400000000" + } + ] + } + ``` + +2. Query for an account's balance. + + | Method | Path | + | :----- | :----------------------- | + | `GET` | `/bank/balances/{address}` | + + Sample response: + + ```json + { + "height": "0", + "result": [ + { + "denom": "node0token", + "amount": "1000000000" + }, + { + "denom": "stake", + "amount": "400000000" + } + ] + } + ``` diff --git a/x/bank/atlas/atlas.toml b/x/bank/atlas/atlas.toml new file mode 100644 index 0000000000..f10863e30b --- /dev/null +++ b/x/bank/atlas/atlas.toml @@ -0,0 +1,34 @@ +[module] +description = "The bank module is responsible for handling multi-asset coin transfers between accounts and tracking special-case pseudo-transfers which must work differently with particular kinds of accounts." +homepage = "https://github.com/cosmos/cosmos-sdk" +keywords = [ + "tokens", + "bank", + "transfer", + "asset", + "fungible", + "coins", +] + +name = "x/bank" + +[bug_tracker] +url = "https://github.com/cosmos/cosmos-sdk/issues" + +[[authors]] +name = "alexanderbez" + +[[authors]] +name = "fedekunze" + +[[authors]] +name = "cwgoes" + +[[authors]] +name = "alessio" + +[version] +documentation = "https://raw.githubusercontent.com/cosmos/cosmos-sdk/master/x/bank/atlas/atlas-v0.39.1.md" +repo = "https://github.com/cosmos/cosmos-sdk/releases/tag/v0.39.1" +sdk_compat = "v0.39.x" +version = "v0.39.1"