Trait ckb_rpc::module::NetRpc

source · 
pub trait NetRpc {
    // Required methods
    fn local_node_info(&self) -> Result<LocalNode>;
    fn get_peers(&self) -> Result<Vec<RemoteNode>>;
    fn get_banned_addresses(&self) -> Result<Vec<BannedAddr>>;
    fn clear_banned_addresses(&self) -> Result<()>;
    fn set_ban(
        &self,
        address: String,
        command: String,
        ban_time: Option<Timestamp>,
        absolute: Option<bool>,
        reason: Option<String>,
    ) -> Result<()>;
    fn sync_state(&self) -> Result<SyncState>;
    fn set_network_active(&self, state: bool) -> Result<()>;
    fn add_node(&self, peer_id: String, address: String) -> Result<()>;
    fn remove_node(&self, peer_id: String) -> Result<()>;
    fn ping_peers(&self) -> Result<()>;
}
Expand description

RPC Module Net for P2P network.

Required Methods§

source

fn local_node_info(&self) -> Result<LocalNode>

Returns the local node information.

The local node means the node itself which is serving the RPC.

§Examples

Request

{
  "id": 42,
  "jsonrpc": "2.0",
  "method": "local_node_info",
  "params": []
}

Response

{
  "id": 42,
  "jsonrpc": "2.0",
  "result": {
    "active": true,
    "addresses": [
      {
        "address": "/ip4/192.168.0.2/tcp/8112/p2p/QmTRHCdrRtgUzYLNCin69zEvPvLYdxUZLLfLYyHVY3DZAS",
        "score": "0xff"
      },
      {
        "address": "/ip4/0.0.0.0/tcp/8112/p2p/QmTRHCdrRtgUzYLNCin69zEvPvLYdxUZLLfLYyHVY3DZAS",
        "score": "0x1"
      }
    ],
    "connections": "0xb",
    "node_id": "QmTRHCdrRtgUzYLNCin69zEvPvLYdxUZLLfLYyHVY3DZAS",
    "protocols": [
      {
        "id": "0x0",
        "name": "/ckb/ping",
        "support_versions": [
          "0.0.1"
        ]
      },
      {
        "id": "0x1",
        "name": "/ckb/discovery",
        "support_versions": [
          "0.0.1"
        ]
      }
    ],
    "version": "0.34.0 (f37f598 2020-07-17)"
  }
}
source

fn get_peers(&self) -> Result<Vec<RemoteNode>>

Returns the connected peers’ information.

§Examples

Request

{
  "id": 42,
  "jsonrpc": "2.0",
  "method": "get_peers",
  "params": []
}

Response

