Plugin hooks initial work

documentation/_build/html/_sources/anatomy.rst.txt

@@ -4,4 +4,40 @@
 Plugin Anatomy
 ==============
 
-.. todo:: fill in disections of archetypal plugins 
+.. todo:: fill in disections of archetypal plugins
+
+.. 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,
+		},
+	}
+}``

documentation/_build/html/_sources/api.rst.txt

@@ -46,7 +46,7 @@ Tracers
 
 .. code-block:: go
 
-   ``// CaptureStart is called at the start of each transaction
+   // 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) {}
@@ -55,12 +55,78 @@ Tracers
    // 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) {}``
+   GetResult() (interface{}, error) {}
 
 
 .. warning:: Modifying the values passed into tracer functions can
              alter the 
-             results of the EVM execution in unpredictable ways. Additonally, some objects may be reused acress calls, so data you wish to capture should be copied rather than retianed by reference. 
+             results of the EVM execution in unpredictable ways. Additopackage 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,
+    },
+  }
+}
+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,
+    },
+  }
+}
+nally, some objects may be reused acress calls, so data you wish to capture should be copied rather than retianed by reference. 
 
 LiveTracer
 ----------

documentation/_build/html/_sources/hooks.rst.txt

@@ -4,4 +4,61 @@
 Plugin Hooks
 ============
 
-.. todo:: discussion of 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`_
+
+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`_
+*************
+
+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`_
+**********
+
+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.
+
+`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.  
+
+
+
+**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.**
+
+
+
+
+
+
+.. _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

documentation/_build/html/_sources/index.rst.txt

@@ -25,7 +25,6 @@ Table of Contents
 
     project
     types
-    hooks
     anatomy
     
 
@@ -41,7 +40,7 @@ Table of Contents
 
     system_req
     plugin_loader
-    plugin_hooks
+    hooks
     core_restricted
     api
 

documentation/_build/html/anatomy.html

@@ -16,7 +16,7 @@
     <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="Plugin Hooks" href="hooks.html" /> 
+    <link rel="prev" title="Basic Types of Plugins" href="types.html" /> 
 </head>
 
 <body class="wy-body-for-nav"> 
@@ -38,7 +38,6 @@
 <ul class="current">
 <li class="toctree-l1"><a class="reference internal" href="project.html">Project Design</a></li>
 <li class="toctree-l1"><a class="reference internal" href="types.html">Basic Types of Plugins</a></li>
-<li class="toctree-l1"><a class="reference internal" href="hooks.html">Plugin Hooks</a></li>
 <li class="toctree-l1 current"><a class="current reference internal" href="#">Plugin Anatomy</a></li>
 </ul>
 <p class="caption"><span class="caption-text">Tutorials</span></p>
@@ -49,7 +48,7 @@
 <ul>
 <li class="toctree-l1"><a class="reference internal" href="system_req.html">System Requirements</a></li>
 <li class="toctree-l1"><a class="reference internal" href="plugin_loader.html">Plugin Loader</a></li>
-<li class="toctree-l1"><a class="reference internal" href="plugin_hooks.html">Plugin Hooks</a></li>
+<li class="toctree-l1"><a class="reference internal" href="hooks.html">Plugin Hooks</a></li>
 <li class="toctree-l1"><a class="reference internal" href="core_restricted.html">Core vs Restricted packages in Plugeth-utils</a></li>
 <li class="toctree-l1"><a class="reference internal" href="api.html">API</a></li>
 </ul>
@@ -88,13 +87,56 @@
 <p class="admonition-title">Todo</p>
 <p>fill in disections of archetypal plugins</p>
 </div>
+<div class="highlight-go notranslate"><div class="highlight"><pre><span></span><span class="kn">package</span> <span class="nx">main</span>
+</pre></div>
+</div>
+<dl class="simple">
+<dt>import (</dt><dd><p>“github.com/openrelayxyz/plugeth-utils/core”
+“gopkg.in/urfave/cli.v1”</p>
+</dd>
+</dl>
+<p>)</p>
+<dl class="simple">
+<dt>var (</dt><dd><p>log core.Logger</p>
+</dd>
+</dl>
+<p>)</p>
+<p>type myservice struct{}</p>
+<dl class="simple">
+<dt>func (<a href="#id2"><span class="problematic" id="id3">*</span></a>myservice) Hello() string {</dt><dd><p>return “Hello world”</p>
+</dd>
+</dl>
+<p>}</p>
+<dl class="simple">
+<dt>func Initialize(ctx <a href="#id4"><span class="problematic" id="id5">*</span></a>cli.Context, loader core.PluginLoader, logger core.Logger) {</dt><dd><p>log = logger
+log.Info(“Initialized hello”)</p>
+</dd>
+</dl>
+<p>}</p>
+<dl>
+<dt>func GetAPIs(node core.Node, backend core.Backend) []core.API {</dt><dd><p>defer log.Info(“APIs Initialized”)
+return []core.API{</p>
+<blockquote>
+<div><dl class="simple">
+<dt>{</dt><dd><p>Namespace: “mynamespace”,
+Version:   “1.0”,
+Service:   &amp;myservice{},
+Public:    true,</p>
+</dd>
+</dl>
+<p>},</p>
+</div></blockquote>
+<p>}</p>
+</dd>
+</dl>
+<p>}``</p>
 </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="Plugin Hooks" 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-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>
 

documentation/_build/html/api.html

@@ -38,7 +38,6 @@
 <ul>
 <li class="toctree-l1"><a class="reference internal" href="project.html">Project Design</a></li>
 <li class="toctree-l1"><a class="reference internal" href="types.html">Basic Types of Plugins</a></li>
