cerc-io/plugeth-utils
18
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Moving Austin's work into most current version

Browse Source
This commit is contained in:
philip-morlier 2021-10-05 15:43:09 -07:00
parent 3af8a5be89
commit 708c7643ee
No known key found for this signature in database
GPG Key ID: 0323A143B7B6F663
111 changed files with 21813 additions and 315 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

54
docs/RPC_method.rst Normal file
View File

@ -0,0 +1,54 @@
.. _RPC_method:
===========
RPC Methods
===========
GetAPIs
*******
For **RPC Methods** a Get APIs method is required in the body of the plugin in order to make the plugin available. The bulk of the implementation will be in the MyService struct. MyService should be a struct which includes two public functions.
.. code-block:: Go
type MyService struct {
backend core.Backend
stack core.Node
}
func GetAPIs(stack core.Node, backend core.Backend) []core.API {
return []core.API{
{
Namespace: "plugeth",
Version: "1.0",
Service: &MyService{backend, stack},
Public: true,
},
}
}
RPC Method
**********
(**accurate heading?**)
For 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.
A simple implimentation would look like so:
**eventual link to documentation for hello or some other rpc plugin**
.. code-block:: Go
func (h *MyService) HelloWorld(ctx context.Context) string {
return "Hello World"
}
.. Note:: For plugins such as RPC Methods whcih impliment a
GetAPIs function, an **Initialize Node** function may not be necesary as the ``core.Node`` and ``core.Backend`` will be made available with GetAPIs.
Access
******
As with pre-built plugins, a``.so`` will need to be built from``main.go`` and moved into ``~/.ethereum/plugins``. Geth will need to be started with with a ``http.api=mymamespace`` flag. Additionally you will need to include a ``--http`` flag in order to access the standard json rpc methods.
The plugin can now be accessed with an rpc call to ``mynamespace_helloWorld``.

BIN
docs/_build/doctrees/RPC_method.doctree vendored Normal file
View File

Binary file not shown.

BIN
docs/_build/doctrees/api.doctree vendored Normal file
View File

Binary file not shown.

BIN
docs/_build/doctrees/build.doctree vendored Normal file
View File

Binary file not shown.

BIN
docs/_build/doctrees/contact.doctree vendored Normal file
View File

Binary file not shown.

BIN
docs/_build/doctrees/core_restricted.doctree vendored Normal file
View File

Binary file not shown.

BIN
docs/_build/doctrees/custom.doctree vendored Normal file
View File

Binary file not shown.

BIN
docs/_build/doctrees/environment.pickle vendored Normal file
View File

Binary file not shown.

BIN
docs/_build/doctrees/hook_writing.doctree vendored Normal file
View File

Binary file not shown.

BIN
docs/_build/doctrees/hooks.doctree vendored Normal file
View File

Binary file not shown.

BIN
docs/_build/doctrees/index.doctree vendored Normal file
View File

Binary file not shown.

BIN
docs/_build/doctrees/install.doctree vendored Normal file
View File

Binary file not shown.

BIN
docs/_build/doctrees/plugin_loader.doctree vendored Normal file
View File

Binary file not shown.

BIN
docs/_build/doctrees/project.doctree vendored Normal file
View File

Binary file not shown.

BIN
docs/_build/doctrees/subscription.doctree vendored Normal file
View File

Binary file not shown.

BIN
docs/_build/doctrees/system_req.doctree vendored Normal file
View File

Binary file not shown.

BIN
docs/_build/doctrees/tracer.doctree vendored Normal file
View File

Binary file not shown.

BIN
docs/_build/doctrees/types.doctree vendored Normal file
View File

Binary file not shown.

BIN
docs/_build/doctrees/version.doctree vendored Normal file
View File

Binary file not shown.

4
docs/_build/html/.buildinfo vendored Normal file
View File

@ -0,0 +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: aa952c05dc8678fa4bab1d866c89bf40
tags: 645f666f9bcd5a90fca523b33c5a78b7

178
docs/_build/html/RPC_method.html vendored Normal file
View File

@ -0,0 +1,178 @@
<!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>RPC Methods &mdash; 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="Subscription" href="subscription.html" />
<link rel="prev" title="Building a Custom Plugin" href="custom.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>
</ul>
<p class="caption"><span class="caption-text">Tutorials</span></p>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="install.html">Install</a></li>
<li class="toctree-l1"><a class="reference internal" href="build.html">Build and Deploy</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="custom.html">Building a Custom Plugin</a><ul class="current">
<li class="toctree-l2 current"><a class="current reference internal" href="#">RPC Methods</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#getapis">GetAPIs</a></li>
<li class="toctree-l3"><a class="reference internal" href="#id1">RPC Method</a></li>
<li class="toctree-l3"><a class="reference internal" href="#access">Access</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="subscription.html">Subscription</a></li>
<li class="toctree-l2"><a class="reference internal" href="tracer.html">Tracer</a></li>
<li class="toctree-l2"><a class="reference internal" href="custom.html#basic-implementation">Basic Implementation</a></li>
<li class="toctree-l2"><a class="reference internal" href="custom.html#specialization">Specialization</a></li>
</ul>
</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="version.html">Version</a></li>
<li class="toctree-l1"><a class="reference internal" href="api.html">API</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="hooks.html">Selected Plugin Hooks</a></li>
<li class="toctree-l1"><a class="reference internal" href="hook_writing.html">Hook Writing Guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="core_restricted.html">PluGeth-utils Subpackages</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> &raquo;</li>
<li><a href="custom.html">Building a Custom Plugin</a> &raquo;</li>
<li>RPC Methods</li>
<li class="wy-breadcrumbs-aside">
<a href="_sources/RPC_method.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="rpc-methods">
<span id="rpc-method"></span><h1>RPC Methods<a class="headerlink" href="#rpc-methods" title="Permalink to this headline"></a></h1>
<div class="section" id="getapis">
<h2>GetAPIs<a class="headerlink" href="#getapis" title="Permalink to this headline"></a></h2>
<p>For <strong>RPC Methods</strong> a Get APIs method is required in the body of the plugin in order to make the plugin available. The bulk of the implementation will be in the MyService struct. MyService should be a struct which includes two public functions.</p>
<div class="highlight-Go notranslate"><div class="highlight"><pre><span></span><span class="kd">type</span> <span class="nx">MyService</span> <span class="kd">struct</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="nx">stack</span> <span class="nx">core</span><span class="p">.</span><span class="nx">Node</span>
<span class="p">}</span>
<span class="kd">func</span> <span class="nx">GetAPIs</span><span class="p">(</span><span class="nx">stack</span> <span class="nx">core</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">core</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">&quot;plugeth&quot;</span><span class="p">,</span>
<span class="nx">Version</span><span class="p">:</span> <span class="s">&quot;1.0&quot;</span><span class="p">,</span>
<span class="nx">Service</span><span class="p">:</span> <span class="o">&amp;</span><span class="nx">MyService</span><span class="p">{</span><span class="nx">backend</span><span class="p">,</span> <span class="nx">stack</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>
</pre></div>
</div>
</div>
<div class="section" id="id1">
<h2>RPC Method<a class="headerlink" href="#id1" title="Permalink to this headline"></a></h2>
<p>(<strong>accurate heading?</strong>)</p>
<p>For 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>
<p>A simple implimentation would look like so:</p>
<p><strong>eventual link to documentation for hello or some other rpc plugin</strong></p>
<div class="highlight-Go notranslate"><div class="highlight"><pre><span></span><span class="kd">func</span> <span class="p">(</span><span class="nx">h</span> <span class="o">*</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">&quot;Hello World&quot;</span>
<span class="p">}</span>
</pre></div>
</div>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>For plugins such as RPC Methods whcih impliment a
GetAPIs function, an <strong>Initialize Node</strong> function may not be necesary as the <code class="docutils literal notranslate"><span class="pre">core.Node</span></code> and <code class="docutils literal notranslate"><span class="pre">core.Backend</span></code> will be made available with GetAPIs.</p>
</div>
</div>
<div class="section" id="access">
<h2>Access<a class="headerlink" href="#access" title="Permalink to this headline"></a></h2>
<p>As with pre-built plugins, a``.so`` will need to be built from``main.go`` and moved into <code class="docutils literal notranslate"><span class="pre">~/.ethereum/plugins</span></code>. Geth will need to be started with with a <code class="docutils literal notranslate"><span class="pre">http.api=mymamespace</span></code> flag. Additionally you will need to include a <code class="docutils literal notranslate"><span class="pre">--http</span></code> flag in order to access the standard json rpc methods.</p>
<p>The plugin can now be accessed 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="custom.html" class="btn btn-neutral float-left" title="Building a Custom Plugin" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
<a href="subscription.html" class="btn btn-neutral float-right" title="Subscription" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
</div>
<hr/>
<div role="contentinfo">
<p>&#169; 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>

54
docs/_build/html/_sources/RPC_method.rst.txt vendored Normal file
View File

@ -0,0 +1,54 @@
.. _RPC_method:
===========
RPC Methods
===========
GetAPIs
*******
For **RPC Methods** a Get APIs method is required in the body of the plugin in order to make the plugin available. The bulk of the implementation will be in the MyService struct. MyService should be a struct which includes two public functions.
.. code-block:: Go
type MyService struct {
backend core.Backend
stack core.Node
}
func GetAPIs(stack core.Node, backend core.Backend) []core.API {
return []core.API{
{
Namespace: "plugeth",
Version: "1.0",
Service: &MyService{backend, stack},
Public: true,
},
}
}
RPC Method
**********
(**accurate heading?**)
For 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.
A simple implimentation would look like so:
**eventual link to documentation for hello or some other rpc plugin**
.. code-block:: Go
func (h *MyService) HelloWorld(ctx context.Context) string {
return "Hello World"
}
.. Note:: For plugins such as RPC Methods whcih impliment a
GetAPIs function, an **Initialize Node** function may not be necesary as the ``core.Node`` and ``core.Backend`` will be made available with GetAPIs.
Access
******
As with pre-built plugins, a``.so`` will need to be built from``main.go`` and moved into ``~/.ethereum/plugins``. Geth will need to be started with with a ``http.api=mymamespace`` flag. Additionally you will need to include a ``--http`` flag in order to access the standard json rpc methods.
The plugin can now be accessed with an rpc call to ``mynamespace_helloWorld``.

360
docs/_build/html/_sources/api.rst.txt vendored Normal file
View File

@ -0,0 +1,360 @@
.. _api:
===
API
===
Anatomy of a Plugin
===================
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.
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``
Injected APIs
=============
In addition to hooks that get invoked by Geth, several objects are injected that give you access to additional information.
Backend Object
--------------
The ``core.Backend`` object is injected by the ``InitializeNode()`` and ``GetAPI()`` functions. It offers the following functions:
Downloader
**********
``Downloader() Downloader``
Returns a Downloader objects, which can provide Syncing status
SuggestGasTipCap
****************
``SuggestGasTipCap(ctx context.Context) (*big.Int, error)``
Suggests a Gas tip for the current block.
ExtRPCEnabled
*************
``ExtRPCEnabled() bool``
Returns whether RPC external RPC calls are enabled.
RPCGasCap
*********
``RPCGasCap() uint64``
Returns the maximum Gas available to RPC Calls.
RPCTxFeeCap
***********
``RPCTxFeeCap() float64``
Returns the maximum transaction fee for a transaction submitted via RPC.
UnprotectedAllowed
******************
``UnprotectedAllowed() bool``
Returns whether or not unprotected transactions can be transmitted through this
node via RPC.
SetHead
*******
``SetHead(number uint64)``
Resets the head to the specified block number.
HeaderByNumber
**************
``HeaderByNumber(ctx context.Context, number int64) ([]byte, error)``
Returns an RLP encoded block header for the specified block number.
The RLP encoded response can be decoded into a `plugeth-utils/restricted/types.Header` object.
HeaderByHash
************
``HeaderByHash(ctx context.Context, hash Hash) ([]byte, error)``
Returns an RLP encoded block header for the specified block hash.
The RLP encoded response can be decoded into a `plugeth-utils/restricted/types.Header` object.
CurrentHeader
*************
``CurrentHeader() []byte``
Returns an RLP encoded block header for the current block.
The RLP encoded response can be decoded into a `plugeth-utils/restricted/types.Header` object.
CurrentBlock
************
``CurrentBlock() []byte``
Returns an RLP encoded full block for the current block.
The RLP encoded response can be decoded into a `plugeth-utils/restricted/types.Block` object.
BlockByNumber
*************
``BlockByNumber(ctx context.Context, number int64) ([]byte, error)``
Returns an RLP encoded full block for the specified block number.
The RLP encoded response can be decoded into a `plugeth-utils/restricted/types.Block` object.
BlockByHash
***********
``BlockByHash(ctx context.Context, hash Hash) ([]byte, error)``
Returns an RLP encoded full block for the specified block hash.
The RLP encoded response can be decoded into a `plugeth-utils/restricted/types.Block` object.
GetReceipts
***********
``GetReceipts(ctx context.Context, hash Hash) ([]byte, error)``
Returns an JSON encoded list of receipts for the specified block hash.
The JSON encoded response can be decoded into a `plugeth-utils/restricted/types.Receipts` object.
GetTd
*****
``GetTd(ctx context.Context, hash Hash) *big.Int``
Returns the total difficulty for the specified block hash.
SubscribeChainEvent
*******************
``SubscribeChainEvent(ch chan<- ChainEvent) Subscription``
Subscribes the provided channel to new chain events.
SubscribeChainHeadEvent
***********************
``SubscribeChainHeadEvent(ch chan<- ChainHeadEvent) Subscription``
Subscribes the provided channel to new chain head events.
SubscribeChainSideEvent
***********************
``SubscribeChainSideEvent(ch chan<- ChainSideEvent) Subscription``
Subscribes the provided channel to new chain side events.
SendTx
******
``SendTx(ctx context.Context, signedTx []byte) error``
Sends an RLP encoded, signed transaction to the network.
GetTransaction
**************
``GetTransaction(ctx context.Context, txHash Hash) ([]byte, Hash, uint64, uint64, error)``
Returns an RLP encoded transaction at the specified hash, along with the hash and number of the included block, and the transaction's position within that block.
GetPoolTransactions
^^^^^^^^^^^^^^^^^^^
``GetPoolTransactions() ([][]byte, error)``
Returns a list of RLP encoded transactions found in the mempool
GetPoolTransaction
******************
``GetPoolTransaction(txHash Hash) []byte``
Returns the RLP encoded transaction from the mempool at the specified hash.
GetPoolNonce
************
``GetPoolNonce(ctx context.Context, addr Address) (uint64, error)``
Returns the nonce of the last transaction for a given address, including
transactions found in the mempool.
Stats
*****
``Stats() (pending int, queued int)``
Returns the number of pending and queued transactions in the mempool.
TxPoolContent
*************
``TxPoolContent() (map[Address][][]byte, map[Address][][]byte)``
Returns a map of addresses to the list of RLP encoded transactions pending in
the mempool, and queued in the mempool.
SubscribeNewTxsEvent
********************
``SubscribeNewTxsEvent(chan<- NewTxsEvent) Subscription``
Subscribe to a feed of new transactions added to the mempool.
GetLogs
*******
``GetLogs(ctx context.Context, blockHash Hash) ([][]byte, error)``
Returns a list of RLP encoded logs found in the specified block.
SubscribeLogsEvent
******************
``SubscribeLogsEvent(ch chan<- [][]byte) Subscription``
Subscribe to logs included in a confirmed block.
SubscribePendingLogsEvent
*************************
``SubscribePendingLogsEvent(ch chan<- [][]byte) Subscription``
Subscribe to logs from pending transactions.
SubscribeRemovedLogsEvent
*************************
``SubscribeRemovedLogsEvent(ch chan<- []byte) Subscription``
Subscribe to logs removed from the canonical chain in reorged blocks.
Node Object
-----------
The ``core.Node`` object is injected by the ``InitializeNode()`` and ``GetAPI()`` functions. It offers the following functions:
Server
******
``Server() Server``
The Server object provides access to ``server.PeerCount()``, the number of peers connected to the node.
DataDir
*******
``DataDir() string``
Returns the Ethereuem datadir.
InstanceDir
***********
``InstanceDir() string``
Returns the instancedir used by the protocol stack.
IPCEndpoint
***********
``IPCEndpoint() string``
The path of the IPC Endpoint for this node.
HTTPEndpoint
************
``HTTPEndpoint() string``
The url of the HTTP Endpoint for this node.
WSEndpoint
**********
``WSEndpoint() string``
The url of the websockets Endpoint for this node.
ResolvePath
***********
``ResolvePath(x string) string``
Resolves a path within the DataDir.
.. _*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
Logger
------
The Logger object is injected by the ``Initialize()`` function. It implements
logging based on the interfaces of `Log15 <https://github.com/inconshreveable/log15>`_.
.. _*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

82
docs/_build/html/_sources/build.rst.txt vendored Normal file
View File

@ -0,0 +1,82 @@
.. _build:
================
Build and Deploy
================
.. contents:: :local:
If you are ready to start building your own plugins go ahead and start here.
Setting up the environment
**************************
.. NOTE:: Plugeth is built on a fork of `Geth`_ and as such requires familiarity with `Go`_ and a funtional `environment`_ in which to build Go projects. Thankfully for everyone Go provides a compact and useful `tutorial`_ as well as a `space for practice`_.
PluGeth is an application built in three seperate repositories.
* `PluGeth`_
* `PluGeth-Utils`_
* `PluGeth-Plugins`_
For our purposed here you will only need to clone Plugeth and Plugeth-Plugins. Once you have them cloned you are ready to begin. First we need to build geth though the PluGeth project. Navigate to ``plugeth/cmd/geth`` and run:
.. code-block:: shell
$ go get
This will download all dependencies needed for the project. This process will take a moment or two the first time through. Next run:
.. code-block:: shell
$ go build
Once this is complete you should see a ``.ethereum`` folder in your home directory.
At this point you are ready to start downloading local ethereum nodes. In order to do so, from ``plugeth/cmd/geth`` run:
.. code-block:: shell
$ ./geth
.. NOTE:: ``./geth`` is the primary command to build a *Mainnet* node. Building a mainnet node requires at least 8 GB RAM, 2 CPUs, and 350 GB of SSD disks. However, dozens of available flags will change the behavior of whichever network you choose to connect to. ``--help`` is your friend.
Build a plugin
**************
For the sake of this tutorial we will be building the Hello plugin. Navigate to ``plugethPlugins/packages/hello``. Inside you will see a ``main.go`` file. From this location run:
.. code-block:: shell
$ go build -buildmode=plugin
This will compile the plugin and produce a ``hello.so`` file. Move ``hello.so`` into ``~/.ethereum/plugins`` . In order to use this plugin geth will need to be started with a ``http.api=mymamespace`` flag. Additionally you will need to include a ``--http`` flag in order to access the standard json rpc methods.
Once geth has started you should see that the first ``INFO`` log reads: ``initialized hello`` . A new json rpc method, called hello, has been been appended to the list of available json rpc methods. In order to access this method you will need to ``curl`` into the network with this command:
.. code-block:: shell
$ curl 127.0.0.1:8545 -H "Content-Type: application/json" --data '{"jsonrpc":"2.0","method":"mynamespace_hello","params":[],"id":0}'
You should see that the network has responded with:
.. code-block:: shell
``{"jsonrpc":"2.0","id":0,"result":"Hello world"}``
Congradulations. You have just built and run your first Plugeth plugin. From here you can follow the steps above to build any of the plugins you choose.
.. NOTE:: Each plugin will vary in terms of the requirements to deploy. Refer to the documentation of the plugin itself in order to assure
that you know how to use it.
.. _space for practice: https://tour.golang.org/welcome/1
.. _tutorial: https://tour.golang.org/welcome/1
.. _environment: https://golang.org/doc/code
.. _Go: https://golang.org/doc/
.. _Geth: https://geth.ethereum.org/
.. _PluGeth: https://github.com/openrelayxyz/plugeth
.. _PluGeth-Utils: https://github.com/openrelayxyz/plugeth-utils
.. _PluGeth-Plugins: https://github.com/openrelayxyz/plugeth-plugins

10
docs/_build/html/_sources/contact.rst.txt vendored Normal file
View File

@ -0,0 +1,10 @@
.. _contact:
====================
Get in touch with us
====================
We want to hear from you! The best way to reach the PluGeth team is through our Discord server. Drop in, say hello, we are anxious to hear your ideas and help work through any problems you may be having.
`Join our Discord <https://discord.gg/J3tQMWCVPn>`_

11
docs/_build/html/_sources/core_restricted.rst.txt vendored Normal file
View File

@ -0,0 +1,11 @@
.. _core_restricted:
=========================
PluGeth-utils Subpackages
=========================
PluGeth-utils is separated into two main packages: core, and restricted.
The `core` package has been implemented by the Rivet team, and is licensed under the MIT license, allowing it to be used in open source and closed source plugins alike. Nearly all plugins will need to import plugeth-utils/core in order to
The `restricted` package copies code from the go-ethereum project, which means it must be licensed under the LGPL license. If you import plugeth-utils/restricted, you must be sure that your plugin complies with requirements of linking to LGPL code, which will usually require making your source code available to anyone you distribute the plugin to.

83
docs/_build/html/_sources/custom.rst.txt vendored Normal file
View File

@ -0,0 +1,83 @@
.. _custom:
========================
Building a Custom Plugin
========================
.. toctree::
:hidden:
RPC_method
subscription
tracer
Before setting out to build a plugin it will be helpful to be familiar with the :ref:`types`. deifferent plugins will require different implimentation.
Basic Implementation
====================
In general, no matter which type of plugin you intend to build, all will share some common aspects.
Package
-------
Any plugin will need its own package located in the Plugeth-Plugins packages directory. The package will need to include a main.go from which the .so file will be built. The package and main file should share the same name and the name should be a word that describes the basic functionality of the plugin.
Initialize
----------
Most plugins will need to be initialized with an Initialize function. The initialize function will need to be passed at least three arguments: a cli.Context, core.PluginLoader, and a core.Logger.
And so, all plugins could have an intial template that looks something like this:
.. code-block:: Go
package main
import (
"github.com/openrelayxyz/plugeth-utils/core"
"gopkg.in/urfave/cli.v1"
)
var log core.Logger
func Initialize(ctx *cli.Context, loader core.PluginLoader, logger core.Logger) {
log = logger
log.Info("loaded New Custom Plugin")
}
InitializeNode
--------------
Many plugins will make use of the InitializeNode function. Implimentation will look like so:
.. code-block:: Go
func InitializeNode(stack core.Node, b core.Backend) {
backend = b
log.Info("Initialized node and backend")
}
This is called as soon as the Geth node is initialized. The core.Node object represents the running node with p2p and RPC capabilities, while the Backend gives you access to blocks and other data you may need to access.
Specialization
==============
From this point implimentation becomes more specialized to the particular plugin type. Continue from here for specific instructions for the following plugins:
* :ref:`RPC_method`
* :ref:`subscription`
* :ref:`tracer`
.. _blockupdates: https://github.com/openrelayxyz/plugeth-plugins/blob/master/packages/blockupdates/main.go
.. _hello: https://github.com/openrelayxyz/plugeth-plugins/blob/master/packages/hello/main.go

7
docs/_build/html/_sources/hook_writing.rst.txt vendored Normal file
View File

@ -0,0 +1,7 @@
.. _hook_writing:
==================
Hook Writing Guide
==================
.. todo:: Austin: guide to writing plugin hooks

121
docs/_build/html/_sources/hooks.rst.txt vendored Normal file
View File

@ -0,0 +1,121 @@
.. _hooks:
=====================
Selected Plugin Hooks
=====================
Plugin Hooks
************
Plugeth provides several :ref:`hooks` from which the plugin can capture data from Geth. Additionally in the case of **subcommands** the provided hooks are designed to change the behavior of Geth.
Hooks are called from functions within the plugin. For example, if we wanted to bring in data from the StateUpdate hook. We would impliment it like so:
(from `blockupdates`_)
.. code-block:: Go
func StateUpdate(blockRoot core.Hash, parentRoot core.Hash, destructs map[core.Hash]struct{}, accounts map[core.Hash][]byte, storage map[core.Hash]map[core.Hash][]byte, codeUpdates map[core.Hash][]byte) {
su := &stateUpdate{
Destructs: destructs,
Accounts: accounts,
Storage: storage,
Code: codeUpdates,
}
cache.Add(blockRoot, su)
data, _ := rlp.EncodeToBytes(su)
backend.ChainDb().Put(append([]byte("su"), blockRoot.Bytes()...), data)
}
Many hooks can be deployed in an one plugin as is the case with the **BlockUpdater** plugin.
.. contents:: :local:
StateUpdate
***********
**Function Signature**:``func(root common.Hash, parentRoot common.Hash, destructs map[common.Hash]struct{}, accounts map[common.Hash][]byte, storage map[common.Hash]map[common.Hash][]byte)``
The state update plugin provides a snapshot of the state subsystem in the form of a a stateUpdate object. The stateUpdate object contains all information transformed by a transaction but not the transaction itself.
Invoked for each new block, StateUpdate provides the changes to the blockchain state. root corresponds to the state root of the new block. parentRoot corresponds to the state root of the parent block. destructs serves as a set of accounts that self-destructed in this block. accounts maps the hash of each account address to the SlimRLP encoding of the account data. storage maps the hash of each account to a map of that account's stored data.
.. warning:: StateUpdate is only called if Geth is running with
``-snapshots=true``. This is the default behavior for Geth, but if you are explicitly running with ``--snapshot=false`` this function will not be invoked.
AppendAncient
*************
**Function Signature**:``func(number uint64, hash, header, body, receipts, td []byte)``
Invoked when the freezer moves a block from LevelDB to the ancients database. ``number`` is the number of the block. ``hash`` is the 32 byte hash of the block as a raw ``[]byte``. ``header``, ``body``, and ``receipts`` are the RLP encoded versions of their respective block elements. ``td`` is the byte encoded total difficulty of the block.
GetRPCCalls
***********
**Function Signature**:``func(string, string, string)``
Invoked when the RPC handler registers a method call. Returns the call ``id``, method ``name``, and any ``params`` that may have been passed in.
.. todo:: missing a couple of hooks
PreProcessBlock
***************
**Function Signature**:``func(*types.Block)``
Invoked before the transactions of a block are processed. Returns a block object.
PreProcessTransaction
*********************
**Function Signature**:``func(*types.Transaction, *types.Block, int)``
Invoked before each individual transaction of a block is processed. Returns a transaction, block, and index number.
BlockProcessingError
********************
**Function Signature**:``func(*types.Transaction, *types.Block, error)``
Invoked if an error occurs while processing a transaction. This only applies to errors that would unvalidate the block were this transaction is included not errors such as reverts or opcode errors. Returns a transaction, block, and error.
NewHead
*******
**Function Signature**:``func(*types.Block, common.Hash, []*types.Log)``
Invoked when a new block becomes the canonical latest block. Returns a block, hash, and log.
.. note:: If severtal blocks are processed in a group (such as
during a reorg) this may not be called for each block. You should track the prior latest head if you need to process intermediate blocks.
NewSideBlock
************
**Function Signature**:``func(*types.Block, common.Hash, []*types.Log)``
Invoked when a block is side-chained. Returns a block, has, and logs.
.. note:: Blocks passed to this method are non-canonical blocks.
Reorg
*****
**Function Signature**:``func(common *types.Block, oldChain, newChain types.Blocks)``
Invoked when a chain reorg occurs, that is; at least one block is removed and one block is added. (``oldChain`` is a list of removed blocks, ``newChain`` is a list of newliy added blocks, and ``common`` is the latest block that is an ancestor to both oldChain and newChain.) Returns a block, a list of old blocks, and a list of new blocks.
.. _blockupdates: https://github.com/openrelayxyz/plugeth-plugins/tree/master/packages/blockupdates
.. _StateUpdate: https://github.com/openrelayxyz/plugeth/blob/develop/core/state/plugin_hooks.go
.. _Invocation: https://github.com/openrelayxyz/plugeth/blob/develop/core/state/statedb.go#L955
.. _AppendAncient: https://github.com/openrelayxyz/plugeth/blob/develop/core/rawdb/plugin_hooks.go
.. _GetRPCCalls: https://github.com/openrelayxyz/plugeth/blob/develop/rpc/plugin_hooks.go
.. _NewHead: https://github.com/openrelayxyz/plugeth/blob/develop/core/plugin_hooks.go#L108

60
docs/_build/html/_sources/index.rst.txt vendored Normal file
View File

@ -0,0 +1,60 @@
=======
PluGeth
=======
PluGeth is a fork of the Go Ethereum Client, `Geth`_, that implements a plugin architecture allowing developers to extend Geth's capabilities in a number of different ways using plugins rather than having to create additional new forks.
From Here:
----------
- Ready for an overview of the project and some context? :ref:`project`
- If your goal is to run existing plugns without sourcecode: :ref:`install`
- If your goal is to build and deploy existing plugins or make custom plugins: :ref:`build`
.. 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.
Table of Contents
*****************
.. toctree::
:maxdepth: 1
:caption: Overview
project
types
.. toctree::
:maxdepth: 1
:caption: Tutorials
install
build
custom
.. toctree::
:maxdepth: 1
:caption: Reference
system_req
version
api
plugin_loader
hooks
hook_writing
core_restricted
.. toctree::
:maxdepth: 1
:caption: Contact
contact
.. _Geth: https://geth.ethereum.org/

29
docs/_build/html/_sources/install.rst.txt vendored Normal file
View File

@ -0,0 +1,29 @@
.. _install:
=======
Install
=======
PluGeth provides a pre-built PluGeth-Geth node as well as pre-built plugins available for download.
First download the latest PluGeth `binary release`_.
.. todo:: more language about installing download
Our curated list of plugin builds can be found `here`_
After downloading, move the .so files into the ~/.ethereum/plugins directory.
.. todo:: Build a binary release so as to provide a usable
example. Maybe a different example than hello so that there are two generic cases for which there are tutorials. -- or -- We should provide examples of the common scenerios in which geth has to be started with flags or connected to with web sockets.
.. _binary release: https://github.com/openrelayxyz/plugeth/releases
.. _here: https://www.youtube.com/watch?v=dQw4w9WgXcQ&ab_channel=RickAstley

62
docs/_build/html/_sources/plugin_loader.rst.txt vendored Normal file
View File

@ -0,0 +1,62 @@
.. _plugin_loader:
=============
Plugin Loader
=============
The Plugin Loader is provided to each Plugin through the Initialize()``
function. It provides plugins with:
Lookup
======
``Lookup(name string, validate func(interface{}) bool) []interface{}``
Returns a list of values from plugins identified by ``name``, which match the
provided ``validate`` predicate. For example:
.. code-block:: go
pl.Lookup("Version", func(item interface{}) bool {
_, ok := item.(int)
return ok
})
Would return a list of ``int`` objects named ``Version`` in any loaded plugins.
This can enable Plugins to interact with each other, accessing values and
functions implemented in other plugins.
GetFeed
=======
``GetFeed() Feed``
Returns a new feed that the plugin can used for publish/subscribe models.
For example:
.. code-block:: go
feed := pl.GetFeed()
go func() {
ch := make(chan string)
sub := feed.Subscribe(ch)
for {
select {
case item := <-ch:
// Do something with item
case err := <sub.Err():
log.Error("An error has occurred", "err", err)
sub.Unsubscribe()
close(ch)
return
}
}
}()
feed.Send("hello")
feed.Send("world")
Note that you can send any type through a feed, but the subscribed channel and
sent objects must be of matching types.

51
docs/_build/html/_sources/project.rst.txt vendored Normal file
View File

@ -0,0 +1,51 @@
.. _project:
==============
Project Design
==============
Design Goals
============
Upstream Geth exists primarily to serve as a client for the Ethereum mainnet, though it also supports a number of popular testnets. Supporting the Ethereum mainnet is a big enough challenge in its own right that the Geth team generally avoids changes to support other networks, or to provide features only a small handful of users would be interested in.
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.
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; 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 `obscures security updates as optimizations`_ as a matter of process.
PluGeth aims to provide a single Geth fork that developers can choose to extend rather than forking the Geth project. Out of the box, PluGeth behaves exactly like upstream Geth, but by installing plugins written in Golang, developers can extend its functionality in a wide variety of ways.
Three Repositories
==================
PluGeth is an application built in three repositories:
`PluGeth`_
**********
The largest of the three Repositories, PluGeth is a fork of Geth which has been modified to enable a plugin architecture. The Plugin loader, wrappers, and hooks all reside in this repository.
`PluGeth-Utils`_
****************
Utils are small packages used to develop PluGeth plugins without Geth dependencies. For a more detailed analysis of the reasons see :ref: `core_resticted`. Imports from Utils happen automatically and so most users need not clone a local version.
`PluGeth-Plugins`_
******************
The packages from which plugins are buile are stored here. This repository contains premade plugins as well as providing a location for storing new custom plugins.
Dependency Scheme
-----------------
:ref:`version`
.. _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-plugins

93
docs/_build/html/_sources/subscription.rst.txt vendored Normal file
View File

@ -0,0 +1,93 @@
.. _subscription:
============
Subscription
============
In addition to the initial template containing an intialize function, plugins providing **Subscriptions** will require two additional elements.
GetAPIs
*******
A GetAPIs method is required in the body of the plugin in order to make the plugin available. The bulk of the implementation will be in the MyService struct. MyService should be a struct which includes two public functions.
.. code-block:: Go
type MyService struct {
backend core.Backend
stack core.Node
}
func GetAPIs(stack core.Node, backend core.Backend) []core.API {
return []core.API{
{
Namespace: "plugeth",
Version: "1.0",
Service: &MyService{backend, stack},
Public: true,
},
}
}
Subscription Function
*********************
For subscriptions (supported on IPC and websockets), a function should take MyService as a reciever and a context.Context object as an argument and return a channel and an error. The following is a subscription function that impliments a timer.
.. code-block:: Go
func (*myservice) Timer(ctx context.Context) (<-chan int64, error) {
ticker := time.NewTicker(time.Second)
ch := make(chan int64)
go func() {
defer ticker.Stop()
for {
select {
case <-ctx.Done():
close(ch)
return
case t := <-ticker.C:
ch <- t.UnixNano()
}
}
}()
return ch, nil
}
.. warning:: Notice in the example above, the ``ctx.Done()`` or
Context.Done() method closes the channel. If this is not present the go routine will run for the life of the process.
Access
******
.. Note:: Plugins providing subscriptions can be accessed via IPC
and websockets. In the below example we will be using `wscat`_ to connect a websocket to a local Geth node.
As with pre-built plugins, a ``.so`` will need to be built from ``main.go`` and moved into ``~/.ethereum/plugins``. Geth will need to be started with with ``--ws --ws.api=mynamespace``flags. Additionally you will need to include a ``--http`` flag in order to access the standard json rpc methods.
After starting Geth, from a seperate terminal run:
.. code-block:: shell
wscat -c ws://127.0.0.1:8546
.. Note:: Websockets are available via port 8546
Once the connection has been established from the websocket cursor enter the following argument:
.. code-block:: shell
{"jsonrpc":"2.0","method":"mynamespace_hello","params":[],"id":0}
You should see that the network has responded with:
.. code-block:: shell
``{"jsonrpc":"2.0","id":0,"result":"Hello world"}``
.. _wscat: https://www.npmjs.com/package/wscat

9
docs/_build/html/_sources/system_req.rst.txt vendored Normal file
View File

@ -0,0 +1,9 @@
.. _system_req:
===================
System Requirements
===================
System requirements will vary depending on which network you are connecting to. On the Ethereum mainnet, you should have at least 8 GB RAM, 2 CPUs, and 350 GB of SSD disks.
PluGeth relies on Golang's Plugin implementation, which is only supported on Linux, FreeBSD, and macOS. Windows support is unlikely to be added in the foreseeable future.

71
docs/_build/html/_sources/tracer.rst.txt vendored Normal file
View File

@ -0,0 +1,71 @@
.. _tracer:
======
Tracer
======
In addition to the initial template containing an intialize function, plugins providing **Tracers** will require three additional elements.
.. Warning:: Caution: Modifying of the values passed into tracer
functions can alter the results of the EVM execution in unpredictable ways. Additionally, some objects may be reused across calls, so data you wish to capture should be copied rather than retained be reference.
MyService Struct
****************
First an empty MyService Struct.
.. code-block:: Go
type MyService struct {
}
Map
***
Next, a map of tracers to functions returning a ``core.TracerResult`` which will be implimented like so:
.. code-block:: Go
var Tracers = map[string]func(core.StateDB) core.TracerResult{
"myTracer": func(core.StateDB) core.TracerResult {
return &MyBasicTracerService{}
},
}
TracerResult Functions
**********************
Finally a series of functions which points to the MyService struct and coresponds to the interface which geth anticipates.
.. code-block:: Go
func (b *MyBasicTracerService) CaptureStart(from core.Address, to core.Address, create bool, input []byte, gas uint64, value *big.Int) {
}
func (b *MyBasicTracerService) CaptureState(pc uint64, op core.OpCode, gas, cost uint64, scope core.ScopeContext, rData []byte, depth int, err error) {
}
func (b *MyBasicTracerService) CaptureFault(pc uint64, op core.OpCode, gas, cost uint64, scope core.ScopeContext, depth int, err error) {
}
func (b *MyBasicTracerService) CaptureEnd(output []byte, gasUsed uint64, t time.Duration, err error) {
}
func (b *MyBasicTracerService) Result() (interface{}, error) { return "hello world", nil }
Access
******
As with pre-built plugins, a ``.so`` will need to be built from ``main.go`` and moved into ``~/.ethereum/plugins``. Geth will need to be started with with a ``--http.api+debug`` flag.
From a terminal pass the following argument to the api:
.. code-block:: shell
curl 127.0.0.1:8545 -H "Content-Type: application/json" --data '{"jsonrpc":"2.0","method":"debug_traceCall","params":[{"to":"0x32Be343B94f860124dC4fEe278FDCBD38C102D88"},"latest",{"tracer":"myTracer"}],"id":0}'
.. Note:: The address used above is a test adress and will need to
be replaced by whatever address you wish to access. Also ``traceCall`` is one of several methods available for use.
If using the template above, the call should return:
.. code-block:: shell
{"jsonrpc":"2.0","id":0,"result":"hello world"}

42
docs/_build/html/_sources/types.rst.txt vendored Normal file
View File

@ -0,0 +1,42 @@
.. _types:
======================
Basic Types of Plugins
======================
While PluGeth has been designed to be versatile and customizable, when learning the project it can be helpful to think of plugins as being of four different archetypes.
.. contents:: :local:
RPC Methods
-----------
These plugins provide new json rpc methods to access several objects containing real time and historic data.
Subcommand
------------
A subcommand redifines the total behavior of Geth and could stand on its own. In contrast with the other plugin types which, in general, are meant to capture and manipulate information, a subcommand is meant to change to overall behavior of Geth. It may do this in order to capture information but the primary fuctionality is a modulation of geth behaviour.
Tracers
-------
Tracers rely on historic data recompiled after execution to give insight into a transaction.
**placeholder for eventual discusion of LiveTracers**
Subscriptions
-------------
Subscriptions provide real time notification of data from the EVM as it processes transactions.
.. NOTE:: Plugins are not limited to a singular functionality and can be customized to operate as hybrids of the above. See `blockupdates`_ as an example.
.. todo:: Austin: I don't love this page. The informations is too
shallow.
.. _blockupdates: https://github.com/openrelayxyz/plugeth-plugins/tree/master/packages/blockupdates

47
docs/_build/html/_sources/version.rst.txt vendored Normal file
View File

@ -0,0 +1,47 @@
.. _version:
=======
Version
=======
PluGeth is separated into three packages in order to minimize dependency conflicts. Golang plugins cannot include different versions of the same packages as the program loading the plugin. If plugins had to import packages from PluGeth itself, a plugin build could only be loaded by that same version of PluGeth. By separating out the PluGeth-utils package, both PluGeth and the plugins must rely on the same version of PluGeth-utils, but plugins can be compatible with any version of PluGeth compiled with the same version of PluGeth-utils.
PluGeth builds will follow the naming convention:
.. code-block:: shell
geth-$PLUGETH_UTILS_VERSION-$GETH_VERSION-$RELEASE
For example:
.. code-block:: shell
geth-0.1.0-1.10.8-0
Tells us that:
* PluGeth-utils version is 0.1.0
* Geth version is 1.10.8
* This is the first release with that combination of dependencies.
Plugin builds will follow the naming convention:
.. code-block:: shell
$PLUGIN_NAME-$PLUGETH_UTILS_VERSION-$PLUGIN_VERSION
For example:
.. code-block:: shell
blockupdates-0.1.0-1.0.2
Tells us that:
* The plugin is "blockupdates"
* The PluGeth-utils version is 0.1.0
* The plugin version is 1.0.2
When a Geth update comes out, you can expect a release of `geth-0.1.0-1.10.9-0`, which will be compatible with the same set of plugins.
When PluGeth upgrades are necessary, plugins will need to be recompiled. Whenever possible, we will try to avoid forcing plugins to be recompiled for an immediate Geth upgrade. For example, if we have geth-0.1.0-1.10.8, and upgrade PluGeth-utils, we will have a geth-0.1.1-1.10.8, followed by a geth-0.1.1-1.10.9. This will give users time to upgrade plugins from PluGeth-utils 0.1.0 to 0.1.1 while staying on Geth 1.10.8, and when it is time to upgrade to Geth 1.10.9 they can continue using the plugins they were using with geth 1.10.8. Depending on upgrades to Geth, it may not always be possible to maintain compatibility with existing PluGeth versions, which will be noted in release notes.

856
docs/_build/html/_static/basic.css vendored Normal file
View File

@ -0,0 +1,856 @@
/*
* basic.css
* ~~~~~~~~~
*
* Sphinx stylesheet -- basic theme.
*
* :copyright: Copyright 2007-2021 by the Sphinx team, see AUTHORS.
* :license: BSD, see LICENSE for details.
*
*/
/* -- main layout ----------------------------------------------------------- */
div.clearer {
clear: both;
}
div.section::after {
display: block;
content: '';
clear: left;
}
/* -- relbar ---------------------------------------------------------------- */
div.related {
width: 100%;
font-size: 90%;
}
div.related h3 {
display: none;
}
div.related ul {
margin: 0;
padding: 0 0 0 10px;
list-style: none;
}
div.related li {
display: inline;
}
div.related li.right {
float: right;
margin-right: 5px;
}
/* -- sidebar --------------------------------------------------------------- */
div.sphinxsidebarwrapper {
padding: 10px 5px 0 10px;
}
div.sphinxsidebar {
float: left;
width: 230px;
margin-left: -100%;
font-size: 90%;
word-wrap: break-word;
overflow-wrap : break-word;
}
div.sphinxsidebar ul {
list-style: none;
}
div.sphinxsidebar ul ul,
div.sphinxsidebar ul.want-points {
margin-left: 20px;
list-style: square;
}
div.sphinxsidebar ul ul {
margin-top: 0;
margin-bottom: 0;
}
div.sphinxsidebar form {
margin-top: 10px;
}
div.sphinxsidebar input {
border: 1px solid #98dbcc;
font-family: sans-serif;
font-size: 1em;
}
div.sphinxsidebar #searchbox form.search {
overflow: hidden;
}
div.sphinxsidebar #searchbox input[type="text"] {
float: left;
width: 80%;
padding: 0.25em;
box-sizing: border-box;
}
div.sphinxsidebar #searchbox input[type="submit"] {
float: left;
width: 20%;
border-left: none;
padding: 0.25em;
box-sizing: border-box;
}
img {
border: 0;
max-width: 100%;
}
/* -- search page ----------------------------------------------------------- */
ul.search {
margin: 10px 0 0 20px;
padding: 0;
}
ul.search li {
padding: 5px 0 5px 20px;
background-image: url(file.png);
background-repeat: no-repeat;
background-position: 0 7px;
}
ul.search li a {
font-weight: bold;
}
ul.search li div.context {
color: #888;
margin: 2px 0 0 30px;
text-align: left;
}
ul.keywordmatches li.goodmatch a {
font-weight: bold;
}
/* -- index page ------------------------------------------------------------ */
table.contentstable {
width: 90%;
margin-left: auto;
margin-right: auto;
}
table.contentstable p.biglink {
line-height: 150%;
}
a.biglink {
font-size: 1.3em;
}
span.linkdescr {
font-style: italic;
padding-top: 5px;
font-size: 90%;
}
/* -- general index --------------------------------------------------------- */
table.indextable {
width: 100%;
}
table.indextable td {
text-align: left;
vertical-align: top;
}
table.indextable ul {
margin-top: 0;
margin-bottom: 0;
list-style-type: none;
}
table.indextable > tbody > tr > td > ul {
padding-left: 0em;
}
table.indextable tr.pcap {
height: 10px;
}
table.indextable tr.cap {
margin-top: 10px;
background-color: #f2f2f2;
}
img.toggler {
margin-right: 3px;
margin-top: 3px;
cursor: pointer;
}
div.modindex-jumpbox {
border-top: 1px solid #ddd;
border-bottom: 1px solid #ddd;
margin: 1em 0 1em 0;
padding: 0.4em;
}
div.genindex-jumpbox {
border-top: 1px solid #ddd;
border-bottom: 1px solid #ddd;
margin: 1em 0 1em 0;
padding: 0.4em;
}
/* -- domain module index --------------------------------------------------- */
table.modindextable td {
padding: 2px;
border-collapse: collapse;
}
/* -- general body styles --------------------------------------------------- */
div.body {
min-width: 450px;
max-width: 800px;
}
div.body p, div.body dd, div.body li, div.body blockquote {
-moz-hyphens: auto;
-ms-hyphens: auto;
-webkit-hyphens: auto;
hyphens: auto;
}
a.headerlink {
visibility: hidden;
}
a.brackets:before,
span.brackets > a:before{
content: "[";
}
a.brackets:after,
span.brackets > a:after {
content: "]";
}
h1:hover > a.headerlink,
h2:hover > a.headerlink,
h3:hover > a.headerlink,
h4:hover > a.headerlink,
h5:hover > a.headerlink,
h6:hover > a.headerlink,
dt:hover > a.headerlink,
caption:hover > a.headerlink,
p.caption:hover > a.headerlink,
div.code-block-caption:hover > a.headerlink {
visibility: visible;
}
div.body p.caption {
text-align: inherit;
}
div.body td {
text-align: left;
}
.first {
margin-top: 0 !important;
}
p.rubric {
margin-top: 30px;
font-weight: bold;
}
img.align-left, .figure.align-left, object.align-left {
clear: left;
float: left;
margin-right: 1em;
}
img.align-right, .figure.align-right, object.align-right {
clear: right;
float: right;
margin-left: 1em;
}
img.align-center, .figure.align-center, object.align-center {
display: block;
margin-left: auto;
margin-right: auto;
}
img.align-default, .figure.align-default {
display: block;
margin-left: auto;
margin-right: auto;
}
.align-left {
text-align: left;
}
.align-center {
text-align: center;
}
.align-default {
text-align: center;
}
.align-right {
text-align: right;
}
/* -- sidebars -------------------------------------------------------------- */
div.sidebar {
margin: 0 0 0.5em 1em;
border: 1px solid #ddb;
padding: 7px;
background-color: #ffe;
width: 40%;
float: right;
clear: right;
overflow-x: auto;
}
p.sidebar-title {
font-weight: bold;
}
div.admonition, div.topic, blockquote {
clear: left;
}
/* -- topics ---------------------------------------------------------------- */
div.topic {
border: 1px solid #ccc;
padding: 7px;
margin: 10px 0 10px 0;
}
p.topic-title {
font-size: 1.1em;
font-weight: bold;
margin-top: 10px;
}
/* -- admonitions ----------------------------------------------------------- */
div.admonition {
margin-top: 10px;
margin-bottom: 10px;
padding: 7px;
}
div.admonition dt {
font-weight: bold;
}
p.admonition-title {
margin: 0px 10px 5px 0px;
font-weight: bold;
}
div.body p.centered {
text-align: center;
margin-top: 25px;
}
/* -- content of sidebars/topics/admonitions -------------------------------- */
div.sidebar > :last-child,
div.topic > :last-child,
div.admonition > :last-child {
margin-bottom: 0;
}
div.sidebar::after,
div.topic::after,
div.admonition::after,
blockquote::after {
display: block;
content: '';
clear: both;
}
/* -- tables ---------------------------------------------------------------- */
table.docutils {
margin-top: 10px;
margin-bottom: 10px;
border: 0;
border-collapse: collapse;
}
table.align-center {
margin-left: auto;
margin-right: auto;
}
table.align-default {
margin-left: auto;
margin-right: auto;
}
table caption span.caption-number {
font-style: italic;
}
table caption span.caption-text {
}
table.docutils td, table.docutils th {
padding: 1px 8px 1px 5px;
border-top: 0;
border-left: 0;
border-right: 0;
border-bottom: 1px solid #aaa;
}
table.footnote td, table.footnote th {
border: 0 !important;
}
th {
text-align: left;
padding-right: 5px;
}
table.citation {
border-left: solid 1px gray;
margin-left: 1px;
}
table.citation td {
border-bottom: none;
}
th > :first-child,
td > :first-child {
margin-top: 0px;
}
th > :last-child,
td > :last-child {
margin-bottom: 0px;
}
/* -- figures --------------------------------------------------------------- */
div.figure {
margin: 0.5em;
padding: 0.5em;
}
div.figure p.caption {
padding: 0.3em;
}
div.figure p.caption span.caption-number {
font-style: italic;
}
div.figure p.caption span.caption-text {
}
/* -- field list styles ----------------------------------------------------- */
table.field-list td, table.field-list th {
border: 0 !important;
}
.field-list ul {
margin: 0;
padding-left: 1em;
}
.field-list p {
margin: 0;
}
.field-name {
-moz-hyphens: manual;
-ms-hyphens: manual;
-webkit-hyphens: manual;
hyphens: manual;
}
/* -- hlist styles ---------------------------------------------------------- */
table.hlist {
margin: 1em 0;
}
table.hlist td {
vertical-align: top;
}
/* -- other body styles ----------------------------------------------------- */
ol.arabic {
list-style: decimal;
}
ol.loweralpha {
list-style: lower-alpha;
}
ol.upperalpha {
list-style: upper-alpha;
}
ol.lowerroman {
list-style: lower-roman;
}
ol.upperroman {
list-style: upper-roman;
}
:not(li) > ol > li:first-child > :first-child,
:not(li) > ul > li:first-child > :first-child {
margin-top: 0px;
}
:not(li) > ol > li:last-child > :last-child,
:not(li) > ul > li:last-child > :last-child {
margin-bottom: 0px;
}
ol.simple ol p,
ol.simple ul p,
ul.simple ol p,
ul.simple ul p {
margin-top: 0;
}
ol.simple > li:not(:first-child) > p,
ul.simple > li:not(:first-child) > p {
margin-top: 0;
}
ol.simple p,
ul.simple p {
margin-bottom: 0;
}
dl.footnote > dt,
dl.citation > dt {
float: left;
margin-right: 0.5em;
}
dl.footnote > dd,
dl.citation > dd {
margin-bottom: 0em;
}
dl.footnote > dd:after,
dl.citation > dd:after {
content: "";
clear: both;
}
dl.field-list {
display: grid;
grid-template-columns: fit-content(30%) auto;
}
dl.field-list > dt {
font-weight: bold;
word-break: break-word;
padding-left: 0.5em;
padding-right: 5px;
}
dl.field-list > dt:after {
content: ":";
}
dl.field-list > dd {
padding-left: 0.5em;
margin-top: 0em;
margin-left: 0em;
margin-bottom: 0em;
}
dl {
margin-bottom: 15px;
}
dd > :first-child {
margin-top: 0px;
}
dd ul, dd table {
margin-bottom: 10px;
}
dd {
margin-top: 3px;
margin-bottom: 10px;
margin-left: 30px;
}
dl > dd:last-child,
dl > dd:last-child > :last-child {
margin-bottom: 0;
}
dt:target, span.highlighted {
background-color: #fbe54e;
}
rect.highlighted {
fill: #fbe54e;
}
dl.glossary dt {
font-weight: bold;
font-size: 1.1em;
}
.optional {
font-size: 1.3em;
}
.sig-paren {
font-size: larger;
}
.versionmodified {
font-style: italic;
}
.system-message {
background-color: #fda;
padding: 5px;
border: 3px solid red;
}
.footnote:target {
background-color: #ffa;
}
.line-block {
display: block;
margin-top: 1em;
margin-bottom: 1em;
}
.line-block .line-block {
margin-top: 0;
margin-bottom: 0;
margin-left: 1.5em;
}
.guilabel, .menuselection {
font-family: sans-serif;
}
.accelerator {
text-decoration: underline;
}
.classifier {
font-style: oblique;
}
.classifier:before {
font-style: normal;
margin: 0.5em;
content: ":";
}
abbr, acronym {
border-bottom: dotted 1px;
cursor: help;
}
/* -- code displays --------------------------------------------------------- */
pre {
overflow: auto;
overflow-y: hidden; /* fixes display issues on Chrome browsers */
}
pre, div[class*="highlight-"] {
clear: both;
}
span.pre {
-moz-hyphens: none;
-ms-hyphens: none;
-webkit-hyphens: none;
hyphens: none;
}
div[class*="highlight-"] {
margin: 1em 0;
}
td.linenos pre {
border: 0;
background-color: transparent;
color: #aaa;
}
table.highlighttable {
display: block;
}
table.highlighttable tbody {
display: block;
}
table.highlighttable tr {
display: flex;
}
table.highlighttable td {
margin: 0;
padding: 0;
}
table.highlighttable td.linenos {
padding-right: 0.5em;
}
table.highlighttable td.code {
flex: 1;
overflow: hidden;
}
.highlight .hll {
display: block;
}
div.highlight pre,
table.highlighttable pre {
margin: 0;
}
div.code-block-caption + div {
margin-top: 0;
}
div.code-block-caption {
margin-top: 1em;
padding: 2px 5px;
font-size: small;
}
div.code-block-caption code {
background-color: transparent;
}
table.highlighttable td.linenos,
span.linenos,
div.doctest > div.highlight span.gp { /* gp: Generic.Prompt */
user-select: none;
}
div.code-block-caption span.caption-number {
padding: 0.1em 0.3em;
font-style: italic;
}
div.code-block-caption span.caption-text {
}
div.literal-block-wrapper {
margin: 1em 0;
}
code.descname {
background-color: transparent;
font-weight: bold;
font-size: 1.2em;
}
code.descclassname {
background-color: transparent;
}
code.xref, a code {
background-color: transparent;
font-weight: bold;
}
h1 code, h2 code, h3 code, h4 code, h5 code, h6 code {
background-color: transparent;
}
.viewcode-link {
float: right;
}
.viewcode-back {
float: right;
font-family: sans-serif;
}
div.viewcode-block:target {
margin: -1px -10px;
padding: 0 10px;
}
/* -- math display ---------------------------------------------------------- */
img.math {
vertical-align: middle;
}
div.body div.math p {
text-align: center;
}
span.eqno {
float: right;
}
span.eqno a.headerlink {
position: absolute;
z-index: 1;
}
div.math:hover a.headerlink {
visibility: visible;
}
/* -- printout stylesheet --------------------------------------------------- */
@media print {
div.document,
div.documentwrapper,
div.bodywrapper {
margin: 0 !important;
width: 100%;
}
div.sphinxsidebar,
div.related,
div.footer,
#top-link {
display: none;
}
}

