RPC Calls

Getting Started

To interact with the RPC with the SDK we create an instance and connect to the RPC first

rpc = pyrin.RPC()
success = await rpc.connect()
result = await rpc.ping()

APIs

Ping

Description

await pyrin.rpc.ping()

Metrics

Get node specific details on process , connections, bandwidth and consensus metrics of the node

await pyrin.rpc.get_metrics(process_metrics=True, connection_metrics=True, bandwidth_metrics=True, consensus_metrics=True)


rpc = pyrin.RPC()
await rpc.connect()
result = await rpc.get_metrics(True, True, True, True)

print("process_metrics:")
print(result.process_metrics.resident_set_size) # 334454784
print(result.process_metrics.virtual_memory_size) # 594845696
print(result.process_metrics.core_num) # 20
print(result.process_metrics.cpu_usage) # 0.28120216727256775
print(result.process_metrics.fd_num) # 596
print(result.process_metrics.disk_io_read_bytes) # 748633484
print(result.process_metrics.disk_io_write_bytes) # 178008144
print(result.process_metrics.disk_io_read_per_sec) # 559988.875
print(result.process_metrics.disk_io_write_per_sec) # 20455.455078125

print("connection_metrics:")
print(result.connection_metrics.borsh_live_connections) # 1
print(result.connection_metrics.borsh_connection_attempts) # 7
print(result.connection_metrics.borsh_handshake_failures) # 0
print(result.connection_metrics.json_live_connections) # 0
print(result.connection_metrics.json_connection_attempts) # 0
print(result.connection_metrics.json_handshake_failures) # 0
print(result.connection_metrics.active_peers) # 8

print("bandwidth_metrics:")
print(result.bandwidth_metrics.borsh_bytes_tx) # 1511
print(result.bandwidth_metrics.borsh_bytes_rx) # 104
print(result.bandwidth_metrics.json_bytes_tx) # 0
print(result.bandwidth_metrics.json_bytes_rx) # 0
print(result.bandwidth_metrics.p2p_bytes_tx) # 346863
print(result.bandwidth_metrics.p2p_bytes_rx) # 754849
print(result.bandwidth_metrics.grpc_bytes_tx) # 0
print(result.bandwidth_metrics.grpc_bytes_rx) # 0

print("consensus_metrics:")
print(result.consensus_metrics.node_blocks_submitted_count) # 516
print(result.consensus_metrics.node_headers_processed_count) # 441
print(result.consensus_metrics.node_dependencies_processed_count) # 688
print(result.consensus_metrics.node_bodies_processed_count) # 441
print(result.consensus_metrics.node_transactions_processed_count) # 475
print(result.consensus_metrics.node_chain_blocks_processed_count) # 329
print(result.consensus_metrics.node_mass_processed_count) # 170432
print(result.consensus_metrics.node_database_blocks_count) # 225637
print(result.consensus_metrics.node_database_headers_count) # 225637
print(result.consensus_metrics.network_mempool_size) # 0
print(result.consensus_metrics.network_tip_hashes_count) # 2
print(result.consensus_metrics.network_difficulty) # 235332126575020.44
print(result.consensus_metrics.network_past_median_time) # 1719761907837
print(result.consensus_metrics.network_virtual_parent_hashes_count) # 2
print(result.consensus_metrics.network_virtual_daa_score) # 18943188

print("server_time:")
print(result.server_time) # 1719762094334

Server Info

Get versions, sync status and more network related

result = await rpc.get_server_info()
print(result.rpc_api_version) # [0, 1, 0, 0]
print(result.server_version) # 0.14.1
print(result.network_id) # mainnet
print(result.has_utxo_index) # True
print(result.is_synced) # True
print(result.virtual_daa_score) # 18944668

Sync Status

If the node is sycned, return True or False which is the same as (await rpc.get_server_info()).is_synced

assertTrue(await rpc.get_sync_status())

