---
tags: Technical specification
order: 1
---
# Protocol Messages

## Native Cosmos SDK Messages

Stemming from its Cosmos SDK foundation, BandChain supports all types of messages that are native to the SDK. You can find the reference of each cosmos-sdk module from here https://docs.cosmos.network/v0.42/modules/

## BandChain Specific Messages

Apart from the messages that stems from the Cosmos SDK, BandChain also supports a number of messages native to its data oracle system. These messages' specification is presented below.

### MsgCreateDataSource

Deploys and registers a new data source to BandChain. Once registered, the data source is assigned a unique `int64` identifier which can be used to refer to it forever.

#### Parameters

| Parameter | Type | Description |
|-------------|------------------|------------------------|
| Name | string | The human-readable string name for this data source |
| Description | string | The description of this data source |
| Executable | []byte | The content of executable to be run by validators upon receiving a data request for this data source. The executable can be in any format, as long as it is accepted by the general public. |
| Sender | sdk.AccAddress | The address of the message's sender. Note that the sender does not need to be the same as the owner |
| Owner | sdk.AccAddress | The address of the entity who will be responsible for maintaining the data source |
| Treasury | sdk.AccAddress | The address of the entity who receive data source fee from requester |
| Fee | sdk.Coins | The data source fee per ask_count that data provider will receive from requester |

### MsgEditDataSource

Edits an existing data source given the unique `int64` identifier (i.e. `DataSourceID`). The sender must be the owner of the data source for the transaction to succeed.

#### Parameters

| Parameter | Type | Description |
|-----------------|------------------|------------------------|
| DataSourceID |int64 | The unique identifier number assigned to the data source when it was first registered |
| Name | string | The human-readable string name for this data source |
| Description | string | The description of this data source |
| Executable | []byte | The content of executable to be run by validators upon receiving a data request for this data source. The executable can be in any format, as long as it is accepted by the general public. |
| Sender | sdk.AccAddress | The address of the message's sender. Note that the sender does not need to be the same as the owner |
| Owner | sdk.AccAddress | The address of the entity who will be responsible for maintaining the data source |
| Treasury | sdk.AccAddress | The address of the entity who receive data source fee from requester |
| Fee | sdk.Coins | The data source fee per ask_count that data provider will receive from requester |

### MsgCreateOracleScript

Deploys a new oracle script to BandChain's network. Once registered, the script is assigned a unique `int64` identifier which can be used to refer to it forever.

#### Parameters

| Parameter | Type | Description |
|-----------------|------------------|-------------------------------------------------------------------------------------------------------|
| Sender | sdk.AccAddress | The address of the message's sender. Note that the sender does not need to be the same as the owner |
| Owner | sdk.AccAddress | The address of the entity who will be responsible for maintaining the data source |
| Name | string | The human-readable string name for this data source |
| Description | string | The description of this data source |
| Code | []byte | The Owasm-compiled binary attached to this oracle script |
| Schema | string | The schema detailing the inputs and outputs of this oracle script, as well as the corresponding types |
| Source Code URL | string | The URL for the source code of this oracle script |

### MsgEditOracleScript

Edits an existing oracle script given the unique `int64` identifier (i.e. `oracleScriptID`). The sender must be the owner of the oracle script for the transaction to succeed.

#### Parameters

| Parameter | Type | Description |
|-----------------|------------------|-------------------------------------------------------------------------------------------------------|
| OracleScriptID | int64 | The unique identifier number assigned to the oracle script when it was first registered on Bandchain |
| Sender | sdk.AccAddress | The address of the message's sender. Note that the sender does not need to be the same as the owner |
| Owner | sdk.AccAddress | The address of the entity who will be responsible for maintaining the data source |
| Name | string | The human-readable string name for this data source |
| Description | string | The description of this data source |
| Code | []byte | The Owasm-compiled binary attached to this oracle script |
| Schema | string | The schema detailing the inputs and outputs of this oracle script, as well as the corresponding types |
| Source Code URL | string | The URL for the source code of this oracle script |

### MsgRequestData

Requests a new data based on an existing oracle script. A data request will be assigned a unique identifier once the transaction is confirmed. After sufficient validators report the raw data points. The results of the data requests will be written and stored permanently on BandChain for future uses.

#### Parameters

| Parameter | Type | Description |
|----------------|------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------|
| OracleScriptID | int64 | The unique identifier number assigned to the oracle script when it was first registered on Bandchain |
| Calldata | []byte | The input data passed over to the oracle script for the script to use during its execution |
| AskCount | uint64 | The number of validators that are requested to respond to this request |
| MinCount | uint64 | The minimum number of validators necessary for the request to proceed to the execution phase |
| ClientID | string | The unique identifier of this oracle request, as specified by the client. This same unique ID will be save in request and result object to match request and result. |
| FeeLimit | sdk.Coins | The maximum tokens that will be paid to all data source providers |
| PrepareGas | uint64 | The amount of gas to be allocated for execute `prepare` function on oracle script |
| ExecuteGas | uint64 | The amount of gas to reserve for execute `execute` function of oracle script on execution phase |
| Sender | sdk.AccAddress | The address of the message's sender that need to pay fee for query non-free data source |

