From b09ab5f345178bb4e4fc3f3cbb45ad96bb8355a1 Mon Sep 17 00:00:00 2001
From: rian <rian.hughes@physics.ox.ac.uk>
Date: Thu, 26 Sep 2024 11:22:15 +0300
Subject: [PATCH] add docs

---
 blockchain/blockchain.go |  5 +--
 docs/docs/plugin.md      | 87 ++++++++++++++++++++++++++++++++++++++++
 2 files changed, 88 insertions(+), 4 deletions(-)
 create mode 100644 docs/docs/plugin.md

diff --git a/blockchain/blockchain.go b/blockchain/blockchain.go
index 7f0d4024ac..67cdc08c56 100644
--- a/blockchain/blockchain.go
+++ b/blockchain/blockchain.go
@@ -841,10 +841,7 @@ func (b *Blockchain) GetReverseStateDiff() (*core.StateDiff, error) {
 		}
 		state := core.NewState(txn)
 		reverseStateDiff, err = state.BuildReverseDiff(blockNumber, stateUpdate.StateDiff)
-		if err != nil {
-			return err
-		}
-		return nil
+		return err
 	})
 }
 
diff --git a/docs/docs/plugin.md b/docs/docs/plugin.md
new file mode 100644
index 0000000000..197cc0196b
--- /dev/null
+++ b/docs/docs/plugin.md
@@ -0,0 +1,87 @@
+---
+title: Juno Plugins
+---
+
+## Overview
+
+The Juno client now supports plugins that satisfy the `JunoPlugin` interface. This enhancement allows developers to extend and customize Juno's behavior by dynamically loading external plugins at runtime.
+
+The `JunoPlugin` interface provides a structured way for plugins to interact with the blockchain by receiving notifications when new blocks are added or reverted. This ensures state consistency, especially during blockchain reorganizations, while abstracting away the complexity of implementing block syncing and revert logic.
+
+## The JunoPlugin Interface
+
+Your plugin must implement the `JunoPlugin` interface, which includes methods for initializing, shutting down, and handling new and reverted blocks.
+
+
+```go
+type JunoPlugin interface {
+	Init() error
+	Shutdown() error // Note: Currently this function will never be called.
+	NewBlock(block *core.Block, stateUpdate *core.StateUpdate, newClasses map[felt.Felt]core.Class) error
+	RevertBlock(from, to *BlockAndStateUpdate, reverseStateDiff *core.StateDiff) error
+}
+```
+
+
+**Init**: Called when the plugin is initialized. This can be used to set up database connections or any other necessary resources.
+
+**Shutdown**: Called when the plugin is shut down, though this function is currently never called by Juno. This can be used to clean up resources like database connections.
+
+**NewBlock**: Triggered when a new block is synced by the Juno client. Juno will send the block, the corresponding state update, and any new classes. Importantly, Juno waits for the plugin to finish processing this function call before continuing. This ensures that the plugin completes its task before Juno proceeds with the blockchain sync.
+
+**RevertBlock**: Called during a blockchain reorganization (reorg). Juno will invoke this method for each block that needs to be reverted. Similar to NewBlock, the client will wait for the plugin to finish handling the revert before moving on to the next block.
+
+## Example plugin
+
+Here is a basic example of a plugin that satisfies the `JunoPlugin` interface:
+
+```go
+//go:generate go build -buildmode=plugin -o ../../build/plugin.so ./example.go
+type examplePlugin string
+
+// Important: "JunoPluginInstance" needs to be exported for Juno to load the plugin correctly
+var JunoPluginInstance examplePlugin
+
+var _ junoplugin.JunoPlugin = (*examplePlugin)(nil)
+
+func (p *examplePlugin) Init() error {
+    fmt.Println("ExamplePlugin initialized")
+    return nil
+}
+
+func (p *examplePlugin) Shutdown() error {
+    fmt.Println("ExamplePlugin shutdown")
+    return nil
+}
+
+func (p *examplePlugin) NewBlock(block *core.Block, stateUpdate *core.StateUpdate, newClasses map[felt.Felt]core.Class) error {
+    fmt.Println("ExamplePlugin NewBlock called")
+    return nil
+}
+
+func (p *examplePlugin) RevertBlock(from, to *junoplugin.BlockAndStateUpdate, reverseStateDiff *core.StateDiff) error {
+    fmt.Println("ExamplePlugin RevertBlock called")
+    return nil
+}
+```
+
+The ```JunoPluginInstance``` variable must be exported for Juno to correctly load the plugin:
+```var JunoPluginInstance examplePlugin```
+
+We ensure the plugin implements the ```JunoPlugin``` interface, with the following line:
+```var _ junoplugin.JunoPlugin = (*examplePlugin)(nil)```
+
+
+
+# Building and Loading the Plugin
+
+Once you have written your plugin, you can compile it into a shared object file (.so) using the following command:
+```go build -buildmode=plugin -o ./plugin.so /path/to/your/plugin.go```
+
+This command compiles the plugin into a shared object file (```plugin.so```), which can then be loaded by the Juno client using the ```--plugin-path``` flag.
+
+# Running Juno with the plugin
+
+Once your plugin has been compiled into a `.so` file, you can run Juno with your plugin by providing the `--plugin-path` flag. This flag tells Juno where to find and load your plugin at runtime.
+
+