wasmd/docs/proto/proto.md

37 KiB
Raw Permalink Blame History

Protocol Documentation

Table of Contents

Top

x/wasm/types/genesis.proto

Code

Code struct encompasses CodeInfo and CodeBytes

Field Type Label Description
code_id uint64
code_info CodeInfo
code_bytes bytes
pinned bool Pinned to wasmvm cache

Contract

Contract struct encompasses ContractAddress, ContractInfo, and ContractState

Field Type Label Description
contract_address string
contract_info ContractInfo
contract_state Model repeated

GenesisState

GenesisState - genesis state of x/wasm

Field Type Label Description
params Params
codes Code repeated
contracts Contract repeated
sequences Sequence repeated
gen_msgs GenesisState.GenMsgs repeated

GenesisState.GenMsgs

GenMsgs define the messages that can be executed during genesis phase in order. The intention is to have more human readable data that is auditable.

Field Type Label Description
store_code MsgStoreCode
instantiate_contract MsgInstantiateContract
execute_contract MsgExecuteContract

Sequence

Sequence key and value of an id generation counter

Field Type Label Description
id_key bytes
value uint64

Top

x/wasm/types/ibc.proto

MsgIBCCloseChannel

MsgIBCCloseChannel port and channel need to be owned by the contract

Field Type Label Description
channel string

MsgIBCSend

MsgIBCSend

Field Type Label Description
channel string the channel by which the packet will be sent
timeout_height uint64 Timeout height relative to the current block height. The timeout is disabled when set to 0.
timeout_timestamp uint64 Timeout timestamp (in nanoseconds) relative to the current block timestamp. The timeout is disabled when set to 0.
data bytes data is the payload to transfer

Top

x/wasm/types/proposal.proto

ClearAdminProposal

ClearAdminProposal gov proposal content type to clear the admin of a contract.

Field Type Label Description
title string Title is a short summary
description string Description is a human readable text
contract string Contract is the address of the smart contract

InstantiateContractProposal

InstantiateContractProposal gov proposal content type to instantiate a contract.

Field Type Label Description
title string Title is a short summary
description string Description is a human readable text
run_as string RunAs is the address that is passed to the contract's environment as sender
admin string Admin is an optional address that can execute migrations
code_id uint64 CodeID is the reference to the stored WASM code
label string Label is optional metadata to be stored with a constract instance.
init_msg bytes InitMsg json encoded message to be passed to the contract on instantiation
funds cosmos.base.v1beta1.Coin repeated Funds coins that are transferred to the contract on instantiation

MigrateContractProposal

MigrateContractProposal gov proposal content type to migrate a contract.

Field Type Label Description
title string Title is a short summary
description string Description is a human readable text
run_as string RunAs is the address that is passed to the contract's environment as sender
contract string Contract is the address of the smart contract
code_id uint64 CodeID references the new WASM code
migrate_msg bytes MigrateMsg json encoded message to be passed to the contract on migration

PinCodesProposal

PinCodesProposal gov proposal content type to pin a set of code ids in the wasmvm cache.

Field Type Label Description
title string Title is a short summary
description string Description is a human readable text
code_ids uint64 repeated CodeIDs references the new WASM codes

StoreCodeProposal

StoreCodeProposal gov proposal content type to submit WASM code to the system

Field Type Label Description
title string Title is a short summary
description string Description is a human readable text
run_as string RunAs is the address that is passed to the contract's environment as sender
wasm_byte_code bytes WASMByteCode can be raw or gzip compressed
source string Source is a valid absolute HTTPS URI to the contract's source code, optional
builder string Builder is a valid docker image name with tag, optional
instantiate_permission AccessConfig InstantiatePermission to apply on contract creation, optional

UnpinCodesProposal

UnpinCodesProposal gov proposal content type to unpin a set of code ids in the wasmvm cache.

Field Type Label Description
title string Title is a short summary
description string Description is a human readable text
code_ids uint64 repeated CodeIDs references the WASM codes

UpdateAdminProposal

UpdateAdminProposal gov proposal content type to set an admin for a contract.

Field Type Label Description
title string Title is a short summary
description string Description is a human readable text
new_admin string NewAdmin address to be set
contract string Contract is the address of the smart contract

Top

x/wasm/types/query.proto

CodeInfoResponse

CodeInfoResponse contains code meta data from CodeInfo

Field Type Label Description
code_id uint64 id for legacy support
creator string
data_hash bytes
source string
builder string

ContractInfoWithAddress

