diff --git a/docusaurus.config.js b/docusaurus.config.js index 52439e95ce5..2d9848a32f5 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -37,7 +37,7 @@ const config = { path: "./docs", includeCurrentVersion: true, // Set to the last stable release - lastVersion: "23.10.0", + lastVersion: "23.10.1", versions: { //defaults to the ./docs folder // using 'development' instead of 'next' as path @@ -46,8 +46,11 @@ const config = { path: "development", }, // The last stable release in the versioned_docs/version-stable + "23.10.1": { + label: "stable (23.10.1)", + }, "23.10.0": { - label: "stable (23.10.0)", + label: "23.10.0", }, "23.7.3": { label: "23.7.3", diff --git a/versioned_docs/version-23.10.1/assets/images/Besu-Tessera-High-Availability.png b/versioned_docs/version-23.10.1/assets/images/Besu-Tessera-High-Availability.png new file mode 100644 index 00000000000..12c9f0c36f6 Binary files /dev/null and b/versioned_docs/version-23.10.1/assets/images/Besu-Tessera-High-Availability.png differ diff --git a/versioned_docs/version-23.10.1/assets/images/Besu_TLS.png b/versioned_docs/version-23.10.1/assets/images/Besu_TLS.png new file mode 100644 index 00000000000..fafefc057b4 Binary files /dev/null and b/versioned_docs/version-23.10.1/assets/images/Besu_TLS.png differ diff --git a/versioned_docs/version-23.10.1/assets/images/Bonsai_tries.png b/versioned_docs/version-23.10.1/assets/images/Bonsai_tries.png new file mode 100644 index 00000000000..7e15f349bc4 Binary files /dev/null and b/versioned_docs/version-23.10.1/assets/images/Bonsai_tries.png differ diff --git a/versioned_docs/version-23.10.1/assets/images/CliqueOneIntialSigner.png b/versioned_docs/version-23.10.1/assets/images/CliqueOneIntialSigner.png new file mode 100644 index 00000000000..a04c660f776 Binary files /dev/null and b/versioned_docs/version-23.10.1/assets/images/CliqueOneIntialSigner.png differ diff --git a/versioned_docs/version-23.10.1/assets/images/CliqueTwoIntialSigners.png b/versioned_docs/version-23.10.1/assets/images/CliqueTwoIntialSigners.png new file mode 100644 index 00000000000..57831af0240 Binary files /dev/null and b/versioned_docs/version-23.10.1/assets/images/CliqueTwoIntialSigners.png differ diff --git a/versioned_docs/version-23.10.1/assets/images/EnodeStartup.png b/versioned_docs/version-23.10.1/assets/images/EnodeStartup.png new file mode 100644 index 00000000000..a0aea823b83 Binary files /dev/null and b/versioned_docs/version-23.10.1/assets/images/EnodeStartup.png differ diff --git a/versioned_docs/version-23.10.1/assets/images/Execution-Consensus-Clients.png b/versioned_docs/version-23.10.1/assets/images/Execution-Consensus-Clients.png new file mode 100644 index 00000000000..97c7962619c Binary files /dev/null and b/versioned_docs/version-23.10.1/assets/images/Execution-Consensus-Clients.png differ diff --git a/versioned_docs/version-23.10.1/assets/images/GraphiQL.png b/versioned_docs/version-23.10.1/assets/images/GraphiQL.png new file mode 100644 index 00000000000..3a8f9705ff1 Binary files /dev/null and b/versioned_docs/version-23.10.1/assets/images/GraphiQL.png differ diff --git a/versioned_docs/version-23.10.1/assets/images/Hyperledger-Besu-Client-Libraries.png b/versioned_docs/version-23.10.1/assets/images/Hyperledger-Besu-Client-Libraries.png new file mode 100644 index 00000000000..85bb59af754 Binary files /dev/null and b/versioned_docs/version-23.10.1/assets/images/Hyperledger-Besu-Client-Libraries.png differ diff --git a/versioned_docs/version-23.10.1/assets/images/Hyperledger-Besu-Plugin-API.png b/versioned_docs/version-23.10.1/assets/images/Hyperledger-Besu-Plugin-API.png new file mode 100644 index 00000000000..b5c4e56ac98 Binary files /dev/null and b/versioned_docs/version-23.10.1/assets/images/Hyperledger-Besu-Plugin-API.png differ diff --git a/versioned_docs/version-23.10.1/assets/images/JWT.png b/versioned_docs/version-23.10.1/assets/images/JWT.png new file mode 100644 index 00000000000..069e6488897 Binary files /dev/null and b/versioned_docs/version-23.10.1/assets/images/JWT.png differ diff --git a/versioned_docs/version-23.10.1/assets/images/KibanaQuickstart.png b/versioned_docs/version-23.10.1/assets/images/KibanaQuickstart.png new file mode 100644 index 00000000000..395337842c8 Binary files /dev/null and b/versioned_docs/version-23.10.1/assets/images/KibanaQuickstart.png differ diff --git a/versioned_docs/version-23.10.1/assets/images/LoadBalancer.png b/versioned_docs/version-23.10.1/assets/images/LoadBalancer.png new file mode 100644 index 00000000000..4c4c4aaf5f4 Binary files /dev/null and b/versioned_docs/version-23.10.1/assets/images/LoadBalancer.png differ diff --git a/versioned_docs/version-23.10.1/assets/images/Multi-tenancy.png b/versioned_docs/version-23.10.1/assets/images/Multi-tenancy.png new file mode 100644 index 00000000000..cbc3b537074 Binary files /dev/null and b/versioned_docs/version-23.10.1/assets/images/Multi-tenancy.png differ diff --git a/versioned_docs/version-23.10.1/assets/images/OrionNodes.png b/versioned_docs/version-23.10.1/assets/images/OrionNodes.png new file mode 100644 index 00000000000..a8fd413ccff Binary files /dev/null and b/versioned_docs/version-23.10.1/assets/images/OrionNodes.png differ diff --git a/versioned_docs/version-23.10.1/assets/images/PermissioningFlow.png b/versioned_docs/version-23.10.1/assets/images/PermissioningFlow.png new file mode 100644 index 00000000000..dafa2f6a94e Binary files /dev/null and b/versioned_docs/version-23.10.1/assets/images/PermissioningFlow.png differ diff --git a/versioned_docs/version-23.10.1/assets/images/PortConfiguration.png b/versioned_docs/version-23.10.1/assets/images/PortConfiguration.png new file mode 100644 index 00000000000..7522147db46 Binary files /dev/null and b/versioned_docs/version-23.10.1/assets/images/PortConfiguration.png differ diff --git a/versioned_docs/version-23.10.1/assets/images/PrivacyGroups.png b/versioned_docs/version-23.10.1/assets/images/PrivacyGroups.png new file mode 100644 index 00000000000..8d01cfa2720 Binary files /dev/null and b/versioned_docs/version-23.10.1/assets/images/PrivacyGroups.png differ diff --git a/versioned_docs/version-23.10.1/assets/images/PrivateTransactionProcessing.png b/versioned_docs/version-23.10.1/assets/images/PrivateTransactionProcessing.png new file mode 100644 index 00000000000..d8a2eecaa5f Binary files /dev/null and b/versioned_docs/version-23.10.1/assets/images/PrivateTransactionProcessing.png differ diff --git a/versioned_docs/version-23.10.1/assets/images/TesseraNodes.png b/versioned_docs/version-23.10.1/assets/images/TesseraNodes.png new file mode 100644 index 00000000000..5e195f403c5 Binary files /dev/null and b/versioned_docs/version-23.10.1/assets/images/TesseraNodes.png differ diff --git a/versioned_docs/version-23.10.1/assets/images/alethio-light-explorer-screenshot.png b/versioned_docs/version-23.10.1/assets/images/alethio-light-explorer-screenshot.png new file mode 100644 index 00000000000..b3bf1125004 Binary files /dev/null and b/versioned_docs/version-23.10.1/assets/images/alethio-light-explorer-screenshot.png differ diff --git a/versioned_docs/version-23.10.1/assets/images/besu-cpu-pattern-during-sync.png b/versioned_docs/version-23.10.1/assets/images/besu-cpu-pattern-during-sync.png new file mode 100644 index 00000000000..e345bb212dc Binary files /dev/null and b/versioned_docs/version-23.10.1/assets/images/besu-cpu-pattern-during-sync.png differ diff --git a/versioned_docs/version-23.10.1/assets/images/block-time.png b/versioned_docs/version-23.10.1/assets/images/block-time.png new file mode 100644 index 00000000000..914c186237d Binary files /dev/null and b/versioned_docs/version-23.10.1/assets/images/block-time.png differ diff --git a/versioned_docs/version-23.10.1/assets/images/chainlens-block-details.png b/versioned_docs/version-23.10.1/assets/images/chainlens-block-details.png new file mode 100644 index 00000000000..756a3145bb0 Binary files /dev/null and b/versioned_docs/version-23.10.1/assets/images/chainlens-block-details.png differ diff --git a/versioned_docs/version-23.10.1/assets/images/chainlens-block.png b/versioned_docs/version-23.10.1/assets/images/chainlens-block.png new file mode 100644 index 00000000000..be5efc1e408 Binary files /dev/null and b/versioned_docs/version-23.10.1/assets/images/chainlens-block.png differ diff --git a/versioned_docs/version-23.10.1/assets/images/chainlens-contract-details.png b/versioned_docs/version-23.10.1/assets/images/chainlens-contract-details.png new file mode 100644 index 00000000000..4afad979c29 Binary files /dev/null and b/versioned_docs/version-23.10.1/assets/images/chainlens-contract-details.png differ diff --git a/versioned_docs/version-23.10.1/assets/images/chainlens-contracts.png b/versioned_docs/version-23.10.1/assets/images/chainlens-contracts.png new file mode 100644 index 00000000000..fc2ea290c75 Binary files /dev/null and b/versioned_docs/version-23.10.1/assets/images/chainlens-contracts.png differ diff --git a/versioned_docs/version-23.10.1/assets/images/chainlens-dashboard.png b/versioned_docs/version-23.10.1/assets/images/chainlens-dashboard.png new file mode 100644 index 00000000000..5db9998e163 Binary files /dev/null and b/versioned_docs/version-23.10.1/assets/images/chainlens-dashboard.png differ diff --git a/versioned_docs/version-23.10.1/assets/images/chainlens-events.png b/versioned_docs/version-23.10.1/assets/images/chainlens-events.png new file mode 100644 index 00000000000..08540f9494a Binary files /dev/null and b/versioned_docs/version-23.10.1/assets/images/chainlens-events.png differ diff --git a/versioned_docs/version-23.10.1/assets/images/chainlens-loading.png b/versioned_docs/version-23.10.1/assets/images/chainlens-loading.png new file mode 100644 index 00000000000..499e1afa3eb Binary files /dev/null and b/versioned_docs/version-23.10.1/assets/images/chainlens-loading.png differ diff --git a/versioned_docs/version-23.10.1/assets/images/chainlens-transaction-details.png b/versioned_docs/version-23.10.1/assets/images/chainlens-transaction-details.png new file mode 100644 index 00000000000..39cd74e3f7e Binary files /dev/null and b/versioned_docs/version-23.10.1/assets/images/chainlens-transaction-details.png differ diff --git a/versioned_docs/version-23.10.1/assets/images/chainlens-transactions.png b/versioned_docs/version-23.10.1/assets/images/chainlens-transactions.png new file mode 100644 index 00000000000..e8aad29d83c Binary files /dev/null and b/versioned_docs/version-23.10.1/assets/images/chainlens-transactions.png differ diff --git a/versioned_docs/version-23.10.1/assets/images/create-resource-button-screenshot.png b/versioned_docs/version-23.10.1/assets/images/create-resource-button-screenshot.png new file mode 100644 index 00000000000..85de6d9eced Binary files /dev/null and b/versioned_docs/version-23.10.1/assets/images/create-resource-button-screenshot.png differ diff --git a/versioned_docs/version-23.10.1/assets/images/dapp-explorer-tx.png b/versioned_docs/version-23.10.1/assets/images/dapp-explorer-tx.png new file mode 100644 index 00000000000..700f5c47e74 Binary files /dev/null and b/versioned_docs/version-23.10.1/assets/images/dapp-explorer-tx.png differ diff --git a/versioned_docs/version-23.10.1/assets/images/dapp-metamask-tx.png b/versioned_docs/version-23.10.1/assets/images/dapp-metamask-tx.png new file mode 100644 index 00000000000..766a6eb59a5 Binary files /dev/null and b/versioned_docs/version-23.10.1/assets/images/dapp-metamask-tx.png differ diff --git a/versioned_docs/version-23.10.1/assets/images/dapp-ui.png b/versioned_docs/version-23.10.1/assets/images/dapp-ui.png new file mode 100644 index 00000000000..fc730254492 Binary files /dev/null and b/versioned_docs/version-23.10.1/assets/images/dapp-ui.png differ diff --git a/versioned_docs/version-23.10.1/assets/images/dashboard.png b/versioned_docs/version-23.10.1/assets/images/dashboard.png new file mode 100644 index 00000000000..761579ac613 Binary files /dev/null and b/versioned_docs/version-23.10.1/assets/images/dashboard.png differ diff --git a/versioned_docs/version-23.10.1/assets/images/deployment-complete-screenshot.png b/versioned_docs/version-23.10.1/assets/images/deployment-complete-screenshot.png new file mode 100644 index 00000000000..d16683d37bc Binary files /dev/null and b/versioned_docs/version-23.10.1/assets/images/deployment-complete-screenshot.png differ diff --git a/versioned_docs/version-23.10.1/assets/images/enterprise-ethereum-account-permissioning.png b/versioned_docs/version-23.10.1/assets/images/enterprise-ethereum-account-permissioning.png new file mode 100644 index 00000000000..684e01ccd8c Binary files /dev/null and b/versioned_docs/version-23.10.1/assets/images/enterprise-ethereum-account-permissioning.png differ diff --git a/versioned_docs/version-23.10.1/assets/images/ethstats.png b/versioned_docs/version-23.10.1/assets/images/ethstats.png new file mode 100644 index 00000000000..c491b24398a Binary files /dev/null and b/versioned_docs/version-23.10.1/assets/images/ethstats.png differ diff --git a/versioned_docs/version-23.10.1/assets/images/explorer.png b/versioned_docs/version-23.10.1/assets/images/explorer.png new file mode 100644 index 00000000000..6a3eb733ea5 Binary files /dev/null and b/versioned_docs/version-23.10.1/assets/images/explorer.png differ diff --git a/versioned_docs/version-23.10.1/assets/images/fastsync.png b/versioned_docs/version-23.10.1/assets/images/fastsync.png new file mode 100644 index 00000000000..7ab329c8769 Binary files /dev/null and b/versioned_docs/version-23.10.1/assets/images/fastsync.png differ diff --git a/versioned_docs/version-23.10.1/assets/images/forest_of_tries.png b/versioned_docs/version-23.10.1/assets/images/forest_of_tries.png new file mode 100644 index 00000000000..e6e73bbb954 Binary files /dev/null and b/versioned_docs/version-23.10.1/assets/images/forest_of_tries.png differ diff --git a/versioned_docs/version-23.10.1/assets/images/grafana.png b/versioned_docs/version-23.10.1/assets/images/grafana.png new file mode 100644 index 00000000000..c9339f249a7 Binary files /dev/null and b/versioned_docs/version-23.10.1/assets/images/grafana.png differ diff --git a/versioned_docs/version-23.10.1/assets/images/grafana_loki.png b/versioned_docs/version-23.10.1/assets/images/grafana_loki.png new file mode 100644 index 00000000000..7fcdbc9637d Binary files /dev/null and b/versioned_docs/version-23.10.1/assets/images/grafana_loki.png differ diff --git a/versioned_docs/version-23.10.1/assets/images/io-utilization.png b/versioned_docs/version-23.10.1/assets/images/io-utilization.png new file mode 100644 index 00000000000..fab930dd5d6 Binary files /dev/null and b/versioned_docs/version-23.10.1/assets/images/io-utilization.png differ diff --git a/versioned_docs/version-23.10.1/assets/images/kuberenetes-genesis-secrets.png b/versioned_docs/version-23.10.1/assets/images/kuberenetes-genesis-secrets.png new file mode 100644 index 00000000000..8b2b52441a9 Binary files /dev/null and b/versioned_docs/version-23.10.1/assets/images/kuberenetes-genesis-secrets.png differ diff --git a/versioned_docs/version-23.10.1/assets/images/kubernetes-1.jpeg b/versioned_docs/version-23.10.1/assets/images/kubernetes-1.jpeg new file mode 100644 index 00000000000..18ede0c091f Binary files /dev/null and b/versioned_docs/version-23.10.1/assets/images/kubernetes-1.jpeg differ diff --git a/versioned_docs/version-23.10.1/assets/images/kubernetes-2.jpeg b/versioned_docs/version-23.10.1/assets/images/kubernetes-2.jpeg new file mode 100644 index 00000000000..1e2c856f3c7 Binary files /dev/null and b/versioned_docs/version-23.10.1/assets/images/kubernetes-2.jpeg differ diff --git a/versioned_docs/version-23.10.1/assets/images/kubernetes-3.png b/versioned_docs/version-23.10.1/assets/images/kubernetes-3.png new file mode 100644 index 00000000000..8621c72f83d Binary files /dev/null and b/versioned_docs/version-23.10.1/assets/images/kubernetes-3.png differ diff --git a/versioned_docs/version-23.10.1/assets/images/kubernetes-bootnode-logs.png b/versioned_docs/version-23.10.1/assets/images/kubernetes-bootnode-logs.png new file mode 100644 index 00000000000..a11a61f2df0 Binary files /dev/null and b/versioned_docs/version-23.10.1/assets/images/kubernetes-bootnode-logs.png differ diff --git a/versioned_docs/version-23.10.1/assets/images/kubernetes-elastic.png b/versioned_docs/version-23.10.1/assets/images/kubernetes-elastic.png new file mode 100644 index 00000000000..46c99465e65 Binary files /dev/null and b/versioned_docs/version-23.10.1/assets/images/kubernetes-elastic.png differ diff --git a/versioned_docs/version-23.10.1/assets/images/kubernetes-explorer-contracts-1.png b/versioned_docs/version-23.10.1/assets/images/kubernetes-explorer-contracts-1.png new file mode 100644 index 00000000000..d27681af61b Binary files /dev/null and b/versioned_docs/version-23.10.1/assets/images/kubernetes-explorer-contracts-1.png differ diff --git a/versioned_docs/version-23.10.1/assets/images/kubernetes-explorer-contracts-set.png b/versioned_docs/version-23.10.1/assets/images/kubernetes-explorer-contracts-set.png new file mode 100644 index 00000000000..530c68deb13 Binary files /dev/null and b/versioned_docs/version-23.10.1/assets/images/kubernetes-explorer-contracts-set.png differ diff --git a/versioned_docs/version-23.10.1/assets/images/kubernetes-explorer-explorer.png b/versioned_docs/version-23.10.1/assets/images/kubernetes-explorer-explorer.png new file mode 100644 index 00000000000..9b169a4b7af Binary files /dev/null and b/versioned_docs/version-23.10.1/assets/images/kubernetes-explorer-explorer.png differ diff --git a/versioned_docs/version-23.10.1/assets/images/kubernetes-explorer-validators.png b/versioned_docs/version-23.10.1/assets/images/kubernetes-explorer-validators.png new file mode 100644 index 00000000000..58fb91cd849 Binary files /dev/null and b/versioned_docs/version-23.10.1/assets/images/kubernetes-explorer-validators.png differ diff --git a/versioned_docs/version-23.10.1/assets/images/kubernetes-explorer-wallet.png b/versioned_docs/version-23.10.1/assets/images/kubernetes-explorer-wallet.png new file mode 100644 index 00000000000..2f9eba7b253 Binary files /dev/null and b/versioned_docs/version-23.10.1/assets/images/kubernetes-explorer-wallet.png differ diff --git a/versioned_docs/version-23.10.1/assets/images/kubernetes-explorer.png b/versioned_docs/version-23.10.1/assets/images/kubernetes-explorer.png new file mode 100644 index 00000000000..ecde2ef11c0 Binary files /dev/null and b/versioned_docs/version-23.10.1/assets/images/kubernetes-explorer.png differ diff --git a/versioned_docs/version-23.10.1/assets/images/kubernetes-genesis-configmaps.png b/versioned_docs/version-23.10.1/assets/images/kubernetes-genesis-configmaps.png new file mode 100644 index 00000000000..71318e36c65 Binary files /dev/null and b/versioned_docs/version-23.10.1/assets/images/kubernetes-genesis-configmaps.png differ diff --git a/versioned_docs/version-23.10.1/assets/images/kubernetes-grafana.png b/versioned_docs/version-23.10.1/assets/images/kubernetes-grafana.png new file mode 100644 index 00000000000..545dfd89bd7 Binary files /dev/null and b/versioned_docs/version-23.10.1/assets/images/kubernetes-grafana.png differ diff --git a/versioned_docs/version-23.10.1/assets/images/kubernetes-ingress-ip.png b/versioned_docs/version-23.10.1/assets/images/kubernetes-ingress-ip.png new file mode 100644 index 00000000000..f14f4d895d2 Binary files /dev/null and b/versioned_docs/version-23.10.1/assets/images/kubernetes-ingress-ip.png differ diff --git a/versioned_docs/version-23.10.1/assets/images/kubernetes-monitoring.png b/versioned_docs/version-23.10.1/assets/images/kubernetes-monitoring.png new file mode 100644 index 00000000000..185e8b0f6f7 Binary files /dev/null and b/versioned_docs/version-23.10.1/assets/images/kubernetes-monitoring.png differ diff --git a/versioned_docs/version-23.10.1/assets/images/kubernetes-tx-Besu-logs.png b/versioned_docs/version-23.10.1/assets/images/kubernetes-tx-Besu-logs.png new file mode 100644 index 00000000000..8227a8a11e2 Binary files /dev/null and b/versioned_docs/version-23.10.1/assets/images/kubernetes-tx-Besu-logs.png differ diff --git a/versioned_docs/version-23.10.1/assets/images/kubernetes-tx-tessera-logs.png b/versioned_docs/version-23.10.1/assets/images/kubernetes-tx-tessera-logs.png new file mode 100644 index 00000000000..a146712cdf2 Binary files /dev/null and b/versioned_docs/version-23.10.1/assets/images/kubernetes-tx-tessera-logs.png differ diff --git a/versioned_docs/version-23.10.1/assets/images/kubernetes-validator-logs.png b/versioned_docs/version-23.10.1/assets/images/kubernetes-validator-logs.png new file mode 100644 index 00000000000..3b815e96012 Binary files /dev/null and b/versioned_docs/version-23.10.1/assets/images/kubernetes-validator-logs.png differ diff --git a/versioned_docs/version-23.10.1/assets/images/mp_0_landing.png b/versioned_docs/version-23.10.1/assets/images/mp_0_landing.png new file mode 100644 index 00000000000..4b44acaf580 Binary files /dev/null and b/versioned_docs/version-23.10.1/assets/images/mp_0_landing.png differ diff --git a/versioned_docs/version-23.10.1/assets/images/mp_10_ssh.png b/versioned_docs/version-23.10.1/assets/images/mp_10_ssh.png new file mode 100644 index 00000000000..1229060dba3 Binary files /dev/null and b/versioned_docs/version-23.10.1/assets/images/mp_10_ssh.png differ diff --git a/versioned_docs/version-23.10.1/assets/images/mp_1_basics.png b/versioned_docs/version-23.10.1/assets/images/mp_1_basics.png new file mode 100644 index 00000000000..ed6e98a9d24 Binary files /dev/null and b/versioned_docs/version-23.10.1/assets/images/mp_1_basics.png differ diff --git a/versioned_docs/version-23.10.1/assets/images/mp_2_size.png b/versioned_docs/version-23.10.1/assets/images/mp_2_size.png new file mode 100644 index 00000000000..f0f41a0cafe Binary files /dev/null and b/versioned_docs/version-23.10.1/assets/images/mp_2_size.png differ diff --git a/versioned_docs/version-23.10.1/assets/images/mp_4_deployment.png b/versioned_docs/version-23.10.1/assets/images/mp_4_deployment.png new file mode 100644 index 00000000000..858b2a4b53d Binary files /dev/null and b/versioned_docs/version-23.10.1/assets/images/mp_4_deployment.png differ diff --git a/versioned_docs/version-23.10.1/assets/images/mp_5_deployment_complete.png b/versioned_docs/version-23.10.1/assets/images/mp_5_deployment_complete.png new file mode 100644 index 00000000000..b10380c738b Binary files /dev/null and b/versioned_docs/version-23.10.1/assets/images/mp_5_deployment_complete.png differ diff --git a/versioned_docs/version-23.10.1/assets/images/mp_6_resource.png b/versioned_docs/version-23.10.1/assets/images/mp_6_resource.png new file mode 100644 index 00000000000..8307edc60ae Binary files /dev/null and b/versioned_docs/version-23.10.1/assets/images/mp_6_resource.png differ diff --git a/versioned_docs/version-23.10.1/assets/images/mp_7_vm.png b/versioned_docs/version-23.10.1/assets/images/mp_7_vm.png new file mode 100644 index 00000000000..b9519fa6fa0 Binary files /dev/null and b/versioned_docs/version-23.10.1/assets/images/mp_7_vm.png differ diff --git a/versioned_docs/version-23.10.1/assets/images/mp_8_block_explorer.png b/versioned_docs/version-23.10.1/assets/images/mp_8_block_explorer.png new file mode 100644 index 00000000000..c898b1ba5de Binary files /dev/null and b/versioned_docs/version-23.10.1/assets/images/mp_8_block_explorer.png differ diff --git a/versioned_docs/version-23.10.1/assets/images/mp_9_grafana.png b/versioned_docs/version-23.10.1/assets/images/mp_9_grafana.png new file mode 100644 index 00000000000..e37c0b9bade Binary files /dev/null and b/versioned_docs/version-23.10.1/assets/images/mp_9_grafana.png differ diff --git a/versioned_docs/version-23.10.1/assets/images/node-permissioning-bad-actor.png b/versioned_docs/version-23.10.1/assets/images/node-permissioning-bad-actor.png new file mode 100644 index 00000000000..b5e8952b51f Binary files /dev/null and b/versioned_docs/version-23.10.1/assets/images/node-permissioning-bad-actor.png differ diff --git a/versioned_docs/version-23.10.1/assets/images/postman-logo.svg b/versioned_docs/version-23.10.1/assets/images/postman-logo.svg new file mode 100644 index 00000000000..8ca967adafd --- /dev/null +++ b/versioned_docs/version-23.10.1/assets/images/postman-logo.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/versioned_docs/version-23.10.1/assets/images/private-architecture.jpeg b/versioned_docs/version-23.10.1/assets/images/private-architecture.jpeg new file mode 100644 index 00000000000..3d31c1a325f Binary files /dev/null and b/versioned_docs/version-23.10.1/assets/images/private-architecture.jpeg differ diff --git a/versioned_docs/version-23.10.1/assets/images/public-architecture.jpeg b/versioned_docs/version-23.10.1/assets/images/public-architecture.jpeg new file mode 100644 index 00000000000..f96066ee909 Binary files /dev/null and b/versioned_docs/version-23.10.1/assets/images/public-architecture.jpeg differ diff --git a/versioned_docs/version-23.10.1/assets/images/sampleNetworks-poa.png b/versioned_docs/version-23.10.1/assets/images/sampleNetworks-poa.png new file mode 100644 index 00000000000..64ecea2a8c8 Binary files /dev/null and b/versioned_docs/version-23.10.1/assets/images/sampleNetworks-poa.png differ diff --git a/versioned_docs/version-23.10.1/assets/images/sirato-network.png b/versioned_docs/version-23.10.1/assets/images/sirato-network.png new file mode 100644 index 00000000000..5d649b5eb5f Binary files /dev/null and b/versioned_docs/version-23.10.1/assets/images/sirato-network.png differ diff --git a/versioned_docs/version-23.10.1/assets/images/splunk-ui.png b/versioned_docs/version-23.10.1/assets/images/splunk-ui.png new file mode 100644 index 00000000000..d40b2b32ac8 Binary files /dev/null and b/versioned_docs/version-23.10.1/assets/images/splunk-ui.png differ diff --git a/versioned_docs/version-23.10.1/assets/images/system-load.png b/versioned_docs/version-23.10.1/assets/images/system-load.png new file mode 100644 index 00000000000..f3b15ec8e09 Binary files /dev/null and b/versioned_docs/version-23.10.1/assets/images/system-load.png differ diff --git a/versioned_docs/version-23.10.1/assets/images/transaction-validation.png b/versioned_docs/version-23.10.1/assets/images/transaction-validation.png new file mode 100644 index 00000000000..523139d8f9d Binary files /dev/null and b/versioned_docs/version-23.10.1/assets/images/transaction-validation.png differ diff --git a/versioned_docs/version-23.10.1/assets/postman/postman_collection.json b/versioned_docs/version-23.10.1/assets/postman/postman_collection.json new file mode 100644 index 00000000000..e86cdb37f98 --- /dev/null +++ b/versioned_docs/version-23.10.1/assets/postman/postman_collection.json @@ -0,0 +1,5780 @@ +{ + "info": { + "_postman_id": "f334929f-c8c3-43ed-bb73-69a6f0d728d8", + "name": "Hyperledger Besu JSON-RPC API", + "description": "Hyperledger Besu JSON-RPC API enables interaction with a Besu Ethereum node.\n\nRefer to [Besu documentation how to page](https://besu.hyperledger.org/en/stable/HowTo/Interact/APIs/Using-JSON-RPC-API/) to learn how to use this API.\n", + "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json" + }, + "item": [ + { + "name": "ADMIN", + "item": [ + { + "name": "admin_addPeer", + "event": [ + { + "listen": "test", + "script": { + "exec": [ + "pm.test(\"Result should be true\", () => {", + " //parse the response json", + " const responseJson = pm.response.json();", + " pm.expect(responseJson.id).to.eql(1);", + " pm.expect(responseJson.result).is.true;", + "});" + ], + "type": "text/javascript" + } + } + ], + "protocolProfileBehavior": { + "disabledSystemHeaders": { + "content-length": true, + "host": true + } + }, + "request": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"admin_addPeer\",\n \"params\": [\n \"enode://c93f69ddd83d3db3e93e5165d60b4f5d93a9731df776beee94c5f8a0c770e41bdea69094136402db0cef7af63f0aa636ff676d4a88c6d37276dfa4160c21ed5f@127.0.0.1:30303\"\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + }, + "description": "Adds a static node\n\n> **Caution**\n>\n> If connections are timing out, ensure the node ID in the enode URL is correct.\n\n#### Parameters\n\n`string` : Enode URL of peer to add\n\n#### Returns\n\n`result` : `boolean` - `true` if peer added or `false` if peer already a static node." + }, + "response": [ + { + "name": "admin_addPeer", + "originalRequest": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"admin_addPeer\",\n \"params\": [\n \"enode://c93f69ddd83d3db3e93e5165d60b4f5d93a9731df776beee94c5f8a0c770e41bdea69094136402db0cef7af63f0aa636ff676d4a88c6d37276dfa4160c21ed5f@127.0.0.1:30303\"\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + } + }, + "code": 200, + "_postman_previewlanguage": "json", + "header": null, + "cookie": [], + "body": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"result\": true\n}" + } + ] + }, + { + "name": "admin_changeLogLevel", + "request": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"admin_changeLogLevel\",\n \"params\": [\n \"DEBUG\"\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + }, + "description": "Changes the log level without restarting Besu. You can change the log level for all logs, or you\ncan change the log level for specific packages or classes.\n\nYou can specify only one log level per RPC call.\n\n#### Parameters\n\n`level` - [Log level](https://besu.hyperledger.org/en/stable/Reference/CLI/CLI-Syntax/#logging)\n\n`log_filter`: `Array` - Packages or classes to change the log level for. Optional.\n\n#### Returns\n\n`result` : `Success` if the log level has changed, otherwise `error`." + }, + "response": [ + { + "name": "admin_changeLogLevel", + "originalRequest": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"admin_changeLogLevel\",\n \"params\": [\n \"DEBUG\"\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + } + }, + "code": 200, + "_postman_previewlanguage": "json", + "header": null, + "cookie": [], + "body": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"result\": \"Success\"\n}" + } + ] + }, + { + "name": "admin_generateLogBloomCache", + "request": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"admin_generateLogBloomCache\",\n \"params\": [\n \"0x0\",\n \"0x10000\"\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + }, + "description": "Generates cached log bloom indexes for blocks. APIs such as [`eth_getLogs`](#eth_getlogs) and\n[`eth_getFilterLogs`](#eth_getfilterlogs) use the cache for improved performance.\n\n> **note**\n>\n> Each index file contains 100000 blocks. The last fragment of blocks less than 100000 are not indexed.\n\n> **tip**\n>\n> Manually executing `admin_generateLogBloomCache` is not required unless the [`--auto-log-bloom-caching-enabled`](https://besu.hyperledger.org/en/stable/Reference/CLI/CLI-Syntax/#auto-log-bloom-caching-enabled) command line option was set to false.\n\n#### Parameters\n\n`integer` - Block to start generating indexes.\n\n`integer` - Block to stop generating indexes.\n\n#### Returns\n\n`result` : *object* - Log bloom index details:\n\n* `quantity` : `startBlock` - Starting block for the last requested cache generation.\n* `quantity` : `endBlock` - Ending block for the last requested cache generation.\n* `quantity` : `currentBlock` - The most recent block added to the cache.\n* `boolean` : `indexing` - `true` if indexing is in progress.\n* `boolean` : `true` indicates acceptance of the request from this call to generate the cache." + }, + "response": [ + { + "name": "admin_generateLogBloomCache", + "originalRequest": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"admin_generateLogBloomCache\",\n \"params\": [\n \"0x0\",\n \"0x10000\"\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + } + }, + "code": 200, + "_postman_previewlanguage": "json", + "header": null, + "cookie": [], + "body": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"result\": {\n \"startBlock\": \"0x0\",\n \"endBlock\": \"0x10000\",\n \"currentBlock\": \"0x0\",\n \"indexing\": true,\n \"requestAccepted\": true\n }\n}" + } + ] + }, + { + "name": "admin_logsRepairCache", + "request": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"admin_logsRepairCache\",\n \"params\": [\n \"1200\"\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + }, + "description": "Repairs cached logs by fixing all segments starting with the specified block number.\n\n#### Parameters\n\n`quantity` - Decimal index of the starting block to fix. If left empty, the head block\nis used as the starting point.\n\n#### Returns\n\n`result` - Status of the repair request. Either `Started`, or `Already running`." + }, + "response": [ + { + "name": "admin_logsRepairCache", + "originalRequest": { + "method": "GET", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"admin_logsRepairCache\",\n \"params\": [\n \"1200\"\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + } + }, + "code": 200, + "_postman_previewlanguage": "json", + "header": null, + "cookie": [], + "body": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"result\": {\n \"Status\": \"Started\"\n }\n}" + } + ] + }, + { + "name": "admin_nodeInfo", + "request": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"admin_nodeInfo\",\n \"params\": [],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + }, + "description": "Returns networking information about the node. The information includes general information about\nthe node and specific information from each running Ethereum sub-protocol (for example, `eth`).\n\n#### Parameters\n\nNone\n\n#### Returns\n\n`result` : Node object\n\nProperties of the node object are:\n\n* `enode` - [Enode URL](https://besu.hyperledger.org/en/stable/Concepts/Node-Keys#enode-url) of the node.\n* `listenAddr` - Host and port for the node.\n* `name` - Client name.\n* `id` - [Node public key](https://besu.hyperledger.org/en/stable/Concepts/Node-Keys#node-public-key).\n* `ports` - Peer discovery and listening\n [ports](https://besu.hyperledger.org/en/stable/HowTo/Find-and-Connect/Managing-Peers#port-configuration).\n* `protocols` - List of objects containing information for each Ethereum sub-protocol.\n\n> **note**\n>\n> If the node is running locally, the host of the `enode` and `listenAddr` display as `[::]` in the result. When advertising externally, the external address displayed for the `enode` and `listenAddr` is defined by [`--nat-method`](https://besu.hyperledger.org/en/stable/HowTo/Find-and-Connect/Specifying-NAT).\n" + }, + "response": [ + { + "name": "admin_nodeInfo", + "originalRequest": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"admin_nodeInfo\",\n \"params\": [],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + } + }, + "code": 200, + "_postman_previewlanguage": "json", + "header": null, + "cookie": [], + "body": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"result\": {\n \"enode\": \"enode://87ec35d558352cc55cd1bf6a472557797f91287b78fe5e86760219124563450ad1bb807e4cc61e86c574189a851733227155551a14b9d0e1f62c5e11332a18a3@[::]:30303\",\n \"listenAddr\": \"[::]:30303\",\n \"name\": \"besu/v1.0.1-dev-0d2294a5/osx-x86_64/oracle-java-1.8\",\n \"id\": \"87ec35d558352cc55cd1bf6a472557797f91287b78fe5e86760219124563450ad1bb807e4cc61e86c574189a851733227155551a14b9d0e1f62c5e11332a18a3\",\n \"ports\": {\n \"discovery\": 30303,\n \"listener\": 30303\n },\n \"protocols\": {\n \"eth\": {\n \"config\": {\n \"chainId\": 2018,\n \"homesteadBlock\": 0,\n \"daoForkBlock\": 0,\n \"daoForkSupport\": true,\n \"eip150Block\": 0,\n \"eip155Block\": 0,\n \"eip158Block\": 0,\n \"byzantiumBlock\": 0,\n \"constantinopleBlock\": 0,\n \"constantinopleFixBlock\": 0,\n \"ethash\": {\n \"fixeddifficulty\": 100\n }\n },\n \"difficulty\": 78536,\n \"genesis\": \"0x43ee12d45470e57c86a0dfe008a5b847af9e372d05e8ba8f01434526eb2bea0f\",\n \"head\": \"0xc6677651f16d07ae59cab3a5e1f0b814ed2ec27c00a93297b2aa2e29707844d9\",\n \"network\": 2018\n }\n }\n }\n}" + } + ] + }, + { + "name": "admin_peers", + "request": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"admin_peers\",\n \"params\": [],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + }, + "description": "Returns networking information about connected remote nodes.\n\n#### Parameters\n\nNone\n\n#### Returns\n\n`result` : *array* of *objects* - Object returned for each remote node.\n\nProperties of the remote node object are:\n\n* `version` - P2P protocol version.\n* `name` - Client name.\n* `caps` - List of Ethereum sub-protocol capabilities.\n* `network` - Local and remote addresses established at time of bonding with the peer. The remote\n address might not match the hex value for `port`. The remote address depends on which node\n initiated the connection.\n* `port` - Port on the remote node on which P2P discovery is listening.\n* `id` - Node public key. Excluding the `0x` prefix, the node public key is the ID in the enode\n URL `enode://@:`.\n* `protocols` - [Current state of peer](https://besu.hyperledger.org/en/stable/HowTo/Find-and-Connect/Managing-Peers#monitoring-peer-connections)\n including `difficulty` and `head`. `head` is the hash of the highest known block for the peer." + }, + "response": [ + { + "name": "admin_peers", + "originalRequest": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"admin_peers\",\n \"params\": [],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + } + }, + "code": 200, + "_postman_previewlanguage": "json", + "header": null, + "cookie": [], + "body": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"result\": [\n {\n \"version\": \"0x5\",\n \"name\": \"besu/v20.10.4-dev-0905d1b2/osx-x86_64/adoptopenjdk-java-11\",\n \"caps\": [\n \"eth/62\",\n \"eth/63\",\n \"eth/64\",\n \"eth/65\",\n \"IBF/1\"\n ],\n \"network\": {\n \"localAddress\": \"192.168.1.229:50115\",\n \"remoteAddress\": \"168.61.153.255:40303\"\n },\n \"port\": \"0x765f\",\n \"id\": \"0xe143eadaf670d49afa3327cae2e655b083f5a89dac037c9af065914a9f8e6bceebcfe7ae2258bd22a9cd18b6a6de07b9790e71de49b78afa456e401bd2fb22fc\",\n \"protocols\": {\n \"eth\": {\n \"difficulty\": \"0x1ac\",\n \"head\": \"0x964090ae9277aef43f47f1b8c28411f162243d523118605f0b1231dbfdf3611a\",\n \"version\": 65\n }\n }\n }\n ]\n}" + } + ] + }, + { + "name": "admin_removePeer", + "request": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"admin_removePeer\",\n \"params\": [\n \"enode://f59c0ab603377b6ec88b89d5bb41b98fc385030ab1e4b03752db6f7dab364559d92c757c13116ae6408d2d33f0138e7812eb8b696b2a22fe3332c4b5127b22a3@127.0.0.1:30304\"\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + }, + "description": "Removes a [static node](https://besu.hyperledger.org/en/stable/HowTo/Find-and-Connect/Static-Nodes).\n\n#### Parameters\n\n`string` : [Enode URL](https://besu.hyperledger.org/en/stable/Concepts/Node-Keys#enode-url) of peer to remove.\n\n#### Returns\n\n`result` : `boolean` - `true` if peer removed or `false` if peer not a\n[static node](https://besu.hyperledger.org/en/stable/HowTo/Find-and-Connect/Static-Nodes))." + }, + "response": [ + { + "name": "admin_removePeer", + "originalRequest": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"admin_removePeer\",\n \"params\": [\n \"enode://f59c0ab603377b6ec88b89d5bb41b98fc385030ab1e4b03752db6f7dab364559d92c757c13116ae6408d2d33f0138e7812eb8b696b2a22fe3332c4b5127b22a3@127.0.0.1:30304\"\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + } + }, + "code": 200, + "_postman_previewlanguage": "json", + "header": null, + "cookie": [], + "body": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"result\": true\n}" + } + ] + } + ], + "description": "> **Note**\n>\n> The `ADMIN` API methods are not enabled by default for JSON-RPC. To enable the `ADMIN` API methods, use the [`--rpc-http-api`](https://besu.hyperledger.org/en/stable/CLI/CLI-Syntax#rpc-http-api) or\n[`--rpc-ws-api`](https://besu.hyperledger.org/en/stable/CLI/CLI-Syntax#rpc-ws-api) options.", + "event": [ + { + "listen": "prerequest", + "script": { + "type": "text/javascript", + "exec": [""] + } + }, + { + "listen": "test", + "script": { + "type": "text/javascript", + "exec": [""] + } + } + ] + }, + { + "name": "CLIQUE", + "item": [ + { + "name": "clique_discard", + "request": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"clique_discard\",\n \"params\": [\n \"0x42eb768f2244c8811c63729a21a3569731535f06\"\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + }, + "description": "Discards a proposal to [add or remove a signer with the specified address].\n\n#### Parameters\n\n`data` - 20-byte address of proposed signer.\n\n#### Returns\n\n`result: boolean` - `true`" + }, + "response": [ + { + "name": "clique_discard", + "originalRequest": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"clique_discard\",\n \"params\": [\n \"0x42eb768f2244c8811c63729a21a3569731535f06\"\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + } + }, + "code": 200, + "_postman_previewlanguage": "json", + "header": null, + "cookie": [], + "body": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"result\": true\n}" + } + ] + }, + { + "name": "clique_getSignerMetrics", + "request": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"clique_getSignerMetrics\",\n \"params\": [\n \"1\",\n \"100\"\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + }, + "description": "Provides validator metrics for the specified range:\n\n* Number of blocks from each validator.\n* Block number of the last block proposed by each validator (if any proposed in the specified\n range).\n* All validators present in the last block.\n\n#### Parameters\n\n`fromBlockNumber` - Integer representing a block number or the string tag `earliest`, as described\nin [Block Parameter](https://besu.hyperledger.org/en/stable/HowTo/Interact/APIs/Using-JSON-RPC-API#block-parameter).\n\n`toBlockNumber` - Integer representing a block number or one of the string tags `latest` or\n`pending`, as described in\n[Block Parameter](https://besu.hyperledger.org/en/stable/HowTo/Interact/APIs/Using-JSON-RPC-API#block-parameter)\n\nIf you specify:\n\n* No parameters, the call provides metrics for the last 100 blocks, or all blocks if there are less\n than 100 blocks.\n* Only the first parameter, the call provides metrics for all blocks from the block specified to\n the latest block.\n\n#### Returns\n\n`result`: _object_ - List of validator objects.\n\n> **Note**\n>\n> The proposer of the genesis block has address `0x0000000000000000000000000000000000000000`." + }, + "response": [ + { + "name": "clique_getSignerMetrics", + "originalRequest": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"clique_getSignerMetrics\",\n \"params\": [\n \"1\",\n \"100\"\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + } + }, + "code": 200, + "_postman_previewlanguage": "json", + "header": null, + "cookie": [], + "body": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"result\": [\n {\n \"address\": \"0x7ffc57839b00206d1ad20c69a1981b489f772031\",\n \"proposedBlockCount\": \"0x21\",\n \"lastProposedBlockNumber\": \"0x61\"\n },\n {\n \"address\": \"0x42eb768f2244c8811c63729a21a3569731535f06\",\n \"proposedBlockCount\": \"0x21\",\n \"lastProposedBlockNumber\": \"0x63\"\n },\n {\n \"address\": \"0xb279182d99e65703f0076e4812653aab85fca0f0\",\n \"proposedBlockCount\": \"0x21\",\n \"lastProposedBlockNumber\": \"0x62\"\n }\n ]\n}" + } + ] + }, + { + "name": "clique_getSigners", + "request": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"clique_getSigners\",\n \"params\": [\n \"latest\"\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + }, + "description": "Lists [signers for the specified block].\n\n#### Parameters\n\n`quantity|tag` - Integer representing a block number or one of the string tags `latest`,\n`earliest`, or `pending`, as described in\n[Block Parameter](https://besu.hyperledger.org/en/stable/HowTo/Interact/APIs/Using-JSON-RPC-API#block-parameter).\n\n#### Returns\n\n`result: array of data` - List of 20-byte addresses of signers." + }, + "response": [ + { + "name": "clique_getSigners", + "originalRequest": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"clique_getSigners\",\n \"params\": [\n \"latest\"\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + } + }, + "code": 200, + "_postman_previewlanguage": "json", + "header": null, + "cookie": [], + "body": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"result\": [\n \"0x42eb768f2244c8811c63729a21a3569731535f06\",\n \"0x7ffc57839b00206d1ad20c69a1981b489f772031\",\n \"0xb279182d99e65703f0076e4812653aab85fca0f0\"\n ]\n}" + } + ] + }, + { + "name": "clique_getSignersAtHash", + "request": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"clique_getSignersAtHash\",\n \"params\": [\n \"0x98b2ddb5106b03649d2d337d42154702796438b3c74fd25a5782940e84237a48\"\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + }, + "description": "Lists signers for the specified block.\n\n#### Parameters\n\n`data` - 32-byte block hash.\n\n#### Returns\n\n`result: array of data` - List of 20-byte addresses of signers." + }, + "response": [ + { + "name": "clique_getSignersAtHash", + "originalRequest": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"clique_getSignersAtHash\",\n \"params\": [\n \"0x98b2ddb5106b03649d2d337d42154702796438b3c74fd25a5782940e84237a48\"\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + } + }, + "code": 200, + "_postman_previewlanguage": "json", + "header": null, + "cookie": [], + "body": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"result\": [\n \"0x42eb768f2244c8811c63729a21a3569731535f06\",\n \"0x7ffc57839b00206d1ad20c69a1981b489f772031\",\n \"0xb279182d99e65703f0076e4812653aab85fca0f0\"\n ]\n}" + } + ] + }, + { + "name": "clique_proposals", + "request": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"clique_proposals\",\n \"params\": [],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + }, + "description": "Returns\n[current proposals](https://besu.hyperledger.org/en/stable/HowTo/Configure/Consensus-Protocols/Clique#adding-and-removing-signers).\n\n#### Parameters\n\nNone\n\n#### Returns\n\n`result`:_object_ - Map of account addresses to corresponding boolean values indicating the\nproposal for each account.\n\nIf the boolean value is `true`, the proposal is to add a signer. If `false`, the proposal is to\nremove a signer." + }, + "response": [ + { + "name": "clique_proposals", + "originalRequest": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"clique_proposals\",\n \"params\": [],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + } + }, + "code": 200, + "_postman_previewlanguage": "json", + "header": null, + "cookie": [], + "body": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"result\": {\n \"0x42eb768f2244c8811c63729a21a3569731535f07\": false,\n \"0x12eb759f2222d7711c63729a45c3585731521d01\": true\n }\n}" + } + ] + }, + { + "name": "clique_propose", + "request": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"clique_propose\",\n \"params\": [\n \"0x12eb759f2222d7711c63729a45c3585731521d01\",\n true\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + }, + "description": "Propose to [add or remove a signer with the specified address].\n\n#### Parameters\n\n`data` - 20-byte address.\n\n`boolean` - `true` to propose adding signer or `false` to propose removing signer.\n\n#### Returns\n\n`result: boolean` - `true`" + }, + "response": [ + { + "name": "clique_propose", + "originalRequest": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"clique_propose\",\n \"params\": [\n \"0x12eb759f2222d7711c63729a45c3585731521d01\",\n true\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + } + }, + "code": 200, + "_postman_previewlanguage": "json", + "header": null, + "cookie": [], + "body": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"result\": true\n}" + } + ] + } + ], + "description": "> Note\n>\n> The `CLIQUE` API methods are not enabled by default for JSON-RPC.\n>\n> To enable the `CLIQUE` API methods use the [`--rpc-http-api`](https://besu.hyperledger.org/en/stable/CLI/CLI-Syntax#rpc-http-api) or [`--rpc-ws-api`](https://besu.hyperledger.org/en/stable/CLI/CLI-Syntax#rpc-ws-api) options." + }, + { + "name": "DEBUG", + "item": [ + { + "name": "debug_accountRange", + "request": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"debug_accountRange\",\n \"params\": [\n \"12345\",\n 0,\n \"0\",\n 5\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + }, + "description": "[Retesteth](https://github.com/ethereum/retesteth/wiki/Retesteth-Overview) uses\n`debug_accountRange` to implement debugging.\n\nReturns the accounts for a specified block.\n\n#### Parameters\n\n`blockHashOrNumber` : `data` - Block hash or number.\n\n`txIndex` : `integer` - Transaction index from which to start.\n\n`address` : `data` - Address hash from which to start.\n\n`limit` : `integer` - Maximum number of account entries to return.\n\n#### Returns\n\n`result`:`object` - Account details:\n\n* `addressMap`:`object` - List of address hashes and account addresses.\n* `nextKey`:`data` - Hash of the next address if any addresses remain in the state, otherwise\n zero.\n" + }, + "response": [ + { + "name": "debug_accountRange", + "originalRequest": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"debug_accountRange\",\n \"params\": [\n \"12345\",\n 0,\n \"0\",\n 5\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + } + }, + "code": 200, + "_postman_previewlanguage": "json", + "header": null, + "cookie": [], + "body": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"result\": {\n \"addressMap\": {\n \"0x005e5...86960\": \"0x0000000000000000000000000000000000000000\",\n \"0x021fe...6ffe3\": \"0x0000000000000000000000000000000000000000\",\n \"0x028e6...ab776\": \"0x0000000000000000000000000000000000000000\",\n \"0x02cb5...bc4d8\": \"0x0000000000000000000000000000000000000000\",\n \"0x03089...23fd5\": \"0x0000000000000000000000000000000000000000\"\n },\n \"nextKey\": \"0x04242954a5cb9748d3f66bcd4583fd3830287aa585bebd9dd06fa6625976be49\"\n }\n}" + } + ] + }, + { + "name": "debug_metrics", + "request": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"debug_metrics\",\n \"params\": [],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + }, + "description": "Returns metrics providing information on the internal operation of Besu.\n\nThe available metrics might change over time. The JVM metrics might vary based on the JVM\nimplementation used.\n\nThe metric types are:\n\n* Timer\n* Counter\n* Gauge.\n\n#### Parameters\n\nNone\n\n#### Returns\n\n`result`:`object`" + }, + "response": [ + { + "name": "debug_metrics", + "originalRequest": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"debug_metrics\",\n \"params\": [],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + } + }, + "code": 200, + "_postman_previewlanguage": "json", + "header": null, + "cookie": [], + "body": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"result\": {\n \"jvm\": {\n \"memory_bytes_init\": {\n \"heap\": 268435456,\n \"nonheap\": 2555904\n },\n \"threads_current\": 41,\n \"memory_bytes_used\": {\n \"heap\": 696923976,\n \"nonheap\": 63633456\n },\n \"memory_pool_bytes_used\": {\n \"PS Eden Space\": 669119360,\n \"Code Cache\": 19689024,\n \"Compressed Class Space\": 4871144,\n \"PS Survivor Space\": 2716320,\n \"PS Old Gen\": 25088296,\n \"Metaspace\": 39073288\n },\n \"other properties...\":\"values...\"\n },\n \"process\": {\n \"open_fds\": 546,\n \"cpu_seconds_total\": 67.148992,\n \"start_time_seconds\": 1543897699.589,\n \"max_fds\": 10240\n },\n \"rpc\": {\n \"request_time\": {\n \"debug_metrics\": {\n \"bucket\": {\n \"+Inf\": 2,\n \"0.01\": 1,\n \"0.075\": 2,\n \"0.75\": 2,\n \"0.005\": 1,\n \"0.025\": 2,\n \"0.1\": 2,\n \"1.0\": 2,\n \"0.05\": 2,\n \"10.0\": 2,\n \"0.25\": 2,\n \"0.5\": 2,\n \"5.0\": 2,\n \"2.5\": 2,\n \"7.5\": 2\n },\n \"count\": 2,\n \"sum\": 0.015925392\n }\n }\n },\n \"blockchain\": {\n \"difficulty_total\": 3533501,\n \"announcedBlock_ingest\": {\n \"bucket\": {\n \"+Inf\": 0,\n \"0.01\": 0,\n \"0.075\": 0,\n \"0.75\": 0,\n \"0.005\": 0,\n \"0.025\": 0,\n \"0.1\": 0,\n \"1.0\": 0,\n \"0.05\": 0,\n \"10.0\": 0,\n \"0.25\": 0,\n \"0.5\": 0,\n \"5.0\": 0,\n \"2.5\": 0,\n \"7.5\": 0\n },\n \"count\": 0,\n \"sum\": 0\n },\n \"height\": 1908793\n },\n \"peers\": {\n \"disconnected_total\": {\n \"remote\": {\n \"SUBPROTOCOL_TRIGGERED\": 5\n },\n \"local\": {\n \"TCP_SUBSYSTEM_ERROR\": 1,\n \"SUBPROTOCOL_TRIGGERED\": 2,\n \"USELESS_PEER\": 3\n }\n },\n \"peer_count_current\": 2,\n \"connected_total\": 10\n }\n }\n}" + } + ] + }, + { + "name": "debug_storageRangeAt", + "request": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"debug_storageRangeAt\",\n \"params\": [\n \"0x2b76b3a2fc44c0e21ea183d06c846353279a7acf12abcc6fb9d5e8fb14ae2f8c\",\n 0,\n \"0x0e0d2c8f7794e82164f11798276a188147fbd415\",\n \"0x0000000000000000000000000000000000000000000000000000000000000000\",\n 1\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + }, + "description": "[Remix](https://remix.ethereum.org/) uses `debug_storageRangeAt` to implement debugging. Use the\n_Debugger_ tab in Remix instead of calling `debug_storageRangeAt` directly.\n\nReturns the contract storage for the specified range.\n\n#### Parameters\n\n`blockHash` : `data` - Block hash.\n\n`txIndex` : `integer` - Transaction index from which to start.\n\n`address` : `data` - Contract address.\n\n`startKey` : `hash` - Start key.\n\n`limit` : `integer` - Number of storage entries to return.\n\n#### Returns\n\n`result`:`object` - [Range object](https://besu.hyperledger.org/en/stable/Reference/API-Objects#range-object).\n" + }, + "response": [ + { + "name": "debug_storageRangeAt", + "originalRequest": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"debug_storageRangeAt\",\n \"params\": [\n \"0x2b76b3a2fc44c0e21ea183d06c846353279a7acf12abcc6fb9d5e8fb14ae2f8c\",\n 0,\n \"0x0e0d2c8f7794e82164f11798276a188147fbd415\",\n \"0x0000000000000000000000000000000000000000000000000000000000000000\",\n 1\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + } + }, + "code": 200, + "_postman_previewlanguage": "json", + "header": null, + "cookie": [], + "body": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"result\": {\n \"storage\": {\n \"0x290decd9548b62a8d60345a988386fc84ba6bc95484008f6362f93160ef3e563\": {\n \"key\": null,\n \"value\": \"0x0000000000000000000000000000000000000000000000000000000000000001\"\n }\n },\n \"nextKey\": \"0xb10e2d527612073b26eecdfd717e6a320cf44b4afac2b0732d9fcbe2b7fa0cf6\"\n }\n}" + } + ] + }, + { + "name": "debug_traceBlock", + "request": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"debug_traceBlock\",\n \"params\": [\n \"0xf90277f90208a05a41d0e66b4120775176c09fcf39e7c0520517a13d2b57b18d33d342df038bfca01dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d4934794e6a7a1d47ff21b6321162aea7c6cb457d5476bcaa00e0df2706b0a4fb8bd08c9246d472abbe850af446405d9eba1db41db18b4a169a04513310fcb9f6f616972a3b948dc5d547f280849a87ebb5af0191f98b87be598a0fe2bf2a941abf41d72637e5b91750332a30283efd40c424dc522b77e6f0ed8c4b9010000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000860153886c1bbd82b44382520b8252088455c426598b657468706f6f6c2e6f7267a0b48c515a9dde8d346c3337ea520aa995a4738bb595495506125449c1149d6cf488ba4f8ecd18aab215f869f86780862d79883d2000825208945df9b87991262f6ba471f09758cde1c0fc1de734827a69801ca088ff6cf0fefd94db46111149ae4bfc179e9b94721fffd821d38d16464b3f71d0a045e0aff800961cfce805daef7016b9b675c137a6a41a548f7b60a3484c06a33ac0\"\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + }, + "description": "Returns full trace of all invoked opcodes of all transactions included in the block.\n\n#### Parameters\n\n`Block` : `data` - RLP of the block.\n\n`Object` - request options (all optional and default to `false`):\n\n* `disableStorage` : `boolean` - `true` disables storage capture.\n* `disableMemory` : `boolean` - `true` disables memory capture.\n* `disableStack` : `boolean` - `true` disables stack capture.\n\n#### Returns\n\n`result`:`object` - [Trace object](https://besu.hyperledger.org/en/stable/Reference/API-Objects#trace-object).\n" + }, + "response": [ + { + "name": "debug_traceBlock", + "originalRequest": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"debug_traceBlock\",\n \"params\": [\n \"0xf90277f90208a05a41d0e66b4120775176c09fcf39e7c0520517a13d2b57b18d33d342df038bfca01dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d4934794e6a7a1d47ff21b6321162aea7c6cb457d5476bcaa00e0df2706b0a4fb8bd08c9246d472abbe850af446405d9eba1db41db18b4a169a04513310fcb9f6f616972a3b948dc5d547f280849a87ebb5af0191f98b87be598a0fe2bf2a941abf41d72637e5b91750332a30283efd40c424dc522b77e6f0ed8c4b9010000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000860153886c1bbd82b44382520b8252088455c426598b657468706f6f6c2e6f7267a0b48c515a9dde8d346c3337ea520aa995a4738bb595495506125449c1149d6cf488ba4f8ecd18aab215f869f86780862d79883d2000825208945df9b87991262f6ba471f09758cde1c0fc1de734827a69801ca088ff6cf0fefd94db46111149ae4bfc179e9b94721fffd821d38d16464b3f71d0a045e0aff800961cfce805daef7016b9b675c137a6a41a548f7b60a3484c06a33ac0\"\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + } + }, + "code": 200, + "_postman_previewlanguage": "json", + "header": null, + "cookie": [], + "body": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"result\": {\n \"gas\": 21000,\n \"failed\": false,\n \"returnValue\": \"\",\n \"structLogs\": [\n {\n \"pc\": 0,\n \"op\": \"STOP\",\n \"gas\": 0,\n \"gasCost\": 0,\n \"depth\": 1,\n \"stack\": [],\n \"memory\": [],\n \"storage\": null\n }\n ]\n }\n}" + } + ] + }, + { + "name": "debug_traceBlockByHash", + "request": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"debug_traceBlockByHash\",\n \"params\": [\n \"0xaceb3b2c9b25b0589230873921eb894b28722011b8df63977145517d754875a5\"\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + }, + "description": "Returns full trace of all invoked opcodes of all transactions included in the block.\n\n#### Parameters\n\n`block hash` : `data` - Block hash.\n\n`Object` - request options (all optional and default to `false`):\n\n* `disableStorage` : `boolean` - `true` disables storage capture.\n* `disableMemory` : `boolean` - `true` disables memory capture.\n* `disableStack` : `boolean` - `true` disables stack capture.\n\n#### Returns\n\n`result`:`array of objects` - [Trace objects](https://besu.hyperledger.org/en/stable/Reference/API-Objects#trace-object)." + }, + "response": [ + { + "name": "debug_traceBlockByHash", + "originalRequest": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"debug_traceBlockByHash\",\n \"params\": [\n \"0xaceb3b2c9b25b0589230873921eb894b28722011b8df63977145517d754875a5\"\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + } + }, + "code": 200, + "_postman_previewlanguage": "json", + "header": null, + "cookie": [], + "body": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"result\": [\n {\n \"gas\": 21000,\n \"failed\": false,\n \"returnValue\": \"\",\n \"structLogs\": [\n {\n \"pc\": 0,\n \"op\": \"STOP\",\n \"gas\": 0,\n \"gasCost\": 0,\n \"depth\": 1,\n \"stack\": [],\n \"memory\": [],\n \"storage\": {},\n \"reason\": null\n }\n ]\n }\n ]\n}" + } + ] + }, + { + "name": "debug_traceBlockByNumber", + "request": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"debug_traceBlockByNumber\",\n \"params\": [\n \"0xaceb3b2c9b25b0589230873921eb894b28722011b8df63977145517d754875a5\"\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + }, + "description": "Returns full trace of all invoked opcodes of all transactions included in the block.\n\n#### Parameters\n\n`quantity|tag` - Integer representing a block number or one of the string tags `latest`,\n`earliest`, or `pending`, as described in\n[Block Parameter](https://besu.hyperledger.org/en/stable/HowTo/Interact/APIs/Using-JSON-RPC-API#block-parameter).\n\n`Object` - request options (all optional and default to `false`):\n\n* `disableStorage` : `boolean` - `true` disables storage capture.\n* `disableMemory` : `boolean` - `true` disables memory capture.\n* `disableStack` : `boolean` - `true` disables stack capture.\n\n#### Returns\n\n`result`:`array of objects` - [Trace objects](https://besu.hyperledger.org/en/stable/Reference/API-Objects#trace-object)." + }, + "response": [ + { + "name": "debug_traceBlockByNumber", + "originalRequest": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"debug_traceBlockByNumber\",\n \"params\": [\n \"0xaceb3b2c9b25b0589230873921eb894b28722011b8df63977145517d754875a5\"\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + } + }, + "code": 200, + "_postman_previewlanguage": "json", + "header": null, + "cookie": [], + "body": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"result\": [\n {\n \"gas\": 21000,\n \"failed\": false,\n \"returnValue\": \"\",\n \"structLogs\": [\n {\n \"pc\": 0,\n \"op\": \"STOP\",\n \"gas\": 0,\n \"gasCost\": 0,\n \"depth\": 1,\n \"stack\": [],\n \"memory\": [],\n \"storage\": null,\n \"reason\": null\n }\n ]\n }\n ]\n}" + } + ] + }, + { + "name": "debug_traceTransaction", + "request": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"debug_traceTransaction\",\n \"params\": [\n \"0x2cc6c94c21685b7e0f8ddabf277a5ccf98db157c62619cde8baea696a74ed18e\",\n {\n \"disableStorage\": true\n }\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + }, + "description": "[Remix](https://remix.ethereum.org/) uses `debug_traceTransaction` to implement debugging. Use the\n_Debugger_ tab in Remix instead of calling `debug_traceTransaction` directly.\n\nReruns the transaction with the same state as when the transaction executed.\n\n#### Parameters\n\n`transactionHash` : `data` - Transaction hash.\n\n`Object` - request options (all optional and default to `false`):\n\n* `disableStorage` : `boolean` - `true` disables storage capture.\n* `disableMemory` : `boolean` - `true` disables memory capture.\n* `disableStack` : `boolean` - `true` disables stack capture.\n\n#### Returns\n\n`result`:`object` - [Trace object](https://besu.hyperledger.org/en/stable/Reference/API-Objects#trace-object).\n" + }, + "response": [ + { + "name": "debug_traceTransaction", + "originalRequest": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"debug_traceTransaction\",\n \"params\": [\n \"0x2cc6c94c21685b7e0f8ddabf277a5ccf98db157c62619cde8baea696a74ed18e\",\n {\n \"disableStorage\": true\n }\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + } + }, + "code": 200, + "_postman_previewlanguage": "json", + "header": null, + "cookie": [], + "body": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"result\": {\n \"gas\": 21000,\n \"failed\": false,\n \"returnValue\": \"\",\n \"structLogs\": [\n {\n \"pc\": 0,\n \"op\": \"STOP\",\n \"gas\": 0,\n \"gasCost\": 0,\n \"depth\": 1,\n \"stack\": [],\n \"memory\": [],\n \"storage\": null\n }\n ]\n }\n}" + } + ] + } + ], + "description": "> **Note**\n>\n> The `DEBUG` API methods are not enabled by default for JSON-RPC. To enable the `DEBUG` API methods, use the [`--rpc-http-api`](https://besu.hyperledger.org/en/stable/CLI/CLI-Syntax#rpc-http-api) or [`--rpc-ws-api`](https://besu.hyperledger.org/en/stable/CLI/CLI-Syntax#rpc-ws-api) options.\n\nThe DEBUG API is a more verbose alternative to the TRACE API whose main purpose is compatibility with tools such as [Remix](https://remix.ethereum.org/). We recommend using the TRACE API for production use over the DEBUG API." + }, + { + "name": "EEA", + "item": [ + { + "name": "eea_sendRawTransaction", + "request": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"eea_sendRawTransaction\",\n \"params\": [\n \"0xf869018203e882520894f17f52151ebef6c7334fad080c5704d77216b732881bc16d674ec80000801ba02da1c48b670996dcb1f447ef9ef00b33033c48a4fe938f420bec3e56bfd24071a062e0aa78a81bf0290afbc3a9d8e9a068e6d74caa66c5e0fa8a46deaae96b0833\"\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + }, + "description": "Distributes the\n[private transaction](https://besu.hyperledger.org/en/stable/HowTo/Send-Transactions/Creating-Sending-Private-Transactions),\ngenerates the [privacy marker transaction](https://besu.hyperledger.org/en/stable/Concepts/Privacy/Private-Transaction-Processing)\nand submits it to the transaction pool, and returns the transaction hash of the\n[privacy marker transaction](https://besu.hyperledger.org/en/stable/Concepts/Privacy/Private-Transaction-Processing).\n\nThe signed transaction passed as an input parameter includes the `privateFrom`,\n[`privateFor` or `privacyGroupId`](https://besu.hyperledger.org/en/stable/HowTo/Send-Transactions/Creating-Sending-Private-Transactions#eea-compliant-or-besu-extended-privacy),\nand `restriction` fields.\n\nThe `gas` and `gasPrice` are used by the [privacy marker transaction](https://besu.hyperledger.org/en/stable/Concepts/Privacy/Private-Transaction-Processing)\nnot the private transaction itself.\n\nTo avoid exposing your private key, create signed transactions offline and send the signed\ntransaction data using `eea_sendRawTransaction`.\n\n> **Important**\n>\n> For production systems requiring private transactions, use a network with a consensus mechanism\n> supporting transaction finality to make sure the private state does not become inconsistent\n> with the chain. For example, [IBFT 2.0](https://besu.hyperledger.org/en/stable/HowTo/Configure/Consensus-Protocols/IBFT)\n> provides the required finality.\n>\n> Using private transactions with [pruning](https://besu.hyperledger.org/en/stable/Concepts/Pruning) or\n> [fast sync](https://besu.hyperledger.org/en/stable/CLI/CLI-Syntax#sync-mode) is not supported.\n> \n> Besu does not implement\n> [`eea_sendTransaction`](https://besu.hyperledger.org/en/stable/HowTo/Send-Transactions/Account-Management).\n> \n> [EthSigner](https://docs.ethsigner.consensys.net/en/latest/) provides transaction signing and\n>implements [`eea_sendTransaction`](https://docs.ethsigner.consensys.net/Reference/API-Methods#eea_sendtransaction).\n\n#### Parameters\n\n`data` - Signed RLP-encoded private transaction. For example:\n\n`params: [\"0xf869018203e882520894f17f52151ebef6c7334fad080c5704d77216b732881bc16d674ec80000801ba02da1c48b670996dcb1f447ef9ef00b33033c48a4fe938f420bec3e56bfd24071a062e0aa78a81bf0290afbc3a9d8e9a068e6d74caa66c5e0fa8a46deaae96b0833\"]`\n\n#### Returns\n\n`result` : `data` - 32-byte transaction hash of the\n[Privacy Marker Transaction](https://besu.hyperledger.org/en/stable/Concepts/Privacy/Private-Transaction-Processing).\n\n> **Tip**\n>\n> If creating a contract, use [priv_getTransactionReceipt](#priv_gettransactionreceipt) to\n> retrieve the contract address after the transaction is finalized." + }, + "response": [ + { + "name": "eea_sendRawTransaction", + "originalRequest": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"eea_sendRawTransaction\",\n \"params\": [\n \"0xf869018203e882520894f17f52151ebef6c7334fad080c5704d77216b732881bc16d674ec80000801ba02da1c48b670996dcb1f447ef9ef00b33033c48a4fe938f420bec3e56bfd24071a062e0aa78a81bf0290afbc3a9d8e9a068e6d74caa66c5e0fa8a46deaae96b0833\"\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + } + }, + "code": 200, + "_postman_previewlanguage": "json", + "header": null, + "cookie": [], + "body": "{\n \"id\": 1,\n \"jsonrpc\": \"2.0\",\n \"result\": \"0xe670ec64341771606e55d6b4ca35a1a6b75ee3d5145a99d05921026d1527331\"\n}" + } + ] + } + ], + "description": "> **Note**\n>\n> The `EEA` API methods are not enabled by default for JSON-RPC. To enable the `EEA` API methods, use the [`--rpc-http-api`](https://besu.hyperledger.org/en/stable/CLI/CLI-Syntax#rpc-http-api) or [`--rpc-ws-api`](https://besu.hyperledger.org/en/stable/CLI/CLI-Syntax#rpc-ws-api) options." + }, + { + "name": "ETH", + "item": [ + { + "name": "eth_accounts", + "request": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"eth_accounts\",\n \"params\": [],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + }, + "description": "Returns a list of account addresses a client owns.\n\n> **note**\n> \n> This method returns an empty object because Besu [doesn't support key management](https://besu.hyperledger.org/en/stable/HowTo/Send-Transactions/Account-Management) inside the client.\n> \n> To provide access to your key store and and then sign transactions, use [EthSigner](http://docs.ethsigner.consensys.net/en/latest/) with Besu.\n\n#### Parameters\n\nNone\n\n#### Returns\n\n`Array of data` : List of 20-byte account addresses owned by the client.\n" + }, + "response": [ + { + "name": "eth_accounts", + "originalRequest": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"eth_accounts\",\n \"params\": [],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + } + }, + "code": 200, + "_postman_previewlanguage": "json", + "header": null, + "cookie": [], + "body": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 53,\n \"result\": []\n}" + } + ] + }, + { + "name": "eth_blockNumber", + "request": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"eth_blockNumber\",\n \"params\": [],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + }, + "description": "Returns the index corresponding to the block number of the current chain head.\n\n#### Parameters\n\nNone\n\n#### Returns\n\n`result` : *QUANTITY* - Hexadecimal integer representing the index corresponding to the block\nnumber of the current chain head.\n" + }, + "response": [ + { + "name": "eth_blockNumber", + "originalRequest": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"eth_blockNumber\",\n \"params\": [],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + } + }, + "code": 200, + "_postman_previewlanguage": "json", + "header": null, + "cookie": [], + "body": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 51,\n \"result\": \"0x2377\"\n}" + } + ] + }, + { + "name": "eth_call", + "request": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"eth_call\",\n \"params\": [\n {\n \"to\": \"0x69498dd54bd25aa0c886cf1f8b8ae0856d55ff13\",\n \"value\": \"0x1\"\n },\n \"latest\"\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + }, + "description": "Invokes a contract function locally and does not change the state of the blockchain.\n\nYou can interact with contracts using `eth_sendRawTransaction` or `eth_call`.\n\n#### Parameters\n\n*OBJECT* - [Transaction call object](https://besu.hyperledger.org/en/stable/Reference/API-Objects#transaction-call-object).\n\n*QUANTITY|TAG* - Integer representing a block number or one of the string tags `latest`,\n`earliest`, or `pending`, as described in\n[Block Parameter](https://besu.hyperledger.org/en/stable/HowTo/Interact/APIs/Using-JSON-RPC-API#block-parameter).\n\n#### Returns\n\n`result` - `data` - Return value of the executed contract.\n" + }, + "response": [ + { + "name": "eth_call", + "originalRequest": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"eth_call\",\n \"params\": [\n {\n \"to\": \"0x69498dd54bd25aa0c886cf1f8b8ae0856d55ff13\",\n \"value\": \"0x1\"\n },\n \"latest\"\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + } + }, + "code": 200, + "_postman_previewlanguage": "json", + "header": null, + "cookie": [], + "body": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 53,\n \"result\": \"0x\"\n}" + } + ] + }, + { + "name": "eth_chainId", + "request": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"eth_chainId\",\n \"params\": [],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + }, + "description": "Returns the [chain ID](https://besu.hyperledger.org/en/stable/Concepts/NetworkID-And-ChainID).\n\n#### Parameters\n\nNone\n\n#### Returns\n\n`result` : *quantity* - Chain ID, in hexadecimal." + }, + "response": [ + { + "name": "eth_chainId", + "originalRequest": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"eth_chainId\",\n \"params\": [],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + } + }, + "code": 200, + "_postman_previewlanguage": "json", + "header": null, + "cookie": [], + "body": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 51,\n \"result\": \"0x7e2\"\n}" + } + ] + }, + { + "name": "eth_coinbase", + "request": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"eth_coinbase\",\n \"params\": [],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + }, + "description": "Returns the client coinbase address. The coinbase address is the account to pay mining rewards to.\n\nTo set a coinbase address, start Besu with the `--miner-coinbase` option set to a valid Ethereum\naccount address. You can get the Ethereum account address from a client such as MetaMask or\nEtherscan. For example:\n\n**Example**\n\n```bash\nbesu --miner-coinbase=\"0xfe3b557e8fb62b89f4916b721be55ceb828dbd73\" --rpc-http-enabled\n```\n\n#### Parameters\n\nNone\n\n#### Returns\n\n`result` : *data* - Coinbase address." + }, + "response": [ + { + "name": "eth_coinbase", + "originalRequest": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"eth_coinbase\",\n \"params\": [],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + } + }, + "code": 200, + "_postman_previewlanguage": "json", + "header": null, + "cookie": [], + "body": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 53,\n \"result\": \"0xfe3b557e8fb62b89f4916b721be55ceb828dbd73\"\n}" + } + ] + }, + { + "name": "eth_estimateGas", + "request": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"eth_estimateGas\",\n \"params\": [\n {\n \"from\": \"0x687422eea2cb73b5d3e242ba5456b782919afc85\",\n \"to\": \"0xdd37f65db31c107f773e82a4f85c693058fef7a9\",\n \"value\": \"0x1\"\n },\n \"latest\"\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + }, + "description": "Returns an estimate of the gas required for a transaction to complete. The estimation process\ndoes not use gas and the transaction is not added to the blockchain. The resulting estimate can be\ngreater than the amount of gas the transaction ends up using, for reasons including EVM mechanics\nand node performance.\n\nThe `eth_estimateGas` call does not send a transaction. You must call\n[`eth_sendRawTransaction`](#eth_sendrawtransaction) to execute the transaction.\n\n#### Parameters\n\nThe transaction call object parameters are the same as those for [`eth_call`](#eth_call) except for the\n[`strict` parameter](https://besu.hyperledger.org/en/stable/Reference/API-Objects#transaction-call-object). If `strict` is set to `true`, the sender\naccount balance is checked for value transfer and transaction fees. The default for `strict` is `false`.\n\nFor `eth_estimateGas`, all fields are optional because setting a gas limit\nis irrelevant to the estimation process (unlike transactions, in which gas limits apply).\n\n`object` - [Transaction call object](https://besu.hyperledger.org/en/stable/Reference/API-Objects#transaction-call-object).\n\n#### Returns\n\n`result` : `quantity` - Amount of gas used." + }, + "response": [ + { + "name": "eth_estimateGas", + "originalRequest": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"eth_estimateGas\",\n \"params\": [\n {\n \"from\": \"0x687422eea2cb73b5d3e242ba5456b782919afc85\",\n \"to\": \"0xdd37f65db31c107f773e82a4f85c693058fef7a9\",\n \"value\": \"0x1\"\n },\n \"latest\"\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + } + }, + "code": 200, + "_postman_previewlanguage": "json", + "header": null, + "cookie": [], + "body": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 53,\n \"result\": \"0x5208\"\n}" + } + ] + }, + { + "name": "eth_gasPrice", + "request": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"eth_gasPrice\",\n \"params\": [],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + }, + "description": "Returns a percentile gas unit price for the most recent blocks, in Wei. By default,\nthe last 100 blocks are examined and the 50th percentile gas unit price (that is, the median value)\nis returned.\n\nIf there are no blocks, the value for [`--min-gas-price`](https://besu.hyperledger.org/en/stable/CLI/CLI-Syntax#min-gas-price) is returned.\nThe value returned is restricted to values between [`--min-gas-price`](https://besu.hyperledger.org/en/stable/CLI/CLI-Syntax#min-gas-price)\nand [`--api-gas-price-max`](https://besu.hyperledger.org/en/stable/CLI/CLI-Syntax#api-gas-price-max). By default, 1000 Wei and\n500GWei.\n\nUse the [`--api-gas-price-blocks`](https://besu.hyperledger.org/en/stable/CLI/CLI-Syntax#api-gas-price-blocks), [`--api-gas-price-percentile`](CLI/CLI-Syntax#api-gas-price-percentile)\n, and [`--api-gas-price-max`](https://besu.hyperledger.org/en/stable/CLI/CLI-Syntax#api-gas-price-max) command line\noptions to configure the `eth_gasPrice` default values.\n\n#### Parameters\n\nNone\n\n#### Returns\n\n`result` : `quantity` - Percentile gas unit price for the most recent blocks, in Wei, as a hexadecimal value." + }, + "response": [ + { + "name": "eth_gasPrice", + "originalRequest": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"eth_gasPrice\",\n \"params\": [],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + } + }, + "code": 200, + "_postman_previewlanguage": "json", + "header": null, + "cookie": [], + "body": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 53,\n \"result\": \"0x3e8\"\n}" + } + ] + }, + { + "name": "eth_getBalance", + "request": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"eth_getBalance\",\n \"params\": [\n \"0xfe3b557e8fb62b89f4916b721be55ceb828dbd73\",\n \"latest\"\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + }, + "description": "Returns the account balance of the specified address.\n\n#### Parameters\n\n`DATA` - 20-byte account address from which to retrieve the balance.\n\n`QUANTITY|TAG` - Integer representing a block number or one of the string tags `latest`,\n`earliest`, or `pending`, as described in\n[Block Parameter](https://besu.hyperledger.org/en/stable/HowTo/Interact/APIs/Using-JSON-RPC-API#block-parameter).\n\n#### Returns\n\n`result` : *QUANTITY* - Current balance, in wei, as a hexadecimal value." + }, + "response": [ + { + "name": "eth_getBalance", + "originalRequest": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"eth_getBalance\",\n \"params\": [\n \"0xfe3b557e8fb62b89f4916b721be55ceb828dbd73\",\n \"latest\"\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + } + }, + "code": 200, + "_postman_previewlanguage": "json", + "header": null, + "cookie": [], + "body": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 53,\n \"result\": \"0x1cfe56f3795885980000\"\n}" + } + ] + }, + { + "name": "eth_getBlockByHash", + "request": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"eth_getBlockByHash\",\n \"params\": [\n \"0xaf5526fcb88b2f0d163c9a78ee678bf95b20115dc3d4e2b7b1f5fc4a308724a0\",\n false\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + }, + "description": "Returns information about the block by hash.\n\n#### Parameters\n\n`DATA` - 32-byte hash of a block.\n\n`Boolean` - If `true`, returns the full [transaction objects](https://besu.hyperledger.org/en/stable/Reference/API-Objects#transaction-object);\nif `false`, returns the transaction hashes.\n\n#### Returns\n\n`result` : *OBJECT* - [Block object](https://besu.hyperledger.org/en/stable/Reference/API-Objects#block-object) , or `null` when there is no block." + }, + "response": [ + { + "name": "eth_getBlockByHash", + "originalRequest": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"eth_getBlockByHash\",\n \"params\": [\n \"0xaf5526fcb88b2f0d163c9a78ee678bf95b20115dc3d4e2b7b1f5fc4a308724a0\",\n false\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + } + }, + "code": 200, + "_postman_previewlanguage": "json", + "header": null, + "cookie": [], + "body": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 53,\n \"result\": {\n \"number\": \"0x68b3\",\n \"hash\": \"0xd5f1812548be429cbdc6376b29611fc49e06f1359758c4ceaaa3b393e2239f9c\",\n \"mixHash\": \"0x24900fb3da77674a861c428429dce0762707ecb6052325bbd9b3c64e74b5af9d\",\n \"parentHash\": \"0x1f68ac259155e2f38211ddad0f0a15394d55417b185a93923e2abe71bb7a4d6d\",\n \"nonce\": \"0x378da40ff335b070\",\n \"sha3Uncles\": \"0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347\",\n \"logsBloom\": \"0x00000000000000100000004080000000000500000000000000020000100000000800001000000004000001000000000000000800040010000020100000000400000010000000000000000040000000000000040000000000000000000000000000000400002400000000000000000000000000000004000004000000000000840000000800000080010004000000001000000800000000000000000000000000000000000800000000000040000000020000000000000000000800000400000000000000000000000600000400000000002000000000000000000000004000000000000000100000000000000000000000000000000000040000900010000000\",\n \"transactionsRoot\": \"0x4d0c8e91e16bdff538c03211c5c73632ed054d00a7e210c0eb25146c20048126\",\n \"stateRoot\": \"0x91309efa7e42c1f137f31fe9edbe88ae087e6620d0d59031324da3e2f4f93233\",\n \"receiptsRoot\": \"0x68461ab700003503a305083630a8fb8d14927238f0bc8b6b3d246c0c64f21f4a\",\n \"miner\": \"0xb42b6c4a95406c78ff892d270ad20b22642e102d\",\n \"difficulty\": \"0x66e619a\",\n \"totalDifficulty\": \"0x1e875d746ae\",\n \"extraData\": \"0xd583010502846765746885676f312e37856c696e7578\",\n \"size\": \"0x334\",\n \"gasLimit\": \"0x47e7c4\",\n \"gasUsed\": \"0x37993\",\n \"timestamp\": \"0x5835c54d\",\n \"uncles\": [],\n \"transactions\": [\n \"0xa0807e117a8dd124ab949f460f08c36c72b710188f01609595223b325e58e0fc\",\n \"0xeae6d797af50cb62a596ec3939114d63967c374fa57de9bc0f4e2b576ed6639d\"\n ]\n }\n}" + } + ] + }, + { + "name": "eth_getBlockByNumber", + "request": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"eth_getBlockByNumber\",\n \"params\": [\n \"0xF\",\n true\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + }, + "description": "Returns information about a block by block number.\n\n#### Parameters\n\n`QUANTITY|TAG` - Integer representing a block number or one of the string tags `latest`,\n`earliest`, or `pending`, as described in\n[Block Parameter](https://besu.hyperledger.org/en/stable/HowTo/Interact/APIs/Using-JSON-RPC-API#block-parameter).\n\n`Boolean` - If `true`, returns the full [transaction objects](https://besu.hyperledger.org/en/stable/Reference/API-Objects#transaction-object);\nif `false`, returns only the hashes of the transactions.\n\n#### Returns\n\n`result` : *OBJECT* - [Block object](https://besu.hyperledger.org/en/stable/Reference/API-Objects#block-object) , or `null` when there is no\nblock." + }, + "response": [ + { + "name": "eth_getBlockByNumber", + "originalRequest": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"eth_getBlockByNumber\",\n \"params\": [\n \"0xF\",\n true\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + } + }, + "code": 200, + "_postman_previewlanguage": "json", + "header": null, + "cookie": [], + "body": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"result\": {\n \"number\": \"0x68b3\",\n \"hash\": \"0xd5f1812548be429cbdc6376b29611fc49e06f1359758c4ceaaa3b393e2239f9c\",\n \"mixHash\": \"0x24900fb3da77674a861c428429dce0762707ecb6052325bbd9b3c64e74b5af9d\",\n \"parentHash\": \"0x1f68ac259155e2f38211ddad0f0a15394d55417b185a93923e2abe71bb7a4d6d\",\n \"nonce\": \"0x378da40ff335b070\",\n \"sha3Uncles\": \"0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347\",\n \"logsBloom\": \"0x00000000000000100000004080000000000500000000000000020000100000000800001000000004000001000000000000000800040010000020100000000400000010000000000000000040000000000000040000000000000000000000000000000400002400000000000000000000000000000004000004000000000000840000000800000080010004000000001000000800000000000000000000000000000000000800000000000040000000020000000000000000000800000400000000000000000000000600000400000000002000000000000000000000004000000000000000100000000000000000000000000000000000040000900010000000\",\n \"transactionsRoot\": \"0x4d0c8e91e16bdff538c03211c5c73632ed054d00a7e210c0eb25146c20048126\",\n \"stateRoot\": \"0x91309efa7e42c1f137f31fe9edbe88ae087e6620d0d59031324da3e2f4f93233\",\n \"receiptsRoot\": \"0x68461ab700003503a305083630a8fb8d14927238f0bc8b6b3d246c0c64f21f4a\",\n \"miner\": \"0xb42b6c4a95406c78ff892d270ad20b22642e102d\",\n \"difficulty\": \"0x66e619a\",\n \"totalDifficulty\": \"0x1e875d746ae\",\n \"extraData\": \"0xd583010502846765746885676f312e37856c696e7578\",\n \"size\": \"0x334\",\n \"gasLimit\": \"0x47e7c4\",\n \"gasUsed\": \"0x37993\",\n \"timestamp\": \"0x5835c54d\",\n \"uncles\": [],\n \"transactions\": []\n }\n}" + } + ] + }, + { + "name": "eth_getBlockTransactionCountByHash", + "request": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"eth_getBlockTransactionCountByHash\",\n \"params\": [\n \"0xb903239f8543d04b5dc1ba6579132b143087c68db1b2168786408fcbce568238\"\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + }, + "description": "Returns the number of transactions in the block matching the given block hash.\n\n#### Parameters\n\n`data` - 32-byte block hash.\n\n#### Returns\n\n`result` : `quantity` - Integer representing the number of transactions in the specified block." + }, + "response": [ + { + "name": "eth_getBlockTransactionCountByHash", + "originalRequest": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"eth_getBlockTransactionCountByHash\",\n \"params\": [\n \"0xb903239f8543d04b5dc1ba6579132b143087c68db1b2168786408fcbce568238\"\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + } + }, + "code": 200, + "_postman_previewlanguage": "json", + "header": null, + "cookie": [], + "body": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"result\": \"0x1\"\n}" + } + ] + }, + { + "name": "eth_getBlockTransactionCountByNumber", + "request": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"eth_getBlockTransactionCountByNumber\",\n \"params\": [\n \"0xe8\"\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + }, + "description": "Returns the number of transactions in a block matching the specified block number.\n\n#### Parameters\n\n`QUANTITY|TAG` - Integer representing a block number or one of the string tags `latest`,\n`earliest`, or `pending`, as described in\n[Block Parameter](https://besu.hyperledger.org/en/stable/HowTo/Interact/APIs/Using-JSON-RPC-API#block-parameter).\n\n#### Returns\n\n`result` : *QUANTITY* - Integer representing the number of transactions in the specified block." + }, + "response": [ + { + "name": "eth_getBlockTransactionCountByNumber", + "originalRequest": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"eth_getBlockTransactionCountByNumber\",\n \"params\": [\n \"0xe8\"\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + } + }, + "code": 200, + "_postman_previewlanguage": "json", + "header": null, + "cookie": [], + "body": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 51,\n \"result\": \"0x8\"\n}" + } + ] + }, + { + "name": "eth_getCode", + "request": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"eth_getCode\",\n \"params\": [\n \"0xa50a51c09a5c451c52bb714527e1974b686d8e77\",\n \"latest\"\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + }, + "description": "Returns the code of the smart contract at the specified address. Besu stores compiled smart\ncontract code as a hexadecimal value.\n\n#### Parameters\n\n`DATA` - 20-byte contract address.\n\n`QUANTITY|TAG` - Integer representing a block number or one of the string tags `latest`,\n`earliest`, or `pending`, as described in\n[Block Parameter](https://besu.hyperledger.org/en/stable/HowTo/Interact/APIs/Using-JSON-RPC-API#block-parameter).\n\n#### Returns\n\n`result` : *DATA* - Code stored at the specified address." + }, + "response": [ + { + "name": "eth_getCode", + "originalRequest": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"eth_getCode\",\n \"params\": [\n \"0xa50a51c09a5c451c52bb714527e1974b686d8e77\",\n \"latest\"\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + } + }, + "code": 200, + "_postman_previewlanguage": "json", + "header": null, + "cookie": [], + "body": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 53,\n \"result\": \"0x60806040526004361060485763ffffffff7c01000000000000000000000000000000000000000000000000000000006000350416633fa4f2458114604d57806355241077146071575b600080fd5b348015605857600080fd5b50605f6088565b60408051918252519081900360200190f35b348015607c57600080fd5b506086600435608e565b005b60005481565b60008190556040805182815290517f199cd93e851e4c78c437891155e2112093f8f15394aa89dab09e38d6ca0727879181900360200190a1505600a165627a7a723058209d8929142720a69bde2ab3bfa2da6217674b984899b62753979743c0470a2ea70029\"\n}" + } + ] + }, + { + "name": "eth_getFilterChanges", + "request": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"eth_getFilterChanges\",\n \"params\": [\n \"0xf8bf5598d9e04fbe84523d42640b9b0e\"\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + }, + "description": "Polls the specified filter and returns an array of changes that have occurred since the last poll.\n\n#### Parameters\n\n`data` - Filter ID.\n\n#### Returns\n\n`result` : `Array of Object` - If nothing changed since the last poll, an empty list. Otherwise:\n\n* For filters created with `eth_newBlockFilter`, returns block hashes.\n* For filters created with `eth_newPendingTransactionFilter`, returns transaction hashes.\n* For filters created with `eth_newFilter`, returns [log objects](https://besu.hyperledger.org/en/stable/Reference/API-Objects#log-object)." + }, + "response": [ + { + "name": "filter created with eth_newPendingTransactionFilter", + "originalRequest": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"eth_getFilterChanges\",\n \"params\": [\n \"0xf8bf5598d9e04fbe84523d42640b9b0e\"\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + } + }, + "code": 200, + "_postman_previewlanguage": "json", + "header": null, + "cookie": [], + "body": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"result\": [\n \"0x1e977049b6db09362da09491bee3949d9362080ce3f4fc19721196d508580d46\",\n \"0xa3abc4b9a4e497fd58dc59cdff52e9bb5609136bcd499e760798aa92802769be\"\n ]\n}" + }, + { + "name": "Filter created with eth_newFilter", + "originalRequest": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"eth_getFilterChanges\",\n \"params\": [\n \"0xf8bf5598d9e04fbe84523d42640b9b0e\"\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + } + }, + "code": 200, + "_postman_previewlanguage": "json", + "header": null, + "cookie": [], + "body": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"result\": [\n {\n \"logIndex\": \"0x0\",\n \"removed\": false,\n \"blockNumber\": \"0x233\",\n \"blockHash\": \"0xfc139f5e2edee9e9c888d8df9a2d2226133a9bd87c88ccbd9c930d3d4c9f9ef5\",\n \"transactionHash\": \"0x66e7a140c8fa27fe98fde923defea7562c3ca2d6bb89798aabec65782c08f63d\",\n \"transactionIndex\": \"0x0\",\n \"address\": \"0x42699a7612a82f1d9c36148af9c77354759b210b\",\n \"data\": \"0x0000000000000000000000000000000000000000000000000000000000000004\",\n \"topics\": [\n \"0x04474795f5b996ff80cb47c148d4c5ccdbe09ef27551820caa9c2f8ed149cce3\"\n ]\n },\n {\n \"logIndex\": \"0x0\",\n \"removed\": false,\n \"blockNumber\": \"0x238\",\n \"blockHash\": \"0x98b0ec0f9fea0018a644959accbe69cd046a8582e89402e1ab0ada91cad644ed\",\n \"transactionHash\": \"0xdb17aa1c2ce609132f599155d384c0bc5334c988a6c368056d7e167e23eee058\",\n \"transactionIndex\": \"0x0\",\n \"address\": \"0x42699a7612a82f1d9c36148af9c77354759b210b\",\n \"data\": \"0x0000000000000000000000000000000000000000000000000000000000000007\",\n \"topics\": [\n \"0x04474795f5b996ff80cb47c148d4c5ccdbe09ef27551820caa9c2f8ed149cce3\"\n ]\n }\n ]\n}" + }, + { + "name": "Filter created with eth_newBlockFilter", + "originalRequest": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"eth_getFilterChanges\",\n \"params\": [\n \"0xf8bf5598d9e04fbe84523d42640b9b0e\"\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + } + }, + "code": 200, + "_postman_previewlanguage": "json", + "header": null, + "cookie": [], + "body": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"result\": [\n \"0xda2bfe44bf85394f0d6aa702b5af89ae50ae22c0928c18b8903d9269abe17e0b\",\n \"0x88cd3a37306db1306f01f7a0e5b25a9df52719ad2f87b0f88ee0e6753ed4a812\",\n \"0x4d4c731fe129ff32b425e6060d433d3fde278b565bbd1fd624d5a804a34f8786\"\n ]\n}" + } + ] + }, + { + "name": "eth_getFilterLogs", + "request": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"eth_getFilterLogs\",\n \"params\": [\n \"0x5ace5de3985749b6a1b2b0d3f3e1fb69\"\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + }, + "description": "Returns an array of [logs](https://besu.hyperledger.org/en/stable/Concepts/Events-and-Logs) for the specified filter.\n\nLeave the [`--auto-log-bloom-caching-enabled`](https://besu.hyperledger.org/en/stable/CLI/CLI-Syntax#auto-log-bloom-caching-enabled)\ncommand line option at the default value of `true` to improve log retrieval performance.\n\n> **note**\n\n `eth_getFilterLogs` is only used for filters created with `eth_newFilter`. To specify a filter\n object and get logs without creating a filter, use `eth_getLogs` .\n\n#### Parameters\n\n`data` - Filter ID.\n\n#### Returns\n\n`array` - [Log objects](https://besu.hyperledger.org/en/stable/Reference/API-Objects#log-object)." + }, + "response": [ + { + "name": "eth_getFilterLogs", + "originalRequest": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"eth_getFilterLogs\",\n \"params\": [\n \"0x5ace5de3985749b6a1b2b0d3f3e1fb69\"\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + } + }, + "code": 200, + "_postman_previewlanguage": "json", + "header": null, + "cookie": [], + "body": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"result\": [\n {\n \"logIndex\": \"0x0\",\n \"removed\": false,\n \"blockNumber\": \"0xb3\",\n \"blockHash\": \"0xe7cd776bfee2fad031d9cc1c463ef947654a031750b56fed3d5732bee9c61998\",\n \"transactionHash\": \"0xff36c03c0fba8ac4204e4b975a6632c862a3f08aa01b004f570cc59679ed4689\",\n \"transactionIndex\": \"0x0\",\n \"address\": \"0x2e1f232a9439c3d459fceca0beef13acc8259dd8\",\n \"data\": \"0x0000000000000000000000000000000000000000000000000000000000000003\",\n \"topics\": [\n \"0x04474795f5b996ff80cb47c148d4c5ccdbe09ef27551820caa9c2f8ed149cce3\"\n ]\n },\n {\n \"logIndex\": \"0x0\",\n \"removed\": false,\n \"blockNumber\": \"0xb6\",\n \"blockHash\": \"0x3f4cf35e7ed2667b0ef458cf9e0acd00269a4bc394bb78ee07733d7d7dc87afc\",\n \"transactionHash\": \"0x117a31d0dbcd3e2b9180c40aca476586a648bc400aa2f6039afdd0feab474399\",\n \"transactionIndex\": \"0x0\",\n \"address\": \"0x2e1f232a9439c3d459fceca0beef13acc8259dd8\",\n \"data\": \"0x0000000000000000000000000000000000000000000000000000000000000005\",\n \"topics\": [\n \"0x04474795f5b996ff80cb47c148d4c5ccdbe09ef27551820caa9c2f8ed149cce3\"\n ]\n }\n ]\n}" + } + ] + }, + { + "name": "eth_getLogs", + "request": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"eth_getLogs\",\n \"params\": [\n {\n \"fromBlock\": \"earliest\",\n \"toBlock\": \"latest\",\n \"address\": \"0x2e1f232a9439c3d459fceca0beef13acc8259dd8\",\n \"topics\": []\n }\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + }, + "description": "Returns an array of [logs](https://besu.hyperledger.org/en/stable/Concepts/Events-and-Logs) matching a specified filter object.\n\nLeave the [`--auto-log-bloom-caching-enabled`](https://besu.hyperledger.org/en/stable/CLI/CLI-Syntax#auto-log-bloom-caching-enabled)\ncommand line option at the default value of `true` to improve log retrieval performance.\n\n> **Attention**\n>\n> Using `eth_getLogs` to get the logs from a large range of blocks, especially an entire chain from its genesis block, can cause Besu to hang and never return a response. We recommend splitting one large query into multiple ones for better performance.\n\n#### Parameters\n\n`Object` - [Filter options object](https://besu.hyperledger.org/en/stable/Reference/API-Objects#filter-options-object).\n\n#### Returns\n\n`array` - [Log objects](https://besu.hyperledger.org/en/stable/Reference/API-Objects#log-object)." + }, + "response": [ + { + "name": "eth_getLogs", + "originalRequest": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"eth_getLogs\",\n \"params\": [\n {\n \"fromBlock\": \"earliest\",\n \"toBlock\": \"latest\",\n \"address\": \"0x2e1f232a9439c3d459fceca0beef13acc8259dd8\",\n \"topics\": []\n }\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + } + }, + "code": 200, + "_postman_previewlanguage": "json", + "header": null, + "cookie": [], + "body": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"result\": [\n {\n \"logIndex\": \"0x0\",\n \"removed\": false,\n \"blockNumber\": \"0xb3\",\n \"blockHash\": \"0xe7cd776bfee2fad031d9cc1c463ef947654a031750b56fed3d5732bee9c61998\",\n \"transactionHash\": \"0xff36c03c0fba8ac4204e4b975a6632c862a3f08aa01b004f570cc59679ed4689\",\n \"transactionIndex\": \"0x0\",\n \"address\": \"0x2e1f232a9439c3d459fceca0beef13acc8259dd8\",\n \"data\": \"0x0000000000000000000000000000000000000000000000000000000000000003\",\n \"topics\": [\n \"0x04474795f5b996ff80cb47c148d4c5ccdbe09ef27551820caa9c2f8ed149cce3\"\n ]\n },\n {\n \"logIndex\": \"0x0\",\n \"removed\": false,\n \"blockNumber\": \"0xb6\",\n \"blockHash\": \"0x3f4cf35e7ed2667b0ef458cf9e0acd00269a4bc394bb78ee07733d7d7dc87afc\",\n \"transactionHash\": \"0x117a31d0dbcd3e2b9180c40aca476586a648bc400aa2f6039afdd0feab474399\",\n \"transactionIndex\": \"0x0\",\n \"address\": \"0x2e1f232a9439c3d459fceca0beef13acc8259dd8\",\n \"data\": \"0x0000000000000000000000000000000000000000000000000000000000000005\",\n \"topics\": [\n \"0x04474795f5b996ff80cb47c148d4c5ccdbe09ef27551820caa9c2f8ed149cce3\"\n ]\n }\n ]\n}" + } + ] + }, + { + "name": "eth_getMinerDataByBlockHash", + "request": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"eth_getMinerDataByBlockHash\",\n \"params\": [\n \"0xbf137c3a7a1ebdfac21252765e5d7f40d115c2757e4a4abee929be88c624fdb7\"\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + }, + "description": "Returns miner data for the specified block.\n\n#### Parameters\n\n`data` - 32 byte block hash.\n\n#### Returns\n\n`result`: `object` - [Miner data](https://besu.hyperledger.org/en/stable/Reference/API-Objects#miner-data-object)." + }, + "response": [ + { + "name": "eth_getMinerDataByBlockHash", + "originalRequest": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"eth_getMinerDataByBlockHash\",\n \"params\": [\n \"0xbf137c3a7a1ebdfac21252765e5d7f40d115c2757e4a4abee929be88c624fdb7\"\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + } + }, + "code": 200, + "_postman_previewlanguage": "json", + "header": null, + "cookie": [], + "body": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"result\": {\n \"netBlockReward\": \"0x47c6f3739f3da800\",\n \"staticBlockReward\": \"0x4563918244f40000\",\n \"transactionFee\": \"0x38456548220800\",\n \"uncleInclusionReward\": \"0x22b1c8c1227a000\",\n \"uncleRewards\": [\n {\n \"hash\": \"0x2422d43b4f72e19faf4368949a804494f67559405046b39c6d45b1bd53044974\",\n \"coinbase\": \"0x0c062b329265c965deef1eede55183b3acb8f611\"\n }\n ],\n \"coinbase\": \"0xb42b6c4a95406c78ff892d270ad20b22642e102d\",\n \"extraData\": \"0xd583010502846765746885676f312e37856c696e7578\",\n \"difficulty\": \"0x7348c20\",\n \"totalDifficulty\": \"0xa57bcfdd96\"\n }\n}" + } + ] + }, + { + "name": "eth_getMinerDataByBlockNumber", + "request": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"eth_getMinerDataByBlockNumber\",\n \"params\": [\n \"0x7689D2\"\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + }, + "description": "Returns miner data for the specified block.\n\n#### Parameters\n\n`quantity|tag` - Integer representing a block number or one of the string tags `latest`,\n`earliest`, or `pending`, as described in\n[Block Parameter](https://besu.hyperledger.org/en/stable/HowTo/Interact/APIs/Using-JSON-RPC-API#block-parameter).\n\n#### Returns\n\n`result`: `object` - [Miner data](https://besu.hyperledger.org/en/stable/Reference/API-Objects#miner-data-object)." + }, + "response": [ + { + "name": "eth_getMinerDataByBlockNumber", + "originalRequest": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"eth_getMinerDataByBlockHash\",\n \"params\": [\n \"0xbf137c3a7a1ebdfac21252765e5d7f40d115c2757e4a4abee929be88c624fdb7\"\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + } + }, + "code": 200, + "_postman_previewlanguage": "json", + "header": null, + "cookie": [], + "body": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"result\": {\n \"netBlockReward\": \"0x47c6f3739f3da800\",\n \"staticBlockReward\": \"0x4563918244f40000\",\n \"transactionFee\": \"0x38456548220800\",\n \"uncleInclusionReward\": \"0x22b1c8c1227a000\",\n \"uncleRewards\": [\n {\n \"hash\": \"0x2422d43b4f72e19faf4368949a804494f67559405046b39c6d45b1bd53044974\",\n \"coinbase\": \"0x0c062b329265c965deef1eede55183b3acb8f611\"\n }\n ],\n \"coinbase\": \"0xb42b6c4a95406c78ff892d270ad20b22642e102d\",\n \"extraData\": \"0xd583010502846765746885676f312e37856c696e7578\",\n \"difficulty\": \"0x7348c20\",\n \"totalDifficulty\": \"0xa57bcfdd96\"\n }\n}" + } + ] + }, + { + "name": "eth_getProof", + "request": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"eth_getProof\",\n \"params\": [\n \"0a8156e7ee392d885d10eaa86afd0e323afdcd95\",\n [\n \"0x0000000000000000000000000000000000000000000000000000000000000347\"\n ],\n \"latest\"\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + }, + "description": "Returns the account and storage values of the specified account, including the Merkle proof.\n\nThe API allows IoT devices or mobile apps which are unable to run light clients to verify responses\nfrom untrusted sources, by using a trusted block hash.\n\n#### Parameters\n\n`DATA` - 20-byte address of the account or contract.\n\n`ARRAY` - Array of 32-byte storage keys to generate proofs for.\n\n`QUANTITY|TAG` - Integer representing a block number or one of the string tags `latest`,\n`earliest`, or `pending`, as described in\n[Block Parameter](https://besu.hyperledger.org/en/stable/HowTo/Interact/APIs/Using-JSON-RPC-API#block-parameter).\n\n#### Returns\n\n`result`: *Object* - Account details:\n\n* `balance`:`Quantity` - Account balance.\n* `codeHash`:`Data, 32-byte` - Hash of the account code.\n* `nonce`:`Quantity` - Number of transactions sent from the account.\n* `storageHash`:`Data, 32-byte` - SHA3 of the `storageRoot`.\n* `accountProof`:`Array` - RLP-encoded Merkle tree nodes, starting with the `stateRoot`.\n* `storageProof`:`Array`- Storage entries. Each entry is an object that displays:\n * `key`:`Quantity` - Storage key.\n * `value`:`Quantity` - Storage value.\n * `proof`:`Array` - RLP-encoded Merkle tree nodes, starting with the `storageHash`." + }, + "response": [ + { + "name": "eth_getProof", + "originalRequest": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"eth_getProof\",\n \"params\": [\n \"0a8156e7ee392d885d10eaa86afd0e323afdcd95\",\n [\n \"0x0000000000000000000000000000000000000000000000000000000000000347\"\n ],\n \"latest\"\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + } + }, + "code": 200, + "_postman_previewlanguage": "json", + "header": null, + "cookie": [], + "body": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"result\": {\n \"accountProof\": [\n \"0xf90211a0...608d898380\",\n \"0xf90211a0...ec33f19580\",\n \"0xf901d1a0...9e55584480\",\n \"0xf8718080...18e5777142\"\n ],\n \"address\": \"0x0a8156e7ee392d885d10eaa86afd0e323afdcd95\",\n \"balance\": \"0x0\",\n \"codeHash\": \"0x2b6975dcaf69f9bb9a3b30bb6a37b305ce440250bf0dd2f23338cb18e5777142\",\n \"nonce\": \"0x5f\",\n \"storageHash\": \"0x917688de43091589aa58c1dfd315105bc9de4478b9ba7471616a4d8a43d46203\",\n \"storageProof\": [\n {\n \"key\": \"0x0000000000000000000000000000000000000000000000000000000000000347\",\n \"value\": \"0x0\",\n \"proof\": [\n \"0xf90211a0...5176779280\",\n \"0xf901f1a0...c208d86580\",\n \"0xf8d180a0...1ce6808080\"\n ]\n }\n ]\n }\n}" + } + ] + }, + { + "name": "eth_getStorageAt", + "request": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"eth_getStorageAt\",\n \"params\": [\n \"0x3B3F3E\",\n \"0x0\",\n \"latest\"\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + }, + "description": "Returns the value of a storage position at a specified address.\n\n#### Parameters\n\n`DATA` - A 20-byte storage address.\n\n`QUANTITY` - Integer index of the storage position.\n\n`QUANTITY|TAG` - Integer representing a block number or one of the string tags `latest`,\n`earliest`, or `pending`, as described in\n[Block Parameter](https://besu.hyperledger.org/en/stable/HowTo/Interact/APIs/Using-JSON-RPC-API#block-parameter).\n\n#### Returns\n\n`result` : *DATA* - The value at the specified storage position." + }, + "response": [ + { + "name": "eth_getStorageAt", + "originalRequest": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"eth_getStorageAt\",\n \"params\": [\n \"0x3B3F3E\",\n \"0x0\",\n \"latest\"\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + } + }, + "code": 200, + "_postman_previewlanguage": "json", + "header": null, + "cookie": [], + "body": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 53,\n \"result\": \"0x0000000000000000000000000000000000000000000000000000000000000000\"\n}" + } + ] + }, + { + "name": "eth_getTransactionByBlockHashAndIndex", + "request": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"eth_getTransactionByBlockHashAndIndex\",\n \"params\": [\n \"0xa52be92809541220ee0aaaede6047d9a6c5d0cd96a517c854d944ee70a0ebb44\",\n \"0x1\"\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + }, + "description": "Returns transaction information for the specified block hash and transaction index position.\n\n#### Parameters\n\n`DATA` - 32-byte hash of a block.\n\n`QUANTITY` - Integer representing the transaction index position.\n\n#### Returns\n\nObject - [Transaction object](https://besu.hyperledger.org/en/stable/Reference/API-Objects#transaction-object), or `null` when there is no\ntransaction." + }, + "response": [ + { + "name": "eth_getTransactionByBlockHashAndIndex", + "originalRequest": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"eth_getTransactionByBlockHashAndIndex\",\n \"params\": [\n \"0xa52be92809541220ee0aaaede6047d9a6c5d0cd96a517c854d944ee70a0ebb44\",\n \"0x1\"\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + } + }, + "code": 200, + "_postman_previewlanguage": "json", + "header": null, + "cookie": [], + "body": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"result\": {\n \"blockHash\": \"0xbf137c3a7a1ebdfac21252765e5d7f40d115c2757e4a4abee929be88c624fdb7\",\n \"blockNumber\": \"0x1442e\",\n \"from\": \"0x70c9217d814985faef62b124420f8dfbddd96433\",\n \"gas\": \"0x3d090\",\n \"gasPrice\": \"0x57148a6be\",\n \"hash\": \"0xfc766a71c406950d4a4955a340a092626c35083c64c7be907060368a5e6811d6\",\n \"input\": \"0x51a34eb8000000000000000000000000000000000000000000000029b9e659e41b780000\",\n \"nonce\": \"0x2cb2\",\n \"to\": \"0xcfdc98ec7f01dab1b67b36373524ce0208dc3953\",\n \"transactionIndex\": \"0x2\",\n \"value\": \"0x0\",\n \"v\": \"0x2a\",\n \"r\": \"0xa2d2b1021e1428740a7c67af3c05fe3160481889b25b921108ac0ac2c3d5d40a\",\n \"s\": \"0x63186d2aaefe188748bfb4b46fb9493cbc2b53cf36169e8501a5bc0ed941b484\"\n }\n}" + } + ] + }, + { + "name": "eth_getTransactionByBlockNumberAndIndex", + "request": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"eth_getTransactionByBlockNumberAndIndex\",\n \"params\": [\n \"latest\",\n \"0x0\"\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + }, + "description": "Returns transaction information for the specified block number and transaction index position.\n\n#### Parameters\n\n`QUANTITY|TAG` - Integer representing a block number or one of the string tags `latest`,\n`earliest`, or `pending`, as described in\n[Block Parameter](https://besu.hyperledger.org/en/stable/HowTo/Interact/APIs/Using-JSON-RPC-API#block-parameter).\n\n`QUANTITY` - The transaction index position.\n\n#### Returns\n\nObject - [Transaction object](https://besu.hyperledger.org/en/stable/Reference/API-Objects#transaction-object), or `null` when there is no\ntransaction." + }, + "response": [ + { + "name": "eth_getTransactionByBlockNumberAndIndex", + "originalRequest": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"eth_getTransactionByBlockNumberAndIndex\",\n \"params\": [\n \"latest\",\n \"0x0\"\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + } + }, + "code": 200, + "_postman_previewlanguage": "json", + "header": null, + "cookie": [], + "body": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"result\": {\n \"blockHash\": \"0xbf137c3a7a1ebdfac21252765e5d7f40d115c2757e4a4abee929be88c624fdb7\",\n \"blockNumber\": \"0x1442e\",\n \"from\": \"0x70c9217d814985faef62b124420f8dfbddd96433\",\n \"gas\": \"0x3d090\",\n \"gasPrice\": \"0x57148a6be\",\n \"hash\": \"0xfc766a71c406950d4a4955a340a092626c35083c64c7be907060368a5e6811d6\",\n \"input\": \"0x51a34eb8000000000000000000000000000000000000000000000029b9e659e41b780000\",\n \"nonce\": \"0x2cb2\",\n \"to\": \"0xcfdc98ec7f01dab1b67b36373524ce0208dc3953\",\n \"transactionIndex\": \"0x2\",\n \"value\": \"0x0\",\n \"v\": \"0x2a\",\n \"r\": \"0xa2d2b1021e1428740a7c67af3c05fe3160481889b25b921108ac0ac2c3d5d40a\",\n \"s\": \"0x63186d2aaefe188748bfb4b46fb9493cbc2b53cf36169e8501a5bc0ed941b484\"\n }\n}" + } + ] + }, + { + "name": "eth_getTransactionByHash", + "request": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"eth_getTransactionByHash\",\n \"params\": [\n \"0xa52be92809541220ee0aaaede6047d9a6c5d0cd96a517c854d944ee70a0ebb44\"\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + }, + "description": "Returns transaction information for the specified transaction hash.\n\n#### Parameters\n\n`DATA` - 32-byte transaction hash.\n\n#### Returns\n\nObject - [Transaction object](https://besu.hyperledger.org/en/stable/Reference/API-Objects#transaction-object), or `null` when there is no\ntransaction." + }, + "response": [ + { + "name": "eth_getTransactionByHash", + "originalRequest": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"eth_getTransactionByHash\",\n \"params\": [\n \"0xa52be92809541220ee0aaaede6047d9a6c5d0cd96a517c854d944ee70a0ebb44\"\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + } + }, + "code": 200, + "_postman_previewlanguage": "json", + "header": null, + "cookie": [], + "body": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 53,\n \"result\": {\n \"blockHash\": \"0x510efccf44a192e6e34bcb439a1947e24b86244280762cbb006858c237093fda\",\n \"blockNumber\": \"0x422\",\n \"from\": \"0xfe3b557e8fb62b89f4916b721be55ceb828dbd73\",\n \"gas\": \"0x5208\",\n \"gasPrice\": \"0x3b9aca00\",\n \"hash\": \"0xa52be92809541220ee0aaaede6047d9a6c5d0cd96a517c854d944ee70a0ebb44\",\n \"input\": \"0x\",\n \"nonce\": \"0x1\",\n \"to\": \"0x627306090abab3a6e1400e9345bc60c78a8bef57\",\n \"transactionIndex\": \"0x0\",\n \"value\": \"0x4e1003b28d9280000\",\n \"v\": \"0xfe7\",\n \"r\": \"0x84caf09aefbd5e539295acc67217563438a4efb224879b6855f56857fa2037d3\",\n \"s\": \"0x5e863be3829812c81439f0ae9d8ecb832b531d651fb234c848d1bf45e62be8b9\"\n }\n}" + } + ] + }, + { + "name": "eth_getTransactionCount", + "request": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"eth_getTransactionCount\",\n \"params\": [\n \"0x9d8f8572f345e1ae53db1dFA4a7fce49B467bD7f\",\n \"latest\"\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + }, + "description": "Returns the number of transactions sent from a specified address. Use the `pending` tag to get the\nnext account nonce not used by any pending transactions.\n\n#### Parameters\n\n`data` - 20-byte account address.\n\n`quantity|tag` - Integer representing a block number or one of the string tags `latest`,\n`earliest`, or `pending`, as described in\n[Block Parameter](https://besu.hyperledger.org/en/stable/HowTo/Interact/APIs/Using-JSON-RPC-API#block-parameter).\n\n#### Returns\n\n`result` : *quantity* - Integer representing the number of transactions sent from the specified\naddress." + }, + "response": [ + { + "name": "eth_getTransactionCount", + "originalRequest": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"eth_getTransactionCount\",\n \"params\": [\n \"0x9d8f8572f345e1ae53db1dFA4a7fce49B467bD7f\",\n \"latest\"\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + } + }, + "code": 200, + "_postman_previewlanguage": "json", + "header": null, + "cookie": [], + "body": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"result\": \"0x1\"\n}" + } + ] + }, + { + "name": "eth_getTransactionReceipt", + "request": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"eth_getTransactionReceipt\",\n \"params\": [\n \"0x96c6830efd87a70020d4d1647c93402d747c05ecf6beeb068dee621f8d13d8d1\"\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + }, + "description": "Returns the receipt of a transaction by transaction hash. Receipts for pending transactions are not\navailable.\n\nIf you enabled [revert reason](https://besu.hyperledger.org/en/stable/HowTo/Send-Transactions/Revert-Reason), the receipt includes\navailable revert reasons in the response.\n\n#### Parameters\n\n`DATA` - 32-byte hash of a transaction.\n\n#### Returns\n\n`Object` - [Transaction receipt object](https://besu.hyperledger.org/en/stable/Reference/API-Objects#transaction-receipt-object), or `null` when\nthere is no receipt." + }, + "response": [ + { + "name": "eth_getTransactionReceipt", + "originalRequest": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"eth_getTransactionReceipt\",\n \"params\": [\n \"0x96c6830efd87a70020d4d1647c93402d747c05ecf6beeb068dee621f8d13d8d1\"\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + } + }, + "code": 200, + "_postman_previewlanguage": "json", + "header": null, + "cookie": [], + "body": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"result\": {\n \"blockHash\": \"0xe7212a92cfb9b06addc80dec2a0dfae9ea94fd344efeb157c41e12994fcad60a\",\n \"blockNumber\": \"0x50\",\n \"contractAddress\": null,\n \"cumulativeGasUsed\": \"0x5208\",\n \"from\": \"0x627306090abab3a6e1400e9345bc60c78a8bef57\",\n \"gasUsed\": \"0x5208\",\n \"logs\": [],\n \"logsBloom\": \"0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000\",\n \"status\": \"0x1\",\n \"to\": \"0xf17f52151ebef6c7334fad080c5704d77216b732\",\n \"transactionHash\": \"0xc00e97af59c6f88de163306935f7682af1a34c67245e414537d02e422815efc3\",\n \"transactionIndex\": \"0x0\"\n }\n}" + } + ] + }, + { + "name": "eth_getUncleByBlockHashAndIndex", + "request": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"eth_getUncleByBlockHashAndIndex\",\n \"params\": [\n \"0xc48fb64230a82f65a08e7280bd8745e7fea87bc7c206309dee32209fe9a985f7\",\n \"0x0\"\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + }, + "description": "Returns uncle specified by block hash and index.\n\n#### Parameters\n\n`data` - 32-byte block hash.\n\n`quantity` - Index of the uncle.\n\n#### Returns\n\n`result` : [Block object](https://besu.hyperledger.org/en/stable/Reference/API-Objects#block-object)\n\n> **note**\n>\n> Uncles do not contain individual transactions." + }, + "response": [ + { + "name": "eth_getUncleByBlockHashAndIndex", + "originalRequest": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"eth_getUncleByBlockHashAndIndex\",\n \"params\": [\n \"0xc48fb64230a82f65a08e7280bd8745e7fea87bc7c206309dee32209fe9a985f7\",\n \"0x0\"\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + } + }, + "code": 200, + "_postman_previewlanguage": "json", + "header": null, + "cookie": [], + "body": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"result\": {\n \"difficulty\": \"0x76b123df93230\",\n \"extraData\": \"0x50505945206e616e6f706f6f6c2e6f7267\",\n \"gasLimit\": \"0x7a121d\",\n \"gasUsed\": \"0x7a0175\",\n \"hash\": \"0xc20189c0b1a4a23116ab3b177e929137f6e826f17fc4c2e880e7258c620e9817\",\n \"logsBloom\": \"0x890086c024487ca422be846a201a10e41bc2882902312116c1119609482031e9c000e2a708004a10281024028020c505727a12570c4810121c59024490b040894406a1c23c37a0094810921da3923600c71c03044b40924280038d07ab91964a008084264a01641380798840805a284cce201a8026045451002500113a00de441001320805ca2840037000111640d090442c11116d2112948084240242340400236ce81502063401dcc214b9105194d050884721c1208800b20501a4201400276004142f118e60808284506979a86e050820101c170c185e2310005205a82a2100382422104182090184800c02489e033440218142140045801c024cc1818485\",\n \"miner\": \"0x52bc44d5378309ee2abf1539bf71de1b7d7be3b5\",\n \"mixHash\": \"0xf557cc827e058862aa3ea1bd6088fb8766f70c0eac4117c56cf85b7911f82a14\",\n \"nonce\": \"0xd320b48904347cdd\",\n \"number\": \"0x768964\",\n \"parentHash\": \"0x98d752708b3677df8f439c4529f999b94663d5494dbfc08909656db3c90f6255\",\n \"receiptsRoot\": \"0x0f838f0ceb73368e7fc8d713a7761e5be31e3b4beafe1a6875a7f275f82da45b\",\n \"sha3Uncles\": \"0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347\",\n \"size\": \"0x21a\",\n \"stateRoot\": \"0xa0c7d4fca79810c89c517eff8dadb9c6d6f4bcc27c2edfb301301e1cf7dec642\",\n \"timestamp\": \"0x5cdcbba6\",\n \"totalDifficulty\": \"0x229ad33cabd4c40d23d\",\n \"transactionsRoot\": \"0x866e38e91d01ef0387b8e07ccf35cd910224271ccf2b7477b8c8439e8b70f365\",\n \"uncles\": []\n }\n}" + } + ] + }, + { + "name": "eth_getUncleByBlockNumberAndIndex", + "request": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"eth_getUncleByBlockNumberAndIndex\",\n \"params\": [\n \"0x7689D2\",\n \"0x0\"\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + }, + "description": "Returns uncle specified by block number and index.\n\n#### Parameters\n\n`quantity|tag` - Index of the block, or one of the string tags `latest`, `earliest`, or `pending`,\nas described in [Block Parameter](https://besu.hyperledger.org/en/stable/HowTo/Interact/APIs/Using-JSON-RPC-API#block-parameter).\n\n`quantity` - Index of the uncle.\n\n#### Returns\n\n`result` : [Block object](https://besu.hyperledger.org/en/stable/Reference/API-Objects#block-object)\n\n> **note**\n>\n> Uncles do not contain individual transactions." + }, + "response": [ + { + "name": "eth_getUncleByBlockNumberAndIndex", + "originalRequest": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"eth_getUncleByBlockNumberAndIndex\",\n \"params\": [\n \"0x7689D2\",\n \"0x0\"\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + } + }, + "code": 200, + "_postman_previewlanguage": "json", + "header": null, + "cookie": [], + "body": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"result\": {\n \"difficulty\": \"0x77daec467bf93\",\n \"extraData\": \"0x50505945206e616e6f706f6f6c2e6f7267\",\n \"gasLimit\": \"0x7a121d\",\n \"gasUsed\": \"0x7a0f7b\",\n \"hash\": \"0x42d83ae9c0743f4b1f9c61ff7ea8b164c1bab3627decd49233760680be006ecf\",\n \"logsBloom\": \"0x888200800000340120220008640200500408006100038400100581c000080240080a0014e8002010080004088040004022402a000c18010001400100002a041141a0610a0052900600041018c0002a0003090020404c00206010010513d00020005380124e08050480710000000108401012b0901c1424006000083a10a8c1040100a0440081050210124400040044304070004001100000012600806008061d0320800000b40042160600002480000000800000c0002100200940801c000820800048024904710000400640490026000a44300309000286088010c2300060003011380006400200812009144042204810209020410a84000410520c08802941\",\n \"miner\": \"0x52bc44d5378309ee2abf1539bf71de1b7d7be3b5\",\n \"mixHash\": \"0xf977fcdb52868be410b75ef2becc35cc312f13ab0a6ce400ecd9d445f66fa3f2\",\n \"nonce\": \"0x628b28403bf1e3d3\",\n \"number\": \"0x7689d0\",\n \"parentHash\": \"0xb32cfdfbf4adb05d30f02fcc6fe039cc6666402142954051c1a1cb9cc91aa11e\",\n \"receiptsRoot\": \"0x9c7c8361d1a24ea2841432234c81974a9920d3eba2b2b1c496b5f925a95cb4ac\",\n \"sha3Uncles\": \"0x7d972aa1b182b7e93f1db043f03fbdbfac6874fe7e67e162141bcc0aefa6336b\",\n \"size\": \"0x21a\",\n \"stateRoot\": \"0x74e97b77813146344d75acb5a52a006cc6dfaca678a10fb8a484a8443e919272\",\n \"timestamp\": \"0x5cdcc0a7\",\n \"totalDifficulty\": \"0x229b0583b4bd2698ca0\",\n \"transactionsRoot\": \"0x1d21626afddf05e5866de66ca3fcd98f1caf5357eba0cc6ec675606e116a891b\",\n \"uncles\": []\n }\n}" + } + ] + }, + { + "name": "eth_getUncleCountByBlockHash", + "request": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"eth_getUncleCountByBlockHash\",\n \"params\": [\n \"0xb903239f8543d04b5dc1ba6579132b143087c68db1b2168786408fcbce568238\"\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + }, + "description": "Returns the number of uncles in a block from a block matching the given block hash.\n\n#### Parameters\n\n`DATA` - 32-byte block hash.\n\n#### Returns\n\n`result` : *QUANTITY* - Integer representing the number of uncles in the specified block." + }, + "response": [ + { + "name": "eth_getUncleCountByBlockHash", + "originalRequest": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"eth_getUncleCountByBlockHash\",\n \"params\": [\n \"0xb903239f8543d04b5dc1ba6579132b143087c68db1b2168786408fcbce568238\"\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + } + }, + "code": 200, + "_postman_previewlanguage": "json", + "header": null, + "cookie": [], + "body": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"result\": \"0x0\"\n}" + } + ] + }, + { + "name": "eth_getUncleCountByBlockNumber", + "request": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"eth_getUncleCountByBlockNumber\",\n \"params\": [\n \"latest\"\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + }, + "description": "Returns the number of uncles in a block matching the specified block number.\n\n#### Parameters\n\n`QUANTITY|TAG` - Integer representing either the index of the block within the blockchain, or one\nof the string tags `latest`, `earliest`, or `pending`, as described in\n[Block Parameter](https://besu.hyperledger.org/en/stable/HowTo/Interact/APIs/Using-JSON-RPC-API#block-parameter).\n\n#### Returns\n\n`result` : *QUANTITY* - Integer representing the number of uncles in the specified block." + }, + "response": [ + { + "name": "eth_getUncleCountByBlockNumber", + "originalRequest": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"eth_getUncleCountByBlockNumber\",\n \"params\": [\n \"latest\"\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + } + }, + "code": 200, + "_postman_previewlanguage": "json", + "header": null, + "cookie": [], + "body": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"result\": \"0x1\"\n}" + } + ] + }, + { + "name": "eth_getWork", + "request": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"eth_getWork\",\n \"params\": [],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + }, + "description": "Returns the hash of the current block, the seed hash, and the required target boundary condition.\n\n#### Parameters\n\nNone\n\n#### Returns\n\n`result` : Array with the following fields:\n\n* `DATA`, 32 Bytes - Hash of the current block header (pow-hash).\n* `DATA`, 32 Bytes - The seed hash used for the DAG.\n* `DATA`, 32 Bytes - The required target boundary condition: 2^256 / difficulty.\n* `QUANTITY` - Hexadecimal integer representing the current block number." + }, + "response": [ + { + "name": "eth_getWork", + "originalRequest": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"eth_getWork\",\n \"params\": [],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + } + }, + "code": 200, + "_postman_previewlanguage": "json", + "header": null, + "cookie": [], + "body": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"result\": [\n \"0xce5e32ca59cb86799a1879e90150b2c3b882852173e59865e9e79abb67a9d636\",\n \"0x0000000000000000000000000000000000000000000000000000000000000000\",\n \"0x00a3d70a3d70a3d70a3d70a3d70a3d70a3d70a3d70a3d70a3d70a3d70a3d70a3\",\n \"0x42\"\n ]\n}" + } + ] + }, + { + "name": "eth_hashrate", + "request": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"eth_hashrate\",\n \"params\": [],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + }, + "description": "Returns the number of hashes per second with which the node is mining.\n\nWhen the stratum server is enabled, this method returns the cumulative hashrate of all sealers\nreporting their hashrate.\n\n#### Parameters\n\nNone\n\n#### Returns\n\n`result` : `quantity` - Number of hashes per second.\n" + }, + "response": [ + { + "name": "eth_hashrate", + "originalRequest": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"eth_hashrate\",\n \"params\": [],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + } + }, + "code": 200, + "_postman_previewlanguage": "json", + "header": null, + "cookie": [], + "body": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"result\": \"0x12b\"\n}" + } + ] + }, + { + "name": "eth_mining", + "request": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"eth_mining\",\n \"params\": [],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + }, + "description": "Whether the client is actively mining new blocks. Besu pauses mining while the client synchronizes\nwith the network regardless of command settings or methods called.\n\n#### Parameters\n\nNone\n\n#### Returns\n\n`result` (*BOOLEAN*) - `true` if the client is actively mining new blocks, otherwise `false`." + }, + "response": [ + { + "name": "eth_mining", + "originalRequest": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"eth_mining\",\n \"params\": [],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + } + }, + "code": 200, + "_postman_previewlanguage": "json", + "header": null, + "cookie": [], + "body": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 53,\n \"result\": true\n}" + } + ] + }, + { + "name": "eth_newBlockFilter", + "request": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"eth_newBlockFilter\",\n \"params\": [],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + }, + "description": "Creates a filter to retrieve new block hashes. To poll for new blocks, use\n[`eth_getFilterChanges`](#eth_getfilterchanges).\n\n#### Parameters\n\nNone\n\n#### Returns\n\n`data` - Filter ID." + }, + "response": [ + { + "name": "eth_newBlockFilter", + "originalRequest": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"eth_newBlockFilter\",\n \"params\": [],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + } + }, + "code": 200, + "_postman_previewlanguage": "json", + "header": null, + "cookie": [], + "body": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"result\": \"0x9d78b6780f844228b96ecc65a320a825\"\n}" + } + ] + }, + { + "name": "eth_newFilter", + "request": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"eth_newFilter\",\n \"params\": [\n {\n \"fromBlock\": \"earliest\",\n \"toBlock\": \"latest\",\n \"topics\": []\n }\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + }, + "description": "Creates a [log filter](https://besu.hyperledger.org/en/stable/Concepts/Events-and-Logs). To poll for logs associated with the\ncreated filter, use [`eth_getFilterChanges`](#eth_getfilterchanges). To get all logs associated with\nthe filter, use [`eth_getFilterLogs`](#eth_getfilterlogs).\n\n#### Parameters\n\n`Object` - [Filter options object](https://besu.hyperledger.org/en/stable/Reference/API-Objects#filter-options-object).\n\n> **note**\n>\n> `fromBlock` and `toBlock` in the filter options object default to `latest`.\n\n#### Returns\n\n`data` - Filter ID." + }, + "response": [ + { + "name": "eth_newFilter", + "originalRequest": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"eth_newFilter\",\n \"params\": [\n {\n \"fromBlock\": \"earliest\",\n \"toBlock\": \"latest\",\n \"topics\": []\n }\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + } + }, + "code": 200, + "_postman_previewlanguage": "json", + "header": null, + "cookie": [], + "body": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"result\": \"0x1ddf0c00989044e9b41cc0ae40272df3\"\n}" + } + ] + }, + { + "name": "eth_newPendingTransactionFilter", + "request": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"eth_newPendingTransactionFilter\",\n \"params\": [],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + }, + "description": "Creates a filter to retrieve new pending transactions hashes. To poll for new pending transactions,\nuse [`eth_getFilterChanges`](#eth_getfilterchanges).\n\n#### Parameters\n\nNone\n\n#### Returns\n\n`data` - Filter ID." + }, + "response": [ + { + "name": "eth_newPendingTransactionFilter", + "originalRequest": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"eth_newPendingTransactionFilter\",\n \"params\": [],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + } + }, + "code": 200, + "_postman_previewlanguage": "json", + "header": null, + "cookie": [], + "body": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"result\": \"0x443d6a77c4964707a8554c92f7e4debd\"\n}" + } + ] + }, + { + "name": "eth_protocolVersion", + "request": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"eth_protocolVersion\",\n \"params\": [],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + }, + "description": "Returns current Ethereum protocol version.\n\n#### Parameters\n\nNone\n\n#### Returns\n\n`result` : *quantity* - Ethereum protocol version." + }, + "response": [ + { + "name": "eth_protocolVersion", + "originalRequest": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"eth_protocolVersion\",\n \"params\": [],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + } + }, + "code": 200, + "_postman_previewlanguage": "json", + "header": null, + "cookie": [], + "body": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"result\": \"0x3f\"\n}" + } + ] + }, + { + "name": "eth_sendRawTransaction", + "request": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"eth_sendRawTransaction\",\n \"params\": [\n \"0xf86a018203e882520894f17f52151ebef6c7334fad080c5704d77216b732896c6b935b8bbd400000801ba093129415f03b4794fd1512e79ee7f097e4271f66721020f8407aac92179893a5a0451b875d89721ec98be55201092980b0a87bb1c48507fccb86da713596b2a09e\"\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + }, + "description": "Sends a [signed transaction](https://besu.hyperledger.org/en/stable/HowTo/Send-Transactions/Transactions).\nA transaction can send ether, deploy a contract, or interact with a contract.\nSet the maximum transaction fee for transactions using the [`--rpc-tx-feecap`](https://besu.hyperledger.org/en/stable/CLI/CLI-Syntax#rpc-tx-feecap) CLI option.\n\nYou can interact with contracts using [`eth_sendRawTransaction` or `eth_call`].\n\nTo avoid exposing your private key, create signed transactions offline and send the signed\ntransaction data using `eth_sendRawTransaction`.\n\n> **important**\n>\n> Besu does not implement [`eth_sendTransaction`](https://besu.hyperledger.org/en/stable/HowTo/Send-Transactions/Account-Management).\n>\n> [EthSigner](https://docs.ethsigner.consensys.net/) provides transaction signing and implements\n> [`eth_sendTransaction`](https://docs.ethsigner.consensys.net/Reference/API-Methods#eth_sendtransaction).\n\n#### Parameters\n\n`data` - Signed transaction serialized to hexadecimal format. For example:\n\n`params: [\"0xf869018203e882520894f17f52151ebef6c7334fad080c5704d77216b732881bc16d674ec80000801ba02da1c48b670996dcb1f447ef9ef00b33033c48a4fe938f420bec3e56bfd24071a062e0aa78a81bf0290afbc3a9d8e9a068e6d74caa66c5e0fa8a46deaae96b0833\"]`\n\n> **note**\n>\n> [Creating and Sending Transactions](https://besu.hyperledger.org/en/stable/HowTo/Send-Transactions/Transactions) includes examples of creating signed transactions using the [web3.js](https://github.com/ethereum/web3.js/) library.\n\n#### Returns\n\n`result` : `data` - 32-byte transaction hash." + }, + "response": [ + { + "name": "eth_sendRawTransaction", + "originalRequest": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\"jsonrpc\":\"2.0\",\"method\":\"eth_sendRawTransaction\",\"params\" :[\"0xf85f808203e8832dc6c08080914f785b6f626a656374204f626a6563745d1ba004193142058b4fe6802677a939e76f93e7fa30e91835a911e206f9855330929ca055ce11a262c804a168c8a801e55a68b3d578a4b52b9dfbed98c4aa47f88a0adf\"], \"id\":1}" + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + } + }, + "code": 200, + "_postman_previewlanguage": "json", + "header": [ + { + "key": "Content-Length", + "value": "118", + "name": "Content-Length", + "description": "The length of the response body in octets (8-bit bytes)" + }, + { + "key": "Content-Type", + "value": "application/json", + "name": "Content-Type", + "description": "The mime type of this content" + } + ], + "cookie": [], + "body": "{\n \"jsonrpc\" : \"2.0\",\n \"id\" : 1,\n \"result\" : \"0xac182cc23bb94696217aa17ca15bd466106af9ba7ea7420aae24ff37338d6e3b\"\n}" + } + ] + }, + { + "name": "eth_submitHashrate", + "request": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"eth_submitHashrate\",\n \"params\": [\n \"0x0000000000000000000000000000000000000000000000000000000000500000\",\n \"0x59daa26581d0acd1fce254fb7e85952f4c09d0915afd33d3886cd914bc7d283c\"\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + }, + "description": "Submits the mining hashrate.\n\nUsed by mining software such as [Ethminer](https://github.com/ethereum-mining/ethminer).\n\n#### Parameters\n\n* DATA, 32 Bytes - Hexadecimal string representation of the hash rate.\n* DATA, 32 Bytes - Random hexadecimal ID identifying the client.\n\n#### Returns\n\n`result: Boolean`, `true` if submission is successful, otherwise `false`." + }, + "response": [ + { + "name": "eth_submitHashrate", + "originalRequest": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"eth_submitHashrate\",\n \"params\": [\n \"0x0000000000000000000000000000000000000000000000000000000000500000\",\n \"0x59daa26581d0acd1fce254fb7e85952f4c09d0915afd33d3886cd914bc7d283c\"\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + } + }, + "code": 200, + "_postman_previewlanguage": "json", + "header": null, + "cookie": [], + "body": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"result\": true\n}" + } + ] + }, + { + "name": "eth_submitWork", + "request": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"eth_submitWork\",\n \"params\": [\n \"0x0000000000000001\",\n \"0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef\",\n \"0xD1GE5700000000000000000000000000D1GE5700000000000000000000000000\"\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + }, + "description": "Submits a Proof of Work (Ethash) solution.\n\nUsed by mining software such as [Ethminer](https://github.com/ethereum-mining/ethminer).\n\n#### Parameters\n\n* DATA, 8 Bytes - Retrieved nonce.\n* DATA, 32 Bytes - Hash of the block header (PoW-hash).\n* DATA, 32 Bytes - Mix digest.\n\n#### Returns\n\n`result: Boolean`, `true` if the provided solution is valid, otherwise `false`." + }, + "response": [ + { + "name": "eth_submitHashrate", + "originalRequest": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"eth_submitHashrate\",\n \"params\": [\n \"0x0000000000000000000000000000000000000000000000000000000000500000\",\n \"0x59daa26581d0acd1fce254fb7e85952f4c09d0915afd33d3886cd914bc7d283c\"\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + } + }, + "code": 200, + "_postman_previewlanguage": "json", + "header": null, + "cookie": [], + "body": "{\n \"id\": 1,\n \"jsonrpc\": \"2.0\",\n \"result\": true\n}" + } + ] + }, + { + "name": "eth_syncing", + "request": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"eth_syncing\",\n \"params\": [],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + }, + "description": "Returns an object with data about the synchronization status, or `false` if not synchronizing.\n\n#### Parameters\n\nNone\n\n#### Returns\n\n`result` : *Object|Boolean* - Object with synchronization status data or `false` if not\nsynchronizing:\n\n* `startingBlock` : *quantity* - Index of the highest block on the blockchain when the network\n synchronization starts.\n* `currentBlock` : *quantity* - Index of the latest block (also known as the best block) for the\n current node. This is the same index that [`eth_blockNumber`](#eth_blocknumber) returns.\n* `highestBlock`: *quantity* - Index of the highest known block in the peer network (that is, the\n highest block so far discovered among peer nodes). This is the same value as `currentBlock` if\n the current node has no peers.\n* `pulledStates`: *quantity* - If fast synchronizing, the number of state entries fetched so far,\n or `null` if this is not known or not relevant. If full synchronizing or fully synchronized, this\n field is not returned.\n* `knownStates`: *quantity* - If fast synchronizing, the number of states the node knows of so\n far, or `null` if this is not known or not relevant. If full synchronizing or fully synchronized,\n this field is not returned." + }, + "response": [ + { + "name": "eth_syncing", + "originalRequest": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"eth_syncing\",\n \"params\": [],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + } + }, + "code": 200, + "_postman_previewlanguage": "json", + "header": null, + "cookie": [], + "body": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 51,\n \"result\": {\n \"startingBlock\": \"0x0\",\n \"currentBlock\": \"0x1518\",\n \"highestBlock\": \"0x9567a3\",\n \"pulledStates\": \"0x203ca\",\n \"knownStates\": \"0x200636\"\n }\n}" + } + ] + }, + { + "name": "eth_uninstallFilter", + "request": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"eth_uninstallFilter\",\n \"params\": [\n \"0x70355a0b574b437eaa19fe95adfedc0a\"\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + }, + "description": "Uninstalls a filter with the specified ID. When a filter is no longer required, call this method.\n\nFilters time out when not requested by [`eth_getFilterChanges`](#eth_getfilterchanges) or [`eth_getFilterLogs`](#eth_getfilterlogs) for 10\nminutes.\n\n#### Parameters\n\n`data` - Filter ID.\n\n#### Returns\n\n`Boolean` - `true` if the filter was successfully uninstalled, otherwise `false`." + }, + "response": [ + { + "name": "eth_uninstallFilter", + "originalRequest": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"eth_uninstallFilter\",\n \"params\": [\n \"0x70355a0b574b437eaa19fe95adfedc0a\"\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + } + }, + "code": 200, + "_postman_previewlanguage": "json", + "header": null, + "cookie": [], + "body": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"result\": true\n}" + } + ] + } + ], + "description": "> **Note**\n>\n> Methods with an equivalent [GraphQL](https://besu.hyperledger.org/en/stable/HowTo/Interact/APIs/GraphQL) query include a GraphQL\n request and result in the method example. The parameter and result descriptions apply to the\n JSON-RPC requests. The GraphQL specification is defined in the [schema](https://github.com/hyperledger/besu/blob/master/ethereum/api/src/main/resources/schema.graphqls)." + }, + { + "name": "IBFT", + "item": [ + { + "name": "ibft_discardValidatorVote", + "request": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"ibft_discardValidatorVote\",\n \"params\": [\n \"0x42eb768f2244c8811c63729a21a3569731535f06\"\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + }, + "description": "Discards a proposal to [add or remove a validator] with the specified address.\n\n#### Parameters\n\n`data` - 20-byte address of proposed validator.\n\n#### Returns\n\n`result: boolean` - `true`" + }, + "response": [ + { + "name": "ibft_discardValidatorVote", + "originalRequest": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"ibft_discardValidatorVote\",\n \"params\": [\n \"0x42eb768f2244c8811c63729a21a3569731535f06\"\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + } + }, + "code": 200, + "_postman_previewlanguage": "json", + "header": null, + "cookie": [], + "body": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"result\": true\n}" + } + ] + }, + { + "name": "ibft_getPendingVotes", + "request": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"ibft_getPendingVotes\",\n \"params\": [],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + }, + "description": "Returns [votes](https://besu.hyperledger.org/en/stable/HowTo/Configure/Consensus-Protocols/IBFT#adding-and-removing-validators)\ncast in the current [epoch](https://besu.hyperledger.org/en/stable/HowTo/Configure/Consensus-Protocols/IBFT#genesis-file).\n\n#### Parameters\n\nNone\n\n#### Returns\n\n`result`: `object` - Map of account addresses to corresponding boolean values indicating the vote\nfor each account.\n\nIf the boolean value is `true`, the vote is to add a validator. If `false`, the proposal is to\nremove a validator." + }, + "response": [ + { + "name": "ibft_getPendingVotes", + "originalRequest": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"ibft_getPendingVotes\",\n \"params\": [],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + } + }, + "code": 200, + "_postman_previewlanguage": "json", + "header": null, + "cookie": [], + "body": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"result\": {\n \"0xef1bfb6a12794615c9b0b5a21e6741f01e570185\": true,\n \"0x42d4287eac8078828cf5f3486cfe601a275a49a5\": true\n }\n}" + } + ] + }, + { + "name": "ibft_getSignerMetrics", + "request": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"ibft_getSignerMetrics\",\n \"params\": [\n \"1\",\n \"100\"\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + }, + "description": "Provides validator metrics for the specified range:\n\n* Number of blocks from each validator.\n* Block number of the last block proposed by each validator (if any proposed in the specified\n range).\n* All validators present in the last block of the range.\n\n#### Parameters\n\n`fromBlockNumber` - Integer representing a block number or the string tag `earliest` as described\nin [Block Parameter](https://besu.hyperledger.org/en/stable/HowTo/Interact/APIs/Using-JSON-RPC-API#block-parameter).\n\n`toBlockNumber` - Integer representing a block number or one of the string tags `latest` or\n`pending`, as described in\n[Block Parameter](https://besu.hyperledger.org/en/stable/HowTo/Interact/APIs/Using-JSON-RPC-API#block-parameter)\n\nIf you specify:\n\n* No parameters, the call provides metrics for the last 100 blocks, or all blocks if there are less\n than 100 blocks.\n* Only the first parameter, the call provides metrics for all blocks from the block specified to\n the latest block.\n\n#### Returns\n\n`result`: _object_ - List of validator objects\n\n> **Note**\n>\n> The proposer of the genesis block has address `0x0000000000000000000000000000000000000000`." + }, + "response": [ + { + "name": "ibft_getSignerMetrics", + "originalRequest": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"ibft_getSignerMetrics\",\n \"params\": [\n \"1\",\n \"100\"\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + } + }, + "code": 200, + "_postman_previewlanguage": "json", + "header": null, + "cookie": [], + "body": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"result\": [\n {\n \"address\": \"0x7ffc57839b00206d1ad20c69a1981b489f772031\",\n \"proposedBlockCount\": \"0x21\",\n \"lastProposedBlockNumber\": \"0x61\"\n },\n {\n \"address\": \"0x42eb768f2244c8811c63729a21a3569731535f06\",\n \"proposedBlockCount\": \"0x21\",\n \"lastProposedBlockNumber\": \"0x63\"\n },\n {\n \"address\": \"0xb279182d99e65703f0076e4812653aab85fca0f0\",\n \"proposedBlockCount\": \"0x21\",\n \"lastProposedBlockNumber\": \"0x62\"\n }\n ]\n}" + } + ] + }, + { + "name": "ibft_getValidatorsByBlockHash", + "request": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"ibft_getValidatorsByBlockHash\",\n \"params\": [\n \"0x98b2ddb5106b03649d2d337d42154702796438b3c74fd25a5782940e84237a48\"\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + }, + "description": "Lists the validators defined in the specified block.\n\n#### Parameters\n\n`data` - 32-byte block hash.\n\n#### Returns\n\n`result: array of data` - List of validator addresses." + }, + "response": [ + { + "name": "ibft_getValidatorsByBlockHash", + "originalRequest": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"ibft_getValidatorsByBlockHash\",\n \"params\": [\n \"0x98b2ddb5106b03649d2d337d42154702796438b3c74fd25a5782940e84237a48\"\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + } + }, + "code": 200, + "_postman_previewlanguage": "json", + "header": null, + "cookie": [], + "body": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"result\": [\n \"0x42d4287eac8078828cf5f3486cfe601a275a49a5\",\n \"0xb1b2bc9582d2901afdc579f528a35ca41403fa85\",\n \"0xef1bfb6a12794615c9b0b5a21e6741f01e570185\"\n ]\n}" + } + ] + }, + { + "name": "ibft_getValidatorsByBlockNumber", + "request": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"ibft_getValidatorsByBlockNumber\",\n \"params\": [\n \"0x09\"\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + }, + "description": "Lists the validators defined in the specified block.\n\n#### Parameters\n\n`quantity|tag` - Integer representing a block number or one of the string tags `latest`,\n`earliest`, or `pending`, as described in\n[Block Parameter](https://besu.hyperledger.org/en/stable/HowTo/Interact/APIs/Using-JSON-RPC-API#block-parameter).\n\n#### Returns\n\n`result: array of data` - List of validator addresses." + }, + "response": [ + { + "name": "ibft_getValidatorsByBlockNumber", + "originalRequest": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"ibft_getValidatorsByBlockNumber\",\n \"params\": [\n \"0x09\"\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + } + }, + "code": 200, + "_postman_previewlanguage": "json", + "header": null, + "cookie": [], + "body": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"result\": [\n \"0x42d4287eac8078828cf5f3486cfe601a275a49a5\",\n \"0xb1b2bc9582d2901afdc579f528a35ca41403fa85\",\n \"0xef1bfb6a12794615c9b0b5a21e6741f01e570185\"\n ]\n}" + } + ] + }, + { + "name": "ibft_proposeValidatorVote", + "request": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"ibft_proposeValidatorVote\",\n \"params\": [\n \"42d4287eac8078828cf5f3486cfe601a275a49a5\",\n true\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + }, + "description": "Propose to [add or remove a validator] with the specified address.\n\n#### Parameters\n\n`data` - Account address\n\n`boolean` - `true` to propose adding validator or `false` to propose removing validator.\n\n#### Returns\n\n`result: boolean` - `true`" + }, + "response": [ + { + "name": "ibft_proposeValidatorVote", + "originalRequest": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"ibft_proposeValidatorVote\",\n \"params\": [\n \"42d4287eac8078828cf5f3486cfe601a275a49a5\",\n true\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + } + }, + "code": 200, + "_postman_previewlanguage": "json", + "header": null, + "cookie": [], + "body": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"result\": true\n}" + } + ] + } + ], + "description": "> **Note**\n>\n> The `IBFT` API methods are not enabled by default for JSON-RPC. To enable the `IBFT` API methods, use the [`--rpc-http-api`](https://besu.hyperledger.org/en/stable/CLI/CLI-Syntax#rpc-http-api) or [`--rpc-ws-api`](https://besu.hyperledger.org/en/stable/CLI/CLI-Syntax#rpc-ws-api) options." + }, + { + "name": "MINER", + "item": [ + { + "name": "miner_start", + "request": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"miner_start\",\n \"params\": [],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + }, + "description": "Starts the mining process. To start mining, you must first specify a miner coinbase using the\n[`--miner-coinbase`](https://besu.hyperledger.org/en/stable/CLI/CLI-Syntax#miner-coinbase) command line option.\n\n#### Parameters\n\nNone\n\n#### Returns\n\n`result` : `boolean` - `true` if mining starts, or if the node was already mining." + }, + "response": [ + { + "name": "miner_start", + "originalRequest": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"miner_start\",\n \"params\": [],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + } + }, + "code": 200, + "_postman_previewlanguage": "json", + "header": null, + "cookie": [], + "body": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"result\": true\n}" + } + ] + }, + { + "name": "miner_stop", + "request": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"miner_stop\",\n \"params\": [],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + }, + "description": "Stops the mining process on the client.\n\n#### Parameters\n\nNone\n\n#### Returns\n\n`result` : `boolean` - `true` if mining stops, or if the node was not mining.\n" + }, + "response": [ + { + "name": "miner_stop", + "originalRequest": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"miner_stop\",\n \"params\": [],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + } + }, + "code": 200, + "_postman_previewlanguage": "json", + "header": null, + "cookie": [], + "body": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"result\": true\n}" + } + ] + } + ], + "description": "> **Note**\n>\n> The `MINER` API methods are not enabled by default for JSON-RPC. To enable the `MINER` API methods, use the [`--rpc-http-api`](https://besu.hyperledger.org/en/stable/CLI/CLI-Syntax#rpc-http-api) or [`--rpc-ws-api`](https://besu.hyperledger.org/en/stable/CLI/CLI-Syntax#rpc-ws-api) options." + }, + { + "name": "Miscellaneous", + "item": [ + { + "name": "rpc_modules", + "request": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"rpc_modules\",\n \"params\": [],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + }, + "description": "Lists [enabled APIs](https://besu.hyperledger.org/en/stable/HowTo/Interact/APIs/Using-JSON-RPC-API#api-methods-enabled-by-default)\nand the version of each.\n\n#### Parameters\n\nNone\n\n#### Returns\n\nEnabled APIs." + }, + "response": [ + { + "name": "rpc_modules", + "originalRequest": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"rpc_modules\",\n \"params\": [],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + } + }, + "code": 200, + "_postman_previewlanguage": "json", + "header": null, + "cookie": [], + "body": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"result\": {\n \"web3\": \"1.0\",\n \"eth\": \"1.0\",\n \"net\": \"1.0\"\n }\n}" + } + ] + } + ] + }, + { + "name": "NET", + "item": [ + { + "name": "net_version", + "request": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"net_version\",\n \"params\": [],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + }, + "description": "Returns the [network ID](https://besu.hyperledger.org/en/stable/Concepts/NetworkID-And-ChainID).\n\n#### Parameters\n\nNone\n\n#### Returns\n\n`result` : *string* - Current network ID.\n\n| Network ID | Chain | Network | Description\n|------------|-------|---------|-------------------------------|\n| `1` | ETH | Mainnet | Main Ethereum network |\n| `3` | ETH | Ropsten | PoW test network |\n| `4` | ETH | Rinkeby | PoA test network using Clique |\n| `5` | ETH | Goerli | PoA test network using Clique |\n| `2018` | ETH | Dev | PoW development network |\n| `1` | ETC | Classic | Main Ethereum Classic network |\n| `7` | ETC | Mordor | PoW test network |\n\n> **note**\n>\n> For almost all networks network ID and chain ID are the same.\nThe only networks in the table above with different network and chain IDs are\nClassic with a chain ID of `61` and Mordor with a chain ID of `63`." + }, + "response": [ + { + "name": "net_version", + "originalRequest": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"net_version\",\n \"params\": [],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + } + }, + "_postman_previewlanguage": "json", + "header": null, + "cookie": [], + "body": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 53,\n \"result\": \"3\"\n}" + } + ] + }, + { + "name": "net_listening", + "request": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"net_listening\",\n \"params\": [],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + }, + "description": "Whether the client is actively listening for network connections.\n\n#### Parameters\n\nNone\n\n#### Returns\n\n`result` (*BOOLEAN*) - `true` if the client is actively listening for network connections;\notherwise `false`." + }, + "response": [ + { + "name": "net_listening", + "originalRequest": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"net_listening\",\n \"params\": [],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + } + }, + "_postman_previewlanguage": "json", + "header": null, + "cookie": [], + "body": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 53,\n \"result\": true\n}" + } + ] + }, + { + "name": "net_peerCount", + "request": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"net_peerCount\",\n \"params\": [],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + }, + "description": "Returns the number of peers currently connected to the client.\n\n#### Parameters\n\nNone\n\n#### Returns\n\n`result` : *integer* - Number of connected peers in hexadecimal." + }, + "response": [ + { + "name": "net_peerCount", + "originalRequest": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"net_peerCount\",\n \"params\": [],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://127.0.0.1:8545", + "protocol": "http", + "host": ["127", "0", "0", "1"], + "port": "8545" + } + }, + "_postman_previewlanguage": "json", + "header": null, + "cookie": [], + "body": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 53,\n \"result\": \"0x5\"\n}" + } + ] + }, + { + "name": "net_enode", + "request": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"net_enode\",\n \"params\": [],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + }, + "description": "Returns the [enode URL](https://besu.hyperledger.org/en/stable/Concepts/Node-Keys#enode-url).\n\n#### Parameters\n\nNone\n\n#### Returns\n\n`result` : *string* - [Enode URL](https://besu.hyperledger.org/en/stable/Concepts/Node-Keys#enode-url) of the node." + }, + "response": [ + { + "name": "net_enode", + "originalRequest": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"net_enode\",\n \"params\": [],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + } + }, + "_postman_previewlanguage": "json", + "header": null, + "cookie": [], + "body": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"result\": \"enode://6a63160d0ccef5e4986d270937c6c8d60a9a4d3b25471cda960900d037c61988ea14da67f69dbfb3497c465d0de1f001bb95598f74b68a39a5156a608c42fa1b@127.0.0.1:30303\"\n}" + } + ] + }, + { + "name": "net_services", + "request": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"net_services\",\n \"params\": [],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + }, + "description": "Returns enabled services (for example, `jsonrpc`) and the host and port for each service.\n\n#### Parameters\n\nNone\n\n#### Returns\n\n`result` : *objects* - Enabled services." + }, + "response": [ + { + "name": "net_services", + "originalRequest": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"net_services\",\n \"params\": [],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + } + }, + "_postman_previewlanguage": "json", + "header": null, + "cookie": [], + "body": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"result\": {\n \"jsonrpc\": {\n \"host\": \"127.0.0.1\",\n \"port\": \"8545\"\n },\n \"p2p\": {\n \"host\": \"127.0.0.1\",\n \"port\": \"30303\"\n },\n \"metrics\": {\n \"host\": \"127.0.0.1\",\n \"port\": \"9545\"\n }\n }\n}" + } + ] + } + ] + }, + { + "name": "PERM (permissioning)", + "item": [ + { + "name": "perm_addAccountsToAllowlist", + "request": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"perm_addAccountsToAllowlist\",\n \"params\": [\n [\n \"0xb9b81ee349c3807e46bc71aa2632203c5b462032\",\n \"0xb9b81ee349c3807e46bc71aa2632203c5b462034\"\n ]\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + }, + "description": "Adds accounts (participants) to the\n[accounts permission list](https://besu.hyperledger.org/en/stable/HowTo/Limit-Access/Local-Permissioning#account-permissioning).\n\n#### Parameters\n\n`list of strings` - List of account addresses.\n\n> **Note**\n>\n> The parameters list contains a list which is why the account addresses are enclosed by double square brackets.\n\n#### Returns\n\n`result` - `Success` or `error`. Errors include attempting to add accounts already on the\nallowlist or including invalid account addresses.\n" + }, + "response": [ + { + "name": "perm_addAccountsToAllowlist", + "originalRequest": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"perm_addAccountsToAllowlist\",\n \"params\": [\n [\n \"0xb9b81ee349c3807e46bc71aa2632203c5b462032\",\n \"0xb9b81ee349c3807e46bc71aa2632203c5b462034\"\n ]\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + } + }, + "code": 200, + "_postman_previewlanguage": "json", + "header": null, + "cookie": [], + "body": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"result\": \"Success\"\n}" + } + ] + }, + { + "name": "perm_addNodesToAllowlist", + "request": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"perm_addNodesToAllowlist\",\n \"params\": [\n [\n \"enode://7e4ef30e9ec683f26ad76ffca5b5148fa7a6575f4cfad4eb0f52f9c3d8335f4a9b6f9e66fcc73ef95ed7a2a52784d4f372e7750ac8ae0b544309a5b391a23dd7@127.0.0.1:30303\",\n \"enode://2feb33b3c6c4a8f77d84a5ce44954e83e5f163e7a65f7f7a7fec499ceb0ddd76a46ef635408c513d64c076470eac86b7f2c8ae4fcd112cb28ce82c0d64ec2c94@127.0.0.1:30304\"\n ]\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + }, + "description": "Adds nodes to the\n[nodes allowlist](https://besu.hyperledger.org/en/stable/HowTo/Limit-Access/Local-Permissioning#node-allowlisting).\n\n#### Parameters\n\n`list of strings` - List of [enode URLs](https://besu.hyperledger.org/en/stable/Concepts/Node-Keys#enode-url).\n\n> **Note**\n>\n> The parameters list contains a list which is why the enode URLs are enclosed by double square brackets.\n\n#### Returns\n\n`result` - `Success` or `error`. Errors include attempting to add nodes already on the allowlist or\nincluding invalid enode URLs." + }, + "response": [ + { + "name": "perm_addNodesToAllowlist", + "originalRequest": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"perm_addNodesToAllowlist\",\n \"params\": [\n [\n \"enode://7e4ef30e9ec683f26ad76ffca5b5148fa7a6575f4cfad4eb0f52f9c3d8335f4a9b6f9e66fcc73ef95ed7a2a52784d4f372e7750ac8ae0b544309a5b391a23dd7@127.0.0.1:30303\",\n \"enode://2feb33b3c6c4a8f77d84a5ce44954e83e5f163e7a65f7f7a7fec499ceb0ddd76a46ef635408c513d64c076470eac86b7f2c8ae4fcd112cb28ce82c0d64ec2c94@127.0.0.1:30304\"\n ]\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + } + }, + "code": 200, + "_postman_previewlanguage": "json", + "header": null, + "cookie": [], + "body": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"result\": \"Success\"\n}" + } + ] + }, + { + "name": "perm_getAccountsAllowlist", + "request": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"perm_getAccountsAllowlist\",\n \"params\": [],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + }, + "description": "Lists accounts (participants) in the\n[accounts permissions list](https://besu.hyperledger.org/en/stable/HowTo/Limit-Access/Local-Permissioning#account-permissioning).\n\n#### Parameters\n\nNone\n\n#### Returns\n\n`result: list` - Accounts (participants) in the accounts allowlist." + }, + "response": [ + { + "name": "perm_getAccountsAllowlist", + "originalRequest": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"perm_getAccountsAllowlist\",\n \"params\": [],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + } + }, + "code": 200, + "_postman_previewlanguage": "json", + "header": null, + "cookie": [], + "body": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"result\": [\n \"0x0000000000000000000000000000000000000009\",\n \"0xb9b81ee349c3807e46bc71aa2632203c5b462033\"\n ]\n}" + } + ] + }, + { + "name": "perm_getNodesAllowlist", + "request": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"perm_getNodesAllowlist\",\n \"params\": [],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + }, + "description": "Lists nodes in the\n[nodes allowlist](https://besu.hyperledger.org/en/stable/HowTo/Limit-Access/Local-Permissioning#node-allowlisting).\n\n#### Parameters\n\nNone\n\n#### Returns\n\n`result: list` - [Enode URLs](https://besu.hyperledger.org/en/stable/Concepts/Node-Keys#enode-url) of nodes in the nodes allowlist." + }, + "response": [ + { + "name": "perm_getNodesAllowlist", + "originalRequest": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"perm_getNodesAllowlist\",\n \"params\": [],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + } + }, + "code": 200, + "_postman_previewlanguage": "json", + "header": null, + "cookie": [], + "body": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"result\": [\n \"enode://7b61d5ee4b44335873e6912cb5dd3e3877c860ba21417c9b9ef1f7e500a82213737d4b269046d0669fb2299a234ca03443f25fe5f706b693b3669e5c92478ade@127.0.0.1:30305\",\n \"enode://2feb33b3c6c4a8f77d84a5ce44954e83e5f163e7a65f7f7a7fec499ceb0ddd76a46ef635408c513d64c076470eac86b7f2c8ae4fcd112cb28ce82c0d64ec2c94@127.0.0.1:30304\"\n ]\n}" + } + ] + }, + { + "name": "perm_reloadPermissionsFromFile", + "request": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"perm_reloadPermissionsFromFile\",\n \"params\": [],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + }, + "description": "Reloads the accounts and nodes allowlists from the [permissions configuration file].\n\n#### Parameters\n\nNone\n\n#### Returns\n\n`result` - `Success`, or `error` if the permissions configuration file is not valid." + }, + "response": [ + { + "name": "perm_reloadPermissionsFromFile", + "originalRequest": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"perm_reloadPermissionsFromFile\",\n \"params\": [],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + } + }, + "code": 200, + "_postman_previewlanguage": "json", + "header": null, + "cookie": [], + "body": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"result\": \"Success\"\n}" + } + ] + }, + { + "name": "perm_removeAccountsFromAllowlist", + "request": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"perm_removeAccountsFromAllowlist\",\n \"params\": [\n [\n \"0xb9b81ee349c3807e46bc71aa2632203c5b462032\",\n \"0xb9b81ee349c3807e46bc71aa2632203c5b462034\"\n ]\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + }, + "description": "Removes accounts (participants) from the\n[accounts permissions list](https://besu.hyperledger.org/en/stable/HowTo/Limit-Access/Local-Permissioning#account-permissioning).\n\n#### Parameters\n\n`list of strings` - List of account addresses.\n\n> **Note**\n>\n> The parameters list contains a list which is why the account addresses are enclosed by double square brackets.\n\n#### Returns\n\n`result` - `Success` or `error`. Errors include attempting to remove accounts not on the allowlist\nor including invalid account addresses." + }, + "response": [ + { + "name": "perm_removeAccountsFromAllowlist", + "originalRequest": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"perm_removeAccountsFromAllowlist\",\n \"params\": [\n [\n \"0xb9b81ee349c3807e46bc71aa2632203c5b462032\",\n \"0xb9b81ee349c3807e46bc71aa2632203c5b462034\"\n ]\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + } + }, + "code": 200, + "_postman_previewlanguage": "json", + "header": null, + "cookie": [], + "body": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"result\": \"Success\"\n}" + } + ] + }, + { + "name": "perm_removeNodesFromAllowlist", + "request": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"perm_removeNodesFromAllowlist\",\n \"params\": [\n [\n \"enode://7e4ef30e9ec683f26ad76ffca5b5148fa7a6575f4cfad4eb0f52f9c3d8335f4a9b6f9e66fcc73ef95ed7a2a52784d4f372e7750ac8ae0b544309a5b391a23dd7@127.0.0.1:30303\",\n \"enode://2feb33b3c6c4a8f77d84a5ce44954e83e5f163e7a65f7f7a7fec499ceb0ddd76a46ef635408c513d64c076470eac86b7f2c8ae4fcd112cb28ce82c0d64ec2c94@127.0.0.1:30304\"\n ]\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + }, + "description": "Removes nodes from the\n[nodes allowlist](https://besu.hyperledger.org/en/stable/HowTo/Limit-Access/Local-Permissioning#node-allowlisting).\n\n#### Parameters\n\n`list of strings` - List of [enode URLs](https://besu.hyperledger.org/en/stable/Concepts/Node-Keys#enode-url)\n\n> **Note**\n>\n> The parameters list contains a list which is why the enode URLs are enclosed by double square brackets.\n\n#### Returns\n\n`result` - `Success` or `error`. Errors include attempting to remove nodes not on the allowlist\nor including invalid enode URLs." + }, + "response": [ + { + "name": "perm_removeNodesFromAllowlist", + "originalRequest": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"perm_removeNodesFromAllowlist\",\n \"params\": [\n [\n \"enode://7e4ef30e9ec683f26ad76ffca5b5148fa7a6575f4cfad4eb0f52f9c3d8335f4a9b6f9e66fcc73ef95ed7a2a52784d4f372e7750ac8ae0b544309a5b391a23dd7@127.0.0.1:30303\",\n \"enode://2feb33b3c6c4a8f77d84a5ce44954e83e5f163e7a65f7f7a7fec499ceb0ddd76a46ef635408c513d64c076470eac86b7f2c8ae4fcd112cb28ce82c0d64ec2c94@127.0.0.1:30304\"\n ]\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + } + }, + "code": 200, + "_postman_previewlanguage": "json", + "header": null, + "cookie": [], + "body": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"result\": \"Success\"\n}" + } + ] + } + ], + "description": "Use the permissioning API methods for [local](https://besu.hyperledger.org/en/stable/HowTo/Limit-Access/Local-Permissioning)\npermissioning only.\n\n> **Note**\n>\n>The `PERM` API methods are not enabled by default for JSON-RPC. To enable the `PERM` API methods, use the [`--rpc-http-api`](https://besu.hyperledger.org/en/stable/CLI/CLI-Syntax#rpc-http-api) or [`--rpc-ws-api`](https://besu.hyperledger.org/en/stable/CLI/CLI-Syntax#rpc-ws-api) CLI options." + }, + { + "name": "PLUGINS", + "item": [ + { + "name": "plugins_reloadPluginConfig", + "request": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"plugins_reloadPluginConfig\",\n \"params\": [\n \"tech.pegasys.plus.plugin.kafka.KafkaPlugin\"\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": null, + "description": "Reloads specified plugin configuration.\n\n#### Parameters\n\n`string` - Plugin\n\n#### Returns\n\n`string` - `Success`" + }, + "response": [ + { + "name": "plugins_reloadPluginConfig", + "originalRequest": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"plugins_reloadPluginConfig\",\n \"params\": [\n \"tech.pegasys.plus.plugin.kafka.KafkaPlugin\"\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": null + }, + "code": 200, + "_postman_previewlanguage": "json", + "header": null, + "cookie": [], + "body": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"result\": \"Success\"\n}" + } + ] + } + ], + "description": "> **Note**\n>\n> The `PLUGINS` API methods are not enabled by default for JSON-RPC. To enable the `PLUGINS` API methods, use the [`--rpc-http-api`](https://besu.hyperledger.org/en/stable/CLI/CLI-Syntax#rpc-http-api) or [`--rpc-ws-api`](https://besu.hyperledger.org/en/stable/CLI/CLI-Syntax#rpc-ws-api) options." + }, + { + "name": "PRIV", + "item": [ + { + "name": "priv_call", + "request": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"priv_call\",\n \"params\": [\n \"tb8NVyQqZnHNegf/3mYsyB+HEud4SPWn90rz3GoskRw=\",\n {\n \"to\": \"0x69498dd54bd25aa0c886cf1f8b8ae0856d55ff13\",\n \"data\": \"0x3fa4f245\"\n },\n \"latest\"\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + } + }, + "response": [ + { + "name": "priv_call", + "originalRequest": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"priv_call\",\n \"params\": [\n \"tb8NVyQqZnHNegf/3mYsyB+HEud4SPWn90rz3GoskRw=\",\n {\n \"to\": \"0x69498dd54bd25aa0c886cf1f8b8ae0856d55ff13\",\n \"data\": \"0x3fa4f245\"\n },\n \"latest\"\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + } + }, + "code": 200, + "_postman_previewlanguage": "json", + "header": null, + "cookie": [], + "body": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"result\": \"0x0000000000000000000000000000000000000000000000000000000000000001\"\n}" + } + ] + }, + { + "name": "priv_createPrivacyGroup", + "request": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"priv_createPrivacyGroup\",\n \"params\": [\n {\n \"addresses\": [\n \"sTZpbQhcOfd9ZaFDnC00e/N2Ofv9p4/ZTBbEeVtXJ3E=\",\n \"quhb1pQPGN1w8ZSZSyiIfncEAlVY/M/rauSyQ5wVMRE=\"\n ],\n \"name\": \"Group A\",\n \"description\": \"Description Group A\"\n }\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + }, + "description": "Creates a group of nodes, specified by their [Tessera](https://docs.tessera.consensys.net/) public key.\n\n#### Parameters\n\n`Object` - Request options:\n\n* `addresses`: `array of data` - Array of nodes, specified by\n [Tessera](https://docs.tessera.consensys.net/) public keys.\n* `name`: `string` - Privacy group name. Optional.\n* `description`: `string` - Privacy group description. Optional.\n\n#### Returns\n\nPrivacy group ID" + }, + "response": [ + { + "name": "priv_createPrivacyGroup", + "originalRequest": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"priv_createPrivacyGroup\",\n \"params\": [\n {\n \"addresses\": [\n \"sTZpbQhcOfd9ZaFDnC00e/N2Ofv9p4/ZTBbEeVtXJ3E=\",\n \"quhb1pQPGN1w8ZSZSyiIfncEAlVY/M/rauSyQ5wVMRE=\"\n ],\n \"name\": \"Group A\",\n \"description\": \"Description Group A\"\n }\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + } + }, + "code": 200, + "_postman_previewlanguage": "json", + "header": null, + "cookie": [], + "body": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"result\": \"ewuTVoc5nlvWMwTFdRRK/wvV0dcyQo/Pauvx5bNEbTk=\"\n}" + } + ] + }, + { + "name": "priv_deletePrivacyGroup", + "request": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"priv_deletePrivacyGroup\",\n \"params\": [\n \"ewuTVoc5nlvWMwTFdRRK/wvV0dcyQo/Pauvx5bNEbTk=\"\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + }, + "description": "Deletes the specified privacy group.\n\n#### Parameters\n\n`data` - Privacy group ID\n\n#### Returns\n\nPrivacy group ID that was deleted." + }, + "response": [ + { + "name": "priv_deletePrivacyGroup", + "originalRequest": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"priv_deletePrivacyGroup\",\n \"params\": [\n \"ewuTVoc5nlvWMwTFdRRK/wvV0dcyQo/Pauvx5bNEbTk=\"\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + } + }, + "code": 200, + "_postman_previewlanguage": "json", + "header": null, + "cookie": [], + "body": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 53,\n \"result\": \"ewuTVoc5nlvWMwTFdRRK/wvV0dcyQo/Pauvx5bNEbTk=\"\n}" + } + ] + }, + { + "name": "priv_distributeRawTransaction", + "request": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"priv_distributeRawTransaction\",\n \"params\": [\n \"0xf869018203e882520894f17f52151ebef6c7334fad080c5704d77216b732881bc16d674ec80000801ba02da1c48b670996dcb1f447ef9ef00b33033c48a4fe938f420bec3e56bfd24071a062e0aa78a81bf0290afbc3a9d8e9a068e6d74caa66c5e0fa8a46deaae96b0833\"\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + }, + "description": "Distributes a signed, RLP encoded\n[private transaction](https://besu.hyperledger.org/en/stable/HowTo/Send-Transactions/Creating-Sending-Private-Transactions).\n\n> **tip**\n\n If you want to sign the Privacy Marker Transaction outside of Besu,\n use [`priv_distributeRawTransaction`](https://besu.hyperledger.org/en/stable//HowTo/Send-Transactions/Creating-Sending-Private-Transactions#priv_distributerawtransaction)\n instead of [`eea_sendRawTransaction`](#eea_sendrawtransaction).\n\n#### Parameters\n\n`data` - Signed RLP-encoded private transaction. For example:\n\n`params: [\"0xf869018203e882520894f17f52151ebef6c7334fad080c5704d77216b732881bc16d674ec80000801ba02da1c48b670996dcb1f447ef9ef00b33033c48a4fe938f420bec3e56bfd24071a062e0aa78a81bf0290afbc3a9d8e9a068e6d74caa66c5e0fa8a46deaae96b0833\"]`\n\n#### Returns\n\n`result` : `data` - 32-byte enclave key. The enclave key is a pointer to the private transaction in\n[Tessera](https://docs.tessera.consensys.net/)." + }, + "response": [ + { + "name": "priv_distributeRawTransaction", + "originalRequest": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"priv_distributeRawTransaction\",\n \"params\": [\n \"0xf869018203e882520894f17f52151ebef6c7334fad080c5704d77216b732881bc16d674ec80000801ba02da1c48b670996dcb1f447ef9ef00b33033c48a4fe938f420bec3e56bfd24071a062e0aa78a81bf0290afbc3a9d8e9a068e6d74caa66c5e0fa8a46deaae96b0833\"\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + } + }, + "code": 200, + "_postman_previewlanguage": "json", + "header": null, + "cookie": [], + "body": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"result\": \"0xfd0d90ab824574abc19c0776ca0210e764561d0ef6d621f2bbbea316eccfe56b\"\n}" + } + ] + }, + { + "name": "priv_findPrivacyGroup", + "request": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"priv_findPrivacyGroup\",\n \"params\": [\n [\n \"negmDcN2P4ODpqn/6WkJ02zT/0w0bjhGpkZ8UP6vARk=\",\n \"g59BmTeJIn7HIcnq8VQWgyh/pDbvbt2eyP0Ii60aDDw=\"\n ]\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + }, + "description": "Returns a list of privacy groups containing only the listed members. For example, if the listed\nmembers are A and B, a privacy group containing A, B, and C is not returned.\n\n#### Parameters\n\n`array of data` - Members specified by [Tessera](https://docs.tessera.consensys.net/) public keys.\n\n#### Returns\n\nPrivacy groups containing only the specified members. Privacy groups are\n[EEA-compliant](https://besu.hyperledger.org/en/stable/Concepts/Privacy/Privacy-Groups#enterprise-ethereum-alliance-privacy)\nor [Besu-extended](https://besu.hyperledger.org/en/stable/Concepts/Privacy/Privacy-Groups#besu-extended-privacy) with types:\n\n* `LEGACY` for EEA-compliant groups.\n* `PANTHEON` for Besu-extended groups." + }, + "response": [ + { + "name": "priv_findPrivacyGroup", + "originalRequest": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"priv_findPrivacyGroup\",\n \"params\": [\n [\n \"negmDcN2P4ODpqn/6WkJ02zT/0w0bjhGpkZ8UP6vARk=\",\n \"g59BmTeJIn7HIcnq8VQWgyh/pDbvbt2eyP0Ii60aDDw=\"\n ]\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + } + }, + "code": 200, + "_postman_previewlanguage": "json", + "header": null, + "cookie": [], + "body": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"result\": [\n {\n \"privacyGroupId\": \"GpK3ErNO0xF27T0sevgkJ3+4qk9Z+E3HtXYxcKIBKX8=\",\n \"name\": \"Group B\",\n \"description\": \"Description of Group B\",\n \"type\": \"PANTHEON\",\n \"members\": [\n \"negmDcN2P4ODpqn/6WkJ02zT/0w0bjhGpkZ8UP6vARk=\",\n \"g59BmTeJIn7HIcnq8VQWgyh/pDbvbt2eyP0Ii60aDDw=\"\n ]\n }\n ]\n}" + } + ] + }, + { + "name": "priv_getCode", + "request": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"priv_getCode\",\n \"params\": [\n \"1lJxSIP4JOp6uRn9wYsPeWwqoOP1c4nPQjylB4FExUA=\",\n \"0xeaf1c1bd00ef0bec5e39fba81740f1c5d05aa201\",\n \"latest\"\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + }, + "description": "Returns the code of the private smart contract at the specified address. Compiled smart contract code\nis stored as a hexadecimal value.\n\n#### Parameters\n\n`data` - 32-byte [privacy Group ID](https://besu.hyperledger.org/en/stable/Concepts/Privacy/Privacy-Groups).\n\n`data` - 20-byte contract address.\n\n`quantity|tag` - Integer representing a block number or one of the string tags `latest`, `earliest`,\nor `pending`, as described in [Block Parameter](https://besu.hyperledger.org/en/stable/HowTo/Interact/APIs/Using-JSON-RPC-API#block-parameter).\n\n#### Returns\n\n`result` : `data` - Code stored at the specified address." + }, + "response": [ + { + "name": "priv_getCode", + "originalRequest": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"priv_getCode\",\n \"params\": [\n \"1lJxSIP4JOp6uRn9wYsPeWwqoOP1c4nPQjylB4FExUA=\",\n \"0xeaf1c1bd00ef0bec5e39fba81740f1c5d05aa201\",\n \"latest\"\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + } + }, + "code": 200, + "_postman_previewlanguage": "json", + "header": null, + "cookie": [], + "body": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"result\": \"0x60806040526004361060485763ffffffff7c01000000000000000000000000000000000000000000000000000000006000350416633fa4f2458114604d57806355241077146071575b600080fd5b348015605857600080fd5b50605f6088565b60408051918252519081900360200190f35b348015607c57600080fd5b506086600435608e565b005b60005481565b60008190556040805182815290517f199cd93e851e4c78c437891155e2112093f8f15394aa89dab09e38d6ca0727879181900360200190a1505600a165627a7a723058209d8929142720a69bde2ab3bfa2da6217674b984899b62753979743c0470a2ea70029\"\n}" + } + ] + }, + { + "name": "priv_getEeaTransactionCount", + "request": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"priv_getEeaTransactionCount\",\n \"params\": [\n \"0xfe3b557e8fb62b89f4916b721be55ceb828dbd73\",\n \"GGilEkXLaQ9yhhtbpBT03Me9iYa7U/mWXxrJhnbl1XY=\",\n [\n \"KkOjNLmCI6r+mICrC6l+XuEDjFEzQllaMQMpWLl4y1s=\",\n \"eLb69r4K8/9WviwlfDiZ4jf97P9czyS3DkKu0QYGLjg=\"\n ]\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + }, + "description": "Returns the private transaction count for the specified account and\n[group of sender and recipients].\n\n> **Important**\n\n> If sending more than one transaction to be mined in the same block (that is, you are not\n> waiting for the transaction receipt), you must calculate the private transaction nonce outside\n> Besu instead of using `priv_getEeaTransactionCount`.\n\n#### Parameters\n\n`data` - Account address.\n\n`data` - Base64 encoded Tessera address of the sender.\n\n`array of data` - Base64 encoded Tessera addresses of recipients.\n\n#### Returns\n\n`quantity` - Integer representing the number of private transactions sent from the address to the\nspecified group of sender and recipients.\n" + }, + "response": [ + { + "name": "priv_getEeaTransactionCount", + "originalRequest": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"priv_getEeaTransactionCount\",\n \"params\": [\n \"0xfe3b557e8fb62b89f4916b721be55ceb828dbd73\",\n \"GGilEkXLaQ9yhhtbpBT03Me9iYa7U/mWXxrJhnbl1XY=\",\n [\n \"KkOjNLmCI6r+mICrC6l+XuEDjFEzQllaMQMpWLl4y1s=\",\n \"eLb69r4K8/9WviwlfDiZ4jf97P9czyS3DkKu0QYGLjg=\"\n ]\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + } + }, + "code": 200, + "_postman_previewlanguage": "json", + "header": null, + "cookie": [], + "body": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"result\": \"0x1\"\n}" + } + ] + }, + { + "name": "priv_getFilterChanges", + "request": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"priv_getFilterChanges\",\n \"params\": [\n \"4rFldHM792LeP/e2WPkTXZedjwKuTr/KwCFTt6mBbkI=\",\n \"0x4a35b92809d73f4f53a2355d62125442\"\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + }, + "description": "Polls the specified filter for a private contract and returns an array of changes that have occurred\nsince the last poll.\n\nFilters for private contracts can only be created by [`priv_newFilter`](#priv_newfilter) so unlike\n[`eth_getFilterChanges`](#eth_getfilterchanges), `priv_getFilterChanges` always returns an array\nof log objects or an empty list.\n\n#### Parameters\n\n`data` - 32-byte [privacy Group ID](https://besu.hyperledger.org/en/stable/Concepts/Privacy/Privacy-Groups).\n\n`data` - Filter ID.\n\n#### Returns\n\n`array` - [Log objects](https://besu.hyperledger.org/en/stable/Reference/API-Objects#log-object). If nothing has changed since the last poll, an\nempty list." + }, + "response": [ + { + "name": "priv_getFilterChanges", + "originalRequest": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"priv_getFilterChanges\",\n \"params\": [\n \"4rFldHM792LeP/e2WPkTXZedjwKuTr/KwCFTt6mBbkI=\",\n \"0x4a35b92809d73f4f53a2355d62125442\"\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + } + }, + "code": 200, + "_postman_previewlanguage": "json", + "header": null, + "cookie": [], + "body": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"result\": [\n {\n \"logIndex\": \"0x0\",\n \"removed\": false,\n \"blockNumber\": \"0x4d0\",\n \"blockHash\": \"0x1c8200667a869e99b945374c37277b5ee7a7ae67943e13c82563381387553dbb\",\n \"transactionHash\": \"0xb1966b9b372ba68952f48f3a3e78f036f5ae82ceca2de972a782d07fb88f6d88\",\n \"transactionIndex\": \"0x0\",\n \"address\": \"0x991cc548c154b2953cc48c02f782e1314097dfbb\",\n \"data\": \"0x\",\n \"topics\": [\n \"0x85bea11d86cefb165374e0f727bacf21dc2f4ea816493981ecf72dcfb212a410\",\n \"0x0000000000000000000000000000000000000000000000000000000000000002\"\n ]\n }\n ]\n}" + } + ] + }, + { + "name": "priv_getFilterLogs", + "request": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"priv_getFilterLogs\",\n \"params\": [\n \"4rFldHM792LeP/e2WPkTXZedjwKuTr/KwCFTt6mBbkI=\",\n \"0x4a35b92809d73f4f53a2355d62125442\"\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + }, + "description": "Returns an array of [logs](https://besu.hyperledger.org/en/stable/Concepts/Events-and-Logs) for the specified filter for a private\ncontract.\n\nFor private contracts, `priv_getFilterLogs` is the same as [`eth_getFilterLogs`](#eth_getfilterlogs)\nfor public contracts except there is no [automatic log bloom caching](https://besu.hyperledger.org/en/stable/CLI/CLI-Syntax#auto-log-bloom-caching-enabled)\nfor private contracts.\n\n> **Note**\n>\n> `priv_getFilterLogs` is only used for filters created with [`priv_newFilter`](#priv_newfilter).\n> To specify a filter object and get logs without creating a filter, use [`priv_getLogs`](#priv_getlogs).\n\n#### Parameters\n\n`data` - 32-byte [privacy Group ID](https://besu.hyperledger.org/en/stable/Concepts/Privacy/Privacy-Groups).\n\n`data` - Filter ID.\n\n#### Returns\n\n`array` - [Log objects](https://besu.hyperledger.org/en/stable/Reference/API-Objects#log-object)." + }, + "response": [ + { + "name": "priv_getFilterLogs", + "originalRequest": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"priv_getFilterLogs\",\n \"params\": [\n \"4rFldHM792LeP/e2WPkTXZedjwKuTr/KwCFTt6mBbkI=\",\n \"0x4a35b92809d73f4f53a2355d62125442\"\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + } + }, + "code": 200, + "_postman_previewlanguage": "json", + "header": null, + "cookie": [], + "body": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"result\": [\n {\n \"logIndex\": \"0x0\",\n \"removed\": false,\n \"blockNumber\": \"0x493\",\n \"blockHash\": \"0xd9cb3a852e1e02c95f035a2e32d57f82c10cab61faa3e8f5c010adf979bb4786\",\n \"transactionHash\": \"0x78866dc51fdf189d8cca74f6a8fe54f172348fbd2163bbe80fa8b106cfc7deb4\",\n \"transactionIndex\": \"0x0\",\n \"address\": \"0x991cc548c154b2953cc48c02f782e1314097dfbb\",\n \"data\": \"0x\",\n \"topics\": [\n \"0x85bea11d86cefb165374e0f727bacf21dc2f4ea816493981ecf72dcfb212a410\",\n \"0x0000000000000000000000000000000000000000000000000000000000000001\"\n ]\n },\n {\n \"logIndex\": \"0x0\",\n \"removed\": false,\n \"blockNumber\": \"0x4d0\",\n \"blockHash\": \"0x1c8200667a869e99b945374c37277b5ee7a7ae67943e13c82563381387553dbb\",\n \"transactionHash\": \"0xb1966b9b372ba68952f48f3a3e78f036f5ae82ceca2de972a782d07fb88f6d88\",\n \"transactionIndex\": \"0x0\",\n \"address\": \"0x991cc548c154b2953cc48c02f782e1314097dfbb\",\n \"data\": \"0x\",\n \"topics\": [\n \"0x85bea11d86cefb165374e0f727bacf21dc2f4ea816493981ecf72dcfb212a410\",\n \"0x0000000000000000000000000000000000000000000000000000000000000002\"\n ]\n }\n ]\n}" + } + ] + }, + { + "name": "priv_getLogs", + "request": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"priv_getLogs\",\n \"params\": [\n \"vGy/TZgO6y8VPMVeJAQ99MF1NaTf5ohA3TFfzoEF71k=\",\n {\n \"fromBlock\": \"earliest\",\n \"toBlock\": \"latest\",\n \"addresses\": [\n \"0x630c507ff633312087dc33c513b66276abcd2fc3\"\n ],\n \"topics\": [\n \"0x85bea11d86cefb165374e0f727bacf21dc2f4ea816493981ecf72dcfb212a410\"\n ]\n }\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + }, + "description": "Returns an array of [logs](https://besu.hyperledger.org/en/stable/Concepts/Events-and-Logs) matching a specified filter object.\n\nFor private contracts, `priv_getLogs` is the same as [`eth_getLogs`](#eth_getlogs) for public contracts\nexcept there is no [automatic log bloom caching](https://besu.hyperledger.org/en/stable/CLI/CLI-Syntax#auto-log-bloom-caching-enabled)\nfor private contracts.\n\n#### Parameters\n\n`data` - 32-byte [privacy Group ID](https://besu.hyperledger.org/en/stable/Concepts/Privacy/Privacy-Groups).\n\n`Object` - [Filter options object](https://besu.hyperledger.org/en/stable/Reference/API-Objects#filter-options-object).\n\n#### Returns\n\n`array` - [Log objects](https://besu.hyperledger.org/en/stable/Reference/API-Objects#log-object)." + }, + "response": [ + { + "name": "priv_getLogs", + "originalRequest": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"priv_getLogs\",\n \"params\": [\n \"vGy/TZgO6y8VPMVeJAQ99MF1NaTf5ohA3TFfzoEF71k=\",\n {\n \"fromBlock\": \"earliest\",\n \"toBlock\": \"latest\",\n \"addresses\": [\n \"0x630c507ff633312087dc33c513b66276abcd2fc3\"\n ],\n \"topics\": [\n \"0x85bea11d86cefb165374e0f727bacf21dc2f4ea816493981ecf72dcfb212a410\"\n ]\n }\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + } + }, + "code": 200, + "_postman_previewlanguage": "json", + "header": null, + "cookie": [], + "body": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"result\": [\n {\n \"logIndex\": \"0x0\",\n \"removed\": false,\n \"blockNumber\": \"0x342\",\n \"blockHash\": \"0xf5954f068fa2f2f7741281e8c753a8e92047e27ab3c4971836d2c89fab86d92b\",\n \"transactionHash\": \"0xa9ba5cffde9d4ad8997c5c4352d5d49eeea0e9def8a4ea69991b8837c49d4e4f\",\n \"transactionIndex\": \"0x0\",\n \"address\": \"0x630c507ff633312087dc33c513b66276abcd2fc3\",\n \"data\": \"0x\",\n \"topics\": [\n \"0x85bea11d86cefb165374e0f727bacf21dc2f4ea816493981ecf72dcfb212a410\",\n \"0x0000000000000000000000000000000000000000000000000000000000000001\"\n ]\n },\n {\n \"logIndex\": \"0x0\",\n \"removed\": false,\n \"blockNumber\": \"0x383\",\n \"blockHash\": \"0x91b73a47d53e3a88d62ed091a89a4be7557ad91b552e7ff7d86bf78977d5d45d\",\n \"transactionHash\": \"0xc2a185faf00e87434e55b7f70cc4c38be354c2128b4b96b5f5def0b54a2173ec\",\n \"transactionIndex\": \"0x0\",\n \"address\": \"0x630c507ff633312087dc33c513b66276abcd2fc3\",\n \"data\": \"0x\",\n \"topics\": [\n \"0x85bea11d86cefb165374e0f727bacf21dc2f4ea816493981ecf72dcfb212a410\",\n \"0x0000000000000000000000000000000000000000000000000000000000000002\"\n ]\n }\n ]\n}" + } + ] + }, + { + "name": "priv_getPrivacyPrecompileAddress", + "request": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"priv_getPrivacyPrecompileAddress\",\n \"params\": [],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + }, + "description": "Returns the address of the\n[privacy precompiled contract](https://besu.hyperledger.org/en/stable/Concepts/Privacy/Private-Transaction-Processing). The address\nis derived and based on the value of the [`privacy-onchain-groups-enabled`](https://besu.hyperledger.org/en/stable/CLI/CLI-Syntax#privacy-onchain-groups-enabled)\noption.\n\n#### Parameters\n\nNone\n\n#### Returns\n\n`result` : `data` - Address of the privacy precompile." + }, + "response": [ + { + "name": "priv_getPrivacyPrecompileAddress", + "originalRequest": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"priv_getPrivacyPrecompileAddress\",\n \"params\": [],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + } + }, + "code": 200, + "_postman_previewlanguage": "json", + "header": null, + "cookie": [], + "body": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"result\": \"0x000000000000000000000000000000000000007e\"\n}" + } + ] + }, + { + "name": "priv_getPrivateTransaction", + "request": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"priv_getPrivateTransaction\",\n \"params\": [\n \"0x623c4ce5275a87b91f4f1c521012d39ca19311c787bde405490f4c0426a71498\"\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + }, + "description": "Returns the private transaction if you are a participant, otherwise, `null`.\n\n#### Parameters\n\n`data` - Transaction hash returned by [`eea_sendRawTransaction`](#eea_sendrawtransaction) or\n[`eea_sendTransaction`](https://docs.ethsigner.consensys.net/Reference/API-Methods#eea_sendtransaction).\n\n#### Returns\n\nObject - [Private transaction object](https://besu.hyperledger.org/en/stable/Reference/API-Objects#private-transaction-object), or `null` if not\na participant in the private transaction." + }, + "response": [ + { + "name": "priv_getPrivateTransaction", + "originalRequest": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"priv_getPrivateTransaction\",\n \"params\": [\n \"0x623c4ce5275a87b91f4f1c521012d39ca19311c787bde405490f4c0426a71498\"\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + } + }, + "code": 200, + "_postman_previewlanguage": "json", + "header": null, + "cookie": [], + "body": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"result\": {\n \"from\": \"0xfe3b557e8fb62b89f4916b721be55ceb828dbd73\",\n \"gas\": \"0x2dc6c0\",\n \"gasPrice\": \"0x0\",\n \"hash\": \"0x623c4ce5275a87b91f4f1c521012d39ca19311c787bde405490f4c0426a71498\",\n \"input\": \"0x608060405234801561001057600080fd5b50336000806101000a81548173ffffffffffffffffffffffffffffffffffffffff021916908373ffffffffffffffffffffffffffffffffffffffff160217905550610221806100606000396000f300608060405260043610610057576000357c0100000000000000000000000000000000000000000000000000000000900463ffffffff1680633fa4f2451461005c5780636057361d1461008757806367e404ce146100b4575b600080fd5b34801561006857600080fd5b5061007161010b565b6040518082815260200191505060405180910390f35b34801561009357600080fd5b506100b260048036038101908080359060200190929190505050610115565b005b3480156100c057600080fd5b506100c96101cb565b604051808273ffffffffffffffffffffffffffffffffffffffff1673ffffffffffffffffffffffffffffffffffffffff16815260200191505060405180910390f35b6000600254905090565b7fc9db20adedc6cf2b5d25252b101ab03e124902a73fcb12b753f3d1aaa2d8f9f53382604051808373ffffffffffffffffffffffffffffffffffffffff1673ffffffffffffffffffffffffffffffffffffffff1681526020018281526020019250505060405180910390a18060028190555033600160006101000a81548173ffffffffffffffffffffffffffffffffffffffff021916908373ffffffffffffffffffffffffffffffffffffffff16021790555050565b6000600160009054906101000a900473ffffffffffffffffffffffffffffffffffffffff169050905600a165627a7a723058208efaf938851fb2d235f8bf9a9685f149129a30fe0f4b20a6c1885dc02f639eba0029\",\n \"nonce\": \"0x0\",\n \"to\": null,\n \"value\": \"0x0\",\n \"v\": \"0xfe8\",\n \"r\": \"0x654a6a9663ca70bb13e27cca14b3777cc92da184e19a151cdeef2ccbbd5c6405\",\n \"s\": \"0x5dd4667b020c8a5af7ae28d4c3126f8dcb1187f49dcf0de9d7a39b1651892eef\",\n \"privateFrom\": \"negmDcN2P4ODpqn/6WkJ02zT/0w0bjhGpkZ8UP6vARk=\",\n \"privateFor\": [\n \"g59BmTeJIn7HIcnq8VQWgyh/pDbvbt2eyP0Ii60aDDw=\"\n ],\n \"restriction\": \"restricted\"\n }\n}" + } + ] + }, + { + "name": "priv_getTransactionCount", + "request": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"priv_getTransactionCount\",\n \"params\": [\n \"0xfe3b557e8fb62b89f4916b721be55ceb828dbd73\",\n \"kAbelwaVW7okoEn1+okO+AbA4Hhz/7DaCOWVQz9nx5M=\"\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + }, + "description": "Returns the private transaction count for specified account and privacy group.\n\n> **important**\n\n> If sending more than one transaction to be mined in the same block (that is, you are not waiting for the transaction receipt), you must calculate the private transaction nonce outside Besu instead of using `priv_getTransactionCount`.\n\n#### Parameters\n\n`data` - Account address.\n\n`data` - Privacy group ID.\n\n#### Returns\n\n`quantity` - Integer representing the number of private transactions sent from the address to the\nspecified privacy group." + }, + "response": [ + { + "name": "priv_getTransactionCount", + "originalRequest": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"priv_getTransactionCount\",\n \"params\": [\n \"0xfe3b557e8fb62b89f4916b721be55ceb828dbd73\",\n \"kAbelwaVW7okoEn1+okO+AbA4Hhz/7DaCOWVQz9nx5M=\"\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + } + }, + "code": 200, + "_postman_previewlanguage": "json", + "header": null, + "cookie": [], + "body": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"result\": \"0x1\"\n}" + } + ] + }, + { + "name": "priv_getTransactionReceipt", + "request": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"priv_getTransactionReceipt\",\n \"params\": [\n \"0xf3ab9693ad92e277bf785e1772f29fb1864904bbbe87b0470455ddb082caab9d\"\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + }, + "description": "Returns information about the private transaction after mining the transaction. Receipts for\npending transactions are not available.\n\n#### Parameters\n\n`data` - 32-byte hash of a transaction.\n\n#### Returns\n\n`Object` - [Private Transaction receipt object](https://besu.hyperledger.org/en/stable/Reference/API-Objects#private-transaction-receipt-object),\nor `null` if no receipt found." + }, + "response": [ + { + "name": "priv_getTransactionReceipt", + "originalRequest": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"priv_getTransactionReceipt\",\n \"params\": [\n \"0xf3ab9693ad92e277bf785e1772f29fb1864904bbbe87b0470455ddb082caab9d\"\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + } + }, + "code": 200, + "_postman_previewlanguage": "json", + "header": null, + "cookie": [], + "body": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"result\": {\n \"contractAddress\": \"0x493b76031593402e24e16faa81f677b58e2d53f3\",\n \"from\": \"0xfe3b557e8fb62b89f4916b721be55ceb828dbd73\",\n \"output\": \"0x6080604052600436106049576000357c010000000000000000000000000000000000000000000\\n 0000000000000900463ffffffff1680633fa4f24514604e57806355241077146076575b600080fd5b3480156059\\n 57600080fd5b50606060a0565b6040518082815260200191505060405180910390f35b348015608157600080fd5b\\n 50609e6004803603810190808035906020019092919050505060a6565b005b60005481565b8060008190555050560\\n 0a165627a7a723058202bdbba2e694dba8fff33d9d0976df580f57bff0a40e25a46c398f8063b4c00360029\",\n \"commitmentHash\": \"0x79b9e6b0856db398ad7dc208f15b1d38c0c0b0c5f99e4a443a2c5a85510e96a5\",\n \"transactionHash\": \"0x36219e92b5f53d4150aa9ef7d2d793118cced523de6724100da5b534e3ceb4b8\",\n \"privateFrom\": \"negmDcN2P4ODpqn/6WkJ02zT/0w0bjhGpkZ8UP6vARk=\",\n \"privacyGroupId\": \"cD636RZlcqVSpoxT/ExbkWQfBO7kPAZO0QlWHErNSL8=\",\n \"status\": \"0x1\",\n \"logs\": []\n }\n}" + } + ] + }, + { + "name": "priv_newFilter", + "request": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"priv_newFilter\",\n \"params\": [\n \"4rFldHM792LeP/e2WPkTXZedjwKuTr/KwCFTt6mBbkI=\",\n {\n \"fromBlock\": \"earliest\",\n \"toBlock\": \"latest\",\n \"addresses\": [\n \"0x991cc548c154b2953cc48c02f782e1314097dfbb\"\n ],\n \"topics\": [\n \"0x85bea11d86cefb165374e0f727bacf21dc2f4ea816493981ecf72dcfb212a410\"\n ]\n }\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + }, + "description": "Creates a [log filter](https://besu.hyperledger.org/en/stable/Concepts/Events-and-Logs) for a private contract. To poll for logs associated with the\ncreated filter, use [`priv_getFilterChanges`](#priv_getfilterchanges). To get all logs associated with\nthe filter, use [`priv_getFilterLogs`](#priv_getfilterlogs).\n\nFor private contracts, `priv_newFilter` is the same as [`eth_newFilter`](#eth_newfilter)\nfor public contracts.\n\n#### Parameters\n\n`data` - 32-byte [privacy Group ID](https://besu.hyperledger.org/en/stable/Concepts/Privacy/Privacy-Groups).\n\n`Object` - [Filter options object](https://besu.hyperledger.org/en/stable/Reference/API-Objects#filter-options-object).\n\n> **Note**\n>\n> `fromBlock` and `toBlock` in the filter options object default to `latest`." + }, + "response": [ + { + "name": "priv_newFilter", + "originalRequest": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"priv_newFilter\",\n \"params\": [\n \"4rFldHM792LeP/e2WPkTXZedjwKuTr/KwCFTt6mBbkI=\",\n {\n \"fromBlock\": \"earliest\",\n \"toBlock\": \"latest\",\n \"addresses\": [\n \"0x991cc548c154b2953cc48c02f782e1314097dfbb\"\n ],\n \"topics\": [\n \"0x85bea11d86cefb165374e0f727bacf21dc2f4ea816493981ecf72dcfb212a410\"\n ]\n }\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + } + }, + "code": 200, + "_postman_previewlanguage": "json", + "header": null, + "cookie": [], + "body": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"result\": \"0x4a35b92809d73f4f53a2355d62125442\"\n}" + } + ] + }, + { + "name": "priv_uninstallFilter", + "request": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"priv_uninstallFilter\",\n \"params\": [\n \"4rFldHM792LeP/e2WPkTXZedjwKuTr/KwCFTt6mBbkI=\",\n \"0x4a35b92809d73f4f53a2355d62125442\"\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + }, + "description": "Uninstalls a filter for a private contract with the specified ID. When a filter is no longer required,\ncall this method.\n\nFilters time out when not requested by [`priv_getFilterChanges`](#priv_getfilterchanges) or [`priv_getFilterLogs`](#priv_getfilterlogs) for 10\nminutes.\n\nFor private contracts, `priv_uninstallFilter` is the same as [`eth_uninstallFilter`](#eth_uninstallfilter)\nfor public contracts.\n\n#### Parameters\n\n`data` - 32-byte [privacy Group ID](https://besu.hyperledger.org/en/stable/Concepts/Privacy/Privacy-Groups).\n\n`data` - Filter ID.\n\n#### Returns\n\n`Boolean` - `true` if the filter was successfully uninstalled, otherwise `false`." + }, + "response": [ + { + "name": "priv_uninstallFilter", + "originalRequest": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"priv_uninstallFilter\",\n \"params\": [\n \"4rFldHM792LeP/e2WPkTXZedjwKuTr/KwCFTt6mBbkI=\",\n \"0x4a35b92809d73f4f53a2355d62125442\"\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + } + }, + "code": 200, + "_postman_previewlanguage": "json", + "header": null, + "cookie": [], + "body": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"result\": true\n}" + } + ] + } + ], + "description": "> **Note**\n>\n> The `PRIV` API methods are not enabled by default for JSON-RPC. To enable the `PRIV` API methods, use the [`--rpc-http-api`](https://besu.hyperledger.org/en/stable/CLI/CLI-Syntax#rpc-http-api) or [`--rpc-ws-api`](https://besu.hyperledger.org/en/stable/CLI/CLI-Syntax#rpc-ws-api) options." + }, + { + "name": "TRACE", + "item": [ + { + "name": "trace_replayBlockTransactions", + "request": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"trace_replayBlockTransactions\",\n \"params\": [\n \"0x12\",\n [\n \"trace\",\n \"vmTrace\",\n \"stateDiff\"\n ]\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + }, + "description": "Provides transaction processing tracing per block.\n\n> **important**\n\n Your node must be an archive node (that is, synchronized without pruning or fast sync) or the\n requested block must be within [the number of pruning blocks retained](https://besu.hyperledger.org/en/stable/CLI/CLI-Syntax#pruning-blocks-retained)\n (by default, 1024).\n\n#### Parameters\n\n`quantity|tag` - Integer representing a block number or one of the string tags `latest`,\n`earliest`, or `pending`, as described in\n[Block Parameter](https://besu.hyperledger.org/en/stable/HowTo/Interact/APIs/Using-JSON-RPC-API#block-parameter).\n\n`array of strings` - Tracing options are\n[`trace`, `vmTrace`, and `stateDiff`](Trace-Types). Specify any\ncombination of the three options including none of them.\n\n#### Returns\n\n`result` - Array of [transaction trace objects](https://besu.hyperledger.org/en/stable/Reference/API-Objects#transaction-trace-object) containing\none object per transaction, in transaction execution order." + }, + "response": [ + { + "name": "trace_replayBlockTransactions", + "originalRequest": { + "method": "POST", + "header": [], + "url": null + }, + "code": 200, + "_postman_previewlanguage": "json", + "header": null, + "cookie": [], + "body": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"result\":[\n {\n \"output\":\"0x\",\n \"vmTrace\":{\n \"code\":\"0x7f3940be4289e4c3587d88c1856cc95352461992db0a584c281226faefe560b3016000527f14c4d2c102bdeb2354bfc3dc96a95e4512cf3a8461e0560e2272dbf884ef3905601052600851\",\n \"ops\":[\n {\n \"cost\":3,\n \"ex\":{\n \"mem\":null,\n \"push\":[\n \"0x8\"\n ],\n \"store\":null,\n \"used\":16756175\n },\n \"pc\":72,\n \"sub\":null\n },\n {\"other properties...\":\"values...\"}\n ]\n },\n \"trace\":[\n {\n \"action\":{\n \"callType\":\"call\",\n \"from\":\"0xfe3b557e8fb62b89f4916b721be55ceb828dbd73\",\n \"gas\":\"0xffadea\",\n \"input\":\"0x\",\n \"to\":\"0x0100000000000000000000000000000000000000\",\n \"value\":\"0x0\"\n },\n \"result\":{\n \"gasUsed\":\"0x1e\",\n \"output\":\"0x\"\n },\n \"subtraces\":0,\n \"traceAddress\":[\n ],\n \"type\":\"call\"\n }\n ],\n \"stateDiff\":{\n \"0xfe3b557e8fb62b89f4916b721be55ceb828dbd73\":{\n \"balance\":{\n \"*\":{\n \"from\":\"0xffffffffffffffffffffffffffffffffc3e12a20b\",\n \"to\":\"0xffffffffffffffffffffffffffffffffc3dc5f091\"\n }\n },\n \"code\":\"=\",\n \"nonce\":{\n \"*\":{\n \"from\":\"0x14\",\n \"to\":\"0x15\"\n }\n },\n \"storage\":{\n }\n }\n },\n \"transactionHash\":\"0x2a5079cc535c429f668f13a7fb9a28bdba6831b5462bd04f781777b332a8fcbd\",\n },\n {\"other properties...\":\"values...\"}\n ]\n}" + } + ] + }, + { + "name": "trace_block", + "request": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"trace_block\",\n \"params\": [\n \"0x6\"\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + }, + "description": "Provides transaction processing of [type `trace`](Trace-Types#trace) for the specified block.\n\n> **Important**\n>\n> Your node must be an archive node (that is, synchronized without pruning or fast sync) or the\n> requested block must be within [the number of pruning blocks retained](https://besu.hyperledger.org/en/stable/CLI/CLI-Syntax#pruning-blocks-retained) (by default, 1024).\n\n#### Parameters\n\n`quantity|tag` - Integer representing a block number or one of the string tags `latest`,\n`earliest`, or `pending`, as described in\n[Block Parameter](https://besu.hyperledger.org/en/stable/HowTo/Interact/APIs/Using-JSON-RPC-API#block-parameter).\n\n#### Returns\n\n`result` - Array of [calls to other contracts](Trace-Types#trace) containing\none object per call, in transaction execution order." + }, + "response": [ + { + "name": "trace_block", + "originalRequest": { + "method": "POST", + "header": [], + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + } + }, + "_postman_previewlanguage": null, + "header": null, + "cookie": [], + "body": null + } + ] + }, + { + "name": "trace_transaction", + "request": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"trace_transaction\",\n \"params\": [\n \"0x4c253746668dca6ac3f7b9bc18248b558a95b5fc881d140872c2dff984d344a7\"\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + }, + "description": "Provides transaction processing of [type `trace`](Trace-Types#trace) for the specified transaction.\n\n> **Important**\n>\n> Your node must be an archive node (that is, synchronized without pruning or fast sync) or the\n> requested transaction must be contained in a block within [the number of pruning blocks retained](https://besu.hyperledger.org/en/stable/CLI/CLI-Syntax#pruning-blocks-retained) (by default, 1024).\n\n#### Parameters\n\n`data` : Transaction hash\n\n#### Returns\n\n`result` - Array of [calls to other contracts](Trace-Types#trace) containing\none object per call, in the order called by the transaction.\n" + }, + "response": [ + { + "name": "trace_transaction", + "originalRequest": { + "method": "POST", + "header": [], + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + } + }, + "code": 200, + "_postman_previewlanguage": "json", + "header": null, + "cookie": [], + "body": "{\n \"jsonrpc\": \"2.0\",\n \"result\": [\n {\n \"action\": {\n \"creationMethod\": \"create\",\n \"from\": \"0x627306090abab3a6e1400e9345bc60c78a8bef57\",\n \"gas\": \"0xff2e26\",\n \"init\": \"0x60006000600060006000732c2b9c9a4a25e24b174f26114e8926a9f2128fe45af2600060006000600060007300a00000000000000000000000000000000000005af2\",\n \"value\": \"0x0\"\n },\n \"blockHash\": \"0x7e9a993adc6f043c0a9b6a385e6ed3fa370586c55823251b8fa7033cf89d414e\",\n \"blockNumber\": 19,\n \"result\": {\n \"address\": \"0x30753e4a8aad7f8597332e813735def5dd395028\",\n \"code\": \"0x\",\n \"gasUsed\": \"0x1c39\"\n },\n \"subtraces\": 2,\n \"traceAddress\": [],\n \"transactionHash\": \"0x4c253746668dca6ac3f7b9bc18248b558a95b5fc881d140872c2dff984d344a7\",\n \"transactionPosition\": 3,\n \"type\": \"create\"\n },\n {\n \"action\": {\n \"callType\": \"callcode\",\n \"from\": \"0x30753e4a8aad7f8597332e813735def5dd395028\",\n \"gas\": \"0xfb2ea9\",\n \"input\": \"0x\",\n \"to\": \"0x2c2b9c9a4a25e24b174f26114e8926a9f2128fe4\",\n \"value\": \"0x0\"\n },\n \"blockHash\": \"0x7e9a993adc6f043c0a9b6a385e6ed3fa370586c55823251b8fa7033cf89d414e\",\n \"blockNumber\": 19,\n \"result\": {\n \"gasUsed\": \"0x138e\",\n \"output\": \"0x\"\n },\n \"subtraces\": 1,\n \"traceAddress\": [\n 0\n ],\n \"transactionHash\": \"0x4c253746668dca6ac3f7b9bc18248b558a95b5fc881d140872c2dff984d344a7\",\n \"transactionPosition\": 3,\n \"type\": \"call\"\n },\n {\n \"action\": {\n \"address\": \"0x30753e4a8aad7f8597332e813735def5dd395028\",\n \"balance\": \"0x0\",\n \"refundAddress\": \"0x0000000000000000000000000000000000000000\"\n },\n \"blockHash\": \"0x7e9a993adc6f043c0a9b6a385e6ed3fa370586c55823251b8fa7033cf89d414e\",\n \"blockNumber\": 19,\n \"result\": null,\n \"subtraces\": 0,\n \"traceAddress\": [\n 0,\n 0\n ],\n \"transactionHash\": \"0x4c253746668dca6ac3f7b9bc18248b558a95b5fc881d140872c2dff984d344a7\",\n \"transactionPosition\": 3,\n \"type\": \"suicide\"\n },\n {\n \"action\": {\n \"callType\": \"callcode\",\n \"from\": \"0x30753e4a8aad7f8597332e813735def5dd395028\",\n \"gas\": \"0xfb18a5\",\n \"input\": \"0x\",\n \"to\": \"0x00a0000000000000000000000000000000000000\",\n \"value\": \"0x0\"\n },\n \"blockHash\": \"0x7e9a993adc6f043c0a9b6a385e6ed3fa370586c55823251b8fa7033cf89d414e\",\n \"blockNumber\": 19,\n \"result\": {\n \"gasUsed\": \"0x30b\",\n \"output\": \"0x\"\n },\n \"subtraces\": 0,\n \"traceAddress\": [\n 1\n ],\n \"transactionHash\": \"0x4c253746668dca6ac3f7b9bc18248b558a95b5fc881d140872c2dff984d344a7\",\n \"transactionPosition\": 3,\n \"type\": \"call\"\n }\n ],\n \"id\": 1\n}" + } + ] + } + ], + "description": "> **Note**\n>\n> The `TRACE` API methods are not enabled by default for JSON-RPC. To enable the `TRACE` API methods, use the [`--rpc-http-api`](https://besu.hyperledger.org/en/stable/CLI/CLI-Syntax#rpc-http-api) or [`--rpc-ws-api`](https://besu.hyperledger.org/en/stable/CLI/CLI-Syntax#rpc-ws-api) options.\n\nThe TRACE API is a more concise alternative to the DEBUG API." + }, + { + "name": "TXPOOL", + "item": [ + { + "name": "txpool_besuPendingTransactions", + "request": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"txpool_besuPendingTransactions\",\n \"params\": [\n 2,\n {\n \"from\": {\n \"eq\": \"0xfe3b557e8fb62b89f4916b721be55ceb828dbd73\"\n },\n \"gas\": {\n \"lt\": \"0x5209\"\n },\n \"nonce\": {\n \"gt\": \"0x1\"\n }\n }\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + }, + "description": "Lists pending transactions that match the supplied filter conditions.\n\n#### Parameters\n\n* `QUANTITY` - Integer representing the maximum number of results to return.\n* Object of fields used to create the filter condition.\n\nEach field in the object corresponds to a field name containing an operator, and a value for the\noperator. A field name can only be specified once, and can only contain one operator.\nFor example, you cannot query transactions with a gas price between 8 and 9 Gwei by using both the\n`gt` and `lt` operator in the same field name instance.\n\nAll filters must be satisfied for a transaction to be returned.\n\n| Field name | Value | Value type | Supported operators |\n|--------------|-------------------------------------------|:---------------------:|---------------------|\n| **from** | Address of the sender. | *Data*, 20 bytes | `eq` |\n| **to** | Address of the receiver, or `\"contract_creation\"`.| *Data*, 20 bytes |`eq`, `action`|\n| **gas** | Gas provided by the sender. | *Quantity* | `eq`, `gt`, `lt` |\n| **gasPrice** | Gas price, in wei, provided by the sender.| *Quantity* | `eq`, `gt`, `lt` |\n| **value** | Value transferred, in wei. | *Quantity* | `eq`, `gt`, `lt` |\n| **nonce** | Number of transactions made by the sender.| *Quantity* | `eq`, `gt`, `lt` |\n|\n\nSupported operators:\n\n* `eq` (Equal to)\n* `lt` (Less than)\n* `gt` (Greater than)\n* `action`\n\n> **Note**\n>\n> The only supported `action` is `\"contract_creation\"`.\n\n#### Returns\n\n`result` - Array of objects with [details of the pending transaction](https://besu.hyperledger.org/en/stable/Reference/API-Objects#pending-transaction-object)." + }, + "response": [ + { + "name": "txpool_besuPendingTransactions", + "originalRequest": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"txpool_besuPendingTransactions\",\n \"params\": [\n 2,\n {\n \"from\": {\n \"eq\": \"0xfe3b557e8fb62b89f4916b721be55ceb828dbd73\"\n },\n \"gas\": {\n \"lt\": \"0x5209\"\n },\n \"nonce\": {\n \"gt\": \"0x1\"\n }\n }\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + } + }, + "code": 200, + "_postman_previewlanguage": "json", + "header": null, + "cookie": [], + "body": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"result\": [\n {\n \"from\": \"0xfe3b557e8fb62b89f4916b721be55ceb828dbd73\",\n \"gas\": \"0x5208\",\n \"gasPrice\": \"0xab5d04c00\",\n \"hash\": \"0xb7b2f4306c1c228ec94043da73b582594007091a7dfe024b1f8d6d772284e54b\",\n \"input\": \"0x\",\n \"nonce\": \"0x2\",\n \"to\": \"0xf8be4ebda7f62d79a665294ec1263bfdb59aabf2\",\n \"value\": \"0x0\",\n \"v\": \"0xfe8\",\n \"r\": \"0x5beb711e652c6cf0a589d3cea904eefc4f45ce4372652288701d08cc4412086d\",\n \"s\": \"0x3af14a56e63aa5fb7dcb444a89708363a9d2c1eba1f777c67690288415080ded\"\n }\n ]\n}" + } + ] + }, + { + "name": "txpool_besuStatistics", + "request": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"txpool_besuStatistics\",\n \"params\": [],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + }, + "description": "Lists statistics about the node transaction pool.\n\n#### Parameters\n\nNone\n\n#### Returns\n\n`result` - Transaction pool statistics:\n\n* `maxSize` - Maximum number of transactions kept in the transaction pool. Use the\n [`--tx-pool-max-size`](https://besu.hyperledger.org/en/stable/CLI/CLI-Syntax#tx-pool-max-size) option to configure the maximum size.\n* `localCount` - Number of transactions submitted directly to this node.\n* `remoteCount` - Number of transactions received from remote nodes." + }, + "response": [ + { + "name": "txpool_besuStatistics", + "originalRequest": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"txpool_besuStatistics\",\n \"params\": [],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + } + }, + "code": 200, + "_postman_previewlanguage": "json", + "header": null, + "cookie": [], + "body": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"result\": {\n \"maxSize\": 4096,\n \"localCount\": 1,\n \"remoteCount\": 0\n }\n}" + } + ] + }, + { + "name": "txpool_besuTransactions", + "request": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"txpool_besuTransactions\",\n \"params\": [],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + }, + "description": "Lists transactions in the node transaction pool.\n\n#### Parameters\n\nNone\n\n#### Returns\n\n`result` - List of transactions." + }, + "response": [ + { + "name": "txpool_besuTransactions", + "originalRequest": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"txpool_besuTransactions\",\n \"params\": [],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + } + }, + "code": 200, + "_postman_previewlanguage": "json", + "header": null, + "cookie": [], + "body": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"result\": [\n {\n \"hash\": \"0x8a66830098be4006a3f63a03b6e9b67aa721e04bd6b46d420b8f1937689fb4f1\",\n \"isReceivedFromLocalSource\": true,\n \"addedToPoolAt\": \"2019-03-21T01:35:50.911Z\"\n },\n {\n \"hash\": \"0x41ee803c3987ceb5bcea0fad7a76a8106a2a6dd654409007d9931032ea54579b\",\n \"isReceivedFromLocalSource\": true,\n \"addedToPoolAt\": \"2019-03-21T01:36:00.374Z\"\n }\n ]\n}" + } + ] + } + ], + "description": "> **Note**\n>\n> The `TXPOOL` API methods are not enabled by default for JSON-RPC. To enable the `TXPOOL` API methods, use the [`--rpc-http-api`](https://besu.hyperledger.org/en/stable/CLI/CLI-Syntax#rpc-http-api) or [`--rpc-ws-api`](https://besu.hyperledger.org/en/stable/CLI/CLI-Syntax#rpc-ws-api) options." + }, + { + "name": "WEB3", + "item": [ + { + "name": "web3_clientVersion", + "request": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"web3_clientVersion\",\n \"params\": [],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + }, + "description": "Returns the current client version.\n\n#### Parameters\n\nNone\n\n#### Returns\n\n`result` : *string* - Current client version." + }, + "response": [ + { + "name": "web3_clientVersion", + "originalRequest": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"web3_clientVersion\",\n \"params\": [],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + } + }, + "code": 200, + "_postman_previewlanguage": "json", + "header": null, + "cookie": [], + "body": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 53,\n \"result\": \"besu/\"\n}" + } + ] + }, + { + "name": "web3_sha3", + "request": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"web3_sha3\",\n \"params\": [\n \"0x68656c6c6f20776f726c00\"\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + }, + "description": "Returns a [SHA3](https://en.wikipedia.org/wiki/SHA-3) hash of the specified data. The result value\nis a [Keccak-256](https://keccak.team/keccak.html) hash, not the standardized SHA3-256.\n\n#### Parameters\n\n`DATA` - Data to convert to a SHA3 hash.\n\n#### Returns\n\n`result` (*DATA*) - SHA3 result of the input data." + }, + "response": [ + { + "name": "web3_sha3", + "originalRequest": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"jsonrpc\": \"2.0\",\n \"method\": \"web3_sha3\",\n \"params\": [\n \"0x68656c6c6f20776f726c00\"\n ],\n \"id\": 1\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "http://{{rpc-http-host}}:{{rpc-http-port}}", + "protocol": "http", + "host": ["{{rpc-http-host}}"], + "port": "{{rpc-http-port}}" + } + }, + "code": 200, + "_postman_previewlanguage": "json", + "header": null, + "cookie": [], + "body": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 53,\n \"result\": \"0x5e39a0a66544c0668bde22d61c47a8710000ece931f13b84d3b2feb44ec96d3f\"\n}" + } + ] + } + ] + } + ], + "event": [ + { + "listen": "prerequest", + "script": { + "type": "text/javascript", + "exec": [""] + } + }, + { + "listen": "test", + "script": { + "type": "text/javascript", + "exec": [""] + } + } + ] +} diff --git a/versioned_docs/version-23.10.1/global/postman.md b/versioned_docs/version-23.10.1/global/postman.md new file mode 100644 index 00000000000..a9afe58649b --- /dev/null +++ b/versioned_docs/version-23.10.1/global/postman.md @@ -0,0 +1,15 @@ +:::info Besu JSON-RPC APIs documentation in Postman format + +View the [Besu JSON-RPC APIs documentation](https://www.postman.com/hyperledger/workspace/hyperledger-besu/collection/11610746-f334929f-c8c3-43ed-bb73-69a6f0d728d8) in the Postman format and obtain example requests in multiple coding languages. + +#### Run in Postman + +Click the following button to fork the collection and run requests directly on your local network. + +[![Run in Postman](https://run.pstmn.io/button.svg)](https://god.gw.postman.com/run-collection/11610746-f334929f-c8c3-43ed-bb73-69a6f0d728d8?action=collection%2Ffork&collection-url=entityId%3D11610746-f334929f-c8c3-43ed-bb73-69a6f0d728d8%26entityType%3Dcollection%26workspaceId%3Dc4b60b6f-9f15-42d0-8327-7ebabca6f0fd#?env%5BBesu%20node%20on%20local%20host%5D=W3sia2V5IjoicnBjLWh0dHAtaG9zdCIsInZhbHVlIjoibG9jYWxob3N0IiwiZW5hYmxlZCI6ZmFsc2V9LHsia2V5IjoicnBjLWh0dHAtcG9ydCIsInZhbHVlIjoiODU0NSIsImVuYWJsZWQiOmZhbHNlfV0=). + +#### Download collection + +Alternatively you can [download the JSON collection file](../assets/postman/postman_collection.json). + +::: diff --git a/versioned_docs/version-23.10.1/global/test_accounts.md b/versioned_docs/version-23.10.1/global/test_accounts.md new file mode 100644 index 00000000000..ae819b23ed3 --- /dev/null +++ b/versioned_docs/version-23.10.1/global/test_accounts.md @@ -0,0 +1,51 @@ +:::danger **Do not use the test accounts on Ethereum Mainnet or any production network.** + +The following accounts are test accounts and their private keys are publicly visible in this documentation and in publicly available source code. + +They are not secure and everyone can use them. + +**Using test accounts on Ethereum Mainnet and production networks can lead to loss of funds and identity fraud.** + +In this documentation, we only provide test accounts for ease of testing and learning purposes; never use them for other purposes. + +**Always secure your Ethereum Mainnet and any production account properly.** + +See for instance [MyCrypto "Protecting Yourself and Your Funds" guide](https://support.mycrypto.com/staying-safe/protecting-yourself-and-your-funds). + +::: + +:::info "Test Account 1 (address `0xfe3b557e8fb62b89f4916b721be55ceb828dbd73`)" + +Private key to copy : + +```text +0x8f2a55949038a9610f50fb23b5883af3b4ecb3c3bb792cbcefbd1542c692be63 +``` + +Initial balance : 200 Eth _(200000000000000000000 Wei)_ + +::: + +:::info "Test Account 2 (address `0x627306090abaB3A6e1400e9345bC60c78a8BEf57`)" + +Private key to copy : + +```text +0xc87509a1c067bbde78beb793e6fa76530b6382a4c0241e5e4a9ec0a0f44dc0d3 +``` + +Initial balance : 90000 Eth _(90000000000000000000000 Wei)_ + +::: + +:::info "Test Account 3 (address `0xf17f52151EbEF6C7334FAD080c5704D77216b732`)" + +Private key to copy : + +```text +0xae6ae8e5ccbfb04590405997ee2d52d2b330726137b875053c36d94e974d162f +``` + +Initial balance : 90000 Eth _(90000000000000000000000 Wei)_ + +::: diff --git a/versioned_docs/version-23.10.1/private-networks/_category_.json b/versioned_docs/version-23.10.1/private-networks/_category_.json new file mode 100644 index 00000000000..865a111a8b4 --- /dev/null +++ b/versioned_docs/version-23.10.1/private-networks/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Private networks", + "position": 1 +} diff --git a/versioned_docs/version-23.10.1/private-networks/concepts/_category_.json b/versioned_docs/version-23.10.1/private-networks/concepts/_category_.json new file mode 100644 index 00000000000..d373a29254a --- /dev/null +++ b/versioned_docs/version-23.10.1/private-networks/concepts/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Concepts", + "position": 4 +} diff --git a/versioned_docs/version-23.10.1/private-networks/concepts/index.md b/versioned_docs/version-23.10.1/private-networks/concepts/index.md new file mode 100644 index 00000000000..efffe0e3a05 --- /dev/null +++ b/versioned_docs/version-23.10.1/private-networks/concepts/index.md @@ -0,0 +1,22 @@ +--- +title: Concepts +description: private networks concepts overview +sidebar_position: 3 +tags: + - private networks +--- + +# Concepts + +This section provides background information and context about private network features. + +The following features are shared with [public networks](../../public-networks/index.md) and the content can be found in the public networks section: + +- Transactions: + - [Transaction types](../../public-networks/concepts/transactions/types.md) + - [Transaction pool](../../public-networks/concepts/transactions/pool.md) + - [Transaction validation](../../public-networks/concepts/transactions/validation.md) +- [Network ID and chain ID](../../public-networks/concepts/network-and-chain-id.md) +- [Events and logs](../../public-networks/concepts/events-and-logs.md) +- [Genesis file](../../public-networks/concepts/genesis-file.md) +- [Node keys](../../public-networks/concepts/node-keys.md) diff --git a/versioned_docs/version-23.10.1/private-networks/concepts/permissioning/_category_.json b/versioned_docs/version-23.10.1/private-networks/concepts/permissioning/_category_.json new file mode 100644 index 00000000000..7299170da97 --- /dev/null +++ b/versioned_docs/version-23.10.1/private-networks/concepts/permissioning/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Permissioning", + "position": 3 +} diff --git a/versioned_docs/version-23.10.1/private-networks/concepts/permissioning/index.md b/versioned_docs/version-23.10.1/private-networks/concepts/permissioning/index.md new file mode 100644 index 00000000000..ad3678f68fd --- /dev/null +++ b/versioned_docs/version-23.10.1/private-networks/concepts/permissioning/index.md @@ -0,0 +1,65 @@ +--- +title: Permissioning +sidebar_position: 1 +description: Besu permissioning feature +tags: + - private networks +--- + +# Permissioning + +A permissioned network enables node permissioning and account permissioning, allowing only specified nodes and accounts to access the network. + +:::caution Permissioning is not privacy + +In peer-to-peer networks, node permissioning enforces rules on nodes you control. + +Permissioning requires a distributed network of trust across the network where participants agree to follow the rules. One bad actor can decide not to follow the rules. Nodes can take action to prevent the bad actor adding to the chain but they cannot prevent the bad actor from allowing access to the chain. + +Besu also implements [privacy](../privacy/index.md). + +::: + +## Node permissioning + +Use node permissioning to restrict access to known participants only. + +![Node Permissioning](../../../assets/images/node-permissioning-bad-actor.png) + +## Account permissioning + +Use account permissioning to: + +- Enforce onboarding or identity requirements. +- Suspend accounts. +- Restrict the actions an account can perform. + +![Account Permissioning](../../../assets/images/enterprise-ethereum-account-permissioning.png) + +## Specify permissioning + +You can specify permissioning [locally](#local) or [onchain](#onchain). + +### Local + +[Local permissioning](../../how-to/use-permissioning/local.md) works at the node level. Each node in the network has a [permissions configuration file]. + +Local permissioning affects your node but not the rest of the network. Use local permissioning to restrict use of your node (that is, the resources under your control). For example, customers able to access your node. + +Local permissioning does not require coordination with the rest of the network and you can act immediately to protect your node. Your rules are not enforced in blocks produced by other nodes. + +### Onchain + +[Onchain permissioning](onchain.md) works through a smart contract on the network. Specifying permissioning onchain enables all nodes to read and update permissioning configuration from one location. + +Onchain permissioning requires coordination to update the rules. The network might not be able to act immediately (for example, the smart contract might enforce a minimum of number of votes before changing permissioning rules). + +When you update onchain permissioning, the update applies across the network and new blocks abide by the updated rules. For example, blocked accounts can no longer add transactions to the chain. + +The following diagram illustrates applying local and onchain permissioning rules. + +![Permissioning Flow](../../../assets/images/PermissioningFlow.png) + + + +[permissions configuration file]: ../../how-to/use-permissioning/local.md#permissions-configuration-file diff --git a/versioned_docs/version-23.10.1/private-networks/concepts/permissioning/onchain.md b/versioned_docs/version-23.10.1/private-networks/concepts/permissioning/onchain.md new file mode 100644 index 00000000000..908a3418f9b --- /dev/null +++ b/versioned_docs/version-23.10.1/private-networks/concepts/permissioning/onchain.md @@ -0,0 +1,73 @@ +--- +title: Onchain permissioning +description: Onchain permissioning +sidebar_position: 1 +tags: + - private networks +--- + +# Onchain permissioning + +Onchain [permissioning](index.md) uses smart contracts to store and administer the node, account, and admin allowlists. Using onchain permissioning enables all nodes to read the allowlists from a single source, the blockchain. + +:::danger + +When using onchain account permissioning, a node checks permissions when importing blocks. Meaning, a node only imports blocks in which all transactions are from authorized senders. If you disable onchain account permissioning and your node accepts blocks without enforcing this rule, your node cannot re-synchronize with other nodes that enforce onchain account permissioning rules (your node goes into forked state). + +::: + +:::note + +Custom smart contracts and dapps can be implemented to work with onchain permissioning. + +::: + +## Permissioning contracts + +:::caution + +The permissioning contract has multiple interfaces, and each interface maps to a specific version of the [Enterprise Ethereum Alliance Client Specification](https://entethalliance.org/technical-specifications/). Ensure that you [specify the permissioning contract interface] being used when starting Besu. + +::: + +### Allowlists + +Permissioning implements three allowlists: + +- Accounts, which can submit transactions to the network. +- Nodes, which can join the network. +- Admins, which are accounts able to update the accounts and nodes allowlists. + +:::caution Using account permissioning and privacy + +Account permissioning is incompatible with [random key signing](../../how-to/use-privacy/sign-pmts.md) for [privacy marker transactions](../privacy/private-transactions/processing.md). + +If using account permissioning and privacy, a signing key must be specified using the [`--privacy-marker-transaction-signing-key-file`](../../reference/cli/options.md#privacy-marker-transaction-signing-key-file) command line option and the corresponding public key included in the accounts allowlist. + +::: + +:::tip + +If nodes are not connecting as expected, set the [log level to `TRACE`](../../../public-networks/reference/cli/options.md#logging) and search for messages containing `Node permissioning` to identify the issue. + +Ensure the [`--p2p-host`](../../../public-networks/reference/cli/options.md#p2p-host) command line option has been correctly configured for all nodes with the externally accessible address. + +If you change your network configuration, you may need to update the node allowlist. + +::: + +## Bootnodes + +When a node joins the network, the node connects to the [bootnodes](../../how-to/configure/bootnodes.md) until it synchronizes to the chain head, regardless of node permissions. After synchronization, the Account Rules and Node Rules smart contracts apply the permissioning rules. + +If a synchronized node loses all peer connections (that is, it has zero peers), it reconnects to the bootnodes to rediscover peers. + +:::info + +All bootnodes must be on the nodes allowlist. + +::: + + + +[specify the permissioning contract interface]: ../../how-to/use-permissioning/onchain.md#specify-the-permissioning-contract-interface-version diff --git a/versioned_docs/version-23.10.1/private-networks/concepts/permissioning/plugin.md b/versioned_docs/version-23.10.1/private-networks/concepts/permissioning/plugin.md new file mode 100644 index 00000000000..a4f62031d8b --- /dev/null +++ b/versioned_docs/version-23.10.1/private-networks/concepts/permissioning/plugin.md @@ -0,0 +1,53 @@ +--- +title: Permissioning plugin +description: Plugin based permissioning +sidebar_position: 2 +tags: + - private networks +--- + +# Permissioning plugin + +You can define complex [permissioning](index.md) solutions by building a plugin that extends Hyperledger Besu functionality. + +The plugin API provides a `PermissioningService` interface that currently supports connection permissioning and message permissioning. + +## Connection permissioning + +Use connection permissioning when deciding whether to restrict node access to known participants only. + +## Message permissioning + +Use message permissioning to propagate different types of devP2P messages to particular nodes. For example, this can be used to prevent pending transactions from being forwarded to other nodes. + +## Register your plugin + +To enable permissioning in your plugin, implement the `PermissioningService` interface and register your providers. + +```java +@AutoService(BesuPlugin.class) +public class TestPermissioningPlugin implements BesuPlugin { + PermissioningService service; + + @Override + public void register(final BesuContext context) { + service = context.getService(PermissioningService.class).get(); + } + + @Override + public void start() { + service.registerNodePermissioningProvider((sourceEnode, destinationEnode) -> { + // perform logic for node permissioning + return true; + }); + + service.registerNodeMessagePermissioningProvider((destinationEnode, code) -> { + // perform logic for message permissioning + return true; + }); + } + + @Override + public void stop() {} +} +``` diff --git a/versioned_docs/version-23.10.1/private-networks/concepts/pki.md b/versioned_docs/version-23.10.1/private-networks/concepts/pki.md new file mode 100644 index 00000000000..97cec02eab0 --- /dev/null +++ b/versioned_docs/version-23.10.1/private-networks/concepts/pki.md @@ -0,0 +1,45 @@ +--- +title: Public key infrastructure +sidebar_position: 5 +description: Public key infrastructure +tags: + - private networks +--- + +# Public key infrastructure + +:::warning + +Public key infrastructure (PKI) support is an early access feature, and functionality and options may be updated between releases. + +::: + +Hyperledger Besu's public key infrastructure allows you to use certificates issued by a trusted authority to manage node and account identities in the following ways: + +- Node permissioning - Only authorized nodes can connect to other nodes in the network using TLS for the P2P communication. +- Block proposal permissioning - Only blocks proposed by authorized validators are accepted. + +Supported keystore and truststore formats used to store the certificates include PKCS11, PKCS12, and JKS. + +## Node permissioning + +Allow TLS communication between nodes by using certificates issued by a trusted authority to connect to other authorized nodes in the network. + +When receiving connection requests, the incoming connection must be from another authorized node. Similarly, when connecting to a node the initiator ensures that the remote node is authorized to participate in the network. + +[Configure TLS for the P2P communication using the Besu command line options](../how-to/configure/tls/p2p.md). + +## Block proposal permissioning + +:::caution + +Only private networks using the [QBFT consensus protocol] support block proposal permissioning. + +::: + +Use certificates issued by a trusted authority to ensure only authorized validator nodes can propose new blocks in the network. The block hash is signed by the validator private certificate and included in the header of the proposed block as a [CMS (Cryptographic Message Syntax)]. This is used by other validators to verify that the proposer is authorized to create a block in the network. + +[Configure block proposal permissioning using the Besu command line options](../how-to/configure/block-proposal-permissioning.md). + +[QBFT consensus protocol]: ../how-to/configure/consensus/qbft.md +[CMS (Cryptographic Message Syntax)]: https://en.wikipedia.org/wiki/Cryptographic_Message_Syntax diff --git a/versioned_docs/version-23.10.1/private-networks/concepts/plugins.md b/versioned_docs/version-23.10.1/private-networks/concepts/plugins.md new file mode 100644 index 00000000000..70ee78f7ca4 --- /dev/null +++ b/versioned_docs/version-23.10.1/private-networks/concepts/plugins.md @@ -0,0 +1,55 @@ +--- +title: Plugins +sidebar_position: 6 +description: Plugins overview +tags: + - private networks +--- + +# Plugins + +You can extend Hyperledger Besu functionality by building Java plugins or using existing open source Besu plugins. Use the Plugin API to take data from any Besu network, public or permissioned, and feed it into an application or system. + +For example, create a plugin to add more monitoring functionality or stream event data to a third-party application. The API exposes data about the following components: + +- Blocks +- Balances +- Transactions +- Smart contracts +- Execution results +- Logs +- Syncing state. + +![Besu plugin API](../../assets/images/Hyperledger-Besu-Plugin-API.png) + +The plugin API provides access to [interfaces](../reference/plugin-api-interfaces.md) allowing you to build the plugin. + +:::info + +View the [plugin API webinar](https://youtu.be/78sa2WuA1rg) for an example of how to build a plugin. + +For more information about the available interfaces, see the [Plugin API Javadoc](https://javadoc.io/doc/org.hyperledger.besu/plugin-api/latest/index.html). + +::: + +## Install plugins + +To allow Besu to access and use the plugin, copy the plugin (`.jar`) to the `plugins` directory. + +:::caution + +If not already present, you must create the `plugins` directory one directory level below (`../`) the `besu` executable. + +::: + +Each plugin in the directory has the following lifecycle events: + +- **Register** - Executed when Besu starts. Besu checks plugin compatibility and registers plugins. +- **Start** - Plugins start after being successfully registered. +- **Stop** - Besu stops plugins. + +:::note + +The order in which Besu calls plugins during lifecycle events is not guaranteed. + +::: diff --git a/versioned_docs/version-23.10.1/private-networks/concepts/poa.md b/versioned_docs/version-23.10.1/private-networks/concepts/poa.md new file mode 100644 index 00000000000..40d07a75c53 --- /dev/null +++ b/versioned_docs/version-23.10.1/private-networks/concepts/poa.md @@ -0,0 +1,69 @@ +--- +title: Proof of authority consensus +sidebar_position: 1 +description: Besu proof of authority consensus protocols comparison +tags: + - private networks +--- + +# Proof of authority consensus + +Besu implements the QBFT, IBFT 2.0, and Clique proof of authority (PoA) [consensus protocols](../how-to/configure/consensus/index.md). PoA consensus protocols work when participants know each other and there is a level of trust between them. For example, in a permissioned consortium network. + +PoA consensus protocols have faster block times and a much greater transaction throughput than the Ethash proof of work consensus protocol used on the Ethereum Mainnet. + +In QBFT, IBFT 2.0, or Clique, a group of nodes in the network act as validators (QBFT and IBFT 2.0) or signers (Clique). The existing nodes in the signer/validator pool vote to add nodes to or remove nodes from the pool. + +:::note + +For the rest of this page, the term validator is used to refer to signers and validators. + +::: + +## Properties + +Properties to consider when comparing QBFT, IBFT 2.0, and Clique are: + +- Immediate finality. +- Minimum number of validators. +- Liveness. +- Speed. + +### Immediate finality + +QBFT and IBFT 2.0 have immediate finality; there are no forks and all valid blocks get included in the main chain. + +Clique does not have immediate finality. Implementations using Clique must be aware of forks and chain reorganizations occurring. + +### Minimum number of validators + +To be Byzantine fault tolerant, QBFT and IBFT 2.0 require a minimum of four validators. + +Clique can operate with a single validator but operating with a single validator offers no redundancy if the validator fails. + +:::tip + +Byzantine fault tolerant is the ability to function correctly and reach consensus despite nodes failing or propagating incorrect information to peers. + +::: + +### Liveness + +Clique is more fault tolerant than QBFT and IBFT 2.0. Clique tolerates up to half of the validators failing. QBFT and IBFT 2.0 networks require greater than or equal to two-thirds of validators to be operating to create blocks. For example, an QBFT and IBFT 2.0 network of: + +- Four to five validators tolerates one unresponsive validator. +- Six to eight validators tolerates two unresponsive validators. + +Networks with three or less validators can produce blocks but do not guarantee finality when operating in adversarial environments. + +:::caution + +We recommend using QBFT or IBFT 2.0 networks with at least four nodes in production environments. + +::: + +### Speed + +Reaching consensus and adding blocks is faster in Clique networks. For Clique, the probability of a fork increases as the number of validators increases. + +For QBFT and IBFT 2.0, the time to add new blocks increases as the number of validators increases. diff --git a/versioned_docs/version-23.10.1/private-networks/concepts/privacy/_category_.json b/versioned_docs/version-23.10.1/private-networks/concepts/privacy/_category_.json new file mode 100644 index 00000000000..e1382c18fd5 --- /dev/null +++ b/versioned_docs/version-23.10.1/private-networks/concepts/privacy/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Privacy", + "position": 2 +} diff --git a/versioned_docs/version-23.10.1/private-networks/concepts/privacy/flexible-privacy.md b/versioned_docs/version-23.10.1/private-networks/concepts/privacy/flexible-privacy.md new file mode 100644 index 00000000000..ea40eca8c52 --- /dev/null +++ b/versioned_docs/version-23.10.1/private-networks/concepts/privacy/flexible-privacy.md @@ -0,0 +1,81 @@ +--- +title: Flexible privacy groups +sidebar_position: 3 +description: Flexible privacy groups +--- + +# Flexible privacy groups + +Flexible [privacy groups](privacy-groups.md) use smart contracts to store and maintain the group membership. You can [add and remove members to and from flexible privacy groups](../../how-to/use-privacy/flexible.md). + +:::tip + +Because group membership for flexible privacy groups is stored in a smart contract, flexible privacy groups are also known as onchain privacy groups. + +::: + +:::danger + +Flexible privacy groups are an early access feature. Don't use in production networks. + +The flexible privacy group interfaces might change between releases. There might not be an upgrade path from flexible privacy groups created using v1.5 or earlier to enable use of flexible privacy group functionality in future versions. + +We don't recommended creating flexible privacy groups in a chain with existing [offchain privacy groups](privacy-groups.md). + +::: + +## Group management contracts + +The privacy group management contract bytecode is hard-coded into Besu and when you create a privacy group, the contract bytecode is part of the genesis state of the privacy group. + +:::caution + +All members of a flexible privacy group must be using the same version of Besu. If using different versions, the private state within the privacy group may become inconsistent. + +::: + +In the default implementation of the group management contract, the signer of the private transaction that creates the privacy group is also the owner of the group. Only the owner can add and remove participants, and upgrade the management contract. + +The owner is identified by the signing key. Transactions to add and remove participants, or upgrade the management contract, must be signed by the same key that signed the group creation transaction. + +## Flexible privacy group IDs + +When creating a flexible privacy group, generate the privacy group ID for the group outside of Besu and pass the ID as a parameter. + +The [web3js-quorum library](../../how-to/use-privacy/flexible.md) generates a unique privacy group ID and passes the ID to Besu when creating a privacy group. + +:::caution + +When generating a privacy group ID, you must ensure the ID is unique across all network participants. If you create a privacy group with an existing privacy group ID, the existing privacy group is overwritten. + +To ensure unique privacy group IDs, we recommend using 256-bit SecureRandom. + +::: + +## Multi-tenancy + +When using [multi-tenancy](multi-tenancy.md) with flexible privacy groups, each user provides a JSON Web Token (JWT) which allows Besu to check that the user has access to functionality and data associated with a privacy group. + +Using multi-tenancy with flexible privacy groups is more complex than with [offchain privacy groups](privacy-groups.md) because users may be added and removed from flexible privacy groups. When a user is added to a privacy group, they get access to all existing data in the privacy group. After being removed from a privacy group, a user retains access to already existing data in the privacy group, up to the block containing the [privacy marker transaction (PMT)](private-transactions/processing.md) that removed them (the removal block). A removed user doesn't have access to data in the privacy group that happens after they were removed. + +In particular, when multi-tenancy is enabled and a user requests access to a privacy group they were once a member of but later removed from, Besu allows the user access to the following functionality and data associated with the privacy group: + +- Private transactions using `priv_getTransaction` and private transaction receipts using [`priv_getTransactionReceipt`](../../../public-networks/reference/api/index.md#priv_gettransactionreceipt) from blocks up to (and including) the removal block. + + :::note + + A removed group member may have access to some private transactions after the removal PMT in the same block. + + ::: + +- Using [`priv_call`](../../../public-networks/reference/api/index.md#priv_call) on blocks up to (and including) the removal block. + +- Private logs using [`priv_getLogs`](../../../public-networks/reference/api/index.md#priv_getlogs) for blocks up to (and including) the removal block. When the `toBlock` is greater than the removal block, `priv_getLogs` still returns logs up to the removal block. + + :::note + + When a user is removed from a privacy group, any log filters they've created are also removed and can't be accessed. A user can only create and access filters for a privacy group they are currently a member of. + + ::: + +All other [`PRIV` API methods](../../../public-networks/reference/api/index.md#priv-methods) fail for the removed group member. diff --git a/versioned_docs/version-23.10.1/private-networks/concepts/privacy/index.md b/versioned_docs/version-23.10.1/private-networks/concepts/privacy/index.md new file mode 100644 index 00000000000..0888bbe40e3 --- /dev/null +++ b/versioned_docs/version-23.10.1/private-networks/concepts/privacy/index.md @@ -0,0 +1,71 @@ +--- +title: Privacy +sidebar_position: 1 +description: Privacy +--- + +# Privacy + +In Besu, privacy refers to the ability to keep transactions private between the involved participants. Other participants cannot access the transaction content or list of participants. + +:::danger + +For production environments requiring private transactions: + +- We recommend using a network with a consensus mechanism supporting transaction finality. For example, [IBFT 2.0](../../how-to/configure/consensus/ibft.md). +- Tessera must be [highly available and run in a separate instance to Besu]. + +Using private transactions with [pruning] or [fast sync](../../../public-networks/reference/cli/options.md#sync-mode) isn't supported. + +::: + +## Private transaction manager + +Besu uses a private transaction manager, [Tessera](https://docs.tessera.consensys.net/), to implement privacy. Each Besu node that sends or receives [private transactions](private-transactions/index.md) requires an associated Tessera node. + +

+ +![Tessera Nodes](../../../assets/images/TesseraNodes.png) + +

+ +Private transactions pass from the Besu node to the associated Tessera node. The Tessera node encrypts and directly distributes (that is, point-to-point) the private transaction to the Tessera nodes participating in the transaction. + +By default, each participant in a privacy-enabled network uses its own Besu and Tessera node. [Multi-tenancy](multi-tenancy.md) allows more than one participant to use the same Besu and Tessera node. + +:::tip + +Private Transaction Managers are also known as Enclaves. + +::: + +## Privacy-enabled networks + +When enabling privacy in a [private network](../../get-started/system-requirements.md), there's an assumed level of trust among the node operators, since all are members of the private network. + +:::caution + +Inefficient contracts deployed accidentally or deliberately can cause performance issues in privacy-enabled networks because gas isn't required in private transactions. + +::: + +In contrast, gas is required in Ethereum Mainnet and public testnets because they are trustless environments. + +Privacy-enabled networks should have a mechanism to establish trust offchain. Node operators should be informed on: + +- Guidelines for use, responsibilities, and good behavior. +- Smart contract security, so contracts deployed on the network use resources efficiently. +- Consequences for malicious activity. + +Privacy-enabled networks should run development and test environments that closely resemble production, so contracts can be tested, and potential issues can be found before they're deployed in production. + +## Reorg-compatible privacy + +In v1.4, using private transactions in a network using a consensus mechanism where forks occur (that is, PoW algorithms or Clique) is an early access feature. + +Do not use private transactions in production environments using consensus mechanisms where forks occur. + + + +[highly available and run in a separate instance to Besu]: ../../how-to/use-privacy/tessera.md +[pruning]: ../../../public-networks/concepts/data-storage-formats.md#pruning diff --git a/versioned_docs/version-23.10.1/private-networks/concepts/privacy/multi-tenancy.md b/versioned_docs/version-23.10.1/private-networks/concepts/privacy/multi-tenancy.md new file mode 100644 index 00000000000..d04b9606eb8 --- /dev/null +++ b/versioned_docs/version-23.10.1/private-networks/concepts/privacy/multi-tenancy.md @@ -0,0 +1,33 @@ +--- +title: Multi-tenancy +sidebar_position: 4 +description: Multi-tenancy +--- + +# Multi-tenancy + +By default, each participant in a privacy network uses its own Besu and Tessera node. + +Multi-tenancy allows multiple participants to use the same Besu and Tessera node. Each participant is a _tenant_, and the operator is the _owner_ of the Besu and Tessera node. + +:::info + +The operator is responsible for [configuring multi-tenancy](../../tutorials/privacy/multi-tenancy.md), and has access to all tenant data. + +::: + +![Multi-tenancy](../../../assets/images/Multi-tenancy.png) + +:::tip + +Ensure the multi-tenant Tessera node client API is configured to allow access only by the multi-tenant Besu node. Access to your data is secured through Besu using multi-tenancy mode. + +If not configured to allow access only by the multi-tenant Besu node, other Tessera clients, including other Besu nodes, might be able to access tenant data. + +To secure access, you can [configure TLS between Besu and Tessera](../../how-to/configure/tls/client-and-server.md) with the [`WHITELIST`](https://docs.tessera.consensys.net/en/stable/HowTo/Configure/TLS/#whitelist) trust mode. + +::: + +Multi-tenancy validates that tenants have permission to use the specified HTTP or WebSocket JSON-RPC requests, and the tenant has access to the requested privacy data. Private data is isolated and each tenant uses a JSON Web Token (JWT) for authentication. + +You can [create the JWT either externally or internally](../../../public-networks/how-to/use-besu-api/authenticate.md). diff --git a/versioned_docs/version-23.10.1/private-networks/concepts/privacy/plugin.md b/versioned_docs/version-23.10.1/private-networks/concepts/privacy/plugin.md new file mode 100644 index 00000000000..fbc34fb440f --- /dev/null +++ b/versioned_docs/version-23.10.1/private-networks/concepts/privacy/plugin.md @@ -0,0 +1,111 @@ +--- +title: Privacy plugin +description: Privacy plugin +sidebar_position: 5 +--- + +# Privacy plugin + +You can define your own strategy for private transactions by building a plugin that extends Hyperledger Besu functionality. + +The plugin can take many forms, but it must provide Besu with a private transaction when required. + +:::danger + +The privacy plugin is an early access feature and plugin interfaces are subject to change between releases. + +::: + +## Configuration + +Enable the privacy plugin by starting Besu and including the `--Xprivacy-plugin-enabled` command line option. The registered plugin must implement the `PrivacyPluginPayloadProvider` interface. + +## Use the payload provider interface + +The privacy plugin must define the [privacy marker transaction (PMT)] payload. Use the payload to retrieve the contents of the private transaction which could be a link to a location in an enclave, or an encrypted form of the private payload itself. + +Besu doesn't need to know how the private transaction is distributed, it just needs to know what the private transaction for the PMT is. + +### Send transactions + +When submitting a private transaction using [`eea_sendRawTransaction`](../../../public-networks/reference/api/index.md#eea_sendrawtransaction), the signed transaction must be sent to `0x000000000000000000000000000000000000007a` to indicate which [privacy precompiled contract](private-transactions/processing.md) is being used. + +The transaction flow is as follows: + +1. The JSON-RPC endpoint passes the private transaction to the private transaction manager (for example Tessera). +2. The private transaction manager sends the private transaction to the privacy plugin. +3. The plugin decides what data to store onchain in the payload, for example the encrypted and serialized private transaction. +4. The plugin returns what needs to be stored in the payload for the PMT. +5. The private transaction handler creates a PMT for the private transaction, and propagates the PMT using devP2P in the same way as a public Ethereum transaction. + +### Mine transactions + +The process of mining transactions happens in reverse to sending transactions. + +1. The Mainnet transaction processor processes the PMT in the same way as any other public transaction. On nodes containing the [privacy precompile contract](../../../public-networks/reference/api/index.md#priv_getprivacyprecompileaddress) specified in the `to` attribute of the PMT, the Mainnet transaction processor passes the PMT to the privacy precompile contract. + + :::note + + Nodes receiving the PMT that do not contain the specified privacy precompile contract will ignore the PMT. + + ::: + +1. The privacy precompile contract queries the plugin for the private transaction using the PMT. +1. The privacy precompile contract passes the private transaction to the private transaction manager. The privacy group ID specifies the private world state to use. +1. The private transaction manager executes the transaction. The private transaction manager can read and write to the private world state, and read from the public world state. + +## Transaction factory + +An additional extension is available to help you define how PMTs are signed. Currently, Besu supports fixed or random key signing for PMTs. + +The extension allows you to use a more dynamic approach, for example different keys for different groups. + +Your plugin needs to register the `PrivateMarkerTransactionFactory` interface which is called before submitting a PMT to the transaction pool. The responsibility then lies with the plugin to sign and serialize the PMT. + +[privacy marker transaction (PMT)]: ../../how-to/use-privacy/access-private-transactions.md + +## Register your plugin + +To enable Besu to use your privacy plugin, you must implement the `PrivacyPluginService` interface and you must call `setPayloadProvider`. + +```java + +@AutoService(BesuPlugin.class) +public class TestPrivacyPlugin implements BesuPlugin { + + private PrivacyPluginService service; + + @Override + public void register(BesuContext context) { + service = context.getService(PrivacyPluginService.class).get(); + } + + @Override + public void start() { + service.setPayloadProvider(new PrivacyPluginPayloadProvider() { + @Override + public Bytes generateMarkerPayload(PrivateTransaction privateTransaction, String privacyUserId) { + // perform logic to serialize the payload of the marker transaction + // in this example we are serialising the private transaction using rlp https://ethereum.org/en/developers/docs/data-structures-and-encoding/rlp/ + return org.hyperledger.besu.ethereum.privacy.PrivateTransaction.serialize(privateTransaction).encoded(); + } + + @Override + public Optional getPrivateTransactionFromPayload(Transaction transaction) { + // perform logic to deserialize payload from the marker transaction + + final BytesValueRLPInput bytesValueRLPInput = + new BytesValueRLPInput(transaction.getPayload(), false); + + return Optional.of(org.hyperledger.besu.ethereum.privacy.PrivateTransaction.readFrom(bytesValueRLPInput)); + } + }); + } + + @Override + public void stop() { + + } +} + +``` diff --git a/versioned_docs/version-23.10.1/private-networks/concepts/privacy/privacy-groups.md b/versioned_docs/version-23.10.1/private-networks/concepts/privacy/privacy-groups.md new file mode 100644 index 00000000000..8521efe7810 --- /dev/null +++ b/versioned_docs/version-23.10.1/private-networks/concepts/privacy/privacy-groups.md @@ -0,0 +1,77 @@ +--- +title: Privacy groups +sidebar_position: 2 +description: Privacy groups +--- + +# Privacy groups + +A privacy group is a group of nodes identified by a unique privacy group ID by Tessera. Tessera stores each private transaction with the privacy group ID. + +The Besu nodes maintain the public world state for the blockchain and a private state for each privacy group. The private states contain data that is not shared in the globally replicated world state. + +:::caution + +The privacy group implementations described below are offchain privacy groups and cannot have their group membership updated. + +[Flexible privacy groups are an early access feature](flexible-privacy.md). + +::: + +## Privacy types + +Besu implements two types of privacy: + +- Enterprise Ethereum Alliance (EEA) privacy, where private transactions include `privateFor` as the recipient. +- Besu-extended privacy, where private transactions include `privacyGroupId` as the recipient. + +Both privacy types create privacy groups and store private transactions with their privacy group in Tessera. + +

+ +![Privacy Groups](../../../assets/images/PrivacyGroups.png) + +

+ +:::note + +For clarity, the Tessera nodes are not shown in the previous diagram. To send private transactions, each Besu node must have an associated Tessera node. + +::: + +### Access between states + +A contract in a privacy group: + +- Can read or write to a contract in the same privacy group. +- Can read from the public state including public contracts. +- Cannot access contracts from a different privacy group. + +A public contract cannot access a private contract. + +### Enterprise Ethereum Alliance privacy + +In the privacy implementation complying with the [EEA Client Specification](https://entethalliance.org/technical-documents/) the group of nodes specified by `privateFrom` and `privateFor` form a privacy group with a unique privacy group ID provided by Tessera. + +The previous diagram illustrates two privacy groups enabling: + +- A, B, and C to send transactions that are private from D. +- A, C, and D to send transactions that are private from B. + +Using EEA-compliant privacy, to send private transactions between A, B, and C, A initializes a contract in a private transaction with B and C specified as the `privateFor` and A specified as the `privateFrom`. Initializing the contract creates a privacy group consisting of A, B, and C. For the ABC private state to remain consistent, A, B, and C must be included on transactions (as either `privateFrom` or `privateFor`) even if they are between only two of the three parties. + +To send private transactions between A, C, and D, C initializes a different contract in a private transaction with A and D specified as the `privateFor` and C specified as the `privateFrom`. Initializing the contract creates a privacy group consisting of A, C, and D. For the ACD private state to remain consistent, A, C, and D must be included on transactions (as either `privateFrom` or `privateFor`) even if they are between only two of the three parties. + +### Besu-extended privacy + +The Besu-extended privacy implementation creates a privacy group using [`priv_createPrivacyGroup`](../../../public-networks/reference/api/index.md#priv_createprivacygroup) with private transactions sent to the privacy group ID. + +Using the same privacy groups as in the previous example. + +Using Besu-extended privacy, to send private transactions between A, B, and C, A creates a privacy group consisting of A, B, and C. The privacy group ID is specified when sending private transactions and A, B, and C are recipients of all private transactions sent to the privacy group. + +To send private transactions between A, C, and D, A creates a privacy group consisting of A, C, and D. The privacy group ID of this group is specified when sending private transactions with A, C, and D as recipients. + +## Multi-tenancy + +When using [multi-tenancy](multi-tenancy.md) with privacy groups, each user provides a JSON Web Token (JWT) which allows Besu to check that the user has access to functionality and data associated with a privacy group. diff --git a/versioned_docs/version-23.10.1/private-networks/concepts/privacy/private-transactions/_category_.json b/versioned_docs/version-23.10.1/private-networks/concepts/privacy/private-transactions/_category_.json new file mode 100644 index 00000000000..465b0be5572 --- /dev/null +++ b/versioned_docs/version-23.10.1/private-networks/concepts/privacy/private-transactions/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Private transactions", + "position": 1 +} diff --git a/versioned_docs/version-23.10.1/private-networks/concepts/privacy/private-transactions/index.md b/versioned_docs/version-23.10.1/private-networks/concepts/privacy/private-transactions/index.md new file mode 100644 index 00000000000..c149089080d --- /dev/null +++ b/versioned_docs/version-23.10.1/private-networks/concepts/privacy/private-transactions/index.md @@ -0,0 +1,98 @@ +--- +description: Private transaction overview +--- + +# Private transactions + +Private transactions have the same parameters as public Ethereum transactions, with the following additions: + +- `privateFrom` - The Tessera public key of the transaction sender. +- One of the following: + - `privateFor` - The Tessera public keys of the transaction recipients. + - `privacyGroupId` - [The privacy group to receive the transaction](../privacy-groups.md). +- `restriction` - Whether the private transaction is `restricted` or `unrestricted`: + + - `restricted` - Only the nodes participating in the transaction receive and store the payload of the private transaction. + - `unrestricted` - All nodes in the network receive the payload of the private transaction, but only the nodes participating in the transaction can read the transaction. + + :::info + + Besu implements `restricted` private transactions only. + + ::: + +The `gas` and `gasPrice` are used by the [privacy marker transaction (PMT)](processing.md), not the private transaction itself. + +:::info + +Because gas isn't required in private transactions, inefficient contracts deployed accidentally or deliberately can cause performance issues in privacy-enabled networks. Ensure your network has a mechanism to [establish trust offchain](../index.md#privacy-enabled-networks). + +::: + +You can [create and send private transactions](../../../how-to/send-transactions/private-transactions.md). + +## Besu and Tessera keys + +Besu and Tessera nodes both have public/private key pairs identifying them. A Besu node sending a private transaction to a Tessera node signs the transaction with the Besu node private key. The `privateFrom` and `privateFor` parameters specified in the RLP-encoded transaction string for [`eea_sendRawTransaction`](../../../reference/api/index.md#eea_sendrawtransaction) are the public keys of the Tessera nodes sending and receiving the transaction. + +:::info + +The mapping of Besu node addresses to Tessera node public keys is offchain. That is, the sender of a private transaction must know the Tessera node public key of the recipient. + +::: + +## Nonces + +A nonce is the number of previous transactions made by the sender. + +[Private transaction processing](processing.md) involves two transactions: the private transaction distributed to involved participants, and the privacy marker transaction (PMT) included on the public blockchain. Each of these transactions has its own nonce. Since the PMT is a public transaction, the PMT nonce is the public nonce for the account. + +### Private transaction nonce + +Besu maintains separate private states for each [privacy group](../privacy-groups.md). The private transaction nonce for an account is specific to the privacy group. That is, the nonce for account A for privacy group ABC is different to the nonce for account A for privacy group AB. + +### Private nonce validation + +Unlike public transactions, private transactions are not submitted to the [transaction pool](../../../../public-networks/concepts/transactions/pool.md). The private transaction is distributed directly to the participants in the transaction, and the PMT is submitted to the transaction pool. + +Unlike [public transaction nonces](../../../../public-networks/concepts/transactions/validation.md), private transaction nonces aren't validated when the private transaction is submitted. If a private transaction has an incorrect nonce, the PMT is still valid and is added to a block. However, in this scenario, the private transaction execution fails when [processing the PMT](processing.md) for the private transaction with the incorrect nonce. + +The following private transaction flow illustrates when nonce validation occurs: + +1. Submit a private transaction with a [nonce value](#private-transaction-nonce). +1. The private transaction is distributed to all participants in the privacy group. +1. The PMT is created and submitted to the transaction pool with a nonce of `0` if using one-time accounts. If using a specific account with [`--privacy-marker-transaction-signing-key-file`](../../../reference/cli/options.md#privacy-marker-transaction-signing-key-file), the public nonce for that account is obtained and used for the PMT. +1. The PMT is mined and included in the block. +1. After the block containing the PMT is imported, and the PMT is processed, the private transaction is retrieved from the private transaction manager and executed. + + If the private transaction was submitted with a correct nonce in step 1, the nonce is validated as correct. If an incorrect nonce was submitted, the private transaction execution fails. + +### Private nonce management + +In Besu, you call [`eth_getTransactionCount`](../../../../public-networks/reference/api/index.md#eth_gettransactioncount) to get a nonce, then use that nonce with [`eea_sendRawTransaction`](../../../reference/api/index.md#eea_sendrawtransaction) to send a private transaction. + +However, when you send multiple transactions in row, if a subsequent call to `getTransactionCount` happens before a previous transaction is processed, you can get the same nonce again. + +You can manage private nonces in multiple ways: + +- Let Besu handle it. You just need to wait long enough between calls to `sendRawTransaction` for the transactions to process. The current window is around 1.5 seconds, depending on block time. + + Public transactions deal with this issue, but the window is shorter, since you can use the transaction pool to take into account pending transactions (by using `eth_getTransactionCount("pending")`). + + For private transactions, the window is longer because private transactions aren't submitted to the transaction pool. You must wait until the private transaction's corresponding PMT is included in a block. + +- Manage the nonce yourself, by keeping track of and providing the nonce at each call. We recommend this if you're [sending many transactions that are independent of each other](../../../how-to/send-transactions/concurrent-private-transactions.md). + + :::note + + You can use [`priv_getTransactionCount`](../../../reference/api/index.md#priv_gettransactioncount) or [`priv_getEeaTransactionCount`](../../../reference/api/index.md#priv_geteeatransactioncount) to get the nonce for an account for the specified privacy group or participants. + + ::: + +- Use [Orchestrate](https://docs.orchestrate.consensys.net/en/stable/) for nonce management. We recommend this for enterprise use. + +:::tip + +The [web3js-quorum library includes an example](https://github.com/ConsenSys/web3js-quorum/blob/9a0f9eb1b91a4a0d93801f77782b509ae2e7314c/example/concurrentPrivateTransactions/concurrentPrivateTransactions.js) of nonce management when [sending concurrent private transactions](../../../how-to/send-transactions/concurrent-private-transactions.md). The example calculates the correct nonces for the private transactions and PMTs outside of Besu. + +::: diff --git a/versioned_docs/version-23.10.1/private-networks/concepts/privacy/private-transactions/processing.md b/versioned_docs/version-23.10.1/private-networks/concepts/privacy/private-transactions/processing.md new file mode 100644 index 00000000000..196f2b9e7e0 --- /dev/null +++ b/versioned_docs/version-23.10.1/private-networks/concepts/privacy/private-transactions/processing.md @@ -0,0 +1,72 @@ +--- +title: Private transaction processing +sidebar_position: 1 +description: Private transaction processing +--- + +# Private transaction processing + +Processing [private transactions](index.md) involves the following: + +- **Precompiled contract**: A smart contract compiled from the source language to EVM bytecode and stored by an Ethereum node for later execution. + +- **Privacy marker transaction (PMT)**: A public Ethereum transaction with a payload of the enclave key. The enclave key is a pointer to the private transaction in Tessera. The `to` attribute of the PMT is the [address of the privacy precompiled contract](../../../reference/api/index.md#priv_getprivacyprecompileaddress). + + The PMT is [signed with a random key or the key specified on the command line]. + +Private transaction processing is illustrated and described in the following diagram. + +![Processing Private Transactions](../../../../assets/images/PrivateTransactionProcessing.png) + +1. Submit a private transaction using [`eea_sendRawTransaction`](../../../reference/api/index.md#eea_sendrawtransaction). The signed transaction includes transaction parameters specific to private transactions, including: + + - `privateFor` or `privacyGroupId`, which specifies the list of recipients. + - `privateFrom`, which specifies the sender. + - `restriction`, which specifies the transaction is restricted to the transaction participants. + +1. The JSON-RPC endpoint passes the private transaction to the Private Transaction Handler. + +1. The Private Transaction Handler sends the private transaction to Tessera. + +1. Tessera distributes the private transaction directly (that is, point-to-point) to the Tessera nodes specified in `privateFor` or belonging to the privacy group identified by `privacyGroupId`. All recipient Tessera nodes store the transaction. Tessera associates the stored transaction with the transaction hash and privacy group ID. + +1. Tessera returns the transaction hash to the Private Transaction Handler. + +1. The Private Transaction Handler creates a PMT for the private transaction. The Private Transaction Handler propagates the PMT using devP2P in the same way as any other public Ethereum transaction. + + :::tip + + If you want to sign the PMT outside of Besu, use [`priv_distributeRawTransaction`](../../../how-to/send-transactions/private-transactions.md#priv_distributerawtransaction) instead of [`eea_sendRawTransaction`](../../../reference/api/index.md#eea_sendrawtransaction). + + ::: + +1. Besu mines the PMT into a block and the PMT is distributed to all Ethereum nodes in the network. + +1. The Mainnet Transaction Processor processes the PMT in the same way as any other public transaction. On nodes containing the [privacy precompile contract](../../../reference/api/index.md#priv_getprivacyprecompileaddress) specified in the `to` attribute of the PMT, the Mainnet Transaction Processor passes the PMT to the privacy precompile contract. + + :::note + + Nodes receiving the PMT that don't contain the privacy precompile contract ignore the PMT. + + ::: + +1. The privacy precompile contract queries Tessera for the private transaction and privacy group ID using the transaction hash. + +1. The privacy precompile contract passes the private transaction to the Private Transaction Processor. The privacy group ID specifies the private world state to use. + +1. The Private Transaction Processor executes the transaction. The Private Transaction Processor can read and write to the private world state, and read from the public world state. + +:::danger Recommendations + +- We recommend using a network with a consensus mechanism supporting transaction finality. For example, [IBFT 2.0](../../../how-to/configure/consensus/ibft.md). +- Tessera must be [highly available and run in a separate instance to Besu](../../../how-to/use-privacy/tessera.md). + +Using private transactions with [pruning] or [fast sync](../../../../public-networks/reference/cli/options.md#sync-mode) is not supported. + +::: + + + +[signed with a random key or the key specified on the command line]: ../../../how-to/use-privacy/sign-pmts.md +[highly available and run in a separate instance to Besu]: ../../../how-to/use-privacy/tessera.md +[pruning]: ../../../../public-networks/concepts/data-storage-formats.md#pruning diff --git a/versioned_docs/version-23.10.1/private-networks/get-started/_category_.json b/versioned_docs/version-23.10.1/private-networks/get-started/_category_.json new file mode 100644 index 00000000000..3b3ed44eda6 --- /dev/null +++ b/versioned_docs/version-23.10.1/private-networks/get-started/_category_.json @@ -0,0 +1,9 @@ +{ + "label": "Get started", + "position": 2, + "collapsed": false, + "link": { + "type": "generated-index", + "slug": "/private-networks/get-started" + } +} diff --git a/versioned_docs/version-23.10.1/private-networks/get-started/install/_category_.json b/versioned_docs/version-23.10.1/private-networks/get-started/install/_category_.json new file mode 100644 index 00000000000..043580c1474 --- /dev/null +++ b/versioned_docs/version-23.10.1/private-networks/get-started/install/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Install Besu", + "position": 2 +} diff --git a/versioned_docs/version-23.10.1/private-networks/get-started/install/binary-distribution.md b/versioned_docs/version-23.10.1/private-networks/get-started/install/binary-distribution.md new file mode 100644 index 00000000000..74dcba7e6f4 --- /dev/null +++ b/versioned_docs/version-23.10.1/private-networks/get-started/install/binary-distribution.md @@ -0,0 +1,94 @@ +--- +title: Install binary distribution +description: Install or upgrade Hyperledger Besu from binary distribution +sidebar_position: 3 +tags: + - private networks +--- + +# Install binary distribution + +## MacOS with Homebrew + +### Prerequisites + +- [Homebrew](https://brew.sh/) +- Java JDK + +:::caution + +Hyperledger Besu supports: + +- MacOS High Sierra 10.13 or later versions. +- Java 17+. You can install Java using `brew install openjdk`. Alternatively, you can manually install the [Java JDK](https://www.oracle.com/java/technologies/downloads). + +::: + +### Install (or upgrade) using Homebrew + +To install Besu using Homebrew: + +```bash +brew tap hyperledger/besu +brew install hyperledger/besu/besu +``` + +To upgrade an existing Besu installation using Homebrew: + +```bash +brew upgrade hyperledger/besu/besu +``` + +:::note + +If you've upgraded your MacOS version between installing and upgrading Besu, when running `brew upgrade hyperledger/besu/besu` you may be prompted to reinstall command line tools with `xcode-select --install`. + +::: + +:::note + +When upgrading Besu, you might be prompted to fix the remote branch names in Homebrew by using the command `brew tap --repair`. + +::: + +To display the Besu version and confirm installation: + +```bash +besu --version +``` + +To display Besu command line help: + +```bash +besu --help +``` + +## Linux / Unix + +### Prerequisites + +- [Java JDK 17+](https://www.oracle.com/java/technologies/downloads/) + +:::note Linux open file limit + +If synchronizing to Mainnet on Linux or other chains with large data requirements, increase the maximum number of open files allowed using `ulimit`. If the open files limit is not high enough, a `Too many open files` RocksDB exception occurs. + +::: + +:::tip + +We recommend installing [jemalloc](https://jemalloc.net/) to reduce memory usage. If using Ubuntu, you can install it with the command: `apt install libjemalloc-dev`. + +::: + +### Install from packaged binaries + +Download the Besu [packaged binaries](https://github.com/hyperledger/besu/releases). + +Unpack the downloaded files and change into the `besu-` directory. + +Display Besu command line help to confirm installation: + +```bash +bin/besu --help +``` diff --git a/versioned_docs/version-23.10.1/private-networks/get-started/install/index.md b/versioned_docs/version-23.10.1/private-networks/get-started/install/index.md new file mode 100644 index 00000000000..5c6fb933f52 --- /dev/null +++ b/versioned_docs/version-23.10.1/private-networks/get-started/install/index.md @@ -0,0 +1,28 @@ +--- +title: Installation options +description: Options for getting started with Hyperledger Besu +sidebar_position: 1 +tags: + - private networks +--- + +# Installation options + +Get started with the [Developer Quickstart](../../../private-networks/tutorials/quickstart.md). Use the quickstart to rapidly generate local blockchain networks. + +You can also install the following: + +- [Docker image](run-docker-image.md) +- [Binaries](binary-distribution.md) + +## Build from source + +If you want to use the latest development version of Hyperledger Besu or a specific commit, build from source. Otherwise, use the [binary] or [Docker image] for more stable versions. + +View the [Hyperledger Wiki] for instructions to install Hyperledger Besu from source. + + + +[Hyperledger Wiki]: https://wiki.hyperledger.org/display/BESU/Building+from+source +[binary]: binary-distribution.md +[Docker image]: run-docker-image.md diff --git a/versioned_docs/version-23.10.1/private-networks/get-started/install/run-docker-image.md b/versioned_docs/version-23.10.1/private-networks/get-started/install/run-docker-image.md new file mode 100644 index 00000000000..bc84eefbb97 --- /dev/null +++ b/versioned_docs/version-23.10.1/private-networks/get-started/install/run-docker-image.md @@ -0,0 +1,109 @@ +--- +title: Run Besu from Docker image +description: Run Hyperledger Besu using the official docker image +sidebar_position: 2 +tags: + - private networks +--- + +# Run Besu from a Docker image + +Hyperledger Besu provides a Docker image to run a Besu node in a Docker container. + +Use this Docker image to run a single Besu node without installing Besu. + +## Prerequisites + +- [Docker](https://docs.docker.com/install/) + +- MacOS or Linux + + :::caution + + The Docker image does not run on Windows. + + ::: + +## Expose ports + +Expose ports for P2P discovery, GraphQL, metrics, and HTTP and WebSocket JSON-RPC. You need to expose the ports to use the default ports or the ports specified using [`--rpc-http-port`](../../../public-networks/reference/cli/options.md#rpc-http-port), [`--p2p-port`](../../../public-networks/reference/cli/options.md#p2p-port), [`--rpc-ws-port`](../../../public-networks/reference/cli/options.md#rpc-ws-port), [`--metrics-port`](../../../public-networks/reference/cli/options.md#metrics-port), [`--graphql-http-port`](../../../public-networks/reference/cli/options.md#graphql-http-port), and [`--metrics-push-port`](../../../public-networks/reference/cli/options.md#metrics-push-port) options. + +To run Besu exposing local ports for access: + +```bash +docker run -p :8545 -p :8546 -p :30303 hyperledger/besu:latest --rpc-http-enabled --rpc-ws-enabled +``` + +:::note + +The examples on this page expose TCP ports only. To expose UDP ports, specify `/udp` at the end of the argument for the `-p` Docker subcommand option: + +```bash +docker run -p :/udp +``` + +See the [`docker run -p` documentation](https://docs.docker.com/engine/reference/commandline/run/#publish-or-expose-port--p---expose). + +::: + +To enable JSON-RPC HTTP calls to `127.0.0.1:8545` and P2P discovery on `127.0.0.1:13001`: + +```bash +docker run -p 8545:8545 -p 13001:30303 hyperledger/besu:latest --rpc-http-enabled +``` + +## Start Besu + +:::danger + +Don't mount a volume at the default data path (`/opt/besu`). Mounting a volume at the default data path interferes with the operation of Besu and prevents Besu from safely launching. + +To run a node that maintains the node state (key and database), [`--data-path`](../../../public-networks/reference/cli/options.md#data-path) must be set to a location other than `/opt/besu` and a storage volume mounted at that location. + +When running in a Docker container, [`--nat-method`](../../../public-networks/how-to/connect/specify-nat.md) must be set to `DOCKER` or `AUTO` (default). Don't set [`--nat-method`](../../../public-networks/how-to/connect/specify-nat.md) to `NONE` or `UPNP`. + +::: + +You can specify [Besu environment variables](../../../public-networks/reference/cli/options.md#specify-options) with the Docker image instead of the command line options. + +```bash +docker run -p 30303:30303 -p 8545:8545 -e BESU_RPC_HTTP_ENABLED=true -e BESU_NETWORK=goerli hyperledger/besu:latest +``` + +:::caution "Unsupported address type exception" + +When running Besu from a Docker image, you might get the following exception: + +```bash +Unsupported address type exception when connecting to peer {}, this is likely due to ipv6 not being enabled at runtime. +``` + +This happens when the IPv6 support in Docker is disabled while connecting to an IPv6 peer, preventing outbound communication. IPv6 is disabled by default in Docker. + +[Enable IPv6 support in Docker](https://docs.docker.com/config/daemon/ipv6/) to allow outbound IPv6 traffic and allow connection with IPv6 peers. + +::: + +### Run a node for testing + +To run a node that mines blocks at a rate suitable for testing purposes with WebSocket enabled: + +```bash +docker run -p 8546:8546 --mount type=bind,source=/,target=/var/lib/besu hyperledger/besu:latest --miner-enabled --miner-coinbase fe3b557e8fb62b89f4916b721be55ceb828dbd73 --rpc-ws-enabled --network=dev --data-path=/var/lib/besu +``` + +## Stop Besu and clean up resources + +When done running nodes, you can shut down the node container without deleting resources or you can delete the container after stopping it. Run `docker container ls` and `docker volume ls` to get the container and volume names. + +To stop a container: + +```bash +docker stop +``` + +To delete a container: + +```bash +docker rm +``` diff --git a/versioned_docs/version-23.10.1/private-networks/get-started/start-node.md b/versioned_docs/version-23.10.1/private-networks/get-started/start-node.md new file mode 100644 index 00000000000..4d7162a5927 --- /dev/null +++ b/versioned_docs/version-23.10.1/private-networks/get-started/start-node.md @@ -0,0 +1,106 @@ +--- +title: Start Besu +description: Start Besu on a private Ethereum network. +sidebar_position: 3 +tags: + - private networks +--- + +# Start Besu + +Use the [`besu`](../reference/cli/options.md) command with the required command line options to start a node. + +## Prerequisites + +[Besu installed](install/binary-distribution.md) + +## Local block data + +When connecting to a network other than the network previously connected to, you must either delete the local block data or use the [`--data-path`](../../public-networks/reference/cli/options.md#data-path) option to specify a different data directory. + +To delete the local block data, delete the `database` directory in the `besu/build/distribution/besu-` directory. + +## Genesis configuration + +To define a genesis configuration, create a [genesis file](../../public-networks/concepts/genesis-file.md) (for example, `genesis.json`) and specify the file using the [`--genesis-file`](../../public-networks/reference/cli/options.md#genesis-file) option. + +When you specify [`--network=dev`](../../public-networks/reference/cli/options.md#network), Besu uses the development mode genesis configuration with a fixed low difficulty. A node started with [`--network=dev`](../../public-networks/reference/cli/options.md#network) has an empty bootnodes list by default. + +Predefined genesis configurations for named networks are in the [Besu source files](https://github.com/hyperledger/besu/tree/master/config/src/main/resources). + +## Confirm node is running + +If you started Besu with the [`--rpc-http-enabled`](../../public-networks/reference/cli/options.md#rpc-http-enabled) option, use [cURL](https://curl.haxx.se/) to call [JSON-RPC API methods](../reference/api/index.md) to confirm the node is running. + +- `eth_chainId` returns the chain ID of the network. + + ```bash + curl -X POST --data '{"jsonrpc":"2.0","method":"eth_chainId","params":[],"id":1}' localhost:8545 + ``` + +- `eth_syncing` returns the starting, current, and highest block. + + ```bash + curl -X POST --data '{"jsonrpc":"2.0","method":"eth_syncing","params":[],"id":1}' localhost:8545 + ``` + + For example, after connecting to Mainnet, `eth_syncing` will return something similar to: + + ```json + { + "jsonrpc": "2.0", + "id": 1, + "result": { + "startingBlock": "0x0", + "currentBlock": "0x2d0", + "highestBlock": "0x66c0" + } + } + ``` + +## Run a node for testing + +To run a node that mines blocks at a rate suitable for testing purposes: + +```bash +besu --network=dev --miner-enabled --miner-coinbase=0xfe3b557e8fb62b89f4916b721be55ceb828dbd73 --rpc-http-cors-origins="all" --host-allowlist="*" --rpc-ws-enabled --rpc-http-enabled --data-path=/tmp/tmpDatdir +``` + +You can also use the following [configuration file](../../public-networks/how-to/configuration-file.md) on the command line to start a node with the same options as above: + +```toml +network="dev" +miner-enabled=true +miner-coinbase="0xfe3b557e8fb62b89f4916b721be55ceb828dbd73" +rpc-http-cors-origins=["all"] +host-allowlist=["*"] +rpc-ws-enabled=true +rpc-http-enabled=true +data-path="/tmp/tmpdata-path" +``` + +:::caution + +The following settings are a security risk in production environments: + +- Enabling the HTTP JSON-RPC service ([`--rpc-http-enabled`](../../public-networks/reference/cli/options.md#rpc-http-enabled)) and setting [`--rpc-http-host`](../../public-networks/reference/cli/options.md#rpc-http-host) to 0.0.0.0 exposes the RPC connection on your node to any remote connection. +- Setting [`--host-allowlist`](../../public-networks/reference/cli/options.md#host-allowlist) to `"*"` allows JSON-RPC API access from any host. +- Setting [`--rpc-http-cors-origins`](../../public-networks/reference/cli/options.md#rpc-http-cors-origins) to `"all"` or `"*"` allows cross-origin resource sharing (CORS) access from any domain. + +::: + +## Run a node on a private network + +To run a node on your private network specifying a genesis file and data directory: + +```bash +besu --genesis-file=/genesis.json --data-path= --rpc-http-enabled --bootnodes= +``` + +Where `` is the path to the directory to save the chain data to. Ensure you configure a peer discovery method, such as [bootnodes](../how-to/configure/bootnodes.md). + +:::note + +You might need to set [`--tx-pool-limit-by-account-percentage`](../../public-networks/reference/cli/options.md#tx-pool-limit-by-account-percentage) to 1. The default value is suitable for Mainnet, but may cause issues on private networks. + +::: diff --git a/versioned_docs/version-23.10.1/private-networks/get-started/system-requirements.md b/versioned_docs/version-23.10.1/private-networks/get-started/system-requirements.md new file mode 100644 index 00000000000..18666307ee7 --- /dev/null +++ b/versioned_docs/version-23.10.1/private-networks/get-started/system-requirements.md @@ -0,0 +1,52 @@ +--- +title: System requirements +description: Ensure you meet the system requirements to sync and run Besu. +sidebar_position: 1 +tags: + - private networks +--- + +# System requirements + +Private network system requirements depend on many factors, including: + +- Size of the world state for the network. +- Number of transactions submitted to the network. +- [Block gas limit](../../public-networks/reference/genesis-items.md#genesis-block-parameters). +- Number and complexity of [JSON-RPC](../../public-networks/how-to/use-besu-api/json-rpc.md), [PubSub](../../public-networks/how-to/use-besu-api/rpc-pubsub.md), or [GraphQL](../../public-networks/how-to/use-besu-api/graphql.md) queries handled by the node. + +Participation in private networks is typically restricted in some way, so the volume of traffic is much lower than on Mainnet, resulting in lower system requirements. + +## Determining system requirements + +To determine system requirements, check CPU and disk space requirements using [Prometheus](../../public-networks/how-to/monitor/metrics.md). Grafana provides a [sample dashboard](https://grafana.com/grafana/dashboards/10273) for Besu. + +## Java Virtual Machine size + +Depending on your environment and network setup, the minimum Java Virtual Machine (JVM) memory requirement for private networks is 4 GB. + +JVM memory requirements are highest when syncing, but will reduce after the node is synchronized to the chain head. Monitor your system to determine your actual JVM memory needs. + +## VM requirements + +If you set up your own VM locally using a VM manager such as [VirtualBox](https://www.oracle.com/virtualization/virtualbox/): + +- Ensure you enable Intel Virtualization Technology (VTx) and Virtualization Technology for Directed I/O (VT-d) in the BIOS settings. +- On Windows, you might need to disable Hyper-V in the Windows Feature list. + +We recommend you create a VM with the following attributes: + +- Memory size: Set to 6 GB (recommended) +- Create a virtual hard disk with at least 10 GB (20 GB recommended) +- Virtual hard disk file type: VDI (if you need to share it with other apps, use VHD) +- (Optional) You can create a shared directory to copy block files or genesis files from the host computer to the VM. For details on how to create a shared directory, see "Share Folders" in the [Oracle VirtualBox documentation]. + +## Disk type + +Use [local SSD storage](https://cloud.google.com/compute/docs/disks) for high throughput nodes (validators and RPC nodes). Read-only nodes can use a lower performance setup. + +You can use local SSDs through [SCSI interfaces](https://en.wikipedia.org/wiki/SCSI). For higher performance in production settings, we recommend upgrading to [NVMe interfaces](https://cloud.google.com/compute/docs/disks/local-ssd#performance). + + + +[Oracle VirtualBox documentation]: https://docs.oracle.com/en/virtualization/virtualbox/6.1/user/ diff --git a/versioned_docs/version-23.10.1/private-networks/how-to/_category_.json b/versioned_docs/version-23.10.1/private-networks/how-to/_category_.json new file mode 100644 index 00000000000..ba43c43036f --- /dev/null +++ b/versioned_docs/version-23.10.1/private-networks/how-to/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "How to", + "position": 3 +} diff --git a/versioned_docs/version-23.10.1/private-networks/how-to/backup.md b/versioned_docs/version-23.10.1/private-networks/how-to/backup.md new file mode 100644 index 00000000000..d81cca0621c --- /dev/null +++ b/versioned_docs/version-23.10.1/private-networks/how-to/backup.md @@ -0,0 +1,51 @@ +--- +title: Backup and restore +description: Backing up and restoring Besu +sidebar_position: 7 +tags: + - private networks +--- + +# Backup and restore Besu + +In a decentralized blockchain, data replicates between nodes so it's not lost. But backing up configuration and data ensures a smoother recovery from corrupted data or other failures. + +## Genesis file + +The genesis file for a network must be accessible on every node. We recommend storing the genesis file under source control. + +## Data backups + +If installed locally, the default data location is the Besu installation directory. + +We recommend mounting a [separate volume to store data](../get-started/install/run-docker-image.md). Use the [`--data-path`](../../public-networks/reference/cli/options.md#data-path) command line option to pass the path to Besu. + +The default data location is the Besu installation directory, or `/opt/besu/database` if using the [Besu Docker image](../get-started/install/run-docker-image.md). + +Having some data reduces the time to synchronize a new node. You can perform periodic backups of the data directory and send the data to your preferred backup mechanism. For example, `cron` job and `rsync`, archives to the cloud such as s3, or `tar.gz` archives. + +## Data restores + +To restore data: + +1. If the node is running, stop the node. +1. If required, move the data directory to another location for analysis. +1. Restore the data from your last known good backup to the same directory. +1. Ensure user permissions are valid so you can read from and write to the data directory. +1. Restart the node. + +## Corrupted data + +If log messages signify a corrupt database, the cleanest way to recover is: + +1. Stop the node. +1. Restore the data from a [previous backup](#data-backups). +1. Restart the node. + +## Find peers after restarting + +The process for finding peers after restarting is the same as for [finding peers after upgrading and restarting]. + + + +[finding peers after upgrading and restarting]: ../../public-networks/how-to/upgrade-node.md#find-peers-on-restarting diff --git a/versioned_docs/version-23.10.1/private-networks/how-to/configure/_category_.json b/versioned_docs/version-23.10.1/private-networks/how-to/configure/_category_.json new file mode 100644 index 00000000000..49e1f9da31b --- /dev/null +++ b/versioned_docs/version-23.10.1/private-networks/how-to/configure/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Configure", + "position": 1 +} diff --git a/versioned_docs/version-23.10.1/private-networks/how-to/configure/block-proposal-permissioning.md b/versioned_docs/version-23.10.1/private-networks/how-to/configure/block-proposal-permissioning.md new file mode 100644 index 00000000000..c164fadeddd --- /dev/null +++ b/versioned_docs/version-23.10.1/private-networks/how-to/configure/block-proposal-permissioning.md @@ -0,0 +1,292 @@ +--- +title: Block proposal permissioning +description: Block proposal permissioning +sidebar_position: 7 +tags: + - private networks +--- + +# Block proposal permissioning + +:::info + +Only private networks using the [QBFT consensus protocol] support block proposal permissioning. + +Block proposal permissioning is an early access feature, and functionality and options may be updated between releases. + +::: + +You can configure [block proposal permissioning](../../concepts/pki.md#block-proposal-permissioning) to ensure only authorized validator nodes can propose blocks in the network. + +Use certificates issued by a trusted authority to ensure validators are authorized to propose blocks. + +## Configure block proposal permissioning + +**Prerequisites**: + +- A configured network. For example, [see steps 1 to 5 in the QBFT tutorial](../../tutorials/qbft.md). +- A keystore containing the certificate and key for each network node. +- A truststore containing all the trusted certificates for the network. + +Start Besu and include the following command line options on the required nodes: + +```bash +besu --Xpki-block-creation-enabled=true \ +--Xpki-block-creation-keystore-type="pkcs12" \ +--Xpki-block-creation-keystore-file="keystore" \ +--Xpki-block-creation-keystore-password-file="keystore.password" \ +--Xpki-block-creation-crl-file="crl2.pem" \ +--Xpki-block-creation-keystore-certificate-alias="validator" \ +--Xpki-block-creation-truststore-type="pkcs12" \ +--Xpki-block-creation-truststore-file="truststore" \ +--Xpki-block-creation-truststore-password-file="truststore.password" +``` + +In the command line: + +- Enable block proposal permissioning using [`--Xpki-block-creation-enabled=true`](#xpki-block-creation-enabled). +- Specify the keystore type and keystore file using [`Xpki-block-creation-keystore-type`](#xpki-block-creation-keystore-type) and [`--Xpki-block-creation-keystore-file`](#xpki-block-creation-keystore-file). +- Specify the text file containing the password to unlock the keystore file using [`Xpki-block-creation-keystore-password-file`](#xpki-block-creation-keystore-password-file). +- Specify the optional [certificate revocation list (CRL)] file using [`Xpki-block-creation-crl-file`](#xpki-block-creation-crl-file). +- Specify the alias of the certificate to be included in blocks proposed by this validator using [`Xpki-block-creation-keystore-certificate-alias`](#xpki-block-creation-keystore-certificate-alias). +- Specify the truststore type and truststore file using [`Xpki-block-creation-truststore-type`](#xpki-block-creation-truststore-type) and [`Xpki-block-creation-truststore-file`](#xpki-block-creation-truststore-file). +- Specify the text file containing the password to unlock the truststore file using [`Xpki-block-creation-truststore-password-file`](#xpki-block-creation-truststore-password-file). + +## Command line options + +### `Xpki-block-creation-crl-file` + + + +# Syntax + +```bash +--Xpki-block-creation-crl-file= +``` + +# Example + +```bash +--Xpki-block-creation-crl-file=/home/cert/cert.crl.pem +``` + +# Environment variable + +```bash +BESU_XPKI_BLOCK_CREATION_CRL_FILE=/home/cert/cert.crl.pem +``` + + + +Path to the optional certificate revocation list (CRL) file. + +### `Xpki-block-creation-enabled` + + + +# Syntax + +```bash +--Xpki-block-creation-enabled[=] +``` + +# Example + +```bash +--Xpki-block-creation-enabled=true +``` + +# Environment variable + +```bash +BESU_XPKI_BLOCK_CREATION_ENABLED=true +``` + + + +Enable PKI integration. The default is `false`. + +### `Xpki-block-creation-keystore-certificate-alias` + + + +# Syntax + +```bash +--Xpki-block-creation-keystore-certificate-alias= +``` + +# Example + +```bash +--Xpki-block-creation-keystore-certificate-alias=validatorA +``` + +# Environment variable + +```bash +BESU_XPKI_BLOCK_CREATION_KEYSTORE_CERTIFICATE_ALIAS=validatorA +``` + + + +Alias of the certificate to be included in the blocks proposed by this validator. The default is `validator`. + +### `Xpki-block-creation-keystore-file` + + + +# Syntax + +```bash +--Xpki-block-creation-keystore-file= +``` + +# Example + +```bash +--Xpki-block-creation-keystore-file=/home/cert/keystore.jks +``` + +# Environment variable + +```bash +BESU_XPKI_BLOCK_CREATION_KEYSTORE_FILE=/home/cert/keystore.jks +``` + + + +Keystore file containing the key and certificate for PKI block creation. + +### `Xpki-block-creation-keystore-password-file` + + + +# Syntax + +```bash +--Xpki-block-creation-keystore-password-file= +``` + +# Example + +```bash +--Xpki-block-creation-keystore-password-file=/home/cert/password.txt +``` + +# Environment variable + +```bash +BESU_XPKI_BLOCK_CREATION_KEYSTORE_PASSWORD-FILE=/home/cert/password.txt +``` + + + +Text file containing the password to unlock the keystore file. + +### `Xpki-block-creation-keystore-type` + + + +# Syntax + +```bash +--Xpki-block-creation-keystore-type= +``` + +# Example + +```bash +--Xpki-block-creation-keystore-type=JKS +``` + +# Environment variable + +```bash +BESU_XPKI_BLOCK_CREATION_KEYSTORE_TYPE=JKS +``` + + + +PKI keystore type. Valid options are `JKS` and `PKCS12`. The default is `JKS`. + +### `Xpki-block-creation-truststore-file` + + + +# Syntax + +```bash +--Xpki-block-creation-truststore-file= +``` + +# Example + +```bash +--Xpki-block-creation-truststore-file=/home/cert/truststore.jks +``` + +# Environment variable + +```bash +BESU_XPKI_BLOCK_CREATION_TRUSTSTORE_FILE=/home/cert/truststore.jks +``` + + + +Truststore containing the trusted certificates for PKI block creation. + +### `Xpki-block-creation-truststore-password-file` + + + +# Syntax + +```bash +--Xpki-block-creation-truststore-password-file= +``` + +# Example + +```bash +--Xpki-block-creation-truststore-password-file=/home/cert/password.txt +``` + +# Environment variable + +```bash +BESU_XPKI_BLOCK_CREATION_TRUSTSTORE_PASSWORD_FILE=/home/cert/password.txt +``` + + + +Text file containing the password to unlock the truststore file. + +### `Xpki-block-creation-truststore-type` + + + +# Syntax + +```bash +--Xpki-block-creation-truststore-type= +``` + +# Example + +```bash +--Xpki-block-creation-truststore-type=JKS +``` + +# Environment variable + +```bash +BESU_XPKI_BLOCK_CREATION_TRUSTSTORE_TYPE=JKS +``` + + + +PKI truststore type. Valid options are `JKS` and `PKCS12`. The default is `JKS`. + +[QBFT consensus protocol]: ./consensus/qbft.md +[certificate revocation list (CRL)]: https://www.securew2.com/blog/certificate-revocation-crl-explained diff --git a/versioned_docs/version-23.10.1/private-networks/how-to/configure/bootnodes.md b/versioned_docs/version-23.10.1/private-networks/how-to/configure/bootnodes.md new file mode 100644 index 00000000000..11787681a04 --- /dev/null +++ b/versioned_docs/version-23.10.1/private-networks/how-to/configure/bootnodes.md @@ -0,0 +1,71 @@ +--- +title: Bootnodes +description: Configuring bootnodes +sidebar_position: 3 +tags: + - private networks +--- + +# Configure bootnodes + +You can use bootnodes to initially discover peers. Bootnodes are regular nodes used to discover other nodes. + +In private networks for development or testing purposes, specify at least one bootnode. + +In production networks, [configure two or more nodes as bootnodes](#configure-bootnodes-in-a-production-network). + +:::tip + +Bootnodes and static nodes are parallel methods for finding peers. Depending on your use case, you can use only bootnodes, only static nodes, or both bootnodes and static nodes. + +To find peers, configure one or more bootnodes. To configure a specific set of peer connections, use [static nodes](../../../public-networks/how-to/connect/static-nodes.md). + +::: + +:::note Mainnet and public testnets + +For Mainnet and the Sepolia and Goerli testnets, Hyperledger Besu has an internal list of enode URLs and uses this list automatically when you specify the [`--network`](../../../public-networks/reference/cli/options.md#network) option. + +::: + +## Specify a bootnode + +To start a node, specify a bootnode [enode](../../../public-networks/concepts/node-keys.md) for P2P discovery, using the [`--bootnodes`](../../../public-networks/reference/cli/options.md#bootnodes) option. + +```bash +besu --genesis-file=privateNetworkGenesis.json --data-path=nodeDataPath --bootnodes=enode://c35c3ec90a8a51fd5703594c6303382f3ae6b2ecb99bab2c04b3794f2bc3fc2631dabb0c08af795787a6c004d8f532230ae6e9925cbbefb0b28b79295d615f@127.0.0.1:30303 +``` + +The default host and port advertised to other peers for P2P discovery is `127.0.0.1:30303`. To specify a different host or port, use the [`--p2p-host`](../../../public-networks/reference/cli/options.md#p2p-host) and [`--p2p-port`](../../../public-networks/reference/cli/options.md#p2p-port) options. + +By default, peer discovery listens on all available network interfaces. If the device Besu is running on must bind to a specific network interface, specify the interface using the [`--p2p-interface`](../../../public-networks/reference/cli/options.md#p2p-interface) option. + +## Configure bootnodes in a production network + +A network must have at least one operating bootnode. To allow for continuity in the event of failure, configure two or more bootnodes in a production network. + +We don't recommend putting bootnodes behind a load balancer because the [enode](../../../public-networks/concepts/node-keys.md#enode-url) relates to the node public key, IP address, and discovery ports. Any changes to a bootnode enode prevents other nodes from being able to establish a connection with the bootnode. This is why we recommend putting more bootnodes on the network itself. + +To ensure a bootnode enode doesn't change when recovering from a complete bootnode failure: + +1. Create the [node key pair](../../../public-networks/concepts/node-keys.md) (that is, the private and public key) before starting the bootnode. +1. When creating bootnodes in the cloud (for example, AWS and Azure), attempt to assign a static IP address to them. If your network is: + + - Publicly accessible, assign an elastic IP. + - Internal only, specify a private IP address when you create the instance and record this IP address. + +We recommend storing the bootnode configuration under source control. + +To allow for failure, specify all bootnodes on the command line (even to the bootnodes themselves). + +:::tip + +Having each bootnode list the other bootnodes increases the speed of discovery. Nodes ignore their own enode in the bootnodes list so it isn't required to specify different bootnode lists to the bootnodes themselves. + +::: + +## Add and remove bootnodes + +Adding new bootnodes is a similar process to creating bootnodes. After creating the bootnodes and adding them to the network, update the [`--bootnodes`](../../../public-networks/reference/cli/options.md#bootnodes) command line option for each node to include the new bootnodes. + +When adding bootnodes, you don't need to restart running nodes. By updating the [`--bootnodes`](../../../public-networks/reference/cli/options.md#bootnodes) option, the next time you restart the nodes (for example, when [upgrading](../../../public-networks/how-to/upgrade-node.md)), the nodes connect to the new bootnodes. diff --git a/versioned_docs/version-23.10.1/private-networks/how-to/configure/consensus/_category_.json b/versioned_docs/version-23.10.1/private-networks/how-to/configure/consensus/_category_.json new file mode 100644 index 00000000000..bc0d5770af5 --- /dev/null +++ b/versioned_docs/version-23.10.1/private-networks/how-to/configure/consensus/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Consensus", + "position": 1 +} diff --git a/versioned_docs/version-23.10.1/private-networks/how-to/configure/consensus/add-validators-without-voting.md b/versioned_docs/version-23.10.1/private-networks/how-to/configure/consensus/add-validators-without-voting.md new file mode 100644 index 00000000000..70d875e33a0 --- /dev/null +++ b/versioned_docs/version-23.10.1/private-networks/how-to/configure/consensus/add-validators-without-voting.md @@ -0,0 +1,309 @@ +--- +title: Add and remove validators without voting +description: How to add or remove validators without voting +sidebar_position: 5 +tags: + - private networks +--- + +# Add and remove validators without voting + +[QBFT](qbft.md) or [IBFT 2.0](ibft.md) network conditions might not allow voting to change validators. For example, if a majority of the current validators are no longer participating in the network, a vote to add or remove validators won't be successful. You can bypass voting and specify new validators using a transition in the genesis file. + +:::caution + +- In most cases, add or remove validators [by voting or smart contract for QBFT](qbft.md#add-and-remove-validators); or [by voting for IBFT 2.0](ibft.md#add-and-remove-validators). Use transitions only when voting isn't possible. Using transitions requires coordinating a rolling update of all the nodes in order to pick up the configuration at the correct block height. Using transitions also leaves the validator overrides permanently in your genesis configuration. +- Transitions are a Besu-specific feature. If you run a mixed-client QBFT network, you can't use transitions to change the validators. + +::: + +To add or remove validators without voting: + +1. In the genesis file, add the `transitions` configuration item where: + + - `` is the upcoming block at which to change validators. + - ` ... ` are strings representing the account addresses of the validators after ``. + + + + # QBFT syntax + + ```bash + { + "config": { + ... + "qbft": { + "blockperiodseconds": 2, + "epochlength": 30000, + "requesttimeoutseconds": 4 + }, + "transitions": { + "qbft": [ + { + "block": , + "validators": [ + , + ... + + ] + } + ] + } + }, + ... + } + ``` + + # QBFT example + + ```bash + { + "config": { + ... + "qbft": { + "blockperiodseconds": 2, + "epochlength": 30000, + "requesttimeoutseconds": 4 + }, + "transitions": { + "qbft": [ + { + "block": 25, + "validators": [ + "0x372a70ace72b02cc7f1757183f98c620254f9c8d", + "0x9811ebc35d7b06b3fa8dc5809a1f9c52751e1deb" + ] + } + ] + } + }, + ... + } + ``` + + # IBFT 2.0 syntax + + ```bash + { + "config": { + ... + "ibft2": { + "blockperiodseconds": 2, + "epochlength": 30000, + "requesttimeoutseconds": 4 + }, + "transitions": { + "ibft2": [ + { + "block": , + "validators": [ + , + ... + + ] + } + ] + } + }, + ... + } + ``` + + # IBFT 2.0 example + + ```bash + { + "config": { + ... + "ibft2": { + "blockperiodseconds": 2, + "epochlength": 30000, + "requesttimeoutseconds": 4 + }, + "transitions": { + "ibft2": [ + { + "block": 25, + "validators": [ + "0x372a70ace72b02cc7f1757183f98c620254f9c8d", + "0x9811ebc35d7b06b3fa8dc5809a1f9c52751e1deb" + ] + } + ] + } + }, + ... + } + ``` + + + +2. Restart all nodes in the network using the updated genesis file. You can make a rolling update of the nodes, as long as they're all up before the transition block is processed. +3. To verify the changes after the transition block, call [`qbft_getValidatorsByBlockNumber`](../../../reference/api/index.md#qbft_getvalidatorsbyblocknumber) or [`ibft_getValidatorsByBlockNumber`](../../../reference/api/index.md#ibft_getvalidatorsbyblocknumber), specifying `latest`. + +:::caution + +Don't specify a transition block in the past. + +Specifying a transition block in the past can result in unexpected behavior, such as causing the network to fork. + +::: + +## Override smart contract validators + +When using [QBFT contract validator selection](qbft.md#add-and-remove-validators-using-a-smart-contract), if network conditions require it, you can bypass the smart contract and specify new validators in the genesis file. For example, you lose quorum for your current list of contract validators, and you can't perform a transaction to vote more in. + +This requires temporarily [switching to block header validator selection mode](qbft.md#swap-validator-management-methods). + +To bypass the smart contract and specify new validators: + +1. In the genesis file, add a `transitions` configuration item where: + + - `` is the upcoming block at which to change validators. + - `` is the validator selection mode to switch to. In this case we'll switch to the `blockheader` mode temporarily. + - ` ... ` are strings representing the account addresses of the validators after ``. These validators only need to be sufficient to progress the chain and allow a new contract to be deployed. + + + + # Syntax + + ```bash + { + "config": { + ... + "qbft": { + "blockperiodseconds": 2, + "epochlength": 30000, + "requesttimeoutseconds": 4, + "validatorcontractaddress": "0x0000000000000000000000000000000000007777" + }, + "transitions": { + "qbft": [ + { + "block": , + "validatorselectionmode": , + "validators": [ + , + ... + + ] + } + ] + } + }, + ... + } + ``` + + # Example + + ```bash + { + "config": { + ... + "qbft": { + "blockperiodseconds": 2, + "epochlength": 30000, + "requesttimeoutseconds": 4, + "validatorcontractaddress": "0x0000000000000000000000000000000000007777" + }, + "transitions": { + "qbft": [ + { + "block": 2555, + "validatorselectionmode": "blockheader", + "validators": [ + "0x372a70ace72b02cc7f1757183f98c620254f9c8d", + "0x9811ebc35d7b06b3fa8dc5809a1f9c52751e1deb" + ] + } + ] + } + }, + ... + } + ``` + + + +1. Restart all nodes in the network using the updated genesis file. You can make a rolling update of the nodes, as long as they're all up before the transition block is processed. +1. Deploy a new contract to the blockchain containing the desired list of validators. +1. In the genesis file, add another `transitions` configuration item where: + + - `` is the upcoming block at which to change validators. + - `` is the validator selection mode to switch to. In this case we'll switch to `contract` mode. + - `` is the address of the new smart contract. + + + + # Syntax + + ```bash + { + "config": { + ... + "qbft": { + "blockperiodseconds": 2, + "epochlength": 30000, + "requesttimeoutseconds": 4, + “validatorcontractaddress”: “0x0000000000000000000000000000000000007777” + }, + "transitions": { + "qbft": [ + { + "block": 2555, + "validatorselectionmode": "blockheader", + "validators": [ + "0x372a70ace72b02cc7f1757183f98c620254f9c8d", + "0x9811ebc35d7b06b3fa8dc5809a1f9c52751e1deb" + ] + }, + { + "block": , + "validatorselectionmode": , + "validatorcontractaddress": + } + ] + } + }, + ... + } + ``` + + # Example + + ```bash + { + "config": { + ... + "qbft": { + "blockperiodseconds": 2, + "epochlength": 30000, + "requesttimeoutseconds": 4, + "validatorcontractaddress": "0x0000000000000000000000000000000000007777" + }, + "transitions": { + "qbft": [ + { + "block": 2555, + "validatorselectionmode": "blockheader", + "validators": [ + "0x372a70ace72b02cc7f1757183f98c620254f9c8d", + "0x9811ebc35d7b06b3fa8dc5809a1f9c52751e1deb" + ] + }, + { + "block": 2755, + "validatorselectionmode": "contract", + "validatorcontractaddress": "0x0000000000000000000000000000000000009999" + } + ] + } + }, + ... + } + ``` + + + +1. Restart all nodes in the network using the updated genesis file. You can make a rolling update of the nodes, as long as they're all up before the transition block is processed. diff --git a/versioned_docs/version-23.10.1/private-networks/how-to/configure/consensus/clique.md b/versioned_docs/version-23.10.1/private-networks/how-to/configure/consensus/clique.md new file mode 100644 index 00000000000..6bf2aecf81f --- /dev/null +++ b/versioned_docs/version-23.10.1/private-networks/how-to/configure/consensus/clique.md @@ -0,0 +1,158 @@ +--- +title: Clique +description: Hyperledger Besu Clique Proof-of-Authority (PoA) consensus protocol implementation +sidebar_position: 4 +path: blob/master/config/src/main/resources/ +source: rinkeby.json +tags: + - private networks +--- + +# Configure Clique consensus + +Besu implements the [Clique](https://eips.ethereum.org/EIPS/eip-225) proof of authority (PoA) [consensus protocol](index.md). Private networks can use Clique. + +:::danger + +Clique is not suitable for production environments. Use only in development environments. + +::: + +In Clique networks, approved accounts, known as signers, validate transactions and blocks. Signers take turns to create the next block. Existing signers propose and vote to [add or remove signers](#add-and-remove-signers). + +You can [create a private network using Clique](../../../tutorials/clique.md). + +## Genesis file + +To use Clique in a private network, Besu requires a Clique [genesis file](../../../../public-networks/concepts/genesis-file.md). + +A Clique genesis file defines properties specific to Clique. + +```json title="Example Clique genesis file" +{ + "config": { + "chainId": 1981, + "berlinBlock": 0, + "clique": { + "blockperiodseconds": 15, + "epochlength": 30000 + } + }, + "coinbase": "0x0000000000000000000000000000000000000000", + "difficulty": "0x1", + "extraData": "0x000000000000000000000000000000000000000000000000000000000000000001a54556254bfa3db2daa7673435ec63649925c50000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000", + "gasLimit": "0x1fffffffffffff", + "mixHash": "0x0000000000000000000000000000000000000000000000000000000000000000", + "nonce": "0x0", + "timestamp": "0x5c51a607", + "alloc": {}, + "number": "0x0", + "gasUsed": "0x0", + "parentHash": "0x0000000000000000000000000000000000000000000000000000000000000000" +} +``` + +The properties specific to Clique are: + +- `blockperiodseconds` - The block time, in seconds. +- `epochlength` - The number of blocks after which to reset all votes. +- `extraData` - [Extra data](#extra-data) including the initial signers. + +### Extra data + +The `extraData` property consists of: + +- 0x prefix. +- 32 bytes of vanity data. +- A list of initial signer addresses (at least one initial signer is required). 20 bytes for each signer. +- 65 bytes for the proposer signature. In the genesis block there is no initial proposer, so the proposer signature is all zeros. + +### One initial signer + +![One Initial Signer](../../../../assets/images/CliqueOneIntialSigner.png) + +### Two initial signers + +![Two Initial Signers](../../../../assets/images/CliqueTwoIntialSigners.png) + +### Post-Merge configuration + +After [The Merge](../../../../public-networks/concepts/the-merge.md), the following block fields are modified or deprecated. Their fields **must** contain only the constant values from the following chart. + +| Field | Constant value | Comment | +| --- | --- | --- | +| **`ommersHash`** | `0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347` | `= Keccak256(RLP([]))` | +| **`difficulty`** | `0` | Replaced with `prevrandao` | +| **`mixHash`** | `0x0000000000000000000000000000000000000000000000000000000000000000` | Replaced with `prevrandao` | +| **`nonce`** | `0x0000000000000000` | | +| **`ommers`** | `[]` | `RLP([]) = 0xc0` | + +Additionally, [`extraData`](#extra-data) is limited to 32 bytes of vanity data after The Merge. + +## Connect to a Clique network + +To start a node on a Clique private network, use the [`--genesis-file`](../../../../public-networks/reference/cli/options.md#genesis-file) option to specify the custom genesis file. + +## Add and remove signers + +Existing signers propose and vote to add or remove validators using the Clique JSON-RPC API methods. Enable the HTTP interface with [`--rpc-http-enabled`](../../../../public-networks/reference/cli/options.md#rpc-http-enabled) or the WebSocket interface with [`--rpc-ws-enabled`](../../../../public-networks/reference/cli/options.md#rpc-ws-enabled). + +The Clique API methods are disabled by default. To enable them, specify the [`--rpc-http-api`](../../../../public-networks/reference/cli/options.md#rpc-http-api) or [`--rpc-ws-api`](../../../../public-networks/reference/cli/options.md#rpc-ws-api) option and include `CLIQUE`. + +The methods to add or remove signers are: + +- [`clique_propose`](../../../reference/api/index.md#clique_propose). +- [`clique_getSigners`](../../../reference/api/index.md#clique_getsigners). +- [`clique_discard`](../../../reference/api/index.md#clique_discard). + +To view signer metrics for a specified block range, call [`clique_getSignerMetrics`](../../../reference/api/index.md#clique_getsignermetrics). + +### Add a signer + +To propose adding a signer to a Clique network, call [`clique_propose`](../../../reference/api/index.md#clique_propose), specifying the address of the proposed signer and `true`. A majority of signers must execute the call. + +```bash title="JSON-RPC clique_propose request example" +curl -X POST --data '{"jsonrpc":"2.0","method":"clique_propose","params":["0xFE3B557E8Fb62b89F4916B721be55cEb828dBd73", true], "id":1}' +``` + +When the signer creates the next block, the signer adds a vote to the block for the proposed signer. + +When more than 50% of the existing signers propose adding the signer, with their votes distributed in blocks, the signer can begin signing blocks. + +To return a list of signers and confirm the addition of a proposed signer, call [`clique_getSigners`](../../../reference/api/index.md#clique_getsigners). + +```bash title="JSON-RPC clique_getSigners request example" +curl -X POST --data '{"jsonrpc":"2.0","method":"clique_getSigners","params":["latest"], "id":1}' +``` + +To discard your proposal after confirming the addition of a signer, call [`clique_discard`](../../../reference/api/index.md#clique_discard) specifying the address of the proposed signer. + +```bash title="JSON-RPC clique_discard request example" +curl -X POST --data '{"jsonrpc":"2.0","method":"clique_discard","params":["0xFE3B557E8Fb62b89F4916B721be55cEb828dBd73"], "id":1}' +``` + +### Remove a signer + +The process for removing a signer from a Clique network is the same as [adding a signer](#add-a-signer), except you specify `false` as the second parameter of [`clique_propose`](../../../reference/api/index.md#clique_propose). + +### Epoch transition + +At each epoch transition, Clique discards all pending votes collected from received blocks. Existing proposals remain in effect and signers re-add their vote the next time they create a block. + +Define the number of blocks between epoch transitions in the [Clique genesis file](#genesis-file). + +## Limitations + +In Clique, blocks created by in-turn validators are published immediately. Out-of-turn validators create blocks that are published after a short delay. In-turn blocks have a higher difficulty than out-of-turn blocks, which allows small forks to resolve to the chain with more in-turn blocks. + +However, when the out-of-turn delay is shorter than the block propagation delay, out-of-turn blocks may be published before in-turn blocks. This may cause large, irresolvable forks in a network. + +:::tip + +We recommend using a more updated consensus protocol such as [IBFT 2.0](ibft.md) or [QBFT](qbft.md). + +::: + + + +\*[vanity data]: Signers can include anything they like as vanity data. diff --git a/versioned_docs/version-23.10.1/private-networks/how-to/configure/consensus/ibft.md b/versioned_docs/version-23.10.1/private-networks/how-to/configure/consensus/ibft.md new file mode 100644 index 00000000000..de26b5a2a2b --- /dev/null +++ b/versioned_docs/version-23.10.1/private-networks/how-to/configure/consensus/ibft.md @@ -0,0 +1,501 @@ +--- +title: IBFT 2.0 +description: Hyperledger Besu IBFT 2.0 proof of authority (PoA) consensus protocol implementation +sidebar_position: 3 +tags: + - private networks +--- + +# Configure IBFT 2.0 consensus + +Besu implements the IBFT 2.0 proof of authority (PoA) [consensus protocol](index.md). IBFT 2.0 is supported for existing private networks, but [QBFT](qbft.md) is the recommended enterprise-grade consensus protocol for private networks. + +In IBFT 2.0 networks, approved accounts, known as validators, validate transactions and blocks. Validators take turns to create the next block. Before inserting the block onto the chain, a super-majority (greater than or equal to 2/3) of validators must first sign the block. + +Existing validators propose and vote to [add or remove validators](#add-and-remove-validators). + +You can [create a private network using IBFT](../../../tutorials/ibft/index.md). + +:::danger + +Configure your network to ensure you never lose more than 1/3 of your validators. If more than 1/3 of validators stop participating, new blocks are no longer created, and the network stalls. It may take significant time to recover once nodes are restarted. + +::: + +:::tip + +You can use a plugin to securely store a validator's key using the [`--security-module`](../../../../public-networks/reference/cli/options.md#security-module) option. + +::: + +## Genesis file + +To use IBFT 2.0, Besu requires an IBFT 2.0 [genesis file](../../../../public-networks/concepts/genesis-file.md). The genesis file defines properties specific to IBFT 2.0. + +```json title="Example IBFT 2.0 genesis file" +{ + "config": { + "chainId": 1981, + "berlinBlock": 0, + "ibft2": { + "blockperiodseconds": 2, + "epochlength": 30000, + "requesttimeoutseconds": 4, + "blockreward": "5000000000000000", + "miningbeneficiary": "0xfe3b557e8fb62b89f4916b721be55ceb828dbd73" + } + }, + "nonce": "0x0", + "timestamp": "0x58ee40ba", + "extraData": "0xf83ea00000000000000000000000000000000000000000000000000000000000000000d594c2ab482b506de561668e07f04547232a72897daf808400000000c0", + "gasLimit": "0x1fffffffffffff", + "difficulty": "0x1", + "mixHash": "0x63746963616c2062797a616e74696e65206661756c7420746f6c6572616e6365", + "alloc": {} +} +``` + +The properties specific to IBFT 2.0 are: + +- `blockperiodseconds` - The minimum block time, in seconds. +- `epochlength` - The number of blocks after which to reset all votes. +- `requesttimeoutseconds` - The timeout for each consensus round before a round change, in seconds. +- `blockreward` - Optional reward amount in Wei to reward the beneficiary. Defaults to zero (0). Can be specified as a hexadecimal (with 0x prefix) or decimal string value. If set, then all nodes on the network must use the identical value. +- `miningbeneficiary` - Optional beneficiary of the `blockreward`. Defaults to the validator that proposes the block. If set, then all nodes on the network must use the same beneficiary. +- `extraData` - RLP encoded [extra data](#extra-data). + +:::caution + +We don't recommend changing `epochlength` in a running network. Changing the `epochlength` after genesis can result in illegal blocks. + +::: + +:::caution Invalid block header error + +When adding a new node, if a `TimeStampMoreRecentThanParent | Invalid block header` error occurs, the genesis file of the new node specifies a higher `blockperiodseconds` than the imported chain. The imported chain makes new blocks faster than the genesis file allows and Besu rejects them with this error. This error most often occurs when importing chains from older versions of Besu. + +Decrease the `blockperiodseconds` in the new IBFT 2.0 genesis file to a lower value that satisfies the block header validation. + +::: + +If the error reads `| TimestampMoreRecentThanParent | Invalid block header: timestamp 1619660141 is only 3 seconds newer than parent timestamp 1619660138. Minimum 4 seconds`, decrease the `blockperiodseconds` from 4 seconds to 3 seconds to match the imported chain. + +After you update the new genesis file, if the imported chain has a `blockperiodseconds` value set lower than you prefer, you can adjust it by [configuring the block time on an existing IBFT 2.0 network](#configure-block-time-on-an-existing-network). + +The properties with specific values in the IBFT 2.0 genesis files are: + +- `nonce` - `0x0` +- `difficulty` - `0x1` +- `mixHash` - `0x63746963616c2062797a616e74696e65206661756c7420746f6c6572616e6365` for Istanbul block identification + +To start a node on an IBFT 2.0 private network, use the [`--genesis-file`](../../../../public-networks/reference/cli/options.md#genesis-file) option to specify the custom genesis file. + +### Extra data + +The `extraData` property is an RLP encoding of: + +- 32 bytes of vanity data. +- A list of validator addresses. +- Any validator votes. No vote is included in the genesis block. +- The round the block was created on. The round in the genesis block is 0. +- A list of seals of the validators (signed block hashes). No seals are included in the genesis block. + +In the genesis block, the important information in the extra data is the list of validators. All other details have empty values. Formally, `extraData` in the genesis block contains `RLP([32 bytes Vanity, List, No Vote, Round=Int(0), 0 Seals])`. + +:::info + +RLP encoding is a space-efficient object serialization scheme used in Ethereum. + +::: + +#### Generate extra data + +To generate the `extraData` RLP string for inclusion in the genesis file, use the [`rlp encode`](../../../../public-networks/reference/cli/subcommands.md#rlp) Besu subcommand. + +```bash title="Example" +besu rlp encode --from=toEncode.json +``` + +Where the `toEncode.json` file contains a list of the initial validators, in ascending order. To write the validator address and copy it to the `toEncode.json` file, use the [`public-key export-address`](../../../../public-networks/reference/cli/subcommands.md#export-address) Besu subcommand. For example: + +```json title="One initial validator in toEncode.json file" +["9811ebc35d7b06b3fa8dc5809a1f9c52751e1deb"] +``` + +Copy the RLP encoded data to the `extraData` property in the genesis file. + +### Block time + +When the protocol receives a new chain head, the block time (`blockperiodseconds`) and round timeout (`requesttimeoutseconds`) timers start. When `blockperiodseconds` expires, the protocol proposes a new block. + +If `requesttimeoutseconds` expires before adding the proposed block, a round change occurs, with the block time and timeout timers reset. The timeout period for the new round is two times `requesttimeoutseconds`. The timeout period continues to double each time a round fails to add a block. + +Usually, the protocol adds the proposed block before reaching `requesttimeoutseconds`. A new round then starts, resetting the block time and round timeout timers. When `blockperiodseconds` expires, the protocol proposes the next new block. + +:::danger + +If more than 1/3 of validators stop participating, new blocks can no longer be created and `requesttimeoutseconds` doubles with each round change. The quickest method to resume block production is to restart all validators, which resets `requesttimeoutseconds` to its genesis value. + +::: + +Once `blockperiodseconds` is over, the time from proposing a block to adding the block is small (usually around one second) even in networks with geographically dispersed validators. + +An internal network run by ConsenSys had four geographically dispersed validators in Sweden, Sydney, and two in North Virginia. With a `blockperiodseconds` of 5 and a `requesttimeoutseconds` of 10, the testnet consistently created blocks with a five second block time. + +#### Tune block timeout + +To tune the block timeout for your network deployment: + +1. Set `blockperiodseconds` to your desired block time and `requesttimeoutseconds` to two times `blockperiodseconds`. +1. Reduce `requesttimeoutseconds` until you start to see round changes occurring. +1. Increase `requesttimeoutseconds` to the value where round changes are no longer occurring. + +:::tip + +View [`TRACE` logs](../../../../public-networks/reference/api/index.md#trace-methods) to see round change log messages. + +::: + +Use a [transition](#transitions) to update the `blockperiodseconds` in an existing network. + +### Optional configuration options + +Optional configuration options in the genesis file are: + +- `messageQueueLimit` - In large networks with limited resources, increasing the message queue limit might help with message activity surges. The default is 1000. +- `duplicateMessageLimit` - If the same node is retransmitting messages, increasing the duplicate message limit might reduce the number of retransmissions. A value of two to three times the number of validators is usually enough. The default is 100. +- `futureMessagesLimit` - The future messages buffer holds messages for a future chain height. For large networks, increasing the future messages limit might be useful. The default is 1000. +- `futureMessagesMaxDistance` - The maximum height from the current chain height for buffering messages in the future messages buffer. The default is 10. + +### Post-Merge configuration + +After [The Merge](../../../../public-networks/concepts/the-merge.md), the following block fields are modified or deprecated. Their fields **must** contain only the constant values from the following chart. + +| Field | Constant value | Comment | +| --- | --- | --- | +| **`ommersHash`** | `0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347` | `= Keccak256(RLP([]))` | +| **`difficulty`** | `0` | Replaced with `prevrandao` | +| **`mixHash`** | `0x0000000000000000000000000000000000000000000000000000000000000000` | Replaced with `prevrandao` | +| **`nonce`** | `0x0000000000000000` | | +| **`ommers`** | `[]` | `RLP([]) = 0xc0` | + +Additionally, [`extraData`](#extra-data) is limited to 32 bytes of vanity data after The Merge. + +## Add and remove validators + +Existing validators propose and vote to add or remove validators using the IBFT 2.0 JSON-RPC API methods. Enable the HTTP interface with [`--rpc-http-enabled`](../../../../public-networks/reference/cli/options.md#rpc-http-enabled) or the WebSocket interface with [`--rpc-ws-enabled`](../../../../public-networks/reference/cli/options.md#rpc-ws-enabled). + +The IBFT 2.0 API methods are disabled by default. To enable them, specify the [`--rpc-http-api`](../../../../public-networks/reference/cli/options.md#rpc-http-api) or [`--rpc-ws-api`](../../../../public-networks/reference/cli/options.md#rpc-ws-api) option and include `IBFT`. + +The methods to add or remove validators are: + +- [`ibft_getPendingVotes`](../../../reference/api/index.md#ibft_getpendingvotes). +- [`ibft_proposeValidatorVote`](../../../reference/api/index.md#ibft_proposevalidatorvote). +- [`ibft_discardValidatorVote`](../../../reference/api/index.md#ibft_discardvalidatorvote). + +To view validator metrics for a specified block range, use [`ibft_getSignerMetrics`](../../../../public-networks/reference/api/index.md#ibft_getsignermetrics). + +:::note + +If network conditions render it impossible to add and remove validators by voting, you can [add and remove validators without voting](add-validators-without-voting.md). + +::: + +### Add a validator + +To propose adding a validator to an IBFT 2.0 network, call [`ibft_proposeValidatorVote`](../../../reference/api/index.md#ibft_proposevalidatorvote), specifying the address of the proposed validator and `true`. A majority of validators must execute the call. + +```bash title="JSON-RPC ibft_proposeValidatorVote request example" +curl -X POST --data '{"jsonrpc":"2.0","method":"ibft_proposeValidatorVote","params":["0xFE3B557E8Fb62b89F4916B721be55cEb828dBd73", true], "id":1}' +``` + +When the validator proposes the next block, the protocol inserts one proposal received from [`ibft_proposeValidatorVote`](../../../reference/api/index.md#ibft_proposevalidatorvote) into the block. If blocks include all proposals, subsequent blocks proposed by the validator will not contain a vote. + +When more than 50% of the existing validators have published a matching proposal, the protocol adds the proposed validator to the validator pool and the validator can begin validating blocks. + +To return a list of validators and confirm the addition of a proposed validator, use [`ibft_getValidatorsByBlockNumber`](../../../reference/api/index.md#ibft_getvalidatorsbyblocknumber). + +```bash title="JSON-RPC ibft_getValidatorsByBlockNumber request example" +curl -X POST --data '{"jsonrpc":"2.0","method":"ibft_getValidatorsByBlockNumber","params":["latest"], "id":1}' +``` + +To discard your proposal after confirming the addition of a validator, call [`ibft_discardValidatorVote`](../../../reference/api/index.md#ibft_discardvalidatorvote), specifying the address of the proposed validator. + +```bash title="JSON-RPC ibft_discardValidatorVote request example" +curl -X POST --data '{"jsonrpc":"2.0","method":"ibft_discardValidatorVote","params":["0xFE3B557E8Fb62b89F4916B721be55cEb828dBd73"], "id":1}' +``` + +### Remove a validator + +The process for removing a validator from an IBFT 2.0 network is the same as [adding a validator](#add-a-validator) except you specify `false` as the second parameter of [`ibft_proposeValidatorVote`](../../../reference/api/index.md#ibft_proposevalidatorvote). + +### Epoch transition + +At each epoch transition, IBFT 2.0 discards all pending votes collected from received blocks. Existing proposals remain in effect and validators re-add their vote the next time they create a block. + +An epoch transition occurs every `epochLength` blocks. Define `epochlength` in the [IBFT 2.0 genesis file](#genesis-file). + +### Minimum number of validators + +IBFT 2.0 requires four validators to be Byzantine fault tolerant. Byzantine fault tolerance is the ability for a blockchain network to function correctly and reach consensus despite nodes failing or propagating incorrect information to peers. + +### Maximum number of validators + +As the number of validators increase, the message complexity increases, which can decrease performance. In [network tests](https://wiki.hyperledger.org/display/BESU/Maximum+Validator+count+for+an+IBFT2+Network), IBFT 2.0 handles up to 30 validators with no loss of performance. + +Non-validator nodes don't affect performance and don't count towards the maximum limit. + +## Transitions + +The `transitions` genesis configuration item allows you to specify a future block number at which to change IBFT 2.0 network configuration in an existing network. For example, you can update the [block time](#configure-block-time-on-an-existing-network-deployment), [block reward](#configure-block-rewards-on-an-existing-network-deployment), or [mining beneficiary](#configure-the-mining-beneficiary-on-an-existing-network-deployment). + +:::caution + +Do not specify a transition block in the past. Specifying a transition block in the past could result in unexpected behavior, such as causing the network to fork. + +::: + +### Configure block time on an existing network deployment + +To update an existing network with a new `blockperiodseconds`: + +1. Stop all nodes in the network. +1. In the [genesis file](#genesis-file), add the `transitions` configuration item where: + + - `` is the upcoming block at which to change `blockperiodseconds`. + - `` is the updated value for `blockperiodseconds`. + + + + # Syntax + + ```bash + { + "config": { + ... + "ibft2": { + "blockperiodseconds": 2, + "epochlength": 30000, + "requesttimeoutseconds": 4 + }, + "transitions": { + "ibft2": [ + { + "block": , + "blockperiodseconds": + } + ] + } + }, + ... + } + ``` + + # Example + + ```bash + { + "config": { + ... + "ibft2": { + "blockperiodseconds": 2, + "epochlength": 30000, + "requesttimeoutseconds": 4 + }, + "transitions": { + "ibft2": [ + { + "block": 1240, + "blockperiodseconds": 4 + } + ] + } + }, + ... + } + ``` + + + +1. Restart all nodes in the network using the updated genesis file. +1. To verify the changes after the transition block, call [`ibft_getValidatorsByBlockNumber`](../../../../public-networks/reference/api/index.md#ibft_getvalidatorsbyblocknumber), specifying `latest`. + +### Configure block rewards on an existing network deployment + +To update an existing network with a new `blockreward`: + +1. Stop all nodes in the network. +1. In the [genesis file](#genesis-file), add the `transitions` configuration item where: + + - `` is the upcoming block at which to change `blockreward`. + - `` is the updated value for `blockreward`. + + + + # Syntax + + ```bash + { + "config": { + ... + "ibft2": { + "blockperiodseconds": 2, + "epochlength": 30000, + "requesttimeoutseconds": 4 + "blockreward": "5000000000000000" + }, + "transitions": { + "ibft2": [ + { + "block": , + "blockreward": + }, + { + "block": , + "blockreward": + }, + { + "block": , + "blockreward": + } + ] + } + }, + ... + } + ``` + + # Example + + ```bash + { + "config": { + ... + "ibft2": { + "blockperiodseconds": 2, + "epochlength": 30000, + "requesttimeoutseconds": 4 + "blockreward": "5000000000000000" + }, + "transitions": { + "ibft2": [ + { + "block": 10, + "blockreward": "6000000000000000" + }, + { + "block": 15, + "blockreward": "75000000000000000" + }, + { + "block": 20, + "blockreward": "0" + } + ] + } + }, + ... + } + ``` + + + + :::note + + You can add multiple `blockreward` updates in one transition object by specifying multiple future blocks. + + ::: + +1. Restart all nodes in the network using the updated genesis file. + +### Configure the mining beneficiary on an existing network deployment + +To update an existing network with a new mining beneficiary: + +1. Stop all nodes in the network. +1. In the [genesis file](#genesis-file), add the `transitions` configuration item where: + + - `` is the upcoming block at which to change `miningbeneficiary`. + - `` is the updated 20-byte address for `miningbeneficiary`. Starting at ``, block rewards go to this address. + + + + # Syntax + + ```bash + { + "config": { + "chainId": 999, + "berlinBlock": 0, + "ibft2": { + "blockperiodseconds": 1, + "epochlength": 30000, + "requesttimeoutseconds": 5, + "blockreward": "5000000000000000000", + "miningbeneficiary": "0x0000000000000000000000000000000000000001" + }, + "transitions": { + "ibft2": [ + { + "block": , + "miningbeneficiary": + }, + { + "block": , + "miningbeneficiary": + } + ] + } + }, + ... + } + ``` + + # Example + + ```bash + { + "config": { + "chainId": 999, + "berlinBlock": 0, + "ibft2": { + "blockperiodseconds": 1, + "epochlength": 30000, + "requesttimeoutseconds": 5, + "blockreward": "5000000000000000000", + "miningbeneficiary": "0x0000000000000000000000000000000000000001" + }, + "transitions": { + "ibft2": [ + { + "block": 10000, + "miningbeneficiary": "", + }, + { + "block": 20000, + "miningbeneficiary": "0x0000000000000000000000000000000000000002", + } + ] + } + }, + ... + } + ``` + + + + :::note + + Setting the `miningbeneficiary` to an empty value clears out any override so that block rewards go to the block producer rather than a global override address. + + ::: + +1. Restart all nodes in the network using the updated genesis file. + + + +_[vanity data]: Validators can include anything they like as vanity data. _[RLP]: Recursive Length Prefix + +``` + +``` diff --git a/versioned_docs/version-23.10.1/private-networks/how-to/configure/consensus/index.md b/versioned_docs/version-23.10.1/private-networks/how-to/configure/consensus/index.md new file mode 100644 index 00000000000..8ea4813a032 --- /dev/null +++ b/versioned_docs/version-23.10.1/private-networks/how-to/configure/consensus/index.md @@ -0,0 +1,81 @@ +--- +title: Consensus protocols +description: Besu consensus protocols +sidebar_position: 1 +tags: + - private networks +--- + +# Consensus protocols + +Besu supports the following consensus protocols: + +- [QBFT](qbft.md) (proof of authority) - The recommended enterprise-grade consensus protocol for private networks. +- [IBFT 2.0](ibft.md) (proof of authority) - Supported for existing private networks. +- [Clique](clique.md) (proof of authority) - Not recommended for production use. +- [Proof of stake](../../../../public-networks/concepts/proof-of-stake/index.md) - Used on Ethereum Mainnet and public testnets. +- [Ethash](https://ethereum.org/en/developers/docs/consensus-mechanisms/pow/) (proof of work) - Can be used in [small development networks](../../../tutorials/ethash.md). + +See a [comparison of the proof of authority consensus protocols](../../../concepts/poa.md). + +The `config` property in the genesis file specifies the consensus protocol for a chain. + + + +# Ethash + +```json +{ + "config": { + ... + "ethash": { + ... + } + }, + ... +} +``` + +# Clique + +```json +{ + "config": { + ... + "clique": { + ... + } + }, + ... +} +``` + +# IBFT 2.0 + +```json +{ + "config": { + ... + "ibft2": { + ... + } + }, + ... +} +``` + +# QBFT + +```json +{ + "config": { + ... + "qbft": { + ... + } + }, + ... +} +``` + + diff --git a/versioned_docs/version-23.10.1/private-networks/how-to/configure/consensus/qbft.md b/versioned_docs/version-23.10.1/private-networks/how-to/configure/consensus/qbft.md new file mode 100644 index 00000000000..727f2662887 --- /dev/null +++ b/versioned_docs/version-23.10.1/private-networks/how-to/configure/consensus/qbft.md @@ -0,0 +1,695 @@ +--- +title: QBFT +description: Hyperledger Besu QBFT proof of authority (PoA) consensus protocol implementation +sidebar_position: 2 +tags: + - private networks +--- + +# Configure QBFT consensus + +Hyperledger Besu implements the QBFT proof of authority (PoA) [consensus protocol](index.md). QBFT is the recommended enterprise-grade consensus protocol for private networks. + +In QBFT networks, approved accounts, known as validators, validate transactions and blocks. Validators take turns to create the next block. Before inserting the block onto the chain, a super-majority (greater than or equal to 2/3) of validators must first sign the block. + +Existing validators propose and vote to [add or remove validators](#add-and-remove-validators). + +You can [create a private network using QBFT](../../../tutorials/qbft.md). + +:::caution + +Configure your network to ensure you never lose more than 1/3 your validators. If more than 1/3 of validators stop participating, new blocks are no longer created, and the network stalls. It may take significant time to recover once nodes are restarted. + +::: + +:::tip + +You can use a plugin to securely store a validator's key using the [`--security-module`](../../../../public-networks/reference/cli/options.md#security-module) option. + +::: + +## Genesis file + +To use QBFT, define a [genesis file](../../../../public-networks/concepts/genesis-file.md) that contains the QBFT properties. + +The genesis file differs depending on the [validator management method](#add-and-remove-validators) you intend to use. + +:::note + +You can use a [transitions](#transitions) to change the `blockperiodseconds` or validator management method of the network at a later time. + +::: + + + +# Block header validator selection + +```json +{ + "config": { + "chainid": 1337, + "berlinBlock": 0, + "qbft": { + "epochlength": 30000, + "blockperiodseconds": 5, + "requesttimeoutseconds": 10 + } + }, + "nonce": "0x0", + "timestamp": "0x5b3d92d7", + "extraData": "0xf87aa00000000000000000000000000000000000000000000000000000000000000000f8549464a702e6263b7297a96638cac6ae65e6541f4169943923390ad55e90c237593b3b0e401f3b08a0318594aefdb9a738c9f433e5b6b212a6d62f6370c2f69294c7eeb9a4e00ce683cf93039b212648e01c6c6b78c080c0", + "gasLimit": "0x29b92700", + "difficulty": "0x1", + "mixHash": "0x63746963616c2062797a616e74696e65206661756c7420746f6c6572616e6365", + "coinbase": "0x0000000000000000000000000000000000000000", + "alloc": { + "64d9be4177f418bcf4e56adad85f33e3a64efe22": { + "balance": "0x446c3b15f9926687d2c40534fdb564000000000000" + }, + "9f66f8a0f0a6537e4a36aa1799673ea7ae97a166": { + "balance": "0x446c3b15f9926687d2c40534fdb564000000000000" + }, + "a7f25969fb6f3d5ac09a88862c90b5ff664557a7": { + "balance": "0x446c3b15f9926687d2c40534fdb564000000000000" + }, + "f4bbfd32c11c9d63e9b4c77bb225810f840342df": { + "balance": "0x446c3b15f9926687d2c40534fdb564000000000000" + } + }, + "number": "0x0", + "gasUsed": "0x0", + "parentHash": "0x0000000000000000000000000000000000000000000000000000000000000000" +} +``` + +# Contract validator selection + +```json +{ + "config": { + "chainid": 1337, + "berlinBlock": 0, + "qbft": { + "epochlength": 30000, + "blockperiodseconds": 5, + "requesttimeoutseconds": 10, + "validatorcontractaddress": "0x0000000000000000000000000000000000007777" + } + }, + "nonce": "0x0", + "timestamp": "0x5b3d92d7", + "extraData": "0xe5a00000000000000000000000000000000000000000000000000000000000000000c0c080c0", + "gasLimit": "0x29b92700", + "difficulty": "0x1", + "mixHash": "0x63746963616c2062797a616e74696e65206661756c7420746f6c6572616e6365", + "coinbase": "0x0000000000000000000000000000000000000000", + "alloc": { + "64d9be4177f418bcf4e56adad85f33e3a64efe22": { + "balance": "0x446c3b15f9926687d2c40534fdb564000000000000" + }, + "9f66f8a0f0a6537e4a36aa1799673ea7ae97a166": { + "balance": "0x446c3b15f9926687d2c40534fdb564000000000000" + }, + "a7f25969fb6f3d5ac09a88862c90b5ff664557a7": { + "balance": "0x446c3b15f9926687d2c40534fdb564000000000000" + }, + "f4bbfd32c11c9d63e9b4c77bb225810f840342df": { + "balance": "0x446c3b15f9926687d2c40534fdb564000000000000" + }, + "0x0000000000000000000000000000000000007777": { + "comment": "validator smart contract", + "balance": "0", + "code": "0x608060405234801561001057600080fd5b50600436106100a5576000357c0100000000000000000000000000000000000000000000000000000000900480639692ea25116100785780639692ea2514610113578063b4ec9ac114610126578063b7ab4db514610139578063c76f24371461014e57600080fd5b80631c5a9d9c146100aa578063508adcfc146100bf57806351b42b00146100db5780635dc43899146100e3575b600080fd5b6100bd6100b8366004611399565b610161565b005b6100c860035481565b6040519081526020015b60405180910390f35b6100bd6104aa565b6100f66100f1366004611399565b61074e565b6040805193845260208401929092521515908201526060016100d2565b6100bd610121366004611399565b610bbd565b6100bd610134366004611399565b610deb565b6101416110a3565b6040516100d291906113c9565b6100bd61015c366004611399565b611105565b3360009081526001602052604090205460ff1661019c5760405160e560020a62461bcd02815260040161019390611416565b60405180910390fd5b600160a060020a03811661021b5760405160e560020a62461bcd02815260206004820152602860248201527f63616e6e6f742061637469766174652076616c696461746f722077697468206160448201527f64647265737320300000000000000000000000000000000000000000000000006064820152608401610193565b60005b6000548110156102b7576000818154811061023b5761023b611505565b600091825260209091200154600160a060020a03838116911614156102a55760405160e560020a62461bcd02815260206004820152601b60248201527f76616c696461746f7220697320616c72656164792061637469766500000000006044820152606401610193565b806102af816114b8565b91505061021e565b33600090815260016020526040902054610100900460ff16156103345733600090815260016020526040812054815484929162010000900460ff1690811061030157610301611505565b9060005260206000200160006101000a815481600160a060020a030219169083600160a060020a03160217905550610432565b600054610100116103b05760405160e560020a62461bcd02815260206004820152602e60248201527f6e756d626572206f662076616c696461746f72732063616e6e6f74206265206c60448201527f6172676572207468616e203235360000000000000000000000000000000000006064820152608401610193565b3360009081526001602081905260408220805461ff001981166101009081178355845460ff16620100000262ffff001990921691909117179055815490810182559080527f290decd9548b62a8d60345a988386fc84ba6bc95484008f6362f93160ef3e563018054600160a060020a038416600160a060020a03199091161790555b600160a060020a0382166000818152600260205260408082208054600160a060020a03191633908117909155915490519192917fbdea108da876d927928b65816d521f940fd6dc068dc0e02ba434e0ed0f2d915f9161049e916001909182521515602082015260400190565b60405180910390a35050565b3360009081526001602052604090205460ff166104dc5760405160e560020a62461bcd02815260040161019390611416565b6000546001106105315760405160e560020a62461bcd02815260206004820181905260248201527f63616e6e6f742064656163746976617465206c6173742076616c696461746f726044820152606401610193565b33600090815260016020526040902054610100900460ff166105be5760405160e560020a62461bcd02815260206004820152602860248201527f73656e64657220646f6573206e6f74206861766520616e20616374697665207660448201527f616c696461746f720000000000000000000000000000000000000000000000006064820152608401610193565b336000908152600160205260408120805461ff0019169081905581546201000090910460ff1691908190839081106105f8576105f8611505565b60009182526020822001548154600160a060020a03909116925081906106209060019061148a565b8154811061063057610630611505565b60009182526020822001548154600160a060020a03909116925082919060ff861690811061066057610660611505565b60009182526020808320919091018054600160a060020a031916600160a060020a03948516179055838316825260028152604080832054909316825260019052908120805462ff000019166201000060ff8716021790558054806106c6576106c66114ec565b6000828152602080822060001990840181018054600160a060020a03199081169091559301909355600160a060020a03851680825260028452604080832080549094169093558154835190815293840191909152339290917fbdea108da876d927928b65816d521f940fd6dc068dc0e02ba434e0ed0f2d915f910160405180910390a3505050565b336000908152600160205260408120548190819060ff166107845760405160e560020a62461bcd02815260040161019390611416565b60005b600160a060020a03851660009081526004602052604090205481101561082357600160a060020a038516600090815260046020526040812080546001929190849081106107d6576107d6611505565b6000918252602080832090910154600160a060020a0316835282019290925260400190205460ff1615610811578361080d816114b8565b9450505b8061081b816114b8565b915050610787565b5060026003546108339190611465565b831115610b8657600160a060020a038416600090815260046020526040812061085b9161135f565b600160a060020a03841660009081526001602052604090205460ff1615610ab0576003805490600061088c836114a1565b9091555050600160a060020a038416600090815260016020526040902054610100900460ff1615610a89576000546001106109325760405160e560020a62461bcd02815260206004820152603860248201527f63616e6e6f742072656d6f766520616c6c6f776564206163636f756e7420776960448201527f7468206c617374206163746976652076616c696461746f7200000000000000006064820152608401610193565b600160a060020a03841660009081526001602052604081205481546201000090910460ff169160029181908490811061096d5761096d611505565b6000918252602080832090910154600160a060020a0316835282019290925260400181208054600160a060020a0319169055805481906109af9060019061148a565b815481106109bf576109bf611505565b60009182526020822001548154600160a060020a03909116925082919060ff85169081106109ef576109ef611505565b600091825260208220018054600160a060020a031916600160a060020a039390931692909217909155805480610a2757610a276114ec565b6000828152602080822083016000199081018054600160a060020a0319169055909201909255600160a060020a0392831682526002815260408083205490931682526001905220805460ff909216620100000262ff0000199092169190911790555b600160a060020a0384166000908152600160205260409020805462ffffff19169055610b32565b60038054906000610ac0836114b8565b909155505060408051606081018252600180825260006020808401828152848601838152600160a060020a038b16845293909152939020915182549351915160ff16620100000262ff0000199215156101000261ff00199215159290921661ffff199095169490941717169190911790555b600160a060020a03841660008181526001602090815260409182902054915160ff909216151582527f94154efdb7741591680558a88682943a481f1a468cb81f46fe7f8cead2e40519910160405180910390a25b826002600354610b969190611465565b610ba190600161144d565b6002600354610bb09190611465565b9196909550931192915050565b3360009081526001602052604090205460ff16610bef5760405160e560020a62461bcd02815260040161019390611416565b60005b600160a060020a038216600090815260046020526040902054811015610d4b57600160a060020a0382166000908152600460205260409020805433919083908110610c3f57610c3f611505565b600091825260209091200154600160a060020a03161415610d3957600160a060020a03821660009081526004602052604090208054610c809060019061148a565b81548110610c9057610c90611505565b6000918252602080832090910154600160a060020a03858116845260049092526040909220805491909216919083908110610ccd57610ccd611505565b60009182526020808320919091018054600160a060020a031916600160a060020a039485161790559184168152600490915260409020805480610d1257610d126114ec565b60008281526020902081016000199081018054600160a060020a0319169055019055610d4b565b80610d43816114b8565b915050610bf2565b50600160a060020a0381166000818152600460205260409020546003543392917f91ad81c76cda7c0ccc324838ae74757eab38b250da52daab154daf408cb3bcba91610d9990600290611465565b610da490600161144d565b600160a060020a0386166000908152600160208181526040928390205483519586529085019390935260ff909216159083015260608201526080015b60405180910390a350565b3360009081526001602052604090205460ff16610e1d5760405160e560020a62461bcd02815260040161019390611416565b600160a060020a038116610e765760405160e560020a62461bcd02815260206004820152601f60248201527f6163636f756e7420746f2062652061646465642063616e6e6f742062652030006044820152606401610193565b600160a060020a03811660009081526001602081905260409091205460ff16151514610f0d5760405160e560020a62461bcd02815260206004820152602a60248201527f6163636f756e7420746f2072656d6f7665206973206e6f74206f6e207468652060448201527f616c6c6f77206c697374000000000000000000000000000000000000000000006064820152608401610193565b60005b600160a060020a038216600090815260046020526040902054811015610ffb57600160a060020a0382166000908152600460205260409020805433919083908110610f5d57610f5d611505565b600091825260209091200154600160a060020a03161415610fe95760405160e560020a62461bcd02815260206004820152602a60248201527f73656e6465722068617320616c726561647920766f74656420746f2072656d6f60448201527f7665206163636f756e74000000000000000000000000000000000000000000006064820152608401610193565b80610ff3816114b8565b915050610f10565b50600160a060020a0381166000818152600460209081526040822080546001810182558184529183209091018054600160a060020a0319163390811790915591839052546003549192917f91ad81c76cda7c0ccc324838ae74757eab38b250da52daab154daf408cb3bcba919061107490600290611465565b61107f90600161144d565b60408051928352602083019190915260009082018190526060820152608001610de0565b606060008054806020026020016040519081016040528092919081815260200182805480156110fb57602002820191906000526020600020905b8154600160a060020a031681526001909101906020018083116110dd575b5050505050905090565b3360009081526001602052604090205460ff166111375760405160e560020a62461bcd02815260040161019390611416565b600160a060020a03811660009081526001602052604090205460ff16156111c95760405160e560020a62461bcd02815260206004820152602b60248201527f6163636f756e7420746f2061646420697320616c7265616479206f6e2074686560448201527f20616c6c6f77206c6973740000000000000000000000000000000000000000006064820152608401610193565b60005b600160a060020a0382166000908152600460205260409020548110156112b757600160a060020a038216600090815260046020526040902080543391908390811061121957611219611505565b600091825260209091200154600160a060020a031614156112a55760405160e560020a62461bcd02815260206004820152602760248201527f73656e6465722068617320616c726561647920766f74656420746f206164642060448201527f6163636f756e74000000000000000000000000000000000000000000000000006064820152608401610193565b806112af816114b8565b9150506111cc565b50600160a060020a0381166000818152600460209081526040822080546001810182558184529183209091018054600160a060020a0319163390811790915591839052546003549192917f91ad81c76cda7c0ccc324838ae74757eab38b250da52daab154daf408cb3bcba919061133090600290611465565b61133b90600161144d565b60408051928352602083019190915260019082015260006060820152608001610de0565b508054600082559060005260206000209081019061137d9190611380565b50565b5b808211156113955760008155600101611381565b5090565b6000602082840312156113ab57600080fd5b8135600160a060020a03811681146113c257600080fd5b9392505050565b6020808252825182820181905260009190848201906040850190845b8181101561140a578351600160a060020a0316835292840192918401916001016113e5565b50909695505050505050565b6020808252601f908201527f73656e646572206973206e6f74206f6e2074686520616c6c6f77206c69737400604082015260600190565b60008219821115611460576114606114d3565b500190565b6000826114855760e060020a634e487b7102600052601260045260246000fd5b500490565b60008282101561149c5761149c6114d3565b500390565b6000816114b0576114b06114d3565b506000190190565b60006000198214156114cc576114cc6114d3565b5060010190565b60e060020a634e487b7102600052601160045260246000fd5b60e060020a634e487b7102600052603160045260246000fd5b60e060020a634e487b7102600052603260045260246000fdfea26469706673582212200c3e9c07521b155532c0de1605aae52f4ae953670f0afb0f30d320580b93213d64736f6c63430008070033", + "storage": { + "0000000000000000000000000000000000000000000000000000000000000000": "0000000000000000000000000000000000000000000000000000000000000002", + "290decd9548b62a8d60345a988386fc84ba6bc95484008f6362f93160ef3e563": "0000000000000000000000009a6d82ef3912d5ab60473124bccd2f2a640769d7", + "290decd9548b62a8d60345a988386fc84ba6bc95484008f6362f93160ef3e564": "00000000000000000000000065463bf6268e5cc409b6501ec846487b935a1446", + "aedead2c33b41c31b4afd2246c6bf5131c209d4b0ca6c2247778ac7be7443a00": "0000000000000000000000000000000000000000000000000000000000000101", + "33784757d5da236467d27a7c5b0cc5aa9026ca3b79e29106a67a5e93c292a523": "0000000000000000000000000000000000000000000000000000000000010101", + "35aba1eb0bbe741ac01e5b6ce584bc042b1a0b7d115eb8f7dd02a1a1de2fd14d": "000000000000000000000000fe3b557e8fb62b89f4916b721be55ceb828dbd73", + "0d9217f0a1f7c602fd67052d20171ff73b156d1b87ea258cb6a5d94f71298158": "000000000000000000000000627306090abab3a6e1400e9345bc60c78a8bef57", + "0000000000000000000000000000000000000000000000000000000000000003": "0000000000000000000000000000000000000000000000000000000000000002" + }, + "version": "0x01" + } + }, + "number": "0x0", + "gasUsed": "0x0", + "parentHash": "0x0000000000000000000000000000000000000000000000000000000000000000" +} +``` + + + +The QBFT properties are: + +- `blockperiodseconds` - The minimum block time, in seconds. +- `epochlength` - The number of blocks after which to reset all votes. +- `requesttimeoutseconds` - The timeout for each consensus round before a round change, in seconds. +- `blockreward` - Optional reward amount in Wei to reward the beneficiary. Defaults to zero (0). Can be specified as a hexadecimal (with 0x prefix) or decimal string value. If set, then all nodes on the network must use the identical value. +- `validatorcontractaddress` - Address of the validator smart contract. Required only if using a contract validator selection. The address must be identical to the address in the `alloc` section. This option can also be used in the [transitions](#transitions) configuration item if swapping [validator management methods](#add-and-remove-validators) in an existing network. +- `miningbeneficiary` - Optional beneficiary of the `blockreward`. Defaults to the validator that proposes the block. If set, then all nodes on the network must use the same beneficiary. +- [`extraData`](#extra-data) - RLP encoded [extra data](#extra-data). + +:::caution + +We don't recommend changing `epochlength` in a running network. Changing the `epochlength` after genesis can result in illegal blocks. + +::: + +:::caution Invalid block header error + +When adding a new node, if a `TimeStampMoreRecentThanParent | Invalid block header` error occurs, the genesis file of the new node specifies a higher `blockperiodseconds` than the imported chain. The imported chain makes new blocks faster than the genesis file allows and Besu rejects them with this error. This error most often occurs when importing chains from older versions of Besu. + +Decrease the `blockperiodseconds` in the new QBFT genesis file to a lower value that satisfies the block header validation. + +If the error reads `| TimestampMoreRecentThanParent | Invalid block header: timestamp 1619660141 is only 3 seconds newer than parent timestamp 1619660138. Minimum 4 seconds`, decrease the `blockperiodseconds` from 4 seconds to 3 seconds to match the imported chain. + +After you update the new genesis file, if the imported chain has a `blockperiodseconds` value set lower than you prefer, you can adjust it by [configuring the block time on an existing QBFT network](#configure-block-time-on-an-existing-network). + +::: + +The properties with specific values in the QBFT genesis files are: + +- `difficulty` - `0x1` +- `mixHash` - `0x63746963616c2062797a616e74696e65206661756c7420746f6c6572616e6365` for Istanbul block identification + +To start a node on a QBFT private network, use the [`--genesis-file`](../../../../public-networks/reference/cli/options.md#genesis-file) option to specify the custom genesis file. + +### Extra data + +The `extraData` property is an RLP encoding of: + +- 32 bytes of vanity data. +- If using: + - [Block header validator selection](#add-and-remove-validators-using-block-headers), a list of validator addresses. + - [Contract validator selection](#add-and-remove-validators-using-a-smart-contract), no validators. +- Any validator votes. No vote is included in the genesis block. +- The round the block was created on. The round in the genesis block is 0. +- A list of seals of the validators (signed block hashes). No seals are included in the genesis block. + +When using block header validator selection, the important information in the genesis block extra data is the list of validators. All other details have empty values in the genesis block. + +:::info + +When using contract validator selection to manage validators, the list of validators is configured in the `alloc` property's `storage` section. View the example smart contract for more information on how to generate the `storage` section. + +::: + +Formally, `extraData` in the genesis block contains: + +- If using block header validator selection: `RLP([32 bytes Vanity, List, No Vote, Round=Int(0), 0 Seals])`. +- If using contract validator selection: `RLP([32 bytes Vanity, 0 Validators, No Vote, Round=Int(0), 0 Seals])`. + +:::info + +RLP encoding is a space-efficient object serialization scheme used in Ethereum. + +::: + +#### Generate extra data + +To generate the `extraData` RLP string for inclusion in the genesis file, use the [`rlp encode`](../../../reference/cli/subcommands.md#rlp) Besu subcommand. + +```bash title="Example" +besu rlp encode --from=toEncode.json --type=QBFT_EXTRA_DATA +``` + +Where the `toEncode.json` file contains a list of the initial validators, in ascending order. To write the validator address and copy it to the `toEncode.json` file, use the [`public-key export-address`](../../../../public-networks/reference/cli/subcommands.md#export-address) Besu subcommand. For example: + +```json title="Initial validators in toEncode.json file" +[ + "0x4592c8e45706cc08b8f44b11e43cba0cfc5892cb", + "0x06e23768a0f59cf365e18c2e0c89e151bcdedc70", + "0xc5327f96ee02d7bcbc1bf1236b8c15148971e1de", + "0xab5e7f4061c605820d3744227eed91ff8e2c8908" +] +``` + +Copy the RLP encoded data to the `extraData` property in the genesis file. + +```bash title="RLP encoded data" +0xf87aa00000000000000000000000000000000000000000000000000000000000000000f854944592c8e45706cc08b8f44b11e43cba0cfc5892cb9406e23768a0f59cf365e18c2e0c89e151bcdedc7094c5327f96ee02d7bcbc1bf1236b8c15148971e1de94ab5e7f4061c605820d3744227eed91ff8e2c8908c080c0 +``` + +When you start the network, the four nodes previously specified in `toEncode.json` are the validators for the network. + +### Block time + +When the protocol receives a new chain head, the block time (`blockperiodseconds`) timer starts. When `blockperiodseconds` expires, the round timeout (`requesttimeoutseconds`) timer starts and the protocol proposes a new block. + +If `requesttimeoutseconds` expires before adding the proposed block, a round change occurs, with the block time and timeout timers reset. The timeout period for the new round is two times `requesttimeoutseconds`. The timeout period continues to double each time a round fails to add a block. + +Usually, the protocol adds the proposed block before reaching `requesttimeoutseconds`. A new round then starts, resetting the block time and round timeout timers. When `blockperiodseconds` expires, the protocol proposes the next new block. + +:::danger + +If more than 1/3 of validators stop participating, new blocks can no longer be created and `requesttimeoutseconds` doubles with each round change. The quickest method to resume block production is to restart all validators, which resets `requesttimeoutseconds` to its genesis value. + +::: + +Once `blockperiodseconds` is over, the time from proposing a block to adding the block is small (usually around one second) even in networks with geographically dispersed validators. + +#### Tune block timeout + +To tune the block timeout for your network deployment: + +1. Set `blockperiodseconds` to your desired block time and `requesttimeoutseconds` to two times `blockperiodseconds`. +1. Reduce `requesttimeoutseconds` until you start to see round changes occurring. +1. Increase `requesttimeoutseconds` to the value where round changes are no longer occurring. + +:::tip + +View [`TRACE` logs](../../../../public-networks/reference/api/index.md#admin_changeloglevel) to see round change log messages. + +::: + +Use a [transition](#transitions) to update the `blockperiodseconds` in an existing network. + +### Optional configuration options + +Optional configuration options in the genesis file are: + +- `messageQueueLimit` - In large networks with limited resources, increasing the message queue limit might help with message activity surges. The default is 1000. +- `duplicateMessageLimit` - If the same node is retransmitting messages, increasing the duplicate message limit might reduce the number of retransmissions. A value of two to three times the number of validators is usually enough. The default is 100. +- `futureMessagesLimit` - The future messages buffer holds messages for a future chain height. For large networks, increasing the future messages limit might be useful. The default is 1000. +- `futureMessagesMaxDistance` - The maximum height from the current chain height for buffering messages in the future messages buffer. The default is 10. + +### Post-Merge configuration + +After [The Merge](../../../../public-networks/concepts/the-merge.md), the following block fields are modified or deprecated. Their fields **must** contain only the constant values from the following chart. + +| Field | Constant value | Comment | +| --- | --- | --- | +| **`ommersHash`** | `0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347` | `= Keccak256(RLP([]))` | +| **`difficulty`** | `0` | Replaced with `prevrandao` | +| **`mixHash`** | `0x0000000000000000000000000000000000000000000000000000000000000000` | Replaced with `prevrandao` | +| **`nonce`** | `0x0000000000000000` | | +| **`ommers`** | `[]` | `RLP([]) = 0xc0` | + +Additionally, [`extraData`](#extra-data) is limited to the 32 bytes of vanity data after The Merge. + +## Add and remove validators + +QBFT provides two methods to manage validators: + +- [Block header validator selection](#add-and-remove-validators-using-block-headers) - Existing validators propose and vote to add or remove validators using the QBFT JSON-RPC API methods. + +- [Contract validator selection](#add-and-remove-validators-using-a-smart-contract) - Use a smart contract to specify the validators used to propose and validate blocks. + +You can use [transitions](#transitions) to swap between block header validator selection and contract validator selection in an existing network. + +For block header validator selection, initial validators are configured in the genesis file's [`extraData`](#extra-data) property, whereas the initial validators when using the contract validator selection method are configured in the genesis file's `storage` section. + +### Add and remove validators using block headers + +Enable the HTTP interface with [`--rpc-http-enabled`](../../../../public-networks/reference/cli/options.md#rpc-http-enabled) or the WebSockets interface with [`--rpc-ws-enabled`](../../../../public-networks/reference/cli/options.md#rpc-ws-enabled). + +The QBFT API methods are disabled by default. To enable them, specify the [`--rpc-http-api`](../../../../public-networks/reference/cli/options.md#rpc-http-api) or [`--rpc-ws-api`](../../../../public-networks/reference/cli/options.md#rpc-ws-api) option and include `QBFT`. + +The methods to add or remove validators are: + +- [`qbft_getPendingVotes`](../../../reference/api/index.md#qbft_getpendingvotes). +- [`qbft_proposeValidatorVote`](../../../reference/api/index.md#qbft_proposevalidatorvote). +- [`qbft_discardValidatorVote`](../../../reference/api/index.md#qbft_discardvalidatorvote). + +To view validator metrics for a specified block range, use [`qbft_getSignerMetrics`](../../../reference/api/index.md#qbft_getsignermetrics). + +:::note + +If network conditions render it impossible to add and remove validators by voting, you can [add and remove validators without voting](add-validators-without-voting.md). + +::: + +#### Add a validator + +To propose adding a validator, call [`qbft_proposeValidatorVote`](../../../reference/api/index.md#qbft_proposevalidatorvote), specifying the address of the proposed validator and `true`. A majority of validators must execute the call. + +```bash title="JSON-RPC qbft_proposeValidatorVote request example" +curl -X POST --data '{"jsonrpc":"2.0","method":"qbft_proposeValidatorVote","params":["0xFE3B557E8Fb62b89F4916B721be55cEb828dBd73", true], "id":1}' +``` + +When the validator proposes the next block, the protocol inserts one proposal received from [`qbft_proposeValidatorVote`](../../../reference/api/index.md#qbft_proposevalidatorvote) into the block. If blocks include all proposals, subsequent blocks proposed by the validator will not contain a vote. + +When more than 50% of the existing validators have published a matching proposal, the protocol adds the proposed validator to the validator pool and the validator can begin validating blocks. + +To return a list of validators and confirm the addition of a proposed validator, use [`qbft_getValidatorsByBlockNumber`](../../../reference/api/index.md#qbft_getvalidatorsbyblocknumber). + +```bash title="JSON-RPC qbft_getValidatorsByBlockNumber request example" +curl -X POST --data '{"jsonrpc":"2.0","method":"qbft_getValidatorsByBlockNumber","params":["latest"], "id":1}' +``` + +To discard your proposal after confirming the addition of a validator, call [`qbft_discardValidatorVote`](../../../reference/api/index.md#qbft_discardvalidatorvote), specifying the address of the proposed validator. + +```bash title="JSON-RPC qbft_discardValidatorVote request example" +curl -X POST --data '{"jsonrpc":"2.0","method":"qbft_discardValidatorVote","params":["0xFE3B557E8Fb62b89F4916B721be55cEb828dBd73"], "id":1}' +``` + +#### Remove a validator + +The process for removing a validator is the same as adding a validator except you specify `false` as the second parameter of [`qbft_proposeValidatorVote`](../../../reference/api/index.md#qbft_proposevalidatorvote). + +#### Epoch transition + +At each epoch transition, QBFT discards all pending votes collected from received blocks. Existing proposals remain in effect and validators re-add their vote the next time they create a block. + +An epoch transition occurs every `epochLength` blocks. Define `epochlength` in the QBFT genesis file. + +### Add and remove validators using a smart contract + +Users can create their own smart contracts to add or remove validators based on their organizational requirements. View the [example smart contract](https://github.com/ConsenSys/validator-smart-contracts) for more information on how to create and deploy the smart contract. + +You can pre-deploy the validator smart contract in a new QBFT network by specifying the contract details in the [genesis file](qbft.md#genesis-file). For existing QBFT networks you need to compile and deploy the contract using a transaction, then obtain the contract address from the receipt and use that in a [transition](#swap-validator-management-methods). + +:::info + +You can't use the JSON-RPC methods to add or remove validators when using a smart contract to manage nodes. + +You must interact with the contract functions using transactions. + +::: + +:::note + +If network conditions render it impossible to add and remove validators using a smart contract, you can [override smart contract validators](add-validators-without-voting.md#override-smart-contract-validators). + +::: + +### Minimum number of validators + +QBFT requires four validators to be Byzantine fault tolerant. Byzantine fault tolerance is the ability for a blockchain network to function correctly and reach consensus despite nodes failing or propagating incorrect information to peers. + +## Transitions + +The `transitions` genesis configuration item allows you to specify a future block number at which to change QBFT network configuration in an existing network. For example, you can update the [block time](#configure-block-time-on-an-existing-network), [block reward](#configure-block-rewards-on-an-existing-network-deployment), [validator management method](#swap-validator-management-methods), or [mining beneficiary](#configure-the-mining-beneficiary-on-an-existing-network-deployment). + +:::caution + +Do not specify a transition block in the past. Specifying a transition block in the past could result in unexpected behavior, such as causing the network to fork. + +::: + +### Configure block time on an existing network + +To update an existing network with a new `blockperiodseconds`: + +1. Stop all nodes in the network. +2. In the [genesis file](#genesis-file), add the `transitions` configuration item where: + + - `` is the upcoming block at which to change `blockperiodseconds`. + - `` is the updated value for `blockperiodseconds`. + + + + # Syntax + + ```bash + { + "config": { + ... + "qbft": { + "blockperiodseconds": 2, + "epochlength": 30000, + "requesttimeoutseconds": 4 + }, + "transitions": { + "qbft": [ + { + "block": , + "blockperiodseconds": + } + ] + } + }, + ... + } + ``` + + # Example + + ```bash + { + "config": { + ... + "qbft": { + "blockperiodseconds": 2, + "epochlength": 30000, + "requesttimeoutseconds": 4 + }, + "transitions": { + "qbft": [ + { + "block": 1240, + "blockperiodseconds": 4 + } + ] + } + }, + ... + } + ``` + + + +3. Restart all nodes in the network using the updated genesis file. +4. To verify the changes after the transition block, call [`qbft_getValidatorsByBlockNumber`](../../../reference/api/index.md#ibft_getvalidatorsbyblocknumber), specifying `latest`. + +### Configure block rewards on an existing network deployment + +To update an existing network with a new `blockreward`: + +1. Stop all nodes in the network. +2. In the [genesis file](#genesis-file), add the `transitions` configuration item where: + + - `` is the upcoming block at which to change `blockreward`. + - `` is the updated value for `blockreward`. + + + + # Syntax + + ```bash + { + "config": { + ... + "qbft": { + "blockperiodseconds": 2, + "epochlength": 30000, + "requesttimeoutseconds": 4 + "blockreward": "5000000000000000" + }, + "transitions": { + "qbft": [ + { + "block": , + "blockreward": + }, + { + "block": , + "blockreward": + }, + { + "block": , + "blockreward": + } + ] + } + }, + ... + } + ``` + + # Example + + ```bash + { + "config": { + ... + "qbft": { + "blockperiodseconds": 2, + "epochlength": 30000, + "requesttimeoutseconds": 4 + "blockreward": "5000000000000000" + }, + "transitions": { + "qbft": [ + { + "block": 10, + "blockreward": "6000000000000000" + }, + { + "block": 15, + "blockreward": "75000000000000000" + }, + { + "block": 20, + "blockreward": "0" + } + ] + } + }, + ... + } + ``` + + + + :::note + + You can add multiple `blockreward` updates in one transition object by specifying multiple future blocks. + + ::: + +3. Restart all nodes in the network using the updated genesis file. + +### Swap validator management methods + +To swap between block header validator selection and contract validator selection methods in an existing network: + +1. Stop all nodes in the network. +2. In the [genesis file](#genesis-file), add the `transitions` configuration item where: + + - `` is the upcoming block at which to change the validator selection method. + - `` is the validator selection mode to switch to. Valid options are `contract` and `blockheader`. + - `` is the smart contract address, if switching to the contract validator selection method. + + + + # Syntax + + ```bash + { + "config": { + ... + "qbft": { + "blockperiodseconds": 5, + "epochlength": 30000, + "requesttimeoutseconds": 10 + }, + "transitions": { + "qbft": [ + { + "block": , + "validatorselectionmode": , + "validatorcontractaddress": + } + ] + } + }, + ... + } + ``` + + # Example + + ```bash + { + "config": { + ... + "qbft": { + "blockperiodseconds": 5, + "epochlength": 30000, + "requesttimeoutseconds": 10 + }, + "transitions": { + "qbft": [ + { + "block": 102885, + "validatorselectionmode": "contract", + "validatorcontractaddress": "0x0000000000000000000000000000000000007777" + } + ] + } + }, + ... + } + ``` + + + +3. Restart all nodes in the network using the updated genesis file. + +### Configure the mining beneficiary on an existing network deployment + +To update an existing network with a new mining beneficiary: + +1. Stop all nodes in the network. +2. In the [genesis file](#genesis-file), add the `transitions` configuration item where: + + - `` is the upcoming block at which to change `miningbeneficiary`. + - `` is the updated 20-byte address for `miningbeneficiary`. Starting at ``, block rewards go to this address. + + + + # Syntax + + ```bash + { + "config": { + ... + "qbft": { + "blockperiodseconds": 5, + "epochlength": 30000, + "requesttimeoutseconds": 10 + }, + "transitions": { + "qbft": [ + { + "block": , + "miningbeneficiary": + }, + { + "block": , + "miningbeneficiary": + } + ] + } + }, + ... + } + ``` + + # Example + + ```bash + { + "config": { + ... + "qbft": { + "blockperiodseconds": 5, + "epochlength": 30000, + "requesttimeoutseconds": 10 + }, + "transitions": { + "qbft": [ + { + "block": 10000, + "miningbeneficiary": "0x0000000000000000000000000000000000000002", + }, + { + "block": 20000, + "miningbeneficiary": "", + } + ] + } + }, + ... + } + ``` + + + + :::note + + Setting the `miningbeneficiary` to an empty value clears out any override so that block rewards go to the block producer rather than a global override address. + + ::: + +3. Restart all nodes in the network using the updated genesis file. + + + +_[vanity data]: Validators can include anything they like as vanity data. _[RLP]: Recursive Length Prefix + +[GoQuorum]: https://consensys.net/docs/goquorum/en/stable/ +[View the example smart contract]: https://github.com/ConsenSys/validator-smart-contracts diff --git a/versioned_docs/version-23.10.1/private-networks/how-to/configure/contracts.md b/versioned_docs/version-23.10.1/private-networks/how-to/configure/contracts.md new file mode 100644 index 00000000000..a38c58e3894 --- /dev/null +++ b/versioned_docs/version-23.10.1/private-networks/how-to/configure/contracts.md @@ -0,0 +1,39 @@ +--- +title: Pre-deploy a contract +description: Pre-deploying contracts in the genesis file +sidebar_position: 5 +tags: + - private networks +--- + +# Pre-deploy contracts in the genesis file + +To pre-deploy contracts when starting Besu, specify the contract code in the [genesis file](../../../public-networks/concepts/genesis-file.md). + +:::tip Contract code in the genesis file + +```json +{ + ... + "alloc": { + "0x0ffd23af8eebc60b3cfdeed6f814988757237314": { + "balance": "0x100000000000000000000000000000000000000000000000000", + "code": "0x6080604052600436106043576000357c010000000000000000000000000000000000000000000000000000000090048063010fc84214604857806355241077146070575b600080fd5b348015605357600080fd5b50605a60a7565b6040518082815260200191505060405180910390f35b348015607b57600080fd5b5060a560048036036020811015609057600080fd5b810190808035906020019092919050505060ad565b005b60005481565b80600081905550807f04474795f5b996ff80cb47c148d4c5ccdbe09ef27551820caa9c2f8ed149cce360405160405180910390a25056fea165627a7a7230582038cb7ea327af8f73feabcfbff64498f1e74831e67f7c75286760d3845c6747c70029", + "storage": { + "7aa07e0c924147697605046b7c2c32645b7bbfb41e0ac5d0a84ac93cbb759798": "0000000000000000000000000000000000000000000000000000000000000001", + "cea2b0602db61f92b76ec4402875cc38eedc9fc425cb1b697fc2265d50fc20fb": "0000000000000000000000000000000000000000000000000000000000000001", + } + } + }, + ... +} +``` + +::: + +The contract code in the genesis file defines the: + +- Address. +- Balance. +- Bytecode. +- Key value pairs for contract storage. diff --git a/versioned_docs/version-23.10.1/private-networks/how-to/configure/curves.md b/versioned_docs/version-23.10.1/private-networks/how-to/configure/curves.md new file mode 100644 index 00000000000..72edb764a18 --- /dev/null +++ b/versioned_docs/version-23.10.1/private-networks/how-to/configure/curves.md @@ -0,0 +1,41 @@ +--- +title: Alternative elliptic curves +description: Using alternative elliptic curves in Besu +sidebar_position: 8 +tags: + - private networks +--- + +# Configure alternative elliptic curves + +:::caution + +Configuring alternative elliptic curves is an early access feature. + +::: + +By default, Besu uses the Ethereum standard `secp256k1` elliptic curve (EC). However, when running nodes in a private network, it is possible to configure an alternative elliptic curve. + +The configuration for what elliptic curve Besu will use is done in the network configuration section of genesis file, using the [`ecCurve`](../../../public-networks/reference/genesis-items.md#Configuration_Items) key: + +```bash +{ + "genesis": { + "config": { + "ecCurve": "secp256k1", + [...] + }, + [...] +} +``` + +:::danger Important + +All nodes in the network **MUST** use the same elliptic curve. Nodes with different EC configuration from the network won't be able to send messages to other nodes or verify transactions and blocks. + +::: + +Besu supports the following elliptic curves: + +- `secp256k1` (Ethereum default) +- `secp256r1` diff --git a/versioned_docs/version-23.10.1/private-networks/how-to/configure/free-gas.md b/versioned_docs/version-23.10.1/private-networks/how-to/configure/free-gas.md new file mode 100644 index 00000000000..9eccfd2666d --- /dev/null +++ b/versioned_docs/version-23.10.1/private-networks/how-to/configure/free-gas.md @@ -0,0 +1,136 @@ +--- +title: Free gas network +description: Configuring free gas networks +sidebar_position: 2 +tags: + - private networks +--- + +# Configure free gas networks + +Transactions use computational resources so have an associated cost. Gas is the cost unit and the gas price is the price per gas unit. The transaction cost is the gas used \* gas price. + +In public networks, the account submitting the transaction pays the transaction cost, in Ether. The miner (or validator in PoA networks) that includes the transaction in a block receives transaction cost. + +In many private networks, network participants run the validators and do not require gas as an incentive. Networks that don't require gas as an incentive usually configure the gas price to be zero (that is, free gas). Some private networks might allocate Ether and use a non-zero gas price to limit resource use. + +:::tip + +We use the term _free gas network_ to refer to a network with a gas price of zero. A network with a gas price of zero is also known as a _zero gas network_ or _no gas network_. + +::: + +:::note + +Some pre-crafted transactions require the deployment account to have gas available. For example, the transaction that creates the smart contract in [EIP-1820](https://eips.ethereum.org/EIPS/eip-1820). + +::: + +In a free gas network, transactions still use gas but the gas price is zero, meaning the transaction cost is zero. Transaction cost = gas used \* 0 (the gas price). + +## Configure free gas in Besu + +When gas is free, limiting block and contract sizes is less important. In free gas networks, we increase the block size limit and set the contract size limit to the maximum value. + +### 1. Set the block size + +If you want to remove gas from consideration and don't mind blocks potentially taking longer to create, in the genesis file set the block size limit (measured in gas) to the maximum accepted by Hardhat (`0x1fffffffffffff`). In the genesis file, specify `gasLimit` following the `config` key. + +```json +{ + "config": { + .... + }, + ... + "gasLimit": "0x1fffffffffffff", + .... +} +``` + +If you are more concerned about blocks arriving on time and don't have expensive individual transactions, set `gasLimit` to a value closer to the amount of gas your validators can process in the configured block time. + +### 2. Set the contract size + +In the `config` section of the genesis file, set the contract size limit to the maximum supported size (in bytes). + +```json +( + "config": { + ... + "contractSizeLimit": 2147483647, + ... + } + ... +} +``` + +### 3. Start Besu with a minimum gas price of zero + +When starting nodes, set the [minimum gas price](../../../public-networks/reference/cli/options.md#min-gas-price) to zero. + + + +# Command Line + +```bash +--min-gas-price=0 +``` + +# Configuration File + +```bash +min-gas-price=0 +``` + + + +# Command Line + +:::danger Important + +In a free gas network, ensure the [minimum gas price](../../../public-networks/reference/cli/options.md#min-gas-price) is set to zero for every node. Any node with a minimum gas price set higher than zero will silently drop transactions with a zero gas price. You can query a node's gas configuration using [`eth_gasPrice`](../../../public-networks/reference/api/index.md#eth_gasprice). + +::: + +### 4. Enable zero base fee if using London fork or later + +If your network is configured to use the `londonBlock` or a later hard fork, then you must also enable the `zeroBaseFee` configuration. You must set this on all your nodes. Once it is set, future blocks produced by that node will set a `baseFee` of 0. This is required because the London hard fork (EIP-1559) introduced a non-zero `baseFee` into the block which normally means transactions require gas. + +```json +{ + "config": { + "londonBlock": 0, + "zeroBaseFee": true, + ... + }, + ... +} +``` + +## Configure free gas in Hardhat + +If using Hardhat to develop on your free gas network, you also need to configure free gas in Hardhat. + +Like setting block and contract size limits to their maximum values for Besu, set the transaction gas limit in Hardhat to the maximum possible. + +:::info + +Besu does not support private key management. To use Besu with Hardhat, you must configure a [Hardhat wallet](../../../public-networks/how-to/develop/hardhat.md). + +::: + +### Update `hardhat.config.js` + +Update the `hardhat.config.js` file: + +1. Set the gas price to zero. + + ```js + gasPrice: 0; + ``` + +1. Set the gas limit for a transaction (that is, contract creation) to be the block gas limit - 1. + + ```js + gas: "0x1ffffffffffffe"; + ``` diff --git a/versioned_docs/version-23.10.1/private-networks/how-to/configure/tls/_category_.json b/versioned_docs/version-23.10.1/private-networks/how-to/configure/tls/_category_.json new file mode 100644 index 00000000000..dbda63e2b5b --- /dev/null +++ b/versioned_docs/version-23.10.1/private-networks/how-to/configure/tls/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "TLS", + "position": 6 +} diff --git a/versioned_docs/version-23.10.1/private-networks/how-to/configure/tls/client-and-server.md b/versioned_docs/version-23.10.1/private-networks/how-to/configure/tls/client-and-server.md new file mode 100644 index 00000000000..5ee1722415d --- /dev/null +++ b/versioned_docs/version-23.10.1/private-networks/how-to/configure/tls/client-and-server.md @@ -0,0 +1,119 @@ +--- +title: Client and server TLS +sidebar_position: 1 +tags: + - private networks +--- + +# Configure client and server TLS + +Hyperledger Besu supports TLS for client and server communication. For example, you can configure TLS for communication between [EthSigner](https://docs.ethsigner.consensys.net/en/latest/Concepts/TLS/) and Besu, and Besu and [Tessera](https://docs.tessera.consensys.net/HowTo/Configure/TLS/). + +The following diagram displays an example client and server TLS configuration. + +![Besu client and server TLS](../../../../assets/images/Besu_TLS.png) + +Configure TLS communication from the command line. + +## Prerequisites + +- Besu's password-protected PKCS12 keystore +- File containing the keystore password + +## Configure client TLS + +Allow clients (for example a dapp, curl, or EthSigner) to send and receive secure HTTP JSON-RPCs. + +**Client prerequisites**: + +- [Configure the client for TLS] +- Client's PKCS12 keystore information + +### Create the known clients file + +The known clients file allows clients with self-signed certificates or non-public certificates to connect to Besu. + +Create a file (in this example, `knownClients`) that lists one or more trusted clients. Use the format` ` where: + +- `` is the Common Name specified in the client certificate. +- `` is the SHA-256 fingerprint of the client certificate. + +```bash title="Example" +ethsigner 8E:E0:85:9F:FC:2E:2F:21:31:46:0B:82:4C:A6:88:AB:30:34:9A:C6:EA:4F:04:31:ED:0F:69:A7:B5:C2:2F:A7 +curl FC:18:BF:39:45:45:9A:15:46:76:A6:E7:C3:94:64:B8:34:84:A3:8E:B8:EA:67:DC:61:C0:29:E6:38:B8:B7:99 +``` + +You can use [`openssl`](https://www.openssl.org/) or [`keytool`](https://docs.oracle.com/javase/6/docs/technotes/tools/solaris/keytool.html) to display the SHA256 fingerprint. + +``` +keytool -list -v -keystore -storetype PKCS12 -storepass `. +``` + +### Start Besu + +```bash +besu --rpc-http-enabled --rpc-http-tls-enabled --rpc-http-tls-client-auth-enabled --rpc-http-tls-keystore-file=/Users/me/my_node/keystore.pfx --rpc-http-tls-keystore-password-file=/Users/me/my_node/keystorePassword --rpc-http-tls-known-clients-file=/Users/me/my_node/knownClients --rpc-http-tls-cipher-suite=TLS_AES_256_GCM_SHA384 --rpc-http-tls-protocol=TLSv1.3,TLSv1.2 +``` + +The command line: + +- Enables the HTTP JSON-RPC service using the [`--rpc-http-enabled`](../../../../public-networks/reference/cli/options.md#rpc-http-enabled) option. +- Enables TLS for the HTTP JSON-RPC service using the [`--rpc-http-tls-enabled`](../../../../public-networks/reference/cli/options.md#rpc-http-tls-enabled) option. +- Enables TLS client authentication using the [`--rpc-http-tls-client-auth-enabled`](../../../../public-networks/reference/cli/options.md#rpc-http-tls-client-auth-enabled) option. +- Specifies the keystore using the [`--rpc-http-tls-keystore-file`](../../../../public-networks/reference/cli/options.md#rpc-http-tls-keystore-file) option. +- Specifies the file that contains the password to decrypt the keystore using the [`--rpc-http-tls-keystore-password-file`](../../../../public-networks/reference/cli/options.md#rpc-http-tls-keystore-password-file) option. +- [Specifies the clients](#create-the-known-clients-file) allowed to connect to Besu using the [`--rpc-http-tls-known-clients-file`](../../../../public-networks/reference/cli/options.md#rpc-http-tls-known-clients-file) option. +- specifies the Java cipher suites using the [`--rpc-http-tls-cipher-suite`](../../../../public-networks/reference/cli/options.md#rpc-http-tls-cipher-suite) option. +- specifies the TLS protocol version using the [`--rpc-http-tls-protocol`](../../../../public-networks/reference/cli/options.md#rpc-http-tls-protocol) option. + +:::note + +Set [`--rpc-http-tls-ca-clients-enabled`](../../../../public-networks/reference/cli/options.md#rpc-http-tls-ca-clients-enabled) to `true` to allow access to clients with signed and trusted root CAs. + +::: + +## Configure server TLS + +Allow Besu to securely communicate with the server (Tessera). + +**Server prerequisites**: + +- [Configure the server to allow TLS communication] +- Server's certificate information + +### Create the known servers file + +Create a file (in this example, `knownServers`) that lists one or more trusted servers. The file contents use the format `: ` where: + +- `` is the server hostname +- `` is the port used for communication +- `` is the SHA-256 fingerprint of the server's certificate. + +```bash title="Example" +localhost:8888 3C:B4:5A:F9:88:43:5E:62:69:9F:A9:9D:41:14:03:BA:83:24:AC:04:CE:BD:92:49:1B:8D:B2:A4:86:39:4C:AC +127.0.0.1:8888 3C:B4:5A:F9:88:43:5E:62:69:9F:A9:9D:41:14:03:BA:83:24:AC:04:CE:BD:92:49:1B:8D:B2:A4:86:39:4C:AC +``` + +:::note + +If you are unsure whether requests use the hostname or an IP address, configure both in the file. + +::: + +### Start Besu + +```bash +besu --privacy-tls-enabled --privacy-tls-keystore-file=/Users/me/my_node/keystore.pfx --privacy-tls-keystore-password-file=/Users/me/my_node/keystorePassword --privacy-tls-known-enclave-file=/Users/me/my_node/knownServers +``` + +The command line: + +- Enables TLS with the server using the [`--privacy-tls-enabled`](../../../reference/cli/options.md#privacy-tls-enabled) option. +- Specifies the keystore using the [`--privacy-tls-keystore-file`](../../../reference/cli/options.md#privacy-tls-keystore-file) option. +- Specifies the file that contains the password to decrypt the keystore using the [`--privacy-tls-keystore-password-file`](../../../reference/cli/options.md#privacy-tls-keystore-password-file) option. +- Specifies the trusted servers using the [`--privacy-tls-known-enclave-file`](../../../reference/cli/options.md#privacy-tls-known-enclave-file) option. + + + +[Configure the client for TLS]: https://docs.ethsigner.consensys.net/en/latest/HowTo/Configure-TLS/#server-tls-connection +[Configure the server to allow TLS communication]: https://docs.tessera.consensys.net/HowTo/Configure/TLS/ diff --git a/versioned_docs/version-23.10.1/private-networks/how-to/configure/tls/p2p.md b/versioned_docs/version-23.10.1/private-networks/how-to/configure/tls/p2p.md new file mode 100644 index 00000000000..3121d25c520 --- /dev/null +++ b/versioned_docs/version-23.10.1/private-networks/how-to/configure/tls/p2p.md @@ -0,0 +1,261 @@ +--- +title: Peer-to-peer TLS +sidebar_position: 2 +description: Configure P2P TLS communication +tags: + - private networks +--- + +# Configure P2P TLS + +You can configure TLS to secure the P2P communication between nodes by ensuring only authorized nodes can communicate with each other. Use certificates issued by a trusted authority to connect authorized nodes in the network. + +:::caution + +P2P TLS is an early access feature, and functionality and options may be updated between releases. + +::: + +Besu supports PKCS11, PKCS12, and JKS keystore and truststore types for P2P TLS. + +## Configure P2P TLS + +**Prerequisites**: + +- A configured network. For example, [see steps 1 to 5 in the QBFT tutorial](../../../tutorials/qbft.md). +- Each node requires a keystore that contains the node's certificate and key. +- A truststore containing all the trusted certificates for the network. + +Start Besu and include the following command line options on the required nodes: + +```bash +besu --Xp2p-tls-enabled=true \ +--Xp2p-tls-keystore-type="PKCS12" \ +--Xp2p-tls-keystore-file="keystore" \ +--Xp2p-tls-keystore-password-file="keystore.password" \ +--Xp2p-tls-crl-file="crl2.pem" \ +--Xp2p-tls-truststore-type="JKS" \ +--Xp2p-tls-truststore-file="truststore.jks" \ +--Xp2p-tls-truststore-password-file="truststore_password.txt" +``` + +In the command line: + +- Enable TLS for P2P communication using [`--Xp2p-tls-enabled=true`](#xp2p-tls-enabled). +- Specify the keystore type and keystore file using [`--Xp2p-tls-keystore-type`](#xp2p-tls-keystore-type) and [`--Xp2p-tls-keystore-file`](#xp2p-tls-keystore-file). +- Specify the text file containing the password to unlock the keystore file using [`--Xp2p-tls-keystore-password-file`](#xp2p-tls-keystore-password-file). +- Specify the optional [certificate revocation list (CRL)] file using [`--Xp2p-tls-crl-file`](#xp2p-tls-crl-file). +- Specify the truststore type and truststore file using [`--Xp2p-tls-truststore-type`](#xp2p-tls-truststore-type) and [`--Xp2p-tls-truststore-file`](#xp2p-tls-truststore-file). +- Specify the text file containing the password to unlock the truststore file using [`--Xp2p-tls-truststore-password-file`](#xp2p-tls-keystore-password-file). + +## Command line options + +### `Xp2p-tls-crl-file` + + + +# Syntax + +```bash +--Xp2p-tls-crl-file= +``` + +# Example + +```bash +--Xp2p-tls-crl-file=/home/cert/cert.crl.pem +``` + +# Environment variable + +```bash +BESU_XP2P_TLS_CRL_FILE=/home/cert/cert.crl.pem +``` + + + +Path to the optional certificate revocation list (CRL) file. + +### `Xp2p-tls-enabled` + + + +# Syntax + +```bash +--Xp2p-tls-enabled[=] +``` + +# Example + +```bash +--Xp2p-tls-enabled=true +``` + +# Environment variable + +```bash +BESU_XP2P_TLS_ENABLED=true +``` + + + +Enable TLS for P2P communication. The default is `false`. + +### `Xp2p-tls-keystore-file` + + + +# Syntax + +```bash +--Xp2p-tls-keystore-file= +``` + +# Example + +```bash +--Xp2p-tls-keystore-file=/home/cert/keystore.jks +``` + +# Environment variable + +```bash +BESU_XP2P_TLS_KEYSTORE_FILE=/home/cert/keystore.jks +``` + + + +Keystore file containing the key and certificate to allow TLS for P2P communication. + +### `Xp2p-tls-keystore-password-file` + + + +# Syntax + +```bash +--Xp2p-tls-keystore-password-file= +``` + +# Example + +```bash +--Xp2p-tls-keystore-password-file=/home/cert/password.txt +``` + +# Environment variable + +```bash +BESU_XP2P_TLS_KEYSTORE_PASSWORD_FILE=/home/cert/password.txt +``` + + + +Text file containing the password to unlock the keystore file. + +### `Xp2p-tls-keystore-type` + + + +# Syntax + +```bash +--Xp2p-tls-keystore-type= +``` + +# Example + +```bash +--Xp2p-tls-keystore-type=JKS +``` + +# Environment variable + +```bash +BESU_XP2P_TLS_KEYSTORE_TYPE=JKS +``` + + + +Keystore type that allows TLS for P2P communication. Valid options are `JKS`, `PKCS11`, and `PKCS12`. The default is `JKS`. + +### `Xp2p-tls-truststore-file` + + + +# Syntax + +```bash +--Xp2p-tls-truststore-file= +``` + +# Example + +```bash +--Xp2p-tls-truststore-file=/home/cert/truststore.jks +``` + +# Environment variable + +```bash +BESU_XP2P_TLS_TRUSTSTORE_FILE=/home/cert/truststore.jks +``` + + + +Truststore containing the trusted certificates that allows TLS for P2P communication. + +### `Xp2p-tls-truststore-password-file` + + + +# Syntax + +```bash +--Xp2p-tls-truststore-password-file= +``` + +# Example + +```bash +--Xp2p-tls-truststore-password-file=/home/cert/password.txt +``` + +# Environment variable + +```bash +BESU_XP2P_TLS_TRUSTSTORE_PASSWORD_FILE=/home/cert/password.txt +``` + + + +Text file containing the password to unlock the truststore file. + +### `Xp2p-tls-truststore-type` + + + +# Syntax + +```bash +--Xp2p-tls-truststore-type= +``` + +# Example + +```bash +--Xp2p-tls-truststore-type=JKS +``` + +# Environment variable + +```bash +BESU_XP2P_TLS_TRUSTSTORE_TYPE=JKS +``` + + + +Truststore type. Valid options are `JKS`, `PKCS11`, and `PKCS12`. The default is `JKS`. + +[certificate revocation list (CRL)]: https://www.securew2.com/blog/certificate-revocation-crl-explained diff --git a/versioned_docs/version-23.10.1/private-networks/how-to/configure/validators.md b/versioned_docs/version-23.10.1/private-networks/how-to/configure/validators.md new file mode 100644 index 00000000000..0a5be8501e4 --- /dev/null +++ b/versioned_docs/version-23.10.1/private-networks/how-to/configure/validators.md @@ -0,0 +1,40 @@ +--- +title: Validators +description: Configuring validators in production networks +sidebar_position: 4 +tags: + - private networks +--- + +# Configure validators in a production network + +As when [configuring bootnodes](bootnodes.md): + +1. Create the [node key pair](../../../public-networks/concepts/node-keys.md) (that is, the private and public key) before starting the validator. +1. When creating validators in the cloud (for example, AWS or Azure), attempt to assign static IP addresses to them. If your network is: + + - Publicly accessible, assign an elastic IP address. + - Internal only, specify a private IP address when you create the instance and record this IP address. + +We recommend storing validator configuration under source control. + +## Number of validators required + +Ensure you configure enough validators to allow for redundancy. IBFT 2.0 tolerates `f = (n-1)/3` faulty validators, where: + +- `f` is the number of faulty validators +- `n` is the number of validators. + +## Adding and removing validators + +You can [vote validators in or out of the validator pool]. + +## Validators as bootnodes + +Validators can also be bootnodes. Other than the [usual configuration for bootnodes](bootnodes.md), you do not need to specify any extra configuration when a validator is also a bootnode. + +If you remove a validator that is also a bootnode, ensure there are enough remaining bootnodes on the network. + + + +[vote validators in or out of the validator pool]: consensus/ibft.md#add-and-remove-validators diff --git a/versioned_docs/version-23.10.1/private-networks/how-to/deploy/_category_.json b/versioned_docs/version-23.10.1/private-networks/how-to/deploy/_category_.json new file mode 100644 index 00000000000..5befebd2362 --- /dev/null +++ b/versioned_docs/version-23.10.1/private-networks/how-to/deploy/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Deploy for production", + "position": 6 +} diff --git a/versioned_docs/version-23.10.1/private-networks/how-to/deploy/ansible.md b/versioned_docs/version-23.10.1/private-networks/how-to/deploy/ansible.md new file mode 100644 index 00000000000..c8b9b82d5c1 --- /dev/null +++ b/versioned_docs/version-23.10.1/private-networks/how-to/deploy/ansible.md @@ -0,0 +1,19 @@ +--- +sidebar_position: 2 +title: Use Ansible +description: Deploying Hyperledger Besu with Ansible role on Galaxy +tags: + - private networks +--- + +# Deploy Besu with Ansible + +To deploy Besu using Ansible, use the [Hyperledger Besu role](https://galaxy.ansible.com/consensys/hyperledger_besu) published on Galaxy. + +For more information, see the "Read Me" button on the [Ansible Galaxy Besu page](https://galaxy.ansible.com/consensys/hyperledger_besu). + +:::tip + +We strongly recommend automating network creation. Automating makes updates easier and ensures your configuration is synchronized across the network. + +::: diff --git a/versioned_docs/version-23.10.1/private-networks/how-to/deploy/cloud.md b/versioned_docs/version-23.10.1/private-networks/how-to/deploy/cloud.md new file mode 100644 index 00000000000..d3d6b36a97c --- /dev/null +++ b/versioned_docs/version-23.10.1/private-networks/how-to/deploy/cloud.md @@ -0,0 +1,16 @@ +--- +title: Deploy to the cloud +sidebar_position: 1 +description: Deploying Besu to the cloud +tags: + - private networks +--- + +# Deploy Besu to the cloud + +When deploying Besu to the cloud: + +- Ensure you have enough spread across Availability Zones (AZs) and Regions, especially for bootnodes and validators. +- If your network is a multi-region network, consider using VPC Peering to reduce latency. +- Where required, use VPNs to connect to your on premise systems, or single private chains. +- If deploying to Kubernetes, please refer to the [tutorial](../../tutorials/kubernetes/index.md). diff --git a/versioned_docs/version-23.10.1/private-networks/how-to/deploy/ethstats.md b/versioned_docs/version-23.10.1/private-networks/how-to/deploy/ethstats.md new file mode 100644 index 00000000000..a8a48610cc7 --- /dev/null +++ b/versioned_docs/version-23.10.1/private-networks/how-to/deploy/ethstats.md @@ -0,0 +1,55 @@ +--- +sidebar_position: 4 +title: Use Ethstats network monitor +description: Ethstats network monitor +tags: + - private networks +--- + +# Connect to Ethstats network monitor + +Connect to [Ethstats](https://ethstats.dev) to display real time and historical [statistics](#statistics) about the network and nodes. You can connect to the Ethstats dashboard by [connecting to a client and server](#connect-through-a-client-and-server) or by [connecting through the command line](#connect-through-the-command-line). + +## Components + +Ethstats consists of: + +- A [server](https://github.com/goerli/ethstats-server), which consumes node data received from the client. +- A [client](https://github.com/goerli/ethstats-client), which extracts data from the node and sends it to the server. +- A [dashboard](https://github.com/goerli/ethstats-client#available-dashboards), which displays statistics. + +## Statistics + +Statistics displayed by Ethstats include: + +- Nodes in the network. Metrics for nodes include: + - Information about the last received block such as block number, block hash, transaction count, uncle count, block time, and propagation time. + - Connected peers, whether the node is mining, hash rate, latency, and uptime. +- Charts for block time, block difficulty, block gas limit, block uncles, block transactions, block gas used, block propagation histogram, and top miners. +- IP-based geolocation overview. +- Node logs, which display the data sent by a node. +- Block history, which provides the ability to go back in time and playback the block propagation through the nodes. + +## Connect through a client and server + +Refer to the external [Ethstats client](https://github.com/goerli/ethstats-client) and [Ethstats server](https://github.com/goerli/ethstats-server) documentation for installing those components and connecting to a dashboard. + +## Connect through the command line + +You can use command line options to connect a node directly to a [dashboard](https://github.com/goerli/ethstats-client#available-dashboards), without using a client. + +Start a node using the [`--ethstats`](../../../public-networks/reference/cli/options.md#ethstats) option to specify the Ethstats server URL. You can specify a contact email to send to the server using [`--ethstats-contact`](../../../public-networks/reference/cli/options.md#ethstats-contact). + +```bash +besu --ethstats=Dev-Node-1:secret@127.0.0.1:3001 --ethstats-contact=contact@mail.com +``` + +:::note + +A server must be specified by `--ethstats` in order to use `--ethstats-contact`. + +::: + +Open the selected dashboard website. Find your node under the list of nodes to see the statistics for the node and the network. + +![dashboard](../../../assets/images/dashboard.png) diff --git a/versioned_docs/version-23.10.1/private-networks/how-to/deploy/kubernetes.md b/versioned_docs/version-23.10.1/private-networks/how-to/deploy/kubernetes.md new file mode 100644 index 00000000000..fe1a95bec41 --- /dev/null +++ b/versioned_docs/version-23.10.1/private-networks/how-to/deploy/kubernetes.md @@ -0,0 +1,13 @@ +--- +sidebar_position: 3 +title: Use Kubernetes +description: Deploying Hyperledger Besu with Kubernetes +tags: + - private networks +--- + +# Deploy Besu with Kubernetes + +Use the [reference implementations](https://github.com/ConsenSys/quorum-kubernetes) to install private networks using Kubernetes (K8s). The repository has full support for cloud providers like AWS, Azure, GCP, and IBM, and has production setups that use of identities and cloud-native secret storage services like Azure KeyVault and AWS Secrets Manager. + +Refer to the [tutorial](../../tutorials/kubernetes/index.md) and familiarize yourself with the reference implementations, and customize them to your requirements. diff --git a/versioned_docs/version-23.10.1/private-networks/how-to/index.md b/versioned_docs/version-23.10.1/private-networks/how-to/index.md new file mode 100644 index 00000000000..9884ebccd56 --- /dev/null +++ b/versioned_docs/version-23.10.1/private-networks/how-to/index.md @@ -0,0 +1,37 @@ +--- +description: Private networks how to overview +tags: + - private networks +--- + +# How to + +This section provides instructional content for private network features. + +The following features are shared with [public networks](../../public-networks/index.md) and the content can be found in the public networks section: + +- Configure and manage: + - [Use a configuration file](../../public-networks/how-to/configuration-file.md) + - [Configure high availability](../../public-networks/how-to/configure-ha/index.md) + - [Configure mining](../../public-networks/how-to/use-pow/mining.md) +- [Use the Besu API](../../public-networks/how-to/use-besu-api/index.md): + - [Use JSON-RPC over HTTP, WS, and IPC](../../public-networks/how-to/use-besu-api/json-rpc.md) + - [Use RPC Pub/Sub over WS](../../public-networks/how-to/use-besu-api/rpc-pubsub.md) + - [Use GraphQL over HTTP](../../public-networks/how-to/use-besu-api/graphql.md) + - [Authenticate JSON-RPC requests](../../public-networks/how-to/use-besu-api/authenticate.md) + - [Access logs using JSON-RPC API](../../public-networks/how-to/use-besu-api/access-logs.md) +- Find and connect to peers: + - [Configure static nodes](../../public-networks/how-to/connect/static-nodes.md) + - [Configure ports](../../public-networks/how-to/connect/configure-ports.md) + - [Manage peers](../../public-networks/how-to/connect/manage-peers.md) + - [Specify NAT method](../../public-networks/how-to/connect/specify-nat.md) +- [Configure the Java Virtual Machine](../../public-networks/how-to/configure-jvm/index.md) + - [Pass JVM options](../../public-networks/how-to/configure-jvm/pass-jvm-options.md) + - [Manage JVM memory](../../public-networks/how-to/configure-jvm/manage-memory.md) + - [Use Java Flight Recorder](../../public-networks/how-to/configure-jvm/java-flight-recorder.md) +- Develop dapps: + - [Use Hardhat](../../public-networks/how-to/develop/hardhat.md) + - [Use client libraries](../../public-networks/how-to/develop/client-libraries.md) +- Troubleshoot: + - [Use EVM tool](../../public-networks/how-to/troubleshoot/evm-tool.md) + - [Trace transactions](../../public-networks/how-to/troubleshoot/trace-transactions.md) diff --git a/versioned_docs/version-23.10.1/private-networks/how-to/monitor/_category_.json b/versioned_docs/version-23.10.1/private-networks/how-to/monitor/_category_.json new file mode 100644 index 00000000000..8e8c27af9a7 --- /dev/null +++ b/versioned_docs/version-23.10.1/private-networks/how-to/monitor/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Monitor nodes", + "position": 3 +} diff --git a/versioned_docs/version-23.10.1/private-networks/how-to/monitor/chainlens.md b/versioned_docs/version-23.10.1/private-networks/how-to/monitor/chainlens.md new file mode 100644 index 00000000000..0e5f507621f --- /dev/null +++ b/versioned_docs/version-23.10.1/private-networks/how-to/monitor/chainlens.md @@ -0,0 +1,116 @@ +--- +title: Use Chainlens Explorer +sidebar_position: 7 +description: Use Chainlens Explorer on a privacy-enabled Besu network +tags: + - private networks +--- + +# Use Chainlens Blockchain Explorer + +[Chainlens Blockchain Explorer](https://chainlens.com/) supports public and private EVM networks. +This page describes how to use the free version of Chainlens with its built-in support for +[privacy-enabled](../../concepts/privacy/index.md) Besu networks created using the +[Developer Quickstart](../../tutorials/quickstart.md). + +Chainlens provides an overview of the entire network, including block information, contract +metadata, transaction searches, and [more](https://chainlens.com/). + +:::note +You must connect to one of the privacy nodes (for example, `member1besu`), not the dedicated RPC, to +allow access for Besu [privacy API methods](../../reference/api/index.md#priv-methods). +In production networks, you must [secure access](../../../public-networks/how-to/use-besu-api/authenticate.md) +to RPC nodes. +::: + +## Prerequisites + +[Docker and Docker Compose](https://docs.docker.com/compose/install/) installed. + +## Start Chainlens + +Clone the [Chainlens GitHub repository](https://github.com/web3labs/chainlens-free): + +```bash +git clone https://github.com/web3labs/chainlens-free +``` + +The repository contains a `docker-compose` directory to allow Chainlens to start with a Developer +Quickstart test network. +From the `docker-compose` directory, run the following command: + +```bash +NODE_ENDPOINT=http://rpcnode:8545 docker-compose -f docker-compose.yml -f chainlens-extensions/docker-compose-quorum-dev-quickstart.yml up +``` + +This command does two things: + +- Sets up the node endpoint +- Tells Docker to run by using the two Docker Compose files provided + +The first `docker-compose.yml` file in the command contains all the services required for Chainlens. + +The second file named `docker-compose-quorum-dev-quickstart` contains the network settings required to start +Chainlens on the same network as the Besu development node. + +Next, open `http://localhost/` on your browser. +You’ll see the new initialization page while it boots up. +This may take 5–10 minutes for the all services to start and the ingestion sync to complete. + +![`Chainlens_loading`](../../../assets/images/chainlens-loading.png) + +## View on Chainlens + +After starting Chainlens, you can view information about your network. + +:::note +Screenshots in this section are taken from the [Chainlens Goerli network](https://goerli.chainlens.com/dashboard). +::: + +The **Dashboard** page provides an aggregated view of network activities. + +![`Chainlens_dashboard`](../../../assets/images/chainlens-dashboard.png) + +The **Network** page provides an overview of the network status and connected peers. +This page is disabled by default, and is only visible if you set `DISPLAY_NETWOR_TAB=enabled` using +the following command: + +```bash +NODE_ENDPOINT=http://member1besu:8545 DISPLAY_NETWORK_TAB=enabled docker-compose -f docker-compose.yml -f chainlens-extensions/docker-compose-quorum-dev-quickstart.yml up +``` + +The **Blocks** page shows a real-time view of the finalized blocks. + +![Chainlens blocks](../../../assets/images/chainlens-block.png) + +You can view a given block details by selecting a block hash or number. + +![Chainlens block details](../../../assets/images/chainlens-block-details.png) + +The **Transactions** page shows a paginated view of new and historical transactions. + +![Chainlens transactions](../../../assets/images/chainlens-transactions.png) + +If you select any transaction hash, you can get the **transaction details.** + +![Chainlens transaction_details](../../../assets/images/chainlens-transaction-details.png) + +The **Contracts** page shows all the smart contracts deployed on the network. + +![Chainlens contracts](../../../assets/images/chainlens-contracts.png) + +You can view a smart contract details by selecting the contract address. + +![Chainlens contract details](../../../assets/images/chainlens-contract-details.png) + +The **Events** page shows all the events generated on the network. + +![Chainlens events](../../../assets/images/chainlens-events.png) + +## Stop Chainlens + +To stop all the services from running, run the following command: + +```bash +docker-compose down +``` diff --git a/versioned_docs/version-23.10.1/private-networks/how-to/monitor/elastic-stack.md b/versioned_docs/version-23.10.1/private-networks/how-to/monitor/elastic-stack.md new file mode 100644 index 00000000000..b74dd929dfd --- /dev/null +++ b/versioned_docs/version-23.10.1/private-networks/how-to/monitor/elastic-stack.md @@ -0,0 +1,35 @@ +--- +title: Use Elastic Stack +sidebar_position: 3 +description: Using Elastic Stack (ELK) with Hyperledger Besu +tags: + - private networks +--- + +# Use Elastic Stack + +[Elastic Stack] (ELK) is an open-source log management platform that is available when using the [Developer Quickstart](../../tutorials/quickstart.md). + +The [Filebeat] configuration ingests logs and the [Metricbeat] configuration collects metrics from the nodes at regular defined intervals and outputs them to Redis for storage. Redis provides a highly available mechanism enabling storage by any of the Elastic Beats and pulled by Logstash as required. + +The [pipeline configuration] defines the JSON format used for Besu logs and automatically picks up any new log fields. + +:::note + +The pipeline configuration must match the your log format. If using the default log format, you can use the [grok plugin](https://www.elastic.co/guide/en/logstash/current/plugins-filters-grok.html) to extract the log fields. + +::: + +To see the Besu Quickstart network logs in Kibana: + +1. [Start the Developer Quickstart with Besu](../../tutorials/quickstart.md), selecting ELK monitoring. +1. Open the [`Kibana logs address`](http://localhost:5601/app/kibana#/discover) listed by the sample networks `list.sh` script. The logs display in Kibana. + + ![Kibana](../../../assets/images/KibanaQuickstart.png) + + + +[Filebeat]: https://github.com/ConsenSys/quorum-dev-quickstart/blob/b72a0f64d685c851bf8be399a8e33bbdf0e09982/files/common/filebeat/filebeat.yml +[Metricbeat]: https://github.com/ConsenSys/quorum-dev-quickstart/blob/b72a0f64d685c851bf8be399a8e33bbdf0e09982/files/common/metricbeat/metricbeat.yml +[pipeline configuration]: https://github.com/ConsenSys/quorum-dev-quickstart/blob/b72a0f64d685c851bf8be399a8e33bbdf0e09982/files/common/logstash/pipeline/20_besu.conf +[Elastic Stack]: https://www.elastic.co/what-is/elk-stack diff --git a/versioned_docs/version-23.10.1/private-networks/how-to/monitor/index.md b/versioned_docs/version-23.10.1/private-networks/how-to/monitor/index.md new file mode 100644 index 00000000000..08ff29aede2 --- /dev/null +++ b/versioned_docs/version-23.10.1/private-networks/how-to/monitor/index.md @@ -0,0 +1,20 @@ +--- +description: Monitoring using metrics and logging +tags: + - private networks +--- + +# Monitoring + +Use monitoring to identify node and network issues. In private networks, you can [configure metrics and logging](../../../public-networks/how-to/monitor/index.md) as in public networks. + +You can also use the following monitoring tools in private networks: + +- [Loki](loki.md) +- [Elastic Stack](elastic-stack.md) +- [Quorum Hibernate](quorum-hibernate.md) +- [Splunk](splunk.md) +- [OpenTelemetry](opentelemetry.md) +- [Chainlens Explorer](chainlens.md) + +For an overview of monitoring Hyperledger Besu, view [this recording](https://www.youtube.com/watch?v=7BuutRe0I28&feature=youtu.be). diff --git a/versioned_docs/version-23.10.1/private-networks/how-to/monitor/loki.md b/versioned_docs/version-23.10.1/private-networks/how-to/monitor/loki.md new file mode 100644 index 00000000000..eabe6f0667b --- /dev/null +++ b/versioned_docs/version-23.10.1/private-networks/how-to/monitor/loki.md @@ -0,0 +1,37 @@ +--- +title: Use Grafana Loki +sidebar_position: 2 +description: Using Grafana Loki log management platform with Hyperledger Besu +tags: + - private networks +--- + +# Grafana Loki + +[Grafana Loki] is an open-source log management platform that is available when using the [Developer Quickstart](../../tutorials/quickstart.md). + +The [Promtail configuration] ingests logs at regular defined intervals and outputs them to [Loki] for storage. + +The `pipeline configuration` in Promtail defines pipeline stages that can collate logs natively or using the JSON format. + +:::note + +If using the pipeline regex stage in `Promtail`, configuration must match your log format. + +::: + +To view the GoQuorum Quickstart network logs in Loki: + +1. [Start the Developer Quickstart with Besu](../../tutorials/quickstart.md), selecting Loki monitoring. +2. Open the [`Grafana Loki address`](http://localhost:3000/d/Ak6eXLsPxFemKYKEXfcH/quorum-logs-loki?orgId=1&var-app=besu&var-search=&from=now-15m&to=now) listed by the sample networks `list.sh` script. + + The logs display in Loki. + + ![Loki logs](../../../assets/images/grafana_loki.png) + + + +[Promtail configuration]: https://github.com/ConsenSys/quorum-dev-quickstart/blob/master/files/common/promtail/promtail.yml +[pipeline configuration]: https://github.com/ConsenSys/quorum-dev-quickstart/blob/master/files/common/promtail/promtail.yml +[Loki]: https://github.com/ConsenSys/quorum-dev-quickstart/blob/master/files/common/loki/loki.yml +[Grafana Loki]: https://grafana.com/oss/loki/ diff --git a/versioned_docs/version-23.10.1/private-networks/how-to/monitor/opentelemetry.md b/versioned_docs/version-23.10.1/private-networks/how-to/monitor/opentelemetry.md new file mode 100644 index 00000000000..185b61da3d5 --- /dev/null +++ b/versioned_docs/version-23.10.1/private-networks/how-to/monitor/opentelemetry.md @@ -0,0 +1,176 @@ +--- +title: Use OpenTelemetry +sidebar_position: 6 +description: Collect Besu information with the OpenTelemetry Collector +tags: + - private networks +--- + +# Use OpenTelemetry + +You can use the OpenTelemetry monitoring and tracing service to gather node metrics and traces. To enable OpenTelemetry to access Hyperledger Besu, use the [`--metrics-enabled`](../../../public-networks/reference/cli/options.md#metrics-enabled) and [`--metrics-protocol=opentelemetry`](../../../public-networks/reference/cli/options.md#metrics-protocol) options. Use [Splunk](https://splunk.com) to visualize the collected data. A [Besu Sync example](https://github.com/splunk/splunk-connect-for-ethereum/tree/master/examples/besu-sync) is available. + +:::tip + +Use OpenTelemetry to monitor the sync time of your Besu node and show where time is spent internally and over the JSON-RPC interface. + +[This office hours recording](https://wiki.hyperledger.org/display/BESU/2021-01-19+Office+Hours+Notes) shows examples of monitoring Hyperledger Besu. + +::: + +## Install OpenTelemetry Collector + +Download and install the [OpenTelemetry Collector](https://github.com/open-telemetry/opentelemetry-collector-contrib/releases). + +:::tip + +You can also install exporters that send system metrics to OpenTelemetry to monitor non-Besu-specific items such as disk and CPU usage. The OpenTelemetry Collector can connect to additional applications, and may be deployed in Kubernetes environments as a daemonset. + +::: + +## Setting up and running OpenTelemetry with Besu + +1. Configure OpenTelemetry to accept data from Besu. For example, use the following configuration for your `otel-collector-config.yml` file, and send data to Splunk and Splunk APM: + + ```yml title="otel-collector-config.yml" + receivers: + otlp: + protocols: + grpc: + http: + + exporters: + splunk_hec/traces: + # Splunk HTTP Event Collector token. + token: "11111111-1111-1111-1111-1111111111113" + # URL to a Splunk instance to send data to. + endpoint: "https://:8088/services/collector" + # Optional Splunk source: https://docs.splunk.com/Splexicon:Source + source: "besu:traces" + # Optional Splunk source type: https://docs.splunk.com/Splexicon:Sourcetype + sourcetype: "otlp" + # Splunk index, optional name of the Splunk index targeted. + index: "traces" + # Maximum HTTP connections to use simultaneously when sending data. Defaults to 100. + max_connections: 20 + # Whether to disable gzip compression over HTTP. Defaults to false. + disable_compression: false + # HTTP timeout when sending data. Defaults to 10s. + timeout: 10s + # Whether to skip checking the certificate of the HEC endpoint when sending data over HTTPS. Defaults to false. + # For this demo, we use a self-signed certificate on the Splunk docker instance, so this flag is set to true. + insecure_skip_verify: true + splunk_hec/metrics: + # Splunk HTTP Event Collector token. + token: "11111111-1111-1111-1111-1111111111113" + # URL to a Splunk instance to send data to. + endpoint: "https://:8088/services/collector" + # Optional Splunk source: https://docs.splunk.com/Splexicon:Source + source: "besu:metrics" + # Optional Splunk source type: https://docs.splunk.com/Splexicon:Sourcetype + sourcetype: "prometheus" + # Splunk index, optional name of the Splunk index targeted. + index: "metrics" + # Maximum HTTP connections to use simultaneously when sending data. Defaults to 100. + max_connections: 20 + # Whether to disable gzip compression over HTTP. Defaults to false. + disable_compression: false + # HTTP timeout when sending data. Defaults to 10s. + timeout: 10s + # Whether to skip checking the certificate of the HEC endpoint when sending data over HTTPS. Defaults to false. + # For this demo, we use a self-signed certificate on the Splunk docker instance, so this flag is set to true. + insecure_skip_verify: true + # Traces + sapm: + access_token: "${SPLUNK_ACCESS_TOKEN}" + endpoint: "https://ingest.${SPLUNK_REALM}.signalfx.com/v2/trace" + # Metrics + Events + signalfx: + access_token: "${SPLUNK_ACCESS_TOKEN}" + realm: "${SPLUNK_REALM}" + + processors: + batch: + + extensions: + health_check: + pprof: + zpages: + + service: + extensions: [pprof, zpages, health_check] + pipelines: + traces: + receivers: [otlp] + exporters: [splunk_hec/traces, sapm] + processors: [batch] + metrics: + receivers: [otlp] + exporters: [splunk_hec/metrics, signalfx] + processors: [batch] + ``` + + It is easiest to run the OpenTelemetry collector with Docker with the following command: + + + + # Syntax + + ```bash + docker run -d \ + -v ./otel-collector-config.yml:/etc/otel/config.yaml \ + -e SPLUNK_ACCESS_TOKEN= \ + -e SPLUNK_REALM= \ + -p 4317:4317 \ + otel/opentelemetry-collector-contrib:latest + ``` + + # Example + + ```bash + docker run -d \ + -v ./otel-collector-config.yml:/etc/otel/config.yaml \ + -e SPLUNK_ACCESS_TOKEN=abcdefg654 \ + -e SPLUNK_REALM=us1 \ + -p 4317:4317 \ + otel/opentelemetry-collector-contrib:latest + ``` + + + + You can also refer to this [Docker-compose example](https://github.com/splunk/splunk-connect-for-ethereum/blob/989dc2ccae7d8235bf3ce2a83a18cf0cd1713294/examples/besu-sync/full-sync/docker-compose.yaml). + +2. Start Besu with the [`--metrics-enabled`](../../../public-networks/reference/cli/options.md#metrics-enabled) and [`--metrics-protocol=opentelemetry`](../../../public-networks/reference/cli/options.md#metrics-protocol) options. For example, run the following command to start a single node: + + + + # Syntax + + ```bash + OTEL_EXPORTER_OTLP_ENDPOINT=https://: besu --network=dev --miner-enabled --miner-coinbase --rpc-http-cors-origins="all" --rpc-http-enabled --metrics-enabled --metrics-protocol=opentelemetry + ``` + + # Example + + ```bash + OTEL_EXPORTER_OTLP_ENDPOINT=https://localhost:4317 besu --network=dev --miner-enabled --miner-coinbase fe3b557e8fb62b89f4916b721be55ceb828dbd73 --rpc-http-cors-origins="all" --rpc-http-enabled --metrics-enabled --metrics-protocol=opentelemetry + ``` + + + + The [OpenTelemetry SDK](https://github.com/open-telemetry/opentelemetry-specification/blob/8f7cdb73618a0b3afa9532b8f8103d719e352781/specification/sdk-environment-variables.md) mandates how to configure the OpenTelemetry gRPC client, so data flows to the collector from Besu. + + You can use the following environment variables: + + | Name | Description | Required | + | --- | --- | --- | + | OTEL_EXPORTER_OTLP_ENDPOINT | OpenTelemetry Collector endpoint, of the form `https://host:port`. The default value is `https://localhost:4317` | Yes | + | OTEL_EXPORTER_OTLP_INSECURE | Whether to allow insecure connections for OpenTelemetry data. False by default. | No | + + + +[Monitoring Besu synchronization to chain with Splunk]: https://github.com/splunk/splunk-connect-for-ethereum/tree/master/examples/besu-sync + + + +\*[APM]: Application Performance Monitoring diff --git a/versioned_docs/version-23.10.1/private-networks/how-to/monitor/quorum-hibernate.md b/versioned_docs/version-23.10.1/private-networks/how-to/monitor/quorum-hibernate.md new file mode 100644 index 00000000000..2d6b6139db0 --- /dev/null +++ b/versioned_docs/version-23.10.1/private-networks/how-to/monitor/quorum-hibernate.md @@ -0,0 +1,20 @@ +--- +title: Use Quorum Hibernate +sidebar_position: 4 +description: Use Quorum Hibernate with Hyperledger Besu +tags: + - private networks +--- + +# Use Quorum Hibernate + +[Quorum Hibernate] is a proxy that monitors a node's API traffic and hibernates the node when inactive. This reduces infrastructure costs by ensuring only nodes receiving API requests or nodes required to establish consensus are running. + +Quorum Hibernate wakes up hibernating nodes: + +- When a new transaction or API request is received. +- To allow it to periodically sync with the network. + + + +[Quorum Hibernate]: https://github.com/ConsenSys/quorum-hibernate diff --git a/versioned_docs/version-23.10.1/private-networks/how-to/monitor/splunk.md b/versioned_docs/version-23.10.1/private-networks/how-to/monitor/splunk.md new file mode 100644 index 00000000000..2b749536740 --- /dev/null +++ b/versioned_docs/version-23.10.1/private-networks/how-to/monitor/splunk.md @@ -0,0 +1,192 @@ +--- +title: Use Splunk +sidebar_position: 5 +description: Send Hyperledger Besu logs to Splunk +tags: + - private networks +--- + +# Use Splunk + +[Splunk](https://splunkbase.splunk.com/app/4866/) is a third-party monitoring solution compatible with Besu. A Splunk server can receive Besu logs and enable complex search, visualization, and analysis. + +Splunk can aggregate multiple logs in one place and run complex queries without being connected to the machine running Besu to read the standard output. + +Options for running Splunk and Besu are: + +- [Use Splunk](#use-splunk) + - [Developer Quickstart with Splunk](#developer-quickstart-with-splunk) + - [Splunk Connect for Ethereum Docker Compose](#splunk-connect-for-ethereum-docker-compose) + - [Requirements](#requirements) + - [Steps](#steps) + - [Use Splunk Enterprise as a Docker container](#use-splunk-enterprise-as-a-docker-container) + - [Prerequisites](#prerequisites) + - [Steps](#steps-1) + - [Run a Splunk Enterprise instance](#run-a-splunk-enterprise-instance) + - [Prerequisites](#prerequisites-1) + - [Steps](#steps-2) + - [Splunk options reference](#splunk-options-reference) + +## Developer Quickstart with Splunk + +To view the Quickstart network logs in Splunk: + +1. [Start the Developer Quickstart with Besu](../../tutorials/quickstart.md), selecting Splunk monitoring. +1. Open the [Splunk UI](http://localhost:8000). + +## Splunk Connect for Ethereum Docker Compose + +To run a development Besu node and connect it to Splunk Enterprise, use the Splunk Connect for Ethereum demonstration Docker Compose environment provided by Splunk. + +### Requirements + +- [Git](https://git-scm.com/) +- [Docker and Docker-compose](https://docs.docker.com/compose/install/) + +:::info + +A Splunk license is not required to use the Splunk Connect for Ethereum demonstration. + +::: + +### Steps + +1. Clone the Splunk Connect for Ethereum repository: + + ```bash + git clone https://github.com/splunk/splunk-connect-for-ethereum.git + cd splunk-connect-for-ethereum + ``` + +1. Start the demonstration environment by following the Splunk Connect for Ethereum repository [README](https://github.com/splunk/splunk-connect-for-ethereum/tree/master/examples/besu). + + :::note + + Splunk enterprise takes some time to start. + + Run `docker ps` and wait for the `STATUS` of the 3 containers to be `Up [number] seconds (healthy)`. + + ``` + CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES + 127600dd1173 splunkdlt/ethlogger:latest "ethlogger" 53 seconds ago Up 51 seconds (healthy) ethlogger + 88dfcee683c4 splunk/splunk:latest "/sbin/entrypoint.sh…" 53 seconds ago Up 52 seconds (healthy) 8065/tcp, 8088-8089/tcp, 8191/tcp, 9887/tcp, 9997/tcp, 0.0.0.0:18000->8000/tcp splunk + 111b0c6d6072 hyperledger/besu:1.4.4 "besu" 53 seconds ago Up 52 seconds (healthy) 8545-8547/tcp, 30303/tcp besu + ``` + + ::: + +## Use Splunk Enterprise as a Docker container + +### Prerequisites + +- [Docker](https://docs.docker.com/compose/install/) +- [Besu 1.4.4](https://github.com/hyperledger/besu/blob/750580dcca349d22d024cc14a8171b2fa74b505a/CHANGELOG.md#144) or later [installed](../../get-started/install/binary-distribution.md) + +:::info + +A Splunk license is not required to use the trial version of the Splunk Docker image. The image is not suitable for production use and has [restrictions on daily log volume](https://www.splunk.com/). + +::: + +:::note + +If running [Besu as a Docker container](../../get-started/install/run-docker-image.md), consider using [Splunk Connect for Ethereum Docker Compose](#splunk-connect-for-ethereum-docker-compose) or [Kubernetes](../deploy/kubernetes.md) instead of the Splunk Enterprise trial container. + +::: + +### Steps + +1. Start the Splunk Enterprise container: + + ```bash + docker run \ + -e SPLUNK_START_ARGS=--accept-license \ + -e SPLUNK_HEC_TOKEN=11111111-1111-1111-1111-1111111111113 \ + -e SPLUNK_PASSWORD=changeme \ + --rm \ + -p8080:8000 -p8088:8088 \ + -d \ + --name splunk-demo \ + splunk/splunk:latest + ``` + + Once the service is started, connect on [`http://localhost:8080/`](http://localhost:8080/) and login as the `admin` user with a password of `changeme`. + + :::tip + + To follow the logs of the Splunk container: + + ```bash + docker logs -f splunk-demo + ``` + + ::: + +2. Create the Besu index: + + 1. In the Splunk Web interface, navigate to the [index list in the settings](http://localhost:8080/en-US/manager/search/data/indexes). + 2. [Create an event index] with an Index Name of `besu`. + 3. Leave other fields with the default values. + 4. Save the `besu` index. + +3. Run Besu. To start a Besu node running in development mode, run the following command: + + ```bash + LOGGER=Splunk \ + SPLUNK_URL=https://localhost:8088 \ + SPLUNK_TOKEN=11111111-1111-1111-1111-1111111111113 \ + SPLUNK_SKIPTLSVERIFY=true \ + besu \ + --network=dev \ + --miner-coinbase=0xfe3b557e8fb62b89f4916b721be55ceb828dbd73 \ + --miner-enabled \ + --logging=trace + ``` + + The environment variables specified send the Besu logs to Splunk. Only `LOGGER`, `SPLUNK_URL`, `SPLUNK_TOKEN` and `SPLUNK_SKIPTLSVERIFY` are required in this example. The complete list of options is in the [Splunk options reference table](#splunk-options-reference). + +4. In the Splunk Web interface, navigate to the [search page](http://localhost:8080/en-US/app/search/search). Type `index="besu"` in the search field. Log events sent by Besu are displayed. + + Congratulations! You can now play with the search and other Splunk features to explore your Besu logs. + + ![Splunk search page](../../../assets/images/splunk-ui.png) + +5. Stop Besu with ++ctrl+c++. Stop the Splunk container with `docker stop splunk-demo`. + +## Run a Splunk Enterprise instance + +### Prerequisites + +- [Splunk Enterprise license](https://www.splunk.com/) +- [Besu 1.4.4](https://github.com/hyperledger/besu/blob/master/CHANGELOG.md#144) or later [installed](../../get-started/install/binary-distribution.md) + +### Steps + +1. Follow the steps in the [Splunk Enterprise documentation](https://docs.splunk.com/Documentation/Splunk/8.0.4/Installation) to download, install, and run Splunk Enterprise. + +1. After logging into the Splunk Enterprise Web interface, navigate to the settings to: + + 1. [Create an HTTP Event Collector](https://docs.splunk.com/Documentation/Splunk/8.0.4/Data/UsetheHTTPEventCollector). + 1. [Create an event index] named `besu`. + +1. Run Besu as in step 3 in [using Splunk on Docker](#use-splunk-enterprise-as-a-docker-container). Set the `SPLUNK_URL` value to match the HTTP Event Collector address and port. + + You can display logs and use the search engine as in step 4 in [using Splunk on Docker](#use-splunk-enterprise-as-a-docker-container). + +## Splunk options reference + +| Name | Description | Required | +| --- | --- | --- | +| LOGGER | Set to `Splunk` to activate sending logs to Splunk. | Yes | +| HOST | Current host. If in a Docker environment, the default value is the docker container ID. Otherwise, the default value is `localhost`. | No | +| SPLUNK_URL | URL of the Splunk HTTP Event Collector. For example, use `https://localhost:8088` | Yes | +| SPLUNK_TOKEN | Authentication token, usually of the form `11111111-1111-1111-1111-111111111111` | Yes | +| SPLUNK_INDEX | [Index](https://docs.splunk.com/Splexicon:Index) to store logs. Defaults to `besu` | No | +| SPLUNK_SOURCE | [Source of the logs](https://docs.splunk.com/Splexicon:Source). Defaults to `besu` | No | +| SPLUNK_SOURCETYPE | [Source type of the logs](https://docs.splunk.com/Splexicon:Sourcetype). Defaults to `besu` | No | +| SPLUNK_BATCH_SIZE_BYTES | Size of a log batch in bytes. Defaults to `65536` | No | +| SPLUNK_BATCH_SIZE_COUNT | Size of a log batch in number of events. Defaults to `1000` | No | +| SPLUNK_BATCH_INTERVAL | Interval at which to send log batches. Defaults to `500` | No | +| SPLUNK_SKIPTLSVERIFY | Whether to check the Splunk instance TLS certificate when sending data. Defaults to `false` | No | + +[Create an event index]: https://docs.splunk.com/Documentation/Splunk/8.0.4/Indexer/Setupmultipleindexes#Create_events_indexes diff --git a/versioned_docs/version-23.10.1/private-networks/how-to/send-transactions/_category_.json b/versioned_docs/version-23.10.1/private-networks/how-to/send-transactions/_category_.json new file mode 100644 index 00000000000..a663c5c6ed7 --- /dev/null +++ b/versioned_docs/version-23.10.1/private-networks/how-to/send-transactions/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Create and send transactions", + "position": 2 +} diff --git a/versioned_docs/version-23.10.1/private-networks/how-to/send-transactions/concurrent-private-transactions.md b/versioned_docs/version-23.10.1/private-networks/how-to/send-transactions/concurrent-private-transactions.md new file mode 100644 index 00000000000..a1fb71eb48a --- /dev/null +++ b/versioned_docs/version-23.10.1/private-networks/how-to/send-transactions/concurrent-private-transactions.md @@ -0,0 +1,37 @@ +--- +title: Send concurrent private transactions +description: Creating and sending concurrent private transactions with Hyperledger Besu +sidebar_position: 2 +tags: + - private networks +--- + +# Send concurrent private transactions + +Private transaction processing involves two transactions, the private transaction and the [privacy marker transaction (PMT)](../../concepts/privacy/private-transactions/processing.md). The private transaction and the PMT each have their own [nonce](../../concepts/privacy/private-transactions/index.md#nonces). + +If your private transaction rate requires sending private transactions without waiting for the previous private transaction to be mined, using [`eth_getTransactionCount`](../../../public-networks/reference/api/index.md#eth_gettransactioncount) and [`eea_sendRawTransaction`](../../reference/api/index.md#eea_sendrawtransaction) may result in [incorrect nonces](../../concepts/privacy/private-transactions/index.md#private-nonce-management). + +In this case, use [`priv_distributeRawTransaction`](private-transactions.md#priv_distributerawtransaction) instead of [`eea_sendRawTransaction`](../../reference/api/index.md#eea_sendrawtransaction). + +:::note + +You can use [`priv_getTransactionCount`](../../reference/api/index.md#priv_gettransactioncount) or [`priv_getEeaTransactionCount`](../../reference/api/index.md#priv_geteeatransactioncount) to get the nonce for an account for the specified privacy group or participants. + +::: + +Send the corresponding PMT using [`eth_sendRawTransaction`](../../../public-networks/reference/api/index.md#eth_sendrawtransaction), specifying the public PMT nonce. This method allows you to create and send the PMT yourself rather than [`eea_sendRawTransaction`](../../reference/api/index.md#eea_sendrawtransaction) handling the PMT. + +:::caution + +When using `priv_distributeRawTransaction` to distribute transactions with consecutive nonces for the same account, the corresponding PMTs must use one account with the nonces in the same order as the private transactions. + +This is to ensure that the private transactions are executed in the correct order. + +::: + +:::info + +The [web3js-quorum library](https://github.com/ConsenSys/web3js-quorum/tree/master/example/concurrentPrivateTransactions) includes an example of how to send concurrent private transactions. The example uses [offchain privacy groups](../../concepts/privacy/privacy-groups.md). Use [`priv_getPrivacyPrecompileAddress`](../../reference/api/index.md#priv_getprivacyprecompileaddress) to get the precompile address to specify in the `to` field when creating the PMT. + +::: diff --git a/versioned_docs/version-23.10.1/private-networks/how-to/send-transactions/index.md b/versioned_docs/version-23.10.1/private-networks/how-to/send-transactions/index.md new file mode 100644 index 00000000000..3f9920a3d31 --- /dev/null +++ b/versioned_docs/version-23.10.1/private-networks/how-to/send-transactions/index.md @@ -0,0 +1,16 @@ +--- +title: Create and send transactions +description: private networks send transactions overview +tags: + - private networks +--- + +# Create and send transactions + +In private networks, you can create and [send regular transactions](../../../public-networks/how-to/send-transactions.md) as in public networks. + +You can also: + +- [Send private transactions](private-transactions.md). +- [Send concurrent private transactions](concurrent-private-transactions.md). +- [Include revert reason in transactions](revert-reason.md). diff --git a/versioned_docs/version-23.10.1/private-networks/how-to/send-transactions/private-transactions.md b/versioned_docs/version-23.10.1/private-networks/how-to/send-transactions/private-transactions.md new file mode 100644 index 00000000000..cdeb49aec37 --- /dev/null +++ b/versioned_docs/version-23.10.1/private-networks/how-to/send-transactions/private-transactions.md @@ -0,0 +1,142 @@ +--- +title: Create and send private transactions +description: Creating and sending private transactions with Hyperledger Besu +sidebar_position: 1 +tags: + - private networks +--- + +# Create and send private transactions + +Create and send [private transactions](../../concepts/privacy/index.md) using: + +- [web3js-quorum client library](../use-privacy/web3js-quorum.md) or [web3j client library](https://github.com/web3j/web3j) +- [`eea_sendTransaction` with EthSigner](https://docs.ethsigner.consensys.net/Reference/API-Methods#eea_sendtransaction) +- [`eea_sendRawTransaction`](#eea_sendrawtransaction) +- [`priv_distributeRawTransaction`](#priv_distributerawtransaction). + +All private transaction participants must be online for a private transaction to be successfully distributed. If any participants are offline when submitting the private transaction, the transaction is not attempted and you must resubmit the transaction. + +The `gas` and `gasPrice` specified when sending a private transaction are used by the [privacy marker transaction (PMT)](../../concepts/privacy/private-transactions/processing.md), not the private transaction itself. + +:::note + +Private transactions either deploy contracts or call contract functions. Ether transfer transactions cannot be private. + +::: + +## eea_sendRawTransaction + +[`eea_sendRawTransaction`](../../reference/api/index.md#eea_sendrawtransaction) distributes the private transaction to the participating nodes, and signs and submits the PMT, as described in [Private transaction processing](../../concepts/privacy/private-transactions/processing.md). + +:::note + +If [sending concurrent transactions](concurrent-private-transactions.md), you must use [`priv_distributeRawTransaction`](#priv_distributerawtransaction) instead of [`eea_sendRawTransaction`](../../reference/api/index.md#eea_sendrawtransaction). + +::: + +## priv_distributeRawTransaction + +Use [`priv_distributeRawTransaction`](../../reference/api/index.md#priv_distributerawtransaction) instead of [`eea_sendRawTransaction`](#eea_sendrawtransaction) when sending [concurrent private transactions](concurrent-private-transactions.md). + +[`priv_distributeRawTransaction`](../../reference/api/index.md#priv_distributerawtransaction) distributes the private transaction to the participating nodes but does not sign and submit the PMT. That is, it performs steps 1 to 5 of [private transaction processing](../../concepts/privacy/private-transactions/processing.md). + +If using [`priv_distributeRawTransaction`](../../reference/api/index.md#priv_distributerawtransaction) instead of [`eea_sendRawTransaction`](../../reference/api/index.md#eea_sendrawtransaction), use the value returned by [`priv_distributeRawTransaction`](../../reference/api/index.md#priv_distributerawtransaction), which is the enclave key to the private transaction in [Tessera](https://docs.tessera.consensys.net/), in the `data` field of a call to [`eth_sendRawTransaction`](../../../public-networks/reference/api/index.md#eth_sendrawtransaction). Use the value returned by [`priv_getPrivacyPrecompileAddress`](../../reference/api/index.md#priv_getprivacyprecompileaddress), which is the address of the [privacy precompiled contract](../../concepts/privacy/private-transactions/processing.md), in the `to` field of the call. + +By using the [public Ethereum transaction](../../how-to/send-transactions/index.md), [`eth_sendRawTransaction`](../../../public-networks/reference/api/index.md#eth_sendrawtransaction), you are signing and submitting the PMT yourself instead of having it signed by the Besu node, giving you greater control over the PMT. + +:::warning + +If the PMT is not sent after distributing the private transaction, the distributed private transaction is not executed and the private states are not updated. + +::: + +```json title="Distribute private transaction using priv_distributeRawTransaction" +{ + "jsonrpc": "2.0", + "method": "priv_distributeRawTransaction", + "params": [ + "0xf90198808203e8832dc6c08080b8fb608060405234801561001057600080fd5b5060dc8061001f6000396000f3006080604052600436106049576000357c0100000000000000000000000000000000000000000000000000000000900463ffffffff1680633fa4f24514604e57806355241077146076575b600080fd5b348015605957600080fd5b50606060a0565b6040518082815260200191505060405180910390f35b348015608157600080fd5b50609e6004803603810190808035906020019092919050505060a6565b005b60005481565b80600081905550505600a165627a7a723058202bdbba2e694dba8fff33d9d0976df580f57bff0a40e25a46c398f8063b4c003600291ba05393543d483654fd01d9ee818cddfc7527dd6e13e6ef7b45a61e2ca13ffb6b70a0452338873862803ffe04056aea98cd0e3417ff971dcb384e54fce8ca1756a665a09de8260dc3763f8383a6a9ffe96909d36cd3ff4c346e3846a6467c50feaf0119e1a0839f41993789227ec721c9eaf1541683287fa436ef6edd9ec8fd088bad1a0c3c8a72657374726963746564" + ], + "id": 1 +} +``` + +```json title="Enclave key to the private transaction in Tessera returned by priv_distributeRawTransaction" +{ + "jsonrpc": "2.0", + "id": 1, + "result": "0xfd0d90ab824574abc19c0776ca0210e764561d0ef6d621f2bbbea316eccfe56b" +} +``` + +Send the enclave key in the `data` field, and the [privacy precompile address](../../reference/api/index.md#priv_getprivacyprecompileaddress) in the `to` field of `eth_sendRawTransaction`: + +```json +{ + "jsonrpc": "2.0", + "method": "eth_sendRawTransaction", + "params": [ + { + "from": "0xfe3b557e8fb62b89f4916b721be55ceb828dbd73", + "to": "0x000000000000000000000000000000000000007e", + "data": "0xfd0d90ab824574abc19c0776ca0210e764561d0ef6d621f2bbbea316eccfe56b", + "gas": "0x2E1800", + "gasPrice": "0x9184e72a000" + } + ], + "id": 1 +} +``` + +## EEA-compliant or Besu-extended privacy + +To create an [EEA-compliant private transaction], specify `privateFor` when creating the signed transaction passed as an input parameter to [`eea_sendRawTransaction`](../../reference/api/index.md#eea_sendrawtransaction). + +To create a [Besu-extended private transaction], specify a `privacyGroupId` when creating the signed transaction passed as an input parameter to [`eea_sendRawTransaction`](../../reference/api/index.md#eea_sendrawtransaction). + +## Unsigned and unencoded private transactions + +The [`eea_sendRawTransaction`](../../reference/api/index.md#eea_sendrawtransaction) parameter is a signed RLP-encoded private transaction. Shown below are examples of unsigned and unencoded private transactions to create a contract. + +```json title="Unencoded and unsigned EEA-compliant private transaction" +{ + "to": null, + "from": "0xfe3b557e8fb62b89f4916b721be55ceb828dbd73", + "gas": "0x7600", + "gasPrice": "0x0", + "data": "0x608060405234801561001057600080fd5b5060dc8061001f6000396000f3006080604052600436106049576000357c0100000000000000000000000000000000000000000000000000000000900463ffffffff1680633fa4f24514604e57806355241077146076575b600080fd5b348015605957600080fd5b50606060a0565b6040518082815260200191505060405180910390f35b348015608157600080fd5b50609e6004803603810190808035906020019092919050505060a6565b005b60005481565b80600081905550505600a165627a7a723058202bdbba2e694dba8fff33d9d0976df580f57bff0a40e25a46c398f8063b4c00360029", + "nonce": "0x0", + "privateFrom": "negmDcN2P4ODpqn/6WkJ02zT/0w0bjhGpkZ8UP6vARk=", + "privateFor": [ + "g59BmTeJIn7HIcnq8VQWgyh/pDbvbt2eyP0Ii60aDDw=", + "6fg8q5rWMBoAT2oIiU3tYJbk4b7oAr7dxaaVY7TeM3U=" + ], + "restriction": "restricted" +} +``` + +```json title="Unencoded and unsigned Besu-extended private transaction" +{ + "to": null, + "from": "0xfe3b557e8fb62b89f4916b721be55ceb828dbd73", + "gas": "0x7600", + "gasPrice": "0x0", + "data": "0x608060405234801561001057600080fd5b5060dc8061001f6000396000f3006080604052600436106049576000357c0100000000000000000000000000000000000000000000000000000000900463ffffffff1680633fa4f24514604e57806355241077146076575b600080fd5b348015605957600080fd5b50606060a0565b6040518082815260200191505060405180910390f35b348015608157600080fd5b50609e6004803603810190808035906020019092919050505060a6565b005b60005481565b80600081905550505600a165627a7a723058202bdbba2e694dba8fff33d9d0976df580f57bff0a40e25a46c398f8063b4c00360029", + "nonce": "0x0", + "privateFrom": "negmDcN2P4ODpqn/6WkJ02zT/0w0bjhGpkZ8UP6vARk=", + "privacyGroupId": "kAbelwaVW7okoEn1+okO+AbA4Hhz/7DaCOWVQz9nx5M=", + "restriction": "restricted" +} +``` + +:::tip + +The `example` directory in the [web3js-quorum client library](../use-privacy/web3js-quorum.md) contains examples of signing and encoding private transactions. + +::: + + + +[EEA-compliant private transaction]: ../../concepts/privacy/privacy-groups.md#enterprise-ethereum-alliance-privacy +[Besu-extended private transaction]: ../../concepts/privacy/privacy-groups.md#besu-extended-privacy diff --git a/versioned_docs/version-23.10.1/private-networks/how-to/send-transactions/revert-reason.md b/versioned_docs/version-23.10.1/private-networks/how-to/send-transactions/revert-reason.md new file mode 100644 index 00000000000..da206b31e80 --- /dev/null +++ b/versioned_docs/version-23.10.1/private-networks/how-to/send-transactions/revert-reason.md @@ -0,0 +1,148 @@ +--- +title: Include revert reason +description: Including revert reason in transactions with Hyperledger Besu +sidebar_position: 3 +tags: + - private networks +--- + +# Revert reason + +In smart contracts, the [`revert`](https://docs.soliditylang.org/en/v0.8.12/control-structures.html#revert) operation triggers an exception to flag an error and revert the current call. The EVM passes back to the client an optional string message containing information about the error. + +```sol +pragma solidity ^0.8.4; + +contract VendingMachine { + address owner; + constructor() { + owner = msg.sender; + } + error Unauthorized(); + function buy(uint amount) public payable { + if (amount > msg.value / 2 ether) + revert("Not enough Ether provided."); + // Alternative way to do it: + require( + amount <= msg.value / 2 ether, + "Not enough Ether provided." + ); + // Perform the purchase. + } + function withdraw() public { + if (msg.sender != owner) + revert Unauthorized(); + + payable(msg.sender).transfer(address(this).balance); + } +} +``` + +## Enable revert reason + +Use the [`--revert-reason-enabled`](../../../public-networks/reference/cli/options.md#revert-reason-enabled) command line option to include the revert reason in the transaction receipt and the [`trace`](../../../public-networks/reference/trace-types.md#trace) response in Hyperledger Besu. + +:::caution + +Enabling revert reason may use a significant amount of memory. We do not recommend enabling revert reason when connected to public Ethereum networks. + +::: + +## Where the revert reason is included + +With revert reason enabled, the transaction receipt returned by [`eth_getTransactionReceipt`](../../../public-networks/reference/api/index.md#eth_gettransactionreceipt) includes the revert reason as an ABI-encoded string. + +:::info + +The revert reason is not included in the transaction receipt's root hash. Not including the revert reason in the transactions receipt's root hash means the revert reason is only available to nodes that execute the transaction when importing the block. That is, the revert reason is not available if using fast synchronization ([`--sync-mode=FAST`](../../../public-networks/reference/cli/options.md#sync-mode)). + +::: + +```json title="Example of transaction receipt" +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + "blockHash": "0xe7212a92cfb9b06addc80dec2a0dfae9ea94fd344efeb157c41e12994fcad60a", + "blockNumber": "0x50", + "contractAddress": null, + "cumulativeGasUsed": "0x5208", + "from": "0x627306090abab3a6e1400e9345bc60c78a8bef57", + "gasUsed": "0x5208", + "logs": [], + "logsBloom": "0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000", + "status": "0x1", + "to": "0xf17f52151ebef6c7334fad080c5704d77216b732", + "transactionHash": "0xc00e97af59c6f88de163306935f7682af1a34c67245e414537d02e422815efc3", + "transactionIndex": "0x0", + "revertReason": "0x08c379a00000000000000000000000000000000000000000000000000000000000000020000000000000000000000000000000000000000000000000000000000000001a4e6f7420656e6f7567682045746865722070726f76696465642e000000000000" + } +} +``` + +With revert reason enabled, the list items in the [`trace`](../../../public-networks/reference/trace-types.md#trace) response returned by [`trace_replayBlockTransactions`](../../../public-networks/reference/api/index.md#trace_replayblocktransactions), [`trace_block`](../../../public-networks/reference/api/index.md#trace_block), and [`trace_transaction`](../../../public-networks/reference/api/index.md#trace_transaction) include the revert reason as an ABI-encoded string. + +```json title="Example of trace response list item" +{ + "jsonrpc": "2.0", + "id": 415, + "result": [ + { + "action": { + "callType": "call", + "from": "0xfe3b557e8fb62b89f4916b721be55ceb828dbd73", + "gas": "0xffadea", + "input": "0x", + "to": "0x0110000000000000000000000000000000000000", + "value": "0x0" + }, + "blockHash": "0x220bc13dc4f1ed38dcca927a5be15eca16497d279f4c40d7b8fe9704eadf1464", + "blockNumber": 18, + "error": "Reverted", + "revertReason": "0x7d88c1856cc95352", + "subtraces": 0, + "traceAddress": [], + "transactionHash": "0xc388baa0e55e6b73e850b22dc7e9853700f6b995fd55d95dd6ccd5a13d63c566", + "transactionPosition": 1, + "type": "call" + } + ] +} +``` + +By default, the error returned by [`eth_estimateGas`](../../../public-networks/reference/api/index.md#eth_estimategas) and [`eth_call`](../../../public-networks/reference/api/index.md#eth_call) includes the revert reason as an ABI-encoded string in the `data` field. + +```json title="Example of eth_estimateGas and eth_call error" +{ + "jsonrpc": "2.0", + "id": 3, + "error": { + "code": -32000, + "message": "Execution reverted: ERC20: transfer amount exceeds balance", + "data": "0x08c379a00000000000000000000000000000000000000000000000000000000000000020000000000000000000000000000000000000000000000000000000000000001a4e6f7420656e6f7567682045746865722070726f76696465642e000000000000" + } +} +``` + +## Revert reason format + +As described in the [Solidity documentation], the revert reason is an ABI-encoded string consisting of: + +```bash +0x08c379a0 // Function selector for Error(string) +0x0000000000000000000000000000000000000000000000000000000000000020 // Data offset +0x000000000000000000000000000000000000000000000000000000000000001a // String length +0x4e6f7420656e6f7567682045746865722070726f76696465642e000000000000 // String data +``` + +```bash title="Example of revert reason string for 'Not enough Ether provided' " +"0x08c379a00000000000000000000000000000000000000000000000000000000000000020000000000000000000000000000000000000000000000000000000000000001a4e6f7420656e6f7567682045746865722070726f76696465642e000000000000" +``` + +## Dapp support + +Client libraries, such as web3j, do not support extracting the revert reason from the transaction receipt. To extract the revert reason your dapp must interact directly with Besu using a custom JSON -> Object converter. + + + +[Solidity documentation]: https://docs.soliditylang.org/en/v0.8.12/control-structures.html#revert diff --git a/versioned_docs/version-23.10.1/private-networks/how-to/upgrade.md b/versioned_docs/version-23.10.1/private-networks/how-to/upgrade.md new file mode 100644 index 00000000000..9d985eeb6e4 --- /dev/null +++ b/versioned_docs/version-23.10.1/private-networks/how-to/upgrade.md @@ -0,0 +1,44 @@ +--- +title: Upgrade +description: Upgrading protocol versions +sidebar_position: 8 +tags: + - private networks +--- + +# Network and protocol upgrades + +:::info + +Node upgrades upgrade your Besu client to a later version. In private networks, you can [upgrade your node](../../public-networks/how-to/upgrade-node.md) as in public networks. + +::: + +Network upgrades are the mechanism for upgrading the Ethereum protocol. Protocol upgrades occur during the network upgrades. + +For Ethereum Mainnet and public testnets, the milestone block definitions are included in Besu. Upgrading your Besu client applies the network upgrade. + +For private networks, all network participants must agree on the protocol upgrades and coordinate the network upgrades. The genesis file specifies the milestone block at which to apply the protocol upgrade. + +## Upgrade the protocol + +To upgrade the protocol in a private network: + +1. Review included EIPs for breaking changes. A [meta EIP](https://eips.ethereum.org/meta) for each protocol upgrade lists included EIPs. For example, [Istanbul](https://eips.ethereum.org/EIPS/eip-1679). +1. Network participants agree on the block number at which to upgrade. +1. For each node in the network: + 1. Add the [milestone block number](../../public-networks/reference/genesis-items.md#milestone-blocks) to the genesis file. + 1. Restart the node before reaching milestone block. + +:::caution + +To avoid a forked network, all network participants must update their genesis file to include the agreed on milestone block and restart their node before reaching the milestone block. + +::: + +:::tip + +- For compatibility with future protocol upgrades, don't hardcode any gas price assumptions. +- Implementing upgradeable contracts enables contracts to be upgraded if a protocol upgrade does include breaking changes. + +::: diff --git a/versioned_docs/version-23.10.1/private-networks/how-to/use-permissioning/_category_.json b/versioned_docs/version-23.10.1/private-networks/how-to/use-permissioning/_category_.json new file mode 100644 index 00000000000..cbca3cfba02 --- /dev/null +++ b/versioned_docs/version-23.10.1/private-networks/how-to/use-permissioning/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Use permissioning", + "position": 5 +} diff --git a/versioned_docs/version-23.10.1/private-networks/how-to/use-permissioning/local.md b/versioned_docs/version-23.10.1/private-networks/how-to/use-permissioning/local.md new file mode 100644 index 00000000000..c1269a66d9e --- /dev/null +++ b/versioned_docs/version-23.10.1/private-networks/how-to/use-permissioning/local.md @@ -0,0 +1,191 @@ +--- +title: Use local permissioning +sidebar_position: 1 +description: Hyperledger Besu local permissioning +tags: + - private networks +--- + +# Use local permissioning + +[Local permissioning](../../concepts/permissioning/index.md#local) supports node and account allowlisting. + +## Node allowlisting + +You can allow access to specified nodes in the [permissions configuration file](#permissions-configuration-file). With node allowlisting enabled, communication is only between nodes in the allowlist. + +:::info + +Node allowlists [support domain names] in enode URLs as an early access feature. Use the `--Xdns-enabled` option to enable domain name support. + +If using Kubernetes, enable domain name support and use the `--Xdns-update-enabled` option to ensure that Besu can connect to a container after being restarted, even if the IP address of the container changes. + +::: + +:::info Nodes allowlist in the permissions configuration file + +`nodes-allowlist=["enode://6f8a80d14311c39f35f516fa664deaaaa13e85b2f7493f37f6144d86991ec012937307647bd3b9a82abe2974e1407241d54947bbb39763a4cac9f77166ad92a0@192.168.0.9:4567","enode://6f8a80d14311c39f35f516fa664deaaaa13e85b2f7493f37f6144d86991ec012937307647bd3b9a82abe2974e1407241d54947bbb39763a4cac9f77166ad92a0@192.169.0.9:4568"]` + +::: + +Node allowlisting is at the node level. That is, each node in the network has a [permissions configuration file](#permissions-configuration-file) file in the [data directory](../../../public-networks/reference/cli/options.md#data-path) for the node. + +Local permissioning doesn't check that the node using the permissions configuration file is listed in the allowlist, it only checks that the remote end of the connection is in the allowlist. Use [onchain permissioning] if you need to check both ends of the connection. + +### Specify bootnodes in the allowlist + +The nodes permissions list must include the [bootnodes](../configure/bootnodes.md) or Hyperledger Besu doesn't start with node permissions enabled. + +If you start Besu with specified bootnodes and have node permissioning enabled: + +```bash +--bootnodes="enode://7e4ef30e9ec683f26ad76ffca5b5148fa7a6575f4cfad4eb0f52f9c3d8335f4a9b6f9e66fcc73ef95ed7a2a52784d4f372e7750ac8ae0b544309a5b391a23dd7@127.0.0.1:30303","enode://2feb33b3c6c4a8f77d84a5ce44954e83e5f163e7a65f7f7a7fec499ceb0ddd76a46ef635408c513d64c076470eac86b7f2c8ae4fcd112cb28ce82c0d64ec2c94@127.0.0.1:30304","enode://7b61d5ee4b44335873e6912cb5dd3e3877c860ba21417c9b9ef1f7e500a82213737d4b269046d0669fb2299a234ca03443f25fe5f706b693b3669e5c92478ade@127.0.0.1:30305" +``` + +The `nodes-allowlist` in the [permissions configuration file](#permissions-configuration-file) must contain the specified bootnodes. + +:::tip + +If your node has two different IP addresses for ingress and egress (for example, if you use Kubernetes implementing a load balancer for ingress and a NAT gateway IP address for egress), add both addresses to the allowlist, using the same public key for each IP address. This will allow the node to connect. + +::: + +### Enable node allowlisting + +To enable node allowlisting, specify the [`--permissions-nodes-config-file-enabled`](../../reference/cli/options.md#permissions-nodes-config-file-enabled) option when starting Besu. + +The `PERM` API methods are not enabled by default. To enable the `PERM` API methods, use the [`--rpc-http-api`](../../../public-networks/reference/cli/options.md#rpc-http-api) or [`--rpc-ws-api`](../../../public-networks/reference/cli/options.md#rpc-ws-api) options. + +### Update the node allowlist + +To update the nodes allowlist while the node is running, use the following JSON-RPC API methods: + +- [perm_addNodesToAllowlist](../../reference/api/index.md#perm_addnodestoallowlist) +- [perm_removeNodesFromAllowlist](../../reference/api/index.md#perm_removenodesfromallowlist) + +You can also update the [`permissions_config.toml`](#permissions-configuration-file) file directly and then update the allowlist using the [`perm_reloadPermissionsFromFile`](../../reference/api/index.md#perm_reloadpermissionsfromfile) method. + +Updates to the permissions configuration file persist across node restarts. + +### View the node allowlist + +To view the nodes allowlist, use the [perm_getNodesAllowlist](../../reference/api/index.md#perm_getnodesallowlist) method. + +:::note + +Each node has a [permissions configuration file](#permissions-configuration-file), which means nodes can have different nodes allowlists. This means nodes might be participating in the network that are not on the allowlist of other nodes in the network. We recommend each node in the network has the same nodes allowlist. + +::: + +```bash Example of different node allowlists + +Node 1 Allowlist = [Node 2, Node 3] + +Node 2 Allowlist = [Node 3, Node 5] + +Node 5 is participating in the same network as Node 1 even though Node 1 does not have Node 5 +on their allowlist. +``` + +## Account allowlisting + +You can specify accounts in the accounts allowlist in the [permissions configuration file](#permissions-configuration-file). A node with account permissioning accepts transactions only from accounts in the accounts allowlist. + +:::info Accounts allowlist in the permissions configuration file + +`accounts-allowlist=["0x0000000000000000000000000000000000000009"]` + +::: + +Account allowlisting is at the node level. That is, each node in the network has a [permissions configuration file](#permissions-configuration-file) in the [data directory](../../../public-networks/reference/cli/options.md#data-path) for the node. + +:::caution Using account permissioning and privacy + +Account permissioning is incompatible with [random key signing](../use-privacy/sign-pmts.md) for [privacy marker transactions](../../concepts/privacy/private-transactions/processing.md). + +If using account permissioning and privacy, a signing key must be specified using the [`--privacy-marker-transaction-signing-key-file`](../../reference/cli/options.md#privacy-marker-transaction-signing-key-file) command line option and the corresponding public key included in the accounts allowlist. + +::: + +Transaction validation against the accounts allowlist occurs at the following points: + +- Submitted by JSON-RPC API method [`eth_sendRawTransaction`](../../../public-networks/reference/api/index.md#eth_sendrawtransaction) +- Received via propagation from another node +- Added to a block by a mining node + +After adding transactions to a block, the transactions are not validated against the allowlist when received by another node. That is, a node can synchronize and add blocks containing transactions from accounts that are not on the accounts allowlist of that node. + +The following diagram illustrates applying local and onchain permissioning rules. + +![Permissioning Flow](../../../assets/images/PermissioningFlow.png) + +```bash title="Example of different account allowlists" + +Node 1 Allowlist = [Account A, Account B] + +Node 2 Allowlist = [Account B, Account C] + +Mining Node Allowlist = [Account A, Account B] + +Account A submits a transaction on Node 1. Node 1 validates and propagates the transaction. The +Mining Node receives the transaction, validates it is from an account in the Mining Node +accounts allowlist, and includes the transaction in the block. Node 2 receives and adds +the block created by the Mining Node. + +Node 2 now has a transaction in the blockchain from Account A, which is not on the accounts +allowlist for Node 2. + +``` + +:::note + +Each node has a [permissions configuration file](#permissions-configuration-file) which means nodes in the network can have different accounts allowlists. This means a transaction can be successfully submitted by Node A from an account in the Node A allowlist but rejected by Node B to which it's propagated if the account is not in the Node B allowlist. We recommend each node in the network has the same accounts allowlist. + +::: + +### Enable account allowlisting + +To enable account allowlisting, specify the [`--permissions-accounts-config-file-enabled`](../../reference/cli/options.md#permissions-accounts-config-file-enabled) option when starting Besu. + +The `PERM` API methods are not enabled by default. To enable the `PERM` API methods, use the [`--rpc-http-api`](../../../public-networks/reference/cli/options.md#rpc-http-api) or [`--rpc-ws-api`](../../../public-networks/reference/cli/options.md#rpc-ws-api) options. + +### Update the account allowlist + +To update the accounts allowlist when the node is running, use the JSON-RPC API methods: + +- [`perm_addAccountsToAllowlist`](../../reference/api/index.md#perm_addaccountstoallowlist) +- [`perm_removeAccountsFromAllowlist`](../../reference/api/index.md#perm_removeaccountsfromallowlist). + +You can also update the [`permissions_config.toml`](#permissions-configuration-file) file directly and use the [`perm_reloadPermissionsFromFile`](../../reference/api/index.md#perm_reloadpermissionsfromfile) method to update the allowlists. + +Updates to the permissions configuration file persist across node restarts. + +### View the account allowlist + +To view the accounts allowlist, use the [`perm_getAccountsAllowlist`](../../reference/api/index.md#perm_getaccountsallowlist) method. + +## Permissions configuration file + +The permissions configuration file contains the nodes and accounts allowlists. If the [`--permissions-accounts-config-file`](../../reference/cli/options.md#permissions-accounts-config-file) and [`--permissions-nodes-config-file`](../../reference/cli/options.md#permissions-nodes-config-file) options are not specified, the name of the permissions configuration file must be [`permissions_config.toml`](#permissions-configuration-file) and must be in the [data directory](../../../public-networks/reference/cli/options.md#data-path) for the node. + +You can specify the accounts and nodes allowlists in the same file or in separate files for accounts and nodes. + +To specify a permissions configuration file (or separate files for accounts and nodes) in any location, use the [`--permissions-accounts-config-file`](../../reference/cli/options.md#permissions-accounts-config-file) and [`--permissions-nodes-config-file`](../../reference/cli/options.md#permissions-nodes-config-file) options. + +:::note + +The [`--permissions-accounts-config-file`](../../reference/cli/options.md#permissions-accounts-config-file) and [`permissions-nodes-config-file`](../../reference/cli/options.md#permissions-nodes-config-file) options are not used when running Besu from the [Docker image](../../get-started/install/run-docker-image.md). Use a bind mount to [specify a permissions configuration file with Docker]. + +::: + +```toml title="Sample permissions configuration file" +accounts-allowlist=["0xb9b81ee349c3807e46bc71aa2632203c5b462032", "0xb9b81ee349c3807e46bc71aa2632203c5b462034"] + +nodes-allowlist=["enode://7e4ef30e9ec683f26ad76ffca5b5148fa7a6575f4cfad4eb0f52f9c3d8335f4a9b6f9e66fcc73ef95ed7a2a52784d4f372e7750ac8ae0b544309a5b391a23dd7@127.0.0.1:30303","enode://2feb33b3c6c4a8f77d84a5ce44954e83e5f163e7a65f7f7a7fec499ceb0ddd76a46ef635408c513d64c076470eac86b7f2c8ae4fcd112cb28ce82c0d64ec2c94@127.0.0.1:30304","enode://7b61d5ee4b44335873e6912cb5dd3e3877c860ba21417c9b9ef1f7e500a82213737d4b269046d0669fb2299a234ca03443f25fe5f706b693b3669e5c92478ade@127.0.0.1:30305"] +``` + + + +[specify a permissions configuration file with Docker]: ../../get-started/install/run-docker-image.md +[support domain names]: ../../../public-networks/concepts/node-keys.md#domain-name-support +[onchain permissioning]: ../../concepts/permissioning/onchain.md diff --git a/versioned_docs/version-23.10.1/private-networks/how-to/use-permissioning/onchain.md b/versioned_docs/version-23.10.1/private-networks/how-to/use-permissioning/onchain.md new file mode 100644 index 00000000000..4b177026a20 --- /dev/null +++ b/versioned_docs/version-23.10.1/private-networks/how-to/use-permissioning/onchain.md @@ -0,0 +1,60 @@ +--- +title: Use onchain permissioning +sidebar_position: 2 +description: Use onchain permissioning allowlists +tags: + - private networks +--- + +# Use onchain permissioning + +This page contains some extra info if you're using [onchain permissioning](../../concepts/permissioning/onchain.md). + +:::tip + +If your node has two different IP addresses for ingress and egress (for example, if you use Kubernetes implementing a load balancer for ingress and a NAT gateway IP address for egress), add both addresses to the allowlist, using the same public key for each IP address. This will allow the node to connect. + +::: + +:::important + +Node allowlists [support domain names] in enode URLs as an early access feature. Use the `--Xdns-enabled` option to enable domain name support. + +If using Kubernetes, enable domain name support and use the `--Xdns-update-enabled` option to ensure that Besu can connect to a container after being restarted, even if the IP address of the container changes. + +::: + +:::tip + +If you add a running node, the node does not attempt to reconnect to the bootnode and synchronize until peer discovery restarts. To add an allowlisted node as a peer without waiting for peer discovery to restart, use [`admin_addPeer`](../../../public-networks/reference/api/index.md#admin_addpeer). + +If you add the node to the allowlist before starting the node, using `admin_addPeer` is not required because peer discovery is run on node startup. + +::: + +:::tip + +If nodes are not connecting as expected, set the [log level to `TRACE`](../../../public-networks/reference/cli/options.md#logging) and search for messages containing `Node permissioning` to identify the issue. + +Ensure the [`--p2p-host`](../../../public-networks/reference/cli/options.md#p2p-host) command line option has been correctly configured for all nodes with the externally accessible address. + +If you change your network configuration, you may need to update the node allowlist. + +::: + +## Specify the permissioning contract interface version + +Use the [`--permissions-nodes-contract-version`](../../reference/cli/options.md#permissions-nodes-contract-version) command line option to specify the version of the [permissioning contract interface](../../concepts/permissioning/onchain.md#permissioning-contracts). The default is 1. + +Specify the contract interface version that maps to the version of the [Enterprise Ethereum Alliance Client Specification](https://entethalliance.org/technical-specifications/) the contract interface implements. + +| | EEA Client Specification | Contract interface | +| :------ | :----------------------- | :----------------- | +| Version | 5 | 1 | +| Version | 6 | 2 | + +The permissioning contracts in the [`ConsenSys/permissioning-smart-contracts`](https://github.com/ConsenSys/permissioning-smart-contracts) repository implement the version 2 contract interface. + +[support domain names]: ../../../public-networks/concepts/node-keys.md#domain-name-support +[projects release page]: https://github.com/ConsenSys/permissioning-smart-contracts/releases/latest +[onchain permissioning tutorial]: ../../tutorials/permissioning/onchain.md diff --git a/versioned_docs/version-23.10.1/private-networks/how-to/use-privacy/_category_.json b/versioned_docs/version-23.10.1/private-networks/how-to/use-privacy/_category_.json new file mode 100644 index 00000000000..f2a1d4ca864 --- /dev/null +++ b/versioned_docs/version-23.10.1/private-networks/how-to/use-privacy/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Use privacy", + "position": 4 +} diff --git a/versioned_docs/version-23.10.1/private-networks/how-to/use-privacy/access-private-transactions.md b/versioned_docs/version-23.10.1/private-networks/how-to/use-privacy/access-private-transactions.md new file mode 100644 index 00000000000..611f57269a3 --- /dev/null +++ b/versioned_docs/version-23.10.1/private-networks/how-to/use-privacy/access-private-transactions.md @@ -0,0 +1,33 @@ +--- +title: Access private and privacy marker transactions +description: Methods for accessing and managing private transactions and privacy groups in Hyperledger Besu +sidebar_position: 6 +tags: + - private networks +--- + +# Access private and privacy marker transactions + +A Hyperledger Besu private transaction creates a [privacy marker transaction](../../concepts/privacy/private-transactions/processing.md) and the private transaction itself. + +## Transaction receipts + +With the transaction hash returned when submitting the private transaction, to get the transaction receipt for the: + +- Private transaction, use [`priv_getTransactionReceipt`](../../reference/api/index.md#priv_gettransactionreceipt). +- Privacy marker transaction, use [`eth_getTransactionReceipt`](../../../public-networks/reference/api/index.md#eth_gettransactionreceipt). + +The transaction receipt includes a `status` indicating if the transaction failed (`0x0`), succeeded (`0x1`), or was invalid (`0x2`). + +:::note Private transaction failure example + +To deploy a private contract, you submit a transaction using [`eea_sendRawTransaction`](../send-transactions/private-transactions.md). If contract deployment fails because of insufficient gas, the privacy marker transaction receipt has a status of success and the private transaction receipt has a status of failure. + +::: + +## Transactions + +With the transaction hash returned when submitting the private transaction, to get the: + +- Private transaction, use [`priv_getPrivateTransaction`](../../reference/api/index.md#priv_getprivatetransaction). +- Privacy marker transaction, use [`eth_getTransactionByHash`](../../../public-networks/reference/api/index.md#eth_gettransactionbyhash). diff --git a/versioned_docs/version-23.10.1/private-networks/how-to/use-privacy/besu-extended.md b/versioned_docs/version-23.10.1/private-networks/how-to/use-privacy/besu-extended.md new file mode 100644 index 00000000000..40c1c7d365e --- /dev/null +++ b/versioned_docs/version-23.10.1/private-networks/how-to/use-privacy/besu-extended.md @@ -0,0 +1,40 @@ +--- +title: Use Besu-extended privacy +description: Hyperledger Besu-extended privacy +sidebar_position: 2 +tags: + - private networks +--- + +# Use Besu-extended privacy + +Hyperledger Besu provides an extended implementation of privacy allowing you to [create a privacy group for a set of participants](../../concepts/privacy/privacy-groups.md). You must specify the privacy group ID when sending private transactions. + +To enable the [`PRIV` API methods](../../reference/api/index.md#priv-methods), use the [`--rpc-http-api`](../../../public-networks/reference/cli/options.md#rpc-http-api) or [`--rpc-ws-api`](../../../public-networks/reference/cli/options.md#rpc-ws-api) command line options. + +To create the privacy group containing the recipients of a private transaction, use [`priv_createPrivacyGroup`](../../reference/api/index.md#priv_createprivacygroup). + +To create an EEA-compliant private transaction, specify `privacyGroupId` when creating the signed transaction passed as an input parameter to [`eea_sendRawTransaction`](../../reference/api/index.md#eea_sendrawtransaction). + +## Privacy group type + +Privacy groups created using [`priv_createPrivacyGroup`](../../reference/api/index.md#priv_createprivacygroup) have a `BESU` privacy group type when returned by [`priv_findPrivacyGroup`](../../reference/api/index.md#priv_findprivacygroup). + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": [ + { + "privacyGroupId": "GpK3ErNO0xF27T0sevgkJ3+4qk9Z+E3HtXYxcKIBKX8=", + "name": "Group B", + "description": "Description of Group B", + "type": "BESU", + "members": [ + "negmDcN2P4ODpqn/6WkJ02zT/0w0bjhGpkZ8UP6vARk=", + "g59BmTeJIn7HIcnq8VQWgyh/pDbvbt2eyP0Ii60aDDw=" + ] + } + ] +} +``` diff --git a/versioned_docs/version-23.10.1/private-networks/how-to/use-privacy/eea-compliant.md b/versioned_docs/version-23.10.1/private-networks/how-to/use-privacy/eea-compliant.md new file mode 100644 index 00000000000..300c0b987fd --- /dev/null +++ b/versioned_docs/version-23.10.1/private-networks/how-to/use-privacy/eea-compliant.md @@ -0,0 +1,38 @@ +--- +title: Use EEA-compliant privacy +description: Hyperledger Besu JSON-RPC methods to use for EEA-compliant privacy +sidebar_position: 1 +tags: + - private networks +--- + +# Use EEA-compliant privacy + +When using Hyperledger Besu [EEA-compliant privacy](../../concepts/privacy/privacy-groups.md), the group of nodes specified by `privateFrom` and `privateFor` form a privacy group, to which Tessera assigns a unique privacy group ID. + +To enable the [`EEA` API methods](../../reference/api/index.md#eea-methods), use the [`--rpc-http-api`](../../../public-networks/reference/cli/options.md#rpc-http-api) or [`--rpc-ws-api`](../../../public-networks/reference/cli/options.md#rpc-ws-api) command line options. + +To create an EEA-compliant private transaction, specify `privateFor` when creating the signed transaction passed as an input parameter to [`eea_sendRawTransaction`](../../reference/api/index.md#eea_sendrawtransaction). + +## Privacy group type + +Privacy groups created when specifying `privateFrom` and `privateFor` have a `LEGACY` privacy group type when returned by [`priv_findPrivacyGroup`](../../reference/api/index.md#priv_findprivacygroup). + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": [ + { + "privacyGroupId": "68/Cq0mVjB8FbXDLE1tbDRAvD/srluIok137uFOaClM=", + "name": "legacy", + "description": "Privacy groups to support the creation of groups by privateFor and privateFrom", + "type": "LEGACY", + "members": [ + "g59BmTeJIn7HIcnq8VQWgyh/pDbvbt2eyP0Ii60aDDw=", + "negmDcN2P4ODpqn/6WkJ02zT/0w0bjhGpkZ8UP6vARk=" + ] + } + ] +} +``` diff --git a/versioned_docs/version-23.10.1/private-networks/how-to/use-privacy/flexible.md b/versioned_docs/version-23.10.1/private-networks/how-to/use-privacy/flexible.md new file mode 100644 index 00000000000..abf1892732b --- /dev/null +++ b/versioned_docs/version-23.10.1/private-networks/how-to/use-privacy/flexible.md @@ -0,0 +1,62 @@ +--- +title: Use flexible privacy groups +description: Use flexible privacy groups +sidebar_position: 5 +tags: + - private networks +--- + +# Use flexible privacy groups + +Use the [`web3js-quorum` library](https://github.com/ConsenSys/web3js-quorum) to create and update membership of [flexible privacy groups](../../concepts/privacy/flexible-privacy.md). + +:::tip + +Because group membership for flexible privacy groups is stored in a smart contract, flexible privacy groups are also known as onchain privacy groups. + +::: + +:::info + +[Flexible privacy groups](../../concepts/privacy/flexible-privacy.md) are an early access feature. Don't use in production networks. + +The flexible privacy group interfaces may change between releases. There might not be an upgrade path from flexible privacy groups created using v1.5 or earlier to enable use of flexible privacy group functionality in future versions. + +We don't recommend creating flexible privacy groups in a chain with existing [offchain privacy groups](../../concepts/privacy/privacy-groups.md). + +::: + +## Enable flexible privacy groups + +Use the [`--privacy-flexible-groups-enabled`](../../reference/cli/options.md#privacy-flexible-groups-enabled) command line option to enable [flexible privacy groups](../../concepts/privacy/flexible-privacy.md). When flexible privacy groups are enabled, the [`priv_createPrivacyGroup`](../../reference/api/index.md#priv_createprivacygroup), [`priv_deletePrivacyGroup`](../../reference/api/index.md#priv_deleteprivacygroup), and [`priv_findPrivacyGroup`](../../reference/api/index.md#priv_findprivacygroup) methods for [offchain privacy groups](../../concepts/privacy/privacy-groups.md) are disabled. + +## Simple flexible privacy group example + +To create and find a [flexible privacy group](../../concepts/privacy/flexible-privacy.md) using the [`web3js-quorum` library](https://github.com/ConsenSys/web3js-quorum): + +1. Update the `example/keys.js` file to match your network configuration. + +1. Run: + + ```bash + cd example/onchainPrivacy + node simpleExample.js + ``` + + This script creates the flexible privacy group with two members. `findPrivacyGroup` finds and displays the created privacy group. + +:::tip + +The Tessera logs for Tessera 1 and Tessera 2 display `PrivacyGroupNotFound` errors. This is expected behavior because private transactions check offchain and onchain to find the privacy group for a private transaction. + +::: + +## Add and remove members + +To add and remove members from a [flexible privacy group](../../concepts/privacy/flexible-privacy.md), use the `addTo` and `removeFrom` methods in the [`web3js-quorum` library](https://github.com/ConsenSys/web3js-quorum) client library. + +:::note + +When adding a member, Besu pushes all existing group transactions to the new member and processes them. If there are a large number of existing transactions, adding the member may take some time. + +::: diff --git a/versioned_docs/version-23.10.1/private-networks/how-to/use-privacy/performance-best-practices.md b/versioned_docs/version-23.10.1/private-networks/how-to/use-privacy/performance-best-practices.md new file mode 100644 index 00000000000..5559d610189 --- /dev/null +++ b/versioned_docs/version-23.10.1/private-networks/how-to/use-privacy/performance-best-practices.md @@ -0,0 +1,61 @@ +--- +title: Performance best practices +description: Performance best practices +sidebar_position: 10 +tags: + - private networks +--- + +# Performance best practices + +This document collects deployment and usage tips to help you achieve high performance for private transactions. If transaction throughput or latency is not meeting your expectations, please consider the following before raising an issue. + +## General performance + +Private transactions use the same facilities as public ones. General Besu performance tunings apply. Specific approaches are out of scope of this document, except for the following, which strongly impacts performance: + +### Use fast, local, solid state storage + +Running EVM transactions creates a lot of random reads that are executed sequentially. The Besu data folder for high throughput nodes should be located on the fastest possible storage media. + +- Prefer [NVMe](https://cloud.google.com/compute/docs/disks/local-ssd#performance) attached SLC flash or Intel Optane. +- Avoid network attached SSDs or cloud storage with limited input/output operations per second. +- Do not use spinning disks under any circumstances. + +## Private transaction performance + +### Use concurrent submission + +When submitting a private transaction using [web3js-quorum](https://github.com/ConsenSys/web3js-quorum), the submit call will only return once the privacy marker transaction has been included in a block. This limits the throughput to at most one private transaction per block when submitting from a single thread. To increase throughput, use web3js-quorum from multiple concurrent threads or processes. + +### Co-locate Besu and Tessera + +Besu has to talk to its local Tessera node frequently while handling a block. While we do not recommend running them on the same node, minimizing the latency between Besu and Tessera will improve block processing times. Besu and Tessera should not be hosted in geographically distributed locations. + +### Optimize worst-case latency between Tessera nodes + +When distributing a new private transaction between Tessera nodes, the overall throughput is determined by the slowest Tessera nodes. Try to minimize network latency between Tessera nodes and do not mix different machine types when hosting Tessera. + +### Use stateful nonce management + +Management of public and private nonces in web3js-quorum is stateless: before a transaction is sent, web3js-quorum has to query for those nonces. This is increasing latency, the node's load, and is a source of fragility due to nonce collision when multiple senders try to use the same account concurrently. + +For performance and reliability it is advantageous to manage nonces in a stateful manner on the client side instead of querying them for every transaction. If custom code for this is not an option, [Orchestrate](https://consensys.net/codefi/orchestrate/) can be used. + +### Use random senders for privacy marker transactions + +To avoid public nonce management, privacy marker transactions can be sent using a [random account per transaction](https://besu.hyperledger.org/en/stable/Reference/CLI/CLI-Syntax/#privacy-marker-transaction-signing-key-file). This option is only available for zero gas networks. + +### Avoid queuing transactions in Tessera + +When Tessera is overloaded with transactions, the performance breaks down catastrophically due to unbounded growth of the request queue. Avoid sending more transactions to Tessera than it can handle. Sudden jumps in submission latency and submission failure rate should be answered with a load reduction on the client side, for example using a back-off scheme. + +Please note that this is not Tessera specific but a general issue in distributed systems. It just happens that if queueing discipline is not maintained, Tessera tends to be the first component to fail. + +### Limit the group size to reduce communication overhead + +Smaller groups need fewer communication for transaction propagation. If reducing the number of Tessera nodes involved in a transaction is an option, it will lead to slightly better tail latencies. Multi-tenancy Tessera can be used to have large groups with a small number of Tessera nodes (possibly only one). + +### Limit group membership changes and make them quick + +Groups are locked (prevented from executing transactions) during membership changes. Try to minimize the number of times the membership changes. When possible, spread load across multiple groups to always have some groups available while others are locked. Consider batching group membership changes if possible. Note however that this does not work with the default management contract, yet. diff --git a/versioned_docs/version-23.10.1/private-networks/how-to/use-privacy/privacy-groups.md b/versioned_docs/version-23.10.1/private-networks/how-to/use-privacy/privacy-groups.md new file mode 100644 index 00000000000..1b3f0fadf23 --- /dev/null +++ b/versioned_docs/version-23.10.1/private-networks/how-to/use-privacy/privacy-groups.md @@ -0,0 +1,21 @@ +--- +title: Create and manage privacy groups +description: Create and manage privacy groups with Hyperledger Besu +sidebar_position: 4 +tags: + - private networks +--- + +# Create and manage privacy groups + +Hyperledger Besu-extended privacy provides JSON-RPC API methods for creating and managing privacy groups: + +- [`priv_createPrivacyGroup`](../../reference/api/index.md#priv_createprivacygroup) +- [`priv_findPrivacyGroup`](../../reference/api/index.md#priv_findprivacygroup) +- [`priv_deletePrivacyGroup`](../../reference/api/index.md#priv_deleteprivacygroup). + +:::tip + +You can find and delete [EEA-compliant privacy groups](../../concepts/privacy/privacy-groups.md) using [`priv_findPrivacyGroup`](../../reference/api/index.md#priv_findprivacygroup) and [`priv_deletePrivacyGroup`](../../reference/api/index.md#priv_deleteprivacygroup). + +::: diff --git a/versioned_docs/version-23.10.1/private-networks/how-to/use-privacy/sign-pmts.md b/versioned_docs/version-23.10.1/private-networks/how-to/use-privacy/sign-pmts.md new file mode 100644 index 00000000000..7ad0029f5d1 --- /dev/null +++ b/versioned_docs/version-23.10.1/private-networks/how-to/use-privacy/sign-pmts.md @@ -0,0 +1,39 @@ +--- +title: Sign privacy marker transactions +description: How to sign a privacy marker transaction with Hyperledger Besu +sidebar_position: 7 +tags: + - private networks +--- + +# Sign privacy marker transactions + +You can sign privacy marker transactions (PMTs) with either a random key or a specified key. To sign privacy marker transactions with a specified private key, use [`--privacy-marker-transaction-signing-key-file`](../../reference/cli/options.md#privacy-marker-transaction-signing-key-file) when starting Hyperledger Besu. + +:::note + +The private key file can be the same file used by [`--node-private-key-file`](#node-private-key-file), or a different key file to identify who signed the privacy marker transaction. + +::: + +In networks where you pay gas, you must specify a key and the associated account must contain adequate funds. + +In [free gas networks](../configure/free-gas.md), to provide further anonymity by signing each privacy marker transaction with a different random key, exclude the [`--privacy-marker-transaction-signing-key-file`](../../reference/cli/options.md#privacy-marker-transaction-signing-key-file) command line option when starting Besu. + +:::caution "Using account permissioning and privacy" + +You can't use [account permissioning] with random key signing. + +If using account permissioning and privacy, a signing key must be specified using the [`--privacy-marker-transaction-signing-key-file`](../../reference/cli/options.md#privacy-marker-transaction-signing-key-file) command line option and the corresponding public key included in the accounts allowlist. + +::: + +:::note + +Besu signs privacy marker transactions during the [private transaction process](../../concepts/privacy/private-transactions/processing.md). + +::: + + + +[account permissioning]: ../../concepts/permissioning/index.md#account-permissioning diff --git a/versioned_docs/version-23.10.1/private-networks/how-to/use-privacy/tessera.md b/versioned_docs/version-23.10.1/private-networks/how-to/use-privacy/tessera.md new file mode 100644 index 00000000000..02754f3fe8f --- /dev/null +++ b/versioned_docs/version-23.10.1/private-networks/how-to/use-privacy/tessera.md @@ -0,0 +1,41 @@ +--- +title: Run Tessera with Besu +description: Running ConsenSys Quorum Tessera with Hyperledger Besu +sidebar_position: 3 +tags: + - private networks +--- + +# Run Tessera with Besu + +To enable [privacy functionality](../../concepts/privacy/index.md) in production systems, [Tessera](https://docs.tessera.consensys.net/) must be [highly available](#high-availability) and [run in a separate instance](#separate-instances) to Hyperledger Besu. + +![Besu-Tessera-High-Availability](../../../assets/images/Besu-Tessera-High-Availability.png) + +:::note + +You can also configure Besu for high availability using load balancers. + +::: + +## High availability + +Privacy requires you to [configure Tessera for high availability]. Besu also requires [`orion` mode](https://docs.tessera.consensys.net/HowTo/Configure/Orion-Mode) to be enabled in Tessera. + +To successfully distribute a private transaction, all private transaction participants must be online. If any participants are offline when submitting the private transaction, the transaction is not attempted and you need to resubmit the transaction. + +If a Tessera node is unavailable when Besu attempts to process a privacy marker transaction, the Besu node stops processing all new blocks until Tessera is available. The Besu node continually attempts to process the privacy marker transaction until Tessera is available again. + +:::caution + +If Tessera becomes available but has lost data, Besu resumes processing blocks and the private states in the Besu nodes might become inconsistent. + +::: + +## Separate instances + +For production systems, we recommend running Besu and Tessera in separate instances. If running Besu and Tessera in the same instance, restrict the amount of memory used by each JVM to ensure each has enough memory. + + + +[configure Tessera for high availability]: https://consensys.net/docs/goquorum//en/stable/configure-and-manage/configure/high-availability/ diff --git a/versioned_docs/version-23.10.1/private-networks/how-to/use-privacy/web3js-quorum.md b/versioned_docs/version-23.10.1/private-networks/how-to/use-privacy/web3js-quorum.md new file mode 100644 index 00000000000..5538b3f9bc9 --- /dev/null +++ b/versioned_docs/version-23.10.1/private-networks/how-to/use-privacy/web3js-quorum.md @@ -0,0 +1,88 @@ +--- +title: Use the web3js-quorum library +description: web3js-quorum client library +sidebar_position: 9 +tags: + - private networks +--- + +# Use the web3js-quorum client library + +[web3js-quorum](https://github.com/ConsenSys/web3js-quorum) is an Ethereum JavaScript library extending [web3.js](https://github.com/ethereum/web3.js/) that adds support for Besu-specific JSON-RPC APIs and features. Use the library to create and send RLP-encoded transactions using JSON-RPC. + +:::caution important +web3js-quorum supports JSON-RPC over HTTP only. +::: + +:::note + +web3js-quorum includes all [quorum.js](https://github.com/ConsenSys/quorum.js) and [web3js-eea](https://github.com/ConsenSys/web3js-eea) features. + +If migrating to web3js-quorum, update your JavaScript code as indicated in the following examples. + +[Read the migration guide for more information about updating your code.](https://consensys.github.io/web3js-quorum/latest/tutorial-Migrate%20from%20web3js-eea.html) + +::: + +## Prerequisites + +- [Node.js (version > 10)](https://nodejs.org/en/download/) +- [The web3 library must be installed in your project](https://github.com/ChainSafe/web3.js#installation) + +## Add web3js-quorum to project + +```bash +npm install web3js-quorum +``` + +## Initialize the web3js-quorum client + +Initialize your client where: + +- `` is the JSON-RPC HTTP endpoint of your Hyperledger Besu node. Specified by the [`--rpc-http-host`](../../../public-networks/reference/cli/options.md#rpc-http-host) and [`--rpc-http-port`](../../../public-networks/reference/cli/options.md#rpc-http-port) command line options. + + + +# Syntax + +```js +const { Web3 } = require("web3"); +const Web3Quorum = require("web3js-quorum"); +const web3 = new Web3Quorum(new Web3("")); +``` + +# Example + +```js +const { Web3 } = require("web3"); +const Web3Quorum = require("web3js-quorum"); +const web3 = new Web3Quorum(new Web3("http://localhost:8545")); +``` + + + +:::note + +When migrating from web3js-eea to web3js-quorum, use `Web3Quorum`. The constructor doesn't require the chain ID anymore. Chain ID is automatically retrieved from the chain using the specified JSON-RPC HTTP endpoint. + +::: + +## Deploy a contract with `generateAndSendRawTransaction` + +To deploy a private contract, you need the contract binary. You can use [Solidity](https://solidity.readthedocs.io/en/develop/using-the-compiler.html) to get the contract binary. + +```js title="Deploying a contract with 'web3.priv.generateAndSendRawTransaction'" +const contractOptions = { + data: `0x123`, // contract binary + privateFrom: "tesseraNode1PublicKey", + privateFor: ["tesseraNode3PublicKey"], + privateKey: "besuNode1PrivateKey", +}; +return web3.priv.generateAndSendRawTransaction(contractOptions); +``` + +`web3.priv.generateAndSendRawTransaction(contractOptions)` returns the transaction hash. To get the private transaction receipt, use `web3.priv.waitForTransactionReceipt(txHash)`. + +## web3js-quorum methods + +For more information about the web3js-quorum methods, see the [web3js-quorum reference documentation](https://consensys.github.io/web3js-quorum/latest/index.html). diff --git a/versioned_docs/version-23.10.1/private-networks/index.md b/versioned_docs/version-23.10.1/private-networks/index.md new file mode 100644 index 00000000000..377c1af8e90 --- /dev/null +++ b/versioned_docs/version-23.10.1/private-networks/index.md @@ -0,0 +1,30 @@ +--- +title: Private networks +sidebar_position: 1 +sidebar_label: Introduction +id: index +description: Private networks overview +tags: + - private networks +--- + +# Hyperledger Besu for private networks + +You can use Besu to develop enterprise applications requiring secure, high-performance transaction processing in a private network. + +A private network is a network not connected to Ethereum Mainnet or an Ethereum testnet. Private networks typically use a different [chain ID](../public-networks/concepts/network-and-chain-id.md) and proof of authority consensus ([QBFT](how-to/configure/consensus/qbft.md), [IBFT 2.0](how-to/configure/consensus/ibft.md), or [Clique](how-to/configure/consensus/clique.md)). + +You can also [create a local development network](tutorials/ethash.md) using proof of work (Ethash). + +Besu supports enterprise features including [privacy](concepts/privacy/index.md) and [permissioning](concepts/permissioning/index.md). + +Get started with the [Developer Quickstart](tutorials/quickstart.md) to rapidly generate local blockchain networks. + +## Architecture + +The following diagram outlines the high-level architecture of Besu for private networks. + +![Private architecture](../assets/images/private-architecture.jpeg) + +If you have any questions about Besu for private networks, ask on the **besu** channel on +[Hyperledger Discord](https://discord.gg/hyperledger). diff --git a/versioned_docs/version-23.10.1/private-networks/reference/_category_.json b/versioned_docs/version-23.10.1/private-networks/reference/_category_.json new file mode 100644 index 00000000000..3ce2f2b757b --- /dev/null +++ b/versioned_docs/version-23.10.1/private-networks/reference/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Reference", + "position": 6 +} diff --git a/versioned_docs/version-23.10.1/private-networks/reference/accounts-for-testing.md b/versioned_docs/version-23.10.1/private-networks/reference/accounts-for-testing.md new file mode 100644 index 00000000000..f32a1dbf8a1 --- /dev/null +++ b/versioned_docs/version-23.10.1/private-networks/reference/accounts-for-testing.md @@ -0,0 +1,27 @@ +--- +title: Accounts for testing +sidebar_position: 3 +description: Ethereum accounts used for Hyperledger Besu testing only on private networks +tags: + - private networks +--- + +import TestAccounts from '../../global/test_accounts.md'; + +# Accounts for testing + +You can use existing accounts for testing by including them in the genesis file for a private network. Hyperledger Besu also provides predefined accounts for use in development mode. + +## Development mode + +When you start Besu with the [`--network=dev`](../../public-networks/reference/cli/options.md#network) command line option, Besu uses the `dev.json` genesis file by default. + +The `dev.json` genesis file defines the following accounts used for testing. + + + +## Genesis file + +To use existing test accounts, specify the accounts and balances in a genesis file for your test network. For an example of how to define accounts in the genesis file, see [`dev.json`](https://github.com/hyperledger/besu/blob/750580dcca349d22d024cc14a8171b2fa74b505a/config/src/main/resources/dev.json). + +To start Besu with the genesis file defining the existing accounts, use the [`--genesis-file`](../../public-networks/reference/cli/options.md#genesis-file) command line option . diff --git a/versioned_docs/version-23.10.1/private-networks/reference/api/_category_.json b/versioned_docs/version-23.10.1/private-networks/reference/api/_category_.json new file mode 100644 index 00000000000..777d7bb818f --- /dev/null +++ b/versioned_docs/version-23.10.1/private-networks/reference/api/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Besu API", + "position": 2 +} diff --git a/versioned_docs/version-23.10.1/private-networks/reference/api/index.md b/versioned_docs/version-23.10.1/private-networks/reference/api/index.md new file mode 100644 index 00000000000..7ff104b9338 --- /dev/null +++ b/versioned_docs/version-23.10.1/private-networks/reference/api/index.md @@ -0,0 +1,2157 @@ +--- +description: Hyperledger Besu private network JSON-RPC API methods reference +tags: + - private networks +--- + +# Private network API methods + +:::warning + +- This reference contains API methods that apply to only private networks. For API methods that apply to both private and public networks, see the [public network API reference](../../../public-networks/reference/api/index.md). +- All JSON-RPC HTTP examples use the default host and port endpoint `http://127.0.0.1:8545`. If using the [--rpc-http-host](../../../public-networks/reference/cli/options.md#rpc-http-host) or [--rpc-http-port](../../../public-networks/reference/cli/options.md#rpc-http-port) options, update the endpoint. + +::: + +## `CLIQUE` methods + +The `CLIQUE` API methods provide access to the [Clique](../../how-to/configure/consensus/clique.md) consensus engine. + +:::note + +The `CLIQUE` API methods are not enabled by default for JSON-RPC. To enable the `CLIQUE` API methods use the [`--rpc-http-api`](../../../public-networks/reference/cli/options.md#rpc-http-api) or [`--rpc-ws-api`](../../../public-networks/reference/cli/options.md#rpc-ws-api) options. + +::: + +### `clique_discard` + +Discards a proposal to [add or remove a signer with the specified address]. + +#### Parameters + +`address`: _string_ - 20-byte address of proposed signer + +#### Returns + +`result`: _boolean_ - indicates if the proposal is discarded + + + +# curl HTTP request + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"clique_discard","params":["0xFE3B557E8Fb62b89F4916B721be55cEb828dBd73"], "id":1}' http://127.0.0.1:8545 +``` + +# wscat WS request + +```bash +{"jsonrpc":"2.0","method":"clique_discard","params":["0xFE3B557E8Fb62b89F4916B721be55cEb828dBd73"], "id":1} +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": true +} +``` + + + +### `clique_getSigners` + +Lists [signers for the specified block]. + +#### Parameters + +`blockNumber`: _string_ - hexadecimal or decimal integer representing a block number or one of the string tags `latest`, `earliest`, `pending`, `finalized`, or `safe`, as described in [block parameter](../../../public-networks/how-to/use-besu-api/json-rpc.md#block-parameter) + +#### Returns + +`result`: _array_ of _string_ - list of 20-byte addresses of signers + + + +# curl HTTP request + + ```bash + curl -X POST --data '{"jsonrpc":"2.0","method":"clique_getSigners","params":["latest"], "id":1}' http://127.0.0.1:8545 + ``` + +# wscat WS request + + ```bash + {"jsonrpc":"2.0","method":"clique_getSigners","params":["latest"], "id":1} + ``` + +# JSON result + + ```json + { + "jsonrpc" : "2.0", + "id" : 1, + "result" : [ "0x42eb768f2244c8811c63729a21a3569731535f06", "0x7ffc57839b00206d1ad20c69a1981b489f772031", "0xb279182d99e65703f0076e4812653aab85fca0f0" ] + } + ``` + + + +### `clique_getSignerMetrics` + +Provides the following validator metrics for the specified range: + +- Number of blocks from each validator + +- Block number of the last block proposed by each validator (if any proposed in the specified range) + +- All validators present in the last block + +#### Parameters + +- `fromBlockNumber`: _string_ - hexadecimal or decimal integer representing a block number or the string tags `latest`, `earliest`, `pending`, `finalized`, or `safe`, as described in [block parameter](../../../public-networks/how-to/use-besu-api/json-rpc.md#block-parameter) + +- `toBlockNumber`: _string_ - hexadecimal or decimal integer representing a block number or one of the string tags `latest`, `earliest`, `pending`, `finalized`, or `safe`, as described in [block parameter](../../../public-networks/how-to/use-besu-api/json-rpc.md#block-parameter) + +If you specify: + +- No parameters, the call provides metrics for the last 100 blocks, or all blocks if there are less than 100 blocks. + +- Only the first parameter, the call provides metrics for all blocks from the block specified to the latest block. + +#### Returns + +`result`: _array_ of _objects_ - list of validator objects + +:::note + +The proposer of the genesis block has address `0x0000000000000000000000000000000000000000`. + +::: + + + +# curl HTTP + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"clique_getSignerMetrics","params":["1", "100"], "id":1}' http://127.0.0.1:8545 +``` + +# wscat WS + +```bash +{"jsonrpc":"2.0","method":"clique_getSignerMetrics","params":["1", "100"], "id":1} +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": [ + { + "address": "0x7ffc57839b00206d1ad20c69a1981b489f772031", + "proposedBlockCount": "0x21", + "lastProposedBlockNumber": "0x61" + }, + { + "address": "0x42eb768f2244c8811c63729a21a3569731535f06", + "proposedBlockCount": "0x21", + "lastProposedBlockNumber": "0x63" + }, + { + "address": "0xb279182d99e65703f0076e4812653aab85fca0f0", + "proposedBlockCount": "0x21", + "lastProposedBlockNumber": "0x62" + } + ] +} +``` + + + +### `clique_getSignersAtHash` + +Lists signers for the specified block. + +#### Parameters + +`hash`: _string_ - 32-byte block hash + +#### Returns + +`result`: _array_ of _string_ - list of 20-byte addresses of signers + + + +# curl HTTP request + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"clique_getSignersAtHash","params":["0x98b2ddb5106b03649d2d337d42154702796438b3c74fd25a5782940e84237a48"], "id":1}' http://127.0.0.1:8545 +``` + +# wscat WS request + +```bash +{"jsonrpc":"2.0","method":"clique_getSignersAtHash","params":["0x98b2ddb5106b03649d2d337d42154702796438b3c74fd25a5782940e84237a48"], "id":1} +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": [ + "0x42eb768f2244c8811c63729a21a3569731535f06", + "0x7ffc57839b00206d1ad20c69a1981b489f772031", + "0xb279182d99e65703f0076e4812653aab85fca0f0" + ] +} +``` + + + +### `clique_proposals` + +Returns [current proposals](../../how-to/configure/consensus/clique.md#add-and-remove-signers). + +#### Parameters + +None + +#### Returns + +`result`: _map_ of _strings_ to _booleans_ - map of account addresses to corresponding boolean values indicating the proposal for each account (if `true`, the proposal is to add a signer; if `false`, the proposal is to remove a signer.) + + + +# curl HTTP request + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"clique_proposals","params":[], "id":1}' http://127.0.0.1:8545 +``` + +# wscat WS request + +```bash +{"jsonrpc":"2.0","method":"clique_proposals","params":[], "id":1} +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + "0x42eb768f2244c8811c63729a21a3569731535f07": false, + "0x12eb759f2222d7711c63729a45c3585731521d01": true + } +} +``` + + + +### `clique_propose` + +Proposes to [add or remove a signer with the specified address]. + +#### Parameters + +- `address`: _string_ - 20-byte address + +- `proposal`: _boolean_ - `true` to propose adding signer or `false` to propose removing signer + +#### Returns + +`result`: _boolean_ - `true` + + + +# curl HTTP request + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"clique_propose","params":["0xFE3B557E8Fb62b89F4916B721be55cEb828dBd73", true], "id":1}' http://127.0.0.1:8545 +``` + +# wscat WS request + +```bash +{"jsonrpc":"2.0","method":"clique_propose","params":["0xFE3B557E8Fb62b89F4916B721be55cEb828dBd73", true], "id":1} +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": true +} +``` + + + +## `EEA` methods + +The `EEA` API methods provide functionality for [private transactions](../../concepts/privacy/private-transactions/index.md) and [privacy groups](../../concepts/privacy/privacy-groups.md). + +:::note + +The `EEA` API methods are not enabled by default for JSON-RPC. To enable the `EEA` API methods, use the [`--rpc-http-api`](../../../public-networks/reference/cli/options.md#rpc-http-api) or [`--rpc-ws-api`](../../../public-networks/reference/cli/options.md#rpc-ws-api) options. + +::: + +### `eea_sendRawTransaction` + +Distributes the [private transaction](../../how-to/send-transactions/private-transactions.md), generates the [privacy marker transaction](../../concepts/privacy/private-transactions/processing.md) and submits it to the transaction pool, and returns the transaction hash of the [privacy marker transaction](../../concepts/privacy/private-transactions/processing.md). + +The signed transaction passed as an input parameter includes the `privateFrom`, [`privateFor` or `privacyGroupId`](../../how-to/send-transactions/private-transactions.md#eea-compliant-or-besu-extended-privacy), and `restriction` fields. + +The `gas` and `gasPrice` are used by the [privacy marker transaction](../../concepts/privacy/private-transactions/processing.md) not the private transaction itself. + +To avoid exposing your private key, create signed transactions offline and send the signed transaction data using `eea_sendRawTransaction`. + +:::important + +For production systems requiring private transactions, use a network with a consensus mechanism supporting transaction finality to make sure the private state does not become inconsistent with the chain. For example, [IBFT 2.0](../../how-to/configure/consensus/ibft.md) and [QBFT](../../how-to/configure/consensus/qbft.md) provide the required finality. + +Using private transactions with [pruning](../../../public-networks/concepts/data-storage-formats.md#pruning) or [fast sync](../../../public-networks/reference/cli/options.md#sync-mode) isn't supported. + +Besu doesn't implement [`eea_sendTransaction`](../../how-to/send-transactions/private-transactions.md). + +[EthSigner](https://docs.ethsigner.consensys.net/en/latest/) provides transaction signing and implements [`eea_sendTransaction`](https://docs.ethsigner.consensys.net/Reference/API-Methods#eea_sendtransaction). + +::: + +#### Parameters + +`transaction`: _string_ - signed RLP-encoded private transaction + +#### Returns + +`result`: _string_ - 32-byte transaction hash of the [privacy marker transaction](../../concepts/privacy/private-transactions/processing.md) + +:::tip + +If creating a contract, use [priv_getTransactionReceipt](#priv_gettransactionreceipt) to retrieve the contract address after the transaction is finalized. + +::: + + + +# curl HTTP request + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"eea_sendRawTransaction","params": ["0xf869018203e882520894f17f52151ebef6c7334fad080c5704d77216b732881bc16d674ec80000801ba02da1c48b670996dcb1f447ef9ef00b33033c48a4fe938f420bec3e56bfd24071a062e0aa78a81bf0290afbc3a9d8e9a068e6d74caa66c5e0fa8a46deaae96b0833"], "id":1}' http://127.0.0.1:8545 +``` + +# wscat WS request + +```bash +{"jsonrpc":"2.0","method":"eea_sendRawTransaction","params": ["0xf869018203e882520894f17f52151ebef6c7334fad080c5704d77216b732881bc16d674ec80000801ba02da1c48b670996dcb1f447ef9ef00b33033c48a4fe938f420bec3e56bfd24071a062e0aa78a81bf0290afbc3a9d8e9a068e6d74caa66c5e0fa8a46deaae96b0833"], "id":1} +``` + +# JSON result + +```json +{ + "id": 1, + "jsonrpc": "2.0", + "result": "0xe670ec64341771606e55d6b4ca35a1a6b75ee3d5145a99d05921026d1527331" +} +``` + + + +## `IBFT` 2.0 methods + +The `IBFT` API methods provide access to the [IBFT 2.0](../../how-to/configure/consensus/ibft.md) consensus engine. + +:::note + +The `IBFT` API methods are not enabled by default for JSON-RPC. To enable the `IBFT` API methods, use the [`--rpc-http-api`](../../../public-networks/reference/cli/options.md#rpc-http-api) or [`--rpc-ws-api`](../../../public-networks/reference/cli/options.md#rpc-ws-api) options. + +::: + +### `ibft_discardValidatorVote` + +Discards a proposal to [add or remove a validator] with the specified address. + +#### Parameters + +`address`: _string_ - 20-byte address of proposed validator + +#### Returns + +`result`: _boolean_ - indicates if the proposal is discarded + + + +# curl HTTP request + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"ibft_discardValidatorVote","params":["0xef1bfb6a12794615c9b0b5a21e6741f01e570185"], "id":1}' http://127.0.0.1:8545 +``` + +# wscat WS request + +```bash +{"jsonrpc":"2.0","method":"ibft_discardValidatorVote","params":["0xef1bfb6a12794615c9b0b5a21e6741f01e570185"], "id":1} +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": true +} +``` + + + +### `ibft_getPendingVotes` + +Returns [votes](../../how-to/configure/consensus/ibft.md#add-and-remove-validators) cast in the current [epoch](../../how-to/configure/consensus/ibft.md#genesis-file). + +#### Parameters + +None + +#### Returns + +`result`: _map_ of _strings_ to _booleans_ - map of account addresses to corresponding boolean values indicating the vote for each account; if `true`, the vote is to add a validator. If `false`, the proposal is to remove a validator. + + + +# curl HTTP request + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"ibft_getPendingVotes","params":[], "id":1}' http://127.0.0.1:8545 +``` + +# wscat WS request + +```bash +{"jsonrpc":"2.0","method":"ibft_getPendingVotes","params":[], "id":1} +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + "0xef1bfb6a12794615c9b0b5a21e6741f01e570185": true, + "0x42d4287eac8078828cf5f3486cfe601a275a49a5": true + } +} +``` + + + +### `ibft_getSignerMetrics` + +Provides the following validator metrics for the specified range: + +- Number of blocks from each validator + +- Block number of the last block proposed by each validator (if any proposed in the specified range) + +- All validators present in the last block of the range + +#### Parameters + +- `fromBlockNumber`: _string_ - hexadecimal or decimal integer representing a block number or the string tags `latest`, `earliest`, `pending`, `finalized`, or `safe`, as described in [block parameter](../../../public-networks/how-to/use-besu-api/json-rpc.md#block-parameter) + +- `toBlockNumber`: _string_ - hexadecimal or decimal integer representing a block number or one of the string tags `latest`, `earliest`, `pending`, `finalized`, or `safe`, as described in [block parameter](../../../public-networks/how-to/use-besu-api/json-rpc.md#block-parameter) + +If you specify: + +- No parameters, the call provides metrics for the last 100 blocks, or all blocks if there are less than 100 blocks. + +- Only the first parameter, the call provides metrics for all blocks from the block specified to the latest block. + +#### Returns + +`result`: _array_ of _objects_ - list of validator objects + +:::note + +The proposer of the genesis block has address `0x0000000000000000000000000000000000000000`. + +::: + + + +# curl HTTP + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"ibft_getSignerMetrics","params":["1", "100"], "id":1}' http://127.0.0.1:8545 +``` + +# wscat WS + +```bash +{"jsonrpc":"2.0","method":"ibft_getSignerMetrics","params":["1", "100"], "id":1} +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": [ + { + "address": "0x7ffc57839b00206d1ad20c69a1981b489f772031", + "proposedBlockCount": "0x21", + "lastProposedBlockNumber": "0x61" + }, + { + "address": "0x42eb768f2244c8811c63729a21a3569731535f06", + "proposedBlockCount": "0x21", + "lastProposedBlockNumber": "0x63" + }, + { + "address": "0xb279182d99e65703f0076e4812653aab85fca0f0", + "proposedBlockCount": "0x21", + "lastProposedBlockNumber": "0x62" + } + ] +} +``` + + + +### `ibft_getValidatorsByBlockHash` + +Lists the validators defined in the specified block. + +#### Parameters + +`block`: _string_ - 32-byte block hash + +#### Returns + +`result`: _array_ of _strings_ - list of validator addresses + + + +# curl HTTP request + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"ibft_getValidatorsByBlockHash","params":["0xbae7d3feafd743343b9a4c578cab5e5d65eb735f6855fb845c00cab356331256"], "id":1}' http://127.0.0.1:8545 +``` + +# wscat WS request + +```bash +{"jsonrpc":"2.0","method":"ibft_getValidatorsByBlockHash","params":["0xbae7d3feafd743343b9a4c578cab5e5d65eb735f6855fb845c00cab356331256"], "id":1} +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": [ + "0x42d4287eac8078828cf5f3486cfe601a275a49a5", + "0xb1b2bc9582d2901afdc579f528a35ca41403fa85", + "0xef1bfb6a12794615c9b0b5a21e6741f01e570185" + ] +} +``` + + + +### `ibft_getValidatorsByBlockNumber` + +Lists the validators defined in the specified block. + +#### Parameters + +- `blockNumber`: _string_ - hexadecimal or decimal integer representing a block number or one of the string tags `latest`, `earliest`, `pending`, `finalized`, or `safe`, as described in [block parameter](../../../public-networks/how-to/use-besu-api/json-rpc.md#block-parameter) + +#### Returns + +`result`: _array_ of _strings_ - list of validator addresses + + + +# curl HTTP request + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"ibft_getValidatorsByBlockNumber","params":["latest"], "id":1}' http://127.0.0.1:8545 +``` + +# wscat WS request + +```bash +{"jsonrpc":"2.0","method":"ibft_getValidatorsByBlockNumber","params":["latest"], "id":1} +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": [ + "0x42d4287eac8078828cf5f3486cfe601a275a49a5", + "0xb1b2bc9582d2901afdc579f528a35ca41403fa85", + "0xef1bfb6a12794615c9b0b5a21e6741f01e570185" + ] +} +``` + + + +### `ibft_proposeValidatorVote` + +Proposes to [add or remove a validator] with the specified address. + +#### Parameters + +- `address`: _string_ - account address + +- `proposal`: _boolean_ - `true` to propose adding validator or `false` to propose removing validator + +#### Returns + +`result`: _boolean_ - `true` + + + +# curl HTTP request + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"ibft_proposeValidatorVote","params":["42d4287eac8078828cf5f3486cfe601a275a49a5",true], "id":1}' http://127.0.0.1:8545 +``` + +# wscat WS request + +```bash +{"jsonrpc":"2.0","method":"ibft_proposeValidatorVote","params":["42d4287eac8078828cf5f3486cfe601a275a49a5",true], "id":1} +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": true +} +``` + + + +## `PERM` (Permissioning) methods + +The `PERM` API methods provide permissioning functionality. Use these methods for [local permissioning](../../how-to/use-permissioning/local.md) only. + +:::important + +The `PERM` API methods are not enabled by default for JSON-RPC. To enable the `PERM` API methods, use the [`--rpc-http-api`](../../../public-networks/reference/cli/options.md#rpc-http-api) or [`--rpc-ws-api`](../../../public-networks/reference/cli/options.md#rpc-ws-api) CLI options. + +::: + +### `perm_addAccountsToAllowlist` + +Adds accounts (participants) to the [accounts permission list](../../how-to/use-permissioning/local.md#account-permissioning). + +#### Parameters + +`addresses`: _array_ of _strings_ - list of account addresses + +:::note + +The parameters list contains a list which is why the account addresses are enclosed by double square brackets. + +::: + +#### Returns + +`result`: _string_ - `Success` or `error` (errors include attempting to add accounts already on the allowlist and including invalid account addresses.) + + + +# curl HTTP request + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"perm_addAccountsToAllowlist","params":[["0xb9b81ee349c3807e46bc71aa2632203c5b462032", "0xb9b81ee349c3807e46bc71aa2632203c5b462034"]], "id":1}' http://127.0.0.1:8545 +``` + +# wscat WS request + +```bash +{"jsonrpc":"2.0","method":"perm_addAccountsToAllowlist","params":[["0xb9b81ee349c3807e46bc71aa2632203c5b462032", "0xb9b81ee349c3807e46bc71aa2632203c5b462034"]], "id":1} +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": "Success" +} +``` + + + +### `perm_addNodesToAllowlist` + +Adds nodes to the [nodes allowlist](../../how-to/use-permissioning/local.md#node-allowlisting). + +To use domain names in enode URLs, ensure you [enable DNS support](../../../public-networks/concepts/node-keys.md#domain-name-support) to avoid receiving a `request contains an invalid node` error. + +:::warning + +Enode URL domain name support is an early access feature. + +::: + +#### Parameters + +`enodes`: _array_ of _strings_ - list of [enode URLs](../../../public-networks/concepts/node-keys.md#enode-url) + +:::note + +The parameters list contains a list which is why the enode URLs are enclosed by double square brackets. + +::: + +#### Returns + +`result`: _string_ - `Success` or `error`; errors include attempting to add nodes already on the allowlist or including invalid enode URLs. + + + +# curl HTTP request + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"perm_addNodesToAllowlist","params":[["enode://7e4ef30e9ec683f26ad76ffca5b5148fa7a6575f4cfad4eb0f52f9c3d8335f4a9b6f9e66fcc73ef95ed7a2a52784d4f372e7750ac8ae0b544309a5b391a23dd7@127.0.0.1:30303","enode://2feb33b3c6c4a8f77d84a5ce44954e83e5f163e7a65f7f7a7fec499ceb0ddd76a46ef635408c513d64c076470eac86b7f2c8ae4fcd112cb28ce82c0d64ec2c94@127.0.0.1:30304"]], "id":1}' http://127.0.0.1:8545 +``` + +# wscat WS request + +```bash +{"jsonrpc":"2.0","method":"perm_addNodesToAllowlist","params":[["enode://7e4ef30e9ec683f26ad76ffca5b5148fa7a6575f4cfad4eb0f52f9c3d8335f4a9b6f9e66fcc73ef95ed7a2a52784d4f372e7750ac8ae0b544309a5b391a23dd7@127.0.0.1:30303","enode://2feb33b3c6c4a8f77d84a5ce44954e83e5f163e7a65f7f7a7fec499ceb0ddd76a46ef635408c513d64c076470eac86b7f2c8ae4fcd112cb28ce82c0d64ec2c94@127.0.0.1:30304"]], "id":1} +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": "Success" +} +``` + + + +### `perm_getAccountsAllowlist` + +Lists accounts (participants) in the [accounts permissions list](../../how-to/use-permissioning/local.md#account-permissioning). + +#### Parameters + +None + +#### Returns + +`result`: _array_ of _strings_ - list of accounts (participants) in the accounts allowlist + + + +# curl HTTP request + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"perm_getAccountsAllowlist","params":[], "id":1}' http://127.0.0.1:8545 +``` + +# wscat WS request + +```bash +{"jsonrpc":"2.0","method":"perm_getAccountsAllowlist","params":[], "id":1} +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": [ + "0x0000000000000000000000000000000000000009", + "0xb9b81ee349c3807e46bc71aa2632203c5b462033" + ] +} +``` + + + +### `perm_getNodesAllowlist` + +Lists nodes in the [nodes allowlist](../../how-to/use-permissioning/local.md#node-allowlisting). + +#### Parameters + +None + +#### Returns + +`result`: _array_ of _strings_ - [enode URLs](../../../public-networks/concepts/node-keys.md#enode-url) of nodes in the nodes allowlist + + + +# curl HTTP request + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"perm_getNodesAllowlist","params":[], "id":1}' http://127.0.0.1:8545 +``` + +# wscat WS request + +```bash +{"jsonrpc":"2.0","method":"perm_getNodesAllowlist","params":[], "id":1} +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": [ + "enode://7b61d5ee4b44335873e6912cb5dd3e3877c860ba21417c9b9ef1f7e500a82213737d4b269046d0669fb2299a234ca03443f25fe5f706b693b3669e5c92478ade@127.0.0.1:30305", + "enode://2feb33b3c6c4a8f77d84a5ce44954e83e5f163e7a65f7f7a7fec499ceb0ddd76a46ef635408c513d64c076470eac86b7f2c8ae4fcd112cb28ce82c0d64ec2c94@127.0.0.1:30304" + ] +} +``` + + + +### `perm_reloadPermissionsFromFile` + +Reloads the accounts and nodes allowlists from the [permissions configuration file]. + +#### Parameters + +None + +#### Returns + +`result`: _string_ - `Success`, or `error` if the permissions configuration file is not valid + + + +# curl HTTP request + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"perm_reloadPermissionsFromFile","params":[], "id":1}' http://127.0.0.1:8545 +``` + +# wscat WS request + +```bash +{"jsonrpc":"2.0","method":"perm_reloadPermissionsFromFile","params":[], "id":1} +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": "Success" +} +``` + + + +### `perm_removeAccountsFromAllowlist` + +Removes accounts (participants) from the [accounts permissions list](../../how-to/use-permissioning/local.md#account-permissioning). + +#### Parameters + +`addresses`: _array_ of _strings_ - list of account addresses + +:::note + +The parameters list contains a list which is why the account addresses are enclosed by double square brackets. + +::: + +#### Returns + +`result`: _string_ - `Success` or `error` (errors include attempting to remove accounts not on the allowlist and including invalid account addresses.) + + + +# curl HTTP request + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"perm_removeAccountsFromAllowlist","params":[["0xb9b81ee349c3807e46bc71aa2632203c5b462032", "0xb9b81ee349c3807e46bc71aa2632203c5b462034"]], "id":1}' http://127.0.0.1:8545 +``` + +# wscat WS request + +```bash +{"jsonrpc":"2.0","method":"perm_removeAccountsFromAllowlist","params":[["0xb9b81ee349c3807e46bc71aa2632203c5b462032", "0xb9b81ee349c3807e46bc71aa2632203c5b462034"]], "id":1} +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": "Success" +} +``` + + + +### `perm_removeNodesFromAllowlist` + +Removes nodes from the [nodes allowlist](../../how-to/use-permissioning/local.md#node-allowlisting). + +#### Parameters + +`enodes`: _array_ of _strings_ - list of [enode URLs](../../../public-networks/concepts/node-keys.md#enode-url) + +:::note + +The parameters list contains a list which is why the enode URLs are enclosed by double square brackets. + +::: + +#### Returns + +`result`: _string_ - `Success` or `error` (errors include attempting to remove nodes not on the allowlist and including invalid enode URLs.) + + + +# curl HTTP request + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"perm_removeNodesFromAllowlist","params":[["enode://7e4ef30e9ec683f26ad76ffca5b5148fa7a6575f4cfad4eb0f52f9c3d8335f4a9b6f9e66fcc73ef95ed7a2a52784d4f372e7750ac8ae0b544309a5b391a23dd7@127.0.0.1:30303","enode://2feb33b3c6c4a8f77d84a5ce44954e83e5f163e7a65f7f7a7fec499ceb0ddd76a46ef635408c513d64c076470eac86b7f2c8ae4fcd112cb28ce82c0d64ec2c94@127.0.0.1:30304"]], "id":1}' http://127.0.0.1:8545 +``` + +# wscat WS request + +```bash +{"jsonrpc":"2.0","method":"perm_removeNodesFromAllowlist","params":[["enode://7e4ef30e9ec683f26ad76ffca5b5148fa7a6575f4cfad4eb0f52f9c3d8335f4a9b6f9e66fcc73ef95ed7a2a52784d4f372e7750ac8ae0b544309a5b391a23dd7@127.0.0.1:30303","enode://2feb33b3c6c4a8f77d84a5ce44954e83e5f163e7a65f7f7a7fec499ceb0ddd76a46ef635408c513d64c076470eac86b7f2c8ae4fcd112cb28ce82c0d64ec2c94@127.0.0.1:30304"]], "id":1} +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": "Success" +} +``` + + + +## `PRIV` methods + +The `PRIV` API methods provide functionality for [private transactions](../../concepts/privacy/private-transactions/index.md) and [privacy groups](../../concepts/privacy/privacy-groups.md). + +:::note + +The `PRIV` API methods are not enabled by default for JSON-RPC. To enable the `PRIV` API methods, use the [`--rpc-http-api`](../../../public-networks/reference/cli/options.md#rpc-http-api) or [`--rpc-ws-api`](../../../public-networks/reference/cli/options.md#rpc-ws-api) options. + +::: + +### `priv_call` + +Invokes a private contract function locally and does not change the privacy group state. + +For private contracts, `priv_call` is the same as [`eth_call`](../../../public-networks/reference/api/index.md#eth_call) for public contracts. + +#### Parameters + +- `privacyGroupId`: _string_ - 32-byte [privacy Group ID](../../concepts/privacy/privacy-groups.md) + +- `call`: _object_ - [transaction call object](../../../public-networks/reference/api/objects.md#transaction-call-object) + +- `blockNumber`: _string_ - hexadecimal or decimal integer representing a block number or one of the string tags `latest`, `earliest`, `pending`, `finalized`, or `safe`, as described in [block parameter](../../../public-networks/how-to/use-besu-api/json-rpc.md#block-parameter) + +#### Returns + +`result`: _data_ - return value of the executed contract + + + +# curl HTTP + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"priv_call","params":["tb8NVyQqZnHNegf/3mYsyB+HEud4SPWn90rz3GoskRw=", {"to":"0x69498dd54bd25aa0c886cf1f8b8ae0856d55ff13","data": "0x3fa4f245"}, "latest"],"id":1}' http://127.0.0.1:8545 +``` + +# wscat WS + +```bash +{"jsonrpc":"2.0","method":"priv_call","params":["tb8NVyQqZnHNegf/3mYsyB+HEud4SPWn90rz3GoskRw=", {"to":"0x69498dd54bd25aa0c886cf1f8b8ae0856d55ff13","data": "0x3fa4f245"}, "latest"],"id":1} +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": "0x0000000000000000000000000000000000000000000000000000000000000001" +} +``` + +# curl GraphQL + +```bash +curl -X POST -H "Content-Type: application/json" --data '{ "query": "{block {number call (data : {from : \"0xa94f5374fce5edbc8e2a8697c15331677e6ebf0b\", to: \"0x69498dd54bd25aa0c886cf1f8b8ae0856d55ff13\", data :\"0x12a7b914\"}){data status}}}"}' http://localhost:8547/graphql +``` + +# GraphQL + +```bash +{ + block { + number + call(data: {from: "0xa94f5374fce5edbc8e2a8697c15331677e6ebf0b", to: "0x69498dd54bd25aa0c886cf1f8b8ae0856d55ff13", data: "0x12a7b914"}) { + data + status + } + } +} +``` + +# GraphQL result + +```json +{ + "data": { + "block": { + "number": 17449, + "call": { + "data": "0x", + "status": 1 + } + } + } +} +``` + + + +### `priv_createPrivacyGroup` + +Creates a group of nodes, specified by their [Tessera](https://docs.tessera.consensys.net/) public key. + +#### Parameters + +`options`: _object_ - request options object with the following fields: + +- `addresses`: _array_ of _strings_ - list of nodes specified by [Tessera](https://docs.tessera.consensys.net/) public keys + +- `name`: _string_ - (optional) privacy group name + +- `description`: _string_ - (optional) privacy group description + +#### Returns + +`result`: _string_ - privacy group ID + + + +# curl HTTP request + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method": "priv_createPrivacyGroup", "params": [{"addresses":["sTZpbQhcOfd9ZaFDnC00e/N2Ofv9p4/ZTBbEeVtXJ3E=","quhb1pQPGN1w8ZSZSyiIfncEAlVY/M/rauSyQ5wVMRE="],"name":"Group A","description":"Description Group A"}],"id":1}' http://127.0.0.1:8545 +``` + +# wscat WS request + +```bash +{"jsonrpc":"2.0","method": "priv_createPrivacyGroup", "params": [{"addresses":["sTZpbQhcOfd9ZaFDnC00e/N2Ofv9p4/ZTBbEeVtXJ3E=","quhb1pQPGN1w8ZSZSyiIfncEAlVY/M/rauSyQ5wVMRE="],"name":"Group A","description":"Description Group A"}],"id":1} +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": "ewuTVoc5nlvWMwTFdRRK/wvV0dcyQo/Pauvx5bNEbTk=" +} +``` + + + +### `priv_debugGetStateRoot` + +Returns the state root of the specified privacy group at the specified block. + +#### Parameters + +- `privacyGroupId`: _string_ - 32-byte [privacy Group ID](../../concepts/privacy/privacy-groups.md) + +- `blockNumber`: _string_ - hexadecimal or decimal integer representing a block number or one of the string tags `latest`, `earliest`, `pending`, `finalized`, or `safe`, as described in [block parameter](../../../public-networks/how-to/use-besu-api/json-rpc.md#block-parameter) + +#### Returns + +`result`: _string_ - 32-byte state root + + + +# curl HTTP + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"priv_debugGetStateRoot","params":["xJdxvWOEmrs2MCkKWlgArTzWIXFfU/tmVxI3EKssVTk=","latest"],"id":1}' http://127.0.0.1:8545 +``` + +# wscat WS + +```bash +{"jsonrpc":"2.0","method":"priv_debugGetStateRoot","params":["xJdxvWOEmrs2MCkKWlgArTzWIXFfU/tmVxI3EKssVTk=","latest"],"id":1} +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": "0x56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421" +} +``` + + + +### `priv_deletePrivacyGroup` + +Deletes the specified privacy group. + +#### Parameters + +`privacyGroupId`: _string_ - privacy group ID + +#### Returns + +`result`: _string_ - deleted privacy group ID + + + +# curl HTTP request + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"priv_deletePrivacyGroup","params":["ewuTVoc5nlvWMwTFdRRK/wvV0dcyQo/Pauvx5bNEbTk="],"id":1}' http://127.0.0.1:8545 +``` + +# wscat WS request + +```bash +{"jsonrpc":"2.0","method":"priv_deletePrivacyGroup","params":["ewuTVoc5nlvWMwTFdRRK/wvV0dcyQo/Pauvx5bNEbTk="],"id":1} +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 53, + "result": "ewuTVoc5nlvWMwTFdRRK/wvV0dcyQo/Pauvx5bNEbTk=" +} +``` + + + +### `priv_distributeRawTransaction` + +Distributes a signed, RLP encoded [private transaction](../../how-to/send-transactions/private-transactions.md). + +:::tip + +If you want to sign the [privacy marker transaction](../../how-to/use-privacy/sign-pmts.md) outside of Besu, use [`priv_distributeRawTransaction`](../../how-to/send-transactions/private-transactions.md#priv_distributerawtransaction) instead of [`eea_sendRawTransaction`](#eea_sendrawtransaction). + +::: + +#### Parameters + +`transaction`: _string_ - signed RLP-encoded private transaction + +#### Returns + +`result`: _string_ - 32-byte enclave key (the enclave key is a pointer to the private transaction in [Tessera](https://docs.tessera.consensys.net/).) + + + +# curl HTTP request + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"priv_distributeRawTransaction","params": ["0xf869018203e882520894f17f52151ebef6c7334fad080c5704d77216b732881bc16d674ec80000801ba02da1c48b670996dcb1f447ef9ef00b33033c48a4fe938f420bec3e56bfd24071a062e0aa78a81bf0290afbc3a9d8e9a068e6d74caa66c5e0fa8a46deaae96b0833"], "id":1}' http://127.0.0.1:8545 +``` + +# wscat WS request + +```bash +{"jsonrpc":"2.0","method":"priv_distributeRawTransaction","params": ["0xf869018203e882520894f17f52151ebef6c7334fad080c5704d77216b732881bc16d674ec80000801ba02da1c48b670996dcb1f447ef9ef00b33033c48a4fe938f420bec3e56bfd24071a062e0aa78a81bf0290afbc3a9d8e9a068e6d74caa66c5e0fa8a46deaae96b0833"], "id":1} +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": "0xfd0d90ab824574abc19c0776ca0210e764561d0ef6d621f2bbbea316eccfe56b" +} +``` + + + +### `priv_findPrivacyGroup` + +Returns a list of privacy groups containing only the listed members. For example, if the listed members are A and B, a privacy group containing A, B, and C is not returned. + +#### Parameters + +`members`: _array_ of _strings_ - members specified by [Tessera](https://docs.tessera.consensys.net/) public keys + +#### Returns + +`result`: _array_ of _objects_ - privacy group objects containing only the specified members; privacy groups are [EEA-compliant](../../concepts/privacy/privacy-groups.md#enterprise-ethereum-alliance-privacy) or [Besu-extended](../../concepts/privacy/privacy-groups.md#besu-extended-privacy) with types: + +- `LEGACY` for EEA-compliant groups. + +- `PANTHEON` for Besu-extended groups. + + + +# curl HTTP request + +```bash +curl -X POST --data '{"jsonrpc": "2.0","method": "priv_findPrivacyGroup","params": [["negmDcN2P4ODpqn/6WkJ02zT/0w0bjhGpkZ8UP6vARk=", "g59BmTeJIn7HIcnq8VQWgyh/pDbvbt2eyP0Ii60aDDw="]],"id": 1}' http://127.0.0.1:8545 +``` + +# wscat WS request + +```bash +{"jsonrpc": "2.0","method": "priv_findPrivacyGroup","params": [["negmDcN2P4ODpqn/6WkJ02zT/0w0bjhGpkZ8UP6vARk=", "g59BmTeJIn7HIcnq8VQWgyh/pDbvbt2eyP0Ii60aDDw="]],"id": 1} +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": [ + { + "privacyGroupId": "GpK3ErNO0xF27T0sevgkJ3+4qk9Z+E3HtXYxcKIBKX8=", + "name": "Group B", + "description": "Description of Group B", + "type": "PANTHEON", + "members": [ + "negmDcN2P4ODpqn/6WkJ02zT/0w0bjhGpkZ8UP6vARk=", + "g59BmTeJIn7HIcnq8VQWgyh/pDbvbt2eyP0Ii60aDDw=" + ] + } + ] +} +``` + + + +### `priv_getCode` + +Returns the code of the private smart contract at the specified address. Compiled smart contract code is stored as a hexadecimal value. + +#### Parameters + +- `privacyGroupId`: _string_ - 32-byte [privacy Group ID](../../concepts/privacy/privacy-groups.md) + +- `address`: _string_ - 20-byte contract address + +- `blockNumber`: _string_ - hexadecimal or decimal integer representing a block number or one of the string tags `latest`, `earliest`, `pending`, `finalized`, or `safe`, as described in [block parameter](../../../public-networks/how-to/use-besu-api/json-rpc.md#block-parameter) + +#### Returns + +`result`: _data_ - code stored at the specified address + + + +# curl HTTP + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"priv_getCode","params":["1lJxSIP4JOp6uRn9wYsPeWwqoOP1c4nPQjylB4FExUA=", "0xeaf1c1bd00ef0bec5e39fba81740f1c5d05aa201", "latest"],"id":1}' http://127.0.0.1:8545 +``` + +# wscat WS + +```bash +{"jsonrpc":"2.0","method":"priv_getCode","params":["1lJxSIP4JOp6uRn9wYsPeWwqoOP1c4nPQjylB4FExUA=", "0xeaf1c1bd00ef0bec5e39fba81740f1c5d05aa201", "latest"],"id":1} +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": "0x60806040526004361060485763ffffffff7c01000000000000000000000000000000000000000000000000000000006000350416633fa4f2458114604d57806355241077146071575b600080fd5b348015605857600080fd5b50605f6088565b60408051918252519081900360200190f35b348015607c57600080fd5b506086600435608e565b005b60005481565b60008190556040805182815290517f199cd93e851e4c78c437891155e2112093f8f15394aa89dab09e38d6ca0727879181900360200190a1505600a165627a7a723058209d8929142720a69bde2ab3bfa2da6217674b984899b62753979743c0470a2ea70029" +} +``` + + + +### `priv_getEeaTransactionCount` + +Returns the private transaction count for the specified account and [group of sender and recipients]. + +::caution important +If sending more than one transaction to be mined in the same block (that is, you are not +waiting for the transaction receipt), you must calculate the private transaction nonce outside +Besu instead of using `priv_getEeaTransactionCount`. +::: + +#### Parameters + +- `address`: _string_ - account address + +- `sender`: _string_ - base64-encoded Tessera address of the sender + +- `recipients`: _array_ of _strings_ - base64-encoded Tessera addresses of recipients + +#### Returns + +`result`: _string_ - integer representing the number of private transactions sent from the address to the specified group of sender and recipients + + + +# curl HTTP request + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"priv_getEeaTransactionCount","params":["0xfe3b557e8fb62b89f4916b721be55ceb828dbd73", "GGilEkXLaQ9yhhtbpBT03Me9iYa7U/mWXxrJhnbl1XY=", ["KkOjNLmCI6r+mICrC6l+XuEDjFEzQllaMQMpWLl4y1s=","eLb69r4K8/9WviwlfDiZ4jf97P9czyS3DkKu0QYGLjg="]], "id":1}' http://127.0.0.1:8545 +``` + +# wscat WS request + +```bash +{"jsonrpc":"2.0","method":"priv_getEeaTransactionCount","params":["0xfe3b557e8fb62b89f4916b721be55ceb828dbd73", "GGilEkXLaQ9yhhtbpBT03Me9iYa7U/mWXxrJhnbl1XY=", ["KkOjNLmCI6r+mICrC6l+XuEDjFEzQllaMQMpWLl4y1s=","eLb69r4K8/9WviwlfDiZ4jf97P9czyS3DkKu0QYGLjg="]], "id":1} +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": "0x1" +} +``` + + + +### `priv_getFilterChanges` + +Polls the specified filter for a private contract and returns an array of changes that have occurred since the last poll. + +Filters for private contracts can only be created by [`priv_newFilter`](#priv_newfilter) so unlike [`eth_getFilterChanges`](../../../public-networks/reference/api/index.md#eth_getfilterchanges), `priv_getFilterChanges` always returns an array of log objects or an empty list. + +#### Parameters + +- `privacyGroupId`: _string_ - 32-byte [privacy Group ID](../../concepts/privacy/privacy-groups.md) + +- `filterId`: _string_ - filter ID + +#### Returns + +`result`: _array_ of _objects_ - list of [log objects](../../../public-networks/reference/api/objects.md#log-object), or an empty list if nothing has changed since the last poll + + + +# curl HTTP request + +```bash +curl -X POST --data '{"jsonrpc": "2.0","method": "priv_getFilterChanges","params": ["4rFldHM792LeP/e2WPkTXZedjwKuTr/KwCFTt6mBbkI=","0x4a35b92809d73f4f53a2355d62125442"],"id": 1}' http://127.0.0.1:8545 +``` + +# wscat WS request + +```bash +{"jsonrpc": "2.0","method": "priv_getFilterChanges","params": ["4rFldHM792LeP/e2WPkTXZedjwKuTr/KwCFTt6mBbkI=","0x4a35b92809d73f4f53a2355d62125442"],"id": 1} +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": [ + { + "logIndex": "0x0", + "removed": false, + "blockNumber": "0x4d0", + "blockHash": "0x1c8200667a869e99b945374c37277b5ee7a7ae67943e13c82563381387553dbb", + "transactionHash": "0xb1966b9b372ba68952f48f3a3e78f036f5ae82ceca2de972a782d07fb88f6d88", + "transactionIndex": "0x0", + "address": "0x991cc548c154b2953cc48c02f782e1314097dfbb", + "data": "0x", + "topics": [ + "0x85bea11d86cefb165374e0f727bacf21dc2f4ea816493981ecf72dcfb212a410", + "0x0000000000000000000000000000000000000000000000000000000000000002" + ] + } + ] +} +``` + + + +### `priv_getFilterLogs` + +Returns an array of [logs](../../../public-networks/concepts/events-and-logs.md) for the specified filter for a private contract. + +For private contracts, `priv_getFilterLogs` is the same as [`eth_getFilterLogs`](../../../public-networks/reference/api/index.md#eth_getfilterlogs) for public contracts except there's no [automatic log bloom caching](../../../public-networks/reference/cli/options.md#auto-log-bloom-caching-enabled) for private contracts. + +:::note + +`priv_getFilterLogs` is only used for filters created with [`priv_newFilter`](#priv_newfilter). To specify a filter object and get logs without creating a filter, use [`priv_getLogs`](#priv_getlogs). + +::: + +#### Parameters + +- `privacyGroupId`: _string_ - 32-byte [privacy Group ID](../../concepts/privacy/privacy-groups.md) + +- `filterId`: _string_ - filter ID + +#### Returns + +`result`: _array_ of _objects_ - list of [log objects](../../../public-networks/reference/api/objects.md#log-object) + + + +# curl HTTP request + +```bash +curl -X POST --data '{"jsonrpc": "2.0","method": "priv_getFilterLogs","params":["4rFldHM792LeP/e2WPkTXZedjwKuTr/KwCFTt6mBbkI=","0x4a35b92809d73f4f53a2355d62125442"],"id": 1}' http://127.0.0.1:8545 +``` + +# wscat WS request + +```bash +{"jsonrpc": "2.0","method": "priv_getFilterLogs","params":["4rFldHM792LeP/e2WPkTXZedjwKuTr/KwCFTt6mBbkI=","0x4a35b92809d73f4f53a2355d62125442"],"id": 1} +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": [ + { + "logIndex": "0x0", + "removed": false, + "blockNumber": "0x493", + "blockHash": "0xd9cb3a852e1e02c95f035a2e32d57f82c10cab61faa3e8f5c010adf979bb4786", + "transactionHash": "0x78866dc51fdf189d8cca74f6a8fe54f172348fbd2163bbe80fa8b106cfc7deb4", + "transactionIndex": "0x0", + "address": "0x991cc548c154b2953cc48c02f782e1314097dfbb", + "data": "0x", + "topics": [ + "0x85bea11d86cefb165374e0f727bacf21dc2f4ea816493981ecf72dcfb212a410", + "0x0000000000000000000000000000000000000000000000000000000000000001" + ] + }, + { + "logIndex": "0x0", + "removed": false, + "blockNumber": "0x4d0", + "blockHash": "0x1c8200667a869e99b945374c37277b5ee7a7ae67943e13c82563381387553dbb", + "transactionHash": "0xb1966b9b372ba68952f48f3a3e78f036f5ae82ceca2de972a782d07fb88f6d88", + "transactionIndex": "0x0", + "address": "0x991cc548c154b2953cc48c02f782e1314097dfbb", + "data": "0x", + "topics": [ + "0x85bea11d86cefb165374e0f727bacf21dc2f4ea816493981ecf72dcfb212a410", + "0x0000000000000000000000000000000000000000000000000000000000000002" + ] + } + ] +} +``` + + + +### `priv_getLogs` + +Returns an array of [logs](../../../public-networks/concepts/events-and-logs.md) matching a specified filter object. + +For private contracts, `priv_getLogs` is the same as [`eth_getLogs`](../../../public-networks/reference/api/index.md#eth_getlogs) for public contracts except there is no [automatic log bloom caching](../../../public-networks/reference/cli/options.md#auto-log-bloom-caching-enabled) for private contracts. + +#### Parameters + +- `privacyGroupId`: _string_ - 32-byte [privacy Group ID](../../concepts/privacy/privacy-groups.md) + +- `filterOptions`: _object_ - [filter options object](../../../public-networks/reference/api/objects.md#filter-options-object) + +#### Returns + +`result`: _array_ of _objects_ - list of [log objects](../../../public-networks/reference/api/objects.md#log-object) + + + +# curl HTTP + +```bash +curl -X POST --data '{"jsonrpc": "2.0","method": "priv_getLogs","params":["vGy/TZgO6y8VPMVeJAQ99MF1NaTf5ohA3TFfzoEF71k=",{"fromBlock": "earliest","toBlock": "latest","addresses": ["0x630c507ff633312087dc33c513b66276abcd2fc3"],"topics": ["0x85bea11d86cefb165374e0f727bacf21dc2f4ea816493981ecf72dcfb212a410"]}],"id": 1}' http://127.0.0.1:8545 +``` + +# wscat WS + +```bash +{"jsonrpc": "2.0","method": "priv_getLogs","params":["vGy/TZgO6y8VPMVeJAQ99MF1NaTf5ohA3TFfzoEF71k=",{"fromBlock": "earliest","toBlock": "latest","addresses": ["0x630c507ff633312087dc33c513b66276abcd2fc3"],"topics": ["0x85bea11d86cefb165374e0f727bacf21dc2f4ea816493981ecf72dcfb212a410"]}],"id": 1} +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": [ + { + "logIndex": "0x0", + "removed": false, + "blockNumber": "0x342", + "blockHash": "0xf5954f068fa2f2f7741281e8c753a8e92047e27ab3c4971836d2c89fab86d92b", + "transactionHash": "0xa9ba5cffde9d4ad8997c5c4352d5d49eeea0e9def8a4ea69991b8837c49d4e4f", + "transactionIndex": "0x0", + "address": "0x630c507ff633312087dc33c513b66276abcd2fc3", + "data": "0x", + "topics": [ + "0x85bea11d86cefb165374e0f727bacf21dc2f4ea816493981ecf72dcfb212a410", + "0x0000000000000000000000000000000000000000000000000000000000000001" + ] + }, + { + "logIndex": "0x0", + "removed": false, + "blockNumber": "0x383", + "blockHash": "0x91b73a47d53e3a88d62ed091a89a4be7557ad91b552e7ff7d86bf78977d5d45d", + "transactionHash": "0xc2a185faf00e87434e55b7f70cc4c38be354c2128b4b96b5f5def0b54a2173ec", + "transactionIndex": "0x0", + "address": "0x630c507ff633312087dc33c513b66276abcd2fc3", + "data": "0x", + "topics": [ + "0x85bea11d86cefb165374e0f727bacf21dc2f4ea816493981ecf72dcfb212a410", + "0x0000000000000000000000000000000000000000000000000000000000000002" + ] + } + ] +} +``` + + + +### `priv_getPrivacyPrecompileAddress` + +Returns the address of the [privacy precompiled contract](../../concepts/privacy/private-transactions/processing.md). The address is derived and based on the value of the [`privacy-flexible-groups-enabled`](../cli/options.md#privacy-flexible-groups-enabled) option. + +#### Parameters + +None + +#### Returns + +`result`: _string_ - address of the privacy precompile + + + +# curl HTTP request + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"priv_getPrivacyPrecompileAddress","params":[], "id":1}' http://127.0.0.1:8545 +``` + +# wscat WS request + +```bash +{"jsonrpc":"2.0","method":"priv_getPrivacyPrecompileAddress","params":[], "id":1} +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": "0x000000000000000000000000000000000000007e" +} +``` + + + +### `priv_getPrivateTransaction` + +Returns the private transaction if you are a participant, otherwise, `null`. + +#### Parameters + +`transaction`: _string_ - transaction hash returned by [`eea_sendRawTransaction`](#eea_sendrawtransaction) or [`eea_sendTransaction`](https://docs.ethsigner.consensys.net/Reference/API-Methods#eea_sendtransaction). + +#### Returns + +`result`: _object_ - [private transaction object](objects.md#private-transaction-object), or `null` if not a participant in the private transaction + + + +# curl HTTP request + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"priv_getPrivateTransaction","params":["0x623c4ce5275a87b91f4f1c521012d39ca19311c787bde405490f4c0426a71498"], "id":1}' http://127.0.0.1:8545 +``` + +# wscat WS request + +```bash +{"jsonrpc":"2.0","method":"priv_getPrivateTransaction","params":["0x623c4ce5275a87b91f4f1c521012d39ca19311c787bde405490f4c0426a71498"], "id":1} +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + "from": "0xfe3b557e8fb62b89f4916b721be55ceb828dbd73", + "gas": "0x2dc6c0", + "gasPrice": "0x0", + "hash": "0x623c4ce5275a87b91f4f1c521012d39ca19311c787bde405490f4c0426a71498", + "input": "0x608060405234801561001057600080fd5b50336000806101000a81548173ffffffffffffffffffffffffffffffffffffffff021916908373ffffffffffffffffffffffffffffffffffffffff160217905550610221806100606000396000f300608060405260043610610057576000357c0100000000000000000000000000000000000000000000000000000000900463ffffffff1680633fa4f2451461005c5780636057361d1461008757806367e404ce146100b4575b600080fd5b34801561006857600080fd5b5061007161010b565b6040518082815260200191505060405180910390f35b34801561009357600080fd5b506100b260048036038101908080359060200190929190505050610115565b005b3480156100c057600080fd5b506100c96101cb565b604051808273ffffffffffffffffffffffffffffffffffffffff1673ffffffffffffffffffffffffffffffffffffffff16815260200191505060405180910390f35b6000600254905090565b7fc9db20adedc6cf2b5d25252b101ab03e124902a73fcb12b753f3d1aaa2d8f9f53382604051808373ffffffffffffffffffffffffffffffffffffffff1673ffffffffffffffffffffffffffffffffffffffff1681526020018281526020019250505060405180910390a18060028190555033600160006101000a81548173ffffffffffffffffffffffffffffffffffffffff021916908373ffffffffffffffffffffffffffffffffffffffff16021790555050565b6000600160009054906101000a900473ffffffffffffffffffffffffffffffffffffffff169050905600a165627a7a723058208efaf938851fb2d235f8bf9a9685f149129a30fe0f4b20a6c1885dc02f639eba0029", + "nonce": "0x0", + "to": null, + "value": "0x0", + "v": "0xfe8", + "r": "0x654a6a9663ca70bb13e27cca14b3777cc92da184e19a151cdeef2ccbbd5c6405", + "s": "0x5dd4667b020c8a5af7ae28d4c3126f8dcb1187f49dcf0de9d7a39b1651892eef", + "privateFrom": "negmDcN2P4ODpqn/6WkJ02zT/0w0bjhGpkZ8UP6vARk=", + "privateFor": ["g59BmTeJIn7HIcnq8VQWgyh/pDbvbt2eyP0Ii60aDDw="], + "restriction": "restricted" + } +} +``` + + + +### `priv_getTransactionCount` + +Returns the private transaction count for specified account and privacy group. + +:::important + +If sending more than one transaction to be mined in the same block (that is, you are not waiting for the transaction receipt), you must calculate the private transaction nonce outside Besu instead of using `priv_getTransactionCount`. + +::: + +#### Parameters + +- `address`: _string_ - account address + +- `privacyGroupId`: _string_ - privacy group ID + +#### Returns + +`result`: _string_ - integer representing the number of private transactions sent from the address to the specified privacy group + + + +# curl HTTP request + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"priv_getTransactionCount","params":["0xfe3b557e8fb62b89f4916b721be55ceb828dbd73", "kAbelwaVW7okoEn1+okO+AbA4Hhz/7DaCOWVQz9nx5M="], "id":1}' http://127.0.0.1:8545 +``` + +# wscat WS request + +```bash +{"jsonrpc":"2.0","method":"priv_getTransactionCount","params":["0xfe3b557e8fb62b89f4916b721be55ceb828dbd73", "kAbelwaVW7okoEn1+okO+AbA4Hhz/7DaCOWVQz9nx5M="], "id":1} +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": "0x1" +} +``` + + + +### `priv_getTransactionReceipt` + +Returns information about the private transaction after mining the transaction. Receipts for pending transactions are not available. + +#### Parameters + +`transaction`: _string_ - 32-byte hash of a transaction + +#### Returns + +`result`: _object_ - [private Transaction receipt object](objects.md#private-transaction-receipt-object), or `null` if no receipt found + + + +# curl HTTP request + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"priv_getTransactionReceipt","params":["0xf3ab9693ad92e277bf785e1772f29fb1864904bbbe87b0470455ddb082caab9d"],"id":1}' http://127.0.0.1:8545 +``` + +# wscat WS request + +```bash +{"jsonrpc":"2.0","method":"priv_getTransactionReceipt","params":["0xf3ab9693ad92e277bf785e1772f29fb1864904bbbe87b0470455ddb082caab9d"],"id":1} +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + "blockHash": "0xe7212a92cfb9b06addc80dec2a0dfae9ea94fd344efeb157c41e12994fcad60a", + "blockNumber": "0x50", + "contractAddress": "0x493b76031593402e24e16faa81f677b58e2d53f3", + "from": "0xfe3b557e8fb62b89f4916b721be55ceb828dbd73", + "logs": [], + "to": "0xf17f52151ebef6c7334fad080c5704d77216b732", + "transactionHash": "0x36219e92b5f53d4150aa9ef7d2d793118cced523de6724100da5b534e3ceb4b8", + "transactionIndex": "0x0", + "output": "0x6080604052600436106049576000357c010000000000000000000000000000000000000000000 + 0000000000000900463ffffffff1680633fa4f24514604e57806355241077146076575b600080fd5b3480156059 + 57600080fd5b50606060a0565b6040518082815260200191505060405180910390f35b348015608157600080fd5b + 50609e6004803603810190808035906020019092919050505060a6565b005b60005481565b8060008190555050560 + 0a165627a7a723058202bdbba2e694dba8fff33d9d0976df580f57bff0a40e25a46c398f8063b4c00360029", + "commitmentHash": "0x79b9e6b0856db398ad7dc208f15b1d38c0c0b0c5f99e4a443a2c5a85510e96a5", + "status": "0x1", + "privateFrom": "negmDcN2P4ODpqn/6WkJ02zT/0w0bjhGpkZ8UP6vARk=", + "privacyGroupId": "cD636RZlcqVSpoxT/ExbkWQfBO7kPAZO0QlWHErNSL8=", + "logsBloom": "0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000" + } +} +``` + + + +### `priv_newFilter` + +Creates a [log filter](../../../public-networks/concepts/events-and-logs.md) for a private contract. To poll for logs associated with the created filter, use [`priv_getFilterChanges`](#priv_getfilterchanges). To get all logs associated with the filter, use [`priv_getFilterLogs`](#priv_getfilterlogs). + +For private contracts, `priv_newFilter` is the same as [`eth_newFilter`](../../../public-networks/reference/api/index.md#eth_newfilter) for public contracts. + +#### Parameters + +- `privacyGroupId`: _string_ - 32-byte [privacy Group ID](../../concepts/privacy/privacy-groups.md) + +- `filterOptions`: _object_ - [filter options object](../../../public-networks/reference/api/objects.md#filter-options-object) + +:::note + +`fromBlock` and `toBlock` in the filter options object default to `latest`. + +::: + +#### Returns + +`result`: _string_ - filter ID + + + +# curl HTTP request + +```bash +curl -X POST --data '{"jsonrpc": "2.0","method": "priv_newFilter","params": ["4rFldHM792LeP/e2WPkTXZedjwKuTr/KwCFTt6mBbkI=",{"fromBlock": "earliest","toBlock": "latest","addresses": ["0x991cc548c154b2953cc48c02f782e1314097dfbb"],"topics": ["0x85bea11d86cefb165374e0f727bacf21dc2f4ea816493981ecf72dcfb212a410"]}],"id": 1}' http://127.0.0.1:8545 +``` + +# wscat WS request + +```bash +{"jsonrpc": "2.0","method": "priv_newFilter","params": ["4rFldHM792LeP/e2WPkTXZedjwKuTr/KwCFTt6mBbkI=",{"fromBlock": "earliest","toBlock": "latest","addresses": ["0x991cc548c154b2953cc48c02f782e1314097dfbb"],"topics": ["0x85bea11d86cefb165374e0f727bacf21dc2f4ea816493981ecf72dcfb212a410"]}],"id": 1} +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": "0x4a35b92809d73f4f53a2355d62125442" +} +``` + + + +### `priv_uninstallFilter` + +Uninstalls a filter for a private contract with the specified ID. When a filter is no longer required, call this method. + +Filters time out when not requested by [`priv_getFilterChanges`](#priv_getfilterchanges) or [`priv_getFilterLogs`](#priv_getfilterlogs) for 10 minutes. + +For private contracts, `priv_uninstallFilter` is the same as [`eth_uninstallFilter`](../../../public-networks/reference/api/index.md#eth_uninstallfilter) for public contracts. + +#### Parameters + +- `privacyGroupId`: _string_ - 32-byte [privacy group ID](../../concepts/privacy/privacy-groups.md) + +- `filterId`: _string_ - filter ID + +#### Returns + +`result`: _boolean_ - indicates if the filter is successfully uninstalled + + + +# curl HTTP request + +```bash +curl -X POST --data '{"jsonrpc": "2.0","method": "priv_uninstallFilter","params":["4rFldHM792LeP/e2WPkTXZedjwKuTr/KwCFTt6mBbkI=","0x4a35b92809d73f4f53a2355d62125442"],"id": 1}' http://127.0.0.1:8545 +``` + +# wscat WS request + +```bash +{"jsonrpc": "2.0","method": "priv_uninstallFilter","params":["4rFldHM792LeP/e2WPkTXZedjwKuTr/KwCFTt6mBbkI=","0x4a35b92809d73f4f53a2355d62125442"],"id": 1} +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": true +} +``` + + + +## `QBFT` methods + +The `QBFT` API methods provide access to the [QBFT](../../how-to/configure/consensus/qbft.md) consensus engine. + +:::note + +The `QBFT` API methods are not enabled by default for JSON-RPC. To enable the `QBFT` API methods, use the [`--rpc-http-api`](../../../public-networks/reference/cli/options.md#rpc-http-api) or [`--rpc-ws-api`](../../../public-networks/reference/cli/options.md#rpc-ws-api) options. + +::: + +### `qbft_discardValidatorVote` + +Discards a proposal to [add or remove a validator](../../how-to/configure/consensus/qbft.md#add-and-remove-validators) with the specified address. + +#### Parameters + +`address`: _string_ - 20-byte address of proposed validator + +#### Returns + +`result`: _boolean_ - indicates if the proposal is discarded + + + +# curl HTTP request + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"qbft_discardValidatorVote","params":["0xef1bfb6a12794615c9b0b5a21e6741f01e570185"], "id":1}' http://127.0.0.1:8545 +``` + +# wscat WS request + +```bash +{"jsonrpc":"2.0","method":"qbft_discardValidatorVote","params":["0xef1bfb6a12794615c9b0b5a21e6741f01e570185"], "id":1} +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": true +} +``` + + + +### `qbft_getPendingVotes` + +Returns [votes](../../how-to/configure/consensus/qbft.md#add-and-remove-validators) cast in the current [epoch](../../how-to/configure/consensus/qbft.md#genesis-file). + +#### Parameters + +None + +#### Returns + +`result`: _map_ of _strings_ to _booleans_ - map of account addresses to corresponding boolean values indicating the vote for each account; if `true`, the vote is to add a validator. If `false`, the proposal is to remove a validator. + + + +# curl HTTP request + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"qbft_getPendingVotes","params":[], "id":1}' http://127.0.0.1:8545 +``` + +# wscat WS request + +```bash +{"jsonrpc":"2.0","method":"qbft_getPendingVotes","params":[], "id":1} +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + "0xef1bfb6a12794615c9b0b5a21e6741f01e570185": true, + "0x42d4287eac8078828cf5f3486cfe601a275a49a5": true + } +} +``` + + + +### `qbft_getSignerMetrics` + +Provides the following validator metrics for the specified range: + +- Number of blocks from each validator + +- Block number of the last block proposed by each validator (if any proposed in the specified range) + +- All validators present in the last block of the range + +#### Parameters + +- `fromBlockNumber`: _string_ - hexadecimal or decimal integer representing a block number or the string tags `latest`, `earliest`, `pending`, `finalized`, or `safe`, as described in [block parameter](../../../public-networks/how-to/use-besu-api/json-rpc.md#block-parameter) + +- `toBlockNumber`: _string_ - hexadecimal or decimal integer representing a block number or one of the string tags `latest`, `earliest`, `pending`, `finalized`, or `safe`, as described in [block parameter](../../../public-networks/how-to/use-besu-api/json-rpc.md#block-parameter) + +If you specify: + +- No parameters, the call provides metrics for the last 100 blocks, or all blocks if there are less than 100 blocks. + +- Only the first parameter, the call provides metrics for all blocks from the block specified to the latest block. + +#### Returns + +`result`: _array_ of _objects_ - list of validator objects + +:::note + +The proposer of the genesis block has address `0x0000000000000000000000000000000000000000`. + +::: + + + +# curl HTTP + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"qbft_getSignerMetrics","params":["1", "100"], "id":1}' http://127.0.0.1:8545 +``` + +# wscat WS + +```bash +{"jsonrpc":"2.0","method":"qbft_getSignerMetrics","params":["1", "100"], "id":1} +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": [ + { + "address": "0x7ffc57839b00206d1ad20c69a1981b489f772031", + "proposedBlockCount": "0x21", + "lastProposedBlockNumber": "0x61" + }, + { + "address": "0x42eb768f2244c8811c63729a21a3569731535f06", + "proposedBlockCount": "0x21", + "lastProposedBlockNumber": "0x63" + }, + { + "address": "0xb279182d99e65703f0076e4812653aab85fca0f0", + "proposedBlockCount": "0x21", + "lastProposedBlockNumber": "0x62" + } + ] +} +``` + + + +### `qbft_getValidatorsByBlockHash` + +Lists the validators defined in the specified block. + +#### Parameters + +`block`: _string_ - 32-byte block hash + +#### Returns + +`result`: _array_ of _strings_ - list of validator addresses + + + +# curl HTTP request + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"qbft_getValidatorsByBlockHash","params":["0xbae7d3feafd743343b9a4c578cab5e5d65eb735f6855fb845c00cab356331256"], "id":1}' http://127.0.0.1:8545 +``` + +# wscat WS request + +```bash +{"jsonrpc":"2.0","method":"qbft_getValidatorsByBlockHash","params":["0xbae7d3feafd743343b9a4c578cab5e5d65eb735f6855fb845c00cab356331256"], "id":1} +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": [ + "0x42d4287eac8078828cf5f3486cfe601a275a49a5", + "0xb1b2bc9582d2901afdc579f528a35ca41403fa85", + "0xef1bfb6a12794615c9b0b5a21e6741f01e570185" + ] +} +``` + + + +### `qbft_getValidatorsByBlockNumber` + +Lists the validators defined in the specified block. + +#### Parameters + +- `blockNumber`: _string_ - hexadecimal or decimal integer representing a block number or one of the string tags `latest`, `earliest`, `pending`, `finalized`, or `safe`, as described in [block parameter](../../../public-networks/how-to/use-besu-api/json-rpc.md#block-parameter) + +#### Returns + +`result`: _array_ of _strings_ - list of validator addresses + + + +# curl HTTP request + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"qbft_getValidatorsByBlockNumber","params":["latest"], "id":1}' http://127.0.0.1:8545 +``` + +# wscat WS request + +```bash +{"jsonrpc":"2.0","method":"qbft_getValidatorsByBlockNumber","params":["latest"], "id":1} +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": [ + "0x42d4287eac8078828cf5f3486cfe601a275a49a5", + "0xb1b2bc9582d2901afdc579f528a35ca41403fa85", + "0xef1bfb6a12794615c9b0b5a21e6741f01e570185" + ] +} +``` + + + +### `qbft_proposeValidatorVote` + +Proposes to [add or remove a validator](../../how-to/configure/consensus/qbft.md#add-and-remove-validators) with the specified address. + +#### Parameters + +- `address`: _string_ - account address + +- `proposal`: _boolean_ - `true` to propose adding validator or `false` to propose removing validator + +#### Returns + +`result`: _boolean_ - `true` + + + +# curl HTTP request + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"qbft_proposeValidatorVote","params":["42d4287eac8078828cf5f3486cfe601a275a49a5",true], "id":1}' http://127.0.0.1:8545 +``` + +# wscat WS request + +```bash +{"jsonrpc":"2.0","method":"qbft_proposeValidatorVote","params":["42d4287eac8078828cf5f3486cfe601a275a49a5",true], "id":1} +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": true +} +``` + + + + + +[add or remove a signer with the specified address]: ../../how-to/configure/consensus/clique.md#add-and-remove-signers +[signers for the specified block]: ../../how-to/configure/consensus/clique.md#adding-and-removing-signers +[add or remove a validator]: ../../how-to/configure/consensus/ibft.md#add-and-remove-validators +[permissions configuration file]: ../../how-to/use-permissioning/local.md#permissions-configuration-file +[group of sender and recipients]: ../../concepts/privacy/privacy-groups.md#enterprise-ethereum-alliance-privacy + +\*[EEA]: Enterprise Ethereum Alliance diff --git a/versioned_docs/version-23.10.1/private-networks/reference/api/objects.md b/versioned_docs/version-23.10.1/private-networks/reference/api/objects.md new file mode 100644 index 00000000000..747a50db098 --- /dev/null +++ b/versioned_docs/version-23.10.1/private-networks/reference/api/objects.md @@ -0,0 +1,59 @@ +--- +title: Private network API objects +sidebar_position: 2 +description: Hyperledger Besu private network API objects reference +tags: + - private networks +--- + +# Private network API objects + +The following objects are parameters for or returned by Besu private network API methods. + +:::warning + +This reference contains API objects that apply to only private networks. For API objects that apply to both private and public networks, see the [public network API objects reference](../../../public-networks/reference/api/objects.md). + +::: + +## Private transaction object + +Returned by [`priv_getPrivateTransaction`](index.md#priv_getprivatetransaction). + +| Key | Type | Value | +| --- | :-: | --- | +| `from` | Data, 20 bytes | Address of the sender. | +| `gas` | Quantity | Gas provided by the sender. | +| `gasPrice` | Quantity | Gas price, in Wei, provided by the sender. | +| `input` | Data | The data to create or invoke a contract. | +| `nonce` | Quantity | Number of transactions made by the sender to the privacy group before this one. | +| `to` | Data, 20 bytes | `null` if a contract creation transaction, otherwise, the contract address. | +| `value` | Quantity | `null` because private transactions cannot transfer Ether. | +| `v` | Quantity | ECDSA Recovery ID. | +| `r` | Data, 32 bytes | ECDSA signature r. | +| `s` | Data, 32 bytes | ECDSA signature s. | +| `privateFrom` | Data, 32 bytes | [Tessera](https://docs.tessera.consensys.net/) public key of the sender. | +| `privateFor` | Array of Data, 32 bytes each | [Tessera](https://docs.tessera.consensys.net/) public keys of recipients. Not returned if using `privacyGroupId` to [send the transaction](../../../private-networks/concepts/privacy/privacy-groups.md#privacy-types). | +| `privacyGroupId` | Data, 32 bytes | [Tessera](https://docs.tessera.consensys.net/) privacy group ID of recipients. Not returned if using `privateFor` to [send the transaction](../../../private-networks/concepts/privacy/privacy-groups.md#privacy-types). | +| `restriction` | String | Must be [`restricted`](../../../private-networks/concepts/privacy/private-transactions/index.md). | + +## Private transaction receipt object + +Returned by [`priv_getTransactionReceipt`](index.md#priv_gettransactionreceipt). + +| Key | Type | Value | +| --- | :-: | --- | +| `blockHash` | Data, 32 bytes | Hash of block containing this transaction. | +| `blockNumber` | Quantity | Block number of block containing this transaction. | +| `contractAddress` | Data, 20 bytes | Contract address created if a contract creation transaction, otherwise, `null`. A failed contract creation transaction still produces a contract address value. | +| `from` | Data, 20 bytes | Address of the sender. | +| `logs` | Array | Array of [log objects](../../../public-networks/reference/api/objects.md#log-object) generated by this private transaction. | +| `to` | Data, 20 bytes | Address of the receiver, if sending ether, otherwise, null. | +| `transactionIndex` | Quantity, Integer | Index position of transaction in the block. | +| `revertReason` | String | ABI-encoded string that displays the [reason for reverting the transaction](../../../private-networks/how-to/send-transactions/revert-reason.md). Only available if revert reason is [enabled](../cli/options.md#revert-reason-enabled). | +| `output` | Data | RLP-encoded return value of a contract call if a value returns, otherwise, `null`. | +| `commitmentHash` | Data, 32 bytes | Hash of the privacy marker transaction. | +| `status` | Quantity | Either `0x1` (success) or `0x0` (failure). | +| `privateFrom` | Data, 32 bytes | [Tessera](https://docs.tessera.consensys.net/) public key of the sender. | +| `privateFor` or `privacyGroupId` | Array or Data, 32 bytes | [Tessera](https://docs.tessera.consensys.net/) public keys or privacy group ID of the recipients. | +| `logsBloom` | Data, 256 bytes | Bloom filter for light clients to quickly retrieve related logs. | diff --git a/versioned_docs/version-23.10.1/private-networks/reference/cli/_category_.json b/versioned_docs/version-23.10.1/private-networks/reference/cli/_category_.json new file mode 100644 index 00000000000..bec3b04721b --- /dev/null +++ b/versioned_docs/version-23.10.1/private-networks/reference/cli/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Besu CLI", + "position": 1 +} diff --git a/versioned_docs/version-23.10.1/private-networks/reference/cli/options.md b/versioned_docs/version-23.10.1/private-networks/reference/cli/options.md new file mode 100644 index 00000000000..064549d46f2 --- /dev/null +++ b/versioned_docs/version-23.10.1/private-networks/reference/cli/options.md @@ -0,0 +1,709 @@ +--- +title: Private network options +sidebar_position: 1 +description: Hyperledger Besu private networks CLI reference +tags: + - private networks +--- + +# Private network command line options + +This reference describes the syntax of the Hyperledger Besu private network command line interface (CLI) options. + +:::danger + +This reference contains options that apply to only private networks. For options that apply to both private and public networks, see the [public network options reference](../../../public-networks/reference/cli/options.md). + +::: + +## Specify options + +You can specify Besu options: + +- On the command line. + + ```bash + besu [OPTIONS] [SUBCOMMAND] + ``` + +- As an environment variable. For each command line option, the equivalent environment variable is: + + - Uppercase. + - `_` replaces `-`. + - Has a `BESU_` prefix. + + For example, set `--miner-coinbase` using the `BESU_MINER_COINBASE` environment variable. + +- In a [configuration file](../../../public-networks/how-to/configuration-file.md). + +If you specify an option in more than one place, the order of priority is command line, environment variable, configuration file. + +If using Bash or Z shell, you can view option suggestions by entering `--` and pressing the Tab key twice. + +```bash +besu --Tab+Tab +``` + +:::caution + +Characters such as smart quotes and long (em) hyphens don't work in Besu command line options. Ensure quotes aren't automatically converted to smart quotes, or double hyphens combined into em hyphens. + +::: + +## Options + +### `permissions-accounts-config-file` + + + +# Syntax + +```bash +--permissions-accounts-config-file= +``` + +# Example + +```bash +--permissions-accounts-config-file=/home/me/me_configFiles/myPermissionsFile +``` + +# Environment variable + +```bash +BESU_PERMISSIONS_ACCOUNTS_CONFIG_FILE=/home/me/me_configFiles/myPermissionsFile +``` + +# Configuration file + +```bash +permissions-accounts-config-file="/home/me/me_configFiles/myPermissionsFile" +``` + + + +The [accounts permissions configuration file]. The default is the `permissions_config.toml` file in the [data directory](../../../public-networks/reference/cli/options.md#data-path). + +:::tip + +`--permissions-accounts-config-file` and [`--permissions-nodes-config-file`](#permissions-nodes-config-file) can use the same file. + +::: + +### `permissions-accounts-config-file-enabled` + + + +# Syntax + +```bash +--permissions-accounts-config-file-enabled[=] +``` + +# Example + +```bash +--permissions-accounts-config-file-enabled=true +``` + +# Environment variable + +```bash +BESU_PERMISSIONS_ACCOUNTS_CONFIG_FILE_ENABLED=true +``` + +# Configuration file + +```bash +permissions-accounts-config-file-enabled=true +``` + + + +Enables or disables file-based account level permissions. The default is `false`. + +### `permissions-accounts-contract-address` + + + +# Syntax + +```bash +--permissions-accounts-contract-address= +``` + +# Example + +```bash +--permissions-accounts-contract-address=xyz +``` + +# Environment variable + +```bash +BESU_PERMISSIONS_ACCOUNTS_CONTRACT_ADDRESS=xyz +``` + +# Configuration file + +```bash +permissions-accounts-contract-address="xyz" +``` + + + +The contract address for [onchain account permissioning](../../concepts/permissioning/onchain.md). + +### `permissions-accounts-contract-enabled` + + + +# Syntax + +```bash +--permissions-accounts-contract-enabled[=] +``` + +# Example + +```bash +--permissions-accounts-contract-enabled=true +``` + +# Environment variable + +```bash +BESU_PERMISSIONS_ACCOUNTS_CONTRACT_ENABLED=true +``` + +# Configuration file + +```bash +permissions-accounts-contract-enabled=true +``` + + + +Enables or disables contract-based [onchain account permissioning](../../concepts/permissioning/onchain.md). The default is `false`. + +### `permissions-nodes-config-file` + + + +# Syntax + +```bash +--permissions-nodes-config-file= +``` + +# Example + +```bash +--permissions-nodes-config-file=/home/me/me_configFiles/myPermissionsFile +``` + +# Environment variable + +```bash +BESU_PERMISSIONS_NODES_CONFIG_FILE=/home/me/me_configFiles/myPermissionsFile +``` + +# Configuration file + +```bash +permissions-nodes-config-file="/home/me/me_configFiles/myPermissionsFile" +``` + + + +The [nodes permissions configuration file]. The default is the `permissions_config.toml` file in the [data directory](../../../public-networks/reference/cli/options.md#data-path). + +:::tip + +`--permissions-nodes-config-file` and [`--permissions-accounts-config-file`](#permissions-accounts-config-file) can use the same file. + +::: + +### `permissions-nodes-config-file-enabled` + + + +# Syntax + +```bash +--permissions-nodes-config-file-enabled[=] +``` + +# Example + +```bash +--permissions-nodes-config-file-enabled=true +``` + +# Environment variable + +```bash +BESU_PERMISSIONS_NODES_CONFIG_FILE_ENABLED=true +``` + +# Configuration file + +```bash +permissions-nodes-config-file-enabled=true +``` + + + +Enables or disables file-based node level permissions. The default is `false`. + +### `permissions-nodes-contract-address` + + + +# Syntax + +```bash +--permissions-nodes-contract-address= +``` + +# Example + +```bash +--permissions-nodes-contract-address=xyz +``` + +# Environment variable + +```bash +BESU_PERMISSIONS_NODES_CONTRACT_ADDRESS=xyz +``` + +# Configuration file + +```bash +permissions-nodes-contract-address="xyz" +``` + + + +The contract address for [onchain node permissioning](../../concepts/permissioning/onchain.md). + +### `permissions-nodes-contract-enabled` + + + +# Syntax + +```bash +--permissions-nodes-contract-enabled[=] +``` + +# Example + +```bash +--permissions-nodes-contract-enabled=true +``` + +# Environment variable + +```bash +BESU_PERMISSIONS_NODES_CONTRACT_ENABLED=true +``` + +# Configuration file + +```bash +permissions-nodes-contract-enabled=true +``` + + + +Enables or disables contract-based [onchain node permissioning](../../concepts/permissioning/onchain.md). The default is `false`. + +### `permissions-nodes-contract-version` + + + +# Syntax + +```bash +--permissions-nodes-contract-version= +``` + +# Example + +```bash +--permissions-nodes-contract-version=2 +``` + +# Environment variable + +```bash +BESU_PERMISSIONS_NODES_CONTRACT_VERSION=2 +``` + +# Configuration file + +```bash +permissions-nodes-contract-version=2 +``` + + + +Version of the EEA [node permissioning interface](../../how-to/use-permissioning/onchain.md#specify-the-permissioning-contract-interface-version). The default is 1. + +### `privacy-enabled` + + + +# Syntax + +```bash +--privacy-enabled[=] +``` + +# Example + +```bash +--privacy-enabled=false +``` + +# Environment variable + +```bash +BESU_PRIVACY_ENABLED=false +``` + +# Configuration file + +```bash +privacy-enabled=false +``` + + + +Enables or disables [private transactions](../../concepts/privacy/index.md). The default is `false`. + +:::important + +Using private transactions with [pruning](../../../public-networks/concepts/data-storage-formats.md) or [fast sync](../../../public-networks/reference/cli/options.md#sync-mode) is not supported. + +::: + +### `privacy-marker-transaction-signing-key-file` + + + +# Syntax + +```bash +--privacy-marker-transaction-signing-key-file= +``` + +# Example + +```bash +--privacy-marker-transaction-signing-key-file=/home/me/me_node/myPrivateKey +``` + +# Environment variable + +```bash +BESU_PRIVACY_MARKER_TRANSACTION_SIGNING_KEY_FILE=/home/me/me_node/myPrivateKey +``` + +# Configuration file + +```bash +privacy-marker-transaction-signing-key-file="/home/me/me_node/myPrivateKey" +``` + + + +`` is the name of the private key file used to [sign privacy marker transactions](../../how-to/use-privacy/sign-pmts.md). + +:::note + +This can be the same file used by [`--node-private-key-file`](../../../public-networks/reference/cli/options.md#node-private-key-file), or a different key file to identify who signed the privacy marker transaction. + +::: + +You must specify this option if you're using: + +- a privacy network where you pay gas. Also, the associated account must contain adequate funds. +- [account permissioning] and privacy. You must include the corresponding public key in the accounts allowlist. + +If you do not specify this option (for example, in a free gas network), Besu signs each transaction with a different randomly generated key. + +### `privacy-multi-tenancy-enabled` + + + +# Syntax + +```bash +--privacy-multi-tenancy-enabled[=] +``` + +# Example + +```bash +--privacy-multi-tenancy-enabled=false +``` + +# Environment variable + +```bash +BESU_PRIVACY_MULTI_TENANCY_ENABLED=false +``` + +# Configuration file + +```bash +privacy-multi-tenancy-enabled=false +``` + + + +Enables or disables [multi-tenancy](../../concepts/privacy/multi-tenancy.md) for private transactions. The default is `false`. + +### `privacy-flexible-groups-enabled` + + + +# Syntax + +```bash +--privacy-flexible-groups-enabled[=] +``` + +# Example + +```bash +--privacy-flexible-groups-enabled=true +``` + +# Environment variable + +```bash +BESU_PRIVACY_FLEXIBLE_GROUPS_ENABLED=true +``` + +# Configuration file + +```bash +privacy-flexible-groups-enabled=true +``` + + + +Enables or disables [flexible privacy groups](../../concepts/privacy/flexible-privacy.md). The default is `false`. + +Deprecated syntax for this option is `--privacy-onchain-groups-enabled`. + +### `privacy-public-key-file` + + + +# Syntax + +```bash +--privacy-public-key-file= +``` + +# Example + +```bash +--privacy-public-key-file=Tessera/nodeKey.pub +``` + +# Environment variable + +```bash +BESU_PRIVACY_PUBLIC_KEY_FILE=Tessera/nodeKey.pub +``` + +# Configuration file + +```bash +privacy-public-key-file="Tessera/nodeKey.pub" +``` + + + +The [public key of the Tessera node](https://docs.tessera.consensys.net/). + +:::important + +You cannot specify `privacy-public-key-file` when [`--privacy-multi-tenancy-enabled`](#privacy-multi-tenancy-enabled) is `true` + +::: + +### `privacy-tls-enabled` + + + +# Syntax + +```bash +--privacy-tls-enabled[=] +``` + +# Example + +```bash +--privacy-tls-enabled=false +``` + +# Environment variable + +```bash +BESU_PRIVACY_TLS_ENABLED=false +``` + +# Configuration file + +```bash +privacy-tls-enabled=false +``` + + + +Enables or disables [TLS on communication with the private transaction manager]. The default is false. + +### `privacy-tls-keystore-file` + + + +# Syntax + +```bash +--privacy-tls-keystore-file= +``` + +# Example + +```bash +--privacy--keystore-file=/home/me/me_node/key +``` + +# Environment variable + +```bash +BESU_PRIVACY_TLS_KEYSTORE_FILE=/home/me/me_node/key +``` + +# Configuration file + +```bash +privacy-tls-keystore-file="/home/me/me_node/key" +``` + + + +The keystore file (in PKCS #12 format) containing the private key and the certificate presented during authentication. + +You must specify `privacy-tls-keystore-file` if [`--privacy-tls-enabled`](#privacy-tls-enabled) is `true`. + +### `privacy-tls-keystore-password-file` + + + +# Syntax + +```bash +--privacy-tls-keystore-password-file= +``` + +# Example + +```bash +--privacy-tls-keystore-password-file=/home/me/me_node/password +``` + +# Environment variable + +```bash +BESU_PRIVACY_TLS_KEYSTORE_PASSWORD_FILE=/home/me/me_node/password +``` + +# Configuration file + +```bash +privacy-tls-keystore-password-file="/home/me/me_node/password" +``` + + + +The path to the file containing the password to decrypt the keystore. + +### `privacy-tls-known-enclave-file` + + + +# Syntax + +```bash +--privacy-tls-known-enclave-file= +``` + +# Example + +```bash +--privacy-tls-known-enclave-file=/home/me/me_node/knownEnclave +``` + +# Environment variable + +```bash +BESU_PRIVACY_TLS_KNOWN_ENCLAVE_FILE=/home/me/me_node/knownEnclave +``` + +# Configuration file + +```bash +privacy-tls-known-enclave-file="/home/me/me_node/knownEnclave" +``` + + + +The path to the file containing the hostnames, ports, and SHA256 certificate fingerprints of the [authorized privacy enclave](../../how-to/configure/tls/client-and-server.md#create-the-known-servers-file). + +### `privacy-url` + + + +# Syntax + +```bash +--privacy-url= +``` + +# Example + +```bash +--privacy-url=http://127.0.0.1:8888 +``` + +# Environment variable + +```bash +BESU_PRIVACY_URL=http://127.0.0.1:8888 +``` + +# Configuration file + +```bash +privacy-url="http://127.0.0.1:8888" +``` + + + +The URL on which the [Tessera node](../../tutorials/privacy/index.md#3-create-tessera-configuration-files) is running. + + + +[accounts permissions configuration file]: ../../how-to/use-permissioning/local.md#permissions-configuration-file +[nodes permissions configuration file]: ../../how-to/use-permissioning/local.md#permissions-configuration-file +[account permissioning]: ../../concepts/permissioning/index.md#account-permissioning +[TLS on communication with the private transaction manager]: ../../concepts/privacy/index.md#private-transaction-manager diff --git a/versioned_docs/version-23.10.1/private-networks/reference/cli/subcommands.md b/versioned_docs/version-23.10.1/private-networks/reference/cli/subcommands.md new file mode 100644 index 00000000000..5b8b07c4dbd --- /dev/null +++ b/versioned_docs/version-23.10.1/private-networks/reference/cli/subcommands.md @@ -0,0 +1,143 @@ +--- +title: Private network subcommands +sidebar_position: 2 +description: Hyperledger Besu command line interface subcommands +tags: + - private networks +--- + +# Private network subcommands + +This reference describes the syntax of the Hyperledger Besu private network command line interface (CLI) subcommands. + +:::danger + +This reference contains subcommands that apply to only private networks. For subcommands that apply to both private and public networks, see the [public network subcommands reference](../../../public-networks/reference/cli/subcommands.md). + +::: + +To start a Besu node using subcommands, run: + +```bash +besu [OPTIONS] [SUBCOMMAND] [SUBCOMMAND OPTIONS] +``` + +If using Bash or Z shell, you can view subcommand suggestions by pressing the Tab key twice. + +```bash +besu Tab+Tab +``` + +## `operator` + +Provides operator actions. + +### `generate-blockchain-config` + + + +# Syntax + +```bash +besu operator generate-blockchain-config --config-file= --to= [--genesis-file-name=] [--private-key-file-name=] [--public-key-file-name=] +``` + +# Example + +```bash +besu operator generate-blockchain-config --config-file=config.json --to=myNetworkFiles +``` + + + +Generates an [IBFT 2.0](../../how-to/configure/consensus/ibft.md#genesis-file) or [QBFT](../../how-to/configure/consensus/qbft.md#genesis-file) genesis file. + +The configuration file has two nested JSON nodes. The first is the `genesis` property defining the IBFT 2.0 or QBFT genesis file, except for the `extraData` string. The second is the `blockchain` property defining the number of key pairs to generate. + +## `rlp` + +Provides RLP related actions. + +### `encode` + + + +# Syntax + +```bash +besu rlp encode [--from=] [--to=] [--type=] +``` + +# File example + + ```bash + besu rlp encode --from=ibft_extra_data.json --to=extra_data_for_ibft_genesis.txt --type=IBFT_EXTRA_DATA + ``` + +# Standard input/output example + +```bash +cat extra_data.json | besu rlp encode > rlp.txt +``` + + + +Encodes the RLP hexadecimal string for use in an [IBFT 2.0](../../how-to/configure/consensus/ibft.md#genesis-file) or [QBFT](../../how-to/configure/consensus/qbft.md#genesis-file) genesis file. The default type is `IBFT_EXTRA_DATA`. + +Supported types are: + +- `IBFT_EXTRA_DATA` - The IBFT 2.0 genesis file includes the `IBFT_EXTRA_DATA` type in the [`extraData`](../../how-to/configure/consensus/ibft.md#extra-data) property. + +- `QBFT_EXTRA_DATA` - The QBFT genesis file includes the `QBFT_EXTRA_DATA` type in the [`extraData`](../../how-to/configure/consensus/qbft.md#extra-data) property. + +## IBFT 2.0 extra data + +To generate the RLP encoded `extraData` string, specify a JSON input that is an array of validator addresses in ascending order. + +:::tip JSON Schema for IBFT_EXTRA_DATA + +Use the following JSON Schema to validate that your JSON data is well formed. To validate your JSON content, use an online validation tool, such as [JSON Schema Validator](https://www.jsonschemavalidator.net/). + +```json +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "$id": "http://org.hyperledger.besu/cli_rlp_ibft_extra_data.json", + "type": "array", + "definitions": {}, + "title": "IBFT extra data", + "description": "JSON format used as input to generate an IBFT extra data RLP string", + "items": { + "$id": "#/address", + "type": "string", + "title": "Validator address", + "description": "The validator node address", + "default": "", + "examples": [ + "be068f726a13c8d46c44be6ce9d275600e1735a4", + "5ff6f4b66a46a2b2310a6f3a93aaddc0d9a1c193" + ], + "pattern": "^([0-9a-f]{40})$" + } +} +``` + +Example IBFT_EXTRA_DATA encoding + + + +# JSON input + +```json +[ + "be068f726a13c8d46c44be6ce9d275600e1735a4", + "5ff6f4b66a46a2b2310a6f3a93aaddc0d9a1c193" +] +``` + +# RLP output + +``` +0xf853a00000000000000000000000000000000000000000000000000000000000000000ea94be068f726a13c8d46c44be6ce9d275600e1735a4945ff6f4b66a46a2b2310a6f3a93aaddc0d9a1c193808400000000c0 +``` + + diff --git a/versioned_docs/version-23.10.1/private-networks/reference/index.md b/versioned_docs/version-23.10.1/private-networks/reference/index.md new file mode 100644 index 00000000000..079ea80b12b --- /dev/null +++ b/versioned_docs/version-23.10.1/private-networks/reference/index.md @@ -0,0 +1,23 @@ +--- +description: private networks reference overview +tags: + - private networks +--- + +# Reference + +This section provides reference material for private network features. + +The following features and resources are shared with [public networks](../../public-networks/index.md) and the content can be found in the public networks section: + +- Besu command line: + - [Standard options](../../public-networks/reference/cli/options.md) + - [Standard subcommands](../../public-networks/reference/cli/subcommands.md) +- Besu API: + - [Standard Besu API methods](../../public-networks/reference/api/index.md) + - [Standard Besu API objects](../../public-networks/reference/api/objects.md) +- [Genesis file items](../../public-networks/reference/genesis-items.md) +- [EVM tool options](../../public-networks/reference/evm-tool.md) +- [Transaction trace types](../../public-networks/reference/trace-types.md) +- [Projects using Besu](../../public-networks/reference/projects-using-besu.md) +- [Security disclosure policy](../../public-networks/reference/disclosure.md) diff --git a/versioned_docs/version-23.10.1/private-networks/reference/plugin-api-interfaces.md b/versioned_docs/version-23.10.1/private-networks/reference/plugin-api-interfaces.md new file mode 100644 index 00000000000..54d4beda062 --- /dev/null +++ b/versioned_docs/version-23.10.1/private-networks/reference/plugin-api-interfaces.md @@ -0,0 +1,61 @@ +--- +title: Plugin API interfaces +sidebar_position: 4 +description: Plugin interfaces +tags: + - private networks +--- + +# Plugin API interfaces + +API interfaces in Hyperledger Besu allow users to [build plugins](../concepts/plugins.md) to extend Besu functionality. + +For more information about the available interfaces, see the [Plugin API Javadoc](https://javadoc.io/doc/org.hyperledger.besu/plugin-api/latest/index.html). + +:::note Javadoc issue + +The plugin API documentation is currently not being updated. We're working on a fix, but in the meantime, some links are temporarily pointing to wiki.hyperledger.org. + +::: + +## Core plugin classes + +The following table lists the interfaces providing core plugin classes. + +| Interface | Description | +| --- | --- | +| [**BesuContext**](https://wiki.hyperledger.org/display/BESU/BesuContext) | Allows plugins to access Besu services. | +| [**BesuPlugin**](https://javadoc.io/doc/org.hyperledger.besu/plugin-api/latest/org/hyperledger/besu/plugin/BesuPlugin.html) | Used to manage the plugin lifecycle. | + +## Plugin services + +The following table lists interfaces providing services you can retrieve. + +| Interface | Description | +| --- | --- | +| [**BesuEvents**](https://javadoc.io/doc/org.hyperledger.besu/plugin-api/latest/org/hyperledger/besu/plugin/services/BesuEvents.html) | Allows plugins to attach to events during Besu operation. | +| [**BesuConfiguration**](https://javadoc.io/doc/org.hyperledger.besu/plugin-api/latest/org/hyperledger/besu/plugin/services/BesuConfiguration.html) | Provides file system locations of Besu's storage. | +| [**IbftQueryService**](https://javadoc.io/doc/org.hyperledger.besu/plugin-api/latest/org/hyperledger/besu/plugin/services/query/IbftQueryService.html) | Allows query of the IBFT 2.0 aspects of the blockchain. | +| [**MetricCategoryRegistry**](https://javadoc.io/doc/org.hyperledger.besu/plugin-api/latest/org/hyperledger/besu/plugin/services/metrics/MetricCategoryRegistry.html) | Adds a new metrics category to the CLI. | +| [**MetricsSystem**](https://javadoc.io/doc/org.hyperledger.besu/plugin-api/latest/org/hyperledger/besu/plugin/services/MetricsSystem.html) | Register metrics with the Prometheus endpoint. | +| [**PoaQueryService**](https://javadoc.io/doc/org.hyperledger.besu/plugin-api/latest/org/hyperledger/besu/plugin/services/query/PoaQueryService.html) | Query the current state of Clique and IBFT 2.0 consensus protocols. | +| [**PicoCLIOptions**](https://javadoc.io/doc/org.hyperledger.besu/plugin-api/latest/org/hyperledger/besu/plugin/services/PicoCLIOptions.html) | Adds CLI commands to the Besu command line. | +| [**SecurityModuleService**](https://javadoc.io/doc/org.hyperledger.besu/plugin-api/latest/org/hyperledger/besu/plugin/services/SecurityModuleService.html) | Allows plugins to register a security module. | +| [**StorageService**](https://javadoc.io/doc/org.hyperledger.besu/plugin-api/latest/org/hyperledger/besu/plugin/services/StorageService.html) | Allows plugins to register as a storage engine. For example, to connect to a hardware security module (HSM). | +| [**PermissioningService**](https://wiki.hyperledger.org/display/BESU/PermissioningService) | Allows for fine grain control of node connection and node messaging permissioning. | +| [**PrivacyPluginService**](https://wiki.hyperledger.org/display/BESU/PrivacyPluginService) | Provides a way to define how [privacy marker transactions] are created, and what private genesis to use. | +| [**RpcEndpointService**](https://wiki.hyperledger.org/display/BESU/RpcEndpointService) | Register custom RPC endpoints. | + +To use the interfaces in your plugin, ensure the [Gradle build file](https://github.com/ConsenSys/PluginsAPIDemo/blob/957628b3c6f533f3c3f405e2a17e369cd1f02c31/build.gradle) contains the `https://hyperledger.jfrog.io/hyperledger/besu-maven` repository and the `plugin-api` dependency. + +:::warning Known issue + +As indicated in [issue #406](https://github.com/hyperledger/besu-docs/issues/406), plugins may need to access the parsed command line during registration, but the command line is not yet initialized at this stage. + +It's in our roadmap to improve lifecycle steps and provide additional visibility for some data. A workaround is to create a supplier during the `register` step and store it in memory. + +The `start` step can be ignored and your plugin module will be instantiated when the command line interface is parsed and available. + +::: + +[privacy marker transactions]: ../concepts/privacy/private-transactions/processing.md diff --git a/versioned_docs/version-23.10.1/private-networks/tutorials/_category_.json b/versioned_docs/version-23.10.1/private-networks/tutorials/_category_.json new file mode 100644 index 00000000000..25d3afe68ac --- /dev/null +++ b/versioned_docs/version-23.10.1/private-networks/tutorials/_category_.json @@ -0,0 +1,8 @@ +{ + "label": "Tutorials", + "position": 5, + "link": { + "type": "generated-index", + "slug": "private-networks/tutorials" + } +} diff --git a/versioned_docs/version-23.10.1/private-networks/tutorials/azure.md b/versioned_docs/version-23.10.1/private-networks/tutorials/azure.md new file mode 100644 index 00000000000..ab62e978fcc --- /dev/null +++ b/versioned_docs/version-23.10.1/private-networks/tutorials/azure.md @@ -0,0 +1,98 @@ +--- +title: Deploy using Microsoft Azure +sidebar_position: 10 +description: Deploy a private IBFT 2.0 network using Microsoft Azure. +tags: + - private networks +--- + +# Deploy private network example on Azure + +The [Quorum Dev Quickstart on Azure Marketplace] enables deploying a private IBFT 2.0 network, which includes: + +- A bootnode. +- An RPC node. +- Three regular nodes. +- A block explorer. +- Prometheus and Grafana with the Besu dashboard installed. + +These are deployed on a single Azure VM in minutes. + +Once deployed, you can develop and test applications and connect to the Visual Studio Code (VSCode) plugin using the RPC endpoint `http:///jsonrpc`. + +## Overview + +The following is a high-level overview of the deployed network. + +![Image landing](../../assets/images/sampleNetworks-poa.png) + +## Deploy + +To deploy the private network example on Azure: + +1. Create a Resource Group in the [Azure Portal](https://portal.azure.com). + +1. Go to the [Quorum Dev Quickstart on Azure Marketplace]. + +1. Click **Get It Now** and **Continue**. The Quickstart landing page is displayed. + + ![Image landing](../../assets/images/mp_0_landing.png) + +1. Click **Create**. The **Basics** page is displayed. + + ![Image basics](../../assets/images/mp_1_basics.png) + +1. Enter: + + - Details of the Resource Group you created earlier. + - Basic user credentials to start a VM. + - Prefix for your new VM and any other resources created. + - Region to which you wish to deploy the VM. + +1. Click **Next: Size** and select the size of the VM you want to use. + +1. To start the deployment, click **Review + create** at the bottom left of the page. + + The deployment typically takes 3--5 minutes. The progress of your deployment is displayed. + + When the deployment is complete, the resources created are displayed. + +1. Click **Go to Resource**. Everything created in the deployment is displayed. + +1. Click on the VM name. The VM details such as the IP and DNS name are displayed. Use the IP and DNS name displayed to connect to the VM, either in browser or via RPC calls. + +## Block explorer + +To display the block explorer, open a new tab and enter either the IP of the VM or the DNS name. + +![Image be](../../assets/images/mp_8_block_explorer.png) + +## Metrics + +The deployment includes Prometheus metrics and Grafana with a custom Besu Dashboard installed. To display the dashboard: + +1. Open a new tab and enter the IP or DNS name appended with `/grafana`. For example: `http:///grafana`. + +1. Click on home and select the Besu dashboard. + + ![Grafana screenshot](../../assets/images/mp_9_grafana.png) + +The dashboard provides a visual way to monitor your network and nodes as the chain progresses. Alerting can also be configured. + +## Connect to VM RPC endpoint + +You can connect dapps or develop directly from the IDE by using VSCode and connecting to the VM RPC endpoint. The endpoint is the DNS name appended with `/jsonrpc`: `http:///jsonrpc`. + +## SSH + +You can SSH into the VM to see how everything is set up and working. Use the credentials from step 5 of [deployment](#deploy) and your preferred client: + +```bash +ssh username@ +``` + +To list all containers running, run `docker ps`. Find the complete setup in `/home//besu-quickstart`. + +![Image ssh](../../assets/images/mp_10_ssh.png) + +[Quorum Dev Quickstart on Azure Marketplace]: https://azuremarketplace.microsoft.com/en-us/marketplace/apps/consensys.quorum-dev-quickstart diff --git a/versioned_docs/version-23.10.1/private-networks/tutorials/clique.md b/versioned_docs/version-23.10.1/private-networks/tutorials/clique.md new file mode 100644 index 00000000000..5a92e40122f --- /dev/null +++ b/versioned_docs/version-23.10.1/private-networks/tutorials/clique.md @@ -0,0 +1,272 @@ +--- +title: Create a Clique network +sidebar_position: 4 +description: Create a private network using the Clique consensus protocol. +tags: + - private networks +--- + +# Create a private network using Clique + +A private network provides a configurable network for testing. This private network uses the [Clique (proof of authority) consensus protocol]. + +:::danger + +The steps in this tutorial create an isolated, but not protected or secure, Ethereum private network. We recommend running the private network behind a properly configured firewall. + +::: + +## Prerequisites + +- [Hyperledger Besu](../get-started/install/binary-distribution.md) +- [Curl (or similar webservice client)](https://curl.haxx.se/download.html). + +## Steps + +Listed on the right-hand side of the page are the steps to create a private network using Clique. + +### 1. Create directories + +Each node requires a data directory for the blockchain data. When the node starts, Besu saves the [node key](../../public-networks/concepts/node-keys.md) in this directory. + +Create directories for your private network, each of the three nodes, and a data directory for each node: + +```bash +Clique-Network/ +├── Node-1 +│   ├── data +├── Node-2 +│   ├── data +└── Node-3 + ├── data +``` + +### 2. Get the address for Node-1 + +In Clique networks, you must include the address of at least one initial signer in the genesis file. For this Clique network, we'll use Node-1 as the initial signer. This requires obtaining the address for Node-1. + +To get the address for Node-1, in the `Node-1` directory, use the [`public-key export-address`](../../public-networks/reference/cli/subcommands.md#export-address) subcommand to write the node address to the specified file (`node1Address` in this example). + + + +# MacOS + +```bash +besu --data-path=data public-key export-address --to=data/node1Address +``` + +# Windows + +```bash +besu --data-path=data public-key export-address --to=data\node1Address +``` + + + +### 3. Create the genesis file + +The genesis file defines the genesis block of the blockchain (that is, the start of the blockchain). The [Clique genesis file](../how-to/configure/consensus/clique.md#genesis-file) includes the address of Node-1 as the initial signer in the `extraData` field. + +All nodes in a network must use the same genesis file. + +Copy the following genesis definition to a file called `cliqueGenesis.json` and save it in the `Clique-Network` directory: + +```json +{ + "config": { + "chainId": 1337, + "berlinBlock": 0, + "clique": { + "blockperiodseconds": 15, + "epochlength": 30000 + } + }, + "coinbase": "0x0000000000000000000000000000000000000000", + "difficulty": "0x1", + + "extraData": "0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000", + "gasLimit": "0xa00000", + "mixHash": "0x0000000000000000000000000000000000000000000000000000000000000000", + "nonce": "0x0", + "timestamp": "0x5c51a607", + "alloc": { + "fe3b557e8fb62b89f4916b721be55ceb828dbd73": { + "privateKey": "8f2a55949038a9610f50fb23b5883af3b4ecb3c3bb792cbcefbd1542c692be63", + "comment": "private key and this comment are ignored. In a real chain, the private key should NOT be stored", + "balance": "0xad78ebc5ac6200000" + }, + "627306090abaB3A6e1400e9345bC60c78a8BEf57": { + "privateKey": "c87509a1c067bbde78beb793e6fa76530b6382a4c0241e5e4a9ec0a0f44dc0d3", + "comment": "private key and this comment are ignored. In a real chain, the private key should NOT be stored", + "balance": "90000000000000000000000" + }, + "f17f52151EbEF6C7334FAD080c5704D77216b732": { + "privateKey": "ae6ae8e5ccbfb04590405997ee2d52d2b330726137b875053c36d94e974d162f", + "comment": "private key and this comment are ignored. In a real chain, the private key should NOT be stored", + "balance": "90000000000000000000000" + } + } +} +``` + +:::note + +We recommend specifying the latest [milestone](../../public-networks/reference/genesis-items.md#milestone-blocks) when creating the genesis file for a private network. This ensures you are using the most up-to-date protocol and have access to the most recent opcodes. + +::: + +In `extraData`, replace `` with the [address for Node-1](#2-get-the-address-for-node-1), excluding the 0x prefix. + +```json +{ + ... +"extraData":"0x0000000000000000000000000000000000000000000000000000000000000000b9b81ee349c3807e46bc71aa2632203c5b4620340000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000", + ... +} +``` + +:::warning + +Do not use the accounts in `alloc` in the genesis file on Mainnet or any public network except for testing. The private keys display, which means the accounts are not secure. + +::: + +### 4. Start the first node as the bootnode + +Start Node-1: + + + +# MacOS + +```bash +besu --data-path=data --genesis-file=../cliqueGenesis.json --network-id 123 --rpc-http-enabled --rpc-http-api=ETH,NET,CLIQUE --host-allowlist="*" --rpc-http-cors-origins="all" +``` + +# Windows + +```bash +besu --data-path=data --genesis-file=..\cliqueGenesis.json --network-id 123 --rpc-http-enabled --rpc-http-api=ETH,NET,CLIQUE --host-allowlist="*" --rpc-http-cors-origins="all" +``` + + + +The command line enables: + +- The JSON-RPC API using the [`--rpc-http-enabled`](../../public-networks/reference/cli/options.md#rpc-http-enabled) option +- The ETH, NET, and CLIQUE APIs using the [`--rpc-http-api`](../../public-networks/reference/cli/options.md#rpc-http-api) option +- All-host access to the HTTP JSON-RPC API using the [`--host-allowlist`](../../public-networks/reference/cli/options.md#host-allowlist) option +- All-domain access to the node through the HTTP JSON-RPC API using the [`--rpc-http-cors-origins`](../../public-networks/reference/cli/options.md#rpc-http-cors-origins) option + +When the node starts, the [enode URL](../../public-networks/concepts/node-keys.md#enode-url) displays. Copy the enode URL to specify Node-1 as the bootnode in the following steps. + +![Node 1 Enode URL](../../assets/images/EnodeStartup.png) + +### 5. Start Node-2 + +Start another terminal, change to the `Node-2` directory and start Node-2 specifying the Node-1 enode URL copied when starting Node-1 as the bootnode: + + + +# MacOS + +```bash +besu --data-path=data --genesis-file=../cliqueGenesis.json --bootnodes= --network-id 123 --p2p-port=30304 --rpc-http-enabled --rpc-http-api=ETH,NET,CLIQUE --host-allowlist="*" --rpc-http-cors-origins="all" --rpc-http-port=8546 +``` + +# Windows + +```bash +besu --data-path=data --genesis-file=..\cliqueGenesis.json --bootnodes= --network-id 123 --p2p-port=30304 --rpc-http-enabled --rpc-http-api=ETH,NET,CLIQUE --host-allowlist="*" --rpc-http-cors-origins="all" --rpc-http-port=8546 +``` + + + +The command line specifies: + +- A different port to Node-1 for P2P discovery using the [`--p2p-port`](../../public-networks/reference/cli/options.md#p2p-port) option. +- A different port to Node-1 for HTTP JSON-RPC using the [`--rpc-http-port`](../../public-networks/reference/cli/options.md#rpc-http-port) option. +- The enode URL of Node-1 using the [`--bootnodes`](../../public-networks/reference/cli/options.md#bootnodes) option. +- The data directory for Node-2 using the [`--data-path`](../../public-networks/reference/cli/options.md#data-path) option. +- Other options as for [Node-1](#4-start-the-first-node-as-the-bootnode). + +### 6. Start Node-3 + +Start another terminal, change to the `Node-3` directory and start Node-3 specifying the Node-1 enode URL copied when starting Node-1 as the bootnode: + + + +# MacOS + +```bash +besu --data-path=data --genesis-file=../cliqueGenesis.json --bootnodes= --network-id 123 --p2p-port=30305 --rpc-http-enabled --rpc-http-api=ETH,NET,CLIQUE --host-allowlist="*" --rpc-http-cors-origins="all" --rpc-http-port=8547 +``` + +# Windows + +```bash +besu --data-path=data --genesis-file=..\cliqueGenesis.json --bootnodes= --network-id 123 --p2p-port=30305 --rpc-http-enabled --rpc-http-api=ETH,NET,CLIQUE --host-allowlist="*" --rpc-http-cors-origins="all" --rpc-http-port=8547 +``` + + + +The command line specifies: + +- A different port to Node-1 and Node-2 for P2P discovery using the [`--p2p-port`](../../public-networks/reference/cli/options.md#p2p-port) option. +- A different port to Node-1 and Node-2 for HTTP JSON-RPC using the [`--rpc-http-port`](../../public-networks/reference/cli/options.md#rpc-http-port) option. +- The data directory for Node-3 using the [`--data-path`](../../public-networks/reference/cli/options.md#data-path) option. +- The bootnode as for [Node-2](#5-start-node-2). +- Other options as for [Node-1](#4-start-the-first-node-as-the-bootnode). + +### 7. Confirm the private network is working + +Start another terminal, use curl to call the JSON-RPC API [`net_peerCount`](../../public-networks/reference/api/index.md#net_peercount) method and confirm the nodes are functioning as peers: + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"net_peerCount","params":[],"id":1}' localhost:8545 +``` + +The result confirms Node-1 has two peers (Node-2 and Node-3): + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": "0x2" +} +``` + +## Next steps + +Look at the logs displayed to confirm Node-1 is producing blocks and Node-2 and Node-3 are importing blocks. + +Use the [Clique API to add] Node-2 or Node-3 as a signer. + +:::note + +To add Node-2 or Node-3 as a signer you need the [node address as when specifying Node-1](#2-get-the-address-for-node-1) as the initial signer. + +::: + +Import accounts to MetaMask and send transactions, as described in the [Quickstart tutorial](quickstart.md#create-a-transaction-using-metamask). + +:::info + +Besu doesn't support [private key management](../../public-networks/how-to/send-transactions.md). + +::: + +## Stop the nodes + +When finished using the private network, stop all nodes using ++ctrl+c++ in each terminal window. + +:::tip + +To restart the Clique network in the future, start from [4. Start First Node as Bootnode](#4-start-the-first-node-as-the-bootnode). + +::: + + + +[Clique (proof of authority) consensus protocol]: ../how-to/configure/consensus/clique.md +[Clique API to add]: ../how-to/configure/consensus/clique.md#add-and-remove-signers diff --git a/versioned_docs/version-23.10.1/private-networks/tutorials/contracts/_category_.json b/versioned_docs/version-23.10.1/private-networks/tutorials/contracts/_category_.json new file mode 100644 index 00000000000..3ba8177fcc1 --- /dev/null +++ b/versioned_docs/version-23.10.1/private-networks/tutorials/contracts/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Deploy a smart contract", + "position": 8 +} diff --git a/versioned_docs/version-23.10.1/private-networks/tutorials/contracts/index.md b/versioned_docs/version-23.10.1/private-networks/tutorials/contracts/index.md new file mode 100644 index 00000000000..56de7beebe9 --- /dev/null +++ b/versioned_docs/version-23.10.1/private-networks/tutorials/contracts/index.md @@ -0,0 +1,275 @@ +--- +title: Deploy a smart contract +sidebar_position: 1 +description: deploying smart contracts +tags: + - private networks +--- + +# Deploy smart contracts to an Ethereum chain + +This tutorial shows you how to deploy smart contracts as transactions to a network. + +## Prerequisites + +This tutorial requires a local blockchain network. You can use the [Developer Quickstart](../quickstart.md) to rapidly generate one. If deploying a private contract, enable privacy on the network (public contracts can also be deployed on privacy-enabled networks). + +## Use `eth_sendSignedTransaction` + +To deploy a smart contract using [`eth_sendSignedTransaction`](https://web3js.readthedocs.io/en/v1.2.0/web3-eth.html#sendsignedtransaction), use an account's private key to sign and serialize the transaction, and send the API request. + +This example uses the [web3js](https://www.npmjs.com/package/web3) library to make the API calls. + +Using the [`SimpleStorage.sol`](https://github.com/ConsenSys/quorum-dev-quickstart/blob/1e8cc281098923802845cd829ec20c88513c2e1c/files/common/smart_contracts/privacy/contracts/SimpleStorage.sol) smart contract as an example, create a new file called `compile.js` with the following content: + +```js title="compile.js" +const fs = require("fs").promises; +const solc = require("solc"); + +async function main() { + // Load the contract source code + const sourceCode = await fs.readFile("SimpleStorage.sol", "utf8"); + // Compile the source code and retrieve the ABI and bytecode + const { abi, bytecode } = compile(sourceCode, "SimpleStorage"); + // Store the ABI and bytecode into a JSON file + const artifact = JSON.stringify({ abi, bytecode }, null, 2); + await fs.writeFile("SimpleStorage.json", artifact); +} + +function compile(sourceCode, contractName) { + // Create the Solidity Compiler Standard Input and Output JSON + const input = { + language: "Solidity", + sources: { main: { content: sourceCode } }, + settings: { outputSelection: { "*": { "*": ["abi", "evm.bytecode"] } } }, + }; + // Parse the compiler output to retrieve the ABI and bytecode + const output = solc.compile(JSON.stringify(input)); + const artifact = JSON.parse(output).contracts.main[contractName]; + return { + abi: artifact.abi, + bytecode: artifact.evm.bytecode.object, + }; +} + +main().then(() => process.exit(0)); +``` + +Run `compile.js` to get the smart contract's output JSON: + +```bash +node compile.js +``` + +Run `solc` to get the contract's bytecode and ABI: + +```bash +solc SimpleStorage.sol --bin --abi +``` + +Once you have the bytecode and ABI, you can rename the output files to make them easier to use; this tutorial refers to them as `SimpleStorage.bin` and `SimpleStorage.abi`. + +Create a new file named `public_tx.js` to send the transaction (or run the following commands in a JavaScript console). The Developer Quickstart provides an [example of a public transaction script](https://github.com/ConsenSys/quorum-dev-quickstart/blob/1e8cc281098923802845cd829ec20c88513c2e1c/files/besu/smart_contracts/privacy/scripts/public_tx.js). + +```js titl="public_tx.js" +const web3 = new Web3(host); +// use an existing account, or make an account +const privateKey = + "0x8f2a55949038a9610f50fb23b5883af3b4ecb3c3bb792cbcefbd1542c692be63"; +const account = web3.eth.accounts.privateKeyToAccount(privateKey); + +// read in the contracts +const contractJsonPath = path.resolve(__dirname, "SimpleStorage.json"); +const contractJson = JSON.parse(fs.readFileSync(contractJsonPath)); +const contractAbi = contractJson.abi; +const contractBinPath = path.resolve(__dirname, "SimpleStorage.bin"); +const contractBin = fs.readFileSync(contractBinPath); +// initialize the default constructor with a value `47 = 0x2F`; this value is appended to the bytecode +const contractConstructorInit = + "000000000000000000000000000000000000000000000000000000000000002F"; + +// get txnCount for the nonce value +const txnCount = await web3.eth.getTransactionCount(account.address); + +const rawTxOptions = { + nonce: web3.utils.numberToHex(txnCount), + from: account.address, + to: null, //public tx + value: "0x00", + data: "0x" + contractBin + contractConstructorInit, // contract binary appended with initialization value + gasPrice: "0x0", //ETH per unit of gas + gasLimit: "0x24A22", //max number of gas units the tx is allowed to use +}; +console.log("Creating transaction..."); +const tx = new Tx(rawTxOptions); +console.log("Signing transaction..."); +tx.sign(privateKey); +console.log("Sending transaction..."); +var serializedTx = tx.serialize(); +const pTx = await web3.eth.sendSignedTransaction( + "0x" + serializedTx.toString("hex").toString("hex"), +); +console.log("tx transactionHash: " + pTx.transactionHash); +console.log("tx contractAddress: " + pTx.contractAddress); +``` + +`rawTxOptions` contains the following fields: + +- `nonce` - the number of transactions sent from an address. +- `from` - address of the sending account. For example `0xfe3b557e8fb62b89f4916b721be55ceb828dbd73`. +- `to` - address of the receiver. To deploy a contract, set to `null`. +- `gas` - amount of gas provided by the sender for the transaction. +- `gasPrice` - price for each unit of gas the sender is willing to pay. +- `data` - binary of the contract (in this example there's also a constructor initialization value, so we append that to the binary value). +- `value` - amount of Ether/Wei transferred from the sender to the recipient. + +Run the `public_tx.js` to send the transaction: + +```bash +node public_tx.js +``` + +This example code creates the transaction `tx`, signs it with the private key of the account, serializes it, then calls `eth_sendSignedTransaction` to deploy the contract. + +## Use `eth_sendTransaction` + +You can use [`eth_sendTransaction`](https://ethereum.github.io/execution-apis/api-documentation) as an alternative to `eth_sendSignedTransaction`. However, Hyperledger Besu does not support the `eth_sendTransaction` API call and keeps account management separate for stronger security. Configure [EthSigner](https://docs.ethsigner.consensys.net/en/stable/) with your Besu node to make the `eth_sendTransaction` API call. + +An example can be found in the [Developer Quickstart](../quickstart.md) where the RPC node is paired with EthSigner. Refer to the [EthSigner documentation](https://docs.ethsigner.consensys.net/) for configuration details. + +Pass the following parameters to the [`eth_sendTransaction`](https://docs.ethsigner.consensys.net/Reference/API-Methods/#eth_sendtransaction) call to EthSigner; EthSigner then converts the request to an [`eth_sendRawTransaction`](../../../public-networks/reference/api/index.md#eth_sendrawtransaction) call that Besu uses: + +- `to` - address of the receiver. To deploy a contract, set to `null`. +- `from` - address of the sender account. For example `0x9b790656b9ec0db1936ed84b3bea605873558198`. +- `gas` - amount of gas provided by the sender for the transaction +- `gasPrice` - price for each unit of gas the sender is willing to pay +- `data` - one of the following: + - For contract deployments (this use case) - compiled code of the contract + - For contract interactions - hash of the invoked method signature and encoded parameters (see [Ethereum Contract ABI](https://solidity.readthedocs.io/en/develop/abi-spec.html)) + - For simple ether transfers - empty + +```json title="'eth_sendTransaction' parameters" +params: { + "to": null, + "from": "0x9b790656b9ec0db1936ed84b3bea605873558198", + "gas": "0x76c0", + "gasPrice": "0x9184e72a000", + "data": "0x608060405234801561001057600080fd5b5060405161014d38038061014d8339818101604052602081101561003357600080fd5b8101908080519060200190929190505050806000819055505060f38061005a6000396000f3fe6080604052348015600f57600080fd5b5060043610603c5760003560e01c80632a1afcd914604157806360fe47b114605d5780636d4ce63c146088575b600080fd5b604760a4565b6040518082815260200191505060405180910390f35b608660048036036020811015607157600080fd5b810190808035906020019092919050505060aa565b005b608e60b4565b6040518082815260200191505060405180910390f35b60005481565b8060008190555050565b6000805490509056fea2646970667358221220e6966e446bd0af8e6af40eb0d8f323dd02f771ba1f11ae05c65d1624ffb3c58264736f6c63430007060033" +} +``` + +Make the request using `eth_sendTransaction`: + +```bash title="'eth_sendTransaction' curl HTTP request" +curl -X POST --data '{"jsonrpc":"2.0","method":"eth_sendTransaction","params":[{"from":"0x9b790656b9ec0db1936ed84b3bea605873558198", "to":null, "gas":"0x7600","gasPrice":"0x9184e72a000", "data":"0x608060405234801561001057600080fd5b5060405161014d38038061014d8339818101604052602081101561003357600080fd5b8101908080519060200190929190505050806000819055505060f38061005a6000396000f3fe6080604052348015600f57600080fd5b5060043610603c5760003560e01c80632a1afcd914604157806360fe47b114605d5780636d4ce63c146088575b600080fd5b604760a4565b6040518082815260200191505060405180910390f35b608660048036036020811015607157600080fd5b810190808035906020019092919050505060aa565b005b608e60b4565b6040518082815260200191505060405180910390f35b60005481565b8060008190555050565b6000805490509056fea2646970667358221220e6966e446bd0af8e6af40eb0d8f323dd02f771ba1f11ae05c65d1624ffb3c58264736f6c63430007060033"}], "id":1}' +``` + +## Use `eea_sendRawTransaction` for private contracts with web3js-quorum + +To deploy a private contract to another node or [privacy group](../../concepts/privacy/privacy-groups.md) member, use the [web3js-quorum](https://www.npmjs.com/package/web3js-quorum) library and the [`eea_sendRawTransaction`](../../../public-networks/reference/api/index.md#eea_sendrawtransaction) API call. You must use this API call instead of [`eth_sendTransaction`](https://ethereum.github.io/execution-apis/api-documentation) because Hyperledger Besu keeps account management separate for stronger security. + +The Developer Quickstart provides an [example of a private transaction script](https://github.com/ConsenSys/quorum-dev-quickstart/blob/1e8cc281098923802845cd829ec20c88513c2e1c/files/besu/smart_contracts/privacy/scripts/private_tx.js). + +This example uses the [web3js](https://www.npmjs.com/package/web3) library to make the API calls. + +Use [`web3.priv.generateAndSendRawTransaction`](https://consensys.github.io/web3js-quorum/latest/module-priv.html#~generateAndSendRawTransaction) by running the following commands in a JavaScript console, or by including them in a `private_tx.js` file and running `node private_tx.js`: + +```js title="'private_tx.js' using 'web3.priv.generateAndSendRawTransaction'" +const Web3 = require("web3"); +const Web3Quorum = require("web3js-quorum"); + +const bytecode = + "608060405234801561001057600080fd5b5060405161014d38038061014d8339818101604052602081101561003357600080fd5b8101908080519060200190929190505050806000819055505060f38061005a6000396000f3fe6080604052348015600f57600080fd5b5060043610603c5760003560e01c80632a1afcd914604157806360fe47b114605d5780636d4ce63c146088575b600080fd5b604760a4565b6040518082815260200191505060405180910390f35b608660048036036020811015607157600080fd5b810190808035906020019092919050505060aa565b005b608e60b4565b6040518082815260200191505060405180910390f35b60005481565b8060008190555050565b6000805490509056fea2646970667358221220e6966e446bd0af8e6af40eb0d8f323dd02f771ba1f11ae05c65d1624ffb3c58264736f6c63430007060033"; +// initialize the default constructor with a value `47 = 0x2F`; this value is appended to the bytecode +const contractConstructorInit = + "000000000000000000000000000000000000000000000000000000000000002F"; + +const chainId = 1337; +const web3 = new Web3(clientUrl); +const web3quorum = new Web3Quorum(web3, chainId); + +const txOptions = { + data: "0x" + bytecode + contractConstructorInit, + privateKey: fromPrivateKey, + privateFrom: fromPublicKey, + privateFor: [toPublicKey], +}; +console.log("Creating contract..."); +const txHash = await web3quorum.priv.generateAndSendRawTransaction(txOptions); +console.log("Getting contractAddress from txHash: ", txHash); + +const privateTxReceipt = await web3quorum.priv.waitForTransactionReceipt( + txHash, +); +console.log("Private Transaction Receipt: ", privateTxReceipt); +return privateTxReceipt; +``` + +`txOptions` contains the following field: + +- `data` - compiled code of the contract (in this example there's also a constructor initialization value, so we append that to the bytecode). + +The deployment process includes creating the client as in the previous examples, but rather than deploying the contract with `to: null`, it instead sends the transaction with `privateFor: [memberPublicKey/s]`. Once you make the API call, you receive a `transactionHash`, which you can use to get a `transactionReceipt` containing the contract's address. + +:::note + +This example doesn't use a privacy group and makes a simple node-to-node transaction. To use a privacy group: + +- Create the privacy group using the public keys of the nodes in the group. +- Specify the `privacyGroupId` instead of the `privateFor` option in the txOptions above and then send the transaction. + +The Developer Quickstart provides an [example of a private transaction with a privacy group](https://github.com/ConsenSys/quorum-dev-quickstart/blob/b72a0f64d685c851bf8be399a8e33bbdf0e09982/files/besu/smart_contracts/privacy/scripts/private_tx_privacy_group.js). + +::: + +## Use `eea_sendRawTransaction` for private contracts with web3js-eea + +:::warning + +This web3js-eea library will be deprecated on December 31, 2021. Please use the [web3js-quorum](https://www.npmjs.com/package/web3js-quorum) library instead and refer to the previous section. + +::: + +To deploy a private contract to another [privacy group](../../concepts/privacy/privacy-groups.md) member, use the [web3js-quorum](https://consensys.github.io/web3js-quorum/latest/index.html) library and the [`eea_sendRawTransaction`](../../../public-networks/reference/api/index.md#eea_sendrawtransaction) API call. You must use this API call instead of [`eth_sendTransaction`](https://ethereum.github.io/execution-apis/api-documentation) because Hyperledger Besu keeps account management separate for stronger security. + +The Developer Quickstart provides an [example of a private transaction script](https://github.com/ConsenSys/quorum-dev-quickstart/blob/1e8cc281098923802845cd829ec20c88513c2e1c/files/besu/smart_contracts/privacy/scripts/private_tx.js). + +This example uses the [web3js](https://www.npmjs.com/package/web3) library to make the API calls. + +Use `eea_sendRawTransaction` by running the following commands in a JavaScript console, or by including them in a `private_tx.js` file and running `node private_tx.js`: + +```js title="'private_tx.js' using 'eea_sendRawTransaction'" +const Web3 = require("web3"); +const EEAClient = require("web3-eea"); + +const bytecode = + "608060405234801561001057600080fd5b5060405161014d38038061014d8339818101604052602081101561003357600080fd5b8101908080519060200190929190505050806000819055505060f38061005a6000396000f3fe6080604052348015600f57600080fd5b5060043610603c5760003560e01c80632a1afcd914604157806360fe47b114605d5780636d4ce63c146088575b600080fd5b604760a4565b6040518082815260200191505060405180910390f35b608660048036036020811015607157600080fd5b810190808035906020019092919050505060aa565b005b608e60b4565b6040518082815260200191505060405180910390f35b60005481565b8060008190555050565b6000805490509056fea2646970667358221220e6966e446bd0af8e6af40eb0d8f323dd02f771ba1f11ae05c65d1624ffb3c58264736f6c63430007060033"; +// initialize the default constructor with a value `47 = 0x2F`; this value is appended to the bytecode +const contractConstructorInit = + "000000000000000000000000000000000000000000000000000000000000002F"; + +const web3 = new Web3(clientUrl); +const web3eea = new EEAClient(web3, 1337); +const txOptions = { + data: "0x" + bytecode + contractConstructorInit, + privateKey: fromPrivateKey, + privateFrom: fromPublicKey, + privateFor: [toPublicKey], +}; +console.log("Creating contract..."); +const txHash = await web3eea.eea.sendRawTransaction(txOptions); +console.log("Getting contractAddress from txHash: ", txHash); + +const privateTxReceipt = await web3.priv.getTransactionReceipt( + txHash, + fromPublicKey, +); +// console.log("Private Transaction Receipt: ", privateTxReceipt); +return privateTxReceipt; +``` + +`txOptions` contains the following field: + +- `data` - compiled code of the contract (in this example there's also a constructor initialization value, so we append that to the bytecode). + +The deployment process includes creating the client as in the previous examples, but rather than deploying the contract with `to: null`, it instead sends the transaction with `privateFor: [memberPublicKey/s]`. Once you make the API call, you receive a `transactionHash`, which you can use to get a `transactionReceipt` containing the contract's address. diff --git a/versioned_docs/version-23.10.1/private-networks/tutorials/contracts/interact.md b/versioned_docs/version-23.10.1/private-networks/tutorials/contracts/interact.md new file mode 100644 index 00000000000..11da4b07e28 --- /dev/null +++ b/versioned_docs/version-23.10.1/private-networks/tutorials/contracts/interact.md @@ -0,0 +1,194 @@ +--- +title: Interact with a deployed contract +sidebar_position: 2 +description: calling smart contracts functions +tags: + - private networks +--- + +# Interact with deployed smart contracts + +You can get started with the [Developer Quickstart](../quickstart.md) to rapidly generate local blockchain networks. + +This tutorial shows you how to interact with smart contracts that have been deployed to a network. + +## Prerequisites + +- A network with a deployed smart contract as in the [deploying smart contracts tutorial](index.md) + +## Interact with public contracts + +This tutorial uses the [`SimpleStorage.sol`](https://github.com/ConsenSys/quorum-dev-quickstart/blob/1e8cc281098923802845cd829ec20c88513c2e1c/files/common/smart_contracts/privacy/contracts/SimpleStorage.sol) contract: + +```js +pragma solidity ^0.7.0; + +contract SimpleStorage { + uint public storedData; + + constructor(uint initVal) public { + storedData = initVal; + } + + function set(uint x) public { + storedData = x; + } + + function get() view public returns (uint retVal) { + return storedData; + } +} +``` + +Once the contract is deployed, you can perform a read operation using the `get` function call and a write operation using the `set` function call. This tutorial uses the [web3js](https://www.npmjs.com/package/web3) library to interact with the contract. A [full example](https://github.com/ConsenSys/quorum-dev-quickstart/blob/1e8cc281098923802845cd829ec20c88513c2e1c/files/besu/smart_contracts/privacy/scripts/public_tx.js) of these calls can be found in the [Developer Quickstart]. + +### 1. Perform a read operation + +To perform a read operation, you need the address that the contract was deployed to and the contract's ABI. The contract's ABI can be obtained from compiling the contract; see the [deploying smart contracts tutorial](index.md) for an example. + +Use the [`web3.eth.Contract`](https://web3js.readthedocs.io/en/v1.3.4/web3-eth-contract.html) object to create a new instance of the smart contract, then make the `get` function call from the contract's list of methods, which will return the value stored: + +```js +async function getValueAtAddress( + host, + deployedContractAbi, + deployedContractAddress, +) { + const web3 = new Web3(host); + const contractInstance = new web3.eth.Contract( + deployedContractAbi, + deployedContractAddress, + ); + const res = await contractInstance.methods.get().call(); + console.log("Obtained value at deployed contract is: " + res); + return res; +} +``` + +### 2. Perform a write operation + +To perform a write operation, send a transaction to update the stored value. As with the [`get` call](#1-perform-a-read-operation), you need to use the address that the contract was deployed to and the contract's ABI. The account address must correspond to an actual account with some ETH in it to perform the transaction. Because Besu doesn't manage accounts, this address is the address you use in [EthSigner](https://docs.ethsigner.consensys.net/en/stable/) (or equivalent) to manage your accounts. + +Make the `set` call passing in your account address, `value` as the updated value of the contract, and the amount of gas you are willing to spend for the transaction: + +```js +// You need to use the accountAddress details provided to Besu to send/interact with contracts +async function setValueAtAddress( + host, + accountAddress, + value, + deployedContractAbi, + deployedContractAddress, +) { + const web3 = new Web3(host); + const contractInstance = new web3.eth.Contract( + deployedContractAbi, + deployedContractAddress, + ); + const res = await contractInstance.methods + .set(value) + .send({ from: accountAddress, gasPrice: "0xFF", gasLimit: "0x24A22" }); + return res; +} +``` + +### 3. Verify an updated value + +To verify that a value has been updated, perform a `get` call after a `set` update call. + +## Interact with private contracts + +This private contracts example uses the same `SimpleStorage.sol` contract as in the [public contracts example](#interact-with-public-contracts), but it uses the [web3js-quorum](https://consensys.github.io/web3js-quorum/latest/index.html) library and the [`generateAndSendRawTransaction`](https://consensys.github.io/web3js-quorum/latest/module-priv.html#~generateAndSendRawTransaction) method to interact with the contract. Both read and write operations are performed using the `generateAndSendRawTransaction` API call. A [full example](https://github.com/ConsenSys/quorum-dev-quickstart/blob/1e8cc281098923802845cd829ec20c88513c2e1c/files/besu/smart_contracts/privacy/scripts/private_tx.js) can be found in the [Developer Quickstart]. + +### 1. Perform a read operation + +As in the public contracts example, to perform a read operation, you need the address that the contract was deployed to and the contract's ABI. You also need your private and public keys and the recipient's public key. + +Use the [`web3.eth.Contract`](https://web3js.readthedocs.io/en/v1.3.4/web3-eth-contract.html) object to create a new instance of the smart contract, extract the signature of function's ABI for the `get` method, and then use this value as the `data` parameter for the `generateAndSendRawTransaction` transaction. + +The keys remain the same for the sender and recipient, and the `to` field is the contract's address. Once you make the request, you receive a `transactionHash`, which you can use to get a `transactionReceipt` containing the value stored: + +```js +async function getValueAtAddress( + clientUrl, + address, + contractAbi, + fromPrivateKey, + fromPublicKey, + toPublicKey, +) { + const Web3 = require("web3"); + const Web3Quorum = require("web3js-quorum"); + const web3 = new Web3Quorum(new Web3("http://localhost:22000")); + // eslint-disable-next-line no-underscore-dangle + const functionAbi = contract._jsonInterface.find((e) => { + return e.name === "get"; + }); + const functionParams = { + to: address, + data: functionAbi.signature, + privateKey: fromPrivateKey, + privateFrom: fromPublicKey, + privateFor: [toPublicKey], + }; + const transactionHash = await web3quorum.priv.generateAndSendRawTransaction( + functionParams, + ); + // console.log(`Transaction hash: ${transactionHash}`); + const result = await web3quorum.priv.waitForTransactionReceipt( + transactionHash, + ); + console.log( + "" + nodeName + " value from deployed contract is: " + result.output, + ); + return result; +} +``` + +### 2. Perform a write operation + +Performing a write operation is almost the same process as the read operation, except that you encode the new value to the `set` function's ABI, and then append these arguments to the `set` function's ABI and use this as the `data` field: + +```js +async function setValueAtAddress( + clientUrl, + address, + value, + contractAbi, + fromPrivateKey, + fromPublicKey, + toPublicKey, +) { + const Web3 = require("web3"); + const Web3Quorum = require("web3js-quorum"); + const web3 = new Web3Quorum(new Web3("http://localhost:22000")); + // eslint-disable-next-line no-underscore-dangle + const functionAbi = contract._jsonInterface.find((e) => { + return e.name === "set"; + }); + const functionArgs = web3quorum.eth.abi + .encodeParameters(functionAbi.inputs, [value]) + .slice(2); + const functionParams = { + to: address, + data: functionAbi.signature + functionArgs, + privateKey: fromPrivateKey, + privateFrom: fromPublicKey, + privateFor: [toPublicKey], + }; + const transactionHash = await web3quorum.priv.generateAndSendRawTransaction( + functionParams, + ); + console.log(`Transaction hash: ${transactionHash}`); + const result = await web3quorum.priv.waitForTransactionReceipt( + transactionHash, + ); + return result; +} +``` + +### 3. Verify an updated value + +To verify that a value has been updated, perform a `get` call after a `set` update call. + +[Developer Quickstart]: ../quickstart.md diff --git a/versioned_docs/version-23.10.1/private-networks/tutorials/contracts/transfer-funds.md b/versioned_docs/version-23.10.1/private-networks/tutorials/contracts/transfer-funds.md new file mode 100644 index 00000000000..d2ae16ca8f4 --- /dev/null +++ b/versioned_docs/version-23.10.1/private-networks/tutorials/contracts/transfer-funds.md @@ -0,0 +1,128 @@ +--- +title: Transfer account funds +sidebar_position: 1 +description: funds transfer transactions +tags: + - private networks +--- + +# Transfer funds between accounts in a transaction + +You can get started with the [Developer Quickstart](../quickstart.md) to rapidly generate local blockchain networks. + +This tutorial shows you how to transfer funds (ETH) between accounts in a transaction. + +## Prerequisites + +- A [private network](../quickstart.md) + +## Use `eth_sendSignedTransaction` + +The simplest way to transfer funds between externally-owned accounts is using [`eth_sendSignedTransaction`](https://web3js.readthedocs.io/en/v1.2.11/web3-eth.html#sendsignedtransaction). This example uses `eth_sendSignedTransaction` and one of the [test accounts](../../reference/accounts-for-testing.md) to transfer funds to a newly created account. + +:::danger Do not use the test accounts on Ethereum Mainnet or any production network + +The private key is publicly displayed, which means the account is not secure. + +::: + +Before making the transaction, check the balances of both accounts to verify the funds transfer after the transaction. + +```js +const web3 = new Web3(host); +// Pre-seeded account with 90000 ETH +const privateKeyA = + "0xc87509a1c067bbde78beb793e6fa76530b6382a4c0241e5e4a9ec0a0f44dc0d3"; +const accountA = web3.eth.accounts.privateKeyToAccount(privateKeyA); +var accountABalance = web3.utils.fromWei( + await web3.eth.getBalance(accountA.address), +); +console.log("Account A has balance of: " + accountABalance); + +// Create a new account to transfer ETH to +var accountB = web3.eth.accounts.create(); +var accountBBalance = web3.utils.fromWei( + await web3.eth.getBalance(accountB.address), +); +console.log("Account B has balance of: " + accountBBalance); +``` + +Use the test account address (Account A) for the `from` parameter, the recipient account address (Account B) for the `to` parameter, and the amount of ETH to transfer between accounts for the `value` parameter. Sign the transaction with Account A's private key and send it using `eth_sendSignedTransaction`. + +```js +// Send some ETH from A to B +const rawTxOptions = { + nonce: web3.utils.numberToHex( + await web3.eth.getTransactionCount(accountA.address), + ), + from: accountA.address, + to: accountB.address, + value: "0x100", // Amount of ETH to transfer + gasPrice: "0x0", // ETH per unit of gas + gasLimit: "0x24A22", // Max number of gas units the tx is allowed to use +}; +console.log("Creating transaction..."); +const tx = new Tx(rawTxOptions); +console.log("Signing transaction..."); +tx.sign(Buffer.from(accountA.privateKey.substring(2), "hex")); +console.log("Sending transaction..."); +var serializedTx = tx.serialize(); +const pTx = await web3.eth.sendSignedTransaction( + "0x" + serializedTx.toString("hex").toString("hex"), +); +console.log("tx transactionHash: " + pTx.transactionHash); +``` + +Once it completes, you can see the updated balances. + +```js +// After the transaction, there should be some ETH transferred +var accountABalance = await getAccountBalance(host, accountA); +console.log("Account A has an updated balance of: " + accountABalance); +var accountBBalance = await getAccountBalance(host, accountB); +console.log("Account B has an updatedbalance of: " + accountBBalance); +} +``` + +A [full example](https://github.com/ConsenSys/quorum-dev-quickstart/blob/1e8cc281098923802845cd829ec20c88513c2e1c/files/besu/smart_contracts/privacy/scripts/eth_tx.js) can be found in the Developer Quickstart. + +## Use `eth_sendTransaction` + +An alternative to using `eth_sendSignedTransaction` is [`eth_sendTransaction`](https://web3js.readthedocs.io/en/v1.2.11/web3-eth.html#sendtransaction). However, Hyperledger Besu does not support the `eth_sendTransaction` API call and keeps account management separate for stronger security. Instead, Besu uses [EthSigner](https://docs.ethsigner.consensys.net/en/stable/) to make the `eth_sendTransaction` API call. + +An example can be found in the [Developer Quickstart](../quickstart.md) where the RPC node is paired with EthSigner. Refer to the [EthSigner documentation](https://docs.ethsigner.consensys.net/en/stable/) configuration details. + +Use `eth_sendTransaction` similarly to [using `eth_sendSignedTransaction`](#use-eth_sendsignedtransaction) (without the signing step which is done by EthSigner): + +```js +const web3 = new Web3(host); +// Pre-seeded account with 90000 ETH +const privateKeyA = "0xc87509a1c067bbde78beb793e6fa76530b6382a4c0241e5e4a9ec0a0f44dc0d3"; +const accountA = web3.eth.accounts.privateKeyToAccount(privateKeyA); +var accountABalance = web3.utils.fromWei(await web3.eth.getBalance(accountA.address)); +console.log("Account A has balance of: " + accountABalance); + +// Create a new account to transfer ETH to +var accountB = web3.eth.accounts.create(); +var accountBBalance = web3.utils.fromWei(await web3.eth.getBalance(accountB.address)); +console.log("Account B has balance of: " + accountBBalance); + +// Send some ETH from A to B +const txOptions = { + from: accountA.address, + to: accountB.address, + value: "0x100", // Amount of ETH to transfer + gasPrice: "0x0", // ETH per unit of gas + gasLimit: "0x24A22" // Max number of gas units the tx is allowed to use +}; +console.log("Creating transaction..."); +const pTx = await web3.eth.sendTransaction(txOptions); +console.log("tx transactionHash: " + pTx.transactionHash); + +// After the transaction, there should be some ETH transferred +var accountABalance = await getAccountBalance(host, accountA); +console.log("Account A has an updated balance of: " + accountABalance); +var accountBBalance = await getAccountBalance(host, accountB); +console.log("Account B has an updatedbalance of: " + accountBBalance); +} +``` diff --git a/versioned_docs/version-23.10.1/private-networks/tutorials/ethash.md b/versioned_docs/version-23.10.1/private-networks/tutorials/ethash.md new file mode 100644 index 00000000000..ea464438383 --- /dev/null +++ b/versioned_docs/version-23.10.1/private-networks/tutorials/ethash.md @@ -0,0 +1,225 @@ +--- +title: Create an Ethash network +sidebar_position: 5 +description: Create a private network using the Ethash consensus protocol. +tags: + - private networks +--- + +# Create a private network using Ethash + +A private network provides a configurable network for testing. By configuring a low difficulty and enabling mining, this allows for fast block creation. + +You can test multi-block and multi-user scenarios on a private network before moving to one of the public testnets. + +:::danger + +The steps in this tutorial create an isolated, but not protected or secure, Ethereum private network. We recommend running the private network behind a properly configured firewall. + +::: + +## Prerequisites + +- [Hyperledger Besu](../get-started/install/binary-distribution.md) +- [Curl (or similar webservice client)](https://curl.haxx.se/download.html). + +## Steps + +Listed on the right-hand side of the page are the steps to create a private network using Ethash. + +### 1. Create directories + +Each node requires a data directory for the blockchain data. When the node starts, Besu saves the [node key](../../public-networks/concepts/node-keys.md) in this directory. + +Create directories for your private network, each of the three nodes, and a data directory for each node: + +```bash +Private-Network/ +├── Node-1 +│   ├── data +├── Node-2 +│   ├── data +└── Node-3 + ├── data +``` + +### 2. Create a genesis file + +The genesis file defines the genesis block of the blockchain (that is, the start of the blockchain). The genesis file includes entries for configuring the blockchain, such as the mining difficulty and initial accounts and balances. + +All nodes in a network must use the same genesis file. The [network ID](../../public-networks/concepts/network-and-chain-id.md) defaults to the `chainID` in the genesis file. The `fixeddifficulty` enables fast block mining. + +Copy the following genesis definition to a file called `privateNetworkGenesis.json` and save it in the `Private-Network` directory: + +```json +{ + "config": { + "berlinBlock": 0, + "ethash": { + "fixeddifficulty": 1000 + }, + "chainID": 1337 + }, + "nonce": "0x42", + "gasLimit": "0x1000000", + "difficulty": "0x10000", + "alloc": { + "fe3b557e8fb62b89f4916b721be55ceb828dbd73": { + "privateKey": "8f2a55949038a9610f50fb23b5883af3b4ecb3c3bb792cbcefbd1542c692be63", + "comment": "private key and this comment are ignored. In a real chain, the private key should NOT be stored", + "balance": "0xad78ebc5ac6200000" + }, + "f17f52151EbEF6C7334FAD080c5704D77216b732": { + "privateKey": "ae6ae8e5ccbfb04590405997ee2d52d2b330726137b875053c36d94e974d162f", + "comment": "private key and this comment are ignored. In a real chain, the private key should NOT be stored", + "balance": "90000000000000000000000" + } + } +} +``` + +:::note + +We recommend specifying the latest [milestone](../../public-networks/reference/genesis-items.md#milestone-blocks) when creating the genesis file for a private network. This ensures you are using the most up-to-date protocol and have access to the most recent opcodes. + +::: + +:::warning + +Don't use the accounts in `alloc` in the genesis file on Mainnet or any public network except for testing. The private keys display, which means the accounts are not secure. + +::: + +### 3. Start the first node as a bootnode + +Start Node-1: + + + +# MacOS + +```bash +besu --data-path=data --genesis-file=../privateNetworkGenesis.json --miner-enabled --miner-coinbase fe3b557e8fb62b89f4916b721be55ceb828dbd73 --rpc-http-enabled --host-allowlist="*" --rpc-http-cors-origins="all" +``` + +# Windows + +```bash +besu --data-path=data --genesis-file=..\privateNetworkGenesis.json --miner-enabled --miner-coinbase fe3b557e8fb62b89f4916b721be55ceb828dbd73 --rpc-http-enabled --host-allowlist="*" --rpc-http-cors-origins="all" +``` + + + +The command line enables: + +- Mining and specifies the account to pay mining rewards to using the [`--miner-enabled`](../../public-networks/reference/cli/options.md#miner-enabled) and [`--miner-coinbase`](../../public-networks/reference/cli/options.md#miner-coinbase) options. +- JSON-RPC API using the [`--rpc-http-enabled`](../../public-networks/reference/cli/options.md#rpc-http-enabled) option. +- All-host access to the HTTP JSON-RPC API using the [`--host-allowlist`](../../public-networks/reference/cli/options.md#host-allowlist) option. +- All-domain access to the node through the HTTP JSON-RPC API using the [`--rpc-http-cors-origins`](../../public-networks/reference/cli/options.md#rpc-http-cors-origins) option. + +:::info + +The miner coinbase account is one of the accounts defined in the genesis file. + +::: + +When the node starts, the [enode URL](../../public-networks/concepts/node-keys.md#enode-url) displays. Copy the enode URL to specify Node-1 as the bootnode in the following steps. + +![Node 1 Enode URL](../../assets/images/EnodeStartup.png) + +### 4. Start Node-2 + +Start another terminal, change to the `Node-2` directory and start Node-2 specifying the Node-1 enode URL copied when starting Node-1 as the bootnode: + + + +# MacOS + +```bash +besu --data-path=data --genesis-file=../privateNetworkGenesis.json --bootnodes= --p2p-port=30304 +``` + +# Windows + +```bash +besu --data-path=data --genesis-file=..\privateNetworkGenesis.json --bootnodes= --p2p-port=30304 +``` + + + +The command line specifies: + +- A different port to Node-1 for P2P discovery using the [`--p2p-port`](../../public-networks/reference/cli/options.md#p2p-port) option. +- The enode URL of Node-1 using the [`--bootnodes`](../../public-networks/reference/cli/options.md#bootnodes) option. +- A data directory for Node-2 using the [`--data-path`](../../public-networks/reference/cli/options.md#data-path) option. +- A genesis file as for Node-1. + +### 5. Start Node-3 + +Start another terminal, change to the `Node-3` directory and start Node-3 specifying the Node-1 enode URL copied when starting Node-1 as the bootnode: + + + +# MacOS + +```bash +besu --data-path=data --genesis-file=../privateNetworkGenesis.json --bootnodes= --p2p-port=30305 +``` + +# Windows + +```bash +besu --data-path=data --genesis-file=..\privateNetworkGenesis.json --bootnodes= --p2p-port=30305 +``` + + + +The command line specifies: + +- A different port to Node-1 and Node-2 for P2P discovery. +- A data directory for Node-3 using the [`--data-path`](../../public-networks/reference/cli/options.md#data-path) option. +- A bootnode and genesis file as for Node-2. + +### 6. Confirm the private network is working + +Start another terminal, use curl to call the JSON-RPC API [`net_peerCount`](../../public-networks/reference/api/index.md#net_peercount) method and confirm the nodes are functioning as peers: + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"net_peerCount","params":[],"id":1}' localhost:8545 +``` + +The result confirms Node-1 (the node running the JSON-RPC service) has two peers (Node-2 and Node-3): + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": "0x2" +} +``` + +## Next steps + +Import accounts to MetaMask and send transactions as described in the [Quickstart tutorial](quickstart.md#create-a-transaction-using-metamask). + +:::info + +Besu doesn't support [private key management](../../public-networks/how-to/send-transactions.md). + +::: + +Send transactions using `eth_sendRawTransaction` to [send ether or, deploy or invoke contracts](../how-to/send-transactions/index.md). + +Use the [JSON-RPC API](../../public-networks/how-to/use-besu-api/json-rpc.md). + +Start a node with the [`--rpc-ws-enabled`](../../public-networks/reference/cli/options.md#rpc-ws-enabled) option and use the [RPC Pub/Sub API](../../public-networks/how-to/use-besu-api/rpc-pubsub.md). + +## Stop the nodes + +When finished using the private network, stop all nodes using ++ctrl+c++ in each terminal window. + +:::tip + +To restart the private network in the future, start from [3. Start the first node as a bootnode](#3-start-the-first-node-as-a-bootnode). + +::: diff --git a/versioned_docs/version-23.10.1/private-networks/tutorials/ibft/_category_.json b/versioned_docs/version-23.10.1/private-networks/tutorials/ibft/_category_.json new file mode 100644 index 00000000000..c90421ed03c --- /dev/null +++ b/versioned_docs/version-23.10.1/private-networks/tutorials/ibft/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Create an IBFT 2.0 network", + "position": 3 +} diff --git a/versioned_docs/version-23.10.1/private-networks/tutorials/ibft/index.md b/versioned_docs/version-23.10.1/private-networks/tutorials/ibft/index.md new file mode 100644 index 00000000000..92df0a3f9ae --- /dev/null +++ b/versioned_docs/version-23.10.1/private-networks/tutorials/ibft/index.md @@ -0,0 +1,376 @@ +--- +description: Hyperledger Besu private network using the IBFT 2.0 (Proof of Authority) consensus protocol +tags: + - private networks +--- + +# Create a private network using IBFT 2.0 + +A private network provides a configurable network for testing. This private network uses the [IBFT 2.0 (proof of authority) consensus protocol](../../how-to/configure/consensus/ibft.md). + +:::danger + +The steps in this tutorial create an isolated, but not protected or secure, Ethereum private network. We recommend running the private network behind a properly configured firewall. + +This tutorial configures a private network using IBFT 2.0 for educational purposes only. IBFT 2.0 requires 4 validators to be Byzantine fault tolerant. + +::: + +## Prerequisites + +- [Hyperledger Besu](../../get-started/install/binary-distribution.md) +- [Curl (or similar webservice client)](https://curl.haxx.se/download.html). + +## Steps + +Listed on the right-hand side of the page are the steps to create a private network using IBFT 2.0 with four nodes. The four nodes are all validators. + +### 1. Create directories + +Each node requires a data directory for the blockchain data. + +Create directories for your private network, each of the four nodes, and a data directory for each node: + +```bash +IBFT-Network/ +├── Node-1 +│   ├── data +├── Node-2 +│   ├── data +├── Node-3 +│   ├── data +└── Node-4 + ├── data +``` + +### 2. Create a configuration file + +The configuration file defines the [IBFT 2.0 genesis file](../../how-to/configure/consensus/ibft.md#genesis-file) and the number of node key pairs to generate. + +The configuration file has two nested JSON nodes. The first is the `genesis` property defining the IBFT 2.0 genesis file, except for the `extraData` string, which Besu generates automatically in the resulting genesis file. The second is the `blockchain` property defining the number of key pairs to generate. + +Copy the following configuration file definition to a file called `ibftConfigFile.json` and save it in the `IBFT-Network` directory: + +```json +{ + "genesis": { + "config": { + "chainId": 1337, + "berlinBlock": 0, + "ibft2": { + "blockperiodseconds": 2, + "epochlength": 30000, + "requesttimeoutseconds": 4 + } + }, + "nonce": "0x0", + "timestamp": "0x58ee40ba", + "gasLimit": "0x47b760", + "difficulty": "0x1", + "mixHash": "0x63746963616c2062797a616e74696e65206661756c7420746f6c6572616e6365", + "coinbase": "0x0000000000000000000000000000000000000000", + "alloc": { + "fe3b557e8fb62b89f4916b721be55ceb828dbd73": { + "privateKey": "8f2a55949038a9610f50fb23b5883af3b4ecb3c3bb792cbcefbd1542c692be63", + "comment": "private key and this comment are ignored. In a real chain, the private key should NOT be stored", + "balance": "0xad78ebc5ac6200000" + }, + "627306090abaB3A6e1400e9345bC60c78a8BEf57": { + "privateKey": "c87509a1c067bbde78beb793e6fa76530b6382a4c0241e5e4a9ec0a0f44dc0d3", + "comment": "private key and this comment are ignored. In a real chain, the private key should NOT be stored", + "balance": "90000000000000000000000" + }, + "f17f52151EbEF6C7334FAD080c5704D77216b732": { + "privateKey": "ae6ae8e5ccbfb04590405997ee2d52d2b330726137b875053c36d94e974d162f", + "comment": "private key and this comment are ignored. In a real chain, the private key should NOT be stored", + "balance": "90000000000000000000000" + } + } + }, + "blockchain": { + "nodes": { + "generate": true, + "count": 4 + } + } +} +``` + +:::note + +We recommend specifying the latest [milestone](../../../public-networks/reference/genesis-items.md#milestone-blocks) when creating the configuration file for a private network. This ensures you are using the most up-to-date protocol and have access to the most recent opcodes. + +::: + +:::warning + +Do not use the accounts in `alloc` in the genesis file on Mainnet or any public network except for testing. The private keys display, which means the accounts are not secure. + +::: + +### 3. Generate node keys and a genesis file + +In the `IBFT-Network` directory, generate the node key and genesis file: + +```bash +besu operator generate-blockchain-config --config-file=ibftConfigFile.json --to=networkFiles --private-key-file-name=key +``` + +Besu creates the following in the `networkFiles` directory: + +- `genesis.json` - The genesis file including the `extraData` property specifying the four nodes are validators. +- A directory for each node named using the node address and containing the public and private key for each node. + +```bash +networkFiles/ +├── genesis.json +└── keys + ├── 0x438821c42b812fecdcea7fe8235806a412712fc0 + │   ├── key + │   └── key.pub + ├── 0xca9c2dfa62f4589827c0dd7dcf48259aa29f22f5 + │   ├── key + │   └── key.pub + ├── 0xcd5629bd37155608a0c9b28c4fd19310d53b3184 + │   ├── key + │   └── key.pub + └── 0xe96825c5ab8d145b9eeca1aba7ea3695e034911a + ├── key + └── key.pub +``` + +### 4. Copy the genesis file to the IBFT-Network directory + +Copy the `genesis.json` file to the `IBFT-Network` directory. + +### 5. Copy the node private keys to the node directories + +For each node, copy the key files to the `data` directory for that node + +```bash +IBFT-Network/ +├── genesis.json +├── Node-1 +│   ├── data +│ │    ├── key +│ │    ├── key.pub +├── Node-2 +│   ├── data +│ │    ├── key +│ │    ├── key.pub +├── Node-3 +│   ├── data +│ │    ├── key +│ │    ├── key.pub +├── Node-4 +│ ├── data +│ │    ├── key +│ │    ├── key.pub +``` + +### 6. Start the first node as the bootnode + +In the `Node-1` directory, start Node-1: + + + +# MacOS + +```bash +besu --data-path=data --genesis-file=../genesis.json --rpc-http-enabled --rpc-http-api=ETH,NET,IBFT --host-allowlist="*" --rpc-http-cors-origins="all" +``` + +# Windows + +```bash +besu --data-path=data --genesis-file=../genesis.json --rpc-http-enabled --rpc-http-api=ETH,NET,IBFT --host-allowlist="*" --rpc-http-cors-origins="all" +``` + + + +The command line: + +- Specifies the data directory for Node-1 using the [`--data-path`](../../../public-networks/reference/cli/options.md#data-path) option. +- Enables the JSON-RPC API using the [`--rpc-http-enabled`](../../../public-networks/reference/cli/options.md#rpc-http-enabled) option. +- Enables the ETH, NET, and IBFT APIs using the [`--rpc-http-api`](../../../public-networks/reference/cli/options.md#rpc-http-api) option. +- Enables all-host access to the HTTP JSON-RPC API using the [`--host-allowlist`](../../../public-networks/reference/cli/options.md#host-allowlist) option. +- Enables all-domain access to the node through the HTTP JSON-RPC API using the [`--rpc-http-cors-origins`](../../../public-networks/reference/cli/options.md#rpc-http-cors-origins) option. + +When the node starts, the [enode URL](../../../public-networks/concepts/node-keys.md#enode-url) displays. Copy the enode URL to specify Node-1 as the bootnode in the following steps. + +![Node 1 Enode URL](../../../assets/images/EnodeStartup.png) + +### 7. Start Node-2 + +Start another terminal, change to the `Node-2` directory and start Node-2 specifying the Node-1 enode URL copied when starting Node-1 as the bootnode: + + + +# MacOS + +```bash +besu --data-path=data --genesis-file=../genesis.json --bootnodes= --p2p-port=30304 --rpc-http-enabled --rpc-http-api=ETH,NET,IBFT --host-allowlist="*" --rpc-http-cors-origins="all" --rpc-http-port=8546 +``` + +# Windows + +```bash +besu --data-path=data --genesis-file=../genesis.json --bootnodes= --p2p-port=30304 --rpc-http-enabled --rpc-http-api=ETH,NET,IBFT --host-allowlist="*" --rpc-http-cors-origins="all" --rpc-http-port=8546 +``` + + + +The command line specifies: + +- The data directory for Node-2 using the [`--data-path`](../../../public-networks/reference/cli/options.md#data-path) option. +- A different port to Node-1 for P2P discovery using the [`--p2p-port`](../../../public-networks/reference/cli/options.md#p2p-port) option. +- A different port to Node-1 for HTTP JSON-RPC using the [`--rpc-http-port`](../../../public-networks/reference/cli/options.md#rpc-http-port) option. +- The enode URL of Node-1 using the [`--bootnodes`](../../../public-networks/reference/cli/options.md#bootnodes) option. +- Other options as for [Node-1](#6-start-the-first-node-as-the-bootnode). + +### 8. Start Node-3 + +Start another terminal, change to the `Node-3` directory and start Node-3 specifying the Node-1 enode URL copied when starting Node-1 as the bootnode: + + + +# MacOS + +```bash +besu --data-path=data --genesis-file=../genesis.json --bootnodes= --p2p-port=30305 --rpc-http-enabled --rpc-http-api=ETH,NET,IBFT --host-allowlist="*" --rpc-http-cors-origins="all" --rpc-http-port=8547 +``` + +# Windows + +```bash +besu --data-path=data --genesis-file=../genesis.json --bootnodes= --p2p-port=30305 --rpc-http-enabled --rpc-http-api=ETH,NET,IBFT --host-allowlist="*" --rpc-http-cors-origins="all" --rpc-http-port=8547 +``` + + + +The command line specifies: + +- The data directory for Node-3 using the [`--data-path`](../../../public-networks/reference/cli/options.md#data-path) option. +- A different port to Node-1 and Node-2 for P2P discovery using the [`--p2p-port`](../../../public-networks/reference/cli/options.md#p2p-port) option. +- A different port to Node-1 and Node-2 for HTTP JSON-RPC using the [`--rpc-http-port`](../../../public-networks/reference/cli/options.md#rpc-http-port) option. +- The bootnode as for [Node-2](#7-start-node-2). +- Other options as for [Node-1](#6-start-the-first-node-as-the-bootnode). + +### 9. Start Node-4 + +Start another terminal, change to the `Node-4` directory and start Node-4 specifying the Node-1 enode URL copied when starting Node-1 as the bootnode: + + + +# MacOS + +```bash +besu --data-path=data --genesis-file=../genesis.json --bootnodes= --p2p-port=30306 --rpc-http-enabled --rpc-http-api=ETH,NET,IBFT --host-allowlist="*" --rpc-http-cors-origins="all" --rpc-http-port=8548 +``` + +# Windows + +```bash +besu --data-path=data --genesis-file=..\genesis.json --bootnodes= --p2p-port=30306 --rpc-http-enabled --rpc-http-api=ETH,NET,IBFT --host-allowlist="*" --rpc-http-cors-origins="all" --rpc-http-port=8548 +``` + + + +The command line specifies: + +- The data directory for Node-4 using the [`--data-path`](../../../public-networks/reference/cli/options.md#data-path) option. +- A different port to Node-1, Node-2, and Node-3 for P2P discovery using the [`--p2p-port`](../../../public-networks/reference/cli/options.md#p2p-port) option. +- A different port to Node-1, Node-2, and Node-3 for HTTP JSON-RPC using the [`--rpc-http-port`](../../../public-networks/reference/cli/options.md#rpc-http-port) option. +- The bootnode as for [Node-2](#7-start-node-2). +- Other options as for [Node-1](#6-start-the-first-node-as-the-bootnode). + +### 10. Confirm the private network is working + +Start another terminal, use curl to call the JSON-RPC API [`ibft_getvalidatorsbyblocknumber`](../../reference/api/index.md#ibft_getvalidatorsbyblocknumber) method and confirm the network has four validators: + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"ibft_getValidatorsByBlockNumber","params":["latest"], "id":1}' localhost:8545 +``` + +The result displays the four validators: + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": [ + "0x1e326b6da177ede2d3eb6d7247bd9f6901d40234", + "0x4aaac297fefe4466ebcb0b23ab90c5f466b11556", + "0xa267ead2e91e1673e0943b925176b51d9cd4f6d2", + "0xe3e680bc0ff485d1d415a384721f19e0db65fea7" + ] +} +``` + +Look at the logs to confirm Besu is producing blocks: + +```bash +2020-12-21 07:22:17.883+10:00 | EthScheduler-Workers-0 | INFO | PersistBlockTask | Imported #1 / 0 tx / 0 om / 0 (0.0%) gas / (0xde088192f27ca376eea969cb7a4a1de445bd923fde0444194c88e630f7705584) in 0.010s. Peers: 4 +2020-12-21 07:22:19.057+10:00 | pool-8-thread-1 | INFO | IbftRound | Importing block to chain. round=ConsensusRoundIdentifier{Sequence=2, Round=0}, hash=0x2ca2652fa79ae2b3b6aadcfb13d5d362ffd6207c3b5ae47971e04eb9d05deaa9 +2020-12-21 07:22:21.044+10:00 | pool-8-thread-1 | INFO | IbftRound | Importing block to chain. round=ConsensusRoundIdentifier{Sequence=3, Round=0}, hash=0x5d9a06cd17127712cfae7d1c25f705f302e146f4b64a73de3c814e1b5a3f9a16 +2020-12-21 07:22:23.049+10:00 | pool-8-thread-1 | INFO | IbftRound | Importing block to chain. round=ConsensusRoundIdentifier{Sequence=4, Round=0}, hash=0x843981375f4cb2bb0f33a09b647ac27da5df2c539d940d8344c907eede57829c +2020-12-21 07:22:25.060+10:00 | pool-8-thread-1 | INFO | IbftRound | Importing block to chain. round=ConsensusRoundIdentifier{Sequence=5, Round=0}, hash=0x82b2069961d9185f7857cad1123de72d715729e122441335db486ea436834d6e +``` + +:::info + +If the key files were not copied to the correct directory in [step 5](#5-copy-the-node-private-keys-to-the-node-directories), the network will not start producing blocks. + +The logs for each node should indicate the public key was loaded from the `data/key` directory: + +```bash +2020-12-21 07:16:18.360+10:00 | main | INFO | KeyPairUtil | Loaded public key 0xe143eadaf670d49afa3327cae2e655b083f5a89dac037c9af065914a9f8e6bceebcfe7ae2258bd22a9cd18b6a6de07b9790e71de49b78afa456e401bd2fb22fc from /IBFT-Network/Node-1/data/key +``` + +If the keys were not copied to the correct directory, Besu creates a key when starting up: + +```bash +2020-12-21 07:33:11.458+10:00 | main | INFO | KeyPairUtil | Generated new public key 0x1a4a2ade5ebc0a85572e2492e0cdf3e96b8928c75fa55b4425de8849850cf9b3a8cad1e27d98a3d3afac326a5e8788dbe6cc40249715c92825aebb28abe3e346 and stored it to /IBFT-Network/Node-1/data/key +``` + +If a new key was created, the validator key specified in the configuration does not match the created key and the node cannot participate in creating blocks. + +::: + +## Next steps + +Use the [IBFT API](../../reference/api/index.md#ibft-20-methods) to remove or add validators. + +:::note + +To add or remove nodes as validators you need the node address. The directory [created for each node](#3-generate-node-keys-and-a-genesis-file) has the node address as the name. + +This tutorial configures a private network using IBFT 2.0 for educational purposes only. IBFT 2.0 requires four validators to be Byzantine fault tolerant. + +::: + +Import accounts to MetaMask and send transactions as described in the [Quickstart tutorial](../quickstart.md#create-a-transaction-using-metamask). + +:::info + +Besu doesn't support [private key management](../../../public-networks/how-to/send-transactions.md). + +::: + +## Stop the nodes + +When finished using the private network, stop all nodes using ++ctrl+c++ in each terminal window. + +:::tip + +To restart the IBFT 2.0 network in the future, start from [6. Start First Node as Bootnode](#6-start-the-first-node-as-the-bootnode). + +::: + + + +[IBFT 2.0 (proof of authority)consensus protocol]: ../../how-to/configure/consensus/ibft.md + + + +\*[Byzantine fault tolerant]: Ability to function correctly and reach consensus despite nodes failing or propagating incorrect information to peers. diff --git a/versioned_docs/version-23.10.1/private-networks/tutorials/ibft/validators.md b/versioned_docs/version-23.10.1/private-networks/tutorials/ibft/validators.md new file mode 100644 index 00000000000..1e74b04d01d --- /dev/null +++ b/versioned_docs/version-23.10.1/private-networks/tutorials/ibft/validators.md @@ -0,0 +1,125 @@ +--- +title: Add and removing IBFT 2.0 validators +sidebar_position: 1 +description: Adding and removing IBFT 2.0 validators +tags: + - private networks +--- + +# Add and remove IBFT 2.0 validators + +This example walks through [adding and removing an IBFT 2.0 validator](../../how-to/configure/consensus/ibft.md#add-and-remove-validators). + +## Prerequisites + +- [IBFT 2.0 network as configured in the IBFT 2.0 tutorial](index.md) + +## Add a validator + +### 1. Create directories + +Create a working directory and a data directory for the new node that needs to be added: + +```bash +mkdir -p Node-5/data +``` + +### 2. Start the node + +Change into the working directory for the new Node-5 and start the node, specifying the [Node-1 enode URL](index.md#6-start-the-first-node-as-the-bootnode) as the bootnode: + +```bash +besu --data-path=data --genesis-file=../genesis.json --bootnodes= --p2p-port=30307 --rpc-http-enabled --rpc-http-api=ETH,NET,IBFT --host-allowlist="*" --rpc-http-cors-origins="all" --rpc-http-port=8549 +``` + +The command line specifies: + +- The data directory for Node-5 using the [`--data-path`](../../../public-networks/reference/cli/options.md#data-path) option. +- A different port to Node-1 for P2P discovery using the [`--p2p-port`](../../../public-networks/reference/cli/options.md#p2p-port) option. +- A different port to Node-1 for HTTP JSON-RPC using the [`--rpc-http-port`](../../../public-networks/reference/cli/options.md#rpc-http-port) option. +- The enode URL of Node-1 using the [`--bootnodes`](../../../public-networks/reference/cli/options.md#bootnodes) option. +- Other options as for [Node-1](index.md#6-start-the-first-node-as-the-bootnode). + +### 3. Copy the address of the node + +Copy the address of the node. You can find the address in the logs when starting the new node: + +```bash +2021-05-28 09:49:00.881+10:00 | main | INFO | DefaultP2PNetwork | Node address 0x90626e6a67445aabf1c0615410d108d4733aa90b +``` + +Or use the [`public-key export-address`](../../../public-networks/reference/cli/subcommands.md#export-address) subcommand: + + + +# Subcommand + +```bash +besu --data-path=IBFT-Network/Node-5/data public-key export-address +``` + +# Output + +```bash +0x90626e6a67445aabf1c0615410d108d4733aa90b +``` + + + +### 4. Propose adding the new validator + +Propose adding the new validator from more than half the number of current validators, using [`ibft_proposeValidatorVote`](../../../public-networks/reference/api/index.md#ibft_proposevalidatorvote), specifying the address of the proposed validator and `true`: + + + +# curl HTTP request + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"ibft_proposeValidatorVote","params":["0x90626e6a67445aabf1c0615410d108d4733aa90b", true], "id":1}' http://127.0.0.1:8545 +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": true +} +``` + + + +Repeat the proposal process for this candidate node from at least two of the other nodes. + +### 5. Verify the addition of the new validator + +Verify that the new validator is now in the list of validators using [`ibft_getValidatorsByBlockNumber`](../../../public-networks/reference/api/index.md#ibft_getvalidatorsbyblocknumber): + + + +# curl HTTP request + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"ibft_getValidatorsByBlockNumber","params":["latest"], "id":1}' http://127.0.0.1:8545 +``` + +# JSON result + +```json +[ + "0x189d23d201b03ae1cf9113672df29a5d672aefa3", + "0x2aabbc1bb9bacef60a09764d1a1f4f04a47885c1", + "0x44b07d2c28b8ed8f02b45bd84ac7d9051b3349e6", + "0x4c1ccd426833b9782729a212c857f2f03b7b4c0d", + "0x90626e6a67445aabf1c0615410d108d4733aa90b" +] +``` + + + +The list of validators contains 5 addresses now. + +## Remove a validator + +The process for removing a validator is similar to [adding a validator](#add-a-validator) starting from step 2, except you specify `false` as the second parameter of [`ibft_proposeValidatorVote`](../../../public-networks/reference/api/index.md#ibft_proposevalidatorvote). diff --git a/versioned_docs/version-23.10.1/private-networks/tutorials/kubernetes/_category_.json b/versioned_docs/version-23.10.1/private-networks/tutorials/kubernetes/_category_.json new file mode 100644 index 00000000000..5a498fa215c --- /dev/null +++ b/versioned_docs/version-23.10.1/private-networks/tutorials/kubernetes/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Deploy using Kubernetes", + "position": 9 +} diff --git a/versioned_docs/version-23.10.1/private-networks/tutorials/kubernetes/charts.md b/versioned_docs/version-23.10.1/private-networks/tutorials/kubernetes/charts.md new file mode 100644 index 00000000000..259fe1d13d3 --- /dev/null +++ b/versioned_docs/version-23.10.1/private-networks/tutorials/kubernetes/charts.md @@ -0,0 +1,504 @@ +--- +title: Deploying Charts +sidebar_position: 3 +description: Deploying Besu Helm Charts for a Kubernetes cluster +tags: + - private networks +--- + +# Deploy charts + +You can deploy Besu Helm charts for a Kubernetes cluster. + +## Prerequisites + +- Clone the [Quorum-Kubernetes](https://github.com/ConsenSys/quorum-kubernetes) repository +- A [running Kubernetes cluster](cluster.md) +- Install [Kubectl](https://kubernetes.io/docs/tasks/tools/) +- Install [Helm3](https://helm.sh/docs/intro/install/) + +## Provision with Helm charts + +Helm is a method of packaging a collection of objects into a chart which can then be deployed to the cluster. After you have cloned the [Quorum-Kubernetes](https://github.com/ConsenSys/quorum-kubernetes) repository, change the directory to `helm` for the rest of this tutorial. + +```bash +cd helm +``` + +Each helm chart has the following key-map values which you will need to set depending on your needs. The `cluster.provider` is used as a key for the various cloud features enabled. Please specify only one cloud provider, not both. At present, the charts have full support for cloud native services in both AWS and Azure. Please note that if you use GCP, IBM etc please set `cluster.provider: local` and set `cluster.cloudNativeServices: false`. + +Please update the `aws` or `azure` map as shown below if you deploy to either cloud provider. + +```bash +cluster: + provider: local # choose from: local | aws | azure + cloudNativeServices: false # set to true to use Cloud Native Services (SecretsManager and IAM for AWS; KeyVault & Managed Identities for Azure) + reclaimPolicy: Delete # set to either Retain or Delete; note that PVCs and PVs will still exist after a 'helm delete'. Setting to Retain will keep volumes even if PVCs/PVs are deleted in kubernetes. Setting to Delete will remove volumes from EC2 EBS when PVC is deleted + +quorumFlags: + privacy: false + removeKeysOnDelete: false + +aws: + # the aws cli commands uses the name 'quorum-node-secrets-sa' so only change this if you altered the name + serviceAccountName: quorum-node-secrets-sa + # the region you are deploying to + region: ap-southeast-2 + +azure: + # the script/bootstrap.sh uses the name 'quorum-pod-identity' so only change this if you altered the name + identityName: quorum-pod-identity + # the clientId of the user assigned managed identity created in the template + identityClientId: azure-clientId + keyvaultName: azure-keyvault + # the tenant ID of the key vault + tenantId: azure-tenantId + # the subscription ID to use - this needs to be set explictly when using multi tenancy + subscriptionId: azure-subscriptionId +``` + +Setting the `cluster.cloudNativeServices: true`: + +- Stores keys in Azure Key Vault or AWS Secrets Manager. +- Uses Azure Managed Identities or AWS Identity and Access Management for pod identity access. + +:::note + +You can customize any of the charts in this repository to suit your requirements, and make pull requests to extend functionality. + +::: + +### 1. Check that you can connect to the cluster with `kubectl` + +Verify kubectl is connected to cluster using: (use the latest version) + +```bash +kubectl version +``` + +The result looks similar to: + +```bash +Client Version: version.Info{Major:"1", Minor:"23", GitVersion:"v1.23.1", GitCommit:"86ec240af8cbd1b60bcc4c03c20da9b98005b92e", GitTreeState:"clean", BuildDate:"2021-12-16T11:41:01Z", GoVersion:"go1.17.5", Compiler:"gc", Platform:"linux/amd64"} +Server Version: version.Info{Major:"1", Minor:"22", GitVersion:"v1.22.3", GitCommit:"c92036820499fedefec0f847e2054d824aea6cd1", GitTreeState:"clean", BuildDate:"2021-10-27T18:35:25Z", GoVersion:"go1.16.9", Compiler:"gc", Platform:"linux/amd64"} +``` + +### 2. Create the namespace + +This tutorial isolates groups of resources (for example, StatefulSets and Services) within a single cluster. + +:::note + +The rest of this tutorial uses `besu` as the namespace, but you're free to pick any name when deploying, as long as it's consistent across the [infrastructure scripts](cluster.md) and charts. + +::: + +Run the following in a terminal window: + +```bash +kubectl create namespace besu +``` + +### 3. Deploy the monitoring chart + +This chart deploys Prometheus and Grafana to monitor the metrics of the cluster, nodes and state of the network. + +Update the admin `username` and `password` in the [monitoring values file](https://github.com/ConsenSys/quorum-kubernetes/blob/5920caff6dd15b4ca17f760ad9e4d7d2e43b41a1/helm/values/monitoring.yml). Configure alerts to the receiver of your choice (for example, email or Slack), then deploy the chart using: + +```bash +helm repo add prometheus-community https://prometheus-community.github.io/helm-charts +helm repo update +helm install monitoring prometheus-community/kube-prometheus-stack --version 34.10.0 --namespace=besu --values ./values/monitoring.yml --wait +kubectl --namespace besu apply -f ./values/monitoring/ +``` + +Metrics are collected via a [ServiceMonitor](https://github.com/prometheus-operator/prometheus-operator/blob/7c77626e5e270a2530e187b185d45eeed8a773bf/Documentation/user-guides/getting-started.md) that scrapes each Besu pod, using given [`annotations`](https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/) which specify the port and path to use. For example: + +```bash + template: + metadata: + annotations: + prometheus.io/scrape: "true" + prometheus.io/port: 9545 + prometheus.io/path: "/metrics" +``` + +:::warning + +For production use cases, configure Grafana with one of the supported [native auth mechanisms](https://grafana.com/docs/grafana/latest/auth/). + +::: + +![k8s-metrics](../../../assets/images/kubernetes-grafana.png) + +Optionally you can also deploy the [Elastic Stack](https://www.elastic.co/elastic-stack/) to view logs (and metrics). + +```bash +helm repo add elastic https://helm.elastic.co +helm repo update +# if on cloud +helm install elasticsearch --version 7.17.1 elastic/elasticsearch --namespace quorum --values ./values/elasticsearch.yml +# if local - set the replicas to 1 +helm install elasticsearch --version 7.17.1 elastic/elasticsearch --namespace quorum --values ./values/elasticsearch.yml --set replicas=1 --set minimumMasterNodes: 1 +helm install kibana --version 7.17.1 elastic/kibana --namespace quorum --values ./values/kibana.yml +helm install filebeat --version 7.17.1 elastic/filebeat --namespace quorum --values ./values/filebeat.yml +``` + +If you install `filebeat`, please create a `filebeat-*` index pattern in `kibana`. All the logs from the nodes are sent to the `filebeat` index. If you use The Elastic stack for logs and metrics, please deploy `metricbeat` in a similar manner to `filebeat` and create an index pattern in Kibana. + +![k8s-elastic](../../../assets/images/kubernetes-elastic.png) + +To connect to Kibana or Grafana, we also need to deploy an ingress so you can access your monitoring endpoints publicly. We use Nginx as our ingress here, and you are free to configure any ingress per your requirements. + +```bash +helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx +helm repo update +helm install quorum-monitoring-ingress ingress-nginx/ingress-nginx \ + --namespace quorum \ + --set controller.ingressClassResource.name="monitoring-nginx" \ + --set controller.ingressClassResource.controllerValue="k8s.io/monitoring-ingress-nginx" \ + --set controller.replicaCount=1 \ + --set controller.nodeSelector."kubernetes\.io/os"=linux \ + --set defaultBackend.nodeSelector."kubernetes\.io/os"=linux \ + --set controller.admissionWebhooks.patch.nodeSelector."kubernetes\.io/os"=linux \ + --set controller.service.externalTrafficPolicy=Local + +kubectl apply -f ../ingress/ingress-rules-monitoring.yml +``` + +Once complete, view the IP address listed under the `Ingress` section if you're using the Kubernetes Dashboard or on the command line `kubectl -n quorum get services quorum-monitoring-ingress-ingress-nginx-controller`. + +:::note + +We refer to the ingress here as `external-nginx` because it deals with monitoring endpoints specifically. We also deploy a second ingress called `network-ingress` which is for the blockchain nodes only in [step 8](#9-connect-to-the-node-from-your-local-machine-via-an-ingress) + +::: + +![`k8s-ingress-external`](../../../assets/images/kubernetes-ingress-ip.png) + +You can view the Besu dashboard by going to: + +```bash +http:///d/XE4V0WGZz/besu-overview?orgId=1&refresh=10s +``` + +You can view the Kibana dashboard (if deployed) by going to: + +```bash +http:///kibana +``` + +### 4. Deploy the genesis chart + +The genesis chart creates the genesis file and keys for the validators. + +:::warning + +It's important to keep the release names of the initial validator pool as per this tutorial, that is `validator-n`, where `n` is the node number. Any validators created after the initial pool can be named to anything you like. + +::: + +The override [values.yml](https://github.com/ConsenSys/quorum-kubernetes/blob/5920caff6dd15b4ca17f760ad9e4d7d2e43b41a1/helm/values/genesis-besu.yml) looks like below: + +```bash +--- +quorumFlags: + removeGenesisOnDelete: true + +cluster: + provider: local # choose from: local | aws | azure + cloudNativeServices: false + +aws: + # the aws cli commands uses the name 'quorum-node-secrets-sa' so only change this if you altered the name + serviceAccountName: quorum-node-secrets-sa + # the region you are deploying to + region: ap-southeast-2 + +azure: + # the script/bootstrap.sh uses the name 'quorum-pod-identity' so only change this if you altered the name + identityName: quorum-pod-identity + # the clientId of the user assigned managed identity created in the template + identityClientId: azure-clientId + keyvaultName: azure-keyvault + # the tenant ID of the key vault + tenantId: azure-tenantId + # the subscription ID to use - this needs to be set explictly when using multi tenancy + subscriptionId: azure-subscriptionId + +# the raw Genesis config +# rawGenesisConfig.blockchain.nodes set the number of validators/signers +rawGenesisConfig: + genesis: + config: + chainId: 1337 + algorithm: + consensus: qbft # choose from: ibft2 | qbft | clique + blockperiodseconds: 10 + epochlength: 30000 + requesttimeoutseconds: 20 + gasLimit: '0x47b760' + difficulty: '0x1' + coinbase: '0x0000000000000000000000000000000000000000' + blockchain: + nodes: + generate: true + count: 4 + accountPassword: 'password' +``` + +Please set the `aws`, `azure` and `cluster` keys are as per the [Provisioning](#provision-with-helm-charts) step. `quorumFlags.removeGenesisOnDelete: true` tells the chart to delete the genesis file when the chart is deleted. If you may wish to retain the genesis on deletion, please set that value to `false`. + +The last config item is `rawGenesisConfig` which has details of the chain you are creating, please edit any of the parameters in there to match your requirements. To set the number of initial validators set the `rawGenesisConfig.blockchain.nodes` to the number that you'd like. We recommend using the Byzantine formula of `N=3F+1` when setting the number of validators. + +One more thing to note is that when `cluster.cloudNativeServices: true` is set, the genesis job will not add the [Quickstart](../quickstart.md) test accounts into the genesis file. + +When you are ready deploy the chart with : + +```bash +cd helm +helm install genesis ./charts/besu-genesis --namespace besu --create-namespace --values ./values/genesis-besu.yml +``` + +Once completed, view the genesis and enodes (the list of static nodes) configuration maps that every Besu node uses, and the validator and bootnode node keys as secrets. + +![k8s-genesis-configmaps](../../../assets/images/kubernetes-genesis-configmaps.png) + +![k8s-genesis-secrets](../../../assets/images/kuberenetes-genesis-secrets.png) + +### 5. Deploy the bootnodes + +This is an optional but recommended step. In a production setup we recommend the use of two ore more bootnodes for best practices. Each Besu node has a map that tells the StatefulSet what to deploy and how to clean up. The default `values.yml` for the StatefulSet define the following flags which are present in all the override values files. + +```bash +--- +quorumFlags: + privacy: false + removeKeysOnDelete: true + isBootnode: true # set this to true if this node is a bootnode + usesBootnodes: true # set this to true if the network you are connecting to use a bootnode/s that are deployed in the cluster + +cluster: + provider: local # choose from: local | aws | azure + cloudNativeServices: false + reclaimPolicy: Delete # set to either Retain or Delete; note that PVCs and PVs will still exist after a 'helm delete'. Setting to Retain will keep volumes even if PVCs/PVs are deleted in kubernetes. Setting to Delete will remove volumes from EC2 EBS when PVC is deleted + +aws: + # the aws cli commands uses the name 'quorum-node-secrets-sa' so only change this if you altered the name + serviceAccountName: quorum-node-secrets-sa + # the region you are deploying to + region: ap-southeast-2 + +azure: + # the script/bootstrap.sh uses the name 'quorum-pod-identity' so only change this if you altered the name + identityName: quorum-pod-identity + # the clientId of the user assigned managed identity created in the template + identityClientId: azure-clientId + keyvaultName: azure-keyvault + # the tenant ID of the key vault + tenantId: azure-tenantId + # the subscription ID to use - this needs to be set explictly when using multi tenancy + subscriptionId: azure-subscriptionId + +node: + besu: + metrics: + serviceMonitorEnabled: true + resources: + cpuLimit: 1 + cpuRequest: 0.1 + memLimit: "2G" + memRequest: "1G" +``` + +Please set the `aws`, `azure` and `cluster` keys are as per the [Provisioning](#provision-with-helm-charts) step. `quorumFlags.removeKeysOnDelete: true` tells the chart to delete the node's keys when the chart is deleted. If you may wish to retain the keys on deletion, please set that value to `false`. + +For the bootnodes only, set the `quorumFlags.isBootnode: true`. When using bootnodes you have to also set `quorumFlags.usesBootnodes: true` to indicate that all nodes on the network will use these bootnodes. + +:::note + +If you use bootnodes, you must set `quorumFlags.usesBootnodes: true` in the override values.yaml for every other node type, that is validators.yaml, txnode.yaml and reader.yaml + +::: + +```bash +helm install bootnode-1 ./charts/besu-node --namespace besu --values ./values/bootnode.yml +helm install bootnode-2 ./charts/besu-node --namespace besu --values ./values/bootnode.yml +``` + +Once complete, you see two StatefulSets, and the two bootnodes discover themselves and peer. Because there are no validators present yet, there are no blocks created, as seen in the following logs. + +![k8s-bootnode-logs](../../../assets/images/kubernetes-bootnode-logs.png) + +### 6. Deploy the validators + +The validators peer with the bootnodes and themselves, and when a majority of the validators have peered, blocks are proposed and created on the chain. + +These are the next set of nodes that we will deploy. The charts use four validators (default) to replicate best practices for a network. The override [values.yml](https://github.com/ConsenSys/quorum-kubernetes/blob/5920caff6dd15b4ca17f760ad9e4d7d2e43b41a1/helm/values/validator.yml) for the StatefulSet looks like below: + +```bash +--- +quorumFlags: + privacy: false + removeKeysOnDelete: false + isBootnode: false # set this to true if this node is a bootnode + usesBootnodes: true # set this to true if the network you are connecting to use a bootnode/s that are deployed in the cluster +``` + +Please set the `aws`, `azure` and `cluster` keys are as per the [Provisioning](#provision-with-helm-charts) step. `quorumFlags.removeKeysOnDelete: true` tells the chart to delete the node's keys when the chart is deleted. If you may wish to retain the keys on deletion, please set that value to `false`. + +:::warning + +Please note that if you delete a majority of the validators, the network will halt. Additionally, if the validator keys are deleted you may not be able to recover as you need a majority of the validators up to vote to add new validators into the pool + +::: + +When using bootnodes (if deployed in the previous step) you have to also set `quorumFlags.usesBootnodes: true` to indicate that all nodes on the network will use these bootnodes. + +For the initial validator pool we set all the node flags to `false` and then deploy. + +```bash +helm install validator-1 ./charts/besu-node --namespace besu --values ./values/validator.yml +helm install validator-2 ./charts/besu-node --namespace besu --values ./values/validator.yml +helm install validator-3 ./charts/besu-node --namespace besu --values ./values/validator.yml +helm install validator-4 ./charts/besu-node --namespace besu --values ./values/validator.yml +``` + +:::warning + +It's important to keep the release names of the validators the same as it is tied to the keys that the genesis chart creates. So we use `validator-1`, `validator-2`, etc. in the following command. + +::: + +Once completed, you may need to give the validators a few minutes to peer and for round changes, depending on when the first validator was spun up, before the logs display blocks being created. + +![k8s-validator-logs](../../../assets/images/kubernetes-validator-logs.png) + +### 7. Add/Remove additional validators to the validator pool + +To add (or remove) more validators to the initial validator pool, you need to deploy a node such as an RPC node (step 8) and then [vote](../../how-to/configure/consensus/ibft.md#add-and-remove-validators) that node in. The vote API call must be made on a majority of the existing pool and the new node will then become a validator. + +Please refer to the [Ingress Section](#9-connect-to-the-node-from-your-local-machine-via-an-ingress) for details on making the API calls from your local machine or equivalent. + +### 8. Deploy RPC or Transaction nodes + +An RPC node is simply a node that can be used to make public transactions or perform read heavy operations such as when connected to a chain explorer like [BlockScout](https://github.com/blockscout/blockscout). + +The RPC override [values.yml](https://github.com/ConsenSys/quorum-kubernetes/blob/5920caff6dd15b4ca17f760ad9e4d7d2e43b41a1/helm/values/reader.yml) for the StatefulSet looks identical to that of the validators above, and will create it's own node keys before the node starts. + +To deploy an RPC node: + +```bash +helm install rpc-1 ./charts/besu-node --namespace besu --values ./values/reader.yml +``` + +A Transaction or Member node in turn is one which has an accompanying Private Transaction Manager, such as Tessera; which allow you to make private transactions between nodes. + +The Transaction override [values.yml](https://github.com/ConsenSys/quorum-kubernetes/blob/5920caff6dd15b4ca17f760ad9e4d7d2e43b41a1/helm/values/txnode.yml) for the StatefulSet looks identical to that of the validators above and only has `quorumFlags.privacy: true` to indicate that it is deploying a pair of GoQuorum and Tessera nodes. + +To deploy a Transaction or Member node: + +```bash +helm install member-1 ./charts/besu-node --namespace besu --values ./values/txnode.yml +``` + +Logs for `member-1` resemble the following for Tessera: + +![`k8s-tx-tessera-logs`](../../../assets/images/kubernetes-tx-tessera-logs.png) + +Logs for Besu resemble the following: + +![`k8s-tx-Besu-logs`](../../../assets/images/kubernetes-tx-Besu-logs.png) + +:::note + +In these examples we use `member-1` and `rpc-1` as release names for the deployments. You can pick any release name that you'd like to use in place of those as per your requirements. + +::: + +### 9. Connect to the node from your local machine via an ingress + +In order to view the Grafana dashboards or connect to the nodes to make transactions from your local machine you can deploy an ingress controller with rules. We use the `ingress-nginx` ingress controller which can be deployed as follows: + +```bash +helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx +helm repo update +helm install quorum-network-ingress ingress-nginx/ingress-nginx \ + --namespace quorum \ + --set controller.ingressClassResource.name="network-nginx" \ + --set controller.ingressClassResource.controllerValue="k8s.io/network-ingress-nginx" \ + --set controller.replicaCount=1 \ + --set controller.nodeSelector."kubernetes\.io/os"=linux \ + --set defaultBackend.nodeSelector."kubernetes\.io/os"=linux \ + --set controller.admissionWebhooks.patch.nodeSelector."kubernetes\.io/os"=linux \ + --set controller.service.externalTrafficPolicy=Local +``` + +Use [pre-defined rules](https://github.com/ConsenSys/quorum-kubernetes/blob/5920caff6dd15b4ca17f760ad9e4d7d2e43b41a1/ingress/ingress-rules-besu.yml) to test functionality, and alter to suit your requirements (for example, restrict access for API calls to trusted CIDR blocks). + +Edit the [rules](https://github.com/ConsenSys/quorum-kubernetes/blob/5920caff6dd15b4ca17f760ad9e4d7d2e43b41a1/ingress/ingress-rules-besu.yml) file so that the service names match your release name. In the example, we deployed a transaction node with the release name `member-1` so the corresponding service is called `besu-node-member-1`. Once you have settings that match your deployments, deploy the rules as follows: + +```bash +kubectl apply -f ../ingress/ingress-rules-besu.yml +``` + +Once complete, view the IP address listed under the `Ingress` section if you're using the Kubernetes Dashboard or on the command line `kubectl -n quorum get services quorum-network-ingress-ingress-nginx-controller`. + +![`k8s-ingress`](../../../assets/images/kubernetes-ingress-ip.png) + +The following is an example RPC call, which confirms that the node running the JSON-RPC service is syncing: + + + +# curl HTTP request + +```bash +curl -v -X POST -H "Content-Type: application/json" --data '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}' http:///rpc +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": "0x4e9" +} +``` + + + +### 10. Blockchain explorer + +You can deploy [BlockScout](https://github.com/blockscout/blockscout) to aid with monitoring the blockchain. To do this, update the [BlockScout values file](https://github.com/ConsenSys/quorum-kubernetes/blob/5920caff6dd15b4ca17f760ad9e4d7d2e43b41a1/helm/values/blockscout-besu.yml) and set the `database` and `secret_key_base` values. + +:::important + +Changes to the database requires changes to both the `database` and the `blockscout` dictionaries. + +::: + +Once completed, deploy the chart using: + +```bash +helm dependency update ./charts/blockscout +helm install blockscout ./charts/blockscout --namespace quorum --values ./values/blockscout-goquorum.yaml +``` + +You can optionally deploy the [Quorum-Explorer](https://github.com/ConsenSys/quorum-explorer) as a lightweight blockchain explorer. The Quorum Explorer is not recommended for use in production and is intended for demonstration or Development purposes only. The Explorer can give an overview over the whole network, such as querying each node on the network for node or block information, voting (add/remove) validators from the network, demonstrating a SimpleStorage smart contract with privacy enabled, and sending transactions between wallets as you would do in MetaMask. Please see the [Explorer](quorum-explorer.md) page for details on how to use the application. + +:::warning + +The accounts listed in the file below are for test purposes only and should not be used on a production network. + +::: + +To deploy the application, update the [Explorer values file](https://github.com/ConsenSys/quorum-kubernetes/blob/5920caff6dd15b4ca17f760ad9e4d7d2e43b41a1/helm/values/explorer-besu.yaml) with details of your nodes and endpoints and then deploy. + +```bash +helm install quorum-explorer ./charts/explorer --namespace besu --values ./values/explorer-besu.yaml +``` + +You will also need deploy the ingress (if not already done in [Monitoring](#3-deploy-the-monitoring-chart) to access the endpoint on `http:///explorer` + +![`k8s-explorer`](../../../assets/images/kubernetes-explorer.png) diff --git a/versioned_docs/version-23.10.1/private-networks/tutorials/kubernetes/cluster.md b/versioned_docs/version-23.10.1/private-networks/tutorials/kubernetes/cluster.md new file mode 100644 index 00000000000..ba2772510b6 --- /dev/null +++ b/versioned_docs/version-23.10.1/private-networks/tutorials/kubernetes/cluster.md @@ -0,0 +1,230 @@ +--- +title: Create a cluster +sidebar_position: 2 +description: Create a cluster for deployment +tags: + - private networks +--- + +# Create a cluster + +You can create a [local](#local-clusters) or [cloud](#cloud-clusters) cluster to deploy a Besu network using Kubernetes. + +## Prerequisites + +- Clone the [Quorum-Kubernetes](https://github.com/ConsenSys/quorum-kubernetes) repository +- Install [Kubectl](https://kubernetes.io/docs/tasks/tools/) +- Install [Helm3](https://helm.sh/docs/intro/install/) +- Install [AWS CLI](https://aws.amazon.com/cli/) and [`eksctl`](https://eksctl.io/) for AWS EKS clusters +- Install [Azure CLI](https://docs.microsoft.com/en-us/cli/azure/install-azure-cli) for Azure AKS clusters +- Install the cloud-specific CLI + +## Local Clusters + +Use one of several options to create a local cluster. Select one listed below, or another that you're comfortable with. + +### Minikube + +[Minikube](https://minikube.sigs.k8s.io/docs/start/) is one of the most popular options to spin up a local Kubernetes cluster for development. You can [install a version](https://minikube.sigs.k8s.io/docs/start/) based on your architecture. + +:::note + +We recommend at least 2 CPUs and 16GB of RAM. + +::: + +To start the cluster, run the following command: + +```bash +minikube start --cpus 2 --memory 16384 --cni auto +``` + +### kind + +[kind (Kubernetes in Docker)](https://kind.sigs.k8s.io) is a lightweight tool for running local Kubernetes clusters. The [installation](https://kind.sigs.k8s.io/docs/user/quick-start#installation) is similar to [Minikube](#minikube). + +To start the cluster, run the following command: + +```bash +kind create cluster +``` + +### Rancher + +[Rancher](https://github.com/rancher-sandbox/rancher-desktop/) is a lightweight open source desktop application for Mac, Windows, and Linux. It provides Kubernetes and container management, and allows you to choose the version of Kubernetes to run. + +It can build, push, pull, and run container images. Built container images can be run without needing a registry. + +:::note + +The official Docker-CLI is not supported but rather uses [nerdctl](https://github.com/containerd/nerdctl) which is a Docker-CLI compatible tool for containerd, and is automatically installed with Rancher Desktop. + +::: + +:::note + +For Windows, you must [install Windows Subsystem for Linux (WSL)](https://docs.microsoft.com/en-us/windows/wsl/install) to install Rancher Desktop. + +Refer to the [official Rancher Desktop documentation](https://docs.rancherdesktop.io/) for system requirements and installation instructions. + +::: + +## Cloud clusters + +### AWS EKS + +[AWS Elastic Kubernetes Service (AWS EKS)](https://aws.amazon.com/eks/) is one of the most popular platforms to deploy Hyperledger Besu. + +To create a cluster in AWS, you must install the [AWS CLI](https://aws.amazon.com/cli/) and [`eksctl`](https://eksctl.io/). + +The [template](https://github.com/ConsenSys/quorum-kubernetes/tree/master/aws) comprises the base infrastructure used to build the cluster and other resources in AWS. We also use some native services with the cluster for performance and best practices, these include: + +- [Pod identities](https://github.com/aws/amazon-eks-pod-identity-webhook). +- [Secrets Store CSI drivers](https://docs.aws.amazon.com/eks/latest/userguide/ebs-csi.html). +- Dynamic storage classes backed by AWS EBS. The [volume claims](https://kubernetes.io/docs/concepts/storage/persistent-volumes/#persistentvolumeclaims) are fixed sizes and can be updated as you grow via helm updates, and won't need to re-provision the underlying storage class. +- [CNI](https://docs.aws.amazon.com/eks/latest/userguide/pod-networking.html) networking mode for EKS. By default, EKS clusters use `kubenet` to create a virtual network and subnet. Nodes get an IP address from a virtual network subnet. Network address translation (NAT) is then configured on the nodes, and pods receive an IP address "hidden" behind the node IP. + + :::note + + This approach reduces the number of IP addresses that you must reserve in your network space for pods, but constrains what can connect to the nodes from outside the cluster (for example, on-premise nodes or those on another cloud provider). + + ::: + +AWS Container Networking Interface (CNI) provides each pod with an IP address from the subnet, and can be accessed directly. The IP addresses must be unique across your network space, and must be planned in advance. Each node has a configuration parameter for the maximum number of pods that it supports. The equivalent number of IP addresses per node are then reserved up front for that node. This approach requires more planning, and can lead to IP address exhaustion as your application demands grow, however makes it easier for external nodes to connect to your cluster. + +:::warning + +EKS clusters must not use 169.254.0.0/16, 172.30.0.0/16, 172.31.0.0/16, or 192.0.2.0/24 for the Kubernetes service address range. + +::: + +To provision the cluster: + +1. Update [cluster.yml](https://github.com/ConsenSys/quorum-kubernetes/blob/5920caff6dd15b4ca17f760ad9e4d7d2e43b41a1/aws/templates/cluster.yml) + +2. Deploy the template: + + ```bash + eksctl create cluster -f ./templates/cluster.yml + ``` + +3. Your `.kube/config` should be connected to the cluster automatically, but if not, run the commands below and replace `AWS_REGION` and `CLUSTER_NAME` with details that are specific to your deployment. + + ```bash + aws sts get-caller-identity + aws eks --region AWS_REGION update-kubeconfig --name CLUSTER_NAME + ``` + +4. After the deployment completes, provision the EBS drivers for the volumes. While it is possible to use the in-tree `aws-ebs` driver that's natively supported by Kubernetes, it is no longer being updated and does not support newer EBS features such as the [cheaper and better gp3 volumes](https://stackoverflow.com/questions/68359043/whats-the-difference-between-ebs-csi-aws-com-vs-kubernetes-io-aws-ebs-for-provi). The `cluster.yml` file (from the steps above) that is included in this folder automatically deploys the cluster with the EBS IAM policies, but you need to install the EBS CSI drivers. This can be done through the AWS Management Console for simplicity, or via a CLI command as below. Replace `CLUSTER_NAME`, `AWS_REGION` and `AWS_ACCOUNT` with details that are specific to your deployment. + + ```bash + eksctl create iamserviceaccount --name ebs-csi-controller-sa --namespace kube-system --cluster CLUSTER_NAME --region AWS_REGION --attach-policy-arn arn:aws:iam::aws:policy/service-role/AmazonEBSCSIDriverPolicy --approve --role-only --role-name AmazonEKS_EBS_CSI_DriverRole + + eksctl create addon --name aws-ebs-csi-driver --cluster CLUSTER_NAME --region AWS_REGION --service-account-role-arn arn:aws:iam::AWS_ACCOUNT:role/AmazonEKS_EBS_CSI_DriverRole --force + ``` + +5. Once the deployment is completed, provision the Secrets Manager IAM and CSI driver. Use `besu` (or equivalent) for `NAMESPACE` and replace `CLUSTER_NAME`, `AWS_REGION` and `AWS_ACCOUNT` with details that are specific to your deployment. + + ```bash + helm repo add secrets-store-csi-driver https://kubernetes-sigs.github.io/secrets-store-csi-driver/charts + helm install --namespace kube-system --create-namespace csi-secrets-store secrets-store-csi-driver/secrets-store-csi-driver + kubectl apply -f https://raw.githubusercontent.com/aws/secrets-store-csi-driver-provider-aws/main/deployment/aws-provider-installer.yaml + + POLICY_ARN=$(aws --region AWS_REGION --query Policy.Arn --output text iam create-policy --policy-name quorum-node-secrets-mgr-policy --policy-document '{ + "Version": "2012-10-17", + "Statement": [ { + "Effect": "Allow", + "Action": ["secretsmanager:CreateSecret","secretsmanager:UpdateSecret","secretsmanager:DescribeSecret","secretsmanager:GetSecretValue","secretsmanager:PutSecretValue","secretsmanager:ReplicateSecretToRegions","secretsmanager:TagResource"], + "Resource": ["arn:aws:secretsmanager:AWS_REGION:AWS_ACCOUNT:secret:besu-node-*"] + } ] + }') + + # If you have deployed the above policy before, you can acquire its ARN: + POLICY_ARN=$(aws iam list-policies --scope Local \ + --query 'Policies[?PolicyName==`quorum-node-secrets-mgr-policy`].Arn' \ + --output text) + + eksctl create iamserviceaccount --name quorum-node-secrets-sa --namespace NAMESPACE --region=AWS_REGION --cluster CLUSTER_NAME --attach-policy-arn "$POLICY_ARN" --approve --override-existing-serviceaccounts + ``` + + :::warning + + The above command creates a service account called `quorum-node-secrets-sa` and is preconfigured in the helm charts override `values.yml` files, for ease of use. + + ::: + +6. Optionally, deploy the [kubernetes dashboard](https://github.com/ConsenSys/quorum-kubernetes/tree/master/aws/templates/k8s-dashboard). + +7. You can now use your cluster and you can deploy [Helm charts](charts.md) to it. + +### Azure Kubernetes Service + +[Azure Kubernetes Service (AKS)](https://azure.microsoft.com/en-us/services/kubernetes-service/) is another popular cloud platform that you can use to deploy Besu. To create a cluster in Azure, you must install the [Azure CLI](https://docs.microsoft.com/en-us/cli/azure/install-azure-cli) and have admin rights on your Azure subscription to enable some preview features on AKS. + +The [template](https://github.com/ConsenSys/quorum-kubernetes/tree/master/azure) comprises the base infrastructure used to build the cluster and other resources in Azure. We also make use Azure native services and features after the cluster is created. These include: + +- [AAD pod identities](https://docs.microsoft.com/en-us/azure/aks/use-azure-ad-pod-identity). +- [Secrets Store CSI drivers](https://docs.microsoft.com/en-us/azure/key-vault/general/key-vault-integrate-kubernetes). +- Dynamic storage classes backed by Azure Files. The [volume claims](https://docs.microsoft.com/en-us/azure/aks/azure-disks-dynamic-pv) are fixed sizes and can be updated as you grow via helm updates, and won't need to re-provision the underlying storage class. +- [CNI](https://docs.microsoft.com/en-us/azure/aks/configure-azure-cni) networking mode for AKS. By default, AKS clusters use `kubenet`, to create a virtual network and subnet. Nodes get an IP address from a virtual network subnet. Network address translation (NAT) is then configured on the nodes, and pods receive an IP address "hidden" behind the node IP. + + :::note + + This approach reduces the number of IP addresses you must reserve in your network space for pods to use, but constrains what can connect to the nodes from outside the cluster (for example, on-premise nodes or other cloud providers). + + ::: + +AKS Container Networking Interface (CNI) provides each pod with an IP address from the subnet, and can be accessed directly. These IP addresses must be unique across your network space, and must be planned in advance. Each node has a configuration parameter for the maximum number of pods that it supports. The equivalent number of IP addresses per node are then reserved up front for that node. This approach requires more planning, and can leads to IP address exhaustion as your application demands grow, however makes it easier for external nodes to connect to your cluster. + +:::warning + +Please do not create more than one AKS cluster in the same subnet. AKS clusters may not use `169.254.0.0/16`, `172.30.0.0/16`, `172.31.0.0/16`, or `192.0.2.0/24` for the Kubernetes service address range. + +::: + +To provision the cluster: + +1. Enable the preview features that allow you to use AKS with CNI, and a managed identity to authenticate and run cluster operations with other services. We also enable [AAD pod identities](https://docs.microsoft.com/en-us/azure/aks/use-azure-ad-pod-identity) which use the managed identity. This is in preview, so you must enable this feature by registering the `EnablePodIdentityPreview` feature: + + ```bash + az feature register --name EnablePodIdentityPreview --namespace Microsoft.ContainerService + ``` + + This takes a little while and you can check on progress by running: + + ```bash + az feature list --namespace Microsoft.ContainerService -o table + ``` + + Install or update your local Azure CLI with preview features: + + ```bash + az extension add --name aks-preview + az extension update --name aks-preview + ``` + +1. Create a resource group if you don't already have one: + + ```bash + az group create --name BesuGroup --location "East US" + ``` + +1. Deploy the template: + + 1. Navigate to the [Azure portal](https://portal.azure.com), select **+ Create a resource** in the upper left corner. + 1. Search for `Template deployment (deploy using custom templates)` and select **Create**. + 1. Select **Build your own template in the editor**. + 1. Remove the contents (JSON) in the editor and paste in the contents of [`azuredeploy.json`](https://github.com/ConsenSys/quorum-kubernetes/blob/5920caff6dd15b4ca17f760ad9e4d7d2e43b41a1/azure/arm/azuredeploy.json) + 1. Select **Save**. + 1. Input provisioning parameters in the displayed user interface. + +1. Provision the drivers: + + 1. Run the [bootstrap](https://github.com/ConsenSys/quorum-kubernetes/blob/5920caff6dd15b4ca17f760ad9e4d7d2e43b41a1/azure/scripts/bootstrap.sh) script. + 1. Use `besu` for `AKS_NAMESPACE`, and update `AKS_RESOURCE_GROUP`, `AKS_CLUSTER_NAME`, and `AKS_MANAGED_IDENTITY` in the commands below to match your settings and deployed resources from step 3. + + ```bash + ./scripts/bootstrap.sh "AKS_RESOURCE_GROUP" "AKS_CLUSTER_NAME" "AKS_MANAGED_IDENTITY" "AKS_NAMESPACE" + ``` + +1. You can now use your cluster and you can deploy [Helm charts](charts.md) to it. diff --git a/versioned_docs/version-23.10.1/private-networks/tutorials/kubernetes/index.md b/versioned_docs/version-23.10.1/private-networks/tutorials/kubernetes/index.md new file mode 100644 index 00000000000..bd1dea65869 --- /dev/null +++ b/versioned_docs/version-23.10.1/private-networks/tutorials/kubernetes/index.md @@ -0,0 +1,138 @@ +--- +title: Deploy a Hyperledger Besu private network with Kubernetes +description: Deploying Hyperledger Besu with Kubernetes +tags: + - private networks +--- + +# Deploy Besu using Kubernetes + +Use the [reference implementations](https://github.com/ConsenSys/besu-kubernetes) to install private networks using Kubernetes (K8s). Reference implementations are available using: + +- [Helm](https://github.com/ConsenSys/quorum-kubernetes/tree/master/helm). +- [Helmfile](https://github.com/roboll/helmfile). +- [`kubectl`](https://github.com/ConsenSys/besu-kubernetes/tree/master/playground/kubectl). + +Familiarize yourself with the reference implementations and customize them for your requirements. + +## Quorum-Kubernetes + +[Quorum-Kubernetes](https://github.com/ConsenSys/quorum-Kubernetes) is a repository containing Kubernetes manifests and Helm charts that you can customize and deploy on a local cluster or in the cloud. + +:::important + +We recommend starting with the [playground](https://github.com/ConsenSys/quorum-kubernetes/tree/master/playground) directory and working through the example setups before moving to the [`Helm charts`](https://github.com/ConsenSys/quorum-kubernetes/tree/master/helm/) directory. + +::: + +The `helm` directory contains charts for the various components, and each chart has a `cluster` map with features that you can toggle. + +```bash +cluster: + provider: local # choose from: local | aws | azure + cloudNativeServices: false # set to true to use Cloud Native Services (SecretsManager and IAM for AWS; KeyVault & Managed Identities for Azure) +``` + +Setting `cluster.cloudNativeServices: true` stores keys in AWS Secrets Manager or Azure Key Vault instead of Kubernetes Secrets, and will also make use of AWS IAM or Azure Managed Identities for the pods. + +### Cloud support + +The repository's `helm` charts support on-premise and cloud providers such as AWS, Azure, GCP, IBM etc. You can configure the provider in the [values.yml](https://github.com/ConsenSys/quorum-kubernetes/blob/5920caff6dd15b4ca17f760ad9e4d7d2e43b41a1/helm/values/genesis-besu.yml) file of the respective charts by setting `cluster.provider` to `local`, `aws`, or `azure`. If you use GCP, IBM etc., please set `cluster.provider: local` and `cluster.cloudNativeServices: false`. + +The repository also contains [Azure ARM templates](https://github.com/ConsenSys/quorum-kubernetes/tree/master/azure) and [AWS `eksctl` templates](https://github.com/ConsenSys/quorum-kubernetes/tree/master/aws) to deploy the required base infrastructure. + +## Limitations + +When using multi-clusters, Kubernetes load balancers disallow TCP and UDP traffic on the same port, which inhibits discovery working natively for each pod. Use the following solutions to mitigate this limitation: + +- Disallow discovery and use static nodes to allow only TCP traffic. This isn't an issue for load balancers or exposing nodes publicly. +- If you need to use discovery, use something such as [CNI](#cni) which is supported by all major cloud providers, and the cloud templates already have CNI implemented. + +### CNI + +With the traditional `kubenet` networking mode, nodes get an IP from the virtual network subnet. Each node in turn uses NAT to configure the pods so that they reach other pods on the virtual network. This limits where they can reach but also more specifically what can reach them. For example, an external VM which must have custom routes does not scale well. + +![without-CNI](../../../assets/images/kubernetes-1.jpeg) + +CNI, on the other hand, allows every pod to get a unique IP directly from the virtual subnet which removes this restriction. Therefore, it has a limit on the maximum number of pods that can be spun up, so you must plan ahead to avoid IP exhaustion. + +![with-CNI](../../../assets/images/kubernetes-2.jpeg) + +## Multi-cluster + +You must enable [CNI](#cni) to use multi-cluster, or to connect external nodes to an existing Kubernetes cluster. To connect multiple clusters, they must each have different CIDR blocks to ensure no conflicts, and the first step is to peer the VPCs or VNets together and update the route tables. From that point on you can use static nodes and pods to communicate across the cluster. + +The same setup also works to connect external nodes and business applications from other infrastructure, either in the cloud or on premise. + +![multi-cluster](../../../assets/images/kubernetes-3.png) + +## Concepts + +### Namespaces + +In Kubernetes, [namespaces](https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/) provide a mechanism for isolating groups of resources within a single cluster. Both namespaces and resources (for example, Stateful Sets or Services) within a namespace must be unique, but resources across namespaces don't need to be. + +:::note + +Namespace-based scoping is not applicable for cluster-wide objects (for example, Storage Class or Persistent Volumes). + +::: + +### Nodes + +Consider using Stateful Sets instead of Deployments for Besu. The term 'client node' refers to bootnode, validator and member/RPC nodes. For Besu nodes, we only use CLI arguments to keep things consistent. + +### Role-based access controls + +We encourage using role-based access controls (RBACs) for access to the private key of each node, that is, only a specific pod or statefulset is allowed to access a specific secret. + +If you need to specify a Kube configuration file for each pod, use the `KUBE_CONFIG_PATH` variable. + +### Storage + +We use separate data volumes to store the blockchain data. This is similar to using separate volumes to store data when using docker containers natively or docker-compose. This is done for a few reasons: + +- Containers are mortal and we do not want to store data on them. +- Kubernetes host nodes can fail and we want the chain data to persist. + +Ensure that you provide enough data storage capacity for all nodes on the cluster. Select the appropriate type of [Storage Class](https://kubernetes.io/docs/concepts/storage/storage-classes/) based on your cloud provider. In the templates, the size of the [volume claims](https://kubernetes.io/docs/concepts/storage/persistent-volumes/#persistentvolumeclaims) is set to 20Gb by default; you can change this depending on your needs. If you have a different storage account than the one in the charts, you may edit those [Storage Classes](https://github.com/ConsenSys/quorum-kubernetes/blob/5920caff6dd15b4ca17f760ad9e4d7d2e43b41a1/helm/charts/besu-node/templates/node-storage.yaml). + +When using Persistent Volume Claims, set the `allowVolumeExpansion` to `true`. This helps keep costs low and enables growing the volume over time rather than creating new volumes and copying data across. + +### Monitoring + +We recommend deploying metrics to get an overview of the network, nodes, and volumes. You can also create alerts. + +Besu publishes metrics to Prometheus, and you can configure metrics using the kubernetes scraper configuration. We also have custom Grafana dashboards to monitor the blockchain. + +:::note + +Refer to `values/monitoring.yml` to configure the alerts per your requirements (for example slack or email). + +::: + +```bash +cd helm +helm repo add prometheus-community https://prometheus-community.github.io/helm-charts +helm repo update +helm install monitoring prometheus-community/kube-prometheus-stack --version 34.10.0 --namespace=besu --create-namespace --values ./values/monitoring.yml --wait +kubectl --namespace besu apply -f ./values/monitoring/ +``` + +You can configure Besu to suit your environment. For example, use the Elastic charts to log to a file that you can parse using Logstash into an ELK cluster. + +```bash +cd helm +helm repo add elastic https://helm.elastic.co +helm repo update +# if on cloud +helm install elasticsearch --version 7.17.1 elastic/elasticsearch --namespace besu --create-namespace --values ./values/elasticsearch.yml +# if local - set the replicas to 1 +helm install elasticsearch --version 7.17.1 elastic/elasticsearch --namespace besu --create-namespace --values ./values/elasticsearch.yml --set replicas=1 --set minimumMasterNodes: 1 +helm install kibana --version 7.17.1 elastic/kibana --namespace besu --values ./values/kibana.yml +helm install filebeat --version 7.17.1 elastic/filebeat --namespace besu --values ./values/filebeat.yml +``` + +### Ingress Controllers + +If you require the ingress controllers for the RPC calls or the monitoring dashboards, we have provided example [rules](https://github.com/ConsenSys/quorum-kubernetes/blob/5920caff6dd15b4ca17f760ad9e4d7d2e43b41a1/ingress/ingress-rules-besu.yml) that are pre-configured for common use cases. Use these as a reference and develop solutions to match your network topology and requirements. diff --git a/versioned_docs/version-23.10.1/private-networks/tutorials/kubernetes/maintenance.md b/versioned_docs/version-23.10.1/private-networks/tutorials/kubernetes/maintenance.md new file mode 100644 index 00000000000..a32bf1a15b2 --- /dev/null +++ b/versioned_docs/version-23.10.1/private-networks/tutorials/kubernetes/maintenance.md @@ -0,0 +1,64 @@ +--- +title: Maintenance +sidebar_position: 5 +description: Maintenance for Besu on a Kubernetes cluster +tags: + - private networks +--- + +# Maintenance + +You can perform maintenance for Besu on a Kubernetes cluster. + +## Prerequisites + +- Clone the [Quorum-Kubernetes](https://github.com/ConsenSys/quorum-kubernetes) repository +- A [running Kubernetes cluster](cluster.md) with a [network](charts.md) +- Install [Kubectl](https://kubernetes.io/docs/tasks/tools/) +- Install [Helm3](https://helm.sh/docs/intro/install/) + +## Update a persistent volume claim size + +Over time, as the chain grows, so will the amount of space used by the persistent volume claim (PVC). As of Kubernetes v1.11, [certain types of Storage Classes](https://kubernetes.io/docs/concepts/storage/storage-classes/#allow-volume-expansion) allow volume resizing. Production charts for Azure use Azure Files, and on AWS use EBS Block Store which allow for volume expansion. + +To update the volume size, you must update the override values file. For example, to increase the size on the transaction nodes volumes, add the following snippet to the [`txnode values.yml`](https://github.com/ConsenSys/quorum-kubernetes/blob/5920caff6dd15b4ca17f760ad9e4d7d2e43b41a1/helm/values/txnode.yml) file, with the new size limit (the following example uses 50Gi). + +```bash +storage: + sizeLimit: "50Gi" + pvcSizeLimit: "50Gi" +``` + +Once complete, update the node via helm: + +```bash +helm upgrade tx-1 ./charts/besu-node --namespace besu --values ./values/txnode.yml +``` + +## Update Besu versions + +:::important + +When updating Besu nodes across a cluster, perform the updates as a rolling update and not all at once, especially for the validator pool. If all the validators are taken offline, the chain halts, and you must wait for round changes to expire before blocks are created again. + +::: + +Updates for Besu can be done via Helm in exactly the same manner as other applications. Alternatively, this can be done via `kubectl`. This example updates a node called `besu-validator-3`: + +1. Set the update policy to use rolling updates (if not done already): + + ```bash + kubectl patch statefulset besu-validator-3 --namespace besu -p '{"spec":{"updateStrategy":{"type":"RollingUpdate"}}}' + ``` + +2. Update the Besu version via Helm: + + ```bash + helm upgrade bootnode-1 ./charts/besu-node --namespace besu --values ./values/bootnode.yml --set image.besu.tag=21.10.0 + ``` + + Or via `kubectl`: + + ```bash + kubectl patch statefulset besu-validator-3 --namespace besu --type='json' -p='[{"op": "replace", "path": "/spec/template/spec/containers/0/image", "value":"hyperledger/besu:21.10.0"}]' + ``` diff --git a/versioned_docs/version-23.10.1/private-networks/tutorials/kubernetes/nat-manager.md b/versioned_docs/version-23.10.1/private-networks/tutorials/kubernetes/nat-manager.md new file mode 100644 index 00000000000..5a66ede1f48 --- /dev/null +++ b/versioned_docs/version-23.10.1/private-networks/tutorials/kubernetes/nat-manager.md @@ -0,0 +1,221 @@ +--- +title: Configure Kubernetes mode in NAT manager +sidebar_position: 9 +description: Tutorial to configure Kubernetes mode for Hyperledger Besu Nat Manager +tags: + - private networks +--- + +# Configure Kubernetes mode in NAT Manager + +Use [`--nat-method=AUTO`](../../../public-networks/how-to/connect/specify-nat.md#auto) or [`--nat-method=KUBERNETES`](../../../public-networks/how-to/connect/specify-nat.md#kubernetes) CLI options to let the Besu node automatically configure its IP address and ports. + +Use mode [`--nat-method=NONE`](../../../public-networks/how-to/connect/specify-nat.md#none) to be able to set your Besu ports and IP address manually. + +Default mode is [`AUTO`](../../../public-networks/how-to/connect/specify-nat.md#auto) but Besu will fallback to [`NONE`](../../../public-networks/how-to/connect/specify-nat.md#none) mode if automatic configuration fails. + +:::info The following log shows fallback to [`NONE`](../../../public-networks/how-to/connect/specify-nat.md#none) mode after an automatic detection failure. + + ``` + INFO | KubernetesNatManager | Starting kubernetes NAT manager. + DEBUG | KubernetesNatManager | Trying to update information using Kubernetes client SDK. + DEBUG | NatService | Nat manager failed to configure itself automatically due to the following reason Service not found. NONE mode will be used + INFO | NetworkRunner | Starting Network. + ``` + +::: + +## Automatic configuration + +Follow 3 steps to configure Besu for automatic IP address and ports detection on Kubernetes: + +1. [Create a load balancer](#1-create-a-load-balancer) +1. [Check if the load balancer is properly deployed](#2-check-if-the-load-balancer-is-properly-deployed) +1. [Deploy Besu](#3-deploy-besu) + +### 1. Create a load balancer + +Deploy a `LoadBalancer` service for Besu to recover IP address and ports. + +Here is an example that you can customize with your own ports and routing rules. + +```yaml +--- +apiVersion: v1 +kind: Service +metadata: + labels: + app.kubernetes.io/name: besu + app.kubernetes.io/release: "1.0.0" + name: besu +spec: + ports: + - name: "json-rpc" + port: 8545 + targetPort: 8545 + - name: "rlpx" + port: 30303 + targetPort: 30303 + selector: + app.kubernetes.io/name: besu + app.kubernetes.io/release: "1.0.0" + type: LoadBalancer +``` + +This service example lists the rules for the different ports used by Besu (`json-rpc` and` rlpx`). The default value is used for `discovery`. + +### 2. Check if the load balancer is properly deployed + +Verify the load balancer readiness before launching Besu. + +Run `kubectl describe services besu` to check the service status. + +The command should display the following information: + +```bash +Name: besu +Namespace: default +Labels: app.kubernetes.io/name=besu + app.kubernetes.io/release=1.0.0 +Annotations: kubectl.kubernetes.io/last-applied-configuration: + {"apiVersion":"v1","kind":"Service","metadata":{"annotations":{},"labels":{"app.kubernetes.io/name":"besu","app.kubernetes.io/release":"1.... +Selector: app.kubernetes.io/name=besu,app.kubernetes.io/release=1.0.0 +Type: LoadBalancer +IP: -------- +LoadBalancer Ingress: ****** +``` + +The load balancer must have an IP address displayed in place of `******` on the `LoadBalancer Ingress` line to be ready. + +Run the `kubectl describe services besu` command again until the load balancer IP address appears in the output. + +### 3. Deploy Besu + +When steps 1 and 2 are completed, deploy Besu using the following YAML example: + +```yaml +--- +apiVersion: v1 +kind: ConfigMap +metadata: + name: besu-config + labels: + app.kubernetes.io/name: besu + app.kubernetes.io/release: 1.0.0 +data: + BESU_LOGGING: "INFO" + BESU_NETWORK: "dev" + BESU_P2P_ENABLED: "true" + BESU_RPC_HTTP_ENABLED: "true" + BESU_RPC_HTTP_APIS: "eth,net,web3,debug,admin" + KUBE_CONFIG_PATH: "/opt/besu/shared/kube-config" +--- +apiVersion: extensions/v1beta1 +kind: Deployment +metadata: + name: besu + labels: + app.kubernetes.io/name: besu + app.kubernetes.io/release: "1.0.0" +spec: + replicas: 1 + strategy: {} + template: + metadata: + creationTimestamp: null + labels: + app.kubernetes.io/name: besu + app.kubernetes.io/release: "1.0.0" + spec: + containers: + - name: besu + image: "hyperledger/besu:latest" + imagePullPolicy: Always + ports: + - containerPort: 8545 + - containerPort: 30303 + envFrom: + - configMapRef: + name: besu-config + restartPolicy: Always +status: {} +``` + +## Automatic detection errors + +:::danger + +Automatic detection error messages do not prevent you to use Besu. + +Try the fix indicated for each error or use [`--nat-method=KUBERNETES`](../../../public-networks/how-to/connect/specify-nat.md#kubernetes) CLI option and [set IP address and port manually](../../../public-networks/how-to/connect/configure-ports.md). + +::: + +Possible errors messages for Kubernetes automatic detection failure: + +- [`Service not found`](#service-not-found-error-message) +- [`Forbidden`](#forbidden-error-message) +- [`Ingress not found`](#ingress-not-found-error-message) + +### `Service not found` error message + +- **Error message:** `Nat manager failed to configure itself automatically due to the following reason Service not found. NONE mode will be used` +- **Cause:** load balancer did start correctly or has the incorrect name. +- **Fix:** check and modify load balancer YAML configuration and restart service. + +:::info Example error log + + ``` + INFO | KubernetesNatManager | Starting kubernetes NAT manager. + DEBUG | KubernetesNatManager | Trying to update information using Kubernetes client SDK. + DEBUG | NatService | Nat manager failed to configure itself automatically due to the following reason Service not found. NONE mode will be used + INFO | NetworkRunner | Starting Network. + ``` + +::: + +### `Forbidden` error message + +- **Error message:** `Nat manager failed to configure itself automatically due to the following reason Forbidden. NONE mode will be used` +- **Cause:** Besu don't have permission to list the services via the Kubernetes API to retrieve IP address and ports from the load balancer. +- **Fix:** Give it the required permissions using [Role-based access control](https://kubernetes.io/docs/reference/access-authn-authz/rbac/). + + If you can't manage permissions, define the IP address and ports manually with [`NONE`](../../../public-networks/how-to/connect/specify-nat.md#none) mode + +:::info Example error log + + ``` + INFO | KubernetesNatManager | Starting kubernetes NAT manager. + DEBUG | KubernetesNatManager | Trying to update information using Kubernetes client SDK. + DEBUG | NatService | Nat manager failed to configure itself automatically due to the following reason Forbidden. NONE mode will be used + INFO | NetworkRunner | Starting Network. + ``` + +::: + +:::tip + +For development environment, the permission issue can be fixed by running `kubectl create clusterrolebinding myapp-view-binding --clusterrole=admin --serviceaccount=default:default` + +This command should only be used on development environment and not in production environment. + +In production environment, require a finer management of permissions using Kubernetes [Role-based access control](https://kubernetes.io/docs/reference/access-authn-authz/rbac/). + +::: + +### `Ingress not found` error message + +- **Error message:** `Nat manager failed to configure itself automatically due to the following reason Ingress not found. NONE mode will be used` +- **Cause:** Load balancer did not finish to recover an IP address. +- **Fix:** [Check that the load balancer is properly deployed](#2-check-if-the-load-balancer-is-properly-deployed) before launching Besu. + +:::info Example error log + + ``` + INFO | KubernetesNatManager | Starting kubernetes NAT manager. + DEBUG | KubernetesNatManager | Trying to update information using Kubernetes client SDK. + DEBUG | NatService | Nat manager failed to configure itself automatically due to the following reason Ingress not found. NONE mode will be used + INFO | NetworkRunner | Starting Network. + ``` + +::: diff --git a/versioned_docs/version-23.10.1/private-networks/tutorials/kubernetes/playground.md b/versioned_docs/version-23.10.1/private-networks/tutorials/kubernetes/playground.md new file mode 100644 index 00000000000..67962456a62 --- /dev/null +++ b/versioned_docs/version-23.10.1/private-networks/tutorials/kubernetes/playground.md @@ -0,0 +1,28 @@ +--- +title: Local playground +sidebar_position: 1 +description: Deploying a Hyperledger Besu private network locally with Kubernetes +tags: + - private networks +--- + +# Deploy in a local environment + +The [playground](https://github.com/ConsenSys/quorum-kubernetes/tree/master/playground) was created to provide an opportunity to deploy [quorum-kubernetes](https://github.com/ConsenSys/quorum-kubernetes/) in a local environment before attempting in a live environment (such as in the cloud or on-premise). Local deployment can be done with any local Kubernetes tool. Minikube and Rancher Desktop have been tested to work, but any complete Kubernetes solution with support for `kubectl` should suffice. + +## Steps + +1. Navigate to the playground [`README`](https://github.com/ConsenSys/quorum-kubernetes/tree/master/playground). +1. Ensure that your system meets the requirements specified. +1. Choose your Ethereum client (Hyperledger Besu or GoQuorum): `quorum-besu` or `quorum-go`. +1. Choose your consensus algorithm. The playground supports Clique, Ethash (PoW), and IBFT2 for Besu, and IBFT for GoQuorum. +1. Follow the instructions from the `README` for the chosen client and consensus algorithm folder. + +## Important notes + +Consider the following when deploying and developing with the playground: + +- The playground is created specifically for developers and operators to become familiar with the deployment of Besu in a Kubernetes environment in preparation for going into a cloud or on-premise environment. Thus, it should **not** be deployed into a production environment. +- The playground is not a complete reflection of the `helm` charts as it does not use `Helm`, but rather static or non-templated code that is deployed through `kubectl apply -f`. This means that without `Helm` there's a significant amount of repeated code. This is fine for development but not ideal for a production environment. +- The playground uses static/hard-coded keys. Automatic key generation is only supported in `helm` charts. +- As the playground is for local development, no cloud integration or lifecycle support is offered. diff --git a/versioned_docs/version-23.10.1/private-networks/tutorials/kubernetes/production.md b/versioned_docs/version-23.10.1/private-networks/tutorials/kubernetes/production.md new file mode 100644 index 00000000000..a9cd60d9da3 --- /dev/null +++ b/versioned_docs/version-23.10.1/private-networks/tutorials/kubernetes/production.md @@ -0,0 +1,89 @@ +--- +title: Production +sidebar_position: 6 +description: Deploying Besu Helm Charts for production on a Kubernetes cluster +tags: + - private networks +--- + +# Deploy for production + +You can deploy Besu for production on a Kubernetes cluster. + +## Prerequisites + +- Clone the [Quorum-Kubernetes](https://github.com/ConsenSys/quorum-kubernetes) repository +- A [running Kubernetes cluster](cluster.md) +- [Kubectl](https://kubernetes.io/docs/tasks/tools/) +- [Helm3](https://helm.sh/docs/intro/install/) + +## Overview + +To get things production-ready, we'll use the same charts, and set a few of the values in the `cluster` map as in the [Deploy](#deploy-the-network) section. + +:::warning + +The following tutorial ONLY supports AWS and Azure currently. Other cloud providers will be added in time. + +::: + +:::warning + +We recommend using AWS RDS or Azure PostgreSQL in High Availability mode for any Tessera nodes that you use. The templates don't include that functionality. They can be provisioned with CloudFormation or Azure Resource Manager, respectively. Once created, please specify the connection details to the `values.yml`. + +::: + +## Deploy + +### Check that you can connect to the cluster with `kubectl` + +Once you have a [cluster running](cluster.md), verify `kubectl` is connected to cluster with: + +```bash +kubectl version +Client Version: version.Info{Major:"1", Minor:"23", GitVersion:"v1.23.1", GitCommit:"86ec240af8cbd1b60bcc4c03c20da9b98005b92e", GitTreeState:"clean", BuildDate:"2021-12-16T11:41:01Z", GoVersion:"go1.17.5", Compiler:"gc", Platform:"linux/amd64"} +Server Version: version.Info{Major:"1", Minor:"22", GitVersion:"v1.22.3", GitCommit:"c92036820499fedefec0f847e2054d824aea6cd1", GitTreeState:"clean", BuildDate:"2021-10-27T18:35:25Z", GoVersion:"go1.16.9", Compiler:"gc", Platform:"linux/amd64"} +``` + +### Deploy the network + +For the rest of this tutorial we use Helm charts. After you have cloned the [Quorum-Kubernetes](https://github.com/ConsenSys/quorum-kubernetes) repository, change the directory to `helm` for the rest of this tutorial. + +```bash +cd helm +``` + +Each helm chart has the following keys that must be set. + +Specify either `aws` or `azure` for the `cluster.provider`. Additionally, set `cloudNativeServices: true` and `reclaimPolicy: Retain` so that it looks like the following for AWS: + +```bash +cluster: + provider: aws # choose from: aws | azure + cloudNativeServices: true # set to true to use Cloud Native Services (SecretsManager and IAM for AWS; KeyVault & Managed Identities for Azure) + reclaimPolicy: Retain # set to either Retain or Delete; note that PVCs and PVs will still exist after a 'helm delete'. Setting to Retain will keep volumes even if PVCs/PVs are deleted in kubernetes. Setting to Delete will remove volumes from EC2 EBS when PVC is deleted +``` + +Follow the steps outlined in the [deploy charts](charts.md) tutorial to deploy the network. + +## Best practices + +The most important thing is to plan your network out on paper first and then test it in a Dev cluster to make sure connectivity works with your applications and you get the required throughput in transactions per second (TPS). We also recommend you test the entire process, from provisioning infrastructure to updating nodes on a Dev cluster, prior to launching your production network. + +By default, the cloud Kubernetes clusters take care of availability and do multi-zones within a region. The scheduler also ensures that deployments are spread out across zones. Where possible, we recommend you use multiple bootnodes and static nodes to speed up peering. + +You can connect to APIs and services outside the cluster normally, but connecting into your network (such as adding an on-premise node to the network) might require more configuration. Please check the [limitations](index.md#limitations) and use CNI where possible. To connect an external node to your cluster, the easiest way is to use a VPN as seen in the following [multi-cluster](#multi-cluster-support) setup. + +Finally, we recommend setting up monitoring and alerting from the beginning, so you can get early warnings of issues rather than after failure. We have a monitoring chart which uses Grafana and you can use it with Alertmanager to create alerts or alternatively alert via Cloudwatch or Azure Monitoring. + +## Multi-cluster support + +When CNI is used, multi-cluster support is simple, but you have to cater for cross-cluster DNS names. Ideally, you want to create two separate VPCs (or VNets) and make sure they have different base CIDR blocks so that IP addresses don't conflict. Once done, peer the VPCs together and update the subnet route table, so they are effectively a giant single network. + +![multi-cluster](../../../assets/images/kubernetes-3.png) + +When you [spin up clusters](cluster.md), use [CNI](index.md#limitations) and CIDR blocks to match the subnet's CIDR settings. Then deploy the genesis chart on one cluster and copy across the genesis file and static nodes config maps. Depending on your DNS settings, they might be fine as is, or they might need to be actual IP addresses. That is, you can provision cluster B only after cluster A has Besu nodes up and running. + +Deploy the network on cluster A, and then on cluster B. Besu nodes on cluster A should work as expected, and Besu nodes on cluster B should use the list of peers provided to communicate with the nodes on cluster A. + +Keeping the list of peers on the clusters live and up to date can be challenging, so we recommend using the cloud service provider's DNS service such as Route 53 or Azure DNS and adapting the charts to create entries for each node when it comes up. diff --git a/versioned_docs/version-23.10.1/private-networks/tutorials/kubernetes/quorum-explorer.md b/versioned_docs/version-23.10.1/private-networks/tutorials/kubernetes/quorum-explorer.md new file mode 100644 index 00000000000..cd69831c806 --- /dev/null +++ b/versioned_docs/version-23.10.1/private-networks/tutorials/kubernetes/quorum-explorer.md @@ -0,0 +1,69 @@ +--- +title: Using the Quorum Explorer +sidebar_position: 4 +description: Using the Quorum Explorer on a Kubernetes cluster +tags: + - private networks +--- + +# Use the Quorum Explorer + +You can use the Quorum Explorer on a Kubernetes cluster. + +## Prerequisites + +- Clone the [Quorum-Kubernetes](https://github.com/ConsenSys/quorum-kubernetes) repository +- A [running Kubernetes cluster](cluster.md) +- [Kubectl](https://kubernetes.io/docs/tasks/tools/) +- [Helm3](https://helm.sh/docs/intro/install/) +- [Existing network](charts.md) + +## Deploy the Quorum Explorer helm chart + +[Quorum-Explorer](https://github.com/ConsenSys/quorum-explorer) as a lightweight blockchain explorer. The Quorum Explorer is **not** recommended for use in production and is intended for demonstration or development purposes only. + +The explorer can provide an overview over the whole network, such as block information, voting or removing validators from the network, and demonstrates using the `SimpleStorage` smart contract with privacy enabled, and sending transactions between wallets in one interface. + +To use the explorer, update the [Quorum-Explorer values file](https://github.com/ConsenSys/quorum-kubernetes/blob/5920caff6dd15b4ca17f760ad9e4d7d2e43b41a1/helm/values/explorer-besu.yaml) with your node details and endpoints, and then [deploy](charts.md). + +## Nodes + +The **Nodes** page provides an overview of the nodes on the network. Select the node you would like to interact with from the drop-down on the top right, and you'll get details of the node, block height, peers, queued transactions etc. + +![`k8s-explorer`](../../../assets/images/kubernetes-explorer.png) + +## Validators + +The **Validators** page simulates a production environment or consortium where each node individually runs API calls to vote to add a validator or remove an existing validator. + +When using the buttons to remove, discard pending validators, or proposing a validator, the app sends an API request to the selected node in the drop-down only. To add or remove a validator you need to select a majority of the existing validator pool individually, and perform the vote API call by clicking the button. Each node can call a discard on the voting process during or after the validator has been added. + +The vote calls made from non-validator nodes have no effect on overall consensus. + +![`k8s-explorer-validators`](../../../assets/images/kubernetes-explorer-validators.png) + +## Explorer + +The **Explorer** page gives you the latest blocks from the chain and the latest transactions as they occur on the network. In addition, you can search by block number or transaction hash using the respective search bar. + +![`k8s-explorer-explorer`](../../../assets/images/kubernetes-explorer-explorer.png) + +## Contracts + +Use the **Contracts** page to compile and deploy a smart contract. Currently, the only contract available for deployment through the app is the `SimpleStorage` contract. However, in time, we plan to add more contracts to that view. + +In this example, we deploy from `member-1` and select `member-1` and `member-3` in the **Private For** multi-select. Then click on `Compile` and `Deploy` + +![`k8s-explorer-contracts-1`](../../../assets/images/kubernetes-explorer-contracts-1.png) + +Once deployed, you can interact with the contract. As this is a new transaction, select `member-1` and `member-3` in **Interact** multi-select, and then click on the appropriate method call to `get` or `set` the value at the deployed contract address. + +![`k8s-explorer-contracts-set`](../../../assets/images/kubernetes-explorer-contracts-set.png) + +To test the private transaction functionality, select `member-2` from the drop-down on the top right, you'll notice that you are unable to interact with the contract because `member-2` was not part of the transaction. Only `members-1` and `member-3` responds correctly. + +## Wallet + +The **Wallet** page gives you the functionality to send simple ETH transactions between accounts by providing the account's private key, the recipient's address, and transfer amount in Wei. + +![`k8s-explorer-wallet`](../../../assets/images/kubernetes-explorer-wallet.png) diff --git a/versioned_docs/version-23.10.1/private-networks/tutorials/permissioning/_category_.json b/versioned_docs/version-23.10.1/private-networks/tutorials/permissioning/_category_.json new file mode 100644 index 00000000000..da14c12d4b3 --- /dev/null +++ b/versioned_docs/version-23.10.1/private-networks/tutorials/permissioning/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Create a permissioned network", + "position": 7 +} diff --git a/versioned_docs/version-23.10.1/private-networks/tutorials/permissioning/index.md b/versioned_docs/version-23.10.1/private-networks/tutorials/permissioning/index.md new file mode 100644 index 00000000000..054469e436d --- /dev/null +++ b/versioned_docs/version-23.10.1/private-networks/tutorials/permissioning/index.md @@ -0,0 +1,497 @@ +--- +title: Create a permissioned network +sidebar_position: 1 +description: Hyperledger Besu create a permissioned network +tags: + - private networks +--- + +# Create a permissioned network + +The following steps set up a permissioned network with local node and account permissions. The network uses the [IBFT 2.0 proof of authority consensus protocol]. + +:::danger + +A permissioned Ethereum network as described here is not protected against all attack vectors. We recommend applying defense in depth to protect your infrastructure. + +::: + +## Prerequisites + +- [Hyperledger Besu](../../get-started/install/binary-distribution.md) +- [curl (or similar Web service client)](https://curl.haxx.se/download.html) + +## Steps + +### 1. Create folders + +Each node requires a data directory for the blockchain data. + +Create directories for your permissioned network and each of the three nodes, and a data directory for each node: + +```bash +Permissioned-Network/ +├── Node-1 +│   ├── data +├── Node-2 +│   ├── data +└── Node-3 +│   ├── data +└── Node-4 + ├── data +``` + +### 2. Create the configuration file + +The configuration file defines the [IBFT 2.0 genesis file](../../how-to/configure/consensus/ibft.md#genesis-file) and the number of node key pairs to generate. + +The configuration file has two nested JSON nodes. The first is the `genesis` property defining the IBFT 2.0 genesis file, except for the `extraData` string, which Besu generates automatically in the resulting genesis file. The second is the `blockchain` property defining the number of key pairs to generate. + +Copy the following configuration file definition to a file called `ibftConfigFile.json` and save it in the `Permissioned-Network` directory: + +```json +{ + "genesis": { + "config": { + "chainId": 1337, + "berlinBlock": 0, + "ibft2": { + "blockperiodseconds": 2, + "epochlength": 30000, + "requesttimeoutseconds": 4 + } + }, + "nonce": "0x0", + "timestamp": "0x58ee40ba", + "gasLimit": "0x47b760", + "difficulty": "0x1", + "mixHash": "0x63746963616c2062797a616e74696e65206661756c7420746f6c6572616e6365", + "coinbase": "0x0000000000000000000000000000000000000000", + "alloc": { + "fe3b557e8fb62b89f4916b721be55ceb828dbd73": { + "privateKey": "8f2a55949038a9610f50fb23b5883af3b4ecb3c3bb792cbcefbd1542c692be63", + "comment": "private key and this comment are ignored. In a real chain, the private key should NOT be stored", + "balance": "0xad78ebc5ac6200000" + }, + "627306090abaB3A6e1400e9345bC60c78a8BEf57": { + "privateKey": "c87509a1c067bbde78beb793e6fa76530b6382a4c0241e5e4a9ec0a0f44dc0d3", + "comment": "private key and this comment are ignored. In a real chain, the private key should NOT be stored", + "balance": "90000000000000000000000" + }, + "f17f52151EbEF6C7334FAD080c5704D77216b732": { + "privateKey": "ae6ae8e5ccbfb04590405997ee2d52d2b330726137b875053c36d94e974d162f", + "comment": "private key and this comment are ignored. In a real chain, the private key should NOT be stored", + "balance": "90000000000000000000000" + } + } + }, + "blockchain": { + "nodes": { + "generate": true, + "count": 4 + } + } +} +``` + +:::danger Security warning + +Don't use the accounts in the genesis file on Mainnet or any public network except for testing. The private keys display, which means the accounts are not secure. + +::: + +### 3. Generate node keys and a genesis file + +In the `Permissioned-Network` directory, generate the node key and genesis file: + +```bash +besu operator generate-blockchain-config --config-file=ibftConfigFile.json --to=networkFiles --private-key-file-name=key +``` + +Besu creates the following in the `networkFiles` directory: + +- `genesis.json` - The genesis file including the `extraData` property specifying the four nodes are validators. +- A directory for each node named using the node address and containing the public and private key for each node. + +```bash +networkFiles/ +├── genesis.json +└── keys + ├── 0x438821c42b812fecdcea7fe8235806a412712fc0 + │   ├── key + │   └── key.pub + ├── 0xca9c2dfa62f4589827c0dd7dcf48259aa29f22f5 + │   ├── key + │   └── key.pub + ├── 0xcd5629bd37155608a0c9b28c4fd19310d53b3184 + │   ├── key + │   └── key.pub + └── 0xe96825c5ab8d145b9eeca1aba7ea3695e034911a + ├── key + └── key.pub +``` + +### 4. Copy the genesis file to the Permissioned-Network directory + +Copy the `genesis.json` file to the `Permisssioned-Network` directory. + +### 5. Copy the node private keys to the node directories + +For each node, copy the key files to the `data` directory for that node + +```bash +Permissioned-Network/ +├── genesis.json +├── Node-1 +│   ├── data +│ │    ├── key +│ │    ├── key.pub +├── Node-2 +│   ├── data +│ │    ├── key +│ │    ├── key.pub +├── Node-3 +│   ├── data +│ │    ├── key +│ │    ├── key.pub +├── Node-4 +│ ├── data +│ │    ├── key +│ │    ├── key.pub +``` + +### 6. Create the permissions configuration file + +The [permissions configuration file](../../how-to/use-permissioning/local.md#permissions-configuration-file) defines the nodes and accounts allowlists. + +Copy the following permissions configuration to a file called `permissions_config.toml` and save a copy in the `Node-1/data`, `Node-2/data`, `Node-3/data`, and `Node-4/data` directories: + +```toml title="permissions_config.toml" +accounts-allowlist=["0xfe3b557e8fb62b89f4916b721be55ceb828dbd73", "0x627306090abaB3A6e1400e9345bC60c78a8BEf57"] + +nodes-allowlist=[] +``` + +The permissions configuration file includes the first two accounts from the genesis file. + +Use the [`perm_addNodesToAllowlist`](../../reference/api/index.md#perm_addnodestoallowlist) JSON-RPC API method to add permissioned nodes after starting the nodes. + +### 7. Start Node-1 + +Use the following command: + + + +# MacOS + +```bash +besu --data-path=data --genesis-file=../genesis.json --permissions-nodes-config-file-enabled --permissions-accounts-config-file-enabled --rpc-http-enabled --rpc-http-api=ADMIN,ETH,NET,PERM,IBFT --host-allowlist="*" --rpc-http-cors-origins="*" +``` + +# Windows + +```bash +besu --data-path=data --genesis-file=..\genesis.json --permissions-nodes-config-file-enabled --permissions-accounts-config-file-enabled --rpc-http-enabled --rpc-http-api=ADMIN,ETH,NET,PERM,IBFT --host-allowlist="*" --rpc-http-cors-origins="*" +``` + + + +The command line allows you to enable: + +- Nodes and accounts permissions using [`--permissions-nodes-config-file-enabled`](../../reference/cli/options.md#permissions-nodes-config-file-enabled) and [`--permissions-accounts-config-file-enabled`](../../reference/cli/options.md#permissions-accounts-config-file-enabled). +- The JSON-RPC API using [`--rpc-http-enabled`](../../../public-networks/reference/cli/options.md#rpc-http-enabled). +- The `ADMIN`, `ETH`, `NET`, `PERM`, and `IBFT` APIs using [`--rpc-http-api`](../../../public-networks/reference/cli/options.md#rpc-http-api). +- All-host access to the HTTP JSON-RPC API using [`--host-allowlist`](../../../public-networks/reference/cli/options.md#host-allowlist). +- All-domain access to the node through the HTTP JSON-RPC API using [`--rpc-http-cors-origins`](../../../public-networks/reference/cli/options.md#rpc-http-cors-origins). + +When the node starts, the [enode URL](../../../public-networks/concepts/node-keys.md#enode-url) displays. You need the enode URL to specify Node-1 as a peer and update the permissions configuration file in the following steps. + +![Node 1 Enode URL](../../../assets/images/EnodeStartup.png) + +### 8. Start Node-2 + +Start another terminal, change to the `Node-2` directory, and start Node-2: + + + +# MacOS + +```bash +besu --data-path=data --genesis-file=../genesis.json --permissions-nodes-config-file-enabled --permissions-accounts-config-file-enabled --rpc-http-enabled --rpc-http-api=ADMIN,ETH,NET,PERM,IBFT --host-allowlist="*" --rpc-http-cors-origins="*" --p2p-port=30304 --rpc-http-port=8546 +``` + +# Windows + +```bash +besu --data-path=data --genesis-file=..\genesis.json --permissions-nodes-config-file-enabled --permissions-accounts-config-file-enabled --rpc-http-enabled --rpc-http-api=ADMIN,ETH,NET,PERM,IBFT --host-allowlist="*" --rpc-http-cors-origins="*" --p2p-port=30304 --rpc-http-port=8546 +``` + + + +The command line specifies: + +- A different port to Node-1 for P2P discovery using [`--p2p-port`](../../../public-networks/reference/cli/options.md#p2p-port). +- A different port to Node-1 for HTTP JSON-RPC using [`--rpc-http-port`](../../../public-networks/reference/cli/options.md#rpc-http-port). +- A data directory for Node-2 using [`--data-path`](../../../public-networks/reference/cli/options.md#data-path). +- Other options as for [Node-1](#7-start-node-1). + +When the node starts, the [enode URL](../../../public-networks/concepts/node-keys.md#enode-url) displays. You need the enode URL to update the permissions configuration file in the following steps. + +### 9. Start Node-3 + +Start another terminal, change to the `Node-3` directory, and start Node-3: + + + +# MacOS + +```bash +besu --data-path=data --genesis-file=../genesis.json --permissions-nodes-config-file-enabled --permissions-accounts-config-file-enabled --rpc-http-enabled --rpc-http-api=ADMIN,ETH,NET,PERM,IBFT --host-allowlist="*" --rpc-http-cors-origins="*" --p2p-port=30305 --rpc-http-port=8547 +``` + +# Windows + +```bash +besu --data-path=data --genesis-file=..\genesis.json --permissions-nodes-config-file-enabled --permissions-accounts-config-file-enabled --rpc-http-enabled --rpc-http-api=ADMIN,ETH,NET,PERM,IBFT --host-allowlist="*" --rpc-http-cors-origins="*" --p2p-port=30305 --rpc-http-port=8547 +``` + + + +The command line specifies: + +- A different port to Node-1 and Node-2 for P2P discovery using [`--p2p-port`](../../../public-networks/reference/cli/options.md#p2p-port). +- A different port to Node-1 and Node-2 for HTTP JSON-RPC using [`--rpc-http-port`](../../../public-networks/reference/cli/options.md#rpc-http-port). +- A data directory for Node-3 using [`--data-path`](../../../public-networks/reference/cli/options.md#data-path). +- Other options as for [Node-1](#7-start-node-1). + +When the node starts, the [enode URL](../../../public-networks/concepts/node-keys.md#enode-url) displays. You need the enode URL to update the permissions configuration file in the following steps. + +### 10. Start Node-4 + +Start another terminal, change to the `Node-4` directory, and start Node-4: + + + +# MacOS + +```bash +besu --data-path=data --genesis-file=../genesis.json --permissions-nodes-config-file-enabled --permissions-accounts-config-file-enabled --rpc-http-enabled --rpc-http-api=ADMIN,ETH,NET,PERM,IBFT --host-allowlist="*" --rpc-http-cors-origins="*" --p2p-port=30306 --rpc-http-port=8548 +``` + +# Windows + +```bash +besu --data-path=data --genesis-file=..\genesis.json --permissions-nodes-config-file-enabled --permissions-accounts-config-file-enabled --rpc-http-enabled --rpc-http-api=ADMIN,ETH,NET,PERM,IBFT --host-allowlist="*" --rpc-http-cors-origins="*" --p2p-port=30306 --rpc-http-port=8548 +``` + + + +The command line specifies: + +- A different port to Node-1, Node-2, and Node-3 for P2P discovery using [`--p2p-port`](../../../public-networks/reference/cli/options.md#p2p-port). +- A different port to Node-1, Node-2, and Node-3 for HTTP JSON-RPC using [`--rpc-http-port`](../../../public-networks/reference/cli/options.md#rpc-http-port). +- A data directory for Node-4 using [`--data-path`](../../../public-networks/reference/cli/options.md#data-path). +- Other options as for [Node-1](#7-start-node-1). + +When the node starts, the [enode URL](../../../public-networks/concepts/node-keys.md#enode-url) displays. You need the enode URL to update the permissions configuration file in the following steps. + +### 11. Add enode URLs for nodes to permissions configuration file + +Start another terminal and use the [`perm_addNodesToAllowlist`](../../reference/api/index.md#perm_addnodestoallowlist) JSON-RPC API method to add the nodes to the permissions configuration file for each node. + +Replace ``, ``, ``, and `` with the enode URL displayed when starting each node. + + + +# Node-1 + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"perm_addNodesToAllowlist","params":[["","","","EnodeNode4"]], "id":1}' http://127.0.0.1:8545 +``` + +# Node-2 + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"perm_addNodesToAllowlist","params":[["","","","EnodeNode4"]], "id":1}' http://127.0.0.1:8546 +``` + +# Node-3 + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"perm_addNodesToAllowlist","params":[["","","","EnodeNode4"]], "id":1}' http://127.0.0.1:8547 +``` + +# Node-4 + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"perm_addNodesToAllowlist","params":[["","","","EnodeNode4"]], "id":1}' http://127.0.0.1:8548 +``` + + + +:::tip + +The curl call is the same for each node except for the JSON-RPC endpoint. + +::: + +### 12. Add nodes as peers + +Use the [`admin_addPeer`](../../../public-networks/reference/api/index.md#admin_addpeer) JSON-RPC API method to add Node-1 as a peer for Node-2, Node-3, and Node-4. + +Replace `` with the enode URL displayed when starting Node-1. + + + +# Node-2 + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"admin_addPeer","params":[""],"id":1}' http://127.0.0.1:8546 +``` + +# Node-3 + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"admin_addPeer","params":[""],"id":1}' http://127.0.0.1:8547 +``` + +# Node-4 + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"admin_addPeer","params":[""],"id":1}' http://127.0.0.1:8548 +``` + + + +:::tip + +The curl call is the same for each node except for the JSON-RPC endpoint. + +::: + +Replace `` with the enode URL displayed when starting Node-2. + + + +# Node-3 + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"admin_addPeer","params":[""],"id":1}' http://127.0.0.1:8547 +``` + +# Node-4 + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"admin_addPeer","params":[""],"id":1}' http://127.0.0.1:8548 +``` + + + +Replace `` with the enode URL displayed when starting Node-3. + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"admin_addPeer","params":[""],"id":1}' http://127.0.0.1:8548 +``` + +### 13. Confirm permissioned network is working + +#### Check peer count + +Use curl to call the JSON-RPC API [`net_peerCount`](../../../public-networks/reference/api/index.md#net_peercount) method and confirm the nodes are functioning as peers: + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"net_peerCount","params":[],"id":1}' localhost:8545 +``` + +The result confirms Node-1 (the node running the JSON-RPC service) has three peers (Node-2, Node-3 and Node-4): + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": "0x3" +} +``` + +#### Send a transaction from an account in the allowlist + +Import the first account from the genesis file into MetaMask and send transactions, as described in [Quickstart tutorial]: + +:::info Account 1 + +- Address: `0xfe3b557e8fb62b89f4916b721be55ceb828dbd73` +- Private key : `0x8f2a55949038a9610f50fb23b5883af3b4ecb3c3bb792cbcefbd1542c692be63` +- Initial balance : `0xad78ebc5ac6200000` (200000000000000000000 in decimal) + +::: + +:::info + +Besu doesn't support [private key management](../../../public-networks/how-to/send-transactions.md). + +::: + +### Try sending a transaction from an account not in the accounts allowlist + +Import the third account from the genesis file into MetaMask and try to send a transaction, as described in [Quickstart tutorial]: + +:::info Account 3 + +- Address: `0xf17f52151EbEF6C7334FAD080c5704D77216b732` +- Private key: `0xae6ae8e5ccbfb04590405997ee2d52d2b330726137b875053c36d94e974d162f` +- Initial balance: `0x90000000000000000000000` (2785365088392105618523029504 in decimal) + +::: + +### Start a node not on the nodes allowlist + +In your `Permissioned-Network` directory, create a `Node-5` directory and `data` directory inside it. + +Change to the `Node-5` directory and start Node-5 specifying the Node-1 enode URL as the bootnode: + + + +# MacOS + +```bash +besu --data-path=data --bootnodes="" --genesis-file=../genesis.json --rpc-http-enabled --rpc-http-api=ADMIN,ETH,NET,PERM,IBFT --host-allowlist="*" --rpc-http-cors-origins="*" --p2p-port=30307 --rpc-http-port=8549 +``` + +# Windows + +```bash +besu --data-path=data --bootnodes="" --genesis-file=..\genesis.json --rpc-http-enabled --rpc-http-api=ADMIN,ETH,NET,PERM,IBFT --host-allowlist="*" --rpc-http-cors-origins="*" --p2p-port=30307 --rpc-http-port=8549 +``` + + + +Start another terminal and use curl to call the JSON-RPC API [`net_peerCount`](../../../public-networks/reference/api/index.md#net_peercount) method: + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"net_peerCount","params":[],"id":1}' localhost:8549 +``` + +The result confirms Node-5 has no peers even though it specifies Node-1 as a bootnode: + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": "0x0" +} +``` + +## Stop nodes + +When finished using the permissioned network, stop all nodes using ++ctrl+c++ in each terminal window. + +:::tip + +To restart the permissioned network in the future, start from [step 7](#7-start-node-1). + +::: + + + +[IBFT 2.0 proof of authority consensus protocol]: ../../how-to/configure/consensus/ibft.md +[Private network example tutorial]: ../quickstart.md#create-a-transaction-using-metamask diff --git a/versioned_docs/version-23.10.1/private-networks/tutorials/permissioning/onchain.md b/versioned_docs/version-23.10.1/private-networks/tutorials/permissioning/onchain.md new file mode 100644 index 00000000000..2d2655b0b3c --- /dev/null +++ b/versioned_docs/version-23.10.1/private-networks/tutorials/permissioning/onchain.md @@ -0,0 +1,350 @@ +--- +title: Get started with onchain permissioning +sidebar_position: 1 +description: Setting up and using Hyperledger Besu onchain permissioning +tags: + - private networks +--- + +# Get started with onchain permissioning + +The following steps describe bootstrapping a permissioned network using a Hyperledger Besu node. + +This tutorial configures permissioning on a [IBFT 2.0 proof of authority (PoA)] network. + +:::caution Please use this as reference material only! + +The [permissioning-contract-repo](https://github.com/ConsenSys/permissioning-smart-contracts) has been archived and is intended as reference material only. +Please update all dependencies in there before proceeding. + +In addition, we also recommend using [Hardhat](https://hardhat.org/hardhat-runner/docs/guides/deploying) instead of [Truffle](https://trufflesuite.com/), +as the development environment. Please refer to the [Quorum Dev Quickstart](../../tutorials/quickstart.md) for an example. + +::: + +## Prerequisites + +- [Node.js](https://nodejs.org/en/) v10.16.0 or later +- [Yarn](https://yarnpkg.com/en/) v1.15 or later +- Browser with [MetaMask installed](https://metamask.io/) + +## Steps + +### 1. Create folders + +Each node requires a data directory for the blockchain data. + +Create directories for your permissioned network and each of the three nodes, and a data directory for each node: + +```bash +Permissioned-Network/ +├── Node-1 +│   ├── data +├── Node-2 +│   ├── data +└── Node-3 +│   ├── data +└── Node-4 + ├── data +``` + +### 2. Create the configuration file + +The configuration file defines the [IBFT 2.0 genesis file](../../how-to/configure/consensus/ibft.md#genesis-file) and the number of node key pairs to generate. + +The configuration file has two nested JSON nodes. The first is the `genesis` property defining the IBFT 2.0 genesis file, except for the `extraData` string, which Besu generates automatically in the resulting genesis file. The second is the `blockchain` property defining the number of key pairs to generate. + +Copy the following configuration file definition to a file called `ibftConfigFile.json` and save it in the `Permissioned-Network` directory: + +```json +{ + "genesis": { + "config": { + "chainId": 1337, + "berlinBlock": 0, + "ibft2": { + "blockperiodseconds": 2, + "epochlength": 30000, + "requesttimeoutseconds": 4 + } + }, + "nonce": "0x0", + "timestamp": "0x58ee40ba", + "gasLimit": "0x47b760", + "difficulty": "0x1", + "mixHash": "0x63746963616c2062797a616e74696e65206661756c7420746f6c6572616e6365", + "coinbase": "0x0000000000000000000000000000000000000000", + "alloc": { + "fe3b557e8fb62b89f4916b721be55ceb828dbd73": { + "privateKey": "8f2a55949038a9610f50fb23b5883af3b4ecb3c3bb792cbcefbd1542c692be63", + "comment": "private key and this comment are ignored. In a real chain, the private key should NOT be stored", + "balance": "0xad78ebc5ac6200000" + }, + "627306090abaB3A6e1400e9345bC60c78a8BEf57": { + "privateKey": "c87509a1c067bbde78beb793e6fa76530b6382a4c0241e5e4a9ec0a0f44dc0d3", + "comment": "private key and this comment are ignored. In a real chain, the private key should NOT be stored", + "balance": "90000000000000000000000" + }, + "f17f52151EbEF6C7334FAD080c5704D77216b732": { + "privateKey": "ae6ae8e5ccbfb04590405997ee2d52d2b330726137b875053c36d94e974d162f", + "comment": "private key and this comment are ignored. In a real chain, the private key should NOT be stored", + "balance": "90000000000000000000000" + } + } + }, + "blockchain": { + "nodes": { + "generate": true, + "count": 4 + } + } +} +``` + +:::critical Security warning + +Don't use the accounts in the genesis file on Mainnet or any public network except for testing. The private keys display, which means the accounts are not secure. + +::: + +### 3. Generate node keys and a genesis file + +In the `Permissioned-Network` directory, generate the node key and genesis file: + +```bash +besu operator generate-blockchain-config --config-file=ibftConfigFile.json --to=networkFiles --private-key-file-name=key +``` + +Besu creates the following in the `networkFiles` directory: + +- `genesis.json` - The genesis file including the `extraData` property specifying the four nodes are validators. +- A directory for each node named using the node address and containing the public and private key for each node. + +```bash +networkFiles/ +├── genesis.json +└── keys + ├── 0x438821c42b812fecdcea7fe8235806a412712fc0 + │   ├── key + │   └── key.pub + ├── 0xca9c2dfa62f4589827c0dd7dcf48259aa29f22f5 + │   ├── key + │   └── key.pub + ├── 0xcd5629bd37155608a0c9b28c4fd19310d53b3184 + │   ├── key + │   └── key.pub + └── 0xe96825c5ab8d145b9eeca1aba7ea3695e034911a + ├── key + └── key.pub +``` + +### 4. Copy the genesis file to the Permissioned-Network directory + +Copy the `genesis.json` file to the `Permisssioned-Network` directory. + +### 5. Add the Ingress contracts to the genesis file + +:::tip + +If the network is using only account or node permissioning, add only the relevant Ingress contract to the genesis file. + +::: + +Add the Ingress contracts to the genesis file for your network by copying them from [`genesis.json`](https://github.com/ConsenSys/permissioning-smart-contracts/blob/e6c2d4d5a728c11cdb8e97a07ddda3c0bfb57b5d/genesis.json) in the [`permissioning-smart-contracts` repository](https://github.com/ConsenSys/permissioning-smart-contracts) to the `alloc` section of the contract: + +```json +"0x0000000000000000000000000000000000008888": { + "comment": "Account Ingress smart contract", + "balance": "0", + "code": , + "storage": { + + } +} + +"0x0000000000000000000000000000000000009999": { + "comment": "Node Ingress smart contract", + "balance": "0", + "code": , + "storage": { + + } +} +``` + +:::info + +To support the permissioning contracts, ensure your genesis file includes at least the `constantinopleFixBlock` milestone. + +The permissioning contract has multiple interfaces, and each interface maps to a specific version of the [Enterprise Ethereum Alliance Client Specification](https://entethalliance.org/technical-specifications/). Ensure that you specify the [permissioning contract interface](../../how-to/use-permissioning/onchain.md) being used when starting Besu. + +::: + +### 6. Copy the node private keys to the node directories + +For each node, copy the key files to the `data` directory for that node + +```bash +Permissioned-Network/ +├── genesis.json +├── Node-1 +│   ├── data +│ │    ├── key +│ │    ├── key.pub +├── Node-2 +│   ├── data +│ │    ├── key +│ │    ├── key.pub +├── Node-3 +│   ├── data +│ │    ├── key +│ │    ├── key.pub +├── Node-4 +│ ├── data +│ │    ├── key +│ │    ├── key.pub +``` + +### 7. Start Node-1 + +:::info + +The specified node must be producing blocks, that is, be a miner (PoW networks) or validator (PoA networks). + +To allow MetaMask to connect, the node must have JSON-RPC HTTP enabled, and have `--rpc-http-cors-origins` set to allow MetaMask. + +If your network is not a [free gas network](../../how-to/configure/free-gas.md), the account used to interact with the permissioning contracts must have a balance. + +::: + +Start the first node with command line options to enable onchain permissioning and the location of the **data** folder and genesis file: + +```cmd +besu --data-path=data --genesis-file=../genesis.json --permissions-accounts-contract-enabled --permissions-accounts-contract-address "0x0000000000000000000000000000000000008888" --permissions-nodes-contract-enabled --permissions-nodes-contract-address "0x0000000000000000000000000000000000009999" --permissions-nodes-contract-version=2 --rpc-http-enabled --rpc-http-cors-origins="*" --rpc-http-api=ADMIN,ETH,NET,PERM,IBFT --host-allowlist="*" +``` + +On the command line: + +- Enable onchain accounts permissioning using [`--permissions-accounts-contract-enabled`](../../reference/cli/options.md#permissions-accounts-contract-enabled). +- Set the address of the Account Ingress contract in the genesis file using [`--permissions-accounts-contract-address`](../../reference/cli/options.md#permissions-accounts-contract-address). +- Enable onchain nodes permissioning using [`--permissions-nodes-contract-enabled`](../../reference/cli/options.md#permissions-nodes-contract-enabled). +- Set the address of the Node Ingress contract in the genesis file using [`--permissions-nodes-contract-address`](../../reference/cli/options.md#permissions-nodes-contract-address). +- Set the version of the [permissioning contract interface](../../how-to/use-permissioning/onchain.md#specify-the-permissioning-contract-interface-version) using [`--permissions-nodes-contract-version`](../../reference/cli/options.md#permissions-nodes-contract-version). +- Enable the JSON-RPC API using [`--rpc-http-enabled`](../../../public-networks/reference/cli/options.md#rpc-http-enabled). +- Enable the `ADMIN`, `ETH`, `NET`, `PERM`, and `IBFT` APIs using [`--rpc-http-api`](../../../public-networks/reference/cli/options.md#rpc-http-api). +- Allow all-host access to the HTTP JSON-RPC API using [`--host-allowlist`](../../../public-networks/reference/cli/options.md#host-allowlist). +- Allow all-domain access to the node through the HTTP JSON-RPC API using [`--rpc-http-cors-origins`](../../../public-networks/reference/cli/options.md#rpc-http-cors-origins). + +When the node starts, the [enode URL](../../../public-networks/concepts/node-keys.md#enode-url) displays. Copy the enode URL to use when starting Node-2, Node-3, and Node-4. + +### 8. Start Node-2 + +Use the following command to start Node-2: + +```cmd +besu --data-path=data --genesis-file=../genesis.json --bootnodes= --permissions-accounts-contract-enabled --permissions-accounts-contract-address "0x0000000000000000000000000000000000008888" --permissions-nodes-contract-enabled --permissions-nodes-contract-address "0x0000000000000000000000000000000000009999" --permissions-nodes-contract-version=2 --rpc-http-enabled --rpc-http-cors-origins="*" --rpc-http-api=ADMIN,ETH,NET,PERM,IBFT --host-allowlist="*" --p2p-port=30304 --rpc-http-port=8546 +``` + +The command line specifies: + +- A different port to Node-1 for P2P discovery using [`--p2p-port`](../../../public-networks/reference/cli/options.md#p2p-port). +- A different port to Node-1 for HTTP JSON-RPC using [`--rpc-http-port`](../../../public-networks/reference/cli/options.md#rpc-http-port). +- The enode URL of Node-1 using [`--bootnodes`](../../../public-networks/reference/cli/options.md#bootnodes). +- Other options as for [Node-1](#7-start-node-1). + +### 9. Start Node-3 + +Use the following command to start Node-3: + +```cmd +besu --data-path=data --genesis-file=../genesis.json --bootnodes= --permissions-accounts-contract-enabled --permissions-accounts-contract-address "0x0000000000000000000000000000000000008888" --permissions-nodes-contract-enabled --permissions-nodes-contract-address "0x0000000000000000000000000000000000009999" --permissions-nodes-contract-version=2 --rpc-http-enabled --rpc-http-cors-origins="*" --rpc-http-api=ADMIN,ETH,NET,PERM,IBFT --host-allowlist="*" --p2p-port=30305 --rpc-http-port=8547 +``` + +The command line specifies: + +- A different port to Node-1 and Node-2 for P2P discovery using [`--p2p-port`](../../../public-networks/reference/cli/options.md#p2p-port). +- A different port to Node-1 and Node-2 for HTTP JSON-RPC using [`--rpc-http-port`](../../../public-networks/reference/cli/options.md#rpc-http-port). +- The enode URL of Node-1 using [`--bootnodes`](../../../public-networks/reference/cli/options.md#bootnodes). +- Other options as for [Node-1](#7-start-node-1). + +### 10. Start Node-4 + +Use the following command to start Node-4: + +```cmd +besu --data-path=data --genesis-file=../genesis.json --bootnodes= --permissions-accounts-contract-enabled --permissions-accounts-contract-address "0x0000000000000000000000000000000000008888" --permissions-nodes-contract-enabled --permissions-nodes-contract-address "0x0000000000000000000000000000000000009999" --permissions-nodes-contract-version=2 --rpc-http-enabled --rpc-http-cors-origins="*" --rpc-http-api=ADMIN,ETH,NET,PERM,IBFT --host-allowlist="*" --p2p-port=30306 --rpc-http-port=8548 +``` + +The command line specifies: + +- A different port to Node-1, Node-2, and Node-3 for P2P discovery using [`--p2p-port`](../../../public-networks/reference/cli/options.md#p2p-port). +- A different port to Node-1, Node-2, and Node-3 for HTTP JSON-RPC using [`--rpc-http-port`](../../../public-networks/reference/cli/options.md#rpc-http-port). +- The enode URL of Node-1 using [`--bootnodes`](../../../public-networks/reference/cli/options.md#bootnodes). +- Other options as for [Node-1](#7-start-node-1). + +:::tip + +If your nodes are having trouble connecting as peers, update the `--bootnodes` option for each node to include all four enode URLs. + +::: + +### 11. Clone the contracts and install dependencies + +Clone the `permissioning-smart-contracts` repository: + +```bash +git clone https://github.com/ConsenSys/permissioning-smart-contracts.git +``` + +Change into the `permissioning-smart-contracts` directory. + +### 12. Set the environment variables + +Create the following environment variables and set to the specified values: + +- `BESU_NODE_PERM_ACCOUNT` - Account to deploy the permissioning contracts and become the first admin account. +- `BESU_NODE_PERM_KEY` - Private key of the account to deploy the permissioning contracts. +- `ACCOUNT_INGRESS_CONTRACT_ADDRESS` - Address of the Account Ingress contract in the genesis file. +- `NODE_INGRESS_CONTRACT_ADDRESS` - Address of the Node Ingress contract in the genesis file. +- `BESU_NODE_PERM_ENDPOINT` - Required only if your node is not using the default JSON-RPC host and port (`http://127.0.0.1:8545`). Set to JSON-RPC host and port. When bootstrapping the network, Besu uses the specified node to deploy the contracts and is the first node in the network. +- `CHAIN_ID` - The chain ID from the genesis file. +- `INITIAL_ALLOWLISTED_NODES`(optional) - The enode URLs of permitted nodes. Specify multiple nodes (Node-1, Node-2, Node-3) as a comma-separated list. + +:::tip + +A simple way to set multiple environment variables is to create a file called `.env` with the required settings: + +```env +NODE_INGRESS_CONTRACT_ADDRESS=0x0000000000000000000000000000000000009999 +ACCOUNT_INGRESS_CONTRACT_ADDRESS=0x0000000000000000000000000000000000008888 +BESU_NODE_PERM_ACCOUNT=627306090abaB3A6e1400e9345bC60c78a8BEf57 +BESU_NODE_PERM_KEY=c87509a1c067bbde78beb793e6fa76530b6382a4c0241e5e4a9ec0a0f44dc0d3 +BESU_NODE_PERM_ENDPOINT=http://127.0.0.1:8545 +CHAIN_ID=1337 +INITIAL_ALLOWLISTED_NODES=enode://c35c3...d615f@1.2.3.4:30303,enode://f42c13...fc456@1.2.3.5:30303 +``` + +If using a `.env` file, save the file to the `permissioning-smart-contracts` directory. + +::: + +### 13. Deploy the contracts + +In the `permissioning-smart-contracts` directory, while your network is running, deploy the Admin and Rules contracts: + +```bash +yarn truffle migrate --reset --network besu +``` + +This also updates the Ingress contract with the name and version of the Admin and Rules contracts. The migration logs the addresses of the Admin and Rules contracts. + +:::important + +The account that deploys the contracts is automatically an admin account. + +::: + + + +[Node-1, Node-2, Node-3, and Node-4 to the allowlist]: ../../how-to/use-permissioning/onchain.md#update-nodes-allowlist +[IBFT 2.0 proof of authority (PoA)]: ../../how-to/configure/consensus/ibft.md diff --git a/versioned_docs/version-23.10.1/private-networks/tutorials/permissioning/upgrade-contracts.md b/versioned_docs/version-23.10.1/private-networks/tutorials/permissioning/upgrade-contracts.md new file mode 100644 index 00000000000..7d44a43b56a --- /dev/null +++ b/versioned_docs/version-23.10.1/private-networks/tutorials/permissioning/upgrade-contracts.md @@ -0,0 +1,167 @@ +--- +title: Upgrade permissioning contracts +sidebar_position: 2 +description: Upgrade the permissioning contracts for onchain permissioning +tags: + - private networks +--- + +# Upgrade permissioning contracts + +The following tutorial describes the steps to upgrade the onchain permissioning contracts to the latest version. + +:::caution Please use this as reference material only! + +The [permissioning-contract-repo](https://github.com/ConsenSys/permissioning-smart-contracts) has been archived and is intended as reference material only. +Please update all dependencies in there before proceeding. + +In addition we also recommend using [Hardhat](https://hardhat.org/hardhat-runner/docs/guides/deploying) instead of [Truffle](https://trufflesuite.com/), +as the development environment. Please refer to the [Quorum Dev Quickstart](../../tutorials/quickstart.md) for an example. + +::: + +## Prerequisites + + + +- [Node.js](https://nodejs.org/en/) v10.16.0 or later + +- [Yarn](https://yarnpkg.com/en/) v1.15 or later +- Browser with [MetaMask installed](https://metamask.io/). + + +## Steps + + +### 1. Get the latest contracts and install dependencies + +:::note + +Pull the latest changes if you already have a cloned repository using the `git pull` command inside the `permissioning-smart-contracts` directory. + +::: + +1. Clone the `permissioning-smart-contracts` repository: + + ```bash + git clone https://github.com/ConsenSys/permissioning-smart-contracts.git + ``` + +### 3. Update environment variables + +If using a `.env` file to configure environment variables, then the file must be in the `permissioning-smart-contracts` directory. + +:::tip + +You can use environment variables to retain existing contracts if required. For example: + +- `RETAIN_ADMIN_CONTRACT=true` to retain the current admin list +- `RETAIN_NODE_RULES_CONTRACT=true` to retain the current Node rules contract +- `RETAIN_ACCOUNT_RULES_CONTRACT=true` to retain the current Account rules contract + +::: + +1. Legacy: If they exist, rename the following environment variables: + + - `PANTHEON_NODE_PERM_ACCOUNT` to `BESU_NODE_PERM_ACCOUNT` + - `PANTHEON_NODE_PERM_KEY` to `BESU_NODE_PERM_KEY` + - `PANTHEON_NODE_PERM_ENDPOINT` to `BESU_NODE_PERM_ENDPOINT` + +2. If updating from v1 to v2, you need to re-deploy the `NodeIngress` contract. In order to do this, first delete the `NODE_INGRESS_CONTRACT_ADDRESS` environment variable. + + :::important + + This step is only required if upgrading from v1 of the node permissioning contract to v2 (because the interface changed, a new `NodeIngress` contract must be deployed). + + ::: + +### 4. Optional: Export current allowlists + +:::note + +This step enables you to export the current allowlists to assist in updating. + +::: + +1. Export the current allowlists by setting the following environment variables: + + ```bash + RETAIN_ADMIN_CONTRACT=true + RETAIN_NODE_RULES_CONTRACT=true + RETAIN_ACCOUNT_RULES_CONTRACT=true + ``` + +2. Log the current allowlists to console: + + ```bash + truffle migrate --reset + ``` + + The migration scripts will log the existing allowlists to the console, but no contracts will be deployed. + +3. Set initial values for updated deployment using the values logged in the previous step: + + ```bash + INITIAL_ADMIN_ACCOUNTS= + INITIAL_ALLOWLISTED_ACCOUNTS= + INITIAL_ALLOWLISTED_NODES= + ``` + +4. Update environment variables for contracts that are to be deployed. For example: + + ```bash + RETAIN_ADMIN_CONTRACT=true + RETAIN_NODE_RULES_CONTRACT=false + RETAIN_ACCOUNT_RULES_CONTRACT=false + ``` + +### 5. Deploy the contracts + +1. In the `permissioning-smart-contracts` directory, deploy the contracts: + + ```bash + truffle migrate --reset + ``` + + :::important + + - If updating from v1 to v2, the new `NodeIngress` contract address must be specified when restarting the Besu nodes. Copy this address from the migration output. For example: + + ```bash + > Deployed NodeIngress contract to address = 0x12B1f953395080A13AeED0dC4d0bb14e787A91cF + ``` + + - If upgrading from v2 (using separate storage contracts) copy the `Storage` contract addresses displayed in the output. For example: + + ``` + > Deployed NodeStorage contract to address = 0x4F3e35A3Be3C1b77Ade39969D175C743ad3484Ee + ... + > Deployed AccountStorage contract to address = 0x2362187023D738034B516438Af187356b31E8Fb8 + ``` + + ::: + +1. Set the storage contract address environment variables to ensure that the storage contracts are not re-deployed. For example: + + ```bash + NODE_STORAGE_CONTRACT_ADDRESS=0xE0bF6021e023a197DBb3fABE64efA880E13D3f4b + ACCOUNT_STORAGE_CONTRACT_ADDRESS=0x7153CCD1a20Bbb2f6dc89c1024de368326EC6b4F + ``` + +1. Deploy the updated contracts: + + ```bash + truffle migrate --reset + ``` + +### 6. Restart Besu nodes + +Restart the Besu nodes with the updated [`NodeIngress`](#5-deploy-the-contracts) contract address and [permissioning contract interface](../../how-to/use-permissioning/onchain.md#specify-the-permissioning-contract-interface-version) version 2. + +```besu +cmd besu --data-path=data --genesis-file=../genesis.json --permissions-accounts-contract-enabled --permissions-accounts-contract-address "0x0000000000000000000000000000000000008888" --permissions-nodes-contract-enabled --permissions-nodes-contract-address "0x4E72770760c011647D4873f60A3CF6cDeA896CD8" --permissions-nodes-contract-version=2 --rpc-http-enabled --rpc-http-cors-origins="*" --rpc-http-api=ADMIN,ETH,NET,PERM,IBFT --host-allowlist="*" +``` + + + +[nodes to the allowlist]: ../../how-to/use-permissioning/onchain.md#update-nodes-allowlist diff --git a/versioned_docs/version-23.10.1/private-networks/tutorials/privacy/_category_.json b/versioned_docs/version-23.10.1/private-networks/tutorials/privacy/_category_.json new file mode 100644 index 00000000000..c6e33f3bea4 --- /dev/null +++ b/versioned_docs/version-23.10.1/private-networks/tutorials/privacy/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Create a privacy enabled network", + "position": 6 +} diff --git a/versioned_docs/version-23.10.1/private-networks/tutorials/privacy/index.md b/versioned_docs/version-23.10.1/private-networks/tutorials/privacy/index.md new file mode 100644 index 00000000000..f3991a18afd --- /dev/null +++ b/versioned_docs/version-23.10.1/private-networks/tutorials/privacy/index.md @@ -0,0 +1,433 @@ +--- +title: Create a privacy enabled network using the Quickstart +sidebar_position: 1 +description: Configure Hyperledger Besu privacy +tags: + - private networks +--- + +# Create a privacy-enabled network + +Configuring a network that supports private transactions requires starting a [Tessera] node for each Hyperledger Besu node. Besu command line options associate the Besu node with the Tessera node. + +This tutorial assumes you have completed setting up an IBFT 2.0 network to the point where you have [created the genesis file and copied the private keys](../ibft/index.md#5-copy-the-node-private-keys-to-the-node-directories). If not, complete steps 1 to 5 of the [Create an IBFT 2.0](../ibft/index.md) tutorial before continuing. + +:::important + +To support privacy, ensure your genesis file includes at least the `byzantium` milestone. + +This tutorial configures a private network using IBFT 2.0 for educational purposes only. IBFT 2.0 requires 4 validators to be Byzantine fault tolerant. + +::: + +In this tutorial we start Tessera nodes for the four Besu nodes and associate each Besu node with a Tessera node. + +## Prerequisites + +- [Install Tessera](https://docs.tessera.consensys.net/category/install). + +## 1. Create Tessera directories + +Inside each `Node-*` directory, create a `Tessera` directory: + +```bash +IBFT-Network/ +├── Node-1 +│   ├── data +│ ├── Tessera +├── Node-2 +│   ├── data +│ ├── Tessera +├── Node-3 +│   ├── data +│ ├── Tessera +└── Node-4 + ├── data + ├── Tessera +``` + +## 2. Generate Tessera keys + +This example creates an unlocked private key, meaning you do not need a password to decrypt the private key file. + +In each `Tessera` directory, generate a public/private key pair for the Tessera node: + +```bash +tessera -keygen -filename nodeKey +``` + +At the prompt, press **Enter** to create an unlocked key. + +Tessera generates the public/private key pair and saves the keys in the `nodeKey.pub` and `nodeKey.key` files. + +## 3. Create Tessera configuration files + +In the `Tessera` directory for each node, create a file called `tessera.conf`, with the following configuration: + +:::important + +In production environments, only specify [`tls`](https://docs.tessera.consensys.net/HowTo/Configure/TLS/) as `OFF` if another transport security mechanism, such as WireGuard, is in place. + +::: + + + +# Node-1 + +```json +{ + "mode": "orion", + "useWhiteList": false, + "jdbc": { + "username": "sa", + "password": "", + "url": "jdbc:h2:./target/h2/tessera1", + "autoCreateTables": true + }, + "serverConfigs": [ + { + "app": "ThirdParty", + "serverAddress": "http://localhost:9101", + "communicationType": "REST" + }, + { + "app": "Q2T", + "serverAddress": "http://localhost:9102", + "communicationType": "REST" + }, + { + "app": "P2P", + "serverAddress": "http://localhost:9103", + "sslConfig": { + "tls": "OFF" + }, + "communicationType": "REST" + } + ], + "peer": [ + { + "url": "http://localhost:9203" + }, + { + "url": "http://localhost:9303" + }, + { + "url": "http://localhost:9403" + } + ], + "keys": { + "passwords": [], + "keyData": [ + { + "privateKeyPath": "nodeKey.key", + "publicKeyPath": "nodeKey.pub" + } + ] + }, + "alwaysSendTo": [] +} +``` + +# Node-2 + +```json +{ + "mode": "orion", + "useWhiteList": false, + "jdbc": { + "username": "sa", + "password": "", + "url": "jdbc:h2:./target/h2/tessera1", + "autoCreateTables": true + }, + "serverConfigs": [ + { + "app": "ThirdParty", + "serverAddress": "http://localhost:9201", + "communicationType": "REST" + }, + { + "app": "Q2T", + "serverAddress": "http://localhost:9202", + "communicationType": "REST" + }, + { + "app": "P2P", + "serverAddress": "http://localhost:9203", + "sslConfig": { + "tls": "OFF" + }, + "communicationType": "REST" + } + ], + "peer": [ + { + "url": "http://localhost:9103" + }, + { + "url": "http://localhost:9303" + }, + { + "url": "http://localhost:9403" + } + ], + "keys": { + "passwords": [], + "keyData": [ + { + "privateKeyPath": "nodeKey.key", + "publicKeyPath": "nodeKey.pub" + } + ] + }, + "alwaysSendTo": [] +} +``` + +# Node-3 + +```json +{ + "mode": "orion", + "useWhiteList": false, + "jdbc": { + "username": "sa", + "password": "", + "url": "jdbc:h2:./target/h2/tessera1", + "autoCreateTables": true + }, + "serverConfigs": [ + { + "app": "ThirdParty", + "serverAddress": "http://localhost:9301", + "communicationType": "REST" + }, + { + "app": "Q2T", + "serverAddress": "http://localhost:9302", + "communicationType": "REST" + }, + { + "app": "P2P", + "serverAddress": "http://localhost:9303", + "sslConfig": { + "tls": "OFF" + }, + "communicationType": "REST" + } + ], + "peer": [ + { + "url": "http://localhost:9103" + }, + { + "url": "http://localhost:9203" + }, + { + "url": "http://localhost:9403" + } + ], + "keys": { + "passwords": [], + "keyData": [ + { + "privateKeyPath": "nodeKey.key", + "publicKeyPath": "nodeKey.pub" + } + ] + }, + "alwaysSendTo": [] +} +``` + +# Node-4 + +```json +{ + "mode": "orion", + "useWhiteList": false, + "jdbc": { + "username": "sa", + "password": "", + "url": "jdbc:h2:./target/h2/tessera1", + "autoCreateTables": true + }, + "serverConfigs": [ + { + "app": "ThirdParty", + "serverAddress": "http://localhost:9401", + "communicationType": "REST" + }, + { + "app": "Q2T", + "serverAddress": "http://localhost:9402", + "communicationType": "REST" + }, + { + "app": "P2P", + "serverAddress": "http://localhost:9403", + "sslConfig": { + "tls": "OFF" + }, + "communicationType": "REST" + } + ], + "peer": [ + { + "url": "http://localhost:9103" + }, + { + "url": "http://localhost:9203" + }, + { + "url": "http://localhost:9303" + } + ], + "keys": { + "passwords": [], + "keyData": [ + { + "privateKeyPath": "nodeKey.key", + "publicKeyPath": "nodeKey.pub" + } + ] + }, + "alwaysSendTo": [] +} +``` + + + +In the configuration file, specify: + +- Different port numbers for the various servers in the [`serverConfigs`](https://docs.tessera.consensys.net/HowTo/Configure/TesseraAPI/) section. +- The address of the Tessera nodes to discover, in the [`peer`](https://docs.tessera.consensys.net/HowTo/Configure/Peer-discovery/#specify-peers) section. +- The location of the public/private key pair. + +## 4. Start the Tessera nodes + +In each `Tessera` directory, start Tessera specifying the [configuration file](#3-create-tessera-configuration-files) created in the previous step: + +```bash +tessera -configfile tessera.conf +``` + +:::info + +After starting the first Tessera node and before starting the other nodes, the log message `failed to connect to node` displays. This is normal behavior. Until you start the other peer nodes, your node is not connected and displays this warning. You can continue to start the other nodes. + +::: + +## 5. Start Besu Node-1 + +In the `Node-1` directory, start Besu Node-1: + + + +# MacOS + +```bash +besu --data-path=data --genesis-file=../genesis.json --rpc-http-enabled --rpc-http-api=ETH,NET,IBFT,EEA,PRIV --host-allowlist="*" --rpc-http-cors-origins="all" --privacy-enabled --privacy-url=http://127.0.0.1:9102 --privacy-public-key-file=Tessera/nodeKey.pub --min-gas-price=0 +``` + +# Windows + +```bash +besu --data-path=data --genesis-file=..\genesis.json --rpc-http-enabled --rpc-http-api=ETH,NET,IBFT,EEA,PRIV --host-allowlist="*" --rpc-http-cors-origins="all" --privacy-enabled --privacy-url=http://127.0.0.1:9102 --privacy-public-key-file=Tessera\nodeKey.pub --min-gas-price=0 +``` + + + +The command line specifies privacy options: + +- [`--privacy-enabled`](../../reference/cli/options.md#privacy-enabled) enables privacy +- [`--privacy-url`](../../reference/cli/options.md#privacy-url) specifies the Q2T server address of the Tessera node (`Q2T` in `tessera.conf`) +- [`--privacy-public-key-file`](../../reference/cli/options.md#privacy-public-key-file) specifies the file containing Tessera node public key (created in [3. Generate Tessera Keys](#2-generate-tessera-keys)) +- [`--rpc-http-api`](../../../public-networks/reference/cli/options.md#rpc-http-api) includes `EEA` and `PRIV` in the list of JSON-RPC APIs to enable privacy JSON-RPC API methods. +- [`--min-gas-price`](../../../public-networks/reference/cli/options.md#min-gas-price) is 0 for a [free gas network](../../how-to/configure/free-gas.md). + +:::note + +Use the [`--privacy-marker-transaction-signing-key-file`](../../reference/cli/options.md#privacy-marker-transaction-signing-key-file) command line option to sign [privacy marker transactions](../../concepts/privacy/private-transactions/processing.md) using a supplied key. The command line option is mandatory in privacy-enabled paid gas networks. + +::: + +When the node starts, the [enode URL](../../../public-networks/concepts/node-keys.md#enode-url) displays. Copy the enode URL to specify Node-1 as the bootnode in the following steps. + +![Node 1 Enode URL](../../../assets/images/EnodeStartup.png) + +## 6. Start Besu Node-2 + +In the `Node-2` directory, start Besu Node-2 specifying the Node-1 enode URL copied when starting Node-1 as the bootnode: + + + +# MacOS + +```bash +besu --data-path=data --genesis-file=../genesis.json --bootnodes= --p2p-port=30304 --rpc-http-enabled --rpc-http-api=ETH,NET,IBFT,EEA,PRIV --host-allowlist="*" --rpc-http-cors-origins="all" --rpc-http-port=8546 --privacy-enabled --privacy-url=http://127.0.0.1:9202 --privacy-public-key-file=Tessera/nodeKey.pub --min-gas-price=0 +``` + +# Windows + +```bash +besu --data-path=data --genesis-file=..\genesis.json --bootnodes= --p2p-port=30304 --rpc-http-enabled --rpc-http-api=ETH,NET,IBFT,EEA,PRIV --host-allowlist="*" --rpc-http-cors-origins="all" --rpc-http-port=8546 --privacy-enabled --privacy-url=http://127.0.0.1:9202 --privacy-public-key-file=Tessera\nodeKey.pub --min-gas-price=0 +``` + + + +The command line specifies the same options as for Node-1 with different ports and Tessera node URL. The [`--bootnodes`](../../../public-networks/reference/cli/options.md#bootnodes) option specifies the enode URL of Node-1. + +:::note + +When running Besu from the [Docker image](../../get-started/install/run-docker-image.md), [expose ports](../../get-started/install/run-docker-image.md#expose-ports). + +::: + +## 7. Start Besu Node-3 + +In the `Node-3` directory, start Besu Node-3 specifying the Node-1 enode URL copied when starting Node-1 as the bootnode: + + + +# MacOS + +```bash +besu --data-path=data --genesis-file=../genesis.json --bootnodes= --p2p-port=30305 --rpc-http-enabled --rpc-http-api=ETH,NET,IBFT,EEA,PRIV --host-allowlist="*" --rpc-http-cors-origins="all" --rpc-http-port=8547 --privacy-enabled --privacy-url=http://127.0.0.1:9302 --privacy-public-key-file=Tessera/nodeKey.pub --min-gas-price=0 +``` + +# Windows + +```bash +besu --data-path=data --genesis-file=..\genesis.json --bootnodes= --p2p-port=30305 --rpc-http-enabled --rpc-http-api=ETH,NET,IBFT,EEA,PRIV --host-allowlist="*" --rpc-http-cors-origins="all" --rpc-http-port=8547 --privacy-enabled --privacy-url=http://127.0.0.1:9302 --privacy-public-key-file=Tessera\nodeKey.pub --min-gas-price=0 +``` + + + +The command line specifies the same options as for Node-1 with different ports and Tessera node URL. The [`--bootnodes`](../../../public-networks/reference/cli/options.md#bootnodes) option specifies the enode URL of Node-1. + +## 8. Start Besu Node-4 + +In the `Node-4` directory, start Besu Node-4 specifying the Node-1 enode URL copied when starting Node-1 as the bootnode: + + + +# MacOS + +```bash +besu --data-path=data --genesis-file=../genesis.json --bootnodes= --p2p-port=30306 --rpc-http-enabled --rpc-http-api=ETH,NET,IBFT,EEA,PRIV --host-allowlist="*" --rpc-http-cors-origins="all" --rpc-http-port=8548 --privacy-enabled --privacy-url=http://127.0.0.1:9402 --privacy-public-key-file=Tessera/nodeKey.pub --min-gas-price=0 +``` + +# Windows + +```bash +besu --data-path=data --genesis-file=..\genesis.json --bootnodes= --p2p-port=30306 --rpc-http-enabled --rpc-http-api=ETH,NET,IBFT,EEA,PRIV --host-allowlist="*" --rpc-http-cors-origins="all" --rpc-http-port=8548 --privacy-enabled --privacy-url=http://127.0.0.1:9402 --privacy-public-key-file=Tessera\nodeKey.pub --min-gas-price=0 +``` + + + +The command line specifies the same options as for Node-1 with different ports and Tessera node URL. The [`--bootnodes`](../../../public-networks/reference/cli/options.md#bootnodes) option specifies the enode URL of Node-1. + + + +[Tessera]: https://docs.tessera.consensys.net/ diff --git a/versioned_docs/version-23.10.1/private-networks/tutorials/privacy/multi-tenancy.md b/versioned_docs/version-23.10.1/private-networks/tutorials/privacy/multi-tenancy.md new file mode 100644 index 00000000000..c077e8910e5 --- /dev/null +++ b/versioned_docs/version-23.10.1/private-networks/tutorials/privacy/multi-tenancy.md @@ -0,0 +1,187 @@ +--- +title: Create a multi-tenant network +sidebar_position: 2 +description: Configure multi-tenancy +tags: + - private networks +--- + +# Configure a multi-tenant node + +You can configure Besu and associated Tessera node in a privacy-enabled network to host [multiple tenants](../../concepts/privacy/multi-tenancy.md). + +In this tutorial we'll add tenants to the `Node-1` Besu and Tessera node in a [privacy-enabled network](index.md). + +```bash +IBFT-Network/ +├── Node-1 +│   ├── data +│ ├── Tessera +├── Node-2 +│   ├── data +│ ├── Tessera +├── Node-3 +│   ├── data +│ ├── Tessera +└── Node-4 + ├── data + ├── Tessera +``` + +:::info + +This tutorial uses [JWT public key authentication] to create the tenant's JWT, but you can also use [username and password authentication]. + +::: + +## Prerequisites + +- A [Privacy-enabled network](index.md). + +## 1. Generate a private and public key pair + +In the `Node-1` directory, [generate the private and public key pair]. The key pair, which must be in `.pem` format, belongs to the operator who uses the key pair to authenticate the [tenant JWTs](#6-generate-the-tenant-jwts). + +:::info + +This step is not required when using [username and password authentication] to create the required JWTs. + +::: + +## 2. Generate Tessera keys + +In the `Node-1/Tessera` directory, [generate a public/private key pair for each tenant](index.md#2-generate-tessera-keys). + +:::note + +The instructions creates an unlocked private key, meaning you do not need a password to decrypt the private key file. + +::: + +Name the key pair `nodeKey2` and `nodeKey3`. + +## 3. Update the Tessera configuration file + +In the `Node-1/Tessera` directory, update the `tessera.conf` file by adding the new key pairs: + +```json +{ + "mode": "orion", + "useWhiteList": false, + "jdbc": { + "username": "sa", + "password": "", + "url": "jdbc:h2:./target/h2/tessera1", + "autoCreateTables": true + }, + "serverConfigs": [ + { + "app": "ThirdParty", + "serverAddress": "http://localhost:9101", + "communicationType": "REST" + }, + { + "app": "Q2T", + "serverAddress": "http://localhost:9102", + "communicationType": "REST" + }, + { + "app": "P2P", + "serverAddress": "http://localhost:9103", + "sslConfig": { + "tls": "OFF" + }, + "communicationType": "REST" + } + ], + "peer": [ + { + "url": "http://localhost:9203" + }, + { + "url": "http://localhost:9303" + }, + { + "url": "http://localhost:9403" + } + ], + "keys": { + "passwords": [], + "keyData": [ + { + "privateKeyPath": "nodeKey.key", + "publicKeyPath": "nodeKey.pub" + }, + { + "privateKeyPath": "nodeKey2.key", + "publicKeyPath": "nodeKey2.pub" + }, + { + "privateKeyPath": "nodeKey3.key", + "publicKeyPath": "nodeKey3.pub" + } + ] + }, + "alwaysSendTo": [] +} +``` + +:::info + +Besu requires [`orion` mode](https://docs.tessera.consensys.net/HowTo/Configure/Orion-Mode). Add the line `"mode": "orion",` to the Tessera configuration file. + +::: + +## 4. Start Tessera + +[Start the Tessera nodes](index.md#4-start-the-tessera-nodes) and specify the configuration file. + +## 5. Start Besu Node-1 + +In the `Node-1` directory, start Besu Node-1: + +```bash +besu --data-path=data --genesis-file=../genesis.json --rpc-http-authentication-enabled --rpc-http-authentication-jwt-public-key-file=publicKey.pem --rpc-http-enabled --rpc-http-api=ETH,NET,IBFT,EEA,PRIV --host-allowlist="*" --rpc-http-cors-origins="all" --privacy-enabled --privacy-url=http://127.0.0.1:9102 --privacy-multi-tenancy-enabled --min-gas-price=0 +``` + +The command line specifies privacy options: + +- [`--rpc-http-authentication-enabled`](../../../public-networks/reference/cli/options.md#rpc-http-authentication-enabled) enables authentication for JSON-RPC APIs. +- [`--rpc-http-authentication-jwt-public-key-file`](../../../public-networks/reference/cli/options.md#rpc-http-authentication-jwt-public-key-file) specifies the Operator's [public key file](#1-generate-a-private-and-public-key-pair). Used to authenticate the [tenant JWTs](#6-generate-the-tenant-jwts). +- [`--privacy-enabled`](../../reference/cli/options.md#privacy-enabled) enables privacy. +- [`--privacy-url`](../../reference/cli/options.md#privacy-url) specifies the [Quorum to Tessera (Q2T)] server address of the Tessera node (`Q2T` in `tessera.conf`). +- [`--privacy-multi-tenancy-enabled`](../../reference/cli/options.md#privacy-multi-tenancy-enabled) enables multi-tenancy. + +:::note + +[`--rpc-http-authentication-jwt-public-key-file`](../../../public-networks/reference/cli/options.md#rpc-http-authentication-jwt-public-key-file) is only required when using [JWT public key authentication]. If using [username and password authentication], use [`--rpc-http-authentication-credentials-file`](../../../public-networks/reference/cli/options.md#rpc-http-authentication-credentials-file) instead. + +::: + +[Start the remaining Besu nodes](index.md#6-start-besu-node-2). + +## 6. Generate the tenant JWTs + +[Generate the JWT](../../../public-networks/how-to/use-besu-api/authenticate.md#2-create-the-jwt) for each tenant and specify the [tenant's Tessera public key](#2-generate-tessera-keys) in the `privacyPublicKey` field. + +Ensure you apply the appropriate [JSON-RPC API permissions](../../../public-networks/how-to/use-besu-api/authenticate.md#json-rpc-permissions) to the token. For example, ensure you enable the `PRIV` and `EEA` APIs for privacy. + +:::note + +This step is not required when using [username and password authentication] to create the required JWTs. + +::: + +[Use the authentication token to make requests]. + + + +[JWT public key authentication]: ../../../public-networks/how-to/use-besu-api/authenticate.md#jwt-public-key-authentication +[username and password authentication]: ../../../public-networks/how-to/use-besu-api/authenticate.md#username-and-password-authentication +[generate the private and public key pair]: ../../../public-networks/how-to/use-besu-api/authenticate.md#1-generate-a-private-and-public-key-pair +[Use the authentication token to make requests]: ../../../public-networks/how-to/use-besu-api/authenticate.md#using-an-authentication-token-to-make-requests +[Quorum to Tessera (Q2T)]: https://docs.tessera.consensys.net/Reference/TesseraAPI + + + +\*[JWT]: JSON Web Token diff --git a/versioned_docs/version-23.10.1/private-networks/tutorials/privacy/quickstart.md b/versioned_docs/version-23.10.1/private-networks/tutorials/privacy/quickstart.md new file mode 100644 index 00000000000..2c467736ed0 --- /dev/null +++ b/versioned_docs/version-23.10.1/private-networks/tutorials/privacy/quickstart.md @@ -0,0 +1,160 @@ +--- +description: Hyperledger Besu privacy-enabled private network tutorial +tags: + - private networks +--- + +# Create a privacy-enabled network using the Quorum Developer Quickstart + +You can create a privacy-enabled network using the [Quorum Developer Quickstart](../quickstart.md). It runs a private Hyperledger Besu network that uses [Tessera](https://docs.tessera.consensys.net/en/stable/) as its private transaction manager. + +You can use the [Block Explorer](../quickstart.md#block-explorer), make [JSON-RPC requests](../quickstart.md#run-json-rpc-requests), and [create transactions using MetaMask](../quickstart.md#create-a-transaction-using-metamask). This tutorial describes how to make private transactions between nodes, and perform read and write operations on private contracts. + +:::important + +This tutorial runs a private network suitable for education or demonstration purposes and is not intended for running production networks. + +::: + +## Prerequisites + +To run this tutorial, you must have the following installed: + +- [Docker and Docker-compose](https://docs.docker.com/compose/install/) + + :::important + + If using [MacOS](https://docs.docker.com/docker-for-mac/) or [Windows](https://docs.docker.com/docker-for-windows/), enable Docker to use up to 6GB of memory on the _Advanced_ tab in _Preferences_. + + ::: + +- [Nodejs](https://nodejs.org/en/download/) +- [Git command line](https://git-scm.com/) +- [Curl command line](https://curl.haxx.se/download.html). + +## Create Docker-compose file + +## Usage + +To create the docker-compose file and artifacts, run: + +```bash +npx quorum-dev-quickstart +``` + +Follow the prompts displayed to run Hyperledger Besu, private transactions, and [logging with ELK](../../how-to/monitor/elastic-stack.md). Enter `n` for [Codefi Orchestrate](https://docs.orchestrate.consensys.net/en/stable/). + +## Start the network + +:::caution + +If running in Windows, please run commands from the GitBash shell + +::: + +In the installation directory, start the network: + +```bash +./run.sh +``` + +The script pulls the Docker images starts the network. Pulling the images takes a few minutes the first time. The network details display. + +```bash +************************************* +Quorum Dev Quickstart +************************************* +Setting up the index patterns in kibana ................. +---------------------------------- +List endpoints and services +---------------------------------- +JSON-RPC HTTP service endpoint : http://localhost:8545 +JSON-RPC WebSocket service endpoint : ws://localhost:8546 +Web block explorer address : http://localhost:25000/ +Prometheus address : http://localhost:9090/graph +Grafana address : http://localhost:3000/d/XE4V0WGZz/besu-overview?orgId=1&refresh=10s&from=now-30m&to=now&var-system=All +Collated logs using Kibana endpoint : http://localhost:5601/app/kibana#/discover + +For more information on the endpoints and services, refer to README.md in the installation directory. +**************************************************************** +``` + +## Deploy the private contract and interact with the nodes + +To deploy a private contract to another [privacy group](../../concepts/privacy/privacy-groups.md) member, use the [web3js-quorum](https://consensys.github.io/web3js-quorum/latest/index.html) library and the [`eea_sendRawTransaction`](../../../public-networks/reference/api/index.md#eea_sendrawtransaction) API call. You must use this API call instead of [`eth_sendTransaction`](https://ethereum.github.io/execution-apis/api-documentation) because Hyperledger Besu keeps account management separate for stronger security. + +This example uses the [web3js](https://www.npmjs.com/package/web3) library to make the API calls, the example creates three Besu nodes, with each node having a corresponding Tessera node for privacy. You can access the Besu member nodes for API calls on the following ports: + +```bash +Member1Besu RPC: http://localhost:20000 +Member1Tessera: http://localhost:9081 + +Member2Besu RPC: http://localhost:20002 +Member2Tessera: http://localhost:9082 + +Member3Besu RPC: http://localhost:20004 +Member3Tessera: http://localhost:9083 +``` + +Navigate to the `smart_contracts` directory and deploy the private transaction: + +```bash +cd smart_contracts +npm install +node scripts/private/private_tx.js +``` + +The script deploys the contract and sends an arbitrary value (47) from `Member1` to `Member3`. Once done, it queries all three members (Tessera) to check the value at an address. Only `Member1` & `Member3` has this information as they were involved in the transaction, `Member2` responds with a `0x` to indicate it is unaware of the transaction. + +```bash +node scripts/private/private_tx.js +Creating contract... +Getting contractAddress from txHash: 0xc1b57f6a7773fe887afb141a09a573d19cb0fdbb15e0f2b9ed0dfead6f5b5dbf +Waiting for transaction to be mined ... +Address of transaction: 0x8220ca987f7bb7f99815d0ef64e1d8a072a2c167 +Use the smart contracts 'get' function to read the contract's constructor initialized value .. +Waiting for transaction to be mined ... +Member1 value from deployed contract is: 0x000000000000000000000000000000000000000000000000000000000000002f +Use the smart contracts 'set' function to update that value to 123 .. - from member1 to member3 +Transaction hash: 0x387c6627fe87e235b0f2bbbe1b2003a11b54afc737dca8da4990d3de3197ac5f +Waiting for transaction to be mined ... +Verify the private transaction is private by reading the value from all three members .. +Waiting for transaction to be mined ... +Member1 value from deployed contract is: 0x000000000000000000000000000000000000000000000000000000000000007b +Waiting for transaction to be mined ... +Member2 value from deployed contract is: 0x +Waiting for transaction to be mined ... +Member3 value from deployed contract is: 0x000000000000000000000000000000000000000000000000000000000000007b +``` + +The general contract deployment flow is: + +1. Deploy a contract, which returns a transaction hash. + +1. Obtain the privacy transaction receipt from the transaction hash. + +1. Use the contract address in the privacy transaction receipt to [interact with the contract](../contracts/interact.md) from that point on. + +## Further examples + +View the [web3js-quorum client library example](web3js-quorum.md) and view the [sample code examples](https://github.com/ConsenSys/web3js-quorum/tree/master/example). + +You can also test the erc20 token example by executing `erc20.js` which deploys a `HumanStandardToken` contract and transfers 1 token to Node2. + +This can be verified from the `data` field of the `logs` which is `1`. + +## Stop the network + +Do one of the following to stop the network: + +- Stop the network: + + ```bash + ./stop.sh + ``` + +- Stop the network and remove the containers and volumes: + + ```bash + ./remove.sh + ``` diff --git a/versioned_docs/version-23.10.1/private-networks/tutorials/privacy/web3js-quorum.md b/versioned_docs/version-23.10.1/private-networks/tutorials/privacy/web3js-quorum.md new file mode 100644 index 00000000000..c4c7fd0f92d --- /dev/null +++ b/versioned_docs/version-23.10.1/private-networks/tutorials/privacy/web3js-quorum.md @@ -0,0 +1,120 @@ +--- +title: Use the web3js-quorum multi-node example +sidebar_position: 3 +description: web3js-quorum client library multi-node example +tags: + - private networks +--- + +# Use the multi-node example in the web3js-quorum client library + +To use the examples provided in the web3js-quorum library with [your privacy network](index.md): + +:::note + +This example uses 3 of the 4 nodes configured in the [privacy tutorial](index.md). + +::: + +1. Clone the **ConsenSys/web3js-quorum** repository: + + ```bash + git clone https://github.com/ConsenSys/web3js-quorum + ``` + +2. In the `web3js-quorum` directory: + + ```bash + npm install + ``` + +3. In the `example` directory, update the `keys.js` file to include: + + - chain ID + - Tessera node public keys + - Hyperledger Besu node RPC URLs + - [Hyperledger Besu node private keys](../../../public-networks/concepts/node-keys.md#node-private-key). + +4. In the `example/multiNodeExample` directory, deploy the contract: + + ```bash + node deployContract.js + ``` + + A private transaction receipt returns. + + ```text + Transaction Hash 0x23b57ddc3ecf9c9a548e4401a411420ffc0002fd259a86d5656add7c6108beeb + Waiting for transaction to be mined ... + Private Transaction Receipt + { contractAddress: '0xfee84481da8f4b9a998dfacb38091b3145bb01ab', + from: '0x9811ebc35d7b06b3fa8dc5809a1f9c52751e1deb', + to: null, + output: + '0x6080604052600436106100565763ffffffff7c01000000000000000000000000000000000000000000000000000000006000350416633fa4f245811461005b5780636057361d1461008257806367e404ce146100ae575b600080fd5b34801561006757600080fd5b506100706100ec565b60408051918252519081900360200190f35b34801561008e57600080fd5b506100ac600480360360208110156100a557600080fd5b50356100f2565b005b3480156100ba57600080fd5b506100c3610151565b6040805173ffffffffffffffffffffffffffffffffffffffff9092168252519081900360200190f35b60025490565b604080513381526020810183905281517fc9db20adedc6cf2b5d25252b101ab03e124902a73fcb12b753f3d1aaa2d8f9f5929181900390910190a16002556001805473ffffffffffffffffffffffffffffffffffffffff191633179055565b60015473ffffffffffffffffffffffffffffffffffffffff169056fea165627a7a72305820c7f729cb24e05c221f5aa913700793994656f233fe2ce3b9fd9a505ea17e8d8a0029', + logs: [] } + ``` + + :::note + + If you receive a `Method not enabled` error, ensure you enabled the appropriate APIs using the [`--rpc-http-api`](../../../public-networks/reference/cli/options.md#rpc-http-api) + + ::: + +5. Copy the contract address from the private transaction receipt and set the `CONTRACT_ADDRESS` environment variable: + + ```bash + export CONTRACT_ADDRESS= + ``` + + :::tip example + ```bash + export CONTRACT_ADDRESS=0xfee84481da8f4b9a998dfacb38091b3145bb01ab + ``` + ::: + +6. Store a value in the contract from Node 1: + + ```bash + node storeValueFromNode1.js + ``` + + Node 1 stores the value of 1000 (3e8 in hex) and is visible to Node 1 and Node 2. + + ```bash + Transaction Hash: 0xd9d71cc6f64675e1a48183ded8f08930af317eb883ebae4c4eec66ae68618d85 + Waiting for transaction to be mined ... + Event Emited: 0x0000000000000000000000009811ebc35d7b06b3fa8dc5809a1f9c52751e1deb00000000000000000000000000000000000000000000000000000000000003e8 + Waiting for transaction to be mined ... + Get Value from http://localhost:8545: 0x00000000000000000000000000000000000000000000000000000000000003e8 + Waiting for transaction to be mined ... + Get Value from http://localhost:8546: 0x00000000000000000000000000000000000000000000000000000000000003e8 + Waiting for transaction to be mined ... + Get Value from http://localhost:8547: 0x + ``` + +7. Store a value in the contract from Node 2: + + ```bash + node storeValueFromNode2.js + ``` + + Node 2 stores the value of 42 (2a in hex) and is visible to Node 1 and Node 2. + + ```text + Transaction Hash: 0xa025433aec47a71b0230f12f43708812fd38ff7b7c1dc89a715f71dcbd5fbdbf + Waiting for transaction to be mined ... + Event Emited: 0x000000000000000000000000372a70ace72b02cc7f1757183f98c620254f9c8d000000000000000000000000000000000000000000000000000000000000002a + Waiting for transaction to be mined ... + Get Value from http://localhost:8545: 0x000000000000000000000000000000000000000000000000000000000000002a + Waiting for transaction to be mined ... + Get Value from http://localhost:8546: 0x000000000000000000000000000000000000000000000000000000000000002a + Waiting for transaction to be mined ... + Get Value from http://localhost:8547: 0x + ``` + + :::note + + As expected, log messages indicate that Node 3 Tessera cannot find payloads because Node 3 does not have access to the private transactions between Node 1 and Node 2. + + ::: diff --git a/versioned_docs/version-23.10.1/private-networks/tutorials/qbft.md b/versioned_docs/version-23.10.1/private-networks/tutorials/qbft.md new file mode 100644 index 00000000000..a8c2234ee1a --- /dev/null +++ b/versioned_docs/version-23.10.1/private-networks/tutorials/qbft.md @@ -0,0 +1,377 @@ +--- +title: Create a QBFT network +sidebar_position: 2 +description: Create a private network using the QBFT consensus protocol. +tags: + - private networks +--- + +# Create a private network using QBFT + +A private network provides a configurable network for testing. This private network uses the [QBFT (proof of authority) consensus protocol](../how-to/configure/consensus/qbft.md). + +The QBFT network in this tutorial implements the [block header validator selection method] to manage validators. For a tutorial on how to implement the [contract validator selection method], follow the steps in the [example smart contract repository]. + +:::important + +The steps in this tutorial create an isolated, but not protected or secure, Ethereum private network. We recommend running the private network behind a properly configured firewall. + +This tutorial configures a private network using QBFT for educational purposes only. QBFT requires 4 validators to be Byzantine fault tolerant. + +::: + +## Prerequisites + +- [Hyperledger Besu](../get-started/install/binary-distribution.md) +- [Curl (or similar webservice client)](https://curl.haxx.se/download.html). + +## Steps + +Listed on the right-hand side of the page are the steps to create a private network using QBFT with four nodes. The four nodes are all validators. + +### 1. Create directories + +Each node requires a data directory for the blockchain data. + +Create directories for your private network, each of the four nodes, and a data directory for each node: + +```bash +QBFT-Network/ +├── Node-1 +│ ├── data +├── Node-2 +│ ├── data +├── Node-3 +│ ├── data +└── Node-4 + ├── data +``` + +### 2. Create a configuration file + +The configuration file defines the [QBFT genesis file](../how-to/configure/consensus/qbft.md#genesis-file) and the number of node key pairs to generate. + +The configuration file has two nested JSON nodes. The first is the `genesis` property defining the QBFT genesis file, except for the `extraData` string, which Besu generates automatically in the resulting genesis file. The second is the `blockchain` property defining the number of key pairs to generate. + +Copy the following configuration file definition to a file called `qbftConfigFile.json` and save it in the `QBFT-Network` directory: + +```json +{ + "genesis": { + "config": { + "chainId": 1337, + "berlinBlock": 0, + "qbft": { + "blockperiodseconds": 2, + "epochlength": 30000, + "requesttimeoutseconds": 4 + } + }, + "nonce": "0x0", + "timestamp": "0x58ee40ba", + "gasLimit": "0x47b760", + "difficulty": "0x1", + "mixHash": "0x63746963616c2062797a616e74696e65206661756c7420746f6c6572616e6365", + "coinbase": "0x0000000000000000000000000000000000000000", + "alloc": { + "fe3b557e8fb62b89f4916b721be55ceb828dbd73": { + "privateKey": "8f2a55949038a9610f50fb23b5883af3b4ecb3c3bb792cbcefbd1542c692be63", + "comment": "private key and this comment are ignored. In a real chain, the private key should NOT be stored", + "balance": "0xad78ebc5ac6200000" + }, + "627306090abaB3A6e1400e9345bC60c78a8BEf57": { + "privateKey": "c87509a1c067bbde78beb793e6fa76530b6382a4c0241e5e4a9ec0a0f44dc0d3", + "comment": "private key and this comment are ignored. In a real chain, the private key should NOT be stored", + "balance": "90000000000000000000000" + }, + "f17f52151EbEF6C7334FAD080c5704D77216b732": { + "privateKey": "ae6ae8e5ccbfb04590405997ee2d52d2b330726137b875053c36d94e974d162f", + "comment": "private key and this comment are ignored. In a real chain, the private key should NOT be stored", + "balance": "90000000000000000000000" + } + } + }, + "blockchain": { + "nodes": { + "generate": true, + "count": 4 + } + } +} +``` + +:::note + +We recommend specifying the latest [milestone](../../public-networks/reference/genesis-items.md#milestone-blocks) when creating the genesis file for a private network. This ensures you are using the most up-to-date protocol and have access to the most recent opcodes. + +::: + +:::warning + +Do not use the accounts in `alloc` in the genesis file on Mainnet or any public network except for testing. The private keys display, which means the accounts are not secure. + +::: + +### 3. Generate node keys and a genesis file + +In the `QBFT-Network` directory, generate the node key and genesis file: + +```bash +besu operator generate-blockchain-config --config-file=qbftConfigFile.json --to=networkFiles --private-key-file-name=key +``` + +Besu creates the following in the `networkFiles` directory: + +- `genesis.json` - The genesis file including the `extraData` property specifying the four nodes are validators. +- A directory for each node named using the node address and containing the public and private key for each node. + +```text +networkFiles/ +├── genesis.json +└── keys + ├── 0x438821c42b812fecdcea7fe8235806a412712fc0 + │ ├── key + │ └── key.pub + ├── 0xca9c2dfa62f4589827c0dd7dcf48259aa29f22f5 + │ ├── key + │ └── key.pub + ├── 0xcd5629bd37155608a0c9b28c4fd19310d53b3184 + │ ├── key + │ └── key.pub + └── 0xe96825c5ab8d145b9eeca1aba7ea3695e034911a + ├── key + └── key.pub +``` + +### 4. Copy the genesis file to the QBFT-Network directory + +Copy the `genesis.json` file to the `QBFT-Network` directory. + +### 5. Copy the node private keys to the node directories + +For each node, copy the key files to the `data` directory for that node + +```text +QBFT-Network/ +├── genesis.json +├── Node-1 +│ ├── data +│ │ ├── key +│ │ ├── key.pub +├── Node-2 +│ ├── data +│ │ ├── key +│ │ ├── key.pub +├── Node-3 +│ ├── data +│ │ ├── key +│ │ ├── key.pub +├── Node-4 +│ ├── data +│ │ ├── key +│ │ ├── key.pub +``` + +### 6. Start the first node as the bootnode + +In the `Node-1` directory, start Node-1: + + + +# MacOS + +```bash +besu --data-path=data --genesis-file=../genesis.json --rpc-http-enabled --rpc-http-api=ETH,NET,QBFT --host-allowlist="*" --rpc-http-cors-origins="all" +``` + +# Windows + +```bash +besu --data-path=data --genesis-file=..\genesis.json --rpc-http-enabled --rpc-http-api=ETH,NET,QBFT --host-allowlist="*" --rpc-http-cors-origins="all" +``` + + + +The command line: + +- Specifies the data directory for Node-1 using the [`--data-path`](../../public-networks/reference/cli/options.md#data-path) option. +- Enables the JSON-RPC API using the [`--rpc-http-enabled`](../../public-networks/reference/cli/options.md#rpc-http-enabled) option. +- Enables the ETH, NET, and QBFT APIs using the [`--rpc-http-api`](../../public-networks/reference/cli/options.md#rpc-http-api) option. +- Enables all-host access to the HTTP JSON-RPC API using the [`--host-allowlist`](../../public-networks/reference/cli/options.md#host-allowlist) option. +- Enables all-domain access to the node through the HTTP JSON-RPC API using the [`--rpc-http-cors-origins`](../../public-networks/reference/cli/options.md#rpc-http-cors-origins) option. + +When the node starts, the [enode URL](../../public-networks/concepts/node-keys.md#enode-url) displays. Copy the enode URL to specify Node-1 as the bootnode in the following steps. + +![Node 1 Enode URL](../../assets/images/EnodeStartup.png) + +### 7. Start Node-2 + +Start another terminal, change to the `Node-2` directory and start Node-2 specifying the Node-1 enode URL copied when starting Node-1 as the bootnode: + + + +# MacOS + +```bash +besu --data-path=data --genesis-file=../genesis.json --bootnodes= --p2p-port=30304 --rpc-http-enabled --rpc-http-api=ETH,NET,QBFT --host-allowlist="*" --rpc-http-cors-origins="all" --rpc-http-port=8546 +``` + +# Windows + +```bash +besu --data-path=data --genesis-file=..\genesis.json --bootnodes= --p2p-port=30304 --rpc-http-enabled --rpc-http-api=ETH,NET,QBFT --host-allowlist="*" --rpc-http-cors-origins="all" --rpc-http-port=8546 +``` + + + +The command line specifies: + +- The data directory for Node-2 using the [`--data-path`](../../public-networks/reference/cli/options.md#data-path) option. +- A different port to Node-1 for P2P discovery using the [`--p2p-port`](../../public-networks/reference/cli/options.md#p2p-port) option. +- A different port to Node-1 for HTTP JSON-RPC using the [`--rpc-http-port`](../../public-networks/reference/cli/options.md#rpc-http-port) option. +- The enode URL of Node-1 using the [`--bootnodes`](../../public-networks/reference/cli/options.md#bootnodes) option. +- Other options as for [Node-1](#6-start-the-first-node-as-the-bootnode). + +### 8. Start Node-3 + +Start another terminal, change to the `Node-3` directory and start Node-3 specifying the Node-1 enode URL copied when starting Node-1 as the bootnode: + + + +# MacOS + +```bash +besu --data-path=data --genesis-file=../genesis.json --bootnodes= --p2p-port=30305 --rpc-http-enabled --rpc-http-api=ETH,NET,QBFT --host-allowlist="*" --rpc-http-cors-origins="all" --rpc-http-port=8547 +``` + +# Windows + +```bash +besu --data-path=data --genesis-file=..\genesis.json --bootnodes= --p2p-port=30305 --rpc-http-enabled --rpc-http-api=ETH,NET,QBFT --host-allowlist="*" --rpc-http-cors-origins="all" --rpc-http-port=8547 +``` + + + +The command line specifies: + +- The data directory for Node-3 using the [`--data-path`](../../public-networks/reference/cli/options.md#data-path) option. +- A different port to Node-1 and Node-2 for P2P discovery using the [`--p2p-port`](../../public-networks/reference/cli/options.md#p2p-port) option. +- A different port to Node-1 and Node-2 for HTTP JSON-RPC using the [`--rpc-http-port`](../../public-networks/reference/cli/options.md#rpc-http-port) option. +- The bootnode as for [Node-2](#7-start-node-2). +- Other options as for [Node-1](#6-start-the-first-node-as-the-bootnode). + +### 9. Start Node-4 + +Start another terminal, change to the `Node-4` directory and start Node-4 specifying the Node-1 enode URL copied when starting Node-1 as the bootnode: + + + +# MacOS + +```bash +besu --data-path=data --genesis-file=../genesis.json --bootnodes= --p2p-port=30306 --rpc-http-enabled --rpc-http-api=ETH,NET,QBFT --host-allowlist="*" --rpc-http-cors-origins="all" --rpc-http-port=8548 +``` + +# Windows + +```bash +besu --data-path=data --genesis-file=..\genesis.json --bootnodes= --p2p-port=30306 --rpc-http-enabled --rpc-http-api=ETH,NET,QBFT --host-allowlist="*" --rpc-http-cors-origins="all" --rpc-http-port=8548 +``` + + + +The command line specifies: + +- The data directory for Node-4 using the [`--data-path`](../../public-networks/reference/cli/options.md#data-path) option. +- A different port to Node-1, Node-2, and Node-3 for P2P discovery using the [`--p2p-port`](../../public-networks/reference/cli/options.md#p2p-port) option. +- A different port to Node-1, Node-2, and Node-3 for HTTP JSON-RPC using the [`--rpc-http-port`](../../public-networks/reference/cli/options.md#rpc-http-port) option. +- The bootnode as for [Node-2](#7-start-node-2). +- Other options as for [Node-1](#6-start-the-first-node-as-the-bootnode). + +### 10. Confirm the private network is working + +Start another terminal, use curl to call the JSON-RPC API [`qbft_getvalidatorsbyblocknumber`](../reference/api/index.md#qbft_getvalidatorsbyblocknumber) method and confirm the network has four validators: + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"qbft_getValidatorsByBlockNumber","params":["latest"], "id":1}' localhost:8545 +``` + +The result displays the four validators: + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": [ + "0x73ced0bd3def2e2d9859e3bd0882683a2e6835fb", + "0x7a175f3542ceb60bf80fb536b3f42e7a30c0a6d7", + "0x7f6efa6e34f8c9b591a9ad4763e21b3fca31bcd6", + "0xc64140f1c9d5bb82e54976e568ad39958c3e94be" + ] +} +``` + +Look at the logs to confirm Besu is producing blocks: + +```bash +2021-05-26 08:47:00.221+10:00 | EthScheduler-Workers-0 | INFO | PersistBlockTask | Imported #1 / 0 tx / 0 om / 0 (0.0%) gas / (0x4ee4456536e2793523df87288fae76518089eec91c3f7e05e220f1f4d3f6f95b) in 0.016s. Peers: 4 +2021-05-26 08:47:02.071+10:00 | pool-8-thread-1 | INFO | QbftBesuControllerBuilder | Imported #2 / 0 tx / 0 pending / 0 (0.0%) gas / (0x6fc47ada7146d75f6a46911d8d4038795b0c99970bbd4ce0c6d6aa60955f66fe) +2021-05-26 08:47:04.051+10:00 | pool-8-thread-1 | INFO | QbftBesuControllerBuilder | Imported #3 / 0 tx / 0 pending / 0 (0.0%) gas / (0x3cb663880a65103266b11a8d8631beca5c482d515ac287125aa077b2e31b80b0) +2021-05-26 08:47:06.058+10:00 | pool-8-thread-1 | INFO | QbftBesuControllerBuilder | Produced #4 / 0 tx / 0 pending / 0 (0.0%) gas / (0xc2927915ac0c94bab5fc9acea6608455f1c857d69e97191dc2c39e4ac411817b) +2021-05-26 08:47:08.058+10:00 | pool-8-thread-1 | INFO | QbftBesuControllerBuilder | Imported #5 / 0 tx / 0 pending / 0 (0.0%) gas / (0xba63471d62c936733add9b884f5213c3842af9f52460268e39e0666ab82f02a5) +``` + +:::important + +If the key files were not copied to the correct directory in [step 5](#5-copy-the-node-private-keys-to-the-node-directories), the network will not start producing blocks. + +The logs for each node should indicate the public key was loaded from the `data/key` directory: + +```bash +2021-05-26 08:43:16.592+10:00 | main | INFO | KeyPairUtil | Loaded public key 0x931d32f1aec4e45b150ee38f3c74157a750fc53f523e63fe2b07bf3fce43a3de64587fc9aaf3736444f2e3eef0eea90be3b67d18be7b5b2b7cb2fcd670416a7e from /QBFT-Network/Node-1/data/key +``` + +If the keys were not copied to the correct directory, Besu creates a key when starting up: + +```bash +2021-05-26 08:43:16.592+10:00 | main | INFO | KeyPairUtil | Generated new public key 0x1a4a2ade5ebc0a85572e2492e0cdf3e96b8928c75fa55b4425de8849850cf9b3a8cad1e27d98a3d3afac326a5e8788dbe6cc40249715c92825aebb28abe3e346 and stored it to /QBFT-Network/Node-1/data/key +``` + +If a new key was created, the validator key specified in the configuration does not match the created key and the node cannot participate in creating blocks. + +::: + +## Next steps + +Use the [QBFT API](../reference/api/index.md#qbft-methods) to remove or add validators, or import accounts to MetaMask and send transactions as described in the [Quickstart tutorial](quickstart.md#create-a-transaction-using-metamask). + +:::note + +To add or remove nodes as validators you need the node address. The directory [created for each node](#3-generate-node-keys-and-a-genesis-file) has the node address as the name. + +Besu doesn't support [private key management](../../public-networks/how-to/send-transactions.md). + +::: + +You can switch from the [block header validator selection method] configured here, to the [contract validator selection method] by updating the genesis file and [configuring a transition]. + +## Stop the nodes + +When finished using the private network, stop all nodes using ++ctrl+c++ in each terminal window. + +:::tip + +To restart the QBFT network in the future, start from [step 6](#6-start-the-first-node-as-the-bootnode). + +::: + + + +[block header validator selection method]: ../how-to/configure/consensus/qbft.md#add-and-remove-validators-using-block-headers +[contract validator selection method]: ../how-to/configure/consensus/qbft.md#add-and-remove-validators-using-a-smart-contract +[example smart contract repository]: https://github.com/ConsenSys/validator-smart-contracts +[configuring a transition]: ../how-to/configure/consensus/qbft.md#transitions + + + +\*[Byzantine fault tolerant]: Ability to function correctly and reach consensus despite nodes failing or propagating incorrect information to peers. diff --git a/versioned_docs/version-23.10.1/private-networks/tutorials/quickstart.md b/versioned_docs/version-23.10.1/private-networks/tutorials/quickstart.md new file mode 100644 index 00000000000..b54fb721347 --- /dev/null +++ b/versioned_docs/version-23.10.1/private-networks/tutorials/quickstart.md @@ -0,0 +1,628 @@ +--- +title: Quorum Developer Quickstart +sidebar_position: 1 +description: Rapidly generate a local blockchain network using the Quickstart. +tags: + - private networks +--- + +import TestAccounts from '../../global/test_accounts.md'; + +import Postman from '../../global/postman.md'; + +# Developer Quickstart + +The Quorum Developer Quickstart uses the Hyperledger Besu Docker image to run a private [IBFT 2.0](../how-to/configure/consensus/ibft.md) network of Besu nodes managed by Docker Compose. + +:::caution + +This tutorial runs a private network suitable for education or demonstration purposes and is not intended for running production networks. + +::: + +## Prerequisites + +- One of the following operating systems: + - Linux on x86_64 architecture + - macOS on an Intel processor (M1 processor not supported yet) + - Windows 64-bit edition, with: + - Windows Subsystem for Linux 2 + - Docker desktop configured to use the WSL2-based engine +- [Docker and Docker Compose](https://docs.docker.com/compose/install/) +- [Node.js](https://nodejs.org/en/download/) version 12 or higher +- [Hardhat](https://hardhat.org/hardhat-runner/docs/getting-started#overview) +- [cURL command line](https://curl.haxx.se/download.html) +- [MetaMask](https://metamask.io/) + +:::info + +Allow Docker up to 4G of memory or 6G if running the privacy examples. Refer to the **Resources** section in [Docker for Mac](https://docs.docker.com/docker-for-mac/) and [Docker Desktop](https://docs.docker.com/docker-for-windows/) for details. + +::: + +## Generate the tutorial blockchain configuration files + +To create the tutorial `docker-compose` files and artifacts, run: + +```bash +npx quorum-dev-quickstart +``` + +Follow the prompts displayed to run Hyperledger Besu and [logging with ELK](../how-to/monitor/elastic-stack.md). Enter `n` for [Codefi Orchestrate](https://docs.orchestrate.consensys.net/en/stable/) and [private transactions](../concepts/privacy/index.md). + +:::note + +If you enter `y` for private transactions, you get three Besu nodes with corresponding Tessera nodes for privacy. You can follow the [privacy walk-through](privacy/index.md), which details how to send private transactions and interact with deployed private contracts. + +::: + +## Start the network + +To start the network, go to the installation directory (`quorum-test-network` if you used the default value) and run: + +```bash +./run.sh +``` + +The script builds the Docker images, and runs the Docker containers. + +Four Besu IBFT 2.0 validator nodes and a non-validator node are created to simulate a base network. + +When execution is successfully finished, the process lists the available services: + +```log title="Services list" +************************************* +Quorum Dev Quickstart +************************************* +---------------------------------- +List endpoints and services +---------------------------------- +JSON-RPC HTTP service endpoint : http://localhost:8545 +JSON-RPC WebSocket service endpoint : ws://localhost:8546 +Web block explorer address : http://localhost:25000/ +Prometheus address : http://localhost:9090/graph +Grafana address : http://localhost:3000/d/XE4V0WGZz/besu-overview?orgId=1&refresh=10s&from=now-30m&to=now&var-system=All +Kibana logs address : http://localhost:5601/app/kibana#/discover +Collated logs using Grafana Loki : http://localhost:3000/d/Ak6eXLsPxFemKYKEXfcH/quorum-logs-loki?orgId=1&var-app=besu&var-search= + +For more information on the endpoints and services, refer to README.md in the installation directory. +**************************************************************** +``` + +- Use the **JSON-RPC HTTP service endpoint** to access the RPC node service from your dapp or from cryptocurrency wallets such as MetaMask. +- Use the **JSON-RPC WebSocket service endpoint** to access the Web socket node service from your dapp. +- Use the **Web block explorer address** to display the [block explorer Web application](http://localhost:25000). +- Use the **Prometheus address** to access the [Prometheus dashboard](http://localhost:9090/graph). [Read more about metrics](../../public-networks/how-to/monitor/metrics.md). +- Use the **Grafana address** to access the [Grafana dashboard](http://localhost:3000/d/XE4V0WGZz/besu-overview?orgId=1&refresh=10s&from=now-30m&to=now&var-system=All). [Read more about metrics](../../public-networks/how-to/monitor/metrics.md). +- Use the **Kibana logs address** to access the [logs in Kibana](http://localhost:5601/app/kibana#/discover). [Read more about log management](../how-to/monitor/elastic-stack.md). +- Use the **Grafana Loki logs address** to access the [logs in Grafana](http://localhost:3000/d/Ak6eXLsPxFemKYKEXfcH/quorum-logs-loki?orgId=1&var-app=besu&var-search=). [Read more about log management](../how-to/monitor/loki.md). + +To display the list of endpoints again, run: + +```bash +./list.sh +``` + +## Use a block explorer + +You can [use Chainlens Blockchain Explorer](../how-to/monitor/chainlens.md) to analyze block +information, contract metadata, transaction searches, and more. +Chainlens has built-in support for privacy-enabled Besu networks. + +:::note +You must connect to one of the privacy nodes (for example, `member1besu`), not the dedicated RPC, +to allow access for Besu [privacy API methods](../reference/api/index.md#priv-methods). +In production networks, you must [secure access](../../public-networks/how-to/use-besu-api/authenticate.md) +to RPC nodes. +::: + +Clone the [Chainlens GitHub repository](https://github.com/web3labs/chainlens-free): + +```bash +git clone https://github.com/web3labs/chainlens-free +``` + +From the `docker-compose` directory, run the following command: + +```bash +cd docker-compose +NODE_ENDPOINT=member1besu PORT=26000 docker-compose -f docker-compose.yml -f chainlens-extensions/docker-compose-quorum-dev-quickstart.yml up +``` + +Open `http://localhost/` on your browser. +You’ll see the new initialization page while it boots up. +This may take 5–10 minutes for the all services to start and the ingestion sync to complete. + +To stop all the services from running, run the following command from the `docker-compose` directory: + +```bash +docker-compose down -v +``` + +## Monitor nodes with Prometheus and Grafana + +The sample network also includes Prometheus and Grafana monitoring tools to let you visualize node health and usage. You can directly access these tools from your browser at the addresses displayed in the endpoint list. + +- [Prometheus dashboard](http://localhost:9090/graph) +- [Grafana dashboard](http://localhost:3000/d/XE4V0WGZz/besu-overview?orgId=1&refresh=10s&from=now-30m&to=now&var-system=All) +- [Grafana Loki logs dashboard](http://localhost:3000/d/Ak6eXLsPxFemKYKEXfcH/quorum-logs-loki?orgId=1&var-app=quorum&var-search=) + +For more details on how to configure and use these tools for your own nodes, see the [performance monitoring documentation](../../public-networks/how-to/monitor/metrics.md), [Prometheus documentation](https://prometheus.io/docs/introduction/overview/) and [Grafana documentation](https://grafana.com/docs/). + +![Grafana dashboard screenshot](../../assets/images/grafana.png) + +and collated logs via Grafana Loki + +![Grafana Loki dashboard screenshot](../../assets/images/grafana_loki.png) + +## Run JSON-RPC requests + +You can run JSON-RPC requests on: + +- HTTP with `http://localhost:8545`. +- WebSockets with `ws://localhost:8546`. + +### Run with `cURL` + +This tutorial uses [cURL](https://curl.haxx.se/download.html) to send JSON-RPC requests over HTTP. + +### Run with Postman + +You can also run all the requests with the Besu Postman collection. + + + +### Request the node version + +Run the following command from the host shell: + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"web3_clientVersion","params":[],"id":1}' http://localhost:8545 +``` + +The result displays the client version of the running node: + + + +# Result example + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": "besu/v21.1.2/linux-x86_64/oracle_openjdk-java-11" +} +``` + +# Result explanation + +- `"jsonrpc" : "2.0"` indicates that the JSON-RPC 2.0 spec format is used. +- `"id" : 1` is the request identifier used to match the request and the response. This tutorial always uses 1. +- `"result"` contains the running Besu information: + - `v21.1.2` is the running Besu version number. This may be different when you run this tutorial. + - `linux-x86_64` is the architecture used to build this version. + - `oracle_openjdk-java-11` is the JVM type and version used to build this version. This may be different when you run this tutorial. + + + +Successfully calling this method shows that you can connect to the nodes using JSON-RPC over HTTP. + +From here, you can walk through more interesting requests demonstrated in the rest of this section, or skip ahead to [Create a transaction using MetaMask](#create-a-transaction-using-metamask). + +### Count the peers + +Peers are the other nodes connected to the node receiving the JSON-RPC request. + +Poll the peer count using [`net_peerCount`](../../public-networks/reference/api/index.md#net_peercount): + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"net_peerCount","params":[],"id":1}' http://localhost:8545 +``` + +The result indicates that there are four peers (the validators): + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": "0x4" +} +``` + +### Request the most recent block number + +Call [`eth_blockNumber`](../../public-networks/reference/api/index.md#eth_blockNumber) to retrieve the number of the most recently synchronized block: + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}' http://localhost:8545 +``` + +The result indicates the highest block number synchronized on this node. + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": "0x2a" +} +``` + +Here the hexadecimal value `0x2a` translates to decimal as `42`, the number of blocks received by the node so far, about two minutes after the new network started. + +## Public transactions + +This example uses the [web3.js](https://www.npmjs.com/package/web3) library to make the API calls, using the `rpcnode` +accessed on `http://localhost:8545`. + +Navigate to the `smart_contracts` directory and deploy the public transaction: + +```bash +cd smart_contracts +npm install +node scripts/public/public_tx.js +# or via ethers +node scripts/public/public_tx_ethers.js +``` + +This deploys the contract and sends an arbitrary value (`47`) from `Member1` to `Member3`. The script then performs: + +1. A read operation on the contract using the `get` function and the contract's ABI, at the specified address. +1. A write operation using the `set` function and the contract's ABI, at the address and sets the value to `123`. +1. A read operation on all events emitted. + +The script output is as follows: + +```bash +{ + address: '0x2b224e70f606267586616586850aC6f4Ae971eCb', + privateKey: '0xb3f2ab4d7bb07a4168432fb572ceb57fd9b842ed8dc41256255db6ff95784000', + signTransaction: [Function: signTransaction], + sign: [Function: sign], + encrypt: [Function: encrypt] +} +create and sign the txn +sending the txn +tx transactionHash: 0x423d56f958a316d2691e05e158c6a3f37004c27a1ec9697cf9fed2a5c2ae2c2b +tx contractAddress: 0xB9A44d3BeF64ABfA1485215736B61880eDe630D9 +Contract deployed at address: 0xB9A44d3BeF64ABfA1485215736B61880eDe630D9 +Use the smart contracts 'get' function to read the contract's constructor initialized value .. +Obtained value at deployed contract is: 47 +Use the smart contracts 'set' function to update that value to 123 .. +sending the txn +tx transactionHash: 0xab460da2544687c5fae4089d01b14bbb9bea765449e1fd2c30b30e1761481344 +tx contractAddress: null +Verify the updated value that was set .. +Obtained value at deployed contract is: 123 +Obtained all value events from deployed contract : [47,123] +``` + +We also have a second example that shows how to transfer ETH between accounts. Navigate to the `smart_contracts` directory +and deploy the `eth_tx` transaction: + +```bash +cd smart_contracts +npm install +node scripts/public/eth_tx.js +``` + +The output is as follows: + +```bash +Account A has balance of: 90000 +Account B has balance of: 0 +create and sign the txn +sending the txn +tx transactionHash: 0x8b9d247900f2b50a8dded3c0d73ee29f04487a268714ec4ebddf268e73080f98 +Account A has an updated balance of: 89999.999999999999999744 +Account B has an updated balance of: 0.000000000000000256 +``` + +## Create a transaction using MetaMask + +You can use [MetaMask](https://metamask.io/) to send a transaction on your private network. + +1. Open MetaMask and connect it to your private network RPC endpoint by selecting `Localhost 8545` in the network list. +1. Choose one of the following test accounts and [import it into MetaMask by copying the corresponding private key](https://metamask.zendesk.com/hc/en-us/articles/360015489331-How-to-import-an-Account). + + + +:::note + +Besu doesn't incorporate [account management](../../public-networks/how-to/send-transactions.md). To create your own account, you have to use a third-party tool, such as MetaMask. + +::: + +1. After importing an existing test account, [create another test account from scratch] to use as the recipient for a test Ether transaction. + +1. In MetaMask, select the new test account and [copy its address](https://metamask.zendesk.com/hc/en-us/articles/360015289512-How-to-copy-your-MetaMask-Account-Public-Address). + +1. In the [Block Explorer](http://localhost:25000), search for the new test account by selecting the :mag: and pasting the test account address into the search box. + + The new test account displays with a zero balance. + +1. [Send test Ether](https://metamask.zendesk.com/hc/en-us/articles/360015488931-How-to-send-ETH-and-ERC-20-tokens-from-your-MetaMask-Wallet) from the first test account (containing test Ether) to the new test account (which has a zero balance). + + :::tip + + You can use a zero gas price here as this private test network is a [free gas network](../how-to/configure/free-gas.md), but the maximum amount of gas that can be used (the gas limit) for a value transaction must be at least 21000. + + ::: + +1. Refresh the Block Explorer page in your browser displaying the target test account. + + The updated balance reflects the transaction completed using MetaMask. + +## Smart contract and dapp usage + +You can use a demo dapp called QuorumToken which uses an ERC20 token that is deployed to the network. + +We'll use [Hardhat](https://www.npmjs.com/package/hardhat), [Ethers](https://www.npmjs.com/package/ethers) and [MetaMask](https://metamask.io/) to interact with the network, which involves the following steps: + +1. Deploy the contract and **save the contract's address**. +1. Start the dapp, and read and transact with the deployed token. + +The `dapps/quorumToken` directory is this structured in this manner (only relevant paths shown): + +```bash +quorumToken +├── hardhat.config.ts // hardhat network config +├── contracts // the QuorumToken.sol +├── scripts // handy scripts eg: to deploy to a chain +├── test // contract tests +└── frontend // dapp done in next.js + ├── public + ├── src + ├── styles + ├── tsconfig.json +``` + +### Deploy the contract + +Once the network is up and running, enter the `quorumToken` directory and run the following: + +```bash +# install dependencies +npm i +# compile the contract +npm run compile +npm run test +# deploy the contract to the quickstart network +npm run deploy-quorumtoken +``` +The output is similar to the following: + +```bash + +# compile +> quorumToken@1.0.0 compile +> npx hardhat compile + +Generating typings for: 5 artifacts in dir: typechain-types for target: ethers-v6 +Successfully generated 24 typings! +Compiled 5 Solidity files successfully + +# test +> quorumToken@1.0.0 test +> npx hardhat test + + QuorumToken + Deployment + âś” Should have the correct initial supply (1075ms) + âś” Should token transfer with correct balance (78ms) + + + 2 passing (1s) + +# deploy +Contract deploy at: 0x5FbDB2315678afecb367f032d93F642f64180aa3 +``` +This will deploy the contract to the network and return the address. **Please save this address for the next step**. + +### Run the dapp + +The dapp runs a local website using Next.js, and uses the contract in the previous step deployed on the network. + +With the blockchain running, and MetaMask connected to `localhost` on port `8545`, import one of [our test accounts via private key](../reference/accounts-for-testing.md), and run the following command: + +```bash +cd frontend +npm i +npm run dev +``` +This starts the dapp, binding it to port `3001` on your machine. + +```text + +> webapp@0.1.0 dev +> next dev -p 3001 + +- ready started server on [::]:3001, url: http://localhost:3001 +- event compiled client and server successfully in 270 ms (18 modules) +- wait compiling... +- event compiled client and server successfully in 173 ms (18 modules) +``` + +In the browser where you have MetaMask enabled and one of the test accounts loaded, open a new tab and navigate to +[the QuorumToken dapp](http://localhost:3001). +Connect to MetaMask and input the address from the previous step. Fox example our contract above deployed to `0x5FbDB2315678afecb367f032d93F642f64180aa3`. + +The dapp will then read the balance of the account from MetaMask and get details of the contract. You can then send funds +to another address (any of the other test accounts) on the network, and MetaMask will sign and send the transaction. + +You can also search for the transaction and view its details in the [Block Explorer](http://localhost:25000/). + +![Dapp UI](../../assets/images/dapp-explorer-tx.png) + +The MetMask UI also keeps a record of the transaction. + +![Dapp UI](../../assets/images/dapp-metamask-tx.png) + +### Deploy your own dapp + +You can deploy your own dapp to the Quorum Developer Quickstart by configuring your dapp to point to the Quickstart network. + +We recommend using [Hardhat](https://hardhat.org/hardhat-runner/docs/guides/project-setup), and you can use the sample +`hardhat.config.js` to configure the `networks` object in the [Hardhat configuration file](https://hardhat.org/hardhat-network/docs/reference#config) +to specify which networks to connect to for deployments and testing. The Quickstart's RPC service endpoint is `http://localhost:8545`. + +For example, the following is the Hardhat configuration file for the QuorumToken dapp used in the Quickstart GoQuorum network: + +```js +module.exports = { + networks: { + // in built test network to use when developing contracts + hardhat: { + chainId: 1337 + }, + quickstart: { + url: "http://127.0.0.1:8545", + chainId: 1337, + // test accounts only, all good ;) + accounts: [ + "0x8f2a55949038a9610f50fb23b5883af3b4ecb3c3bb792cbcefbd1542c692be63", + "0xc87509a1c067bbde78beb793e6fa76530b6382a4c0241e5e4a9ec0a0f44dc0d3", + "0xae6ae8e5ccbfb04590405997ee2d52d2b330726137b875053c36d94e974d162f" + ] + } + }, + defaultNetwork: "hardhat", + ... + ... +``` + +Deploy the contract using: + +```bash +npx hardhat run ./scripts/deploy_quorumtoken.ts --network quickstart +``` + +## Stop and restart the private network without removing containers + +To shut down the private network without deleting the containers: + +```bash +./stop.sh +``` + +This command stops the containers related to the services specified in the `docker-compose.yml` file. + +To restart the private network: + +```bash +./resume.sh +``` + +## Stop the private network and remove containers + +To shut down the private network and delete all containers and images created from running the sample network and the Pet Shop dapp: + +```bash +./remove.sh +``` + +## Add a new node to the network + +New nodes joining an existing network require the following: + +- The same genesis file used by all other nodes on the running network. +- A list of nodes to connect to; this is done by specifying [bootnodes], or by providing a list of [static nodes]. +- A node key pair and optionally an account. If the running network is using permissions, then you need to add the new node's enode details to the [permissions file] used by existing nodes, or update the onchain permissioning contract. + +The following steps describe the process to add a new node to the Developer Quickstart. + +### 1. Create the node key files + +Create a node key pair and account for a new node by running the following script: + +```bash +cd ./extra +npm install +node generate_node_keys.js --password "Password" +``` + +:::note + +The `--password` parameter is optional. + +::: + +### 2. Create new node directory + +Navigate to the directory where the configuration files for the network were created. + +:::note + +The directory was specified in an earlier step when running `npx quorum-dev-quickstart`. The default location is `./quorum-test-network`. + +::: + +In the `config/nodes` directory, create a subdirectory for the new node (for example, `newnode`), and move the `nodekey`, `nodekey.pub`, `address` and `accountkey` files from the previous step into this directory. + +### 3. Update docker-compose + +Add an entry for the new node into the docker-compose file: + +```yaml +newnode: + <<: *besu-def + container_name: newnode + volumes: + - public-keys:/opt/besu/public-keys/ + - ./config/besu/:/config + - ./config/nodes/newnode:/opt/besu/keys + - ./logs/besu:/tmp/besu + depends_on: + - validator1 + networks: + quorum-dev-quickstart: + ipv4_address: 172.16.239.41 +``` + +:::caution important +Select an IP address and port map not being used for the other containers. +Mount the newly created folder `./config/nodes/newnode` to the `/opt/besu/keys` directory of the new node, as seen +in this example. +::: + +### 4. Update Prometheus configuration + +Update `prometheus.yml` in the `./config/prometheus/` directory to configure metrics to display in Grafana. + +Insert the following under `scrape_configs` section in the file. Change `job_name` and `targets` appropriately if you've updated them. + +```yaml +- job_name: newnode + scrape_interval: 15s + scrape_timeout: 10s + metrics_path: /metrics + scheme: http + static_configs: + - targets: [newnode:9545] +``` + +### 5. Update files with the enode address + +Add the new node's enode address to the [static nodes] file and [permissions file]. The enode uses the format `enode://pubkey@ip_address:30303`. If the `nodekey.pub` is `4540ea...9c1d78` and the IP address is `172.16.239.41`, then the enode address is `"enode://4540ea...9c1d78@172.16.239.41:30303"`, which must be added to both files. + +Alternatively, call the [`perm_addNodesToAllowlist`](../../public-networks/reference/api/index.md#perm_addnodestoallowlist) API method on existing nodes to add the new node without restarting. + +:::note + +Calling the API method by itself only persists for as long as the nodes remain online and is lost on the next restart. + +On a live network, the new node must be added to the [permissions file] so that subsequent restarts of the nodes are aware of the change. + +::: + +### 6. Start the network + +Once complete, start the network up with `./run.sh`. When using the smart contract you can either make changes via a [dapp](https://github.com/ConsenSys/permissioning-smart-contracts) or via [RPC API calls](../../public-networks/reference/api/index.md#perm_addnodestoallowlist). + + + +[bootnodes]: ../how-to/configure/bootnodes.md +[permissions file]: ../how-to/use-permissioning/local.md +[static nodes]: ../../public-networks/how-to/connect/static-nodes.md +[allow list]: ../how-to/use-permissioning/local.md#node-allowlisting +[Import one of the existing accounts above into MetaMask]: https://metamask.zendesk.com/hc/en-us/articles/360015489331-Importing-an-Account-New-UI- +[create another test account from scratch]: https://metamask.zendesk.com/hc/en-us/articles/360015289452-Creating-Additional-MetaMask-Wallets-New-UI- diff --git a/versioned_docs/version-23.10.1/public-networks/.meta.yml b/versioned_docs/version-23.10.1/public-networks/.meta.yml new file mode 100644 index 00000000000..47f9110472f --- /dev/null +++ b/versioned_docs/version-23.10.1/public-networks/.meta.yml @@ -0,0 +1,6 @@ +--- +# Meta items setting with yaml files is an insider only feature +# see https://squidfunk.github.io/mkdocs-material/reference/#built-in-meta-plugin + +tags: + - public networks diff --git a/versioned_docs/version-23.10.1/public-networks/concepts/_category_.json b/versioned_docs/version-23.10.1/public-networks/concepts/_category_.json new file mode 100644 index 00000000000..0eb56feedb7 --- /dev/null +++ b/versioned_docs/version-23.10.1/public-networks/concepts/_category_.json @@ -0,0 +1,8 @@ +{ + "label": "Concepts", + "position": 4, + "link": { + "type": "generated-index", + "slug": "public-networks/concepts" + } +} diff --git a/versioned_docs/version-23.10.1/public-networks/concepts/data-storage-formats.md b/versioned_docs/version-23.10.1/public-networks/concepts/data-storage-formats.md new file mode 100644 index 00000000000..30802b9a080 --- /dev/null +++ b/versioned_docs/version-23.10.1/public-networks/concepts/data-storage-formats.md @@ -0,0 +1,93 @@ +--- +title: Data storage formats +sidebar_position: 3 +description: Learn about storing data using Forest of Tries and Bonsai Tries. +tags: + - public networks +--- + +# Data storage formats + +Besu offers two formats for storing the world state, [Forest of Tries](#forest-of-tries) and [Bonsai Tries](#bonsai-tries). + +## Forest of Tries + +Forest of Tries, also called forest mode, is the default storage format. + +In forest mode, each node in the trie is saved in a key-value store by hash. For each block, the world state is updated with new nodes, leaf nodes, and a new state root. Old leaf nodes remain in the underlying data store. Data is accessed and stored by hash, which increases the size of the database and increases the resources and time needed to access account data. + +

+ +![forest_of_tries](../../assets/images/forest_of_tries.png) + +

+ +### Pruning + +Pruning reduces the storage required by removing state trie nodes unreachable from [recent blocks](../../public-networks/reference/cli/options.md#pruning-blocks-retained). + +Pruning is disabled by default, and can be enabled with the [`--pruning-enabled`](../../public-networks/reference/cli/options.md#pruning-enabled) command line option. + +:::info + +Using pruning with [private transactions](../../private-networks/concepts/privacy/private-transactions)\ +isn't supported. + +::: + +Pruning might increase block import times, but it doesn't affect the ability of nodes to stay in sync. + +:::caution + +Pruning is being deprecated for [Bonsai Tries](#bonsai-tries) and is currently not being updated. + +::: + +## Bonsai Tries + +Bonsai Tries is a data storage layout policy designed to reduce storage requirements and increase read performance. + +Bonsai stores leaf values in a trie log, separate from the branches of the trie. Bonsai stores nodes by the location of the node instead of the hash of the node. Bonsai can access the leaf from the underlying storage directly using the account key. This greatly reduces the disk space needed for storage and allows for less resource-demanding and faster read performance. Bonsai inherently prunes orphaned nodes and old branches. + +To run a node with Bonsai Tries data storage format, use the command line option [`--data-storage-format=BONSAI`](../reference/cli/options.md#data-storage-format). + +

+ +![Bonsai_tries](../../assets/images/Bonsai_tries.png) + +

+ +## Forest of Tries vs. Bonsai Tries + +### Storage requirements + +Forest mode uses significantly more memory than Bonsai. With an [archive node](../get-started/connect/sync-node.md#run-an-archive-node), forest mode uses an estimated 12 TB of storage, while Bonsai uses an estimated 1100 GB of storage. With a [full node](../get-started/connect/sync-node.md#run-a-full-node), forest mode uses an estimated 750 GB of storage, while Bonsai uses an estimated 650 GB of storage. + +### Accessing data + +Forest mode must go through all the branches by hash to read a leaf value. Bonsai can access the leaf from the underlying storage directly using the account key. Bonsai will generally read faster than forest mode, particularly if the blocks are more recent. + +However, Bonsai becomes increasingly more resource-intensive the further in history you try to read data. To prevent this, you can limit how far Bonsai looks back while reconstructing data. The default limit Bonsai looks back is 512. To change the parameter, use the [`--bonsai-historical-block-limit`](../reference/cli/options.md#bonsai-historical-block-limit) option. + +:::note + +Using `--bonsai-historical-block-limit` doesn't affect the size of the database being stored, only how far back to load. This means there is no "safe minimum" value to use with this option. + +::: + +### Syncing nodes + +The following table shows the ways you can [sync a full node](../get-started/connect/sync-node.md#run-a-full-node) with the different data storage formats using [fast](../get-started/connect/sync-node.md#fast-synchronization) and [snap](../get-started/connect/sync-node.md#snap-synchronization) sync. + +| Data storage format | Sync mode | Storage estimate | Can other nodes sync to your node? | +| --- | --- | --- | --- | +| Bonsai | Fast | 650 GB | No | +| Bonsai | Snap | 650 GB | To be implemented | +| Forest | Fast | 750 GB | Yes | +| Forest | Snap | 750 GB | No | + +:::tip + +We recommend using snap sync with Bonsai for the fastest sync and lowest storage requirements. + +::: diff --git a/versioned_docs/version-23.10.1/public-networks/concepts/events-and-logs.md b/versioned_docs/version-23.10.1/public-networks/concepts/events-and-logs.md new file mode 100644 index 00000000000..c5b78fe2bbb --- /dev/null +++ b/versioned_docs/version-23.10.1/public-networks/concepts/events-and-logs.md @@ -0,0 +1,186 @@ +--- +title: Events and logs +sidebar_position: 6 +description: Learn about events and logs in Besu. +tags: + - public networks + - private networks +--- + +# Events and logs + +Transaction mining causes smart contracts to emit events and write logs to the blockchain. + +The smart contract address is the link to the logs and the blockchain includes the logs, but contracts cannot access logs. Log storage is cheaper than contract storage (that is, it costs less gas) so storing and accessing the required data in logs reduces the cost. For example, use logs to display all transfers made using a specific contract, but not the current state of the contract. + +A Dapp front end can either access logs using the [JSON-RPC API filter methods](../how-to/use-besu-api/access-logs.md) or subscribe to logs using the [RPC Pub/Sub API](../how-to/use-besu-api/rpc-pubsub.md#logs). + +Use [`admin_generateLogBloomCache`](../reference/api/index.md#admin_generatelogbloomcache) to improve log retrieval performance. + +## Topics + +Log entries contain up to four topics. The first topic is the [event signature hash](#event-signature-hash) and up to three topics are the indexed [event parameters](#event-parameters). + +```json title="A log entry for an event with one indexed parameter" +{ + "logIndex": "0x0", + "removed": false, + "blockNumber": "0x84", + "blockHash": "0x5fc573d76ec48ec80cbc43f299ebc306a8168112e3a4485c23e84e9a40f5d336", + "transactionHash": "0xcb52f02342c2498df82c49ac26b2e91e182155c8b2a2add5b6dc4c249511f85a", + "transactionIndex": "0x0", + "address": "0x42699a7612a82f1d9c36148af9c77354759b210b", + "data": "0x", + "topics": [ + "0x04474795f5b996ff80cb47c148d4c5ccdbe09ef27551820caa9c2f8ed149cce3", + "0x0000000000000000000000000000000000000000000000000000000000000001" + ] +} +``` + +## Event parameters + +Up to three event parameters can have the `indexed` attribute. Logs store these indexed parameters as `topics`. Indexed parameters are searchable and filterable. + +Topics are 32 bytes. If an indexed argument is an array (including `string` and `byte` datatypes), the log stores the keccak-256 hash of the parameter as a topic. + +Log `data` includes non-indexed parameters but is difficult to search or filter. + +A Solidity contract storing one indexed and one non-indexed parameter and has an event emitting the value of each parameter: + +```solidity +pragma solidity ^0.5.1; +contract Storage { + uint256 public valueIndexed; + uint256 public valueNotIndexed; + + event Event1(uint256 indexed valueIndexed, uint256 valueNotIndexed); + + function setValue(uint256 _valueIndexed, uint256 _valueNotIndexed) public { + valueIndexed = _valueIndexed; + valueNotIndexed = _valueNotIndexed; + emit Event1(_valueIndexed, _valueNotIndexed); + } +} +``` + +A log entry created by invoking the contract in the previous example with `valueIndexed` set to 5 and `valueNotIndexed` set to 7: + +```json +{ + "logIndex": "0x0", + "removed": false, + "blockNumber": "0x4d6", + "blockHash": "0x7d0ac7c12ac9f622d346d444c7e0fa4dda8d4ed90de80d6a28814613a4884a67", + "transactionHash": "0xe994022ada94371ace00c4e1e20663a01437846ced02f18b3f3afec827002781", + "transactionIndex": "0x0", + "address": "0x43d1f9096674b5722d359b6402381816d5b22f28", + "data": "0x0000000000000000000000000000000000000000000000000000000000000007", + "topics": [ + "0xd3610b1c54575b7f4f0dc03d210b8ac55624ae007679b7a928a4f25a709331a8", + "0x0000000000000000000000000000000000000000000000000000000000000005" + ] +} +``` + +## Event signature hash + +The first topic in a log entry is always the event signature hash. The event signature hash is a keccak-256 hash of the event name and input argument types, with argument names ignored. For example, the event `Hello(uint256 worldId)` has the signature hash `keccak('Hello(uint256)')`. The signature identifies to which event log topics belong. + +A Solidity contract with two different events: + +```solidity +pragma solidity ^0.5.1; +contract Storage { + uint256 public valueA; + uint256 public valueB; + + event Event1(uint256 indexed valueA); + event Event2(uint256 indexed valueB); + + function setValue(uint256 _valueA) public { + valueA = _valueA; + emit Event1(_valueA); + } + + function setValueAgain(uint256 _valueB) public { + valueB = _valueB; + emit Event2(_valueB); + } +} +``` + +The event signature hash for event 1 is `keccak('Event1(uint256)')` and the event signature hash for event 2 is `keccak('Event2(uint256)')`. The hashes are: + +- `04474795f5b996ff80cb47c148d4c5ccdbe09ef27551820caa9c2f8ed149cce3` for event 1 +- `06df6fb2d6d0b17a870decb858cc46bf7b69142ab7b9318f7603ed3fd4ad240e` for event 2. + +:::tip + +You can use a library keccak (sha3) hash function, such as provided in [Web3.js](https://web3js.readthedocs.io/en/v1.2.11/web3-utils.html?highlight=sha3#sha3), or an online tool, such as https://emn178.github.io/online-tools/keccak_256.html, to generate event signature hashes. + +::: + +Log entries from invoking the Solidity contract in the previous example: + +```json +[ + { + "logIndex": "0x0", + "removed": false, + "blockNumber": "0x84", + "blockHash": "0x5fc573d76ec48ec80cbc43f299ebc306a8168112e3a4485c23e84e9a40f5d336", + "transactionHash": "0xcb52f02342c2498df82c49ac26b2e91e182155c8b2a2add5b6dc4c249511f85a", + "transactionIndex": "0x0", + "address": "0x42699a7612a82f1d9c36148af9c77354759b210b", + "data": "0x", + "topics": [ + "0x04474795f5b996ff80cb47c148d4c5ccdbe09ef27551820caa9c2f8ed149cce3", + "0x0000000000000000000000000000000000000000000000000000000000000001" + ] + }, + { + "logIndex": "0x0", + "removed": false, + "blockNumber": "0x87", + "blockHash": "0x6643a1e58ad857f727552e4572b837a85b3ca64c4799d085170c707e4dad5255", + "transactionHash": "0xa95295fcea7df3b9e47ab95d2dadeb868145719ed9cc0e6c757c8a174e1fcb11", + "transactionIndex": "0x0", + "address": "0x42699a7612a82f1d9c36148af9c77354759b210b", + "data": "0x", + "topics": [ + "0x06df6fb2d6d0b17a870decb858cc46bf7b69142ab7b9318f7603ed3fd4ad240e", + "0x0000000000000000000000000000000000000000000000000000000000000002" + ] + } +] +``` + +## Topic filters + +[Filter options objects](../reference/api/objects.md#filter-options-object) have a `topics` key to filter logs by topics. + +Topics are order-dependent. A transaction with a log containing topics `[A, B]` matches with the following topic filters: + +- `[]` - Match any topic +- `[A]` - Match A in first position +- `[[null], [B]]` - Match any topic in first position AND B in second position +- `[[A],[B]]` - Match A in first position AND B in second position +- `[[A, C], [B, D]]` - Match (A OR C) in first position AND (B OR D) in second position. + +The following filter option object returns log entries for the [Event Parameters example contract](#event-parameters) with `valueIndexed` set to 5 or 9: + +```json +{ + "fromBlock": "earliest", + "toBlock": "latest", + "address": "0x43d1f9096674b5722d359b6402381816d5b22f28", + "topics": [ + ["0xd3610b1c54575b7f4f0dc03d210b8ac55624ae007679b7a928a4f25a709331a8"], + [ + "0x0000000000000000000000000000000000000000000000000000000000000005", + "0x0000000000000000000000000000000000000000000000000000000000000009" + ] + ] +} +``` diff --git a/versioned_docs/version-23.10.1/public-networks/concepts/genesis-file.md b/versioned_docs/version-23.10.1/public-networks/concepts/genesis-file.md new file mode 100644 index 00000000000..d91a237e096 --- /dev/null +++ b/versioned_docs/version-23.10.1/public-networks/concepts/genesis-file.md @@ -0,0 +1,50 @@ +--- +title: Genesis file +sidebar_position: 7 +description: Learn about configuring a network using the genesis file. +tags: + - public networks + - private networks +--- + +# Genesis file + +The genesis file defines the first block in the chain, and the first block defines which chain you want to join. + +For Ethereum Mainnet and public testnets (for example, Goerli) the genesis configuration definition is in Besu and used when specifying a public network using the [`--network`](../reference/cli/options.md#network) command line option. + +For private networks, [create a JSON genesis file](https://consensys.net/blog/quorum/hyperledger-besu-how-to-create-an-ethereum-genesis-file/), then specify the genesis file using the [`--genesis-file`](../reference/cli/options.md#genesis-file) command line option. + +The genesis file specifies the [network-wide settings](../reference/genesis-items.md), such as those for a [free gas network](../../private-networks/how-to/configure/free-gas.md), so all nodes in a network must use the same genesis file. + +:::note + +You can specify node-level settings on the command line or in the [node configuration file](../how-to/configuration-file.md). + +::: + +```json title="Example IBFT 2.0 genesis file" +{ + "config": { + "chainId": 2018, + "berlinBlock": 0, + "ibft2": { + "blockperiodseconds": 2, + "epochlength": 30000, + "requesttimeoutseconds": 4 + } + }, + "nonce": "0x0", + "timestamp": "0x58ee40ba", + "extraData": "0xf83ea00000000000000000000000000000000000000000000000000000000000000000d5949811ebc35d7b06b3fa8dc5809a1f9c52751e1deb808400000000c0", + "gasLimit": "0x1fffffffffffff", + "difficulty": "0x1", + "mixHash": "0x63746963616c2062797a616e74696e65206661756c7420746f6c6572616e6365", + "coinbase": "0x0000000000000000000000000000000000000000", + "alloc": { + "9811ebc35d7b06b3fa8dc5809a1f9c52751e1deb": { + "balance": "0xad78ebc5ac6200000" + } + } +} +``` diff --git a/versioned_docs/version-23.10.1/public-networks/concepts/network-and-chain-id.md b/versioned_docs/version-23.10.1/public-networks/concepts/network-and-chain-id.md new file mode 100644 index 00000000000..a72133d3a5e --- /dev/null +++ b/versioned_docs/version-23.10.1/public-networks/concepts/network-and-chain-id.md @@ -0,0 +1,74 @@ +--- +title: Network ID and chain ID +sidebar_position: 5 +description: Learn about network ID and chain ID in Besu. +tags: + - public networks + - private networks +--- + +# Network ID and chain ID + +Ethereum networks have two identifiers, a network ID and a chain ID. Although they often have the same value, they have different uses. + +Peer-to-peer communication between nodes uses the _network ID_, while the transaction signature process uses the _chain ID_. + +:::note + +[EIP-155](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-155.md) introduced using the chain ID as part of the transaction signing process to protect against transaction replay attacks. + +::: + +For most networks, including Mainnet and the public testnets, the network ID and the chain ID are the same, with the network ID defaulting to the chain ID, as specified in the genesis file. + +```json title="Chain ID in the genesis file" +{ + "config": { + "ethash": { + }, + "chainID": 1981 + }, + ... +} +``` + +Besu sets the chain ID (and by default the network ID) automatically, using either the [`--genesis-file`](../reference/cli/options.md#genesis-file) option or when specifying a network using the [`--network`](../reference/cli/options.md#network) option. The following table lists the available networks and their chain and network IDs. + +| Network | Chain | Chain ID | Network ID | Type | +| --------- | ----- | -------- | ---------- | ----------- | +| `mainnet` | ETH | 1 | 1 | Production | +| `goerli` | ETH | 5 | 5 | Test | +| `sepolia` | ETH | 11155111 | 11155111 | Test | +| `dev` | ETH | 2018 | 2018 | Development | +| `classic` | ETC | 61 | 1 | Production | +| `mordor` | ETC | 63 | 7 | Test | + +:::info + +The Ropsten, Rinkeby, and Kiln testnets are deprecated. + +::: + +## Specify a different network ID + +Usually the network ID is the same as the chain ID, but if you want to separate specific nodes from the rest of the network so they can't connect or synchronize with other nodes, you can override the default network ID for those nodes using the [`--network-id`](../reference/cli/options.md#network-id) option. + +## Start a new chain with a new chain ID + +If you update the chain ID (or network ID) of existing nodes, they can no longer peer with other nodes in the network. Nodes need to have a matching [genesis file](genesis-file.md), including the chain ID, in order to peer. In this case, you're effectively running two chains that can't communicate with each other. + +To change a chain ID and start a new chain: + +1. Stop all your nodes using ctrl+c in each terminal window. +2. Update the [genesis file](genesis-file.md) with the new chain ID. +3. Make sure all nodes have the same genesis file. +4. Delete the old data directory or point to a new location for each node. +5. [Restart the nodes](../../private-networks/tutorials/ibft/index.md#6-start-the-first-node-as-the-bootnode). + +:::danger Warning + +Starting a new chain is starting from block zero. + +This means when you start a new chain with a new chain ID, you lose all previous data. + +::: diff --git a/versioned_docs/version-23.10.1/public-networks/concepts/node-keys.md b/versioned_docs/version-23.10.1/public-networks/concepts/node-keys.md new file mode 100644 index 00000000000..01f1c98a31a --- /dev/null +++ b/versioned_docs/version-23.10.1/public-networks/concepts/node-keys.md @@ -0,0 +1,104 @@ +--- +title: Node keys +sidebar_position: 8 +description: Learn about node public and private keys, and the node address. +tags: + - public networks + - private networks +--- + +# Node keys and node address + +Each node has a private and public key pair, and a node address. Hyperledger Besu uses the private and public key pair to sign and verify transactions, and the node address as an identifier for the node. + +## Node private key + +When starting Hyperledger Besu, if the [`--node-private-key-file`](../reference/cli/options.md#node-private-key-file) option is not specified and a `key` file does not exist in the data directory for the node, Besu generates a node private key and writes it to the `key` file. + +If a `key` file does exist in the data directory when starting Besu, the node starts using the private key in the `key` file. + +:::info + +The private key is not encrypted. + +::: + +## Node public key + +The node public key displays in the log after starting Besu. Also referred to as the node ID, the node public key forms part of the enode URL of a node. + +You can export the node public key, either to standard output or to a specified file, using the [`public-key export`](../reference/cli/subcommands.md#public-key) subcommand. + +## Node address + +Besu generates the node address by creating a hash of the node public key and using the last 20 bytes of the hash as the node address. It is also displayed in the logs after starting Besu. + +You can export the node address, either to standard output or to a specified file, using the [`public-key export-address`](../reference/cli/subcommands.md#public-key) subcommand. + +## Specify a custom node private key file + +Use the [`--node-private-key-file`](../reference/cli/options.md#node-private-key-file) option to specify a custom `key` file in any location. + +If the `key` file exists, the node starts with the private key in the `key` file. If the `key` file does not exist, Besu generates a node private key and writes it to the `key` file. + +For example, the following command either reads the node private key from `privatekeyfile` or writes a generated private key to `privatekeyfile`. + +```bash +besu --node-private-key-file="/Users/username/privatekeyfile" +``` + +## Enode URL + +The enode URL identifies a node. For example, the [`--bootnodes`](../reference/cli/options.md#bootnodes) option and the [`perm_addNodesToAllowlist`](../reference/api/index.md#perm_addnodestoallowlist) method specify nodes by enode URL. + +The enode URL format is `enode://@[?discport=]` where: + +- `` is the node public key, excluding the initial 0x. +- `` is the host and TCP port the bootnode is listening on for P2P discovery. Specify the host and TCP port using the [`--p2p-host`](../reference/cli/options.md#p2p-host) and [`--p2p-port`](../reference/cli/options.md#p2p-port) options. The default host is `127.0.0.1` and the default port is `30303`. + + :::note + + Standard Ethereum enode URLs allow hostnames as IP addresses only, however Besu provides [domain name support](#domain-name-support) in private permissioned networks. + + ::: + +- If the TCP listening and UDP discovery ports differ, the UDP port is specified as query parameter `discport`. + +:::info + +If the node public key is `0xc35c3ec90a8a51fd5703594c6303382f3ae6b2ecb9589bab2c04b3794f2bc3fc2631dabb0c08af795787a6c004d8f532230ae6e9925cbbefb0b28b79295d615f`, the host is `10.3.58.6`, the TCP listening port is `30303`, and the UDP discovery port is `30301`, then the enode URL is `enode://c35c3ec90a8a51fd5703594c6303382f3ae6b2ecb9589bab2c04b3794f2bc3fc2631dabb0c08af795787a6c004d8f532230ae6e9925cbbefb0b28b79295d615f@10.3.58.6:30303?discport=30301` + +If the [`--p2p-host`](../reference/cli/options.md#p2p-host) or [`--p2p-port`](../reference/cli/options.md#p2p-port) options are not specified and the node public key is `0xc35c3ec90a8a51fd5703594c6303382f3ae6b2ecb9589bab2c04b3794f2bc3fc2631dabb0c08af795787a6c004d8f532230ae6e9925cbbefb0b28b79295d615f`, then the enode URL is `enode://c35c3ec90a8a51fd5703594c6303382f3ae6b2ecb9589bab2c04b3794f2bc3fc2631dabb0c08af795787a6c004d8f532230ae6e9925cbbefb0b28b79295d615f@127.0.0.1:30303` + +::: + +The enode URL displays when starting a Besu node. Use the [`net_enode`](../reference/api/index.md#net_enode) JSON-RPC API method to get the enode URL of the node. + +The enode advertised to other nodes during discovery is the external IP address and port, as defined by [`--nat-method`](../how-to/connect/specify-nat.md). + +### Domain name support + +:::caution + +Enode URL domain name support is an early access feature that you can use in private [permissioned networks](../../private-networks/concepts/permissioning/index.md) only. + +::: + +To use domain names in enode URLs: + +- Configure DNS reverse lookup. +- Enable DNS support using the early access option `--Xdns-enabled`. + +```bash title="Example enode URL using a domain name" +enode://c35c3ec90a8a51fd5703594c6303382f3ae6b2ecb9589bab2c04b3794f2bc3fc2631dabb0c08af795787a6c004d8f532230ae6e9925cbbefb0b28b79295d615f@mydomain.dev.example.net:30301 +``` + +:::tip + +If deploying Besu using Kubernetes in private permissioned networks, use the `--Xdns-enabled` and `--Xdns-update-enabled` options to ensure that Besu can connect to a container after restarting even if the IP address of the container changes. + +Use the [`--Xhelp`](../reference/cli/options.md#xhelp) command line option to view early access options and their descriptions. + +::: + +If nodes are not connecting as expected, set the [log level to TRACE](../reference/api/index.md#admin_changeloglevel) to help troubleshoot the issue. diff --git a/versioned_docs/version-23.10.1/public-networks/concepts/proof-of-stake/_category_.json b/versioned_docs/version-23.10.1/public-networks/concepts/proof-of-stake/_category_.json new file mode 100644 index 00000000000..47b2323cd5d --- /dev/null +++ b/versioned_docs/version-23.10.1/public-networks/concepts/proof-of-stake/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Proof of stake consensus", + "position": 2 +} diff --git a/versioned_docs/version-23.10.1/public-networks/concepts/proof-of-stake/attestations.md b/versioned_docs/version-23.10.1/public-networks/concepts/proof-of-stake/attestations.md new file mode 100644 index 00000000000..765320567b6 --- /dev/null +++ b/versioned_docs/version-23.10.1/public-networks/concepts/proof-of-stake/attestations.md @@ -0,0 +1,76 @@ +--- +title: Attestations +sidebar_position: 1 +description: Proof of stake attestations +tags: + - public networks +--- + +# Attestations + +Ethereum's move to [proof of stake consensus](./index.md) has brought many changes to the way the network operates. An important aspect of proof of stake is the need for validators to provide attestations in a timely and accurate manner. However, missed attestations have become a common occurrence among validators, leading to a loss of rewards and earnings. This page explores the context behind missing attestations. + +## What are attestations? + +Every epoch (6.4 minutes), a validator proposes an attestation to the network. The attestation is for a specific slot (every 12 seconds) in the epoch. The attestation votes in favor of the validator's view of the chain, in particular, the most recent justified block and the first block in the current epoch (known as _source_ and _target_ checkpoints). This information is collected for all participating validators, enabling the network to reach consensus about the state of the blockchain. + +Honest nodes have 1/3 \* `SECONDS_PER_SLOT` (4 seconds) from the start of the slot to either receive the block or decide there was no block produced and attest to an “empty” or “skip” slot. Once this time has elapsed, attesters should broadcast their attestation reflecting their local view of the chain. + +See the [official specification](https://github.com/ethereum/consensus-specs/blob/dev/specs/phase0/validator.md#attesting) for more information about attestations. + +## Attestation rewards + +Around 85% of validators' rewards come from making attestations. Although committee and slot assignments for attesting are randomized, every active validator will be selected to make exactly one attestation each epoch. + +Attestations receive rewards only if they're included in Beacon Chain blocks. An attestation contains three votes. Each vote is eligible for a reward, subject to the following conditions: + +- Getting attestations included with the correct source checkpoint within 5 slots +- Getting attestations included with the correct target checkpoint within 32 slots +- Getting attestations included with the correct head within 1 slot immediately + +Each of these duties carries a reward rate, a portion of the entire "weight denominator," or the sum of weighted rewards for each attestation. The remaining weights relate to participating in sync committees and proposing blocks (excluding any tips/MEV, the bulk of block rewards). The following table (from [Upgrading Ethereum](https://eth2book.info/bellatrix/part2/incentives/rewards/)) breaks down these weights for cumulative rewards: + +| Name | Percentage | Value | +| ---------------------- | ---------- | ------------ | +| `TIMELY_SOURCE_WEIGHT` | 21.9% | `uint64(14)` | +| `TIMELY_TARGET_WEIGHT` | 40.6% | `uint64(26)` | +| `TIMELY_HEAD_WEIGHT` | 21.9% | `uint64(14)` | +| `SYNC_REWARD_WEIGHT` | 3.1% | `uint64(2)` | +| `PROPOSER_WEIGHT` | 12.5% | `uint64(8)` | +| `WEIGHT_DENOMINATOR` | 100% | `uint64(64)` | + +## Incorrect attestations + +If you have attestations with incorrect head votes, your node might be experiencing slow block imports. However, block producers can also be slow to publish blocks, resulting in a majority of validators getting the head vote wrong. A <100% head vote doesn't necessarily imply a problem with your node. + +In case of a slowdown, identify whether the issue is with the beacon node or the execution client. Block timing logs can be helpful in determining this. + +If you're using [Teku](https://docs.teku.consensys.net/) as a consensus layer client, identify late blocks (the block didn't get to Teku in time) with the following kind of log: + +```bash +Late Block Import *** Block: c2b911533a8f8d5e699d1a334e0576d2b9aa4caa726bde8b827548b579b47c68 (4765916) proposer 6230 arrival 3475ms, pre-state_retrieved +5ms, processed +185ms, execution_payload_result_received +1436ms, begin_importing +0ms, transaction_prepared +0ms, transaction_committed +0ms, completed +21ms +``` + +The time of arrival indicates how much time elapsed after the start of the slot before your node received the block. In this example, the block arrived after 3475ms, which is slower than optimal, but still enough time for Teku to create an attestation 4 seconds into the slot. + +Typically, delayed arrivals occur when the block producer is slow in generating the block. It's also possible that the block was published on time but took longer to propagate to your node through peer-to-peer gossip. If delayed arrivals are a recurring issue, it might be a problem with your node, such as an incorrect system clock, network issues, or a reduction in the number of peers. + +## Conclusion + +Attestations are complicated. Rewards can be impacted by: + +- The contents of a block (how long it takes to compute). +- The hardware processing that block (execution speed). +- How long it takes for the block to arrive to Besu from the consensus layer. +- The arrival time of the block from other consensus layer peers. Besu and your consensus layer client have no control over how late into a slot they receive blocks. +- General network latency. +- The status of either Besu or the consensus layer client. + +[Monitoring](../../how-to/monitor/index.md) your validator carefully for uptime, execution speed, and a valid consensus layer connection will help you explore attestation performance for your node. + +## References + +- [Upgrading Ethereum](https://eth2book.info/bellatrix/part2/incentives/rewards/) +- [Understanding Attestation Misses](https://www.symphonious.net/2022/09/25/understanding-attestation-misses/) +- [Block production in Ethereum after the Merge](https://notes.ethereum.org/DaWh-02HQ4qftum1xdphkg?view#Broadcast-attestation) +- [Ethereum Consensus Specs](https://github.com/ethereum/consensus-specs/blob/dev/specs/phase0/validator.md#attesting) diff --git a/versioned_docs/version-23.10.1/public-networks/concepts/proof-of-stake/index.md b/versioned_docs/version-23.10.1/public-networks/concepts/proof-of-stake/index.md new file mode 100644 index 00000000000..8fad0be6237 --- /dev/null +++ b/versioned_docs/version-23.10.1/public-networks/concepts/proof-of-stake/index.md @@ -0,0 +1,47 @@ +--- +description: Ethereum proof of stake consensus +tags: + - public networks +--- + +# Proof of stake consensus + +[The Merge](../the-merge.md) transitioned Ethereum Mainnet to [proof of stake +(PoS)](https://ethereum.org/en/developers/docs/consensus-mechanisms/pos/) consensus. + +In Ethereum's PoS, you must run a [full node](../the-merge.md#execution-and-consensus-clients) and +[stake 32 ETH](https://ethereum.org/en/staking/) to become a validator. + +:::note +You must run a beacon node and an execution client to operate a full node on Mainnet. +To become a validator, you must also run a validator client (either [in the same process as the +beacon node](https://docs.teku.consensys.net/get-started/start-teku#start-the-clients-in-a-single-process) +or [separately](https://docs.teku.consensys.net/get-started/start-teku#run-the-clients-separately)). +::: + +PoS is preferred over proof of work and proof of authority as a consensus mechanism because it is +more secure, requires less energy, and lowers the barrier to entry. + +The PoS mechanism randomly chooses validators to propose or validate blocks on the [Beacon +Chain](https://ethereum.org/en/upgrades/beacon-chain/) in defined time frames. + +Proposers are responsible for proposing new consensus blocks, and non-proposing validators are +responsible for validating (attesting to) proposed blocks. +Validators earn [rewards](https://www.blocknative.com/ethereum-staking-calculator) for proposing and +attesting to consensus blocks eventually included in the Beacon Chain, and penalized for malicious behavior. +[Attestations](./attestations.md) make up the bulk of validator rewards (~85%). +Validators also receive transaction fees for included blocks. + +Each consensus block contains an execution payload, which contains a list of transactions and other data required to execute and validate the payload. + +When a node validates a consensus block, its [consensus client](../the-merge.md#consensus-clients) processes the block and sends the execution payload to the [execution client](../the-merge.md#execution-clients), which: + +1. Assembles a block on the execution layer. +2. Verifies pre-conditions. +3. Executes transactions. +4. Verifies post-conditions. +5. Sends the validity result back to the consensus client. + +If the block is valid, the execution client includes it in the execution chain and stores the new state in execution state storage. + +If a consensus block receives attestations backed by enough staked ETH, the block is included in the Beacon Chain. diff --git a/versioned_docs/version-23.10.1/public-networks/concepts/the-merge.md b/versioned_docs/version-23.10.1/public-networks/concepts/the-merge.md new file mode 100644 index 00000000000..a84e7f428ae --- /dev/null +++ b/versioned_docs/version-23.10.1/public-networks/concepts/the-merge.md @@ -0,0 +1,85 @@ +--- +title: The Merge +sidebar_position: 1 +description: Learn about The Merge, and execution and consensus clients. +tags: + - public networks +--- + +# The Merge + +:::info + +The Merge was executed on **September 15, 2022**. + +::: + +[The Merge](https://ethereum.org/en/upgrades/merge/) was an Ethereum upgrade that merged the +[Beacon Chain] into Ethereum Mainnet, turning Mainnet into a combination of an [execution layer and +consensus layer](#execution-and-consensus-clients). +The Merge transitioned Mainnet from proof of work to [proof of stake consensus](proof-of-stake/index.md). + +You can run Besu as an execution client with: + +- [Any consensus client on Mainnet](../get-started/connect/mainnet.md). +- [Any consensus client on a testnet](../get-started/connect/testnet.md). +- [Teku on Mainnet](../tutorials/besu-teku-mainnet.md). +- [Teku on a testnet](../tutorials/besu-teku-testnet.md). + +## Execution and consensus clients + +After The Merge, a full Ethereum Mainnet node is a combination of an execution client (previously +called an [Ethereum 1.0](https://blog.ethereum.org/2022/01/24/the-great-eth2-renaming/) client) and +a consensus client (previously called an [Ethereum +2.0](https://blog.ethereum.org/2022/01/24/the-great-eth2-renaming/) client). + +Execution and consensus clients communicate with each other using the [Engine API](../how-to/use-engine-api.md). + +![Ethereum Merge node](../../assets/images/Execution-Consensus-Clients.png) + +### Execution clients + +Execution clients, such as Besu, manage the execution layer, including executing transactions and +updating the world state. +Execution clients serve [JSON-RPC API](../reference/engine-api/index.md) requests and communicate +with each other in a peer-to-peer network. + +### Consensus clients + +Consensus clients, such as [Teku], contain beacon node and validator client implementations. +The beacon node is the primary link to the [Beacon Chain] (consensus layer). +The validator client performs [validator duties](proof-of-stake/index.md) on the consensus layer. +Consensus clients serve [REST API](https://docs.teku.consensys.net/reference/rest) requests and +communicate with each other in a peer-to-peer network. + +## What happened during The Merge + +Before The Merge, the execution and consensus clients' configurations were updated to listen for a +certain total terminal difficulty (TTD) to be reached. + +:::info +The TTD is a specific value for the total difficulty, which is the sum of the proof-of-work mining +difficulty for all blocks up to some point in the blockchain. +::: + +The consensus layer enabled the Merge configuration (Bellatrix) before reaching the TTD. +Once the execution layer blocks reached the TTD, the Beacon Chain merged into Ethereum Mainnet, and +Ethereum transitioned to a proof of stake network. + +:::tip +After The Merge, a Mainnet node operator must run both an execution client and a beacon node at the +same time. +To become a validator, you must also run a validator client (either [in the same process as the +beacon node](https://docs.teku.consensys.net/get-started/start-teku#start-the-clients-in-a-single-process) +or [separately](https://docs.teku.consensys.net/get-started/start-teku#run-the-clients-separately). +::: + +After The Merge, validators earn [rewards](https://www.blocknative.com/ethereum-staking-calculator) +for performing [validator duties](proof-of-stake/index.md), and [fee +recipients](https://docs.teku.consensys.net/reference/cli#validators-proposer-default-fee-recipient) +also earn rewards for the inclusion of execution layer transactions. + + + +[Beacon Chain]: https://ethereum.org/en/upgrades/beacon-chain/ +[Teku]: https://docs.teku.consensys.net/en/stable/ diff --git a/versioned_docs/version-23.10.1/public-networks/concepts/transactions/_category_.json b/versioned_docs/version-23.10.1/public-networks/concepts/transactions/_category_.json new file mode 100644 index 00000000000..e82ef121922 --- /dev/null +++ b/versioned_docs/version-23.10.1/public-networks/concepts/transactions/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Transactions", + "position": 4 +} diff --git a/versioned_docs/version-23.10.1/public-networks/concepts/transactions/pool.md b/versioned_docs/version-23.10.1/public-networks/concepts/transactions/pool.md new file mode 100644 index 00000000000..87f2e499e8c --- /dev/null +++ b/versioned_docs/version-23.10.1/public-networks/concepts/transactions/pool.md @@ -0,0 +1,48 @@ +--- +title: Transaction pool +sidebar_position: 2 +description: Transaction pool overview +tags: + - public networks + - private networks +--- + +# Transaction pool + +All nodes maintain a transaction pool to store pending transactions before processing. + +Options and methods for configuring and monitoring the transaction pool include: + +- [`txpool_besuTransactions`](../../reference/api/index.md#txpool_besutransactions) JSON-RPC API method to list transactions in the transaction pool. +- [`--tx-pool-max-size`](../../reference/cli/options.md#tx-pool-max-size) command line option to specify the maximum number of transactions in the transaction pool. +- [`--tx-pool-price-bump`](../../reference/cli/options.md#tx-pool-price-bump) command line option to specify the price bump percentage to replace an existing transaction. +- [`--tx-pool-retention-hours`](../../reference/cli/options.md#tx-pool-retention-hours) command line option to specify the maximum number of hours to keep pending transactions in the transaction pool. +- [`newPendingTransactions`](../../how-to/use-besu-api/rpc-pubsub.md#pending-transactions) and [`droppedPendingTransactions`](../../how-to/use-besu-api/rpc-pubsub.md#dropped-transactions) RPC subscriptions to notify of transactions added to and dropped from the transaction pool. + +:::tip + +When submitting [private transactions](../../../private-networks/concepts/privacy/private-transactions/index.md#nonce-validation), the [privacy marker transaction](../../../private-networks/concepts/privacy/private-transactions/processing.md) is submitted to the transaction pool, not the private transaction itself. + +::: + +## Dropping transactions when the transaction pool is full + +When the transaction pool is full, it accepts and retains local transactions in preference to remote transactions. If the transaction pool is full of local transactions, Besu drops the oldest local transactions first. That is, a full transaction pool continues to accept new local transactions by first dropping remote transactions and then by dropping the oldest local transactions. + +## Replacing transactions with the same sender and nonce + +You can replace a pending transaction with a transaction that has the same sender and nonce but a higher gas price. + +If sending a [legacy transaction](types.md#frontier-transactions), the old transaction is replaced if the new transaction has a gas price higher than the existing gas price by the percentage specified by [`--tx-pool-price-bump`](../../reference/cli/options.md#tx-pool-price-bump). + +If sending an [`EIP1559` transaction](types.md#eip1559-transactions), the old transaction is replaced if one of the following is true: + +- The new transaction's effective gas price is higher than the existing gas price by the percentage specified by [`--tx-pool-price-bump`](../../reference/cli/options.md#tx-pool-price-bump) AND the new effective priority fee is greater than or equal to the existing priority fee. + +- The new transaction's effective gas price is the equal to the existing gas price AND the new effective priority fee is higher than the existing priority fee by the percentage specified by [`--tx-pool-price-bump`](../../reference/cli/options.md#tx-pool-price-bump). + +The default value for [`--tx-pool-price-bump`](../../reference/cli/options.md#tx-pool-price-bump) is 10%. + +## Size of the transaction pool + +Decreasing the maximum size of the transaction pool reduces memory use. If the network is busy and there is a backlog of transactions, increasing the size of the transaction pool reduces the risk of removing transactions from the transaction pool. diff --git a/versioned_docs/version-23.10.1/public-networks/concepts/transactions/types.md b/versioned_docs/version-23.10.1/public-networks/concepts/transactions/types.md new file mode 100644 index 00000000000..91306fa3d4d --- /dev/null +++ b/versioned_docs/version-23.10.1/public-networks/concepts/transactions/types.md @@ -0,0 +1,41 @@ +--- +title: Transaction types +sidebar_position: 1 +description: Description of the different transaction types +tags: + - public networks + - private networks +--- + +# Transaction types + +You can interact with the Hyperledger Besu JSON-RPC API using different transaction types (specified by the `transactionType` parameter). + +The following API objects use a unique format for each `transactionType`: + +- [Pending transaction object](../../reference/api/objects.md#pending-transaction-object) +- [Transaction object](../../reference/api/objects.md#transaction-object) +- [Transaction call object](../../reference/api/objects.md#transaction-call-object) +- [Transaction receipt object](../../reference/api/objects.md#transaction-receipt-object) + +## `FRONTIER` transactions + +Transactions with type `FRONTIER` are _legacy transactions_ that use the transaction format existing before typed transactions were introduced in [EIP-2718](https://eips.ethereum.org/EIPS/eip-2718). They contain the parameters `chainId`, `nonce`, `gasPrice`, `gasLimit`, `to`, `value`, `data`, `v`, `r`, and `s`. Legacy transactions don't use [access lists](#access_list-transactions) or incorporate [EIP-1559 fee market changes](#eip1559-transactions). + +## `ACCESS_LIST` transactions + +Transactions with type `ACCESS_LIST` are transactions introduced in [EIP-2930](https://eips.ethereum.org/EIPS/eip-2930). They contain, along with the [legacy parameters](#frontier-transactions), an `accessList` parameter, which specifies an array of addresses and storage keys that the transaction plans to access (an _access list_). `ACCESS_LIST` transactions must specify an access list, and they don't incorporate [EIP-1559 fee market changes](#eip1559-transactions). + +Use the [`eth_createAccessList`](../../reference/api/index.md#eth_createaccesslist) API to simulate a transaction which returns the addresses and storage keys that may be used to send the real transaction, and the approximate gas cost. + +## `EIP1559` transactions + +Transactions with type `EIP1559` are transactions introduced in [EIP-1559](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-1559.md). EIP-1559 addresses the network congestion and overpricing of transaction fees caused by the historical fee market, in which users send transactions specifying a gas price bid using the `gasPrice` parameter, and miners choose transactions with the highest bids. + +`EIP1559` transactions don't specify `gasPrice`, and instead use an in-protocol, dynamically changing _base fee_ per gas. At each block, the base fee per gas is adjusted to address network congestion as measured by a gas target. + +`EIP1559` transactions contain, along with the [`accessList`](#access_list-transactions) parameter and [legacy parameters](#frontier-transactions) except for `gasPrice`, a `maxPriorityFeePerGas` parameter, which specifies the maximum fee the sender is willing to pay per gas above the base fee (the maximum _priority fee_ per gas), and a `maxFeePerGas` parameter, which specifies the maximum total fee (base fee + priority fee) the sender is willing to pay per gas. + +An `EIP1559` transaction always pays the base fee of the block it's included in, and it pays a priority fee as priced by `maxPriorityFeePerGas` or, if the base fee per gas + `maxPriorityFeePerGas` exceeds `maxFeePerGas`, it pays a priority fee as priced by `maxFeePerGas` minus the base fee per gas. The base fee is burned, and the priority fee is paid to the miner that included the transaction. A transaction's priority fee per gas incentivizes miners to include the transaction over other transactions with lower priority fees per gas. + +`EIP1559` transactions must specify both `maxPriorityFeePerGas` and `maxFeePerGas`. They must not specify `gasPrice`. diff --git a/versioned_docs/version-23.10.1/public-networks/concepts/transactions/validation.md b/versioned_docs/version-23.10.1/public-networks/concepts/transactions/validation.md new file mode 100644 index 00000000000..39368ee1927 --- /dev/null +++ b/versioned_docs/version-23.10.1/public-networks/concepts/transactions/validation.md @@ -0,0 +1,30 @@ +--- +title: Transaction validation +sidebar_position: 3 +description: What transaction validation and when +tags: + - public networks + - private networks +--- + +# Transaction validation + +For transactions submitted and added to a block, Besu validates the transactions, as illustrated in the following diagram. + +![Transaction Validation](../../../assets/images/transaction-validation.png) + +Besu repeats the set of transaction pool validations after propagating the transaction. Besu repeats the same set of validations when importing the block that includes the transaction, except the nonce must be exactly right when importing the block. + +:::tip + +Private transactions are not added to the transaction pool. The privacy marker transaction is submitted to the transaction pool but the private transaction itself is directly distributed to the transaction participants. + +::: + +When adding the transaction to a block, Besu performs an additional validation to check that the transaction gas limit is less than the remaining block gas limit. After creating a block, the node imports the block and then repeats the transaction pool validations. + +:::info + +The transaction is only added if the entire transaction gas limit is less than the remaining gas for the block. The total gas used by the transaction is not relevant to this validation. That is, if the total gas used by the transaction is less than the remaining block gas, but the transaction gas limit is more than the remaining block gas, the transaction is not added. + +::: diff --git a/versioned_docs/version-23.10.1/public-networks/get-started/_category_.json b/versioned_docs/version-23.10.1/public-networks/get-started/_category_.json new file mode 100644 index 00000000000..25ee51d48e5 --- /dev/null +++ b/versioned_docs/version-23.10.1/public-networks/get-started/_category_.json @@ -0,0 +1,9 @@ +{ + "label": "Get started", + "position": 2, + "collapsed": false, + "link": { + "type": "generated-index", + "slug": "/public-networks/get-started" + } +} diff --git a/versioned_docs/version-23.10.1/public-networks/get-started/connect/_category_.json b/versioned_docs/version-23.10.1/public-networks/get-started/connect/_category_.json new file mode 100644 index 00000000000..f326ba7b151 --- /dev/null +++ b/versioned_docs/version-23.10.1/public-networks/get-started/connect/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Connect to a network", + "position": 4 +} diff --git a/versioned_docs/version-23.10.1/public-networks/get-started/connect/index.md b/versioned_docs/version-23.10.1/public-networks/get-started/connect/index.md new file mode 100644 index 00000000000..0ce16f25aba --- /dev/null +++ b/versioned_docs/version-23.10.1/public-networks/get-started/connect/index.md @@ -0,0 +1,11 @@ +--- +title: Connect to a network overview +tags: + - public networks +hide: + - feedback +--- + +# Connect to a network + +This section provides information on connecting Besu to a public Ethereum network. diff --git a/versioned_docs/version-23.10.1/public-networks/get-started/connect/mainnet.md b/versioned_docs/version-23.10.1/public-networks/get-started/connect/mainnet.md new file mode 100644 index 00000000000..00722030e74 --- /dev/null +++ b/versioned_docs/version-23.10.1/public-networks/get-started/connect/mainnet.md @@ -0,0 +1,144 @@ +--- +title: Connect to Mainnet +sidebar_position: 2 +description: How to connect to Mainnet +tags: + - public networks +--- + +# Connect to Mainnet + +:::info + +[The Merge](../../concepts/the-merge.md) was executed on **September 15, 2022**. Ethereum is now a [proof of stake](../../concepts/proof-of-stake/index.md) network, and a full Ethereum node requires both [an execution client and a consensus client](../../concepts/the-merge.md#execution-and-consensus-clients). + +::: + +Run Besu as an [execution client](../../concepts/the-merge.md#execution-clients) with any consensus client on Ethereum Mainnet. + +If you're using [Teku] as a consensus client, you can follow the [Besu and Teku Mainnet tutorial](../../tutorials/besu-teku-mainnet.md). + +## Prerequisites + +- [Besu installed](../install/binary-distribution.md). +- A consensus client installed. For example, [Teku](https://docs.teku.consensys.net/en/latest/). + +## Steps + +### 1. Generate the shared secret + +Run the following command: + +```bash +openssl rand -hex 32 | tr -d "\n" > jwtsecret.hex +``` + +You will specify `jwtsecret.hex` when starting Besu and the consensus client. This is a shared JWT secret the clients use to authenticate each other when using the [Engine API](../../how-to/use-engine-api.md). + +### 2. Generate validator keys + +If you're running the consensus client as a beacon node only, skip to the [next step](#3-start-besu). + +If you're also running the consensus client as a validator client, have a funded Ethereum address ready (32 ETH and gas fees for each validator). + +Generate validator keys for one or more validators using the [Staking Launchpad](https://launchpad.ethereum.org/en/). + +:::info + +Save the password you use to generate each key pair in a `.txt` file. You should also have a `.json` file for each validator key pair. + +::: + +### 3. Start Besu + +Run the following command or specify the options in a [configuration file](../../how-to/configuration-file.md): + +```bash +besu \ + --sync-mode=X_SNAP \ + --data-storage-format=BONSAI \ + --rpc-http-enabled=true \ + --rpc-http-host=0.0.0.0 \ + --rpc-ws-enabled=true \ + --rpc-ws-host=0.0.0.0 \ + --host-allowlist=,127.0.0.1,localhost \ + --engine-host-allowlist=,127.0.0.1,localhost \ + --engine-rpc-enabled \ + --engine-jwt-secret= +``` + +Specify: + +- The path to the `jwtsecret.hex` file generated in [step 1](#1-generate-the-shared-secret) using the [`--engine-jwt-secret`](../../reference/cli/options.md#engine-jwt-secret) option. +- The IP address of your Besu node using the [`--host-allowlist`](../../reference/cli/options.md#host-allowlist) and [`--engine-host-allowlist`](../../reference/cli/options.md#engine-host-allowlist) options. + +Also, in the command: + +- [`--sync-mode`](../../reference/cli/options.md#sync-mode) specifies using [snap sync](sync-node.md#snap-synchronization). +- [`--data-storage-format`](../../reference/cli/options.md#data-storage-format) specifies using [Bonsai Tries](../../concepts/data-storage-formats.md#bonsai-tries). +- [`--rpc-http-enabled`](../../reference/cli/options.md#rpc-http-enabled) enables the HTTP JSON-RPC service. +- [`--rpc-http-host`](../../reference/cli/options.md#rpc-http-host) is set to `0.0.0.0` to allow remote RPC connections. +- [`--rpc-ws-enabled`](../../reference/cli/options.md#rpc-ws-enabled) enables the WebSocket JSON-RPC service. +- [`--rpc-ws-host`](../../reference/cli/options.md#rpc-ws-host) is set to `0.0.0.0` to allow remote RPC connections. +- [`--engine-rpc-enabled`](../../reference/cli/options.md#engine-rpc-enabled) enables the [Engine API](../../reference/engine-api/index.md). + +You can modify the option values and add other [command line options](../../reference/cli/options.md) as needed. + +### 4. Start the consensus client + +Refer to your consensus client documentation to configure and start the consensus client. + +:::info + +If you're running a validator client, make sure you set a fee recipient address. + +::: + +If you're using Teku, follow the [Besu and Teku Mainnet tutorial](../../tutorials/besu-teku-mainnet.md#5-start-teku). + +### 5. Wait for the clients to sync + +After starting Besu and the consensus client, your node starts syncing and connecting to peers. + + + +# Besu logs + +```bash +{"@timestamp":"2023-02-03T04:43:49,555","level":"INFO","thread":"main","class":"DefaultSynchronizer","message":"Starting synchronizer.","throwable":""} +{"@timestamp":"2023-02-03T04:43:49,556","level":"INFO","thread":"main","class":"FastSyncDownloader","message":"Starting sync","throwable":""} +{"@timestamp":"2023-02-03T04:43:49,559","level":"INFO","thread":"main","class":"Runner","message":"Ethereum main loop is up.","throwable":""} +{"@timestamp":"2023-02-03T04:43:53,106","level":"INFO","thread":"Timer-0","class":"DNSResolver","message":"Resolved 2409 nodes","throwable":""} +{"@timestamp":"2023-02-03T04:45:04,803","level":"INFO","thread":"nioEventLoopGroup-3-10","class":"SnapWorldStateDownloader","message":"Downloading world state from peers for pivot block 16545859 (0x616ae3c4cf85f95a9bce2814a7282d75dc2eac36 +cb9f0fcc6f16386df70da3c5). State root 0xa7114541f42c62a72c8b6bb9901c2ccf4b424cd7f76570a67b82a183b02f25dc pending requests 0","throwable":""} +{"@timestamp":"2023-02-03T04:46:04,834","level":"INFO","thread":"EthScheduler-Services-3 (batchPersistAccountData)","class":"SnapsyncMetricsManager","message":"Worldstate download progress: 0.08%, Peer count: 8","throwable":""} +{"@timestamp":"2023-02-03T04:48:01,840","level":"INFO","thread":"EthScheduler-Services-3 (batchPersistAccountData)","class":"SnapsyncMetricsManager","message":"Worldstate download progress: 0.23%, Peer count: 8","throwable":""} +{"@timestamp":"2023-02-03T04:49:09,931","level":"INFO","thread":"EthScheduler-Services-3 (batchPersistAccountData)","class":"SnapsyncMetricsManager","message":"Worldstate download progress: 0.41%, Peer count: 11","throwable":""} +{"@timestamp":"2023-02-03T04:50:12,466","level":"INFO","thread":"EthScheduler-Services-3 (batchPersistAccountData)","class":"SnapsyncMetricsManager","message":"Worldstate download progress: 0.61%, Peer count: 10","throwable":""} +{"@timestamp":"2023-02-03T04:51:20,977","level":"INFO","thread":"EthScheduler-Services-3 (batchPersistAccountData)","class":"SnapsyncMetricsManager","message":"Worldstate download progress: 0.75%, Peer count: 10","throwable":""} +{"@timestamp":"2023-02-03T04:51:28,985","level":"INFO","thread":"EthScheduler-Services-29 (importBlock)","class":"FastImportBlocksStep","message":"Block import progress: 180400 of 16545859 (1%)","throwable":""} +``` + +# Teku logs + +```bash +2022-03-21 20:43:24.355 INFO - Syncing *** Target slot: 76092, Head slot: 2680, Remaining slots: 73412, Connected peers: 8 +2022-03-21 20:43:36.363 INFO - Syncing *** Target slot: 76093, Head slot: 2879, Remaining slots: 73214, Connected peers: 10 +2022-03-21 20:43:48.327 INFO - Syncing *** Target slot: 76094, Head slot: 3080, Remaining slots: 73014, Connected peers: 8 +2022-03-21 20:44:00.339 INFO - Syncing *** Target slot: 76095, Head slot: 3317, Remaining slots: 72778, Connected peers: 6 +2022-03-21 20:44:12.353 INFO - Syncing *** Target slot: 76096, Head slot: 3519, Remaining slots: 72577, Connected peers: 9 +``` + + + +If you're running the consensus client as a beacon node only, you're all set. If you're also running the consensus client as a validator client, ensure your clients are fully synced before submitting your staking deposit in the next step. Syncing Besu can take several days. + +### 6. Stake ETH + +Stake your ETH for one or more validators using the [Staking Launchpad](https://launchpad.ethereum.org/en/). + +You can check your validator status by searching your Ethereum address on the [Beacon Chain explorer](https://beaconcha.in/). It may take up to multiple days for your validator to be activated and start proposing blocks. + + + +[Teku]: https://docs.teku.consensys.net/en/stable/ diff --git a/versioned_docs/version-23.10.1/public-networks/get-started/connect/sync-node.md b/versioned_docs/version-23.10.1/public-networks/get-started/connect/sync-node.md new file mode 100644 index 00000000000..5a6fd8ddfca --- /dev/null +++ b/versioned_docs/version-23.10.1/public-networks/get-started/connect/sync-node.md @@ -0,0 +1,163 @@ +--- +title: Sync Besu +sidebar_position: 1 +description: Full and archive node types +tags: + - public networks +--- + +# Sync Besu + +Besu supports two node types, commonly referred to as [full nodes](#run-a-full-node) and [archive nodes](#run-an-archive-node). + +Full nodes have the current state of the blockchain. They can't serve the network with all data requests (for example, the balance of an account at an old block). Full nodes can guarantee the latest state for the blockchain (and some older states, but not all). You can check current balances, sign and send transactions, and look at current dapp data. + +Archive nodes also store the intermediary state of every account and contract for every block since the genesis block. Archive nodes can do everything full nodes do, and they can access historical state data. Archive nodes require more disk space than full nodes. + +Besu must connect with other peers to sync with the network. If your node is having trouble peering, try [troubleshooting peering](../../how-to/troubleshoot/peering.md). + +## Sync times + +To sync with a public network, Besu runs two processes in parallel: the world state sync and the blockchain download. + +The following table shows the average world state sync time for each sync mode on Mainnet. All times are hardware dependent; this table is based on running AWS instances m6gd.2xlarge. Each sync mode also has its own world state database size. + +| Sync mode | Time to sync world state | Disk usage | +| ---------- | ------------------------ | ------------- | +| Snap | ~6 hours | Average disk | +| Checkpoint | ~5 hours | Smallest disk | +| Fast | ~1.5 days | Average disk | +| Full | ~weeks | Largest disk | + +:::note + +- As of late 2022, an average Mainnet snap sync consumes around 750 GB using Bonsai Tries. Read more about [storage requirements](../../concepts/data-storage-formats.md#storage-requirements) across data storage formats and sync modes. + +- Testnets take significantly less time and space to sync. + +::: + +While the world state syncs, Besu downloads and imports the blockchain in the background. The blockchain download time depends on CPU, the network, Besu's peers, and disk speed. It generally takes longer than the world state sync. + +Besu must catch up to the current chain head and sync the world state to participate on Mainnet. + +## Storage + +You can store the world state using [Forest of Tries](../../concepts/data-storage-formats.md#forest-of-tries) or [Bonsai Tries](../../concepts/data-storage-formats.md#bonsai-tries). We recommend using Bonsai Tries for the lowest storage requirements. + +## Run a full node + +You can run a full node using [snap synchronization (snap sync)](#snap-synchronization), [checkpoint synchronization (checkpoint sync)](#checkpoint-synchronization), or [fast synchronization (fast sync)](#fast-synchronization). + +### Snap synchronization + +:::tip + +We recommend using snap sync over fast sync because snap sync can be faster by several days. + +We recommend using snap sync with the [Bonsai](../../concepts/data-storage-formats.md#bonsai-tries) data storage format for the fastest sync and lowest storage requirements. + +::: + +Enable snap sync using [`--sync-mode=X_SNAP`](../../reference/cli/options.md#sync-mode). You need Besu version 22.4.0 or later to use snap sync. + +Instead of downloading the [state trie](../../concepts/data-storage-formats.md) node by node, snap sync downloads as many leaves of the trie as possible, and reconstructs the trie locally. + +You can't switch from fast sync to snap sync. If your node is blocked in the middle of a fast sync, you can start over using snap sync instead by stopping the node, deleting the data directory, and starting over using `--sync-mode=X_SNAP`. + +You can restart Besu during a snap sync in case of hardware or software problems. The sync resumes from the last valid world state and continues to download blocks starting from the last downloaded block. + +See [how to read the Besu metrics charts](../../how-to/monitor/understand-metrics.md) when using snap sync. + +### Checkpoint synchronization + +:::caution + +Checkpoint sync is an early access feature. + +::: + +Enable checkpoint sync using [`--sync-mode=X_CHECKPOINT`](../../reference/cli/options.md#sync-mode). You need Besu version 22.4.3 or later to use checkpoint sync. + +Checkpoint sync behaves like [snap sync](#snap-synchronization), but instead of syncing from the genesis block, it syncs from a specific checkpoint block configured in the [Besu genesis file](../../concepts/genesis-file.md). + +Ethereum Mainnet and the Goerli testnet configurations already define default checkpoints, so you don't have to add this yourself. + +For other networks, you can configure a checkpoint in the genesis file by specifying the block hash, number, and total difficulty as in the following example. + +```json title="Checkpoint configuration example" +"checkpoint": { + "hash": "0x844d581cb00058d19f0584fb582fa2de208876ee56bbae27446a679baf4633f4", + "number": 14700000, + "totalDifficulty": "0xA2539264C62BF98CFC6" +} +``` + +:::note + +If using [Clique](../../../private-networks/how-to/configure/consensus/clique.md) consensus, the checkpoint must be the beginning of an epoch. + +::: + +If you enable checkpoint sync without a checkpoint configuration in the genesis file, Besu snap syncs from the genesis block. + +You can restart Besu during a checkpoint sync in case of hardware or software problems. The sync resumes from the last valid world state and continues to download blocks starting from the last downloaded block. + +### Fast synchronization + +:::caution + +It might become impossible to sync Ethereum Mainnet using fast sync in the future. If you sync for the first time or ever need to re-sync, update Besu to a version that supports newer sync methods. + +::: + +Enable fast sync using [`--sync-mode=FAST`](../../reference/cli/options.md#sync-mode). + +Fast sync downloads the block headers and transaction receipts, and verifies the chain of block headers from the genesis block. + +When starting fast sync, Besu first downloads the world state for a recent block verified by its peers (referred to as a pivot block), and then begins fast sync from the genesis block. + +Fast sync is the default for named networks specified using the [`--network`](../../reference/cli/options.md#network) option, except for the `dev` development network. It's also the default if connecting to Ethereum Mainnet by not specifying the [`--network`](../../reference/cli/options.md#network) or [`--genesis-file`](../../reference/cli/options.md#genesis-file) options. + +Using fast sync with [private transactions](../../../private-networks/concepts/privacy/index.md) isn't supported. + +You can observe the `besu_synchronizer_fast_sync_*` and `besu_synchronizer_world_state_*` [metrics](../../how-to/monitor/metrics.md#metrics-list) to monitor fast sync. + +:::note + +When fast syncing, block numbers increase until close to the head block, then the process pauses while the world state download completes. This may take a significant amount of time depending on world state size, during which the current head block doesn't increase. For example, Mainnet may take several days or more to fast sync. Fast sync time may increase because Besu picks new pivot blocks, or because peers prune the world state before it completes downloading. + +::: + +:::caution RocksDB error on AWS + +When running Besu on some cloud providers, a known [RocksDB](https://github.com/facebook/rocksdb/issues/6435) issue causes fast sync to fail occasionally. The following error is displayed repeatedly: + +``` +EthScheduler-Services-1 (importBlock) | ERROR | PipelineChainDownloader | Chain download failed. Restarting after short delay. +java.util.concurrent.CompletionException: org.hyperledger.besu.plugin.services.exception.StorageException: org.rocksdb.RocksDBException: block checksum mismatch: +``` + +The failure has been seen on AWS and Digital Ocean. On AWS, A full restart of the VM is required to restart the fast sync. Fast sync isn't [currently supported on Digital Ocean](https://github.com/hyperledger/besu/blob/750580dcca349d22d024cc14a8171b2fa74b505a/CHANGELOG.md#143). + +::: + +:::caution Pending state nodes stays constant + +When fast syncing, the pending state nodes count is the number of nodes yet to be downloaded, and it should change constantly. Pending state nodes trend to 0 during fast sync and then goes to 0. + +If the number stays constant, this could mean your node isn't syncing against any peers. + +In the following example, the pivot block is 0 and the pending state nodes value is constant. This means the node isn't syncing against any peers. The fact that state nodes have been downloaded means at some stage it was syncing. + +![Fast synchronization](../../../assets/images/fastsync.png) + +The easiest solution in this scenario is to restart fast sync to obtain a new pivot block. + +::: + +## Run an archive node + +To run an archive node, enable full synchronization (full sync) using [`--sync-mode=FULL`](../../reference/cli/options.md#sync-mode). + +Full sync starts from the genesis block and reprocesses all transactions. diff --git a/versioned_docs/version-23.10.1/public-networks/get-started/connect/testnet.md b/versioned_docs/version-23.10.1/public-networks/get-started/connect/testnet.md new file mode 100644 index 00000000000..1722bc8e489 --- /dev/null +++ b/versioned_docs/version-23.10.1/public-networks/get-started/connect/testnet.md @@ -0,0 +1,171 @@ +--- +title: Connect to a testnet +sidebar_position: 3 +Description: How to connect to a testnet +tags: + - public networks +--- + +# Connect to a testnet + +Run Besu as an [execution client](../../concepts/the-merge.md#execution-clients) with any consensus client on the [Goerli](https://github.com/eth-clients/goerli) and [Sepolia](https://github.com/eth-clients/sepolia) testnets. + +If you're using [Teku](https://docs.teku.consensys.net/en/latest/) as a consensus client, you can follow the [Besu and Teku testnet tutorial](../../tutorials/besu-teku-testnet.md). + +:::note + +Sepolia is a permissioned network and you can't run a validator client on it without [requesting to become a validator](https://notes.ethereum.org/zvkfSmYnT0-uxwwEegbCqg) first. You can connect your consensus client using the beacon node only, without any validator duties. + +::: + +## Prerequisites + +- [Besu installed](../install/binary-distribution.md). +- A consensus client installed. For example, [Teku](https://docs.teku.consensys.net/en/latest/). + +## Steps + +### 1. Generate the shared secret + +Run the following command: + +```bash +openssl rand -hex 32 | tr -d "\n" > jwtsecret.hex +``` + +You will specify `jwtsecret.hex` when starting Besu and the consensus client. This is a shared JWT secret the clients use to authenticate each other when using the [Engine API](../../how-to/use-engine-api.md). + +### 2. Generate validator keys + +If you're running the consensus client as a beacon node only, skip to the [next step](#3-start-besu). + +If you're also running the consensus client as a validator client, create a test Ethereum address (you can do this in [MetaMask](https://metamask.zendesk.com/hc/en-us/articles/360015289452-How-to-create-an-additional-account-in-your-wallet)). Fund this address with testnet ETH (32 ETH and gas fees for each validator) using a faucet. See the list of [Goerli faucets](https://github.com/eth-clients/goerli#meta-data-g%C3%B6rli) and [Sepolia faucets](https://github.com/eth-clients/sepolia#meta-data-sepolia). + +:::note + +If you can't get ETH using the faucet, you can ask for help on the [EthStaker Discord](https://discord.io/ethstaker). + +::: + +Generate validator keys for one or more validators using the [Goerli Staking Launchpad](https://goerli.launchpad.ethereum.org/) (or [request to become validator on Sepolia](https://notes.ethereum.org/zvkfSmYnT0-uxwwEegbCqg)). + +:::info + +Save the password you use to generate each key pair in a `.txt` file. You should also have a `.json` file for each validator key pair. + +::: + +### 3. Start Besu + +Run the following command or specify the options in a [configuration file](../../how-to/configuration-file.md): + + + +# Goerli + +```bash +besu \ + --network=goerli \ + --rpc-http-enabled=true \ + --rpc-http-host=0.0.0.0 \ + --rpc-http-cors-origins="*" \ + --rpc-ws-enabled=true \ + --rpc-ws-host=0.0.0.0 \ + --host-allowlist="*" \ + --engine-host-allowlist="*" \ + --engine-rpc-enabled \ + --engine-jwt-secret= +``` + +# Holesky + +```bash +besu \ + --network=holesky \ + --rpc-http-enabled=true \ + --rpc-http-host=0.0.0.0 \ + --rpc-http-cors-origins="*" \ + --rpc-ws-enabled=true \ + --rpc-ws-host=0.0.0.0 \ + --host-allowlist="*" \ + --engine-host-allowlist="*" \ + --engine-rpc-enabled \ + --engine-jwt-secret= +``` + +# Sepolia + +```bash +besu \ + --network=sepolia \ + --rpc-http-enabled=true \ + --rpc-http-host=0.0.0.0 \ + --rpc-http-cors-origins="*" \ + --rpc-ws-enabled=true \ + --rpc-ws-host=0.0.0.0 \ + --host-allowlist="*" \ + --engine-host-allowlist="*" \ + --engine-rpc-enabled \ + --engine-jwt-secret= +``` + + + +Specify the path to the `jwtsecret.hex` file generated in [step 1](#1-generate-the-shared-secret) using the [`--engine-jwt-secret`](../../reference/cli/options.md#engine-jwt-secret) option. + +You can modify the option values and add other [command line options](../../reference/cli/options.md) as needed. + +### 4. Start the consensus client + +Refer to your consensus client documentation to configure and start the consensus client. + +:::info + +If you're running a validator client, make sure you set a fee recipient address. + +::: + +If you're using Teku, follow the [Besu and Teku testnet tutorial](../../tutorials/besu-teku-testnet.md#5-start-teku). + +### 5. Wait for the clients to sync + +After starting Besu and the consensus client, your node starts syncing and connecting to peers. + + + +# Besu logs + +```bash +{"@timestamp":"2023-02-03T04:43:49,555","level":"INFO","thread":"main","class":"DefaultSynchronizer","message":"Starting synchronizer.","throwable":""} +{"@timestamp":"2023-02-03T04:43:49,556","level":"INFO","thread":"main","class":"FastSyncDownloader","message":"Starting sync","throwable":""} +{"@timestamp":"2023-02-03T04:43:49,559","level":"INFO","thread":"main","class":"Runner","message":"Ethereum main loop is up.","throwable":""} +{"@timestamp":"2023-02-03T04:43:53,106","level":"INFO","thread":"Timer-0","class":"DNSResolver","message":"Resolved 2409 nodes","throwable":""} +{"@timestamp":"2023-02-03T04:45:04,803","level":"INFO","thread":"nioEventLoopGroup-3-10","class":"SnapWorldStateDownloader","message":"Downloading world state from peers for pivot block 16545859 (0x616ae3c4cf85f95a9bce2814a7282d75dc2eac36 +cb9f0fcc6f16386df70da3c5). State root 0xa7114541f42c62a72c8b6bb9901c2ccf4b424cd7f76570a67b82a183b02f25dc pending requests 0","throwable":""} +{"@timestamp":"2023-02-03T04:46:04,834","level":"INFO","thread":"EthScheduler-Services-3 (batchPersistAccountData)","class":"SnapsyncMetricsManager","message":"Worldstate download progress: 0.08%, Peer count: 8","throwable":""} +{"@timestamp":"2023-02-03T04:48:01,840","level":"INFO","thread":"EthScheduler-Services-3 (batchPersistAccountData)","class":"SnapsyncMetricsManager","message":"Worldstate download progress: 0.23%, Peer count: 8","throwable":""} +{"@timestamp":"2023-02-03T04:49:09,931","level":"INFO","thread":"EthScheduler-Services-3 (batchPersistAccountData)","class":"SnapsyncMetricsManager","message":"Worldstate download progress: 0.41%, Peer count: 11","throwable":""} +{"@timestamp":"2023-02-03T04:50:12,466","level":"INFO","thread":"EthScheduler-Services-3 (batchPersistAccountData)","class":"SnapsyncMetricsManager","message":"Worldstate download progress: 0.61%, Peer count: 10","throwable":""} +{"@timestamp":"2023-02-03T04:51:20,977","level":"INFO","thread":"EthScheduler-Services-3 (batchPersistAccountData)","class":"SnapsyncMetricsManager","message":"Worldstate download progress: 0.75%, Peer count: 10","throwable":""} +{"@timestamp":"2023-02-03T04:51:28,985","level":"INFO","thread":"EthScheduler-Services-29 (importBlock)","class":"FastImportBlocksStep","message":"Block import progress: 180400 of 16545859 (1%)","throwable":""} +``` + +# Teku logs + +```bash +2022-03-21 20:43:24.355 INFO - Syncing *** Target slot: 76092, Head slot: 2680, Remaining slots: 73412, Connected peers: 8 +2022-03-21 20:43:36.363 INFO - Syncing *** Target slot: 76093, Head slot: 2879, Remaining slots: 73214, Connected peers: 10 +2022-03-21 20:43:48.327 INFO - Syncing *** Target slot: 76094, Head slot: 3080, Remaining slots: 73014, Connected peers: 8 +2022-03-21 20:44:00.339 INFO - Syncing *** Target slot: 76095, Head slot: 3317, Remaining slots: 72778, Connected peers: 6 +2022-03-21 20:44:12.353 INFO - Syncing *** Target slot: 76096, Head slot: 3519, Remaining slots: 72577, Connected peers: 9 +``` + + + +If you're running the consensus client as a beacon node only, you're all set. If you're also running the consensus client as a validator client, ensure your clients are fully synced before submitting your staking deposit in the next step. This can take several days. + +### 6. Stake ETH + +Stake your testnet ETH for one or more validators using the [Goerli Staking Launchpad](https://goerli.launchpad.ethereum.org/). + +You can check your validator status by searching your Ethereum address on the [Goerli Beacon Chain explorer](https://goerli.beaconcha.in/). It may take up to multiple days for your validator to be activated and start proposing blocks. diff --git a/versioned_docs/version-23.10.1/public-networks/get-started/install/_category_.json b/versioned_docs/version-23.10.1/public-networks/get-started/install/_category_.json new file mode 100644 index 00000000000..043580c1474 --- /dev/null +++ b/versioned_docs/version-23.10.1/public-networks/get-started/install/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Install Besu", + "position": 2 +} diff --git a/versioned_docs/version-23.10.1/public-networks/get-started/install/binary-distribution.md b/versioned_docs/version-23.10.1/public-networks/get-started/install/binary-distribution.md new file mode 100644 index 00000000000..ae1e28a5b6c --- /dev/null +++ b/versioned_docs/version-23.10.1/public-networks/get-started/install/binary-distribution.md @@ -0,0 +1,94 @@ +--- +title: Install binary distribution +sidebar_position: 2 +description: Install or upgrade Hyperledger Besu from binary distribution +tags: + - public networks +--- + +# Install binary distribution + +## MacOS with Homebrew + +### Prerequisites + +- [Homebrew](https://brew.sh/) +- Java JDK + +:::caution + +Hyperledger Besu supports: + +- MacOS High Sierra 10.13 or later versions. +- Java 17+. You can install Java using `brew install openjdk`. Alternatively, you can manually install the [Java JDK](https://www.oracle.com/java/technologies/downloads). + +::: + +### Install (or upgrade) using Homebrew + +To install Besu using Homebrew: + +```bash +brew tap hyperledger/besu +brew install hyperledger/besu/besu +``` + +To upgrade an existing Besu installation using Homebrew: + +```bash +brew upgrade hyperledger/besu/besu +``` + +:::note + +If you've upgraded your MacOS version between installing and upgrading Besu, when running `brew upgrade hyperledger/besu/besu` you may be prompted to reinstall command line tools with `xcode-select --install`. + +::: + +:::note + +When upgrading Besu, you might be prompted to fix the remote branch names in Homebrew by using the command `brew tap --repair`. + +::: + +To display the Besu version and confirm installation: + +```bash +besu --version +``` + +To display Besu command line help: + +```bash +besu --help +``` + +## Linux / Unix + +### Prerequisites + +- [Java JDK 17+](https://www.oracle.com/java/technologies/downloads/) + +:::note Linux open file limit + +If synchronizing to Mainnet on Linux or other chains with large data requirements, increase the maximum number of open files allowed using `ulimit`. If the open files limit is not high enough, a `Too many open files` RocksDB exception occurs. + +::: + +:::tip + +We recommend installing [jemalloc](https://jemalloc.net/) to reduce memory usage. If using Ubuntu, you can install it with the command: `apt install libjemalloc-dev`. + +::: + +### Install from packaged binaries + +Download the Besu [packaged binaries](https://github.com/hyperledger/besu/releases). + +Unpack the downloaded files and change into the `besu-` directory. + +Display Besu command line help to confirm installation: + +```bash +bin/besu --help +``` diff --git a/versioned_docs/version-23.10.1/public-networks/get-started/install/index.md b/versioned_docs/version-23.10.1/public-networks/get-started/install/index.md new file mode 100644 index 00000000000..c4717c1fe65 --- /dev/null +++ b/versioned_docs/version-23.10.1/public-networks/get-started/install/index.md @@ -0,0 +1,23 @@ +--- +title: Installation options +description: Options for getting started with Hyperledger Besu +tags: + - public networks +--- + +# Installation options + +- [Docker image](run-docker-image.md) +- [Binaries](binary-distribution.md) + +## Build from source + +If you want to use the latest development version of Hyperledger Besu or a specific commit, build from source. Otherwise, use the [binary] or [Docker image] for more stable versions. + +View the [Hyperledger Wiki] for instructions to install Hyperledger Besu from source. + + + +[Hyperledger Wiki]: https://wiki.hyperledger.org/display/BESU/Building+from+source +[binary]: binary-distribution.md +[Docker image]: run-docker-image.md diff --git a/versioned_docs/version-23.10.1/public-networks/get-started/install/run-docker-image.md b/versioned_docs/version-23.10.1/public-networks/get-started/install/run-docker-image.md new file mode 100644 index 00000000000..a2561f40c08 --- /dev/null +++ b/versioned_docs/version-23.10.1/public-networks/get-started/install/run-docker-image.md @@ -0,0 +1,143 @@ +--- +title: Run Besu from Docker image +sidebar_position: 1 +description: Run Hyperledger Besu using the official docker image +tags: + - public networks +--- + +# Run Besu from a Docker image + +Hyperledger Besu provides a Docker image to run a Besu node in a Docker container. + +Use this Docker image to run a single Besu node without installing Besu. + +## Prerequisites + +- [Docker](https://docs.docker.com/install/) + +- MacOS or Linux + + :::info + + The Docker image doesn't run on Windows. + + ::: + +## Default node for Mainnet + +To run a Besu node in a container connected to the Ethereum Mainnet: + +```bash +docker run hyperledger/besu:latest +``` + +:::note + +https://hub.docker.com/r/hyperledger/besu/tags lists the available tags for the image. + +If you previously pulled `latest`, Docker runs the cached version. + +To ensure your image is up to date, pull the `latest` version again using `docker pull hyperledger/besu:latest`. + +::: + +## Expose ports + +Expose ports for P2P discovery, GraphQL, metrics, and HTTP and WebSocket JSON-RPC. You need to expose the ports to use the default ports or the ports specified using [`--rpc-http-port`](../../reference/cli/options.md#rpc-http-port), [`--p2p-port`](../../reference/cli/options.md#p2p-port), [`--rpc-ws-port`](../../reference/cli/options.md#rpc-ws-port), [`--metrics-port`](../../reference/cli/options.md#metrics-port), [`--graphql-http-port`](../../reference/cli/options.md#graphql-http-port), and [`--metrics-push-port`](../../reference/cli/options.md#metrics-push-port) options. + +To run Besu exposing local ports for access: + +```bash +docker run -p :8545 -p :8546 -p :30303 hyperledger/besu:latest --rpc-http-enabled --rpc-ws-enabled +``` + +:::note + +The examples on this page expose TCP ports only. To expose UDP ports, specify `/udp` at the end of the argument for the `-p` Docker subcommand option: + +```bash +docker run -p :/udp +``` + +See the [`docker run -p` documentation](https://docs.docker.com/engine/reference/commandline/run/#publish-or-expose-port--p---expose). + +::: + +To enable JSON-RPC HTTP calls to `127.0.0.1:8545` and P2P discovery on `127.0.0.1:13001`: + +```bash +docker run -p 8545:8545 -p 13001:30303 hyperledger/besu:latest --rpc-http-enabled +``` + +## Start Besu + +:::danger + +Don't mount a volume at the default data path (`/opt/besu`). Mounting a volume at the default data path interferes with the operation of Besu and prevents Besu from safely launching. + +To run a node that maintains the node state (key and database), [`--data-path`](../../reference/cli/options.md#data-path) must be set to a location other than `/opt/besu` and a storage volume mounted at that location. + +When running in a Docker container, [`--nat-method`](../../how-to/connect/specify-nat.md) must be set to `DOCKER` or `AUTO` (default). Don't set [`--nat-method`](../../how-to/connect/specify-nat.md) to `NONE` or `UPNP`. + +::: + +You can specify [Besu environment variables](../../reference/cli/options.md#specify-options) with the Docker image instead of the command line options. + +```bash title="Example" +docker run -p 30303:30303 -p 8545:8545 -e BESU_RPC_HTTP_ENABLED=true -e BESU_NETWORK=goerli hyperledger/besu:latest +``` + +:::caution Unsupported address type exception + +When running Besu from a Docker image, you might get the following exception: + +```bash +Unsupported address type exception when connecting to peer {}, this is likely due to ipv6 not being enabled at runtime. +``` + +This happens when the IPv6 support in Docker is disabled while connecting to an IPv6 peer, preventing outbound communication. IPv6 is disabled by default in Docker. + +[Enable IPv6 support in Docker](https://docs.docker.com/config/daemon/ipv6/) to allow outbound IPv6 traffic and allow connection with IPv6 peers. + +::: + +### Run a node for testing + +To run a node that mines blocks at a rate suitable for testing purposes with WebSocket enabled: + +```bash +docker run -p 8546:8546 --mount type=bind,source=/,target=/var/lib/besu hyperledger/besu:latest --miner-enabled --miner-coinbase fe3b557e8fb62b89f4916b721be55ceb828dbd73 --rpc-ws-enabled --network=dev --data-path=/var/lib/besu +``` + +### Run a node on Goerli testnet + +To run a node on Goerli: + +```bash +docker run -p 30303:30303 --mount type=bind,source=/,target=/var/lib/besu hyperledger/besu:latest --network=goerli --data-path=/var/lib/besu +``` + +### Run a node on Ethereum Mainnet + +To run a node on Ethereum Mainnet with the HTTP JSON-RPC service enabled: + +```bash +docker run -p 8545:8545 --mount type=bind,source=/,target=/var/lib/besu -p 30303:30303 hyperledger/besu:latest --rpc-http-enabled --data-path=/var/lib/besu +``` + +## Stop Besu and clean up resources + +When done running nodes, you can shut down the node container without deleting resources or you can delete the container after stopping it. Run `docker container ls` and `docker volume ls` to get the container and volume names. + +To stop a container: + +```bash +docker stop +``` + +To delete a container: + +```bash +docker rm +``` diff --git a/versioned_docs/version-23.10.1/public-networks/get-started/migrate-to-besu.md b/versioned_docs/version-23.10.1/public-networks/get-started/migrate-to-besu.md new file mode 100644 index 00000000000..2693411ced0 --- /dev/null +++ b/versioned_docs/version-23.10.1/public-networks/get-started/migrate-to-besu.md @@ -0,0 +1,15 @@ +--- +description: Migrate to Besu from a different Ethereum execution client. +tags: + - public networks +--- + +# Migrate to Besu + +Migrate from a different Ethereum [execution client](../concepts/the-merge.md#execution-clients) to Besu to contribute to [client diversity](https://clientdiversity.org/). + +To migrate from a different client, [configure Besu as an execution client](connect/mainnet.md#2-start-besu) and connect your [consensus client](../concepts/the-merge.md#consensus-clients) to Besu instead of your original execution client. + +To minimize downtime while [Besu syncs](connect/sync-node.md) and avoid downtime penalties, you can sync Besu with a new consensus layer instance. Once Besu has fully synced you can connect it to your existing consensus client. + +Find guides to switch from specific clients on the [client diversity website](https://clientdiversity.org/#switch). diff --git a/versioned_docs/version-23.10.1/public-networks/get-started/start-node.md b/versioned_docs/version-23.10.1/public-networks/get-started/start-node.md new file mode 100644 index 00000000000..2151516dec1 --- /dev/null +++ b/versioned_docs/version-23.10.1/public-networks/get-started/start-node.md @@ -0,0 +1,163 @@ +--- +title: Start Besu +sidebar_position: 3 +description: Start Besu on a public Ethereum network. +tags: + - public networks +--- + +# Start Besu + +Nodes can connect to Ethereum Mainnet and public testnets. + +Use the [`besu`](../reference/cli/options.md) command with the required command line options to start a node. + +## Prerequisites + +[Besu installed](install/binary-distribution.md) + +## Local block data + +When connecting to a network other than the network previously connected to, you must either delete the local block data or use the [`--data-path`](../reference/cli/options.md#data-path) option to specify a different data directory. + +To delete the local block data, delete the `database` directory in the `besu/build/distribution/besu-` directory. + +## Genesis configuration + +Besu specifies the genesis configuration, and sets the network ID and bootnodes when connecting to [Goerli](#run-a-node-on-goerli-testnet), [Sepolia](#run-a-node-on-sepolia-testnet), and [Mainnet](#run-a-node-on-ethereum-mainnet). + +:::info + +The Ropsten, Rinkeby, and Kiln testnets are deprecated. + +::: + +When you specify [`--network=dev`](../reference/cli/options.md#network), Besu uses the development mode genesis configuration with a fixed low difficulty. A node started with [`--network=dev`](../reference/cli/options.md#network) has an empty bootnodes list by default. + +The genesis files defining the genesis configurations are in the [Besu source files](https://github.com/hyperledger/besu/tree/master/config/src/main/resources). + +To define a genesis configuration, create a genesis file (for example, `genesis.json`) and specify the file using the [`--genesis-file`](../reference/cli/options.md#genesis-file) option. + +## Syncing and storage + +By default, Besu syncs to the current state of the blockchain using [fast sync](connect/sync-node.md#fast-synchronization) in: + +- Networks specified using [`--network`](../reference/cli/options.md#network) except for the `dev` development network. +- Ethereum Mainnet. + +We recommend using [snap sync](connect/sync-node.md#snap-synchronization) for a faster sync, by starting Besu with [`--sync-mode=X_SNAP`](../reference/cli/options.md#sync-mode). + +By default, Besu stores data in the [Forest of Tries](../concepts/data-storage-formats.md#forest-of-tries) format. We recommend using [Bonsai Tries](../concepts/data-storage-formats.md#bonsai-tries) for lower storage requirements, by starting Besu with [`--data-storage-format=BONSAI`](../reference/cli/options.md#data-storage-format). + +## Run a node for testing + +To run a node that mines blocks at a rate suitable for testing purposes: + +```bash +besu --network=dev --miner-enabled --miner-coinbase=0xfe3b557e8fb62b89f4916b721be55ceb828dbd73 --rpc-http-cors-origins="all" --host-allowlist="*" --rpc-ws-enabled --rpc-http-enabled --data-path=/tmp/tmpDatdir +``` + +You can also use the following [configuration file](../how-to/configuration-file.md) on the command line to start a node with the same options as above: + +```toml +network="dev" +miner-enabled=true +miner-coinbase="0xfe3b557e8fb62b89f4916b721be55ceb828dbd73" +rpc-http-cors-origins=["all"] +host-allowlist=["*"] +rpc-ws-enabled=true +rpc-http-enabled=true +data-path="/tmp/tmpdata-path" +``` + +:::danger Warning + +The following settings are a security risk in production environments: + +- Enabling the HTTP JSON-RPC service ([`--rpc-http-enabled`](../reference/cli/options.md#rpc-http-enabled)) and setting [`--rpc-http-host`](../reference/cli/options.md#rpc-http-host) to 0.0.0.0 exposes the RPC connection on your node to any remote connection. +- Setting [`--host-allowlist`](../reference/cli/options.md#host-allowlist) to `"*"` allows JSON-RPC API access from any host. +- Setting [`--rpc-http-cors-origins`](../reference/cli/options.md#rpc-http-cors-origins) to `"all"` or `"*"` allows cross-origin resource sharing (CORS) access from any domain. + +::: + +## Run a node on Goerli testnet + +To run a node on [Goerli](https://github.com/goerli/testnet) specifying a data directory: + +```bash +besu --network=goerli --data-path=/ +``` + +Where `` and `` are the path and directory to save the Goerli chain data to. + +See the [guide on connecting to a testnet](connect/testnet.md) for more information. + +## Run a node on Holesky testnet + +To run a node on [Holesky](https://github.com/eth-clients/holesky) specifying a data directory: + +```bash +besu --network=holesky --data-path=/ +``` + +Where `` and `` are the path and directory to save the Holesky chain data to. + +See the [guide on connecting to a testnet](connect/testnet.md) for more information. + +## Run a node on Sepolia testnet + +To run a node on [Sepolia](https://github.com/goerli/sepolia) specifying a data directory: + +```bash +besu --network=sepolia --data-path=/ +``` + +Where `` and `` are the path and directory to save the Sepolia chain data to. + +See the [guide on connecting to a testnet](connect/testnet.md) for more information. + +## Run a node on Ethereum Mainnet + +To run a node on the Ethereum Mainnet: + +```bash +besu +``` + +To run a node on Mainnet with the HTTP JSON-RPC service enabled and available for localhost only: + +```bash +besu --rpc-http-enabled +``` + +See the [guide on connecting to Mainnet](connect/mainnet.md) for more information. + +## Confirm node is running + +If you started Besu with the [`--rpc-http-enabled`](../reference/cli/options.md#rpc-http-enabled) option, use [cURL](https://curl.haxx.se/) to call [JSON-RPC API methods](../reference/api/index.md) to confirm the node is running. + +- `eth_chainId` returns the chain ID of the network. + + ```bash + curl -X POST --data '{"jsonrpc":"2.0","method":"eth_chainId","params":[],"id":1}' localhost:8545 + ``` + +- `eth_syncing` returns the starting, current, and highest block. + + ```bash + curl -X POST --data '{"jsonrpc":"2.0","method":"eth_syncing","params":[],"id":1}' localhost:8545 + ``` + + For example, after connecting to Mainnet, `eth_syncing` will return something similar to: + + ```json + { + "jsonrpc": "2.0", + "id": 1, + "result": { + "startingBlock": "0x0", + "currentBlock": "0x2d0", + "highestBlock": "0x66c0" + } + } + ``` diff --git a/versioned_docs/version-23.10.1/public-networks/get-started/system-requirements.md b/versioned_docs/version-23.10.1/public-networks/get-started/system-requirements.md new file mode 100644 index 00000000000..e0d9dfe7122 --- /dev/null +++ b/versioned_docs/version-23.10.1/public-networks/get-started/system-requirements.md @@ -0,0 +1,144 @@ +--- +title: System requirements +sidebar_position: 1 +description: Ensure you meet the system requirements to sync and run Besu. +tags: + - public networks +--- + +# System requirements + +Determine public network system requirements by checking CPU and disk space requirements using [Prometheus](../how-to/monitor/metrics.md). Grafana provides a [sample dashboard](https://grafana.com/grafana/dashboards/10273) for Besu. + +:::tip + +CPU requirements are highest when syncing to the network and typically reduce after the node is synchronized to the chain head. + +::: + +## Java distribution and installation + +Besu requires an installation of Java 17+ to run. +We currently recommend two Java distributions, [OpenJDK 17](https://jdk.java.net/17/) and +[OpenJ9](https://www.eclipse.org/openj9/), though you can experiment based on your needs. + +OpenJDK is the default for many Java users and is balanced in performance and garbage collection. +OpenJ9 consumes less memory and system resources, but can have worse performance on some setups. + +If you have more than 32GB RAM (for Besu and your [consensus client](../concepts/the-merge.md)), use OpenJDK. +If you have less RAM: + +* If you're on Linux (or Unix-based) and your CPU is x86-64 bit architecture (like Intel), use OpenJ9. +* If you're on ARM-64 CPU architecture (Mac M-series, Raspberry Pi), use OpenJDK. + +If you have OpenJDK installed or need a fresh installation of OpenJ9, you can pick up the OpenJ9 +docker image, or install the OpenJ9 JDK using the following steps: + +1. Get the [binaries](https://github.com/ibmruntimes/semeru17-binaries/releases) corresponding to + your OS architecture. + For example: + + ```bash + wget https://github.com/ibmruntimes/semeru17-binaries/releases/download/jdk-17.0.5%2B8_openj9-0.35.0/ibm-semeru-open-jdk_x64_linux_17.0.5_8_openj9-0.35.0.tar.gz + ``` +2. Uncompress the binaries: + + + + # Command + + ```bash + tar -xvf YOUR_J9_IMAGE.tar.gz + ``` + # Example + + ```bash + tar -xvf ibm-semeru-open-jdk_x64_linux_17.0.5_8_openj9-0.35.0.tar.gz + ``` + + + +3. Move the binaries to `bin` directory: + + + + # Command + + ```bash + sudo cp -r YOUR_IMAGE/ /usr/bin/ + ``` + # Example + + ```bash + sudo cp -r jdk-17.0.5+8/ /usr/bin/ + ``` + + + +4. Specify OpenJ9 for Java on your machine: + + + + # Command + + ```bash + sudo update-alternatives --install "/usr/bin/java" "java" "/usr/bin/YOUR_IMAGE" 1 + sudo update-alternatives --config java (and choose OpenJ9) + ``` + + # Example + + ```bash + sudo update-alternatives --install "/usr/bin/java" "java" "/usr/bin/jdk-17.0.5+8/bin/java" + ``` + + + + Change your `JAVA_HOME` to OpenJ9 (if using the JDK implementation), where `jdk-install-dir` is + the installation location you specified: + + + + # Command + + ```bash + export JAVA_HOME=jdk-install-dir` + ``` + + # Example + + ```bash + export JAVA_HOME=/usr/bin/jdk-17.0.5+8 + ``` + + + +## Java Virtual Machine size + +For Mainnet and testnets, the minimum [Java Virtual Machine (JVM) memory requirement is 8 GB](../how-to/configure-jvm/manage-memory.md). + +JVM memory requirements are highest when syncing, but will reduce after the node is synchronized to the chain head. Monitor your system to determine your actual JVM memory needs. + +## Disk space + +[Fast synchronization](../reference/cli/options.md#sync-mode) with [pruning](../concepts/data-storage-formats.md) enabled requires approximately 750 GB of disk space. [Full synchronization](../reference/cli/options.md#sync-mode) requires approximately 3 TB. + +## Disk type + +Use [local SSD storage](https://cloud.google.com/compute/docs/disks) for high throughput nodes (validators and RPC nodes). Read-only nodes can use a lower performance setup. + +You can use local SSDs through [SCSI interfaces](https://en.wikipedia.org/wiki/SCSI). For higher performance in production settings, we recommend upgrading to [NVMe interfaces](https://cloud.google.com/compute/docs/disks/local-ssd#performance). + +## AWS requirements + +We are running 22.4.2 Mainnet nodes using `m6gd.2xlarge` boxes. + +We synchronized the 22.4.2 Mainnet nodes using `m6gd.2xlarge` boxes. + +Using a larger box while synchronizing speeds up the sync process by giving it more resources. When the sync is completed, the box size can be reduced. + +:::caution + +If you are using a more recent release than 22.4.2, resource requirements may have increased. + +::: diff --git a/versioned_docs/version-23.10.1/public-networks/how-to/_category_.json b/versioned_docs/version-23.10.1/public-networks/how-to/_category_.json new file mode 100644 index 00000000000..6a19126f23e --- /dev/null +++ b/versioned_docs/version-23.10.1/public-networks/how-to/_category_.json @@ -0,0 +1,8 @@ +{ + "label": "How to", + "position": 3, + "link": { + "type": "generated-index", + "slug": "public-networks/how-to" + } +} diff --git a/versioned_docs/version-23.10.1/public-networks/how-to/configuration-file.md b/versioned_docs/version-23.10.1/public-networks/how-to/configuration-file.md new file mode 100644 index 00000000000..d3a428ce4a9 --- /dev/null +++ b/versioned_docs/version-23.10.1/public-networks/how-to/configuration-file.md @@ -0,0 +1,68 @@ +--- +title: Use a configuration file +sidebar_position: 3 +description: Specify options in the Besu configuration file. +tags: + - public networks + - private networks +--- + +# Use the Hyperledger Besu configuration file + +To specify command line options in a file, use a TOML configuration file. + +Save the configuration file and reuse it across node startups. To specify the configuration file, use the [`--config-file`](../reference/cli/options.md#config-file) option. + +To override an option specified in the configuration file, either specify the same option on the command line or as an [environment variable](../reference/cli/options.md#specify-options). For options specified in more than one place, the order of precedence is command line, environment variable, configuration file. + +:::note + +The configuration file is used for node-level settings. You can specify network-wide settings in the [genesis file](../concepts/genesis-file.md). + +::: + +## TOML specification + +The configuration file must be a valid TOML file composed of key/value pairs. Each key is the same as the corresponding command line option name without the leading dashes (`--`). + +Values must conform to TOML specifications for string, numbers, arrays, and booleans. Specific differences between the command line and the TOML file format are: + +- Comma-separated lists on the command line are string arrays in the TOML file. +- Enclose file paths, hexadecimal numbers, URLs, and <host:port> values in quotes. + +Table headings are ignored in TOML files. If you specify a valid Besu option under a table heading in the configuration file, Besu ignores the table heading and reads the option in the same way it does for options not under table headings. + +:::tip + +The [command line reference](../reference/cli/options.md) includes configuration file examples for each option. + +::: + +```toml title="Sample TOML configuration file" +# Valid TOML config file +data-path="~/besudata" # Path + +# Network +bootnodes=["enode://001@123:4567", "enode://002@123:4567", "enode://003@123:4567"] + +p2p-host="1.2.3.4" +p2p-port=1234 +max-peers=42 + +rpc-http-host="5.6.7.8" +rpc-http-port=5678 + +rpc-ws-host="9.10.11.12" +rpc-ws-port=9101 + +# Chain +genesis-file="~/genesis.json" # Path to the custom genesis file + +# Mining +miner-enabled=true +miner-coinbase="0xfe3b557e8fb62b89f4916b721be55ceb828dbd73" +``` + +```bash title="Starting Besu with a configuration file" +besu --config-file=/home/me/me_node/config.toml +``` diff --git a/versioned_docs/version-23.10.1/public-networks/how-to/configure-ha/_category_.json b/versioned_docs/version-23.10.1/public-networks/how-to/configure-ha/_category_.json new file mode 100644 index 00000000000..450cbdb623f --- /dev/null +++ b/versioned_docs/version-23.10.1/public-networks/how-to/configure-ha/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Configure high availability", + "position": 7 +} diff --git a/versioned_docs/version-23.10.1/public-networks/how-to/configure-ha/index.md b/versioned_docs/version-23.10.1/public-networks/how-to/configure-ha/index.md new file mode 100644 index 00000000000..0f642295f0a --- /dev/null +++ b/versioned_docs/version-23.10.1/public-networks/how-to/configure-ha/index.md @@ -0,0 +1,107 @@ +--- +description: Hyperledger Besu high availability +tags: + - public networks + - private networks +--- + +# High availability of JSON-RPC and RPC Pub/Sub APIs + +To enable high availability to the [RPC Pub/Sub API over WebSocket](../use-besu-api/rpc-pubsub.md) or the [JSON-RPC API](../use-besu-api/json-rpc.md), run and synchronize more than one Hyperledger Besu node to the network. Use a load balancer to distribute requests across nodes in the cluster that are ready to receive requests. + +![Load Balancer](../../../assets/images/LoadBalancer.png) + +:::tip + +We don't recommend putting [bootnodes](../../../private-networks/how-to/configure/bootnodes.md) behind a load balancer. + +::: + +:::info + +We recommend using load balancers over WebSockets because WebSockets are persistent connections associated with specific nodes. If you use load balancers configured in sticky mode over HTTP instead, the connection sticks to the associated node even when the node is congested and there is a lower load node available. If you use load balancers not configured in sticky mode over HTTP, the connections may switch from node to node, so some JSON-RPC requests may not provide expected results (for example, [`admin` methods](../../reference/api/index.md#admin-methods), [`net_enode`](../../reference/api/index.md#net_enode), [`net_peerCount`](../../reference/api/index.md#net_peercount), and [`eth_syncing`](../../reference/api/index.md#eth_syncing)). + +::: + +## Determine when a node is ready + +Use the [readiness endpoint](../use-besu-api/json-rpc.md#readiness-and-liveness-endpoints) to determine when a node is ready. + +:::note + +The minimum number of peers and number of blocks from the best known block for determining if a node considered ready is deployment specific. + +::: + +## Transaction nonces + +Besu obtains the nonce for the next transaction using [`eth_getTransactionCount`](../../reference/api/index.md#eth_gettransactioncount). The nonce depends on the transactions in the [transaction pool](../../concepts/transactions/pool.md). If sending [`eth_getTransactionCount`](../../reference/api/index.md#eth_gettransactioncount) and [`eth_sendRawTransaction`](../../reference/api/index.md#eth_sendrawtransaction) requests for a specific account to more than one node, the [`eth_getTransactionCount`](../../reference/api/index.md#eth_gettransactioncount) results might be incorrect. + +:::note + +If using [private transactions](../../../private-networks/concepts/privacy/private-transactions/index.md), retrieve the nonce using [`priv_getTransactionCount`](../../../private-networks/reference/api/index.md#priv_gettransactioncount) or [`priv_getEeaTransactionCount`](../../../private-networks/reference/api/index.md#priv_geteeatransactioncount) and send the private transactions using [`eea_sendRawTransaction`](../../../private-networks/reference/api/index.md#eea_sendrawtransaction). + +::: + +To get correct nonces when distributing requests across a cluster, either: + +- Track the next nonce outside of the Besu node (as MetaMask does). +- Configure the load balancer in sticky mode to send requests from a specific account to a single node, unless that node is unavailable. + +## Subscriptions + +You can subscribe to events using: + +- [RPC Pub/Sub over WebSockets](../use-besu-api/rpc-pubsub.md). +- [Filters over HTTP](../use-besu-api/access-logs.md). + +We recommend using [RPC Pub/Sub over WebSocket](../use-besu-api/rpc-pubsub.md) because WebSockets connections associate with a specific node and do not require using the load balancer in sticky mode. + +If using [filters over HTTP](../use-besu-api/access-logs.md), configure the load balancer in sticky mode to associate the subscription with a specific node. + +## Recover from dropped subscriptions + +Dropped subscriptions can occur because of: + +- A disconnected WebSockets connection +- The removal of the node serving the subscription from the ready pool. + +If there is a dropped subscription, missed events might occur while reconnecting to a different node. To recover dropped messages, create another subscription and follow the process for that [subscription type](../use-besu-api/rpc-pubsub.md#subscribe): + +- [`newHeads`](#new-headers) +- [`logs`](#logs) +- [`newPendingTransactions`](#new-pending-transactions) +- [`droppedPendingTransactions`](#dropped-pending-transactions) +- [`syncing`](#syncing). + +### New headers + +To request information on blocks from the last block before the subscription dropped to the first block received from the new subscription, use [`eth_getBlockByNumber`](../../reference/api/index.md#eth_getblockbynumber). + +### Logs + +To request logs from the block number of the last log received before the subscription dropped to the current chain head, use [`eth_getLogs`](../../reference/api/index.md#eth_getlogs). + +### New pending transactions + +To request all pending transactions for the new node, use [`txpool_besuTransactions`](../../reference/api/index.md#txpool_besutransactions). + +:::note + +Nodes do not all store the same pending transactions. + +::: + +### Dropped pending transactions + +To request all pending transactions for the new node, use [`txpool_besuTransactions`](../../reference/api/index.md#txpool_besutransactions). + +:::note + +Nodes do not all store the same pending transactions. + +::: + +### Syncing + +The syncing state of each node is specific to that node. To retrieve the syncing state of the new node, use [`eth_syncing`](../../reference/api/index.md#eth_syncing). diff --git a/versioned_docs/version-23.10.1/public-networks/how-to/configure-ha/sample-configuration.md b/versioned_docs/version-23.10.1/public-networks/how-to/configure-ha/sample-configuration.md new file mode 100644 index 00000000000..b018ba2a75b --- /dev/null +++ b/versioned_docs/version-23.10.1/public-networks/how-to/configure-ha/sample-configuration.md @@ -0,0 +1,99 @@ +--- +title: Sample load balancer configurations +sidebar_position: 1 +description: Sample load balancers +tags: + - public networks + - private networks +--- + +# Sample load balancer configurations + +## AWS + +For AWS, we recommend the Classic Load Balancer. The Classic Load Balancer is the easiest to configure and work with. Register the Hyperledger Besu instances to the load balancer and use the [liveness endpoint](../use-besu-api/json-rpc.md#readiness-and-liveness-endpoints) for health checks. + +For finer grain control, use the Application Load Balancer: + +- Configure one target group with n nodes. +- Configure multiple listeners with one per port (for example, `30303`, `8545`) you are using and route to the target group. +- Use the [liveness endpoint](../use-besu-api/json-rpc.md#readiness-and-liveness-endpoints) for health checks. +- Register the Besu instances multiple times with different ports. This is like configuring microservices on Elastic Container Service (ECS) or Elastic Kubernetes Service (EKS). + +### HTTPS redirection + +With either AWS load balancer, you can add certificates using ACM (Amazon Certificate Manager), add them to the load balancers, and redirect all HTTP calls to HTTPS. + +## Elastic Kubernetes Service + +For Elastic Kubernetes Service (AWS Kubernetes service) use the same load balancer configuration as when running nodes in Kubernetes. Use labels to specify nodes for the load balanced group. + +## Manual configurations + +Where applicable, we strongly recommend using service discovery. That is, pair your load balancer configuration with something that dynamically detects new nodes and removed failed nodes. + +For Nginx, use multiple upstreams (one for each port). Pair each upstream with a separate server block. + +```conf title="Upstreams paired with server blocks" +upstream discovery_tcp_30303 { + server 10.0.1.1:30303; + server 10.0.1.2:30303; +} + +upstream rpc_tcp_8545 { + server 10.0.1.1:8545; + server 10.0.1.2:8545; +} + +server { + listen 30303; + server_name some.host; + location / { + proxy_pass http://discovery_tcp_30303; + } +} + +server { + listen 8545; + server_name some.host; + location / { + proxy_pass http://rpc_tcp_8545; + } +} +... +``` + +For HAProxy, create multiple backend and frontend sets. + +```text title="Multiple backend and frontend sets" +frontend discovery-tcp-30303 + bind *:30303 + acl ... + ... + default_backend back-discovery-tcp-30303 + +frontend rpc-tcp-8545 + bind *:8545 + acl ... + ... + default_backend back-rpc-tcp-8545 + +backend back-discovery-tcp-30303 + balance leastconn + server node-01 10.0.1.1:30303 weight 1 check + server node-02 10.0.1.2:30303 weight 1 check + option ... + timeout server 600s + +backend back-rpc-tcp-8545 + balance leastconn + server node-01 10.0.1.1:8545 weight 1 check + server node-02 10.0.1.2:8545 weight 1 check + option .... + timeout server 600s +... +``` + +### HTTPS redirection + +To add HTTPS capability, update the above server blocks to include the certificates and specific ciphers. If you require an HTTP to HTTPS redirection, add separate blocks to return a 301 code with the new URI. diff --git a/versioned_docs/version-23.10.1/public-networks/how-to/configure-jvm/_category_.json b/versioned_docs/version-23.10.1/public-networks/how-to/configure-jvm/_category_.json new file mode 100644 index 00000000000..bb5cfebb77f --- /dev/null +++ b/versioned_docs/version-23.10.1/public-networks/how-to/configure-jvm/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Configure the Java Virtual Machine", + "position": 8 +} diff --git a/versioned_docs/version-23.10.1/public-networks/how-to/configure-jvm/index.md b/versioned_docs/version-23.10.1/public-networks/how-to/configure-jvm/index.md new file mode 100644 index 00000000000..95bf95bfac3 --- /dev/null +++ b/versioned_docs/version-23.10.1/public-networks/how-to/configure-jvm/index.md @@ -0,0 +1,12 @@ +--- +title: Configure Java and Besu +tags: + - public networks + - private networks +hide: + - feedback +--- + +# Configure the Java Virtual Machine + +This section contains information on configuring Besu and the Java Virtual Machine (JVM). diff --git a/versioned_docs/version-23.10.1/public-networks/how-to/configure-jvm/java-flight-recorder.md b/versioned_docs/version-23.10.1/public-networks/how-to/configure-jvm/java-flight-recorder.md new file mode 100644 index 00000000000..b1cd6e32fcd --- /dev/null +++ b/versioned_docs/version-23.10.1/public-networks/how-to/configure-jvm/java-flight-recorder.md @@ -0,0 +1,36 @@ +--- +title: Use Java Flight Recorder +sidebar_position: 3 +description: Using Java Flight Recorder with Hyperledger Besu +tags: + - public networks + - private networks +--- + +# Use Java Flight Recorder + +[Java Flight Recorder (JFR)](https://docs.oracle.com/javacomponents/jmc-5-4/jfr-runtime-guide/about.htm#JFRUH170) is a monitoring tool that collects information about the Java Virtual Machine (JVM) when Hyperledger Besu is running. Use the JFR as a tool to analyze Besu performance. + +## Enable Java Flight Recorder + +To enable JFR, set `BESU_OPTS` to the JFR tags as follows: + +```bash +export BESU_OPTS=-XX:StartFlightRecording=disk=true,delay=15s,dumponexit=true,\ +filename=/tmp/recording.jfr,maxsize=1024m,maxage=1d,\ +settings=profile,path-to-gc-roots=true +``` + +:::tip + +When recording, cleanly exiting Besu results in better data. If not possible to cleanly exit, the file may be missing some information not flushed to disk. + +::: + +Inspect the file written to `/tmp/recording.jfr` with tools such as [Mission Control](https://docs.oracle.com/javacomponents/jmc-5-5/jmc-user-guide/intro.htm#JMCCI109). + +:::danger + +If providing the output file to [ConsenSys Quorum support](https://consensys.net/quorum/support/), be aware that while JFR files don't contain secrets such as private keys, some details about the user configuration can be inferred from the JFR output. + +::: diff --git a/versioned_docs/version-23.10.1/public-networks/how-to/configure-jvm/manage-memory.md b/versioned_docs/version-23.10.1/public-networks/how-to/configure-jvm/manage-memory.md new file mode 100644 index 00000000000..9605ce18cfe --- /dev/null +++ b/versioned_docs/version-23.10.1/public-networks/how-to/configure-jvm/manage-memory.md @@ -0,0 +1,74 @@ +--- +title: Manage JVM memory +sidebar_position: 2 +description: Besu memory management +tags: + - public networks + - private networks +--- + +# Manage JVM memory + +You can manage Java Virtual Machine (JVM) memory usage for Besu by modifying the maximum heap size. + +By default, the JVM uses 25% of system RAM. For example, if you have 16 GB RAM installed, the JVM uses 4 GB by default. + +On public networks, we recommend setting the maximum heap size to: + +- 3 GB on an 8 GB RAM system. +- 5 GB on a 16 GB RAM system. +- 8 GB on a system with at least 24 GB RAM. + +:::note + +Setting a higher maximum heap size speeds up the sync period but doesn't have much impact after sync. Thus, we recommend setting it to 8 GB only when you have available RAM. + +::: + +You can set the maximum heap size using the `BESU_OPTS` environment variable and the `-Xmx` option. The following examples set the maximum heap size to 8 GB: + + + +# Exported environment variable example + +Set the variable for the whole shell before running Besu. + +```bash +export BESU_OPTS=-Xmx8g +``` + +# Inline environment variable example + +Set the variable only for the specific Besu command. + +```bash +BESU_OPTS=-Xmx8g besu [Besu options] +``` + +# `.service` file example + +```bash +[Service] +... +Environment="BESU_OPTS=-Xmx8g" +ExecStart=besu [Besu options] +... +``` + + + +## Manage the heap dump + +Heap dump file generation is disabled by default. To enable it, set the `-XX:+HeapDumpOnOutOfMemoryError` Java option. + +```bash +BESU_OPTS="-XX:+HeapDumpOnOutOfMemoryError" +``` + +When heap dump file generation is enabled, and an out-of-memory error occurs, the heap dump file is saved in the Besu runtime directory by default. + +The heap dump file might be large and can saturate your drive. It can be up to the size of the allocated memory. For example, for 8 GB heap memory, the file can be up to 8 GB. Specify the directory where you want the dump to be saved using the `-XX:HeapDumpPath` Java option. + +```bash +BESU_OPTS="-XX:HeapDumpPath=///" +``` diff --git a/versioned_docs/version-23.10.1/public-networks/how-to/configure-jvm/pass-jvm-options.md b/versioned_docs/version-23.10.1/public-networks/how-to/configure-jvm/pass-jvm-options.md new file mode 100644 index 00000000000..39196ef84fb --- /dev/null +++ b/versioned_docs/version-23.10.1/public-networks/how-to/configure-jvm/pass-jvm-options.md @@ -0,0 +1,21 @@ +--- +title: Pass JVM options +sidebar_position: 1 +description: Passing Java virtual machine JVM options to Hyperledger Besu at runtime +tags: + - public networks + - private networks +--- + +# Pass JVM options + +To perform tasks such as attaching a debugger or configuring the garbage collector, pass Java Virtual Machine (JVM) options to Hyperledger Besu. + +Besu passes the contents of the `BESU_OPTS` environment variable to the JVM. Set standard JVM options in the `BESU_OPTS` variable. + +For Bash-based executions, you can set the variable for only the scope of the program execution by setting it before starting Besu. + +```bash +BESU_OPTS=-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=5005 \ +besu --network=goerli +``` diff --git a/versioned_docs/version-23.10.1/public-networks/how-to/connect/_category_.json b/versioned_docs/version-23.10.1/public-networks/how-to/connect/_category_.json new file mode 100644 index 00000000000..cce59e7c3f8 --- /dev/null +++ b/versioned_docs/version-23.10.1/public-networks/how-to/connect/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Find and connect to peers", + "position": 5 +} diff --git a/versioned_docs/version-23.10.1/public-networks/how-to/connect/configure-ports.md b/versioned_docs/version-23.10.1/public-networks/how-to/connect/configure-ports.md new file mode 100644 index 00000000000..55df8aa0fd8 --- /dev/null +++ b/versioned_docs/version-23.10.1/public-networks/how-to/connect/configure-ports.md @@ -0,0 +1,48 @@ +--- +title: Configure ports +sidebar_position: 2 +description: To enable communication you must expose Hyperledger Besu ports appropriately +tags: + - public networks + - private networks +--- + +# Configure ports + +To enable communication you must expose Hyperledger Besu ports appropriately. The following shows an example port configuration for a Besu node on AWS. + +![Port Configuration](../../../assets/images/PortConfiguration.png) + +When running Besu from the [Docker image](../../get-started/install/run-docker-image.md), [expose ports](../../get-started/install/run-docker-image.md#exposing-ports). + +:::tip + +Besu supports [UPnP](specify-nat.md) for home or small office environments where a wireless router or modem provides NAT isolation. + +::: + +## P2P networking + +To enable peer discovery, the P2P UDP port must be open for inbound connections. Specify the P2P port using the [`--p2p-port`](../../reference/cli/options.md#p2p-port) option. The default is `30303`. + +We also recommend opening the P2P TCP port for inbound connections. This is not strictly required because Besu attempts to open outbound TCP connections. But if no nodes on the network are accepting inbound TCP connections, nodes cannot communicate. + +Combine the P2P port with the values for the [`--p2p-host`](../../reference/cli/options.md#p2p-host) and [`--p2p-interface`](../../reference/cli/options.md#p2p-interface) options when specifying the [P2P host](../../reference/cli/options.md#p2p-host) and [P2P network interface](../../reference/cli/options.md#p2p-interface). + +:::info + +By default, peer discovery listens on `0.0.0.0:30303` (all interfaces). If the device Besu is running on must bind to a specific network interface, specify the interface using the [`--p2p-interface`](../../reference/cli/options.md#p2p-interface) option. + +::: + +## JSON-RPC API + +To enable access to the [JSON-RPC API](../use-besu-api/json-rpc.md), open the HTTP JSON-RPC and WebSockets JSON-RPC ports to the intended users of the JSON-RPC API on TCP. + +Specify the HTTP and WebSockets JSON-RPC ports using the [`--rpc-http-port`](../../reference/cli/options.md#rpc-http-port) and [`--rpc-ws-port`](../../reference/cli/options.md#rpc-ws-port) options. The defaults are `8545` and `8546`. + +## Metrics + +To enable [Prometheus to access Besu](../monitor/metrics.md), open the metrics port or metrics push port to Prometheus or the Prometheus push gateway on TCP. + +Specify the ports for Prometheus and Prometheus push gateway using the [`--metrics-port`](../../reference/cli/options.md#metrics-port) and [`--metrics-push-port`](../../reference/cli/options.md#metrics-push-port) options. The defaults are `9545` and `9001`. diff --git a/versioned_docs/version-23.10.1/public-networks/how-to/connect/manage-peers.md b/versioned_docs/version-23.10.1/public-networks/how-to/connect/manage-peers.md new file mode 100644 index 00000000000..84e29fe2573 --- /dev/null +++ b/versioned_docs/version-23.10.1/public-networks/how-to/connect/manage-peers.md @@ -0,0 +1,88 @@ +--- +title: Manage peers +sidebar_position: 3 +description: Managing Hyperledger Besu peers +tags: + - public networks + - private networks +--- + +# Manage peers + +Hyperledger Besu peer-to-peer (P2P) discovery happens periodically based on the number of peers in a network and the node's [peer limit](#limit-peers). + +The frequency of discovery isn't configurable, but you can [limit remote connections](#limit-remote-connections) in public networks and [randomly prioritize connections](../../reference/cli/options.md#random-peer-priority-enabled) in small, stable networks. + +:::info + +You can use [`admin_addPeer`](../../reference/cli/options.md#admin_addpeer) to attempt a specific connection, but this isn't P2P discovery. + +::: + +In private networks, we recommend [using bootnodes](../../../private-networks/how-to/configure/bootnodes.md) to initially discover peers. + +## Limit peers + +You can limit peers to reduce the bandwidth, CPU time, and disk access Besu uses to manage and respond to peers. + +To reduce the maximum number of peers, use the [`--max-peers`](../../reference/cli/options.md#max-peers) option. The default is 25. + +:::caution + +The minimum number of peers is set by the `--Xp2p-peer-lower-bound` option, which also has a default of 25. If you reduce the `--max-peers` from the default, you must also set the `--Xp2p-peer-lower-bound` option to the same value or lower. For example, if you decrease `--max-peers` to 20, set `--Xp2p-peer-lower-bound` to 20 or lower. + +Note, `Xp2p-peer-lower-bound` is an early access option. + +::: + +## Limit remote connections + +Prevent eclipse attacks when using [`--sync-mode`](../../reference/cli/options.md#sync-mode) and [`--fast-sync-min-peers`](../../reference/cli/options.md#fast-sync-min-peers) on public networks by enabling the [remote connection limits](../../reference/cli/options.md#remote-connections-limit-enabled). + +In private and permissioned networks with only trusted peers, enabling the remote connection limits is unnecessary and might adversely affect the speed at which nodes can join the network. Limiting remote connections can cause a closed group of peers to form when the number of nodes in the network is slightly higher than [`--max-peers`](../../reference/cli/options.md#max-peers). The nodes in this closed group are all connected to each other and can't accept more connections. + +:::tip + +You can use [`--random-peer-priority-enabled`](../../reference/cli/options.md#random-peer-priority-enabled) to help prevent closed groups of peers in small, stable networks. + +::: + +## Monitor peer connections + +JSON-RPC API methods to monitor peer connections include: + +- [`net_peerCount`](../../reference/api/index.md#net_peercount). +- [`admin_peers`](../../reference/api/index.md#admin_peers). +- [`debug_metrics`](../../reference/api/index.md#debug_metrics). + +Each peer entry returned by [`admin_peers`](../../reference/api/index.md#admin_peers) includes a `protocols` section. Use the information in the `protocols` section to: + +- Determine the health of peers. For example, an external process can use [`admin_peers`](../../reference/api/index.md#admin_peers) and [`admin_removePeer`](../../reference/api/index.md#admin_removepeer) to disconnect from peers that are stalled at a single difficulty for an extended period of time. + +- Monitor node health. For example, if peers report increasing difficulties but the node is stuck at the same block number, the node may be on a different fork to most peers. + +- Determine which protocol level peers are communicating with. For example, you can see if `"version": 65` is being used to reduce transaction sharing traffic. + +## List node connections + +The default logging configuration doesn't list node connection and disconnection messages. To enable listing them, set the [`--logging`](../../reference/cli/options.md#logging) option to `DEBUG`. For more verbosity, set the option to `TRACE`. + +The console logs connection and disconnection events when the log level is `DEBUG` or higher. If the message `Successfully accepted connection from ...` displays, connections are getting through the firewalls. + +```bash title="Sample log output" +2018-10-16 12:37:35.479-04:00 | nioEventLoopGroup-3-1 | INFO | NettyP2PNetwork | Successfully accepted connection from 0xa979fb575495b8d6db44f750317d0f4622bf4c2aa3365d6af7c284339968eef29b69ad0dce72a4d8db5ebb4968de0e3bec910127f134779fbcb0cb6d3331163c +``` + +## Disable discovery + +To disable P2P discovery, set the [`--discovery-enabled`](../../reference/cli/options.md#discovery-enabled) option to `false`. + +With discovery disabled, peers can't open connections with the node unless they were previously discovered or manually peered (for example, using [`admin_addPeer`](../../reference/api/index.md#admin_addpeer)). [Static nodes](static-nodes.md) can also open connections. + +## Troubleshoot + +If your nodes fail to connect, ensure the [required ports are open](configure-ports.md). + +If your nodes are running in AWS, check you have appropriate `SecurityGroups` to allow access to the required ports. + +Check that the [enode URLs](../../concepts/node-keys.md#enode-url) specified for [bootnodes](../../../private-networks/how-to/configure/bootnodes.md) or [static nodes](static-nodes.md) match the enode URLs displayed when starting the remote nodes. diff --git a/versioned_docs/version-23.10.1/public-networks/how-to/connect/specify-nat.md b/versioned_docs/version-23.10.1/public-networks/how-to/connect/specify-nat.md new file mode 100644 index 00000000000..6438ab2fc13 --- /dev/null +++ b/versioned_docs/version-23.10.1/public-networks/how-to/connect/specify-nat.md @@ -0,0 +1,93 @@ +--- +title: Specify NAT method +sidebar_position: 4 +description: Configuring NAT with Hyperledger Besu +tags: + - public networks + - private networks +--- + +# Specify the NAT method + +Use the [`--nat-method`](../../reference/cli/options.md#nat-method) option to specify the NAT method. Options are: [`UPNP`](#upnp), [`KUBERNETES`](#kubernetes), [`DOCKER`](#docker), [`AUTO`](#auto), and [`NONE`](#none). + +The [enode](../../concepts/node-keys.md#enode-url) advertised to other nodes during discovery is the external IP address and port. The [`admin_nodeInfo`](../../reference/api/index.md#admin_nodeinfo) JSON-RPC API method returns the external address and port for the `enode` and `listenAddr` properties. + +While Hyperledger Besu is running, the following are not supported: + +- IP address changes +- Changing NAT methods. To change the NAT method, restart the node with the [`--nat-method`](../../reference/cli/options.md#nat-method) option set. + +## Auto + +`AUTO` detects if Besu is running inside a Kubernetes cluster or a Docker container. + +- If Besu is running in a Kubernetes cluster, `AUTO` sets to [`KUBERNETES`](#kubernetes). +- If Besu is running in a Docker container, `AUTO` sets to [`DOCKER`](#docker). +- If Besu is not running in Kubernetes or Docker container, `AUTO` sets to [`NONE`](#none). + +`AUTO` is the default NAT method. + +The following log shows an automatic detection failure. + +```log title="The following log shows an automatic detection failure" +INFO | KubernetesNatManager | Starting kubernetes NAT manager. +DEBUG | KubernetesNatManager | Trying to update information using Kubernetes client SDK. +DEBUG | NatService | Nat manager failed to configure itself automatically due to the following reason Service not found. NONE mode will be used +INFO | NetworkRunner | Starting Network. +``` + +:::tip + +If automatic detection fails, set the IP and ports in [`NONE`](#none) mode. + +::: + +## UPnP + +Specify `UPNP` to quickly allow inbound peer connections without manual router configuration. Use UPnP in home or small office environments where a wireless router or modem provides NAT isolation. + +UPnP automatically detects if a node is running in a UPnP environment and provides port forwarding. UPnP might introduce delays during node startup, especially on networks without a UPnP gateway device. + +Use `UPNPP2PONLY` if you wish to enable UPnP only for p2p traffic. + +:::tip + +UPnP support is often disabled by default in networking firmware. If disabled by default, you must explicitly enable UPnP support. + +::: + +:::info + +When the NAT method is set to `UPNP`, the advertised port is the same as the [listening port](../../reference/cli/options.md#p2p-port). + +::: + +## Kubernetes + +Specify `KUBERNETES` to explicitly specify Hyperledger Besu is running inside a Kubernetes cluster. Besu automatically detects if it's running inside of a Kubernetes cluster and interacts with Kubernetes APIs as required to determine external IP addresses and exposed ports. + +In Kubernetes, the Ingress IP of the load balancer will be used as the external IP for Besu. A load balancer service can map any incoming port to a target port. These mapping rules will be the one retrieved by Besu. + +A tutorial to [Configure the Nat Manager for Kubernetes](../../../private-networks/tutorials/kubernetes/nat-manager.md) is available. + +## Docker + +Specify `DOCKER` to explicitly specify Hyperledger Besu is running inside a Docker container. If you specify `DOCKER`, you advertise the host IP address not the container IP address. + +The host IP address is the advertised host specified in the [`docker run` command](https://docs.docker.com/engine/reference/commandline/run/#add-entries-to-container-hosts-file---add-host). If not specified in the `docker run` command, the advertised host defaults to the values for [`--p2p-host`](../../reference/cli/options.md#p2p-host) and [`--p2p-port`](../../reference/cli/options.md#p2p-port). + +## None + +Specify `NONE` to explicitly configure the external IP address and ports advertised using: + +- [`--p2p-host`](../../reference/cli/options.md#p2p-host) and [`--p2p-port`](../../reference/cli/options.md#p2p-port) for the P2P service. +- [`--rpc-http-host`](../../reference/cli/options.md#rpc-http-host) and [`--rpc-http-port`](../../reference/cli/options.md#rpc-http-port) for the JSON-RPC HTTP service. + +The P2P and JSON-RPC HTTP hosts and ports are advertised in the [`net_services`](../../reference/api/index.md#net_services) method. + +:::tip + +When the NAT method is set to `NONE`, the advertised port is the same as the [listening port](../../reference/cli/options.md#p2p-port). + +::: diff --git a/versioned_docs/version-23.10.1/public-networks/how-to/connect/static-nodes.md b/versioned_docs/version-23.10.1/public-networks/how-to/connect/static-nodes.md new file mode 100644 index 00000000000..aa0eb09641f --- /dev/null +++ b/versioned_docs/version-23.10.1/public-networks/how-to/connect/static-nodes.md @@ -0,0 +1,65 @@ +--- +title: Configure static nodes +sidebar_position: 1 +description: Configuring static nodes +tags: + - public networks + - private networks +--- + +# Static nodes + +Static nodes are a configured set of trusted nodes. Static nodes are exempt from [maximum peer](manage-peers.md#limit-peers) and [remote connection](manage-peers.md#limit-remote-connections) limits. + +Besu attempts to maintain connections with static nodes by periodically initiating a connection to any unconnected static node. + +:::tip + +Bootnodes and static nodes are parallel methods for finding peers. Depending on your use case, you can use only bootnodes, only static nodes, or both bootnodes and static nodes. For example, you run multiple nodes on Mainnet (discovery using bootnodes), but want to ensure your nodes are always connected (using static nodes). + +To find peers, configure one or more [bootnodes](../../../private-networks/how-to/configure/bootnodes.md). To configure a specific set of peer connections, use static nodes. + +::: + +## Configure static nodes + +To configure a network of static nodes: + +1. List the [enode URLs](../../concepts/node-keys.md#enode-url) of the nodes in the [`static-nodes.json` file](#static-nodesjson-file). + +1. Save the `static-nodes.json` file in the data directory (specified by [`--data-path`](../../reference/cli/options.md#data-path)) of each node. Alternatively, you can explicitly specify the static nodes file on the command line using [`--static-nodes-file`](../../reference/cli/options.md#static-nodes-file). + +1. Start Besu with discovery disabled using [`--discovery-enabled=false`](../../reference/cli/options.md#discovery-enabled). + +To update the list of static peers at run time, use the [`admin_addPeer`](../../reference/api/index.md#admin_addpeer) and [`admin_removePeer`](../../reference/api/index.md#admin_removepeer) JSON-RPC API methods. + +:::note + +Runtime modifications of static nodes are not persisted between runs. The `static-nodes.json` file is not updated by the `admin_addPeer` and `admin_removePeer` methods. + +Nodes not in the list of the static nodes are not prevented from connecting. To prevent nodes from connecting, use [Permissioning](../../../private-networks/concepts/permissioning/index.md). + +::: + +:::tip + +If the added peer does not appear in the peer list (returned by [`admin_peers`](../../reference/api/index.md#admin_peers)), check the the supplied [enode URL](../../concepts/node-keys.md#enode-url) is correct, the node is running, and the node is listening for TCP connections on the endpoint. + +::: + +### `static-nodes.json` file + +The `static-nodes.json` file must be in the data directory (specified by [`--data-path`](../../reference/cli/options.md#data-path)) and contain a JSON array of [enode URLs](../../concepts/node-keys.md#enode-url). + +```json title="Example" +[ + "enode://cea71cb65a471037e01508cebcc178f176f9d5267bf29507ea1f6431eb6a5dc67d086dc8dc54358a72299dab1161febc5d7af49d1609c69b42b5e54544145d4f@127.0.0.1:30303", + "enode://ca05e940488614402705a6b6836288ea902169ecc67a89e1bd5ef94bc0d1933f20be16bc881ffb4be59f521afa8718fc26eec2b0e90f2cd0f44f99bc8103e60f@127.0.0.1:30304" +] +``` + +:::note + +Each node has a `static-nodes.json` file. We recommend each node in the network has the same `static-nodes.json` file. + +::: diff --git a/versioned_docs/version-23.10.1/public-networks/how-to/develop/_category_.json b/versioned_docs/version-23.10.1/public-networks/how-to/develop/_category_.json new file mode 100644 index 00000000000..8c8a280b930 --- /dev/null +++ b/versioned_docs/version-23.10.1/public-networks/how-to/develop/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Develop dapps", + "position": 9 +} diff --git a/versioned_docs/version-23.10.1/public-networks/how-to/develop/client-libraries.md b/versioned_docs/version-23.10.1/public-networks/how-to/develop/client-libraries.md new file mode 100644 index 00000000000..009e82d8d35 --- /dev/null +++ b/versioned_docs/version-23.10.1/public-networks/how-to/develop/client-libraries.md @@ -0,0 +1,31 @@ +--- +title: Use client libraries +sidebar_position: 2 +description: Hyperledger Besu client libraries +tags: + - public networks + - private networks +--- + +# Use client libraries + +Dapps use client libraries, such as [web3.js](https://github.com/ethereum/web3.js/), [web3j](https://github.com/web3j/web3j), or [ethereumj](https://github.com/ethereum/ethereumj), to forward JSON-RPC requests to Hyperledger Besu. Any client library implementing core Ethereum RPC methods works with Besu. + +Use the [web3js-quorum library](../../../private-networks/how-to/use-privacy/web3js-quorum.md) with Besu for [privacy features](../../../private-networks/concepts/privacy/index.md). + +![Client Libraries](../../../assets/images/Hyperledger-Besu-Client-Libraries.png) + +Use client libraries to: + +- Create signed transactions +- [Create and send private transactions]. + +:::note + +[Hyperledger Besu does not support key management inside the client](../send-transactions.md#use-wallets-for-key-management). + +::: + + + +[Create and send private transactions]: ../../../private-networks/how-to/send-transactions/private-transactions.md diff --git a/versioned_docs/version-23.10.1/public-networks/how-to/develop/hardhat.md b/versioned_docs/version-23.10.1/public-networks/how-to/develop/hardhat.md new file mode 100644 index 00000000000..06b4a800171 --- /dev/null +++ b/versioned_docs/version-23.10.1/public-networks/how-to/develop/hardhat.md @@ -0,0 +1,74 @@ +--- +title: Use Hardhat +sidebar_position: 1 +description: Using Hyperledger Besu with Hardhat +tags: + - public networks + - private networks +--- + +# Use Hardhat + +Developing for Hyperledger Besu using Hardhat is the same as developing for public Ethereum networks using Hardhat. Hardhat +supports Besu with the only difference being Besu does not support private key management. + +You can therefore use a wallet provider, or specify your private key in the code. + +## Private key management + +### Use an HD wallet + +To add the wallet provider, update the `hardhat.config.ts` file in the project directory. Replace: + +- `` with the JSON-RPC endpoint (IP address and port) of a Besu node. +- `` with the list of words that make up your account's mnemonic. +- ` your password if used +- `` your account's private key + +```js +module.exports = { + // See + // for more about customizing your Hardhat configuration! + networks: { + besuWallet: { + url: "", + accounts: { + mnemonic: "", + path: "m/44'/60'/0'/0", + initialIndex: 0, + count: 1, + passphrase: "", + }, + }, + }, +}; +``` + +### Specify your private key in code + +:::danger + +Ensure you do not commit private keys to source control like Github, always inject your keys at runtime as environment variables, or +use a vault or similar. + +::: + +```js +const provider = new ethers.JsonRpcApiProvider(); +const wallet = new ethers.Wallet(); +// connect the wallet to the provider +const signer = wallet.connect(provider); + +``` + +## Start a Besu node + +Start a Besu node with JSON-RPC enabled on the endpoint specified in the Hardhat configuration file. + +## Deploy a contract + +To deploy a contract onto the Besu network: + +```bash +npx hardhat scripts run ./scripts/deploy_my_contract.ts --network besuWallet +``` diff --git a/versioned_docs/version-23.10.1/public-networks/how-to/monitor/_category_.json b/versioned_docs/version-23.10.1/public-networks/how-to/monitor/_category_.json new file mode 100644 index 00000000000..9be56b91890 --- /dev/null +++ b/versioned_docs/version-23.10.1/public-networks/how-to/monitor/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Monitor nodes", + "position": 6 +} diff --git a/versioned_docs/version-23.10.1/public-networks/how-to/monitor/index.md b/versioned_docs/version-23.10.1/public-networks/how-to/monitor/index.md new file mode 100644 index 00000000000..c2c49d0e9fd --- /dev/null +++ b/versioned_docs/version-23.10.1/public-networks/how-to/monitor/index.md @@ -0,0 +1,15 @@ +--- +description: Monitoring using metrics and logging +tags: + - public networks + - private networks +--- + +# Monitor Besu + +Monitoring enables identification of node and network issues. Specifically, configuring metrics and logging enables: + +- [Visual representation of declining node or network performance](metrics.md) +- [Collection of log files to enable issue diagnosis](logging.md). + +For an overview of monitoring Hyperledger Besu, view [this recording](https://www.youtube.com/watch?v=7BuutRe0I28&feature=youtu.be). diff --git a/versioned_docs/version-23.10.1/public-networks/how-to/monitor/logging.md b/versioned_docs/version-23.10.1/public-networks/how-to/monitor/logging.md new file mode 100644 index 00000000000..c994d6388c6 --- /dev/null +++ b/versioned_docs/version-23.10.1/public-networks/how-to/monitor/logging.md @@ -0,0 +1,77 @@ +--- +title: Configure logging +sidebar_position: 3 +description: Hyperledger Besu log level setting and log formatting +path: blob/master/besu/src/main/resources/ +source: log4j2.xml +tags: + - public networks + - private networks +--- + +# Use logging + +Hyperledger Besu uses Log4J2 for logging and provides two methods to configure logging behavior: + +- [Basic](#basic-logging) - Changes the log level. +- [Advanced](#advanced-logging) - Configures the output and format of the logs. + +[Quorum Developer Quickstart](https://github.com/ConsenSys/quorum-dev-quickstart) provides an [example implementation using Elastic Stack](../../../private-networks/how-to/monitor/elastic-stack.md) for log management. + +## Basic logging + +Use the [`--logging`](../../reference/cli/options.md#logging) command line option to specify logging verbosity. The [`--logging`](../../reference/cli/options.md#logging) option changes the volume of events displayed in the log. Valid log levels are `OFF`, `ERROR`, `WARN`, `INFO`, `DEBUG`, `TRACE`, `ALL`. The default level is `INFO`. + +For most use cases, the basic method provides enough configurability. + +:::tip + +Use the [`admin_changeLogLevel`](../../reference/api/index.md#admin_changeloglevel) API method to change the log level while Besu is running. + +::: + +## Advanced logging + +You can provide your own logging configuration using the standard Log4J2 configuration mechanisms. For example, the following Log4J2 configuration is the same as the [default configuration] except for the exclusion of logging of stack traces for exceptions. + +```xml title="debug.xml" + + + + INFO + + + + + + + + + + + + + +``` + +To use your custom configuration, set the environment variable `LOG4J_CONFIGURATION_FILE` to the location of your configuration file. + +If you have more specific requirements, you can create your own [log4j2 configuration](https://logging.apache.org/log4j/2.x/manual/configuration.html). + +For Bash-based executions, you can set the variable for only the scope of the program execution by setting it before starting Besu. + +To set the debug logging and start Besu connected to the Goerli testnet: + +```bash +LOG4J_CONFIGURATION_FILE=./debug.xml besu --network=goerli +``` + +### Log rotation + +[Quorum Developer Quickstart](https://github.com/ConsenSys/quorum-dev-quickstart) logging configuration defines a [log rotation to restrict the size of the log files]. + + + +[default configuration]: https://github.com/hyperledger/besu/blob/750580dcca349d22d024cc14a8171b2fa74b505a/besu/src/main/resources/log4j2.xml +[log rotation to restrict the size of the log files]: https://github.com/ConsenSys/quorum-dev-quickstart/blob/b72a0f64d685c851bf8be399a8e33bbdf0e09982/files/besu/config/besu/log-config.xml +[default configuration]: https://github.com/hyperledger/besu/blob/750580dcca349d22d024cc14a8171b2fa74b505a/besu/src/main/resources/log4j2.xml diff --git a/versioned_docs/version-23.10.1/public-networks/how-to/monitor/metrics.md b/versioned_docs/version-23.10.1/public-networks/how-to/monitor/metrics.md new file mode 100644 index 00000000000..e76b90abbc2 --- /dev/null +++ b/versioned_docs/version-23.10.1/public-networks/how-to/monitor/metrics.md @@ -0,0 +1,297 @@ +--- +title: Use metrics +sidebar_position: 1 +description: Monitoring and metrics +tags: + - public networks + - private networks +--- + +# Use metrics to monitor node performance + +To enable the [Prometheus](https://prometheus.io/) monitoring and alerting service to access Hyperledger Besu metrics, use the [`--metrics-enabled`](../../reference/cli/options.md#metrics-enabled) option. Use [Grafana](https://grafana.com/) to visualize the collected data. See the sample [Besu Full Grafana dashboard](https://grafana.com/grafana/dashboards/16455-besu-full/). + +The Besu example networks have [monitoring with Prometheus and Grafana configured]. + +Use Prometheus to monitor the number of blocks your Besu node is behind the chain head, and to alert you that your node is not keeping up with the chain head. + +[This recording](https://www.youtube.com/watch?v=7BuutRe0I28&feature=youtu.be) shows examples of monitoring Hyperledger Besu. + +## Install Prometheus + +To use Prometheus with Besu, install the [Prometheus main component](https://prometheus.io/download/). On MacOS, install with [Homebrew](https://formulae.brew.sh/formula/prometheus): + +```bash +brew install prometheus +``` + +:::tip + +You can also install: + +- Exporters that send system metrics to Prometheus to monitor non-Besu-specific items such as disk and CPU usage. +- Other Prometheus components, such as the Alert Manager. Additional configuration is not required for these components because Prometheus handles and analyzes data directly from the feed. + +::: + +## Set up and run Prometheus with Besu + +To configure Prometheus and run with Besu: + +1. Configure Prometheus to poll Besu. For example, add the following YAML fragment to the `scrape_configs` block of the `prometheus.yml` file: + + + + # Fragment to insert in prometheus.yml + + ```yml + - job_name: besu + scrape_interval: 15s + scrape_timeout: 10s + metrics_path: /metrics + scheme: http + static_configs: + - targets: + - localhost:9545 + ``` + + # Full prometheus.yml example + + ```yml + global: + scrape_interval: 15s + + scrape_configs: + - job_name: "prometheus" + static_configs: + - targets: ["localhost:9090"] + - job_name: besu + scrape_interval: 15s + scrape_timeout: 10s + metrics_path: /metrics + scheme: http + static_configs: + - targets: + - localhost:9545 + ``` + + + + Prometheus requires 3 MB of space per node per hour for metrics, with a `scrape_interval` of 15 seconds. + +2. Start Besu with the [`--metrics-enabled`](../../reference/cli/options.md#metrics-enabled) option. To start a single node for testing with metrics enabled, run the following command: + + + + # Syntax + + ```bash + besu --network=dev --miner-enabled --miner-coinbase --rpc-http-cors-origins="all" --rpc-http-enabled --metrics-enabled + ``` + + # Example + + ```bash + besu --network=dev --miner-enabled --miner-coinbase fe3b557e8fb62b89f4916b721be55ceb828dbd73 --rpc-http-cors-origins="all" --rpc-http-enabled --metrics-enabled + ``` + + + + To specify the host and port on which Prometheus accesses Besu, use the [`--metrics-host`](../../reference/cli/options.md#metrics-host) and [`--metrics-port`](../../reference/cli/options.md#metrics-port) options. The default host and port are 127.0.0.1 (`localhost`) and 9545. + + :::danger + + To avoid DNS rebinding attacks, if running Prometheus on a different host than your Besu node (any host other than `localhost`), add the hostname that Prometheus uses to [`--host-allowlist`](../../reference/cli/options.md#host-allowlist). + + For example, if Prometheus is configured to get metrics from `http://besu.local:8008/metrics`, then `besu.local` has to be in `--host-allowlist`. + + ::: + +3. In another terminal, run Prometheus specifying the `prometheus.yml` file: + + ```bash + prometheus --config.file=prometheus.yml + ``` + +4. View the [Prometheus graphical interface](#view-prometheus-graphical-interface). + + :::tip + + Use a log ingestion tool, such as Logstash, to parse the logs and alert you to configured anomalies. + + ::: + +## Run Prometheus with Besu in push mode + +The [`--metrics-enabled`](../../reference/cli/options.md#metrics-enabled) option enables Prometheus polling of Besu, but sometimes metrics are hard to poll (for example, when running inside Docker containers with varying IP addresses). To enable Besu to push metrics to a [Prometheus push gateway](https://github.com/prometheus/pushgateway), use the [`--metrics-push-enabled`](../../reference/cli/options.md#metrics-push-enabled) option. + +To configure Prometheus and run with Besu pushing to a push gateway: + +1. Configure Prometheus to read from a push gateway. For example, add the following YAML fragment to the `scrape_configs` block of the `prometheus.yml` file: + + ```yml + - job_name: push-gateway + metrics_path: /metrics + scheme: http + static_configs: + - targets: + - localhost:9091 + ``` + +1. Start the push gateway. You can deploy the push gateway using the Docker image: + + ```bash + docker pull prom/pushgateway + docker run -d -p 9091:9091 prom/pushgateway + ``` + +1. Start Besu specifying the `--metrics-push-enabled` option and port of the push gateway: + + + + # Syntax + + ```bash + besu --network=dev --miner-enabled --miner-coinbase --rpc-http-cors-origins="all" --rpc-http-enabled --metrics-push-enabled --metrics-push-port=9091 --metrics-push-host=127.0.0.1 + ``` + + # Example + + ```bash + besu --network=dev --miner-enabled --miner-coinbase fe3b557e8fb62b89f4916b721be55ceb828dbd73 --rpc-http-cors-origins="all" --rpc-http-enabled --metrics-push-enabled --metrics-push-port=9091 --metrics-push-host=127.0.0.1 + ``` + + + +1. In another terminal, run Prometheus specifying the `prometheus.yml` file: + + ```bash + prometheus --config.file=prometheus.yml + ``` + +1. View the [Prometheus graphical interface](#view-prometheus-graphical-interface). + +## View Prometheus graphical interface + +1. Open a Web browser to [`http://localhost:9090`](http://localhost:9090) to view the Prometheus graphical interface. + +1. Choose **Graph** from the menu bar and click the **Console** tab below. + +1. From the **Insert metric at cursor** drop-down, select a [metric](#metrics-list) such as `besu_blockchain_difficulty_total` or `ethereum_blockchain_height` and click **Execute**. The values display. + +1. Click the **Graph** tab to view the data as a time-based graph. The query string displays below the graph. For example, `{ethereum_blockchain_height{instance="localhost:9545",job="prometheus"}`. + +## Metrics list + +The following table lists available metrics. Each metric starts with a metric category prefix. Metrics specific to Besu use the `besu_` prefix, followed by another metric category. Metric categories can be enabled using the [`metrics-category`](../../reference/cli/options.md#metrics-category) command line option. If a metric has a JSON-RPC equivalent, it is included in the definition column. + +| Name | Metric type | Definition | +| --- | --- | --- | +| `besu_blockchain_chain_head_gas_limit` | Gauge | Block gas limit of the current chain head block | +| `besu_blockchain_chain_head_gas_used` | Gauge | Gas used by the current chain head block | +| `besu_blockchain_chain_head_ommer_count` | Gauge | Number of uncles in the current chain head block (JSON-RPC equivalent: [`eth_getUncleCountByBlockHash`](../../reference/api/index.md#eth_getunclecountbyblockhash) or [`eth_getUncleCountByBlockNumber`](../../reference/api/index.md#eth_getunclecountbyblocknumber)) | +| `besu_blockchain_chain_head_timestamp` | Gauge | Timestamp from the current chain head | +| `besu_blockchain_chain_head_transaction_count` | Gauge | Number of transactions in the current chain head block (JSON-RPC equivalent: [`eth_getBlockTransactionCountByHash`](../../reference/api/index.md#eth_getblocktransactioncountbyhash) or [`eth_getBlockTransactionCountByNumber`](../../reference/api/index.md#eth_getblocktransactioncountbynumber)) | +| `besu_blockchain_difficulty_total` | Gauge | Difficulty of the chain head (JSON-RPC equivalent: `difficulty` of [`admin_peers`](../../reference/api/index.md#admin_peers)) | +| `besu_executors_ethscheduler_computation_active_threads_current` | Gauge | Current number of threads executing computation tasks | +| `besu_executors_ethscheduler_computation_completed_tasks_total` | Gauge | Total number of computation tasks executed | +| `besu_executors_ethscheduler_computation_pool_size_current` | Gauge | Current number of threads in the computation thread pool | +| `besu_executors_ethscheduler_computation_queue_length_current` | Gauge | Current number of computation tasks awaiting execution | +| `besu_executors_ethscheduler_computation_rejected_tasks_total` | Counter | Total number of tasks rejected by this computation executor | +| `besu_executors_ethscheduler_computation_submitted_tasks_total` | Gauge | Total number of computation tasks submitted | +| `besu_executors_ethscheduler_timer_active_threads_current` | Gauge | Current number of threads executing timer tasks | +| `besu_executors_ethscheduler_timer_completed_tasks_total` | Gauge | Total number of timer tasks executed | +| `besu_executors_ethscheduler_timer_pool_size_current` | Gauge | Current number of threads in the timer thread pool | +| `besu_executors_ethscheduler_timer_queue_length_current` | Gauge | Current number of timer tasks awaiting execution | +| `besu_executors_ethscheduler_timer_rejected_tasks_total` | Counter | Total number of tasks rejected by this timer executor | +| `besu_executors_ethscheduler_timer_submitted_tasks_total` | Gauge | Total number of timer tasks submitted | +| `besu_executors_ethscheduler_workers_active_threads_current` | Gauge | Current number of threads executing worker tasks | +| `besu_executors_ethscheduler_workers_completed_tasks_total` | Gauge | Total number of worker tasks executed | +| `besu_executors_ethscheduler_workers_pool_size_current` | Gauge | Current number of threads in the worker thread pool | +| `besu_executors_ethscheduler_workers_queue_length_current` | Gauge | Current number of worker tasks awaiting execution | +| `besu_executors_ethscheduler_workers_rejected_tasks_total` | Counter | Total number of tasks rejected by this worker executor | +| `besu_executors_ethscheduler_workers_submitted_tasks_total` | Gauge | Total number of worker tasks submitted | +| `besu_network_discovery_inflight_interactions_current` | Gauge | Current number of inflight discovery interactions | +| `besu_network_discovery_interaction_count` | Counter | Total number of discovery interactions initiated | +| `besu_network_discovery_interaction_retry_count` | Counter | Total number of interaction retries performed | +| `besu_network_discovery_messages_inbound` | Counter | Total number of P2P discovery messages received | +| `besu_network_discovery_messages_outbound` | Counter | Total number of P2P discovery messages sent | +| `besu_network_netty_boss_pending_tasks` | Gauge | Number of pending tasks in Netty boss event loop | +| `besu_network_netty_workers_pending_tasks` | Gauge | Number of pending tasks in Netty workers event loop | +| `besu_network_p2p_messages_inbound` | Counter | Total number of P2P messages received | +| `besu_network_vertx_eventloop_pending_tasks` | Gauge | Number of pending tasks in Vertx event loop | +| `besu_network_vertx_worker_pool_completed_total` | Counter | Total number of tasks completed by Vertx worker pool | +| `besu_network_vertx_worker_pool_rejected_total` | Counter | Total number of tasks rejected by Vertx worker pool | +| `besu_network_vertx_worker_pool_submitted_total` | Counter | Total number of tasks submitted to Vertx worker pool | +| `besu_peers_connected_total` | Counter | Total number of peers connected | +| `besu_peers_disconnected_total` | Counter | Total number of peers disconnected | +| `besu_peers_pending_peer_requests_current` | Gauge | Current number of peer requests pending because peers are busy | +| `besu_pruner_mark_time_duration` | Gauge | Cumulative number of seconds spent marking the state trie across all pruning cycles | +| `besu_pruner_mark_operations_total` | Counter | Total number of mark operations performed | +| `besu_pruner_marked_nodes_total` | Counter | Total number of nodes marked as in use | +| `besu_pruner_sweep_operations_total` | Counter | Total number of sweep operations performed | +| `besu_pruner_swept_nodes_total` | Counter | Total number of unused nodes removed | +| `besu_stratum_connections` | Counter | Number of connections over time | +| `besu_stratum_difficulty` | Gauge | Current mining difficulty | +| `besu_stratum_disconnections` | Counter | Number of disconnections over time | +| `besu_stratum_miners` | Gauge | Number of connected miners | +| `besu_synchronizer_chain_download_pipeline_processed_total` | Counter | Number of entries processed by each chain download pipeline stage | +| `besu_synchronizer_chain_download_pipeline_restarts` | Counter | Number of times chain download pipeline has been restarted | +| `besu_synchronizer_fast_sync_pivot_block_current` | Gauge | The current fast sync pivot block | +| `besu_synchronizer_fast_sync_pivot_block_selected_count` | Counter | Number of times a fast sync pivot block has been selected | +| `besu_synchronizer_fast_sync_validation_mode` | Counter | Number of blocks validated using light vs full validation during fast sync | +| `besu_synchronizer_in_sync` | Gauge | Whether or not the local node has caught up to the best known peer (1 or 0) | +| `besu_synchronizer_task` | Summary | Internal processing tasks | +| `besu_synchronizer_world_state_completed_requests_total` | Counter | Total number of node data requests completed as part of fast sync world state download | +| `besu_synchronizer_world_state_existing_nodes_total` | Counter | Total number of node data requests completed using existing data | +| `besu_synchronizer_world_state_inflight_requests_current` | Gauge | Number of in progress requests for world state data | +| `besu_synchronizer_world_state_node_requests_since_last_progress_current` | Gauge | Number of world state requests made since the last time new data was returned | +| `besu_synchronizer_world_state_pending_requests_cache_size` | Gauge | Pending request cache size for fast sync world state download | +| `besu_synchronizer_world_state_pending_requests_current` | Gauge | Number of pending requests for fast sync world state download | +| `besu_synchronizer_world_state_pipeline_processed_total` | Counter | Number of entries processed by each world state download pipeline stage | +| `besu_synchronizer_world_state_retried_requests_total` | Counter | Total number of node data requests repeated as part of fast sync world state download | +| `besu_transaction_pool_pending_transactions_messages_skipped_total` | Counter | Total number of pending transactions messages skipped by the processor | +| `besu_transaction_pool_transactions` | Gauge | Current size of the transaction pool (JSON-RPC equivalent: result number of [`txpool_besuTransactions`](../../reference/api/index.md#txpool_besutransactions)) | +| `besu_transaction_pool_transactions_added_total` | Counter | Count of transactions added to the transaction pool | +| `besu_transaction_pool_transactions_messages_skipped_total` | Counter | Total number of transactions messages skipped by the processor. | +| `ethereum_best_known_block_number` | Gauge | Estimated highest block available (JSON-RPC equivalent: `highestBlock` of [`eth_syncing`](../../reference/api/index.md#eth_syncing), or [`eth_blockNumber`](../../reference/api/index.md#eth_blocknumber) if not syncing) | +| `ethereum_blockchain_height` | Gauge | Current height of the canonical chain (JSON-RPC equivalent: [`eth_blockNumber`](../../reference/api/index.md#eth_blocknumber)) | +| `ethereum_peer_count` | Gauge | Current number of peers connected (JSON-RPC equivalent: [`net_peerCount`](../../reference/api/index.md#net_peercount)) | +| `ethereum_peer_limit` | Gauge | Maximum number of peers this node allows to connect | +| `jvm_buffer_pool_capacity_bytes` | Gauge | Bytes capacity of a given JVM buffer pool | +| `jvm_buffer_pool_used_buffers` | Gauge | Used buffers of a given JVM buffer pool | +| `jvm_buffer_pool_used_bytes` | Gauge | Used bytes of a given JVM buffer pool | +| `jvm_classes_loaded` | Gauge | Current number of classes loaded in the JVM | +| `jvm_classes_loaded_total` | Counter | Total number of classes loaded since the JVM started execution | +| `jvm_classes_unloaded_total` | Counter | Total number of classes unloaded since the JVM started execution | +| `jvm_gc_collection_seconds` | Summary | Seconds spent in a given JVM garbage collector | +| `jvm_memory_bytes_committed` | Gauge | Committed bytes of a given JVM memory area | +| `jvm_memory_bytes_init` | Gauge | Initial bytes of a given JVM memory area | +| `jvm_memory_bytes_max` | Gauge | Maximum bytes of a given JVM memory area | +| `jvm_memory_bytes_used` | Gauge | Used bytes of a given JVM memory area | +| `jvm_memory_pool_bytes_committed` | Gauge | Committed bytes of a given JVM memory pool | +| `jvm_memory_pool_bytes_init` | Gauge | Initial bytes of a given JVM memory pool | +| `jvm_memory_pool_bytes_max` | Gauge | Maximum bytes of a given JVM memory pool | +| `jvm_memory_pool_bytes_used` | Gauge | Used bytes of a given JVM memory pool | +| `jvm_threads_current` | Gauge | Current thread count of a JVM | +| `jvm_threads_daemon` | Gauge | Daemon thread count of a JVM | +| `jvm_threads_deadlocked` | Gauge | Cycles of JVM threads in deadlock waiting to acquire object monitors or ownable synchronizers | +| `jvm_threads_deadlocked_monitor` | Gauge | Cycles of JVM threads in deadlock waiting to acquire object monitors | +| `jvm_threads_peak` | Gauge | Peak thread count of a JVM | +| `jvm_threads_started_total` | Counter | Started thread count of a JVM | +| `jvm_threads_state` | Gauge | Current count of threads by state | +| `process_cpu_seconds_total` | Counter | Total user and system CPU time spent in seconds | +| `process_max_fds` | Gauge | Maximum number of open file descriptors | +| `process_open_fds` | Gauge | Number of open file descriptors | +| `process_start_time_seconds` | Gauge | Start time of the process since Unix epoch in seconds | + +:::info + +- The `ethereum_best_known_block_number` metric always has a value. When the [`eth_syncing` JSON-RPC method](../../reference/api/index.md#eth_syncing) returns false, the current chain height displays. +- Although the `ethereum_peer_limit` metric does not have a JSON-RPC equivalent, the [`max peers` command line option](../../reference/cli/options.md#max-peers) sets the maximum number of P2P connections that can be established. + +::: + + + +[monitoring with Prometheus and Grafana configured]: ../../../private-networks/tutorials/quickstart.md#monitor-nodes-with-prometheus-and-grafana diff --git a/versioned_docs/version-23.10.1/public-networks/how-to/monitor/understand-metrics.md b/versioned_docs/version-23.10.1/public-networks/how-to/monitor/understand-metrics.md new file mode 100644 index 00000000000..863798555be --- /dev/null +++ b/versioned_docs/version-23.10.1/public-networks/how-to/monitor/understand-metrics.md @@ -0,0 +1,101 @@ +--- +title: Understand metrics +sidebar_position: 2 +description: Understand Besu performance metrics +tags: + - public networks +--- + +# Understand metrics + +When running Besu on Ethereum Mainnet using [snap sync](../../get-started/connect/sync-node.md#snap-synchronization), you might notice graphical patterns that stand out in different metrics charts. These patterns are related to the [CPU usage](#cpu-usage) and [block time](#block-time) of the Besu sync process. + +## CPU usage + +The following screenshot from [monitoring Besu with Prometheus and Grafana] shows patterns related to CPU usage. + +![CPU Grafana Besu dashboard patterns screenshot](../../../assets/images/besu-cpu-pattern-during-sync.png) + +The CPU pattern is a "staircase" pattern, where each step represents one of the Besu running stages. + +### 1. Blocks import and world state download + +Step 1 highlights blocks import and world state download, two tasks executed in parallel in Besu. Besu manages these two tasks with two different pipelines. + +This step is CPU-bound.[^1] The two pipeline stages run on multiple threads. + +As displayed in the following screenshot (for a VM with 8 CPUs) the CPU load average is about 7.5 and sometimes exceeds 10 (a 100% load for the 8 CPUs is 8). This means there's more work to be done than what the CPUs can handle. + +![System load metrics screenshot](../../../assets/images/system-load.png) + +### 2. World state healing + +Step 2, world state healing, starts just after the world state download in step 1 is complete. The peak in system CPU is related to the high rate of input and output (IO) required during this step. IO usage is around 61% during healing, and it's only 39% during the remaining sync. + +![IO utilization metrics screenshot](../../../assets/images/io-utilization.png) + +### 3. Blocks import + +After steps 1 and 2, world state is downloaded and healed, and block import continues. + +The visible drop in CPU shows that Besu finished the world state nodes download. + +The block import step is long because Besu can't parallelize block import -- it must validate each parent block before importing a child. + +:::note + +The Besu team is currently working on other algorithm and implementations to make this block import faster. + +::: + +### 4. Blocks full import + +In step 4, Besu executes all transactions of each block. This is when Besu updates the world state after the healing step. + +The quantity of imported blocks in this step depends on the speed of the sync. This number indicates the cumulated blocks quantity behind head since the last healing step. + +This step consumes less CPU than the previous steps because the sequential part -- executing transactions on the EVM -- must be single-threaded, reducing the concurrent work at the CPU level. + +### 5. Blocks production and propagation + +Once Besu is completely synced, it propagates blocks and executes the transactions inside each block. Step 5, block production and propagation, shows a reduction in CPU consumption due to the idle time while waiting for the new block and the sequential nature of executing transactions on the EVM. + +## Block time + +Block time measures the duration of getting new blocks in Besu. Block time is closely related to [CPU usage](#cpu-usage). + +The following screenshot shows patterns related to block time as available in the [Besu Grafana full dashboard](https://grafana.com/grafana/dashboards/16455-besu-full/). + +![Block time Grafana Besu dashboard patterns screenshot](../../../assets/images/block-time.png) + +The block time pattern is also a "staircase" pattern. + +### 1. Block import time + +Step 1, block import time, is the duration of importing a block. + +Import includes: + +- Data retrieval over the network. +- Headers, body, and receipt validation. +- Persisting the block in the database. + +Block import takes between a few and tens of milliseconds. + +### 2. Block full import time + +Step 2, block full import time, is the duration of importing a block (step 1) and executing all its transactions. + +Block full import takes between 1 and 2 seconds per block, depending on the number and complexity of the transactions. + +### 3. Block network time + +Step 3, block network time, is the duration of propagating a block over the network and executing all its transactions. + +Block network takes between 13 and 16 seconds. + + + +[monitoring Besu with Prometheus and Grafana]: ../../../private-networks/tutorials/quickstart.md#monitor-nodes-with-prometheus-and-grafana + +[^1]: A CPU-bound task means that the time required to execute the task is determined only by the CPU speed. diff --git a/versioned_docs/version-23.10.1/public-networks/how-to/send-transactions.md b/versioned_docs/version-23.10.1/public-networks/how-to/send-transactions.md new file mode 100644 index 00000000000..56d74607621 --- /dev/null +++ b/versioned_docs/version-23.10.1/public-networks/how-to/send-transactions.md @@ -0,0 +1,65 @@ +--- +title: Create and send transactions +sidebar_position: 4 +description: Send transactions using eth_call or eth_sendRawTransaction. +tags: + - public networks +--- + +# Create and send transactions + +You can send signed transactions using the [`eth_sendRawTransaction`](../reference/api/index.md#eth_sendrawtransaction) JSON-RPC API method. + +Signed transactions can be simple value transfers, contract creation, or contract invocation. Set the maximum transaction fee for transactions using the [`--rpc-tx-feecap`](../reference/cli/options.md#rpc-tx-feecap) CLI option. + +To accept signed transactions from remote connections, set the [API listening host](use-besu-api/index.md#service-hosts) to `0.0.0.0`. + +[Use client libraries](develop/client-libraries.md) to create and send a signed raw transaction to transfer Ether and create a smart contract. + +:::danger Private keys + +Don't use the accounts from the examples on Mainnet or any public network except for testing. The private keys are displayed which means the accounts are not secure. + +All accounts and private keys in the examples are from the `dev.json` genesis file in the [`/besu/config/src/main/resources`](https://github.com/hyperledger/besu/tree/master/config/src/main/resources) directory. + +In production environments avoid exposing your private keys by creating signed transactions offline, or use [EthSigner](https://docs.ethsigner.consensys.net/) to isolate your private keys and sign transactions with [`eth_sendTransaction`](https://docs.ethsigner.consensys.net/Reference/API-Methods#eth_sendtransaction). + +::: + +:::caution + +Setting the [listening host](use-besu-api/index.md#service-hosts) to `0.0.0.0` exposes the API service connection on your node to any remote connection. In a production environment, ensure you are using a firewall to avoid exposing your node to the internet. + +::: + +:::tip + +Libraries such as [web3j](https://github.com/web3j/web3j) or [ethereumj](https://github.com/ethereum/ethereumj) and tools such as [MyCrypto](https://mycrypto.com/) can also create signed transactions. + +::: + +## `eth_call` vs `eth_sendRawTransaction` + +You can interact with contracts using [`eth_call`](../reference/api/index.md#eth_call) or [`eth_sendRawTransaction`](../reference/api/index.md#eth_sendrawtransaction). The table below compares the characteristics of both calls. + +| `eth_call` | `eth_sendRawTransaction` | +| --- | --- | +| Read-only | Write | +| Invokes contract function locally | Broadcasts to the network | +| Does not change state of blockchain | Updates the blockchain (for example, transfers ether between accounts) | +| Does not consume gas | Requires gas | +| Synchronous | Asynchronous | +| Returns the value of a contract function available immediately | Returns transaction hash only. A block might not include all possible transactions (for example, if the gas price is too low). | + +## Use wallets for key management + +Besu doesn't support key management inside the client. Use: + +- [EthSigner](http://docs.ethsigner.consensys.net/en/latest/) with Besu to provide access to your key store and sign transactions. +- Third-party tools (for example, [MetaMask](https://metamask.io/) and [web3j](https://web3j.io/)) for creating accounts. + +:::tip + +[EthSigner](http://docs.ethsigner.consensys.net/en/latest/) implements [`eth_sendTransaction`](https://docs.ethsigner.consensys.net/Reference/API-Methods#eth_sendtransaction) and [`eea_sendTransaction`](https://docs.ethsigner.consensys.net/Reference/API-Methods#eea_sendtransaction). + +::: diff --git a/versioned_docs/version-23.10.1/public-networks/how-to/troubleshoot/_category_.json b/versioned_docs/version-23.10.1/public-networks/how-to/troubleshoot/_category_.json new file mode 100644 index 00000000000..cf5f9653813 --- /dev/null +++ b/versioned_docs/version-23.10.1/public-networks/how-to/troubleshoot/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Troubleshoot", + "position": 12 +} diff --git a/versioned_docs/version-23.10.1/public-networks/how-to/troubleshoot/evm-tool.md b/versioned_docs/version-23.10.1/public-networks/how-to/troubleshoot/evm-tool.md new file mode 100644 index 00000000000..7e5a044180a --- /dev/null +++ b/versioned_docs/version-23.10.1/public-networks/how-to/troubleshoot/evm-tool.md @@ -0,0 +1,74 @@ +--- +title: Use EVM tool +sidebar_position: 1 +description: Hyperledger Besu EVM tool +tags: + - public networks + - private networks +--- + +# Use the EVM tool + +The Besu EVM tool is a CLI program that executes arbitrary EVM programs and Ethereum State Tests outside the context of an operating node. Use the EVM tool for benchmarking and fuzz testing. + +## Get the EVM tool + +The Besu EVM tool does not have a standard zip file distribution. To use, you need to either build from the source repository or use a pre-published docker image. + +### Build from source + +To build from source, run the following from the root of the Besu repository: + +```bash +./gradlew :ethereum:evmTool:installDist +``` + +An extractable archive files is created in `ethereum/evmtool/build/distributions` and an executable installation in `ethereum/evmtool/build/install/evmtool`. + +Execute the EVM tool: + +```bash +ethereum/evmtool/build/install/evmtool/bin/evm +``` + +### Execute with Docker + +To run the Besu EVM tool in a container: + +```bash +docker run -rm hyperledger/besu-evmtool:develop +``` + +- Because no data is stored in local directories we recommended using the `-rm` docker option. The `-rm` option deletes the container at the end of execution. +- If you use an option that requires input from standard in, use the `-i` docker option. The `-i` option pipes standard input to the EVM tool. +- If you need to reference files we recommend using a docker file binding, such as `-v ${PWD}:/opt/data`, which maps the current directory to the `/opt/data` directory in the container. + +:::note + +The `latest` tag is the latest released version of Besu, starting with 1.5.3. The `develop` tag is the current main branch code that will go into a future release version of Besu. + +::: + +## EVM tool run options + +The first mode of the EVM tool runs an arbitrary EVM and is invoked without an extra command. [Command line options](../../reference/evm-tool.md) specify the code and other contextual information. + +The EVM tool also has a [`state-test` subcommand](../../reference/evm-tool.md#state-test-options) that allows [Ethereum state tests](https://github.com/ethereum/tests/tree/develop/GeneralStateTests) to be evaluated, and a [`code-validate` subcommand](../../reference/evm-tool.md#eof-code-validation) that allows [Ethereum object formatted (EOF)](https://eips.ethereum.org/EIPS/eip-3540) code to be validated. Most of the options from EVM execution don't apply. + + + +# `state-test` + +```bash +evm state-test --nomemory +``` + +# `code-validate` + +```bash +evm code-validate --file +``` + + + +The [EVM tool reference](../../reference/evm-tool.md) provides more information on these modes. diff --git a/versioned_docs/version-23.10.1/public-networks/how-to/troubleshoot/peering.md b/versioned_docs/version-23.10.1/public-networks/how-to/troubleshoot/peering.md new file mode 100644 index 00000000000..e248665fe37 --- /dev/null +++ b/versioned_docs/version-23.10.1/public-networks/how-to/troubleshoot/peering.md @@ -0,0 +1,69 @@ +--- +title: Troubleshoot peering +sidebar_position: 4 +description: How to troubleshoot peering +tags: + - public networks +--- + +# Troubleshoot peering + +Many factors can affect the ability of your node to find and maintain peers. Your network router, machine environment, and node configuration are all important. If you have peering issues, start by [configuring your ports](../connect/configure-ports.md) and [managing peers](../connect/manage-peers.md). + +## Peering FAQ + +### "Why can’t I find enough peers to sync?" + +One or more of the following may be the cause: + +- Your hardware doesn't have enough CPU, disk IOPS, or bandwidth to handle all the peers. +- Your ports aren't open in your firewall and/or router. +- Your node is sending large numbers of DNS requests. See [issue #4375](https://github.com/hyperledger/besu/issues/4375). +- You're using [checkpoint sync](../../get-started/connect/sync-node.md#checkpoint-synchronization), which doesn't download all historical block data, so your peers may disconnect you when fetching those blocks. +- Your node is experiencing the normal behavior of peers connecting and disconnecting. This is especially normal soon after you start your node. + +You can try the following to find more peers: + +- Set [`p2p-host`](../../reference/cli/options.md#p2p-host) to your external IP address to allow inbound connections. +- Restart Besu. This can take a while to build up again. +- Set `-Xdns-enabled` to `true` (only for private networks). +- Set `-Xp2p-peer-lower-bound` to a minimum number of peers. +- Delete the node key (which is autogenerated in your data directory). There are two reasons that this might help find more peers: + 1. Your node (identified by the address associated with this key) has been put onto other peers' bad peer lists for some reason. + 2. Peer discovery is influenced by the value of the node key. This is related to the node "distance" in the [discovery algorithm](https://github.com/ethereum/devp2p/wiki/Discovery-Overview#kademlia). + +You can read the [Prysm EL and CL peering documentation](https://docs.prylabs.network/docs/prysm-usage/p2p-host-ip) for more information. + +### "What network or router/modem settings should I check?" + +Check the following settings: + +- Your machine and router's specified DNS should support TCP. You can check your DNS online for TCP support. Google and Cloudflare, 8.8.8.8 and 1.1.1.1, support TCP over port 853. Other DNS might as well. +- The appropriate ports should be open on your router, or your router should have UPNP enabled. See the next FAQ for more information on router settings. +- If you use [Docker](https://docs.docker.com/network/network-tutorial-host/) or virtualization, the container should be able to create outbound connections on the host machine. + +### "How do I open/forward my ports?" + +If you’re behind NAT, you probably need to set up port forwarding in your router. You might also need to configure your firewall. Forward and open `30303` (if using the default p2p port) for both UDP and TCP. If your router supports UPNP, you can set [`--nat-method`](../../reference/cli/options.md#nat-method) to [`UPNPP2PONLY`](../connect/specify-nat.md#upnp). + +### "How do I test that my ports are open?" + +You can use this [open port checker](https://www.yougetsignal.com/tools/open-ports/). + +### "What's the ideal number of peers for Besu?" + +The default maximum is 25. Increasing the number of peers increases the bandwidth, CPU, and disk access Besu uses to respond to peers. Hardware with low specifications might result in low peer numbers. You'll experience diminishing returns with a larger number of peers (>100). + +### "What's the benefit of increasing the number of peers?" + +Increasing the number of max peers won't speed up Besu syncing, because the bottleneck during sync is disk IO and CPU. + +Note that Besu's peers are only used for the initial sync and transaction gossip, neither of which affects attestation performance. The beacon node connectivity controls how quickly you receive blocks and how attestations are published. Increasing Besu's peer count increases the load on your node, which may hurt attestations. + +## Metrics + +Capture [metrics](../monitor/index.md) to gain insights into peering behavior over time. + +To [enable Prometheus to access Besu](../monitor/metrics.md), open the metrics port or metrics push port to Prometheus or the Prometheus push gateway on TCP. + +Specify the ports for Prometheus and Prometheus push gateway using the [`--metrics-port`](../../reference/cli/options.md#metrics-port) and [`--metrics-push-port`](../../reference/cli/options.md#metrics-push-port) options. The defaults are `9545` and `9001`. diff --git a/versioned_docs/version-23.10.1/public-networks/how-to/troubleshoot/performance.md b/versioned_docs/version-23.10.1/public-networks/how-to/troubleshoot/performance.md new file mode 100644 index 00000000000..545cfb80856 --- /dev/null +++ b/versioned_docs/version-23.10.1/public-networks/how-to/troubleshoot/performance.md @@ -0,0 +1,45 @@ +--- +description: Troubleshoot poor performance and resource constraints. +sidebar_label: Troubleshoot performance +sidebar_position: 3 +tags: + - public networks +--- + +# Troubleshoot poor performance and resource constraints + +Your hardware, machine environment, and node configuration can affect your node's ability to serve +requests and perform [validator duties](../../concepts/proof-of-stake/index.md), including +[attestation performance](../../concepts/proof-of-stake/attestations.md). + +If you notice high resource usage when [monitoring your node](../monitor/index.md), you can +try the following suggestions: + +* Disable swapping. + Besu is an I/O intensive application, especially during sync, enabling swapping hurts Besu's performance. + You can disable swap at the OS level. + [This article](https://www.tecmint.com/disable-swap-partition/) provides information on how to + disable swap (and caveats). +* Use a high performance SSD disk with NVMe, since Besu's performance bottleneck is often slow disk I/O. +* Configure memory and RAM: + * If you have RAM constraints, use [OpenJ9](../../get-started/system-requirements.md) if you're + running on `x86_64` Linux architecture to reduce memory usage. + * Review and change your [Java heap size](../configure-jvm/manage-memory.md) if necessary. + 5GB is an appropriate limit. + Higher values may improve sync time, but can be reduced after completing sync. + * Ensure Besu is using [jemalloc](../../get-started/install/binary-distribution.md). + * If you have 32GB RAM or more, set the `Xplugin-rocksdb-high-spec-enabled` configuration option + to `true`. + Don't use this on RAM machines with 16GB RAM or less if you're running a consensus client on the + same hardware. +* If you're running on ARM64, make sure the glibc version is greater than 2.29. + If not, Besu uses a Java implementation instead of the native one for some precompiled contracts, + which results in lower performance. + * On Ubuntu, run `ldd --version`. + See [the methods for other environments](https://dev.to/0xbf/how-to-get-glibc-version-c-lang-26he). +* Pay attention to what processes are running on the same machine/VM as Besu. + Java applications, with default settings, are designed to run alone on the machine. + You can run your consensus client on the same machine, but this adds overhead on Besu, and vice + versa (on CPU cache misses, CPU scheduler latency, IO, etc.). + +You should continue to monitor your node after following these suggestions. diff --git a/versioned_docs/version-23.10.1/public-networks/how-to/troubleshoot/trace-transactions.md b/versioned_docs/version-23.10.1/public-networks/how-to/troubleshoot/trace-transactions.md new file mode 100644 index 00000000000..773b0d9fa05 --- /dev/null +++ b/versioned_docs/version-23.10.1/public-networks/how-to/troubleshoot/trace-transactions.md @@ -0,0 +1,40 @@ +--- +title: Trace transactions +sidebar_position: 2 +description: How to trace transactions +tags: + - public networks + - private networks +--- + +# Trace transactions + +To get detailed information about transaction processing, use the [`TRACE` API](../../reference/api/index.md#trace-methods). Enable the `TRACE` API using the [`--rpc-http-api`](../../reference/cli/options.md#rpc-http-api) or [`--rpc-ws-api`](../../reference/cli/options.md#rpc-ws-api) command line options. + +The `TRACE` API has two sets of trace calls, [ad-hoc tracing APIs](#ad-hoc-tracing-apis) and [transaction-trace filtering APIs](#transaction-trace-filtering-apis). + +## Ad-hoc tracing APIs + +These APIs allow you to use the [`trace`, `vmTrace`, or `stateDiff`](../../reference/trace-types.md) diagnostic options when tracing calls or transactions. + +To use the ad-hoc tracing APIs, the requested block or transaction must be within the number of [blocks retained](../../reference/cli/options.md#pruning-blocks-retained) with [pruning enabled](../../reference/cli/options.md#pruning-enabled) (by default, 1024). + +The ad-hoc tracing APIs are: + +- [`trace_call`](../../reference/api/index.md#trace_call) +- [`trace_callMany`](../../reference/api/index.md#trace_callmany) +- [`trace_rawTransaction`](../../reference/api/index.md#trace_rawtransaction) +- [`trace_replayBlockTransactions`](../../reference/api/index.md#trace_replayblocktransactions) + +## Transaction-trace filtering APIs + +These APIs allow you to filter and search by specific information such as the block, address, or transaction. These APIs only use the [`trace` type](../../reference/trace-types.md#trace). + +To use the transaction-trace filtering APIs, your node must be an archive node (that is, synchronized without pruning or fast sync) or the requested block or transaction must be within the number of [blocks retained](../../reference/cli/options.md#pruning-blocks-retained) with [pruning enabled](../../reference/cli/options.md#pruning-enabled) (by default, 1024). + +The transaction-trace filtering APIs are: + +- [`trace_block`](../../reference/api/index.md#trace_block) +- [`trace_filter`](../../reference/api/index.md#trace_filter) +- [`trace_get`](../../reference/api/index.md#trace_get) +- [`trace_transaction`](../../reference/api/index.md#trace_transaction) diff --git a/versioned_docs/version-23.10.1/public-networks/how-to/upgrade-node.md b/versioned_docs/version-23.10.1/public-networks/how-to/upgrade-node.md new file mode 100644 index 00000000000..4e33d3dce08 --- /dev/null +++ b/versioned_docs/version-23.10.1/public-networks/how-to/upgrade-node.md @@ -0,0 +1,33 @@ +--- +title: Upgrade Besu +sidebar_position: 11 +description: Upgrade your Besu node to a new version. +tags: + - public networks +--- + +# Upgrade your Besu node + +When upgrading your Besu node, we recommend: + +- Using an orchestration method (for example, Ansible or Chef) to keep all nodes in sync with your desired configuration. +- Storing your configuration under version control. + +## Ansible + +You can use the [Ansible role on Galaxy](https://galaxy.ansible.com/consensys/hyperledger_besu) directly or customize it to suit your needs. + +Upgrade the Besu version on nodes by running the play with the new version. For more information, For more information, select **Read Me** on the [Ansible Galaxy Besu page](https://galaxy.ansible.com/consensys/hyperledger_besu). + +The playbook: + +1. Stops Besu. +1. Downloads the updated version. +1. Applies any new configuration. +1. Starts Besu. + +## Find peers on restarting + +Nodes store known peers in the peer table. The peer table is not persisted to disk. When a node restarts, the node connects to the specified bootnodes and discovers other nodes through the peer discovery process. The node continues collecting data from where it left off before the restart (assuming there was no data corruption in a failure scenario). + +Before the node restarted, connected peers saved the node details in their peer tables. These peers can reconnect to the restarted node. The restarted node uses these peers and the bootnodes, to discover more peers. To ensure that the restarted node successfully rejoins the network, ensure you specify at least one operational bootnode. diff --git a/versioned_docs/version-23.10.1/public-networks/how-to/use-besu-api/_category_.json b/versioned_docs/version-23.10.1/public-networks/how-to/use-besu-api/_category_.json new file mode 100644 index 00000000000..300deff1cbe --- /dev/null +++ b/versioned_docs/version-23.10.1/public-networks/how-to/use-besu-api/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Use the Besu API", + "position": 1 +} diff --git a/versioned_docs/version-23.10.1/public-networks/how-to/use-besu-api/access-logs.md b/versioned_docs/version-23.10.1/public-networks/how-to/use-besu-api/access-logs.md new file mode 100644 index 00000000000..4f35a86ffd8 --- /dev/null +++ b/versioned_docs/version-23.10.1/public-networks/how-to/use-besu-api/access-logs.md @@ -0,0 +1,195 @@ +--- +title: Access logs using JSON-RPC +sidebar_position: 5 +description: Accessing logs using the Hyperledger Besu API +tags: + - public networks + - private networks +--- + +# Access logs using the Hyperledger Besu API + +Subscribe to events, such as logs, using either [RPC Pub/Sub over WebSockets](rpc-pubsub.md) or filters over HTTP. + +Access logs using the following Hyperledger Besu API methods: + +- [`eth_getFilterChanges`](../../reference/api/index.md#eth_getfilterchanges) +- [`eth_getFilterLogs`](../../reference/api/index.md#eth_getfilterlogs) +- [`eth_getLogs`](../../reference/api/index.md#eth_getlogs). + +Use [`eth_newFilter`](../../reference/api/index.md#eth_newfilter) to create the filter before using [`eth_getFilterChanges`](../../reference/api/index.md#eth_getfilterchanges) and [`eth_getFilterLogs`](../../reference/api/index.md#eth_getfilterlogs)). + +Access logs for [private contracts](../../../private-networks/concepts/privacy/index.md) using the equivalent [`priv_*` methods and specifying the privacy group ID](#filters-for-private-contracts). For example, [`priv_getLogs`](../../reference/api/index.md#priv_getlogs). + +:::note + +The following examples use the sample contract included in [events and logs](../../concepts/events-and-logs.md). + +::: + +## Create a filter + +Create a filter using [`eth_newFilter`](../../reference/api/index.md#eth_newfilter). + +If the [example contract](../../concepts/events-and-logs.md) was deployed to 0x42699a7612a82f1d9c36148af9c77354759b210b, the following request for `eth_newFilter` creates a filter to log when `valueIndexed` is set to 5: + +```json +{ + "jsonrpc": "2.0", + "method": "eth_newFilter", + "params": [ + { + "fromBlock": "earliest", + "toBlock": "latest", + "address": "0x42699a7612a82f1d9c36148af9c77354759b210b", + "topics": [ + ["0xd3610b1c54575b7f4f0dc03d210b8ac55624ae007679b7a928a4f25a709331a8"], + ["0x0000000000000000000000000000000000000000000000000000000000000005"] + ] + } + ], + "id": 1 +} +``` + +[`eth_newFilter`](../../reference/api/index.md#eth_newfilter) returns a filter ID hash (for example, `0x1ddf0c00989044e9b41cc0ae40272df3`). + +### Poll a filter for changes + +To poll the filter for changes since the last poll, use [`eth_getFilterChanges`](../../reference/api/index.md#eth_getfilterchanges) with the filter ID hash returned by [`eth_newFilter`](../../reference/api/index.md#eth_newfilter). + +If the contract had been executed twice since the last poll, with `valueIndexed` set to 1 and 5, [`eth_getFilterChanges`](../../reference/api/index.md#eth_getfilterchanges) returns only the log where the [topic](../../concepts/events-and-logs.md#event-parameters) for `valueIndexed` is 5: + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": [ + { + "logIndex": "0x0", + "removed": false, + "blockNumber": "0x21c", + "blockHash": "0xc7e6c9d5b9f522b2c9d2991546be0a8737e587beb6628c056f3c327a44b45132", + "transactionHash": "0xfd1a40f9fbf89c97b4545ec9db774c85e51dd8a3545f969418a22f9cb79417c5", + "transactionIndex": "0x0", + "address": "0x42699a7612a82f1d9c36148af9c77354759b210b", + "data": "0x0000000000000000000000000000000000000000000000000000000000000005", + "topics": [ + "0xd3610b1c54575b7f4f0dc03d210b8ac55624ae007679b7a928a4f25a709331a8", + "0x0000000000000000000000000000000000000000000000000000000000000005" + ] + } + ] +} +``` + +### Get all logs for a filter + +To get all logs for a filter, use [`eth_getFilterLogs`](../../reference/api/index.md#eth_getfilterlogs). + +If the contract had been executed twice with `valueIndexed` set to 5 since the filter was created using `eth_newFilter`, `eth_getFilterLogs` returns: + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": [ + { + "logIndex": "0x0", + "removed": false, + "blockNumber": "0x1a7", + "blockHash": "0x4edda22a242ddc7bc51e2b6b11e63cd67be1af7389470cdea9c869768ff75d42", + "transactionHash": "0x9535bf8830a72ca7d0020df0b547adc4d0ecc4321b7d5b5d6beb1eccee5c0afa", + "transactionIndex": "0x0", + "address": "0x42699a7612a82f1d9c36148af9c77354759b210b", + "data": "0x0000000000000000000000000000000000000000000000000000000000000005", + "topics": [ + "0xd3610b1c54575b7f4f0dc03d210b8ac55624ae007679b7a928a4f25a709331a8", + "0x0000000000000000000000000000000000000000000000000000000000000005" + ] + }, + { + "logIndex": "0x0", + "removed": false, + "blockNumber": "0x21c", + "blockHash": "0xc7e6c9d5b9f522b2c9d2991546be0a8737e587beb6628c056f3c327a44b45132", + "transactionHash": "0xfd1a40f9fbf89c97b4545ec9db774c85e51dd8a3545f969418a22f9cb79417c5", + "transactionIndex": "0x0", + "address": "0x42699a7612a82f1d9c36148af9c77354759b210b", + "data": "0x0000000000000000000000000000000000000000000000000000000000000005", + "topics": [ + "0xd3610b1c54575b7f4f0dc03d210b8ac55624ae007679b7a928a4f25a709331a8", + "0x0000000000000000000000000000000000000000000000000000000000000005" + ] + } + ] +} +``` + +:::tip + +You can use [`eth_getLogs`](#get-logs-using-a-filter-options-object) with a filter options object to get all logs matching the filter options instead of using [`eth_newFilter`](../../reference/api/index.md#eth_newfilter) followed by [`eth_getFilterLogs`](../../reference/api/index.md#eth_getfilterlogs). + +::: + +## Uninstall a filter + +When a filter is no longer required, use [`eth_uninstallFilter`](../../reference/api/index.md#eth_uninstallfilter) to remove the filter. + +## Filters for private contracts + +Filters for private contracts are created, accessed, and uninstalled using: + +- [`priv_getFilterChanges`](../../reference/api/index.md#priv_getfilterchanges) +- [`priv_getFilterLogs`](../../reference/api/index.md#priv_getfilterlogs) +- [`priv_getLogs`](../../reference/api/index.md#priv_getlogs) +- [`priv_newFilter`](../../reference/api/index.md#priv_newfilter) +- [`priv_uninstallFilter`](../../reference/api/index.md#priv_uninstallfilter). + +The [privacy group ID](../../../private-networks/concepts/privacy/index.md) must be specified as parameter 0 for the `priv` methods. + +```json +{ + "jsonrpc": "2.0", + "method": "priv_newFilter", + "params": [ + "4rFldHM792LeP/e2WPkTXZedjwKuTr/KwCFTt6mBbkI=", + { + "fromBlock": "earliest", + "toBlock": "latest", + "addresses": ["0x991cc548c154b2953cc48c02f782e1314097dfbb"], + "topics": [ + "0x85bea11d86cefb165374e0f727bacf21dc2f4ea816493981ecf72dcfb212a410" + ] + } + ], + "id": 1 +} +``` + +## Get logs using a filter options object + +To get all logs for a filter options object, use [`eth_getLogs`](../../reference/api/index.md#eth_getlogs) or [`priv_getLogs`](../../reference/api/index.md#priv_getlogs) for a private contract. + +The following request for `eth_getLogs` returns all the logs where the example contract has been deployed to `0x42699a7612a82f1d9c36148af9c77354759b210b` and executed with `valueIndexed` set to 5. + +```json +{ + "jsonrpc": "2.0", + "method": "eth_getLogs", + "params": [ + { + "fromBlock": "earliest", + "toBlock": "latest", + "address": "0x42699a7612a82f1d9c36148af9c77354759b210b", + "topics": [ + ["0xd3610b1c54575b7f4f0dc03d210b8ac55624ae007679b7a928a4f25a709331a8"], + ["0x0000000000000000000000000000000000000000000000000000000000000005"] + ] + } + ], + "id": 1 +} +``` + +The above example returns the same result as calling [eth_newFilter](#creating-a-filter) followed by [eth_getFilterLogs](#getting-all-logs-for-a-filter). diff --git a/versioned_docs/version-23.10.1/public-networks/how-to/use-besu-api/authenticate.md b/versioned_docs/version-23.10.1/public-networks/how-to/use-besu-api/authenticate.md new file mode 100644 index 00000000000..490203cd708 --- /dev/null +++ b/versioned_docs/version-23.10.1/public-networks/how-to/use-besu-api/authenticate.md @@ -0,0 +1,273 @@ +--- +title: Authenticate over JSON-RPC requests +sidebar_position: 4 +description: Hyperledger Besu authentication and authorization for JSON-RPC +tags: + - public networks + - private networks +--- + +# Authenticate and authorize JSON-RPC + +Authentication identifies a user, and authorization verifies user access to requested JSON-RPC methods. Hyperledger Besu verifies users using [JSON Web Tokens (JWT)](https://jwt.io/introduction/). JWT is also used in [multi-tenancy](../../../private-networks/concepts/privacy/multi-tenancy.md) to verify tenant data access. + +Besu supports two mutually exclusive authentication methods: + +- [Username and password](#username-and-password-authentication) +- [JWT public key](#jwt-public-key-authentication). + +Besu creates JWT internally with [username and password authentication](#username-and-password-authentication), and externally with [JWT public key authentication](#jwt-public-key-authentication). + +:::info + +Using JSON-RPC authentication and authorization with [MetaMask](https://metamask.io/) is not supported. + +::: + +:::caution + +To prevent interception of authentication credentials and authenticated tokens, make authenticated requests over HTTPS. We recommend running production deployments behind a network layer that provides SSL termination. Besu does not provide a HTTPS connection natively. + +::: + +## Username and password authentication + +Enable authentication from the command line. Supply the credentials file and send a request to the `/login` endpoint using the username and password. The `/login` endpoint creates a JWT for making permitted JSON-RPC requests. + +Using [public key authentication](#jwt-public-key-authentication) disables the `/login` endpoint. + +### 1. Create the credentials file + +The `toml` credentials file defines user details and the JSON-RPC methods they can access. + +:::info Sample `auth.toml` credentials file + +```toml +[Users.username1] +password = "$2a$10$l3GA7K8g6rJ/Yv.YFSygCuI9byngpEzxgWS9qEg5emYDZomQW7fGC" +permissions=["net:*","eth:blockNumber"] +privacyPublicKey="U7ANiOOd5L9Z/dMxRFjdbhA1Qragw6fLuYgmgCvLoX4=" + +[Users.username2] +password = "$2b$10$6sHt1J0MVUGIoNKvJiK33uaZzUwNmMmJlaVLkIwinkPiS1UBnAnF2" +permissions=["net:version","admin:*"] +privacyPublicKey="quhb1pQPGN1w8ZSZSyiIfncEAlVY/M/rauSyQ5wVMRE=" +``` + +::: + +Each user requiring JSON-RPC access the configuration file lists the: + +- Username. `Users.` is mandatory and followed by the username. That is, replace `` in `[Users.]` with the username. +- Hash of the user password. Use the [`password hash`](../../reference/cli/subcommands.md#password) subcommand to generate the hash. +- [JSON-RPC permissions](#json-rpc-permissions). +- Optional. The tenant's Tessera public key using `privacyPublicKey`. Only used for [multi-tenancy](../../../private-networks/concepts/privacy/multi-tenancy.md). + + + +# Command + +```bash +besu password hash --password=MyPassword +``` + +# Hash output + +```text +$2a$10$L3Xb5G/AJOsEK5SuOn9uzOhpCCfuVWTajc5hwWerY6N5xBM/xlrMK +``` + + + +### 2. Enable authentication + +To require authentication for the JSON-RPC API, use the [`--rpc-http-authentication-enabled`](../../reference/cli/options.md#rpc-http-authentication-enabled) or [`--rpc-ws-authentication-enabled`](../../reference/cli/options.md#rpc-ws-authentication-enabled) options. + +To specify the [credentials file](#1-create-the-credentials-file), use the [`--rpc-http-authentication-credentials-file`](../../reference/cli/options.md#rpc-http-authentication-credentials-file) and [`--rpc-ws-authentication-credentials-file`](../../reference/cli/options.md#rpc-ws-authentication-credentials-file) options. + +### 3. Generate an authentication token + +To generate an authentication token, make a request to the `/login` endpoint with your username and password. Specify the HTTP port or the WS port to generate a token to authenticate over HTTP or WS respectively. HTTP and WS requires a different token. + + + +# Generate a token for HTTP + +```bash +curl -X POST --data '{"username":"username1","password":"MyPassword"}' /login +``` + +# Example for HTTP + +```bash +curl -X POST --data '{"username":"username1","password":"MyPassword"}' http://localhost:8545/login +``` + +# Generate a token for WS + +```bash +curl -X POST --data '{"username":"username1","password":"MyPassword"}' /login +``` + +# Example for WS + +```bash +curl -X POST --data '{"username":"username1","password":"MyPassword"}' http://localhost:8546/login +``` + +# JSON result + +```json +{ + "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJwZXJtaXNzaW9ucyI6WyIqOioiXSwidXNlcm5hbWUiOiJ1c2VyMiIsImlhdCI6MTU1MDQ2MDYwNCwiZXhwIjoxNTUwNDYwOTA0fQ.l2Ycqzl_AyvReXBeUSayOlOMS_E8-DCuz3q0Db0DKD7mqyl6q-giWoEtfdWzUEvZbRRi2_ecKO3N6JkXq7zMKQAJbVAEzobfbaaXWcQEpHOjtnK4_Yz-UPyKiXtu7HGdcdl5Tfx3dKoksbqkBl3U3vFWxzmFnuu3dAISfVJYUNA" +} +``` + + + +Authentication tokens expire five minutes after generation. If you require access after the token expires, you need to generate a new token. + +## JWT public key authentication + +Enable authentication from the command line and supply the external JWT provider's public key. + +:::danger + +JWT public authentication disables the Besu `/login` endpoint, meaning [username and password authentication](#username-and-password-authentication) will not work. + +::: + +### 1. Generate a private and public key pair + +The private and accompanying public key files must be in `.pem` format. + +The [key algorithm](https://datatracker.ietf.org/doc/html/rfc7518#section-3.1) can be: + +- RSA with private key length of at least 2048 bits using algorithm `RS256`, `RS384` or `RS512`. +- ECDSA private key, using `ES256` (`secp256r1` or `secp256k1`), `ES384` or `ES512`. + +Besu default is `RS256`. + + + +# `RS256` RSA Keys + +1. Generate the private key: + + ```bash + openssl genrsa -out privateRSAKey.pem 2048 + ``` + +2. Generate the public key: + + ```bash + openssl rsa -pubout -in privateRSAKey.pem -pubout -out publicRSAKey.pem + ``` + +# `ES256` `secp256r1` ECDSA Keys + +1. Generate the private key: + + ```bash + openssl ecparam -name secp256r1 -genkey -out privateECDSAKey.pem + ``` + +2. Generate the public key: + + ```bash + openssl ec -in privateECDSAKey.pem -pubout -out publicECDSAKey.pem + ``` + + + +:::danger Private key security + +The private key must be kept secret. Never share private keys publicly or on a Web site, even if advertised as secure. + +Always keep your private keys safe -- ideally using [hardware](https://connect2id.com/products/nimbus-jose-jwt/examples/pkcs11) or [vault](https://www.vaultproject.io/docs/secrets/identity/identity-token) -- and define a strong security policy and [best practices](https://auth0.com/docs/best-practices/token-best-practices). + +Compromised keys can provide attackers access to you nodes RPC-API. + +::: + +### 2. Create the JWT + +Create the JWT using a trusted authentication provider[^1] or [library](https://jwt.io/libraries) in your own code. + +[^1]: for example [Auth0](https://auth0.com/) or [Keycloak](https://www.keycloak.org/) + +See [Java code sample to generate JWT using Vertx](https://github.com/NicolasMassart/java-jwt-sample-generation/) for an example implementation. + +:::caution + +The JWT must use one of the `RS256`, `RS384`, `RS512`, `ES256`, `ES384`, or `ES512` algorithms. + +::: + +Each payload for the JWT must contain: + +- [JSON-RPC permissions](#json-rpc-permissions) +- [`exp` (Expiration Time) claim](https://tools.ietf.org/html/rfc7519#section-4.1.4) +- Optionally, the tenant's Tessera public key using `privacyPublicKey`. Only used for [multi-tenancy](../../../private-networks/concepts/privacy/multi-tenancy.md). + + + +# Example JSON Payload + +```json +{ + "permissions": ["*:*"], + "privacyPublicKey": "2UKH3VJThkOoKskrLFpwoxCnnRARyobV1bEdgseFHTs=", + "exp": 1600899999002 +} +``` + +# Example JWT result + +![Example result](jwt.png) + + + +### 3. Enable authentication + +To require authentication for the JSON-RPC API, use the [`--rpc-http-authentication-enabled`](../../reference/cli/options.md#rpc-http-authentication-enabled) or [`--rpc-ws-authentication-enabled`](../../reference/cli/options.md#rpc-ws-authentication-enabled) options. + +To specify the JWT provider's public key file to use with the externally created JWT, use the [`--rpc-http-authentication-jwt-public-key-file`](../../reference/cli/options.md#rpc-http-authentication-jwt-public-key-file) or [`--rpc-ws-authentication-jwt-public-key-file`](../../reference/cli/options.md#rpc-ws-authentication-jwt-public-key-file) options. + +## JSON-RPC permissions + +Each user has a list of permissions strings defining the methods they can access. To give access to: + +- All API methods, specify `["*:*"]`. +- All API methods in an API group, specify `[":*"]`. For example, `["eth:*"]`. +- Specific API methods, specify `[":"]`. For example, `["admin:peers"]`. + +With authentication enabled, to explicitly specify a user cannot access any methods, include the user with an empty permissions list (`[]`). Users with an empty permissions list and users not included in the credentials file cannot access any JSON-RPC methods. + +## Use an authentication token to make requests + +Specify the authentication token as a `Bearer` token in the JSON-RPC request header. + +### Postman + +In the **Authorization** tab in the **TYPE** drop-down list, select **Bearer Token** and specify the token (generated either [externally](#2-create-the-jwt) or by the [`login` request](#3-generate-an-authentication-token)). + +### cURL + +Specify the `Bearer` in the header. + + + +# cURL Request with authentication placeholders + +```bash +curl -X POST -H 'Authorization: Bearer ' -d '{"jsonrpc":"2.0","method":"","params":[],"id":1}' +``` + +# cURL Request with authentication + +```bash +curl -X POST -H 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJwZXJtaXNzaW9ucyI6WyIqOioiXSwidXNlcm5hbWUiOiJ1c2VyMiIsImlhdCI6MTU1MDQ2MTQxNiwiZXhwIjoxNTUwNDYxNzE2fQ.WQ1mqpqzRLHaoL8gOSEZPvnRs_qf6j__7A3Sg8vf9RKvWdNTww_vRJF1gjcVy-FFh96AchVnQyXVx0aNUz9O0txt8VN3jqABVWbGMfSk2T_CFdSw5aDjuriCsves9BQpP70Vhj-tseaudg-XU5hCokX0tChbAqd9fB2138zYm5M' -d '{"jsonrpc":"2.0","method":"net_listening","params":[],"id":1}' http://localhost:8545 +``` + + diff --git a/versioned_docs/version-23.10.1/public-networks/how-to/use-besu-api/graphql.md b/versioned_docs/version-23.10.1/public-networks/how-to/use-besu-api/graphql.md new file mode 100644 index 00000000000..0ac87401670 --- /dev/null +++ b/versioned_docs/version-23.10.1/public-networks/how-to/use-besu-api/graphql.md @@ -0,0 +1,192 @@ +--- +title: Use GraphQL over HTTP +sidebar_position: 3 +description: How to access the Hyperledger Besu API using GraphQL +tags: + - public networks + - private networks +--- + +# Use GraphQL over HTTP + +GraphQL can reduce the overhead needed for common queries. +For example, instead of querying each receipt in a block, GraphQL can get the same result with a +single query for the entire block. + +The [Besu GraphQL schema] describes the GraphQL implementation for Ethereum. +Enable the GraphQL service using [command line options](index.md#enable-api-access). + +:::note + +GraphQL is not supported over WebSocket. + +::: + +Access the GraphQL endpoint at `http://:/graphql`. +Configure `` and `` using [`graphql-http-host`](../../reference/cli/options.md#graphql-http-host) +and [`graphql-http-port`](../../reference/cli/options.md#graphql-http-port). +The default endpoint is `http://127.0.0.1:8547/graphql`. + +## GraphQL requests with cURL + +[Hyperledger Besu JSON-RPC API methods](../../reference/api/index.md) with an equivalent +[GraphQL](graphql.md) query include a GraphQL request and result in the method example. + +For example, the following request returns the block number: + + + +# Request + +```bash +curl -X POST -H "Content-Type: application/json" --data '{ "query": "{block{number}}"}' http://localhost:8547/graphql +``` + +# Response + +```json +{ + "data" : { + "block" : { + "number" : "0x281" + } + } +} +``` + + + +The following request returns the gas price: + + + +# Request + +```bash +curl -X POST -H "Content-Type: application/json" --data '{ "query": "{gasPrice}"}' http://localhost:8547/graphql +``` + +# Response + +```json +{ + "data" : { + "gasPrice" : "0x0" + } +} +``` + + + +The following [`syncing`](../../reference/api/index.md#eth_syncing) request returns data about the +synchronization status: + + + +# Request + +```bash +curl -X POST -H "Content-Type: application/json" --data '{ "query": "{syncing{startingBlock currentBlock highestBlock}}"}' http://localhost:8547/graphql +``` + +# Response + +```json +{ + "data" : { + "syncing" : { + "startingBlock" : 665, + "currentBlock" : 3190, + "highestBlock" : 26395 + } + } +} +``` + + + +:::info note +In some cases, for example, when your node is fully synced, the syncing request returns a `null` response: + +```json +{ + "data" : { + "syncing" : null + } +} +``` +::: + +## GraphQL requests with GraphiQL app + +The third-party tool, [GraphiQL](https://github.com/skevy/graphiql-app), provides a tabbed interface +for editing and testing GraphQL queries and mutations. +GraphiQL also provides access to the [Besu GraphQL schema] from within the app. + +![GraphiQL](../../../assets/images/GraphiQL.png) + +## Pending + +`transactionCount` and `transactions` supports the Pending query. + +:::info + +Besu does not execute pending transactions so results from `account`, `call`, and `estimateGas` for +Pending do not reflect pending transactions. + +::: + + + +# Pending transaction count + +```bash +curl -X POST -H "Content-Type: application/json" --data '{ "query": "{pending {transactionCount}}"}' http://localhost:8547/graphql +``` + +# Result + +```json +{ + "data": { + "pending": { + "transactionCount": 2 + } + } +} +``` + + + + + +# Pending transactions + +```bash +curl -X POST -H "Content-Type: application/json" --data '{ "query": "{pending {transactions{hash}}}"}' http://localhost:8547/graphql +``` + +# Result + +```json +{ + "data": { + "pending": { + "transactions": [ + { + "hash": "0xbb3ab8e2113a4afdde9753782cb0680408c0d5b982572dda117a4c72fafbf3fa" + }, + { + "hash": "0xf6bd6b1bccf765024bd482a71c6855428e2903895982090ab5dbb0feda717af6" + } + ] + } + } +} +``` + + + + + +[Besu GraphQL schema]: https://github.com/hyperledger/besu/blob/750580dcca349d22d024cc14a8171b2fa74b505a/ethereum/api/src/main/resources/schema.graphqls diff --git a/versioned_docs/version-23.10.1/public-networks/how-to/use-besu-api/index.md b/versioned_docs/version-23.10.1/public-networks/how-to/use-besu-api/index.md new file mode 100644 index 00000000000..381c2e4ba93 --- /dev/null +++ b/versioned_docs/version-23.10.1/public-networks/how-to/use-besu-api/index.md @@ -0,0 +1,104 @@ +--- +description: Hyperledger Besu API +tags: + - public networks + - private networks +--- + +# Access the Hyperledger Besu API + +Access the [Hyperledger Besu API](../../reference/api/index.md) using: + +- [JSON-RPC over HTTP, WebSocket, or IPC](json-rpc.md) +- [RPC Pub/Sub over WebSockets](rpc-pubsub.md) +- [GraphQL over HTTP](graphql.md). + +:::note + +HTTP and WebSocket responses are compact JSON by default. You can use [`--json-pretty-print-enabled`](../../reference/cli/options.md#json-pretty-print-enabled) to pretty-print the output. + +::: + +The following sections provide information about JSON-RPC, RPC Pub/Sub, and GraphQL. + +## Enable API access + +To enable API access, use the [`--rpc-http-enabled`](../../reference/cli/options.md#rpc-http-enabled), [`--ws-http-enabled`](../../reference/cli/options.md#rpc-ws-enabled), [`--graphql-http-enabled`](../../reference/cli/options.md#graphql-http-enabled), and `--Xrpc-ipc-enabled` options. + +:::caution + +`--Xrpc-ipc-enabled` is an early access option. + +::: + +## Service hosts + +To specify the host the API service listens on, use the [`--rpc-http-host`](../../reference/cli/options.md#rpc-http-host), [`--rpc-ws-host`](../../reference/cli/options.md#rpc-ws-host), and [`--graphql-http-host`](../../reference/cli/options.md#graphql-http-host) options. The default host is `127.0.0.1`. + +To allow remote connections, set the host to `0.0.0.0`. + +:::caution + +Setting the host to `0.0.0.0` exposes the API service connection on your node to any remote connection. In a production environment, ensure you use a firewall to avoid exposing your node to the internet. + +::: + +## Service ports + +To specify the port the API service listens on, use the [`--rpc-http-port`](../../reference/cli/options.md#rpc-http-port), [`--rpc-ws-port`](../../reference/cli/options.md#rpc-ws-port), and [`--graphql-http-port`](../../reference/cli/options.md#graphql-http-port) options. + +The default ports are: + +- 8545 for JSON-RPC over HTTP. +- 8546 for JSON-RPC over WebSocket. +- 8547 for GraphQL over HTTP. + +Ports must be [exposed appropriately](../connect/configure-ports.md). + +## Socket path + +To specify the socket path for the IPC socket, use the `--Xrpc-ipc-path` option. The default path is `besu.ipc` in the Besu data directory. + +:::caution + +`--Xrpc-ipc-path` is an early access option. + +::: + +## Host allowlist + +To prevent DNS rebinding attacks, Besu checks incoming HTTP request host headers, WebSocket connections, and GraphQL requests. Besu accepts requests only when hostnames specified using the [`--host-allowlist`](../../reference/cli/options.md#host-allowlist) option matches the request host headers. By default, Besu accepts requests and connections from `localhost` and `127.0.0.1`. + +:::info + +This isn't a permissioning feature. To restrict access to the API, we recommend using the [Besu authentication mechanism](authenticate.md) with username and password authentication or JWT public key authentication. + +::: + +If your application publishes RPC ports, specify the hostnames when starting Besu. + +```bash +besu --host-allowlist=example.com +``` + +Specify `*` for `--host-allowlist` to effectively disable host protection. + +:::caution + +Specifying `*` for `--host-allowlist` is not recommended for production code. + +::: + +## Not supported by Besu + +### Account management + +Account management relies on private key management in the client, which is not supported by Besu. + +To send signed transactions, use [`eth_sendRawTransaction`](../../reference/api/index.md#eth_sendrawtransaction). `eth_sendTransaction` is not implemented. + +For [account management](../send-transactions.md#use-wallets-for-key-management), use third-party wallets. + +### Protocols + +Besu does not support the Whisper and Swarm protocols. diff --git a/versioned_docs/version-23.10.1/public-networks/how-to/use-besu-api/json-rpc.md b/versioned_docs/version-23.10.1/public-networks/how-to/use-besu-api/json-rpc.md new file mode 100644 index 00000000000..84f70aa4086 --- /dev/null +++ b/versioned_docs/version-23.10.1/public-networks/how-to/use-besu-api/json-rpc.md @@ -0,0 +1,292 @@ +--- +title: Use JSON-RPC over HTTP, WS, and IPC +sidebar_position: 1 +description: How to access the Hyperledger Besu API using JSON-RPC +tags: + - public networks + - private networks +--- + +import Postman from '../../../global/postman.md'; + +# Use JSON-RPC over HTTP, WebSocket, and IPC + +JSON-RPC APIs allow you to interact with your node. JSON-RPC endpoints are not enabled by default. + +:::caution + +You should secure access to your node's JSON-RPC endpoints. Users with access to your node via JSON-RPC can make calls directly to your node, causing your node to consume resources. + +::: + +To enable JSON-RPC over HTTP or WebSocket, use the [`--rpc-http-enabled`](../../reference/cli/options.md#rpc-http-enabled) and [`--rpc-ws-enabled`](../../reference/cli/options.md#rpc-ws-enabled) options. + +To enable JSON-RPC over an [IPC socket](index.md#socket-path), use the `--Xrpc-ipc-enabled` option. + +:::caution + +`--Xrpc-ipc-enabled` is an early access option. + +::: + + + +## Geth console + +The geth console is a REPL (Read, Evaluate, & Print Loop) JavaScript console. Use JSON-RPC APIs supported by geth and Hyperledger Besu directly in the console. + +To use the geth console with Besu: + +1. Start Besu with the [`--rpc-http-enabled`](../../reference/cli/options.md#rpc-http-enabled) or `--Xrpc-ipc-enabled` option. +1. Specify which APIs to enable using the [`--rpc-http-api`](../../reference/cli/options.md#rpc-http-api) or `--Xrpc-ipc-api` option. +1. Start the geth console specifying the JSON-RPC endpoint: + + + +# HTTP endpoint + +```bash +geth attach http://localhost:8545 +``` + +# IPC endpoint + +```bash +geth attach /path/to/besu.ipc +``` + +Use the geth console to call [JSON-RPC API methods](../../reference/api/index.md) that geth and Besu share. + +```bash +eth.syncing +``` + +## JSON-RPC authentication + +Besu disables [Authentication](authenticate.md) by default. + +## HTTP and WebSocket requests + +### HTTP + +To make RPC requests over HTTP, you can use [`curl`](https://curl.haxx.se/download.html). + + + +# Syntax + +```bash +curl -X POST --data '{"jsonrpc":"2.0","id":,"method":"","params":[]}' +``` + +# curl HTTP request + +```bash +curl -X POST --data '{"jsonrpc":"2.0","id":"1","method":"eth_blockNumber","params":[]}' http://127.0.0.1:8555 +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": "1", + "result": "0x60e" +} +``` + + + +You can use `curl` to make multiple RPC requests (batch requests) over HTTP at the same time. Send the requests as an array, and receive an array of responses. The default number of allowed requests in a RPC batch request is `1024`. Use the [`--rpc-http-max-batch-size`](../../reference/cli/options.md#rpc-http-max-batch-size) command line option to update the default value. + + + +# curl HTTP request + +```bash +curl -X POST --data '[{"jsonrpc":"2.0","id":"1","method":"eth_blockNumber","params":[]}, {"jsonrpc":"2.0","id":"2","method":"admin_peers","params":[]}]' http://127.0.0.1:8555 +``` + +# JSON result + +```json +[ + { + "jsonrpc": "2.0", + "id": "1", + "result": "0x60e" + }, + { + "jsonrpc": "2.0", + "id": "2", + "result": [] + } +] +``` + + + +### WebSocket + +To make RPC requests over WebSocket, you can use [`wscat`](https://github.com/websockets/wscat), a Node.js based command-line tool. + +First connect to the WebSocket server using `wscat` (you only need to connect once per session): + +```bash +wscat -c ws:// +``` + +After you establish a connection, the terminal displays a '>' prompt. Send individual requests as a JSON data package at each prompt. + + + +# Syntax + +```bash +{"jsonrpc":"2.0","id":,"method":"","params":[]} +``` + +# wscat WS request + +```bash +{"jsonrpc":"2.0","id":"1","method":"eth_blockNumber","params":[]} +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": "1", + "result": "0x23" +} +``` + + + +You can use `wscat` to make multiple RPC requests over WebSocket at the same time. Send the requests as an array, and receive an array of responses. + + + +# wscat WS request + +```bash +[{"jsonrpc":"2.0","id":"1","method":"eth_blockNumber","params":[]}, {"jsonrpc":"2.0","id":"2","method":"admin_peers","params":[]}] +``` + +# JSON result + +```json +[ + { + "jsonrpc": "2.0", + "id": "1", + "result": "0x23" + }, + { + "jsonrpc": "2.0", + "id": "2", + "result": [] + } +] +``` + + + +:::note + +`wscat` does not support headers. [Authentication](authenticate.md) requires you to pass an authentication token in the request header. To use authentication with WebSocket, you need an app that supports headers. + +::: + +## Readiness and liveness endpoints + +Besu provides readiness and liveness endpoints to confirm the Besu node status. Both return a `200 OK` status when ready or live and a `503 Service Unavailable` status if not ready or live. + +### Readiness + +By default, the readiness check requires a connected peer and the node to be within two blocks of the best known block. If you have [disabled P2P communication](../../reference/cli/options.md#p2p-enabled), you do not need peers. A live node with P2P disabled is always ready. + +Use the query parameters `minPeers` and `maxBlocksBehind` to adjust the number of peers required and the number of blocks tolerance. + + + +# Readiness endpoint + +```bash +http:///readiness +``` + +# curl request example + +```bash +curl -v 'http://localhost:8545/readiness' +``` + +# Query parameters example + +```bash +curl -v 'http://localhost:8545/readiness?minPeers=0&maxBlocksBehind=10' +``` + + + +### Liveness + +The liveness check requires the JSON-RPC server to be up. You can use the endpoint to verify that the node can respond to RPC calls. The status in the response will always be `UP`. + + + +# Liveness endpoint + +```bash +http:///liveness +``` + +# curl request example + +```bash +curl -v 'http://localhost:8545/liveness' +``` + + + +## API methods enabled by default + +Besu enables the `ETH`, `NET`, and `WEB3` API methods by default. + +To enable the `ADMIN`, `CLIQUE`, `DEBUG`, `EEA`, `IBFT`, `MINER`, `PERM`, `PLUGINS`, `PRIV`, `TRACE`, and `TXPOOL` API methods, use the [`--rpc-http-api`](../../reference/cli/options.md#rpc-http-api), [`--rpc-ws-api`](../../reference/cli/options.md#rpc-ws-api), or `--Xrpc-ipc-api` options. + +:::caution + +`--Xrpc-ipc-api` is an early access option. + +::: + +## Block parameter + +When you make requests that might have different results depending on the block accessed, the block parameter specifies the block. Methods such as [`eth_getTransactionByBlockNumberAndIndex`](../../reference/api/index.md#eth_gettransactionbyblocknumberandindex) have a block parameter. + +The block parameter can have one of the following values: + +- `blockNumber` : _quantity_ - The block number, specified in hexadecimal or decimal. 0 represents the genesis block. +- `blockHash` : _string_ or _object_ - 32-byte block hash or JSON object specifying the block hash. If using a JSON object, you can specify `requireCanonical` to indicate whether the block must be a canonical block. See [this example](https://github.com/hyperledger/besu/blob/a2dedb0b2c7980cdc35db8eb4c094f2eb0dc7deb/ethereum/api/src/test/resources/org/hyperledger/besu/ethereum/api/jsonrpc/eth/eth_getBalance_blockHashObjectCanonical.json). + + :::note + + Only the following methods support the `blockHash` parameter: + + - [`eth_call`](../../reference/api/index.md#eth_call) + - [`eth_getBalance`](../../reference/api/index.md#eth_getbalance) + - [`eth_getCode`](../../reference/api/index.md#eth_getcode) + - [`eth_getProof`](../../reference/api/index.md#eth_getproof) + - [`eth_getStorageAt`](../../reference/api/index.md#eth_getstorageat) + - [`eth_getTransactionCount`](../../reference/api/index.md#eth_gettransactioncount) + + ::: + +- `earliest` : _tag_ - The earliest (genesis) block. +- `latest` : _tag_ - The last block mined. +- `pending` : _tag_ - The last block mined plus pending transactions. Use only with [`eth_getTransactionCount`](../../reference/api/index.md#eth_gettransactioncount). +- `finalized` : _tag_ - The most recent crypto-economically secure block. It cannot be reorganized outside manual intervention driven by community coordination. +- `safe` : _tag_ - The most recent block that is safe from reorganization under honest majority and certain synchronicity assumptions. diff --git a/versioned_docs/version-23.10.1/public-networks/how-to/use-besu-api/jwt.png b/versioned_docs/version-23.10.1/public-networks/how-to/use-besu-api/jwt.png new file mode 100644 index 00000000000..ee676469c77 Binary files /dev/null and b/versioned_docs/version-23.10.1/public-networks/how-to/use-besu-api/jwt.png differ diff --git a/versioned_docs/version-23.10.1/public-networks/how-to/use-besu-api/rpc-pubsub.md b/versioned_docs/version-23.10.1/public-networks/how-to/use-besu-api/rpc-pubsub.md new file mode 100644 index 00000000000..ab315fd1468 --- /dev/null +++ b/versioned_docs/version-23.10.1/public-networks/how-to/use-besu-api/rpc-pubsub.md @@ -0,0 +1,533 @@ +--- +title: Use RPC Pub/Sub over WS +sidebar_position: 2 +description: Using RPC Pub/Sub with Hyperledger Besu WebSockets +tags: + - public networks + - private networks +--- + +# Use RPC Pub/Sub over WebSockets + +## Introduction + +Subscribe to events by using either RPC Pub/Sub over WebSockets or [filters over HTTP](access-logs.md). + +Use RPC Pub/Sub over WebSockets to wait for events instead of polling for them. For example, dapps subscribe to logs and receive notifications when a specific event occurs. + +Methods specific to RPC Pub/Sub are: + +- `eth_subscribe` and `eth_unsubscribe` - create or cancel a subscription for specific events. +- `priv_subscribe` and `priv_unsubscribe` - create or cancel a subscription for [private logs](../../../private-networks/concepts/privacy/index.md). + +:::info + +Unlike other [Hyperledger Besu API methods](../../reference/api/index.md), you cannot call the RPC Pub/Sub methods over HTTP. Use the [`--rpc-ws-enabled`](../../reference/cli/options.md#rpc-ws-enabled) option to enable the WebSockets JSON-RPC service. + +::: + +### Use RPC Pub/Sub + +[WebSockets](json-rpc.md#http-and-websocket-requests) supports the RPC Pub/Sub API. + +To create subscriptions, use `eth_subscribe` or `priv_subscribe`. Once subscribed, the API publishes notifications using `eth_subscription` or `priv_subscription`. + +Subscriptions couple with connections. If a connection is closed, all subscriptions created over the connection are removed. + +### Subscription ID + +`eth_subscribe` and `priv_subscribe` return a subscription ID for each subscription created. Notifications include the subscription ID. + +For example, to create a synchronizing subscription: + +```json +{ "id": 1, "method": "eth_subscribe", "params": ["syncing"] } +``` + +The result includes the subscription ID of `"0x1"`: + +```json +{ "jsonrpc": "2.0", "id": 1, "result": "0x1" } +``` + +The notifications also include the subscription ID of `"0x1"`: + +```json +{ + "jsonrpc": "2.0", + "method": "eth_subscription", + "params": { + "subscription": "0x1", + "result": { + "startingBlock": "0x0", + "currentBlock": "0x50", + "highestBlock": "0x343c19" + } + } +} +``` + +### Notifications when synchronizing + +Subscribing to some events (for example, logs) can cause a flood of notifications while the node is synchronizing. + +## Subscribe + +Use `eth_subscribe` to create subscriptions for the following event types: + +- [Use RPC Pub/Sub over WebSockets](#use-rpc-pubsub-over-websockets) + - [Introduction](#introduction) + - [Use RPC Pub/Sub](#use-rpc-pubsub) + - [Subscription ID](#subscription-id) + - [Notifications when synchronizing](#notifications-when-synchronizing) + - [Subscribe](#subscribe) + - [New headers](#new-headers) + - [Logs](#logs) +- [All logs](#all-logs) +- [Specific address, topic, fromBlock and toBlock](#specific-address-topic-fromblock-and-toblock) +- [Result](#result) +- [Notification](#notification) +- [All logs for privacy group](#all-logs-for-privacy-group) +- [Specific address and topic](#specific-address-and-topic) +- [Result](#result-1) +- [Notification](#notification-1) + - [Pending transactions](#pending-transactions) + - [Dropped transactions](#dropped-transactions) + - [Synchronizing](#synchronizing) + - [Unsubscribe](#unsubscribe) + +Use `priv_subscribe` to [create subscriptions for logs on private contracts](#logs). + +:::tip + +Only logs subscriptions are relevant for private transactions because private transactions are anchored to the public chain rather than having their own private blockchain. + +::: + +### New headers + +To notify you about each block added to the blockchain, use the `newHeads` parameter with `eth_subscribe`. + +If a chain reorganization occurs, the subscription publishes notifications for blocks in the new chain. This means the subscription can publish notifications for multiple blocks at the same height on the blockchain. + +The new headers notification returns [block objects](../../reference/api/objects.md#block-object). The second parameter is optional. If specified, the notifications include whole [transaction objects](../../reference/api/objects.md#transaction-object), Otherwise, the notifications include transaction hashes. + +To subscribe to new header notifications: + +```json +{ + "id": 1, + "method": "eth_subscribe", + "params": ["newHeads", { "includeTransactions": true }] +} +``` + +Example result: + +```json +{ "jsonrpc": "2.0", "id": 2, "result": "0x1" } +``` + +Example notification without the `{"includeTransactions": true}` parameter included: + +```json +{ + "jsonrpc": "2.0", + "method": "eth_subscription", + "params": { + "subscription": "0x1", + "result": { + "number": "0x40c22", + "hash": "0x16af2ee1672203c7ac13ff280822008be0f38e1e5bdc675760015ae3192c0e3a", + "parentHash": "0x1fcf5dadfaf2ab4d985eb05d40eaa23605b0db25d736610c4b87173bfe438f91", + "nonce": "0x0000000000000000", + "sha3Uncles": "0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347", + "logsBloom": "0x00008000000000080000000000000000000000000000000000000000000000000000000000000000000000000010000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000010000000000000000000000000000000000000040000000000000000000000000000000000000000001000000000000000000000040000000000000000000000000000000000000400000000010000000000000000100000000000020000000000000000000000000000000000010000000000000000000000000000000000000000000", + "transactionsRoot": "0x5b2e3c1a49352f1ca9fb5dfe74b7ffbbb6d70e23a12693444e26058d8a8e6296", + "stateRoot": "0xbe8d3bc58bd982421a3ea8b66753404502df0f464ae78a17661d157c406dd38b", + "receiptsRoot": "0x81b175ec1f4d44fbbd6ba08f1bd3950663b307b7cb35751c067b535cc0b58f12", + "miner": "0x0000000000000000000000000000000000000000", + "difficulty": "0x1", + "totalDifficulty": "0x7c16e", + "extraData": "0xd783010600846765746887676f312e372e33856c696e757800000000000000002160f780bb1f61eda045c67cdb1297ba37d8349df8035533cb0cf82a7e45f23f3d72bbec125a9f499b3eb110b7d1918d466cb2ede90b38296cfe2aaf452c513f00", + "size": "0x3a1", + "gasLimit": "0x47e7c4", + "gasUsed": "0x11ac3a", + "timestamp": "0x592afc24", + "uncles": [], + "transactions": [ + "0x419c69d21b14e2e8f911def22bb6d0156c876c0e1c61067de836713043364d6c", + "0x70a5b2cb2cee6e0b199232a1757fc2a9d6053a4691a7afef8508fd88aeeec703", + "0x4b3035f1d32339fe1a4f88147dc197a0fe5bbd63d3b9dec2dad96a3b46e4fddd" + ] + } + } +} +``` + +Example notification with the `{"includeTransactions": true}` parameter included: + +```json +{ +"jsonrpc": "2.0", +"method": "eth_subscription", +"params":{ + "subscription":"0x1", + "result": { + .... + "transactions":[ + { + "blockHash":"0xa30ee4d7c271ae5150aec494131c5f1f34089c7aa8fb58bd8bb916a55275bb90", + "blockNumber":"0x63", + "from":"0xfe3b557e8fb62b89f4916b721be55ceb828dbd73", + "gas":"0x5208", + "gasPrice":"0x3b9aca00", + "hash":"0x11f66c3e96a92e3c14c1c33ad77381221bf8b58a887b4fed6aee456fc6f39b24", + "input":"0x", + "nonce":"0x1", + "to":"0x627306090abab3a6e1400e9345bc60c78a8bef57", + "transactionIndex":"0x0", + "value":"0x56bc75e2d63100000", + "v":"0xfe8", + "r":"0x4b57d179c74885ef5f9326fd000665ea7fae44095c1e2016a2817fc671beb8cc", + "s":"0x7ec060b115746dda392777df07ae1feacc0b83b3646f0a3de9a5fc3615af9bb8", + } + ], + }, + } +} +``` + +### Logs + +To notify you about [logs](../../concepts/events-and-logs.md) included in new blocks, use the `logs` parameter with `eth_subscribe` or `priv_subscribe`. Specify a filter object to receive notifications only for logs matching your filter. + +Logs subscriptions have an filter object parameter with the following fields: + +- `address` - (optional) Either an address or an array of addresses. Returns only logs created from these addresses. +- `topics` - (optional) Returns only logs that match the [specified topics](../../concepts/events-and-logs.md#topic-filters). +- `fromBlock` - (optional) The earliest block from which to return logs. +- `toBlock` - (optional) The last block from which to return logs. + +For private contracts, the privacy group ID must be specified. Only members of a privacy group receive logs for a private contract subscription. If you create a subscription for a privacy group you are not a member of, you will not receive any notifications. + +If a chain reorganization occurs, the subscription publishes notifications for logs from the old chain with the `removed` property in the [log object](../../reference/api/objects.md#log-object) set to `true`. This means the subscription can publish notifications for multiple logs for the same transaction. + +The logs subscription returns [log objects](../../reference/api/objects.md#log-object). + + + +# All logs + +```json +{ "id": 1, "method": "eth_subscribe", "params": ["logs", {}] } +``` + +# Specific address, topic, fromBlock and toBlock + +```json +{ + "id": 1, + "method": "eth_subscribe", + "params": [ + "logs", + { + "address": "0x8320fe7702b96808f7bbc0d4a888ed1468216cfd", + "topics": [ + "0xd78a0cb8bb633d06981248b816e7bd33c2a35a6089241d099fa519e361cab902" + ], + "fromBlock": "0x0", + "toBlock": "latest" + } + ] +} +``` + +# Result + +```json +{ "jsonrpc": "2.0", "id": 1, "result": "0x2" } +``` + +# Notification + +```json +{ + "jsonrpc": "2.0", + "method": "eth_subscription", + "params": { + "subscription": "0x2", + "result": { + "logIndex": "0x0", + "removed": false, + "blockNumber": "0x2174", + "blockHash": "0x7bc83837534aa13df55ff7db77784b1d1ba666d4c4bdd223cae9fe09c7c37eba", + "transactionHash": "0x942179373e413824c6bc7045e92295aff91b679215446549b4aeb084da46495b", + "transactionIndex": "0x0", + "address": "0x9b8397f1b0fecd3a1a40cdd5e8221fa461898517", + "data": "0x", + "topics": [ + "0x199cd93e851e4c78c437891155e2112093f8f15394aa89dab09e38d6ca072787", + "0x0000000000000000000000000000000000000000000000000000000000000005" + ] + } + } +} +``` + + + + + +# All logs for privacy group + +```json +{ + "id": 1, + "method": "priv_subscribe", + "params": ["4sSv8eqB6/0lV9I0tBGUhPjjHtLEf3z0eeMc8Lokkyo=", "logs", {}] +} +``` + +# Specific address and topic + +```json +{ + "id": 1, + "method": "priv_subscribe", + "params": [ + "4sSv8eqB6/0lV9I0tBGUhPjjHtLEf3z0eeMc8Lokkyo=", + "logs", + { + "address": "0x8320fe7702b96808f7bbc0d4a888ed1468216cfd", + "topics": [ + "0xd78a0cb8bb633d06981248b816e7bd33c2a35a6089241d099fa519e361cab902" + ] + } + ] +} +``` + +# Result + +```json +{ "jsonrpc": "2.0", "id": 1, "result": "0x1" } +``` + +# Notification + +```json +{ + "jsonrpc": "2.0", + "method": "priv_subscription", + "params": { + "subscription": "0x1", + "privacyGroupId": "4sSv8eqB6/0lV9I0tBGUhPjjHtLEf3z0eeMc8Lokkyo=", + "result": { + "logIndex": "0x0", + "removed": false, + "blockNumber": "0x285", + "blockHash": "0x98490766b16de2a4d044c04d92599d71e626bc96e42f0c74274ef4e03fafd579", + "transactionHash": "0x40034ef14e3a22946693dd2a11efddf3a8850ddcad46b408198df6c176c53ffb", + "transactionIndex": "0x0", + "address": "0x61f96a7ed09877197d4fff0c29b8e523913651a9", + "data": "0x", + "topics": [ + "0x85bea11d86cefb165374e0f727bacf21dc2f4ea816493981ecf72dcfb212a410", + "0x0000000000000000000000000000000000000000000000000000000000000002" + ] + } + } +} +``` + + + +### Pending transactions + +To notify you about pending transactions added to the transaction pool for the node, use the `newPendingTransactions` parameter with `eth_subscribe`. + +The pending transactions subscription returns the transaction hashes or transaction details of the pending transactions. If the `includeTransactions` parameter is not included, the default is transaction hashes only. + +If a chain reorganization occurs, Besu resubmits transactions for inclusion in the new canonical chain. This means the subscription can publish notifications for the same pending transaction more than once. + +To subscribe to pending transaction notifications and receive transaction hashes only: + +```json +{ + "id": 1, + "method": "eth_subscribe", + "params": ["newPendingTransactions", { "includeTransactions": false }] +} +``` + +Example result: + +```json +{ "jsonrpc": "2.0", "id": 1, "result": "0x1" } +``` + +Example notification: + +```json +{ + "jsonrpc": "2.0", + "method": "eth_subscription", + "params": { + "subscription": "0x1", + "result": "0x5705bc8bf875ff03e98adb98489428835892dc6ba6a6b139fee1becbc26db0b8" + } +} +``` + +To subscribe to pending transaction notifications and receive transaction details: + +```json +{ + "id": 1, + "method": "eth_subscribe", + "params": ["newPendingTransactions", { "includeTransactions": true }] +} +``` + +Example result: + +```json +{ "jsonrpc": "2.0", "id": 1, "result": "0x2" } +``` + +Example notification: + +```json +{ + "jsonrpc": "2.0", + "method": "eth_subscription", + "params": { + "subscription": "0x2", + "result": { + "from": "0xfe3b557e8fb62b89f4916b721be55ceb828dbd73", + "gas": "0x5208", + "gasPrice": "0x2540be400", + "hash": "0x7a4185f40ee93cb27eb132f301d0a5414c1f871051f166fc8804c376aab3ffec", + "input": "0x", + "nonce": "0x13", + "to": "0x9d8f8572f345e1ae53db1dfa4a7fce49b467bd7f", + "value": "0x8ac7230489e80000", + "v": "0xfe7", + "r": "0xdd9013c67469d2fe79afdc61777c55bdced33c90fa6f9b83d8f9b7e445085123", + "s": "0x45823a1ab22ae9c83876ea435dc5ecc4fe3a83c1bfbc340a5f57df2f5a474fa5" + } + } +} +``` + +### Dropped transactions + +To notify you about transactions dropped from the transaction pool for the node, use the `droppedPendingTransactions` parameter with `eth_subscribe`. + +The dropped transactions subscription returns the transaction hashes of the dropped transactions. + +Dropped transactions can be re-added to the transaction pool from a variety of sources. For example, receiving a previously dropped transaction from a peer. As a result, it's possible to receive multiple dropped transaction notifications for the same transaction. + +To subscribe to dropped transaction notifications: + +```json +{ "id": 1, "method": "eth_subscribe", "params": ["droppedPendingTransactions"] } +``` + +Example result: + +```json +{ "jsonrpc": "2.0", "id": 1, "result": "0x1" } +``` + +Example notification: + +```json +{ + "jsonrpc": "2.0", + "method": "eth_subscription", + "params": { + "subscription": "0x1", + "result": "0xf57d6a90a7fb30880cfbdf6b432b487d0e94a3b55b34dc4b45e3b0b237ecab4c" + } +} +``` + +### Synchronizing + +To notify you about synchronization progress, use the `syncing` parameter with `eth_subscribe`. + +When behind the chain head, the synchronizing subscription returns an object indicating the synchronization progress. When fully synchronized, returns `false`. + +To subscribe to synchronizing notifications: + +```json +{ "id": 1, "method": "eth_subscribe", "params": ["syncing"] } +``` + +Example result: + +```json +{ "jsonrpc": "2.0", "id": 1, "result": "0x4" } +``` + +Example notification while synchronizing: + +```json +{ + "jsonrpc": "2.0", + "method": "eth_subscription", + "params": { + "subscription": "0x4", + "result": { + "startingBlock": "0x0", + "currentBlock": "0x3e80", + "highestBlock": "0x67b93c" + } + } +} +``` + +Example notification when synchronized with chain head: + +```json +{ + "jsonrpc": "2.0", + "method": "eth_subscription", + "params": { + "subscription": "0x4", + "result": false + } +} +``` + +## Unsubscribe + +To cancel a subscription, use the [subscription ID](#subscription-id) with `eth_unsubscribe` or `priv_unsubscribe`. Only the connection that created a subscription can unsubscribe from it. + +When cancelling a subscription for private logs, the privacy group ID must be specified. + +`eth_unsubscribe` and `priv_unsubscribe` return `true` if subscription successfully unsubscribed; otherwise, returns an error. + +To unsubscribe from a subscription with subscription ID of `0x1`: + +```json +{ "id": 1, "method": "eth_unsubscribe", "params": ["0x1"] } +``` + +To unsubscribe from private logs subscription: + +```json +{ + "id": 1, + "method": "priv_unsubscribe", + "params": ["4sSv8eqB6/0lV9I0tBGUhPjjHtLEf3z0eeMc8Lokkyo=", "0x2"] +} +``` + +Example result: + +```json +{ "jsonrpc": "2.0", "id": 1, "result": true } +``` diff --git a/versioned_docs/version-23.10.1/public-networks/how-to/use-engine-api.md b/versioned_docs/version-23.10.1/public-networks/how-to/use-engine-api.md new file mode 100644 index 00000000000..b64ab795482 --- /dev/null +++ b/versioned_docs/version-23.10.1/public-networks/how-to/use-engine-api.md @@ -0,0 +1,209 @@ +--- +title: Use the Engine API +sidebar_position: 2 +description: Use the Engine API to communicate with a consensus client. +tags: + - public networks +--- + +# Use the Engine API + +[Consensus and execution clients](../concepts/the-merge.md#execution-and-consensus-clients) communicate with each other using the [Engine API](../reference/engine-api/index.md). These API methods are a separate subsection of the [JSON-RPC API](../how-to/use-besu-api/index.md). + +## Configure the Engine API + +The Engine API is enabled by default even if no consensus client configuration exists. You can configure the Engine API to: + +- Specify the [service ports](#service-ports). +- Specify the [host allowlist](#host-allowlist). + +```bash title="Example Engine API configuration" +besu --engine-rpc-port=8551 --engine-host-allowlist=localhost,127.0.0.1 --engine-jwt-secret=jwt.hex +``` + + +### Service ports + +To specify the port the Engine API service listens on for HTTP and WebSocket, use the [`--engine-rpc-port`](../reference/cli/options.md#engine-rpc-port) option. The default is `8551`. This option is useful when you have another execution engine running on port 8551, in which case you can specify Besu to use another port, for example, `--engine-rpc-port 8552`. + +### Host allowlist + +To prevent DNS rebinding attacks, Besu checks incoming HTTP request host headers, WebSocket connections, and GraphQL requests. Besu accepts requests only when hostnames specified using the [`--engine-host-allowlist`](../reference/cli/options.md#engine-host-allowlist) option matches the request host headers. By default, Besu accepts requests and connections from `localhost` and `127.0.0.1`. + +:::info + +This isn't a permissioning feature. To restrict access to the Engine API, we recommend using [authentication](#authentication). + +::: + +If your application publishes RPC ports, specify the hostnames when starting Besu. + +Specify `*` for `--engine-host-allowlist` to effectively disable host protection. + +:::caution + +We don't recommend specifying `*` for `--engine-host-allowlist` in production. + +::: + +## Authentication + +By default, [authentication](../how-to/use-besu-api/authenticate.md) for the Engine API is enabled. To disable, set the [`--engine-jwt-disabled`](../reference/cli/options.md#engine-jwt-disabled) option to `true`. + +:::caution + +Don't disable JWT authentication in production environments. + +Disable only for testing purposes. + +::: + +Set the [JWT secret](use-besu-api/authenticate.md#jwt-public-key-authentication) by using the [`--engine-jwt-secret`](../reference/cli/options.md#engine-jwt-secret) option. + +## Send a payload using the Engine API + +### 1. Prepare a payload + +Prepare to send a payload using [`engine_forkchoiceUpdatedV1`](../reference/engine-api/index.md#engine_forkchoiceupdatedv1). + + + +# curl HTTP request + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"engine_forkchoiceUpdatedV1","params":[{"headBlockHash": "0x3b8fb240d288781d4aac94d3fd16809ee413bc99294a085798a589dae51ddd4a", "safeBlockHash": "0x3b8fb240d288781d4aac94d3fd16809ee413bc99294a085798a589dae51ddd4a", "finalizedBlockHash": "0x0000000000000000000000000000000000000000000000000000000000000000"},{"timestamp": "0x5","prevRandao": "0x0000000000000000000000000000000000000000000000000000000000000000","suggestedFeeRecipient": "0xa94f5374fce5edbc8e2a8697c15331677e6ebf0b"}],"id":67}' http://127.0.0.1:8550 +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 67, + "result": { + "payloadStatus": { + "status": "VALID", + "latestValidHash": "0x3b8fb240d288781d4aac94d3fd16809ee413bc99294a085798a589dae51ddd4a", + "validationError": null + }, + "payloadId": "0x0000000021f32cc1" + } +} +``` + + + +### 2. Get the payload + +Get the payload using [`engine_getPayloadV1`](../reference/engine-api/index.md#engine_getpayloadv1) + + + +# curl HTTP request + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"engine_getPayloadV1","params":["0x1"],"id":1}' http://127.0.0.1:8550 +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + "parentHash": "0x3b8fb240d288781d4aac94d3fd16809ee413bc99294a085798a589dae51ddd4a", + "feeRecipient": "0xa94f5374fce5edbc8e2a8697c15331677e6ebf0b", + "stateRoot": "0xca3149fa9e37db08d1cd49c9061db1002ef1cd58db2210f2115c8c989b2bdf45", + "receiptsRoot": "0x56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421", + "logsBloom": "0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000", + "prevRandao": "0x0000000000000000000000000000000000000000000000000000000000000000", + "blockNumber": "0x1", + "gasLimit": "0x1c9c380", + "gasUsed": "0x0", + "timestamp": "0x5", + "extraData": "0x", + "baseFeePerGas": "0x7", + "blockHash": "0x3559e851470f6e7bbed1db474980683e8c315bfce99b2a6ef47c057c04de7858", + "transactions": [] + } +} +``` + + + +### 3. Execute the payload + +Execute the payload using [`engine_newPayloadV1`](../reference/engine-api/index.md#engine_newpayloadv1) + + + +# curl HTTP request + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"engine_newPayloadV1","params":[ + { + "parentHash": "0x3b8fb240d288781d4aac94d3fd16809ee413bc99294a085798a589dae51ddd4a", + "feeRecipient": "0xa94f5374fce5edbc8e2a8697c15331677e6ebf0b", + "stateRoot": "0xca3149fa9e37db08d1cd49c9061db1002ef1cd58db2210f2115c8c989b2bdf45", + "receiptsRoot": "0x56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421", + "logsBloom": "0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000", + "prevRandao": "0x0000000000000000000000000000000000000000000000000000000000000000", + "blockNumber": "0x1", + "gasLimit": "0x1c9c380", + "gasUsed": "0x0", + "timestamp": "0x5", + "extraData": "0x", + "baseFeePerGas": "0x7", + "blockHash": "0x3559e851470f6e7bbed1db474980683e8c315bfce99b2a6ef47c057c04de7858", + "transactions": [] + } +],"id":67}' http://127.0.0.1:8550 +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + "status": "VALID", + "latestValidHash": "0x3559e851470f6e7bbed1db474980683e8c315bfce99b2a6ef47c057c04de7858", + "validationError": null + } +} +``` + + + +### 4. Update the fork choice + +Update the fork choice using [`engine_forkchoiceUpdatedV1`](../reference/engine-api/index.md#engine_forkchoiceupdatedv1) again. + + + +# curl HTTP request + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"engine_forkchoiceUpdatedV1","params":[{"headBlockHash": "0x3559e851470f6e7bbed1db474980683e8c315bfce99b2a6ef47c057c04de7858", "safeBlockHash": "0x3559e851470f6e7bbed1db474980683e8c315bfce99b2a6ef47c057c04de7858", "finalizedBlockHash": "0x3b8fb240d288781d4aac94d3fd16809ee413bc99294a085798a589dae51ddd4a"},null],"id":67}' http://127.0.0.1:8550 +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 67, + "result": { + "payloadStatus": { + "status": "VALID", + "latestValidHash": "0x3559e851470f6e7bbed1db474980683e8c315bfce99b2a6ef47c057c04de7858", + "validationError": null + }, + "payloadId": null + } +} +``` + + diff --git a/versioned_docs/version-23.10.1/public-networks/how-to/use-pow/_category_.json b/versioned_docs/version-23.10.1/public-networks/how-to/use-pow/_category_.json new file mode 100644 index 00000000000..1381dd9fc66 --- /dev/null +++ b/versioned_docs/version-23.10.1/public-networks/how-to/use-pow/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Use proof of work", + "position": 10 +} diff --git a/versioned_docs/version-23.10.1/public-networks/how-to/use-pow/mining.md b/versioned_docs/version-23.10.1/public-networks/how-to/use-pow/mining.md new file mode 100644 index 00000000000..6dbd9b29f52 --- /dev/null +++ b/versioned_docs/version-23.10.1/public-networks/how-to/use-pow/mining.md @@ -0,0 +1,111 @@ +--- +title: Configure mining +sidebar_position: 1 +description: Using Hyperledger Besu for PoW CPU mining +tags: + - public networks + - private networks +--- + +# Configure mining + +Hyperledger Besu supports CPU and GPU mining, which are configured using command line options. + +GPU mining tests used [Ethminer](https://github.com/ethereum-mining/ethminer) with the `stratum+tcp` and `getwork` schemes. + +Ethminer has been used with Hyperledger Besu to mine blocks on the [Ropsten testnet](https://ropsten.etherscan.io/address/0x2f14582947E292a2eCd20C430B46f2d27CFE213c#mine), [ETC Mainnet (uncle block only)](https://etc.tokenview.com/en/uncleblock/10555173) and Mordor ETC testnet. + +:::note + +- Some mining software supports the `getwork` scheme as the `http` scheme. + +- The Ropsten testnet is now deprecated. It transitioned to proof of stake consensus before deprecation. + +::: + +## Configure CPU mining + +To enable CPU mining, start Hyperledger Besu with the following options: + +```bash +besu --rpc-http-api=ETH,MINER --miner-enabled --miner-coinbase= +``` + +Where `` is the account you pay mining rewards to. For example, `fe3b557e8fb62b89f4916b721be55ceb828dbd73`. + +Start and stop mining using the [`miner_start`](../../reference/api/index.md#miner_start) and [`miner_stop`](../../reference/api/index.md#miner_stop) APIs. + +## Configure GPU mining + +Besu supports GPU mining, tested using [Ethminer](https://github.com/ethereum-mining/ethminer) with the `stratum+tcp` scheme. + +To enable GPU mining, start Hyperledger Besu with the following options: + +```bash +besu --rpc-http-api=ETH,MINER --miner-enabled --miner-stratum-enabled --miner-coinbase= +``` + +Where `` is the account you pay mining rewards to. For example, `fe3b557e8fb62b89f4916b721be55ceb828dbd73`. + +Optional command line options are: + +- [`--miner-stratum-host`](../../reference/cli/options.md#miner-stratum-host) to specify the host of the mining service. +- [`--miner-stratum-port`](../../reference/cli/options.md#miner-stratum-port) to specify the port of the mining service. + +:::note + +Besu also supports the `getwork` scheme. Use the [`--miner-stratum-enabled`](../../reference/cli/options.md#miner-stratum-enabled) option and [enable the `ETH` RPCs](../../reference/cli/options.md#rpc-http-api). + +The `getwork` scheme is supported as the `http` scheme in certain mining software. + +::: + +Start and stop mining using the [`miner_start`](../../reference/api/index.md#miner_start) and [`miner_stop`](../../reference/api/index.md#miner_stop) APIs. + +## Mining APIs + +The JSON-RPC API methods for mining are: + +- [`miner_start`](../../reference/api/index.md#miner_start) to start mining. +- [`miner_stop`](../../reference/api/index.md#miner_stop) to stop mining. +- [`eth_mining`](../../reference/api/index.md#eth_mining) to determine whether the client is actively mining new blocks. +- [`eth_getMinerDataByBlockHash`](../../reference/api/index.md#eth_getminerdatabyblockhash) and [`eth_getMinerDataByBlockNumber`](../../reference/api/index.md#eth_getminerdatabyblocknumber) to get the miner data for a specified block. +- [`eth_hashrate`](../../reference/api/index.md#eth_hashrate) to get the number of hashes per second with which the node is mining. Not supported for GPU mining. +- [`eth_getWork`](../../reference/api/index.md#eth_getwork) to get the hash of the current block, the seed hash, and the target boundary condition. Only used when using the `getwork` scheme. +- [`eth_submitWork`](../../reference/api/index.md#eth_submitwork) to submit the PoW solution. Only used when using the `getwork` scheme. + +## Besu mined blocks + +Besu has successfully mined blocks on the Ropsten testnet, ETC Mainnet (uncle block only) and Mordor ETC testnet. Blocks mined by the Hyperledger Besu team contain the version number used in the block's `extraData` field. The following accounts have been used to mine on public networks with Hyperledger Besu: + +- **Ropsten**: [`0x2f14582947E292a2eCd20C430B46f2d27CFE213c`](https://ropsten.etherscan.io/address/0x2f14582947E292a2eCd20C430B46f2d27CFE213c#mine) +- **ETC**: [`0x3125309aa670f5e60493b50884a7e7abf9ebb701`](https://etc.tokenview.com/en/address/0x3125309aa670f5e60493b50884a7e7abf9ebb701) +- **Mordor**: `0x2f14582947E292a2eCd20C430B46f2d27CFE213c` + +## Troubleshoot + +### Check block creation + +On mining nodes, log messages indicate block creation. + +```bash +2019-05-08 20:28:27.026+10:00 | pool-10-thread-1 | INFO | IbftRound | Importing block to chain. round=ConsensusRoundIdentifier{Sequence=660, Round=0}, hash=0x759afaba4e923d89175d850ceca4b8ef81f7d9c727b0b0b8e714b624a4b8e8cc +2019-05-08 20:28:29.020+10:00 | pool-10-thread-1 | INFO | IbftRound | Importing block to chain. round=ConsensusRoundIdentifier{Sequence=661, Round=0}, hash=0x5443e504256765f06b3cebfbee82276a034ebcc8d685b7c3d1a6010fd4acfa14 +``` + +On non-mining nodes, log messages indicate importing blocks. + +```bash +2019-05-08 20:28:29.026+10:00 | EthScheduler-Workers-1 | INFO | BlockPropagationManager | Imported #661 / 0 tx / 0 om / 0 (0.0%) gas / (0x5443e504256765f06b3cebfbee82276a034ebcc8d685b7c3d1a6010fd4acfa14) in 0.000s. +2019-05-08 20:28:31.031+10:00 | EthScheduler-Workers-0 | INFO | BlockPropagationManager | Imported #662 / 0 tx / 0 om / 0 (0.0%) gas / (0x0ead4e20123d3f1433d8dec894fcce386da4049819b24b309963ce7a8a0fcf03) in 0.000s. +``` + +To confirm the block number is increasing, use the [`eth_blockNumber`](../../reference/api/index.md#eth_blocknumber) JSON-RPC API method. + +If there's no block creation in [Clique](../../../private-networks/how-to/configure/consensus/clique.md#extra-data) or [IBFT 2.0](../../../private-networks/how-to/configure/consensus/ibft.md#extra-data) networks, ensure the validator addresses in the genesis file match running nodes. + +### No mined transactions + +If you add a transaction to the [transaction pool](../../concepts/transactions/pool.md) and the transaction hash returns, but the transaction is never mined, check the [`--min-gas-price`](../../reference/cli/options.md#min-gas-price) option on mining nodes. If the `gasPrice` on a [transaction](../send-transactions.md) is lower than the `min-gas-price` for the mining node, the transaction will never mine. + +In [free gas networks](../../../private-networks/how-to/configure/free-gas.md), you must set [`--min-gas-price`](../../reference/cli/options.md#min-gas-price) to zero. diff --git a/versioned_docs/version-23.10.1/public-networks/index.md b/versioned_docs/version-23.10.1/public-networks/index.md new file mode 100644 index 00000000000..d16d273afd8 --- /dev/null +++ b/versioned_docs/version-23.10.1/public-networks/index.md @@ -0,0 +1,25 @@ +--- +title: Public networks +sidebar_position: 1 +sidebar_label: Introduction +description: Public networks overview +tags: + - public networks +--- + +# Hyperledger Besu for public networks + +Besu serves as an [execution client](concepts/the-merge.md#execution-clients) on public proof-of-stake Ethereum networks such as Ethereum Mainnet, Goerli, and Sepolia. + +You can also run Besu using proof of work on [Ethereum Classic (ETC)](how-to/use-pow/mining.md). + +Get started by [installing Besu](get-started/install/index.md). + +## Architecture + +The following diagram outlines the high-level architecture of Besu for public networks. + +![Public architecture](../assets/images/public-architecture.jpeg) + +If you have any questions about Besu for public networks, ask on the **besu** channel on +[Hyperledger Discord](https://discord.gg/hyperledger). diff --git a/versioned_docs/version-23.10.1/public-networks/reference/_category_.json b/versioned_docs/version-23.10.1/public-networks/reference/_category_.json new file mode 100644 index 00000000000..1f988aef3d0 --- /dev/null +++ b/versioned_docs/version-23.10.1/public-networks/reference/_category_.json @@ -0,0 +1,8 @@ +{ + "label": "Reference", + "position": 6, + "link": { + "type": "generated-index", + "slug": "public-networks/reference" + } +} diff --git a/versioned_docs/version-23.10.1/public-networks/reference/api/index.md b/versioned_docs/version-23.10.1/public-networks/reference/api/index.md new file mode 100644 index 00000000000..fb0c3d0ab30 --- /dev/null +++ b/versioned_docs/version-23.10.1/public-networks/reference/api/index.md @@ -0,0 +1,6739 @@ +--- +title: Besu API +sidebar_position: 2 +description: Hyperledger Besu JSON-RPC API methods reference +tags: + - public networks + - private networks +--- + +import Postman from '../../../global/postman.md' + +# Besu API methods + +:::caution + +- This reference contains API methods that apply to both public and private networks. For private-network-specific API methods, see the [private network API reference](../../../private-networks/reference/api/index.md). +- All JSON-RPC HTTP examples use the default host and port endpoint `http://127.0.0.1:8545`. If using the [--rpc-http-host](../cli/options.md#rpc-http-host) or [--rpc-http-port](../cli/options.md#rpc-http-port) options, update the endpoint. +- Most example requests are made against private networks. Depending on network configuration and activity, your example results might be different. + +::: + + + +## `ADMIN` methods + +The `ADMIN` API methods provide administrative functionality to manage your node. + +:::note + +The `ADMIN` API methods are not enabled by default for JSON-RPC. To enable the `ADMIN` API methods, use the [`--rpc-http-api`](../cli/options.md#rpc-http-api) or [`--rpc-ws-api`](../cli/options.md#rpc-ws-api) options. + +::: + +### `admin_addPeer` + +Adds a [static node](../../how-to/connect/static-nodes.md). + +:::caution + +If connections are timing out, ensure the node ID in the [enode URL](../../concepts/node-keys.md#enode-url) is correct. + +::: + +#### Parameters + +`enode`: _string_ - [enode URL](../../concepts/node-keys.md#enode-url) of peer to add + +#### Returns + +`result`: _boolean_ - `true` if peer added or `false` if peer already a [static node](../../how-to/connect/static-nodes.md) + + + +# curl HTTP request + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"admin_addPeer","params":["enode://f59c0ab603377b6ec88b89d5bb41b98fc385030ab1e4b03752db6f7dab364559d92c757c13116ae6408d2d33f0138e7812eb8b696b2a22fe3332c4b5127b22a3@127.0.0.1:30304"],"id":1}' http://127.0.0.1:8545 +``` + +# wscat WS request + +```bash +{"jsonrpc":"2.0","method":"admin_addPeer","params":["enode://f59c0ab603377b6ec88b89d5bb41b98fc385030ab1e4b03752db6f7dab364559d92c757c13116ae6408d2d33f0138e7812eb8b696b2a22fe3332c4b5127b22a3@127.0.0.1:30304"],"id":1} +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": true +} +``` + + + +### `admin_changeLogLevel` + +Changes the log level without restarting Besu. You can change the log level for all logs, or you can change the log level for specific packages or classes. + +You can specify only one log level per RPC call. + +#### Parameters + +- `level`: _string_ - [log level](../cli/options.md#logging) + +- `log_filter`: _array_ - (optional) packages or classes for which to change the log level + +#### Returns + +`result`: _string_ - `Success` if the log level has changed, otherwise `error` + +The following example changes the debug level for specified classes to `DEBUG`. + + + +# curl HTTP request + +```bash +curl -X POST --data '{"jsonrpc":"2.0", "method":"admin_changeLogLevel", "params":["DEBUG", ["org.hyperledger.besu.ethereum.eth.manager","org.hyperledger.besu.ethereum.p2p.rlpx.connections.netty.ApiHandler"]], "id":1}' http://127.0.0.1:8545 +``` + +# wscat WS request + +```bash +{"jsonrpc":"2.0", "method":"admin_changeLogLevel", "params":["DEBUG", ["org.hyperledger.besu.ethereum.eth.manager","org.hyperledger.besu.ethereum.p2p.rlpx.connections.netty.ApiHandler"]], "id":1} +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": "Success" +} +``` + + + +The following example changes the debug level of all logs to `WARN`. + + + +# curl HTTP request + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"admin_changeLogLevel","params":["WARN"], "id":1}' http://127.0.0.1:8545 +``` + +# wscat WS request + +```json +{ + "jsonrpc": "2.0", + "method": "admin_changeLogLevel", + "params": ["WARN"], + "id": 1 +} +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": "Success" +} +``` + + + +### `admin_generateLogBloomCache` + +Generates cached log bloom indexes for blocks. APIs such as [`eth_getLogs`](#eth_getlogs) and [`eth_getFilterLogs`](#eth_getfilterlogs) use the cache for improved performance. + +:::tip + +Manually executing `admin_generateLogBloomCache` is not required unless the [`--auto-log-bloom-caching-enabled`](../cli/options.md#auto-log-bloom-caching-enabled) command line option is set to false. + +::: + +:::note + +Each index file contains 100000 blocks. The last fragment of blocks less than 100000 are not indexed. + +::: + +#### Parameters + +- `startBlock`: _string_ - block to start generating indexes + +- `endBlock`: _string_ - block to stop generating indexes + +#### Returns + +`result`: _object_ - log bloom index details: + +- `startBlock`: _string_ - starting block for the last requested cache generation + +- `endBlock`: _string_ - ending block for the last requested cache generation + +- `currentBlock`: _string_ - most recent block added to the cache + +- `indexing`: _boolean_ - indicates if indexing is in progress + +- _boolean_ - indicates acceptance of the request from this call to generate the cache + + + +# curl HTTP request + +```bash +curl -X POST --data '{jsonrpc":"2.0","method":"admin_generateLogBloomCache", "params":["0x0", "0x10000"], "id":1}' http://127.0.0.1:8545 +``` + +# wscat WS request + +```json +{ + "jsonrpc": "2.0", + "method": "admin_generateLogBloomCache", + "params": ["0x0", "0x10000"], + "id": 1 +} +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + "startBlock": "0x0", + "endBlock": "0x10000", + "currentBlock": "0x0", + "indexing": true, + "requestAccepted": true + } +} +``` + + + +### `admin_logsRemoveCache` + +Removes cache files for the specified range of blocks. + +#### Parameters + +- `fromBlock`: _string_ - hexadecimal or decimal integer representing a block number or one of the string tags `latest`, `earliest`, `pending`, `finalized`, or `safe`, as described in [block parameter](../../how-to/use-besu-api/json-rpc.md#block-parameter) + +- `toBlock`: _string_ - hexadecimal or decimal integer representing a block number or one of the string tags `latest`, `earliest`, `pending`, `finalized`, or `safe`, as described in [block parameter](../../how-to/use-besu-api/json-rpc.md#block-parameter) + +You can skip a parameter by using an empty string, `""`. If you specify: + +- No parameters, the call removes cache files for all blocks. + +- Only `fromBlock`, the call removes cache files for the specified block. + +- Only `toBlock`, the call removes cache files from the genesis block to the specified block. + +#### Returns + +`result`: _object_ - `Cache Removed` status or `error`. + + + +# curl HTTP request + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"admin_logsRemoveCache","params":["1", "100"], "id":1}' http://127.0.0.1:8545 +``` + +# wscat WS request + +```json +{ + "jsonrpc": "2.0", + "method": "admin_logsRemoveCache", + "params": ["1", "100"], + "id": 1 +} +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + "Status": "Cache Removed" + } +} +``` + + + +### `admin_logsRepairCache` + +Repairs cached logs by fixing all segments starting with the specified block number. + +#### Parameters + +`startBlock`: _string_ - decimal index of the starting block to fix; defaults to the head block + +#### Returns + +`result`: _object_ - status of the repair request; `Started` or `Already running` + + + +# curl HTTP request + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"admin_logsRepairCache","params":["1200"], "id":1}' http://127.0.0.1:8545 +``` + +# wscat WS request + +```json +{ + "jsonrpc": "2.0", + "method": "admin_logsRepairCache", + "params": ["1200"], + "id": 1 +} +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + "Status": "Started" + } +} +``` + + + +### `admin_nodeInfo` + +Returns networking information about the node. The information includes general information about the node and specific information from each running Ethereum sub-protocol (for example, `eth`). + +#### Parameters + +None + +#### Returns + +`result`: _object_ - node object with the following fields: + +- `enode`: _string_ - [enode URL](../../concepts/node-keys.md#enode-url) of the node + +- `listenAddr`: _string_ - host and port for the node + +- `name`: _string_ - client name + +- `id`: _string_ - [node public key](../../concepts/node-keys.md#node-public-key) + +- `ports`: _object_ - peer discovery and listening [ports](../../how-to/connect/manage-peers.md#port-configuration) + +- `protocols`: _object_ - list of objects containing information for each Ethereum sub-protocol + +:::note + +If the node is running locally, the host of the `enode` and `listenAddr` display as `[::]` in the result. When advertising externally, the external address displayed for the `enode` and `listenAddr` is defined by [`--nat-method`](../../how-to/connect/specify-nat.md). + +::: + + + +# curl HTTP request + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"admin_nodeInfo","params":[],"id":1}' http://127.0.0.1:8545 +``` + +# wscat WS request + +```bash +{"jsonrpc":"2.0","method":"admin_nodeInfo","params":[],"id":1} +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + "enode": "enode://87ec35d558352cc55cd1bf6a472557797f91287b78fe5e86760219124563450ad1bb807e4cc61e86c574189a851733227155551a14b9d0e1f62c5e11332a18a3@[::]:30303", + "listenAddr": "[::]:30303", + "name": "besu/v1.0.1-dev-0d2294a5/osx-x86_64/oracle-java-1.8", + "id": "87ec35d558352cc55cd1bf6a472557797f91287b78fe5e86760219124563450ad1bb807e4cc61e86c574189a851733227155551a14b9d0e1f62c5e11332a18a3", + "ports": { + "discovery": 30303, + "listener": 30303 + }, + "protocols": { + "eth": { + "config": { + "chainId": 2018, + "homesteadBlock": 0, + "daoForkBlock": 0, + "daoForkSupport": true, + "eip150Block": 0, + "eip155Block": 0, + "eip158Block": 0, + "byzantiumBlock": 0, + "constantinopleBlock": 0, + "constantinopleFixBlock": 0, + "ethash": { + "fixeddifficulty": 100 + } + }, + "difficulty": 78536, + "genesis": "0x43ee12d45470e57c86a0dfe008a5b847af9e372d05e8ba8f01434526eb2bea0f", + "head": "0xc6677651f16d07ae59cab3a5e1f0b814ed2ec27c00a93297b2aa2e29707844d9", + "network": 2018 + } + } + } +} +``` + + + +### `admin_peers` + +Returns networking information about connected remote nodes. + +#### Parameters + +None + +#### Returns + +`result`: _array_ of _objects_ - list of objects returned for each remote node, with the following fields. + +- `version`: _string_ - P2P protocol version + +- `name`: _string_ - client name + +- `caps`: _array_ of _strings_ - list of Ethereum sub-protocol capabilities + +- `network`: _object_ - local and remote addresses established at time of bonding with the peer (the remote address might not match the hex value for `port`; it depends on which node initiated the connection.) + +- `port`: _string_ - port on the remote node on which P2P discovery is listening + +- `id`: _string_ - node public key (excluding the `0x` prefix, the node public key is the ID in the [enode URL](../../concepts/node-keys.md#enode-url) `enode://@:`.) + +- `protocols`: _object_ - [current state of peer](../../how-to/connect/manage-peers.md#monitor-peer-connections) including `difficulty` and `head` (`head` is the hash of the highest known block for the peer.) + +- `enode`: _string_ - enode URL of the remote node + + + +# curl HTTP request + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"admin_peers","params":[],"id":1}' http://127.0.0.1:8545 +``` + +# wscat WS request + +```bash +{"jsonrpc":"2.0","method":"admin_peers","params":[],"id":1} +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": [ + { + "version": "0x5", + "name": "besu/v20.10.4-dev-0905d1b2/osx-x86_64/adoptopenjdk-java-11", + "caps": ["eth/62", "eth/63", "eth/64", "eth/65", "IBF/1"], + "network": { + "localAddress": "192.168.1.229:50115", + "remoteAddress": "168.61.153.255:40303" + }, + "port": "0x765f", + "id": "0xe143eadaf670d49afa3327cae2e655b083f5a89dac037c9af065914a9f8e6bceebcfe7ae2258bd22a9cd18b6a6de07b9790e71de49b78afa456e401bd2fb22fc", + "protocols": { + "eth": { + "difficulty": "0x1ac", + "head": "0x964090ae9277aef43f47f1b8c28411f162243d523118605f0b1231dbfdf3611a", + "version": 65 + } + }, + "enode": "enode://e143eadaf670d49afa3327cae2e655b083f5a89dac037c9af065914a9f8e6bceebcfe7ae2258bd22a9cd18b6a6de07b9790e71de49b78afa456e401bd2fb22fc@127.0.0.1:30303" + } + ] +} +``` + + + +### `admin_removePeer` + +Removes a [static node](../../how-to/connect/static-nodes.md). + +#### Parameters + +`enode`: _string_ - [enode URL](../../concepts/node-keys.md#enode-url) of peer to remove + +#### Returns + +`result`: _boolean_ - `true` if peer removed or `false` if peer not a [static node](../../how-to/connect/static-nodes.md) + + + +# curl HTTP request + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"admin_removePeer","params":["enode://f59c0ab603377b6ec88b89d5bb41b98fc385030ab1e4b03752db6f7dab364559d92c757c13116ae6408d2d33f0138e7812eb8b696b2a22fe3332c4b5127b22a3@127.0.0.1:30304"],"id":1}' http://127.0.0.1:8545 +``` + +# wscat WS request + +```bash +{"jsonrpc":"2.0","method":"admin_removePeer","params":["enode://f59c0ab603377b6ec88b89d5bb41b98fc385030ab1e4b03752db6f7dab364559d92c757c13116ae6408d2d33f0138e7812eb8b696b2a22fe3332c4b5127b22a3@127.0.0.1:30304"],"id":1} +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": true +} +``` + + + +## `DEBUG` methods + +The `DEBUG` API methods allow you to inspect and debug the network. The `DEBUG` API is a more verbose alternative to the [`TRACE` API](#trace-methods), and its main purpose is compatibility with tools such as [Remix](https://remix.ethereum.org/). Where these APIs overlap, we recommend using the [`TRACE` API](#trace-methods) for production use over the `DEBUG` API. Specifically, we recommend `trace_block` over `debug_traceBlock`, and `trace_transaction` over `debug_traceTransaction`. + +:::note + +The `DEBUG` API methods are not enabled by default for JSON-RPC. To enable the `DEBUG` API methods, use the [`--rpc-http-api`](../cli/options.md#rpc-http-api) or [`--rpc-ws-api`](../cli/options.md#rpc-ws-api) options. + +::: + +### `debug_accountAt` + +Returns account information at the specified index of the specified block. + +#### Parameters + +- `blockHashOrNumber`: _string_ - block hash or number at which to retrieve account information + +- `txIndex`: _number_ - transaction index at which to retrieve account information + +- `address`: _string_ - contract or account address for which to retrieve information + +#### Returns + +`result`: _object_ - account details object with the following fields: + +- `code`: _data_ - code for the account. Displays `0x0` if the address is an externally owned account. + +- `nonce`: _quantity_ - number of transactions made by the account before this one + +- `balance`: _quantity_ - balance of the account in Wei + +- `codehash`: _data_ - code hash for the account + +This example uses an externally owned account address for the `address` parameter. + + + +# curl HTTP request + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"debug_accountAt","params":["0xc8df1f061abb4d0c107b2b1a794ade8780b3120e681f723fe55a7be586d95ba6", 0, "0xbcde5374fce5edbc8e2a8697c15331677e6ebf0b"],"id":1}' http://127.0.0.1:8545 +``` + +# wscat WS request + +```json +{ + "jsonrpc": "2.0", + "method": "debug_accountAt", + "params": [ + "0xc8df1f061abb4d0c107b2b1a794ade8780b3120e681f723fe55a7be586d95ba6", + 0, + "0xbcde5374fce5edbc8e2a8697c15331677e6ebf0b" + ], + "id": 1 +} +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + "code": "0x0", + "nonce": "0x5", + "balance": "0xad78ebc5ac6200000", + "codehash": "0xc5d2460186f7233c927e7db2dcc703c0e500b653ca82273b7bfad8045d85a470" + } +} +``` + + + +This example uses a contract address for the `address` parameter. + + + +# curl HTTP request + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"debug_accountAt","params":["0x2b76b3a2fc44c0e21ea183d06c846353279a7acf12abcc6fb9d5e8fb14ae2f8c", 0, "0x0e0d2c8f7794e82164f11798276a188147fbd415"],"id":1}' http://127.0.0.1:8545 +``` + +# wscat WS request + +```json +{ + "jsonrpc": "2.0", + "method": "debug_accountAt", + "params": [ + "0x2b76b3a2fc44c0e21ea183d06c846353279a7acf12abcc6fb9d5e8fb14ae2f8c", + 0, + "0x0e0d2c8f7794e82164f11798276a188147fbd415" + ], + "id": 1 +} +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + "code": "0x608060405234801561001057600080fd5b506004361061002b5760003560e01c8063b27b880414610030575b600080fd5b61004a60048036038101906100459190610108565b61004c565b005b60606000806000604051935036600085376000803686885af490503d9150816000853e806000811461007d57610093565b60008311156100925761012085019350836040525b5b5060008114156100ec578473ffffffffffffffffffffffffffffffffffffffff167f410d96db3f80b0f89b36888c4d8a94004268f8d42309ac39b7bcba706293e099856040516100e3919061016e565b60405180910390a25b5050505050565b60008135905061010281610227565b92915050565b60006020828403121561011e5761011d610211565b5b600061012c848285016100f3565b91505092915050565b600061014082610190565b61014a818561019b565b935061015a8185602086016101de565b61016381610216565b840191505092915050565b600060208201905081810360008301526101888184610135565b905092915050565b600081519050919050565b600082825260208201905092915050565b60006101b7826101be565b9050919050565b600073ffffffffffffffffffffffffffffffffffffffff82169050919050565b60005b838110156101fc5780820151818401526020810190506101e1565b8381111561020b576000848401525b50505050565b600080fd5b6000601f19601f8301169050919050565b610230816101ac565b811461023b57600080fd5b5056fea2646970667358221220fdfb5c371055342507b8fb9ca7b0c234f79819bd5cb05c0d467fb605de979eb564736f6c63430008060033", + "nonce": "0x1", + "balance": "0x0", + "codehash": "0xf5f334d41776ed2828fc910d488a05c57fe7c2352aab2d16e30539d7726e1562" + } +} +``` + + + +### `debug_accountRange` + +[Retesteth](https://github.com/ethereum/retesteth/wiki/Retesteth-Overview) uses `debug_accountRange` to implement debugging. + +Returns the accounts for a specified block. + +#### Parameters + +- `blockHashOrNumber`: _string_ - block hash or number at which to retrieve account information + +- `txIndex`: _number_ - transaction index at which to retrieve account information + +- `address`: _string_ - address hash from which to start + +- `limit`: _integer_ - maximum number of account entries to return + +#### Returns + +`result`: _object_ - account details object with the following fields: + +- `addressMap`: _map_ of _strings_ to _strings_ - map of address hashes and account addresses + +- `nextKey`: _string_ - hash of the next address if any addresses remain in the state, otherwise zero + + + +# curl HTTP request + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"debug_accountRange","params":["12345", 0, "0", 5],"id":1}' http://127.0.0.1:8545 +``` + +# wscat WS request + +```json +{ + "jsonrpc": "2.0", + "method": "debug_accountRange", + "params": ["12345", 0, "0", 5], + "id": 1 +} +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + "addressMap": { + "0x005e5...86960": "0x0000000000000000000000000000000000000000", + "0x021fe...6ffe3": "0x0000000000000000000000000000000000000000", + "0x028e6...ab776": "0x0000000000000000000000000000000000000000", + "0x02cb5...bc4d8": "0x0000000000000000000000000000000000000000", + "0x03089...23fd5": "0x0000000000000000000000000000000000000000" + }, + "nextKey": "0x04242954a5cb9748d3f66bcd4583fd3830287aa585bebd9dd06fa6625976be49" + } +} +``` + + + +### `debug_batchSendRawTransaction` + +Sends a list of [signed transactions](../../how-to/send-transactions.md). This is used to quickly load a network with a lot of transactions. This does the same thing as calling [`eth_sendRawTransaction`](#eth_sendrawtransaction) multiple times. + +#### Parameters + +`data`: _string_ - signed transaction data array + +#### Returns + +`result`: _array_ of _objects_ - object returned for each transaction, with the following fields: + +- `index`: _string_ - index of the transaction in the request parameters array + +- `success`: _boolean_ - indicates whether or not the transaction has been added to the transaction pool + +- `errorMessage`: _string_ - (optional) error message + + + +# curl HTTP + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"debug_batchSendRawTransaction","params":["0xf868808203e882520894627306090abab3a6e1400e9345bc60c78a8bef57872386f26fc10000801ba0ac74ecfa0e9b85785f042c143ead4780931234cc9a032fce99fab1f45e0d90faa02fd17e8eb433d4ca47727653232045d4f81322619c0852d3fe8ddcfcedb66a43","0x416","0xf868018203e882520894627306090abab3a6e1400e9345bc60c78a8bef57872386f26fc10000801ca0b24ea1bee8fe36984c36acbf80979a4509f23fc17141851e08d505c0df158aa0a00472a05903d4cd7a811bd4d5c59cc105d93f5943f3393f253e92e65fc36e7ce0","0xf868808203e882520894627306090abab3a6e1400e9345bc60c78a8bef5787470de4df820000801ca0f7936b4de04792e3c65095cfbfd1399d231368f5f05f877588c0c8509f6c98c9a01834004dead527c8da1396eede42e1c60e41f38a77c2fd13a6e495479c729b99"],"id":1}' http://127.0.0.1:8545 +``` + +# wscat WS + +```bash +{"jsonrpc":"2.0","method":"debug_batchSendRawTransaction","params":["0xf868808203e882520894627306090abab3a6e1400e9345bc60c78a8bef57872386f26fc10000801ba0ac74ecfa0e9b85785f042c143ead4780931234cc9a032fce99fab1f45e0d90faa02fd17e8eb433d4ca47727653232045d4f81322619c0852d3fe8ddcfcedb66a43","0x416","0xf868018203e882520894627306090abab3a6e1400e9345bc60c78a8bef57872386f26fc10000801ca0b24ea1bee8fe36984c36acbf80979a4509f23fc17141851e08d505c0df158aa0a00472a05903d4cd7a811bd4d5c59cc105d93f5943f3393f253e92e65fc36e7ce0","0xf868808203e882520894627306090abab3a6e1400e9345bc60c78a8bef5787470de4df820000801ca0f7936b4de04792e3c65095cfbfd1399d231368f5f05f877588c0c8509f6c98c9a01834004dead527c8da1396eede42e1c60e41f38a77c2fd13a6e495479c729b99"],"id":1} +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": [ + { + "index": 0, + "success": true + }, + { + "index": 1, + "success": false, + "errorMessage": "Invalid raw transaction hex" + }, + { + "index": 2, + "success": true + }, + { + "index": 3, + "success": false, + "errorMessage": "TRANSACTION_REPLACEMENT_UNDERPRICED" + } + ] +} +``` + + + +### `debug_getBadBlocks` + +Returns a list of invalid blocks. This is used to detect and analyze consensus flaws. + +#### Parameters + +None + +#### Returns + +`result`: _array_ of _objects_ - list of [block objects](objects.md#block-object) + + + +# curl HTTP + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"debug_getBadBlocks","params":[],"id":1}' http://127.0.0.1:8545 +``` + +# wscat WS + +```bash +{"jsonrpc":"2.0","method":"debug_getBadBlocks","params":[],"id":1} +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": [ + { + "block": { + "number": "0xd", + "hash": "0x85c2edc1ca74b4863cab46ff6ed4df514a698aa7c29a9bce58742a33af07d7e6", + "mixHash": "0x0000000000000000000000000000000000000000000000000000000000000000", + "parentHash": "0x544a2f7a4c8defc0d8da44aa0c0db7c36b56db2605c01ed266e919e936579d31", + "nonce": "0x0000000000000000", + "sha3Uncles": "0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347", + "logsBloom": "0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000", + "transactionsRoot": "0x02c387e001cbe2a8296bfa2e18afbc3480d0e49588b05556148b0bf7c17dec41", + "stateRoot": "0x861ab7e868e3c23f84b7c4ed86b52a6a4f063633bc45ef29212c33459df84ea5", + "receiptsRoot": "0xccd2d33763dc0ac3fe02d4ecbbcd7d2bdc6f57db635ba31007184679303721d7", + "miner": "0x0000000000000000000000000000000000000000", + "difficulty": "0x1", + "totalDifficulty": "0x1", + "extraData": "0x00000000000000000000000000000000000000000000000000000000000000008c6a091f07e4ba3930f2f5fabbfc5b1c70986319096760ba200a6abc0d30e33c2d501702d1b58d7f75807bdbf981044557628611319121170b96466ec06bb3fd01", + "size": "0x3a0", + "gasLimit": "0xffffffffffff", + "gasUsed": "0x1a488", + "timestamp": "0x5f5b6824", + "uncles": [], + "transactions": [ + { + "blockHash": "0x85c2edc1ca74b4863cab46ff6ed4df514a698aa7c29a9bce58742a33af07d7e6", + "blockNumber": "0xd", + "from": "0xfe3b557e8fb62b89f4916b721be55ceb828dbd73", + "gas": "0x1a49e", + "gasPrice": "0x3e8", + "hash": "0xdd8cf045113754c306ba9ac8ac8786235e33bc5c087678084ef260a2a583f127", + "input": "0x608060405234801561001057600080fd5b5060c78061001f6000396000f3fe6080604052348015600f57600080fd5b506004361060325760003560e01c80636057361d146037578063b05784b8146062575b600080fd5b606060048036036020811015604b57600080fd5b8101908080359060200190929190505050607e565b005b60686088565b6040518082815260200191505060405180910390f35b8060008190555050565b6000805490509056fea26469706673582212208dea039245bf78c381278382d7056eef5083f7d243d8958817ef447e0a403bd064736f6c63430006060033", + "nonce": "0x0", + "to": null, + "transactionIndex": "0x0", + "value": "0x0", + "v": "0xf9d", + "r": "0xa7a15050302ca4b7d3842d35cdd3cbf25b2c48c0c37f96d78beb6a6a6bc4f1c7", + "s": "0x130d29294b2b6a2b7e89f501eb27772f7abf37bfa28a1ce300daade975589fca" + } + ] + }, + "hash": "0x85c2edc1ca74b4863cab46ff6ed4df514a698aa7c29a9bce58742a33af07d7e6", + "rlp": "0xf9039df9025ca0544a2f7a4c8defc0d8da44aa0c0db7c36b56db2605c01ed266e919e936579d31a01dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347940000000000000000000000000000000000000000a0861ab7e868e3c23f84b7c4ed86b52a6a4f063633bc45ef29212c33459df84ea5a002c387e001cbe2a8296bfa2e18afbc3480d0e49588b05556148b0bf7c17dec41a0ccd2d33763dc0ac3fe02d4ecbbcd7d2bdc6f57db635ba31007184679303721d7b9010000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000010d86ffffffffffff8301a488845f5b6824b86100000000000000000000000000000000000000000000000000000000000000008c6a091f07e4ba3930f2f5fabbfc5b1c70986319096760ba200a6abc0d30e33c2d501702d1b58d7f75807bdbf981044557628611319121170b96466ec06bb3fd01a00000000000000000000000000000000000000000000000000000000000000000880000000000000000f9013af90137808203e88301a49e8080b8e6608060405234801561001057600080fd5b5060c78061001f6000396000f3fe6080604052348015600f57600080fd5b506004361060325760003560e01c80636057361d146037578063b05784b8146062575b600080fd5b606060048036036020811015604b57600080fd5b8101908080359060200190929190505050607e565b005b60686088565b6040518082815260200191505060405180910390f35b8060008190555050565b6000805490509056fea26469706673582212208dea039245bf78c381278382d7056eef5083f7d243d8958817ef447e0a403bd064736f6c63430006060033820f9da0a7a15050302ca4b7d3842d35cdd3cbf25b2c48c0c37f96d78beb6a6a6bc4f1c7a0130d29294b2b6a2b7e89f501eb27772f7abf37bfa28a1ce300daade975589fcac0" + }, + { + "block": { + "number": "0x8", + "hash": "0x601a3ae9b6eceb2476d249e1cffe058ba3ff2c9c1b28b1ec7a0259fdd1d90121", + "mixHash": "0x0000000000000000000000000000000000000000000000000000000000000000", + "parentHash": "0x98ae440cd7b904d842daa6c263608969a3c8ce6a9acd6bd1f99b394f5f28a207", + "nonce": "0x0000000000000000", + "sha3Uncles": "0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347", + "logsBloom": "0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000", + "transactionsRoot": "0x8ee998cc699a1f9310a1079458780b3ebee8756f96a0905f5224b89d0eb17486", + "stateRoot": "0x140a9783291704223eb759e3a0db5471a520d349fc17ac2f77ff8582472e3bac", + "receiptsRoot": "0x2b5c77f6e7764d2468178fab7253346b9b8bb6a34b63946f6bdc2f5ad398bfc3", + "miner": "0x0000000000000000000000000000000000000000", + "difficulty": "0x2", + "totalDifficulty": "0x2", + "extraData": "0x00000000000000000000000000000000000000000000000000000000000000004d04551bdd9ae08af1fd661e49d4ab662c98c532c7ec0e4656a27e4de7d330af578ab1e4f5e49e085ff1d78673c7388ed9ccf017fbe89e53066bfa4018142c0701", + "size": "0x3a0", + "gasLimit": "0xffffffffffff", + "gasUsed": "0x1a4c9", + "timestamp": "0x5f5b6b80", + "uncles": [], + "transactions": [ + { + "blockHash": "0x601a3ae9b6eceb2476d249e1cffe058ba3ff2c9c1b28b1ec7a0259fdd1d90121", + "blockNumber": "0x8", + "from": "0xfe3b557e8fb62b89f4916b721be55ceb828dbd73", + "gas": "0x1a4c9", + "gasPrice": "0x3e8", + "hash": "0x675e336a4281b29c619dfd4ccfbd2f930f3728b20caf9e0067284aa3224e6758", + "input": "0x608060405234801561001057600080fd5b5060c78061001f6000396000f3fe6080604052348015600f57600080fd5b506004361060325760003560e01c80636057361d146037578063b05784b8146062575b600080fd5b606060048036036020811015604b57600080fd5b8101908080359060200190929190505050607e565b005b60686088565b6040518082815260200191505060405180910390f35b8060008190555050565b6000805490509056fea26469706673582212208dea039245bf78c381278382d7056eef5083f7d243d8958817ef447e0a403bd064736f6c63430006060033", + "nonce": "0x0", + "to": null, + "transactionIndex": "0x0", + "value": "0x0", + "v": "0xf9d", + "r": "0x2e30624c0305e64812e1d9e325ba6e50410314634b008edcb50f45be71fa0d4", + "s": "0x50e205faed23c219ba15610de2451d458cbd4221207b2168344cfc972a7973c0" + } + ] + }, + "hash": "0x601a3ae9b6eceb2476d249e1cffe058ba3ff2c9c1b28b1ec7a0259fdd1d90121", + "rlp": "0xf9039df9025ca098ae440cd7b904d842daa6c263608969a3c8ce6a9acd6bd1f99b394f5f28a207a01dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347940000000000000000000000000000000000000000a0140a9783291704223eb759e3a0db5471a520d349fc17ac2f77ff8582472e3baca08ee998cc699a1f9310a1079458780b3ebee8756f96a0905f5224b89d0eb17486a02b5c77f6e7764d2468178fab7253346b9b8bb6a34b63946f6bdc2f5ad398bfc3b9010000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000020886ffffffffffff8301a4c9845f5b6b80b86100000000000000000000000000000000000000000000000000000000000000004d04551bdd9ae08af1fd661e49d4ab662c98c532c7ec0e4656a27e4de7d330af578ab1e4f5e49e085ff1d78673c7388ed9ccf017fbe89e53066bfa4018142c0701a00000000000000000000000000000000000000000000000000000000000000000880000000000000000f9013af90137808203e88301a4c98080b8e6608060405234801561001057600080fd5b5060c78061001f6000396000f3fe6080604052348015600f57600080fd5b506004361060325760003560e01c80636057361d146037578063b05784b8146062575b600080fd5b606060048036036020811015604b57600080fd5b8101908080359060200190929190505050607e565b005b60686088565b6040518082815260200191505060405180910390f35b8060008190555050565b6000805490509056fea26469706673582212208dea039245bf78c381278382d7056eef5083f7d243d8958817ef447e0a403bd064736f6c63430006060033820f9da002e30624c0305e64812e1d9e325ba6e50410314634b008edcb50f45be71fa0d4a050e205faed23c219ba15610de2451d458cbd4221207b2168344cfc972a7973c0c0" + } + ] +} +``` + + + +### `debug_getRawBlock` + +Returns the [RLP encoding](https://ethereum.org/en/developers/docs/data-structures-and-encoding/rlp/) of the specified block. + +#### Parameters + +`blockNumber`: _string_ - hexadecimal or decimal integer representing a block number or one of the string tags `latest`, `earliest`, `pending`, `finalized`, or `safe`, as described in [block parameter](../../how-to/use-besu-api/json-rpc.md#block-parameter) + +#### Returns + +`result`: _object_ - RLP-encoded [block object](objects.md#block-object) + + + +# curl HTTP request + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"debug_getRawBlock","params":["0x32026E"],"id":1}' http://127.0.0.1:8545 +``` + +# wscat WS request + +```bash +{"jsonrpc":"2.0","method":"debug_getRawBlock","params":["0x32026E"],"id":1} +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": "0xf96096f90236a09f73691f6dabca4f0a99b05d0a701995506aa311dcaa9ce9833d6f4ca474c162a01dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d4934794c6e2459991bfe27cca6d86722f35da23a1e4cb97a078103ea8c47231886481d72ec1afae6eeb06c3773ce24a91323d5c9eed69d4cca0008992da2531db404f07b0871dd620a94ba346963e1b1c6dc7b00748e8593a1ea0b6c3890d9604434fc52f722848c84d1770add20cd75bbc28cdedff42940dbb56b90100200800000400000002000e0000000401000000440100000000c0400600000002000801000000040480020840048000000000400000000000000020004220000011002000000000000204000800000010010002000002000000000040a000000000000400020000010885000000000808000000008800001004002010020300005000000010002110410402000000000000000890000008000000000000000000020040000002000000000000810400000040006000004000004080020000000000000022001000000000000840400000000220250000000000080402000420000418000000000000000400040000004080040010200000000000108020020000808332026e8401c9c380833e3c3c846436f93899d883010b05846765746888676f312e32302e32856c696e7578a0112d8f15793e7df7f8dcdb21c891cff78c0d1839cb5b6dcd06116cdbb99536ae88000000000000000008a0cdb97712af6685bb9650d21d609525913293c48adda7c45990926daada335c9bf95c56f8ac82d51f8502540be4008303c9e294a68d4c1e3de1b721ad1356bbf827d6bc8cef304f80b844b1bb4d351300dbc7e12342566318001b83aefc9f20080000f3ef25472407fe9c9c69a1470000000242692bb4cd506c409651ab80eb3acfa54551d3dbc9af4493605d79871ba01e474fb147b16b9538d7a59a57738e406158d9cc306a9062b1b7a9f544c35abfa061aabb714c760f2243a16a024811679d402c8822e8b25dfd0038d84298fb5205b87502f87283aa36a754849502f900849502f9108302222794102554afa6b5dbccc86176faef2b2d854201756e8084e2bc7b43c001a04f2398f24bc950db1f5439de3cf6431ea277236595ae8dc5815c0cc671c9f97ca029898786a59c56f086fc0f7a16859f366cf46084add999fe137cbf43693712e8b87c02f87983aa36a7830293748459682f00850165a0bc008255f094fafb56bb5b37c3b0b0ee9d7c31f018aac91dfb778806f05b59d3b2000080c080a0b069dd8967533a773e592c26b1b36df0793d0b9f6eceba34da246f602c2fae58a002009dab32ab63a25b705d9a00e311f7cd5d85e73f9b2c03ffd0e5135c0bb2c6b89502f89283aa36a7018459682f008459682f0983011fec945b9fedd37f0b92e7e282b19cebcf06f57b77c60480a46a62784200000000000000000000000019a1fcc6fcc5832cd2db7704d75efbc800f5a742c001a0c65eb0e48090a8f8830de47f430b9ad11071a62a5db9555619a990d7e9b81738a05a6e826610a5b2ee529a22942ebcd3abd2a8a10228098c8158380e8fcceb962fb9028002f9027c83aa36a7178459682f008459682f0983017ac9942ab7c0ab9ab47fcf370d13058bfee28f2ec0940c880169964394fc8860b9020496e17852000000000000000000000000000000000000000000000000000000000000002000000000000000000000000000000000000000000000000000000000000000010000000000000000000000003aa4d7eb55ec2539f5305eb27ea42f6f90f168270000000000000000000000000000000000000000000000000000000000aa36a70000000000000000000000000000000000000000000000000000000000028c5c0000000000000000000000003aa4d7eb55ec2539f5305eb27ea42f6f90f168270000000000000000000000003aa4d7eb55ec2539f5305eb27ea42f6f90f168270000000000000000000000003aa4d7eb55ec2539f5305eb27ea42f6f90f16827000000000000000000000000000000000000000000000000016345785d8a00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000650cb3772886000000000000000000000000000000000000000000000000000000000000222e000000000000000000000000000000000000000000000000000000000000001a000000000000000000000000000000000000000000000000000000000000001c000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000c080a004f8666c8e5d0f3c7110994f624d24aa47a1327814289698c3e2777284a5cfdca04ff05f1b8c5beb58972d40e5a7b894d5e28ad2f15a3429c7d2bee6b6a9633730b9019f02f9019b83aa36a70b8459682f008459682f098303644f944284890d4acd0bcb017ece481b96fd4cb457cac88715c0f4db6e0ea0b90124ee1490b20000000000000000000000000000000000000000000000000000000000028c5c0000000000000000000000007847f2e0262512206333ffb200f6d9df2da319d40000000000000000000000001e8c104d068f22d351859cdbfe41a697a98e6ea20000000000000000000000000000000000000000000000000de0b6b3a764000000000000000000000000000000000000000000000000000000000000000222e00000000000000000000000000000000000000000000000000015c0f4db6e0ea00000000000000000000000007847f2e0262512206333ffb200f6d9df2da319d400000000000000000000000000000000000000000000000000000000000001000000000000000000000000000000000000000000000000000000000000000000c080a0e5270f6291acc162885656bedf64fbcb904c41951221dc0cbbbdca03bb33ce43a01f08c7ed3c231403b55f37a157d80e121b653baa810add8c02aea722631450dcb87c02f87983aa36a7830293758459682f00850165a0bc008255f0948d247f4fbbe81429d3d164a5c9ae0063210edbdc8806f05b59d3b2000080c080a0bb83dd6181c9a7ae3069af3bdf1820b5e556eaf99e385b8d7b3571321fb2966ba02ac193773704524adcd02824796df83407a42cdd81e786b591eba43c4ffc6c40b9028002f9027c83aa36a7048459682f008459682f0983017ac9942ab7c0ab9ab47fcf370d13058bfee28f2ec0940c880169964394fc8860b9020496e178520000000000000000000000000000000000000000000000000000000000000020000000000000000000000000000000000000000000000000000000000000000100000000000000000000000062d23ed77d0e5d0205edabe4ce3a27adc49ac6790000000000000000000000000000000000000000000000000000000000aa36a70000000000000000000000000000000000000000000000000000000000028c5c00000000000000000000000062d23ed77d0e5d0205edabe4ce3a27adc49ac67900000000000000000000000062d23ed77d0e5d0205edabe4ce3a27adc49ac67900000000000000000000000062d23ed77d0e5d0205edabe4ce3a27adc49ac679000000000000000000000000000000000000000000000000016345785d8a00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000650cb3772886000000000000000000000000000000000000000000000000000000000000222e000000000000000000000000000000000000000000000000000000000000001a000000000000000000000000000000000000000000000000000000000000001c000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000c001a0fc882968005f717a74a2c2fb345f691091cab084f4bd3934358741807bd5a66ea03f81c68d05d06bf851a6ef5ea6874557a221cbadde24f3fa51f777699b5d2804b8d802f8d583aa36a7822c0b8459682f008459682f098303534f943367dfa11e3148a07c2da773e1f65b155b0abe5680b864ad58bdd100000000000000000000000053844f9577c2334e541aec7df7174ece5df1fcf0000000000000000000000000e9e12c660e77a732940bab3c2cf385c843b834b800000000000000000000000000000000000000000006015d637c177581800000c001a0a292e7723d3c950aa8a557bd91dece34ec527d9efe2cc413d582dcd9fc6bf6eba03386ce6f58e862f329946bf32897f7df5d1c8f818fecfafc1223052fb251d97eb8b602f8b383aa36a7138459682f008459682f09832dc6c094ba175fdab00e7fcf603f43be8f68db7f4de9f3a980b844095ea7b300000000000000000000000084a0cc1ab353da6b7817947f7b116b8ea982c3d20000000000000000000000000000000000000000000000068f365aea1e440000c001a0968ed0274829918071d9cef28e1adbf1fd15ec76e5a4f809971e887b4c9f34b6a001ce26485bc7e3ea71fb99866bd43002b264b2ed80e10850203c2f07b78856bdb87c02f87983aa36a7830293768459682f00850165a0bc008255f0946d3b93db4e4078cf6541a68532d00705d9a4da618806f05b59d3b2000080c080a083c831630788e7ee57c87128d18582e29aa51f1f233e91d916c06d0750578156a0549b5a00477f3fb4d8fbf95ba3a636c3a14ff011c1bbf3a717e00d61735cbf34b87c02f87983aa36a7830293778459682f00850165a0bc008255f0940d3a7d69859a0dd6971d39703b15379e05ae2ec48806f05b59d3b2000080c001a0082660b5db2d3a8a58c0b863673ab27f7cfe4c049dcc52c76a00ab45b0358db5a05a7519a2d399cb534480383ac21262fbde2dd85241495d7832dee8bb02c49c87b87c02f87983aa36a7830293788459682f00850165a0bc008255f0941be13f64a2463fc7a76b4092c53328cc965a77fb8806f05b59d3b2000080c001a0e6ee9b85c3b729518524fdaeb25d47f89f6fc6c4d2c4df707187bef74d73f958a0756bbf4ab119805b77466957b5895c1d5bf422c5f65d8a06f7efd37dcb2c87afb87c02f87983aa36a7830293798459682f00850165a0bc008255f094a90b28fd6f8e46ac668fcb688414184a163e2cd28806f05b59d3b2000080c080a0d394dd43c58591e5dda8a7f3a2f4eae1bfd65655b9e9eec5facc6dcb39aa77baa002eeabf3fe9c0a56eae476d2f6452ea72e63a9c9b1180290b792883258f939f5b8f802f8f583aa36a7830283818459682f008459682f1082962494d0f723c6b2226df56fe41e63b9eaa66eb540bcb880b884abac047b000000000000000000000000000000000000000000000000000000000103e9f0f3471dc445d8f209ef546e0d20eaccc12ed0a5b4100007f57d9bc8638dacaf6480000000000000000000000000000000000000000000000000000000001d209b1ea11d77d1ab457eb3e2954cb2b98e77b5b07e2a4f48507af0adc61329ddc210c001a0efa10ab60f3bd1e7c4a8d52a275a568fbe2f5edc9e1eaf386299577ff9ddbd6ba06e62cf2f66b58f655ddd3eae47ce40408445b086f6ea858edb7bd847ee206207f86f82e6e582014482f618949ebf6b12e7e33b8672788e7b2b3330356f6f2c41880de0b6b3a7640000808401546d72a008d6be7aa21be0a43e08e960620f4c40c44010a743ead9919ef9423863c08b12a06a63a7caae4504ee5528e50387ca09974f7124035328a62d1085da2fee6618f9f86f82e1c382014482f618949c68eb31c4d00b94c3e3d4c2887946f8b076b24c880de0b6b3a7640000808401546d72a0c22d48d72c70ccf0a44d0950daf16741838f9333ee0bc5e05ff02b058da1e010a06a20c9f74cbc14c0d5bf3b3c38d3c33a5ace9194cddc2c533afb16459eaa7647f86f82e4cb82014482f61894d531e7aa3c0bee832aaff22642c7a3128d48a81a880de0b6b3a7640000808401546d72a01dbaeffc8e11964c06a722bae73e35bb5de55b8f959592868f2ff5fc13b69bd3a002acadc04665570a2032cdb616de15bdca79127f21302d62db5baf96ae4734e6f86e830176e381d882520894ad346e81c5b26fe563ab1ba2aa4ff811655882ca872386f26fc10000808401546d72a0b6de11598824e338100d5ebe70c0b0f4d6893fbb36f11ad55cf74b2f43afc5dda05101e65e7e84ea9edba6e5bf1a1e07028ae3fa5213240e812e57cf6b29080726b9235302f9234f83aa36a7830137d564748315f52194ac9251ee97ed8bef31706354310c6b020c35d87b80b922e48ed7b3be000000000000000000000000000000000000000000000000000000000001edc00000000000000000000000000000000000000000000000000000000000000040000000000000000000000000000000000000000000000000000000000000000300000000000000000000000000000000000000000000000000000000000000600000000000000000000000000000000000000000000000000000000000001fe000000000000000000000000000000000000000000000000000000000000020c00000000000000000000000000000000000000000000000000000000000001f60000000000000000000000000000000000000000000000000000000000000002000000000000000000000000000000000000000000000000000000000000000a000000000000000000000000000000000000000000000000000000000000002200000000000000000000000009d69394bd71906a235f9113cc04321f573958d3e00000000000000000000000000000000000000000000000000000000000005200000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000001edc00000000000000000000000000000000000000000000000000000000000320266d6b1b655f66cf8f99d35432492f8fbedfa97a2a48f0efaae65de6738e2594aa5000000000000000000000000000077770000000000000000000000000000000191c15235c348207e935e72b9151056a9661d73631d1e2c3f89ffddf8e74efe8a42ab8767076a555a049372055c846097c99e69c26ab0a24553d21c15de29ea900000000000000000000000000000000000000000000000000000000000000160000000000000000000000000000000000000000000000000000000000030ef2c000000000000000000000000000000000000000000000000000000006436f8d800000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000004d65822107fcfd520000000000000000000000000000000000000000000000000000000000000000ec15abee257256da1a964434000f59ddd45b1ce67d5df44f1c82fd5bfe95c3b31dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d493470000000000000000000000000000777700000000000000000000000000000001d4b5b35d93f51c8143f6a4cc3d7b320d37ce03989cd88c28601f4ea94cd6554249cff83e4dd8e99a8ef9004b2ac7518996f4784af1f9e52debb6223a697e9652530feda219f333e01f8cd0b31ee83b9c250ee51fde9718ef5fa305cbcd01901200200100002020000400000280000006004000c0020000000000000000000100000000029000000000000000090000000000008000200040000012004020000800000000240002400008000800000020000000001040000000000040824000000000000002040000400000002000080000000000000804000000001001000c84000208000000000180020000014000000000210100510008000082c0000000001200002000000024000008400000000220001800400000008010000052000200000200028000000000800000040200000110000010000010000001020000210004100002000000000900280000010008001000000018004000000020000010000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000001edc0000000000000000000000000000000000000000000000000000000000034bfbc00000000000000000000000000000000000000000000000000000000002ddb24000000000000000000000000000000000000000000000000000000006436f8d800000000000000000000000000000000000000000000000000000000000002e042ab8767076a555a049372055c846097c99e69c26ab0a24553d21c15de29ea900000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000003000000000000000000000000000000000000000000000000000000000000006000000000000000000000000000000000000000000000000000000000000016a000000000000000000000000000000000000000000000000000000000000017e000000000000000000000000000000000000000000000000000000000000016202bf20ff78727f38ef16e03bfb3d4895f35cc626f97ede7cc99f48aeff8661fe32015ea8d62ec7a79e01cd398e85867bafdcf55cb6a7121b6fef097f5f5656a5d11ddf336b6879926ea2ae425e91c748a553c9a496cbe2ab556a91689f75ee2b01ad3c43aa774b50a9d8411a9f65be42d6cde781db1a1949a1e886f868917997b2a7122720155935f15da0807d0054f1a4c3db2a92ec4124bf590ce7a16594f3f1812f260acb049d01ad534a937840a80c0f56fd9a54ca5a8628ed896d14a5f8b2570f5813e35c990656f6300a1a1849429135ada6337646248f6ea03a7f70ac426c1d805216d154ea5a8e5ff953bc04b71b049b4b5bd549b6b0cfa7f8b21dba72a3805c7093d8589f2d4c55b6211441041e8bd7916daed5093fcebd377c31e810a6499e6e26840e3afadc9b339c6abc86b7f89fc3559f4242d373a71389db20219195f6e13069701f6d539dcf63a049726cdd8cadc412d1c43cf3fc0095ae5e2157dc668bdb924d7d7afc2b4632ab8a0e4ef71941a0a6a65645f6cd8570302f90b98bbdd01be238dc07780ee9b93e22ab87f26170d7fc5531347fb9fadcb65dc2ca20442a70be9e785292d533fa9496308a7b1588b50b45c17ea765de525259f036edd3984782399b46793acd5abb9f49e38b309c2363aead57264ac1a44e6432b81127a0bfdc29f01bd04e7db2b2545ed8426d2fe9b3e561793ec8fc875f2a71f31c13d11b94f892bb9f96bd2931b66ffa5e22b104c549e7c0d5010e4e70e271d48c0bd6e4be68c920ea77af85d12eb155d9b25703eabbd0ede1909565a55f11fcba848e01c60438611958101321898e95c8fdc936d31389bdba8073b382e5b1e2cd25993ad31586d7525f165fb25a1cf8c22623f983c025d21f0e52ecfec5f0232a753addaad88340ca39f00e9722f35dd25fbe8fdd8846bfc0288215d0638004009396bfcd5e6eb0c587797ae8297decbca48b02407219b910ce163552ed230438292cec430007886beabe7cdf5c6f9c3740a3dd6c52ba88e6d652ce43f90044193c4a42335291795c2cc160dc68b6225edb425a88d27cae159f77df3a2241fbe809c8f1122d245bf439df0761bec97358b96d6653bc83702b559bde5a2d12f771a2a11bc9dc32580bc3ccf9dfacd0a5379587ac5160b45d333a85cde46810ad2875b406f00438aee245ecc63815528a185e9e2a029147db7fcffcb8875e5259f15c3e467de02e035891b131bc715e54e7e27a7acc437bb9f6f84fa4456aa016b3578a73ed8a4706efb935be8b6abe0697e46d878d9c74e274f2816d2fd88146b316731719e125d227e002af95aa13f468a9bae4ff41a4a6036ee7fc321b3249aed4dfb6e75089ec0656ee4e87e1fffefbd74edf55a20d752a85caccf583c0d9e2ef1040b4d36a8e992ad50ce1c4bd2b300b344ca881725c164886a5f8f18035f6e75e67a3eaa2064fc24ff79897edb624e1a67f34deb414d5efaf4c55d482da108aa2ab7504fd5d7f78d91da5c20230380ec013b910b01a26b8bed8a05a004d52db30b7fb01f16347692e9f19f303f48ea8cbbed2d3a3eb277ddf4e9ed8026af5ce92a618c8942caf28b3249044347e14e5c3c2ed5ec0f9cccf1d11a5b290c00773e12c25feafbcceeb8ae6c25a88c9657c627187af6fe0bfea0b3cc36c908a76f90e965bc4135c8596534f444c91aaaaaa6277985e36248bd53ef0f74f103eeac98ba92c5350e4a0c586c851ad25df982e16b2d408de37c687efc6915a41197df379614aa657ab5100627c47896b51b000cb95505bac77e4e440ecd1fe50252fc98f15ee41cafbf717e144da35f424e141639de04ebe5d333e9df8c06821c689d1ef2abbfd12e8a1edc059a9279db7ff44bac1962b5f7297da5c989528229e98a91a3a2e351f371dfa34d4c3676725baa5fa4696f67f4239b5fe1e3fa351d66aa5a2df992426d94ba049bbb4eea0ab22e3b9a7409f2b6719ede64353f4112e4da3919adc16dcd99c545966256493d2699ae529e365c20515d95c013ba2627576fb75a030ffd25b85ed3fc40dbbedbca54427f8dc2255c16b742b3e2b82e1bb634ae73a402927e6dc424d1908942b9b0f2cc17909ed050defe85d24a1986291facbb4ecf9b7ff66c27f8e771d28ec6866e3d24bc97e7be388013df8ba8f407b9147ed9b3581784003a22eeada55656d2be271afce06ef3fca32ac9b77b4f2420d60e892c95418b2a1b7d3dae2738a073ef105e66c08488e8a91e8ebdb5a10e979611bd29245c13cc4c0f5b33eedc5263edd6c27666e0c3f02161114120230511406f9f82102fd8c37c36d4e383e445df4afc6e7dbaa570cfe05b3f6038ec1b7932b70e7b068a2656173d241e8f20bb6be3a3a3767111aa6f459f84be961c2337f6e03ed3cc6c847a3683894288b471504cbdc43a78f856801a10a87c77322e36e0ca426ec67ad3a2a3b79bc5cb81928a79a67a0fb46bb967cbab73fd36022f92d920204de61717dde6a85b7bcf57584c11ce54ac92998f856bf042a01c5006f155ac97d6757728caceba5530eb745e72277723ad34268b34008a97a27c370e9bc006aeaca4ac36414f35aa41ff400f698623a447c949f7f004f3c3fdb09f2af3c96042e215f0d4bbb23fda72d4f01dd9a55dbdec930919715a23e2cd772a260e2b91324c244d88ce1b83c92dce1aa0e0c255b80ed9325dec0e677563984a1c559ddb4a544eadeb2a38e8ed7736174a30d2bee6e0b65f3766e0b7a4e4d8022dd9f82493a9b1fadd1907147ac29edeb8cf8c7c58fbfa9b82ed3d9f9f05bfc900e52e29a05ca8d445b5245b16928dd61800ebb63933d9c471c2fb38776459641e9debdc606abf6ccfdf8fb41da88ba0745d96fd4557a879fee82e33df32d18b18d7360529f89f3dea680a5cb0c6a7652ee38589e1997f3e64ce4db1d3c04cd628fc0fd6e7ef1944108d48eb742a28467fa4bca693dbc8f923945256da2a83222d172286c82b1949803c54409de4653f258d0cf4266c83d5675ca9b5b3a3fb322b9c493ed7bff0a6165babb19c94d9e2014b13b099f09894fbcf32959b9d4ce71ddf9d24dee8bc40d6be92ee6e1220d84d68ecf1a0424132315c0612802b477b0acabcf346b0ad5ea329ea72f4de7524530bc00ad36baeee835908655faecd350463484d31623127c09c6cec446a9ac9a53cb6841ca2a097ceef88e537e209880ffdcfd5033bc3f5a885c271e41ee332366345fa867780beb3c1d5eaa496ea0908c560e84b404afb45f69169d28348ca20bb4f5693db19304d154f60a91ec4e9255be05739f5dc7e0b420d4bde4b188a8520bf39202f81dd3e2f4adcc6f4b4be16880103e0ab232f509729c91ddf0006d6a099a769b38affb89d7489b3bf261106aec362c77acdbb0a71c3da369067eb0f2ee9866a0bbdc4ee41ae81a88d860f1784565b7b1cdd350e8e12241103ff9d57c86c368775530773bafc058cbcea6309bd6d9c144cf6657cac5084ac5fe63ef038a71b3d79e6b7a32cc70039e182052f5cd5e415128e9ab1f553f13c165ea122d089975c1daf617766e12d9f3abb2501571eefde182b767e4b63568d37a8c553671adcee2ee4c7c6d77493e4599cd70d002a718fe0d7c31b7df3893f8b9993c90d7d55eea1c38292f1eae3a7887cfd182977403d5c029a42809f2c6fb8d04aff1c60106ba36367ecca0699866e5ec922ebaeffc4e624d0cc2c748f9c446da0c293d8ba7a28125145ce0936a2dd47172c4502ccf050145fc0584ad8608ee8f6c34c3e718fa5ca616722c5b3549ddb5e2f6a96e82c3d706bf255afda0272c199da51f9a4a869ce8b164694f6ef7593ce08b4bb0afda822eed4a0a7863f532fc0a22de9de5d3456574021b711c42eb1c9190de35ea592568f8ba5528c0f5fadc38e10b14a89a1e49fba9a76ca2478dcca20f8a3c78bb3e1b9869b7375d0deb87819ce7209ad4d73d84a92d08d23649bb50ecb4a1763050b7860afb055461b3158647b453d7977bddde0fac9415327e7eb2ea373fc8abd6793f576e72a47c92d6f6e19fadfdf2c6912365b74929d9b483c19f5146ac5a8dd943caf50b2e0a95fb19066a63a71862a540b2e41731ea66697094e51d309589ce9d25a37c06c9a12839c4c08a050a3ff9e502514f20d573c610466ac5399e11b0153954428f25d16958ab48614d34f768991f84411c401e6900fb0dfaab4108db0ad42fc9ae0a255e60fa4d92747ddda47d07de9f847e7a2be289798c5d34924aae419abdc41d30fb095c6ccabe5c5d5be73ec6197371ea74e08f0583b21901bd748db5348282cabaf57d883f5c55311f1304d7fcd30a9f0b22f810b1a7f089860e4ca0f23ddce9a23d7167762734b10b995d5bd2cf3b31f8f24b18d0a2f7ce1101d3a32d18988f162e91ac94b0f521f24fa287b0d2b97c408079336b89af9e842cf31886c701018ba98d5b0eb0e6d41b67b499f4c466cb1412db0e5937f7ffa83426c9234c713096444d0fc65d1b45f166e54d2a54bc103de110669fbc34555a6d16714ca37651e976b06a7ee96d80af9ff50162016a998451e2ce5819f3346b1fcdf6fe9ff3ec8420d4860a9980ce28fd8c55660983a3fb02cbedb5c638a49e5cdf0b69b71d78e071f1200608e235e6ed0ee8fea5567be12018bcd026412db0538c28bcd4a9afe799d5c677298646943c4200a039d2fced71d985d188f84dfd3132b6a015c50b8a60d712a97c89e0cd7d3a1740244c1522b117dad1220463f5d4af1004c1a2ad6b5708d7d6b28f8ae1e1e7dd1b2d3798b8c2e27a3559c7202aa268099eb3bbdf7c42d0d20b47e5623dba8e6aa1392ff532113c32bd836f4160abb287aefe648aaff6bb0a23928f580347046b64babf354790704538c6ce83f117ac7e83e1e0f54054466cc82b2144cf135be31f24f1b224e2a956827c303b0d82964e284b968c5ebe97688e49ca793a4aba81a3d36eefd8c12e3ce9409be63c3a308636a7b296b804d8125b4f29068ef44d3f2a3c9eb13e61d6365bb96d6973e88a70757b1d9213511d357d252df58d1e848d534d9517165263e803855e8caf387579f1ff0e7e9c3c8e532a2025d8016b70a45c24a546f0b21acf38d16b27eae6466e22396097090291184a7719beb4a55beb89275c6893e01f2075d3b73e165c39335d34a5aa7b280386e30a6df9ba917e1dc6774e2edaa0c87e8f5fcf89306a6fdbcf8cf52cf25f5df473fe350325d510421546765acd00b34ef53e56b01445deea042282e7d6ce20c8f967204c26bda9f2596fa378dc611091ab6db9e1e8d4e9b5c1cc4c4d6ee2ad82b32d08f8cb5a9dd9b03f7aa754f2738ddf2dc0c3318974ff3810765917c251c74ce3d7132c26b5f2ede12a6f62f2e8ddecd5e0d02f99f2ed8ac15641c586d68e093fbe80cefd6a7dbdac6d43e261160807eb82fc2aea870a22b25148d256a083325a5b97bcf0187f748b6c0a1691867344efdd53809fb9edea57669c33780a4aa9e65149937817d3d845d9fccae1876575d5383d06adeacd0f3371209a30e1a9c98446174b0b98560652d0643f120bdabd5484435871b42ad0ce36aa8330c7edd26e64e89eb84e0c72a2c6e49fb24088ae2bdaf7ef07af9bfe381dd6a9ed430a553de1bad4dcefd5239b389090925a69e44e25800d9fccda11ff4e1e4d3049386397f1145c3595ab5115255bc1c1eabb379a37504eda27b1a103b88ae8f174e1d182e3dfbb0b8317d05d6e08c191661b04537421fd84057a9ff5a6eceb68c5bf1f0e356df6e93d936bb6bdccb42127cba43e7615d522242df13f08e5fa162a641430c1431a7d7181dec65202fb618a690c2bf3361d7dc689d5e4a97a550a9b17c8a5ada8f32db3f774e9ed047c02eb7d1ba7add29fa07ab90f290e77bd91ee9b5208b1fb19a37f29dd1a492fa32156a7d43146a336fe6144d19228f975c54ab304565269124e069e864873c0eef23f2e7b012e84ad0c71d76e1b23b8b9a0a66edcd59f4b203a9773ce26baee206254b49efb10cc48bad814b2e299bd478fd4bd8b1ae2c8bd99070b259a9e204e42fc5f65f9e25cb4e4a1a3b67872314fcaeede2abbbc6978660c3e685f6dccb53160d1f7517bbda54177495c23fcf45cdd66363a70a84f2699e239b5071c9e6cb19069f3e0be9f4390c8028ae9960851e34ea18ff88d36ee826c0a4db4e33e94f0ec6651a728a1a2b0c15b30a1783ad4b1d224d87264779a817d107d40c75b77c25addd7b7d6a8b73b2d551f125daed95786920c4130d2061178604f9604a0e2f1c6cdbf3066fd28bf276ee0aee379bc049bc8eba361f4052bd2a698da312c991015c0fbc43ea1d2e72426279fc5181851a15a2f4883018ab01ff8745625f388f05f5fa9abc5d87a710a1227322626115b60f781f4ddd91e205c1cca582a5e37e005396703375846be4f36fdb76c277dc1a2ff1f183cbafc6db485a562f4d08262a207844a3d12261fa0ac479abca76f417df42b037e611b1b6acfda94d5dacc620c3edf5744db24bcc41ef1722dc0e620f8a35c50585a7cecfc97f05bfec21f919420e62a9c4f28ea9585cc056aee08ed8891d077a9647d9c0b5c3141f8c517f13b05bf0a18b99111d2d6e7b4892e78fab35d882e4e153060f0c44cb946d20ad0897a34d2a24d3800b54acd68fdd797aa362560dcede6d12909948bd6f4726a20142eec9c6b78d224b2c24885490bfb492217c6809e0628164579d2c2c16a90f28aa5393ad44c45d4e1500fccdcc684023d7cac4e2cca889333f048cd9a29de018e958d00553c77c74ab50d974df5f654233fb923e809ef6ceabe6a860386603003cc376e90b8bee74f2477343a5ae923aea4ffe99a91b9d9289ddcc3ca316b026b3d369aca474b7941588fc6e9cb062528b10f13b90dd55afd64f7b0ab79163163ce02aed379af25740ac5e37c5628c0b868b7ccfed0ae521c964846f0287d3006952539b2dffaf891bd01fe98a1685e71536d7f33ae85775d11545eb379e0916be616206968605e5033267f6f79cc651c2ce71a790ae5cef19fea7604e479c0793f82db1f8e85bec40d8c6a2dbc9bf76d02a616aced611ae1a7a3756d87dab2855ca585d0048e1e4222ed9d6fa24e3e13677256fbb9959b965727c192696a11474a7f6a6b6c8efb649b1f601c76576f36996ec7a20eee84208232c20e8502903d4e303e4ad7139c654b7e5d2aa262d75672cbb4f653e62ed8e4d28835f7d6d0efb3f39c40558d9cbf19f250681a5c8a59143fec80d6a69d8a265835d6562ef248fa4ac508bd60c9283f6e731baa786828d0f7a635e1d14a448383c8b0243570df4a42799afe03143c227e3fcf0b1393bdf8bacbd26f1041d5e3112c84755942fac77981fe16f048cd882243a8787b09bdc38847a5a9cc9aaf4d30544181ff014dca8b2892c00a933333df6d8ef79041483f2d8c6416897ae7897ca1da85e8f0a493be4520595cd0dd7d32c87999e703704ba0ac7d8b444dba807746123100e2cf7573843a0a755eebad6045d2970a0ef8c9adddff093e79731d5e506f1c43318fb25144ff5fb63041574e89216ebe0ac75d7dcffc35d095691723493c94dcc11d4480bf3fe7b76ba53cae5b409c002f2d1bb5eab08ac993054ec297543798700fe3e2877a4a0cce53599a66eb4f1fef5cafc774277f0e694ebd7f8748fb5140735282e5e0b9bb35b8aeb098775a33820c9b8decad3ad6ce36f79c347dcc2c60a5442d2eab4368827acae1f0ccd52f0475fab95ac57c3c9d7c2649d355756140d5a1e8c6eab8b67a5c169cb899230c4be1dc702323f2b07ee1fcf5657361e250ccbe93bb403abd857eee4335e454e8485a3b055c908c957dca3f9a288299729216103089910386fb994285602ce12b04be1819a2c80394b2410767d9aabdb591e4c4dcd08d1d5bc1bcb532496ff1fc968ac3ff59bc7266d8ecbb67f34b681331685a99b781c9752dfe83d145bd4f3c8ec634f028e850e246aa81f1d03aef40d000000000000000000000000000000000000000000000000000000000000010cf90109b853f851a0bf32b9037b600aae3ecd3dd1838bc9f18ae1661f615cf3d70bc270b6c31f55fb80808080808080a0a2381991afea644ece5cba0d8d69f838f7b123d2e0057a54509e0c61e8b293028080808080808080b8b2f8b030b8adf8ab8301edbf808303d09094000077770000000000000000000000000000000180b844a0ca2d080000000000000000000000000000000000000000000000000000000000320266d6b1b655f66cf8f99d35432492f8fbedfa97a2a48f0efaae65de6738e2594aa5830518dca079be667ef9dcbbac55a06295ce870b07029bfcdb2dce28d959f2815b16f81798a05f3b41e975b46e86d5365943cfe25ae960fc2c7c1bb4eb0025eac5eb0bc6639c000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000001ebf901e8b853f851a0529f2d89256fc038782a4d70b40bf127de906cbe211e7acaa3e928e0fd5cf11d80808080808080a0b4f4d0be01c65da5308bab41d52d8a7c93a1693c170c44d1f619b8364d40e3428080808080808080b90190f9018d30b90189f901860183039445b9010000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000100000000000000000000000000000040000000000000000000000000000000000000000000000000000000000000008000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000100000000000000001000000000000000000000000000000000000000000800000000000000000000000000000000000200000000000000000000000000000000000000001000000000000000000000000000000400000000000000000000000000000000000000000000000000000000000000f87cf87a940000777700000000000000000000000000000001f842a058313b60ec6c5bfc381e52f0de3ede0faac3cdffea26f7d6bcc3d09b61018691a00000000000000000000000000000000000000000000000000000000000320266a0d6b1b655f66cf8f99d35432492f8fbedfa97a2a48f0efaae65de6738e2594aa500000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000adf8ab8301edbf808303d09094000077770000000000000000000000000000000180b844a0ca2d080000000000000000000000000000000000000000000000000000000000320266d6b1b655f66cf8f99d35432492f8fbedfa97a2a48f0efaae65de6738e2594aa5830518dca079be667ef9dcbbac55a06295ce870b07029bfcdb2dce28d959f2815b16f81798a05f3b41e975b46e86d5365943cfe25ae960fc2c7c1bb4eb0025eac5eb0bc6639c000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000189f901860183039445b9010000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000100000000000000000000000000000040000000000000000000000000000000000000000000000000000000000000008000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000100000000000000001000000000000000000000000000000000000000000800000000000000000000000000000000000200000000000000000000000000000000000000001000000000000000000000000000000400000000000000000000000000000000000000000000000000000000000000f87cf87a940000777700000000000000000000000000000001f842a058313b60ec6c5bfc381e52f0de3ede0faac3cdffea26f7d6bcc3d09b61018691a00000000000000000000000000000000000000000000000000000000000320266a0d6b1b655f66cf8f99d35432492f8fbedfa97a2a48f0efaae65de6738e2594aa50000000000000000000000000000000000000000000000c080a0ae5e67673b90f2d6802e8dba26aadb2e8b81e059d1611afd1908e743e3c0b75da004886b0ac3a810519aa2395bffdd94fbcfe4a2de989ec95d1aea0fcd09afd931b9235302f9234f83aa36a7830137d664748315f42594ac9251ee97ed8bef31706354310c6b020c35d87b80b922e48ed7b3be000000000000000000000000000000000000000000000000000000000001edc10000000000000000000000000000000000000000000000000000000000000040000000000000000000000000000000000000000000000000000000000000000300000000000000000000000000000000000000000000000000000000000000600000000000000000000000000000000000000000000000000000000000001fe000000000000000000000000000000000000000000000000000000000000020c00000000000000000000000000000000000000000000000000000000000001f60000000000000000000000000000000000000000000000000000000000000002000000000000000000000000000000000000000000000000000000000000000a000000000000000000000000000000000000000000000000000000000000002200000000000000000000000009d69394bd71906a235f9113cc04321f573958d3e00000000000000000000000000000000000000000000000000000000000005200000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000001edc10000000000000000000000000000000000000000000000000000000000320267dbfbf2c535ffc52117d4cc616b8d97bd07cdd8585ab67d9095c067e9de6d674400000000000000000000000000007777000000000000000000000000000000010012f20d5ba20a09e185d452c999c129d712b83c75480e2e029fc895986d361a781b2045b8b5226f9c1fd712d8b1a5f1faca84f5fcee87a7d1dd2b57f55617df000000000000000000000000000000000000000000000000000000000000016000000000000000000000000000000000000000000000000000000000004f9456000000000000000000000000000000000000000000000000000000006436f8e400000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000004d65822107fcfd520000000000000000000000000000000000000000000000000000000000000000bbe20eedcc0216c615d3a0550a5507bdb2f9912eba7b608300486e871a4e42491dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d4934700000000000000000000000000007777000000000000000000000000000000014852ab81d236f35c396d4836a6f82239f5672a4b6136ab9ebdd8669a9f9e831b87a26944e5c04f16b79426135ac11b155922c14178bf3d1ecbb1fb12ccc8119a22df5003de2d5956c745f9e825a8f0ca1bb1e265d4d431781b00765e0fe37280000000000004a00000000000800000020400004002001000000000000000010000000002800000000000100009000000000000a000000050000010004020000000000000000412000008002900000000000000000000000000000000820000000000000002000000400000000000080000000000000800000000001000040c0400000000000000010000000001400000000081000001800800008280000000001200002000000000000008440000000000001000000000004000000000000200200040028000000000000000000200000000000000000010000000020200290004100000000000000902080400010000001000000008000000000020000010000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000001edc100000000000000000000000000000000000000000000000000000000005364e600000000000000000000000000000000000000000000000000000000004456ed000000000000000000000000000000000000000000000000000000006436f8e400000000000000000000000000000000000000000000000000000000000002e0781b2045b8b5226f9c1fd712d8b1a5f1faca84f5fcee87a7d1dd2b57f55617df0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000003000000000000000000000000000000000000000000000000000000000000006000000000000000000000000000000000000000000000000000000000000016a000000000000000000000000000000000000000000000000000000000000017e000000000000000000000000000000000000000000000000000000000000016202bf20ff78727f38ef16e03bfb3d4895f35cc626f97ede7cc99f48aeff8661fe32015ea8d62ec7a79e01cd398e85867bafdcf55cb6a7121b6fef097f5f5656a5d11ddf336b6879926ea2ae425e91c748a553c9a496cbe2ab556a91689f75ee2b01ad3c43aa774b50a9d8411a9f65be42d6cde781db1a1949a1e886f868917997b21ad05b7c1eb0d208d17426c52831c6347a8db75b12bfeb2970c4dc6666e4eba0492d2ec318089b11ee7ec6087ab6a3df335770526cc0c1679b764d847b4ec1e303d400c12e690aa26a3771e5676e7ac95e2dc7a1b33be698f077c598f880d4203defa26ad36b84573e923af347475c7c7671be245e9859ca1db3c047faeee4b1c0e81d8a92915c2b94ff300e18f77f70ffec15631161e0bc3cdc9143c43422c208187652c1ec83c5d282e10587216eaf56689e5fe236f72c13eb9574afabc622a739cefbbe11aaa4e2e3d4c5415818914fe554a07be374f565d9bcebc0134940e8921b87bd4f6b42a6432e6e176be5ec82bb8eb6bdb7e4acc1f1e99725bd3ab2e3fa52e02c2741dfe6eddf5a3846dfd57f6a72e834faa048cb007826a293d9e163d47f9ea635871b25afcc3561dfce77b3a2604b3c8de90aa24916f41aed62d2e0c0d18f9c259bf614f1321c5b7cf7b5bd73cec408dd85f046bf36302e20f3603b7832071796022e893386de4e3b170135a591b1a44117240ba85876dba586b1f31c13d11b94f892bb9f96bd2931b66ffa5e22b104c549e7c0d5010e4e70e271d48c0bd6e4be68c920ea77af85d12eb155d9b25703eabbd0ede1909565a55f12f7e30e74b0329222f6067cad3b4324a80f570506985d729f7780955333f40e615f065023fb607d975d7a2b9f234137e72260d8f6b586baecf42819f8328dfb3304441f2c9e97d1fab9a3625073ac3d2bff6ba2f8d659cbc6f66e8d9afde1ef229ff39bac1ecd65eddc4953e2726a72daefa76f00d58e11c9a9ba3448fbe0d3a03db78d70ed9c574ddc45de5c73efdf3113ee70a4b42cea9884f85c1b995516912800abeb70f3022d5de6d9f49469161a36a6a309099ca43e388908635ed4ae825a14b7cf5213454a1f345497008ed417e5d33ef84c4934368b36f27606072192a1b43396f89647f0541dd25f55b42c5295d3ab2a22355664608b8dfec3c9d76045b27d8c2bdba7f376a44826bbf4044aed0d57068489fd32a2bf52f8613aa150185aafe655d2b86bf8867a6f7728c4133fb95776545b19767a0d7144f60f5ef038eac390d1cac6f9882211d7302137efc82b93b8f9c55db629f47a2c61931c21d01d5ad967c9dc6c1abfd496a74df2ac4714cfb027bc4d8c0153543ca663ded2af64f7396ed3b2ebd1976386814e94b7f7fcc3a19a4dd876288b905c381bc8f008de145083d6404890a863e1af1dd897aeef2516b20df50befb6c708c9728a22cb31d80b0e953aa71230d2462bb0668dd8701e11bc5240d85184f9298e2c5a3257b5dcc3e138df8b7d4162d6253fb5c21a65e952600c8764c613c6f43d22c861d4380cd688c286e9ffad6bb8582421fcab96b075769cf48b3160f056dfac4041b08287533a769bed0f08fdee9a16c5c8f414eb35830793c7b64341fef79dbc529a7b99f85d4e2e88b64954be967c5ee6386f9131b80b454ce70209f78f2101d0ca71da273735bcbcdc5ea5d3d54b607820b9bc852abb1b733cb7bb5018276d30c4c0a7f9ffcd318499a2041043494b82456ca8ac6f07678a8b770329b7c00f31e70e97ce48bc796570be27577e8986ee4c7fa51da44bdecfddfcf18686cbddc02ca206d9132d451ab55cce8069f631412ad2ae02b1a8245d31c0a65854d07370259f632fe253b2412c5a785148248d660d7cb6bef5240749d6ac4a4ac59384b27e7019c6cae15ef7c82e5a952f4da079b6205f9e16f3d3c84e94b490530c5b602d4bf5e9d34f2a785cdb7f7755d6d467a9d88071bbdf8c79195730db7d0b7872cbdcdabab02bd4b8487b726c5ce6492344ae7e900a21893e7b840b46380ba99278ce95322dc23daa97995d1149d425952913428c8ef8659dd2cc2895f12b08e0532a254fd5674fcac1b0992472ef75337d8d77f6fef3720d4b7b17302478c7d2e3b8dec7af4c681aba5e25d8aa3f4382b0082066c3f7a0b4e42c4637df90d9a1e2f3fd1cffa7e0d5577f5da89353521ed02cb1c39eb5746cef10ceb74c3fdba13199b42516ebfe29af40da64ad81b46b7bf04bf25994255c7a51f6839848810025bb52fe7500cf1ef628a07747894e3b73d53e6b2997d0654f1ffd0c070455400fd7e9d670984ac807a0f8131977ed1806fd3c0927c34b7b4dabf011d31e86b1b7932b70e7b068a2656173d241e8f20bb6be3a3a3767111aa6f459f84be961c2337f6e03ed3cc6c847a3683894288b471504cbdc43a78f856801a10a87c77322e36e0ca426ec67ad3a2a3b79bc5cb81928a79a67a0fb46bb967cbab73fd36022f92d920204de61717dde6a85b7bcf57584c11ce54ac92998f856bf042a01c5020d266b1ccea774955484405f58ad161251d879a87c43d5dbaecd976ac5d04dd2586d70031a86b0dcade14028f36a04508494c7a20e98b3b21f7765e7b3ef68f10960709e63eea35a26ff47424e18df8cc271ff3049262c855d6a131695a395f2ba2f1b039012ac8a2abdf6d9f6b0c432f0ae78b9bccb99f89759434477257ce1f44cc61e95b9c9843ec8efb17c640fc4c837ec125fb25323d3f0644615d21721607fee4d68e2dc9bd29f5b13fafe39b0710d0365dccda35e3c937aed1b6949b2a0a7523011eb706357b85e174376ea7cadbd01ed0dd1bc6a8e5a5a11bc6131f0661dd6365b13c6e2de50b98cba1cde58a921d19936c711424eb625b7c35cba01a0f7dfa8d6f86a2a02425ab48e2c28f8f2f61adbb744c221b9c4f35b16c749c227bcee1202e87537c7441f421c855ce87d858a679f09dcf814bfa1f26f7d9ce18f723d2f84d4b25ec60adbb6367e92270836d03c71ed43413767342a4fb8d6801b8755bf65e7947ed4459ad6486fc1cca1f1cc89df3d307f01d8ac68aa1d08d18aa35a46bf245589c599eddc6337e764c36426f7b7f5d2afde0a76fd3aa536d1a165f9f23cfc65866f574f2289aa5be056dd32c72a204ba8328dd9b0b4643790463484d31623127c09c6cec446a9ac9a53cb6841ca2a097ceef88e537e209880ffdcfd5033bc3f5a885c271e41ee332366345fa867780beb3c1d5eaa496ea09160db3fa7477a2fff436ecee95aa2d51ff42ca9d4fcf021b6e501410fd41098a1a8f6021636ece98c27bd74740b7280d3a5e13d9850fcf7f2118c4c91572ba5826fcc4b0837d0b394f6683cba38fa35a5e2bd242041533bd25939cc873d1f5852a2f57cb172eb17c2e3c351240a0b2b334978b90ac18041b09aead26649b1c1c019e41731e77c6b2211d7da94630507bad027561dc625b7e84094378e599a57b09eb32c2a67cf5f2f0bf9250e6da07b165f97dca10517e9f3fe3561d02ec83a722b544bd6e25ef27d9825d13651443c4d984d7e5d0fd70c2a7f983b3ae8c698d27a2a0bf2d35655f477adc99c56f48773922831746f8af58de941a020986ad7c23fb7d31c2f17f305174db26b40447e64c66216dce98e7a8316dd91dee468e602206a4d1d18fa7827f733037fa87dfc9c74c9df0960867087c776382b94db9420a19e5338e17e8a68cb7621f0b56984610bedd3d9b77dc5447cdb129ecc33596079cf206e93904368cae07f0d449e2095f8abd95f26603d2db047647babc8342200be0095aa5489fd18cd00a52f59b70ff04c4b1e572db76d08bad419abbabb00b9e485e3f017807c12b427b5e0e648cf7b16065e313c1c073ce354a5fc6812c02b8d4b6aa1168c575dad9875087fe9f61702309febfb99b895387cc1104c35e123b713019b5e51c320fc2521cdb5cfca20f617773fd46d3872128b87df6f66a21fb3fa16711245ab65eef629c5e6073efaff5b707657f4442f2eb2637fa71000f14fc691a71aacf902c0c1a1a5d7d8d351b8b3cad57acd0a9e47a1abdcaf2b70aed8b7370a6bb2bb4f3d679c4f9793e4b256deefaef1e6dbcdbb648b917e34822d833d2ac1614aebcf360d328d9271f27c52c93de4a9455ce6cd8d2140ebf6b21c9b172cf47556efc5dff9afb913e328a708292bfb65c96d668f4d0b3a9a21b222039156cba9980d6bf11efbd8dd893378e5dc1b323c57d8f702076c22d125d1489bab2553c5521631c35f7b5236007ce8f37012cace78d6eb39718904b5dc31ddcb6f4f175e52bcf6c6008f6f5a572925600194b9af7ae074dbf85119e3afd141b2ff2652a58f043e97f11b77997a9da1c96c18b5254a107f24e997a3ea61c2069b9d04d49bd1bcd2495b19bc71848f28bfb4f0346b682a1b474e040b056e60a32b5e8aa532103101cb45ca41c6a690c8688523b8566d507f29eb44fe2d2490e81f4343ca61c8783b83e40e3ce66532f186e9d09bd2667cf974a763072a910121aa5e86e151d92a868508b680f795bc30b4502769f41e3afef5f321be9ce2f1cff3eb3308d65aa0ed780cc889f605f35eb5e02ba772d08db2579f8561c61fa09a8e23ea1416fb95ca0c7e139ddd16f04b0c872499e44cb5a03868d6c5fa1300c19a96b8586b8f33bd760c6350713696b7d3236acb0eb35bde2e6378e9ef9b117b02290ead7824d42452e332f6ec95a7f871da9ebdf6ad02c959a1a36ba33ff0089a4f5217b7bfa5379a507b1e994fb7b8fef489f1f2cf6fdedf0e530635ef31faaa1a37457c445836376dc5cdefc7770fbbad8c326955655efe4ecde89bd2f1dc62a2551a45206fd7d42605aa1c0fc80476b741bd7df1f0f2db0fc387614240e78427bb3a8cbbaf9bb112da06ea6942335f88c65d42d17816136509ec39b51079b5eb2a8cd15c3d1fbc56dd72c3499c101e2fc9126e8f194c6c8006faef30917c5e535439c6b0d78be52a4d17a3a25d0878649b668db027eecbbafcfac7a612138c77d1511f9cc5e763eaddbad6d9d8770705ef7b4d062b4c6dc72f30d1d272dca8700ae03a4c6d2cc6a0a03f9bfb2615b2b294515ca80827ec9cbaa7746112530f5e70f236a641c05bbc8647dd130f02db3561f9dfaa1d687235bccb0498202af478a6070dfa49df99785a61eb5fe5f18777569c18b08d2042ae8639abbc225b832a2fbcd95ff43a3fee4fb2962983af8304ef995716110a7ad35c538697c109c01c427ca6cefef3a842fcf74b1c49a3f2da88b85fdb1d05e20cd567538942fa2f0ffbb5d2ff73d60d562d9a0a6894bec3d85a709b43e42ab64e2306cb96919e078b899f3155af56390d06ddc662afe8d2c91fc091e2c5cbbfab3fdb3f49423a5a5f7741f2d70c6736adc66e7c2caa89c6bbc678bb4b445a8a63d120867f01f164dc87adc853633ca7bd4b9d585c2a637d1469da612b5210476fc8d66f90029bdbf7fa5eddc8335cd23deb4bb47e1582e64a03dd021292d34435419af80af178cdfab0fb9374fa0fade48108cd3a571b814231784ac37c9f6071fc6ac0bb018595c9d8afbfcd6f31832b2581f7f7ce7c45d22817aab8ac6df0e0995e12dbd1595c3377b707b816c96ceb1893b9e7c747a577bb7540b89eb3ff7cac878a7a121a37b38fcd3248abfd24b50e25948dcaeff8c1c7ab8b745a93adb87cd54fca223dd940ef4d7eca9dd69243c74ea128ed624e52c7a2257f3950d0c7409d665d912495f8a8a2cf2482c1d51cd7793d3d31f32ffc24374d8606daa2a423931d97019ba2fd3ba773645b7fd01cf75e8201dd29f694a72136b585d940bff8867654223c28d0603d85fe4472d93ee30e35f46e27b8f40f9a9ad03992d9ff23305fc062c7d95971baae1ab074df88d41e09ec9752efff012c482e0cf9aea2b78cc26db146a278d584575ed615f5d168e6df7a832322da093f0aea706cee594207427d3005fd910843f3dc54b14f8b187e3b495b7474792743fc2e43f62bbc7fd50a76513f1fa4073b15a42d1e78a708134238f2521c749d086deeef512823b514aa64122b365efd51e11415de40826971c234d571c3e2a0507226c6ccc540e43a9aa32244b29784ac824c20d3d1b72dc7262f61cce4eefbe9a4ea4cb1061e4a71925aa13f31d6ce80bb7c56bf47b91cf107ab17168dd4fb60614757d7c7f4ebe0320692235fb502621ed9b15b9b3fa23aa1bf266a2a2c3f2386b52625e42e0cd85c37319e3266185419bcf6dea997e52ec8fca5887a68530002fcc5b3619e88d4dc9a918cc36bac2416ffa9b9734ac4e67a93a800f36d7aba4ecfed8d65f62cf6ad13d184a8c6406e3ba17b8aee6af0721ed091e1d225d044629a4ef5153c294a3e87e243e03bdcf6eaf7ee56d9d969a1f054d5774a7e2c363b160386b909c89717aa7015385f4ab8b6c97805c12c37d981ca945134cb1306d39a4d136b42c36d8aacd2c37575a11b17fa50ede8072d667f64bb55e3b54aff2c3c61782e442e088db7c1ce62287477132bef00c17e9992dd42f35b5e098eb97724fc4e697d75812635203abe8f96000d9553012be065980fb16d6d1c0c80457585c6eb699b0e8a6e36c1cd518dd1ffc517afcb9114a4ff629d06cd2f0be1495c4ee09243e96529e6c3a228c923ca2a703930ea94f7a5803645324ba9ea1a08e6c3241fe57a80bd24f780566342561189baed15e85ba9257b701d651754ff534e51279961ff379974e34010d80773b169a140e0ee7c5e2c0312c9dee46fb7b309710d448a43805c7eab513e84e346411b7145f77ff4ced7b32eb641528f78d88af0fe88e0840e9c16f2210e18c1da605bb04a4c963441c06fa839f722b0c67345168bc0fbb1c826f20472c7551a1327eae9eddbc24e63814fb81320cbc6f03488d64587f3e5f53c03db02cb15412e622f9ec9944643d4b5530b0cd4d577489d8ee499ecf2b74fb72423412aca8530fe53c3fc584ed8e39f900843ac73e36fb113c343cc197cd689a09e12f29203c1dfe839630f6932f3a29de81ba787f6044e70dff8981b71fe82f8a4d01f45770a53b090026a003b3e639eca0e6a1e5bdd0aad456e89d83012ea1f53e1a5fe848b33528f7195a7b0c36d4315f1b96b62d5603e87a13e12a97ec335e3922d4339d9575cb26d5691da78a738aa5c84aecc22a93033a6912f84360d13e2e23b0185bdc2cd331bd26ababcc91894935db5c7e1800b8a10db884a7614ceea91f38bbf623c5e7e7238eef06cd9fc9e43507c56e8d6212b7d03ef2db0dfceb040c0b206e1b7eee6ae564b15e4c02e9c3e4179d78bc68a9fbc2166cb8458342f218dc631705602b2ef1c6716dbc08f30810c9e2ab3ac7a03e300e9c21cd2a0240025ed5eda13e6daa246241669acfae65302dbca5c579d3b5c3a4c16a976209e22845337f9ca033329f849f3ccebc69ff01b301d99dbe9e79058fade67bf881c70283f41eaca130d1423e733ccd520f26ebbe8d304cbb8fa2f4bf67e2e041e5e90e840d5510d33a9f700219fbead699901ea3b3f8aa3d5ff0c028ceee5b5e711c29e7740bc98f4b78f15f2aa1e01449f1f15e68023861f540d2ae0541273c641914ea0e6abadbb2f11618bb678c8b7abff1f6d4e9f789706cdbd8dcc1acd4bbd506e42e928d134366d3f32d8caa4b86736bb065b1a3f89354835b7ba5ae1e53cc1bd9f5dfa3e0d49c0a0a8d32670c382712e30f8f4cb8fc980785fb6012df752e02c923d3f56f5764a41629646f9fd7641c8365f0917f85a64d0ba36179e2c2b3045d7b3c6ccfdb60cd5c365c43d88e231465c6616f7d2cab0db88cd79268e5ba0cecb98875958ee3827af7842e35d9cc89c3776e5640f2433a6afccf0e6fff9321e31802746639bf2bf77f375dd6799baa184b48815f24d3fca5d534dfe61d1306d15e97d3a320457ddd2239cc52fb31dbf98709cf090ae59afabbda6da75f4e1373a28bcadc2405e0a7f6dbf9a3e26511fc600a496b4623593213283a1fd33f000000000000000000000000000000000000000000000000000000000000010cf90109b853f851a04dd5a916917c46969db2e2093e73972daa52d5582e183eb0bd08362e7aca1dc280808080808080a03605d0d2c4765be29883abb71f1c4b162f9d6786835ccabb068a243ff819909f8080808080808080b8b2f8b030b8adf8ab8301edc0808303d09094000077770000000000000000000000000000000180b844a0ca2d080000000000000000000000000000000000000000000000000000000000320267dbfbf2c535ffc52117d4cc616b8d97bd07cdd8585ab67d9095c067e9de6d6744830518dba079be667ef9dcbbac55a06295ce870b07029bfcdb2dce28d959f2815b16f81798a05a4ba290d849b719839872aa1e6999ee672fff37d450956de85fe07c96f172d2000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000001ebf901e8b853f851a087eef6c6fab228bc280138441d870592a3910f042806b16f257faf5f1542f9a280808080808080a00ac60a3a5bafa4560edb7bd978a6b8980fa818c5edea7c010986328de4d9b4ba8080808080808080b90190f9018d30b90189f901860183039445b9010000000000000400000000000000000000040000000000000000000000000000000000000000000000000000000100000000000000000000000000000040000000000000000000000000000000000000000000000000000000000000008000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000100000000000000000080000000000000000000000000000000000000000800000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000400000000000000000000000000000000000000000000000000000000000000f87cf87a940000777700000000000000000000000000000001f842a058313b60ec6c5bfc381e52f0de3ede0faac3cdffea26f7d6bcc3d09b61018691a00000000000000000000000000000000000000000000000000000000000320267a0dbfbf2c535ffc52117d4cc616b8d97bd07cdd8585ab67d9095c067e9de6d674400000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000adf8ab8301edc0808303d09094000077770000000000000000000000000000000180b844a0ca2d080000000000000000000000000000000000000000000000000000000000320267dbfbf2c535ffc52117d4cc616b8d97bd07cdd8585ab67d9095c067e9de6d6744830518dba079be667ef9dcbbac55a06295ce870b07029bfcdb2dce28d959f2815b16f81798a05a4ba290d849b719839872aa1e6999ee672fff37d450956de85fe07c96f172d2000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000189f901860183039445b9010000000000000400000000000000000000040000000000000000000000000000000000000000000000000000000100000000000000000000000000000040000000000000000000000000000000000000000000000000000000000000008000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000100000000000000000080000000000000000000000000000000000000000800000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000400000000000000000000000000000000000000000000000000000000000000f87cf87a940000777700000000000000000000000000000001f842a058313b60ec6c5bfc381e52f0de3ede0faac3cdffea26f7d6bcc3d09b61018691a00000000000000000000000000000000000000000000000000000000000320267a0dbfbf2c535ffc52117d4cc616b8d97bd07cdd8585ab67d9095c067e9de6d67440000000000000000000000000000000000000000000000c080a0d86a71e8e531bae3b2a2e70d98e516ccf31b6583d936ffa31c3772ac265db828a0420f5a8067c7eec5214117647da149eaa4e7c78a10d8ee6fa62001ee1b680f9fb9060002f905fc83aa36a7823d3f647482a9c494bac000000000000000000000000000000000000380b905930001536cb8da3dd105e94414690798c7f100000000057b78da8ccffb3bd38b03c0f12199bb964b426dd6b091efd7dc3ad1a9d321d1713b2ea1189d39280b4791c5c858729090c3b6182ac75951eef74b38191686b35c4669656ca9dc5a0ce7e9399f7efffc03afe7fd6e7485887f6264e97e9856a6978b65c5db3b4ce57cf4812abeba0de10d0d6ee5a2cbc9885a2163a58d1895524adbfd86d795eac74ec74d783b599861bf4b7b3e6daf70b3ae0e5740c88a4dc15b893f76fe074a718bcead52fb2a06d6e5f1cf3ca344ad05dcf5ca10bd9bc2809cd8ecd40a2dd0e03200dadd8f921f0e9953a7e6d8c7dc99e60cf6fe81465175e0cf99b702ac6a13706e64ac349a1119796eb0b6e7d5ae48ad74a5c997d679ef9c637c619587cb98ecf88e620dacdc57701500c74e087533f978831a78bf3857cb6044a8c66e41645cdee74ac7cdac69a8484083eb003827ccfd6b92c77b7097a15f38a419f6f0578f3568465e6fb639f1a8d6e52e9d17a0413100ca8d08b210a2e5adb2bead3dfaada14b2513113802f3996daccac89014dafd1368700300053ad7daeea2a4d4d9e8502aa44337c6ff91165a25de84fe5273b2e5b7f4dda3a0410900125e7778d5c2a59a2ca2ce36bacc9e95812ae1b69a478fc7ecf5ded14b68a80a010d6e03e07137d5de8082773f8a422390cd0a592d81e6e623a42bc69547e6b343e1d9a14e64ac3486116e29a8315486a2324d93d3e33a8344ffdbc2655b76dbf72077e43c13961a6a52f0565f2000881576c7a113e7aa6e9a6ed4679014533f8d1bf80ff44ae5599813e80d2c1f2fd0a03400864952137916724a4504bb118ccaf9236f217a1e43c97e471397a3f86672226dd0e02e00d4dcbfe4dd250a97d0c830b3d93213fd048fed38ea8378018c726be68728e22c687037000e3bb6d2858fba82db877c2e28fa1e2cca4ce57b6bdfdba7513dcd2649da93544083d06f85c8f4d21559e8e7651dcaa0c3aafc4a691fdfb27f2f39ea08ea62feff43cf0d80061500b0b00cb246f3641d83f5c934c477ca641a5c545da8aa0e4662c4c5f26ee70525a04125006cf268fbdcaddb151168bf24d3fa2e09f7445d859ff9e5ba2fe71e7ef8861ba61834a80280ebddf1bc99e8d00ae5d2a0893d64774d4cea1bad7146fc964526b6c4617cd70a68500d00f7e8131b976b9537ab4e2b9c9cf086fcfd82e235cf6c6eabbf8030cc3fd1e395071a840120bfbd7fd4a54397eca0c0f7adc1231dd539950f508f92e237e3aeb91468c38d4083ea0068a89abd38178e2e9f67559758419b6908d48d58967547c9edfe98ba016e050734a809807957936c079272b238748593ee3a73f5c7647d0ece20a5c208769c484474aa2f192b6dcc780a770c9b40b42348219a34a746cb495f3f1efb710a816ac142121461c6f7bf82fb00b0dec5bfbcaa2e32983075c84989e439154bfc7df1d0549680a6c1a4999c18aa010dee074028fcade2995b7daec4562449ccbced0caf7a660f49ac4ea07d485b22348948a0415d001ce8e16f70ca5813141f7f7544586da1364d2f77dd8fbb7cc937c6d46136f93d68f000009a72d59e5a9bdf1de5e60bbb17358bc65e8ff1566fabad6d6eb42ef2781f6d6d40837000bce21c64847942319b4ac1c92b2ee02fe2bfbf43b685908b92a0c3cd25f21641a0417d0084138599419cf73489312bda0d53e1fa748e1f7927380961470ec9fda73b36978c953661c8065aaafe09fb847fb54e35b3c68f771b6953941b2b4e619b486d81761ee187bf828700301cd34529763c60738c12e1ccce6ddff8b8338cda8fda245e5d8d5613d20734408306df96bd65c7b8d5c27299269dd9335ef7cb1f3357145983f365ec2f933686fc6d77d0a01100ca3a3773d3f0a52559ee691776b714fedc8c7b2cd672c7065c295693d0616d37408318007c18e9a9f6e4929e20d8efd4c2428065720ed1938af8e5348c14b373b0a845d1063468d2f96f000000ffff86f9aa5001c001a08f785a1c8e4c549c415dd948da80f86e3aaabc4e7a784604b6362208e0fb6b85a011d366d57b6ad95cda2eb6b618704859b4d433ad7557cad177eff6f6bae578cbc0f90200df8345de7e8203e494e276bc378a527a8792b353cdca5b5e53263dfb9e82168cdf8345de7f8203e594e276bc378a527a8792b353cdca5b5e53263dfb9e82168cdf8345de8082062294388ea662ef2c223ec0b047d41bf3c0f362142ad58212cadf8345de8182062394388ea662ef2c223ec0b047d41bf3c0f362142ad58212cadf8345de828201949425c4a76e7d118705e7ea2e9b7d8c59930d8acd3b8212cadf8345de838201979425c4a76e7d118705e7ea2e9b7d8c59930d8acd3b8212cadf8345de848201999425c4a76e7d118705e7ea2e9b7d8c59930d8acd3b8212cadf8345de8582019a9425c4a76e7d118705e7ea2e9b7d8c59930d8acd3b8212cadf8345de8682019b9425c4a76e7d118705e7ea2e9b7d8c59930d8acd3b8212cadf8345de8782019e9425c4a76e7d118705e7ea2e9b7d8c59930d8acd3b820f08df8345de888201a29425c4a76e7d118705e7ea2e9b7d8c59930d8acd3b820f08df8345de898201a59425c4a76e7d118705e7ea2e9b7d8c59930d8acd3b820f08df8345de8a8201a89425c4a76e7d118705e7ea2e9b7d8c59930d8acd3b820f08df8345de8b8201a99425c4a76e7d118705e7ea2e9b7d8c59930d8acd3b820f08df8345de8c8201aa9425c4a76e7d118705e7ea2e9b7d8c59930d8acd3b820f08df8345de8d8201ac9425c4a76e7d118705e7ea2e9b7d8c59930d8acd3b820f08" +} +``` + + + +### `debug_getRawHeader` + +Returns the [RLP encoding](https://ethereum.org/en/developers/docs/data-structures-and-encoding/rlp/) of the header of specified block. + +#### Parameters + +`blockNumber`: _string_ - hexadecimal or decimal integer representing a block number or one of the string tags `latest`, `earliest`, `pending`, `finalized`, or `safe`, as described in [block parameter](../../how-to/use-besu-api/json-rpc.md#block-parameter) + +#### Returns + +`result`: _string_ - RLP-encoded block header or `error` + + + +# curl HTTP request + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"debug_getRawHeader","params":["0x32026E"],"id":1}' http://127.0.0.1:8545 +``` + +# wscat WS request + +```json +{ + "jsonrpc": "2.0", + "method": "debug_getRawHeader", + "params": ["0x32026E"], + "id": 1 +} +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": "0xf90236a09f73691f6dabca4f0a99b05d0a701995506aa311dcaa9ce9833d6f4ca474c162a01dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d4934794c6e2459991bfe27cca6d86722f35da23a1e4cb97a078103ea8c47231886481d72ec1afae6eeb06c3773ce24a91323d5c9eed69d4cca0008992da2531db404f07b0871dd620a94ba346963e1b1c6dc7b00748e8593a1ea0b6c3890d9604434fc52f722848c84d1770add20cd75bbc28cdedff42940dbb56b90100200800000400000002000e0000000401000000440100000000c0400600000002000801000000040480020840048000000000400000000000000020004220000011002000000000000204000800000010010002000002000000000040a000000000000400020000010885000000000808000000008800001004002010020300005000000010002110410402000000000000000890000008000000000000000000020040000002000000000000810400000040006000004000004080020000000000000022001000000000000840400000000220250000000000080402000420000418000000000000000400040000004080040010200000000000108020020000808332026e8401c9c380833e3c3c846436f93899d883010b05846765746888676f312e32302e32856c696e7578a0112d8f15793e7df7f8dcdb21c891cff78c0d1839cb5b6dcd06116cdbb99536ae88000000000000000008a0cdb97712af6685bb9650d21d609525913293c48adda7c45990926daada335c9b" +} +``` + + + +### `debug_getRawReceipts` + +Returns the [RLP encoding](https://ethereum.org/en/developers/docs/data-structures-and-encoding/rlp/) +of the transaction receipts of the specified block. + +#### Parameters + +`blockNumber`: _string_ - hexadecimal or decimal integer representing a block number or one of the string tags `latest`, +`earliest`, `pending`, `finalized`, or `safe`, as described in [block parameter](../../how-to/use-besu-api/json-rpc.md#block-parameter) + +#### Returns + +`result`: _object_ - array of RLP-encoded [transaction receipts](objects.md#transaction-receipt-object) + + + +# curl HTTP request + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"debug_getRawReceipts","params":["0x32026E"],"id":1}' http://127.0.0.1:8545 +``` + +# wscat WS request + +```bash +{"jsonrpc":"2.0","method":"debug_getRawReceipts","params":["0x32026E"],"id":1} +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": [ + "0xf901a60182c70eb9010000000000000000000000000000000000000000000000000000000000000000000000000001000000000000000000000000000000000000000000000000000002000000000000000000000008000000000000000000000000000000000040000000001000000000000000000000000000000000000000000000000010000000000000000000000000000000000000000000000000100000000000000400000000000000000000000000000000000000000000000000000000000000000000000000000002000000000100000000000000000000000800000000000000000000000000000000000000000000000000000000000000000000020000000000000000f89df89b947753cfad258efbc52a9a1452e42ffbce9be486cbf863a0ddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3efa00000000000000000000000000828d0386c1122e565f07dd28c7d1340ed5b3315a000000000000000000000000021849e99c31e3113a489d7eb0fd4d8c0edbe47afa00000000000000000000000000000000000000000000000000000000029b92700", + "0xf901a70183018e1cb9010000000000000000000000000000000000000000000000000000000000000000000000000001000000000000000000000000000000000000000000000000000002000000000000000000000008000000000000000000000000000000000040000000001000000000000000000000000000000000000000000000000010000000000000000000000000000000008000000000000000100000000000000000000000000000000000000000000000000000000000000000000000000000000000000200000002000000000000000000000000000000000000000000000040000000000000000000000000000000000000000000000000000000020000000000000000f89df89b947753cfad258efbc52a9a1452e42ffbce9be486cbf863a0ddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3efa00000000000000000000000000828d0386c1122e565f07dd28c7d1340ed5b3315a000000000000000000000000069cda9d6cc6ce05982d0b4fdf9480f2991f39b5aa00000000000000000000000000000000000000000000000000000000029b92700" + ] +} +``` + + + +### `debug_getRawTransaction` + +Returns the [RLP encoding](https://ethereum.org/en/developers/docs/data-structures-and-encoding/rlp/) +of the specified transaction. + +#### Parameters + +`transaction`: _string_ - 32-byte transaction hash + +#### Returns + +`result`: _object_ - RLP-encoded [transaction object](objects.md#transaction-object) + + + +# curl HTTP request + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"debug_getRawTransaction","params":["0x3a2fd1a5ea9ffee477f449be53a49398533d2c006a5815023920d1c397298df3"],"id":1}' http://127.0.0.1:8545 +``` + +# wscat WS request + +```bash +{"jsonrpc":"2.0","method":"debug_getRawTransaction","params":["0x3a2fd1a5ea9ffee477f449be53a49398533d2c006a5815023920d1c397298df3"],"id":1} +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": "0xf8678084342770c182520894658bdf435d810c91414ec09147daa6db624063798203e880820a95a0af5fc351b9e457a31f37c84e5cd99dd3c5de60af3de33c6f4160177a2c786a60a0201da7a21046af55837330a2c52fc1543cd4d9ead00ddf178dd96935b607ff9b" +} +``` + + + +### `debug_metrics` + +Returns metrics providing information on the internal operation of Besu. + +The available metrics might change over time. The JVM metrics might vary based on the JVM implementation used. + +The metric types are: + +- Timer + +- Counter + +- Gauge + +#### Parameters + +None + +#### Returns + +`result`: _object_ - metrics object + + + +# curl HTTP request + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"debug_metrics","params":[],"id":1}' http://127.0.0.1:8545 +``` + +# wscat WS request + +```json +{ "jsonrpc": "2.0", "method": "debug_metrics", "params": [], "id": 1 } +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + "jvm": { + "memory_bytes_init": { + "heap": 268435456, + "nonheap": 2555904 + }, + "threads_current": 41, + "memory_bytes_used": { + "heap": 696923976, + "nonheap": 63633456 + }, + "memory_pool_bytes_used": { + "PS Eden Space": 669119360, + "Code Cache": 19689024, + "Compressed Class Space": 4871144, + "PS Survivor Space": 2716320, + "PS Old Gen": 25088296, + "Metaspace": 39073288 + }, + ... + }, + "process": { + "open_fds": 546, + "cpu_seconds_total": 67.148992, + "start_time_seconds": 1543897699.589, + "max_fds": 10240 + }, + "rpc": { + "request_time": { + "debug_metrics": { + "bucket": { + "+Inf": 2, + "0.01": 1, + "0.075": 2, + "0.75": 2, + "0.005": 1, + "0.025": 2, + "0.1": 2, + "1.0": 2, + "0.05": 2, + "10.0": 2, + "0.25": 2, + "0.5": 2, + "5.0": 2, + "2.5": 2, + "7.5": 2 + }, + "count": 2, + "sum": 0.015925392 + } + } + }, + "blockchain": { + "difficulty_total": 3533501, + "announcedBlock_ingest": { + "bucket": { + "+Inf": 0, + "0.01": 0, + "0.075": 0, + "0.75": 0, + "0.005": 0, + "0.025": 0, + "0.1": 0, + "1.0": 0, + "0.05": 0, + "10.0": 0, + "0.25": 0, + "0.5": 0, + "5.0": 0, + "2.5": 0, + "7.5": 0 + }, + "count": 0, + "sum": 0 + }, + "height": 1908793 + }, + "peers": { + "disconnected_total": { + "remote": { + "SUBPROTOCOL_TRIGGERED": 5 + }, + "local": { + "TCP_SUBSYSTEM_ERROR": 1, + "SUBPROTOCOL_TRIGGERED": 2, + "USELESS_PEER": 3 + } + }, + "peer_count_current": 2, + "connected_total": 10 + } + } +} +``` + + + +### `debug_replayBlock` + +Re-imports the block matching the specified block number, by rolling the head of the local chain back to the block right before the specified block, then importing the specified block. + +#### Parameters + +`blockNumber`: _string_ - hexadecimal or decimal integer representing a block number or one of the string tags `latest`, `earliest`, `pending`, `finalized`, or `safe`, as described in [block parameter](../../how-to/use-besu-api/json-rpc.md#block-parameter) + +#### Returns + +`result`: _string_ - `Success` or `error` + + + +# curl HTTP request + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"debug_replayBlock","params":["0x1"],"id":1}' http://127.0.0.1:8545 +``` + +# wscat WS request + +```json +{ "jsonrpc": "2.0", "method": "debug_replayBlock", "params": ["0x1"], "id": 1 } +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": "Success" +} +``` + + + +### `debug_resyncWorldstate` + +Triggers a re-synchronization of the world state while retaining imported blocks. This is useful if there are world state database inconsistencies (for example, Bonsai database issues). + +#### Parameters + +None + +#### Returns + +`result`: _string_ - `Success` or `error` + + + +# curl HTTP request + +```bash + curl -X POST --data '{"jsonrpc":"2.0","method":"debug_resyncWorldstate","params":[],"id":1}' http://127.0.0.1:8545 +``` + +# wscat WS request + +```json +{ "jsonrpc": "2.0", "method": "debug_resyncWorldstate", "params": [], "id": 1 } +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": "Success" +} +``` + + + +### `debug_setHead` + +Sets the current head of the local chain to the block matching the specified block number. + +#### Parameters + +`blockNumber`: _string_ - hexadecimal or decimal integer representing a block number or one of the string tags `latest`, `earliest`, `pending`, `finalized`, or `safe`, as described in [block parameter](../../how-to/use-besu-api/json-rpc.md#block-parameter) + +#### Returns + +`result`: _string_ - `Success` or `error` + + + +# curl HTTP request + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"debug_setHead","params":["0x1"],"id":1}' http://127.0.0.1:8545 +``` + +# wscat WS request + +```json +{ "jsonrpc": "2.0", "method": "debug_setHead", "params": ["0x1"], "id": 1 } +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": "Success" +} +``` + + + +### `debug_standardTraceBlockToFile` + +Generates files containing the block trace. A separate file is generated for each transaction in the block. + +You can also specify a trace file for a specific transaction in a block. + +Use [`debug_standardTraceBadBlockToFile`](#debug_standardtracebadblocktofile) to view the trace for an invalid block. + +#### Parameters + +`blockHash`: _string_ - block hash + +`txHash`: _string_ - (optional) transaction hash; if omitted, a trace file is generated for each transaction in the block. + +`disableMemory`: _boolean_ - (optional) specifies whether to capture EVM memory during the trace; defaults to `true` + +#### Returns + +`result`: _string_ - location of the generated trace files + + + +# curl HTTP request + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"debug_standardTraceBlockToFile","params":["0x2dc0b6c43144e314a86777b4bd4f987c0790a6a0b21560671d221ed81a23f2dc", { +"txHash": "0x4ff04c4aec9517721179c8dd435f47fbbfc2ed26cd4926845ab687420d5580a6", "disableMemory": false}], "id":1}' http://127.0.0.1:8545 +``` + +# wscat WS request + +```json +{ + "jsonrpc": "2.0", + "method": "debug_standardTraceBlockToFile", + "params": [ + "0x2dc0b6c43144e314a86777b4bd4f987c0790a6a0b21560671d221ed81a23f2dc", + { + "txHash": "0x4ff04c4aec9517721179c8dd435f47fbbfc2ed26cd4926845ab687420d5580a6", + "disableMemory": false + } + ], + "id": 1 +} +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": [ + "/Users/me/mynode/goerli/data/traces/block_0x2dc0b6c4-4-0x4ff04c4a-1612820117332" + ] +} +``` + + + +### `debug_standardTraceBadBlockToFile` + +Generates files containing the block trace of invalid blocks. A separate file is generated for each transaction in the block. + +Use [`debug_standardTraceBlockToFile`](#debug_standardtraceblocktofile) to view the trace for a valid block. + +#### Parameters + +`blockHash`: _string_ - block hash + +#### Returns + +`result`: _string_ - location of the generated trace files + + + +# curl HTTP request + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"debug_standardTraceBadBlockToFile","params":["0x53741e9e94791466d117c5f9e41a2ed1de3f73d39920c621dfc2f294e7779baa"], "id":1}' http://127.0.0.1:8545 +``` + +# wscat WS request + +```json +{ + "jsonrpc": "2.0", + "method": "debug_standardTraceBadBlockToFile", + "params": [ + "0x53741e9e94791466d117c5f9e41a2ed1de3f73d39920c621dfc2f294e7779baa" + ], + "id": 1 +} +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": [ + "/Users/me/mynode/goerli/data/traces/block_0x53741e9e-0-0x407ec43d-1600951088172" + ] +} +``` + + + +### `debug_storageRangeAt` + +[Remix](https://remix.ethereum.org/) uses `debug_storageRangeAt` to implement debugging. Use the _Debugger_ tab in Remix instead of calling `debug_storageRangeAt` directly. + +Returns the contract storage for the specified range. + +#### Parameters + +- `blockHash`: _string_ - block hash + +- `txIndex`: _number_ - transaction index from which to start + +- `address`: _string_ - contract address + +- `startKey`: _string_ - start key + +- `limit`: _number_ - number of storage entries to return + +#### Returns + +`result`: _object_ - [range object](objects.md#range-object). + + + +# curl HTTP request + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"debug_storageRangeAt","params":["0x2b76b3a2fc44c0e21ea183d06c846353279a7acf12abcc6fb9d5e8fb14ae2f8c",0,"0x0e0d2c8f7794e82164f11798276a188147fbd415","0x0000000000000000000000000000000000000000000000000000000000000000",1], "id":1}' http://127.0.0.1:8545 +``` + +# wscat WS request + +```json +{ + "jsonrpc": "2.0", + "method": "debug_storageRangeAt", + "params": [ + "0x2b76b3a2fc44c0e21ea183d06c846353279a7acf12abcc6fb9d5e8fb14ae2f8c", + 0, + "0x0e0d2c8f7794e82164f11798276a188147fbd415", + "0x0000000000000000000000000000000000000000000000000000000000000000", + 1 + ], + "id": 1 +} +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + "storage": { + "0x290decd9548b62a8d60345a988386fc84ba6bc95484008f6362f93160ef3e563": { + "key": null, + "value": "0x0000000000000000000000000000000000000000000000000000000000000001" + } + }, + "nextKey": "0xb10e2d527612073b26eecdfd717e6a320cf44b4afac2b0732d9fcbe2b7fa0cf6" + } +} +``` + +::: + +### `debug_traceTransaction` + +[Remix](https://remix.ethereum.org/) uses `debug_traceTransaction` to implement debugging. Use the _Debugger_ tab in Remix instead of calling `debug_traceTransaction` directly. + +Reruns the transaction with the same state as when the transaction executed. + +#### Parameters + +- `transactionHash`: _string_ - transaction hash + +- `options`: _object_ - request options object with the following fields (all optional and default to `false`): + + - `disableStorage`: _boolean_ - `true` disables storage capture. + + - `disableMemory`: _boolean_ - `true` disables memory capture. + + - `disableStack` : _boolean_ - `true` disables stack capture. + +#### Returns + +`result`: _object_ - [trace object](objects.md#trace-object) + + + +# curl HTTP request + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"debug_traceTransaction","params":["0x2cc6c94c21685b7e0f8ddabf277a5ccf98db157c62619cde8baea696a74ed18e",{"disableStorage":true}],"id":1}' http://127.0.0.1:8545 +``` + +# wscat WS request + +```json +{ + "jsonrpc": "2.0", + "method": "debug_traceTransaction", + "params": [ + "0x2cc6c94c21685b7e0f8ddabf277a5ccf98db157c62619cde8baea696a74ed18e", + { "disableStorage": true } + ], + "id": 1 +} +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + "gas": 21000, + "failed": false, + "returnValue": "", + "structLogs": [ + { + "pc": 0, + "op": "STOP", + "gas": 0, + "gasCost": 0, + "depth": 1, + "stack": [], + "memory": [], + "storage": null + } + ] + } +} +``` + + + +### `debug_traceBlock` + +Returns full trace of all invoked opcodes of all transactions included in the block. + +#### Parameters + +- `block`: _string_ - RLP of the block + +- `options`: _object_ - request options object with the following fields (all optional and default to `false`): + + - `disableStorage`: _boolean_ - `true` disables storage capture. + + - `disableMemory`: _boolean_ - `true` disables memory capture. + + - `disableStack` : _boolean_ - `true` disables stack capture. + +#### Returns + +`result`: _object_ - [trace object](objects.md#trace-object) + + + +# curl HTTP request + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"debug_traceBlock","params":["0xf90277f90208a05a41d0e66b4120775176c09fcf39e7c0520517a13d2b57b18d33d342df038bfca01dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d4934794e6a7a1d47ff21b6321162aea7c6cb457d5476bcaa00e0df2706b0a4fb8bd08c9246d472abbe850af446405d9eba1db41db18b4a169a04513310fcb9f6f616972a3b948dc5d547f280849a87ebb5af0191f98b87be598a0fe2bf2a941abf41d72637e5b91750332a30283efd40c424dc522b77e6f0ed8c4b9010000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000860153886c1bbd82b44382520b8252088455c426598b657468706f6f6c2e6f7267a0b48c515a9dde8d346c3337ea520aa995a4738bb595495506125449c1149d6cf488ba4f8ecd18aab215f869f86780862d79883d2000825208945df9b87991262f6ba471f09758cde1c0fc1de734827a69801ca088ff6cf0fefd94db46111149ae4bfc179e9b94721fffd821d38d16464b3f71d0a045e0aff800961cfce805daef7016b9b675c137a6a41a548f7b60a3484c06a33ac0"],"id":1}' http://127.0.0.1:8545 +``` + +# wscat WS request + +```json +{ + "jsonrpc": "2.0", + "method": "debug_traceBlock", + "params": [ + "0xf90277f90208a05a41d0e66b4120775176c09fcf39e7c0520517a13d2b57b18d33d342df038bfca01dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d4934794e6a7a1d47ff21b6321162aea7c6cb457d5476bcaa00e0df2706b0a4fb8bd08c9246d472abbe850af446405d9eba1db41db18b4a169a04513310fcb9f6f616972a3b948dc5d547f280849a87ebb5af0191f98b87be598a0fe2bf2a941abf41d72637e5b91750332a30283efd40c424dc522b77e6f0ed8c4b9010000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000860153886c1bbd82b44382520b8252088455c426598b657468706f6f6c2e6f7267a0b48c515a9dde8d346c3337ea520aa995a4738bb595495506125449c1149d6cf488ba4f8ecd18aab215f869f86780862d79883d2000825208945df9b87991262f6ba471f09758cde1c0fc1de734827a69801ca088ff6cf0fefd94db46111149ae4bfc179e9b94721fffd821d38d16464b3f71d0a045e0aff800961cfce805daef7016b9b675c137a6a41a548f7b60a3484c06a33ac0" + ], + "id": 1 +} +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + "gas": 21000, + "failed": false, + "returnValue": "", + "structLogs": [ + { + "pc": 0, + "op": "STOP", + "gas": 0, + "gasCost": 0, + "depth": 1, + "stack": [], + "memory": [], + "storage": null + } + ] + } +} +``` + + + +### `debug_traceBlockByHash` + +Returns full trace of all invoked opcodes of all transactions included in the block. + +#### Parameters + +- `blockHash`: _string_ - block hash + +- `options`: _object_ - request options object with the following fields (all optional and default to `false`): + + - `disableStorage`: _boolean_ - `true` disables storage capture. + + - `disableMemory`: _boolean_ - `true` disables memory capture. + + - `disableStack` : _boolean_ - `true` disables stack capture. + +#### Returns + +`result`: _array_ of _objects_ - list of [trace objects](objects.md#trace-object) + + + +# curl HTTP request + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"debug_traceBlockByHash","params":["0xaceb3b2c9b25b0589230873921eb894b28722011b8df63977145517d754875a5"], "id":1}' http://127.0.0.1:8545 +``` + +# wscat WS request + +```json +{ + "jsonrpc": "2.0", + "method": "debug_traceBlockByHash", + "params": [ + "0xaceb3b2c9b25b0589230873921eb894b28722011b8df63977145517d754875a5" + ], + "id": 1 +} +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": [ + { + "gas": 21000, + "failed": false, + "returnValue": "", + "structLogs": [ + { + "pc": 0, + "op": "STOP", + "gas": 0, + "gasCost": 0, + "depth": 1, + "stack": [], + "memory": [], + "storage": {}, + "reason": null + } + ] + } + ] +} +``` + + + +### `debug_traceBlockByNumber` + +Returns full trace of all invoked opcodes of all transactions included in the block. + +#### Parameters + +- `blockNumber`: _string_ - hexadecimal or decimal integer representing a block number or one of the string tags `latest`, `earliest`, `pending`, `finalized`, or `safe`, as described in [block parameter](../../how-to/use-besu-api/json-rpc.md#block-parameter) + +- `options`: _object_ - request options object with the following fields (all optional and default to `false`): + + - `disableStorage`: _boolean_ - `true` disables storage capture. + + - `disableMemory`: _boolean_ - `true` disables memory capture. + + - `disableStack` : _boolean_ - `true` disables stack capture. + +#### Returns + +`result`: _array_ of _objects_ - list of [trace objects](objects.md#trace-object) + + + +# curl HTTP request + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"debug_traceBlockByNumber","params":["0x7224",{"disableStorage":true}], "id":1}' http://127.0.0.1:8545 +``` + +# wscat WS request + +```json +{ + "jsonrpc": "2.0", + "method": "debug_traceBlockByNumber", + "params": ["0x7224", { "disableStorage": true }], + "id": 1 +} +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": [ + { + "gas": 21000, + "failed": false, + "returnValue": "", + "structLogs": [ + { + "pc": 0, + "op": "STOP", + "gas": 0, + "gasCost": 0, + "depth": 1, + "stack": [], + "memory": [], + "storage": null, + "reason": null + } + ] + } + ] +} +``` + + + +## `ETH` methods + +The `ETH` API methods allow you to interact with the blockchain. + +:::note + +Methods with an equivalent [GraphQL](../../how-to/use-besu-api/graphql.md) query include a GraphQL request and result in the method example. The parameter and result descriptions apply to the JSON-RPC requests. The GraphQL specification is defined in the [schema]. + +::: + +### `eth_accounts` + +Returns a list of account addresses a client owns. + +:::note + +This method returns an empty object because Besu [doesn't support key management](../../how-to/send-transactions.md) inside the client. + +To provide access to your key store and and then sign transactions, use [EthSigner](http://docs.ethsigner.consensys.net/en/latest/) with Besu. + +::: + +#### Parameters + +None + +#### Returns + +`result`: _array_ of _strings_ - list of 20-byte account addresses owned by the client + + + +# curl HTTP request + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"eth_accounts","params":[],"id":53}' http://127.0.0.1:8545 +``` + +# wscat WS request + +```json +{ "jsonrpc": "2.0", "method": "eth_accounts", "params": [], "id": 53 } +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 53, + "result": [] +} +``` + + + +### `eth_blockNumber` + +Returns the index corresponding to the block number of the current chain head. + +#### Parameters + +None + +#### Returns + +`result`: _string_ - hexadecimal integer representing the index corresponding to the block number of the current chain head + + + +# curl HTTP + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":51}' http://127.0.0.1:8545 +``` + +# wscat WS + +```json +{ "jsonrpc": "2.0", "method": "eth_blockNumber", "params": [], "id": 51 } +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 51, + "result": "0x2377" +} +``` + +# curl GraphQL + +```bash +curl -X POST -H "Content-Type: application/json" --data '{ "query": "{block{number}}"}' http://localhost:8547/graphql +``` + +# GraphQL + +```text +{ + block { + number + } +} +``` + +# GraphQL result + +```json +{ + "data": { + "block": { + "number": 16221 + } + } +} +``` + + + +### `eth_call` + +Invokes a contract function locally and does not change the state of the blockchain. + +You can interact with contracts using [`eth_sendRawTransaction`](#eth_sendrawtransaction) or `eth_call`. + +By default, the `eth_call` error response includes the [revert reason](../../../private-networks/how-to/send-transactions/revert-reason.md). + +#### Parameters + +`call`: _object_ - [transaction call object](objects.md#transaction-call-object) + +`blockNumber` or `blockHash`: _string_ - hexadecimal or decimal integer representing a block number, block hash, or one of the string tags `latest`, `earliest`, `pending`, `finalized`, or `safe`, as described in [block parameter](../../how-to/use-besu-api/json-rpc.md#block-parameter) + +:::note + +By default, `eth_call` does not fail if the sender account has an insufficient balance. This is done by setting the balance of the account to a large amount of ether. To enforce balance rules, set the [`strict` parameter](objects.md#transaction-call-object) in the transaction call object to `true`. + +::: + +#### Returns + +`result`: _string_ - return value of the executed contract + + + +# curl HTTP + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"eth_call","params":[{"to":"0x69498dd54bd25aa0c886cf1f8b8ae0856d55ff13","value":"0x1"}, "latest"],"id":53}' http://127.0.0.1:8545 +``` + +# wscat WS + +```json +{ + "jsonrpc": "2.0", + "method": "eth_call", + "params": [ + { "to": "0x69498dd54bd25aa0c886cf1f8b8ae0856d55ff13", "value": "0x1" }, + "latest" + ], + "id": 53 +} +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 53, + "result": "0x" +} +``` + +# curl GraphQL + +```bash +curl -X POST -H "Content-Type: application/json" --data '{ "query": "{block {number call (data : {from : \"0xa94f5374fce5edbc8e2a8697c15331677e6ebf0b\", to: \"0x69498dd54bd25aa0c886cf1f8b8ae0856d55ff13\", data :\"0x12a7b914\"}){data status}}}"}' http://localhost:8547/graphql +``` + +# GraphQL + +```text +{ + block { + number + call(data: {from: "0xa94f5374fce5edbc8e2a8697c15331677e6ebf0b", to: "0x69498dd54bd25aa0c886cf1f8b8ae0856d55ff13", data: "0x12a7b914"}) { + data + status + } + } +} +``` + +# GraphQL result + +```json +{ + "data": { + "block": { + "number": 17449, + "call": { + "data": "0x", + "status": 1 + } + } + } +} +``` + + + +:::info Example of a simulated contract creation + +The following example creates a simulated contract by not including the `to` parameter from the [transaction call object](objects.md#transaction-call-object) in the `call` parameter. Besu simulates the data to create the contract. + + + +# curl HTTP + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"eth_call","params":[{"from":"0xfe3b557e8fb62b89f4916b721be55ceb828dbd73", "data":"0x6080604052336000806101000a81548173ffffffffffffffffffffffffffffffffffffffff021916908373ffffffffffffffffffffffffffffffffffffffff16021790555034801561005057600080fd5b5061021e806100606000396000f3fe608060405234801561001057600080fd5b50600436106100415760003560e01c8063445df0ac146100465780638da5cb5b14610064578063fdacd576146100ae575b600080fd5b61004e6100dc565b6040518082815260200191505060405180910390f35b61006c6100e2565b604051808273ffffffffffffffffffffffffffffffffffffffff1673ffffffffffffffffffffffffffffffffffffffff16815260200191505060405180910390f35b6100da600480360360208110156100c457600080fd5b8101908080359060200190929190505050610107565b005b60015481565b6000809054906101000a900473ffffffffffffffffffffffffffffffffffffffff1681565b6000809054906101000a900473ffffffffffffffffffffffffffffffffffffffff1673ffffffffffffffffffffffffffffffffffffffff163373ffffffffffffffffffffffffffffffffffffffff16146101ac576040517f08c379a00000000000000000000000000000000000000000000000000000000081526004018080602001828103825260338152602001806101b76033913960400191505060405180910390fd5b806001819055505056fe546869732066756e6374696f6e206973207265737472696374656420746f2074686520636f6e74726163742773206f776e6572a265627a7a7231582007302f208a10686769509b529e1878bda1859883778d70dedd1844fe790c9bde64736f6c63430005100032","gas":"0x439cf","gasPrice":"0x0"},"latest"],"id":53}' http://127.0.0.1:8545 +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 53, + "result": "0x608060405234801561001057600080fd5b50600436106100415760003560e01c8063445df0ac146100465780638da5cb5b14610064578063fdacd576146100ae575b600080fd5b61004e6100dc565b6040518082815260200191505060405180910390f35b61006c6100e2565b604051808273ffffffffffffffffffffffffffffffffffffffff1673ffffffffffffffffffffffffffffffffffffffff16815260200191505060405180910390f35b6100da600480360360208110156100c457600080fd5b8101908080359060200190929190505050610107565b005b60015481565b6000809054906101000a900473ffffffffffffffffffffffffffffffffffffffff1681565b6000809054906101000a900473ffffffffffffffffffffffffffffffffffffffff1673ffffffffffffffffffffffffffffffffffffffff163373ffffffffffffffffffffffffffffffffffffffff16146101ac576040517f08c379a00000000000000000000000000000000000000000000000000000000081526004018080602001828103825260338152602001806101b76033913960400191505060405180910390fd5b806001819055505056fe546869732066756e6374696f6e206973207265737472696374656420746f2074686520636f6e74726163742773206f776e6572a265627a7a7231582007302f208a10686769509b529e1878bda1859883778d70dedd1844fe790c9bde64736f6c63430005100032" +} +``` + + + +::: + +### `eth_chainId` + +Returns the [chain ID](../../concepts/network-and-chain-id.md). + +#### Parameters + +None + +#### Returns + +`result`: _string_ - chain ID in hexadecimal + + + +# curl HTTP request + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"eth_chainId","params":[],"id":51}' http://127.0.0.1:8545 +``` + +# wscat WS request + +```json +{ "jsonrpc": "2.0", "method": "eth_chainId", "params": [], "id": 51 } +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 51, + "result": "0x7e2" +} +``` + + + +### `eth_coinbase` + +Returns the client coinbase address. The coinbase address is the account to pay mining rewards to. + +To set a coinbase address, start Besu with the `--miner-coinbase` option set to a valid Ethereum account address. You can get the Ethereum account address from a client such as MetaMask or Etherscan. For example: + +```bash title="Example" +besu --miner-coinbase="0xfe3b557e8fb62b89f4916b721be55ceb828dbd73" --rpc-http-enabled +``` + +#### Parameters + +None + +#### Returns + +`result`: _string_ - coinbase address + + + +# curl HTTP request + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"eth_coinbase","params":[],"id":53}' http://127.0.0.1:8545 +``` + +# wscat WS request + +```json +{ "jsonrpc": "2.0", "method": "eth_coinbase", "params": [], "id": 53 } +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 53, + "result": "0xfe3b557e8fb62b89f4916b721be55ceb828dbd73" +} +``` + + + +### `eth_createAccessList` + +Creates an [EIP-2930](https://eips.ethereum.org/EIPS/eip-2930) access list that you can [include in a transaction](../../concepts/transactions/types.md#access_list-transactions). + +#### Parameters + +`transaction`: _object_ - [transaction call object](objects.md#transaction-call-object) + +`blockNumber` or `blockHash`: _string_ - hexadecimal or decimal integer representing a block number, block hash, or one of the string tags `latest`, `earliest`, `pending`, `finalized`, or `safe`, as described in [block parameter](../../how-to/use-besu-api/json-rpc.md#block-parameter). + +#### Returns + +`result`: _object_ - access list object with the following fields: + +- `accessList`: _array_ of _objects_ - list of objects with the following fields: + - `address`: _string_ - addresses to be accessed by the transaction + - `storageKeys`: _array_ - storage keys to be accessed by the transaction +- `gasUsed`: _string_ - approximate gas cost for the transaction if the access list is included + + + +# curl HTTP + +```bash +curl -X POST --data '{"method":"eth_createAccessList","params":[{"from": "0xaeA8F8f781326bfE6A7683C2BD48Dd6AA4d3Ba63", "data": "0x608060806080608155"}, "pending"],"id":1,"jsonrpc":"2.0"}' http://127.0.0.1:8545 +``` + +# wscat WS + +```json +{ + "method": "eth_createAccessList", + "params": [ + { + "from": "0xaeA8F8f781326bfE6A7683C2BD48Dd6AA4d3Ba63", + "data": "0x608060806080608155" + }, + "pending" + ], + "id": 1, + "jsonrpc": "2.0" +} +``` + +# JSON result + +```json +{ + "accessList": [ + { + "address": "0xa02457e5dfd32bda5fc7e1f1b008aa5979568150", + "storageKeys": [ + "0x0000000000000000000000000000000000000000000000000000000000000081", + ] + } + ] + "gasUsed": "0x125f8" +} +``` + + + +### `eth_estimateGas` + +Returns an estimate of the gas required for a transaction to complete. The estimation process does not use gas and the transaction is not added to the blockchain. The resulting estimate can be greater than the amount of gas the transaction ends up using, for reasons including EVM mechanics and node performance. + +The `eth_estimateGas` call does not send a transaction. You must call [`eth_sendRawTransaction`](#eth_sendrawtransaction) to execute the transaction. + +By default, the `eth_estimateGas` error response includes the [revert reason](../../../private-networks/how-to/send-transactions/revert-reason.md). + +#### Parameters + +For `eth_estimateGas`, all fields are optional because setting a gas limit is irrelevant to the estimation process (unlike transactions, in which gas limits apply). + +`call`: _object_ - [transaction call object](objects.md#transaction-call-object) + +#### Returns + +`result`: _string_ - amount of gas used + +The following example returns an estimate of 21000 wei (`0x5208`) for the transaction. + + + +# curl HTTP + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"eth_estimateGas","params":[{"from":"0xFE3B557E8Fb62b89F4916B721be55cEb828dBd73","to":"0x44Aa93095D6749A706051658B970b941c72c1D53","value":"0x1"}],"id":53}' http://127.0.0.1:8545 +``` + +# wscat WS + +```json +{ + "jsonrpc": "2.0", + "method": "eth_estimateGas", + "params": [ + { + "from": "0xFE3B557E8Fb62b89F4916B721be55cEb828dBd73", + "to": "0x44Aa93095D6749A706051658B970b941c72c1D53", + "value": "0x1" + } + ], + "id": 53 +} +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 53, + "result": "0x5208" +} +``` + +# curl GraphQL + +```bash +curl -X POST -H "Content-Type: application/json" --data '{ "query": "{block{estimateGas (data: {from :\"0x6295ee1b4f6dd65047762f924ecd367c17eabf8f\", to :\"0x8888f1f195afa192cfee860698584c030f4c9db1\"})}}"}' http://localhost:8547/graphql +``` + +# GraphQL + +```text +{ + block { + estimateGas(data: {from: "0x6295ee1b4f6dd65047762f924ecd367c17eabf8f", to: "0x8888f1f195afa192cfee860698584c030f4c9db1"}) + } +} +``` + +# GraphQL result + +```json +{ + "data": { + "block": { + "estimateGas": 21000 + } + } +} +``` + + + +The following example request estimates the cost of deploying a simple storage smart contract to the network. The data field contains the hash of the compiled contract you want to deploy. (You can get the compiled contract hash from your IDE, for example, **Remix > Compile tab > details > WEB3DEPLOY**.) The result is 113355 wei. + + + +# curl HTTP request + +```bash +curl -X POST \ +http://127.0.0.1:8545 \ +-H 'Content-Type: application/json' \ +-d '{ + "jsonrpc": "2.0", + "method": "eth_estimateGas", + "params": [{ + "from": "0x8bad598904ec5d93d07e204a366d084a80c7694e", + "data": "0x608060405234801561001057600080fd5b5060e38061001f6000396000f3fe6080604052600436106043576000357c0100000000000000000000000000000000000000000000000000000000900480633fa4f24514604857806355241077146070575b600080fd5b348015605357600080fd5b50605a60a7565b6040518082815260200191505060405180910390f35b348015607b57600080fd5b5060a560048036036020811015609057600080fd5b810190808035906020019092919050505060ad565b005b60005481565b806000819055505056fea165627a7a7230582020d7ad478b98b85ca751c924ef66bcebbbd8072b93031073ef35270a4c42f0080029" + }], + "id": 1 +}' +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": "0x1bacb" +} +``` + + + +### `eth_feeHistory` + +Returns base fee per gas and transaction effective priority fee per gas history for the requested block range, allowing you to track trends over time. + +#### Parameters + +- `blockCount`: _integer_ or _string_ - Number of blocks in the requested range. Between 1 and 1024 blocks can be requested in a single query. If blocks in the specified block range are not available, then only the fee history for available blocks is returned. Accepts hexadecimal or integer values. + +- `newestBlock`: _string_ - hexadecimal or decimal integer representing the highest number block of the requested range or one of the string tags `latest`, `earliest`, `pending`, `finalized`, or `safe`, as described in [block parameter](../../how-to/use-besu-api/json-rpc.md#block-parameter). + +- `array` of `integers` - (optional) A monotonically increasing list of percentile values to sample from each block's effective priority fees per gas in ascending order, weighted by gas used. + +#### Returns + +`result`: _object_ - [Fee history results object](objects.md#fee-history-results-object). + + + +# curl HTTP + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"eth_feeHistory","params": ["0x5", "latest", [20,30]],"id":1}' http://127.0.0.1:8545 +``` + +# wscat WS + +```json +{ + "jsonrpc": "2.0", + "method": "eth_feeHistory", + "params": ["0x5", "latest", [20, 30]], + "id": 1 +} +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "result": { + "baseFeePerGas": [ + "0x3da8e7618", + "0x3e1ba3b1b", + "0x3dfd72b90", + "0x3d64eee76", + "0x3d4da2da0", + "0x3ccbcac6b" + ], + "gasUsedRatio": [ + 0.5290747666666666, 0.49240453333333334, 0.4615576, 0.49407083333333335, + 0.4669053 + ], + "oldestBlock": "0xfab8ac", + "reward": [ + ["0x59682f00", "0x59682f00"], + ["0x59682f00", "0x59682f00"], + ["0x3b9aca00", "0x59682f00"], + ["0x510b0870", "0x59682f00"], + ["0x3b9aca00", "0x59682f00"] + ] + }, + "id": 1 +} +``` + + + +### `eth_gasPrice` + +Returns a percentile gas unit price for the most recent blocks, in Wei. By default, the last 100 blocks are examined and the 50th percentile gas unit price (that is, the median value) is returned. + +If there are no blocks, the value for [`--min-gas-price`](../cli/options.md#min-gas-price) is returned. The value returned is restricted to values between [`--min-gas-price`](../cli/options.md#min-gas-price) and [`--api-gas-price-max`](../cli/options.md#api-gas-price-max). By default, 1000 Wei and 500GWei. + +Use the [`--api-gas-price-blocks`](../cli/options.md#api-gas-price-blocks), [`--api-gas-price-percentile`](../cli/options.md#api-gas-price-percentile) , and [`--api-gas-price-max`](../cli/options.md#api-gas-price-max) command line options to configure the `eth_gasPrice` default values. + +#### Parameters + +None + +#### Returns + +`result`: _string_ - percentile gas unit price for the most recent blocks, in Wei, as a hexadecimal value + + + +# curl HTTP + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"eth_gasPrice","params":[],"id":53}' http://127.0.0.1:8545 +``` + +# wscat WS + +```json +{ "jsonrpc": "2.0", "method": "eth_gasPrice", "params": [], "id": 53 } +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 53, + "result": "0x3e8" +} +``` + +# curl GraphQL + +```bash +curl -X POST -H "Content-Type: application/json" --data '{ "query": "{gasPrice}"}' http://localhost:8547/graphql +``` + +# GraphQL + +```text +{ + gasPrice +} +``` + +# GraphQL result + +```json +{ + "data": { + "gasPrice": "0x3e8" + } +} +``` + + + +### `eth_getBalance` + +Returns the account balance of the specified address. + +#### Parameters + +- `address`: _string_ - 20-byte account address from which to retrieve the balance + +- `blockNumber` or `blockHash`: _string_ - hexadecimal or decimal integer representing a block number, block hash, or one of the string tags `latest`, `earliest`, `pending`, `finalized`, or `safe`, as described in [block parameter](../../how-to/use-besu-api/json-rpc.md#block-parameter) + +#### Returns + +`result`: _string_ - current balance, in Wei, as a hexadecimal value + + + +# curl HTTP + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"eth_getBalance","params":["0xfe3b557e8fb62b89f4916b721be55ceb828dbd73", "latest"],"id":53}' http://127.0.0.1:8545 +``` + +# wscat WS + +```json +{ + "jsonrpc": "2.0", + "method": "eth_getBalance", + "params": ["0xfe3b557e8fb62b89f4916b721be55ceb828dbd73", "latest"], + "id": 53 +} +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 53, + "result": "0x1cfe56f3795885980000" +} +``` + +# curl GraphQL + +```bash +curl -X POST -H "Content-Type: application/json" --data '{ "query": "{ account ( address: \"0xfe3b557e8fb62b89f4916b721be55ceb828dbd73\") { balance } }"}' http://localhost:8547/graphql +``` + +# GraphQL + +```text +{ + account(address: "0xfe3b557e8fb62b89f4916b721be55ceb828dbd73") { + balance + } +} +``` + +# GraphQL result + +```json +{ + "data": { + "account": { + "balance": "0x1ce96a1ffe7620d00000" + } + } +} +``` + + + +### `eth_getBlockByHash` + +Returns information about the block matching the specified block hash. + +#### Parameters + +- `hash`: _string_ - 32-byte hash of a block + +- `verbose`: _boolean_ - if `true`, returns the full [transaction objects](objects.md#transaction-object); if `false`, returns the transaction hashes + +#### Returns + +`result`: _object_ - [block object](objects.md#block-object), or `null` when there is no block + + + +# curl HTTP + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"eth_getBlockByHash","params":["0xd5f1812548be429cbdc6376b29611fc49e06f1359758c4ceaaa3b393e2239f9c", false],"id":53}' http://127.0.0.1:8545 +``` + +# wscat WS + +```json +{ + "jsonrpc": "2.0", + "method": "eth_getBlockByHash", + "params": [ + "0xd5f1812548be429cbdc6376b29611fc49e06f1359758c4ceaaa3b393e2239f9c", + false + ], + "id": 53 +} +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 53, + "result": { + "number": "0x68b3", + "hash": "0xd5f1812548be429cbdc6376b29611fc49e06f1359758c4ceaaa3b393e2239f9c", + "mixHash": "0x24900fb3da77674a861c428429dce0762707ecb6052325bbd9b3c64e74b5af9d", + "parentHash": "0x1f68ac259155e2f38211ddad0f0a15394d55417b185a93923e2abe71bb7a4d6d", + "nonce": "0x378da40ff335b070", + "sha3Uncles": "0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347", + "logsBloom": "0x00000000000000100000004080000000000500000000000000020000100000000800001000000004000001000000000000000800040010000020100000000400000010000000000000000040000000000000040000000000000000000000000000000400002400000000000000000000000000000004000004000000000000840000000800000080010004000000001000000800000000000000000000000000000000000800000000000040000000020000000000000000000800000400000000000000000000000600000400000000002000000000000000000000004000000000000000100000000000000000000000000000000000040000900010000000", + "transactionsRoot": "0x4d0c8e91e16bdff538c03211c5c73632ed054d00a7e210c0eb25146c20048126", + "stateRoot": "0x91309efa7e42c1f137f31fe9edbe88ae087e6620d0d59031324da3e2f4f93233", + "receiptsRoot": "0x68461ab700003503a305083630a8fb8d14927238f0bc8b6b3d246c0c64f21f4a", + "miner": "0xb42b6c4a95406c78ff892d270ad20b22642e102d", + "difficulty": "0x66e619a", + "totalDifficulty": "0x1e875d746ae", + "extraData": "0xd583010502846765746885676f312e37856c696e7578", + "size": "0x334", + "gasLimit": "0x47e7c4", + "gasUsed": "0x37993", + "timestamp": "0x5835c54d", + "uncles": [], + "transactions": [ + "0xa0807e117a8dd124ab949f460f08c36c72b710188f01609595223b325e58e0fc", + "0xeae6d797af50cb62a596ec3939114d63967c374fa57de9bc0f4e2b576ed6639d" + ], + "baseFeePerGas": "0x7" + } +} +``` + +# curl GraphQL + +```bash +curl -X POST -H "Content-Type: application/json" --data '{ "query": "{block (hash : \"0xb0efed1fc9326fee967cb2d845d4ebe57c5350a0670c8e86f8052dea6f219f92\") {number transactions{hash} timestamp difficulty totalDifficulty gasUsed gasLimit hash nonce ommerCount logsBloom mixHash ommerHash extraData stateRoot receiptsRoot transactionCount transactionsRoot}}"}' http://localhost:8547/graphql +``` + +# GraphQL + +```text +{ + block(hash: "0xb0efed1fc9326fee967cb2d845d4ebe57c5350a0670c8e86f8052dea6f219f92") { + number + transactions { + hash + } + timestamp + difficulty + totalDifficulty + gasUsed + gasLimit + hash + nonce + ommerCount + logsBloom + mixHash + ommerHash + extraData + stateRoot + receiptsRoot + transactionCount + transactionsRoot + } +} +``` + +# GraphQL result + +```json +{ + "data": { + "block": { + "number": 17607, + "transactions": [], + "timestamp": "0x5cdbdfb5", + "difficulty": "0x1", + "totalDifficulty": "0x44c8", + "gasUsed": 0, + "gasLimit": 4700000, + "hash": "0xb0efed1fc9326fee967cb2d845d4ebe57c5350a0670c8e86f8052dea6f219f92", + "nonce": "0x0000000000000000", + "ommerCount": 0, + "logsBloom": "0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000", + "mixHash": "0x63746963616c2062797a616e74696e65206661756c7420746f6c6572616e6365", + "ommerHash": "0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347", + "extraData": "0xf882a00000000000000000000000000000000000000000000000000000000000000000d5949811ebc35d7b06b3fa8dc5809a1f9c52751e1deb808400000000f843b841fae6d25da0b91e3e88669d0a765c98479d86d53e9ea1f3fb6b36d7ff22fa622a3da0c49c20e5562c774e90acae8ad487936f6b6019cd8a782db684693cba1e9800", + "stateRoot": "0xa7086c266aed46cd3bc45579178f8acb36d9d147de575a3ecbf8c7e6f1c737fc", + "receiptsRoot": "0x56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421", + "transactionCount": 0, + "transactionsRoot": "0x56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421", + "baseFeePerGas": "0x7" + } + } +} +``` + + + +### `eth_getBlockByNumber` + +Returns information about the block matching the specified block number. + +#### Parameters + +- `blockNumber`: _string_ - hexadecimal or decimal integer representing a block number or one of the string tags `latest`, `earliest`, `pending`, `finalized`, or `safe`, as described in [block parameter](../../how-to/use-besu-api/json-rpc.md#block-parameter) + +- `verbose`: _boolean_ - if `true`, returns the full [transaction objects](objects.md#transaction-object); if `false`, returns only the hashes of the transactions. + +#### Returns + +`result`: _object_ - [block object](objects.md#block-object), or `null` when there is no block. + + + +# curl HTTP + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"eth_getBlockByNumber","params":["0x68B3", true],"id":1}' http://127.0.0.1:8545 +``` + +# wscat WS + +```json +{ + "jsonrpc": "2.0", + "method": "eth_getBlockByNumber", + "params": ["0x68B3", true], + "id": 1 +} +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + "number": "0x68b3", + "hash": "0xd5f1812548be429cbdc6376b29611fc49e06f1359758c4ceaaa3b393e2239f9c", + "mixHash": "0x24900fb3da77674a861c428429dce0762707ecb6052325bbd9b3c64e74b5af9d", + "parentHash": "0x1f68ac259155e2f38211ddad0f0a15394d55417b185a93923e2abe71bb7a4d6d", + "nonce": "0x378da40ff335b070", + "sha3Uncles": "0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347", + "logsBloom": "0x00000000000000100000004080000000000500000000000000020000100000000800001000000004000001000000000000000800040010000020100000000400000010000000000000000040000000000000040000000000000000000000000000000400002400000000000000000000000000000004000004000000000000840000000800000080010004000000001000000800000000000000000000000000000000000800000000000040000000020000000000000000000800000400000000000000000000000600000400000000002000000000000000000000004000000000000000100000000000000000000000000000000000040000900010000000", + "transactionsRoot": "0x4d0c8e91e16bdff538c03211c5c73632ed054d00a7e210c0eb25146c20048126", + "stateRoot": "0x91309efa7e42c1f137f31fe9edbe88ae087e6620d0d59031324da3e2f4f93233", + "receiptsRoot": "0x68461ab700003503a305083630a8fb8d14927238f0bc8b6b3d246c0c64f21f4a", + "miner": "0xb42b6c4a95406c78ff892d270ad20b22642e102d", + "difficulty": "0x66e619a", + "totalDifficulty": "0x1e875d746ae", + "extraData": "0xd583010502846765746885676f312e37856c696e7578", + "size": "0x334", + "gasLimit": "0x47e7c4", + "gasUsed": "0x37993", + "timestamp": "0x5835c54d", + "uncles": [], + "transactions": [], + "baseFeePerGas": "0x7" + } +} +``` + +# curl GraphQL + +```bash +curl -X POST -H "Content-Type: application/json" --data '{ "query": "{block (number : 100) {transactions{hash} timestamp difficulty totalDifficulty gasUsed gasLimit hash nonce ommerCount logsBloom mixHash ommerHash extraData stateRoot receiptsRoot transactionCount transactionsRoot ommers{hash} ommerAt(index : 1){hash} miner{address} account(address: \"0xfe3b557e8fb62b89f4916b721be55ceb828dbd73\"){balance} parent{hash} }}"}' http://localhost:8547/graphql +``` + +# GraphQL + +```text +{ + block(number: 100) { + transactions { + hash + } + timestamp + difficulty + totalDifficulty + gasUsed + gasLimit + hash + nonce + ommerCount + logsBloom + mixHash + ommerHash + extraData + stateRoot + receiptsRoot + transactionCount + transactionsRoot + ommers { + hash + } + ommerAt(index: 1) { + hash + } + miner { + address + } + account(address: "0xfe3b557e8fb62b89f4916b721be55ceb828dbd73") { + balance + } + parent { + hash + } + } +} +``` + +# GraphQL result + +```json +{ + "data": { + "block": { + "transactions": [], + "timestamp": "0x5cd10933", + "difficulty": "0x1", + "totalDifficulty": "0x65", + "gasUsed": 0, + "gasLimit": 4700000, + "hash": "0x63b3ea2bc37fec8f82680eb823652da6af8acebb4f6c4d0ff659c55be473c8b0", + "nonce": "0x0000000000000000", + "ommerCount": 0, + "logsBloom": "0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000", + "mixHash": "0x63746963616c2062797a616e74696e65206661756c7420746f6c6572616e6365", + "ommerHash": "0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347", + "extraData": "0xf882a00000000000000000000000000000000000000000000000000000000000000000d5949811ebc35d7b06b3fa8dc5809a1f9c52751e1deb808400000000f843b8414d877d8d0ced37ea138fab55a978f3740367a24a31731322ecdc3368f11e0d4966c9ce17ae59a76fb94eb436e8a386868f6bd6b0a5678e58daf49f5dd940558b00", + "stateRoot": "0xd650578a04b39f50cc979155f4510ec28c2c0a7c1e5fdbf84609bc7b1c430f48", + "receiptsRoot": "0x56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421", + "transactionCount": 0, + "transactionsRoot": "0x56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421", + "ommers": [], + "ommerAt": null, + "miner": { + "address": "0x9811ebc35d7b06b3fa8dc5809a1f9c52751e1deb" + }, + "account": { + "balance": "0xad0f47f269cbf31ac" + }, + "parent": { + "hash": "0x7bca25e1fa5e395fd6029eb496a70b6b5495843976bf9e49b993c723ded29d9e" + }, + "baseFeePerGas": "0x7" + } + } +} +``` + + + +### `eth_getBlockTransactionCountByHash` + +Returns the number of transactions in the block matching the specified block hash. + +#### Parameters + +`hash`: _string_ - 32-byte block hash + +#### Returns + +`result`: _number_ - integer representing the number of transactions in the specified block, or `null` if no matching block hash is found + + + +# curl HTTP + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"eth_getBlockTransactionCountByHash","params":["0xb903239f8543d04b5dc1ba6579132b143087c68db1b2168786408fcbce568238"],"id":53}' http://127.0.0.1:8545 +``` + +# wscat WS + +```json +{ + "jsonrpc": "2.0", + "method": "eth_getBlockTransactionCountByHash", + "params": [ + "0xb903239f8543d04b5dc1ba6579132b143087c68db1b2168786408fcbce568238" + ], + "id": 53 +} +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 53, + "result": null +} +``` + +# curl GraphQL + +```bash +curl -X POST -H "Content-Type: application/json" --data '{ "query": "{block(hash:\"0xe455c14f757b0b9b67774baad1be1c180a4c1657df52259dbb685bf375408097\"){transactionCount}}"}' http://localhost:8547/graphql +``` + +# GraphQL + +```text +{ + block(hash: "0xe455c14f757b0b9b67774baad1be1c180a4c1657df52259dbb685bf375408097") { + transactionCount + } +} +``` + +# GraphQL result + +```json +{ + "data": { + "block": { + "transactionCount": 1 + } + } +} +``` + + + +### `eth_getBlockTransactionCountByNumber` + +Returns the number of transactions in a block matching the specified block number. + +#### Parameters + +`blockNumber`: _string_ - hexadecimal or decimal integer representing a block number or one of the string tags `latest`, `earliest`, `pending`, `finalized`, or `safe`, as described in [block parameter](../../how-to/use-besu-api/json-rpc.md#block-parameter) + +#### Returns + +`result`: _string_ - integer representing the number of transactions in the specified block, or `null` if no matching block number is found + + + +# curl HTTP + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"eth_getBlockTransactionCountByNumber","params":["0xe8"],"id":51}' http://127.0.0.1:8545 +``` + +# wscat WS + +```json +{ + "jsonrpc": "2.0", + "method": "eth_getBlockTransactionCountByNumber", + "params": ["0xe8"], + "id": 51 +} +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 51, + "result": "0x8" +} +``` + +# curl GraphQL + +```bash +curl -X POST -H "Content-Type: application/json" --data '{ "query": "{block(number:232){transactionCount}}"}' http://localhost:8547/graphql +``` + +# GraphQL + +```text +{ + block(number: 232) { + transactionCount + } +} +``` + +# GraphQL result + +```json +{ + "data": { + "block": { + "transactionCount": 1 + } + } +} +``` + + + +### `eth_getCode` + +Returns the code of the smart contract at the specified address. Besu stores compiled smart contract code as a hexadecimal value. + +#### Parameters + +`address`: _string_ - 20-byte contract address + +`blockNumber` or `blockHash`: _string_ - hexadecimal or decimal integer representing a block number, block hash, or one of the string tags `latest`, `earliest`, `pending`, `finalized`, or `safe`, as described in [block parameter](../../how-to/use-besu-api/json-rpc.md#block-parameter) + +#### Returns + +`result`: _data_ - code stored at the specified address + + + +# curl HTTP + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"eth_getCode","params":["0xa50a51c09a5c451c52bb714527e1974b686d8e77", "latest"],"id":53}' http://127.0.0.1:8545 +``` + +# wscat WS + +```json +{ + "jsonrpc": "2.0", + "method": "eth_getCode", + "params": ["0xa50a51c09a5c451c52bb714527e1974b686d8e77", "latest"], + "id": 53 +} +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 53, + "result": "0x60806040526004361060485763ffffffff7c01000000000000000000000000000000000000000000000000000000006000350416633fa4f2458114604d57806355241077146071575b600080fd5b348015605857600080fd5b50605f6088565b60408051918252519081900360200190f35b348015607c57600080fd5b506086600435608e565b005b60005481565b60008190556040805182815290517f199cd93e851e4c78c437891155e2112093f8f15394aa89dab09e38d6ca0727879181900360200190a1505600a165627a7a723058209d8929142720a69bde2ab3bfa2da6217674b984899b62753979743c0470a2ea70029" +} +``` + +# curl GraphQL + +```bash +curl -X POST -H "Content-Type: application/json" --data '{"query": "{account(address: \"0xa50a51c09a5c451c52bb714527e1974b686d8e77\"){ code }}"}' http://localhost:8547/graphql +``` + +# GraphQL + +```text +{ + account(address: "0xa50a51c09a5c451c52bb714527e1974b686d8e77") { + code + } +} +``` + +# GraphQL result + +```json +{ + "data": { + "account": { + "code": "0x60806040526004361060485763ffffffff7c01000000000000000000000000000000000000000000000000000000006000350416633fa4f2458114604d57806355241077146071575b600080fd5b348015605857600080fd5b50605f6088565b60408051918252519081900360200190f35b348015607c57600080fd5b506086600435608e565b005b60005481565b60008190556040805182815290517f199cd93e851e4c78c437891155e2112093f8f15394aa89dab09e38d6ca0727879181900360200190a1505600a165627a7a723058209d8929142720a69bde2ab3bfa2da6217674b984899b62753979743c0470a2ea70029" + } + } +} +``` + + + +### `eth_getFilterChanges` + +Polls the specified filter and returns an array of changes that have occurred since the last poll. + +#### Parameters + +`filterId`: _string_ - filter ID + +#### Returns + +`result`: _array_ of _strings_ or _objects_ - if nothing changed since the last poll, an empty list; otherwise: + +- For filters created with `eth_newBlockFilter`, returns block hashes. + +- For filters created with `eth_newPendingTransactionFilter`, returns transaction hashes. + +- For filters created with `eth_newFilter`, returns [log objects](objects.md#log-object). + + + +# curl HTTP request + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"eth_getFilterChanges","params":["0xf8bf5598d9e04fbe84523d42640b9b0e"],"id":1}' http://127.0.0.1:8545 +``` + +# wscat WS request + +```json +{ + "jsonrpc": "2.0", + "method": "eth_getFilterChanges", + "params": ["0xf8bf5598d9e04fbe84523d42640b9b0e"], + "id": 1 +} +``` + +# JSON result + +```json title="Example result from a filter created with eth_newBlockFilter" +{ + "jsonrpc": "2.0", + "id": 1, + "result": [ + "0xda2bfe44bf85394f0d6aa702b5af89ae50ae22c0928c18b8903d9269abe17e0b", + "0x88cd3a37306db1306f01f7a0e5b25a9df52719ad2f87b0f88ee0e6753ed4a812", + "0x4d4c731fe129ff32b425e6060d433d3fde278b565bbd1fd624d5a804a34f8786" + ] +} +``` + +```json title="Example result from a filter created with eth_newPendingTransactionFilter" +{ + "jsonrpc": "2.0", + "id": 1, + "result": [ + "0x1e977049b6db09362da09491bee3949d9362080ce3f4fc19721196d508580d46", + "0xa3abc4b9a4e497fd58dc59cdff52e9bb5609136bcd499e760798aa92802769be" + ] +} +``` + +```json title="Example result from a filter created with eth_newFilter" +{ + "jsonrpc": "2.0", + "id": 1, + "result": [ + { + "logIndex": "0x0", + "removed": false, + "blockNumber": "0x233", + "blockHash": "0xfc139f5e2edee9e9c888d8df9a2d2226133a9bd87c88ccbd9c930d3d4c9f9ef5", + "transactionHash": "0x66e7a140c8fa27fe98fde923defea7562c3ca2d6bb89798aabec65782c08f63d", + "transactionIndex": "0x0", + "address": "0x42699a7612a82f1d9c36148af9c77354759b210b", + "data": "0x0000000000000000000000000000000000000000000000000000000000000004", + "topics": [ + "0x04474795f5b996ff80cb47c148d4c5ccdbe09ef27551820caa9c2f8ed149cce3" + ] + }, + { + "logIndex": "0x0", + "removed": false, + "blockNumber": "0x238", + "blockHash": "0x98b0ec0f9fea0018a644959accbe69cd046a8582e89402e1ab0ada91cad644ed", + "transactionHash": "0xdb17aa1c2ce609132f599155d384c0bc5334c988a6c368056d7e167e23eee058", + "transactionIndex": "0x0", + "address": "0x42699a7612a82f1d9c36148af9c77354759b210b", + "data": "0x0000000000000000000000000000000000000000000000000000000000000007", + "topics": [ + "0x04474795f5b996ff80cb47c148d4c5ccdbe09ef27551820caa9c2f8ed149cce3" + ] + } + ] +} +``` + + + +### `eth_getFilterLogs` + +Returns an array of [logs](../../concepts/events-and-logs.md) for the specified filter. + +Leave the [`--auto-log-bloom-caching-enabled`](../cli/options.md#auto-log-bloom-caching-enabled) command line option at the default value of `true` to improve log retrieval performance. + +:::note + +`eth_getFilterLogs` is only used for filters created with `eth_newFilter`. To specify a filter object and get logs without creating a filter, use `eth_getLogs`. + +::: + +#### Parameters + +`filterId`: _string_ - filter ID + +#### Returns + +`result`: _array_ of _objects_ - list of [log objects](objects.md#log-object) + + + +# curl HTTP request + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"eth_getFilterLogs","params":["0x5ace5de3985749b6a1b2b0d3f3e1fb69"],"id":1}' http://127.0.0.1:8545 +``` + +# wscat WS request + +```json +{ + "jsonrpc": "2.0", + "method": "eth_getFilterLogs", + "params": ["0x5ace5de3985749b6a1b2b0d3f3e1fb69"], + "id": 1 +} +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": [ + { + "logIndex": "0x0", + "removed": false, + "blockNumber": "0xb3", + "blockHash": "0xe7cd776bfee2fad031d9cc1c463ef947654a031750b56fed3d5732bee9c61998", + "transactionHash": "0xff36c03c0fba8ac4204e4b975a6632c862a3f08aa01b004f570cc59679ed4689", + "transactionIndex": "0x0", + "address": "0x2e1f232a9439c3d459fceca0beef13acc8259dd8", + "data": "0x0000000000000000000000000000000000000000000000000000000000000003", + "topics": [ + "0x04474795f5b996ff80cb47c148d4c5ccdbe09ef27551820caa9c2f8ed149cce3" + ] + }, + { + "logIndex": "0x0", + "removed": false, + "blockNumber": "0xb6", + "blockHash": "0x3f4cf35e7ed2667b0ef458cf9e0acd00269a4bc394bb78ee07733d7d7dc87afc", + "transactionHash": "0x117a31d0dbcd3e2b9180c40aca476586a648bc400aa2f6039afdd0feab474399", + "transactionIndex": "0x0", + "address": "0x2e1f232a9439c3d459fceca0beef13acc8259dd8", + "data": "0x0000000000000000000000000000000000000000000000000000000000000005", + "topics": [ + "0x04474795f5b996ff80cb47c148d4c5ccdbe09ef27551820caa9c2f8ed149cce3" + ] + } + ] +} +``` + + + +### `eth_getLogs` + +Returns an array of [logs](../../concepts/events-and-logs.md) matching a specified filter object. + +Leave the [`--auto-log-bloom-caching-enabled`](../cli/options.md#auto-log-bloom-caching-enabled) command line option at the default value of `true` to improve log retrieval performance. + +:::caution + +Using `eth_getLogs` to get logs from a large range of blocks, especially an entire chain from its genesis block, might cause Besu to hang for an indeterminable amount of time while generating the response. We recommend setting a range limit using the [`--rpc-max-logs-range`](../cli/options.md#rpc-max-logs-range) option (or leaving it at its default value of 1000). + +::: + +#### Parameters + +`filterOptions`: _object_ - [filter options object](objects.md#filter-options-object) + +#### Returns + +`result`: _array_ of _objects_ - list of [log objects](objects.md#log-object) + + + +# curl HTTP + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"eth_getLogs","params":[{"fromBlock":"earliest", "toBlock":"latest", "address": "0x2e1f232a9439c3d459fceca0beef13acc8259dd8", "topics":[]}], "id":1}' http://127.0.0.1:8545 +``` + +# wscat WS + +```json +{ + "jsonrpc": "2.0", + "method": "eth_getLogs", + "params": [ + { + "fromBlock": "earliest", + "toBlock": "latest", + "address": "0x2e1f232a9439c3d459fceca0beef13acc8259dd8", + "topics": [] + } + ], + "id": 1 +} +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": [ + { + "logIndex": "0x0", + "removed": false, + "blockNumber": "0xb3", + "blockHash": "0xe7cd776bfee2fad031d9cc1c463ef947654a031750b56fed3d5732bee9c61998", + "transactionHash": "0xff36c03c0fba8ac4204e4b975a6632c862a3f08aa01b004f570cc59679ed4689", + "transactionIndex": "0x0", + "address": "0x2e1f232a9439c3d459fceca0beef13acc8259dd8", + "data": "0x0000000000000000000000000000000000000000000000000000000000000003", + "topics": [ + "0x04474795f5b996ff80cb47c148d4c5ccdbe09ef27551820caa9c2f8ed149cce3" + ] + }, + { + "logIndex": "0x0", + "removed": false, + "blockNumber": "0xb6", + "blockHash": "0x3f4cf35e7ed2667b0ef458cf9e0acd00269a4bc394bb78ee07733d7d7dc87afc", + "transactionHash": "0x117a31d0dbcd3e2b9180c40aca476586a648bc400aa2f6039afdd0feab474399", + "transactionIndex": "0x0", + "address": "0x2e1f232a9439c3d459fceca0beef13acc8259dd8", + "data": "0x0000000000000000000000000000000000000000000000000000000000000005", + "topics": [ + "0x04474795f5b996ff80cb47c148d4c5ccdbe09ef27551820caa9c2f8ed149cce3" + ] + } + ] +} +``` + +# curl GraphQL + +```bash +curl -X POST -H "Content-Type: application/json" --data '{"query": "{logs(filter:{fromBlock: 1486000, toBlock: 1486010, addresses: [\"0x7ef66b77759e12caf3ddb3e4aff524e577c59d8d\"], topics: [[\"0x8a22ee899102a366ac8ad0495127319cb1ff2403cfae855f83a89cda1266674d\"]]}) {index topics data account{address} transaction{hash} }}"}' http://localhost:8547/graphql +``` + +# GraphQL + +```text +{ + logs(filter: {fromBlock: 1486000, toBlock: 1486010, addresses: ["0x7ef66b77759e12caf3ddb3e4aff524e577c59d8d"], topics: [["0x8a22ee899102a366ac8ad0495127319cb1ff2403cfae855f83a89cda1266674d"]]}) { + index + topics + data + account { + address + } + transaction { + hash + } + } +} +``` + +# GraphQL result + +```json +{ + "data": { + "logs": [ + { + "index": 0, + "topics": [ + "0x8a22ee899102a366ac8ad0495127319cb1ff2403cfae855f83a89cda1266674d", + "0x0000000000000000000000000000000000000000000000000000000000000004", + "0x0000000000000000000000000000000000000000000000000000000000508918" + ], + "data": "0xa5a04999ec29a8bd19ce32b859280ef9dbb464d846be06f64a1b1012ec08ab03", + "account": { + "address": "0x7ef66b77759e12caf3ddb3e4aff524e577c59d8d" + }, + "transaction": { + "hash": "0x36a2186344c6a32760e7700fdf3685936220876c51ff39d071eb48c17f7e802f" + } + }, + { + "index": 0, + "topics": [ + "0x8a22ee899102a366ac8ad0495127319cb1ff2403cfae855f83a89cda1266674d", + "0x0000000000000000000000000000000000000000000000000000000000000003", + "0x0000000000000000000000000000000000000000000000000000000000648c72" + ], + "data": "0x0ee96b660ad82c8010c90760a03edfbb40b4af5e3634a8c214e4ac7fa1f61492", + "account": { + "address": "0x7ef66b77759e12caf3ddb3e4aff524e577c59d8d" + }, + "transaction": { + "hash": "0x9e2cc9e84a9e78839d6f4b591dfd98cc7a454a8ee3cd6ccd0a18e662e22d3818" + } + } + ] + } +} +``` + + + +### `eth_getMinerDataByBlockHash` + +Returns miner data for the specified block. + +#### Parameters + +`hash`: _string_ - 32-byte block hash + +#### Returns + +`result`: _object_ - [miner data object](objects.md#miner-data-object) + + + +# curl HTTP + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method": "eth_getMinerDataByBlockHash","params": ["0xbf137c3a7a1ebdfac21252765e5d7f40d115c2757e4a4abee929be88c624fdb7"],"id": 1}' http://127.0.0.1:8545 +``` + +# wscat WS + +```json +{ + "jsonrpc": "2.0", + "method": "eth_getMinerDataByBlockHash", + "params": [ + "0xbf137c3a7a1ebdfac21252765e5d7f40d115c2757e4a4abee929be88c624fdb7" + ], + "id": 1 +} +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + "netBlockReward": "0x47c6f3739f3da800", + "staticBlockReward": "0x4563918244f40000", + "transactionFee": "0x38456548220800", + "uncleInclusionReward": "0x22b1c8c1227a000", + "uncleRewards": [ + { + "hash": "0x2422d43b4f72e19faf4368949a804494f67559405046b39c6d45b1bd53044974", + "coinbase": "0x0c062b329265c965deef1eede55183b3acb8f611" + } + ], + "coinbase": "0xb42b6c4a95406c78ff892d270ad20b22642e102d", + "extraData": "0xd583010502846765746885676f312e37856c696e7578", + "difficulty": "0x7348c20", + "totalDifficulty": "0xa57bcfdd96" + } +} +``` + + + +### `eth_getMinerDataByBlockNumber` + +Returns miner data for the specified block. + +#### Parameters + +`blockNumber`: _string_ - hexadecimal or decimal integer representing a block number or one of the string tags `latest`, `earliest`, `pending`, `finalized`, or `safe`, as described in [block parameter](../../how-to/use-besu-api/json-rpc.md#block-parameter) + +#### Returns + +`result`: _object_ - [miner data object](objects.md#miner-data-object) + + + +# curl HTTP + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method": "eth_getMinerDataByBlockNumber","params": ["0x7689D2"],"id": 1}' http://127.0.0.1:8545 +``` + +# wscat WS + +```json +{ + "jsonrpc": "2.0", + "method": "eth_getMinerDataByBlockNumber", + "params": ["0x7689D2"], + "id": 1 +} +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + "netBlockReward": "0x47c6f3739f3da800", + "staticBlockReward": "0x4563918244f40000", + "transactionFee": "0x38456548220800", + "uncleInclusionReward": "0x22b1c8c1227a000", + "uncleRewards": [ + { + "hash": "0x2422d43b4f72e19faf4368949a804494f67559405046b39c6d45b1bd53044974", + "coinbase": "0x0c062b329265c965deef1eede55183b3acb8f611" + } + ], + "coinbase": "0xb42b6c4a95406c78ff892d270ad20b22642e102d", + "extraData": "0xd583010502846765746885676f312e37856c696e7578", + "difficulty": "0x7348c20", + "totalDifficulty": "0xa57bcfdd96" + } +} +``` + + + +### `eth_getProof` + +Returns the account and storage values of the specified account, including the Merkle proof. + +The API allows IoT devices or mobile apps which are unable to run light clients to verify responses from untrusted sources, by using a trusted block hash. + +#### Parameters + +`address`: _string_ - 20-byte address of the account or contract + +`keys`: _array_ of _strings_ - list of 32-byte storage keys to generate proofs for + +`blockNumber` or `blockHash`: _string_ - hexadecimal or decimal integer representing a block number, block hash, or one of the string tags `latest`, `earliest`, `pending`, `finalized`, or `safe`, as described in [block parameter](../../how-to/use-besu-api/json-rpc.md#block-parameter) + +#### Returns + +`result`: _object_ - account details object with the following fields: + +- `balance`: _string_ - account balance + +- `codeHash`: _string_ - 32-byte hash of the account code + +- `nonce`: _string_ - number of transactions sent from the account + +- `storageHash`: _string_ - 32-byte SHA3 of the `storageRoot` + +- `accountProof`: _array_ of _strings_ - list of RLP-encoded Merkle tree nodes, starting with the `stateRoot` + +- `storageProof`: _array_ of _objects_ - list of storage entry objects with the following fields: + + - `key`: _string_ - storage key + + - `value`: _string_ - storage value + + - `proof`: _array_ of _strings_ - list of RLP-encoded Merkle tree nodes, starting with the `storageHash` + + + +# curl HTTP + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method": "eth_getProof","params": [ +"0a8156e7ee392d885d10eaa86afd0e323afdcd95", ["0x0000000000000000000000000000000000000000000000000000000000000347"], "latest"],"id": 1}' http://127.0.0.1:8545 +``` + +# wscat WS + +```json +{ + "jsonrpc": "2.0", + "method": "eth_getProof", + "params": [ + "0a8156e7ee392d885d10eaa86afd0e323afdcd95", + ["0x0000000000000000000000000000000000000000000000000000000000000347"], + "latest" + ], + "id": 1 +} +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + "accountProof": [ + "0xf90211a0...608d898380", + "0xf90211a0...ec33f19580", + "0xf901d1a0...9e55584480", + "0xf8718080...18e5777142" + ], + "address": "0x0a8156e7ee392d885d10eaa86afd0e323afdcd95", + "balance": "0x0", + "codeHash": "0x2b6975dcaf69f9bb9a3b30bb6a37b305ce440250bf0dd2f23338cb18e5777142", + "nonce": "0x5f", + "storageHash": "0x917688de43091589aa58c1dfd315105bc9de4478b9ba7471616a4d8a43d46203", + "storageProof": [ + { + "key": "0x0000000000000000000000000000000000000000000000000000000000000347", + "value": "0x0", + "proof": [ + "0xf90211a0...5176779280", + "0xf901f1a0...c208d86580", + "0xf8d180a0...1ce6808080" + ] + } + ] + } +} +``` + + + +### `eth_getStorageAt` + +Returns the value of a storage position at a specified address. + +#### Parameters + +`address`: _string_ - 20-byte storage address + +`index`: _string_ - integer index of the storage position + +`blockNumber` or `blockHash`: _string_ - hexadecimal or decimal integer representing a block number, block hash, or one of the string tags `latest`, `earliest`, `pending`, `finalized`, or `safe`, as described in [block parameter](../../how-to/use-besu-api/json-rpc.md#block-parameter) + +#### Returns + +`result` : _string_ - value at the specified storage position + +Calculating the correct position depends on the storage you want to retrieve. + + + +# curl HTTP + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method": "eth_getStorageAt","params": ["0x‭3B3F3E‬","0x0","latest"],"id": 53}' http://127.0.0.1:8545 +``` + +# wscat WS + +```json +{ + "jsonrpc": "2.0", + "method": "eth_getStorageAt", + "params": ["0x‭3B3F3E‬", "0x0", "latest"], + "id": 53 +} +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 53, + "result": "0x0000000000000000000000000000000000000000000000000000000000000000" +} +``` + +# curl GraphQL + +```bash +curl -X POST -H "Content-Type: application/json" --data '{ "query": "{account(address: \"0xfe3b557e8fb62b89f4916b721be55ceb828dbd73\") {storage(slot: \"0x04\")}}"}' http://localhost:8547/graphql +``` + +# GraphQL + +```text +{ + account(address: "0xfe3b557e8fb62b89f4916b721be55ceb828dbd73") { + storage(slot: "0x04") + } +} +``` + +# GraphQL result + +```json +{ + "data": { + "account": { + "storage": "0x0000000000000000000000000000000000000000000000000000000000000000" + } + } +} +``` + + + +### `eth_getTransactionByBlockHashAndIndex` + +Returns transaction information for the specified block hash and transaction index position. + +#### Parameters + +`block`: _string_ - 32-byte hash of a block + +`index`: _string_ - integer representing the transaction index position + +#### Returns + +`result`: _object_ - [transaction object](objects.md#transaction-object), or `null` when there is no transaction + + + +# curl HTTP + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"eth_getTransactionByBlockHashAndIndex","params":["0xbf137c3a7a1ebdfac21252765e5d7f40d115c2757e4a4abee929be88c624fdb7", "0x2"], "id":1}' http://127.0.0.1:8545 +``` + +# wscat WS + +```json +{ + "jsonrpc": "2.0", + "method": "eth_getTransactionByBlockHashAndIndex", + "params": [ + "0xbf137c3a7a1ebdfac21252765e5d7f40d115c2757e4a4abee929be88c624fdb7", + "0x2" + ], + "id": 1 +} +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + "blockHash": "0xbf137c3a7a1ebdfac21252765e5d7f40d115c2757e4a4abee929be88c624fdb7", + "blockNumber": "0x1442e", + "chainId": 2018, + "from": "0x70c9217d814985faef62b124420f8dfbddd96433", + "gas": "0x3d090", + "gasPrice": "0x57148a6be", + "hash": "0xfc766a71c406950d4a4955a340a092626c35083c64c7be907060368a5e6811d6", + "input": "0x51a34eb8000000000000000000000000000000000000000000000029b9e659e41b780000", + "nonce": "0x2cb2", + "to": "0xcfdc98ec7f01dab1b67b36373524ce0208dc3953", + "transactionIndex": "0x2", + "value": "0x0", + "v": "0x2a", + "r": "0xa2d2b1021e1428740a7c67af3c05fe3160481889b25b921108ac0ac2c3d5d40a", + "s": "0x63186d2aaefe188748bfb4b46fb9493cbc2b53cf36169e8501a5bc0ed941b484" + } +} +``` + +# curl GraphQL + +```bash +curl -X POST -H "Content-Type: application/json" --data '{"query": "{ block(hash: \"0x9270651f9c6fa36232c379d0ecf69b519383aa275815a65f1e03114346668f69\") { transactionAt(index: 0) {block{hash} hash } } }"}' http://localhost:8547/graphql +``` + +# GraphQL + +```text +{ + block(hash: "0x9270651f9c6fa36232c379d0ecf69b519383aa275815a65f1e03114346668f69") { + transactionAt(index: 0) { + block { + hash + } + hash + } + } +} +``` + +# GraphQL result + +```json +{ + "data": { + "block": { + "transactionAt": { + "block": { + "hash": "0x9270651f9c6fa36232c379d0ecf69b519383aa275815a65f1e03114346668f69" + }, + "hash": "0x5f5366af89e8777d5ae62a1af94a0876bdccbc22417bed0aff361eefa3e37f86" + } + } + } +} +``` + + + +### `eth_getTransactionByBlockNumberAndIndex` + +Returns transaction information for the specified block number and transaction index position. + +#### Parameters + +`blockNumber`: _string_ - hexadecimal or decimal integer representing a block number or one of the string tags `latest`, `earliest`, `pending`, `finalized`, or `safe`, as described in [block parameter](../../how-to/use-besu-api/json-rpc.md#block-parameter) + +`index`: _string_ - transaction index position + +#### Returns + +`result`: _object_ - [transaction object](objects.md#transaction-object), or `null` when there is no transaction + + + +This request returns the third transaction in the 82990 block on the Ropsten testnet. You can also view this [block](https://ropsten.etherscan.io/txs?block=82990) and [transaction] on Etherscan. + +# curl HTTP + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"eth_getTransactionByBlockNumberAndIndex","params":["82990", "0x2"], "id":1}' http://127.0.0.1:8545 +``` + +# wscat WS + +```json +{ + "jsonrpc": "2.0", + "method": "eth_getTransactionByBlockNumberAndIndex", + "params": ["82990", "0x2"], + "id": 1 +} +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + "blockHash": "0xbf137c3a7a1ebdfac21252765e5d7f40d115c2757e4a4abee929be88c624fdb7", + "blockNumber": "0x1442e", + "chainId": 2018, + "from": "0x70c9217d814985faef62b124420f8dfbddd96433", + "gas": "0x3d090", + "gasPrice": "0x57148a6be", + "hash": "0xfc766a71c406950d4a4955a340a092626c35083c64c7be907060368a5e6811d6", + "input": "0x51a34eb8000000000000000000000000000000000000000000000029b9e659e41b780000", + "nonce": "0x2cb2", + "to": "0xcfdc98ec7f01dab1b67b36373524ce0208dc3953", + "transactionIndex": "0x2", + "value": "0x0", + "v": "0x2a", + "r": "0xa2d2b1021e1428740a7c67af3c05fe3160481889b25b921108ac0ac2c3d5d40a", + "s": "0x63186d2aaefe188748bfb4b46fb9493cbc2b53cf36169e8501a5bc0ed941b484" + } +} +``` + +# curl GraphQL + +```bash +curl -X POST -H "Content-Type: application/json" --data '{"query": "{block(number:20303) {transactionAt(index: 0) {block{hash} hash}}}"}' http://localhost:8547/graphql +``` + +# GraphQL + +```text +{ + block(number: 20303) { + transactionAt(index: 0) { + block { + hash + } + hash + } + } +} +``` + +# GraphQL result + +```json +{ + "data": { + "block": { + "transactionAt": { + "block": { + "hash": "0x9270651f9c6fa36232c379d0ecf69b519383aa275815a65f1e03114346668f69" + }, + "hash": "0x5f5366af89e8777d5ae62a1af94a0876bdccbc22417bed0aff361eefa3e37f86" + } + } + } +} +``` + + + +### `eth_getTransactionByHash` + +Returns transaction information for the specified transaction hash. + +#### Parameters + +`transaction`: _string_ - 32-byte transaction hash + +#### Returns + +`result`: _object_ - [transaction object](objects.md#transaction-object), or `null` when there is no transaction + + + +# curl HTTP + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"eth_getTransactionByHash","params":["0xa52be92809541220ee0aaaede6047d9a6c5d0cd96a517c854d944ee70a0ebb44"],"id":53}' http://127.0.0.1:8545 +``` + +# wscat WS + +```json +{ + "jsonrpc": "2.0", + "method": "eth_getTransactionByHash", + "params": [ + "0xa52be92809541220ee0aaaede6047d9a6c5d0cd96a517c854d944ee70a0ebb44" + ], + "id": 53 +} +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 53, + "result": { + "blockHash": "0x510efccf44a192e6e34bcb439a1947e24b86244280762cbb006858c237093fda", + "blockNumber": "0x422", + "chainId": 2018, + "from": "0xfe3b557e8fb62b89f4916b721be55ceb828dbd73", + "gas": "0x5208", + "gasPrice": "0x3b9aca00", + "hash": "0xa52be92809541220ee0aaaede6047d9a6c5d0cd96a517c854d944ee70a0ebb44", + "input": "0x", + "nonce": "0x1", + "to": "0x627306090abab3a6e1400e9345bc60c78a8bef57", + "transactionIndex": "0x0", + "value": "0x4e1003b28d9280000", + "v": "0xfe7", + "r": "0x84caf09aefbd5e539295acc67217563438a4efb224879b6855f56857fa2037d3", + "s": "0x5e863be3829812c81439f0ae9d8ecb832b531d651fb234c848d1bf45e62be8b9" + } +} +``` + +# curl GraphQL + +```bash +curl -X POST -H "Content-Type: application/json" --data '{"query": "{transaction(hash : \"0x03d80b9ca0a71435399a268609d6d7896f7155d2147cc22b780672bcb59b170d\") { block{hash} gas gasPrice hash nonce value from {address} to {address} status}}"}' http://localhost:8547/graphql +``` + +# GraphQL + +```text +{ + transaction(hash: "0x03d80b9ca0a71435399a268609d6d7896f7155d2147cc22b780672bcb59b170d") { + block { + hash + } + gas + gasPrice + hash + nonce + value + from { + address + } + to { + address + } + status + } +} +``` + +# GraphQL result + +```json +{ + "data": { + "transaction": { + "block": { + "hash": "0xb1ef35744bade6980c3a933024b2557a8c724a19e5fdd2116bac712aa5e57198" + }, + "gas": 21000, + "gasPrice": "0x2540be400", + "hash": "0x03d80b9ca0a71435399a268609d6d7896f7155d2147cc22b780672bcb59b170d", + "nonce": 6, + "value": "0x8ac7230489e80000", + "from": { + "address": "0xfe3b557e8fb62b89f4916b721be55ceb828dbd73" + }, + "to": { + "address": "0x9d8f8572f345e1ae53db1dfa4a7fce49b467bd7f" + }, + "status": 1 + } + } +} +``` + + + +### `eth_getTransactionCount` + +Returns the number of transactions sent from a specified address. Use the `pending` tag to get the next account nonce not used by any pending transactions. + +#### Parameters + +`address`: _string_ - 20-byte account address + +`blockNumber` or `blockHash`: _string_ - hexadecimal or decimal integer representing a block number, block hash, or one of the string tags `latest`, `earliest`, `pending`, `finalized`, or `safe`, as described in [block parameter](../../how-to/use-besu-api/json-rpc.md#block-parameter) + +#### Returns + +`result`: _string_ - integer representing the number of transactions sent from the specified address + + + +# curl HTTP + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"eth_getTransactionCount","params":["0xc94770007dda54cF92009BFF0dE90c06F603a09f","latest"],"id":1}' http://127.0.0.1:8545 +``` + +# wscat WS + +```json +{ + "jsonrpc": "2.0", + "method": "eth_getTransactionCount", + "params": ["0xc94770007dda54cF92009BFF0dE90c06F603a09f", "latest"], + "id": 1 +} +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": "0x1" +} +``` + +# curl GraphQL + +```bash +curl -X POST -H "Content-Type: application/json" --data '{ "query": "{ account (address:\"0xfe3b557e8fb62b89f4916b721be55ceb828dbd73\"){transactionCount}}"}' http://localhost:8547/graphql +``` + +# GraphQL + +```text +{ + account(address: "0xfe3b557e8fb62b89f4916b721be55ceb828dbd73") { + transactionCount + } +} +``` + +# GraphQL result + +```json +{ + "data": { + "account": { + "transactionCount": 5 + } + } +} +``` + + + +### `eth_getTransactionReceipt` + +Returns the receipt of a transaction by transaction hash. Receipts for pending transactions are not available. + +If you enabled [revert reason](../../../private-networks/how-to/send-transactions/revert-reason.md), the receipt includes available revert reasons in the response. + +#### Parameters + +`transaction`: _string_ - 32-byte hash of a transaction + +#### Returns + +`result`: _object_ - [transaction receipt object](objects.md#transaction-receipt-object), or `null` when there is no receipt + + + +# curl HTTP + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"eth_getTransactionReceipt","params":["0x504ce587a65bdbdb6414a0c6c16d86a04dd79bfcc4f2950eec9634b30ce5370f"],"id":53}' http://127.0.0.1:8545 +``` + +# wscat WS + +```json +{ + "jsonrpc": "2.0", + "method": "eth_getTransactionReceipt", + "params": [ + "0x504ce587a65bdbdb6414a0c6c16d86a04dd79bfcc4f2950eec9634b30ce5370f" + ], + "id": 53 +} +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + "blockHash": "0xe7212a92cfb9b06addc80dec2a0dfae9ea94fd344efeb157c41e12994fcad60a", + "blockNumber": "0x50", + "contractAddress": null, + "cumulativeGasUsed": "0x5208", + "from": "0x627306090abab3a6e1400e9345bc60c78a8bef57", + "gasUsed": "0x5208", + "effectiveGasPrice": "0x1", + "logs": [], + "logsBloom": "0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000", + "status": "0x1", + "to": "0xf17f52151ebef6c7334fad080c5704d77216b732", + "transactionHash": "0xc00e97af59c6f88de163306935f7682af1a34c67245e414537d02e422815efc3", + "transactionIndex": "0x0" + } +} +``` + +# curl GraphQL + +```bash +curl -X POST -H "Content-Type: application/json" --data '{"query": "{transaction(hash: \"0x5f5366af89e8777d5ae62a1af94a0876bdccbc22417bed0aff361eefa3e37f86\") {block{hash logsBloom} hash createdContract{address} cumulativeGasUsed gas gasUsed logs{topics} from{address} to{address} index}}"}' http://localhost:8547/graphql +``` + +# GraphQL + +```text +{ + transaction(hash: "0x5f5366af89e8777d5ae62a1af94a0876bdccbc22417bed0aff361eefa3e37f86") { + block { + hash + logsBloom + } + hash + createdContract { + address + } + cumulativeGasUsed + gas + gasUsed + logs { + topics + } + from { + address + } + to { + address + } + index + } +} +``` + +# GraphQL result + +```json +{ + "data": { + "transaction": { + "block": { + "hash": "0x9270651f9c6fa36232c379d0ecf69b519383aa275815a65f1e03114346668f69", + "logsBloom": "0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000" + }, + "hash": "0x5f5366af89e8777d5ae62a1af94a0876bdccbc22417bed0aff361eefa3e37f86", + "createdContract": null, + "cumulativeGasUsed": 21000, + "gas": 21000, + "gasUsed": 21000, + "effectiveGasPrice": "0x1", + "logs": [], + "from": { + "address": "0xfe3b557e8fb62b89f4916b721be55ceb828dbd73" + }, + "to": { + "address": "0x9d8f8572f345e1ae53db1dfa4a7fce49b467bd7f" + }, + "index": 0 + } + } +} +``` + + + +### `eth_getUncleByBlockHashAndIndex` + +Returns uncle specified by block hash and index. + +#### Parameters + +`block`: _string_ - 32-byte block hash + +`uncleIndex`: _string_ - index of the uncle + +#### Returns + +`result`: _object_ - [block object](objects.md#block-object) + +:::note + +Uncles don't contain individual transactions. + +::: + + + +# curl HTTP + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"eth_getUncleByBlockHashAndIndex","params":["0xc48fb64230a82f65a08e7280bd8745e7fea87bc7c206309dee32209fe9a985f7", "0x0"],"id":1}' http://127.0.0.1:8545 +``` + +# wscat WS + +```json +{ + "jsonrpc": "2.0", + "method": "eth_getUncleByBlockHashAndIndex", + "params": [ + "0xc48fb64230a82f65a08e7280bd8745e7fea87bc7c206309dee32209fe9a985f7", + "0x0" + ], + "id": 1 +} +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + "difficulty": "0x76b123df93230", + "extraData": "0x50505945206e616e6f706f6f6c2e6f7267", + "gasLimit": "0x7a121d", + "gasUsed": "0x7a0175", + "hash": "0xc20189c0b1a4a23116ab3b177e929137f6e826f17fc4c2e880e7258c620e9817", + "logsBloom": "0x890086c024487ca422be846a201a10e41bc2882902312116c1119609482031e9c000e2a708004a10281024028020c505727a12570c4810121c59024490b040894406a1c23c37a0094810921da3923600c71c03044b40924280038d07ab91964a008084264a01641380798840805a284cce201a8026045451002500113a00de441001320805ca2840037000111640d090442c11116d2112948084240242340400236ce81502063401dcc214b9105194d050884721c1208800b20501a4201400276004142f118e60808284506979a86e050820101c170c185e2310005205a82a2100382422104182090184800c02489e033440218142140045801c024cc1818485", + "miner": "0x52bc44d5378309ee2abf1539bf71de1b7d7be3b5", + "mixHash": "0xf557cc827e058862aa3ea1bd6088fb8766f70c0eac4117c56cf85b7911f82a14", + "nonce": "0xd320b48904347cdd", + "number": "0x768964", + "parentHash": "0x98d752708b3677df8f439c4529f999b94663d5494dbfc08909656db3c90f6255", + "receiptsRoot": "0x0f838f0ceb73368e7fc8d713a7761e5be31e3b4beafe1a6875a7f275f82da45b", + "sha3Uncles": "0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347", + "size": "0x21a", + "stateRoot": "0xa0c7d4fca79810c89c517eff8dadb9c6d6f4bcc27c2edfb301301e1cf7dec642", + "timestamp": "0x5cdcbba6", + "totalDifficulty": "0x229ad33cabd4c40d23d", + "transactionsRoot": "0x866e38e91d01ef0387b8e07ccf35cd910224271ccf2b7477b8c8439e8b70f365", + "uncles": [] + } +} +``` + +# curl GraphQL + +```bash +curl -X POST -H "Content-Type: application/json" --data '{ "query": "{block(hash:\"0xc48fb64230a82f65a08e7280bd8745e7fea87bc7c206309dee32209fe9a985f7\"){ ommerAt(index: 0) {difficulty extraData gasLimit gasUsed hash logsBloom mixHash nonce number receiptsRoot stateRoot timestamp totalDifficulty transactionsRoot}}}"}' http://localhost:8547/graphql +``` + +# GraphQL + +```text +{ + block(hash: "0xc48fb64230a82f65a08e7280bd8745e7fea87bc7c206309dee32209fe9a985f7") { + ommerAt(index: 0) { + difficulty + extraData + gasLimit + gasUsed + hash + logsBloom + mixHash + nonce + number + receiptsRoot + stateRoot + timestamp + totalDifficulty + transactionsRoot + } + } +} +``` + +# GraphQL result + +```json +{ + "data": { + "block": { + "difficulty": "0x1", + "extraData": "0xf882a00000000000000000000000000000000000000000000000000000000000000000d5949811ebc35d7b06b3fa8dc5809a1f9c52751e1deb808400000000f843b8418e98ef756acdae1e510b1df4b507b7af04eb3802db7fa0f3e73e7d0721b3645e76f4eb3d0dbf0de75620c4405bd5a663247cdd9616482c883053856d857f884a01", + "gasLimit": 4700000, + "gasUsed": 0, + "hash": "0x0efe67972b982eb6be5df84e5238eb07475f86afa8a7de708f6a13ac0ff60d6c", + "logsBloom": "0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000", + "mixHash": "0x63746963616c2062797a616e74696e65206661756c7420746f6c6572616e6365", + "nonce": "0x0000000000000000", + "number": 200, + "receiptsRoot": "0x56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421", + "stateRoot": "0xd650578a04b39f50cc979155f4510ec28c2c0a7c1e5fdbf84609bc7b1c430f48", + "timestamp": "0x5cd109fb", + "totalDifficulty": "0xc9", + "transactionsRoot": "0x56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421" + } + } +} +``` + + + +### `eth_getUncleByBlockNumberAndIndex` + +Returns uncle specified by block number and index. + +#### Parameters + +- `blockNumber`: _string_ - hexadecimal or decimal integer representing a block number or one of the string tags `latest`, `earliest`, `pending`, `finalized`, or `safe`, as described in [block parameter](../../how-to/use-besu-api/json-rpc.md#block-parameter) + +- `uncleIndex`: _string_ - index of the uncle + +#### Returns + +`result`: _object_ - [block object](objects.md#block-object) + +:::note + +Uncles do not contain individual transactions. + +::: + + + +# curl HTTP + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"eth_getUncleByBlockNumberAndIndex","params":["0x7689D2", "0x0"],"id":1}' http://127.0.0.1:8545 +``` + +# wscat WS + +```json +{ + "jsonrpc": "2.0", + "method": "eth_getUncleByBlockNumberAndIndex", + "params": ["0x7689D2", "0x0"], + "id": 1 +} +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + "difficulty": "0x77daec467bf93", + "extraData": "0x50505945206e616e6f706f6f6c2e6f7267", + "gasLimit": "0x7a121d", + "gasUsed": "0x7a0f7b", + "hash": "0x42d83ae9c0743f4b1f9c61ff7ea8b164c1bab3627decd49233760680be006ecf", + "logsBloom": "0x888200800000340120220008640200500408006100038400100581c000080240080a0014e8002010080004088040004022402a000c18010001400100002a041141a0610a0052900600041018c0002a0003090020404c00206010010513d00020005380124e08050480710000000108401012b0901c1424006000083a10a8c1040100a0440081050210124400040044304070004001100000012600806008061d0320800000b40042160600002480000000800000c0002100200940801c000820800048024904710000400640490026000a44300309000286088010c2300060003011380006400200812009144042204810209020410a84000410520c08802941", + "miner": "0x52bc44d5378309ee2abf1539bf71de1b7d7be3b5", + "mixHash": "0xf977fcdb52868be410b75ef2becc35cc312f13ab0a6ce400ecd9d445f66fa3f2", + "nonce": "0x628b28403bf1e3d3", + "number": "0x7689d0", + "parentHash": "0xb32cfdfbf4adb05d30f02fcc6fe039cc6666402142954051c1a1cb9cc91aa11e", + "receiptsRoot": "0x9c7c8361d1a24ea2841432234c81974a9920d3eba2b2b1c496b5f925a95cb4ac", + "sha3Uncles": "0x7d972aa1b182b7e93f1db043f03fbdbfac6874fe7e67e162141bcc0aefa6336b", + "size": "0x21a", + "stateRoot": "0x74e97b77813146344d75acb5a52a006cc6dfaca678a10fb8a484a8443e919272", + "timestamp": "0x5cdcc0a7", + "totalDifficulty": "0x229b0583b4bd2698ca0", + "transactionsRoot": "0x1d21626afddf05e5866de66ca3fcd98f1caf5357eba0cc6ec675606e116a891b", + "uncles": [] + } +} +``` + +# curl GraphQL + +```bash +curl -X POST -H "Content-Type: application/json" --data '{ "query": "{block(number:2587){ ommerAt(index: 0) {difficulty extraData gasLimit gasUsed hash logsBloom mixHash nonce number receiptsRoot stateRoot timestamp totalDifficulty transactionsRoot}}}"}' http://localhost:8547/graphql +``` + +# GraphQL + +```text +{ + block(number: 2587) { + ommerAt(index: 0) { + difficulty + extraData + gasLimit + gasUsed + hash + logsBloom + mixHash + nonce + number + receiptsRoot + stateRoot + timestamp + totalDifficulty + transactionsRoot + } + } +} +``` + +# GraphQL result + +```json +{ + "data": { + "block": { + "ommerAt": null + } + } +} +``` + + + +### `eth_getUncleCountByBlockHash` + +Returns the number of uncles in a block from a block matching the given block hash. + +#### Parameters + +`block`: _string_ - 32-byte block hash + +#### Returns + +`result`: _string_ - integer representing the number of uncles in the specified block + + + +# curl HTTP + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"eth_getUncleCountByBlockHash","params":["0xb903239f8543d04b5dc1ba6579132b143087c68db1b2168786408fcbce568238"],"id":1}' http://127.0.0.1:8545 +``` + +# wscat WS + +```json +{ + "jsonrpc": "2.0", + "method": "eth_getUncleCountByBlockHash", + "params": [ + "0xb903239f8543d04b5dc1ba6579132b143087c68db1b2168786408fcbce568238" + ], + "id": 1 +} +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": 0x0 +} +``` + +# curl GraphQL + +```bash +curl -X POST -H "Content-Type: application/json" --data '{ "query": "{block(hash:\"0x65c08d792e4192b9ece6b6f2390da7da464208b22d88490be8add9373917b426\"){ommerCount}}"}' http://localhost:8547/graphql +``` + +# GraphQL + +```text +{ + block(hash: "0x65c08d792e4192b9ece6b6f2390da7da464208b22d88490be8add9373917b426") { + ommerCount + } +} +``` + +# GraphQL result + +```json +{ + "data": { + "block": { + "ommerCount": 2 + } + } +} +``` + + + +### `eth_getUncleCountByBlockNumber` + +Returns the number of uncles in a block matching the specified block number. + +#### Parameters + +`blockNumber`: _string_ - hexadecimal or decimal integer representing a block number or one of the string tags `latest`, `earliest`, `pending`, `finalized`, or `safe`, as described in [block parameter](../../how-to/use-besu-api/json-rpc.md#block-parameter) + +#### Returns + +`result`: _string_ - integer representing the number of uncles in the specified block + + + +# curl HTTP + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"eth_getUncleCountByBlockNumber","params":["0xe8"],"id":1}' http://127.0.0.1:8545 +``` + +# wscat WS + +```json +{ + "jsonrpc": "2.0", + "method": "eth_getUncleCountByBlockNumber", + "params": ["0xe8"], + "id": 1 +} +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": "0x1" +} +``` + +# curl GraphQL + +```bash +curl -X POST -H "Content-Type: application/json" --data '{ "query": "{block(number:\"0x59fd\"){ommerCount}}"}' http://localhost:8547/graphql +``` + +# GraphQL + +```text +{ + block(number: "0x59fd") { + ommerCount + } +} +``` + +# GraphQL result + +```json +{ + "data": { + "block": { + "ommerCount": 0 + } + } +} +``` + + + +### `eth_getWork` + +Returns the hash of the current block, the seed hash, and the required target boundary condition. + +#### Parameters + +None + +#### Returns + +`result`: _array_ of _strings_ - array with the following items: + +- `header`: _string_ - 32-byte hash of the current block header (PoW-hash) + +- `seed`: _string_ - 32-byte seed hash used for the DAG + +- `target`: _string_ - 32-byte required target boundary condition: 2^256 / difficulty + +- `blockNumber`: _string_ - hexadecimal integer representing the current block number + + + +# curl HTTP request + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"eth_getWork","params":[],"id":1}' http://127.0.0.1:8545 +``` + +# wscat WS request + +```json +{ "jsonrpc": "2.0", "method": "eth_getWork", "params": [], "id": 1 } +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": [ + "0xce5e32ca59cb86799a1879e90150b2c3b882852173e59865e9e79abb67a9d636", + "0x0000000000000000000000000000000000000000000000000000000000000000", + "0x00a3d70a3d70a3d70a3d70a3d70a3d70a3d70a3d70a3d70a3d70a3d70a3d70a3", + "0x42" + ] +} +``` + + + +### `eth_hashrate` + +Returns the number of hashes per second with which the node is mining. + +When the stratum server is enabled, this method returns the cumulative hashrate of all sealers reporting their hashrate. + +#### Parameters + +None + +#### Returns + +`result`: _string_ - number of hashes per second + + + +# curl HTTP request + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"eth_hashrate","params":[],"id":1}' http://127.0.0.1:8545 +``` + +# wscat WS request + +```bash +{"jsonrpc":"2.0","method":"eth_hashrate","params":[],"id":1} +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": "0x12b" +} +``` + + + +### `eth_mining` + +Whether the client is actively mining new blocks. Besu pauses mining while the client synchronizes with the network regardless of command settings or methods called. + +#### Parameters + +None + +#### Returns + +`result`: _boolean_ - indicates if the client is actively mining new blocks + + + +# curl HTTP request + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"eth_mining","params":[],"id":53}' http://127.0.0.1:8545 +``` + +# wscat WS request + +```json +{ "jsonrpc": "2.0", "method": "eth_mining", "params": [], "id": 53 } +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 53, + "result": true +} +``` + + + +### `eth_newBlockFilter` + +Creates a filter to retrieve new block hashes. To poll for new blocks, use [`eth_getFilterChanges`](#eth_getfilterchanges). + +#### Parameters + +None + +#### Returns + +`result`: _string_ - filter ID + + + +# curl HTTP request + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"eth_newBlockFilter","params":[],"id":1}' http://127.0.0.1:8545 +``` + +# wscat WS request + +```json +{ "jsonrpc": "2.0", "method": "eth_newBlockFilter", "params": [], "id": 1 } +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": "0x9d78b6780f844228b96ecc65a320a825" +} +``` + + + +### `eth_newFilter` + +Creates a [log filter](../../concepts/events-and-logs.md). To poll for logs associated with the created filter, use [`eth_getFilterChanges`](#eth_getfilterchanges). To get all logs associated with the filter, use [`eth_getFilterLogs`](#eth_getfilterlogs). + +#### Parameters + +`filterOptions`: _object_ - [filter options object](objects.md#filter-options-object) + +:::note + +`fromBlock` and `toBlock` in the filter options object default to `latest`. + +::: + +#### Returns + +`result`: _string_ - filter ID + + + +# curl HTTP request + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"eth_newFilter","params":[{"fromBlock":"earliest", "toBlock":"latest", "topics":[]}],"id":1}' http://127.0.0.1:8545 +``` + +# wscat WS request + +```json +{ + "jsonrpc": "2.0", + "method": "eth_newFilter", + "params": [{ "fromBlock": "earliest", "toBlock": "latest", "topics": [] }], + "id": 1 +} +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": "0x1ddf0c00989044e9b41cc0ae40272df3" +} +``` + + + +### `eth_newPendingTransactionFilter` + +Creates a filter to retrieve new pending transactions hashes. To poll for new pending transactions, use [`eth_getFilterChanges`](#eth_getfilterchanges). + +#### Parameters + +None + +#### Returns + +`result`: _string_ - filter ID + + + +# curl HTTP request + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"eth_newPendingTransactionFilter","params":[],"id":1}' http://127.0.0.1:8545 +``` + +# wscat WS request + +```json +{ + "jsonrpc": "2.0", + "method": "eth_newPendingTransactionFilter", + "params": [], + "id": 1 +} +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": "0x443d6a77c4964707a8554c92f7e4debd" +} +``` + + + +### `eth_protocolVersion` + +Returns current Ethereum protocol version. + +#### Parameters + +None + +#### Returns + +`result`: _string_ - Ethereum protocol version + + + +# curl HTTP + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"eth_protocolVersion","params":[],"id":1}' http://127.0.0.1:8545 +``` + +# wscat WS + +```json +{ "jsonrpc": "2.0", "method": "eth_protocolVersion", "params": [], "id": 1 } +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": "0x3f" +} +``` + +# curl GraphQL + +```bash +curl -X POST -H "Content-Type: application/json" --data '{ "query": "{protocolVersion}"}' http://localhost:8547/graphql +``` + +# GraphQL + +```text +{ + protocolVersion +} +``` + +# GraphQL result + +```json +{ + "data": { + "protocolVersion": 63 + } +} +``` + + + +### `eth_sendRawTransaction` + +Sends a [signed transaction](../../how-to/send-transactions.md). A transaction can send ether, deploy a contract, or interact with a contract. Set the maximum transaction fee for transactions using the [`--rpc-tx-feecap`](../cli/options.md#rpc-tx-feecap) CLI option. + +You can interact with contracts using `eth_sendRawTransaction` or [`eth_call`](#eth_call). + +To avoid exposing your private key, create signed transactions offline and send the signed transaction data using `eth_sendRawTransaction`. + +:::info + +Besu doesn't implement [`eth_sendTransaction`](../../how-to/send-transactions.md). + +[EthSigner](https://docs.ethsigner.consensys.net/) provides transaction signing and implements [`eth_sendTransaction`](https://docs.ethsigner.consensys.net/Reference/API-Methods#eth_sendtransaction). + +::: + +#### Parameters + +`transaction`: _string_ - signed transaction serialized to hexadecimal format + +:::note + +[Creating and sending transactions](../../how-to/send-transactions.md) includes examples of creating signed transactions using the [web3.js](https://github.com/ethereum/web3.js/) library. + +::: + +#### Returns + +`result`: _string_ - 32-byte transaction hash + + + +# curl HTTP + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"eth_sendRawTransaction","params":["0xf869018203e882520894f17f52151ebef6c7334fad080c5704d77216b732881bc16d674ec80000801ba02da1c48b670996dcb1f447ef9ef00b33033c48a4fe938f420bec3e56bfd24071a062e0aa78a81bf0290afbc3a9d8e9a068e6d74caa66c5e0fa8a46deaae96b0833"],"id":1}' http://127.0.0.1:8545 +``` + +# wscat WS + +```json +{ + "jsonrpc": "2.0", + "method": "eth_sendRawTransaction", + "params": [ + "0xf869018203e882520894f17f52151ebef6c7334fad080c5704d77216b732881bc16d674ec80000801ba02da1c48b670996dcb1f447ef9ef00b33033c48a4fe938f420bec3e56bfd24071a062e0aa78a81bf0290afbc3a9d8e9a068e6d74caa66c5e0fa8a46deaae96b0833" + ], + "id": 1 +} +``` + +# JSON result + +```json +{ + "id": 1, + "jsonrpc": "2.0", + "result": "0xe670ec64341771606e55d6b4ca35a1a6b75ee3d5145a99d05921026d1527331" +} +``` + +# curl GraphQL + +```bash +curl -X POST -H "Content-Type: application/json" --data '{ "query": "mutation {sendRawTransaction(data: \"0xf869018203e882520894f17f52151ebef6c7334fad080c5704d77216b732881bc16d674ec80000801ba02da1c48b670996dcb1f447ef9ef00b33033c48a4fe938f420bec3e56bfd24071a062e0aa78a81bf0290afbc3a9d8e9a068e6d74caa66c5e0fa8a46deaae96b0833\")}"}' http://localhost:8547/graphql +``` + +# GraphQL + +```text +mutation { + sendRawTransaction(data: "0xf869018203e882520894f17f52151ebef6c7334fad080c5704d77216b732881bc16d674ec80000801ba02da1c48b670996dcb1f447ef9ef00b33033c48a4fe938f420bec3e56bfd24071a062e0aa78a81bf0290afbc3a9d8e9a068e6d74caa66c5e0fa8a46deaae96b0833") +} +``` + +# GraphQL result + +```json +{ + "data": { + "sendRawTransaction": "0xe670ec64341771606e55d6b4ca35a1a6b75ee3d5145a99d05921026d1527331" + } +} +``` + + + +### `eth_submitHashrate` + +Submits the mining hashrate. This is used by mining software such as [Ethminer](https://github.com/ethereum-mining/ethminer). + +#### Parameters + +- `hashrate`: _string_ - 32-byte hexadecimal string representation of the hashrate + +- `id`: _string_ - 32-byte random hexadecimal ID identifying the client + +#### Returns + +`result`: _boolean_ - indicates if submission is successful + + + +# curl HTTP request + +```bash +curl -X POST --data '{"jsonrpc":"2.0", "method":"eth_submitHashrate", "params":["0x0000000000000000000000000000000000000000000000000000000000500000", "0x59daa26581d0acd1fce254fb7e85952f4c09d0915afd33d3886cd914bc7d283c"],"id":1}' http://127.0.0.1:8545 +``` + +# wscat WS request + +```json +{ + "jsonrpc": "2.0", + "method": "eth_submitHashrate", + "params": [ + "0x0000000000000000000000000000000000000000000000000000000000500000", + "0x59daa26581d0acd1fce254fb7e85952f4c09d0915afd33d3886cd914bc7d283c" + ], + "id": 1 +} +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": true +} +``` + + + +### `eth_submitWork` + +Submits a proof of work (Ethash) solution. This is used by mining software such as [Ethminer](https://github.com/ethereum-mining/ethminer). + +#### Parameters + +- `nonce`: _string_ - retrieved 8-byte nonce + +- `header`: _string_ - 32-byte hash of the block header (PoW-hash) + +- `digest`: _string_ - 32-bytes mix digest + +#### Returns + +`result`: _boolean_ - indicates if the provided solution is valid + + + +# curl HTTP request + +```bash +curl -X POST --data '{"jsonrpc":"2.0", "method":"eth_submitWork", "params":["0x0000000000000001", "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef", "0xD1GE5700000000000000000000000000D1GE5700000000000000000000000000"],"id":1}' http://127.0.0.1:8545 +``` + +# wscat WS request + +```bash +{"jsonrpc":"2.0", "method":"eth_submitWork", "params":["0x0000000000000001", "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef", "0xD1GE5700000000000000000000000000D1GE5700000000000000000000000000"],"id":73} +``` + +# JSON result + +```json +{ + "id": 1, + "jsonrpc": "2.0", + "result": true +} +``` + + + +### `eth_syncing` + +Returns an object with data about the synchronization status, or `false` if not synchronizing. + +:::note + +Once the node reaches the head of the chain, `eth_syncing` returns false, indicating that there is no active syncing target. + +::: + +#### Parameters + +None + +#### Returns + +`result`: _object_ or _boolean_ - synchronization status data object with the following fields, or `false` if not synchronizing: + +- `startingBlock`: _string_ - index of the highest block on the blockchain when the network synchronization starts + +- `currentBlock`: _string_ - index of the latest block (also known as the best block) for the current node (this is the same index that [`eth_blockNumber`](#eth_blocknumber) returns.) + +- `highestBlock`: _string_ - index of the highest known block in the peer network (that is, the highest block so far discovered among peer nodes. This is the same value as `currentBlock` if the current node has no peers.) + +- `pulledStates`: _string_ - if fast synchronizing, the number of state entries fetched so far, or `null` if this is not known or not relevant (if full synchronizing or fully synchronized, this field is not returned.) + +- `knownStates`: _string_ - if fast synchronizing, the number of states the node knows of so far, or `null` if this is not known or not relevant (if full synchronizing or fully synchronized, this field is not returned.) + + + +# curl HTTP + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"eth_syncing","params":[],"id":51}' http://127.0.0.1:8545 +``` + +# wscat WS + +```json +{ "jsonrpc": "2.0", "method": "eth_syncing", "params": [], "id": 51 } +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 51, + "result": { + "startingBlock": "0x0", + "currentBlock": "0x1518", + "highestBlock": "0x9567a3", + "pulledStates": "0x203ca", + "knownStates": "0x200636" + } +} +``` + +# curl GraphQL + +```bash +curl -X POST -H "Content-Type: application/json" --data '{ "query": "{syncing{startingBlock currentBlock highestBlock pulledStates knownStates}}"}' http://localhost:8547/graphql +``` + +# GraphQL + +```text +{ + syncing { + startingBlock + currentBlock + highestBlock + pulledStates + knownStates + } +} +``` + +# GraphQL result + +```json +{ + "data": { + "syncing": { + "startingBlock": 0, + "currentBlock": 5400, + "highestBlock": 9791395, + "pullStates": 132042, + "knownStates": 2098742 + } + } +} +``` + + + +### `eth_uninstallFilter` + +Uninstalls a filter with the specified ID. When a filter is no longer required, call this method. + +Filters time out when not requested by [`eth_getFilterChanges`](#eth_getfilterchanges) or [`eth_getFilterLogs`](#eth_getfilterlogs) for 10 minutes. + +#### Parameters + +`filterId`: _string_ - filter ID + +#### Returns + +`result`: _boolean_ - indicates if the filter is successfully uninstalled + + + +# curl HTTP request + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"eth_uninstallFilter","params":["0x70355a0b574b437eaa19fe95adfedc0a"],"id":1}' http://127.0.0.1:8545 +``` + +# wscat WS request + +```json +{ + "jsonrpc": "2.0", + "method": "eth_uninstallFilter", + "params": ["0x70355a0b574b437eaa19fe95adfedc0a"], + "id": 1 +} +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": true +} +``` + + + +## `MINER` methods + +The `MINER` API methods allow you to control the node’s mining operation. + +:::note + +The `MINER` API methods are not enabled by default for JSON-RPC. To enable the `MINER` API methods, use the [`--rpc-http-api`](../cli/options.md#rpc-http-api) or [`--rpc-ws-api`](../cli/options.md#rpc-ws-api) options. + +::: + +### `miner_changeTargetGasLimit` + +Updates the target gas limit set using the [`--target-gas-limit`](../cli/options.md#target-gas-limit) command line option. + +#### Parameters + +`gasPrice`: _number_ - target gas price in Wei + +#### Returns + +`result`: _string_ - `Success` or `error` + + + +# curl HTTP request + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"miner_changeTargetGasLimit","params":[800000], "id":1}' http://127.0.0.1:8545 +``` + +# wscat WS request + +```json +{ + "jsonrpc": "2.0", + "method": "miner_changeTargetGasLimit", + "params": [800000], + "id": 1 +} +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": "Success" +} +``` + + + +### `miner_setCoinbase` + +Sets the coinbase, the address for the mining rewards. + +:::note + +You can also use `miner_setEtherbase` as an alternative method. They both work the same way. Etherbase is a historic name for coinbase. + +::: + +#### Parameters + +`coinbase`: _string_ - Account address you pay mining rewards to + +#### Returns + +`result`: _boolean_ - `true` when address is set + + + +# curl HTTP request + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"miner_setCoinbase","params":["0xFE3B557E8Fb62b89F4916B721be55cEb828dBd73"],"id":1}' http://127.0.0.1:8545 +``` + +# wscat WS request + +```json +{ + "jsonrpc": "2.0", + "method": "miner_setCoinbase", + "params": ["0xFE3B557E8Fb62b89F4916B721be55cEb828dBd73"], + "id": 1 +} +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": true +} +``` + + + +### `miner_start` + +Starts the mining process. To start mining, you must first specify a miner coinbase using the [`--miner-coinbase`](../cli/options.md#miner-coinbase) command line option or using [`miner_setCoinbase`](#miner_setcoinbase). + +#### Parameters + +None + +#### Returns + +`result`: _boolean_ - `true` if mining starts, or if the node is already mining + + + +# curl HTTP request + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"miner_start","params":[],"id":1}' http://127.0.0.1:8545 +``` + +# wscat WS request + +```json +{ "jsonrpc": "2.0", "method": "miner_start", "params": [], "id": 1 } +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": true +} +``` + + + +### `miner_stop` + +Stops the mining process on the client. + +#### Parameters + +None + +#### Returns + +`result`: _boolean_ - `true` if mining stops, or if the node is not mining + + + +# curl HTTP request + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"miner_stop","params":[],"id":1}' http://127.0.0.1:8545 +``` + +# wscat WS request + +```json +{ "jsonrpc": "2.0", "method": "miner_stop", "params": [], "id": 1 } +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": true +} +``` + + + +## `NET` methods + +The `NET` API methods provide network-related information. + +### `net_enode` + +Returns the [enode URL](../../concepts/node-keys.md#enode-url). + +#### Parameters + +None + +#### Returns + +`result`: _string_ - [enode URL](../../concepts/node-keys.md#enode-url) of the node + + + +# curl HTTP request + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"net_enode","params":[],"id":1}' http://127.0.0.1:8545 +``` + +# wscat WS request + +```bash +{"jsonrpc":"2.0","method":"net_enode","params":[],"id":1} +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": "enode://6a63160d0ccef5e4986d270937c6c8d60a9a4d3b25471cda960900d037c61988ea14da67f69dbfb3497c465d0de1f001bb95598f74b68a39a5156a608c42fa1b@127.0.0.1:30303" +} +``` + + + +### `net_listening` + +Whether the client is actively listening for network connections. + +#### Parameters + +None + +#### Returns + +`result`: _boolean_ - indicates if the client is actively listening for network connections + + + +# curl HTTP request + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"net_listening","params":[],"id":53}' http://127.0.0.1:8545 +``` + +# wscat WS request + +```bash +{"jsonrpc":"2.0","method":"net_listening","params":[],"id":53} +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 53, + "result": true +} +``` + + + +### `net_peerCount` + +Returns the number of peers currently connected to the client. + +#### Parameters + +None + +#### Returns + +`result`: _string_ - number of connected peers in hexadecimal + + + +# curl HTTP request + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"net_peerCount","params":[],"id":53}' http://127.0.0.1:8545 +``` + +# wscat WS request + +```json +{ "jsonrpc": "2.0", "method": "net_peerCount", "params": [], "id": 53 } +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 53, + "result": "0x5" +} +``` + + + +### `net_services` + +Returns enabled services (for example, `jsonrpc`) and the host and port for each service. + +:::note + +The [`--nat-method`](../cli/options.md#nat-method) setting affects the JSON-RPC and P2P host and port values, but not the metrics host and port values. + +::: + +#### Parameters + +None + +#### Returns + +`result`: _object_ - enabled services + + + +# curl HTTP request + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"net_services","params":[],"id":1}' http://127.0.0.1:8545 +``` + +# wscat WS request + +```bash +{"jsonrpc":"2.0","method":"net_services","params":[],"id":1} +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + "jsonrpc": { + "host": "127.0.0.1", + "port": "8545" + }, + "p2p": { + "host": "127.0.0.1", + "port": "30303" + }, + "metrics": { + "host": "127.0.0.1", + "port": "9545" + } + } +} +``` + + + +### `net_version` + +Returns the [network ID](../../concepts/network-and-chain-id.md). + +#### Parameters + +None + +#### Returns + +`result`: _string_ - current network ID + +| Network ID | Chain | Network | Description | +| ---------- | ----- | ------- | ----------------------------- | +| `1` | ETH | Mainnet | Main Ethereum network | +| `5` | ETH | Goerli | PoS test network | +| `11155111` | ETH | Sepolia | PoS test network | +| `2018` | ETH | Dev | PoW development network | +| `1` | ETC | Classic | Main Ethereum Classic network | +| `7` | ETC | Mordor | PoW test network | + +:::note + +For almost all networks, network ID and chain ID are the same. + +The only networks in the table above with different network and chain IDs are Classic with a chain ID of `61` and Mordor with a chain ID of `63`. + +::: + + + +# curl HTTP request + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"net_version","params":[],"id":53}' http://127.0.0.1:8545 +``` + +# wscat WS request + +```json +{ "jsonrpc": "2.0", "method": "net_version", "params": [], "id": 53 } +``` + +# JSON result for Mainnet + +```json +{ + "jsonrpc": "2.0", + "id": 51, + "result": "1" +} +``` + +# JSON result for Goerli + +```json +{ + "jsonrpc": "2.0", + "id": 53, + "result": "5" +} +``` + + + +## `PLUGINS` methods + +The `PLUGINS` API methods provide plugin-related functionality. + +:::note + +The `PLUGINS` API methods are not enabled by default for JSON-RPC. To enable the `PLUGINS` API methods, use the [`--rpc-http-api`](../cli/options.md#rpc-http-api) or [`--rpc-ws-api`](../cli/options.md#rpc-ws-api) options. + +::: + +### `plugins_reloadPluginConfig` + +Reloads specified plugin configuration. + +#### Parameters + +`plugin`: _string_ - plugin + +#### Returns + +`result`: _string_ - `Success` + + + +# curl HTTP request + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"plugins_reloadPluginConfig","params":["tech.pegasys.plus.plugin.kafka.KafkaPlugin"],"id":1}' http://127.0.0.1:8545 +``` + +# wscat WS request + +```json +{ + "jsonrpc": "2.0", + "method": "plugins_reloadPluginConfig", + "params": ["tech.pegasys.plus.plugin.kafka.KafkaPlugin"], + "id": 1 +} +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": "Success" +} +``` + + + +## `TRACE` methods + +The `TRACE` API is a more concise alternative to the [`DEBUG` API](#debug-methods). + +:::note + +The `TRACE` API methods are not enabled by default for JSON-RPC. To enable the `TRACE` API methods, use the [`--rpc-http-api`](../cli/options.md#rpc-http-api) or [`--rpc-ws-api`](../cli/options.md#rpc-ws-api) options. + +::: + +### `trace_block` + +Provides transaction processing of [type `trace`](../trace-types.md#trace) for the specified block. + +:::tip + +Your node must be an archive node (that is, synchronized without pruning or fast sync) or the requested block must be within the number of [blocks retained](../cli/options.md#pruning-blocks-retained) with [pruning enabled](../cli/options.md#pruning-enabled) (by default, 1024). + +::: + +#### Parameters + +`blockNumber`: _string_ - hexadecimal or decimal integer representing a block number or one of the string tags `latest`, `earliest`, `pending`, `finalized`, or `safe`, as described in [block parameter](../../how-to/use-besu-api/json-rpc.md#block-parameter) + +#### Returns + +`result`: _array_ of _objects_ - list of [calls to other contracts](../trace-types.md#trace) containing one object per call, in transaction execution order; if revert reason is enabled with [`--revert-reason-enabled`](../cli/options.md#revert-reason-enabled), the returned list items include the [revert reason](../../../private-networks/how-to/send-transactions/revert-reason.md). + + + +# curl HTTP request + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"trace_block","params":["0x6"],"id":1}' http://127.0.0.1:8545 +``` + +# wscat WS request + +```json +{ "jsonrpc": "2.0", "method": "trace_block", "params": ["0x6"], "id": 1 } +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "result": [ + { + "action": { + "callType": "call", + "from": "0xfe3b557e8fb62b89f4916b721be55ceb828dbd73", + "gas": "0xffad82", + "input": "0x0000000000000000000000000000000000000999", + "to": "0x0020000000000000000000000000000000000000", + "value": "0x0" + }, + "blockHash": "0x71512d31e18f828cef069a87bc2c7514a8ca334f9ee72625efdf5cc2d43768dd", + "blockNumber": 6, + "result": { + "gasUsed": "0x7536", + "output": "0x" + }, + "subtraces": 1, + "traceAddress": [], + "transactionHash": "0x91eeabc671e2dd2b1c8ddebb46ba59e8cb3e7d189f80bcc868a9787728c6e59e", + "transactionPosition": 0, + "type": "call" + }, + { + "action": { + "address": "0x0020000000000000000000000000000000000000", + "balance": "0x300", + "refundAddress": "0x0000000000000999000000000000000000000000" + }, + "blockHash": "0x71512d31e18f828cef069a87bc2c7514a8ca334f9ee72625efdf5cc2d43768dd", + "blockNumber": 6, + "result": null, + "subtraces": 0, + "traceAddress": [0], + "transactionHash": "0x91eeabc671e2dd2b1c8ddebb46ba59e8cb3e7d189f80bcc868a9787728c6e59e", + "transactionPosition": 0, + "type": "suicide" + }, + { + "action": { + "author": "0x0000000000000000000000000000000000000000", + "rewardType": "block", + "value": "0x1bc16d674ec80000" + }, + "blockHash": "0x71512d31e18f828cef069a87bc2c7514a8ca334f9ee72625efdf5cc2d43768dd", + "blockNumber": 6, + "result": null, + "subtraces": 0, + "traceAddress": [], + "transactionHash": null, + "transactionPosition": null, + "type": "reward" + } + ], + "id": 1 +} +``` + + + +### `trace_call` + +Executes the given call and returns a number of possible traces for it. + +:::info + +The requested transaction must be contained in a block within the number of [blocks retained](../cli/options.md#pruning-blocks-retained) with [pruning enabled](../cli/options.md#pruning-enabled) (by default, 1024). + +::: + +#### Parameters + +- `call`: _object_ - [transaction call object](objects.md#transaction-call-object) + +- `blockNumber`: _string_ - hexadecimal or decimal integer representing a block number or one of the string tags `latest`, `earliest`, `pending`, `finalized`, or `safe`, as described in [block parameter](../../how-to/use-besu-api/json-rpc.md#block-parameter) + +- `options`: _array_ of _strings_ - list of tracing options; tracing options are [`trace`, `vmTrace`, and `stateDiff`](../trace-types.md). Specify any combination of the three options including none of them. + +#### Returns + +`result`: _array_ of _objects_ - list of [calls to other contracts](../trace-types.md#trace) containing one object per call, in transaction execution order + + + +# curl HTTP request + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"trace_call","params":[{"from":"0xfe3b557e8fb62b89f4916b721be55ceb828dbd73","to":"0x0010000000000000000000000000000000000000","gas":"0xfffff2","gasPrice":"0xef","value":"0x0","data":"0x0000000000000000000000000000000000000000000000000000000000000001000000000000000000000000000000000000000000000000000000000000000100000000000000000000000000000000000000000000000000000000000000020000000000000000000000000000000000000000000000000000000000000002","nonce":"0x0"},["trace"],"latest"],"id":1}' http://127.0.0.1:8545 +``` + +# wscat WS request + +```json +{ + "jsonrpc": "2.0", + "method": "trace_call", + "params": [ + { + "from": "0xfe3b557e8fb62b89f4916b721be55ceb828dbd73", + "to": "0x0010000000000000000000000000000000000000", + "gas": "0xfffff2", + "gasPrice": "0xef", + "value": "0x0", + "data": "0x0000000000000000000000000000000000000000000000000000000000000001000000000000000000000000000000000000000000000000000000000000000100000000000000000000000000000000000000000000000000000000000000020000000000000000000000000000000000000000000000000000000000000002", + "nonce": "0x0" + }, + ["trace"], + "latest" + ], + "id": 1 +} +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "result": { + "output" : "0x", + "stateDiff" : null, + "trace" : [ { + "action" : { + "callType" : "call", + "from" : "0xfe3b557e8fb62b89f4916b721be55ceb828dbd73", + "gas" : "0xffabba", + "input" : "0x0000000000000000000000000000000000000000000000000000000000000001000000000000000000000000000000000000000000000000000000000000000100000000000000000000000000000000000000000000000000000000000000020000000000000000000000000000000000000000000000000000000000000002", + "to" : "0x0010000000000000000000000000000000000000", + "value" : "0x0" + }, + "result" : { + "gasUsed" : "0x9c58", + "output" : "0x" + }, + "subtraces" : 0, + "traceAddress" : [ ], + "type" : "call" + } ], + "vmTrace" : null + }, +"id" : 2 +}, +``` + + + +### `trace_callMany` + +Performs multiple call traces on top of the same block. You can trace dependent transactions. + +:::info + +The requested block must be within the number of [blocks retained](../cli/options.md#pruning-blocks-retained) with [pruning enabled](../cli/options.md#pruning-enabled) (by default, 1024). + +::: + +#### Parameters + +- `options`: _array_ of _strings_ - list of tracing options; tracing options are [`trace`, `vmTrace`, and `stateDiff`](../trace-types.md). Specify any combination of the three options including none of them. + +- `blockNumber`: _string_ - hexadecimal or decimal integer representing a block number or one of the string tags `latest`, `earliest`, `pending`, `finalized`, or `safe`, as described in [block parameter](../../how-to/use-besu-api/json-rpc.md#block-parameter) + +#### Returns + +`result`: _array_ of _objects_ - list of [calls to other contracts](../trace-types.md#trace) containing one object per call, in transaction execution order + + + +# curl HTTP request + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"trace_callMany","params":[[[{"from":"0x407d73d8a49eeb85d32cf465507dd71d507100c1","to":"0xa94f5374fce5edbc8e2a8697c15331677e6ebf0b","value":"0x186a0"},["trace"]],[{"from":"0x407d73d8a49eeb85d32cf465507dd71d507100c1","to":"0xa94f5374fce5edbc8e2a8697c15331677e6ebf0b","value":"0x186a0"},["trace"]]],"latest"],"id":1}' http://127.0.0.1:8545 +``` + +# wscat WS request + +```json +{"jsonrpc":"2.0","method":"trace_callMany","params":[[[{"from":"0x407d73d8a49eeb85d32cf465507dd71d507100c1","to":"0xa94f5374fce5edbc8e2a8697c15331677e6ebf0b","value":"0x186a0"},["trace"]],[{"from":"0x407d73d8a49eeb85d32cf465507dd71d507100c1","to":"0xa94f5374fce5edbc8e2a8697c15331677e6ebf0b","value":"0x186a0"},["trace"]]],"latest"],"latest"],"id":1} +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "result": [ + { + "output" : "0x", + "stateDiff" : null, + "trace" : [ { + "action" : { + "callType" : "call", + "from" : "0x407d73d8a49eeb85d32cf465507dd71d507100c1", + "gas" : "0x1dcd12f8", + "input" : "0x", + "to" : "0xa94f5374fce5edbc8e2a8697c15331677e6ebf0b", + "value" : "0x186a0" + }, + "result" : { + "gasUsed" : "0x0", + "output" : "0x" + }, + "subtraces" : 0, + "traceAddress" : [ ], + "type" : "call" + } ], + "vmTrace" : null + }, + { + "output" : "0x", + "stateDiff" : null, + "trace" : [ { + "action" : { + "callType" : "call", + "from" : "0x407d73d8a49eeb85d32cf465507dd71d507100c1", + "gas" : "0x1dcd12f8", + "input" : "0x", + "to" : "0xa94f5374fce5edbc8e2a8697c15331677e6ebf0b", + "value" : "0x186a0" + }, + "result" : { + "gasUsed" : "0x0", + "output" : "0x" + }, + "subtraces" : 0, + "traceAddress" : [ ], + "type" : "call" + } ], + "vmTrace" : null + }, + ], +"id" : 1 +}, +``` + + + +### `trace_filter` + +Returns traces matching the specified filter. + +:::info + +Your node must be an archive node (that is, synchronized without pruning or fast sync) or the requested block must be within the number of [blocks retained](../cli/options.md#pruning-blocks-retained) with [pruning enabled](../cli/options.md#pruning-enabled) (by default, 1024). + +::: + +#### Parameters + +`traceFilterOptions`: _object_ - [trace filter options object](objects.md#trace-filter-options-object) + +#### Returns + +`result`: _array_ of _objects_ - list of [calls to other contracts](../trace-types.md#trace) containing one object per call, in transaction execution order + + + +# curl HTTP request + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"trace_filter","params":[{"fromBlock":"0x1","toBlock":"0x21","after":2,"count":2,"fromAddress":["0xfe3b557e8fb62b89f4916b721be55ceb828dbd73"]}],"id":415}' http://127.0.0.1:8545 +``` + +# wscat WS request + +```json +{ + "jsonrpc": "2.0", + "method": "trace_filter", + "params": [ + { + "fromBlock": "0x1", + "toBlock": "0x21", + "after": 2, + "count": 2, + "fromAddress": ["0xfe3b557e8fb62b89f4916b721be55ceb828dbd73"] + } + ], + "id": 415 +} +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "result": [ + { + "action": { + "callType": "call", + "from": "0xfe3b557e8fb62b89f4916b721be55ceb828dbd73", + "gas": "0xffad82", + "input": "0x0000000000000000000000000000000000000999", + "to": "0x0020000000000000000000000000000000000000", + "value": "0x0" + }, + "blockHash": "0xcd5d9c7acdcbd3fb4b24a39e05a38e32235751bb0c9e4f1aa16dc598a2c2a9e4", + "blockNumber": 6, + "result": { + "gasUsed": "0x7536", + "output": "0x" + }, + "subtraces": 1, + "traceAddress": [], + "transactionHash": "0x91eeabc671e2dd2b1c8ddebb46ba59e8cb3e7d189f80bcc868a9787728c6e59e", + "transactionPosition": 0, + "type": "call" + }, + { + "action": { + "callType": "call", + "from": "0xfe3b557e8fb62b89f4916b721be55ceb828dbd73", + "gas": "0xffad52", + "input": "0xf000000000000000000000000000000000000000000000000000000000000001", + "to": "0x0030000000000000000000000000000000000000", + "value": "0x0" + }, + "blockHash": "0xeed85fe57db751442c826cfe4fdf43b10a5c2bc8b6fd3a8ccced48eb3fb35885", + "blockNumber": 7, + "result": { + "gasUsed": "0x1b", + "output": "0xf000000000000000000000000000000000000000000000000000000000000002" + }, + "subtraces": 0, + "traceAddress": [], + "transactionHash": "0x47f4d445ea1812cb1ddd3464ab23d2bfc6ed408a8a9db1c497f94e8e06e85286", + "transactionPosition": 0, + "type": "call" + } + ], + "id": 415 +} +``` + + + +### `trace_get` + +Returns trace at given position. + +:::info + +Your node must be an archive node (that is, synchronized without pruning or fast sync) or the requested transaction must be contained in a block within the number of [blocks retained](../cli/options.md#pruning-blocks-retained) with [pruning enabled](../cli/options.md#pruning-enabled) (by default, 1024). + +::: + +#### Parameters + +- `transaction`: _string_ - transaction hash + +- `indexPositions`: _array_ - Index positions of the traces + +#### Returns + +`result`: _array_ of _objects_ - list of [calls to other contracts](../trace-types.md#trace) containing one object per call, in the order called by the transaction + + + +# curl HTTP request + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"trace_get","params":["0x17104ac9d3312d8c136b7f44d4b8b47852618065ebfa534bd2d3b5ef218ca1f3",["0x0"]],"id":1}' http://127.0.0.1:8545 +``` + +# wscat WS request + +```json +{ + "jsonrpc": "2.0", + "method": "trace_get", + "params": [ + "0x17104ac9d3312d8c136b7f44d4b8b47852618065ebfa534bd2d3b5ef218ca1f3", + ["0x0"] + ], + "id": 1 +} +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "result": { + "action" : { + "callType" : "call", + "from" : "0x1c39ba39e4735cb65978d4db400ddd70a72dc750", + "gas" : "0x13e99", + "input" : "0x16c72721", + "to" : "0x2bd2326c993dfaef84f696526064ff22eba5b362", + "value" : "0x0" + }, + "blockHash" : "0x7eb25504e4c202cf3d62fd585d3e238f592c780cca82dacb2ed3cb5b38883add" + "blockNumber": 3068185, + "result": { + "gasUsed": "0x183", + "output" : "0x0000000000000000000000000000000000000000000000000000000000000001" + }, + "subtraces" : 0, + "traceAddress" : [ + 0 + ], + "transactionHash": "0x17104ac9d3312d8c136b7f44d4b8b47852618065ebfa534bd2d3b5ef218ca1f3", + "transactionPosition": 2, + "type" : "call" + }, +"id" : 1 +}, +``` + + + +### `trace_rawTransaction` + +Traces a call to `eth_sendRawTransaction` without making the call, returning the traces. + +:::info + +The requested transaction must be contained in a block within the number of [blocks retained](../cli/options.md#pruning-blocks-retained) with [pruning enabled](../cli/options.md#pruning-enabled) (by default, 1024). + +::: + +#### Parameters + +- `data` - _string_ - Raw transaction data + +- `options`: _array_ of _strings_ - list of tracing options; tracing options are [`trace`, `vmTrace`, and `stateDiff`](../trace-types.md). Specify any combination of the three options including none of them. + +#### Returns + +`result`: _array_ of _objects_ - list of [calls to other contracts](../trace-types.md#trace) containing one object per call, in the order called by the transaction + + + +# curl HTTP request + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"trace_rawTransaction","params":["0xd46e8dd67c5d32be8d46e8dd67c5d32be8058bb8eb970870f072445675058bb8eb970870f072445675",["trace"]],"id":1}' http://127.0.0.1:8545 +``` + +# wscat WS request + +```json +{ + "jsonrpc": "2.0", + "method": "trace_rawTransaction", + "params": [ + "0xd46e8dd67c5d32be8d46e8dd67c5d32be8058bb8eb970870f072445675058bb8eb970870f072445675", + ["trace"] + ], + "id": 1 +} +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "result": { + "output" : "0x" + "stateDiff": null, + "from" : "0x1c39ba39e4735cb65978d4db400ddd70a72dc750", + "trace": [{ + "action": { ... }, + "result": { + "gasUsed": "0x0", + "output": "0x" + } + "subtraces": 0, + "traceAddress": [], + "type": "call" + }], + "vmTrace": null + }, +"id" : 1 +}, +``` + + + +### `trace_replayBlockTransactions` + +Provides transaction processing tracing per block. + +:::info + +When using [Bonsai](../../concepts/data-storage-formats.md#bonsai-tries), the requested block must be within the number of [blocks retained](../cli/options.md#bonsai-historical-block-limit) (by default, 512 from the head of the chain). + +When using [Forest](../../concepts/data-storage-formats.md#forest-of-tries), the requested block must be within the number of [blocks retained](../cli/options.md#pruning-blocks-retained) with [pruning enabled](../cli/options.md#pruning-enabled) (by default, 1024 from head of the chain). + +::: + +#### Parameters + +- `blockNumber`: _string_ - hexadecimal or decimal integer representing a block number or one of the string tags `latest`, `earliest`, `pending`, `finalized`, or `safe`, as described in [block parameter](../../how-to/use-besu-api/json-rpc.md#block-parameter) + +- `options`: _array_ of _strings_ - list of tracing options; tracing options are [`trace`, `vmTrace`, and `stateDiff`](../trace-types.md). Specify any combination of the three options including none of them. + +#### Returns + +`result`: _array_ of _objects_ - list of [transaction trace objects](objects.md#transaction-trace-object) containing one object per transaction, in transaction execution order; if revert reason is enabled with [`--revert-reason-enabled`](../cli/options.md#revert-reason-enabled), the [`trace`](../trace-types.md#trace) list items in the returned transaction trace object include the [revert reason](../../../private-networks/how-to/send-transactions/revert-reason.md). + + + +# curl HTTP request + +```bash +curl -X POST --data '{"jsonrpc": "2.0", "method": "trace_replayBlockTransactions","params": ["0x12",["trace","vmTrace","stateDiff"]],"id": 1}' http://127.0.0.1:8545 +``` + +# wscat WS request + +```json +{ + "jsonrpc": "2.0", + "method": "trace_replayBlockTransactions", + "params": ["0x12", ["trace", "vmTrace", "stateDiff"]], + "id": 1 +} +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result":[ + { + "output":"0x", + "vmTrace":{ + "code":"0x7f3940be4289e4c3587d88c1856cc95352461992db0a584c281226faefe560b3016000527f14c4d2c102bdeb2354bfc3dc96a95e4512cf3a8461e0560e2272dbf884ef3905601052600851", + "ops":[ + { + "cost":3, + "ex":{ + "mem":null, + "push":[ + "0x8" + ], + "store":null, + "used":16756175 + }, + "pc":72, + "sub":null + }, + ... + ] + }, + "trace":[ + { + "action":{ + "callType":"call", + "from":"0xfe3b557e8fb62b89f4916b721be55ceb828dbd73", + "gas":"0xffadea", + "input":"0x", + "to":"0x0100000000000000000000000000000000000000", + "value":"0x0" + }, + "result":{ + "gasUsed":"0x1e", + "output":"0x" + }, + "subtraces":0, + "traceAddress":[ + ], + "type":"call" + } + ], + "stateDiff":{ + "0xfe3b557e8fb62b89f4916b721be55ceb828dbd73":{ + "balance":{ + "*":{ + "from":"0xffffffffffffffffffffffffffffffffc3e12a20b", + "to":"0xffffffffffffffffffffffffffffffffc3dc5f091" + } + }, + "code":"=", + "nonce":{ + "*":{ + "from":"0x14", + "to":"0x15" + } + }, + "storage":{ + } + } + }, + "transactionHash":"0x2a5079cc535c429f668f13a7fb9a28bdba6831b5462bd04f781777b332a8fcbd", + }, + {...} + ] +} +``` + + + +### `trace_transaction` + +Provides transaction processing of [type `trace`](../trace-types.md#trace) for the specified transaction. + +:::info + +Your node must be an archive node (that is, synchronized without pruning or fast sync) or the requested transaction must be contained in a block within the number of [blocks retained](../cli/options.md#pruning-blocks-retained) with [pruning enabled](../cli/options.md#pruning-enabled) (by default, 1024). + +::: + +#### Parameters + +`transaction`: _string_ - transaction hash + +#### Returns + +`result`: _array_ of _objects_ - list of [calls to other contracts](../trace-types.md#trace) containing one object per call, in the order called by the transaction; if revert reason is enabled with [`--revert-reason-enabled`](../cli/options.md#revert-reason-enabled), the returned list items include the [revert reason](../../../private-networks/how-to/send-transactions/revert-reason.md). + + + +# curl HTTP request + +```bash +curl -X POST --data '{"jsonrpc": "2.0", "method": "trace_transaction","params": ["0x4c253746668dca6ac3f7b9bc18248b558a95b5fc881d140872c2dff984d344a7"],"id": 1}' http://127.0.0.1:8545 +``` + +# wscat WS request + +```json +{ + "jsonrpc": "2.0", + "method": "trace_transaction", + "params": [ + "0x4c253746668dca6ac3f7b9bc18248b558a95b5fc881d140872c2dff984d344a7" + ], + "id": 1 +} +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "result": [ + { + "action": { + "creationMethod": "create", + "from": "0x627306090abab3a6e1400e9345bc60c78a8bef57", + "gas": "0xff2e26", + "init": "0x60006000600060006000732c2b9c9a4a25e24b174f26114e8926a9f2128fe45af2600060006000600060007300a00000000000000000000000000000000000005af2", + "value": "0x0" + }, + "blockHash": "0x7e9a993adc6f043c0a9b6a385e6ed3fa370586c55823251b8fa7033cf89d414e", + "blockNumber": 19, + "result": { + "address": "0x30753e4a8aad7f8597332e813735def5dd395028", + "code": "0x", + "gasUsed": "0x1c39" + }, + "subtraces": 2, + "traceAddress": [], + "transactionHash": "0x4c253746668dca6ac3f7b9bc18248b558a95b5fc881d140872c2dff984d344a7", + "transactionPosition": 3, + "type": "create" + }, + { + "action": { + "callType": "callcode", + "from": "0x30753e4a8aad7f8597332e813735def5dd395028", + "gas": "0xfb2ea9", + "input": "0x", + "to": "0x2c2b9c9a4a25e24b174f26114e8926a9f2128fe4", + "value": "0x0" + }, + "blockHash": "0x7e9a993adc6f043c0a9b6a385e6ed3fa370586c55823251b8fa7033cf89d414e", + "blockNumber": 19, + "result": { + "gasUsed": "0x138e", + "output": "0x" + }, + "subtraces": 1, + "traceAddress": [0], + "transactionHash": "0x4c253746668dca6ac3f7b9bc18248b558a95b5fc881d140872c2dff984d344a7", + "transactionPosition": 3, + "type": "call" + }, + { + "action": { + "address": "0x30753e4a8aad7f8597332e813735def5dd395028", + "balance": "0x0", + "refundAddress": "0x0000000000000000000000000000000000000000" + }, + "blockHash": "0x7e9a993adc6f043c0a9b6a385e6ed3fa370586c55823251b8fa7033cf89d414e", + "blockNumber": 19, + "result": null, + "subtraces": 0, + "traceAddress": [0, 0], + "transactionHash": "0x4c253746668dca6ac3f7b9bc18248b558a95b5fc881d140872c2dff984d344a7", + "transactionPosition": 3, + "type": "suicide" + }, + { + "action": { + "callType": "callcode", + "from": "0x30753e4a8aad7f8597332e813735def5dd395028", + "gas": "0xfb18a5", + "input": "0x", + "to": "0x00a0000000000000000000000000000000000000", + "value": "0x0" + }, + "blockHash": "0x7e9a993adc6f043c0a9b6a385e6ed3fa370586c55823251b8fa7033cf89d414e", + "blockNumber": 19, + "result": { + "gasUsed": "0x30b", + "output": "0x" + }, + "subtraces": 0, + "traceAddress": [1], + "transactionHash": "0x4c253746668dca6ac3f7b9bc18248b558a95b5fc881d140872c2dff984d344a7", + "transactionPosition": 3, + "type": "call" + } + ], + "id": 1 +} +``` + + + +## `TXPOOL` methods + +The `TXPOOL` API methods allow you to inspect the contents of the transaction pool. + +:::note + +The `TXPOOL` API methods are not enabled by default for JSON-RPC. To enable the `TXPOOL` API methods, use the [`--rpc-http-api`](../cli/options.md#rpc-http-api) or [`--rpc-ws-api`](../cli/options.md#rpc-ws-api) options. + +::: + +### `txpool_besuPendingTransactions` + +Lists pending transactions that match the supplied filter conditions. + +#### Parameters + +- `numResults`: _number_ - integer representing the maximum number of results to return + +- `fields`: _object_ - object of fields used to create the filter condition + +Each field in the object corresponds to a field name containing an operator, and a value for the operator. A field name can only be specified once, and can only contain one operator. For example, you cannot query transactions with a gas price between 8 and 9 Gwei by using both the `gt` and `lt` operator in the same field name instance. + +All filters must be satisfied for a transaction to be returned. + +| Field name | Value | Value type | Supported operators | +| --- | --- | :-: | --- | +| `from` | Address of the sender. | _Data_, 20 bytes | `eq` | +| `to` | Address of the receiver, or `"contract_creation"`. | _Data_, 20 bytes | `eq`, `action` | +| `gas` | Gas provided by the sender. | _Quantity_ | `eq`, `gt`, `lt` | +| `gasPrice` | Gas price, in wei, provided by the sender. | _Quantity_ | `eq`, `gt`, `lt` | +| `value` | Value transferred, in wei. | _Quantity_ | `eq`, `gt`, `lt` | +| `nonce` | Number of transactions made by the sender. | _Quantity_ | `eq`, `gt`, `lt` | + +Supported operators: + +- `eq` (equal to) + +- `lt` (less than) + +- `gt` (greater than) + +- `action` + +:::note + +The only supported `action` is `"contract_creation"`. + +::: + +#### Returns + +`result`: _array_ of _objects_ - list of objects with [details of the pending transaction](objects.md#pending-transaction-object) + + + +# curl HTTP request + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"txpool_besuPendingTransactions","params":[2,{"from":{"eq":"0xfe3b557e8fb62b89f4916b721be55ceb828dbd73"},"gas":{"lt":"0x5209"},"nonce":{"gt":"0x1"}}],"id":1}' http://127.0.0.1:8545 +``` + +# wscat WS request + +```json +{ + "jsonrpc": "2.0", + "method": "txpool_besuPendingTransactions", + "params": [ + 2, + { + "from": { "eq": "0xfe3b557e8fb62b89f4916b721be55ceb828dbd73" }, + "gas": { "lt": "0x5209" }, + "nonce": { "gt": "0x1" } + } + ], + "id": 1 +} +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": [ + { + "from": "0xfe3b557e8fb62b89f4916b721be55ceb828dbd73", + "gas": "0x5208", + "gasPrice": "0xab5d04c00", + "hash": "0xb7b2f4306c1c228ec94043da73b582594007091a7dfe024b1f8d6d772284e54b", + "input": "0x", + "nonce": "0x2", + "to": "0xf8be4ebda7f62d79a665294ec1263bfdb59aabf2", + "value": "0x0", + "v": "0xfe8", + "r": "0x5beb711e652c6cf0a589d3cea904eefc4f45ce4372652288701d08cc4412086d", + "s": "0x3af14a56e63aa5fb7dcb444a89708363a9d2c1eba1f777c67690288415080ded" + } + ] +} +``` + + + +### `txpool_besuStatistics` + +Lists statistics about the node transaction pool. + +#### Parameters + +None + +#### Returns + +`result`: _object_ - transaction pool statistics object with the following fields: + +- `maxSize`: _number_ - maximum number of transactions kept in the transaction pool; use the [`--tx-pool-max-size`](../cli/options.md#tx-pool-max-size) option to configure the maximum size. + +- `localCount`: _number_ - number of transactions submitted directly to this node + +- `remoteCount`: _number_ - number of transactions received from remote nodes + + + +# curl HTTP request + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"txpool_besuStatistics","params":[],"id":1}' http://127.0.0.1:8545 +``` + +# wscat WS request + +```bash +{"jsonrpc":"2.0","method":"txpool_besuStatistics","params":[],"id":1} +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + "maxSize": 4096, + "localCount": 1, + "remoteCount": 0 + } +} +``` + + + +### `txpool_besuTransactions` + +Lists transactions in the node transaction pool. + +#### Parameters + +None + +#### Returns + +`result`: _array_ of _objects_ - list of transactions + + + +# curl HTTP request + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"txpool_besuTransactions","params":[],"id":1}' http://127.0.0.1:8545 +``` + +# wscat WS request + +```json +{ "jsonrpc": "2.0", "method": "txpool_besuTransactions", "params": [], "id": 1 } +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": [ + { + "hash": "0x8a66830098be4006a3f63a03b6e9b67aa721e04bd6b46d420b8f1937689fb4f1", + "isReceivedFromLocalSource": true, + "addedToPoolAt": "2019-03-21T01:35:50.911Z" + }, + { + "hash": "0x41ee803c3987ceb5bcea0fad7a76a8106a2a6dd654409007d9931032ea54579b", + "isReceivedFromLocalSource": true, + "addedToPoolAt": "2019-03-21T01:36:00.374Z" + } + ] +} +``` + + + +## `WEB3` methods + +The `WEB3` API methods provide functionality for the Ethereum ecosystem. + +### `web3_clientVersion` + +Returns the current client version. + +#### Parameters + +None + +#### Returns + +`result`: _string_ - current client version + + + +# curl HTTP request + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"web3_clientVersion","params":[],"id":1}' http://127.0.0.1:8545 +``` + +# wscat WS request + +```json +{ "jsonrpc": "2.0", "method": "web3_clientVersion", "params": [], "id": 1 } +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 53, + "result": "besu/" +} +``` + + + +### `web3_sha3` + +Returns a [SHA3](https://en.wikipedia.org/wiki/SHA-3) hash of the specified data. The result value is a [Keccak-256](https://keccak.team/keccak.html) hash, not the standardized SHA3-256. + +#### Parameters + +`data`: _string_ - data to convert to a SHA3 hash + +#### Returns + +`result`: _string_ - SHA3 result of the input data + + + +# curl HTTP request + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"web3_sha3","params":["0x68656c6c6f20776f726c00"],"id":53}' http://127.0.0.1:8545 +``` + +# wscat WS request + +```json +{ + "jsonrpc": "2.0", + "method": "web3_sha3", + "params": ["0x68656c6c6f20776f726c00"], + "id": 53 +} +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 53, + "result": "0x5e39a0a66544c0668bde22d61c47a8710000ece931f13b84d3b2feb44ec96d3f" +} +``` + + + +## Miscellaneous methods + +### `rpc_modules` + +Lists [enabled APIs](../../how-to/use-besu-api/json-rpc.md#api-methods-enabled-by-default) and the version of each. + +#### Parameters + +None + +#### Returns + +`result`: _map_ of _strings_ to _strings_ - enabled APIs and their versions + + + +# curl HTTP request + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"rpc_modules","params":[],"id":1}' http://127.0.0.1:8545 +``` + +# wscat WS request + +```bash +{"jsonrpc":"2.0","method":"rpc_modules","params":[],"id":1} +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + "web3": "1.0", + "eth": "1.0", + "net": "1.0" + } +} +``` + + + + + +[schema]: https://github.com/hyperledger/besu/blob/750580dcca349d22d024cc14a8171b2fa74b505a/ethereum/api/src/main/resources/schema.graphqls +[eth_sendRawTransaction or eth_call]: ../../how-to/send-transactions.md#eth_call-or-eth_sendrawtransaction +[transaction]: https://ropsten.etherscan.io/tx/0xfc766a71c406950d4a4955a340a092626c35083c64c7be907060368a5e6811d6 diff --git a/versioned_docs/version-23.10.1/public-networks/reference/api/objects.md b/versioned_docs/version-23.10.1/public-networks/reference/api/objects.md new file mode 100644 index 00000000000..1694463f148 --- /dev/null +++ b/versioned_docs/version-23.10.1/public-networks/reference/api/objects.md @@ -0,0 +1,265 @@ +--- +title: Objects +description: Hyperledger Besu API objects reference +tags: + - public networks + - private networks +--- + +# Besu API objects + +The following objects are parameters for or returned by Besu API methods. + +:::info + +This reference contains API objects that apply to both public and private networks. For private-network-specific API objects, see the [private network API object reference](../../../private-networks/reference/api/objects.md). + +::: + +## Block object + +Returned by [`eth_getBlockByHash`](index.md#eth_getblockbyhash) and [`eth_getBlockByNumber`](index.md#eth_getblockbynumber). + +| Key | Type | Value | +| --- | :-: | --- | +| `number` | _Quantity_, Integer | Block number. `null` when block is pending. | +| `hash` | _Data_, 32 bytes | Hash of the block. `null` when block is pending. | +| `parentHash` | _Data_, 32 bytes | Hash of the parent block. | +| `nonce` | _Data_, 8 bytes | Hash of the generated proof of work. `null` when block is pending. | +| `sha3Uncles` | _Data_, 32 bytes | SHA3 of the uncle's data in the block. | +| `logsBloom` | _Data_, 256 bytes | Bloom filter for the block logs. `null` when block is pending. | +| `transactionsRoot` | _Data_, 32 bytes | Root of the transaction trie for the block. | +| `stateRoot` | Data, 32 bytes | Root of the final state trie for the block. | +| `receiptsRoot` | Data, 32 bytes | Root of the receipts trie for the block. | +| `miner` | Data, 20 bytes | Address to pay mining rewards to. | +| `difficulty` | Quantity, Integer | Difficulty for this block. | +| `totalDifficulty` | Quantity, Integer | Total difficulty of the chain until this block. This value will always be `0` for an uncle block. | +| `extraData` | Data | Extra data field for this block. The first 32 bytes is vanity data you can set using the [`--miner-extra-data`](../cli/options.md#miner-extra-data) command line option. Stores extra data when used with [Clique](../../../private-networks/how-to/configure/consensus/clique.md#genesis-file) and [IBFT](../../../private-networks/how-to/configure/consensus/ibft.md#genesis-file). | +| `size` | Quantity, Integer | Size of block in bytes. | +| `gasLimit` | Quantity | Maximum gas allowed in this block. | +| `gasUsed` | Quantity | Total gas used by all transactions in this block. | +| `timestamp` | Quantity | Unix timestamp (milliseconds) for block assembly. | +| `transactions` | Array | Array of [transaction objects](#transaction-object), or 32 byte transaction hashes depending on the specified boolean parameter. | +| `uncles` | Array | Array of uncle hashes. | +| `baseFeePerGas` | Quantity | The block's [base fee per gas](../../concepts/transactions/types.md#eip1559-transactions). This field is empty for blocks created before [EIP-1559](https://github.com/ethereum/EIPs/blob/2d8a95e14e56de27c5465d93747b0006bd8ac47f/EIPS/eip-1559.md). | + +## Fee history results object + +Returned by [`eth_feeHistory`](index.md#eth_feehistory) for the requested block range. If blocks in the specified block range are not available, then only the fee history for available blocks is returned. + +| Key | Type | Value | +| --- | :-: | --- | +| `oldestBlock` | Quantity, Integer | Lowest number block of the returned range. | +| `baseFeePerGas` | Array | Array of block base fees per gas, including an extra block value. The extra value is the next block after the newest block in the returned range. Returns zeroes for blocks created before [EIP-1559](https://github.com/ethereum/EIPs/blob/2d8a95e14e56de27c5465d93747b0006bd8ac47f/EIPS/eip-1559.md). | +| `gasUsedRatio` | Array | Array of block gas used ratios. These are calculated as the ratio of `gasUsed` and `gasLimit`. | +| `reward` | Array | Array of effective priority fee per gas data points from a single block. All zeroes are returned if the block is empty. | + +## Filter options object + +Parameter for [`eth_newFilter`](index.md#eth_newfilter), [`eth_getLogs`](index.md#eth_getlogs), and [`priv_getLogs`](../../../private-networks/reference/api/index.md#priv_getlogs). Used to [`filter logs`](../../how-to/use-besu-api/access-logs.md). + +| Key | Type | Required/Optional | Value | +| --- | :-: | :-: | --- | +| `fromBlock` | Quantity | Tag | Optional | Integer block number or `latest`, `pending`, `earliest`. See [block parameter](../../how-to/use-besu-api/json-rpc.md#block-parameter). Default is `latest`. | +| `toBlock` | Quantity | Tag | Optional | Integer block number or `latest`, `pending`, `earliest`. See [block parameter](../../how-to/use-besu-api/json-rpc.md#block-parameter). Default is `latest`. | +| `address` | Data | Array | Optional | Contract address or array of addresses from which [logs](../../concepts/events-and-logs.md) originate. | +| `topics` | Array of Data, 32 bytes each | Optional | Array of topics by which to [filter logs](../../concepts/events-and-logs.md#topic-filters). | + +[`eth_getLogs`](index.md#eth_getlogs) and [`priv_getLogs`](index.md#priv_getlogs) have an extra key. + +| Key | Type | Required/Optional | Value | +| --- | :-: | :-: | --- | +| `blockHash` | Data, 32 bytes | Optional. | Hash of block for which to return logs. If you specify `blockHash`, you cannot specify `fromBlock` and `toBlock`. | + +## Log object + +Returned by [`eth_getFilterChanges`](index.md#eth_getfilterchanges) and [`priv_getLogs`](../../../private-networks/reference/api/index.md#priv_getlogs). [`Transaction receipt objects`](#transaction-receipt-object) can contain an array of log objects. + +| Key | Type | Value | +| --- | :-: | --- | +| `removed` | Tag | `true` if log removed because of a chain reorganization. `false` if a valid log. | +| `logIndex` | Quantity, Integer | Log index position in the block. `null` when log is pending. | +| `transactionIndex` | Quantity, Integer | Index position of the starting transaction for the log. `null` when log is pending. | +| `transactionHash` | Data, 32 bytes | Hash of the starting transaction for the log. `null` when log is pending. | +| `blockHash` | Data, 32 bytes | Hash of the block that includes the log. `null` when log is pending. | +| `blockNumber` | Quantity | Number of block that includes the log. `null` when log is pending. | +| `address` | Data, 20 bytes | Address the log originated from. | +| `data` | Data | Non-indexed arguments of the log. | +| `topics` | Array of Data, 32 bytes each | [Event signature hash](../../concepts/events-and-logs.md#event-signature-hash) and 0 to 3 [indexed log arguments](../../concepts/events-and-logs.md#event-parameters). | + +## Miner data object + +Returned by [`eth_getMinerDataByBlockHash`](index.md#eth_getminerdatabyblockhash) and [`eth_getMinerDataByBlockNumber`](index.md#eth_getminerdatabyblocknumber). + +| Key | Type | Value | +| --- | :-: | --- | +| `netBlockReward` | Quantity, Integer | The net block reward, in Wei, is `staticBlockReward + transactionFee + uncleInclusionReward`. | +| `staticBlockReward` | Quantity, Integer | The static block reward, in Wei, is preset on a hard fork. | +| `transactionFee` | Quantity, Integer | The transaction fee, in Wei, is `sum of upfront cost - refund amount for all transactions`. | +| `uncleInclusionReward` | Quantity, Integer | The uncle inclusion reward, in Wei, is `static block reward * number of ommers/32`. | +| `uncleRewards` | Map | Map of uncle block hashes and uncle miner coinbase addresses. | +| `coinbase` | Data, 20 bytes | Coinbase address. | +| `extraData` | Data | Extra data field for this block. The first 32 bytes is vanity data you can set using the [`--miner-extra-data`](../cli/options.md#miner-extra-data) command line option. | +| `difficulty` | Quantity, Integer | Difficulty of this block. | +| `totalDifficulty` | Quantity, Integer | Total difficulty of the chain until this block. | + +## Pending transaction object + +Returned by [`txpool_besuPendingTransactions`](index.md#txpool_besupendingtransactions). + +| Key | Type | Value | +| --- | :-: | --- | +| `accessList` | Array | (Optional) List of addresses and storage keys the transaction plans to access. Used in [`ACCESS_LIST` transactions](../../concepts/transactions/types.md#access_list-transactions) and may be used in [`EIP1559` transactions](../../concepts/transactions/types.md#eip1559-transactions). | +| `from` | Data, 20 bytes | Address of the sender. | +| `gas` | Quantity | Gas provided by the sender. | +| `gasPrice` | Quantity | (Optional) Gas price, in Wei, provided by the sender. Not used only in [`EIP1559` transactions](../../concepts/transactions/types.md#eip1559-transactions). | +| `maxPriorityFeePerGas` | Quantity, Integer | (Optional) Maximum fee, in Wei, the sender is willing to pay per gas above the base fee. Used only in [`EIP1559` transactions](../../concepts/transactions/types.md#eip1559-transactions). | +| `maxFeePerGas` | Quantity, Integer | (Optional) Maximum total fee (base fee + priority fee), in Wei, the sender is willing to pay per gas. Used only in [`EIP1559` transactions](../../concepts/transactions/types.md#eip1559-transactions). | +| `hash` | Data, 32 bytes | Hash of the transaction. | +| `input` | Data | Data sent with the transaction to create or invoke a contract. | +| `nonce` | Quantity | Number of transactions made by the sender before this one. | +| `to` | Data, 20 bytes | Address of the receiver. `null` if a contract creation transaction. | +| `transactionType` | String | [Transaction type](../../concepts/transactions/types.md). | +| `value` | Quantity | Value transferred, in Wei. | +| `v` | Quantity | ECDSA Recovery ID. | +| `r` | Data, 32 bytes | ECDSA signature r. | +| `s` | Data, 32 bytes | ECDSA signature s. | + +## Range object + +Returned by [`debug_storageRangeAt`](index.md#debug_storagerangeat). + +| Key | Type | Value | +| --- | :-: | --- | +| `storage` | Object | Key hash and value. Pre-image key is `null` if it falls outside the cache. | +| `nextKey` | Hash | Hash of next key if further storage in range. Otherwise, not included. | + +### Structured log object + +Log information returned as part of the [Trace object](#trace-object). + +| Key | Type | Value | +| --- | :-: | --- | +| `pc` | Integer | Current program counter. | +| `op` | String | Current OpCode. | +| `gas` | Integer | Gas remaining. | +| `gasCost` | Integer | Cost in wei of each gas unit. | +| `depth` | Integer | Execution depth. | +| `exceptionalHaltReasons` | Array | One or more strings representing an error condition causing the EVM execution to terminate. These strings suggest that EVM execution terminated for reasons such as running out of gas or attempting to execute an unknown instruction. Generally a single exceptional halt reason returns but it's possible for more than one to occur at once. | +| `stack` | Array of 32 byte arrays | EVM execution stack before executing current operation. | +| `memory` | Array of 32 byte arrays | Memory space of the contract before executing current operation. | +| `storage` | Object | Storage entries changed by the current transaction. | + +## Trace object + +Returned by [`debug_traceBlock`](index.md#debug_traceblock), [`debug_traceBlockByHash`](index.md#debug_traceblockbyhash), [`debug_traceBlockByNumber`](index.md#debug_traceblockbynumber), and [`debug_traceTransaction`](index.md#debug_tracetransaction). + +| Key | Type | Value | +| --- | :-: | --- | +| `gas` | Integer | Gas used by the transaction. | +| `failed` | Boolean | True if transaction failed, otherwise, false. | +| `returnValue` | String | Bytes returned from transaction execution (without a `0x` prefix). | +| `structLogs` | Array | Array of structured log objects. | + +## Trace filter options object + +Parameter for [`trace_filter`](index.md#trace_filter). All parameters are optional. + +| Key | Type | Value | +| --- | :-: | --- | +| `fromBLock` | String | Tag | Trace starts at this block. | +| `toBlock` | String | Tag | Trace stops at this block. | +| `fromAddress` | String | Include only traces sent from this address. | +| `toAddress` | String | Include only traces with this destination address. | +| `after` | Quantity | The offset trace number. | +| `count` | Integer | Number of traces to display in a batch. | + +## Transaction object + +Returned by [`eth_getTransactionByHash`](index.md#eth_gettransactionbyhash), [`eth_getTransactionByBlockHashAndIndex`](index.md#eth_gettransactionbyblockhashandindex), and [`eth_getTransactionByBlockNumberAndIndex`](index.md#eth_gettransactionbyblocknumberandindex). + +| Key | Type | Value | +| --- | :-: | --- | +| `accessList` | Array | (Optional) List of addresses and storage keys the transaction plans to access. Used in [`ACCESS_LIST` transactions](../../concepts/transactions/types.md#access_list-transactions) and may be used in [`EIP1559` transactions](../../concepts/transactions/types.md#eip1559-transactions). | +| `blockHash` | Data, 32 bytes | Hash of the block containing this transaction. `null` when transaction is pending. | +| `blockNumber` | Quantity | Block number of the block containing this transaction. `null` when transaction is pending. | +| `chainId` | Quantity | [Chain ID](../../concepts/network-and-chain-id.md). | +| `from` | Data, 20 bytes | Address of the sender. | +| `gas` | Quantity | Gas provided by the sender. | +| `gasPrice` | Quantity | (Optional) Gas price, in Wei, provided by the sender. Used only in non-[`EIP1559`](../../concepts/transactions/types.md#eip1559-transactions) transactions. | +| `maxPriorityFeePerGas` | Quantity, Integer | (Optional) Maximum fee, in Wei, the sender is willing to pay per gas above the base fee. Used only in [`EIP1559` transactions](../../concepts/transactions/types.md#eip1559-transactions). | +| `maxFeePerGas` | Quantity, Integer | (Optional) Maximum total fee (base fee + priority fee), in Wei, the sender is willing to pay per gas. Used only in [`EIP1559` transactions](../../concepts/transactions/types.md#eip1559-transactions). | +| `hash` | Data, 32 bytes | Hash of the transaction. | +| `input` | Data | Data sent with the transaction to create or invoke a contract. For [private transactions](../../../private-networks/concepts/privacy/index.md), it's a pointer to the transaction location in [Tessera](https://docs.tessera.consensys.net/). | +| `nonce` | Quantity | Number of transactions made by the sender before this one. | +| `to` | Data, 20 bytes | Address of the receiver. `null` if a contract creation transaction. | +| `transactionIndex` | Quantity, Integer | Index position of the transaction in the block. `null` when transaction is pending. | +| `transactionType` | String | [Transaction type](../../concepts/transactions/types.md). | +| `value` | Quantity | Value transferred, in Wei. | +| `v` | Quantity | ECDSA Recovery ID. | +| `r` | Data, 32 bytes | ECDSA signature r. | +| `s` | Data, 32 bytes | ECDSA signature s. | + +## Transaction call object + +Parameter for [`eth_call`](index.md#eth_call), [`eth_createAccessList`](index.md#eth_createAccessList), and [`eth_estimateGas`](index.md#eth_estimategas). + +All transaction call object parameters are optional. + +| Key | Type | Value | +| --- | :-: | --- | +| `from` | Data, 20 bytes | Address of the sender. | +| `to` | Data, 20 bytes | Address of the action receiver. | +| `gas` | Quantity, Integer | Gas provided by the sender. `eth_call` consumes zero gas, but other executions might need this parameter. `eth_estimateGas` ignores this value. | +| `gasPrice` | Quantity, Integer | Gas price, in Wei, provided by the sender. The default is `0`. Used only in non-[`EIP1559`](../../concepts/transactions/types.md#eip1559-transactions) transactions. | +| `maxPriorityFeePerGas` | Quantity, Integer | Maximum fee, in Wei, the sender is willing to pay per gas above the base fee. Can be used only in [`EIP1559` transactions](../../concepts/transactions/types.md#eip1559-transactions). If used, must specify `maxFeePerGas`. | +| `maxFeePerGas` | Quantity, Integer | Maximum total fee (base fee + priority fee), in Wei, the sender is willing to pay per gas. Can be used only in [`EIP1559` transactions](../../concepts/transactions/types.md#eip1559-transactions). If used, must specify `maxPriorityFeePerGas`. | +| `value` | Quantity, Integer | Value transferred, in Wei. | +| `data` | Data | Hash of the method signature and encoded parameters. For details, see [Ethereum Contract ABI](https://solidity.readthedocs.io/en/develop/abi-spec.html). | +| `accessList` | Array | List of addresses and storage keys that the transaction plans to access. Used only in non-[`FRONTIER`](../../concepts/transactions/types.md#frontier-transactions) transactions. | +| `strict` | Tag | If `true`, checks that the `from` account’s ether balance is sufficient to cover the transaction and gas fee. If `false`, the `gasPrice` and `baseFee` are set to zero, in order to simulate a transaction without enforcing a balance check. The default is `false`. | + +## Transaction receipt object + +Returned by [`eth_getTransactionReceipt`](index.md#eth_gettransactionreceipt). + +| Key | Type | Value | +| --- | :-: | --- | +| `blockHash` | Data, 32 bytes | Hash of block containing this transaction. | +| `blockNumber` | Quantity | Block number of block containing this transaction. | +| `contractAddress` | Data, 20 bytes | Contract address created, if contract creation transaction, otherwise, `null`. A failed contract creation transaction still produces a contract address value. | +| `cumulativeGasUsed` | Quantity | Total amount of gas used by previous transactions in the block and this transaction. | +| `effectiveGasPrice` | Quantity | The [actual value per gas deducted](../../concepts/transactions/types.md#eip1559-transactions) from the sender's account. | +| `from` | Data, 20 bytes | Address of the sender. | +| `gasUsed` | Quantity | Amount of gas used by this specific transaction. | +| `logs` | Array | Array of [log objects](#log-object) generated by this transaction. | +| `logsBloom` | Data, 256 bytes | Bloom filter for light clients to quickly retrieve related logs. | +| `status` | Quantity | Either `0x0` (failure), `0x1` (success), or `0x2` (invalid). | +| `to` | Data, 20 bytes | Address of the receiver, if sending ether, otherwise, null. | +| `transactionHash` | Data, 32 bytes | Hash of the transaction. | +| `transactionIndex` | Quantity, Integer | Index position of transaction in the block. | +| `transactionType` | String | [Transaction type](../../concepts/transactions/types.md). | +| `revertReason` | String | ABI-encoded string that displays the [reason for reverting the transaction](../../../private-networks/how-to/send-transactions/revert-reason.md). Only available if revert reason is [enabled](../cli/options.md#revert-reason-enabled). | +| `type` | Quantity | Transaction type, `0x00` for legacy transactions, `0x01` for access list types, `0x02` for dynamic fees. | + +:::note + +For pre-Byzantium transactions, the transaction receipt object includes the following instead of `status`: + +| Key | Type | Value | +| ------ | :-----------------: | --------------------------- | +| `root` | Data, 32 bytes | Post-transaction state root | + +::: + +## Transaction trace object + +Returned by [`trace_replayBlockTransactions`](index.md#trace_replayblocktransactions). + +| Key | Type | Value | +| --- | :-: | --- | +| `output` | Boolean | Transaction result. 1 for success and 0 for failure. | +| `stateDiff` | Object | [State changes in the requested block](../trace-types.md#statediff). | +| `trace` | Array | [Ordered list of calls to other contracts](../trace-types.md#trace). | +| `vmTrace` | Object | [Ordered list of EVM actions](../trace-types.md#vmtrace). | +| `transactionHash` | Data, 32 bytes | Hash of the replayed transaction. | diff --git a/versioned_docs/version-23.10.1/public-networks/reference/cli/_category_.json b/versioned_docs/version-23.10.1/public-networks/reference/cli/_category_.json new file mode 100644 index 00000000000..e94b0c9a474 --- /dev/null +++ b/versioned_docs/version-23.10.1/public-networks/reference/cli/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Besu command line", + "position": 1 +} diff --git a/versioned_docs/version-23.10.1/public-networks/reference/cli/options.md b/versioned_docs/version-23.10.1/public-networks/reference/cli/options.md new file mode 100644 index 00000000000..28b1023dd3e --- /dev/null +++ b/versioned_docs/version-23.10.1/public-networks/reference/cli/options.md @@ -0,0 +1,4050 @@ +--- +title: Options +description: Hyperledger Besu command line interface reference +sidebar_position: 1 +tags: + - public networks + - private networks +--- + +# Command line options + +This reference describes the syntax of the Hyperledger Besu command line interface (CLI) options. + +:::info + +This reference contains options that apply to both public and private networks. For private-network-specific options, see the [private network options reference](../../../private-networks/reference/cli/options.md). + +::: + +## Specify options + +You can specify Besu options: + +- On the command line. + + ```bash + besu [OPTIONS] [SUBCOMMAND] + ``` + +- As an environment variable. For each command line option, the equivalent environment variable is: + + - Uppercase. + - `_` replaces `-`. + - Has a `BESU_` prefix. + + For example, set `--miner-coinbase` using the `BESU_MINER_COINBASE` environment variable. + +- In a [configuration file](../../how-to/configuration-file.md). + +If you specify an option in more than one place, the order of priority is command line, environment variable, configuration file. + +If using Bash or Z shell, you can view option suggestions by entering `--` and pressing the Tab key twice. + +```bash +besu --Tab+Tab +``` + +:::caution + +Characters such as smart quotes and long (em) hyphens don't work in Besu command line options. Ensure quotes aren't automatically converted to smart quotes, or double hyphens combined into em hyphens. + +::: + +## Options + +### `api-gas-price-blocks` + + + +# Syntax + +```bash +--api-gas-price-blocks= +``` + +# Example + +```bash +--api-gas-price-blocks=50 +``` + +# Environment variable + +```bash +BESU_API_GAS_PRICE_BLOCKS=50 +``` + +# Example configuration file + +```bash +api-gas-price-blocks=50 +``` + + + +Number of blocks back from the head block to examine for [`eth_gasPrice`](../api/index.md#eth_gasprice). The default is `100`. + +### `api-gas-price-max` + + + +# Syntax + +```bash +--api-gas-price-max= +``` + +# Example + +```bash +--api-gas-price-max=20000 +``` + +# Environment variable + +```bash +BESU_API_GAS_PRICE_MAX=20000 +``` + +# Example configuration file + +```bash +api-gas-price-max=20000 +``` + + + +Maximum gas price to return for [`eth_gasPrice`](../api/index.md#eth_gasprice), regardless of the percentile value measured. The default is `500000000000` (500 GWei). + +### `api-gas-price-percentile` + + + +# Syntax + +```bash +--api-gas-price-percentile= +``` + +# Example + +```bash +--api-gas-price-percentile=75 +``` + +# Environment variable + +```bash +BESU_API_GAS_PRICE_PERCENTILE=75 +``` + +# Example configuration file + +```bash +api-gas-price-percentile=75 +``` + + + +Percentile value to measure for [`eth_gasPrice`](../api/index.md#eth_gasprice). The default is `50.0`. + +For [`eth_gasPrice`](../api/index.md#eth_gasprice), to return the: + +- Highest gas price in [`--api-gas-price-blocks`](#api-gas-price-blocks), set to `100`. +- Lowest gas price in [`--api-gas-price-blocks`](#api-gas-price-blocks), set to `0`. + +### `auto-log-bloom-caching-enabled` + + + +# Syntax + +```bash +--auto-log-bloom-caching-enabled[=] +``` + +# Example + +```bash +--auto-log-bloom-caching-enabled=false +``` + +# Environment variable + +```bash +BESU_AUTO_LOG_BLOOM_CACHING_ENABLED=false +``` + +# Example configuration file + +```bash +auto-log-bloom-caching-enabled=false +``` + + + +Enables or disables automatic log bloom caching. APIs such as [`eth_getLogs`](../api/index.md#eth_getlogs) and [`eth_getFilterLogs`](../api/index.md#eth_getfilterlogs) use the cache for improved performance. The default is `true`. + +If automatic log bloom caching is enabled and a log bloom query reaches the end of the cache, Besu performs an uncached query for logs not yet written to the cache. + +Automatic log bloom caching has a small impact on performance. If you are not querying logs blooms for a large number of blocks, you might want to disable automatic log bloom caching. + +### `banned-node-ids` + + + +# Syntax + +```bash +--banned-node-ids=[,...]... +``` + +# Example + +```bash +--banned-node-ids=0xc35c3...d615f,0xf42c13...fc456 +``` + +# Environment variable + +```bash +BESU_BANNED_NODE_IDS=0xc35c3...d615f,0xf42c13...fc456 +``` + +# Configuration file + +```bash +banned-node-ids=["0xc35c3...d615f","0xf42c13...fc456"] +``` + + + +A list of node IDs with which this node will not peer. The node ID is the public key of the node. You can specify the banned node IDs with or without the `0x` prefix. + +:::tip + +The singular `--banned-node-id` and plural `--banned-node-ids` are available and are two names for the same option. + +::: + +### `bonsai-historical-block-limit` + + + +# Syntax + +```bash +--bonsai-historical-block-limit=256 +``` + +# Example + +```bash +--bonsai-historical-block-limit=256 +``` + +# Environment variable + +```bash +BESU_BONSAI_MAXIMUM_BACK_LAYERS_TO_LOAD=256 +``` + +# Example configuration file + +```bash +bonsai-historical-block-limit=256 +``` + + + +When using [Bonsai Tries](../../concepts/data-storage-formats.md#bonsai-tries), the [maximum number of previous blocks](../../concepts/data-storage-formats.md#accessing-data) for which Bonsai can reconstruct a historical state. The default is 512. + +### `bootnodes` + + + +# Syntax + +```bash +--bootnodes[=[,...]...] +``` + +# Example + +```bash +--bootnodes=enode://c35c3...d615f@1.2.3.4:30303,enode://f42c13...fc456@1.2.3.5:30303 +``` + +# Environment variable + +```bash +BESU_BOOTNODES=enode://c35c3...d615f@1.2.3.4:30303,enode://f42c13...fc456@1.2.3.5:30303 +``` + +# Example configuration file + +```bash +bootnodes=["enode://c35c3...d615f@1.2.3.4:30303","enode://f42c13...fc456@1.2.3.5:30303"] +``` + + + +A list of comma-separated [enode URLs](../../concepts/node-keys.md#enode-url) for [P2P discovery bootstrap](../../../private-networks/how-to/configure/bootnodes.md). + +When connecting to Mainnet or public testnets, the default is a predefined list of enode URLs. + +In private networks defined using [`--genesis-file`](#genesis-file) or when using [`--network=dev`](#network), the default is an empty list of bootnodes. + +### `color-enabled` + + + +# Syntax + +```bash +--color-enabled[=] +``` + +# Example + +```bash +--color-enabled=false +``` + +# Environment variable + +```bash +BESU_COLOR_ENABLED=false +``` + +# Example configuration file + +```bash +color-enabled=false +``` + + + +Enables or disables color output to console. The default is `true`. + +### `compatibility-eth64-forkid-enabled` + + + +# Syntax + +```bash +--compatibility-eth64-forkid-enabled[=] +``` + +# Example + +```bash +--compatibility-eth64-forkid-enabled=true +``` + +# Environment variable + +```bash +BESU_COMPATIBILITY_ETH64_FORKID_ENABLED=true +``` + +# Example configuration file + +```bash +compatibility-eth64-forkid-enabled=true +``` + + + +Enables or disables the legacy Eth/64 fork ID. For any networks with nodes using Besu v1.4 or earlier and nodes using Besu v20.10.1 or later, either: + +- All nodes must be upgraded to v20.10.1 or later. +- All nodes using v20.10.1 or later must have `--compatibility-eth64-forkid-enabled` set to `true`. + +The default is `false`. + +:::caution + +If networks have Besu nodes using v1.4 or earlier and other Besu nodes using v20.10.1 or later, the nodes on different versions cannot communicate unless `--compatibility-eth64-forkid-enabled` is set to `true`. + +::: + +### `config-file` + + + +# Syntax + +```bash +--config-file= +``` + +# Example + +```bash +--config-file=/home/me/me_node/config.toml +``` + +# Environment variable + +```bash +BESU_CONFIG_FILE=/home/me/me_node/config.toml +``` + + + +The path to the [TOML configuration file](../../how-to/configuration-file.md). The default is `none`. + +### `data-path` + + + +# Syntax + +```bash +--data-path= +``` + +# Example + +```bash +--data-path=/home/me/me_node +``` + +# Environment variable + +```bash +BESU_DATA_PATH=/home/me/me_node +``` + +# Configuration file + +```bash +data-path="/home/me/me_node" +``` + + + +The path to the Besu data directory. The default is the directory you installed Besu in, or `/opt/besu/database` if using the [Besu Docker image](../../get-started/install/run-docker-image.md). + +### `data-storage-format` + + + +# Syntax + +```bash +--data-storage-format= +``` + +# Example + +```bash +--data-storage-format=BONSAI +``` + +# Environment variable + +```bash +BESU_DATA_STORAGE_FORMAT=BONSAI +``` + +# Configuration file + +```bash +data-storage-format="BONSAI" +``` + + + +The [data storage format](../../concepts/data-storage-formats.md) to use. Set to `BONSAI` for Bonsai Tries or `FOREST` for Forest of Tries. The default is `FOREST`. + +### `discovery-dns-url` + + + +# Syntax + +```bash +--discovery-dns-url= +``` + +# Environment variable + +```bash +BESU_DISCOVERY_DNS_URL=enrtree://AM5FCQLWIZX2QFPNJAP7VUERCCRNGRHWZG3YYHIUV7BVDQ5FDPRT2@nodes.example.org +``` + +# Example configuration file + +```bash +discovery-dns-url="enrtree://AM5FCQLWIZX2QFPNJAP7VUERCCRNGRHWZG3YYHIUV7BVDQ5FDPRT2@nodes.example.org" +``` + + + +The `enrtree` URL of the DNS node list for [node discovery via DNS](https://eips.ethereum.org/EIPS/eip-1459). The default is `null`. + +### `discovery-enabled` + + + +# Syntax + +```bash +--discovery-enabled[=] +``` + +# Example + +```bash +--discovery-enabled=false +``` + +# Environment variable + +```bash +BESU_DISCOVERY_ENABLED=false +``` + +# Example configuration file + +```bash +discovery-enabled=false +``` + + + +Enables or disables P2P discovery. The default is `true`. + +:::note + +You can override the default DNS server if it's unreliable or doesn't serve TCP DNS requests, using the [early access option](#xhelp) `--Xp2p-dns-discovery-server=`. + +::: + +### `engine-host-allowlist` + + + +# Syntax + +```bash +--engine-host-allowlist=[,...]... or "*" +``` + +# Example + +```bash +--engine-host-allowlist=localhost,127.0.0.1 +``` + +# Environment variable + +```bash +BESU_ENGINE_HOST_ALLOWLIST=localhost,127.0.0.1 +``` + +# Configuration file + +```bash +engine-host-allowlist=["localhost","127.0.0.1"] +``` + + + +A comma-separated list of hostnames to allow for Engine API access (applies to both HTTP and WebSocket). + +:::tip + +To allow all hostnames, use `"*"`. We don't recommend allowing all hostnames in production environments. + +::: + +### `engine-jwt-disabled` + + + +# Syntax + +```bash +--engine-jwt-disabled[=] +``` + +# Example + +```bash +--engine-jwt-disabled=true +``` + +# Environment variable + +```bash +BESU_ENGINE_JWT_DISABLED=true +``` + +# Configuration file + +```bash +engine-jwt-disabled=true +``` + + + +Disables or enables [authentication](../../how-to/use-engine-api.md#authentication) for Engine APIs. The default is `false` (authentication is enabled by default). + +### `engine-jwt-secret` + + + +# Syntax + +```bash +--engine-jwt-secret= +``` + +# Example + +```bash +--engine-jwt-secret=jwt.hex +``` + +# Environment variable + +```bash +BESU_ENGINE_JWT_SECRET="jwt.hex" +``` + +# Configuration file + +```bash +engine-jwt-secret="jwt.hex" +``` + + + +Shared secret used to authenticate [consensus clients](../../concepts/the-merge.md) when using the Engine JSON-RPC API (both HTTP and WebSocket). Contents of file must be at least 32 hex-encoded bytes and not begin with `0x`. May be a relative or absolute path. See an [example of how to generate this](../../get-started/connect/mainnet.md#1-generate-the-shared-secret). + +### `engine-rpc-enabled` + + + +# Syntax + +```bash +--engine-rpc-enabled[= +``` + +# Example + +```bash +--engine-rpc-enabled +``` + +# Environment variable + +```bash +BESU_ENGINE_RPC_ENABLED=true +``` + +# Configuration file + +```bash +engine-rpc-enabled=true +``` + + + +Enables or disables the [Engine API](../engine-api/index.md). The default is `true`. + +### `engine-rpc-port` + + + +# Syntax + +```bash +--engine-rpc-port= +``` + +# Example + +```bash +--engine-rpc-port=8551 +``` + +# Environment variable + +```bash +BESU_ENGINE_RPC_PORT=8551 +``` + +# Configuration file + +```bash +engine-rpc-port="8551" +``` + + + +The listening port for the Engine API calls (`ENGINE`, `ETH`) for JSON-RPC over HTTP and WebSocket. The default is `8551`. + +### `ethstats` + + + +# Syntax + +```bash +--ethstats=<[ws://|wss://]nodename:secret@host:[port]> +``` + +# Example + +```bash +--ethstats=Dev-Node-1:secret@127.0.0.1:3001 +``` + +# Environment variable + +```bash +BESU_ETHSTATS=Dev-Node-1:secret@127.0.0.1:3001 +``` + +# Configuration file + +```bash +ethstats="Dev-Node-1:secret@127.0.0.1:3001" +``` + + + +Reporting URL of an [Ethstats](../../../private-networks/how-to/deploy/ethstats.md) server. +If specified without a port, the default port is 443 for SSL connections and 80 for non-SSL connections. + +You can optionally specify `ws://` or `wss://` in the Ethstats URL. +If you specify this scheme, the connection doesn't need to switch from SSL to non-SSL on each retry logic. + +### `ethstats-cacert-file` + + + +# Syntax + +```bash +--ethstats-cacert-file= +``` + +# Example + +```bash +--ethstats-cacert-file=./root.cert +``` + +# Environment variable + +```bash +BESU_ETHSTATS_CACERT_FILE=./root.cert +``` + +# Configuration file + +```bash +ethstats-cacert-file="./root.cert" +``` + + + +Path to the root certificate authority (CA) certificate file of the Ethstats server specified by [`--ethstats`](#ethstats). This option is useful in non-production environments. + +### `ethstats-contact` + + + +# Syntax + +```bash +--ethstats-contact= +``` + +# Example + +```bash +--ethstats-contact=contact@mail.com +``` + +# Environment variable + +```bash +BESU_ETHSTATS_CONTACT=contact@mail.com +``` + +# Configuration file + +```bash +ethstats-contact="contact@mail.com" +``` + + + +Contact email address to send to the Ethstats server specified by [`--ethstats`](#ethstats). + +### `fast-sync-min-peers` + + + +# Syntax + +```bash +--fast-sync-min-peers= +``` + +# Example + +```bash +--fast-sync-min-peers=8 +``` + +# Environment variable + +```bash +BESU_FAST_SYNC_MIN_PEERS=8 +``` + +# Example configuration file + +```bash +fast-sync-min-peers=8 +``` + + + +The minimum number of peers required before starting [fast synchronization](../../get-started/connect/sync-node.md#fast-synchronization) in [proof of work](../../how-to/use-pow/mining.md) networks. The default is 5. + +:::info + +This option only applies to proof of work networks. + +::: + +### `genesis-file` + + + +# Syntax + +```bash +--genesis-file= +``` + +# Example + +```bash +--genesis-file=/home/me/me_node/customGenesisFile.json +``` + +# Environment variable + +```bash +BESU_GENESIS_FILE=/home/me/me_node/customGenesisFile.json +``` + +# Configuration file + +```bash +genesis-file="/home/me/me_node/customGenesisFile.json" +``` + + + +The path to the [genesis file](../../concepts/genesis-file.md). + +:::caution + +You can't use the [`--genesis-file`](#genesis-file) and [`--network`](#network) options at the same time. + +::: + +### `graphql-http-cors-origins` + + + +# Syntax + +```bash +--graphql-http-cors-origins= +``` + +# Example + +```bash +--graphql-http-cors-origins="http://medomain.com","https://meotherdomain.com" +``` + +# Environment variable + +```bash +BESU_GRAPHQL_HTTP_CORS_ORIGINS="http://medomain.com","https://meotherdomain.com" +``` + +# Configuration file + +```bash +graphql-http-cors-origins=["http://medomain.com","https://meotherdomain.com"] +``` + + + +A list of comma-separated origin domain URLs for CORS validation. The default is none. + +### `graphql-http-enabled` + + + +# Syntax + +```bash +--graphql-http-enabled[=] +``` + +# Example + +```bash +--graphql-http-enabled +``` + +# Environment variable + +```bash +BESU_GRAPHQL_HTTP_ENABLED=true +``` + +# Configuration file + +```bash +graphql-http-enabled=true +``` + + + +Enables or disables the GraphQL HTTP service. The default is `false`. + +The default GraphQL HTTP service endpoint is `http://127.0.0.1:8547/graphql` if set to `true`. + +### `graphql-http-host` + + + +# Syntax + +```bash +--graphql-http-host= +``` + +# Example + +```bash +# to listen on all interfaces +--graphql-http-host=0.0.0.0 +``` + +# Environment variable + +```bash +# to listen on all interfaces +BESU_GRAPHQL_HTTP_HOST=0.0.0.0 +``` + +# Configuration file + +```bash +graphql-http-host="0.0.0.0" +``` + + + +The host on which GraphQL HTTP listens. The default is `127.0.0.1`. + +To allow remote connections, set to `0.0.0.0`. + +### `graphql-http-port` + + + +# Syntax + +```bash +--graphql-http-port= +``` + +# Example + +```bash +# to listen on port 6175 +--graphql-http-port=6175 +``` + +# Environment variable + +```bash +# to listen on port 6175 +BESU_GRAPHQL_HTTP_PORT=6175 +``` + +# Configuration file + +```bash +graphql-http-port="6175" +``` + + + +The port (TCP) on which GraphQL HTTP listens. The default is `8547`. Ports must be [exposed appropriately](../../how-to/connect/configure-ports.md). + +### `help` + + + +# Syntax + +```bash +-h, --help +``` + + + +Show the help message and exit. + +### `host-allowlist` + + + +# Syntax + +```bash +--host-allowlist=[,...]... or "*" +``` + +# Example + +```bash +--host-allowlist=medomain.com,meotherdomain.com +``` + +# Environment variable + +```bash +BESU_HOST_ALLOWLIST=medomain.com,meotherdomain.com +``` + +# Configuration file + +```bash +host-allowlist=["medomain.com", "meotherdomain.com"] +``` + + + +A comma-separated list of hostnames to [access the JSON-RPC API](../../how-to/use-besu-api/index.md#host-allowlist) and [pull Besu metrics](../../how-to/monitor/metrics.md). By default, Besu accepts requests from `localhost` and `127.0.0.1`. + +:::info + +This isn't a permissioning feature. To restrict access to the API, we recommend using the [Besu authentication mechanism](../../how-to/use-besu-api/authenticate.md) with username and password authentication or JWT public key authentication. + +::: + +:::note + +If using [Prometheus](https://prometheus.io/) to pull metrics from a node, you must specify all the other nodes you want to pull metrics from in the list of allowed hostnames. + +::: + +:::tip + +To allow all hostnames, use `"*"`. We don't recommend allowing all hostnames for production environments. + +::: + +### `identity` + + + +# Syntax + +```bash +--identity= +``` + +# Example + +```bash +--identity=MyNode +``` + +# Environment variable + +```bash +BESU_IDENTITY=MyNode +``` + +# Configuration file + +```bash +identity="MyNode" +``` + + + +The name for the node. If specified, it's the second section of the client ID provided by some Ethereum network explorers. For example, in the client ID `besu/MyNode/v1.3.4/linux-x86_64/oracle_openjdk-java-11`, the node name is `MyNode`. + +If a name is not specified, the name section is not included in the client ID. For example, `besu/v1.3.4/linux-x86_64/oracle_openjdk-java-11`. + +### `json-pretty-print-enabled` + + + +# Syntax + +```bash +--json-pretty-print-enabled[=] +``` + +# Example + +```bash +--json-pretty-print-enabled=true +``` + +# Environment variable + +```bash +BESU_JSON_PRETTY_PRINT_ENABLED=true +``` + +# Configuration file + +```bash +json-pretty-print-enabled=true +``` + + + +Enables or disables the pretty-print output for HTTP and WebSocket responses. The default is `false`. + +### `key-value-storage` + + + +# Syntax + +```bash +--key-value-storage= +``` + +# Example + +```bash +--key-value-storage=rocksdb +``` + +# Environment variable + +```bash +BESU_KEY_VALUE_STORAGE=rocksdb +``` + +# Configuration file + +```bash +key-value-storage="rocksdb" +``` + + + +The key-value storage to use. Use this option only if using a storage system provided with a plugin. The default is `rocksdb`. + +For development use only, the `memory` option provides ephemeral storage for sync testing and debugging. + +### `kzg-trusted-setup` + + + +# Syntax + +```bash +--kzg-trusted-setup= +``` + +# Example + +```bash +--kzg-trusted-setup=/etc/besu/kzg-trusted-setup.txt +``` + +# Environment variable + +```bash +BESU_KZG_TRUSTED_SETUP=/etc/besu/kzg-trusted-setup.txt +``` + +# Configuration file + +```bash +kzg-trusted-setup=/etc/besu/kzg-trusted-setup.txt +``` + + + +The path to the [C-KZG-4844](https://github.com/ethereum/c-kzg-4844) trusted setup file. Use this option to pass a custom setup file for custom networks or to override the default setup file for named networks. + +### `logging` + + + +# Syntax + +```bash +-l, --logging= +``` + +# Example + +```bash +--logging=DEBUG +``` + +# Environment variable + +```bash +BESU_LOGGING=DEBUG +``` + +# Example configuration file + +```bash +logging="DEBUG" +``` + + + +Sets logging verbosity. Log levels are `OFF`, `FATAL`, `ERROR`, `WARN`, `INFO`, `DEBUG`, `TRACE`, `ALL`. The default is `INFO`. + +### `max-peers` + + + +# Syntax + +```bash +--max-peers= +``` + +# Example + +```bash +--max-peers=42 +``` + +# Environment variable + +```bash +BESU_MAX_PEERS=42 +``` + +# Configuration file + +```bash +max-peers=42 +``` + + + +The maximum number of P2P connections you can establish. The default is 25. + +:::caution + +The minimum number of peers is set by the early access option `--Xp2p-peer-lower-bound`, which also has a default of 25. If you reduce the `--max-peers` from the default, you must also set the `--Xp2p-peer-lower-bound` option to the same value or lower. For example, if you decrease `--max-peers` to 20, set `--Xp2p-peer-lower-bound` to 20 or lower. + +::: + +### `metrics-category` + + + +# Syntax + +```bash +--metrics-category=[,metrics-category...]... +``` + +# Example + +```bash +--metrics-category=BLOCKCHAIN,PEERS,PROCESS +``` + +# Environment variable + +```bash +BESU_METRICS_CATEGORY=BLOCKCHAIN,PEERS,PROCESS +``` + +# Configuration file + +```bash +metrics-category=["BLOCKCHAIN","PEERS","PROCESS"] +``` + + + +A comma-separated list of categories for which to track metrics. The defaults are `BLOCKCHAIN`, `ETHEREUM`, `EXECUTORS`, `JVM`, `NETWORK`, `PEERS`, `PERMISSIONING`, `PROCESS`, `PRUNER`, `RPC`, `STRATUM`, `SYNCHRONIZER`, and `TRANSACTION_POOL`. + +Other categories are `KVSTORE_ROCKSDB`, `KVSTORE_PRIVATE_ROCKSDB`, `KVSTORE_ROCKSDB_STATS`, and `KVSTORE_PRIVATE_ROCKSDB_STATS`. + +Categories containing `PRIVATE` track metrics when you enable [private transactions](../../../private-networks/concepts/privacy/index.md). + +### `metrics-enabled` + + + +# Syntax + +```bash +--metrics-enabled[=] +``` + +# Example + +```bash +--metrics-enabled +``` + +# Environment variable + +```bash +BESU_METRICS_ENABLED=true +``` + +# Configuration file + +```bash +metrics-enabled=true +``` + + + +Enables or disables the [metrics exporter](../../how-to/monitor/metrics.md#monitor-node-performance-using-prometheus). The default is `false`. + +You can't specify `--metrics-enabled` with [`--metrics-push-enabled`](#metrics-push-enabled). That is, you can enable either Prometheus polling or Prometheus push gateway support, but not both at once. + +### `metrics-host` + + + +# Syntax + +```bash +--metrics-host= +``` + +# Example + +```bash +--metrics-host=127.0.0.1 +``` + +# Environment variable + +```bash +BESU_METRICS_HOST=127.0.0.1 +``` + +# Configuration file + +```bash +metrics-host="127.0.0.1" +``` + + + +The host on which [Prometheus](https://prometheus.io/) accesses [Besu metrics](../../how-to/monitor/metrics.md#monitor-node-performance-using-prometheus). The metrics server respects the [`--host-allowlist` option](#host-allowlist). + +The default is `127.0.0.1`. + +### `metrics-port` + + + +# Syntax + +```bash +--metrics-port= +``` + +# Example + +```bash +--metrics-port=6174 +``` + +# Environment variable + +```bash +BESU_METRICS_PORT=6174 +``` + +# Configuration file + +```bash +metrics-port="6174" +``` + + + +The port (TCP) on which [Prometheus](https://prometheus.io/) accesses [Besu metrics](../../how-to/monitor/metrics.md#monitor-node-performance-using-prometheus). The default is `9545`. Ports must be [exposed appropriately](../../how-to/connect/configure-ports.md). + +### `metrics-protocol` + + + +# Syntax + +```bash +--metrics-protocol= +``` + +# Example + +```bash +--metrics-protocol=OPENTELEMETRY +``` + +# Environment variable + +```bash +BESU_METRICS_PROTOCOL=OPENTELEMETRY +``` + +# Configuration file + +```bash +metrics-protocol="OPENTELEMETRY" +``` + + + +Metrics protocol to use: `PROMETHEUS`, `OPENTELEMETRY`, or `NONE`. The default is `PROMETHEUS`. + +### `metrics-push-enabled` + + + +# Syntax + +```bash +--metrics-push-enabled[=] +``` + +# Example + +```bash +--metrics-push-enabled=true +``` + +# Environment variable + +```bash +BESU_METRICS_PUSH_ENABLED=true +``` + +# Configuration file + +```bash +metrics-push-enabled=true +``` + + + +Enables or disables [push gateway integration]. + +You can't specify `--metrics-push-enabled` with [`--metrics-enabled`](#metrics-enabled). That is, you can enable either Prometheus polling or Prometheus push gateway support, but not both at once. + +### `metrics-push-host` + + + +# Syntax + +```bash +--metrics-push-host= +``` + +# Example + +```bash +--metrics-push-host=127.0.0.1 +``` + +# Environment variable + +```bash +BESU_METRICS_PUSH_HOST=127.0.0.1 +``` + +# Configuration file + +```bash +metrics-push-host="127.0.0.1" +``` + + + +The host of the [Prometheus Push Gateway](https://github.com/prometheus/pushgateway). The default is `127.0.0.1`. The metrics server respects the [`--host-allowlist` option](#host-allowlist). + +:::note + +When pushing metrics, ensure you set `--metrics-push-host` to the machine on which the push gateway is. Generally, this is a different machine to the machine on which Besu is running. + +::: + +### `metrics-push-interval` + + + +# Syntax + +```bash +--metrics-push-interval= +``` + +# Example + +```bash +--metrics-push-interval=30 +``` + +# Environment variable + +```bash +BESU_METRICS_PUSH_INTERVAL=30 +``` + +# Configuration file + +```bash +metrics-push-interval=30 +``` + + + +The interval, in seconds, to push metrics when in `push` mode. The default is 15. + +### `metrics-push-port` + + + +# Syntax + +```bash +--metrics-push-port= +``` + +# Example + +```bash +--metrics-push-port=6174 +``` + +# Environment variable + +```bash +BESU_METRICS_PUSH_PORT=6174 +``` + +# Configuration file + +```bash +metrics-push-port="6174" +``` + + + +The port (TCP) of the [Prometheus Push Gateway](https://github.com/prometheus/pushgateway). The default is `9001`. Ports must be [exposed appropriately](../../how-to/connect/configure-ports.md). + +### `metrics-push-prometheus-job` + + + +# Syntax + +```bash +--metrics-push-prometheus-job= +``` + +# Example + +```bash +--metrics-push-prometheus-job="my-custom-job" +``` + +# Environment variable + +```bash +BESU_METRICS_PUSH_PROMETHEUS_JOB="my-custom-job" +``` + +# Configuration file + +```bash +metrics-push-prometheus-job="my-custom-job" +``` + + + +The job name when in `push` mode. The default is `besu-client`. + +### `min-block-occupancy-ratio` + + + +# Syntax + +```bash +--min-block-occupancy-ratio= +``` + +# Example + +```bash +--min-block-occupancy-ratio=0.5 +``` + +# Environment variable + +```bash +BESU_MIN_BLOCK_OCCUPANCY_RATIO=0.5 +``` + +# Configuration file + +```bash +min-block-occupancy-ratio="0.5" +``` + + + +Minimum occupancy ratio for a mined block if the transaction pool is not empty. When filling a block during mining, the occupancy ratio indicates the threshold at which the node stops waiting for smaller transactions to fill the remaining space. The default is 0.8. + +:::note + +Besu ignores the `--min-block-occupancy-ratio` option for proof of stake networks (for example, Mainnet). + +::: + +### `miner-coinbase` + + + +# Syntax + +```bash +--miner-coinbase= +``` + +# Example + +```bash +--miner-coinbase=fe3b557e8fb62b89f4916b721be55ceb828dbd73 +``` + +# Environment variable + +```bash +BESU_MINER_COINBASE=fe3b557e8fb62b89f4916b721be55ceb828dbd73 +``` + +# Configuration file + +```bash +miner-coinbase="0xfe3b557e8fb62b89f4916b721be55ceb828dbd73" +``` + + + +The account you pay mining rewards to. You must specify a valid coinbase when you enable mining using the [`--miner-enabled`](#miner-enabled) option or the [`miner_start`](../api/index.md#miner_start) JSON-RPC API method. + +:::note + +Besu ignores this option in networks using [Clique](../../../private-networks/how-to/configure/consensus/clique.md), [IBFT 2.0](../../../private-networks/how-to/configure/consensus/ibft.md), or [QBFT](../../../private-networks/how-to/configure/consensus/qbft.md) consensus protocols. + +::: + +### `miner-enabled` + + + +# Syntax + +```bash +--miner-enabled[=] +``` + +# Example + +```bash +--miner-enabled=true +``` + +# Environment variable + +```bash +BESU_MINER_ENABLED=true +``` + +# Configuration file + +```bash +miner-enabled=true +``` + + + +Enables or disables mining when you start the node. The default is `false`. + +### `miner-extra-data` + + + +# Syntax + +```bash +--miner-extra-data= +``` + +# Example + +```bash +--miner-extra-data=0x444F4E27542050414E4943202120484F444C2C20484F444C2C20484F444C2021 +``` + +# Environment variable + +```bash +BESU_MINER_EXTRA_DATA=0x444F4E27542050414E4943202120484F444C2C20484F444C2C20484F444C2021 +``` + +# Configuration file + +```bash +miner-extra-data="0x444F4E27542050414E4943202120484F444C2C20484F444C2C20484F444C2021" +``` + + + +A hex string representing the 32 bytes included in the extra data field of a mined block. The default is 0x. + +### `miner-stratum-enabled` + + + +# Syntax + +```bash +--miner-stratum-enabled +``` + +# Environment variable + +```bash +BESU_MINER_STRATUM_ENABLED=true +``` + +# Configuration file + +```bash +miner-stratum-enabled=true +``` + + + +Enables a node to perform stratum mining. The default is `false`. + +### `miner-stratum-host` + + + +# Syntax + +```bash +--miner-stratum-host= +``` + +# Example + +```bash +--miner-stratum-host=192.168.1.132 +``` + +# Environment variable + +```bash +BESU_MINER_STRATUM_HOST=192.168.1.132 +``` + +# Configuration file + +```bash +miner-stratum-host="192.168.1.132" +``` + + + +The host of the stratum mining service. The default is `0.0.0.0`. + +### `miner-stratum-port` + + + +# Syntax + +```bash +--miner-stratum-port= +``` + +# Example + +```bash +--miner-stratum-port=8010 +``` + +# Environment variable + +```bash +BESU_MINER_STRATUM_PORT=8010 +``` + +# Configuration file + +```bash +miner-stratum-port="8010" +``` + + + +The port of the stratum mining service. The default is `8008`. You must [expose ports appropriately](../../how-to/connect/configure-ports.md). + +### `min-gas-price` + + + +# Syntax + +```bash +--min-gas-price= +``` + +# Example + +```bash +--min-gas-price=1337 +``` + +# Environment variable + +```bash +BESU_MIN_GAS_PRICE=1337 +``` + +# Configuration file + +```bash +min-gas-price=1337 +``` + + + +The minimum price a transaction offers to include it in a mined block. The minimum gas price is the lowest value [`eth_gasPrice`](../api/index.md#eth_gasprice) can return. The default is 1000 Wei. + +:::tip + +In a [free gas network](../../../private-networks/how-to/configure/free-gas.md), ensure the minimum gas price is set to zero for every node. Any node with a minimum gas price set higher than zero will silently drop transactions with a zero gas price. You can query a node's gas configuration using [`eth_gasPrice`](../api/index.md#eth_gasprice). + +::: + +### `nat-method` + + + +# Syntax + +```bash +--nat-method=UPNP +``` + +# Example configuration file + +```bash +nat-method="UPNP" +``` + + + +Specify the method for handling [NAT environments](../../how-to/connect/specify-nat.md). The options are: + +- [`UPNP`](../../how-to/connect/specify-nat.md#upnp) +- [`UPNPP2PONLY`](../../how-to/connect/specify-nat.md#upnp) +- [`KUBERNETES`](../../how-to/connect/specify-nat.md#kubernetes) +- [`DOCKER`](../../how-to/connect/specify-nat.md#docker) +- [`AUTO`](../../how-to/connect/specify-nat.md#auto) +- [`NONE`](../../how-to/connect/specify-nat.md#none). + +The default is `AUTO`. `NONE` disables NAT functionality. + +:::tip + +UPnP support is often disabled by default in networking firmware. If disabled by default, explicitly enable UPnP support. + +::: + +:::tip + +Use `UPNPP2PONLY` if you wish to enable UPnP for p2p traffic but not JSON-RPC. + +::: + +:::note + +Specifying `UPNP` might introduce delays during node startup, especially on networks without a UPnP gateway device. + +You must specify `DOCKER` when using the [Besu Docker image](../../get-started/install/run-docker-image.md). + +::: + +### `network` + + + +# Syntax + +```bash +--network= +``` + +# Example + +```bash +--network=goerli +``` + +# Environment variable + +```bash +BESU_NETWORK=goerli +``` + +# Configuration file + +```bash +network="goerli" +``` + + + +The predefined network configuration. The default is `mainnet`. + +Possible values are: + +| Network | Chain | Type | Default Sync Mode | Description | +| :-------- | :---- | :-----------| :----------------- | :------------------------------------------------------------- | +| `mainnet` | ETH | Production | [FAST](#sync-mode) | The main network | +| `goerli` | ETH | Test | [FAST](#sync-mode) | A PoS network | +| `holesky` | ETH | Test | [FAST](#sync-mode) | A PoS network | +| `sepolia` | ETH | Test | [FAST](#sync-mode) | A PoS network | +| `dev` | ETH | Development | [FULL](#sync-mode) | A PoW network with a low difficulty to enable local CPU mining | +| `classic` | ETC | Production | [FAST](#sync-mode) | The main Ethereum Classic network | +| `mordor ` | ETC | Test | [FAST](#sync-mode) | A PoW network | + +:::tip + +Values are case insensitive, so either `mainnet` or `MAINNET` works. + +::: + +:::info + +- You can't use the `--network` and [`--genesis-file`](#genesis-file) options at the same time. + +- The Ropsten, Rinkeby, and Kiln testnets are deprecated. + +::: + +### `network-id` + + + +# Syntax + +```bash +--network-id= +``` + +# Example + +```bash +--network-id=8675309 +``` + +# Environment variable + +```bash +BESU_NETWORK_ID=8675309 +``` + +# Configuration file + +```bash +network-id="8675309" +``` + + + +The [P2P network identifier](../../concepts/network-and-chain-id.md). + +Use this option to override the default network ID. The default value is the same as the chain ID defined in the genesis file. + +### `node-private-key-file` + + + +# Syntax + +```bash +--node-private-key-file= +``` + +# Example + +```bash +--node-private-key-file=/home/me/me_node/myPrivateKey +``` + +# Environment variable + +```bash +BESU_NODE_PRIVATE_KEY_FILE=/home/me/me_node/myPrivateKey +``` + +# Configuration file + +```bash +node-private-key-file="/home/me/me_node/myPrivateKey" +``` + + + +The private key file for the node. The default is the key file in the [data directory](#data-path). If no key file exists, Besu creates a key file containing the generated private key, otherwise, the existing key file specifies the node private key. + +:::danger + +The private key is not encrypted. + +::: + +This option is ignored if [`--security-module`](#security-module) is set to a non-default value. + +### `p2p-enabled` + + + +# Syntax + +```bash +--p2p-enabled[=] +``` + +# Example + +```bash +--p2p-enabled=false +``` + +# Environment variable + +```bash +BESU_P2P_ENABLED=false +``` + +# Configuration file + +```bash +p2p-enabled=false +``` + + + +Enables or disables all P2P communication. The default is `true`. + +### `p2p-host` + + + +# Syntax + +```bash +--p2p-host= +``` + +# Example + +```bash +# to listen on all interfaces +--p2p-host=0.0.0.0 +``` + +# Environment variable + +```bash +# to listen on all interfaces +BESU_P2P_HOST=0.0.0.0 +``` + +# Configuration file + +```bash +p2p-host="0.0.0.0" +``` + + + +The advertised host that can be used to access the node from outside the network in [P2P communication](../../how-to/connect/configure-ports.md#p2p-networking). The default is `127.0.0.1`. + +:::info + +If [`--nat-method`](#nat-method) is set to [`NONE`](../../how-to/connect/specify-nat.md), `--p2p-host` is not overridden and must be specified for the node to be accessed from outside the network. + +::: + +### `p2p-interface` + + + +Syntax + +```bash +--p2p-interface= +``` + +# Example + +```bash +--p2p-interface=192.168.1.132 +``` + +# Environment variable + +```bash +BESU_P2P_INTERFACE=192.168.1.132 +``` + +# Configuration file + +```bash +p2p-interface="192.168.1.132" +``` + + + +The network interface on which the node listens for [P2P communication](../../how-to/connect/configure-ports.md#p2p-networking). Use the option to specify the required network interface when the device that Besu is running on has multiple network interfaces. The default is 0.0.0.0 (all interfaces). + +### `p2p-port` + + + +# Syntax + +```bash +--p2p-port= +``` + +# Example + +```bash +# to listen on port 1789 +--p2p-port=1789 +``` + +# Environment variable + +```bash +# to listen on port 1789 +BESU_P2P_PORT=1789 +``` + +# Configuration file + +```bash +p2p-port="1789" +``` + + + +The P2P listening ports (UDP and TCP). The default is `30303`. You must [expose ports appropriately](../../how-to/connect/configure-ports.md). + +### `pruning-block-confirmations` + + + +# Syntax + +```bash +--pruning-block-confirmations= +``` + +# Example + +```bash +--pruning-block-confirmations=5 +``` + +# Environment variable + +```bash +BESU_PRUNING_BLOCK_CONFIRMATIONS=5 +``` + +# Configuration file + +```bash +pruning-block-confirmations=5 +``` + + + +The minimum number of confirmations on a block before marking of newly-stored or in-use state trie nodes that cannot be pruned. The default is 10. + +:::info + +Using pruning with [private transactions](../../../private-networks/concepts/privacy/index.md) is not supported. + +::: + +### `pruning-blocks-retained` + + + +# Syntax + +```bash +--pruning-blocks-retained= +``` + +# Example + +```bash +--pruning-blocks-retained=10000 +``` + +# Environment variable + +```bash +BESU_PRUNING_BLOCKS_RETAINED=10000 +``` + +# Configuration file + +```bash +pruning-blocks-retained=10000 +``` + + + +The minimum number of recent blocks to keep the entire world state for. The default is 1024. + +:::info + +Using pruning with [private transactions](../../../private-networks/concepts/privacy/index.md) isn't supported. + +::: + +### `pruning-enabled` + + + +# Syntax + +```bash +--pruning-enabled +``` + +# Example + +```bash +--pruning-enabled=true +``` + +# Environment variable + +```bash +BESU_PRUNING_ENABLED=true +``` + +# Configuration file + +```bash +pruning-enabled=true +``` + + + +Enables [pruning](../../concepts/data-storage-formats.md#pruning) to reduce storage required for the world state. The default is `false`. + +:::info + +Using pruning with [private transactions](../../../private-networks/concepts/privacy/index.md) isn't supported. + +::: + +:::note + +Pruning is being deprecated for [Bonsai Tries](../../concepts/data-storage-formats.md#bonsai-tries) and is currently not being updated. + +::: + +### `random-peer-priority-enabled` + + + +# Syntax + +```bash +--random-peer-priority-enabled[=] +``` + +# Example + +```bash +--random-peer-priority-enabled=true +``` + +# Environment variable + +```bash +BESU_RANDOM_PEER_PRIORITY_ENABLED=true +``` + +# Configuration file + +```bash +random-peer-priority-enabled=true +``` + + + +Enables or disables random prioritization of incoming connections. Enable in small, stable networks to prevent closed groups of peers forming. The default is `false`. + +### `remote-connections-limit-enabled` + + + +# Syntax + +```bash +--remote-connections-limit-enabled[=] +``` + +# Example + +```bash +--remote-connections-limit-enabled=false +``` + +# Environment variable + +```bash +BESU_REMOTE_CONNECTIONS_LIMIT_ENABLED=false +``` + +# Configuration file + +```bash +remote-connections-limit-enabled=false +``` + + + +Enables or disables using the [`--remote-connections-max-percentage`](#remote-connections-max-percentage) option to limit the percentage of remote P2P connections initiated by peers. The default is `true`. + +:::tip + +In private and permissioned networks with a level of trust between peers, disabling the remote connection limits may increase the speed at which nodes can join the network. + +::: + +:::danger + +To prevent eclipse attacks, ensure you enable the remote connections limit when connecting to any public network, and especially when using [`--sync-mode`](#sync-mode) and [`--fast-sync-min-peers`](#fast-sync-min-peers). + +::: + +### `remote-connections-max-percentage` + + + +# Syntax + +```bash +--remote-connections-max-percentage= +``` + +# Example + +```bash +--remote-connections-max-percentage=25 +``` + +# Environment variable + +```bash +BESU_REMOTE_CONNECTIONS_MAX_PERCENTAGE=25 +``` + +# Configuration file + +```bash +remote-connections-max-percentage=25 +``` + + + +The percentage of remote P2P connections you can establish with the node. Must be between 0 and 100, inclusive. The default is 60. + +### `reorg-logging-threshold` + + + +# Syntax + +```bash +--reorg-logging-threshold= +``` + +# Example + +```bash +--reorg-logging-threshold=3 +``` + +# Environment variable + +```bash +BESU_REORG_LOGGING_THRESHOLD=3 +``` + +# Configuration file + +```bash +reorg-logging-threshold=3 +``` + + + +Minimum depth of chain reorganizations to log. The default is 6. + +### `required-block` + + + +# Syntax + +```bash +--required-block, --required-blocks[=BLOCK=HASH[,BLOCK=HASH...]...] +``` + +# Example + +```bash +--required-block=6485846=0x43f0cd1e5b1f9c4d5cda26c240b59ee4f1b510d0a185aa8fd476d091b0097a80 +``` + +# Environment variable + +```bash +BESU_REQUIRED_BLOCK=6485846=0x43f0cd1e5b1f9c4d5cda26c240b59ee4f1b510d0a185aa8fd476d091b0097a80 +``` + +# Configuration file + +```bash +required-block=["6485846=0x43f0cd1e5b1f9c4d5cda26c240b59ee4f1b510d0a185aa8fd476d091b0097a80"] +``` + + + +Requires a peer with the specified block number to have the specified hash when connecting, or Besu rejects that peer. + +### `revert-reason-enabled` + + + +# Syntax + +```bash +--revert-reason-enabled[=] +``` + +# Example + +```bash +--revert-reason-enabled=true +``` + +# Environment variable + +```bash +BESU_REVERT_REASON_ENABLED=true +``` + +# Configuration file + +```bash +revert-reason-enabled=true +``` + + + +Enables or disables including the [revert reason](../../../private-networks/how-to/send-transactions/revert-reason.md) in the transaction receipt, [`eth_estimateGas`](../api/index.md#eth_estimategas) error response, [`eth_call`](../api/index.md#eth_call) error response, and [`trace`](../trace-types.md#trace) response. The default is `false`. + +:::caution + +Enabling revert reason may use a significant amount of memory. We don't recommend enabling revert reason when connected to public Ethereum networks. + +::: + +### `rpc-http-api` + + + +# Syntax + +```bash +--rpc-http-api=[,...]... +``` + +# Example + +```bash +--rpc-http-api=ETH,NET,WEB3 +``` + +# Environment variable + +```bash +BESU_RPC_HTTP_API=ETH,NET,WEB3 +``` + +# Configuration file + +```bash +rpc-http-api=["ETH","NET","WEB3"] +``` + + + +A comma-separated list of APIs to enable on the HTTP JSON-RPC channel. When you use this option you must also specify the `--rpc-http-enabled` option. The available API options are: `ADMIN`, `CLIQUE`, `DEBUG`, `EEA`, `ETH`, `IBFT`, `MINER`, `NET`, `PERM`, `PLUGINS`, `PRIV`, `QBFT`, `TRACE`, `TXPOOL`, and `WEB3`. The default is: `ETH`, `NET`, `WEB3`. + +:::tip + +The singular `--rpc-http-api` and plural `--rpc-http-apis` are available and are two names for the same option. + +::: + +### `rpc-http-authentication-credentials-file` + + + +# Syntax + +```bash +--rpc-http-authentication-credentials-file= +``` + +# Example + +```bash +--rpc-http-authentication-credentials-file=/home/me/me_node/auth.toml +``` + +# Environment variable + +```bash +BESU_RPC_HTTP_AUTHENTICATION_CREDENTIALS_FILE=/home/me/me_node/auth.toml +``` + +# Configuration file + +```bash +rpc-http-authentication-credentials-file="/home/me/me_node/auth.toml" +``` + + + +The [credentials file](../../how-to/use-besu-api/authenticate.md#credentials-file) for JSON-RPC API [authentication](../../how-to/use-besu-api/authenticate.md). + +### `rpc-http-authentication-enabled` + + + +# Syntax + +```bash +--rpc-http-authentication-enabled[=] +``` + +# Example + +```bash +--rpc-http-authentication-enabled=true +``` + +# Environment variable + +```bash +BESU_RPC_HTTP_AUTHENTICATION_ENABLED=true +``` + +# Configuration file + +```bash +rpc-http-authentication-enabled=true +``` + + + +Enables or disables [authentication](../../how-to/use-besu-api/authenticate.md) for the HTTP JSON-RPC service. + +### `rpc-http-authentication-jwt-public-key-file` + + + +# Syntax + +```bash +--rpc-http-authentication-jwt-public-key-file= +``` + +# Example + +```bash +--rpc-http-authentication-jwt-public-key-file=publicKey.pem +``` + +# Environment variable + +```bash +BESU_RPC_HTTP_AUTHENTICATION_JWT_PUBLIC_KEY_FILE="publicKey.pem" +``` + +# Configuration file + +```bash +rpc-http-authentication-jwt-public-key-file="publicKey.pem" +``` + + + +The [JWT provider's public key file] used for JSON-RPC HTTP authentication with an external JWT. + +### `rpc-http-cors-origins` + + + +# Syntax + +```bash +--rpc-http-cors-origins=[,...]... or all or "*" +``` + +# Example + +```bash + +$# You can allow one or more domains with a comma-separated list. + +--rpc-http-cors-origins=http://medomain.com,https://meotherdomain.com +``` + +# Environment variable + +```bash +BESU_RPC_HTTP_CORS_ORIGINS=http://medomain.com,https://meotherdomain.com +``` + +# Configuration file + +```bash +rpc-http-cors-origins=["http://medomain.com","https://meotherdomain.com"] +``` + +# Remix example + +```bash + +$# The following allows Remix to interact with your Besu node. + +--rpc-http-cors-origins=http://remix.ethereum.org +``` + + + +A list of domain URLs for CORS validation. + +Listed domains can access the node using JSON-RPC. If your client interacts with Besu using a browser app (such as Remix or a block explorer), add the client domain to the list. + +The default value is `"none"`. If you do not list any domains, browser apps cannot interact with your Besu node. + +:::note + +To run a local Besu node with MetaMask, set `--rpc-http-cors-origins` to `chrome-extension://nkbihfbeogaeaoehlefnkodbefgpgknn`. + +Remember to also include the dapp domain MetaMask interacts with, for example if your app is deployed on Remix and you're using MetaMask to interact with the contract, use `--rpc-http-cors-origins=chrome-extension://nkbihfbeogaeaoehlefnkodbefgpgknn,http://remix.ethereum.org` + +::: + +:::tip + +For testing and development purposes, use `"all"` or `"*"` to accept requests from any domain. We don't recommend accepting requests from any domain for production environments. + +::: + +### `rpc-http-enabled` + + + +# Syntax + +```bash +--rpc-http-enabled[=] +``` + +# Example + +```bash +--rpc-http-enabled=true +``` + +# Environment variable + +```bash +BESU_RPC_HTTP_ENABLED=true +``` + +# Configuration file + +```bash +rpc-http-enabled=true +``` + + + +Enables or disables the HTTP JSON-RPC service. The default is `false`. + +### `rpc-http-host` + + + +# Syntax + +```bash +--rpc-http-host= +``` + +# Example + +```bash +# to listen on all interfaces +--rpc-http-host=0.0.0.0 +``` + +# Environment variable + +```bash +BESU_RPC_HTTP_HOST=0.0.0.0 +``` + +# Configuration file + +```bash +rpc-http-host="0.0.0.0" +``` + + + +The host on which HTTP JSON-RPC listens. The default is `127.0.0.1`. + +To allow remote connections, set to `0.0.0.0`. + +:::caution + +Setting the host to `0.0.0.0` exposes the RPC connection on your node to any remote connection. In a production environment, ensure you are using a firewall to avoid exposing your node to the internet. + +::: + +### `rpc-http-max-active-connections` + + + +# Syntax + +```bash +--rpc-http-max-active-connections= +``` + +# Example + +```bash +--rpc-http-max-active-connections=100 +``` + +# Environment variable + +```bash +BESU_RPC_HTTP_MAX_ACTIVE_CONNECTIONS=100 +``` + +# Configuration file + +```toml +rpc-http-max-active-connections=100 +``` + + + +The maximum number of allowed HTTP JSON-RPC connections. Once this limit is reached, incoming connections are rejected. The default is 80. + +### `rpc-http-max-request-content-length` + + + +# Syntax + +```bash +--rpc-http-max-request-content-length= +``` + +# Example + +```bash +--rpc-http-max-request-content-length=2097152 +``` + +# Environment variable + +```bash +BESU_RPC_HTTP_MAX_REQUEST_CONTENT_LENGTH=2097152 +``` + +# Configuration file + +```toml +rpc-http-max-request-content-length=2097152 +``` + + + +The maximum request content length. +Besu only accepts JSON-RPC API requests with a body size less than or equal to this value. +The default is 5242880 (5 MB). + +### `rpc-http-max-batch-size` + + + +# Syntax + +```bash +--rpc-http-max-batch-size= +``` + +# Example + +```bash +--rpc-http-max-batch-size=1200 +``` + +# Environment variable + +```bash +BESU_RPC_HTTP_MAX_BATCH_SIZE=1200 +``` + +# Configuration file + +```toml +rpc-http-max-batch-size=1200 +``` + + + +The maximum number of allowed requests in a [RPC batch request](../../how-to/use-besu-api/json-rpc.md#http). The default limit is `1024`, and `-1` specifies no limit. + +### `rpc-http-port` + + + +# Syntax + +```bash +--rpc-http-port= +``` + +# Example + +```bash +# to listen on port 3435 +--rpc-http-port=3435 +``` + +# Environment variable + +```bash +BESU_RPC_HTTP_PORT=3435 +``` + +# Configuration file + +```bash +rpc-http-port="3435" +``` + + + +The port (TCP) on which HTTP JSON-RPC listens. The default is `8545`. You must [expose ports appropriately](../../how-to/connect/configure-ports.md). + +### `rpc-http-tls-ca-clients-enabled` + + + +# Syntax + +```bash +--rpc-http-tls-ca-clients-enabled[=] +``` + +# Example + +```bash +--rpc-http-tls-ca-clients-enabled=true +``` + +# Environment variable + +```bash +BESU_RPC_HTTP_TLS_CA_CLIENTS_ENABLED=true +``` + +# Configuration file + +```bash +rpc-http-tls-ca-clients-enabled=true +``` + + + +Enables or disables clients with trusted CA certificates to connect. The default is `false`. + +:::note + +You must enable client authentication using the [`--rpc-http-tls-client-auth-enabled`](#rpc-http-tls-client-auth-enabled) option. + +::: + +### `rpc-http-tls-client-auth-enabled` + + + +# Syntax + +```bash +--rpc-http-tls-client-auth-enabled[=] +``` + +# Example + +```bash +--rpc-http-tls-client-auth-enabled=true +``` + +# Environment variable + +```bash +BESU_RPC_HTTP_TLS_CLIENT_AUTH_ENABLED=true +``` + +# Configuration file + +```bash +rpc-http-tls-client-auth-enabled=true +``` + + + +Enables or disables TLS client authentication for the JSON-RPC HTTP service. The default is `false`. + +:::note + +You must specify [`--rpc-http-tls-ca-clients-enabled`](#rpc-http-tls-ca-clients-enabled) and/or [`rpc-http-tls-known-clients-file`](#rpc-http-tls-known-clients-file). + +::: + +### `rpc-http-tls-cipher-suite` + + + +# Syntax + +```bash +--rpc-http-tls-cipher-suite=[, ...] +``` + +# Example + +```bash +--rpc-http-tls-cipher-suite=TLS_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 +``` + +# Environment variable + +```bash +BESU_RPC_HTTP_TLS_CIPHER_SUITE=TLS_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 +``` + +# Configuration file + +```bash +rpc-http-tls-cipher-suite=["TLS_AES_256_GCM_SHA384","TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384","TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256"] +``` + + + +A list of comma-separated TLS cipher suites to support. + +:::tip + +The singular `--rpc-http-tls-cipher-suite` and plural `--rpc-http-tls-cipher-suites` are available and are two names for the same option. + +::: + +### `rpc-http-tls-enabled` + + + +# Syntax + +```bash +--rpc-http-tls-enabled[=] +``` + +# Example + +```bash +--rpc-http-tls-enabled=true +``` + +# Environment variable + +```bash +BESU_RPC_HTTP_TLS_ENABLED=true +``` + +# Configuration file + +```bash +rpc-http-tls-enabled=true +``` + + + +Enables or disables TLS for the JSON-RPC HTTP service. The default is `false`. + +:::note + +[`--rpc-http-enabled`](#rpc-http-enabled) must be enabled. + +::: + +### `rpc-http-tls-keystore-file` + + + +# Syntax + +```bash +--rpc-http-tls-keystore-file= +``` + +# Example + +```bash +--rpc-http-tls-keystore-file=/home/me/me_node/keystore.pfx +``` + +# Environment variable + +```bash +BESU_RPC_HTTP_TLS_KEYSTORE_FILE=/home/me/me_node/keystore.pfx +``` + +# Configuration file + +```bash +rpc-http-tls-keystore-file="/home/me/me_node/keystore.pfx" +``` + + + +The Keystore file (in PKCS #12 format) that contains private key and the certificate presented to the client during authentication. + +### `rpc-http-tls-keystore-password-file` + + + +# Syntax + +```bash +--rpc-http-tls-keystore-password-file= +``` + +# Example + +```bash +--rpc-http-tls-keystore-password-file=/home/me/me_node/password +``` + +# Environment variable + +```bash +BESU_RPC_HTTP_TLS_KEYSTORE_PASSWORD_FILE=/home/me/me_node/password +``` + +# Configuration file + +```bash +rpc-http-tls-keystore-password-file="/home/me/me_node/password" +``` + + + +The path to the file containing the password to decrypt the keystore. + +### `rpc-http-tls-known-clients-file` + + + +# Syntax + +```bash +--rpc-http-tls-known-clients-file= +``` + +# Example + +```bash +--rpc-http-tls-known-clients-file=/home/me/me_node/knownClients +``` + +# Environment variable + +```bash +BESU_RPC_HTTP_TLS_KNOWN_CLIENTS_FILE=/home/me/me_node/knownClients +``` + +# Configuration file + +```bash +rpc-http-tls-known-clients-file="/home/me/me_node/knownClients" +``` + + + +The path to the file used to [authenticate clients](../../../private-networks/how-to/configure/tls/client-and-server.md#create-the-known-clients-file) using self-signed certificates or non-public certificates. + +Must contain the certificate's Common Name, and SHA-256 fingerprint in the format ` `. + +:::note + +You must enable client authentication using the [`--rpc-http-tls-client-auth-enabled`](#rpc-http-tls-client-auth-enabled) option. + +::: + +### `rpc-http-tls-protocol` + + + +# Syntax + +```bash +--rpc-http-tls-protocol=[, ...] +``` + +# Example + +```bash +--rpc-http-tls-protocol=TLSv1.3,TLSv1.2 +``` + +# Environment variable + +```bash +BESU_RPC_HTTP_TLS_PROTOCOL=TLSv1.3,TLSv1.2 +``` + +# Configuration file + +```bash +rpc-http-tls-protocol=["TLSv1.3","TLSv1.2"] +``` + + + +A list of comma-separated TLS protocols to support. The default is `DEFAULT_TLS_PROTOCOLS`, a list which includes `TLSv1.3` and `TLSv1.2`. + +:::tip + +The singular `--rpc-http-tls-protocol` and plural `--rpc-http-tls-protocols` are available and are two names for the same option. + +::: + +### `rpc-max-logs-range` + + + +# Syntax + +```bash +--rpc-max-logs-range= +``` + +# Example + +```bash +--rpc-max-logs-range=500 +``` + +# Environment variable + +```bash +BESU_RPC_MAX_LOGS_RANGE=500 +``` + +# Configuration file + +```bash +rpc-max-logs-range=500 +``` + + + +When using [`eth_getLogs`](../api/index.md#eth_getlogs), the maximum number of blocks to retrieve logs from. Set to 0 to specify no limit. The default is 5000. + +:::caution + +Using `eth_getLogs` to get logs from a large range of blocks, especially an entire chain from its genesis block, might cause Besu to hang for an indeterminable amount of time while generating the response. + +We recommend setting a range limit or leaving this option at its default value. + +::: + +### `rpc-tx-feecap` + + + +# Syntax + +```bash +--rpc-tx-feecap= +``` + +# Example + +```bash +--rpc-tx-feecap=1200000000000000000 +``` + +# Environment variable + +```bash +BESU_RPC_TX_FEECAP=1200000000000000000 +``` + +# Configuration file + +```bash +rpc-tx-feecap=1200000000000000000 +``` + + + +The maximum transaction fee (in Wei) accepted for transactions submitted through the [`eth_sendRawTransaction`](../api/index.md#eth_sendrawtransaction) RPC. The default is 1000000000000000000 (1 ether). + +If set to 0, then this option is ignored and no cap is applied. + +### `rpc-ws-api` + + + +# Syntax + +```bash +--rpc-ws-api=[,...]... +``` + +# Example + +```bash +--rpc-ws-api=ETH,NET,WEB3 +``` + +# Environment variable + +```bash +BESU_RPC_WS_API=ETH,NET,WEB3 +``` + +# Configuration file + +```bash +rpc-ws-api=["ETH","NET","WEB3"] +``` + + + +A comma-separated list of APIs to enable on the WebSockets channel. When you use this option you must also specify the `--rpc-ws-enabled` option. The available API options are: `ADMIN`, `CLIQUE`, `DEBUG`, `EEA`, `ETH`, `IBFT`, `MINER`, `NET`, `PERM`, `PLUGINS`, `PRIV`, `QBFT`, `TRACE`, `TXPOOL`, and `WEB3`. The default is: `ETH`, `NET`, `WEB3`. + +:::tip + +The singular `--rpc-ws-api` and plural `--rpc-ws-apis` options are available and are two names for the same option. + +::: + +### `rpc-ws-authentication-credentials-file` + + + +# Syntax + +```bash +--rpc-ws-authentication-credentials-file= +``` + +# Example + +```bash +--rpc-ws-authentication-credentials-file=/home/me/me_node/auth.toml +``` + +# Environment variable + +```bash +BESU_RPC_WS_AUTHENTICATION_CREDENTIALS_FILE=/home/me/me_node/auth.toml +``` + +# Configuration file + +```bash +rpc-ws-authentication-credentials-file="/home/me/me_node/auth.toml" +``` + + + +The path to the [credentials file](../../how-to/use-besu-api/authenticate.md#credentials-file) for JSON-RPC API [authentication](../../how-to/use-besu-api/authenticate.md). + +### `rpc-ws-authentication-enabled` + + + +# Syntax + +```bash +--rpc-ws-authentication-enabled[=] +``` + +# Example + +```bash +--rpc-ws-authentication-enabled=true +``` + +# Environment variable + +```bash +BESU_RPC_WS_AUTHENTICATION_ENABLED=true +``` + +# Configuration file + +```bash +rpc-ws-authentication-enabled=true +``` + + + +Enables or disables [authentication](../../how-to/use-besu-api/authenticate.md) for the WebSocket JSON-RPC service. + +:::note + +`wscat` doesn't support headers. [Authentication](../../how-to/use-besu-api/authenticate.md) requires you to pass an authentication token in the request header. To use authentication with WebSockets, you need an app that supports headers. + +::: + +### `rpc-ws-authentication-jwt-public-key-file` + + + +# Syntax + +```bash +--rpc-ws-authentication-jwt-public-key-file= +``` + +# Example + +```bash +--rpc-ws-authentication-jwt-public-key-file=publicKey.pem +``` + +# Environment variable + +```bash +BESU_RPC_WS_AUTHENTICATION_JWT_PUBLIC_KEY_FILE="publicKey.pem" +``` + +# Configuration file + +```bash +rpc-ws-authentication-jwt-public-key-file="publicKey.pem" +``` + + + +The [JWT provider's public key file] used for JSON-RPC WebSocket authentication with an external JWT. + +### `rpc-ws-enabled` + + + +# Syntax + +```bash +--rpc-ws-enabled[=] +``` + +# Example + +```bash +--rpc-ws-enabled=true +``` + +# Environment variable + +```bash +BESU_RPC_WS_ENABLED=true +``` + +# Configuration file + +```bash +rpc-ws-enabled=true +``` + + + +Enables or disables the WebSocket JSON-RPC service. The default is `false`. + +### `rpc-ws-host` + + + +# Syntax + +```bash +--rpc-ws-host= +``` + +# Example + +```bash +# to listen on all interfaces +--rpc-ws-host=0.0.0.0 +``` + +# Environment variable + +```bash +BESU_RPC_WS_HOST=0.0.0.0 +``` + +# Configuration file + +```bash +rpc-ws-host="0.0.0.0" +``` + + + +The host on which WebSocket JSON-RPC listens. +The default is `127.0.0.1`. + +To allow remote connections, set to `0.0.0.0` + +### `rpc-ws-max-active-connections` + + + +# Syntax + +```bash +--rpc-ws-max-active-connections= +``` + +# Example + +```bash +--rpc-ws-max-active-connections=100 +``` + +# Environment variable + +```bash +BESU_RPC_WS_MAX_ACTIVE_CONNECTIONS=100 +``` + +# Configuration file + +```toml +rpc-ws-max-active-connections=100 +``` + + + +The maximum number of WebSocket connections allowed for JSON-RPC. Once this limit is reached, incoming connections are rejected. The default is 80. + +### `rpc-ws-max-frame-size` + + + +# Syntax + +```bash +--rpc-ws-max-frame-size= +``` + +# Example + +```bash +--rpc-ws-max-frame-size=65536 +``` + +# Environment variable + +```bash +BESU_RPC_WS_MAX_FRAME_SIZE=65536 +``` + +# Configuration file + +```toml +rpc-ws-max-frame-size=65536 +``` + + + +The maximum size in bytes for JSON-RPC WebSocket frames. If this limit is exceeded, the WebSocket disconnects. The default is 1048576 (or 1 MB). + +### `rpc-ws-port` + + + +# Syntax + +```bash +--rpc-ws-port= +``` + +# Example + +```bash +# to listen on port 6174 +--rpc-ws-port=6174 +``` + +# Environment variable + +```bash +BESU_RPC_WS_PORT=6174 +``` + +# Configuration file + +```bash +rpc-ws-port="6174" +``` + + + +The port (TCP) on which WebSocket JSON-RPC listens. The default is `8546`. You must [expose ports appropriately](../../how-to/connect/configure-ports.md). + +### `security-module` + + + +# Syntax + +```bash +--security-module= +``` + +# Example + +```bash +--security-module=security_module +``` + +# Environment variable + +```bash +BESU_SECURITY_MODULE=security_module +``` + +# Configuration file + +```bash +security-module="security_module" +``` + + + +Name of the security module plugin to use. For example, a Hardware Security Module (HSM) or V3 filestore plugin. + +The default is the node's local private key file specified using [`--node-private-key-file`](#node-private-key-file). + +### `static-nodes-file` + + + +# Syntax + +```bash +--static-nodes-file= +``` + +# Example + +```bash +--static-nodes-file=~/besudata/static-nodes.json +``` + +# Environment variable + +```bash +BESU_STATIC_NODES_FILE=~/besudata/static-nodes.json +``` + +# Configuration file + +```bash +static-nodes-file="~/besudata/static-nodes.json" +``` + + + +Static nodes JSON file containing the [static nodes](../../how-to/connect/static-nodes.md) for this node to connect to. The default is `datapath/static-nodes.json`. + +### `strict-tx-replay-protection-enabled` + + + +# Syntax + +```bash +--strict-tx-replay-protection-enabled[=] +``` + +# Example + +```bash +--strict-tx-replay-protection-enabled=false +``` + +# Environment variable + +```bash +STRICT_TX_REPLAY_PROTECTION_ENABLED=false +``` + +# Configuration file + +```bash +strict-tx-replay-protection-enabled=false +``` + + + +Enables or disables replay protection, in accordance with [EIP-155](https://eips.ethereum.org/EIPS/eip-155), on transactions submitted using JSON-RPC. The default is `false`. + +### `sync-mode` + + + +# Syntax + +```bash +--sync-mode=X_SNAP +``` + +# Example + +```bash +--sync-mode=X_SNAP +``` + +# Environment variable + +```bash +BESU_SYNC_MODE=X_SNAP +``` + +# Configuration file + +```bash +sync-mode="X_SNAP" +``` + + + +The synchronization mode. Use `X_SNAP` for [snap sync](../../get-started/connect/sync-node.md#snap-synchronization), `X_CHECKPOINT` for [checkpoint sync](../../get-started/connect/sync-node.md#checkpoint-synchronization), `FAST` for [fast sync](../../get-started/connect/sync-node.md#fast-synchronization), and `FULL` for [full sync](../../get-started/connect/sync-node.md#run-an-archive-node). + +- The default is `FULL` when connecting to a private network by not using the [`--network`](#network) option and specifying the [`--genesis-file`](#genesis-file) option. +- The default is `FAST` when using the [`--network`](#network) option with named networks, except for the `dev` development network. `FAST` is also the default if running Besu on the default network (Ethereum Mainnet) by specifying neither [network](#network) nor [genesis file](#genesis-file). + +:::tip + +- We recommend using snap sync over fast sync because snap sync can be faster by several days. +- Checkpoint sync is an early access feature. +- It might become impossible to sync Ethereum Mainnet using fast sync in the future. Update Besu to a version that supports newer sync methods. +- When synchronizing in a mode other than `FULL`, most historical world state data is unavailable. Any methods attempting to access unavailable world state data return `null`. + +::: + +### `target-gas-limit` + + + +# Syntax + +```bash +--target-gas-limit= +``` + +# Example + +```bash +--target-gas-limit=8000000 +``` + +# Environment variable + +```bash +BESU_TARGET_GAS_LIMIT=8000000 +``` + +# Configuration file + +```bash +target-gas-limit="8000000" +``` + + + +The gas limit toward which Besu will gradually move on an existing network, if enough miners are in agreement. To change the block gas limit set in the genesis file without creating a new network, use `target-gas-limit`. The gas limit between blocks can change only 1/1024th, so the target tells the block creator how to set the gas limit in its block. If the values are the same or within 1/1024th, Besu sets the limit to the specified value. Otherwise, the limit moves as far as it can within that constraint. + +If a value for `target-gas-limit` is not specified, the block gas limit remains at the value specified in the [genesis file](../genesis-items.md#genesis-block-parameters). + +Use the [`miner_changeTargetGasLimit`](../api/index.md#miner_changetargetgaslimit) API to update the `target-gas-limit` while Besu is running. Alternatively restart Besu with an updated `target-gas-limit` value. + +### `tx-pool-disable-locals` + + + +# Syntax + +```bash +--tx-pool-disable-locals[=] +``` + +# Example + +```bash +--tx-pool-disable-locals=true +``` + +# Environment variable + +```bash +BESU_TX_POOL_DISABLE_LOCALS=true +``` + +# Configuration file + +```bash +tx-pool-disable-locals=true +``` + + + +If this option is set to true, transactions received via RPC must have the same checks, and should not be prioritized +over remote transactions. The default is `false`. + +### `tx-pool-enable-save-restore` + + + +# Syntax + +```bash +--tx-pool-enable-save-restore[=] +``` + +# Example + +```bash +--tx-pool-enable-save-restore=true +``` + +# Environment variable + +```bash +BESU_TX_POOL_ENABLE_SAVE_RESTORE=true +``` + +# Configuration file + +```bash +tx-pool-enable-save-restore=true +``` + + + +Enables or disables saving the transaction pool contents to a file on shutdown and reloading it at startup. +The default is `false`. + +You can define a custom path to the transaction pool file using the [`--tx-pool-save-file`](#tx-pool-save-file) option. + +### `tx-pool-limit-by-account-percentage` + + + +# Syntax + +```bash +--tx-pool-limit-by-account-percentage= +``` + +# Example + +```bash +--tx-pool-limit-by-account-percentage=0.1 +``` + +# Environment variable + +```bash +BESU_TX_POOL_LIMIT_BY_ACCOUNT_PERCENTAGE=0.1 +``` + +# Configuration file + +```bash +tx-pool-limit-by-account-percentage=0.4 +``` + + + +The maximum percentage of future transactions kept in the transaction pool, per account. Accepted values are in the range (0–1]. The default is .001 or 0.1% of transactions from a single account to be kept in the pool. + +:::caution + +The default value is often unsuitable for [private networks](../../../private-networks/index.md). This feature mitigates future-nonce transactions from filling the pool without ever being executable by Besu. This is important for Mainnet, but may cause issues on private networks. Please update this value or set to 1 if you know the nodes gossiping transactions in your network. + +::: + +### `tx-pool-max-size` + + + +# Syntax + +```bash +--tx-pool-max-size= +``` + +# Example + +```bash +--tx-pool-max-size=2000 +``` + +# Environment variable + +```bash +BESU_TX_POOL_MAX_SIZE=2000 +``` + +# Configuration file + +```bash +tx-pool-max-size="2000" +``` + + + +The maximum number of transactions kept in the transaction pool. The default is 4096. + +### `tx-pool-price-bump` + + + +# Syntax + +```bash +--tx-pool-price-bump= +``` + +# Example + +```bash +--tx-pool-price-bump=25 +``` + +# Environment variable + +```bash +BESU_TX_POOL_PRICE_BUMP=25 +``` + +# Configuration file + +```bash +tx-pool-price-bump=25 +``` + + + +The price bump percentage to replace an existing transaction. The default is 10. + +### `tx-pool-retention-hours` + + + +# Syntax + +```bash +--tx-pool-retention-hours= +``` + +# Example + +```bash +--tx-pool-retention-hours=5 +``` + +# Environment variable + +```bash +BESU_TX_POOL_RETENTION_HOURS=5 +``` + +# Configuration file + +```bash +tx-pool-retention-hours=5 +``` + + + +The maximum period, in hours, to hold pending transactions in the transaction pool. The default is 13. + +### `tx-pool-save-file` + + + +# Syntax + +```bash +--tx-pool-save-file= +``` + +# Example + +```bash +--tx-pool-save-file=/home/me/me_node/node_txpool.dump +``` + +# Environment variable + +```bash +BESU_TX_POOL_SAVE_FILE=/home/me/me_node/node_txpool.dump +``` + +# Configuration file + +```bash +tx-pool-save-file="/home/me/me_node/node_txpool.dump" +``` + + + +Path to the file that stores the transaction pool's content if the save and restore functionality is enabled +using [`--tx-pool-enable-save-restore`](#tx-pool-enable-save-restore). The +file is created on shutdown and reloaded during startup. The default file name is `txpool.dump` in the +[data directory](#data-path). + +### `Xhelp` + + + +# Syntax + +```bash +-X, --Xhelp +``` + + + +Displays the early access options and their descriptions, and exit. + +:::caution + +The displayed options are unstable and may change between releases. + +::: + +### `version` + + + +# Syntax + +```bash +-V, --version +``` + + + +Prints version information and exit. + + + +[push gateway integration]: ../../how-to/monitor/metrics.md#running-prometheus-with-besu-in-push-mode +[JWT provider's public key file]: ../../how-to/use-besu-api/authenticate.md#jwt-public-key-authentication diff --git a/versioned_docs/version-23.10.1/public-networks/reference/cli/subcommands.md b/versioned_docs/version-23.10.1/public-networks/reference/cli/subcommands.md new file mode 100644 index 00000000000..2edad520f93 --- /dev/null +++ b/versioned_docs/version-23.10.1/public-networks/reference/cli/subcommands.md @@ -0,0 +1,264 @@ +--- +title: Subcommands +description: Hyperledger Besu command line interface subcommands +sidebar_position: 2 +tags: + - public networks + - private networks +--- + +# Subcommands + +This reference describes the syntax of the Hyperledger Besu command line interface (CLI) subcommands. + +:::note + +This reference contains subcommands that apply to both public and private networks. For private-network-specific subcommands, see the [private network subcommands reference](../../../private-networks/reference/cli/subcommands.md). + +::: + +To start a Besu node using subcommands, run: + +```bash +besu [OPTIONS] [SUBCOMMAND] [SUBCOMMAND OPTIONS] +``` + +If using Bash or Z shell, you can view subcommand suggestions by pressing the Tab key twice. + +```bash +besu Tab+Tab +``` + +## `blocks` + +Provides blocks related actions. + +### `import` + + + +# Syntax + +```bash +besu blocks import [--skip-pow-validation-enabled] [--start-block=] [--end-block=] --from= +``` + +# Example + +```bash +besu blocks import --skip-pow-validation-enabled --start-block=100 --end-block=300 --from=/home/me/me_project/mainnet-export1.blocks --from=/home/me/me_project/mainnet-export2.blocks +``` + + + +Imports a block or range of blocks from the specified file into the blockchain database. + +You can specify the starting index of the block range to import with `--start-block`. If omitted, the default start block is 0 (the beginning of the chain). + +You can specify the ending index (exclusive) of the block range to import with `--end-block`. If omitted, all blocks after the start block are imported. + +You can specify multiple `--from` arguments. This can be useful when blocks have been exported over time to multiple files. If multiple files are provided they are read in the order specified in the command. + +Including `--skip-pow-validation-enabled` skips validation of the `mixHash` when importing blocks. + +:::note + +Use `--skip-pow-validation-enabled` when performing [Ethereum Foundation hive testing](https://github.com/ethereum/hive). + +::: + +### `export` + + + +# Syntax + +```bash +besu blocks export [--start-block=] [--end-block=] --to= +``` + +# Example + +```bash +besu --network=goerli --data-path=/home/data/ blocks export --start-block=100 --end-block=300 --to=/home/exportblock.bin +``` + + + +Exports a block or range of blocks from storage to a file in RLP format. + +If you omit `--start-block`, the default start block is 0 (the beginning of the chain), and if you omit `--end-block`, the default end block is the current chain head. + +If you are not running the command against the default network (Mainnet), specify the `--network` or `--genesis-file` parameter. + +## `public-key` + +Provides node public key related actions. + +:::caution + +To get the public key or address of a node, ensure you use the [`--data-path`](options.md#data-path) or [`--node-private-key-file`](options.md#node-private-key-file) option with the `public-key` command. Otherwise, a new [node key](../../concepts/node-keys.md) is silently generated when starting Besu. + +::: + +### `export` + + + +# Syntax + +```bash +besu public-key export [--node-private-key-file=] [--to=] [--ec-curve=] +``` + +# Example (to standard output) + +```bash +besu --data-path= public-key export --node-private-key-file=/home/me/me_node/myPrivateKey --ec-curve=secp256k1 +``` + +# Example (to file) + +```bash +besu --data-path= public-key export --node-private-key-file=/home/me/me_node/myPrivateKey --to=/home/me/me_project/not_precious_pub_key --ec-curve=secp256k1 +``` + + + +Outputs the node public key to standard output or to the file specified by `--to=`. You can output the public key associated with a specific private key file using the [`--node-private-key-file`](options.md#node-private-key-file) option. The default elliptic curve used for the key is `secp256k1`. Use the `--ec-curve` option to choose between `secp256k1` or `secp256r1`. + +### `export-address` + + + +# Syntax + +```bash +besu public-key export-address [--node-private-key-file=] [--to=] [--ec-curve=] +``` + +# Example (to standard output) + +```bash +besu --data-path= public-key export-address --node-private-key-file=/home/me/me_node/myPrivateKey --ec-curve=secp256k1 +``` + +# Example (to file) + +```bash +besu --data-path= public-key export-address --node-private-key-file=/home/me/me_node/myPrivateKey --to=/home/me/me_project/me_node_address --ec-curve=secp256k1 +``` + + + +Outputs the node address to standard output or to the file specified by `--to=`. You can output the address associated with a specific private key file using the [`--node-private-key-file`](options.md#node-private-key-file) option. The default elliptic curve used for the key is `secp256k1`. Use the `--ec-curve` option to choose between `secp256k1` or `secp256r1`. + +## `password` + +Provides password related actions. + +### `hash` + + + +# Syntax + +```bash +besu password hash --password= +``` + +# Example + +```bash +besu password hash --password=myPassword123 +``` + + + +Generates the hash of a given password. Include the hash in the [credentials file](../../how-to/use-besu-api/authenticate.md#credentials-file) for JSON-RPC API [authentication](../../how-to/use-besu-api/authenticate.md). + +## `operator` + +Provides operator actions. + +### `generate-log-bloom-cache` + + + +# Syntax + +```bash +besu operator generate-log-bloom-cache [--start-block=] [--end-block=] +``` + +# Example + +```bash +besu --network=goerli --data-path=/project/goerli operator generate-log-bloom-cache --start-block=0 --end-block=100000 +``` + + + +:::tip + +Manually executing `generate-log-bloom-cache` is not required unless you set the [`--auto-log-bloom-caching-enabled`](options.md#auto-log-bloom-caching-enabled) command line option to false. + +::: + +Generates cached log bloom indexes for blocks. APIs use the cached indexes for improved log query performance. + +:::note + +Each index file contains 100000 blocks. The last fragment of blocks less that 100000 are not indexed. + +::: + +To generate cached log bloom indexes while the node is running, use the [`admin_generateLogBloomCache`](../api/index.md#admin_generatelogbloomcache) API. + +## `retesteth` + + + +# Syntax + +```bash +besu retesteth [--data-path=] [--rpc-http-host=] [--rpc-http-port=] [-l=] [--host-allowlist=[,…]… or * or all] +``` + +# Example + +```bash +besu retesteth --data-path=/home/me/me_node --rpc-http-port=8590 --host-allowlist=* +``` + + + +Runs a Retesteth-compatible server. [Retesteth](https://github.com/ethereum/retesteth/wiki) is a developer tool that can generate and run consensus tests against any Ethereum client running such a server. + +The command accepts the following command line options: + +- [`--data-path`](options.md#data-path) +- [`--host-allowlist`](options.md#host-allowlist) +- [`--rpc-http-host`](options.md#rpc-http-host) +- [`--rpc-http-port`](options.md#rpc-http-port) +- [`--logging`](options.md#logging) + +## `validate-config` + + + +# Syntax + +```bash +besu validate-config --config-file +``` + +# Example + +```bash +besu validate-config --config-file ../besu-local-nodes/config/besu/besu1.conf +``` + + + +Performs basic syntax validation of the specified [TOML configuration file](../../how-to/configuration-file.md). Checks TOML syntax (for example, valid format and unmatched quotes) and flags unknown options. Doesn't check data types, and doesn't check dependencies between options (this is done at Besu startup). diff --git a/versioned_docs/version-23.10.1/public-networks/reference/disclosure.md b/versioned_docs/version-23.10.1/public-networks/reference/disclosure.md new file mode 100644 index 00000000000..3182278df61 --- /dev/null +++ b/versioned_docs/version-23.10.1/public-networks/reference/disclosure.md @@ -0,0 +1,14 @@ +--- +title: Security disclosure policy +sidebar_position: 8 +description: Hyperledger Besu responsible disclosure statement +tags: + - public networks + - private networks +--- + +# Security disclosure policy + +At Hyperledger Besu, security is a priority. But regardless of how much effort we put into system security, there might still be vulnerabilities present. If you discover a vulnerability, we need to know about it so we can take steps to address it as quickly as possible. We would like you to help us better protect our clients and our systems. + +Please follow the process explained on [Hyperledger defect response wiki page](https://wiki.hyperledger.org/display/SEC/Defect+Response). diff --git a/versioned_docs/version-23.10.1/public-networks/reference/engine-api/_category_.json b/versioned_docs/version-23.10.1/public-networks/reference/engine-api/_category_.json new file mode 100644 index 00000000000..0ea3b53ab2e --- /dev/null +++ b/versioned_docs/version-23.10.1/public-networks/reference/engine-api/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Engine API", + "position": 3 +} diff --git a/versioned_docs/version-23.10.1/public-networks/reference/engine-api/index.md b/versioned_docs/version-23.10.1/public-networks/reference/engine-api/index.md new file mode 100644 index 00000000000..2ab80ffb27d --- /dev/null +++ b/versioned_docs/version-23.10.1/public-networks/reference/engine-api/index.md @@ -0,0 +1,487 @@ +--- +title: Engine API +description: Engine API methods reference +tags: + - public networks +--- + +# Engine API methods + +[Consensus and execution clients](../../concepts/the-merge.md#execution-and-consensus-clients) communicate with each other using the Engine API. When running Besu as an execution client, [use these API calls](../../how-to/use-engine-api.md) to communicate with a consensus client. + +:::info + +The engine API is enabled by default. + +::: + +See the [Ethereum Engine API specification](https://github.com/ethereum/execution-apis/blob/0b965fb714ccd3faa3c939fdce1726e56679cdec/src/engine/specification.md) for more information. Not all changes to the Engine API are documented on this page. + +## Methods + +### `engine_exchangeCapabilities` + +Exchanges a list of supported Engine API methods between the consensus client and Besu. + +#### Parameters + +`remoteCapabilities`: _array_ of _strings_ - Engine API method names that the consensus client supports + +#### Returns + +`localCapabilities`: _array_ of _strings_ - Engine API method names that Besu supports + + + +# curl HTTP + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"engine_exchangeCapabilities","params":[["engine_exchangeTransitionConfigurationV1","engine_forkchoiceUpdatedV1","engine_getPayloadBodiesByHash","engine_getPayloadBodiesByRangeV1","engine_getPayloadV1","engine_newPayloadV1"]],"id":67}' http://127.0.0.1:8550 +``` + +# wscat WS + +```json +{ + "jsonrpc": "2.0", + "method": "engine_exchangeCapabilities", + "params": [ + [ + "engine_exchangeTransitionConfigurationV1", + "engine_forkchoiceUpdatedV1", + "engine_getPayloadBodiesByHash", + "engine_getPayloadBodiesByRangeV1", + "engine_getPayloadV1", + "engine_newPayloadV1" + ] + ], + "id": 67 +} +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 67, + "result": [ + "engine_getPayloadV1", + "engine_getPayloadV2", + "engine_executePayloadV1", + "engine_newPayloadV1", + "engine_newPayloadV2", + "engine_forkchoiceUpdatedV1", + "engine_forkchoiceUpdatedV2", + "engine_exchangeTransitionConfigurationV1", + "engine_getPayloadBodiesByHashV1", + "engine_getPayloadBodiesByRangeV1" + ] +} +``` + + + +### `engine_exchangeTransitionConfigurationV1` + +Sends the transition configuration to the consensus client to verify the configuration between both clients. + +:::note + +The execution client runs this call every 60 seconds in the background. The log displays a warning message if the call hasn't been sent in 120 seconds. + +::: + +#### Parameters + +`transitionConfiguration`: _object_ - [Transition configuration object](objects.md#transition-configuration-object) + +#### Returns + +`transitionConfiguration`: _object_ - [Transition configuration object](objects.md#transition-configuration-object) + + + +# curl HTTP + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"engine_exchangeTransitionConfigurationV1","params":[{"terminalTotalDifficulty": 0, "terminalBlockHash": "0x0000000000000000000000000000000000000000000000000000000000000000", "terminalBlockNumber": "0x1"}],"id":67}' http://127.0.0.1:8550 +``` + +# wscat WS + +```json +{ + "jsonrpc": "2.0", + "method": "engine_exchangeTransitionConfigurationV1", + "params": [ + { + "terminalTotalDifficulty": 0, + "terminalBlockHash": "0x0000000000000000000000000000000000000000000000000000000000000000", + "terminalBlockNumber": "0x1" + } + ], + "id": 67 +} +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 67, + "result": { + "terminalTotalDifficulty": 0, + "terminalBlockHash": "0x0000000000000000000000000000000000000000000000000000000000000000", + "terminalBlockNumber": "0x1" + } +} +``` + + + +### `engine_forkchoiceUpdatedV1` + +Updates the fork choice with the consensus client. + +#### Parameters + +- `forkchoiceState`: _object_ - [Fork choice state object](objects.md#fork-choice-state-object) + +- `payloadAttributes`: _object_ - [Payload attribute object](objects.md#payload-attributes-object). Can be `null`. + +#### Returns + +- `payloadStatus`: _object_ - [Payload status object](objects.md#payload-status-object) + +- `payloadId`: _data_ - identifier of the payload build process or `null` + + + +# curl HTTP + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"engine_forkchoiceUpdatedV1","params":[{"headBlockHash": "0x3559e851470f6e7bbed1db474980683e8c315bfce99b2a6ef47c057c04de7858", "safeBlockHash": "0x3559e851470f6e7bbed1db474980683e8c315bfce99b2a6ef47c057c04de7858", "finalizedBlockHash": "0x3b8fb240d288781d4aac94d3fd16809ee413bc99294a085798a589dae51ddd4a"},null],"id":67}' http://127.0.0.1:8550 +``` + +# wscat WS + +```json +{ + "jsonrpc": "2.0", + "method": "engine_forkchoiceUpdatedV1", + "params": [ + { + "headBlockHash": "0x3559e851470f6e7bbed1db474980683e8c315bfce99b2a6ef47c057c04de7858", + "safeBlockHash": "0x3559e851470f6e7bbed1db474980683e8c315bfce99b2a6ef47c057c04de7858", + "finalizedBlockHash": "0x3b8fb240d288781d4aac94d3fd16809ee413bc99294a085798a589dae51ddd4a" + }, + null + ], + "id": 67 +} +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 67, + "result": { + "payloadStatus": { + "status": "VALID", + "latestValidHash": "0x3559e851470f6e7bbed1db474980683e8c315bfce99b2a6ef47c057c04de7858", + "validationError": null + }, + "payloadId": null + } +} +``` + + + +### `engine_getPayloadBodiesByHashV1` + +Returns the bodies of the execution payloads corresponding to the specified block hashes. + +#### Parameters + +`blockHashes`: **array** of **strings** - Block hashes + +#### Returns + +`engineGetPayloadBodiesResultV1`: **array** of **objects** - Execution payload body objects + + + +# curl HTTP + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"engine_getPayloadBodiesByHashV1","params":[["0xd5f1812548be429cbdc6376b29611fc49e06f1359758c4ceaaa3b393e2239f9c","0xfe88c94d860f01a17f961bf4bdfb6e0c6cd10d3fda5cc861e805ca1240c58553"]],"id":1}' http://127.0.0.1:8550 +``` + +# wscat WS + +```json +{ + "jsonrpc": "2.0", + "method": "engine_getPayloadBodiesByHashV1", + "params": [ + [ + "0xd5f1812548be429cbdc6376b29611fc49e06f1359758c4ceaaa3b393e2239f9c", + "0xfe88c94d860f01a17f961bf4bdfb6e0c6cd10d3fda5cc861e805ca1240c58553" + ] + ], + "id": 67 +} +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 67, + "result": [{ + "transactions": ["0xf865808506fc23ac00830124f8940101010101010101010101010101010101010101018031a02c4d88bfdc2f6dbf82c33d235c4e785e9fc23b2d0fc7b9d20fc5e9674f1f9d15a016d6d69b925cf26128683ab4a096e196fbb1142d6c6d4e8d3481b9bef1bd0f65", "0x02f86c0701843b9aca008506fc23ac00830124f89402020202020202020202020202020202020202020180c080a039409b4e5603dd8c3cf38232348661a8e99ac518396eeaa128ec9ec2a3eb8127a06b21ab956f5f138cb44fda1a9055bd08980ea4f8040d877c00dac025608d0d95", ...], + "withdrawals": [{ + "index" : "0xf0", + "validatorIndex" : "0xf0", + "address" : "0x00000000000000000000000000000000000010f0", + "amount" : "0x1" + }, { + "index" : "0xf1", + "validatorIndex" : "0xf1", + "address" : "0x00000000000000000000000000000000000010f1", + "amount" : "0x1" + }] + }, { + "transactions": ["0xf865108506fc23ac00830124f8940101010101010101010101010101010101010101018031a0d9712a3c40ae85aea4ad1bd95a0b7cc7bd805189a9e2517403b11a00a1530f81a053b53b0267a6dcfe9f9a1652307b396b3e8a65e65707a450e60c92baefdbcfbe", "0x02f86c0711843b9aca008506fc23ac00830124f89402020202020202020202020202020202020202020180c080a071d36bc93c7ae8cc5c01501e51e5e97a51aa541d1a89c809a2af7eb40e9bc2cba071644230e21c075c1da08916aff5efe9f95a6f6a4f94dc217f6c1bb4a3240b29", ...], + "withdrawals": [{ + "index" : "0xf2", + "validatorIndex" : "0xf2", + "address" : "0x00000000000000000000000000000000000010f2", + "amount" : "0x1" + }, { + "index" : "0xf3", + "validatorIndex" : "0xf3", + "address" : "0x00000000000000000000000000000000000010f3", + "amount" : "0x1" + }] + }] +} +``` + + + +### `engine_getPayloadBodiesByRangeV1` + +Returns the bodies of the execution payloads corresponding to the specified range of block numbers. + +#### Parameters + +- `startBlockNumber`: _string_ - Number of the starting block of the range, as a hexadecimal string + +- `count`: _string_ - Number of blocks in the range (including the starting block), as a hexadecimal string + +#### Returns + +`engineGetPayloadBodiesResultV1`: _array_ of _objects_ - Execution payload body objects + + + +# curl HTTP + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"engine_getPayloadBodiesByRangeV1","params":["0x20", "0x2"],"id":1}' http://127.0.0.1:8550 +``` + +# wscat WS + +```json +{ + "jsonrpc": "2.0", + "method": "engine_getPayloadBodiesByRangeV1", + "params": ["0x20", "0x2"], + "id": 67 +} +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 67, + "result": [{ + "transactions": ["0xf865808506fc23ac00830124f8940101010101010101010101010101010101010101018031a02c4d88bfdc2f6dbf82c33d235c4e785e9fc23b2d0fc7b9d20fc5e9674f1f9d15a016d6d69b925cf26128683ab4a096e196fbb1142d6c6d4e8d3481b9bef1bd0f65", "0x02f86c0701843b9aca008506fc23ac00830124f89402020202020202020202020202020202020202020180c080a039409b4e5603dd8c3cf38232348661a8e99ac518396eeaa128ec9ec2a3eb8127a06b21ab956f5f138cb44fda1a9055bd08980ea4f8040d877c00dac025608d0d95", ...], + "withdrawals": [{ + "index" : "0xf0", + "validatorIndex" : "0xf0", + "address" : "0x00000000000000000000000000000000000010f0", + "amount" : "0x1" + }, { + "index" : "0xf1", + "validatorIndex" : "0xf1", + "address" : "0x00000000000000000000000000000000000010f1", + "amount" : "0x1" + }] + }, { + "transactions": ["0xf865108506fc23ac00830124f8940101010101010101010101010101010101010101018031a0d9712a3c40ae85aea4ad1bd95a0b7cc7bd805189a9e2517403b11a00a1530f81a053b53b0267a6dcfe9f9a1652307b396b3e8a65e65707a450e60c92baefdbcfbe", "0x02f86c0711843b9aca008506fc23ac00830124f89402020202020202020202020202020202020202020180c080a071d36bc93c7ae8cc5c01501e51e5e97a51aa541d1a89c809a2af7eb40e9bc2cba071644230e21c075c1da08916aff5efe9f95a6f6a4f94dc217f6c1bb4a3240b29", ...], + "withdrawals": [{ + "index" : "0xf2", + "validatorIndex" : "0xf2", + "address" : "0x00000000000000000000000000000000000010f2", + "amount" : "0x1" + }, { + "index" : "0xf3", + "validatorIndex" : "0xf3", + "address" : "0x00000000000000000000000000000000000010f3", + "amount" : "0x1" + }] + }] +} +``` + + + +### `engine_getPayloadV1` + +Prepares the payload to send to the consensus client. + +#### Parameters + +`payloadId`: _data_ - Identifier of the payload build process + +#### Returns + +`executionPayload`: _object_ - [Execution payload object](objects.md#execution-payload-object) + + + +# curl HTTP + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"engine_getPayloadV1","params":["0x0000000021f32cc1"],"id":1}' http://127.0.0.1:8550 +``` + +# wscat WS + +```json +{ + "jsonrpc": "2.0", + "method": "engine_getPayloadV1", + "params": ["0x0000000021f32cc1"], + "id": 67 +} +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 67, + "result": { + "parentHash": "0x3b8fb240d288781d4aac94d3fd16809ee413bc99294a085798a589dae51ddd4a", + "feeRecipient": "0xa94f5374fce5edbc8e2a8697c15331677e6ebf0b", + "stateRoot": "0xca3149fa9e37db08d1cd49c9061db1002ef1cd58db2210f2115c8c989b2bdf45", + "receiptsRoot": "0x56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421", + "logsBloom": "0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000", + "prevRandao": "0x0000000000000000000000000000000000000000000000000000000000000000", + "blockNumber": "0x1", + "gasLimit": "0x1c9c380", + "gasUsed": "0x0", + "timestamp": "0x5", + "extraData": "0x", + "baseFeePerGas": "0x7", + "blockHash": "0x3559e851470f6e7bbed1db474980683e8c315bfce99b2a6ef47c057c04de7858", + "transactions": [] + } +} +``` + + + +### `engine_newPayloadV1` + +Executes the payload with the consensus client. + +#### Parameters + +`executionPayload`: _object_ - [Execution payload object](objects.md#execution-payload-object) + +#### Returns + +- `payloadStatus`: _object_ - [Payload status object](objects.md#payload-status-object) + + + +# curl HTTP + +```bash +curl -X POST --data '{"jsonrpc":"2.0","method":"engine_newPayloadV1","params":[ + { + "parentHash": "0x3b8fb240d288781d4aac94d3fd16809ee413bc99294a085798a589dae51ddd4a", + "feeRecipient": "0xa94f5374fce5edbc8e2a8697c15331677e6ebf0b", + "stateRoot": "0xca3149fa9e37db08d1cd49c9061db1002ef1cd58db2210f2115c8c989b2bdf45", + "receiptsRoot": "0x56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421", + "logsBloom": "0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000", + "prevRandao": "0x0000000000000000000000000000000000000000000000000000000000000000", + "blockNumber": "0x1", + "gasLimit": "0x1c9c380", + "gasUsed": "0x0", + "timestamp": "0x5", + "extraData": "0x", + "baseFeePerGas": "0x7", + "blockHash": "0x3559e851470f6e7bbed1db474980683e8c315bfce99b2a6ef47c057c04de7858", + "transactions": [] + } +],"id":67}' http://127.0.0.1:8550 +``` + +# wscat WS + +```json +{ + "jsonrpc": "2.0", + "method": "engine_newPayloadV1", + "params": [ + { + "parentHash": "0x3b8fb240d288781d4aac94d3fd16809ee413bc99294a085798a589dae51ddd4a", + "feeRecipient": "0xa94f5374fce5edbc8e2a8697c15331677e6ebf0b", + "stateRoot": "0xca3149fa9e37db08d1cd49c9061db1002ef1cd58db2210f2115c8c989b2bdf45", + "receiptsRoot": "0x56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421", + "logsBloom": "0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000", + "prevRandao": "0x0000000000000000000000000000000000000000000000000000000000000000", + "blockNumber": "0x1", + "gasLimit": "0x1c9c380", + "gasUsed": "0x0", + "timestamp": "0x5", + "extraData": "0x", + "baseFeePerGas": "0x7", + "blockHash": "0x3559e851470f6e7bbed1db474980683e8c315bfce99b2a6ef47c057c04de7858", + "transactions": [] + } + ], + "id": 67 +} +``` + +# JSON result + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + "status": "VALID", + "latestValidHash": "0x3559e851470f6e7bbed1db474980683e8c315bfce99b2a6ef47c057c04de7858", + "validationError": null + } +} +``` + + diff --git a/versioned_docs/version-23.10.1/public-networks/reference/engine-api/objects.md b/versioned_docs/version-23.10.1/public-networks/reference/engine-api/objects.md new file mode 100644 index 00000000000..ecd40054d9f --- /dev/null +++ b/versioned_docs/version-23.10.1/public-networks/reference/engine-api/objects.md @@ -0,0 +1,71 @@ +--- +title: Objects +description: Engine API objects reference +tags: + - public networks +--- + +# Engine API objects + +The following objects are parameters for or returned by the [Engine API methods](index.md). + +## Execution payload object + +Parameter for [`engine_newPayloadV1`](index.md#engine_newpayloadv1). Returned by [`engine_getPayloadV1`](index.md#engine_getpayloadv1). + +| Key | Type | Value | +| --- | :-: | --- | +| `parentHash` | _Data_, 32 Bytes | Hash of the parent block. | +| `feeRecipient` | _Data_, 20 Bytes | Beneficiary of the fee. | +| `stateRoot` | _Data_, 32 Bytes | Root of the final state trie for the block. | +| `receiptsRoot` | _Data_, 32 Bytes | Root of the receipts trie for the block. | +| `logsBloom` | _Data_, 256 Bytes | Bloom filter for light clients to quickly retrieve related logs. | +| `prevRandao` | _Data_, 32 Bytes | Difficulty for this block. | +| `blockNumber` | _Quantity_, 64 Bits | Block number of block containing this transaction. | +| `gasLimit` | _Quantity_, 64 Bits | Maximum gas allowed in this block. | +| `gasUsed` | _Quantity_, 64 Bits | Total gas used by all transactions in this block. | +| `timestamp` | _Quantity_, 64 Bits | Unix timestamp (milliseconds) for block assembly. | +| `extraData` | _Data_, 0 to 32 Bytes | Extra data field for this block. | +| `baseFeePerGas` | _Quantity_, 256 Bits | The block's [base fee per gas](../../concepts/transactions/types.md#eip1559-transactions). This field is empty for blocks created before [EIP-1559](https://github.com/ethereum/EIPs/blob/2d8a95e14e56de27c5465d93747b0006bd8ac47f/EIPS/eip-1559.md). | +| `blockHash` | _Data_, 32 Bytes | Hash of the execution block. | +| `transactions` | _Array_ | Array of transaction objects, each object is a list representing `TransactionType`, `TransactionPayload`, or `LegacyTransaction` as defined in [EIP-2718](https://eips.ethereum.org/EIPS/eip-2718). | + +## Fork choice state object + +Parameter for [`engine_forkchoiceUpdatedV1`](index.md#engine_forkchoiceupdatedv1). + +| Key | Type | Value | +| --- | :-: | --- | +| `headBlockHash` | _Data_, 32 Bytes | Block hash of the head of the canonical chain. | +| `safeBlockHash` | _Data_, 32 Bytes | "Safe" block hash of the canonical chain under certain synchrony and honesty assumptions. This value MUST be either equal to or an ancestor of `headBlockHash`. | +| `finalizedBlockHash` | _Data_, 32 Bytes | Block hash of the most recent finalized block. | + +## Payload attributes object + +Parameter for [`engine_forkchoiceUpdatedV1`](index.md#engine_forkchoiceupdatedv1). + +| Key | Type | Value | +| --- | :-: | --- | +| `timestamp` | _Quantity_, 64 Bits | Value for the `timestamp` field of the new payload. | +| `prevRandao` | _Data_, 32 Bytes | Value for the `prevRandao` field of the new payload. | +| `suggestedFeeRecipient` | _Data_, 20 Bytes | Suggested value for the `feeRecipient` field of the new payload. | + +## Payload status object + +Returned by [`engine_newPayloadV1`](index.md#engine_newpayloadv1) and [`engine_forkchoiceUpdatedV1`](index.md#engine_forkchoiceupdatedv1). + +| Key | Type | Value | +| --- | :-: | --- | +| `status` | _Enumeration_ | Either `"VALID"`, `"INVALID"`, `"SYNCING"`, `"ACCEPTED"`, `"INVALID_BLOCK_HASH"`, or `"INVALID_TERMINAL_BLOCK"`. | +| `latestValidHash` | _Data_, 32 Bytes | Hash of the most recent valid block in the branch defined by payload and its ancestors. | +| `validationError` | _String_ | Message providing additional details on the validation error if the payload is classified as `INVALID`, `INVALID_BLOCK_HASH` or `INVALID_TERMINAL_BLOCK`. | + +## Transition configuration object + +Parameter for and returned by [`engine_exchangeTransitionConfigurationV1`](index.md#engine_exchangetransitionconfigurationv1). + +| Key | Type | Value | +| --- | :-: | --- | +| `terminalTotalDifficulty` | _Quantity_, 256 Bits | Maps on the `TERMINAL_TOTAL_DIFFICULTY` parameter of [EIP-3675](https://eips.ethereum.org/EIPS/eip-3675#client-software-configuration). | +| `terminalBlockHash` | _Data_, 32 Bytes | Maps on the `TERMINAL_BLOCK_HASH` parameter of [EIP-3675](https://eips.ethereum.org/EIPS/eip-3675#client-software-configuration). | +| `terminalBlockNumber` | _Quantity_, 64 Bits | Maps on the `TERMINAL_BLOCK_NUMBER` parameter of [EIP-3675](https://eips.ethereum.org/EIPS/eip-3675#client-software-configuration). | diff --git a/versioned_docs/version-23.10.1/public-networks/reference/evm-tool.md b/versioned_docs/version-23.10.1/public-networks/reference/evm-tool.md new file mode 100644 index 00000000000..37c8b88ea02 --- /dev/null +++ b/versioned_docs/version-23.10.1/public-networks/reference/evm-tool.md @@ -0,0 +1,562 @@ +--- +title: EVM tool options +sidebar_position: 5 +description: Besu EVM tool options reference +tags: + - public networks + - private networks +--- + +# EVM tool reference + +This reference describes options for running the following [using the EVM tool](../how-to/troubleshoot/evm-tool.md): + +- [Arbitrary EVM programs](#run-options) +- [Ethereum state tests](#state-test-options) +- [Ethereum object formatted code](#eof-code-validation) + +:::note + +Option names that include `trace`, such as [`--trace`](#json-trace) and [`--trace.[no]memory`](#nomemory-tracenomemory) exist to support [`t8ntool`](https://ethereum-tests.readthedocs.io/en/latest/t8ntool.html) reference testing, and are interchangeable with their standard option names. + +::: + +## Run options + +The first mode of the EVM tool runs an arbitrary EVM and is invoked without an extra command. Command line options specify the code and other contextual information. + +### `code` + + + +# Syntax + +```bash +--code= +``` + +# Example + +```bash +--code=5B600080808060045AFA50600056 +``` + + + +The code to be executed, in compiled hex code form. Execution fails if this is not set. + +### `gas` + + + +# Syntax + +```bash +--gas= +``` + +# Example + +```bash +--gas=100000000 +``` + + + +Amount of gas to make available to the EVM. The default is 10 billion, a number unlikely to be seen in any production blockchain. + +### `price` + + + +# Syntax + +```bash +--price= +``` + +# Example + +```bash +--price=10 +``` + + + +Price of gas in Gwei. The default is `0`. If set to a non-zero value, the sender account must have enough value to cover the gas fees. + +### `sender` + + + +# Syntax + +```bash +--sender=
+``` + +# Example + +```bash +--sender=0xfe3b557e8fb62b89f4916b721be55ceb828dbd73 +``` + + + +The account the invocation is sent from. The specified account must exist in the world state, which, unless specified by [`--genesis`](#genesis), is the set of [accounts used for testing](../../private-networks/reference/accounts-for-testing.md). + +### `receiver` + + + +# Syntax + +```bash +--receiver=
+``` + +# Example + +```bash +--receiver=0x588108d3eab34e94484d7cda5a1d31804ca96fe7 +``` + + + +The account the invocation is sent to. The specified account does not need to exist. + +### `input` + + + +# Syntax + +```bash +--input= +``` + +# Example + +```bash +--input=9064129300000000000000000000000000000000000000000000000000000000 +``` + + + +The data passed into the call. Corresponds to the `data` field of the transaction and is returned by the `CALLDATA` and related opcodes. + +### `value` + + + +# Syntax + +```bash +--value= +``` + +# Example + +```bash +--value=1000000000000000000 +``` + + + +The value, in wei, attached to this transaction. For operations that query the value or transfer it to other accounts this is the amount that is available. The amount is not reduced to cover intrinsic cost and gas fees. + +### `json`, `trace` + + + +# Syntax + +```bash +--json +``` + + + +Provides an operation-by-operation trace of the command in JSON. + +`--trace` is an alias for `--json`. + +### `json-alloc` + + + +# Syntax + +```bash +--json-alloc +``` + + + +Outputs a JSON summary of the post-execution world state and allocations. + +### `[no]memory`, `trace.[no]memory` + + + +# Syntax + +```bash +--nomemory, --memory +``` + + + +Setting `--nomemory` disables tracing the memory output for each operation. Setting `--memory` enables it. Memory traces are disabled by default. + +For memory heavy scripts, disabling memory traces may reduce the volume of JSON output. + +`--trace.[no]memory` is an alias for `--[no]memory`. + +### `trace.[no]stack` + + + +# Syntax + +```bash +--trace.nostack, --trace.stack +``` + + + +Setting `--trace.nostack` disables tracing the operand stack for each operation. Setting `--trace.stack` enables it. Stack traces are enabled by default. + +### `trace.[no]returndata` + + + +# Syntax + +```bash +--trace.noreturndata, --trace.returndata +``` + + + +Setting `--trace.noreturndata` disables tracing the return data for each operation. Setting `--trace.returndata` enables it. Return data traces are enabled by default. + +### `[no]time` + + + +# Syntax + +```bash +--notime, --time +``` + + + +Setting `--notime` disables including time data in the summary output. Setting `--time` enables it. + +This is useful for testing and differential evaluations. + +### `genesis` + + + +# Syntax + +```bash +--genesis= +``` + +# Example + +```bash +--genesis=/opt/besu/genesis.json +``` + + + +The [Besu genesis file](genesis-items.md) to use when evaluating the EVM. Most useful are the `alloc` items that set up accounts and their stored memory states. + +`--prestate` is a deprecated alias for `--genesis`. + +### `chain` + + + +# Syntax + +```bash +--chain= +``` + +# Example + +```bash +--chain=goerli +``` + + + +The well-known network genesis file to use when evaluating the EVM. These values are an alternative to the [`--genesis`](#genesis) option for well-known networks. + +### `repeat` + + + +# Syntax + +```bash +--repeat= +``` + +# Example + +```bash +--repeat=1000 +``` + + + +Number of times to repeat the contract before gathering timing information. This is useful when benchmarking EVM operations. The default is `0`. + +### `revert-reason-enabled` + + + +# Syntax + +```bash +--revert-reason-enabled +``` + + + +Enables tracing the reason included in `REVERT` operations. The revert reason is enabled by default. + +### `fork` + + + +# Syntax + +```bash +--fork= +``` + +# Example + +```bash +--fork=FutureEips +``` + + + +Specific fork to evaluate, overriding network settings. + +### `key-value-storage` + + + +# Syntax + +```bash +--key-value-storage= +``` + +# Example + +```bash +--key-value-storage=rocksdb +``` + + + +Kind of key value storage to use. + +It might be useful to execute isolated EVM calls in the context of an actual world state. The default is `memory`, which executes the call only in the context of the world provided by [`--genesis`](#genesis) or [`--chain`](#chain) at block zero. + +When set to `rocksdb` and combined with [`--data-path`](#data-path), [`--block-number`](#block-number), and [`--genesis`](#genesis), a Besu node that isn't currently running can be used to provide the appropriate world state for a transaction. This is useful when evaluating consensus failures. + +### `data-path` + + + +# Syntax + +```bash +--data-path= +``` + +# Example + +```bash +--data-path=/opt/besu/data +``` + + + +When [`--key-value-storage`](#key-value-storage) is set to `rocksdb`, specifies the location of the database on disk. + +### `block-number` + + + +# Syntax + +```bash +--block-number= +``` + +# Example + +```bash +--block-number=10000000 +``` + + + +The block number to evaluate the code against. Used to ensure that the EVM is evaluating the code against the correct fork, or to specify the world state when [`--key-value-storage`](#key-value-storage) is set to `rocksdb`. + +### `version` + + + +# Syntax + +```bash +--version +``` + + + +Displays the version information. + +`-v` is an alias for `--version`. + +## State test options + +The `state-test` subcommand allows the [Ethereum state tests](https://github.com/ethereum/tests/tree/develop/GeneralStateTests) to be evaluated. The only applicable options are `--json` and `--nomemory`. + +### `json`, `trace` + + + +# Syntax + +```bash +--json +``` + + + +Provides an operation-by-operation trace of the command in JSON. + +Set this option for EVM Lab Fuzzing. Whether or not `--json` is set, a summary JSON object is printed to standard output for each state test executed. + +`--trace` is an alias for `--json`. + +### `[no]memory`, `trace.[no]memory` + + + +# Syntax + +```bash +--[no]memory +``` + + + +Setting `--nomemory` disables tracing the memory output for each operation. Setting `--memory` enables it. Memory traces are disabled by default. + +For memory heavy scripts, disabling memory traces may reduce the volume of JSON output. + +`--trace.[no]memory` is an alias for `--[no]memory`. + +### Use command arguments + +If you use command arguments, you can list one or more state tests. All the state tests are evaluated in the order they are specified. + + + +# Docker example + +```bash +docker run --rm -v ${PWD}:/opt/referencetests hyperledger/besu-evmtool:develop --json state-test /opt/referencetests/GeneralStateTests/stExample/add11.json +``` + +# CLI example + +```bash +evm --json state-test stExample/add11.json +``` + + + +### Use standard input + +If no reference tests are passed in using the command line, the EVM tool loads one complete JSON object from standard input and executes that state test. + + + +# Docker example + +```bash +docker run --rm -i hyperledger/besu-evmtool:develop --json state-test < stExample/add11.json +``` + +# CLI example + +```bash +evm --json state-test < stExample/add11.json +``` + + + +## EOF code validation + +The `code-validate` subcommand allows [Ethereum object formatted (EOF)](https://eips.ethereum.org/EIPS/eip-3540) code to be validated. It accepts candidate EOF containers or EVM bytecode using the `--file` option, command arguments, or standard input. + +### `file` + + + +# Syntax + +```bash +--file= +``` + +# Example + +```bash +--file=eof.txt +``` + + + +File containing one or more EOF containers or EVM bytecode. Each line in the file is considered a separate program. + +### Use command arguments + +If you use command arguments, each argument is considered a separate program. If a code segment includes spaces, it must be contained in quotes. + + + +# Docker example + +```bash +docker run --rm hyperledger/besu-evmtool:develop code-validate "0xef0001 010008 020002-0007-0002 030000 00 00000002-02010002 59-59-b00001-50-b1 03-b1" 0xef0002 0xef00010100040200010001030000000000000000 +``` + +# CLI example + +```bash +evm code-validate "0xef0001 010008 020002-0007-0002 030000 00 00000002-02010002 59-59-b00001-50-b1 03-b1" 0xef0002 0xef00010100040200010001030000000000000000 +``` + + + +### Use standard input + +If no reference tests are passed in using the command line, the EVM tool loads and validates code from standard input. Each line is considered a separate program. Comment lines and blanks are ignored. diff --git a/versioned_docs/version-23.10.1/public-networks/reference/genesis-items.md b/versioned_docs/version-23.10.1/public-networks/reference/genesis-items.md new file mode 100644 index 00000000000..dbf4089990c --- /dev/null +++ b/versioned_docs/version-23.10.1/public-networks/reference/genesis-items.md @@ -0,0 +1,151 @@ +--- +title: Genesis file items +sidebar_position: 4 +description: Genesis file configuration items reference +tags: + - public networks + - private networks +--- + +# Genesis file items + +The [Besu genesis file](../concepts/genesis-file.md) contains [network configuration items](#configuration-items) and [genesis block parameters](#genesis-block-parameters). + +## Configuration items + +Network configuration items are specified in the genesis file in the `config` object. + +| Item | Description | +| --- | --: | +| Milestone blocks | [Milestone blocks for the network](#milestone-blocks). | +| `chainID` | [Chain ID for the network](../concepts/network-and-chain-id.md). | +| `ethash` | Specifies network uses [Ethash](../../private-networks/how-to/configure/consensus/index.md) and contains [`fixeddifficulty`](#fixed-difficulty). | +| `clique` | Specifies network uses [Clique](../../private-networks/how-to/configure/consensus/clique.md) and contains [Clique configuration items](../../private-networks/how-to/configure/consensus/clique.md#genesis-file). | +| `ibft2` | Specifies network uses [IBFT 2.0](../../private-networks/how-to/configure/consensus/ibft.md) and contains [IBFT 2.0 configuration items](../../private-networks/how-to/configure/consensus/ibft.md#genesis-file). | +| `qbft` | Specifies network uses [QBFT](../../private-networks/how-to/configure/consensus/qbft.md) and contains [QBFT configuration items](../../private-networks/how-to/configure/consensus/qbft.md#genesis-file). | +| `transitions` | Specifies block at which to [change IBFT 2.0 or QBFT validators](../../private-networks/how-to/configure/consensus/add-validators-without-voting.md). | +| `contractSizeLimit` | Maximum contract size in bytes. Specify in [free gas networks](../../private-networks/how-to/configure/free-gas.md). The default is `24576` and the maximum size is `2147483647`. | +| `evmStackSize` | Maximum stack size. Specify to increase the maximum stack size in private networks with complex smart contracts. The default is `1024`. | +| `ecCurve` | Specifies [the elliptic curve to use](../../private-networks/how-to/configure/curves.md). Default is `secp256k1`. | +| `discovery` | Specifies [discovery configuration items](#discovery-configuration-items). The `discovery` object can be left empty. | + +## Genesis block parameters + +The purpose of some genesis block parameters varies depending on the consensus protocol (Ethash, [Clique](../../private-networks/how-to/configure/consensus/clique.md), [IBFT 2.0](../../private-networks/how-to/configure/consensus/ibft.md), or [QBFT](../../private-networks/how-to/configure/consensus/qbft.md)). These parameters include: + +- `difficulty`. +- `extraData`. +- `mixHash`. + +The following table describes the genesis block parameters with the same purpose across all consensus protocols. + +| Item | Description | +| --- | --: | +| `coinbase` | Address to pay mining rewards to. Can be any value in the genesis block (commonly set to `0x0000000000000000000000000000000000000000`). | +| `gasLimit` | Block gas limit. Total gas limit for all transactions in a block. | +| `nonce` | Used in block computation. Can be any value in the genesis block (commonly set to `0x0`). | +| `timestamp` | Creation date and time of the block. Must be before the next block so we recommend specifying `0x0` in the genesis file. | +| `alloc` | Defines [accounts with balances](../../private-networks/reference/accounts-for-testing.md) or [contracts](../../private-networks/how-to/configure/contracts.md). | + +:::caution + +If a `Supplied genesis block does not match stored chain data` error occurs, use the genesis file matching the genesis block of the data directory, or use the [`--data-path`](../reference/cli/options.md#data-path) option to specify a different data directory. + +::: + +## Milestone blocks + +In public networks, the milestone blocks specify the blocks at which the network changed protocol. See a [full list of Ethereum protocol releases](https://github.com/ethereum/execution-specs#ethereum-protocol-releases) and their corresponding milestone blocks. + +```json title="Ethereum Mainnet milestone blocks" +{ + "config": { + ... + "homesteadBlock": 1150000, + "daoForkBlock": 1920000, + "daoForkSupport": true, + "eip150Block": 2463000, + "eip150Hash": "0x2086799aeebeae135c246c65021c82b4e15a2c451340993aacfd2751886514f0", + "eip155Block": 2675000, + "eip158Block": 2675000, + "byzantiumBlock": 4370000, + "constantinopleBlock": 7280000, + "constantinopleFixBlock": 7280000, + "muirGlacierBlock": 9200000, + "berlinBlock": 12244000, + "londonBlock": 12965000, + "arrowGlacierBlock": 13773000, + "grayGlacierBlock": 15050000, + ... + }, +} +``` + +:::caution + +Ensure you include a milestone far enough in advance in the genesis file. Not doing so can lead to unexpected and inconsistent behavior without specific errors. + +::: + +In private networks, the milestone block defines the protocol version for the network. + +```json title="Private network milestone block" +{ + "config": { + ... + "berlinBlock": 0, + ... + }, +} +``` + +:::note + +In private networks, we recommend specifying the latest milestone block. It's implied this includes the preceding milestones. This ensures you use the most up-to-date protocol and have access to the most recent opcodes. + +::: + +## Fixed difficulty + +Use `fixeddifficulty` to specify a fixed difficulty in private networks using Ethash. This will keep the network's difficulty constant and override the `difficulty` parameter from the genesis file. + +```json +{ + "config": { + ... + "ethash": { + "fixeddifficulty": 1000 + }, + + }, + ... +} +``` + +:::tip + +Using `fixeddifficulty` is not recommended for use with Ethash outside of test environments. For production networks using Ethash, we recommend setting a low `difficulty` value in the genesis file instead. Ethash will adjust the difficulty of the network based on hashrate to produce blocks at the targeted frequency. + +::: + +## Discovery configuration items + +Use the `discovery` configuration items to specify the [`bootnodes`](cli/options.md#bootnodes) and [`discovery-dns-url`](cli/options.md#discovery-dns-url) in the genesis file, in place of using CLI options or listing them in the configuration file. If either CLI option is used, it takes precedence over the genesis file. Anything listed in the configuration file also takes precedence. + +```json +{ + "config": { + "discovery": { + "bootnodes": [ + "enode://c35c3...d615f@1.2.3.4:30303", + "enode://f42c13...fc456@1.2.3.5:30303" + ], + "dns": "enrtree://AM5FCQLWIZX2QFPNJAP7VUERCCRNGRHWZG3YYHIUV7BVDQ5FDPRT2@nodes.example.org" + } + } +} +``` + + + +[GoQuorum clients]: https://consensys.net/docs/goquorum/en/stable/ diff --git a/versioned_docs/version-23.10.1/public-networks/reference/projects-using-besu.md b/versioned_docs/version-23.10.1/public-networks/reference/projects-using-besu.md new file mode 100644 index 00000000000..801ed4448db --- /dev/null +++ b/versioned_docs/version-23.10.1/public-networks/reference/projects-using-besu.md @@ -0,0 +1,18 @@ +--- +title: Projects using Besu +sidebar_position: 7 +description: List of projects using Besu +tags: + - public networks + - private networks +--- + +# Projects using Besu + +## Block explorers + +The following block explorers are compatible with Besu: + +- [BlockScout](https://github.com/blockscout/blockscout#readme) - See the [project documentation](https://docs.blockscout.com/) for setup instructions. + +- [Chainlens Blockchain Explorer](https://www.web3labs.com/chainlens) - See how to [use Chainlens with privacy-enabled networks](../../private-networks/how-to/monitor/chainlens.md). diff --git a/versioned_docs/version-23.10.1/public-networks/reference/trace-types.md b/versioned_docs/version-23.10.1/public-networks/reference/trace-types.md new file mode 100644 index 00000000000..2ea2b785ce9 --- /dev/null +++ b/versioned_docs/version-23.10.1/public-networks/reference/trace-types.md @@ -0,0 +1,160 @@ +--- +title: Transaction trace types +sidebar_position: 6 +description: Transaction trace types reference +tags: + - public networks + - private networks +--- + +# Transaction trace types + +When [tracing transactions](../how-to/troubleshoot/trace-transactions.md), the trace type options are [`trace`](#trace), [`vmTrace`](#vmtrace), and [`stateDiff`](#statediff). + +## `trace` + +An ordered list of calls to other contracts, excluding precompiled contracts. + +```json title="trace example" +"trace":[ + { + "action":{ + "callType":"call", + "from":"0xfe3b557e8fb62b89f4916b721be55ceb828dbd73", + "gas":"0xffadea", + "input":"0x", + "to":"0x0100000000000000000000000000000000000000", + "value":"0x0" + }, + "result":{ + "gasUsed":"0x1e", + "output":"0x" + }, + "subtraces":0, + "traceAddress":[ + ], + "type":"call" + } +] +``` + +| Key | Value | +| --- | --- | +| `action` | Transaction details. | +| `callType` | Whether the transaction is `call` or `create`. | +| `from` | Address of the transaction sender. | +| `gas` | Gas provided by sender. | +| `input` | Transaction data. | +| `to` | Target of the transaction. | +| `value` | Value transferred in the transaction. | +| `result` | Transaction result. | +| `gasUsed` | Gas used by the transaction. Includes any refunds of unused gas. | +| `output` | Return value of the contract call. Contains only the actual value sent by a `RETURN` operation. If a `RETURN` was not executed, the output is empty bytes. | +| `subTraces` | Traces of contract calls made by the transaction. | +| `traceAddress` | Tree list address of where the call occurred, address of the parents, and order of the current sub call. | +| `type` | Whether the transaction is a `CALL` or `CREATE` series operation. | + +## `vmTrace` + +An ordered list of EVM actions when processing the transaction. + +`vmTrace` only reports actual data returned from a `RETURN` opcode and does not return the contents of the reserved output space for the call operations. As a result: + +- `vmTrace` reports `null` when a call operation ends because of a `STOP`, `HALT`, `REVERT`, running out of instructions, or any exceptional halts. +- When a `RETURN` operation returns data of a different length to the space reserved by the call, `vmTrace` reports only the data passed to the `RETURN` operation and does not include pre-existing memory data or trim the returned data. + +For out of gas operations, `vmTrace` reports the operation that caused the out of gas exception, including the calculated gas cost. `vmTrace` does not report `ex` values because the operation is not executed. + +```json title="vmTrace example" +"vmTrace":{ + "code":"0x7f3940be4289e4c3587d88c1856cc95352461992db0a584c281226faefe560b3016000527f14c4d2c102bdeb2354bfc3dc96a95e4512cf3a8461e0560e2272dbf884ef3905601052600851", + "ops":[ + { + "cost":3, + "ex":{ + "mem":null, + "push":[ + "0x8" + ], + "store":null, + "used":16756175 + }, + "pc":72, + "sub":null + }, + ... + ] +} +``` + +| Key | Value | +| --- | --- | +| `code` | Code executed by the EVM. | +| `ops` | Sequence of EVM operations (opcodes) executed in the transaction. | +| `cost` | Gas cost of the opcode. Includes memory expansion costs but not gas refunds. For precompiled contract calls, reports only the actual cost. | +| `ex` | Executed operations. | +| `mem` | Memory read or written by the operation. | +| `push` | Adjusted stack items. For swap, includes all intermediate values and the result. Otherwise, is the value pushed onto the stack. | +| `store` | Account storage written by the operation. | +| `used` | Remaining gas taking into account the all but 1/64th rule for calls. | +| `pc` | Program counter. | +| `sub` | Sub call operations. | + +## `stateDiff` + +State changes in the requested block for each transaction represented as a map of accounts to an object. Besu lists the balance, code, nonce, and storage changes from immediately before the transaction to after the transaction. For the `key:value` pairs: + +- `+` indicates the field didn’t exist before and now has the specified value +- `-` indicates a deleted value +- `*` has a `from` and a `to` value. + +An absent value is distinct from zero when creating accounts or clearing storage. + +```json title="stateDiff example" +"stateDiff":{ + "0xfe3b557e8fb62b89f4916b721be55ceb828dbd73":{ + "balance":{ + "*":{ + "from":"0xffffffffffffffffffffffffffffffffc3e12a20b", + "to":"0xffffffffffffffffffffffffffffffffc3dc5f091" + } + }, + "code":"=", + "nonce":{ + "*":{ + "from":"0x14", + "to":"0x15" + } + }, + "storage":{ + } + } +} +``` + +| Key | Value | +| -------------- | ----------------------------------------- | +| `balance` | Change of balance event. | +| `balance.from` | Balance before the transaction. | +| `balance.to` | Balance after the transaction. | +| `code` | Changes to code. None in this example. | +| `nonce` | Change of nonce. | +| `nonce.from` | Nonce before the transaction. | +| `nonce.to` | Nonce after the transaction. | +| `storage` | Changes to storage. None in this example. | + +## Applicable API methods + +The trace options `trace`, `vmTrace`, and `stateDiff` are available for the following [ad-hoc tracing API methods](../how-to/troubleshoot/trace-transactions.md#ad-hoc-tracing-apis): + +- [`trace_call`](api/index.md#trace_call) +- [`trace_callMany`](api/index.md#trace_callmany) +- [`trace_rawTransaction`](api/index.md#trace_rawtransaction) +- [`trace_replayBlockTransactions`](api/index.md#trace_replayblocktransactions) + +Only the `trace` option is available for the following [transaction-trace filtering API methods](../how-to/troubleshoot/trace-transactions.md#transaction-trace-filtering-apis): + +- [`trace_block`](api/index.md#trace_block) +- [`trace_filter`](api/index.md#trace_filter) +- [`trace_get`](api/index.md#trace_get) +- [`trace_transaction`](api/index.md#trace_transaction) diff --git a/versioned_docs/version-23.10.1/public-networks/tutorials/_category_.json b/versioned_docs/version-23.10.1/public-networks/tutorials/_category_.json new file mode 100644 index 00000000000..f72790313cd --- /dev/null +++ b/versioned_docs/version-23.10.1/public-networks/tutorials/_category_.json @@ -0,0 +1,8 @@ +{ + "label": "Tutorials", + "position": 5, + "link": { + "type": "generated-index", + "slug": "public-networks/tutorials" + } +} diff --git a/versioned_docs/version-23.10.1/public-networks/tutorials/besu-teku-mainnet.md b/versioned_docs/version-23.10.1/public-networks/tutorials/besu-teku-mainnet.md new file mode 100644 index 00000000000..56fa7eaaa14 --- /dev/null +++ b/versioned_docs/version-23.10.1/public-networks/tutorials/besu-teku-mainnet.md @@ -0,0 +1,182 @@ +--- +title: Run Besu and Teku on Mainnet +sidebar_position: 1 +description: Run Besu and Teku on Ethereum Mainnet. +tags: + - public networks +--- + +# Run Besu and Teku on Mainnet + +Run Besu as an [execution client](../concepts/the-merge.md#execution-clients) and [Teku](https://docs.teku.consensys.net/) as a [consensus client](../concepts/the-merge.md#consensus-clients) on Ethereum Mainnet. + +## 1. Install Besu and Teku + +Install [Besu](../get-started/install/binary-distribution.md) and [Teku](https://docs.teku.consensys.net/HowTo/Get-Started/Installation-Options/Install-Binaries/). + +Ensure you meet the prerequisites for the installation option you use. For example, you must have Java 17+ if using the Besu and Teku binary distributions. + +Ensure you meet the [system requirements for Besu on public networks](../get-started/system-requirements.md). + +## 2. Generate the shared secret + +Run the following command: + +```bash +openssl rand -hex 32 | tr -d "\n" > jwtsecret.hex +``` + +You will specify `jwtsecret.hex` when starting Besu and Teku. This is a shared JWT secret the clients use to authenticate each other when using the [Engine API](../how-to/use-engine-api.md). + +## 3. Generate validator keys + +If you're running Teku as a beacon node only, skip to the [next step](#4-start-besu). + +If you're also running Teku as a validator client, have a funded Ethereum address ready (32 ETH and gas fees for each validator). + +Generate validator keys and stake your ETH for one or more validators using the [Staking Launchpad](https://launchpad.ethereum.org/en/). + +:::info + +Save the password you use to generate each key pair in a `.txt` file. + +You should also have a `.json` file for each validator key pair. + +::: + +## 4. Start Besu + +Run the following command or specify the options in a [configuration file](../how-to/configuration-file.md): + +```bash +besu \ + --sync-mode=X_SNAP \ + --data-storage-format=BONSAI \ + --rpc-http-enabled=true \ + --rpc-http-host="0.0.0.0" \ + --rpc-ws-enabled=true \ + --rpc-ws-host="0.0.0.0" \ + --host-allowlist=,127.0.0.1,localhost \ + --engine-host-allowlist=,127.0.0.1,localhost \ + --engine-rpc-enabled \ + --engine-jwt-secret= +``` + +Specify: + +- The path to the `jwtsecret.hex` file generated in [step 2](#2-generate-the-shared-secret) using the [`--engine-jwt-secret`](../reference/cli/options.md#engine-jwt-secret) option. +- The IP address of your Besu node using the [`--host-allowlist`](../reference/cli/options.md#host-allowlist) and [`--engine-host-allowlist`](../reference/cli/options.md#engine-host-allowlist) options. + +Also, in the command: + +- [`--sync-mode`](../reference/cli/options.md#sync-mode) specifies using [snap sync](../get-started/connect/sync-node.md#snap-synchronization). +- [`--data-storage-format`](../reference/cli/options.md#data-storage-format) specifies using [Bonsai Tries](../concepts/data-storage-formats.md#bonsai-tries). +- [`--rpc-http-enabled`](../reference/cli/options.md#rpc-http-enabled) enables the HTTP JSON-RPC service. +- [`--rpc-http-host`](../reference/cli/options.md#rpc-http-host) is set to `0.0.0.0` to allow remote RPC connections. +- [`--rpc-ws-enabled`](../reference/cli/options.md#rpc-ws-enabled) enables the WebSocket JSON-RPC service. +- [`--rpc-ws-host`](../reference/cli/options.md#rpc-ws-host) is set to `0.0.0.0` to allow remote RPC connections. +- [`--engine-rpc-enabled`](../reference/cli/options.md#engine-rpc-enabled) enables the [Engine API](../reference/engine-api/index.md). + +You can modify the option values and add other [command line options](../reference/cli/options.md) as needed. + +## 5. Start Teku + +Open a new terminal window. + +### Beacon node only + +To run Teku as a beacon node only (without validator duties), run the following command or specify the options in the [Teku configuration file]: + +```bash +teku \ + --ee-endpoint=http://localhost:8551 \ + --ee-jwt-secret-file= \ + --metrics-enabled=true \ + --rest-api-enabled=true +``` + +Specify the path to the `jwtsecret.hex` file generated in [step 2](#2-generate-the-shared-secret) using the [`--ee-jwt-secret-file`](https://docs.teku.consensys.net/Reference/CLI/CLI-Syntax/#ee-jwt-secret-file) option. + +Also, in the command: + +- [`--ee-endpoint`](https://docs.teku.consensys.net/Reference/CLI/CLI-Syntax/#ee-endpoint) is set to the default URL of Besu's Engine API. +- [`--metrics-enabled`](https://docs.teku.consensys.net/Reference/CLI/CLI-Syntax/#metrics-enabled) enables Teku's metrics exporter. +- [`--rest-api-enabled`](https://docs.teku.consensys.net/Reference/CLI/CLI-Syntax/#rest-api-enabled) enables Teku's REST API service. + +You can modify the option values and add other [Teku command line options] as needed. + +### Beacon node and validator client + +To run Teku as a beacon node and validator in a single process, run the following command or specify the options in the [Teku configuration file]: + +```bash +teku \ + --ee-endpoint http://localhost:8551 \ + --ee-jwt-secret-file \ + --metrics-enabled=true \ + --rest-api-enabled=true \ + --validators-proposer-default-fee-recipient= \ + --validator-keys=:[,:,...] +``` + +Specify: + +- The path to the `jwtsecret.hex` file generated in [step 2](#2-generate-the-shared-secret) using the [`--ee-jwt-secret-file`](https://docs.teku.consensys.net/Reference/CLI/CLI-Syntax/#ee-jwt-secret-file) option. +- An Ethereum address you own as the default fee recipient using the [`--validators-proposer-default-fee-recipient`](https://docs.teku.consensys.net/Reference/CLI/CLI-Syntax/#validators-proposer-default-fee-recipient) option. +- The paths to the keystore `.json` file and password `.txt` file created in [step 3](#3-generate-validator-keys) for each validator using the [`--validator-keys`](https://docs.teku.consensys.net/Reference/CLI/CLI-Syntax/#validator-keys) option. Separate the `.json` and `.txt` files with a colon, and separate entries for multiple validators with commas. + +Also, in the command: + +- [`--ee-endpoint`](https://docs.teku.consensys.net/Reference/CLI/CLI-Syntax/#ee-endpoint) is set to the default URL of Besu's Engine API. +- [`--metrics-enabled`](https://docs.teku.consensys.net/Reference/CLI/CLI-Syntax/#metrics-enabled) enables Teku's metrics exporter. +- [`--rest-api-enabled`](https://docs.teku.consensys.net/Reference/CLI/CLI-Syntax/#rest-api-enabled) enables Teku's REST API service. + +You can modify the option values and add other [Teku command line options] as needed. + +## 6. Wait for Besu and Teku to sync + +After starting Besu and Teku, your node starts syncing and connecting to peers. + + + +# Besu logs + +```json +{"@timestamp":"2023-02-03T04:43:49,555","level":"INFO","thread":"main","class":"DefaultSynchronizer","message":"Starting synchronizer.","throwable":""} +{"@timestamp":"2023-02-03T04:43:49,556","level":"INFO","thread":"main","class":"FastSyncDownloader","message":"Starting sync","throwable":""} +{"@timestamp":"2023-02-03T04:43:49,559","level":"INFO","thread":"main","class":"Runner","message":"Ethereum main loop is up.","throwable":""} +{"@timestamp":"2023-02-03T04:43:53,106","level":"INFO","thread":"Timer-0","class":"DNSResolver","message":"Resolved 2409 nodes","throwable":""} +{"@timestamp":"2023-02-03T04:45:04,803","level":"INFO","thread":"nioEventLoopGroup-3-10","class":"SnapWorldStateDownloader","message":"Downloading world state from peers for pivot block 16545859 (0x616ae3c4cf85f95a9bce2814a7282d75dc2eac36 +cb9f0fcc6f16386df70da3c5). State root 0xa7114541f42c62a72c8b6bb9901c2ccf4b424cd7f76570a67b82a183b02f25dc pending requests 0","throwable":""} +{"@timestamp":"2023-02-03T04:46:04,834","level":"INFO","thread":"EthScheduler-Services-3 (batchPersistAccountData)","class":"SnapsyncMetricsManager","message":"Worldstate download progress: 0.08%, Peer count: 8","throwable":""} +{"@timestamp":"2023-02-03T04:48:01,840","level":"INFO","thread":"EthScheduler-Services-3 (batchPersistAccountData)","class":"SnapsyncMetricsManager","message":"Worldstate download progress: 0.23%, Peer count: 8","throwable":""} +{"@timestamp":"2023-02-03T04:49:09,931","level":"INFO","thread":"EthScheduler-Services-3 (batchPersistAccountData)","class":"SnapsyncMetricsManager","message":"Worldstate download progress: 0.41%, Peer count: 11","throwable":""} +{"@timestamp":"2023-02-03T04:50:12,466","level":"INFO","thread":"EthScheduler-Services-3 (batchPersistAccountData)","class":"SnapsyncMetricsManager","message":"Worldstate download progress: 0.61%, Peer count: 10","throwable":""} +{"@timestamp":"2023-02-03T04:51:20,977","level":"INFO","thread":"EthScheduler-Services-3 (batchPersistAccountData)","class":"SnapsyncMetricsManager","message":"Worldstate download progress: 0.75%, Peer count: 10","throwable":""} +{"@timestamp":"2023-02-03T04:51:28,985","level":"INFO","thread":"EthScheduler-Services-29 (importBlock)","class":"FastImportBlocksStep","message":"Block import progress: 180400 of 16545859 (1%)","throwable":""} +``` + +# Teku logs + +```bash +2022-03-21 20:43:24.355 INFO - Syncing *** Target slot: 76092, Head slot: 2680, Remaining slots: 73412, Connected peers: 8 +2022-03-21 20:43:36.363 INFO - Syncing *** Target slot: 76093, Head slot: 2879, Remaining slots: 73214, Connected peers: 10 +2022-03-21 20:43:48.327 INFO - Syncing *** Target slot: 76094, Head slot: 3080, Remaining slots: 73014, Connected peers: 8 +2022-03-21 20:44:00.339 INFO - Syncing *** Target slot: 76095, Head slot: 3317, Remaining slots: 72778, Connected peers: 6 +2022-03-21 20:44:12.353 INFO - Syncing *** Target slot: 76096, Head slot: 3519, Remaining slots: 72577, Connected peers: 9 +``` + + + +If you're running Teku as a beacon node only, you're all set. If you're also running Teku as a validator client, ensure Besu and Teku are fully synced before submitting your staking deposit in the next step. Syncing Besu can take several days. + +## 7. Stake ETH + +Stake your ETH for one or more validators using the [Staking Launchpad](https://launchpad.ethereum.org/en/). + +You can check your validator status by searching your Ethereum address on the [Beacon Chain explorer](https://beaconcha.in/). It may take up to multiple days for your validator to be activated and start proposing blocks. + + + +[Teku configuration file]: https://docs.teku.consensys.net/HowTo/Configure/Use-Configuration-File/ +[Teku command line options]: https://docs.teku.consensys.net/Reference/CLI/CLI-Syntax/ diff --git a/versioned_docs/version-23.10.1/public-networks/tutorials/besu-teku-testnet.md b/versioned_docs/version-23.10.1/public-networks/tutorials/besu-teku-testnet.md new file mode 100644 index 00000000000..c270a234b58 --- /dev/null +++ b/versioned_docs/version-23.10.1/public-networks/tutorials/besu-teku-testnet.md @@ -0,0 +1,218 @@ +--- +title: Run Besu and Teku on a testnet +sidebar_position: 2 +description: Run Besu and Teku on Goerli or Sepolia testnet. +tags: + - public networks +--- + +# Run Besu and Teku on a testnet + +Run Besu as an [execution client](../concepts/the-merge.md#execution-clients) and [Teku](https://docs.teku.consensys.net/) as a [consensus client](../concepts/the-merge.md#consensus-clients) on the [Goerli](https://github.com/eth-clients/goerli) and [Sepolia](https://github.com/eth-clients/sepolia) Ethereum testnets. + +:::note + +Sepolia is a permissioned network and you can't run a validator client on it without [requesting to become a validator](https://notes.ethereum.org/zvkfSmYnT0-uxwwEegbCqg) first. You can connect your consensus client using the beacon node only, without any validator duties. + +::: + +## 1. Install Besu and Teku + +Install [Besu](../get-started/install/binary-distribution.md) and [Teku](https://docs.teku.consensys.net/HowTo/Get-Started/Installation-Options/Install-Binaries/). + +Ensure you meet the prerequisites for the installation option you use. For example, you must have Java 17+ if using the Besu and Teku binary distributions. + +Ensure you meet the [system requirements for Besu on public networks](../get-started/system-requirements.md). + +## 2. Generate the shared secret + +Run the following command: + +```bash +openssl rand -hex 32 | tr -d "\n" > jwtsecret.hex +``` + +You will specify `jwtsecret.hex` when starting Besu and Teku. This is a shared JWT secret the clients use to authenticate each other when using the [Engine API](../how-to/use-engine-api.md). + +## 3. Generate validator keys + +If you're running Teku as a beacon node only, skip to the [next step](#4-start-besu). + +If you're also running Teku as a validator client, create a test Ethereum address (you can do this in [MetaMask](https://metamask.zendesk.com/hc/en-us/articles/360015289452-How-to-create-an-additional-account-in-your-wallet)). Fund this address with testnet ETH (32 ETH and gas fees for each validator) using a faucet. See the list of [Goerli faucets](https://github.com/eth-clients/goerli#meta-data-g%C3%B6rli) and [Sepolia faucets](https://github.com/eth-clients/sepolia#meta-data-sepolia). + +:::note + +If you can't get ETH using the faucet, you can ask for help on the [EthStaker Discord](https://discord.io/ethstaker). + +::: + +Generate validator keys for one or more validators using the [Goerli Staking Launchpad](https://goerli.launchpad.ethereum.org/) (or [request to become validator on Sepolia](https://notes.ethereum.org/zvkfSmYnT0-uxwwEegbCqg)). + +:::info + +Save the password you use to generate each key pair in a `.txt` file. You should also have a `.json` file for each validator key pair. + +::: + +## 4. Start Besu + +Run the following command or specify the options in a [configuration file](../how-to/configuration-file.md): + + + +# Goerli + +```bash +besu \ + --network=goerli \ + --rpc-http-enabled=true \ + --rpc-http-host=0.0.0.0 \ + --rpc-http-cors-origins="*" \ + --rpc-ws-enabled=true \ + --rpc-ws-host=0.0.0.0 \ + --host-allowlist="*" \ + --engine-host-allowlist="*" \ + --engine-rpc-enabled \ + --engine-jwt-secret= +``` + +# Sepolia + +```bash +besu \ + --network=sepolia \ + --rpc-http-enabled=true \ + --rpc-http-host=0.0.0.0 \ + --rpc-http-cors-origins="*" \ + --rpc-ws-enabled=true \ + --rpc-ws-host=0.0.0.0 \ + --host-allowlist="*" \ + --engine-host-allowlist="*" \ + --engine-rpc-enabled \ + --engine-jwt-secret= +``` + + + +Specify the path to the `jwtsecret.hex` file generated in [step 2](#2-generate-the-shared-secret) using the [`--engine-jwt-secret`](../reference/cli/options.md#engine-jwt-secret) option. + +You can modify the option values and add other [command line options](../reference/cli/options.md) as needed. + +## 5. Start Teku + +Open a new terminal window. + +### Beacon node only + +To run Teku as a beacon node only (without validator duties), run the following command or specify the options in the [Teku configuration file]: + + + +# Goerli + +```bash +teku \ + --network=goerli \ + --ee-endpoint=http://localhost:8551 \ + --ee-jwt-secret-file= \ + --metrics-enabled=true \ + --rest-api-enabled=true +``` + +# Sepolia + +```bash +teku \ + --network=sepolia \ + --ee-endpoint=http://localhost:8551 \ + --ee-jwt-secret-file= \ + --metrics-enabled=true \ + --rest-api-enabled=true +``` + + + +Specify the path to the `jwtsecret.hex` file generated in [step 2](#2-generate-the-shared-secret) using the [`--ee-jwt-secret-file`](https://docs.teku.consensys.net/Reference/CLI/CLI-Syntax/#ee-jwt-secret-file) option. + +You can modify the option values and add other [Teku command line options] as needed. + +### Beacon node and validator client + +To run Teku as a beacon node and validator in a single process, run the following command or specify the options in the [Teku configuration file]: + + + +# Goerli + +```bash +teku \ + --network=goerli \ + --ee-endpoint=http://localhost:8551 \ + --ee-jwt-secret-file= \ + --metrics-enabled=true \ + --rest-api-enabled=true \ + --validators-proposer-default-fee-recipient= \ + --validator-keys=:[,:,...] +``` + +# Sepolia + +Sepolia is a permissioned network and you can't run a validator client on it without [requesting to become a validator](https://notes.ethereum.org/zvkfSmYnT0-uxwwEegbCqg) first. + + + +Specify: + +- The path to the `jwtsecret.hex` file generated in [step 2](#2-generate-the-shared-secret) using the [`--ee-jwt-secret-file`](https://docs.teku.consensys.net/Reference/CLI/CLI-Syntax/#ee-jwt-secret-file) option. +- The test Ethereum address created in [step 3](#3-generate-validator-keys) as the default fee recipient using the [`--validators-proposer-default-fee-recipient`](https://docs.teku.consensys.net/Reference/CLI/CLI-Syntax/#validators-proposer-default-fee-recipient) option. +- The paths to the keystore `.json` file and password `.txt` file created in [step 3](#3-generate-validator-keys) for each validator using the [`--validator-keys`](https://docs.teku.consensys.net/Reference/CLI/CLI-Syntax/#validator-keys) option. Separate the `.json` and `.txt` files with a colon, and separate entries for multiple validators with commas. + +You can modify the option values and add other [Teku command line options] as needed. + +## 6. Wait for Besu and Teku to sync + +After starting Besu and Teku, your node starts syncing and connecting to peers. + + + +# Besu logs + +```json +{"@timestamp":"2023-02-03T04:43:49,555","level":"INFO","thread":"main","class":"DefaultSynchronizer","message":"Starting synchronizer.","throwable":""} +{"@timestamp":"2023-02-03T04:43:49,556","level":"INFO","thread":"main","class":"FastSyncDownloader","message":"Starting sync","throwable":""} +{"@timestamp":"2023-02-03T04:43:49,559","level":"INFO","thread":"main","class":"Runner","message":"Ethereum main loop is up.","throwable":""} +{"@timestamp":"2023-02-03T04:43:53,106","level":"INFO","thread":"Timer-0","class":"DNSResolver","message":"Resolved 2409 nodes","throwable":""} +{"@timestamp":"2023-02-03T04:45:04,803","level":"INFO","thread":"nioEventLoopGroup-3-10","class":"SnapWorldStateDownloader","message":"Downloading world state from peers for pivot block 16545859 (0x616ae3c4cf85f95a9bce2814a7282d75dc2eac36 +cb9f0fcc6f16386df70da3c5). State root 0xa7114541f42c62a72c8b6bb9901c2ccf4b424cd7f76570a67b82a183b02f25dc pending requests 0","throwable":""} +{"@timestamp":"2023-02-03T04:46:04,834","level":"INFO","thread":"EthScheduler-Services-3 (batchPersistAccountData)","class":"SnapsyncMetricsManager","message":"Worldstate download progress: 0.08%, Peer count: 8","throwable":""} +{"@timestamp":"2023-02-03T04:48:01,840","level":"INFO","thread":"EthScheduler-Services-3 (batchPersistAccountData)","class":"SnapsyncMetricsManager","message":"Worldstate download progress: 0.23%, Peer count: 8","throwable":""} +{"@timestamp":"2023-02-03T04:49:09,931","level":"INFO","thread":"EthScheduler-Services-3 (batchPersistAccountData)","class":"SnapsyncMetricsManager","message":"Worldstate download progress: 0.41%, Peer count: 11","throwable":""} +{"@timestamp":"2023-02-03T04:50:12,466","level":"INFO","thread":"EthScheduler-Services-3 (batchPersistAccountData)","class":"SnapsyncMetricsManager","message":"Worldstate download progress: 0.61%, Peer count: 10","throwable":""} +{"@timestamp":"2023-02-03T04:51:20,977","level":"INFO","thread":"EthScheduler-Services-3 (batchPersistAccountData)","class":"SnapsyncMetricsManager","message":"Worldstate download progress: 0.75%, Peer count: 10","throwable":""} +{"@timestamp":"2023-02-03T04:51:28,985","level":"INFO","thread":"EthScheduler-Services-29 (importBlock)","class":"FastImportBlocksStep","message":"Block import progress: 180400 of 16545859 (1%)","throwable":""} +``` + +# Teku logs + +```bash +2022-03-21 20:43:24.355 INFO - Syncing *** Target slot: 76092, Head slot: 2680, Remaining slots: 73412, Connected peers: 8 +2022-03-21 20:43:36.363 INFO - Syncing *** Target slot: 76093, Head slot: 2879, Remaining slots: 73214, Connected peers: 10 +2022-03-21 20:43:48.327 INFO - Syncing *** Target slot: 76094, Head slot: 3080, Remaining slots: 73014, Connected peers: 8 +2022-03-21 20:44:00.339 INFO - Syncing *** Target slot: 76095, Head slot: 3317, Remaining slots: 72778, Connected peers: 6 +2022-03-21 20:44:12.353 INFO - Syncing *** Target slot: 76096, Head slot: 3519, Remaining slots: 72577, Connected peers: 9 +``` + + + +If you're running Teku as a beacon node only, you're all set. If you're also running Teku as a validator client, ensure Besu and Teku are fully synced before submitting your staking deposit in the next step. Syncing Besu can take several days. + +## 7. Stake ETH + +Stake your testnet ETH for one or more validators using the [Goerli Staking Launchpad](https://goerli.launchpad.ethereum.org/). + +You can check your validator status by searching your Ethereum address on the [Goerli Beacon Chain explorer](https://goerli.beaconcha.in/). It may take up to multiple days for your validator to be activated and start proposing blocks. + + + +[Teku configuration file]: https://docs.teku.consensys.net/HowTo/Configure/Use-Configuration-File/ +[Teku command line options]: https://docs.teku.consensys.net/Reference/CLI/CLI-Syntax/ diff --git a/versioned_sidebars/version-23.10.1-sidebars.json b/versioned_sidebars/version-23.10.1-sidebars.json new file mode 100644 index 00000000000..32910f92f17 --- /dev/null +++ b/versioned_sidebars/version-23.10.1-sidebars.json @@ -0,0 +1,14 @@ +{ + "publicDocSidebar": [ + { + "type": "autogenerated", + "dirName": "public-networks" + } + ], + "privateDocSidebar": [ + { + "type": "autogenerated", + "dirName": "private-networks" + } + ] +} diff --git a/versions.json b/versions.json index d0c766221c4..a8f6f67e50f 100644 --- a/versions.json +++ b/versions.json @@ -1,4 +1,5 @@ [ + "23.10.1", "23.10.0", "23.7.3", "23.7.2",