-<li class="toctree-l1"><a class="reference internal" href="hooks.html">Plugin Hooks</a></li>
 <li class="toctree-l1"><a class="reference internal" href="anatomy.html">Plugin Anatomy</a></li>
 </ul>
 <p class="caption"><span class="caption-text">Tutorials</span></p>
@@ -49,7 +48,7 @@
 <ul class="current">
 <li class="toctree-l1"><a class="reference internal" href="system_req.html">System Requirements</a></li>
 <li class="toctree-l1"><a class="reference internal" href="plugin_loader.html">Plugin Loader</a></li>
-<li class="toctree-l1"><a class="reference internal" href="plugin_hooks.html">Plugin Hooks</a></li>
+<li class="toctree-l1"><a class="reference internal" href="hooks.html">Plugin Hooks</a></li>
 <li class="toctree-l1"><a class="reference internal" href="core_restricted.html">Core vs Restricted packages in Plugeth-utils</a></li>
 <li class="toctree-l1 current"><a class="current reference internal" href="#">API</a><ul>
 <li class="toctree-l2"><a class="reference internal" href="#flags">Flags</a></li>
@@ -138,7 +137,7 @@ restricted.backend</p>
 <li><p><strong>Type:</strong> map[string]TracerResult</p></li>
 <li><p><strong>Behavior:</strong> When calling debug.traceX functions (such as <code class="docutils literal notranslate"><span class="pre">debug_traceCall</span></code> and <code class="docutils literal notranslate"><span class="pre">debug_traceTransaction</span></code>) the tracer can be specified as a key to this map and the tracer used will be the TracerResult specified here. TracerResult objects must match the interface:</p></li>
 </ul>
-<div class="highlight-go notranslate"><div class="highlight"><pre><span></span><span class="s">``</span><span class="c1">// CaptureStart is called at the start of each transaction</span>
+<div class="highlight-go notranslate"><div class="highlight"><pre><span></span><span class="c1">// CaptureStart is called at the start of each transaction</span>
 <span class="nx">CaptureStart</span><span class="p">(</span><span class="nx">env</span> <span class="nx">core</span><span class="p">.</span><span class="nx">EVM</span><span class="p">,</span> <span class="nx">from</span> <span class="nx">core</span><span class="p">.</span><span class="nx">Address</span><span class="p">,</span> <span class="nx">to</span> <span class="nx">core</span><span class="p">.</span><span class="nx">Address</span><span class="p">,</span> <span class="nx">create</span> <span class="kt">bool</span><span class="p">,</span> <span class="nx">input</span> <span class="p">[]</span><span class="kt">byte</span><span class="p">,</span> <span class="nx">gas</span> <span class="kt">uint64</span><span class="p">,</span> <span class="nx">value</span> <span class="o">*</span><span class="nx">big</span><span class="p">.</span><span class="nx">Int</span><span class="p">)</span> <span class="p">{}</span>
 <span class="c1">// CaptureState is called for each opcode</span>
 <span class="nx">CaptureState</span><span class="p">(</span><span class="nx">env</span> <span class="nx">core</span><span class="p">.</span><span class="nx">EVM</span><span class="p">,</span> <span class="nx">pc</span> <span class="kt">uint64</span><span class="p">,</span> <span class="nx">op</span> <span class="nx">core</span><span class="p">.</span><span class="nx">OpCode</span><span class="p">,</span> <span class="nx">gas</span><span class="p">,</span> <span class="nx">cost</span> <span class="kt">uint64</span><span class="p">,</span> <span class="nx">scope</span> <span class="o">*</span><span class="nx">vm</span><span class="p">.</span><span class="nx">ScopeContext</span><span class="p">,</span> <span class="nx">rData</span> <span class="p">[]</span><span class="kt">byte</span><span class="p">,</span> <span class="nx">depth</span> <span class="kt">int</span><span class="p">,</span> <span class="nx">err</span> <span class="kt">error</span><span class="p">)</span> <span class="p">{}</span>
@@ -147,15 +146,97 @@ restricted.backend</p>
 <span class="c1">// CaptureEnd is called at the end of each transaction</span>
 <span class="nx">CaptureEnd</span><span class="p">(</span><span class="nx">output</span> <span class="p">[]</span><span class="kt">byte</span><span class="p">,</span> <span class="nx">gasUsed</span> <span class="kt">uint64</span><span class="p">,</span> <span class="nx">t</span> <span class="nx">time</span><span class="p">.</span><span class="nx">Duration</span><span class="p">,</span> <span class="nx">err</span> <span class="kt">error</span><span class="p">)</span> <span class="p">{}</span>
 <span class="c1">// GetResult should return a JSON serializable result object to respond to the trace call</span>
-<span class="nx">GetResult</span><span class="p">()</span> <span class="p">(</span><span class="kd">interface</span><span class="p">{},</span> <span class="kt">error</span><span class="p">)</span> <span class="p">{}</span><span class="s">``</span>
+<span class="nx">GetResult</span><span class="p">()</span> <span class="p">(</span><span class="kd">interface</span><span class="p">{},</span> <span class="kt">error</span><span class="p">)</span> <span class="p">{}</span>
 </pre></div>
 </div>
 <div class="admonition warning">
 <p class="admonition-title">Warning</p>
 <p>Modifying the values passed into tracer functions can
 alter the
