From 10f846217d9e573ff5b192e365d71219f6dce403 Mon Sep 17 00:00:00 2001 From: Aleksandr Bezobchuk Date: Thu, 10 Dec 2020 10:40:42 -0500 Subject: [PATCH] atlas: x/auth v0.39.1 (#7996) --- x/auth/atlas/atlas-v0.39.1.md | 194 ++++++++++++++++++++++++++++++++++ x/auth/atlas/atlas.toml | 33 ++++++ 2 files changed, 227 insertions(+) create mode 100644 x/auth/atlas/atlas-v0.39.1.md create mode 100644 x/auth/atlas/atlas.toml diff --git a/x/auth/atlas/atlas-v0.39.1.md b/x/auth/atlas/atlas-v0.39.1.md new file mode 100644 index 000000000..ad6fa5355 --- /dev/null +++ b/x/auth/atlas/atlas-v0.39.1.md @@ -0,0 +1,194 @@ +# x/auth + +The `x/auth` module is responsible for specifying the base transaction and +account types for an application, as well as AnteHandler and authentication logic. + +## Usage + +1. Import the module. + + ```go + import ( + "github.com/cosmos/cosmos-sdk/x/auth" + ) + ``` + +2. Add `AppModuleBasic` to your `ModuleBasics`. + + ```go + var ( + ModuleBasics = module.NewBasicManager( + // ... + auth.AppModuleBasic{}, + } + ) + ``` + +3. Create the module's parameter subspace in your application constructor. + + ```go + func NewApp(...) *App { + // ... + app.subspaces[auth.ModuleName] = app.ParamsKeeper.Subspace(auth.DefaultParamspace) + } + ``` + +4. Create the keeper. + + ```go + func NewApp(...) *App { + // ... + app.AccountKeeper = auth.NewAccountKeeper( + app.cdc, keys[auth.StoreKey], app.subspaces[auth.ModuleName], auth.ProtoBaseAccount, + ) + } + ``` + +5. Add the `x/auth` module to the app's `ModuleManager`. + + ```go + func NewApp(...) *App { + // ... + app.mm = module.NewManager( + // ... + auth.NewAppModule(app.AccountKeeper), + // ... + ) + } + ``` + +6. Set the `x/auth` module genesis order. + + ```go + func NewApp(...) *App { + // ... + app.mm.SetOrderInitGenesis(..., auth.ModuleName, ...) + } + ``` + +7. Add the `x/auth` module to the simulation manager (if you have one set). + + ```go + func NewApp(...) *App { + // ... + app.sm = module.NewSimulationManager( + // ... + auth.NewAppModule(app.AccountKeeper), + // ... + ) + } + +8. Set the `AnteHandler` if you're using the default provided by `x/auth`. Note, +the default `AnteHandler` provided by the `x/auth` module depends on the `x/supply` +module. + + ```go + func NewApp(...) *App { + app.SetAnteHandler(ante.NewAnteHandler( + app.AccountKeeper, + app.SupplyKeeper, + auth.DefaultSigVerificationGasConsumer, + )) + } + ``` + +### Vesting Accounts + +The `x/auth` modules also defines a few standard vesting account types under the +`vesting` sub-package. In order to get your application to automatically support +these in terms of encoding and decoding, you must register the types with your +application Amino codec. + +Where ever you define the application `Codec`, be sure to register types via: + +```go +import ( + "github.com/cosmos/cosmos-sdk/x/auth/vesting" +) + +func MakeCodec() *codec.Codec { + var cdc = codec.New() + + // ... + vesting.RegisterCodec(cdc) + // ... + + return cdc +} +``` + +## Genesis + +The `x/auth` module defines its genesis state as follows: + +```go +type GenesisState struct { + Params Params `json:"params" yaml:"params"` + Accounts exported.GenesisAccounts `json:"accounts" yaml:"accounts"` +} +``` + +Which relies on the following types: + +```go +type Account interface { + GetAddress() sdk.AccAddress + SetAddress(sdk.AccAddress) error + GetPubKey() crypto.PubKey + SetPubKey(crypto.PubKey) error + GetAccountNumber() uint64 + SetAccountNumber(uint64) error + GetSequence() uint64 + SetSequence(uint64) error + GetCoins() sdk.Coins + SetCoins(sdk.Coins) error + SpendableCoins(blockTime time.Time) sdk.Coins + String() string +} + +type Params struct { + MaxMemoCharacters uint64 `json:"max_memo_characters" yaml:"max_memo_characters"` + TxSigLimit uint64 `json:"tx_sig_limit" yaml:"tx_sig_limit"` + TxSizeCostPerByte uint64 `json:"tx_size_cost_per_byte" yaml:"tx_size_cost_per_byte"` + SigVerifyCostED25519 uint64 `json:"sig_verify_cost_ed25519" yaml:"sig_verify_cost_ed25519"` + SigVerifyCostSecp256k1 uint64 `json:"sig_verify_cost_secp256k1" yaml:"sig_verify_cost_secp256k1"` +} +``` + +## Client + +### CLI + +The `x/auth` module provides various auxiliary CLI commands and a few that are +part of the module itself via the `ModuleManager`. The commands that are part of +the module itself are defined below: + +1. Query an account. + + ```shell + $ q auth account [address] [...flags] + ``` + +2. Sign an unsigned transaction using a single signature. + + ```shell + $ tx auth sign [file] + ``` + +3. Sign an unsigned transaction using a multisig. + + ```shell + $ tx auth multisign [file] [name] [[signature]...] + ``` + +### REST + +The `x/auth` module provides various auxiliary REST handlers and a few that are +part of the module itself via the `ModuleManager`. The endpoints that are part of +the module itself are defined below: + +1. Query an account. + + | Method | Path | + | :----- | :----------------------- | + | `GET` | `/auth/accounts/{address}` | diff --git a/x/auth/atlas/atlas.toml b/x/auth/atlas/atlas.toml new file mode 100644 index 000000000..ef59a18e7 --- /dev/null +++ b/x/auth/atlas/atlas.toml @@ -0,0 +1,33 @@ +[module] +description = "The auth module is responsible for specifying the base transaction and account types for an application, as well as AnteHandler and authentication logic." +homepage = "https://github.com/cosmos/cosmos-sdk" +keywords = [ + "authentication", + "signatures", + "ante", + "transactions", + "accounts", +] + +name = "x/auth" + +[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/auth/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"