Merge pull request #36 from Reactive-Network/update-docs

Update docs

docs/docs/reactvm.md

@@ -43,36 +43,36 @@ The following diagram illustrates a process involving the interaction between an
 
 ![Reactive Network Lifecycle](./img/global-processing-flow.png)
 
-Here’s a step-by-step description of the process:
+### Step-by-step Description
 
-- **New Block in Origin Chain**: The process starts when a new block is created on the Origin Chain. This block contains multiple transactions.
+**New Block in Origin Chain**: The process starts when a new block is created on the Origin Chain. This block contains multiple transactions.
 
-- **Catch Block in Reactive Network**: The Reactive Network catches the newly created block from the Origin Chain.
+**Catch Block in Reactive Network**: The Reactive Network catches the newly created block from the Origin Chain.
 
-- **Iterate Transactions**: The system iterates through all the transactions in the newly caught block.
+**Iterate Transactions**: The system iterates through all the transactions in the newly caught block.
 
-- **Extract Transaction Logs**: Transaction logs are extracted from each transaction.
+**Extract Transaction Logs**: Transaction logs are extracted from each transaction.
 
-- **Find Transactions at System SC**: The system identifies specific transactions that need to be processed by the System Smart Contract (System SC).
+**Find Transactions at System SC**: The system identifies specific transactions that need to be processed by the System Smart Contract (System SC).
 
-- **Prepare Transaction and Publish to RVM**: The identified transactions are prepared and published to the ReactVM for further processing.
+**Prepare Transaction and Publish to RVM**: The identified transactions are prepared and published to the ReactVM for further processing.
 
-- **ReactVM Processing**:
+**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.
+**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.
+**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.
+**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.
 
 [More on ReactVM →](../education/module-1/react-vm.md)

docs/docs/subscriptions.md

@@ -10,13 +10,13 @@ hide_title: true
 
 ## Overview
 
-This section explains how to configure and manage subscriptions in Reactive Smart Contracts within the Reactive Network. It covers the basics of setting up subscriptions in the contract's constructor, handling dynamic subscriptions through callbacks, and applying filtering criteria like chain ID, contract address, and event topics.
+This section explains how to configure and manage subscriptions in a reactive contract within the Reactive Network. It covers the basics of setting up subscriptions in the contract's constructor, handling dynamic subscriptions through callbacks, and applying filtering criteria like chain ID, contract address, and event topics.
 
 ## Subscription Basics
 
