tbcapi

📡 Hemi Tiny Bitcoin Daemon RPC

Last updated: May 16th, 2024

This document provides details on the RPC protocol and available commands for the Hemi Tiny Bitcoin Daemon (tbcd).

Table of Contents

• 📡 Hemi Tiny Bitcoin Daemon RPC
  • ⚙️ Implementations
    • ⚙️ tbcd Daemon
    • 🔧 RPC Client
  • 📚 Resources
  • 📡 Protocol
    • 🚫 Errors
    • 🗄️ Serialized Types
      • Block Header
      • Address
      • UTXO
      • Transaction
      • Transaction Input
      • Transaction Output
      • Outpoint
  • 👉 Block Headers by Height
    • 🗂 Raw Data
      • 📤 Request
        • Payload
        • Example Request
      • 📥 Response
        • Payload
        • Example Response
    • 🗂 Serialized Data
      • 📤 Request
        • Payload
        • Example Request
      • 📥 Response
        • Payload
        • Example Response
  • 👉 Best Block Header
    • 🗂 Raw Data
      • 📤 Request
        • Example Request
      • 📥 Response
        • Payload
        • Example Response
      • 🗂 Serialized Data
      • 📤 Request
        • Example Request
      • 📥 Response
        • Payload
        • Example Response
  • 👉 Balance by Address
    • 🗂 Raw Data
      • 📤 Request
        • Payload
        • Example Request
      • 📥 Response
        • Payload
        • Example Response
  • 👉 UTXOs by Address
    • 🗂 Raw Data
      • 📤 Request
        • Payload
        • Example Request
      • 📥 Response
        • Payload
        • Example Response
    • 🗂 Serialized Data
      • 📤 Request
        • Payload
        • Example Request
      • 📥 Response
        • Payload
        • Example Response
  • 👉 Transaction by ID
    • 🗂 Raw Data
      • 📤 Request
        • Payload
      • 📥 Response
        • Payload
        • Example Response
    • 🗂 Serialized Data
      • 📤 Request
        • Payload
        • Example Request
      • 📥 Response
        • Payload
        • Example Response

---

⚙️ Implementations

⚙️ tbcd Daemon

The tbcd daemon runs an RPC server that listens on the address provided by the TBC_ADDRESS environment variable. You can run the tbcd daemon with the RPC server enabled with the following command:

# Make sure to replace localhost:8082 with your desired address and port
TBC_ADDRESS=localhost:8082 /path/to/tbcd

🔧 RPC Client

hemictl serves as a reference implementation of an RPC client tailored for interacting with the tbcd daemon. The client provides a command-line interface for all supported RPC commands.

---

📚 Resources

For developers looking to integrate or extend functionality:

• View the raw Go types used in TBC's RPC commands: View tbcapi.go
• Check our contribution guidelines
• Review our security policy

---

📡 Protocol

The RPC protocol is WebSocket-based and follows a standard request/response model. All communications are done via JSON messages. For more detailed information, refer to the protocol documentation.

🚫 Errors

If an error occurs during a request, the response payload will include an error value containing the following details:

Field	Description	Example
timestamp	The time at which the error occurred, in Unix seconds.	1679198400
trace	A unique string for tracing errors between server and client (internal errors only).	804d952f893e686c
message	The error message. For internal server errors, this will read internal error.	invalid address format

🗄️ Serialized Types

The following types are used throughout the API. All integer values are encoded in little-endian format unless specified otherwise.

Block Header

A serialized block header contains the following data:

Field	Description	Format
version	The version of the block.	uint32
prev_hash	The hash of the previous block header in the blockchain, in reverse byte order and encoded as a hexadecimal string.	string[64]
merkle_root	The hash derived from the hashes of all transactions in the block, in reverse byte order and encoded as a hexadecimal string.	string[64]
timestamp	The time the miner began hashing the header, represented in Unix seconds.	uint32
bits	The difficulty target for the block.	string[8]
nonce	The nonce used to create the hash that is less than or equal to the target threshold.	uint32

Address

Represents an encoded Bitcoin address. The following address types are supported:

Type	Description	Example
P2PKH	Pay to Public Key Hash	mxVFsFW5N4mu1HPkxPttorvocvzeZ7KZyk
P2SH	Pay to Script Hash	2N3zXjbwdTcPsJiy8sUK9FhWJhqQCxA8Jjr
P2WPKH	Pay to Witness Public Key Hash	tb1qw508d6qejxtdg4y5r3zarvary0c5xw7kxpjzsx
P2WSH	Pay to Witness Script Hash	tb1qrp33g0q5c5txsp9arysrx4k6zdkfs4nce4xj0gdcccefvpysxf3q0sl5k7
P2TR	Pay to Taproot	tb1p6h5fuzxvqnlhkucpszs7g5h3qc4dhkj99uet6tzxz6k64ch7mgwsyf8jg4