ContractInfoWithAddress adds the address (key) to the ContractInfo representation

Field Type Label Description
address string
contract_info ContractInfo

QueryAllContractStateRequest

QueryAllContractStateRequest is the request type for the Query/AllContractState RPC method

Field Type Label Description
address string address is the address of the contract
pagination cosmos.base.query.v1beta1.PageRequest pagination defines an optional pagination for the request.

QueryAllContractStateResponse

QueryAllContractStateResponse is the response type for the Query/AllContractState RPC method

Field Type Label Description
models Model repeated
pagination cosmos.base.query.v1beta1.PageResponse pagination defines the pagination in the response.

QueryCodeRequest

QueryCodeRequest is the request type for the Query/Code RPC method

Field Type Label Description
code_id uint64 grpc-gateway_out does not support Go style CodID

QueryCodeResponse

QueryCodeResponse is the response type for the Query/Code RPC method

Field Type Label Description
code_info CodeInfoResponse
data bytes

QueryCodesRequest

QueryCodesRequest is the request type for the Query/Codes RPC method

Field Type Label Description
pagination cosmos.base.query.v1beta1.PageRequest pagination defines an optional pagination for the request.

QueryCodesResponse

QueryCodesResponse is the response type for the Query/Codes RPC method

Field Type Label Description
code_infos CodeInfoResponse repeated
pagination cosmos.base.query.v1beta1.PageResponse pagination defines the pagination in the response.

QueryContractHistoryRequest

QueryContractHistoryRequest is the request type for the Query/ContractHistory RPC method

Field Type Label Description
address string address is the address of the contract to query
pagination cosmos.base.query.v1beta1.PageRequest pagination defines an optional pagination for the request.

QueryContractHistoryResponse

QueryContractHistoryResponse is the response type for the Query/ContractHistory RPC method

Field Type Label Description
entries ContractCodeHistoryEntry repeated
pagination cosmos.base.query.v1beta1.PageResponse pagination defines the pagination in the response.

QueryContractInfoRequest

QueryContractInfoRequest is the request type for the Query/ContractInfo RPC method

Field Type Label Description
address string address is the address of the contract to query

QueryContractInfoResponse

QueryContractInfoResponse is the response type for the Query/ContractInfo RPC method

Field Type Label Description
address string address is the address of the contract
contract_info ContractInfo

QueryContractsByCodeRequest

QueryContractsByCodeRequest is the request type for the Query/ContractsByCode RPC method

Field Type Label Description
code_id uint64 grpc-gateway_out does not support Go style CodID
pagination cosmos.base.query.v1beta1.PageRequest pagination defines an optional pagination for the request.

QueryContractsByCodeResponse

QueryContractsByCodeResponse is the response type for the Query/ContractsByCode RPC method

Field Type Label Description
contract_infos ContractInfoWithAddress repeated
pagination cosmos.base.query.v1beta1.PageResponse pagination defines the pagination in the response.

QueryRawContractStateRequest

QueryRawContractStateRequest is the request type for the Query/RawContractState RPC method

Field Type Label Description
address string address is the address of the contract
query_data bytes

QueryRawContractStateResponse

QueryRawContractStateResponse is the response type for the Query/RawContractState RPC method

Field Type Label Description
data bytes Data contains the raw store data

QuerySmartContractStateRequest

QuerySmartContractStateRequest is the request type for the Query/SmartContractState RPC method

Field Type Label Description
address string address is the address of the contract
query_data bytes QueryData contains the query data passed to the contract

QuerySmartContractStateResponse

QuerySmartContractStateResponse is the response type for the Query/SmartContractState RPC method

Field Type Label Description
data bytes Data contains the json data returned from the smart contract

Query

Query provides defines the gRPC querier service

Method Name Request Type Response Type Description
ContractInfo QueryContractInfoRequest QueryContractInfoResponse ContractInfo gets the contract meta data
ContractHistory QueryContractHistoryRequest QueryContractHistoryResponse ContractHistory gets the contract code history
ContractsByCode QueryContractsByCodeRequest QueryContractsByCodeResponse ContractsByCode lists all smart contracts for a code id
AllContractState QueryAllContractStateRequest QueryAllContractStateResponse AllContractState gets all raw store data for a single contract
RawContractState QueryRawContractStateRequest QueryRawContractStateResponse RawContractState gets single key from the raw store data of a contract
SmartContractState QuerySmartContractStateRequest QuerySmartContractStateResponse SmartContractState get smart query result from the contract
Code QueryCodeRequest QueryCodeResponse Code gets the binary code and metadata for a singe wasm code
Codes QueryCodesRequest QueryCodesResponse Codes gets the metadata for all stored wasm codes

