From 9f543b1c3b3d51e8f310fa9ca848d6b101c93f4c Mon Sep 17 00:00:00 2001 From: Ivan Gavran Date: Sun, 3 Apr 2022 11:50:51 +0200 Subject: [PATCH] refactor: Small clarifications to authz docs and one error description (#11506) ## Description This small PR is trying to clarify the documentation that I found ambiguous when reading it. Furthermore, it makes one error message more precise ("non-negative" --> "positive"). In particular: - I clarified that the field `AcceptResponse.Accept` will be set to `true` when an authorization is accepted, but **will not** be set to `false` otherwise (instead, the function `Accept` will return an error). - I clarified that the field `AcceptResponse.Updated` will not always be populated: it will be `nil` unless there are real changes to the authorization - I changed the error message in the `send_authorization.go` function, when `IsAllPositive()` returns `false` from _spend limit cannot be negitive_ to _spend limit must be positive_. I emphasized the fact that spend limit must be positive in the documentation. This is my first contribution to the Cosmos-SDK codebase so if I made some mistake the process (wrt the checklist), guide me patiently, pls. --- ### Author Checklist *All items are required. Please add a note to the item if the item is not applicable and please add links to any relevant follow up issues.* I have... - [x] included the correct [type prefix](https://github.com/commitizen/conventional-commit-types/blob/v3.0.0/index.json) in the PR title - [x] added `!` to the type prefix if API or client breaking change - [x] targeted the correct branch (see [PR Targeting](https://github.com/cosmos/cosmos-sdk/blob/master/CONTRIBUTING.md#pr-targeting)) - [ ] provided a link to the relevant issue or specification: NOTE: does not apply, these are clarification changes - [ ] followed the guidelines for [building modules](https://github.com/cosmos/cosmos-sdk/blob/master/docs/building-modules): NOTE: does not apply, these are clarification changes - [ ] included the necessary unit and integration [tests](https://github.com/cosmos/cosmos-sdk/blob/master/CONTRIBUTING.md#testing): NOTE: does not apply, these are clarification changes - [ ] added a changelog entry to `CHANGELOG.md`: NOTE: does not apply, these are clarification changes - [ ] included comments for [documenting Go code](https://blog.golang.org/godoc) NOTE: does not apply, these are clarification changes - [x] updated the relevant documentation or specification - [x] reviewed "Files changed" and left comments if necessary - [ ] confirmed all CI checks have passed ### Reviewers Checklist *All items are required. Please add a note if the item is not applicable and please add your handle next to the items reviewed if you only reviewed selected items.* I have... - [ ] confirmed the correct [type prefix](https://github.com/commitizen/conventional-commit-types/blob/v3.0.0/index.json) in the PR title - [ ] confirmed `!` in the type prefix if API or client breaking change - [ ] confirmed all author checklist items have been addressed - [ ] reviewed state machine logic - [ ] reviewed API design and naming - [ ] reviewed documentation is accurate - [ ] reviewed tests and test coverage - [ ] manually tested (if applicable) --- docs/architecture/adr-030-authz-module.md | 9 +++++++++ x/authz/spec/01_concepts.md | 2 +- x/bank/types/send_authorization.go | 2 +- 3 files changed, 11 insertions(+), 2 deletions(-) diff --git a/docs/architecture/adr-030-authz-module.md b/docs/architecture/adr-030-authz-module.md index 0bdf08ecb6..b9c0720e10 100644 --- a/docs/architecture/adr-030-authz-module.md +++ b/docs/architecture/adr-030-authz-module.md @@ -117,6 +117,15 @@ A different type of capability for `MsgSend` could be implemented using the `Authorization` interface with no need to change the underlying `bank` module. +##### Small notes on `AcceptResponse` + +- The `AcceptResponse.Accept` field will be set to `true` if the authorization is accepted. +However, if it is rejected, the function `Accept` will raise an error (without setting `AcceptResponse.Accept` to `false`). + +- The `AcceptResponse.Updated` field will be set to a non-nil value only if there is a real change to the authorization. +If authorization remains the same (as is, for instance, always the case for a [`GenericAuthorization`](#genericauthorization)), +the field will be `nil`. + ### `Msg` Service ```proto diff --git a/x/authz/spec/01_concepts.md b/x/authz/spec/01_concepts.md index cfa46a09f0..c4cc63acc4 100644 --- a/x/authz/spec/01_concepts.md +++ b/x/authz/spec/01_concepts.md @@ -32,7 +32,7 @@ The Cosmos SDK `x/authz` module comes with following authorization types: ### SendAuthorization -`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. The `SpendLimit` is updated as the tokens are spent. +`SendAuthorization` implements the `Authorization` interface for the `cosmos.bank.v1beta1.MsgSend` Msg. It takes a (positive) `SpendLimit` that specifies the maximum amount of tokens the grantee can spend. The `SpendLimit` is updated as the tokens are spent. +++ https://github.com/cosmos/cosmos-sdk/blob/v0.43.0-beta1/proto/cosmos/bank/v1beta1/authz.proto#L10-L19 diff --git a/x/bank/types/send_authorization.go b/x/bank/types/send_authorization.go index 75a47cdf0d..08a7b641fe 100644 --- a/x/bank/types/send_authorization.go +++ b/x/bank/types/send_authorization.go @@ -45,7 +45,7 @@ func (a SendAuthorization) ValidateBasic() error { return sdkerrors.ErrInvalidCoins.Wrap("spend limit cannot be nil") } if !a.SpendLimit.IsAllPositive() { - return sdkerrors.ErrInvalidCoins.Wrapf("spend limit cannot be negitive") + return sdkerrors.ErrInvalidCoins.Wrapf("spend limit must be positive") } return nil }