-results of the EVM execution in unpredictable ways. Additonally, some objects may be reused acress calls, so data you wish to capture should be copied rather than retianed by reference.</p>
+results of the EVM execution in unpredictable ways. Additopackage main</p>
 </div>
+<dl class="simple">
+<dt>import (</dt><dd><p>“github.com/openrelayxyz/plugeth-utils/core”
+“gopkg.in/urfave/cli.v1”</p>
+</dd>
+</dl>
+<p>)</p>
+<dl class="simple">
+<dt>var (</dt><dd><p>log core.Logger</p>
+</dd>
+</dl>
+<p>)</p>
+<p>type myservice struct{}</p>
+<dl class="simple">
+<dt>func (<a href="#id5"><span class="problematic" id="id6">*</span></a>myservice) Hello() string {</dt><dd><p>return “Hello world”</p>
+</dd>
+</dl>
+<p>}</p>
+<dl class="simple">
+<dt>func Initialize(ctx <a href="#id7"><span class="problematic" id="id8">*</span></a>cli.Context, loader core.PluginLoader, logger core.Logger) {</dt><dd><p>log = logger
+log.Info(“Initialized hello”)</p>
+</dd>
+</dl>
+<p>}</p>
+<dl>
+<dt>func GetAPIs(node core.Node, backend core.Backend) []core.API {</dt><dd><p>defer log.Info(“APIs Initialized”)
+return []core.API{</p>
+<blockquote>
+<div><dl class="simple">
+<dt>{</dt><dd><p>Namespace: “mynamespace”,
+Version:   “1.0”,
+Service:   &amp;myservice{},
+Public:    true,</p>
+</dd>
+</dl>
+<p>},</p>
+</div></blockquote>
+<p>}</p>
+</dd>
+</dl>
+<p>}
+package main</p>
+<dl class="simple">
+<dt>import (</dt><dd><p>“github.com/openrelayxyz/plugeth-utils/core”
+“gopkg.in/urfave/cli.v1”</p>
+</dd>
+</dl>
+<p>)</p>
+<dl class="simple">
+<dt>var (</dt><dd><p>log core.Logger</p>
+</dd>
+</dl>
+<p>)</p>
+<p>type myservice struct{}</p>
+<dl class="simple">
+<dt>func (<a href="#id9"><span class="problematic" id="id10">*</span></a>myservice) Hello() string {</dt><dd><p>return “Hello world”</p>
+</dd>
+</dl>
+<p>}</p>
+<dl class="simple">
+<dt>func Initialize(ctx <a href="#id11"><span class="problematic" id="id12">*</span></a>cli.Context, loader core.PluginLoader, logger core.Logger) {</dt><dd><p>log = logger
+log.Info(“Initialized hello”)</p>
+</dd>
+</dl>
+<p>}</p>
+<dl>
+<dt>func GetAPIs(node core.Node, backend core.Backend) []core.API {</dt><dd><p>defer log.Info(“APIs Initialized”)
+return []core.API{</p>
+<blockquote>
+<div><dl class="simple">
+<dt>{</dt><dd><p>Namespace: “mynamespace”,
+Version:   “1.0”,
+Service:   &amp;myservice{},
+Public:    true,</p>
+</dd>
+</dl>
+<p>},</p>
+</div></blockquote>
+<p>}</p>
+</dd>
+</dl>
+<p>}
+nally, some objects may be reused acress calls, so data you wish to capture should be copied rather than retianed by reference.</p>
 </div>
 <div class="section" id="livetracer">
 <h2>LiveTracer<a class="headerlink" href="#livetracer" title="Permalink to this headline">¶</a></h2>

documentation/_build/html/build.html

@@ -38,7 +38,6 @@
 <ul>
 <li class="toctree-l1"><a class="reference internal" href="project.html">Project Design</a></li>
 <li class="toctree-l1"><a class="reference internal" href="types.html">Basic Types of Plugins</a></li>
-<li class="toctree-l1"><a class="reference internal" href="hooks.html">Plugin Hooks</a></li>
 <li class="toctree-l1"><a class="reference internal" href="anatomy.html">Plugin Anatomy</a></li>
 </ul>
 <p class="caption"><span class="caption-text">Tutorials</span></p>
@@ -53,7 +52,7 @@
 <ul>
 <li class="toctree-l1"><a class="reference internal" href="system_req.html">System Requirements</a></li>
 <li class="toctree-l1"><a class="reference internal" href="plugin_loader.html">Plugin Loader</a></li>
-<li class="toctree-l1"><a class="reference internal" href="plugin_hooks.html">Plugin Hooks</a></li>
+<li class="toctree-l1"><a class="reference internal" href="hooks.html">Plugin Hooks</a></li>
 <li class="toctree-l1"><a class="reference internal" href="core_restricted.html">Core vs Restricted packages in Plugeth-utils</a></li>
 <li class="toctree-l1"><a class="reference internal" href="api.html">API</a></li>
 </ul>

documentation/_build/html/contact.html

@@ -37,7 +37,6 @@
 <ul>
 <li class="toctree-l1"><a class="reference internal" href="project.html">Project Design</a></li>
 <li class="toctree-l1"><a class="reference internal" href="types.html">Basic Types of Plugins</a></li>
-<li class="toctree-l1"><a class="reference internal" href="hooks.html">Plugin Hooks</a></li>
 <li class="toctree-l1"><a class="reference internal" href="anatomy.html">Plugin Anatomy</a></li>
 </ul>
 <p class="caption"><span class="caption-text">Tutorials</span></p>
