diff --git a/GETTING-STARTED.md b/GETTING-STARTED.md new file mode 100644 index 0000000000..ed08b3fdb7 --- /dev/null +++ b/GETTING-STARTED.md @@ -0,0 +1,6 @@ +# Getting Started +**Pantheon 0.8.0 RC2 release** +After you clone the PegaSysEng/pantheon repo, we recommend that you first run the 'pantheon' startup script for Linux/MacOS (or the 'pantheon.bat' startup script for Windows) in the pantheon-/bin directory. This script appropriately sets system variables and command-line arguments for Java, JVM, and Pantheon. +After you've run the startup script, we encourage you to read the Pantheon technical documentation, located on the wiki tab of PegaSysEng/pantheon: + https://github.com/PegaSysEng/pantheon/wiki +This wiki provides detailed information on getting started, along with tutorials and comprehensive reference content. diff --git a/docs/PantheonDocumentation0.8.0-RC2.html b/docs/PantheonDocumentation0.8.0-RC2.html new file mode 100644 index 0000000000..47bbc6c066 --- /dev/null +++ b/docs/PantheonDocumentation0.8.0-RC2.html @@ -0,0 +1,2725 @@ + + + + + + + Pantheon Documentation 0.8.0-RC2 + + + + + + + + + + +
+
+
+ + Pantheon Documentation 0.8.0-RC2 +
+ +
+
+
+
+
+
+ +
+
+ + +
+

Overview

+

Pantheon Overview

+

[This is preliminary content for the Pantheon Alpha release.]

+

Contents

+ +

What is Pantheon?

+

Pantheon is an open-source Ethereum client 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 and Proof of Authority (Clique) consensus mechanisms.

+

You can use Pantheon to develop enterprise applications requiring secure, high-performance transaction processing in a private network.

+

Our roadmap includes Pantheon with privacy features, alternative consensus mechanisms, and other enterprise features.

+

What can you do with Pantheon?

+

Pantheon includes a command line interface and JSON-RPC API 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:

+
    +
  • Ether token mining
    • +
  • Smart contract development
    • +
  • Decentralized application (Dapp) development
    • +
+

The Pantheon client supports common smart contract and Dapp development, deployment, and operational use cases, using tools such as Truffle, Remix, and web3j. 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).

+

Architecture

+

Getting Started

+

Get started with Pantheon:

+ +

Installation

+

Pantheon Installation

+

[This is preliminary content for the Pantheon Alpha release.]

+

Contents

+

Running Locally

+ +

Running Virtually

+ +

Installation on Linux / Unix / Mac OS X

+

Prerequisites

+
    +

  • 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 and the sync mode you use. A small test network might require 200 MB while a mainnet node might require 1.5TB. If you use fast sync mode, allow 500 GB for the fast blockchain import snapshot. If you use full sync mode, allow 1.5 TB to 2 TB for the full blockchain archive.

    +
    • +

  • Java JDK

    +
    +

    IMPORTANT: Pantheon requires Java 8+ to compile; earlier versions are not supported.

    +
    +
    • +

  • Git or GitHub Desktop

    +
    • +
+

Clone the Pantheon Repository

+
+

Note: We recommend that you create and copy a personal access token (PAT) for your GitHub account (with all repo scopes enabled) in order to clone the Pantheon repo.

+
+

Clone the PegaSysEng/pantheon repo to your home directory (/home/<user>). When Git prompts you for your username and password, enter the PAT as the password. For example:

+
$ git clone --recursive https://github.com/PegaSysEng/pantheon.git
+Cloning into 'pantheon'...
+Username: <username>
+Password: <personal-access-token>

Build Pantheon

+

After the cloning process completes, go to the pantheon repo directory and run git branch to make sure you're in the branch in which you cloned the Pantheon source code (by default this is the master branch).

+

Build the pantheon executable using gradlew. You can use the -x test option to exclude tests, which can take a long time to run and are not necessary for initial build:

+
./gradlew build -x test

Continue with Basic Quickstart, Docker Quickstart, or Starting Pantheon.

+

Installation on Windows

+

Prerequisites

+
    +

  • Java JDK

    +
    +

    IMPORTANT: Pantheon requires Java 8+ to compile; earlier versions are not supported.

    +
    +
    • +

  • Git or GitHub Desktop

    +
    • +
+

Install Pantheon

+

Log in to your GitHub account and open Settings > Developer Settings > Personal Access Token. Create and copy a personal access token (PAT) for your GitHub account in order to clone the Pantheon repo. In Scopes, select repo, and click Generate. When GitHub lists the generated token, click the clipboard icon to copy its value. Save this value, as you can only view it once.

+

In Git bash, go to your working directory for repositories. Clone the PegaSysEng/pantheon repo into this directory. This will create a pantheon directory under Git revision control, and will contain the cloned PegaSysEng/pantheon repo contents.

+

When you invoke git clone, Git will prompt you for your username and password. Enter the PAT instead of your password. The command and response should look like the following:

+
$ git clone --recursive https://github.com/PegaSysEng/pantheon
+Cloning into 'pantheon'...
+Username: <username>
+Password: <personal-access-token>

Build Pantheon

+

After the cloning process completes, navigate to the pantheon directory, which should contain the Gradle wrapper gradlew:

+
cd <repos-dir>\pantheon

Build the Pantheon JAR on Windows with gradlew:

+
gradlew build

Or build using assembleDist:

+
./gradlew assembleDist -x test
+

NOTE: To run gradlew, you must have the JAVA_HOME system variable set to the Java installation location. +For example: JAVA_HOME = C:\Program Files (x86)\Java\jdk1.8.0_181.

+
+

Pantheon should begin to build and the output will be displayed in the console.

+

Installation on VM

+

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 VirtualBox.

+

If you set up your own VM locally using a VM manager such as VirtualBox, there are a few considerations:

+
    +

  • Make sure that Intel Virtualization Technology (VTx) and Virtualization Technology for Directed I/O (VT-d) are enabled in BIOS settings.

    +
    • +

  • On Windows, you might need to disable Hyper-V in the Windows Feature list.

    +
    • +
+

It is recommended that you create a VM with the following attributes:

+
    +

  • Memory Size: Set to 4096 (recommended)

    +
    • +

  • Create a virtual hard disk with at least 10 GB; 20 GB is recommended

    +
    • +

  • Virtual hard disk file type: VDI (if you need to share it with other apps, use VHD)

    +
    • +

  • (Optional) You can create a shared directory 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 Install Ubuntu on Oracle VirtualBox.

    +
    • +
+

Basic Quickstart

+

Pantheon Quickstart

+

[This is preliminary content for the Pantheon Alpha release.]

+

This tutorial shows you how to install Pantheon and invoke the Pantheon CLI to run a single node in default mode:

+
    +
  • The node runs on the Ethereum mainnet and uses the default embedded mainnet genesis file.
    • +
  • The node does not perform mining.
    • +
  • P2P peer discovery is enabled on the default P2P port. There are a maximium of 25 P2P peer connections.
    • +
  • Listen on the default RPC over HTTP host/port.
    • +
  • Use full synchronization mode.
    • +
+

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 curl to make a call using Pantheon JSON-RPC API; this will make a request to verify that the node is running.

+

Installation

+

Install Java, Git, and Pantheon for your platform as described in Installation, then proceed through the following steps.

+

Run Pantheon

+

In this tutorial, you'll build and run Pantheon in one terminal (bash) window and run curl commands to make JSON-RPC requests in another terminal window. To do this, either open two separate instances of Terminal, or run a utility such as tmux to run a split screen terminal.

+

In the first terminal, go to the ~/pantheon folder:

+
cd pantheon

Build Pantheon as described in Installation.

+

To run pantheon, go to the distribution folder:

+
cd build/distributions/

Expand the distribution archive:

+
tar -xzf pantheon-0.8.0-SNAPSHOT.tar.gz

Move to the expanded folder and run pantheon using the script to display command help:

+
cd pantheon-0.8.0-SNAPSHOT/
+bin/pantheon --help

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:

+
bin/pantheon import ~/pantheon/testutil/src/main/resources/1000.blocks

When the import completes successfully, you should see messages containing the following:

+
ImportSubCommand | Runs import sub command with blocksImportPath
+
+KeyPairUtil | Generated new key <key> and stored it to ~/pantheon/build/distributions/pantheon-0.8.0-SNAPSHOT/key

For more information on using the pantheon import subcommand, see Pantheon CLI Syntax.

+

After the import successfully completes, run Pantheon with only the --rpc-enabled option:

+
bin/pantheon --rpc-enabled

This runs Pantheon in default mode, meaning it runs in mainnet with the default genesis file, and peer discovery is enabled.

+

The --rpc-enabled option starts the JSON-RPC service.

+

The terminal output will indicate that the node is synchronizing.

+

Test the Pantheon Node

+

Make JSON-RPC Requests using curl

+

While the node is running, make a request on it using curl and the JSON-RPC API.

+

Switch to the bottom window using Ctrl+b o and run the following curl command:

+
curl -X POST --data '{"jsonrpc":"2.0","method":"eth_syncing","params":[],"id":1}' 127.0.0.1:8545

Note the endpoint IP and default port. You should see a result similar to the following:

+
{
+  "jsonrpc" : "2.0",
+  "id" : 1,
+  "result" : {
+    "startingBlock" : "0x3e7",
+    "currentBlock" : "0x3e7",
+    "highestBlock" : "0x0"
+  }
+}

You can now call other JSON-RPC commands listed in Pantheon JSON RPC API.

+

Close the Terminal Session

+

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 Ctrl+c.

+

Docker Quickstart

+

Docker Quickstart Tutorial

+

This tutorial describes how to use Pantheon to run a private network of Pantheon nodes in a Docker container.

+

Prerequisites

+

To run this tutorial, you must have the following installed:

+ +

Clone Pantheon Source Code

+

As indicated in the installation section, +clone the repository.

+

Build Docker Images and Start Services and Network

+

This tutorial uses Docker Compose to simplify assembling images and +running in a private network. To run the containers, go to the pantheon directory and run the following shell command:

+
./runPantheonPrivateNetwork.sh

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.

+

When the ./runPantheonPrivateNetwork.sh script ends, it lists the running services:

+
         Name                       Command               State                           Ports