Top

x/wasm/types/tx.proto

MsgClearAdmin

MsgClearAdmin removes any admin stored for a smart contract

Field Type Label Description
sender string Sender is the that actor that signed the messages
contract string Contract is the address of the smart contract

MsgClearAdminResponse

MsgClearAdminResponse returns empty data

MsgExecuteContract

MsgExecuteContract submits the given message data to a smart contract

Field Type Label Description
sender string Sender is the that actor that signed the messages
contract string Contract is the address of the smart contract
msg bytes Msg json encoded message to be passed to the contract
funds cosmos.base.v1beta1.Coin repeated Funds coins that are transferred to the contract on execution

MsgExecuteContractResponse

MsgExecuteContractResponse returns execution result data.

Field Type Label Description
data bytes Data contains base64-encoded bytes to returned from the contract

MsgInstantiateContract

MsgInstantiateContract create a new smart contract instance for the given code id.

Field Type Label Description
sender string Sender is the that actor that signed the messages
admin string Admin is an optional address that can execute migrations
code_id uint64 CodeID is the reference to the stored WASM code
label string Label is optional metadata to be stored with a contract instance.
init_msg bytes InitMsg json encoded message to be passed to the contract on instantiation
funds cosmos.base.v1beta1.Coin repeated Funds coins that are transferred to the contract on instantiation

MsgInstantiateContractResponse

MsgInstantiateContractResponse return instantiation result data

Field Type Label Description
address string Address is the bech32 address of the new contract instance.
data bytes Data contains base64-encoded bytes to returned from the contract

MsgMigrateContract

MsgMigrateContract runs a code upgrade/ downgrade for a smart contract

Field Type Label Description
sender string Sender is the that actor that signed the messages
contract string Contract is the address of the smart contract
code_id uint64 CodeID references the new WASM code
migrate_msg bytes MigrateMsg json encoded message to be passed to the contract on migration

MsgMigrateContractResponse

MsgMigrateContractResponse returns contract migration result data.

Field Type Label Description
data bytes Data contains same raw bytes returned as data from the wasm contract. (May be empty)

MsgStoreCode

MsgStoreCode submit Wasm code to the system

Field Type Label Description
sender string Sender is the that actor that signed the messages
wasm_byte_code bytes WASMByteCode can be raw or gzip compressed
source string Source is a valid absolute HTTPS URI to the contract's source code, optional
builder string Builder is a valid docker image name with tag, optional
instantiate_permission AccessConfig InstantiatePermission access control to apply on contract creation, optional

MsgStoreCodeResponse

MsgStoreCodeResponse returns store result data.

Field Type Label Description
code_id uint64 CodeID is the reference to the stored WASM code

MsgUpdateAdmin

MsgUpdateAdmin sets a new admin for a smart contract

Field Type Label Description
sender string Sender is the that actor that signed the messages
new_admin string NewAdmin address to be set
contract string Contract is the address of the smart contract

MsgUpdateAdminResponse

MsgUpdateAdminResponse returns empty data

Msg

Msg defines the wasm Msg service.

Method Name Request Type Response Type Description
StoreCode MsgStoreCode MsgStoreCodeResponse StoreCode to submit Wasm code to the system
InstantiateContract MsgInstantiateContract MsgInstantiateContractResponse Instantiate creates a new smart contract instance for the given code id.
ExecuteContract MsgExecuteContract MsgExecuteContractResponse Execute submits the given message data to a smart contract
MigrateContract MsgMigrateContract MsgMigrateContractResponse Migrate runs a code upgrade/ downgrade for a smart contract
UpdateAdmin MsgUpdateAdmin MsgUpdateAdminResponse UpdateAdmin sets a new admin for a smart contract
ClearAdmin MsgClearAdmin MsgClearAdminResponse ClearAdmin removes any admin stored for a smart contract

Top

x/wasm/types/types.proto

AbsoluteTxPosition

AbsoluteTxPosition is a unique transaction position that allows for global ordering of transactions.

Field Type Label Description
block_height uint64 BlockHeight is the block the contract was created at
tx_index uint64 TxIndex is a monotonic counter within the block (actual transaction index, or gas consumed)

AccessConfig

AccessConfig access control type.

Field Type Label Description
permission AccessType
address string