@@ -48,7 +47,7 @@
 <ul>
 <li class="toctree-l1"><a class="reference internal" href="system_req.html">System Requirements</a></li>
 <li class="toctree-l1"><a class="reference internal" href="plugin_loader.html">Plugin Loader</a></li>
-<li class="toctree-l1"><a class="reference internal" href="plugin_hooks.html">Plugin Hooks</a></li>
+<li class="toctree-l1"><a class="reference internal" href="hooks.html">Plugin Hooks</a></li>
 <li class="toctree-l1"><a class="reference internal" href="core_restricted.html">Core vs Restricted packages in Plugeth-utils</a></li>
 <li class="toctree-l1"><a class="reference internal" href="api.html">API</a></li>
 </ul>

documentation/_build/html/core_restricted.html

@@ -16,7 +16,7 @@
     <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="Plugin Hooks" href="plugin_hooks.html" /> 
+    <link rel="prev" title="Plugin Hooks" href="hooks.html" /> 
 </head>
 
 <body class="wy-body-for-nav"> 
@@ -38,7 +38,6 @@
 <ul>
 <li class="toctree-l1"><a class="reference internal" href="project.html">Project Design</a></li>
 <li class="toctree-l1"><a class="reference internal" href="types.html">Basic Types of Plugins</a></li>
-<li class="toctree-l1"><a class="reference internal" href="hooks.html">Plugin Hooks</a></li>
 <li class="toctree-l1"><a class="reference internal" href="anatomy.html">Plugin Anatomy</a></li>
 </ul>
 <p class="caption"><span class="caption-text">Tutorials</span></p>
@@ -49,7 +48,7 @@
 <ul class="current">
 <li class="toctree-l1"><a class="reference internal" href="system_req.html">System Requirements</a></li>
 <li class="toctree-l1"><a class="reference internal" href="plugin_loader.html">Plugin Loader</a></li>
-<li class="toctree-l1"><a class="reference internal" href="plugin_hooks.html">Plugin Hooks</a></li>
+<li class="toctree-l1"><a class="reference internal" href="hooks.html">Plugin Hooks</a></li>
 <li class="toctree-l1 current"><a class="current reference internal" href="#">Core vs Restricted packages in Plugeth-utils</a></li>
 <li class="toctree-l1"><a class="reference internal" href="api.html">API</a></li>
 </ul>
@@ -94,7 +93,7 @@
            </div>
           </div>
           <footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
-        <a href="plugin_hooks.html" class="btn btn-neutral float-left" title="Plugin Hooks" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
+        <a href="hooks.html" class="btn btn-neutral float-left" title="Plugin Hooks" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
         <a href="api.html" class="btn btn-neutral float-right" title="API" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
     </div>
 

documentation/_build/html/genindex.html

@@ -36,7 +36,6 @@
 <ul>
 <li class="toctree-l1"><a class="reference internal" href="project.html">Project Design</a></li>
 <li class="toctree-l1"><a class="reference internal" href="types.html">Basic Types of Plugins</a></li>
-<li class="toctree-l1"><a class="reference internal" href="hooks.html">Plugin Hooks</a></li>
 <li class="toctree-l1"><a class="reference internal" href="anatomy.html">Plugin Anatomy</a></li>
 </ul>
 <p class="caption"><span class="caption-text">Tutorials</span></p>
@@ -47,7 +46,7 @@
 <ul>
 <li class="toctree-l1"><a class="reference internal" href="system_req.html">System Requirements</a></li>
 <li class="toctree-l1"><a class="reference internal" href="plugin_loader.html">Plugin Loader</a></li>
-<li class="toctree-l1"><a class="reference internal" href="plugin_hooks.html">Plugin Hooks</a></li>
+<li class="toctree-l1"><a class="reference internal" href="hooks.html">Plugin Hooks</a></li>
 <li class="toctree-l1"><a class="reference internal" href="core_restricted.html">Core vs Restricted packages in Plugeth-utils</a></li>
 <li class="toctree-l1"><a class="reference internal" href="api.html">API</a></li>
 </ul>

documentation/_build/html/hooks.html

@@ -15,8 +15,8 @@
     <script src="_static/js/theme.js"></script>
     <link rel="index" title="Index" href="genindex.html" />
     <link rel="search" title="Search" href="search.html" />
-    <link rel="next" title="Plugin Anatomy" href="anatomy.html" />
+    <link rel="next" title="Core vs Restricted packages in Plugeth-utils" href="core_restricted.html" />
-    <link rel="prev" title="Basic Types of Plugins" href="types.html" /> 
+    <link rel="prev" title="Plugin Loader" href="plugin_loader.html" /> 
 </head>
 
 <body class="wy-body-for-nav"> 
@@ -35,10 +35,9 @@
 </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">
+<ul>
 <li class="toctree-l1"><a class="reference internal" href="project.html">Project Design</a></li>
 <li class="toctree-l1"><a class="reference internal" href="types.html">Basic Types of Plugins</a></li>
-<li class="toctree-l1 current"><a class="current reference internal" href="#">Plugin Hooks</a></li>
 <li class="toctree-l1"><a class="reference internal" href="anatomy.html">Plugin Anatomy</a></li>
 </ul>
 <p class="caption"><span class="caption-text">Tutorials</span></p>
@@ -46,10 +45,19 @@
 <li class="toctree-l1"><a class="reference internal" href="build.html">Build and Deploy</a></li>
 </ul>
 <p class="caption"><span class="caption-text">Reference</span></p>
-<ul>
+<ul class="current">
 <li class="toctree-l1"><a class="reference internal" href="system_req.html">System Requirements</a></li>
 <li class="toctree-l1"><a class="reference internal" href="plugin_loader.html">Plugin Loader</a></li>
