Reference
JSON-RPC API Reference
Firechain's JSON-RPC API is a standard interface for interacting with Firechain nodes. It is a stateless, light-weight RPC protocol that uses JSON as a data format. It is designed to be simple and easy to implement.
Firechain's JSON-RPC API conforms to the JSON-RPC 2.0 Specification.
Errors
The specification defines several error codes that may be returned by the API. The following table lists the error codes that may be returned by the API, along with their meaning.
| Code | Message | Description |
|---|---|---|
| -32001 | Server Panic | The JSON-RPC server is unable to handle the request. |
| -32002 | Callback Failed | The callback was not able to be completed as expected. |
| -32003 to -32099 | Server Error | Reserved for implementation-specific internal errors. |
| -32000 | Server Stopped | The JSON-RPC server has been stopped. |
| -32600 | Invalid Request | The JSON-RPC request object is invalid. |
| -32601 | Method not found | The JSON-RPC method does not exist or is unavailable. |
| -32602 | Invalid params | Invalid JSON-RPC method parameter(s). |
| -32603 | Internal error | Internal JSON-RPC error. |
| -32700 | Parse error | An error occurred while parsing the request. |
| -34001 | Decryption Error | Unable to decrypt content. |
| -35001 | Balance Error | Insufficient balance to complete transfer. |
| -35002 | Heat Limit Error | Request would exceed account's heat capacity. |
| -35004 | Method Error | Invalid contract method parameter(s). |
| -35005 | PoW Limit Error | Too many outstanding PoW requests to create more. |
| -35006 | Code Not Found | Unable to find requested ABI method. |
| -35007 | Invalid Latency | The specified response latency is not valid. |
| -35008 | Entity Not Found | No entity was found at the specified address. |
| -35009 | Reserved | Reserved |
| -35010 | Invalid Heat Multiplier | The specified heat multiplier is not valid. |
| -35011 | PoW Unavailable | The network is unable to accept PoW requests. |
| -35012 | Max Request Heat | The request would exceed the maximum heat capacity. |
| -36001 | Invalid Producer | The specified block producer address is not valid. |
| -36002 | Invalid hash | The specified hash is not valid. |
| -36003 | Invalid signature | The specified signature is not valid. |
| -36004 | Invalid PoW Nonce | The specified PoW nonce is not valid. |
| -36005 | Invalid Upstream | The specified hash does not match the previous block. |
| -36006 | Invalid Block | The specified block is not yet available. |
Models
The following models are widely used throughout the Firechain JSON-RPC API.
Response
The specification defines a standard response object that is always returned by the API. The response object contains the following fields:
| Field | Type | Description |
|---|---|---|
| jsonrpc | String | A String specifying the version of the JSON-RPC protocol. Must be exactly "2.0". |
| id | String or Number | The request id. This can be of any type. It is used to match the request with the response. |
| result | Any | The result of the request. This can be of any type. |
| error | Object | The error object in case there was an error. |
Error
| Field | Type | Description |
|---|---|---|
| code | Number | A Number that indicates the error type that occurred. This MUST be an integer. |
| message | String | A String providing a short description of the error. The message SHOULD be limited to a concise single sentence. |
| data | Any | A Primitive or Structured value that contains additional information about the error. This may be omitted. The value of this member is defined by the Server (e.g. detailed error information, nested errors etc.). |
Account
| Field | Type | Description |
|---|---|---|
| address | String | The account's address. |
| height | Number | The number of entries in the account's transaction history. |
| balances | Map(tokenId: address, balance: Balance) | The account's balances. |
Balance
| Field | Type | Description |
|---|---|---|
| token | Token | The token associated with the balance. |
| amount | Number | The amount of the balance. |
| activity | Number | The number of transactions that have been made with the token. |
Token
| Field | Type | Description |
|---|---|---|
| id | String | The token's ID. |
| name | String | The token's name. |
| symbol | String | The token's symbol. |
| decimals | Number | The number of decimal places the token supports. |
| totalSupply | Number | The total supply of the token. |
| maxSupply | Number | The maximum supply of the token. |
| mintable | Boolean | Whether the token is mintable. |
| burnable | Boolean | Whether the token is burnable. |
| transferable | Boolean | Whether the token is transferable. |
| creator | String | The token's creator. |
Transaction
| Field | Type | Description |
|---|---|---|
| hash | String | The transaction's hash. |
| type | TxType | The transaction's type. |
| height | Number | The sending account's height (nonce). |
| hash | String | A hash of the transaction object. |
| previousHash | String | The hash of previous transaction. A hash of all zeros is used for the account's first transaction. |
| producer | String | Validator's address. This is typically the account address for users, and always a consensus group delegate for on-chain entities. |
| sender | String | The address of the account from which the transaction was sent. |
| receiver | String | The address of the account to which the transaction is directed. |
| tokenId | String | The ID of the token to transfer, if any. |
| amount | String | The amount of tokens to transfer, if any. |
| fee | String | Fee paid to the validator, if any. Not used at this time. |
| data | String | Unstructured data, typically used for deploying and interacting with entities. |
| signature | String | Signature for the transaction object. |
| logs | String[] | A list of the hashes of any VM logs generated during execution. |
| downstreams | Transaction[] | A list of downstream requests generated as part of the current execution. |
| upstream | Transaction | The upstream request that led to the current execution, if applicable. |
| heat | String | The net heat generated by the transaction, which excludes any amount offset through PoW. |
| rawHeat | String | The gross heat generated by the transaction, including any offsets from PoW solutions. |
| confirmations | String | Number of global confirmations for the transaction. |
| sealedAt | int64 | The timestamp of the first global confirmation. |
| sealedIn | String | The hash of global block that sealed the transaction. |
| sealedBy | String | The address of the signer of the global block that sealed the transaction. |
PoW Fields
If the sender of a transaction used a PoW solution to offset any portion of the transaction's heat, the following fields will be appended:
| Field | Type | Description |
|---|---|---|
| difficulty | String | Difficulty of the submitted PoW solution, if applicable. |
| solution | String | The nonce of an accepted PoW solution, if applicable. |
Enums and Constants
TxType
| ID | Type | Description |
|---|---|---|
| 1 | Request | Deploy new code. |
| 2 | Request | Transfer token. |
| 3 | Request | Mint token. |
| 4 | Response | Reply to call. |
| 5 | Response | Reply with failure/rejection |
| 6 | Request | Code-initiated refund. |
| 7 | Response | Initializer (genesis). |
JSON-RPC Methods
The following methods are available in Firechain's JSON-RPC API:
| Method | Description |
|---|---|
| get_height | Returns the current height of the global state chain. |
| get_block | Returns the global state entry matching the given hash. |
| get_block_by_height | Returns the global state entry for the given block height. |
| get_message | Returns the message for the given message ID. |
| get_message_receipt | Returns the message receipt for the given message ID. |
| get_message_count | Returns the number of messages sent from the given address. |
| get_balance | Returns the given address's balance of the given token. |
| get_codehash | Returns the codehash of the given address. |
| get_heat_capacity | Returns the heat capacity of the given address. |
| get_storage_at | Returns the storage value at the given position for the given address. |
| get_peer_count | Returns the number of peers connected to the RPC node. |
| get_version | Returns the version details of the software being run by the RPC node. |
| get_status | Returns the status of the Firechain node. |
| get_events | Returns the events matching the given filter. Can be used to fetch events by block, message, or address. |
| get_message_events | Returns the events broadcast during a given message. |
| get_block_events | Returns events broadcast during a given global state entry. |
| send_message | Sends a message to the network. |
| send_raw_message | Sends a raw message to the network. |
| simulate | Simulates a message call from the current RPC node. Does not create a message on the network. |
| estimate_heat | Analyze a message call, which won't be added to the blockchain and returns the amount of heat it should generate, which can be used for estimating the used gas. |
| get_work | Returns a proof-of-work challenge that can be solved by a given account to temporarily unlock more heat tolerance. |
| submit_work | Submits a proof-of-work solution. |
get_height
Returns the current height of the global state chain.
Parameters
None
Returns
Number - The current height of the global state chain.
get_block
Returns the global state entry matching the given block hash.
Parameters
| Field | Type | Description |
|---|---|---|
| block_hash | String | The block hash. |
Returns
| Field | Type | Description |
|---|---|---|
| block | Object | The global state entry. |
| block.hash | String | The block hash. |
| block.number | Number | The block number. |
| block.parent_hash | String | The parent block hash. |
| block.timestamp | Number | The block timestamp. |
| block.heat | Number | The block's total generated heat. |
| block.messages | Array<Message> | The block messages. |
get_block_by_height
Returns the global state entry for the given block height.
Parameters
| Field | Type | Description |
|---|---|---|
| height | Number | The block height. |
Returns
| Field | Type | Description |
|---|---|---|
| block | Object | The global state entry. |
| block.hash | String | The block hash. |
| block.number | Number | The block number. |
| block.parent_hash | String | The parent block hash. |
| block.timestamp | Number | The block timestamp. |
| block.heat | Number | The block's total generated heat. |
| block.messages | Array<Message> | The block messages. |
get_message
Returns the message for the given message ID.
Parameters
| Field | Type | Description |
|---|---|---|
| message_id | String | The message ID. |
Returns
| Field | Type | Description |
|---|---|---|
message | Message | The message. |
message.id | String | The message ID, which is a hash of its contents. |
message.timestamp | Number | The timestamp in the message's header. |
message.version | Number | The protocol version the message targets. |
message.sender | String | The message sender. |
message.receiver | String | The message recipient. |
message.links | Array<String> | The IDs of any referenced messages. |
message.bodyHash | String | The hash of the message body. |
message.signature | String | The signature provided by the sender. |
message.body | Object | The message body. |
get_message_receipt
Returns the message receipt for the given message ID.
Parameters
| Field | Type | Description |
|---|---|---|
| message_id | String | The message ID. |
Returns
| Field | Type | Description |
|---|---|---|
receipt | Object | The message receipt. |
receipt.id | String | The message ID, which is a hash of its contents. |
receipt.timestamp | Number | The timestamp in the message's header. |
receipt.heat | Number | The heat generated by the message. |
receipt.heat_limit | Number | The heat limit of the message. |
receipt.state_root | String | The account's state root after the message was executed. |
receipt.message | Message | The message. |
receipt.events | Array<Event> | The events generated by the message. |
receipt.events[].id | String | The event ID. |
receipt.events[].name | String | The event name. |
receipt.events[].data | String | The event data. |
receipt.events[].topics | Array<String> | The event's indexed topics. |
get_message_count
Returns the number of messages sent from the given address.
Parameters
| Field | Type | Description |
|---|---|---|
| address | String | The address. |
Returns
Number - The number of messages sent from the given address.
get_balance
Returns the given address's balance of the given token.
Parameters
| Field | Type | Description |
|---|---|---|
| address | String | The address. |
| token | String? | The token to query. Defaults to the native token. |
Returns
Number - The given address's balance of the given token.
get_codehash
Returns the hash of the code stored at the given address, not the code itself. Can be used to verify the currently deployed code matches a known or trusted version, for example.
Parameters
| Field | Type | Description |
|---|---|---|
| address | String | The address. |
Returns
String - The hash of the code stored at the given address.
get_heat_capacity
Returns the heat capacity of the given address.
Parameters
| Field | Type | Description |
|---|---|---|
| address | String | The address. |
Returns
Number - The heat capacity of the given address.
get_storage_at
Returns the storage value at the given position for the given address. Can be used to retrieve the actual deployed code, or just individual storage values. The value, if reachable, is returned as a hex string.
Parameters
| Field | Type | Description |
|---|---|---|
| address | String | The address. |
| position | String | The storage position. |
Returns
String - The storage value at the given position for the given address.
get_peer_count
Returns the number of peers connected to the RPC node.
Parameters
None
Returns
Number - The number of peers connected to the RPC node.
get_version
Returns the version details of the software being run by the RPC node.
Parameters
None
Returns
| Field | Type | Description |
|---|---|---|
| id | String | The RPC node's implementation identifier. |
| build | String | The build of the RPC node software. Usually a git commit hash. |
| network | String | The ID of the network supported by the node. |
| protocol | String | The protocol version supported by the node. |
get_status
Returns the status of the Firechain node.
Parameters
None
Returns
| Field | Type | Description |
|---|---|---|
| id | String | The RPC node's implementation identifier. |
| build | String | The build of the RPC node software. Usually a git commit hash. |
| network | String | The ID of the network supported by the node. |
| protocol | String | The protocol version supported by the node. |
| height | Number | The current height of the global state chain. |
| uptime | Number | The number of milliseconds the node has been connected to at least 1 peer. |
| peers | Number | The number of peers connected to the RPC node. |
| syncing | Boolean | Whether the node is currently syncing. |
| operator | String | The address of the operator of the node. |
get_events
Returns the broadcasted events matching the given filter.
Parameters
| Field | Type | Description |
|---|---|---|
| filter | Object | The filter. |
| filter.from_block | Number? | The block height to start searching from. Defaults to the current height. |
| filter.to_block | Number? | The block height to stop searching at. Defaults to the current height. |
| filter.address | String? | The address to filter for. |
| filter.topics | Array<String>? | The topics to filter for. |
Returns
Array<Event> - The broadcasted events matching the filter.
get_message_events
Returns the events broadcasted by the given message.
Parameters
| Field | Type | Description |
|---|---|---|
| message_id | String | The message ID. |
Returns
Array<Event> - The events broadcasted by the given message.
get_block_events
Returns the events broadcasted in the given global state entry.
Parameters
| Field | Type | Description |
|---|---|---|
| block_hash | String | The block hash. |
Returns
Array<Event> - The events broadcasted in the given global state entry.
send_message
Sends a message to the Firechain network.
Parameters
| Field | Type | Description |
|---|---|---|
message | Message | The message. |
message.id | String | The message ID, which is a hash of its contents. |
message.timestamp | Number | The timestamp in the message's header. |
message.version | Number | The protocol version the message targets. |
message.sender | String | The message sender. |
message.receiver | String | The message recipient. |
message.links | Array<String> | The IDs of any referenced messages. |
message.bodyHash | String | The hash of the message body. |
message.signature | String | The signature provided by the sender. |
message.body | Object | The message body. |
Returns
String - The message ID of the sent message.
send_raw_message
Sends a raw message to the Firechain network.
Parameters
| Field | Type | Description |
|---|---|---|
| raw_message | String | The raw message. |
Returns
String - The message ID of the sent message.
simulate
Simulates the execution of a message.
Parameters
| Field | Type | Description |
|---|---|---|
message | Message | The message. |
message.id | String | The message ID, which is a hash of its contents. |
message.timestamp | Number | The timestamp in the message's header. |
message.version | Number | The protocol version the message targets. |
message.sender | String | The message sender. |
message.receiver | String | The message recipient. |
message.links | Array<String> | The IDs of any referenced messages. |
message.bodyHash | String | The hash of the message body. |
message.signature | String | The signature provided by the sender. |
message.body | Object | The message body. |
Returns
Object - The simulation result.
estimate_heat
Estimates the amount of heat a message will generate.
Parameters
| Field | Type | Description |
|---|---|---|
message | Message | The message. |
message.id | String | The message ID, which is a hash of its contents. |
message.timestamp | Number | The timestamp in the message's header. |
message.version | Number | The protocol version the message targets. |
message.sender | String | The message sender. |
message.receiver | String | The message recipient. |
message.links | Array<String> | The IDs of any referenced messages. |
message.bodyHash | String | The hash of the message body. |
message.signature | String | The signature provided by the sender. |
message.body | Object | The message body. |
Returns
Number - The estimated heat.
get_work
Returns a proof-of-work challenge for the given address.
Parameters
| Field | Type | Description |
|---|---|---|
| address | String | The address. |
Returns
| Field | Type | Description |
|---|---|---|
| id | String | The challenge ID. |
| challenge | String | The challenge. |
| difficulty | Number | The difficulty. |
| deadline | Number | The deadline to submit a solution for this challenge. |
submit_work
Submits a proof-of-work solution for the given address. Must be submitted by the requester and before the deadline specified in the challenge.
Parameters
| Field | Type | Description |
|---|---|---|
| address | String | The address. |
| challenge_id | String | The challenge ID. |
| solution | String | The solution. |
Returns
| Field | Type | Description |
|---|---|---|
| success | Boolean | Whether the solution was accepted. |
| message | String? | The reason for the solution being rejected, if any. |
| capacity | Number? | The heat capacity unlocked by the solution, if any. |
| expiration | Number? | The expiration of the unlocked heat capacity, if applicable. |
| value | Number? | The number of tokens paid out for the solution, if applicable. |