From c271f6096331ad0dc04b1767de579b3bffbde173 Mon Sep 17 00:00:00 2001 From: Pino' Surace Date: Thu, 7 Sep 2023 14:10:52 +0200 Subject: [PATCH] Update files --- UPGRADING.md | 74 +++++++++++++++++++++++ x/wasm/Governance.md | 136 ++++++++++++++++++++----------------------- 2 files changed, 137 insertions(+), 73 deletions(-) diff --git a/UPGRADING.md b/UPGRADING.md index b6cc7dda96..a5e204f2b1 100644 --- a/UPGRADING.md +++ b/UPGRADING.md @@ -208,6 +208,80 @@ docker run --rm -it \ query gov votes 1 ``` +## Vote on the upgrade (Starting from wasmd v0.40.0) + +Starting from `v0.40.0` of `wasmd`, which incorporates cosmos-sdk `v0.47.x`, +there have been changes in how upgrade proposals are handled. Below, +we provide an example of how to achieve the same outcome as described +in the preceding section. + +Please be aware that some commands have been replaced by an interactive +Command Line Interface (CLI), and the process of submitting a proposal +is now divided into two distinct steps: `proposal creation` and `proposal submission`. + +```sh +# create the proposal +docker run --rm -it \ + --mount type=volume,source=musselnet_client,target=/root \ + --network=host \ + cosmwasm/wasmd:v0.40.0 wasmd \ + tx gov draft-proposal \ + --from validator --chain-id testing + +# choose from the interactive CLI and fill all the fields +# of the generated json file draft_proposal.json +# example: +{ + "messages": [ + { + "@type": "/cosmos.upgrade.v1beta1.MsgSoftwareUpgrade", + "authority": "wasm10d07y265gmmuvt4z0w9aw880jnsr700js7zslc", + "plan": { + "name": "Upgrade", + "time": "0001-01-01T00:00:00Z", + "height": "500", + "info": "", + "upgraded_client_state": null + } + } + ], + "metadata": "ipfs://CID", + "deposit": "100000ustake", + "title": "Upgrade", + "summary": "summary" +} + +# submit the proposal +docker run --rm -it \ + --mount type=volume,source=musselnet_client,target=/root \ + --network=host \ + cosmwasm/wasmd:v0.40.0 wasmd \ + tx gov submit-proposal draft_proposal.json \ + --from validator --chain-id testing + +# make sure it looks good +docker run --rm -it \ + --mount type=volume,source=musselnet_client,target=/root \ + --network=host \ + cosmwasm/wasmd:v0.40.0 wasmd \ + query gov proposal 1 + +# vote for it +docker run --rm -it \ + --mount type=volume,source=musselnet_client,target=/root \ + --network=host \ + cosmwasm/wasmd:v0.40.0 wasmd \ + tx gov vote 1 yes \ + --from validator --chain-id testing + +# ensure vote was counted +docker run --rm -it \ + --mount type=volume,source=musselnet_client,target=/root \ + --network=host \ + cosmwasm/wasmd:v0.40.0 wasmd \ + query gov votes 1 +``` + ## Swap out binaries Now, we just wait about 5 minutes for the vote to pass, and ensure it is passed: diff --git a/x/wasm/Governance.md b/x/wasm/Governance.md index da47240c14..d9fdff8284 100644 --- a/x/wasm/Governance.md +++ b/x/wasm/Governance.md @@ -6,45 +6,27 @@ a high-level, technical introduction meant to provide context before looking into the code, or constructing proposals. ## Proposal Types -We have added 9 new wasm specific proposal types that cover the contract's live cycle and authorization: +We have added 15 new wasm specific proposal messages that cover the contract's live cycle and authorization: -* `StoreCodeProposal` - upload a wasm binary -* `InstantiateContractProposal` - instantiate a wasm contract -* `MigrateContractProposal` - migrate a wasm contract to a new code version -* `SudoContractProposal` - call into the protected `sudo` entry point of a contract -* `ExecuteContractProposal` - execute a wasm contract as an arbitrary user -* `UpdateAdminProposal` - set a new admin for a contract -* `ClearAdminProposal` - clear admin for a contract to prevent further migrations -* `PinCodes` - pin the given code ids in cache. This trades memory for reduced startup time and lowers gas cost -* `UnpinCodes` - unpin the given code ids from the cache. This frees up memory and returns to standard speed and gas cost -* `UpdateInstantiateConfigProposal` - update instantiate permissions to a list of given code ids. -* `StoreAndInstantiateContractProposal` - upload and instantiate a wasm contract. - -For details see the proposal type [implementation](https://github.com/CosmWasm/wasmd/blob/master/x/wasm/types/proposal.go) - -### Unit tests -[Proposal type validations](https://github.com/CosmWasm/wasmd/blob/master/x/wasm/types/proposal_test.go) - -## Proposal Handler -The [wasmd proposal_handler](https://github.com/CosmWasm/wasmd/blob/master/x/wasm/keeper/proposal_handler.go) implements the `gov.Handler` function -and executes the wasmd proposal types after a successful tally. - -The proposal handler uses a [`GovAuthorizationPolicy`](https://github.com/CosmWasm/wasmd/blob/master/x/wasm/keeper/authz_policy.go#L29) to bypass the existing contract's authorization policy. - -### Tests -* [Integration: Submit and execute proposal](https://github.com/CosmWasm/wasmd/blob/master/x/wasm/keeper/proposal_integration_test.go) - -## Gov Integration -The wasmd proposal handler can be added to the gov router in the [abci app](https://github.com/CosmWasm/wasmd/blob/master/app/app.go#L306) -to receive proposal execution calls. -```go -govRouter.AddRoute(wasm.RouterKey, wasm.NewWasmProposalHandler(app.wasmKeeper, enabledProposals)) -``` +* `MsgStoreCode` - upload a wasm binary +* `MsgInstantiateContract` - instantiate a wasm contract +* `MsgInstantiateContract2` - instantiate a wasm contract with a predictable address +* `MsgMigrateContract` - migrate a wasm contract to a new code version +* `MsgSudoContract` - call into the protected `sudo` entry point of a contract +* `MsgExecuteContract` - execute a wasm contract as an arbitrary user +* `MsgUpdateAdmin` - set a new admin for a contract +* `MsgClearAdmin` - clear admin for a contract to prevent further migrations +* `MsgPinCodes` - pin the given code ids in cache. This trades memory for reduced startup time and lowers gas cost +* `MsgUnpinCodes` - unpin the given code ids from the cache. This frees up memory and returns to standard speed and gas cost +* `MsgUpdateInstantiateConfig` - update instantiate permissions to a list of given code ids. +* `MsgStoreAndInstantiateContract` - upload and instantiate a wasm contract. +* `MsgRemoveCodeUploadParamsAddresses` - remove addresses from code upload params. +* `MsgAddCodeUploadParamsAddresses` - add addresses to code upload params. ## Wasmd Authorization Settings Settings via sdk `params` module: -- `code_upload_access` - who can upload a wasm binary: `Nobody`, `Everybody`, `OnlyAddress` +- `code_upload_access` - who can upload a wasm binary: `Nobody`, `Everybody`, `AnyOfAddresses` - `instantiate_default_permission` - platform default, who can instantiate a wasm binary when the code owner has not set it See [params.go](https://github.com/CosmWasm/wasmd/blob/master/x/wasm/types/params.go) @@ -62,12 +44,19 @@ See [params.go](https://github.com/CosmWasm/wasmd/blob/master/x/wasm/types/param }, ``` -The values can be updated via gov proposal implemented in the `params` module. +The values can be updated via gov proposal `MsgUpdateParams`. -### Update Params Via [ParamChangeProposal](https://github.com/cosmos/cosmos-sdk/blob/v0.45.3/proto/cosmos/params/v1beta1/params.proto#L10) +### Update Params Via [MsgUpdateParams](https://github.com/CosmWasm/wasmd/blob/v0.41.0/proto/cosmwasm/wasm/v1/tx.proto#L263) Example to submit a parameter change gov proposal: + +- First create a draft proposal using the interactive CLI +```sh +wasmd tx gov draft-proposal +``` + +- Submit the proposal ```sh -wasmd tx gov submit-proposal param-change --from validator --chain-id=testing -b block +wasmd tx gov submit-proposal --from validator --chain-id=testing -b block ``` #### Content examples * Disable wasm code uploads @@ -115,14 +104,34 @@ wasmd tx gov submit-proposal param-change --from validator "subspace": "wasm", "key": "uploadAccess", "value": { - "permission": "OnlyAddress", - "address": "cosmos1qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq0fr2sh" + "permission": "AnyOfAddresses", + "addresses": ["cosmos1qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq0fr2sh"] } } ], "deposit": "" } ``` + +* Restrict code uploads to two addresses +```json +{ + "title": "Foo", + "description": "Bar", + "changes": [ + { + "subspace": "wasm", + "key": "uploadAccess", + "value": { + "permission": "AnyOfAddresses", + "addresses": ["cosmos1qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq0fr2sh", "cosmos1bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb0fr2sh"] + } + } + ], + "deposit": "" +} +``` + * Set chain **default** instantiation settings to nobody ```json { @@ -154,15 +163,6 @@ wasmd tx gov submit-proposal param-change --from validator } ``` -### Enable gov proposals at **compile time**. -As gov proposals bypass the existing authorization policy they are disabled and require to be enabled at compile time. -``` --X github.com/CosmWasm/wasmd/app.ProposalsEnabled=true - enable all x/wasm governance proposals (default false) --X github.com/CosmWasm/wasmd/app.EnableSpecificProposals=MigrateContract,UpdateAdmin,ClearAdmin - enable a subset of the x/wasm governance proposal types (overrides ProposalsEnabled) -``` - -The `ParamChangeProposal` is always enabled. - ### Tests * [params validation unit tests](https://github.com/CosmWasm/wasmd/blob/master/x/wasm/types/params_test.go) * [genesis validation tests](https://github.com/CosmWasm/wasmd/blob/master/x/wasm/types/genesis_test.go) @@ -171,35 +171,25 @@ The `ParamChangeProposal` is always enabled. ## CLI ```shell script - wasmd tx gov submit-proposal [command] + wasmd tx wasm submit-proposal [command] Available Commands: - wasm-store Submit a wasm binary proposal - instantiate-contract Submit an instantiate wasm contract proposal - migrate-contract Submit a migrate wasm contract to a new code version proposal - set-contract-admin Submit a new admin for a contract proposal - clear-contract-admin Submit a clear admin for a contract to prevent further migrations proposal + add-code-upload-params-addresses Submit an add code upload params addresses proposal to add addresses to code upload config params + clear-contract-admin Submit a clear admin for a contract to prevent further migrations proposal + execute-contract Submit a execute wasm contract proposal (run by any address) + instantiate-contract Submit an instantiate wasm contract proposal + instantiate-contract-2 Submit an instantiate wasm contract proposal with predictable address + migrate-contract Submit a migrate wasm contract to a new code version proposal + pin-codes Submit a pin code proposal for pinning a code to cache + remove-code-upload-params-addresses Submit a remove code upload params addresses proposal to remove addresses from code upload config params + set-contract-admin Submit a new admin for a contract proposal + store-instantiate Submit and instantiate a wasm contract proposal + sudo-contract Submit a sudo wasm contract proposal (to call privileged commands) + unpin-codes Submit a unpin code proposal for unpinning a code to cache + update-instantiate-config Submit an update instantiate config proposal. + wasm-store Submit a wasm binary proposal ... ``` -## Rest -New [`ProposalHandlers`](https://github.com/CosmWasm/wasmd/blob/master/x/wasm/client/proposal_handler.go) - -* Integration -```shell script -gov.NewAppModuleBasic(append(wasmclient.ProposalHandlers, paramsclient.ProposalHandler, distr.ProposalHandler, upgradeclient.ProposalHandler)...), -``` -In [abci app](https://github.com/CosmWasm/wasmd/blob/master/app/app.go#L109) - -### Tests -* [Rest Unit tests](https://github.com/CosmWasm/wasmd/blob/master/x/wasm/client/proposal_handler_test.go) -* [Rest smoke LCD test](https://github.com/CosmWasm/wasmd/blob/master/lcd_test/wasm_test.go) -## Pull requests -* https://github.com/CosmWasm/wasmd/pull/190 -* https://github.com/CosmWasm/wasmd/pull/186 -* https://github.com/CosmWasm/wasmd/pull/183 -* https://github.com/CosmWasm/wasmd/pull/180 -* https://github.com/CosmWasm/wasmd/pull/179 -* https://github.com/CosmWasm/wasmd/pull/173