-<li class="toctree-l1"><a class="reference internal" href="plugin_hooks.html">Plugin Hooks</a></li>
+<li class="toctree-l1 current"><a class="current reference internal" href="#">Plugin Hooks</a><ul>
+<li class="toctree-l2"><a class="reference internal" href="#selected-hooks">Selected Hooks</a><ul>
+<li class="toctree-l3"><a class="reference internal" href="#stateupdate">StateUpdate</a></li>
+<li class="toctree-l3"><a class="reference internal" href="#appendancient">AppendAncient</a></li>
+<li class="toctree-l3"><a class="reference internal" href="#newhead">NewHead</a></li>
+<li class="toctree-l3"><a class="reference internal" href="#getrpccalls">GetRPCCalls</a></li>
+</ul>
+</li>
+</ul>
+</li>
 <li class="toctree-l1"><a class="reference internal" href="core_restricted.html">Core vs Restricted packages in Plugeth-utils</a></li>
 <li class="toctree-l1"><a class="reference internal" href="api.html">API</a></li>
 </ul>
@@ -84,9 +92,38 @@
              
   <div class="section" id="plugin-hooks">
 <span id="hooks"></span><h1>Plugin Hooks<a class="headerlink" href="#plugin-hooks" title="Permalink to this headline">¶</a></h1>
-<div class="admonition-todo admonition" id="id1">
+<p>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 <strong>plugin loader</strong>. 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.</p>
-<p class="admonition-title">Todo</p>
+<p>The public plugin hook function should follow the naming convention <code class="docutils literal notranslate"><span class="pre">Plugin$HookName</span></code>. 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.</p>
-<p>discussion of plugin hooks</p>
+<p><strong>Public and Private Hook Functions</strong></p>
+<p>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.</p>
+<p><strong>Invocation</strong></p>
+<p>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.</p>
+<div class="section" id="selected-hooks">
+<h2>Selected Hooks<a class="headerlink" href="#selected-hooks" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="stateupdate">
+<h3><a class="reference external" href="https://github.com/openrelayxyz/plugeth/blob/develop/core/state/plugin_hooks.go">StateUpdate</a><a class="headerlink" href="#stateupdate" title="Permalink to this headline">¶</a></h3>
+<p><a class="reference external" href="https://github.com/openrelayxyz/plugeth/blob/develop/core/state/statedb.go#L955">Invocation</a></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">
+<h3><a class="reference external" href="https://github.com/openrelayxyz/plugeth/blob/develop/core/rawdb/plugin_hooks.go">AppendAncient</a><a class="headerlink" href="#appendancient" title="Permalink to this headline">¶</a></h3>
+<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="newhead">
+<h3><a class="reference external" href="https://github.com/openrelayxyz/plugeth/blob/develop/core/plugin_hooks.go#L108">NewHead</a><a class="headerlink" href="#newhead" title="Permalink to this headline">¶</a></h3>
+<p>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.</p>
+</div>
+<div class="section" id="getrpccalls">
+<h3><a class="reference external" href="https://github.com/openrelayxyz/plugeth/blob/develop/rpc/plugin_hooks.go">GetRPCCalls</a><a class="headerlink" href="#getrpccalls" title="Permalink to this headline">¶</a></h3>
+<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>
+<p><strong>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.</strong></p>
+</div>
 </div>
 </div>
 
@@ -94,8 +131,8 @@
            </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="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="anatomy.html" class="btn btn-neutral float-right" title="Plugin Anatomy" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
+        <a href="core_restricted.html" class="btn btn-neutral float-right" title="Core vs Restricted packages in Plugeth-utils" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
     </div>
 
   <hr/>

documentation/_build/html/index.html

@@ -37,7 +37,6 @@
 <ul>
 <li class="toctree-l1"><a class="reference internal" href="project.html">Project Design</a></li>
 <li class="toctree-l1"><a class="reference internal" href="types.html">Basic Types of Plugins</a></li>
-<li class="toctree-l1"><a class="reference internal" href="hooks.html">Plugin Hooks</a></li>
 <li class="toctree-l1"><a class="reference internal" href="anatomy.html">Plugin Anatomy</a></li>
 </ul>
 <p class="caption"><span class="caption-text">Tutorials</span></p>
@@ -48,7 +47,7 @@
 <ul>
 <li class="toctree-l1"><a class="reference internal" href="system_req.html">System Requirements</a></li>
 <li class="toctree-l1"><a class="reference internal" href="plugin_loader.html">Plugin Loader</a></li>
-<li class="toctree-l1"><a class="reference internal" href="plugin_hooks.html">Plugin Hooks</a></li>
+<li class="toctree-l1"><a class="reference internal" href="hooks.html">Plugin Hooks</a></li>
 <li class="toctree-l1"><a class="reference internal" href="core_restricted.html">Core vs Restricted packages in Plugeth-utils</a></li>
 <li class="toctree-l1"><a class="reference internal" href="api.html">API</a></li>
 </ul>
@@ -98,7 +97,6 @@ perspective, PluGeth should be as stable as upstream Geth less whatever isstabil
 <ul>
 <li class="toctree-l1"><a class="reference internal" href="project.html">Project Design</a></li>
 <li class="toctree-l1"><a class="reference internal" href="types.html">Basic Types of Plugins</a></li>
-<li class="toctree-l1"><a class="reference internal" href="hooks.html">Plugin Hooks</a></li>
 <li class="toctree-l1"><a class="reference internal" href="anatomy.html">Plugin Anatomy</a></li>
 </ul>
 </div>