AccessTypeParam

AccessTypeParam

Field Type Label Description
value AccessType

CodeInfo

CodeInfo is data for the uploaded contract WASM code

Field Type Label Description
code_hash bytes CodeHash is the unique identifier created by wasmvm
creator string Creator address who initially stored the code
source string Source is a valid absolute HTTPS URI to the contract's source code, optional
builder string Builder is a valid docker image name with tag, optional
instantiate_config AccessConfig InstantiateConfig access control to apply on contract creation, optional

ContractCodeHistoryEntry

ContractCodeHistoryEntry metadata to a contract.

Field Type Label Description
operation ContractCodeHistoryOperationType
code_id uint64 CodeID is the reference to the stored WASM code
updated AbsoluteTxPosition Updated Tx position when the operation was executed.
msg bytes

ContractInfo

ContractInfo stores a WASM contract instance

Field Type Label Description
code_id uint64 CodeID is the reference to the stored Wasm code
creator string Creator address who initially instantiated the contract
admin string Admin is an optional address that can execute migrations
label string Label is optional metadata to be stored with a contract instance.
created AbsoluteTxPosition Created Tx position when the contract was instantiated. This data should kept internal and not be exposed via query results. Just use for sorting
ibc_port_id string

Model

Model is a struct that holds a KV pair

Field Type Label Description
key bytes hex-encode key to read it better (this is often ascii)
value bytes base64-encode raw value

Params

Params defines the set of wasm parameters.

Field Type Label Description
code_upload_access AccessConfig
instantiate_default_permission AccessType
max_wasm_code_size uint64

AccessType

AccessType permission types

Name Number Description
ACCESS_TYPE_UNSPECIFIED 0 AccessTypeUnspecified placeholder for empty value
ACCESS_TYPE_NOBODY 1 AccessTypeNobody forbidden
ACCESS_TYPE_ONLY_ADDRESS 2 AccessTypeOnlyAddress restricted to an address
ACCESS_TYPE_EVERYBODY 3 AccessTypeEverybody unrestricted

ContractCodeHistoryOperationType

ContractCodeHistoryOperationType actions that caused a code change

Name Number Description
CONTRACT_CODE_HISTORY_OPERATION_TYPE_UNSPECIFIED 0 ContractCodeHistoryOperationTypeUnspecified placeholder for empty value
CONTRACT_CODE_HISTORY_OPERATION_TYPE_INIT 1 ContractCodeHistoryOperationTypeInit on chain contract instantiation
CONTRACT_CODE_HISTORY_OPERATION_TYPE_MIGRATE 2 ContractCodeHistoryOperationTypeMigrate code migration
CONTRACT_CODE_HISTORY_OPERATION_TYPE_GENESIS 3 ContractCodeHistoryOperationTypeGenesis based on genesis data

Scalar Value Types

.proto Type Notes C++ Java Python Go C# PHP Ruby
double double double float float64 double float Float
float float float float float32 float float Float
int32 Uses variable-length encoding. Inefficient for encoding negative numbers if your field is likely to have negative values, use sint32 instead. int32 int int int32 int integer Bignum or Fixnum (as required)
int64 Uses variable-length encoding. Inefficient for encoding negative numbers if your field is likely to have negative values, use sint64 instead. int64 long int/long int64 long integer/string Bignum
uint32 Uses variable-length encoding. uint32 int int/long uint32 uint integer Bignum or Fixnum (as required)
uint64 Uses variable-length encoding. uint64 long int/long uint64 ulong integer/string Bignum or Fixnum (as required)
sint32 Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. int32 int int int32 int integer Bignum or Fixnum (as required)
sint64 Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. int64 long int/long int64 long integer/string Bignum
fixed32 Always four bytes. More efficient than uint32 if values are often greater than 2^28. uint32 int int uint32 uint integer Bignum or Fixnum (as required)
fixed64 Always eight bytes. More efficient than uint64 if values are often greater than 2^56. uint64 long int/long uint64 ulong integer/string Bignum
sfixed32 Always four bytes. int32 int int int32 int integer Bignum or Fixnum (as required)
sfixed64 Always eight bytes. int64 long int/long int64 long integer/string Bignum
bool bool boolean boolean bool bool boolean TrueClass/FalseClass
string A string must always contain UTF-8 encoded or 7-bit ASCII text. string String str/unicode string string string String (UTF-8)
bytes May contain any arbitrary sequence of bytes. string ByteString str []byte ByteString string String (ASCII-8BIT)