JSON RPC API

JSON RPC API

API Reference for the core JSON RPC API.

Each Tableland validator provides a simple JSON-RPC 2.0 API to interact with the Tableland network. These API methods are used under the hood by the JavaScript SDK and CLI tool, and they enable tons of flexibility once you start utilizing the power of SQL statements.

Recall that creating and writing to tables requires a transaction to be sent on a blockchain. This requires gas and must be paid for. To make it easy for developers, any smart contracts that are deployed on testnet chains will be able to use the Tableland validator to relay the transaction for them. The transaction will sent by and paid for by the validator free of charge with testnet currency.

On mainnet chains, Tableland will not relay transactions. Thus, the APIs and RPCs that leverage the relay feature cannot be used for a mainnet chain deployment. Only testnet transactions are relayed by the validator to the corresponding chain.

🔮
If you are interested in running a Tableland validator let use know! We are onboarding experienced infrastructure operators to help us run and improve the early versions of the protocol. Reach out

Setup

Before getting started, review the CLI documentation for how to generate a Sign In With Ethereum (SIWE) token using tableland token. Add this as an environment variable (export SIWE_TOKEN=siwe_token_string) to then use the token within the various method calls.

All of the RPC calls expect an Authorization header with a signed SIWE, except for read queries. Reads do not require any on-chain interaction to take place and can directly access the Tableland network of validators.

Lastly, a number of examples have been provided using HTTPie and cURL — ensure these are installed if you would like to follow along. An optional tool called jq can be used to format the responses in a “pretty” format (e.g., curl <url> | jq).

⚠️
Tableland is still a testnet and will be launching a Tableland mainnet in 2023. But, smart contracts and apps deployed on testnet and mainnet chains can and should use the Tableland testnet. Developers should still proceed with caution due to the nature of testnets and ensure contracts that use Tableland are upgradable.

Settings & Request Format

The following HTTP settings are what’s needed to interact with JSON-RPC APIs. All requests should send an HTTP POST with a Content-Type: application/json header and contain the following fields in the JSON request data:

  • jsonrpc: <string> ⇒ Always set to "2.0" (see JSON-PRC 2.0 spec for details)
  • id: <number> ⇒ Some unique client generated integer; value doesn’t really matter (e.g., 1)
  • method: <string> ⇒ The desired method to be called
  • params: <array> ⇒ A JSON array containing a single object with a key and value (defined by each method)
    • <object> ⇒ Object with the method params
      • <string>: <string> ⇒ A single (or set of) key-value pairs, defined in each method

All requests, except for tableland_runReadQuery, also need to set a header for Authorization': 'Bearer {siwe_token}' with the SIWE token.

Endpoint

All chains use the same endpoint:

  • https://testnet.tableland.network/rpc

Response Format

The response will include a JSON object with the following information:

  • jsonrpc: <string> ⇒ Should match the jsonrpc string from the request
  • id: <number> ⇒ Should match the client-generated number from the request
  • result: <object> ⇒ Requested data as a JSON object, along with success confirmation

Errors

If an error occurs, the response will return an error instead of result. Namely, the full response will include the jsonrpc and id defined above as well as:

  • error: <object> ⇒ Error object only included if there are request issues
    • code: <number> ⇒ Numeric code that identifies the error type
    • message: <string> ⇒ Addition context about the error

Methods Overview

Testnet Only Methods

Definitions

  • Structure hash ⇒ Hash generated upon table creation that describes uniquely describes a table schema (i.e., identical schemas have equivalent structure hashes)
  • Transaction ⇒ Instructions corresponding an on-chain activity, represented as a hash
  • Chain ⇒ Blockchain or layer two solution in which transactions are being sent; available chainId options can be found here

JSON-RPC API Reference

tableland_runReadQuery

Execute a read query (SELECT) request and have the corresponding results returned.

Parameters

  • <object> ⇒ Object containing a single field that specifies the read query statement
    • statement: <string> ⇒ The SQL read query statement

Response

  • <object> ⇒ Object containing all results matching the read query statement
    • data: <object> ⇒ Object that contains the columns and rows
      • columns: <array> ⇒ Array of objects, each describing a corresponding table column
        • <object> ⇒ Object containing information about a single column
          • name: <string> ⇒ The name of the column
      • rows: <array> ⇒ Array of arrays, each describing the table rows
        • <array> ⇒ Array of row values, each separated by a comma and corresponding to the order of the objects in columns

