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

CLI

REST API