x/authz specs

x/README.md

@@ -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).

x/authz/spec/01_concepts.md

@@ -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](../../../docs/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.

x/authz/spec/02_state.md

@@ -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

x/authz/spec/03_messages.md

@@ -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.

x/authz/spec/04_events.md

@@ -0,0 +1,29 @@
+<!--
+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           |                    |
+| grant-authorization  | grantee           |                    |
+
+
+### RevokeAuthorization
+
+| Type                 | Attribute Key     | Attribute Value    |
+|----------------------|-------------------|--------------------|
+| revoke-authorization | module            | authz              |
+| revoke-authorization | grant-type        | {msgType}          |
+| revoke-authorization | granter           |                    |
+| revoke-authorization | grantee           |                    |
+

x/authz/spec/README.md

@@ -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](docs/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)
+