Updated toctree with further development of scope.
This commit is contained in:
philip-morlier
Austin Roberts
parent
d3514eaccb
commit
daa7b44fef
Binary file not shown.
BIN
documentation/_build/doctrees/api.doctree
Normal file
BIN
documentation/_build/doctrees/api.doctree
Normal file
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
BIN
documentation/_build/doctrees/plugin_hooks.doctree
Normal file
BIN
documentation/_build/doctrees/plugin_hooks.doctree
Normal file
Binary file not shown.
BIN
documentation/_build/doctrees/plugin_loader.doctree
Normal file
BIN
documentation/_build/doctrees/plugin_loader.doctree
Normal file
Binary file not shown.
Binary file not shown.
@ -1,4 +1,4 @@
|
||||
# Sphinx build info version 1
|
||||
# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
|
||||
config: d325def9cbc62f774a29b7fa152439a4
|
||||
config: aa952c05dc8678fa4bab1d866c89bf40
|
||||
tags: 645f666f9bcd5a90fca523b33c5a78b7
|
||||
|
||||
@ -1,122 +1,7 @@
|
||||
.. _anatomy:
|
||||
|
||||
===================
|
||||
Anatomy of a Plugin
|
||||
===================
|
||||
==============
|
||||
Plugin Anatomy
|
||||
==============
|
||||
|
||||
Plugins for Plugeth use Golang's `Native Plugin System`_. Plugin modules must export variables using specific names and types. These will be processed by the plugin loader, and invoked at certain points during Geth's operations.
|
||||
|
||||
API
|
||||
***
|
||||
|
||||
Flags
|
||||
-----
|
||||
|
||||
* **Name:** Flags
|
||||
* **Type:** `flag.FlagSet`_
|
||||
* **Behavior:** This FlagSet will be parsed and your plugin will be able to access the resulting flags. Flags will be passed to Geth from the command line and are intended to of the plugin. Note that if any flags are provided, certain checks are disabled within Geth to avoid failing due to unexpected flags.
|
||||
|
||||
Subcommands
|
||||
-----------
|
||||
|
||||
* **Name:** Subcommands
|
||||
* **Type:** map[string]func(ctx `*cli.Context`_, args []string) error
|
||||
* **Behavior:** If Geth is invoked with ``./geth YOUR_COMMAND``, the plugin loader will look for ``YOUR_COMMAND`` within this map, and invoke the corresponding function. This can be useful for certain behaviors like manipulating Geth's database without having to build a separate binary.
|
||||
|
||||
Initialize
|
||||
----------
|
||||
|
||||
* **Name:** Initialize
|
||||
* **Type:** func(*cli.Context, core.PluginLoader, core.logs )
|
||||
* **Behavior:** Called as soon as the plugin is loaded, with the cli context and a reference to the plugin loader. This is your plugin's opportunity to initialize required variables as needed. Note that using the context object you can check arguments, and optionally can manipulate arguments if needed for your plugin.
|
||||
:ref:`Core vs Restricted packages in Plugeth-utils`
|
||||
|
||||
**todo: explain that plugin could provide node.Node with restricted.backend**
|
||||
|
||||
InitializeNode
|
||||
--------------
|
||||
|
||||
* **Name:** InitializeNode
|
||||
* **Type:** func(core.Node, core.Backend)
|
||||
* **Behavior:** 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 a wide array of data you may need to access.
|
||||
|
||||
Tracers
|
||||
-------
|
||||
|
||||
* **Name:** Tracers
|
||||
* **Type:** map[string]TracerResult
|
||||
* **Behavior:** When calling debug.traceX functions (such as ``debug_traceCall`` and ``debug_traceTransaction``) the tracer can be specified as a key to this map and the tracer used will be the TracerResult specified here. TracerResult objects must match the interface:
|
||||
|
||||
.. code-block:: go
|
||||
|
||||
``// CaptureStart is called at the start of each transaction
|
||||
CaptureStart(env core.EVM, from core.Address, to core.Address, create bool, input []byte, gas uint64, value *big.Int) {}
|
||||
// CaptureState is called for each opcode
|
||||
CaptureState(env core.EVM, pc uint64, op core.OpCode, gas, cost uint64, scope *vm.ScopeContext, rData []byte, depth int, err error) {}
|
||||
// CaptureFault is called when an error occurs in the EVM
|
||||
CaptureFault(env core.EVM, pc uint64, op core.OpCode, gas, cost uint64, scope *vm.ScopeContext, depth int, err error) {}
|
||||
// CaptureEnd is called at the end of each transaction
|
||||
CaptureEnd(output []byte, gasUsed uint64, t time.Duration, err error) {}
|
||||
// GetResult should return a JSON serializable result object to respond to the trace call
|
||||
GetResult() (interface{}, error) {}``
|
||||
|
||||
|
||||
.. warning:: Modifying the values passed into tracer functions can alter the
|
||||
results of the EVM execution in unpredictable ways. Additonally, some objects may be reused acress calls, so data you wish to capture should be copied rather than retianed by reference.
|
||||
|
||||
LiveTracer
|
||||
----------
|
||||
|
||||
* **Name:** LiveTracers
|
||||
* **Type:** core.Tracer
|
||||
* **Behavior:** This tracer is used for tracing transactions as they are processed within blocks. Note that if a block does not validate, some transactions may be processed that don't end up in blocks, so be sure to check transactions against finalized blocks.
|
||||
|
||||
The interface for a vm.Tracer is similar to a TracerResult (above), but does not require a ``GetResult()`` function.
|
||||
|
||||
GetAPIs
|
||||
-------
|
||||
|
||||
* **Name:** GetAPIs
|
||||
* **Type:** func(core.Node, core.Backend) []rpc.API
|
||||
* **Behavior:** This allows you to register new RPC methods to run within Geth.
|
||||
|
||||
The GetAPIs function itself will generally be fairly brief, and will looks something like this:
|
||||
|
||||
.. code-block:: go
|
||||
|
||||
``func GetAPIs(stack *node.Node, backend core.Backend) []core.API {
|
||||
return []rpc.API{
|
||||
{
|
||||
Namespace: "mynamespace",
|
||||
Version: "1.0",
|
||||
Service: &MyService{backend},
|
||||
Public: true,
|
||||
},
|
||||
}
|
||||
}``
|
||||
|
||||
The bulk of the implementation will be in the ``MyService`` struct. MyService should be a struct with public functions. These functions can have two different types of signatures:
|
||||
|
||||
* RPC Calls: For straight RPC calls, a function should have a ``context.Context`` object as the first argument, followed by an arbitrary number of JSON marshallable arguments, and return either a single JSON marshal object, or a JSON marshallable object and an error. The RPC framework will take care of decoding inputs to this function and encoding outputs, and if the error is non-nil it will serve an error response.
|
||||
|
||||
* Subscriptions: For subscriptions (supported on IPC and websockets), a function should have a ``context.Context`` object as the first argument followed by an arbitrary number of JSON marshallable arguments, and should return an ``*rpc.Subscription`` object. The subscription object can be created with ``rpcSub := notifier.CreateSubscription()``, and JSON marshallable data can be sent to the subscriber with ``notifier.Notify(rpcSub.ID, b)``.
|
||||
|
||||
A very simple MyService might look like:
|
||||
|
||||
.. code-block:: go
|
||||
|
||||
``type MyService struct{}
|
||||
|
||||
func (h MyService) HelloWorld(ctx context.Context) string {
|
||||
return "Hello World"
|
||||
}``
|
||||
|
||||
And the client could access this with an rpc call to
|
||||
``mynamespace_helloworld``
|
||||
|
||||
|
||||
|
||||
|
||||
.. _*cli.Context: https://pkg.go.dev/github.com/urfave/cli#Context
|
||||
.. _flag.FlagSet: https://pkg.go.dev/flag#FlagSet
|
||||
.. _Native Plugin System: https://pkg.go.dev/plugin
|
||||
.. todo:: fill in disections of archetypal plugins
|
||||
120
documentation/_build/html/_sources/api.rst.txt
Normal file
120
documentation/_build/html/_sources/api.rst.txt
Normal file
@ -0,0 +1,120 @@
|
||||
.. _api:
|
||||
|
||||
===
|
||||
API
|
||||
===
|
||||
|
||||
Plugins for Plugeth use Golang's `Native Plugin System`_. Plugin modules must export variables using specific names and types. These will be processed by the plugin loader, and invoked at certain points during Geth's operations.
|
||||
|
||||
Flags
|
||||
-----
|
||||
|
||||
* **Name:** Flags
|
||||
* **Type:** `flag.FlagSet`_
|
||||
* **Behavior:** This FlagSet will be parsed and your plugin will be able to access the resulting flags. Flags will be passed to Geth from the command line and are intended to of the plugin. Note that if any flags are provided, certain checks are disabled within Geth to avoid failing due to unexpected flags.
|
||||
|
||||
Subcommands
|
||||
-----------
|
||||
|
||||
* **Name:** Subcommands
|
||||
* **Type:** map[string]func(ctx `*cli.Context`_, args []string) error
|
||||
* **Behavior:** If Geth is invoked with ``./geth YOUR_COMMAND``, the plugin loader will look for ``YOUR_COMMAND`` within this map, and invoke the corresponding function. This can be useful for certain behaviors like manipulating Geth's database without having to build a separate binary.
|
||||
|
||||
Initialize
|
||||
----------
|
||||
|
||||
* **Name:** Initialize
|
||||
* **Type:** func(*cli.Context, core.PluginLoader, core.logs )
|
||||
* **Behavior:** Called as soon as the plugin is loaded, with the cli context and a reference to the plugin loader. This is your plugin's opportunity to initialize required variables as needed. Note that using the context object you can check arguments, and optionally can manipulate arguments if needed for your plugin.
|
||||
|
||||
.. todo:: explain that plugin could provide node.Node with
|
||||
restricted.backend
|
||||
|
||||
InitializeNode
|
||||
--------------
|
||||
|
||||
* **Name:** InitializeNode
|
||||
* **Type:** func(core.Node, core.Backend)
|
||||
* **Behavior:** 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 a wide array of data you may need to access.
|
||||
|
||||
Tracers
|
||||
-------
|
||||
|
||||
* **Name:** Tracers
|
||||
* **Type:** map[string]TracerResult
|
||||
* **Behavior:** When calling debug.traceX functions (such as ``debug_traceCall`` and ``debug_traceTransaction``) the tracer can be specified as a key to this map and the tracer used will be the TracerResult specified here. TracerResult objects must match the interface:
|
||||
|
||||
.. code-block:: go
|
||||
|
||||
``// CaptureStart is called at the start of each transaction
|
||||
CaptureStart(env core.EVM, from core.Address, to core.Address, create bool, input []byte, gas uint64, value *big.Int) {}
|
||||
// CaptureState is called for each opcode
|
||||
CaptureState(env core.EVM, pc uint64, op core.OpCode, gas, cost uint64, scope *vm.ScopeContext, rData []byte, depth int, err error) {}
|
||||
// CaptureFault is called when an error occurs in the EVM
|
||||
CaptureFault(env core.EVM, pc uint64, op core.OpCode, gas, cost uint64, scope *vm.ScopeContext, depth int, err error) {}
|
||||
// CaptureEnd is called at the end of each transaction
|
||||
CaptureEnd(output []byte, gasUsed uint64, t time.Duration, err error) {}
|
||||
// GetResult should return a JSON serializable result object to respond to the trace call
|
||||
GetResult() (interface{}, error) {}``
|
||||
|
||||
|
||||
.. warning:: Modifying the values passed into tracer functions can
|
||||
alter the
|
||||
results of the EVM execution in unpredictable ways. Additonally, some objects may be reused acress calls, so data you wish to capture should be copied rather than retianed by reference.
|
||||
|
||||
LiveTracer
|
||||
----------
|
||||
|
||||
* **Name:** LiveTracers
|
||||
* **Type:** core.Tracer
|
||||
* **Behavior:** This tracer is used for tracing transactions as they are processed within blocks. Note that if a block does not validate, some transactions may be processed that don't end up in blocks, so be sure to check transactions against finalized blocks.
|
||||
|
||||
The interface for a vm.Tracer is similar to a TracerResult (above), but does not require a ``GetResult()`` function.
|
||||
|
||||
GetAPIs
|
||||
-------
|
||||
|
||||
* **Name:** GetAPIs
|
||||
* **Type:** func(core.Node, core.Backend) []rpc.API
|
||||
* **Behavior:** This allows you to register new RPC methods to run within Geth.
|
||||
|
||||
The GetAPIs function itself will generally be fairly brief, and will looks something like this:
|
||||
|
||||
.. code-block:: go
|
||||
|
||||
``func GetAPIs(stack *node.Node, backend core.Backend) []core.API {
|
||||
return []rpc.API{
|
||||
{
|
||||
Namespace: "mynamespace",
|
||||
Version: "1.0",
|
||||
Service: &MyService{backend},
|
||||
Public: true,
|
||||
},
|
||||
}
|
||||
}``
|
||||
|
||||
The bulk of the implementation will be in the ``MyService`` struct. MyService should be a struct with public functions. These functions can have two different types of signatures:
|
||||
|
||||
* RPC Calls: For straight RPC calls, a function should have a ``context.Context`` object as the first argument, followed by an arbitrary number of JSON marshallable arguments, and return either a single JSON marshal object, or a JSON marshallable object and an error. The RPC framework will take care of decoding inputs to this function and encoding outputs, and if the error is non-nil it will serve an error response.
|
||||
|
||||
* Subscriptions: For subscriptions (supported on IPC and websockets), a function should have a ``context.Context`` object as the first argument followed by an arbitrary number of JSON marshallable arguments, and should return an ``*rpc.Subscription`` object. The subscription object can be created with ``rpcSub := notifier.CreateSubscription()``, and JSON marshallable data can be sent to the subscriber with ``notifier.Notify(rpcSub.ID, b)``.
|
||||
|
||||
A very simple MyService might look like:
|
||||
|
||||
.. code-block:: go
|
||||
|
||||
``type MyService struct{}
|
||||
|
||||
func (h MyService) HelloWorld(ctx context.Context) string {
|
||||
return "Hello World"
|
||||
}``
|
||||
|
||||
And the client could access this with an rpc call to
|
||||
``mynamespace_helloworld``
|
||||
|
||||
|
||||
|
||||
|
||||
.. _*cli.Context: https://pkg.go.dev/github.com/urfave/cli#Context
|
||||
.. _flag.FlagSet: https://pkg.go.dev/flag#FlagSet
|
||||
.. _Native Plugin System: https://pkg.go.dev/plugin
|
||||
@ -1,7 +1,8 @@
|
||||
.. _build:
|
||||
|
||||
Build
|
||||
=====
|
||||
================
|
||||
Build and Deploy
|
||||
================
|
||||
|
||||
.. contents:: :local:
|
||||
|
||||
|
||||
@ -4,4 +4,5 @@
|
||||
Core vs Restricted packages in Plugeth-utils
|
||||
============================================
|
||||
|
||||
**todo: copy on core and restricted packages in utils. what, why, how.**
|
||||
|
||||
.. todo:: need explinations of core vs restircted functionality. what, why, how.
|
||||
@ -4,5 +4,4 @@
|
||||
Plugin Hooks
|
||||
============
|
||||
|
||||
|
||||
**todo: discussion on plugin hooks**
|
||||
.. todo:: discussion of plugin hooks
|
||||
|
||||
@ -8,11 +8,12 @@ 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 of Geth.
|
||||
|
||||
**WARNING: UNSTABLE API**
|
||||
.. 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 isstability is added by plugins you might run. But if you plan to run PluGeth today, be aware that furture updates will likely break you plugins.
|
||||
|
||||
|
||||
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 future updates will likely break your plugins.
|
||||
|
||||
|
||||
Table of Contents
|
||||
*****************
|
||||
@ -27,6 +28,7 @@ Table of Contents
|
||||
hooks
|
||||
anatomy
|
||||
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
:caption: Tutorials
|
||||
@ -37,8 +39,11 @@ Table of Contents
|
||||
:maxdepth: 1
|
||||
:caption: Reference
|
||||
|
||||
sytem_req
|
||||
system_req
|
||||
plugin_loader
|
||||
plugin_hooks
|
||||
core_restricted
|
||||
api
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
7
documentation/_build/html/_sources/plugin_hooks.rst.txt
Normal file
7
documentation/_build/html/_sources/plugin_hooks.rst.txt
Normal file
@ -0,0 +1,7 @@
|
||||
.. _plugin_hooks:
|
||||
|
||||
============
|
||||
Plugin Hooks
|
||||
============
|
||||
|
||||
.. todo:: guide to writing plugin hooks
|
||||
7
documentation/_build/html/_sources/plugin_loader.rst.txt
Normal file
7
documentation/_build/html/_sources/plugin_loader.rst.txt
Normal file
@ -0,0 +1,7 @@
|
||||
.. _plugin_loader:
|
||||
|
||||
=============
|
||||
Plugin Loader
|
||||
=============
|
||||
|
||||
.. todo:: breakdown of plugin loader function
|
||||
@ -37,14 +37,14 @@ Plugins are packages which contain premade plugins as well as a location provide
|
||||
Dependency Scheme
|
||||
-----------------
|
||||
|
||||
**todo: copy on version number protocol**
|
||||
.. todo:: needs elaboration of dependency scheme
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
.. _obscures security updates as optimixations: https://blog.openrelay.xyz/vulnerability-lifecycle-framework-geth/
|
||||
.. _obscures security updates as optimizations: https://blog.openrelay.xyz/vulnerability-lifecycle-framework-geth/
|
||||
.. _PluGeth: https://github.com/openrelayxyz/plugeth
|
||||
.. _PluGeth-Utils: https://github.com/openrelayxyz/plugeth-utils
|
||||
.. _PluGeth-Plugins: https://github.com/openrelayxyz/plugeth-plugin
|
||||
@ -3,7 +3,7 @@
|
||||
<head>
|
||||
<meta charset="utf-8" />
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
|
||||
<title>Anatomy of a Plugin — Plugeth Austin Roberts documentation</title><link rel="stylesheet" href="_static/css/theme.css" type="text/css" />
|
||||
<title>Plugin Anatomy — Plugeth Austin Roberts documentation</title><link rel="stylesheet" href="_static/css/theme.css" type="text/css" />
|
||||
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
|
||||
<!--[if lt IE 9]>
|
||||
<script src="_static/js/html5shiv.min.js"></script>
|
||||
@ -15,7 +15,7 @@
|
||||
<script src="_static/js/theme.js"></script>
|
||||
<link rel="index" title="Index" href="genindex.html" />
|
||||
<link rel="search" title="Search" href="search.html" />
|
||||
<link rel="next" title="Build" href="build.html" />
|
||||
<link rel="next" title="Build and Deploy" href="build.html" />
|
||||
<link rel="prev" title="Plugin Hooks" href="hooks.html" />
|
||||
</head>
|
||||
|
||||
@ -39,27 +39,19 @@
|
||||
<li class="toctree-l1"><a class="reference internal" href="project.html">Project Design</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="types.html">Basic Types of Plugins</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="hooks.html">Plugin Hooks</a></li>
|
||||
<li class="toctree-l1 current"><a class="current reference internal" href="#">Anatomy of a Plugin</a><ul>
|
||||
<li class="toctree-l2"><a class="reference internal" href="#api">API</a><ul>
|
||||
<li class="toctree-l3"><a class="reference internal" href="#flags">Flags</a></li>
|
||||
<li class="toctree-l3"><a class="reference internal" href="#subcommands">Subcommands</a></li>
|
||||
<li class="toctree-l3"><a class="reference internal" href="#initialize">Initialize</a></li>
|
||||
<li class="toctree-l3"><a class="reference internal" href="#initializenode">InitializeNode</a></li>
|
||||
<li class="toctree-l3"><a class="reference internal" href="#tracers">Tracers</a></li>
|
||||
<li class="toctree-l3"><a class="reference internal" href="#livetracer">LiveTracer</a></li>
|
||||
<li class="toctree-l3"><a class="reference internal" href="#getapis">GetAPIs</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
</ul>
|
||||
</li>
|
||||
<li class="toctree-l1 current"><a class="current reference internal" href="#">Plugin Anatomy</a></li>
|
||||
</ul>
|
||||
<p class="caption"><span class="caption-text">Tutorials</span></p>
|
||||
<ul>
|
||||
<li class="toctree-l1"><a class="reference internal" href="build.html">Build</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="build.html">Build and Deploy</a></li>
|
||||
</ul>
|
||||
<p class="caption"><span class="caption-text">Reference</span></p>
|
||||
<ul>
|
||||
<li class="toctree-l1"><a class="reference internal" href="system_req.html">System Requirements</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="plugin_loader.html">Plugin Loader</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="plugin_hooks.html">Plugin Hooks</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="core_restricted.html">Core vs Restricted packages in Plugeth-utils</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="api.html">API</a></li>
|
||||
</ul>
|
||||
<p class="caption"><span class="caption-text">Contact</span></p>
|
||||
<ul>
|
||||
@ -80,7 +72,7 @@
|
||||
<div role="navigation" aria-label="Page navigation">
|
||||
<ul class="wy-breadcrumbs">
|
||||
<li><a href="index.html" class="icon icon-home"></a> »</li>
|
||||
<li>Anatomy of a Plugin</li>
|
||||
<li>Plugin Anatomy</li>
|
||||
<li class="wy-breadcrumbs-aside">
|
||||
<a href="_sources/anatomy.rst.txt" rel="nofollow"> View page source</a>
|
||||
</li>
|
||||
@ -90,115 +82,11 @@
|
||||
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
|
||||
<div itemprop="articleBody">
|
||||
|
||||
<div class="section" id="anatomy-of-a-plugin">
|
||||
<span id="anatomy"></span><h1>Anatomy of a Plugin<a class="headerlink" href="#anatomy-of-a-plugin" title="Permalink to this headline">¶</a></h1>
|
||||
<p>Plugins for Plugeth use Golang’s <a class="reference external" href="https://pkg.go.dev/plugin">Native Plugin System</a>. Plugin modules must export variables using specific names and types. These will be processed by the plugin loader, and invoked at certain points during Geth’s operations.</p>
|
||||
<div class="section" id="api">
|
||||
<h2>API<a class="headerlink" href="#api" title="Permalink to this headline">¶</a></h2>
|
||||
<div class="section" id="flags">
|
||||
<h3>Flags<a class="headerlink" href="#flags" title="Permalink to this headline">¶</a></h3>
|
||||
<ul class="simple">
|
||||
<li><p><strong>Name:</strong> Flags</p></li>
|
||||
<li><p><strong>Type:</strong> <a class="reference external" href="https://pkg.go.dev/flag#FlagSet">flag.FlagSet</a></p></li>
|
||||
<li><p><strong>Behavior:</strong> This FlagSet will be parsed and your plugin will be able to access the resulting flags. Flags will be passed to Geth from the command line and are intended to of the plugin. Note that if any flags are provided, certain checks are disabled within Geth to avoid failing due to unexpected flags.</p></li>
|
||||
</ul>
|
||||
</div>
|
||||
<div class="section" id="subcommands">
|
||||
<h3>Subcommands<a class="headerlink" href="#subcommands" title="Permalink to this headline">¶</a></h3>
|
||||
<ul class="simple">
|
||||
<li><p><strong>Name:</strong> Subcommands</p></li>
|
||||
<li><p><strong>Type:</strong> map[string]func(ctx <a class="reference external" href="https://pkg.go.dev/github.com/urfave/cli#Context">*cli.Context</a>, args []string) error</p></li>
|
||||
<li><p><strong>Behavior:</strong> If Geth is invoked with <code class="docutils literal notranslate"><span class="pre">./geth</span> <span class="pre">YOUR_COMMAND</span></code>, the plugin loader will look for <code class="docutils literal notranslate"><span class="pre">YOUR_COMMAND</span></code> within this map, and invoke the corresponding function. This can be useful for certain behaviors like manipulating Geth’s database without having to build a separate binary.</p></li>
|
||||
</ul>
|
||||
</div>
|
||||
<div class="section" id="initialize">
|
||||
<h3>Initialize<a class="headerlink" href="#initialize" title="Permalink to this headline">¶</a></h3>
|
||||
<ul class="simple">
|
||||
<li><p><strong>Name:</strong> Initialize</p></li>
|
||||
<li><p><strong>Type:</strong> func(<a href="#id1"><span class="problematic" id="id2">*</span></a>cli.Context, core.PluginLoader, core.logs )</p></li>
|
||||
<li><p><strong>Behavior:</strong> Called as soon as the plugin is loaded, with the cli context and a reference to the plugin loader. This is your plugin’s opportunity to initialize required variables as needed. Note that using the context object you can check arguments, and optionally can manipulate arguments if needed for your plugin.</p></li>
|
||||
</ul>
|
||||
<p><span class="xref std std-ref">Core vs Restricted packages in Plugeth-utils</span></p>
|
||||
<p><strong>todo: explain that plugin could provide node.Node with restricted.backend</strong></p>
|
||||
</div>
|
||||
<div class="section" id="initializenode">
|
||||
<h3>InitializeNode<a class="headerlink" href="#initializenode" title="Permalink to this headline">¶</a></h3>
|
||||
<ul class="simple">
|
||||
<li><p><strong>Name:</strong> InitializeNode</p></li>
|
||||
<li><p><strong>Type:</strong> func(core.Node, core.Backend)</p></li>
|
||||
<li><p><strong>Behavior:</strong> 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 a wide array of data you may need to access.</p></li>
|
||||
</ul>
|
||||
</div>
|
||||
<div class="section" id="tracers">
|
||||
<h3>Tracers<a class="headerlink" href="#tracers" title="Permalink to this headline">¶</a></h3>
|
||||
<ul class="simple">
|
||||
<li><p><strong>Name:</strong> Tracers</p></li>
|
||||
<li><p><strong>Type:</strong> map[string]TracerResult</p></li>
|
||||
<li><p><strong>Behavior:</strong> When calling debug.traceX functions (such as <code class="docutils literal notranslate"><span class="pre">debug_traceCall</span></code> and <code class="docutils literal notranslate"><span class="pre">debug_traceTransaction</span></code>) the tracer can be specified as a key to this map and the tracer used will be the TracerResult specified here. TracerResult objects must match the interface:</p></li>
|
||||
</ul>
|
||||
<div class="highlight-go notranslate"><div class="highlight"><pre><span></span><span class="s">``</span><span class="c1">// CaptureStart is called at the start of each transaction</span>
|
||||
<span class="nx">CaptureStart</span><span class="p">(</span><span class="nx">env</span> <span class="nx">core</span><span class="p">.</span><span class="nx">EVM</span><span class="p">,</span> <span class="nx">from</span> <span class="nx">core</span><span class="p">.</span><span class="nx">Address</span><span class="p">,</span> <span class="nx">to</span> <span class="nx">core</span><span class="p">.</span><span class="nx">Address</span><span class="p">,</span> <span class="nx">create</span> <span class="kt">bool</span><span class="p">,</span> <span class="nx">input</span> <span class="p">[]</span><span class="kt">byte</span><span class="p">,</span> <span class="nx">gas</span> <span class="kt">uint64</span><span class="p">,</span> <span class="nx">value</span> <span class="o">*</span><span class="nx">big</span><span class="p">.</span><span class="nx">Int</span><span class="p">)</span> <span class="p">{}</span>
|
||||
<span class="c1">// CaptureState is called for each opcode</span>
|
||||
<span class="nx">CaptureState</span><span class="p">(</span><span class="nx">env</span> <span class="nx">core</span><span class="p">.</span><span class="nx">EVM</span><span class="p">,</span> <span class="nx">pc</span> <span class="kt">uint64</span><span class="p">,</span> <span class="nx">op</span> <span class="nx">core</span><span class="p">.</span><span class="nx">OpCode</span><span class="p">,</span> <span class="nx">gas</span><span class="p">,</span> <span class="nx">cost</span> <span class="kt">uint64</span><span class="p">,</span> <span class="nx">scope</span> <span class="o">*</span><span class="nx">vm</span><span class="p">.</span><span class="nx">ScopeContext</span><span class="p">,</span> <span class="nx">rData</span> <span class="p">[]</span><span class="kt">byte</span><span class="p">,</span> <span class="nx">depth</span> <span class="kt">int</span><span class="p">,</span> <span class="nx">err</span> <span class="kt">error</span><span class="p">)</span> <span class="p">{}</span>
|
||||
<span class="c1">// CaptureFault is called when an error occurs in the EVM</span>
|
||||
<span class="nx">CaptureFault</span><span class="p">(</span><span class="nx">env</span> <span class="nx">core</span><span class="p">.</span><span class="nx">EVM</span><span class="p">,</span> <span class="nx">pc</span> <span class="kt">uint64</span><span class="p">,</span> <span class="nx">op</span> <span class="nx">core</span><span class="p">.</span><span class="nx">OpCode</span><span class="p">,</span> <span class="nx">gas</span><span class="p">,</span> <span class="nx">cost</span> <span class="kt">uint64</span><span class="p">,</span> <span class="nx">scope</span> <span class="o">*</span><span class="nx">vm</span><span class="p">.</span><span class="nx">ScopeContext</span><span class="p">,</span> <span class="nx">depth</span> <span class="kt">int</span><span class="p">,</span> <span class="nx">err</span> <span class="kt">error</span><span class="p">)</span> <span class="p">{}</span>
|
||||
<span class="c1">// CaptureEnd is called at the end of each transaction</span>
|
||||
<span class="nx">CaptureEnd</span><span class="p">(</span><span class="nx">output</span> <span class="p">[]</span><span class="kt">byte</span><span class="p">,</span> <span class="nx">gasUsed</span> <span class="kt">uint64</span><span class="p">,</span> <span class="nx">t</span> <span class="nx">time</span><span class="p">.</span><span class="nx">Duration</span><span class="p">,</span> <span class="nx">err</span> <span class="kt">error</span><span class="p">)</span> <span class="p">{}</span>
|
||||
<span class="c1">// GetResult should return a JSON serializable result object to respond to the trace call</span>
|
||||
<span class="nx">GetResult</span><span class="p">()</span> <span class="p">(</span><span class="kd">interface</span><span class="p">{},</span> <span class="kt">error</span><span class="p">)</span> <span class="p">{}</span><span class="s">``</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<div class="admonition warning">
|
||||
<p class="admonition-title">Warning</p>
|
||||
<p>Modifying the values passed into tracer functions can alter the
|
||||
results of the EVM execution in unpredictable ways. Additonally, some objects may be reused acress calls, so data you wish to capture should be copied rather than retianed by reference.</p>
|
||||
</div>
|
||||
</div>
|
||||
<div class="section" id="livetracer">
|
||||
<h3>LiveTracer<a class="headerlink" href="#livetracer" title="Permalink to this headline">¶</a></h3>
|
||||
<ul class="simple">
|
||||
<li><p><strong>Name:</strong> LiveTracers</p></li>
|
||||
<li><p><strong>Type:</strong> core.Tracer</p></li>
|
||||
<li><p><strong>Behavior:</strong> This tracer is used for tracing transactions as they are processed within blocks. Note that if a block does not validate, some transactions may be processed that don’t end up in blocks, so be sure to check transactions against finalized blocks.</p></li>
|
||||
</ul>
|
||||
<p>The interface for a vm.Tracer is similar to a TracerResult (above), but does not require a <code class="docutils literal notranslate"><span class="pre">GetResult()</span></code> function.</p>
|
||||
</div>
|
||||
<div class="section" id="getapis">
|
||||
<h3>GetAPIs<a class="headerlink" href="#getapis" title="Permalink to this headline">¶</a></h3>
|
||||
<ul class="simple">
|
||||
<li><p><strong>Name:</strong> GetAPIs</p></li>
|
||||
<li><p><strong>Type:</strong> func(core.Node, core.Backend) []rpc.API</p></li>
|
||||
<li><p><strong>Behavior:</strong> This allows you to register new RPC methods to run within Geth.</p></li>
|
||||
</ul>
|
||||
<p>The GetAPIs function itself will generally be fairly brief, and will looks something like this:</p>
|
||||
<div class="highlight-go notranslate"><div class="highlight"><pre><span></span> <span class="s">``</span><span class="kd">func</span> <span class="nx">GetAPIs</span><span class="p">(</span><span class="nx">stack</span> <span class="o">*</span><span class="nx">node</span><span class="p">.</span><span class="nx">Node</span><span class="p">,</span> <span class="nx">backend</span> <span class="nx">core</span><span class="p">.</span><span class="nx">Backend</span><span class="p">)</span> <span class="p">[]</span><span class="nx">core</span><span class="p">.</span><span class="nx">API</span> <span class="p">{</span>
|
||||
<span class="k">return</span> <span class="p">[]</span><span class="nx">rpc</span><span class="p">.</span><span class="nx">API</span><span class="p">{</span>
|
||||
<span class="p">{</span>
|
||||
<span class="nx">Namespace</span><span class="p">:</span> <span class="s">"mynamespace"</span><span class="p">,</span>
|
||||
<span class="nx">Version</span><span class="p">:</span> <span class="s">"1.0"</span><span class="p">,</span>
|
||||
<span class="nx">Service</span><span class="p">:</span> <span class="o">&</span><span class="nx">MyService</span><span class="p">{</span><span class="nx">backend</span><span class="p">},</span>
|
||||
<span class="nx">Public</span><span class="p">:</span> <span class="kc">true</span><span class="p">,</span>
|
||||
<span class="p">},</span>
|
||||
<span class="p">}</span>
|
||||
<span class="p">}</span><span class="s">``</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>The bulk of the implementation will be in the <code class="docutils literal notranslate"><span class="pre">MyService</span></code> struct. MyService should be a struct with public functions. These functions can have two different types of signatures:</p>
|
||||
<ul class="simple">
|
||||
<li><p>RPC Calls: For straight RPC calls, a function should have a <code class="docutils literal notranslate"><span class="pre">context.Context</span></code> object as the first argument, followed by an arbitrary number of JSON marshallable arguments, and return either a single JSON marshal object, or a JSON marshallable object and an error. The RPC framework will take care of decoding inputs to this function and encoding outputs, and if the error is non-nil it will serve an error response.</p></li>
|
||||
<li><p>Subscriptions: For subscriptions (supported on IPC and websockets), a function should have a <code class="docutils literal notranslate"><span class="pre">context.Context</span></code> object as the first argument followed by an arbitrary number of JSON marshallable arguments, and should return an <code class="docutils literal notranslate"><span class="pre">*rpc.Subscription</span></code> object. The subscription object can be created with <code class="docutils literal notranslate"><span class="pre">rpcSub</span> <span class="pre">:=</span> <span class="pre">notifier.CreateSubscription()</span></code>, and JSON marshallable data can be sent to the subscriber with <code class="docutils literal notranslate"><span class="pre">notifier.Notify(rpcSub.ID,</span> <span class="pre">b)</span></code>.</p></li>
|
||||
</ul>
|
||||
<p>A very simple MyService might look like:</p>
|
||||
<div class="highlight-go notranslate"><div class="highlight"><pre><span></span><span class="s">``</span><span class="kd">type</span> <span class="nx">MyService</span> <span class="kd">struct</span><span class="p">{}</span>
|
||||
|
||||
<span class="kd">func</span> <span class="p">(</span><span class="nx">h</span> <span class="nx">MyService</span><span class="p">)</span> <span class="nx">HelloWorld</span><span class="p">(</span><span class="nx">ctx</span> <span class="nx">context</span><span class="p">.</span><span class="nx">Context</span><span class="p">)</span> <span class="kt">string</span> <span class="p">{</span>
|
||||
<span class="k">return</span> <span class="s">"Hello World"</span>
|
||||
<span class="p">}</span><span class="s">``</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>And the client could access this with an rpc call to
|
||||
<code class="docutils literal notranslate"><span class="pre">mynamespace_helloworld</span></code></p>
|
||||
</div>
|
||||
<div class="section" id="plugin-anatomy">
|
||||
<span id="anatomy"></span><h1>Plugin Anatomy<a class="headerlink" href="#plugin-anatomy" title="Permalink to this headline">¶</a></h1>
|
||||
<div class="admonition-todo admonition" id="id1">
|
||||
<p class="admonition-title">Todo</p>
|
||||
<p>fill in disections of archetypal plugins</p>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
@ -207,7 +95,7 @@ results of the EVM execution in unpredictable ways. Additonally, some objects ma
|
||||
</div>
|
||||
<footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
|
||||
<a href="hooks.html" class="btn btn-neutral float-left" title="Plugin Hooks" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
|
||||
<a href="build.html" class="btn btn-neutral float-right" title="Build" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
|
||||
<a href="build.html" class="btn btn-neutral float-right" title="Build and Deploy" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
|
||||
</div>
|
||||
|
||||
<hr/>
|
||||
|
||||
238
documentation/_build/html/api.html
Normal file
238
documentation/_build/html/api.html
Normal file
@ -0,0 +1,238 @@
|
||||
<!DOCTYPE html>
|
||||
<html class="writer-html5" lang="en" >
|
||||
<head>
|
||||
<meta charset="utf-8" />
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
|
||||
<title>API — Plugeth Austin Roberts documentation</title><link rel="stylesheet" href="_static/css/theme.css" type="text/css" />
|
||||
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
|
||||
<!--[if lt IE 9]>
|
||||
<script src="_static/js/html5shiv.min.js"></script>
|
||||
<![endif]-->
|
||||
<script id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
|
||||
<script src="_static/jquery.js"></script>
|
||||
<script src="_static/underscore.js"></script>
|
||||
<script src="_static/doctools.js"></script>
|
||||
<script src="_static/js/theme.js"></script>
|
||||
<link rel="index" title="Index" href="genindex.html" />
|
||||
<link rel="search" title="Search" href="search.html" />
|
||||
<link rel="next" title="Get in touch with us" href="contact.html" />
|
||||
<link rel="prev" title="Core vs Restricted packages in Plugeth-utils" href="core_restricted.html" />
|
||||
</head>
|
||||
|
||||
<body class="wy-body-for-nav">
|
||||
<div class="wy-grid-for-nav">
|
||||
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
|
||||
<div class="wy-side-scroll">
|
||||
<div class="wy-side-nav-search" >
|
||||
<a href="index.html" class="icon icon-home"> Plugeth
|
||||
</a>
|
||||
<div role="search">
|
||||
<form id="rtd-search-form" class="wy-form" action="search.html" method="get">
|
||||
<input type="text" name="q" placeholder="Search docs" />
|
||||
<input type="hidden" name="check_keywords" value="yes" />
|
||||
<input type="hidden" name="area" value="default" />
|
||||
</form>
|
||||
</div>
|
||||
</div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
|
||||
<p class="caption"><span class="caption-text">Overview</span></p>
|
||||
<ul>
|
||||
<li class="toctree-l1"><a class="reference internal" href="project.html">Project Design</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="types.html">Basic Types of Plugins</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="hooks.html">Plugin Hooks</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="anatomy.html">Plugin Anatomy</a></li>
|
||||
</ul>
|
||||
<p class="caption"><span class="caption-text">Tutorials</span></p>
|
||||
<ul>
|
||||
<li class="toctree-l1"><a class="reference internal" href="build.html">Build and Deploy</a></li>
|
||||
</ul>
|
||||
<p class="caption"><span class="caption-text">Reference</span></p>
|
||||
<ul class="current">
|
||||
<li class="toctree-l1"><a class="reference internal" href="system_req.html">System Requirements</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="plugin_loader.html">Plugin Loader</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="plugin_hooks.html">Plugin Hooks</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="core_restricted.html">Core vs Restricted packages in Plugeth-utils</a></li>
|
||||
<li class="toctree-l1 current"><a class="current reference internal" href="#">API</a><ul>
|
||||
<li class="toctree-l2"><a class="reference internal" href="#flags">Flags</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="#subcommands">Subcommands</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="#initialize">Initialize</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="#initializenode">InitializeNode</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="#tracers">Tracers</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="#livetracer">LiveTracer</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="#getapis">GetAPIs</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
</ul>
|
||||
<p class="caption"><span class="caption-text">Contact</span></p>
|
||||
<ul>
|
||||
<li class="toctree-l1"><a class="reference internal" href="contact.html">Get in touch with us</a></li>
|
||||
</ul>
|
||||
|
||||
</div>
|
||||
</div>
|
||||
</nav>
|
||||
|
||||
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" >
|
||||
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
|
||||
<a href="index.html">Plugeth</a>
|
||||
</nav>
|
||||
|
||||
<div class="wy-nav-content">
|
||||
<div class="rst-content">
|
||||
<div role="navigation" aria-label="Page navigation">
|
||||
<ul class="wy-breadcrumbs">
|
||||
<li><a href="index.html" class="icon icon-home"></a> »</li>
|
||||
<li>API</li>
|
||||
<li class="wy-breadcrumbs-aside">
|
||||
<a href="_sources/api.rst.txt" rel="nofollow"> View page source</a>
|
||||
</li>
|
||||
</ul>
|
||||
<hr/>
|
||||
</div>
|
||||
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
|
||||
<div itemprop="articleBody">
|
||||
|
||||
<div class="section" id="api">
|
||||
<span id="id1"></span><h1>API<a class="headerlink" href="#api" title="Permalink to this headline">¶</a></h1>
|
||||
<p>Plugins for Plugeth use Golang’s <a class="reference external" href="https://pkg.go.dev/plugin">Native Plugin System</a>. Plugin modules must export variables using specific names and types. These will be processed by the plugin loader, and invoked at certain points during Geth’s operations.</p>
|
||||
<div class="section" id="flags">
|
||||
<h2>Flags<a class="headerlink" href="#flags" title="Permalink to this headline">¶</a></h2>
|
||||
<ul class="simple">
|
||||
<li><p><strong>Name:</strong> Flags</p></li>
|
||||
<li><p><strong>Type:</strong> <a class="reference external" href="https://pkg.go.dev/flag#FlagSet">flag.FlagSet</a></p></li>
|
||||
<li><p><strong>Behavior:</strong> This FlagSet will be parsed and your plugin will be able to access the resulting flags. Flags will be passed to Geth from the command line and are intended to of the plugin. Note that if any flags are provided, certain checks are disabled within Geth to avoid failing due to unexpected flags.</p></li>
|
||||
</ul>
|
||||
</div>
|
||||
<div class="section" id="subcommands">
|
||||
<h2>Subcommands<a class="headerlink" href="#subcommands" title="Permalink to this headline">¶</a></h2>
|
||||
<ul class="simple">
|
||||
<li><p><strong>Name:</strong> Subcommands</p></li>
|
||||
<li><p><strong>Type:</strong> map[string]func(ctx <a class="reference external" href="https://pkg.go.dev/github.com/urfave/cli#Context">*cli.Context</a>, args []string) error</p></li>
|
||||
<li><p><strong>Behavior:</strong> If Geth is invoked with <code class="docutils literal notranslate"><span class="pre">./geth</span> <span class="pre">YOUR_COMMAND</span></code>, the plugin loader will look for <code class="docutils literal notranslate"><span class="pre">YOUR_COMMAND</span></code> within this map, and invoke the corresponding function. This can be useful for certain behaviors like manipulating Geth’s database without having to build a separate binary.</p></li>
|
||||
</ul>
|
||||
</div>
|
||||
<div class="section" id="initialize">
|
||||
<h2>Initialize<a class="headerlink" href="#initialize" title="Permalink to this headline">¶</a></h2>
|
||||
<ul class="simple">
|
||||
<li><p><strong>Name:</strong> Initialize</p></li>
|
||||
<li><p><strong>Type:</strong> func(<a href="#id2"><span class="problematic" id="id3">*</span></a>cli.Context, core.PluginLoader, core.logs )</p></li>
|
||||
<li><p><strong>Behavior:</strong> Called as soon as the plugin is loaded, with the cli context and a reference to the plugin loader. This is your plugin’s opportunity to initialize required variables as needed. Note that using the context object you can check arguments, and optionally can manipulate arguments if needed for your plugin.</p></li>
|
||||
</ul>
|
||||
<div class="admonition-todo admonition" id="id4">
|
||||
<p class="admonition-title">Todo</p>
|
||||
<p>explain that plugin could provide node.Node with
|
||||
restricted.backend</p>
|
||||
</div>
|
||||
</div>
|
||||
<div class="section" id="initializenode">
|
||||
<h2>InitializeNode<a class="headerlink" href="#initializenode" title="Permalink to this headline">¶</a></h2>
|
||||
<ul class="simple">
|
||||
<li><p><strong>Name:</strong> InitializeNode</p></li>
|
||||
<li><p><strong>Type:</strong> func(core.Node, core.Backend)</p></li>
|
||||
<li><p><strong>Behavior:</strong> 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 a wide array of data you may need to access.</p></li>
|
||||
</ul>
|
||||
</div>
|
||||
<div class="section" id="tracers">
|
||||
<h2>Tracers<a class="headerlink" href="#tracers" title="Permalink to this headline">¶</a></h2>
|
||||
<ul class="simple">
|
||||
<li><p><strong>Name:</strong> Tracers</p></li>
|
||||
<li><p><strong>Type:</strong> map[string]TracerResult</p></li>
|
||||
<li><p><strong>Behavior:</strong> When calling debug.traceX functions (such as <code class="docutils literal notranslate"><span class="pre">debug_traceCall</span></code> and <code class="docutils literal notranslate"><span class="pre">debug_traceTransaction</span></code>) the tracer can be specified as a key to this map and the tracer used will be the TracerResult specified here. TracerResult objects must match the interface:</p></li>
|
||||
</ul>
|
||||
<div class="highlight-go notranslate"><div class="highlight"><pre><span></span><span class="s">``</span><span class="c1">// CaptureStart is called at the start of each transaction</span>
|
||||
<span class="nx">CaptureStart</span><span class="p">(</span><span class="nx">env</span> <span class="nx">core</span><span class="p">.</span><span class="nx">EVM</span><span class="p">,</span> <span class="nx">from</span> <span class="nx">core</span><span class="p">.</span><span class="nx">Address</span><span class="p">,</span> <span class="nx">to</span> <span class="nx">core</span><span class="p">.</span><span class="nx">Address</span><span class="p">,</span> <span class="nx">create</span> <span class="kt">bool</span><span class="p">,</span> <span class="nx">input</span> <span class="p">[]</span><span class="kt">byte</span><span class="p">,</span> <span class="nx">gas</span> <span class="kt">uint64</span><span class="p">,</span> <span class="nx">value</span> <span class="o">*</span><span class="nx">big</span><span class="p">.</span><span class="nx">Int</span><span class="p">)</span> <span class="p">{}</span>
|
||||
<span class="c1">// CaptureState is called for each opcode</span>
|
||||
<span class="nx">CaptureState</span><span class="p">(</span><span class="nx">env</span> <span class="nx">core</span><span class="p">.</span><span class="nx">EVM</span><span class="p">,</span> <span class="nx">pc</span> <span class="kt">uint64</span><span class="p">,</span> <span class="nx">op</span> <span class="nx">core</span><span class="p">.</span><span class="nx">OpCode</span><span class="p">,</span> <span class="nx">gas</span><span class="p">,</span> <span class="nx">cost</span> <span class="kt">uint64</span><span class="p">,</span> <span class="nx">scope</span> <span class="o">*</span><span class="nx">vm</span><span class="p">.</span><span class="nx">ScopeContext</span><span class="p">,</span> <span class="nx">rData</span> <span class="p">[]</span><span class="kt">byte</span><span class="p">,</span> <span class="nx">depth</span> <span class="kt">int</span><span class="p">,</span> <span class="nx">err</span> <span class="kt">error</span><span class="p">)</span> <span class="p">{}</span>
|
||||
<span class="c1">// CaptureFault is called when an error occurs in the EVM</span>
|
||||
<span class="nx">CaptureFault</span><span class="p">(</span><span class="nx">env</span> <span class="nx">core</span><span class="p">.</span><span class="nx">EVM</span><span class="p">,</span> <span class="nx">pc</span> <span class="kt">uint64</span><span class="p">,</span> <span class="nx">op</span> <span class="nx">core</span><span class="p">.</span><span class="nx">OpCode</span><span class="p">,</span> <span class="nx">gas</span><span class="p">,</span> <span class="nx">cost</span> <span class="kt">uint64</span><span class="p">,</span> <span class="nx">scope</span> <span class="o">*</span><span class="nx">vm</span><span class="p">.</span><span class="nx">ScopeContext</span><span class="p">,</span> <span class="nx">depth</span> <span class="kt">int</span><span class="p">,</span> <span class="nx">err</span> <span class="kt">error</span><span class="p">)</span> <span class="p">{}</span>
|
||||
<span class="c1">// CaptureEnd is called at the end of each transaction</span>
|
||||
<span class="nx">CaptureEnd</span><span class="p">(</span><span class="nx">output</span> <span class="p">[]</span><span class="kt">byte</span><span class="p">,</span> <span class="nx">gasUsed</span> <span class="kt">uint64</span><span class="p">,</span> <span class="nx">t</span> <span class="nx">time</span><span class="p">.</span><span class="nx">Duration</span><span class="p">,</span> <span class="nx">err</span> <span class="kt">error</span><span class="p">)</span> <span class="p">{}</span>
|
||||
<span class="c1">// GetResult should return a JSON serializable result object to respond to the trace call</span>
|
||||
<span class="nx">GetResult</span><span class="p">()</span> <span class="p">(</span><span class="kd">interface</span><span class="p">{},</span> <span class="kt">error</span><span class="p">)</span> <span class="p">{}</span><span class="s">``</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<div class="admonition warning">
|
||||
<p class="admonition-title">Warning</p>
|
||||
<p>Modifying the values passed into tracer functions can
|
||||
alter the
|
||||
results of the EVM execution in unpredictable ways. Additonally, some objects may be reused acress calls, so data you wish to capture should be copied rather than retianed by reference.</p>
|
||||
</div>
|
||||
</div>
|
||||
<div class="section" id="livetracer">
|
||||
<h2>LiveTracer<a class="headerlink" href="#livetracer" title="Permalink to this headline">¶</a></h2>
|
||||
<ul class="simple">
|
||||
<li><p><strong>Name:</strong> LiveTracers</p></li>
|
||||
<li><p><strong>Type:</strong> core.Tracer</p></li>
|
||||
<li><p><strong>Behavior:</strong> This tracer is used for tracing transactions as they are processed within blocks. Note that if a block does not validate, some transactions may be processed that don’t end up in blocks, so be sure to check transactions against finalized blocks.</p></li>
|
||||
</ul>
|
||||
<p>The interface for a vm.Tracer is similar to a TracerResult (above), but does not require a <code class="docutils literal notranslate"><span class="pre">GetResult()</span></code> function.</p>
|
||||
</div>
|
||||
<div class="section" id="getapis">
|
||||
<h2>GetAPIs<a class="headerlink" href="#getapis" title="Permalink to this headline">¶</a></h2>
|
||||
<ul class="simple">
|
||||
<li><p><strong>Name:</strong> GetAPIs</p></li>
|
||||
<li><p><strong>Type:</strong> func(core.Node, core.Backend) []rpc.API</p></li>
|
||||
<li><p><strong>Behavior:</strong> This allows you to register new RPC methods to run within Geth.</p></li>
|
||||
</ul>
|
||||
<p>The GetAPIs function itself will generally be fairly brief, and will looks something like this:</p>
|
||||
<div class="highlight-go notranslate"><div class="highlight"><pre><span></span> <span class="s">``</span><span class="kd">func</span> <span class="nx">GetAPIs</span><span class="p">(</span><span class="nx">stack</span> <span class="o">*</span><span class="nx">node</span><span class="p">.</span><span class="nx">Node</span><span class="p">,</span> <span class="nx">backend</span> <span class="nx">core</span><span class="p">.</span><span class="nx">Backend</span><span class="p">)</span> <span class="p">[]</span><span class="nx">core</span><span class="p">.</span><span class="nx">API</span> <span class="p">{</span>
|
||||
<span class="k">return</span> <span class="p">[]</span><span class="nx">rpc</span><span class="p">.</span><span class="nx">API</span><span class="p">{</span>
|
||||
<span class="p">{</span>
|
||||
<span class="nx">Namespace</span><span class="p">:</span> <span class="s">"mynamespace"</span><span class="p">,</span>
|
||||
<span class="nx">Version</span><span class="p">:</span> <span class="s">"1.0"</span><span class="p">,</span>
|
||||
<span class="nx">Service</span><span class="p">:</span> <span class="o">&</span><span class="nx">MyService</span><span class="p">{</span><span class="nx">backend</span><span class="p">},</span>
|
||||
<span class="nx">Public</span><span class="p">:</span> <span class="kc">true</span><span class="p">,</span>
|
||||
<span class="p">},</span>
|
||||
<span class="p">}</span>
|
||||
<span class="p">}</span><span class="s">``</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>The bulk of the implementation will be in the <code class="docutils literal notranslate"><span class="pre">MyService</span></code> struct. MyService should be a struct with public functions. These functions can have two different types of signatures:</p>
|
||||
<ul class="simple">
|
||||
<li><p>RPC Calls: For straight RPC calls, a function should have a <code class="docutils literal notranslate"><span class="pre">context.Context</span></code> object as the first argument, followed by an arbitrary number of JSON marshallable arguments, and return either a single JSON marshal object, or a JSON marshallable object and an error. The RPC framework will take care of decoding inputs to this function and encoding outputs, and if the error is non-nil it will serve an error response.</p></li>
|
||||
<li><p>Subscriptions: For subscriptions (supported on IPC and websockets), a function should have a <code class="docutils literal notranslate"><span class="pre">context.Context</span></code> object as the first argument followed by an arbitrary number of JSON marshallable arguments, and should return an <code class="docutils literal notranslate"><span class="pre">*rpc.Subscription</span></code> object. The subscription object can be created with <code class="docutils literal notranslate"><span class="pre">rpcSub</span> <span class="pre">:=</span> <span class="pre">notifier.CreateSubscription()</span></code>, and JSON marshallable data can be sent to the subscriber with <code class="docutils literal notranslate"><span class="pre">notifier.Notify(rpcSub.ID,</span> <span class="pre">b)</span></code>.</p></li>
|
||||
</ul>
|
||||
<p>A very simple MyService might look like:</p>
|
||||
<div class="highlight-go notranslate"><div class="highlight"><pre><span></span><span class="s">``</span><span class="kd">type</span> <span class="nx">MyService</span> <span class="kd">struct</span><span class="p">{}</span>
|
||||
|
||||
<span class="kd">func</span> <span class="p">(</span><span class="nx">h</span> <span class="nx">MyService</span><span class="p">)</span> <span class="nx">HelloWorld</span><span class="p">(</span><span class="nx">ctx</span> <span class="nx">context</span><span class="p">.</span><span class="nx">Context</span><span class="p">)</span> <span class="kt">string</span> <span class="p">{</span>
|
||||
<span class="k">return</span> <span class="s">"Hello World"</span>
|
||||
<span class="p">}</span><span class="s">``</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>And the client could access this with an rpc call to
|
||||
<code class="docutils literal notranslate"><span class="pre">mynamespace_helloworld</span></code></p>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
|
||||
</div>
|
||||
</div>
|
||||
<footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
|
||||
<a href="core_restricted.html" class="btn btn-neutral float-left" title="Core vs Restricted packages in Plugeth-utils" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
|
||||
<a href="contact.html" class="btn btn-neutral float-right" title="Get in touch with us" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
|
||||
</div>
|
||||
|
||||
<hr/>
|
||||
|
||||
<div role="contentinfo">
|
||||
<p>© Copyright 2021, Philip Morlier.</p>
|
||||
</div>
|
||||
|
||||
Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
|
||||
<a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a>
|
||||
provided by <a href="https://readthedocs.org">Read the Docs</a>.
|
||||
|
||||
|
||||
</footer>
|
||||
</div>
|
||||
</div>
|
||||
</section>
|
||||
</div>
|
||||
<script>
|
||||
jQuery(function () {
|
||||
SphinxRtdTheme.Navigation.enable(true);
|
||||
});
|
||||
</script>
|
||||
|
||||
</body>
|
||||
</html>
|
||||
@ -3,7 +3,7 @@
|
||||
<head>
|
||||
<meta charset="utf-8" />
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
|
||||
<title>Build — Plugeth Austin Roberts documentation</title><link rel="stylesheet" href="_static/css/theme.css" type="text/css" />
|
||||
<title>Build and Deploy — Plugeth Austin Roberts documentation</title><link rel="stylesheet" href="_static/css/theme.css" type="text/css" />
|
||||
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
|
||||
<!--[if lt IE 9]>
|
||||
<script src="_static/js/html5shiv.min.js"></script>
|
||||
@ -15,8 +15,8 @@
|
||||
<script src="_static/js/theme.js"></script>
|
||||
<link rel="index" title="Index" href="genindex.html" />
|
||||
<link rel="search" title="Search" href="search.html" />
|
||||
<link rel="next" title="Core vs Restricted packages in Plugeth-utils" href="core_restricted.html" />
|
||||
<link rel="prev" title="Anatomy of a Plugin" href="anatomy.html" />
|
||||
<link rel="next" title="System Requirements" href="system_req.html" />
|
||||
<link rel="prev" title="Plugin Anatomy" href="anatomy.html" />
|
||||
</head>
|
||||
|
||||
<body class="wy-body-for-nav">
|
||||
@ -39,11 +39,11 @@
|
||||
<li class="toctree-l1"><a class="reference internal" href="project.html">Project Design</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="types.html">Basic Types of Plugins</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="hooks.html">Plugin Hooks</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="anatomy.html">Anatomy of a Plugin</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="anatomy.html">Plugin Anatomy</a></li>
|
||||
</ul>
|
||||
<p class="caption"><span class="caption-text">Tutorials</span></p>
|
||||
<ul class="current">
|
||||
<li class="toctree-l1 current"><a class="current reference internal" href="#">Build</a><ul>
|
||||
<li class="toctree-l1 current"><a class="current reference internal" href="#">Build and Deploy</a><ul>
|
||||
<li class="toctree-l2"><a class="reference internal" href="#setting-up-the-environment">Setting up the environment</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="#build-a-plugin">Build a plugin</a></li>
|
||||
</ul>
|
||||
@ -51,7 +51,11 @@
|
||||
</ul>
|
||||
<p class="caption"><span class="caption-text">Reference</span></p>
|
||||
<ul>
|
||||
<li class="toctree-l1"><a class="reference internal" href="system_req.html">System Requirements</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="plugin_loader.html">Plugin Loader</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="plugin_hooks.html">Plugin Hooks</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="core_restricted.html">Core vs Restricted packages in Plugeth-utils</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="api.html">API</a></li>
|
||||
</ul>
|
||||
<p class="caption"><span class="caption-text">Contact</span></p>
|
||||
<ul>
|
||||
@ -72,7 +76,7 @@
|
||||
<div role="navigation" aria-label="Page navigation">
|
||||
<ul class="wy-breadcrumbs">
|
||||
<li><a href="index.html" class="icon icon-home"></a> »</li>
|
||||
<li>Build</li>
|
||||
<li>Build and Deploy</li>
|
||||
<li class="wy-breadcrumbs-aside">
|
||||
<a href="_sources/build.rst.txt" rel="nofollow"> View page source</a>
|
||||
</li>
|
||||
@ -82,16 +86,16 @@
|
||||
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
|
||||
<div itemprop="articleBody">
|
||||
|
||||
<div class="section" id="build">
|
||||
<span id="id1"></span><h1>Build<a class="headerlink" href="#build" title="Permalink to this headline">¶</a></h1>
|
||||
<div class="section" id="build-and-deploy">
|
||||
<span id="build"></span><h1>Build and Deploy<a class="headerlink" href="#build-and-deploy" title="Permalink to this headline">¶</a></h1>
|
||||
<div class="contents local topic" id="contents">
|
||||
<ul class="simple">
|
||||
<li><p><a class="reference internal" href="#setting-up-the-environment" id="id2">Setting up the environment</a></p></li>
|
||||
<li><p><a class="reference internal" href="#build-a-plugin" id="id3">Build a plugin</a></p></li>
|
||||
<li><p><a class="reference internal" href="#setting-up-the-environment" id="id1">Setting up the environment</a></p></li>
|
||||
<li><p><a class="reference internal" href="#build-a-plugin" id="id2">Build a plugin</a></p></li>
|
||||
</ul>
|
||||
</div>
|
||||
<div class="section" id="setting-up-the-environment">
|
||||
<h2><a class="toc-backref" href="#id2">Setting up the environment</a><a class="headerlink" href="#setting-up-the-environment" title="Permalink to this headline">¶</a></h2>
|
||||
<h2><a class="toc-backref" href="#id1">Setting up the environment</a><a class="headerlink" href="#setting-up-the-environment" title="Permalink to this headline">¶</a></h2>
|
||||
<div class="admonition note">
|
||||
<p class="admonition-title">Note</p>
|
||||
<p>Plugeth is built on a fork of <a class="reference external" href="https://geth.ethereum.org/">Geth</a> and as such requires familiarity with <a class="reference external" href="https://golang.org/doc/">Go</a> and a funtional <a class="reference external" href="https://golang.org/doc/code">environment</a> in which to build Go projects. Thankfully for everyone Go provides a compact and useful <a class="reference external" href="https://tour.golang.org/welcome/1">tutorial</a> as well as a <a class="reference external" href="https://tour.golang.org/welcome/1">space for practice</a>.</p>
|
||||
@ -121,7 +125,7 @@
|
||||
</div>
|
||||
</div>
|
||||
<div class="section" id="build-a-plugin">
|
||||
<h2><a class="toc-backref" href="#id3">Build a plugin</a><a class="headerlink" href="#build-a-plugin" title="Permalink to this headline">¶</a></h2>
|
||||
<h2><a class="toc-backref" href="#id2">Build a plugin</a><a class="headerlink" href="#build-a-plugin" title="Permalink to this headline">¶</a></h2>
|
||||
<p>Navigate to <code class="docutils literal notranslate"><span class="pre">plugethPlugins/packages/hello</span></code>. Inside you will see a <code class="docutils literal notranslate"><span class="pre">main.go</span></code> file. From this location run:</p>
|
||||
<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>$ go build -buildmode<span class="o">=</span>plugin
|
||||
</pre></div>
|
||||
@ -143,8 +147,8 @@
|
||||
</div>
|
||||
</div>
|
||||
<footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
|
||||
<a href="anatomy.html" class="btn btn-neutral float-left" title="Anatomy of a Plugin" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
|
||||
<a href="core_restricted.html" class="btn btn-neutral float-right" title="Core vs Restricted packages in Plugeth-utils" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
|
||||
<a href="anatomy.html" class="btn btn-neutral float-left" title="Plugin Anatomy" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
|
||||
<a href="system_req.html" class="btn btn-neutral float-right" title="System Requirements" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
|
||||
</div>
|
||||
|
||||
<hr/>
|
||||
|
||||
@ -15,7 +15,7 @@
|
||||
<script src="_static/js/theme.js"></script>
|
||||
<link rel="index" title="Index" href="genindex.html" />
|
||||
<link rel="search" title="Search" href="search.html" />
|
||||
<link rel="prev" title="Core vs Restricted packages in Plugeth-utils" href="core_restricted.html" />
|
||||
<link rel="prev" title="API" href="api.html" />
|
||||
</head>
|
||||
|
||||
<body class="wy-body-for-nav">
|
||||
@ -38,15 +38,19 @@
|
||||
<li class="toctree-l1"><a class="reference internal" href="project.html">Project Design</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="types.html">Basic Types of Plugins</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="hooks.html">Plugin Hooks</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="anatomy.html">Anatomy of a Plugin</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="anatomy.html">Plugin Anatomy</a></li>
|
||||
</ul>
|
||||
<p class="caption"><span class="caption-text">Tutorials</span></p>
|
||||
<ul>
|
||||
<li class="toctree-l1"><a class="reference internal" href="build.html">Build</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="build.html">Build and Deploy</a></li>
|
||||
</ul>
|
||||
<p class="caption"><span class="caption-text">Reference</span></p>
|
||||
<ul>
|
||||
<li class="toctree-l1"><a class="reference internal" href="system_req.html">System Requirements</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="plugin_loader.html">Plugin Loader</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="plugin_hooks.html">Plugin Hooks</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="core_restricted.html">Core vs Restricted packages in Plugeth-utils</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="api.html">API</a></li>
|
||||
</ul>
|
||||
<p class="caption"><span class="caption-text">Contact</span></p>
|
||||
<ul class="current">
|
||||
@ -87,7 +91,7 @@
|
||||
</div>
|
||||
</div>
|
||||
<footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
|
||||
<a href="core_restricted.html" class="btn btn-neutral float-left" title="Core vs Restricted packages in Plugeth-utils" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
|
||||
<a href="api.html" class="btn btn-neutral float-left" title="API" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
|
||||
</div>
|
||||
|
||||
<hr/>
|
||||
|
||||
@ -15,8 +15,8 @@
|
||||
<script src="_static/js/theme.js"></script>
|
||||
<link rel="index" title="Index" href="genindex.html" />
|
||||
<link rel="search" title="Search" href="search.html" />
|
||||
<link rel="next" title="Get in touch with us" href="contact.html" />
|
||||
<link rel="prev" title="Build" href="build.html" />
|
||||
<link rel="next" title="API" href="api.html" />
|
||||
<link rel="prev" title="Plugin Hooks" href="plugin_hooks.html" />
|
||||
</head>
|
||||
|
||||
<body class="wy-body-for-nav">
|
||||
@ -39,15 +39,19 @@
|
||||
<li class="toctree-l1"><a class="reference internal" href="project.html">Project Design</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="types.html">Basic Types of Plugins</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="hooks.html">Plugin Hooks</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="anatomy.html">Anatomy of a Plugin</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="anatomy.html">Plugin Anatomy</a></li>
|
||||
</ul>
|
||||
<p class="caption"><span class="caption-text">Tutorials</span></p>
|
||||
<ul>
|
||||
<li class="toctree-l1"><a class="reference internal" href="build.html">Build</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="build.html">Build and Deploy</a></li>
|
||||
</ul>
|
||||
<p class="caption"><span class="caption-text">Reference</span></p>
|
||||
<ul class="current">
|
||||
<li class="toctree-l1"><a class="reference internal" href="system_req.html">System Requirements</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="plugin_loader.html">Plugin Loader</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="plugin_hooks.html">Plugin Hooks</a></li>
|
||||
<li class="toctree-l1 current"><a class="current reference internal" href="#">Core vs Restricted packages in Plugeth-utils</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="api.html">API</a></li>
|
||||
</ul>
|
||||
<p class="caption"><span class="caption-text">Contact</span></p>
|
||||
<ul>
|
||||
@ -80,15 +84,18 @@
|
||||
|
||||
<div class="section" id="core-vs-restricted-packages-in-plugeth-utils">
|
||||
<span id="core-restricted"></span><h1>Core vs Restricted packages in Plugeth-utils<a class="headerlink" href="#core-vs-restricted-packages-in-plugeth-utils" title="Permalink to this headline">¶</a></h1>
|
||||
<p><strong>todo: copy on core and restricted packages in utils. what, why, how.</strong></p>
|
||||
<div class="admonition-todo admonition" id="id1">
|
||||
<p class="admonition-title">Todo</p>
|
||||
<p>need explinations of core vs restircted functionality. what, why, how.</p>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
|
||||
</div>
|
||||
</div>
|
||||
<footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
|
||||
<a href="build.html" class="btn btn-neutral float-left" title="Build" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
|
||||
<a href="contact.html" class="btn btn-neutral float-right" title="Get in touch with us" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
|
||||
<a href="plugin_hooks.html" class="btn btn-neutral float-left" title="Plugin Hooks" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
|
||||
<a href="api.html" class="btn btn-neutral float-right" title="API" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
|
||||
</div>
|
||||
|
||||
<hr/>
|
||||
|
||||
@ -37,15 +37,19 @@
|
||||
<li class="toctree-l1"><a class="reference internal" href="project.html">Project Design</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="types.html">Basic Types of Plugins</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="hooks.html">Plugin Hooks</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="anatomy.html">Anatomy of a Plugin</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="anatomy.html">Plugin Anatomy</a></li>
|
||||
</ul>
|
||||
<p class="caption"><span class="caption-text">Tutorials</span></p>
|
||||
<ul>
|
||||
<li class="toctree-l1"><a class="reference internal" href="build.html">Build</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="build.html">Build and Deploy</a></li>
|
||||
</ul>
|
||||
<p class="caption"><span class="caption-text">Reference</span></p>
|
||||
<ul>
|
||||
<li class="toctree-l1"><a class="reference internal" href="system_req.html">System Requirements</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="plugin_loader.html">Plugin Loader</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="plugin_hooks.html">Plugin Hooks</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="core_restricted.html">Core vs Restricted packages in Plugeth-utils</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="api.html">API</a></li>
|
||||
</ul>
|
||||
<p class="caption"><span class="caption-text">Contact</span></p>
|
||||
<ul>
|
||||
|
||||
@ -15,7 +15,7 @@
|
||||
<script src="_static/js/theme.js"></script>
|
||||
<link rel="index" title="Index" href="genindex.html" />
|
||||
<link rel="search" title="Search" href="search.html" />
|
||||
<link rel="next" title="Anatomy of a Plugin" href="anatomy.html" />
|
||||
<link rel="next" title="Plugin Anatomy" href="anatomy.html" />
|
||||
<link rel="prev" title="Basic Types of Plugins" href="types.html" />
|
||||
</head>
|
||||
|
||||
@ -39,15 +39,19 @@
|
||||
<li class="toctree-l1"><a class="reference internal" href="project.html">Project Design</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="types.html">Basic Types of Plugins</a></li>
|
||||
<li class="toctree-l1 current"><a class="current reference internal" href="#">Plugin Hooks</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="anatomy.html">Anatomy of a Plugin</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="anatomy.html">Plugin Anatomy</a></li>
|
||||
</ul>
|
||||
<p class="caption"><span class="caption-text">Tutorials</span></p>
|
||||
<ul>
|
||||
<li class="toctree-l1"><a class="reference internal" href="build.html">Build</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="build.html">Build and Deploy</a></li>
|
||||
</ul>
|
||||
<p class="caption"><span class="caption-text">Reference</span></p>
|
||||
<ul>
|
||||
<li class="toctree-l1"><a class="reference internal" href="system_req.html">System Requirements</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="plugin_loader.html">Plugin Loader</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="plugin_hooks.html">Plugin Hooks</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="core_restricted.html">Core vs Restricted packages in Plugeth-utils</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="api.html">API</a></li>
|
||||
</ul>
|
||||
<p class="caption"><span class="caption-text">Contact</span></p>
|
||||
<ul>
|
||||
@ -80,7 +84,10 @@
|
||||
|
||||
<div class="section" id="plugin-hooks">
|
||||
<span id="hooks"></span><h1>Plugin Hooks<a class="headerlink" href="#plugin-hooks" title="Permalink to this headline">¶</a></h1>
|
||||
<p><strong>todo: discussion on plugin hooks</strong></p>
|
||||
<div class="admonition-todo admonition" id="id1">
|
||||
<p class="admonition-title">Todo</p>
|
||||
<p>discussion of plugin hooks</p>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
|
||||
@ -88,7 +95,7 @@
|
||||
</div>
|
||||
<footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
|
||||
<a href="types.html" class="btn btn-neutral float-left" title="Basic Types of Plugins" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
|
||||
<a href="anatomy.html" class="btn btn-neutral float-right" title="Anatomy of a Plugin" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
|
||||
<a href="anatomy.html" class="btn btn-neutral float-right" title="Plugin Anatomy" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
|
||||
</div>
|
||||
|
||||
<hr/>
|
||||
|
||||
@ -38,15 +38,19 @@
|
||||
<li class="toctree-l1"><a class="reference internal" href="project.html">Project Design</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="types.html">Basic Types of Plugins</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="hooks.html">Plugin Hooks</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="anatomy.html">Anatomy of a Plugin</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="anatomy.html">Plugin Anatomy</a></li>
|
||||
</ul>
|
||||
<p class="caption"><span class="caption-text">Tutorials</span></p>
|
||||
<ul>
|
||||
<li class="toctree-l1"><a class="reference internal" href="build.html">Build</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="build.html">Build and Deploy</a></li>
|
||||
</ul>
|
||||
<p class="caption"><span class="caption-text">Reference</span></p>
|
||||
<ul>
|
||||
<li class="toctree-l1"><a class="reference internal" href="system_req.html">System Requirements</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="plugin_loader.html">Plugin Loader</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="plugin_hooks.html">Plugin Hooks</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="core_restricted.html">Core vs Restricted packages in Plugeth-utils</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="api.html">API</a></li>
|
||||
</ul>
|
||||
<p class="caption"><span class="caption-text">Contact</span></p>
|
||||
<ul>
|
||||
@ -80,8 +84,13 @@
|
||||
<div class="section" id="plugeth">
|
||||
<h1>PluGeth<a class="headerlink" href="#plugeth" title="Permalink to this headline">¶</a></h1>
|
||||
<p>PluGeth is a fork of the <a class="reference external" href="https://github.com/ethereum/go-ethereum">Go Ethereum Client Geth</a> 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 of Geth.</p>
|
||||
<p><strong>WARNING: UNSTABLE API</strong></p>
|
||||
<p>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 future updates will likely break your plugins.</p>
|
||||
<div class="admonition warning">
|
||||
<p class="admonition-title">Warning</p>
|
||||
<p>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 isstability is added by plugins you might run. But if you plan to run PluGeth today, be aware that furture updates will likely break you plugins.</p>
|
||||
</div>
|
||||
<div class="section" id="table-of-contents">
|
||||
<h2>Table of Contents<a class="headerlink" href="#table-of-contents" title="Permalink to this headline">¶</a></h2>
|
||||
<div class="toctree-wrapper compound">
|
||||
@ -90,19 +99,23 @@
|
||||
<li class="toctree-l1"><a class="reference internal" href="project.html">Project Design</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="types.html">Basic Types of Plugins</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="hooks.html">Plugin Hooks</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="anatomy.html">Anatomy of a Plugin</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="anatomy.html">Plugin Anatomy</a></li>
|
||||
</ul>
|
||||
</div>
|
||||
<div class="toctree-wrapper compound">
|
||||
<p class="caption"><span class="caption-text">Tutorials</span></p>
|
||||
<ul>
|
||||
<li class="toctree-l1"><a class="reference internal" href="build.html">Build</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="build.html">Build and Deploy</a></li>
|
||||
</ul>
|
||||
</div>
|
||||
<div class="toctree-wrapper compound">
|
||||
<p class="caption"><span class="caption-text">Reference</span></p>
|
||||
<ul>
|
||||
<li class="toctree-l1"><a class="reference internal" href="system_req.html">System Requirements</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="plugin_loader.html">Plugin Loader</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="plugin_hooks.html">Plugin Hooks</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="core_restricted.html">Core vs Restricted packages in Plugeth-utils</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="api.html">API</a></li>
|
||||
</ul>
|
||||
</div>
|
||||
<div class="toctree-wrapper compound">
|
||||
|
||||
Binary file not shown.
@ -37,15 +37,19 @@
|
||||
<li class="toctree-l1"><a class="reference internal" href="project.html">Project Design</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="types.html">Basic Types of Plugins</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="hooks.html">Plugin Hooks</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="anatomy.html">Anatomy of a Plugin</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="anatomy.html">Plugin Anatomy</a></li>
|
||||
</ul>
|
||||
<p class="caption"><span class="caption-text">Tutorials</span></p>
|
||||
<ul>
|
||||
<li class="toctree-l1"><a class="reference internal" href="build.html">Build</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="build.html">Build and Deploy</a></li>
|
||||
</ul>
|
||||
<p class="caption"><span class="caption-text">Reference</span></p>
|
||||
<ul>
|
||||
<li class="toctree-l1"><a class="reference internal" href="system_req.html">System Requirements</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="plugin_loader.html">Plugin Loader</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="plugin_hooks.html">Plugin Hooks</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="core_restricted.html">Core vs Restricted packages in Plugeth-utils</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="api.html">API</a></li>
|
||||
</ul>
|
||||
<p class="caption"><span class="caption-text">Contact</span></p>
|
||||
<ul>
|
||||
|
||||
124
documentation/_build/html/plugin_hooks.html
Normal file
124
documentation/_build/html/plugin_hooks.html
Normal file
@ -0,0 +1,124 @@
|
||||
<!DOCTYPE html>
|
||||
<html class="writer-html5" lang="en" >
|
||||
<head>
|
||||
<meta charset="utf-8" />
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
|
||||
<title>Plugin Hooks — Plugeth Austin Roberts documentation</title><link rel="stylesheet" href="_static/css/theme.css" type="text/css" />
|
||||
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
|
||||
<!--[if lt IE 9]>
|
||||
<script src="_static/js/html5shiv.min.js"></script>
|
||||
<![endif]-->
|
||||
<script id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
|
||||
<script src="_static/jquery.js"></script>
|
||||
<script src="_static/underscore.js"></script>
|
||||
<script src="_static/doctools.js"></script>
|
||||
<script src="_static/js/theme.js"></script>
|
||||
<link rel="index" title="Index" href="genindex.html" />
|
||||
<link rel="search" title="Search" href="search.html" />
|
||||
<link rel="next" title="Core vs Restricted packages in Plugeth-utils" href="core_restricted.html" />
|
||||
<link rel="prev" title="Plugin Loader" href="plugin_loader.html" />
|
||||
</head>
|
||||
|
||||
<body class="wy-body-for-nav">
|
||||
<div class="wy-grid-for-nav">
|
||||
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
|
||||
<div class="wy-side-scroll">
|
||||
<div class="wy-side-nav-search" >
|
||||
<a href="index.html" class="icon icon-home"> Plugeth
|
||||
</a>
|
||||
<div role="search">
|
||||
<form id="rtd-search-form" class="wy-form" action="search.html" method="get">
|
||||
<input type="text" name="q" placeholder="Search docs" />
|
||||
<input type="hidden" name="check_keywords" value="yes" />
|
||||
<input type="hidden" name="area" value="default" />
|
||||
</form>
|
||||
</div>
|
||||
</div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
|
||||
<p class="caption"><span class="caption-text">Overview</span></p>
|
||||
<ul>
|
||||
<li class="toctree-l1"><a class="reference internal" href="project.html">Project Design</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="types.html">Basic Types of Plugins</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="hooks.html">Plugin Hooks</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="anatomy.html">Plugin Anatomy</a></li>
|
||||
</ul>
|
||||
<p class="caption"><span class="caption-text">Tutorials</span></p>
|
||||
<ul>
|
||||
<li class="toctree-l1"><a class="reference internal" href="build.html">Build and Deploy</a></li>
|
||||
</ul>
|
||||
<p class="caption"><span class="caption-text">Reference</span></p>
|
||||
<ul class="current">
|
||||
<li class="toctree-l1"><a class="reference internal" href="system_req.html">System Requirements</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="plugin_loader.html">Plugin Loader</a></li>
|
||||
<li class="toctree-l1 current"><a class="current reference internal" href="#">Plugin Hooks</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="core_restricted.html">Core vs Restricted packages in Plugeth-utils</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="api.html">API</a></li>
|
||||
</ul>
|
||||
<p class="caption"><span class="caption-text">Contact</span></p>
|
||||
<ul>
|
||||
<li class="toctree-l1"><a class="reference internal" href="contact.html">Get in touch with us</a></li>
|
||||
</ul>
|
||||
|
||||
</div>
|
||||
</div>
|
||||
</nav>
|
||||
|
||||
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" >
|
||||
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
|
||||
<a href="index.html">Plugeth</a>
|
||||
</nav>
|
||||
|
||||
<div class="wy-nav-content">
|
||||
<div class="rst-content">
|
||||
<div role="navigation" aria-label="Page navigation">
|
||||
<ul class="wy-breadcrumbs">
|
||||
<li><a href="index.html" class="icon icon-home"></a> »</li>
|
||||
<li>Plugin Hooks</li>
|
||||
<li class="wy-breadcrumbs-aside">
|
||||
<a href="_sources/plugin_hooks.rst.txt" rel="nofollow"> View page source</a>
|
||||
</li>
|
||||
</ul>
|
||||
<hr/>
|
||||
</div>
|
||||
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
|
||||
<div itemprop="articleBody">
|
||||
|
||||
<div class="section" id="plugin-hooks">
|
||||
<span id="id1"></span><h1>Plugin Hooks<a class="headerlink" href="#plugin-hooks" title="Permalink to this headline">¶</a></h1>
|
||||
<div class="admonition-todo admonition" id="id2">
|
||||
<p class="admonition-title">Todo</p>
|
||||
<p>guide to writing plugin hooks</p>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
|
||||
</div>
|
||||
</div>
|
||||
<footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
|
||||
<a href="plugin_loader.html" class="btn btn-neutral float-left" title="Plugin Loader" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
|
||||
<a href="core_restricted.html" class="btn btn-neutral float-right" title="Core vs Restricted packages in Plugeth-utils" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
|
||||
</div>
|
||||
|
||||
<hr/>
|
||||
|
||||
<div role="contentinfo">
|
||||
<p>© Copyright 2021, Philip Morlier.</p>
|
||||
</div>
|
||||
|
||||
Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
|
||||
<a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a>
|
||||
provided by <a href="https://readthedocs.org">Read the Docs</a>.
|
||||
|
||||
|
||||
</footer>
|
||||
</div>
|
||||
</div>
|
||||
</section>
|
||||
</div>
|
||||
<script>
|
||||
jQuery(function () {
|
||||
SphinxRtdTheme.Navigation.enable(true);
|
||||
});
|
||||
</script>
|
||||
|
||||
</body>
|
||||
</html>
|
||||
124
documentation/_build/html/plugin_loader.html
Normal file
124
documentation/_build/html/plugin_loader.html
Normal file
@ -0,0 +1,124 @@
|
||||
<!DOCTYPE html>
|
||||
<html class="writer-html5" lang="en" >
|
||||
<head>
|
||||
<meta charset="utf-8" />
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
|
||||
<title>Plugin Loader — Plugeth Austin Roberts documentation</title><link rel="stylesheet" href="_static/css/theme.css" type="text/css" />
|
||||
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
|
||||
<!--[if lt IE 9]>
|
||||
<script src="_static/js/html5shiv.min.js"></script>
|
||||
<![endif]-->
|
||||
<script id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
|
||||
<script src="_static/jquery.js"></script>
|
||||
<script src="_static/underscore.js"></script>
|
||||
<script src="_static/doctools.js"></script>
|
||||
<script src="_static/js/theme.js"></script>
|
||||
<link rel="index" title="Index" href="genindex.html" />
|
||||
<link rel="search" title="Search" href="search.html" />
|
||||
<link rel="next" title="Plugin Hooks" href="plugin_hooks.html" />
|
||||
<link rel="prev" title="System Requirements" href="system_req.html" />
|
||||
</head>
|
||||
|
||||
<body class="wy-body-for-nav">
|
||||
<div class="wy-grid-for-nav">
|
||||
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
|
||||
<div class="wy-side-scroll">
|
||||
<div class="wy-side-nav-search" >
|
||||
<a href="index.html" class="icon icon-home"> Plugeth
|
||||
</a>
|
||||
<div role="search">
|
||||
<form id="rtd-search-form" class="wy-form" action="search.html" method="get">
|
||||
<input type="text" name="q" placeholder="Search docs" />
|
||||
<input type="hidden" name="check_keywords" value="yes" />
|
||||
<input type="hidden" name="area" value="default" />
|
||||
</form>
|
||||
</div>
|
||||
</div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
|
||||
<p class="caption"><span class="caption-text">Overview</span></p>
|
||||
<ul>
|
||||
<li class="toctree-l1"><a class="reference internal" href="project.html">Project Design</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="types.html">Basic Types of Plugins</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="hooks.html">Plugin Hooks</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="anatomy.html">Plugin Anatomy</a></li>
|
||||
</ul>
|
||||
<p class="caption"><span class="caption-text">Tutorials</span></p>
|
||||
<ul>
|
||||
<li class="toctree-l1"><a class="reference internal" href="build.html">Build and Deploy</a></li>
|
||||
</ul>
|
||||
<p class="caption"><span class="caption-text">Reference</span></p>
|
||||
<ul class="current">
|
||||
<li class="toctree-l1"><a class="reference internal" href="system_req.html">System Requirements</a></li>
|
||||
<li class="toctree-l1 current"><a class="current reference internal" href="#">Plugin Loader</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="plugin_hooks.html">Plugin Hooks</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="core_restricted.html">Core vs Restricted packages in Plugeth-utils</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="api.html">API</a></li>
|
||||
</ul>
|
||||
<p class="caption"><span class="caption-text">Contact</span></p>
|
||||
<ul>
|
||||
<li class="toctree-l1"><a class="reference internal" href="contact.html">Get in touch with us</a></li>
|
||||
</ul>
|
||||
|
||||
</div>
|
||||
</div>
|
||||
</nav>
|
||||
|
||||
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" >
|
||||
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
|
||||
<a href="index.html">Plugeth</a>
|
||||
</nav>
|
||||
|
||||
<div class="wy-nav-content">
|
||||
<div class="rst-content">
|
||||
<div role="navigation" aria-label="Page navigation">
|
||||
<ul class="wy-breadcrumbs">
|
||||
<li><a href="index.html" class="icon icon-home"></a> »</li>
|
||||
<li>Plugin Loader</li>
|
||||
<li class="wy-breadcrumbs-aside">
|
||||
<a href="_sources/plugin_loader.rst.txt" rel="nofollow"> View page source</a>
|
||||
</li>
|
||||
</ul>
|
||||
<hr/>
|
||||
</div>
|
||||
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
|
||||
<div itemprop="articleBody">
|
||||
|
||||
<div class="section" id="plugin-loader">
|
||||
<span id="id1"></span><h1>Plugin Loader<a class="headerlink" href="#plugin-loader" title="Permalink to this headline">¶</a></h1>
|
||||
<div class="admonition-todo admonition" id="id2">
|
||||
<p class="admonition-title">Todo</p>
|
||||
<p>breakdown of plugin loader function</p>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
|
||||
</div>
|
||||
</div>
|
||||
<footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
|
||||
<a href="system_req.html" class="btn btn-neutral float-left" title="System Requirements" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
|
||||
<a href="plugin_hooks.html" class="btn btn-neutral float-right" title="Plugin Hooks" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
|
||||
</div>
|
||||
|
||||
<hr/>
|
||||
|
||||
<div role="contentinfo">
|
||||
<p>© Copyright 2021, Philip Morlier.</p>
|
||||
</div>
|
||||
|
||||
Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
|
||||
<a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a>
|
||||
provided by <a href="https://readthedocs.org">Read the Docs</a>.
|
||||
|
||||
|
||||
</footer>
|
||||
</div>
|
||||
</div>
|
||||
</section>
|
||||
</div>
|
||||
<script>
|
||||
jQuery(function () {
|
||||
SphinxRtdTheme.Navigation.enable(true);
|
||||
});
|
||||
</script>
|
||||
|
||||
</body>
|
||||
</html>
|
||||
@ -37,15 +37,19 @@
|
||||
<li class="toctree-l1"><a class="reference internal" href="project.html">Project Design</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="types.html">Basic Types of Plugins</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="hooks.html">Plugin Hooks</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="anatomy.html">Anatomy of a Plugin</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="anatomy.html">Plugin Anatomy</a></li>
|
||||
</ul>
|
||||
<p class="caption"><span class="caption-text">Tutorials</span></p>
|
||||
<ul>
|
||||
<li class="toctree-l1"><a class="reference internal" href="build.html">Build</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="build.html">Build and Deploy</a></li>
|
||||
</ul>
|
||||
<p class="caption"><span class="caption-text">Reference</span></p>
|
||||
<ul>
|
||||
<li class="toctree-l1"><a class="reference internal" href="system_req.html">System Requirements</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="plugin_loader.html">Plugin Loader</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="plugin_hooks.html">Plugin Hooks</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="core_restricted.html">Core vs Restricted packages in Plugeth-utils</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="api.html">API</a></li>
|
||||
</ul>
|
||||
<p class="caption"><span class="caption-text">Contact</span></p>
|
||||
<ul>
|
||||
|
||||
@ -48,15 +48,19 @@
|
||||
</li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="types.html">Basic Types of Plugins</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="hooks.html">Plugin Hooks</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="anatomy.html">Anatomy of a Plugin</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="anatomy.html">Plugin Anatomy</a></li>
|
||||
</ul>
|
||||
<p class="caption"><span class="caption-text">Tutorials</span></p>
|
||||
<ul>
|
||||
<li class="toctree-l1"><a class="reference internal" href="build.html">Build</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="build.html">Build and Deploy</a></li>
|
||||
</ul>
|
||||
<p class="caption"><span class="caption-text">Reference</span></p>
|
||||
<ul>
|
||||
<li class="toctree-l1"><a class="reference internal" href="system_req.html">System Requirements</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="plugin_loader.html">Plugin Loader</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="plugin_hooks.html">Plugin Hooks</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="core_restricted.html">Core vs Restricted packages in Plugeth-utils</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="api.html">API</a></li>
|
||||
</ul>
|
||||
<p class="caption"><span class="caption-text">Contact</span></p>
|
||||
<ul>
|
||||
@ -92,7 +96,7 @@
|
||||
<p>Design Goals</p>
|
||||
<p>The upstream Geth client 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.</p>
|
||||
<p>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.</p>
|
||||
<p>Creating numerous different forks to fill a variety of different needs comes with a number of drawbacks. Forks tend to drift apart from each other. Many networks that forked from Geth long ago have stopped merging updates from Geth; this makes some sense, given that those networks have moved in different directions than Geth and merging upstream changes while properly maintaining consensus rules of an existing network could prove quite challenging. But not merging changes from upstream can mean that security updates are easily missed, especially when the upstream team <a href="#id4"><span class="problematic" id="id5">`obscures security updates as optimizations`_</span></a> as a matter of process.</p>
|
||||
<p>Creating numerous different forks to fill a variety of different needs comes with a number of drawbacks. Forks tend to drift apart from each other. Many networks that forked from Geth long ago have stopped merging updates from Geth; this makes some sense, given that those networks have moved in different directions than Geth and merging upstream changes while properly maintaining consensus rules of an existing network could prove quite challenging. But not merging changes from upstream can mean that security updates are easily missed, especially when the upstream team <a class="reference external" href="https://blog.openrelay.xyz/vulnerability-lifecycle-framework-geth/">obscures security updates as optimizations</a> as a matter of process.</p>
|
||||
<p>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.</p>
|
||||
<div class="section" id="three-repositories">
|
||||
<h2>Three Repositories<a class="headerlink" href="#three-repositories" title="Permalink to this headline">¶</a></h2>
|
||||
@ -112,7 +116,10 @@
|
||||
</div>
|
||||
<div class="section" id="dependency-scheme">
|
||||
<h2>Dependency Scheme<a class="headerlink" href="#dependency-scheme" title="Permalink to this headline">¶</a></h2>
|
||||
<p><strong>todo: copy on version number protocol</strong></p>
|
||||
<div class="admonition-todo admonition" id="id1">
|
||||
<p class="admonition-title">Todo</p>
|
||||
<p>needs elaboration of dependency scheme</p>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
|
||||
@ -40,15 +40,19 @@
|
||||
<li class="toctree-l1"><a class="reference internal" href="project.html">Project Design</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="types.html">Basic Types of Plugins</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="hooks.html">Plugin Hooks</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="anatomy.html">Anatomy of a Plugin</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="anatomy.html">Plugin Anatomy</a></li>
|
||||
</ul>
|
||||
<p class="caption"><span class="caption-text">Tutorials</span></p>
|
||||
<ul>
|
||||
<li class="toctree-l1"><a class="reference internal" href="build.html">Build</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="build.html">Build and Deploy</a></li>
|
||||
</ul>
|
||||
<p class="caption"><span class="caption-text">Reference</span></p>
|
||||
<ul>
|
||||
<li class="toctree-l1"><a class="reference internal" href="system_req.html">System Requirements</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="plugin_loader.html">Plugin Loader</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="plugin_hooks.html">Plugin Hooks</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="core_restricted.html">Core vs Restricted packages in Plugeth-utils</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="api.html">API</a></li>
|
||||
</ul>
|
||||
<p class="caption"><span class="caption-text">Contact</span></p>
|
||||
<ul>
|
||||
|
||||
File diff suppressed because one or more lines are too long
@ -15,6 +15,8 @@
|
||||
<script src="_static/js/theme.js"></script>
|
||||
<link rel="index" title="Index" href="genindex.html" />
|
||||
<link rel="search" title="Search" href="search.html" />
|
||||
<link rel="next" title="Plugin Loader" href="plugin_loader.html" />
|
||||
<link rel="prev" title="Build and Deploy" href="build.html" />
|
||||
</head>
|
||||
|
||||
<body class="wy-body-for-nav">
|
||||
@ -37,15 +39,19 @@
|
||||
<li class="toctree-l1"><a class="reference internal" href="project.html">Project Design</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="types.html">Basic Types of Plugins</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="hooks.html">Plugin Hooks</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="anatomy.html">Anatomy of a Plugin</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="anatomy.html">Plugin Anatomy</a></li>
|
||||
</ul>
|
||||
<p class="caption"><span class="caption-text">Tutorials</span></p>
|
||||
<ul>
|
||||
<li class="toctree-l1"><a class="reference internal" href="build.html">Build</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="build.html">Build and Deploy</a></li>
|
||||
</ul>
|
||||
<p class="caption"><span class="caption-text">Reference</span></p>
|
||||
<ul>
|
||||
<ul class="current">
|
||||
<li class="toctree-l1 current"><a class="current reference internal" href="#">System Requirements</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="plugin_loader.html">Plugin Loader</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="plugin_hooks.html">Plugin Hooks</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="core_restricted.html">Core vs Restricted packages in Plugeth-utils</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="api.html">API</a></li>
|
||||
</ul>
|
||||
<p class="caption"><span class="caption-text">Contact</span></p>
|
||||
<ul>
|
||||
@ -85,7 +91,10 @@
|
||||
|
||||
</div>
|
||||
</div>
|
||||
<footer>
|
||||
<footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
|
||||
<a href="build.html" class="btn btn-neutral float-left" title="Build and Deploy" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
|
||||
<a href="plugin_loader.html" class="btn btn-neutral float-right" title="Plugin Loader" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
|
||||
</div>
|
||||
|
||||
<hr/>
|
||||
|
||||
|
||||
@ -45,15 +45,19 @@
|
||||
</ul>
|
||||
</li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="hooks.html">Plugin Hooks</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="anatomy.html">Anatomy of a Plugin</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="anatomy.html">Plugin Anatomy</a></li>
|
||||
</ul>
|
||||
<p class="caption"><span class="caption-text">Tutorials</span></p>
|
||||
<ul>
|
||||
<li class="toctree-l1"><a class="reference internal" href="build.html">Build</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="build.html">Build and Deploy</a></li>
|
||||
</ul>
|
||||
<p class="caption"><span class="caption-text">Reference</span></p>
|
||||
<ul>
|
||||
<li class="toctree-l1"><a class="reference internal" href="system_req.html">System Requirements</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="plugin_loader.html">Plugin Loader</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="plugin_hooks.html">Plugin Hooks</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="core_restricted.html">Core vs Restricted packages in Plugeth-utils</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="api.html">API</a></li>
|
||||
</ul>
|
||||
<p class="caption"><span class="caption-text">Contact</span></p>
|
||||
<ul>
|
||||
|
||||
@ -37,15 +37,19 @@
|
||||
<li class="toctree-l1"><a class="reference internal" href="project.html">Project Design</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="types.html">Basic Types of Plugins</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="hooks.html">Plugin Hooks</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="anatomy.html">Anatomy of a Plugin</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="anatomy.html">Plugin Anatomy</a></li>
|
||||
</ul>
|
||||
<p class="caption"><span class="caption-text">Tutorials</span></p>
|
||||
<ul>
|
||||
<li class="toctree-l1"><a class="reference internal" href="build.html">Build</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="build.html">Build and Deploy</a></li>
|
||||
</ul>
|
||||
<p class="caption"><span class="caption-text">Reference</span></p>
|
||||
<ul>
|
||||
<li class="toctree-l1"><a class="reference internal" href="system_req.html">System Requirements</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="plugin_loader.html">Plugin Loader</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="plugin_hooks.html">Plugin Hooks</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="core_restricted.html">Core vs Restricted packages in Plugeth-utils</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="api.html">API</a></li>
|
||||
</ul>
|
||||
<p class="caption"><span class="caption-text">Contact</span></p>
|
||||
<ul>
|
||||
|
||||
@ -1,122 +1,7 @@
|
||||
.. _anatomy:
|
||||
|
||||
===================
|
||||
Anatomy of a Plugin
|
||||
===================
|
||||
==============
|
||||
Plugin Anatomy
|
||||
==============
|
||||
|
||||
Plugins for Plugeth use Golang's `Native Plugin System`_. Plugin modules must export variables using specific names and types. These will be processed by the plugin loader, and invoked at certain points during Geth's operations.
|
||||
|
||||
API
|
||||
***
|
||||
|
||||
Flags
|
||||
-----
|
||||
|
||||
* **Name:** Flags
|
||||
* **Type:** `flag.FlagSet`_
|
||||
* **Behavior:** This FlagSet will be parsed and your plugin will be able to access the resulting flags. Flags will be passed to Geth from the command line and are intended to of the plugin. Note that if any flags are provided, certain checks are disabled within Geth to avoid failing due to unexpected flags.
|
||||
|
||||
Subcommands
|
||||
-----------
|
||||
|
||||
* **Name:** Subcommands
|
||||
* **Type:** map[string]func(ctx `*cli.Context`_, args []string) error
|
||||
* **Behavior:** If Geth is invoked with ``./geth YOUR_COMMAND``, the plugin loader will look for ``YOUR_COMMAND`` within this map, and invoke the corresponding function. This can be useful for certain behaviors like manipulating Geth's database without having to build a separate binary.
|
||||
|
||||
Initialize
|
||||
----------
|
||||
|
||||
* **Name:** Initialize
|
||||
* **Type:** func(*cli.Context, core.PluginLoader, core.logs )
|
||||
* **Behavior:** Called as soon as the plugin is loaded, with the cli context and a reference to the plugin loader. This is your plugin's opportunity to initialize required variables as needed. Note that using the context object you can check arguments, and optionally can manipulate arguments if needed for your plugin.
|
||||
:ref:`Core vs Restricted packages in Plugeth-utils`
|
||||
|
||||
**todo: explain that plugin could provide node.Node with restricted.backend**
|
||||
|
||||
InitializeNode
|
||||
--------------
|
||||
|
||||
* **Name:** InitializeNode
|
||||
* **Type:** func(core.Node, core.Backend)
|
||||
* **Behavior:** 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 a wide array of data you may need to access.
|
||||
|
||||
Tracers
|
||||
-------
|
||||
|
||||
* **Name:** Tracers
|
||||
* **Type:** map[string]TracerResult
|
||||
* **Behavior:** When calling debug.traceX functions (such as ``debug_traceCall`` and ``debug_traceTransaction``) the tracer can be specified as a key to this map and the tracer used will be the TracerResult specified here. TracerResult objects must match the interface:
|
||||
|
||||
.. code-block:: go
|
||||
|
||||
``// CaptureStart is called at the start of each transaction
|
||||
CaptureStart(env core.EVM, from core.Address, to core.Address, create bool, input []byte, gas uint64, value *big.Int) {}
|
||||
// CaptureState is called for each opcode
|
||||
CaptureState(env core.EVM, pc uint64, op core.OpCode, gas, cost uint64, scope *vm.ScopeContext, rData []byte, depth int, err error) {}
|
||||
// CaptureFault is called when an error occurs in the EVM
|
||||
CaptureFault(env core.EVM, pc uint64, op core.OpCode, gas, cost uint64, scope *vm.ScopeContext, depth int, err error) {}
|
||||
// CaptureEnd is called at the end of each transaction
|
||||
CaptureEnd(output []byte, gasUsed uint64, t time.Duration, err error) {}
|
||||
// GetResult should return a JSON serializable result object to respond to the trace call
|
||||
GetResult() (interface{}, error) {}``
|
||||
|
||||
|
||||
.. warning:: Modifying the values passed into tracer functions can alter the
|
||||
results of the EVM execution in unpredictable ways. Additonally, some objects may be reused acress calls, so data you wish to capture should be copied rather than retianed by reference.
|
||||
|
||||
LiveTracer
|
||||
----------
|
||||
|
||||
* **Name:** LiveTracers
|
||||
* **Type:** core.Tracer
|
||||
* **Behavior:** This tracer is used for tracing transactions as they are processed within blocks. Note that if a block does not validate, some transactions may be processed that don't end up in blocks, so be sure to check transactions against finalized blocks.
|
||||
|
||||
The interface for a vm.Tracer is similar to a TracerResult (above), but does not require a ``GetResult()`` function.
|
||||
|
||||
GetAPIs
|
||||
-------
|
||||
|
||||
* **Name:** GetAPIs
|
||||
* **Type:** func(core.Node, core.Backend) []rpc.API
|
||||
* **Behavior:** This allows you to register new RPC methods to run within Geth.
|
||||
|
||||
The GetAPIs function itself will generally be fairly brief, and will looks something like this:
|
||||
|
||||
.. code-block:: go
|
||||
|
||||
``func GetAPIs(stack *node.Node, backend core.Backend) []core.API {
|
||||
return []rpc.API{
|
||||
{
|
||||
Namespace: "mynamespace",
|
||||
Version: "1.0",
|
||||
Service: &MyService{backend},
|
||||
Public: true,
|
||||
},
|
||||
}
|
||||
}``
|
||||
|
||||
The bulk of the implementation will be in the ``MyService`` struct. MyService should be a struct with public functions. These functions can have two different types of signatures:
|
||||
|
||||
* RPC Calls: For straight RPC calls, a function should have a ``context.Context`` object as the first argument, followed by an arbitrary number of JSON marshallable arguments, and return either a single JSON marshal object, or a JSON marshallable object and an error. The RPC framework will take care of decoding inputs to this function and encoding outputs, and if the error is non-nil it will serve an error response.
|
||||
|
||||
* Subscriptions: For subscriptions (supported on IPC and websockets), a function should have a ``context.Context`` object as the first argument followed by an arbitrary number of JSON marshallable arguments, and should return an ``*rpc.Subscription`` object. The subscription object can be created with ``rpcSub := notifier.CreateSubscription()``, and JSON marshallable data can be sent to the subscriber with ``notifier.Notify(rpcSub.ID, b)``.
|
||||
|
||||
A very simple MyService might look like:
|
||||
|
||||
.. code-block:: go
|
||||
|
||||
``type MyService struct{}
|
||||
|
||||
func (h MyService) HelloWorld(ctx context.Context) string {
|
||||
return "Hello World"
|
||||
}``
|
||||
|
||||
And the client could access this with an rpc call to
|
||||
``mynamespace_helloworld``
|
||||
|
||||
|
||||
|
||||
|
||||
.. _*cli.Context: https://pkg.go.dev/github.com/urfave/cli#Context
|
||||
.. _flag.FlagSet: https://pkg.go.dev/flag#FlagSet
|
||||
.. _Native Plugin System: https://pkg.go.dev/plugin
|
||||
.. todo:: fill in disections of archetypal plugins
|
||||
120
documentation/api.rst
Normal file
120
documentation/api.rst
Normal file
@ -0,0 +1,120 @@
|
||||
.. _api:
|
||||
|
||||
===
|
||||
API
|
||||
===
|
||||
|
||||
Plugins for Plugeth use Golang's `Native Plugin System`_. Plugin modules must export variables using specific names and types. These will be processed by the plugin loader, and invoked at certain points during Geth's operations.
|
||||
|
||||
Flags
|
||||
-----
|
||||
|
||||
* **Name:** Flags
|
||||
* **Type:** `flag.FlagSet`_
|
||||
* **Behavior:** This FlagSet will be parsed and your plugin will be able to access the resulting flags. Flags will be passed to Geth from the command line and are intended to of the plugin. Note that if any flags are provided, certain checks are disabled within Geth to avoid failing due to unexpected flags.
|
||||
|
||||
Subcommands
|
||||
-----------
|
||||
|
||||
* **Name:** Subcommands
|
||||
* **Type:** map[string]func(ctx `*cli.Context`_, args []string) error
|
||||
* **Behavior:** If Geth is invoked with ``./geth YOUR_COMMAND``, the plugin loader will look for ``YOUR_COMMAND`` within this map, and invoke the corresponding function. This can be useful for certain behaviors like manipulating Geth's database without having to build a separate binary.
|
||||
|
||||
Initialize
|
||||
----------
|
||||
|
||||
* **Name:** Initialize
|
||||
* **Type:** func(*cli.Context, core.PluginLoader, core.logs )
|
||||
* **Behavior:** Called as soon as the plugin is loaded, with the cli context and a reference to the plugin loader. This is your plugin's opportunity to initialize required variables as needed. Note that using the context object you can check arguments, and optionally can manipulate arguments if needed for your plugin.
|
||||
|
||||
.. todo:: explain that plugin could provide node.Node with
|
||||
restricted.backend
|
||||
|
||||
InitializeNode
|
||||
--------------
|
||||
|
||||
* **Name:** InitializeNode
|
||||
* **Type:** func(core.Node, core.Backend)
|
||||
* **Behavior:** 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 a wide array of data you may need to access.
|
||||
|
||||
Tracers
|
||||
-------
|
||||
|
||||
* **Name:** Tracers
|
||||
* **Type:** map[string]TracerResult
|
||||
* **Behavior:** When calling debug.traceX functions (such as ``debug_traceCall`` and ``debug_traceTransaction``) the tracer can be specified as a key to this map and the tracer used will be the TracerResult specified here. TracerResult objects must match the interface:
|
||||
|
||||
.. code-block:: go
|
||||
|
||||
``// CaptureStart is called at the start of each transaction
|
||||
CaptureStart(env core.EVM, from core.Address, to core.Address, create bool, input []byte, gas uint64, value *big.Int) {}
|
||||
// CaptureState is called for each opcode
|
||||
CaptureState(env core.EVM, pc uint64, op core.OpCode, gas, cost uint64, scope *vm.ScopeContext, rData []byte, depth int, err error) {}
|
||||
// CaptureFault is called when an error occurs in the EVM
|
||||
CaptureFault(env core.EVM, pc uint64, op core.OpCode, gas, cost uint64, scope *vm.ScopeContext, depth int, err error) {}
|
||||
// CaptureEnd is called at the end of each transaction
|
||||
CaptureEnd(output []byte, gasUsed uint64, t time.Duration, err error) {}
|
||||
// GetResult should return a JSON serializable result object to respond to the trace call
|
||||
GetResult() (interface{}, error) {}``
|
||||
|
||||
|
||||
.. warning:: Modifying the values passed into tracer functions can
|
||||
alter the
|
||||
results of the EVM execution in unpredictable ways. Additonally, some objects may be reused acress calls, so data you wish to capture should be copied rather than retianed by reference.
|
||||
|
||||
LiveTracer
|
||||
----------
|
||||
|
||||
* **Name:** LiveTracers
|
||||
* **Type:** core.Tracer
|
||||
* **Behavior:** This tracer is used for tracing transactions as they are processed within blocks. Note that if a block does not validate, some transactions may be processed that don't end up in blocks, so be sure to check transactions against finalized blocks.
|
||||
|
||||
The interface for a vm.Tracer is similar to a TracerResult (above), but does not require a ``GetResult()`` function.
|
||||
|
||||
GetAPIs
|
||||
-------
|
||||
|
||||
* **Name:** GetAPIs
|
||||
* **Type:** func(core.Node, core.Backend) []rpc.API
|
||||
* **Behavior:** This allows you to register new RPC methods to run within Geth.
|
||||
|
||||
The GetAPIs function itself will generally be fairly brief, and will looks something like this:
|
||||
|
||||
.. code-block:: go
|
||||
|
||||
``func GetAPIs(stack *node.Node, backend core.Backend) []core.API {
|
||||
return []rpc.API{
|
||||
{
|
||||
Namespace: "mynamespace",
|
||||
Version: "1.0",
|
||||
Service: &MyService{backend},
|
||||
Public: true,
|
||||
},
|
||||
}
|
||||
}``
|
||||
|
||||
The bulk of the implementation will be in the ``MyService`` struct. MyService should be a struct with public functions. These functions can have two different types of signatures:
|
||||
|
||||
* RPC Calls: For straight RPC calls, a function should have a ``context.Context`` object as the first argument, followed by an arbitrary number of JSON marshallable arguments, and return either a single JSON marshal object, or a JSON marshallable object and an error. The RPC framework will take care of decoding inputs to this function and encoding outputs, and if the error is non-nil it will serve an error response.
|
||||
|
||||
* Subscriptions: For subscriptions (supported on IPC and websockets), a function should have a ``context.Context`` object as the first argument followed by an arbitrary number of JSON marshallable arguments, and should return an ``*rpc.Subscription`` object. The subscription object can be created with ``rpcSub := notifier.CreateSubscription()``, and JSON marshallable data can be sent to the subscriber with ``notifier.Notify(rpcSub.ID, b)``.
|
||||
|
||||
A very simple MyService might look like:
|
||||
|
||||
.. code-block:: go
|
||||
|
||||
``type MyService struct{}
|
||||
|
||||
func (h MyService) HelloWorld(ctx context.Context) string {
|
||||
return "Hello World"
|
||||
}``
|
||||
|
||||
And the client could access this with an rpc call to
|
||||
``mynamespace_helloworld``
|
||||
|
||||
|
||||
|
||||
|
||||
.. _*cli.Context: https://pkg.go.dev/github.com/urfave/cli#Context
|
||||
.. _flag.FlagSet: https://pkg.go.dev/flag#FlagSet
|
||||
.. _Native Plugin System: https://pkg.go.dev/plugin
|
||||
@ -1,7 +1,8 @@
|
||||
.. _build:
|
||||
|
||||
Build
|
||||
=====
|
||||
================
|
||||
Build and Deploy
|
||||
================
|
||||
|
||||
.. contents:: :local:
|
||||
|
||||
|
||||
@ -19,7 +19,7 @@
|
||||
|
||||
project = 'Plugeth'
|
||||
copyright = '2021, Philip Morlier'
|
||||
author = 'Philip Morlier'
|
||||
author = 'Philip Morlier, Austin Roberts'
|
||||
|
||||
# The full version, including alpha/beta/rc tags
|
||||
release = 'Austin Roberts'
|
||||
@ -31,8 +31,14 @@ release = 'Austin Roberts'
|
||||
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
|
||||
# ones.
|
||||
extensions = [
|
||||
'sphinx.ext.intersphinx',
|
||||
'sphinx.ext.autodoc',
|
||||
'sphinx.ext.doctest',
|
||||
'sphinx.ext.todo',
|
||||
]
|
||||
|
||||
todo_include_todos=True
|
||||
|
||||
# Add any paths that contain templates here, relative to this directory.
|
||||
templates_path = ['_templates']
|
||||
|
||||
|
||||
@ -4,4 +4,5 @@
|
||||
Core vs Restricted packages in Plugeth-utils
|
||||
============================================
|
||||
|
||||
**todo: copy on core and restricted packages in utils. what, why, how.**
|
||||
|
||||
.. todo:: need explinations of core vs restircted functionality. what, why, how.
|
||||
@ -4,5 +4,4 @@
|
||||
Plugin Hooks
|
||||
============
|
||||
|
||||
|
||||
**todo: discussion on plugin hooks**
|
||||
.. todo:: discussion of plugin hooks
|
||||
|
||||
@ -8,11 +8,12 @@ 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 of Geth.
|
||||
|
||||
**WARNING: UNSTABLE API**
|
||||
.. 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 isstability is added by plugins you might run. But if you plan to run PluGeth today, be aware that furture updates will likely break you plugins.
|
||||
|
||||
|
||||
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 future updates will likely break your plugins.
|
||||
|
||||
|
||||
Table of Contents
|
||||
*****************
|
||||
@ -27,6 +28,7 @@ Table of Contents
|
||||
hooks
|
||||
anatomy
|
||||
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
:caption: Tutorials
|
||||
@ -37,8 +39,11 @@ Table of Contents
|
||||
:maxdepth: 1
|
||||
:caption: Reference
|
||||
|
||||
sytem_req
|
||||
system_req
|
||||
plugin_loader
|
||||
plugin_hooks
|
||||
core_restricted
|
||||
api
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
7
documentation/plugin_hooks.rst
Normal file
7
documentation/plugin_hooks.rst
Normal file
@ -0,0 +1,7 @@
|
||||
.. _plugin_hooks:
|
||||
|
||||
============
|
||||
Plugin Hooks
|
||||
============
|
||||
|
||||
.. todo:: guide to writing plugin hooks
|
||||
7
documentation/plugin_loader.rst
Normal file
7
documentation/plugin_loader.rst
Normal file
@ -0,0 +1,7 @@
|
||||
.. _plugin_loader:
|
||||
|
||||
=============
|
||||
Plugin Loader
|
||||
=============
|
||||
|
||||
.. todo:: breakdown of plugin loader function
|
||||
@ -37,14 +37,14 @@ Plugins are packages which contain premade plugins as well as a location provide
|
||||
Dependency Scheme
|
||||
-----------------
|
||||
|
||||
**todo: copy on version number protocol**
|
||||
.. todo:: needs elaboration of dependency scheme
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
.. _obscures security updates as optimixations: https://blog.openrelay.xyz/vulnerability-lifecycle-framework-geth/
|
||||
.. _obscures security updates as optimizations: https://blog.openrelay.xyz/vulnerability-lifecycle-framework-geth/
|
||||
.. _PluGeth: https://github.com/openrelayxyz/plugeth
|
||||
.. _PluGeth-Utils: https://github.com/openrelayxyz/plugeth-utils
|
||||
.. _PluGeth-Plugins: https://github.com/openrelayxyz/plugeth-plugin
|
||||
Loading…
Reference in New Issue
Block a user