Current Network

assertEqual(await rpc.get_current_network(), "mainnet")

Submit Block

Submit a block into the DAG

Blocks are generally expected to have been generated using the get_block_template call

error = await rpc.submit_block({
            "header": {
                "hash": "bb149e176aecf79a60a22f57bc1c50b145100f7b6ec8bcb817070907a7ef44ec",
                "parents_by_level": [["bb149e176aecf79a60a22f57bc1c50b145100f7b6ec8bcb817070907a7ef44ec"]],
                "hash_merkle_root": "bb149e176aecf79a60a22f57bc1c50b145100f7b6ec8bcb817070907a7ef44ec",
                "accepted_id_merkle_root": "bb149e176aecf79a60a22f57bc1c50b145100f7b6ec8bcb817070907a7ef44ec",
                "utxo_commitment": "bb149e176aecf79a60a22f57bc1c50b145100f7b6ec8bcb817070907a7ef44ec",
                "version": 1,
                "timestamp": 1,
                "bits": 1,
                "nonce": 1,
                "daa_score": 1,
                "blue_work": 1,
                "blue_score": 1,
                "pruning_point": "bb149e176aecf79a60a22f57bc1c50b145100f7b6ec8bcb817070907a7ef44ec",
            },
            "transactions": [{
                "version": 1,
                "inputs": [{
                    "previous_outpoint": {
                        "transaction_id": "9e30e8d0327480c6c9c6b227537c018827a25e7e2e51280e8328acdbcf0fe76c",
                        "index": 0,
                    },
                    "signature_script": [],
                    "sequence": 0,
                    "sig_op_count": 0,
                    "verbose_data": None,
                }],
                "outputs": [],
                "lock_time": 1,
                "subnetwork_id": "0100000000000000000000000000000000000000",
                "gas": 1,
                "payload": [],
                "mass": 1,
                "verbose_data": {
                    "transaction_id": "bb149e176aecf79a60a22f57bc1c50b145100f7b6ec8bcb817070907a7ef44ec",
                    "hash": "bb149e176aecf79a60a22f57bc1c50b145100f7b6ec8bcb817070907a7ef44ec",
                    "mass": 1,
                    "block_hash": "bb149e176aecf79a60a22f57bc1c50b145100f7b6ec8bcb817070907a7ef44ec",
                    "block_time": 1,
                },
            }],

            # "hash": "bb149e176aecf79a60a22f57bc1c50b145100f7b6ec8bcb817070907a7ef44ec",
            # "transactions": 1,
            # "verbose_data": 1,
        }, True) # allow_non_daa_blocks

        if error > 0:
            # error == 1: block invalid
            # error == 2: is in ibd
            print(f"Failed to submit block: {error}")
        else:
            print("Block submitted successfully")

Get block template

Request a current block template

Callers are expected to solve the block template and submit it using the submit_block call.

result = await rpc.get_block_template("pyrin:qzn54t6vpasykvudztupcpwn2gelxf8y9p84szksr73me39mzf69uaalnymtx", [])
        print("result:", result.transactions[0].version)
        print("subnetwork_id:", result.transactions[0].subnetwork_id)
        print("verbose_data:", result.transactions[0].verbose_data)
        # print("result:", result.transactions[0].inputs[0].previous_outpoint.transaction_id)
        # print("result:", result.transactions[0].inputs[0].previous_outpoint.index)
        print("script_public_key:", result.transactions[0].outputs[0].script_public_key)
        print("result:", result.transactions[0].outputs[0].verbose_data)
        # print("result:", result.transactions[0].outputs[0].verbose_data.script_public_key_type) # TODO:
        # print("result:", result.transactions[0].outputs[0].verbose_data.script_public_key_address) # TODO:
        print("value:", result.transactions[0].outputs[0].value)

Get peer addresses

Requests the list of known pyipad addresses in the current network (mainnet, testnet, etc.)

