diff --git a/x/README.md b/x/README.md index 3be56a3de605..e90ee59cebcb 100644 --- a/x/README.md +++ b/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). diff --git a/x/authz/spec/01_concepts.md b/x/authz/spec/01_concepts.md new file mode 100644 index 000000000000..0f5e482f1619 --- /dev/null +++ b/x/authz/spec/01_concepts.md @@ -0,0 +1,37 @@ + + +# 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. diff --git a/x/authz/spec/02_state.md b/x/authz/spec/02_state.md new file mode 100644 index 000000000000..3afc5eddbafb --- /dev/null +++ b/x/authz/spec/02_state.md @@ -0,0 +1,14 @@ + + +# 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 diff --git a/x/authz/spec/03_messages.md b/x/authz/spec/03_messages.md new file mode 100644 index 000000000000..9b3cffa35c24 --- /dev/null +++ b/x/authz/spec/03_messages.md @@ -0,0 +1,42 @@ + + +# 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. \ No newline at end of file diff --git a/x/authz/spec/04_events.md b/x/authz/spec/04_events.md new file mode 100644 index 000000000000..4d0a9858af7f --- /dev/null +++ b/x/authz/spec/04_events.md @@ -0,0 +1,28 @@ + + +# 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} | diff --git a/x/authz/spec/README.md b/x/authz/spec/README.md new file mode 100644 index 000000000000..07ec1ba0c1e6 --- /dev/null +++ b/x/authz/spec/README.md @@ -0,0 +1,26 @@ + + +# `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) +