Support plugins (#2051)

Co-authored-by: rian <rian@physics.ox.ac.uk>
Co-authored-by: LordGhostX <solomonghost9@gmail.com>

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 @@ func (b *Blockchain) RevertHead() error {
 	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.GetReverseStateDiff(blockNumber, stateUpdate.StateDiff)
+		return err
+	})
+}
+
 func (b *Blockchain) revertHead(txn db.Transaction) error {
 	blockNumber, err := chainHeight(txn)
 	if err != nil {
@@ -874,7 +891,6 @@ func (b *Blockchain) revertHead(txn db.Transaction) error {
 	}
 
 	// 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 plugin .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

@@ -540,10 +540,14 @@ func (s *State) Revert(blockNumber uint64, update *StateUpdate) error {
 		return fmt.Errorf("remove declared classes: %v", err)
 	}
 
-	// update contracts
-	reversedDiff, err := s.buildReverseDiff(blockNumber, update.StateDiff)
+	reversedDiff, err := s.GetReverseStateDiff(blockNumber, update.StateDiff)
 	if err != nil {
-		return fmt.Errorf("build reverse diff: %v", err)
+		return fmt.Errorf("error getting reverse state diff: %v", err)
+	}
+
+	err = s.performStateDeletions(blockNumber, update.StateDiff)
+	if err != nil {
+		return fmt.Errorf("error performing state deletions: %v", err)
 	}
 
 	stateTrie, storageCloser, err := s.storage()
@@ -566,12 +570,17 @@ func (s *State) Revert(blockNumber uint64, update *StateUpdate) error {
 		}
 	}
 
-	// purge noClassContracts
-	//
+	if err = s.purgeNoClassContracts(); err != nil {
+		return err
+	}
+
+	return s.verifyStateUpdateRoot(update.OldRoot)
+}
+
+func (s *State) purgeNoClassContracts() error {
 	// As noClassContracts are not in StateDiff.DeployedContracts we can only purge them if their storage no longer exists.
 	// Updating contracts with reverse diff will eventually lead to the deletion of noClassContract's storage key from db. Thus,
 	// we can use the lack of key's existence as reason for purging noClassContracts.
-
 	for addr := range noClassContracts {
 		noClassC, err := NewContractUpdater(&addr, s.txn)
 		if err != nil {
@@ -592,8 +601,7 @@ func (s *State) Revert(blockNumber uint64, update *StateUpdate) error {
 			}
 		}
 	}
-
-	return s.verifyStateUpdateRoot(update.OldRoot)
+	return nil
 }
 
 func (s *State) removeDeclaredClasses(blockNumber uint64, v0Classes []*felt.Felt, v1Classes map[felt.Felt]*felt.Felt) error {
@@ -657,7 +665,7 @@ func (s *State) purgeContract(addr *felt.Felt) error {
 	return storageCloser()
 }
 
-func (s *State) buildReverseDiff(blockNumber uint64, diff *StateDiff) (*StateDiff, error) {
+func (s *State) GetReverseStateDiff(blockNumber uint64, diff *StateDiff) (*StateDiff, error) {
 	reversed := *diff
 
 	// storage diffs
@@ -673,10 +681,6 @@ func (s *State) buildReverseDiff(blockNumber uint64, diff *StateDiff) (*StateDif
 				}
 				value = oldValue
 			}
-
-			if err := s.DeleteContractStorageLog(&addr, &key, blockNumber); err != nil {
-				return nil, err
-			}
 			reversedDiffs[key] = value
 		}
 		reversed.StorageDiffs[addr] = reversedDiffs
@@ -686,18 +690,13 @@ func (s *State) buildReverseDiff(blockNumber uint64, diff *StateDiff) (*StateDif
 	reversed.Nonces = make(map[felt.Felt]*felt.Felt, len(diff.Nonces))
 	for addr := range diff.Nonces {
 		oldNonce := &felt.Zero
-
 		if blockNumber > 0 {
 			var err error
 			oldNonce, err = s.ContractNonceAt(&addr, blockNumber-1)
 			if err != nil {
 				return nil, err
 			}
 		}
-
-		if err := s.DeleteContractNonceLog(&addr, blockNumber); err != nil {
-			return nil, err
-		}
 		reversed.Nonces[addr] = oldNonce
 	}
 
@@ -712,12 +711,35 @@ func (s *State) buildReverseDiff(blockNumber uint64, diff *StateDiff) (*StateDif
 				return nil, err
 			}
 		}
+		reversed.ReplacedClasses[addr] = classHash
+	}
 
+	return &reversed, nil
+}
+
+func (s *State) performStateDeletions(blockNumber uint64, diff *StateDiff) error {
+	// storage diffs
+	for addr, storageDiffs := range diff.StorageDiffs {
+		for key := range storageDiffs {
+			if err := s.DeleteContractStorageLog(&addr, &key, blockNumber); err != nil {
+				return err
+			}
+		}
+	}
+
+	// nonces
+	for addr := range diff.Nonces {
+		if err := s.DeleteContractNonceLog(&addr, blockNumber); err != nil {
+			return err
+		}
+	}
+
+	// replaced classes
+	for addr := range diff.ReplacedClasses {
 		if err := s.DeleteContractClassHashLog(&addr, blockNumber); err != nil {
-			return nil, err
+			return err
 		}
-		reversed.ReplacedClasses[addr] = classHash
 	}
 
-	return &reversed, nil
+	return nil
 }

docs/docs/plugins.md

@@ -0,0 +1,82 @@
+---
+title: Juno Plugins
+---
+
+Juno supports plugins that satisfy the `JunoPlugin` interface, enabling developers to extend and customize Juno's behaviour and functionality by dynamically loading external plugins during runtime.
+
+The `JunoPlugin` interface provides a structured way for plugins to interact with the blockchain by sending 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.
+
+## 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
+	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 Juno node is shut down. 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:
+
+```shell
+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.

docs/sidebars.js

@@ -12,6 +12,7 @@ const sidebars = {
         "hardware-requirements",
         "running-juno",
         "configuring",
+        "plugins",
         "running-on-gcp",
         "updating",
       ],

go.mod

@@ -14,6 +14,7 @@ require (
 	github.com/ethereum/go-ethereum v1.14.11
 	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.27.0

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=