Categorygithub.com/hemilabs/heminetworkapitbcapi
package
0.8.0
Repository: https://github.com/hemilabs/heminetwork.git
Documentation: pkg.go.dev
Overview
Dependencies
8
Dependents
3

# README

📡 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

⚙️ 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:

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.

📚 Resources

For developers looking to integrate or extend functionality, view the raw Go types used in TBC's RPC commands: View tbcapi.go.

📡 Protocol

The RPC protocol is WebSocket-based and follows a standard request/response model. 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:

FieldDescription
timestampThe time at which the error occurred, in Unix seconds.
traceA unique string for tracing errors between server and client (internal errors only).
messageThe error message. For internal server errors, this will read internal error.

🗄️ Serialized Types

Block Header

A serialized block header contains the following data:

FieldDescription
versionThe version of the block.
prev_hashThe hash of the previous block header in the blockchain, in reverse byte order and encoded as a hexadecimal string.
merkle_rootThe hash derived from the hashes of all transactions in the block, in reverse byte order and encoded as a hexadecimal string.
timestampThe time the miner began hashing the header, represented in Unix seconds.
bitsThe difficulty target for the block.
nonceThe nonce used to create the hash that is less than or equal to the target threshold.

Address

Represents an encoded Bitcoin address, supporting these types:

  • P2PKH
  • P2SH
  • P2WPKH
  • P2WSH
  • P2TR

UTXO

A serialized UTXO contains the following data:

FieldDescription
tx_idThe transaction ID, in reverse byte order and encoded as a hexadecimal string.
valueThe value of the UTXO.
out_indexThe output index of the UTXO.

Transaction

A serialized transaction contains the following data:

FieldDescription
versionThe transaction version.
lock_timeThe block height or timestamp after which the transaction becomes final.
tx_inAn array of transaction inputs.
tx_outAn array of transaction outputs.

Transaction Input

A serialized transaction input contains the following data:

FieldDescription
outpointThe outpoint for the previous transaction output.
signature_scriptThe signature script for the transaction.
witnessAn array of the transaction witnesses, encoded as hexadecimal strings.
sequenceThe transaction sequence number.

Transaction Output

A serialized transaction output contains the following data:

FieldDescription
valueThe value of the transaction output in satoshis.
pk_scriptThe pubkey script of the transaction output, encoded as a hexadecimal string.

Outpoint

A serialized outpoint contains the following data:

FieldDescription
hashThe ID of the transaction holding the output to be spent, in reverse byte order and encoded as a hexadecimal string.
indexThe index of the specific output to spend from the transaction.

👉 Block Headers by Height

Retrieve the block headers by height.

🗂 Raw Data

Typecommand value
Requesttbcapi-block-headers-by-height-raw-request
Responsetbcapi-block-headers-by-height-raw-response

📤 Request

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

Retrieve block headers at height 43111:

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

📥 Response

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

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

Typecommand value
Requesttbcapi-block-headers-by-height-request
Responsetbcapi-block-headers-by-height-response

📤 Request

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

Retrieve block headers at height 43111:

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

📥 Response

Payload
Example Response

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

Typecommand value
Requesttbcapi-block-header-best-raw-request
Responsetbcapi-block-header-best-raw-response

📤 Request

Example Request

Retrieve the best block headers:

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

📥 Response

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

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

Typecommand value
Requesttbcapi-block-header-best-request
Responsetbcapi-block-header-best-response

📤 Request

Example Request

Retrieve the best block headers:

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

📥 Response

Payload
  • height: The best-known height.
  • block_header: The best-known block header.
Example Response

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

Typecommand value
Requesttbcapi-balance-by-address-request
Responsetbcapi-balance-by-address-response

📤 Request

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

Retrieve the balance for the address myqzZmRvoXmrhsrM5STiMGtNRxCFArHWRd:

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

📥 Response

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

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

Typecommand value
Requesttbcapi-utxos-by-address-raw-request
Responsetbcapi-utxos-by-address-raw-response

📤 Request

Payload
  • 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.
Example Request

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

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

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

Typecommand value
Requesttbcapi-utxos-by-address-request
Responsetbcapi-utxos-by-address-response

📤 Request

Payload
  • 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.
Example Request

Retrieve 5 UTXOs for the address mxVFsFW5N4mu1HPkxPttorvocvzeZ7KZyk:

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

📥 Response

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

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

Typecommand value
Requesttbcapi-tx-by-id-raw-request
Responsettbcapi-tx-by-id-raw-response

📤 Request

Payload
  • 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

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

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

Typecommand value
Requesttbcapi-tx-by-id-request
Responsetbcapi-tx-by-id-response

📤 Request

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

An example request to retrieve the transaction 0584ad53bf1938702b952026f7c986ab5d07ee7295c0ad3241c932a5483158ac:

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

📥 Response

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

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"
        }
      ]
    }
  }
}