Example

Request (using curl):

curl --location --request POST 'https://testnet.tableland.network/rpc' \
--header 'Content-Type: application/json' \
--data-raw '{
    "jsonrpc": "2.0",
    "method": "tableland_runReadQuery",
    "id" : 1,
    "params": [{
        "statement": "SELECT * FROM rpc_counter_5_65"
    }]
}'
httpie
https https://testnet.tableland.network/rpc \
  jsonrpc=2.0 id=1 method=tableland_runReadQuery \
  params:='[{"statement":"SELECT * FROM rpc_counter_5_65"}]'

Response:

{
  "jsonrpc": "2.0",
  "id": "1",
  "result": {
    "data": {
      "columns": [
        {
          "name": "counter"
        }
      ],
      "rows": [
        [
          0
        ],
      ]
    }
  }
}

tableland_validateCreateTable

Validate a CREATE TABLE query as a pre-creation check, and also calculate its structure hash.

Parameters

  • <object> ⇒ Object containing a single field that specifies the create table statement
    • create_statement: <string> ⇒ SQL CREATE TABLE statement with corresponding schema, using the table’s prefix_chainId as the table name (i.e., no appended table id)

Response

  • <object> ⇒ Object containing the structure hash
    • structure_hash: <string> ⇒ String representing the table’s schema, as a hash

Example

Request (using curl):

curl --location --request POST 'https://testnet.tableland.network/rpc' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer '"$SIWE_TOKEN"'' \
--data-raw '{
   "jsonrpc": "2.0",
    "method": "tableland_validateCreateTable",
    "id" : 1,
    "params": [{
        "create_statement": "CREATE TABLE rpc_counter_5 (id int, name text)"
    }]
}'
httpie
https -A bearer -a $TBL_TOKEN post https://testnet.tableland.network/rpc \
  jsonrpc=2.0 id=1 method=tableland_validateCreateTable \
  params:='[{ "create_statement": "CREATE TABLE rpc_table_5 (id int, name text)" }]'

Response:

{
   "jsonrpc": "2.0",
   "id": 1,
   "result": {
      "structure_hash": "466dc130f3b02cf995fb66f6a0bdbadc49d2a527c26ac328daddc3f7b8ef779c"
   }
}

tableland_validateWriteQuery

Validate a write query as a pre-write check.

Parameters

  • <object> ⇒ Object containing a single field that specifies the write query statement
    • statement: <string> ⇒ SQL write query statement

Response

  • <object> ⇒ Object containing the tableId
    • structure_hash: <string> ⇒ String representing the table’s schema, as a hash

Example

Request (using curl):

curl --location --request POST 'https://testnet.tableland.network/rpc' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer '"$SIWE_TOKEN"'' \
--data-raw '{
   "jsonrpc": "2.0",
    "method": "tableland_validateWriteQuery",
    "id" : 1,
    "params": [{
        "statement": "INSERT INTO rpc_counter_5_65 VALUES (0)"
    }]
}'
httpie
https -A bearer -a $TBL_TOKEN post https://testnet.tableland.network/rpc \
  jsonrpc=2.0 id=1 method=tableland_validateWriteQuery \
  params:='[{ "statement": "INSERT INTO rpc_counter_5_65 VALUES (0)" }]'

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "table_id": "65"
  }
}

tableland_getReceipt

Get the receipt of a chain transaction to verify if it was executed, along with the execution details.

Parameters

  • <object> ⇒ Object containing a single field that specifies the transaction hash
    • txn_hash: <string> ⇒ On-chain transaction hash corresponding to an interaction with a table