UTXO

A serialized UTXO (Unspent Transaction Output) contains the following data:

Field	Description	Format
tx_id	The transaction ID, in reverse byte order and encoded as a hexadecimal string.	string[64]
value	The value of the UTXO in satoshis.	uint64
out_index	The output index of the UTXO in the transaction.	uint32

Example UTXO:

{
  "tx_id": "0012a33f3c301c90427d81f256d8a4848dcbfc289e8325725e7657e9a643d6fd",
  "value": 2026,
  "out_index": 1
}

Transaction

A serialized transaction contains the following data:

Field	Description	Format
version	The transaction version number.	uint32
lock_time	The block height or timestamp after which the transaction becomes final.	uint32
tx_in	An array of transaction inputs.	array
tx_out	An array of transaction outputs.	array

Example Transaction:

{
  "version": 2,
  "lock_time": 0,
  "tx_in": [
    {
      "outpoint": {
        "hash": "9554a7eb8bc903ea957c87964ab04a58d177692f15d7271cccb95258202f14b5",
        "index": 189
      },
      "signature_script": "",
      "witness": ["304402..."],
      "sequence": 4294967293
    }
  ],
  "tx_out": [
    {
      "value": 330,
      "pk_script": "51208ec88237b5978e75e93feaeeb1343ff86ae2f2c348a903c9c9c4ad0819267735"
    }
  ]
}

Transaction Input

A serialized transaction input contains the following data:

Field	Description	Format
outpoint	The outpoint for the previous transaction output.	object
signature_script	The signature script that satisfies the spending conditions.	string
witness	An array of witness data for Segregated Witness transactions.	array[string]
sequence	The transaction sequence number for Replace-By-Fee or timelock.	uint32

Transaction Output

A serialized transaction output contains the following data:

Field	Description	Format
value	The value of the transaction output in satoshis.	uint64
pk_script	The pubkey script defining the conditions to spend this output.	string

Outpoint

A serialized outpoint contains the following data:

Field	Description	Format
hash	The ID of the transaction holding the output to be spent, in reverse byte order and encoded as a hexadecimal string.	string[64]
index	The index of the specific output to spend from the transaction.	uint32

---

👉 Block Headers by Height

Retrieve the block headers by height.

🗂 Raw Data

Type	command value
Request	tbcapi-block-headers-by-height-raw-request
Response	tbcapi-block-headers-by-height-raw-response

📤 Request

• height: The height at which block headers should be retrieved.

Retrieve block headers at height 43111:

{
  "header": {
    "command": "tbcapi-block-headers-by-height-raw-request",
    "id": "68656d69"
  },
  "payload": {
    "height": 43111
  }
}

📥 Response

• block_headers: An array of raw block headers encoded as hexadecimal strings.

Response for a request with id 68656d69 and height 43111:

{
  "header": {
    "command": "tbcapi-block-headers-by-height-raw-response",
    "id": "68656d69"
  },
  "payload": {
    "block_headers": [
      "02000000cf31d5156c8ab752b91874d1072d4673b83ee3ed718d3cb4f461c410000000000ca43abadf59bee614186d30da42f56932dc2a53e6d920169b8577207f7b11fcfec3d750c0ff3f1c4f428f6a"
    ]
  }
}

🗂 Serialized Data

Type	command value
Request	tbcapi-block-headers-by-height-request
Response	tbcapi-block-headers-by-height-response

📤 Request

• height: The height at which block headers should be retrieved.

Retrieve block headers at height 43111:

{
  "header": {
    "command": "tbcapi-block-headers-by-height-request",
    "id": "68656d69"
  },
  "payload": {
    "height": 43111
  }
}

📥 Response

• block_headers: An array of block headers.

Response for a request with id 68656d69 and height 43111:

{
  "header": {
    "command": "tbcapi-block-headers-by-height-response",
    "id": "68656d69"
  },
  "payload": {
    "block_headers": [
      {
        "version": 2,
        "prev_hash": "0000000010c461f4b43c8d71ede33eb873462d07d17418b952b78a6c15d531cf",
        "merkle_root": "fc117b7f2077859b1620d9e6532adc3269f542da306d1814e6be59dfba3aa40c",
        "timestamp": 1356317694,
        "bits": "1c3fffc0",
        "nonce": 1787773519
      }
    ]
  }
}

---

👉 Best Block Header

Retrieve the best block headers.

🗂 Raw Data

Type	command value
Request	tbcapi-block-header-best-raw-request
Response	tbcapi-block-header-best-raw-response

📤 Request

Retrieve the best block headers:

{
  "header": {
    "command": "tbcapi-block-header-best-raw-request",
    "id": "68656d69"
  }
}

