Skip to content

Commit

Permalink
Update files
Browse files Browse the repository at this point in the history
  • Loading branch information
@pinosu
pinosu committed Sep 7, 2023
1 parent 4a58649 commit c271f60
Show file tree
Hide file tree
Showing 2 changed files with 137 additions and 73 deletions.
74 changes: 74 additions & 0 deletions UPGRADING.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 <software-upgrade> 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:
Expand Down
136 changes: 63 additions & 73 deletions x/wasm/Governance.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand All @@ -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 <proposal-json-file> --from validator --chain-id=testing -b block
wasmd tx gov submit-proposal <proposal-json-file> --from validator --chain-id=testing -b block
```
#### Content examples
* Disable wasm code uploads
Expand Down Expand Up @@ -115,14 +104,34 @@ wasmd tx gov submit-proposal param-change <proposal-json-file> --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
{
Expand Down Expand Up @@ -154,15 +163,6 @@ wasmd tx gov submit-proposal param-change <proposal-json-file> --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)
Expand All @@ -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

0 comments on commit c271f60

Please sign in to comment.