An enterprise-grade Java-based, Apache 2.0 licensed Ethereum client https://wiki.hyperledger.org/display/besu

18 KiB

Raw Blame History

description: Pantheon private network quickstart tutorial

Private Network Quickstart tutorial

!!! important "Upcoming Change in v0.9" In v0.9, the Private Network Quickstart will be moved to a separate repository and the existing Private Network Quickstart will be removed from the Pantheon repository. This tutorial will be updated and use the Private Network Quickstart in the separate repository.

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

!!! note To run the Private Network Quickstart, you must install Pantheon by cloning and building.

If you have installed Pantheon from the [packaged binaries](Intallation/Install-Binaries) or are running the [Docker image](Run-Docker-Image), you can proceed with [Starting Pantheon](Starting-Pantheon).

Prerequisites

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

For MacOS and Linux, Docker and Docker-compose
For Windows, Docker for Windows

!!!important Docker for Windows requires Windows 10 Pro, Enterpise, or Education. The Private Network Quickstart does not support Docker Toolbox.

Git command line
Curl command line
A web browser that supports Metamask (currently Chrome, Firefox, Opera, and Brave), and has the MetaMask plug-in installed. This tutorial uses screenshots from Brave.

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 commands:

Run the following commands :

# Shell script are provided in the Quickstart directory

quickstart/runPantheonPrivateNetwork.sh

// Run the docker-compose commands directly

// Run the services and ask for 4 regular nodes
quickstart\docker-compose up -d --scale node=4

// List the endpoints
quickstart\docker-compose port explorer 80

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 process ends, it lists the running services:

!!! example "Docker-compose services list example" ```log

Name Command State Ports
quickstart_bootnode_1 /opt/pantheon/bootnode_sta ... Up 30303/tcp, 8545/tcp, 8546/tcp
quickstart_explorer_1 nginx -g daemon off; Up 0.0.0.0:32770->80/tcp
quickstart_minernode_1 /opt/pantheon/node_start.s ... Up 30303/tcp, 8545/tcp, 8546/tcp
quickstart_node_1 /opt/pantheon/node_start.s ... Up 30303/tcp, 8545/tcp, 8546/tcp
quickstart_node_2 /opt/pantheon/node_start.s ... Up 30303/tcp, 8545/tcp, 8546/tcp
quickstart_node_3 /opt/pantheon/node_start.s ... Up 30303/tcp, 8545/tcp, 8546/tcp
quickstart_node_4 /opt/pantheon/node_start.s ... Up 30303/tcp, 8545/tcp, 8546/tcp
quickstart_rpcnode_1 /opt/pantheon/node_start.s ... Up 30303/tcp, 0.0.0.0:32769->8545/tcp, 0.0.0.0:32768->8546/tcp
```

This is followed by a list of the endpoints:

!!! example "Endpoint list example" log **************************************************************** JSON-RPC HTTP service endpoint : http://localhost:32770/jsonrpc * JSON-RPC WebSocket service endpoint : ws://localhost:32770/jsonws * 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 form ws://localhost:32770/jsonws.
Use the Web block explorer address to display the block explorer web application. View the block explorer by entering the URL in your web browser.

To display the list of endpoints again, run the following shell command:

# Shell script are provided in the Quickstart directory

quickstart/listQuickstartServices.sh

// Run the docker-compose commands directly

quickstart\docker-compose port explorer 80

Block Explorer

This tutorial uses the Alethio light block explorer.

Run the Block Explorer

Access the explorer by copying and pasting the Web block explorer address displayed when starting the private network to your browser.

The block explorer displays a summary of the private network:

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

Click on the block number to the right of Best Block to display the block details.

You can explore blocks by clicking on the blocks under Bk down the left-hand side.

You can search for a specific block, transaction hash, or address by clicking the magnifying glass in the top left-hand corner.

Run JSON-RPC Requests

Now we're ready to run requests.

You can run RPC requests on rpcnode, the node that is exposed to the host in order to listen for requests. This tutorial uses cURL to make JSON-RPC requests.

!!!tip On Windows: We suggest using Postman or a similar client to make RPC requests.

Using curl via Command Prompt or Windows PowerShell might not work.

This tutorial uses the placeholder http://localhost:http-rpc-port. When you run this tutorial, replace http-rpc-port with the JSON-RPC HTTP service endpoint provided when you list the endpoints. (For example, http://localhost:32770/jsonrpc.) 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/1.0.0"
}

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"
}

!!!info 0x79f905c6fd34e80000 = 2250000000000000000000 Wei (2250 Ether)