@@ -113,7 +111,7 @@ perspective, PluGeth should be as stable as upstream Geth less whatever isstabil
 <ul>
 <li class="toctree-l1"><a class="reference internal" href="system_req.html">System Requirements</a></li>
 <li class="toctree-l1"><a class="reference internal" href="plugin_loader.html">Plugin Loader</a></li>
-<li class="toctree-l1"><a class="reference internal" href="plugin_hooks.html">Plugin Hooks</a></li>
+<li class="toctree-l1"><a class="reference internal" href="hooks.html">Plugin Hooks</a></li>
 <li class="toctree-l1"><a class="reference internal" href="core_restricted.html">Core vs Restricted packages in Plugeth-utils</a></li>
 <li class="toctree-l1"><a class="reference internal" href="api.html">API</a></li>
 </ul>

documentation/_build/html/plugeth.html

@@ -36,7 +36,6 @@
 <ul>
 <li class="toctree-l1"><a class="reference internal" href="project.html">Project Design</a></li>
 <li class="toctree-l1"><a class="reference internal" href="types.html">Basic Types of Plugins</a></li>
-<li class="toctree-l1"><a class="reference internal" href="hooks.html">Plugin Hooks</a></li>
 <li class="toctree-l1"><a class="reference internal" href="anatomy.html">Plugin Anatomy</a></li>
 </ul>
 <p class="caption"><span class="caption-text">Tutorials</span></p>
@@ -47,7 +46,7 @@
 <ul>
 <li class="toctree-l1"><a class="reference internal" href="system_req.html">System Requirements</a></li>
 <li class="toctree-l1"><a class="reference internal" href="plugin_loader.html">Plugin Loader</a></li>
-<li class="toctree-l1"><a class="reference internal" href="plugin_hooks.html">Plugin Hooks</a></li>
+<li class="toctree-l1"><a class="reference internal" href="hooks.html">Plugin Hooks</a></li>
 <li class="toctree-l1"><a class="reference internal" href="core_restricted.html">Core vs Restricted packages in Plugeth-utils</a></li>
 <li class="toctree-l1"><a class="reference internal" href="api.html">API</a></li>
 </ul>

documentation/_build/html/plugin_hooks.html

@@ -14,9 +14,7 @@
         <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="search" title="Search" href="search.html" /> 
-    <link rel="next" title="Core vs Restricted packages in Plugeth-utils" href="core_restricted.html" />
-    <link rel="prev" title="Plugin Loader" href="plugin_loader.html" /> 
 </head>
 
 <body class="wy-body-for-nav"> 
@@ -38,7 +36,6 @@
 <ul>
 <li class="toctree-l1"><a class="reference internal" href="project.html">Project Design</a></li>
 <li class="toctree-l1"><a class="reference internal" href="types.html">Basic Types of Plugins</a></li>
-<li class="toctree-l1"><a class="reference internal" href="hooks.html">Plugin Hooks</a></li>
 <li class="toctree-l1"><a class="reference internal" href="anatomy.html">Plugin Anatomy</a></li>
 </ul>
 <p class="caption"><span class="caption-text">Tutorials</span></p>
@@ -46,10 +43,10 @@
 <li class="toctree-l1"><a class="reference internal" href="build.html">Build and Deploy</a></li>
 </ul>
 <p class="caption"><span class="caption-text">Reference</span></p>
-<ul class="current">
+<ul>
 <li class="toctree-l1"><a class="reference internal" href="system_req.html">System Requirements</a></li>
 <li class="toctree-l1"><a class="reference internal" href="plugin_loader.html">Plugin Loader</a></li>
-<li class="toctree-l1 current"><a class="current reference internal" href="#">Plugin Hooks</a></li>
+<li class="toctree-l1"><a class="reference internal" href="hooks.html">Plugin Hooks</a></li>
 <li class="toctree-l1"><a class="reference internal" href="core_restricted.html">Core vs Restricted packages in Plugeth-utils</a></li>
 <li class="toctree-l1"><a class="reference internal" href="api.html">API</a></li>
 </ul>
@@ -93,10 +90,7 @@
 
            </div>
           </div>
-          <footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
+          <footer>
-        <a href="plugin_loader.html" class="btn btn-neutral float-left" title="Plugin Loader" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
-        <a href="core_restricted.html" class="btn btn-neutral float-right" title="Core vs Restricted packages in Plugeth-utils" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
-    </div>
 
   <hr/>
 

documentation/_build/html/plugin_loader.html

@@ -15,7 +15,7 @@
     <script src="_static/js/theme.js"></script>
     <link rel="index" title="Index" href="genindex.html" />
     <link rel="search" title="Search" href="search.html" />
-    <link rel="next" title="Plugin Hooks" href="plugin_hooks.html" />
+    <link rel="next" title="Plugin Hooks" href="hooks.html" />
     <link rel="prev" title="System Requirements" href="system_req.html" /> 
 </head>
 
@@ -38,7 +38,6 @@
 <ul>
 <li class="toctree-l1"><a class="reference internal" href="project.html">Project Design</a></li>
 <li class="toctree-l1"><a class="reference internal" href="types.html">Basic Types of Plugins</a></li>
-<li class="toctree-l1"><a class="reference internal" href="hooks.html">Plugin Hooks</a></li>
 <li class="toctree-l1"><a class="reference internal" href="anatomy.html">Plugin Anatomy</a></li>
 </ul>
 <p class="caption"><span class="caption-text">Tutorials</span></p>