result = await rpc.get_peer_addresses()
        print("result.known_addresses:", result.known_addresses) # ["127.0.0.1:13111"]
        print("result.banned_addresses:", result.banned_addresses) # ["127.0.0.1:13111"]

Get Sink

Requests the hash of the current virtual's selected parent.

result = await rpc.get_sink()
        print("result.sink:", result.sink) # 69c2ef342b17daddb222fe1cc94faab477f31b91f8f84496edfde430c41ca9cf

Get mempool entry

Requests information about a specific transaction in the mempool.

result = await rpc.get_mempool_entry("a419045a31afad611c32344fa269e712499d3e97f74271e4a2deffa734ba9f71", True, True)
        print("result", result)

Get mempool entries

Requests information about all the transactions currently in the mempool

result = await rpc.get_mempool_entries(True, True)
        print("get_mempool_entries", result)

Get connected peer info

Requests information about all the p2p peers currently connected to this node

result = await rpc.get_connected_peer_info()
        print("peer_info[0].id", result.peer_info[0].id) # sfdgabdb-4043-3e46-c333-adfasdfga6f4
        print("peer_info[0].address", result.peer_info[0].address) # 127.0.0.1:13111
        print("peer_info[0].last_ping_duration", result.peer_info[0].last_ping_duration) # 80
        print("peer_info[0].is_outbound", result.peer_info[0].is_outbound) # True
        print("peer_info[0].time_offset", result.peer_info[0].time_offset) # 677
        print("peer_info[0].user_agent", result.peer_info[0].user_agent) # /pyipad:0.13.4/pyipad:0.13.4/
        print("peer_info[0].advertised_protocol_version", result.peer_info[0].advertised_protocol_version) # 5
        print("peer_info[0].time_connected", result.peer_info[0].time_connected) # 24211336
        print("peer_info[0].is_ibd_peer", result.peer_info[0].is_ibd_peer) # False

Add peer

Adds a peer to the node's outgoing connection list.

await rpc.add_peer("192.168.1.2:13111", True)

Submit Transaction

Submits a transaction to the mempool.

await rpc.submit_transaction({
            "version": 0,
            "lock_time": 0,
            "subnetwork_id": "0100000000000000000000000000000000000000",
            "gas": 0,
            "payload": [],
            "mass": 0,
            # "inputs": [],
            "inputs": [{
                "previous_outpoint": {
                    "transaction_id": "9e30e8d0327480c6c9c6b227537c018827a25e7e2e51280e8328acdbcf0fe76c",
                    "index": 0,
                },
                "signature_script": [],
                "sequence": 0,
                "sig_op_count": 0,
                "verbose_data": None,
            }],
        }, True)

Get Block

