`auth`

摘要

本文檔指定了 auth(授權) 模塊。

auth 模塊負責指定應用程序的基本交易和帳戶類型，因為 SDK 本身對這些細節是不可知的。它包含 ante 處理程序，其中執行所有基本交易有效性檢查（簽名、隨機數、輔助字段），並公開 account keeper，允許其他模塊讀取、寫入和修改賬戶。

概念

Gas(气体) & Fees（手续费）

對於網絡運營商來說，費用有兩個目的。

手续费限制了每個完整節點存儲的狀態的增長，並允許對經濟價值很小的交易進行通用審查。手续费最適合作為反垃圾郵件機制，其中驗證者對網絡的使用和用戶身份不感興趣。

手续费由交易提供的 gas 限額和 gas 價格決定，其中

fees = ceil(gasLimit * gasPrices)。

Txs 會為所有狀態讀/寫、簽名驗證以及與 tx 大小成比例的成本產生 gas 成本。運營商應在啟動節點時設置最低 gas 價格。他們必須在他們希望支持的每個代幣面額中設置 gas 的單位成本：

`stcd start ... --minimum-gas-prices=5000000000dst`

在將交易添加到mempool或gossipping交易時，驗證器會檢查交易的gas價格（由提供的手续费確定）是否滿足驗證器的最低gas價格。換句話說，交易必須提供至少一種與驗證器的最低gas價格相匹配的幣種的費用。

Tendermint 目前不提供基於手续费的內存池優先級排序，並且基於手续费的內存池過濾是節點本地的，而不是共識的一部分。但是在設置最低 gas 價格的情況下，這種機制可以由節點運營商實施。

由於代幣的市場價值會波動，因此預計驗證器會動態地將其最低汽油價格調整到鼓勵使用網絡的水平。

狀態

帳戶

帳戶包含 SDK 區塊鏈唯一標識的外部用戶的身份驗證信息，包括公鑰、地址和用於重放保護的帳號/序列號。為了提高效率，由於還必須獲取帳戶餘額以支付費用，因此帳戶結構還將用戶的餘額存儲為“sdk.Coins”。

賬戶作為接口對外公開，並在內部存儲為基本賬戶或歸屬賬戶。希望添加更多帳戶類型的模塊客戶可以這樣做。

0x01 | Address -> ProtocolBuffer(account)

賬戶接口

帳戶接口公開了讀取和寫入標準帳戶信息的方法。請注意，所有這些方法都在確認接口的帳戶結構上運行 - 為了將帳戶寫入存储，需要使用account keeper。

// AccountI 是一個接口，用於在狀態內的給定地址存儲代幣。
// 它假定用於重播保護的序列號概念，用於先前修剪帳戶的重播保護的帳號概念，以及用於身份驗證目的的公鑰。
// 在實現 AccountI 的具體結構中可以使用許多複雜的條件。
type AccountI interface {
    proto.Message

    GetAddress() sdk.AccAddress
    SetAddress(sdk.AccAddress) error // errors if already set.

    GetPubKey() crypto.PubKey // can return nil.
    SetPubKey(crypto.PubKey) error

    GetAccountNumber() uint64
    SetAccountNumber(uint64) error

    GetSequence() uint64
    SetSequence(uint64) error

    // Ensure that account implements stringer
    String() string
}

Base Account

基本賬戶是最簡單和最常見的賬戶類型，它只存儲所有必需的直接在結構中的字段。

// BaseAccount defines a base account type. It contains all the necessary fields
// for basic account functionality. Any custom account type should extend this
// type for additional functionality (e.g. vesting).
message BaseAccount {
  string address = 1;
  google.protobuf.Any pub_key = 2;
  uint64 account_number = 3;
  uint64 sequence       = 4;
}

AnteHandlers

x/auth 模塊目前沒有自己的交易處理程序，但確實暴露了特殊的 AnteHandler，用於對交易執行基本的有效性檢查，這樣它就可以被拋出內存池。 AnteHandler 可以看作是一組裝飾器，用於檢查當前上下文中的事務 , 可见 ADR 010.

請注意，在 CheckTx 和 DeliverTx 上都會調用 AnteHandler，因為 Tendermint 提議者目前有能力將失敗的 CheckTx 包含在他們提議的區塊交易中。

裝飾器

The auth module provides AnteDecorators that are recursively chained together into a single AnteHandler in the following order:

SetUpContextDecorator: 在 Context 中設置 GasMeter 並用 defer 子句包裝下一個 AnteHandler 以從 AnteHandler 鏈中的任何下文 OutOfGas panic中恢復，以返回錯誤以及有關提供的gas和使用的gas的信息。
RejectExtensionOptionsDecorator: 拒絕所有可以選擇性地包含在 protobuf 事務中的擴展選項。
MempoolFeeDecorator: 在 CheckTx 期間檢查 tx 費用是否高於本地內存池 minFee 參數。
ValidateBasicDecorator: 調用 tx.ValidateBasic 並返回任何非nil錯誤。
TxTimeoutHeightDecorator: 檢查“tx”高度超時。
ValidateMemoDecorator: 使用應用程序參數驗證“tx”備忘錄並返回任何非nil錯誤。
ConsumeGasTxSizeDecorator: 根據應用程序參數消耗與“tx”大小成比例的gas。
DeductFeeDecorator: 從 tx 的第一個簽名者那裡扣除 FeeAmount。如果啟用了 x/feegrant 模塊並設置了費用授予者，它將從費用授予者帳戶中扣除費用。
SetPubKeyDecorator: 從尚未在狀態機和當前上下文中保存相應公鑰的“tx”簽名者設置公鑰。
ValidateSigCountDecorator: 根據應用程序參數驗證 tx 中的簽名數量。
SigGasConsumeDecorator: 為每個簽名消耗參數定義的gas量。這需要在上下文中為所有簽名者設置公鑰作為 SetPubKeyDecorator 的一部分。
SigVerificationDecorator: 驗證所有簽名是否有效。這需要在上下文中為所有簽名者設置公鑰作為 SetPubKeyDecorator 的一部分。
IncrementSequenceDecorator: 增加每個簽名者的帳戶序列以防止重放攻擊。

Keepers

auth模塊只暴露了一個keeper，即account keeper，可以用來讀寫account。

Account Keeper

目前只有一個完全權限的賬戶管理員被公開，它有能力讀寫所有賬戶的所有字段，並迭代所有存儲的賬戶。

// AccountKeeperI is the interface contract that x/auth's keeper implements.
type AccountKeeperI interface {
    // Return a new account with the next account number and the specified address. Does not save the new account to the store.
    NewAccountWithAddress(sdk.Context, sdk.AccAddress) types.AccountI

    // Return a new account with the next account number. Does not save the new account to the store.
    NewAccount(sdk.Context, types.AccountI) types.AccountI

    // Check if an account exists in the store.
    HasAccount(sdk.Context, sdk.AccAddress) bool

    // Retrieve an account from the store.
    GetAccount(sdk.Context, sdk.AccAddress) types.AccountI

    // Set an account in the store.
    SetAccount(sdk.Context, types.AccountI)

    // Remove an account from the store.
    RemoveAccount(sdk.Context, types.AccountI)

    // Iterate over all accounts, calling the provided function. Stop iteration when it returns true.
    IterateAccounts(sdk.Context, func(types.AccountI) bool)

    // Fetch the public key of an account at a specified address
    GetPubKey(sdk.Context, sdk.AccAddress) (crypto.PubKey, error)

    // Fetch the sequence of an account at a specified address.
    GetSequence(sdk.Context, sdk.AccAddress) (uint64, error)

    // Fetch the next account number, and increment the internal counter.
    GetNextAccountNumber(sdk.Context) uint64
}

Client

Auth

CLI

用戶可以使用 CLI 查詢“auth”模塊並與之交互。

Query

query 命令允許用戶查詢 auth 狀態。

stcd query auth --help

account

account 命令允許用戶通過地址查詢帳戶。

stcd query auth account [address] [flags]

例子:

simd query auth account cosmos1...

示例輸出:

'@type': /cosmos.auth.v1beta1.BaseAccount
account_number: "0"
address: cosmos1zwg6tpl8aw4rawv8sgag9086lpw5hv33u5ctr2
pub_key:
  '@type': /cosmos.crypto.secp256k1.PubKey
  key: ApDrE38zZdd7wLmFS9YmqO684y5DG6fjZ4rVeihF/AQD
sequence: "1"

accounts

accounts 命令允許用戶查詢所有可用的帳戶。

stcd query auth accounts [flags]

例子:

stcd query auth accounts

示例輸出:

accounts:
- '@type': /cosmos.auth.v1beta1.BaseAccount
  account_number: "0"
  address: cosmos1zwg6tpl8aw4rawv8sgag9086lpw5hv33u5ctr2
  pub_key:
    '@type': /cosmos.crypto.secp256k1.PubKey
    key: ApDrE38zZdd7wLmFS9YmqO684y5DG6fjZ4rVeihF/AQD
  sequence: "1"
- '@type': /cosmos.auth.v1beta1.ModuleAccount
  base_account:
    account_number: "8"
    address: cosmos1yl6hdjhmkf37639730gffanpzndzdpmhwlkfhr
    pub_key: null
    sequence: "0"
  name: transfer
  permissions:
  - minter
  - burner
- '@type': /cosmos.auth.v1beta1.ModuleAccount
  base_account:
    account_number: "4"
    address: cosmos1fl48vsnmsdzcv85q5d2q4z5ajdha8yu34mf0eh
    pub_key: null
    sequence: "0"
  name: bonded_tokens_pool
  permissions:
  - burner
  - staking
- '@type': /cosmos.auth.v1beta1.ModuleAccount
  base_account:
    account_number: "5"
    address: cosmos1tygms3xhhs3yv487phx3dw4a95jn7t7lpm470r
    pub_key: null
    sequence: "0"
  name: not_bonded_tokens_pool
  permissions:
  - burner
  - staking
- '@type': /cosmos.auth.v1beta1.ModuleAccount
  base_account:
    account_number: "6"
    address: cosmos10d07y265gmmuvt4z0w9aw880jnsr700j6zn9kn
    pub_key: null
    sequence: "0"
  name: gov
  permissions:
  - burner
- '@type': /cosmos.auth.v1beta1.ModuleAccount
  base_account:
    account_number: "3"
    address: cosmos1jv65s3grqf6v6jl3dp4t6c9t9rk99cd88lyufl
    pub_key: null
    sequence: "0"
  name: distribution
  permissions: []
- '@type': /cosmos.auth.v1beta1.BaseAccount
  account_number: "1"
  address: cosmos147k3r7v2tvwqhcmaxcfql7j8rmkrlsemxshd3j
  pub_key: null
  sequence: "0"
- '@type': /cosmos.auth.v1beta1.ModuleAccount
  base_account:
    account_number: "7"
    address: cosmos1m3h30wlvsf8llruxtpukdvsy0km2kum8g38c8q
    pub_key: null
    sequence: "0"
  name: mint
  permissions:
  - minter
- '@type': /cosmos.auth.v1beta1.ModuleAccount
  base_account:
    account_number: "2"
    address: cosmos17xpfvakm2amg962yls6f84z3kell8c5lserqta
    pub_key: null
    sequence: "0"
  name: fee_collector
  permissions: []
pagination:
  next_key: null
  total: "0"

params(參數)

params 命令允許用戶查詢當前的授權參數。

stcd query auth params [flags]

例子:

stcd query auth params

示例輸出:

max_memo_characters: "256"
sig_verify_cost_ed25519: "590"
sig_verify_cost_secp256k1: "1000"
tx_sig_limit: "7"
tx_size_cost_per_byte: "10"

gRPC

用戶可以使用 gRPC 端點查詢“auth”模塊。

Account

account 端點允許用戶通過地址查詢帳戶。

cosmos.auth.v1beta1.Query/Account

例子:

grpcurl -plaintext \
    -d '{"address":"cosmos1.."}' \
    localhost:9090 \
    cosmos.auth.v1beta1.Query/Account

示例輸出:

{
  "account":{
    "@type":"/cosmos.auth.v1beta1.BaseAccount",
    "address":"cosmos1zwg6tpl8aw4rawv8sgag9086lpw5hv33u5ctr2",
    "pubKey":{
      "@type":"/cosmos.crypto.secp256k1.PubKey",
      "key":"ApDrE38zZdd7wLmFS9YmqO684y5DG6fjZ4rVeihF/AQD"
    },
    "sequence":"1"
  }
}

Accounts

accounts 端點允許用戶查詢所有可用的帳戶。

cosmos.auth.v1beta1.Query/Accounts

例子:

grpcurl -plaintext \
    localhost:9090 \
    cosmos.auth.v1beta1.Query/Accounts