@@ -49,7 +48,7 @@
 <ul class="current">
 <li class="toctree-l1"><a class="reference internal" href="system_req.html">System Requirements</a></li>
 <li class="toctree-l1 current"><a class="current reference internal" href="#">Plugin Loader</a></li>
-<li class="toctree-l1"><a class="reference internal" href="plugin_hooks.html">Plugin Hooks</a></li>
+<li class="toctree-l1"><a class="reference internal" href="hooks.html">Plugin Hooks</a></li>
 <li class="toctree-l1"><a class="reference internal" href="core_restricted.html">Core vs Restricted packages in Plugeth-utils</a></li>
 <li class="toctree-l1"><a class="reference internal" href="api.html">API</a></li>
 </ul>
@@ -95,7 +94,7 @@
           </div>
           <footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
         <a href="system_req.html" class="btn btn-neutral float-left" title="System Requirements" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
-        <a href="plugin_hooks.html" class="btn btn-neutral float-right" title="Plugin Hooks" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
+        <a href="hooks.html" class="btn btn-neutral float-right" title="Plugin Hooks" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
     </div>
 
   <hr/>

documentation/_build/html/plugins.html

@@ -36,7 +36,6 @@
 <ul>
 <li class="toctree-l1"><a class="reference internal" href="project.html">Project Design</a></li>
 <li class="toctree-l1"><a class="reference internal" href="types.html">Basic Types of Plugins</a></li>
-<li class="toctree-l1"><a class="reference internal" href="hooks.html">Plugin Hooks</a></li>
 <li class="toctree-l1"><a class="reference internal" href="anatomy.html">Plugin Anatomy</a></li>
 </ul>
 <p class="caption"><span class="caption-text">Tutorials</span></p>
@@ -47,7 +46,7 @@
 <ul>
 <li class="toctree-l1"><a class="reference internal" href="system_req.html">System Requirements</a></li>
 <li class="toctree-l1"><a class="reference internal" href="plugin_loader.html">Plugin Loader</a></li>
-<li class="toctree-l1"><a class="reference internal" href="plugin_hooks.html">Plugin Hooks</a></li>
+<li class="toctree-l1"><a class="reference internal" href="hooks.html">Plugin Hooks</a></li>
 <li class="toctree-l1"><a class="reference internal" href="core_restricted.html">Core vs Restricted packages in Plugeth-utils</a></li>
 <li class="toctree-l1"><a class="reference internal" href="api.html">API</a></li>
 </ul>

documentation/_build/html/project.html

@@ -47,7 +47,6 @@
 </ul>
 </li>
 <li class="toctree-l1"><a class="reference internal" href="types.html">Basic Types of Plugins</a></li>
-<li class="toctree-l1"><a class="reference internal" href="hooks.html">Plugin Hooks</a></li>
 <li class="toctree-l1"><a class="reference internal" href="anatomy.html">Plugin Anatomy</a></li>
 </ul>
 <p class="caption"><span class="caption-text">Tutorials</span></p>
@@ -58,7 +57,7 @@
 <ul>
 <li class="toctree-l1"><a class="reference internal" href="system_req.html">System Requirements</a></li>
 <li class="toctree-l1"><a class="reference internal" href="plugin_loader.html">Plugin Loader</a></li>
-<li class="toctree-l1"><a class="reference internal" href="plugin_hooks.html">Plugin Hooks</a></li>
+<li class="toctree-l1"><a class="reference internal" href="hooks.html">Plugin Hooks</a></li>
 <li class="toctree-l1"><a class="reference internal" href="core_restricted.html">Core vs Restricted packages in Plugeth-utils</a></li>
 <li class="toctree-l1"><a class="reference internal" href="api.html">API</a></li>
 </ul>

documentation/_build/html/search.html

@@ -39,7 +39,6 @@
 <ul>
 <li class="toctree-l1"><a class="reference internal" href="project.html">Project Design</a></li>
 <li class="toctree-l1"><a class="reference internal" href="types.html">Basic Types of Plugins</a></li>
-<li class="toctree-l1"><a class="reference internal" href="hooks.html">Plugin Hooks</a></li>
 <li class="toctree-l1"><a class="reference internal" href="anatomy.html">Plugin Anatomy</a></li>
 </ul>
 <p class="caption"><span class="caption-text">Tutorials</span></p>
@@ -50,7 +49,7 @@
 <ul>
 <li class="toctree-l1"><a class="reference internal" href="system_req.html">System Requirements</a></li>
 <li class="toctree-l1"><a class="reference internal" href="plugin_loader.html">Plugin Loader</a></li>
-<li class="toctree-l1"><a class="reference internal" href="plugin_hooks.html">Plugin Hooks</a></li>
+<li class="toctree-l1"><a class="reference internal" href="hooks.html">Plugin Hooks</a></li>
 <li class="toctree-l1"><a class="reference internal" href="core_restricted.html">Core vs Restricted packages in Plugeth-utils</a></li>
 <li class="toctree-l1"><a class="reference internal" href="api.html">API</a></li>
 </ul>

documentation/_build/html/system_req.html

@@ -38,7 +38,6 @@
 <ul>
 <li class="toctree-l1"><a class="reference internal" href="project.html">Project Design</a></li>
 <li class="toctree-l1"><a class="reference internal" href="types.html">Basic Types of Plugins</a></li>
-<li class="toctree-l1"><a class="reference internal" href="hooks.html">Plugin Hooks</a></li>
 <li class="toctree-l1"><a class="reference internal" href="anatomy.html">Plugin Anatomy</a></li>
 </ul>
 <p class="caption"><span class="caption-text">Tutorials</span></p>