Requests information about a specific block.

 block = await rpc.get_block("f269afa4a29dd7e751e15343d9edbb132e2e2f7daecb71b29908c9f6922ec165", True)

        # Header
        print("block.header.hash:", block.header.hash)
        print("block.header.version:", block.header.version)
        print("block.header.parents_by_level:", block.header.parents_by_level)
        print("block.header.hash_merkle_root:", block.header.hash_merkle_root)
        print("block.header.accepted_id_merkle_root:", block.header.accepted_id_merkle_root)
        print("block.header.utxo_commitment:", block.header.utxo_commitment)
        print("block.header.timestamp:", block.header.timestamp)
        print("block.header.bits:", block.header.bits)
        print("block.header.nonce:", block.header.nonce)
        print("block.header.daa_score:", block.header.daa_score)
        print("block.header.blue_work:", block.header.blue_work)
        print("block.header.blue_score:", block.header.blue_score)
        print("block.header.pruning_point:", block.header.pruning_point)

        # Transactions
        print("block.transactions[0].version:", block.transactions[0].version)
        print("block.transactions[0].lock_time:", block.transactions[0].lock_time)
        print("block.transactions[0].subnetwork_id:", block.transactions[0].subnetwork_id)
        print("block.transactions[0].gas:", block.transactions[0].gas)
        print("block.transactions[0].payload:", block.transactions[0].payload)
        print("block.transactions[0].mass:", block.transactions[0].mass)
        print("\n")

        print("block.transactions[1].inputs[0].previous_outpoint.transaction_id:", block.transactions[1].inputs[0].previous_outpoint.transaction_id)
        print("block.transactions[1].inputs[0].previous_outpoint.index:", block.transactions[1].inputs[0].previous_outpoint.index)
        print("block.transactions[1].inputs[0].signature_script:", block.transactions[1].inputs[0].signature_script)
        print("block.transactions[1].inputs[0].sequence:", block.transactions[1].inputs[0].sequence)
        print("block.transactions[1].inputs[0].sig_op_count:", block.transactions[1].inputs[0].sig_op_count)
        print("block.transactions[1].inputs[0].verbose_data:", block.transactions[1].inputs[0].verbose_data)
        print("\n")

        print("block.transactions[0].outputs[0].script_public_key:", block.transactions[0].outputs[0].script_public_key)
        print("block.transactions[0].outputs[0].value:", block.transactions[0].outputs[0].value)
        print("block.transactions[0].outputs[0].verbose_data:", block.transactions[0].outputs[0].verbose_data.script_public_key_type)
        print("block.transactions[0].outputs[0].verbose_data:", block.transactions[0].outputs[0].verbose_data.script_public_key_address)

        # Verbose data
        print("block.verbose_data.difficulty:", block.verbose_data.difficulty)
        print("block.verbose_data.selected_parent_hash:", block.verbose_data.selected_parent_hash)
        print("block.verbose_data.transaction_ids:", block.verbose_data.transaction_ids)
        print("block.verbose_data.is_header_only:", block.verbose_data.is_header_only)
        print("block.verbose_data.blue_score:", block.verbose_data.blue_score)
        print("block.verbose_data.children_hashes:", block.verbose_data.children_hashes)
        print("block.verbose_data.merge_set_blues_hashes:", block.verbose_data.merge_set_blues_hashes)
        print("block.verbose_data.merge_set_reds_hashes:", block.verbose_data.merge_set_reds_hashes)
        print("block.verbose_data.is_chain_block:", block.verbose_data.is_chain_block)

Get subnetwork

Requests information about a specific subnetwork.

subnetwork = await rpc.get_subnetwork("0000000000000000000000000000000000000000")
        print("subnetwork.gas:", subnetwork.gas)

Get virtual chain from block

Requests the virtual selected parent chain from some start_hash to this node's current virtual

virtual_chain = await rpc.get_virtual_chain_from_block("f269afa4a29dd7e751e15343d9edbb132e2e2f7daecb71b29908c9f6922ec165", True)
        print("virtual_chain.removed_chain_block_hashes:", virtual_chain.removed_chain_block_hashes)
        print("virtual_chain.added_chain_block_hashes:", virtual_chain.added_chain_block_hashes)
        print("virtual_chain.accepted_transaction_ids[0].accepting_block_hash:", virtual_chain.accepted_transaction_ids[0].accepting_block_hash)
        print("virtual_chain.accepted_transaction_ids[0].accepted_transaction_ids:", virtual_chain.accepted_transaction_ids[0].accepted_transaction_ids)

Get Blocks

Requests blocks between a certain block low_hash up to this node's current virtual

blocks = await rpc.get_blocks("f269afa4a29dd7e751e15343d9edbb132e2e2f7daecb71b29908c9f6922ec165", True, True)
        print("blocks.block_hashes", len(blocks.block_hashes))
        print("blocks.blocks", len(blocks.blocks)) 

Get Block count

Requests the current number of blocks in this node