1
docs/_build/html/_static/css/badge_only.css vendored Normal file
View File

@ -0,0 +1 @@
.fa:before{-webkit-font-smoothing:antialiased}.clearfix{*zoom:1}.clearfix:after,.clearfix:before{display:table;content:""}.clearfix:after{clear:both}@font-face{font-family:FontAwesome;font-style:normal;font-weight:400;src:url(fonts/fontawesome-webfont.eot?674f50d287a8c48dc19ba404d20fe713?#iefix) format("embedded-opentype"),url(fonts/fontawesome-webfont.woff2?af7ae505a9eed503f8b8e6982036873e) format("woff2"),url(fonts/fontawesome-webfont.woff?fee66e712a8a08eef5805a46892932ad) format("woff"),url(fonts/fontawesome-webfont.ttf?b06871f281fee6b241d60582ae9369b9) format("truetype"),url(fonts/fontawesome-webfont.svg?912ec66d7572ff821749319396470bde#FontAwesome) format("svg")}.fa:before{font-family:FontAwesome;font-style:normal;font-weight:400;line-height:1}.fa:before,a .fa{text-decoration:inherit}.fa:before,a .fa,li .fa{display:inline-block}li .fa-large:before{width:1.875em}ul.fas{list-style-type:none;margin-left:2em;text-indent:-.8em}ul.fas li .fa{width:.8em}ul.fas li .fa-large:before{vertical-align:baseline}.fa-book:before,.icon-book:before{content:"\f02d"}.fa-caret-down:before,.icon-caret-down:before{content:"\f0d7"}.fa-caret-up:before,.icon-caret-up:before{content:"\f0d8"}.fa-caret-left:before,.icon-caret-left:before{content:"\f0d9"}.fa-caret-right:before,.icon-caret-right:before{content:"\f0da"}.rst-versions{position:fixed;bottom:0;left:0;width:300px;color:#fcfcfc;background:#1f1d1d;font-family:Lato,proxima-nova,Helvetica Neue,Arial,sans-serif;z-index:400}.rst-versions a{color:#2980b9;text-decoration:none}.rst-versions .rst-badge-small{display:none}.rst-versions .rst-current-version{padding:12px;background-color:#272525;display:block;text-align:right;font-size:90%;cursor:pointer;color:#27ae60}.rst-versions .rst-current-version:after{clear:both;content:"";display:block}.rst-versions .rst-current-version .fa{color:#fcfcfc}.rst-versions .rst-current-version .fa-book,.rst-versions .rst-current-version .icon-book{float:left}.rst-versions .rst-current-version.rst-out-of-date{background-color:#e74c3c;color:#fff}.rst-versions .rst-current-version.rst-active-old-version{background-color:#f1c40f;color:#000}.rst-versions.shift-up{height:auto;max-height:100%;overflow-y:scroll}.rst-versions.shift-up .rst-other-versions{display:block}.rst-versions .rst-other-versions{font-size:90%;padding:12px;color:grey;display:none}.rst-versions .rst-other-versions hr{display:block;height:1px;border:0;margin:20px 0;padding:0;border-top:1px solid #413d3d}.rst-versions .rst-other-versions dd{display:inline-block;margin:0}.rst-versions .rst-other-versions dd a{display:inline-block;padding:6px;color:#fcfcfc}.rst-versions.rst-badge{width:auto;bottom:20px;right:20px;left:auto;border:none;max-width:300px;max-height:90%}.rst-versions.rst-badge .fa-book,.rst-versions.rst-badge .icon-book{float:none;line-height:30px}.rst-versions.rst-badge.shift-up .rst-current-version{text-align:right}.rst-versions.rst-badge.shift-up .rst-current-version .fa-book,.rst-versions.rst-badge.shift-up .rst-current-version .icon-book{float:left}.rst-versions.rst-badge>.rst-current-version{width:auto;height:30px;line-height:30px;padding:0 6px;display:block;text-align:center}@media screen and (max-width:768px){.rst-versions{width:85%;display:none}.rst-versions.shift{display:block}}

BIN
docs/_build/html/_static/css/fonts/Roboto-Slab-Bold.woff vendored Normal file
View File

Binary file not shown.

BIN
docs/_build/html/_static/css/fonts/Roboto-Slab-Bold.woff2 vendored Normal file
View File

Binary file not shown.

BIN
docs/_build/html/_static/css/fonts/Roboto-Slab-Regular.woff vendored Normal file
View File

Binary file not shown.

BIN
docs/_build/html/_static/css/fonts/Roboto-Slab-Regular.woff2 vendored Normal file
View File

Binary file not shown.

BIN
docs/_build/html/_static/css/fonts/fontawesome-webfont.eot vendored Normal file
View File

Binary file not shown.

2671
docs/_build/html/_static/css/fonts/fontawesome-webfont.svg vendored Normal file
View File

File diff suppressed because it is too large Load Diff
Side by Side

After

Width:  |  Height:  |  Size: 434 KiB

BIN
docs/_build/html/_static/css/fonts/fontawesome-webfont.ttf vendored Normal file
View File

Binary file not shown.

BIN
docs/_build/html/_static/css/fonts/fontawesome-webfont.woff vendored Normal file
View File

Binary file not shown.

BIN
docs/_build/html/_static/css/fonts/fontawesome-webfont.woff2 vendored Normal file
View File

Binary file not shown.

BIN
docs/_build/html/_static/css/fonts/lato-bold-italic.woff vendored Normal file
View File

Binary file not shown.

BIN
docs/_build/html/_static/css/fonts/lato-bold-italic.woff2 vendored Normal file
View File

Binary file not shown.

BIN
docs/_build/html/_static/css/fonts/lato-bold.woff vendored Normal file
View File

Binary file not shown.

BIN
docs/_build/html/_static/css/fonts/lato-bold.woff2 vendored Normal file
View File

Binary file not shown.

BIN
docs/_build/html/_static/css/fonts/lato-normal-italic.woff vendored Normal file
View File

Binary file not shown.

BIN
docs/_build/html/_static/css/fonts/lato-normal-italic.woff2 vendored Normal file
View File

Binary file not shown.

BIN
docs/_build/html/_static/css/fonts/lato-normal.woff vendored Normal file
View File

Binary file not shown.

BIN
docs/_build/html/_static/css/fonts/lato-normal.woff2 vendored Normal file
View File

Binary file not shown.

4
docs/_build/html/_static/css/theme.css vendored Normal file
View File

File diff suppressed because one or more lines are too long

316
docs/_build/html/_static/doctools.js vendored Normal file
View File

@ -0,0 +1,316 @@
/*
* doctools.js
* ~~~~~~~~~~~
*
* Sphinx JavaScript utilities for all documentation.
*
* :copyright: Copyright 2007-2021 by the Sphinx team, see AUTHORS.
* :license: BSD, see LICENSE for details.
*
*/
/**
* select a different prefix for underscore
*/
$u = _.noConflict();
/**
* make the code below compatible with browsers without
* an installed firebug like debugger
if (!window.console || !console.firebug) {
var names = ["log", "debug", "info", "warn", "error", "assert", "dir",
"dirxml", "group", "groupEnd", "time", "timeEnd", "count", "trace",
"profile", "profileEnd"];
window.console = {};
for (var i = 0; i < names.length; ++i)
window.console[names[i]] = function() {};
}
*/
/**
* small helper function to urldecode strings
*/
jQuery.urldecode = function(x) {
return decodeURIComponent(x).replace(/\+/g, ' ');
};
/**
* small helper function to urlencode strings
*/
jQuery.urlencode = encodeURIComponent;
/**
* This function returns the parsed url parameters of the
* current request. Multiple values per key are supported,
* it will always return arrays of strings for the value parts.
*/
jQuery.getQueryParameters = function(s) {
if (typeof s === 'undefined')
s = document.location.search;
var parts = s.substr(s.indexOf('?') + 1).split('&');
var result = {};
for (var i = 0; i < parts.length; i++) {
var tmp = parts[i].split('=', 2);
var key = jQuery.urldecode(tmp[0]);
var value = jQuery.urldecode(tmp[1]);
if (key in result)
result[key].push(value);
else
result[key] = [value];
}
return result;
};
/**
* highlight a given string on a jquery object by wrapping it in
* span elements with the given class name.
*/
jQuery.fn.highlightText = function(text, className) {
function highlight(node, addItems) {
if (node.nodeType === 3) {
var val = node.nodeValue;
var pos = val.toLowerCase().indexOf(text);
if (pos >= 0 &&
!jQuery(node.parentNode).hasClass(className) &&
!jQuery(node.parentNode).hasClass("nohighlight")) {
var span;
var isInSVG = jQuery(node).closest("body, svg, foreignObject").is("svg");
if (isInSVG) {
span = document.createElementNS("http://www.w3.org/2000/svg", "tspan");
} else {
span = document.createElement("span");
span.className = className;
}
span.appendChild(document.createTextNode(val.substr(pos, text.length)));
node.parentNode.insertBefore(span, node.parentNode.insertBefore(
document.createTextNode(val.substr(pos + text.length)),
node.nextSibling));
node.nodeValue = val.substr(0, pos);
if (isInSVG) {
var rect = document.createElementNS("http://www.w3.org/2000/svg", "rect");
var bbox = node.parentElement.getBBox();
rect.x.baseVal.value = bbox.x;
rect.y.baseVal.value = bbox.y;
rect.width.baseVal.value = bbox.width;
rect.height.baseVal.value = bbox.height;
rect.setAttribute('class', className);
addItems.push({
"parent": node.parentNode,
"target": rect});
}
}
}
else if (!jQuery(node).is("button, select, textarea")) {
jQuery.each(node.childNodes, function() {
highlight(this, addItems);
});
}
}
var addItems = [];
var result = this.each(function() {
highlight(this, addItems);
});
for (var i = 0; i < addItems.length; ++i) {
jQuery(addItems[i].parent).before(addItems[i].target);
}
return result;
};
/*
* backward compatibility for jQuery.browser
* This will be supported until firefox bug is fixed.
*/
if (!jQuery.browser) {
jQuery.uaMatch = function(ua) {
ua = ua.toLowerCase();
var match = /(chrome)[ \/]([\w.]+)/.exec(ua) ||
/(webkit)[ \/]([\w.]+)/.exec(ua) ||
/(opera)(?:.*version|)[ \/]([\w.]+)/.exec(ua) ||
/(msie) ([\w.]+)/.exec(ua) ||
ua.indexOf("compatible") < 0 && /(mozilla)(?:.*? rv:([\w.]+)|)/.exec(ua) ||
[];
return {
browser: match[ 1 ] || "",
version: match[ 2 ] || "0"
};
};
jQuery.browser = {};
jQuery.browser[jQuery.uaMatch(navigator.userAgent).browser] = true;
}
/**
* Small JavaScript module for the documentation.
*/
var Documentation = {
init : function() {
this.fixFirefoxAnchorBug();
this.highlightSearchWords();
this.initIndexTable();
if (DOCUMENTATION_OPTIONS.NAVIGATION_WITH_KEYS) {
this.initOnKeyListeners();
}
},
/**
* i18n support
*/
TRANSLATIONS : {},
PLURAL_EXPR : function(n) { return n === 1 ? 0 : 1; },
LOCALE : 'unknown',
// gettext and ngettext don't access this so that the functions
// can safely bound to a different name (_ = Documentation.gettext)
gettext : function(string) {
var translated = Documentation.TRANSLATIONS[string];
if (typeof translated === 'undefined')
return string;
return (typeof translated === 'string') ? translated : translated[0];
},
ngettext : function(singular, plural, n) {
var translated = Documentation.TRANSLATIONS[singular];
if (typeof translated === 'undefined')
return (n == 1) ? singular : plural;
return translated[Documentation.PLURALEXPR(n)];
},
addTranslations : function(catalog) {
for (var key in catalog.messages)
this.TRANSLATIONS[key] = catalog.messages[key];
this.PLURAL_EXPR = new Function('n', 'return +(' + catalog.plural_expr + ')');
this.LOCALE = catalog.locale;
},
/**
* add context elements like header anchor links
*/
addContextElements : function() {
$('div[id] > :header:first').each(function() {
$('<a class="headerlink">\u00B6</a>').
attr('href', '#' + this.id).
attr('title', _('Permalink to this headline')).
appendTo(this);
});
$('dt[id]').each(function() {
$('<a class="headerlink">\u00B6</a>').
attr('href', '#' + this.id).
attr('title', _('Permalink to this definition')).
appendTo(this);
});
},
/**
* workaround a firefox stupidity
* see: https://bugzilla.mozilla.org/show_bug.cgi?id=645075
*/
fixFirefoxAnchorBug : function() {
if (document.location.hash && $.browser.mozilla)
window.setTimeout(function() {
document.location.href += '';
}, 10);
},
/**
* highlight the search words provided in the url in the text
*/
highlightSearchWords : function() {
var params = $.getQueryParameters();
var terms = (params.highlight) ? params.highlight[0].split(/\s+/) : [];
if (terms.length) {
var body = $('div.body');
if (!body.length) {
body = $('body');
}
window.setTimeout(function() {
$.each(terms, function() {
body.highlightText(this.toLowerCase(), 'highlighted');
});
}, 10);
$('<p class="highlight-link"><a href="javascript:Documentation.' +
'hideSearchWords()">' + _('Hide Search Matches') + '</a></p>')
.appendTo($('#searchbox'));
}
},
/**
* init the domain index toggle buttons
*/
initIndexTable : function() {
var togglers = $('img.toggler').click(function() {
var src = $(this).attr('src');
var idnum = $(this).attr('id').substr(7);
$('tr.cg-' + idnum).toggle();
if (src.substr(-9) === 'minus.png')
$(this).attr('src', src.substr(0, src.length-9) + 'plus.png');
else
$(this).attr('src', src.substr(0, src.length-8) + 'minus.png');
}).css('display', '');
if (DOCUMENTATION_OPTIONS.COLLAPSE_INDEX) {
togglers.click();
}
},
/**
* helper function to hide the search marks again
*/
hideSearchWords : function() {
$('#searchbox .highlight-link').fadeOut(300);
$('span.highlighted').removeClass('highlighted');
},
/**
* make the url absolute
*/
makeURL : function(relativeURL) {
return DOCUMENTATION_OPTIONS.URL_ROOT + '/' + relativeURL;
},
/**
* get the current relative url
*/
getCurrentURL : function() {
var path = document.location.pathname;
var parts = path.split(/\//);
$.each(DOCUMENTATION_OPTIONS.URL_ROOT.split(/\//), function() {
if (this === '..')
parts.pop();
});
var url = parts.join('/');
return path.substring(url.lastIndexOf('/') + 1, path.length - 1);
},
initOnKeyListeners: function() {
$(document).keydown(function(event) {
var activeElementType = document.activeElement.tagName;
// don't navigate when in search box, textarea, dropdown or button
if (activeElementType !== 'TEXTAREA' && activeElementType !== 'INPUT' && activeElementType !== 'SELECT'
&& activeElementType !== 'BUTTON' && !event.altKey && !event.ctrlKey && !event.metaKey
&& !event.shiftKey) {
switch (event.keyCode) {
case 37: // left
var prevHref = $('link[rel="prev"]').prop('href');
if (prevHref) {
window.location.href = prevHref;
return false;
}
case 39: // right
var nextHref = $('link[rel="next"]').prop('href');
if (nextHref) {
window.location.href = nextHref;
return false;
}
}
}
});
}
};
// quick alias for translations
_ = Documentation.gettext;
$(document).ready(function() {
Documentation.init();
});

12
docs/_build/html/_static/documentation_options.js vendored Normal file
View File

@ -0,0 +1,12 @@
var DOCUMENTATION_OPTIONS = {
URL_ROOT: document.getElementById("documentation_options").getAttribute('data-url_root'),
VERSION: 'Austin Roberts',
LANGUAGE: 'None',
COLLAPSE_INDEX: false,
BUILDER: 'html',
FILE_SUFFIX: '.html',
LINK_SUFFIX: '.html',
HAS_SOURCE: true,
SOURCELINK_SUFFIX: '.txt',
NAVIGATION_WITH_KEYS: false
};

BIN
docs/_build/html/_static/file.png vendored Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 286 B

10872
docs/_build/html/_static/jquery-3.5.1.js vendored Normal file
View File

File diff suppressed because it is too large Load Diff

2
docs/_build/html/_static/jquery.js vendored Normal file
View File

File diff suppressed because one or more lines are too long

1
docs/_build/html/_static/js/badge_only.js vendored Normal file
View File

@ -0,0 +1 @@
!function(e){var t={};function r(n){if(t[n])return t[n].exports;var o=t[n]={i:n,l:!1,exports:{}};return e[n].call(o.exports,o,o.exports,r),o.l=!0,o.exports}r.m=e,r.c=t,r.d=function(e,t,n){r.o(e,t)||Object.defineProperty(e,t,{enumerable:!0,get:n})},r.r=function(e){"undefined"!=typeof Symbol&&Symbol.toStringTag&&Object.defineProperty(e,Symbol.toStringTag,{value:"Module"}),Object.defineProperty(e,"__esModule",{value:!0})},r.t=function(e,t){if(1&t&&(e=r(e)),8&t)return e;if(4&t&&"object"==typeof e&&e&&e.__esModule)return e;var n=Object.create(null);if(r.r(n),Object.defineProperty(n,"default",{enumerable:!0,value:e}),2&t&&"string"!=typeof e)for(var o in e)r.d(n,o,function(t){return e[t]}.bind(null,o));return n},r.n=function(e){var t=e&&e.__esModule?function(){return e.default}:function(){return e};return r.d(t,"a",t),t},r.o=function(e,t){return Object.prototype.hasOwnProperty.call(e,t)},r.p="",r(r.s=4)}({4:function(e,t,r){}});

4
docs/_build/html/_static/js/html5shiv-printshiv.min.js vendored Normal file
View File

@ -0,0 +1,4 @@
/**
* @preserve HTML5 Shiv 3.7.3-pre | @afarkas @jdalton @jon_neal @rem | MIT/GPL2 Licensed
*/
!function(a,b){function c(a,b){var c=a.createElement("p"),d=a.getElementsByTagName("head")[0]||a.documentElement;return c.innerHTML="x<style>"+b+"</style>",d.insertBefore(c.lastChild,d.firstChild)}function d(){var a=y.elements;return"string"==typeof a?a.split(" "):a}function e(a,b){var c=y.elements;"string"!=typeof c&&(c=c.join(" ")),"string"!=typeof a&&(a=a.join(" ")),y.elements=c+" "+a,j(b)}function f(a){var b=x[a[v]];return b||(b={},w++,a[v]=w,x[w]=b),b}function g(a,c,d){if(c||(c=b),q)return c.createElement(a);d||(d=f(c));var e;return e=d.cache[a]?d.cache[a].cloneNode():u.test(a)?(d.cache[a]=d.createElem(a)).cloneNode():d.createElem(a),!e.canHaveChildren||t.test(a)||e.tagUrn?e:d.frag.appendChild(e)}function h(a,c){if(a||(a=b),q)return a.createDocumentFragment();c=c||f(a);for(var e=c.frag.cloneNode(),g=0,h=d(),i=h.length;i>g;g++)e.createElement(h[g]);return e}function i(a,b){b.cache||(b.cache={},b.createElem=a.createElement,b.createFrag=a.createDocumentFragment,b.frag=b.createFrag()),a.createElement=function(c){return y.shivMethods?g(c,a,b):b.createElem(c)},a.createDocumentFragment=Function("h,f","return function(){var n=f.cloneNode(),c=n.createElement;h.shivMethods&&("+d().join().replace(/[\w\-:]+/g,function(a){return b.createElem(a),b.frag.createElement(a),'c("'+a+'")'})+");return n}")(y,b.frag)}function j(a){a||(a=b);var d=f(a);return!y.shivCSS||p||d.hasCSS||(d.hasCSS=!!c(a,"article,aside,dialog,figcaption,figure,footer,header,hgroup,main,nav,section{display:block}mark{background:#FF0;color:#000}template{display:none}")),q||i(a,d),a}function k(a){for(var b,c=a.getElementsByTagName("*"),e=c.length,f=RegExp("^(?:"+d().join("|")+")$","i"),g=[];e--;)b=c[e],f.test(b.nodeName)&&g.push(b.applyElement(l(b)));return g}function l(a){for(var b,c=a.attributes,d=c.length,e=a.ownerDocument.createElement(A+":"+a.nodeName);d--;)b=c[d],b.specified&&e.setAttribute(b.nodeName,b.nodeValue);return e.style.cssText=a.style.cssText,e}function m(a){for(var b,c=a.split("{"),e=c.length,f=RegExp("(^|[\\s,>+~])("+d().join("|")+")(?=[[\\s,>+~#.:]|$)","gi"),g="$1"+A+"\\:$2";e--;)b=c[e]=c[e].split("}"),b[b.length-1]=b[b.length-1].replace(f,g),c[e]=b.join("}");return c.join("{")}function n(a){for(var b=a.length;b--;)a[b].removeNode()}function o(a){function b(){clearTimeout(g._removeSheetTimer),d&&d.removeNode(!0),d=null}var d,e,g=f(a),h=a.namespaces,i=a.parentWindow;return!B||a.printShived?a:("undefined"==typeof h[A]&&h.add(A),i.attachEvent("onbeforeprint",function(){b();for(var f,g,h,i=a.styleSheets,j=[],l=i.length,n=Array(l);l--;)n[l]=i[l];for(;h=n.pop();)if(!h.disabled&&z.test(h.media)){try{f=h.imports,g=f.length}catch(o){g=0}for(l=0;g>l;l++)n.push(f[l]);try{j.push(h.cssText)}catch(o){}}j=m(j.reverse().join("")),e=k(a),d=c(a,j)}),i.attachEvent("onafterprint",function(){n(e),clearTimeout(g._removeSheetTimer),g._removeSheetTimer=setTimeout(b,500)}),a.printShived=!0,a)}var p,q,r="3.7.3",s=a.html5||{},t=/^<|^(?:button|map|select|textarea|object|iframe|option|optgroup)$/i,u=/^(?:a|b|code|div|fieldset|h1|h2|h3|h4|h5|h6|i|label|li|ol|p|q|span|strong|style|table|tbody|td|th|tr|ul)$/i,v="_html5shiv",w=0,x={};!function(){try{var a=b.createElement("a");a.innerHTML="<xyz></xyz>",p="hidden"in a,q=1==a.childNodes.length||function(){b.createElement("a");var a=b.createDocumentFragment();return"undefined"==typeof a.cloneNode||"undefined"==typeof a.createDocumentFragment||"undefined"==typeof a.createElement}()}catch(c){p=!0,q=!0}}();var y={elements:s.elements||"abbr article aside audio bdi canvas data datalist details dialog figcaption figure footer header hgroup main mark meter nav output picture progress section summary template time video",version:r,shivCSS:s.shivCSS!==!1,supportsUnknownElements:q,shivMethods:s.shivMethods!==!1,type:"default",shivDocument:j,createElement:g,createDocumentFragment:h,addElements:e};a.html5=y,j(b);var z=/^$|\b(?:all|print)\b/,A="html5shiv",B=!q&&function(){var c=b.documentElement;return!("undefined"==typeof b.namespaces||"undefined"==typeof b.parentWindow||"undefined"==typeof c.applyElement||"undefined"==typeof c.removeNode||"undefined"==typeof a.attachEvent)}();y.type+=" print",y.shivPrint=o,o(b),"object"==typeof module&&module.exports&&(module.exports=y)}("undefined"!=typeof window?window:this,document);

4
docs/_build/html/_static/js/html5shiv.min.js vendored Normal file
View File

@ -0,0 +1,4 @@
/**
* @preserve HTML5 Shiv 3.7.3 | @afarkas @jdalton @jon_neal @rem | MIT/GPL2 Licensed
*/
!function(a,b){function c(a,b){var c=a.createElement("p"),d=a.getElementsByTagName("head")[0]||a.documentElement;return c.innerHTML="x<style>"+b+"</style>",d.insertBefore(c.lastChild,d.firstChild)}function d(){var a=t.elements;return"string"==typeof a?a.split(" "):a}function e(a,b){var c=t.elements;"string"!=typeof c&&(c=c.join(" ")),"string"!=typeof a&&(a=a.join(" ")),t.elements=c+" "+a,j(b)}function f(a){var b=s[a[q]];return b||(b={},r++,a[q]=r,s[r]=b),b}function g(a,c,d){if(c||(c=b),l)return c.createElement(a);d||(d=f(c));var e;return e=d.cache[a]?d.cache[a].cloneNode():p.test(a)?(d.cache[a]=d.createElem(a)).cloneNode():d.createElem(a),!e.canHaveChildren||o.test(a)||e.tagUrn?e:d.frag.appendChild(e)}function h(a,c){if(a||(a=b),l)return a.createDocumentFragment();c=c||f(a);for(var e=c.frag.cloneNode(),g=0,h=d(),i=h.length;i>g;g++)e.createElement(h[g]);return e}function i(a,b){b.cache||(b.cache={},b.createElem=a.createElement,b.createFrag=a.createDocumentFragment,b.frag=b.createFrag()),a.createElement=function(c){return t.shivMethods?g(c,a,b):b.createElem(c)},a.createDocumentFragment=Function("h,f","return function(){var n=f.cloneNode(),c=n.createElement;h.shivMethods&&("+d().join().replace(/[\w\-:]+/g,function(a){return b.createElem(a),b.frag.createElement(a),'c("'+a+'")'})+");return n}")(t,b.frag)}function j(a){a||(a=b);var d=f(a);return!t.shivCSS||k||d.hasCSS||(d.hasCSS=!!c(a,"article,aside,dialog,figcaption,figure,footer,header,hgroup,main,nav,section{display:block}mark{background:#FF0;color:#000}template{display:none}")),l||i(a,d),a}var k,l,m="3.7.3-pre",n=a.html5||{},o=/^<|^(?:button|map|select|textarea|object|iframe|option|optgroup)$/i,p=/^(?:a|b|code|div|fieldset|h1|h2|h3|h4|h5|h6|i|label|li|ol|p|q|span|strong|style|table|tbody|td|th|tr|ul)$/i,q="_html5shiv",r=0,s={};!function(){try{var a=b.createElement("a");a.innerHTML="<xyz></xyz>",k="hidden"in a,l=1==a.childNodes.length||function(){b.createElement("a");var a=b.createDocumentFragment();return"undefined"==typeof a.cloneNode||"undefined"==typeof a.createDocumentFragment||"undefined"==typeof a.createElement}()}catch(c){k=!0,l=!0}}();var t={elements:n.elements||"abbr article aside audio bdi canvas data datalist details dialog figcaption figure footer header hgroup main mark meter nav output picture progress section summary template time video",version:m,shivCSS:n.shivCSS!==!1,supportsUnknownElements:l,shivMethods:n.shivMethods!==!1,type:"default",shivDocument:j,createElement:g,createDocumentFragment:h,addElements:e};a.html5=t,j(b),"object"==typeof module&&module.exports&&(module.exports=t)}("undefined"!=typeof window?window:this,document);

1
docs/_build/html/_static/js/theme.js vendored Normal file
View File

File diff suppressed because one or more lines are too long

297
docs/_build/html/_static/language_data.js vendored Normal file
View File

@ -0,0 +1,297 @@
/*
* language_data.js
* ~~~~~~~~~~~~~~~~
*
* This script contains the language-specific data used by searchtools.js,
* namely the list of stopwords, stemmer, scorer and splitter.
*
* :copyright: Copyright 2007-2021 by the Sphinx team, see AUTHORS.
* :license: BSD, see LICENSE for details.
*
*/
var stopwords = ["a","and","are","as","at","be","but","by","for","if","in","into","is","it","near","no","not","of","on","or","such","that","the","their","then","there","these","they","this","to","was","will","with"];
/* Non-minified version JS is _stemmer.js if file is provided */
/**
* Porter Stemmer
*/
var Stemmer = function() {
var step2list = {
ational: 'ate',
tional: 'tion',
enci: 'ence',
anci: 'ance',
izer: 'ize',
bli: 'ble',
alli: 'al',
entli: 'ent',
eli: 'e',
ousli: 'ous',
ization: 'ize',
ation: 'ate',
ator: 'ate',
alism: 'al',
iveness: 'ive',
fulness: 'ful',
ousness: 'ous',
aliti: 'al',
iviti: 'ive',
biliti: 'ble',
logi: 'log'
};
var step3list = {
icate: 'ic',
ative: '',
alize: 'al',
iciti: 'ic',
ical: 'ic',
ful: '',
ness: ''
};
var c = "[^aeiou]"; // consonant
var v = "[aeiouy]"; // vowel
var C = c + "[^aeiouy]*"; // consonant sequence
var V = v + "[aeiou]*"; // vowel sequence
var mgr0 = "^(" + C + ")?" + V + C; // [C]VC... is m>0
var meq1 = "^(" + C + ")?" + V + C + "(" + V + ")?$"; // [C]VC[V] is m=1
var mgr1 = "^(" + C + ")?" + V + C + V + C; // [C]VCVC... is m>1
var s_v = "^(" + C + ")?" + v; // vowel in stem
this.stemWord = function (w) {
var stem;
var suffix;
var firstch;
var origword = w;
if (w.length < 3)
return w;
var re;
var re2;
var re3;
var re4;
firstch = w.substr(0,1);
if (firstch == "y")
w = firstch.toUpperCase() + w.substr(1);
// Step 1a
re = /^(.+?)(ss|i)es$/;
re2 = /^(.+?)([^s])s$/;
if (re.test(w))
w = w.replace(re,"$1$2");
else if (re2.test(w))
w = w.replace(re2,"$1$2");
// Step 1b
re = /^(.+?)eed$/;
re2 = /^(.+?)(ed|ing)$/;
if (re.test(w)) {
var fp = re.exec(w);
re = new RegExp(mgr0);
if (re.test(fp[1])) {
re = /.$/;
w = w.replace(re,"");
}
}
else if (re2.test(w)) {
var fp = re2.exec(w);
stem = fp[1];
re2 = new RegExp(s_v);
if (re2.test(stem)) {
w = stem;
re2 = /(at|bl|iz)$/;
re3 = new RegExp("([^aeiouylsz])\\1$");
re4 = new RegExp("^" + C + v + "[^aeiouwxy]$");
if (re2.test(w))
w = w + "e";
else if (re3.test(w)) {
re = /.$/;
w = w.replace(re,"");
}
else if (re4.test(w))
w = w + "e";
}
}
// Step 1c
re = /^(.+?)y$/;
if (re.test(w)) {
var fp = re.exec(w);
stem = fp[1];
re = new RegExp(s_v);
if (re.test(stem))
w = stem + "i";
}
// Step 2
re = /^(.+?)(ational|tional|enci|anci|izer|bli|alli|entli|eli|ousli|ization|ation|ator|alism|iveness|fulness|ousness|aliti|iviti|biliti|logi)$/;
if (re.test(w)) {
var fp = re.exec(w);
stem = fp[1];
suffix = fp[2];
re = new RegExp(mgr0);
if (re.test(stem))
w = stem + step2list[suffix];
}
// Step 3
re = /^(.+?)(icate|ative|alize|iciti|ical|ful|ness)$/;
if (re.test(w)) {
var fp = re.exec(w);
stem = fp[1];
suffix = fp[2];
re = new RegExp(mgr0);
if (re.test(stem))
w = stem + step3list[suffix];
}
// Step 4
re = /^(.+?)(al|ance|ence|er|ic|able|ible|ant|ement|ment|ent|ou|ism|ate|iti|ous|ive|ize)$/;
re2 = /^(.+?)(s|t)(ion)$/;
if (re.test(w)) {
var fp = re.exec(w);
stem = fp[1];
re = new RegExp(mgr1);
if (re.test(stem))
w = stem;
}
else if (re2.test(w)) {
var fp = re2.exec(w);
stem = fp[1] + fp[2];
re2 = new RegExp(mgr1);
if (re2.test(stem))
w = stem;
}
// Step 5
re = /^(.+?)e$/;
if (re.test(w)) {
var fp = re.exec(w);
stem = fp[1];
re = new RegExp(mgr1);
re2 = new RegExp(meq1);
re3 = new RegExp("^" + C + v + "[^aeiouwxy]$");
if (re.test(stem) || (re2.test(stem) && !(re3.test(stem))))
w = stem;
}
re = /ll$/;
re2 = new RegExp(mgr1);
if (re.test(w) && re2.test(w)) {
re = /.$/;
w = w.replace(re,"");
}
// and turn initial Y back to y
if (firstch == "y")
w = firstch.toLowerCase() + w.substr(1);
return w;
}
}
var splitChars = (function() {
var result = {};
var singles = [96, 180, 187, 191, 215, 247, 749, 885, 903, 907, 909, 930, 1014, 1648,
1748, 1809, 2416, 2473, 2481, 2526, 2601, 2609, 2612, 2615, 2653, 2702,
2706, 2729, 2737, 2740, 2857, 2865, 2868, 2910, 2928, 2948, 2961, 2971,
2973, 3085, 3089, 3113, 3124, 3213, 3217, 3241, 3252, 3295, 3341, 3345,
3369, 3506, 3516, 3633, 3715, 3721, 3736, 3744, 3748, 3750, 3756, 3761,
3781, 3912, 4239, 4347, 4681, 4695, 4697, 4745, 4785, 4799, 4801, 4823,
4881, 5760, 5901, 5997, 6313, 7405, 8024, 8026, 8028, 8030, 8117, 8125,
8133, 8181, 8468, 8485, 8487, 8489, 8494, 8527, 11311, 11359, 11687, 11695,
11703, 11711, 11719, 11727, 11735, 12448, 12539, 43010, 43014, 43019, 43587,
43696, 43713, 64286, 64297, 64311, 64317, 64319, 64322, 64325, 65141];
var i, j, start, end;
for (i = 0; i < singles.length; i++) {
result[singles[i]] = true;
}
var ranges = [[0, 47], [58, 64], [91, 94], [123, 169], [171, 177], [182, 184], [706, 709],
[722, 735], [741, 747], [751, 879], [888, 889], [894, 901], [1154, 1161],
[1318, 1328], [1367, 1368], [1370, 1376], [1416, 1487], [1515, 1519], [1523, 1568],
[1611, 1631], [1642, 1645], [1750, 1764], [1767, 1773], [1789, 1790], [1792, 1807],
[1840, 1868], [1958, 1968], [1970, 1983], [2027, 2035], [2038, 2041], [2043, 2047],
[2070, 2073], [2075, 2083], [2085, 2087], [2089, 2307], [2362, 2364], [2366, 2383],
[2385, 2391], [2402, 2405], [2419, 2424], [2432, 2436], [2445, 2446], [2449, 2450],
[2483, 2485], [2490, 2492], [2494, 2509], [2511, 2523], [2530, 2533], [2546, 2547],
[2554, 2564], [2571, 2574], [2577, 2578], [2618, 2648], [2655, 2661], [2672, 2673],
[2677, 2692], [2746, 2748], [2750, 2767], [2769, 2783], [2786, 2789], [2800, 2820],
[2829, 2830], [2833, 2834], [2874, 2876], [2878, 2907], [2914, 2917], [2930, 2946],
[2955, 2957], [2966, 2968], [2976, 2978], [2981, 2983], [2987, 2989], [3002, 3023],
[3025, 3045], [3059, 3076], [3130, 3132], [3134, 3159], [3162, 3167], [3170, 3173],
[3184, 3191], [3199, 3204], [3258, 3260], [3262, 3293], [3298, 3301], [3312, 3332],
[3386, 3388], [3390, 3423], [3426, 3429], [3446, 3449], [3456, 3460], [3479, 3481],
[3518, 3519], [3527, 3584], [3636, 3647], [3655, 3663], [3674, 3712], [3717, 3718],
[3723, 3724], [3726, 3731], [3752, 3753], [3764, 3772], [3774, 3775], [3783, 3791],
[3802, 3803], [3806, 3839], [3841, 3871], [3892, 3903], [3949, 3975], [3980, 4095],
[4139, 4158], [4170, 4175], [4182, 4185], [4190, 4192], [4194, 4196], [4199, 4205],
[4209, 4212], [4226, 4237], [4250, 4255], [4294, 4303], [4349, 4351], [4686, 4687],
[4702, 4703], [4750, 4751], [4790, 4791], [4806, 4807], [4886, 4887], [4955, 4968],
[4989, 4991], [5008, 5023], [5109, 5120], [5741, 5742], [5787, 5791], [5867, 5869],
[5873, 5887], [5906, 5919], [5938, 5951], [5970, 5983], [6001, 6015], [6068, 6102],
[6104, 6107], [6109, 6111], [6122, 6127], [6138, 6159], [6170, 6175], [6264, 6271],
[6315, 6319], [6390, 6399], [6429, 6469], [6510, 6511], [6517, 6527], [6572, 6592],
[6600, 6607], [6619, 6655], [6679, 6687], [6741, 6783], [6794, 6799], [6810, 6822],
[6824, 6916], [6964, 6980], [6988, 6991], [7002, 7042], [7073, 7085], [7098, 7167],
[7204, 7231], [7242, 7244], [7294, 7400], [7410, 7423], [7616, 7679], [7958, 7959],
[7966, 7967], [8006, 8007], [8014, 8015], [8062, 8063], [8127, 8129], [8141, 8143],
[8148, 8149], [8156, 8159], [8173, 8177], [8189, 8303], [8306, 8307], [8314, 8318],
[8330, 8335], [8341, 8449], [8451, 8454], [8456, 8457], [8470, 8472], [8478, 8483],
[8506, 8507], [8512, 8516], [8522, 8525], [8586, 9311], [9372, 9449], [9472, 10101],
[10132, 11263], [11493, 11498], [11503, 11516], [11518, 11519], [11558, 11567],
[11622, 11630], [11632, 11647], [11671, 11679], [11743, 11822], [11824, 12292],
[12296, 12320], [12330, 12336], [12342, 12343], [12349, 12352], [12439, 12444],
[12544, 12548], [12590, 12592], [12687, 12689], [12694, 12703], [12728, 12783],
[12800, 12831], [12842, 12880], [12896, 12927], [12938, 12976], [12992, 13311],
[19894, 19967], [40908, 40959], [42125, 42191], [42238, 42239], [42509, 42511],
[42540, 42559], [42592, 42593], [42607, 42622], [42648, 42655], [42736, 42774],
[42784, 42785], [42889, 42890], [42893, 43002], [43043, 43055], [43062, 43071],
[43124, 43137], [43188, 43215], [43226, 43249], [43256, 43258], [43260, 43263],
[43302, 43311], [43335, 43359], [43389, 43395], [43443, 43470], [43482, 43519],
[43561, 43583], [43596, 43599], [43610, 43615], [43639, 43641], [43643, 43647],
[43698, 43700], [43703, 43704], [43710, 43711], [43715, 43738], [43742, 43967],
[44003, 44015], [44026, 44031], [55204, 55215], [55239, 55242], [55292, 55295],
[57344, 63743], [64046, 64047], [64110, 64111], [64218, 64255], [64263, 64274],
[64280, 64284], [64434, 64466], [64830, 64847], [64912, 64913], [64968, 65007],
[65020, 65135], [65277, 65295], [65306, 65312], [65339, 65344], [65371, 65381],
[65471, 65473], [65480, 65481], [65488, 65489], [65496, 65497]];
for (i = 0; i < ranges.length; i++) {
start = ranges[i][0];
end = ranges[i][1];
for (j = start; j <= end; j++) {
result[j] = true;
}
}
return result;
})();
function splitQuery(query) {
var result = [];
var start = -1;
for (var i = 0; i < query.length; i++) {
if (splitChars[query.charCodeAt(i)]) {
if (start !== -1) {
result.push(query.slice(start, i));
start = -1;
}
} else if (start === -1) {
start = i;
}
}
if (start !== -1) {
result.push(query.slice(start));
}
return result;
}

BIN
docs/_build/html/_static/minus.png vendored Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 90 B

BIN
docs/_build/html/_static/plus.png vendored Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 90 B

74
docs/_build/html/_static/pygments.css vendored Normal file
View File

@ -0,0 +1,74 @@
pre { line-height: 125%; }
td.linenos .normal { color: inherit; background-color: transparent; padding-left: 5px; padding-right: 5px; }
span.linenos { color: inherit; background-color: transparent; padding-left: 5px; padding-right: 5px; }
td.linenos .special { color: #000000; background-color: #ffffc0; padding-left: 5px; padding-right: 5px; }
span.linenos.special { color: #000000; background-color: #ffffc0; padding-left: 5px; padding-right: 5px; }
.highlight .hll { background-color: #ffffcc }
.highlight { background: #f8f8f8; }
.highlight .c { color: #408080; font-style: italic } /* Comment */
.highlight .err { border: 1px solid #FF0000 } /* Error */
.highlight .k { color: #008000; font-weight: bold } /* Keyword */
.highlight .o { color: #666666 } /* Operator */
.highlight .ch { color: #408080; font-style: italic } /* Comment.Hashbang */
.highlight .cm { color: #408080; font-style: italic } /* Comment.Multiline */
.highlight .cp { color: #BC7A00 } /* Comment.Preproc */
.highlight .cpf { color: #408080; font-style: italic } /* Comment.PreprocFile */
.highlight .c1 { color: #408080; font-style: italic } /* Comment.Single */
.highlight .cs { color: #408080; font-style: italic } /* Comment.Special */
.highlight .gd { color: #A00000 } /* Generic.Deleted */
.highlight .ge { font-style: italic } /* Generic.Emph */
.highlight .gr { color: #FF0000 } /* Generic.Error */
.highlight .gh { color: #000080; font-weight: bold } /* Generic.Heading */
.highlight .gi { color: #00A000 } /* Generic.Inserted */
.highlight .go { color: #888888 } /* Generic.Output */
.highlight .gp { color: #000080; font-weight: bold } /* Generic.Prompt */
.highlight .gs { font-weight: bold } /* Generic.Strong */
.highlight .gu { color: #800080; font-weight: bold } /* Generic.Subheading */
.highlight .gt { color: #0044DD } /* Generic.Traceback */
.highlight .kc { color: #008000; font-weight: bold } /* Keyword.Constant */
.highlight .kd { color: #008000; font-weight: bold } /* Keyword.Declaration */
.highlight .kn { color: #008000; font-weight: bold } /* Keyword.Namespace */
.highlight .kp { color: #008000 } /* Keyword.Pseudo */
.highlight .kr { color: #008000; font-weight: bold } /* Keyword.Reserved */
.highlight .kt { color: #B00040 } /* Keyword.Type */
.highlight .m { color: #666666 } /* Literal.Number */
.highlight .s { color: #BA2121 } /* Literal.String */
.highlight .na { color: #7D9029 } /* Name.Attribute */
.highlight .nb { color: #008000 } /* Name.Builtin */
.highlight .nc { color: #0000FF; font-weight: bold } /* Name.Class */
.highlight .no { color: #880000 } /* Name.Constant */
.highlight .nd { color: #AA22FF } /* Name.Decorator */
.highlight .ni { color: #999999; font-weight: bold } /* Name.Entity */
.highlight .ne { color: #D2413A; font-weight: bold } /* Name.Exception */
.highlight .nf { color: #0000FF } /* Name.Function */
.highlight .nl { color: #A0A000 } /* Name.Label */
.highlight .nn { color: #0000FF; font-weight: bold } /* Name.Namespace */
.highlight .nt { color: #008000; font-weight: bold } /* Name.Tag */
.highlight .nv { color: #19177C } /* Name.Variable */
.highlight .ow { color: #AA22FF; font-weight: bold } /* Operator.Word */
.highlight .w { color: #bbbbbb } /* Text.Whitespace */
.highlight .mb { color: #666666 } /* Literal.Number.Bin */
.highlight .mf { color: #666666 } /* Literal.Number.Float */
.highlight .mh { color: #666666 } /* Literal.Number.Hex */
.highlight .mi { color: #666666 } /* Literal.Number.Integer */
.highlight .mo { color: #666666 } /* Literal.Number.Oct */
.highlight .sa { color: #BA2121 } /* Literal.String.Affix */
.highlight .sb { color: #BA2121 } /* Literal.String.Backtick */
.highlight .sc { color: #BA2121 } /* Literal.String.Char */
.highlight .dl { color: #BA2121 } /* Literal.String.Delimiter */
.highlight .sd { color: #BA2121; font-style: italic } /* Literal.String.Doc */
.highlight .s2 { color: #BA2121 } /* Literal.String.Double */
.highlight .se { color: #BB6622; font-weight: bold } /* Literal.String.Escape */
.highlight .sh { color: #BA2121 } /* Literal.String.Heredoc */
.highlight .si { color: #BB6688; font-weight: bold } /* Literal.String.Interpol */
.highlight .sx { color: #008000 } /* Literal.String.Other */
.highlight .sr { color: #BB6688 } /* Literal.String.Regex */
.highlight .s1 { color: #BA2121 } /* Literal.String.Single */
.highlight .ss { color: #19177C } /* Literal.String.Symbol */
.highlight .bp { color: #008000 } /* Name.Builtin.Pseudo */
.highlight .fm { color: #0000FF } /* Name.Function.Magic */
.highlight .vc { color: #19177C } /* Name.Variable.Class */
.highlight .vg { color: #19177C } /* Name.Variable.Global */
.highlight .vi { color: #19177C } /* Name.Variable.Instance */
.highlight .vm { color: #19177C } /* Name.Variable.Magic */
.highlight .il { color: #666666 } /* Literal.Number.Integer.Long */

514
docs/_build/html/_static/searchtools.js vendored Normal file
View File

@ -0,0 +1,514 @@
/*
* searchtools.js
* ~~~~~~~~~~~~~~~~
*
* Sphinx JavaScript utilities for the full-text search.
*
* :copyright: Copyright 2007-2021 by the Sphinx team, see AUTHORS.
* :license: BSD, see LICENSE for details.
*
*/
if (!Scorer) {
/**
* Simple result scoring code.
*/
var Scorer = {
// Implement the following function to further tweak the score for each result
// The function takes a result array [filename, title, anchor, descr, score]
// and returns the new score.
/*
score: function(result) {
return result[4];
},
*/
// query matches the full name of an object
objNameMatch: 11,
// or matches in the last dotted part of the object name
objPartialMatch: 6,
// Additive scores depending on the priority of the object
objPrio: {0: 15, // used to be importantResults
1: 5, // used to be objectResults
2: -5}, // used to be unimportantResults
// Used when the priority is not in the mapping.
objPrioDefault: 0,
// query found in title
title: 15,
partialTitle: 7,
// query found in terms
term: 5,
partialTerm: 2
};
}
if (!splitQuery) {
function splitQuery(query) {
return query.split(/\s+/);
}
}
/**
* Search Module
*/
var Search = {
_index : null,
_queued_query : null,
_pulse_status : -1,
htmlToText : function(htmlString) {
var virtualDocument = document.implementation.createHTMLDocument('virtual');
var htmlElement = $(htmlString, virtualDocument);
htmlElement.find('.headerlink').remove();
docContent = htmlElement.find('[role=main]')[0];
if(docContent === undefined) {
console.warn("Content block not found. Sphinx search tries to obtain it " +
"via '[role=main]'. Could you check your theme or template.");
return "";
}
return docContent.textContent || docContent.innerText;
},
init : function() {
var params = $.getQueryParameters();
if (params.q) {
var query = params.q[0];
$('input[name="q"]')[0].value = query;
this.performSearch(query);
}
},
loadIndex : function(url) {
$.ajax({type: "GET", url: url, data: null,
dataType: "script", cache: true,
complete: function(jqxhr, textstatus) {
if (textstatus != "success") {
document.getElementById("searchindexloader").src = url;
}
}});
},
setIndex : function(index) {
var q;
this._index = index;
if ((q = this._queued_query) !== null) {
this._queued_query = null;
Search.query(q);
}
},
hasIndex : function() {
return this._index !== null;
},
deferQuery : function(query) {
this._queued_query = query;
},
stopPulse : function() {
this._pulse_status = 0;
},
startPulse : function() {
if (this._pulse_status >= 0)
return;
function pulse() {
var i;
Search._pulse_status = (Search._pulse_status + 1) % 4;
var dotString = '';
for (i = 0; i < Search._pulse_status; i++)
dotString += '.';
Search.dots.text(dotString);
if (Search._pulse_status > -1)
window.setTimeout(pulse, 500);
}
pulse();
},
/**
* perform a search for something (or wait until index is loaded)
*/
performSearch : function(query) {
// create the required interface elements
this.out = $('#search-results');
this.title = $('<h2>' + _('Searching') + '</h2>').appendTo(this.out);
this.dots = $('<span></span>').appendTo(this.title);
this.status = $('<p class="search-summary">&nbsp;</p>').appendTo(this.out);
this.output = $('<ul class="search"/>').appendTo(this.out);
$('#search-progress').text(_('Preparing search...'));
this.startPulse();
// index already loaded, the browser was quick!
if (this.hasIndex())
this.query(query);
else
this.deferQuery(query);
},
/**
* execute search (requires search index to be loaded)
*/
query : function(query) {
var i;
// stem the searchterms and add them to the correct list
var stemmer = new Stemmer();
var searchterms = [];
var excluded = [];
var hlterms = [];
var tmp = splitQuery(query);
var objectterms = [];
for (i = 0; i < tmp.length; i++) {
if (tmp[i] !== "") {
objectterms.push(tmp[i].toLowerCase());
}
if ($u.indexOf(stopwords, tmp[i].toLowerCase()) != -1 || tmp[i] === "") {
// skip this "word"
continue;
}
// stem the word
var word = stemmer.stemWord(tmp[i].toLowerCase());
// prevent stemmer from cutting word smaller than two chars
if(word.length < 3 && tmp[i].length >= 3) {
word = tmp[i];
}
var toAppend;
// select the correct list
if (word[0] == '-') {
toAppend = excluded;
word = word.substr(1);
}
else {
toAppend = searchterms;
hlterms.push(tmp[i].toLowerCase());
}
// only add if not already in the list
if (!$u.contains(toAppend, word))
toAppend.push(word);
}
var highlightstring = '?highlight=' + $.urlencode(hlterms.join(" "));
// console.debug('SEARCH: searching for:');
// console.info('required: ', searchterms);
// console.info('excluded: ', excluded);
// prepare search
var terms = this._index.terms;
var titleterms = this._index.titleterms;
// array of [filename, title, anchor, descr, score]
var results = [];
$('#search-progress').empty();
// lookup as object
for (i = 0; i < objectterms.length; i++) {
var others = [].concat(objectterms.slice(0, i),
objectterms.slice(i+1, objectterms.length));
results = results.concat(this.performObjectSearch(objectterms[i], others));
}
// lookup as search terms in fulltext
results = results.concat(this.performTermsSearch(searchterms, excluded, terms, titleterms));
// let the scorer override scores with a custom scoring function
if (Scorer.score) {
for (i = 0; i < results.length; i++)
results[i][4] = Scorer.score(results[i]);
}
// now sort the results by score (in opposite order of appearance, since the
// display function below uses pop() to retrieve items) and then
// alphabetically
results.sort(function(a, b) {
var left = a[4];
var right = b[4];
if (left > right) {
return 1;
} else if (left < right) {
return -1;
} else {
// same score: sort alphabetically
left = a[1].toLowerCase();
right = b[1].toLowerCase();
return (left > right) ? -1 : ((left < right) ? 1 : 0);
}
});
// for debugging
//Search.lastresults = results.slice(); // a copy
//console.info('search results:', Search.lastresults);
// print the results
var resultCount = results.length;
function displayNextItem() {
// results left, load the summary and display it
if (results.length) {
var item = results.pop();
var listItem = $('<li style="display:none"></li>');
var requestUrl = "";
var linkUrl = "";
if (DOCUMENTATION_OPTIONS.BUILDER === 'dirhtml') {
// dirhtml builder
var dirname = item[0] + '/';
if (dirname.match(/\/index\/$/)) {
dirname = dirname.substring(0, dirname.length-6);
} else if (dirname == 'index/') {
dirname = '';
}
requestUrl = DOCUMENTATION_OPTIONS.URL_ROOT + dirname;
linkUrl = requestUrl;
} else {
// normal html builders
requestUrl = DOCUMENTATION_OPTIONS.URL_ROOT + item[0] + DOCUMENTATION_OPTIONS.FILE_SUFFIX;
linkUrl = item[0] + DOCUMENTATION_OPTIONS.LINK_SUFFIX;
}
listItem.append($('<a/>').attr('href',
linkUrl +
highlightstring + item[2]).html(item[1]));
if (item[3]) {
listItem.append($('<span> (' + item[3] + ')</span>'));
Search.output.append(listItem);
listItem.slideDown(5, function() {
displayNextItem();
});
} else if (DOCUMENTATION_OPTIONS.HAS_SOURCE) {
$.ajax({url: requestUrl,
dataType: "text",
complete: function(jqxhr, textstatus) {
var data = jqxhr.responseText;
if (data !== '' && data !== undefined) {
listItem.append(Search.makeSearchSummary(data, searchterms, hlterms));
}
Search.output.append(listItem);
listItem.slideDown(5, function() {
displayNextItem();
});
}});
} else {
// no source available, just display title
Search.output.append(listItem);
listItem.slideDown(5, function() {
displayNextItem();
});
}
}
// search finished, update title and status message
else {
Search.stopPulse();
Search.title.text(_('Search Results'));
if (!resultCount)
Search.status.text(_('Your search did not match any documents. Please make sure that all words are spelled correctly and that you\'ve selected enough categories.'));
else
Search.status.text(_('Search finished, found %s page(s) matching the search query.').replace('%s', resultCount));
Search.status.fadeIn(500);
}
}
displayNextItem();
},
/**
* search for object names
*/
performObjectSearch : function(object, otherterms) {
var filenames = this._index.filenames;
var docnames = this._index.docnames;
var objects = this._index.objects;
var objnames = this._index.objnames;
var titles = this._index.titles;
var i;
var results = [];
for (var prefix in objects) {
for (var name in objects[prefix]) {
var fullname = (prefix ? prefix + '.' : '') + name;
var fullnameLower = fullname.toLowerCase()
if (fullnameLower.indexOf(object) > -1) {
var score = 0;
var parts = fullnameLower.split('.');
// check for different match types: exact matches of full name or
// "last name" (i.e. last dotted part)
if (fullnameLower == object || parts[parts.length - 1] == object) {
score += Scorer.objNameMatch;
// matches in last name
} else if (parts[parts.length - 1].indexOf(object) > -1) {
score += Scorer.objPartialMatch;
}
var match = objects[prefix][name];
var objname = objnames[match[1]][2];
var title = titles[match[0]];
// If more than one term searched for, we require other words to be
// found in the name/title/description
if (otherterms.length > 0) {
var haystack = (prefix + ' ' + name + ' ' +
objname + ' ' + title).toLowerCase();
var allfound = true;
for (i = 0; i < otherterms.length; i++) {
if (haystack.indexOf(otherterms[i]) == -1) {
allfound = false;
break;
}
}
if (!allfound) {
continue;
}
}
var descr = objname + _(', in ') + title;
var anchor = match[3];
if (anchor === '')
anchor = fullname;
else if (anchor == '-')
anchor = objnames[match[1]][1] + '-' + fullname;
// add custom score for some objects according to scorer
if (Scorer.objPrio.hasOwnProperty(match[2])) {
score += Scorer.objPrio[match[2]];
} else {
score += Scorer.objPrioDefault;
}
results.push([docnames[match[0]], fullname, '#'+anchor, descr, score, filenames[match[0]]]);
}
}
}
return results;
},
/**
* search for full-text terms in the index
*/
performTermsSearch : function(searchterms, excluded, terms, titleterms) {
var docnames = this._index.docnames;
var filenames = this._index.filenames;
var titles = this._index.titles;
var i, j, file;
var fileMap = {};
var scoreMap = {};
var results = [];
// perform the search on the required terms
for (i = 0; i < searchterms.length; i++) {
var word = searchterms[i];
var files = [];
var _o = [
{files: terms[word], score: Scorer.term},
{files: titleterms[word], score: Scorer.title}
];
// add support for partial matches
if (word.length > 2) {
for (var w in terms) {
if (w.match(word) && !terms[word]) {
_o.push({files: terms[w], score: Scorer.partialTerm})
}
}
for (var w in titleterms) {
if (w.match(word) && !titleterms[word]) {
_o.push({files: titleterms[w], score: Scorer.partialTitle})
}
}
}
// no match but word was a required one
if ($u.every(_o, function(o){return o.files === undefined;})) {
break;
}
// found search word in contents
$u.each(_o, function(o) {
var _files = o.files;
if (_files === undefined)
return
if (_files.length === undefined)
_files = [_files];
files = files.concat(_files);
// set score for the word in each file to Scorer.term
for (j = 0; j < _files.length; j++) {
file = _files[j];
if (!(file in scoreMap))
scoreMap[file] = {};
scoreMap[file][word] = o.score;
}
});
// create the mapping
for (j = 0; j < files.length; j++) {
file = files[j];
if (file in fileMap && fileMap[file].indexOf(word) === -1)
fileMap[file].push(word);
else
fileMap[file] = [word];
}
}
// now check if the files don't contain excluded terms
for (file in fileMap) {
var valid = true;
// check if all requirements are matched
var filteredTermCount = // as search terms with length < 3 are discarded: ignore
searchterms.filter(function(term){return term.length > 2}).length
if (
fileMap[file].length != searchterms.length &&
fileMap[file].length != filteredTermCount
) continue;
// ensure that none of the excluded terms is in the search result
for (i = 0; i < excluded.length; i++) {
if (terms[excluded[i]] == file ||
titleterms[excluded[i]] == file ||
$u.contains(terms[excluded[i]] || [], file) ||
$u.contains(titleterms[excluded[i]] || [], file)) {
valid = false;
break;
}
}
// if we have still a valid result we can add it to the result list
if (valid) {
// select one (max) score for the file.
// for better ranking, we should calculate ranking by using words statistics like basic tf-idf...
var score = $u.max($u.map(fileMap[file], function(w){return scoreMap[file][w]}));
results.push([docnames[file], titles[file], '', null, score, filenames[file]]);
}
}
return results;
},
/**
* helper function to return a node containing the
* search summary for a given text. keywords is a list
* of stemmed words, hlwords is the list of normal, unstemmed
* words. the first one is used to find the occurrence, the
* latter for highlighting it.
*/
makeSearchSummary : function(htmlText, keywords, hlwords) {
var text = Search.htmlToText(htmlText);
var textLower = text.toLowerCase();
var start = 0;
$.each(keywords, function() {
var i = textLower.indexOf(this.toLowerCase());
if (i > -1)
start = i;
});
start = Math.max(start - 120, 0);
var excerpt = ((start > 0) ? '...' : '') +
$.trim(text.substr(start, 240)) +
((start + 240 - text.length) ? '...' : '');
var rv = $('<div class="context"></div>').text(excerpt);
$.each(hlwords, function() {
rv = rv.highlightText(this, 'highlighted');
});
return rv;
}
};
$(document).ready(function() {
Search.init();
});

999
docs/_build/html/_static/underscore-1.3.1.js vendored Normal file
View File

@ -0,0 +1,999 @@
// Underscore.js 1.3.1
// (c) 2009-2012 Jeremy Ashkenas, DocumentCloud Inc.
// Underscore is freely distributable under the MIT license.
// Portions of Underscore are inspired or borrowed from Prototype,
// Oliver Steele's Functional, and John Resig's Micro-Templating.
// For all details and documentation:
// http://documentcloud.github.com/underscore
(function() {
// Baseline setup
// --------------
// Establish the root object, `window` in the browser, or `global` on the server.
var root = this;
// Save the previous value of the `_` variable.
var previousUnderscore = root._;
// Establish the object that gets returned to break out of a loop iteration.
var breaker = {};
// Save bytes in the minified (but not gzipped) version:
var ArrayProto = Array.prototype, ObjProto = Object.prototype, FuncProto = Function.prototype;
// Create quick reference variables for speed access to core prototypes.
var slice = ArrayProto.slice,
unshift = ArrayProto.unshift,
toString = ObjProto.toString,
hasOwnProperty = ObjProto.hasOwnProperty;
// All **ECMAScript 5** native function implementations that we hope to use
// are declared here.
var
nativeForEach = ArrayProto.forEach,
nativeMap = ArrayProto.map,
nativeReduce = ArrayProto.reduce,
nativeReduceRight = ArrayProto.reduceRight,
nativeFilter = ArrayProto.filter,
nativeEvery = ArrayProto.every,
nativeSome = ArrayProto.some,
nativeIndexOf = ArrayProto.indexOf,
nativeLastIndexOf = ArrayProto.lastIndexOf,
nativeIsArray = Array.isArray,
nativeKeys = Object.keys,
nativeBind = FuncProto.bind;
// Create a safe reference to the Underscore object for use below.
var _ = function(obj) { return new wrapper(obj); };
// Export the Underscore object for **Node.js**, with
// backwards-compatibility for the old `require()` API. If we're in
// the browser, add `_` as a global object via a string identifier,
// for Closure Compiler "advanced" mode.
if (typeof exports !== 'undefined') {
if (typeof module !== 'undefined' && module.exports) {
exports = module.exports = _;
}
exports._ = _;
} else {
root['_'] = _;
}
// Current version.
_.VERSION = '1.3.1';
// Collection Functions
// --------------------
// The cornerstone, an `each` implementation, aka `forEach`.
// Handles objects with the built-in `forEach`, arrays, and raw objects.
// Delegates to **ECMAScript 5**'s native `forEach` if available.
var each = _.each = _.forEach = function(obj, iterator, context) {
if (obj == null) return;
if (nativeForEach && obj.forEach === nativeForEach) {
obj.forEach(iterator, context);
} else if (obj.length === +obj.length) {
for (var i = 0, l = obj.length; i < l; i++) {
if (i in obj && iterator.call(context, obj[i], i, obj) === breaker) return;
}
} else {
for (var key in obj) {
if (_.has(obj, key)) {
if (iterator.call(context, obj[key], key, obj) === breaker) return;
}
}
}
};
// Return the results of applying the iterator to each element.
// Delegates to **ECMAScript 5**'s native `map` if available.
_.map = _.collect = function(obj, iterator, context) {
var results = [];
if (obj == null) return results;
if (nativeMap && obj.map === nativeMap) return obj.map(iterator, context);
each(obj, function(value, index, list) {
results[results.length] = iterator.call(context, value, index, list);
});
if (obj.length === +obj.length) results.length = obj.length;
return results;
};
// **Reduce** builds up a single result from a list of values, aka `inject`,
// or `foldl`. Delegates to **ECMAScript 5**'s native `reduce` if available.
_.reduce = _.foldl = _.inject = function(obj, iterator, memo, context) {
var initial = arguments.length > 2;
if (obj == null) obj = [];
if (nativeReduce && obj.reduce === nativeReduce) {
if (context) iterator = _.bind(iterator, context);
return initial ? obj.reduce(iterator, memo) : obj.reduce(iterator);
}
each(obj, function(value, index, list) {
if (!initial) {
memo = value;
initial = true;
} else {
memo = iterator.call(context, memo, value, index, list);
}
});
if (!initial) throw new TypeError('Reduce of empty array with no initial value');
return memo;
};
// The right-associative version of reduce, also known as `foldr`.
// Delegates to **ECMAScript 5**'s native `reduceRight` if available.
_.reduceRight = _.foldr = function(obj, iterator, memo, context) {
var initial = arguments.length > 2;
if (obj == null) obj = [];
if (nativeReduceRight && obj.reduceRight === nativeReduceRight) {
if (context) iterator = _.bind(iterator, context);
return initial ? obj.reduceRight(iterator, memo) : obj.reduceRight(iterator);
}
var reversed = _.toArray(obj).reverse();
if (context && !initial) iterator = _.bind(iterator, context);
return initial ? _.reduce(reversed, iterator, memo, context) : _.reduce(reversed, iterator);
};
// Return the first value which passes a truth test. Aliased as `detect`.
_.find = _.detect = function(obj, iterator, context) {
var result;
any(obj, function(value, index, list) {
if (iterator.call(context, value, index, list)) {
result = value;
return true;
}
});
return result;
};
// Return all the elements that pass a truth test.
// Delegates to **ECMAScript 5**'s native `filter` if available.
// Aliased as `select`.
_.filter = _.select = function(obj, iterator, context) {
var results = [];
if (obj == null) return results;
if (nativeFilter && obj.filter === nativeFilter) return obj.filter(iterator, context);
each(obj, function(value, index, list) {
if (iterator.call(context, value, index, list)) results[results.length] = value;
});
return results;
};
// Return all the elements for which a truth test fails.
_.reject = function(obj, iterator, context) {
var results = [];
if (obj == null) return results;
each(obj, function(value, index, list) {
if (!iterator.call(context, value, index, list)) results[results.length] = value;
});
return results;
};
// Determine whether all of the elements match a truth test.
// Delegates to **ECMAScript 5**'s native `every` if available.
// Aliased as `all`.
_.every = _.all = function(obj, iterator, context) {
var result = true;
if (obj == null) return result;
if (nativeEvery && obj.every === nativeEvery) return obj.every(iterator, context);
each(obj, function(value, index, list) {
if (!(result = result && iterator.call(context, value, index, list))) return breaker;
});
return result;
};
// Determine if at least one element in the object matches a truth test.
// Delegates to **ECMAScript 5**'s native `some` if available.
// Aliased as `any`.
var any = _.some = _.any = function(obj, iterator, context) {
iterator || (iterator = _.identity);
var result = false;
if (obj == null) return result;
if (nativeSome && obj.some === nativeSome) return obj.some(iterator, context);
each(obj, function(value, index, list) {
if (result || (result = iterator.call(context, value, index, list))) return breaker;
});
return !!result;
};
// Determine if a given value is included in the array or object using `===`.
// Aliased as `contains`.
_.include = _.contains = function(obj, target) {
var found = false;
if (obj == null) return found;
if (nativeIndexOf && obj.indexOf === nativeIndexOf) return obj.indexOf(target) != -1;
found = any(obj, function(value) {
return value === target;
});
return found;
};
// Invoke a method (with arguments) on every item in a collection.
_.invoke = function(obj, method) {
var args = slice.call(arguments, 2);
return _.map(obj, function(value) {
return (_.isFunction(method) ? method || value : value[method]).apply(value, args);
});
};
// Convenience version of a common use case of `map`: fetching a property.
_.pluck = function(obj, key) {
return _.map(obj, function(value){ return value[key]; });
};
// Return the maximum element or (element-based computation).
_.max = function(obj, iterator, context) {
if (!iterator && _.isArray(obj)) return Math.max.apply(Math, obj);
if (!iterator && _.isEmpty(obj)) return -Infinity;
var result = {computed : -Infinity};
each(obj, function(value, index, list) {
var computed = iterator ? iterator.call(context, value, index, list) : value;
computed >= result.computed && (result = {value : value, computed : computed});
});
return result.value;
};
// Return the minimum element (or element-based computation).
_.min = function(obj, iterator, context) {
if (!iterator && _.isArray(obj)) return Math.min.apply(Math, obj);
if (!iterator && _.isEmpty(obj)) return Infinity;
var result = {computed : Infinity};
each(obj, function(value, index, list) {
var computed = iterator ? iterator.call(context, value, index, list) : value;
computed < result.computed && (result = {value : value, computed : computed});
});
return result.value;
};
// Shuffle an array.
_.shuffle = function(obj) {
var shuffled = [], rand;
each(obj, function(value, index, list) {
if (index == 0) {
shuffled[0] = value;
} else {
rand = Math.floor(Math.random() * (index + 1));
shuffled[index] = shuffled[rand];
shuffled[rand] = value;
}
});
return shuffled;
};
// Sort the object's values by a criterion produced by an iterator.
_.sortBy = function(obj, iterator, context) {
return _.pluck(_.map(obj, function(value, index, list) {
return {
value : value,
criteria : iterator.call(context, value, index, list)
};
}).sort(function(left, right) {
var a = left.criteria, b = right.criteria;
return a < b ? -1 : a > b ? 1 : 0;
}), 'value');
};
// Groups the object's values by a criterion. Pass either a string attribute
// to group by, or a function that returns the criterion.
_.groupBy = function(obj, val) {
var result = {};
var iterator = _.isFunction(val) ? val : function(obj) { return obj[val]; };
each(obj, function(value, index) {
var key = iterator(value, index);
(result[key] || (result[key] = [])).push(value);
});
return result;
};
// Use a comparator function to figure out at what index an object should
// be inserted so as to maintain order. Uses binary search.
_.sortedIndex = function(array, obj, iterator) {
iterator || (iterator = _.identity);
var low = 0, high = array.length;
while (low < high) {
var mid = (low + high) >> 1;
iterator(array[mid]) < iterator(obj) ? low = mid + 1 : high = mid;
}
return low;
};
// Safely convert anything iterable into a real, live array.
_.toArray = function(iterable) {
if (!iterable) return [];
if (iterable.toArray) return iterable.toArray();
if (_.isArray(iterable)) return slice.call(iterable);
if (_.isArguments(iterable)) return slice.call(iterable);
return _.values(iterable);
};
// Return the number of elements in an object.
_.size = function(obj) {
return _.toArray(obj).length;
};
// Array Functions
// ---------------
// Get the first element of an array. Passing **n** will return the first N
// values in the array. Aliased as `head`. The **guard** check allows it to work
// with `_.map`.
_.first = _.head = function(array, n, guard) {
return (n != null) && !guard ? slice.call(array, 0, n) : array[0];
};
// Returns everything but the last entry of the array. Especcialy useful on
// the arguments object. Passing **n** will return all the values in
// the array, excluding the last N. The **guard** check allows it to work with
// `_.map`.
_.initial = function(array, n, guard) {
return slice.call(array, 0, array.length - ((n == null) || guard ? 1 : n));
};
// Get the last element of an array. Passing **n** will return the last N
// values in the array. The **guard** check allows it to work with `_.map`.
_.last = function(array, n, guard) {
if ((n != null) && !guard) {
return slice.call(array, Math.max(array.length - n, 0));
} else {
return array[array.length - 1];
}
};
// Returns everything but the first entry of the array. Aliased as `tail`.
// Especially useful on the arguments object. Passing an **index** will return
// the rest of the values in the array from that index onward. The **guard**
// check allows it to work with `_.map`.
_.rest = _.tail = function(array, index, guard) {
return slice.call(array, (index == null) || guard ? 1 : index);
};
// Trim out all falsy values from an array.
_.compact = function(array) {
return _.filter(array, function(value){ return !!value; });
};
// Return a completely flattened version of an array.
_.flatten = function(array, shallow) {
return _.reduce(array, function(memo, value) {
if (_.isArray(value)) return memo.concat(shallow ? value : _.flatten(value));
memo[memo.length] = value;
return memo;
}, []);
};
// Return a version of the array that does not contain the specified value(s).
_.without = function(array) {
return _.difference(array, slice.call(arguments, 1));
};
// Produce a duplicate-free version of the array. If the array has already
// been sorted, you have the option of using a faster algorithm.
// Aliased as `unique`.
_.uniq = _.unique = function(array, isSorted, iterator) {
var initial = iterator ? _.map(array, iterator) : array;
var result = [];
_.reduce(initial, function(memo, el, i) {
if (0 == i || (isSorted === true ? _.last(memo) != el : !_.include(memo, el))) {
memo[memo.length] = el;
result[result.length] = array[i];
}
return memo;
}, []);
return result;
};
// Produce an array that contains the union: each distinct element from all of
// the passed-in arrays.
_.union = function() {
return _.uniq(_.flatten(arguments, true));
};
// Produce an array that contains every item shared between all the
// passed-in arrays. (Aliased as "intersect" for back-compat.)
_.intersection = _.intersect = function(array) {
var rest = slice.call(arguments, 1);
return _.filter(_.uniq(array), function(item) {
return _.every(rest, function(other) {
return _.indexOf(other, item) >= 0;
});
});
};
// Take the difference between one array and a number of other arrays.
// Only the elements present in just the first array will remain.
_.difference = function(array) {
var rest = _.flatten(slice.call(arguments, 1));
return _.filter(array, function(value){ return !_.include(rest, value); });
};
// Zip together multiple lists into a single array -- elements that share
// an index go together.
_.zip = function() {
var args = slice.call(arguments);
var length = _.max(_.pluck(args, 'length'));
var results = new Array(length);
for (var i = 0; i < length; i++) results[i] = _.pluck(args, "" + i);
return results;
};
// If the browser doesn't supply us with indexOf (I'm looking at you, **MSIE**),
// we need this function. Return the position of the first occurrence of an
// item in an array, or -1 if the item is not included in the array.
// Delegates to **ECMAScript 5**'s native `indexOf` if available.
// If the array is large and already in sort order, pass `true`
// for **isSorted** to use binary search.
_.indexOf = function(array, item, isSorted) {
if (array == null) return -1;
var i, l;
if (isSorted) {
i = _.sortedIndex(array, item);
return array[i] === item ? i : -1;
}
if (nativeIndexOf && array.indexOf === nativeIndexOf) return array.indexOf(item);
for (i = 0, l = array.length; i < l; i++) if (i in array && array[i] === item) return i;
return -1;
};
// Delegates to **ECMAScript 5**'s native `lastIndexOf` if available.
_.lastIndexOf = function(array, item) {
if (array == null) return -1;
if (nativeLastIndexOf && array.lastIndexOf === nativeLastIndexOf) return array.lastIndexOf(item);
var i = array.length;
while (i--) if (i in array && array[i] === item) return i;
return -1;
};
// Generate an integer Array containing an arithmetic progression. A port of
// the native Python `range()` function. See
// [the Python documentation](http://docs.python.org/library/functions.html#range).
_.range = function(start, stop, step) {
if (arguments.length <= 1) {
stop = start || 0;
start = 0;
}
step = arguments[2] || 1;
var len = Math.max(Math.ceil((stop - start) / step), 0);
var idx = 0;
var range = new Array(len);
while(idx < len) {
range[idx++] = start;
start += step;
}
return range;
};
// Function (ahem) Functions
// ------------------
// Reusable constructor function for prototype setting.
var ctor = function(){};
// Create a function bound to a given object (assigning `this`, and arguments,
// optionally). Binding with arguments is also known as `curry`.
// Delegates to **ECMAScript 5**'s native `Function.bind` if available.
// We check for `func.bind` first, to fail fast when `func` is undefined.
_.bind = function bind(func, context) {
var bound, args;
if (func.bind === nativeBind && nativeBind) return nativeBind.apply(func, slice.call(arguments, 1));
if (!_.isFunction(func)) throw new TypeError;
args = slice.call(arguments, 2);
return bound = function() {
if (!(this instanceof bound)) return func.apply(context, args.concat(slice.call(arguments)));
ctor.prototype = func.prototype;
var self = new ctor;
var result = func.apply(self, args.concat(slice.call(arguments)));
if (Object(result) === result) return result;
return self;
};
};
// Bind all of an object's methods to that object. Useful for ensuring that
// all callbacks defined on an object belong to it.
_.bindAll = function(obj) {
var funcs = slice.call(arguments, 1);
if (funcs.length == 0) funcs = _.functions(obj);
each(funcs, function(f) { obj[f] = _.bind(obj[f], obj); });
return obj;
};
// Memoize an expensive function by storing its results.
_.memoize = function(func, hasher) {
var memo = {};
hasher || (hasher = _.identity);
return function() {
var key = hasher.apply(this, arguments);
return _.has(memo, key) ? memo[key] : (memo[key] = func.apply(this, arguments));
};
};
// Delays a function for the given number of milliseconds, and then calls
// it with the arguments supplied.
_.delay = function(func, wait) {
var args = slice.call(arguments, 2);
return setTimeout(function(){ return func.apply(func, args); }, wait);
};
// Defers a function, scheduling it to run after the current call stack has
// cleared.
_.defer = function(func) {
return _.delay.apply(_, [func, 1].concat(slice.call(arguments, 1)));
};
// Returns a function, that, when invoked, will only be triggered at most once
// during a given window of time.
_.throttle = function(func, wait) {
var context, args, timeout, throttling, more;
var whenDone = _.debounce(function(){ more = throttling = false; }, wait);
return function() {
context = this; args = arguments;
var later = function() {
timeout = null;
if (more) func.apply(context, args);
whenDone();
};
if (!timeout) timeout = setTimeout(later, wait);
if (throttling) {
more = true;
} else {
func.apply(context, args);
}
whenDone();
throttling = true;
};
};
// Returns a function, that, as long as it continues to be invoked, will not
// be triggered. The function will be called after it stops being called for
// N milliseconds.
_.debounce = function(func, wait) {
var timeout;
return function() {
var context = this, args = arguments;
var later = function() {
timeout = null;
func.apply(context, args);
};
clearTimeout(timeout);
timeout = setTimeout(later, wait);
};
};
// Returns a function that will be executed at most one time, no matter how
// often you call it. Useful for lazy initialization.
_.once = function(func) {
var ran = false, memo;
return function() {
if (ran) return memo;
ran = true;
return memo = func.apply(this, arguments);
};
};
// Returns the first function passed as an argument to the second,
// allowing you to adjust arguments, run code before and after, and
// conditionally execute the original function.
_.wrap = function(func, wrapper) {
return function() {
var args = [func].concat(slice.call(arguments, 0));
return wrapper.apply(this, args);
};
};
// Returns a function that is the composition of a list of functions, each
// consuming the return value of the function that follows.
_.compose = function() {
var funcs = arguments;
return function() {
var args = arguments;
for (var i = funcs.length - 1; i >= 0; i--) {
args = [funcs[i].apply(this, args)];
}
return args[0];
};
};
// Returns a function that will only be executed after being called N times.
_.after = function(times, func) {
if (times <= 0) return func();
return function() {
if (--times < 1) { return func.apply(this, arguments); }
};
};
// Object Functions
// ----------------
// Retrieve the names of an object's properties.
// Delegates to **ECMAScript 5**'s native `Object.keys`
_.keys = nativeKeys || function(obj) {
if (obj !== Object(obj)) throw new TypeError('Invalid object');
var keys = [];
for (var key in obj) if (_.has(obj, key)) keys[keys.length] = key;
return keys;
};
// Retrieve the values of an object's properties.
_.values = function(obj) {
return _.map(obj, _.identity);
};
// Return a sorted list of the function names available on the object.
// Aliased as `methods`
_.functions = _.methods = function(obj) {
var names = [];
for (var key in obj) {
if (_.isFunction(obj[key])) names.push(key);
}
return names.sort();
};
// Extend a given object with all the properties in passed-in object(s).
_.extend = function(obj) {
each(slice.call(arguments, 1), function(source) {
for (var prop in source) {
obj[prop] = source[prop];
}
});
return obj;
};
// Fill in a given object with default properties.
_.defaults = function(obj) {
each(slice.call(arguments, 1), function(source) {
for (var prop in source) {
if (obj[prop] == null) obj[prop] = source[prop];
}
});
return obj;
};
// Create a (shallow-cloned) duplicate of an object.
_.clone = function(obj) {
if (!_.isObject(obj)) return obj;
return _.isArray(obj) ? obj.slice() : _.extend({}, obj);
};
// Invokes interceptor with the obj, and then returns obj.
// The primary purpose of this method is to "tap into" a method chain, in
// order to perform operations on intermediate results within the chain.
_.tap = function(obj, interceptor) {
interceptor(obj);
return obj;
};
// Internal recursive comparison function.
function eq(a, b, stack) {
// Identical objects are equal. `0 === -0`, but they aren't identical.
// See the Harmony `egal` proposal: http://wiki.ecmascript.org/doku.php?id=harmony:egal.
if (a === b) return a !== 0 || 1 / a == 1 / b;
// A strict comparison is necessary because `null == undefined`.
if (a == null || b == null) return a === b;
// Unwrap any wrapped objects.
if (a._chain) a = a._wrapped;
if (b._chain) b = b._wrapped;
// Invoke a custom `isEqual` method if one is provided.
if (a.isEqual && _.isFunction(a.isEqual)) return a.isEqual(b);
if (b.isEqual && _.isFunction(b.isEqual)) return b.isEqual(a);
// Compare `[[Class]]` names.
var className = toString.call(a);
if (className != toString.call(b)) return false;
switch (className) {
// Strings, numbers, dates, and booleans are compared by value.
case '[object String]':
// Primitives and their corresponding object wrappers are equivalent; thus, `"5"` is
// equivalent to `new String("5")`.
return a == String(b);
case '[object Number]':
// `NaN`s are equivalent, but non-reflexive. An `egal` comparison is performed for
// other numeric values.
return a != +a ? b != +b : (a == 0 ? 1 / a == 1 / b : a == +b);
case '[object Date]':
case '[object Boolean]':
// Coerce dates and booleans to numeric primitive values. Dates are compared by their
// millisecond representations. Note that invalid dates with millisecond representations
// of `NaN` are not equivalent.
return +a == +b;
// RegExps are compared by their source patterns and flags.
case '[object RegExp]':
return a.source == b.source &&
a.global == b.global &&
a.multiline == b.multiline &&
a.ignoreCase == b.ignoreCase;
}
if (typeof a != 'object' || typeof b != 'object') return false;
// Assume equality for cyclic structures. The algorithm for detecting cyclic
// structures is adapted from ES 5.1 section 15.12.3, abstract operation `JO`.
var length = stack.length;
while (length--) {
// Linear search. Performance is inversely proportional to the number of
// unique nested structures.
if (stack[length] == a) return true;
}
// Add the first object to the stack of traversed objects.
stack.push(a);
var size = 0, result = true;
// Recursively compare objects and arrays.
if (className == '[object Array]') {
// Compare array lengths to determine if a deep comparison is necessary.
size = a.length;
result = size == b.length;
if (result) {
// Deep compare the contents, ignoring non-numeric properties.
while (size--) {
// Ensure commutative equality for sparse arrays.
if (!(result = size in a == size in b && eq(a[size], b[size], stack))) break;
}
}
} else {
// Objects with different constructors are not equivalent.
if ('constructor' in a != 'constructor' in b || a.constructor != b.constructor) return false;
// Deep compare objects.
for (var key in a) {
if (_.has(a, key)) {
// Count the expected number of properties.
size++;
// Deep compare each member.
if (!(result = _.has(b, key) && eq(a[key], b[key], stack))) break;
}
}
// Ensure that both objects contain the same number of properties.
if (result) {
for (key in b) {
if (_.has(b, key) && !(size--)) break;
}
result = !size;
}
}
// Remove the first object from the stack of traversed objects.
stack.pop();
return result;
}
// Perform a deep comparison to check if two objects are equal.
_.isEqual = function(a, b) {
return eq(a, b, []);
};
// Is a given array, string, or object empty?
// An "empty" object has no enumerable own-properties.
_.isEmpty = function(obj) {
if (_.isArray(obj) || _.isString(obj)) return obj.length === 0;
for (var key in obj) if (_.has(obj, key)) return false;
return true;
};
// Is a given value a DOM element?
_.isElement = function(obj) {
return !!(obj && obj.nodeType == 1);
};
// Is a given value an array?
// Delegates to ECMA5's native Array.isArray
_.isArray = nativeIsArray || function(obj) {
return toString.call(obj) == '[object Array]';
};
// Is a given variable an object?
_.isObject = function(obj) {
return obj === Object(obj);
};
// Is a given variable an arguments object?
_.isArguments = function(obj) {
return toString.call(obj) == '[object Arguments]';
};
if (!_.isArguments(arguments)) {
_.isArguments = function(obj) {
return !!(obj && _.has(obj, 'callee'));
};
}
// Is a given value a function?
_.isFunction = function(obj) {
return toString.call(obj) == '[object Function]';
};
// Is a given value a string?
_.isString = function(obj) {
return toString.call(obj) == '[object String]';
};
// Is a given value a number?
_.isNumber = function(obj) {
return toString.call(obj) == '[object Number]';
};
// Is the given value `NaN`?
_.isNaN = function(obj) {
// `NaN` is the only value for which `===` is not reflexive.
return obj !== obj;
};
// Is a given value a boolean?
_.isBoolean = function(obj) {
return obj === true || obj === false || toString.call(obj) == '[object Boolean]';
};
// Is a given value a date?
_.isDate = function(obj) {
return toString.call(obj) == '[object Date]';
};
// Is the given value a regular expression?
_.isRegExp = function(obj) {
return toString.call(obj) == '[object RegExp]';
};
// Is a given value equal to null?
_.isNull = function(obj) {
return obj === null;
};
// Is a given variable undefined?
_.isUndefined = function(obj) {
return obj === void 0;
};
// Has own property?
_.has = function(obj, key) {
return hasOwnProperty.call(obj, key);
};
// Utility Functions
// -----------------
// Run Underscore.js in *noConflict* mode, returning the `_` variable to its
// previous owner. Returns a reference to the Underscore object.
_.noConflict = function() {
root._ = previousUnderscore;
return this;
};
// Keep the identity function around for default iterators.
_.identity = function(value) {
return value;
};
// Run a function **n** times.
_.times = function (n, iterator, context) {
for (var i = 0; i < n; i++) iterator.call(context, i);
};
// Escape a string for HTML interpolation.
_.escape = function(string) {
return (''+string).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;').replace(/'/g, '&#x27;').replace(/\//g,'&#x2F;');
};
// Add your own custom functions to the Underscore object, ensuring that
// they're correctly added to the OOP wrapper as well.
_.mixin = function(obj) {
each(_.functions(obj), function(name){
addToWrapper(name, _[name] = obj[name]);
});
};
// Generate a unique integer id (unique within the entire client session).
// Useful for temporary DOM ids.
var idCounter = 0;
_.uniqueId = function(prefix) {
var id = idCounter++;
return prefix ? prefix + id : id;
};
// By default, Underscore uses ERB-style template delimiters, change the
// following template settings to use alternative delimiters.
_.templateSettings = {
evaluate : /<%([\s\S]+?)%>/g,
interpolate : /<%=([\s\S]+?)%>/g,
escape : /<%-([\s\S]+?)%>/g
};
// When customizing `templateSettings`, if you don't want to define an
// interpolation, evaluation or escaping regex, we need one that is
// guaranteed not to match.
var noMatch = /.^/;
// Within an interpolation, evaluation, or escaping, remove HTML escaping
// that had been previously added.
var unescape = function(code) {
return code.replace(/\\\\/g, '\\').replace(/\\'/g, "'");
};
// JavaScript micro-templating, similar to John Resig's implementation.
// Underscore templating handles arbitrary delimiters, preserves whitespace,
// and correctly escapes quotes within interpolated code.
_.template = function(str, data) {
var c = _.templateSettings;
var tmpl = 'var __p=[],print=function(){__p.push.apply(__p,arguments);};' +
'with(obj||{}){__p.push(\'' +
str.replace(/\\/g, '\\\\')
.replace(/'/g, "\\'")
.replace(c.escape || noMatch, function(match, code) {
return "',_.escape(" + unescape(code) + "),'";
})
.replace(c.interpolate || noMatch, function(match, code) {
return "'," + unescape(code) + ",'";
})
.replace(c.evaluate || noMatch, function(match, code) {
return "');" + unescape(code).replace(/[\r\n\t]/g, ' ') + ";__p.push('";
})
.replace(/\r/g, '\\r')
.replace(/\n/g, '\\n')
.replace(/\t/g, '\\t')
+ "');}return __p.join('');";
var func = new Function('obj', '_', tmpl);
if (data) return func(data, _);
return function(data) {
return func.call(this, data, _);
};
};
// Add a "chain" function, which will delegate to the wrapper.
_.chain = function(obj) {
return _(obj).chain();
};
// The OOP Wrapper
// ---------------
// If Underscore is called as a function, it returns a wrapped object that
// can be used OO-style. This wrapper holds altered versions of all the
// underscore functions. Wrapped objects may be chained.
var wrapper = function(obj) { this._wrapped = obj; };
// Expose `wrapper.prototype` as `_.prototype`
_.prototype = wrapper.prototype;
// Helper function to continue chaining intermediate results.
var result = function(obj, chain) {
return chain ? _(obj).chain() : obj;
};
// A method to easily add functions to the OOP wrapper.
var addToWrapper = function(name, func) {
wrapper.prototype[name] = function() {
var args = slice.call(arguments);
unshift.call(args, this._wrapped);
return result(func.apply(_, args), this._chain);
};
};
// Add all of the Underscore functions to the wrapper object.
_.mixin(_);
// Add all mutator Array functions to the wrapper.
each(['pop', 'push', 'reverse', 'shift', 'sort', 'splice', 'unshift'], function(name) {
var method = ArrayProto[name];
wrapper.prototype[name] = function() {
var wrapped = this._wrapped;
method.apply(wrapped, arguments);
var length = wrapped.length;
if ((name == 'shift' || name == 'splice') && length === 0) delete wrapped[0];
return result(wrapped, this._chain);
};
});
// Add all accessor Array functions to the wrapper.
each(['concat', 'join', 'slice'], function(name) {
var method = ArrayProto[name];
wrapper.prototype[name] = function() {
return result(method.apply(this._wrapped, arguments), this._chain);
};
});
// Start chaining a wrapped Underscore object.
wrapper.prototype.chain = function() {
this._chain = true;
return this;
};
// Extracts the result from a wrapped and chained object.
wrapper.prototype.value = function() {
return this._wrapped;
};
}).call(this);

31
docs/_build/html/_static/underscore.js vendored Normal file
View File

@ -0,0 +1,31 @@
// Underscore.js 1.3.1
// (c) 2009-2012 Jeremy Ashkenas, DocumentCloud Inc.
// Underscore is freely distributable under the MIT license.
// Portions of Underscore are inspired or borrowed from Prototype,
// Oliver Steele's Functional, and John Resig's Micro-Templating.
// For all details and documentation:
// http://documentcloud.github.com/underscore
(function(){function q(a,c,d){if(a===c)return a!==0||1/a==1/c;if(a==null||c==null)return a===c;if(a._chain)a=a._wrapped;if(c._chain)c=c._wrapped;if(a.isEqual&&b.isFunction(a.isEqual))return a.isEqual(c);if(c.isEqual&&b.isFunction(c.isEqual))return c.isEqual(a);var e=l.call(a);if(e!=l.call(c))return false;switch(e){case "[object String]":return a==String(c);case "[object Number]":return a!=+a?c!=+c:a==0?1/a==1/c:a==+c;case "[object Date]":case "[object Boolean]":return+a==+c;case "[object RegExp]":return a.source==
c.source&&a.global==c.global&&a.multiline==c.multiline&&a.ignoreCase==c.ignoreCase}if(typeof a!="object"||typeof c!="object")return false;for(var f=d.length;f--;)if(d[f]==a)return true;d.push(a);var f=0,g=true;if(e=="[object Array]"){if(f=a.length,g=f==c.length)for(;f--;)if(!(g=f in a==f in c&&q(a[f],c[f],d)))break}else{if("constructor"in a!="constructor"in c||a.constructor!=c.constructor)return false;for(var h in a)if(b.has(a,h)&&(f++,!(g=b.has(c,h)&&q(a[h],c[h],d))))break;if(g){for(h in c)if(b.has(c,
h)&&!f--)break;g=!f}}d.pop();return g}var r=this,G=r._,n={},k=Array.prototype,o=Object.prototype,i=k.slice,H=k.unshift,l=o.toString,I=o.hasOwnProperty,w=k.forEach,x=k.map,y=k.reduce,z=k.reduceRight,A=k.filter,B=k.every,C=k.some,p=k.indexOf,D=k.lastIndexOf,o=Array.isArray,J=Object.keys,s=Function.prototype.bind,b=function(a){return new m(a)};if(typeof exports!=="undefined"){if(typeof module!=="undefined"&&module.exports)exports=module.exports=b;exports._=b}else r._=b;b.VERSION="1.3.1";var j=b.each=
b.forEach=function(a,c,d){if(a!=null)if(w&&a.forEach===w)a.forEach(c,d);else if(a.length===+a.length)for(var e=0,f=a.length;e<f;e++){if(e in a&&c.call(d,a[e],e,a)===n)break}else for(e in a)if(b.has(a,e)&&c.call(d,a[e],e,a)===n)break};b.map=b.collect=function(a,c,b){var e=[];if(a==null)return e;if(x&&a.map===x)return a.map(c,b);j(a,function(a,g,h){e[e.length]=c.call(b,a,g,h)});if(a.length===+a.length)e.length=a.length;return e};b.reduce=b.foldl=b.inject=function(a,c,d,e){var f=arguments.length>2;a==
null&&(a=[]);if(y&&a.reduce===y)return e&&(c=b.bind(c,e)),f?a.reduce(c,d):a.reduce(c);j(a,function(a,b,i){f?d=c.call(e,d,a,b,i):(d=a,f=true)});if(!f)throw new TypeError("Reduce of empty array with no initial value");return d};b.reduceRight=b.foldr=function(a,c,d,e){var f=arguments.length>2;a==null&&(a=[]);if(z&&a.reduceRight===z)return e&&(c=b.bind(c,e)),f?a.reduceRight(c,d):a.reduceRight(c);var g=b.toArray(a).reverse();e&&!f&&(c=b.bind(c,e));return f?b.reduce(g,c,d,e):b.reduce(g,c)};b.find=b.detect=
function(a,c,b){var e;E(a,function(a,g,h){if(c.call(b,a,g,h))return e=a,true});return e};b.filter=b.select=function(a,c,b){var e=[];if(a==null)return e;if(A&&a.filter===A)return a.filter(c,b);j(a,function(a,g,h){c.call(b,a,g,h)&&(e[e.length]=a)});return e};b.reject=function(a,c,b){var e=[];if(a==null)return e;j(a,function(a,g,h){c.call(b,a,g,h)||(e[e.length]=a)});return e};b.every=b.all=function(a,c,b){var e=true;if(a==null)return e;if(B&&a.every===B)return a.every(c,b);j(a,function(a,g,h){if(!(e=
e&&c.call(b,a,g,h)))return n});return e};var E=b.some=b.any=function(a,c,d){c||(c=b.identity);var e=false;if(a==null)return e;if(C&&a.some===C)return a.some(c,d);j(a,function(a,b,h){if(e||(e=c.call(d,a,b,h)))return n});return!!e};b.include=b.contains=function(a,c){var b=false;if(a==null)return b;return p&&a.indexOf===p?a.indexOf(c)!=-1:b=E(a,function(a){return a===c})};b.invoke=function(a,c){var d=i.call(arguments,2);return b.map(a,function(a){return(b.isFunction(c)?c||a:a[c]).apply(a,d)})};b.pluck=
function(a,c){return b.map(a,function(a){return a[c]})};b.max=function(a,c,d){if(!c&&b.isArray(a))return Math.max.apply(Math,a);if(!c&&b.isEmpty(a))return-Infinity;var e={computed:-Infinity};j(a,function(a,b,h){b=c?c.call(d,a,b,h):a;b>=e.computed&&(e={value:a,computed:b})});return e.value};b.min=function(a,c,d){if(!c&&b.isArray(a))return Math.min.apply(Math,a);if(!c&&b.isEmpty(a))return Infinity;var e={computed:Infinity};j(a,function(a,b,h){b=c?c.call(d,a,b,h):a;b<e.computed&&(e={value:a,computed:b})});
return e.value};b.shuffle=function(a){var b=[],d;j(a,function(a,f){f==0?b[0]=a:(d=Math.floor(Math.random()*(f+1)),b[f]=b[d],b[d]=a)});return b};b.sortBy=function(a,c,d){return b.pluck(b.map(a,function(a,b,g){return{value:a,criteria:c.call(d,a,b,g)}}).sort(function(a,b){var c=a.criteria,d=b.criteria;return c<d?-1:c>d?1:0}),"value")};b.groupBy=function(a,c){var d={},e=b.isFunction(c)?c:function(a){return a[c]};j(a,function(a,b){var c=e(a,b);(d[c]||(d[c]=[])).push(a)});return d};b.sortedIndex=function(a,
c,d){d||(d=b.identity);for(var e=0,f=a.length;e<f;){var g=e+f>>1;d(a[g])<d(c)?e=g+1:f=g}return e};b.toArray=function(a){return!a?[]:a.toArray?a.toArray():b.isArray(a)?i.call(a):b.isArguments(a)?i.call(a):b.values(a)};b.size=function(a){return b.toArray(a).length};b.first=b.head=function(a,b,d){return b!=null&&!d?i.call(a,0,b):a[0]};b.initial=function(a,b,d){return i.call(a,0,a.length-(b==null||d?1:b))};b.last=function(a,b,d){return b!=null&&!d?i.call(a,Math.max(a.length-b,0)):a[a.length-1]};b.rest=
b.tail=function(a,b,d){return i.call(a,b==null||d?1:b)};b.compact=function(a){return b.filter(a,function(a){return!!a})};b.flatten=function(a,c){return b.reduce(a,function(a,e){if(b.isArray(e))return a.concat(c?e:b.flatten(e));a[a.length]=e;return a},[])};b.without=function(a){return b.difference(a,i.call(arguments,1))};b.uniq=b.unique=function(a,c,d){var d=d?b.map(a,d):a,e=[];b.reduce(d,function(d,g,h){if(0==h||(c===true?b.last(d)!=g:!b.include(d,g)))d[d.length]=g,e[e.length]=a[h];return d},[]);
return e};b.union=function(){return b.uniq(b.flatten(arguments,true))};b.intersection=b.intersect=function(a){var c=i.call(arguments,1);return b.filter(b.uniq(a),function(a){return b.every(c,function(c){return b.indexOf(c,a)>=0})})};b.difference=function(a){var c=b.flatten(i.call(arguments,1));return b.filter(a,function(a){return!b.include(c,a)})};b.zip=function(){for(var a=i.call(arguments),c=b.max(b.pluck(a,"length")),d=Array(c),e=0;e<c;e++)d[e]=b.pluck(a,""+e);return d};b.indexOf=function(a,c,
d){if(a==null)return-1;var e;if(d)return d=b.sortedIndex(a,c),a[d]===c?d:-1;if(p&&a.indexOf===p)return a.indexOf(c);for(d=0,e=a.length;d<e;d++)if(d in a&&a[d]===c)return d;return-1};b.lastIndexOf=function(a,b){if(a==null)return-1;if(D&&a.lastIndexOf===D)return a.lastIndexOf(b);for(var d=a.length;d--;)if(d in a&&a[d]===b)return d;return-1};b.range=function(a,b,d){arguments.length<=1&&(b=a||0,a=0);for(var d=arguments[2]||1,e=Math.max(Math.ceil((b-a)/d),0),f=0,g=Array(e);f<e;)g[f++]=a,a+=d;return g};
var F=function(){};b.bind=function(a,c){var d,e;if(a.bind===s&&s)return s.apply(a,i.call(arguments,1));if(!b.isFunction(a))throw new TypeError;e=i.call(arguments,2);return d=function(){if(!(this instanceof d))return a.apply(c,e.concat(i.call(arguments)));F.prototype=a.prototype;var b=new F,g=a.apply(b,e.concat(i.call(arguments)));return Object(g)===g?g:b}};b.bindAll=function(a){var c=i.call(arguments,1);c.length==0&&(c=b.functions(a));j(c,function(c){a[c]=b.bind(a[c],a)});return a};b.memoize=function(a,
c){var d={};c||(c=b.identity);return function(){var e=c.apply(this,arguments);return b.has(d,e)?d[e]:d[e]=a.apply(this,arguments)}};b.delay=function(a,b){var d=i.call(arguments,2);return setTimeout(function(){return a.apply(a,d)},b)};b.defer=function(a){return b.delay.apply(b,[a,1].concat(i.call(arguments,1)))};b.throttle=function(a,c){var d,e,f,g,h,i=b.debounce(function(){h=g=false},c);return function(){d=this;e=arguments;var b;f||(f=setTimeout(function(){f=null;h&&a.apply(d,e);i()},c));g?h=true:
a.apply(d,e);i();g=true}};b.debounce=function(a,b){var d;return function(){var e=this,f=arguments;clearTimeout(d);d=setTimeout(function(){d=null;a.apply(e,f)},b)}};b.once=function(a){var b=false,d;return function(){if(b)return d;b=true;return d=a.apply(this,arguments)}};b.wrap=function(a,b){return function(){var d=[a].concat(i.call(arguments,0));return b.apply(this,d)}};b.compose=function(){var a=arguments;return function(){for(var b=arguments,d=a.length-1;d>=0;d--)b=[a[d].apply(this,b)];return b[0]}};
b.after=function(a,b){return a<=0?b():function(){if(--a<1)return b.apply(this,arguments)}};b.keys=J||function(a){if(a!==Object(a))throw new TypeError("Invalid object");var c=[],d;for(d in a)b.has(a,d)&&(c[c.length]=d);return c};b.values=function(a){return b.map(a,b.identity)};b.functions=b.methods=function(a){var c=[],d;for(d in a)b.isFunction(a[d])&&c.push(d);return c.sort()};b.extend=function(a){j(i.call(arguments,1),function(b){for(var d in b)a[d]=b[d]});return a};b.defaults=function(a){j(i.call(arguments,
1),function(b){for(var d in b)a[d]==null&&(a[d]=b[d])});return a};b.clone=function(a){return!b.isObject(a)?a:b.isArray(a)?a.slice():b.extend({},a)};b.tap=function(a,b){b(a);return a};b.isEqual=function(a,b){return q(a,b,[])};b.isEmpty=function(a){if(b.isArray(a)||b.isString(a))return a.length===0;for(var c in a)if(b.has(a,c))return false;return true};b.isElement=function(a){return!!(a&&a.nodeType==1)};b.isArray=o||function(a){return l.call(a)=="[object Array]"};b.isObject=function(a){return a===Object(a)};
b.isArguments=function(a){return l.call(a)=="[object Arguments]"};if(!b.isArguments(arguments))b.isArguments=function(a){return!(!a||!b.has(a,"callee"))};b.isFunction=function(a){return l.call(a)=="[object Function]"};b.isString=function(a){return l.call(a)=="[object String]"};b.isNumber=function(a){return l.call(a)=="[object Number]"};b.isNaN=function(a){return a!==a};b.isBoolean=function(a){return a===true||a===false||l.call(a)=="[object Boolean]"};b.isDate=function(a){return l.call(a)=="[object Date]"};
b.isRegExp=function(a){return l.call(a)=="[object RegExp]"};b.isNull=function(a){return a===null};b.isUndefined=function(a){return a===void 0};b.has=function(a,b){return I.call(a,b)};b.noConflict=function(){r._=G;return this};b.identity=function(a){return a};b.times=function(a,b,d){for(var e=0;e<a;e++)b.call(d,e)};b.escape=function(a){return(""+a).replace(/&/g,"&amp;").replace(/</g,"&lt;").replace(/>/g,"&gt;").replace(/"/g,"&quot;").replace(/'/g,"&#x27;").replace(/\//g,"&#x2F;")};b.mixin=function(a){j(b.functions(a),
function(c){K(c,b[c]=a[c])})};var L=0;b.uniqueId=function(a){var b=L++;return a?a+b:b};b.templateSettings={evaluate:/<%([\s\S]+?)%>/g,interpolate:/<%=([\s\S]+?)%>/g,escape:/<%-([\s\S]+?)%>/g};var t=/.^/,u=function(a){return a.replace(/\\\\/g,"\\").replace(/\\'/g,"'")};b.template=function(a,c){var d=b.templateSettings,d="var __p=[],print=function(){__p.push.apply(__p,arguments);};with(obj||{}){__p.push('"+a.replace(/\\/g,"\\\\").replace(/'/g,"\\'").replace(d.escape||t,function(a,b){return"',_.escape("+
u(b)+"),'"}).replace(d.interpolate||t,function(a,b){return"',"+u(b)+",'"}).replace(d.evaluate||t,function(a,b){return"');"+u(b).replace(/[\r\n\t]/g," ")+";__p.push('"}).replace(/\r/g,"\\r").replace(/\n/g,"\\n").replace(/\t/g,"\\t")+"');}return __p.join('');",e=new Function("obj","_",d);return c?e(c,b):function(a){return e.call(this,a,b)}};b.chain=function(a){return b(a).chain()};var m=function(a){this._wrapped=a};b.prototype=m.prototype;var v=function(a,c){return c?b(a).chain():a},K=function(a,c){m.prototype[a]=
function(){var a=i.call(arguments);H.call(a,this._wrapped);return v(c.apply(b,a),this._chain)}};b.mixin(b);j("pop,push,reverse,shift,sort,splice,unshift".split(","),function(a){var b=k[a];m.prototype[a]=function(){var d=this._wrapped;b.apply(d,arguments);var e=d.length;(a=="shift"||a=="splice")&&e===0&&delete d[0];return v(d,this._chain)}});j(["concat","join","slice"],function(a){var b=k[a];m.prototype[a]=function(){return v(b.apply(this._wrapped,arguments),this._chain)}});m.prototype.chain=function(){this._chain=
true;return this};m.prototype.value=function(){return this._wrapped}}).call(this);

467
docs/_build/html/api.html vendored Normal file
View File

@ -0,0 +1,467 @@
<!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 &mdash; 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 Loader" href="plugin_loader.html" />
<link rel="prev" title="Version" href="version.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>
</ul>
<p class="caption"><span class="caption-text">Tutorials</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="install.html">Install</a></li>
<li class="toctree-l1"><a class="reference internal" href="build.html">Build and Deploy</a></li>
<li class="toctree-l1"><a class="reference internal" href="custom.html">Building a Custom Plugin</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="version.html">Version</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="#anatomy-of-a-plugin">Anatomy of a Plugin</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="#getapis">GetAPIs</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#injected-apis">Injected APIs</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#backend-object">Backend Object</a><ul>
<li class="toctree-l4"><a class="reference internal" href="#downloader">Downloader</a></li>
<li class="toctree-l4"><a class="reference internal" href="#suggestgastipcap">SuggestGasTipCap</a></li>
<li class="toctree-l4"><a class="reference internal" href="#extrpcenabled">ExtRPCEnabled</a></li>
<li class="toctree-l4"><a class="reference internal" href="#rpcgascap">RPCGasCap</a></li>
<li class="toctree-l4"><a class="reference internal" href="#rpctxfeecap">RPCTxFeeCap</a></li>
<li class="toctree-l4"><a class="reference internal" href="#unprotectedallowed">UnprotectedAllowed</a></li>
<li class="toctree-l4"><a class="reference internal" href="#sethead">SetHead</a></li>
<li class="toctree-l4"><a class="reference internal" href="#headerbynumber">HeaderByNumber</a></li>
<li class="toctree-l4"><a class="reference internal" href="#headerbyhash">HeaderByHash</a></li>
<li class="toctree-l4"><a class="reference internal" href="#currentheader">CurrentHeader</a></li>
<li class="toctree-l4"><a class="reference internal" href="#currentblock">CurrentBlock</a></li>
<li class="toctree-l4"><a class="reference internal" href="#blockbynumber">BlockByNumber</a></li>
<li class="toctree-l4"><a class="reference internal" href="#blockbyhash">BlockByHash</a></li>
<li class="toctree-l4"><a class="reference internal" href="#getreceipts">GetReceipts</a></li>
<li class="toctree-l4"><a class="reference internal" href="#gettd">GetTd</a></li>
<li class="toctree-l4"><a class="reference internal" href="#subscribechainevent">SubscribeChainEvent</a></li>
<li class="toctree-l4"><a class="reference internal" href="#subscribechainheadevent">SubscribeChainHeadEvent</a></li>
<li class="toctree-l4"><a class="reference internal" href="#subscribechainsideevent">SubscribeChainSideEvent</a></li>
<li class="toctree-l4"><a class="reference internal" href="#sendtx">SendTx</a></li>
<li class="toctree-l4"><a class="reference internal" href="#gettransaction">GetTransaction</a></li>
<li class="toctree-l4"><a class="reference internal" href="#getpooltransaction">GetPoolTransaction</a></li>
<li class="toctree-l4"><a class="reference internal" href="#getpoolnonce">GetPoolNonce</a></li>
<li class="toctree-l4"><a class="reference internal" href="#stats">Stats</a></li>
<li class="toctree-l4"><a class="reference internal" href="#txpoolcontent">TxPoolContent</a></li>
<li class="toctree-l4"><a class="reference internal" href="#subscribenewtxsevent">SubscribeNewTxsEvent</a></li>
<li class="toctree-l4"><a class="reference internal" href="#getlogs">GetLogs</a></li>
<li class="toctree-l4"><a class="reference internal" href="#subscribelogsevent">SubscribeLogsEvent</a></li>
<li class="toctree-l4"><a class="reference internal" href="#subscribependinglogsevent">SubscribePendingLogsEvent</a></li>
<li class="toctree-l4"><a class="reference internal" href="#subscriberemovedlogsevent">SubscribeRemovedLogsEvent</a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="#node-object">Node Object</a><ul>
<li class="toctree-l4"><a class="reference internal" href="#server">Server</a></li>
<li class="toctree-l4"><a class="reference internal" href="#datadir">DataDir</a></li>
<li class="toctree-l4"><a class="reference internal" href="#instancedir">InstanceDir</a></li>
<li class="toctree-l4"><a class="reference internal" href="#ipcendpoint">IPCEndpoint</a></li>
<li class="toctree-l4"><a class="reference internal" href="#httpendpoint">HTTPEndpoint</a></li>
<li class="toctree-l4"><a class="reference internal" href="#wsendpoint">WSEndpoint</a></li>
<li class="toctree-l4"><a class="reference internal" href="#resolvepath">ResolvePath</a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="#logger">Logger</a></li>
</ul>
</li>
</ul>
</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="hooks.html">Selected Plugin Hooks</a></li>
<li class="toctree-l1"><a class="reference internal" href="hook_writing.html">Hook Writing Guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="core_restricted.html">PluGeth-utils Subpackages</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> &raquo;</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>
<div class="section" id="anatomy-of-a-plugin">
<h2>Anatomy of a Plugin<a class="headerlink" href="#anatomy-of-a-plugin" title="Permalink to this headline"></a></h2>
<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">
<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="#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">
<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="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">&quot;mynamespace&quot;</span><span class="p">,</span>
<span class="nx">Version</span><span class="p">:</span> <span class="s">&quot;1.0&quot;</span><span class="p">,</span>
<span class="nx">Service</span><span class="p">:</span> <span class="o">&amp;</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">&quot;Hello World&quot;</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 class="section" id="injected-apis">
<h2>Injected APIs<a class="headerlink" href="#injected-apis" title="Permalink to this headline"></a></h2>
<p>In addition to hooks that get invoked by Geth, several objects are injected that give you access to additional information.</p>
<div class="section" id="backend-object">
<h3>Backend Object<a class="headerlink" href="#backend-object" title="Permalink to this headline"></a></h3>
<p>The <code class="docutils literal notranslate"><span class="pre">core.Backend</span></code> object is injected by the <code class="docutils literal notranslate"><span class="pre">InitializeNode()</span></code> and <code class="docutils literal notranslate"><span class="pre">GetAPI()</span></code> functions. It offers the following functions:</p>
<div class="section" id="downloader">
<h4>Downloader<a class="headerlink" href="#downloader" title="Permalink to this headline"></a></h4>
<p><code class="docutils literal notranslate"><span class="pre">Downloader()</span> <span class="pre">Downloader</span></code></p>
<p>Returns a Downloader objects, which can provide Syncing status</p>
</div>
<div class="section" id="suggestgastipcap">
<h4>SuggestGasTipCap<a class="headerlink" href="#suggestgastipcap" title="Permalink to this headline"></a></h4>
<p><code class="docutils literal notranslate"><span class="pre">SuggestGasTipCap(ctx</span> <span class="pre">context.Context)</span> <span class="pre">(*big.Int,</span> <span class="pre">error)</span></code></p>
<p>Suggests a Gas tip for the current block.</p>
</div>
<div class="section" id="extrpcenabled">
<h4>ExtRPCEnabled<a class="headerlink" href="#extrpcenabled" title="Permalink to this headline"></a></h4>
<p><code class="docutils literal notranslate"><span class="pre">ExtRPCEnabled()</span> <span class="pre">bool</span></code></p>
<p>Returns whether RPC external RPC calls are enabled.</p>
</div>
<div class="section" id="rpcgascap">
<h4>RPCGasCap<a class="headerlink" href="#rpcgascap" title="Permalink to this headline"></a></h4>
<p><code class="docutils literal notranslate"><span class="pre">RPCGasCap()</span> <span class="pre">uint64</span></code></p>
<p>Returns the maximum Gas available to RPC Calls.</p>
</div>
<div class="section" id="rpctxfeecap">
<h4>RPCTxFeeCap<a class="headerlink" href="#rpctxfeecap" title="Permalink to this headline"></a></h4>
<p><code class="docutils literal notranslate"><span class="pre">RPCTxFeeCap()</span> <span class="pre">float64</span></code></p>
<p>Returns the maximum transaction fee for a transaction submitted via RPC.</p>
</div>
<div class="section" id="unprotectedallowed">
<h4>UnprotectedAllowed<a class="headerlink" href="#unprotectedallowed" title="Permalink to this headline"></a></h4>
<p><code class="docutils literal notranslate"><span class="pre">UnprotectedAllowed()</span> <span class="pre">bool</span></code></p>
<p>Returns whether or not unprotected transactions can be transmitted through this
node via RPC.</p>
</div>
<div class="section" id="sethead">
<h4>SetHead<a class="headerlink" href="#sethead" title="Permalink to this headline"></a></h4>
<p><code class="docutils literal notranslate"><span class="pre">SetHead(number</span> <span class="pre">uint64)</span></code></p>
<p>Resets the head to the specified block number.</p>
</div>
<div class="section" id="headerbynumber">
<h4>HeaderByNumber<a class="headerlink" href="#headerbynumber" title="Permalink to this headline"></a></h4>
<p><code class="docutils literal notranslate"><span class="pre">HeaderByNumber(ctx</span> <span class="pre">context.Context,</span> <span class="pre">number</span> <span class="pre">int64)</span> <span class="pre">([]byte,</span> <span class="pre">error)</span></code></p>
<p>Returns an RLP encoded block header for the specified block number.</p>
<p>The RLP encoded response can be decoded into a <cite>plugeth-utils/restricted/types.Header</cite> object.</p>
</div>
<div class="section" id="headerbyhash">
<h4>HeaderByHash<a class="headerlink" href="#headerbyhash" title="Permalink to this headline"></a></h4>
<p><code class="docutils literal notranslate"><span class="pre">HeaderByHash(ctx</span> <span class="pre">context.Context,</span> <span class="pre">hash</span> <span class="pre">Hash)</span> <span class="pre">([]byte,</span> <span class="pre">error)</span></code></p>
<p>Returns an RLP encoded block header for the specified block hash.</p>
<p>The RLP encoded response can be decoded into a <cite>plugeth-utils/restricted/types.Header</cite> object.</p>
</div>
<div class="section" id="currentheader">
<h4>CurrentHeader<a class="headerlink" href="#currentheader" title="Permalink to this headline"></a></h4>
<p><code class="docutils literal notranslate"><span class="pre">CurrentHeader()</span> <span class="pre">[]byte</span></code></p>
<p>Returns an RLP encoded block header for the current block.</p>
<p>The RLP encoded response can be decoded into a <cite>plugeth-utils/restricted/types.Header</cite> object.</p>
</div>
<div class="section" id="currentblock">
<h4>CurrentBlock<a class="headerlink" href="#currentblock" title="Permalink to this headline"></a></h4>
<p><code class="docutils literal notranslate"><span class="pre">CurrentBlock()</span> <span class="pre">[]byte</span></code></p>
<p>Returns an RLP encoded full block for the current block.</p>
<p>The RLP encoded response can be decoded into a <cite>plugeth-utils/restricted/types.Block</cite> object.</p>
</div>
<div class="section" id="blockbynumber">
<h4>BlockByNumber<a class="headerlink" href="#blockbynumber" title="Permalink to this headline"></a></h4>
<p><code class="docutils literal notranslate"><span class="pre">BlockByNumber(ctx</span> <span class="pre">context.Context,</span> <span class="pre">number</span> <span class="pre">int64)</span> <span class="pre">([]byte,</span> <span class="pre">error)</span></code></p>
<p>Returns an RLP encoded full block for the specified block number.</p>
<p>The RLP encoded response can be decoded into a <cite>plugeth-utils/restricted/types.Block</cite> object.</p>
</div>
<div class="section" id="blockbyhash">
<h4>BlockByHash<a class="headerlink" href="#blockbyhash" title="Permalink to this headline"></a></h4>
<p><code class="docutils literal notranslate"><span class="pre">BlockByHash(ctx</span> <span class="pre">context.Context,</span> <span class="pre">hash</span> <span class="pre">Hash)</span> <span class="pre">([]byte,</span> <span class="pre">error)</span></code></p>
<p>Returns an RLP encoded full block for the specified block hash.</p>
<p>The RLP encoded response can be decoded into a <cite>plugeth-utils/restricted/types.Block</cite> object.</p>
</div>
<div class="section" id="getreceipts">
<h4>GetReceipts<a class="headerlink" href="#getreceipts" title="Permalink to this headline"></a></h4>
<p><code class="docutils literal notranslate"><span class="pre">GetReceipts(ctx</span> <span class="pre">context.Context,</span> <span class="pre">hash</span> <span class="pre">Hash)</span> <span class="pre">([]byte,</span> <span class="pre">error)</span></code></p>
<p>Returns an JSON encoded list of receipts for the specified block hash.</p>
<p>The JSON encoded response can be decoded into a <cite>plugeth-utils/restricted/types.Receipts</cite> object.</p>
</div>
<div class="section" id="gettd">
<h4>GetTd<a class="headerlink" href="#gettd" title="Permalink to this headline"></a></h4>
<p><code class="docutils literal notranslate"><span class="pre">GetTd(ctx</span> <span class="pre">context.Context,</span> <span class="pre">hash</span> <span class="pre">Hash)</span> <span class="pre">*big.Int</span></code></p>
<p>Returns the total difficulty for the specified block hash.</p>
</div>
<div class="section" id="subscribechainevent">
<h4>SubscribeChainEvent<a class="headerlink" href="#subscribechainevent" title="Permalink to this headline"></a></h4>
<p><code class="docutils literal notranslate"><span class="pre">SubscribeChainEvent(ch</span> <span class="pre">chan&lt;-</span> <span class="pre">ChainEvent)</span> <span class="pre">Subscription</span></code></p>
<p>Subscribes the provided channel to new chain events.</p>
</div>
<div class="section" id="subscribechainheadevent">
<h4>SubscribeChainHeadEvent<a class="headerlink" href="#subscribechainheadevent" title="Permalink to this headline"></a></h4>
<p><code class="docutils literal notranslate"><span class="pre">SubscribeChainHeadEvent(ch</span> <span class="pre">chan&lt;-</span> <span class="pre">ChainHeadEvent)</span> <span class="pre">Subscription</span></code></p>
<p>Subscribes the provided channel to new chain head events.</p>
</div>
<div class="section" id="subscribechainsideevent">
<h4>SubscribeChainSideEvent<a class="headerlink" href="#subscribechainsideevent" title="Permalink to this headline"></a></h4>
<p><code class="docutils literal notranslate"><span class="pre">SubscribeChainSideEvent(ch</span> <span class="pre">chan&lt;-</span> <span class="pre">ChainSideEvent)</span> <span class="pre">Subscription</span></code></p>
<p>Subscribes the provided channel to new chain side events.</p>
</div>
<div class="section" id="sendtx">
<h4>SendTx<a class="headerlink" href="#sendtx" title="Permalink to this headline"></a></h4>
<p><code class="docutils literal notranslate"><span class="pre">SendTx(ctx</span> <span class="pre">context.Context,</span> <span class="pre">signedTx</span> <span class="pre">[]byte)</span> <span class="pre">error</span></code></p>
<p>Sends an RLP encoded, signed transaction to the network.</p>
</div>
<div class="section" id="gettransaction">
<h4>GetTransaction<a class="headerlink" href="#gettransaction" title="Permalink to this headline"></a></h4>
<p><code class="docutils literal notranslate"><span class="pre">GetTransaction(ctx</span> <span class="pre">context.Context,</span> <span class="pre">txHash</span> <span class="pre">Hash)</span> <span class="pre">([]byte,</span> <span class="pre">Hash,</span> <span class="pre">uint64,</span> <span class="pre">uint64,</span> <span class="pre">error)</span></code></p>
<p>Returns an RLP encoded transaction at the specified hash, along with the hash and number of the included block, and the transaction’s position within that block.</p>
<div class="section" id="getpooltransactions">
<h5>GetPoolTransactions<a class="headerlink" href="#getpooltransactions" title="Permalink to this headline"></a></h5>
<p><code class="docutils literal notranslate"><span class="pre">GetPoolTransactions()</span> <span class="pre">([][]byte,</span> <span class="pre">error)</span></code></p>
<p>Returns a list of RLP encoded transactions found in the mempool</p>
</div>
</div>
<div class="section" id="getpooltransaction">
<h4>GetPoolTransaction<a class="headerlink" href="#getpooltransaction" title="Permalink to this headline"></a></h4>
<p><code class="docutils literal notranslate"><span class="pre">GetPoolTransaction(txHash</span> <span class="pre">Hash)</span> <span class="pre">[]byte</span></code></p>
<p>Returns the RLP encoded transaction from the mempool at the specified hash.</p>
</div>
<div class="section" id="getpoolnonce">
<h4>GetPoolNonce<a class="headerlink" href="#getpoolnonce" title="Permalink to this headline"></a></h4>
<p><code class="docutils literal notranslate"><span class="pre">GetPoolNonce(ctx</span> <span class="pre">context.Context,</span> <span class="pre">addr</span> <span class="pre">Address)</span> <span class="pre">(uint64,</span> <span class="pre">error)</span></code></p>
<p>Returns the nonce of the last transaction for a given address, including
transactions found in the mempool.</p>
</div>
<div class="section" id="stats">
<h4>Stats<a class="headerlink" href="#stats" title="Permalink to this headline"></a></h4>
<p><code class="docutils literal notranslate"><span class="pre">Stats()</span> <span class="pre">(pending</span> <span class="pre">int,</span> <span class="pre">queued</span> <span class="pre">int)</span></code></p>
<p>Returns the number of pending and queued transactions in the mempool.</p>
</div>
<div class="section" id="txpoolcontent">
<h4>TxPoolContent<a class="headerlink" href="#txpoolcontent" title="Permalink to this headline"></a></h4>
<p><code class="docutils literal notranslate"><span class="pre">TxPoolContent()</span> <span class="pre">(map[Address][][]byte,</span> <span class="pre">map[Address][][]byte)</span></code></p>
<p>Returns a map of addresses to the list of RLP encoded transactions pending in
the mempool, and queued in the mempool.</p>
</div>
<div class="section" id="subscribenewtxsevent">
<h4>SubscribeNewTxsEvent<a class="headerlink" href="#subscribenewtxsevent" title="Permalink to this headline"></a></h4>
<p><code class="docutils literal notranslate"><span class="pre">SubscribeNewTxsEvent(chan&lt;-</span> <span class="pre">NewTxsEvent)</span> <span class="pre">Subscription</span></code></p>
<p>Subscribe to a feed of new transactions added to the mempool.</p>
</div>
<div class="section" id="getlogs">
<h4>GetLogs<a class="headerlink" href="#getlogs" title="Permalink to this headline"></a></h4>
<p><code class="docutils literal notranslate"><span class="pre">GetLogs(ctx</span> <span class="pre">context.Context,</span> <span class="pre">blockHash</span> <span class="pre">Hash)</span> <span class="pre">([][]byte,</span> <span class="pre">error)</span></code></p>
<p>Returns a list of RLP encoded logs found in the specified block.</p>
</div>
<div class="section" id="subscribelogsevent">
<h4>SubscribeLogsEvent<a class="headerlink" href="#subscribelogsevent" title="Permalink to this headline"></a></h4>
<p><code class="docutils literal notranslate"><span class="pre">SubscribeLogsEvent(ch</span> <span class="pre">chan&lt;-</span> <span class="pre">[][]byte)</span> <span class="pre">Subscription</span></code></p>
<p>Subscribe to logs included in a confirmed block.</p>
</div>
<div class="section" id="subscribependinglogsevent">
<h4>SubscribePendingLogsEvent<a class="headerlink" href="#subscribependinglogsevent" title="Permalink to this headline"></a></h4>
<p><code class="docutils literal notranslate"><span class="pre">SubscribePendingLogsEvent(ch</span> <span class="pre">chan&lt;-</span> <span class="pre">[][]byte)</span> <span class="pre">Subscription</span></code></p>
<p>Subscribe to logs from pending transactions.</p>
</div>
<div class="section" id="subscriberemovedlogsevent">
<h4>SubscribeRemovedLogsEvent<a class="headerlink" href="#subscriberemovedlogsevent" title="Permalink to this headline"></a></h4>
<p><code class="docutils literal notranslate"><span class="pre">SubscribeRemovedLogsEvent(ch</span> <span class="pre">chan&lt;-</span> <span class="pre">[]byte)</span> <span class="pre">Subscription</span></code></p>
<p>Subscribe to logs removed from the canonical chain in reorged blocks.</p>
</div>
</div>
<div class="section" id="node-object">
<h3>Node Object<a class="headerlink" href="#node-object" title="Permalink to this headline"></a></h3>
<p>The <code class="docutils literal notranslate"><span class="pre">core.Node</span></code> object is injected by the <code class="docutils literal notranslate"><span class="pre">InitializeNode()</span></code> and <code class="docutils literal notranslate"><span class="pre">GetAPI()</span></code> functions. It offers the following functions:</p>
<div class="section" id="server">
<h4>Server<a class="headerlink" href="#server" title="Permalink to this headline"></a></h4>
<p><code class="docutils literal notranslate"><span class="pre">Server()</span> <span class="pre">Server</span></code></p>
<p>The Server object provides access to <code class="docutils literal notranslate"><span class="pre">server.PeerCount()</span></code>, the number of peers connected to the node.</p>
</div>
<div class="section" id="datadir">
<h4>DataDir<a class="headerlink" href="#datadir" title="Permalink to this headline"></a></h4>
<p><code class="docutils literal notranslate"><span class="pre">DataDir()</span> <span class="pre">string</span></code></p>
<p>Returns the Ethereuem datadir.</p>
</div>
<div class="section" id="instancedir">
<h4>InstanceDir<a class="headerlink" href="#instancedir" title="Permalink to this headline"></a></h4>
<p><code class="docutils literal notranslate"><span class="pre">InstanceDir()</span> <span class="pre">string</span></code></p>
<p>Returns the instancedir used by the protocol stack.</p>
</div>
<div class="section" id="ipcendpoint">
<h4>IPCEndpoint<a class="headerlink" href="#ipcendpoint" title="Permalink to this headline"></a></h4>
<p><code class="docutils literal notranslate"><span class="pre">IPCEndpoint()</span> <span class="pre">string</span></code></p>
<p>The path of the IPC Endpoint for this node.</p>
</div>
<div class="section" id="httpendpoint">
<h4>HTTPEndpoint<a class="headerlink" href="#httpendpoint" title="Permalink to this headline"></a></h4>
<p><code class="docutils literal notranslate"><span class="pre">HTTPEndpoint()</span> <span class="pre">string</span></code></p>
<p>The url of the HTTP Endpoint for this node.</p>
</div>
<div class="section" id="wsendpoint">
<h4>WSEndpoint<a class="headerlink" href="#wsendpoint" title="Permalink to this headline"></a></h4>
<p><code class="docutils literal notranslate"><span class="pre">WSEndpoint()</span> <span class="pre">string</span></code></p>
<p>The url of the websockets Endpoint for this node.</p>
</div>
<div class="section" id="resolvepath">
<h4>ResolvePath<a class="headerlink" href="#resolvepath" title="Permalink to this headline"></a></h4>
<p><code class="docutils literal notranslate"><span class="pre">ResolvePath(x</span> <span class="pre">string)</span> <span class="pre">string</span></code></p>
<p>Resolves a path within the DataDir.</p>
</div>
</div>
<div class="section" id="logger">
<h3>Logger<a class="headerlink" href="#logger" title="Permalink to this headline"></a></h3>
<p>The Logger object is injected by the <code class="docutils literal notranslate"><span class="pre">Initialize()</span></code> function. It implements
logging based on the interfaces of <a class="reference external" href="https://github.com/inconshreveable/log15">Log15</a>.</p>
</div>
</div>
</div>
</div>
</div>
<footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
<a href="version.html" class="btn btn-neutral float-left" title="Version" 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/>
<div role="contentinfo">
<p>&#169; 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>

185
docs/_build/html/build.html vendored Normal file
View File

@ -0,0 +1,185 @@
<!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>Build and Deploy &mdash; 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="Building a Custom Plugin" href="custom.html" />
<link rel="prev" title="Install" href="install.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>
</ul>
<p class="caption"><span class="caption-text">Tutorials</span></p>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="install.html">Install</a></li>
<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>
</li>
<li class="toctree-l1"><a class="reference internal" href="custom.html">Building a Custom Plugin</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="version.html">Version</a></li>
<li class="toctree-l1"><a class="reference internal" href="api.html">API</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="hooks.html">Selected Plugin Hooks</a></li>
<li class="toctree-l1"><a class="reference internal" href="hook_writing.html">Hook Writing Guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="core_restricted.html">PluGeth-utils Subpackages</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> &raquo;</li>
<li>Build and Deploy</li>
<li class="wy-breadcrumbs-aside">
<a href="_sources/build.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="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="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>
<p>If you are ready to start building your own plugins go ahead and start here.</p>
<div class="section" id="setting-up-the-environment">
<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>
</div>
<p>PluGeth is an application built in three seperate repositories.</p>
<ul class="simple">
<li><p><a class="reference external" href="https://github.com/openrelayxyz/plugeth">PluGeth</a></p></li>
<li><p><a class="reference external" href="https://github.com/openrelayxyz/plugeth-utils">PluGeth-Utils</a></p></li>
<li><p><a class="reference external" href="https://github.com/openrelayxyz/plugeth-plugins">PluGeth-Plugins</a></p></li>
</ul>
<p>For our purposed here you will only need to clone Plugeth and Plugeth-Plugins. Once you have them cloned you are ready to begin. First we need to build geth though the PluGeth project. Navigate to <code class="docutils literal notranslate"><span class="pre">plugeth/cmd/geth</span></code> and run:</p>
<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>$ go get
</pre></div>
</div>
<p>This will download all dependencies needed for the project. This process will take a moment or two the first time through. Next run:</p>
<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>$ go build
</pre></div>
</div>
<p>Once this is complete you should see a <code class="docutils literal notranslate"><span class="pre">.ethereum</span></code> folder in your home directory.</p>
<p>At this point you are ready to start downloading local ethereum nodes. In order to do so, from <code class="docutils literal notranslate"><span class="pre">plugeth/cmd/geth</span></code> run:</p>
<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>$ ./geth
</pre></div>
</div>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p><code class="docutils literal notranslate"><span class="pre">./geth</span></code> is the primary command to build a <em>Mainnet</em> node. Building a mainnet node requires at least 8 GB RAM, 2 CPUs, and 350 GB of SSD disks. However, dozens of available flags will change the behavior of whichever network you choose to connect to. <code class="docutils literal notranslate"><span class="pre">--help</span></code> is your friend.</p>
</div>
</div>
<div class="section" id="build-a-plugin">
<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>For the sake of this tutorial we will be building the Hello plugin. 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>
</div>
<p>This will compile the plugin and produce a <code class="docutils literal notranslate"><span class="pre">hello.so</span></code> file. Move <code class="docutils literal notranslate"><span class="pre">hello.so</span></code> into <code class="docutils literal notranslate"><span class="pre">~/.ethereum/plugins</span></code> . In order to use this plugin geth will need to be started with a <code class="docutils literal notranslate"><span class="pre">http.api=mymamespace</span></code> flag. Additionally you will need to include a <code class="docutils literal notranslate"><span class="pre">--http</span></code> flag in order to access the standard json rpc methods.</p>
<p>Once geth has started you should see that the first <code class="docutils literal notranslate"><span class="pre">INFO</span></code> log reads: <code class="docutils literal notranslate"><span class="pre">initialized</span> <span class="pre">hello</span></code> . A new json rpc method, called hello, has been been appended to the list of available json rpc methods. In order to access this method you will need to <code class="docutils literal notranslate"><span class="pre">curl</span></code> into the network with this command:</p>
<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>$ curl <span class="m">127</span>.0.0.1:8545 -H <span class="s2">&quot;Content-Type: application/json&quot;</span> --data <span class="s1">&#39;{&quot;jsonrpc&quot;:&quot;2.0&quot;,&quot;method&quot;:&quot;mynamespace_hello&quot;,&quot;params&quot;:[],&quot;id&quot;:0}&#39;</span>
</pre></div>
</div>
<p>You should see that the network has responded with:</p>
<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span><span class="sb">``</span><span class="o">{</span><span class="s2">&quot;jsonrpc&quot;</span>:<span class="s2">&quot;2.0&quot;</span>,<span class="s2">&quot;id&quot;</span>:0,<span class="s2">&quot;result&quot;</span>:<span class="s2">&quot;Hello world&quot;</span><span class="o">}</span><span class="sb">``</span>
</pre></div>
</div>
<p>Congradulations. You have just built and run your first Plugeth plugin. From here you can follow the steps above to build any of the plugins you choose.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>Each plugin will vary in terms of the requirements to deploy. Refer to the documentation of the plugin itself in order to assure
that you know how to use it.</p>
</div>
</div>
</div>
</div>
</div>
<footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
<a href="install.html" class="btn btn-neutral float-left" title="Install" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
<a href="custom.html" class="btn btn-neutral float-right" title="Building a Custom Plugin" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
</div>
<hr/>
<div role="contentinfo">
<p>&#169; 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>

122
docs/_build/html/contact.html vendored Normal file
View File

@ -0,0 +1,122 @@
<!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>Get in touch with us &mdash; 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="prev" title="PluGeth-utils Subpackages" 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>
</ul>
<p class="caption"><span class="caption-text">Tutorials</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="install.html">Install</a></li>
<li class="toctree-l1"><a class="reference internal" href="build.html">Build and Deploy</a></li>
<li class="toctree-l1"><a class="reference internal" href="custom.html">Building a Custom Plugin</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="version.html">Version</a></li>
<li class="toctree-l1"><a class="reference internal" href="api.html">API</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="hooks.html">Selected Plugin Hooks</a></li>
<li class="toctree-l1"><a class="reference internal" href="hook_writing.html">Hook Writing Guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="core_restricted.html">PluGeth-utils Subpackages</a></li>
</ul>
<p class="caption"><span class="caption-text">Contact</span></p>
<ul class="current">
<li class="toctree-l1 current"><a class="current reference internal" href="#">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> &raquo;</li>
<li>Get in touch with us</li>
<li class="wy-breadcrumbs-aside">
<a href="_sources/contact.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="get-in-touch-with-us">
<span id="contact"></span><h1>Get in touch with us<a class="headerlink" href="#get-in-touch-with-us" title="Permalink to this headline"></a></h1>
<p>We want to hear from you! The best way to reach the PluGeth team is through our Discord server. Drop in, say hello, we are anxious to hear your ideas and help work through any problems you may be having.</p>
<p><a class="reference external" href="https://discord.gg/J3tQMWCVPn">Join our Discord</a></p>
</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="PluGeth-utils Subpackages" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
</div>
<hr/>
<div role="contentinfo">
<p>&#169; 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>

125
docs/_build/html/core_restricted.html vendored Normal file
View File

@ -0,0 +1,125 @@
<!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>PluGeth-utils Subpackages &mdash; 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="Hook Writing Guide" href="hook_writing.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>
</ul>
<p class="caption"><span class="caption-text">Tutorials</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="install.html">Install</a></li>
<li class="toctree-l1"><a class="reference internal" href="build.html">Build and Deploy</a></li>
<li class="toctree-l1"><a class="reference internal" href="custom.html">Building a Custom Plugin</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="version.html">Version</a></li>
<li class="toctree-l1"><a class="reference internal" href="api.html">API</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="hooks.html">Selected Plugin Hooks</a></li>
<li class="toctree-l1"><a class="reference internal" href="hook_writing.html">Hook Writing Guide</a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="#">PluGeth-utils Subpackages</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> &raquo;</li>
<li>PluGeth-utils Subpackages</li>
<li class="wy-breadcrumbs-aside">
<a href="_sources/core_restricted.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="plugeth-utils-subpackages">
<span id="core-restricted"></span><h1>PluGeth-utils Subpackages<a class="headerlink" href="#plugeth-utils-subpackages" title="Permalink to this headline"></a></h1>
<p>PluGeth-utils is separated into two main packages: core, and restricted.</p>
<p>The <cite>core</cite> package has been implemented by the Rivet team, and is licensed under the MIT license, allowing it to be used in open source and closed source plugins alike. Nearly all plugins will need to import plugeth-utils/core in order to</p>
<p>The <cite>restricted</cite> package copies code from the go-ethereum project, which means it must be licensed under the LGPL license. If you import plugeth-utils/restricted, you must be sure that your plugin complies with requirements of linking to LGPL code, which will usually require making your source code available to anyone you distribute the plugin to.</p>
</div>
</div>
</div>
<footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
<a href="hook_writing.html" class="btn btn-neutral float-left" title="Hook Writing Guide" 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>&#169; 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>

185
docs/_build/html/custom.html vendored Normal file
View File

@ -0,0 +1,185 @@
<!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>Building a Custom Plugin &mdash; 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="RPC Methods" href="RPC_method.html" />
<link rel="prev" title="Build and Deploy" href="build.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>
</ul>
<p class="caption"><span class="caption-text">Tutorials</span></p>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="install.html">Install</a></li>
<li class="toctree-l1"><a class="reference internal" href="build.html">Build and Deploy</a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="#">Building a Custom Plugin</a><ul>
<li class="toctree-l2"><a class="reference internal" href="RPC_method.html">RPC Methods</a></li>
<li class="toctree-l2"><a class="reference internal" href="subscription.html">Subscription</a></li>
<li class="toctree-l2"><a class="reference internal" href="tracer.html">Tracer</a></li>
<li class="toctree-l2"><a class="reference internal" href="#basic-implementation">Basic Implementation</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#package">Package</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>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#specialization">Specialization</a></li>
</ul>
</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="version.html">Version</a></li>
<li class="toctree-l1"><a class="reference internal" href="api.html">API</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="hooks.html">Selected Plugin Hooks</a></li>
<li class="toctree-l1"><a class="reference internal" href="hook_writing.html">Hook Writing Guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="core_restricted.html">PluGeth-utils Subpackages</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> &raquo;</li>
<li>Building a Custom Plugin</li>
<li class="wy-breadcrumbs-aside">
<a href="_sources/custom.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="building-a-custom-plugin">
<span id="custom"></span><h1>Building a Custom Plugin<a class="headerlink" href="#building-a-custom-plugin" title="Permalink to this headline"></a></h1>
<div class="toctree-wrapper compound">
</div>
<p>Before setting out to build a plugin it will be helpful to be familiar with the <a class="reference internal" href="types.html#types"><span class="std std-ref">Basic Types of Plugins</span></a>. deifferent plugins will require different implimentation.</p>
<div class="section" id="basic-implementation">
<h2>Basic Implementation<a class="headerlink" href="#basic-implementation" title="Permalink to this headline"></a></h2>
<p>In general, no matter which type of plugin you intend to build, all will share some common aspects.</p>
<div class="section" id="package">
<h3>Package<a class="headerlink" href="#package" title="Permalink to this headline"></a></h3>
<p>Any plugin will need its own package located in the Plugeth-Plugins packages directory. The package will need to include a main.go from which the .so file will be built. The package and main file should share the same name and the name should be a word that describes the basic functionality of the plugin.</p>
</div>
<div class="section" id="initialize">
<h3>Initialize<a class="headerlink" href="#initialize" title="Permalink to this headline"></a></h3>
<p>Most plugins will need to be initialized with an Initialize function. The initialize function will need to be passed at least three arguments: a cli.Context, core.PluginLoader, and a core.Logger.</p>
<p>And so, all plugins could have an intial template that looks something like this:</p>
<div class="highlight-Go notranslate"><div class="highlight"><pre><span></span><span class="kn">package</span> <span class="nx">main</span>
<span class="kn">import</span> <span class="p">(</span>
<span class="s">&quot;github.com/openrelayxyz/plugeth-utils/core&quot;</span>
<span class="s">&quot;gopkg.in/urfave/cli.v1&quot;</span>
<span class="p">)</span>
<span class="kd">var</span> <span class="nx">log</span> <span class="nx">core</span><span class="p">.</span><span class="nx">Logger</span>
<span class="kd">func</span> <span class="nx">Initialize</span><span class="p">(</span><span class="nx">ctx</span> <span class="o">*</span><span class="nx">cli</span><span class="p">.</span><span class="nx">Context</span><span class="p">,</span> <span class="nx">loader</span> <span class="nx">core</span><span class="p">.</span><span class="nx">PluginLoader</span><span class="p">,</span> <span class="nx">logger</span> <span class="nx">core</span><span class="p">.</span><span class="nx">Logger</span><span class="p">)</span> <span class="p">{</span>
<span class="nx">log</span> <span class="p">=</span> <span class="nx">logger</span>
<span class="nx">log</span><span class="p">.</span><span class="nx">Info</span><span class="p">(</span><span class="s">&quot;loaded New Custom Plugin&quot;</span><span class="p">)</span>
<span class="p">}</span>
</pre></div>
</div>
</div>
<div class="section" id="initializenode">
<h3>InitializeNode<a class="headerlink" href="#initializenode" title="Permalink to this headline"></a></h3>
<p>Many plugins will make use of the InitializeNode function. Implimentation will look like so:</p>
<div class="highlight-Go notranslate"><div class="highlight"><pre><span></span><span class="kd">func</span> <span class="nx">InitializeNode</span><span class="p">(</span><span class="nx">stack</span> <span class="nx">core</span><span class="p">.</span><span class="nx">Node</span><span class="p">,</span> <span class="nx">b</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">backend</span> <span class="p">=</span> <span class="nx">b</span>
<span class="nx">log</span><span class="p">.</span><span class="nx">Info</span><span class="p">(</span><span class="s">&quot;Initialized node and backend&quot;</span><span class="p">)</span>
<span class="p">}</span>
</pre></div>
</div>
<p>This is called as soon as the Geth node is initialized. The core.Node object represents the running node with p2p and RPC capabilities, while the Backend gives you access to blocks and other data you may need to access.</p>
</div>
</div>
<div class="section" id="specialization">
<h2>Specialization<a class="headerlink" href="#specialization" title="Permalink to this headline"></a></h2>
<p>From this point implimentation becomes more specialized to the particular plugin type. Continue from here for specific instructions for the following plugins:</p>
<ul class="simple">
<li><p><a class="reference internal" href="RPC_method.html#rpc-method"><span class="std std-ref">RPC Methods</span></a></p></li>
<li><p><a class="reference internal" href="subscription.html#subscription"><span class="std std-ref">Subscription</span></a></p></li>
<li><p><a class="reference internal" href="tracer.html#tracer"><span class="std std-ref">Tracer</span></a></p></li>
</ul>
</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 and Deploy" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
<a href="RPC_method.html" class="btn btn-neutral float-right" title="RPC Methods" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
</div>
<hr/>
<div role="contentinfo">
<p>&#169; 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>

119
docs/_build/html/genindex.html vendored Normal file
View File

@ -0,0 +1,119 @@
<!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>Index &mdash; 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="#" />
<link rel="search" title="Search" href="search.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>
</ul>
<p class="caption"><span class="caption-text">Tutorials</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="install.html">Install</a></li>
<li class="toctree-l1"><a class="reference internal" href="build.html">Build and Deploy</a></li>
<li class="toctree-l1"><a class="reference internal" href="custom.html">Building a Custom Plugin</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="version.html">Version</a></li>
<li class="toctree-l1"><a class="reference internal" href="api.html">API</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="hooks.html">Selected Plugin Hooks</a></li>
<li class="toctree-l1"><a class="reference internal" href="hook_writing.html">Hook Writing Guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="core_restricted.html">PluGeth-utils Subpackages</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> &raquo;</li>
<li>Index</li>
<li class="wy-breadcrumbs-aside">
</li>
</ul>
<hr/>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<h1 id="index">Index</h1>
<div class="genindex-jumpbox">
</div>
</div>
</div>
<footer>
<hr/>
<div role="contentinfo">
<p>&#169; 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>

126
docs/_build/html/hook_writing.html vendored Normal file
View File

@ -0,0 +1,126 @@
<!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>Hook Writing Guide &mdash; 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="PluGeth-utils Subpackages" href="core_restricted.html" />
<link rel="prev" title="Selected Plugin Hooks" href="hooks.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>
</ul>
<p class="caption"><span class="caption-text">Tutorials</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="install.html">Install</a></li>
<li class="toctree-l1"><a class="reference internal" href="build.html">Build and Deploy</a></li>
<li class="toctree-l1"><a class="reference internal" href="custom.html">Building a Custom Plugin</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="version.html">Version</a></li>
<li class="toctree-l1"><a class="reference internal" href="api.html">API</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="hooks.html">Selected Plugin Hooks</a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="#">Hook Writing Guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="core_restricted.html">PluGeth-utils Subpackages</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> &raquo;</li>
<li>Hook Writing Guide</li>
<li class="wy-breadcrumbs-aside">
<a href="_sources/hook_writing.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="hook-writing-guide">
<span id="hook-writing"></span><h1>Hook Writing Guide<a class="headerlink" href="#hook-writing-guide" title="Permalink to this headline"></a></h1>
<div class="admonition-todo admonition" id="id1">
<p class="admonition-title">Todo</p>
<p>Austin: guide to writing plugin hooks</p>
</div>
</div>
</div>
</div>
<footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
<a href="hooks.html" class="btn btn-neutral float-left" title="Selected Plugin Hooks" 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="PluGeth-utils Subpackages" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
</div>
<hr/>
<div role="contentinfo">
<p>&#169; 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>

218
docs/_build/html/hooks.html vendored Normal file
View File

@ -0,0 +1,218 @@
<!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>Selected Plugin Hooks &mdash; 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="Hook Writing Guide" href="hook_writing.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>
</ul>
<p class="caption"><span class="caption-text">Tutorials</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="install.html">Install</a></li>
<li class="toctree-l1"><a class="reference internal" href="build.html">Build and Deploy</a></li>
<li class="toctree-l1"><a class="reference internal" href="custom.html">Building a Custom Plugin</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="version.html">Version</a></li>
<li class="toctree-l1"><a class="reference internal" href="api.html">API</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="#">Selected Plugin Hooks</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#plugin-hooks">Plugin Hooks</a></li>
<li class="toctree-l2"><a class="reference internal" href="#stateupdate">StateUpdate</a></li>
<li class="toctree-l2"><a class="reference internal" href="#appendancient">AppendAncient</a></li>
<li class="toctree-l2"><a class="reference internal" href="#getrpccalls">GetRPCCalls</a></li>
<li class="toctree-l2"><a class="reference internal" href="#preprocessblock">PreProcessBlock</a></li>
<li class="toctree-l2"><a class="reference internal" href="#preprocesstransaction">PreProcessTransaction</a></li>
<li class="toctree-l2"><a class="reference internal" href="#blockprocessingerror">BlockProcessingError</a></li>
<li class="toctree-l2"><a class="reference internal" href="#newhead">NewHead</a></li>
<li class="toctree-l2"><a class="reference internal" href="#newsideblock">NewSideBlock</a></li>
<li class="toctree-l2"><a class="reference internal" href="#reorg">Reorg</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="hook_writing.html">Hook Writing Guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="core_restricted.html">PluGeth-utils Subpackages</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> &raquo;</li>
<li>Selected Plugin Hooks</li>
<li class="wy-breadcrumbs-aside">
<a href="_sources/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="selected-plugin-hooks">
<span id="hooks"></span><h1>Selected Plugin Hooks<a class="headerlink" href="#selected-plugin-hooks" title="Permalink to this headline"></a></h1>
<div class="section" id="plugin-hooks">
<h2>Plugin Hooks<a class="headerlink" href="#plugin-hooks" title="Permalink to this headline"></a></h2>
<p>Plugeth provides several <a class="reference internal" href="#hooks"><span class="std std-ref">Selected Plugin Hooks</span></a> from which the plugin can capture data from Geth. Additionally in the case of <strong>subcommands</strong> the provided hooks are designed to change the behavior of Geth.</p>
<p>Hooks are called from functions within the plugin. For example, if we wanted to bring in data from the StateUpdate hook. We would impliment it like so:
(from <a class="reference external" href="https://github.com/openrelayxyz/plugeth-plugins/tree/master/packages/blockupdates">blockupdates</a>)</p>
<div class="highlight-Go notranslate"><div class="highlight"><pre><span></span><span class="kd">func</span> <span class="nx">StateUpdate</span><span class="p">(</span><span class="nx">blockRoot</span> <span class="nx">core</span><span class="p">.</span><span class="nx">Hash</span><span class="p">,</span> <span class="nx">parentRoot</span> <span class="nx">core</span><span class="p">.</span><span class="nx">Hash</span><span class="p">,</span> <span class="nx">destructs</span> <span class="kd">map</span><span class="p">[</span><span class="nx">core</span><span class="p">.</span><span class="nx">Hash</span><span class="p">]</span><span class="kd">struct</span><span class="p">{},</span> <span class="nx">accounts</span> <span class="kd">map</span><span class="p">[</span><span class="nx">core</span><span class="p">.</span><span class="nx">Hash</span><span class="p">][]</span><span class="kt">byte</span><span class="p">,</span> <span class="nx">storage</span> <span class="kd">map</span><span class="p">[</span><span class="nx">core</span><span class="p">.</span><span class="nx">Hash</span><span class="p">]</span><span class="kd">map</span><span class="p">[</span><span class="nx">core</span><span class="p">.</span><span class="nx">Hash</span><span class="p">][]</span><span class="kt">byte</span><span class="p">,</span> <span class="nx">codeUpdates</span> <span class="kd">map</span><span class="p">[</span><span class="nx">core</span><span class="p">.</span><span class="nx">Hash</span><span class="p">][]</span><span class="kt">byte</span><span class="p">)</span> <span class="p">{</span>
<span class="nx">su</span> <span class="o">:=</span> <span class="o">&amp;</span><span class="nx">stateUpdate</span><span class="p">{</span>
<span class="nx">Destructs</span><span class="p">:</span> <span class="nx">destructs</span><span class="p">,</span>
<span class="nx">Accounts</span><span class="p">:</span> <span class="nx">accounts</span><span class="p">,</span>
<span class="nx">Storage</span><span class="p">:</span> <span class="nx">storage</span><span class="p">,</span>
<span class="nx">Code</span><span class="p">:</span> <span class="nx">codeUpdates</span><span class="p">,</span>
<span class="p">}</span>
<span class="nx">cache</span><span class="p">.</span><span class="nx">Add</span><span class="p">(</span><span class="nx">blockRoot</span><span class="p">,</span> <span class="nx">su</span><span class="p">)</span>
<span class="nx">data</span><span class="p">,</span> <span class="nx">_</span> <span class="o">:=</span> <span class="nx">rlp</span><span class="p">.</span><span class="nx">EncodeToBytes</span><span class="p">(</span><span class="nx">su</span><span class="p">)</span>
<span class="nx">backend</span><span class="p">.</span><span class="nx">ChainDb</span><span class="p">().</span><span class="nx">Put</span><span class="p">(</span><span class="nb">append</span><span class="p">([]</span><span class="nb">byte</span><span class="p">(</span><span class="s">&quot;su&quot;</span><span class="p">),</span> <span class="nx">blockRoot</span><span class="p">.</span><span class="nx">Bytes</span><span class="p">()</span><span class="o">...</span><span class="p">),</span> <span class="nx">data</span><span class="p">)</span>
<span class="p">}</span>
</pre></div>
</div>
<p>Many hooks can be deployed in an one plugin as is the case with the <strong>BlockUpdater</strong> plugin.</p>
</div>
<div class="section" id="stateupdate">
<h2>StateUpdate<a class="headerlink" href="#stateupdate" title="Permalink to this headline"></a></h2>
<p><strong>Function Signature</strong>:<code class="docutils literal notranslate"><span class="pre">func(root</span> <span class="pre">common.Hash,</span> <span class="pre">parentRoot</span> <span class="pre">common.Hash,</span> <span class="pre">destructs</span> <span class="pre">map[common.Hash]struct{},</span> <span class="pre">accounts</span> <span class="pre">map[common.Hash][]byte,</span> <span class="pre">storage</span> <span class="pre">map[common.Hash]map[common.Hash][]byte)</span></code></p>
<p>The state update plugin provides a snapshot of the state subsystem in the form of a a stateUpdate object. The stateUpdate object contains all information transformed by a transaction but not the transaction itself.</p>
<p>Invoked for each new block, StateUpdate provides the changes to the blockchain state. root corresponds to the state root of the new block. parentRoot corresponds to the state root of the parent block. destructs serves as a set of accounts that self-destructed in this block. accounts maps the hash of each account address to the SlimRLP encoding of the account data. storage maps the hash of each account to a map of that account’s stored data.</p>
<div class="admonition warning">
<p class="admonition-title">Warning</p>
<p>StateUpdate is only called if Geth is running with
<code class="docutils literal notranslate"><span class="pre">-snapshots=true</span></code>. This is the default behavior for Geth, but if you are explicitly running with <code class="docutils literal notranslate"><span class="pre">--snapshot=false</span></code> this function will not be invoked.</p>
</div>
</div>
<div class="section" id="appendancient">
<h2>AppendAncient<a class="headerlink" href="#appendancient" title="Permalink to this headline"></a></h2>
<p><strong>Function Signature</strong>:<code class="docutils literal notranslate"><span class="pre">func(number</span> <span class="pre">uint64,</span> <span class="pre">hash,</span> <span class="pre">header,</span> <span class="pre">body,</span> <span class="pre">receipts,</span> <span class="pre">td</span> <span class="pre">[]byte)</span></code></p>
<p>Invoked when the freezer moves a block from LevelDB to the ancients database. <code class="docutils literal notranslate"><span class="pre">number</span></code> is the number of the block. <code class="docutils literal notranslate"><span class="pre">hash</span></code> is the 32 byte hash of the block as a raw <code class="docutils literal notranslate"><span class="pre">[]byte</span></code>. <code class="docutils literal notranslate"><span class="pre">header</span></code>, <code class="docutils literal notranslate"><span class="pre">body</span></code>, and <code class="docutils literal notranslate"><span class="pre">receipts</span></code> are the RLP encoded versions of their respective block elements. <code class="docutils literal notranslate"><span class="pre">td</span></code> is the byte encoded total difficulty of the block.</p>
</div>
<div class="section" id="getrpccalls">
<h2>GetRPCCalls<a class="headerlink" href="#getrpccalls" title="Permalink to this headline"></a></h2>
<p><strong>Function Signature</strong>:<code class="docutils literal notranslate"><span class="pre">func(string,</span> <span class="pre">string,</span> <span class="pre">string)</span></code></p>
<p>Invoked when the RPC handler registers a method call. Returns the call <code class="docutils literal notranslate"><span class="pre">id</span></code>, method <code class="docutils literal notranslate"><span class="pre">name</span></code>, and any <code class="docutils literal notranslate"><span class="pre">params</span></code> that may have been passed in.</p>
<div class="admonition-todo admonition" id="id1">
<p class="admonition-title">Todo</p>
<p>missing a couple of hooks</p>
</div>
</div>
<div class="section" id="preprocessblock">
<h2>PreProcessBlock<a class="headerlink" href="#preprocessblock" title="Permalink to this headline"></a></h2>
<p><strong>Function Signature</strong>:<code class="docutils literal notranslate"><span class="pre">func(*types.Block)</span></code></p>
<p>Invoked before the transactions of a block are processed. Returns a block object.</p>
</div>
<div class="section" id="preprocesstransaction">
<h2>PreProcessTransaction<a class="headerlink" href="#preprocesstransaction" title="Permalink to this headline"></a></h2>
<p><strong>Function Signature</strong>:<code class="docutils literal notranslate"><span class="pre">func(*types.Transaction,</span> <span class="pre">*types.Block,</span> <span class="pre">int)</span></code></p>
<p>Invoked before each individual transaction of a block is processed. Returns a transaction, block, and index number.</p>
</div>
<div class="section" id="blockprocessingerror">
<h2>BlockProcessingError<a class="headerlink" href="#blockprocessingerror" title="Permalink to this headline"></a></h2>
<p><strong>Function Signature</strong>:<code class="docutils literal notranslate"><span class="pre">func(*types.Transaction,</span> <span class="pre">*types.Block,</span> <span class="pre">error)</span></code></p>
<p>Invoked if an error occurs while processing a transaction. This only applies to errors that would unvalidate the block were this transaction is included not errors such as reverts or opcode errors. Returns a transaction, block, and error.</p>
</div>
<div class="section" id="newhead">
<h2>NewHead<a class="headerlink" href="#newhead" title="Permalink to this headline"></a></h2>
<p><strong>Function Signature</strong>:<code class="docutils literal notranslate"><span class="pre">func(*types.Block,</span> <span class="pre">common.Hash,</span> <span class="pre">[]*types.Log)</span></code></p>
<p>Invoked when a new block becomes the canonical latest block. Returns a block, hash, and log.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>If severtal blocks are processed in a group (such as
during a reorg) this may not be called for each block. You should track the prior latest head if you need to process intermediate blocks.</p>
</div>
</div>
<div class="section" id="newsideblock">
<h2>NewSideBlock<a class="headerlink" href="#newsideblock" title="Permalink to this headline"></a></h2>
<p><strong>Function Signature</strong>:<code class="docutils literal notranslate"><span class="pre">func(*types.Block,</span> <span class="pre">common.Hash,</span> <span class="pre">[]*types.Log)</span></code></p>
<p>Invoked when a block is side-chained. Returns a block, has, and logs.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>Blocks passed to this method are non-canonical blocks.</p>
</div>
</div>
<div class="section" id="reorg">
<h2>Reorg<a class="headerlink" href="#reorg" title="Permalink to this headline"></a></h2>
<p><strong>Function Signature</strong>:<code class="docutils literal notranslate"><span class="pre">func(common</span> <span class="pre">*types.Block,</span> <span class="pre">oldChain,</span> <span class="pre">newChain</span> <span class="pre">types.Blocks)</span></code></p>
<p>Invoked when a chain reorg occurs, that is; at least one block is removed and one block is added. (<code class="docutils literal notranslate"><span class="pre">oldChain</span></code> is a list of removed blocks, <code class="docutils literal notranslate"><span class="pre">newChain</span></code> is a list of newliy added blocks, and <code class="docutils literal notranslate"><span class="pre">common</span></code> is the latest block that is an ancestor to both oldChain and newChain.) Returns a block, a list of old blocks, and a list of new blocks.</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="hook_writing.html" class="btn btn-neutral float-right" title="Hook Writing Guide" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
</div>
<hr/>
<div role="contentinfo">
<p>&#169; 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>

172
docs/_build/html/index.html vendored Normal file
View File

@ -0,0 +1,172 @@
<!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>PluGeth &mdash; 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="Project Design" href="project.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="#" 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>
</ul>
<p class="caption"><span class="caption-text">Tutorials</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="install.html">Install</a></li>
<li class="toctree-l1"><a class="reference internal" href="build.html">Build and Deploy</a></li>
<li class="toctree-l1"><a class="reference internal" href="custom.html">Building a Custom Plugin</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="version.html">Version</a></li>
<li class="toctree-l1"><a class="reference internal" href="api.html">API</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="hooks.html">Selected Plugin Hooks</a></li>
<li class="toctree-l1"><a class="reference internal" href="hook_writing.html">Hook Writing Guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="core_restricted.html">PluGeth-utils Subpackages</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="#">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="#" class="icon icon-home"></a> &raquo;</li>
<li>PluGeth</li>
<li class="wy-breadcrumbs-aside">
<a href="_sources/index.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="plugeth">
<h1>PluGeth<a class="headerlink" href="#plugeth" title="Permalink to this headline"></a></h1>
<p>PluGeth is a fork of the Go Ethereum Client, <a class="reference external" href="https://geth.ethereum.org/">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.</p>
<div class="section" id="from-here">
<h2>From Here:<a class="headerlink" href="#from-here" title="Permalink to this headline"></a></h2>
<ul class="simple">
<li><p>Ready for an overview of the project and some context? <a class="reference internal" href="project.html#project"><span class="std std-ref">Project Design</span></a></p></li>
<li><p>If your goal is to run existing plugns without sourcecode: <a class="reference internal" href="install.html#install"><span class="std std-ref">Install</span></a></p></li>
<li><p>If your goal is to build and deploy existing plugins or make custom plugins: <a class="reference internal" href="build.html#build"><span class="std std-ref">Build and Deploy</span></a></p></li>
</ul>
<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">
<h3>Table of Contents<a class="headerlink" href="#table-of-contents" title="Permalink to this headline"></a></h3>
<div class="toctree-wrapper compound">
<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>
</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="install.html">Install</a></li>
<li class="toctree-l1"><a class="reference internal" href="build.html">Build and Deploy</a></li>
<li class="toctree-l1"><a class="reference internal" href="custom.html">Building a Custom Plugin</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="version.html">Version</a></li>
<li class="toctree-l1"><a class="reference internal" href="api.html">API</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="hooks.html">Selected Plugin Hooks</a></li>
<li class="toctree-l1"><a class="reference internal" href="hook_writing.html">Hook Writing Guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="core_restricted.html">PluGeth-utils Subpackages</a></li>
</ul>
</div>
<div class="toctree-wrapper compound">
<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>
</div>
</div>
</div>
</div>
<footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
<a href="project.html" class="btn btn-neutral float-right" title="Project Design" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
</div>
<hr/>
<div role="contentinfo">
<p>&#169; 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>

135
docs/_build/html/install.html vendored Normal file
View File

@ -0,0 +1,135 @@
<!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>Install &mdash; 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="Build and Deploy" href="build.html" />
<link rel="prev" title="Basic Types of Plugins" href="types.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>
</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="#">Install</a></li>
<li class="toctree-l1"><a class="reference internal" href="build.html">Build and Deploy</a></li>
<li class="toctree-l1"><a class="reference internal" href="custom.html">Building a Custom Plugin</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="version.html">Version</a></li>
<li class="toctree-l1"><a class="reference internal" href="api.html">API</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="hooks.html">Selected Plugin Hooks</a></li>
<li class="toctree-l1"><a class="reference internal" href="hook_writing.html">Hook Writing Guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="core_restricted.html">PluGeth-utils Subpackages</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> &raquo;</li>
<li>Install</li>
<li class="wy-breadcrumbs-aside">
<a href="_sources/install.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="install">
<span id="id1"></span><h1>Install<a class="headerlink" href="#install" title="Permalink to this headline"></a></h1>
<p>PluGeth provides a pre-built PluGeth-Geth node as well as pre-built plugins available for download.</p>
<p>First download the latest PluGeth <a class="reference external" href="https://github.com/openrelayxyz/plugeth/releases">binary release</a>.</p>
<div class="admonition-todo admonition" id="id2">
<p class="admonition-title">Todo</p>
<p>more language about installing download</p>
</div>
<p>Our curated list of plugin builds can be found <a class="reference external" href="https://www.youtube.com/watch?v=dQw4w9WgXcQ&amp;ab_channel=RickAstley">here</a></p>
<p>After downloading, move the .so files into the ~/.ethereum/plugins directory.</p>
<div class="admonition-todo admonition" id="id3">
<p class="admonition-title">Todo</p>
<p>Build a binary release so as to provide a usable
example. Maybe a different example than hello so that there are two generic cases for which there are tutorials. – or – We should provide examples of the common scenerios in which geth has to be started with flags or connected to with web sockets.</p>
</div>
</div>
</div>
</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="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/>
<div role="contentinfo">
<p>&#169; 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>

11
docs/_build/html/objects.inv vendored Normal file
View File

@ -0,0 +1,11 @@
# Sphinx inventory version 2
# Project: Plugeth
# Version:
# The remainder of this file is compressed using zlib.
xÚ…TËn<EFBFBD>0Ý߯°D·T궻6‘ÒH<C392>„n¢vyå SpclâGSþ¾Æ/Æ@Òsæœ9ã±™sssÁ ²#ÚtŸ;Ù’ú9gôã`F¾ÄäÁÇúD'†©. œ/Í}ÎqzŽ³ÕŸ¿ZÆ #ýWŸ£¢#·0q9#r.·Ò]Á<> •ÂÐÖàú
w`ÄHÛä•™<E280A2>X]ˆ²–9§7„
.
´Q¬5Е®E*¸7ܺ:Cm ãš<ÚëDÛgÚÃq%ÔʾVµ€5R¼SÛj#Ç¢9<C2A2> ™3ÑJnÑUê™À²µ“U˜¦$íA0ÑÁßRœÐà{¿|ž)Ÿ/¯Š™¥ êã<>ÿÍ!ägdÞYÖÁ^œ­vòjAêÄ}£–Þv ƒõ#pH3vÇór<C3B3>…­NÓ9V­s‰>h$ñ
GÊyÉòP<1A>
^î3]‰;ÊîàJ¦¹N‰PúAv–C¼œÉ7~á’v p7E"÷¾ò»‡”«åN[¨ŽìM%%CùCG(úÆü-hÖ‹‚¾Z"<22>ÉV²Îà?Ãif·þD9#5µxyfñf}VŽWGÞ¤¨r ¥<>,==ŸoÜ<6F>|Òöª[Å&Ã\h<18>*„ìe«ÑV¸¼ÚB:k£[=/…_F£›<C2A3>É^,S0‚0z«\-Kmâzá•1Š¶åÓ H0~òߘ”}Í*ç ŠÜq RÍZòäòW|„IÖÒY´¬ÀcÙPzsK
n?BPð²f:‹Äý <>»

172
docs/_build/html/plugin_loader.html vendored Normal file
View File

@ -0,0 +1,172 @@
<!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 &mdash; 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="Selected Plugin Hooks" href="hooks.html" />
<link rel="prev" title="API" href="api.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>
</ul>
<p class="caption"><span class="caption-text">Tutorials</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="install.html">Install</a></li>
<li class="toctree-l1"><a class="reference internal" href="build.html">Build and Deploy</a></li>
<li class="toctree-l1"><a class="reference internal" href="custom.html">Building a Custom Plugin</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="version.html">Version</a></li>
<li class="toctree-l1"><a class="reference internal" href="api.html">API</a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="#">Plugin Loader</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#lookup">Lookup</a></li>
<li class="toctree-l2"><a class="reference internal" href="#getfeed">GetFeed</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="hooks.html">Selected Plugin Hooks</a></li>
<li class="toctree-l1"><a class="reference internal" href="hook_writing.html">Hook Writing Guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="core_restricted.html">PluGeth-utils Subpackages</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> &raquo;</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>
<p>The Plugin Loader is provided to each Plugin through the Initialize()``
function. It provides plugins with:</p>
<div class="section" id="lookup">
<h2>Lookup<a class="headerlink" href="#lookup" title="Permalink to this headline"></a></h2>
<p><code class="docutils literal notranslate"><span class="pre">Lookup(name</span> <span class="pre">string,</span> <span class="pre">validate</span> <span class="pre">func(interface{})</span> <span class="pre">bool)</span> <span class="pre">[]interface{}</span></code></p>
<p>Returns a list of values from plugins identified by <code class="docutils literal notranslate"><span class="pre">name</span></code>, which match the
provided <code class="docutils literal notranslate"><span class="pre">validate</span></code> predicate. For example:</p>
<div class="highlight-go notranslate"><div class="highlight"><pre><span></span><span class="nx">pl</span><span class="p">.</span><span class="nx">Lookup</span><span class="p">(</span><span class="s">&quot;Version&quot;</span><span class="p">,</span> <span class="kd">func</span><span class="p">(</span><span class="nx">item</span> <span class="kd">interface</span><span class="p">{})</span> <span class="kt">bool</span> <span class="p">{</span>
<span class="nx">_</span><span class="p">,</span> <span class="nx">ok</span> <span class="o">:=</span> <span class="nx">item</span><span class="p">.(</span><span class="kt">int</span><span class="p">)</span>
<span class="k">return</span> <span class="nx">ok</span>
<span class="p">})</span>
</pre></div>
</div>
<p>Would return a list of <code class="docutils literal notranslate"><span class="pre">int</span></code> objects named <code class="docutils literal notranslate"><span class="pre">Version</span></code> in any loaded plugins.
This can enable Plugins to interact with each other, accessing values and
functions implemented in other plugins.</p>
</div>
<div class="section" id="getfeed">
<h2>GetFeed<a class="headerlink" href="#getfeed" title="Permalink to this headline"></a></h2>
<p><code class="docutils literal notranslate"><span class="pre">GetFeed()</span> <span class="pre">Feed</span></code></p>
<p>Returns a new feed that the plugin can used for publish/subscribe models.</p>
<p>For example:</p>
<div class="highlight-go notranslate"><div class="highlight"><pre><span></span><span class="nx">feed</span> <span class="o">:=</span> <span class="nx">pl</span><span class="p">.</span><span class="nx">GetFeed</span><span class="p">()</span>
<span class="k">go</span> <span class="kd">func</span><span class="p">()</span> <span class="p">{</span>
<span class="nx">ch</span> <span class="o">:=</span> <span class="nb">make</span><span class="p">(</span><span class="kd">chan</span> <span class="kt">string</span><span class="p">)</span>
<span class="nx">sub</span> <span class="o">:=</span> <span class="nx">feed</span><span class="p">.</span><span class="nx">Subscribe</span><span class="p">(</span><span class="nx">ch</span><span class="p">)</span>
<span class="k">for</span> <span class="p">{</span>
<span class="k">select</span> <span class="p">{</span>
<span class="k">case</span> <span class="nx">item</span> <span class="o">:=</span> <span class="o">&lt;-</span><span class="nx">ch</span><span class="p">:</span>
<span class="c1">// Do something with item</span>
<span class="k">case</span> <span class="nx">err</span> <span class="o">:=</span> <span class="p">&lt;</span><span class="nx">sub</span><span class="p">.</span><span class="nx">Err</span><span class="p">():</span>
<span class="nx">log</span><span class="p">.</span><span class="nx">Error</span><span class="p">(</span><span class="s">&quot;An error has occurred&quot;</span><span class="p">,</span> <span class="s">&quot;err&quot;</span><span class="p">,</span> <span class="nx">err</span><span class="p">)</span>
<span class="nx">sub</span><span class="p">.</span><span class="nx">Unsubscribe</span><span class="p">()</span>
<span class="nb">close</span><span class="p">(</span><span class="nx">ch</span><span class="p">)</span>
<span class="k">return</span>
<span class="p">}</span>
<span class="p">}</span>
<span class="p">}()</span>
<span class="nx">feed</span><span class="p">.</span><span class="nx">Send</span><span class="p">(</span><span class="s">&quot;hello&quot;</span><span class="p">)</span>
<span class="nx">feed</span><span class="p">.</span><span class="nx">Send</span><span class="p">(</span><span class="s">&quot;world&quot;</span><span class="p">)</span>
</pre></div>
</div>
<p>Note that you can send any type through a feed, but the subscribed channel and
sent objects must be of matching types.</p>
</div>
</div>
</div>
</div>
<footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
<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>
<a href="hooks.html" class="btn btn-neutral float-right" title="Selected 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>&#169; 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>

161
docs/_build/html/project.html vendored Normal file
View File

@ -0,0 +1,161 @@
<!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>Project Design &mdash; 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="Basic Types of Plugins" href="types.html" />
<link rel="prev" title="PluGeth" href="index.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 class="current">
<li class="toctree-l1 current"><a class="current reference internal" href="#">Project Design</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#design-goals">Design Goals</a></li>
<li class="toctree-l2"><a class="reference internal" href="#three-repositories">Three Repositories</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#plugeth">PluGeth</a></li>
<li class="toctree-l3"><a class="reference internal" href="#plugeth-utils">PluGeth-Utils</a></li>
<li class="toctree-l3"><a class="reference internal" href="#plugeth-plugins">PluGeth-Plugins</a><ul>
<li class="toctree-l4"><a class="reference internal" href="#dependency-scheme">Dependency Scheme</a></li>
</ul>
</li>
</ul>
</li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="types.html">Basic Types of Plugins</a></li>
</ul>
<p class="caption"><span class="caption-text">Tutorials</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="install.html">Install</a></li>
<li class="toctree-l1"><a class="reference internal" href="build.html">Build and Deploy</a></li>
<li class="toctree-l1"><a class="reference internal" href="custom.html">Building a Custom Plugin</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="version.html">Version</a></li>
<li class="toctree-l1"><a class="reference internal" href="api.html">API</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="hooks.html">Selected Plugin Hooks</a></li>
<li class="toctree-l1"><a class="reference internal" href="hook_writing.html">Hook Writing Guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="core_restricted.html">PluGeth-utils Subpackages</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> &raquo;</li>
<li>Project Design</li>
<li class="wy-breadcrumbs-aside">
<a href="_sources/project.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="project-design">
<span id="project"></span><h1>Project Design<a class="headerlink" href="#project-design" title="Permalink to this headline"></a></h1>
<div class="section" id="design-goals">
<h2>Design Goals<a class="headerlink" href="#design-goals" title="Permalink to this headline"></a></h2>
<p>Upstream Geth exists primarily to serve as a client for the Ethereum mainnet, though it also supports a number of popular testnets. Supporting the Ethereum mainnet is a big enough challenge in its own right that the Geth team generally avoids changes to support other networks, or to provide features only a small handful of users would be interested in.</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; 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>
<div class="section" id="three-repositories">
<h2>Three Repositories<a class="headerlink" href="#three-repositories" title="Permalink to this headline"></a></h2>
<p>PluGeth is an application built in three repositories:</p>
<div class="section" id="plugeth">
<h3><a class="reference external" href="https://github.com/openrelayxyz/plugeth">PluGeth</a><a class="headerlink" href="#plugeth" title="Permalink to this headline"></a></h3>
<p>The largest of the three Repositories, PluGeth is a fork of Geth which has been modified to enable a plugin architecture. The Plugin loader, wrappers, and hooks all reside in this repository.</p>
</div>
<div class="section" id="plugeth-utils">
<h3><a class="reference external" href="https://github.com/openrelayxyz/plugeth-utils">PluGeth-Utils</a><a class="headerlink" href="#plugeth-utils" title="Permalink to this headline"></a></h3>
<p>Utils are small packages used to develop PluGeth plugins without Geth dependencies. For a more detailed analysis of the reasons see :ref: <cite>core_resticted</cite>. Imports from Utils happen automatically and so most users need not clone a local version.</p>
</div>
<div class="section" id="plugeth-plugins">
<h3><a class="reference external" href="https://github.com/openrelayxyz/plugeth-plugins">PluGeth-Plugins</a><a class="headerlink" href="#plugeth-plugins" title="Permalink to this headline"></a></h3>
<p>The packages from which plugins are buile are stored here. This repository contains premade plugins as well as providing a location for storing new custom plugins.</p>
<div class="section" id="dependency-scheme">
<h4>Dependency Scheme<a class="headerlink" href="#dependency-scheme" title="Permalink to this headline"></a></h4>
<p><a class="reference internal" href="version.html#version"><span class="std std-ref">Version</span></a></p>
</div>
</div>
</div>
</div>
</div>
</div>
<footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
<a href="index.html" class="btn btn-neutral float-left" title="PluGeth" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
<a href="types.html" class="btn btn-neutral float-right" title="Basic Types of Plugins" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
</div>
<hr/>
<div role="contentinfo">
<p>&#169; 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>

134
docs/_build/html/search.html vendored Normal file
View File

@ -0,0 +1,134 @@
<!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>Search &mdash; 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>
<script src="_static/searchtools.js"></script>
<script src="_static/language_data.js"></script>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="#" />
</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="#" 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>
</ul>
<p class="caption"><span class="caption-text">Tutorials</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="install.html">Install</a></li>
<li class="toctree-l1"><a class="reference internal" href="build.html">Build and Deploy</a></li>
<li class="toctree-l1"><a class="reference internal" href="custom.html">Building a Custom Plugin</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="version.html">Version</a></li>
<li class="toctree-l1"><a class="reference internal" href="api.html">API</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="hooks.html">Selected Plugin Hooks</a></li>
<li class="toctree-l1"><a class="reference internal" href="hook_writing.html">Hook Writing Guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="core_restricted.html">PluGeth-utils Subpackages</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> &raquo;</li>
<li>Search</li>
<li class="wy-breadcrumbs-aside">
</li>
</ul>
<hr/>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<noscript>
<div id="fallback" class="admonition warning">
<p class="last">
Please activate JavaScript to enable the search functionality.
</p>
</div>
</noscript>
<div id="search-results">
</div>
</div>
</div>
<footer>
<hr/>
<div role="contentinfo">
<p>&#169; 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>
<script>
jQuery(function() { Search.loadIndex("searchindex.js"); });
</script>
<script id="searchindexloader"></script>
</body>
</html>

1
docs/_build/html/searchindex.js vendored Normal file
View File

File diff suppressed because one or more lines are too long

211
docs/_build/html/subscription.html vendored Normal file
View File

@ -0,0 +1,211 @@
<!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>Subscription &mdash; 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="Tracer" href="tracer.html" />
<link rel="prev" title="RPC Methods" href="RPC_method.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>
</ul>
<p class="caption"><span class="caption-text">Tutorials</span></p>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="install.html">Install</a></li>
<li class="toctree-l1"><a class="reference internal" href="build.html">Build and Deploy</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="custom.html">Building a Custom Plugin</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="RPC_method.html">RPC Methods</a></li>
<li class="toctree-l2 current"><a class="current reference internal" href="#">Subscription</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#getapis">GetAPIs</a></li>
<li class="toctree-l3"><a class="reference internal" href="#subscription-function">Subscription Function</a></li>
<li class="toctree-l3"><a class="reference internal" href="#access">Access</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="tracer.html">Tracer</a></li>
<li class="toctree-l2"><a class="reference internal" href="custom.html#basic-implementation">Basic Implementation</a></li>
<li class="toctree-l2"><a class="reference internal" href="custom.html#specialization">Specialization</a></li>
</ul>
</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="version.html">Version</a></li>
<li class="toctree-l1"><a class="reference internal" href="api.html">API</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="hooks.html">Selected Plugin Hooks</a></li>
<li class="toctree-l1"><a class="reference internal" href="hook_writing.html">Hook Writing Guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="core_restricted.html">PluGeth-utils Subpackages</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> &raquo;</li>
<li><a href="custom.html">Building a Custom Plugin</a> &raquo;</li>
<li>Subscription</li>
<li class="wy-breadcrumbs-aside">
<a href="_sources/subscription.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="subscription">
<span id="id1"></span><h1>Subscription<a class="headerlink" href="#subscription" title="Permalink to this headline"></a></h1>
<p>In addition to the initial template containing an intialize function, plugins providing <strong>Subscriptions</strong> will require two additional elements.</p>
<div class="section" id="getapis">
<h2>GetAPIs<a class="headerlink" href="#getapis" title="Permalink to this headline"></a></h2>
<p>A GetAPIs method is required in the body of the plugin in order to make the plugin available. The bulk of the implementation will be in the MyService struct. MyService should be a struct which includes two public functions.</p>
<div class="highlight-Go notranslate"><div class="highlight"><pre><span></span><span class="kd">type</span> <span class="nx">MyService</span> <span class="kd">struct</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="nx">stack</span> <span class="nx">core</span><span class="p">.</span><span class="nx">Node</span>
<span class="p">}</span>
<span class="kd">func</span> <span class="nx">GetAPIs</span><span class="p">(</span><span class="nx">stack</span> <span class="nx">core</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">core</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">&quot;plugeth&quot;</span><span class="p">,</span>
<span class="nx">Version</span><span class="p">:</span> <span class="s">&quot;1.0&quot;</span><span class="p">,</span>
<span class="nx">Service</span><span class="p">:</span> <span class="o">&amp;</span><span class="nx">MyService</span><span class="p">{</span><span class="nx">backend</span><span class="p">,</span> <span class="nx">stack</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>
</pre></div>
</div>
</div>
<div class="section" id="subscription-function">
<h2>Subscription Function<a class="headerlink" href="#subscription-function" title="Permalink to this headline"></a></h2>
<p>For subscriptions (supported on IPC and websockets), a function should take MyService as a reciever and a context.Context object as an argument and return a channel and an error. The following is a subscription function that impliments a timer.</p>
<div class="highlight-Go notranslate"><div class="highlight"><pre><span></span><span class="kd">func</span> <span class="p">(</span><span class="o">*</span><span class="nx">myservice</span><span class="p">)</span> <span class="nx">Timer</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="p">(</span><span class="o">&lt;-</span><span class="kd">chan</span> <span class="kt">int64</span><span class="p">,</span> <span class="kt">error</span><span class="p">)</span> <span class="p">{</span>
<span class="nx">ticker</span> <span class="o">:=</span> <span class="nx">time</span><span class="p">.</span><span class="nx">NewTicker</span><span class="p">(</span><span class="nx">time</span><span class="p">.</span><span class="nx">Second</span><span class="p">)</span>
<span class="nx">ch</span> <span class="o">:=</span> <span class="nb">make</span><span class="p">(</span><span class="kd">chan</span> <span class="kt">int64</span><span class="p">)</span>
<span class="k">go</span> <span class="kd">func</span><span class="p">()</span> <span class="p">{</span>
<span class="k">defer</span> <span class="nx">ticker</span><span class="p">.</span><span class="nx">Stop</span><span class="p">()</span>
<span class="k">for</span> <span class="p">{</span>
<span class="k">select</span> <span class="p">{</span>
<span class="k">case</span> <span class="o">&lt;-</span><span class="nx">ctx</span><span class="p">.</span><span class="nx">Done</span><span class="p">():</span>
<span class="nb">close</span><span class="p">(</span><span class="nx">ch</span><span class="p">)</span>
<span class="k">return</span>
<span class="k">case</span> <span class="nx">t</span> <span class="o">:=</span> <span class="o">&lt;-</span><span class="nx">ticker</span><span class="p">.</span><span class="nx">C</span><span class="p">:</span>
<span class="nx">ch</span> <span class="o">&lt;-</span> <span class="nx">t</span><span class="p">.</span><span class="nx">UnixNano</span><span class="p">()</span>
<span class="p">}</span>
<span class="p">}</span>
<span class="p">}()</span>
<span class="k">return</span> <span class="nx">ch</span><span class="p">,</span> <span class="kc">nil</span>
<span class="p">}</span>
</pre></div>
</div>
<div class="admonition warning">
<p class="admonition-title">Warning</p>
<p>Notice in the example above, the <code class="docutils literal notranslate"><span class="pre">ctx.Done()</span></code> or
Context.Done() method closes the channel. If this is not present the go routine will run for the life of the process.</p>
</div>
</div>
<div class="section" id="access">
<h2>Access<a class="headerlink" href="#access" title="Permalink to this headline"></a></h2>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>Plugins providing subscriptions can be accessed via IPC
and websockets. In the below example we will be using <a class="reference external" href="https://www.npmjs.com/package/wscat">wscat</a> to connect a websocket to a local Geth node.</p>
</div>
<p>As with pre-built plugins, a <code class="docutils literal notranslate"><span class="pre">.so</span></code> will need to be built from <code class="docutils literal notranslate"><span class="pre">main.go</span></code> and moved into <code class="docutils literal notranslate"><span class="pre">~/.ethereum/plugins</span></code>. Geth will need to be started with with <code class="docutils literal notranslate"><span class="pre">--ws</span> <span class="pre">--ws.api=mynamespace``flags.</span> <span class="pre">Additionally</span> <span class="pre">you</span> <span class="pre">will</span> <span class="pre">need</span> <span class="pre">to</span> <span class="pre">include</span> <span class="pre">a</span> <span class="pre">``--http</span></code> flag in order to access the standard json rpc methods.</p>
<p>After starting Geth, from a seperate terminal run:</p>
<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>wscat -c ws://127.0.0.1:8546
</pre></div>
</div>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>Websockets are available via port 8546</p>
</div>
<p>Once the connection has been established from the websocket cursor enter the following argument:</p>
<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span><span class="o">{</span><span class="s2">&quot;jsonrpc&quot;</span>:<span class="s2">&quot;2.0&quot;</span>,<span class="s2">&quot;method&quot;</span>:<span class="s2">&quot;mynamespace_hello&quot;</span>,<span class="s2">&quot;params&quot;</span>:<span class="o">[]</span>,<span class="s2">&quot;id&quot;</span>:0<span class="o">}</span>
You should see that the network has responded with:
</pre></div>
</div>
<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span><span class="sb">``</span><span class="o">{</span><span class="s2">&quot;jsonrpc&quot;</span>:<span class="s2">&quot;2.0&quot;</span>,<span class="s2">&quot;id&quot;</span>:0,<span class="s2">&quot;result&quot;</span>:<span class="s2">&quot;Hello world&quot;</span><span class="o">}</span><span class="sb">``</span>
</pre></div>
</div>
</div>
</div>
</div>
</div>
<footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
<a href="RPC_method.html" class="btn btn-neutral float-left" title="RPC Methods" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
<a href="tracer.html" class="btn btn-neutral float-right" title="Tracer" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
</div>
<hr/>
<div role="contentinfo">
<p>&#169; 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
docs/_build/html/system_req.html vendored Normal file
View 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>System Requirements &mdash; 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="Version" href="version.html" />
<link rel="prev" title="Tracer" href="tracer.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>
</ul>
<p class="caption"><span class="caption-text">Tutorials</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="install.html">Install</a></li>
<li class="toctree-l1"><a class="reference internal" href="build.html">Build and Deploy</a></li>
<li class="toctree-l1"><a class="reference internal" href="custom.html">Building a Custom Plugin</a></li>
</ul>
<p class="caption"><span class="caption-text">Reference</span></p>
<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="version.html">Version</a></li>
<li class="toctree-l1"><a class="reference internal" href="api.html">API</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="hooks.html">Selected Plugin Hooks</a></li>
<li class="toctree-l1"><a class="reference internal" href="hook_writing.html">Hook Writing Guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="core_restricted.html">PluGeth-utils Subpackages</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> &raquo;</li>
<li>System Requirements</li>
<li class="wy-breadcrumbs-aside">
<a href="_sources/system_req.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="system-requirements">
<span id="system-req"></span><h1>System Requirements<a class="headerlink" href="#system-requirements" title="Permalink to this headline"></a></h1>
<p>System requirements will vary depending on which network you are connecting to. On the Ethereum mainnet, you should have at least 8 GB RAM, 2 CPUs, and 350 GB of SSD disks.</p>
<p>PluGeth relies on Golang’s Plugin implementation, which is only supported on Linux, FreeBSD, and macOS. Windows support is unlikely to be added in the foreseeable future.</p>
</div>
</div>
</div>
<footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
<a href="tracer.html" class="btn btn-neutral float-left" title="Tracer" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
<a href="version.html" class="btn btn-neutral float-right" title="Version" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
</div>
<hr/>
<div role="contentinfo">
<p>&#169; 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>

193
docs/_build/html/tracer.html vendored Normal file
View File

@ -0,0 +1,193 @@
<!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>Tracer &mdash; 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="System Requirements" href="system_req.html" />
<link rel="prev" title="Subscription" href="subscription.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>
</ul>
<p class="caption"><span class="caption-text">Tutorials</span></p>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="install.html">Install</a></li>
<li class="toctree-l1"><a class="reference internal" href="build.html">Build and Deploy</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="custom.html">Building a Custom Plugin</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="RPC_method.html">RPC Methods</a></li>
<li class="toctree-l2"><a class="reference internal" href="subscription.html">Subscription</a></li>
<li class="toctree-l2 current"><a class="current reference internal" href="#">Tracer</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#myservice-struct">MyService Struct</a></li>
<li class="toctree-l3"><a class="reference internal" href="#map">Map</a></li>
<li class="toctree-l3"><a class="reference internal" href="#tracerresult-functions">TracerResult Functions</a></li>
<li class="toctree-l3"><a class="reference internal" href="#access">Access</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="custom.html#basic-implementation">Basic Implementation</a></li>
<li class="toctree-l2"><a class="reference internal" href="custom.html#specialization">Specialization</a></li>
</ul>
</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="version.html">Version</a></li>
<li class="toctree-l1"><a class="reference internal" href="api.html">API</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="hooks.html">Selected Plugin Hooks</a></li>
<li class="toctree-l1"><a class="reference internal" href="hook_writing.html">Hook Writing Guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="core_restricted.html">PluGeth-utils Subpackages</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> &raquo;</li>
<li><a href="custom.html">Building a Custom Plugin</a> &raquo;</li>
<li>Tracer</li>
<li class="wy-breadcrumbs-aside">
<a href="_sources/tracer.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="tracer">
<span id="id1"></span><h1>Tracer<a class="headerlink" href="#tracer" title="Permalink to this headline"></a></h1>
<p>In addition to the initial template containing an intialize function, plugins providing <strong>Tracers</strong> will require three additional elements.</p>
<div class="admonition warning">
<p class="admonition-title">Warning</p>
<p>Caution: Modifying of the values passed into tracer
functions can alter the results of the EVM execution in unpredictable ways. Additionally, some objects may be reused across calls, so data you wish to capture should be copied rather than retained be reference.</p>
</div>
<div class="section" id="myservice-struct">
<h2>MyService Struct<a class="headerlink" href="#myservice-struct" title="Permalink to this headline"></a></h2>
<p>First an empty MyService Struct.</p>
<div class="highlight-Go notranslate"><div class="highlight"><pre><span></span><span class="kd">type</span> <span class="nx">MyService</span> <span class="kd">struct</span> <span class="p">{</span>
<span class="p">}</span>
</pre></div>
</div>
</div>
<div class="section" id="map">
<h2>Map<a class="headerlink" href="#map" title="Permalink to this headline"></a></h2>
<p>Next, a map of tracers to functions returning a <code class="docutils literal notranslate"><span class="pre">core.TracerResult</span></code> which will be implimented like so:</p>
<div class="highlight-Go notranslate"><div class="highlight"><pre><span></span><span class="kd">var</span> <span class="nx">Tracers</span> <span class="p">=</span> <span class="kd">map</span><span class="p">[</span><span class="kt">string</span><span class="p">]</span><span class="kd">func</span><span class="p">(</span><span class="nx">core</span><span class="p">.</span><span class="nx">StateDB</span><span class="p">)</span> <span class="nx">core</span><span class="p">.</span><span class="nx">TracerResult</span><span class="p">{</span>
<span class="s">&quot;myTracer&quot;</span><span class="p">:</span> <span class="kd">func</span><span class="p">(</span><span class="nx">core</span><span class="p">.</span><span class="nx">StateDB</span><span class="p">)</span> <span class="nx">core</span><span class="p">.</span><span class="nx">TracerResult</span> <span class="p">{</span>
<span class="k">return</span> <span class="o">&amp;</span><span class="nx">MyBasicTracerService</span><span class="p">{}</span>
<span class="p">},</span>
<span class="p">}</span>
</pre></div>
</div>
</div>
<div class="section" id="tracerresult-functions">
<h2>TracerResult Functions<a class="headerlink" href="#tracerresult-functions" title="Permalink to this headline"></a></h2>
<p>Finally a series of functions which points to the MyService struct and coresponds to the interface which geth anticipates.</p>
<div class="highlight-Go notranslate"><div class="highlight"><pre><span></span><span class="kd">func</span> <span class="p">(</span><span class="nx">b</span> <span class="o">*</span><span class="nx">MyBasicTracerService</span><span class="p">)</span> <span class="nx">CaptureStart</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="p">}</span>
<span class="kd">func</span> <span class="p">(</span><span class="nx">b</span> <span class="o">*</span><span class="nx">MyBasicTracerService</span><span class="p">)</span> <span class="nx">CaptureState</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="nx">core</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="p">}</span>
<span class="kd">func</span> <span class="p">(</span><span class="nx">b</span> <span class="o">*</span><span class="nx">MyBasicTracerService</span><span class="p">)</span> <span class="nx">CaptureFault</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="nx">core</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="p">}</span>
<span class="kd">func</span> <span class="p">(</span><span class="nx">b</span> <span class="o">*</span><span class="nx">MyBasicTracerService</span><span class="p">)</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="p">}</span>
<span class="kd">func</span> <span class="p">(</span><span class="nx">b</span> <span class="o">*</span><span class="nx">MyBasicTracerService</span><span class="p">)</span> <span class="nx">Result</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="k">return</span> <span class="s">&quot;hello world&quot;</span><span class="p">,</span> <span class="kc">nil</span> <span class="p">}</span>
</pre></div>
</div>
</div>
<div class="section" id="access">
<h2>Access<a class="headerlink" href="#access" title="Permalink to this headline"></a></h2>
<p>As with pre-built plugins, a <code class="docutils literal notranslate"><span class="pre">.so</span></code> will need to be built from <code class="docutils literal notranslate"><span class="pre">main.go</span></code> and moved into <code class="docutils literal notranslate"><span class="pre">~/.ethereum/plugins</span></code>. Geth will need to be started with with a <code class="docutils literal notranslate"><span class="pre">--http.api+debug</span></code> flag.</p>
<p>From a terminal pass the following argument to the api:</p>
<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>curl <span class="m">127</span>.0.0.1:8545 -H <span class="s2">&quot;Content-Type: application/json&quot;</span> --data <span class="s1">&#39;{&quot;jsonrpc&quot;:&quot;2.0&quot;,&quot;method&quot;:&quot;debug_traceCall&quot;,&quot;params&quot;:[{&quot;to&quot;:&quot;0x32Be343B94f860124dC4fEe278FDCBD38C102D88&quot;},&quot;latest&quot;,{&quot;tracer&quot;:&quot;myTracer&quot;}],&quot;id&quot;:0}&#39;</span>
</pre></div>
</div>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>The address used above is a test adress and will need to
be replaced by whatever address you wish to access. Also <code class="docutils literal notranslate"><span class="pre">traceCall</span></code> is one of several methods available for use.</p>
</div>
<p>If using the template above, the call should return:</p>
<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span><span class="o">{</span><span class="s2">&quot;jsonrpc&quot;</span>:<span class="s2">&quot;2.0&quot;</span>,<span class="s2">&quot;id&quot;</span>:0,<span class="s2">&quot;result&quot;</span>:<span class="s2">&quot;hello world&quot;</span><span class="o">}</span>
</pre></div>
</div>
</div>
</div>
</div>
</div>
<footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
<a href="subscription.html" class="btn btn-neutral float-left" title="Subscription" 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/>
<div role="contentinfo">
<p>&#169; 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>

163
docs/_build/html/types.html vendored Normal file
View File

@ -0,0 +1,163 @@
<!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>Basic Types of Plugins &mdash; 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="Install" href="install.html" />
<link rel="prev" title="Project Design" href="project.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 class="current">
<li class="toctree-l1"><a class="reference internal" href="project.html">Project Design</a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="#">Basic Types of Plugins</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#rpc-methods">RPC Methods</a></li>
<li class="toctree-l2"><a class="reference internal" href="#subcommand">Subcommand</a></li>
<li class="toctree-l2"><a class="reference internal" href="#tracers">Tracers</a></li>
<li class="toctree-l2"><a class="reference internal" href="#subscriptions">Subscriptions</a></li>
</ul>
</li>
</ul>
<p class="caption"><span class="caption-text">Tutorials</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="install.html">Install</a></li>
<li class="toctree-l1"><a class="reference internal" href="build.html">Build and Deploy</a></li>
<li class="toctree-l1"><a class="reference internal" href="custom.html">Building a Custom Plugin</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="version.html">Version</a></li>
<li class="toctree-l1"><a class="reference internal" href="api.html">API</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="hooks.html">Selected Plugin Hooks</a></li>
<li class="toctree-l1"><a class="reference internal" href="hook_writing.html">Hook Writing Guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="core_restricted.html">PluGeth-utils Subpackages</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> &raquo;</li>
<li>Basic Types of Plugins</li>
<li class="wy-breadcrumbs-aside">
<a href="_sources/types.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="basic-types-of-plugins">
<span id="types"></span><h1>Basic Types of Plugins<a class="headerlink" href="#basic-types-of-plugins" title="Permalink to this headline"></a></h1>
<p>While PluGeth has been designed to be versatile and customizable, when learning the project it can be helpful to think of plugins as being of four different archetypes.</p>
<div class="contents local topic" id="contents">
<ul class="simple">
<li><p><a class="reference internal" href="#rpc-methods" id="id2">RPC Methods</a></p></li>
<li><p><a class="reference internal" href="#subcommand" id="id3">Subcommand</a></p></li>
<li><p><a class="reference internal" href="#tracers" id="id4">Tracers</a></p></li>
<li><p><a class="reference internal" href="#subscriptions" id="id5">Subscriptions</a></p></li>
</ul>
</div>
<div class="section" id="rpc-methods">
<h2><a class="toc-backref" href="#id2">RPC Methods</a><a class="headerlink" href="#rpc-methods" title="Permalink to this headline"></a></h2>
<p>These plugins provide new json rpc methods to access several objects containing real time and historic data.</p>
</div>
<div class="section" id="subcommand">
<h2><a class="toc-backref" href="#id3">Subcommand</a><a class="headerlink" href="#subcommand" title="Permalink to this headline"></a></h2>
<p>A subcommand redifines the total behavior of Geth and could stand on its own. In contrast with the other plugin types which, in general, are meant to capture and manipulate information, a subcommand is meant to change to overall behavior of Geth. It may do this in order to capture information but the primary fuctionality is a modulation of geth behaviour.</p>
</div>
<div class="section" id="tracers">
<h2><a class="toc-backref" href="#id4">Tracers</a><a class="headerlink" href="#tracers" title="Permalink to this headline"></a></h2>
<p>Tracers rely on historic data recompiled after execution to give insight into a transaction.</p>
<p><strong>placeholder for eventual discusion of LiveTracers</strong></p>
</div>
<div class="section" id="subscriptions">
<h2><a class="toc-backref" href="#id5">Subscriptions</a><a class="headerlink" href="#subscriptions" title="Permalink to this headline"></a></h2>
<p>Subscriptions provide real time notification of data from the EVM as it processes transactions.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>Plugins are not limited to a singular functionality and can be customized to operate as hybrids of the above. See <a class="reference external" href="https://github.com/openrelayxyz/plugeth-plugins/tree/master/packages/blockupdates">blockupdates</a> as an example.</p>
</div>
<div class="admonition-todo admonition" id="id1">
<p class="admonition-title">Todo</p>
<p>Austin: I don’t love this page. The informations is too
shallow.</p>
</div>
</div>
</div>
</div>
</div>
<footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
<a href="project.html" class="btn btn-neutral float-left" title="Project Design" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
<a href="install.html" class="btn btn-neutral float-right" title="Install" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
</div>
<hr/>
<div role="contentinfo">
<p>&#169; 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>

153
docs/_build/html/version.html vendored Normal file
View File

@ -0,0 +1,153 @@
<!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>Version &mdash; 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="API" href="api.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>
</ul>
<p class="caption"><span class="caption-text">Tutorials</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="install.html">Install</a></li>
<li class="toctree-l1"><a class="reference internal" href="build.html">Build and Deploy</a></li>
<li class="toctree-l1"><a class="reference internal" href="custom.html">Building a Custom Plugin</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="#">Version</a></li>
<li class="toctree-l1"><a class="reference internal" href="api.html">API</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="hooks.html">Selected Plugin Hooks</a></li>
<li class="toctree-l1"><a class="reference internal" href="hook_writing.html">Hook Writing Guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="core_restricted.html">PluGeth-utils Subpackages</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> &raquo;</li>
<li>Version</li>
<li class="wy-breadcrumbs-aside">
<a href="_sources/version.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="version">
<span id="id1"></span><h1>Version<a class="headerlink" href="#version" title="Permalink to this headline"></a></h1>
<p>PluGeth is separated into three packages in order to minimize dependency conflicts. Golang plugins cannot include different versions of the same packages as the program loading the plugin. If plugins had to import packages from PluGeth itself, a plugin build could only be loaded by that same version of PluGeth. By separating out the PluGeth-utils package, both PluGeth and the plugins must rely on the same version of PluGeth-utils, but plugins can be compatible with any version of PluGeth compiled with the same version of PluGeth-utils.</p>
<p>PluGeth builds will follow the naming convention:</p>
<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>geth-<span class="nv">$PLUGETH_UTILS_VERSION</span>-<span class="nv">$GETH_VERSION</span>-<span class="nv">$RELEASE</span>
</pre></div>
</div>
<p>For example:</p>
<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>geth-0.1.0-1.10.8-0
</pre></div>
</div>
<p>Tells us that:</p>
<ul class="simple">
<li><p>PluGeth-utils version is 0.1.0</p></li>
<li><p>Geth version is 1.10.8</p></li>
<li><p>This is the first release with that combination of dependencies.</p></li>
</ul>
<p>Plugin builds will follow the naming convention:</p>
<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span><span class="nv">$PLUGIN_NAME</span>-<span class="nv">$PLUGETH_UTILS_VERSION</span>-<span class="nv">$PLUGIN_VERSION</span>
</pre></div>
</div>
<p>For example:</p>
<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>blockupdates-0.1.0-1.0.2
</pre></div>
</div>
<p>Tells us that:</p>
<ul class="simple">
<li><p>The plugin is “blockupdates”</p></li>
<li><p>The PluGeth-utils version is 0.1.0</p></li>
<li><p>The plugin version is 1.0.2</p></li>
</ul>
<p>When a Geth update comes out, you can expect a release of <cite>geth-0.1.0-1.10.9-0</cite>, which will be compatible with the same set of plugins.</p>
<p>When PluGeth upgrades are necessary, plugins will need to be recompiled. Whenever possible, we will try to avoid forcing plugins to be recompiled for an immediate Geth upgrade. For example, if we have geth-0.1.0-1.10.8, and upgrade PluGeth-utils, we will have a geth-0.1.1-1.10.8, followed by a geth-0.1.1-1.10.9. This will give users time to upgrade plugins from PluGeth-utils 0.1.0 to 0.1.1 while staying on Geth 1.10.8, and when it is time to upgrade to Geth 1.10.9 they can continue using the plugins they were using with geth 1.10.8. Depending on upgrades to Geth, it may not always be possible to maintain compatibility with existing PluGeth versions, which will be noted in release notes.</p>
</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="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/>
<div role="contentinfo">
<p>&#169; 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>

7
docs/anatomy.rst
View File

@ -1,7 +0,0 @@
.. _anatomy:
==============
Plugin Anatomy
==============
.. todo:: fill in disections of archetypal plugins (Philip: Are you doing this, or am I?)

235
docs/api.rst
View File

@ -4,8 +4,8 @@
API
===
PluGeth Hooks
+++++++++++++
Anatomy of a Plugin
===================
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.
@ -28,9 +28,9 @@ 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.
* **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
.. todo:: explain that plugin could provide node.Node with
restricted.backend
InitializeNode
@ -40,118 +40,6 @@ 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. Additopackage main
.. code-block:: go
import (
"github.com/openrelayxyz/plugeth-utils/core"
"gopkg.in/urfave/cli.v1"
)
var (
log core.Logger
)
type myservice struct{}
func (*myservice) Hello() string {
return "Hello world"
}
func Initialize(ctx *cli.Context, loader core.PluginLoader, logger core.Logger) {
log = logger
log.Info("Initialized hello")
}
func GetAPIs(node core.Node, backend core.Backend) []core.API {
defer log.Info("APIs Initialized")
return []core.API{
{
Namespace: "mynamespace",
Version: "1.0",
Service: &myservice{},
Public: true,
},
}
}
.. todo:: Why do we have two copies of this? Also, these are GetAPIs examples, not tracers
.. code-block:: go
package main
import (
"github.com/openrelayxyz/plugeth-utils/core"
"gopkg.in/urfave/cli.v1"
)
var (
log core.Logger
)
type myservice struct{}
func (*myservice) Hello() string {
return "Hello world"
}
func Initialize(ctx *cli.Context, loader core.PluginLoader, logger core.Logger) {
log = logger
log.Info("Initialized hello")
}
func GetAPIs(node core.Node, backend core.Backend) []core.API {
defer log.Info("APIs Initialized")
return []core.API{
{
Namespace: "mynamespace",
Version: "1.0",
Service: &myservice{},
Public: true,
},
}
}
Internally, some objects may be reused across calls, so data you wish to capture should be copied rather than retained by reference.
LiveTracer
----------
.. todo:: Let's leave this out until we can have a more detailed implementation.
* **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
-------
@ -163,16 +51,16 @@ The GetAPIs function itself will generally be fairly brief, and will looks somet
.. 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,
},
}
}
``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:
@ -184,17 +72,17 @@ A very simple MyService might look like:
.. code-block:: go
type MyService struct{}
``type MyService struct{}
func (h MyService) HelloWorld(ctx context.Context) string {
return "Hello World"
}
func (h MyService) HelloWorld(ctx context.Context) string {
return "Hello World"
}``
And the client could access this with an rpc call to
``mynamespace_helloWorld``
And the client could access this with an rpc call to
``mynamespace_helloworld``
Injected APIs
+++++++++++++
=============
In addition to hooks that get invoked by Geth, several objects are injected that give you access to additional information.
@ -204,50 +92,50 @@ Backend Object
The ``core.Backend`` object is injected by the ``InitializeNode()`` and ``GetAPI()`` functions. It offers the following functions:
Downloader
^^^^^^^^^^
**********
``Downloader() Downloader``
Returns a Downloader objects, which can provide Syncing status
SuggestGasTipCap
^^^^^^^^^^^^^^^^
****************
``SuggestGasTipCap(ctx context.Context) (*big.Int, error)``
Suggests a Gas tip for the current block.
ExtRPCEnabled
^^^^^^^^^^^^^
*************
``ExtRPCEnabled() bool``
Returns whether RPC external RPC calls are enabled.
RPCGasCap
^^^^^^^^^
*********
``RPCGasCap() uint64``
Returns the maximum Gas available to RPC Calls.
RPCTxFeeCap
^^^^^^^^^^^
***********
``RPCTxFeeCap() float64``
Returns the maximum transaction fee for a transaction submitted via RPC.
UnprotectedAllowed
^^^^^^^^^^^^^^^^^^
******************
``UnprotectedAllowed() bool``
Returns whether or not unprotected transactions can be transmitted through this
node via RPC.
SetHead
^^^^^^^
*******
``SetHead(number uint64)``
Resets the head to the specified block number.
HeaderByNumber
^^^^^^^^^^^^^^
**************
``HeaderByNumber(ctx context.Context, number int64) ([]byte, error)``
Returns an RLP encoded block header for the specified block number.
@ -255,7 +143,7 @@ Returns an RLP encoded block header for the specified block number.
The RLP encoded response can be decoded into a `plugeth-utils/restricted/types.Header` object.
HeaderByHash
^^^^^^^^^^^^
************
``HeaderByHash(ctx context.Context, hash Hash) ([]byte, error)``
Returns an RLP encoded block header for the specified block hash.
@ -263,7 +151,7 @@ Returns an RLP encoded block header for the specified block hash.
The RLP encoded response can be decoded into a `plugeth-utils/restricted/types.Header` object.
CurrentHeader
^^^^^^^^^^^^^
*************
``CurrentHeader() []byte``
Returns an RLP encoded block header for the current block.
@ -271,7 +159,7 @@ Returns an RLP encoded block header for the current block.
The RLP encoded response can be decoded into a `plugeth-utils/restricted/types.Header` object.
CurrentBlock
^^^^^^^^^^^^
************
``CurrentBlock() []byte``
Returns an RLP encoded full block for the current block.
@ -280,15 +168,16 @@ The RLP encoded response can be decoded into a `plugeth-utils/restricted/types.B
BlockByNumber
^^^^^^^^^^^^^
*************
``BlockByNumber(ctx context.Context, number int64) ([]byte, error)``
Returns an RLP encoded full block for the specified block number.
The RLP encoded response can be decoded into a `plugeth-utils/restricted/types.Block` object.
BlockByHash
^^^^^^^^^^^
***********
``BlockByHash(ctx context.Context, hash Hash) ([]byte, error)``
Returns an RLP encoded full block for the specified block hash.
@ -296,7 +185,7 @@ Returns an RLP encoded full block for the specified block hash.
The RLP encoded response can be decoded into a `plugeth-utils/restricted/types.Block` object.
GetReceipts
^^^^^^^^^^^
***********
``GetReceipts(ctx context.Context, hash Hash) ([]byte, error)``
Returns an JSON encoded list of receipts for the specified block hash.
@ -305,37 +194,37 @@ The JSON encoded response can be decoded into a `plugeth-utils/restricted/types.
GetTd
^^^^^
*****
``GetTd(ctx context.Context, hash Hash) *big.Int``
Returns the total difficulty for the specified block hash.
SubscribeChainEvent
^^^^^^^^^^^^^^^^^^^
*******************
``SubscribeChainEvent(ch chan<- ChainEvent) Subscription``
Subscribes the provided channel to new chain events.
SubscribeChainHeadEvent
^^^^^^^^^^^^^^^^^^^^^^^
***********************
``SubscribeChainHeadEvent(ch chan<- ChainHeadEvent) Subscription``
Subscribes the provided channel to new chain head events.
SubscribeChainSideEvent
^^^^^^^^^^^^^^^^^^^^^^^
***********************
``SubscribeChainSideEvent(ch chan<- ChainSideEvent) Subscription``
Subscribes the provided channel to new chain side events.
SendTx
^^^^^^
******
``SendTx(ctx context.Context, signedTx []byte) error``
Sends an RLP encoded, signed transaction to the network.
GetTransaction
^^^^^^^^^^^^^^
**************
``GetTransaction(ctx context.Context, txHash Hash) ([]byte, Hash, uint64, uint64, error)``
Returns an RLP encoded transaction at the specified hash, along with the hash and number of the included block, and the transaction's position within that block.
@ -347,57 +236,57 @@ GetPoolTransactions
Returns a list of RLP encoded transactions found in the mempool
GetPoolTransaction
^^^^^^^^^^^^^^^^^^
******************
``GetPoolTransaction(txHash Hash) []byte``
Returns the RLP encoded transaction from the mempool at the specified hash.
GetPoolNonce
^^^^^^^^^^^^
************
``GetPoolNonce(ctx context.Context, addr Address) (uint64, error)``
Returns the nonce of the last transaction for a given address, including
transactions found in the mempool.
Stats
^^^^^
*****
``Stats() (pending int, queued int)``
Returns the number of pending and queued transactions in the mempool.
TxPoolContent
^^^^^^^^^^^^^
*************
``TxPoolContent() (map[Address][][]byte, map[Address][][]byte)``
Returns a map of addresses to the list of RLP encoded transactions pending in
the mempool, and queued in the mempool.
SubscribeNewTxsEvent
^^^^^^^^^^^^^^^^^^^^
********************
``SubscribeNewTxsEvent(chan<- NewTxsEvent) Subscription``
Subscribe to a feed of new transactions added to the mempool.
GetLogs
^^^^^^^
*******
``GetLogs(ctx context.Context, blockHash Hash) ([][]byte, error)``
Returns a list of RLP encoded logs found in the specified block.
SubscribeLogsEvent
^^^^^^^^^^^^^^^^^^
******************
``SubscribeLogsEvent(ch chan<- [][]byte) Subscription``
Subscribe to logs included in a confirmed block.
SubscribePendingLogsEvent
^^^^^^^^^^^^^^^^^^^^^^^^^
*************************
``SubscribePendingLogsEvent(ch chan<- [][]byte) Subscription``
Subscribe to logs from pending transactions.
SubscribeRemovedLogsEvent
^^^^^^^^^^^^^^^^^^^^^^^^^
*************************
``SubscribeRemovedLogsEvent(ch chan<- []byte) Subscription``
Subscribe to logs removed from the canonical chain in reorged blocks.
@ -409,44 +298,44 @@ Node Object
The ``core.Node`` object is injected by the ``InitializeNode()`` and ``GetAPI()`` functions. It offers the following functions:
Server
^^^^^^
******
``Server() Server``
The Server object provides access to ``server.PeerCount()``, the number of peers connected to the node.
DataDir
^^^^^^^
*******
``DataDir() string``
Returns the Ethereuem datadir.
InstanceDir
^^^^^^^^^^^
***********
``InstanceDir() string``
Returns the instancedir used by the protocol stack.
IPCEndpoint
^^^^^^^^^^^
***********
``IPCEndpoint() string``
The path of the IPC Endpoint for this node.
HTTPEndpoint
^^^^^^^^^^^^
************
``HTTPEndpoint() string``
The url of the HTTP Endpoint for this node.
WSEndpoint
^^^^^^^^^^
**********
``WSEndpoint() string``
The url of the websockets Endpoint for this node.
ResolvePath
^^^^^^^^^^^
***********
``ResolvePath(x string) string``
Resolves a path within the DataDir.
@ -461,3 +350,11 @@ Logger
The Logger object is injected by the ``Initialize()`` function. It implements
logging based on the interfaces of `Log15 <https://github.com/inconshreveable/log15>`_.
.. _*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

39
docs/build.rst
View File

@ -6,30 +6,32 @@ Build and Deploy
.. contents:: :local:
If you are ready to start building your own plugins go ahead and start here.
Setting up the environment
**************************
.. NOTE:: Plugeth is built on a fork of `Geth`_ and as such requires familiarity with `Go`_ and a funtional `environment`_ in which to build Go projects. Thankfully for everyone Go provides a compact and useful `tutorial`_ as well as a `space for practice`_.
.. NOTE:: Plugeth is built on a fork of `Geth`_ and as such requires familiarity with `Go`_ and a funtional `environment`_ in which to build Go projects. Thankfully for everyone Go provides a compact and useful `tutorial`_ as well as a `space for practice`_.
PluGeth is an application built in three seperate repositories.
PluGeth is an application built in three seperate repositories.
* `PluGeth`_
* `PluGethUtils`_
* `PluGethPlugins`_
* `PluGeth-Utils`_
* `PluGeth-Plugins`_
Once all three are cloned into their own directories you are ready to begin. First we need to build geth though the PluGeth project. Navigate to ``plugeth/cmd/geth`` and run:
For our purposed here you will only need to clone Plugeth and Plugeth-Plugins. Once you have them cloned you are ready to begin. First we need to build geth though the PluGeth project. Navigate to ``plugeth/cmd/geth`` and run:
.. code-block:: shell
$ go get
This will download all dependencies needed for the project. This process will take a moment or two the first time through. Next run:
This will download all dependencies needed for the project. This process will take a moment or two the first time through. Next run:
.. code-block:: shell
$ go build
Once this is complete you should see a ``.ethereum`` folder in your home directory.
Once this is complete you should see a ``.ethereum`` folder in your home directory.
At this point you are ready to start downloading local ethereum nodes. In order to do so, from ``plugeth/cmd/geth`` run:
@ -37,19 +39,19 @@ At this point you are ready to start downloading local ethereum nodes. In order
$ ./geth
.. NOTE:: ``./geth`` is the primary command to build a *Mainnet* node. Building a mainnet node requires at least 8 GB RAM, 2 CPUs, and 350 GB of SSD disks. However, dozens of available flags will change the behavior of whichever network you choose to connect to. ``--help`` is your friend.
.. NOTE:: ``./geth`` is the primary command to build a *Mainnet* node. Building a mainnet node requires at least 8 GB RAM, 2 CPUs, and 350 GB of SSD disks. However, dozens of available flags will change the behavior of whichever network you choose to connect to. ``--help`` is your friend.
Build a plugin
**************
Navigate to ``plugethPlugins/packages/hello``. Inside you will see a ``main.go`` file. From this location run:
For the sake of this tutorial we will be building the Hello plugin. Navigate to ``plugethPlugins/packages/hello``. Inside you will see a ``main.go`` file. From this location run:
.. code-block:: shell
$ go build -buildmode=plugin
This will compile the plugin and produce a ``hello.so`` file. Move ``hello.so`` into ``~/.ethereum/plugins`` . In order to use this plugin geth will need to be started with a ``http.api=mynamespace`` flag. Additionally you will need to include a ``--http`` flag in order to access the standard json rpc methods.
This will compile the plugin and produce a ``hello.so`` file. Move ``hello.so`` into ``~/.ethereum/plugins`` . In order to use this plugin geth will need to be started with a ``http.api=mymamespace`` flag. Additionally you will need to include a ``--http`` flag in order to access the standard json rpc methods.
Once geth has started you should see that the first ``INFO`` log reads: ``initialized hello`` . A new json rpc method, called hello, has been been appended to the list of available json rpc methods. In order to access this method you will need to ``curl`` into the network with this command:
@ -61,15 +63,20 @@ You should see that the network has responded with:
.. code-block:: shell
{"jsonrpc":"2.0","id":0,"result":"Hello world"}
``{"jsonrpc":"2.0","id":0,"result":"Hello world"}``
Congradulations. You have just built and run your first Plugeth plugin.
Congradulations. You have just built and run your first Plugeth plugin. From here you can follow the steps above to build any of the plugins you choose.
.. _space for practice: https://tour.golang.org/welcome/1
.. _tutorial: https://tour.golang.org/welcome/1
.. NOTE:: Each plugin will vary in terms of the requirements to deploy. Refer to the documentation of the plugin itself in order to assure
that you know how to use it.
.. _space for practice: https://tour.golang.org/welcome/1
.. _tutorial: https://tour.golang.org/welcome/1
.. _environment: https://golang.org/doc/code
.. _Go: https://golang.org/doc/
.. _Geth: https://geth.ethereum.org/
.. _PluGeth: https://github.com/openrelayxyz/plugeth
.. _PluGethUtils: https://github.com/openrelayxyz/plugeth-utils
.. _PluGethPlugins: https://github.com/openrelayxyz/plugeth-plugins
.. _PluGeth-Utils: https://github.com/openrelayxyz/plugeth-utils
.. _PluGeth-Plugins: https://github.com/openrelayxyz/plugeth-plugins

83
docs/custom.rst Normal file
View File

@ -0,0 +1,83 @@
.. _custom:
========================
Building a Custom Plugin
========================
.. toctree::
:hidden:
RPC_method
subscription
tracer
Before setting out to build a plugin it will be helpful to be familiar with the :ref:`types`. deifferent plugins will require different implimentation.
Basic Implementation
====================
In general, no matter which type of plugin you intend to build, all will share some common aspects.
Package
-------
Any plugin will need its own package located in the Plugeth-Plugins packages directory. The package will need to include a main.go from which the .so file will be built. The package and main file should share the same name and the name should be a word that describes the basic functionality of the plugin.
Initialize
----------
Most plugins will need to be initialized with an Initialize function. The initialize function will need to be passed at least three arguments: a cli.Context, core.PluginLoader, and a core.Logger.
And so, all plugins could have an intial template that looks something like this:
.. code-block:: Go
package main
import (
"github.com/openrelayxyz/plugeth-utils/core"
"gopkg.in/urfave/cli.v1"
)
var log core.Logger
func Initialize(ctx *cli.Context, loader core.PluginLoader, logger core.Logger) {
log = logger
log.Info("loaded New Custom Plugin")
}
InitializeNode
--------------
Many plugins will make use of the InitializeNode function. Implimentation will look like so:
.. code-block:: Go
func InitializeNode(stack core.Node, b core.Backend) {
backend = b
log.Info("Initialized node and backend")
}
This is called as soon as the Geth node is initialized. The core.Node object represents the running node with p2p and RPC capabilities, while the Backend gives you access to blocks and other data you may need to access.
Specialization
==============
From this point implimentation becomes more specialized to the particular plugin type. Continue from here for specific instructions for the following plugins:
* :ref:`RPC_method`
* :ref:`subscription`
* :ref:`tracer`
.. _blockupdates: https://github.com/openrelayxyz/plugeth-plugins/blob/master/packages/blockupdates/main.go
.. _hello: https://github.com/openrelayxyz/plugeth-plugins/blob/master/packages/hello/main.go

7
docs/hook_writing.rst Normal file
View File

@ -0,0 +1,7 @@
.. _hook_writing:
==================
Hook Writing Guide
==================
.. todo:: Austin: guide to writing plugin hooks

117
docs/hooks.rst
View File

@ -1,29 +1,41 @@
.. _hooks:
============
=====================
Selected Plugin Hooks
=====================
Plugin Hooks
============
The key to understanding a plugin is understanding its corresponding hook. Broadly, plugin hooks can be thought of as functions which deliver a function signiture to the **plugin loader**. The signature matches that of the function(s) called by the plugin and describes the data that is being captured and how the plugin will deliver said data upon invocation.
The public plugin hook function should follow the naming convention ``Plugin$HookName``. The first argument should be a `` core.PluginLoader``, followed by any arguments required by the functions to be provided by any plugins implementing this hook.
**Public and Private Hook Functions**
Each hook provides both a Public and private version. The private plugin hook function should bear the same name as the public plugin hook function, but with a lower case first letter. The signature should match the public plugin hook function, except that the first argument referencing the PluginLoader should be removed. It should invoke the public plugin hook function on plugins.DefaultPluginLoader. It should always verify that the DefaultPluginLoader is non-nil, log warning and return if the DefaultPluginLoader has not been initialized.
**Invocation**
the private plugin hook function should be invoked, with the appropriate arguments, in a single line within the Geth codebase inorder to minimize unexpected conflicts merging upstream Geth into plugeth.
Selected Hooks
--------------
`StateUpdate`_
************
`Invocation`_
Plugeth provides several :ref:`hooks` from which the plugin can capture data from Geth. Additionally in the case of **subcommands** the provided hooks are designed to change the behavior of Geth.
Hooks are called from functions within the plugin. For example, if we wanted to bring in data from the StateUpdate hook. We would impliment it like so:
(from `blockupdates`_)
.. code-block:: Go
func StateUpdate(blockRoot core.Hash, parentRoot core.Hash, destructs map[core.Hash]struct{}, accounts map[core.Hash][]byte, storage map[core.Hash]map[core.Hash][]byte, codeUpdates map[core.Hash][]byte) {
su := &stateUpdate{
Destructs: destructs,
Accounts: accounts,
Storage: storage,
Code: codeUpdates,
}
cache.Add(blockRoot, su)
data, _ := rlp.EncodeToBytes(su)
backend.ChainDb().Put(append([]byte("su"), blockRoot.Bytes()...), data)
}
Many hooks can be deployed in an one plugin as is the case with the **BlockUpdater** plugin.
.. contents:: :local:
StateUpdate
***********
**Function Signature**:``func(root common.Hash, parentRoot common.Hash, destructs map[common.Hash]struct{}, accounts map[common.Hash][]byte, storage map[common.Hash]map[common.Hash][]byte)``
The state update plugin provides a snapshot of the state subsystem in the form of a a stateUpdate object. The stateUpdate object contains all information transformed by a transaction but not the transaction itself.
@ -33,30 +45,75 @@ Invoked for each new block, StateUpdate provides the changes to the blockchain s
``-snapshots=true``. This is the default behavior for Geth, but if you are explicitly running with ``--snapshot=false`` this function will not be invoked.
`AppendAncient`_
AppendAncient
*************
**Function Signature**:``func(number uint64, hash, header, body, receipts, td []byte)``
Invoked when the freezer moves a block from LevelDB to the ancients database. ``number`` is the number of the block. ``hash`` is the 32 byte hash of the block as a raw ``[]byte``. ``header``, ``body``, and ``receipts`` are the RLP encoded versions of their respective block elements. ``td`` is the byte encoded total difficulty of the block.
`NewHead`_
**********
GetRPCCalls
***********
Invoked when a new block becomes the canonical latest block. Note that if several blocks are processed in a group (such as during a reorg) this may not be called for each block. You should track the prior latest head if you need to process intermediate blocks.
**Function Signature**:``func(string, string, string)``
`GetRPCCalls`_
Invoked when the RPC handler registers a method call. Returns the call ``id``, method ``name``, and any ``params`` that may have been passed in.
.. todo:: missing a couple of hooks
PreProcessBlock
***************
**Function Signature**:``func(*types.Block)``
Invoked before the transactions of a block are processed. Returns a block object.
PreProcessTransaction
*********************
**Function Signature**:``func(*types.Transaction, *types.Block, int)``
Invoked before each individual transaction of a block is processed. Returns a transaction, block, and index number.
BlockProcessingError
********************
**Function Signature**:``func(*types.Transaction, *types.Block, error)``
Invoked if an error occurs while processing a transaction. This only applies to errors that would unvalidate the block were this transaction is included not errors such as reverts or opcode errors. Returns a transaction, block, and error.
NewHead
*******
**Function Signature**:``func(*types.Block, common.Hash, []*types.Log)``
Invoked when a new block becomes the canonical latest block. Returns a block, hash, and log.
.. note:: If severtal blocks are processed in a group (such as
during a reorg) this may not be called for each block. You should track the prior latest head if you need to process intermediate blocks.
NewSideBlock
************
Invoked when the RPC handler registers a method call. returns the call ``id``, method ``name``, and any ``params`` that may have been passed in.
**Function Signature**:``func(*types.Block, common.Hash, []*types.Log)``
Invoked when a block is side-chained. Returns a block, has, and logs.
.. note:: Blocks passed to this method are non-canonical blocks.
Reorg
*****
**I am struggling all of assudden with if this is really this best course of action. Giving all of this reference, seems to beg the -utils vs plugeth conversation and I am not sure that is a smart thing to get into.**
**Function Signature**:``func(common *types.Block, oldChain, newChain types.Blocks)``
Invoked when a chain reorg occurs, that is; at least one block is removed and one block is added. (``oldChain`` is a list of removed blocks, ``newChain`` is a list of newliy added blocks, and ``common`` is the latest block that is an ancestor to both oldChain and newChain.) Returns a block, a list of old blocks, and a list of new blocks.
.. _blockupdates: https://github.com/openrelayxyz/plugeth-plugins/tree/master/packages/blockupdates
.. _StateUpdate: https://github.com/openrelayxyz/plugeth/blob/develop/core/state/plugin_hooks.go
.. _Invocation: https://github.com/openrelayxyz/plugeth/blob/develop/core/state/statedb.go#L955
.. _AppendAncient: https://github.com/openrelayxyz/plugeth/blob/develop/core/rawdb/plugin_hooks.go

Some files were not shown because too many files have changed in this diff Show More