Merge pull request #11 from openrelayxyz/pre-cardinal-docs-update
Pre cardinal docs update
This commit is contained in:
Philip Morlier
GitHub
commit
3e6e60003b
@ -6,12 +6,10 @@ Build and Deploy
|
||||
|
||||
.. contents:: :local:
|
||||
|
||||
If you are ready to start building your own plugins go ahead and start here.
|
||||
|
||||
Setting up the environment
|
||||
**************************
|
||||
|
||||
.. NOTE:: Plugeth is built on a fork of `Geth`_ and as such requires familiarity with `Go`_ and a funtional `environment`_ in which to build Go projects. Thankfully for everyone Go provides a compact and useful `tutorial`_ as well as a `space for practice`_.
|
||||
.. NOTE:: PluGeth is built on a fork of `Geth`_ and as such requires familiarity with `Go`_ and a funtional `environment`_ in which to build Go projects. Thankfully for everyone Go provides a compact and useful `tutorial`_ as well as a `space for practice`_.
|
||||
|
||||
PluGeth is an application built in three seperate repositories.
|
||||
|
||||
@ -19,7 +17,7 @@ PluGeth is an application built in three seperate repositories.
|
||||
* `PluGeth-Utils`_
|
||||
* `PluGeth-Plugins`_
|
||||
|
||||
For our purposed here you will only need to clone Plugeth and Plugeth-Plugins. Once you have them cloned you are ready to begin. First we need to build geth though the PluGeth project. Navigate to ``plugeth/cmd/geth`` and run:
|
||||
For the purposes here you will only need to clone PluGeth and PluGeth-Plugins. Once you have them cloned you are ready to begin. First we need to build PluGeth though the PluGeth project. Navigate to ``plugeth/cmd/geth`` and run:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
@ -31,7 +29,6 @@ This will download all dependencies needed for the project. This process will ta
|
||||
|
||||
$ go build
|
||||
|
||||
Once this is complete you should see a ``.ethereum`` folder in your home directory.
|
||||
|
||||
At this point you are ready to start downloading local ethereum nodes. In order to do so, from ``plugeth/cmd/geth`` run:
|
||||
|
||||
@ -39,11 +36,9 @@ At this point you are ready to start downloading local ethereum nodes. In order
|
||||
|
||||
$ ./geth
|
||||
|
||||
.. NOTE:: ``./geth`` is the primary command to build a *Mainnet* node. Building a mainnet node requires at least 8 GB RAM, 2 CPUs, and 350 GB of SSD disks. However, dozens of available flags will change the behavior of whichever network you choose to connect to. ``--help`` is your friend.
|
||||
|
||||
|
||||
Build a plugin
|
||||
**************
|
||||
Build your first plugin
|
||||
***********************
|
||||
|
||||
For the sake of this tutorial we will be building the Hello plugin. Navigate to ``plugethPlugins/packages/hello``. Inside you will see a ``main.go`` file. From this location run:
|
||||
|
||||
@ -53,6 +48,8 @@ For the sake of this tutorial we will be building the Hello plugin. Navigate to
|
||||
|
||||
This will compile the plugin and produce a ``hello.so`` file. Move ``hello.so`` into ``~/.ethereum/plugins`` . In order to use this plugin geth will need to be started with a ``http.api=mymamespace`` flag. Additionally you will need to include a ``--http`` flag in order to access the standard json rpc methods.
|
||||
|
||||
.. note:: The above location may change when changing ``--datadir``.
|
||||
|
||||
Once geth has started you should see that the first ``INFO`` log reads: ``initialized hello`` . A new json rpc method, called hello, has been been appended to the list of available json rpc methods. In order to access this method you will need to ``curl`` into the network with this command:
|
||||
|
||||
.. code-block:: shell
|
||||
@ -65,7 +62,7 @@ You should see that the network has responded with:
|
||||
|
||||
``{"jsonrpc":"2.0","id":0,"result":"Hello world"}``
|
||||
|
||||
Congradulations. You have just built and run your first Plugeth plugin. From here you can follow the steps above to build any of the plugins you choose.
|
||||
You have just built and run your first Plugeth plugin. From here you can follow the steps above to build any of the plugins you choose.
|
||||
|
||||
.. NOTE:: Each plugin will vary in terms of the requirements to deploy. Refer to the documentation of the plugin itself in order to assure
|
||||
that you know how to use it.
|
||||
|
||||
@ -18,7 +18,7 @@
|
||||
# -- Project information -----------------------------------------------------
|
||||
|
||||
project = 'Plugeth'
|
||||
copyright = '2021, Philip Morlier'
|
||||
copyright = '2021, Austin Roberts, Sam Johnston, Philip Morlier'
|
||||
author = 'Philip Morlier, Austin Roberts'
|
||||
|
||||
# The full version, including alpha/beta/rc tags
|
||||
@ -63,3 +63,4 @@ html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
|
||||
# relative to this directory. They are copied after the builtin static files,
|
||||
# so a file named "default.css" will overwrite the builtin "default.css".
|
||||
html_static_path = ['_static']
|
||||
master_doc = 'index'
|
||||
|
||||
@ -1,9 +1,9 @@
|
||||
.. _custom:
|
||||
|
||||
|
||||
========================
|
||||
Building a Custom Plugin
|
||||
========================
|
||||
=======================
|
||||
Writing a Custom Plugin
|
||||
=======================
|
||||
|
||||
.. toctree::
|
||||
:hidden:
|
||||
@ -13,24 +13,24 @@ Building a Custom Plugin
|
||||
tracer
|
||||
|
||||
|
||||
Before setting out to build a plugin it will be helpful to be familiar with the :ref:`types`. deifferent plugins will require different implimentation.
|
||||
Before setting out to write a plugin it will be helpful to be familiar with the :ref:`types`. Different plugins will require different implementation.
|
||||
|
||||
Basic Implementation
|
||||
====================
|
||||
|
||||
In general, no matter which type of plugin you intend to build, all will share some common aspects.
|
||||
All plugins will share some common aspects.
|
||||
|
||||
Package
|
||||
-------
|
||||
|
||||
Any plugin will need its own package located in the Plugeth-Plugins packages directory. The package will need to include a main.go from which the .so file will be built. The package and main file should share the same name and the name should be a word that describes the basic functionality of the plugin.
|
||||
Any plugin will need its own package located in ``plugeth-plugins/packages``. The package will need to include a ``main.go`` from which the ``.so`` file will be built. The package and main file should share the same name and the name should be a word that describes the basic functionality of the plugin.
|
||||
|
||||
Initialize
|
||||
----------
|
||||
|
||||
Most plugins will need to be initialized with an Initialize function. The initialize function will need to be passed at least three arguments: a cli.Context, core.PluginLoader, and a core.Logger.
|
||||
Most plugins will need to be initialized with a ``func Initialize``. The initialize function will need to be passed at least three arguments: ``cli.Context``, ``core.PluginLoader``, ``core.Logger``.
|
||||
|
||||
And so, all plugins could have an intial template that looks something like this:
|
||||
All plugins could have an intial template that looks something like this:
|
||||
|
||||
.. code-block:: Go
|
||||
|
||||
@ -51,7 +51,7 @@ And so, all plugins could have an intial template that looks something like this
|
||||
InitializeNode
|
||||
--------------
|
||||
|
||||
Many plugins will make use of the InitializeNode function. Implimentation will look like so:
|
||||
Many plugins will make use of ``func InitializeNode``.
|
||||
|
||||
.. code-block:: Go
|
||||
|
||||
@ -61,7 +61,7 @@ Many plugins will make use of the InitializeNode function. Implimentation will l
|
||||
}
|
||||
|
||||
|
||||
This is called as soon as the Geth node is initialized. The core.Node object represents the running node with p2p and RPC capabilities, while the Backend gives you access to blocks and other data you may need to access.
|
||||
``InitializeNode`` is called as soon as the Geth node is initialized. The ``core.Node`` object represents the running node with P2P and RPC capabilities, while the ``core.Backend`` gives you access to blocks and other data you may need to access.
|
||||
|
||||
Specialization
|
||||
==============
|
||||
@ -79,5 +79,7 @@ From this point implimentation becomes more specialized to the particular plugin
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
.. _blockupdates: https://github.com/openrelayxyz/plugeth-plugins/blob/master/packages/blockupdates/main.go
|
||||
.. _hello: https://github.com/openrelayxyz/plugeth-plugins/blob/master/packages/hello/main.go
|
||||
|
||||
82
docs/existing.rst
Normal file
82
docs/existing.rst
Normal file
@ -0,0 +1,82 @@
|
||||
.. _existing:
|
||||
|
||||
================
|
||||
Existing Pluings
|
||||
================
|
||||
|
||||
getRPCCalls
|
||||
===========
|
||||
|
||||
getRPCCalls is a subcommand written to print a log containing information about RPC methods upon execution. Namely the id, method name, and parameters into the method.
|
||||
|
||||
Usage
|
||||
-----
|
||||
|
||||
Once compiled the plugin will execute automatically as RPC methods are passed into the api.
|
||||
|
||||
isSynced
|
||||
========
|
||||
|
||||
The isSynced plugin was designed as an extention of the ``eth_syncing`` method available on standard Geth. ``plugeth_isSynced`` was desinged to return a status object such that a status report could be given as to the current state of the node as opposed to ``eth_syncing`` which returns the status object only if the node is actively syncing and a simple false if frozen or fully synced.
|
||||
|
||||
|
||||
Usage
|
||||
-----
|
||||
As with all ``rpc`` methods, isSynced is available by ``curl`` or the `javascript console`_.
|
||||
|
||||
From the command line using the ``curl`` command:
|
||||
|
||||
``{"method": "plugeth_isSynced", "params": []}``
|
||||
|
||||
Which will return:
|
||||
|
||||
.. code-block:: Json
|
||||
|
||||
"activePeers": true,
|
||||
"currentBlock": "0x60e880",
|
||||
"healedBytecodeBytes": "0x0",
|
||||
"healedBytecodes": "0x0",
|
||||
"healedTrienodeBytes": "0x0",
|
||||
"healedTrienodes": "0x0",
|
||||
"healingBytecode": "0x0",
|
||||
"healingTrienodes": "0x0",
|
||||
"highestBlock": "0x60e880",
|
||||
"nodeIsSynced": true,
|
||||
"startingBlock": "0x0",
|
||||
"syncedAccountBytes": "0x0",
|
||||
"syncedAccounts": "0x0",
|
||||
"syncedBytecodeBytes": "0x0",
|
||||
"syncedBytecodes": "0x0",
|
||||
"syncedStorage": "0x0",
|
||||
"syncedStorageBytes": "0x0"
|
||||
|
||||
|
||||
|
||||
|
||||
blockTracer
|
||||
===========
|
||||
|
||||
Blocktracer is an subscription plugin written such that for each block mined, blockTracer will return a json payload reporting the type, from and to addresses, gas, gas used, input, output, and calls made for each transaction. The data will stream in real time as the block is mined.
|
||||
|
||||
Usage
|
||||
=====
|
||||
|
||||
As with any websocket an itial connection will need to be established.
|
||||
|
||||
|
||||
Here we are using wscat to connect to local host port 8556.
|
||||
|
||||
``wscat -c "http://127.0.0.1:8556"``
|
||||
|
||||
Once the connection has been made the method as well as blockTracer parameter will be passed in.
|
||||
|
||||
``{"method":"plugeth_subscribe","params":["traceBlock"],"id":0}``
|
||||
|
||||
Which will return a streaming result similar to the one below.
|
||||
|
||||
.. code-block:: Json
|
||||
|
||||
"type":"CALL","from":"0x75d5e88adf8f3597c7c3e4a930544fb48089c779","to":"0x9ac40b4e6a0c60ca54a7fa2753d65448e6a71ecb","gas":"0x58cc2","gasUsed":"0x6007","input":"0x000000000000000000000000000000000000000000000000000000000000000000000000000000000000000028d2f41e4c1dfca58114457fbe07632cabbfb9d900000000000000000000000000000000000000000000000000000000001db898fbdbdd5c","output":"0x0000000000000000000000000000000000000000000000000000000000000000","calls":[{"type":"DELEGATECALL","from":"0x9ac40b4e6a0c60ca54a7fa2753d65448e6a71ecb","to":"0xae9a8ae28d55325dff2af4ed5fe2335c1a39139b","gas":"0x56308","gasUsed":"0x4c07","input":"0x0000000000000000000000000000000000000000000000000000000000000000abbfb9d900000000000000000000000000000000000000000000000000000000001db8980000000000000000000000000000000000000000035298ac0ba8bb05fbdbdd5c","output":"0x0000000000000000000000000000000000000000000000000000000000000000"}]}]}]}}
|
||||
|
||||
|
||||
.. _javascript console: https://geth.ethereum.org/docs/interface/javascript-console
|
||||
@ -2,29 +2,26 @@
|
||||
PluGeth
|
||||
=======
|
||||
|
||||
PluGeth is a fork of the Go Ethereum Client, `Geth`_, that implements a plugin architecture allowing developers to extend Geth's capabilities in a number of different ways using plugins rather than having to create additional new forks.
|
||||
|
||||
From Here:
|
||||
----------
|
||||
|
||||
- Ready for an overview of the project and some context? :ref:`project`
|
||||
- If your goal is to run existing plugns without sourcecode: :ref:`install`
|
||||
- If your goal is to build and deploy existing plugins or make custom plugins: :ref:`build`
|
||||
**The Geth fork to end all Forks.**
|
||||
|
||||
- If your goal is to build cutsom plugins: :ref:`custom`
|
||||
PluGeth is a fork of the Go Ethereum Client, `Geth`_, implementing the Golang plugin architecture allowing developers to adapt and extend Geth's capabilities using plugins rather than having to create additional new forks.
|
||||
|
||||
.. warning:: Right now PluGeth is in early development. We are
|
||||
still settling on some of the plugin APIs, and are
|
||||
not yet making official releases. From an operational
|
||||
perspective, PluGeth should be as stable as upstream Geth less whatever instability is added by plugins you might run. But if you plan to run PluGeth today, be aware that furture updates will likely break your plugins.
|
||||
The PluGeth project aims to provide a secure and versitile tool for anyone who needs to run a Geth (or Geth-derived) node client that supports features beyond those offered by Geth’s vanilla EVM.
|
||||
|
||||
Table of Contents
|
||||
*****************
|
||||
All dependencies and updates are handled by the PluGeth project, and so, PluGeth enables developers to focus on their projects without having to maintian upstream code.
|
||||
|
||||
|
||||
- :ref:`project`
|
||||
- :ref:`install`
|
||||
- :ref:`build`
|
||||
- :ref:`custom`
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
:caption: Overview
|
||||
:hidden:
|
||||
|
||||
project
|
||||
types
|
||||
@ -33,6 +30,7 @@ Table of Contents
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
:caption: Tutorials
|
||||
:hidden:
|
||||
|
||||
install
|
||||
build
|
||||
@ -42,7 +40,9 @@ Table of Contents
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
:caption: Reference
|
||||
:hidden:
|
||||
|
||||
existing
|
||||
system_req
|
||||
version
|
||||
api
|
||||
@ -54,9 +54,15 @@ Table of Contents
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
:caption: Contact
|
||||
:hidden:
|
||||
|
||||
contact
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
.. _Geth: https://geth.ethereum.org/
|
||||
@ -4,15 +4,20 @@
|
||||
Install
|
||||
=======
|
||||
|
||||
PluGeth provides a pre-built PluGeth-Geth node as well as pre-built plugins available for download.
|
||||
.. note:: Prior to install make sure to be familiar with :ref:`system requirements<system_req>`.
|
||||
|
||||
|
||||
First download the latest PluGeth `binary release`_.
|
||||
PluGeth can be installed in two ways. The repositories can be cloned and compiled from the source code. Alternatively PluGeth provides binaries of a PluGeth node as well as plugins.
|
||||
|
||||
In order to run PluGeth without the source code, download the latest `release`_ here.
|
||||
|
||||
Our curated list of plugin builds can be found `here`_
|
||||
The curated list of plugin builds can be found `here`_
|
||||
|
||||
After downloading, move the .so files into the ~/.ethereum/plugins directory.
|
||||
.. note:: Make sure versions of PluGeth and plugins are compatable see: :ref:`version control<version>`.
|
||||
|
||||
After downloading plugins, move the ``.so`` files into the ``~/.ethereum/plugins`` directory.
|
||||
|
||||
.. note:: The above location may change when changing ``--datadir``.
|
||||
|
||||
|
||||
|
||||
@ -21,7 +26,5 @@ After downloading, move the .so files into the ~/.ethereum/plugins directory.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
.. _binary release: https://github.com/openrelayxyz/plugeth/releases
|
||||
.. _release: https://github.com/openrelayxyz/plugeth/releases
|
||||
.. _here: https://github.com/openrelayxyz/plugeth-plugins/releases
|
||||
@ -7,7 +7,7 @@ Project Design
|
||||
Design Goals
|
||||
============
|
||||
|
||||
Upstream Geth exists primarily to serve as a client for the Ethereum mainnet, though it also supports a number of popular testnets. Supporting the Ethereum mainnet is a big enough challenge in its own right that the Geth team generally avoids changes to support other networks, or to provide features only a small handful of users would be interested in.
|
||||
Upstream Geth exists primarily to serve as a client for the Ethereum mainnet, though it also supports a number of popular testnets. The Geth team generally avoids changes to support other networks, or to provide features only a small handful of users would be interested in.
|
||||
|
||||
The result is that many projects have forked Geth. Some implement their own consensus protocols or alter the behavior of the EVM to support other networks. Others are designed to extract information from the Ethereum mainnet in ways the standard Geth client does not support.
|
||||
|
||||
@ -16,14 +16,14 @@ Creating numerous different forks to fill a variety of different needs comes wit
|
||||
PluGeth aims to provide a single Geth fork that developers can choose to extend rather than forking the Geth project. Out of the box, PluGeth behaves exactly like upstream Geth, but by installing plugins written in Golang, developers can extend its functionality in a wide variety of ways.
|
||||
|
||||
Three Repositories
|
||||
==================
|
||||
------------------
|
||||
|
||||
PluGeth is an application built in three repositories:
|
||||
**PluGeth is an application built in three repositories:**
|
||||
|
||||
`PluGeth`_
|
||||
----------
|
||||
|
||||
The largest of the three Repositories, PluGeth is a fork of Geth which has been modified to enable a plugin architecture. The Plugin loader, wrappers, and hooks all reside in this repository.
|
||||
The largest of the three, PluGeth is a fork of Geth which has been modified to enable a plugin architecture. The Plugin loader, wrappers, and hooks all reside in this repository.
|
||||
|
||||
`PluGeth-Utils`_
|
||||
----------------
|
||||
@ -38,7 +38,7 @@ The packages from which plugins are buile are stored here. This repository conta
|
||||
Version Control
|
||||
*****************
|
||||
|
||||
In order to ensure that the the project can compile and is up to date see: :ref:`version`; to be familiar with dependencies and requirements.
|
||||
Before using Plugeth users are enocuraged to familiarize themselves with the :ref:`version control<version>` scheme of the project.
|
||||
|
||||
|
||||
|
||||
|
||||
@ -4,6 +4,15 @@
|
||||
System Requirements
|
||||
===================
|
||||
|
||||
System requirements will vary depending on which network you are connecting to. On the Ethereum mainnet, you should have at least 8 GB RAM, 2 CPUs, and 350 GB of SSD disks.
|
||||
If compiling from source code Plugeth requires that the user have `Go`_ version 1.17 or later.
|
||||
|
||||
PluGeth relies on Golang's Plugin implementation, which is only supported on Linux, FreeBSD, and macOS. Windows support is unlikely to be added in the foreseeable future.
|
||||
Our provided release binaries require `Glibc`_ 2.29.
|
||||
|
||||
.. note:: System requirements vary depending on the network being run. For detailed requirements Refer to `Geth`_ documentation.
|
||||
|
||||
.. warning:: PluGeth relies on Golang's Plugin implementation, which is only supported on Linux, FreeBSD, and macOS. Windows support is unlikely to be added in the foreseeable future.
|
||||
|
||||
|
||||
.. _Go: https://go.dev/dl/
|
||||
.. _Glibc: https://pkgs.org/download/glibc
|
||||
.. _Geth: https://ethereum.org/en/developers/docs/nodes-and-clients/#requirements
|
||||
@ -6,23 +6,21 @@ Basic Types of Plugins
|
||||
|
||||
While PluGeth has been designed to be versatile and customizable, when learning the project it can be helpful to think of plugins as being of four different archetypes.
|
||||
|
||||
.. contents:: :local:
|
||||
|
||||
RPC Methods
|
||||
-----------
|
||||
|
||||
These plugins provide new json rpc methods to access several objects containing real time and historic data.
|
||||
|
||||
|
||||
Subcommand
|
||||
------------
|
||||
|
||||
A subcommand redifines the total behavior of Geth and could stand on its own. In contrast with the other plugin types which, in general, are meant to capture and manipulate information, a subcommand is meant to change to overall behavior of Geth. It may do this in order to capture information but the primary fuctionality is a modulation of geth behaviour.
|
||||
A subcommand redifines the total behavior of Geth and could stand on its own. In contrast with the other plugin types which, in general, are meant to capture and manipulate information, a subcommand is meant to change the overall behavior of Geth. It may do this in order to capture information but the primary fuctionality is a modulation of geth behaviour.
|
||||
|
||||
Tracers
|
||||
-------
|
||||
|
||||
Tracers rely on historic data recompiled after execution to give insight into a transaction.
|
||||
Tracers are used to collect information about a transaction or block during EVM execution. They can be written to refine the results of a ``debug`` trace or written to delver custom data using various other objects available from the PluGeth APIs.
|
||||
|
||||
Subscriptions
|
||||
-------------
|
||||
|
||||
@ -1,8 +1,8 @@
|
||||
.. _version:
|
||||
|
||||
=======
|
||||
Version
|
||||
=======
|
||||
===============
|
||||
Version Control
|
||||
===============
|
||||
|
||||
PluGeth is separated into three packages in order to minimize dependency conflicts. Golang plugins cannot include different versions of the same packages as the program loading the plugin. If plugins had to import packages from PluGeth itself, a plugin build could only be loaded by that same version of PluGeth. By separating out the PluGeth-utils package, both PluGeth and the plugins must rely on the same version of PluGeth-utils, but plugins can be compatible with any version of PluGeth compiled with the same version of PluGeth-utils.
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user