Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: state-compatibility documentation #2514

Merged
merged 10 commits into from
Aug 29, 2022
Merged

Conversation

p0mvn
Copy link
Member

@p0mvn p0mvn commented Aug 26, 2022

Closes: #XXX

What is the purpose of the change

Add documentation for state-compatibility safety, patch and minor releases.

Brief Changelog

This change is a trivial rework / code cleanup without any test coverage.

Documentation and Release Note

  • Does this pull request introduce a new feature or user-facing behavior changes? no
  • Is a relevant changelog entry added to the Unreleased section in CHANGELOG.md? no
  • How is the feature or change documented? not applicable

@p0mvn p0mvn marked this pull request as ready for review August 26, 2022 01:43
@p0mvn p0mvn requested a review from a team August 26, 2022 01:43
@p0mvn
Copy link
Member Author

p0mvn commented Aug 26, 2022

Todo: mention historical queries that can be pruned

Copy link
Contributor

@AlpinYukseloglu AlpinYukseloglu left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Awesome addition, well overdue. Thanks for adding this! Left a couple comments but overall I think the main points are covered

Copy link
Member

@czarcas7ic czarcas7ic left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM! 🚀

CONTRIBUTING.md Outdated
Comment on lines 388 to 406
Version A
```go
func (sk Keeper) validateAmount(ctx context.Context, amount sdk.Int) error {
if amount.IsNegative() {
return sdkerrors.Wrap(sdkerrors.ErrInvalidRequest, "amount must be positive or zero")
}
return nil, errors.New("error")
}
```

Version B
```go
func (sk Keeper) validateAmount(ctx context.Context, amount sdk.Int) error {
if amount.IsNegative() || amount.IsZero() {
return sdkerrors.Wrap(sdkerrors.ErrInvalidRequest, "amount must be positive")
}
return nil, errors.New("error")
}
```
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Wouldn't this also be state incompatible for a second reason? Not only is 0 now returning a different result, but now a negative number also returns a different error response right?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That's a good observation.

It seems to me that the error message does not affect things unless we store it in state for some reason which really should never happen.

However, if we were to change error code, that would cause an issue. As per Dev's comment:
#2514 (comment)

there is a transaction response code that gets included in the LastResultsHash. This is what the error code here seems to represent. So we should be really careful about error codes. I will add a section about that

Copy link
Member

@mattverse mattverse left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looking good! This is one of the documentations that we have needed!

Would it be possible to also add docs about changes of Queries and Msgs?

CONTRIBUTING.md Outdated
Therefore, we introduced a state-incompatibility by merklezing diverging gas
usage.

##### Network Requests
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can we specify what we mean by network requests here?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This specific part refers to querying external services, for example, some API for getting exchange rates. This is not allowed since such API might be unavailable in some regions, rate limit or just be down.

I haven't seen anyone doing that but I think it might make sense to mention for beginners since querying an API is a common activity in other systems


#### Sources of State-incompatibility

##### Creating Additional State
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We should also handle Changing Existing State(Ex changing of existing proto field)

CONTRIBUTING.md Outdated
Comment on lines 368 to 373
The state compatibility is ensured by taking the app hash of the state and comparing it
to the app hash with the rest of the network. Essentially, an app hash is a hash of
hashes of every store's Merkle root.

For example, at height n, we compute:
`app hash = hash(hash(root of x/epochs), hash(root of x/gamm)...)`
Copy link
Member

@ValarDragon ValarDragon Aug 26, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We should also probably note the LastResultsHash for tx results matters as well: https://github.com/tendermint/tendermint/blob/main/proto/tendermint/types/types.proto#L70-L77

(The other hashes are unlikely to be an issue / you don't really have to separately think about)

The LastResultsHash today contains:
https://github.com/tendermint/tendermint/blob/main/types/results.go#L47-L54

  • Tx GasWanted
  • Tx GasUsed
  • Tx response "Data"
  • Tx response "Code"

The data field includes the proto message response (therefore we cannot change these in patch releases). Tbh idk what the Code field does, as far as I can tell its not even used: https://github.com/cosmos/cosmos-sdk/blob/main/baseapp/abci.go#L298-L304

The gas used field being merkelized means that:

  • right now we cannot change the order of operations within a tx execution (different gas used in edge cases of out of gas'ing)
    • Therefore we must be worried about refactoring errors earlier in the tx stack
  • We cannot change gas usage amounts (e.g. removing extraneous store reads)

Gas used being merkelized is slated for removal in a subsequent Tendermint release, at which point we will have more flexibility in reordering operations / erroring.

Note that these all stem from DeliverTx execution path, which handles:

  • AnteHandler's marked as deliver tx
  • msg.ValidateBasic
  • execution of a message from the message server

AnteHandlers with CheckTx fields can always change at the moment.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks! Great points

re: code

Apparently, it seems to be used when an error is returned. I discussed this briefly here:
#2514 (comment)

Planning to include a few sentences on it.

CONTRIBUTING.md Outdated
Comment on lines 448 to 450
It is critical to avoid performing network requests since it is common
for services to be unavailable or rate-limit. As a result, nodes
may get diverging responses, leading to state breakage.
Copy link
Member

@ValarDragon ValarDragon Aug 26, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hrmm not sure I follow. Maybe we can clarify by stating what is the state machine scope, which is:

  • All messages supported by the chain
  • Tx gas usage
  • Queries in {whitelist file}
  • All BeginBlock/Endblock logic

Importantly the following are not state machine versioned:

  • Events
  • Queries not in the whitelist file
  • CLI interfaces

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Will add the suggestions.

This specific part refers to querying external services, for example, some API for getting exchange rates. This is not allowed since such API might be unavailable in some regions, rate limit or just be down.

@p0mvn p0mvn marked this pull request as draft August 26, 2022 19:15
@p0mvn p0mvn marked this pull request as ready for review August 26, 2022 22:59
@p0mvn
Copy link
Member Author

p0mvn commented Aug 26, 2022

Pretty sure I covered all suggestions in the updates. Please let me know what you all think

Copy link
Member

@ValarDragon ValarDragon left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nice work!

@ValarDragon ValarDragon merged commit 9dc45d9 into main Aug 29, 2022
@ValarDragon ValarDragon deleted the roman/state-compatibility branch August 29, 2022 11:02
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

5 participants