Merge pull request #1 from Reactive-Network/dec24-prerelease

Preparations for testnet refresh.

Author: pbl64k

src/abstract-base/AbstractCallback.sol

@@ -5,12 +5,14 @@ pragma solidity >=0.8.0;
 import '../interfaces/IPayable.sol';
 import './AbstractPayer.sol';
 
+/// @title Abstract base contract for contracts receiving the Reactive Network callbacks.
 abstract contract AbstractCallback is AbstractPayer {
     address internal rvm_id;
 
     constructor(address _callback_sender) {
         rvm_id = msg.sender;
         vendor = IPayable(payable(_callback_sender));
+        addAuthorizedSender(_callback_sender);
     }
 
     modifier rvmIdOnly(address _rvm_id) {

src/abstract-base/AbstractPausableReactive.sol

@@ -3,9 +3,9 @@
 pragma solidity >=0.8.0;
 
 import '../interfaces/IReactive.sol';
-import '../interfaces/ISubscriptionService.sol';
 import './AbstractReactive.sol';
 
+/// @title Abstract base contract for pausable reactive contracts.
 abstract contract AbstractPausableReactive is IReactive, AbstractReactive {
     struct Subscription{
         uint256 chain_id;
@@ -23,13 +23,16 @@ abstract contract AbstractPausableReactive is IReactive, AbstractReactive {
         owner = msg.sender;
     }
 
+    /// @notice This function should return the list of subscriptions to pause/resume.
+    /// @return The list of subscriptions to pause/resume.
     function getPausableSubscriptions() virtual internal view returns (Subscription[] memory);
 
     modifier onlyOwner() {
         require(msg.sender == owner, 'Unauthorized');
         _;
     }
 
+    /// @notice Pauses the reactive contract by unsubscribing from events using the criteria provided by the implementation.
     function pause() external rnOnly onlyOwner {
         require(!paused, 'Already paused');
         Subscription[] memory subscriptions = getPausableSubscriptions();
@@ -46,6 +49,7 @@ abstract contract AbstractPausableReactive is IReactive, AbstractReactive {
         paused = true;
     }
 
+    /// @notice Resumed the reactive contract by subscribing to events using the criteria provided by the implementation.
     function resume() external rnOnly onlyOwner {
         require(paused, 'Not paused');
         Subscription[] memory subscriptions = getPausableSubscriptions();

src/abstract-base/AbstractPayer.sol

@@ -5,34 +5,56 @@ pragma solidity >=0.8.0;
 import '../interfaces/IPayer.sol';
 import '../interfaces/IPayable.sol';
 
+/// @title Abstract base contract for contracts needing to handle payments to the system contract or callback proxies.
 abstract contract AbstractPayer is IPayer {
     IPayable internal vendor;
 
+    /// @notice ACL for addresses allowed to make callbacks and/or request payment.
+    mapping(address => bool) senders;
+
     constructor() {
     }
 
+    /// @inheritdoc IPayer
     receive() virtual external payable {
     }
 
     modifier authorizedSenderOnly() {
-        require(address(vendor) == address(0) || msg.sender == address(vendor), 'Authorized sender only');
+        require(senders[msg.sender], 'Authorized sender only');
         _;
     }
 
+    /// @inheritdoc IPayer
     function pay(uint256 amount) external authorizedSenderOnly {
         _pay(payable(msg.sender), amount);
     }
 
+    /// @notice Automatically cover the outstanding debt to the system contract or callback proxy, provided the contract has sufficient funds.
     function coverDebt() external {
         uint256 amount = vendor.debt(address(this));
         _pay(payable(vendor), amount);
     }
 
+    /// @notice Attempts to safely transfer the specified sum to the given address.
+    /// @param recipient Address of the transfer's recipient.
+    /// @param amount Amount to be transferred.
     function _pay(address payable recipient, uint256 amount) internal {
         require(address(this).balance >= amount, 'Insufficient funds');
         if (amount > 0) {
             (bool success,) = payable(recipient).call{value: amount}(new bytes(0));
             require(success, 'Transfer failed');
         }
     }
+
+    /// @notice Adds the given address to the ACL.
+    /// @param sender Sender address to add.
+    function addAuthorizedSender(address sender) internal {
+        senders[sender] = true;
+    }
+
+    /// @notice Removes the given address from the ACL.
+    /// @param sender Sender address to remove.
+    function removeAuthorizedSender(address sender) internal {
+        senders[sender] = false;
+    }
 }

src/abstract-base/AbstractReactive.sol

@@ -3,23 +3,22 @@
 pragma solidity >=0.8.0;
 
 import '../interfaces/IReactive.sol';
-import '../interfaces/IPayable.sol';
 import '../interfaces/ISystemContract.sol';
 import './AbstractPayer.sol';
 
+/// @title Abstract base contract for reactive contracts.
 abstract contract AbstractReactive is IReactive, AbstractPayer {
     uint256 internal constant REACTIVE_IGNORE = 0xa65f96fc951c35ead38878e0f0b7a3c744a6f5ccc1476b313353ce31712313ad;
     ISystemContract internal constant SERVICE_ADDR = ISystemContract(payable(0x0000000000000000000000000000000000fffFfF));
 
-    /**
-     * Indicates whether this is a ReactVM instance of the contract.
-     */
+    /// @notice Indicates whether this is a ReactVM instance of the contract.
     bool internal vm;
 
     ISystemContract internal service;
 
     constructor() {
         vendor = service = SERVICE_ADDR;
+        addAuthorizedSender(address(SERVICE_ADDR));
         detectVm();
     }
 
@@ -33,6 +32,7 @@ abstract contract AbstractReactive is IReactive, AbstractPayer {
         _;
     }
 
+    /// @notice Determines whether this copy of the contract is deployed to an RVM or the top-level Reactive Network by checking for the presence of the system contract at the predetermined address.
     function detectVm() internal {
         uint256 size;
         // solhint-disable-next-line no-inline-assembly

src/interfaces/IPayable.sol

@@ -2,11 +2,13 @@
 
 pragma solidity >=0.8.0;
 
+/// @title Common interface for the system contract and the callback proxy, allows contracts to check and pay their debts.
 interface IPayable {
-    // @notice Allows contracts to pay their debts and resume subscriptions.
+    /// @notice Allows contracts to pay their debts and resume subscriptions.
     receive() external payable;
 
-    // @notice Allows reactive contracts to check their outstanding debt.
-    // @param _contract Reactive contract's address.
+    /// @notice Allows reactive contracts to check their outstanding debt.
+    /// @param _contract Reactive contract's address.
+    /// @return Reactive contract's current debt due to unpaid reactive transactions and/or callbacks.
     function debt(address _contract) external view returns (uint256);
 }

src/interfaces/IPayer.sol

@@ -2,9 +2,13 @@
 
 pragma solidity >=0.8.0;
 
+/// @title Common interface for the contracts that need to pay for system contract's or proxies' services.
 interface IPayer {
-    // @dev Make sure to check the msg.sender
+    /// @notice Method called by the system contract and/or proxies when payment is due.
+    /// @dev Make sure to check the msg.sender.
+    /// @param amount Amount owed due to reactive transactions and/or callbacks.
     function pay(uint256 amount) external;
 
+    /// @notice Allows the reactive contracts and callback contracts to receive funds for their operational expenses.
     receive() external payable;
 }

src/interfaces/IReactive.sol

@@ -4,35 +4,32 @@ pragma solidity >=0.8.0;
 
 import './IPayer.sol';
 
-// @title Interface for reactive contracts.
-// @notice Reactive contracts receive notifications about new events matching the criteria of their event subscriptions.
+/// @title Interface for reactive contracts.
+/// @notice Reactive contracts receive notifications about new events matching the criteria of their event subscriptions.
 interface IReactive is IPayer {
+    struct LogRecord {
+        uint256 chain_id;
+        address _contract;
+        uint256 topic_0;
+        uint256 topic_1;
+        uint256 topic_2;
+        uint256 topic_3;
+        bytes data;
+        uint256 block_number;
+        uint256 op_code;
+        uint256 block_hash;
+        uint256 tx_hash;
+        uint256 log_index;
+    }
+
     event Callback(
         uint256 indexed chain_id,
         address indexed _contract,
         uint64 indexed gas_limit,
         bytes payload
     );
 
-    // @notice Entry point for handling new event notifications.
-    // @param chain_id EIP155 source chain ID for the event (as a `uint256`).
-    // @param _contract Address of the originating contract for the received event.
-    // @param topic_0 Topic 0 of the event (or `0` for `LOG0`).
-    // @param topic_1 Topic 1 of the event (or `0` for `LOG0` and `LOG1`).
-    // @param topic_2 Topic 2 of the event (or `0` for `LOG0` .. `LOG2`).
-    // @param topic_3 Topic 3 of the event (or `0` for `LOG0` .. `LOG3`).
-    // @param data Event data as a byte array.
-    // @param block_number Block number where the log record is located in its chain of origin.
-    // @param op_code Number of topics in the log record (0 to 4).
-    function react(
-        uint256 chain_id,
-        address _contract,
-        uint256 topic_0,
-        uint256 topic_1,
-        uint256 topic_2,
-        uint256 topic_3,
-        bytes calldata data,
-        uint256 block_number,
-        uint256 op_code
-    ) external;
+    /// @notice Entry point for handling new event notifications.
+    /// @param log Data structure containing the information about the intercepted log record.
+    function react(LogRecord calldata log) external;
 }

src/interfaces/ISubscriptionService.sol

@@ -4,18 +4,16 @@ pragma solidity >=0.8.0;
 
 import './IPayable.sol';
 
-// @title Interface for event subscription service.
-// @notice Reactive contracts receive notifications about new events matching the criteria of their event subscriptions.
+/// @title Interface for event subscription service.
+/// @notice Reactive contracts receive notifications about new events matching the criteria of their event subscriptions.
 interface ISubscriptionService is IPayable {
-    // @notice Subscribes the calling contract to receive events matching the criteria specified.
-    // @param chain_id EIP155 source chain ID for the event (as a `uint256`), or `0` for all chains.
-    // @param _contract Contract address to monitor, or `0` for all contracts.
-    // @param topic_0 Topic 0 to monitor, or `REACTIVE_IGNORE` for all topics.
-    // @param topic_1 Topic 1 to monitor, or `REACTIVE_IGNORE` for all topics.
-    // @param topic_2 Topic 2 to monitor, or `REACTIVE_IGNORE` for all topics.
-    // @param topic_3 Topic 3 to monitor, or `REACTIVE_IGNORE` for all topics.
-    // @dev At least one of criteria above must be non-`REACTIVE_IGNORE`.
-    // @dev Will allow duplicate or overlapping subscriptions, clients must ensure idempotency.
+    /// @notice Subscribes the calling contract to receive events matching the criteria specified.
+    /// @param chain_id EIP155 source chain ID for the event (as a `uint256`), or `0` for all chains.
+    /// @param _contract Contract address to monitor, or `0` for all contracts.
+    /// @param topic_0 Topic 0 to monitor, or `REACTIVE_IGNORE` for all topics.
+    /// @param topic_1 Topic 1 to monitor, or `REACTIVE_IGNORE` for all topics.
+    /// @param topic_2 Topic 2 to monitor, or `REACTIVE_IGNORE` for all topics.
+    /// @param topic_3 Topic 3 to monitor, or `REACTIVE_IGNORE` for all topics.
     function subscribe(
         uint256 chain_id,
         address _contract,
@@ -25,14 +23,13 @@ interface ISubscriptionService is IPayable {
         uint256 topic_3
     ) external;
 
-    // @notice Removes active subscription of the calling contract, matching the criteria specified, if one exists.
-    // @param chain_id Chain ID criterion of the original subscription.
-    // @param _contract Contract address criterion of the original subscription.
-    // @param topic_0 Topic 0 criterion of the original subscription.
-    // @param topic_1 Topic 0 criterion of the original subscription.
-    // @param topic_2 Topic 0 criterion of the original subscription.
-    // @param topic_3 Topic 0 criterion of the original subscription.
-    // @dev This is very expensive.
+    /// @notice Removes active subscription of the calling contract, matching the criteria specified, if one exists.
+    /// @param chain_id Chain ID criterion of the original subscription.
+    /// @param _contract Contract address criterion of the original subscription.
+    /// @param topic_0 Topic 0 criterion of the original subscription.
+    /// @param topic_1 Topic 0 criterion of the original subscription.
+    /// @param topic_2 Topic 0 criterion of the original subscription.
+    /// @param topic_3 Topic 0 criterion of the original subscription.
     function unsubscribe(
         uint256 chain_id,
         address _contract,

src/interfaces/ISystemContract.sol

@@ -5,5 +5,6 @@ pragma solidity >=0.8.0;
 import './IPayable.sol';
 import './ISubscriptionService.sol';
 
+/// @title Interface for the Reactive Network's system contract.
 interface ISystemContract is IPayable, ISubscriptionService {
 }

src/libraries/SystemLib.sol

@@ -2,6 +2,8 @@
 
 pragma solidity >=0.8.0;
 
+/// @notice Gets the current implementation address of the system contract by calling the node's custom function on address `0x64`.
+/// @return The address of the current implementation of the system contract.
 function getSystemContractImpl() returns (address) {
     (bool success, bytes memory ret) = address(0x64).call(abi.encode(block.number));
     require(success && ret.length == 0x20, 'Failure');