{
  "id": 42,
  "jsonrpc": "2.0",
  "result": [
    {
      "addresses": [
        {
          "address": "/ip6/::ffff:18.185.102.19/tcp/8115/p2p/QmXwUgF48ULy6hkgfqrEwEfuHW7WyWyWauueRDAYQHNDfN",
          "score": "0x64"
        },
        {
          "address": "/ip4/18.185.102.19/tcp/8115/p2p/QmXwUgF48ULy6hkgfqrEwEfuHW7WyWyWauueRDAYQHNDfN",
          "score": "0x64"
        }
      ],
      "connected_duration": "0x2f",
      "is_outbound": true,
      "last_ping_duration": "0x1a",
      "node_id": "QmXwUgF48ULy6hkgfqrEwEfuHW7WyWyWauueRDAYQHNDfN",
      "protocols": [
        {
          "id": "0x4",
          "version": "0.0.1"
        },
        {
          "id": "0x2",
          "version": "0.0.1"
        },
        {
          "id": "0x1",
          "version": "0.0.1"
        },
        {
          "id": "0x64",
          "version": "1"
        },
        {
          "id": "0x6e",
          "version": "1"
        },
        {
          "id": "0x66",
          "version": "1"
        },
        {
          "id": "0x65",
          "version": "1"
        },
        {
          "id": "0x0",
          "version": "0.0.1"
        }
      ],
      "sync_state": {
        "best_known_header_hash": null,
        "best_known_header_number": null,
        "can_fetch_count": "0x80",
        "inflight_count": "0xa",
        "last_common_header_hash": null,
        "last_common_header_number": null,
        "unknown_header_list_size": "0x20"
      },
      "version": "0.34.0 (f37f598 2020-07-17)"
    },
    {
      "addresses": [
        {
          "address": "/ip4/174.80.182.60/tcp/52965/p2p/QmVTMd7SEXfxS5p4EEM5ykTe1DwWWVewEM3NwjLY242vr2",
          "score": "0x1"
        }
      ],
      "connected_duration": "0x95",
      "is_outbound": true,
      "last_ping_duration": "0x41",
      "node_id": "QmSrkzhdBMmfCGx8tQGwgXxzBg8kLtX8qMcqECMuKWsxDV",
      "protocols": [
        {
          "id": "0x0",
          "version": "0.0.1"
        },
        {
          "id": "0x2",
          "version": "0.0.1"
        },
        {
          "id": "0x6e",
          "version": "1"
        },
        {
          "id": "0x66",
          "version": "1"
        },
        {
          "id": "0x1",
          "version": "0.0.1"
        },
        {
          "id": "0x65",
          "version": "1"
        },
        {
          "id": "0x64",
          "version": "1"
        },
        {
          "id": "0x4",
          "version": "0.0.1"
        }
      ],
      "sync_state": {
        "best_known_header_hash": "0x2157c72b3eddd41a7a14c361173cd22ef27d7e0a29eda2e511ee0b3598c0b895",
        "best_known_header_number": "0xdb835",
        "can_fetch_count": "0x80",
        "inflight_count": "0xa",
        "last_common_header_hash": "0xc63026bd881d880bb142c855dc8153187543245f0a94391c831c75df31f263c4",
        "last_common_header_number": "0x4dc08",
        "unknown_header_list_size": "0x1f"
      },
      "version": "0.30.1 (5cc1b75 2020-03-23)"
    }
  ]
}
source

fn get_banned_addresses(&self) -> Result<Vec<BannedAddr>>

Returns all banned IPs/Subnets.

§Examples

Request

{
  "id": 42,
  "jsonrpc": "2.0",
  "method": "get_banned_addresses",
  "params": []
}

Response

{
  "id": 42,
  "jsonrpc": "2.0",
  "result": [
    {
      "address": "192.168.0.2/32",
      "ban_reason": "",
      "ban_until": "0x1ac89236180",
      "created_at": "0x16bde533338"
    }
  ]
}
source

fn clear_banned_addresses(&self) -> Result<()>

Clears all banned IPs/Subnets.

§Examples

Request

{
  "id": 42,
  "jsonrpc": "2.0",
  "method": "clear_banned_addresses",
  "params": []
}

Response

{
  "id": 42,
  "jsonrpc": "2.0",
  "result": null
}
source

fn set_ban( &self, address: String, command: String, ban_time: Option<Timestamp>, absolute: Option<bool>, reason: Option<String>, ) -> Result<()>

Inserts or deletes an IP/Subnet from the banned list

§Params
  • address - The IP/Subnet with an optional netmask (default is /32 = single IP). Examples:
    • “192.168.0.2” bans a single IP
    • “192.168.0.0/24” bans IP from “192.168.0.0” to “192.168.0.255”.
  • command - insert to insert an IP/Subnet to the list, delete to delete an IP/Subnet from the list.
  • ban_time - Time in milliseconds how long (or until when if [absolute] is set) the IP is banned, optional parameter, null means using the default time of 24h
  • absolute - If set, the ban_time must be an absolute timestamp in milliseconds since epoch, optional parameter.
  • reason - Ban reason, optional parameter.
§Errors
  • InvalidParams (-32602)
    • Expected address to be a valid IP address with an optional netmask.
    • Expected command to be in the list [insert, delete].
§Examples

Request

{
  "id": 42,
  "jsonrpc": "2.0",
  "method": "set_ban",
  "params": [
    "192.168.0.2",
    "insert",
    "0x1ac89236180",
    true,
    "set_ban example"
  ]
}

Response

{
  "id": 42,
  "jsonrpc": "2.0",
  "result": null
}
source

fn sync_state(&self) -> Result<SyncState>

Returns chain synchronization state of this node.

§Examples

