<ulclass="nav"><liclass="active"><ahref="#Overview">Overview</a></li><li><ahref="#Getting-Started">Getting Started</a><ulclass="nav"><li><ahref="#Installation">Installation</a></li><li><ahref="#Quickstart">Basic Quickstart</a></li><li><ahref="#Private-Network-Quickstart">Private Network Quickstart</a></li><li><ahref="#Starting-Pantheon">Starting Pantheon</a></li><li><ahref="#Run-Docker-Image">Running Pantheon from Docker Image</a></li></ul></li><li><span>Configuring Pantheon</span><ulclass="nav"><li><ahref="#NetworkID-And-ChainID">Network ID and Chain ID</a></li><li><ahref="#Node-Keys">Node Keys</a></li><li><ahref="#Networking">Networking</a></li><li><ahref="#Accounts-for-Testing">Accounts for Testing</a></li><li><ahref="#Logging">Logging</a></li><li><ahref="#Testing-Developing-Nodes">Testing and Developing Nodes</a></li><li><ahref="#Proof-of-Authority">Proof of Authority</a></li><li><ahref="#Passing-JVM-Options">Passing JVM Options</a></li></ul></li><li><span>Using Pantheon</span><ulclass="nav"><li><ahref="#Transactions">Creating and Sending Transactions</a></li><li><ahref="#Account-Management">Using Wallets for Account Management</a></li><li><ahref="#Mining">Mining</a></li><li><ahref="#RPC-PubSub">RPC Pub/Sub</a></li><li><ahref="#Debugging">Debugging Pantheon</a></li></ul></li><li><span>Reference</span><ulclass="nav"><li><ahref="#Pantheon-CLI-Syntax">Pantheon CLI Reference</a></li><li><ahref="#JSON-RPC-API">JSON-RPC API Reference</a></li></ul></li></ul>
<p>Pantheon is an open-source Ethereum client developed under the Apache 2.0 license and written in Java. It runs on the Ethereum public network, private networks, and test networks such as Rinkeby and Ropsten. Pantheon implements Proof of Work (Ethash) and Proof of Authority (Clique) consensus mechanisms. </p>
<p>Pantheon includes a <ahref="https://github.com/PegaSysEng/pantheon/wiki/Pantheon-CLI-Syntax">command line interface</a> and <ahref="https://github.com/PegaSysEng/pantheon/wiki/JSON-RPC-API">JSON-RPC API</a> for running, maintaining, debugging, and monitoring node operations in an Ethereum network. You can use the API via RPC over HTTP or via WebSockets transport, and Pub/Sub is supported. The API supports typical Ethereum functionalities such as:</p>
<p>The Pantheon client supports common smart contract and Dapp development, deployment, and operational use cases, using tools such as <ahref="http://truffleframework.com/">Truffle</a>, <ahref="https://github.com/ethereum/remix">Remix</a>, and <ahref="https://web3j.io/">web3j</a>. The client supports common JSON-RPC API methods such as eth, net, web3, debug, and miner.</p>
<p>To run a single node to connect the Ethereum mainnet or a public testnet, running from the Pantheon <ahref="#Run-Docker-Image">docker image</a> or <ahref="https://bintray.com/consensys/pegasys-repo/pantheon/0.8.1#files">downloading the packaged binaries</a> is the fastest way to get started. </p>
<p>To run a private network on which you can make JSON-RPC requests and send transactions, or explore Pantheon and Ethereum networks, the <ahref="#Private-Network-Quickstart">Private Network Quickstart</a> runs a private network of Pantheon nodes in a Docker container. </p>
<p><strong>Note</strong> If you have installed Pantheon from the <ahref="https://bintray.com/consensys/pegasys-repo/pantheon/0.8.1#files">packaged binaries</a> or are running the <ahref="https://hub.docker.com/r/pegasyseng/pantheon/">Docker image</a>, you do not need to follow the procedures in this section. You can proceed with the <ahref="#Quickstart">Basic Quickstart</a> or <ahref="#Starting-Pantheon">Starting Pantheon</a>.</p>
<li><p>Disk space and RAM: Your computer should have at least 4 GB RAM. Disk space needed varies depending on the network on which you run nodes. A small test network might require 200 MB while a mainnet node might require 1.5TB. If syncing a node on mainnet, allow 1.5 TB to 2 TB for the full blockchain archive.</p>
<p>After the cloning process completes, go to the <code>pantheon</code> repo directory and run <code>git branch</code> to make sure you're in the branch in which you cloned the Pantheon source code (by default this is the <code>master</code> branch).</p>
<p>Build the pantheon executable using <code>gradlew</code>. You can use the <code>-x test</code> option to exclude tests, which can take a long time to run and are not necessary for initial build:</p>
<p><strong>Note</strong> Pantheon is currently supported only on 64-bit versions of Windows, and requires a 64-bit version of JDK/JRE. We recommend that you also remove any 32-bit JDK/JRE installations.</p>
<p>In Git bash, go to your working directory for repositories. Clone the <code>PegaSysEng/pantheon</code> repo into this directory:</p>
<preclass="hljs">git <spanclass="hljs-keyword">clone</span><spanclass="hljs-title">--recursive</span> https://github.com/PegaSysEng/pantheon</pre><p>This creates a <code>pantheon</code> directory under Git revision control that will contain the cloned repo contents.</p>
<h4id="build-pantheon">Build Pantheon</h4>
<p>Go to the <code>pantheon</code> directory:</p>
<preclass="hljs"><spanclass="hljs-built_in">cd</span> pantheon</pre><p>Open a Windows command prompt (the following won't work in Git bash). Build Pantheon with the Gradle wrapper <code>gradlew</code>, omitting tests as follows:</p>
<p><strong>Note</strong> To run <code>gradlew</code>, you must have the <strong>JAVA_HOME</strong> system variable set to the Java installation directory.
For example: <code>JAVA_HOME = C:\Program Files\Java\jdk1.8.0_181</code>.</p>
<p>After the build completes, your system is ready to run Pantheon. See <ahref="#Starting-Pantheon">Starting Pantheon</a> and other sections of <ahref="#Getting-Started">Getting Started</a> for guidance on using Pantheon.</p>
<h2id="installation-on-vm">Installation on VM</h2>
<p>You can run Pantheon on a virtual machine (VM) on a cloud service such as AWS or Azure, or locally using a VM manager such as <ahref="https://www.virtualbox.org/">VirtualBox</a>.</p>
<p>If you set up your own VM locally using a VM manager such as <ahref="https://www.virtualbox.org/">VirtualBox</a>, there are a few considerations:</p>
<ul>
<li><p>Make sure that Intel Virtualization Technology (VTx) and Virtualization Technology for Directed I/O (VT-d) are enabled in BIOS settings.</p>
</li>
<li><p>On Windows, you might need to disable Hyper-V in the Windows Feature list.</p>
</li>
</ul>
<p>It is recommended that you create a VM with the following attributes:</p>
<ul>
<li><p>Memory Size: Set to 4096 (recommended)</p>
</li>
<li><p>Create a virtual hard disk with at least 10 GB; 20 GB is recommended</p>
</li>
<li><p>Virtual hard disk file type: VDI (if you need to share it with other apps, use VHD)</p>
</li>
<li><p>(Optional) You can create a shared directory in order 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 <ahref="https://linus.nci.nih.gov/bdge/installUbuntu.html">Install Ubuntu on Oracle VirtualBox</a>.</p>
<li>Listen on the default RPC over HTTP host/port.</li>
<li>Use full synchronization mode.</li>
</ul>
<p>During the tutorial, you'll import a test block file to provide the initial blocks for the node to use, then run the node. You'll then use <code>curl</code> to make a call using Pantheon JSON-RPC API; this will make a request to verify that the node is running.</p>
<h2id="installation">Installation</h2>
<p>Install Java, Git, and Pantheon for your platform as described in <ahref="#Installation">Installation</a>, then proceed through the following steps.</p>
<h2id="run-pantheon">Run Pantheon</h2>
<p>In this tutorial, you'll build and run Pantheon in one terminal (bash) window and run <code>curl</code> commands to make JSON-RPC requests in another terminal window. To do this, either open two separate instances of <code>Terminal</code>, or run a utility such as <ahref="https://github.com/tmux/tmux/wiki">tmux</a> to run a split screen terminal.</p>
<p>In the first terminal, go to the <code>~/pantheon</code> folder:</p>
<preclass="hljs"><spanclass="hljs-built_in">cd</span> pantheon</pre><p>Build Pantheon as described in <ahref="#Installation">Installation</a>.</p>
<p>To run <code>pantheon</code>, go to the distribution folder:</p>
<preclass="hljs"><spanclass="hljs-built_in">cd</span> build/distributions/</pre><p>Expand the distribution archive:</p>
<preclass="hljs">tar -xzf pantheon-<version>.tar.gz</pre><p>Move to the expanded folder and run <code>pantheon</code> using the script to display command help:</p>
bin/pantheon --<spanclass="hljs-built_in">help</span></pre><p>Import initial blocks for the node to work with from a blocks file. You can use the provided sample blocks file as shown in the following command:</p>
<preclass="hljs">bin/pantheon import ~/pantheon/testutil/src/main/resources/1000.blocks</pre><p>When the import completes successfully, you should see messages containing the following:</p>
<preclass="hljs">ImportSubCommand | Runs import sub <spanclass="hljs-built_in">command</span> with blocksImportPath
KeyPairUtil | Generated new key <key> and stored it to ~/pantheon/build/distributions/pantheon-<version>/key</pre><p>For more information on using the <code>pantheon import</code> subcommand, see <ahref="#Pantheon-CLI-Syntax">Pantheon CLI Syntax</a>.</p>
<p>After the import successfully completes, run Pantheon with only the <code>--rpc-enabled</code> option:</p>
<preclass="hljs">bin/pantheon <spanclass="hljs-comment">--rpc-enabled</span></pre><p>This runs Pantheon in default mode, meaning it runs in mainnet with the default genesis file, and peer discovery is enabled.</p>
<p>The <code>--rpc-enabled</code> option starts the JSON-RPC service. </p>
<p>The terminal output will indicate that the node is synchronizing.</p>
<h2id="test-the-pantheon-node">Test the Pantheon Node</h2>
<h4id="make-json-rpc-requests-using-curl">Make JSON-RPC Requests using curl</h4>
<p>While the node is running, make a request on it using curl and the JSON-RPC API.</p>
<p>Switch to the bottom window using <code>Ctrl+b o</code> and run the following <code>curl</code> command:</p>
<preclass="hljs">curl -X POST --data '{<spanclass="hljs-string">"jsonrpc"</span>:<spanclass="hljs-string">"2.0"</span>,<spanclass="hljs-string">"method"</span>:<spanclass="hljs-string">"eth_syncing"</span>,<spanclass="hljs-string">"params"</span>:<spanclass="hljs-string">[]</span>,<spanclass="hljs-string">"id"</span>:<spanclass="hljs-number">1</span>}' <spanclass="hljs-number">127.0.0.1:8545</span></pre><p>Note the endpoint IP and default port. You should see a result similar to the following:</p>
}</pre><p>You can now call other JSON-RPC commands listed in <ahref="https://github.com/PegaSysEng/pantheon/wiki/JSON-RPC-API">Pantheon JSON RPC API</a>.</p>
<h2id="close-the-terminal-session">Close the Terminal Session</h2>
<p>After you're finished running the demo, you can stop the Pantheon client by returning to the terminal window that runs the node and entering <code>Ctrl+c</code>.</p>
<p>This tutorial describes how to use Pantheon to run a private network of Pantheon nodes in a Docker container.</p>
<blockquote>
<p><strong>Note</strong> To run the Private Network Quickstart, you must install Pantheon by <ahref="https://github.com/PegaSysEng/pantheon/wiki/Installation">cloning and building</a>. </p>
<p>If you have installed Pantheon from the <ahref="https://pegasys.tech/">packaged binaries</a> or are running the <ahref="https://hub.docker.com/u/pegasyseng/">Docker image</a>, you can proceed with the <ahref="#Quickstart">Basic Quickstart</a> or <ahref="#Starting-Pantheon">Starting Pantheon</a>.</p>
</blockquote>
<h2id="prerequisites">Prerequisites</h2>
<p>To run this tutorial, you must have the following installed:</p>
<ul>
<li><p><ahref="https://docs.docker.com/compose/install/">Docker and Docker-compose</a></p>
<li><p>A web browser that supports <ahref="https://metamask.io/">Metamask</a> (currently Chrome, Firefox, Opera, and Brave), and has the MetaMask plug-in installed. This tutorial uses screenshots from Brave.</p>
quickstart\docker-compose port explorer 80</pre><p>This script builds Pantheon, builds the images and runs the containers. It will also scale the regular node container to four containers to simulate a network with enough peers to synchronize.</p>
quickstart_bootnode_1 /opt/pantheon/bootnode_sta ... Up <spanclass="hljs-number">30303</span>/tcp, <spanclass="hljs-number">8545</span>/tcp, <spanclass="hljs-number">8546</span>/tcp
quickstart_explorer_1 nginx -g daemon off; Up <spanclass="hljs-number">0.0</span><spanclass="hljs-number">.0</span><spanclass="hljs-number">.0</span>:<spanclass="hljs-number">32770</span>-><spanclass="hljs-number">80</span>/tcp
quickstart_minernode_1 /opt/pantheon/node_start.s ... Up <spanclass="hljs-number">30303</span>/tcp, <spanclass="hljs-number">8545</span>/tcp, <spanclass="hljs-number">8546</span>/tcp
quickstart_node_1 /opt/pantheon/node_start.s ... Up <spanclass="hljs-number">30303</span>/tcp, <spanclass="hljs-number">8545</span>/tcp, <spanclass="hljs-number">8546</span>/tcp
quickstart_node_2 /opt/pantheon/node_start.s ... Up <spanclass="hljs-number">30303</span>/tcp, <spanclass="hljs-number">8545</span>/tcp, <spanclass="hljs-number">8546</span>/tcp
quickstart_node_3 /opt/pantheon/node_start.s ... Up <spanclass="hljs-number">30303</span>/tcp, <spanclass="hljs-number">8545</span>/tcp, <spanclass="hljs-number">8546</span>/tcp
quickstart_node_4 /opt/pantheon/node_start.s ... Up <spanclass="hljs-number">30303</span>/tcp, <spanclass="hljs-number">8545</span>/tcp, <spanclass="hljs-number">8546</span>/tcp
quickstart_rpcnode_1 /opt/pantheon/node_start.s ... Up <spanclass="hljs-number">30303</span>/tcp, <spanclass="hljs-number">0.0</span><spanclass="hljs-number">.0</span><spanclass="hljs-number">.0</span>:<spanclass="hljs-number">32769</span>-><spanclass="hljs-number">8545</span>/tcp, <spanclass="hljs-number">0.0</span><spanclass="hljs-number">.0</span><spanclass="hljs-number">.0</span>:<spanclass="hljs-number">32768</span>-><spanclass="hljs-number">8546</span>/tcp</pre><p>This is followed by a list of the endpoints:</p>
<li>Use the <strong>JSON-RPC HTTP service endpoint</strong> to access the RPC node service from your Dapp or from cryptocurrency wallets such as Metamask.</li>
<li>Use the <strong>JSON-RPC WebSocket service endpoint</strong> to access the web socket node service from your Dapp. Use the form <code>ws://localhost:32770/jsonws</code>.</li>
<li>Use the <strong>Web block explorer address</strong> to display the block explorer web application. View the block explorer by entering the URL in your web browser.</li>
</ul>
<blockquote>
<p>On Linux/Mac, to display the list of endpoints again, run the following shell command:</p>
<p>This tutorial uses the <ahref="https://aleth.io/">Alethio light block explorer</a>.</p>
<h3id="run-the-block-explorer">Run the Block Explorer</h3>
<p>Access the explorer by copying and pasting the <code>Web block explorer address</code> displayed when starting the private network to your browser.</p>
<p>The block explorer displays a summary of the private network:</p>
<p>You can run RPC requests on <code>rpcnode</code>, the node that is exposed to the host in order to listen for requests. This tutorial uses <ahref="https://curl.haxx.se/download.html">cURL</a> to make JSON-RPC requests.</p>
<blockquote>
<p><strong>On Windows:</strong> We suggest using Postman or a similar client to make RPC requests from Windows. Using curl via Command Prompt or Windows PowerShell might not work.</p>
</blockquote>
<p>This tutorial uses the placeholder <code>http://localhost:http-rpc-port</code>. When you run this tutorial, replace <code>http-rpc-port</code> with the JSON-RPC HTTP service endpoint provided when you list the endpoints. (For example, <code>http://localhost:32770/jsonrpc</code>.) The dynamic docker port mapping changes each time you run the network.</p>
<h3id="requesting-the-node-version">Requesting the Node Version</h3>
<p>Run the following command from the host shell :</p>
<preclass="hljs">curl -X POST --data <spanclass="hljs-string">'{"jsonrpc":"2.0","method":"web3_clientVersion","params":[],"id":1}'</span> http://localhost:http-rpc-port</pre><p>The result should be as follows: </p>
}</pre><p>Here we simply query the version of the Pantheon node, which confirms the node is running.</p>
<p>Now if this works, let's see some more interesting requests.</p>
<h3id="counting-peers">Counting Peers</h3>
<p>Peers are the number of other nodes connected to the RPC node.</p>
<p>Poll the peer count using <code>net_peerCount</code>:</p>
<preclass="hljs">curl -X POST --data <spanclass="hljs-string">'{"jsonrpc":"2.0","method":"net_peerCount","params":[],"id":1}'</span> http://localhost:http-rpc-port</pre><p>The result should be the following response, indicating that there are 6 peers:</p>
}</pre><h3id="requesting-the-most-recent-mined-block-number">Requesting the Most Recent Mined Block Number</h3>
<p>This provides the count of blocks already mined.</p>
<p>To do so, call <code>eth_blockNumber</code> to retrieve the number of the most recent block:</p>
<preclass="hljs">curl -X POST --data <spanclass="hljs-string">'{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}'</span> http://localhost:http-rpc-port</pre><p>The result of this call should be:</p>
}</pre><p>Here the hexadecimal value <code>0x8b8</code> translates to <code>2232</code> in decimal; that many blocks have already been mined.</p>
<h3id="checking-the-miner-account-balance-coinbase-">Checking the Miner Account Balance (Coinbase)</h3>
<p>Then call <code>eth_getBalance</code> to retrieve the balance of the mining address defined in the miner node:</p>
<preclass="hljs">curl -X POST --data <spanclass="hljs-string">'{"jsonrpc":"2.0","method":"eth_getBalance","params":["0xfe3b557e8fb62b89f4916b721be55ceb828dbd73","latest"],"id":1}'</span> http://localhost:http-rpc-port</pre><p>The result of this call should be something like :</p>
}</pre><p><em>0x79f905c6fd34e80000 = 2250000000000000000000 Wei (2250 Ether)</em> (you can use a unit <ahref="https://etherconverter.online/">converter</a> )</p>
<p>Wait a few seconds until new blocks are mined and make this call again. The balance should increase,
meaning that the miner address successfully received the mining reward.</p>
<p><em>Also you can see this information in the block explorer. It does exactly the same thing as we
did manually, connecting to the rpc node using http JSON-RPC, but displays information on a web page.</em></p>
<li>Initial balance : 0x90000000000000000000000 (2785365088392105618523029504 in decimal)</li>
</ul>
<blockquote>
<p><strong>Note:</strong> Pantheon does not provide an accounts management system, so if you want to create your own account, you will have to use a third party tool like Metamask.</p>
</blockquote>
<h3id="creating-a-transaction-using-metamask">Creating a Transaction Using MetaMask</h3>
<p>After you sign in to MetaMask, connect to the private network RPC endpoint by:</p>
<ol>
<li>In the MetaMask network list, select <strong>Custom RPC</strong>.</li>
<li>In the <strong>New RPC URL</strong> field, enter the <code>JSON-RPC HTTP service endpoint</code> displayed when you started the private network.</li>
</ol>
<p>Save the configuration and return to the MetaMask main screen. Your current network is now set to the private network RPC node.</p>
<p><ahref="https://metamask.zendesk.com/hc/en-us/articles/360015489331-Importing-an-Account-New-UI-">Import one of the existing accounts above into metamask</a>
<p>Once this is done, try to <ahref="https://metamask.zendesk.com/hc/en-us/articles/360015289452-Creating-Additional-MetaMask-Wallets-New-UI-">create another account from scratch</a>
<p><em>Of course remember that here we are dealing with valueless ether as we are not
on the main network but on a local private network.</em></p>
<p>In MetaMask, select the new account and copy the account address by clicking the <strong>...</strong> button and selecting <strong>Copy Address to clipboard</strong>.</p>
<p>In the block explorer, search for the new account by clicking on the magnifying glass and pasting the account address into the search box. The account is displayed with a zero balance. </p>
from the first account (containing some ether) to the new one (that have a zero balance).</p>
<p>Click refresh on the browser page displaying the new account. The updated balance is displayed and reflects the transaction completed using MetaMask. </p>
<h3id="playing-with-the-truffle-pet-shop-tutorial">Playing with the Truffle Pet Shop Tutorial</h3>
<p>This step is inspired by <ahref="https://truffleframework.com/tutorials/pet-shop">the PetShop tutorial on Truffle website</a>.</p>
<p>Use the following instructions to run it with the quick-start Pantheon Docker network and a wallet to manage keys.</p>
<h4id="prerequisites">Prerequisites</h4>
<ul>
<li>Install Truffle :</li>
</ul>
<preclass="hljs">npm install -g truffle</pre><ul>
<li>Grab the tutorial <ahref="https://truffleframework.com/tutorials/pet-shop#creating-a-truffle-project-using-a-truffle-box">as indicated in the Truffle site</a>:</li>
};</pre><p>Then replace the <code>[YOUR HTTP RPC NODE ENDPOINT]</code> placeholder with your HTTP RPC node endpoint. <code>http://localhost:32770/jsonrpc</code> in this case.</p>
<p>The private address indicated in the file is the miner address so we know we will have funds in it. You don't need to change it.</p>
<p>Once this is done, you can go through the regular tutorial steps.</p>
<p>When you have to run a truffle command, you only have to indicate the right network to use, as in the following command using the <code>--network quickstartWallet</code> option :</p>
<preclass="hljs">truffle migrate --network quickstartWallet</pre><p>You're now able to see the transactions and contracts deployed on your local docker network on the block explorer.</p>
<h2id="shut-down-the-network-and-remove-the-containers">Shut Down the Network and Remove the Containers</h2>
<p>To shut down the network and delete all containers:</p>
<blockquote>
<p>On Linux/Mac, run the following shell command:</p>
<p><strong>Note</strong> On Windows, the quickstart creates a volume called <code>quickstart_public-keys</code>. Remove this volume using <code>docker volume rm quickstart_public-keys</code>.</p>
<p>Pantheon nodes can be used for varying purposes as described in the <ahref="#Overview">Overview</a>. Nodes can connect to the Ethereum mainnet, public testnets such as Ropsten, or private networks.</p>
<h2id="local-block-data">Local Block Data</h2>
<p>When connecting to a network other than the network previously connected to, you must either delete the local block data or use the <code>--datadir</code> option to specify a different data directory. </p>
<p>To delete the local block data, delete the <code>database</code> directory in the <code>pantheon/build/distribution/pantheon-0.8.0-<version></code> directory.</p>
<p>Pantheon specifies the genesis configuration, and sets the network ID and bootnodes when connecting to <ahref="#run-a-node-on-ethereum--mainnet">mainnet</a>, <ahref="#run-a-node-on-rinkeby-testnet">Rinkeby</a>, and <ahref="#run-a-node-on-ropsten-testnet">Ropsten</a>. </p>
<p>When <code>--dev-mode</code> is specified, Pantheon uses the development mode genesis configuration.</p>
<p>The genesis files defining the genesis configurations are in the <ahref="https://github.com/PegaSysEng/pantheon/tree/master/config/src/main/resources">Pantheon source files</a>. </p>
<p>To define a genesis configuration, create a genesis file (for example, <code>genesis.json</code>) and specify the file using the <code>--genesis</code> option.</p>
<p><strong>Note</strong> From v0.8.2 or when <ahref="#Installation">building from source</a>, use the <ahref="#Pantheon-CLI-Syntaxoptions"><code>--ropsten</code> option</a> instead of the following options. For v0.8.1, use the following options.</p>
<p>All other <ahref="https://github.com/PegaSysEng/pantheon/wiki/Pantheon-CLI-Syntax">Pantheon command line options</a> work in the same way as when Pantheon is installed locally.</p>
<h3id="persisting-data">Persisting Data</h3>
<p>Specify a Docker volume to persist data between stopping and restarting the container. This is the equivalent of specifying the <code>-datadir</code> option. </p>
<p>If a Docker volume is not specified, all data saved to the data directory is removed each time the container is stopped. </p>
<p>To run Pantheon specifying a volume for the data directory: </p>
<p>Specify a custom configuration file to provide a file containing key/value pairs for command line options. This is the equivalent of specifying the <code>--config</code> option. </p>
<p>To run Pantheon specifying a custom configuration file: </p>
<preclass="hljs">docker run --mount type=bind,source=</path/mygenesis.json>,target=/etc/pantheon/genesis.json pegasyseng/pantheon:latest</pre><p>Where <code>mygenesis.json</code> is your custom configuration file and <code>path</code> is the absolute path to the file. For example:</p>
<preclass="hljs">docker run --mount type=bind,source=/Users/username/pantheon/mygenesis.json,target=/etc/pantheon/genesis.json pegasyseng/pantheon:latest</pre><h3id="exposing-ports">Exposing Ports</h3>
<p>Expose ports for P2P peer discovery, JSON-RPC service, and WebSockets. This is required to use the defaults ports or specify different ports (the equivalent of specifying the <code>--rpc-listen</code>, <code>--p2p-listen</code>, <code>--ws-listen</code> options).</p>
<p>To run Pantheon exposing local ports for access: </p>
<preclass="hljs">docker run -p <localportJSON-RPC>:8545 -p <localportWS>:8546 -p <localportP2P>:30303 pegasyseng/pantheon:latest --rpc-enabled --ws-enabled</pre><p>For example, to enable RPC calls to <ahref="http://127.0.0.1:8545">http://127.0.0.1:8545</a> and P2P discovery on <ahref="http://127.0.0.1:13001">http://127.0.0.1:13001</a>:</p>
<preclass="hljs">docker run -p 8545:8545 -p 13001:30303 pegasyseng/pantheon:latest --rpc-enabled</pre><h2id="starting-pantheon">Starting Pantheon</h2>
<h3id="run-a-node-on-ethereum-mainnet">Run a Node on Ethereum Mainnet</h3>
<preclass="hljs">docker run -p 30303:30303 --mount type=bind,source=/<myvolume/pantheon>,target=/var/lib/pantheon pegasyseng/pantheon:latest</pre><p>To run a node on mainnet with the HTTP JSON-RPC service enabled: </p>
<preclass="hljs">docker run -p 8545:8545 -p 30303:30303 --mount type=bind,source=/<myvolume/pantheon>,target=/var/lib/pantheon pegasyseng/pantheon:latest --rpc-enabled</pre><h2id="run-a-node-on-ropsten-testnet">Run a Node on Ropsten Testnet</h2>
<p>Save a local copy of the <ahref="https://github.com/PegaSysEng/pantheon/blob/master/config/src/main/resources/ropsten.json">Ropsten genesis file</a>. </p>
<preclass="hljs">docker run -p 30303:30303 --mount type=bind,source=/<myvolume/pantheon/rinkeby>,target=/var/lib/pantheon pegasyseng/pantheon:latest --rinkeby</pre><h2id="run-a-node-for-testing">Run a Node for Testing</h2>
<preclass="hljs">docker run -p 8546:8546 --mount type=bind,source=/<myvolume/pantheon/testnode>,target=/var/lib/pantheon pegasyseng/pantheon:latest --dev-mode --bootnodes= --miner-enabled --miner-coinbase fe3b557e8fb62b89f4916b721be55ceb828dbd73 --rpc-cors-origins "all" --ws-enabled</pre><h2id="stopping-pantheon-and-cleaning-up-resources">Stopping Pantheon and Cleaning up Resources</h2>
<p>When you're done running nodes, you can shut down the node container without deleting resources. Alternatively, you can delete the container (after stopping it) and its associated volume. Run <code>docker container ls</code> and <code>docker volume ls</code> to obtain the container and volume names. Then run the following commands:</p>
<p>To stop a container:</p>
<preclass="hljs">docker stop <container-name></pre><p>To delete a container:</p>
<preclass="hljs">docker rm <container-name></pre><p>To delete a container volume (optional):</p>
<preclass="hljs">docker volume rm <volume-name></pre><pclass="page"id="NetworkID-And-ChainID"></p><h1>Network ID and Chain ID</h1>
<h1id="network-id-and-chain-id">Network ID and Chain ID</h1>
<p>Ethereum networks have a network ID and a chain ID. The network ID is specified using the <code>--network-id</code> option and the chain ID is specified in the genesis file.</p>
<p>For most networks including mainnet and the public testnets, the network ID and the chain ID are the same. </p>
<p>The network ID is defined by Pantheon when connecting to the Ethereum mainnet (<code>1</code>), Rinkeby (<code>4</code>), and Ropsten(<code>3</code>).</p>
<p>When using the <code>--dev-mode</code> or <code>--genesis</code> options, specify the network ID using the <code>--network-id</code> option. </p>
<p>Each node has a node key pair consisting of a node private key and node public key. </p>
<h2id="node-private-key">Node Private Key</h2>
<p>If a <code>key</code> file does not exist in the data directory and the <code>--node-private-key</code> option is not specified when Pantheon is started, a node private key is generated and written to the <code>key</code> file. If Pantheon is stopped and restarted without deleting the <code>key</code> file, the same private key is used when Pantheon is restarted.</p>
<p>If a <code>key</code> file exists in the data directory when Pantheon is started, the node is started with the private key in the <code>key</code> file. </p>
<blockquote>
<p><strong>Note</strong> The private key is not encrypted. </p>
</blockquote>
<h2id="node-public-key">Node Public Key</h2>
<p>The node public key is displayed in the log after starting Pantheon. Use the <ahref="#Pantheon-CLI-Syntaxcommands"><code>export-pub-key</code></a> subcommand to export the public key to a file. </p>
<p>The node public key is also referred to as the node ID. The node ID forms part of the <ahref="#Testing-Developing-Nodesprivate-networks">enode URL</a> for a node. </p>
<h2id="specifying-a-custom-node-private-key-file">Specifying a Custom Node Private Key File</h2>
<p>Use the <code>--node-private-key</code> option to specify a custom <code>key</code> file in any location. </p>
<p>If the <code>key</code> file exists, the node is started with the private key in the custom <code>key</code> file. If the custom <code>key</code> file does not exist, a node private key is generated and written to the custom <code>key</code> file.</p>
<p>For example, the following command either reads the node private key from the <code>privatekeyfile</code> or writes the generated private key to the <code>privatekeyfile</code>:</p>
<p>Pantheon uses the network to find and connect to peers. </p>
<h2id="firewalls-and-incoming-connections">Firewalls and Incoming Connections</h2>
<p>The default logging configuration does not list node connection and disconnection messages. </p>
<p>To enable listing of node connection and disconnection messages, specify the command line option <code>--logging=DEBUG</code>. For more verbosity, specify <code>--logging=TRACE</code>. </p>
<p>The console logs connection and disconnection events when the log level is <code>DEBUG</code> or higher. If <code>Successfully accepted connection from ...</code> is displayed, connections are getting through the firewalls. For example:</p>
<preclass="hljs">2018-10-16 12:37:35.479-04:00 | nioEventLoopGroup-3-1 | <spanclass="hljs-builtin-name">INFO</span> | NettyP2PNetwork | Successfully accepted<spanclass="hljs-built_in"> connection </span><spanclass="hljs-keyword">from</span> 0xa979fb575495b8d6db44f750317d0f4622bf4c2aa3365d6af7c284339968eef29b69ad0dce72a4d8db5ebb4968de0e3bec910127f134779fbcb0cb6d3331163c</pre><p>If connections are not getting through the firewalls, ensure the peer discovery port is open on your firewall. </p>
<p>The <code>--p2p-listen</code> option specifies the host and port on which P2P peer discovery listens. The default is <code>127.0.0.1:30303</code>.</p>
<h2id="limiting-peers">Limiting Peers</h2>
<p>Limiting peers reduces the bandwidth used by Pantheon. It also reduces the CPU time and disk access used to manage and respond to peers. </p>
<p>Use the <code>--max-peers</code> command line option to reduce the maximum number of peers. The default is 25.</p>
<p>Use the <code>--max-trailing-peers</code> option to reduce the maximum P2P peer connections for peers that are trailing behind the local chain head. The default is unlimited but the number of trailing peers cannot exceed the value specified by <code>--max-peers</code>.</p>
<p>Trailing peers cannot be used to get new blocks and are more likely to be requesting blocks from you. Limiting trailing peers may reduce the time taken to catch up to the chain head when synchronizing. </p>
<h2id="no-discovery">No Discovery</h2>
<p>The <code>--no-discovery</code> command line option disables P2P peer discovery. Only use this option if you are running a test node or a test network with fixed nodes.</p>
<pclass="page"id="Accounts-for-Testing"></p><h1>Accounts for Testing</h1>
<h3id="accounts-for-testing">Accounts for Testing</h3>
<p>You can use existing accounts for testing by including them in the genesis file for a private network. Alternatively, Pantheon provides predefined accounts in development mode. </p>
<h4id="development-mode">Development Mode</h4>
<p> When you start Pantheon with the <ahref="#Pantheon-CLI-Syntax"><code>--dev-mode</code> command line option</a>, the <code>dev.json</code> genesis file is used by default. </p>
<p> The <code>dev.json</code> genesis file defines the accounts below that can be used for testing. </p>
<blockquote>
<p><strong>Warning</strong> Do not use the following accounts on mainnet or any public network except for testing. The private keys are displayed here so the accounts are not secure. </p>
<li><p>Initial balance : <code>0x90000000000000000000000</code> (2785365088392105618523029504 in decimal)</p>
<h4id="genesis-file">Genesis File</h4>
</li>
</ul>
<p>To use existing test accounts, specify the accounts and balances in a genesis file for your test network. For an example of defining accounts in the genesis file, refer to <ahref="https://github.com/PegaSysEng/pantheon/blob/master/config/src/main/resources/dev.json"><code>dev.json</code></a>.</p>
<p>Use the <ahref="https://github.com/PegaSysEng/pantheon/wiki/Pantheon-CLI-Syntax"><code>--genesis</code> command line option</a> to start Pantheon with the genesis file defining the existing accounts. </p>
<p>Use the <ahref="#Pantheon-CLI-Syntax"><code>--logging</code> command line option</a> to specify the logging verbosity. The <code>--logging</code> option changes the volume of events displayed in the log. </p>
<p>You can provide your own logging configuration using the standard Log4J2 configuration mechanisms. For example, the following Log4J2 configuration is the same as the <ahref="https://github.com/PegaSysEng/pantheon/blob/master/pantheon/src/main/resources/log4j2.xml">default configuration</a> except logging of stack traces for exceptions is excluded.</p>
<spanclass="hljs-tag"></<spanclass="hljs-name">Configuration</span>></span></pre><p>To use your custom configuration, set the environment variable <code>LOG4J_CONFIGURATION_FILE</code> to the location of your configuration file. </p>
<p>If you have more specific requirements, you can create your own <ahref="https://logging.apache.org/log4j/2.x/manual/configuration.html">log4j2 configuration</a>.</p>
<p>For Bash-based executions, you can set the variable for only the scope of the program execution by setting it before starting Pantheon. For example, to set the debug logging and start Pantheon connected to the Rinkeby testnet:</p>
<preclass="hljs">LOG4J_CONFIGURATION_FILE=./debug.xml bin/pantheon --rinkeby</pre><pclass="page"id="Testing-Developing-Nodes"></p><h1>Testing and Developing Nodes</h1>
<h1id="testing-and-developing-nodes">Testing and Developing Nodes</h1>
<h2id="bootnodes">Bootnodes</h2>
<p>Bootnodes are used to initially discover peers. </p>
<h3id="mainnet-and-public-testnets">Mainnet and Public Testnets</h3>
<p>For mainnet and Rinkeby, Pantheon predefines a list of enonde URLs. For Ropsten, bootnodes are specified using the <ahref="#Starting-Pantheonrun-a-node-on-ropsten-testnet"><code>--bootnodes</code> option</a>. </p>
<h3id="private-networks">Private Networks</h3>
<p>To start a bootnode for a private network:</p>
<ol>
<li><p>Export the public key to a file:</p>
<preclass="hljs">pantheon export-pub-key bootnode</pre><p>The node public key is exported to the <code>bootnode</code> file. </p>
</li>
<li><p>Start the bootnode, specifying:</p>
<ul>
<li>An empty string for the <code>--bootnodes</code> option because this is the bootnode. </li>
<li><p>The network ID for your private network. </p>
<p>To specify this bootnode for another node, the enode URL for the <code>--bootnodes</code> option is <code>enode://<id>@<host:port></code> where:</p>
<ul>
<li><code><id></code> is the node public key written to the specified file (<code>bootnode</code> in the above example) excluding the initial 0x. </li>
<li><code><host:port></code> is the host and port the bootnode is listening on for P2P peer discovery. Specified by the <code>--p2p-listen</code> option for the bootnode (default is <code>127.0.0.1:30303</code>).</li>
</ul>
<p>For example, if the <code>--p2p-listen</code> option is not specified and the node public key exported is <code>0xc35c3ec90a8a51fd5703594c6303382f3ae6b2ecb9589bab2c04b3794f2bc3fc2631dabb0c08af795787a6c004d8f532230ae6e9925cbbefb0b28b79295d615f</code></p>
<p><strong>Note</strong> The default host and port for P2P peer discovery is <code>127.0.0.1:30303</code>. The <code>--p2p-listen</code> option can be used to specify a host and port. </p>
</blockquote>
<p>To start a node specifying the bootnode for P2P discovery:</p>
<preclass="hljs">pantheon --datadir=/tmp/pantheon/30301 --p2p-listen=127.0.0.1:30301 --network-id=123 --bootnodes=enode://c35c3ec90a8a51fd5703594c6303382f3ae6b2ecb99bab2c04b3794f2bc3fc2631dabb0c08af795787a6c004d8f532230ae6e9925cbbefb0b28b79295d615f@127.0.0.1:30303</pre><pclass="page"id="Proof-of-Authority"></p><h1>Proof of Authority</h1>
<h2id="proof-of-authority">Proof of Authority</h2>
<p>Pantheon implements the Clique Proof-of-Authority (PoA) consensus protocol. Clique is used by the Rinkeby testnet and can be used for private networks. </p>
<p>In PoA networks, transactions and blocks are validated by approved accounts, known as signers. Signers take turns to create the next block. Existing signers propose and vote to add or remove signers. </p>
<p>Before starting a private network using Clique, create at least one </p>
<p>Specify at least 1 but preferably </p>
<ul>
<li>Must create 1 or more (preferably at least 3) private keys (Pantheon doesn't do account management so probably externally or start nodes with different data directories to get private key)</li>
<li>32 bytes/64 characters of vanity data</li>
<li>signers nX40 characters for each one - left pad with zeros</li>
<li>followed by 65 bytes/130 - usually this is the signature for the block but because this is the genesis block it's unsigned </li>
</ul>
<p>Then need to start network with the nodes specified as initial signers - refer to Node Keys topic. </p>
<p>Process as per Slack DM. Trent getting back to me. </p>
<p>To use Clique in a private network, Pantheon requires a PoA genesis file. When connecting to Rinkeby, Pantheon uses the <ahref="https://github.com/PegaSysEng/pantheon/blob/master/ethereum/core/src/main/resources/rinkeby.json"><code>rinkeby.json</code></a> genesis file in the <code>/pantheon/ethereum/core/src/main/resources</code> directory.</p>
<p>A PoA genesis file defines properties specific to Clique:</p>
<p>To connect to the Rinkeby testnet, start Pantheon with the <code>--rinkeby</code> option. To start a node on a PoA private network, use the <code>--network-id</code> and <code>--genesis</code> options. </p>
<h3id="adding-and-removing-signers">Adding and Removing Signers</h3>
<p>To propose adding or removing signers using the JSON-RPC methods, you must enable the RPC interface using the <ahref="#Pantheon-CLI-Syntaxoptions"><code>--rpc-enabled</code> option</a>. If also using the <ahref="#Pantheon-CLI-Syntaxoptions"><code>--rpc-api</code> option</a>, include <code>CLIQUE</code>.</p>
<p>The JSON-RPC methods to add or remove signers are:</p>
<p>To propose adding a signer, call <code>clique_propose</code> specifying the address of the proposed signer and <code>true</code>. For example, </p>
<preclass="hljs">curl -X POST --data '{"jsonrpc":"2.0","method":"clique_propose","params":["0xFE3B557E8Fb62b89F4916B721be55cEb828dBd73", true], "id":1}' <JSON-RPC-endpoint:port></pre><p>When the next block is created by the signer, a vote is added to the block for the proposed signer. </p>
<p>When more than half of the existing signers propose adding the signer and their votes have been distributed in blocks, the signer is added and can begin signing blocks. </p>
<p>Use <code>clique_getSigners</code> to return a list of the signers and to confirm that your proposed signer has been added. </p>
<preclass="hljs">curl -X POST --data '{"jsonrpc":"2.0","method":"clique_getSigners","params":["latest"], "id":1}' <JSON-RPC-endpoint:port></pre><p>To discard your proposal after confirming the signer was added, call <code>clique_discard</code> specifying the address of the proposed signer. For example:</p>
<preclass="hljs"> curl -X POST --data '{"jsonrpc":"2.0","method":"clique_discard","params":["0xFE3B557E8Fb62b89F4916B721be55cEb828dBd73"], "id":1}' <JSON-RPC-endpoint:port></pre><p>The process for removing a signer is the same as adding a signer except you specify <code>false</code> as the second parameter of <code>clique_propose</code>. </p>
<h4id="epoch-transition">Epoch Transition</h4>
<p>At each epoch transition, all pending votes collected from received blocks are discarded. Existing proposals remain in effect and signers re-add their vote the next time they create a block. </p>
<p>Define the number of blocks between epoch transitions in the genesis file. </p>
<h1id="passing-jvm-options-to-pantheon">Passing JVM Options to Pantheon</h1>
<p>To perform tasks such as attaching a debugger or configuring the garbage collector, pass JVM options to Pantheon. </p>
<p>Pantheon passes the contents of the <code>PANTHEON_OPTS</code> environmental variable to the JVM. Set standard JVM options in the <code>PANTHEON_OPTS</code> variable. </p>
<p>For Bash-based executions, you can set the variable for only the scope of the program execution by setting it before starting Pantheon. For example:</p>
<preclass="hljs">PANTHEON_OPTS=-agentlib:jdwp=transport=dt_socket,server=y,<spanclass="hljs-built_in">suspend</span>=n,address=5005 bin/pantheon --rinkeby</pre><pclass="page"id="Transactions"></p><h1>Creating and Sending Transactions</h1>
<p>You can send signed transactions using the <ahref="https://github.com/PegaSysEng/pantheon/wiki/JSON-RPC-API#eth_sendrawtransaction"><code>eth_sendRawTransaction</code></a> JSON-RPC API method.</p>
<p>These examples describe how to create a signed raw transaction that can be passed to <ahref="https://github.com/PegaSysEng/pantheon/wiki/JSON-RPC-API#eth_sendrawtransaction"><code>eth_sendRawTransaction</code></a>.</p>
<p><strong>Note:</strong> Other libraries (such as <ahref="https://github.com/web3j/web3j">webj3</a> or <ahref="https://github.com/ethereum/ethereumj">ethereumj</a>) and tools (such as <ahref="https://kb.myetherwallet.com/offline/making-offline-transaction-on-myetherwallet.html">MyEtherWallet</a> or <ahref="https://mycrypto.com/">MyCrypto</a>) can also be used to create signed transactions. </p>
</blockquote>
<p>Example JS scripts are provided to create signed raw transaction strings to: </p>
<p>The example JS scripts can be used to create raw transactions to send in the private network created by the <ahref="#Private-Network-Quickstartprivate-network-quickstart-tutorial">Private Network Quickstart</a>. The <code>JSON-RPC endpoint</code> in the examples must be updated to the endpoint for the private network displayed after running the <code>quickstart/runPantheonPrivateNetwork.sh</code> script. </p>
<preclass="hljs">curl -X POST --data <spanclass="hljs-string">'{"jsonrpc":"2.0","method":"eth_sendRawTransaction","params":["raw_transaction_string"],"id":1}'</span><JSON-RPC-endpoint:port></pre><p>Where:</p>
<preclass="hljs">curl -X POST --data <spanclass="hljs-string">'{"jsonrpc":"2.0","method":"eth_sendRawTransaction","params":["0xf86a808203e882520894f17f52151ebef6c7334fad080c5704d77216b732896c6b935b8bbd400000801ca08ce4a6c12f7f273321c5dc03910744f8fb11573fcce8140aa44486d385d22fb3a051f6bcc918bf3f12e06bfccfd1451bea5c517dffee0777ebd50caf177b17f383"],"id":1}'</span> http://localhost:8545</pre><p>All accounts and private keys in the examples are from the <code>dev.json</code> genesis file in the <code>/pantheon/ethereum/core/src/main/resources</code> directory.</p>
// Compiled contract <spanclass="hljs-built_in">hash</span> - can obtain from Remix by clicking the Details button <spanclass="hljs-keyword">in</span> the Compile tab.
// Compiled contract <spanclass="hljs-built_in">hash</span> is value of data parameter <spanclass="hljs-keyword">in</span> the WEB3DEPLOY section
console.log(<spanclass="hljs-string">"Raw transaction string="</span> + rawTxHex); </pre><h2id="eth_call-or-eth_sendrawtransaction">eth_call or eth_sendRawTransaction</h2>
<p>You can interact with contracts using <ahref="#JSON-RPC-APIeth_call">eth_call</a> or <ahref="#JSON-RPC-APIeth_sendrawtransaction">eth_sendRawTransaction</a>. </p>
<table>
<thead>
<tr>
<th>eth_call</th>
<th>eth_sendRawTransaction</th>
</tr>
</thead>
<tbody>
<tr>
<td>Read-only</td>
<td>Write</td>
</tr>
<tr>
<td>Invokes contract function locally</td>
<td>Broadcasts to network</td>
</tr>
<tr>
<td>Does not change state of blockchain</td>
<td>Updates blockchain (for example, transfers ether between accounts)</td>
</tr>
<tr>
<td>Does not consume gas</td>
<td>Requires gas</td>
</tr>
<tr>
<td>Synchronous</td>
<td>Asynchronous</td>
</tr>
<tr>
<td>Return value of contract function available immediately</td>
<td>Returns transaction hash only. Possible transaction may not be included in a block (for example, if the gas price is too low)</td>
<pclass="page"id="Account-Management"></p><h1>Using Wallets for Account Management</h1>
<h2id="using-wallets-for-account-management">Using Wallets for Account Management</h2>
<p>Pantheon does not implement private key management. Use third-party tools (for example, <ahref="https://consensys.zendesk.com/hc/en-us/articles/360004685212-Generating-MetaMask-Wallet-New-UI-">MetaMask</a> and <ahref="https://web3j.io/">web3j</a>) for creating accounts. </p>
<p>In Pantheon, you can use the JSON-RPC methods:</p>
<li><ahref="#JSON-RPC-APIeth_sendrawtransaction">eth_sendRawTransaction</a> to transfer ether or create and interact with contracts (for more information, refer to <ahref="#Transactionstransactions">Transactions</a>). </li>
<p>Start Pantheon with the following options to enable mining: </p>
<preclass="hljs">bin/pantheon --miner-enabled --miner-coinbase <account></pre><p>Where <code><account></code> is the account to which mining rewards are to be paid. For example, <code>fe3b557e8fb62b89f4916b721be55ceb828dbd73</code>.</p>
<p>JSON-RPC API methods for mining are: </p>
<ul>
<li><ahref="#JSON-RPC-APIminer_start"><code>miner_start</code></a> to start mining. </li>
<li><ahref="#JSON-RPC-APIminer_stop"><code>miner_stop</code></a> to stop mining. </li>
<li><ahref="#JSON-RPC-APIeth_mining"><code>eth_mining</code></a> to determine whether the client is actively mining new blocks. </li>
<p>Pantheon supports event publication and subscription with the RPC Pub/Sub methods. Using these methods, your client can wait for events instead of polling for them. You invoke the RPC Pub/Sub methods over WebSockets. (Note that these methods cannot be called over HTTP.)</p>
<li>Your client calls <code>eth_subscribe</code> to create a subscription that waits for particular events.</li>
<li>Your client calls <code>eth_unsubscribe</code> to cancel an existing subscription.</li>
<li>The server invokes <code>eth_subscription</code> to publish (report) notifications of event occurrences to your client. Your client never calls this method.</li>
<p>When you subscribe to particular events (using <code>eth_subscribe</code>), the node returns a subscription ID. For each matching event that occurs, the node uses <code>eth_subscription</code> to return a notification with relevant data and the subscription ID.</p>
<p>Subscriptions require a full duplex connection, so you need to invoke the RPC Pub/Sub methods over WebSockets. You can use a tool such as <ahref="https://github.com/websockets/wscat">wscat</a>, a Node.js based command-line tool.</p>
<p>Subscriptions are coupled to a connection. If the connection is closed, all subscriptions that have been created over this connection will be removed.</p>
<p>The types of events that you can subscribe to are:</p>
<p>This subscription sends a notification each time a new header is appended to the chain. This includes chain reorganizations. You can use the bloom filter to determine if the block contains logs of interest. In case of a chain reorganization the subscription will emit all new headers for the new chain. Therefore the subscription can emit multiple headers on the same height.</p>
<p>You can filter blocks using elements from the <ahref="https://github.com/PegaSysEng/pantheon/wiki/JSON-RPC-API#block-object">Block Object</a>. For example, you can use the <code>logsBloom</code> parameter to filter blocks containing logs of interest to you.</p>
<p>Returns logs included in new imported blocks and match the given filter criteria. In a chain reorganization, previous sent logs from the old chain are resent with the removed property set to <code>true</code>. Logs from transactions included in the new chain are sent. Therefore a subscription can send logs for the same transaction multiple times.</p>
<p>Returns the hash of transactions in the pending state and signed with a key available in the node. If a transaction that was previously part of the canonical chain isn't in the new canonical chain after a reorganization, it will be sent again.</p>
<p>Indicates whether the node is currently synchronizing. The result can either be a <code>boolean</code> indicating that the synchronization has finished (<code>false</code>) or an <code>object</code> with various progress indicators, indicating that synchronization is in progress.</p>
<p>Notifications are sent for current events only, not past events.</p>
<p>Notifications are stored in an internal buffer to be sent to the client. If the client falls behind and the number of buffered notifications reaches a limit (currently 10k), the connection will be closed. Keep in mind that subscribing to certain events can cause a flood of notifications; for example, listening for all logs when the node synchronizes.</p>
<p><code>eth_unsubscribe</code> cancels an existing subscription. It returns a boolean indicating whether the subscription was cancelled successfully.</p>
<blockquote>
<p><strong>Note:</strong> Only the connection that created a subscription is able to unsubscribe from it. If another connection tries to unsubscribe, it will receive a <code>SubscriptionNotFound</code> response with no information about existing subscriptions.</p>
</blockquote>
<h4id="parameters">Parameters</h4>
<p><code>subscriptionID</code> : - The ID of the subscription to cancel. You receive this ID from <code>eth_subscribe</code>.</p>
<h4id="returns">Returns</h4>
<p><code>result</code> : <code>boolean</code> - <code>true</code> if the subscription was cancelled successfully; otherwise <code>false</code>.</p>
<p><code>eth_subscription</code> is the method the node uses to publish (report) notifications of event occurrences. You do not call this method. The node invokes <code>eth_subscription</code> to return a notification with relevant data and the subscription ID for each matching event that occurs.</p>
<p><code>subscription</code> : <code>string</code> - The subscription ID. </p>
<p><code>result</code> : <code>object</code> - An object containing relevant block data. For example, for pending transactions the returned data is a transaction hash. For detailed information on this data, see <ahref="https://github.com/PegaSysEng/pantheon/wiki/JSON-RPC-API#block-object">Block Object</a>.</p>
<h2id="pantheon-command-line-interface-reference">Pantheon Command Line Interface Reference</h2>
<p>This reference describes the syntax of the Pantheon Command Line Interface (CLI) options and subcommands.</p>
<preclass="hljs">pantheon <spanclass="hljs-string">[OPTIONS]</span><spanclass="hljs-string">[COMMAND]</span></pre><p>Runs the Pantheon Ethereum full node client.</p>
<dd>List of node IDs to ban from the P2P network. The node ID is the public key of the node. The banned node IDs can be specified with or without the <code>0x</code> prefix.</dd>
><strong>Note</strong> This option is only available from v0.8.2 or when <ahref="#Installation">building from source</a>.
<dd>List of comma-separated enode URLs for P2P discovery bootstrap. </dd>
<dd>When connecting to mainnet and Rinkeby, the default is a predefined list of enode URLs. Specify bootnodes when <ahref="https://github.com/PegaSysEng/pantheon/wiki/Starting-Pantheon#run-a-node-on-ropsten-testnet">connecting to Ropsten</a> or a <ahref="https://github.com/PegaSysEng/pantheon/wiki/Testing-Developing-Nodes#bootnodes">private network.</a></dd>
<dd>The path to the TOML configuration file. The default is <code>none</code>. The TOML file is composed of key/value pairs. Each key is the same as the corresponding CLI option name without the leading dashes (<code>--</code>). The config option is not used in the config file. Values must be treated according to TOML specifications for string, numbers, arrays and Booleans.
><strong>Note:</strong> This option is not used when running Pantheon from the <ahref="#Run-Docker-Imagecustom-configuration-file">Docker image</a>.
<dd>The path to the Pantheon data directory. The default location is the <code>/build/distributions/pantheon-<version></code> directory in the Pantheon installation directory.</dd>
Set this option to <code>true</code> to run in development mode. For example, specify this option to perform CPU mining more easily in a private test network. In development mode, a custom genesis configuration specifies the chain ID. When using this option, also set the <code>--network-id</code> option to the network you use for development. Default is <code>false</code>.
><strong>Note:</strong> The <code>--dev-mode</code> option overrides the <code>--genesis</code> option. If both are specified, the development mode configuration is used.<br><br>
<dd>The path to the genesis file. The default is the embedded genesis file for the Ethereum mainnet. When using this option, it is recommended to also set the <code>--network-id</code> option.</dd>
><strong>Note:</strong> The <code>--genesis</code> option is overriden by the <code>--dev-mode</code> option. If both are specified, the specified genesis file is ignored and the development mode configuration used.
<dd>Specifies the maximum P2P peer connections for peers that are trailing behind the local chain head. The default is unlimited but the number of trailing peers cannot exceed the value specified by <code>--max-peers</code>.</dd>
<dd><code><PATH></code> is the path of the private key file of the node. The default is the key file in the data directory. If no key file exists, a key file containing the generated private key is created; otherwise, the existing key file specifies the node private key.
<dd>Uses the Rinkeby test network. Default is <code>false</code>.</dd>
<dt><code>--ropsten</code></dt>
<dd>Uses the Ropsten test network. Default is <code>false</code>.</dd>
><strong>Note</strong> This option is only available when <ahref="#Installation">building from source</a>. For v0.8.1, refer <ahref="#Starting-Pantheonrun-a-node-on-ropsten-testnet">here</a>.
<dd>Comma-separated APIs to enable on the JSON-RPC channel. When you use this option, the <code>--rpc-enabled</code> option must also be specified. The available API options are: <code>ETH</code>, <code>NET</code>, <code>WEB3</code>, <code>CLIQUE</code>, <code>IBFT</code>, <code>DEBUG</code>, and <code>MINER</code>. The default is: <code>ETH</code>, <code>NET</code>, <code>WEB3</code>, <code>CLIQUE</code>, <code>IBFT</code>.</dd>
><strong>Note:</strong> IBFT is not currently supported. Support for IBFT is in active development.
Specifies domain URLs for CORS validation. Domain URLs must be enclosed in double quotes and comma-separated.
Listed domains will be allowed access to node data (whitelisted). If your client interacts with Pantheon using a browser app (such as Remix using a direct connection or a block explorer), you must whitelist the client domains. For example, the following allows Remix to interact with your Pantheon node without using MetaMask:
<strong>Note:</strong> MetaMask runs as native code so does not require CORS validation. If Remix is connecting to the node through MetaMask, it also does not require CORS validation.
The default value is <code>"none"</code>. If you don't whitelist any domains, you won't be able to use webapps to interact with your Pantheon node.
You can whitelist one or more domains with a comma-separated list. For example:
For development purposes, you can use <code>"all"</code> to accept requests from any domain, but we don't recommend this for production code.
<dd>Comma-separated APIs to enable on Websockets channel. When you use this option, the <code>--ws-enabled</code> option must also be specified. The available API options are: <code>ETH</code>, <code>NET</code>, <code>WEB3</code>, <code>CLIQUE</code>, <code>IBFT</code>, <code>DEBUG</code>, and <code>MINER</code>. The default is: <code>ETH</code>, <code>NET</code>, <code>WEB3</code>, <code>CLIQUE</code>, <code>IBFT</code>.</dd>
<p>The Pantheon JSON-RPC API uses the <ahref="http://json.org/">JSON</a> (RFC 4627) data format, which can represent objects and data fields as collections of name/value pairs, in a relatively readable, hierarchical form. Values have specific data types such as QUANTITIES (decimal integers, hexadecimal numbers, strings) and UNFORMATTED DATA (byte arrays, account addresses, hashes, and bytecode arrays).</p>
<p>RPC is the remote procedure call protocol (RFC 1831), which is stateless and transport agnostic in that the concepts can be used within the same process, over sockets, over HTTP, or in many various message passing environments.</p>
<h2id="using-the-pantheon-json-rpc-api">Using the Pantheon JSON-RPC API</h2>
<h3id="endpoint-address-and-port">Endpoint Address and Port</h3>
<p>In this reference, the placeholder
<code><JSON-RPC-http-endpoint:port></code> and <code><JSON-RPC-ws-endpoint:port></code> means an endpoint (IP address and port) of the JSON-RPC service of a Pantheon node respectively for http endpoint and for WebSocket endpoint.
To activate JSON-RPC using http or WebSocket, see <ahref="https://github.com/PegaSysEng/pantheon/wiki/Pantheon-CLI-Syntax">--rpc-listen and --ws-listen options in the CLI documentation</a>.</p>
<p>The transport attributes are:</p>
<ul>
<li>HTTP: Listens by default on port 8545</li>
<li>WebSockets: Listens by default on port 8546</li>
</ul>
<h3id="http-and-websocket-requests">HTTP and WebSocket Requests</h3>
<h4id="http">HTTP</h4>
<p>To make RPC over HTTP requests, you can use the <code>curl</code> tool, available in many systems using <ahref="https://curl.haxx.se/download.html">curl source code or pre-compiled packages</a>.</p>
<preclass="hljs">curl -X POST --data '{"jsonrpc":"2.0","method":"web3_clientVersion","params":[],"id":53}' <JSON-RPC-http-endpoint:port></pre><h4id="websockets">WebSockets</h4>
<p>To make requests over WebSockets, this reference uses <ahref="https://github.com/websockets/wscat">wscat</a>, a Node.js based command-line tool.</p>
<p>First connect to the WebSockets server using <code>wscat</code> (you only need to connect once per session):</p>
<preclass="hljs">wscat -c ws://<JSON-RPC-ws-endpoint:port></pre><p>After the connection is established, the terminal will display a '>' prompt. Send individual requests as a JSON data package at each prompt:</p>
<p>When you make requests that might have different results depending on the block accessed, the block parameter specifies the block. Several methods, such as <ahref="#eth_gettransactionbyblocknumberandindex">eth_getTransactionByBlockNumberAndIndex</a>, have a block parameter.</p>
<p>The block parameter can have the following values:</p>
<ul>
<li><code>blockNumber</code> : <code>quantity</code> - Block number. Can be specified in hexadecimal or decimal. 0 represents the genesis block.</li>
<li><code>pending</code> : <code>tag</code> - Last block mined plus pending transactions. Use only with <ahref="#eth_gettransactioncount">eth_getTransactionCount</a>. </li>
<p>Use <ahref="#eth_sendrawtransaction"><code>eth_sendRawTransaction</code></a> to send signed transactions; <code>eth_sendTransaction</code> is not implemented. </p>
<p>Use third-party wallets for <ahref="#Account-Management">account management</a>. </p>
<h3id="protocols">Protocols</h3>
<p>Pantheon does not implement the Whisper and Swarm protocols. </p>
<preclass="hljs">{<spanclass="hljs-attr">"jsonrpc"</span>:<spanclass="hljs-string">"2.0"</span>,<spanclass="hljs-attr">"method"</span>:<spanclass="hljs-string">"web3_clientVersion"</span>,<spanclass="hljs-attr">"params"</span>:[],<spanclass="hljs-attr">"id"</span>:<spanclass="hljs-number">53</span>}</pre><p>For an explanation of how to make an HTTP or WebSockets request using this data, see <ahref="#http-and-websocket-requests">HTTP and WebSocket Requests</a>.</p>
<p>Returns a <ahref="https://en.wikipedia.org/wiki/SHA-3">SHA3</a> hash of the specified data. The result value is a <ahref="https://keccak.team/keccak.html">Keccak-256</a> hash, not the standardized SHA3-256.</p>
<p>To set a coinbase address, call the pantheon CLI with the <code>--miner-coinbase</code> 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:</p>
<p>Indicates whether the client is actively mining new blocks. Mining is paused while the client synchronizes with the network regardless of command settings or methods called. </p>
<p><strong>NOTE:</strong> This method returns an empty object because Pantheon <ahref="#account-management-not-supported-by-pantheon">does not support account management</a>.</p>
<p>Returns the index of the current block the client is processing.</p>
<h5id="parameters">Parameters</h5>
<p>None</p>
<h5id="returns">Returns</h5>
<p><code>result</code> : <em>QUANTITY</em> - Hexadecimal integer representing the 0-based index of the block that the client is currently processing.</p>
<h5id="request">Request</h5>
<preclass="hljs">curl -X POST --data '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":51}' <JSON-RPC-endpoint:port></pre><h5id="result">Result</h5>
<p>Returns the account balance of the specified address.</p>
<h5id="parameters">Parameters</h5>
<p><code>DATA</code> - 20-byte account address from which to retrieve the balance.</p>
<p><code>QUANTITY|TAG</code> - Integer representing a block number or one of the string tags <code>latest</code>, <code>earliest</code>, or <code>pending</code>, as described in <ahref="#block-parameter">Block Parameter</a>.</p>
<h5id="returns">Returns</h5>
<p><code>result</code> : <em>QUANTITY</em> - Integer value of the current balance in wei.</p>
<h5id="request">Request</h5>
<preclass="hljs">curl -X POST --data '{"jsonrpc":"2.0","method":"eth_getBalance","params":["0xdd37f65db31c107f773e82a4f85c693058fef7a9", "latest"],"id":53}' <JSON-RPC-endpoint:port></pre><h5id="result">Result</h5>
<p>Returns the value of a storage position at a specified address.</p>
<h5id="parameters">Parameters</h5>
<p><code>DATA</code> - A 20-byte storage address.</p>
<p><code>QUANTITY</code> - Integer index of the storage position.</p>
<p><code>QUANTITY|TAG</code> - Integer representing a block number or one of the string tags <code>latest</code>, <code>earliest</code>, or <code>pending</code>, as described in <ahref="#block-parameter">Block Parameter</a>.</p>
<h5id="returns">Returns</h5>
<p><code>result</code> : <em>DATA</em> - The value at the specified storage position.</p>
<h5id="request">Request</h5>
<p>Calculating the correct position depends on the storage you want to retrieve.</p>
<preclass="hljs">curl -X POST --data '{"jsonrpc":"2.0","method": "eth_getStorageAt","params": ["0x3B3F3E","0x0","latest"],"id": 53}' <JSON-RPC-endpoint:port></pre><h5id="result">Result</h5>
<p><code>QUANTITY|TAG</code> - Integer representing a block number or one of the string tags <code>latest</code>, <code>earliest</code>, or <code>pending</code>, as described in <ahref="#block-parameter">Block Parameter</a>.</p>
<h5id="returns">Returns</h5>
<p><code>result</code> : <em>QUANTITY</em> - Integer representing the number of transactions sent from the specified address.</p>
<h5id="request">Request</h5>
<preclass="hljs">curl -X POST --data '{"jsonrpc":"2.0","method":"eth_getTransactionCount","params":["0xc94770007dda54cF92009BFF0dE90c06F603a09f","latest"],"id":1}' <JSON-RPC-endpoint:port></pre><h5id="result">Result</h5>
<p>Returns the number of transactions in a block matching the specified block number.</p>
<h5id="parameters">Parameters</h5>
<p><code>QUANTITY|TAG</code> - Integer representing a block number or one of the string tags <code>latest</code>, <code>earliest</code>, or <code>pending</code>, as described in <ahref="#block-parameter">Block Parameter</a>.</p>
<h5id="returns">Returns</h5>
<p><code>result</code> : <em>QUANTITY</em> - Integer representing the number of transactions in the specified block.</p>
<h5id="request">Request</h5>
<preclass="hljs">curl -X POST --data '{"jsonrpc":"2.0","method":"eth_getBlockTransactionCountByNumber","params":["0xe8"],"id":51}' <JSON-RPC-endpoint:port></pre><h5id="result">Result</h5>
<p>Returns the number of uncles in a block matching the specified block number.</p>
<h5id="parameters">Parameters</h5>
<p><code>QUANTITY|TAG</code> - Integer representing either the 0-based index of the block within the blockchain, or one of the string tags <code>latest</code>, <code>earliest</code>, or <code>pending</code>, as described in <ahref="#block-parameter">Block Parameter</a>.</p>
<h5id="returns">Returns</h5>
<p><code>result</code> : <em>QUANTITY</em> - Integer representing the number of uncles in the specified block.</p>
<h5id="request">Request</h5>
<preclass="hljs">curl -X POST --data '{"jsonrpc":"2.0","method":"eth_getUncleCountByBlockNumber","params":["0xe8"],"id":1}' <JSON-RPC-endpoint:port></pre><h5id="result">Result</h5>
<p><code>QUANTITY|TAG</code> - Integer representing a block number or one of the string tags <code>latest</code>, <code>earliest</code>, or <code>pending</code>, as described in <ahref="#block-parameter">Block Parameter</a>.</p>
<h5id="returns">Returns</h5>
<p><code>result</code> : <em>DATA</em> - Code stored at the specified address.</p>
<h5id="request">Request</h5>
<preclass="hljs">curl -X POST --data '{"jsonrpc":"2.0","method":"eth_getCode","params":["0xa50a51c09a5c451c52bb714527e1974b686d8e77", "latest"],"id":53}' <JSON-RPC-endpoint:port></pre><h5id="result">Result</h5>
<p>You can interact with contracts using <ahref="#Transactionseth_call-or-eth_sendrawtransaction">eth_sendRawTransaction or eth_call</a>.</p>
<p>To avoid exposing your private key, create signed transactions offline and send the signed transaction data using this method. For information on creating signed transactions and using <code>eth_sendRawTransaction</code>, refer to <ahref="#Transactions">Using Pantheon</a>. </p>
<p><em>QUANTITY|TAG</em> - Integer representing a block number or one of the string tags <code>latest</code>, <code>earliest</code>, or <code>pending</code>, as described in <ahref="#block-parameter">Block Parameter</a>.</p>
<h5id="returns">Returns</h5>
<p><code>result</code> (<em>DATA</em>) - Return value of the executed contract.</p>
<p>Generates and returns an estimate of how much gas is necessary to allow the transaction to complete. (Per Etherscan: gas price * gas used.) The transaction is added to the blockchain. The estimate may be significantly more than the amount of gas actually used by the transaction for reasons including EVM mechanics and node performance.</p>
<h5id="parameters">Parameters</h5>
<blockquote>
<p><strong>NOTE:</strong> Parameters are the same as the eth_call parameters, except that all properties are optional. If you do not specify a <code>gas</code> limit, Pantheon uses the gas limit from the pending block as an upper bound. As a result, the returned estimate might not be enough to execute the call or transaction when the amount of gas is higher than the pending block's gas limit.</p>
<p><em>QUANTITY|TAG</em> - Integer representing a block number or one of the string tags <code>latest</code>, <code>earliest</code>, or <code>pending</code>, as described in <ahref="#block-parameter">Block Parameter</a>.</p>
<p>Returns information about the block by hash.</p>
<h5id="parameters">Parameters</h5>
<p><code>DATA</code> - 32-byte hash of a block.</p>
<p><code>Boolean</code> - If <code>true</code>, returns the full <ahref="#transaction-object">transaction objects</a>; if <code>false</code>, returns the transaction hashes.</p>
<p>Returns information about a block by block number.</p>
<h5id="parameters">Parameters</h5>
<p><code>QUANTITY|TAG</code> - Integer representing a block number or one of the string tags <code>latest</code>, <code>earliest</code>, or <code>pending</code>, as described in <ahref="#block-parameter">Block Parameter</a>.</p>
<p><code>Boolean</code> - If <code>true</code>, returns the full <ahref="#transaction-object">transaction objects</a>; if <code>false</code>, returns only the hashes of the transactions.</p>
<p>Returns transaction information for the specified block hash and transaction index position.</p>
<h5id="parameters">Parameters</h5>
<p><code>DATA</code> - 32-byte hash of a block.</p>
<p><code>QUANTITY</code> - Integer representing the transaction index position.</p>
<h5id="returns">Returns</h5>
<p>Object - <ahref="#transaction-object">Transaction object</a>, or <code>null</code> when no transaction is found.</p>
<h5id="request">Request</h5>
<p>This request returns the 3rd transaction in the 82990 block on the Ropsten testnet. You can also view this <ahref="https://ropsten.etherscan.io/txs?block=82990">block</a> and <ahref="https://ropsten.etherscan.io/tx/0xfc766a71c406950d4a4955a340a092626c35083c64c7be907060368a5e6811d6">transaction</a> on Etherscan. </p>
<p><strong>Note:</strong> You must be synchronized to at least the block containing the transaction for the request to return it. </p>
<preclass="hljs">curl -X POST --data '{"jsonrpc":"2.0","method":"eth_getTransactionByBlockHashAndIndex","params":["0xbf137c3a7a1ebdfac21252765e5d7f40d115c2757e4a4abee929be88c624fdb7", "0x2"], "id":1}' <JSON-RPC-endpoint:port></pre><h5id="result">Result</h5>
<p>Returns transaction information for the specified block number and transaction index position.</p>
<h5id="parameters">Parameters</h5>
<p><code>QUANTITY|TAG</code> - Integer representing a block number or one of the string tags <code>latest</code>, <code>earliest</code>, or <code>pending</code>, as described in <ahref="#block-parameter">Block Parameter</a>.</p>
<p><code>QUANTITY</code> - The transaction index position.</p>
<h5id="returns">Returns</h5>
<p>Object - <ahref="#transaction-object">Transaction object</a>, or <code>null</code> when no transaction is found.</p>
<h5id="request">Request</h5>
<p>This request returns the 3rd transaction in the 82990 block on the Ropsten testnet. You can also view this <ahref="https://ropsten.etherscan.io/txs?block=82990">block</a> and <ahref="https://ropsten.etherscan.io/tx/0xfc766a71c406950d4a4955a340a092626c35083c64c7be907060368a5e6811d6">transaction</a> on Etherscan. </p>
<p><strong>Note:</strong> You must be synchronized to at least the block containing the transaction for the request to return it.</p>
<preclass="hljs">curl -X POST --data '{"jsonrpc":"2.0","method":"eth_getTransactionByBlockNumberAndIndex","params":["82990", "0x2"], "id":1}' <JSON-RPC-endpoint:port></pre><h5id="result">Result</h5>
<p>Creates a topic filter with the specified options to notify (log) when the state changes. To determine whether the state has changed, call <ahref="#eth_getfilterchanges">eth_getFilterChanges</a>.</p>
<p><strong>Note:</strong> Topics are order-dependent. A transaction with a log containing topics <code>[A, B]</code> would be matched with the following topic filters:</p>
<ul>
<li>[] - Match any topic</li>
<li>[A] - Match A in first position (and any topic thereafter)</li>
<li>[null, B] - Match any topic in first position AND B in second position (and any topic thereafter)</li>
<li>[A, B] - Match A in first position AND B in second position (and any topic thereafter)</li>
<li>[[A, B], [A, B]] - Match (A OR B) in first position AND (A OR B) in second position (and any topic thereafter)</li>
</ul>
<p>For example, params could be specified as follows:</p>
<p>Creates a filter in the node that notifies when a new block arrives. To determine whether the state has changed, call <ahref="#eth_getfilterchanges">eth_getFilterChanges</a>.</p>
<p><code>QUANTITY</code> - Hexadecimal integer filter ID. Each time you call this method, it creates a new filter, and the index is incremented by 1.</p>
<p>Creates a filter in the node that notifies when new pending transactions arrive. To check if the state has changed, call <ahref="#eth_getfilterchanges">eth_getFilterChanges</a>.</p>
<p><code>QUANTITY</code> - Hexadecimal integer filter ID. Each time you call this method, it creates a new filter, and the index is incremented by 1.</p>
<p>Uninstalls a filter with the specified ID. This method should always be called when notification is no longer needed. Note that filters time out when they are not requested with <ahref="#eth_getfilterchanges">eth_getFilterChanges</a> for a period of time.</p>
<p><code>result</code> : <code>Array of Object</code> - List of logs, or an empty array if nothing has changed since the last poll.</p>
<ul>
<li><p>For filters created with <code>eth_newBlockFilter</code>, returns 32-byte <em>DATA</em> block hashes; for example <code>["0x3454645634534..."]</code>.</p>
</li>
<li><p>For filters created with <code>eth_newPendingTransactionFilter</code>, returns transaction hashes (32-byte <em>DATA</em>); for example <code>["0x6345343454645..."]</code>.</p>
</li>
<li><p>For filters created with <code>eth_newFilter</code>, returns <ahref="#log-object">log objects</a>. </p>
</li>
</ul>
<h5id="request">Request</h5>
<preclass="hljs">curl -X POST --data '{"jsonrpc":"2.0","method":"eth_getFilterChanges","params":["0xa"]:"id":53}' <JSON-RPC-endpoint:port></pre><h5id="result">Result</h5>
<p>The following response indicates that nothing has changed since the last poll:</p>
<p>The request above returns the logs for the 82893 block on the Ropsten testnet. You can also view this <ahref="https://ropsten.etherscan.io/block/82983">block</a> on Etherscan. </p>
<p><strong>Note:</strong> You must be synchronised to at least the requested block for the request to return the logs.</p>
<preclass="hljs">curl -X POST --data '{"jsonrpc":"2.0","method":"eth_getLogs","params":[{"blockhash":"0x677bf4b962464e6dfd548d6a30b6c703dd78c7cc3602825a7013a6e90a001d2a"}], "id":1}' <JSON-RPC-endpoint:port></pre><h5id="result">Result</h5>
<p><code>quantity|tag</code> - Integer representing a block number or one of the string tags <code>latest</code>, <code>earliest</code>, or <code>pending</code>, as described in <ahref="#default-block-parameter">Default Block Parameter</a>. </p>
<h5id="returns">Returns</h5>
<p><code>result: array of data</code> - List of 20-byte addresses of signers. </p>
<h5id="request">Request</h5>
<preclass="hljs">curl -X POST --data '{"jsonrpc":"2.0","method":"clique_getSigners","params":["latest"], "id":1}' <JSON-RPC-endpoint:port></pre><h5id="result">Result</h5>
<p>Attempts to run the transaction as it was executed on the network. It will replay transactions that might already have been executed before it attempts to execute the transaction that corresponds to the specified hash.</p>
<p>You can use this method with tools such as Remix when you want to execute a transaction step-by-step.</p>
<h5id="parameters">Parameters</h5>
<p><code>transactionHash</code> : <code>data</code> - The transaction hash.</p>
<p><code>options</code> : <code>string</code> - (Optional) Specifies request options as follows:</p>
<ul>
<li><code>disableStorage</code> : <code>BOOL</code> - <code>true</code> disables storage capture. The default is <code>false</code>.</li>
<li><code>disableMemory</code> : <code>BOOL</code> - <code>true</code> disables memory capture. The default is <code>false</code>.</li>
<li><code>disableStack</code> : <code>BOOL</code> - <code>true</code> disables stack capture. The default is <code>false</code>.</li>
<li><code>tracer</code> : <code>STRING</code> - A tracer object that enables JavaScript-based transaction tracing. If you specify a tracer object, the previous four arguments are ignored. A tracer object has two methods, <code>step</code> and <code>result</code>:<ul>
<li><code>step</code> is a function that takes two arguments, <code>log</code> and <code>db</code>. This function is called for each step of the EVM, or when an error occurs, as the specified transaction is traced.</li>
<li><code>log</code> has the following fields:<ul>
<li><code>pc</code> : <code>number</code> - The current program counter.</li>
<li><code>op</code> : <code>object</code> - An <code>OpCode</code> object representing the current opcode.</li>
<li><code>gas</code> : <code>number</code> - The amount of gas remaining.</li>
<li><code>gasPrice</code> : <code>number</code> - The cost in wei of each unit of gas.</li>
<li><code>memory</code> : <code>object</code> - A structure representing the contract's memory space.</li>
<li><code>stack</code> : <code>array[big.Int]</code> - The EVM execution stack.</li>
<li><code>depth</code> : <code>number</code> - The execution depth.</li>
<li><code>account</code> : <code>data</code> - The address of the account executing the current operation.</li>
<li><code>err</code> : If an error occured, this field contains information about the error. If <code>err</code> is non-null, you can ignore all other fields.</li>
</ul>
</li>
</ul>
</li>
<li><code>timeout</code> : <code>STRING</code> - A duration string that overrides the default timeout of 5 seconds for JavaScript-based tracing calls. A duration string is a signed sequence of decimal numbers, each with an optional fraction and a unit suffix, such as "300ms", "-1.5h" or "2h45m". Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h".</li>
</ul>
<h5id="returns">Returns</h5>
<p>A <code>tracer</code> object, as described above.</p>
<h5id="request">Request</h5>
<preclass="hljs">curl -X POST --data '{"jsonrpc":"2.0","method":"debug_traceTransaction","params”:[“0xaaaaaaaaaaaaaaaaaaa”,{“disableStorage":true}],"id”:1}' <JSON-RPC-endpoint:port></pre><h5id="result">Result</h5>
<preclass="hljs">{...}</pre><hr>
<h4id="miner_start">miner_start</h4>
<p>Starts the CPU mining process on the client.</p>
<h5id="parameters">Parameters</h5>
<p>None</p>
<h5id="returns">Returns</h5>
<p><code>result</code> : <code>boolean | integer</code> - <code>true</code> if the mining start request was received successfully; otherwise returns an error. An example of an error condition would be when a coinbase has not been specified.</p>
<h5id="request">Request</h5>
<preclass="hljs">curl -X POST --data '{"jsonrpc":"2.0","method":"miner_start","params":[],"id":1}' <JSON-RPC-endpoint:port></pre><h5id="result">Result</h5>
<preclass="hljs">{...}</pre><hr>
<h4id="miner_stop">miner_stop</h4>
<p>Stops the CPU mining process on the client.</p>
<h5id="parameters">Parameters</h5>
<p>None</p>
<h5id="returns">Returns</h5>
<p><code>result</code> : <code>boolean | integer</code> - <code>true</code> if the mining stop request was received successfully; otherwise returns an error. An example of an error condition would be when a coinbase has not been specified.</p>
<h5id="request">Request</h5>
<preclass="hljs">curl -X POST --data '{"jsonrpc":"2.0","method":"miner_stop","params":[],"id":1}' <JSON-RPC-endpoint:port></pre><h5id="result">Result</h5>
<preclass="hljs">{...}</pre><hr>
<h2id="objects">Objects</h2>
<p>The following objects are parameters for or returned by JSON-RPC Methods:</p>
<td>Integer block number or <code>latest</code>, <code>pending</code>, <code>earliest</code>. See <ahref="#block-parameter">Block Parameter</a>. Default is <code>latest</code>.</td>
<td>Integer block number or <code>latest</code>, <code>pending</code>, <code>earliest</code>. See <ahref="#block-parameter">Block Parameter</a>. Default is <code>latest</code>.</td>
<td>Hash of block for which to return logs. If <code>blockhash</code> is specified, <code>fromBlock</code> and <code>toBlock</code> cannot be specified.</td>
<p>Returned by <ahref="#eth_getfilterchanges">eth_getFilterChanges</a> and <ahref="#transaction-receipt-object">transaction receipt objects</a> can contain an array of log objects. </p>
<td>Index position of transaction from which log was created. <code>null</code> when log is pending.</td>
</tr>
<tr>
<td><code>transactionHash</code></td>
<tdstyle="text-align:center">Data, 32 bytes</td>
<td>Hash of transaction from which log was created. <code>null</code> when log is pending.</td>
</tr>
<tr>
<td><code>blockHash</code></td>
<tdstyle="text-align:center">Data, 32 bytes</td>
<td>Hash of block in which log included. <code>null</code> when log is pending.</td>
</tr>
<tr>
<td><code>blockNumber</code></td>
<tdstyle="text-align:center">Quantity</td>
<td>Number of block in which log included. <code>null</code> when log is pending.</td>
</tr>
<tr>
<td><code>address</code></td>
<tdstyle="text-align:center">Data, 20 bytes</td>
<td>Address from which log originated.</td>
</tr>
<tr>
<td><code>data</code></td>
<tdstyle="text-align:center">Data</td>
<td>Non-indexed arguments of log.</td>
</tr>
<tr>
<td><code>topics</code></td>
<tdstyle="text-align:center">Array of Data, 32 bytes each</td>
<td>0 to 4 indexed log arguments. In Solidity, the first topic is the hash of the signature of the event (for example, <code>Deposit(address, bytes32, unit256)</code>) except you declare the event with an anonymous specifier.) </td>
<p>Returned by <ahref="#eth_gettransactionbyhash">eth_getTransactionByHash</a>, <ahref="#eth_gettransactionbyblockhashandindex">eth_getTransactionByBlockHashAndIndex</a>, and <ahref="#eth_gettransactionbyblocknumberandindex">eth_getTransactionsByBlockNumberAndIndex</a>.</p>
<table>
<thead>
<tr>
<th>Key</th>
<thstyle="text-align:center">Type</th>
<th>Value</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>blockHash</code></td>
<tdstyle="text-align:center">Data, 32 bytes</td>
<td>Hash of block containing this transaction. <code>null</code> when transaction is pending.</td>
</tr>
<tr>
<td><code>blockNumber</code></td>
<tdstyle="text-align:center">Quantity</td>
<td>Block number of block containing this transaction. <code>null</code> when transaction is pending.</td>
</tr>
<tr>
<td><code>from</code></td>
<tdstyle="text-align:center">Data, 20 bytes</td>
<td>Address of the sender.</td>
</tr>
<tr>
<td><code>gas</code></td>
<tdstyle="text-align:center">Quantity</td>
<td>Gas provided by the sender.</td>
</tr>
<tr>
<td><code>gasPrice</code></td>
<tdstyle="text-align:center">Quantity</td>
<td>Gas price provided by the sender in Wei.</td>
</tr>
<tr>
<td><code>hash</code></td>
<tdstyle="text-align:center">Data, 32 bytes</td>
<td>Hash of the transaction.</td>
</tr>
<tr>
<td><code>input</code></td>
<tdstyle="text-align:center">Data</td>
<td>Data sent with the transaction.</td>
</tr>
<tr>
<td><code>nonce</code></td>
<tdstyle="text-align:center">Quantity</td>
<td>Number of transactions made by the sender before this one.</td>
</tr>
<tr>
<td><code>to</code></td>
<tdstyle="text-align:center">Data, 20 bytes</td>
<td>Address of the receiver. <code>null</code> if a contract creation transaction.</td>
