wasmd/docs/proto/proto.md

Protocol Documentation

Table of Contents

• x/wasm/types/genesis.proto

  • Code
  • Contract
  • GenesisState
  • GenesisState.GenMsgs
  • Sequence

• x/wasm/types/ibc.proto

  • MsgIBCCloseChannel
  • MsgIBCSend

• x/wasm/types/proposal.proto

  • ClearAdminProposal
  • InstantiateContractProposal
  • MigrateContractProposal
  • PinCodesProposal
  • StoreCodeProposal
  • UnpinCodesProposal
  • UpdateAdminProposal

• x/wasm/types/query.proto

  • CodeInfoResponse

  • ContractInfoWithAddress

  • QueryAllContractStateRequest

  • QueryAllContractStateResponse

  • QueryCodeRequest

  • QueryCodeResponse

  • QueryCodesRequest

  • QueryCodesResponse

  • QueryContractHistoryRequest

  • QueryContractHistoryResponse

  • QueryContractInfoRequest

  • QueryContractInfoResponse

  • QueryContractsByCodeRequest

  • QueryContractsByCodeResponse

  • QueryRawContractStateRequest

  • QueryRawContractStateResponse

  • QuerySmartContractStateRequest

  • QuerySmartContractStateResponse

  • Query

• x/wasm/types/tx.proto

  • MsgClearAdmin

  • MsgClearAdminResponse

  • MsgExecuteContract

  • MsgExecuteContractResponse

  • MsgInstantiateContract

  • MsgInstantiateContractResponse

  • MsgMigrateContract

  • MsgMigrateContractResponse

  • MsgStoreCode

  • MsgStoreCodeResponse

  • MsgUpdateAdmin

  • MsgUpdateAdminResponse

  • Msg

• x/wasm/types/types.proto

  • AbsoluteTxPosition

  • AccessConfig

  • AccessTypeParam

  • CodeInfo

  • ContractCodeHistoryEntry

  • ContractInfo

  • Model

  • Params

  • AccessType

  • ContractCodeHistoryOperationType

• Scalar Value Types

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)