4. API Calls

The values in brackets indicate the size of the value.

Variable length lists can be calculated using the size of the message.

4.1. Blockchain

These commands are prefixed with “blockchain.”. For instance “blockchain.fetch_transaction”.

Fetch a transaction by hash from the blockchain:

Request tx_hash(32)
Reply ec(4) + tx

Fetch the last height of the latest block:

Reply ec(4) + height(4)

Fetch a block header by height:

Request height(4)
Reply ec(4) + header(80)

Fetch a block header by hash:

Request block_hash(32)
Reply ec(4) + header(80)

Fetch a list of ordered transaction hashes belonging to a block.

Request height(4)
Reply ec(4) + hash_list(hash_list_size * 32)
Request block_hash(32)
Reply ec(4) + hash_list(hash_list_size * 32)

4.2. Transaction pool

These commands are prefixed with “transaction_pool.”. For instance “transaction_pool.validate”.

Request tx
Reply ec(4) + index_list(index_list_size * 4)

Validates an unconfirmed transaction using the transaction pool. The index list is a collection of unconfirmed indexes if a transaction is validated successfully. The unconfirmed indexes are the inputs which depend on other transactions in the pool that are unconfirmed. Clients may wish to use it but it can be safely ignored.

In the case of error::input_not_found or error::validate_inputs_failed, then the unconfirmed index list will be used to indicate the first problematic input, and the index_list_size will be 1.

4.3. Protocol

These commands are prefixed with “protocol.”. For instance “protocol.broadcast_transaction”.

Request tx
Reply ec(4)

Broadcasts a transaction to the currently connected nodes on the backend. Clients are advised to find their own broadcast method and use leave this as a backup method. An example might be running a broadcast daemon on localhost that is responsible for actually checking a transaction gets delivered to the network and responding back if it wasn’t accepted. Obelisk does not do this - it simply relays the transaction straight onto connected nodes.

4.4. Address

These commands are prefixed with “address.”. For instance “address.fetch_history”.

Request address_version_byte(1) + address_hash(20) + from_height(4)
Reply ec(4) + row_list

from_height indicates the starting height of the fetch_history() operation. This is to avoid potentially redundant re-fetching of the entire history when repeatedly calling fetch_history(). Typically the client before shutdown will save the current version of their history along with the latest block height and hash. Upon restarting, the client will call fetch_history() with the saved block height. Then the client would query blockchain::fetch_block_header() to compare the block hash is the same as during shutdown. If the block hash has changed then it’s apt to call fetch_history() with a from_height of 0.

The row_list size is calculated using (reply_data.size() - 4) / row_size. Each row represents a credit/debit pairing. The output sending credit, and the spend of that money (if any exists). If the output/spend is unconfirmed then the block height is set to 0.

Row Fields Type Description
output hash hash(32) Transaction hash of the output.
output index uint32(4) Index of the output.
output height uint32(4) Block height containing output transaction.
value (Satoshis) uint64(8) Satoshi value of credit.
spend hash hash(32) Transaction hash of input spend (0x00...00 if none).
spend index uint32(4) Input index.
spend height uint32(4) Block height containing input spend transaction.

By polling the latest block height, the client can display the number of confirmations. We don’t need to worried about consistency and polling from the same worker as confirmations are aesthetic and part of gradual network consensus.

Table Of Contents

Previous topic

3. Example

Next topic

5. Subscribe

This Page