Response

  • <object> ⇒ Object containing information about the corresponding transaction
    • ok: <bool> ⇒ Boolean that represents if the transaction was executed or not
    • receipt: <object> ⇒ If "ok": true, the response includes the related transaction data
      • chain_id: <number> ⇒ Identifier for the corresponding chainId
      • txn_hash: <string> ⇒ Matching transaction hash from the request
      • block_number: <int> ⇒ Block in which the transaction was included
      • table_id: <string> ⇒ Unique id relative to the chain, representing a table’s ERC-721 tokenId
      • error: <string> ⇒ If there’s no error, an empty string; if there is an error occurred, the message is included (e.g,, db query execution failed (code: SQLITE_cannot…)
      • error_event_idx: <int> ⇒ Returns -1 if no error message was included, or returns a number that’s not -1 if an error does exist

Example

Request (using curl):

curl --location --request POST 'https://testnet.tableland.network/rpc' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer '"$SIWE_TOKEN"'' \
--data-raw '{
   "jsonrpc": "2.0",
    "method": "tableland_getReceipt",
    "id" : 1,
    "params": [{
        "txn_hash": "0xb6da1119ab376055767cde770647a66024119b429cea332443682e2b53e378dc"
    }]
}'
httpie
https -A bearer -a $TBL_TOKEN post https://testnet.tableland.network/rpc \
  jsonrpc=2.0 id=1 method=tableland_getReceipt \
  params:='[{ "txn_hash": "0xb6da1119ab376055767cde770647a66024119b429cea332443682e2b53e378dc" }]'

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "ok": true,
    "receipt": {
      "chain_id": 5,
      "txn_hash": "0xb6da1119ab376055767cde770647a66024119b429cea332443682e2b53e378dc",
      "block_number": 7223294,
      "table_id": "65"
		  "error": "",
		  "error_event_idx": -1
			}
    }
  }
}

Testnet Only Methods

tableland_relayWriteQuery

For write queries, use a validator to relay a runSQL smart contract call on your behalf

Parameters

  • <object> ⇒ Object containing a single field that specifies the write query statement
    • caller: <string> ⇒ On-chain address that is setting the controller (must be the table’s owner)
    • token_id: <string> ⇒ Identifier for the table’s tokenId from the smart contract
    • controller: <string> ⇒ On-chain address of the controller (EOA or contract)

Response

  • <object> ⇒ Object containing information about the corresponding transaction
    • tx: <object> ⇒ Object containing the transaction hash
      • hash: <string> ⇒ On-chain transaction hash corresponding to a runQL smart contract call

Example

Request (using curl):

curl --location --request POST 'https://testnet.tableland.network/rpc' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer '"$SIWE_TOKEN"'' \
--data-raw '{
   "jsonrpc": "2.0",
    "method": "tableland_relayWriteQuery",
    "id" : 1,
    "params": [{
        "statement": "INSERT INTO rpc_counter_5_65 VALUES (0)"
    }]
}'
httpie
https -A bearer -a $TBL_TOKEN  post https://testnet.tableland.network/rpc \
  jsonrpc=2.0 id=1 method=tableland_relayWriteQuery \
  params:='[{
        "statement": "INSERT INTO rpc_counter_5_65 VALUES (0)"
    }]'

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tx": {
      "hash": "0xe558e5d284f165573e4f716f9b3943f6fbe9c2c66be2a4d7da12dadc0ea9458f"
    }
  }
}

tableland_setController

Set the table’s controller by using a validator to relay a setController smart contract call on your behalf, using the SIWE token to infer a caller.

Parameters

  • <object> ⇒ Object containing a single field that specifies the write query statement
    • token_id: <string> ⇒ Identifier for the table’s tokenId from the smart contract
    • controller: <string> ⇒ On-chain address of the controller (EOA or contract)

Response

  • <object> ⇒ Object containing information about the corresponding transaction
    • tx: <object> ⇒ Object containing the transaction hash
      • hash: <string> ⇒ On-chain transaction hash corresponding to a setController smart contract call

Example

Request (using curl):

curl --location --request POST 'https://testnet.tableland.network/rpc' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer '"$SIWE_TOKEN"'' \
--data-raw '{
   "jsonrpc": "2.0",
    "method": "tableland_setController",
    "id" : 1,
    "params": [{
        "token_id": "65",
        "controller": "0x9bA89c8aD3856C0137E268bD76ed12d14696E140"
    }]
}'
httpie
https -A bearer -a $TBL_TOKEN  post https://testnet.tableland.network/rpc \
  jsonrpc=2.0 id=1 method=tableland_setController \
  params:='[{
        "caller": "0x4D5286d81317E284Cd377cB98b478552Bbe641ae",
        "token_id": "65",
        "controller": "0x9bA89c8aD3856C0137E268bD76ed12d14696E140"
    }]'

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tx": true,
    "receipt": {
      "tx": {
        "hash": "0xa69590589a9ae04bfde4ca07351c611f9ddb2ddc3bab6cd0165684dc959be5c7"
      }
    }
  }
}

← Previous

Next →