📥 Response

• height: The best-known height.
• block_header: The best-known block header encoded as a hexadecimal string.

Response for a request with id 68656d69 and best height 2182000:

{
  "header": {
    "command": "tbcapi-block-header-best-raw-response",
    "id": "68656d69"
  },
  "payload": {
    "height": 2182000,
    "block_header": "0420002075089ac1ab1cab70cf6e6b774a86703a8d7127c0ebed1d3dfa2c00000000000086105509ec4a79457a400451290ad2a019fec4c76b47512623f1bb17a0ced76f38d82662bef4001b07d86700"
  }
}

🗂 Serialized Data

Type	command value
Request	tbcapi-block-header-best-request
Response	tbcapi-block-header-best-response

📤 Request

Retrieve the best block headers:

{
  "header": {
    "command": "tbcapi-block-header-best-request",
    "id": "68656d69"
  }
}

📥 Response

• height: The best-known height.
• block_header: The best-known block header.

Response for a request with id 68656d69 and height 2587400:

{
  "header": {
    "command": "tbcapi-block-header-best-response",
    "id": "68656d69"
  },
  "payload": {
    "height": 2587400,
    "block_header": {
      "version": 536887296,
      "prev_hash": "000000000000002bbbbec8f126dc76a82109d898383bca5013a2386c8675ce34",
      "merkle_root": "b9d74efdafb5436330b47478b2df28251057da5a9bc11c5509410950253d4f0e",
      "timestamp": 1713461092,
      "bits": "192e17d5",
      "nonce": 3365605040
    }
  }
}

👉 Balance by Address

Retrieve the balance for an address.

🗂 Raw Data

Type	command value
Request	tbcapi-balance-by-address-request
Response	tbcapi-balance-by-address-response

📤 Request

• address: The address for which the balance should be retrieved.

Retrieve the balance for the address myqzZmRvoXmrhsrM5STiMGtNRxCFArHWRd:

{
  "header": {
    "command": "tbcapi-balance-by-address-request",
    "id": "68656d69"
  },
  "payload": {
    "address": "mhAfMWDjd8YV3RoWcpHSzqjkWi6q5Bfixa"
  }
}

📥 Response

• balance: The known balance of the address, in satoshis.

Response for a request with id 68656d69, if the address's balance is 0:

{
  "header": {
    "command": "tbcapi-balance-by-address-response",
    "id": "68656d69"
  },
  "payload": {
    "balance": 0
  }
}

---

👉 UTXOs by Address

Retrieve UTXOs by address.

🗂 Raw Data

Type	command value
Request	tbcapi-utxos-by-address-raw-request
Response	tbcapi-utxos-by-address-raw-response

📤 Request

• address: The address to retrieve the UTXOs for.
• start: The start index for the UTXOs that should be included in the response (or the number of UTXOs that should be skipped).
• count: The maximum number of UTXOs that should be included in the response.

Retrieve five UTXOs for the address mxVFsFW5N4mu1HPkxPttorvocvzeZ7KZyk:

{
  "header": {
    "command": "tbcapi-utxos-by-address-raw-request",
    "id": "68656d69"
  },
  "payload": {
    "address": "mxVFsFW5N4mu1HPkxPttorvocvzeZ7KZyk",
    "start": 0,
    "count": 5
  }
}

📥 Response

• utxos: An array of known UTXOs for the address, encoded as hexadecimal strings, or null if there are * no UTXOs* for the address.

Response for a request with id 68656d69, requesting 5 UTXOs for the address mxVFsFW5N4mu1HPkxPttorvocvzeZ7KZyk:

{
  "header": {
    "command": "tbcapi-utxos-by-address-raw-response",
    "id": "68656d69"
  },
  "payload": {
    "utxos": [
      "0073700282db1dcc4853dc64e5da5c8595d1204ea7d036b04ea6b8ba41093a770000000000000cab00000002",
      "0073700282db1dcc4853dc64e5da5c8595d1204ea7d036b04ea6b8ba41093a770000000000000cab00000002",
      "0073700282db1dcc4853dc64e5da5c8595d1204ea7d036b04ea6b8ba41093a770000000000000cab00000002",
      "0073700282db1dcc4853dc64e5da5c8595d1204ea7d036b04ea6b8ba41093a770000000000000cab00000002",
      "0073700282db1dcc4853dc64e5da5c8595d1204ea7d036b04ea6b8ba41093a770000000000000cab00000002"
    ]
  }
}

🗂 Serialized Data

Type	command value
Request	tbcapi-utxos-by-address-request
Response	tbcapi-utxos-by-address-response

📤 Request