+-----------------------------------------------------------------------------------------------------------------------
+quickstart_bootnode_1    /opt/pantheon/bootnode_sta ...   Up      30303/tcp, 30303/udp, 8084/tcp, 8545/tcp
+quickstart_explorer_1    /bin/sh -c npm start             Up      0.0.0.0:32770->3000/tcp
+quickstart_minernode_1   /opt/pantheon/node_start.s ...   Up      30303/tcp, 30303/udp, 8084/tcp, 8545/tcp
+quickstart_node_1        /opt/pantheon/node_start.s ...   Up      30303/tcp, 30303/udp, 8084/tcp, 8545/tcp
+quickstart_node_2        /opt/pantheon/node_start.s ...   Up      30303/tcp, 30303/udp, 8084/tcp, 8545/tcp
+quickstart_node_3        /opt/pantheon/node_start.s ...   Up      30303/tcp, 30303/udp, 8084/tcp, 8545/tcp
+quickstart_node_4        /opt/pantheon/node_start.s ...   Up      30303/tcp, 30303/udp, 8084/tcp, 8545/tcp
+quickstart_rpcnode_1     /opt/pantheon/node_start.s ...   Up      30303/tcp, 30303/udp, 8084/tcp,
+                                                                  0.0.0.0:32769->8545/tcp, 0.0.0.0:32768->8546/tcp

And a friendly recap of the entrypoints :

+
****************************************************************
+JSON-RPC HTTP service endpoint      : http://localhost:32769   *
+JSON-RPC WebSocket service endpoint : http://localhost:32768   *
+Web block explorer address          : http://localhost:32770   *
+****************************************************************
    +
  • Use the JSON-RPC HTTP service endpoint to access the RPC node service from your Dapp or from cryptocurrency wallets such as Metamask.
    • +
  • Use the JSON-RPC WebSocket service endpoint to access the web socket node service from your Dapp.
    • +
  • Use the Web block explorer address to display the block explorer web application. You can invoke the block explorer by clicking on the endpoint link or by entering the URL in your web browser.
    • +
+

To display this list at any time, run:

+
./listQuickstartServices.sh

Block Explorer

+

This tutorial uses a block explorer based on the MIX project explorer.

+
+

Note: 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.)

+
+

Using the Block Explorer with MetaMask

+

Log in to MetaMask if you don't already have it running. The block explorer displays the network to which MetaMask is connected. If you see a Peer Count of 100 in the block explorer, it's likely MetaMask is connected to mainnet or one of the testnets such as Ropsten.

+

To display the private network in the block explorer, you have to configure a custom RPC network.

+

After you sign in to MetaMask, connect to the private network RPC endpoint by:

+
    +
  1. In the MetaMask network list, select Custom RPC.
    2. +
  2. In the New RPC URL field, enter the JSON-RPC HTTP service endpoint displayed when you started the private network.
    3. +
+

Save the configuration and return to the MetaMask main screen. Your current network is now set to the private network RPC node.

+

Using the Block Explorer without MetaMask

+

If you don't have Metamask running, the block explorer works directly without configuration. The block explorer integrates its own web3 version and knows the RPC node endpoint.

+

Run the Block Explorer

+

Access the explorer using the Web block explorer address displayed when starting the private network.

+

+

You will see the already mined blocks on the right, and some stats about the RPC node we are connected to on the left.

+

Notice the explorer indicates 6 peers: the 4 regular nodes, the mining node and the bootnode.

+

Now lets play with some requests.

+

Run cURL JSON-RPC requests

+

You can run RPC requests on rpcnode, the node that is exposed to the host in order to listen for requests.

+

In this tutorial, note that the http://localhost:http-rpc-port placeholder is http://localhost: 32769.

+
+

Note: Make sure to replace port with the one provided in the ./listQuickstartServices.sh command JSON-RPC HTTP service endpoint. +The dynamic docker port mapping changes each time you run the network.

+
+

Requesting the Node Version

+

Run the following command from the host shell :

+
curl -X POST --data '{"jsonrpc":"2.0","method":"web3_clientVersion","params":[],"id":1}' http://localhost:http-rpc-port

The result should be as follows:

+
{
+   "jsonrpc" : "2.0",
+   "id" : 1,
+   "result" : "pantheon/0.8.0-SNAPSHOT"
+}

Here we simply query the version of the Pantheon node, which confirms the node is running.

+

Now if this works, let's see some more interesting requests.

+

Counting Peers

+

Peers are the number of other nodes connected to the RPC node.

+

Poll the peer count using net_peerCount:

+
curl -X POST --data '{"jsonrpc":"2.0","method":"net_peerCount","params":[],"id":1}' http://localhost:http-rpc-port

The result should be the following response, indicating that there are 6 peers:

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

Requesting the Most Recent Mined Block Number

+

This provides the count of blocks already mined.

+

To do so, call eth_blockNumber to retrieve the number of the most recent block:

+
curl -X POST --data '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}' http://localhost:http-rpc-port

The result of this call should be:

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

Here the hexadecimal value 0x8b8 translates to 2232 in decimal; that many blocks have already been mined.

+

Checking the Miner Account Balance (Coinbase)

+

Then call eth_getBalance to retrieve the balance of the mining address defined in the miner node:

+
curl -X POST --data '{"jsonrpc":"2.0","method":"eth_getBalance","params":["0xfe3b557e8fb62b89f4916b721be55ceb828dbd73","latest"],"id":1}' http://localhost:http-rpc-port

The result of this call should be something like :

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

0x79f905c6fd34e80000 = 2250000000000000000000 Wei (2250 Ether) (you can use a unit converter )

+

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.

+

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.

+

Additional Requests

+

Now that you are familiar with basic RPC requests you can run JSON-RPC commands to send transactions. +In order to send transactions, you will first need to create an account or use one of the 3 accounts +created during the genesis of this test network.

+

Account 1

+

This is the mining node codebase account:

+
    +
  • Address: 0xfe3b557e8fb62b89f4916b721be55ceb828dbd73
    • +
  • Private key : 0x8f2a55949038a9610f50fb23b5883af3b4ecb3c3bb792cbcefbd1542c692be63
    • +

  • Initial balance : 0xad78ebc5ac6200000 (200000000000000000000 in decimal)

    +

    Account 2

    +
    • +

  • Address: 0x627306090abaB3A6e1400e9345bC60c78a8BEf57

    +
    • +
  • Private key : 0xc87509a1c067bbde78beb793e6fa76530b6382a4c0241e5e4a9ec0a0f44dc0d3
    • +

  • Initial balance : 0x90000000000000000000000 (2785365088392105618523029504 in decimal)

    +

    Account 3

    +
    • +

  • Address: 0xf17f52151EbEF6C7334FAD080c5704D77216b732

    +
    • +
  • Private key : 0xae6ae8e5ccbfb04590405997ee2d52d2b330726137b875053c36d94e974d162f
    • +
  • Initial balance : 0x90000000000000000000000 (2785365088392105618523029504 in decimal)
    • +
+
+

Note: 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.

+
+

Creating a Transaction Using MetaMask

+

Once you have Configured a custom RPC network, import one of the existing accounts above into +metamask +using the corresponding private key.

+

NOTE that here we don't really care about securing the keys as it's just a tutorial, but be sure +to secure your accounts when you run into a real usecase. This will be discussed in a more advanced +chapter.

+

Once this is done, try to create another account from scratch +to send some ether to.

+

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.

+

Send some ether +from the first account (containing some ether) to the new one (that have a zero balance) +and go to the explorer to check that your transaction is validated.

+

You should see a block in the list with one transaction, and you can look at the detail of the block +and of the transactions.

+

+

Playing with the Truffle Pet Shop Tutorial

+

This step is inspired by the PetShop tutorial on Truffle website.

+

Use the following instructions to run it with the quick-start Pantheon Docker network and a wallet to manage keys.

+

Prerequisites

+
    +
  • Install Truffle :
    • +
+
npm install -g truffle
+
mkdir pet-shop-tutorial
+cd pet-shop-tutorial
+truffle unbox pet-shop
    +
  • Install the Wallet by running the following command:
    • +
+
npm install truffle-privatekey-provider

Modify the Pet Shop Example

+

We are going to modify the truffle.js file to add our wallet provider. +So modify the file to look like the following :

+
const PrivateKeyProvider = require("truffle-privatekey-provider");
+const privateKey = "8f2a55949038a9610f50fb23b5883af3b4ecb3c3bb792cbcefbd1542c692be63";
+const privateKeyProvider = new PrivateKeyProvider(privateKey, "[YOUR HTTP RPC NODE ENDPOINT]");
+
+module.exports = {
+  // See <http://truffleframework.com/docs/advanced/configuration>
+  // for more about customizing your Truffle configuration!
+  networks: {
+    development: {
+      host: "127.0.0.1",
+      port: 7545,
+      network_id: "*" // Match any network id
+    },
+    quickstartWallet: {
+      provider: privateKeyProvider,
+      network_id: "*"
+    },
+  }
+};

Then replace the [YOUR HTTP RPC NODE ENDPOINT] placeholder with your HTTP RPC node endpoint. http://localhost:32769 in this case.

+

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.

+

Once this is done, you can go through the regular tutorial steps.

+

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 --network quickstartWallet option :

+
truffle migrate --network quickstartWallet

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.

+

Shut Down the Network and Remove the Nodes

+

To shut down the network, you can use the script ./removePantheonPrivateNetwork.sh; this will stop and destroy all containers.

+

Starting Pantheon

+

Starting Pantheon

+

Pantheon nodes can be used for varying purposes as described in the Overview. Nodes can connect to the Ethereum mainnet, public testnets such as Ropsten, or private networks.

+

Local Block Data

+

When connecting to a network other than the network previously connected to, you must either delete the local block data or use the --datadir option to specify a different data directory.

+

To delete the local block data, delete the database directory in the pantheon/build/distribution/pantheon-0.8.0-SNAPSHOT directory.

+

Genesis Files Provided

+

The following genesis files are provided in the /pantheon/ethereum/core/src/main/resources directory:

+
    +
  • dev.json - Default genesis file when --dev-mode specified.
    • +
  • mainnet.json - Default genesis file when --dev-mode not specified.
    • +
  • rinkeby.json - Used to connect to Rinkeby testnet when --rinkeby specified.
    • +
  • ropsten.json - Specify using --genesis option when connecting to Ropsten testnet.
    • +
+

