LaconicNetwork/cosmos-sdk
10
0
Fork 0
Code Issues Pull Requests Packages Projects Releases 2 Wiki Activity

docs(x/feegrant): Update readme (backport #21364) (#21367)

Browse Source 
Co-authored-by: Ezequiel Raynaudo <raynaudo.ee@gmail.com>
This commit is contained in:
mergify[bot] 2024-08-20 09:45:17 +02:00 committed by GitHub
parent eb9be58ef6
commit 64a44d2405
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 75 additions and 22 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

97
x/feegrant/README.md
View File

@ -35,13 +35,13 @@ This module allows accounts to grant fee allowances and to use fees from their a
`Grant` is stored in the KVStore to record a grant with full context. Every grant will contain `granter`, `grantee` and what kind of `allowance` is granted. `granter` is an account address who is giving permission to `grantee` (the beneficiary account address) to pay for some or all of `grantee`'s transaction fees. `allowance` defines what kind of fee allowance (`BasicAllowance` or `PeriodicAllowance`, see below) is granted to `grantee`. `allowance` accepts an interface which implements `FeeAllowanceI`, encoded as `Any` type. There can be only one existing fee grant allowed for a `grantee` and `granter`, self grants are not allowed.
```protobuf reference
https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/feegrant/v1beta1/feegrant.proto#L83-L93
https://github.com/cosmos/cosmos-sdk/blob/release/v0.52.x/x/feegrant/proto/cosmos/feegrant/v1beta1/feegrant.proto#L86-L96
```
`FeeAllowanceI` looks like:
```go reference
https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/x/feegrant/fees.go#L9-L32
https://github.com/cosmos/cosmos-sdk/blob/release/v0.52.x/x/feegrant/fees.go#L10-L34
```
### Fee Allowance types
@ -57,7 +57,7 @@ There are two types of fee allowances present at the moment:
`BasicAllowance` is permission for `grantee` to use fee from a `granter`'s account. If any of the `spend_limit` or `expiration` reaches its limit, the grant will be removed from the state.
```protobuf reference
https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/feegrant/v1beta1/feegrant.proto#L15-L28
https://github.com/cosmos/cosmos-sdk/blob/release/v0.52.x/x/feegrant/proto/cosmos/feegrant/v1beta1/feegrant.proto#L15-L33
```
* `spend_limit` is the limit of coins that are allowed to be used from the `granter` account. If it is empty, it assumes there's no spend limit, `grantee` can use any number of available coins from `granter` account address before the expiration.
@ -71,7 +71,7 @@ https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/feegrant/v1be
`PeriodicAllowance` is a repeating fee allowance for the mentioned period, we can mention when the grant can expire as well as when a period can reset. We can also define the maximum number of coins that can be used in a mentioned period of time.
```protobuf reference
https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/feegrant/v1beta1/feegrant.proto#L34-L68
https://github.com/cosmos/cosmos-sdk/blob/release/v0.52.x/x/feegrant/proto/cosmos/feegrant/v1beta1/feegrant.proto#L35-L71
```
* `basic` is the instance of `BasicAllowance` which is optional for periodic fee allowance. If empty, the grant will have no `expiration` and no `spend_limit`.
@ -89,7 +89,7 @@ https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/feegrant/v1be
`AllowedMsgAllowance` is a fee allowance, it can be any of `BasicFeeAllowance`, `PeriodicAllowance` but restricted only to the allowed messages mentioned by the granter.
```protobuf reference
https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/feegrant/v1beta1/feegrant.proto#L70-L81
https://github.com/cosmos/cosmos-sdk/blob/release/v0.52.x/x/feegrant/proto/cosmos/feegrant/v1beta1/feegrant.proto#L73-L84
```
* `allowance` is either `BasicAllowance` or `PeriodicAllowance`.
@ -101,25 +101,25 @@ https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/feegrant/v1be
`feegrant` module introduces a `FeeGranter` flag for CLI for the sake of executing transactions with fee granter. When this flag is set, `clientCtx` will append the granter account address for transactions generated through CLI.
```go reference
https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/client/cmd.go#L249-L260
https://github.com/cosmos/cosmos-sdk/blob/release/v0.52.x/client/cmd.go#L256-L267
```
```go reference
https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/client/tx/tx.go#L109-L109
https://github.com/cosmos/cosmos-sdk/blob/release/v0.52.x/client/tx/tx.go#L129-L131
```
```go reference
https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/x/auth/tx/builder.go#L275-L284
https://github.com/cosmos/cosmos-sdk/blob/release/v0.52.x/x/auth/tx/builder.go#L208
```
```protobuf reference
https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/tx/v1beta1/tx.proto#L203-L224
https://github.com/cosmos/cosmos-sdk/blob/release/v0.52.x/proto/cosmos/tx/v1beta1/tx.proto#L216-L243
```
Example cmd:
```go
./simd tx gov submit-proposal --title="Test Proposal" --description="My awesome proposal" --type="Text" --from validator-key --fee-granter=cosmos1xh44hxt7spr67hqaa7nyx5gnutrz5fraw6grxn --chain-id=testnet --fees="10stake"
```shell
simd tx gov submit-legacy-proposal --title="Test Proposal" --description="My awesome proposal" --type="Text" --from validator-key --fee-granter=cosmos1xh44hxt7spr67hqaa7nyx5gnutrz5fraw6grxn --chain-id=testnet --fees="10stake"
```
### Granted Fee Deductions
@ -147,7 +147,7 @@ Fee allowance grants are stored in the state as follows:
* Grant: `0x00 | grantee_addr_len (1 byte) | grantee_addr_bytes | granter_addr_len (1 byte) | granter_addr_bytes -> ProtocolBuffer(Grant)`
```go reference
https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/x/feegrant/feegrant.pb.go#L222-L230
https://github.com/cosmos/cosmos-sdk/blob/release/v0.52.x/x/feegrant/feegrant.pb.go#L222-L230
```
### FeeAllowanceQueue
@ -165,7 +165,7 @@ Fee allowance queue keys are stored in the state as follows:
A fee allowance grant will be created with the `MsgGrantAllowance` message.
```protobuf reference
https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/feegrant/v1beta1/tx.proto#L25-L39
https://github.com/cosmos/cosmos-sdk/blob/release/v0.52.x/x/feegrant/proto/cosmos/feegrant/v1beta1/tx.proto#L30-L44
```
### Msg/RevokeAllowance
@ -173,7 +173,7 @@ https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/feegrant/v1be
An allowed grant fee allowance can be removed with the `MsgRevokeAllowance` message.
```protobuf reference
https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/feegrant/v1beta1/tx.proto#L41-L54
https://github.com/cosmos/cosmos-sdk/blob/release/v0.52.x/x/feegrant/proto/cosmos/feegrant/v1beta1/tx.proto#L49-L62
```
## Events
@ -255,18 +255,49 @@ grantee: cosmos1..
granter: cosmos1..
```
##### grants
##### grants-by-grantee
The `grants` command allows users to query all grants for a given grantee.
The `grants-by-grantee ` command allows users to query all grants for a given grantee.
```shell
simd query feegrant grants [grantee] [flags]
simd query feegrant grants-by-grantee [grantee] [flags]
```
Example:
```shell
simd query feegrant grants cosmos1..
simd query feegrant grants-by-grantee cosmos1..
```
Example Output:
```yml
allowances:
- allowance:
'@type': /cosmos.feegrant.v1beta1.BasicAllowance
expiration: null
spend_limit:
- amount: "100"
denom: stake
grantee: cosmos1..
granter: cosmos1..
pagination:
next_key: null
total: "0"
```
##### grants-by-granter
The `grants-by-granter` command allows users to query all grants created by a given granter.
```shell
simd query feegrant grants-by-granter [granter] [flags]
```
Example:
```shell
simd query feegrant grants-by-granter cosmos1..
```
Example Output:
@ -296,24 +327,46 @@ simd tx feegrant --help
##### grant
The `grant` command allows users to grant fee allowances to another account. The fee allowance can have an expiration date, a total spend limit, and/or a periodic spend limit.
The `grant` command allows users to grant fee allowances to another account. The fee allowance can have an expiration date, a total spend limit, a periodic spend limit, and/or allowed messages.
```shell
simd tx feegrant grant [granter] [grantee] [flags]
```
Example (one-time spend limit):
Examples:
###### One-time spend limit
```shell
simd tx feegrant grant cosmos1.. cosmos1.. --spend-limit 100stake
```
Example (periodic spend limit):
###### Periodic spend limit
```shell
simd tx feegrant grant cosmos1.. cosmos1.. --period 3600 --period-limit 10stake
simd tx feegrant grant cosmos1.. cosmos1.. --spend-limit 100stake --period 3600 --period-limit 10stake
```
###### With expiration
```shell
simd tx feegrant grant cosmos1.. cosmos1.. --spend-limit 100stake --expiration 2024-10-31T15:04:05Z
```
###### With allowed messages
```shell
simd tx feegrant grant cosmos1.. cosmos1.. --spend-limit 100stake --expiration 2024-10-31T15:04:05Z --allowed-messages "/cosmos.gov.v1beta1.MsgSubmitProposal,/cosmos.gov.v1beta1.MsgVote"
```
Available flags:
- `--spend-limit`: The maximum amount of tokens the grantee can spend
- `--period`: The time duration in seconds for periodic allowance
- `--period-limit`: The maximum amount of tokens the grantee can spend within each period
- `--expiration`: The date and time when the grant expires (RFC3339 format)
- `--allowed-messages`: Comma-separated list of allowed message type URLs
##### revoke
The `revoke` command allows users to revoke a granted fee allowance.