Skip to content

Commit

Permalink
docs: #10178 reference authz from auth (#10238)
Browse files Browse the repository at this point in the history
## Description

Closes: #178

Adds the requested differential language between auth and authz modules.  Resolves instances of future tense that were noticed.

---

### Author Checklist

*All items are required. Please add a note to the item if the item is not applicable and
please add links to any relevant follow up issues.*

I have...

- [x] included the correct [type prefix](https://github.com/commitizen/conventional-commit-types/blob/v3.0.0/index.json) in the PR title
- [NA] added `!` to the type prefix if API or client breaking change
- [x] targeted the correct branch (see [PR Targeting](https://github.com/cosmos/cosmos-sdk/blob/master/CONTRIBUTING.md#pr-targeting))
- [x] provided a link to the relevant issue or specification
- [NA] followed the guidelines for [building modules](https://github.com/cosmos/cosmos-sdk/blob/master/docs/building-modules)
- [NA] included the necessary unit and integration [tests](https://github.com/cosmos/cosmos-sdk/blob/master/CONTRIBUTING.md#testing)
- [NA] added a changelog entry to `CHANGELOG.md`
- [NA] included comments for [documenting Go code](https://blog.golang.org/godoc)
- [x] updated the relevant documentation or specification
- [NA] reviewed "Files changed" and left comments if necessary
- [NA] confirmed all CI checks have passed

### Reviewers Checklist

*All items are required. Please add a note if the item is not applicable and please add
your handle next to the items reviewed if you only reviewed selected items.*

I have...

- [ ] confirmed the correct [type prefix](https://github.com/commitizen/conventional-commit-types/blob/v3.0.0/index.json) in the PR title
- [ ] confirmed `!` in the type prefix if API or client breaking change
- [ ] confirmed all author checklist items have been addressed 
- [ ] reviewed state machine logic
- [ ] reviewed API design and naming
- [ ] reviewed documentation is accurate
- [ ] reviewed tests and test coverage
- [ ] manually tested (if applicable)
  • Loading branch information
brennhill authored Sep 30, 2021
1 parent a64a8cc commit a237f5a
Show file tree
Hide file tree
Showing 7 changed files with 24 additions and 18 deletions.
6 changes: 6 additions & 0 deletions x/auth/spec/01_concepts.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
2 changes: 1 addition & 1 deletion x/auth/spec/03_antehandlers.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
16 changes: 8 additions & 8 deletions x/auth/spec/05_vesting.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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.

Expand Down Expand Up @@ -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 {
Expand Down
2 changes: 1 addition & 1 deletion x/auth/spec/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
10 changes: 5 additions & 5 deletions x/authz/spec/01_concepts.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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.
2 changes: 1 addition & 1 deletion x/authz/spec/03_messages.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
4 changes: 2 additions & 2 deletions x/authz/spec/05_client.md
Original file line number Diff line number Diff line change
Expand Up @@ -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]
Expand Down Expand Up @@ -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
Expand Down

0 comments on commit a237f5a

Please sign in to comment.