update spec and fix code snippets (#9334)
* update spec and fix code snippets * updating authz.Grant documentation * Update proto/cosmos/authz/v1beta1/tx.proto Co-authored-by: Ryan Christoffersen <12519942+ryanchrypto@users.noreply.github.com> * Apply suggestions from code review Co-authored-by: Ryan Christoffersen <12519942+ryanchrypto@users.noreply.github.com> * rename messages to services * Update proto/cosmos/authz/v1beta1/tx.proto Co-authored-by: Ryan Christoffersen <12519942+ryanchrypto@users.noreply.github.com> * update snippets * Apply suggestions from code review Co-authored-by: Ryan Christoffersen <12519942+ryanchristo@users.noreply.github.com> * authz: update service docs to emphasis the service methods * authz spec: rollback to use message oriented spec * Apply suggestions from code review Co-authored-by: Ryan Christoffersen <12519942+ryanchristo@users.noreply.github.com> * Update MsgGrant type doc Co-authored-by: Ryan Christoffersen <12519942+ryanchrypto@users.noreply.github.com> Co-authored-by: Ryan Christoffersen <12519942+ryanchristo@users.noreply.github.com> Co-authored-by: mergify[bot] <37929162+mergify[bot]@users.noreply.github.com> Co-authored-by: Tyler <48813565+technicallyty@users.noreply.github.com>
This commit is contained in:
Robert Zaremba
GitHub
parent
e5abed1c3b
commit
b36664df4a
|
|
@ -1318,8 +1318,8 @@ MsgExecResponse defines the Msg/MsgExecResponse response type.
|
|||
<a name="cosmos.authz.v1beta1.MsgGrant"></a>
|
||||
|
||||
### 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. |
|
||||
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -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;
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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"`
|
||||
}
|
||||
|
|
|
|||
Loading…
Reference in New Issue