diff --git a/docs/core/proto-docs.md b/docs/core/proto-docs.md index 250bdeb9ad..4b67f25205 100644 --- a/docs/core/proto-docs.md +++ b/docs/core/proto-docs.md @@ -1318,8 +1318,8 @@ MsgExecResponse defines the Msg/MsgExecResponse response type. ### MsgGrant -MsgGrant grants the provided authorization to the grantee on the granter's -account with the provided expiration time. +MsgGrant is a request type for Grant method. It declares authorization to the grantee +on behalf of the granter with the provided expiration time. | Field | Type | Label | Description | @@ -1384,7 +1384,7 @@ Msg defines the authz Msg service. | Method Name | Request Type | Response Type | Description | HTTP Verb | Endpoint | | ----------- | ------------ | ------------- | ------------| ------- | -------- | -| `Grant` | [MsgGrant](#cosmos.authz.v1beta1.MsgGrant) | [MsgGrantResponse](#cosmos.authz.v1beta1.MsgGrantResponse) | Grant grants the provided authorization to the grantee on the granter's account with the provided expiration time. | | +| `Grant` | [MsgGrant](#cosmos.authz.v1beta1.MsgGrant) | [MsgGrantResponse](#cosmos.authz.v1beta1.MsgGrantResponse) | Grant grants the provided authorization to the grantee on the granter's account with the provided expiration time. If there is already a grant for the given (granter, grantee, Authorization) triple, then the grant will be overwritten. | | | `Exec` | [MsgExec](#cosmos.authz.v1beta1.MsgExec) | [MsgExecResponse](#cosmos.authz.v1beta1.MsgExecResponse) | Exec attempts to execute the provided messages using authorizations granted to the grantee. Each message should have only one signer corresponding to the granter of the authorization. | | | `Revoke` | [MsgRevoke](#cosmos.authz.v1beta1.MsgRevoke) | [MsgRevokeResponse](#cosmos.authz.v1beta1.MsgRevokeResponse) | Revoke revokes any authorization corresponding to the provided method name on the granter's account that has been granted to the grantee. | | @@ -5901,7 +5901,7 @@ GenesisState defines the slashing module's genesis state. | ----- | ---- | ----- | ----------- | | `params` | [Params](#cosmos.slashing.v1beta1.Params) | | params defines all the paramaters of related to deposit. | | `signing_infos` | [SigningInfo](#cosmos.slashing.v1beta1.SigningInfo) | repeated | signing_infos represents a map between validator addresses and their signing infos. | -| `missed_blocks` | [ValidatorMissedBlocks](#cosmos.slashing.v1beta1.ValidatorMissedBlocks) | repeated | signing_infos represents a map between validator addresses and their missed blocks. | +| `missed_blocks` | [ValidatorMissedBlocks](#cosmos.slashing.v1beta1.ValidatorMissedBlocks) | repeated | missed_blocks represents a map between validator addresses and their missed blocks. | diff --git a/proto/cosmos/authz/v1beta1/tx.proto b/proto/cosmos/authz/v1beta1/tx.proto index 472b81a0e4..ffff463409 100644 --- a/proto/cosmos/authz/v1beta1/tx.proto +++ b/proto/cosmos/authz/v1beta1/tx.proto @@ -14,7 +14,9 @@ option (gogoproto.goproto_getters_all) = false; // Msg defines the authz Msg service. service Msg { // Grant grants the provided authorization to the grantee on the granter's - // account with the provided expiration time. + // account with the provided expiration time. If there is already a grant + // for the given (granter, grantee, Authorization) triple, then the grant + // will be overwritten. rpc Grant(MsgGrant) returns (MsgGrantResponse); // Exec attempts to execute the provided messages using @@ -27,8 +29,8 @@ service Msg { rpc Revoke(MsgRevoke) returns (MsgRevokeResponse); } -// MsgGrant grants the provided authorization to the grantee on the granter's -// account with the provided expiration time. +// MsgGrant is a request type for Grant method. It declares authorization to the grantee +// on behalf of the granter with the provided expiration time. message MsgGrant { string granter = 1; string grantee = 2; diff --git a/x/authz/spec/01_concepts.md b/x/authz/spec/01_concepts.md index 48ef52d20b..8ae6a874bd 100644 --- a/x/authz/spec/01_concepts.md +++ b/x/authz/spec/01_concepts.md @@ -8,11 +8,10 @@ order: 1 `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 an Msg by grantee address on behalf of the granter. -Authorization is an interface which must be implemented by a concrete authorization logic to validate and execute grants. They 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 below for more details. +Grant is an allowance to execute a Msg by the grantee on behalf of the granter. +Authorization is an interface which must be implemented by a concrete authorization logic to validate and execute grants. They 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. - -+++ https://github.com/cosmos/cosmos-sdk/blob/c95de9c4177442dee4c69d96917efc955b5d19d9/x/authz/types/authorizations.go#L15-L24 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.43.0-beta1/x/authz/authorizations.go#L11-L25 ## Built-in Authorizations @@ -21,22 +20,22 @@ Cosmos-SDK `x/authz` module comes with following authorization types ### SendAuthorization -`SendAuthorization` implements `Authorization` interface for the `cosmos.bank.v1beta1.MsgSend` Msg, that takes a `SpendLimit` and updates it down to zero. +`SendAuthorization` implements the `Authorization` interface for the `cosmos.bank.v1beta1.MsgSend` Msg. It takes a `SpendLimit` that specifies the maximum amount of tokens the grantee can spend, which is updated as the tokens are spent. -+++ https://github.com/cosmos/cosmos-sdk/blob/c95de9c4177442dee4c69d96917efc955b5d19d9/proto/cosmos/authz/v1beta1/authz.proto#L12-L19 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.43.0-beta1/proto/cosmos/bank/v1beta1/authz.proto#L10-L19 -+++ https://github.com/cosmos/cosmos-sdk/blob/c95de9c4177442dee4c69d96917efc955b5d19d9/x/authz/types/send_authorization.go#L23-L45 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.43.0-beta1/x/bank/types/send_authorization.go#L25-L40 -- `spent_limit` keeps track of how many coins left in the authorization. +- `spent_limit` keeps track of how many coins are left in the authorization. ### GenericAuthorization `GenericAuthorization` implements the `Authorization` interface, that gives unrestricted permission to execute the provided Msg 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/v0.43.0-beta1/proto/cosmos/authz/v1beta1/authz.proto#L14-L19 -+++ https://github.com/cosmos/cosmos-sdk/blob/c95de9c4177442dee4c69d96917efc955b5d19d9/x/authz/types/generic_authorization.go#L20-L28 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.43.0-beta1/x/authz/generic_authorization.go#L18-L31 - `msg` stores Msg type URL. diff --git a/x/authz/spec/02_state.md b/x/authz/spec/02_state.md index 9648b623ef..5b07f645a1 100644 --- a/x/authz/spec/02_state.md +++ b/x/authz/spec/02_state.md @@ -4,11 +4,12 @@ order: 2 # State -## AuthorizationGrant +## Grant -Grants are identified by combining granter address (the address bytes of the granter), grantee address (the address bytes of the grantee) and Msg type (its TypeURL). Hence we only allow one grant for the (granter, grantee, msg type) triple. +Grants are identified by combining granter address (the address bytes of the granter), grantee address (the address bytes of the grantee) and Authorization type (its type URL). Hence we only allow one grant for the (granter, grantee, Authorization) triple. -- AuthorizationGrant: `0x01 | granter_address_len (1 byte) | granter_address_bytes | grantee_address_len (1 byte) | grantee_address_bytes | msgType_bytes-> ProtocolBuffer(AuthorizationGrant)` +- Grant: `0x01 | granter_address_len (1 byte) | granter_address_bytes | grantee_address_len (1 byte) | grantee_address_bytes | msgType_bytes-> ProtocolBuffer(AuthorizationGrant)` +The grant object encapsulates an `Authorization` type and an expiration timestamp: -+++ https://github.com/cosmos/cosmos-sdk/blob/c95de9c4177442dee4c69d96917efc955b5d19d9/proto/cosmos/authz/v1beta1/authz.proto#L32-L37 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.43.0-beta1/proto/cosmos/authz/v1beta1/authz.proto#L21-L26 diff --git a/x/authz/spec/03_messages.md b/x/authz/spec/03_messages.md index 86d6150644..2a438ad4e1 100644 --- a/x/authz/spec/03_messages.md +++ b/x/authz/spec/03_messages.md @@ -6,38 +6,42 @@ order: 3 In this section we describe the processing of messages for the authz module. -## Msg/Grant +## MsgGrant -An authorization-grant is created using the `MsgGrant` message. +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. -+++ https://github.com/cosmos/cosmos-sdk/blob/c95de9c4177442dee4c69d96917efc955b5d19d9/proto/cosmos/authz/v1beta1/tx.proto#L27-L35 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.43.0-beta1/proto/cosmos/authz/v1beta1/tx.proto#L32-L37 -This message is expected to fail if: +The message handling should fail if: -- both granter & grantee have same address. -- provided `Expiration` time less than current unix timestamp. -- provided `Authorization` is not implemented. -- Authorization Method doesn't exist (there is no defined handler in the app router to handle that Msg types) +- both granter and grantee have the same address. +- provided `Expiration` time is less than current unix timestamp. +- provided `Grant.Authorization` is not implemented. +- `Authorization.MsgTypeURL()` is not defined in the router (there is no defined handler in the app router to handle that Msg types). -## Msg/Revoke -An allowed authorization can be removed with `MsgRevoke` message. +## MsgRevoke -+++ https://github.com/cosmos/cosmos-sdk/blob/c95de9c4177442dee4c69d96917efc955b5d19d9/proto/cosmos/authz/v1beta1/tx.proto#L53-L59 +A grant can be removed with the `MsgRevoke` message. -This message is expected to fail if: ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.43.0-beta1/proto/cosmos/authz/v1beta1/tx.proto#L60-L64 -- both granter & grantee have same address. +The message handling should fail if: + +- both granter and grantee have the same address. - provided `MsgTypeUrl` is empty. -## Msg/Exec +NOTE: The `MsgExec` message removes a grant if the grant has expired. -When a grantee wants to execute transaction on behalf of a granter, it must send MsgExecRequest. +## MsgExec -+++ https://github.com/cosmos/cosmos-sdk/blob/c95de9c4177442dee4c69d96917efc955b5d19d9/proto/cosmos/authz/v1beta1/tx.proto#L42-L48 +When a grantee wants to execute a transaction on behalf of a granter, they must send `MsgExec`. -This message is expected to fail if: ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.43.0-beta1/proto/cosmos/authz/v1beta1/tx.proto#L47-L53 -- authorization not implemented for the provided msg. -- grantee don't have permission to run transaction. +The message handling should fail if: + +- provided `Authorization` is not implemented. +- grantee doesn't have permission to run the transaction. - if granted authorization is expired. diff --git a/x/authz/spec/README.md b/x/authz/spec/README.md index c5f9824407..855460889b 100644 --- a/x/authz/spec/README.md +++ b/x/authz/spec/README.md @@ -10,7 +10,7 @@ parent: ## Contents ## Abstract -`x/authz` is an implementation of a Cosmos SDK module, per [ADR 30](../../../architecture/adr-030-authz-module.md), that allows +`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)** @@ -19,9 +19,8 @@ granting arbitrary privileges from one account (the granter) to another account - [Gas](01_concepts.md#gas) 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) + - [MsgGrant](03_messages.md#MsgGrant) + - [MsgRevoke](03_messages.md#MsgRevoke) + - [MsgExec](03_messages.md#MsgExec) 4. **[Events](04_events.md)** - [Keeper](04_events.md#Keeper) - diff --git a/x/authz/tx.pb.go b/x/authz/tx.pb.go index 69e9fd72c7..cac4f3b3cc 100644 --- a/x/authz/tx.pb.go +++ b/x/authz/tx.pb.go @@ -32,8 +32,8 @@ var _ = math.Inf // proto package needs to be updated. const _ = proto.GoGoProtoPackageIsVersion3 // please upgrade the proto package -// MsgGrant grants the provided authorization to the grantee on the granter's -// account with the provided expiration time. +// MsgGrant is a request type for Grant method. It declares authorization to the grantee +// on behalf of the granter with the provided expiration time. type MsgGrant struct { Granter string `protobuf:"bytes,1,opt,name=granter,proto3" json:"granter,omitempty"` Grantee string `protobuf:"bytes,2,opt,name=grantee,proto3" json:"grantee,omitempty"` @@ -330,7 +330,9 @@ const _ = grpc.SupportPackageIsVersion4 // For semantics around ctx use and closing/ending streaming RPCs, please refer to https://godoc.org/google.golang.org/grpc#ClientConn.NewStream. type MsgClient interface { // Grant grants the provided authorization to the grantee on the granter's - // account with the provided expiration time. + // account with the provided expiration time. If there is already a grant + // for the given (granter, grantee, Authorization) triple, then the grant + // will be overwritten. Grant(ctx context.Context, in *MsgGrant, opts ...grpc.CallOption) (*MsgGrantResponse, error) // Exec attempts to execute the provided messages using // authorizations granted to the grantee. Each message should have only @@ -379,7 +381,9 @@ func (c *msgClient) Revoke(ctx context.Context, in *MsgRevoke, opts ...grpc.Call // MsgServer is the server API for Msg service. type MsgServer interface { // Grant grants the provided authorization to the grantee on the granter's - // account with the provided expiration time. + // account with the provided expiration time. If there is already a grant + // for the given (granter, grantee, Authorization) triple, then the grant + // will be overwritten. Grant(context.Context, *MsgGrant) (*MsgGrantResponse, error) // Exec attempts to execute the provided messages using // authorizations granted to the grantee. Each message should have only diff --git a/x/slashing/types/genesis.pb.go b/x/slashing/types/genesis.pb.go index 9819899d09..7235626bd7 100644 --- a/x/slashing/types/genesis.pb.go +++ b/x/slashing/types/genesis.pb.go @@ -30,7 +30,7 @@ type GenesisState struct { // signing_infos represents a map between validator addresses and their // signing infos. SigningInfos []SigningInfo `protobuf:"bytes,2,rep,name=signing_infos,json=signingInfos,proto3" json:"signing_infos" yaml:"signing_infos"` - // signing_infos represents a map between validator addresses and their + // missed_blocks represents a map between validator addresses and their // missed blocks. MissedBlocks []ValidatorMissedBlocks `protobuf:"bytes,3,rep,name=missed_blocks,json=missedBlocks,proto3" json:"missed_blocks" yaml:"missed_blocks"` }