you can use a unit [converter](https://etherconverter.online/) to go from wei to ether.

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.

Creating a Transaction Using MetaMask

Now we'll use MetaMask to send transactions.

To send transactions, you first need to create an account or use one of the 3 accounts below created during the genesis of this test network.

{!global/test_accounts.md!}

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

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

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

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

Import one of the existing accounts above into metamask using the corresponding private key.

!!!note 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.

!!!info 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.

In MetaMask, select the new account and copy the account address by clicking the ... button and selecting Copy Address to clipboard.

In the block explorer, search for the new account by clicking on the magnifying glass and pasting the account address into the search box. The account is displayed with a zero balance.

Send some ether from the first account (containing some ether) to the new one (that have a zero balance).

Click refresh on the browser page displaying the new account. The updated balance is displayed and reflects the transaction completed using MetaMask.

Truffle Pet Shop Tutorial

With a couple of modifications, we can use the private network in this tutorial as the blockchain for the PetShop tutorial on Truffle website.

Prerequisites

Node.js v6+ LTS and npm (comes with Node)

Install Truffle and Unpack Truffle Box

Install Truffle :

npm install -g truffle

!!!note npm requires sudo on Linux.

Create a pet-shop-tutorial directory and move into it:

mkdir pet-shop-tutorial
cd pet-shop-tutorial

Unpack Pet Shop truffle box:

truffle unbox pet-shop

Install the wallet:

npm install truffle-privatekey-provider

!!!note npm requires sudo on Linux.

Modify the Pet Shop Example

Modify the truffle.js file in the pet-shop-tutorial directory to add our wallet provider:

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: "*"
    },
  }
};

Replace <YOUR HTTP RPC NODE ENDPOINT> with your HTTP RPC node endpoint (for example, http://localhost:32770/jsonrpc).

The private key is the miner address which means it will have funds.

Once this is done, you can continue with the regular tutorial steps on the Truffle website until Step 3 in the Migration section.

Use Pantheon Private Network Instead of Ganache

We are going to use our private network instead of Ganache, so skip steps 3, 4, and 5 in the Migration section.

In step 4, specify our private network:

truffle migrate --network quickstartWallet

Output similar to the following is displayed (your addresses will differ):

Using network 'quickstartWallet'.

Running migration: 1_initial_migration.js
  Deploying Migrations...
  ... 0xfc1dbc1eaa14fa283c2c4415364579da0d195b3f2f2fefd7e0edb600a6235bdb
  Migrations: 0x9a3dbca554e9f6b9257aaa24010da8377c57c17e
Saving successful migration to network...
  ... 0x77cc6e9966b886fb74268f118b3ff44cf973d32b616ed4f050b3eabf0a31a30e
Saving artifacts...
Running migration: 2_deploy_contracts.js
  Deploying Adoption...
  ... 0x5035fe3ea7dab1d81482acc1259450b8bf8fefecfbe1749212aca86dc765660a
  Adoption: 0x2e1f232a9439c3d459fceca0beef13acc8259dd8
Saving successful migration to network...
  ... 0xa7b5a36e0ebc9c25445ce29ff1339a19082d0dda516e5b72c06ee6b99a901ec0
Saving artifacts...

Search for the deployed contracts and transactions in the block explorer using the addresses displayed in your output.

Continue with the regular tutorial steps in the Testing the smart contract section.

To run the tests in the Running the tests section, specify our private network:

truffle test --network quickstartWallet

Output similar to the following is displayed:

Using network 'quickstartWallet'.

Compiling ./contracts/Adoption.sol...
Compiling ./test/TestAdoption.sol...
Compiling truffle/Assert.sol...
Compiling truffle/DeployedAddresses.sol...


  TestAdoption
    ✓ testUserCanAdoptPet (2071ms)
    ✓ testGetAdopterAddressByPetId (6070ms)
    ✓ testGetAdopterAddressByPetIdInArray (6077ms)


  3 passing (37s)

Continue with the regular tutorial steps in the Creating a user interface to interact with the smart contract section.

We have already connected our private network to MetaMask so you can skip the Installing and configuring MetaMask section.

Continue with the regular tutorial steps from the Installing and configuring lite-server section to the end of the tutorial.

When you adopt pets in the browser and approve the transaction in MetaMask, you will be able to see the transactions in the block explorer.

Shut Down the Network and Remove the Containers

To shut down the network and delete all containers:

# Shell script are provided in the Quickstart directory

quickstart/removePantheonPrivateNetwork.sh

// Run the docker-compose commands directly

quickstart\docker-compose down

!!!note On Windows, the quickstart creates a volume called quickstart_public-keys but it's not automatically removed. Remove this volume using docker volume rm quickstart_public-keys.

Stop and restart the Private Network without Removing the Containers

To shut down the network without deleting the containers:

# Shell script are provided in the Quickstart directory

quickstart/stopPantheonPrivateNetwork.sh

// Run the docker-compose commands directly

quickstart\docker-compose stop

(This command will also stop other running containers unrelated to quickstart.)

To restart the private network:

# Shell script are provided in the Quickstart directory

quickstart/resumePantheonPrivateNetwork.sh

// Run the docker-compose commands directly

quickstart\docker-compose start

18 KiB Raw Blame History

Private Network Quickstart tutorial

Prerequisites

Clone Pantheon Source Code

Build Docker Images and Start Services and Network

Block Explorer

Run the Block Explorer

Run JSON-RPC Requests

Requesting the Node Version

Counting Peers

Requesting the Most Recent Mined Block Number

Checking the Miner Account Balance (Coinbase)

Creating a Transaction Using MetaMask

Truffle Pet Shop Tutorial

Prerequisites

Install Truffle and Unpack Truffle Box

Modify the Pet Shop Example

Use Pantheon Private Network Instead of Ganache

Shut Down the Network and Remove the Containers

Stop and restart the Private Network without Removing the Containers

18 KiB

Raw Blame History