Support plugins

README.md

@@ -228,6 +228,7 @@ After following these steps, Juno should be up and running on your machine, util
 - Starknet state construction and storage using a path-based Merkle Patricia trie.
 - Feeder gateway synchronisation of Blocks, Transactions, Receipts, State Updates and Classes.
 - Block and Transaction hash verification.
+- Plugins 
 
 ## 🛣 Roadmap
 

blockchain/blockchain.go

@@ -828,6 +828,23 @@
 	return b.database.Update(b.revertHead)
 }
 
+func (b *Blockchain) GetReverseStateDiff() (*core.StateDiff, error) {
+	var reverseStateDiff *core.StateDiff
+	return reverseStateDiff, b.database.View(func(txn db.Transaction) error {
+		blockNumber, err := chainHeight(txn)
+		if err != nil {
+			return err
+		}
+		stateUpdate, err := stateUpdateByNumber(txn, blockNumber)
+		if err != nil {
+			return err
+		}
+		state := core.NewState(txn)
+		reverseStateDiff, err = state.BuildReverseDiff(blockNumber, stateUpdate.StateDiff)
+		return err
+	})
+}
+
 func (b *Blockchain) revertHead(txn db.Transaction) error {
 	blockNumber, err := chainHeight(txn)
 	if err != nil {
@@ -874,7 +891,6 @@
 	}
 
 	// Revert chain height and pending.
-
 	if genesisBlock {
 		if err = txn.Delete(db.Pending.Key()); err != nil {
 			return err

cmd/juno/juno.go

@@ -82,6 +82,7 @@ const (
 	callMaxStepsF           = "rpc-call-max-steps"
 	corsEnableF             = "rpc-cors-enable"
 	versionedConstantsFileF = "versioned-constants-file"
+	pluginPathF             = "plugin-path"
 
 	defaultConfig                   = ""
 	defaulHost                      = "localhost"
@@ -119,6 +120,7 @@ const (
 	defaultGwTimeout                = 5 * time.Second
 	defaultCorsEnable               = false
 	defaultVersionedConstantsFile   = ""
+	defaultPluginPath               = ""
 
 	configFlagUsage                       = "The YAML configuration file."
 	logLevelFlagUsage                     = "Options: trace, debug, info, warn, error."
@@ -170,6 +172,7 @@ const (
 		"The upper limit is 4 million steps, and any higher value will still be capped at 4 million."
 	corsEnableUsage             = "Enable CORS on RPC endpoints"
 	versionedConstantsFileUsage = "Use custom versioned constants from provided file"
+	pluginPathUsage             = "Path to the plugins .so file"
 )
 
 var Version string
@@ -355,6 +358,7 @@ func NewCmd(config *node.Config, run func(*cobra.Command, []string) error) *cobr
 	junoCmd.Flags().Bool(corsEnableF, defaultCorsEnable, corsEnableUsage)
 	junoCmd.Flags().String(versionedConstantsFileF, defaultVersionedConstantsFile, versionedConstantsFileUsage)
 	junoCmd.MarkFlagsMutuallyExclusive(p2pFeederNodeF, p2pPeersF)
+	junoCmd.Flags().String(pluginPathF, defaultPluginPath, pluginPathUsage)
 
 	junoCmd.AddCommand(GenP2PKeyPair(), DBCmd(defaultDBPath))
 

core/state.go

@@ -541,7 +541,7 @@ func (s *State) Revert(blockNumber uint64, update *StateUpdate) error {
 	}
 
 	// update contracts
-	reversedDiff, err := s.buildReverseDiff(blockNumber, update.StateDiff)
+	reversedDiff, err := s.BuildReverseDiff(blockNumber, update.StateDiff)
 	if err != nil {
 		return fmt.Errorf("build reverse diff: %v", err)
 	}
@@ -657,7 +657,7 @@ func (s *State) purgeContract(addr *felt.Felt) error {
 	return storageCloser()
 }
 
-func (s *State) buildReverseDiff(blockNumber uint64, diff *StateDiff) (*StateDiff, error) {
+func (s *State) BuildReverseDiff(blockNumber uint64, diff *StateDiff) (*StateDiff, error) {
 	reversed := *diff
 
 	// storage diffs

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.
+
+

go.mod

@@ -14,6 +14,7 @@ require (
 	github.com/ethereum/go-ethereum v1.14.9
 	github.com/fxamacker/cbor/v2 v2.7.0
 	github.com/go-playground/validator/v10 v10.22.1
+	github.com/golang/protobuf v1.5.4
 	github.com/jinzhu/copier v0.4.0
 	github.com/libp2p/go-libp2p v0.36.2
 	github.com/libp2p/go-libp2p-kad-dht v0.26.1

go.sum

@@ -179,6 +179,8 @@ github.com/golang/protobuf v1.4.0-rc.4.0.20200313231945-b860323f09d0/go.mod h1:W
 github.com/golang/protobuf v1.4.0/go.mod h1:jodUvKwWbYaEsadDk5Fwe5c77LiNKVO9IDvqG2KuDX0=
 github.com/golang/protobuf v1.4.1/go.mod h1:U8fpvMrcmy5pZrNK1lt4xCsGvpyWQ/VVv6QDs8UjoX8=
 github.com/golang/protobuf v1.4.3/go.mod h1:oDoupMAO8OvCJWAcko0GGGIgR6R6ocIYbsSw735rRwI=
+github.com/golang/protobuf v1.5.4 h1:i7eJL8qZTpSEXOPTxNKhASYpMn+8e5Q6AdndVa1dWek=
+github.com/golang/protobuf v1.5.4/go.mod h1:lnTiLA8Wa4RWRcIUkrtSVa5nRhsEGBg48fD6rSs7xps=
 github.com/golang/snappy v0.0.5-0.20220116011046-fa5810519dcb h1:PBC98N2aIaM3XXiurYmW7fx4GZkL8feAMVq7nEjURHk=
 github.com/golang/snappy v0.0.5-0.20220116011046-fa5810519dcb/go.mod h1:/XxbfmMg8lxefKM7IXC3fBNl/7bRcc72aCRzEWrmP2Q=
 github.com/google/btree v0.0.0-20180813153112-4030bb1f1f0c/go.mod h1:lNA+9X1NB3Zf8V7Ke586lFgjr2dZNuvo3lPJSGZ5JPQ=

node/node.go

@@ -22,6 +22,7 @@
 	"github.com/NethermindEth/juno/l1"
 	"github.com/NethermindEth/juno/migration"
 	"github.com/NethermindEth/juno/p2p"
+	junoplugin "github.com/NethermindEth/juno/plugin"
 	"github.com/NethermindEth/juno/rpc"
 	"github.com/NethermindEth/juno/service"
 	adaptfeeder "github.com/NethermindEth/juno/starknetdata/feeder"
@@ -88,6 +89,8 @@
 
 	GatewayAPIKey  string        `mapstructure:"gw-api-key"`
 	GatewayTimeout time.Duration `mapstructure:"gw-timeout"`
+
+	PluginPath string `mapstructure:"plugin-path"`
 }
 
 type Node struct {
@@ -156,6 +159,14 @@
 	synchronizer := sync.New(chain, adaptfeeder.New(client), log, cfg.PendingPollInterval, dbIsRemote)
 	gatewayClient := gateway.NewClient(cfg.Network.GatewayURL, log).WithUserAgent(ua).WithAPIKey(cfg.GatewayAPIKey)
 
+	if cfg.PluginPath != "" {
+		plugin, err := junoplugin.Load(cfg.PluginPath)
+		if err != nil {
+			return nil, err
+		}
+		synchronizer.WithPlugin(plugin)
+	}
+
 	var p2pService *p2p.Service
 	if cfg.P2P {
 		if cfg.Network != utils.Sepolia {

plugin/plugin.go

@@ -0,0 +1,43 @@
+package junoplugin
+
+import (
+	"fmt"
+	"plugin"
+
+	"github.com/NethermindEth/juno/core"
+	"github.com/NethermindEth/juno/core/felt"
+)
+
+//go:generate mockgen -destination=../mocks/mock_plugin.go -package=mocks github.com/NethermindEth/juno/plugin JunoPlugin
+type JunoPlugin interface {
+	Init() error
+	Shutdown() error // Todo: Currently this function will never be called.
+	NewBlock(block *core.Block, stateUpdate *core.StateUpdate, newClasses map[felt.Felt]core.Class) error
+	// The state is reverted by applying a write operation with the reverseStateDiff's StorageDiffs, Nonces, and ReplacedClasses,
+	// and a delete option with its DeclaredV0Classes, DeclaredV1Classes, and ReplacedClasses.
+	RevertBlock(from, to *BlockAndStateUpdate, reverseStateDiff *core.StateDiff) error
+}
+
+type BlockAndStateUpdate struct {
+	Block       *core.Block
+	StateUpdate *core.StateUpdate
+}
+
+func Load(pluginPath string) (JunoPlugin, error) {
+	plug, err := plugin.Open(pluginPath)
+	if err != nil {
+		return nil, fmt.Errorf("error loading plugin .so file: %w", err)
+	}
+
+	symPlugin, err := plug.Lookup("JunoPluginInstance")
+	if err != nil {
+		return nil, fmt.Errorf("error looking up PluginInstance: %w", err)
+	}
+
+	pluginInstance, ok := symPlugin.(JunoPlugin)
+	if !ok {
+		return nil, fmt.Errorf("the plugin does not staisfy the required interface")
+	}
+
+	return pluginInstance, pluginInstance.Init()
+}