x/authz specs (#8499)

* init

* init

* add events

* add state & messages

* WIP

* update Readme

* WIP

* Update x/README.md

Co-authored-by: Alessio Treglia <alessio@tendermint.com>

* Update x/authz/spec/README.md

Co-authored-by: Amaury <amaury.martiny@protonmail.com>

* Update x/authz/spec/02_state.md

Co-authored-by: Amaury <amaury.martiny@protonmail.com>

* Update x/authz/spec/01_concepts.md

Co-authored-by: Amaury <amaury.martiny@protonmail.com>

* review changes

* Update x/authz/spec/01_concepts.md

Co-authored-by: Amaury <amaury.martiny@protonmail.com>

* Update x/authz/spec/02_state.md

Co-authored-by: Amaury <amaury.martiny@protonmail.com>

* Update x/authz/spec/01_concepts.md

Co-authored-by: Cory <cjlevinson@gmail.com>

* Update x/authz/spec/04_events.md

Co-authored-by: Cory <cjlevinson@gmail.com>

* Update x/authz/spec/04_events.md

Co-authored-by: Cory <cjlevinson@gmail.com>

* Update x/authz/spec/README.md

Co-authored-by: Cory <cjlevinson@gmail.com>

Co-authored-by: Alessio Treglia <alessio@tendermint.com>
Co-authored-by: Amaury <amaury.martiny@protonmail.com>
Co-authored-by: Cory <cjlevinson@gmail.com>
This commit is contained in:
MD Aleem 2021-02-11 22:26:37 +05:30 committed by GitHub
parent bddbc131fd
commit 2154815f4c
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
6 changed files with 148 additions and 0 deletions

View File

@ -8,6 +8,7 @@ parent:
Here are some production-grade modules that can be used in Cosmos SDK applications, along with their respective documentation:
- [Auth](auth/spec/README.md) - Authentication of accounts and transactions for Cosmos SDK application.
- [Authz](authz/spec/README.md) - Authorization for accounts to perform actions on behalf of other accounts.
- [Bank](bank/spec/README.md) - Token transfer functionalities.
- [Capability](capability/spec/README.md) - Object capability implementation.
- [Crisis](crisis/spec/README.md) - Halting the blockchain under certain circumstances (e.g. if an invariant is broken).

View File

@ -0,0 +1,37 @@
<!--
order: 1
-->
# Concepts
## Authorization
Any concrete type of authorization defined in the `x/authz` module must fulfill the `Authorization` interface outlined below. Authorizations determine exactly what privileges are granted. They are extensible and can be defined for any Msg service method even outside of the module where the Msg method is defined. Authorizations use the new `ServiceMsg` type from [ADR 031](../../../architecture/adr-031-msg-service.md).
+++ https://github.com/cosmos/cosmos-sdk/blob/c95de9c4177442dee4c69d96917efc955b5d19d9/x/authz/types/authorizations.go#L15-L24
## Built-in Authorizations
Cosmos-SDK `x/authz` module comes with following authorization types
### SendAuthorization
`SendAuthorization` implements `Authorization` interface for the `cosmos.bank.v1beta1.Msg/Send` ServiceMsg, that takes a `SpendLimit` and updates it down to zero.
+++ https://github.com/cosmos/cosmos-sdk/blob/c95de9c4177442dee4c69d96917efc955b5d19d9/proto/cosmos/authz/v1beta1/authz.proto#L12-L19
+++ https://github.com/cosmos/cosmos-sdk/blob/c95de9c4177442dee4c69d96917efc955b5d19d9/x/authz/types/send_authorization.go#L23-L45
- `spent_limit` keeps track of how many coins left in the authorization.
### GenericAuthorization
`GenericAuthorization` implements the `Authorization` interface, that gives unrestricted permission to execute the provided ServiceMsg on behalf of granter's account.
+++ https://github.com/cosmos/cosmos-sdk/blob/c95de9c4177442dee4c69d96917efc955b5d19d9/proto/cosmos/authz/v1beta1/authz.proto#L21-L30
+++ https://github.com/cosmos/cosmos-sdk/blob/c95de9c4177442dee4c69d96917efc955b5d19d9/x/authz/types/generic_authorization.go#L20-L28
- `method_name` holds ServiceMsg type.

14
x/authz/spec/02_state.md Normal file
View File

@ -0,0 +1,14 @@
<!--
order: 2
-->
# State
## AuthorizationGrant
Authorizations are identified by combining granter address (the address bytes of the granter), grantee address (the address bytes of the grantee) and ServiceMsg type (its method name).
- AuthorizationGrant: `0x01 | granter_address_len (1 byte) | granter_address_bytes | grantee_address_len (1 byte) | grantee_address_bytes | msgType_bytes-> ProtocolBuffer(AuthorizationGrant)`
+++ https://github.com/cosmos/cosmos-sdk/blob/c95de9c4177442dee4c69d96917efc955b5d19d9/proto/cosmos/authz/v1beta1/authz.proto#L32-L37

View File

@ -0,0 +1,42 @@
<!--
order: 3
-->
# Messages
In this section we describe the processing of messages for the authz module.
## Msg/GrantAuthorization
An authorization-grant is created using the `MsgGrantAuthorization` message.
+++ https://github.com/cosmos/cosmos-sdk/blob/c95de9c4177442dee4c69d96917efc955b5d19d9/proto/cosmos/authz/v1beta1/tx.proto#L27-L35
This message is expected to fail if:
- both granter & grantee have same address.
- provided `Expiration` time less than current unix timestamp.
- provided `Authorization` is not implemented.
## Msg/RevokeAuthorization
An allowed authorization can be removed with `MsgRevokeAuthorization` message.
+++ https://github.com/cosmos/cosmos-sdk/blob/c95de9c4177442dee4c69d96917efc955b5d19d9/proto/cosmos/authz/v1beta1/tx.proto#L53-L59
This message is expected to fail if:
- both granter & grantee have same address.
- provided `MethodName` is empty.
## Msg/ExecAuthorizedRequest
When a grantee wants to execute transaction on behalf of a granter, it must send MsgExecAuthorizedRequest.
+++ https://github.com/cosmos/cosmos-sdk/blob/c95de9c4177442dee4c69d96917efc955b5d19d9/proto/cosmos/authz/v1beta1/tx.proto#L42-L48
This message is expected to fail if:
- authorization not implemented for the provided msg.
- grantee don't have permission to run transaction.
- if granted authorization is expired.

28
x/authz/spec/04_events.md Normal file
View File

@ -0,0 +1,28 @@
<!--
order: 4
-->
# Events
The authz module emits the following events:
## Keeper
### GrantAuthorization
| Type | Attribute Key | Attribute Value |
|----------------------|-------------------|--------------------|
| grant-authorization | module | authz |
| grant-authorization | grant-type | {msgType} |
| grant-authorization | granter | {granterAddress} |
| grant-authorization | grantee | {granteeAddress} |
### RevokeAuthorization
| Type | Attribute Key | Attribute Value |
|----------------------|-------------------|--------------------|
| revoke-authorization | module | authz |
| revoke-authorization | grant-type | {msgType} |
| revoke-authorization | granter | {granterAddress} |
| revoke-authorization | grantee | {granteeAddress} |

26
x/authz/spec/README.md Normal file
View File

@ -0,0 +1,26 @@
<!--
order: 0
title: Authz Overview
parent:
title: "authz"
-->
# `authz`
## Contents
## Abstract
`x/authz` is an implementation of a Cosmos SDK module, per [ADR 30](../../../architecture/adr-030-authz-module.md), that allows
granting arbitrary privileges from one account (the granter) to another account (the grantee). Authorizations must be granted for a particular Msg service method one by one using an implementation of the `Authorization` interface.
1. **[Concept](01_concepts.md)**
- [Authorization](01_concepts.md#Authorization)
- [Built-in Authorizations](01_concepts.md#Built-in-Authorization)
2. **[State](02_state.md)**
3. **[Messages](03_messages.md)**
- [Msg/GrantAuthorization](03_messages.md#MsgGrantAuthorization)
- [Msg/RevokeAuthorization](03_messages.md#MsgRevokeAuthorization)
- [Msg/ExecAuthorized](03_messages.md#MsgExecAuthorized)
4. **[Events](04_events.md)**
- [Keeper](04_events.md#Keeper)