wasmd/x/wasm/Governance.md

Governance

This document gives an overview of how the various governance proposals interact with the CosmWasm contract lifecycle. It is 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:

• 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

Unit tests

Proposal type validations

Proposal Handler

The wasmd proposal_handler implements the gov.Handler function and executes the wasmd proposal types after a successful tally.

The proposal handler uses a GovAuthorizationPolicy to bypass the existing contract's authorization policy.

Tests

• Integration: Submit and execute proposal

Gov Integration

The wasmd proposal handler can be added to the gov router in the abci app to receive proposal execution calls.

govRouter.AddRoute(wasm.RouterKey, wasm.NewWasmProposalHandler(app.wasmKeeper, enabledProposals))

Wasmd Authorization Settings

Settings via sdk params module:

• code_upload_access - who can upload a wasm binary: Nobody, Everybody, OnlyAddress
• instantiate_default_permission - platform default, who can instantiate a wasm binary when the code owner has not set it

See params.go

Init Params Via Genesis

    "wasm": {
      "params": {
        "code_upload_access": {
          "permission": "Everybody"
        },
        "instantiate_default_permission": "Everybody"
      }
    },  

The values can be updated via gov proposal implemented in the params module.

Update Params Via ParamChangeProposal

Example to submit a parameter change gov proposal:

wasmd tx gov submit-proposal param-change <proposal-json-file> --from validator --chain-id=testing -b block

Content examples

• Disable wasm code uploads

{
  "title": "Foo",
  "description": "Bar",
  "changes": [
    {
      "subspace": "wasm",
      "key": "uploadAccess",
      "value": {
        "permission": "Nobody"
      }
    }
  ],
  "deposit": ""
}

• Allow wasm code uploads for everybody

{
  "title": "Foo",
  "description": "Bar",
  "changes": [
    {
      "subspace": "wasm",
      "key": "uploadAccess",
      "value": {
        "permission": "Everybody"
      }
    }
  ],
  "deposit": ""
}

• Restrict code uploads to a single address

{
  "title": "Foo",
  "description": "Bar",
  "changes": [
    {
      "subspace": "wasm",
      "key": "uploadAccess",
      "value": {
        "permission": "OnlyAddress",
        "address": "cosmos1qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq0fr2sh"
      }
    }
  ],
  "deposit": ""
}

• Set chain default instantiation settings to nobody

{
  "title": "Foo",
  "description": "Bar",
  "changes": [
    {
      "subspace": "wasm",
      "key": "instantiateAccess",
      "value": "Nobody"
    }
  ],
  "deposit": ""
}

• Set chain default instantiation settings to everybody

{
  "title": "Foo",
  "description": "Bar",
  "changes": [
    {
      "subspace": "wasm",
      "key": "instantiateAccess",
      "value": "Everybody"
    }
  ],
  "deposit": ""
}

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
• genesis validation tests
• policy integration tests

CLI

  wasmd tx gov 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
...

Rest

New ProposalHandlers

• Integration

gov.NewAppModuleBasic(append(wasmclient.ProposalHandlers, paramsclient.ProposalHandler, distr.ProposalHandler, upgradeclient.ProposalHandler)...),

In abci app

Tests

• Rest Unit tests
• Rest smoke LCD test

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