• address: The address to retrieve the UTXOs for.
• start: The start index for the UTXOs that should be included in the response (or the number of UTXOs that should be skipped).
• count: The maximum number of UTXOs that should be included in the response.

Retrieve 5 UTXOs for the address mxVFsFW5N4mu1HPkxPttorvocvzeZ7KZyk:

{
  "header": {
    "command": "tbcapi-utxos-by-address-request",
    "id": "68656d69"
  },
  "payload": {
    "address": "mxVFsFW5N4mu1HPkxPttorvocvzeZ7KZyk",
    "start": 0,
    "count": 5
  }
}

📥 Response

• utxos: An array of known UTXOs. The maximum number of items in this array can be changed with * count* in the request.

Response for a request with id 68656d69, showing 5 UTXOs for the address:

{
  "header": {
    "command": "tbcapi-utxos-by-address-response",
    "id": "68656d69"
  },
  "payload": {
    "utxos": [
      {
        "tx_id": "0012a33f3c301c90427d81f256d8a4848dcbfc289e8325725e7657e9a643d6fd",
        "value": 2026,
        "out_index": 1
      },
      {
        "tx_id": "0066c9f87d012e75e390adb490794a746fefe05eb16d220515788f33d5b6b336",
        "value": 10000,
        "out_index": 1
      },
      {
        "tx_id": "0066c9f87d012e75e390adb490794a746fefe05eb16d220515788f33d5b6b336",
        "value": 10000,
        "out_index": 2
      },
      {
        "tx_id": "0073700282db1dcc4853dc64e5da5c8595d1204ea7d036b04ea6b8ba41093a77",
        "value": 3243,
        "out_index": 1
      },
      {
        "tx_id": "0073700282db1dcc4853dc64e5da5c8595d1204ea7d036b04ea6b8ba41093a77",
        "value": 3243,
        "out_index": 2
      }
    ]
  }
}

---

👉 Transaction by ID

🗂 Raw Data

Type	command value
Request	tbcapi-tx-by-id-raw-request
Response	tbcapi-tx-by-id-raw-response

📤 Request

• tx_id: The ID of the transaction to retrieve, encoded as a hexadecimal string.

An example request to retrieve the transaction 0584ad53bf1938702b952026f7c986ab5d07ee7295c0ad3241c932a5483158ac:

{
  "header": {
    "command": "tbcapi-tx-by-id-raw-request",
    "id": "68656d69"
  },
  "payload": {
    "tx_id": "0584ad53bf1938702b952026f7c986ab5d07ee7295c0ad3241c932a5483158ac"
  }
}

📥 Response

• tx: The transaction (encoded as a hexadecimal string).

An example response for a request with id 68656d69, requesting the transaction 0584ad53bf1938702b952026f7c986ab5d07ee7295c0ad3241c932a5483158ac:

{
  "header": {
    "command": "tbcapi-tx-by-id-raw-response",
    "id": "68656d69"
  },
  "payload": {
    "tx": "02000000019554a7eb8bc903ea957c87964ab04a58d177692f15d7271cccb95258202f14b5bd00000000fdffffff014a010000000000002251208ec88237b5978e75e93feaeeb1343ff86ae2f2c348a903c9c9c4ad081926773500000000"
  }
}

🗂 Serialized Data

Type	command value
Request	tbcapi-tx-by-id-request
Response	tbcapi-tx-by-id-response

📤 Request

• tx_id: The ID of the transaction to retrieve, in reverse byte order and encoded as a hexadecimal string.

An example request to retrieve the transaction 0584ad53bf1938702b952026f7c986ab5d07ee7295c0ad3241c932a5483158ac:

{
  "header": {
    "command": "tbcapi-tx-by-id-request",
    "id": "68656d69"
  },
  "payload": {
    "tx_id": "0584ad53bf1938702b952026f7c986ab5d07ee7295c0ad3241c932a5483158ac"
  }
}

📥 Response

• tx: The requested transaction, if found, otherwise null.

An example response for a request with id 68656d69, requesting the transaction 0584ad53bf1938702b952026f7c986ab5d07ee7295c0ad3241c932a5483158ac:

{
  "header": {
    "command": "tbcapi-tx-by-id-response",
    "id": "68656d69"
  },
  "payload": {
    "tx": {
      "version": 2,
      "lock_time": 0,
      "tx_in": [
        {
          "outpoint": {
            "hash": "9554a7eb8bc903ea957c87964ab04a58d177692f15d7271cccb95258202f14b5",
            "index": 189
          },
          "signature_script": "",
          "tx_witness": null,
          "sequence": 4294967293
        }
      ],
      "tx_out": [
        {
          "value": 330,
          "pk_script": "51208ec88237b5978e75e93feaeeb1343ff86ae2f2c348a903c9c9c4ad0819267735"
        }
      ]
    }
  }
}