mirror of https://github.com/hyperledger/besu
remove the doc content and update contribution docs (#1822)
* remove the doc content and update contribution docs Signed-off-by: Adrian Sutton <adrian.sutton@consensys.net>pull/2/head
Nicolas MASSART
5 years ago
committed by
GitHub
parent
b20147c062
commit
eee210b26a
@ -1,110 +0,0 @@ |
||||
# Pantheon Documentation Style Guide |
||||
|
||||
## Purpose of this Document |
||||
|
||||
This document contains guidelines to ensure the Pantheon documentation is consistent and well organised. |
||||
|
||||
This is a living document and will evolve to better suit Pantheon users and contributors needs. |
||||
|
||||
> **Note:** Although not everything in this style guide is currently followed in the Pantheon |
||||
documention, these guidelines are intended to be applied when writing new content and revising |
||||
existing content. |
||||
|
||||
**The primary audience for this document is:** |
||||
|
||||
* Members of the Pantheon team |
||||
* Developers and technical writers contributing to the Pantheon documentation |
||||
|
||||
## Mission Statement |
||||
|
||||
The Pantheon documentation contributes to a consistent and easy to understand experience for end users. |
||||
We're focused on creating a great experience for both new and expert users of Ethereum clients. |
||||
|
||||
## General Guidelines |
||||
|
||||
The guiding principles for the Pantheon documentation are: |
||||
1. Be consistent |
||||
1. Keep it simple but technically correct |
||||
1. Be proactive and suggest good practices |
||||
1. Be informative and exhaustive. |
||||
|
||||
### 1. Be Consistent |
||||
|
||||
Consistency is important to help our end users build a mental model of how Pantheon works. |
||||
By being consistent with our word choices, visual formatting, and style of communication it helps |
||||
users know what to expect when they refer to or search Pantheon documentation. |
||||
|
||||
### 2. Keep It Simple But Technically Correct |
||||
|
||||
Avoid technical jargon and always assume our end users may not be Ethereum experts. |
||||
|
||||
This doesn't mean explaining all Ethereum concepts in our documentation. Explain Pantheon functionality |
||||
and when an understanding of complex Ethereum concepts is required refer users to relevant resources. |
||||
|
||||
For example, to explain how the EVM works, link to ethdocs.org documentation such as |
||||
http://ethdocs.org/en/latest/introduction/what-is-ethereum.html#ethereum-virtual-machine |
||||
|
||||
Simple explanations must still be technically correct. |
||||
|
||||
### 3. Be Proactive And Suggest Good Practices |
||||
|
||||
Being proactive means anticipating user needs and guiding them through a process. |
||||
This most often takes the form of notes or tip messages alongside the main explanation. |
||||
Put yourself in the user's shoes and consider what questions you would have when reading the documentation. |
||||
|
||||
Do not assume required steps are implied. Err on the side of including them if you are unsure. |
||||
|
||||
Documenting good practices is also important. |
||||
For example, instruct users to secure private keys and protect RPC endpoints a production environments. |
||||
|
||||
### 4. Be Informative But Concise |
||||
|
||||
We seek a balance between providing enough relevant information to help our users develop a solid |
||||
mental model of how Pantheon works without forcing them to read too much text or redundant detail. |
||||
|
||||
To provide additional detail, use sub-sections. |
||||
|
||||
## Writing Style Guide |
||||
|
||||
We use the [Microsoft Style Guide](https://docs.microsoft.com/en-us/style-guide/welcome/) as our general guide |
||||
to writing technical documentation. |
||||
We take guidance from it but do not apply every rule. |
||||
For example, we use title case rather than sentence case. |
||||
|
||||
The Micrsoft Style Guide aims for natural, simple, and clear communication. |
||||
|
||||
Here are some important points we follow: |
||||
|
||||
### Active Voice |
||||
Use active voice. Use _you_ to create a more personal friendly style. Avoid gendered pronouns (_he_ or _she_). |
||||
|
||||
### Contractions |
||||
Use contractions. For example, don’t. |
||||
|
||||
Use common contractions, such as it’s and you’re, to create a friendly, informal tone. |
||||
|
||||
### Recommend |
||||
It's acceptable to use "we recommend" to introduce a product recommendation. |
||||
Don't use "PegaSys recommends" or "it is recommended." |
||||
|
||||
Example: Instead of _This is not recommended for production code_ use _We don't recommend this for production code_. |
||||
|
||||
### Directory vs Folder |
||||
Use _directory_ over _folder_ because we are writing for developers. |
||||
|
||||
### Title Case For Headings |
||||
Use title case for headings. |
||||
|
||||
Note: This is a case where we are not following the Microsoft Writing Style Guide. |
||||
|
||||
### Assumed Knowledge For Readers |
||||
We have two distinct audiences to consider when developing content: |
||||
|
||||
- New to Ethereum and Ethereum clients |
||||
- Experienced with Ethereum clients other than Pantheon. |
||||
|
||||
### Avoid Abbreviations |
||||
|
||||
Try not to use abbreviations [except for well known ones and some jargon](MKDOCS-MARKDOWN-GUIDE.md#abbreviations). |
||||
Don't use "e.g." but use "for example". |
||||
Don't use "i.e." but use "that is". |
||||
@ -1,420 +0,0 @@ |
||||
# MkDocs And Markdown Guide |
||||
|
||||
Pantheon documentation is written using [Markdown](https://daringfireball.net/projects/markdown/) syntax. |
||||
|
||||
However, we use two flavors of this syntax: |
||||
|
||||
- One for pages inside the [/docs](/docs) directory that will be rendered by [MkDocs] as described below |
||||
in the [Installed Markdown Extensions](#installed-markdown-extensions) section. |
||||
- Another using the [Github syntax](https://guides.github.com/features/mastering-markdown/) |
||||
for pages outside of this documentation directory. These are mainly files to support our [open source |
||||
community](https://github.com/PegaSysEng/pantheon/community). |
||||
|
||||
## MkDocs Documentation Website |
||||
|
||||
The [Pantheon documentation website](https://docs.pantheon.pegasys.tech/) is maintained by PegaSys from |
||||
the content of the [/docs](/docs) directory. |
||||
|
||||
### /docs Directory |
||||
|
||||
The [/docs](/docs) directory in the Pantheon repository contains all the documentation that |
||||
is generated into a static HTML website using [MkDocs] and the [Mkdocs Material] theme and hosted by [readthedocs.org]. |
||||
|
||||
The documentation is automatically updated using [WebHooks](https://docs.readthedocs.io/en/stable/webhooks.html) |
||||
linking GitHub to the [readthedocs.org] site when you merge a pull-request in the master branch of Pantheon. |
||||
|
||||
The system also detects tags in the Github repository and takes care of making the latest stable release |
||||
and previous versions available. |
||||
|
||||
If any issues occur, contact the maintainers of the [Pantheon documentation project](https://readthedocs.org/projects/pantheon/). |
||||
|
||||
### MkDocs Configuration |
||||
|
||||
[MkDocs] is a Python tool that generates the static HTML website that is published. |
||||
|
||||
Our [MkDocs] setup uses a [Mkdocs Material] theme to render the html pages. It also comes with a number of useful extensions. |
||||
|
||||
[MkDocs] in configured in the [mdkocs.yml](/mkdocs.yml) file. |
||||
|
||||
This file configures: |
||||
|
||||
- Site meta data and variables |
||||
- Theme configuration |
||||
- Page navigation |
||||
- Extensions |
||||
- Plugins |
||||
|
||||
If you add pages to the documentation (rather than updating existing pages), update the "nav" section |
||||
to add your page and specify the page name. |
||||
|
||||
### Preview The Documentation |
||||
|
||||
We recommended previewing your work locally before pushing your changes within a pull-request. |
||||
As the final documentation is build with [MkDocs], you have to build your docs locally with this tool |
||||
to ensure the Markdown is correctly understood and displayed. |
||||
|
||||
To preview Pantheon documentation locally: |
||||
|
||||
- [Install Python 3.x](https://www.mkdocs.org/#installing-python) (see [readthedocs.yml](readthedocs.yml) file for |
||||
the exact version) |
||||
- [Install PIP](https://www.mkdocs.org/#installing-pip) |
||||
- Install all the required dependencies : |
||||
```bash |
||||
pip install -r docs/requirements.txt |
||||
``` |
||||
>**note** |
||||
> If pip raises errors like `Could not find a version that satisfies the requirement` when executing |
||||
`pip`, you may have to use the `pip3` commend to explicitely run Python 3 specific pip depending if |
||||
you already have another python version installed or not and in what order you installed them. |
||||
- Run the following command in the project directory : |
||||
```bash |
||||
mkdocs serve |
||||
``` |
||||
- Follow the link displayed on the output of this command that |
||||
looks like `[I 190206 18:48:47 server:298] Serving on http://127.0.0.1:8000`, |
||||
here connect to [http://127.0.0.1:8000] |
||||
|
||||
You can let this doc server run while you work on the doc, it updates the local website |
||||
automatically when you save changes in your Markdown files. |
||||
|
||||
>**Important** |
||||
> |
||||
> Run `python --version` to make sure you are using version indicated in [readthedocs.yml](readthedocs.yml) file. |
||||
> |
||||
> If you are updating from a previous Python version you will also have to run pip install again and |
||||
check your path. |
||||
|
||||
## Formatting Markdown For Doc Site |
||||
|
||||
Final documentation rendering is essential, but the format of the Markdown files is also very important. |
||||
|
||||
Formatting the Markdown code helps reviewers and writers easily navigate in the code and review your changes. |
||||
|
||||
A few basic rules: |
||||
|
||||
- Each file must contain a header composed of [meta-data](https://squidfunk.github.io/mkdocs-material/extensions/metadata/) |
||||
and ended by a specific comment. |
||||
Ex: |
||||
```markdown |
||||
title: Installation overview |
||||
description: Overview and requirements to install Pantheon |
||||
<!--- END of page meta data --> |
||||
``` |
||||
- [As for other code](https://google.github.io/styleguide/javaguide.html#s4.4-column-limit), |
||||
each line of Markdown code must be limited to 100 columns long to be readable on any editor. |
||||
Lines have to be wrapped without cutting the line in the middle of a word. A line break displays as a space. |
||||
- No HTML markup can be used inside a Markdown document. |
||||
We provide [a lot of extensions](#installed-markdown-extensions) that are able to do the same thing |
||||
without HTML. If you think one is missing, just discuss it with the team on [Gitter] and we'll decide together |
||||
if it's worth adding an extension. |
||||
- Only one first level title can be present on a page. |
||||
- Format tables so they are also readable in the source code. |
||||
You can quickly achieve this by using a tool like http://markdowntable.com/ |
||||
|
||||
## Installed Markdown Extensions |
||||
|
||||
>**Important** |
||||
> Extensions are only available for the docs under [/docs](/docs) directory. |
||||
|
||||
As markdown can be a bit limited when it comes to some specific rendering of code, TOCs, and other documentation |
||||
elements, we configured some extensions for these items. |
||||
Extensions enable you to use simple Markdown syntax to achieve some complex rendering. |
||||
|
||||
>**Important** |
||||
> Never use HTML tags directly in the Markdown files to try to render content. |
||||
For consistency reasons we only allow the specific renderings available in the extensions. |
||||
|
||||
Here is a list of the available extensions: |
||||
|
||||
### TOC |
||||
|
||||
This extension automatically displays a table of content of the current page on the right side of the page. |
||||
It displays titles to the third level (`###`). After the third level, titles won't be displayed in the TOC. |
||||
|
||||
This extension also displays a link on the right of any title called "permalink". |
||||
This link can be used to point directly to the title from another website. |
||||
|
||||
### Include |
||||
|
||||
If you have content to be repeated on multiple pages, you can create it in a common page in and include |
||||
it in all required pages. |
||||
|
||||
Example: |
||||
To include the content of the "test_accounts.md" page in the "/docs/global" directory in another page, use: |
||||
```markdown |
||||
{!global/test_accounts.md!} |
||||
``` |
||||
|
||||
### Admonition |
||||
|
||||
The [Admonition extension](https://squidfunk.github.io/mkdocs-material/extensions/admonition/#admonition) |
||||
enables information, warning, and danger blocks. |
||||
|
||||
Example: |
||||
````markdown |
||||
!!! note |
||||
This is a multi line note |
||||
in the Pantheon documentation. |
||||
```` |
||||
|
||||
The 4 spaces indentation is required for the content to be part of the admonition. |
||||
|
||||
We generally use the following [types](https://squidfunk.github.io/mkdocs-material/extensions/admonition/#types) |
||||
in our documentation: |
||||
|
||||
- **Note** : Used to add information about a subject that doesn't directly needs to be taken in account |
||||
to use this specific part. |
||||
Example: "Available since v0.8.3" |
||||
- **Abstract** : Used at the beginning of a long article. Also known as "TL;DR", this can help users jump |
||||
into the content knowing that they will find their answer somewhere in the page. |
||||
- **Info** : Used to provide detail about a specific part of the documentation. |
||||
Ex: "The miner coinbase account is one of the accounts defined in the genesis file." |
||||
- **Tip** : Used to provide information that could help improve the use of the tool, make it faster. |
||||
Example: "To restart the private network in the future, start from 4. Restart First Node as Bootnode." |
||||
- **Warning** : Used to warn the users about something important. |
||||
Ex: "This will be deprecated in next version." |
||||
- **Danger** : Used to alert the user about a potential dangerous effect such as a risk of destroying |
||||
something or losing assets. |
||||
Ex: "Never use the development private keys for production use". |
||||
- **Example** : used to display an example. We usually use it with a single or tabbed code-block: |
||||
````markdown |
||||
!!! example |
||||
This example shows how to use the `net_listening` RPC method. |
||||
|
||||
```bash tab="curl HTTP request" |
||||
$ curl -X POST --data '{"jsonrpc":"2.0","method":"net_listening","params":[],"id":53}' <JSON-RPC-http-endpoint:port> |
||||
``` |
||||
|
||||
```bash tab="wscat WS request" |
||||
{"jsonrpc":"2.0","method":"net_listening","params":[],"id":53} |
||||
``` |
||||
|
||||
```json tab="JSON result" |
||||
{ |
||||
"jsonrpc" : "2.0", |
||||
"id" : 53, |
||||
"result" : true |
||||
} |
||||
``` |
||||
```` |
||||
|
||||
### Footnotes |
||||
|
||||
The [Footnotes extension](https://squidfunk.github.io/mkdocs-material/extensions/footnotes/) enables |
||||
adding footnotes. |
||||
|
||||
Footnotes display content at the end of the page and a numbered link inside the text to go to this content. |
||||
The extension also adds a link at the end of the footnote back to the text. |
||||
|
||||
### Definitions List |
||||
|
||||
The [def_list extension](https://python-markdown.github.io/extensions/definition_lists/) enables listing definitions |
||||
directly in the Markdown. |
||||
|
||||
### Abbreviations |
||||
|
||||
Generally we avoid the use of abbreviations but some like "PoW" for proof-of-work or "dApp" for |
||||
decentralized application are now part of the Ethereum jargon. The [Abbreviation extension](https://python-markdown.github.io/extensions/abbreviations/) |
||||
enables a tool tip hint to be provided for abbreviations. |
||||
|
||||
Place abbreviations at the beginning of the Markdown file just after the meta-data header. |
||||
|
||||
Example: |
||||
```markdown |
||||
description: This is an example page |
||||
<!--- END of page meta data --> |
||||
|
||||
*[PoA]: Proof of Work |
||||
|
||||
Clique is a PoA mechanism used in the Rinkeby test network |
||||
``` |
||||
|
||||
### Math |
||||
|
||||
[Arithmatex extension](https://squidfunk.github.io/mkdocs-material/extensions/pymdown/#arithmatex-mathjax ) |
||||
enables writing math formulas in the documentation using the provided syntax. |
||||
|
||||
Example: |
||||
```markdown |
||||
$\sigma=\displaystyle\prod_{k=1}^t\sigma_{i_k}^{L_{i_k}(0)}$ |
||||
|
||||
Constructing the threshold signature $\sigma$ from $t$ individual |
||||
signatures $\sigma_{i_k}$, $k=1,\dots,t$ and the Lagrange polynomials |
||||
$L_{i_1}, \dots,L_{i_t}$ associated to the set $I=\{i_1,\dots,i_t\}$ of signers. |
||||
``` |
||||
|
||||
### Better Emphasis |
||||
|
||||
The [Betterem extension](https://facelessuser.github.io/pymdown-extensions/extensions/betterem/) is |
||||
automatically applied to your bold and italic content. |
||||
|
||||
### Keyboard Shortcuts |
||||
|
||||
The [Keys syntax](https://facelessuser.github.io/pymdown-extensions/extensions/keys/) extension enables |
||||
displaying keyboard shortcuts. |
||||
|
||||
Example: |
||||
```markdown |
||||
++ctrl+C++ |
||||
``` |
||||
|
||||
### Folding Details Blocks |
||||
|
||||
You can use a folding block to hide content. The block can be closed by default or open. |
||||
This pattern helps reduce the content length and enables a faster overview of the whole page. |
||||
|
||||
Ex: |
||||
```markdown |
||||
???+ note "Folding details" |
||||
This is the detail of my content. |
||||
The plus sign makes it unfolded by default. |
||||
Remove the plus sign and it will be folded by default. |
||||
``` |
||||
|
||||
### Emojis |
||||
|
||||
Emojis are fun, but they can also be useful to draw the reader's attention. |
||||
Try to use only neutral emojis like :warning: |
||||
|
||||
Refer to a [supported full list of available emojis](https://www.webfx.com/tools/emoji-cheat-sheet/) |
||||
to find the suitable code. |
||||
|
||||
Example: |
||||
`:warning:` displays :warning: |
||||
|
||||
### Magic Links |
||||
|
||||
If you want an URL to be displayed as a link, simply write it and this extension automatically displays it as |
||||
a link. You don't need to surround it with Markdown links syntax. |
||||
|
||||
### Highlight Content |
||||
|
||||
The [Mark extension](https://facelessuser.github.io/pymdown-extensions/extensions/mark/) enables highlighting of |
||||
content. |
||||
|
||||
Text surrounded by double equals is highlighted in yellow. |
||||
|
||||
Example: |
||||
```markdown |
||||
==This is highlighted text== |
||||
``` |
||||
|
||||
### Strike Through |
||||
|
||||
The [tilde syntax](https://squidfunk.github.io/mkdocs-material/extensions/pymdown/#tilde) extensions enables text |
||||
strike through to be displayed. |
||||
|
||||
Example: |
||||
```markdown |
||||
~~This is the wrong way to do~~ |
||||
``` |
||||
|
||||
### Symbols |
||||
|
||||
The [Smart symbols syntax](https://facelessuser.github.io/pymdown-extensions/extensions/smartsymbols/) enables |
||||
the inclusion of symbols. |
||||
|
||||
Ex: |
||||
`-->` will draw a nice right arrow. |
||||
|
||||
### Task lists |
||||
|
||||
The [Task list syntax](https://squidfunk.github.io/mkdocs-material/extensions/pymdown/#tasklist) extension |
||||
enables displaying a list as a checklist. |
||||
|
||||
### Code Samples And Examples With [SuperFences] |
||||
|
||||
#### Format The Code |
||||
|
||||
For writing code examples inside the documentation, refer to the developer style guides: |
||||
|
||||
- Java : refer to our [coding convention](CODING-CONVENTIONS.md). |
||||
- JSON : use https://jsonformatter.curiousconcept.com/ to format your JSON code. |
||||
- TOML : we follow version 0.5.0 language definition. |
||||
- JavaScript : see [Google JavaScript Style Guide](https://google.github.io/styleguide/jsguide.html). |
||||
|
||||
#### Including Code in the Documentation |
||||
|
||||
We use code-blocks provided by the [SuperFences] extension to present code samples and examples in the |
||||
documentation. |
||||
|
||||
A basic code-block uses triple back ticks and the language name to enable syntax highlighting. |
||||
|
||||
For example, a JSON result is written as: |
||||
|
||||
````markdown |
||||
```json |
||||
{ |
||||
"jsonrpc": "2.0", |
||||
"id": 1, |
||||
"result": true |
||||
} |
||||
``` |
||||
```` |
||||
|
||||
#### Tabbed Code Blocks |
||||
|
||||
[SuperFences] enables additional functionality such as the tabbed code-block. |
||||
|
||||
For example, to group the usage syntax and a usage example in the same block with tabs: |
||||
|
||||
````markdown |
||||
```bash tab="Syntax" |
||||
$ pantheon rlp encode [--from=<FILE>] [--to=<FILE>] [--type=<type>] |
||||
``` |
||||
|
||||
```bash tab="File Example" |
||||
$ pantheon rlp encode --from=ibft_extra_data.json --to=extra_data_for_ibft_genesis.txt --type=IBFT_EXTRA_DATA |
||||
``` |
||||
|
||||
```bash tab="Standart Input/Output Example" |
||||
$ cat extra_data.json | pantheon rlp encode > rlp.txt |
||||
``` |
||||
```` |
||||
|
||||
#### Line Numbers On Long Code Samples |
||||
|
||||
[SuperFences] can also add [line numbers](https://facelessuser.github.io/pymdown-extensions/extensions/superfences/#showing-line-numbers) |
||||
to the code sample which makes it easier when discussing the code the sample. |
||||
|
||||
The line numbers will only appear on the code block that uses the `linenums="1"` parameter. |
||||
|
||||
Example: |
||||
````markdown |
||||
```javascript linenums="1" |
||||
// A very long javascript sample code |
||||
``` |
||||
```` |
||||
|
||||
#### Code Syntax Highlight |
||||
|
||||
Codehilite extension enables automatic syntax highlighting of code blocks. Define the language after |
||||
the code block delimiter to ensure correct highlighting. |
||||
If you don't provide the language name, the extension attempts to automatically discover it |
||||
but this can lead to errors. |
||||
|
||||
Example: |
||||
````markdown |
||||
```json |
||||
{ |
||||
"jsonrpc" : "2.0", |
||||
"id" : 51, |
||||
"result" : { |
||||
"startingBlock" : "0x5a0", |
||||
"currentBlock" : "0xad9", |
||||
"highestBlock" : "0xad9" |
||||
} |
||||
} |
||||
``` |
||||
```` |
||||
|
||||
Pygment is the implementation for this extension, refer to Pygment website for a |
||||
[list of the supported languages](http://pygments.org/languages/). |
||||
|
||||
|
||||
|
||||
[MkDocs]: https://www.mkdocs.org/ |
||||
[readthedocs.org]: https://readthedocs.org/ |
||||
[Mkdocs Material]: https://squidfunk.github.io/mkdocs-material/ |
||||
[Gitter]: https://gitter.im/PegaSysEng/pantheon |
||||
[SuperFences]: https://squidfunk.github.io/mkdocs-material/extensions/pymdown/#superfences |
||||
@ -1,10 +0,0 @@ |
||||
description: Pantheon Architecture |
||||
<!--- END of page meta data --> |
||||
|
||||
# Pantheon Architecture |
||||
|
||||
The high-level architecture of Pantheon is: |
||||
|
||||
 |
||||
|
||||
If you've got questions about the architecture of Pantheon, contact us on [gitter](https://gitter.im/PegaSysEng/pantheon). |
||||
@ -1,24 +0,0 @@ |
||||
description: Ethereum accounts used for testing only on private network |
||||
<!--- END of page meta data --> |
||||
|
||||
# Accounts for Testing |
||||
|
||||
You can use existing accounts for testing by including them in the genesis file for a private network. |
||||
Alternatively, Pantheon provides predefined accounts in development mode. |
||||
|
||||
## Development Mode |
||||
|
||||
When you start Pantheon with the [`--network=dev`](../Reference/Pantheon-CLI-Syntax.md#network) |
||||
command line option, the `dev.json` genesis file is used by default. |
||||
|
||||
The `dev.json` genesis file defines the accounts below that can be used for testing. |
||||
|
||||
{!global/test_accounts.md!} |
||||
|
||||
## Genesis File |
||||
|
||||
To use existing test accounts, specify the accounts and balances in a genesis file for your test network. |
||||
For an example of defining accounts in the genesis file, refer to [`dev.json`](https://github.com/PegaSysEng/pantheon/blob/master/config/src/main/resources/dev.json). |
||||
|
||||
Use the [`--genesis-file`](../Reference/Pantheon-CLI-Syntax.md#genesis-file) command line option to |
||||
start Pantheon with the genesis file defining the existing accounts. |
||||
@ -1,73 +0,0 @@ |
||||
description: Configuration items specified in the genesis file |
||||
<!--- END of page meta data --> |
||||
|
||||
# Configuration Items |
||||
|
||||
Network configuration items are specified in the genesis file. |
||||
|
||||
| Item | Description | |
||||
|---------------------|-:----------------------------------------------------------------------------------------------------------------------------------------| |
||||
| Chain ID | [Chain ID for the network](NetworkID-And-ChainID.md) | |
||||
| Milestone blocks | [Milestone blocks for the network](#milestone-blocks) | |
||||
| `ethash` | Specifies network uses [Ethash](../Consensus-Protocols/Overview-Consensus.md) and contains [`fixeddifficulty`](#Fixed Difficulty) | |
||||
| `clique` | Specifies network uses [Clique](../Consensus-Protocols/Clique.md) and contains [Clique configuration items](../Consensus-Protocols/Clique.md#genesis-file) | |
||||
| `ibft2` | Specifies network uses [IBFT 2.0](../Consensus-Protocols/IBFT.md) and contains [IBFT 2.0 configuration items](../Consensus-Protocols/IBFT.md#genesis-file) | |
||||
| `contractSizeLimit` | Maximum contract size in bytes. Specify in [free gas networks](FreeGas.md). Default is `24576` and the maximum size is `2147483647`. | |
||||
| `evmStackSize` | Maximum stack size. Specify to increase the maximum stack size in private networks with very complex smart contracts. Default is `1024`. | |
||||
|
||||
|
||||
## Milestone Blocks |
||||
|
||||
In public networks, the milestone blocks specify the blocks at which the network changed protocol. |
||||
|
||||
!!! example "Ethereum Mainnet Milestone Blocks" |
||||
```json |
||||
{ |
||||
"config": { |
||||
... |
||||
"homesteadBlock": 1150000, |
||||
"daoForkBlock": 1920000, |
||||
"daoForkSupport": true, |
||||
"eip150Block": 2463000, |
||||
"eip150Hash": "0x2086799aeebeae135c246c65021c82b4e15a2c451340993aacfd2751886514f0", |
||||
"eip155Block": 2675000, |
||||
"eip158Block": 2675000, |
||||
"byzantiumBlock": 4370000, |
||||
"constantinopleBlock": 7280000, |
||||
"constantinopleFixBlock": 7280000, |
||||
... |
||||
}, |
||||
} |
||||
``` |
||||
|
||||
In private networks, the milestone block defines the protocol version for the network. |
||||
|
||||
!!! example "Private Network Milestone Block" |
||||
```json |
||||
{ |
||||
"config": { |
||||
... |
||||
"constantinopleFixBlock": 0, |
||||
... |
||||
}, |
||||
} |
||||
``` |
||||
|
||||
## Fixed Difficulty |
||||
|
||||
Use `fixeddifficulty` to specify a fixed difficulty in private networks using Ethash. |
||||
|
||||
!!! example |
||||
```json |
||||
{ |
||||
"config": { |
||||
... |
||||
"ethash": { |
||||
"fixeddifficulty": 1000 |
||||
}, |
||||
|
||||
}, |
||||
... |
||||
} |
||||
``` |
||||
|
||||
@ -1,31 +0,0 @@ |
||||
description: Pre-deploying contracts in genesis file |
||||
<!--- END of page meta data --> |
||||
|
||||
# Predeploying Contracts in the Genesis File |
||||
|
||||
To predeploy contracts when starting Pantheon, specify contract code in the genesis file. |
||||
|
||||
!!! example "Contract Code in Genesis File" |
||||
```json |
||||
{ |
||||
... |
||||
"alloc": { |
||||
"0x0ffd23af8eebc60b3cfdeed6f814988757237314": { |
||||
"balance": "0x100000000000000000000000000000000000000000000000000", |
||||
"code": "0x6080604052600436106043576000357c010000000000000000000000000000000000000000000000000000000090048063010fc84214604857806355241077146070575b600080fd5b348015605357600080fd5b50605a60a7565b6040518082815260200191505060405180910390f35b348015607b57600080fd5b5060a560048036036020811015609057600080fd5b810190808035906020019092919050505060ad565b005b60005481565b80600081905550807f04474795f5b996ff80cb47c148d4c5ccdbe09ef27551820caa9c2f8ed149cce360405160405180910390a25056fea165627a7a7230582038cb7ea327af8f73feabcfbff64498f1e74831e67f7c75286760d3845c6747c70029", |
||||
"storage": { |
||||
"7aa07e0c924147697605046b7c2c32645b7bbfb41e0ac5d0a84ac93cbb759798": "0000000000000000000000000000000000000000000000000000000000000001", |
||||
"cea2b0602db61f92b76ec4402875cc38eedc9fc425cb1b697fc2265d50fc20fb": "0000000000000000000000000000000000000000000000000000000000000001", |
||||
} |
||||
} |
||||
}, |
||||
... |
||||
} |
||||
``` |
||||
|
||||
The contract code in the genesis file defines: |
||||
|
||||
* Address |
||||
* Balance |
||||
* Bytecode |
||||
* Key value pairs for contract storage. |
||||
@ -1,87 +0,0 @@ |
||||
description: Configuring Free Gas Networks |
||||
<!--- END of page meta data --> |
||||
|
||||
# Free Gas Networks |
||||
|
||||
Transactions use computational resources so have an associated cost. Gas is the cost unit and the gas |
||||
price is the price per gas unit. The transaction cost is the gas used * gas price. |
||||
|
||||
In public networks, the transaction cost is paid in Ether by the account submitting the transaction. |
||||
The transaction cost is paid to the miner (or validator in PoA networks) that includes the transaction in a block. |
||||
|
||||
In many private networks, the validators are run by the network participants and do not require gas as an |
||||
incentive to participate. Generally, networks that do not require gas as an incentive, configure the gas price to be 0 (that is, make gas free). |
||||
Some private networks may allocate Ether and use a non-zero gas price to limit resource use. |
||||
|
||||
!!! tip |
||||
We are using the term _free gas network_ to refer to a network where the gas price is set to zero. |
||||
A network with gas price of zero is also known as a _zero gas network_ or _no gas network_. |
||||
|
||||
In a free gas network, transactions still use gas but the gas price is 0 meaning the transaction cost is 0: |
||||
|
||||
Transaction cost = gas used * 0 (gas price) |
||||
|
||||
## Configuring Pantheon for Free Gas |
||||
|
||||
When gas is free, limiting block and contract sizes is less important. In free gas networks, we increase the |
||||
block size limit and set the contract size limit to the maximum value. |
||||
|
||||
### 1. Set Block Size |
||||
|
||||
If you want to remove gas from consideration and don't mind blocks potentially taking longer |
||||
to be created, set the block size limit (measured in gas) in the genesis file to the maximum accepted by Truffle (`0x1fffffffffffff`): |
||||
|
||||
```json |
||||
"gasLimit": "0x1fffffffffffff" |
||||
``` |
||||
|
||||
If you are more concerned about blocks arriving on time and don't have very expensive individual transactions, set the |
||||
`gasLimit` to a value closer to the amount of gas your validators can process in the configured block time. |
||||
|
||||
### 2. Set Contract Size |
||||
|
||||
Set the contract size limit to the maximum supported size (in bytes) in the `config` section of the genesis file: |
||||
|
||||
```json |
||||
"contractSizeLimit": 2147483647 |
||||
``` |
||||
|
||||
### 3. Start Pantheon with Minimum Gas Price of 0 |
||||
|
||||
When starting validators (mining nodes in a PoW network), set the [minimum gas price](../Reference/Pantheon-CLI-Syntax.md#min-gas-price) to 0: |
||||
|
||||
```bash tab="Command Line" |
||||
--min-gas-price=0 |
||||
``` |
||||
|
||||
```bash tab="Configuration File" |
||||
min-gas-price=0 |
||||
``` |
||||
|
||||
## Configuring Truffle for Free Gas |
||||
|
||||
If using Truffle to develop on your free gas network, you also need to configure Truffle for free gas. |
||||
|
||||
Similar to setting block and contract size limits to their maximum values for Pantheon, we set the |
||||
gas limit for transactions in Truffle to the maximum possible. |
||||
|
||||
!!! important |
||||
Pantheon does not implement private key management. To use Pantheon with Truffle, you must configure |
||||
a [Truffle wallet](../Using-Pantheon/Truffle.md). |
||||
|
||||
|
||||
### Update truffle-config.js |
||||
|
||||
Update the `truffle-config.js` file: |
||||
|
||||
1. Set the gas price to 0: |
||||
|
||||
```js |
||||
gasPrice:0 |
||||
``` |
||||
|
||||
1. Set the gas limit for a transaction (that is, contract creation) to be the block gas limit - 1 |
||||
|
||||
```js |
||||
gas: "0x1ffffffffffffe" |
||||
``` |
||||
@ -1,13 +0,0 @@ |
||||
description: Configuring Pantheon at the network level compared to the node level |
||||
<!--- END of page meta data --> |
||||
|
||||
# Network vs Node Configuration |
||||
|
||||
Pantheon is configured at the network level and the node level. |
||||
|
||||
Network wide settings are specified in the [genesis file](Config-Items.md). Examples include `evmStackSize` and the |
||||
[consensus mechanism](../Consensus-Protocols/Overview-Consensus.md). |
||||
|
||||
Node settings are specified on the command line or in the [node configuration file](Using-Configuration-File.md). |
||||
For example, the [JSON-RPC API methods to enable](../Reference/Pantheon-API-Methods.md) or the |
||||
[data directory](../Reference/Pantheon-CLI-Syntax.md#data-path) for the node. |
||||
@ -1,35 +0,0 @@ |
||||
description: Pantheon network ID and chain ID implementation |
||||
<!--- END of page meta data --> |
||||
|
||||
# Network ID and Chain ID |
||||
|
||||
Ethereum networks have a network ID and a chain ID. The network ID defaults to the chain ID specified |
||||
in the genesis file. |
||||
|
||||
!!! example "Chain ID in Genesis File" |
||||
```json |
||||
{ |
||||
"config": { |
||||
"ethash": { |
||||
}, |
||||
"chainID": 1981 |
||||
}, |
||||
... |
||||
} |
||||
``` |
||||
|
||||
For most networks including MainNet and the public testnets, the network ID and the chain ID are the |
||||
same and are specified in the genesis file. |
||||
|
||||
The network ID and chain ID are automatically defined by Pantheon when connecting to networks specified |
||||
using the [`--network`](../Reference/Pantheon-CLI-Syntax.md#network) option: |
||||
|
||||
- **MainNet:** chain-id 1, network-id 1 |
||||
- **Rinkeby:** chain-id 4, network-id 4 |
||||
- **Ropsten:** chain-id 3, network-id 3 |
||||
- **Dev:** chain-id 2018, network-id 2018 |
||||
|
||||
When using the [`--network=dev`](../Reference/Pantheon-CLI-Syntax.md#network) or |
||||
[`--genesis-file`](../Reference/Pantheon-CLI-Syntax.md#genesis-file) options, you can override the |
||||
network ID using the [`--network-id`](../Reference/Pantheon-CLI-Syntax.md#network-id) option. |
||||
|
||||
@ -1,56 +0,0 @@ |
||||
description: Pantheon Clique Proof-of-Authority (PoA) consensus protocol implementation |
||||
path: blob/master/ethereum/core/src/main/resources/ |
||||
source: rinkeby.json |
||||
<!--- END of page meta data --> |
||||
|
||||
# Bootnodes |
||||
|
||||
Bootnodes are used to initially discover peers. |
||||
|
||||
## Mainnet and Public Testnets |
||||
|
||||
For mainnet, Rinkeby, Ropsten, and Görli, Pantheon predefines a list of enode URLs. |
||||
|
||||
## Private Networks |
||||
|
||||
### Start Bootnode |
||||
|
||||
To start a bootnode for a private network, complete the following steps: |
||||
|
||||
1. Export the public key to a file: |
||||
|
||||
!!! example |
||||
```bash |
||||
pantheon --genesis-file=privateNetworkGenesis.json --data-path=nodeDataPath public-key export --to=bootnode |
||||
``` |
||||
Where `privateNetworkGenesis.json` and `nodeDataPath` are changed to the relevant values for |
||||
your private network. |
||||
|
||||
The node public key is exported to the `bootnode` file. |
||||
|
||||
2. Start the bootnode, specifying: |
||||
|
||||
* Genesis file and data directory, as in the previous step. |
||||
* No arguments for the [`--bootnodes` option](../../Reference/Pantheon-CLI-Syntax.md#bootnodes) because this is your bootnode. |
||||
|
||||
!!! example |
||||
``` |
||||
pantheon --genesis-file=privateNetworkGenesis.json --data-path=nodeDataPath --bootnodes |
||||
``` |
||||
|
||||
To specify this bootnode for another node, specify the [enode URL](../Node-Keys.md#enode-url) using the [`--bootnodes`](../../Reference/Pantheon-CLI-Syntax.md#bootnodes) |
||||
option. |
||||
|
||||
!!! info |
||||
The default host and port for P2P peer discovery is `127.0.0.1:30303`. |
||||
Use the [`--p2p-host`](../../Reference/Pantheon-CLI-Syntax.md#p2p-host) and |
||||
[`--p2p-port`](../../Reference/Pantheon-CLI-Syntax.md#p2p-port) option to specify a host and port. |
||||
|
||||
### Start Node Specifying the Bootnode |
||||
|
||||
To start a node specifying the bootnode for P2P discovery: |
||||
|
||||
!!! example |
||||
```bash |
||||
pantheon --genesis-file=privateNetworkGenesis.json --data-path=nodeDataPath --p2p-host=127.0.0.1 --p2p-port=30301 --network-id=123 --bootnodes=enode://c35c3ec90a8a51fd5703594c6303382f3ae6b2ecb99bab2c04b3794f2bc3fc2631dabb0c08af795787a6c004d8f532230ae6e9925cbbefb0b28b79295d615f@127.0.0.1:30303 |
||||
``` |
||||
@ -1,41 +0,0 @@ |
||||
description: Ports must be exposed appropriately to enable communication |
||||
<!--- END of page meta data --> |
||||
|
||||
# Configuring Ports |
||||
|
||||
Ports must be exposed appropriately to enable communication. An example port configuration for a Pantheon node on AWS is: |
||||
|
||||
 |
||||
|
||||
When running Pantheon from the [Docker image](../../Getting-Started/Run-Docker-Image.md), [expose ports](../../Getting-Started/Run-Docker-Image.md#exposing-ports). |
||||
|
||||
!!! tip |
||||
Pantheon supports [UPnP](Using-UPnP.md) for home or small office environments where a wireless router |
||||
or modem provides NAT isolation. |
||||
|
||||
## P2P Networking |
||||
|
||||
To enable peer discovery, the P2P UDP port must be open for inbound connections. |
||||
|
||||
We also recommended opening the P2P TCP port for inbound connections. This is not strictly required because |
||||
Pantheon attempts to initiate outbound TCP connections. However, if no nodes on the network are accepting inbound TCP |
||||
connections, nodes cannot communicate. |
||||
|
||||
The P2P port is specified by the [`--p2p-port`](../../Reference/Pantheon-CLI-Syntax.md#p2p-port) option. |
||||
The default is `30303`. |
||||
|
||||
## JSON-RPC API |
||||
|
||||
To enable access to the [JSON-RPC API](../../Pantheon-API/JSON-RPC-API.md), open the HTTP JSON-RPC and WebSockets JSON-RPC ports to the intended users |
||||
of the JSON-RPC API on TCP. |
||||
|
||||
The [`--rpc-http-port`](../../Reference/Pantheon-CLI-Syntax.md#rpc-http-port) and [`--rpc-ws-port`](../../Reference/Pantheon-CLI-Syntax.md#rpc-ws-port) |
||||
options specify the HTTP and WebSockets JSON-RPC ports. The defaults are `8545` and `8546`. |
||||
|
||||
## Metrics |
||||
|
||||
To enable [Prometheus to access Pantheon](../../Monitoring/Monitoring-Performance.md#monitor-node-performance-using-prometheus), |
||||
open the metrics port or metrics push port to Prometheus or the Prometheus push gateway on TCP. |
||||
|
||||
The [`--metrics-port`](../../Reference/Pantheon-CLI-Syntax.md#metrics-port) and [`--metrics-push-port`](../../Reference/Pantheon-CLI-Syntax.md#metrics-push-port) |
||||
options specify the ports for Prometheus and Prometheus push gateway. The defaults are `9545` and `9001`. |
||||
@ -1,91 +0,0 @@ |
||||
description: Managing Pantheon peers |
||||
<!--- END of page meta data --> |
||||
|
||||
# Managing Peers |
||||
|
||||
## Limiting Peers |
||||
|
||||
Limiting peers reduces the bandwidth used by Pantheon. It also reduces the CPU time and disk access |
||||
used to manage and respond to peers. |
||||
|
||||
Use the [`--max-peers`](../../Reference/Pantheon-CLI-Syntax.md#max-peers) command line option to reduce |
||||
the maximum number of peers. The default is 25. |
||||
|
||||
## No Discovery |
||||
|
||||
The [`--discovery-enabled`](../../Reference/Pantheon-CLI-Syntax.md#discovery-enabled) command line option |
||||
can be used to disable P2P peer discovery. |
||||
Set this option to `false` if you are running a test node or a network with [static nodes](#static-nodes). |
||||
|
||||
## Static Nodes |
||||
|
||||
Static nodes are configured nodes that remain connected rather than nodes connected through P2P discovery. |
||||
Static nodes attempt to maintain connectivity. If a connection goes down to a static node, |
||||
the node attempts to reconnect every 60 seconds. |
||||
|
||||
To configure a network of static nodes: |
||||
|
||||
1. List [enode URLs](../Node-Keys.md#enode-url) of the nodes in the [`static-nodes.json` file](#static-nodesjson-file). |
||||
|
||||
1. Save the `static-nodes.json` file in the data directory of each node. |
||||
|
||||
1. Start Pantheon with discovery disabled using [`--discovery-enabled=false`](../../Reference/Pantheon-CLI-Syntax.md#discovery-enabled). |
||||
|
||||
To modify the static peers at run time, use the [`admin_addPeer`](../../Reference/Pantheon-API-Methods.md#admin_addpeer) |
||||
and [`admin_removePeer`](../../Reference/Pantheon-API-Methods.md#admin_removepeer) JSON-RPC API methods. |
||||
|
||||
!!! note |
||||
Runtime modifications of static nodes are not persisted between runs. The `static-nodes.json` file |
||||
is not updated by `admin_addPeer` and `admin_removePeer` methods. |
||||
|
||||
Nodes outside of the static nodes are not prevented from connecting. To prevent nodes from connecting, |
||||
use [Permissioning](../../Permissions/Permissioning-Overview.md). |
||||
|
||||
!!! caution |
||||
If the added peer does not appear in the peer list (returned by [`admin_peers`](../../Reference/Pantheon-API-Methods.md#admin_peers)), |
||||
check the supplied [enode URL](../Node-Keys.md#enode-url) is correct, the node is running, the node is listening for |
||||
TCP connections on the endpoint, and has not reached the [maximum number of peers](#limiting-peers). |
||||
|
||||
### static-nodes.json File |
||||
|
||||
The `static-nodes.json` file must be located in the data directory (specified by [`--data-path`](../../Reference/Pantheon-CLI-Syntax.md#data-path)) |
||||
and contain a JSON array of [enode URLs](../Node-Keys.md#enode-url). |
||||
|
||||
!!! example |
||||
```json |
||||
[ |
||||
"enode://cea71cb65a471037e01508cebcc178f176f9d5267bf29507ea1f6431eb6a5dc67d086dc8dc54358a72299dab1161febc5d7af49d1609c69b42b5e54544145d4f@127.0.0.1:30303", |
||||
"enode://ca05e940488614402705a6b6836288ea902169ecc67a89e1bd5ef94bc0d1933f20be16bc881ffb4be59f521afa8718fc26eec2b0e90f2cd0f44f99bc8103e60f@127.0.0.1:30304" |
||||
] |
||||
``` |
||||
|
||||
!!! note |
||||
Each node has a `static-nodes.json` file. We recommend each node in the network has the same `static-nodes.json` file. |
||||
|
||||
## Monitoring Peer Connections |
||||
|
||||
JSON-RPC API methods to monitor peer connections include: |
||||
|
||||
* [`net_peerCount`](../../Reference/Pantheon-API-Methods.md#net_peercount) |
||||
* [`admin_peers`](../../Reference/Pantheon-API-Methods.md#admin_peers) |
||||
* [`debug_metrics`](../../Reference/Pantheon-API-Methods.md#debug_metrics) |
||||
|
||||
## Node Connections |
||||
|
||||
The default logging configuration does not list node connection and disconnection messages. |
||||
|
||||
To enable listing of node connection and disconnection messages, specify the |
||||
[`--logging`](../../Reference/Pantheon-CLI-Syntax.md#logging) command line option `--logging=DEBUG`. |
||||
For more verbosity, specify `--logging=TRACE`. |
||||
|
||||
The console logs connection and disconnection events when the log level is `DEBUG` or higher. |
||||
If `Successfully accepted connection from ...` is displayed, connections are getting through the firewalls. |
||||
|
||||
!!! example "Example log output" |
||||
`2018-10-16 12:37:35.479-04:00 | nioEventLoopGroup-3-1 | INFO | NettyP2PNetwork | Successfully accepted connection from 0xa979fb575495b8d6db44f750317d0f4622bf4c2aa3365d6af7c284339968eef29b69ad0dce72a4d8db5ebb4968de0e3bec910127f134779fbcb0cb6d3331163c` |
||||
|
||||
## Limiting Remote Connections |
||||
|
||||
In private networks with a level of trust between peers, enabling the [remote connection limits](../../Reference/Pantheon-CLI-Syntax.md#remote-connections-limit-enabled) |
||||
is unnecessary and disabling may increase the speed at which nodes can join the network. |
||||
|
||||
@ -1,32 +0,0 @@ |
||||
description: Configuring UPnP with Pantheon |
||||
<!--- END of page meta data --> |
||||
|
||||
# UPnP |
||||
|
||||
Enable UPnP to quickly allow inbound peer connections without manual router configuration. Use UPnP |
||||
in home or small office environments where a wireless router or modem provides NAT isolation. |
||||
|
||||
UPnP automatically detects that a node is running in a UPnP environment and provides port forwarding. |
||||
|
||||
!!! tip |
||||
UPnP support is often disabled by default in networking firmware. If disabled by default, explicitly |
||||
enable UPnP support. |
||||
|
||||
## Enabling UPnP |
||||
|
||||
Use the [`--nat-method`](../../Reference/Pantheon-CLI-Syntax.md#nat-method) command line option to enable UPnP. |
||||
|
||||
!!! note |
||||
Enabling UPnP may slow down node startup, especially on networks without a UPnP gateway device. |
||||
|
||||
When UPnP is enabled: |
||||
|
||||
* [Enode](../Node-Keys.md#enode-url) advertised to other nodes during discovery is the external IP address and port. |
||||
* External address and port are returned by the [`admin_NodeInfo`](../../Reference/Pantheon-API-Methods.md#admin_nodeinfo) |
||||
JSON-RPC API method for the `enode` and `listenAddr` properties. |
||||
|
||||
While Pantheon is running, UPnP does not support: |
||||
|
||||
* IP address changes |
||||
* Disabling UPnP. To disable UPnP, restart the node without the [`--nat-method`](../../Reference/Pantheon-CLI-Syntax.md#nat-method) |
||||
option or set to `NONE`. |
||||
@ -1,61 +0,0 @@ |
||||
description: Pantheon private and public key used to identify node |
||||
<!--- END of page meta data --> |
||||
|
||||
# Node Keys |
||||
|
||||
Each node has a node key pair consisting of a node private key and node public key. |
||||
|
||||
## Node Private Key |
||||
|
||||
If a `key` file does not exist in the data directory and the [`--node-private-key-file`](../Reference/Pantheon-CLI-Syntax.md#node-private-key-file) |
||||
option is not specified when Pantheon is started, a node private key is generated and written to the `key` file. |
||||
If Pantheon is stopped and restarted without deleting the `key` file, the same private key is used when Pantheon is restarted. |
||||
|
||||
If a `key` file exists in the data directory when Pantheon is started, the node is started with the private key in the `key` file. |
||||
|
||||
!!!info |
||||
The private key is not encrypted. |
||||
|
||||
## Node Public Key |
||||
|
||||
The node public key is displayed in the log after starting Pantheon. Use the [`public-key`](../Reference/Pantheon-CLI-Syntax.md#public-key) subcommand to export the public key to a file. |
||||
|
||||
The node public key is also referred to as the node ID. The node ID forms part of the enode URL for a node. |
||||
|
||||
## Enode URL |
||||
|
||||
Nodes are identified by their enode URL. For example, the `--bootnodes` option and `perm_addNodesToWhitelist` method specify nodes by the enode URL. |
||||
|
||||
The enode URL is `enode://<id>@<host:port>` where: |
||||
|
||||
* `<id>` is the node public key excluding the initial 0x. |
||||
* `<host:port>` is the host and port the bootnode is listening on for P2P peer discovery. |
||||
Specified by the [`--p2p-host`](../Reference/Pantheon-CLI-Syntax.md#p2p-host) and |
||||
[`--p2p-port`](../Reference/Pantheon-CLI-Syntax.md#p2p-port) options |
||||
(default host is `127.0.0.1` and port is `30303`). |
||||
|
||||
!!! example |
||||
If the [`--p2p-host`](../Reference/Pantheon-CLI-Syntax.md#p2p-host) or [`--p2p-port`](../Reference/Pantheon-CLI-Syntax.md#p2p-port) options are not specified and the node public key is `0xc35c3ec90a8a51fd5703594c6303382f3ae6b2ecb9589bab2c04b3794f2bc3fc2631dabb0c08af795787a6c004d8f532230ae6e9925cbbefb0b28b79295d615f` |
||||
|
||||
The enode URL is: |
||||
`enode://c35c3ec90a8a51fd5703594c6303382f3ae6b2ecb9589bab2c04b3794f2bc3fc2631dabb0c08af795787a6c004d8f532230ae6e9925cbbefb0b28b79295d615f@127.0.0.1:30303` |
||||
|
||||
The enode is displayed when starting a Pantheon node and can be obtained using the [`net_enode`](../Reference/Pantheon-API-Methods.md#net_enode) |
||||
JSON-RPC API method. |
||||
|
||||
If [UPnP](Networking/Using-UPnP.md) is enabled, the enode advertised to other nodes during discovery is the |
||||
external IP address and port. |
||||
|
||||
## Specifying a Custom Node Private Key File |
||||
|
||||
Use the [`--node-private-key-file`](../Reference/Pantheon-CLI-Syntax.md#node-private-key-file) option to specify a custom `key` file in any location. |
||||
|
||||
If the `key` file exists, the node is started with the private key in the custom `key` file. If the custom `key` file does not exist, |
||||
a node private key is generated and written to the custom `key` file. |
||||
|
||||
For example, the following command either reads the node private key from the `privatekeyfile` or writes the generated private key to the `privatekeyfile`: |
||||
|
||||
!!! example |
||||
```bash |
||||
pantheon --node-private-key-file="/Users/username/privatekeyfile" |
||||
``` |
||||
@ -1,16 +0,0 @@ |
||||
description: Passing Java virtual machine JVM options to Pantheon at runtime |
||||
<!--- END of page meta data --> |
||||
|
||||
# Passing JVM Options |
||||
|
||||
To perform tasks such as attaching a debugger or configuring the garbage collector, pass JVM options to Pantheon. |
||||
|
||||
Pantheon passes the contents of the `PANTHEON_OPTS` environmental variable to the JVM. Set standard JVM options in the `PANTHEON_OPTS` variable. |
||||
|
||||
For Bash-based executions, you can set the variable for only the scope of the program execution by setting it before starting Pantheon. |
||||
|
||||
!!! example |
||||
```bash |
||||
PANTHEON_OPTS=-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=5005 \ |
||||
pantheon --network=rinkeby |
||||
``` |
||||
@ -1,55 +0,0 @@ |
||||
# Using a Configuration File |
||||
|
||||
To specify command line options in a file, use a TOML configuration file. |
||||
|
||||
The configuration file can be saved and reused across node startups. To specify the configuration file, |
||||
use the [`--config-file`](../Reference/Pantheon-CLI-Syntax.md#config-file) option. |
||||
|
||||
To override an option specified in the configuration file, specify the same option on the command line or as |
||||
an [environment variable](../Reference/Pantheon-CLI-Syntax.md#pantheon-environment-variables). If an option is specified in multiple places, |
||||
the order of priority is command line, environment variable, configuration file. |
||||
|
||||
## TOML Specification |
||||
|
||||
The configuration file must be a valid TOML file and is composed of key/value pairs. Each key is the |
||||
same as the corresponding command line option name without the leading dashes (`--`). |
||||
|
||||
Values must be be specified according to TOML specifications for string, numbers, arrays, and booleans. |
||||
Specific differences between the command line and the TOML file format are: |
||||
|
||||
* Comma-separated lists on the command line are string arrays in the TOML file |
||||
* File paths, hexadecimal numbers, URLs, and <host:port> values must be enclosed in quotes. |
||||
|
||||
!!!tip |
||||
The [command line reference](../Reference/Pantheon-CLI-Syntax.md) includes configuration file examples for each option. |
||||
|
||||
!!!example "Example TOML configuration file" |
||||
```toml |
||||
# Valid TOML config file |
||||
data-path="~/pantheondata" # Path |
||||
|
||||
# Network |
||||
bootnodes=["enode://001@123:4567", "enode://002@123:4567", "enode://003@123:4567"] |
||||
|
||||
p2p-host="1.2.3.4" |
||||
p2p-port=1234 |
||||
max-peers=42 |
||||
|
||||
rpc-http-host="5.6.7.8" |
||||
rpc-http-port=5678 |
||||
|
||||
rpc-ws-host="9.10.11.12" |
||||
rpc-ws-port=9101 |
||||
|
||||
# Chain |
||||
genesis-file="~/genesis.json" # Path to the custom genesis file |
||||
|
||||
# Mining |
||||
miner-enabled=true |
||||
miner-coinbase="0xfe3b557e8fb62b89f4916b721be55ceb828dbd73" |
||||
``` |
||||
|
||||
!!!example "Starting Pantheon with a Configuration File" |
||||
```bash |
||||
pantheon --config-file=/home/me/me_node/config.toml |
||||
``` |
||||
@ -1,129 +0,0 @@ |
||||
description: Pantheon Clique Proof-of-Authority (PoA) consensus protocol implementation |
||||
path: blob/master/config/src/main/resources/ |
||||
source: rinkeby.json |
||||
<!--- END of page meta data --> |
||||
|
||||
*[vanity data]: Signers can include anything they like as vanity data. |
||||
|
||||
# Clique |
||||
|
||||
Pantheon implements the Clique Proof-of-Authority (PoA) consensus protocol. Clique is used by the |
||||
Rinkeby testnet and can be used for private networks. |
||||
|
||||
In Clique networks, transactions and blocks are validated by approved accounts, known as signers. |
||||
Signers take turns to create the next block. Existing signers propose and vote to add or remove signers. |
||||
|
||||
## Genesis File |
||||
|
||||
To use Clique in a private network, Pantheon requires a Clique genesis file. When connecting to Rinkeby, |
||||
Pantheon uses the [`rinkeby.json`](https://github.com/PegaSysEng/pantheon/blob/master/config/src/main/resources/rinkeby.json) |
||||
genesis file in the `/pantheon/config/src/main/resources` directory. |
||||
|
||||
A PoA genesis file defines properties specific to Clique: |
||||
|
||||
!!! example "Example Clique Genesis File" |
||||
```json |
||||
{ |
||||
"config":{ |
||||
"chainId":1981, |
||||
"constantinoplefixblock": 0, |
||||
"clique":{ |
||||
"blockperiodseconds":15, |
||||
"epochlength":30000 |
||||
} |
||||
}, |
||||
"coinbase":"0x0000000000000000000000000000000000000000", |
||||
"difficulty":"0x1", |
||||
"extraData":"0x000000000000000000000000000000000000000000000000000000000000000001a54556254bfa3db2daa7673435ec63649925c50000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000", |
||||
"gasLimit":"0xa00000", |
||||
"mixHash":"0x0000000000000000000000000000000000000000000000000000000000000000", |
||||
"nonce":"0x0", |
||||
"timestamp":"0x5c51a607", |
||||
"alloc": {}, |
||||
"number":"0x0", |
||||
"gasUsed":"0x0", |
||||
"parentHash":"0x0000000000000000000000000000000000000000000000000000000000000000" |
||||
} |
||||
``` |
||||
|
||||
The properties specific to Clique are: |
||||
|
||||
* `blockperiodseconds` - Block time in seconds. |
||||
* `epochlength` - Number of blocks after which to reset all votes. |
||||
* `extraData` - Initial signers are specified after the 32 bytes reserved for vanity data. |
||||
|
||||
### Extra Data |
||||
|
||||
The `extraData` field consists of: |
||||
|
||||
* 0x prefix |
||||
* 32 bytes (64 hex characters) of vanity data |
||||
* Concatenated list of initial signer addresses. 20 bytes (40 hex characters) for each signer. At least one |
||||
initial signer must be specified. |
||||
* 65 bytes (130 hex characters) for proposer signature. In the genesis block there is no initial proproser so the proproser signature is all zeros. |
||||
|
||||
!!! example "One Initial Signer" |
||||
`extraData` field for a Clique network with one initial signer with an address of `dd37f65db31c107f773e82a4f85c693058fef7a9` |
||||
|
||||
`0x0000000000000000000000000000000000000000000000000000000000000000dd37f65db31c107f773e82a4f85c693058fef7a90000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000` |
||||
|
||||
!!! example "Two Initial Signers" |
||||
`extraData` field for a Clique network with two initial signers with addresses of `dd37f65db31c107f773e82a4f85c693058fef7a9` and `b9b81ee349c3807e46bc71aa2632203c5b462034`. |
||||
|
||||
`0x0000000000000000000000000000000000000000000000000000000000000000dd37f65db31c107f773e82a4f85c693058fef7a9b9b81ee349c3807e46bc71aa2632203c5b4620340000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000` |
||||
|
||||
## Connecting to Clique Network |
||||
|
||||
To connect to the Rinkeby testnet, start Pantheon with the [`--network=rinkeby`](../Reference/Pantheon-CLI-Syntax.md#network) |
||||
command line option. To start a node on a Clique private network, use the |
||||
[`--genesis-file`](../Reference/Pantheon-CLI-Syntax.md#genesis-file) option to specify the custom genesis file. |
||||
|
||||
## Adding and Removing Signers |
||||
|
||||
To propose adding or removing signers using the JSON-RPC methods, enable the HTTP interface |
||||
using [`--rpc-http-enabled`](../Reference/Pantheon-CLI-Syntax.md#rpc-http-enabled) or WebSockets interface using |
||||
[`--rpc-ws-enabled`](../Reference/Pantheon-CLI-Syntax.md#rpc-ws-enabled). |
||||
|
||||
The Clique API methods are not enabled by default. To enable, specify the [`--rpc-http-api`](../Reference/Pantheon-CLI-Syntax.md#rpc-http-api) |
||||
or [`--rpc-ws-api`](../Reference/Pantheon-CLI-Syntax.md#rpc-ws-api) option and include `CLIQUE`. |
||||
|
||||
The JSON-RPC methods to add or remove signers are: |
||||
|
||||
* [clique_propose](../Reference/Pantheon-API-Methods.md#clique_propose) |
||||
* [clique_getSigners](../Reference/Pantheon-API-Methods.md#clique_getsigners) |
||||
* [clique_discard](../Reference/Pantheon-API-Methods.md#clique_discard) |
||||
|
||||
To propose adding a signer, call `clique_propose` specifying the address of the proposed signer and `true`. |
||||
!!! example "JSON-RPC clique_propose Request Example" |
||||
```bash |
||||
curl -X POST --data '{"jsonrpc":"2.0","method":"clique_propose","params":["0xFE3B557E8Fb62b89F4916B721be55cEb828dBd73", true], "id":1}' <JSON-RPC-endpoint:port> |
||||
``` |
||||
|
||||
When the next block is created by the signer, a vote is added to the block for the proposed signer. |
||||
|
||||
When more than half of the existing signers propose adding the signer and their votes have been |
||||
distributed in blocks, the signer is added and can begin signing blocks. |
||||
|
||||
Use `clique_getSigners` to return a list of the signers and to confirm that your proposed signer has |
||||
been added. |
||||
!!! example "JSON-RPC clique_getSigners Request Example" |
||||
```bash |
||||
curl -X POST --data '{"jsonrpc":"2.0","method":"clique_getSigners","params":["latest"], "id":1}' <JSON-RPC-endpoint:port> |
||||
``` |
||||
|
||||
To discard your proposal after confirming the signer was added, call `clique_discard` specifying the address of the proposed signer. |
||||
!!! example "JSON-RPC clique_discard Request Example" |
||||
```bash |
||||
curl -X POST --data '{"jsonrpc":"2.0","method":"clique_discard","params":["0xFE3B557E8Fb62b89F4916B721be55cEb828dBd73"], "id":1}' <JSON-RPC-endpoint:port> |
||||
``` |
||||
|
||||
The process for removing a signer is the same as adding a signer except you specify `false` as the |
||||
second parameter of `clique_propose`. |
||||
|
||||
### Epoch Transition |
||||
|
||||
At each epoch transition, all pending votes collected from received blocks are discarded. |
||||
Existing proposals remain in effect and signers re-add their vote the next time they create a block. |
||||
|
||||
Define the number of blocks between epoch transitions in the genesis file. |
||||
|
||||
@ -1,67 +0,0 @@ |
||||
*[Byzantine fault tolerant]: Ability to function correctly and reach consensus despite nodes failing or propagating incorrect information to peers. |
||||
|
||||
# Comparing Proof of Authority Consensus Protocols |
||||
|
||||
Pantheon implements the Clique and IBFT 2.0 Proof of Authority consensus protocols. Proof of Authority |
||||
consensus protocols are used when participants are known to each other and there is a level of trust between them. |
||||
For example, in a permissioned consortium network. |
||||
|
||||
Proof of Authority consensus protocols allow faster block times and have a much greater throughput of transactions |
||||
than the Ethash Proof of Work consensus protocol used on the Ethereum MainNet. |
||||
|
||||
In Clique and IBFT 2.0, a group of nodes in the network act as signers (Clique) or validators (IBFT 2.0). These nodes propose, validate, |
||||
and add blocks to the blockchain. Nodes are added to or removed from the signer/validator pool by the existing group of nodes voting. |
||||
|
||||
!!! note |
||||
For the rest of this page, the term validator is used to refer to signers and validators. |
||||
|
||||
## Properties |
||||
|
||||
Properties to consider when comparing Clique and IBFT 2.0 are: |
||||
|
||||
* Immediate finality |
||||
* Minimum number of validators |
||||
* Liveness |
||||
* Speed |
||||
|
||||
### Immediate Finality |
||||
|
||||
IBFT 2.0 has immediate finality. When using IBFT 2.0 there are no forks and all valid blocks are included in the main chain. |
||||
|
||||
Clique does not have immediate finality. Implementations using Clique must be aware of forks and chain reorganizations occurring. |
||||
|
||||
### Minimum Number of Validators |
||||
|
||||
IBFT 2.0 requires 4 validators to be Byzantine fault tolerant. |
||||
|
||||
Clique can operate with a single validator but operating with a single validator offers no redundancy if |
||||
the validator fails. |
||||
|
||||
### Liveness |
||||
|
||||
Clique is more fault tolerant than IBFT 2.0. Clique tolerates up to half to the validators failing. IBFT 2.0 networks |
||||
require greater than or equal to 2/3 of validators to be operating to create blocks. For example, in an IBFT 2.0 network of: |
||||
|
||||
* 4-5, 1 unresponsive node is tolerated |
||||
* 6-8, 2 unresponsive nodes are tolerated |
||||
|
||||
Networks with 3 or less validators are able to produce blocks but do not guarantee finality when operating |
||||
in adversarial environments. |
||||
|
||||
!!! important |
||||
We recommend not using IBFT 2.0 networks with 3 nodes for production purposes. |
||||
|
||||
### Speed |
||||
|
||||
Reaching consensus and adding blocks is faster in Clique networks. For Clique, the probability of a fork |
||||
increases number as the of validators increases. |
||||
|
||||
For IBFT 2.0, the time to add new blocks increases as the number of validators increases. |
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
@ -1,76 +0,0 @@ |
||||
*[Byzantine fault tolerant]: Ability to function correctly and reach consensus despite nodes failing or propagating incorrect information to peers. |
||||
|
||||
# Comparing Proof of Authority Consensus Protocols |
||||
|
||||
Pantheon implements the Clique and IBFT 2.0 Proof of Authority consensus protocols. Proof of Authority |
||||
consensus protocols are used when participants are known to each other and there is a level of trust between them. |
||||
For example, in a permissioned consortium network. |
||||
|
||||
Proof of Authority consensus protocols allow faster block times and have a much greater throughput of transactions |
||||
than the Ethash Proof of Work consensus protocol used on the Ethereum MainNet. |
||||
|
||||
In Clique and IBFT 2.0, a group of nodes in the network act as signers (Clique) or validators (IBFT 2.0). These nodes propose, validate, |
||||
and add blocks to the blockchain. Nodes are added to or removed from the signer/validator pool by the existing group of nodes voting. |
||||
|
||||
!!! note |
||||
For the rest of this page, the term validator is used to refer to signers and validators. |
||||
|
||||
## Properties |
||||
|
||||
Properties to consider when comparing Clique and IBFT 2.0 are: |
||||
|
||||
* [Immediate finality](#immediate-finality) |
||||
* [Required validator availability](#required-validator-availability) |
||||
* [Type of Byzantine Fault Tolerance](#type-of-byzantine-fault-tolerance) |
||||
* [Speed](#speed) |
||||
|
||||
### Immediate Finality |
||||
|
||||
IBFT 2.0 has immediate finality. When using IBFT 2.0 there are no forks and all valid blocks are included in the main chain. |
||||
|
||||
Clique does not have immediate finality. Implementations using Clique must be aware of forks and chain reorganizations occurring. |
||||
|
||||
### Required Validator Availability |
||||
|
||||
For the network to be able to create blocks and progress, the amount of validators (rounded up to the next integer) |
||||
required to be online is at least: |
||||
|
||||
* 2/3 for IBFT 2.0. |
||||
* 1/2 for Clique. |
||||
|
||||
### Type of Byzantine Fault Tolerance |
||||
|
||||
#### IBFT 2.0 |
||||
|
||||
IBFT 2.0 features a classical BFT consensus protocol that ensures safety (no fork is possible) provided that no more than |
||||
(n-1)/3 of the validators (truncated to the integer value) are Byzantine. |
||||
For example in an IBFT 2.0 network of: |
||||
|
||||
* 3, no Byzantine nodes are tolerated |
||||
* 4-6, 1 Byzantine node is tolerated |
||||
* 7-9, 2 Byzantine nodes are tolerated |
||||
|
||||
If more than (n-1)/3 of the validators (truncated to the integer value) are Byzantine, forks and reorganizations may occur |
||||
from any height after which sufficient nodes were compromised. |
||||
|
||||
#### Clique |
||||
|
||||
Clique features a probabilistic consensus protocol (like Nakamoto) where minor forks always occur. The deeper a block is |
||||
in the chain, the more probable it is that the block is final (that is, the block will not be part of a reorganization event). |
||||
The higher the network latency is, the more depth is required for a block to be considered stable. |
||||
|
||||
If more than 1/2 of the validators (rounded up to the next integer) are Byzantine, the network is compromised |
||||
and the history of the chain can be re-written. |
||||
|
||||
### Speed |
||||
|
||||
Reaching consensus and adding blocks is faster in Clique networks. For Clique, the probability of a fork |
||||
increases as the number of validators increases. |
||||
|
||||
For IBFT 2.0, the time to add new blocks increases as the number of validators increases. |
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
@ -1,169 +0,0 @@ |
||||
description: Pantheon IBFT 2.0 Proof-of-Authority (PoA) consensus protocol implementation |
||||
<!--- END of page meta data --> |
||||
|
||||
*[Vanity]: Validators can include anything they like as vanity data. |
||||
*[RLP]: Recursive Length Prefix |
||||
*[Byzantine fault tolerant]: Ability to function correctly and reach consensus despite nodes failing or propagating incorrect information to peers. |
||||
|
||||
# IBFT 2.0 |
||||
|
||||
Pantheon implements the IBFT 2.0 Proof-of-Authority (PoA) consensus protocol. IBFT 2.0 can be used for private networks. |
||||
|
||||
In IBFT 2.0 networks, transactions and blocks are validated by approved accounts, known as validators. |
||||
Validators take turns to create the next block. Existing validators propose and vote to add or remove validators. |
||||
|
||||
## Minimum Number of Validators |
||||
|
||||
IBFT 2.0 requires 4 validators to be Byzantine fault tolerant. |
||||
|
||||
## Genesis File |
||||
|
||||
To use IBFT 2.0 requires an IBFT 2.0 genesis file. The genesis file defines properties specific to IBFT 2.0: |
||||
|
||||
!!! example "Example IBFT 2.0 Genesis File" |
||||
```json |
||||
{ |
||||
"config": { |
||||
"chainId": 1981, |
||||
"constantinoplefixblock": 0, |
||||
"ibft2": { |
||||
"blockperiodseconds": 2, |
||||
"epochlength": 30000, |
||||
"requesttimeoutseconds": 10 |
||||
} |
||||
}, |
||||
"nonce": "0x0", |
||||
"timestamp": "0x58ee40ba", |
||||
"extraData": "0xf83ea00000000000000000000000000000000000000000000000000000000000000000d594c2ab482b506de561668e07f04547232a72897daf808400000000c0", |
||||
"gasLimit": "0x47b760", |
||||
"difficulty": "0x1", |
||||
"mixHash": "0x63746963616c2062797a616e74696e65206661756c7420746f6c6572616e6365", |
||||
"coinbase": "0x0000000000000000000000000000000000000000", |
||||
"alloc": {} |
||||
} |
||||
``` |
||||
|
||||
Properties specific to IBFT 2.0 are: |
||||
|
||||
* `blockperiodseconds` - Minimum block time in seconds. |
||||
* `epochlength` - Number of blocks after which to reset all votes. |
||||
* `requesttimeoutseconds` - Timeout for each consensus round before a round change. |
||||
* `extraData` - `RLP([32 Bytes Vanity, List<Validators>, No Vote, Round=Int(0), 0 Seals])` |
||||
|
||||
Properties that have specific values in IBFT 2.0 genesis files are: |
||||
|
||||
* `nonce` - `0x0` |
||||
* `difficulty` - `0x1` |
||||
* `mixHash` - `0x63746963616c2062797a616e74696e65206661756c7420746f6c6572616e6365` for Istanbul block identification. |
||||
|
||||
To start a node on an IBFT 2.0 private network, use the [`--genesis-file`](../Reference/Pantheon-CLI-Syntax.md#genesis-file) option to specify the custom genesis file. |
||||
|
||||
### Extra Data |
||||
|
||||
The `extraData` property is RLP encoded. RLP encoding is a space efficient object serialization scheme |
||||
used in Ethereum. Use the Pantheon subcommand [`rlp encode`](../Reference/Pantheon-CLI-Syntax.md#rlp) |
||||
to generate the `extraData` RLP string to include in the genesis file. |
||||
|
||||
!!! example |
||||
```bash |
||||
pantheon rlp encode --from=toEncode.json |
||||
``` |
||||
|
||||
Where the `toEncode.json` file contains a list of the initial validators in ascending order. |
||||
|
||||
!!! example "One Initial Validator" |
||||
```json |
||||
[ |
||||
"9811ebc35d7b06b3fa8dc5809a1f9c52751e1deb" |
||||
] |
||||
``` |
||||
|
||||
Copy the RLP encoded data to the `extraData` in the genesis file. |
||||
|
||||
### Block Time |
||||
|
||||
When a new chain head is received, the block time (`blockperiodseconds`) and round timeout (`requesttimeoutseconds`) |
||||
timers are started. When `blockperiodseconds` is reached, a new block is proposed. |
||||
|
||||
If `requesttimeoutseconds` is reached before the proposed block is added, a round change occurs, and the block time and |
||||
timeout timers are reset. The timeout period for the new round is two times `requesttimeoutseconds`. The |
||||
timeout period continues to double each time a round fails to add a block. |
||||
|
||||
Generally, the proposed block is added before reaching `requesttimeoutseconds`. A new round is then started, |
||||
and the block time and round timeout timers are reset. When `blockperiodseconds` is reached, the next new block is proposed. |
||||
|
||||
The time from proposing a block to the block being added is small (around 1s) even in networks |
||||
with geographically dispersed validators. Setting `blockperiodseconds` to your desired block time and `requesttimeoutseconds` |
||||
to two times `blockperiodseconds` generally results in blocks being added every `blockperiodseconds`. |
||||
|
||||
!!! example |
||||
An internal PegaSys IBFT 2.0 testnet has 4 geographically dispersed validators in Sweden, |
||||
Sydney, and North Virginia (2 validators). With a `blockperiodseconds`of 5 and a `requesttimeoutseconds` of 10, |
||||
the testnet consistently creates block with a 5 second blocktime. |
||||
|
||||
### Optional Configuration Options |
||||
|
||||
Optional configuration options that can be specified in the genesis file are: |
||||
|
||||
* `messageQueueLimit` - Default is 1000. In very large networks with insufficient resources increasing the message queue limit |
||||
may help to deal with message activity surges. |
||||
|
||||
* `duplicateMesageLimit` - Default is 100. If seeing messages being retransmitted by the same node, increasing the duplicate message limit |
||||
may reduce the number of retransmissions. A value of 2 to 3 times the number of validators is generally sufficient. |
||||
|
||||
* `futureMessagesLimit` - Default is 1000. The future messages buffer holds IBFT 2.0 messages for a future chain height. |
||||
For large networks, increasing the future messages limit may be useful. |
||||
|
||||
* `futureMessagesMaxDistance` - Default is 10. Specifies the maximum height from the current chain height |
||||
for which messages are buffered in the future messages buffer. |
||||
|
||||
## Adding and Removing Validators |
||||
|
||||
To propose adding or removing validators using the JSON-RPC methods, enable the HTTP interface |
||||
using [`--rpc-http-enabled`](../Reference/Pantheon-CLI-Syntax.md#rpc-http-enabled) or WebSockets interface using |
||||
[`--rpc-ws-enabled`](../Reference/Pantheon-CLI-Syntax.md#rpc-ws-enabled). |
||||
|
||||
The IBFT API methods are not enabled by default. To enable, specify the [`--rpc-http-api`](../Reference/Pantheon-CLI-Syntax.md#rpc-http-api) |
||||
or [`--rpc-ws-api`](../Reference/Pantheon-CLI-Syntax.md#rpc-ws-api) option and include `IBFT`. |
||||
|
||||
The JSON-RPC methods to add or remove validators are: |
||||
|
||||
* [ibft_getPendingVotes](../Reference/Pantheon-API-Methods.md#ibft_getPendingVotes) |
||||
* [ibft_proposeValidatorVote](../Reference/Pantheon-API-Methods.md#ibft_proposeValidatorVote) |
||||
* [ibft_discardValidatorVote](../Reference/Pantheon-API-Methods.md#ibft_discardValidatorVote) |
||||
|
||||
To propose adding a validator, call `ibft_proposeValidatorVote` specifying the address of the node to be added and `true`. |
||||
!!! example "JSON-RPC ibft_proposeValidatorVote Request Example" |
||||
```bash |
||||
curl -X POST --data '{"jsonrpc":"2.0","method":"ibft_proposeValidatorVote","params":["0xFE3B557E8Fb62b89F4916B721be55cEb828dBd73", true], "id":1}' <JSON-RPC-endpoint:port> |
||||
``` |
||||
|
||||
When the next block is proposed by the validator, one proposal received from `ibft_proposeValidatorVote` is inserted in the block. |
||||
If all proposals have been included in blocks, subsequent blocks proposed by the validator will not contain a vote. |
||||
|
||||
When more than half of the existing validators have published a matching proposal, the proposed validator is added to the validator pool and can begin validating blocks. |
||||
|
||||
Use `ibft_getValidatorsByBlockNumber` to return a list of the validators and confirm your proposed validator has been added. |
||||
|
||||
!!! example "JSON-RPC ibft_getValidatorsByBlockNumber Request Example" |
||||
```bash |
||||
curl -X POST --data '{"jsonrpc":"2.0","method":"ibft_getValidatorsByBlockNumber","params":["latest"], "id":1}' <JSON-RPC-endpoint:port> |
||||
``` |
||||
|
||||
To discard your proposal after confirming the validator was added, call `ibft_discardValidatorVote` specifying the address of the proposed validator. |
||||
|
||||
!!! example "JSON-RPC ibft_discardValidatorVote Request Example" |
||||
```bash |
||||
curl -X POST --data '{"jsonrpc":"2.0","method":"ibft_discardValidatorVote","params":["0xFE3B557E8Fb62b89F4916B721be55cEb828dBd73"], "id":1}' <JSON-RPC-endpoint:port> |
||||
``` |
||||
|
||||
The process for removing a validator is the same as adding a validator except you specify `false` as the second parameter of `ibft_proposeValidatorVote`. |
||||
|
||||
### Epoch Transition |
||||
|
||||
At each epoch transition, all pending votes collected from received blocks are discarded. Existing proposals remain |
||||
in effect and validators re-add their vote the next time they create a block. |
||||
|
||||
An epoch transition occurs every `epochLength` blocks where `epochlength` is defined in the IBFT genesis file. |
||||
|
||||
|
||||
@ -1,65 +0,0 @@ |
||||
description: Pantheon consensus protocols |
||||
<!--- END of page meta data --> |
||||
|
||||
# Consensus Protocols |
||||
|
||||
Pantheon implements a number of consensus protocols: |
||||
|
||||
* Ethash (Proof of Work) |
||||
|
||||
* [Clique](Clique.md) (Proof of Authority) |
||||
|
||||
* [IBFT 2.0](IBFT.md) (Proof of Authority) |
||||
|
||||
* [Quorum IBFT 1.0](QuorumIBFT.md) (Proof of Authority) |
||||
|
||||
The genesis file specifies the consensus protocol for a chain in the `config` property: |
||||
|
||||
```json tab="Ethash" |
||||
{ |
||||
"config": { |
||||
... |
||||
"ethash": { |
||||
|
||||
} |
||||
}, |
||||
... |
||||
} |
||||
``` |
||||
|
||||
```json tab="Clique" |
||||
{ |
||||
"config": { |
||||
.... |
||||
"clique": { |
||||
... |
||||
} |
||||
}, |
||||
... |
||||
} |
||||
``` |
||||
|
||||
```json tab="IBFT 2.0" |
||||
{ |
||||
"config": { |
||||
.... |
||||
"ibft2": { |
||||
... |
||||
} |
||||
}, |
||||
... |
||||
} |
||||
``` |
||||
|
||||
```json tab="IBFT 1.0" |
||||
{ |
||||
"config": { |
||||
.... |
||||
"ibft": { |
||||
... |
||||
} |
||||
}, |
||||
... |
||||
} |
||||
``` |
||||
|
||||
@ -1,23 +0,0 @@ |
||||
description: Pantheon consensus protocols |
||||
<!--- END of page meta data --> |
||||
|
||||
# IBFT 1.0 |
||||
|
||||
Pantheon nodes can participate (submit transactions and receive blocks) in a Quorum [IBFT 1.0](https://github.com/ethereum/EIPs/issues/650) |
||||
network but cannot be a validator. |
||||
|
||||
To connect to a Quorum IBFT 1.0 network: |
||||
|
||||
1. In the Quorum IBFT 1.0 genesis file, update the consensus protocol specified in the `config` property |
||||
from `istanbul` to `ibft`: |
||||
|
||||
```json |
||||
"config": { |
||||
... |
||||
"ibft": { |
||||
... |
||||
} |
||||
``` |
||||
|
||||
1. Use the [`--genesis-file`](../Reference/Pantheon-CLI-Syntax.md#genesis-file) option to specify the |
||||
IBFT 1.0 genesis file. |
||||
@ -1,7 +0,0 @@ |
||||
title: Deploy Pantheon with Ansible |
||||
description: Deploying Pantheon with Ansible role on Galaxy |
||||
<!--- END of page meta data --> |
||||
|
||||
Use the [Pantheon role](https://galaxy.ansible.com/pegasyseng/pantheon) published on Galaxy to deploy Pantheon using Ansible. |
||||
|
||||
Refer to the [Readme](https://galaxy.ansible.com/pegasyseng/pantheon) for details. |
||||
@ -1,101 +0,0 @@ |
||||
description: Pantheon high availability |
||||
<!--- END of page meta data --> |
||||
|
||||
# High Availability of JSON-RPC and RPC Rub/Sub APIs |
||||
|
||||
To enable high availability to the [RPC Pub/Sub API over WebSockets](../Pantheon-API/RPC-PubSub.md) |
||||
or the [JSON-RPC API](../Pantheon-API/Using-JSON-RPC-API.md) run and synchronize multiple Pantheon |
||||
nodes to the network. Use a load balancer to distribute requests across nodes in the cluster that |
||||
are ready to receive requests. |
||||
|
||||
 |
||||
|
||||
## Determining When a Node is Ready |
||||
|
||||
Use the [readiness endpoint](../Pantheon-API/Using-JSON-RPC-API.md#readiness-and-liveness-endpoints) |
||||
to determine when a node is ready. |
||||
|
||||
!!! note |
||||
The minimum number of peers and number of blocks from the best known block for a node to be considered ready |
||||
is deployment specific. |
||||
|
||||
## Transaction Nonces |
||||
|
||||
The account nonce for the next transaction is obtained using [`eth_getTransactionCount`](../Reference/Pantheon-API-Methods.md#eth_gettransactioncount). |
||||
The account nonce depends on the transactions in the [transaction pool](../Using-Pantheon/Transactions/Transaction-Pool.md). |
||||
If [`eth_getTransactionCount`](../Reference/Pantheon-API-Methods.md#eth_gettransactioncount) and |
||||
[`eth_sendRawTransaction`](../Reference/Pantheon-API-Methods.md#eth_sendrawtransaction) requests for a specific account |
||||
are sent to multiple nodes, the [`eth_getTransactionCount`](../Reference/Pantheon-API-Methods.md#eth_gettransactioncount) |
||||
results can be incorrect. |
||||
|
||||
!!! note |
||||
If using [private transactions](../Privacy/Explanation/Privacy-Overview.md), `priv_getTransactionCount` is used to obtain |
||||
the account nonce and [`eea_sendRawTransaction`](../Reference/Pantheon-API-Methods.md#eea_sendrawtransaction) |
||||
to send private transactions. |
||||
|
||||
To get correct account nonces when distributing requests across a cluster, do one of: |
||||
|
||||
* Track the next nonce outside of the Pantheon node (as MetaMask does) |
||||
* Configure the load balancer in sticky mode so requests from a specific account are sent to a single |
||||
node unless that node is unavailable. |
||||
|
||||
## Subscriptions |
||||
|
||||
You can subscribe to events using: |
||||
|
||||
* [RPC Pub/Sub over WebSockets](../Pantheon-API/RPC-PubSub.md) |
||||
* [Filters over HTTP](../Using-Pantheon/Accessing-Logs-Using-JSON-RPC.md) |
||||
|
||||
We recommend using [RPC Pub/Sub over WebSockets](../Pantheon-API/RPC-PubSub.md) because WebSockets |
||||
connections are associated a specific node and do not require using the load balancer in sticky mode. |
||||
|
||||
If using [filters over HTTP](../Using-Pantheon/Accessing-Logs-Using-JSON-RPC.md), configure the load balancer |
||||
in sticky mode to associate the subscription with a specific node. |
||||
|
||||
## Recovering from Dropped Subscriptions |
||||
|
||||
Subscriptions can be dropped if: |
||||
|
||||
* WebSockets connection is disconnected |
||||
* Node serving the subscription is removed from the ready pool |
||||
|
||||
If a subscription is dropped, events can be missed while reconnecting to a different node. |
||||
To recover dropped messages, create another subscription and follow the process for that [subscription type](../Pantheon-API/RPC-PubSub.md#subscribing): |
||||
|
||||
* [`newHeads`](#new-headers) |
||||
* [`logs`](#logs) |
||||
* [`newPendingTransactions`](#new-pending-transactions) |
||||
* [`droppedPendingTransactions`](#dropped-pending-transactions) |
||||
* [`syncing`](#syncing) |
||||
|
||||
|
||||
### New Headers |
||||
|
||||
Use [`eth_getBlockByNumber`](../Reference/Pantheon-API-Methods.md#eth_getblockbynumber) to request information on |
||||
blocks from the last block before the subscription dropped to the first block received from the new subscription. |
||||
|
||||
### Logs |
||||
|
||||
Use [`eth_getLogs`](../Reference/Pantheon-API-Methods.md#eth_getlogs) to request logs from the block number |
||||
of the last log received before the subscription dropped to the current chain head. |
||||
|
||||
### New Pending Transactions |
||||
|
||||
Use [`txpool_pantheonTransactions`](../Reference/Pantheon-API-Methods.md#txpool_pantheontransactions) to |
||||
request all pending transactions for the new node. |
||||
|
||||
!!! note |
||||
Nodes do not all store the same pending transactions. |
||||
|
||||
### Dropped Pending Transactions |
||||
|
||||
Use [`txpool_pantheonTransactions`](../Reference/Pantheon-API-Methods.md#txpool_pantheontransactions) to |
||||
request all pending transactions for the new node. |
||||
|
||||
!!! note |
||||
Nodes do not all store the same pending transactions. |
||||
|
||||
### Syncing |
||||
|
||||
The syncing state of each node is specific to that node. Use [`eth_syncing`](../Reference/Pantheon-API-Methods.md#eth_syncing) |
||||
to retrieve the syncing state of the new node. |
||||
@ -1,56 +0,0 @@ |
||||
description: Migrating from pre v1.2 Docker image to v1.2 Docker image |
||||
<!--- END of page meta data --> |
||||
|
||||
# Migrating from pre-1.2 Docker Image to 1.2+ |
||||
|
||||
## Before v1.2 |
||||
|
||||
The Pantheon Docker image had an entry-script that automatically added a number of options |
||||
to the Pantheon command line. The options could not be set using command line arguments. |
||||
|
||||
The options automatically added to the Pantheon command line for the Pantheon Docker image before v1.2 were: |
||||
|
||||
* If the file existed: |
||||
|
||||
- [`--config-file /etc/pantheon/pantheon.conf`](../Reference/Pantheon-CLI-Syntax.md#config-file) |
||||
- [`--genesis-file /etc/pantheon/genesis.json`](../Reference/Pantheon-CLI-Syntax.md#genesis-file) |
||||
- [`--rpc-http-authentication-credentials-file /etc/pantheon/rpc_http_auth_config.toml`](../Reference/Pantheon-CLI-Syntax.md#rpc-http-authentication-credentials-file) |
||||
- [`--rpc-ws-authentication-credentials-file /etc/pantheon/rpc_ws_auth_config.toml`](../Reference/Pantheon-CLI-Syntax.md#rpc-ws-authentication-credentials-file) |
||||
- [`--privacy-public-key-file /etc/pantheon/privacy_public_key`](../Reference/Pantheon-CLI-Syntax.md#privacy-public-key-file) |
||||
- [`--permissions-nodes-config-file /etc/pantheon/permissions_config.toml`](../Reference/Pantheon-CLI-Syntax.md#permissions-nodes-config-file) |
||||
- [`--permissions-accounts-config-file /etc/pantheon/permissions_config.toml`](../Reference/Pantheon-CLI-Syntax.md#permissions-accounts-config-file) |
||||
|
||||
* [`--data-path /var/lib/pantheon`](../Reference/Pantheon-CLI-Syntax.md#data-path) |
||||
* [`--rpc-http-host=0.0.0.0`](../Reference/Pantheon-CLI-Syntax.md#rpc-http-host) |
||||
* [`--rpc-http-port=8545`](../Reference/Pantheon-CLI-Syntax.md#rpc-http-port) |
||||
* [`--rpc-ws-host=0.0.0.0`](../Reference/Pantheon-CLI-Syntax.md#rpc-ws-host) |
||||
* [`--rpc-ws-port=8546`](../Reference/Pantheon-CLI-Syntax.md#rpc-ws-port) |
||||
* [`--p2p-host=0.0.0.0`](../Reference/Pantheon-CLI-Syntax.md#p2p-host) |
||||
* [`--p2p-port=30303`](../Reference/Pantheon-CLI-Syntax.md#p2p-port) |
||||
|
||||
The [`--node-private-key-file`](../Reference/Pantheon-CLI-Syntax.md#node-private-key-file) command line option |
||||
was not available and the node key was always read from the data path. |
||||
|
||||
## From v1.2 |
||||
|
||||
All file options (for example, [`--config-file`](../Reference/Pantheon-CLI-Syntax.md#config-file)) no longer |
||||
have a default. Add the relevant command line options to your Pantheon command line and specify the file path. |
||||
|
||||
The [`--data-path`](../Reference/Pantheon-CLI-Syntax.md#data-path) default is now `/opt/pantheon`. |
||||
|
||||
The [`--node-private-key-file`](../Reference/Pantheon-CLI-Syntax.md#node-private-key-file) default is |
||||
now `/opt/pantheon/key`. |
||||
|
||||
!!! important |
||||
Do not mount a volume at the default data path (`/opt/pantheon`). Mounting a volume at the default |
||||
data path path interferes with the operation of Pantheon and prevents Pantheon from safely launching. |
||||
|
||||
To run a node that maintains the node state (key and database), [`--data-path` must be set to a location |
||||
other than `/opt/pantheon` and a storage volume mounted at that location](../Getting-Started/Run-Docker-Image.md#starting-pantheon). |
||||
|
||||
The host and port options continue to default to the previously set values. |
||||
|
||||
!!! tip |
||||
All command line options can be set using [environment variables](../Reference/Pantheon-CLI-Syntax.md#pantheon-environment-variables). |
||||
|
||||
|
||||
|
Before Width: | Height: | Size: 28 KiB |
|
Before Width: | Height: | Size: 15 KiB |
|
Before Width: | Height: | Size: 24 KiB |
@ -1,14 +0,0 @@ |
||||
description: Getting started with Pantheon |
||||
<!--- END of page meta data --> |
||||
|
||||
# Getting Started Overview |
||||
|
||||
Get started with Pantheon by: |
||||
|
||||
* [Installing Pantheon](../Installation/Install-Binaries.md) and [starting a node](Starting-Pantheon.md) |
||||
* Running from the [Pantheon Docker image](Run-Docker-Image.md) |
||||
* Using the [Private Network Quickstart](../Tutorials/Private-Network-Quickstart.md) |
||||
|
||||
The fastest way to run a single node and connect to the Ethereum mainnet (or a public testnet) is by using the [Docker image](Run-Docker-Image.md). |
||||
|
||||
To run a private network on which you can make JSON-RPC requests and send transactions, the [Private Network Quickstart](../Tutorials/Private-Network-Quickstart.md) sets up a network of Pantheon nodes in Docker containers. |
||||
@ -1,97 +0,0 @@ |
||||
description: Run Pantheon using the official docker image |
||||
<!--- END of page meta data --> |
||||
|
||||
# Running Pantheon from Docker Image |
||||
|
||||
A Docker image is provided to run a Pantheon node in a Docker container. |
||||
|
||||
Use this Docker image to run a single Pantheon node without installing Pantheon. |
||||
|
||||
## Prerequisites |
||||
|
||||
* [Docker](https://docs.docker.com/install/) |
||||
|
||||
* MacOS or Linux |
||||
|
||||
!!! important |
||||
The Docker image does not run on Windows. |
||||
|
||||
## Quickstart |
||||
|
||||
To run a Pantheon node in a container connected to the Ethereum mainnet: |
||||
|
||||
```bash tab="latest" |
||||
docker run pegasyseng/pantheon:latest |
||||
``` |
||||
|
||||
```bash tab="{{ versions.pantheon_stable }}" |
||||
docker run pegasyseng/pantheon:{{ versions.pantheon_stable }} |
||||
``` |
||||
|
||||
!!! note |
||||
`latest` runs the latest cached version. To pull the latest version, use `docker pull pegasyseng/pantheon:latest`. |
||||
|
||||
## Exposing Ports |
||||
|
||||
Expose ports for P2P peer discovery, GraphQL, metrics, and HTTP and WebSockets JSON-RPC. Exposing the ports is required to use the |
||||
default ports or the ports specified using [`--rpc-http-port`](../Reference/Pantheon-CLI-Syntax.md#rpc-http-port), |
||||
[`--p2p-port`](../Reference/Pantheon-CLI-Syntax.md#p2p-port), [`--rpc-ws-port`](../Reference/Pantheon-CLI-Syntax.md#rpc-ws-port), |
||||
[`--metrics-port`](../Reference/Pantheon-CLI-Syntax.md#metrics-port), [`--graphql-http-port`](../Reference/Pantheon-CLI-Syntax.md#graphql-http-port), |
||||
and [`--metrics-push-port`](../Reference/Pantheon-CLI-Syntax.md#metrics-push-port) options. |
||||
|
||||
To run Pantheon exposing local ports for access: |
||||
```bash |
||||
docker run -p <localportJSON-RPC>:8545 -p <localportWS>:8546 -p <localportP2P>:30303 pegasyseng/pantheon:latest --rpc-http-enabled --rpc-ws-enabled |
||||
``` |
||||
|
||||
!!!example |
||||
To enable RPC calls to http://127.0.0.1:8545 and P2P discovery on http://127.0.0.1:13001: |
||||
```bash |
||||
docker run -p 8545:8545 -p 13001:30303 pegasyseng/pantheon:latest --rpc-http-enabled |
||||
``` |
||||
|
||||
## Starting Pantheon |
||||
|
||||
!!! important |
||||
Do not mount a volume at the default data path (`/opt/pantheon`). Mounting a volume at the default |
||||
data path interferes with the operation of Pantheon and prevents Pantheon from safely launching. |
||||
|
||||
To run a node that maintains the node state (key and database), [`--data-path` must be set to a location |
||||
other than `/opt/pantheon` and a storage volume mounted at that location]. |
||||
|
||||
### Run a Node for Testing |
||||
|
||||
To run a node that mines blocks at a rate suitable for testing purposes with WebSockets enabled: |
||||
```bash |
||||
docker run -p 8546:8546 --mount type=bind,source=/<myvolume/pantheon/testnode>,target=/var/lib/pantheon pegasyseng/pantheon:latest --miner-enabled --miner-coinbase fe3b557e8fb62b89f4916b721be55ceb828dbd73 --rpc-ws-enabled --network=dev --data-path=/var/lib/pantheon |
||||
``` |
||||
|
||||
### Run a Node on Rinkeby Testnet |
||||
|
||||
To run a node on Rinkeby: |
||||
```bash |
||||
docker run -p 30303:30303 --mount type=bind,source=/<myvolume/pantheon/rinkeby>,target=/var/lib/pantheon pegasyseng/pantheon:latest --network=rinkeby --data-path=/var/lib/pantheon |
||||
``` |
||||
|
||||
### Run a Node on Ethereum Mainnet |
||||
|
||||
To run a node on Ethereum mainnet with the HTTP JSON-RPC service enabled: |
||||
```bash |
||||
docker run -p 8545:8545 --mount type=bind,source=/<myvolume/pantheon/rinkeby>,target=/var/lib/pantheon -p 30303:30303 pegasyseng/pantheon:latest --rpc-http-enabled --data-path=/var/lib/pantheon |
||||
``` |
||||
|
||||
## Stopping Pantheon and Cleaning up Resources |
||||
|
||||
When you're done running nodes, you can shut down the node container without deleting resources or |
||||
you can delete the container after stopping it. Run `docker container ls` and `docker volume ls` to |
||||
obtain the container and volume names. |
||||
|
||||
To stop a container: |
||||
```bash |
||||
docker stop <container-name> |
||||
``` |
||||
|
||||
To delete a container: |
||||
```bash |
||||
docker rm <container-name> |
||||
``` |
||||
@ -1,133 +0,0 @@ |
||||
description: Starting Pantheon |
||||
<!--- END of page meta data --> |
||||
|
||||
# Starting Pantheon |
||||
|
||||
Pantheon nodes can be used for varying purposes as described in the [Overview](../index.md). |
||||
Nodes can connect to the Ethereum mainnet, public testnets such as Ropsten, or private networks. |
||||
|
||||
## Prerequisites |
||||
|
||||
[Pantheon Installed](../Installation/Overview.md) |
||||
|
||||
## Local Block Data |
||||
|
||||
When connecting to a network other than the network previously connected to, you must either delete the local block data |
||||
or use the [`--data-path`](../Reference/Pantheon-CLI-Syntax.md#data-path) option to specify a different data directory. |
||||
|
||||
To delete the local block data, delete the `database` directory in the `pantheon/build/distribution/pantheon-<version>` directory. |
||||
|
||||
## Genesis Configuration |
||||
|
||||
Pantheon specifies the genesis configuration, and sets the network ID and bootnodes when connecting |
||||
to [Mainnet](#run-a-node-on-ethereum-mainnet), [Goerli](#run-a-node-on-goerli-testnet), [Rinkeby](#run-a-node-on-rinkeby-testnet), and [Ropsten](#run-a-node-on-ropsten-testnet). |
||||
|
||||
When [`--network=dev`](../Reference/Pantheon-CLI-Syntax.md#network) is specified, Pantheon uses the |
||||
development mode genesis configuration with a fixed low difficulty. |
||||
A node started with [`--network=dev`](../Reference/Pantheon-CLI-Syntax.md#network) has an empty bootnodes list by default. |
||||
|
||||
The genesis files defining the genesis configurations are in the [Pantheon source files](https://github.com/PegaSysEng/pantheon/tree/master/config/src/main/resources). |
||||
|
||||
To define a genesis configuration, create a genesis file (for example, `genesis.json`) and specify the file |
||||
using the [`--genesis-file`](../Reference/Pantheon-CLI-Syntax.md#genesis-file) option. |
||||
|
||||
## Confirm Node is Running |
||||
|
||||
If you have started Pantheon with the [`--rpc-http-enabled`](../Reference/Pantheon-CLI-Syntax.md#rpc-http-enabled) option, use [cURL](https://curl.haxx.se/) to |
||||
call [JSON-RPC API methods](../Reference/Pantheon-API-Methods.md) to confirm the node is running. |
||||
|
||||
!!!example |
||||
|
||||
* `eth_chainId` returns the chain ID of the network. |
||||
|
||||
```bash |
||||
curl -X POST --data '{"jsonrpc":"2.0","method":"eth_chainId","params":[],"id":1}' localhost:8545 |
||||
``` |
||||
|
||||
* `eth_syncing` returns the starting, current, and highest block. |
||||
|
||||
```bash |
||||
curl -X POST --data '{"jsonrpc":"2.0","method":"eth_syncing","params":[],"id":1}' localhost:8545 |
||||
``` |
||||
|
||||
For example, after connecting to mainnet `eth_syncing` will return something similar to: |
||||
|
||||
```json |
||||
{ |
||||
"jsonrpc" : "2.0", |
||||
"id" : 1, |
||||
"result" : { |
||||
"startingBlock" : "0x0", |
||||
"currentBlock" : "0x2d0", |
||||
"highestBlock" : "0x66c0" |
||||
} |
||||
} |
||||
``` |
||||
|
||||
## Run a Node for Testing |
||||
|
||||
To run a node that mines blocks at a rate suitable for testing purposes: |
||||
|
||||
```bash |
||||
pantheon --network=dev --miner-enabled --miner-coinbase=0xfe3b557e8fb62b89f4916b721be55ceb828dbd73 --rpc-http-cors-origins="all" --host-whitelist="*" --rpc-ws-enabled --rpc-http-enabled --data-path=/tmp/tmpDatdir |
||||
``` |
||||
|
||||
Alternatively, use the following [configuration file](../Configuring-Pantheon/Using-Configuration-File.md) |
||||
on the command line to start a node with the same options as above: |
||||
```toml |
||||
network="dev" |
||||
miner-enabled=true |
||||
miner-coinbase="0xfe3b557e8fb62b89f4916b721be55ceb828dbd73" |
||||
rpc-http-cors-origins=["all"] |
||||
host-whitelist=["*"] |
||||
rpc-ws-enabled=true |
||||
rpc-http-enabled=true |
||||
data-path="/tmp/tmpdata-path" |
||||
``` |
||||
|
||||
## Run a Node on Ropsten Testnet |
||||
|
||||
To run a node on Ropsten: |
||||
|
||||
```bash |
||||
pantheon --network=ropsten |
||||
``` |
||||
|
||||
To run a node on Ropsten with the HTTP JSON-RPC service enabled and allow Remix to access the node: |
||||
|
||||
```bash |
||||
pantheon --network=ropsten --rpc-http-enabled --rpc-http-cors-origins "http://remix.ethereum.org" |
||||
``` |
||||
|
||||
## Run a Node on Rinkeby Testnet |
||||
|
||||
To run a node on Rinkeby specifying a data directory: |
||||
|
||||
```bash |
||||
pantheon --network=rinkeby --data-path=<path>/<rinkebydata-path> |
||||
``` |
||||
Where `<path>` and `<rinkebydata-path>` are the path and directory where the Rinkeby chain data is to be saved. |
||||
|
||||
## Run a Node on Goerli Testnet |
||||
|
||||
To run a node on [Goerli](https://github.com/goerli/testnet) specifying a data directory: |
||||
|
||||
```bash |
||||
pantheon --network=goerli --data-path=<path>/<goerlidata-path> |
||||
``` |
||||
|
||||
Where `<path>` and `<goerlidata-path>` are the path and directory where the Goerli chain data is to be saved. |
||||
|
||||
## Run a Node on Ethereum Mainnet |
||||
|
||||
To run a node on the Ethereum mainnet: |
||||
|
||||
```bash |
||||
pantheon |
||||
``` |
||||
|
||||
To run a node on mainnet with the HTTP JSON-RPC service enabled and available for localhost only: |
||||
|
||||
```bash |
||||
pantheon --rpc-http-enabled |
||||
``` |
||||
@ -1,18 +0,0 @@ |
||||
# Getting Started with Pantheon |
||||
|
||||
After you download and unpackage Pantheon, display the command line help to confirm installation: |
||||
|
||||
1. At the command line, change into the `pantheon-<release>` directory. |
||||
|
||||
2. To display the command line help: |
||||
``` |
||||
./bin/pantheon --help |
||||
``` |
||||
|
||||
[Starting Pantheon](https://docs.pantheon.pegasys.tech/en/stable/Getting-Started/Starting-Pantheon/) includes |
||||
command line examples for connecting to MainNet, public testnets, and running a node for testing. |
||||
|
||||
Pantheon documentation is on the [Pantheon documentation site](https://docs.pantheon.pegasys.tech/en/stable/). |
||||
|
||||
!!! note |
||||
Starting Pantheon by double-clicking the `pantheon` or `pantheon.bat` executables starts a node synchronizing with the Ethereum mainnet. |
||||
@ -1,137 +0,0 @@ |
||||
description: Building Pantheon from source code |
||||
<!--- END of page meta data --> |
||||
|
||||
# Build from Source |
||||
|
||||
## Prerequisites |
||||
|
||||
* [Java JDK](http://www.oracle.com/technetwork/java/javase/downloads/index.html) |
||||
|
||||
!!!important |
||||
Pantheon requires Java 11+ to compile; earlier versions are not supported. |
||||
|
||||
* [Git](https://git-scm.com/downloads) or [GitHub Desktop](https://desktop.github.com/) |
||||
|
||||
## Running Locally |
||||
|
||||
* [Installation on Linux / Unix / Mac OS X](#installation-on-linux-unix-mac-os-x) |
||||
* [Installation on Windows](#installation-on-windows) |
||||
|
||||
## Running On Virtual Machine |
||||
|
||||
* [Installation on VM](#installation-on-vm) |
||||
|
||||
|
||||
## Installation on Linux / Unix / Mac OS X |
||||
|
||||
###Clone the Pantheon Repository |
||||
|
||||
Clone the **PegaSysEng/pantheon** repo to your home directory (`/home/<user>`): |
||||
|
||||
```bash |
||||
git clone --recursive https://github.com/PegaSysEng/pantheon.git |
||||
``` |
||||
|
||||
### Build Pantheon |
||||
|
||||
After cloning, go to the `pantheon` directory. |
||||
|
||||
Build Pantheon with the Gradle wrapper `gradlew`, omitting tests as follows: |
||||
|
||||
```bash |
||||
./gradlew build -x test |
||||
``` |
||||
|
||||
Go to the distribution directory: |
||||
```bash |
||||
cd build/distributions/ |
||||
``` |
||||
|
||||
Expand the distribution archive: |
||||
```bash |
||||
tar -xzf pantheon-<version>.tar.gz |
||||
``` |
||||
|
||||
Move to the expanded folder and display the Pantheon help to confirm installation. |
||||
````bash |
||||
cd pantheon-<version>/ |
||||
bin/pantheon --help |
||||
```` |
||||
|
||||
!!! note "Linux Open File Limit" |
||||
If synchronizing to MainNet on Linux or other chains with large data requirements, increase the maximum number |
||||
of open files allowed using `ulimit`. If the open files limit is not high enough, a `Too many open files` RocksDB exception occurs. |
||||
|
||||
Continue with [Starting Pantheon](../Getting-Started/Starting-Pantheon.md). |
||||
|
||||
|
||||
## Installation on Windows |
||||
|
||||
!!!note |
||||
Pantheon is currently supported only on 64-bit versions of Windows, and requires a 64-bit version of JDK/JRE. |
||||
We recommend that you also remove any 32-bit JDK/JRE installations. |
||||
|
||||
### Install Pantheon |
||||
|
||||
In Git bash, go to your working directory for repositories. Clone the `PegaSysEng/pantheon` repo into this directory: |
||||
|
||||
```bat |
||||
git clone --recursive https://github.com/PegaSysEng/pantheon |
||||
``` |
||||
|
||||
### Build Pantheon |
||||
|
||||
Go to the `pantheon` directory: |
||||
|
||||
```bat |
||||
cd pantheon |
||||
``` |
||||
|
||||
Open a Windows command prompt. Build Pantheon with the Gradle wrapper `gradlew`, omitting tests as follows: |
||||
|
||||
```bat |
||||
.\gradlew build -x test |
||||
``` |
||||
|
||||
!!!note |
||||
To run `gradlew`, you must have the **JAVA_HOME** system variable set to the Java installation directory. |
||||
For example: `JAVA_HOME = C:\Program Files\Java\jdk1.8.0_181`. |
||||
|
||||
Go to the distribution directory: |
||||
```bat |
||||
cd build\distributions |
||||
``` |
||||
|
||||
Expand the distribution archive: |
||||
```bat |
||||
tar -xzf pantheon-<version>.tar.gz |
||||
``` |
||||
|
||||
Move to the expanded folder and display the Pantheon help to confirm installation. |
||||
```bat |
||||
cd pantheon-<version> |
||||
bin\pantheon --help |
||||
``` |
||||
|
||||
Continue with [Starting Pantheon](../Getting-Started/Starting-Pantheon.md). |
||||
|
||||
|
||||
## 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](https://www.virtualbox.org/). |
||||
|
||||
If you set up your own VM locally using a VM manager such as [VirtualBox](https://www.virtualbox.org/), 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](https://linus.nci.nih.gov/bdge/installUbuntu.html). |
||||
@ -1,57 +0,0 @@ |
||||
description: Install Pantheon from binary distribution |
||||
<!--- END of page meta data --> |
||||
|
||||
# Install Binary Distribution |
||||
|
||||
## Mac OS with Homebrew |
||||
|
||||
### Prerequisites |
||||
|
||||
* [Homebrew](https://brew.sh/) |
||||
* Java JDK |
||||
|
||||
!!!attention |
||||
Pantheon requires Java 11+ to compile; earlier versions are not supported. You can install Java using `brew cask install adoptopenjdk`. Alternatively, you can manually install the [Java JDK](http://www.oracle.com/technetwork/java/javase/downloads/index.html). |
||||
|
||||
### Install Using Homebrew |
||||
|
||||
```bash |
||||
brew tap pegasyseng/pantheon |
||||
brew install pantheon |
||||
``` |
||||
Display Pantheon command line help to confirm installation: |
||||
|
||||
```bash |
||||
pantheon --help |
||||
``` |
||||
|
||||
## Linux / Unix / Windows |
||||
|
||||
### Prerequisites |
||||
|
||||
* [Java JDK](http://www.oracle.com/technetwork/java/javase/downloads/index.html) |
||||
|
||||
!!!attention |
||||
Pantheon requires Java 11+ to compile; earlier versions are not supported. |
||||
Pantheon is currently supported only on 64-bit versions of Windows, and requires a 64-bit version of JDK/JRE. |
||||
We recommend that you also remove any 32-bit JDK/JRE installations. |
||||
|
||||
!!! note "Linux Open File Limit" |
||||
If synchronizing to MainNet on Linux or other chains with large data requirements, increase the maximum |
||||
number of open files allowed using `ulimit`. If the open files limit is not high enough, a `Too many open files` RocksDB exception occurs. |
||||
|
||||
### Install from Packaged Binaries |
||||
|
||||
Download the Pantheon [packaged binaries](https://bintray.com/consensys/pegasys-repo/pantheon/_latestVersion#files). |
||||
|
||||
Unpack the downloaded files and change into the `pantheon-<release>` directory. |
||||
|
||||
Display Pantheon command line help to confirm installation: |
||||
|
||||
```bash tab="Linux/macOS" |
||||
bin/pantheon --help |
||||
``` |
||||
|
||||
```bat tab="Windows" |
||||
bin\pantheon --help |
||||
``` |
||||
@ -1,15 +0,0 @@ |
||||
title: Installation overview |
||||
description: Overview and requirements to install Pantheon |
||||
<!--- END of page meta data --> |
||||
|
||||
# Installation Overview |
||||
|
||||
You can install Pantheon by: |
||||
|
||||
* [Installing the binary distribution](Install-Binaries.md) |
||||
* [Building from source](Build-From-Source.md) |
||||
|
||||
!!! note |
||||
To run a single node to connect the Ethereum mainnet or a public testnet, running from the [Pantheon docker image](../Getting-Started/Run-Docker-Image.md) is the fastest way to get started. |
||||
|
||||
|
||||
@ -1,29 +0,0 @@ |
||||
title: System Requirements |
||||
description: System requirements to sync and run Pantheon |
||||
<!--- END of page meta data --> |
||||
|
||||
# System Requirements |
||||
|
||||
The system requirements for Pantheon depend on a number of factors: |
||||
|
||||
* Size of the world state for the network |
||||
* Number of transactions submitted to network |
||||
* Block gas limit |
||||
* Number and complexity of [JSON-RPC](../Pantheon-API/Using-JSON-RPC-API.md), [PubSub](../Pantheon-API/RPC-PubSub.md), |
||||
or [GraphQL](../Pantheon-API/GraphQL.md) queries being handled by the node |
||||
|
||||
## Determining System Requirements |
||||
|
||||
To determine system requirements, monitor CPU and disk space requirements using [Prometheus](https://docs.pantheon.pegasys.tech/en/stable/Monitoring/Monitoring-Performance/#monitor-node-performance-using-prometheus). |
||||
A sample [Grafana dashboard](https://grafana.com/grafana/dashboards/10273) is provided for Pantheon. |
||||
|
||||
!!! tip |
||||
CPU requirements are highest when syncing to the network and typically reduce once the node is synchronized to the chain head. |
||||
|
||||
## RAM |
||||
|
||||
Pantheon requires 4GB of RAM. For Ethereum Mainnet, a minimum of 8GB of RAM is required |
||||
|
||||
## Disk Space |
||||
|
||||
Syncing to the Ethereum mainnet requires 3TB for a full sync. |
||||
@ -1,106 +0,0 @@ |
||||
description: Ethereum Lite Explorer |
||||
<!--- END of page meta data --> |
||||
|
||||
# Alethio Ethereum Lite Explorer |
||||
|
||||
Use the [Alethio Ethereum Lite Explorer](https://lite-explorer.aleth.io/) to explore blockchain data |
||||
at the block, transaction, and account level. |
||||
|
||||
The Alethio Ethereum Lite Explorer is a web application that connects to any Ethereum |
||||
JSON-RPC enabled node. No online server, hosting, or trusting third parties to display the blockchain |
||||
data is required. |
||||
|
||||
!!! note |
||||
The Alethio Ethereum Lite Explorer is an [Alethio product](https://company.aleth.io/developers). |
||||
|
||||
## Prerequisites |
||||
|
||||
[Docker](https://docs.docker.com/install/) or [Node.js](https://nodejs.org/) |
||||
|
||||
!!! tip |
||||
Using Docker is the easiest way to get started using the Ethereum Lite Explorer with Pantheon if you |
||||
do not have Node.js installed. |
||||
|
||||
## Run Using Docker |
||||
|
||||
To run the Ethereum Lite Explorer using the Docker image: |
||||
|
||||
1. Start Pantheon with the [`--rpc-http-enabled`](../../Reference/Pantheon-CLI-Syntax.md#rpc-http-enabled) option. |
||||
|
||||
!!! example |
||||
|
||||
To run Pantheon in development mode: |
||||
|
||||
```bash |
||||
pantheon --network=dev --miner-enabled --miner-coinbase=0xfe3b557e8fb62b89f4916b721be55ceb828dbd73 --rpc-http-cors-origins="all" --host-whitelist="*" --rpc-http-enabled --data-path=/tmp/tmpDatdir |
||||
``` |
||||
|
||||
1. Run the `alethio/ethereum-lite-explorer` Docker image specifying the JSON-RPC HTTP URL (`http://localhost:8545` in this example): |
||||
|
||||
```bash |
||||
docker run --rm -p 8080:80 -e APP_NODE_URL=http://localhost:8545 alethio/ethereum-lite-explorer |
||||
``` |
||||
|
||||
1. Open [http://localhost:8080](http://localhost:8080) in your browser to view the Lite Explorer. |
||||
|
||||
 |
||||
|
||||
!!! note "Default HTTP port" |
||||
We are using port 8080 to run the Ethereum Lite Explorer so |
||||
the [EthStats Lite](Lite-Network-Monitor.md) can use port 80. You can then run |
||||
both at the same time. |
||||
|
||||
## Install and Run with Node.js |
||||
|
||||
1. Clone the `ethereum-lite-explorer` repository: |
||||
|
||||
```bash |
||||
git clone https://github.com/Alethio/ethereum-lite-explorer.git |
||||
``` |
||||
|
||||
1. Change into the `ethereum-lite-explorer` directory: |
||||
```bash |
||||
cd ethereum-lite-explorer |
||||
``` |
||||
|
||||
1. Install npm packages: |
||||
|
||||
```bash |
||||
npm install |
||||
``` |
||||
|
||||
1. Copy the sample config: |
||||
|
||||
```bash |
||||
cp config.default.json config.dev.json |
||||
``` |
||||
|
||||
1. Update the `config.dev.json` file: |
||||
|
||||
* Set `APP_NODE_URL` to the JSON-RPC HTTP URL of your node (`http://localhost:8545` in this example) |
||||
|
||||
* Remove other environment variables. |
||||
|
||||
1. In another terminal, start Pantheon with the [`--rpc-http-enabled`](../../Reference/Pantheon-CLI-Syntax.md#rpc-http-enabled) option. |
||||
|
||||
!!! example |
||||
|
||||
To run Pantheon in development mode: |
||||
|
||||
```bash |
||||
pantheon --network=dev --miner-enabled --miner-coinbase=0xfe3b557e8fb62b89f4916b721be55ceb828dbd73 --rpc-http-cors-origins="all" --host-whitelist="*" --rpc-http-enabled --data-path=/tmp/tmpDatdir |
||||
``` |
||||
|
||||
1. In the `ethereum-lite-explorer` directory, run the Lite Explorer in development mode: |
||||
|
||||
```bash |
||||
npm run build |
||||
npm run start |
||||
``` |
||||
|
||||
1. A browser window displays the Ethereum Lite Explorer (http://localhost:3000/). |
||||
|
||||
## Lite Block Explorer Documentation |
||||
|
||||
See the Ethereum Lite Explorer [GitHub repository](https://github.com/Alethio/ethereum-lite-explorer) |
||||
for more documentation, including details on deploying it. |
||||
@ -1,169 +0,0 @@ |
||||
description: Alethio EthStats Lite network monitor |
||||
<!--- END of page meta data --> |
||||
|
||||
# Alethio EthStats Lite (network monitor) |
||||
|
||||
Use [EthStats Lite](https://github.com/Alethio?utf8=%E2%9C%93&q=ethstats&type=&language=javascript) |
||||
to have a live view of private network health by displaying real time and historical statistics |
||||
about the network and nodes. |
||||
|
||||
EthStats Lite supports in-memory persistence or using Redis to persist a fixed number of blocks |
||||
(by default, 3000). |
||||
|
||||
You can also use a full online version of EthStats for the [Ethereum MainNet](https://ethstats.io). |
||||
|
||||
!!! note |
||||
The EthStats Lite is an [Alethio product](https://company.aleth.io/developers). |
||||
|
||||
!!! tip |
||||
Static local ports 80 and 3000 are used in the example [running EthStats Lite |
||||
for a Pantheon Node](#running-ethstats-lite-for-a-pantheon-node). |
||||
|
||||
## Statistics |
||||
|
||||
Statistics displayed by EthStats Lite include: |
||||
|
||||
* Nodes in the network. Metrics for nodes include: |
||||
- Information about the last received block such as block number, |
||||
block hash, transaction count, uncle count, block time and propagation time |
||||
- Connected peers, whether the node is mining, hash rate, latency, and uptime |
||||
* Charts for Block Time, Block Difficulty, Block Gas Limit, Block Uncles, Block Transactions, Block Gas Used, |
||||
Block Propagation Histogram, and Top Miners |
||||
* IP based geolocation overview |
||||
* Node logs. Node logs display the data sent by a node |
||||
* Block history. Block history provides the ability to go back in time and playback the block propagation |
||||
through the nodes |
||||
|
||||
## Components |
||||
|
||||
EthStats Lite consists of: |
||||
|
||||
* [Server](https://github.com/Alethio/ethstats-network-server). Consumes node data received from the |
||||
client. |
||||
|
||||
* [Client](https://github.com/Alethio/ethstats-cli). A client must be started for each node in the network. |
||||
The client extracts data from the node and sends it to the server |
||||
|
||||
* [Dashboard](https://github.com/Alethio/ethstats-network-dashboard). Dashboard displaying [statistics](#statistics). |
||||
|
||||
## Pre-requisities |
||||
|
||||
[Docker](https://docs.docker.com/install/) |
||||
|
||||
!!! tip |
||||
EthStats Lite has a number of dependencies. Using Docker is the easiest way to |
||||
use EthStats Lite with Pantheon. |
||||
|
||||
The [EthStats CLI](https://github.com/Alethio/ethstats-cli), |
||||
[EthStats Network Server](https://github.com/Alethio/ethstats-network-server), and [EthStats Network |
||||
Dashboard](https://github.com/Alethio/ethstats-network-dashboard) documentation describes how to |
||||
install EthStats Lite tools. |
||||
|
||||
## Running EthStats Lite for a Pantheon Node |
||||
|
||||
!!! important |
||||
This example describes how to run EthStats Lite for a single Pantheon node. |
||||
To run EthStats Lite for a network of nodes, a [client](#3-client) must be started for each node. |
||||
|
||||
### 1. Server |
||||
|
||||
Start the EthStats Lite server using in-memory persistence: |
||||
|
||||
1. Clone the server repository: |
||||
|
||||
```bash |
||||
git clone https://github.com/Alethio/ethstats-network-server.git |
||||
``` |
||||
|
||||
1. Change into the `/ethstats-network-server/docker/lite-mode/memory-persistence` directory: |
||||
|
||||
```bash |
||||
cd ethstats-network-server/docker/lite-mode/memory-persistence |
||||
``` |
||||
|
||||
1. Update the `docker-compose.yml` file to your Pantheon [network ID](../../Configuring-Pantheon/NetworkID-And-ChainID.md): |
||||
|
||||
```yaml |
||||
- NETWORK_ID=2018 |
||||
- NETWORK_NAME=mynetwork |
||||
``` |
||||
|
||||
In this example we are using the `dev` Pantheon network with a network ID of `2018`. |
||||
|
||||
1. Start the server using Docker compose: |
||||
|
||||
```bash |
||||
docker-compose up -d |
||||
``` |
||||
|
||||
!!! tip |
||||
A `docker-compose` file is provided in the `ethstats-network-server/docker/lite-mode/redis-persistence` |
||||
directory to run the server using Redis to persist a fixed number of blocks (default is 3000). |
||||
|
||||
### 2. Pantheon |
||||
|
||||
Start Pantheon in development mode with WebSockets enabled: |
||||
|
||||
```bash |
||||
docker run --rm -p 8546:8546 pegasyseng/pantheon:latest --miner-enabled --miner-coinbase fe3b557e8fb62b89f4916b721be55ceb828dbd73 --rpc-http-cors-origins="all" --rpc-ws-enabled --network=dev |
||||
``` |
||||
|
||||
Where `<pantheondata-path>` is the volume to which the node data is saved. |
||||
|
||||
### 3. Client |
||||
|
||||
Start the client for the Pantheon node: |
||||
|
||||
```bash |
||||
docker run -d --rm --name ethstats-client --net host alethio/ethstats-cli --register --account-email <email> --node-name <node_name> --server-url http://localhost:3000 --client-url ws://127.0.0.1:8546 |
||||
``` |
||||
|
||||
Where: |
||||
|
||||
* `--server-url` specifies [your server](#1-server). The default is the server that consumes data for the Ethereum MainNet. |
||||
* `--register` specifies the registration of the Pantheon node is done automatically with the specified `<email>` and `<node_name>`. |
||||
Registering the node is only required the first time the client is started for the node. |
||||
* `--client-url` specifies the WebSockets URL for the Pantheon node. |
||||
|
||||
### 4. Dashboard |
||||
|
||||
To display EthStats Lite dashboard, open [http://localhost](http://localhost) in your browser. |
||||
|
||||
 |
||||
|
||||
!!! note "Default HTTP port" |
||||
We are using the default HTTP port (80) to run EthStats Lite. The [Lite Block Explorer](Lite-Block-Explorer.md) |
||||
example uses port 8080. You can then run both at the same time. |
||||
|
||||
To change the port, update the `docker-compose.yml` file: |
||||
```yaml |
||||
ports: |
||||
- 127.0.0.1:80:80 |
||||
``` |
||||
|
||||
Update the first 80 to the required port: |
||||
```yaml |
||||
ports: |
||||
- 127.0.0.1:8081:80 |
||||
``` |
||||
|
||||
### Stopping and Cleaning Up Resources |
||||
|
||||
When you've finished running EthStats Lite: |
||||
|
||||
1. Stop Pantheon using ++ctrl+c++. |
||||
|
||||
1. Stop EthStats Lite server and remove containers and volumes: |
||||
|
||||
```bash |
||||
docker-compose down -v |
||||
``` |
||||
|
||||
1. Stop EthStats Lite client: |
||||
|
||||
```bash |
||||
docker stop ethstats-client |
||||
``` |
||||
|
||||
!!! tip |
||||
The client container is automatically removed because we used the `--rm` option. |
||||
@ -1,17 +0,0 @@ |
||||
description: Alethio Lite Block Explorer And EthStats Lite Network Monitor Overview |
||||
<!--- END of page meta data --> |
||||
|
||||
# Alethio |
||||
|
||||
Alethio offers a set of tools including the [Block Explorer](https://aleth.io/) and |
||||
[EthStats Network Monitor](https://ethstats.io/). The Alethio tools are developed by [Alethio](https://company.aleth.io/). |
||||
|
||||
The Block Explorer and EthStats provide a comprehensive view into the activity in a |
||||
public or private Enterprise Ethereum network. The statistics are at the network level |
||||
and the block, transaction, and account level. |
||||
|
||||
To use the Block Explorer and EthStats for testing and private networks, run the the [Lite Block |
||||
Explorer](Lite-Block-Explorer.md) and [EthStats Lite](Lite-Network-Monitor.md). |
||||
|
||||
Contact [Alethio](https://company.aleth.io/) at [contact@aleth.io](mailto:contact@aleth.io) for |
||||
details about the full versions and enterprise solutions. |
||||
|
Before Width: | Height: | Size: 830 KiB |
|
Before Width: | Height: | Size: 559 KiB |
@ -1,67 +0,0 @@ |
||||
description: Pantheon log level setting and log formatting |
||||
path: blob/master/pantheon/src/main/resources/ |
||||
source: log4j2.xml |
||||
<!--- END of page meta data --> |
||||
|
||||
# Logging |
||||
|
||||
Pantheon uses Log4J2 for logging. There are two methods to configure logging behavior: |
||||
|
||||
* Basic - changes the log level. |
||||
* Advanced - configures the output and format of the logs. |
||||
|
||||
!!!note |
||||
For most use-cases, the basic method provides sufficient configurability. |
||||
|
||||
## Basic Log Level Setting |
||||
|
||||
Use the [`--logging`](../Reference/Pantheon-CLI-Syntax.md#logging) command line option to specify |
||||
the logging verbosity. The [`--logging`](../Reference/Pantheon-CLI-Syntax.md#logging) option changes |
||||
the volume of events displayed in the log. |
||||
|
||||
!!! tip |
||||
Use the [`admin_changeLogLevel`](../Reference/Pantheon-API-Methods.md#admin_changeloglevel) API method |
||||
to change the log level while Pantheon is running. |
||||
|
||||
## Advanced Custom Logging |
||||
|
||||
You can provide your own logging configuration using the standard Log4J2 configuration mechanisms. |
||||
For example, the following Log4J2 configuration is the same as the |
||||
[default configuration](https://github.com/PegaSysEng/pantheon/blob/master/pantheon/src/main/resources/log4j2.xml) |
||||
except logging of stack traces for exceptions is excluded. |
||||
|
||||
```xml tab="debug.xml" |
||||
<?xml version="1.0" encoding="UTF-8"?> |
||||
<Configuration status="INFO"> |
||||
<Properties> |
||||
<Property name="root.log.level">INFO</Property> |
||||
</Properties> |
||||
|
||||
<Appenders> |
||||
<Console name="Console" target="SYSTEM_OUT"> |
||||
<PatternLayout pattern="%d{yyyy-MM-dd HH:mm:ss.SSSZZZ} | %t | %-5level | %c{1} | %msg %throwable{short.message}%n" /> |
||||
</Console> |
||||
</Appenders> |
||||
<Loggers> |
||||
<Root level="${sys:root.log.level}"> |
||||
<AppenderRef ref="Console" /> |
||||
</Root> |
||||
</Loggers> |
||||
</Configuration> |
||||
``` |
||||
|
||||
To use your custom configuration, set the environment variable `LOG4J_CONFIGURATION_FILE` to the |
||||
location of your configuration file. |
||||
|
||||
If you have more specific requirements, you can create your own |
||||
[log4j2 configuration](https://logging.apache.org/log4j/2.x/manual/configuration.html). |
||||
|
||||
For Bash-based executions, you can set the variable for only the scope of the program execution by |
||||
setting it before starting Pantheon. |
||||
|
||||
!!!example |
||||
To set the debug logging and start Pantheon connected to the Rinkeby testnet: |
||||
|
||||
```bash |
||||
LOG4J_CONFIGURATION_FILE=./debug.xml pantheon --network=rinkeby |
||||
``` |
||||
@ -1,112 +0,0 @@ |
||||
description: Frequently asked questions FAQ and answers for troubleshooting Pantheon use |
||||
<!--- END of page meta data --> |
||||
|
||||
# Monitoring Pantheon |
||||
|
||||
## Monitor Node Performance and Connectivity Using the JSON-RPC API |
||||
|
||||
You can monitor node performance using the [`debug_metrics`](../Reference/Pantheon-API-Methods.md#debug_metrics) |
||||
JSON-RPC API method. |
||||
|
||||
## Monitor Node Performance Using Prometheus |
||||
|
||||
Use the [`--metrics-enabled` option](../Reference/Pantheon-CLI-Syntax.md#metrics-enabled) to enable the [Prometheus](https://prometheus.io/) monitoring and |
||||
alerting service to access Pantheon metrics. You can also visualize the collected data using [Grafana](https://grafana.com/). |
||||
A sample [Pantheon Grafana dashboard](https://grafana.com/dashboards/10273) is provided. |
||||
|
||||
To specify the host and port on which Prometheus accesses Pantheon, use the [`--metrics-host`](../Reference/Pantheon-CLI-Syntax.md#metrics-host) and |
||||
[`--metrics-port`](../Reference/Pantheon-CLI-Syntax.md#metrics-port) options. |
||||
The default host and port are 127.0.0.1 and 9545. |
||||
|
||||
You can install other Prometheus components such as the Alert Manager. Additional configuration |
||||
is not required for these components because Prometheus handles and analyzes data directly from the feed. |
||||
|
||||
To use Prometheus with Pantheon, install the [prometheus main component](https://prometheus.io/download/). On MacOS, install with [Homebrew](https://formulae.brew.sh/formula/prometheus): |
||||
|
||||
``` |
||||
brew install prometheus |
||||
``` |
||||
|
||||
### Setting up and Running Prometheus with Pantheon |
||||
|
||||
To configure Prometheus and run with Pantheon: |
||||
|
||||
1. Configure Prometheus to poll Pantheon. For example, add the following yaml fragment to the `scrape_configs` |
||||
block of the `prometheus.yml` file: |
||||
|
||||
```yml tab="Example" |
||||
job_name: pantheon-dev |
||||
scrape_interval: 15s |
||||
scrape_timeout: 10s |
||||
metrics_path: /metrics |
||||
scheme: http |
||||
static_configs: |
||||
- targets: |
||||
- localhost:9545 |
||||
``` |
||||
|
||||
1. Start Pantheon with the [`--metrics-enabled` option](../Reference/Pantheon-CLI-Syntax.md#metrics-enabled). To start |
||||
a single node for testing with metrics enabled: |
||||
|
||||
```bash tab="Example" |
||||
pantheon --network=dev --miner-enabled --miner-coinbase fe3b557e8fb62b89f4916b721be55ceb828dbd73 |
||||
--rpc-http-cors-origins="all" --rpc-http-enabled --metrics-enabled |
||||
``` |
||||
|
||||
1. In another terminal, run Prometheus specifying the `prometheus.yml` file: |
||||
|
||||
```bash tab="Example" |
||||
prometheus --config.file=config.yml |
||||
``` |
||||
|
||||
1. Open a web browser to `http://localhost:9090` to view the Prometheus graphical interface. |
||||
|
||||
1. Choose **Graph** from the menu bar and click the **Console** tab below. |
||||
|
||||
1. From the **Insert metric at cursor** drop-down, select a metric such as `pantheon_blockchain_difficulty_total` or |
||||
`pantheon_blockchain_height` and click **Execute**. The values are displayed below. |
||||
|
||||
Click the **Graph** tab to view the data as a time-based graph. The query string is displayed below the graph. |
||||
For example: `{pantheon_blockchain_height{instance="localhost:9545",job="prometheus"}` |
||||
|
||||
### Running Prometheus with Pantheon in Push Mode |
||||
|
||||
The [`--metrics-enabled`](../Reference/Pantheon-CLI-Syntax.md#metrics-enabled) option enables Prometheus polling |
||||
Pantheon but sometimes metrics are hard to poll (for example, when running inside Docker containers with varying IP addresses). |
||||
The [`--metrics-push-enabled`](../Reference/Pantheon-CLI-Syntax.md#metrics-push-enabled) option enables Pantheon |
||||
to push metrics to a [Prometheus Pushgateway](https://github.com/prometheus/pushgateway). |
||||
|
||||
To configure Prometheus and run with Pantheon pushing to a push gateway: |
||||
|
||||
1. Configure Prometheus to read from a push gateway. For example, add the following yaml fragment to the `scrape_configs` |
||||
block of the `prometheus.yml` file: |
||||
|
||||
```yml tab="Example" |
||||
- job_name: push-gateway |
||||
metrics_path: /metrics |
||||
scheme: http |
||||
static_configs: |
||||
- targets: |
||||
- localhost:9091 |
||||
``` |
||||
|
||||
1. Start the push gateway. The push gateway can be deployed using the Docker image: |
||||
|
||||
```bash tab="Example" |
||||
docker pull prom/pushgateway |
||||
docker run -d -p 9091:9091 prom/pushgateway |
||||
``` |
||||
|
||||
1. Start Pantheon specifying the `--metrics-push-enabled` option and port of the push gateway: |
||||
|
||||
```bash tab="Example" |
||||
pantheon --network=dev --miner-enabled --miner-coinbase fe3b557e8fb62b89f4916b721be55ceb828dbd73 --rpc-http-cors-origins="all" --rpc-http-enabled --metrics-push-enabled --metrics-push-port=9091 --metrics-push-host=127.0.0.1 |
||||
``` |
||||
|
||||
1. In another terminal, run Prometheus specifying the `prometheus.yml` file: |
||||
|
||||
```bash tab="Example" |
||||
prometheus --config.file=config.yml |
||||
``` |
||||
|
||||
1. View the Prometheus graphical interface as described in [Setting up and Running Prometheus with Pantheon](#setting-up-and-running-prometheus-with-pantheon). |
||||
@ -1,111 +0,0 @@ |
||||
# Authentication and Authorization for JSON-RPC |
||||
|
||||
Authentication identifies a user based on a username and password. Authorization verifies whether the user has |
||||
access to the JSON-RPC method they are requesting. |
||||
|
||||
Pantheon uses the username and password to authenticate users and [JWT tokens](https://jwt.io/introduction/) to authorize JSON-RPC requests. |
||||
|
||||
!!! important |
||||
To prevent interception of authentication credentials and authenticated tokens, make authenticated requests over HTTPS. |
||||
We recommended production deployments are run behind a network layer that provides SSL termination. |
||||
Pantheon does not provide a HTTPS connection natively. |
||||
|
||||
## Credentials File |
||||
|
||||
The credentials file is a `toml` file defining user details and the JSON-RPC methods to which they have access. |
||||
|
||||
!!! example "Example Credentials File" |
||||
```toml |
||||
[Users.username1] |
||||
password = "$2a$10$l3GA7K8g6rJ/Yv.YFSygCuI9byngpEzxgWS9qEg5emYDZomQW7fGC" |
||||
permissions=["net:*","eth:blockNumber"] |
||||
|
||||
[Users.username2] |
||||
password = "$2b$10$6sHt1J0MVUGIoNKvJiK33uaZzUwNmMmJlaVLkIwinkPiS1UBnAnF2" |
||||
permissions=["net:version","admin:*"] |
||||
``` |
||||
|
||||
Each user requiring JSON-RPC access is listed with: |
||||
|
||||
* Username. `Users.` is mandatory and followed by the username. That is, replace `<username>` in `[Users.<username>]` with the username being defined. |
||||
* Hash of the user password. Use the [`password hash`](../Reference/Pantheon-CLI-Syntax.md#password) subcommand to generate the hash. |
||||
* JSON-RPC permissions. |
||||
|
||||
!!! example "password hash Subcommand" |
||||
```bash |
||||
pantheon password hash --password=pegasys |
||||
``` |
||||
|
||||
## JSON-RPC Permissions |
||||
|
||||
Each user has a list of permissions strings defining the methods they can access. To give access to: |
||||
|
||||
* All API methods, specify `["*:*"]`. |
||||
* All API methods in an API group, specify `["<api_group>:*"]`. For example, `["eth:*"]`. |
||||
* Specific API methods, specify `["<api_group>:<method_name>"]`. For example, `["admin:peers"]`. |
||||
|
||||
If authentication is enabled, to explicitly specify a user cannot access any methods, include the user with an empty permissions list (`[]`). |
||||
Users with an empty permissions list and users not included in the credentials file cannot access any JSON-RPC |
||||
methods. |
||||
|
||||
## Enabling Authentication |
||||
|
||||
Use the [` --rpc-http-authentication-enabled`](../Reference/Pantheon-CLI-Syntax.md#rpc-http-authentication-enabled) or |
||||
[`--rpc-ws-authentication-enabled`](../Reference/Pantheon-CLI-Syntax.md#rpc-ws-authentication-enabled) |
||||
options to require authentication for the JSON-RPC API. |
||||
|
||||
Use the [`--rpc-http-authentication-credentials-file`](../Reference/Pantheon-CLI-Syntax.md#rpc-http-authentication-credentials-file) |
||||
and [`--rpc-ws-authentication-credentials-file`](../Reference/Pantheon-CLI-Syntax.md#rpc-ws-authentication-credentials-file) |
||||
options to specify the [credentials file](#credentials-file). |
||||
|
||||
## Obtaining an Authentication Token |
||||
|
||||
To obtain an authentication token, make a request to the `/login` endpoint with your username and password. Specify the |
||||
HTTP port or the WS port to obtain a token to authenticate over HTTP or WS respectively. A different token is required |
||||
for HTTP and WS. |
||||
|
||||
!!! example |
||||
```bash tab="Obtain Token for HTTP" |
||||
curl -X POST --data '{"username":"username1","password":"pegasys"}' <JSON-RPC-http-hostname:http-port>/login |
||||
``` |
||||
|
||||
```bash tab="Example for HTTP" |
||||
curl -X POST --data '{"username":"username1","password":"pegasys"}' http://localhost:8545/login |
||||
``` |
||||
|
||||
```bash tab="Obtain Token for WS" |
||||
curl -X POST --data '{"username":"username1","password":"pegasys"}' <JSON-RPC-ws-hostname:ws-port>/login |
||||
``` |
||||
|
||||
```bash tab="Example for WS" |
||||
curl -X POST --data '{"username":"username1","password":"pegasys"}' http://localhost:8546/login |
||||
``` |
||||
|
||||
```json tab="JSON result" |
||||
{"token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJwZXJtaXNzaW9ucyI6WyIqOioiXSwidXNlcm5hbWUiOiJ1c2VyMiIsImlhdCI6MTU1MDQ2MDYwNCwiZXhwIjoxNTUwNDYwOTA0fQ.l2Ycqzl_AyvReXBeUSayOlOMS_E8-DCuz3q0Db0DKD7mqyl6q-giWoEtfdWzUEvZbRRi2_ecKO3N6JkXq7zMKQAJbVAEzobfbaaXWcQEpHOjtnK4_Yz-UPyKiXtu7HGdcdl5Tfx3dKoksbqkBl3U3vFWxzmFnuu3dAISfVJYUNA"} |
||||
``` |
||||
|
||||
Authentication tokens expire 5 minutes after being generated. It is necessary to generate a new authentication |
||||
token if access is required after token expiration. |
||||
|
||||
## Using an Authentication Token to Make Requests |
||||
|
||||
Specify the authentication token as a `Bearer` token in the JSON-RPC request header. |
||||
|
||||
### Postman |
||||
|
||||
In the _Authorization_ tab in the _TYPE_ drop-down list, select *Bearer Token* and specify the token |
||||
generated by the [`login` request](#obtaining-an-authentication-token). |
||||
|
||||
### Curl |
||||
|
||||
Specify the `Bearer` in the header. |
||||
|
||||
!!! example |
||||
```bash tab="curl Request with Authentication Placeholders" |
||||
curl -X POST -H 'Authorization: Bearer <JWT_TOKEN>' -d '{"jsonrpc":"2.0","method":"<API_METHOD>","params":[],"id":1}' <JSON-RPC-http-hostname:port> |
||||
``` |
||||
|
||||
```bash tab="curl Request with Authentication" |
||||
curl -X POST -H 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJwZXJtaXNzaW9ucyI6WyIqOioiXSwidXNlcm5hbWUiOiJ1c2VyMiIsImlhdCI6MTU1MDQ2MTQxNiwiZXhwIjoxNTUwNDYxNzE2fQ.WQ1mqpqzRLHaoL8gOSEZPvnRs_qf6j__7A3Sg8vf9RKvWdNTww_vRJF1gjcVy-FFh96AchVnQyXVx0aNUz9O0txt8VN3jqABVWbGMfSk2T_CFdSw5aDjuriCsves9BQpP70Vhj-tseaudg-XU5hCokX0tChbAqd9fB2138zYm5M' -d '{"jsonrpc":"2.0","method":"net_listening","params":[],"id":1}' http://localhost:8545 |
||||
``` |
||||
@ -1,73 +0,0 @@ |
||||
description: How to access the Pantheon API using GraphQL |
||||
<!--- END of page meta data --> |
||||
|
||||
# GraphQL over HTTP |
||||
|
||||
GraphQL can reduce the overhead needed for common queries. For example, instead of querying each receipt in a |
||||
block, GraphQL can obtain the same result with a single query for the entire block. |
||||
|
||||
The GraphQL implementation for Ethereum is described in the [schema](https://github.com/PegaSysEng/pantheon/blob/master/ethereum/graphql/src/main/resources/schema.graphqls). |
||||
The GraphQL service is enabled using the [command line options](../Pantheon-API#enabling-api-access). |
||||
|
||||
!!! note |
||||
GraphQL is not supported over WebSockets. |
||||
|
||||
## GraphQL Requests with Curl |
||||
|
||||
[Pantheon JSON-RPC API methods](../Reference/Pantheon-API-Methods.md) with an equivalent [GraphQL](../Pantheon-API/GraphQL.md) |
||||
query include a GraphQL request and result in the method example. |
||||
|
||||
!!! example |
||||
The following [`syncing`](../Reference/Pantheon-API-Methods.md#eth_syncing) request returns data about the synchronization status. |
||||
```bash |
||||
curl -X POST -H "Content-Type: application/json" --data '{ "query": "{syncing{startingBlock currentBlock highestBlock}}"}' http://localhost:8547/graphql |
||||
``` |
||||
|
||||
## GraphQL Requests with GraphiQL App |
||||
|
||||
The third-party tool [GraphiQL](https://github.com/skevy/graphiql-app) provides a tabbed interface for editing and testing GraphQL |
||||
queries and mutations. GraphiQL also provides access the Pantheon GraphQL schema from within the app. |
||||
|
||||
 |
||||
|
||||
## Pending |
||||
|
||||
The Pending query is supported for `transactionCount` and `transactions`. |
||||
|
||||
!!! important |
||||
Pantheon doesn't execute pending transactions so result from `account`, `call`, and `estimateGas` for Pending |
||||
do not reflect pending transactions. |
||||
|
||||
!!! example |
||||
```bash tab="Pending Transaction Count" |
||||
curl -X POST -H "Content-Type: application/json" --data '{ "query": "{pending {transactionCount}}"}' http://localhost:8547/graphql |
||||
``` |
||||
|
||||
```bash tab="Result" |
||||
{ |
||||
"data" : { |
||||
"pending" : { |
||||
"transactionCount" : 2 |
||||
} |
||||
} |
||||
} |
||||
``` |
||||
|
||||
!!! example |
||||
```bash tab="Pending Transactions" |
||||
curl -X POST -H "Content-Type: application/json" --data '{ "query": "{pending {transactions{hash}}}"}' http://localhost:8547/graphql |
||||
``` |
||||
|
||||
```bash tab="Result" |
||||
{ |
||||
"data" : { |
||||
"pending" : { |
||||
"transactions" : [ { |
||||
"hash" : "0xbb3ab8e2113a4afdde9753782cb0680408c0d5b982572dda117a4c72fafbf3fa" |
||||
}, { |
||||
"hash" : "0xf6bd6b1bccf765024bd482a71c6855428e2903895982090ab5dbb0feda717af6" |
||||
} ] |
||||
} |
||||
} |
||||
} |
||||
``` |
||||
@ -1,17 +0,0 @@ |
||||
description: Pantheon JSON-RPC API reference |
||||
<!--- END of page meta data --> |
||||
|
||||
# JSON-RPC API Overview |
||||
|
||||
The Pantheon JSON-RPC API uses the [JSON-RPC v2.0](https://www.jsonrpc.org/specification) specification of the JSON-RPC protocol. |
||||
|
||||
The [JSON](http://json.org/) (RFC 4627) format which represents |
||||
objects and data fields as collections of name/value pairs, in a 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). The protocol is stateless and transport agnostic in that the concepts |
||||
can be used within the same process, over sockets, over HTTP, or in various message passing environments. |
||||
|
||||
The Reference documentation includes the [JSON-RPC API Methods](../Reference/Pantheon-API-Methods.md) |
||||
and [JSON-RPC API Objects](../Reference/Pantheon-API-Objects.md) |
||||
@ -1,72 +0,0 @@ |
||||
description: Pantheon API |
||||
<!--- END of page meta data --> |
||||
|
||||
Access the [Pantheon API](../Reference/Pantheon-API-Methods.md) using: |
||||
|
||||
* [JSON-RPC over HTTP or WebSockets](Using-JSON-RPC-API.md) |
||||
* [RPC Pub/Sub over WebSockets](RPC-PubSub.md) |
||||
* [GraphQL over HTTP](GraphQL.md) |
||||
|
||||
Information applying to JSON-RPC, RPC Pub/Sub, and GraphQL is included below. |
||||
|
||||
## Enabling API Access |
||||
|
||||
Use the [`--rpc-http-enabled`](../Reference/Pantheon-CLI-Syntax.md#rpc-http-enabled), [`--ws-http-enabled`](../Reference/Pantheon-CLI-Syntax.md#rpc-ws-enabled), |
||||
and [`--graphql-http-enabled`](../Reference/Pantheon-CLI-Syntax.md#graphql-http-enabled) options to enable API access. |
||||
|
||||
## Service Hosts |
||||
|
||||
Use the [`--rpc-http-host`](../Reference/Pantheon-CLI-Syntax.md#rpc-http-host), [`--rpc-ws-host`](../Reference/Pantheon-CLI-Syntax.md#rpc-ws-host), |
||||
and [`--graphql-http-host`](../Reference/Pantheon-CLI-Syntax.md#graphql-http-host) options to specify the host on which the API service listens. |
||||
The default host is 127.0.0.1. |
||||
|
||||
Set the host to `0.0.0.0` to allow remote connections. |
||||
|
||||
!!! caution |
||||
Setting the host to 0.0.0.0 exposes the API service connection on your node to any remote connection. In a |
||||
production environment, ensure you use a firewall to avoid exposing your node to the internet. |
||||
|
||||
## Service Ports |
||||
|
||||
Use the [`--rpc-http-port`](../Reference/Pantheon-CLI-Syntax.md#rpc-http-port), [`--rpc-ws-port`](../Reference/Pantheon-CLI-Syntax.md#rpc-ws-port), |
||||
and [`--graphql-http-port`](../Reference/Pantheon-CLI-Syntax.md#graphql-http-port) options to specify the port on which the API service listens. |
||||
|
||||
The default ports are: |
||||
|
||||
* 8545 for JSON-RPC over HTTP |
||||
* 8546 for JSON-RPC over WebSockets |
||||
* 8547 for GraphQL over HTTP |
||||
|
||||
Ports must be [exposed appropriately](../Configuring-Pantheon/Networking/Managing-Peers.md#port-configuration). |
||||
|
||||
## Host Whitelist |
||||
|
||||
To prevent DNS rebinding, incoming HTTP requests, WebSockets connections, and GraphQL requests are only accepted from hostnames |
||||
specified using the [`--host-whitelist`](../Reference/Pantheon-CLI-Syntax.md#host-whitelist) option. |
||||
By default, `localhost` and `127.0.0.1` are accepted. |
||||
|
||||
If your application publishes RPC ports, specify the hostnames when starting Pantheon. |
||||
|
||||
!!! example |
||||
```bash |
||||
pantheon --host-whitelist=example.com |
||||
``` |
||||
|
||||
Specify "*" for `--host-whitelist` to effectively disable host protection. |
||||
|
||||
!!! caution |
||||
Specifying "*" for `--host-whitelist` is not recommended for production code. |
||||
|
||||
## Not Supported by Pantheon |
||||
|
||||
### Account Management |
||||
|
||||
Account management relies on private key management in the client which is not implemented by Pantheon. |
||||
|
||||
Use [`eth_sendRawTransaction`](../Reference/Pantheon-API-Methods.md#eth_sendrawtransaction) to send signed transactions; `eth_sendTransaction` is not implemented. |
||||
|
||||
Use third-party wallets for [account management](../Using-Pantheon/Account-Management.md). |
||||
|
||||
### Protocols |
||||
|
||||
Pantheon does not implement the Whisper and Swarm protocols. |
||||
@ -1,377 +0,0 @@ |
||||
description: Using RPC Pub/Sub with WebSockets |
||||
<!--- END of page meta data --> |
||||
|
||||
# RPC Pub/Sub over WebSockets |
||||
|
||||
## Introduction |
||||
|
||||
Use RPC Pub/Sub over WebSockets to wait for events instead of polling for them. For example, a Dapp can |
||||
subscribe to logs to be notified when a specific event has occurred. |
||||
|
||||
Methods specific to RPC Pub/Sub are: |
||||
|
||||
* `eth_subscribe` - create a subscription for specific events. |
||||
* `eth_unsubscribe` - cancel a subscription. |
||||
|
||||
!!!important |
||||
Unlike other [Pantheon API methods](../Reference/Pantheon-API-Methods.md), |
||||
the RPC Pub/Sub methods cannot be called over HTTP. Use the [`--rpc-ws-enabled`](../Reference/Pantheon-CLI-Syntax.md#rpc-ws-enabled) option to enable |
||||
the WebSockets JSON-RPC service. |
||||
|
||||
### Using RPC Pub/Sub |
||||
|
||||
The RPC Pub/Sub API is supported on [WebSockets](../Pantheon-API/Using-JSON-RPC-API.md#http-and-websocket-requests). |
||||
|
||||
Use `eth_subscribe` to create subscriptions. Once subscribed, notifications are published by the API using `eth_subscription`. |
||||
|
||||
!!!note |
||||
Notifications are published by `eth_subscription`; you do not need to call `eth_subscription`. |
||||
|
||||
Subscriptions are coupled to a connection. If the connection is closed, all subscriptions created over this connection are removed. |
||||
|
||||
### Subscription ID |
||||
|
||||
`eth_subscribe` returns a subscription ID for each subscription created. Notifications include the subscription ID. |
||||
|
||||
|
||||
!!!example |
||||
For example, to create a synchonizing subscription |
||||
|
||||
```json |
||||
{"id": 1, "method": "eth_subscribe", "params": ["syncing"]} |
||||
``` |
||||
The result includes the subscription ID of `"0x1"`: |
||||
```json |
||||
{"jsonrpc":"2.0","id":1,"result":"0x1"} |
||||
``` |
||||
The notifications also include the subscription ID of `"0x1"`: |
||||
```json |
||||
{"jsonrpc":"2.0","method":"eth_subscription","params":{"subscription":"0x1","result":{"startingBlock":"0x0","currentBlock":"0x50","highestBlock":"0x343c19"}}} |
||||
``` |
||||
|
||||
### Notifications when Synchronizing |
||||
|
||||
Subscribing to some events (for example, logs) can cause a flood of notifications while the node is synchronizing. |
||||
|
||||
## Subscribing |
||||
|
||||
Use `eth_subscribe` to create subscriptions for the following event types: |
||||
|
||||
* [New headers](#new-headers) |
||||
* [Logs](#logs) |
||||
* [Pending transactions](#pending-transactions) |
||||
* [Dropped transactions](#dropped-transactions) |
||||
* [Synchronizng](#synchronizing) |
||||
|
||||
### New Headers |
||||
|
||||
Use the `newHeads` parameter with `eth_subscribe` to be notified each time a block is added to the blockchain. |
||||
|
||||
If a chain reorganization occurs, the subscription publishes notifications for blocks in the new chain. |
||||
This means the subscription can publish notifications for multiple blocks at the same height on the blockchain. |
||||
|
||||
The new headers notification returns [block objects](../Reference/Pantheon-API-Objects.md#block-object). The |
||||
second parameter is optional. If specified, whole [transaction objects](../Reference/Pantheon-API-Objects.md#transaction-object) |
||||
are included in the notifications. Otherwise, the transaction hashes are included. |
||||
|
||||
!!!example |
||||
To subscribe to new header notifications: |
||||
|
||||
```json |
||||
{"id": 1, "method": "eth_subscribe", "params": ["newHeads", {"includeTransactions": true}]} |
||||
``` |
||||
|
||||
Example result: |
||||
```json |
||||
{"jsonrpc":"2.0","id":2,"result":"0x1"} |
||||
``` |
||||
|
||||
Example notification without the `{"includeTransactions": true}` parameter included: |
||||
```json |
||||
{ |
||||
"jsonrpc": "2.0", |
||||
"method": "eth_subscription", |
||||
"params":{ |
||||
"subscription":"0x1", |
||||
"result": { |
||||
"number":"0x40c22", |
||||
"hash":"0x16af2ee1672203c7ac13ff280822008be0f38e1e5bdc675760015ae3192c0e3a", |
||||
"parentHash":"0x1fcf5dadfaf2ab4d985eb05d40eaa23605b0db25d736610c4b87173bfe438f91", |
||||
"nonce":"0x0000000000000000", |
||||
"sha3Uncles":"0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347", |
||||
"logsBloom":"0x00008000000000080000000000000000000000000000000000000000000000000000000000000000000000000010000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000010000000000000000000000000000000000000040000000000000000000000000000000000000000001000000000000000000000040000000000000000000000000000000000000400000000010000000000000000100000000000020000000000000000000000000000000000010000000000000000000000000000000000000000000", |
||||
"transactionsRoot":"0x5b2e3c1a49352f1ca9fb5dfe74b7ffbbb6d70e23a12693444e26058d8a8e6296", |
||||
"stateRoot":"0xbe8d3bc58bd982421a3ea8b66753404502df0f464ae78a17661d157c406dd38b", |
||||
"receiptsRoot":"0x81b175ec1f4d44fbbd6ba08f1bd3950663b307b7cb35751c067b535cc0b58f12", |
||||
"miner":"0x0000000000000000000000000000000000000000", |
||||
"difficulty":"0x1", |
||||
"totalDifficulty":"0x7c16e", |
||||
"extraData":"0xd783010600846765746887676f312e372e33856c696e757800000000000000002160f780bb1f61eda045c67cdb1297ba37d8349df8035533cb0cf82a7e45f23f3d72bbec125a9f499b3eb110b7d1918d466cb2ede90b38296cfe2aaf452c513f00", |
||||
"size":"0x3a1", |
||||
"gasLimit":"0x47e7c4", |
||||
"gasUsed":"0x11ac3a", |
||||
"timestamp":"0x592afc24", |
||||
"uncles":[], |
||||
"transactions":["0x419c69d21b14e2e8f911def22bb6d0156c876c0e1c61067de836713043364d6c","0x70a5b2cb2cee6e0b199232a1757fc2a9d6053a4691a7afef8508fd88aeeec703","0x4b3035f1d32339fe1a4f88147dc197a0fe5bbd63d3b9dec2dad96a3b46e4fddd"], |
||||
}, |
||||
} |
||||
} |
||||
``` |
||||
|
||||
Example notification with the `{"includeTransactions": true}` parameter included: |
||||
```json |
||||
{ |
||||
"jsonrpc": "2.0", |
||||
"method": "eth_subscription", |
||||
"params":{ |
||||
"subscription":"0x1", |
||||
"result": { |
||||
.... |
||||
"transactions":[ |
||||
{ |
||||
"blockHash":"0xa30ee4d7c271ae5150aec494131c5f1f34089c7aa8fb58bd8bb916a55275bb90", |
||||
"blockNumber":"0x63", |
||||
"from":"0xfe3b557e8fb62b89f4916b721be55ceb828dbd73", |
||||
"gas":"0x5208", |
||||
"gasPrice":"0x3b9aca00", |
||||
"hash":"0x11f66c3e96a92e3c14c1c33ad77381221bf8b58a887b4fed6aee456fc6f39b24", |
||||
"input":"0x", |
||||
"nonce":"0x1", |
||||
"to":"0x627306090abab3a6e1400e9345bc60c78a8bef57", |
||||
"transactionIndex":"0x0", |
||||
"value":"0x56bc75e2d63100000", |
||||
"v":"0xfe8", |
||||
"r":"0x4b57d179c74885ef5f9326fd000665ea7fae44095c1e2016a2817fc671beb8cc", |
||||
"s":"0x7ec060b115746dda392777df07ae1feacc0b83b3646f0a3de9a5fc3615af9bb8", |
||||
} |
||||
], |
||||
}, |
||||
} |
||||
} |
||||
``` |
||||
|
||||
### Logs |
||||
|
||||
Use the `logs` parameter with `eth_subscribe` to be notified of [logs](../Using-Pantheon/Events-and-Logs.md) included in new blocks. You can |
||||
specify a filter object to receive notifications only for logs matching your filter. |
||||
|
||||
Logs subscriptions have an filter object parameter with the following fields: |
||||
|
||||
- `address` - (optional) Either an address or an array of addresses. Returns only logs created from these addresses. |
||||
- `topics` - (optional) Returns only logs that match the [specified topics](../Using-Pantheon/Events-and-Logs.md#topic-filters). |
||||
|
||||
If a chain reorganization occurs, the subscription publishes notifications for logs from the old chain |
||||
with the `removed` property in the [log object](../Reference/Pantheon-API-Objects.md#log-object) set to `true`. |
||||
This means the subscription can publish notifications for multiple logs for the same transaction. |
||||
|
||||
The logs subscription returns [log objects](../Reference/Pantheon-API-Objects.md#log-object). |
||||
|
||||
!!!example |
||||
To subscribe to all logs notifications: |
||||
```json |
||||
{"id": 1, "method": "eth_subscribe", "params": ["logs",{}]} |
||||
``` |
||||
To subscribe to logs for a specific address and topic: |
||||
```json |
||||
{"id": 1, "method": "eth_subscribe", "params": ["logs", {"address": "0x8320fe7702b96808f7bbc0d4a888ed1468216cfd", "topics": ["0xd78a0cb8bb633d06981248b816e7bd33c2a35a6089241d099fa519e361cab902"]}]} |
||||
``` |
||||
|
||||
Example result: |
||||
```json |
||||
{"jsonrpc":"2.0","id":1,"result":"0x2"} |
||||
``` |
||||
Example notification: |
||||
```json |
||||
{ |
||||
"jsonrpc":"2.0", |
||||
"method":"eth_subscription", |
||||
"params":{ |
||||
"subscription":"0x2", |
||||
"result":{ |
||||
"logIndex":"0x0", |
||||
"removed":false, |
||||
"blockNumber":"0x2174", |
||||
"blockHash":"0x7bc83837534aa13df55ff7db77784b1d1ba666d4c4bdd223cae9fe09c7c37eba", |
||||
"transactionHash":"0x942179373e413824c6bc7045e92295aff91b679215446549b4aeb084da46495b", |
||||
"transactionIndex":"0x0", |
||||
"address":"0x9b8397f1b0fecd3a1a40cdd5e8221fa461898517", |
||||
"data":"0x", |
||||
"topics":["0x199cd93e851e4c78c437891155e2112093f8f15394aa89dab09e38d6ca072787","0x0000000000000000000000000000000000000000000000000000000000000005"] |
||||
} |
||||
} |
||||
} |
||||
``` |
||||
|
||||
### Pending Transactions |
||||
|
||||
Use the `newPendingTransactions` parameter with `eth_subscribe` to be notified of pending transactions |
||||
added to the transaction pool for the node. |
||||
|
||||
The pending transactions subscription returns the transaction hashes or transaction details of the pending transactions. |
||||
If the `includeTransactions` parameter is not included, the default is transaction hashes only. |
||||
|
||||
If a chain reorganization occurs, transactions are resubmitted to be included in the new canonical chain. |
||||
This means the subscription can publish notifications for the same pending transaction more than once. |
||||
|
||||
!!!example "Transaction Hashes" |
||||
To subscribe to pending transaction notifications and receive transaction hashes only: |
||||
|
||||
```json |
||||
{"id": 1, "method": "eth_subscribe", "params": ["newPendingTransactions", {"includeTransactions":false}]} |
||||
``` |
||||
|
||||
Example result: |
||||
```json |
||||
{"jsonrpc":"2.0","id":1,"result":"0x1"} |
||||
``` |
||||
|
||||
|
||||
Example notification: |
||||
```json |
||||
{ |
||||
"jsonrpc":"2.0", |
||||
"method":"eth_subscription", |
||||
"params":{ |
||||
"subscription":"0x1", |
||||
"result":"0x5705bc8bf875ff03e98adb98489428835892dc6ba6a6b139fee1becbc26db0b8" |
||||
} |
||||
} |
||||
``` |
||||
|
||||
!!!example "Transaction Details" |
||||
To subscribe to pending transaction notifications and receive transaction details: |
||||
|
||||
```json |
||||
{"id": 1, "method": "eth_subscribe", "params": ["newPendingTransactions", {"includeTransactions":true}]} |
||||
``` |
||||
|
||||
Example result: |
||||
```json |
||||
{"jsonrpc":"2.0","id":1,"result":"0x2"} |
||||
``` |
||||
|
||||
Example notification: |
||||
```json |
||||
{ |
||||
"jsonrpc":"2.0", |
||||
"method":"eth_subscription", |
||||
"params":{ |
||||
"subscription":"0x2", |
||||
"result":{ |
||||
"from":"0xfe3b557e8fb62b89f4916b721be55ceb828dbd73", |
||||
"gas":"0x5208", |
||||
"gasPrice":"0x2540be400", |
||||
"hash":"0x7a4185f40ee93cb27eb132f301d0a5414c1f871051f166fc8804c376aab3ffec", |
||||
"input":"0x", |
||||
"nonce":"0x13", |
||||
"to":"0x9d8f8572f345e1ae53db1dfa4a7fce49b467bd7f", |
||||
"value":"0x8ac7230489e80000", |
||||
"v":"0xfe7", |
||||
"r":"0xdd9013c67469d2fe79afdc61777c55bdced33c90fa6f9b83d8f9b7e445085123", |
||||
"s":"0x45823a1ab22ae9c83876ea435dc5ecc4fe3a83c1bfbc340a5f57df2f5a474fa5" |
||||
} |
||||
} |
||||
} |
||||
``` |
||||
|
||||
### Dropped Transactions |
||||
|
||||
Use the `droppedPendingTransactions` parameter with `eth_subscribe` to be notified of transactions |
||||
dropped from the transaction pool for the node. |
||||
|
||||
The dropped transactions subscription returns the transaction hashes of the dropped transactions. |
||||
|
||||
Transactions can be re-added to the transaction pool from a variety of sources after being dropped. For example, |
||||
receiving a previously dropped transaction from a peer. As a result it's possible to receive multiple dropped |
||||
transaction notifications for the same transaction. |
||||
|
||||
!!!example |
||||
To subscribe to dropped transaction notifications: |
||||
|
||||
```json |
||||
{"id": 1, "method": "eth_subscribe", "params": ["droppedPendingTransactions"]} |
||||
``` |
||||
|
||||
Example result: |
||||
```json |
||||
{"jsonrpc":"2.0","id":1,"result":"0x1"} |
||||
``` |
||||
|
||||
|
||||
Example notification: |
||||
```json |
||||
{ |
||||
"jsonrpc":"2.0", |
||||
"method":"eth_subscription", |
||||
"params":{ |
||||
"subscription":"0x1", |
||||
"result":"0xf57d6a90a7fb30880cfbdf6b432b487d0e94a3b55b34dc4b45e3b0b237ecab4c" |
||||
} |
||||
} |
||||
``` |
||||
|
||||
### Synchronizing |
||||
|
||||
Use the `syncing` parameter with `eth_subscribe` to be notified about synchronization progress. |
||||
|
||||
When behind the chain head, the synchronizing subscription returns an object indicating the synchronization |
||||
progress. When fully synchronized, returns false. |
||||
|
||||
!!!example |
||||
To subscribe to synchronizing notifications: |
||||
```json |
||||
{"id": 1, "method": "eth_subscribe", "params": ["syncing"]} |
||||
``` |
||||
|
||||
Example result: |
||||
```json |
||||
{"jsonrpc":"2.0","id":1,"result":"0x4"} |
||||
``` |
||||
|
||||
Example notification while synchronizing: |
||||
|
||||
```json |
||||
{ |
||||
"jsonrpc":"2.0", |
||||
"method":"eth_subscription", |
||||
"params":{ |
||||
"subscription":"0x4", |
||||
"result":{ |
||||
"startingBlock":"0x0", |
||||
"currentBlock":"0x3e80", |
||||
"highestBlock":"0x67b93c" |
||||
} |
||||
} |
||||
} |
||||
``` |
||||
|
||||
Example notification when synchronized with chain head: |
||||
|
||||
```json |
||||
{ |
||||
"jsonrpc":"2.0", |
||||
"method":"eth_subscription", |
||||
"params":{ |
||||
"subscription":"0x4", |
||||
"result":false |
||||
} |
||||
} |
||||
``` |
||||
|
||||
## Unsubscribing |
||||
|
||||
Use the [subscription ID](#subscription-id) with `eth_unsubscribe` to cancel a subscription. Only the |
||||
connection that created a subscription can unsubscribe from it. |
||||
|
||||
`eth_unsubscribe` returns `true` if subscription succuessfully unsubscribed; otherwise, an error is returned. |
||||
|
||||
!!!example |
||||
To unsubscribe from a subsciption with subscription ID of `0x1`: |
||||
```json |
||||
{"id": 1, "method": "eth_unsubscribe", "params": ["0x1"]} |
||||
``` |
||||
|
||||
Example result: |
||||
```json |
||||
{"jsonrpc":"2.0","id":1,"result":true} |
||||
``` |
||||
@ -1,126 +0,0 @@ |
||||
description: How to access the Pantheon API using JSON-RPC |
||||
<!--- END of page meta data --> |
||||
|
||||
# JSON-RPC over HTTP and WebSockets |
||||
|
||||
To enable JSON-RPC over HTTP or WebSockets, use the [`--rpc-http-enabled`](../Reference/Pantheon-CLI-Syntax.md#rpc-http-enabled) |
||||
and [`--rpc-ws-enabled`](../Reference/Pantheon-CLI-Syntax.md#rpc-ws-enabled) options. |
||||
|
||||
## Postman |
||||
|
||||
Use the button to import our collection of examples to [Postman](https://www.getpostman.com/). |
||||
|
||||
[](https://app.getpostman.com/run-collection/c765d7d22b055c42a510) |
||||
|
||||
|
||||
## Geth Console |
||||
|
||||
The geth console is a REPL (Read, Evaluate, & Print Loop) Javascript console. Use JSON-RPC APIs supported by geth and |
||||
Pantheon directly in the console. |
||||
|
||||
To use the geth console with Pantheon: |
||||
|
||||
1. Start Pantheon with the [`--rpc-http-enabled`](../Reference/Pantheon-CLI-Syntax.md#rpc-http-enabled) option. |
||||
|
||||
1. Specify which APIs to enable using the [`--rpc-http-api`](../Reference/Pantheon-CLI-Syntax.md#rpc-http-api) option. |
||||
|
||||
1. Start the geth console specifying the JSON-RPC endpoint: |
||||
```bash |
||||
geth attach http://localhost:8545 |
||||
``` |
||||
|
||||
Use the geth console to call [JSON-RPC API methods](../Reference/Pantheon-API-Methods.md) that geth and Pantheon share. |
||||
|
||||
!!! example |
||||
```bash |
||||
eth.syncing |
||||
``` |
||||
|
||||
## JSON-RPC Authentication |
||||
|
||||
[Authentication](Authentication.md) is disabled by default. |
||||
|
||||
## HTTP and WebSocket Requests |
||||
|
||||
### HTTP |
||||
|
||||
To make RPC requests over HTTP, you can use [`curl`](https://curl.haxx.se/download.html). |
||||
|
||||
```bash |
||||
curl -X POST --data '{"jsonrpc":"2.0","method":"web3_clientVersion","params":[],"id":53}' <JSON-RPC-http-endpoint:port> |
||||
``` |
||||
|
||||
### WebSockets |
||||
|
||||
To make RPC requests over WebSockets, you can use [wscat](https://github.com/websockets/wscat), a Node.js based command-line tool. |
||||
|
||||
First connect to the WebSockets server using `wscat` (you only need to connect once per session): |
||||
|
||||
```bash |
||||
wscat -c ws://<JSON-RPC-ws-endpoint:port> |
||||
``` |
||||
|
||||
After the connection is established, the terminal displays a '>' prompt. |
||||
Send individual requests as a JSON data package at each prompt: |
||||
|
||||
```bash |
||||
{"jsonrpc":"2.0","method":"web3_clientVersion","params":[],"id":53} |
||||
``` |
||||
|
||||
!!! note |
||||
`wscat` does not support headers. [Authentication](Authentication.md) requires an authentication token to be passed in the |
||||
request header. To use authentication with WebSockets, an app that supports headers is required. |
||||
|
||||
## Readiness and Liveness Endpoints |
||||
|
||||
Pantheon provides readiness and liveness endpoints to confirm the Pantheon node status. Both return a |
||||
`200 OK` status when ready or live and a `503 Service Unavailable` status if not ready or live. |
||||
|
||||
By default, the readiness check requires a peer to be connected and the node to be within 2 blocks of the best |
||||
known block. If [p2p communication is disabled](../Reference/Pantheon-CLI-Syntax.md#p2p-enabled), |
||||
no peers are required. A live node with p2p disabled is always ready. |
||||
|
||||
Use the query parameters `minPeers` and `maxBlocksBehind` to adjust the number of peers required and number of blocks tolerance. |
||||
|
||||
```bash tab="Readiness Endpoint" |
||||
http://<JSON-RPC-HTTP-endpoint:port>/readiness |
||||
``` |
||||
|
||||
```bash tab="curl Request Example" |
||||
curl -v 'http://localhost:8545/readiness' |
||||
``` |
||||
|
||||
```bash tab="Query Parameters Example" |
||||
curl -v 'http://localhost:8545/readiness?minPeers=0&maxBlocksBehind=10' |
||||
``` |
||||
|
||||
The liveness check requires the JSON RPC server to be up. |
||||
|
||||
```bash tab="Liveness Endpoint" |
||||
http://<JSON-RPC-HTTP-endpoint:port>/liveness |
||||
``` |
||||
|
||||
```bash tab="curl Request Example" |
||||
curl -v 'http://localhost:8545/liveness' |
||||
``` |
||||
|
||||
## API Methods Enabled by Default |
||||
|
||||
The `ETH`, `NET`, and `WEB3` API methods are enabled by default. |
||||
|
||||
Use the [`--rpc-http-api`](../Reference/Pantheon-CLI-Syntax.md#rpc-http-api) or [`--rpc-ws-api`](../Reference/Pantheon-CLI-Syntax.md#rpc-ws-api) |
||||
options to enable the `ADMIN`, `CLIQUE`, `DEBUG`, `EEA`, `IBFT`, `MINER`, `PERM`, and `TXPOOL` API methods. |
||||
|
||||
## 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](../Reference/Pantheon-API-Methods.md#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. Use only with [eth_getTransactionCount](../Reference/Pantheon-API-Methods.md#eth_gettransactioncount). |
||||
|
||||
@ -1,155 +0,0 @@ |
||||
description: Local Permissioning |
||||
<!--- END of page meta data --> |
||||
|
||||
# Local Permissioning |
||||
|
||||
Local permissioning supports node and account whitelisting. |
||||
|
||||
## Node Whitelisting |
||||
|
||||
Node whitelisting is specified by the nodes whitelist in the [permissions configuration file](#permissions-configuration-file) file. |
||||
When node whitelisting is enabled, communication is restricted to only nodes in the whitelist. |
||||
|
||||
!!! example "Nodes Whitelist in Permissions Configuration File" |
||||
`nodes-whitelist=["enode://6f8a80d14311c39f35f516fa664deaaaa13e85b2f7493f37f6144d86991ec012937307647bd3b9a82abe2974e1407241d54947bbb39763a4cac9f77166ad92a0@192.168.0.9:4567","enode://6f8a80d14311c39f35f516fa664deaaaa13e85b2f7493f37f6144d86991ec012937307647bd3b9a82abe2974e1407241d54947bbb39763a4cac9f77166ad92a0@192.169.0.9:4568"]` |
||||
|
||||
Node whitelisting is at the node level. That is, each node in the network has a [permissions configuration file](#permissions-configuration-file) |
||||
file in the [data directory](../Reference/Pantheon-CLI-Syntax.md#data-path) for the node. |
||||
|
||||
To update the nodes whitelist when the node is running, use the JSON-RPC API methods: |
||||
|
||||
* [perm_addNodesToWhitelist](../Reference/Pantheon-API-Methods.md#perm_addnodestowhitelist) |
||||
* [perm_removeNodesFromWhitelist](../Reference/Pantheon-API-Methods.md#perm_removenodesfromwhitelist) |
||||
|
||||
Alternatively, update the [`permissions_config.toml`](#permissions-configuration-file) file directly and use the |
||||
[`perm_reloadPermissionsFromFile`](../Reference/Pantheon-API-Methods.md#perm_reloadpermissionsfromfile) method |
||||
to update the whitelists. |
||||
|
||||
Updates to the permissions configuration file persist across node restarts. |
||||
|
||||
To view the nodes whitelist, use the [perm_getNodesWhitelist](../Reference/Pantheon-API-Methods.md#perm_getnodeswhitelist) method. |
||||
|
||||
!!! note |
||||
Each node has a [permissions configuration file](#permissions-configuration-file) which means nodes can have different nodes whitelists. |
||||
This means nodes may be participating in the network that are not on the whitelist of other nodes in the network. |
||||
We recommend each node in the network has the same nodes whitelist. |
||||
|
||||
On-chain permissioning is under development. On-chain permissioning will use one on-chain |
||||
nodes whitelist. |
||||
|
||||
!!! example "Example Different Node Whitelists" |
||||
|
||||
Node 1 Whitelist = [Node 2, Node 3] |
||||
|
||||
Node 2 Whitelist = [Node 3, Node 5] |
||||
|
||||
Node 5 is participating in the same network as Node 1 even though Node 1 does not have Node 5 on their whitelist. |
||||
|
||||
### Bootnodes |
||||
|
||||
The bootnodes must be included in the nodes whitelist or Pantheon does not start when node permissions are enabled. |
||||
|
||||
!!! example |
||||
If you start Pantheon with specified bootnodes and have node permissioning enabled: |
||||
|
||||
```bash |
||||
--bootnodes="enode://7e4ef30e9ec683f26ad76ffca5b5148fa7a6575f4cfad4eb0f52f9c3d8335f4a9b6f9e66fcc73ef95ed7a2a52784d4f372e7750ac8ae0b544309a5b391a23dd7@127.0.0.1:30303","enode://2feb33b3c6c4a8f77d84a5ce44954e83e5f163e7a65f7f7a7fec499ceb0ddd76a46ef635408c513d64c076470eac86b7f2c8ae4fcd112cb28ce82c0d64ec2c94@127.0.0.1:30304","enode://7b61d5ee4b44335873e6912cb5dd3e3877c860ba21417c9b9ef1f7e500a82213737d4b269046d0669fb2299a234ca03443f25fe5f706b693b3669e5c92478ade@127.0.0.1:30305" |
||||
``` |
||||
|
||||
The `nodes-whitelist` in the [permissions configuration file](#permissions-configuration-file) must contain the specified bootnodes. |
||||
|
||||
### Enabling Node Whitelisting |
||||
|
||||
To enable node whitelisting, specify the [`--permissions-nodes-config-file-enabled`](../Reference/Pantheon-CLI-Syntax.md#permissions-nodes-config-file-enabled) option |
||||
when starting Pantheon. |
||||
|
||||
The `PERM` API methods are not enabled by default. Use the [`--rpc-http-api`](../Reference/Pantheon-CLI-Syntax.md#rpc-http-api) |
||||
or [`--rpc-ws-api`](../Reference/Pantheon-CLI-Syntax.md#rpc-ws-api) options to enable the `PERM` API methods. |
||||
|
||||
## Account Whitelisting |
||||
|
||||
Account whitelisting is specified by the accounts whitelist in the [permissions configuration file](#permissions-configuration-file). |
||||
A node with account permissioning accepts transactions only from accounts in the accounts whitelist. |
||||
|
||||
!!! example "Accounts Whitelist in Permissions Configuration File" |
||||
`accounts-whitelist=["0x0000000000000000000000000000000000000009"]` |
||||
|
||||
Account whitelisting is at the node level. That is, each node in the network has a [permisssions configuration file](#permissions-configuration-file) |
||||
in the [data directory](../Reference/Pantheon-CLI-Syntax.md#data-path) for the node. |
||||
|
||||
Transactions are validated against the accounts whitelist at the following points: |
||||
|
||||
1. Submitted by JSON-RPC API method [`eth_sendRawTransaction`](../Reference/Pantheon-API-Methods.md#eth_sendrawtransaction) |
||||
1. Received via propagation from another node |
||||
1. Added to a block by a mining node |
||||
|
||||
Once added to a block, the transactions are not validated against the whitelist when received by another node. That is, a node |
||||
can synchronise and add blocks containing transactions from accounts that are not on the accounts whitelist of that node. |
||||
|
||||
!!! example "Example Different Account Whitelists" |
||||
Node 1 Whitelist = [Account A, Account B] |
||||
|
||||
Node 2 Whitelist = [Account B, Account C] |
||||
|
||||
Mining Node Whitelist = [Account A, Account B] |
||||
|
||||
Account A submits a transaction on Node 1. Node 1 validates and propagates the transaction. The Mining Node receives the transaction, |
||||
validates it is from an account in the Mining Node accounts whitelist, and includes the transaction in the block. Node 2 receives and |
||||
adds the block created by the Mining Node. |
||||
|
||||
Node 2 now has a transaction in the blockchain from Account A which is not on the accounts whitelist for Node 2. |
||||
|
||||
!!! note |
||||
Each node has a [permissions configuration file](#permissions-configuration-file) which means nodes in the network can have different accounts whitelists. |
||||
This means a transaction can be successfully submitted by Node A from an account in the Node A whitelist but rejected by |
||||
Node B to which it is propagated if the account is not in the Node B whitelist. |
||||
We recommend each node in the network has the same accounts whitelist. |
||||
|
||||
To update the accounts whitelist when the node is running, use the JSON-RPC API methods: |
||||
|
||||
* [`perm_addAccountsToWhitelist`](../Reference/Pantheon-API-Methods.md#perm_addaccountstowhitelist) |
||||
* [`perm_removeAccountsFromWhitelist`](../Reference/Pantheon-API-Methods.md#perm_removeaccountsfromwhitelist) |
||||
|
||||
Alternatively, update the [`permissions_config.toml`](#permissions-configuration-file) file directly and use the |
||||
[`perm_reloadPermissionsFromFile`](../Reference/Pantheon-API-Methods.md#perm_reloadpermissionsfromfile) method |
||||
to update the whitelists. |
||||
|
||||
Updates to the permissions configuration file persist across node restarts. |
||||
|
||||
To view the accounts whitelist, use the [`perm_getAccountsWhitelist`](../Reference/Pantheon-API-Methods.md#perm_getaccountswhitelist) method. |
||||
|
||||
### Enabling Account Whitelisting |
||||
|
||||
To enable account whitelisting, specify the [`--permissions-accounts-config-file-enabled`](../Reference/Pantheon-CLI-Syntax.md#permissions-accounts-enabled) option |
||||
when starting Pantheon. |
||||
|
||||
The `PERM` API methods are not enabled by default. Use the [`--rpc-http-api`](../Reference/Pantheon-CLI-Syntax.md#rpc-http-api) |
||||
or [`--rpc-ws-api`](../Reference/Pantheon-CLI-Syntax.md#rpc-ws-api) options to enable the `PERM` API methods. |
||||
|
||||
## Permissions Configuration File |
||||
|
||||
The permissions configuration file contains the nodes and accounts whitelists. If the [`--permissions-accounts-config-file`](../Reference/Pantheon-CLI-Syntax.md#permissions-accounts-config-file) |
||||
and [`permissions-nodes-config-file`](../Reference/Pantheon-CLI-Syntax.md#permissions-nodes-config-file) |
||||
options are not specified, the permissions configuration file must be called `permissions_config.toml` and |
||||
must be in the [data directory](../Reference/Pantheon-CLI-Syntax.md#data-path) for the node. |
||||
|
||||
The accounts and nodes whitelists can be specified in the same file or in separate files for accounts and nodes. |
||||
|
||||
Use the [`--permissions-accounts-config-file`](../Reference/Pantheon-CLI-Syntax.md#permissions-accounts-config-file) |
||||
and [`permissions-nodes-config-file`](../Reference/Pantheon-CLI-Syntax.md#permissions-nodes-config-file) |
||||
options to specify a permissions configuration file (or separate files for accounts and nodes) in any location. |
||||
|
||||
!!!note |
||||
The [`--permissions-accounts-config-file`](../Reference/Pantheon-CLI-Syntax.md#permissions-accounts-config-file) |
||||
and [`permissions-nodes-config-file`](../Reference/Pantheon-CLI-Syntax.md#permissions-nodes-config-file) |
||||
options are not used when running Pantheon from the [Docker image](../Getting-Started/Run-Docker-Image.md). |
||||
Use a bind mount to [specify a permissions configuration file with Docker](../Getting-Started/Run-Docker-Image.md#permissions-configuration-file). |
||||
|
||||
!!! example "Example Permissions Configuration File" |
||||
```toml |
||||
accounts-whitelist=["0xb9b81ee349c3807e46bc71aa2632203c5b462032", "0xb9b81ee349c3807e46bc71aa2632203c5b462034"] |
||||
|
||||
nodes-whitelist=["enode://7e4ef30e9ec683f26ad76ffca5b5148fa7a6575f4cfad4eb0f52f9c3d8335f4a9b6f9e66fcc73ef95ed7a2a52784d4f372e7750ac8ae0b544309a5b391a23dd7@127.0.0.1:30303","enode://2feb33b3c6c4a8f77d84a5ce44954e83e5f163e7a65f7f7a7fec499ceb0ddd76a46ef635408c513d64c076470eac86b7f2c8ae4fcd112cb28ce82c0d64ec2c94@127.0.0.1:30304","enode://7b61d5ee4b44335873e6912cb5dd3e3877c860ba21417c9b9ef1f7e500a82213737d4b269046d0669fb2299a234ca03443f25fe5f706b693b3669e5c92478ade@127.0.0.1:30305"] |
||||
``` |
||||
|
||||
|
||||
@ -1,171 +0,0 @@ |
||||
description: Setting up and using onchain Permissioning |
||||
<!--- END of page meta data --> |
||||
|
||||
# Getting Started with Onchain Permissioning |
||||
|
||||
The following steps describe bootstrapping a local permissioned network using a Pantheon node and a |
||||
development server to run the Permissioning Management Dapp. |
||||
|
||||
!!! note |
||||
In production, a webserver is required to [host the Permissioning Management Dapp](Production.md). |
||||
|
||||
To start a network with onchain permissioning: |
||||
|
||||
1. [Install pre-requisites](#pre-requisites) |
||||
1. [Add the ingress contracts to the genesis file](#add-ingress-contracts-to-genesis-file) |
||||
1. [Set environment variables](#set-environment-variables) |
||||
1. [Start first node with onchain permissioning and the JSON-RPC HTTP service enabled](#onchain-permissioning-command-line-options) |
||||
1. [Clone the permissioning contracts repository and install dependencies](#clone-contracts-and-install-dependencies) |
||||
1. [Build project](#build-project) |
||||
1. [Deploy the permissioning contracts](#deploy-contracts) |
||||
1. [Start the development server for the Permissioning Management Dapp](#start-the-permissioning-management-dapp) |
||||
1. [Add the first node to the nodes whitelist](#update-nodes-whitelist) |
||||
|
||||
## Pre-requisites |
||||
|
||||
For the development server to run the dapp: |
||||
|
||||
* [NodeJS](https://nodejs.org/en/) v10.16.0 or later |
||||
* [Yarn](https://yarnpkg.com/en/) v1.15 or later |
||||
* Browser with [MetaMask installed](https://metamask.io/) |
||||
|
||||
## Add Ingress Contracts to Genesis File |
||||
|
||||
!!! tip |
||||
If the network is using only account or nodes permissioning, add only the relevant ingress contract to the |
||||
genesis file. |
||||
|
||||
Add the Ingress contracts to the genesis file for your network by copying them from [`genesis.json`](https://github.com/PegaSysEng/permissioning-smart-contracts/blob/master/genesis.json) |
||||
in the [`permissioning-smart-contracts` repository](https://github.com/PegaSysEng/permissioning-smart-contracts): |
||||
|
||||
```json |
||||
"0x0000000000000000000000000000000000008888": { |
||||
"comment": "Account Ingress smart contract", |
||||
"balance": "0", |
||||
"code": <stripped>, |
||||
"storage": { |
||||
<stripped> |
||||
} |
||||
} |
||||
|
||||
"0x0000000000000000000000000000000000009999": { |
||||
"comment": "Node Ingress smart contract", |
||||
"balance": "0", |
||||
"code": <stripped>, |
||||
"storage": { |
||||
<stripped> |
||||
} |
||||
} |
||||
``` |
||||
|
||||
!!! important |
||||
To support the permissioning contracts, ensure your genesis file includes at least the `constantinopleFixBlock` milestone. |
||||
|
||||
## Set Environment Variables |
||||
|
||||
Create the following environment variables and set to the specified values: |
||||
|
||||
* `PANTHEON_NODE_PERM_ACCOUNT` - account to deploy the permissioning contracts and become the first admin account. |
||||
|
||||
* `PANTHEON_NODE_PERM_KEY` - private key of the account to deploy the permissioning contracts. |
||||
|
||||
* `ACCOUNT_INGRESS_CONTRACT_ADDRESS` - address of the Account Ingress contract in the genesis file. |
||||
|
||||
* `NODE_INGRESS_CONTRACT_ADDRESS` - address of the Node Ingress contract in the genesis file. |
||||
|
||||
* `PANTHEON_NODE_PERM_ENDPOINT` - required only if your node is not using the default JSON-RPC host and port (`http://127.0.0.1:8545`). |
||||
Set to JSON-RPC host and port. When bootstrapping the network, the specified node is used to deploy the contracts and is the first node |
||||
in the network. |
||||
|
||||
!!! important |
||||
The account specified must be a miner (PoW networks) or validator (PoA networks). |
||||
|
||||
If your network is not a [free gas network](../../Configuring-Pantheon/FreeGas.md), the account used to |
||||
interact with the permissioning contracts must have a balance. |
||||
|
||||
## Onchain Permissioning Command Line Options |
||||
|
||||
All nodes participating in a permissioned network must include the command line options to enable account and/or |
||||
node permissioning: |
||||
|
||||
* [`--permissions-accounts-contract-enabled`](../../Reference/Pantheon-CLI-Syntax.md#permissions-accounts-contract-enabled) |
||||
to enable onchain accounts permissioning |
||||
|
||||
* [`--permissions-accounts-contract-address`](../../Reference/Pantheon-CLI-Syntax.md#permissions-accounts-contract-address) |
||||
set to the address of the Account Ingress contract in the genesis file (`"0x0000000000000000000000000000000000008888"`) |
||||
|
||||
* [`--permissions-nodes-contract-enabled`](../../Reference/Pantheon-CLI-Syntax.md#permissions-nodes-contract-enabled) |
||||
to enable onchain nodes permissioning |
||||
|
||||
* [`--permissions-nodes-contract-address`](../../Reference/Pantheon-CLI-Syntax.md#permissions-nodes-contract-address) |
||||
set to the address of the Node Ingress contract in the genesis file (`"0x0000000000000000000000000000000000009999"`) |
||||
|
||||
Start your first node with command line options to enable onchain permissioning and the JSON-RPC HTTP host and port |
||||
matching environment variable `PANTHEON_NODE_PERM_ENDPOINT`. |
||||
|
||||
## Clone Project and Install Dependencies |
||||
|
||||
1. Clone the `permissioning-smart-contracts` repository: |
||||
|
||||
```bash |
||||
git clone https://github.com/PegaSysEng/permissioning-smart-contracts.git |
||||
``` |
||||
|
||||
1. Change into the `permissioning-smart-contracts` directory and run: |
||||
|
||||
```bash |
||||
yarn install |
||||
``` |
||||
|
||||
## Build Project |
||||
|
||||
In the `permissioning-smart-contracts` directory, build the project: |
||||
|
||||
```bash |
||||
yarn run build |
||||
``` |
||||
|
||||
## Deploy Contracts |
||||
|
||||
In the `permissioning-smart-contracts` directory, deploy the Admin and Rules contracts: |
||||
|
||||
```bash |
||||
yarn truffle migrate --reset |
||||
``` |
||||
|
||||
The Admin and Rules contracts are deployed and the Ingress contract updated with the name and version of the contracts. |
||||
The migration logs the addresses of the Admin and Rules contracts. |
||||
|
||||
!!! important |
||||
The account that deploys the contracts is automatically an [admin account](#update-accounts-or-admin-accounts-whitelists). |
||||
|
||||
## Start the Development Server for the Permissioning Management Dapp |
||||
|
||||
!!! note |
||||
In production, a webserver is required to [host the Permissioning Management Dapp](Production.md). |
||||
|
||||
1. In the `permissioning-smart-contracts` directory, start the web server serving the Dapp: |
||||
|
||||
```bash |
||||
yarn start |
||||
``` |
||||
|
||||
The Dapp is displayed at [http://localhost:3000](http://localhost:3000). |
||||
|
||||
1. Ensure MetaMask is connected to your local node (by default `http://localhost:8545`). |
||||
|
||||
A MetaMask notification is displayed requesting permission for Pantheon Permissioning to |
||||
connect to your account. |
||||
|
||||
1. Click the _Connect_ button. |
||||
|
||||
The Dapp is displayed with the account specified by the `PANTHEON_NODE_PERM_ACCOUNT` environment variable |
||||
in the _Whitelisted Accounts_ and _Admin Accounts_ tabs. |
||||
|
||||
!!! note |
||||
Only [admin accounts](#update-accounts-or-admin-accounts-whitelists) can add or remove nodes from the whitelist. |
||||
|
||||
## Add First Node to Whitelist |
||||
|
||||
The first node must [add itself to the whitelist](Updating-Whitelists.md#update-nodes-whitelist) before adding other nodes. |
||||
|
||||
@ -1,57 +0,0 @@ |
||||
description: Onchain Permissioning |
||||
<!--- END of page meta data --> |
||||
|
||||
# Onchain Permissioning |
||||
|
||||
Onchain permissioning uses smart contracts to store and maintain the node, account, and admin whitelists. |
||||
Using onchain permissioning enables all nodes to read the whitelists from a single source, the blockchain. |
||||
|
||||
!!! important |
||||
The dependency chain for our implementation of onchain permissioning includes [web3js](https://github.com/ethereum/web3.js/) which is |
||||
LGPL licensed. |
||||
|
||||
## Permissioning Contracts |
||||
|
||||
The permissioning smart contracts are provided in the [PegaSysEng/permissioning-smart-contracts](https://github.com/PegaSysEng/permissioning-smart-contracts) repository: |
||||
|
||||
* Ingress contracts for nodes and accounts - proxy contracts defined in the genesis file that defer the permissioning logic to the |
||||
Node Rules and Account Rules contracts. The Ingress contracts are deployed to static addresses. |
||||
|
||||
* Node Rules - stores the node whitelist and node whitelist operations (for example, add and remove). |
||||
|
||||
* Account Rules - stores the accounts whitelist and account whitelist operations (for example, add and remove). |
||||
|
||||
* Admin - stores the list of admin accounts and admin list operations (for example, add and remove). There is |
||||
one list of admin accounts for node and accounts. |
||||
|
||||
!!! note |
||||
The permissioning smart contracts are currently in the process of going through a third party audit. |
||||
Please [contact us](https://pegasys.tech/contact/) before using in a production environment. |
||||
|
||||
## Permissioning Management Dapp |
||||
|
||||
The [Permissioning Management Dapp](Getting-Started-Onchain-Permissioning.md) is provided to view |
||||
and maintain the whitelists. |
||||
|
||||
!!! tip |
||||
Before v1.2, we provided a [management interface using Truffle](https://docs.pantheon.pegasys.tech/en/1.1.4/Permissions/Onchain-Permissioning/). |
||||
The management interface using Truffle is deprecated and we recommend using the Dapp for an improved user experience. |
||||
|
||||
### Whitelists |
||||
|
||||
Permissioning implements three whitelists: |
||||
|
||||
* Accounts can submit transactions to the network |
||||
|
||||
* Nodes can participate in the network |
||||
|
||||
* Admins are accounts that can update the accounts and nodes whitelists |
||||
|
||||
## Bootnodes |
||||
|
||||
When a node is added to the network, it connects to the bootnodes until it synchronizes to the chain head regardless of |
||||
node permissions. Once in sync, the permissioning rules in the Account Rules and Node Rules smart contracts are applied. |
||||
|
||||
If a sychronized node loses all peer connections (that is, it has 0 peers), it reconnects to the bootnodes to |
||||
rediscover peers. |
||||
|
||||
@ -1,29 +0,0 @@ |
||||
description: Deploying Permissioning Management Dapp for production |
||||
<!--- END of page meta data --> |
||||
|
||||
# Deploying Permissioning Management Dapp for Production |
||||
|
||||
To deploy the Permissioning Management dapp for production: |
||||
|
||||
1. Get the most recent release (tarball or zip) from the [projects release page](https://github.com/PegaSysEng/permissioning-smart-contracts/releases/latest). |
||||
|
||||
1. Unpack the distribution into a directory available to your webserver. |
||||
|
||||
1. In the root of the directory to which the distribution was unpacked, add a file called `config.json` replacing |
||||
the placeholders. |
||||
|
||||
```json tab="config.json" |
||||
{ |
||||
"accountIngressAddress": "<Address of the account ingress contract>", |
||||
"nodeIngressAddress": "<Address of the node ingress contract>", |
||||
"networkId": "<ID of your Ethereum network>" |
||||
} |
||||
``` |
||||
|
||||
1. On your webserver, host the contents of the directory as static files and direct root requests to `index.html` |
||||
|
||||
## Starting a Production Permissioned Network |
||||
|
||||
Follow the procedure as for [Getting Started with Onchain Perissioning](Getting-Started-Onchain-Permissioning.md) |
||||
but do not perform the steps using `yarn` to install, build, and start the development server. Instead follow the procedure above to |
||||
deploy the Permissioning Management dapp to your webserver. |
||||
@ -1,46 +0,0 @@ |
||||
description: Updating onchain whitelists |
||||
<!--- END of page meta data --> |
||||
|
||||
## Update Nodes Whitelist |
||||
|
||||
To add a node to the nodes whitelist: |
||||
|
||||
1. In the _Whitelisted Nodes_ tab of the Permissioning Management Dapp, click the _Add Whitelisted Nodes_ |
||||
button. The add node window is displayed. |
||||
|
||||
2. Enter the [enode URL](../../Configuring-Pantheon/Node-Keys.md#enode-url) of the node to be added and click |
||||
the _Add Whitelisted Node_ button. |
||||
|
||||
To remove a node from the nodes whitelist: |
||||
|
||||
1. In the _Whitelisted Nodes_ tab of the Permissioning Management Dapp, hover over the row of the node to remove. |
||||
A trash can is displayed. |
||||
|
||||
1. Click on the trash can. |
||||
|
||||
!!! tip |
||||
If you add a running node, the node does not attempt to reconnect to the bootnode and synchronize until |
||||
peer discovery restarts. To add a whitelisted node as a peer without waiting for peer discovery to restart, use [`admin_addPeer`](../../Reference/Pantheon-API-Methods.md#admin_addpeer). |
||||
|
||||
If the node is added to the whitelist before starting the node, using `admin_addPeer` is not required because |
||||
peer discovery is run on node startup. |
||||
|
||||
## Update Accounts Whitelists |
||||
|
||||
To add an account to the accounts whitelist: |
||||
|
||||
1. In the _Whitelisted Accounts_ tab of the Permissioning Management Dapp, click the _Add Whitelisted Account_ |
||||
button. The add account window is displayed. |
||||
|
||||
1. Enter the account address in the _Account Address_ field and click the _Add Whitelisted Account_ button. |
||||
|
||||
To remove an account from the accounts whitelist: |
||||
|
||||
1. In the _Whitelisted Accounts_ tab of the Permissioning Management Dapp, hover over the |
||||
row of the account to be removed. A trash can is displayed. |
||||
|
||||
1. Click on the trash can. |
||||
|
||||
## Update Admins |
||||
|
||||
Admins are added or removed in the same way as accounts except in the _Admin Accounts_ tab. |
||||
@ -1,58 +0,0 @@ |
||||
description: Pantheon Permissioning feature |
||||
<!--- END of page meta data --> |
||||
|
||||
# Permissioning |
||||
|
||||
A permissioned network allows only specified nodes and accounts to participate by enabling node permissioning and/or |
||||
account permissioning on the network. |
||||
|
||||
!!! important "Permissioning is not Privacy" |
||||
In peer-to-peer networks, node permissioning enforces rules on nodes you control. |
||||
|
||||
Permissioning requires a distributed network of trust across the network where participants agree to |
||||
follow the rules. A single bad actor can decide not to follow the rules. Nodes can take action |
||||
to prevent the bad actor adding to the chain but they cannot prevent the bad actor from allowing access to the chain. |
||||
|
||||
Pantheon also implements [privacy](../Privacy/Explanation/Privacy-Overview.md). |
||||
|
||||
## Node Permissioning |
||||
|
||||
Use node permissioning to restrict access to known participants only. |
||||
|
||||
 |
||||
|
||||
## Account Permissioning |
||||
|
||||
Use account permissioning: |
||||
|
||||
* Enforce onboarding or identity requirements |
||||
* Suspend accounts |
||||
* Blacklist broken contracts |
||||
* Restrict the actions an account can perform |
||||
|
||||
 |
||||
|
||||
## Specifying Permissioning |
||||
|
||||
Permissioning is [local](#local) or [onchain](#onchain). |
||||
|
||||
### Local |
||||
|
||||
[Local permissioning](Local-Permissioning.md) is specified at the node level. Each node in the network has a [permissions configuration file](#permissions-configuration-file). |
||||
|
||||
Local permissioning affects your node but not the rest of the network. Use local permissioning to restrict use |
||||
of your node (that is, the resources under your control). For example, customers that can access your node. |
||||
|
||||
Local permissioning doesn't require co-ordination with the rest of the network and you can act immediately to |
||||
protect your node. Your rules are not enforced in blocks produced by other nodes. |
||||
|
||||
### Onchain |
||||
|
||||
[Onchain permissioning](Onchain-Permissioning/Onchain-Permissioning.md) is specified in a smart contract on the network. Specifying permissioning onchain |
||||
enables all nodes to read and update permissioning configuration from one location. |
||||
|
||||
Onchain permissioning requires co-ordination to update rules. The network may not be able to act immediately |
||||
(for example, the smart contract may enforce a minimum of votes before changing permissioning rules). |
||||
|
||||
When onchain permissioning is updated, the update is applied across the network and new blocks abide by the updated rules. |
||||
For example, blocked accounts can no longer add transactions to the chain. |
||||
@ -1,67 +0,0 @@ |
||||
description: Privacy |
||||
<!--- END of page meta data --> |
||||
|
||||
# Privacy Groups |
||||
|
||||
A privacy group is a group of nodes identified by a unique privacy group ID by Orion. Each private transaction is |
||||
stored in Orion with the privacy group ID. |
||||
|
||||
The Pantheon nodes maintain the public world state for the blockchain and a private state for each privacy group. |
||||
The private states contain data that is not shared in the globally replicated world state. Private transactions read |
||||
and write to the private world state for the privacy group, and read from the public world state. |
||||
|
||||
## Privacy Types |
||||
|
||||
Pantheon implements two types of privacy: |
||||
|
||||
* EEA-compliant privacy - private transactions include `privateFor` as the recipient. |
||||
* Pantheon-extended privacy - private transactions include `privacyGroupId` as the recipient. |
||||
|
||||
Both privacy types create privacy groups and store private transactions with their privacy group in Orion. |
||||
|
||||
 |
||||
|
||||
!!! note |
||||
The Orion nodes are not shown above for clarity only. To send private transactions, |
||||
each Pantheon node must have an associated Orion node. |
||||
|
||||
### EEA-compliant Privacy |
||||
|
||||
In our privacy implementation complying with the [EEA Client Specification](https://entethalliance.org/technical-documents/) |
||||
the group of nodes specified by `privateFrom`and `privateFor` form a privacy group and are given a unique |
||||
privacy group ID by Orion. |
||||
|
||||
!!! example |
||||
The diagram above illustrates two privacy groups enabling: |
||||
|
||||
* A, B, and C to send transactions that are private from D |
||||
* A, C, and D to send transactions that are private from B |
||||
|
||||
Using EEA-compliant privacy, to send private transactions between A, B, and C, A initialises a contract in a private transaction with |
||||
B and C specified as the `privateFor` and A specified as the `privateFrom`. Initialising the contract |
||||
creates a privacy group consisting of A, B, and C. For the ABC private state to remain consistent, |
||||
A, B, and C must be included on transactions (as either `privateFrom` or `privateFor`) even if they are |
||||
between two of the three parties. |
||||
|
||||
To send private transactions between A, C, and D, C initialises a different contract in a private transaction with |
||||
A and D specified as the `privateFor` and C specified as the `privateFrom`. Initialising the contract |
||||
creates a privacy group consisting of A, C, and D. For the ACD private state to remain consistent, |
||||
A, C, and D must be included on transactions (as either `privateFrom` or `privateFor`) even if they are |
||||
between two of the three parties. |
||||
|
||||
|
||||
### Pantheon-extended Privacy |
||||
|
||||
In our extended privacy implementation, a privacy group is created using [`priv_createPrivacyGroup`](../../Reference/Pantheon-API-Methods.md#priv_createprivacygroup) |
||||
and private transactions sent to the privacy group ID. |
||||
|
||||
!!! example |
||||
Using the same privacy groups as above. |
||||
|
||||
Using Pantheon-extended privacy, to send private transactions between A, B, and C, A creates a privacy |
||||
group consisting of A, B, and C. The privacy group ID is specified when sending private transactions and |
||||
A, B, and C are recipients of all private transactions sent to the privacy group. |
||||
|
||||
To send private transactions between A, C, and D, A creates a privacy group consisting of A, C, and D. |
||||
The privacy group ID of this group is specified when sending private transactions with A, C, and D |
||||
as recipients. |
||||
@ -1,56 +0,0 @@ |
||||
description: Privacy |
||||
<!--- END of page meta data --> |
||||
|
||||
# Privacy |
||||
|
||||
Privacy in Pantheon refers to the ability to keep transactions private between the involved parties. |
||||
Other parties cannot access the transaction content, sending party, or list of participating parties. |
||||
|
||||
!!! important |
||||
For production systems requiring private transactions, we recommend using a network |
||||
with a consensus mechanism supporting transaction finality. For example, [IBFT 2.0](../../Consensus-Protocols/IBFT.md). |
||||
|
||||
## Private Transaction Manager |
||||
|
||||
Pantheon uses a Private Transaction Manager to implement privacy. For example, [Orion](http://docs.orion.pegasys.tech). |
||||
Each Pantheon node that sends or receives private transactions requires an associated Orion node. |
||||
|
||||
 |
||||
|
||||
Private transactions are passed from the Pantheon node to the associated Orion node. The Orion node |
||||
encrypts and directly distributes (that is, point to point) the private transaction to Orion nodes |
||||
participating in the transaction. |
||||
|
||||
!!! tip |
||||
Private Transaction Managers are also known as Enclaves. |
||||
|
||||
## Private Transaction Attributes |
||||
|
||||
Private transactions have additional attributes to public Ethereum transactions: |
||||
|
||||
* `privateFrom` - Orion public key of transaction sender |
||||
|
||||
* `privateFor` - Orion public keys of transaction recipients or `privacyGroupId` - [Privacy group to receive transaction](Privacy-Groups.md) |
||||
|
||||
* `restriction` - Private transactions are `restricted` or `unrestricted`: |
||||
|
||||
- In `restricted` private transactions the payload of the private transaction is received and stored only by |
||||
the nodes participating in the transaction. |
||||
|
||||
- In `unrestricted` private transactions the payload of the private transaction is transmitted to all nodes |
||||
in the network but is readable only by nodes participating in the transaction. |
||||
|
||||
!!! important |
||||
Pantheon implements `restricted` private transactions only. |
||||
|
||||
## Pantheon and Orion Keys |
||||
|
||||
Pantheon and Orion nodes both have public/private key pairs identifying them. The private transaction |
||||
submitted from the Pantheon node to the Orion node is signed with the Pantheon node private key. The |
||||
`privateFrom` and `privateFor` attributes specified in the RLP-encoded transaction string for |
||||
[`eea_sendRawTransaction`](../../Reference/Pantheon-API-Methods.md#eea_sendrawtransaction) are the public keys |
||||
of the Orion nodes sending and receiving the transaction. |
||||
|
||||
!!! important |
||||
The mapping of Pantheon node addresses to Orion node public keys is off-chain. That is, the |
||||
sender of a private transaction must know the Orion node public key of the recipient. |
||||
@ -1,60 +0,0 @@ |
||||
description: Private Transaction Processing |
||||
<!--- END of page meta data --> |
||||
|
||||
# Processing Private Transactions |
||||
|
||||
Processing private transactions involves the following: |
||||
|
||||
- **Precompiled Contract**: Smart contract compiled from the source language to EVM bytecode and stored by an |
||||
Ethereum node for later execution. |
||||
|
||||
- **Privacy Marker Transaction**: Public Ethereum transaction with a payload of the transaction hash of the |
||||
private transaction. The `to` attribute of the Privacy Marker Transaction is the address of the privacy precompile contract. |
||||
The Privacy Marker Transaction is signed with the [Ethereum node private key](../../Configuring-Pantheon/Node-Keys.md#node-private-key). |
||||
|
||||
Private transactions are processed as illustrated and described below. |
||||
|
||||
 |
||||
|
||||
1. A private transaction is submitted using [eea_sendRawTransaction](../../Reference/Pantheon-API-Methods.md#eea_sendrawtransaction). |
||||
The signed transaction includes transaction attributes that are specific to private transactions: |
||||
|
||||
* `privateFor` or `privacyGroupId` specifies the list of recipients |
||||
* `privateFrom` specifies the sender |
||||
* `restriction` specifies the transaction is of type [_restricted_](Privacy-Overview.md#private-transactions) |
||||
|
||||
1. The JSON-RPC endpoint passes the private transaction to the Private Transaction Handler. |
||||
|
||||
1. The Private Transaction Handler sends the private transaction to Orion. |
||||
|
||||
1. Orion distributes the private transaction directly (that is, point-to-point) to the Orion nodes specified |
||||
in `privateFor` or belonging to the privacy group identified by `privacyGroupId`. All recipient Orion nodes store the transaction. |
||||
The stored transaction is associated with the transaction hash and privacy group ID. |
||||
|
||||
1. Orion returns the transaction hash to the Private Transaction Handler. |
||||
|
||||
1. The Private Transaction Handler creates a [Privacy Marker Transaction](Privacy-Overview.md#privacy-concepts) for the private |
||||
transaction. The Privacy Marker Transaction is propagated using devP2P in the same way as a public Ethereum transaction. |
||||
|
||||
1. The Privacy Marker Transaction is mined into a block and distributed to all Ethereum nodes in the network. |
||||
|
||||
1. The Mainnet Transaction Processor processes the Privacy Marker Transaction in the same way as any other public transaction. |
||||
On nodes that contain the privacy precompile contract specified in the `to` attribute of the Privacy Marker Transaction, |
||||
the Privacy Marker Transaction is passed to the privacy precompile contract. |
||||
|
||||
!!! note |
||||
Nodes receiving the Privacy Marker Transaction that do not contain the privacy precompile contract |
||||
specified in the Privacy Marker Transaction ignore the Privacy Marker Transaction. |
||||
|
||||
1. The privacy precompile contract queries Orion for the private transaction and privacy group ID using the |
||||
transaction hash. |
||||
|
||||
1. The privacy precompile contract passes the private transaction to the Private Transaction Processor. |
||||
The privacy group ID specifies the private world state to use. |
||||
|
||||
1. The Private Transaction Processor executes the transaction. The Private Transaction Processor can read and write to |
||||
the private world state, and read from the public world state. |
||||
|
||||
!!! important |
||||
For production systems requiring private transactions, we recommend using a network |
||||
with a consensus mechanism supporting transaction finality. For example, [IBFT 2.0](../../Consensus-Protocols/IBFT.md). |
||||
@ -1,16 +0,0 @@ |
||||
description: Methods for accessing and managing private transactions and privacy groups |
||||
<!--- END of page meta data --> |
||||
|
||||
# Accessing Private and Privacy Marker Transactions |
||||
|
||||
A private transaction creates a [Privacy Marker Transaction](../Explanation/Private-Transaction-Processing.md) in addition to the private transaction itself. |
||||
Use [`eth_getTransactionReceipt`](../../Reference/Pantheon-API-Methods.md#eth_gettransactionreceipt) to |
||||
get the transaction receipt for the Privacy Maker Transaction and [`eea_getTransactionReceipt`](../../Reference/Pantheon-API-Methods.md#eea_gettransactionreceipt) |
||||
to get the transaction receipt for the private transaction. |
||||
|
||||
With the transaction hash returned when submitting the private transaction, use: |
||||
|
||||
* [`eth_getTransactionByHash`](../../Reference/Pantheon-API-Methods.md#eth_gettransactionbyhash) to |
||||
get the Privacy Marker Transaction . |
||||
* [`priv_getPrivateTransaction`](../../Reference/Pantheon-API-Methods.md#priv_getprivatetransaction) |
||||
to get the private transaction. |
||||
@ -1,15 +0,0 @@ |
||||
description: Creating and manage privacy groups |
||||
<!--- END of page meta data --> |
||||
|
||||
Pantheon-extended privacy provides JSON-RPC API methods for creating and managing privacy groups: |
||||
|
||||
* [`priv_createPrivacyGroup`](../../Reference/Pantheon-API-Methods.md#priv_createprivacygroup) |
||||
* [`priv_findPrivacyGroup`](../../Reference/Pantheon-API-Methods.md#priv_findprivacygroup) |
||||
* [`priv_deletePrivacyGroup`](../../Reference/Pantheon-API-Methods.md#priv_deleteprivacygroup) |
||||
|
||||
!!! tip |
||||
[EEA-compliant privacy groups](../Explanation/Privacy-Groups.md) can be found and deleted using |
||||
[`priv_findPrivacyGroup`](../../Reference/Pantheon-API-Methods.md#priv_findprivacygroup) |
||||
and [`priv_deletePrivacyGroup`](../../Reference/Pantheon-API-Methods.md#priv_deleteprivacygroup) but |
||||
future functionality to update group membership will only be available for privacy groups |
||||
created using [`priv_createPrivacyGroup`](../../Reference/Pantheon-API-Methods.md#priv_createprivacygroup). |
||||
@ -1,24 +0,0 @@ |
||||
description: Creating and sending private transactions |
||||
<!--- END of page meta data --> |
||||
|
||||
# Creating and Sending Private Transactions |
||||
|
||||
Create and send private transactions using: |
||||
|
||||
* [web3.js-eea client library](eeajs.md) or [web3j client library](https://github.com/web3j/web3j) |
||||
* [`eea_sendTransaction` with EthSigner](https://docs.ethsigner.pegasys.tech/en/latest/Using-EthSigner/Using-EthSigner/) |
||||
* [`eea_sendRawTransaction`](../../Reference/Pantheon-API-Methods.md#eea_sendrawtransaction) |
||||
|
||||
!!! note |
||||
Private transactions either deploy contracts or call contract functions. |
||||
Ether transfer transactions cannot be private. |
||||
|
||||
Separate private states are maintained for each [privacy group](../Explanation/Privacy-Groups.md) so |
||||
the account nonce for an account is specific to the privacy group. That is, the nonce for account A for |
||||
privacy group ABC is different to the account nonce for account A for privacy group AB. Use |
||||
[`priv_getTransactionCount`](../../Reference/Pantheon-API-Methods.md#priv_gettransactioncount) to get |
||||
the account nonce for an account for the specified privacy group. |
||||
|
||||
!!! note |
||||
If sending more than 1 transaction to be mined in the same block (that is, you're not waiting for |
||||
the transaction receipt), you must calculate the private transaction nonce outside Pantheon. |
||||
@ -1,39 +0,0 @@ |
||||
description: JSON-RPC methods to use for EEA-compliant privacy |
||||
<!--- END of page meta data --> |
||||
|
||||
# Using EEA-compliant Privacy |
||||
|
||||
When using [EEA-compliant privacy](../Explanation/Privacy-Groups.md), the group of nodes specified by `privateFrom`and `privateFor` form a privacy group and are given a unique |
||||
privacy group ID by Orion. |
||||
|
||||
Enable the [`EEA` API methods](../../Reference/Pantheon-API-Methods.md#eea-methods) using the [`--rpc-http-api`](../../Reference/Pantheon-CLI-Syntax.md#rpc-http-api) |
||||
or [`--rpc-ws-api`](../../Reference/Pantheon-CLI-Syntax.md#rpc-ws-api) command line options. |
||||
|
||||
Specify `privateFor` when creating the signed transaction passed as an input parameter to [`eea_sendRawTransaction`](../../Reference/Pantheon-API-Methods.md#eea_sendrawtransaction) |
||||
to create an EEA-compliant private transaction. |
||||
|
||||
## Privacy Group Type |
||||
|
||||
Privacy groups created when specifying `privateFrom` and `privateFor` are identified as type `LEGACY` |
||||
when returned by [`priv_findPrivacyGroup`](../../Reference/Pantheon-API-Methods.md#priv_findprivacygroup). |
||||
|
||||
!!! example |
||||
```json |
||||
{ |
||||
"jsonrpc": "2.0", |
||||
"id": 1, |
||||
"result": [ |
||||
{ |
||||
"privacyGroupId": "68/Cq0mVjB8FbXDLE1tbDRAvD/srluIok137uFOaClM=", |
||||
"name": "legacy", |
||||
"description": "Privacy groups to support the creation of groups by privateFor and privateFrom", |
||||
"type": "LEGACY", |
||||
"members": [ |
||||
"g59BmTeJIn7HIcnq8VQWgyh/pDbvbt2eyP0Ii60aDDw=", |
||||
"negmDcN2P4ODpqn/6WkJ02zT/0w0bjhGpkZ8UP6vARk=" |
||||
] |
||||
} |
||||
] |
||||
} |
||||
``` |
||||
|
||||
@ -1,49 +0,0 @@ |
||||
description: Pantheon-extended privacy |
||||
<!--- END of page meta data --> |
||||
|
||||
# Using Pantheon-extended Privacy |
||||
|
||||
Pantheon provides an extended implementation of privacy by allowing a [privacy |
||||
group to be created for a set of participants](../Explanation/Privacy-Groups.md). The privacy group ID |
||||
must be specified when sending private transactions. |
||||
|
||||
Using the [`--rpc-http-api`](../../Reference/Pantheon-CLI-Syntax.md#rpc-http-api) or [`--rpc-ws-api`](../../Reference/Pantheon-CLI-Syntax.md#rpc-ws-api) |
||||
command line options enable: |
||||
|
||||
* [`EEA` API methods](../../Reference/Pantheon-API-Methods.md#eea-methods) |
||||
* [`PRIV` API methods](../../Reference/Pantheon-API-Methods.md#priv-methods) |
||||
|
||||
Use [`priv_createPrivacyGroup`](../../Reference/Pantheon-API-Methods.md#priv_createprivacygroup) to |
||||
create the privacy group containing the recipients of the private transaction. |
||||
|
||||
Specify `privacyGroupId` when creating the signed transaction passed as an input parameter to [`eea_sendRawTransaction`](../../Reference/Pantheon-API-Methods.md#eea_sendrawtransaction) |
||||
to create an EEA-compliant private transaction. |
||||
|
||||
!!! note |
||||
Support for specifying `privacyGroupId` when using `eea_sendTransaction` with EthSigner will be available in |
||||
a future EthSigner release. |
||||
|
||||
## Privacy Group Type |
||||
|
||||
Privacy groups created using [`priv_createPrivacyGroup`](../../Reference/Pantheon-API-Methods.md#priv_createprivacygroup) |
||||
are identified as type `PANTHEON` when returned by [`priv_findPrivacyGroup`](../../Reference/Pantheon-API-Methods.md#priv_findprivacygroup). |
||||
|
||||
!!! example |
||||
```json |
||||
{ |
||||
"jsonrpc": "2.0", |
||||
"id": 1, |
||||
"result": [ |
||||
{ |
||||
"privacyGroupId": "GpK3ErNO0xF27T0sevgkJ3+4qk9Z+E3HtXYxcKIBKX8=", |
||||
"name": "Group B", |
||||
"description": "Description of Group B", |
||||
"type": "PANTHEON", |
||||
"members": [ |
||||
"negmDcN2P4ODpqn/6WkJ02zT/0w0bjhGpkZ8UP6vARk=", |
||||
"g59BmTeJIn7HIcnq8VQWgyh/pDbvbt2eyP0Ii60aDDw=" |
||||
] |
||||
} |
||||
] |
||||
} |
||||
``` |
||||
@ -1,63 +0,0 @@ |
||||
description: web3.js-eea Client Library |
||||
<!--- END of page meta data --> |
||||
|
||||
# web3.js-eea Client Library |
||||
|
||||
The [web3.js-eea library](https://github.com/PegaSysEng/eeajs) adds an additional property to your web3 |
||||
instance by extending [web3](https://github.com/ethereum/web3.js/). Use the library to create and send |
||||
RLP-encoded transactions using JSON-RPC. |
||||
|
||||
!!! note |
||||
web3.js-eea supports JSON-RPC over HTTP only. |
||||
|
||||
## Prerequisites |
||||
|
||||
- [Node.js (version > 10)](https://nodejs.org/en/download/) |
||||
|
||||
## Add web3.js-eea to Project |
||||
|
||||
```bash |
||||
npm install web3-eea |
||||
``` |
||||
|
||||
## Initialize EEA Client |
||||
|
||||
Initilize your EEA client where: |
||||
|
||||
* `<JSON-RPC HTTP endpoint>` is the JSON-RPC HTTP endpoint of your Pantheon node. Specified by the |
||||
[`--rpc-http-host`](../../Reference/Pantheon-CLI-Syntax.md#rpc-http-host) and [`--rpc-http-port`](../../Reference/Pantheon-CLI-Syntax.md#rpc-http-port) |
||||
command line options. |
||||
* `<chain_id>` is the [chain ID](../../Configuring-Pantheon/NetworkID-And-ChainID.md) of your network. |
||||
|
||||
!!! example |
||||
```js tab="Syntax" |
||||
const EEAClient = require("web3-eea"); |
||||
const web3 = new EEAClient(new Web3("<JSON-RPC HTTP endpoint>"), <chain_id>); |
||||
``` |
||||
|
||||
```js tab="Example" |
||||
const EEAClient = require("web3-eea"); |
||||
const web3 = new EEAClient(new Web3("http://localhost:8545"), 2018); |
||||
``` |
||||
|
||||
## Deploying a Contract with sendRawTransaction |
||||
|
||||
To deploy a private contract, you need the contract binary. You can use [Solidity](https://solidity.readthedocs.io/en/develop/using-the-compiler.html) |
||||
to get the contract binary. |
||||
|
||||
!!! example "Deploying a Contract with sendRawTransaction" |
||||
```js |
||||
const contractOptions = { |
||||
data: `0x123`, // contract binary |
||||
privateFrom: "orionNode1PublicKey", |
||||
privateFor: ["orionNode3PublicKey"], |
||||
privateKey: "pantheonNode1PrivateKey" |
||||
}; |
||||
return web3.eea.sendRawTransaction(contractOptions); |
||||
``` |
||||
|
||||
The transaction hash is returned. To get the private transaction receipt, use `web3.eea.getTransactionReceipt(txHash)`. |
||||
|
||||
## web3.js-eea Methods |
||||
|
||||
Refer to the [web3.js-eea reference documentation](../../Reference/web3js-eea-Methods.md). |
||||
@ -1,100 +0,0 @@ |
||||
description: web3.js-eea client library multinode example |
||||
<!--- END of page meta data --> |
||||
|
||||
# Using Multinode Example in web3.js-eea Client Library |
||||
|
||||
To use the examples provided in EEA JS library with [your privacy network](Configuring-Privacy.md): |
||||
|
||||
1. Clone the **PegaSysEng/eeajs** repository: |
||||
```bash |
||||
git clone https://github.com/PegaSysEng/eeajs.git |
||||
``` |
||||
|
||||
1. In the `eeajs` directory: |
||||
```bash |
||||
npm install |
||||
``` |
||||
|
||||
1. In the `example` directory, update the `keys.js` file to include: |
||||
* Orion node public keys |
||||
* Pantheon node RPC URLs |
||||
* Pantheon node private keys |
||||
|
||||
1. If the `chainID` specified in the genesis file for your network is not `2018`, update `deployContract.js`, |
||||
`storeValueFromNode1.js`, and `storeValueFromNode2.js` to specify your chain ID instead of `2018`. |
||||
|
||||
1. In the `example/multiNodeExample` directory, deploy the contract: |
||||
```bash |
||||
node deployContract.js |
||||
``` |
||||
|
||||
A private transaction receipt is returned. |
||||
|
||||
``` |
||||
Transaction Hash 0x23b57ddc3ecf9c9a548e4401a411420ffc0002fd259a86d5656add7c6108beeb |
||||
Waiting for transaction to be mined ... |
||||
Private Transaction Receipt |
||||
{ contractAddress: '0xfee84481da8f4b9a998dfacb38091b3145bb01ab', |
||||
from: '0x9811ebc35d7b06b3fa8dc5809a1f9c52751e1deb', |
||||
to: null, |
||||
output: |
||||
'0x6080604052600436106100565763ffffffff7c01000000000000000000000000000000000000000000000000000000006000350416633fa4f245811461005b5780636057361d1461008257806367e404ce146100ae575b600080fd5b34801561006757600080fd5b506100706100ec565b60408051918252519081900360200190f35b34801561008e57600080fd5b506100ac600480360360208110156100a557600080fd5b50356100f2565b005b3480156100ba57600080fd5b506100c3610151565b6040805173ffffffffffffffffffffffffffffffffffffffff9092168252519081900360200190f35b60025490565b604080513381526020810183905281517fc9db20adedc6cf2b5d25252b101ab03e124902a73fcb12b753f3d1aaa2d8f9f5929181900390910190a16002556001805473ffffffffffffffffffffffffffffffffffffffff191633179055565b60015473ffffffffffffffffffffffffffffffffffffffff169056fea165627a7a72305820c7f729cb24e05c221f5aa913700793994656f233fe2ce3b9fd9a505ea17e8d8a0029', |
||||
logs: [] } |
||||
``` |
||||
|
||||
1. Copy the contract address from the private transaction receipt and set the `CONTRACT_ADDRESS` environment variable: |
||||
|
||||
```bash |
||||
export CONTRACT_ADDRESS=<Contract Address from Private Transaction Receipt> |
||||
``` |
||||
|
||||
!!! example |
||||
```bash |
||||
export CONTRACT_ADDRESS=0xfee84481da8f4b9a998dfacb38091b3145bb01ab |
||||
``` |
||||
|
||||
1. Store a value in the contract from Node 1: |
||||
```bash |
||||
node storeValueFromNode1.js |
||||
``` |
||||
|
||||
The value of 1000 (3e8 in hex) is stored by Node 1 and is visible to Node 1 and Node 2. |
||||
|
||||
```bash |
||||
Transaction Hash: 0xd9d71cc6f64675e1a48183ded8f08930af317eb883ebae4c4eec66ae68618d85 |
||||
Waiting for transaction to be mined ... |
||||
Event Emited: 0x0000000000000000000000009811ebc35d7b06b3fa8dc5809a1f9c52751e1deb00000000000000000000000000000000000000000000000000000000000003e8 |
||||
Waiting for transaction to be mined ... |
||||
Get Value from http://localhost:8545: 0x00000000000000000000000000000000000000000000000000000000000003e8 |
||||
Waiting for transaction to be mined ... |
||||
Get Value from http://localhost:8546: 0x00000000000000000000000000000000000000000000000000000000000003e8 |
||||
Waiting for transaction to be mined ... |
||||
Get Value from http://localhost:8547: 0x |
||||
``` |
||||
|
||||
7. Store a value in the contract from Node 2: |
||||
```bash |
||||
node storeValueFromNode2.js |
||||
``` |
||||
|
||||
The value of 42 (2a in hex) is stored by Node 1 and is visible to Node 1 and Node 2. |
||||
|
||||
```bash |
||||
Transaction Hash: 0xa025433aec47a71b0230f12f43708812fd38ff7b7c1dc89a715f71dcbd5fbdbf |
||||
Waiting for transaction to be mined ... |
||||
Event Emited: 0x000000000000000000000000372a70ace72b02cc7f1757183f98c620254f9c8d000000000000000000000000000000000000000000000000000000000000002a |
||||
Waiting for transaction to be mined ... |
||||
Get Value from http://localhost:8545: 0x000000000000000000000000000000000000000000000000000000000000002a |
||||
Waiting for transaction to be mined ... |
||||
Get Value from http://localhost:8546: 0x000000000000000000000000000000000000000000000000000000000000002a |
||||
Waiting for transaction to be mined ... |
||||
Get Value from http://localhost:8547: 0x |
||||
``` |
||||
|
||||
!!! note |
||||
The Node 3 Orion log messages indicate payloads cannot be found. This is expected behaviour |
||||
because Node 3 does not have access to the private transactions between Node 1 and Node 2. |
||||
|
||||
|
||||
|
||||
|
||||
@ -0,0 +1,5 @@ |
||||
Pantheon user documentation was moved to as separate repository to help manage versions and releases. |
||||
|
||||
If you want to contribute to the doc site, make a pull request against https://github.com/PegaSysEng/doc.pantheon |
||||
|
||||
The generated doc website is at https://docs.pantheon.pegasys.tech/ |
||||
File diff suppressed because it is too large
Load Diff
@ -1,200 +0,0 @@ |
||||
description: Pantheon API objects reference |
||||
<!--- END of page meta data --> |
||||
|
||||
# Pantheon API Objects |
||||
|
||||
The following objects are parameters for or returned by Pantheon API Methods. |
||||
|
||||
## Block Object |
||||
|
||||
Returned by [eth_getBlockByHash](Pantheon-API-Methods.md#eth_getblockbyhash) and [eth_getBlockByNumber](Pantheon-API-Methods.md#eth_getblockbynumber). |
||||
|
||||
| Key | Type | Value | |
||||
|----------------------|:---------------------:|----------------------------------------------------------------------------------------------------------------------------------| |
||||
| **number** | *Quantity*, Integer | Block number. `null` when block is pending. | |
||||
| **hash** | *Data*, 32 bytes | Hash of the block. `null` when block is pending. | |
||||
| **parentHash** | *Data*, 32 bytes | Hash of the parent block. | |
||||
| **nonce** | *Data*, 8 bytes | Hash of the generated proof of work. `null` when block is pending. | |
||||
| **sha3Uncles** | *Data*, 32 bytes | SHA3 of the uncle's data in the block. | |
||||
| **logsBloom** | *Data*, 256 bytes | Bloom filter for the block logs. `null` when block is pending. | |
||||
| **transactionsRoot** | *Data*, 32 bytes | Root of the transaction trie for the block. | |
||||
| **stateRoot** | Data, 32 bytes | Root of the final state trie for the block. | |
||||
| **receiptsRoot** | Data, 32 bytes | Root of the receipts trie for the block. | |
||||
| **miner** | Data, 20 bytes | Address to which mining rewards were paid. | |
||||
| **difficulty** | Quantity, Integer | Difficulty for this block. | |
||||
| **totalDifficulty** | Quantity, Integer | Total difficulty of the chain until this block. | |
||||
| **extraData** | Data | Extra data field of this block. | |
||||
| **size** | Quantity, Integer | Size of block in bytes. | |
||||
| **gasLimit** | Quantity | Maximum gas allowed in this block. | |
||||
| **gasUsed** | Quantity | Total gas used by all transactions in this block. | |
||||
| **timestamp** | Quantity | Unix timestamp when block was collated. | |
||||
| **transactions** | Array | Array of [transaction objects](#transaction-object), or 32 byte transaction hashes depending on the specified boolean parameter. | |
||||
| **uncles** | Array | Array of uncle hashes. | |
||||
|
||||
|
||||
## Filter Options Object |
||||
|
||||
Parameter for [eth_newFilter](Pantheon-API-Methods.md#eth_newfilter) and [eth_getLogs](Pantheon-API-Methods.md#eth_getlogs). Used to [filter logs](../Using-Pantheon/Accessing-Logs-Using-JSON-RPC.md). |
||||
|
||||
| Key | Type | Required/Optional | Value | |
||||
|---------------|:---------------------------------:|:-----------------:|---------------------------------------------------------------------------------------------------------------------------------------------| |
||||
| **fromBlock** | Quantity | Tag | Optional | Integer block number or `latest`, `pending`, `earliest`. See [Block Parameter](../Pantheon-API/Using-JSON-RPC-API.md#block-parameter). Default is `latest`. | |
||||
| **toBlock** | Quantity | Tag | Optional | Integer block number or `latest`, `pending`, `earliest`. See [Block Parameter](../Pantheon-API/Using-JSON-RPC-API.md#block-parameter). Default is `latest`. | |
||||
| **address** | Data | Array | Optional | Contract address or array of addresses from which [logs](../Using-Pantheon/Events-and-Logs.md) originate. | |
||||
| **topics** | Array of Data, 32 bytes each | Optional | Array of topics by which to [filter logs](../Using-Pantheon/Events-and-Logs.md#topic-filters). | |
||||
|
||||
[eth_getLogs](Pantheon-API-Methods.md#eth_getlogs) has an additional key. |
||||
|
||||
| Key | Type | Required/Optional | Value | |
||||
|------------|:-----------------:|:-----------------:|------| |
||||
| **blockhash** |Data, 32 bytes | Optional | Hash of block for which to return logs. If `blockhash` is specified, `fromBlock` and `toBlock` cannot be specified. | |
||||
|
||||
## Log Object |
||||
|
||||
Returned by [eth_getFilterChanges](Pantheon-API-Methods.md#eth_getfilterchanges) and [transaction receipt objects](#transaction-receipt-object) can contain an array of log objects. |
||||
|
||||
| Key | Type | Value | |
||||
|----------------------|-:- :------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| |
||||
| **removed** | Tag | `true` when log removed due to chain reorganization. `false` if valid log. | |
||||
| **logIndex** | Quantity, Integer | Log index position in the block. `null` when log is pending. | |
||||
| **transactionIndex** | Quantity, Integer | Index position of transaction from which log was created. `null` when log is pending. | |
||||
| **transactionHash** | Data, 32 bytes | Hash of transaction from which log was created. `null` when log is pending. | |
||||
| **blockHash** | Data, 32 bytes | Hash of block in which log included. `null` when log is pending. | |
||||
| **blockNumber** | Quantity | Number of block in which log included. `null` when log is pending. | |
||||
| **address** | Data, 20 bytes | Address from which log originated. | |
||||
| **data** | Data | Non-indexed arguments of log. | |
||||
| **topics** | Array of Data, 32 bytes each | [Event signature hash](../Using-Pantheon/Events-and-Logs.md#event-signature-hash) and 0 to 3 [indexed log arguments](../Using-Pantheon/Events-and-Logs.md#event-parameters). | |
||||
|
||||
## Private Transaction Object |
||||
|
||||
Returned by [priv_getPrivateTransaction](Pantheon-API-Methods.md#priv_getprivatetransaction). |
||||
|
||||
| Key | Type | Value | |
||||
|----------------------|-:-:-------------------------------|---------------------------------------------------------------------------------| |
||||
| **from** | Data, 20 bytes | Address of the sender. | |
||||
| **gas** | Quantity | Gas provided by the sender. | |
||||
| **gasPrice** | Quantity | Gas price provided by the sender in Wei. | |
||||
| **hash** | Data, 32 bytes | Hash of the transaction. | |
||||
| **input** | Data | Data to create or invoke contract. | |
||||
| **nonce** | Quantity | Number of transactions made by the sender to the privacy group before this one. | |
||||
| **to** | Data, 20 bytes | `null` if a contract creation transaction; otherwise, contract address | |
||||
| **value** | Quantity | `null` because private transactions cannot transfer Ether | |
||||
| **v** | Quantity | ECDSA Recovery ID | |
||||
| **r** | Data, 32 bytes | ECDSA signature r | |
||||
| **s** | Data, 32 bytes | ECDSA signature s | |
||||
| **privateFrom** | Data, 32 bytes | [Orion](https://docs.orion.pegasys.tech/en/stable/) public key of sender | |
||||
| **privateFor** | Array of Data, 32 bytes each | [Orion](https://docs.orion.pegasys.tech/en/stable/) public keys of recipients | |
||||
| **restriction** | String | Must be [`restricted`](../Privacy/Explanation/Privacy-Overview.md#private-transaction-attributes) |
||||
|
||||
## Range Object |
||||
|
||||
Returned by [debug_storageRangeAt](Pantheon-API-Methods.md#debug_storagerangeat). |
||||
|
||||
| Key | Type | Value | |
||||
|-----------------|:-------:|-------------------------------------------------------------------| |
||||
| **storage** | Object | Key hash and value. Preimage key is always null | |
||||
| **nextKey** | Hash | Hash of next key if further storage in range. Otherwise, not included | |
||||
|
||||
|
||||
### Structured Log Object |
||||
|
||||
Log information returned as part of the [Trace object](#trace-object). |
||||
|
||||
| Key | Type | Value | |
||||
|----------------------------|:----------------------------:|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| |
||||
| **pc** | Integer | Current program counter | |
||||
| **op** | String | Current OpCode | |
||||
| **gas** | Integer | Gas remaining | |
||||
| **gasCost** | Integer | Cost in wei of each gas unit | |
||||
| **depth** | Integer | Execution depth | |
||||
| **exceptionalHaltReasons** | Array | One or more strings representing an error condition that caused the EVM execution to terminate. These indicate that EVM execution terminated for reasons such as running out of gas or attempting to execute an unknown instruction. Generally a single exceptional halt reason is returned but it is possible for more than one to occur at once. | |
||||
| **stack** | Array of 32 byte arrays | EVM execution stack before executing current operation | |
||||
| **memory** | Array of 32 byte arrays | Memory space of the contract before executing current operation | |
||||
| **storage** | Object | Storage entries changed by the current transaction | |
||||
|
||||
## Trace Object |
||||
|
||||
Returned by [debug_traceBlock](Pantheon-API-Methods.md#debug_traceblock), [debug_traceBlockByHash](Pantheon-API-Methods.md#debug_traceblockbyhash), |
||||
[debug_traceBlockByNumber](Pantheon-API-Methods.md#debug_traceblockbynumber), and [debug_traceTransaction](Pantheon-API-Methods.md#debug_tracetransaction). |
||||
|
||||
| Key | Type | Value | |
||||
|-----------------|:-------:|-------------------------------------------------------------------| |
||||
| **gas** | Integer | Gas used by the transaction | |
||||
| **failed** | Boolean | True if transaction failed; otherwise, false | |
||||
| **returnValue** | String | Bytes returned from transaction execution (without a `0x` prefix) | |
||||
| **structLogs** | Array | Array of structured log objects | |
||||
|
||||
## Transaction Object |
||||
|
||||
Returned by [eth_getTransactionByHash](Pantheon-API-Methods.md#eth_gettransactionbyhash), [eth_getTransactionByBlockHashAndIndex](Pantheon-API-Methods.md#eth_gettransactionbyblockhashandindex), and [eth_getTransactionsByBlockNumberAndIndex](Pantheon-API-Methods.md#eth_gettransactionbyblocknumberandindex). |
||||
|
||||
| Key | Type | Value | |
||||
|----------------------|:-------------------:|----------------------------------------------------------------------------------------| |
||||
| **blockHash** | Data, 32 bytes | Hash of block containing this transaction. `null` when transaction is pending. | |
||||
| **blockNumber** | Quantity | Block number of block containing this transaction. `null` when transaction is pending. | |
||||
| **from** | Data, 20 bytes | Address of the sender. | |
||||
| **gas** | Quantity | Gas provided by the sender. | |
||||
| **gasPrice** | Quantity | Gas price provided by the sender in Wei. | |
||||
| **hash** | Data, 32 bytes | Hash of the transaction. | |
||||
| **input** | Data | Data sent with the transaction to create or invoke a contract. For [private transactions](../Privacy/Explanation/Privacy-Overview.md) it is a pointer to the transaction location in [Orion](https://docs.orion.pegasys.tech/en/stable/). | |
||||
| **nonce** | Quantity | Number of transactions made by the sender before this one. | |
||||
| **to** | Data, 20 bytes | Address of the receiver. `null` if a contract creation transaction. | |
||||
| **transactionIndex** | Quantity, Integer | Index position of transaction in the block. `null` when transaction is pending. | |
||||
| **value** | Quantity | Value transferred in Wei. | |
||||
| **v** | Quantity | ECDSA Recovery ID | |
||||
| **r** | Data, 32 bytes | ECDSA signature r | |
||||
| **s** | Data, 32 bytes | ECDSA signature s | |
||||
|
||||
## Transaction Call Object |
||||
|
||||
Parameter for [eth_call](Pantheon-API-Methods.md#eth_call) and [eth_estimateGas](Pantheon-API-Methods.md#eth_estimategas). |
||||
|
||||
!!!note |
||||
All parameters are optional for [eth_estimateGas](Pantheon-API-Methods.md#eth_estimategas) |
||||
|
||||
| Key | Type | Required/Optional | Value | |
||||
|--------------|:-------------------:|:-----------------:|------------------------------------------------------------------------------------------------------------------------------------------------------------------------| |
||||
| **from** | Data, 20 bytes | Optional | Address from which transaction is sent. | |
||||
| **to** | Data, 20 bytes | Required | Address to which transaction is directed. | |
||||
| **gas** | Quantity, Integer | Optional | Gas provided for the transaction execution. `eth_call` consumes zero gas, but this parameter might be needed by some executions. `eth_estimateGas` ignores this value. | |
||||
| **gasPrice** | Quantity, Integer | Optional | Price used for each paid gas. | |
||||
| **value** | Quantity, Integer | Optional | Value sent with this transaction. | |
||||
| **data** | Data | Optional | Hash of the method signature and encoded parameters. For details, see [Ethereum Contract ABI](https://github.com/ethereum/wiki/wiki/Ethereum-Contract-ABI). | |
||||
|
||||
## Transaction Receipt Object |
||||
|
||||
Returned by [eth_getTransactionReceipt](Pantheon-API-Methods.md#eth_gettransactionreceipt). |
||||
|
||||
| Key | Type | Value | |
||||
|-----------------------|:--------------------:|--------------------------------------------------------------------------------------| |
||||
| **blockHash** | Data, 32 bytes | Hash of block containing this transaction. | |
||||
| **blockNumber** | Quantity | Block number of block containing this transaction. | |
||||
| **contractAddress** | Data, 20 bytes | Contract address created, if contract creation transaction; otherwise, `null`. | |
||||
| **cumulativeGasUsed** | Quantity | Total amount of gas used by previous transactions in the block and this transaction. | |
||||
| **from** | Data, 20 bytes | Address of the sender. | |
||||
| **gasUsed** | Quantity | Amount of gas used by this specific transaction. | |
||||
| **logs** | Array | Array of [log objects](#log-object) generated by this transaction. | |
||||
| **logsBloom** | Data, 256 bytes | Bloom filter for light clients to quickly retrieve related logs. | |
||||
| **status** | Quantity | Either `1` (success) or `0` (failure) | |
||||
| **to** | Data, 20 bytes | Address of the receiver, if sending ether; otherwise, null. | |
||||
| **transactionHash** | Data, 32 bytes | Hash of the transaction. | |
||||
| **transactionIndex** | Quantity, Integer | Index position of transaction in the block. | |
||||
|
||||
!!!note |
||||
For pre-Byzantium transactions, the transaction receipt object includes the following instead of `status`: |
||||
|
||||
| Key | Type | Value | |
||||
|-------|:-----------------:|---------| |
||||
| **root** | Data, 32 bytes| Post-transaction stateroot| |
||||
|
||||
## Private Transaction Receipt Object |
||||
|
||||
Returned by [eea_getTransactionReceipt](Pantheon-API-Methods.md#eea_gettransactionreceipt). |
||||
|
||||
| Key | Type | Value | |
||||
|-----------------------|:--------------------:|--------------------------------------------------------------------------------------| |
||||
| **contractAddress** | Data, 20 bytes | Contract address created, if contract creation transaction; otherwise, `null`. | |
||||
| **from** | Data, 20 bytes | Address of the sender. | |
||||
| **to** | Data, 20 bytes | Address of the receiver, if sending ether; otherwise, null. | |
||||
| **output** | Data | RLP-encoded return value of a contract call, if value is returned; otherwise, `null`.| |
||||
| **logs** | Array | Array of [log objects](#log-object) generated by this transaction. | |
||||
File diff suppressed because it is too large
Load Diff
@ -1,248 +0,0 @@ |
||||
description: web3js-eea methods reference |
||||
<!--- END of page meta data --> |
||||
|
||||
# web3js-eea |
||||
|
||||
Use the [web3.js-eea library](https://github.com/PegaSysEng/eeajs) to [create and send |
||||
private transactions](../Privacy/How-To/Creating-Sending-Private-Transactions.md). |
||||
|
||||
## Options Parameter |
||||
|
||||
The Options parameter has the following properties: |
||||
|
||||
* `privateKey`: Ethereum private key with which to sign the transaction |
||||
* `privateFrom` : Orion public key of the sender |
||||
* [`privateFor` : Orion public keys of recipients or `privacyGroupId`: Privacy group to receive the transaction](../Privacy/Explanation/Privacy-Groups.md) |
||||
* `nonce` : Optional. If not provided, calculated using [`eea_getTransctionCount`](../Reference/Pantheon-API-Methods.md). |
||||
* `to` : Optional. Contract address to send the transaction to. Do not specify for contract deployment transactions |
||||
* `data` : Transaction data |
||||
|
||||
## createPrivacyGroup |
||||
|
||||
Creates privacy group for Pantheon privacy. |
||||
|
||||
**Parameters** |
||||
|
||||
[Transaction options](#options-parameter) |
||||
|
||||
`name` : `string` - Name of the privacy group. Optional. |
||||
|
||||
`description` : `string` - Name of the privacy group. Optional. |
||||
|
||||
**Returns** |
||||
|
||||
`string` : Privacy group ID |
||||
|
||||
!!! example |
||||
```bash |
||||
const createPrivacyGroup = () => { |
||||
const contractOptions = { |
||||
addresses: [orion.node1.publicKey, orion.node2.publicKey], |
||||
name: "Privacy Group A", |
||||
description: "Members of Group A" |
||||
}; |
||||
return web3.eea.createPrivacyGroup(contractOptions).then(result => { |
||||
console.log(`The privacy group created is:`, result); |
||||
return result; |
||||
}); |
||||
}; |
||||
``` |
||||
|
||||
## deletePrivacyGroup |
||||
|
||||
Deletes privacy group. |
||||
|
||||
**Parameters** |
||||
|
||||
[Transaction options](#options-parameter) |
||||
|
||||
**Returns** |
||||
|
||||
`string` : Privacy group ID |
||||
|
||||
!!! example |
||||
```bash |
||||
const deletePrivacyGroup = givenPrivacyGroupId => { |
||||
const contractOptions = { |
||||
privacyGroupId: givenPrivacyGroupId |
||||
}; |
||||
return web3.eea.deletePrivacyGroup(contractOptions).then(result => { |
||||
console.log(`The privacy group deleted is:`, result); |
||||
return result; |
||||
}); |
||||
}; |
||||
``` |
||||
|
||||
## findPrivacyGroup |
||||
|
||||
Finds privacy groups containing only the specified members. |
||||
|
||||
**Parameters** |
||||
|
||||
[Transaction options](#options-parameter) |
||||
|
||||
**Returns** |
||||
|
||||
`array of objects` : Privacy groups containing only the specified members. |
||||
|
||||
!!! example |
||||
```bash |
||||
const findPrivacyGroup = () => { |
||||
const contractOptions = { |
||||
addresses: [orion.node1.publicKey, orion.node2.publicKey] |
||||
}; |
||||
return web3.eea.findPrivacyGroup(contractOptions).then(result => { |
||||
console.log(`The privacy groups found are:`, result); |
||||
return result; |
||||
}); |
||||
}; |
||||
``` |
||||
|
||||
## generatePrivacyGroup |
||||
|
||||
Generates the privacy group ID for [EEA privacy](../Privacy/Explanation/Privacy-Groups.md#eea-compliant-privacy). |
||||
The privacy group ID is the RLP-encoded `privateFor` and `privateFrom` keys. |
||||
|
||||
**Parameters** |
||||
|
||||
[Transaction options](#options-parameter) |
||||
|
||||
**Returns** |
||||
|
||||
`string` : Privacy group ID |
||||
|
||||
!!! example |
||||
```bash |
||||
const privacyGroupId = web3.eea.generatePrivacyGroup({ |
||||
privateFrom: "A1aVtMxLCUHmBVHXoZzzBgPbW/wj5axDpW9X8l91SGo=", |
||||
privateFor: ["Ko2bVqD+nNlNYL5EE7y3IdOnviftjiizpjRt+HTuFBs="] |
||||
}); |
||||
``` |
||||
|
||||
## getMarkerTransaction |
||||
|
||||
Gets the [privacy marker transaction](../Privacy/Explanation/Private-Transaction-Processing.md) transaction receipt. |
||||
|
||||
**Parameters** |
||||
|
||||
`txHash` - `string` : Transaction hash of the private transaction |
||||
|
||||
`retries` - `int` : Maximum number of attempts to get the private marker transaction receipt |
||||
|
||||
`delay` - `int` : Delay between retries in milliseconds |
||||
|
||||
**Returns** |
||||
|
||||
Privacy marker transaction receipt |
||||
|
||||
!!! example |
||||
```bash |
||||
const privateMarkerTransacion = web3.eea.getMarkerTransaction("0x9c41b3d44ed73511c82a9e2b1ef581eb797475c82f318ca2802358d3ba4a8274", 5, 100); |
||||
``` |
||||
|
||||
## getTransactionCount |
||||
|
||||
Returns the number of transactions sent from the specified address for the privacy group. |
||||
|
||||
**Parameters** |
||||
|
||||
[Transaction options](#options-parameter) |
||||
|
||||
**Returns** |
||||
|
||||
`int` : Transaction count for that account (`privateKey`) and privacy group |
||||
|
||||
!!! example |
||||
```bash |
||||
return web3.eea |
||||
.getTransactionCount({ |
||||
privateKey: pantheon.node1.privateKey, |
||||
privateFrom: orion.node1.publicKey, |
||||
privateFor: [orion.node2.publicKey], |
||||
}) |
||||
``` |
||||
|
||||
## getTransactionReceipt |
||||
|
||||
Gets the private transaction receipt using [`eea_getTransactionReceipt`](../Reference/Pantheon-API-Methods.md#eea_gettransactionreceipt). |
||||
|
||||
**Parameters** |
||||
|
||||
`txHash` - `string` : Transaction hash of the private transaction |
||||
|
||||
`enclavePublicKey` - `string` : [`privateFrom` key for the transaction](#options-parameter) |
||||
|
||||
`retries` - `int` : Optional. Maximum number of attempts to get the private marker transaction receipt. Default is `300`. |
||||
|
||||
`delay` - `int` : Optional. Delay between retries in milliseconds. Default is `1000`. |
||||
|
||||
**Returns** |
||||
|
||||
Private transaction receipt |
||||
|
||||
!!! example |
||||
```bash |
||||
const privateTxReceipt = web3.eea.getTransactionReceipt("0x9c41b3d44ed73511c82a9e2b1ef581eb797475c82f318ca2802358d3ba4a8274", "A1aVtMxLCUHmBVHXoZzzBgPbW/wj5axDpW9X8l91SGo="); |
||||
``` |
||||
|
||||
## sendRawTransaction |
||||
|
||||
Signs and sends a RLP-encoded private transaction to Pantheon using [`eea_sendRawTransaction`](Pantheon-API-Methods.md#eea_sendrawtransaction). |
||||
|
||||
`sendRawTransaction` supports [EEA-compliant privacy](../Privacy/How-To/EEA-Compliant.md) using `privateFor`, or [Pantheon-extended privacy](../Privacy/How-To/Pantheon-Privacy.md) using `privacyGroupId`. |
||||
|
||||
**Parameters** |
||||
|
||||
[Transaction options](#options-parameter) |
||||
|
||||
**Returns** |
||||
|
||||
`string` : Transaction hash of the [`privacy marker transaction`](../Privacy/Explanation/Private-Transaction-Processing.md) |
||||
|
||||
!!! example "Pantheon-extended Privacy" |
||||
```bash tab="Contract Deployment with privacyGroupId" |
||||
const createPrivateEmitterContract = privacyGroupId => { |
||||
const contractOptions = { |
||||
data: `0x${binary}`, |
||||
privateFrom: orion.node1.publicKey, |
||||
privacyGroupId, |
||||
privateKey: pantheon.node1.privateKey |
||||
}; |
||||
return web3.eea.sendRawTransaction(contractOptions); |
||||
}; |
||||
``` |
||||
|
||||
```bash tab="Contract Invocation with privacyGroupId " |
||||
const functionCall = { |
||||
to: address, |
||||
data: functionAbi.signature, |
||||
privateFrom, |
||||
privacyGroupId, |
||||
privateKey |
||||
}; |
||||
return web3.eea.sendRawTransaction(functionCall); |
||||
``` |
||||
|
||||
!!! example "EEA-compliant Privacy" |
||||
```bash tab="Contract Deployment with privateFor" |
||||
const createPrivateEmitterContract = () => { |
||||
const contractOptions = { |
||||
data: `0x${binary}`, |
||||
privateFrom: orion.node1.publicKey, |
||||
privateFor: [orion.node2.publicKey], |
||||
privateKey: pantheon.node1.privateKey |
||||
}; |
||||
return web3.eea.sendRawTransaction(contractOptions); |
||||
}; |
||||
``` |
||||
|
||||
```bash tab="Contract Invocation with privateFor" |
||||
const functionCall = { |
||||
to: address, |
||||
data: functionAbi.signature + functionArgs, |
||||
privateFrom: orion.node1.publicKey, |
||||
privateFor: [orion.node2.publicKey], |
||||
privateKey: pantheon.node1.privateKey |
||||
}; |
||||
return web3.eea.sendRawTransaction(functionCall); |
||||
``` |
||||
@ -1,36 +0,0 @@ |
||||
description: Pantheon resources including blog posts, webinars, and meetup recordings. |
||||
<!--- END of page meta data --> |
||||
|
||||
# Pantheon Resources |
||||
|
||||
## Blog Posts |
||||
|
||||
[Privacy in Pantheon: How It Works and Why Your Enterprise Should Care](https://pegasys.tech/privacy-in-pantheon-how-it-works-and-why-your-enterprise-should-care/) |
||||
|
||||
[Permissioning Features in Pantheon](https://pegasys.tech/protecting-the-enterprise-permissioning-features-in-pantheon/) |
||||
|
||||
[Another day, another consensus algorithm. Why IBFT 2.0?](https://pegasys.tech/another-day-another-consensus-algorithm-why-ibft-2-0/) |
||||
|
||||
[Why We Rebuilt Ethereum from Scratch](https://media.consensys.net/why-we-rebuilt-ethereum-from-scratch-9e38b6ebd4a2) |
||||
|
||||
[Why Java for Blockchain](https://media.consensys.net/why-java-for-blockchain-73f1b444c2d) |
||||
|
||||
## Webinars |
||||
|
||||
<<<<<<< HEAD |
||||
<<<<<<< HEAD |
||||
[Permissioning in Blockchain: A Technical Look at Benefits and Best Practices](https://pegasys.wistia.com/medias/3px9eo2sf5) |
||||
======= |
||||
[Permissioning in Blockchain: A Technical Look at Benefits and Best Practices](https://www.youtube.com/watch?v=CD0pHtNDqZs) |
||||
>>>>>>> a4bb4af0dfc8ca9e7b97720aa8ef47e330d7f903 |
||||
======= |
||||
[Permissioning in Blockchain: A Technical Look at Benefits and Best Practices](https://www.youtube.com/watch?v=CD0pHtNDqZs) |
||||
>>>>>>> 5728373ded70eebb57dbb6360d18a1275ebe4953 |
||||
|
||||
[Privacy in Pantheon: How PegaSys Redefined Blockchain for Enterprises](https://www.youtube.com/watch?v=8l7SSZLyFL8) |
||||
|
||||
[The Final Word: IBFT 2.0 and Enterprise Consensus](https://www.youtube.com/watch?v=YmTUP_dWfME) |
||||
|
||||
[De-Mystifying Pantheon: Understanding an Ethereum Codebase](https://www.youtube.com/watch?v=OJfib9kTK7U&feature=youtu.be) |
||||
|
||||
[Getting Started with Pantheon](https://www.youtube.com/watch?v=OKWBr94J9rY&t=1s) |
||||
@ -1,98 +0,0 @@ |
||||
description: Frequently asked questions FAQ and answers for troubleshooting Pantheon |
||||
<!--- END of page meta data --> |
||||
|
||||
# Troubleshooting |
||||
|
||||
If Pantheon is not working as expected, here are some things to check or try. |
||||
|
||||
## Supplied Genesis Block Does Not Match Stored Chain Data |
||||
|
||||
If you get a `Supplied genesis block does not match stored chain data` error, use the genesis file which matches the genesis block |
||||
of the data directory or use the [`--data-path`](../Reference/Pantheon-CLI-Syntax.md#data-path) option to specify a different data directory. |
||||
|
||||
## Host Not Authorized |
||||
|
||||
If you are receiving a `Host not authorized` error when attempting to access the JSON-RPC API, ensure [`--host-whitelist`](../Reference/Pantheon-CLI-Syntax.md#host-whitelist) |
||||
includes the host from which you are sending the RPC or `*`. |
||||
|
||||
## Peers Fail to Connect |
||||
|
||||
If nodes are not communicating, ensure the [required ports are open](https://docs.pantheon.pegasys.tech/en/stable/Configuring-Pantheon/Networking/Configuring-Ports/). |
||||
|
||||
If your nodes are running in AWS, check you have appropriate `SecurityGroups` to allow access to the required ports. |
||||
|
||||
Check the [enode URLs](../Configuring-Pantheon/Node-Keys.md#enode-url) specified for [bootnodes](../Configuring-Pantheon/Networking#bootnodes) |
||||
or [static nodes](../Configuring-Pantheon/Networking/Managing-Peers.md#static-nodes) match the enode URLs |
||||
displayed when the remote nodes are started. |
||||
|
||||
## Mining |
||||
|
||||
Check blocks are being created. On mining nodes, log messages indicate blocks are being created. |
||||
|
||||
```bash |
||||
2019-05-08 20:28:27.026+10:00 | pool-10-thread-1 | INFO | IbftRound | Importing block to chain. round=ConsensusRoundIdentifier{Sequence=660, Round=0}, hash=0x759afaba4e923d89175d850ceca4b8ef81f7d9c727b0b0b8e714b624a4b8e8cc |
||||
2019-05-08 20:28:29.020+10:00 | pool-10-thread-1 | INFO | IbftRound | Importing block to chain. round=ConsensusRoundIdentifier{Sequence=661, Round=0}, hash=0x5443e504256765f06b3cebfbee82276a034ebcc8d685b7c3d1a6010fd4acfa14 |
||||
``` |
||||
|
||||
On non-mining nodes, log messages indicate blocks are being imported. |
||||
|
||||
```bash |
||||
2019-05-08 20:28:29.026+10:00 | EthScheduler-Workers-1 | INFO | BlockPropagationManager | Imported #661 / 0 tx / 0 om / 0 (0.0%) gas / (0x5443e504256765f06b3cebfbee82276a034ebcc8d685b7c3d1a6010fd4acfa14) in 0.000s. |
||||
2019-05-08 20:28:31.031+10:00 | EthScheduler-Workers-0 | INFO | BlockPropagationManager | Imported #662 / 0 tx / 0 om / 0 (0.0%) gas / (0x0ead4e20123d3f1433d8dec894fcce386da4049819b24b309963ce7a8a0fcf03) in 0.000s. |
||||
``` |
||||
|
||||
Use the [`eth_blockNumber`](../Reference/Pantheon-API-Methods.md#eth_blocknumber) JSON-RPC API method to confirm the |
||||
block number is increasing. |
||||
|
||||
If blocks are not being created in [Clique](../Consensus-Protocols/Clique.md#extra-data) or [IBFT 2.0](../Consensus-Protocols/IBFT.md#extra-data) networks, |
||||
ensure the validator addresses in the genesis file match running nodes. |
||||
|
||||
## Transactions Not Being Mined |
||||
|
||||
If a transaction is added to the [transaction pool](../Using-Pantheon/Transactions/Transaction-Pool.md) |
||||
and the transaction hash returned but the transaction is never being mined, check the [`--min-gas-price`](../Reference/Pantheon-CLI-Syntax.md#min-gas-price) |
||||
option on mining nodes. If the `gasPrice` on a [transaction](../Using-Pantheon/Transactions/Transactions.md) |
||||
is lower than the `min-gas-price` for the mining node, the transaction will never be mined. |
||||
|
||||
In [free gas networks](../Configuring-Pantheon/FreeGas.md), [`--min-gas-price`](../Reference/Pantheon-CLI-Syntax.md#min-gas-price) must be set to 0. |
||||
|
||||
## Genesis Milestone |
||||
|
||||
Not including a sufficient milestone in the genesis file can lead to unexpected and inconsistent behaviour without |
||||
specific errors. Ensure a sufficient milestone is included in the genesis file (for example, `constantinoplefixblock`). |
||||
|
||||
## Illegal Reflective Access Error on Startup |
||||
|
||||
When using Java 9 or later, the following error message may be displayed on startup and does not affect the operation of Pantheon: |
||||
|
||||
``` |
||||
WARNING: An illegal reflective access operation has occurred |
||||
WARNING: Illegal reflective access by org.bouncycastle.jcajce.provider.drbg.DRBG (file:/Users/madelinemurray/pantheon/build/distributions/pantheon-1.1.2-SNAPSHOT/lib/bcprov-jdk15on-1.61.jar) to constructor sun.security.provider.Sun() |
||||
WARNING: Please consider reporting this to the maintainers of org.bouncycastle.jcajce.provider.drbg.DRBG |
||||
WARNING: Use --illegal-access=warn to enable warnings of further illegal reflective access operations |
||||
WARNING: All illegal access operations will be denied in a future release |
||||
``` |
||||
|
||||
To stop the message being displayed, add the following to the environment: |
||||
|
||||
```bash tab="Linux / Mac OS" |
||||
export PANTHEON_OPTS="--add-opens java.base/sun.security.provider=ALL-UNNAMED" |
||||
``` |
||||
|
||||
```bash tab="Windows" |
||||
set PANTHEON_OPTS="--add-opens java.base/sun.security.provider=ALL-UNNAMED" |
||||
``` |
||||
|
||||
## Command Line Options |
||||
|
||||
Characters such as smart quotes and long (em) hyphens won't work in Pantheon command line options. Ensure quotes have |
||||
not been automatically converted to smart quotes or double hyphens combined into em hyphens. |
||||
|
||||
## New Line Characters at the End of Files |
||||
|
||||
Ensure there is no new line character (`\n`) at the end of password files. New line characters may not |
||||
be displayed in all editors. |
||||
|
||||
## Logging |
||||
|
||||
Restart Pantheon with the command line option [`--logging=TRACE`](../Reference/Pantheon-CLI-Syntax.md#logging) and look at the log files. |
||||
@ -1,222 +0,0 @@ |
||||
description: Pantheon private network quickstart on Azure tutorial |
||||
<!--- END of page meta data --> |
||||
|
||||
# Azure Private Network Quickstart Tutorial |
||||
|
||||
This tutorial describes how to use the [Pantheon quickstart](https://github.com/PegaSysEng/pantheon-quickstart) |
||||
to run a private network of Pantheon nodes in a Docker container in a Linux Virtual |
||||
machine hosted on Microsoft Azure. |
||||
|
||||
## Duration |
||||
|
||||
**Duration : Approximately 20 minutes** |
||||
|
||||
The duration includes the Azure resources deployment (usually around 5 minutes) but it can vary. |
||||
This tutorial contains some optional steps that will increase the duration. |
||||
|
||||
## Steps |
||||
|
||||
* Step 1 - [Requirements](#requirements) |
||||
* Up to 20 minutes if you need to install requirements |
||||
* Step 2 - [Deploy the Quickstart](#deploy-the-quickstart) |
||||
* One Click Deploy : 5 minutes |
||||
* Manually : 15 minutes |
||||
* Step 3 - [Access the Lite Block Explorer](#accessing-the-alethio-ethstats-lite-block-explorer). |
||||
* 2 minutes |
||||
* Step 4 (optional) - [Copy endpoints and continue from here by following our Docker Quickstart Tutorial](#rpc-enpoints). |
||||
* Up to 10 minutes |
||||
* Step 5 - [Shut down the Azure Quickstart resources](#shutting-down-the-quickstart) |
||||
* Up to 10 minutes depending on the method |
||||
|
||||
## Requirements |
||||
|
||||
* Azure account. A [free trial account](https://azure.microsoft.com/en-us/free/) can be used for this tutorial. |
||||
* If not using Linux or MacOS, a tool to connect to a remote console using SSH. Free tools include: |
||||
* [Putty](https://www.putty.org/) |
||||
* [mRemoteNG](https://mremoteng.org/) |
||||
* [Terminals](https://github.com/terminals-Origin/Terminals) |
||||
|
||||
## Deploy the Quickstart |
||||
|
||||
### One Click Deploy |
||||
|
||||
Deploy the Pantheon Quickstart on [Microsoft Azure](https://azure.microsoft.com) by clicking the button below. |
||||
|
||||
[](https://portal.azure.com/#create/Microsoft.Template/uri/https%3A%2F%2Fraw.githubusercontent.com%2FPegaSysEng%2Fpantheon-quickstart%2Fmaster%2Fazure%2Fazuredeploy.json) |
||||
|
||||
If prompted to log in to the Azure Portal, log in before being redirected to the deployment form. |
||||
|
||||
???info "Filling in the Azure Deployment Form" |
||||
* **Subscription** : Default |
||||
* **Resource group** : Click **Create new** and enter `pantheon-quickstart` |
||||
* **Vm Name** : Default |
||||
* **Admin Username** : Default |
||||
* **Admin Password** : Create a password between 12 and 72 characters with numbers, lower and upper-case |
||||
letters, and a special symbol |
||||
* **Vm Size** : Standard DS2s v3 is the minimum usable size for this quickstart. |
||||
|
||||
### Deploy Manually |
||||
|
||||
To deploy manually instead of using the [One Click Deploy](#one-click-deploy), expand the |
||||
instructions. |
||||
|
||||
???example "Manual Deployment Steps" |
||||
|
||||
#### Connect to Azure Portal |
||||
Log into [Azure portal](https://portal.azure.com/) using your account credentials. |
||||
|
||||
#### Create Resources |
||||
On the home page, click **Create resource button** at the top left hand corner. |
||||
|
||||
Search the Marketplace for **Ubuntu Server 18.04 LTS** by Canonical and click on it. |
||||
An information page is displayed. Accept the default deployment model of Resource Manager and click **Create**. |
||||
|
||||
In **Create a virtual machine**, set the following values for each tab: |
||||
|
||||
##### Basics Step |
||||
|
||||
* Subscription --> Free trial |
||||
* Resource group --> Create a group and name it. For example, pantheon-quickstart |
||||
* Virtual machine name --> quickstart |
||||
* Region --> Default |
||||
* Availability options --> No infrastructure redundancy required |
||||
* Image --> Ubuntu Server 18.04 LTS |
||||
* Size --> Default. The quickstart doesn't require a lot of power and disk space. |
||||
A **Standard D2s v3 (2 vcpus, 8 GB memory)** is enough and is less expensive. |
||||
* Authentication type --> Choose the one you prefer |
||||
* Username --> Provide a user name. **azure** is used for this tutorial. |
||||
* Depending on the authentication method, enter the password or the public key. |
||||
* Login with Azure Active Directory --> **off** |
||||
* Public inbound ports --> Allow selected ports |
||||
* Select inbound ports --> Select **HTTP** and **SSH** |
||||
|
||||
At the top of the page, select the **Guest config** tab. |
||||
|
||||
##### Guest Config |
||||
|
||||
This step installs the required software (Docker and Docker-compose) on your virtual machine |
||||
and retrieves and runs the quickstart private network. |
||||
|
||||
1. Click on the **Select an extension to install** link and a new resource pane is displayed on the right. |
||||
|
||||
1. In the list, click **Custom Script For Linux**. Another pane is displayed with a blue **Create** button at |
||||
the bottom. |
||||
|
||||
1. Click the blue **Create** button. A form with two fields is displayed. |
||||
|
||||
1. In another browser tab or window, open [https://raw.githubusercontent.com/PegaSysEng/pantheon-quickstart/master/azure/install_and_run.sh](https://raw.githubusercontent.com/PegaSysEng/pantheon-quickstart/master/azure/install_and_run.sh) |
||||
|
||||
1. Save (++ctrl+s++) this script to your computer, in any location, called `install_and_run.sh`. |
||||
|
||||
1. Click on the **Script files** field and select the `install_and_run.sh` script you saved. |
||||
|
||||
1. In the **Command** field, enter (replacing the pre filled `sh script.sh`): |
||||
|
||||
```bash |
||||
sh install_and_run.sh azure |
||||
``` |
||||
|
||||
!!!important |
||||
The username is included at the end of this command, **azure** in this example. Use the |
||||
username defined in the Basics step. |
||||
|
||||
1. Click **Ok**. |
||||
|
||||
1. Click the **Review + create** blue button at the bottom of the page. |
||||
|
||||
1. When the green **Validation passed** message is displayed at the top of the screen, |
||||
press the blue **Create** button. |
||||
|
||||
## Access Resources |
||||
|
||||
Now your Quickstart is deploying, a **Your deployment is underway** screen is displayed. |
||||
The deployment takes approximately 5 minutes. |
||||
|
||||
Once the deployment is complete, **Your deployment is complete** is displayed with a list of deployed resources. |
||||
|
||||
 |
||||
|
||||
CLick the **quickstart** resource (the VM) in the list. The machine overview page is displayed. |
||||
|
||||
## Accessing the Alethio EthStats Lite Block Explorer |
||||
|
||||
On the right of the virtual machine page, the **Public IP address** of this machine is displayed. |
||||
Copy the public IP address and copy it into the navigation bar of a new browser tab or window. |
||||
|
||||
The EthStats Lite Block Explorer is displayed. |
||||
Wait a few seconds and 6 peers and the blocks mined are displayed. |
||||
|
||||
 |
||||
|
||||
## RPC Endpoints |
||||
|
||||
For the following optional tutorial steps, the RPC endpoints are: |
||||
|
||||
* HTTP RPC endpoint: **http://<your VM public IP>/jsonrpc** |
||||
* WebSocket RPC endpoint: **ws://<your VM public IP>/jsonws** |
||||
|
||||
## Optional Private Network Tutorial |
||||
|
||||
Follow the [private network quickstart tutorial starting from creating RPC requests](../../Tutorials/Private-Network-Quickstart.md#run-json-rpc-requests). |
||||
|
||||
When complete, resume this tutorial to shut down your resources. |
||||
|
||||
## Shutting Down the Quickstart |
||||
|
||||
!!!attention |
||||
Don't forget to shutdown the quickstart because it will consume your Azure resources |
||||
and that can be expensive or drain free credits from your trial account. |
||||
|
||||
Options for shutting down are: |
||||
|
||||
### I Want to Remove Everything From My Azure Account |
||||
|
||||
This is the easiest way to ensure your Azure resources won't consume any credits. |
||||
|
||||
In the Azure portal, navigate to your resource group (for example, **pantheon-quickstart**) and |
||||
click the **Delete resource group** button. |
||||
|
||||
### I Want to Remove the Virtual Machine Only |
||||
|
||||
In the Azure portal, navigate to your resource group (for example, **pantheon-quickstart**) and |
||||
click the virtual machine resource and click the **Delete** button. |
||||
|
||||
### I Want to Keep the Virtual Machine but Remove the Pantheon Network |
||||
|
||||
1. In the Azure portal, navigate to the VM: |
||||
1. Click **All services** in the left pane |
||||
1. Click **Virtual machines** |
||||
1. Click VM you named **quickstart** |
||||
|
||||
1. Click the **connect** button to obtain the information to connect with SSH (see [Requirements](#requirements)). |
||||
|
||||
1. Once connected to the machine, go to the `pantheon-quickstart` directory: |
||||
```bash |
||||
cd pantheon-quickstart |
||||
``` |
||||
|
||||
1. Run the remove script: |
||||
```bash |
||||
./remove.sh |
||||
``` |
||||
|
||||
1. To run the network again, use the following script: |
||||
|
||||
```bash |
||||
./run.sh -p 80 |
||||
``` |
||||
|
||||
Where 80 is the port number for the Block Explorer and RPC connections. |
||||
|
||||
### I Want to Stop the Pantheon Network and Be Able to Resume It |
||||
|
||||
Connect to the VM using SSH as for [I want to keep the VM but remove the nodes network](#i-want-to-keep-the-vm-but-remove-the-nodes-network) |
||||
but instead of running the remove script, run the stop script: |
||||
```bash |
||||
./stop.sh |
||||
``` |
||||
|
||||
To resume the network: |
||||
```bash |
||||
./resume.sh |
||||
``` |
||||
|
Before Width: | Height: | Size: 323 KiB |
|
Before Width: | Height: | Size: 5.9 KiB |
|
Before Width: | Height: | Size: 321 KiB |
@ -1,189 +0,0 @@ |
||||
description: Pantheon private network with privacy enabled quickstart tutorial |
||||
<!--- END of page meta data --> |
||||
|
||||
# Private Network with Privacy Enabled Quickstart Tutorial |
||||
|
||||
The Private Network with Privacy Enabled Quickstart runs a private network of Pantheon and Orion nodes managed by Docker Compose. |
||||
It is an expanded version of the [Private Network Quickstart](Private-Network-Quickstart.md). |
||||
|
||||
You can use the [Block Explorer](../Tutorials/Private-Network-Quickstart.md#block-explorer), |
||||
make [JSON-RPC requests](../Tutorials/Private-Network-Quickstart.md#run-json-rpc-requests), and |
||||
create [transactions using Metamask](../Tutorials/Private-Network-Quickstart.md#creating-a-transaction-using-metamask) |
||||
as described in the [Private Network Quickstart tutorial](Private-Network-Quickstart.md). |
||||
This tutorial describes how to use the examples provided in the EEAJS library to [create and send private transactions](#send-private-transactions-and-read-values). |
||||
|
||||
!!! important |
||||
The quickstart runs a private network suitable for education or demonstration purposes. |
||||
The quickstart is not intended for running production networks. |
||||
|
||||
## Prerequisites |
||||
|
||||
To run this tutorial, you must have the following installed: |
||||
|
||||
- MacOS or Linux |
||||
|
||||
!!! important |
||||
The Private Network Quickstart is not supported on Windows. If using Windows, run the quickstart |
||||
inside a Linux VM such as Ubuntu. |
||||
|
||||
- [Docker and Docker-compose](https://docs.docker.com/compose/install/) |
||||
|
||||
- [Nodejs](https://nodejs.org/en/download/) |
||||
|
||||
- [Git command line](https://git-scm.com/) |
||||
|
||||
- [Curl command line](https://curl.haxx.se/download.html) |
||||
|
||||
## Clone Pantheon Quickstart Source Code |
||||
|
||||
Clone the repository from the `pantheon-quickstart` repository where `<version>` is replaced with the latest version (`{{ versions.quickstart }}`). |
||||
|
||||
```bash tab="Command" |
||||
git clone --branch <version> https://github.com/PegaSysEng/pantheon-quickstart.git |
||||
``` |
||||
|
||||
```bash tab="Example" |
||||
git clone --branch {{ versions.quickstart }} https://github.com/PegaSysEng/pantheon-quickstart.git |
||||
``` |
||||
|
||||
## Clone EEAJS Libraries |
||||
|
||||
Clone the `PegaSysEng/eeajs` library: |
||||
|
||||
```bash |
||||
git clone https://github.com/PegaSysEng/eeajs.git |
||||
``` |
||||
|
||||
In the `eeajs` directory: |
||||
|
||||
```bash |
||||
npm install |
||||
``` |
||||
|
||||
## Start the Private Network with Privacy Enabled |
||||
|
||||
In the `pantheon-quickstart/privacy` directory, start the network: |
||||
|
||||
```bash |
||||
./run.sh |
||||
``` |
||||
|
||||
The Docker images are pulled and network started. Pulling the images takes a few minutes the first time. |
||||
The network details are displayed. |
||||
|
||||
```bash |
||||
Name Command State Ports |
||||
-------------------------------------------------------------------------------------------------------------------------- |
||||
privacy_bootnode_1 /opt/pantheon/bootnode_sta ... Up 30303/tcp, 8545/tcp, 8546/tcp |
||||
privacy_explorer_1 nginx -g daemon off; Up 0.0.0.0:32771->80/tcp |
||||
privacy_minernode_1 /opt/pantheon/node_start.s ... Up 30303/tcp, 8545/tcp, 8546/tcp |
||||
privacy_node1_1 /opt/pantheon/node_start.s ... Up 30303/tcp, 0.0.0.0:20000->8545/tcp, 0.0.0.0:20001->8546/tcp |
||||
privacy_node2_1 /opt/pantheon/node_start.s ... Up 30303/tcp, 0.0.0.0:20002->8545/tcp, 0.0.0.0:20003->8546/tcp |
||||
privacy_node3_1 /opt/pantheon/node_start.s ... Up 30303/tcp, 0.0.0.0:20004->8545/tcp, 0.0.0.0:20005->8546/tcp |
||||
privacy_orion1_1 /orion/bin/orion data/data ... Up |
||||
privacy_orion2_1 /orion/bin/orion data/data ... Up |
||||
privacy_orion3_1 /orion/bin/orion data/data ... Up |
||||
privacy_rpcnode_1 /opt/pantheon/node_start.s ... Up 30303/tcp, 8545/tcp, 8546/tcp |
||||
**************************************************************** |
||||
JSON-RPC HTTP service endpoint : http://localhost:32771/jsonrpc * |
||||
JSON-RPC WebSocket service endpoint : ws://localhost:32771/jsonws * |
||||
Web block explorer address : http://localhost:32771 * |
||||
**************************************************************** |
||||
``` |
||||
|
||||
## Send Private Transactions and Read Values |
||||
|
||||
The Event Emitter script deploys a contract with a privacy group of Node1 and Node2. That is, the other nodes |
||||
cannot access the contract. After deploying the contract, Event Emitter stores a value. |
||||
|
||||
In the `eeajs` directory, run `eventEmitter.js`: |
||||
|
||||
```bash |
||||
node example/eventEmitter.js |
||||
``` |
||||
|
||||
!!! tip |
||||
The network takes a minute or so to get started. If you get a ` Error: socket hang up` error, the network |
||||
isn't fully setup. Wait and then run the command again. |
||||
|
||||
The Event Emitter logs are displayed. |
||||
|
||||
```bash |
||||
Transaction Hash 0xe0776de9a9d4e30be0025c1308eed8bc45502cba9fe22c504a56e2fd95343e6f |
||||
Waiting for transaction to be mined ... |
||||
Private Transaction Receipt |
||||
{ contractAddress: '0x2f351161a80d74047316899342eedc606b13f9f8', |
||||
from: '0xfe3b557e8fb62b89f4916b721be55ceb828dbd73', |
||||
to: null, |
||||
output: |
||||
'0x6080604052600436106100565763ffffffff7c01000000000000000000000000000000000000000000000000000000006000350416633fa4f245811461005b5780636057361d1461008257806367e404ce146100ae575b600080fd5b34801561006757600080fd5b506100706100ec565b60408051918252519081900360200190f35b34801561008e57600080fd5b506100ac600480360360208110156100a557600080fd5b50356100f2565b005b3480156100ba57600080fd5b506100c3610151565b6040805173ffffffffffffffffffffffffffffffffffffffff9092168252519081900360200190f35b60025490565b604080513381526020810183905281517fc9db20adedc6cf2b5d25252b101ab03e124902a73fcb12b753f3d1aaa2d8f9f5929181900390910190a16002556001805473ffffffffffffffffffffffffffffffffffffffff191633179055565b60015473ffffffffffffffffffffffffffffffffffffffff169056fea165627a7a72305820c7f729cb24e05c221f5aa913700793994656f233fe2ce3b9fd9a505ea17e8d8a0029', |
||||
logs: [] } |
||||
Waiting for transaction to be mined ... |
||||
Transaction Hash: 0xbf14d332fa4c8f50d90cb02d47e0f825b8b2ef987c975306f76a598f181f4698 |
||||
Event Emited: 0x000000000000000000000000fe3b557e8fb62b89f4916b721be55ceb828dbd7300000000000000000000000000000000000000000000000000000000000003e8 |
||||
Waiting for transaction to be mined ... |
||||
Get Value: 0x00000000000000000000000000000000000000000000000000000000000003e8 |
||||
Waiting for transaction to be mined ... |
||||
Transaction Hash: 0x5b538c5690e3ead6e6f811ad23c853bc63b3bca91635b3b611e51d2797b5f073 |
||||
Event Emited: 0x000000000000000000000000fe3b557e8fb62b89f4916b721be55ceb828dbd73000000000000000000000000000000000000000000000000000000000000002a |
||||
Waiting for transaction to be mined ... |
||||
Get Value: 0x000000000000000000000000000000000000000000000000000000000000002a |
||||
``` |
||||
|
||||
Call [`eth_getTransactionReceipt`](../Reference/Pantheon-API-Methods.md#eth_gettransactionreceipt) where: |
||||
|
||||
* `<TransactionHash>` is the transaction hash displayed in the Event Emitter logs. |
||||
* `<JSON-RPC Endpoint>` is the JSON-RPC HTTP service endpoint displayed when starting the network. |
||||
|
||||
```bash tab="curl HTTP request" |
||||
curl -X POST --data '{"jsonrpc":"2.0","method":"eth_getTransactionReceipt","params":["<TransactionHash>"],"id":1}' <JSON-RPC Endpoint> |
||||
``` |
||||
|
||||
```bash tab="Example" |
||||
curl -X POST --data '{"jsonrpc":"2.0","method":"eth_getTransactionReceipt","params":["0xe0776de9a9d4e30be0025c1308eed8bc45502cba9fe22c504a56e2fd95343e6f"],"id":1}' http://localhost:32771/jsonrpc |
||||
``` |
||||
|
||||
The transaction receipt for the [privacy marker transaction](../Privacy/Explanation/Private-Transaction-Processing.md) is displayed with a `contractAddress` of `null`. |
||||
|
||||
```json |
||||
{ |
||||
"jsonrpc" : "2.0", |
||||
"id" : 1, |
||||
"result" : { |
||||
"blockHash" : "0xfacdc805f274553fcb2a12d3ef524f465c25e58626c27101c3e6f677297cdae9", |
||||
"blockNumber" : "0xa", |
||||
"contractAddress" : null, |
||||
"cumulativeGasUsed" : "0x5db8", |
||||
"from" : "0xfe3b557e8fb62b89f4916b721be55ceb828dbd73", |
||||
"gasUsed" : "0x5db8", |
||||
"logs" : [ ], |
||||
"logsBloom" : "0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000", |
||||
"status" : "0x1", |
||||
"to" : "0x000000000000000000000000000000000000007e", |
||||
"transactionHash" : "0xe0776de9a9d4e30be0025c1308eed8bc45502cba9fe22c504a56e2fd95343e6f", |
||||
"transactionIndex" : "0x0" |
||||
} |
||||
} |
||||
``` |
||||
|
||||
## Stop Network |
||||
|
||||
Do one of the following to stop the network: |
||||
|
||||
* Stop the network: |
||||
|
||||
```bash |
||||
./stop.sh |
||||
``` |
||||
|
||||
* Stop the network and remove the containers and volumes: |
||||
|
||||
```bash |
||||
./remove.sh |
||||
``` |
||||
|
||||
* Stop the network and delete the Docker images: |
||||
|
||||
```bash |
||||
./delete.sh |
||||
``` |
||||
@ -1,457 +0,0 @@ |
||||
description: Pantheon private network quickstart tutorial |
||||
<!--- END of page meta data --> |
||||
|
||||
# Private Network Quickstart Tutorial |
||||
|
||||
The Private Network Quickstart uses the Pantheon Docker image to run a private network of Pantheon nodes managed by Docker Compose. |
||||
|
||||
!!! important |
||||
The Private Network Quickstart runs a private network suitable for education or demonstration purposes. |
||||
The Private Network Quickstart is not intended for running production networks. |
||||
|
||||
## Prerequisites |
||||
|
||||
To run this tutorial, you must have the following installed: |
||||
|
||||
- MacOS or Linux |
||||
|
||||
!!! important |
||||
The Private Network Quickstart is not supported on Windows. If using Windows, run the quickstart |
||||
inside a Linux VM such as Ubuntu. |
||||
|
||||
- [Docker and Docker-compose](https://docs.docker.com/compose/install/) |
||||
|
||||
- [Git command line](https://git-scm.com/) |
||||
|
||||
- [Curl command line](https://curl.haxx.se/download.html) |
||||
|
||||
- A web browser that supports [Metamask](https://metamask.io/) (currently Chrome, Firefox, Opera, and Brave), and has |
||||
the MetaMask plug-in installed. This tutorial uses screenshots from Brave. |
||||
|
||||
|
||||
## Clone Pantheon Quickstart Source Code |
||||
|
||||
Clone the repository from the `pantheon-quickstart` with the version matching Pantheon version, currently `{{ versions.quickstart }}`: |
||||
|
||||
```bash tab="Linux/MacOS" |
||||
git clone --branch {{ versions.quickstart }} https://github.com/PegaSysEng/pantheon-quickstart.git |
||||
``` |
||||
|
||||
## Build Docker Images and Start Services and Network |
||||
|
||||
This tutorial uses [Docker Compose](https://docs.docker.com/compose/) to assemble the images and |
||||
run the private network. To build the docker images and run the containers, go to the `pantheon-quickstart` directory and run: |
||||
|
||||
```bash tab="Linux/MacOS" |
||||
./run.sh |
||||
``` |
||||
|
||||
The `run.sh` script builds the images, and runs the containers. It also scales 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 |
||||
************************************* |
||||
Pantheon Quickstart {{ versions.quickstart }} |
||||
************************************* |
||||
List endpoints and services |
||||
---------------------------------- |
||||
Name Command State Ports |
||||
--------------------------------------------------------------------------------------------------------- |
||||
pantheon-quickstart_bootnode_1 /opt/pantheon/bootnode_sta ... Up 30303/tcp, 8545/tcp, 8546/tcp |
||||
pantheon-quickstart_explorer_1 nginx -g daemon off; Up 0.0.0.0:32768->80/tcp |
||||
pantheon-quickstart_grafana_1 /run.sh Up 3000/tcp |
||||
pantheon-quickstart_minernode_1 /opt/pantheon/node_start.s ... Up 30303/tcp, 8545/tcp, 8546/tcp |
||||
pantheon-quickstart_node_1 /opt/pantheon/node_start.s ... Up 30303/tcp, 8545/tcp, 8546/tcp |
||||
pantheon-quickstart_node_2 /opt/pantheon/node_start.s ... Up 30303/tcp, 8545/tcp, 8546/tcp |
||||
pantheon-quickstart_node_3 /opt/pantheon/node_start.s ... Up 30303/tcp, 8545/tcp, 8546/tcp |
||||
pantheon-quickstart_node_4 /opt/pantheon/node_start.s ... Up 30303/tcp, 8545/tcp, 8546/tcp |
||||
pantheon-quickstart_prometheus_1 /bin/prometheus --config.f ... Up 9090/tcp |
||||
pantheon-quickstart_rpcnode_1 /opt/pantheon/node_start.s ... Up 30303/tcp, 8545/tcp, 8546/tcp |
||||
``` |
||||
|
||||
Followed by a list of the endpoints: |
||||
|
||||
!!! example "Endpoint list example" |
||||
```log |
||||
**************************************************************** |
||||
JSON-RPC HTTP service endpoint : http://localhost:32768/jsonrpc |
||||
JSON-RPC WebSocket service endpoint : ws://localhost:32768/jsonws |
||||
GraphQL HTTP service endpoint : http://localhost:32768/graphql |
||||
Web block explorer address : http://localhost:32768 |
||||
Prometheus address : http://localhost:32768/prometheus/graph |
||||
Grafana address : http://localhost:32768/grafana-dashboard |
||||
**************************************************************** |
||||
``` |
||||
|
||||
- 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 **GraphQL HTTP service endpoint** to access the [HTTP GraphQL](../Pantheon-API/GraphQL.md) node service from your Dapp. |
||||
- 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. |
||||
- Use the **Prometheus address** to access the [Prometheus dashboard](../Monitoring/Monitoring-Performance.md). |
||||
- Use the **Grafana address** to access the [Grafana dashboard](https://grafana.com/dashboards/10273). |
||||
|
||||
To display the list of endpoints again, run: |
||||
|
||||
```bash tab="Linux/MacOS" |
||||
./list.sh |
||||
``` |
||||
|
||||
## Block Explorer |
||||
|
||||
This tutorial uses the [Alethio Ethereum Lite Explorer](https://lite-explorer.aleth.io/). |
||||
|
||||
### 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 that the explorer indicates 6 peers: the 4 regular nodes, the mining node and the bootnode. |
||||
|
||||
Click 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** on 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. |
||||
|
||||
 |
||||
|
||||
|
||||
## Monitoring nodes with Prometheus and Grafana |
||||
|
||||
The quickstart also includes Prometheus and Grafana monitoring tools to let you visualise the nodes |
||||
health and usage. You can directly access these tools from your browser at the addresses displayed |
||||
in the endpoint list. |
||||
|
||||
For more details on how to configure and use these tools for your own nodes, refer to our |
||||
[performances monitoring documentation](../Monitoring/Monitoring-Performance.md), |
||||
as well as [Prometheus documentation](https://prometheus.io/docs/introduction/overview/) |
||||
and [Grafana documentation](https://grafana.com/docs/). |
||||
|
||||
 |
||||
|
||||
## Run JSON-RPC Requests |
||||
|
||||
You can run RPC requests on `rpcnode`, the node exposed to the host in order to listen for requests. This tutorial uses |
||||
[cURL](https://curl.haxx.se/download.html) to make JSON-RPC requests. |
||||
|
||||
For the RPC URL, this tutorial uses the placeholder `<http-rpc-endpoint>`. When you run the tutorial, |
||||
replace this placeholder 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: |
||||
|
||||
```bash |
||||
curl -X POST --data '{"jsonrpc":"2.0","method":"web3_clientVersion","params":[],"id":1}' <http-rpc-endpoint> |
||||
``` |
||||
|
||||
The result specifies the client version: |
||||
|
||||
```json |
||||
{ |
||||
"jsonrpc" : "2.0", |
||||
"id" : 1, |
||||
"result" : "pantheon/{{ versions.pantheon_stable }}" |
||||
} |
||||
``` |
||||
Here we simply query the version of the Pantheon node, which confirms the node is running. |
||||
|
||||
Successfully calling this method shows that you can connect to the nodes via RPC. From here, you can walk through more |
||||
interesting requests demonstrated in the rest of this section, or skip ahead to |
||||
[Creating a Transaction Using MetaMask](#creating-a-transaction-using-metamask). |
||||
|
||||
### Counting Peers |
||||
|
||||
Peers are the number of other nodes connected to the RPC node. |
||||
|
||||
Poll the peer count using `net_peerCount`: |
||||
|
||||
```bash |
||||
curl -X POST --data '{"jsonrpc":"2.0","method":"net_peerCount","params":[],"id":1}' <http-rpc-endpoint> |
||||
``` |
||||
|
||||
The result indicates that there are 6 peers: |
||||
|
||||
```json |
||||
{ |
||||
"jsonrpc" : "2.0", |
||||
"id" : 1, |
||||
"result" : "0x6" |
||||
} |
||||
``` |
||||
|
||||
### Requesting the Most Recently Mined Block Number |
||||
|
||||
Call `eth_blockNumber` to retrieve the number of the most recent block: |
||||
|
||||
```bash |
||||
curl -X POST --data '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}' <http-rpc-endpoint> |
||||
``` |
||||
|
||||
The result provides the most recently mined block: |
||||
|
||||
```json |
||||
{ |
||||
"jsonrpc" : "2.0", |
||||
"id" : 1, |
||||
"result" : "0x8b8" |
||||
} |
||||
``` |
||||
|
||||
The hexadecimal value `0x8b8` translates to `2232` in decimal, the number of blocks that have been mined so far. |
||||
|
||||
### Checking the Miner Account Balance |
||||
|
||||
Call `eth_getBalance` to retrieve the balance of the mining address (coinbase) defined in the miner node: |
||||
|
||||
```bash |
||||
curl -X POST --data '{"jsonrpc":"2.0","method":"eth_getBalance","params":["0xfe3b557e8fb62b89f4916b721be55ceb828dbd73","latest"],"id":1}' <http-rpc-endpoint> |
||||
``` |
||||
|
||||
The result specifies the miner account balance: |
||||
|
||||
```json |
||||
{ |
||||
"jsonrpc" : "2.0", |
||||
"id" : 1, |
||||
"result" : "0x79f905c6fd34e80000" |
||||
} |
||||
``` |
||||
|
||||
!!!info |
||||
0x79f905c6fd34e80000 = 2250000000000000000000 Wei (2250 Ether). |
||||
!!!tip |
||||
Use a [unit converter](https://etherconverter.online/) to easily translate values from Wei to Ether. |
||||
|
||||
Wait several seconds until new blocks are mined and call `eth_getBalance` again. The balance increases, meaning the miner |
||||
address successfully received the mining reward. |
||||
|
||||
You can also view this information in the block explorer. It does exactly the same thing as this call, connecting |
||||
to the RPC node using HTTP JSON-RPC, and displaying information on a web page. |
||||
|
||||
|
||||
## Creating a Transaction Using MetaMask |
||||
|
||||
Now let's use [MetaMask](https://metamask.io/) to send transactions. |
||||
|
||||
Before sending transactions, you need to create an account or use one of the accounts below created during the genesis |
||||
of this private test network. |
||||
|
||||
{!global/test_accounts.md!} |
||||
|
||||
!!!note |
||||
Pantheon doesn't implement [account management](../Using-Pantheon/Account-Management.md). To create your own account, |
||||
you have to use a third-party tool such as MetaMask. |
||||
|
||||
After you sign in to MetaMask, connect to the private network RPC endpoint: |
||||
|
||||
1. In the MetaMask network list, select **Custom RPC**. |
||||
1. 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](https://metamask.zendesk.com/hc/en-us/articles/360015489331-Importing-an-Account-New-UI-) |
||||
using the corresponding private key. |
||||
|
||||
!!!note |
||||
In this tutorial, we don't need to secure the keys, because we're using a private test network to send valueless |
||||
Ether. However, be sure to secure your accounts in a real use case on the main Ethereum network (MainNet). |
||||
|
||||
Once this is done, [create another account from scratch](https://metamask.zendesk.com/hc/en-us/articles/360015289452-Creating-Additional-MetaMask-Wallets-New-UI-) |
||||
to send Ether to. |
||||
|
||||
In MetaMask, select the new account and copy the account address by clicking the **...** gadget 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 Ether](https://metamask.zendesk.com/hc/en-us/articles/360015488991-Sending-Ether-New-UI-) from the first account |
||||
(containing ether) to the new one (which has a zero balance). |
||||
|
||||
Refresh the browser page that displays the new account. The updated balance is displayed and reflects the transaction |
||||
completed using MetaMask. |
||||
|
||||
|
||||
## Truffle Pet Shop Tutorial |
||||
|
||||
With a few modifications, we can use the private network in this tutorial as the blockchain for the |
||||
[PetShop tutorial on Truffle website](https://truffleframework.com/tutorials/pet-shop). |
||||
|
||||
#### Prerequisites |
||||
|
||||
* [Node.js v6+ LTS and npm](https://nodejs.org/en/) (comes with Node) |
||||
|
||||
#### Install Truffle and Unpack Truffle Box |
||||
|
||||
Install Truffle : |
||||
|
||||
```bash |
||||
npm install -g truffle |
||||
``` |
||||
|
||||
!!! note |
||||
`npm` requires `sudo` on Linux. |
||||
|
||||
Create a `pet-shop-tutorial` directory and move into it: |
||||
|
||||
```bash |
||||
mkdir pet-shop-tutorial |
||||
|
||||
cd pet-shop-tutorial |
||||
``` |
||||
|
||||
Unpack Pet Shop [Truffle box](https://truffleframework.com/boxes): |
||||
|
||||
`truffle unbox pet-shop` |
||||
|
||||
Install the [Truffle wallet](https://github.com/trufflesuite/truffle-hdwallet-provider): |
||||
Note with Truffle 5, you must use a Web3 1.0 enabled wallet or the Truffle tasks will hang. |
||||
|
||||
```bash |
||||
npm install --save truffle-hdwallet-provider@web3-one |
||||
``` |
||||
|
||||
!!!note |
||||
`npm` requires `sudo` on Linux. |
||||
|
||||
#### Modify the Pet Shop Example |
||||
|
||||
Modify the `truffle-config.js` file in the `pet-shop-tutorial` directory to add our wallet provider. The following shows the |
||||
code with placeholders to change as directed below: |
||||
|
||||
```javascript |
||||
const PrivateKeyProvider = require("truffle-hdwallet-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 contains Ether. |
||||
|
||||
Once this is done, follow the [Truffle tutorial steps](https://truffleframework.com/tutorials/pet-shop#directory-structure) |
||||
up to Step 3 in the [Migration section](https://truffleframework.com/tutorials/pet-shop#migration). |
||||
|
||||
We're using the private network instead of [Ganache](https://truffleframework.com/ganache), so skip steps 3, 4, and 5 in |
||||
the [Migration section](https://truffleframework.com/tutorials/pet-shop#migration). |
||||
|
||||
In step 4, specify the private network: |
||||
|
||||
```bash |
||||
truffle migrate --network quickstartWallet |
||||
``` |
||||
|
||||
Output similar to the following is displayed (your addresses will differ): |
||||
|
||||
```log |
||||
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 Truffle tutorial steps in the [Testing the smart contract](https://truffleframework.com/tutorials/pet-shop#testing-the-smart-contract) section. |
||||
|
||||
To run the tests in the [Running the tests](https://truffleframework.com/tutorials/pet-shop#running-the-tests) section, |
||||
specify the private network: |
||||
|
||||
```bash |
||||
truffle test --network quickstartWallet |
||||
``` |
||||
|
||||
Output similar to the following is displayed: |
||||
```log |
||||
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 Truffle tutorial steps in the [Creating a user interface to interact with the smart contract](https://truffleframework.com/tutorials/pet-shop#creating-a-user-interface-to-interact-with-the-smart-contract) section. |
||||
|
||||
We've already connected the private network to MetaMask, so you can skip the [Installing and configuring MetaMask](https://truffleframework.com/tutorials/pet-shop#installing-and-configuring-metamask) section. |
||||
|
||||
Continue with the regular tutorial steps from the [Installing and configuring lite-server](https://truffleframework.com/tutorials/pet-shop#installing-and-configuring-lite-server) |
||||
section and finish the tutorial. |
||||
|
||||
When you adopt pets in the browser and approve the transaction in MetaMask, you'll be able to see the transactions in the block explorer. |
||||
|
||||
|
||||
## Stop / Restart Private Network without Removing Containers |
||||
|
||||
To shut down the private network without deleting the containers: |
||||
|
||||
```bash tab="Linux/MacOS" |
||||
./stop.sh |
||||
``` |
||||
|
||||
This command stops the containers related to the services specified in the `docker-compose.yml` file. |
||||
|
||||
To restart the private network: |
||||
|
||||
```bash tab="Linux/MacOS" |
||||
./resume.sh |
||||
``` |
||||
|
||||
## Stop Private Network and Remove Containers |
||||
|
||||
To shut down the private network and delete all containers and images created during the quickstart: |
||||
|
||||
```bash tab="Linux/MacOS" |
||||
./remove.sh |
||||
``` |
||||
|
Before Width: | Height: | Size: 868 KiB |
@ -1,163 +0,0 @@ |
||||
# Accessing Logs Using Pantheon API |
||||
|
||||
Access logs using Pantheon API methods: |
||||
|
||||
* [`eth_getFilterChanges`](../Reference/Pantheon-API-Methods.md#eth_getfilterchanges) |
||||
* [`eth_getFilterLogs`](../Reference/Pantheon-API-Methods.md#eth_getfilterlogs) |
||||
* [`eth_getLogs`](../Reference/Pantheon-API-Methods.md#eth_getlogs) |
||||
|
||||
Use [`eth_newFilter`](../Reference/Pantheon-API-Methods.md#eth_newfilter) to create the filter before |
||||
using [`eth_getFilterChanges`](../Reference/Pantheon-API-Methods.md#eth_getfilterchanges) and [`eth_getFilterLogs`](../Reference/Pantheon-API-Methods.md#eth_getfilterlogs)). |
||||
|
||||
!!! note |
||||
The following examples are created using the sample contract included in [Events and Logs](Events-and-Logs.md). |
||||
|
||||
## Creating a Filter |
||||
|
||||
Create a filter using [`eth_newFilter`](../Reference/Pantheon-API-Methods.md#eth_newfilter). |
||||
|
||||
!!! example |
||||
|
||||
If the [example contract](Events-and-Logs.md#example) was deployed to 0x42699a7612a82f1d9c36148af9c77354759b210b, the |
||||
following request for `eth_newFilter` creates a filter to log when `valueIndexed` is set to 5: |
||||
|
||||
```json |
||||
{ |
||||
"jsonrpc":"2.0", |
||||
"method":"eth_newFilter", |
||||
"params":[ |
||||
{ |
||||
"fromBlock":"earliest", |
||||
"toBlock":"latest", |
||||
"address":"0x42699a7612a82f1d9c36148af9c77354759b210b", |
||||
"topics":[ |
||||
["0xd3610b1c54575b7f4f0dc03d210b8ac55624ae007679b7a928a4f25a709331a8"], |
||||
["0x0000000000000000000000000000000000000000000000000000000000000005"] |
||||
] |
||||
} |
||||
], |
||||
"id":1 |
||||
} |
||||
``` |
||||
|
||||
[`eth_newFilter`](../Reference/Pantheon-API-Methods.md#eth_newfilter) returns a filter ID hash (for example, `0x1ddf0c00989044e9b41cc0ae40272df3`). |
||||
|
||||
### Polling Filter for Changes |
||||
|
||||
To poll the filter for changes that have occurred since the last poll, use [`eth_getFilterChanges`](../Reference/Pantheon-API-Methods.md#eth_getfilterchanges) |
||||
with the filter ID hash returned by [`eth_newFilter`](../Reference/Pantheon-API-Methods.md#eth_newfilter). |
||||
|
||||
!!! example |
||||
|
||||
If the contract had been executed twice since the last poll, with `valueIndexed` set to 1 and 5, |
||||
[`eth_getFilterChanges`](../Reference/Pantheon-API-Methods.md#eth_getfilterchanges) returns |
||||
only the log where the [topic](Events-and-Logs.md#event-parameters) for `valueIndexed` is 5: |
||||
|
||||
```json |
||||
{ |
||||
"jsonrpc": "2.0", |
||||
"id": 1, |
||||
"result": [ |
||||
{ |
||||
"logIndex": "0x0", |
||||
"removed": false, |
||||
"blockNumber": "0x21c", |
||||
"blockHash": "0xc7e6c9d5b9f522b2c9d2991546be0a8737e587beb6628c056f3c327a44b45132", |
||||
"transactionHash": "0xfd1a40f9fbf89c97b4545ec9db774c85e51dd8a3545f969418a22f9cb79417c5", |
||||
"transactionIndex": "0x0", |
||||
"address": "0x42699a7612a82f1d9c36148af9c77354759b210b", |
||||
"data": "0x0000000000000000000000000000000000000000000000000000000000000005", |
||||
"topics": [ |
||||
"0xd3610b1c54575b7f4f0dc03d210b8ac55624ae007679b7a928a4f25a709331a8", |
||||
"0x0000000000000000000000000000000000000000000000000000000000000005" |
||||
] |
||||
} |
||||
] |
||||
} |
||||
``` |
||||
|
||||
### Getting All Logs for a Filter |
||||
|
||||
To get all logs for a filter, use [`eth_getFilterLogs`](../Reference/Pantheon-API-Methods.md#eth_getfilterlogs). |
||||
|
||||
!!! example |
||||
|
||||
If the contract had been executed twice with `valueIndexed` set to 5 since the filter was created using `eth_newFilter`, |
||||
`eth_getFilterLogs` returns: |
||||
|
||||
```json |
||||
{ |
||||
"jsonrpc": "2.0", |
||||
"id": 1, |
||||
"result": [ |
||||
{ |
||||
"logIndex": "0x0", |
||||
"removed": false, |
||||
"blockNumber": "0x1a7", |
||||
"blockHash": "0x4edda22a242ddc7bc51e2b6b11e63cd67be1af7389470cdea9c869768ff75d42", |
||||
"transactionHash": "0x9535bf8830a72ca7d0020df0b547adc4d0ecc4321b7d5b5d6beb1eccee5c0afa", |
||||
"transactionIndex": "0x0", |
||||
"address": "0x42699a7612a82f1d9c36148af9c77354759b210b", |
||||
"data": "0x0000000000000000000000000000000000000000000000000000000000000005", |
||||
"topics": [ |
||||
"0xd3610b1c54575b7f4f0dc03d210b8ac55624ae007679b7a928a4f25a709331a8", |
||||
"0x0000000000000000000000000000000000000000000000000000000000000005" |
||||
] |
||||
}, |
||||
{ |
||||
"logIndex": "0x0", |
||||
"removed": false, |
||||
"blockNumber": "0x21c", |
||||
"blockHash": "0xc7e6c9d5b9f522b2c9d2991546be0a8737e587beb6628c056f3c327a44b45132", |
||||
"transactionHash": "0xfd1a40f9fbf89c97b4545ec9db774c85e51dd8a3545f969418a22f9cb79417c5", |
||||
"transactionIndex": "0x0", |
||||
"address": "0x42699a7612a82f1d9c36148af9c77354759b210b", |
||||
"data": "0x0000000000000000000000000000000000000000000000000000000000000005", |
||||
"topics": [ |
||||
"0xd3610b1c54575b7f4f0dc03d210b8ac55624ae007679b7a928a4f25a709331a8", |
||||
"0x0000000000000000000000000000000000000000000000000000000000000005" |
||||
] |
||||
} |
||||
] |
||||
} |
||||
``` |
||||
|
||||
!!! tip |
||||
You can use [`eth_getLogs`](#getting-logs-using-a-filter-options-object) with a filter options object |
||||
to get all logs matching the filter options instead of using [`eth_newFilter`](../Reference/Pantheon-API-Methods.md#eth_newfilter) |
||||
followed by [`eth_getFilterLogs`](../Reference/Pantheon-API-Methods.md#eth_getfilterlogs). |
||||
|
||||
## Uninstalling a Filter |
||||
|
||||
When you are finished using a filter, use [`eth_uninstallFilter`](../Reference/Pantheon-API-Methods.md#eth_uninstallfilter) to remove the filter. |
||||
|
||||
## Getting Logs Using a Filter Options Object |
||||
|
||||
To get all logs for a filter options object, use [`eth_getLogs`](../Reference/Pantheon-API-Methods.md#eth_getlogs). |
||||
|
||||
!!! example |
||||
|
||||
The following request for `eth_getLogs` returns all the logs where the example contract has been |
||||
deployed to 0x42699a7612a82f1d9c36148af9c77354759b210b and executed with `valueIndexed` set to 5. |
||||
|
||||
```json |
||||
{ |
||||
"jsonrpc":"2.0", |
||||
"method":"eth_getLogs", |
||||
"params":[ |
||||
{ |
||||
"fromBlock":"earliest", |
||||
"toBlock":"latest", |
||||
"address":"0x42699a7612a82f1d9c36148af9c77354759b210b", |
||||
"topics":[ |
||||
["0xd3610b1c54575b7f4f0dc03d210b8ac55624ae007679b7a928a4f25a709331a8"], |
||||
["0x0000000000000000000000000000000000000000000000000000000000000005"] |
||||
] |
||||
} |
||||
], |
||||
"id":1 |
||||
} |
||||
``` |
||||
|
||||
This returns the same result as calling [eth_newFilter](#creating-a-fitler) followed by [eth_getFilterLogs](#getting-all-logs-for-a-filter). |
||||
|
||||
@ -1,21 +0,0 @@ |
||||
description: Using third party wallets for account management |
||||
<!--- END of page meta data --> |
||||
|
||||
# Using Wallets for Key Management |
||||
|
||||
Pantheon doesn't support key management inside the client. Use: |
||||
|
||||
* [EthSigner](http://docs.ethsigner.pegasys.tech/en/latest/) with Pantheon to provide access to your key store and sign transactions. |
||||
|
||||
* Third-party tools (for example, [MetaMask](https://metamask.io/) and [web3j](https://web3j.io/)) for creating accounts. |
||||
|
||||
In Pantheon, you can use the JSON-RPC methods: |
||||
|
||||
* [`eth_getBalance`](../Reference/Pantheon-API-Methods.md#eth_getbalance) to obtain the account balance |
||||
* [`eth_sendRawTransaction`](../Reference/Pantheon-API-Methods.md#eth_sendrawtransaction) to transfer ether or create and interact with contracts (for more information, refer to [Transactions](Transactions/Transactions.md#transactions)). |
||||
* [`eea_sendRawTransaction`](../Reference/Pantheon-API-Methods.md#eea_sendrawtransaction) to send [private transactions](../Privacy/How-To/Creating-Sending-Private-Transactions.md). |
||||
|
||||
!!! tip |
||||
[EthSigner](http://docs.ethsigner.pegasys.tech/en/latest/) implements [`eth_sendTransaction`](http://docs.ethsigner.pegasys.tech/en/latest/Using-EthSigner/Using-EthSigner/#eth_sendtransaction) |
||||
and [`eea_sendTransaction`](http://docs.ethsigner.pegasys.tech/en/latest/Using-EthSigner/Using-EthSigner/#eea_sendtransaction). |
||||
|
||||
@ -1,195 +0,0 @@ |
||||
# Events and Logs |
||||
|
||||
When a transaction is mined, smart contracts emit events and write logs to the blockchain. |
||||
|
||||
Logs are associated with the contract address and included in the blockchain but logs are not accessible |
||||
from within contracts. Log storage is cheaper than contract storage (that is, it costs less gas) so if the required data can |
||||
be stored in and accessed from logs, the cost is reduced. For example, you can use logs to display all |
||||
transfers made using a specific contract but not the current state of the contract. |
||||
|
||||
A Dapp front end can either request logs using the [JSON-RPC API filter methods](Accessing-Logs-Using-JSON-RPC.md) |
||||
or subscribe to logs using the [RPC Pub/Sub API](../Pantheon-API/RPC-PubSub.md#logs). |
||||
|
||||
## Topics |
||||
|
||||
Log entries contain up to four topics. The first topic is the [event signature hash](#event-signature-hash) and up to three topics |
||||
are the indexed [event parameters](#event-parameters). |
||||
|
||||
!!! example |
||||
Log entry for an event with one indexed parameter: |
||||
|
||||
```json |
||||
{ |
||||
"logIndex": "0x0", |
||||
"removed": false, |
||||
"blockNumber": "0x84", |
||||
"blockHash": "0x5fc573d76ec48ec80cbc43f299ebc306a8168112e3a4485c23e84e9a40f5d336", |
||||
"transactionHash": "0xcb52f02342c2498df82c49ac26b2e91e182155c8b2a2add5b6dc4c249511f85a", |
||||
"transactionIndex": "0x0", |
||||
"address": "0x42699a7612a82f1d9c36148af9c77354759b210b", |
||||
"data": "0x", |
||||
"topics": [ |
||||
"0x04474795f5b996ff80cb47c148d4c5ccdbe09ef27551820caa9c2f8ed149cce3", |
||||
"0x0000000000000000000000000000000000000000000000000000000000000001" |
||||
] |
||||
} |
||||
``` |
||||
|
||||
## Event Parameters |
||||
|
||||
Up to three event parameters can have the `indexed` attribute. Indexed parameters are stored as `topics` |
||||
in the logs. Indexed parameters can be searched and filtered. |
||||
|
||||
Topics are 32 bytes. If an indexed argument is an array (including `string` and `byte` datatypes), |
||||
the keccak-256 hash of the paramater is stored as a topic. |
||||
|
||||
Non-indexed parameters are included in the logs `data` but cannot be easily searched or filtered. |
||||
|
||||
!!! example |
||||
|
||||
A Solidity contract that stores one indexed and one non-indexed parameter and has an event that emits the value of each parameter: |
||||
|
||||
```solidity |
||||
pragma solidity ^0.5.1; |
||||
contract Storage { |
||||
uint256 public valueIndexed; |
||||
uint256 public valueNotIndexed; |
||||
|
||||
event Event1(uint256 indexed valueIndexed, uint256 valueNotIndexed); |
||||
|
||||
function setValue(uint256 _valueIndexed, uint256 _valueNotIndexed) public { |
||||
valueIndexed = _valueIndexed; |
||||
valueNotIndexed = _valueNotIndexed; |
||||
emit Event1(_valueIndexed, _valueNotIndexed); |
||||
} |
||||
} |
||||
``` |
||||
|
||||
!!! example |
||||
Log entry created by invoking the contract above with `valueIndexed` set to 5 and `valueNotIndexed` set to 7: |
||||
|
||||
```json |
||||
{ |
||||
"logIndex": "0x0", |
||||
"removed": false, |
||||
"blockNumber": "0x4d6", |
||||
"blockHash": "0x7d0ac7c12ac9f622d346d444c7e0fa4dda8d4ed90de80d6a28814613a4884a67", |
||||
"transactionHash": "0xe994022ada94371ace00c4e1e20663a01437846ced02f18b3f3afec827002781", |
||||
"transactionIndex": "0x0", |
||||
"address": "0x43d1f9096674b5722d359b6402381816d5b22f28", |
||||
"data": "0x0000000000000000000000000000000000000000000000000000000000000007", |
||||
"topics": [ |
||||
"0xd3610b1c54575b7f4f0dc03d210b8ac55624ae007679b7a928a4f25a709331a8", |
||||
"0x0000000000000000000000000000000000000000000000000000000000000005" |
||||
] |
||||
} |
||||
``` |
||||
|
||||
## Event Signature Hash |
||||
|
||||
The first topic in a log entry is always the the event signature hash. The event signature hash is a keccak-256 |
||||
hash of the event name and input argument types. Argument names are ignored. For example, the event `Hello(uint256 worldId)` |
||||
has the signature hash `keccak('Hello(uint256)')`. The signature identifies to which event log topics belong. |
||||
|
||||
!!! example |
||||
|
||||
A Solidity contract with two different events: |
||||
|
||||
``` solidity |
||||
pragma solidity ^0.5.1; |
||||
contract Storage { |
||||
uint256 public valueA; |
||||
uint256 public valueB; |
||||
|
||||
event Event1(uint256 indexed valueA); |
||||
event Event2(uint256 indexed valueB); |
||||
|
||||
function setValue(uint256 _valueA) public { |
||||
valueA = _valueA; |
||||
emit Event1(_valueA); |
||||
} |
||||
|
||||
function setValueAgain(uint256 _valueB) public { |
||||
valueB = _valueB; |
||||
emit Event2(_valueB); |
||||
} |
||||
} |
||||
``` |
||||
|
||||
The event signature hash for event 1 is `keccak('Event1(uint256)')` and the event signature hash for event |
||||
2 is `keccak('Event2(uint256)')`. The hashes are: |
||||
|
||||
* `04474795f5b996ff80cb47c148d4c5ccdbe09ef27551820caa9c2f8ed149cce3` for event 1 |
||||
* `06df6fb2d6d0b17a870decb858cc46bf7b69142ab7b9318f7603ed3fd4ad240e` for event 2 |
||||
|
||||
!!! tip |
||||
You can use a library keccak (sha3) hash function such as provided in [Web3.js](https://github.com/ethereum/wiki/wiki/JavaScript-API#web3sha3) |
||||
or an an online tool such as https://emn178.github.io/online-tools/keccak_256.html to generate event signature hashes. |
||||
|
||||
!!! example |
||||
Log entries from invoking the Solidity contract above: |
||||
|
||||
```json |
||||
[ |
||||
{ |
||||
"logIndex": "0x0", |
||||
"removed": false, |
||||
"blockNumber": "0x84", |
||||
"blockHash": "0x5fc573d76ec48ec80cbc43f299ebc306a8168112e3a4485c23e84e9a40f5d336", |
||||
"transactionHash": "0xcb52f02342c2498df82c49ac26b2e91e182155c8b2a2add5b6dc4c249511f85a", |
||||
"transactionIndex": "0x0", |
||||
"address": "0x42699a7612a82f1d9c36148af9c77354759b210b", |
||||
"data": "0x", |
||||
"topics": [ |
||||
"0x04474795f5b996ff80cb47c148d4c5ccdbe09ef27551820caa9c2f8ed149cce3", |
||||
"0x0000000000000000000000000000000000000000000000000000000000000001" |
||||
] |
||||
}, |
||||
{ |
||||
"logIndex": "0x0", |
||||
"removed": false, |
||||
"blockNumber": "0x87", |
||||
"blockHash": "0x6643a1e58ad857f727552e4572b837a85b3ca64c4799d085170c707e4dad5255", |
||||
"transactionHash": "0xa95295fcea7df3b9e47ab95d2dadeb868145719ed9cc0e6c757c8a174e1fcb11", |
||||
"transactionIndex": "0x0", |
||||
"address": "0x42699a7612a82f1d9c36148af9c77354759b210b", |
||||
"data": "0x", |
||||
"topics": [ |
||||
"0x06df6fb2d6d0b17a870decb858cc46bf7b69142ab7b9318f7603ed3fd4ad240e", |
||||
"0x0000000000000000000000000000000000000000000000000000000000000002" |
||||
] |
||||
} |
||||
] |
||||
``` |
||||
|
||||
## Topic Filters |
||||
|
||||
[Filter options objects](../Reference/Pantheon-API-Objects.md#filter-options-object) have a `topics` key to filter logs by topics. |
||||
|
||||
Topics are order-dependent. A transaction with a log containing topics `[A, B]` is matched with the following topic filters: |
||||
|
||||
* `[]` - Match any topic |
||||
* `[A]` - Match A in first position |
||||
* `[[null], [B]]` - Match any topic in first position AND B in second position |
||||
* `[[A],[B]]` - Match A in first position AND B in second position |
||||
* `[[A, C], [B, D]]` - Match (A OR C) in first position AND (B OR D) in second position |
||||
|
||||
|
||||
|
||||
!!! example |
||||
The following filter option object returns log entries for the [Event Parameters example contract](#event-parameters) where `valueIndexed` is set to |
||||
5 or 9: |
||||
|
||||
```json |
||||
{ |
||||
"fromBlock":"earliest", |
||||
"toBlock":"latest", |
||||
"address":"0x43d1f9096674b5722d359b6402381816d5b22f28", |
||||
"topics":[ |
||||
["0xd3610b1c54575b7f4f0dc03d210b8ac55624ae007679b7a928a4f25a709331a8"], |
||||
["0x0000000000000000000000000000000000000000000000000000000000000005", "0x0000000000000000000000000000000000000000000000000000000000000009"] |
||||
] |
||||
} |
||||
``` |
||||
|
||||
|
||||
@ -1,18 +0,0 @@ |
||||
description: Using Pantheon for PoW CPU mining |
||||
<!--- END of page meta data --> |
||||
|
||||
# Mining |
||||
|
||||
Start Pantheon with the following options to enable CPU mining: |
||||
```bash |
||||
pantheon --miner-enabled --miner-coinbase <account> |
||||
``` |
||||
|
||||
Where `<account>` is the account to which mining rewards are to be paid. For example, `fe3b557e8fb62b89f4916b721be55ceb828dbd73`. |
||||
|
||||
JSON-RPC API methods for mining are: |
||||
|
||||
* [`miner_start`](../Reference/Pantheon-API-Methods.md#miner_start) to start mining. |
||||
* [`miner_stop`](../Reference/Pantheon-API-Methods.md#miner_stop) to stop mining. |
||||
* [`eth_mining`](../Reference/Pantheon-API-Methods.md#eth_mining) to determine whether the client is actively mining new blocks. |
||||
* [`eth_hashrate`](../Reference/Pantheon-API-Methods.md#eth_hashrate) to get the number of hashes per second with which the node is mining. |
||||
@ -1,92 +0,0 @@ |
||||
description: Including revert reason in transactions |
||||
<!--- END of page meta data --> |
||||
|
||||
# Revert Reason |
||||
|
||||
In smart contracts, the [`revert`](https://solidity.readthedocs.io/en/v0.5.10/control-structures.html#revert) operation |
||||
triggers an exception to flag an error and revert the current call. An optional string message containing |
||||
information about the error is passed back to the client from the EVM. |
||||
|
||||
!!! example |
||||
```sol |
||||
pragma solidity >=0.5.0 <0.7.0; |
||||
|
||||
contract VendingMachine { |
||||
function buy(uint amount) public payable { |
||||
if (amount > msg.value / 2 ether) |
||||
revert("Not enough Ether provided"); |
||||
// Alternative way to do it: |
||||
require( |
||||
amount <= msg.value / 2 ether, |
||||
"Not enough Ether provided." |
||||
); |
||||
// Perform the purchase. |
||||
} |
||||
} |
||||
``` |
||||
|
||||
## Enabling Revert Reason |
||||
|
||||
Use the [`--revert-reason-enabled`](../../Reference/Pantheon-CLI-Syntax.md#revert-reason-enabled) command line option |
||||
to include the revert reason in the transaction receipt in Pantheon. |
||||
|
||||
!!! caution |
||||
Enabling revert reason may use a significant amount of memory. We do not recommend enabling revert |
||||
reason when connected to public Ethereum networks. |
||||
|
||||
## Where is the Revert Reason Included |
||||
|
||||
When revert reason is enabled, the revert reason is included as an ABI-encoded string in the transaction receipt returned by |
||||
[`eth_getTransactionReceipt`](../../Reference/Pantheon-API-Methods.md#eth_gettransactionreceipt). |
||||
|
||||
!!! important |
||||
The revert reason is not included in the transactions receipts root hash. Not being included in the |
||||
transactions receipts root hash means the revert reason is only available to nodes that execute the |
||||
transaction when importing the block. That is, the revert reason is not available if using fast sync. |
||||
|
||||
!!! example |
||||
``` |
||||
{ |
||||
"jsonrpc": "2.0", |
||||
"id": 1, |
||||
"result": { |
||||
"blockHash": "0xe7212a92cfb9b06addc80dec2a0dfae9ea94fd344efeb157c41e12994fcad60a", |
||||
"blockNumber": "0x50", |
||||
"contractAddress": null, |
||||
"cumulativeGasUsed": "0x5208", |
||||
"from": "0x627306090abab3a6e1400e9345bc60c78a8bef57", |
||||
"gasUsed": "0x5208", |
||||
"logs": [], |
||||
"logsBloom": "0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000", |
||||
"status": "0x1", |
||||
"to": "0xf17f52151ebef6c7334fad080c5704d77216b732", |
||||
"transactionHash": "0xc00e97af59c6f88de163306935f7682af1a34c67245e414537d02e422815efc3", |
||||
"transactionIndex": "0x0", |
||||
"revertReason":"0x08c379a00000000000000000000000000000000000000000000000000000000000000020000000000000000000000000000000000000000000000000000000000000001a4e6f7420656e6f7567682045746865722070726f76696465642e000000000000" |
||||
} |
||||
} |
||||
``` |
||||
|
||||
## Revert Reason Format |
||||
|
||||
As described in the [Solidity documentation](https://solidity.readthedocs.io/en/v0.5.10/control-structures.html#revert), |
||||
the revert reason is included as an ABI-encoded string consisting of: |
||||
|
||||
``` |
||||
0x08c379a0 // Function selector for Error(string) |
||||
0x0000000000000000000000000000000000000000000000000000000000000020 // Data offset |
||||
0x000000000000000000000000000000000000000000000000000000000000001a // String length |
||||
0x4e6f7420656e6f7567682045746865722070726f76696465642e000000000000 // String data |
||||
``` |
||||
|
||||
!!! example |
||||
```bash tab="Revert reason string for Not enough Ether provided." |
||||
"0x08c379a00000000000000000000000000000000000000000000000000000000000000020000000000000000000000000000000000000000000000000000000000000001a4e6f7420656e6f7567682045746865722070726f76696465642e000000000000" |
||||
``` |
||||
|
||||
## Dapp Support |
||||
|
||||
Client libraries (eg, web3j) do not support extracting the revert reason from the transaction receipt. |
||||
To extract the revert reason your Dapp must interact directly with Pantheon using a custom JSON -> Object |
||||
converter. |
||||
|
||||
@ -1,33 +0,0 @@ |
||||
# Transaction Pool |
||||
|
||||
Options and methods for configuring and monitoring the transaction pool include: |
||||
|
||||
* [`txpool_pantheonTransactions`](../../Reference/Pantheon-API-Methods.md#txpool_pantheontransactions) JSON-RPC API method to list |
||||
transactions in the node transaction pool |
||||
|
||||
* [`--tx-pool-max-size`](../../Reference/Pantheon-CLI-Syntax.md#tx-pool-max-size) command line option to specify the maximum number |
||||
of transactions in the node transaction pool |
||||
|
||||
* [`tx-pool-retention-hours`](../../Reference/Pantheon-CLI-Syntax.md#tx-pool-retention-hours) command line option to specify |
||||
the maximum number of hours to retain pending transactions in the transaction pool |
||||
|
||||
* [`newPendingTransactions`](../../Pantheon-API/RPC-PubSub.md#pending-transactions) and [`droppedPendingTransactions`](../../Pantheon-API/RPC-PubSub.md#dropped-transactions) |
||||
RPC subscriptions to notify of transactions added to and dropped from the node transaction pool |
||||
|
||||
## Dropping Transactions when Transaction Pool Full |
||||
|
||||
Once full, the Pantheon transaction pool accepts and retains local transactions in preference to remote transactions. |
||||
If the transaction pool is full of local transactions, the oldest local transactions are dropped first. That is, a |
||||
full transaction pool continues to accept new local transactions by first dropping remote transactions and then by |
||||
dropping the oldest local transactions. |
||||
|
||||
## Replacing Transactions with Same Nonce |
||||
|
||||
If a transaction is received with the same sender and nonce as a pending transaction but a higher gas price, the pending transaction |
||||
is replaced by the new one with the higher gas price. |
||||
|
||||
## Size of Transaction Pool |
||||
|
||||
Decreasing the maximum size of the transaction pool reduces memory use. If the network is busy and there is a backlog |
||||
of transactions, increasing the size of the transaction pool reduces the risk of transactions being |
||||
removed from the transaction pool. |
||||
@ -1,22 +0,0 @@ |
||||
description: What transaction validation is performed when |
||||
<!--- END of page meta data --> |
||||
|
||||
# Validating Transactions |
||||
|
||||
When transactions are submitted and added to a block, validations are performed as illustrated. |
||||
|
||||
 |
||||
|
||||
The set of transaction pool validations are repeated when the transaction is propagated. The same set of |
||||
validations are repeated when the block including the transaction is imported except the nonce must be |
||||
exactly right when importing the block. |
||||
|
||||
When the transaction is added to a block an additional validation is performed to check the transaction gas limit |
||||
is less than the remaining gas limit for the block. After creating a block, the node imports the block and |
||||
the transaction pool validations are repeated. |
||||
|
||||
!!! important |
||||
The transaction is only added if the entire transaction gas limit is less than the remaining gas |
||||
for the block. The total gas used by the transaction is not relevant to this validation. That is, if the total gas used |
||||
by the transaction is less than the remaining block gas but the transaction gas limit is more than the remaining black |
||||
gas, the transaction is not added. |
||||
@ -1,135 +0,0 @@ |
||||
description: Some use cases of creating transactions on a Pantheon network |
||||
<!--- END of page meta data --> |
||||
|
||||
# Creating and Sending Transactions |
||||
|
||||
You can send signed transactions using the [`eth_sendRawTransaction`](../../Reference/Pantheon-API-Methods.md#eth_sendrawtransaction) JSON-RPC API method. |
||||
|
||||
Signed transactions can be simple value transfers, contract creation, or contract invocation. |
||||
|
||||
Example scripts are provided to create a signed raw transaction that can be passed to |
||||
[`eth_sendRawTransaction`](../../Reference/Pantheon-API-Methods.md#eth_sendrawtransaction) to send Ether |
||||
and create a smart contract. |
||||
|
||||
!!! warning "Private keys" |
||||
|
||||
Do not use the accounts in the examples on mainnet or any public network except for testing. |
||||
The private keys are displayed which means the accounts are not secure. |
||||
|
||||
All accounts and private keys in the examples are from the `dev.json` genesis file in the |
||||
[`/pantheon/ethereum/core/src/main/resources`](https://github.com/PegaSysEng/pantheon/tree/master/config/src/main/resources) directory. |
||||
|
||||
In production environments avoid exposing your private keys by creating signed transactions |
||||
offline, or use [EthSigner](https://docs.ethsigner.pegasys.tech/) to isolate your private keys and |
||||
sign transactions with [`eth_sendTransaction`](https://docs.ethsigner.pegasys.tech/Using-EthSigner/Using-EthSigner/#eth_sendtransaction). |
||||
|
||||
!!! tip |
||||
Libraries such as [web3j](https://github.com/web3j/web3j) or [ethereumj](https://github.com/ethereum/ethereumj) |
||||
and tools such as [MyCrypto](https://mycrypto.com/) can also be used to create signed transactions. |
||||
|
||||
You can use the example Javascript scripts to create and send raw transactions in the private network |
||||
created by the [Private Network Quickstart](../../Tutorials/Private-Network-Quickstart.md). |
||||
|
||||
Update the `JSON-RPC endpoint` in the following examples to the endpoint for the private |
||||
network displayed after running the `./run.sh` script. |
||||
|
||||
## Example Javascript scripts |
||||
|
||||
### 1. Requirements |
||||
|
||||
- [Node.js (version > 10)](https://nodejs.org/en/download/) |
||||
- [web3.js 1.0.0 beta](https://github.com/ethereum/web3.js/) and [ethereumjs 1.3](https://github.com/ethereumjs/ethereumjs-tx). |
||||
These dependencies are defined in the included [`package.json`](scripts/package.json) file. |
||||
|
||||
### 2. Create Directory |
||||
```bash |
||||
mkdir example_scripts |
||||
``` |
||||
|
||||
### 3. Copy Files |
||||
Copy the following files to the `example_scripts` directory: |
||||
|
||||
- [`package.json`](scripts/package.json) |
||||
- [`create_value_raw_transaction.js`](scripts/create_value_raw_transaction.js) |
||||
- [`create_contract_raw_transaction.js`](scripts/create_contract_raw_transaction.js) |
||||
|
||||
### 4. Retrieve Dependencies |
||||
```bash |
||||
cd example_scripts |
||||
npm install |
||||
``` |
||||
|
||||
### 5. Send Ether |
||||
The following is the example JavaScript script that displays a signed raw transaction string to send Ether. |
||||
|
||||
!!! example "Send Ether example : create_value_raw_transaction.js" |
||||
```javascript linenums="1" |
||||
{! Using-Pantheon/Transactions/scripts/create_value_raw_transaction.js !} |
||||
|
||||
``` |
||||
|
||||
Run the `create_value_raw_transaction.js` script: |
||||
|
||||
```bash tab="Command" |
||||
node create_value_raw_transaction.js <YOUR JSON-RPC HTTP ENDPOINT> |
||||
``` |
||||
|
||||
```bash tab="Example" |
||||
node create_value_raw_transaction.js http://localhost:32770/jsonrpc |
||||
``` |
||||
|
||||
!!! tip |
||||
The default JSON-RPC HTTP endpoint for `create_value_raw_transaction.js` is `http://localhost:8545`. |
||||
If using `http://localhost:8545`, run `node create_value_raw_transaction.js`. |
||||
|
||||
A signed raw transaction string is displayed. |
||||
|
||||
You can send the raw transaction yourself or let the script send it using the web3.js library. |
||||
|
||||
If sending it yourself, the cURL command is displayed and can be copied and pasted. Otherwise, the script sends it and |
||||
the transaction receipt is displayed. |
||||
|
||||
### 6. Create A Smart Contract |
||||
The following is the example JavaScript script that displays a signed raw transaction string to create a contract. |
||||
|
||||
!!! example "Create a contract example : create_contract_raw_transaction.js" |
||||
```javascript linenums="1" |
||||
{! Using-Pantheon/Transactions/scripts/create_contract_raw_transaction.js !} |
||||
|
||||
``` |
||||
|
||||
Run the `create_contract_raw_transaction.js` script: |
||||
|
||||
```bash tab="Command" |
||||
node create_contract_raw_transaction.js <YOUR JSON-RPC HTTP ENDPOINT> |
||||
``` |
||||
|
||||
```bash tab="Example" |
||||
node create_contract_raw_transaction.js http://localhost:32770/jsonrpc |
||||
``` |
||||
|
||||
!!! tip |
||||
The default JSON-RPC HTTP endpoint for `create_contract_raw_transaction.js` is `http://localhost:8545`. |
||||
If using `http://localhost:8545`, run `node create_contract_raw_transaction.js`. |
||||
|
||||
A signed raw transaction string is displayed. |
||||
|
||||
You can send the raw transaction yourself or let the script send it using the web3.js library. |
||||
|
||||
If sending it yourself, the cURL command is displayed and can be copied and pasted. Otherwise, the script sends it and |
||||
the transaction receipt is displayed. |
||||
|
||||
## eth_call vs eth_sendRawTransaction |
||||
|
||||
You can interact with contracts using [eth_call](../../Reference/Pantheon-API-Methods.md#eth_call) |
||||
or [eth_sendRawTransaction](../../Reference/Pantheon-API-Methods.md#eth_sendrawtransaction). |
||||
The table below compares the characteristics of both calls. |
||||
|
||||
| eth_call | eth_sendRawTransaction | |
||||
|---------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------| |
||||
| Read-only | Write | |
||||
| Invokes contract function locally | Broadcasts to network | |
||||
| Does not change state of blockchain | Updates blockchain (for example, transfers ether between accounts) | |
||||
| Does not consume gas | Requires gas | |
||||
| Synchronous | Asynchronous | |
||||
| Return value of contract function available immediately | Returns transaction hash only. Possible transaction may not be included in a block (for example, if the gas price is too low). | |
||||
@ -1,2 +0,0 @@ |
||||
node_modules |
||||
package-lock.json |
||||
@ -1,76 +0,0 @@ |
||||
const Web3 = require('web3') |
||||
const ethTx = require('ethereumjs-tx') |
||||
const readline = require('readline'); |
||||
|
||||
async function askQuestion(query) { |
||||
const rl = readline.createInterface({ |
||||
input: process.stdin, |
||||
output: process.stdout, |
||||
}); |
||||
|
||||
return new Promise(resolve => rl.question(query, ans => { |
||||
rl.close(); |
||||
resolve(ans); |
||||
})) |
||||
} |
||||
|
||||
const args = process.argv.slice(2); |
||||
|
||||
// web3 initialization - must point to the HTTP JSON-RPC endpoint
|
||||
var provider = args[0] || 'http://localhost:8545'; |
||||
console.log("******************************************"); |
||||
console.log("Using provider : " + provider); |
||||
console.log("******************************************"); |
||||
var web3 = new Web3(new Web3.providers.HttpProvider(provider)) |
||||
web3.transactionConfirmationBlocks = 1; |
||||
// Sender address and private key
|
||||
// Second acccount in dev.json genesis file
|
||||
// Exclude 0x at the beginning of the private key
|
||||
const addressFrom = '0x627306090abaB3A6e1400e9345bC60c78a8BEf57' |
||||
const privKey = Buffer.from('c87509a1c067bbde78beb793e6fa76530b6382a4c0241e5e4a9ec0a0f44dc0d3', 'hex') |
||||
|
||||
// hexadecimal encoded compiled contract code
|
||||
const contractData = '0x608060405234801561001057600080fd5b5060dc8061001f6000396000f3006080604052600436106049576000357c0100000000000000000000000000000000000000000000000000000000900463ffffffff1680633fa4f24514604e57806355241077146076575b600080fd5b348015605957600080fd5b50606060a0565b6040518082815260200191505060405180910390f35b348015608157600080fd5b50609e6004803603810190808035906020019092919050505060a6565b005b60005481565b80600081905550505600a165627a7a723058202bdbba2e694dba8fff33d9d0976df580f57bff0a40e25a46c398f8063b4c00360029' |
||||
|
||||
// Get the address transaction count in order to specify the correct nonce
|
||||
web3.eth.getTransactionCount(addressFrom, "pending").then((txnCount) => { |
||||
// Create the contract creation transaction object
|
||||
var txObject = { |
||||
nonce: web3.utils.toHex(txnCount), |
||||
gasPrice: web3.utils.toHex(1000), |
||||
gasLimit: web3.utils.toHex(126165), |
||||
data: contractData |
||||
}; |
||||
|
||||
// Sign the transaction with the private key
|
||||
var tx = new ethTx(txObject); |
||||
tx.sign(privKey) |
||||
|
||||
//Convert to raw transaction string
|
||||
var serializedTx = tx.serialize(); |
||||
var rawTxHex = '0x' + serializedTx.toString('hex'); |
||||
|
||||
// log raw transaction data to the console so you can send it manually
|
||||
console.log("Raw transaction data: " + rawTxHex); |
||||
|
||||
// but also ask you if you want to send this transaction directly using web3
|
||||
(async() => { |
||||
const ans = await askQuestion("******************************************\n\ |
||||
Do you want to send the signed contract creation transaction now ? (Y/N):"); |
||||
if("y" == ans || "Y" == ans){ |
||||
// Send the signed transaction using web3
|
||||
web3.eth.sendSignedTransaction(rawTxHex) |
||||
.on('receipt', receipt => { console.log('Receipt: ', receipt); }) |
||||
.catch(error => { console.log('Error: ', error.message); }); |
||||
console.log("******************************************"); |
||||
console.log("Contract transaction sent, waiting for receipt."); |
||||
console.log("******************************************"); |
||||
}else{ |
||||
console.log("******************************************"); |
||||
console.log("You can for instance send this transaction manually with the following command:"); |
||||
console.log("curl -X POST --data '{\"jsonrpc\":\"2.0\",\"method\":\"eth_sendRawTransaction\",\"params\":[\"" + rawTxHex + "\"],\"id\":1}'", provider); |
||||
} |
||||
})(); |
||||
|
||||
}) |
||||
.catch(error => { console.log('Error: ', error.message); }); |
||||
@ -1,79 +0,0 @@ |
||||
const Web3 = require('web3') |
||||
const ethTx = require('ethereumjs-tx') |
||||
const readline = require('readline'); |
||||
|
||||
async function askQuestion(query) { |
||||
const rl = readline.createInterface({ |
||||
input: process.stdin, |
||||
output: process.stdout, |
||||
}); |
||||
|
||||
return new Promise(resolve => rl.question(query, ans => { |
||||
rl.close(); |
||||
resolve(ans); |
||||
})) |
||||
} |
||||
|
||||
const args = process.argv.slice(2); |
||||
|
||||
// web3 initialization - must point to the HTTP JSON-RPC endpoint
|
||||
var provider = args[0] || 'http://localhost:8545'; |
||||
console.log("******************************************"); |
||||
console.log("Using provider : " + provider); |
||||
console.log("******************************************"); |
||||
var web3 = new Web3(new Web3.providers.HttpProvider(provider)) |
||||
web3.transactionConfirmationBlocks = 1; |
||||
// Sender address and private key
|
||||
// Second acccount in dev.json genesis file
|
||||
// Exclude 0x at the beginning of the private key
|
||||
const addressFrom = '0x627306090abaB3A6e1400e9345bC60c78a8BEf57' |
||||
const privKey = Buffer.from('c87509a1c067bbde78beb793e6fa76530b6382a4c0241e5e4a9ec0a0f44dc0d3', 'hex') |
||||
|
||||
// Receiver address and value to transfer
|
||||
// Third account in dev.json genesis file
|
||||
const addressTo = '0xf17f52151EbEF6C7334FAD080c5704D77216b732' |
||||
const valueInEther = 2 |
||||
|
||||
// Get the address transaction count in order to specify the correct nonce
|
||||
web3.eth.getTransactionCount(addressFrom, "pending").then((txnCount) => { |
||||
// Create the transaction object
|
||||
var txObject = { |
||||
nonce: web3.utils.numberToHex(txnCount), |
||||
gasPrice: web3.utils.numberToHex(1000), |
||||
gasLimit: web3.utils.numberToHex(21000), |
||||
to: addressTo, |
||||
value: web3.utils.numberToHex(web3.utils.toWei(valueInEther.toString(), 'ether')) |
||||
}; |
||||
|
||||
// Sign the transaction with the private key
|
||||
var tx = new ethTx(txObject); |
||||
tx.sign(privKey) |
||||
|
||||
//Convert to raw transaction string
|
||||
var serializedTx = tx.serialize(); |
||||
var rawTxHex = '0x' + serializedTx.toString('hex'); |
||||
|
||||
// log raw transaction data to the console so you can send it manually
|
||||
console.log("Raw transaction data: " + rawTxHex); |
||||
|
||||
// but also ask you if you want to send this transaction directly using web3
|
||||
(async() => { |
||||
const ans = await askQuestion("******************************************\n\ |
||||
Do you want to send the signed value transaction now ? (Y/N):"); |
||||
if("y" == ans || "Y" == ans){ |
||||
// Send the signed transaction using web3
|
||||
web3.eth.sendSignedTransaction(rawTxHex) |
||||
.on('receipt', receipt => { console.log('Receipt: ', receipt); }) |
||||
.catch(error => { console.log('Error: ', error.message); }); |
||||
console.log("******************************************"); |
||||
console.log("Value transaction sent, waiting for receipt."); |
||||
console.log("******************************************"); |
||||
}else{ |
||||
console.log("******************************************"); |
||||
console.log("You can for instance send this transaction manually with the following command:"); |
||||
console.log("curl -X POST --data '{\"jsonrpc\":\"2.0\",\"method\":\"eth_sendRawTransaction\",\"params\":[\"" + rawTxHex + "\"],\"id\":1}'", provider); |
||||
} |
||||
})(); |
||||
|
||||
}) |
||||
.catch(error => { console.log('Error: ', error.message); }); |
||||
@ -1,14 +0,0 @@ |
||||
{ |
||||
"name": "createAndSendSignedTransaction", |
||||
"version": "1.0.0", |
||||
"description": "Script to generate a signed transaction data using JSON-RPC to check nonce and option to send it using web3", |
||||
"scripts": { |
||||
"test": "echo \"Error: no test specified\" && exit 1" |
||||
}, |
||||
"author": "Pegasys", |
||||
"license": "Apache-2", |
||||
"dependencies": { |
||||
"ethereumjs-tx": "^1.3.7", |
||||
"web3": "^1.0.0-beta.55" |
||||
} |
||||
} |
||||
@ -1,57 +0,0 @@ |
||||
description: Using Pantheon with Truffle |
||||
<!--- END of page meta data --> |
||||
|
||||
# Using Pantheon with Truffle |
||||
|
||||
Developing for Pantheon using Truffle is the same as using Truffle to develop for the public Ethereum networks. |
||||
Truffle supports Pantheon with the only difference being Pantheon does not implement private key management. |
||||
To use Pantheon with Truffle, you must configure a Truffle wallet. |
||||
|
||||
## Install Truffle Wallet |
||||
|
||||
To install the Truffle wallet: |
||||
|
||||
```bash |
||||
npm install --save truffle-hdwallet-provider@web3-one |
||||
``` |
||||
|
||||
!!!note |
||||
With Truffle 5, you must use a Web3 1.0 enabled wallet or the Truffle tasks hang. |
||||
|
||||
#### Modify the Truffle Configuration File |
||||
|
||||
Modify the `truffle-config.js` file in the project directory to add the wallet provider. Replace: |
||||
|
||||
* `<JSON-RPC-http-endpoint>` with the JSON-RPC endpoint (IP address and port) of a Pantheon node |
||||
* `<account-private-key>` with the private key of an Ethereum account containing Ether |
||||
|
||||
```javascript |
||||
const PrivateKeyProvider = require("truffle-hdwallet-provider"); |
||||
const privateKey = "<account-private-key>"; |
||||
const privateKeyProvider = new PrivateKeyProvider(privateKey, "<JSON-RPC-http-endpoint>"); |
||||
|
||||
module.exports = { |
||||
// See <http://truffleframework.com/docs/advanced/configuration> |
||||
// for more about customizing your Truffle configuration! |
||||
networks: { |
||||
pantheonWallet: { |
||||
provider: privateKeyProvider, |
||||
network_id: "*" |
||||
}, |
||||
} |
||||
}; |
||||
``` |
||||
|
||||
### Start Pantheon Node |
||||
|
||||
Start a Pantheon node with JSON-RPC enabled on the endpoint specified in the Truffle configuration |
||||
file. |
||||
|
||||
### Deploy Contract |
||||
|
||||
To deploy a contract onto the Pantheon network: |
||||
|
||||
```bash |
||||
truffle migrate --network pantheonWallet |
||||
``` |
||||
|
||||
Some files were not shown because too many files have changed in this diff Show More
Loading…
Reference in new issue