<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 (note that it doesn't support Whisper or Swarm).</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><strong>[<em>This is preliminary content for the Pantheon Alpha release.</em>]</strong></p>
<p><strong>[<em>This is preliminary content for the Pantheon Alpha release.</em>]</strong></p>
<blockquote>
<p><strong>Note</strong> 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>, this section is not relevant. </p>
<p>Continue with <ahref="#Quickstart">Basic Quickstart</a> or <ahref="#Starting-Pantheon">Starting Pantheon</a>.</p>
</blockquote>
<h2id="contents">Contents</h2>
<h2id="contents">Contents</h2>
<h3id="running-locally">Running Locally</h3>
<h3id="running-locally">Running Locally</h3>
<ul>
<ul>
@ -892,6 +888,10 @@ KeyPairUtil | Generated new key <key> and stored it to ~/pantheon/build/di
<p>This tutorial describes how to use Pantheon to run a private network of Pantheon nodes in a Docker container.</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 Docker 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>, continue with <ahref="#Quickstart">Basic Quickstart</a> or <ahref="#Starting-Pantheon">Starting Pantheon</a>.</p>
</blockquote>
<h2id="prerequisites">Prerequisites</h2>
<h2id="prerequisites">Prerequisites</h2>
<p>To run this tutorial, you must have the following installed:</p>
<p>To run this tutorial, you must have the following installed:</p>
<ul>
<ul>
@ -912,8 +912,8 @@ clone the repository.</p>
<h2id="build-docker-images-and-start-services-and-network">Build Docker Images and Start Services and Network</h2>
<h2id="build-docker-images-and-start-services-and-network">Build Docker Images and Start Services and Network</h2>
<p>This tutorial uses <ahref="https://docs.docker.com/compose/">Docker Compose</a> to simplify assembling images and
<p>This tutorial uses <ahref="https://docs.docker.com/compose/">Docker Compose</a> to simplify assembling images and
running in a private network. To run the containers, go to the <code>pantheon</code> directory and run the following shell command:</p>
running in a private network. To run the containers, go to the <code>pantheon</code> directory and run the following shell command:</p>
<preclass="hljs">./runPantheonPrivateNetwork.sh</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>
<preclass="hljs">quickstart/runPantheonPrivateNetwork.sh</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>
<p>When the <code>./runPantheonPrivateNetwork.sh</code> script ends, it lists the running services:</p>
<p>When the <code>quickstart/runPantheonPrivateNetwork.sh</code> script ends, it lists the running services:</p>
quickstart_bootnode_1 /opt/pantheon/bootnode_sta ... Up <spanclass="hljs-number">30303</span>/tcp, <spanclass="hljs-number">30303</span>/udp, <spanclass="hljs-number">8084</span>/tcp, <spanclass="hljs-number">8545</span>/tcp
quickstart_bootnode_1 /opt/pantheon/bootnode_sta ... Up <spanclass="hljs-number">30303</span>/tcp, <spanclass="hljs-number">30303</span>/udp, <spanclass="hljs-number">8084</span>/tcp, <spanclass="hljs-number">8545</span>/tcp
@ -935,7 +935,7 @@ Web block explorer address : http://localhost:32770 *
<li>Use the <strong>Web block explorer address</strong> to display the block explorer web application. You can invoke the block explorer by clicking on the endpoint link or by entering the URL in your web browser.</li>
<li>Use the <strong>Web block explorer address</strong> to display the block explorer web application. You can invoke the block explorer by clicking on the endpoint link or by entering the URL in your web browser.</li>
<p>This tutorial uses a block explorer based on <ahref="https://github.com/mix-blockchain/block-explorer.git">the MIX project explorer</a>.</p>
<p>This tutorial uses a block explorer based on <ahref="https://github.com/mix-blockchain/block-explorer.git">the MIX project explorer</a>.</p>
<blockquote>
<blockquote>
<p><strong>Note:</strong> As Yarn is an Apache 2.0 licensed tool, it has been patched to fit this tutorial's needs. (You can view the patches in the quickstart/explorer folder.)</p>
<p><strong>Note:</strong> As Yarn is an Apache 2.0 licensed tool, it has been patched to fit this tutorial's needs. (You can view the patches in the quickstart/explorer folder.)</p>
@ -961,7 +961,7 @@ Web block explorer address : http://localhost:32770 *
<p>You can run RPC requests on <code>rpcnode</code>, the node that is exposed to the host in order to listen for requests.</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.</p>
<p>In this tutorial, note that the <code>http://localhost:http-rpc-port</code> placeholder is <code>http://localhost: 32769</code>.</p>
<p>In this tutorial, note that the <code>http://localhost:http-rpc-port</code> placeholder is <code>http://localhost: 32769</code>.</p>
<blockquote>
<blockquote>
<p><strong>Note:</strong> Make sure to replace <code>port</code> with the one provided in the <code>./listQuickstartServices.sh</code> command <code>JSON-RPC HTTP service endpoint</code>.
<p><strong>Note:</strong> Make sure to replace <code>port</code> with the one provided in the <code>quickstart/listQuickstartServices.sh</code> command <code>JSON-RPC HTTP service endpoint</code>.
The dynamic docker port mapping changes each time you run the network.</p>
The dynamic docker port mapping changes each time you run the network.</p>
</blockquote>
</blockquote>
<h3id="requesting-the-node-version">Requesting the Node Version</h3>
<h3id="requesting-the-node-version">Requesting the Node Version</h3>
@ -1087,7 +1087,7 @@ So modify the file to look like the following :</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>
<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>Your are then able to see the transactions and contracts deployed on your local docker network if you have a look in the block explorer.</p>
<preclass="hljs">truffle migrate --network quickstartWallet</pre><p>Your are then able to see the transactions and contracts deployed on your local docker network if you have a look in the block explorer.</p>
<h2id="shut-down-the-network-and-remove-the-nodes">Shut Down the Network and Remove the Nodes</h2>
<h2id="shut-down-the-network-and-remove-the-nodes">Shut Down the Network and Remove the Nodes</h2>
<p>To shut down the network, you can use the script <code>./removePantheonPrivateNetwork.sh</code>; this will stop and destroy all containers.</p>
<p>To shut down the network, you can use the script <code>quickstart/removePantheonPrivateNetwork.sh</code>; this will stop and destroy all containers.</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>
<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>
@ -1104,15 +1104,15 @@ So modify the file to look like the following :</p>
</ul>
</ul>
<h2id="run-a-node-on-ethereum-mainnet">Run a Node on Ethereum Mainnet</h2>
<h2id="run-a-node-on-ethereum-mainnet">Run a Node on Ethereum Mainnet</h2>
<p>To run a node on the Ethereum mainnet: </p>
<p>To run a node on the Ethereum mainnet: </p>
<p><code>$ pantheon</code></p>
<p><code>$ bin/pantheon</code></p>
<p>To run a node on mainnet with the HTTP JSON-RPC service enabled: </p>
<p>To run a node on mainnet with the HTTP JSON-RPC service enabled: </p>
<p><code>$ pantheon --rpc-enabled</code></p>
<p><code>$ bin/pantheon --rpc-enabled</code></p>
<h2id="run-a-node-on-ropsten-testnet">Run a Node on Ropsten Testnet</h2>
<h2id="run-a-node-on-ropsten-testnet">Run a Node on Ropsten Testnet</h2>
<p>Replace <code><path></code> with the path to the <code>/pantheon</code> directory. </p>
<p>Replace <code><path></code> with the path to the <code>/pantheon</code> directory. </p>
<pclass="page"id="Run-Docker-Image"></p><h1>Running Pantheon from Docker Image</h1>
<h1id="using-pantheon">Using Pantheon</h1>
<h1id="run-pantheon-from-docker-image">Run Pantheon from Docker Image</h1>
<p><strong>[<em>This is preliminary content for the Pantheon Alpha release.</em>]</strong></p>
<p>A Docker image is provided to run a Pantheon node in a Docker container. </p>
<h2id="contents">Contents</h2>
<p>Use this Docker image to run a single Pantheon node without installing Pantheon. </p>
<h2id="prerequisites">Prerequisites</h2>
<p>To run Pantheon from the Docker image, you must have the following installed:</p>
<ul>
<ul>
<li><ahref="#Transactions">Transactions</a></li>
<li><p>Linux or Mac OS</p>
<li><ahref="#Filters">Filters</a></li>
</li>
<li><ahref="#Testing-Developing-Nodes">Testing and Developing Nodes</a></li>
<li><p><ahref="https://docs.docker.com/compose/install/">Docker and Docker-compose</a></p>
<li><ahref="#Proof-of-Authority">Proof of Authority (Clique)</a></li>
</li>
<li><ahref="#Mining">Mining</a></li>
</ul>
</ul>
<pclass="page"id="Transactions"></p><h1>Creating and Sending Transactions</h1>
<h2id="quickstart">Quickstart</h2>
<p>To run a Pantheon node in a container connected to the Ethereum mainnet: </p>
<preclass="hljs">docker run pegasyseng/pantheon:latest</pre><h2id="command-line-options">Command Line Options</h2>
<p>The following Pantheon command line options cannot be used when running Pantheon from the Docker image: </p>
<ul>
<li><code>--datadir</code>, see <ahref="#persisting-data">Persisting Data</a></li>
<li><code>--config</code>, see <ahref="#custom-configuration-file">Custom Configuration File</a></li>
<li><code>--genesis</code>, see <ahref="#custom-genesis-file">Custom Genesis File</a>.</li>
<li><code>--rpc-listen</code>, <code>--p2plisten</code>, <code>--ws-listen</code>, see <ahref="#specifying-ports">Specifying Ports</a></li>
</ul>
<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>
<preclass="hljs">docker run -v /<myvolume/pantheon>:/var/lib/pantheon pegasyseng/pantheon:latest</pre><p>Where <code><myvolume/pantheon></code> is the directory to which the data is saved. </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 -v </path/myconf.toml>:/etc/pantheon/pantheon.conf pegasyseng/pantheon:latest</pre><p>Where <code>myconf.toml</code> is your custom configuration file and <code>path</code> is the absolute path to the file. For example:</p>
<preclass="hljs">docker run -v /Users/madelinemurray/pegasys-jenkins/docker/pantheon/myconf.toml:/etc/pantheon/pantheon.conf pegasyseng/pantheon:latest</pre><h3id="custom-genesis-file">Custom Genesis File</h3>
<p>Specify a custom genesis file to configure the blockchain. This is equivalent to specifying the <code>--genesis</code> option.</p>
<p>To run Pantheon specifying a custom genesis file: </p>
<preclass="hljs">docker run -v </path/mygenesis.json>:/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 -v /Users/madelinemurray/pegasys-jenkins/docker/pantheon/mygenesis.json:/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>--p2plisten</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>
<p>To run a node on the Ethereum mainnet: </p>
<preclass="hljs">docker run -v /<myvolume/pantheon>:/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 -v /<myvolume/pantheon>:/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/ethereum/core/src/main/resources/ropsten.json">Ropsten genesis file</a>. </p>
<p>To run a node on Ropsten: </p>
<preclass="hljs">docker run -v /<myvolume/pantheon/ropsten>:/var/lib/pantheon -v ropsten.json:/etc/pantheon/genesis.json pegasyseng/pantheon:latest --network-id=3 --bootnodes=enode://6332792c4a00e3e4ee0926ed89e0d27ef985424d97b6a45bf0f23e51f0dcb5e66b875777506458aea7af6f9e4ffb69f43f3778ee73c81ed9d34c51c4b16b0b0f@52.232.243.152:30303,enode://94c15d1b9e2fe7ce56e458b9a3b672ef11894ddedd0c6f247e0f1d3487f52b66208fb4aeb8179fce6e3a749ea93ed147c37976d67af557508d199d9594c35f09@192.81.208.223:30303</pre><h2id="run-a-node-on-rinkeby-testnet">Run a Node on Rinkeby Testnet</h2>
<p>To run a node on Rinkeby: </p>
<preclass="hljs">docker run -v /<myvolume/pantheon/rinkeby>:/var/lib/pantheon pegasyseng/pantheon:latest --rinkeby</pre><h2id="run-a-node-for-testing">Run a Node for Testing</h2>
<p>To run a node that mines blocks at a rate suitable for testing purposes with WebSockets enabled: </p>
<preclass="hljs">docker run -p 8546:8546 -v /<myvolume/pantheon/testnode>:/var/lib/pantheon pegasyseng/pantheon:latest --dev-mode --bootnodes= --miner-enabled --miner-coinbase fe3b557e8fb62b89f4916b721be55ceb828dbd73 --rpc-cors-origins "all" --ws-enabled</pre><pclass="page"id="Transactions"></p><h1>Creating and Sending Transactions</h1>
<h1id="transactions">Transactions</h1>
<h1id="transactions">Transactions</h1>
<p>Signed transactions can be sent 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>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>To avoid exposing your private keys, create signed transactions offline.</strong></p>
<p><strong>To avoid exposing your private keys, create signed transactions offline.</strong></p>
<p>The examples all use the following libraries to create signed transactions:</p>
<p>The examples use the following libraries to create signed transactions:</p>
<p><strong>Note:</strong> Other libraries (for example, <ahref="https://github.com/web3j/web3j">webj3</a> or <ahref="https://github.com/ethereum/ethereumj">ethereumj</a>) and tools (for example, <ahref="https://kb.myetherwallet.com/offline/making-offline-transaction-on-myetherwallet.html">MyEtherWallet</a> or <ahref="https://mycrypto.com/">mycrypto.com</a>) can also be used to create signed transactions. </p>
<blockquote>
<p>Example JS scripts are provided below to create signed raw transactions to: </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>
<ul>
<ul>
<li><ahref="#sending-ether">Send ether</a></li>
<li><ahref="#sending-ether">Send ether</a></li>
<li><ahref="#deploying-a-contract">Deploy a contract</a></li>
<li><ahref="#deploying-a-contract">Deploy a contract</a></li>
</ul>
</ul>
<p>The example JS scripts can be used to create raw transactions to send in the private network created by the <ahref="#docker-quickstart">Docker Quickstart</a>. The <code>HTTP JSON-RPC endpoint</code> in the examples must be updated to the endpoint for private network. </p>
<blockquote>
<p>Run a JS script to create and display the transaction string. For example:</p>
<p><strong>Note:</strong><ahref="https://nodejs.org/en/download/">Node.js</a> must be installed to run JS scripts. </p>
</blockquote>
<p>The example JS scripts can be used to create raw transactions to send in the private network created by the <ahref="#docker-quickstart">Docker 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>
<p>To create and display the transaction string, run the JS script. For example:</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":["raw_transaction_string"],"id":1}'</span><JSON-RPC-endpoint:port></pre><p>Where:</p>
<ul>
<ul>
<li><code>raw_transaction_string</code> is the signed raw transaction string. </li>
<li><code>raw_transaction_string</code> is the signed raw transaction string displayed by the JS script. </li>
<li><code><JSON-RPC-endpoint:port></code> is the JSON-RPC HTTP endpoint.</li>
<li><code><JSON-RPC-endpoint:port></code> is the JSON-RPC endpoint.</li>
</ul>
</ul>
<p>For example: </p>
<p>For example: </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><h2id="sending-ether">Sending Ether</h2>
<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>
<h2id="sending-ether">Sending Ether</h2>
<p>The following is an example of JS script that displays a signed transaction string to send ether. </p>
<p>The following is an example of JS script that displays a signed transaction string to send ether. </p>
<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>
<ul>
<li><ahref="#JSON-RPC-API.mdeth_getbalance">eth_getBalance</a> to obtain the account balance</li>
<li><ahref="#JSON-RPC-API.mdeth_sendrawtransaction">eth_sendRawTransaction</a> to transfer ether or create and interact with contracts (for more information, refer to <ahref="#transactions">Transactions</a>). </li>
</ul>
<pclass="page"id="Filters"></p><h1>Filters</h1>
<pclass="page"id="Filters"></p><h1>Filters</h1>
<h1id="filters">Filters</h1>
<h1id="filters">Filters</h1>
<p>Explains how to query block status using filters.</p>
<p>Explains how to query block status using filters.</p>
<pclass="page"id="Testing-Developing-Nodes"></p><h1>Testing and Developing Nodes</h1>
<pclass="page"id="Testing-Developing-Nodes"></p><h1>Testing and Developing Nodes</h1>
<h1id="testing-and-developing-nodes">Testing and Developing Nodes</h1>
<h1id="testing-and-developing-nodes">Testing and Developing Nodes</h1>
<p>Explains how to set networks and configure genesis files for test and development.</p>
<h2id="bootnodes">Bootnodes</h2>
<pclass="page"id="Mining"></p><h1>Mining</h1>
<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>[<em>This is preliminary content for the Pantheon Alpha release.</em>]</strong></p>
<h2id="contents">Contents</h2>
<ul>
<li>Event Publication and Subscription</li>
<li>Creating Subscriptions</li>
<li>Canceling Subscriptions</li>
</ul>
<h2id="event-publication-and-subscription">Event Publication and Subscription</h2>
<p>Pantheon supports event publication and subscription with RPC Pub/Sub methods. Using RPC Pub/Sub, your client can wait for events instead of polling for them. You invoke the RPC Pub/Sub methods over WebSockets; the methods are:</p>
<ul>
<li><code>eth_subscribe</code> - Creates a subscription that waits for particular events.</li>
<li><code>eth_unsubscribe</code> - Cancels an existing subscription.</li>
<li><code>eth_subscription</code> - Publishes (reports) notifications of event occurrences.</li>
</ul>
<h3id="subscriptions">Subscriptions</h3>
<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>
<h4id="newblockheaders">NewBlockHeaders</h4>
<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 that are interested to them.
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>The following is an example of <code>NewBlockHeaders</code> notifications:</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><code>Logs</code> subscriptions can take as a parameter an <code>object</code> with the following fields:</p>
<ul>
<li><code>address</code> - (optional) Either an address or an array of addresses. Returns only logs created from these addresses.</li>
<li><code>topics</code> - (optional) Returns only logs that match the specified topics.</li>
</ul>
<p>The following is an example of <code>Logs</code> notifications:</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><code>PendingTransactions</code> takes no parameters.</p>
<p>The returned data is a transaction hash.</p>
<p>The following is an example of <code>PendingTransactions</code> notifications:</p>
<p>Indicates when the node starts or stops synchronizing. The result can either be a <code>boolean</code> indicating that the synchronization has started (<code>true</code>), finished (<code>false</code>) or an <code>object</code> with various progress indicators.</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> publishes (reports) 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>
<h4id="parameters">Parameters</h4>
<p>None</p>
<h4id="returns">Returns</h4>
<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>
<dd>A list of comma-separated enode URLs for P2P discovery bootstrap. The default is a predefined list of enode URLs.</dd>
<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>
<br>
<br>
<dt><code>--config=<PATH></code></dt>
<dt><code>--config=<PATH></code></dt>
<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.
<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>.
<dt><code>--datadir=<PATH></code></dt>
<dt><code>--datadir=<PATH></code></dt>
<dd>The path to the Pantheon data directory. The default location is the <code>/build/distributions/pantheon-1.0.0-SNAPSHOT</code> directory in the Pantheon installation directory.</dd>
<dd>The path to the Pantheon data directory. The default location is the <code>/build/distributions/pantheon-1.0.0-SNAPSHOT</code> directory in the Pantheon installation directory.</dd>
><strong>Note:</strong> This option is not used when running Pantheon from the <ahref="#Run-Docker-Imagepersisting-data">Docker image</a>.
<dd>Comma-separated APIs to enable on the JSON-RPC channel. The <code>--rpc-enabled</code> option must be specified with this option. The default is: <code>ETH, NET, WEB3</code>. The <code>DEBUG</code> and <code>MINER</code> APIs can also be enabled.</dd>
<dd>Comma-separated APIs to enable on the JSON-RPC channel. The <code>--rpc-enabled</code> option must be specified with this option. The default is: <code>ETH, NET, WEB3</code>. The <code>DEBUG</code> and <code>MINER</code> APIs can also be enabled.</dd>
@ -1384,9 +1600,7 @@ 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.
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>
</dd>
<br>
<dt><code>--sync-mode=<MODE></code></dt>
<dd>Synchronization mode. Value can be <code>FULL</code> or <code>FAST</code>. The default is <code>FULL</code>.</dd>
<br>
<br>
<dt><code>--ws-enabled</code></dt>
<dt><code>--ws-enabled</code></dt>
<dd>Set to <code>true</code> to enable the WS-RPC (WebSockets) service. The default is <code>false</code>.</dd>
<dd>Set to <code>true</code> to enable the WS-RPC (WebSockets) service. The default is <code>false</code>.</dd>
@ -1399,6 +1613,7 @@ For development purposes, you can use <code>"all"</code> to accept req
<p>Pantheon is licensed under Apache License 2.0.</p>
<p>Pantheon is licensed under Apache License 2.0.</p>
<pclass="page"id="JSON-RPC-API"></p><h1>JSON-RPC API Reference</h1>
<pclass="page"id="JSON-RPC-API"></p><h1>JSON-RPC API Reference</h1>
@ -1459,6 +1684,10 @@ To activate JSON-RPC using http or WebSocket, see <a href="https://github.com/Pe
<li><code>latest</code> : <code>tag</code> - Last block mined.</li>
<li><code>latest</code> : <code>tag</code> - Last block mined.</li>
<li><code>pending</code> : <code>tag</code> - Last block mined plus pending transactions.</li>
<li><code>pending</code> : <code>tag</code> - Last block mined plus pending transactions.</li>
</ul>
</ul>
<h2id="account-management-not-supported-by-pantheon">Account Management Not Supported by Pantheon</h2>
<p>Account management relies on private key management in the client which is not implemented by Pantheon. </p>
<p>Use <ahref="#eth_sendrawtransaction"><code>eth_sendRawTransaction</code></a> to send signed transaction; <code>eth_sendTransaction</code> is not implemented. </p>
<p>Use wallets for <ahref="#Account-Management">account management</a>. </p>
<h2id="json-rpc-methods">JSON-RPC Methods</h2>
<h2id="json-rpc-methods">JSON-RPC Methods</h2>
<p><strong>[<em>Note for Alpha release: The following lists only the Pantheon JSON-RPC API commands that are currently fully or partially implemented.</em>]</strong></p>
<p><strong>[<em>Note for Alpha release: The following lists only the Pantheon JSON-RPC API commands that are currently fully or partially implemented.</em>]</strong></p>
<p>The following lists the Pantheon JSON-RPC API commands:</p>
<p>The following lists the Pantheon JSON-RPC API commands:</p>
@ -1660,13 +1889,11 @@ To activate JSON-RPC using http or WebSocket, see <a href="https://github.com/Pe
}</pre><hr>
}</pre><hr>
<h4id="eth_accounts">eth_accounts</h4>
<h4id="eth_accounts">eth_accounts</h4>
<p>Returns a list of account addresses that the client owns.</p>
<p>Returns a list of account addresses that the client owns.</p>
<p><strong>NOTE:</strong> This method returns an empty object; this is the correct behavior, not a malfunction, and simply reflects the current state of mainnet.</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><code>Array of DATA</code> : A list of 20-byte account addresses that the client owns.</p>
<p><code>Array of data</code> : List of 20-byte account addresses owned by the client.</p>
<h5id="request">Request</h5>
<h5id="request">Request</h5>
<preclass="hljs">curl -X POST --data '{"jsonrpc":"2.0","method":"eth_accounts","params":[],"id":53}' <JSON-RPC-endpoint:port></pre><h5id="result">Result</h5>
<preclass="hljs">curl -X POST --data '{"jsonrpc":"2.0","method":"eth_accounts","params":[],"id":53}' <JSON-RPC-endpoint:port></pre><h5id="result">Result</h5>
<preclass="hljs">{
<preclass="hljs">{
@ -1801,7 +2028,7 @@ To activate JSON-RPC using http or WebSocket, see <a href="https://github.com/Pe
<p>Sends a signed transaction. A transaction can send ether, deploy a contract, or interact with a contract. </p>
<p>Sends a signed transaction. A transaction can send ether, deploy a contract, or interact with a contract. </p>
<p>You can interact with contracts using <ahref="#Using-Pantheoneth_call-or-eth_sendrawtransaction">eth_sendRawTransaction or eth_call</a>.</p>
<p>You can interact with contracts using <ahref="#Using-Pantheoneth_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="https://github.com/PegaSysEng/pantheon/wiki/Using-Pantheon#transactions">Using Pantheon</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="https://github.com/PegaSysEng/pantheon/wiki/Using-Pantheon#transactions">Using Pantheon</a>. </p>
<p><strong>Note: Pantheon does not implement eth_sendTransaction because this relies on private key management by the client that could potentially be exposed during the transaction.</strong></p>
<p><strong>Note: Pantheon does not implement <ahref="#account-management-not-supported-by-pantheon">eth_sendTransaction</a>.</strong></p>
<h5id="parameters">Parameters</h5>
<h5id="parameters">Parameters</h5>
<p><code>DATA</code> - Hash of the signed raw transaction in hexadecimal format; for example:</p>
<p><code>DATA</code> - Hash of the signed raw transaction in hexadecimal format; for example:</p>
MadelineMurray
6 years ago
committed by
Adrian Sutton