@@ -49,7 +48,7 @@
 <ul class="current">
 <li class="toctree-l1 current"><a class="current reference internal" href="#">System Requirements</a></li>
 <li class="toctree-l1"><a class="reference internal" href="plugin_loader.html">Plugin Loader</a></li>
-<li class="toctree-l1"><a class="reference internal" href="plugin_hooks.html">Plugin Hooks</a></li>
+<li class="toctree-l1"><a class="reference internal" href="hooks.html">Plugin Hooks</a></li>
 <li class="toctree-l1"><a class="reference internal" href="core_restricted.html">Core vs Restricted packages in Plugeth-utils</a></li>
 <li class="toctree-l1"><a class="reference internal" href="api.html">API</a></li>
 </ul>

documentation/_build/html/types.html

@@ -15,7 +15,7 @@
     <script src="_static/js/theme.js"></script>
     <link rel="index" title="Index" href="genindex.html" />
     <link rel="search" title="Search" href="search.html" />
-    <link rel="next" title="Plugin Hooks" href="hooks.html" />
+    <link rel="next" title="Plugin Anatomy" href="anatomy.html" />
     <link rel="prev" title="Project Design" href="project.html" /> 
 </head>
 
@@ -44,7 +44,6 @@
 <li class="toctree-l2"><a class="reference internal" href="#subscriptions">Subscriptions</a></li>
 </ul>
 </li>
-<li class="toctree-l1"><a class="reference internal" href="hooks.html">Plugin Hooks</a></li>
 <li class="toctree-l1"><a class="reference internal" href="anatomy.html">Plugin Anatomy</a></li>
 </ul>
 <p class="caption"><span class="caption-text">Tutorials</span></p>
@@ -55,7 +54,7 @@
 <ul>
 <li class="toctree-l1"><a class="reference internal" href="system_req.html">System Requirements</a></li>
 <li class="toctree-l1"><a class="reference internal" href="plugin_loader.html">Plugin Loader</a></li>
-<li class="toctree-l1"><a class="reference internal" href="plugin_hooks.html">Plugin Hooks</a></li>
+<li class="toctree-l1"><a class="reference internal" href="hooks.html">Plugin Hooks</a></li>
 <li class="toctree-l1"><a class="reference internal" href="core_restricted.html">Core vs Restricted packages in Plugeth-utils</a></li>
 <li class="toctree-l1"><a class="reference internal" href="api.html">API</a></li>
 </ul>
@@ -123,7 +122,7 @@
           </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="hooks.html" class="btn btn-neutral float-right" title="Plugin Hooks" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
+        <a href="anatomy.html" class="btn btn-neutral float-right" title="Plugin Anatomy" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
     </div>
 
   <hr/>

documentation/_build/html/utils.html

@@ -36,7 +36,6 @@
 <ul>
 <li class="toctree-l1"><a class="reference internal" href="project.html">Project Design</a></li>
 <li class="toctree-l1"><a class="reference internal" href="types.html">Basic Types of Plugins</a></li>
-<li class="toctree-l1"><a class="reference internal" href="hooks.html">Plugin Hooks</a></li>
 <li class="toctree-l1"><a class="reference internal" href="anatomy.html">Plugin Anatomy</a></li>
 </ul>
 <p class="caption"><span class="caption-text">Tutorials</span></p>
@@ -47,7 +46,7 @@
 <ul>
 <li class="toctree-l1"><a class="reference internal" href="system_req.html">System Requirements</a></li>
 <li class="toctree-l1"><a class="reference internal" href="plugin_loader.html">Plugin Loader</a></li>
-<li class="toctree-l1"><a class="reference internal" href="plugin_hooks.html">Plugin Hooks</a></li>
+<li class="toctree-l1"><a class="reference internal" href="hooks.html">Plugin Hooks</a></li>
 <li class="toctree-l1"><a class="reference internal" href="core_restricted.html">Core vs Restricted packages in Plugeth-utils</a></li>
 <li class="toctree-l1"><a class="reference internal" href="api.html">API</a></li>
 </ul>

documentation/api.rst

@@ -46,7 +46,7 @@ Tracers
 
 .. code-block:: go
 
-   ``// CaptureStart is called at the start of each transaction
+   // 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) {}
@@ -55,12 +55,78 @@ Tracers
    // 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) {}``
+   GetResult() (interface{}, error) {}
 
 
 .. warning:: Modifying the values passed into tracer functions can
              alter the 
-             results of the EVM execution in unpredictable ways. Additonally, some objects may be reused acress calls, so data you wish to capture should be copied rather than retianed by reference. 
+             results of the EVM execution in unpredictable ways. Additopackage 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,
+    },
+  }
+}
+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,
+    },
+  }
+}
+nally, some objects may be reused acress calls, so data you wish to capture should be copied rather than retianed by reference. 
 
 LiveTracer
 ----------

documentation/hooks.rst

@@ -4,4 +4,61 @@
 Plugin Hooks
 ============
 
-.. todo:: discussion of 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`_
+
+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`_
+*************
+
+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`_
+**********
+
+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.
+
+`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.  
+
+
+
+**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.**
+
+
+
+
+
+
+.. _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

documentation/index.rst

@@ -25,7 +25,6 @@ Table of Contents
 
     project
     types
-    hooks
     anatomy
     
 
@@ -41,7 +40,7 @@ Table of Contents
 
     system_req
     plugin_loader
-    plugin_hooks
+    hooks
     core_restricted
     api