示例輸出:

{
   "accounts":[
      {
         "@type":"/cosmos.auth.v1beta1.BaseAccount",
         "address":"cosmos1zwg6tpl8aw4rawv8sgag9086lpw5hv33u5ctr2",
         "pubKey":{
            "@type":"/cosmos.crypto.secp256k1.PubKey",
            "key":"ApDrE38zZdd7wLmFS9YmqO684y5DG6fjZ4rVeihF/AQD"
         },
         "sequence":"1"
      },
      {
         "@type":"/cosmos.auth.v1beta1.ModuleAccount",
         "baseAccount":{
            "address":"cosmos1yl6hdjhmkf37639730gffanpzndzdpmhwlkfhr",
            "accountNumber":"8"
         },
         "name":"transfer",
         "permissions":[
            "minter",
            "burner"
         ]
      },
      {
         "@type":"/cosmos.auth.v1beta1.ModuleAccount",
         "baseAccount":{
            "address":"cosmos1fl48vsnmsdzcv85q5d2q4z5ajdha8yu34mf0eh",
            "accountNumber":"4"
         },
         "name":"bonded_tokens_pool",
         "permissions":[
            "burner",
            "staking"
         ]
      },
      {
         "@type":"/cosmos.auth.v1beta1.ModuleAccount",
         "baseAccount":{
            "address":"cosmos1tygms3xhhs3yv487phx3dw4a95jn7t7lpm470r",
            "accountNumber":"5"
         },
         "name":"not_bonded_tokens_pool",
         "permissions":[
            "burner",
            "staking"
         ]
      },
      {
         "@type":"/cosmos.auth.v1beta1.ModuleAccount",
         "baseAccount":{
            "address":"cosmos10d07y265gmmuvt4z0w9aw880jnsr700j6zn9kn",
            "accountNumber":"6"
         },
         "name":"gov",
         "permissions":[
            "burner"
         ]
      },
      {
         "@type":"/cosmos.auth.v1beta1.ModuleAccount",
         "baseAccount":{
            "address":"cosmos1jv65s3grqf6v6jl3dp4t6c9t9rk99cd88lyufl",
            "accountNumber":"3"
         },
         "name":"distribution"
      },
      {
         "@type":"/cosmos.auth.v1beta1.BaseAccount",
         "accountNumber":"1",
         "address":"cosmos147k3r7v2tvwqhcmaxcfql7j8rmkrlsemxshd3j"
      },
      {
         "@type":"/cosmos.auth.v1beta1.ModuleAccount",
         "baseAccount":{
            "address":"cosmos1m3h30wlvsf8llruxtpukdvsy0km2kum8g38c8q",
            "accountNumber":"7"
         },
         "name":"mint",
         "permissions":[
            "minter"
         ]
      },
      {
         "@type":"/cosmos.auth.v1beta1.ModuleAccount",
         "baseAccount":{
            "address":"cosmos17xpfvakm2amg962yls6f84z3kell8c5lserqta",
            "accountNumber":"2"
         },
         "name":"fee_collector"
      }
   ],
   "pagination":{
      "total":"9"
   }
}

Params

params 端點允許用戶查詢當前的身份驗證參數。

cosmos.auth.v1beta1.Query/Params

例子:

grpcurl -plaintext \
    localhost:9090 \
    cosmos.auth.v1beta1.Query/Params

示例輸出:

{
  "params": {
    "maxMemoCharacters": "256",
    "txSigLimit": "7",
    "txSizeCostPerByte": "10",
    "sigVerifyCostEd25519": "590",
    "sigVerifyCostSecp256k1": "1000"
  }
}

REST

用戶可以使用 REST 端點查詢“auth”模塊。

Account

account 端點允許用戶通過地址查詢帳戶。

/cosmos/auth/v1beta1/account?address={address}

Accounts

accounts 端點允許用戶查詢所有可用的帳戶。

/cosmos/auth/v1beta1/accounts

Params

params 端點允許用戶查詢當前的身份驗證參數。

/cosmos/auth/v1beta1/params

Parameters

auth 模塊包含以下參數：

Key	Type	Example
MaxMemoCharacters	uint64	256
TxSigLimit	uint64	7
TxSizeCostPerByte	uint64	10
SigVerifyCostED25519	uint64	590
SigVerifyCostSecp256k1	uint64	1000