Run a Node on Ethereum Mainnet

+

To run a node on the Ethereum mainnet:

+

$ pantheon

+

To run a node on mainnet with the HTTP JSON-RPC service enabled:

+

$ pantheon --rpc-enabled

+

Run a Node on Ropsten Testnet

+

Replace <path> with the path to the /pantheon directory.

+

To run a node on Ropsten:

+

$ bin/pantheon --network-id=3 --genesis=<path>/pantheon/ethereum/core/src/main/resources/ropsten.json --bootnodes enode://6332792c4a00e3e4ee0926ed89e0d27ef985424d97b6a45bf0f23e51f0dcb5e66b875777506458aea7af6f9e4ffb69f43f3778ee73c81ed9d34c51c4b16b0b0f@52.232.243.152:30303,enode://94c15d1b9e2fe7ce56e458b9a3b672ef11894ddedd0c6f247e0f1d3487f52b66208fb4aeb8179fce6e3a749ea93ed147c37976d67af557508d199d9594c35f09@192.81.208.223:3030

+

To run a node on Ropsten with the HTTP JSON-RPC service enabled and allow Remix to access the node:

+

$ bin/pantheon --rpc-enabled --rpc-cors-origins "http://remix.ethereum.org" --network-id=3 --genesis=<path>/pantheon/ethereum/core/src/main/resources/ropsten.json --bootnodes enode://6332792c4a00e3e4ee0926ed89e0d27ef985424d97b6a45bf0f23e51f0dcb5e66b875777506458aea7af6f9e4ffb69f43f3778ee73c81ed9d34c51c4b16b0b0f@52.232.243.152:30303,enode://94c15d1b9e2fe7ce56e458b9a3b672ef11894ddedd0c6f247e0f1d3487f52b66208fb4aeb8179fce6e3a749ea93ed147c37976d67af557508d199d9594c35f09@192.81.208.223:3030

+

Run a Node on Rinkeby Testnet

+

Replace <path> with the path where the Rinkeby chain data is to be saved.

+

To run a node on Rinkeby specifying a data directory:

+

$ bin/pantheon --rinkeby --datadir=<path>/rinkebyDataDir

+

Run a Node for Testing

+

To run a node that mines blocks at a rate suitable for testing purposes:

+

$ bin/pantheon --dev-mode --bootnodes= --miner-enabled --miner-coinbase fe3b557e8fb62b89f4916b721be55ceb828dbd73 --rpc-cors-origins "all" --ws-enabled --rpc-enabled

+

Using Pantheon

+

Using Pantheon

+

[This is preliminary content for the Pantheon Alpha release.]

+

Contents

+ +

Creating and Sending Transactions

+

Transactions

+

Signed transactions can be sent using the eth_sendRawTransaction JSON-RPC API method.

+

To avoid exposing your private keys, create signed transactions offline.

+

The examples all use the following libraries to create signed transactions:

+ +

Note: Other libraries (for example, webj3 or ethereumj) and tools (for example, MyEtherWallet or mycrypto.com) can also be used to create signed transactions.

+

Example JS scripts are provided below to create signed raw transactions to:

+ +

The example JS scripts can be used to create raw transactions to send in the private network created by the Docker Quickstart. The HTTP JSON-RPC endpoint in the examples must be updated to the endpoint for private network.

+

Run a JS script to create and display the transaction string. For example:

+

node create_signed_raw_transaction.js

+

To send a signed transaction, run:

+
curl -X POST --data '{"jsonrpc":"2.0","method":"eth_sendRawTransaction","params":["raw_transaction_string"],"id":1}' <JSON-RPC-endpoint:port>

Where:

+
    +
  • raw_transaction_string is the signed raw transaction string.
    • +
  • <JSON-RPC-endpoint:port> is the JSON-RPC HTTP endpoint.
    • +
+

For example:

+
curl -X POST --data '{"jsonrpc":"2.0","method":"eth_sendRawTransaction","params":["0xf86a808203e882520894f17f52151ebef6c7334fad080c5704d77216b732896c6b935b8bbd400000801ca08ce4a6c12f7f273321c5dc03910744f8fb11573fcce8140aa44486d385d22fb3a051f6bcc918bf3f12e06bfccfd1451bea5c517dffee0777ebd50caf177b17f383"],"id":1}' http://localhost:8545

Sending Ether

+

The following is an example of JS script that displays a signed transaction string to send ether.

+
const web3 = require('web3')
+const ethTx = require('ethereumjs-tx')
+
+// web3 initialization - must point to the HTTP JSON-RPC endpoint
+const web3 = new Web3(new Web3.providers.HttpProvider('http://127.0.0.1:8545'))
+
+// Sender address and private key
+// Exclude 0x at the beginning of the private key
+const addressFrom = '0x627306090abaB3A6e1400e9345bC60c78a8BEf57'
+const privKey = Buffer.from('c87509a1c067bbde78beb793e6fa76530b6382a4c0241e5e4a9ec0a0f44dc0d3', 'hex')
+
+// Receiver address and value to transfer
+const addressTo = '0xf17f52151EbEF6C7334FAD080c5704D77216b732'
+const valueInEther = 2000
+
+// Get the address transaction count - required so we use the correct nonce)
+txnCount = web3.eth.getTransactionCount(addressFrom);
+
+// Create the transaction object
+var txObject = {
+    nonce: web3.toHex(txnCount),
+    gasPrice: web3.toHex(1000),
+    gasLimit: web3.toHex(21000),
+    to: addressTo,
+    value: web3.toHex(web3.toWei(valueInEther, 'ether'))
+};
+
+// Sign the transaction with the private key
+const tx = new ethTx(txObject);
+tx.sign(privKey)
+
+//Convert to raw transaction string
+const serializedTx = tx.serialize();
+const rawTxHex = '0x' + serializedTx.toString('hex');
+
+console.log("Raw transaction string=" + rawTxHex)

Deploying a Contract

+

The following is an example of js script that displays a signed raw transaction string to deploy a contract.

+
const web3 = require('web3')
+const ethTx = require('ethereumjs-tx')
+
+// web3 initialization - must point to the HTTP JSON-RPC endpoint
+const web3 = new Web3(new Web3.providers.HttpProvider('http://127.0.0.1:8545'))
+
+// Deployer address and private key
+const addressFrom = '0xFE3B557E8Fb62b89F4916B721be55cEb828dBd73'
+const privKey = Buffer.from('8f2a55949038a9610f50fb23b5883af3b4ecb3c3bb792cbcefbd1542c692be63', 'hex')
+
+// Compiled contract hash - can obtain from Remix by clicking the Details button in the Compile tab. 
+// Compiled contract hash is value of data parameter in the WEB3DEPLOY section
+const contractData = '0x608060405234801561001057600080fd5b5060dc8061001f6000396000f3006080604052600436106049576000357c0100000000000000000000000000000000000000000000000000000000900463ffffffff1680633fa4f24514604e57806355241077146076575b600080fd5b348015605957600080fd5b50606060a0565b6040518082815260200191505060405180910390f35b348015608157600080fd5b50609e6004803603810190808035906020019092919050505060a6565b005b60005481565b80600081905550505600a165627a7a723058202bdbba2e694dba8fff33d9d0976df580f57bff0a40e25a46c398f8063b4c00360029'
+
+// Get the address transaction count (so we use the correct nonce)
+txnCount = web3.eth.getTransactionCount(addressFrom);
+
+var txObject = {
+   nonce: web3.toHex(txnCount),
+   gasPrice: web3.toHex(1000),
+   gasLimit: web3.toHex(126165),
+   data: contractData
+};
+
+const tx = new ethTx(txObject);
+tx.sign(privKey)
+
+const serializedTx = tx.serialize();
+const rawTxHex = '0x' + serializedTx.toString('hex');
+
+console.log("Raw transaction string=" + rawTxHex);

eth_call or eth_sendRawTransaction

+

You can interact with contracts using eth_call or eth_sendRawTransaction.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
eth_calleth_sendRawTransaction
Read-onlyWrite
Invokes contract function locallyBroadcasts to network
Does not change state of blockchainUpdates blockchain (for example, transfers ether between accounts)
Does not consume gasRequires gas
SynchronousAsynchronous
Return value of contract function available immediatelyReturns transaction hash only. Possible transaction may not be included in a block (for example, if the gas price is too low)
+

Filters

+

Filters

+

Explains how to query block status using filters.

+

Testing and Developing Nodes

+

Testing and Developing Nodes

+

Explains how to set networks and configure genesis files for test and development.

+

Mining

+

Mining

+

Explains how to mine blocks.

+

Debugging Pantheon

+

FAQ

+
    +

  • How do I tell if my firewall is correctly configured to accept incoming connections? +** pantheon.log lists incoming connections. If you see "Successfully accepted connection from" in the log, connections are getting through the firewalls. Example:

    +

    2018-10-16 12:37:35.479-04:00 | nioEventLoopGroup-3-1 | INFO | NettyP2PNetwork | Successfully accepted connection from 0xa979fb575495b8d6db44f750317d0f4622bf4c2aa3365d6af7c284339968eef29b69ad0dce72a4d8db5ebb4968de0e3bec910127f134779fbcb0cb6d3331163c

    +
    • +
+

Pantheon CLI Reference

+

Pantheon Command Line Interface Reference

+

This reference describes the syntax of the Pantheon Command Line Interface (CLI) options and subcommands.

+
pantheon [OPTIONS] [COMMAND]

Runs the Pantheon Ethereum full node client.

+

Options