Request

{
  "id": 42,
  "jsonrpc": "2.0",
  "method": "sync_state",
  "params": []
}

Response

{
  "id": 42,
  "jsonrpc": "2.0",
  "result": {
    "assume_valid_target": "0x0000000000000000000000000000000000000000000000000000000000000000",
    "assume_valid_target_reached": true,
    "best_known_block_number": "0x400",
    "best_known_block_timestamp": "0x5cd2b117",
    "fast_time": "0x3e8",
    "ibd": true,
    "inflight_blocks_count": "0x0",
    "low_time": "0x5dc",
    "min_chain_work": "0x0",
    "min_chain_work_reached": true,
    "normal_time": "0x4e2",
    "orphan_blocks_count": "0x0",
    "tip_hash": "0xa5f5c85987a15de25661e5a214f2c1449cd803f071acc7999820f25246471f40",
    "tip_number": "0x400",
    "unverified_tip_hash": "0xa5f5c85987a15de25661e5a214f2c1449cd803f071acc7999820f25246471f40",
    "unverified_tip_number": "0x400"
  }
}
source

fn set_network_active(&self, state: bool) -> Result<()>

Disable/enable all p2p network activity

§Params
  • state - true to enable networking, false to disable
§Examples

Request

{
  "id": 42,
  "jsonrpc": "2.0",
  "method": "set_network_active",
  "params": [
    false
  ]
}

Response

{
  "id": 42,
  "jsonrpc": "2.0",
  "result": null
}
source

fn add_node(&self, peer_id: String, address: String) -> Result<()>

Attempts to add a node to the peers list and try connecting to it.

§Params
  • peer_id - The node id of the node.
  • address - The address of the node.

The full P2P address is usually displayed as address/peer_id, for example in the log

2020-09-16 15:31:35.191 +08:00 NetworkRuntime INFO ckb_network::network
  Listen on address: /ip4/192.168.2.100/tcp/8114/QmUsZHPbjjzU627UZFt4k8j6ycEcNvXRnVGxCPKqwbAfQS

And in RPC local_node_info:

{
  "addresses": [
    {
      "address": "/ip4/192.168.2.100/tcp/8114/QmUsZHPbjjzU627UZFt4k8j6ycEcNvXRnVGxCPKqwbAfQS",
      "score": "0xff"
    }
  ]
}

In both of these examples,

  • peer_id is QmUsZHPbjjzU627UZFt4k8j6ycEcNvXRnVGxCPKqwbAfQS,
  • and address is /ip4/192.168.2.100/tcp/8114
§Examples

Request

{
  "id": 42,
  "jsonrpc": "2.0",
  "method": "add_node",
  "params": [
    "QmUsZHPbjjzU627UZFt4k8j6ycEcNvXRnVGxCPKqwbAfQS",
    "/ip4/192.168.2.100/tcp/8114"
  ]
}

Response

{
  "id": 42,
  "jsonrpc": "2.0",
  "result": null
}
source

fn remove_node(&self, peer_id: String) -> Result<()>

Attempts to remove a node from the peers list and try disconnecting from it.

§Params
  • peer_id - The peer id of the node.

This is the last part of a full P2P address. For example, in address “/ip4/192.168.2.100/tcp/8114/QmUsZHPbjjzU627UZFt4k8j6ycEcNvXRnVGxCPKqwbAfQS”, the peer_id is QmUsZHPbjjzU627UZFt4k8j6ycEcNvXRnVGxCPKqwbAfQS.

§Examples

Request

{
  "id": 42,
  "jsonrpc": "2.0",
  "method": "remove_node",
  "params": [
    "QmUsZHPbjjzU627UZFt4k8j6ycEcNvXRnVGxCPKqwbAfQS"
  ]
}

Response

{
  "id": 42,
  "jsonrpc": "2.0",
  "result": null
}
source

fn ping_peers(&self) -> Result<()>

Requests that a ping is sent to all connected peers, to measure ping time.

§Examples

Requests

{
  "id": 42,
  "jsonrpc": "2.0",
  "method": "ping_peers",
  "params": []
}

Response

{
  "id": 42,
  "jsonrpc": "2.0",
  "result": null
}

Implementors§