Note that this number may decrease as pruning occurs.

 block_count = await rpc.get_block_count()
        print("block_count.header_count:", block_count.header_count)
        print("block_count.block_count:", block_count.block_count)

Get Block dag info

Requests general information about the current state of this node's DAG

block_dag_info = await rpc.get_block_dag_info()
        print("block_dag_info.network:", block_dag_info.network)
        print("block_dag_info.block_count:", block_dag_info.block_count)
        print("block_dag_info.header_count:", block_dag_info.header_count)
        print("block_dag_info.tip_hashes:", block_dag_info.tip_hashes)
        print("block_dag_info.difficulty:", block_dag_info.difficulty)
        print("block_dag_info.past_median_time:", block_dag_info.past_median_time)
        print("block_dag_info.virtual_parent_hashes:", block_dag_info.virtual_parent_hashes)
        print("block_dag_info.pruning_point_hash:", block_dag_info.pruning_point_hash)
        print("block_dag_info.virtual_daa_score:", block_dag_info.virtual_daa_score)
        print("block_dag_info.sink:", block_dag_info.sink)

Resolve finality conflict

await rpc.resolve_finality_conflict("f269afa4a29dd7e751e15343d9edbb132e2e2f7daecb71b29908c9f6922ec165")

Shutdown

Shuts down this node.

await rpc.shutdown()

Get Headers

Requests headers between the given start_hash and the current virtual, up to the given limit

headers = await rpc.get_headers("f269afa4a29dd7e751e15343d9edbb132e2e2f7daecb71b29908c9f6922ec165", 1000, True)
        print("headers", headers)

Get balance by address

Returns the total balance in unspent transactions towards a given address.

This call is only available when this node was started with --utxoindex.

balance = await rpc.get_balance_by_address("pyrin:qzn54t6vpasykvudztupcpwn2gelxf8y9p84szksr73me39mzf69uaalnymtx")
        print("balance:", balance)

Get utxos by address

Requests all current UTXOs for the given node addresses.

This call is only available when this node was started with --utxoindex.

utxos = await rpc.get_utxos_by_addresses(["pyrin:qzn54t6vpasykvudztupcpwn2gelxf8y9p84szksr73me39mzf69uaalnymtx"])
        print("utxos:", len(utxos))
        print("utxos[0].address", utxos[0].address)
        print("utxos[0].outpoint.transaction_id", utxos[0].outpoint.transaction_id)
        print("utxos[0].outpoint.index", utxos[0].outpoint.index)
        print("utxos[0].utxo_entry.amount", utxos[0].utxo_entry.amount)
        print("utxos[0].utxo_entry.script_public_key", utxos[0].utxo_entry.script_public_key)
        print("utxos[0].utxo_entry.block_daa_score", utxos[0].utxo_entry.block_daa_score)
        print("utxos[0].utxo_entry.is_coinbase", utxos[0].utxo_entry.is_coinbase)

Get sink blue score

Requests the blue score of the current selected parent of the virtual block.

sink_blue_score = await rpc.get_sink_blue_score()
        print("sink_blue_score:", sink_blue_score)

Ban

Bans the given ip.

await rpc.ban("192.168.1.2")

Unban

Unbans the given ip.

await rpc.unban("192.168.1.2")

Get info

Returns info about the node.

 info = await rpc.get_info()
        print("get_info.p2p_id:", info.p2p_id)
        print("get_info.mempool_size:", info.mempool_size)
        print("get_info.server_version:", info.server_version)
        print("get_info.is_utxo_indexed:", info.is_utxo_indexed)
        print("get_info.is_synced:", info.is_synced)
        print("get_info.has_notify_command:", info.has_notify_command)
        print("get_info.has_message_id:", info.has_message_id)

Estimate network hashes per second

Window_size: u32, start_hash: Option<RpcHash>
hashes_per_second = await rpc.estimate_network_hashes_per_second(1000)
        print("hashes_per_second:", hashes_per_second)

Last updated