For AI agents: a documentation index is available at /llms.txt. Markdown versions of pages are available by appending .md to any documentation URL.
Skip to main content

ADMIN methods

The ADMIN API methods provide administrative functionality to manage your node.

note

The ADMIN API is not enabled by default for JSON-RPC. Enable it using the --rpc-http-api or --rpc-ws-api option.

admin_addPeer​

Adds a static node.

caution

If connections are timing out, ensure the node ID in the enode URL is correct.

Parameters​

Returns​

  • true if peer added or false if peer is already a static node.

Example​

curl -X POST http://127.0.0.1:8545/ \
  -H "Content-Type: application/json" \
  --data '{
    "jsonrpc": "2.0",
    "method": "admin_addPeer",
    "params": [
      "enode://f59c0ab603377b6ec88b89d5bb41b98fc385030ab1e4b03752db6f7dab364559d92c757c13116ae6408d2d33f0138e7812eb8b696b2a22fe3332c4b5127b22a3@127.0.0.1:30304"
    ],
    "id": 1
  }'

admin_changeLogLevel​

Changes the log level without restarting Besu. You can change the log level for all logs, or you can change the log level for specific packages or classes.

You can specify only one log level per RPC call.

Parameters​

  • level: string - Log level.

  • log_filter: array - (Optional) Packages or classes for which to change the log level.

Returns​

  • Success if the log level has changed, otherwise error.

Example​

The following example changes the debug level for specified classes to DEBUG.

curl -X POST http://127.0.0.1:8545/ \
  -H "Content-Type: application/json" \
  --data '{
    "jsonrpc": "2.0",
    "method": "admin_changeLogLevel",
    "params": [
      "DEBUG",
      [
        "org.hyperledger.besu.ethereum.eth.manager",
        "org.hyperledger.besu.ethereum.p2p.rlpx.connections.netty.ApiHandler"
      ]
    ],
    "id": 1
  }'

The following example changes the debug level of all logs to WARN.

curl -X POST http://127.0.0.1:8545/ \
  -H "Content-Type: application/json" \
  --data '{
    "jsonrpc": "2.0",
    "method": "admin_changeLogLevel",
    "params": [
      "WARN"
    ],
    "id": 1
  }'

admin_generateLogBloomCache​

Generates cached log bloom indexes for blocks. API methods such as eth_getLogs and eth_getFilterLogs use the cache for improved performance.

tip

Manually executing admin_generateLogBloomCache is not required unless the --auto-log-bloom-caching-enabled command line option is set to false.

note

Each index file contains 100000 blocks. The last fragment of blocks less than 100000 are not indexed.

Parameters​

  • startBlock: string - Block to start generating indexes.

  • endBlock: string - Block to stop generating indexes.

Returns​

  • Log bloom index details.

    • startBlock: string - Starting block for the last requested cache generation.

    • endBlock: string - Ending block for the last requested cache generation.

    • currentBlock: string - Most recent block added to the cache.

    • indexing: boolean - Indicates if indexing is in progress.

    • requestAccepted: boolean - Indicates acceptance of the request from this call to generate the cache.

Example​

curl -X POST http://127.0.0.1:8545/ \
  -H "Content-Type: application/json" \
  --data '{
    "jsonrpc": "2.0",
    "method": "admin_generateLogBloomCache",
    "params": [
      "0x0",
      "0x10000"
    ],
    "id": 1
  }'

admin_logsRemoveCache​

Removes cache files for the specified range of blocks.

Parameters​

  • fromBlock: string - Hexadecimal integer representing a block number, or one of the string tags latest, earliest, pending, finalized, or safe, as described in block parameter.

  • toBlock: string - Hexadecimal integer representing a block number, or one of the string tags latest, earliest, pending, finalized, or safe, as described in block parameter.

note

pending returns the same value as latest.

You can skip a parameter by using an empty string, "". If you specify:

  • No parameters, the call removes cache files for all blocks.
  • Only fromBlock, the call removes cache files for the specified block.
  • Only toBlock, the call removes cache files from the genesis block to the specified block.

Returns​

  • Cache Removed status or error.

Example​

curl -X POST http://127.0.0.1:8545/ \
  -H "Content-Type: application/json" \
  --data '{
    "jsonrpc": "2.0",
    "method": "admin_logsRemoveCache",
    "params": [
      "0x1",
      "0x64"
    ],
    "id": 1
  }'

admin_logsRepairCache​

Repairs cached logs by fixing all segments starting with the specified block number.

Parameters​

  • startBlock: string - Decimal index of the starting block to fix. The default is the head block.

Returns​

  • Status of the repair request; Started or Already running.

Example​

curl -X POST http://127.0.0.1:8545/ \
  -H "Content-Type: application/json" \
  --data '{
    "jsonrpc": "2.0",
    "method": "admin_logsRepairCache",
    "params": [
      "1200"
    ],
    "id": 1
  }'

admin_nodeInfo​

Returns networking information about the node. The information includes general information about the node and specific information from each running Ethereum sub-protocol (for example, eth).

Parameters​

  • None

Returns​

  • Node object.

    • id: string - Node public key.

    • name: string - Client name.

    • activeFork: string - Active EVM hard fork name for the current chain head.

    • enode: string - Enode URL of the node.

    • enr: string - ENR URL of the node.

    • ip: string - IP address.

    • ipv6: string - IPv6 address.

    • listenAddr: string - Host and port for the node.

    • listenAddrV6: string - IPv6 host and port for the node.

    • ports: object - Peer discovery and listening ports.

      • discovery: number - UDP discovery port.

      • discoveryV6: number - IPv6 UDP discovery port.

      • listener: number - TCP listening port.

      • listenerV6: number - IPv6 TCP listening port.

    • protocols: object - List of objects containing information for each Ethereum sub-protocol.


    note

    If the node is running locally, the host of the enode and listenAddr display as [::] in the result. When advertising externally, the external address displayed for the enode and listenAddr is defined by --nat-method.

Example​

curl -X POST http://127.0.0.1:8545/ \
  -H "Content-Type: application/json" \
  --data '{
    "jsonrpc": "2.0",
    "method": "admin_nodeInfo",
    "params": [],
    "id": 1
  }'

admin_peers​

Returns networking information about connected remote nodes.

Parameters​

  • None

Returns​

  • List of objects returned for each remote node.

    • version: string - P2P protocol version.

    • name: string - Client name.

    • caps: array of strings - List of Ethereum sub-protocol capabilities.

    • network: object - Local and remote addresses established at time of bonding with the peer (the remote address might not match the hex value for port; it depends on which node initiated the connection.)

    • port: string - Port on the remote node on which P2P discovery is listening.

    • id: string - Node public key (excluding the 0x prefix, the node public key is the ID in the enode URL enode://<id ex 0x>@<host>:<port>.)

    • protocols: object - Current state of peer including difficulty, head, and latestBlock (head is the hash of the highest known block for the peer; latestBlock is the corresponding block number.)

    • enode: string - Enode URL of the remote node.

Example​

curl -X POST http://127.0.0.1:8545/ \
  -H "Content-Type: application/json" \
  --data '{
    "jsonrpc": "2.0",
    "method": "admin_peers",
    "params": [],
    "id": 1
  }'

admin_removePeer​

Removes a static node.

Parameters​

  • enode: string - Enode URL of peer to remove.

Returns​

  • true if peer removed or false if peer is not a static node.

Example​

curl -X POST http://127.0.0.1:8545/ \
  -H "Content-Type: application/json" \
  --data '{
    "jsonrpc": "2.0",
    "method": "admin_removePeer",
    "params": [
      "enode://f59c0ab603377b6ec88b89d5bb41b98fc385030ab1e4b03752db6f7dab364559d92c757c13116ae6408d2d33f0138e7812eb8b696b2a22fe3332c4b5127b22a3@127.0.0.1:30304"
    ],
    "id": 1
  }'