+
+
--bootnodes=<enode://id@host:port>[,<enode://id@host:port>...]...
+
A list of comma-separated enode URLs for P2P discovery bootstrap. The default is a predefined list of enode URLs.
+
+
--config=<PATH>
+
The path to the TOML configuration file. The default is none. The TOML file is composed of key/value pairs. Each key is the same as the corresponding CLI option name without the leading dashes (--). The config option is not used in the config file. Values must be treated according to TOML specifications for string, numbers, arrays and Booleans. + +Example: +# Valid TOML config file +datadir="~/pantheondata" # Path + +# Network +bootnodes=["enode://001@123:4567", "enode://002@123:4567", "enode://003@123:4567"] +p2p-listen="1.2.3.4:1234" # IP:port +max-peers=42 +rpc-listen="5.6.7.8:5678" # IP:port +ws-listen="9.10.11.12:9101" # IP:port + +# Chain +genesis="~/genesis.json" # Path to the custom genesis file +sync-mode="fast"# should be FAST or FULL (or fast or full) + +# Mining +miner-enabled=true +miner-coinbase="0x0000000000000000000000000000000000000002" +
+
+
--datadir=<PATH>
+
The path to the Pantheon data directory. The default location is the /build/distributions/pantheon-1.0.0-SNAPSHOT directory in the Pantheon installation directory.
+
+
--dev-mode
+
+ Set this option to true to run nodes in development mode which means you can run nodes in private or test networks. This is useful, for example, to do CPU mining more easily. In development mode, you use a custom genesis file that specifies a particular chain ID. When you set this option, you should also set the --network-id option to the specific network you use for development. The default is false. +
+
+
--genesis=<PATH>
+
The path to the genesis file. The default is the embedded genesis file in the Pantheon mainnet.
+
+
--max-peers=<INTEGER>
+
Specifies the maximium P2P peer connections that can be established. The default is 25.
+
+
--max-trailing-peers=<INTEGER>
+
Specifies the maximium P2P peer connections for peers that are trailing behind the chain head. The default is unlimited.
+
+
--miner-coinbase=<Ethereum account address>
+
The account to which mining rewards are to be paid. You must specify a coinbase if you enable mining.
+
+
--miner-enabled
+
Set this option to true when the node performs mining. The default is false.
+
+
--miner-extraData=<Extra data>
+
A hex string representing the 32 bytes to be included in the extra data field of a mined block. The default is 0x.
+
+
--miner-minTransactionGasPriceWei=<minTransactionGasPrice>
+
The minimum price that a transaction offers for it to be included in a mined block The default is 1000.
+ +
+
--network-id=<INTEGER>
+
P2P network identifier. The default is set to mainnet with value 1.
+ +
+
--no-discovery
+
Disables P2P peer discovery. The default is false.
+
+
--ottoman
+
Synchronize against the Ottoman test network. This is only useful if you are using an IBFT genesis file. For more information, see IBFT consensus protocol PR #650. The default is false.
+
+
--p2p-listen=<HOST:PORT>
+
Specifies the host and port on which P2P peer discovery listens. The default is 127.0.0.1:30303.
+
+
--rinkeby
+
Uses the Rinkeby test network.
+
+
--rpc-enabled
+
Set to true to enable the JSON-RPC service (RPC over HTTP). The default is false.
+
+
--rpc-listen=<HOST:PORT>
+
Specifies the host and port on which JSON-RPC listens. The default is 127.0.0.1:8545.
+
+
--rpc-api=<api name>[,...]...
+
Comma-separated APIs to enable on the JSON-RPC channel. The --rpc-enabled option must be specified with this option. The default is: ETH, NET, WEB3. The DEBUG and MINER APIs can also be enabled.
+
+
--rpc-cors-origins=<rpcCorsAllowedOrigins>
+
+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: + +--rpc-cors-origins "http://remix.ethereum.org" + +Note: 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 "none". 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: + +--rpc-cors-origins "http://foo.com, https://bar.io" + +For development purposes, you can use "all" to accept requests from any domain, but we don't recommend this for production code. +
+ +
+
--sync-mode=<MODE>
+
Synchronization mode. Value can be FULL or FAST. The default is FULL.
+
+
--ws-enabled
+
Set to true to enable the WS-RPC (WebSockets) service. The default is false.
+
+
--ws-api=<api name>[,...]... +
+
Comma-separated APIs to enable on Websockets channel. The --ws-enabled option must be specified with this option. The default is: ETH, NET, WEB3. The DEBUG and MINER APIs can also be enabled.
+ +
+
--ws-listen=<HOST:PORT>
+
Host and port for WS-RPC (Websocket) to listen on. The default is 127.0.0.1:8546.
+ +
+
-h, --help
+
Show the help message and exit.
+
+
-V, --version
+
Print version information and exit.
+
+ +
+

Commands

+

The import subcommand imports blocks from the specified file into the blockchain database:

+

pantheon import <block-file>

+


+
+

Pantheon is licensed under Apache License 2.0.

+

JSON-RPC API Reference

+

Contents

+ +

Pantheon JSON-RPC API

+

[This content is preliminary and will be published pending tech review for the Pantheon Alpha release.]

+

The Pantheon JSON-RPC API uses the JSON (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).

+

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.

+

Using the Pantheon JSON-RPC API

+

Endpoint Address and Port

+

In this reference, the placeholder +<JSON-RPC-http-endpoint:port> and <JSON-RPC-ws-endpoint:port> 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 --rpc-listen and --ws-listen options in the CLI documentation.

+

The transport attributes are:

+
    +
  • HTTP: Listens by default on port 8545
    • +
  • WebSockets: Listens by default on port 8546
    • +
  • IPC Socket: Listens by default on $BASE/jsonrpc.ipc
    • +
+

HTTP and WebSocket Requests

+

HTTP

+

To make RPC over HTTP requests, you can use the curl tool, available in many systems using curl source code or pre-compiled packages.

+
curl -X POST --data '{"jsonrpc":"2.0","method":"web3_clientVersion","params":[],"id":53}' <JSON-RPC-http-endpoint:port>

WebSockets

+

To make requests over WebSockets, this reference uses wscat, a Node.js based command-line tool.

+

First connect to the WebSockets server using wscat (you only need to connect once per session):

+
wscat -c ws://<JSON-RPC-ws-endpoint:port>

After the connection is established, the terminal will display a '>' prompt. Send individual requests as a JSON data package at each prompt:

+
{"jsonrpc":"2.0","method":"web3_clientVersion","params":[],"id":53}

Block Parameter

+

When you make requests that might have different results depending on the block accessed, the block parameter specifies the block. Several methods, such as eth_getTransactionByBlockNumberAndIndex, have a block parameter.

+

The block parameter can have the following values:

+
    +
  • blockNumber : quantity - Block number. Can be specified in hexadecimal or decimal. 0 represents the genesis block.
    • +
  • earliest : tag - Earliest (genesis) block.
    • +
  • latest : tag - Last block mined.
    • +
  • pending : tag - Last block mined plus pending transactions.
    • +
+

JSON-RPC Methods

+

[Note for Alpha release: The following lists only the Pantheon JSON-RPC API commands that are currently fully or partially implemented.]

+

The following lists the Pantheon JSON-RPC API commands:

+

web3 Methods

+ +

net Methods

+ +

eth Methods

+ +
+

JSON-RPC API Reference

+
+

web3_clientVersion

+

Returns the current client version.

+
Parameters
+

None

+
Returns
+

result : string - The current client version.

+
Request Data
+
{"jsonrpc":"2.0","method":"web3_clientVersion","params":[],"id":53}

For an explanation of how to make an HTTP or WebSockets request using this data, see HTTP and WebSocket Requests.

+
Result
+
{
+  "jsonrpc" : "2.0",
+  "id" : 53,
+  "result" : "pantheon/1.0.0-SNAPSHOT"
+}
+

web3_sha3

+

Returns a SHA3 hash of the specified data. The result value is a Keccak-256 hash, not the standardized SHA3-256.

+
Parameters
+

DATA - The data to convert to a SHA3 hash.

+
Returns
+

result (DATA) - The SHA3 result of the input data.

+
Request
+
curl -X POST --data '{"jsonrpc":"2.0","method":"web3_sha3","params":["0x68656c6c6f20776f726c00"],"id":53}' <JSON-RPC-endpoint:port>
Result
+
{
+  "jsonrpc" : "2.0",
+  "id" : 53,
+  "result" : "0x5e39a0a66544c0668bde22d61c47a8710000ece931f13b84d3b2feb44ec96d3f"
+}
+

net_version

+

Returns the current network ID.

+
Parameters
+

None

+
Returns
+

result : string - The current network ID.

+
    +
  • 1 - Ethereum Mainnet
    • +
  • 2 - Morden Testnet (deprecated)
    • +
  • 3 - Ropsten Testnet
    • +
  • 4 - Rinkeby Testnet
    • +
  • 42 - Kovan Testnet
    • +
+
Request
+
curl -X POST --data '{"jsonrpc":"2.0","method":"net_version","params":[],"id":53}' <JSON-RPC-endpoint:port>
Result
+

Mainnet:

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

Ropsten:

+
{
+  "jsonrpc" : "2.0",
+  "id" : 53,
+  "result" : "3"
+}
+

net_listening

+

Indicates whether the client is actively listening for network connections.

+
Parameters
+

None

+
Returns
+

result (BOOLEAN) - true if the client is actively listening for network connections; otherwise false.

+
Request
+
curl -X POST --data '{"jsonrpc":"2.0","method":"net_listening","params":[],"id":53}' <JSON-RPC-endpoint:port>
Result
+
{
+  "jsonrpc" : "2.0",
+  "id" : 53,
+  "result" : true
+}
+

net_peerCount

+

Returns the number of peers currently connected to the client.

+
Parameters
+

None

+
Returns
+

result : integer - The number of connected peers in hexadecimal.

+
Request
+
curl -X POST --data '{"jsonrpc":"2.0","method":"net_peerCount","params":[],"id":53}' <JSON-RPC-endpoint:port>
Result
+
{
+  "jsonrpc" : "2.0",
+  "id" : 53,
+  "result" : "0x5"
+}
+

eth_syncing

+

Returns an object with data about the sync status, or FALSE if not syncing.

+
Parameters
+

None

+
Returns
+

result : Object|Boolean - An object with sync status data or FALSE, when not syncing:

+
    +
  • startingBlock : QUANTITY - The block at which the import started (will only be reset, after the sync reached his head).
    • +
  • currentBlock : QUANTITY - The current block, same as eth_blockNumber.
    • +
  • highestBlock: QUANTITY - The estimated highest block.
    • +