-In Reactive Smart Contracts, subscriptions are established by invoking the `subscribe()` method of the Reactive Network's system contract. This method is typically called in the contract's `constructor()` or dynamically via a callback (see [Dynamic Subscriptions](./subscriptions.md#dynamic-subscriptions)).
+In a reactive contract, subscriptions are established by invoking the `subscribe()` method of the Reactive Network's [system contract](./system-contract.md). This method is typically called in the contract's `constructor()` or dynamically via a callback (see [Dynamic Subscriptions](./subscriptions.md#dynamic-subscriptions)).
 
-Since deployments occur both on the Reactive Network and in the deployer's private ReactVM, where the system contract is unavailable, the reactive contract must handle potential reverts.
+Since deployments occur both on the Reactive Network and in the deployer's private ReactVM, where the system contract is not present, the reactive contract must handle potential reverts.
 
 ```solidity
 bool private vm;
@@ -41,35 +41,37 @@ constructor() {
 
 The Reactive Network uses the subscription system to link various `uint256` fields to specific events. Subscribers can then filter events based on exact matches of these fields.
 
+:::info[Filtering Criteria]
 During the testnet phase, the Reactive Network provides filtering criteria based on the originating contract's chain ID, address, and all four topics. These criteria may evolve in the future.
+:::
 
 ### Using REACTIVE_IGNORE and 0
 
-- `REACTIVE_IGNORE` is an arbitrary predefined value (`0xa65f96fc951c35ead38878e0f0b7a3c744a6f5ccc1476b313353ce31712313ad`) that allows you to subscribe to any topic.
+`REACTIVE_IGNORE` is an arbitrary predefined value (`0xa65f96fc951c35ead38878e0f0b7a3c744a6f5ccc1476b313353ce31712313ad`) that allows you to subscribe to any topic.
 
-- `0` can be used for chain ID or contract address to match any value. Ensure at least one criterion is specific to create a meaningful subscription.
+`0` can be used for chain ID or contract address to match any value. Ensure at least one criterion is specific to create a meaningful subscription.
 
 ### Subscription Examples
 
-- **All Events from a Specific Contract**: Subscribe to all events from `0x7E0987E5b3a30e3f2828572Bb659A548460a3003`.
+**All Events from a Specific Contract**: Subscribe to all events from `0x7E0987E5b3a30e3f2828572Bb659A548460a3003`.
 
 ```solidity
 subscribe(CHAIN_ID, 0x7E0987E5b3a30e3f2828572Bb659A548460a3003, REACTIVE_IGNORE, REACTIVE_IGNORE, REACTIVE_IGNORE, REACTIVE_IGNORE)
 ```
 
-- **Specific Topic 0**: Subscribe to all Uniswap V2 Sync events.
+**Specific Topic 0**: Subscribe to all Uniswap V2 Sync events.
 
 ```solidity
 subscribe(CHAIN_ID, 0, 0x1c411e9a96e071241c2f21f7726b17ae89e3cab4c78be50e062b03a9fffbbad1, REACTIVE_IGNORE, REACTIVE_IGNORE, REACTIVE_IGNORE)
 ```
 
-- **Specific Contract with Specific Topic 0**: Subscribe to events from `0x7E0987E5b3a30e3f2828572Bb659A548460a3003` with topic 0 `0x1c411e9a96e071241c2f21f7726b17ae89e3cab4c78be50e062b03a9fffbbad1`.
+**Specific Contract with Specific Topic 0**: Subscribe to events from `0x7E0987E5b3a30e3f2828572Bb659A548460a3003` with topic 0 `0x1c411e9a96e071241c2f21f7726b17ae89e3cab4c78be50e062b03a9fffbbad1`.
 
 ```solidity
 subscribe(CHAIN_ID, 0x7E0987E5b3a30e3f2828572Bb659A548460a3003, 0x1c411e9a96e071241c2f21f7726b17ae89e3cab4c78be50e062b03a9fffbbad1, REACTIVE_IGNORE, REACTIVE_IGNORE, REACTIVE_IGNORE)
 ```
 
-- **Multiple Independent Subscriptions**: Call the `subscribe()` method multiple times in the constructor to create multiple independent subscriptions.
+**Multiple Independent Subscriptions**: Call the `subscribe()` method multiple times in the constructor to create multiple independent subscriptions.
 
 ```solidity
 bool private vm;
@@ -81,7 +83,7 @@ constructor() {
     bytes memory payload1 = abi.encodeWithSignature(
         "subscribe(uint256,address,uint256,uint256,uint256,uint256)",
         CHAIN_ID,
-        0x7E0987E5b3a30e3f2828572Bb659A548460a3003, // Specific contract address
+        0x7E0987E5b3a30e3f2828572Bb659A548460a3003, // Contract address
         REACTIVE_IGNORE,
         REACTIVE_IGNORE,
         REACTIVE_IGNORE,
@@ -97,7 +99,7 @@ constructor() {
         "subscribe(uint256,address,uint256,uint256,uint256,uint256)",
         CHAIN_ID,
         0,
-        0x1c411e9a96e071241c2f21f7726b17ae89e3cab4c78be50e062b03a9fffbbad1, // Specific topic 0
+        0x1c411e9a96e071241c2f21f7726b17ae89e3cab4c78be50e062b03a9fffbbad1, // Topic 0
         REACTIVE_IGNORE,
         REACTIVE_IGNORE,
         REACTIVE_IGNORE
@@ -107,25 +109,25 @@ constructor() {
         vm = true;
     }
 
-    // Add more subscriptions as needed
+    // Add more subscriptions if needed
 }
 ```
 
 ### Prohibited Subscriptions
 
-- **Non-Equality Operations**: Subscriptions can’t match event parameters using less than (\<), greater than (\>), range, or bitwise operations. Only strict equality is supported.
+**Non-Equality Operations**: Subscriptions can’t match event parameters using less than (\<), greater than (\>), range, or bitwise operations. Only strict equality is supported.
 
-- **Complex Criteria Sets**: Subscriptions can’t use disjunction or sets of criteria within a single subscription. While calling the `subscribe()` method multiple times can achieve similar results, it may lead to combinatorial explosion.
+**Complex Criteria Sets**: Subscriptions can’t use disjunction or sets of criteria within a single subscription. While calling the `subscribe()` method multiple times can achieve similar results, it may lead to combinatorial explosion.
 
-- **Single Chain and All Contracts**: Subscribing to events from all chains or all contracts simultaneously is not allowed. Subscribing to all events from only one chain is also prohibited, as it is considered unnecessary.
+**Single Chain and All Contracts**: Subscribing to events from all chains or all contracts simultaneously is not allowed. Subscribing to all events from only one chain is also prohibited, as it is considered unnecessary.
 
-- **Duplicate Subscriptions**: While duplicate subscriptions are technically allowed, they function as a single subscription. Users are charged for each transaction sent to the system contract. Preventing duplicates in the system contract is costly due to EVM storage limitations, so duplicate subscriptions are permitted to keep costs manageable.
+**Duplicate Subscriptions**: While duplicate subscriptions are technically allowed, they function as a single subscription. Users are charged for each transaction sent to the system contract. Preventing duplicates in the system contract is costly due to EVM storage limitations, so duplicate subscriptions are permitted to keep costs manageable.
 
 ## Dynamic Subscriptions
 
 Subscriptions in the Reactive Network are managed through a system contract, which is accessible only from the network. Events are sent to the ReactVM's contract copy, which has no direct access to the system contract. Therefore, dynamic subscriptions and unsubscriptions based on incoming events must be handled via callbacks.
 
-The `react()` method processes incoming events and checks if `topic_0` indicates a `subscribe` or `unsubscribe` event. If so, it generates a callback to the Reactive Network to manage the subscription.
+The `react()` method from the [reactive contract](https://github.com/Reactive-Network/reactive-smart-contract-demos/blob/main/src/demos/approval-magic/ApprovalListener.sol) of the [Approval Magic demo](https://github.com/Reactive-Network/reactive-smart-contract-demos/tree/main/src/demos/approval-magic) processes incoming events and checks if `topic_0` indicates a `subscribe` or `unsubscribe` event. If so, it generates a callback to the Reactive Network to manage the subscription.
 
 
 ```solidity
@@ -164,7 +166,7 @@ function react(
             _contract,
             amount
         );
-        emit Callback(SEPOLIA_CHAIN_ID, address(service), CALLBACK_GAS_LIMIT, payload);
+        emit Callback(SEPOLIA_CHAIN_ID, address(approval_service), CALLBACK_GAS_LIMIT, payload);
     }
 }
 ```

docs/docs/system-contract.md

@@ -10,9 +10,9 @@ hide_title: true
 
 ## Overview
 
-The system contract is a core part of the Reactive Network (RNK), responsible for managing subscriptions and acting as a callback proxy. Integrated into the genesis block, it operates with immutable code, handling essential network functions without a mutable state. Extending `CallbackProxy` and `AbstractSubscriptionService`, the system contract also manages payments and whitelisting and blacklisting of contracts.
+The [System Contract](https://github.com/Reactive-Network/system-smart-contracts/blob/main/src/SystemContract.sol) is responsible for managing subscriptions on the Reactive Network (RNK), acting as a callback proxy contract. Integrated into the genesis block, it operates with immutable code, handling essential network functions without a mutable state. Extending `CallbackProxy` and `AbstractSubscriptionService`, the system contract also manages payments, whitelisting and blacklisting of contracts.
 
-The callback proxy operates independently on destination chains and as an integrated component within the system contract on RNK. It primarily authorizes callback senders, processes callbacks, and manages contract balances and debt with methods like `withdraw()`, `addCallbackSenders()`, `callback()`, along with internal functions for deposit and charge management.
+The [Callback Proxy](https://github.com/Reactive-Network/system-smart-contracts/blob/main/src/CallbackProxy.sol) operates independently on destination chains and as an integrated part within the system contract on RNK. It primarily authorizes callback senders, processes callbacks, and manages contract balances and debt with methods like `withdraw()`, `addCallbackSenders()`, `callback()`, along with internal functions for deposit and charge management.
 
 ## Callback Payments
 
@@ -64,32 +64,32 @@ Reactive Transactions will share the same payment mechanism as RNK's callback pa
 
 ## Interfaces & Abstract Contracts
 
-### ISystemContract
+### [ISystemContract](https://github.com/Reactive-Network/reactive-smart-contract-demos/blob/main/src/ISystemContract.sol)
 
 Combines `IPayable` and `ISubscriptionService`, providing both payment handling and event subscription capabilities. Payment functionality inherited from `IPayable` to manage debts and payments. Event subscription functionality inherited from `ISubscriptionService` to manage subscriptions and notifications for reactive contracts.
 
-### ISubscriptionService
+### [ISubscriptionService](https://github.com/Reactive-Network/reactive-smart-contract-demos/blob/main/src/ISubscriptionService.sol)
 
 Allows reactive contracts to subscribe to and receive notifications for events that match specified criteria across chains. Methods include:
 
 - `ping` – Determines whether the contract operates in the Reactive Network or ReactVM context.
 - `subscribe` – Subscribes the contract to monitor events based on specified criteria such as chain ID, contract address, and event topics.
 - `unsubscribe` – Removes the contract's active event subscriptions, which can be resource-intensive.
 
-### IReactive
+### [IReactive](https://github.com/Reactive-Network/reactive-smart-contract-demos/blob/main/src/IReactive.sol)
 
 Defines the structure for reactive contracts, which receive notifications for events matching subscription criteria. Methods include:
 
 - `react` – Handles incoming event notifications based on chain ID, contract address, topics, and event data.
 - `receive` – Allows the contract to receive payments.
 
-### IPayer
+### [IPayer](https://github.com/Reactive-Network/reactive-smart-contract-demos/blob/main/src/IPayer.sol)
 
 Defines the payment functionality for contracts, ensuring that only authorized entities can initiate payments. Methods include:
 
 - `pay` – Facilitates payment of a specified amount, with a requirement to verify the sender.
 
-### IPayable
+### [IPayable](https://github.com/Reactive-Network/reactive-smart-contract-demos/blob/main/src/IPayable.sol)
 
 Defines basic payment functionality for contracts, including debt checking and receiving payments. Methods include:
 
@@ -100,7 +100,7 @@ Defines basic payment functionality for contracts, including debt checking and r
 Abstract contracts reduce boilerplate by incorporating common functionalities. They may change before production deployment.
 :::
 
-### AbstractReactive
+### [AbstractReactive](https://github.com/Reactive-Network/reactive-smart-contract-demos/blob/main/src/AbstractReactive.sol)
 
 Handles the distinction between the Reactive Network and ReactVM environments, enforcing conditions based on the environment and integrating with system contracts. Methods include:
 
@@ -109,30 +109,30 @@ Handles the distinction between the Reactive Network and ReactVM environments, e
 - `sysConOnly` – Ensures that only system contracts can invoke certain functions.
 - `detectVm` – Detects whether the contract is running in a VM or Reactive Network context.
 
-### AbstractPayer
+### [AbstractPayer](https://github.com/Reactive-Network/reactive-smart-contract-demos/blob/main/src/AbstractPayer.sol)
 
 Manages payment operations for contracts, ensuring that only authorized senders can trigger payments. Methods include:
 
 - `pay` – Facilitates payment to the sender if authorized.
 - `coverDebt` – Pays off any outstanding debt to the vendor.
 - `_pay` – Handles internal payment logic and ensures sufficient balance for transactions.
 
-### AbstractPausableReactive
+### [AbstractPausableReactive](https://github.com/Reactive-Network/reactive-smart-contract-demos/blob/main/src/AbstractPausableReactive.sol)
 
 Manages pausable event subscriptions for reactive contracts, allowing the owner to pause and resume event monitoring. Methods include:
 
 - `pause` – Unsubscribes from all active event subscriptions and pauses the contract.
 - `resume` – Resubscribes to all paused event subscriptions and resumes contract functionality.
 - `onlyOwner` – Restricts access to functions only to the contract owner.
 
-### AbstractCallback
+### [AbstractCallback](https://github.com/Reactive-Network/reactive-smart-contract-demos/blob/main/src/AbstractCallback.sol)
 
 An abstract base for managing callback-related functions with restricted access to a designated RVM ID. Methods include:
 
 - `rvmIdOnly` – Ensures that only authorized RVM IDs can interact with specific functions.
 - `constructor` – Sets the callback sender and initializes the RVM ID.
 
-### AbstractSubscriptionService
+### [AbstractSubscriptionService](https://github.com/Reactive-Network/system-smart-contracts/blob/main/src/AbstractSubscriptionService.sol)
 
 Provides an event subscription system for reactive contracts and allows contracts to subscribe to events based on criteria such as chain ID, contract address, and topics. Methods include: