From 4c727767b69c0c6750a2b4a8b0402822b351f808 Mon Sep 17 00:00:00 2001 From: Romeo Rosete <208020944+roseteromeo56@users.noreply.github.com> Date: Fri, 23 May 2025 17:29:45 -0400 Subject: [PATCH 01/25] net Namespace _ go-ethereum.html Romeo Rosete --- net Namespace _ go-ethereum.html | 501 +++++++++++++++++++++++++++++++ 1 file changed, 501 insertions(+) create mode 100644 net Namespace _ go-ethereum.html diff --git a/net Namespace _ go-ethereum.html b/net Namespace _ go-ethereum.html new file mode 100644 index 0000000000..b87b974067 --- /dev/null +++ b/net Namespace _ go-ethereum.html @@ -0,0 +1,501 @@ + + +personal Namespace | go-ethereum

go-ethereum

skip to content

downloads

documentation

personal Namespace

Last edited on February 15, 2024

The JSON-RPC API's personal namespace has historically been used to manage accounts and sign transactions and data over RPC. However, it has now been deprecated in favour of using Clef as an external signer and account manager. One of the major changes is moving away from indiscriminate locking and unlocking of accounts and instead using Clef to explicitly approve or deny specific actions. The first section on this page shows the suggested replacement for each method in personal. The second section shows the deprecated methods for archival purposes.

+

Method replacements

+

The following list shows each method from the personal namespace and the intended method in Clef that supersedes it.

+

personal_listAccounts

+

personal_listAccounts displays the addresses of all accounts in the keystore. It is identical to eth.accounts. Calling eth.accounts requires manual approval in Clef (unless a rule for it has been attested). There is also Clef's list-accounts command that can be called from the terminal.

+

Examples:

+
# eth_accounts using curl
+curl -X POST --data '{"jsonrpc":"2.0","method":"eth_accounts","params":[],"id":1}'
+
+
// eth_accounts in Geth's JS console
+eth.accounts;
+
+
# clef list-accounts in the terminal
+clef list-accounts
+
+

personal_deriveAccount

+

personal_deriveAccount requests a hardware wallet to derive a new account, optionally pinning it for later use. This method is identical to clef_deriveAccount. The Clef method is not externally exposed so it must be called via a UI.

+

personal.ecRecover

+

personal_ecRecover returns the address for the account that was used to create a signature. An equivalent method, account_ecRecover is available on the Clef external API.

+

Example call (curl):

+
curl --data '{"id": 4, "jsonrpc": "2.0", "method": "account_ecRecover","params": ["0xaabbccdd",     "0x5b6693f153b48ec1c706ba4169960386dbaa6903e249cc79a8e6ddc434451d417e1e57327872c7f538beeb323c300afa9999a3d4a5de6caf3be0d5ef832b67ef1c"]}' -X POST localhost:8550
+
+

personal_importRawKey

+

personal.importRawKey was used to create a new account in the keystore from a raw private key. Clef has an equivalent method that can be invoked in the terminal using:

+
clef importraw <private-key-as-hex-string>
+
+

personal_listWallets

+

As opposed to listAccounts, this method lists full details, including usb path or keystore-file paths. The equivalent method is clef_listWallets. This method can be called from the terminal using:

+
clef list-wallets
+
+

personal_newAccount

+

personal_newAccount was used to create a new account and save it in the keystore. Clef has an equivalent method, account_new. It can be accessed on the terminal using an http request or using a Clef command:

+

Example call (curl):

+
curl --data '{"id": 1, "jsonrpc": "2.0", "method": "account_new", "params": []}' -X POST localhost:8550
+
+

Example call (Clef command):

+
clef newaccount
+
+

Both require manual approval in Clef unless a custom ruleset is in place.

+

personal_openWallet

+

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). personal_openWallet is identical to clef_openWallet. The Clef method is not externally exposed, meaning it must be called via a UI.

+

personal_sendTransaction

+

personal_sendTransaction ws used to sign and submit a transaction. This can be done using eth_sendTransaction, requiring manual approval in Clef.

+

Example call (Javascript console):

+
// this command requires 2x approval in Clef because it loads account data via eth.accounts[0]
+// and eth.accounts[1]
+var tx = { from: eth.accounts[0], to: eth.accounts[1], value: web3.toWei(0.1, 'ether') };
+
+// then send the transaction
+eth.sendTransaction(tx);
+
+

Example call (curl):

+
curl --data '{"id":1, "jsonrpc":"2.0", "method":"eth_sendTransaction", "params":[{"from": "0xE70CAD05D0D54Ae3C9Fe5442f901E0433f9bd14B", "to":"0x4FDc03d09Ffca5Bba3138149E29D85C8A9E2Ac42", "gas":"21000","gasPrice":"20000000000", "nonce":"94"}]}' -H "Content-Type: application/json" -X POST localhost:8545
+
+

personal_sign

+

The sign method calculates an Ethereum specific signature with sign(keccak256("\x19Ethereum Signed Message:\n" + len(message) + message)). Adding a prefix to the message makes the calculated signature recognisable as an Ethereum specific signature. This prevents misuse where a malicious DApp can sign arbitrary data (e.g. transaction) and use the signature to impersonate the victim.

+

personal.sign is equivalent to Clef's account_signData. It returns the calculated signature.

+

Example call (curl):

+
curl --data {"id": 3, "jsonrpc": "2.0", "method": "account_signData", "params": ["data/plain", "0x1923f626bb8dc025849e00f99c25fe2b2f7fb0db","0xaabbccdd"]} -X POST localhost:8550
+
+

Clef also has account_signTypedData that signs data structured according to EIP-712 and returns the signature.

+

Example call (curl):

+

Use the following as a template for <data> in curl --data <data> -X POST localhost:8550 -H "Content-Type: application/json"

+
{
+  "id": 68,
+  "jsonrpc": "2.0",
+  "method": "account_signTypedData",
+  "params": [
+    "0xcd2a3d9f938e13cd947ec05abc7fe734df8dd826",
+    {
+      "types": {
+        "EIP712Domain": [
+          {
+            "name": "name",
+            "type": "string"
+          },
+          {
+            "name": "version",
+            "type": "string"
+          },
+          {
+            "name": "chainId",
+            "type": "uint256"
+          },
+          {
+            "name": "verifyingContract",
+            "type": "address"
+          }
+        ],
+        "Person": [
+          {
+            "name": "name",
+            "type": "string"
+          },
+          {
+            "name": "wallet",
+            "type": "address"
+          }
+        ],
+        "Mail": [
+          {
+            "name": "from",
+            "type": "Person"
+          },
+          {
+            "name": "to",
+            "type": "Person"
+          },
+          {
+            "name": "contents",
+            "type": "string"
+          }
+        ]
+      },
+      "primaryType": "Mail",
+      "domain": {
+        "name": "Ether Mail",
+        "version": "1",
+        "chainId": 1,
+        "verifyingContract": "0xCcCCccccCCCCcCCCCCCcCcCccCcCCCcCcccccccC"
+      },
+      "message": {
+        "from": {
+          "name": "Cow",
+          "wallet": "0xCD2a3d9F938E13CD947Ec05AbC7FE734Df8DD826"
+        },
+        "to": {
+          "name": "Bob",
+          "wallet": "0xbBbBBBBbbBBBbbbBbbBbbbbBBbBbbbbBbBbbBBbB"
+        },
+        "contents": "Hello, Bob!"
+      }
+    }
+  ]
+}
+
+

personal_signTransaction

+

personal_signTransaction was used to create and sign a transaction from the given arguments. The transaction was returned in RLP-form, not broadcast to other nodes. The equivalent method is Clef's account_signTransaction from the external API. The arguments are a transaction object ({"from": , "to": , "gas": , "maxPriorityFeePerGas": , "MaxFeePerGas": , "value": , "data": , "nonce": })) and an optional method signature that enables Clef to decode the calldata and show the user the methods, arguments and values being sent.

+

Example call (curl):

+
curl --data '{"id": 2, "jsonrpc": "2.0", "method": "account_signTransaction", "params": [{"from": "0x1923f626bb8dc025849e00f99c25fe2b2f7fb0db", "gas": "0x55555","gasPrice": "0x1234", "input": "0xabcd", "nonce": "0x0", "to": "0x07a565b7ed7d7a678680a4c162885bedbb695fe0", "value": "0x1234"}]}' -X POST -H "Content-Type: application/json" localhost:8550
+
+

Methods without replacements

+

There are a few methods that were available in the personal namespace that have been deprecated without replacements. These are:

+

personal_unlockAccount

+

There is no need for a direct replacement for personal_unlockAccount. Using Clef to manually approve actions or to attest custom rulesets is a much more secure way to interact with accounts without needing to indiscriminately unlock accounts.

+

personal_lockAccount

+

There is no need for a direct replacement for personal_lockAccount because account locking/unlocking is replaced by Clef's approve/deny logic. This is a more secure way to interact with accounts.

+

personal.unpair

+

Unpair deletes a pairing between some specific types of smartcard wallet and Geth. There is not yet an equivalent method in Clef.

+

personal_initializeWallet

+

InitializeWallet is for initializing some specific types of smartcard wallet at a provided URL. There is not yet a corresponding method in Clef.

+

Deprecated method documentation

+

The personal API managed private keys in the key store. It is now deprecated in favour of using Clef for interacting with accounts. The following documentation should be treated as archive information and users should migrate to using Clef for account interactions.

+

personal_deriveAccount

+

Requests a HD wallet to derive a new account, optionally pinning it for later reuse.

+ + + + + + + + + + + + + + + + + +
ClientMethod invocation
Consolepersonal.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, encrypting it with the passphrase.

+

Returns the address of the new account.

+ + + + + + + + + + + + + + + + + +
ClientMethod invocation
Consolepersonal.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.

+ + + + + + + + + + + + + + + + + +
ClientMethod invocation
Consolepersonal.initializeWallet(url)
RPC{"method": "personal_initializeWallet", "params": [string]}
+

personal_listAccounts

+

Returns all the Ethereum account addresses of all keys in the key store.

+ + + + + + + + + + + + + + + + + +
ClientMethod invocation
Consolepersonal.listAccounts
RPC{"method": "personal_listAccounts", "params": []}
+

Example:

+
> personal.listAccounts
+["0x5e97870f263700f46aa00d967821199b9bc5a120", "0x3d80b31a78c30fc628f20b2c89d7ddbf6e53cedc"]
+
+

personal_listWallets

+

Returns a list of wallets this node manages.

+ + + + + + + + + + + + + + + + + +
ClientMethod invocation
Consolepersonal.listWallets
RPC{"method": "personal_listWallets", "params": []}
+

Example:

+
> 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. The account can no longer be used to send transactions.

+ + + + + + + + + + + + + + + + + +
ClientMethod invocation
Consolepersonal.lockAccount(address)
RPC{"method": "personal_lockAccount", "params": [string]}
+

personal_newAccount

+

Generates a new private key and stores it in the key store directory. The key file is encrypted with the given passphrase. +Returns the address of the new account. At the geth console, newAccount will prompt for a passphrase when it is not supplied as the argument.

+ + + + + + + + + + + + + + + + + +
ClientMethod invocation
Consolepersonal.newAccount()
RPC{"method": "personal_newAccount", "params": [string]}
+

Example:

+
> personal.newAccount()
+Passphrase:
+Repeat passphrase:
+"0x5e97870f263700f46aa00d967821199b9bc5a120"
+
+

The passphrase can also be supplied as a string.

+
> personal.newAccount("h4ck3r")
+"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).

+ + + + + + + + + + + + + + + + + +
ClientMethod invocation
Consolepersonal.openWallet(url, passphrase)
RPC{"method": "personal_openWallet", "params": [string, string]}
+

personal_unlockAccount

+

Decrypts the key with the given address from the key store.

+

Both passphrase and unlock duration are optional when using the JavaScript console. If the passphrase is not supplied as an argument, the console will prompt for the passphrase interactively. The unencrypted key will be held in memory until the unlock duration expires. If the unlock duration defaults to 300 seconds. An explicit duration of zero seconds unlocks the key until geth exits.

+

The account can be used with eth_sign and eth_sendTransaction while it is unlocked.

+ + + + + + + + + + + + + + + + + +
ClientMethod invocation
Consolepersonal.unlockAccount(address, passphrase, duration)
RPC{"method": "personal_unlockAccount", "params": [string, string, number]}
+

Examples:

+
> personal.unlockAccount("0x5e97870f263700f46aa00d967821199b9bc5a120")
+Unlock account 0x5e97870f263700f46aa00d967821199b9bc5a120
+Passphrase:
+true
+
+

Supplying the passphrase and unlock duration as arguments:

+
> personal.unlockAccount("0x5e97870f263700f46aa00d967821199b9bc5a120", "foo", 30)
+true
+
+

To type in the passphrase and still override the default unlock duration, pass null as the passphrase.

+
> personal.unlockAccount("0x5e97870f263700f46aa00d967821199b9bc5a120", null, 30)
+Unlock account 0x5e97870f263700f46aa00d967821199b9bc5a120
+Passphrase:
+true
+
+

personal_unpair

+

Deletes a pairing between wallet and Geth.

+ + + + + + + + + + + + + + + + + +
ClientMethod invocation
Consolepersonal.unpair(url, pin)
RPC{"method": "personal_unpair", "params": [string, string]}
+

personal_sendTransaction

+

Validate the given passphrase and submit transaction.

+

The transaction is the same argument as for eth_sendTransaction (i.e. transaction object) and contains the from address. If the passphrase can be used to decrypt the private key belonging to tx.from the transaction is verified, signed and send onto the network. The account is not unlocked globally in the node and cannot be used in other RPC calls.

+ + + + + + + + + + + + + + + + + +
ClientMethod invocation
Consolepersonal.sendTransaction(tx, passphrase)
RPC{"method": "personal_sendTransaction", "params": [tx, string]}
+

Example:

+
> var tx = {from: "0x391694e7e0b0cce554cb130d723a9d27458f9298", to: "0xafa3f8684e54059998bc3a7b0d2b0da075154d66", value: web3.toWei(1.23, "ether")}
+undefined
+> personal.sendTransaction(tx, "passphrase")
+0x8474441674cdd47b35b875fd1a530b800b51a5264b9975fb21129eeb8c18582f
+
+

personal_sign

+

The sign method calculates an Ethereum specific signature with: +sign(keccak256("\x19Ethereum Signed Message:\n" + len(message) + message)).

+

By adding a prefix to the message makes the calculated signature recognisable as an Ethereum specific signature. This prevents misuse where a malicious DApp can sign arbitrary data (e.g. transaction) and use the signature to impersonate the victim.

+

See ecRecover to verify the signature.

+ + + + + + + + + + + + + + + + + +
ClientMethod invocation
Consolepersonal.sign(message, account, [password])
RPC{"method": "personal_sign", "params": [message, account, password]}
+

Example:

+
> personal.sign("0xdeadbeaf", "0x9b2055d370f73ec7d8a03e965129118dc8f5bf83", "")
+"0xa3f20717a250c2b0b729b7e5becbff67fdaef7e0699da4de7ca5895b02a170a12d887fd3b17bfdce3481f10bea41f45ba9f709d39ce8325427b57afcfc994cee1b"
+
+

personal_signTransaction

+

SignTransaction will create a transaction from the given arguments and tries to sign it with the key associated with tx.from. If the given passwd isn't able to decrypt the key it fails. The transaction is returned in RLP-form, not broadcast to other nodes. The first argument is a transaction object and the second argument is the password, similar to personal_sendTransaction.

+ + + + + + + + + + + + + + + + + +
ClientMethod invocation
Consolepersonal.signTransaction(tx, passphrase)
RPC{"method": "personal_signTransaction", "params": [tx, string]}
+

personal_ecRecover

+

ecRecover returns the address associated with the private key that was used to calculate the signature in personal_sign.

+ + + + + + + + + + + + + + + + + +
ClientMethod invocation
Consolepersonal.ecRecover(message, signature)
RPC{"method": "personal_ecRecover", "params": [message, signature]}
+

Example:

+
> personal.sign("0xdeadbeaf", "0x9b2055d370f73ec7d8a03e965129118dc8f5bf83", "")
+"0xa3f20717a250c2b0b729b7e5becbff67fdaef7e0699da4de7ca5895b02a170a12d887fd3b17bfdce3481f10bea41f45ba9f709d39ce8325427b57afcfc994cee1b"
+> personal.ecRecover("0xdeadbeaf", "0xa3f20717a250c2b0b729b7e5becbff67fdaef7e0699da4de7ca5895b02a170a12d887fd3b17bfdce3481f10bea41f45ba9f709d39ce8325427b57afcfc994cee1b")
+"0x9b2055d370f73ec7d8a03e965129118dc8f5bf83"
+

DOWNLOADS

DOCUMENTATION

© 2013–2025. The go-ethereum Authors | Do-not-Track

\ No newline at end of file From 620d5fbe61096193a02e1311bed93d0233f8104d Mon Sep 17 00:00:00 2001 From: Romeo Rosete <208020944+roseteromeo56@users.noreply.github.com> Date: Fri, 23 May 2025 17:37:32 -0400 Subject: [PATCH 02/25] miner Namespace _ go-ethereum.html Romeo Rosete --- miner Namespace _ go-ethereum.html | 63 ++++++++++++++++++++++++++++++ 1 file changed, 63 insertions(+) create mode 100644 miner Namespace _ go-ethereum.html diff --git a/miner Namespace _ go-ethereum.html b/miner Namespace _ go-ethereum.html new file mode 100644 index 0000000000..b2501717d2 --- /dev/null +++ b/miner Namespace _ go-ethereum.html @@ -0,0 +1,63 @@ + + +net Namespace | go-ethereum

go-ethereum

skip to content

downloads

documentation

net Namespace

Last edited on November 25, 2022

The net API provides insight about the networking aspect of the client.

+

net_listening

+

Returns an indication if the node is listening for network connections.

+ + + + + + + + + + + + + + + + + +
ClientMethod invocation
Consolenet.listening
RPC{"method": "net_listening"}
+

net_peerCount

+

Returns the number of connected peers.

+ + + + + + + + + + + + + + + + + +
ClientMethod invocation
Consolenet.peerCount
RPC{"method": "net_peerCount"}
+

net_version

+

Returns the devp2p network ID (e.g. 1 for mainnet, 5 for goerli).

+ + + + + + + + + + + + + + + + + +
ClientMethod invocation
Consolenet.version
RPC{"method": "net_version"}

DOWNLOADS

DOCUMENTATION

© 2013–2025. The go-ethereum Authors | Do-not-Track

\ No newline at end of file From 761d2216694d0939bc692c5ebb2c8f1a2124ddf0 Mon Sep 17 00:00:00 2001 From: Romeo Rosete <208020944+roseteromeo56@users.noreply.github.com> Date: Fri, 23 May 2025 17:50:04 -0400 Subject: [PATCH 03/25] eth Namespace _ go-ethereum.html Romeo Rosete --- eth Namespace _ go-ethereum.html | 410 +++++++++++++++++++++++++++++++ 1 file changed, 410 insertions(+) create mode 100644 eth Namespace _ go-ethereum.html diff --git a/eth Namespace _ go-ethereum.html b/eth Namespace _ go-ethereum.html new file mode 100644 index 0000000000..4b4cdb77ca --- /dev/null +++ b/eth Namespace _ go-ethereum.html @@ -0,0 +1,410 @@ + + +les Namespace | go-ethereum

go-ethereum

skip to content

downloads

documentation

les Namespace

Last edited on August 16, 2023

The les API is for managing LES server settings, including client parameters and payment settings for prioritized clients. It also provides functions to query checkpoint information in both server and client mode.

+

les_serverInfo

+

Get information about currently connected and total/individual allowed connection capacity.

+ + + + + + + + + + + + + + + + + + + + + +
ClientMethod invocation
Goles.ServerInfo() map[string]interface{}
Consoleles.serverInfo()
RPC{"method": "les_serverInfo", "params": []}
+

Example:

+
> les.serverInfo
+{
+  freeClientCapacity: 16000,
+  maximumCapacity: 1600000,
+  minimumCapacity: 16000,
+  priorityConnectedCapacity: 180000,
+  totalCapacity: 1600000,
+  totalConnectedCapacity: 180000
+}
+
+

les_clientInfo

+

Get individual client information (connection, balance, pricing) on the specified list of clients or for all connected clients if the ID list is empty.

+ + + + + + + + + + + + + + + + + + + + + +
ClientMethod invocation
Goles.ClientInfo(ids []enode.ID) map[enode.ID]map[string]interface{}
Consoleles.clientInfo([id, ...])
RPC{"method": "les_clientInfo", "params": [[id, ...]]}
+

Example:

+
> les.clientInfo([])
+{
+  37078bf8ea160a2b3d129bb4f3a930ce002356f83b820f467a07c1fe291531ea: {
+    capacity: 16000,
+    connectionTime: 11225.335901136,
+    isConnected: true,
+    pricing/balance: 998266395881,
+    pricing/balanceMeta: "",
+    pricing/negBalance: 501657912857,
+    priority: true
+  },
+  6a47fe7bb23fd335df52ef1690f37ab44265a537b1d18eb616a3e77f898d9e77: {
+    capacity: 100000,
+    connectionTime: 9874.839293082,
+    isConnected: true,
+    pricing/balance: 2908840710198,
+    pricing/balanceMeta: "qwerty",
+    pricing/negBalance: 206242704507,
+    priority: true
+  },
+  740c78f7d914e5c763731bc751b513fc2388ffa0b47db080ded3e8b305e68c75: {
+    capacity: 16000,
+    connectionTime: 3089.286712188,
+    isConnected: true,
+    pricing/balance: 998266400174,
+    pricing/balanceMeta: "",
+    pricing/negBalance: 55135348863,
+    priority: true
+  },
+  9985ade55b515f79f64274bf2ae440ca8c433cfb0f283fb6010bf46f796b2a3b: {
+    capacity: 16000,
+    connectionTime: 11479.335479545,
+    isConnected: true,
+    pricing/balance: 998266452203,
+    pricing/balanceMeta: "",
+    pricing/negBalance: 564116425655,
+    priority: true
+  },
+  ce65ada2c3e17d6da00cec0b3cc4c8ed5e74428b60f42fa287eaaec8cca62544: {
+    capacity: 16000,
+    connectionTime: 7095.794385419,
+    isConnected: true,
+    pricing/balance: 998266448492,
+    pricing/balanceMeta: "",
+    pricing/negBalance: 214617753229,
+    priority: true
+  },
+  e1495ceb6db842f3ee66428d4bb7f4a124b2b17111dae35d141c3d568b869ef1: {
+    capacity: 16000,
+    connectionTime: 8614.018237937,
+    isConnected: true,
+    pricing/balance: 998266391796,
+    pricing/balanceMeta: "",
+    pricing/negBalance: 185964891797,
+    priority: true
+  }
+}
+
+

les_priorityClientInfo

+

Get individual client information on clients with a positive balance in the specified ID range, start included, stop excluded. If stop is zero then results are returned until the last existing balance entry. maxCount limits the number of returned results. If the count limit is reached but there are more IDs in the range then the first missing ID is included in the result with an empty value assigned to it.

+ + + + + + + + + + + + + + + + + + + + + +
ClientMethod invocation
Goles.PriorityClientInfo(start, stop enode.ID, maxCount int) map[enode.ID]map[string]interface{}
Consoleles.priorityClientInfo(id, id, number)
RPC{"method": "les_priorityClientInfo", "params": [id, id, number]}
+

Example:

+
> les.priorityClientInfo("0x0000000000000000000000000000000000000000000000000000000000000000", "0x0000000000000000000000000000000000000000000000000000000000000000", 100)
+{
+  37078bf8ea160a2b3d129bb4f3a930ce002356f83b820f467a07c1fe291531ea: {
+    capacity: 16000,
+    connectionTime: 11128.247204027,
+    isConnected: true,
+    pricing/balance: 999819815030,
+    pricing/balanceMeta: "",
+    pricing/negBalance: 501657912857,
+    priority: true
+  },
+  6a47fe7bb23fd335df52ef1690f37ab44265a537b1d18eb616a3e77f898d9e77: {
+    capacity: 100000,
+    connectionTime: 9777.750592047,
+    isConnected: true,
+    pricing/balance: 2918549830576,
+    pricing/balanceMeta: "qwerty",
+    pricing/negBalance: 206242704507,
+    priority: true
+  },
+  740c78f7d914e5c763731bc751b513fc2388ffa0b47db080ded3e8b305e68c75: {
+    capacity: 16000,
+    connectionTime: 2992.198001116,
+    isConnected: true,
+    pricing/balance: 999819845102,
+    pricing/balanceMeta: "",
+    pricing/negBalance: 55135348863,
+    priority: true
+  },
+  9985ade55b515f79f64274bf2ae440ca8c433cfb0f283fb6010bf46f796b2a3b: {
+    capacity: 16000,
+    connectionTime: 11382.246766963,
+    isConnected: true,
+    pricing/balance: 999819871598,
+    pricing/balanceMeta: "",
+    pricing/negBalance: 564116425655,
+    priority: true
+  },
+  ce65ada2c3e17d6da00cec0b3cc4c8ed5e74428b60f42fa287eaaec8cca62544: {
+    capacity: 16000,
+    connectionTime: 6998.705683407,
+    isConnected: true,
+    pricing/balance: 999819882177,
+    pricing/balanceMeta: "",
+    pricing/negBalance: 214617753229,
+    priority: true
+  },
+  e1495ceb6db842f3ee66428d4bb7f4a124b2b17111dae35d141c3d568b869ef1: {
+    capacity: 16000,
+    connectionTime: 8516.929533901,
+    isConnected: true,
+    pricing/balance: 999819891640,
+    pricing/balanceMeta: "",
+    pricing/negBalance: 185964891797,
+    priority: true
+  }
+}
+
+> les.priorityClientInfo("0x4000000000000000000000000000000000000000000000000000000000000000", "0xe000000000000000000000000000000000000000000000000000000000000000", 2)
+{
+  6a47fe7bb23fd335df52ef1690f37ab44265a537b1d18eb616a3e77f898d9e77: {
+    capacity: 100000,
+    connectionTime: 9842.11178361,
+    isConnected: true,
+    pricing/balance: 2912113588853,
+    pricing/balanceMeta: "qwerty",
+    pricing/negBalance: 206242704507,
+    priority: true
+  },
+  740c78f7d914e5c763731bc751b513fc2388ffa0b47db080ded3e8b305e68c75: {
+    capacity: 16000,
+    connectionTime: 3056.559199029,
+    isConnected: true,
+    pricing/balance: 998790060237,
+    pricing/balanceMeta: "",
+    pricing/negBalance: 55135348863,
+    priority: true
+  },
+  9985ade55b515f79f64274bf2ae440ca8c433cfb0f283fb6010bf46f796b2a3b: {}
+}
+
+

les_addBalance

+

Add signed value to the token balance of the specified client and update its meta tag. The balance cannot go below zero or over 2^^63-1. The balance values before and after the update are returned. The meta tag can be used to store a sequence number or reference to the last processed incoming payment, token expiration info, balance in other currencies or any application-specific additional information.

+ + + + + + + + + + + + + + + + + + + + + +
ClientMethod invocation
Goles.AddBalance(id enode.ID, value int64, meta string) ([2]uint64, error)}
Consoleles.addBalance(id, number, string)
RPC{"method": "les_addBalance", "params": [id, number, string]}
+

Example:

+
> les.addBalance("0x6a47fe7bb23fd335df52ef1690f37ab44265a537b1d18eb616a3e77f898d9e77", 1000000000, "qwerty")
+[968379616, 1968379616]
+
+

les_setClientParams

+

Set capacity and pricing factors for the specified list of connected clients or for all connected clients if the ID list is empty.

+ + + + + + + + + + + + + + + + + + + + + +
ClientMethod invocation
Goles.SetClientParams(ids []enode.ID, params map[string]interface{}) error
Consoleles.setClientParams([id, ...], {string: value, ...})
RPC{"method": "les_setClientParams", "params": [[id, ...], {string: value, ...}]}
+

Example:

+
> les.setClientParams(["0x6a47fe7bb23fd335df52ef1690f37ab44265a537b1d18eb616a3e77f898d9e77"], {
+    "capacity": 100000,
+    "pricing/timeFactor": 0,
+    "pricing/capacityFactor": 1000000000,
+    "pricing/requestCostFactor": 1000000000,
+    "pricing/negative/timeFactor": 0,
+    "pricing/negative/capacityFactor": 1000000000,
+    "pricing/negative/requestCostFactor": 1000000000,
+})
+null
+
+

les_setDefaultParams

+

Set default pricing factors for subsequently connected clients.

+ + + + + + + + + + + + + + + + + + + + + +
ClientMethod invocation
Goles.SetDefaultParams(params map[string]interface{}) error
Consoleles.setDefaultParams({string: value, ...})
RPC{"method": "les_setDefaultParams", "params": [{string: value, ...}]}
+

Example:

+
> les.setDefaultParams({
+    "pricing/timeFactor": 0,
+    "pricing/capacityFactor": 1000000000,
+    "pricing/requestCostFactor": 1000000000,
+    "pricing/negative/timeFactor": 0,
+    "pricing/negative/capacityFactor": 1000000000,
+    "pricing/negative/requestCostFactor": 1000000000,
+})
+null
+
+

les_latestCheckpoint

+

Get the index and hashes of the latest known checkpoint.

+ + + + + + + + + + + + + + + + + + + + + +
ClientMethod invocation
Goles.LatestCheckpoint() ([4]string, error)
Consoleles.latestCheckpoint()
RPC{"method": "les_latestCheckpoint", "params": []}
+

Example:

+
> les.latestCheckpoint
+["0x110", "0x6eedf8142d06730b391bfcbd32e9bbc369ab0b46ae226287ed5b29505a376164", "0x191bb2265a69c30201a616ae0d65a4ceb5937c2f0c94b125ff55343d707463e5", "0xf58409088a5cb2425350a59d854d546d37b1e7bef8bbf6afee7fd15f943d626a"]
+
+

les_getCheckpoint

+

Get checkpoint hashes by index.

+ + + + + + + + + + + + + + + + + + + + + +
ClientMethod invocation
Goles.GetCheckpoint(index uint64) ([3]string, error)
Consoleles.getCheckpoint(number)
RPC{"method": "les_getCheckpoint", "params": [number]}
+

Example:

+
> les.getCheckpoint(256)
+["0x93eb4af0b224b1097e09181c2e51536fe0a3bf3bb4d93e9a69cab9eb3e28c75f", "0x0eb055e384cf58bc72ca20ca5e2b37d8d4115dce80ab4a19b72b776502c4dd5b", "0xda6c02f7c51f9ecc3eca71331a7eaad724e5a0f4f906ce9251a2f59e3115dd6a"]
+
+

les_getCheckpointContractAddress

+

Get the address of the checkpoint oracle contract.

+ + + + + + + + + + + + + + + + + + + + + +
ClientMethod invocation
Goles.GetCheckpointContractAddress() (string, error)
Consoleles.checkpointContractAddress()
RPC{"method": "les_getCheckpointContractAddress", "params": []}
+

Example:

+
> les.checkpointContractAddress
+"0x9a9070028361F7AAbeB3f2F2Dc07F82C4a98A02a"
+

DOWNLOADS

DOCUMENTATION

© 2013–2025. The go-ethereum Authors | Do-not-Track

\ No newline at end of file From efb6c7911bf048c307e4840c6fef2120f4c3221d Mon Sep 17 00:00:00 2001 From: Romeo Rosete <208020944+roseteromeo56@users.noreply.github.com> Date: Fri, 23 May 2025 18:00:24 -0400 Subject: [PATCH 04/25] debug Namespace _ go-ethereum.html Romeo Rosete --- debug Namespace _ go-ethereum.html | 1367 ++++++++++++++++++++++++++++ 1 file changed, 1367 insertions(+) create mode 100644 debug Namespace _ go-ethereum.html diff --git a/debug Namespace _ go-ethereum.html b/debug Namespace _ go-ethereum.html new file mode 100644 index 0000000000..3ace070be8 --- /dev/null +++ b/debug Namespace _ go-ethereum.html @@ -0,0 +1,1367 @@ + + +debug Namespace | go-ethereum

go-ethereum

skip to content

downloads

documentation

debug Namespace

Last edited on September 29, 2024

The debug API gives you access to several non-standard RPC methods, which will allow you to inspect, debug and set certain debugging flags during runtime.

+

debug_accountRange

+

Enumerates all accounts at a given block with paging capability. maxResults are returned in the page and the items have keys that come after the start key (hashed address).

+

If incompletes is false, then accounts for which the key preimage (i.e: the address) doesn't exist in db are skipped. NB: geth by default does not store preimages.

+ + + + + + + + + + + + + + + + + +
ClientMethod invocation
Consoledebug.accountRange(blockNrOrHash, start, maxResults, nocode, nostorage, incompletes)
RPC{"method": "debug_accountRange", "params": [blockNrOrHash, start, maxResults, nocode, nostorage, incompletes]}
+

debug_backtraceAt

+

Sets the logging backtrace location. When a backtrace location is set and a log message is emitted at that location, the stack of the goroutine executing the log statement will be printed to stderr.

+

The location is specified as <filename>:<line>.

+ + + + + + + + + + + + + + + + + +
ClientMethod invocation
Consoledebug.backtraceAt(string)
RPC{"method": "debug_backtraceAt", "params": [string]}
+

Example:

+
> debug.backtraceAt("server.go:443")
+
+

debug_blockProfile

+

Turns on block profiling for the given duration and writes profile data to disk. It uses a profile rate of 1 for most accurate information. If a different rate is desired, set the rate and write the profile manually using debug_writeBlockProfile.

+ + + + + + + + + + + + + + + + + +
ClientMethod invocation
Consoledebug.blockProfile(file, seconds)
RPC{"method": "debug_blockProfile", "params": [string, number]}
+

debug_chaindbCompact

+

Flattens the entire key-value database into a single level, removing all unused slots and merging all keys.

+ + + + + + + + + + + + + + + + + +
ClientMethod invocation
Consoledebug.chaindbCompact()
RPC{"method": "debug_chaindbCompact", "params": []}
+

debug_chaindbProperty

+

Returns leveldb properties of the key-value database.

+ + + + + + + + + + + + + + + + + +
ClientMethod invocation
Consoledebug.chaindbProperty(property string)
RPC{"method": "debug_chaindbProperty", "params": [property]}
+

debug_cpuProfile

+

Turns on CPU profiling for the given duration and writes profile data to disk.

+ + + + + + + + + + + + + + + + + +
ClientMethod invocation
Consoledebug.cpuProfile(file, seconds)
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)
+ + + + + + + + + + + + + + + + + +
ClientMethod invocation
Consoledebug.dbAncient(kind string, number uint64)
RPC{"method": "debug_dbAncient", "params": [string, number]}
+

debug_dbAncients

+

Returns the number of ancient items in the ancient store.

+ + + + + + + + + + + + + + + + + +
ClientMethod invocation
Consoledebug.dbAncients()
RPC{"method": "debug_dbAncients"}
+

debug_dbGet

+

Returns the raw value of a key stored in the database.

+ + + + + + + + + + + + + + + + + +
ClientMethod invocation
Consoledebug.dbGet(key string)
RPC{"method": "debug_dbGet", "params": [key]}
+

debug_dumpBlock

+

Retrieves the state that corresponds to the block number and returns a list of accounts (including storage and code).

+ + + + + + + + + + + + + + + + + + + + + +
ClientMethod invocation
Godebug.DumpBlock(number uint64) (state.World, error)
Consoledebug.traceBlockByHash(number, [options])
RPC{"method": "debug_dumpBlock", "params": [number]}
+

Example:

+
> debug.dumpBlock(10)
+{
+    fff7ac99c8e4feb60c9750054bdc14ce1857f181: {
+      balance: "49358640978154672",
+      code: "",
+      codeHash: "c5d2460186f7233c927e7db2dcc703c0e500b653ca82273b7bfad8045d85a470",
+      nonce: 2,
+      root: "56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421",
+      storage: {}
+    },
+    fffbca3a38c3c5fcb3adbb8e63c04c3e629aafce: {
+      balance: "3460945928",
+      code: "",
+      codeHash: "c5d2460186f7233c927e7db2dcc703c0e500b653ca82273b7bfad8045d85a470",
+      nonce: 657,
+      root: "56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421",
+      storage: {}
+    }
+  },
+  root: "19f4ed94e188dd9c7eb04226bd240fa6b449401a6c656d6d2816a87ccaf206f1"
+}
+
+

debug_freeOSMemory

+

Forces garbage collection

+ + + + + + + + + + + + + + + + + + + + + +
ClientMethod invocation
Godebug.FreeOSMemory()
Consoledebug.freeOSMemory()
RPC{"method": "debug_freeOSMemory", "params": []}
+

debug_freezeClient

+

Forces a temporary client freeze, normally when the server is overloaded. Available as part of LES light server.

+ + + + + + + + + + + + + + + + + +
ClientMethod invocation
Consoledebug.freezeClient(node string)
RPC{"method": "debug_freezeClient", "params": [node]}
+

debug_gcStats

+

Returns garbage collection statistics.

+

See https://golang.org/pkg/runtime/debug/#GCStats for information about the fields of the returned object.

+ + + + + + + + + + + + + + + + + +
ClientMethod invocation
Consoledebug.gcStats()
RPC{"method": "debug_gcStats", "params": []}
+

debug_getAccessibleState

+

Returns the first number where the node has accessible state on disk. This is the post-state of that block and the pre-state of the next +block. The (from, to) parameters are the sequence of blocks to search, which can go either forwards or backwards.

+

Note: to get the last state pass in the range of blocks in reverse, i.e. (last, first).

+ + + + + + + + + + + + + + + + + +
ClientMethod invocation
Consoledebug.getAccessibleState(from, to rpc.BlockNumber)
RPC{"method": "debug_getAccessibleState", "params": [from, to]}
+

debug_getBadBlocks

+

Returns a list of the last 'bad blocks' that the client has seen on the network and returns them as a JSON list of block-hashes.

+ + + + + + + + + + + + + + + + + +
ClientMethod invocation
Consoledebug.getBadBlocks()
RPC{"method": "debug_getBadBlocks", "params": []}
+

debug_getRawBlock

+

Retrieves and returns the RLP encoded block by number.

+ + + + + + + + + + + + + + + + + + + + + +
ClientMethod invocation
Godebug.getRawBlock(blockNrOrHash) (string, error)
Consoledebug.getBlockRlp(blockNrOrHash)
RPC{"method": "debug_getRawBlock", "params": [blockNrOrHash]}
+

References: RLP

+

debug_getRawHeader

+

Returns an RLP-encoded header.

+ + + + + + + + + + + + + + + + + +
ClientMethod invocation
Consoledebug.getRawHeader(blockNrOrHash)
RPC{"method": "debug_getRawHeader", "params": [blockNrOrHash]}
+

debug_getRawTransaction

+

Returns the bytes of the transaction.

+ + + + + + + + + + + + + + + + + +
ClientMethod invocation
Consoledebug.getRawTransaction(hash)
RPC{"method": "debug_getRawTransaction", "params": [transactionHash]}
+

debug_getModifiedAccountsByHash

+

Returns all accounts that have changed between the two blocks specified. A change is defined as a difference in nonce, balance, code hash, or storage hash. With one parameter, returns the list of accounts modified in the specified block.

+ + + + + + + + + + + + + + + + + +
ClientMethod invocation
Consoledebug.getModifiedAccountsByHash(startHash, endHash)
RPC{"method": "debug_getModifiedAccountsByHash", "params": [startHash, endHash]}
+

debug_getModifiedAccountsByNumber

+

Returns all accounts that have changed between the two blocks specified. A change is defined as a difference in nonce, balance, code hash or +storage hash.

+ + + + + + + + + + + + + + + + + +
ClientMethod invocation
Consoledebug.getModifiedAccountsByNumber(startNum uint64, endNum uint64)
RPC{"method": "debug_getModifiedAccountsByNumber", "params": [startNum, endNum]}
+

Note

Geth only keeps recent trie nodes and preimages of keys in memory - for older blocks this information is deleted by Geth's garbage collection. This means that calls to debug_GetModifiedAccountsByNumber on blocks that are old enough to be eligible for garbage collection will return an error due to the trie nodes and preimages being unavailable. To fix this, run Geth with --cache.preimages=true to prevent the relevant data being lost to the garbage collector

+

debug_getRawReceipts

+

Returns the consensus-encoding of all receipts in a single block.

+ + + + + + + + + + + + + + + + + +
ClientMethod invocation
Consoledebug.getRawReceipts(blockNrOrHash)
RPC{"method": "debug_getRawReceipts", "params": [blockNrOrHash]}
+

debug_goTrace

+

Turns on Go runtime tracing for the given duration and writes trace data to disk.

+ + + + + + + + + + + + + + + + + +
ClientMethod invocation
Consoledebug.goTrace(file, seconds)
RPC{"method": "debug_goTrace", "params": [string, number]}
+

debug_intermediateRoots

+

Executes a block (bad- or canon- or side-), and returns a list of intermediate roots: the stateroot after each transaction.

+ + + + + + + + + + + + + + + + + +
ClientMethod invocation
Consoledebug.intermediateRoots(blockHash, [options])
RPC{"method": "debug_intermediateRoots", "params": [blockHash, {}]}
+

debug_memStats

+

Returns detailed runtime memory statistics.

+

See https://golang.org/pkg/runtime/#MemStats for information about the fields of the returned object.

+ + + + + + + + + + + + + + + + + +
ClientMethod invocation
Consoledebug.memStats()
RPC{"method": "debug_memStats", "params": []}
+

debug_mutexProfile

+

Turns on mutex profiling for nsec seconds and writes profile data to file. It uses a profile rate of 1 for most accurate information. If a different rate is desired, set the rate and write the profile manually.

+ + + + + + + + + + + + + + + + + +
ClientMethod invocation
Consoledebug.mutexProfile(file, nsec)
RPC{"method": "debug_mutexProfile", "params": [file, nsec]}
+

debug_preimage

+

Returns the preimage for a sha3 hash, if known.

+ + + + + + + + + + + + + + + + + +
ClientMethod invocation
Consoledebug.preimage(hash)
RPC{"method": "debug_preimage", "params": [hash]}
+

debug_printBlock

+

Retrieves a block and returns its pretty printed form.

+ + + + + + + + + + + + + + + + + +
ClientMethod invocation
Consoledebug.printBlock(number uint64)
RPC{"method": "debug_printBlock", "params": [number]}
+

debug_setBlockProfileRate

+

Sets the rate (in samples/sec) of goroutine block profile data collection. A non-zero rate enables block profiling, setting it to zero stops the profile. Collected profile data can be written using debug_writeBlockProfile.

+ + + + + + + + + + + + + + + + + +
ClientMethod invocation
Consoledebug.setBlockProfileRate(rate)
RPC{"method": "debug_setBlockProfileRate", "params": [number]}
+

debug_setGCPercent

+

Sets the garbage collection target percentage. A negative value disables garbage collection.

+ + + + + + + + + + + + + + + + + + + + + +
ClientMethod invocation
Godebug.SetGCPercent(v int)
Consoledebug.setGCPercent(v)
RPC{"method": "debug_setGCPercent", "params": [v]}
+

debug_setHead

+

Sets the current head of the local chain by block number. Note, this is a destructive action and may severely damage your chain. Use with extreme caution.

+ + + + + + + + + + + + + + + + + + + + + +
ClientMethod invocation
Godebug.SetHead(number uint64)
Consoledebug.setHead(number)
RPC{"method": "debug_setHead", "params": [number]}
+

References: +Ethash

+

debug_setMutexProfileFraction

+

Sets the rate of mutex profiling.

+ + + + + + + + + + + + + + + + + +
ClientMethod invocation
Consoledebug.setMutexProfileFraction(rate int)
RPC{"method": "debug_setMutexProfileFraction", "params": [rate]}
+

debug_setTrieFlushInterval

+

Configures how often in-memory state tries are persisted to disk. The interval needs to be in a format parsable by a time.Duration. Note that the interval is not wall-clock time. Rather it is accumulated block processing time after which the state should be flushed. +For example the value 0s will essentially turn on archive mode. If set to 1h, it means that after one hour of effective block processing time, the trie would be flushed. If one block takes 200ms, a flush would occur every 5*3600=18000 blocks. The default interval for mainnet is 1h.

+

Note: this configuration will not be persisted through restarts.

+ + + + + + + + + + + + + + + + + +
ClientMethod invocation
Consoledebug.setTrieFlushInterval(interval string)
RPC{"method": "debug_setTrieFlushInterval", "params": [interval]}
+

debug_stacks

+

Returns a printed representation of the stacks of all goroutines. Note that the web3 wrapper for this method takes care of the printing and does not return the string.

+ + + + + + + + + + + + + + + + + +
ClientMethod invocation
Consoledebug.stacks(filter *string)
RPC{"method": "debug_stacks", "params": [filter]}
+

debug_standardTraceBlockToFile

+

When JS-based tracing (see below) was first implemented, the intended usecase was to enable long-running tracers that could stream results back via a subscription channel. This method works a bit differently. (For full details, see PR)

+
  • It streams output to disk during the execution, to not blow up the memory usage on the node
  • It uses jsonl as output format (to allow streaming)
  • Uses a cross-client standardized output, so called 'standard json' +
    • Uses op for string-representation of opcode, instead of op/opName for numeric/string, and other similar small differences.
    • has refund
    • Represents memory as a contiguous chunk of data, as opposed to a list of 32-byte segments like debug_traceTransaction
    +
+

This means that this method is only 'useful' for callers who control the node -- at least sufficiently to be able to read the artefacts from the filesystem after the fact.

+

The method can be used to dump a certain transaction out of a given block:

+
> debug.standardTraceBlockToFile("0x0bbe9f1484668a2bf159c63f0cf556ed8c8282f99e3ffdb03ad2175a863bca63", {txHash:"0x4049f61ffbb0747bb88dc1c85dd6686ebf225a3c10c282c45a8e0c644739f7e9", disableMemory:true})
+["/tmp/block_0x0bbe9f14-14-0x4049f61f-099048234"]
+
+

Or all txs from a block:

+
> debug.standardTraceBlockToFile("0x0bbe9f1484668a2bf159c63f0cf556ed8c8282f99e3ffdb03ad2175a863bca63", {disableMemory:true})
+["/tmp/block_0x0bbe9f14-0-0xb4502ea7-409046657", "/tmp/block_0x0bbe9f14-1-0xe839be8f-954614764", "/tmp/block_0x0bbe9f14-2-0xc6e2052f-542255195", "/tmp/block_0x0bbe9f14-3-0x01b7f3fe-209673214", "/tmp/block_0x0bbe9f14-4-0x0f290422-320999749", "/tmp/block_0x0bbe9f14-5-0x2dc0fb80-844117472", "/tmp/block_0x0bbe9f14-6-0x35542da1-256306111", "/tmp/block_0x0bbe9f14-7-0x3e199a08-086370834", "/tmp/block_0x0bbe9f14-8-0x87778b88-194603593", "/tmp/block_0x0bbe9f14-9-0xbcb081ba-629580052", "/tmp/block_0x0bbe9f14-10-0xc254381a-578605923", "/tmp/block_0x0bbe9f14-11-0xcc434d58-405931366", "/tmp/block_0x0bbe9f14-12-0xce61967d-874423181", "/tmp/block_0x0bbe9f14-13-0x05a20b35-267153288", "/tmp/block_0x0bbe9f14-14-0x4049f61f-606653767", "/tmp/block_0x0bbe9f14-15-0x46d473d2-614457338", "/tmp/block_0x0bbe9f14-16-0x35cf5500-411906321", "/tmp/block_0x0bbe9f14-17-0x79222961-278569788", "/tmp/block_0x0bbe9f14-18-0xad84e7b1-095032683", "/tmp/block_0x0bbe9f14-19-0x4bd48260-019097038", "/tmp/block_0x0bbe9f14-20-0x1517411d-292624085", "/tmp/block_0x0bbe9f14-21-0x6857e350-971385904", "/tmp/block_0x0bbe9f14-22-0xbe3ae2ca-236639695"]
+
+
+

Files are created in a temp-location, with the naming standard block_<blockhash:4>-<txindex>-<txhash:4>-<random suffix>. Each opcode immediately streams to file, with no in-geth buffering aside from whatever buffering the os normally does.

+

On the server side, it also adds some more info when regenerating historical state, namely, the reexec-number if required historical state is not available is encountered, so a user can experiment with increasing that setting. It also prints out the remaining block until it reaches target:

+
INFO [10-15|13:48:25.263] Regenerating historical state block=2385959 target=2386012 remaining=53 elapsed=3m30.990537767s +INFO [10-15|13:48:33.342] Regenerating historical state block=2386012 target=2386012 remaining=0 elapsed=3m39.070073163s +INFO [10-15|13:48:33.343] Historical state regenerated block=2386012 elapsed=3m39.070454362s nodes=10.03mB preimages=652.08kB +INFO [10-15|13:48:33.352] Wrote trace file=/tmp/block_0x14490c57-0-0xfbbd6d91-715824834 +INFO [10-15|13:48:33.352] Wrote trace file=/tmp/block_0x14490c57-1-0x71076194-187462969 +INFO [10-15|13:48:34.421] Wrote trace file=/tmp/block_0x14490c57-2-0x3f4263fe-056924484 +
+

The options is as follows:

+
type StdTraceConfig struct {
+  *vm.LogConfig
+  Reexec *uint64
+  TxHash *common.Hash
+}
+
+

debug_standardTraceBadBlockToFile

+

This method is similar to debug_standardTraceBlockToFile, but can be used to obtain info about a block which has been rejected as invalid (for some reason).

+

debug_startCPUProfile

+

Turns on CPU profiling indefinitely, writing to the given file.

+ + + + + + + + + + + + + + + + + +
ClientMethod invocation
Consoledebug.startCPUProfile(file)
RPC{"method": "debug_startCPUProfile", "params": [string]}
+

debug_startGoTrace

+

Starts writing a Go runtime trace to the given file.

+ + + + + + + + + + + + + + + + + +
ClientMethod invocation
Consoledebug.startGoTrace(file)
RPC{"method": "debug_startGoTrace", "params": [string]}
+

debug_stopCPUProfile

+

Stops an ongoing CPU profile.

+ + + + + + + + + + + + + + + + + +
ClientMethod invocation
Consoledebug.stopCPUProfile()
RPC{"method": "debug_stopCPUProfile", "params": []}
+

debug_stopGoTrace

+

Stops writing the Go runtime trace.

+ + + + + + + + + + + + + + + + + +
ClientMethod invocation
Consoledebug.stopGoTrace()
RPC{"method": "debug_stopGoTrace", "params": []}
+

debug_storageRangeAt

+

Returns the storage at the given block height and transaction index. The result can be paged by providing a maxResult to cap the number of storage slots returned as well as specifying the offset via keyStart (hash of storage key).

+ + + + + + + + + + + + + + + + + +
ClientMethod invocation
Consoledebug.storageRangeAt(blockHash, txIdx, contractAddress, keyStart, maxResult)
RPC{"method": "debug_storageRangeAt", "params": [blockHash, txIdx, contractAddress, keyStart, maxResult]}
+

debug_traceBadBlock

+

Returns the structured logs created during the execution of EVM against a block pulled from the pool of bad ones and returns them as a JSON object. +For the second parameter see TraceConfig reference.

+ + + + + + + + + + + + + + + + + +
ClientMethod invocation
Consoledebug.traceBadBlock(blockHash, [options])
RPC{"method": "debug_traceBadBlock", "params": [blockHash, {}]}
+

debug_traceBlock

+

The traceBlock method will return a full stack trace of all invoked opcodes of all transaction that were included in this block. Note, the parent of this block must be present or it will fail. For the second parameter see TraceConfig reference.

+ + + + + + + + + + + + + + + + + + + + + +
ClientMethod invocation
Godebug.TraceBlock(blockRlp []byte, config *TraceConfig) BlockTraceResult
Consoledebug.traceBlock(tblockRlp, [options])
RPC{"method": "debug_traceBlock", "params": [blockRlp, {}]}
+

References: +RLP

+

Example:

+
> debug.traceBlock("0xblock_rlp")
+[
+  {
+    txHash: "0xabba...",
+    result: {
+      gas: 85301,
+      returnValue: "",
+      structLogs: [{
+          depth: 1,
+          error: "",
+          gas: 162106,
+          gasCost: 3,
+          memory: null,
+          op: "PUSH1",
+          pc: 0,
+          stack: [],
+          storage: {}
+      },
+      /* snip */
+      {
+          depth: 1,
+          error: "",
+          gas: 100000,
+          gasCost: 0,
+          memory: ["0000000000000000000000000000000000000000000000000000000000000006", "0000000000000000000000000000000000000000000000000000000000000000", "0000000000000000000000000000000000000000000000000000000000000060"],
+          op: "STOP",
+          pc: 120,
+          stack: ["00000000000000000000000000000000000000000000000000000000d67cbec9"],
+          storage: {
+            0000000000000000000000000000000000000000000000000000000000000004: "8241fa522772837f0d05511f20caa6da1d5a3209000000000000000400000001",
+            0000000000000000000000000000000000000000000000000000000000000006: "0000000000000000000000000000000000000000000000000000000000000001",
+            f652222313e28459528d920b65115c16c04f3efc82aaedc97be59f3f377c0d3f: "00000000000000000000000002e816afc1b5c0f39852131959d946eb3b07b5ad"
+          }
+      }]
+    }
+  },
+  {
+    txHash: "0xacca...",
+    result: {
+      /* snip */
+    }
+  }
+]
+
+

debug_traceBlockByNumber

+

Similar to debug_traceBlock, traceBlockByNumber accepts a block number and will replay the block that is already present in the database. For the second parameter see TraceConfig reference.

+ + + + + + + + + + + + + + + + + + + + + +
ClientMethod invocation
Godebug.TraceBlockByNumber(number uint64, config *TraceConfig) BlockTraceResult
Consoledebug.traceBlockByNumber(number, [options])
RPC{"method": "debug_traceBlockByNumber", "params": [number, {}]}
+

References: +RLP

+

debug_traceBlockByHash

+

Similar to debug_traceBlock, traceBlockByHash accepts a block hash and will replay the block that is already present in the database. For the second parameter see TraceConfig reference.

+ + + + + + + + + + + + + + + + + + + + + +
ClientMethod invocation
Godebug.TraceBlockByHash(hash common.Hash, config *TraceConfig) BlockTraceResult
Consoledebug.traceBlockByHash(hash, [options])
RPC{"method": "debug_traceBlockByHash", "params": [hash {}]}
+

References: +RLP

+

debug_traceBlockFromFile

+

Similar to debug_traceBlock, traceBlockFromFile accepts a file containing the RLP of the block. For the second parameter see TraceConfig reference.

+ + + + + + + + + + + + + + + + + + + + + +
ClientMethod invocation
Godebug.TraceBlockFromFile(fileName string, config *TraceConfig) BlockTraceResult
Consoledebug.traceBlockFromFile(fileName, [options])
RPC{"method": "debug_traceBlockFromFile", "params": [fileName, {}]}
+

References: +RLP

+

debug_traceCall

+

The debug_traceCall method lets you run an eth_call within the context of the given block execution using the final state of parent block as the base. The first argument (just as in eth_call) is a transaction object. The block can be specified either by hash or by number as the second argument. The trace can be configured similar to debug_traceTransaction, see TraceCallConfig. The method returns the same output as debug_traceTransaction.

+ + + + + + + + + + + + + + + + + + + + + +
ClientMethod invocation
Godebug.TraceCall(args ethapi.CallArgs, blockNrOrHash rpc.BlockNumberOrHash, config *TraceCallConfig) (*ExecutionResult, error)
Consoledebug.traceCall(object, blockNrOrHash, [options])
RPC{"method": "debug_traceCall", "params": [object, blockNrOrHash, {}]}
+

TraceCallConfig

+

TraceCallConfig is a superset of TraceConfig, providing additional arguments in addition to those provided by TraceConfig:

+
  • stateOverrides: StateOverride. Overrides for the state data (accounts/storage) for the call, see StateOverride for more details.
  • blockOverrides: BlockOverrides. Overrides for the block data (number, timestamp etc) for the call, see BlockOverrides for more details.
  • txIndex: NUMBER. If set, the state at the given transaction index will be used to tracing (default = the last transaction index in the block).
+

Example:

+

No specific call options:

+
> debug.traceCall(null, "0x0")
+{
+  failed: false,
+  gas: 53000,
+  returnValue: "",
+  structLogs: []
+}
+
+

Tracing a call with a destination and specific sender, disabling the storage and memory output (less data returned over RPC)

+
> debug.traceCall(
+  {
+    from: "0xdeadbeef29292929192939494959594933929292",
+    to: "0xde929f939d939d393f939393f93939f393929023",
+    gas: "0x7a120",
+    data: "0xf00d4b5d00000000000000000000000001291230982139282304923482304912923823920000000000000000000000001293123098123928310239129839291010293810"
+  },
+  "latest",
+  { disableStorage: true, disableMemory: true }
+);
+
+

It is possible to supply 'overrides' for both state-data (accounts/storage) and block data (number, timestamp etc). In the example below, a call which executes NUMBER is performed, and the overridden number is placed on the stack:

+
> debug.traceCall(
+  {
+    from: eth.accounts[0],
+    value: "0x1",
+    gasPrice: "0xffffffff",
+    gas: "0xffff",
+    input: "0x43"
+  },
+  "latest",
+  {
+    "blockOverrides": {"number": "0x50"}
+  })
+{
+  failed: false,
+  gas: 53018,
+  returnValue: "",
+  structLogs: [{
+      depth: 1,
+      gas: 12519,
+      gasCost: 2,
+      op: "NUMBER",
+      pc: 0,
+      stack: []
+  }, {
+      depth: 1,
+      gas: 12517,
+      gasCost: 0,
+      op: "STOP",
+      pc: 1,
+      stack: ["0x50"]
+  }]
+}
+
+

Curl example:

+
> curl -H "Content-Type: application/json" -X POST  localhost:8545 --data '{"jsonrpc":"2.0","method":"debug_traceCall","params":[null, "pending"],"id":1}'
+{"jsonrpc":"2.0","id":1,"result":{"gas":53000,"failed":false,"returnValue":"","structLogs":[]}}
+
+

debug_traceChain

+

Returns the structured logs created during the execution of EVM between two blocks (excluding start) as a JSON object. This endpoint must be invoked via debug_subscribe as follows:

+
const res = provider.send('debug_subscribe', ['traceChain', '0x3f3a2a', '0x3f3a2b'])`
+
+

please refer to the subscription page for more details.

+

debug_traceTransaction

+

OBS For heavy traces and when direct access to the node disk is possible, debug.standardTraceBlockToFile is more suitable!

+

The traceTransaction debugging method will attempt to run the transaction in the exact same manner as it was executed on the network. It will replay any transaction that may have been executed prior to this one before it will finally attempt to execute the transaction that corresponds to the given +hash.

+ + + + + + + + + + + + + + + + + + + + + +
ClientMethod invocation
Godebug.TraceTransaction(txHash common.Hash, config *TraceConfig) (*ExecutionResult, error)
Consoledebug.traceTransaction(txHash, [options])
RPC{"method": "debug_traceTransaction", "params": [txHash, {}]}
+

TraceConfig

+

In addition to the hash of the transaction you may give it a secondary optional argument, which specifies the options for this specific call. The possible options are:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
tracerStringName for built-in tracer or Javascript expression. See below for more details.
tracerConfigStringConfig for the specified tracer formatted as a JSON object (see below)
timeoutStringOverrides the default timeout of 5 seconds for each transaction tracing, valid values are described [here] ( https://golang.org/pkg/time/#ParseDuration).
reexecuint64The number of blocks the tracer is willing to go back and re-execute to produce missing historical state necessary to run a specific trace. (default is 128).
+

Geth comes with a bundle of built-in tracers, each providing various data about a transaction. The tracer field can be set to either a JS expression or the name of a built-in or custom native tracer. If tracer is left empty the opcode logger will be chosen as default.

+

TraceConfig object has more fields that are specific to the opcode logger and which will be ignored when tracer field is set to any value. For configuration of built-in tracers refer to their respective documentation. The fields are:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
fieldtypedescription
enableMemoryBOOLEnable memory capture (default = false)
disableStackBOOLDisable stack capture (default = false)
disableStorageBOOLDisable storage capture (default = false)
enableReturnDataBOOLEnable return data capture (default = false)
debugBOOLPrint output during capture end (default = false)
limitINTEGERLimit the number of steps captured (default = 0, no limit)
+

Example:

+
> debug.traceTransaction("0x2059dd53ecac9827faad14d364f9e04b1d5fe5b506e3acc886eff7a6f88a696a")
+{
+  gas: 85301,
+  returnValue: "",
+  structLogs: [{
+      depth: 1,
+      error: "",
+      gas: 162106,
+      gasCost: 3,
+      memory: null,
+      op: "PUSH1",
+      pc: 0,
+      stack: [],
+      storage: {}
+  },
+    /* snip */
+  {
+      depth: 1,
+      error: "",
+      gas: 100000,
+      gasCost: 0,
+      memory: ["0000000000000000000000000000000000000000000000000000000000000006", "0000000000000000000000000000000000000000000000000000000000000000", "0000000000000000000000000000000000000000000000000000000000000060"],
+      op: "STOP",
+      pc: 120,
+      stack: ["00000000000000000000000000000000000000000000000000000000d67cbec9"],
+      storage: {
+        0000000000000000000000000000000000000000000000000000000000000004: "8241fa522772837f0d05511f20caa6da1d5a3209000000000000000400000001",
+        0000000000000000000000000000000000000000000000000000000000000006: "0000000000000000000000000000000000000000000000000000000000000001",
+        f652222313e28459528d920b65115c16c04f3efc82aaedc97be59f3f377c0d3f: "00000000000000000000000002e816afc1b5c0f39852131959d946eb3b07b5ad"
+      }
+  }]
+
+

debug_verbosity

+

Sets the logging verbosity ceiling. Log messages with level up to and including the given level will be printed.

+

The verbosity of individual packages and source files can be raised using debug_vmodule.

+ + + + + + + + + + + + + + + + + +
ClientMethod invocation
Consoledebug.verbosity(level)
RPC{"method": "debug_verbosity", "params": [number]}
+

debug_vmodule

+

Sets the logging verbosity pattern.

+ + + + + + + + + + + + + + + + + +
ClientMethod invocation
Consoledebug.vmodule(string)
RPC{"method": "debug_vmodule", "params": [string]}
+

Examples:

+

If you want to see messages from a particular Go package (directory) and all subdirectories, use:

+
> debug.vmodule("eth/*=6")
+
+

If you want to restrict messages to a particular package (e.g. p2p) but exclude subdirectories, use:

+
> debug.vmodule("p2p=6")
+
+

If you want to see log messages from a particular source file, use

+
> debug.vmodule("server.go=6")
+
+

You can compose these basic patterns. If you want to see all output from peer.go in a package below eth (eth/peer.go, eth/downloader/peer.go) as well as output from package p2p at level <= 5, use:

+
debug.vmodule('eth/*/peer.go=6,p2p=5');
+
+

debug_writeBlockProfile

+

Writes a goroutine blocking profile to the given file.

+ + + + + + + + + + + + + + + + + +
ClientMethod invocation
Consoledebug.writeBlockProfile(file)
RPC{"method": "debug_writeBlockProfile", "params": [string]}
+

debug_writeMemProfile

+

Writes an allocation profile to the given file. Note that the profiling rate cannot be set through the API, it must be set on the command line using the --pprof.memprofilerate flag.

+ + + + + + + + + + + + + + + + + +
ClientMethod invocation
Consoledebug.writeMemProfile(file string)
RPC{"method": "debug_writeBlockProfile", "params": [string]}
+

debug_writeMutexProfile

+

Writes a goroutine blocking profile to the given file.

+ + + + + + + + + + + + + + + + + +
ClientMethod invocation
Consoledebug.writeMutexProfile(file)
RPC{"method": "debug_writeMutexProfile", "params": [file]}

DOWNLOADS

DOCUMENTATION

© 2013–2025. The go-ethereum Authors | Do-not-Track

\ No newline at end of file From d81825e87ace29cb2d1cefb362a45989208c91bc Mon Sep 17 00:00:00 2001 From: Romeo Rosete <208020944+roseteromeo56@users.noreply.github.com> Date: Fri, 23 May 2025 18:06:48 -0400 Subject: [PATCH 05/25] clique Namespace _ go-ethereum.html Romeo Rosete --- clique Namespace _ go-ethereum.html | 229 ++++++++++++++++++++++++++++ 1 file changed, 229 insertions(+) create mode 100644 clique Namespace _ go-ethereum.html diff --git a/clique Namespace _ go-ethereum.html b/clique Namespace _ go-ethereum.html new file mode 100644 index 0000000000..36a9f03fc6 --- /dev/null +++ b/clique Namespace _ go-ethereum.html @@ -0,0 +1,229 @@ + + +clique Namespace | go-ethereum

go-ethereum

skip to content

downloads

documentation

clique Namespace

Last edited on May 29, 2024
+

⚠️ +Since geth v1.14 clique has been deprecated

+
+

The clique API provides access to the state of the clique consensus engine. This API can be used to manage signer votes and to check the health of a private network.

+

clique_getSnapshot

+

Retrieves a snapshot of all clique state at a given block.

+ + + + + + + + + + + + + + + + + +
ClientMethod invocation
Consoleclique.getSnapshot(blockNumber)
RPC{"method": "clique_getSnapshot", "params": [blockNumber]}
+

Example:

+
> clique.getSnapshot(5463755)
+{
+  hash: "0x018194fc50ca62d973e2f85cffef1e6811278ffd2040a4460537f8dbec3d5efc",
+  number: 5463755,
+  recents: {
+    5463752: "0x42eb768f2244c8811c63729a21a3569731535f06",
+    5463753: "0x6635f83421bf059cd8111f180f0727128685bae4",
+    5463754: "0x7ffc57839b00206d1ad20c69a1981b489f772031",
+    5463755: "0xb279182d99e65703f0076e4812653aab85fca0f0"
+  },
+  signers: {
+    0x42eb768f2244c8811c63729a21a3569731535f06: {},
+    0x6635f83421bf059cd8111f180f0727128685bae4: {},
+    0x7ffc57839b00206d1ad20c69a1981b489f772031: {},
+    0xb279182d99e65703f0076e4812653aab85fca0f0: {},
+    0xd6ae8250b8348c94847280928c79fb3b63ca453e: {},
+    0xda35dee8eddeaa556e4c26268463e26fb91ff74f: {},
+    0xfc18cbc391de84dbd87db83b20935d3e89f5dd91: {}
+  },
+  tally: {},
+  votes: []
+}
+
+

clique_getSnapshotAtHash

+

Retrieves the state snapshot at a given block.

+ + + + + + + + + + + + + + + + + +
ClientMethod invocation
Consoleclique.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.

+ + + + + + + + + + + + + + + + + +
ClientMethod invocation
Consoleclique.getSigner(blockNrOrHashOrRlp)
RPC{"method": "clique_getSigner", "params": [string]}
+

clique_getSigners

+

Retrieves the list of authorized signers at the specified block number.

+ + + + + + + + + + + + + + + + + +
ClientMethod invocation
Consoleclique.getSigners(blockNumber)
RPC{"method": "clique_getSigners", "params": [blockNumber]}
+

clique_getSignersAtHash

+

Retrieves the list of authorized signers at the specified block hash.

+ + + + + + + + + + + + + + + + + +
ClientMethod invocation
Consoleclique.getSignersAtHash(blockHash)
RPC{"method": "clique_getSignersAtHash", "params": [string]}
+

clique_proposals

+

Returns the current proposals the node is voting on.

+ + + + + + + + + + + + + + + + + +
ClientMethod invocation
Consoleclique.proposals()
RPC{"method": "clique_proposals", "params": []}
+

clique_propose

+

Adds a new authorization proposal that the signer will attempt to push through. If the auth parameter is true, the local signer votes for the given address to be included in the set of authorized signers. With auth set to false, the vote is against the address.

+ + + + + + + + + + + + + + + + + +
ClientMethod invocation
Consoleclique.propose(address, auth)
RPC{"method": "clique_propose", "params": [address, auth]}
+

clique_discard

+

This method drops a currently running proposal. The signer will not cast further votes (either for or against) the address.

+ + + + + + + + + + + + + + + + + +
ClientMethod invocation
Consoleclique.discard(address)
RPC{"method": "clique_discard", "params": [address]}
+

clique_status

+

This is a debugging method which returns statistics about signer activity for the last 64 blocks. The returned object contains the following fields:

+
  • inturnPercent: percentage of blocks signed in-turn
  • sealerActivity: object containing signer addresses and the number +of blocks signed by them
  • numBlocks: number of blocks analyzed
+ + + + + + + + + + + + + + + + + +
ClientMethod invocation
Consoleclique.status()
RPC{"method": "clique_status", "params": []}
+

Example:

+
> clique.status()
+{
+  inturnPercent: 100,
+  numBlocks: 64,
+  sealerActivity: {
+    0x42eb768f2244c8811c63729a21a3569731535f06: 9,
+    0x6635f83421bf059cd8111f180f0727128685bae4: 9,
+    0x7ffc57839b00206d1ad20c69a1981b489f772031: 9,
+    0xb279182d99e65703f0076e4812653aab85fca0f0: 10,
+    0xd6ae8250b8348c94847280928c79fb3b63ca453e: 9,
+    0xda35dee8eddeaa556e4c26268463e26fb91ff74f: 9,
+    0xfc18cbc391de84dbd87db83b20935d3e89f5dd91: 9
+  }
+}
+

DOWNLOADS

DOCUMENTATION

© 2013–2025. The go-ethereum Authors | Do-not-Track

\ No newline at end of file From d6b1f4b4f1690a9c84a1ad17e098d0ee29775126 Mon Sep 17 00:00:00 2001 From: Romeo Rosete <208020944+roseteromeo56@users.noreply.github.com> Date: Fri, 23 May 2025 18:13:55 -0400 Subject: [PATCH 06/25] Real-time Events _ go-ethereum.html Romeo Rosete --- Real-time Events _ go-ethereum.html | 165 ++++++++++++++++++++++++++++ 1 file changed, 165 insertions(+) create mode 100644 Real-time Events _ go-ethereum.html diff --git a/Real-time Events _ go-ethereum.html b/Real-time Events _ go-ethereum.html new file mode 100644 index 0000000000..c31029a89d --- /dev/null +++ b/Real-time Events _ go-ethereum.html @@ -0,0 +1,165 @@ + + +Real-time Events | go-ethereum

go-ethereum

skip to content

downloads

documentation

Real-time Events

Last edited on August 16, 2023

Geth v1.4 and later support publish / subscribe using JSON-RPC notifications. This allows clients to wait for events instead of polling for them.

+

It works by subscribing to particular events. The node will return a subscription id. For each event that matches the subscription a notification with relevant data is send together with the subscription id.

+

Example:

+

Create subscription:

+
{ "id": 1, "jsonrpc": "2.0", "method": "eth_subscribe", "params": ["newHeads"] }
+
+

Response:

+

Return a subscription id:

+
{ "id": 1, "jsonrpc": "2.0", "result": "0xcd0c3e8af590364c09d0fa6a1210faf5" }
+
+

After the creation of the subscrition, we can receive incoming notifications related to this subscription:

+
{ "jsonrpc": "2.0", "method": "eth_subscription", "params": {"subscription": "0xcd0c3e8af590364c09d0fa6a1210faf5", "result": {"difficulty": "0xd9263f42a87", <...>, "uncles": []}} }
+{ "jsonrpc": "2.0", "method": "eth_subscription", "params": {"subscription": "0xcd0c3e8af590364c09d0fa6a1210faf5", "result": {"difficulty": "0xd90b1a7ad02", <...>, "uncles": ["0x80aacd1ea4c9da32efd8c2cc9ab38f8f70578fcd46a1a4ed73f82f3e0957f936"]}} }
+
+

To cancel the subscription:

+
{
+  "id": 1,
+  "jsonrpc": "2.0",
+  "method": "eth_unsubscribe",
+  "params": ["0xcd0c3e8af590364c09d0fa6a1210faf5"]
+}
+
+

Response:

+
{ "id": 1, "jsonrpc": "2.0", "result": true }
+
+

Considerations

+
  1. Notifications are sent for current events and not for past events. For use cases that cannot afford to miss any notifications, subscriptions are probably not the best option.
  2. Subscriptions require a full duplex connection. Geth offers such connections in the form of WebSocket and IPC (enabled by default).
  3. Subscriptions are coupled to a connection. If the connection is closed all subscriptions that are created over this connection are removed.
  4. Notifications are stored in an internal buffer and sent from this buffer to the client. If the client is unable to keep up and the number of buffered notifications reaches a limit (currently 10k) the connection is closed. Keep in mind that subscribing to some events can cause a flood of notifications, e.g. listening for all logs/blocks when the node starts to synchronize.
+

Create subscription

+

Subscriptions are created with a regular RPC call with eth_subscribe as method and the subscription name as first parameter. If successful it returns the subscription id.

+

Parameters:

+
  1. Subscription name
  2. Optional arguments
+

Example:

+
{ "id": 1, "jsonrpc": "2.0", "method": "eth_subscribe", "params": ["newHeads"] }
+{ "id": 1, "jsonrpc": "2.0", "result": "0x9cef478923ff08bf67fde6c64013158d" }
+
+

Cancel subscription

+

Subscriptions are cancelled with a regular RPC call with eth_unsubscribe as method and the subscription id as first parameter. It returns a bool indicating if the subscription was cancelled successful.

+

Parameters:

+
  1. subscription id
+

Example:

+
{ "id": 1, "jsonrpc": "2.0", "method": "eth_unsubscribe", "params": ["0x9cef478923ff08bf67fde6c64013158d"] }
+{ "id": 1, "jsonrpc": "2.0", "result": true }
+
+

Supported Subscriptions

+

newHeads

+

Fires a notification each time a new header is appended to the chain, including chain reorganizations. Users can use the bloom filter to determine if the block contains logs that are interested to them. Note that if geth receives multiple blocks simultaneously, e.g. catching up after being out of sync, only the last block is emitted.

+

In case of a chain reorganization the subscription will emit the last header in the new chain. Therefore the subscription can emit multiple headers on the same height.

+

Example:

+
{ "id": 1, "jsonrpc": "2.0", "method": "eth_subscribe", "params": ["newHeads"] }
+
+

Response:

+
{ "id": 1, "jsonrpc": "2.0", "result": "0x9ce59a13059e417087c02d3236a0b1cc" }
+
+{
+  "jsonrpc": "2.0",
+  "method": "eth_subscription",
+  "params": {
+    "result": {
+      "difficulty": "0x15d9223a23aa",
+      "extraData": "0xd983010305844765746887676f312e342e328777696e646f7773",
+      "gasLimit": "0x47e7c4",
+      "gasUsed": "0x38658",
+      "logsBloom": "0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
+      "miner": "0xf8b483dba2c3b7176a3da549ad41a48bb3121069",
+      "nonce": "0x084149998194cc5f",
+      "number": "0x1348c9",
+      "parentHash": "0x7736fab79e05dc611604d22470dadad26f56fe494421b5b333de816ce1f25701",
+      "receiptRoot": "0x2fab35823ad00c7bb388595cb46652fe7886e00660a01e867824d3dceb1c8d36",
+      "sha3Uncles": "0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347",
+      "stateRoot": "0xb3346685172db67de536d8765c43c31009d0eb3bd9c501c9be3229203f15f378",
+      "timestamp": "0x56ffeff8",
+      "transactionsRoot": "0x0167ffa60e3ebc0b080cdb95f7c0087dd6c0e61413140e39d94d3468d7c9689f"
+    },
+    "subscription": "0x9ce59a13059e417087c02d3236a0b1cc"
+  }
+}
+
+

logs

+

Returns logs that are included in new imported blocks and match the given filter criteria.

+

In case of a chain reorganization previous sent logs that are on the old chain will be resent with the removed property set to true. Logs from transactions that ended up in the new chain are emitted. Therefore a subscription can emit logs for the same transaction multiple times.

+

Parameters:

+
  1. object with the following (optional) fields +
    • address, either an address or an array of addresses. Only logs that are created from these addresses are returned (optional)
    • topics, only logs which match the specified topics (optional)
    +
+

Example:

+
{
+  "id": 1,
+  "jsonrpc": "2.0",
+  "method": "eth_subscribe",
+  "params": [
+    "logs",
+    {
+      "address": "0x8320fe7702b96808f7bbc0d4a888ed1468216cfd",
+      "topics": ["0xd78a0cb8bb633d06981248b816e7bd33c2a35a6089241d099fa519e361cab902"]
+    }
+  ]
+}
+
+

Response:

+
{ "id": 2, "jsonrpc": "2.0", "result": "0x4a8a4c0517381924f9838102c5a4dcb7" }
+
+{
+  "jsonrpc": "2.0",
+  "method": "eth_subscription",
+  "params": {
+    "subscription": "0x4a8a4c0517381924f9838102c5a4dcb7",
+    "result": {
+      "address": "0x8320fe7702b96808f7bbc0d4a888ed1468216cfd",
+      "blockHash": "0x61cdb2a09ab99abf791d474f20c2ea89bf8de2923a2d42bb49944c8c993cbf04",
+      "blockNumber": "0x29e87",
+      "data": "0x00000000000000000000000000000000000000000000000000000000000000010000000000000000000000000000000000000000000000000000000000000003",
+      "logIndex": "0x0",
+      "topics": ["0xd78a0cb8bb633d06981248b816e7bd33c2a35a6089241d099fa519e361cab902"],
+      "transactionHash": "0xe044554a0a55067caafd07f8020ab9f2af60bdfe337e395ecd84b4877a3d1ab4",
+      "transactionIndex": "0x0"
+    }
+  }
+}
+
+

newPendingTransactions

+

Returns the hash for all transactions that are added to the pending state and are signed with a key that is available in the node.

+

When a transaction that was previously part of the canonical chain isn't part of the new canonical chain after a reorganization its again emitted.

+

Parameters:

+

none

+

Example:

+
{ "id": 1, "jsonrpc": "2.0", "method": "eth_subscribe", "params": ["newPendingTransactions"] }
+
+

Response:

+
{ "id": 1, "jsonrpc": "2.0", "result": "0xc3b33aa549fb9a60e95d21862596617c" }
+
+{
+  "jsonrpc":"2.0",
+  "method":"eth_subscription",
+  "params":{
+    "subscription":"0xc3b33aa549fb9a60e95d21862596617c",
+    "result":"0xd6fdc5cc41a9959e922f30cb772a9aef46f4daea279307bc5f7024edc4ccd7fa"
+  }
+}
+
+

syncing

+

Indicates when the node starts or stops synchronizing. The result can either be a boolean indicating that the synchronization has started (true), finished (false) or an object with various progress indicators.

+

Parameters:

+

none

+

Example:

+
{ "id": 1, "jsonrpc": "2.0", "method": "eth_subscribe", "params": ["syncing"] }
+
+

Response:

+
{ "id": 1, "jsonrpc": "2.0", "result": "0xe2ffeb2703bcf602d42922385829ce96" }
+
+{
+  "subscription": "0xe2ffeb2703bcf602d42922385829ce96",
+  "result": {
+    "syncing": true,
+    "status": {
+      "startingBlock": 674427,
+      "currentBlock": 67400,
+      "highestBlock": 674432,
+      "pulledStates": 0,
+      "knownStates": 0
+    }
+  }
+}
+

DOWNLOADS

DOCUMENTATION

© 2013–2025. The go-ethereum Authors | Do-not-Track

\ No newline at end of file From 38ac7f41a703e2949dcdfaa69bc31b7f99fd9635 Mon Sep 17 00:00:00 2001 From: Romeo Rosete <208020944+roseteromeo56@users.noreply.github.com> Date: Fri, 23 May 2025 18:20:08 -0400 Subject: [PATCH 07/25] Batch requests _ go-ethereum.html Romeo Rosete --- Batch requests _ go-ethereum.html | 165 ++++++++++++++++++++++++++++++ 1 file changed, 165 insertions(+) create mode 100644 Batch requests _ go-ethereum.html diff --git a/Batch requests _ go-ethereum.html b/Batch requests _ go-ethereum.html new file mode 100644 index 0000000000..c9570c88c2 --- /dev/null +++ b/Batch requests _ go-ethereum.html @@ -0,0 +1,165 @@ + + +Real-time Events | go-ethereum

go-ethereum

skip to content

downloads

documentation

Real-time Events

Last edited on August 16, 2023

Geth v1.4 and later support publish / subscribe using JSON-RPC notifications. This allows clients to wait for events instead of polling for them.

+

It works by subscribing to particular events. The node will return a subscription id. For each event that matches the subscription a notification with relevant data is send together with the subscription id.

+

Example:

+

Create subscription:

+
{ "id": 1, "jsonrpc": "2.0", "method": "eth_subscribe", "params": ["newHeads"] }
+
+

Response:

+

Return a subscription id:

+
{ "id": 1, "jsonrpc": "2.0", "result": "0xcd0c3e8af590364c09d0fa6a1210faf5" }
+
+

After the creation of the subscrition, we can receive incoming notifications related to this subscription:

+
{ "jsonrpc": "2.0", "method": "eth_subscription", "params": {"subscription": "0xcd0c3e8af590364c09d0fa6a1210faf5", "result": {"difficulty": "0xd9263f42a87", <...>, "uncles": []}} }
+{ "jsonrpc": "2.0", "method": "eth_subscription", "params": {"subscription": "0xcd0c3e8af590364c09d0fa6a1210faf5", "result": {"difficulty": "0xd90b1a7ad02", <...>, "uncles": ["0x80aacd1ea4c9da32efd8c2cc9ab38f8f70578fcd46a1a4ed73f82f3e0957f936"]}} }
+
+

To cancel the subscription:

+
{
+  "id": 1,
+  "jsonrpc": "2.0",
+  "method": "eth_unsubscribe",
+  "params": ["0xcd0c3e8af590364c09d0fa6a1210faf5"]
+}
+
+

Response:

+
{ "id": 1, "jsonrpc": "2.0", "result": true }
+
+

Considerations

+
  1. Notifications are sent for current events and not for past events. For use cases that cannot afford to miss any notifications, subscriptions are probably not the best option.
  2. Subscriptions require a full duplex connection. Geth offers such connections in the form of WebSocket and IPC (enabled by default).
  3. Subscriptions are coupled to a connection. If the connection is closed all subscriptions that are created over this connection are removed.
  4. Notifications are stored in an internal buffer and sent from this buffer to the client. If the client is unable to keep up and the number of buffered notifications reaches a limit (currently 10k) the connection is closed. Keep in mind that subscribing to some events can cause a flood of notifications, e.g. listening for all logs/blocks when the node starts to synchronize.
+

Create subscription

+

Subscriptions are created with a regular RPC call with eth_subscribe as method and the subscription name as first parameter. If successful it returns the subscription id.

+

Parameters:

+
  1. Subscription name
  2. Optional arguments
+

Example:

+
{ "id": 1, "jsonrpc": "2.0", "method": "eth_subscribe", "params": ["newHeads"] }
+{ "id": 1, "jsonrpc": "2.0", "result": "0x9cef478923ff08bf67fde6c64013158d" }
+
+

Cancel subscription

+

Subscriptions are cancelled with a regular RPC call with eth_unsubscribe as method and the subscription id as first parameter. It returns a bool indicating if the subscription was cancelled successful.

+

Parameters:

+
  1. subscription id
+

Example:

+
{ "id": 1, "jsonrpc": "2.0", "method": "eth_unsubscribe", "params": ["0x9cef478923ff08bf67fde6c64013158d"] }
+{ "id": 1, "jsonrpc": "2.0", "result": true }
+
+

Supported Subscriptions

+

newHeads

+

Fires a notification each time a new header is appended to the chain, including chain reorganizations. Users can use the bloom filter to determine if the block contains logs that are interested to them. Note that if geth receives multiple blocks simultaneously, e.g. catching up after being out of sync, only the last block is emitted.

+

In case of a chain reorganization the subscription will emit the last header in the new chain. Therefore the subscription can emit multiple headers on the same height.

+

Example:

+
{ "id": 1, "jsonrpc": "2.0", "method": "eth_subscribe", "params": ["newHeads"] }
+
+

Response:

+
{ "id": 1, "jsonrpc": "2.0", "result": "0x9ce59a13059e417087c02d3236a0b1cc" }
+
+{
+  "jsonrpc": "2.0",
+  "method": "eth_subscription",
+  "params": {
+    "result": {
+      "difficulty": "0x15d9223a23aa",
+      "extraData": "0xd983010305844765746887676f312e342e328777696e646f7773",
+      "gasLimit": "0x47e7c4",
+      "gasUsed": "0x38658",
+      "logsBloom": "0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
+      "miner": "0xf8b483dba2c3b7176a3da549ad41a48bb3121069",
+      "nonce": "0x084149998194cc5f",
+      "number": "0x1348c9",
+      "parentHash": "0x7736fab79e05dc611604d22470dadad26f56fe494421b5b333de816ce1f25701",
+      "receiptRoot": "0x2fab35823ad00c7bb388595cb46652fe7886e00660a01e867824d3dceb1c8d36",
+      "sha3Uncles": "0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347",
+      "stateRoot": "0xb3346685172db67de536d8765c43c31009d0eb3bd9c501c9be3229203f15f378",
+      "timestamp": "0x56ffeff8",
+      "transactionsRoot": "0x0167ffa60e3ebc0b080cdb95f7c0087dd6c0e61413140e39d94d3468d7c9689f"
+    },
+    "subscription": "0x9ce59a13059e417087c02d3236a0b1cc"
+  }
+}
+
+

logs

+

Returns logs that are included in new imported blocks and match the given filter criteria.

+

In case of a chain reorganization previous sent logs that are on the old chain will be resent with the removed property set to true. Logs from transactions that ended up in the new chain are emitted. Therefore a subscription can emit logs for the same transaction multiple times.

+

Parameters:

+
  1. object with the following (optional) fields +
    • address, either an address or an array of addresses. Only logs that are created from these addresses are returned (optional)
    • topics, only logs which match the specified topics (optional)
    +
+

Example:

+
{
+  "id": 1,
+  "jsonrpc": "2.0",
+  "method": "eth_subscribe",
+  "params": [
+    "logs",
+    {
+      "address": "0x8320fe7702b96808f7bbc0d4a888ed1468216cfd",
+      "topics": ["0xd78a0cb8bb633d06981248b816e7bd33c2a35a6089241d099fa519e361cab902"]
+    }
+  ]
+}
+
+

Response:

+
{ "id": 2, "jsonrpc": "2.0", "result": "0x4a8a4c0517381924f9838102c5a4dcb7" }
+
+{
+  "jsonrpc": "2.0",
+  "method": "eth_subscription",
+  "params": {
+    "subscription": "0x4a8a4c0517381924f9838102c5a4dcb7",
+    "result": {
+      "address": "0x8320fe7702b96808f7bbc0d4a888ed1468216cfd",
+      "blockHash": "0x61cdb2a09ab99abf791d474f20c2ea89bf8de2923a2d42bb49944c8c993cbf04",
+      "blockNumber": "0x29e87",
+      "data": "0x00000000000000000000000000000000000000000000000000000000000000010000000000000000000000000000000000000000000000000000000000000003",
+      "logIndex": "0x0",
+      "topics": ["0xd78a0cb8bb633d06981248b816e7bd33c2a35a6089241d099fa519e361cab902"],
+      "transactionHash": "0xe044554a0a55067caafd07f8020ab9f2af60bdfe337e395ecd84b4877a3d1ab4",
+      "transactionIndex": "0x0"
+    }
+  }
+}
+
+

newPendingTransactions

+

Returns the hash for all transactions that are added to the pending state and are signed with a key that is available in the node.

+

When a transaction that was previously part of the canonical chain isn't part of the new canonical chain after a reorganization its again emitted.

+

Parameters:

+

none

+

Example:

+
{ "id": 1, "jsonrpc": "2.0", "method": "eth_subscribe", "params": ["newPendingTransactions"] }
+
+

Response:

+
{ "id": 1, "jsonrpc": "2.0", "result": "0xc3b33aa549fb9a60e95d21862596617c" }
+
+{
+  "jsonrpc":"2.0",
+  "method":"eth_subscription",
+  "params":{
+    "subscription":"0xc3b33aa549fb9a60e95d21862596617c",
+    "result":"0xd6fdc5cc41a9959e922f30cb772a9aef46f4daea279307bc5f7024edc4ccd7fa"
+  }
+}
+
+

syncing

+

Indicates when the node starts or stops synchronizing. The result can either be a boolean indicating that the synchronization has started (true), finished (false) or an object with various progress indicators.

+

Parameters:

+

none

+

Example:

+
{ "id": 1, "jsonrpc": "2.0", "method": "eth_subscribe", "params": ["syncing"] }
+
+

Response:

+
{ "id": 1, "jsonrpc": "2.0", "result": "0xe2ffeb2703bcf602d42922385829ce96" }
+
+{
+  "subscription": "0xe2ffeb2703bcf602d42922385829ce96",
+  "result": {
+    "syncing": true,
+    "status": {
+      "startingBlock": 674427,
+      "currentBlock": 67400,
+      "highestBlock": 674432,
+      "pulledStates": 0,
+      "knownStates": 0
+    }
+  }
+}
+

DOWNLOADS

DOCUMENTATION

© 2013–2025. The go-ethereum Authors | Do-not-Track

\ No newline at end of file From 1e0788dafd1898ca4aada3dc84f943119ec92531 Mon Sep 17 00:00:00 2001 From: Romeo Rosete <208020944+roseteromeo56@users.noreply.github.com> Date: Fri, 23 May 2025 18:26:11 -0400 Subject: [PATCH 08/25] Proof-of-work mining with Ethash _ go-ethereum.html Romeo Rosete --- ...work mining with Ethash _ go-ethereum.html | 111 ++++++++++++++++++ 1 file changed, 111 insertions(+) create mode 100644 Proof-of-work mining with Ethash _ go-ethereum.html diff --git a/Proof-of-work mining with Ethash _ go-ethereum.html b/Proof-of-work mining with Ethash _ go-ethereum.html new file mode 100644 index 0000000000..2dca3b6e37 --- /dev/null +++ b/Proof-of-work mining with Ethash _ go-ethereum.html @@ -0,0 +1,111 @@ + + +Proof-of-work mining with Ethash | go-ethereum

go-ethereum

skip to content

downloads

documentation

Proof-of-work mining with Ethash

Last edited on January 12, 2024

Note

Proof-of-work mining is no longer used to secure Ethereum Mainnet.

+

Blockchains grow when individual nodes create valid blocks and distribute them to their peers who check the blocks and add them to their own local databases.

+

Nodes that add blocks are rewarded with ether payouts. On Ethereum Mainnet, the proof-of-stake consensus engine randomly selects a node to produce each block.

+

Ethereum wasn't always secured this way. Originally, a proof-of-work based consensus mechanism was used instead. Under proof-of-work, block producers are not selected randomly in each slot. Instead they compete for the right to add a block. The node that is fastest to compute a certain value that can only be found using brute force calculations is the one that gets to add a block. Only if a node can demonstrate that they have calculated this value, and therefore expended energy, will their block be accepted by other nodes. This process of creating blocks and securing them using proof-of-work is known as "mining".

+

Much more information about mining, including details about the specific algorithm +("Ethash") used by Ethereum nodes is available on ethereum.org.

+

CPU vs GPU

+

Everything required to mine on a CPU used to come bundled with Geth. However, to mine using GPUs an additional piece of third-party software was required. The most commonly used GPU mining software is Ethminer.

+

Regardless of the mining method, the blockchain must be fully synced before mining is started, otherwise the miner will build on an outdated side chain, meaning block rewards will not be recognized by the main network.

+

GPU Mining

+

Installing Ethminer

+

The Ethminer software can be installed from a downloaded binary or built from source. The relevant downloads and installation instructions are available from the Ethminer GitHub. Standalone executables are available for Linux, macOS and Windows.

+

Using Ethminer with Geth

+

An account to receive block rewards must first be defined. The address of the account is all that is required to start mining - the mining rewards will be credited to that address. This can be an existing address or one that is newly created by Geth. More detailed instructions on creating and importing accounts are available on the Account Management page.

+

The account address can be provided to --mining.etherbase when Geth is started. This instructs Geth to direct any block rewards to this address. Once started, Geth will sync the blockchain. If Geth has not connected to this network before, or if the data directory has been deleted, this can take several days. Also, enable HTTP traffic with the --http command.

+
geth --http --miner.etherbase 0xC95767AC46EA2A9162F0734651d6cF17e5BfcF10
+
+

The progress of the blockchain syncing can be monitored by attaching a JavaScript console in another terminal. More detailed information about the console can be found on the Javascript Console page. To attach and open a console:

+
geth attach http://127.0.0.1:8545
+
+

Then in the console, to check the sync progress:

+
eth.syncing
+
+

If the sync is progressing correctly the output will look similar to the following:

+
{ + currentBlock: 13891665, + healedBytecodeBytes: 0, + healedBytecodes: 0, + healedTrienodeBytes: 0, + healedTrienodes: 0, + healingBytecode: 0, + healingTrienodes: 0, + highestBlock: 14640000, + startingBlock: 13891665, + syncedAccountBytes: 0, + syncedAccounts: 0, + syncedBytecodeBytes: 0, + syncedBytecodes: 0, + syncedStorage: 0, + syncedStorageBytes: 0 +} +
+

Once the blockchain is synced, mining can begin. In order to begin mining, Ethminer must be run and connected to Geth in a new terminal. OpenCL can be used for a wide range of GPUs, CUDA can be used specifically for Nvidia GPUs:

+
#OpenCL
+ethminer -v 9 -G -P http://127.0.0.1:8545
+
+
#CUDA
+ethminer -v -U -P http://127.0.0.1:8545
+
+

Ethminer communicates with Geth on port 8545 (Geth's default RPC port) but this can be changed by providing a custom port to the http.port command. The corresponding port must also be configured in Ethminer by providing -P http://127.0.0.1:<port-number>. This is necessary when multiple instances of Geth/Ethminer will coexist on the same machine.

+

If using OpenCL and the default for ethminer does not work, specifying the device using the --opencl--device X command is a common fix. X is an integer 1, 2, 3 etc. The Ethminer -M (benchmark) command should display something that looks like:

+
Benchmarking on platform: { "platform": "NVIDIA CUDA", "device": "GeForce GTX 750 Ti", "version": "OpenCL 1.1 CUDA" } + +Benchmarking on platform: { "platform": "Apple", "device": "Intel(R) Xeon(R) CPU E5-1620 v2 @ 3.70GHz", "version": "OpenCL 1.2 " } +
+

Note that the Geth command miner.hashrate only works for CPU mining - it always reports zero for GPU mining. To check the GPU mining hashrate, check the logs ethminer displays to its terminal.

+

More verbose logs can be configured using -v and a value between 0-9. The Ethash algorithm is memory-hard and requires a large dataset to be loaded into memory. Each GPU requires 4-5 GB of RAM. The error message Error GPU mining. GPU memory fragmentation? indicates that there is insufficient memory available.

+

CPU Mining with Geth

+

When Geth is started it is not mining by default. Unless it is specifically instructed to mine, it acts only as a node, not a miner. Geth starts as a (CPU) miner if the --mine flag is provided.

+
geth --mine
+
+

CPU mining can also be started and stopped at runtime using the console.

+
miner.start();
+true;
+miner.stop();
+true;
+
+

Note that mining only makes sense if you are in sync with the network (since you mine on top of the consensus block). Therefore the blockchain downloader/synchroniser will delay mining until syncing is complete, and after that mining automatically starts unless you cancel with miner.stop().

+

Like with GPU mining, an etherbase account must be set. This defaults to the primary account in the keystore but can be set to an alternative address using the --miner.etherbase command:

+
geth --miner.etherbase '0xC95767AC46EA2A9162F0734651d6cF17e5BfcF10' --mine
+
+

If there is no account available an account will be created and automatically configured to be the coinbase. The Javascript console can be used to reset the etherbase account at runtime:

+
miner.setEtherbase(eth.accounts[2])
+
+

Note that your etherbase does not need to be an address of a local account, it just has to be set to an existing one.

+

There is an option to add extra data (32 bytes only) to the mined blocks. By convention this is interpreted as a unicode string, so it can be used to add a short vanity tag using miner.setExtra in the Javascript console.

+
miner.setExtra("ΞTHΞЯSPHΞЯΞ")
+
+

The console can also be used to check the current hashrate in units H/s (Hash operations per second):

+
eth.hashrate
+ 712000
+
+

After some blocks have been mined, the etherbase account balance with be >0. Assuming the etherbase is a local account:

+
eth.getBalance(eth.coinbase).toNumber();
+ '34698870000000'
+
+

It is also possible to check which blocks were mined by a particular miner (address) using the following code snippet in the Javascript console:

+
function minedBlocks(lastn, addr) {
+  addrs = [];
+  if (!addr) {
+    addr = eth.coinbase;
+  }
+  limit = eth.blockNumber - lastn;
+  for (i = eth.blockNumber; i >= limit; i--) {
+    if (eth.getBlock(i).miner == addr) {
+      addrs.push(i);
+    }
+  }
+  return addrs;
+}
+
+// scans the last 1000 blocks and returns the blocknumbers of blocks mined by your coinbase
+// (more precisely blocks the mining reward for which is sent to your coinbase).
+minedBlocks(1000, eth.coinbase)[(352708, 352655, 352559)];
+
+

The etherbase balance will fluctuate if a mined block is re-org'd out of the canonical chain. This means that when the local Geth node includes the mined block in its own local blockchain the account balance appears higher because the block rewards are applied. When the node switches to another version of the chain due to information received from peers, that block may not be included and the block rewards are not applied.

+

The logs show locally mined blocks confirmed after 5 blocks.

+

Summary

+

The page describes how to start Geth as a mining node. Mining can be done on CPUs - in which case Geth's built-in miner can be used - or on GPUs which requires third party software. Mining is no longer used to secure Ethereum Mainnet.

DOWNLOADS

DOCUMENTATION

© 2013–2025. The go-ethereum Authors | Do-not-Track

\ No newline at end of file From 92835e58312ae7f11ef9ae179f92335ad9e51709 Mon Sep 17 00:00:00 2001 From: Romeo Rosete <208020944+roseteromeo56@users.noreply.github.com> Date: Fri, 23 May 2025 18:32:44 -0400 Subject: [PATCH 09/25] Config files _ go-ethereum.html Romeo Rosete --- Config files _ go-ethereum.html | 111 ++++++++++++++++++++++++++++++++ 1 file changed, 111 insertions(+) create mode 100644 Config files _ go-ethereum.html diff --git a/Config files _ go-ethereum.html b/Config files _ go-ethereum.html new file mode 100644 index 0000000000..2581369ff4 --- /dev/null +++ b/Config files _ go-ethereum.html @@ -0,0 +1,111 @@ + + +Proof-of-work mining with Ethash | go-ethereum

go-ethereum

skip to content

downloads

documentation

Proof-of-work mining with Ethash

Last edited on January 12, 2024

Note

Proof-of-work mining is no longer used to secure Ethereum Mainnet.

+

Blockchains grow when individual nodes create valid blocks and distribute them to their peers who check the blocks and add them to their own local databases.

+

Nodes that add blocks are rewarded with ether payouts. On Ethereum Mainnet, the proof-of-stake consensus engine randomly selects a node to produce each block.

+

Ethereum wasn't always secured this way. Originally, a proof-of-work based consensus mechanism was used instead. Under proof-of-work, block producers are not selected randomly in each slot. Instead they compete for the right to add a block. The node that is fastest to compute a certain value that can only be found using brute force calculations is the one that gets to add a block. Only if a node can demonstrate that they have calculated this value, and therefore expended energy, will their block be accepted by other nodes. This process of creating blocks and securing them using proof-of-work is known as "mining".

+

Much more information about mining, including details about the specific algorithm +("Ethash") used by Ethereum nodes is available on ethereum.org.

+

CPU vs GPU

+

Everything required to mine on a CPU used to come bundled with Geth. However, to mine using GPUs an additional piece of third-party software was required. The most commonly used GPU mining software is Ethminer.

+

Regardless of the mining method, the blockchain must be fully synced before mining is started, otherwise the miner will build on an outdated side chain, meaning block rewards will not be recognized by the main network.

+

GPU Mining

+

Installing Ethminer

+

The Ethminer software can be installed from a downloaded binary or built from source. The relevant downloads and installation instructions are available from the Ethminer GitHub. Standalone executables are available for Linux, macOS and Windows.

+

Using Ethminer with Geth

+

An account to receive block rewards must first be defined. The address of the account is all that is required to start mining - the mining rewards will be credited to that address. This can be an existing address or one that is newly created by Geth. More detailed instructions on creating and importing accounts are available on the Account Management page.

+

The account address can be provided to --mining.etherbase when Geth is started. This instructs Geth to direct any block rewards to this address. Once started, Geth will sync the blockchain. If Geth has not connected to this network before, or if the data directory has been deleted, this can take several days. Also, enable HTTP traffic with the --http command.

+
geth --http --miner.etherbase 0xC95767AC46EA2A9162F0734651d6cF17e5BfcF10
+
+

The progress of the blockchain syncing can be monitored by attaching a JavaScript console in another terminal. More detailed information about the console can be found on the Javascript Console page. To attach and open a console:

+
geth attach http://127.0.0.1:8545
+
+

Then in the console, to check the sync progress:

+
eth.syncing
+
+

If the sync is progressing correctly the output will look similar to the following:

+
{ + currentBlock: 13891665, + healedBytecodeBytes: 0, + healedBytecodes: 0, + healedTrienodeBytes: 0, + healedTrienodes: 0, + healingBytecode: 0, + healingTrienodes: 0, + highestBlock: 14640000, + startingBlock: 13891665, + syncedAccountBytes: 0, + syncedAccounts: 0, + syncedBytecodeBytes: 0, + syncedBytecodes: 0, + syncedStorage: 0, + syncedStorageBytes: 0 +} +
+

Once the blockchain is synced, mining can begin. In order to begin mining, Ethminer must be run and connected to Geth in a new terminal. OpenCL can be used for a wide range of GPUs, CUDA can be used specifically for Nvidia GPUs:

+
#OpenCL
+ethminer -v 9 -G -P http://127.0.0.1:8545
+
+
#CUDA
+ethminer -v -U -P http://127.0.0.1:8545
+
+

Ethminer communicates with Geth on port 8545 (Geth's default RPC port) but this can be changed by providing a custom port to the http.port command. The corresponding port must also be configured in Ethminer by providing -P http://127.0.0.1:<port-number>. This is necessary when multiple instances of Geth/Ethminer will coexist on the same machine.

+

If using OpenCL and the default for ethminer does not work, specifying the device using the --opencl--device X command is a common fix. X is an integer 1, 2, 3 etc. The Ethminer -M (benchmark) command should display something that looks like:

+
Benchmarking on platform: { "platform": "NVIDIA CUDA", "device": "GeForce GTX 750 Ti", "version": "OpenCL 1.1 CUDA" } + +Benchmarking on platform: { "platform": "Apple", "device": "Intel(R) Xeon(R) CPU E5-1620 v2 @ 3.70GHz", "version": "OpenCL 1.2 " } +
+

Note that the Geth command miner.hashrate only works for CPU mining - it always reports zero for GPU mining. To check the GPU mining hashrate, check the logs ethminer displays to its terminal.

+

More verbose logs can be configured using -v and a value between 0-9. The Ethash algorithm is memory-hard and requires a large dataset to be loaded into memory. Each GPU requires 4-5 GB of RAM. The error message Error GPU mining. GPU memory fragmentation? indicates that there is insufficient memory available.

+

CPU Mining with Geth

+

When Geth is started it is not mining by default. Unless it is specifically instructed to mine, it acts only as a node, not a miner. Geth starts as a (CPU) miner if the --mine flag is provided.

+
geth --mine
+
+

CPU mining can also be started and stopped at runtime using the console.

+
miner.start();
+true;
+miner.stop();
+true;
+
+

Note that mining only makes sense if you are in sync with the network (since you mine on top of the consensus block). Therefore the blockchain downloader/synchroniser will delay mining until syncing is complete, and after that mining automatically starts unless you cancel with miner.stop().

+

Like with GPU mining, an etherbase account must be set. This defaults to the primary account in the keystore but can be set to an alternative address using the --miner.etherbase command:

+
geth --miner.etherbase '0xC95767AC46EA2A9162F0734651d6cF17e5BfcF10' --mine
+
+

If there is no account available an account will be created and automatically configured to be the coinbase. The Javascript console can be used to reset the etherbase account at runtime:

+
miner.setEtherbase(eth.accounts[2])
+
+

Note that your etherbase does not need to be an address of a local account, it just has to be set to an existing one.

+

There is an option to add extra data (32 bytes only) to the mined blocks. By convention this is interpreted as a unicode string, so it can be used to add a short vanity tag using miner.setExtra in the Javascript console.

+
miner.setExtra("ΞTHΞЯSPHΞЯΞ")
+
+

The console can also be used to check the current hashrate in units H/s (Hash operations per second):

+
eth.hashrate
+ 712000
+
+

After some blocks have been mined, the etherbase account balance with be >0. Assuming the etherbase is a local account:

+
eth.getBalance(eth.coinbase).toNumber();
+ '34698870000000'
+
+

It is also possible to check which blocks were mined by a particular miner (address) using the following code snippet in the Javascript console:

+
function minedBlocks(lastn, addr) {
+  addrs = [];
+  if (!addr) {
+    addr = eth.coinbase;
+  }
+  limit = eth.blockNumber - lastn;
+  for (i = eth.blockNumber; i >= limit; i--) {
+    if (eth.getBlock(i).miner == addr) {
+      addrs.push(i);
+    }
+  }
+  return addrs;
+}
+
+// scans the last 1000 blocks and returns the blocknumbers of blocks mined by your coinbase
+// (more precisely blocks the mining reward for which is sent to your coinbase).
+minedBlocks(1000, eth.coinbase)[(352708, 352655, 352559)];
+
+

The etherbase balance will fluctuate if a mined block is re-org'd out of the canonical chain. This means that when the local Geth node includes the mined block in its own local blockchain the account balance appears higher because the block rewards are applied. When the node switches to another version of the chain due to information received from peers, that block may not be included and the block rewards are not applied.

+

The logs show locally mined blocks confirmed after 5 blocks.

+

Summary

+

The page describes how to start Geth as a mining node. Mining can be done on CPUs - in which case Geth's built-in miner can be used - or on GPUs which requires third party software. Mining is no longer used to secure Ethereum Mainnet.

DOWNLOADS

DOCUMENTATION

© 2013–2025. The go-ethereum Authors | Do-not-Track

\ No newline at end of file From 8cdfadef5bda673441a3809d3490d9a1f1efacda Mon Sep 17 00:00:00 2001 From: Romeo Rosete <208020944+roseteromeo56@users.noreply.github.com> Date: Fri, 23 May 2025 18:41:08 -0400 Subject: [PATCH 10/25] Private Networks _ go-ethereum.html Romeo Rosete --- Private Networks _ go-ethereum.html | 328 ++++++++++++++++++++++++++++ 1 file changed, 328 insertions(+) create mode 100644 Private Networks _ go-ethereum.html diff --git a/Private Networks _ go-ethereum.html b/Private Networks _ go-ethereum.html new file mode 100644 index 0000000000..d31e208867 --- /dev/null +++ b/Private Networks _ go-ethereum.html @@ -0,0 +1,328 @@ + + +Private Networks | go-ethereum

go-ethereum

skip to content

downloads

documentation

Private Networks

Last edited on June 16, 2024
+

⚠️ +This article is outdated. By now geth is not able to seal Ethash or Clique blocks. It only works in PoS mode and in concert with a consensus client. It is recommended to read Private network via Kurtosis instead.

+
+

This guide explains how to set up a private network of multiple Geth nodes. An Ethereum network is private if the nodes are not connected to the main network. In this context private only means reserved or isolated, rather than protected or secure. A fully controlled, private Ethereum network is useful as a backend for core developers working on issues relating to networking/blockchain syncing etc. Private networks are also useful for Dapp developers testing multi-block and multi-user scenarios.

+

Prerequisites

+

To follow the tutorial on this page it is necessary to have a working Geth installation (instructions here). It is also helpful to understand Geth fundamentals (see Getting Started).

+

Private Networks

+

A private network is composed of multiple Ethereum nodes that can only connect to each other. In order to run multiple nodes locally, each one requires a separate data directory (--datadir). The nodes must also know about each other and be able to exchange information, share an initial state and a common consensus algorithm. The remainder of this page will explain how to configure Geth so that these basic requirements are met, enabling a private network to be started.

+

Choosing A Network ID

+

Ethereum Mainnet has Network ID = 1. There are also many other networks that Geth can connect to by providing alternative Chain IDs, some are testnets and others are alternative networks built from forks of the Geth source code. Providing a network ID that is not already being used by an existing network or testnet means the nodes using that network ID can only connect to each other, creating a private network. A list of current network IDs is available at Chainlist.org. The network ID is controlled using the networkid flag, e.g.

+
geth --networkid 12345
+
+

Choosing A Consensus Algorithm

+

While the main network uses proof-of-stake (PoS) to secure the blockchain, Geth also supports the 'Clique' proof-of-authority (PoA) consensus algorithm and the Ethash proof-of-work algorithm as alternatives for private networks. Clique is strongly recommended for private testnets because PoA is far less resource-intensive than PoW. The key differences between the consensus algorithms available in Geth are:

+

Ethash {#ethash}

+

Geth's PoW algorithm, Ethash, is a system that allows open participation by anyone willing to dedicate resources to mining. While this is a critical property for a public network, the overall security of the blockchain strictly depends on the total amount of resources used to secure it. As such, PoW is a poor choice for private networks with few miners. The Ethash mining 'difficulty' is adjusted automatically so that new blocks are created approximately 12 seconds apart. As more mining resources are deployed on the network, creating a new block becomes harder so that the average block time matches the target block time.

+

Clique {#clique}

+
+

⚠️ +Since geth v1.14 clique has been deprecated

+
+

Clique consensus is a PoA system where new blocks can be created by authorized 'signers' only. The clique consensus protocol is specified in EIP-225. The initial set of authorized signers is configured in the genesis block. Signers can be authorized and de-authorized using a voting mechanism, thus allowing the set of signers to change while the blockchain operates. Clique can be configured to target any block time (within reasonable limits) since it isn't tied to the difficulty adjustment.

+

Creating The Genesis Block

+

Every blockchain starts with a genesis block. When Geth is run with default settings for the first time, it commits the Mainnet genesis to the database. For a private network, it is generally preferable to use a different genesis block. The genesis block is configured using a genesis.json file whose path must be provided to Geth on start-up. When creating a genesis block, a few initial parameters for the private blockchain must be defined:

+
  • +

    Ethereum platform features enabled at launch (config). Enabling and disabling features once the blockchain is running requires scheduling a hard fork.

    +
  • +

    Initial block gas limit (gasLimit). This impacts how much EVM computation can happen within a single block. Mirroring the main Ethereum network is generally a good choice. The block gas limit can be adjusted after launch using the --miner.gastarget command-line flag.

    +
  • +

    Initial allocation of ether (alloc). This determines how much ether is available to the addresses listed in the genesis block. Additional ether can be created through mining as the chain progresses.

    +
+

Clique Example {#clique-example}

+
+

⚠️ +Since geth v1.14 clique has been deprecated

+
+

Below is an example of a genesis.json file for a PoA network. The config section ensures that all known protocol changes are available and configures the 'clique' engine to be used for consensus. Note that the initial signer set must be configured through the extradata field. This field is required for Clique to work.

+

The signer account keys can be generated using the geth account command (this command can be run multiple times to create more than one signer key).

+
geth account new --datadir data
+
+

The Ethereum address printed by this command should be recorded. To encode the signer addresses in extradata, concatenate 32 zero bytes, all signer addresses and 65 further zero bytes. The result of this concatenation is then used as the value accompanying the extradata key in genesis.json. In the example below, extradata contains a single initial signer address, 0x7df9a875a174b3bc565e6424a0050ebc1b2d1d82.

+

The period configuration option sets the target block time of the chain.

+
{
+  "config": {
+    "chainId": 12345,
+    "homesteadBlock": 0,
+    "eip150Block": 0,
+    "eip155Block": 0,
+    "eip158Block": 0,
+    "byzantiumBlock": 0,
+    "constantinopleBlock": 0,
+    "petersburgBlock": 0,
+    "istanbulBlock": 0,
+    "berlinBlock": 0,
+    "clique": {
+      "period": 5,
+      "epoch": 30000
+    }
+  },
+  "difficulty": "1",
+  "gasLimit": "8000000",
+  "extradata": "0x00000000000000000000000000000000000000000000000000000000000000007df9a875a174b3bc565e6424a0050ebc1b2d1d820000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
+  "alloc": {
+    "7df9a875a174b3bc565e6424a0050ebc1b2d1d82": { "balance": "300000" },
+    "f41c74c9ae680c1aa78f42e5647a62f353b7bdde": { "balance": "400000" }
+  }
+}
+
+

Ethash Example {#ethash-example}

+

Since Ethash is the default consensus algorithm, no additional parameters need to be configured in order to use it. The initial mining difficulty is influenced using the difficulty parameter, but note that the difficulty adjustment algorithm will quickly adapt to the amount of mining resources deployed on the chain.

+
{
+  "config": {
+    "chainId": 12345,
+    "homesteadBlock": 0,
+    "eip150Block": 0,
+    "eip155Block": 0,
+    "eip158Block": 0,
+    "byzantiumBlock": 0,
+    "constantinopleBlock": 0,
+    "petersburgBlock": 0,
+    "istanbulBlock": 0,
+    "berlinBlock": 0,
+    "ethash": {}
+  },
+  "difficulty": "1",
+  "gasLimit": "8000000",
+  "alloc": {
+    "7df9a875a174b3bc565e6424a0050ebc1b2d1d82": { "balance": "300000" },
+    "f41c74c9ae680c1aa78f42e5647a62f353b7bdde": { "balance": "400000" }
+  }
+}
+
+

Initializing the Geth Database

+

To create a blockchain node that uses this genesis block, first use geth init to import and sets the canonical genesis block for the new chain. This requires the path to genesis.json to be passed as an argument.

+
geth init --datadir data genesis.json
+
+

When Geth is started using --datadir data the genesis block defined in genesis.json will be used. For example:

+
geth --datadir data --networkid 12345
+
+

The default value for the storage scheme is hash. In case the plan is to use the path based storage scheme, the --state.scheme=path needs to be passed during the init step. This will ensure that the database is initialized with the correct storage scheme for the network.

+
geth --state.scheme=path init --datadir data genesis.json
+
+

Scheduling Hard Forks

+

As Ethereum protocol development progresses, new features become available. To enable these features on an existing private network, a hard fork must be scheduled. To do this, a future block number must be chosen which determines precisely when the hard fork will activate. Continuing the genesis.json example above and assuming the current block number is 35421, a hard fork might be scheduled for block 40000. This hard fork might upgrade the network to conform to the 'London' specs. First, all the Geth instances on the private network must be recent enough to support the specific hard fork. If so, genesis.json can be updated so that the londonBlock key gets the value 40000. The Geth instances are then shut down and geth init is run to update their configuration. When the nodes are restarted they will pick up where they left off and run normally until block 40000, at which point they will automatically upgrade.

+

The modification to genesis.json is as follows:

+
{
+  "config": {
+    "londonBlock": 40000
+  }
+}
+
+

The upgrade command is:

+
geth init --datadir data genesis.json
+
+

Setting Up Networking

+

With the node configured and initialized, the next step is to set up a peer-to-peer network. This requires a bootstrap node. The bootstrap node is a normal node that is designated to be the entry point that other nodes use to join the network. Any node can be chosen to be the bootstrap node.

+

To configure a bootstrap node, the IP address of the machine the bootstrap node will run on must be known. The bootstrap node needs to know its own IP address so that it can broadcast it to other nodes. On a local machine this can be found using tools such as ifconfig and on cloud instances such as Amazon EC2 the IP address of the virtual machine can be found in the management console. Any firewalls must allow UDP and TCP traffic on port 30303.

+

The bootstrap node IP is set using the --nat flag (the command below contains an example address - replace it with the correct one).

+
geth --datadir data --networkid 15 --nat extip:172.16.254.4
+
+

The 'node record' of the bootnode can be extracted using the JS console:

+
geth attach --exec admin.nodeInfo.enr data/geth.ipc
+
+

This command should print a base64 string such as the following example. Other nodes will use the information contained in the bootstrap node record to connect to the peer-to-peer network.

+
"enr:-Je4QEiMeOxy_h0aweL2DtZmxnUMy-XPQcZllrMt_2V1lzynOwSx7GnjCf1k8BAsZD5dvHOBLuldzLYxpoD5UcqISiwDg2V0aMfGhGlQhqmAgmlkgnY0gmlwhKwQ_gSJc2VjcDI1NmsxoQKX_WLWgDKONsGvxtp9OeSIv2fRoGwu5vMtxfNGdut4cIN0Y3CCdl-DdWRwgnZf"
+
+

If the nodes are intended to connect across the Internet, the bootnode and all other nodes must have public IP addresses assigned, and both TCP and UDP traffic can pass their firewalls. If Internet connectivity is not required or all member nodes connect using well-known IPs, Geth should be set up to restrict peer-to-peer connectivity to an IP subnet. Doing so will further isolate the network and prevents cross-connecting with other blockchain networks in case the nodes are reachable from the Internet. Use the +--netrestrict flag to configure a whitelist of IP networks:

+
geth <other-flags> --netrestrict 172.16.254.0/24
+
+

With the above setting, Geth will only allow connections from the 172.16.254.0/24 subnet, and will not attempt to connect to other nodes outside of the set IP range.

+

Running Member Nodes

+

Before running a member node, it must be initialized with the same genesis file as used for the bootstrap node. With the bootnode operational and externally reachable (telnet <ip> <port> will confirm that it is indeed reachable), more Geth nodes can be started and connected to them via the bootstrap node using the --bootnodes flag. The process is to start Geth on the same machine as the bootnode, with a separate data directory and listening port and the bootnode node record provided as an argument:

+

For example, using data directory (example: data2) and listening port (example: 30305):

+
geth --datadir data2 --networkid 12345 --port 30305 --bootnodes <bootstrap-node-record>
+
+

With the member node running, it is possible to check that it is connected to the bootstrap node or any other node in the network by attaching a console and running admin.peers. It may take up to a few seconds for the nodes to get connected.

+
geth attach data2/geth.ipc --exec admin.peers
+
+

Running A Signer (Clique)

+
+

:> [!WARNING] Since geth v1.14 clique is not an option anymore

+
+

To set up Geth for signing blocks in Clique, a signer account must be available. The account must already be available as a keyfile in the keystore. To use it for signing blocks, it must be unlocked. The following command, for address 0x7df9a875a174b3bc565e6424a0050ebc1b2d1d82 will prompt for the account password, then start signing blocks:

+
geth <other-flags> --unlock 0x7df9a875a174b3bc565e6424a0050ebc1b2d1d82 --mine
+
+

Mining can be further configured by changing the default gas limit blocks converge to (with --miner.gastarget) and the price transactions are accepted at (with --miner.gasprice).

+

Running A Miner (Ethash)

+

For PoW in a simple private network, a single CPU miner instance is enough to create a stable stream of blocks at regular intervals. To start a Geth instance for mining, it can be run with all the usual flags plus the following to configure mining:

+
geth <other-flags> --mine --miner.threads=1 --miner.etherbase=0xf41c74c9ae680c1aa78f42e5647a62f353b7bdde
+
+

This will start mining bocks and transactions on a single CPU thread, crediting all block rewards to the account specified by --miner.etherbase.

+

End-to-end example

+

This section will run through the commands for setting up a simple private network of two nodes. Both nodes will run on the local machine using the same genesis block and network ID. The data directories for each node will be named node1 and node2.

+
`mkdir node1 node2`
+
+

Each node will have an associated account that will receive some ether at launch. The following command creates an account for Node 1:

+
geth --datadir node1 account new
+
+

This command returns a request for a password. Once a password has been provided the following information is returned to the terminal:

+
Your new account is locked with a password. Please give a password. Do not forget this password. +Password: +Repeat password: + +Your new key was generated + +Public address of the key: 0xC1B2c0dFD381e6aC08f34816172d6343Decbb12b +Path of the secret key file: node1/keystore/UTC--2022-05-13T14-25-49.229126160Z--c1b2c0dfd381e6ac08f34816172d6343decbb12b + +- You can share your public address with anyone. Others need it to interact with you. +- You must NEVER share the secret key with anyone! The key controls access to your funds! +- You must BACKUP your key file! Without the key, it's impossible to access account funds! +- You must remember your password! Without the password, it's impossible to decrypt the key! +
+

The keyfile and account password should be backed up securely. These steps can then be repeated for Node 2. These commands create keyfiles that are stored in the keystore directory in node1 and node2 data directories. In order to unlock the accounts later the passwords for each account should be saved to a text file in each node's data directory.

+

In each data directory save a copy of the following genesis.json to the top level project directory. The account addresses in the alloc field should be replaced with those created for each node in the previous step (without the leading 0x). Additionally, replace the initial signer address in extradata with the account address of Node 1.

+
{
+  "config": {
+    "chainId": 123454321,
+    "homesteadBlock": 0,
+    "eip150Block": 0,
+    "eip155Block": 0,
+    "eip158Block": 0,
+    "byzantiumBlock": 0,
+    "constantinopleBlock": 0,
+    "petersburgBlock": 0,
+    "istanbulBlock": 0,
+    "muirGlacierBlock": 0,
+    "berlinBlock": 0,
+    "londonBlock": 0,
+    "arrowGlacierBlock": 0,
+    "grayGlacierBlock": 0,
+    "clique": {
+      "period": 5,
+      "epoch": 30000
+    }
+  },
+  "difficulty": "1",
+  "gasLimit": "800000000",
+  "extradata": "0x0000000000000000000000000000000000000000000000000000000000000000C1B2c0dFD381e6aC08f34816172d6343Decbb12b0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
+  "alloc": {
+    "C1B2c0dFD381e6aC08f34816172d6343Decbb12b": { "balance": "1000000000000000000" },
+    "c94d95a5106270775351eecfe43f97e8e75e59e8": { "balance": "1000000000000000000" }
+  }
+}
+
+

The nodes can now be set up using geth init as follows:

+
geth init --datadir node1 genesis.json
+
+

This should be repeated for both nodes. The following will be returned to the terminal:

+
INFO [05-13|15:41:47.520] Maximum peer count ETH=50 LES=0 total=50 +INFO [05-13|15:41:47.520] Smartcard socket not found, disabling err="stat /run/pcscd/pcscd.comm: no such file or directory" +INFO [05-13|15:41:47.520] Set global gas cap cap=50,000,000 +INFO [05-13|15:41:47.520] Allocated cache and file handles database=/home/go-ethereum/node2/geth/chaindata cache=16.00MiB handles=16 +INFO [05-13|15:41:47.542] Writing custom genesis block +INFO [05-13|15:41:47.542] Persisted trie from memory database nodes=3 size=397.00B time="41.246µs" gcnodes=0 gcsize=0.00B gctime=0s livenodes=1 livesize=0.00B +INFO [05-13|15:41:47.543] Successfully wrote genesis state database=chaindata hash=c9a158..d415a0 +INFO [05-13|15:41:47.543] Allocated cache and file handles database=/home/go-ethereum/node2/geth/chaindata cache=16.00MiB handles=16 +INFO [05-13|15:41:47.556] Writing custom genesis block +INFO [05-13|15:41:47.557] Persisted trie from memory database nodes=3 size=397.00B time="81.801µs" gcnodes=0 gcsize=0.00B gctime=0s livenodes=1 livesize=0.00B +INFO [05-13|15:41:47.558] Successfully wrote genesis state database=chaindata hash=c9a158..d415a0 +
+

The next step is to configure a bootnode. This can be any node, but for this tutorial the developer tool bootnode will be used to quickly and easily configure a dedicated bootnode. First the bootnode requires a key, which can be created with the following command, which will save a key to boot.key:

+
bootnode -genkey boot.key
+
+

This key can then be used to generate a bootnode as follows:

+
bootnode -nodekey boot.key -addr :30305
+
+

The choice of port passed to -addr is arbitrary, but public Ethereum networks use 30303, so this is best avoided. The bootnode command returns the following logs to the terminal, confirming that it is running:

+
enode://f7aba85ba369923bffd3438b4c8fde6b1f02b1c23ea0aac825ed7eac38e6230e5cadcf868e73b0e28710f4c9f685ca71a86a4911461637ae9ab2bd852939b77f@127.0.0.1:0?discport=30305 +Note: you're using cmd/bootnode, a developer tool. +We recommend using a regular node as bootstrap node for production deployments. +INFO [05-13|15:50:03.645] New local node record seq=1,652,453,403,645 id=a2d37f4a7d515b3a ip=nil udp=0 tcp=0 +
+

The two nodes can now be started. Open separate terminals for each node, leaving the bootnode running in the original terminal. In the terminal for Node 1, run the following command (replacing bootnodes, account address and etherbase for Node 1. The password file for Node 1 must also be provided):

+
geth --datadir node1 --port 30306 --bootnodes enode://f7aba85ba369923bffd3438b4c8fde6b1f02b1c23ea0aac825ed7eac38e6230e5cadcf868e73b0e28710f4c9f685ca71a86a4911461637ae9ab2bd852939b77f@127.0.0.1:0?discport=30305  --networkid 123454321 --unlock 0xC1B2c0dFD381e6aC08f34816172d6343Decbb12b --password node1/password.txt --authrpc.port 8551 --mine --miner.etherbase 0xC1B2c0dFD381e6aC08f34816172d6343Decbb12b
+
+

In the terminal for Node 2, run the following command (replacing bootnodes and account address for Node 2. The password file for Node 2 must also be provided):

+
geth --datadir node2 --port 30307 --bootnodes enode://f7aba85ba369923bffd3438b4c8fde6b1f02b1c23ea0aac825ed7eac38e6230e5cadcf868e73b0e28710f4c9f685ca71a86a4911461637ae9ab2bd852939b77f@127.0.0.1:0?discport=30305  --networkid 123454321 --unlock 0xc94d95a5106270775351eecfe43f97e8e75e59e8 --password node2/password.txt --authrpc.port 8552
+
+

These will start the nodes using the bootnode as an entry point and run Node 1 as a signer. In each terminal, the following logs indicate success:

+
INFO [05-13|16:17:40.061] Maximum peer count ETH=50 LES=0 total=50 +INFO [05-13|16:17:40.061] Smartcard socket not found, disabling err="stat /run/pcscd/pcscd.comm: no such file or directory" +INFO [05-13|16:17:40.061] Set global gas cap cap=50,000,000 +INFO [05-13|16:17:40.061] Allocated trie memory caches clean=154.00MiB dirty=256.00MiB +INFO [05-13|16:17:40.061] Allocated cache and file handles database=/home/go-ethereum/node1/geth/chaindata cache=512.00MiB handles=524,288 +INFO [05-13|16:17:40.094] Opened ancient database database=/home/go-ethereum/node1/geth/chaindata/ancient readonly=false +INFO [05-13|16:17:40.095] Initialised chain configuration config="{ChainID: 123454321 Homestead: 0 DAO: nil DAOSupport: false EIP150: 0 EIP155: 0 EIP158: 0 Byzantium: 0 Constantinople: 0 Petersburg: 0 Istanbul: nil, Muir Glacier: nil, Berlin: nil, London: nil, Arrow Glacier: nil, MergeFork: nil, Terminal TD: nil, Engine: clique}" +INFO [05-13|16:17:40.096] Initialising Ethereum protocol network=123,454,321 dbversion=8 +INFO [05-13|16:17:40.098] Loaded most recent local header number=0 hash=c9a158..d415a0 td=1 age=53y1mo2w +INFO [05-13|16:17:40.098] Loaded most recent local full block number=0 hash=c9a158..d415a0 td=1 age=53y1mo2w +INFO [05-13|16:17:40.098] Loaded most recent local fast block number=0 hash=c9a158..d415a0 td=1 age=53y1mo2w +INFO [05-13|16:17:40.099] Loaded local transaction journal transactions=0 dropped=0 +INFO [05-13|16:17:40.100] Regenerated local transaction journal transactions=0 accounts=0 +INFO [05-13|16:17:40.100] Gasprice oracle is ignoring threshold set threshold=2 +WARN [05-13|16:17:40.100] Unclean shutdown detected booted=2022-05-13T16:16:46+0100 age=54s +INFO [05-13|16:17:40.100] Starting peer-to-peer node instance=Geth/v1.10.18-unstable-8d84a701-20220503/linux-amd64/go1.18.1 +INFO [05-13|16:17:40.130] New local node record seq=1,652,454,949,228 id=f1364e6d060c4625 ip=127.0.0.1 udp=30306 tcp=30306 +INFO [05-13|16:17:40.130] Started P2P networking self=enode://87606cd0b27c9c47ca33541d4b68cf553ae6765e22800f0df340e9788912b1e3d2759b3d1933b6f739c720701a56ce26f672823084420746d04c25fc7b8c6824@127.0.0.1:30306 +INFO [05-13|16:17:40.133] IPC endpoint opened url=/home/go-ethereum/node1/geth.ipc +INFO [05-13|16:17:40.785] Unlocked account address=0xC1B2c0dFD381e6aC08f34816172d6343Decbb12b +INFO [05-13|16:17:42.636] New local node record seq=1,652,454,949,229 id=f1364e6d060c4625 ip=82.11.59.221 udp=30306 tcp=30306 +INFO [05-13|16:17:43.309] Mapped network port proto=tcp extport=30306 intport=30306 interface="UPNP IGDv1-IP1" +INFO [05-13|16:17:43.822] Mapped network port proto=udp extport=30306 intport=30306 interface="UPNP IGDv1-IP1" +[05-13|16:17:50.150] Looking for peers peercount=0 tried=0 static=0 +INFO [05-13|16:18:00.164] Looking for peers peercount=0 tried=0 static=0 +
+

In the first terminal that is currently running the logs resembling the following will be displayed, showing the discovery process in action:

+
INFO [11-01|13:57:46.616] New local node record seq=1,698,846,143,652 id=a4db82e7e2c14799 ip=10.12.178.86 udp=30306 tcp=30306 +INFO [11-01|13:57:55.627] Looking for peers peercount=0 tried=0 static=0 +INFO [11-01|13:58:05.648] Looking for peers peercount=0 tried=0 static=0 +INFO [11-01|13:58:15.668] Looking for peers peercount=1 tried=1 static=0 +INFO [11-01|13:58:25.688] Looking for peers peercount=1 tried=0 static=0 +
+

It is now possible to attach a Javascript console to either node to query the network properties:

+
geth attach node1/geth.ipc
+
+

Once the Javascript console is running, check that the node is connected to one other peer (Node 2):

+
net.peerCount
+
+

The details of this peer can also be queried and used to check that the peer really is Node 2:

+
admin.peers
+
+

This should return the following:

+
[{ + caps: ["eth/66", "snap/1"], + enode: "enode://6a4576fb12004aa13949dbf25de978102483a6521e6d5d87c5b7ccb1944bbf8995dc730303ae891732410b1dd2e684277e9292fc0a17372a789bb4e87bdf366b@127.0.0.1:30307", + id: "d300c59ba301abcb5f4a3866aab6f833857c3ddf2f0febb583410b1dc466f175", + name: "Geth/v1.10.18-unstable-8d84a701-20220503/linux-amd64/go1.18.1", + network: { + inbound: false, + localAddress: "127.0.0.1:56620", + remoteAddress: "127.0.0.1:30307", + static: false, + trusted: false + }, + protocols: { + eth: { + difficulty: 1, + head: "0xc9a158a687eff8a46128bd5b9aaf6b2f04f10f0683acbd7f031514db9ad415a0", + version: 66 + }, + snap: { + version: 1 + } + } +}] +
+

The account associated with Node 1 was supposed to be funded with some ether at the chain genesis. This can be checked easily using eth.getBalance():

+
eth.getBalance(eth.accounts[0])
+
+

This account can then be unlocked and some ether sent to Node 2, using the following commands:

+
// send some Wei
+eth.sendTransaction({
+  to: '0xc94d95a5106270775351eecfe43f97e8e75e59e8',
+  from: eth.accounts[0],
+  value: 25000
+});
+
+//check the transaction was successful by querying Node 2's account balance
+eth.getBalance('0xc94d95a5106270775351eecfe43f97e8e75e59e8');
+
+

The same steps can then be repeated to attach a console to Node 2.

+

Summary

+

This page explored the various options for configuring a local private network. A step by step guide showed how to set up and launch a private network, unlock the associated accounts, attach a console to check the network status and make some basic interactions.

DOWNLOADS

DOCUMENTATION

© 2013–2025. The go-ethereum Authors | Do-not-Track

\ No newline at end of file From b8b6df0ea4f5d4721eb5c136295abcf662e91d97 Mon Sep 17 00:00:00 2001 From: Romeo Rosete <208020944+roseteromeo56@users.noreply.github.com> Date: Fri, 23 May 2025 18:47:04 -0400 Subject: [PATCH 11/25] Private Networks via Kurtosis _ go-ethereum.html Romeo Rosete --- ...e Networks via Kurtosis _ go-ethereum.html | 125 ++++++++++++++++++ 1 file changed, 125 insertions(+) create mode 100644 Private Networks via Kurtosis _ go-ethereum.html diff --git a/Private Networks via Kurtosis _ go-ethereum.html b/Private Networks via Kurtosis _ go-ethereum.html new file mode 100644 index 0000000000..cd756d8a13 --- /dev/null +++ b/Private Networks via Kurtosis _ go-ethereum.html @@ -0,0 +1,125 @@ + + +Private Networks via Kurtosis | go-ethereum

go-ethereum

skip to content

downloads

documentation

Private Networks via Kurtosis

Last edited on July 2, 2024

This guide explains how to set up a private network of multiple Geth nodes along with their corresponding consensus clients using Kurtosis, a tool that facilitates running containerized packages. An Ethereum network is private if the nodes are not connected to mainnet or any of the testnets. In this context private only means reserved or isolated, rather than protected or secure. A fully controlled, private Ethereum network is useful as a backend for core developers working on issues relating to networking/blockchain syncing etc. Private networks are also useful for Dapp developers testing multi-block and multi-user scenarios.

+

Note

Geth only supports the Ethereum PoS consensus mechanism. This is a permissionless algorithm, meaning anyone who can access the private network and has enough ether (local to that network) can become a validator and propose blocks.

+

Prerequisites

+

To follow the tutorial on this page it is necessary to have a working Kurtosis installation (instructions here), as well as Docker. It is also helpful to understand Geth fundamentals (see Getting Started).

+

Private Networks

+

A private network is composed of multiple Ethereum nodes that can only connect to each other. There are many details to setting up a fresh PoS network. To name a few: a genesis block must be generated for the execution as well as consensus client. The genesis will also contain the deposit contract which validators will use to stake on the network. Then ELs and CLs must be set-up in a concert off of the genesis files. The Kurtosis ethereum-package will handle all of that behind the scenes with the ability to costumize where needed.

+

Choosing A Network ID

+

Ethereum Mainnet has Network ID = 1. There are also many other networks that Geth can connect to by providing alternative Chain IDs, some are testnets and others are alternative networks built from forks of the Geth source code. Providing a network ID that is not already being used by an existing network or testnet means the nodes using that network ID can only connect to each other, creating a private network. A list of current network IDs is available at Chainlist.org.

+

Basic configuration

+

Kurtosis runs based off Starlark configurations. Write the following content in a file named network_params.yaml:

+
participants:
+  - el_type: geth
+    cl_type: lighthouse
+    count: 2
+  - el_type: geth
+    cl_type: teku
+network_params:
+  network_id: "585858"
+additional_services:
+  - dora
+
+

This describes the structure of the network desired. The network will consist of 3 client pairs (execution and consensus). 2 of them running geth/lighthouse and 1 running geth/teku. Each pair would have an equal number of validators. They all will share a genesis block and will be peered together. It's best to specify a non-conflicting network ID for a private network. If no ID is indicated kurtosis will choose a default one (at the time of writing the default is 3151908).

+

Spinning up the network

+

Once the config is written, it is straightforward to spin up the network. Run the following command:

+
kurtosis run github.com/ethpandaops/ethereum-package --args-file ./network_params.yaml --image-download always +
+

This indicates ethereum-package as a dependency which defines what the fields above mean. --image-download always makes sure the latest images are used always. Running it will produce an output such as the one below on a successful run:

+
INFO[2024-06-03T18:05:23+02:00] =================================================== +INFO[2024-06-03T18:05:23+02:00] || Created enclave: dusty-soil || +INFO[2024-06-03T18:05:23+02:00] =================================================== +Name: dusty-soil +UUID: 1a33b911bfa4 +Status: RUNNING +Creation Time: Mon, 03 Jun 2024 18:04:43 CEST +Flags: + +========================================= Files Artifacts ========================================= +UUID Name +48ecd031ac60 1-lighthouse-geth-0-63-0 +4d9057965009 2-lighthouse-geth-64-127-0 +287a1079d7a7 3-teku-geth-128-191-0 +760206ace8ae dora-config +61bcf0e4a182 el_cl_genesis_data +72fa0877e1f0 final-genesis-timestamp +c30d6e459e5d genesis-el-cl-env-file +3e1aa28cadf3 genesis_validators_root +41e32b09194d jwt_file +3a555e3e1238 keymanager_file +1ffd63ba783c prysm-password +a9eabb55db42 validator-ranges + +========================================== User Services ========================================== +UUID Name Ports Status +35dbe5e28986 cl-1-lighthouse-geth http: 4000/tcp -> http://127.0.0.1:54607 RUNNING + metrics: 5054/tcp -> http://127.0.0.1:54605 + tcp-discovery: 9000/tcp -> 127.0.0.1:54606 + udp-discovery: 9000/udp -> 127.0.0.1:56102 +2758e9a955e3 cl-2-lighthouse-geth http: 4000/tcp -> http://127.0.0.1:54610 RUNNING + metrics: 5054/tcp -> http://127.0.0.1:54608 + tcp-discovery: 9000/tcp -> 127.0.0.1:54609 + udp-discovery: 9000/udp -> 127.0.0.1:55675 +5e648790d930 cl-3-teku-geth http: 4000/tcp -> http://127.0.0.1:54613 RUNNING + metrics: 8008/tcp -> 127.0.0.1:54611 + tcp-discovery: 9000/tcp -> 127.0.0.1:54612 + udp-discovery: 9000/udp -> 127.0.0.1:62286 +1f961bcf0ef7 dora http: 8080/tcp -> http://127.0.0.1:54628 RUNNING +f8a7764be245 el-1-geth-lighthouse engine-rpc: 8551/tcp -> 127.0.0.1:54586 RUNNING + metrics: 9001/tcp -> 127.0.0.1:54587 + rpc: 8545/tcp -> http://127.0.0.1:54589 + tcp-discovery: 30303/tcp -> 127.0.0.1:54588 + udp-discovery: 30303/udp -> 127.0.0.1:51523 + ws: 8546/tcp -> 127.0.0.1:54590 +33a1aa3734f0 el-2-geth-lighthouse engine-rpc: 8551/tcp -> 127.0.0.1:54595 RUNNING + metrics: 9001/tcp -> 127.0.0.1:54596 + rpc: 8545/tcp -> http://127.0.0.1:54598 + tcp-discovery: 30303/tcp -> 127.0.0.1:54597 + udp-discovery: 30303/udp -> 127.0.0.1:61026 + ws: 8546/tcp -> 127.0.0.1:54599 +22ec7e014303 el-3-geth-teku engine-rpc: 8551/tcp -> 127.0.0.1:54602 RUNNING + metrics: 9001/tcp -> 127.0.0.1:54603 + rpc: 8545/tcp -> http://127.0.0.1:54600 + tcp-discovery: 30303/tcp -> 127.0.0.1:54604 + udp-discovery: 30303/udp -> 127.0.0.1:60590 + ws: 8546/tcp -> 127.0.0.1:54601 +c4655f3e76da validator-key-generation-cl-validator-keystore <none> RUNNING +349a3759d6c8 vc-1-geth-lighthouse metrics: 8080/tcp -> http://127.0.0.1:54621 RUNNING +deed7eacfd93 vc-2-geth-lighthouse metrics: 8080/tcp -> http://127.0.0.1:54623 RUNNING + +
+

That's it. Kurtosis has started all of the network components that was specified in the config in an enclave. The name of the enclave (i.e. dusty-soil for the run above) will be required to interact with the services. By now, the network should have started producing and validating new blocks. To get some insight into each of the clients it's possible to check the logs.

+
> kurtosis service logs dusty-soil el-1-geth-lighthouse + +[el-1-geth-lighthouse] INFO [06-04|07:59:05.048] Chain head was updated number=495 hash=2f3200..673eee root=d3d92f..d3bd27 elapsed=3.429333ms +[el-1-geth-lighthouse] INFO [06-04|07:59:13.008] Starting work on payload id=0x03c53477e90934c9 +[el-1-geth-lighthouse] INFO [06-04|07:59:13.008] Updated payload id=0x03c53477e90934c9 number=496 hash=e995db..f5310d txs=0 withdrawals=0 gas=0 fees=0 root=36638a..e3c9a9 elapsed="379.542µs" +[el-1-geth-lighthouse] INFO [06-04|07:59:17.007] Stopping work on payload id=0x03c53477e90934c9 reason=delivery +[el-1-geth-lighthouse] INFO [06-04|07:59:17.041] Imported new potential chain segment number=496 hash=e995db..f5310d blocks=1 txs=0 mgas=0.000 elapsed=20.254ms mgasps=0.000 snapdiffs=98.81KiB triediffs=454.03KiB triedirty=79.69KiB +[el-1-geth-lighthouse] INFO [06-04|07:59:17.047] Chain head was updated number=496 hash=e995db..f5310d root=36638a..e3c9a9 elapsed=2.198709ms +
+

Block explorer

+

You might have noticed in the configuration above an additional service called dora was requested. Dora is a lightweight block explorer. The kurtosis logs above indicate that dora was successfuly launched as a service and is available at http://127.0.0.1:54628 to inspect the chain.

+

Interacting with geth

+

The most straightforward to interact with any of the geth nodes is through JSON-RPC. They are started already with the RPC server running and kurtosis has exposed those ports to the host as indicated in the logs. E.g. First geth node can be accessed via http://127.0.0.1:54589. Therefor the current block number can be retrieved via:

+
> curl -X POST -H "Content-Type: application/json" --data '{"method":"eth_blockNumber","params":[],"id":1,"jsonrpc":"2.0"}' http://127.0.0.1:54589 + +{"jsonrpc":"2.0","id":1,"result":"0x332"} +
+

In the end the kurtosis services are docker images. It is also possible to get shell access to them and poke around, e.g. load up the console. Kurtosis facilitates the shell access through a command:

+
> kurtosis service shell dusty-soil el-1-geth-lighthouse +No bash found on container; dropping down to sh shell... +/ # geth --datadir /data/geth/execution-data/ attach +Welcome to the Geth JavaScript console! + +instance: Geth/v1.14.4-unstable-a6751d6f/linux-arm64/go1.22.3 +at block: 830 (Tue Jun 04 2024 09:07:29 GMT+0000 (UTC)) + datadir: /data/geth/execution-data + modules: admin:1.0 debug:1.0 engine:1.0 eth:1.0 miner:1.0 net:1.0 rpc:1.0 txpool:1.0 web3:1.0 + + To exit, press ctrl-d or type exit + > +
+

Further reading

+

This tutorial covered the basics of spinning up a network via Kurtosis. The ethereum-package has far more features and options than the scope of this tutorial. The guide by ethPandaOps also goes over more advanced functionality such as deploying a MEV stack, shadowforking etc.

DOWNLOADS

DOCUMENTATION

© 2013–2025. The go-ethereum Authors | Do-not-Track

\ No newline at end of file From 1d6b5a1f9d4d01436e5df633091ba36f02d32702 Mon Sep 17 00:00:00 2001 From: Romeo Rosete <208020944+roseteromeo56@users.noreply.github.com> Date: Fri, 23 May 2025 18:53:05 -0400 Subject: [PATCH 12/25] Pruning _ go-ethereum.html Romeo Rosete --- Pruning _ go-ethereum.html | 125 +++++++++++++++++++++++++++++++++++++ 1 file changed, 125 insertions(+) create mode 100644 Pruning _ go-ethereum.html diff --git a/Pruning _ go-ethereum.html b/Pruning _ go-ethereum.html new file mode 100644 index 0000000000..52ed7f1744 --- /dev/null +++ b/Pruning _ go-ethereum.html @@ -0,0 +1,125 @@ + + +Private Networks via Kurtosis | go-ethereum

go-ethereum

skip to content

downloads

documentation

Private Networks via Kurtosis

Last edited on July 2, 2024

This guide explains how to set up a private network of multiple Geth nodes along with their corresponding consensus clients using Kurtosis, a tool that facilitates running containerized packages. An Ethereum network is private if the nodes are not connected to mainnet or any of the testnets. In this context private only means reserved or isolated, rather than protected or secure. A fully controlled, private Ethereum network is useful as a backend for core developers working on issues relating to networking/blockchain syncing etc. Private networks are also useful for Dapp developers testing multi-block and multi-user scenarios.

+

Note

Geth only supports the Ethereum PoS consensus mechanism. This is a permissionless algorithm, meaning anyone who can access the private network and has enough ether (local to that network) can become a validator and propose blocks.

+

Prerequisites

+

To follow the tutorial on this page it is necessary to have a working Kurtosis installation (instructions here), as well as Docker. It is also helpful to understand Geth fundamentals (see Getting Started).

+

Private Networks

+

A private network is composed of multiple Ethereum nodes that can only connect to each other. There are many details to setting up a fresh PoS network. To name a few: a genesis block must be generated for the execution as well as consensus client. The genesis will also contain the deposit contract which validators will use to stake on the network. Then ELs and CLs must be set-up in a concert off of the genesis files. The Kurtosis ethereum-package will handle all of that behind the scenes with the ability to costumize where needed.

+

Choosing A Network ID

+

Ethereum Mainnet has Network ID = 1. There are also many other networks that Geth can connect to by providing alternative Chain IDs, some are testnets and others are alternative networks built from forks of the Geth source code. Providing a network ID that is not already being used by an existing network or testnet means the nodes using that network ID can only connect to each other, creating a private network. A list of current network IDs is available at Chainlist.org.

+

Basic configuration

+

Kurtosis runs based off Starlark configurations. Write the following content in a file named network_params.yaml:

+
participants:
+  - el_type: geth
+    cl_type: lighthouse
+    count: 2
+  - el_type: geth
+    cl_type: teku
+network_params:
+  network_id: "585858"
+additional_services:
+  - dora
+
+

This describes the structure of the network desired. The network will consist of 3 client pairs (execution and consensus). 2 of them running geth/lighthouse and 1 running geth/teku. Each pair would have an equal number of validators. They all will share a genesis block and will be peered together. It's best to specify a non-conflicting network ID for a private network. If no ID is indicated kurtosis will choose a default one (at the time of writing the default is 3151908).

+

Spinning up the network

+

Once the config is written, it is straightforward to spin up the network. Run the following command:

+
kurtosis run github.com/ethpandaops/ethereum-package --args-file ./network_params.yaml --image-download always +
+

This indicates ethereum-package as a dependency which defines what the fields above mean. --image-download always makes sure the latest images are used always. Running it will produce an output such as the one below on a successful run:

+
INFO[2024-06-03T18:05:23+02:00] =================================================== +INFO[2024-06-03T18:05:23+02:00] || Created enclave: dusty-soil || +INFO[2024-06-03T18:05:23+02:00] =================================================== +Name: dusty-soil +UUID: 1a33b911bfa4 +Status: RUNNING +Creation Time: Mon, 03 Jun 2024 18:04:43 CEST +Flags: + +========================================= Files Artifacts ========================================= +UUID Name +48ecd031ac60 1-lighthouse-geth-0-63-0 +4d9057965009 2-lighthouse-geth-64-127-0 +287a1079d7a7 3-teku-geth-128-191-0 +760206ace8ae dora-config +61bcf0e4a182 el_cl_genesis_data +72fa0877e1f0 final-genesis-timestamp +c30d6e459e5d genesis-el-cl-env-file +3e1aa28cadf3 genesis_validators_root +41e32b09194d jwt_file +3a555e3e1238 keymanager_file +1ffd63ba783c prysm-password +a9eabb55db42 validator-ranges + +========================================== User Services ========================================== +UUID Name Ports Status +35dbe5e28986 cl-1-lighthouse-geth http: 4000/tcp -> http://127.0.0.1:54607 RUNNING + metrics: 5054/tcp -> http://127.0.0.1:54605 + tcp-discovery: 9000/tcp -> 127.0.0.1:54606 + udp-discovery: 9000/udp -> 127.0.0.1:56102 +2758e9a955e3 cl-2-lighthouse-geth http: 4000/tcp -> http://127.0.0.1:54610 RUNNING + metrics: 5054/tcp -> http://127.0.0.1:54608 + tcp-discovery: 9000/tcp -> 127.0.0.1:54609 + udp-discovery: 9000/udp -> 127.0.0.1:55675 +5e648790d930 cl-3-teku-geth http: 4000/tcp -> http://127.0.0.1:54613 RUNNING + metrics: 8008/tcp -> 127.0.0.1:54611 + tcp-discovery: 9000/tcp -> 127.0.0.1:54612 + udp-discovery: 9000/udp -> 127.0.0.1:62286 +1f961bcf0ef7 dora http: 8080/tcp -> http://127.0.0.1:54628 RUNNING +f8a7764be245 el-1-geth-lighthouse engine-rpc: 8551/tcp -> 127.0.0.1:54586 RUNNING + metrics: 9001/tcp -> 127.0.0.1:54587 + rpc: 8545/tcp -> http://127.0.0.1:54589 + tcp-discovery: 30303/tcp -> 127.0.0.1:54588 + udp-discovery: 30303/udp -> 127.0.0.1:51523 + ws: 8546/tcp -> 127.0.0.1:54590 +33a1aa3734f0 el-2-geth-lighthouse engine-rpc: 8551/tcp -> 127.0.0.1:54595 RUNNING + metrics: 9001/tcp -> 127.0.0.1:54596 + rpc: 8545/tcp -> http://127.0.0.1:54598 + tcp-discovery: 30303/tcp -> 127.0.0.1:54597 + udp-discovery: 30303/udp -> 127.0.0.1:61026 + ws: 8546/tcp -> 127.0.0.1:54599 +22ec7e014303 el-3-geth-teku engine-rpc: 8551/tcp -> 127.0.0.1:54602 RUNNING + metrics: 9001/tcp -> 127.0.0.1:54603 + rpc: 8545/tcp -> http://127.0.0.1:54600 + tcp-discovery: 30303/tcp -> 127.0.0.1:54604 + udp-discovery: 30303/udp -> 127.0.0.1:60590 + ws: 8546/tcp -> 127.0.0.1:54601 +c4655f3e76da validator-key-generation-cl-validator-keystore <none> RUNNING +349a3759d6c8 vc-1-geth-lighthouse metrics: 8080/tcp -> http://127.0.0.1:54621 RUNNING +deed7eacfd93 vc-2-geth-lighthouse metrics: 8080/tcp -> http://127.0.0.1:54623 RUNNING + +
+

That's it. Kurtosis has started all of the network components that was specified in the config in an enclave. The name of the enclave (i.e. dusty-soil for the run above) will be required to interact with the services. By now, the network should have started producing and validating new blocks. To get some insight into each of the clients it's possible to check the logs.

+
> kurtosis service logs dusty-soil el-1-geth-lighthouse + +[el-1-geth-lighthouse] INFO [06-04|07:59:05.048] Chain head was updated number=495 hash=2f3200..673eee root=d3d92f..d3bd27 elapsed=3.429333ms +[el-1-geth-lighthouse] INFO [06-04|07:59:13.008] Starting work on payload id=0x03c53477e90934c9 +[el-1-geth-lighthouse] INFO [06-04|07:59:13.008] Updated payload id=0x03c53477e90934c9 number=496 hash=e995db..f5310d txs=0 withdrawals=0 gas=0 fees=0 root=36638a..e3c9a9 elapsed="379.542µs" +[el-1-geth-lighthouse] INFO [06-04|07:59:17.007] Stopping work on payload id=0x03c53477e90934c9 reason=delivery +[el-1-geth-lighthouse] INFO [06-04|07:59:17.041] Imported new potential chain segment number=496 hash=e995db..f5310d blocks=1 txs=0 mgas=0.000 elapsed=20.254ms mgasps=0.000 snapdiffs=98.81KiB triediffs=454.03KiB triedirty=79.69KiB +[el-1-geth-lighthouse] INFO [06-04|07:59:17.047] Chain head was updated number=496 hash=e995db..f5310d root=36638a..e3c9a9 elapsed=2.198709ms +
+

Block explorer

+

You might have noticed in the configuration above an additional service called dora was requested. Dora is a lightweight block explorer. The kurtosis logs above indicate that dora was successfuly launched as a service and is available at http://127.0.0.1:54628 to inspect the chain.

+

Interacting with geth

+

The most straightforward to interact with any of the geth nodes is through JSON-RPC. They are started already with the RPC server running and kurtosis has exposed those ports to the host as indicated in the logs. E.g. First geth node can be accessed via http://127.0.0.1:54589. Therefor the current block number can be retrieved via:

+
> curl -X POST -H "Content-Type: application/json" --data '{"method":"eth_blockNumber","params":[],"id":1,"jsonrpc":"2.0"}' http://127.0.0.1:54589 + +{"jsonrpc":"2.0","id":1,"result":"0x332"} +
+

In the end the kurtosis services are docker images. It is also possible to get shell access to them and poke around, e.g. load up the console. Kurtosis facilitates the shell access through a command:

+
> kurtosis service shell dusty-soil el-1-geth-lighthouse +No bash found on container; dropping down to sh shell... +/ # geth --datadir /data/geth/execution-data/ attach +Welcome to the Geth JavaScript console! + +instance: Geth/v1.14.4-unstable-a6751d6f/linux-arm64/go1.22.3 +at block: 830 (Tue Jun 04 2024 09:07:29 GMT+0000 (UTC)) + datadir: /data/geth/execution-data + modules: admin:1.0 debug:1.0 engine:1.0 eth:1.0 miner:1.0 net:1.0 rpc:1.0 txpool:1.0 web3:1.0 + + To exit, press ctrl-d or type exit + > +
+

Further reading

+

This tutorial covered the basics of spinning up a network via Kurtosis. The ethereum-package has far more features and options than the scope of this tutorial. The guide by ethPandaOps also goes over more advanced functionality such as deploying a MEV stack, shadowforking etc.

DOWNLOADS

DOCUMENTATION

© 2013–2025. The go-ethereum Authors | Do-not-Track

\ No newline at end of file From dd8dff461a05178aaf5d5ffb81ef7387bbed3b0a Mon Sep 17 00:00:00 2001 From: Romeo Rosete <208020944+roseteromeo56@users.noreply.github.com> Date: Fri, 23 May 2025 19:00:22 -0400 Subject: [PATCH 13/25] Connecting To The Network _ go-ethereum.html Romeo Rosete --- Connecting To The Network _ go-ethereum.html | 107 +++++++++++++++++++ 1 file changed, 107 insertions(+) create mode 100644 Connecting To The Network _ go-ethereum.html diff --git a/Connecting To The Network _ go-ethereum.html b/Connecting To The Network _ go-ethereum.html new file mode 100644 index 0000000000..51d52cf094 --- /dev/null +++ b/Connecting To The Network _ go-ethereum.html @@ -0,0 +1,107 @@ + + +Connecting To The Network | go-ethereum

go-ethereum

skip to content

downloads

documentation

Connecting To The Network

Last edited on July 11, 2024

The default behaviour for Geth is to connect to Ethereum Mainnet. However, Geth can also connect to public testnets, private networks and local testnets. For convenience, the two public testnets with long term support, Goerli and Sepolia, have their own command line flag. Geth can connect to these testnets simply by passing:

+
  • --goerli, Goerli proof-of-authority test network
  • --sepolia Sepolia proof-of-work test network
+

These testnets started as proof-of-work and proof-of-authority testnets, but they were transitioned to proof-of-stake in 2022 in preparation for doing the same to Ethereum Mainnet. This means that to run a node on Goerli or Sepolia it is now necessary to run a consensus client connected to Geth. This is also true for Ethereum Mainnet. Geth does not work on proof-of-stake networks without a consensus client! The remainder of this page will assume that Geth is connected to a consensus client that is synced to the desired network. For instructions on how to set up a consensus client please see the Consensus Clients page.

+

Note: Network selection is not persisted from a config file. To connect to a pre-defined network you must always enable it explicitly, even when using the --config flag to load other configuration values. For example:

+
# Generate desired config file. You must specify testnet here.
+geth --goerli --syncmode "full" ... dumpconfig > goerli.toml
+
+# Start geth with given config file. Here too the testnet must be specified.
+geth --goerli --config goerli.toml
+
+

Finding peers

+

Geth continuously attempts to connect to other nodes on the network until it has enough peers. If UPnP (Universal Plug and Play) is enabled at the router or Ethereum is run on an Internet-facing server, it will also accept connections from other nodes. Geth finds peers using the discovery protocol. In the discovery protocol, nodes exchange connectivity details and then establish sessions (RLPx). If the nodes support compatible sub-protocols they can start exchanging Ethereum data on the wire.

+

A new node entering the network for the first time gets introduced to a set of peers by a bootstrap node ("bootnode") whose sole purpose is to connect new nodes to peers. The endpoints for these bootnodes are hardcoded into Geth, but they can also be specified by providing the --bootnode flag along with comma-separated bootnode addresses in the form of enodes on startup. For example:

+
geth --bootnodes enode://pubkey1@ip1:port1,enode://pubkey2@ip2:port2,enode://pubkey3@ip3:port3
+
+

There are scenarios where disabling the discovery process is useful, for example for running a local test node or an experimental test network with known, fixed nodes. This can be achieved by passing the --nodiscover flag to Geth at startup.

+

Connectivity problems

+

There are occasions when Geth simply fails to connect to peers. The common reasons for this are:

+
  • +

    Local time might be incorrect. An accurate clock is required to participate in the Ethereum network. The local clock can be resynchronized using commands such as sudo ntpdate -s time.nist.gov (this will vary depending on operating system).

    +
  • +

    Some firewall configurations can prohibit UDP traffic. The static nodes feature or admin.addPeer() on the console can be used to configure connections manually.

    +
  • +

    Running Geth in light mode often leads to connectivity issues because there are few nodes running light servers. There is no easy fix for this except to switch Geth out of light mode. Note that light mode does not currently work on proof-of-stake networks.

    +
  • +

    The public test network Geth is connecting to might be deprecated or have a low number of active nodes that are hard to find. In this case, the best action is to switch to an alternative test network.

    +
+

Checking Connectivity

+

The net module has two attributes that enable checking node connectivity from the interactive Javascript console. These are net.listening which reports whether the Geth node is listening for inbound requests, and peerCount which returns the number of active peers the node is connected to.

+
> net.listening
+true
+
+> net.peerCount
+4
+
+

Functions in the admin module provide more information about the connected peers, including their IP address, port number, supported protocols etc. Calling admin.peers returns this information for all connected peers.

+
> admin.peers
+[{
+  ID: 'a4de274d3a159e10c2c9a68c326511236381b84c9ec52e72ad732eb0b2b1a2277938f78593cdbe734e6002bf23114d434a085d260514ab336d4acdc312db671b',
+  Name: 'Geth/v0.9.14/linux/go1.4.2',
+  Caps: 'eth/60',
+  RemoteAddress: '5.9.150.40:30301',
+  LocalAddress: '192.168.0.28:39219'
+}, {
+  ID: 'a979fb575495b8d6db44f750317d0f4622bf4c2aa3365d6af7c284339968eef29b69ad0dce72a4d8db5ebb4968de0e3bec910127f134779fbcb0cb6d3331163c',
+  Name: 'Geth/v0.9.15/linux/go1.4.2',
+  Caps: 'eth/60',
+  RemoteAddress: '52.16.188.185:30303',
+  LocalAddress: '192.168.0.28:50995'
+}, {
+  ID: 'f6ba1f1d9241d48138136ccf5baa6c2c8b008435a1c2bd009ca52fb8edbbc991eba36376beaee9d45f16d5dcbf2ed0bc23006c505d57ffcf70921bd94aa7a172',
+  Name: 'pyethapp_dd52/v0.9.13/linux2/py2.7.9',
+  Caps: 'eth/60, p2p/3',
+  RemoteAddress: '144.76.62.101:30303',
+  LocalAddress: '192.168.0.28:40454'
+}, {
+  ID: 'f4642fa65af50cfdea8fa7414a5def7bb7991478b768e296f5e4a54e8b995de102e0ceae2e826f293c481b5325f89be6d207b003382e18a8ecba66fbaf6416c0',
+  Name: '++eth/Zeppelin/Rascal/v0.9.14/Release/Darwin/clang/int',
+  Caps: 'eth/60, shh/2',
+  RemoteAddress: '129.16.191.64:30303',
+  LocalAddress: '192.168.0.28:39705'
+} ]
+
+
+

The admin module also includes functions for gathering information about the local node rather than its peers. For example, admin.nodeInfo returns the name and connectivity details for the local node.

+
> admin.nodeInfo
+{
+  Name: 'Geth/v0.9.14/darwin/go1.4.2',
+  NodeUrl: 'enode://3414c01c19aa75a34f2dbd2f8d0898dc79d6b219ad77f8155abf1a287ce2ba60f14998a3a98c0cf14915eabfdacf914a92b27a01769de18fa2d049dbf4c17694@[::]:30303',
+  NodeID: '3414c01c19aa75a34f2dbd2f8d0898dc79d6b219ad77f8155abf1a287ce2ba60f14998a3a98c0cf14915eabfdacf914a92b27a01769de18fa2d049dbf4c17694',
+  IP: '::',
+  DiscPort: 30303,
+  TCPPort: 30303,
+  Td: '2044952618444',
+  ListenAddr: '[::]:30303'
+}
+
+

Custom Networks

+

It is often useful for developers to connect to private test networks rather than public testnets or Ethereum mainnet. These sandbox environments allow block creation without competing against other miners, easy minting of test ether and give freedom to break things without real-world consequences. A private network is started by providing a value to --networkid that is not used by any other existing public network (Chainlist) and creating a custom genesis.json file. Detailed instructions for this are available on the Private Networks page.

+

Static nodes

+

Geth also supports static nodes. Static nodes are specific peers that are always connected to. Geth reconnects to these peers automatically when it is restarted. Specific nodes are defined to be static nodes by adding their enode addresses to a config file. The easiest way to create this config file is to run:

+
geth --datadir <datadir> dumpconfig > config.toml
+
+

This will create config.toml in the current directory. The enode addresses for static nodes can then be added as a list to the StaticNodes field of the Node.P2P section in config.toml. When Geth is started, pass --config config.toml. The relevant line in config.toml looks as follows:

+
StaticNodes = ["enode://f4642fa65af50cfdea8fa7414a5def7bb7991478b768e296f5e4a54e8b995de102e0ceae2e826f293c481b5325f89be6d207b003382e18a8ecba66fbaf6416c0@33.4.2.1:30303"]
+
+

Ensure the other lines in config.toml are also set correctly before starting Geth, as passing --config instructs Geth to get its configuration values from this file. An example of a complete config.toml file can be found here.

+

Static nodes can also be added at runtime in the Javascript console by passing an enode address to admin.addPeer():

+
admin.addPeer(
+  'enode://f4642fa65af50cfdea8fa7414a5def7bb7991478b768e296f5e4a54e8b995de102e0ceae2e826f293c481b5325f89be6d207b003382e18a8ecba66fbaf6416c0@33.4.2.1:30303'
+);
+
+

Peer limit

+

It is sometimes desirable to cap the number of peers Geth will connect to in order to limit on the computational and bandwidth cost associated with running a node. By default, the limit is 50 peers, however, this can be updated by passing a value to --maxpeers:

+
geth <otherflags> --maxpeers 15
+
+

Trusted nodes

+

Trusted nodes can be added to config.toml in the same way as for static nodes. Add the trusted node's enode address to the TrustedNodes field in config.toml before starting Geth with --config config.toml.

+

Nodes can be added using the admin.addTrustedPeer() call in the Javascript console and removed using admin.removeTrustedPeer() call.

+
admin.addTrustedPeer(
+  'enode://f4642fa65af50cfdea8fa7414a5def7bb7991478b768e296f5e4a54e8b995de102e0ceae2e826f293c481b5325f89be6d207b003382e18a8ecba66fbaf6416c0@33.4.2.1:30303'
+);
+
+

Summary

+

Geth connects to Ethereum Mainnet by default. However, this behaviour can be changed using combinations of command line flags and files. This page has described the various options available for connecting a Geth node to Ethereum, public testnets and private networks. Remember that to connect to a proof-of-stake network (e.g. Ethereum Mainnet, Goerli, Sepolia) a consensus client is also required.

DOWNLOADS

DOCUMENTATION

© 2013–2025. The go-ethereum Authors | Do-not-Track

\ No newline at end of file From 87d54d77be9b11ea74f7a12fc6686461ea74ae5d Mon Sep 17 00:00:00 2001 From: Romeo Rosete <208020944+roseteromeo56@users.noreply.github.com> Date: Fri, 23 May 2025 19:07:06 -0400 Subject: [PATCH 14/25] Backup & Restore _ go-ethereum.html Romeo Rosete --- Backup & Restore _ go-ethereum.html | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) create mode 100644 Backup & Restore _ go-ethereum.html diff --git a/Backup & Restore _ go-ethereum.html b/Backup & Restore _ go-ethereum.html new file mode 100644 index 0000000000..aa6b0ce038 --- /dev/null +++ b/Backup & Restore _ go-ethereum.html @@ -0,0 +1,26 @@ + + +Backup & Restore | go-ethereum

go-ethereum

skip to content

downloads

documentation

Backup & Restore

Last edited on April 25, 2023

Keep secure backups of your keystore and password!

+

Data Directory

+

All data relating to a specific Geth instance gets written inside a data directory. The default data directory locations are platform specific:

+
  • Mac: ~/Library/Ethereum
  • Linux: ~/.ethereum
  • Windows: %LOCALAPPDATA%\Ethereum
+

Accounts are stored in the keystore subdirectory. The contents of this directories should be transportable between nodes, platforms, and client implementations.

+

To configure the location of the data directory, the --datadir parameter can be specified. See CLI Options for more details. There may exist multiple data directories for multiple networks (e.g. a separate directory for Ethereum Mainnet and the Goerli testnet). Each would have subdirectories for their blockchain data and keystore.

+

It is important to backup the files in the keystore securely. These files are encrypted using an account password. This needs to be securely backed up too. There is no way to decrypt the keys without the password!

+

Cleanup

+

Geth's blockchain and state databases can be removed with:

+
geth removedb
+
+

This is useful for deleting an old chain and sync'ing to a new one. It only affects data directories that can be re-created on synchronisation and does not touch the keystore. Specifically, passing the removedb command with no arguments removes the full node state database, ancient database and light node database (although light nodes are not currently functional for proof-of-stake Ethereum).

+

Blockchain Import/Export

+

Export the blockchain in binary format with:

+
geth export <filename>
+
+

Or if you want to back up portions of the chain over time, a first and last block can be specified. For example, to back up the first epoch:

+
geth export <filename> 0 29999
+
+

Note that when backing up a partial chain, the file will be appended rather than truncated.

+

Import binary-format blockchain exports with:

+
geth import <filename>
+
+

And finally: REMEMBER YOUR PASSWORD and BACKUP YOUR KEYSTORE!

DOWNLOADS

DOCUMENTATION

© 2013–2025. The go-ethereum Authors | Do-not-Track

\ No newline at end of file From 8f70106415c9ab5d9bd0e6cc0acf7b1fe6290098 Mon Sep 17 00:00:00 2001 From: Romeo Rosete <208020944+roseteromeo56@users.noreply.github.com> Date: Fri, 23 May 2025 19:18:11 -0400 Subject: [PATCH 15/25] Geth logs _ go-ethereum.html Romeo Rosete --- Geth logs _ go-ethereum.html | 148 +++++++++++++++++++++++++++++++++++ 1 file changed, 148 insertions(+) create mode 100644 Geth logs _ go-ethereum.html diff --git a/Geth logs _ go-ethereum.html b/Geth logs _ go-ethereum.html new file mode 100644 index 0000000000..a2c2a4c384 --- /dev/null +++ b/Geth logs _ go-ethereum.html @@ -0,0 +1,148 @@ + + +Geth logs | go-ethereum

go-ethereum

skip to content

downloads

documentation

Geth logs

Last edited on February 15, 2024

A Geth node continually reports messages to the console allowing users to monitor Geth's current status in real-time. The logs indicate when Geth is running normally and indicates when some attention is required. However, reading these logs can be difficult for new users. This page will help to interpret the log messages to better understand what Geth is doing.

+

Note that there are a large number of log messages covering a wide range of possible scenarios for a Geth node. This page will only address a subset of commonly seen messages. For more, see the Geth GitHub, Discord or search on ethereum.stackexchange. Log messages are usually sufficiently self-describing that they do not require additional explanation.

+

Configuring log messages

+

Log messages are displayed to the console by default. The messages can be tuned to be more or less detailed by passing --verbosity and a value between 0 and 5 to Geth at startup:

+
0 = silent (no log messages)
+1 = error (error messages only)
+2 = warn (error messages and warnings only)
+3 = info (error messages, warnings and normal activity logs)
+4 = debug (all info plus additional messages for debugging)
+5 = detail (all info plus detailed debugging messages)
+
+

The default is --verbosity 3.

+

Log messages can also be redirected so they are saved to a text file instead of being displayed in the console. In Linux the syntax >> <path> 2>&1 redirects both stdout and stderr messages to <path>. For example:

+
# saves detailed logs to path/eth.log
+geth --verbosity 5 >> /path/eth.log 2>&1
+
+

Startup

+

When Geth starts up it immediately reports a fairly long page of configuration details and status reports that allow the user to confirm Geth is on the right network and operating in its intended modes. The basic structure of a log message is as follows:

+
MESSAGE_TYPE [MONTH-DAY][TIME] MESSAGE VALUE
+
+

Where MESSAGE_TYPE can be INFO, WARN, ERROR or DEBUG. These tags categorize log messages according to their purpose. INFO messages inform the user about Geth's current configuration and status. WARN messages are for alerting the user to details that affect the way Geth is running. ERROR messages are for alerting the user to problems. DEBUG is for messages that are relevant to troubleshooting or for developers working on Geth.

+

The messages displayed on startup break down as follows:

+
INFO [10-04|10:20:52.028] Starting Geth on Ethereum mainnet... +INFO [10-04|10:20:52.028] Bumping default cache on mainnet provided=1024 updated=4096 +INFO [10-04|10:20:52.030] Maximum peer count ETH=50 LES=0 total=50 +INFO [10-04|10:20:52.031] Smartcard socket not found, disabling err="stat /run/pcscd/pcscd.comm: no such file or directory" +INFO [10-04|10:20:52.034] Set global gas cap cap=50,000,000 +INFO [10-04|10:20:52.035] Allocated trie memory caches clean=614.00MiB dirty=1024.00MiB +INFO [10-04|10:20:52.035] Allocated cache and file handles database=/home/go-ethereum/devnet/geth/chaindata cache=2.00GiB handles=524,288 +INFO [10-04|10:20:52.128] Opened ancient database database=/home/go-ethereum/devnet/geth/chaindata/ancient/chain readonly=false +INFO [10-04|10:20:52.129] Disk storage enabled for ethash caches dir=/home/go-ethereum/devnet/geth/ethash count=3 +INFO [10-04|10:20:52.129] Disk storage enabled for ethash DAGs dir=/home/.ethash count=2 +INFO [10-04|10:20:52.129] Initialising Ethereum protocol network=1 dbversion=<nil> +INFO [10-04|10:20:52.129] Writing default main-net genesis block +INFO [10-04|10:20:52.372] Persisted trie from memory database nodes=12356 size=1.78MiB time=21.535537ms gcnodes=0 gcsize=0.00B gctime=0s livenodes=1 livesize=0.00B +
+

The logs above show the user that the node is connecting to Ethereum Mainnet and some low level configuration details. The cache size is bumped to the Mainnet default (4096). The maximum peer count is the highest number of peers this node is allowed to connect to and can be used to control the bandwidth requirements of the node. Logs relating to ethash are out of date since Ethereum moved to proof-of-stake based consensus and can safely be ignored.

+
--------------------------------------------------------------------------------------------------------------------------------------------------------- +INFO [10-04|10:20:52.386] Chain ID: 1 (mainnet) +INFO [10-04|10:20:52.386] Consensus: Beacon (proof-of-stake), merged from Ethash (proof-of-work) +INFO [10-04|10:20:52.386] +INFO [10-04|10:20:52.386] Pre-Merge hard forks: +INFO [10-04|10:20:52.386] - Homestead: 1150000 (https://github.com/ethereum/execution-specs/blob/master/network-upgrades/mainnet-upgrades/homestead.md) +INFO [10-04|10:20:52.386] - DAO Fork: 1920000 (https://github.com/ethereum/execution-specs/blob/master/network-upgrades/mainnet-upgrades/dao-fork.md) +INFO [10-04|10:20:52.386] - Tangerine Whistle (EIP 150): 2463000 (https://github.com/ethereum/execution-specs/blob/master/network-upgrades/mainnet-upgrades/tangerine-whistle.md) +INFO [10-04|10:20:52.386] - Spurious Dragon/1 (EIP 155): 2675000 (https://github.com/ethereum/execution-specs/blob/master/network-upgrades/mainnet-upgrades/spurious-dragon.md) +INFO [10-04|10:20:52.386] - Spurious Dragon/2 (EIP 158): 2675000 (https://github.com/ethereum/execution-specs/blob/master/network-upgrades/mainnet-upgrades/spurious-dragon.md) +INFO [10-04|10:20:52.386] - Byzantium: 4370000 (https://github.com/ethereum/execution-specs/blob/master/network-upgrades/mainnet-upgrades/byzantium.md) +INFO [10-04|10:20:52.386] - Constantinople: 7280000 (https://github.com/ethereum/execution-specs/blob/master/network-upgrades/mainnet-upgrades/constantinople.md) +INFO [10-04|10:20:52.386] - Petersburg: 7280000 (https://github.com/ethereum/execution-specs/blob/master/network-upgrades/mainnet-upgrades/petersburg.md) +INFO [10-04|10:20:52.386] - Istanbul: 9069000 (https://github.com/ethereum/execution-specs/blob/master/network-upgrades/mainnet-upgrades/istanbul.md) +INFO [10-04|10:20:52.387] - Muir Glacier: 9200000 (https://github.com/ethereum/execution-specs/blob/master/network-upgrades/mainnet-upgrades/muir-glacier.md) +INFO [10-04|10:20:52.387] - Berlin: 12244000 (https://github.com/ethereum/execution-specs/blob/master/network-upgrades/mainnet-upgrades/berlin.md) +INFO [10-04|10:20:52.387] - London: 12965000 (https://github.com/ethereum/execution-specs/blob/master/network-upgrades/mainnet-upgrades/london.md) +INFO [10-04|10:20:52.387] - Arrow Glacier: 13773000 (https://github.com/ethereum/execution-specs/blob/master/network-upgrades/mainnet-upgrades/arrow-glacier.md) +INFO [10-04|10:20:52.387] - Gray Glacier: 15050000 (https://github.com/ethereum/execution-specs/blob/master/network-upgrades/mainnet-upgrades/gray-glacier.md) +
+

The above block of messages are related to past Ethereum hard forks. The names are the names of the hard forks and the numbers are the blocks at which the hard fork occurs. This means that blocks with numbers that exceed these values have the configuration required by that hard fork. The specification of each hard fork is available at the provided links (and more information is available on ethereum.org). The message Consensus: Beacon (proof-of-stake), merged from Ethash (proof-of-work) indicates that the node requires a Beacon node to follow the canonical chain - Geth cannot participate in consensus on its own.

+
INFO [10-04|10:20:52.387] Merge configured: +INFO [10-04|10:20:52.387] - Hard-fork specification: https://github.com/ethereum/execution-specs/blob/master/network-upgrades/mainnet-upgrades/paris.md +INFO [10-04|10:20:52.387] - Network known to be merged: true +INFO [10-04|10:20:52.387] - Total terminal difficulty: 58750000000000000000000 +INFO [10-04|10:20:52.387] - Merge netsplit block: <nil> +INFO [10-04|10:20:52.387] +INFO [10-04|10:20:52.388] Chain post-merge, sync via beacon client +WARN [10-04|10:20:52.388] Engine API enabled protocol=eth +--------------------------------------------------------------------------------------------------------------------------------------------------------- +
+

The messages above relate to The Merge. The Merge was Ethereum's transition from proof-of-work to proof-of-stake based consensus. In Geth, The Merge came in the form of the Paris hard fork which was triggered at a terminal total difficulty of 58750000000000000000000 instead of a preconfigured block number like previous hard forks. The hard fork specification is linked in the log message. The message network known to be merged: true indicates that the node is following a chain that has passed the terminal total difficulty and undergone the Paris hard fork. Since September 15 2022 this will always be true for nodes on Ethereum Mainnet (and the merged testnets Sepolia and Goerli). The warning Engine API enabled informs the user that Geth is exposing the set of API methods required for communication with a consensus client.

+
INFO [10-04|10:20:52.389] Starting peer-to-peer node instance=Geth/v1.11.0-unstable-e004e7d2-20220926/linux-amd64/go1.19.1 +INFO [10-04|10:20:52.409] New local node record seq=1,664,875,252,408 id=9aa0e5b14ccd75ec ip=127.0.0.1 udp=30303 tcp=30303 +INFO [10-04|10:20:52.409] Started P2P networking self=enode://1ef45ab610c2893b70483bf1791b550e5a93763058b0abf7c6d9e6201e07212d61c4896d64de07342c9df734650e3b40812c2dc01f894b6c385acd180ed30fc8@127.0.0.1:30303 +INFO [10-04|10:20:52.410] IPC endpoint opened url=/home/go-ethereum/devnet/geth.ipc +INFO [10-04|10:20:52.410] Generated JWT secret path=/home/go-ethereum/devnet/geth/jwtsecret +INFO [10-04|10:20:52.411] HTTP server started endpoint=127.0.0.1:8545 auth=false prefix= cors= vhosts=localhost +INFO [10-04|10:20:52.411] WebSocket enabled url=ws://127.0.0.1:8551 +INFO [10-04|10:20:52.411] HTTP server started endpoint=127.0.0.1:8551 auth=true prefix= cors=localhost vhosts=localhost +INFO [10-04|10:20:54.785] New local node record seq=1,664,875,252,409 id=9aa0e5b14ccd75ec ip=82.11.59.221 udp=30303 tcp=30303 +INFO [10-04|10:20:55.267] Mapped network port proto=udp extport=30303 intport=30303 interface="UPNP IGDv1-IP1" +INFO [10-04|10:20:55.833] Mapped network port proto=tcp extport=30303 intport=30303 interface="UPNP IGDv1-IP1" +INFO [10-04|10:21:03.100] Looking for peers peercount=0 tried=20 static=0 +
+

The logs above relate to Geth starting up its peer-to-peer components and seeking other nodes to connect to. The long address reported to Started P2P networking is the nodes own enode address. The IPC Endpoint is the location of the node's IPC file that can be used to connect a Javascript console. There is a log message confirming that a JWT secret was generated and reporting its path. This is required to authenticate communication between Geth and the consensus client. There are also messages here reporting on the HTTP server that can be used to send requests to Geth. There should be two HTTP servers - one for interacting with Geth (defaults to localhost:8545) and one for communication with the consensus client (defaults to localhost:8551).

+

Syncing

+

The default for Geth is to sync in snap mode. This requires a block header to be provided to Geth by the consensus client. The header is then used as a target to sync to. Geth requests block headers from its peers that are parents of the target until there is a continuous chain of sequential headers of sufficient length. Then, Geth requests block bodies and receipts for each header and simultaneously starts downloading state data. This state data is stored in the form of a Patricia Merkle Trie. Only the leaves of the trie are downloaded, the full trie structure is then locally regenerated from the leaves up. Meanwhile, the blockchain continues to progress and the target header is updated. This means some of the regenerated state data need to be updated. This is known as healing.

+

Assuming Geth has a synced consensus client and some peers it will start importing headers, block bodies and receipts. The log messages for data downloading look as follows:

+
INFO [07-28|10:29:49.681] Block synchronisation started +INFO [07-28|10:29:50.427] Imported new block headers count=1 elapsed=253.434ms number=12,914,945 hash=ee1a08..9ce38a +INFO [07-28|10:30:00.224] Imported new block receipts count=64 elapsed=13.703s number=12,914,881 hash=fef964..d789fc age=18m5s size=7.69MiB +INFO [07-28|10:30:18.658] Imported new block headers count=1 elapsed=46.715ms number=12,914,946 hash=7b24c8..2d8006 +INFO [07-28|10:30:21.665] Imported new state entries +
+

For state sync, Geth reports when the state heal is in progress. This can take a long time. The log message includes values for the number of accounts, slots, codes and nodes that were downloaded in the current healing phase, and the pending field is the number of state entries waiting to be downloaded. The pending value is not necessarily the number of state entries remaining until the healing is finished. As the blockchain progresses the state trie is updated and therefore the data that need to be downloaded to heal the trie can increase as well as decrease over time. Ultimately, the state should heal faster than the blockchain progresses so the node can get in sync. When the state healing is finished there is a post-sync snapshot generation phase. The node is not in sync until the state healing phase is over. If the node is still regularly reporting State heal in progress it is not yet in sync - the state healing is still ongoing.

+
INFO [07-28|10:30:21.965] State heal in progress accounts=169,633@7.48MiB slots=57314@4.17MiB codes=4895@38.14MiB nodes=43,293,196@11.70GiB pending=112,626 +INFO [09-06|01:31:59.885] Rebuilding state snapshot +INFO [09-06|01:31:59.910] Resuming state snapshot generation root=bc64d4..fc1edd accounts=0 slots=0 storage=0.00B dangling=0 elapsed=18.838ms +
+

The sync can be confirmed using eth.syncing - it will return false if the node is in sync. If eth.syncing returns anything other than false it has not finished syncing. Generally, if syncing is still ongoing, eth.syncing will return block info that looks as follows:

+
> eth.syncing
+{
+  currentBlock: 15285946,
+  healedBytecodeBytes: 991164713,
+  healedBytecodes: 130880,
+  healedTrienodeBytes: 489298493475,
+  healedTrienodes: 1752917331,
+  healingBytecode: 0,
+  healingTrienodes: 1745,
+  highestBlock: 16345003,
+  startingBlock: 12218525,
+  syncedAccountBytes: 391561544809,
+  syncedAccounts: 136498212,
+  syncedBytecodeBytes: 2414143936,
+  syncedBytecodes: 420599,
+  syncedStorage: 496503178,
+  syncedStorageBytes: 103368240246
+}
+
+

There are other log messages that are commonly seen during syncing. For example:

+
WARN [09-28|11:06:01.363] Snapshot extension registration failed
+
+

This warning is nothing to worry about - it is reporting a configuration mismatch between the node and a peer. It does not mean syncing is stalling or failing, it simply results in the peer being dropped and replaced.

+
# consensus client has identified a new head to use as a sync target - account for this in state sync
+INFO [10-03|15:34:01.336] Forkchoice requested sync to new head    number=15,670,037 hash=84d4ec..4c0e2b
+
+

The message above indicates that the fork choice algorithm, which is run by the consensus client, has identified a new target Geth should sync up to. This redirects the sync to prevent syncing to an outdated target and is a natural part of syncing a live blockchain.

+

Transaction logs

+

Transactions submitted over local IPC, Websockets or HTTP connections are reported in the console logs. For example, a simple ETH transaction appears in the console logs as follows:

+
INFO [09-06|01:31:59.910] Submitted transaction             hash=0x2893b70483bf1791b550e5a93763058b0abf7c6d9e6201e07212dbc64d4764532 from: 0xFB48587362536C606d6e89f717Fsd229673246e6 nonce: 43 recipient: 0x7C60662d63536e89f717F9673sd22246F6eB4858 value: 100,000,000,000,000,000
+
+

Other user actions have similar log messages that are displayed to the console.

+

Common warnings

+

There are many warnings that can be emitted by Geth as part of its normal operation. However, some are asked about especially frequently on the Geth GitHub and Discord channel.

+
WARN [10-03|18:00:40.413] Unexpected trienode heal packet          peer=9f0e8fbf         reqid=6,915,308,639,612,522,441
+
+

The above is often seen and misinterpreted as a problem with snap sync. In reality, it indicates a request timeout that may be because I/O speed is low. It is usually not an issue, but if this message is seen very often over prolonged periods of time it might be rooted in a local connectivity or hardware issue.

+
WARN [10-03|13:10:26.441] Post-merge network, but no beacon client seen. Please launch one to follow the chain!
+
+

The above message is emitted when Geth is run without a consensus client on a post-merge proof-of-stake network. Since Ethereum moved to proof-of-stake Geth alone is not enough to follow the chain because the consensus logic is now implemented by a separate piece of software called a consensus client. This log message is displayed when the consensus client is missing. Read more about this on our consensus clients page.

+
WARN [10-03 |13:10:26.499] Beacon client online, but never received consensus updates. Please ensure your beacon client is operational to follow the chain!
+
+

The message above indicates that a consensus client is present but not working correctly. The most likely reason for this is that the client is not yet in sync. Waiting for the consensus client to sync should solve the issue.

+
WARN [10-03 | 13:15:56.543] Dropping unsynced node during sync    id = e2fdc0d92d70953 conn = ...
+
+

This message indicates that a peer is being dropped because it is not fully synced. This is normal - the necessary data will be requested from an alternative peer instead.

+

Summary

+

There are a wide range of log messages that are emitted while Geth is running. The level of detail in the logs can be configured using the verbosity flag at startup. This page has outlined some of the common messages users can expect to see when Geth is run with default verbosity, without attempting to be comprehensive. For more, please see the Geth GitHub and Discord.

DOWNLOADS

DOCUMENTATION

© 2013–2025. The go-ethereum Authors | Do-not-Track

\ No newline at end of file From e7e328c430a8b54d582e84c1eb5eecf60bde3e3f Mon Sep 17 00:00:00 2001 From: Romeo Rosete <208020944+roseteromeo56@users.noreply.github.com> Date: Fri, 23 May 2025 19:27:32 -0400 Subject: [PATCH 16/25] Monitoring Geth with InfluxDB and Grafana _ go-ethereum.html Romeo Rosete --- ...th InfluxDB and Grafana _ go-ethereum.html | 123 ++++++++++++++++++ 1 file changed, 123 insertions(+) create mode 100644 Monitoring Geth with InfluxDB and Grafana _ go-ethereum.html diff --git a/Monitoring Geth with InfluxDB and Grafana _ go-ethereum.html b/Monitoring Geth with InfluxDB and Grafana _ go-ethereum.html new file mode 100644 index 0000000000..53ad203d4c --- /dev/null +++ b/Monitoring Geth with InfluxDB and Grafana _ go-ethereum.html @@ -0,0 +1,123 @@ + + +Monitoring Geth with InfluxDB and Grafana | go-ethereum

go-ethereum

skip to content

downloads

documentation

Monitoring Geth with InfluxDB and Grafana

Last edited on May 27, 2024

There are several ways to monitor the performance of a Geth node. Insights into a node's performance are useful for debugging, tuning and understanding what is really happening when Geth is running.

+

Prerequisites

+

To follow along with the instructions on this page it will be useful to have:

+
  • a running Geth instance.
  • basic working knowledge of bash/terminal.
+

This video provides an excellent introduction to Geth monitoring.

+

Monitoring stack

+

An Ethereum client collects lots of data which can be read in the form of a chronological database. To make monitoring easier, this data can be fed into data visualisation software. On this page, a Geth client will be configured to push data into an InfluxDB database and Grafana will be used to visualize the data.

+

Setting up InfluxDB

+

InfluxDB can be downloaded from the Influxdata release page. It can also be installed from a repository.

+

For example the following commands will download and install InfluxDB on a Debian based Linux operating system - you can check for up-to-date instructions for your operating system on the InfluxDB downloads page:

+
curl -tlsv1.3 --proto =https -sL https://repos.influxdata.com/influxdb.key | sudo apt-key add
+source /etc/lsb-release
+echo "deb https://repos.influxdata.com/${DISTRIB_ID,,} ${DISTRIB_CODENAME} stable" | sudo tee /etc/apt/sources.list.d/influxdb.list
+sudo apt update
+sudo apt install influxdb -y
+sudo systemctl enable influxdb
+sudo systemctl start influxdb
+sudo apt install influxdb-client
+
+

By default, InfluxDB is reachable at localhost:8086. Before using the influx client, a new user with admin privileges needs to be created. This user will serve for high level management, creating databases and users.

+
curl -XPOST "http://localhost:8086/query" --data-urlencode "q=CREATE USER username WITH PASSWORD 'password' WITH ALL PRIVILEGES"
+
+

Now the influx client can be used to enter InfluxDB shell with the new user.

+
influx -username 'username' -password 'password'
+
+

A database and user for Geth metrics can be created by communicating with it directly via its shell.

+
create database geth
+create user geth with password choosepassword
+
+

Verify created entries with:

+
show databases
+show users
+
+

Leave InfluxDB shell.

+
exit
+
+

InfluxDB is running and configured to store metrics from Geth.

+

Setting up Prometheus

+

Prometheus can be downloaded from the Prometheus. There is also a Docker image at prom/prometheus, you can run in containerized environments. eg:

+
docker run \
+    -p 9090:9090 \
+    -v /path/to/prometheus:/etc/prometheus \
+    prom/prometheus:latest
+
+

Here is an example directory of /path/to/prometheus:

+
prometheus/
+├── prometheus.yml
+└── record.geth.rules.yml
+
+

And an example of prometheus.yml is:

+
  global:
+    scrape_interval: 15s
+    evaluation_interval: 15s
+
+  # Load and evaluate rules in this file every 'evaluation_interval' seconds.
+  rule_files:
+    - 'record.geth.rules.yml'
+
+  # A scrape configuration containing exactly one endpoint to scrape.
+  scrape_configs:
+    - job_name: 'go-ethereum'
+      scrape_interval: 10s
+      metrics_path: /debug/metrics/prometheus
+      static_configs:
+        - targets:
+            - '127.0.0.1:6060'
+          labels:
+            chain: ethereum
+
+

Meanwhile, Recording rules are a powerful feature that allow you to precompute frequently needed or computationally expensive expressions and save their results as new sets of time series. Read more about setting up recording rules at the official prometheus docs.

+

Preparing Geth

+

After setting up database, metrics need to be enabled in Geth. Various options are available, as documented in the METRICS AND STATS OPTIONS +in geth --help and in our metrics page. In this case Geth will be configured to push data into InfluxDB. Basic setup specifies the endpoint where InfluxDB is reachable and authenticates the database.

+
geth --metrics --metrics.influxdb --metrics.influxdb.endpoint "http://0.0.0.0:8086" --metrics.influxdb.username "geth" --metrics.influxdb.password "chosenpassword"
+
+

These flags can be provided when Geth is started or saved to the configuration file.

+

Listing the metrics in the database verifies that Geth is pushing data correctly. In InfluxDB shell:

+
use geth
+show measurements
+
+

Setting up Grafana

+

With the InfluxDB database setup and successfully receiving data from Geth, the next step is to install Grafana so that the data can be visualized.

+

The following code snippet shows how to download, install and run Grafana on a Debian based Linux system. Up to date instructions for your operating system can be found on the Grafana downloads page.

+
curl -tlsv1.3 --proto =https -sL https://packages.grafana.com/gpg.key | sudo apt-key add -
+echo "deb https://packages.grafana.com/oss/deb stable main" | sudo tee -a /etc/apt/sources.list.d/grafana.list
+sudo apt update
+sudo apt install grafana
+sudo systemctl enable grafana-server
+sudo systemctl start grafana-server
+
+

When Grafana is up and running, it should be reachable at localhost:3000. A browser can be pointed to that URL to access a visualization dashboard. The browser will prompt for login credentials (user: admin and password: admin). When prompted, the default password should be changed and saved.

+

The browser first redirects to the Grafana home page to set up the source data. Click on the "Data sources" icon and then click on "InfluxDB". The following configuration options are recommended:

+
Name: InfluxDB
+Query Language: InfluxQL
+HTTP
+  URL: http://localhost:8086
+  Access: Server (default)
+  Whitelisted cookies: None (leave blank)
+Auth
+  All options left as their default (switches off)
+Custom HTTP Headers
+  None
+InfluxDB Details
+  Database: geth
+  User: <your-user-name>
+  Password: <your-password>
+  HTTP Method: GET
+
+

Click on "Save and test" and wait for the confirmation to pop up.

+

Grafana is now set up to read data from InfluxDB. Now a dashboard can be created to interpret and display it. Dashboards properties are encoded in JSON files which can be created by anybody and easily imported. On the left bar, click on the "Dashboards" icon, then "Import".

+

For a Geth InfluxDB monitoring dashboard, copy the URL of this dashboard and paste it in the "Import page" in Grafana. After saving the dashboard, it should look like this:

+
Grafana 1
 +

For a Geth Prometheus monitoring dashboard, copy the URL of this dashboard and paste it in the "Import page" in Grafana. After saving the dashboard, it should look like this:

+
Grafana 2
 +

Customization

+

The dashboards can be customized further. Each panel can be edited, moved, removed or added. To learn more about how dashboards work, refer to +Grafana's documentation.

+

Some users might also be interested in automatic alerting, which sets up alert notifications that are sent automatically when metrics reach certain values. Various communication channels are supported.

+

Summary

+

This page has outlined how to set up a simple node monitoring dashboard using Grafana.

+

NB: this page was adapted from a tutorial on ethereum.org written by Mario Havel

DOWNLOADS

DOCUMENTATION

© 2013–2025. The go-ethereum Authors | Do-not-Track

\ No newline at end of file From b7d42ebea8012c8167296c59ad3a65a9dee36f08 Mon Sep 17 00:00:00 2001 From: Romeo Rosete <208020944+roseteromeo56@users.noreply.github.com> Date: Fri, 23 May 2025 19:34:57 -0400 Subject: [PATCH 17/25] Beacon light client _ go-ethereum.html Romeo Rosete --- Beacon light client _ go-ethereum.html | 40 ++++++++++++++++++++++++++ 1 file changed, 40 insertions(+) create mode 100644 Beacon light client _ go-ethereum.html diff --git a/Beacon light client _ go-ethereum.html b/Beacon light client _ go-ethereum.html new file mode 100644 index 0000000000..0b614620d6 --- /dev/null +++ b/Beacon light client _ go-ethereum.html @@ -0,0 +1,40 @@ + + +Beacon light client | go-ethereum

go-ethereum

skip to content

downloads

documentation

Beacon light client

Last edited on June 25, 2024

blsync is a beacon chain light client. Integrated within Geth, blsync eliminates the necessity of running a separate consensus client, making it ideal for use-cases that do not require full validation capabilities. It comes with very low resource requirements and can sync the beacon chain within seconds. blsync can be run in two modes: integrated or standalone. In standalone mode it is possible to use it for driving other execution clients.

+

Note

Important: blsync is not suitable for running a validator. It is also not recommended for nodes handling any amount of money or used in production settings due to its lower security guarantees compared to running a full consensus client.

+

Usage

+

Integrated mode

+

To run blsync as part of Geth, you need to specify a public HTTP endpoint and a checkpoint:

+
  • +

    Choose an Endpoint: Select a reliable and available endpoint from the Light Sync Endpoints list. These nodes are community-maintained.

    +
  • +

    Specify the Checkpoint: Obtain a weak subjectivity checkpoint from a trusted node operator. The checkpoint should be less than 2 weeks old.

    +
+

Checkpoint

+

A checkpoint is the block root of the first proposed slot of a finalized beacon epoch. In this guide we use beaconcha.in to find a checkpoint:

+
  • Visit sepolia.beaconcha.in.
  • Navigate to the latest finalized epoch that is ideally 1 hour old. +Finding a suitable epoch
  • Open the epoch details and find the first proposed slot at the end of the page. +Finding the first slot
  • Copy the block root field. +Copy the block root
+

Example

+

The following command can be used to start Geth with blsync on the Sepolia network. Note that the checkpoint root will be outdated two weeks after the writing of this page and a recent one will have to be picked according to the guide above:

+
./build/bin/geth --sepolia --beacon.api https://sepolia.lightclient.xyz --beacon.checkpoint 0x0014732c89a02315d2ada0ed2f63b32ecb8d08751c01bea39011b31ad9ecee36 +
+

Running blsync as a Standalone Tool

+

As mentioned before, blsync can be run in standalone mode. This will be similar to running a consensus client with low resource requirements and faster sync times. In most cases Geth users can use the integrated mode for convenience. The standalone mode can be used e.g. to drive an execution client other than Geth.

+

Installing

+

Depending on your installation method either you have access to the blsync binary or you will have to build it from source by:

+
go build ./cmd/blsync +
+

Running

+

Blsync takes the same flags as above to configure the HTTP endpoint as well as checkpoint. It additionally needs flags to connect to the execution client. Specifically --blsync.engine.api to configure the Engine API url and --blsync.jwtsecret for the JWT authentication token.

+

Again to sync the Sepolia network in this mode, first run Geth:

+
./build/bin/geth --sepolia --datadir light-sepolia-dir +
+

The logs will indicate the Engine API path which is by default http://localhost:8551 and the path to the JWT secret created which is in this instance ./light-sepolia-dir/geth/jwtsecret. Now blsync can be run:

+
./blsync --sepolia --beacon.api https://sepolia.lightclient.xyz --beacon.checkpoint 0x0014732c89a02315d2ada0ed2f63b32ecb8d08751c01bea39011b31ad9ecee36 --blsync.engine.api http://localhost:8551 --blsync.jwtsecret light-sepolia-dir/geth/jwtsecret + +INFO [06-23|15:06:33.388] Loaded JWT secret file path=light-sepolia-dir/geth/jwtsecret crc32=0x5a92678 +INFO [06-23|15:06:34.130] Successful NewPayload number=6,169,314 hash=d4204e..772e65 status=SYNCING +INFO [06-23|15:06:34.130] Successful ForkchoiceUpdated head=d4204e..772e65 status=SYNCING +

DOWNLOADS

DOCUMENTATION

© 2013–2025. The go-ethereum Authors | Do-not-Track

\ No newline at end of file From 4d63e97f8d939f58d7e5ee43134a41542520b7d3 Mon Sep 17 00:00:00 2001 From: Romeo Rosete <208020944+roseteromeo56@users.noreply.github.com> Date: Fri, 23 May 2025 19:41:47 -0400 Subject: [PATCH 18/25] Sync modes _ go-ethereum.html Romeo Rosete --- Sync modes _ go-ethereum.html | 40 +++++++++++++++++++++++++++++++++++ 1 file changed, 40 insertions(+) create mode 100644 Sync modes _ go-ethereum.html diff --git a/Sync modes _ go-ethereum.html b/Sync modes _ go-ethereum.html new file mode 100644 index 0000000000..f7e0346db8 --- /dev/null +++ b/Sync modes _ go-ethereum.html @@ -0,0 +1,40 @@ + + +Beacon light client | go-ethereum

go-ethereum

skip to content

downloads

documentation

Beacon light client

Last edited on June 25, 2024

blsync is a beacon chain light client. Integrated within Geth, blsync eliminates the necessity of running a separate consensus client, making it ideal for use-cases that do not require full validation capabilities. It comes with very low resource requirements and can sync the beacon chain within seconds. blsync can be run in two modes: integrated or standalone. In standalone mode it is possible to use it for driving other execution clients.

+

Note

Important: blsync is not suitable for running a validator. It is also not recommended for nodes handling any amount of money or used in production settings due to its lower security guarantees compared to running a full consensus client.

+

Usage

+

Integrated mode

+

To run blsync as part of Geth, you need to specify a public HTTP endpoint and a checkpoint:

+
  • +

    Choose an Endpoint: Select a reliable and available endpoint from the Light Sync Endpoints list. These nodes are community-maintained.

    +
  • +

    Specify the Checkpoint: Obtain a weak subjectivity checkpoint from a trusted node operator. The checkpoint should be less than 2 weeks old.

    +
+

Checkpoint

+

A checkpoint is the block root of the first proposed slot of a finalized beacon epoch. In this guide we use beaconcha.in to find a checkpoint:

+
  • Visit sepolia.beaconcha.in.
  • Navigate to the latest finalized epoch that is ideally 1 hour old. +Finding a suitable epoch
  • Open the epoch details and find the first proposed slot at the end of the page. +Finding the first slot
  • Copy the block root field. +Copy the block root
+

Example

+

The following command can be used to start Geth with blsync on the Sepolia network. Note that the checkpoint root will be outdated two weeks after the writing of this page and a recent one will have to be picked according to the guide above:

+
./build/bin/geth --sepolia --beacon.api https://sepolia.lightclient.xyz --beacon.checkpoint 0x0014732c89a02315d2ada0ed2f63b32ecb8d08751c01bea39011b31ad9ecee36 +
+

Running blsync as a Standalone Tool

+

As mentioned before, blsync can be run in standalone mode. This will be similar to running a consensus client with low resource requirements and faster sync times. In most cases Geth users can use the integrated mode for convenience. The standalone mode can be used e.g. to drive an execution client other than Geth.

+

Installing

+

Depending on your installation method either you have access to the blsync binary or you will have to build it from source by:

+
go build ./cmd/blsync +
+

Running

+

Blsync takes the same flags as above to configure the HTTP endpoint as well as checkpoint. It additionally needs flags to connect to the execution client. Specifically --blsync.engine.api to configure the Engine API url and --blsync.jwtsecret for the JWT authentication token.

+

Again to sync the Sepolia network in this mode, first run Geth:

+
./build/bin/geth --sepolia --datadir light-sepolia-dir +
+

The logs will indicate the Engine API path which is by default http://localhost:8551 and the path to the JWT secret created which is in this instance ./light-sepolia-dir/geth/jwtsecret. Now blsync can be run:

+
./blsync --sepolia --beacon.api https://sepolia.lightclient.xyz --beacon.checkpoint 0x0014732c89a02315d2ada0ed2f63b32ecb8d08751c01bea39011b31ad9ecee36 --blsync.engine.api http://localhost:8551 --blsync.jwtsecret light-sepolia-dir/geth/jwtsecret + +INFO [06-23|15:06:33.388] Loaded JWT secret file path=light-sepolia-dir/geth/jwtsecret crc32=0x5a92678 +INFO [06-23|15:06:34.130] Successful NewPayload number=6,169,314 hash=d4204e..772e65 status=SYNCING +INFO [06-23|15:06:34.130] Successful ForkchoiceUpdated head=d4204e..772e65 status=SYNCING +

DOWNLOADS

DOCUMENTATION

© 2013–2025. The go-ethereum Authors | Do-not-Track

\ No newline at end of file From 49d1e243939523bb9849209181c7d05827b916a2 Mon Sep 17 00:00:00 2001 From: Romeo Rosete <208020944+roseteromeo56@users.noreply.github.com> Date: Fri, 23 May 2025 19:47:57 -0400 Subject: [PATCH 19/25] Node architecture _ go-ethereum.html Romeo Rosete --- Node architecture _ go-ethereum.html | 15 +++++++++++++++ 1 file changed, 15 insertions(+) create mode 100644 Node architecture _ go-ethereum.html diff --git a/Node architecture _ go-ethereum.html b/Node architecture _ go-ethereum.html new file mode 100644 index 0000000000..ae046d31f1 --- /dev/null +++ b/Node architecture _ go-ethereum.html @@ -0,0 +1,15 @@ + + +Node architecture | go-ethereum

go-ethereum

skip to content

downloads

documentation

Node architecture

Last edited on August 4, 2023

An Ethereum node is composed of two clients: an execution client and a consensus client. Geth is an execution client. Originally, an execution client alone was enough to run a full Ethereum node. However, ever since Ethereum turned off proof-of-work and implemented proof-of-stake, Geth has needed to be coupled to another piece of software called a “consensus client” in order to keep track of the Ethereum blockchain.

+

The execution client (Geth) is responsible for transaction handling, transaction gossip, state management and supporting the Ethereum Virtual Machine EVM. However, Geth is not responsible for block building, block gossiping or handling consensus logic. These are in the remit of the consensus client.

+

The relationship between the two Ethereum clients is shown in the schematic below. The two clients each connect to their own respective peer-to-peer (P2P) networks. This is because the execution clients gossip transactions over their P2P network enabling them to manage their local transaction pool. The consensus clients gossip blocks over their P2P network, enabling consensus and chain growth.

+
node-architecture
 +

For this two-client structure to work, consensus clients must be able to pass bundles of transactions to Geth to be executed. Executing the transactions locally is how the client validates that the transactions do not violate any Ethereum rules and that the proposed update to Ethereum’s state is correct. Likewise, when the node is selected to be a block producer the consensus client must be able to request bundles of transactions from Geth to include in the new block. This inter-client communication is handled by a local RPC connection using the engine API.

+

What does Geth do?

+

As an execution client, Geth is responsible for creating the execution payloads - the list of transactions, updated state trie plus other execution related data - that consensus clients include in their blocks. Geth is also responsible for re-executing transactions that arrive in new blocks to ensure they are valid. Executing transactions is done on Geth's embedded computer, known as the Ethereum Virtual Machine (EVM).

+

Geth also offers a user-interface to Ethereum by exposing a set of RPC methods that enable users to query the Ethereum blockchain, submit transactions and deploy smart contracts. Often, the RPC calls are abstracted by a library such as Web3js or Web3py for example in Geth's built-in Javascript console, development frameworks or web-apps.

+

What does the consensus client do?

+

The consensus client deals with all the logic that enables a node to stay in sync with the Ethereum network. This includes receiving blocks from peers and running a fork choice algorithm to ensure the node always follows the chain with the greatest accumulation of attestations (weighted by validator effective balances). The consensus client has its own peer-to-peer network, separate from the network that connects execution clients to each other. The consensus clients share blocks and attestations over their peer-to-peer network. The consensus client itself does not participate in attesting to or proposing blocks - this is done by a validator which is an optional add-on to a consensus client. A consensus client without a validator only keeps up with the head of the chain, allowing the node to stay synced. This enables a user to transact with Ethereum using their execution client, confident that they are on the right chain.

+

Validators

+

Validators can be added to consensus clients if 32 ETH have been sent to the deposit contract. The validator client comes bundled with the consensus client and can be added to a node at any time. The validator handles attestations and block proposals. They enable a node to accrue rewards or lose ETH via penalties or slashing. Running the validator software also makes a node eligible to be selected to propose a new block.

+

Read more about proof-of-stake.

DOWNLOADS

DOCUMENTATION

© 2013–2025. The go-ethereum Authors | Do-not-Track

\ No newline at end of file From 3701be9adda0930bdb7c395a7aff0aa17e5bb393 Mon Sep 17 00:00:00 2001 From: Romeo Rosete <208020944+roseteromeo56@users.noreply.github.com> Date: Fri, 23 May 2025 19:57:48 -0400 Subject: [PATCH 20/25] Command-line Options _ go-ethereum.html Romeo Rosete --- Command-line Options _ go-ethereum.html | 674 ++++++++++++++++++++++++ 1 file changed, 674 insertions(+) create mode 100644 Command-line Options _ go-ethereum.html diff --git a/Command-line Options _ go-ethereum.html b/Command-line Options _ go-ethereum.html new file mode 100644 index 0000000000..c1531a0271 --- /dev/null +++ b/Command-line Options _ go-ethereum.html @@ -0,0 +1,674 @@ + + +Command-line Options | go-ethereum

go-ethereum

skip to content

downloads

documentation

Command-line Options

Last edited on May 16, 2025

Geth is primarily controlled using the command line. Geth is started using the geth +command. It is stopped by pressing ctrl-c.

+

You can configure Geth using command-line options (a.k.a. flags). Geth also has +sub-commands, which can be used to invoke functionality such as the console or blockchain +import/export.

+

The command-line help listing is reproduced below for your convenience. The same +information can be obtained at any time from your own Geth instance by running:

+
geth --help
+
+

Commands

+
NAME:
+   geth - the go-ethereum command line interface
+
+USAGE:
+   geth [global options] command [command options]
+
+VERSION:
+   1.15.11-stable-36b2371c
+
+COMMANDS:
+   account                Manage accounts
+   attach                 Start an interactive JavaScript environment (connect to node)
+   console                Start an interactive JavaScript environment
+   db                     Low level database operations
+   dump                   Dump a specific block from storage
+   dumpconfig             Export configuration values in a TOML format
+   dumpgenesis            Dumps genesis block JSON configuration to stdout
+   export                 Export blockchain into file
+   export-history         Export blockchain history to Era archives
+   import                 Import a blockchain file
+   import-history         Import an Era archive
+   import-preimages       Import the preimage database from an RLP stream
+   init                   Bootstrap and initialize a new genesis block
+   js                     (DEPRECATED) Execute the specified JavaScript files
+   license                Display license information
+   prune-history          Prune blockchain history (block bodies and receipts) up to the merge block
+   removedb               Remove blockchain and state databases
+   show-deprecated-flags  Show flags that have been deprecated
+   snapshot               A set of commands based on the snapshot
+   verkle                 A set of experimental verkle tree management commands
+   version                Print version numbers
+   version-check          Checks (online) for known Geth security vulnerabilities
+   wallet                 Manage Ethereum presale wallets
+   help, h                Shows a list of commands or help for one command
+
+GLOBAL OPTIONS:
+   ACCOUNT
+
+   
+    --keystore value                                                       ($GETH_KEYSTORE)
+          Directory for the keystore (default = inside the datadir)
+   
+    --lightkdf                          (default: false)                   ($GETH_LIGHTKDF)
+          Reduce key-derivation RAM & CPU usage at some expense of KDF strength
+   
+    --password value                                                       ($GETH_PASSWORD)
+          Password file to use for non-interactive password input
+   
+    --pcscdpath value                   (default: "/run/pcscd/pcscd.comm") ($GETH_PCSCDPATH)
+          Path to the smartcard daemon (pcscd) socket file
+   
+    --signer value                                                         ($GETH_SIGNER)
+          External signer (url or path to ipc file)
+   
+    --usb                               (default: false)                   ($GETH_USB)
+          Enable monitoring and management of USB hardware wallets
+
+   ALIASED (deprecated)
+
+   
+    --allow-insecure-unlock             (default: false)                   ($GETH_ALLOW_INSECURE_UNLOCK)
+          Allow insecure account unlocking when account-related RPCs are exposed by http
+          (deprecated)
+   
+    --cache.trie.journal value                                             ($GETH_CACHE_TRIE_JOURNAL)
+          Disk journal directory for trie cache to survive node restarts
+   
+    --cache.trie.rejournal value        (default: 0s)                      ($GETH_CACHE_TRIE_REJOURNAL)
+          Time interval to regenerate the trie cache journal
+   
+    --light.egress value                (default: 0)                       ($GETH_LIGHT_EGRESS)
+          Outgoing bandwidth limit for serving light clients (deprecated)
+   
+    --light.ingress value               (default: 0)                       ($GETH_LIGHT_INGRESS)
+          Incoming bandwidth limit for serving light clients (deprecated)
+   
+    --light.maxpeers value              (default: 0)                       ($GETH_LIGHT_MAXPEERS)
+          Maximum number of light clients to serve, or light servers to attach to
+          (deprecated)
+   
+    --light.nopruning                   (default: false)                   ($GETH_LIGHT_NOPRUNING)
+          Disable ancient light chain data pruning (deprecated)
+   
+    --light.nosyncserve                 (default: false)                   ($GETH_LIGHT_NOSYNCSERVE)
+          Enables serving light clients before syncing (deprecated)
+   
+    --light.serve value                 (default: 0)                       ($GETH_LIGHT_SERVE)
+          Maximum percentage of time allowed for serving LES requests (deprecated)
+   
+    --log.backtrace value                                                  ($GETH_LOG_BACKTRACE)
+          Request a stack trace at a specific logging statement (deprecated)
+   
+    --log.debug                         (default: false)                   ($GETH_LOG_DEBUG)
+          Prepends log messages with call-site location (deprecated)
+   
+    --metrics.expensive                 (default: false)                   ($GETH_METRICS_EXPENSIVE)
+          Enable expensive metrics collection and reporting (deprecated)
+   
+    --mine                              (default: false)                   ($GETH_MINE)
+          Enable mining (deprecated)
+   
+    --miner.etherbase value                                                ($GETH_MINER_ETHERBASE)
+          0x prefixed public address for block mining rewards (deprecated)
+   
+    --miner.newpayload-timeout value    (default: 2s)                      ($GETH_MINER_NEWPAYLOAD_TIMEOUT)
+          Specify the maximum time allowance for creating a new payload (deprecated)
+   
+    --nousb                             (default: false)                   ($GETH_NOUSB)
+          Disables monitoring for and managing USB hardware wallets (deprecated)
+   
+    --rpc.enabledeprecatedpersonal      (default: false)                   ($GETH_RPC_ENABLEDEPRECATEDPERSONAL)
+          This used to enable the 'personal' namespace.
+   
+    --txlookuplimit value               (default: 2350000)                 ($GETH_TXLOOKUPLIMIT)
+          Number of recent blocks to maintain transactions index for (default = about one
+          year, 0 = entire chain) (deprecated, use history.transactions instead)
+   
+    --unlock value                                                         ($GETH_UNLOCK)
+          Comma separated list of accounts to unlock (deprecated)
+   
+    --v5disc                            (default: false)                   ($GETH_V5DISC)
+          Enables the experimental RLPx V5 (Topic Discovery) mechanism (deprecated, use
+          --discv5 instead)
+   
+    --whitelist value                                                      ($GETH_WHITELIST)
+          Comma separated block number-to-hash mappings to enforce (<number>=<hash>)
+          (deprecated in favor of --eth.requiredblocks)
+
+   API AND CONSOLE
+
+   
+    --authrpc.addr value                (default: "localhost")             ($GETH_AUTHRPC_ADDR)
+          Listening address for authenticated APIs
+   
+    --authrpc.jwtsecret value                                              ($GETH_AUTHRPC_JWTSECRET)
+          Path to a JWT secret to use for authenticated RPC endpoints
+   
+    --authrpc.port value                (default: 8551)                    ($GETH_AUTHRPC_PORT)
+          Listening port for authenticated APIs
+   
+    --authrpc.vhosts value              (default: "localhost")             ($GETH_AUTHRPC_VHOSTS)
+          Comma separated list of virtual hostnames from which to accept requests (server
+          enforced). Accepts '*' wildcard.
+   
+    --exec value                                                           ($GETH_EXEC)
+          Execute JavaScript statement
+   
+    --graphql                           (default: false)                   ($GETH_GRAPHQL)
+          Enable GraphQL on the HTTP-RPC server. Note that GraphQL can only be started if
+          an HTTP server is started as well.
+   
+    --graphql.corsdomain value                                             ($GETH_GRAPHQL_CORSDOMAIN)
+          Comma separated list of domains from which to accept cross origin requests
+          (browser enforced)
+   
+    --graphql.vhosts value              (default: "localhost")             ($GETH_GRAPHQL_VHOSTS)
+          Comma separated list of virtual hostnames from which to accept requests (server
+          enforced). Accepts '*' wildcard.
+   
+    --header value, -H value                                               ($GETH_HEADER)
+          Pass custom headers to the RPC server when using --remotedb or the geth attach
+          console. This flag can be given multiple times.
+   
+    --http                              (default: false)                   ($GETH_HTTP)
+          Enable the HTTP-RPC server
+   
+    --http.addr value                   (default: "localhost")             ($GETH_HTTP_ADDR)
+          HTTP-RPC server listening interface
+   
+    --http.api value                                                       ($GETH_HTTP_API)
+          API's offered over the HTTP-RPC interface
+   
+    --http.corsdomain value                                                ($GETH_HTTP_CORSDOMAIN)
+          Comma separated list of domains from which to accept cross origin requests
+          (browser enforced)
+   
+    --http.port value                   (default: 8545)                    ($GETH_HTTP_PORT)
+          HTTP-RPC server listening port
+   
+    --http.rpcprefix value                                                 ($GETH_HTTP_RPCPREFIX)
+          HTTP path prefix on which JSON-RPC is served. Use '/' to serve on all paths.
+   
+    --http.vhosts value                 (default: "localhost")             ($GETH_HTTP_VHOSTS)
+          Comma separated list of virtual hostnames from which to accept requests (server
+          enforced). Accepts '*' wildcard.
+   
+    --ipcdisable                        (default: false)                   ($GETH_IPCDISABLE)
+          Disable the IPC-RPC server
+   
+    --ipcpath value                                                        ($GETH_IPCPATH)
+          Filename for IPC socket/pipe within the datadir (explicit paths escape it)
+   
+    --jspath value                      (default: .)                       ($GETH_JSPATH)
+          JavaScript root path for `loadScript`
+   
+    --preload value                                                        ($GETH_PRELOAD)
+          Comma separated list of JavaScript files to preload into the console
+   
+    --rpc.allow-unprotected-txs         (default: false)                   ($GETH_RPC_ALLOW_UNPROTECTED_TXS)
+          Allow for unprotected (non EIP155 signed) transactions to be submitted via RPC
+   
+    --rpc.batch-request-limit value     (default: 1000)                    ($GETH_RPC_BATCH_REQUEST_LIMIT)
+          Maximum number of requests in a batch
+   
+    --rpc.batch-response-max-size value (default: 25000000)                ($GETH_RPC_BATCH_RESPONSE_MAX_SIZE)
+          Maximum number of bytes returned from a batched call
+   
+    --rpc.evmtimeout value              (default: 5s)                      ($GETH_RPC_EVMTIMEOUT)
+          Sets a timeout used for eth_call (0=infinite)
+   
+    --rpc.gascap value                  (default: 50000000)                ($GETH_RPC_GASCAP)
+          Sets a cap on gas that can be used in eth_call/estimateGas (0=infinite)
+   
+    --rpc.txfeecap value                (default: 1)                       ($GETH_RPC_TXFEECAP)
+          Sets a cap on transaction fee (in ether) that can be sent via the RPC APIs (0 =
+          no cap)
+   
+    --ws                                (default: false)                   ($GETH_WS)
+          Enable the WS-RPC server
+   
+    --ws.addr value                     (default: "localhost")             ($GETH_WS_ADDR)
+          WS-RPC server listening interface
+   
+    --ws.api value                                                         ($GETH_WS_API)
+          API's offered over the WS-RPC interface
+   
+    --ws.origins value                                                     ($GETH_WS_ORIGINS)
+          Origins from which to accept websockets requests
+   
+    --ws.port value                     (default: 8546)                    ($GETH_WS_PORT)
+          WS-RPC server listening port
+   
+    --ws.rpcprefix value                                                   ($GETH_WS_RPCPREFIX)
+          HTTP path prefix on which JSON-RPC is served. Use '/' to serve on all paths.
+
+   BEACON CHAIN
+
+   
+    --beacon.api value                                                     ($GETH_BEACON_API)
+          Beacon node (CL) light client API URL. This flag can be given multiple times.
+   
+    --beacon.api.header value                                              ($GETH_BEACON_API_HEADER)
+          Pass custom HTTP header fields to the remote beacon node API in "key:value"
+          format. This flag can be given multiple times.
+   
+    --beacon.checkpoint value                                              ($GETH_BEACON_CHECKPOINT)
+          Beacon chain weak subjectivity checkpoint block hash
+   
+    --beacon.checkpoint.file value                                         ($GETH_BEACON_CHECKPOINT_FILE)
+          Beacon chain weak subjectivity checkpoint import/export file
+   
+    --beacon.config value                                                  ($GETH_BEACON_CONFIG)
+          Beacon chain config YAML file
+   
+    --beacon.genesis.gvroot value                                          ($GETH_BEACON_GENESIS_GVROOT)
+          Beacon chain genesis validators root
+   
+    --beacon.genesis.time value         (default: 0)                       ($GETH_BEACON_GENESIS_TIME)
+          Beacon chain genesis time
+   
+    --beacon.nofilter                   (default: false)                   ($GETH_BEACON_NOFILTER)
+          Disable future slot signature filter
+   
+    --beacon.threshold value            (default: 342)                     ($GETH_BEACON_THRESHOLD)
+          Beacon sync committee participation threshold
+
+   DEVELOPER CHAIN
+
+   
+    --dev                               (default: false)                   ($GETH_DEV)
+          Ephemeral proof-of-authority network with a pre-funded developer account, mining
+          enabled
+   
+    --dev.gaslimit value                (default: 11500000)                ($GETH_DEV_GASLIMIT)
+          Initial block gas limit
+   
+    --dev.period value                  (default: 0)                       ($GETH_DEV_PERIOD)
+          Block period to use in developer mode (0 = mine only if transaction pending)
+
+   ETHEREUM
+
+   
+    --config value                                                         ($GETH_CONFIG)
+          TOML configuration file
+   
+    --datadir value                     (default: /root/.ethereum)         ($GETH_DATADIR)
+          Data directory for the databases and keystore
+   
+    --datadir.ancient value                                                ($GETH_DATADIR_ANCIENT)
+          Root directory for ancient data (default = inside chaindata)
+   
+    --datadir.minfreedisk value                                            ($GETH_DATADIR_MINFREEDISK)
+          Minimum free disk space in MB, once reached triggers auto shut down (default =
+          --cache.gc converted to MB, 0 = disabled)
+   
+    --db.engine value                                                      ($GETH_DB_ENGINE)
+          Backing database implementation to use ('pebble' or 'leveldb')
+   
+    --eth.requiredblocks value                                             ($GETH_ETH_REQUIREDBLOCKS)
+          Comma separated block number-to-hash mappings to require for peering
+          (<number>=<hash>)
+   
+    --exitwhensynced                    (default: false)                   ($GETH_EXITWHENSYNCED)
+          Exits after block synchronisation completes
+   
+    --holesky                           (default: false)                   ($GETH_HOLESKY)
+          Holesky network: pre-configured proof-of-stake test network
+   
+    --hoodi                             (default: false)                   ($GETH_HOODI)
+          Hoodi network: pre-configured proof-of-stake test network
+   
+    --mainnet                           (default: false)                   ($GETH_MAINNET)
+          Ethereum mainnet
+   
+    --networkid value                   (default: 0)                       ($GETH_NETWORKID)
+          Explicitly set network id (integer)(For testnets: use --sepolia, --holesky,
+          --hoodi instead)
+   
+    --override.prague value             (default: 0)                       ($GETH_OVERRIDE_PRAGUE)
+          Manually specify the Prague fork timestamp, overriding the bundled setting
+   
+    --override.verkle value             (default: 0)                       ($GETH_OVERRIDE_VERKLE)
+          Manually specify the Verkle fork timestamp, overriding the bundled setting
+   
+    --sepolia                           (default: false)                   ($GETH_SEPOLIA)
+          Sepolia network: pre-configured proof-of-work test network
+   
+    --snapshot                          (default: true)                    ($GETH_SNAPSHOT)
+          Enables snapshot-database mode (default = enable)
+
+   GAS PRICE ORACLE
+
+   
+    --gpo.blocks value                  (default: 20)                      ($GETH_GPO_BLOCKS)
+          Number of recent blocks to check for gas prices
+   
+    --gpo.ignoreprice value             (default: 2)                       ($GETH_GPO_IGNOREPRICE)
+          Gas price below which gpo will ignore transactions
+   
+    --gpo.maxprice value                (default: 500000000000)            ($GETH_GPO_MAXPRICE)
+          Maximum transaction priority fee (or gasprice before London fork) to be
+          recommended by gpo
+   
+    --gpo.percentile value              (default: 60)                      ($GETH_GPO_PERCENTILE)
+          Suggested gas price is the given percentile of a set of recent transaction gas
+          prices
+
+   LOGGING AND DEBUGGING
+
+   
+    --go-execution-trace value                                             ($GETH_GO_EXECUTION_TRACE)
+          Write Go execution trace to the given file
+   
+    --log.compress                      (default: false)                   ($GETH_LOG_COMPRESS)
+          Compress the log files
+   
+    --log.file value                                                       ($GETH_LOG_FILE)
+          Write logs to a file
+   
+    --log.format value                                                     ($GETH_LOG_FORMAT)
+          Log format to use (json|logfmt|terminal)
+   
+    --log.maxage value                  (default: 30)                      ($GETH_LOG_MAXAGE)
+          Maximum number of days to retain a log file
+   
+    --log.maxbackups value              (default: 10)                      ($GETH_LOG_MAXBACKUPS)
+          Maximum number of log files to retain
+   
+    --log.maxsize value                 (default: 100)                     ($GETH_LOG_MAXSIZE)
+          Maximum size in MBs of a single log file
+   
+    --log.rotate                        (default: false)                   ($GETH_LOG_ROTATE)
+          Enables log file rotation
+   
+    --log.vmodule value                                                    ($GETH_LOG_VMODULE)
+          Per-module verbosity: comma-separated list of <pattern>=<level> (e.g.
+          eth/*=5,p2p=4)
+   
+    --pprof                             (default: false)                   ($GETH_PPROF)
+          Enable the pprof HTTP server
+   
+    --pprof.addr value                  (default: "127.0.0.1")             ($GETH_PPROF_ADDR)
+          pprof HTTP server listening interface
+   
+    --pprof.blockprofilerate value      (default: 0)                       ($GETH_PPROF_BLOCKPROFILERATE)
+          Turn on block profiling with the given rate
+   
+    --pprof.cpuprofile value                                               ($GETH_PPROF_CPUPROFILE)
+          Write CPU profile to the given file
+   
+    --pprof.memprofilerate value        (default: 524288)                  ($GETH_PPROF_MEMPROFILERATE)
+          Turn on memory profiling with the given rate
+   
+    --pprof.port value                  (default: 6060)                    ($GETH_PPROF_PORT)
+          pprof HTTP server listening port
+   
+    --remotedb value                                                       ($GETH_REMOTEDB)
+          URL for remote database
+   
+    --verbosity value                   (default: 3)                       ($GETH_VERBOSITY)
+          Logging verbosity: 0=silent, 1=error, 2=warn, 3=info, 4=debug, 5=detail
+
+   METRICS AND STATS
+
+   
+    --ethstats value                                                       ($GETH_ETHSTATS)
+          Reporting URL of a ethstats service (nodename:secret@host:port)
+   
+    --metrics                           (default: false)                   ($GETH_METRICS)
+          Enable metrics collection and reporting
+   
+    --metrics.addr value                                                   ($GETH_METRICS_ADDR)
+          Enable stand-alone metrics HTTP server listening interface.
+   
+    --metrics.influxdb                  (default: false)                   ($GETH_METRICS_INFLUXDB)
+          Enable metrics export/push to an external InfluxDB database
+   
+    --metrics.influxdb.bucket value     (default: "geth")                  ($GETH_METRICS_INFLUXDB_BUCKET)
+          InfluxDB bucket name to push reported metrics to (v2 only)
+   
+    --metrics.influxdb.database value   (default: "geth")                  ($GETH_METRICS_INFLUXDB_DATABASE)
+          InfluxDB database name to push reported metrics to
+   
+    --metrics.influxdb.endpoint value   (default: "http://localhost:8086") ($GETH_METRICS_INFLUXDB_ENDPOINT)
+          InfluxDB API endpoint to report metrics to
+   
+    --metrics.influxdb.organization value (default: "geth")                  ($GETH_METRICS_INFLUXDB_ORGANIZATION)
+          InfluxDB organization name (v2 only)
+   
+    --metrics.influxdb.password value   (default: "test")                  ($GETH_METRICS_INFLUXDB_PASSWORD)
+          Password to authorize access to the database
+   
+    --metrics.influxdb.tags value       (default: "host=localhost")        ($GETH_METRICS_INFLUXDB_TAGS)
+          Comma-separated InfluxDB tags (key/values) attached to all measurements
+   
+    --metrics.influxdb.token value      (default: "test")                  ($GETH_METRICS_INFLUXDB_TOKEN)
+          Token to authorize access to the database (v2 only)
+   
+    --metrics.influxdb.username value   (default: "test")                  ($GETH_METRICS_INFLUXDB_USERNAME)
+          Username to authorize access to the database
+   
+    --metrics.influxdbv2                (default: false)                   ($GETH_METRICS_INFLUXDBV2)
+          Enable metrics export/push to an external InfluxDB v2 database
+   
+    --metrics.port value                (default: 6060)                    ($GETH_METRICS_PORT)
+          Metrics HTTP server listening port.
+          Please note that --metrics.addr must be set
+          to start the server.
+
+   MINER
+
+   
+    --miner.extradata value                                                ($GETH_MINER_EXTRADATA)
+          Block extra data set by the miner (default = client version)
+   
+    --miner.gaslimit value              (default: 36000000)                ($GETH_MINER_GASLIMIT)
+          Target gas ceiling for mined blocks
+   
+    --miner.gasprice value              (default: 1000000)                 ($GETH_MINER_GASPRICE)
+          Minimum gas price for mining a transaction
+   
+    --miner.pending.feeRecipient value                                     ($GETH_MINER_PENDING_FEERECIPIENT)
+          0x prefixed public address for the pending block producer (not used for actual
+          block production)
+   
+    --miner.recommit value              (default: 2s)                      ($GETH_MINER_RECOMMIT)
+          Time interval to recreate the block being mined
+
+   MISC
+
+   
+    --help, -h                          (default: false)                  
+          show help
+   
+    --synctarget value                                                     ($GETH_SYNCTARGET)
+          Hash of the block to full sync to (dev testing feature)
+   
+    --version, -v                       (default: false)                  
+          print the version
+
+   NETWORKING
+
+   
+    --bootnodes value                                                      ($GETH_BOOTNODES)
+          Comma separated enode URLs for P2P discovery bootstrap
+   
+    --discovery.dns value                                                  ($GETH_DISCOVERY_DNS)
+          Sets DNS discovery entry points (use "" to disable DNS)
+   
+    --discovery.port value              (default: 30303)                   ($GETH_DISCOVERY_PORT)
+          Use a custom UDP port for P2P discovery
+   
+    --discovery.v4, --discv4            (default: true)                    ($GETH_DISCOVERY_V4)
+          Enables the V4 discovery mechanism
+   
+    --discovery.v5, --discv5            (default: true)                    ($GETH_DISCOVERY_V5)
+          Enables the V5 discovery mechanism
+   
+    --identity value                                                       ($GETH_IDENTITY)
+          Custom node name
+   
+    --maxpeers value                    (default: 50)                      ($GETH_MAXPEERS)
+          Maximum number of network peers (network disabled if set to 0)
+   
+    --maxpendpeers value                (default: 0)                       ($GETH_MAXPENDPEERS)
+          Maximum number of pending connection attempts (defaults used if set to 0)
+   
+    --nat value                         (default: "any")                   ($GETH_NAT)
+          NAT port mapping mechanism
+          (any|none|upnp|pmp|pmp:<IP>|extip:<IP>|stun:<IP:PORT>)
+   
+    --netrestrict value                                                    ($GETH_NETRESTRICT)
+          Restricts network communication to the given IP networks (CIDR masks)
+   
+    --nodekey value                                                        ($GETH_NODEKEY)
+          P2P node key file
+   
+    --nodekeyhex value                                                     ($GETH_NODEKEYHEX)
+          P2P node key as hex (for testing)
+   
+    --nodiscover                        (default: false)                   ($GETH_NODISCOVER)
+          Disables the peer discovery mechanism (manual peer addition)
+   
+    --port value                        (default: 30303)                   ($GETH_PORT)
+          Network listening port
+
+   PERFORMANCE TUNING
+
+   
+    --cache value                       (default: 1024)                    ($GETH_CACHE)
+          Megabytes of memory allocated to internal caching (default = 4096 mainnet full
+          node, 128 light mode)
+   
+    --cache.blocklogs value             (default: 32)                      ($GETH_CACHE_BLOCKLOGS)
+          Size (in number of blocks) of the log cache for filtering
+   
+    --cache.database value              (default: 50)                      ($GETH_CACHE_DATABASE)
+          Percentage of cache memory allowance to use for database io
+   
+    --cache.gc value                    (default: 25)                      ($GETH_CACHE_GC)
+          Percentage of cache memory allowance to use for trie pruning (default = 25% full
+          mode, 0% archive mode)
+   
+    --cache.noprefetch                  (default: false)                   ($GETH_CACHE_NOPREFETCH)
+          Disable heuristic state prefetch during block import (less CPU and disk IO, more
+          time waiting for data)
+   
+    --cache.preimages                   (default: false)                   ($GETH_CACHE_PREIMAGES)
+          Enable recording the SHA3/keccak preimages of trie keys
+   
+    --cache.snapshot value              (default: 10)                      ($GETH_CACHE_SNAPSHOT)
+          Percentage of cache memory allowance to use for snapshot caching (default = 10%
+          full mode, 20% archive mode)
+   
+    --cache.trie value                  (default: 15)                      ($GETH_CACHE_TRIE)
+          Percentage of cache memory allowance to use for trie caching (default = 15% full
+          mode, 30% archive mode)
+   
+    --crypto.kzg value                  (default: "gokzg")                 ($GETH_CRYPTO_KZG)
+          KZG library implementation to use; gokzg (recommended) or ckzg
+   
+    --fdlimit value                     (default: 0)                       ($GETH_FDLIMIT)
+          Raise the open file descriptor resource limit (default = system fd limit)
+
+   STATE HISTORY MANAGEMENT
+
+   
+    --gcmode value                      (default: "full")                  ($GETH_GCMODE)
+          Blockchain garbage collection mode, only relevant in state.scheme=hash ("full",
+          "archive")
+   
+    --history.chain value               (default: "all")                   ($GETH_HISTORY_CHAIN)
+          Blockchain history retention ("all" or "postmerge")
+   
+    --history.logs value                (default: 2350000)                 ($GETH_HISTORY_LOGS)
+          Number of recent blocks to maintain log search index for (default = about one
+          year, 0 = entire chain)
+   
+    --history.logs.disable              (default: false)                   ($GETH_HISTORY_LOGS_DISABLE)
+          Do not maintain log search index
+   
+    --history.logs.export value                                            ($GETH_HISTORY_LOGS_EXPORT)
+          Export checkpoints to file in go source file format
+   
+    --history.state value               (default: 90000)                   ($GETH_HISTORY_STATE)
+          Number of recent blocks to retain state history for, only relevant in
+          state.scheme=path (default = 90,000 blocks, 0 = entire chain)
+   
+    --history.transactions value        (default: 2350000)                 ($GETH_HISTORY_TRANSACTIONS)
+          Number of recent blocks to maintain transactions index for (default = about one
+          year, 0 = entire chain)
+   
+    --state.scheme value                                                   ($GETH_STATE_SCHEME)
+          Scheme to use for storing ethereum state ('hash' or 'path')
+   
+    --syncmode value                    (default: "snap")                  ($GETH_SYNCMODE)
+          Blockchain sync mode ("snap" or "full")
+
+   TRANSACTION POOL (BLOB)
+
+   
+    --blobpool.datacap value            (default: 2684354560)              ($GETH_BLOBPOOL_DATACAP)
+          Disk space to allocate for pending blob transactions (soft limit)
+   
+    --blobpool.datadir value            (default: "blobpool")              ($GETH_BLOBPOOL_DATADIR)
+          Data directory to store blob transactions in
+   
+    --blobpool.pricebump value          (default: 100)                     ($GETH_BLOBPOOL_PRICEBUMP)
+          Price bump percentage to replace an already existing blob transaction
+
+   TRANSACTION POOL (EVM)
+
+   
+    --txpool.accountqueue value         (default: 64)                      ($GETH_TXPOOL_ACCOUNTQUEUE)
+          Maximum number of non-executable transaction slots permitted per account
+   
+    --txpool.accountslots value         (default: 16)                      ($GETH_TXPOOL_ACCOUNTSLOTS)
+          Minimum number of executable transaction slots guaranteed per account
+   
+    --txpool.globalqueue value          (default: 1024)                    ($GETH_TXPOOL_GLOBALQUEUE)
+          Maximum number of non-executable transaction slots for all accounts
+   
+    --txpool.globalslots value          (default: 5120)                    ($GETH_TXPOOL_GLOBALSLOTS)
+          Maximum number of executable transaction slots for all accounts
+   
+    --txpool.journal value              (default: "transactions.rlp")      ($GETH_TXPOOL_JOURNAL)
+          Disk journal for local transaction to survive node restarts
+   
+    --txpool.lifetime value             (default: 3h0m0s)                  ($GETH_TXPOOL_LIFETIME)
+          Maximum amount of time non-executable transaction are queued
+   
+    --txpool.locals value                                                  ($GETH_TXPOOL_LOCALS)
+          Comma separated accounts to treat as locals (no flush, priority inclusion)
+   
+    --txpool.nolocals                   (default: false)                   ($GETH_TXPOOL_NOLOCALS)
+          Disables price exemptions for locally submitted transactions
+   
+    --txpool.pricebump value            (default: 10)                      ($GETH_TXPOOL_PRICEBUMP)
+          Price bump percentage to replace an already existing transaction
+   
+    --txpool.pricelimit value           (default: 1)                       ($GETH_TXPOOL_PRICELIMIT)
+          Minimum gas price tip to enforce for acceptance into the pool
+   
+    --txpool.rejournal value            (default: 1h0m0s)                  ($GETH_TXPOOL_REJOURNAL)
+          Time interval to regenerate the local transaction journal
+
+   VIRTUAL MACHINE
+
+   
+    --vmdebug                           (default: false)                   ($GETH_VMDEBUG)
+          Record information useful for VM and contract debugging
+   
+    --vmtrace value                                                        ($GETH_VMTRACE)
+          Name of tracer which should record internal VM operations (costly)
+   
+    --vmtrace.jsonconfig value          (default: "{}")                    ($GETH_VMTRACE_JSONCONFIG)
+          Tracer configuration (JSON)
+
+
+COPYRIGHT:
+   Copyright 2013-2025 The go-ethereum Authors
+

DOWNLOADS

DOCUMENTATION

© 2013–2025. The go-ethereum Authors | Do-not-Track

\ No newline at end of file From e2f1bf3e3c9b3e0b4308bf388698a51f97538790 Mon Sep 17 00:00:00 2001 From: Romeo Rosete <208020944+roseteromeo56@users.noreply.github.com> Date: Fri, 23 May 2025 20:05:17 -0400 Subject: [PATCH 21/25] FAQ _ go-ethereum.html Romeo Rosete --- FAQ _ go-ethereum.html | 51 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 51 insertions(+) create mode 100644 FAQ _ go-ethereum.html diff --git a/FAQ _ go-ethereum.html b/FAQ _ go-ethereum.html new file mode 100644 index 0000000000..0dca91ffa0 --- /dev/null +++ b/FAQ _ go-ethereum.html @@ -0,0 +1,51 @@ + + +FAQ | go-ethereum

go-ethereum

skip to content

downloads

documentation

FAQ

Last edited on May 27, 2024

Where can I get more information?

+

This page contains answers to common questions about Geth. Source code and README documentation can be found on the Geth GitHub. You can also ask questions on Geth's Discord server or keep up to date with Geth on Twitter. Information about Ethereum in general can be found at ethereum.org.

+

The Geth team have also recently started to run AMA's on Reddit:

+
+

It is also recommended to search for 'Geth' and 'go-ethereum' on ethereum.stackexchange.com.

+

What are RPC and IPC?

+

IPC stands for Inter-Process Communications. Geth creates a geth.ipc file on startup that other processes on the same computer can use to communicate with Geth. +RPC stands for Remote Procedure Call. RPC is a mode of communication between processes that may be running on different machines. Geth accepts RPC traffic over HTTP or Websockets. Geth functions are invoked by sending requests that are formatted according to the RPC-API to the node via either IPC or RPC.

+

What is jwtsecret?

+

The jwtsecret file is required to create an authenticated connection between Geth and a consensus client. JWT stands for JSON Web Token - it is signed using a secret key. The signed token acts as a shared secret used to check that information is sent to and received from the correct peer. Read about how to create jwt-secret in Geth on our consensus clients page.

+

I noticed my peercount slowly decreasing, and now it is at 0. Restarting doesn't get any peers.

+

This may be because your clock has fallen out of sync with other nodes. You can force a clock update using ntp like so:

+
sudo ntpdate -s time.nist.gov
+
+

I would like to run multiple Geth instances but got the error "Fatal: blockchain db err: resource temporarily unavailable".

+

Geth uses a datadir to store the blockchain, accounts and some additional information. This directory cannot be shared between running instances. If you would like to run multiple instances follow these instructions.

+

When I try to use the --password command line flag, I get the error "Could not decrypt key with given passphrase" but the password is correct. Why does this error appear?

+

Especially if the password file was created on Windows, it may have a Byte Order Mark or other special encoding that the go-ethereum client doesn't currently recognize. You can change this behavior with a PowerShell command like:

+
echo "mypasswordhere" | out-file test.txt -encoding ASCII
+
+

Additional details and/or any updates on more robust handling are at https://github.com/ethereum/go-ethereum/issues/19905.

+

How does Ethereum syncing work?

+

The current default syncing mode used by Geth is called snap sync. Instead of starting from the genesis block and processing all the transactions that ever occurred (which could take weeks), snap sync downloads the blocks, and only verifies the associated proof-of-works, assuming state transitions to be correct. Downloading all the blocks is a straightforward and fast procedure and will relatively quickly reassemble the entire chain.

+

Many people assume that because they have the blocks, they are in sync. Unfortunately this is not the case. Since no transaction was executed, we do not have any account state available (e.g. balances, nonces, smart contract code, and data). These need to be downloaded separately and cross-checked with the latest blocks. This phase is called the state trie download phase. Snap sync tries to expedite this process by downloading contiguous chunks of state data, instead of doing so one-by-one, as in previous synchronization methods. Geth downloads the leaves of the trie without the intermediate nodes that connect the leaves to the root. The full trie is regenerated locally. However, while this is happening, the blockchain is progressing, meaning some of the regenerated state trie becomes invalid. Therefore, there is also a healing phase that corrects any errors in the state trie. The state sync has to progress faster than the chain growth otherwise it will never finish.

+

Geth can also be synced with --syncmode full. In this case, Geth downloads and independently verifies every block since genesis in sequence, including re-executing transactions to verify state transitions. Although Geth verifies every block since genesis, the state of 128 blocks only are stored in memory.

+

What's the state trie?

+

In the Ethereum mainnet, there are a ton of accounts already, which track the balance, nonce, etc of each user/contract. The accounts themselves are however insufficient to run a node, they need to be cryptographically linked to each block so that nodes can actually verify that the accounts are not tampered with.

+

This cryptographic linking is done by creating a tree-like data structure, where each leaf corresponds to an account, and each intermediary level aggregates the layer below it into an ever smaller layer, until you reach a single root. This gigantic data structure containing all the accounts and the intermediate cryptographic proofs is called the state trie.

+

Read more about Merkle Tries in general and the Ethereum state trie specifically on ethereum.org

+

Why does the state trie download phase require a special syncing mode?

+

The trie data structure is an intricate interlink of hundreds of millions of tiny cryptographic proofs (trie nodes). To truly have a synchronized node, you need to download all the account data, as well as all the tiny cryptographic proofs to verify that no one in the network is trying to cheat you. This itself is already a crazy number of data items.

+

The part where it gets even messier is that this data is constantly morphing: at every block (roughly 13s), about 1000 nodes are deleted from this trie and about 2000 new ones are added. This means your node needs to synchronize a dataset that is changing more than 200 times per second. Until you actually do gather all the data, your local node is not usable since it cannot cryptographically prove anything about any accounts. But while you're syncing the network is moving forward and most nodes on the network keep the state for only a limited number of recent blocks. Any sync algorithm needs to consider this fact.

+

What happened to fast sync?

+

Snap syncing was introduced by version 1.10.0 and was adopted as the default mode in version 1.10.4. Before that, the default was the "fast" syncing mode, which was dropped in version 1.10.14. Even though support for fast sync was dropped, Geth still serves the relevant eth requests to other client implementations still relying on it. The reason being that snap sync relies on an alternative data structure called the snapshot which not all clients implement.

+

You can read more in the article posted above why snap sync replaced fast sync in Geth.

+

What is wrong with my light client?

+

Light sync relies on full nodes that serve data to light clients. Historically, this has been hampered by the fact that serving light clients was turned off by default in geth full nodes and few nodes chose to turn it on. Therefore, light nodes often struggled to find peers. Since Ethereum switched to proof-of-stake, Geth light clients have stopped working altogether. Light clients for proof-of-stake Ethereum are expected to be implemented soon!

+

Why do I need another client in addition to Geth?

+

Historically, running Geth was enough to turn a computer into an Ethereum node. However, when Ethereum transitioned to proof-of-stake, responsibility for consensus logic and block gossip was handed over to a separate consensus layer client. However, Geth still handles transactions and state management. When the consensus client is required to create a new block, it requests Geth to gather transactions from the transaction pool, execute them to compute a state transition and pass this information back to the consensus client. When the consensus client receives a new block from a peer, it passes the transactions to Geth to re-execute to verify the proposed state-transition. There is a clear separation of concerns between the two clients, meaning that both are required for a computer to function as an Ethereum node.

+

What is staking and how do I participate?

+

Staking is how node operators participate in proof-of-stake based consensus. Staking requires validators to deposit 32 ETH to a smart contract and run validator software connected to their node. The validator software broadcasts a vote ("attestation") in favour of checkpoint blocks that it determines to be in the canonical blockchain. The correct chain is then the one with the greatest accumulation of votes, weighted by the validators stake (up to a maximum of 32 ETH). Geth, as an execution client, does not directly handle consensus logic but it does provide the node with the execution and state-management tools required to validate incoming blocks. Validators are also occasionally picked to propose the next block broadcast across the network. In this case Geth's role is to bundle transactions it has received over the execution layer gossip network, pass them to the consensus client to be included in the block and execute them to determine the resulting state change.

+

It is entirely possible to run a node without staking any ETH. In this case the node runs the execution and consensus clients but not the validator software. In order to participate in consensus and earn ETH rewards, the node must run an execution client, consensus client and a validator. The validator software comes bundled with the consensus client.

+

For step-by-step instruction for staking and spinning up a validating node, see ethereum.org or get started on the Ethereum Foundation's Staking Launchpad.

+

How do I set up a consensus client/validator and connect it to Geth?

+

These docs mainly cover how to set up Geth, but since the switch to proof-of-stake it is also necessary to run a consensus client in order to track the head of the chain, and a validator in order to participate in proof-of-stake consensus. A validator node is also required to deposit 32 ETH into a specific smart contract. Our consensus clients page includes a general overview of how to connect a consensus client to Geth. For step by step instructions for specific clients, see their documentation and also see these helpful online guides.

+

How do I update Geth?

+

Updating Geth to the latest version simply requires stopping the node, downloading the latest release and restarting the node. Precisely how to download the latest software depends on the installation method - please refer to our Installation pages.

+

What is a preimage?

+

Geth stores the Ethereum state in a Patricia Merkle Trie. It contains (key,value) pairs with account addresses as keys and RLP encoded account as the value, where an account is an array containing essential account information, specifically: nonce, balance, StorageRoot and codeHash. Definitions for these parameters are available in the Ethereum whitepaper. However, Geth's state trie does not use the keys directly, instead account information is indexed using the SHA3 hash of the key. This means that looking up the account information for an address can be done by traversing the trie for sha3(address), but querying addresses that contain certain data is not possible - the addresses themselves are not part of the trie. This problem is solved using preimages - these are mappings of addresses to their hashes. Geth generates these preimages during block-by-block sync as information is added to the trie but they are deleted once they reach a certain age (128 blocks by default). To retain the preimages, Geth should be started with --cache.preimages=true.

DOWNLOADS

DOCUMENTATION

© 2013–2025. The go-ethereum Authors | Do-not-Track

\ No newline at end of file From 92b657fde524cf8f8f7fa583685885cd76038a3e Mon Sep 17 00:00:00 2001 From: Romeo Rosete <208020944+roseteromeo56@users.noreply.github.com> Date: Fri, 23 May 2025 20:11:19 -0400 Subject: [PATCH 22/25] Introduction to Clef _ go-ethereum.html Romeo Rosete --- Introduction to Clef _ go-ethereum.html | 116 ++++++++++++++++++++++++ 1 file changed, 116 insertions(+) create mode 100644 Introduction to Clef _ go-ethereum.html diff --git a/Introduction to Clef _ go-ethereum.html b/Introduction to Clef _ go-ethereum.html new file mode 100644 index 0000000000..222f9227fc --- /dev/null +++ b/Introduction to Clef _ go-ethereum.html @@ -0,0 +1,116 @@ + + +Introduction to Clef | go-ethereum

go-ethereum

skip to content

downloads

documentation

Introduction to Clef

Last edited on December 20, 2022

What is Clef?

+

Clef is a tool for signing transactions and data in a secure local environment. It is intended to become a more composable and secure replacement for Geth's built-in account management. Clef decouples key management from Geth itself, meaning it can be used as an independent, standalone key management and signing application, or it can be integrated into Geth. This provides a more flexible modular tool compared to Geth's account manager. Clef can be used safely in situations where access to Ethereum is via a remote and/or untrusted node because signing happens locally, either manually or automatically using custom rulesets. The separation of Clef from the node itself enables it to run as a daemon on the same machine as the client software, on a secure usb-stick like USB armory, or even a separate VM in a QubesOS type setup.

+

Installing and starting Clef

+

Clef comes bundled with Geth and can be built along with Geth and the other bundled tools using:

+

make all

+

However, Clef is not bound to Geth and can be built on its own using:

+

make clef

+

Once built, Clef must be initialized. This includes storing some data, some of which is sensitive (such as passwords, account data, signing rules etc). Initializing Clef takes that data and encrypts it using a user-defined password.

+

clef init

+
WARNING! + +Clef is an account management tool. It may, like any software, contain bugs. + +Please take care to +- backup your keystore files, +- verify that the keystore(s) can be opened with your password. + +Clef is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY +without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR +PURPOSE. See the GNU General Public License for more details. + +Enter 'ok' to proceed: +> ok + +The master seed of clef will be locked with a password. +Please specify a password. Do not forget this password! +Password: +Repeat password: + +A master seed has been generated into /home/martin/.clef/masterseed.json + +This is required to be able to store credentials, such as: +* Passwords for keystores (used by rule engine) +* Storage for JavaScript auto-signing rules +* Hash of JavaScript rule-file + +You should treat 'masterseed.json' with utmost secrecy and make a backup of it! +* The password is necessary but not enough, you need to back up the master seed too! +* The master seed does not contain your accounts, those need to be backed up separately! +
+

Security model

+

One of the major benefits of Clef is that it is decoupled from the client software, meaning it can be used by users and dapps to sign data and transactions in a secure, local environment and send the signed packet to an arbitrary Ethereum entry-point, which might include, for example, an untrusted remote node. Alternatively, Clef can simply be used as a standalone, composable signer that can be a backend component for decentralized applications. This requires a secure architecture that separates cryptographic operations from user interactions and internal/external communication.

+

The security model of Clef is as follows:

+
  • +

    A self-contained binary controls all cryptographic operations including encryption, decryption and storage of keystore files, and signing data and transactions.

    +
  • +

    A well defined, deliberately minimal "external" API is used to communicate with the Clef binary - Clef considers this external traffic to be UNTRUSTED. This means Clef does not accept any credentials and does not recognize authority of requests received over this channel. Clef listens on http.addr:http.port or ipcpath - the same as Geth - and expects messages to be formatted using the JSON-RPC 2.0 standard. Some of the external API calls require some user interaction (manual approve/deny)- if it is not received responses can be delayed indefinitely.

    +
  • +

    Clef communicates with the process that invoked the binary using stin/stout. The process invoking the binary is usually the native console-based user interface (UI) but there is also an API that enables communication with an external UI. This has to be enabled using --stdio-ui at startup. This channel is considered TRUSTED and is used to pass approvals and passwords between the user and Clef.

    +
  • +

    Clef does not store keys - the user is responsible for securely storing and backing up keyfiles. Clef does store account passwords in its encrypted vault if they are explicitly provided to Clef by the user to enable automatic account unlocking.

    +
+

The external API never handles any sensitive data directly, but it can be used to request Clef to sign some data or a transaction. It is the internal API that controls signing and triggers requests for manual approval (automatic approves actions that conform to attested rulesets) and passwords.

+

The general flow for a basic transaction-signing operation using Clef and an Ethereum node such as Geth is as follows:

+
Clef signing logic
 +

In the case illustrated in the schematic above, Geth would be started with --signer <addr>:<port> and would relay requests to eth.sendTransaction. Text in mono font positioned along arrows shows the objects passed between each component.

+

Most users use Clef by manually approving transactions through the UI as in the schematic above, but it is also possible to configure Clef to sign transactions without always prompting the user. This requires defining the precise conditions under which a transaction will be signed. These conditions are known as Rules and they are small Javascript snippets that are attested by the user by injecting the snippet's hash into Clef's secure whitelist. Clef is then started with the rule file, so that requests that satisfy the conditions in the whitelisted rule files are automatically signed. This is covered in detail on the Rules page.

+

Basic usage

+

Clef is started on the command line using the clef command. Clef can be configured by providing flags and commands to clef on startup. The full list of command line options is available below. Frequently used options include --keystore and --chainid which configure the path to an existing keystore and a network to connect to. These options default to $HOME/.ethereum/keystore and 1 (corresponding to Ethereum Mainnet) respectively. The following code snippet starts Clef, providing a custom path to an existing keystore and connecting to the Goerli testnet:

+
clef --keystore /my/keystore --chainid 5
+
+

On starting Clef, the following welcome message is displayed in the terminal:

+
WARNING! + +Clef is an account management tool. It may, like any software, contain bugs. + +Please take care to +- backup your keystore files, +- verify that the keystore(s) can be opened with your password. + +Clef is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY. +without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR +PURPOSE. See the GNU General Public License for more details. + +Enter 'ok' to proceed: +> +
+

Requests requiring account access or signing now require explicit consent in this terminal. Activities such as sending transactions via a local Geth node's attached Javascript console or RPC will now hang indefinitely, awaiting approval in this terminal.

+

A much more detailed Clef tutorial is available on the Tutorial page.

+

Command line options

+
COMMANDS:
+   init         Initialize the signer, generate secret storage
+   attest       Attest that a js-file is to be used
+   setpw        Store a credential for a keystore file
+   delpw        Remove a credential for a keystore file
+   newaccount   Create a new account
+   gendoc       Generate documentation about json-rpc format
+   help, h      Shows a list of commands or help for one command
+
+GLOBAL OPTIONS:
+   --loglevel value        log level to emit to the screen (default: 4)
+   --keystore value        Directory for the keystore (default: "$HOME/.ethereum/keystore")
+   --configdir value       Directory for Clef configuration (default: "$HOME/.clef")
+   --chainid value         Chain id to use for signing (1=mainnet, 3=Ropsten, 4=Rinkeby, 5=Goerli) (default: 1)
+   --lightkdf              Reduce key-derivation RAM & CPU usage at some expense of KDF strength
+   --nousb                 Disables monitoring for and managing USB hardware wallets
+   --pcscdpath value       Path to the smartcard daemon (pcscd) socket file (default: "/run/pcscd/pcscd.comm")
+   --http.addr value       HTTP-RPC server listening interface (default: "localhost")
+   --http.vhosts value     Comma separated list of virtual hostnames from which to accept requests (server enforced). Accepts '*' wildcard. (default: "localhost")
+   --ipcdisable            Disable the IPC-RPC server
+   --ipcpath value         Filename for IPC socket/pipe within the datadir (explicit paths escape it)
+   --http                  Enable the HTTP-RPC server
+   --http.port value       HTTP-RPC server listening port (default: 8550)
+   --signersecret value    A file containing the (encrypted) master seed to encrypt Clef data, e.g. keystore credentials and ruleset hash
+   --4bytedb-custom value  File used for writing new 4byte-identifiers submitted via API (default: "./4byte-custom.json")
+   --auditlog value        File used to emit audit logs. Set to "" to disable (default: "audit.log")
+   --rules value           Path to the rule file to auto-authorize requests with
+   --stdio-ui              Use STDIN/STDOUT as a channel for an external UI. This means that an STDIN/STDOUT is used for RPC-communication with a e.g. a graphical user interface, and can be used when Clef is started by an external process.
+   --stdio-ui-test         Mechanism to test interface between Clef and UI. Requires 'stdio-ui'.
+   --advanced              If enabled, issues warnings instead of rejections for suspicious requests. Default off
+   --suppress-bootwarn     If set, does not show the warning during boot
+
+

Summary

+

Clef is an external key management and signer tool that comes bundled with Geth but can either be used as a backend account manager and signer for Geth or as a completely separate standalone application. Being modular and composable it can be used as a component in decentralized applications or to sign data and transactions in untrusted environments. Clef is intended to eventually replace Geth's built-in account management tools.

DOWNLOADS

DOCUMENTATION

© 2013–2025. The go-ethereum Authors | Do-not-Track

\ No newline at end of file From e79b4fe89a54db368b0536f27bf9a162347d9830 Mon Sep 17 00:00:00 2001 From: Romeo Rosete <208020944+roseteromeo56@users.noreply.github.com> Date: Fri, 23 May 2025 20:18:34 -0400 Subject: [PATCH 23/25] Understanding Geth's dashboard _ go-ethereum.html Romeo Rosete --- ...anding Geth's dashboard _ go-ethereum.html | 312 ++++++++++++++++++ 1 file changed, 312 insertions(+) create mode 100644 Understanding Geth's dashboard _ go-ethereum.html diff --git a/Understanding Geth's dashboard _ go-ethereum.html b/Understanding Geth's dashboard _ go-ethereum.html new file mode 100644 index 0000000000..26aebf4cc2 --- /dev/null +++ b/Understanding Geth's dashboard _ go-ethereum.html @@ -0,0 +1,312 @@ + + +Understanding Geth's dashboard | go-ethereum

go-ethereum

skip to content

downloads

documentation

Understanding Geth's dashboard

Last edited on July 11, 2024

Our dashboards page explains how to set up a Grafana dashboard for monitoring your Geth node. This page explores the dashboard itself, explaining what the various metrics are and what they mean for the health of a node. Note that the raw data informing the dashboard can be viewed in JSON format in the browser by navigating to the ip address and port passed to --metrics.addr and --metrics.port (127.0.0.1:6060 by default).

+

What does the dashboard look like?

+

The default Grafana dashboard looks as follows (note that there are many more panels on the actual page than in the snapshot below):

+
The Grafana dashboard
 +

Each panel in the dashboard tracks a different metric that can be used to understand some aspect of how a Geth node is behaving. There are three main categories of panel in the default dashboard: System, Network and Blockchain. The individual panels are explained in the following sections.

+

What do the panels show?

+

System

+

Panels in the System category track the impact of Geth on the local machine, including memory and CPU usage.

+

CPU

+
The CPU panel
 +

The CPU panel shows how much CPU is being used as a percentage of one processing core (i.e. 100% means complete usage of one processing core, 200% means complete usage of two processing cores). There are three processes plotted on the figure. The total CPU usage by the entire system is plotted as system; the percentage of time that the CPUs are idle waiting for disk i/o operations is plotted as iowait; the CPU usage by the Geth process is plotted as geth.

+

Memory

+
The Memory panel
 +

Memory tracks the amount of RAM being used by Geth. Three metrics are plotted: the cache size, i.e. the total RAM reserved for Geth (default 1024 MB) is plotted as held; the amount of the cache actually being used by Geth is plotted as used; the number of bytes being allocated by the system per second is plotted as alloc.

+

Disk

+

Disk tracks the rate that data is written to (plotted as write) or read from (plotted as read) the hard disk in units of MB/s.

+
The Disk panel
 +

Goroutines

+

Tracks the total number of active goroutines being used by Geth. Goroutines are lightweight threads managed by the Go runtime, they allow processes to +execute concurrently.

+
The goroutine panel
 +

Network

+

Panels in the Network category track the data flow in and out of the local node.

+

Traffic

+

The Traffic panel shows the rate of data ingress and egress for all subprotocols, measured in units of kB/s.

+
The Traffic panel
 +

Peers

+

The Peers panel shows the number of individual peers the local node is connected to. The number of dials issued by Geth per second and the number of external connections received per second are also tracked in this panel.

+
The Peers panel
 +

ETH ingress data rate

+

Ingress is the process of data arriving at the local node from its peers. This panel shows the rate that data specifically using the eth subprotocol is arriving at the local node in units of kB/s (kilobytes per second). The data is subdivided into specific versions of the ETH subprotocol. Make sure your dashboard includes the latest version of the eth subprotocol!

+
The ETH ingress rate panel
 +

ETH egress data rate

+

Egress is the process of data leaving the local node and being transferred to its peers. This panel shows the rate that data specifically using the eth subprotocol is leaving the local node in units of kB/s (kilobytes per second). Make sure your dashboard includes the latest version of the eth subprotocol!

+
The ETH egress rate panel
 +

ETH ingress traffic

+

Ingress is the process of data arriving at the local node from its peers. This panel shows a moment-by-moment snapshot of the amount of data that is arriving at the local node, specifically using the eth subprotocol, in units of GB (gigabytes). Make sure your dashboard includes the latest version of the eth subprotocol!

+
The ETH ingress traffic panel
 +

ETH egress traffic

+

Egress is the process of data leaving the local node and being transferred to its peers. This panel shows a moment-by-moment snapshot of the amount of data that has left the local node, specifically using the eth subprotocol, in units of GB (gigabytes). Make sure your dashboard includes the latest version of the eth subprotocol!

+
The ETH egress traffic panel
 +

Blockchain

+

Panels in the Blockchain category track the local node's view of the blockchain.

+

Chain head

+

The chain head simply tracks the latest block number that the local node is aware of.

+
The Chain head panel
 +

Transaction pool

+

Geth has a capacity for pending transactions defined by --txpool.globalslots (default is 5160). The number of slots filled with transactions is tracked as slots. The transactions in the pool are divided into pending transactions and queued transactions. Pending transactions are ready to be processed and included in a block, whereas queued transactions are those whose transaction nonces are out of sequence. Queued transactions can become pending transactions if transactions with the missing nonces become available. In the dashboard pending transactions are labelled as executable and queued transactions are labelled gapped. The subset of those global transactions that originated from the local node are tracked as local.

+
The tx pool panel
 +

Block processing

+

The block processing panel tracks the time taken to complete the various tasks involved in processing each block, measured in microseconds or nanoseconds. Specifically, this includes:

+
  • execution: time taken to execute the transactions in the block
  • validation: time taken to validate that the information in a received block body matches what is described in the block header.
  • commit: time taken to write the new block to the chain data
  • account read: time taken to access account information from the state trie
  • account update: time taken to incorporate dirty account objects into the state trie (account trie)
  • account hash: time taken to re-compute the new root hash of the state trie (account trie)
  • account commit: time taken to commit the changes of state trie (account trie) into database
  • storage read: time taken to access smart contract storage data from the storage trie
  • storage update: time taken to incorporate dirty storage slots into the storage tries
  • storage hash: time take to re-compute the new root hash of storage tries
  • storage commit: time take to commit the changes of storage tries into database
  • snapshot account read: time taken to read account data from a snapshot
  • snapshot storage read: time taken to read storage data from a snapshot
  • snapshot commit: time take to flush the dirty state data as a new snapshot
+
The block processing panel
 +

Transaction processing

+

The transaction processing panel tracks the time taken to complete the various tasks involved in validating the transactions received from the network, measured as a mean rate of events per second:

+
  • known: rate of new transactions arriving at the node that are ignored because the local node already knows about them.
  • valid: rate that node marks received transactions as valid
  • invalid: rate that node marks received transactions as invalid
  • underpriced: rate that node marks transactions paying too low gas price as rejected
  • executable discard: rate that valid transactions are dropped from the transaction pool, e.g. because it is already known.
  • executable replace: rate that valid transactions are replaced with a new one from same sender with same nonce but higher gas
  • executable ratelimit: rate that valid transactions are dropped due to rate-limiting
  • executable nofunds: rate that valid transactions are dropped due to running out of ETH to pay gas
  • gapped discard: rate that queued transactions are discarded from the transaction pool
  • gapped replace: rate that queued transactions are replaced with a new one from same sender with same nonce but higher gas
  • gapped ratelimit: rate that queued transactions are dropped due to rate limiting
  • gapped nofunds: rate that queued transactions are dropped due to running out of ETH to pay gas
+
The tx processing panel
 +

Block propagation

+

Note

+Block propagation was disabled in Geth at The Merge. Block propagation is now the responsibility of the consensus client. Included here for archival interest. +

+

Block propagation metrics track the rate that the local node hears about, receives and broadcasts blocks. This includes:

+
  • ingress announcements: the number of inbound announcements per second. Announcements are messages from peers that signal that they have a block to share
  • known announcements: the number of announcements per second the local node is already aware of them
  • malicious announcements: the number of announcements per second that are determined to be malicious, e.g. because they are trying to mount a denial-of-service attack on the local node
  • ingress broadcasts: the number of blocks directly propagated to local node per second
  • known broadcasts: counts all blocks that have been broadcast by peers including those that are too far behind the head to be downloaded
  • malicious broadcasts: the number of blocks which are determined to be malicious per second
+

Transaction propagation

+

Transaction propagation tracks the sending and receiving of transactions on the peer-to-peer network. This includes:

+
  • ingress announcements: inbound announcements (notifications of a transaction's availability) per second
  • known announcements: announcements that are ignored because the local node is already aware of them, per second
  • underpriced announcements: announcements per second that do not get fetched because they pay too little gas
  • malicious announcements: announcements per second that are dropped because they appear malicious
  • ingress broadcasts: number of transactions propagated from peers per second
  • known broadcasts: transactions per second that are ignored because they duplicate transactions that the local node already knows about
  • underpriced broadcasts: all fetched transactions that are dropped due to paying insufficient gas, per second
  • otherreject broadcasts: transactions that are rejected for reasons other than paying too little gas, per second
  • finished requests: successful deliveries of transactions per second, meaning they have been added to the local transaction pool
  • failed requests: number of failed transaction deliveries per second, e.g. failed because a peer disconnected unexpectedly
  • timed out requests: counts the number of transaction requests that time out per second
  • ingress replies: total number of inbound replies to requests for transactions per second
  • known replies: number of replies that are dropped because they are already known to the local node, per second
  • underpriced replies: number of replies per second that get dropped due to paying too little gas
  • otherreject replies: number of replies to transaction requests that get dropped for reasons other than paying too little gas, per second
+
The tx propagation panel
 +

Block forwarding

+

The block forwarding panel counts the announcements and the blocks that the local node receives that it should pass on to its peers.

+

Transaction fetcher peers

+

The transaction fetcher peers panel shows how many peers the local node is connected to that can serve requests for transactions. The adjacent transaction fetcher hashes panel shows how many transaction hashes are available for fetching. Three statuses are reported in each panel: Waiting, queuing and fetching.

+

Reorg

+

The reorg meter panel simply counts the blocks added and the blocks removed during chain reorgs. The adjacent Reorg total panel shows the total number of reorg executions including both additions and removals.

+

Eth fetcher filter bodies/headers

+

Tracks the rate that headers/block bodies arrive from remote peers.

+

Database

+

The database section tracks various metrics related to data storage and i/o in the LevelDB and ancients databases.

+

Data rate

+

Measures the rate that data is written to, or read from, the LevelDB and ancients databases. Includes:

+
  • leveldb read: Rate that data is read from the fast-access LevelDB database that stores recent data.
  • leveldb write: Rate that data is written to the fast-access LevelDB database that stores recent data.
  • ancient read: Rate that data is read from the freezer (the database storing older data).
  • ancient write: Rate that data is written to the freezer (the database storing older data)
  • compaction read: Rate that data is read from the LevelDB database while it is being compacted (i.e. free space is reclaimed by deleting unnecessary data)
  • compaction write: Rate that data is written to the LevelDB database while it is being compacted (i.e. free space is reclaimed by deleting unnecessary data)
+

Session totals

+

Instead of the rate that data is read from, and written to, the LevelDB and ancients databases (as per Data rate), this panel tracks the total amount of data read and written across the entire time Geth is running.

+

Persistent size

+

This panel shows the amount of data, in GB, in the LevelDB and ancients databases.

+

Compaction time, delay and count

+

These panels show the amount of time spent compacting the LevelDB database, duration write operations to the database are delayed due to compaction and the count of various types of compaction executions.

+

Note

+The current default Geth Grafana dashboard includes panels for light nodes. Light nodes are not currently functional since Ethereum moved to proof-of-stake. +

+

Creating new dashboards

+

If the default dashboard isn't right for you, you can update it in the browser. Remove panels by clicking on their titles and selecting remove. Add a new panel by clicking the "plus" icon in the upper right of the browser window. There, you will have to define an InfluxDB query for the metric you want to display. The endpoints for the various metrics that Geth reports are listed by Geth at the address/port combination passed to --metrics.addr and metrics.port on startup - by default 127.0.0.1:6060/debug/metrics. It is also possible to configure a panel by providing a JSON configuration model. Individual components are defined using the following syntax (the example below is for the CPU panel):

+
{
+  "id": 106,
+  "gridPos": {
+    "h": 6,
+    "w": 8,
+    "x": 0,
+    "y": 1
+  },
+  "type": "graph",
+  "title": "CPU",
+  "datasource": {
+    "uid": "s1zWCjvVk",
+    "type": "influxdb"
+  },
+  "thresholds": [],
+  "pluginVersion": "9.3.6",
+  "links": [],
+  "legend": {
+    "alignAsTable": false,
+    "avg": false,
+    "current": false,
+    "max": false,
+    "min": false,
+    "rightSide": false,
+    "show": true,
+    "total": false,
+    "values": false
+  },
+  "aliasColors": {},
+  "bars": false,
+  "dashLength": 10,
+  "dashes": false,
+  "fieldConfig": {
+    "defaults": {
+      "links": []
+    },
+    "overrides": []
+  },
+  "fill": 1,
+  "fillGradient": 0,
+  "hiddenSeries": false,
+  "lines": true,
+  "linewidth": 1,
+  "nullPointMode": "connected",
+  "options": {
+    "alertThreshold": true
+  },
+  "percentage": false,
+  "pointradius": 5,
+  "points": false,
+  "renderer": "flot",
+  "seriesOverrides": [],
+  "spaceLength": 10,
+  "stack": false,
+  "steppedLine": false,
+  "targets": [
+    {
+      "alias": "system",
+      "expr": "system_cpu_sysload",
+      "format": "time_series",
+      "groupBy": [
+        {
+          "params": ["$interval"],
+          "type": "time"
+        }
+      ],
+      "intervalFactor": 1,
+      "legendFormat": "system",
+      "measurement": "geth.system/cpu/sysload.gauge",
+      "orderByTime": "ASC",
+      "policy": "default",
+      "refId": "A",
+      "resultFormat": "time_series",
+      "select": [
+        [
+          {
+            "params": ["value"],
+            "type": "field"
+          },
+          {
+            "params": [],
+            "type": "mean"
+          }
+        ]
+      ],
+      "tags": [
+        {
+          "key": "host",
+          "operator": "=~",
+          "value": "/^$host$/"
+        }
+      ],
+      "datasource": {
+        "uid": "s1zWCjvVk",
+        "type": "influxdb"
+      }
+    },
+    {
+      "alias": "iowait",
+      "expr": "system_cpu_syswait",
+      "format": "time_series",
+      "groupBy": [
+        {
+          "params": ["$interval"],
+          "type": "time"
+        }
+      ],
+      "intervalFactor": 1,
+      "legendFormat": "iowait",
+      "measurement": "geth.system/cpu/syswait.gauge",
+      "orderByTime": "ASC",
+      "policy": "default",
+      "refId": "B",
+      "resultFormat": "time_series",
+      "select": [
+        [
+          {
+            "params": ["value"],
+            "type": "field"
+          },
+          {
+            "params": [],
+            "type": "mean"
+          }
+        ]
+      ],
+      "tags": [
+        {
+          "key": "host",
+          "operator": "=~",
+          "value": "/^$host$/"
+        }
+      ],
+      "datasource": {
+        "uid": "s1zWCjvVk",
+        "type": "influxdb"
+      }
+    },
+    {
+      "alias": "geth",
+      "expr": "system_cpu_procload",
+      "format": "time_series",
+      "groupBy": [
+        {
+          "params": ["$interval"],
+          "type": "time"
+        }
+      ],
+      "intervalFactor": 1,
+      "legendFormat": "geth",
+      "measurement": "geth.system/cpu/procload.gauge",
+      "orderByTime": "ASC",
+      "policy": "default",
+      "refId": "C",
+      "resultFormat": "time_series",
+      "select": [
+        [
+          {
+            "params": ["value"],
+            "type": "field"
+          },
+          {
+            "params": [],
+            "type": "mean"
+          }
+        ]
+      ],
+      "tags": [
+        {
+          "key": "host",
+          "operator": "=~",
+          "value": "/^$host$/"
+        }
+      ],
+      "datasource": {
+        "uid": "s1zWCjvVk",
+        "type": "influxdb"
+      }
+    }
+  ],
+  "timeFrom": null,
+  "timeRegions": [],
+  "timeShift": null,
+  "tooltip": {
+    "shared": true,
+    "sort": 0,
+    "value_type": "individual"
+  },
+  "xaxis": {
+    "buckets": null,
+    "mode": "time",
+    "name": null,
+    "show": true,
+    "values": []
+  },
+  "yaxes": [
+    {
+      "format": "percent",
+      "label": null,
+      "logBase": 1,
+      "max": null,
+      "min": null,
+      "show": true
+    },
+    {
+      "format": "short",
+      "label": null,
+      "logBase": 1,
+      "max": null,
+      "min": null,
+      "show": true
+    }
+  ],
+  "yaxis": {
+    "align": false,
+    "alignLevel": null
+  }
+}
+

DOWNLOADS

DOCUMENTATION

© 2013–2025. The go-ethereum Authors | Do-not-Track

\ No newline at end of file From ef7b83858cc8070b9cb846e519a867e3df288ed6 Mon Sep 17 00:00:00 2001 From: Romeo Rosete <208020944+roseteromeo56@users.noreply.github.com> Date: Fri, 23 May 2025 20:24:42 -0400 Subject: [PATCH 24/25] Resources _ go-ethereum.html Romeo Rosete --- Resources _ go-ethereum.html | 123 +++++++++++++++++++++++++++++++++++ 1 file changed, 123 insertions(+) create mode 100644 Resources _ go-ethereum.html diff --git a/Resources _ go-ethereum.html b/Resources _ go-ethereum.html new file mode 100644 index 0000000000..7801f626be --- /dev/null +++ b/Resources _ go-ethereum.html @@ -0,0 +1,123 @@ + + +Monitoring Geth with InfluxDB and Grafana | go-ethereum

go-ethereum

skip to content

downloads

documentation

Monitoring Geth with InfluxDB and Grafana

Last edited on May 27, 2024

There are several ways to monitor the performance of a Geth node. Insights into a node's performance are useful for debugging, tuning and understanding what is really happening when Geth is running.

+

Prerequisites

+

To follow along with the instructions on this page it will be useful to have:

+
  • a running Geth instance.
  • basic working knowledge of bash/terminal.
+

This video provides an excellent introduction to Geth monitoring.

+

Monitoring stack

+

An Ethereum client collects lots of data which can be read in the form of a chronological database. To make monitoring easier, this data can be fed into data visualisation software. On this page, a Geth client will be configured to push data into an InfluxDB database and Grafana will be used to visualize the data.

+

Setting up InfluxDB

+

InfluxDB can be downloaded from the Influxdata release page. It can also be installed from a repository.

+

For example the following commands will download and install InfluxDB on a Debian based Linux operating system - you can check for up-to-date instructions for your operating system on the InfluxDB downloads page:

+
curl -tlsv1.3 --proto =https -sL https://repos.influxdata.com/influxdb.key | sudo apt-key add
+source /etc/lsb-release
+echo "deb https://repos.influxdata.com/${DISTRIB_ID,,} ${DISTRIB_CODENAME} stable" | sudo tee /etc/apt/sources.list.d/influxdb.list
+sudo apt update
+sudo apt install influxdb -y
+sudo systemctl enable influxdb
+sudo systemctl start influxdb
+sudo apt install influxdb-client
+
+

By default, InfluxDB is reachable at localhost:8086. Before using the influx client, a new user with admin privileges needs to be created. This user will serve for high level management, creating databases and users.

+
curl -XPOST "http://localhost:8086/query" --data-urlencode "q=CREATE USER username WITH PASSWORD 'password' WITH ALL PRIVILEGES"
+
+

Now the influx client can be used to enter InfluxDB shell with the new user.

+
influx -username 'username' -password 'password'
+
+

A database and user for Geth metrics can be created by communicating with it directly via its shell.

+
create database geth
+create user geth with password choosepassword
+
+

Verify created entries with:

+
show databases
+show users
+
+

Leave InfluxDB shell.

+
exit
+
+

InfluxDB is running and configured to store metrics from Geth.

+

Setting up Prometheus

+

Prometheus can be downloaded from the Prometheus. There is also a Docker image at prom/prometheus, you can run in containerized environments. eg:

+
docker run \
+    -p 9090:9090 \
+    -v /path/to/prometheus:/etc/prometheus \
+    prom/prometheus:latest
+
+

Here is an example directory of /path/to/prometheus:

+
prometheus/
+├── prometheus.yml
+└── record.geth.rules.yml
+
+

And an example of prometheus.yml is:

+
  global:
+    scrape_interval: 15s
+    evaluation_interval: 15s
+
+  # Load and evaluate rules in this file every 'evaluation_interval' seconds.
+  rule_files:
+    - 'record.geth.rules.yml'
+
+  # A scrape configuration containing exactly one endpoint to scrape.
+  scrape_configs:
+    - job_name: 'go-ethereum'
+      scrape_interval: 10s
+      metrics_path: /debug/metrics/prometheus
+      static_configs:
+        - targets:
+            - '127.0.0.1:6060'
+          labels:
+            chain: ethereum
+
+

Meanwhile, Recording rules are a powerful feature that allow you to precompute frequently needed or computationally expensive expressions and save their results as new sets of time series. Read more about setting up recording rules at the official prometheus docs.

+

Preparing Geth

+

After setting up database, metrics need to be enabled in Geth. Various options are available, as documented in the METRICS AND STATS OPTIONS +in geth --help and in our metrics page. In this case Geth will be configured to push data into InfluxDB. Basic setup specifies the endpoint where InfluxDB is reachable and authenticates the database.

+
geth --metrics --metrics.influxdb --metrics.influxdb.endpoint "http://0.0.0.0:8086" --metrics.influxdb.username "geth" --metrics.influxdb.password "chosenpassword"
+
+

These flags can be provided when Geth is started or saved to the configuration file.

+

Listing the metrics in the database verifies that Geth is pushing data correctly. In InfluxDB shell:

+
use geth
+show measurements
+
+

Setting up Grafana

+

With the InfluxDB database setup and successfully receiving data from Geth, the next step is to install Grafana so that the data can be visualized.

+

The following code snippet shows how to download, install and run Grafana on a Debian based Linux system. Up to date instructions for your operating system can be found on the Grafana downloads page.

+
curl -tlsv1.3 --proto =https -sL https://packages.grafana.com/gpg.key | sudo apt-key add -
+echo "deb https://packages.grafana.com/oss/deb stable main" | sudo tee -a /etc/apt/sources.list.d/grafana.list
+sudo apt update
+sudo apt install grafana
+sudo systemctl enable grafana-server
+sudo systemctl start grafana-server
+
+

When Grafana is up and running, it should be reachable at localhost:3000. A browser can be pointed to that URL to access a visualization dashboard. The browser will prompt for login credentials (user: admin and password: admin). When prompted, the default password should be changed and saved.

+

The browser first redirects to the Grafana home page to set up the source data. Click on the "Data sources" icon and then click on "InfluxDB". The following configuration options are recommended:

+
Name: InfluxDB
+Query Language: InfluxQL
+HTTP
+  URL: http://localhost:8086
+  Access: Server (default)
+  Whitelisted cookies: None (leave blank)
+Auth
+  All options left as their default (switches off)
+Custom HTTP Headers
+  None
+InfluxDB Details
+  Database: geth
+  User: <your-user-name>
+  Password: <your-password>
+  HTTP Method: GET
+
+

Click on "Save and test" and wait for the confirmation to pop up.

+

Grafana is now set up to read data from InfluxDB. Now a dashboard can be created to interpret and display it. Dashboards properties are encoded in JSON files which can be created by anybody and easily imported. On the left bar, click on the "Dashboards" icon, then "Import".

+

For a Geth InfluxDB monitoring dashboard, copy the URL of this dashboard and paste it in the "Import page" in Grafana. After saving the dashboard, it should look like this:

+
Grafana 1
 +

For a Geth Prometheus monitoring dashboard, copy the URL of this dashboard and paste it in the "Import page" in Grafana. After saving the dashboard, it should look like this:

+
Grafana 2
 +

Customization

+

The dashboards can be customized further. Each panel can be edited, moved, removed or added. To learn more about how dashboards work, refer to +Grafana's documentation.

+

Some users might also be interested in automatic alerting, which sets up alert notifications that are sent automatically when metrics reach certain values. Various communication channels are supported.

+

Summary

+

This page has outlined how to set up a simple node monitoring dashboard using Grafana.

+

NB: this page was adapted from a tutorial on ethereum.org written by Mario Havel

DOWNLOADS

DOCUMENTATION

© 2013–2025. The go-ethereum Authors | Do-not-Track

\ No newline at end of file From ec63a6c907575260bd2add29e796017275261978 Mon Sep 17 00:00:00 2001 From: Romeo Rosete <208020944+roseteromeo56@users.noreply.github.com> Date: Fri, 23 May 2025 20:31:13 -0400 Subject: [PATCH 25/25] Geth fundamentals _ go-ethereum.html Romeo Rosete --- Geth fundamentals _ go-ethereum.html | 8 ++++++++ 1 file changed, 8 insertions(+) create mode 100644 Geth fundamentals _ go-ethereum.html diff --git a/Geth fundamentals _ go-ethereum.html b/Geth fundamentals _ go-ethereum.html new file mode 100644 index 0000000000..6348574a42 --- /dev/null +++ b/Geth fundamentals _ go-ethereum.html @@ -0,0 +1,8 @@ + + +Geth fundamentals | go-ethereum

go-ethereum

skip to content

downloads

documentation

Geth fundamentals

Last edited on July 1, 2024

This section includes documentation for foundational topics in Geth. The pages here will help you to understand how Geth works from a user perspective and under the hood.

+

This is where you will find information about how to manage a Geth node and understand how it functions.

+

For example, the pages here will help you to understand the underlying architecture of your Geth node, how to start it in different configurations using command line options, how to sync the blockchain and how to manage accounts. There is a page on security practices that will help you to keep your Geth node safe from adversaries.

+

Note also that there is a page explaining common log messages that are often queried on the Geth discord and GitHub - this will help users to interpret the messages displayed to the console and know what actions to take.

+

In this section

+
  • Node architecture: learn about the three components of an Ethereum node and how they fit together
  • Command line options: see the various command line options that can be used to configure Geth
  • Security: learn about basic security best-practises for Geth
  • Sync-modes: learn about the different ways Geth can sync the blockchain
  • Beacon light sync: learn about the usage of Beacon light client, in integrated mode or standalone mode
  • Account management: read about how to manage accounts using Clef and Geth
  • Databases: learn about the two parts of database and the recommended database
  • Backup and restore: learn how to backup and restore data for a Geth instance
  • Logs: learn how to interpret the main log messages Geth displays in the console
  • Connecting-to-peers: learn about Geth's peer-to-peer networking
  • Pruning: read about Geth's data pruning options
  • Private networks via kurtosis: learn how to set up a private network of multiple Geth nodes using Kurtosis
  • Private networks: learn how to set up a private network of multiple Geth nodes
  • Config files: learn about using config files to tune Geth
  • Mining: read about the mining algorithms Geth used to use to secure Ethereum before the network switched to proof-of-stake.

DOWNLOADS

DOCUMENTATION

© 2013–2025. The go-ethereum Authors | Do-not-Track

\ No newline at end of file