+
Request
+
curl -X POST --data '{"jsonrpc":"2.0","method":"eth_syncing","params":[],"id":51}' <JSON-RPC-endpoint:port>
Result
+
{
+  "jsonrpc" : "2.0",
+  "id" : 51,
+  "result" : {
+    "startingBlock" : "0x1d4bff",
+    "currentBlock" : "0x1d4bff",
+    "highestBlock" : "0x0"
+  }
+

eth_coinbase

+

Returns the client coinbase address.

+

To set a coinbase address, call the pantheon CLI with the --miner-coinbase option set to a valid Ethereum account address. You can get the Ethereum account address from a client such as MetaMask or Etherscan. For example:

+
bin/pantheon --genesis=/home/donn/pantheon/ethereum/core/src/main/resources/ropsten.json --miner-coinbase="0xDD37f65dB31c107F773E82a4F85C693058fEf7a9" --dev-mode=true --rpc-enabled
Parameters
+

None

+
Returns
+

result (DATA, 20 bytes) - The current coinbase address.

+
Request
+
curl -X POST --data '{"jsonrpc":"2.0","method":"eth_coinbase","params":[],"id":53}' <JSON-RPC-endpoint:port>
Result
+
{
+  "jsonrpc" : "2.0",
+  "id" : 53,
+  "result" : "0xdd37f65db31c107f773e82a4f85c693058fef7a9"
+}
Errors
+

If you have not specified a coinbase, you will receive this message:

+
{
+  "jsonrpc" : "2.0",
+  "id" : 53,
+  "error" : {
+    "code" : -32000,
+    "message" : "Coinbase must be explicitly specified"
+  }
+}
+

eth_mining

+

Indicates whether the client is actively mining new blocks.

+
Parameters
+

None

+
Returns
+

result (BOOLEAN) - true if the client is actively mining new blocks; otherwise false.

+
Request
+
curl -X POST --data '{"jsonrpc":"2.0","method":"eth_mining","params":[],"id":53}' <JSON-RPC-endpoint:port>
Result
+
{
+  "jsonrpc" : "2.0",
+  "id" : 53,
+  "result" : true
+}
+

eth_gasPrice

+

Returns the current gas unit price in wei.

+
Parameters
+

None

+
Returns
+

result (QUANTITY) - Integer value representing the current gas unit price in wei.

+
Request
+
curl -X POST --data '{"jsonrpc":"2.0","method":"eth_gasPrice","params":[],"id":53}' <JSON-RPC-endpoint:port>
Result
+
{
+  "jsonrpc" : "2.0",
+  "id" : 53,
+  "result" : "0x3e8"
+}
+

eth_accounts

+

Returns a list of account addresses that the client owns.

+

NOTE: This method returns an empty object; this is the correct behavior, not a malfunction, and simply reflects the current state of mainnet.

+
+ +
Parameters
+

None

+
Returns
+

Array of DATA : A list of 20-byte account addresses that the client owns.

+
Request
+
curl -X POST --data '{"jsonrpc":"2.0","method":"eth_accounts","params":[],"id":53}'  <JSON-RPC-endpoint:port>
Result
+
{
+  "jsonrpc" : "2.0",
+  "id" : 53,
+  "result" : [ ]
+}
+

eth_blockNumber

+

Returns the index of the current block the client is processing.

+
Parameters
+

None

+
Returns
+

result : QUANTITY - Hexadecimal integer representing the 0-based index of the block that the client is currently processing.

+
Request
+
curl -X POST --data '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":51}' <JSON-RPC-endpoint:port>
Result
+
{
+  "jsonrpc" : "2.0",
+  "id" : 51,
+  "result" : "0x2377"
+}
+

eth_getBalance

+

Returns the account balance of the specified address.

+
Parameters
+

DATA - 20-byte account address from which to retrieve the balance.

+

QUANTITY|TAG - Integer representing a block number or one of the string tags latest, earliest, or pending, as described in Block Parameter.

+
Returns
+

result : QUANTITY - Integer value of the current balance in wei.

+
Request
+
curl -X POST --data '{"jsonrpc":"2.0","method":"eth_getBalance","params":["0xdd37f65db31c107f773e82a4f85c693058fef7a9", "latest"],"id":53}' <JSON-RPC-endpoint:port>
Result
+
{
+  "jsonrpc" : "2.0",
+  "id" : 53,
+  "result" : "0x0"
+}
+

eth_getStorageAt

+

Returns the value of a storage position at a specified address.

+
Parameters
+

DATA - A 20-byte storage address.

+

QUANTITY - Integer index of the storage position.

+

QUANTITY|TAG - Integer representing a block number or one of the string tags latest, earliest, or pending, as described in Block Parameter.

+
Returns
+

result : DATA - The value at the specified storage position.

+
Request
+

Calculating the correct position depends on the storage you want to retrieve.

+
curl -X POST --data '{"jsonrpc":"2.0","method": "eth_getStorageAt","params": ["0x‭3B3F3E‬","0x0","latest"],"id": 53}' <JSON-RPC-endpoint:port>
Result
+
{
+  "jsonrpc" : "2.0",
+  "id" : 53,
+  "result" : "0x0000000000000000000000000000000000000000000000000000000000000000"
+}
+

eth_getTransactionCount

+

Returns the number of transactions sent from a specified address.

+
Parameters
+

DATA - A 20-byte account address.

+

QUANTITY|TAG - Integer representing a block number or one of the string tags latest, earliest, or pending, as described in Block Parameter.

+
Returns
+

result : QUANTITY - Integer representing the number of transactions sent from the specified address.

+
Request
+
curl -X POST --data '{"jsonrpc":"2.0","method":"eth_getTransactionCount","params":["0xc94770007dda54cF92009BFF0dE90c06F603a09f","latest"],"id":1}' <JSON-RPC-endpoint:port>
Result
+
{
+  "jsonrpc" : "2.0",
+  "id" : 1,
+  "result" : "0x1"
+}
+

eth_getBlockTransactionCountByHash

+

Returns the number of transactions in the block matching the given block hash.

+
Parameters
+

DATA - A 32-byte block hash.

+
Returns
+

result : QUANTITY - Integer representing the number of transactions in the specified block.

+
Request
+
curl -X POST --data '{"jsonrpc":"2.0","method":"eth_getBlockTransactionCountByHash","params":["0xb903239f8543d04b5dc1ba6579132b143087c68db1b2168786408fcbce568238"],"id":53}' <JSON-RPC-endpoint:port>
Result
+
{
+  "jsonrpc" : "2.0",
+  "id" : 53,
+  "result" : null
+}
+

eth_getBlockTransactionCountByNumber

+

Returns the number of transactions in a block matching the specified block number.

+
Parameters
+

QUANTITY|TAG - Integer representing a block number or one of the string tags latest, earliest, or pending, as described in Block Parameter.

+
Returns
+

result : QUANTITY - Integer representing the number of transactions in the specified block.

+
Request
+
curl -X POST --data '{"jsonrpc":"2.0","method":"eth_getBlockTransactionCountByNumber","params":["0xe8"],"id":51}' <JSON-RPC-endpoint:port>
Result
+
{
+  "jsonrpc" : "2.0",
+  "id" : 51,
+  "result" : "0x8"
+}
+

eth_getUncleCountByBlockHash

+

Returns the number of uncles in a block from a block matching the given block hash.

+
Parameters
+

DATA - A 32-byte block hash.

+
Returns
+

result : QUANTITY - Integer representing the number of uncles in the specified block.

+
Request
+
curl -X POST --data '{"jsonrpc":"2.0","method":"eth_getUncleCountByBlockHash","params":["0xb903239f8543d04b5dc1ba6579132b143087c68db1b2168786408fcbce568238"],"id":1}' <JSON-RPC-endpoint:port>
Result
+
{
+  "jsonrpc" : "2.0",
+  "id" : 1,
+  "result" : null
+}
+

eth_getUncleCountByBlockNumber

+

Returns the number of uncles in a block matching the specified block number.

+
Parameters
+

QUANTITY|TAG - Integer representing either the 0-based index of the block within the blockchain, or one of the string tags latest, earliest, or pending, as described in Block Parameter.

+
Returns
+

result : QUANTITY - Integer representing the number of uncles in the specified block.

+
Request
+
curl -X POST --data '{"jsonrpc":"2.0","method":"eth_getUncleCountByBlockNumber","params":["0xe8"],"id":1}' <JSON-RPC-endpoint:port>
Result
+
{
+  "jsonrpc" : "2.0",
+  "id" : 1,
+  "result" : "0x1"
+}
+

eth_getCode

+

Returns the code of the smart contract at the specified address. Compiled smart contract code is stored as a hexadecimal value.

+
Parameters
+

DATA - 20-byte contract address.

+

QUANTITY|TAG - Integer representing a block number or one of the string tags latest, earliest, or pending, as described in Block Parameter.

+
Returns
+

result : DATA - Code stored at the specified address.

+
Request
+
curl -X POST --data '{"jsonrpc":"2.0","method":"eth_getCode","params":["0xa50a51c09a5c451c52bb714527e1974b686d8e77", "latest"],"id":53}' <JSON-RPC-endpoint:port>
Result
+
{
+    "jsonrpc": "2.0",
+    "id": 53,
+    "result": "0x60806040526004361060485763ffffffff7c01000000000000000000000000000000000000000000000000000000006000350416633fa4f2458114604d57806355241077146071575b600080fd5b348015605857600080fd5b50605f6088565b60408051918252519081900360200190f35b348015607c57600080fd5b506086600435608e565b005b60005481565b60008190556040805182815290517f199cd93e851e4c78c437891155e2112093f8f15394aa89dab09e38d6ca0727879181900360200190a1505600a165627a7a723058209d8929142720a69bde2ab3bfa2da6217674b984899b62753979743c0470a2ea70029"
+}
+

eth_sendRawTransaction

+

Sends a signed transaction. A transaction can send ether, deploy a contract, or interact with a contract.

+

You can interact with contracts using eth_sendRawTransaction or eth_call.

+

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 eth_sendRawTransaction, refer to Using Pantheon.

+

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.

+
Parameters
+

DATA - Hash of the signed raw transaction in hexadecimal format; for example:

+
params: ["0xd46e8dd67c5d32be8d46e8dd67c5d32be8058bb8eb970870f072445675058bb8eb970870f072445675"]
Returns
+

result : DATA - 32-byte transaction hash, or zero hash if the transaction is not yet available.

+
Request
+
curl -X POST --data '{"jsonrpc":"2.0","method":"eth_sendRawTransaction","params":["0xd46e8dd67c5d32be8d46e8dd67c5d32be8058bb8eb970870f072445675058bb8eb970870f072445675"],"id":1}' <JSON-RPC-endpoint:port>
Result
+
{
+  "id":1,
+  "jsonrpc": "2.0",
+  "result": "0xe670ec64341771606e55d6b4ca35a1a6b75ee3d5145a99d05921026d1527331"
+}
+

eth_call

+

Invokes a contract function locally and does not change the state of the blockchain.

+

You can interact with contracts using eth_sendRawTransaction or eth_call.

+
Parameters
+

OBJECT - Transaction call object.

+

QUANTITY|TAG - Integer representing a block number or one of the string tags latest, earliest, or pending, as described in Block Parameter.

+
Returns
+

result (DATA) - Return value of the executed contract.

+
Request
+
curl -X POST --data '{"jsonrpc":"2.0","method":"eth_call","params":[{"from":"0xdd37f65db31c107f773e82a4f85c693058fef7a9","to":"0x69498dd54bd25aa0c886cf1f8b8ae0856d55ff13","value":"0.1"}],"id":53}' <JSON-RPC-endpoint:port>
Result
+
{
+  "jsonrpc" : "2.0",
+  "id" : 53,
+  "error" : {
+    "code" : -32602,
+    "message" : "Invalid params"
+  }
+}
+

eth_estimateGas

+

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.

+
Parameters
+
+

NOTE: Parameters are the same as the eth_call parameters, except that all properties are optional. If you do not specify a gas 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.

+
+

OBJECT - Transaction call object.

+

QUANTITY|TAG - Integer representing a block number or one of the string tags latest, earliest, or pending, as described in Block Parameter.

+
Returns
+

result (QUANTITY) - The amount of gas used.

+
Request
+
curl -X POST --data '{"jsonrpc":"2.0","method":"eth_estimateGas","params":[{"from":"0x687422eea2cb73b5d3e242ba5456b782919afc85","to":"0xdd37f65db31c107f773e82a4f85c693058fef7a9","value":"0x1"}],"id":53}' <JSON-RPC-endpoint:port>
Result
+

The following result yields a gas amount estimate of 21000 wei (0x5208) for the transaction.

+
{
+  "jsonrpc" : "2.0",
+  "id" : 54,
+  "result" : "0x5208"
+}
+

eth_getBlockByHash

+

Returns information about the block by hash.

+
Parameters
+

DATA - 32-byte hash of a block.

+

Boolean - If true, returns the full transaction objects; if false, returns the transaction hashes.

+
Returns
+

result : OBJECT - Block object , or null when no block is found.

+
Request
+
curl -X POST --data '{"jsonrpc":"2.0","method":"eth_getBlockByHash","params":["0x16b69965a5949262642cfb5e86368ddbbe57ab9f17d999174a65fd0e66580d8f", false],"id":53}' <JSON-RPC-endpoint:port>
Result
+
{
+  "jsonrpc" : "2.0",
+  "id" : 53,
+  "result" : {
+    "number" : "0x7",
+    "hash" : "0x16b69965a5949262642cfb5e86368ddbbe57ab9f17d999174a65fd0e66580d8f",
+    "parentHash" : "0xe9bd4b277983580ef0eabad6011891f8b6aff9381a78bd1c4faca374a48b3e09",
+    "nonce" : "0x46acb59e85b5bb6d",
+    "sha3Uncles" : "0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347",
+    "logsBloom" : "0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
+    "transactionsRoot" : "0x7aa0913c235f272eb6ed6ab74ba5a057e0a62c1c1d1dbccfd971221e6b6e83a3",
+    "stateRoot" : "0xfaf6520d6e3d24107a4309855593341ab87a1744dbb6eea4e709b92e9c9107ca",
+    "receiptsRoot" : "0x056b23fbba480696b65fe5a59b8f2148a1299103c4f57df839233af2cf4ca2d2",
+    "miner" : "0xfe3b557e8fb62b89f4916b721be55ceb828dbd73",
+    "difficulty" : "0x5",
+    "totalDifficulty" : "0x10023",
+    "extraData" : "0x",
+    "size" : "0x270",
+    "gasLimit" : "0x1000000",
+    "gasUsed" : "0x5208",
+    "timestamp" : "0x5bbbe99f",
+    "uncles" : [ ],
+    "transactions" : [ "0x2cc6c94c21685b7e0f8ddabf277a5ccf98db157c62619cde8baea696a74ed18e" ]
+  }
+}
+

eth_getBlockByNumber

+

Returns information about a block by block number.

+
Parameters
+

QUANTITY|TAG - Integer representing a block number or one of the string tags latest, earliest, or pending, as described in Block Parameter.

+

Boolean - If true, returns the full transaction objects; if false, returns only the hashes of the transactions.

+
Returns
+

result : OBJECT - Block object , or null when no block is found.

+
Request
+
curl -X POST --data '{"jsonrpc":"2.0","method":"eth_getBlockByNumber","params":["0x64", true],"id":1}' <JSON-RPC-endpoint:port>
Result
+
{
+  "jsonrpc" : "2.0",
+  "id" : 1,
+  "result" : {
+    "number" : "0x64",
+    "hash" : "0xdfe2e70d6c116a541101cecbb256d7402d62125f6ddc9b607d49edc989825c64",
+    "parentHash" : "0xdb10afd3efa45327eb284c83cc925bd9bd7966aea53067c1eebe0724d124ec1e",
+    "nonce" : "0x37129c7f29a9364b",
+    "sha3Uncles" : "0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347",
+    "logsBloom" : "0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
+    "transactionsRoot" : "0x56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421",
+    "stateRoot" : "0x90c25f6d7fddeb31a6cc5668a6bba77adbadec705eb7aa5a51265c2d1e3bb7ac",
+    "receiptsRoot" : "0x56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421",
+    "miner" : "0xbb7b8287f3f0a933474a79eae42cbca977791171",
+    "difficulty" : "0x42be722b6",
+    "totalDifficulty" : "0x19b5afdc486",
+    "extraData" : "0x476574682f4c5649562f76312e302e302f6c696e75782f676f312e342e32",
+    "size" : "0x21e",
+    "gasLimit" : "0x1388",
+    "gasUsed" : "0x0",
+    "timestamp" : "0x55ba43eb",
+    "uncles" : [ ],
+    "transactions" : [ ]
+  }
+}
+

eth_getTransactionByHash

+

Returns transaction information for the specified transaction hash.

+
Parameters
+

DATA - 32-byte transaction hash.

+
Returns
+

Object - Transaction object, or null when no transaction is found.

+
Request
+
curl -X POST --data '{"jsonrpc":"2.0","method":"eth_getTransactionByHash","params":["0xa52be92809541220ee0aaaede6047d9a6c5d0cd96a517c854d944ee70a0ebb44"],"id":53}' <JSON-RPC-endpoint:port>
Result
+
{
+  "jsonrpc" : "2.0",
+  "id" : 53,
+  "result" : {
+    "blockHash" : "0x510efccf44a192e6e34bcb439a1947e24b86244280762cbb006858c237093fda",
+    "blockNumber" : "0x422",
+    "from" : "0xfe3b557e8fb62b89f4916b721be55ceb828dbd73",
+    "gas" : "0x5208",
+    "gasPrice" : "0x3b9aca00",
+    "hash" : "0xa52be92809541220ee0aaaede6047d9a6c5d0cd96a517c854d944ee70a0ebb44",
+    "input" : "0x",
+    "nonce" : "0x1",
+    "to" : "0x627306090abab3a6e1400e9345bc60c78a8bef57",
+    "transactionIndex" : "0x0",
+    "value" : "0x4e1003b28d9280000",
+    "v" : "0xfe7",
+    "r" : "0x84caf09aefbd5e539295acc67217563438a4efb224879b6855f56857fa2037d3",
+    "s" : "0x5e863be3829812c81439f0ae9d8ecb832b531d651fb234c848d1bf45e62be8b9"
+  }
+}
+

eth_getTransactionByBlockHashAndIndex

+

Returns transaction information for the specified block hash and transaction index position.

+
Parameters
+

DATA - 32-byte hash of a block.

+

QUANTITY - Integer representing the transaction index position.

+
Returns
+

Object - Transaction object, or null when no transaction is found.

+
Request
+

This request returns the 3rd transaction in the 82990 block on the Ropsten testnet. You can also view this block and transaction on Etherscan.

+

Note: You must be synchronized to at least the block containing the transaction for the request to return it.

+
curl -X POST --data '{"jsonrpc":"2.0","method":"eth_getTransactionByBlockHashAndIndex","params":["0xbf137c3a7a1ebdfac21252765e5d7f40d115c2757e4a4abee929be88c624fdb7", "0x2"], "id":1}' <JSON-RPC-endpoint:port>
Result
+
{
+  "jsonrpc" : "2.0",
+  "id" : 1,
+  "result" : {
+    "blockHash" : "0xbf137c3a7a1ebdfac21252765e5d7f40d115c2757e4a4abee929be88c624fdb7",
+    "blockNumber" : "0x1442e",
+    "from" : "0x70c9217d814985faef62b124420f8dfbddd96433",
+    "gas" : "0x3d090",
+    "gasPrice" : "0x57148a6be",
+    "hash" : "0xfc766a71c406950d4a4955a340a092626c35083c64c7be907060368a5e6811d6",
+    "input" : "0x51a34eb8000000000000000000000000000000000000000000000029b9e659e41b780000",
+    "nonce" : "0x2cb2",
+    "to" : "0xcfdc98ec7f01dab1b67b36373524ce0208dc3953",
+    "transactionIndex" : "0x2",
+    "value" : "0x0",
+    "v" : "0x2a",
+    "r" : "0xa2d2b1021e1428740a7c67af3c05fe3160481889b25b921108ac0ac2c3d5d40a",
+    "s" : "0x63186d2aaefe188748bfb4b46fb9493cbc2b53cf36169e8501a5bc0ed941b484"
+  }
+ }
+

eth_getTransactionByBlockNumberAndIndex

+

Returns transaction information for the specified block number and transaction index position.

+
Parameters
+

QUANTITY|TAG - Integer representing a block number or one of the string tags latest, earliest, or pending, as described in Block Parameter.

+

QUANTITY - The transaction index position.

+
Returns
+

Object - Transaction object, or null when no transaction is found.

+
Request
+

This request returns the 3rd transaction in the 82990 block on the Ropsten testnet. You can also view this block and transaction on Etherscan.

+

Note: You must be synchronized to at least the block containing the transaction for the request to return it.

+
curl -X POST --data '{"jsonrpc":"2.0","method":"eth_getTransactionByBlockNumberAndIndex","params":["82990", "0x2"], "id":1}' <JSON-RPC-endpoint:port>
Result
+
{
+  "jsonrpc" : "2.0",
+  "id" : 1,
+  "result" : {
+    "blockHash" : "0xbf137c3a7a1ebdfac21252765e5d7f40d115c2757e4a4abee929be88c624fdb7",
+    "blockNumber" : "0x1442e",
+    "from" : "0x70c9217d814985faef62b124420f8dfbddd96433",
+    "gas" : "0x3d090",
+    "gasPrice" : "0x57148a6be",
+    "hash" : "0xfc766a71c406950d4a4955a340a092626c35083c64c7be907060368a5e6811d6",
+    "input" : "0x51a34eb8000000000000000000000000000000000000000000000029b9e659e41b780000",
+    "nonce" : "0x2cb2",
+    "to" : "0xcfdc98ec7f01dab1b67b36373524ce0208dc3953",
+    "transactionIndex" : "0x2",
+    "value" : "0x0",
+    "v" : "0x2a",
+    "r" : "0xa2d2b1021e1428740a7c67af3c05fe3160481889b25b921108ac0ac2c3d5d40a",
+    "s" : "0x63186d2aaefe188748bfb4b46fb9493cbc2b53cf36169e8501a5bc0ed941b484"
+  }
+}
+

eth_getTransactionReceipt

+

Returns the receipt of a transaction by transaction hash. Receipts for pending transactions are not available.

+
Parameters
+

DATA - 32-byte hash of a transaction.

+
Returns
+

Object - Transaction receipt object, or null when no receipt is found.

+
Request
+
curl -X POST --data '{"jsonrpc":"2.0","method":"eth_getTransactionReceipt","params":["0x504ce587a65bdbdb6414a0c6c16d86a04dd79bfcc4f2950eec9634b30ce5370f"],"id":53}' <JSON-RPC-endpoint:port>
Result
+
{
+    "jsonrpc": "2.0",
+    "id": 1,
+    "result": {
+        "blockHash": "0xe7212a92cfb9b06addc80dec2a0dfae9ea94fd344efeb157c41e12994fcad60a",
+        "blockNumber": "0x50",
+        "contractAddress": null,
+        "cumulativeGasUsed": "0x5208",
+        "from": "0x627306090abab3a6e1400e9345bc60c78a8bef57",
+        "gasUsed": "0x5208",
+        "logs": [],
+        "logsBloom": "0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
+        "status": "0x1",
+        "to": "0xf17f52151ebef6c7334fad080c5704d77216b732",
+        "transactionHash": "0xc00e97af59c6f88de163306935f7682af1a34c67245e414537d02e422815efc3",
+        "transactionIndex": "0x0"
+    }
+}
+

eth_newFilter

+

Creates a topic filter with the specified options to notify (log) when the state changes. To determine whether the state has changed, call eth_getFilterChanges.

+
Parameters
+

Object - Filter options object.

+

Note: Topics are order-dependent. A transaction with a log containing topics [A, B] would be matched with the following topic filters:

+
    +
  • [] - Match any topic
    • +
  • [A] - Match A in first position (and any topic thereafter)
    • +
  • [null, B] - Match any topic in first position AND B in second position (and any topic thereafter)
    • +
  • [A, B] - Match A in first position AND B in second position (and any topic thereafter)
    • +
  • [[A, B], [A, B]] - Match (A OR B) in first position AND (A OR B) in second position (and any topic thereafter)
    • +
+

For example, params could be specified as follows:

+
params: [{
+  "fromBlock": "earliest",
+  "toBlock": "0x4",
+  "address": "0xc94770007dda54cF92009BFF0dE90c06F603a09f",
+  "topics": ["0x000000000000000000000000a94f5374fce5edbc8e2a8697c15331677e6ebf0b", null, ["0x000000000000000000000000a94f5374fce5edbc8e2a8697c15331677e6ebf0b", "0x0000000000000000000000000aff3454fce5edbc8cca8697c15331677e6ebccc"]]
+}]
Returns
+

result : QUANTITY - The filter ID.

+
Request
+
curl -X POST --data '{"jsonrpc":"2.0","method":"eth_newFilter","params":[{"topics":[]}],"id":53}' <JSON-RPC-endpoint:port>
Result
+
{
+  "jsonrpc" : "2.0",
+  "id" : 53,
+  "result" : "0x3"
+}

Invalid params error:

+
curl -X POST --data '{"jsonrpc":"2.0","method":"eth_newFilter","params":[{"fromBlock": "earliest","toBlock": "latest","address": "0xDD37f65dB31c107F773E82a4F85C693058fEf7a9","topics": []}],"id":53}' 127.0.0.1:8545
+
+{
+  "jsonrpc" : "2.0",
+  "id" : 53,
+  "error" : {
+    "code" : -32602,
+    "message" : "Invalid params"
+  }
+}
+

eth_newBlockFilter

+

Creates a filter in the node that notifies when a new block arrives. To determine whether the state has changed, call eth_getFilterChanges.

+
Parameters
+

None

+
Returns
+

QUANTITY - A hexadecimal integer filter ID. Each time you call this method, it creates a new filter, and the index is incremented by 1.

+
Request
+
curl -X POST --data '{"jsonrpc":"2.0","method":"eth_newBlockFilter","params":[],"id":53}' <JSON-RPC-endpoint:port>
Result
+

Assuming you have previously called eth_newBlockFilter two times, it will assign a filter ID of 3:

+
{
+  "jsonrpc" : "2.0",
+  "id" : 53,
+  "result" : "0x3"
+}
+

eth_newPendingTransactionFilter

+

Creates a filter in the node that notifies when new pending transactions arrive. To check if the state has changed, call eth_getFilterChanges.

+
Parameters
+

None

+
Returns
+

QUANTITY - A hexadecimal integer filter ID. Each time you call this method, it creates a new filter, and the index is incremented by 1.

+
Request
+
curl -X POST --data '{"jsonrpc":"2.0","method":"eth_newPendingTransactionFilter","params":[],"id":53}' <JSON-RPC-endpoint:port>
Result
+

Assuming you have previously called eth_newBlockFilter three times, it will assign a filter ID of 4:

+
{
+  "jsonrpc" : "2.0",
+  "id" : 53,
+  "result" : "0x4"
+}
+

eth_uninstallFilter

+

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 eth_getFilterChanges for a period of time.

+

This method deletes filters of any type: block filters, pending transaction filters, and state (topic) filters.

+
Parameters
+

QUANTITY - A hexadecimal integer filter ID specifying the filter to be deleted.

+
Returns
+

Boolean - true if the filter was successfully uninstalled; otherwise false.

+
Request
+

The following request deletes the block filter with an ID of 0x4:

+
curl -X POST --data '{"jsonrpc":"2.0","method":"eth_uninstallFilter","params":["0x4"],"id":53}' <JSON-RPC-endpoint:port>
Result
+
{
+  "jsonrpc" : "2.0",
+  "id" : 53,
+  "result" : true
+}
+

eth_getFilterChanges

+

Polls the specified filter and returns an array of logs that have occurred since the last poll.

+
Parameters
+

QUANTITY - A hexadecimal integer filter ID.

+
Returns
+

result : Array of Object - List of logs, or an empty array if nothing has changed since the last poll.

+
    +

  • For filters created with eth_newBlockFilter, returns 32-byte DATA block hashes; for example ["0x3454645634534..."].

    +
    • +

  • For filters created with eth_newPendingTransactionFilter, returns transaction hashes (32-byte DATA); for example ["0x6345343454645..."].

    +
    • +

  • For filters created with eth_newFilter, returns log objects.

    +
    • +
+
Request
+
curl -X POST --data '{"jsonrpc":"2.0","method":"eth_getFilterChanges","params":["0xa"]:"id":53}' <JSON-RPC-endpoint:port>
Result
+

The following response indicates that nothing has changed since the last poll:

+
{
+  "jsonrpc" : "2.0",
+  "id" : 53,
+  "result" : [ ]
+}
+

eth_getFilterLogs

+

Returns an array of logs matching the filter with the specified ID.

+
Parameters
+

QUANTITY - An integer representing the filter ID.

+
Returns
+

Same as eth_getFilterChanges.

+
Request
+

The following example requests logs for filter ID 0x16 (22 decimal):

+
curl -X POST --data '{"jsonrpc":"2.0","method":"eth_getFilterLogs","params":["0x3"]"id":53}' <JSON-RPC-endpoint:port>
Result
+
{
+  "jsonrpc" : "2.0",
+  "id" : 1,
+  "result" : [ {
+    "logIndex" : "0x0",
+    "removed" : false,
+    "blockNumber" : "0x14427",
+    "blockHash" : "0x677bf4b962464e6dfd548d6a30b6c703dd78c7cc3602825a7013a6e90a001d2a",
+    "transactionHash" : "0x7bf9876a9de3c0add38495e21a17b96c81b3f18e0990a4a3aecdf9f47fea0eed",
+    "transactionIndex" : "0x0",
+    "address" : "0xe8fe77d1576d0972d453b49bfaa84d716173d133",
+    "data" : "0x0000000000000000000000001046c9bdec0e634fbd7cf91afebd93cc854432b10000000000000000000000002101416eeaf73acb66d124f79efde9631662a83a0000000000000000000000006f72045702a34c473da863945221965c61528bd3",
+    "topics" : [ "0xc36800ebd6079fdafc3a7100d0d1172815751804a6d1b7eb365b85f6c9c80e61", "0x000000000000000000000000b344324aa2a82a6fda8459e40923e1fd65bfac36" ]
+  } ]
+}
+

eth_getLogs

+

Returns an array of all logs matching a specified filter object.

+
Parameters
+

Object - Filter options object

+
Returns
+

Same as eth_getFilterChanges.

+
Request
+

The request above returns the logs for the 82893 block on the Ropsten testnet. You can also view this block on Etherscan.

+

Note: You must be synchronised to at least the requested block for the request to return the logs.

+
curl -X POST --data '{"jsonrpc":"2.0","method":"eth_getLogs","params":[{"blockhash":"0x677bf4b962464e6dfd548d6a30b6c703dd78c7cc3602825a7013a6e90a001d2a"}], "id":1}' <JSON-RPC-endpoint:port>
Result
+
{
+  "jsonrpc" : "2.0",
+  "id" : 1,
+  "result" : [ {
+    "logIndex" : "0x0",
+    "removed" : false,
+    "blockNumber" : "0x14427",
+    "blockHash" : "0x677bf4b962464e6dfd548d6a30b6c703dd78c7cc3602825a7013a6e90a001d2a",
+    "transactionHash" : "0x7bf9876a9de3c0add38495e21a17b96c81b3f18e0990a4a3aecdf9f47fea0eed",
+    "transactionIndex" : "0x0",
+    "address" : "0xe8fe77d1576d0972d453b49bfaa84d716173d133",
+    "data" : "0x0000000000000000000000001046c9bdec0e634fbd7cf91afebd93cc854432b10000000000000000000000002101416eeaf73acb66d124f79efde9631662a83a0000000000000000000000006f72045702a34c473da863945221965c61528bd3",
+    "topics" : [ "0xc36800ebd6079fdafc3a7100d0d1172815751804a6d1b7eb365b85f6c9c80e61", "0x000000000000000000000000b344324aa2a82a6fda8459e40923e1fd65bfac36" ]
+  } ]
+}
+

eth_getWork

+

Returns the hash of the current block, the seed hash, and the target boundary condition to be met.

+
Parameters
+

None

+
Returns
+

result : Array of DATA with the following fields:

+
    +
  • DATA, 32 Bytes - Hash of the current block header (pow-hash).
    • +
  • DATA, 32 Bytes - The seed hash used for the DAG.
    • +
  • DATA, 32 Bytes - The target boundary condition to be met; 2^256 / difficulty.
    • +
+
Request
+
curl -X POST --data '{"jsonrpc":"2.0","method":"eth_getWork","params":[],"id":1}' <JSON-RPC-endpoint:port>
Result
+
{
+  "id":1,
+  "jsonrpc":"2.0",
+  "result": [
+      "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
+      "0x5EED00000000000000000000000000005EED0000000000000000000000000000",
+      "0xd1ff1c01710000000000000000000000d1ff1c01710000000000000000000000"
+    ]
+}
+

debug_traceTransaction

+

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.

+

You can use this method with tools such as Remix when you want to execute a transaction step-by-step.

+
Parameters
+

transactionHash : data - The transaction hash.

+

options : string - (Optional) Specifies request options as follows:

+
    +
  • disableStorage : BOOL - true disables storage capture. The default is false.
    • +
  • disableMemory : BOOL - true disables memory capture. The default is false.
    • +
  • disableStack : BOOL - true disables stack capture. The default is false.
    • +
  • tracer : STRING - 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, step and result:
      +
    • step is a function that takes two arguments, log and db. This function is called for each step of the EVM, or when an error occurs, as the specified transaction is traced.
      • +
    • log has the following fields:
        +
      • pc : number - The current program counter.
        • +
      • op : object - An OpCode object representing the current opcode.
        • +
      • gas : number - The amount of gas remaining.
        • +
      • gasPrice : number - The cost in wei of each unit of gas.
        • +
      • memory : object - A structure representing the contract's memory space.
        • +
      • stack : array[big.Int] - The EVM execution stack.
        • +
      • depth : number - The execution depth.
        • +
      • account : data - The address of the account executing the current operation.
        • +
      • err : If an error occured, this field contains information about the error. If err is non-null, you can ignore all other fields.
        • +
      +
      • +
    +
    • +
  • timeout : STRING - 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".
    • +
+
Returns
+

A tracer object, as described above.

+
Request
+
curl -X POST --data '{"jsonrpc":"2.0","method":"debug_traceTransaction","params”:[“0xaaaaaaaaaaaaaaaaaaa”,{“disableStorage":true}],"id”:1}' <JSON-RPC-endpoint:port>
Result
+
{...}
+

miner_start

+

Starts the CPU mining process on the client.

+
Parameters
+

None

+
Returns
+

result : boolean | integer - true 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.

+
Request
+
curl -X POST --data '{"jsonrpc":"2.0","method":"miner_start","params":[],"id":1}' <JSON-RPC-endpoint:port>
Result
+
{...}
+

miner_stop

+

Stops the CPU mining process on the client.

+
Parameters
+

None

+
Returns
+

result : boolean | integer - true 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.

+
Request
+
curl -X POST --data '{"jsonrpc":"2.0","method":"miner_stop","params":[],"id":1}' <JSON-RPC-endpoint:port>
Result
+
{...}
+

Objects

+

The following objects are parameters for or returned by JSON-RPC Methods:

+ +

Block Object

+

Returned by eth_getBlockByHash and eth_getBlockByNumber.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeyTypeValue
numberQuantity, IntegerBlock number. null when block is pending.
hashData, 32 bytesHash of the block. null when block is pending.
parentHashData, 32 bytesHash of the parent block.
nonceData, 8 bytesHash of the generated proof of work. null when block is pending.
sha3UnclesData, 32 bytesSHA3 of the uncle's data in the block.
logsBloomData, 256 bytesBloom filter for the block logs. null when block is pending.
transactionsRootData, 32 bytesRoot of the transaction trie for the block.
stateRootData, 32 bytesRoot of the final state trie for the block.
receiptsRootData, 32 bytesRoot of the receipts trie for the block.
minerData, 20 bytesAddress to which mining rewards were paid.
difficultyQuantity, IntegerDifficulty for this block.
totalDifficultyQuantity, IntegerTotal difficulty of the chain until this block.
extraDataDataExtra data field of this block.
sizeQuantity, IntegerSize of block in bytes.
gasLimitQuantityMaximum gas allowed in this block.
gasUsedQuantityTotal gas used by all transactions in this block.
timestampQuantityUnix timestamp when block was collated.
transactionsArrayArray of transaction objects, or 32 byte transaction hashes depending on the specified boolean parameter.
unclesArrayArray of uncle hashes.
+

Filter Options Object

+

Parameter for eth_newFilter and eth_getLogs.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeyTypeRequired/OptionalValue
fromBlockQuantity |TagOptionalInteger block number or latest, pending, earliest. See Block Parameter. Default is latest.
toBlockQuantity |TagOptionalInteger block number or latest, pending, earliest. See Block Parameter. Default is latest.
addressData | ArrayOptionalContract address or array of addresses from which logs originate.
topicsArray of Data, 32 bytes eachOptionalArray of 32-byte topics. Topics are order-dependent. Each topic can also be an array of DATA with "or" options.
+

eth_getLogs has an additional key.

+ + + + + + + + + + + + + + + + + +
KeyTypeRequired/OptionalValue
blockhashData, 32 bytesOptionalHash of block for which to return logs. If blockhash is specified, fromBlock and toBlock cannot be specified.
+

Log Object

+

Returned by eth_getFilterChanges and transaction receipt objects can contain an array of log objects.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeyTypeValue
removedTagtrue when log removed due to chain reorganization. false if valid log.
logIndexQuantity, IntegerLog index position in the block. null when log is pending.
transactionIndexQuantity, IntegerIndex position of transaction from which log was created. null when log is pending.
transactionHashData, 32 bytesHash of transaction from which log was created. null when log is pending.
blockHashData, 32 bytesHash of block in which log included. null when log is pending.
blockNumberQuantityNumber of block in which log included. null when log is pending.
addressData, 20 bytesAddress from which log originated.
dataDataNon-indexed arguments of log.
topicsArray of Data, 32 bytes each0 to 4 indexed log arguments. In Solidity, the first topic is the hash of the signature of the event (for example, Deposit(address, bytes32, unit256)) except you declare the event with an anonymous specifier.)
+