### MsgReportData

Reports raw data points for the given data request. Each data point corresponds to a data source query issued during the data request script's execution of `prepare` function.

#### Parameters

| Parameter | Type | Description |
|-----------|---------------------------------------------------------|-----------------------------------------------------------------------------|
| RequestID | int64 | The unique identifier number of the particular request |
| RawReports | []RawReport | The array of raw data. Each item corresponds to a data source query. |
| Validator | sdk.ValAddress | The address of the validator that owns this report |
| Reporter | sdk.AccAddress | The message signer who submits this report transaction for the validator |

#### Raw report struct
| Field | Type | Description |
|-----------|---------------------------------------------------------|-----------------------------------------------------------------------------|
| ExternalID | int64 | The unique identifier number of raw request |
| ExitCode | uint32 | The status code provided by validators to specify error, if any. Exit code is usually filled by the exit code returned from execution of specified data source script. With code 0 means there is no error. |
| Data | []byte | The raw result from execution of specified data source script. |

### MsgAddReporter

Registers an address to the list of addresses available to a validator when signing and submitting a report.

#### Parameters

| Parameter | Type | Description |
|------------------|------------------|--------------------------------------------------------------------------------|
| ValidatorAddress | sdk.ValAddress | The address of the validator wishing to add the reporter address to their list |
| ReporterAddress | sdk.AccAddress | The address to add to the validator's available addresses |

### MsgRemoveReporter

Remove a previously registered address from the list of addresses available to a validator when signing and submitting a report.

#### Parameters

| Parameter | Type | Description |
|------------------|------------------|--------------------------------------------------------------------------------|
| ValidatorAddress | sdk.ValAddress | The address of the validator wishing to add the reporter address to their list |
| ReporterAddress | sdk.AccAddress | The address to remove from the validator's available addresses |

## BandChain Specific Packets/Acknowledgement for IBC communication

There are 2 packets and 1 acknowledgement data type that we declared for request and get response from BandChain. Our packet follow [ics-004](https://github.com/cosmos/ibc/tree/master/spec/core/ics-004-channel-and-packet-semantics) standard how to handle packet and acknowledgement.

### OracleRequestPacketData

Packet to specific detail of how to make a new request oracle data to BandChain. This packet specification looks like MsgRequestData. There is one more field that need for get payer of data source fee.

#### Parameters

| Parameter | Type | Description |
|----------------|------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------|
| OracleScriptID | int64 | The unique identifier number assigned to the oracle script when it was first registered on Bandchain |
| Calldata | []byte | The input data passed over to the oracle script for the script to use during its execution |
| AskCount | uint64 | The number of validators that are requested to respond to this request |
| MinCount | uint64 | The minimum number of validators necessary for the request to proceed to the execution phase |
| ClientID | string | The unique identifier of this oracle request, as specified by the client. This same unique ID will be save in request and result object to match request and result. |
| FeeLimit | sdk.Coins | The maximum tokens that will be paid to all data source providers |
| PrepareGas | uint64 | The amount of gas to be allocated for execute `prepare` function on oracle script |
| ExecuteGas | uint64 | The amount of gas to reserve for execute `execute` function of oracle script on execution phase |
| RequestKey | string | The key from request chain to match data source fee payer on Bandchain |

### OracleRequestPacketAcknowledgement
Encode detail of request acknowledgment when OracleRequestPacketData execute success

#### Parameters

| Parameter | Type | Description |
|----------------|------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------|
| RequestID | int64 | Return the request id that create from this packet |

### OracleResponsePacketData

Packet that will be send to request chain when request(that created by OracleRequest packet) has been resolved to send the result of your request.

#### Parameters

| Parameter | Type | Description |
|----------------|------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------|
| ClientID | string | The unique identifier that match with the ClinetID of request packet |
| RequestID | int64 | The request id that specified the origin request of the result |
| AnsCount | uint64 | The number of validators among to the asked validators that actually responded to this oracle request prior to this oracle request being resolved |
| RequestTime | int64 | The UNIX epoch time at which the request was sent to BandChain |
| ResolveTime | int64 | The UNIX epoch time at which the request was resolved to the final result |
| ResolveStatus | Enum | `SUCCESS` means request has been resolved successfully and can use the final result, `FAILURE` means request fail to resolve with some errors, and `EXPIRED` means there are reports on this request less than ask_count of this request before request expiration time|
| Result | []byte | The final request of this request on available if ResolveStatus is `SUCCESS` |