From ab02b0ebe53a8f2cc8a7a862c66a048e46a5bfcc Mon Sep 17 00:00:00 2001 From: Sina Mahmoodi <1591639+s1na@users.noreply.github.com> Date: Tue, 12 Jul 2022 13:14:37 +0200 Subject: [PATCH] doc: add missing API methods (#25194) Co-authored-by: lightclient <14004106+lightclient@users.noreply.github.com> --- docs/_rpc/ns-admin.md | 70 ++++++++++++++++++++++++++++++++++++++++ docs/_rpc/ns-clique.md | 23 +++++++++++-- docs/_rpc/ns-debug.md | 25 ++++++++++++++ docs/_rpc/ns-miner.md | 9 ++++++ docs/_rpc/ns-net.md | 36 +++++++++++++++++++++ docs/_rpc/ns-personal.md | 62 +++++++++++++++++++++++++++++++++++ docs/_rpc/ns-txpool.md | 10 ++++++ 7 files changed, 233 insertions(+), 2 deletions(-) create mode 100644 docs/_rpc/ns-net.md diff --git a/docs/_rpc/ns-admin.md b/docs/_rpc/ns-admin.md index 58718895e2..fc15227b55 100644 --- a/docs/_rpc/ns-admin.md +++ b/docs/_rpc/ns-admin.md @@ -33,6 +33,18 @@ for tracking or some error occurred. true ``` +### admin_addTrustedPeer + +Adds the given node to a reserved trusted list which allows the +node to always connect, even if the slots are full. + +It returns a `BOOL` to indicate whether the peer was successfully added to the list. + +| Client | Method invocation | +|:--------|------------------------------------------------| +| Console | `admin.addTrustedPeer(url)` | +| RPC | `{"method": "admin_addTrustedPeer", "params": [url]}` | + ### admin_datadir The `datadir` administrative property can be queried for the absolute path the running Geth node @@ -51,6 +63,30 @@ currently uses to store all its databases. "/home/john/.ethereum" ``` +### admin_exportChain + +Exports the current blockchain into a local file. +It optionally takes a first and last block number, in which case it exports only that range of blocks. + +It returns a boolean indicating whether the operation succeeded. + +| Client | Method invocation | +|:--------|---------------------------------------------------------------------- | +| Console | `admin.exportChain(file, first, last)` | +| RPC | `{"method": "admin_exportChain", "params": [string, uint64, uint64]}` | + +### admin_importChain + +Imports an exported list of blocks from a local file. Importing involves processing the blocks and inserting them +into the canonical chain. The state from the parent block of this range is required. + +It returns a boolean indicating whether the operation succeeded. + +| Client | Method invocation | +|:--------|-------------------------------------------------------| +| Console | `admin.importChain(file)` | +| RPC | `{"method": "admin_importChain", "params": [string]}` | + ### admin_nodeInfo The `nodeInfo` administrative property can be queried for all the information known about the running @@ -90,6 +126,17 @@ overlay protocol, as well as specialized information added by each of the runnin } ``` +### admin_peerEvents + +PeerEvents creates an [RPC subscription](/docs/rpc/pubsub) which receives peer events from the node's p2p server. + +The type of events emitted by the server are as follows: + +- `add`: emitted when a peer is added +- `drop`: emitted when a peer is dropped +- `msgsend`: emitted when a message is successfully sent to a peer +- `msgrecv`: emitted when a message is received from a peer + ### admin_peers The `peers` administrative property can be queried for all the information known about the connected @@ -141,6 +188,29 @@ protocols (e.g. `eth`, `les`, `shh`, `bzz`). }] ``` +### admin_removePeer + +Disconnects from a remote node if the connection exists. + +It returns a boolean indicating validations succeeded. Note a `true` value doesn't necessarily mean +that there was a connection which was disconnected. + +| Client | Method invocation | +|:--------|----------------------------------------------------- | +| Console | `admin.removePeer(url)` | +| RPC | `{"method": "admin_removePeer", "params": [string]}` | + +### admin_removeTrustedPeer + +Removes a remote node from the trusted peer set, but it does not disconnect it automatically. + +It returns a boolean indicating validations succeeded. + +| Client | Method invocation | +|:--------|----------------------------------------------------- | +| Console | `admin.removeTrustedPeer(url)` | +| RPC | `{"method": "admin_removeTrustedPeer", "params": [string]}` | + ### admin_startHTTP The `startHTTP` administrative method starts an HTTP based JSON-RPC [API](/docs/rpc/server) diff --git a/docs/_rpc/ns-clique.md b/docs/_rpc/ns-clique.md index 474c03b6f8..ac0b09f19f 100644 --- a/docs/_rpc/ns-clique.md +++ b/docs/_rpc/ns-clique.md @@ -54,15 +54,34 @@ Retrieves the state snapshot at a given block. | Console | `clique.getSnapshotAtHash(blockHash)` | | RPC | `{"method": "clique_getSnapshotAtHash", "params": [blockHash]}` | +### clique_getSigner + +Returns the signer for a specific clique block. Can be called with either a blocknumber, blockhash or an rlp encoded blob. +The RLP encoded blob can either be a block or a header. + +| Client | Method invocation | +|:--------|------------------------------------------------------| +| Console | `clique.getSigner(blockNrOrHashOrRlp)` | +| RPC | `{"method": "clique_getSigner", "params": [string]}` | + ### clique_getSigners -Retrieves the list of authorized signers at the specified block. +Retrieves the list of authorized signers at the specified block number. | Client | Method invocation | -|:--------|------------------------------------------------------------ +|:--------|------------------------------------------------------------| | Console | `clique.getSigners(blockNumber)` | | RPC | `{"method": "clique_getSigners", "params": [blockNumber]}` | +### clique_getSignersAtHash + +Retrieves the list of authorized signers at the specified block hash. + +| Client | Method invocation | +|:--------|-------------------------------------------------------------| +| Console | `clique.getSignersAtHash(blockHash)` | +| RPC | `{"method": "clique_getSignersAtHash", "params": [string]}` | + ### clique_proposals Returns the current proposals the node is voting on. diff --git a/docs/_rpc/ns-debug.md b/docs/_rpc/ns-debug.md index eca96b4246..57640283d0 100644 --- a/docs/_rpc/ns-debug.md +++ b/docs/_rpc/ns-debug.md @@ -84,6 +84,31 @@ profile data to disk. | RPC | `{"method": "debug_cpuProfile", "params": [string, number]}` | +### debug_dbAncient + +Retrieves an ancient binary blob from the freezer. The freezer is a collection of append-only immutable files. +The first argument `kind` specifies which table to look up data from. The list of all table kinds are as follows: + +- `headers`: block headers +- `hashes`: canonical hash table (block number -> block hash) +- `bodies`: block bodies +- `receipts`: block receipts +- `diffs`: total difficulty table (block number -> td) + +| Client | Method invocation | +|:--------|-------------------------------------------------------------| +| Console | `debug.dbAncient(kind string, number uint64)` | +| RPC | `{"method": "debug_dbAncient", "params": [string, number]}` | + +### debug_dbAncients + +Returns the number of ancient items in the ancient store. + +| Client | Method invocation | +|:--------|----------------------------------| +| Console | `debug.dbAncients()` | +| RPC | `{"method": "debug_dbAncients"}` | + ### debug_dbGet Returns the raw value of a key stored in the database. diff --git a/docs/_rpc/ns-miner.md b/docs/_rpc/ns-miner.md index 176cf11b67..303f177b9d 100644 --- a/docs/_rpc/ns-miner.md +++ b/docs/_rpc/ns-miner.md @@ -40,6 +40,15 @@ below this limit are excluded from the mining process. | Console | `miner.setGasPrice(number)` | | RPC | `{"method": "miner_setGasPrice", "params": [number]}` | +### miner_setRecommitInterval + +Updates the interval for recomitting the miner sealing work. + +| Client | Method invocation | +|:--------|---------------------------------------------------------------| +| Console | `miner.setRecommitInterval(interval int)` | +| RPC | `{"method": "miner_setRecommitInterval", "params": [number]}` | + ### miner_start Start the CPU mining process with the given number of threads and generate a new DAG diff --git a/docs/_rpc/ns-net.md b/docs/_rpc/ns-net.md new file mode 100644 index 0000000000..1a92cabb9d --- /dev/null +++ b/docs/_rpc/ns-net.md @@ -0,0 +1,36 @@ +--- +title: net Namespace +sort_key: C +--- + +The `net` API provides insight about the networking aspect of the client. + +* TOC +{:toc} + +### net_listening + +Returns an indication if the node is listening for network connections. + +| Client | Method invocation | +|:--------|-------------------------------| +| Console | `net.listening` | +| RPC | `{"method": "net_listening"}` | + +### net_peerCount + +Returns the number of connected peers. + +| Client | Method invocation | +|:--------|-------------------------------| +| Console | `net.peerCount` | +| RPC | `{"method": "net_peerCount"}` | + +### net_version + +Returns the devp2p network ID (e.g. 1 for mainnet, 5 for goerli). + +| Client | Method invocation | +|:--------|-----------------------------| +| Console | `net.version` | +| RPC | `{"method": "net_version"}` | diff --git a/docs/_rpc/ns-personal.md b/docs/_rpc/ns-personal.md index 9c3c212bab..c3086ccb50 100644 --- a/docs/_rpc/ns-personal.md +++ b/docs/_rpc/ns-personal.md @@ -8,6 +8,15 @@ The personal API manages private keys in the key store. * TOC {:toc} +### personal_deriveAccount + +Requests a HD wallet to derive a new account, optionally pinning it for later reuse. + +| Client | Method invocation | +| :--------| ------------------------------------------------------------------------ | +| Console | `personal.deriveAccount(url, path, pin)` | +| RPC | `{"method": "personal_deriveAccount", "params": [string, string, bool]}` | + ### personal_importRawKey Imports the given unencrypted private key (hex string) into the key store, @@ -20,6 +29,15 @@ Returns the address of the new account. | Console | `personal.importRawKey(keydata, passphrase)` | | RPC | `{"method": "personal_importRawKey", "params": [string, string]}` | +### personal_initializeWallets + +Initializes a new wallet at the provided URL by generating and returning a new private key. + +| Client | Method invocation | +| :--------| ------------------------------------------------------------- | +| Console | `personal.initializeWallet(url)` | +| RPC | `{"method": "personal_initializeWallet", "params": [string]}` | + ### personal_listAccounts Returns all the Ethereum account addresses of all keys @@ -37,6 +55,29 @@ in the key store. ["0x5e97870f263700f46aa00d967821199b9bc5a120", "0x3d80b31a78c30fc628f20b2c89d7ddbf6e53cedc"] ``` +### personal_listWallets + +Returns a list of wallets this node manages. + +| Client | Method invocation | +| :--------| --------------------------------------------------- | +| Console | `personal.listWallets` | +| RPC | `{"method": "personal_listWallets", "params": []}` | + +#### Example + +``` javascript +> personal.listWallets +[{ + accounts: [{ + address: "0x51594065a986c58d4698c23e3d932b68a22c4d21", + url: "keystore:///var/folders/cp/k3x0xm3959qf9l0pcbbdxdt80000gn/T/go-ethereum-keystore65174700/UTC--2022-06-28T10-31-09.477982000Z--51594065a986c58d4698c23e3d932b68a22c4d21" + }], + status: "Unlocked", + url: "keystore:///var/folders/cp/k3x0xm3959qf9l0pcbbdxdt80000gn/T/go-ethereum-keystore65174700/UTC--2022-06-28T10-31-09.477982000Z--51594065a986c58d4698c23e3d932b68a22c4d21" +}] +``` + ### personal_lockAccount Removes the private key with given address from memory. @@ -77,6 +118,18 @@ The passphrase can also be supplied as a string. "0x3d80b31a78c30fc628f20b2c89d7ddbf6e53cedc" ``` +### personal_openWallet + +Initiates a hardware wallet opening procedure by establishing a USB +connection and then attempting to authenticate via the provided passphrase. Note, +the method may return an extra challenge requiring a second open (e.g. the +Trezor PIN matrix challenge). + +| Client | Method invocation | +| :--------| ----------------------------------------------------------- | +| Console | `personal.openWallet(url, passphrase)` | +| RPC | `{"method": "personal_openWallet", "params": [string, string]}` | + ### personal_unlockAccount Decrypts the key with the given address from the key store. @@ -122,6 +175,15 @@ Passphrase: true ``` +### personal_unpair + +Deletes a pairing between wallet and geth. + +| Client | Method invocation | +| :--------| ----------------------------------------------------------- | +| Console | `personal.unpair(url, pin)` | +| RPC | `{"method": "personal_unpair", "params": [string, string]}` | + ### personal_sendTransaction Validate the given passphrase and submit transaction. diff --git a/docs/_rpc/ns-txpool.md b/docs/_rpc/ns-txpool.md index 5c19fe5ae7..fc935c77a6 100644 --- a/docs/_rpc/ns-txpool.md +++ b/docs/_rpc/ns-txpool.md @@ -115,6 +115,16 @@ transactions). } ``` +### txpool_contentFrom + +Retrieves the transactions contained within the txpool, +returning pending as well as queued transactions of this address, grouped by nonce. + +| Client | Method invocation | +|:-------:|--------------------------------------------------------| +| Console | `txpool.contentFrom(address)` | +| RPC | `{"method": "txpool_contentFrom, "params": [string]"}` | + ### txpool_inspect The `inspect` inspection property can be queried to list a textual summary of all the transactions