This is a list of definitions for all the messages exchanged by the client in the cruzbit protocol. Sans official documentation, the canonical source for this document is the cruzbit reference implementation source code in Go (computer language). The messages are defined in protocol.go.
This document is newly constructed, and it is therefore expected to contain inaccuracies and/or a incomplete information. Please do not rely on the information in this document until it is finalized (and this message is removed).
This document describes messages in the cruzbit.1 protocol version.
When hashing headers in JSON format, the order of fields is important. The order fields are listed here is the order they are expected to be listed in a JSON string before hasing. Under most circumstances, cruzbit attempts to adhere to strict JSON formatting rules, therefore, any unquoted newlines and spaces should be removed from JSON strings when transmitting to a peer.
The follwing are values which apply to generation and ingestion of protocol messages.
| Constant | Value | Description |
|---|---|---|
| MAX_PROTOCOL_MESSAGE_LENGTH | 2 * 1024 * 1024 | 2097152 - All messages must be shorter than this length in characters. |
All messages are JSON, and have the following structure:
{
"type": type_name,
"body": content
}The body portion of the message may be omitted if it has no content. The value of body assigned based on the type of message indicated in the type key. For example, a FilterAddMessage might look like this:
{
"type": "filter_add",
"body": {
"public_keys": [
"uKyCfMBEZGvF4bJZXJONoHcPIaSPUxFPh1uTi31ctxc=",
"9yRiPf5WZqnQqn7iomF2s3SFBCofXKNBtfc6rMJG4fw="
]
}
}In constructing messages, certain entities (or structures) are frequently reused. For brevity, these are defined once, below, and then referred to by name in subsequent message definitions.
{
"previous": string,
"hash_list_root": string,
"time": int,
"target": string,
"chain_work": string,
"nonce": int,
"height": int,
"transaction_count": int
}Example:
{
"previous": "0000000024efc1ac4e8adc1d058f165f46b368d1e4d2954f1e0da6d3dd4843b2",
"hash_list_root": "3ec0ab432f5395809784785c21707ec9373cdd0d56de352de60f1c33913b6190",
"time": 1561267226,
"target": "00000000ffff0000000000000000000000000000000000000000000000000000",
"chain_work": "0000000000000000000000000000000000000000000000000000063706370637",
"nonce": 3721276493824185,
"height": 1590,
"transaction_count": 1
}PublicKeyBalance represents a public key and its current balance in a BalancesMessage.
{
"public_key": string,
"balance", int
}Note that cruzbit (1e-8 cruz) is the unit for balance.
Example:
{
"public_key": "uKyCfMBEZGvF4bJZXJONoHcPIaSPUxFPh1uTi31ctxc=",
"balance": 25002000000
}{
"time": int,
"nonce": int,
"from": string,
"to": string,
"amount": int,
"fee": int,
"memo": string,
"matures": int,
"expires": int,
"series": int,
"signature": string
}The following fields may be omitted: from, fee, memo, matures, expires, and signature.
Example:
{
"time": 1561267196,
"nonce": 1678096926,
"to": "jAGxWfCImeDIqFfk8cfi3RDyQSOE2z4dNbTBG6iJ/uc=",
"amount": 5000000000,
"series": 2
}InvBlockMessage is used to communicate blocks available for download.
{
"type": "inv_block",
"body": {
"block_ids": []string
}
}Example:
{
"type": "inv_block",
"body": {
"block_ids": [
"00000000ffd022655096c4a9ac42839ba237f8127ac4e22e7a4b9d0e667a88b7"
]
}
}Clients will send a InvBlockMessage with up to maxBlocksPerInv (500 in the reference implementation) block_id at a time (25 typical) as a response to a FindCommonAncestor message. A InvBlockMessage with a single block_id will be sent as new blocks are found (mined). Arrays of block_id are not necessarily indexed chronologically nor can they be expected to contain contiguous blocks.
GetBlockMessage is used to request a block for download.
{
"type": "get_block",
"body": {
"block_id": string
}
}Example:
{
"type": "get_block",
"body": {
"block_id": "00000000ffd022655096c4a9ac42839ba237f8127ac4e22e7a4b9d0e667a88b7"
}
}GetBlockByHeightMessage is used to request a block for download.
{
"type": "get_block_by_height",
"body": {
"height": int
}
}Example:
{
"type": "get_block_by_height",
"body": {
"height": 16284
}
}BlockMessage is used to send a peer a complete block.
{
"type": "block",
"body": {
"block_id": string,
"block": {
"header": BlockHeader,
"transactions": []Transaction
}
}
}The block_id and block fields may be omitted.
Example:
{
"type": "block",
"body": {
"block_id": "00000000ffed1464ddeb9deeb0d94064f0c6aa1b47300b6855b789b82160995d",
"block": {
"header": {
"previous": "0000000024efc1ac4e8adc1d058f165f46b368d1e4d2954f1e0da6d3dd4843b2",
"hash_list_root": "3ec0ab432f5395809784785c21707ec9373cdd0d56de352de60f1c33913b6190",
"time": 1561267226,
"target": "00000000ffff0000000000000000000000000000000000000000000000000000",
"chain_work": "0000000000000000000000000000000000000000000000000000063706370637",
"nonce": 3721276493824185,
"height": 1590,
"transaction_count": 1
},
"transactions": [
{
"time": 1561267196,
"nonce": 1678096926,
"to": "jAGxWfCImeDIqFfk8cfi3RDyQSOE2z4dNbTBG6iJ/uc=",
"amount": 5000000000,
"series": 2
}
]
}
}
}GetBlockHeaderMessage is used to request a block header.
{
"type": "get_block_header",
"body": {
"block_id": string
}
}Example:
{
"type": "get_block_header",
"body": {
"block_id": "00000000ffed1464ddeb9deeb0d94064f0c6aa1b47300b6855b789b82160995d"
}
}GetBlockHeaderByHeightMessage is used to request a block header.
{
"type": "get_block_header_by_height",
"body": {
"height": int
}
}Example:
{
"type": "get_block_header_by_height",
"body": {
"height": 1590
}
}BlockHeaderMessage is used to send a peer a block's header.
{
"type": "block_header",
"body": {
"block_id": string,
"header": BlockHeader
}
}Example:
{
"type": "block_header",
"body": {
"block_id": "00000000ffed1464ddeb9deeb0d94064f0c6aa1b47300b6855b789b82160995d",
"header": {
"previous": "0000000024efc1ac4e8adc1d058f165f46b368d1e4d2954f1e0da6d3dd4843b2",
"hash_list_root": "3ec0ab432f5395809784785c21707ec9373cdd0d56de352de60f1c33913b6190",
"time": 1561267226,
"target": "00000000ffff0000000000000000000000000000000000000000000000000000",
"chain_work": "0000000000000000000000000000000000000000000000000000063706370637",
"nonce": 3721276493824185,
"height": 1590,
"transaction_count": 1
}
}
}FindCommonAncestorMessage is used to find a common ancestor with a peer.
{
"type": "find_common_ancestor",
"body": {
"block_ids": []string
}
}Example:
{
"type": "find_common_ancestor",
"body": {
"block_ids": [
"0000000001ed5000666f56a7846fd7f9734161e727abbc70f5e28fa216fef50f",
"00000000a4d6df3af040f49d24fb6422187d44e95e2962900ae0dfcda43e7359",
"00000000e29a7850088d660489b7b9ae2da763bc3bd83324ecc54eee04840adb"
]
}
}The peer will respond with an InvBlockMessage containing any subsequent block_ids, up to 500 at a time. If at the tip, the peer will respond with an FindCommonAncestorMessage.
GetBalanceMessage requests a public key's balance.
{
"type": "get_balance",
"body": {
"public_key": string
}
}Example:
{
"type": "get_balance",
"body": {
"public_key": "uKyCfMBEZGvF4bJZXJONoHcPIaSPUxFPh1uTi31ctxc="
}
}BalanceMessage is used to send a public key's balance to a peer.
{
"type": "balance",
"body": {
"block_id": string,
"height": int,
"public_key": string,
"balance", int,
"error": string
}
}The following values may be omitted: block_id, height, and error. Note that balance is returned in cruzbits (1e-8 cruz; 100,000,000 cruzbit = 1 cruz).
Example:
{
"type": "balance",
"body": {
"public_key": "uKyCfMBEZGvF4bJZXJONoHcPIaSPUxFPh1uTi31ctxc=",
"balance", 25002000000
}
}GetBalancesMessage requests a set of public key balances.
{
"type": "get_balances",
"body": {
[]string
}
}Example:
{
"type": "get_balances",
"body": {
[
"uKyCfMBEZGvF4bJZXJONoHcPIaSPUxFPh1uTi31ctxc=",
"9yRiPf5WZqnQqn7iomF2s3SFBCofXKNBtfc6rMJG4fw="
]
}
}BalancesMessage is used to send one or more public key balances to a peer.
{
"type": "balances",
"body": {
"block_id": string,
"height": int,
"balances": []PublicKeyBalance,
"error": string
}
}All fields may be omitted.
Example:
{
"type": "balances",
"body": {
"balances": [
{
"public_key": "uKyCfMBEZGvF4bJZXJONoHcPIaSPUxFPh1uTi31ctxc=",
"balance": 25002000000
},
{
"public_key": "9yRiPf5WZqnQqn7iomF2s3SFBCofXKNBtfc6rMJG4fw=",
"balance": 164099167000
}
]
}
}GetTransactionMessage is used to request a confirmed transaction.
{
"type": "get_transaction",
"body": {
"transaction_id": string
}
}Example:
{
"type": "get_transaction",
"body": {
"transaction_id": "701f3f8ab27527afe8922417c7bb5a6deab676174e4a8c8bcfcb29c9705e3d5c"
}
}TransactionMessage is used to send a peer a confirmed transaction.
{
"type": "transaction",
"body": {
"block_id": string,
"height": int,
"transaction_id": string,
"transaction": Transaction
}
}The block_id, height, and transaction fields may be omitted.
Example:
{
"type": "transaction",
"body": {
"block_id": "00000000000464243307630cfd25726cf1629668da17e9cc915c588e5aaa4616",
"height": 16297,
"transaction_id": "701f3f8ab27527afe8922417c7bb5a6deab676174e4a8c8bcfcb29c9705e3d5c",
"transaction": {
"time": 1564198719,
"nonce": 1151521172,
"from": "fB5zzmvAsfXTDBwczxZY+HO02Z2L1hRz+6U1fmyOjpA=",
"to": "TJKG2bpVgEXEwHlATF4Dfz+J+MTaJzSr2xZUjXS7IUI=",
"amount": 59999000000,
"fee": 1000000,
"memo": "fe7a5505135a451e806dc948eaa6a559",
"expires": 16299,
"series": 17,
"signature": "aNJwO+WhUc9yL5qYynSok7TkVcNYkLjchpM0ovKXjlWH1Pqb7UAHJSvzme5e8vKCRcQs4IVNGZX414eGh/6ICg=="
}
}
}GetTipHeaderMessage is used to request the header for the tip block in the block chain.
{
"type": "get_tip_header"
}GetTipHeaderMessage has an empty body.
TipHeaderMessage is used to send a peer the header for the tip block in the block chain.
{
"type": "tip_header",
"body": {
"block_id": string,
"header": BlockHeader,
"time_seen": int
}
}Example:
{
"type": "tip_header",
"body": {
"block_id": "00000000000785100ecb16d5acbe792ca61daf9fc157d4c2b251182faf5d30b0",
"header": {
"previous": "0000000000033c53280cbdc1742483a4635b0ebac084ce82fa2cbbd768b468f3",
"hash_list_root": "0adf975ad85f1456286f3a5acde29bcdf600e2a6faf010d455d62f87505931fa",
"time": 1564257595,
"target": "000000000007a38c469f3be96898a11435ea27592c2bae351147392e9cd3408d",
"chain_work": "00000000000000000000000000000000000000000000000000ad6ace9ad82af2",
"nonce": 3762307550831105,
"height": 16477,
"transaction_count": 1
},
"time_seen": 1564257719
}
}PushTransactionMessage is used to push a newly processed unconfirmed transaction to peers.
{
"type": "push_transaction",
"body": {
"transaction": Transaction
}
}Example:
{
"type": "push_transaction",
"body": {
"transaction": {
"time": 1564198719,
"nonce": 1151521172,
"from": "fB5zzmvAsfXTDBwczxZY+HO02Z2L1hRz+6U1fmyOjpA=",
"to": "TJKG2bpVgEXEwHlATF4Dfz+J+MTaJzSr2xZUjXS7IUI=",
"amount": 59999000000,
"fee": 1000000,
"memo": "fe7a5505135a451e806dc948eaa6a559",
"expires": 16299,
"series": 17,
"signature": "aNJwO+WhUc9yL5qYynSok7TkVcNYkLjchpM0ovKXjlWH1Pqb7UAHJSvzme5e8vKCRcQs4IVNGZX414eGh/6ICg=="
}
}
}PushTransactionResultMessage is sent in response to a PushTransactionMessage
{
"type": "push_transaction_result",
"body": {
"transaction_id": string,
"error": string
}
}The error field can be omitted if empty.
Example:
{
"type": "push_transaction_result",
"body": {
"transaction_id": "701f3f8ab27527afe8922417c7bb5a6deab676174e4a8c8bcfcb29c9705e3d5c"
}
}FilterLoadMessage is used to request that we load a filter which is used to filter transactions returned to the peer based on interest.
{
"type": "filter_load",
"body": {
"type": string,
"filter": string
}
}FilterAddMessage is used to request the addition of the given public keys to the current filter. The filter is created if it's not set.
{
"type": "filter_add",
"body": {
"public_keys": []string
}
}Example:
{
"type": "filter_add",
"body": {
"public_keys": [
"9yRiPf5WZqnQqn7iomF2s3SFBCofXKNBtfc6rMJG4fw=",
"uKyCfMBEZGvF4bJZXJONoHcPIaSPUxFPh1uTi31ctxc="
]
}
}FilterResultMessage indicates whether or not the filter request was successful.
{
"type": "filter_result",
"body": {
"error": string
}
}The error field may be omitted.
Example:
{
"type": "filter_result"
}FilterBlockMessage represents a pared down block containing only transactions relevant to the peer given their filter.
{
"type": "filter_block",
"body": {
"block_id": string,
"header": BlockHeader,
"transactions": []Transaction
}
}Example:
{
"type": "filter_block",
"body": {
"block_id": "00000000ffed1464ddeb9deeb0d94064f0c6aa1b47300b6855b789b82160995d",
"header": {
"previous": "0000000024efc1ac4e8adc1d058f165f46b368d1e4d2954f1e0da6d3dd4843b2",
"hash_list_root": "3ec0ab432f5395809784785c21707ec9373cdd0d56de352de60f1c33913b6190",
"time": 1561267226,
"target": "00000000ffff0000000000000000000000000000000000000000000000000000",
"chain_work": "0000000000000000000000000000000000000000000000000000063706370637",
"nonce": 3721276493824185,
"height": 1590,
"transaction_count": 1
},
"transactions": [
{
"time": 1561267196,
"nonce": 1678096926,
"to": "jAGxWfCImeDIqFfk8cfi3RDyQSOE2z4dNbTBG6iJ/uc=",
"amount": 5000000000,
"series": 2
}
]
}
}FilterTransactionQueueMessage returns a pared down view of the unconfirmed transaction queue containing only transactions relevant to the peer given their filter.
{
"type": "filter_transaction_queue",
"body": {
"transactions": []Transaction,
"error": string
}
}The error field may be omitted.
Example:
{
"type": "filter_transaction_queue",
"body": {
"transactions": [
{
"time": 1561267196,
"nonce": 1678096926,
"to": "jAGxWfCImeDIqFfk8cfi3RDyQSOE2z4dNbTBG6iJ/uc=",
"amount": 5000000000,
"series": 2
}
]
}
}GetPublicKeyTransactionsMessage requests transactions associated with a given public key over a given height range of the block chain.
{
"type": "get_public_key_transactions",
"body": {
"public_key": string,
"start_height": int,
"start_index": int,
"end_height": int,
"limit": int
}
}Example:
{
"type": "get_public_key_transactions",
"body": {
"public_key": "uKyCfMBEZGvF4bJZXJONoHcPIaSPUxFPh1uTi31ctxc=",
"start_height": 6848,
"start_index": 0,
"end_height": 15525,
"limit": 0
}
}PublicKeyTransactionsMessage is used to return a list of block headers and the transactions relevant to the public key over a given height range of the block chain.
{
"type": "public_key_transactions",
"body": {
"public_key": string,
"start_height": int,
"stop_height": int,
"stop_index": int,
"filter_blocks": []FilterBlockMessage,
"error": string
}
}The error field may be omitted. Note, the filter_blocks field is an array of FilterBlockMessage body fields (not the entire message structure).
Example:
{
"type": "public_key_transactions",
"body": {
"public_key": "uKyCfMBEZGvF4bJZXJONoHcPIaSPUxFPh1uTi31ctxc=",
"start_height": 6848,
"stop_height": 15525,
"stop_index": 1,
"filter_blocks": [
{
"block_id": "00000000014e1f0d57de66590529bd43d856da327c2c4f9d578fed53c004284e",
"header": {
"previous": "00000000008624625959c4bb370797213be3e7a0689631b1828d5d0393cbf678",
"hash_list_root": "174a6207dc172248f8893e235bb06a2ca9e8e7db26a935befef02230b04cf641",
"time": 1562695351,
"target": "00000000042a8ac2a42a42a42a42a42a42a42a42a42a42a42a42a42a42a42a42",
"chain_work": "000000000000000000000000000000000000000000000000000165a3d6459a6c",
"nonce": 7780501328818085,
"height": 6848,
"transaction_count": 1
},
"transactions": [
{
"time": 1562694035,
"nonce": 894650829,
"to": "uKyCfMBEZGvF4bJZXJONoHcPIaSPUxFPh1uTi31ctxc=",
"amount": 5000000000,
"memo": "jstnryan",
"series": 7
}
]
},
...
}
]
}
}GetPeerAddressesMessage is used to request a list of known peer addresses.
{
"type": "get_peer_addresses"
}GetPeerAddressesMessage has an empty body.
PeerAddressesMessage is used to communicate a list of potential peer addresses known by a peer.
{
"type": "peer_addresses",
"body": {
"addresses": []string
}
}Example:
{
"type": "peer_addresses",
"body": {
"addresses": [
"66.172.27.47:8831",
"66.172.12.98:8831",
"66.117.62.146:8831",
"138.68.87.48:8831",
"67.177.244.230:8831",
"116.203.64.99:8831",
]
}
}The addresses field must not be empty.
GetTransactionRelayPolicyMessage is used to request a peer's current fee settings.
{
"type": "get_transaction_relay_policy"
}GetTransactionRelayPolicyMessage has an empty body.
TransactionRelayPolicyMessage is used to communicate this node's current settings for min fee and min amount, sent in response to GetTransactionRelayPolicyMessage.
{
"type": "transaction_relay_policy",
"body": {
"min_fee": int,
"min_amount": int
}
}Note, amounts are represented in cruzbit (1e-8 cruz).
Example:
{
"type": "transaction_relay_policy",
"body": {
"min_fee": 1000000,
"min_amount": 1000000
}
}GetWorkMessage is used by a mining peer to request mining work.
{
"type": "get_work",
"body": {
"public_keys": []string,
"memo": string
}
}The memo field may be omitted.
Example:
{
"type": "get_work",
"body": {
"public_keys": [
"uKyCfMBEZGvF4bJZXJONoHcPIaSPUxFPh1uTi31ctxc="
],
"memo": "Mined by jstnryan"
}
}WorkMessage is used by a client to send work to perform to a mining peer.
{
"type": "work",
"body": {
"work_id": int,
"header": BlockHeader,
"min_time": int,
"error": string
}
}The timestamp and nonce in the header can be manipulated by the peer. It is the mining peer's responsibility to ensure the timestamp is not set below the minimum timestamp and that the nonce does not exceed MAX_NUMBER (2^53-1). The error field may be omitted.
Example:
{
"type": "work",
"body": {
"work_id": 1654409027,
"header": {
"previous": "000000000000e14b714c81f767e85c8bba55873b1cf13b150b0b8aafbe476abd",
"hash_list_root": "4c4eac39aefc8e708f6c77e1a5daa2a34621e5c63e3d32263d83685c22efad89",
"time": 1564266969,
"target": "000000000007a38c469f3be96898a11435ea27592c2bae351147392e9cd3408d",
"chain_work": "00000000000000000000000000000000000000000000000000afc609da3f35f0",
"nonce": 3937900903209282,
"height": 16495,
"transaction_count": 1
},
"min_time": 1564264408
}
}Mining pool implementations may optionally add a non-standard target property to the body of work messages. The value of target is a 32 byte hexadecimal integer representing the minium difficulty of a share that will be accepted by the pool.
{
"type": "work",
"body": {
"work_id": int,
"header": BlockHeader,
"min_time": int,
"target": string,
"error": string
}
}Example:
{
"type": "work",
"body": {
"work_id": 1781,
"header": {
"previous": "00000000000062c62e626216bf906a25db3b6403ce9cd5ed2d3f97a84b4464cc",
"hash_list_root": "1a8ba4010591f9beb57189a4c590bdb9cde9103b28e002390d7d4ab9f553b36c",
"time": 1566108037,
"target": "000000000000d8b2bac96dbacd8556a6dba9a0b552e24265fd2c0ffe35d5d65c",
"chain_work": "00000000000000000000000000000000000000000000000008213bb3ab1de110",
"nonce": 613471930171392,
"height": 22525,
"transaction_count": 16
},
"min_time": 1566108037,
"target": "000000000fffffffffffffffffffffffffffffffffffffffffffffffffffffff"
}
}SubmitWorkMessage is used by a mining peer to submit a potential solution to the client.
{
"type": "submit_work",
"body": {
"work_id": int,
"header": BlockHeader
}
}Example:
{
"type": "submit_work",
"body": {
"work_id": 1654409027,
"header": {
"previous": "000000000000e14b714c81f767e85c8bba55873b1cf13b150b0b8aafbe476abd",
"hash_list_root": "4c4eac39aefc8e708f6c77e1a5daa2a34621e5c63e3d32263d83685c22efad89",
"time": 1564266969,
"target": "000000000007a38c469f3be96898a11435ea27592c2bae351147392e9cd3408d",
"chain_work": "00000000000000000000000000000000000000000000000000afc609da3f35f0",
"nonce": 3937900903209282,
"height": 16495,
"transaction_count": 1
},
}
}SubmitWorkMessage is used to inform a mining peer of the result of its work.
{
"type": "submit_work_result",
"body": {
"work_id": int,
"error": string
}
}The error field may be omitted.
Example:
{
"type": "submit_work_result",
"body": {
"work_id": 1654409027
}
}