diff --git a/x/auth/spec/01_concepts.md b/x/auth/spec/01_concepts.md index 9f8c9b8d8..57393d6ed 100644 --- a/x/auth/spec/01_concepts.md +++ b/x/auth/spec/01_concepts.md @@ -4,6 +4,12 @@ order: 1 # Concepts +**Note:** The auth module is different from the [authz module](../modules/authz/). + +The differences are: +* `auth` - authentication of accounts and transactions for Cosmos SDK applications and is responsible for specifying the base transaction and account types. +* `authz` - authorization for accounts to perform actions on behalf of other accounts and enables a granter to grant authorizations to a grantee that allows the grantee to execute messages on behalf of the granter. + ## Gas & Fees Fees serve two purposes for an operator of the network. diff --git a/x/auth/spec/03_antehandlers.md b/x/auth/spec/03_antehandlers.md index 851005162..ce1dc85c5 100644 --- a/x/auth/spec/03_antehandlers.md +++ b/x/auth/spec/03_antehandlers.md @@ -27,7 +27,7 @@ The auth module provides `AnteDecorator`s that are recursively chained together - `ConsumeGasTxSizeDecorator`: Consumes gas proportional to the `tx` size based on application parameters. -- `DeductFeeDecorator`: Deducts the `FeeAmount` from first signer of the `tx`. If the `x/feegrant` module is enabled and a fee granter is set, it will deduct fees from the fee granter account. +- `DeductFeeDecorator`: Deducts the `FeeAmount` from first signer of the `tx`. If the `x/feegrant` module is enabled and a fee granter is set, it deducts fees from the fee granter account. - `SetPubKeyDecorator`: Sets the pubkey from a `tx`'s signers that does not already have its corresponding pubkey saved in the state machine and in the current context. diff --git a/x/auth/spec/05_vesting.md b/x/auth/spec/05_vesting.md index 858579b6f..b085cc4c5 100644 --- a/x/auth/spec/05_vesting.md +++ b/x/auth/spec/05_vesting.md @@ -34,8 +34,8 @@ the Cosmos Hub. The requirements for this vesting account is that it should be initialized during genesis with a starting balance `X` and a vesting end time `ET`. A vesting account may be initialized with a vesting start time `ST` and a number of vesting periods `P`. If a vesting start time is included, the -vesting period will not begin until start time is reached. If vesting periods -are included, the vesting will occur over the specified number of periods. +vesting period does not begin until start time is reached. If vesting periods +are included, the vesting occurs over the specified number of periods. For all vesting accounts, the owner of the vesting account is able to delegate and undelegate from validators, however they cannot transfer coins to another @@ -378,7 +378,7 @@ func (cva ContinuousVestingAccount) TrackUndelegation(amount Coins) { **Note** `TrackUnDelegation` only modifies the `DelegatedVesting` and `DelegatedFree` fields, so upstream callers MUST modify the `Coins` field by adding `amount`. -**Note**: If a delegation is slashed, the continuous vesting account will end up +**Note**: If a delegation is slashed, the continuous vesting account ends up with an excess `DV` amount, even after all its coins have vested. This is because undelegating free coins are prioritized. @@ -419,11 +419,11 @@ See the above specification for full implementation details. ## Genesis Initialization -To initialize both vesting and non-vesting accounts, the `GenesisAccount` struct will -include new fields: `Vesting`, `StartTime`, and `EndTime`. Accounts meant to be -of type `BaseAccount` or any non-vesting type will have `Vesting = false`. The -genesis initialization logic (e.g. `initFromGenesisState`) will have to parse -and return the correct accounts accordingly based off of these new fields. +To initialize both vesting and non-vesting accounts, the `GenesisAccount` struct +includes new fields: `Vesting`, `StartTime`, and `EndTime`. Accounts meant to be +of type `BaseAccount` or any non-vesting type have `Vesting = false`. The +genesis initialization logic (e.g. `initFromGenesisState`) must parse +and return the correct accounts accordingly based off of these fields. ```go type GenesisAccount struct { diff --git a/x/auth/spec/README.md b/x/auth/spec/README.md index f666e0923..b8a96aaa7 100644 --- a/x/auth/spec/README.md +++ b/x/auth/spec/README.md @@ -16,7 +16,7 @@ for an application, since the SDK itself is agnostic to these particulars. It co the ante handler, where all basic transaction validity checks (signatures, nonces, auxiliary fields) are performed, and exposes the account keeper, which allows other modules to read, write, and modify accounts. -This module will be used in the Cosmos Hub. +This module is used in the Cosmos Hub. ## Contents diff --git a/x/authz/spec/01_concepts.md b/x/authz/spec/01_concepts.md index 20ec9a7b6..7855ff5fc 100644 --- a/x/authz/spec/01_concepts.md +++ b/x/authz/spec/01_concepts.md @@ -6,19 +6,19 @@ order: 1 ## Authorization and Grant -`x/authz` module defines interfaces and messages grant authorizations to perform actions +The `x/authz` module defines interfaces and messages grant authorizations to perform actions on behalf of one account to other accounts. The design is defined in the [ADR 030](../../../architecture/adr-030-authz-module.md). -Grant is an allowance to execute a Msg by the grantee on behalf of the granter. +A *grant* is an allowance to execute a Msg by the grantee on behalf of the granter. Authorization is an interface that must be implemented by a concrete authorization logic to validate and execute grants. Authorizations are extensible and can be defined for any Msg service method even outside of the module where the Msg method is defined. See the `SendAuthorization` example in the next section for more details. -**Note:** The authz module is different from the [auth](../modules/auth/) (authentication) module that is responsible for specifying the base transaction and account types. +**Note:** The authz module is different from the [auth (authentication)](../modules/auth/) module that is responsible for specifying the base transaction and account types. +++ https://github.com/cosmos/cosmos-sdk/blob/v0.43.0-beta1/x/authz/authorizations.go#L11-L25 ## Built-in Authorizations -The Cosmos SDK `x/authz` module comes with following authorization types. +The Cosmos SDK `x/authz` module comes with following authorization types: ### SendAuthorization @@ -42,4 +42,4 @@ The Cosmos SDK `x/authz` module comes with following authorization types. ## Gas -In order to prevent DoS attacks, granting `StakeAuthorizaiton`s with `x/authz` incurs gas. `StakeAuthorization` allows you to authorize another account to delegate, undelegate, or redelegate to validators. The authorizer can define a list of validators they allow or deny delegations to. The Cosmos SDK will iterate over these lists and charge 10 gas for each validator in both of the lists. +In order to prevent DoS attacks, granting `StakeAuthorizaiton`s with `x/authz` incurs gas. `StakeAuthorization` allows you to authorize another account to delegate, undelegate, or redelegate to validators. The authorizer can define a list of validators they allow or deny delegations to. The Cosmos SDK iterates over these lists and charge 10 gas for each validator in both of the lists. diff --git a/x/authz/spec/03_messages.md b/x/authz/spec/03_messages.md index 736c5761b..7ff1b7548 100644 --- a/x/authz/spec/03_messages.md +++ b/x/authz/spec/03_messages.md @@ -9,7 +9,7 @@ In this section we describe the processing of messages for the authz module. ## MsgGrant An authorization grant is created using the `MsgGrant` message. -If there is already a grant for the `(granter, grantee, Authorization)` triple, then the new grant will overwrite the previous one. To update or extend an existing grant, a new grant with the same `(granter, grantee, Authorization)` triple should be created. +If there is already a grant for the `(granter, grantee, Authorization)` triple, then the new grant overwrites the previous one. To update or extend an existing grant, a new grant with the same `(granter, grantee, Authorization)` triple should be created. +++ https://github.com/cosmos/cosmos-sdk/blob/v0.43.0-beta1/proto/cosmos/authz/v1beta1/tx.proto#L32-L37 diff --git a/x/authz/spec/05_client.md b/x/authz/spec/05_client.md index 2c40a6029..a67007e59 100644 --- a/x/authz/spec/05_client.md +++ b/x/authz/spec/05_client.md @@ -18,7 +18,7 @@ simd query authz --help #### grants -The `grants` command allows users to query grants for a granter-grantee pair. If the message type URL is set, it will select grants only for that message type. +The `grants` command allows users to query grants for a granter-grantee pair. If the message type URL is set, it selects grants only for that message type. ```bash simd query authz grants [granter-addr] [grantee-addr] [msg-type-url]? [flags] @@ -99,7 +99,7 @@ A user can query the `authz` module using gRPC endpoints. ### Grants -The `Grants` endpoint allows users to query grants for a granter-grantee pair. If the message type URL is set, it will select grants only for that message type. +The `Grants` endpoint allows users to query grants for a granter-grantee pair. If the message type URL is set, it selects grants only for that message type. ```bash cosmos.authz.v1beta1.Query/Grants