docs: x/bank: Atlas Doc (cosmos#7961)

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
+   $ <app> 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"
+           }
+       ]
+   }
+   ```

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"