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:

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

Fetch the last height of the latest block:

fetch_last_height
Request
Reply	ec(4) + height(4)

Fetch a block header by height:

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

Fetch a block header by hash:

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

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

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

fetch_block_transaction_hashes
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”.

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”.

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”.

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.