Transaction Object

+

Returned by eth_getTransactionByHash, eth_getTransactionByBlockHashAndIndex, and eth_getTransactionsByBlockNumberAndIndex.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeyTypeValue
blockHashData, 32 bytesHash of block containing this transaction. null when transaction is pending.
blockNumberQuantityBlock number of block containing this transaction. null when transaction is pending.
fromData, 20 bytesAddress of the sender.
gasQuantityGas provided by the sender.
gasPriceQuantityGas price provided by the sender in Wei.
hashData, 32 bytesHash of the transaction.
inputDataData sent with the transaction.
nonceQuantityNumber of transactions made by the sender before this one.
toData, 20 bytesAddress of the receiver. null if a contract creation transaction.
transactionIndexQuantity, IntegerIndex position of transaction in the block. null when transaction is pending.
valueQuantityValue transferred in Wei.
vQuantityECDSA Recovery ID
rData, 32 bytesECDSA signature r
sData, 32 bytesECDSA signature s
+

Transaction Call Object

+

Parameter for eth_call and eth_estimateGas.

+

Note: All parameters are optional for eth_estimateGas

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeyTypeRequired/OptionalValue
fromData, 20 bytesOptionalAddress from which transaction sent.
toData, 20 bytesRequiredAddress to which transaction is directed.
gasQuantity, IntegerOptionalGas provided for the transaction execution. eth_call consumes zero gas, but this parameter may be needed by some executions.
gasPriceQuantity, IntegerOptionalgasPrice used for each paid gas.
valueQuantity, IntegerOptionalValue sent with this transaction.
dataDataOptionalHash of the method signature and encoded parameters. For details see Ethereum Contract ABI.
+

Transaction Receipt Object

+

Returned by eth_getTransactionReceipt.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeyTypeValue
blockHashData, 32 bytesHash of block containing this transaction.
blockNumberQuantityBlock number of block containing this transaction.
contractAddressData, 20 bytesContract address created, if contract creation transaction; otherwise, null.
cumulativeGasUsedQuantityTotal amount of gas used by previous transactions in the block and this transaction.
fromData, 20 bytesAddress of the sender.
gasUsedQuantityAmount of gas used by this specific transaction.
logsArrayArray of log objects generated by this transaction.
logsBloomData, 256 bytesBloom filter for light clients to quickly retrieve related logs.
statusQuantityEither 1 (success) or 0 (failure)
toData, 20 bytesAddress of the receiver, if sending ether; otherwise, null.
transactionHashData, 32 bytesHash of the transaction.
transactionIndexQuantity, IntegerIndex position of transaction in the block.
+

Note: For pre-Byzantium transactions, the transaction receipt object includes the following instead of status:

+ + + + + + + + + + + + + + + +
KeyTypeValue
rootData, 32 bytesPost-transaction stateroot
+ +
+
+
+ + + \ No newline at end of file