github.com/fibonacci-chain/fbc@v0.0.0-20231124064014-c7636198c1e9/x/wasm/Governance.md (about)

     1  # Governance
     2  
     3  This document gives an overview of how the various governance
     4  proposals interact with the CosmWasm contract lifecycle. It is
     5  a high-level, technical introduction meant to provide context before
     6  looking into the code, or constructing proposals. 
     7  
     8  ## Proposal Types
     9  We have added 9 new wasm specific proposal types that cover the contract's live cycle and authorization:
    10   
    11  * `StoreCodeProposal` - upload a wasm binary
    12  * `InstantiateContractProposal` - instantiate a wasm contract
    13  * `MigrateContractProposal` - migrate a wasm contract to a new code version
    14  * `SudoContractProposal` - call into the protected `sudo` entry point of a contract
    15  * `ExecuteContractProposal` - execute a wasm contract as an arbitrary user
    16  * `UpdateAdminProposal` - set a new admin for a contract
    17  * `ClearAdminProposal` - clear admin for a contract to prevent further migrations
    18  * `PinCodes` - pin the given code ids in cache. This trades memory for reduced startup time and lowers gas cost
    19  * `UnpinCodes` - unpin the given code ids from the cache. This frees up memory and returns to standard speed and gas cost
    20  * `UpdateInstantiateConfigProposal` - update instantiate permissions to a list of given code ids. 
    21  
    22  For details see the proposal type [implementation](https://github.com/fibonacci-chain/fbc/blob/master/x/wasm/types/proposal.go)
    23  
    24  ### Unit tests
    25  [Proposal type validations](https://github.com/fibonacci-chain/fbc/blob/master/x/wasm/types/proposal_test.go)
    26  
    27  ## Proposal Handler
    28  The [wasmd proposal_handler](https://github.com/fibonacci-chain/fbc/blob/master/x/wasm/keeper/proposal_handler.go) implements the `gov.Handler` function
    29  and executes the wasmd proposal types after a successful tally.
    30   
    31  The proposal handler uses a [`GovAuthorizationPolicy`](https://github.com/fibonacci-chain/fbc/blob/master/x/wasm/keeper/authz_policy.go#L29) to bypass the existing contract's authorization policy.
    32  
    33  ### Tests
    34  * [Integration: Submit and execute proposal](https://github.com/fibonacci-chain/fbc/blob/master/x/wasm/keeper/proposal_integration_test.go)
    35  
    36  ## Gov Integration
    37  The wasmd proposal handler can be added to the gov router in the [abci app](https://github.com/fibonacci-chain/fbc/blob/master/app/app.go#L306)
    38  to receive proposal execution calls. 
    39  ```go
    40  govRouter.AddRoute(wasm.RouterKey, wasm.NewWasmProposalHandler(app.wasmKeeper, enabledProposals))
    41  ```
    42  
    43  ## Wasmd Authorization Settings
    44  
    45  Settings via sdk `params` module: 
    46  - `code_upload_access` - who can upload a wasm binary: `Nobody`, `Everybody`, `OnlyAddress`
    47  - `instantiate_default_permission` - platform default, who can instantiate a wasm binary when the code owner has not set it 
    48  
    49  See [params.go](https://github.com/fibonacci-chain/fbc/blob/master/x/wasm/types/params.go)
    50  
    51  ### Init Params Via Genesis 
    52  
    53  ```json
    54      "wasm": {
    55        "params": {
    56          "code_upload_access": {
    57            "permission": "Everybody"
    58          },
    59          "instantiate_default_permission": "Everybody"
    60        }
    61      },  
    62  ```
    63  
    64  The values can be updated via gov proposal implemented in the `params` module.
    65  
    66  ### Update Params Via [ParamChangeProposal](https://github.com/fibonacci-chain/fbc/libs/cosmos-sdk/blob/v0.45.3/proto/cosmos/params/v1beta1/params.proto#L10)
    67  Example to submit a parameter change gov proposal:
    68  ```sh
    69  wasmd tx gov submit-proposal param-change <proposal-json-file> --from validator --chain-id=testing -b block
    70  ```
    71  #### Content examples
    72  * Disable wasm code uploads
    73  ```json
    74  {
    75    "title": "Foo",
    76    "description": "Bar",
    77    "changes": [
    78      {
    79        "subspace": "wasm",
    80        "key": "uploadAccess",
    81        "value": {
    82          "permission": "Nobody"
    83        }
    84      }
    85    ],
    86    "deposit": ""
    87  }
    88  ```
    89  * Allow wasm code uploads for everybody
    90  ```json
    91  {
    92    "title": "Foo",
    93    "description": "Bar",
    94    "changes": [
    95      {
    96        "subspace": "wasm",
    97        "key": "uploadAccess",
    98        "value": {
    99          "permission": "Everybody"
   100        }
   101      }
   102    ],
   103    "deposit": ""
   104  }
   105  ```
   106  
   107  * Restrict code uploads to a single address
   108  ```json
   109  {
   110    "title": "Foo",
   111    "description": "Bar",
   112    "changes": [
   113      {
   114        "subspace": "wasm",
   115        "key": "uploadAccess",
   116        "value": {
   117          "permission": "OnlyAddress",
   118          "address": "cosmos1qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq0fr2sh"
   119        }
   120      }
   121    ],
   122    "deposit": ""
   123  }
   124  ```
   125  * Set chain **default** instantiation settings to nobody
   126  ```json
   127  {
   128    "title": "Foo",
   129    "description": "Bar",
   130    "changes": [
   131      {
   132        "subspace": "wasm",
   133        "key": "instantiateAccess",
   134        "value": "Nobody"
   135      }
   136    ],
   137    "deposit": ""
   138  }
   139  ```
   140  * Set chain **default** instantiation settings to everybody
   141  ```json
   142  {
   143    "title": "Foo",
   144    "description": "Bar",
   145    "changes": [
   146      {
   147        "subspace": "wasm",
   148        "key": "instantiateAccess",
   149        "value": "Everybody"
   150      }
   151    ],
   152    "deposit": ""
   153  }
   154  ```
   155  
   156  ### Enable gov proposals at **compile time**. 
   157  As gov proposals bypass the existing authorization policy they are disabled and require to be enabled at compile time. 
   158  ```
   159  -X github.com/fibonacci-chain/fbc/app.ProposalsEnabled=true - enable all x/wasm governance proposals (default false)
   160  -X github.com/fibonacci-chain/fbc/app.EnableSpecificProposals=MigrateContract,UpdateAdmin,ClearAdmin - enable a subset of the x/wasm governance proposal types (overrides ProposalsEnabled)
   161  ```
   162  
   163  The `ParamChangeProposal` is always enabled.
   164  
   165  ### Tests
   166  * [params validation unit tests](https://github.com/fibonacci-chain/fbc/blob/master/x/wasm/types/params_test.go)
   167  * [genesis validation tests](https://github.com/fibonacci-chain/fbc/blob/master/x/wasm/types/genesis_test.go)
   168  * [policy integration tests](https://github.com/fibonacci-chain/fbc/blob/master/x/wasm/keeper/keeper_test.go)
   169  
   170  ## CLI
   171  
   172  ```shell script
   173    wasmd tx gov submit-proposal [command]
   174  
   175  Available Commands:
   176    wasm-store           Submit a wasm binary proposal
   177    instantiate-contract Submit an instantiate wasm contract proposal
   178    migrate-contract     Submit a migrate wasm contract to a new code version proposal
   179    set-contract-admin   Submit a new admin for a contract proposal
   180    clear-contract-admin Submit a clear admin for a contract to prevent further migrations proposal
   181  ...
   182  ```
   183  ## Rest
   184  New [`ProposalHandlers`](https://github.com/fibonacci-chain/fbc/blob/master/x/wasm/client/proposal_handler.go)
   185  
   186  * Integration
   187  ```shell script
   188  gov.NewAppModuleBasic(append(wasmclient.ProposalHandlers, paramsclient.ProposalHandler, distr.ProposalHandler, upgradeclient.ProposalHandler)...),
   189  ```
   190  In [abci app](https://github.com/fibonacci-chain/fbc/blob/master/app/app.go#L109)
   191  
   192  ### Tests
   193  * [Rest Unit tests](https://github.com/fibonacci-chain/fbc/blob/master/x/wasm/client/proposal_handler_test.go)
   194  * [Rest smoke LCD test](https://github.com/fibonacci-chain/fbc/blob/master/lcd_test/wasm_test.go)
   195  
   196  
   197  
   198  ## Pull requests
   199  * https://github.com/fibonacci-chain/fbc/pull/190
   200  * https://github.com/fibonacci-chain/fbc/pull/186
   201  * https://github.com/fibonacci-chain/fbc/pull/183
   202  * https://github.com/fibonacci-chain/fbc/pull/180
   203  * https://github.com/fibonacci-chain/fbc/pull/179
   204  * https://github.com/fibonacci-chain/fbc/pull/173