Merge pull request #4 from Reactive-Network/reactvm_subscriptions

ADD and EDIT ReactVM + Subscriptions

docs/contacts/index.md

@@ -7,7 +7,7 @@ hide_title: true
 custom_edit_url: null
 ---
 
-# Contact Us
+![Contacts Image](./img/contacts.jpg)
 
 Welcome to Team Reactive! We are here to assist you with any inquiries or support you may need. Whether you're looking for help with integrating Reactive Smart Contracts into your dApps, troubleshooting issues, or understanding our platform's unique features, our team is ready to guide you.
 

docs/docs/faq.md

@@ -0,0 +1,76 @@
+---
+title: FAQ
+sidebar_position: 8
+description: Find the answers to the most frequetly asked questions about the Reactive Network's architecture, features, and capabilities.
+slug: /faq
+hide_title: true
+custom_edit_url: null
+---
+
+![Reactive FAQ Image](./img/faq.jpg)
+
+## General Questions
+
+**What problem does the Reactive Network aim to solve?**
+
+The Reactive Network enables the execution of arbitrary Solidity logic without user intervention and provides smart contracts that allow users to subscribe to remote ecosystem events. This facilitates sophisticated reactive contracts that can affect protocols across chains based on incoming data.
+
+**How is the Reactive Network different from other cross-chain relayers?**
+
+Existing cross-chain relayers often need to be integrated into your infrastructure during development and may be specific to certain use cases. The Reactive Network generalizes this concept and can apply arbitrary EVM logic. Unlike many cross-chain relayers, the Reactive Network can execute arbitrary EVM logic, not limited to predefined use cases.
+
+**What is the Reactive Network physically?**
+
+The Reactive Network is a fork of Geth, compatible with the Ethereum Virtual Machine, and operates on a Proof of Stake protocol using Prism. It generates blocks approximately every 3 seconds. A Reactive Network node subscribes to other ecosystems' nodes via WebSocket and monitors the `newheads` event. When triggered, the node obtains transaction receipts, searches for subscribers within the Reactive Network, and propagates event logs to their ReactVMs. The state of the Reactive Network is determined by the collective states of ReactVMs and their connections to external blockchains.
+
+**How is the Reactive Network different from Geth?**
+
+The Reactive Network can listen to other blockchains by subscribing to their event logs. It uses event logs from different blockchains to identify Reactive Smart Contracts subscribed to various topics, execute their logic, and propagate results. This computation occurs outside the main layer, making the process more cost-effective.
+
+**Are there any nuances to the Reactive Network system?**
+
+Simply increasing the gas limit for blocks would compromise decentralization, leading to fewer validators. The Reactive Network includes an additional layer called ReactVM to manage computations while maintaining decentralization.
+
+**What is meant by a dual-state environment?**
+
+Each Reactive Smart Contract operates in a dual-state environment with two instances initialized in the constructor. The ReactVM instance updates its state based on events, while the Reactive Network instance updates its state through manual function calls.
+
+**Why does Reactive have two contract copies, one in the Reactive Network and another in the RVM? Why use this architecture?**
+
+The architecture enables parallel transaction execution. The Ethereum Virtual Machine (EVM) is single-threaded, processing commands one at a time. To overcome this limitation, the Reactive Network uses RVMs (Reactive Virtual Machines) which execute independently and in parallel. Each contract copy in this architecture handles its own state and execution context, allowing for more efficient processing.
+
+## Subscriptions
+
+**Are subscriptions to one or multiple events from different chain IDs allowed?**
+
+Yes, users can subscribe to events from all chains with a single subscription by specifying the chain ID as `0`. Note: Use either `REACTIVE_IGNORE` for topics 0-3 or `0` for the chain ID and contact address, but not both together. Subscribing to events from all chains and all contracts simultaneously is not allowed, nor is subscribing to all events from only one chain, as it is considered unnecessary.
+
+**Are identical subscriptions allowed, and if so, why?**
+
+Duplicate subscriptions are allowed but function as a single subscription. Users are charged for each transaction they send to the system contract. Preventing duplicate subscriptions in the system contract is costly due to EVM storage limitations. Therefore, to keep costs manageable, duplicate subscriptions are permitted.
+
+## Technical Questions
+
+**Why does the `subscribe()` function not work when used in a `react()` function to subscribe to another contract?**  
+
+The `subscribe()` function will not work directly from the RVM because the system contract resides in the Reactive Network, not within the RVM. To subscribe or unsubscribe from the RVM, you should emit the `Callback` event, which will send a callback to the Reactive Network.
+
+**The call `(bool subscription_result,) = address(service).call(payload);` is failing, resulting in `vm = false`. What could be the issue?**  
+
+This failure occurs because an RSC exists in two instances: one on the Reactive Network and one within your personal ReactVM. The call will fail in the RVM instance since the System Smart Contract does not exist there, so `vm` will be true. It will succeed in the Reactive Network instance, so `vm` will be false.
+
+**My deployed reactive contract doesn't seem to catch the emitted events. Running the `react()` function using a cast call doesn’t trigger any response either. What should I do?**  
+
+If your cast calls the Reactive Network instance of the contract, the callback won’t be triggered because it can only be invoked by the RVM instance. To invoke a callback, you should run the transaction on the origin chain, which will trigger the reactive contract and the callback.
+
+**How can I check if my reactive contract is listening to my origin contract events?**  
+
+You can verify this by checking for a new transaction on [Reactive Scan](https://kopli.reactscan.net/) in the relevant RVM.
+
+**What is received in `bytes calldata` in the `react()` function?**  
+
+The `bytes calldata` contains the encoded data of all elements other than topics.
+
+**What does the `REACTIVE_IGNORE` value for topics mean?**  
+
+Setting a specific topic as `REACTIVE_IGNORE` means that reactive contracts will not filter events by this topic when subscribing to events. However, events with any value for this topic will still be accessible.

docs/docs/reactvm.md

@@ -15,6 +15,26 @@ ReactVM is a specialized type of EVM (Ethereum Virtual Machine) within the React
 
 Technically, a ReactVM is an isolated execution environment within the Reactive Network. It activates when an event matches the RSC's subscription. While this approach adds some overhead, we have optimized it by separating the EVM from Geth, resulting in a ReactVM boot time of approximately 100μs, which is insignificant relative to the Network's processing capabilities.
 
+## My ReactVM
+
+When you deploy a reactive smart contract, it will be assigned to a ReactVM. The ReactVM's address will match the EOA address used for the deployment. Every smart contract deployed to the reactive network will ultimately reside within your personal ReactVM. State can be shared within the ReactVM, allowing for interaction among contracts. While multiple RSCs can be deployed within a single ReactVM but generally discouraged.
+
+### Calling subscribe()
+
+Calling `subscribe()` or `unsubscribe()` from within an RVM will not produce any real effect. Use callbacks for interaction instead of directly invoking these functions within RVMs.
+
+## State
+
+The Reactive Network's state is determined by the collective states of individual ReactVMs and their connections to external blockchains. Each ReactVM's state is tied to specific block numbers and hashes from these chains, embedded within ReactVM blocks. This linkage is necessary for tracking and managing reorgs in the originating chains, enabling the network to respond to changes.
+
+### Dual-State Environment
+
+The Reactive Network features a dual-state environment to enable parallel transaction execution. While the EVM operates in a single-threaded manner, processing commands sequentially, the Reactive Network uses RVMs that can operate independently and in parallel on different cores or threads. This architecture supports the handling of various operations, including fund flows and token management, with each contract copy having its own state and execution context.
+
+Each [Reactive Smart Contract](./reactive-smart-contracts.md) has two instances with different states, both initialized in the constructor. The ReactVM instance updates its state when an event occurs, while the Reactive Network instance updates its state when you manually call its functions.
+
+As an example, in a governance contract, vote counts are maintained in the ReactVM state, whereas operational commands like `pause()` are part of the Reactive Network state. The primary logic resides within the ReactVM state.
+
 ## Reactive Network Processing Flow
 
 The following diagram illustrates a process involving the interaction between an Origin Chain, the Reactive Network along with ReactVM, and a Destination Chain.
@@ -37,46 +57,20 @@ Here’s a step-by-step description of the process:
 
 - **ReactVM Processing**:
 
-  - **ReactVM Exists?**: The system checks if a ReactVM already exists.
+    - **ReactVM Exists?**: The system checks if a ReactVM already exists.
 
-  - **No**: If no ReactVM exists, the system sets up a new ReactVM.
+    - **No**: If no ReactVM exists, the system sets up a new ReactVM.
 
-  - **Run ReactVM**: The ReactVM is run to process the transaction.
+    - **Run ReactVM**: The ReactVM is run to process the transaction.
 
-  - **Execute Transaction**: The transaction is executed within the ReactVM.
+    - **Execute Transaction**: The transaction is executed within the ReactVM.
 
-  - **Stop ReactVM**: After executing the transaction, the ReactVM is stopped.
+    - **Stop ReactVM**: After executing the transaction, the ReactVM is stopped.
 
 - **Transaction Receipt**: After the ReactVM completes processing the transaction, a transaction receipt is generated.
 
 - **Prepare Transaction for Destination Chain**: Based on the transaction receipt, a new transaction is prepared for the Destination Chain.
 
 - **Transaction at Mem. Pool in Destination Chain**: The prepared transaction is placed in the memory pool of the Destination Chain, ready to be included in a new block on that chain.
 
-## Personal ReactVM
-
-Deploying an RSC provides a dedicated ReactVM, with its address matching the EOA used for deployment. The ReactVM hosts all smart contracts you deploy within the Reactive Network, allowing state sharing within the same ReactVM.
-
-:::warning[Word of Caution]
-
-Though multiple RSCs can be deployed within a single ReactVM, overusing this feature can negate the benefits of parallelized execution. We recommend subscribing to events from other RSCs, similar to subscribing to `Origin` events, to maximize efficiency.
-
-:::
-
-## Calling subscribe()
-
-Calling `subscribe()` or `unsubscribe()` from within an RVM will not produce any real effect. Use callbacks for interaction instead of directly invoking these functions within RVMs.
-
-## State
-
-The Reactive Network's state is determined by the collective states of individual ReactVMs and their connections to external blockchains. Each ReactVM's state is tied to specific block numbers and hashes from these chains, embedded within ReactVM blocks. This linkage is necessary for tracking and managing reorgs in the originating chains, enabling the network to respond to changes.
-
-## Dual-State Environment
-
-The Reactive Network features a dual-state environment to enable parallel transaction execution. While the EVM operates in a single-threaded manner, processing commands sequentially, the Reactive Network uses RVMs that can operate independently and in parallel on different cores or threads. This architecture supports the handling of various operations, including fund flows and token management, with each contract copy having its own state and execution context.
-
-Each [Reactive Smart Contract](./reactive-smart-contracts.md) has two instances with different states, both initialized in the constructor. The ReactVM instance updates its state when an event occurs, while the Reactive Network instance updates its state when you manually call its functions.
-
-As an example, in a governance contract, vote counts are maintained in the ReactVM state, whereas operational commands like `pause()` are part of the Reactive Network state. The primary logic resides within the ReactVM state.
-
 [More on ReactVM →](../education/module-1/react-vm.md)