feat: group subscriptions (#16)

Single entry point via: `redeem(bytes32 id, bytes calldata data)`

Three redemption types:

### Groups
Internal call: `_redeemGroup(bytes32 id)`
External calls via multisend
- `ERC1155.safeTransferFrom` (transfer subscribers tokens to the module)
- `IHubV2.groupMint` (mint group tokens using subscriber CRC to the
module)
- `ERC1155.safeTransferFrom` (transfer group tokens to the subscriber)

Redeeming occurs via this route if the recipient address is a group
address.

Group minting locks tokens from the `msg.sender` and mints group tokens
to the `msg.sender`, so fairly sure three calls are required in a
pull-based setup.

### Personal Trusted
- Via `operateFlowMatrix`

### Personal Untrusted
- Via `safeTransferFrom`

## Refactor Notes
- Replaced use of `periods` with transient storage
(`T_REDEEMABLE_AMOUNT`), set once in `redeem` using `LibTransient`
- `_redeemGroup`, `_redeemTrusted`, and `_redeemUntrusted` now consume
the redeemable amount from transient storage.
- Explicit `clear` calls clean up the slot after redemption

Author: lumoswiz

foundry.toml

@@ -3,6 +3,7 @@
 [profile.default]
 auto_detect_solc = false
 block_timestamp = 1_738_368_000                     # Feb 1, 2025 at 00:00 GMT
+evm_version = "cancun"
 fuzz = { runs = 1_000 }
 gas_reports = ["*"]
 optimizer = true

src/SubscriptionModule.sol

@@ -2,16 +2,18 @@
 pragma solidity ^0.8.28;
 
 import { ISafe } from "src/interfaces/ISafe.sol";
+import { IHubV2 } from "src/interfaces/IHub.sol";
+import { IMultiSend } from "src/interfaces/IMultiSend.sol";
 import { CirclesLib } from "src/libs/CirclesLib.sol";
 import { Errors } from "src/libs/Errors.sol";
-import { Subscription } from "src/libs/Types.sol";
+import { Subscription, Category } from "src/libs/Types.sol";
 import { SubscriptionLib } from "src/libs/SubscriptionLib.sol";
 
 import { ERC1155 } from "@circles/src/circles/ERC1155.sol";
-import { IHubV2 } from "@circles/src/hub/IHub.sol";
 import { TypeDefinitions } from "@circles/src/hub/TypeDefinitions.sol";
 import { Enum } from "@safe-smart-account/contracts/common/Enum.sol";
 import { EnumerableSetLib } from "@solady/src/utils/EnumerableSetLib.sol";
+import { LibTransient } from "@solady/src/utils/LibTransient.sol";
 
 contract SubscriptionModule {
     /*//////////////////////////////////////////////////////////////
@@ -26,6 +28,8 @@ contract SubscriptionModule {
 
     using CirclesLib for TypeDefinitions.Stream[];
 
+    using LibTransient for LibTransient.TUint256;
+
     /*//////////////////////////////////////////////////////////////
                             STATE VARIABLES
     //////////////////////////////////////////////////////////////*/
@@ -35,11 +39,13 @@ contract SubscriptionModule {
 
     address public constant HUB = 0xc12C1E50ABB450d6205Ea2C3Fa861b3B834d13e8;
 
-    mapping(bytes32 id => address safe) public safeFromId;
+    address public constant MULTISEND = 0x38869bf66a61cF6bDB996A6aE40D5853Fd43B526;
+
+    bytes32 internal constant T_REDEEMABLE_AMOUNT = 0x70bfbb43a5ce660914e09d1b48fcc488982d5981137b973eac35b0592a414e90;
 
-    mapping(address safe => mapping(bytes32 id => Subscription subscription)) internal _subscriptions;
+    mapping(bytes32 id => Subscription subscription) internal _subscriptions;
 
-    mapping(address safe => EnumerableSetLib.Bytes32Set) internal ids;
+    mapping(address subscriber => EnumerableSetLib.Bytes32Set) internal ids;
 
     /*//////////////////////////////////////////////////////////////
                                  EVENTS
@@ -50,18 +56,11 @@ contract SubscriptionModule {
         address indexed subscriber,
         address indexed recipient,
         uint256 amount,
-        uint256 lastRedeemed,
-        uint256 frequency,
-        bool requireTrusted
+        uint256 nextRedeemAt,
+        Category category
     );
 
-    event Redeemed(
-        bytes32 indexed id,
-        address indexed subscriber,
-        address indexed recipient,
-        uint256 lastRedeemed,
-        bool requireTrusted
-    );
+    event Redeemed(bytes32 indexed id, address indexed subscriber, address indexed recipient, uint256 nextRedeemAt);
 
     event RecipientUpdated(bytes32 indexed id, address indexed oldRecipient, address indexed newRecipient);
 
@@ -75,7 +74,7 @@ contract SubscriptionModule {
         address recipient,
         uint256 amount,
         uint256 frequency,
-        bool requireTrusted
+        Category category
     )
         external
         returns (bytes32 id)
@@ -87,75 +86,40 @@ contract SubscriptionModule {
             amount: amount,
             lastRedeemed: block.timestamp - frequency,
             frequency: frequency,
-            requireTrusted: requireTrusted
+            category: category
         });
         id = sub.compute();
-        _subscribe(msg.sender, id, sub);
-        emit SubscriptionCreated(
-            id, msg.sender, recipient, amount, block.timestamp - frequency, frequency, requireTrusted
-        );
-    }
-
-    function redeem(
-        bytes32 id,
-        address[] calldata flowVertices,
-        TypeDefinitions.FlowEdge[] calldata flow,
-        TypeDefinitions.Stream[] calldata streams,
-        bytes calldata packedCoordinates,
-        uint256 sourceCoordinate
-    )
-        external
-    {
-        (address safe, Subscription memory sub) = _loadSubscription(id);
-
-        uint256 periods = _requireRedeemablePeriods(sub);
-
-        require(flowVertices[sourceCoordinate] == sub.subscriber, Errors.InvalidSubscriber());
-
-        require(streams.checkSource(sourceCoordinate), Errors.InvalidStreamSource());
-
-        require(streams.checkRecipients(sub.recipient, flowVertices, packedCoordinates), Errors.InvalidRecipient());
-
-        require(flow.extractAmount() == periods * sub.amount, Errors.InvalidAmount());
-
-        _applyRedemption(safe, id, sub, periods);
-
-        require(
-            ISafe(safe).execTransactionFromModule(
-                HUB,
-                0,
-                abi.encodeCall(IHubV2.operateFlowMatrix, (flowVertices, flow, streams, packedCoordinates)),
-                Enum.Operation.Call
-            ),
-            Errors.ExecutionFailed()
-        );
-
-        emit Redeemed(id, safe, sub.recipient, sub.lastRedeemed, sub.requireTrusted);
+        _subscribe(id, sub);
+        emit SubscriptionCreated(id, msg.sender, recipient, amount, block.timestamp, category);
     }
 
-    function redeemUntrusted(bytes32 id) external {
-        (address safe, Subscription memory sub) = _loadSubscription(id);
-
-        require(!sub.requireTrusted, Errors.TrustedPathOnly());
+    function redeem(bytes32 id, bytes calldata data) external {
+        Subscription memory sub = _subscriptions[id];
+        require(sub.subscriber != address(0), Errors.IdentifierNonexistent());
 
-        uint256 periods = _requireRedeemablePeriods(sub);
-
-        _applyRedemption(safe, id, sub, periods);
-
-        require(
-            ISafe(safe).execTransactionFromModule(
-                HUB,
-                0,
-                abi.encodeCall(
-                    ERC1155.safeTransferFrom,
-                    (sub.subscriber, sub.recipient, uint256(uint160(sub.subscriber)), periods * sub.amount, "")
-                ),
-                Enum.Operation.Call
-            ),
-            Errors.ExecutionFailed()
-        );
+        uint256 periods = (block.timestamp - sub.lastRedeemed) / sub.frequency;
+        require(periods >= 1, Errors.NotRedeemable());
 
-        emit Redeemed(id, safe, sub.recipient, sub.lastRedeemed, sub.requireTrusted);
+        LibTransient.tUint256(T_REDEEMABLE_AMOUNT).set(periods * sub.amount);
+        sub.lastRedeemed += periods * sub.frequency;
+        _subscriptions[id] = sub;
+
+        if (sub.category == Category.group) {
+            _redeemGroup(id, sub);
+        } else if (sub.category == Category.trusted) {
+            (
+                address[] memory flowVertices,
+                TypeDefinitions.FlowEdge[] memory flow,
+                TypeDefinitions.Stream[] memory streams,
+                bytes memory packedCoordinates,
+                uint256 sourceCoordinate
+            ) = abi.decode(data, (address[], TypeDefinitions.FlowEdge[], TypeDefinitions.Stream[], bytes, uint256));
+            _redeemTrusted(id, sub, flowVertices, flow, streams, packedCoordinates, sourceCoordinate);
+        } else if (sub.category == Category.untrusted) {
+            _redeemUntrusted(id, sub);
+        } else {
+            revert Errors.InvalidCategory();
+        }
     }
 
     function unsubscribe(bytes32 id) external {
@@ -169,8 +133,7 @@ contract SubscriptionModule {
     }
 
     function updateRecipient(bytes32 id, address newRecipient) external {
-        address safe = safeFromId[id];
-        Subscription storage sub = _subscriptions[safe][id];
+        Subscription storage sub = _subscriptions[id];
         require(sub.recipient == msg.sender, Errors.OnlyRecipient());
         sub.recipient = newRecipient;
         emit RecipientUpdated(id, msg.sender, newRecipient);
@@ -181,62 +144,152 @@ contract SubscriptionModule {
     //////////////////////////////////////////////////////////////*/
 
     function getSubscription(bytes32 id) external view returns (Subscription memory) {
-        return _subscriptions[safeFromId[id]][id];
+        return _subscriptions[id];
     }
 
-    function getSubscriptionIds(address safe) external view returns (bytes32[] memory) {
-        return ids[safe].values();
+    function getSubscriptionIds(address subscriber) external view returns (bytes32[] memory) {
+        return ids[subscriber].values();
     }
 
     function isValidOrRedeemable(bytes32 id) public view returns (uint256) {
-        Subscription memory subscription = _subscriptions[safeFromId[id]][id];
-        return (block.timestamp - subscription.lastRedeemed) / subscription.frequency * subscription.amount;
-    }
-
-    function isTrustedRequired(bytes32 id) external view returns (bool) {
-        return _subscriptions[safeFromId[id]][id].requireTrusted;
+        if (_subscriptions[id].subscriber == address(0)) return 0;
+        Subscription memory sub = _subscriptions[id];
+        return (block.timestamp - sub.lastRedeemed) / sub.frequency * sub.amount;
     }
 
     /*//////////////////////////////////////////////////////////////
                     INTERNAL NON-CONSTANT FUNCTIONS
     //////////////////////////////////////////////////////////////*/
 
-    function _subscribe(address subscriber, bytes32 id, Subscription memory subscription) internal {
-        require(!_exists(id), Errors.IdentifierExists());
-        _subscriptions[subscriber][id] = subscription;
-        safeFromId[id] = subscriber;
-        ids[subscriber].add(id);
+    function _subscribe(bytes32 id, Subscription memory sub) internal {
+        require(_subscriptions[id].subscriber == address(0), Errors.IdentifierExists());
+        _subscriptions[id] = sub;
+        ids[sub.subscriber].add(id);
     }
 
-    function _unsubscribe(address subscriber, bytes32 id) internal {
-        require(_exists(id), Errors.IdentifierNonexistent());
-        delete _subscriptions[subscriber][id];
-        delete safeFromId[id];
-        ids[subscriber].remove(id);
-        emit Unsubscribed(id, subscriber);
+    function _unsubscribe(address caller, bytes32 id) internal {
+        Subscription memory sub = _subscriptions[id];
+        require(sub.subscriber == caller, Errors.OnlySubscriber());
+        delete _subscriptions[id];
+        ids[sub.subscriber].remove(id);
+        emit Unsubscribed(id, sub.subscriber);
     }
 
-    /*//////////////////////////////////////////////////////////////
-                      INTERNAL CONSTANT FUNCTIONS
-    //////////////////////////////////////////////////////////////*/
+    function _redeemGroup(bytes32 id, Subscription memory sub) internal {
+        address[] memory collateralAvatars = new address[](1);
+        collateralAvatars[0] = sub.subscriber;
+
+        uint256[] memory amounts = new uint256[](1);
+        amounts[0] = sub.amount;
+
+        /**
+         * Steps required to handle group minting for the subscriber
+         *   - pull subscriber CRC tokens
+         *   - mint group (= recipient) tokens to this module using subscriber CRC collateral
+         *     - empty data for now, @todo check group mint policies for requirements
+         *   - transfer minted group tokens to the subscriber
+         */
+        bytes memory call0 = abi.encodeCall(
+            ERC1155.safeTransferFrom,
+            (
+                sub.subscriber,
+                address(this),
+                _toTokenId(sub.subscriber),
+                LibTransient.tUint256(T_REDEEMABLE_AMOUNT).get(),
+                ""
+            )
+        );
+        /// @todo empty data for now -- checkout mint policies of existing groups for data requirements
+        bytes memory call1 = abi.encodeCall(IHubV2.groupMint, (sub.recipient, collateralAvatars, amounts, ""));
+        bytes memory call2 = abi.encodeCall(
+            ERC1155.safeTransferFrom,
+            (
+                address(this),
+                sub.subscriber,
+                _toTokenId(sub.recipient),
+                ERC1155(HUB).balanceOf(address(this), _toTokenId(sub.recipient)),
+                ""
+            )
+        );
+        bytes memory transactions = bytes.concat(
+            abi.encodePacked(uint8(0), HUB, uint256(0), call0.length, call0),
+            abi.encodePacked(uint8(0), HUB, uint256(0), call1.length, call1),
+            abi.encodePacked(uint8(0), HUB, uint256(0), call2.length, call2)
+        );
+
+        require(
+            ISafe(sub.subscriber).execTransactionFromModule(
+                MULTISEND, 0, abi.encodeCall(IMultiSend.multiSend, (transactions)), Enum.Operation.DelegateCall
+            ),
+            Errors.ExecutionFailed()
+        );
 
-    function _exists(bytes32 id) internal view returns (bool) {
-        return safeFromId[id] != address(0);
+        emit Redeemed(id, sub.subscriber, sub.recipient, sub.lastRedeemed + sub.frequency);
+        LibTransient.tUint256(T_REDEEMABLE_AMOUNT).clear();
     }
 
-    function _loadSubscription(bytes32 id) internal view returns (address safe, Subscription memory sub) {
-        require(_exists(id), Errors.IdentifierNonexistent());
-        safe = safeFromId[id];
-        sub = _subscriptions[safe][id];
+    function _redeemTrusted(
+        bytes32 id,
+        Subscription memory sub,
+        address[] memory flowVertices,
+        TypeDefinitions.FlowEdge[] memory flow,
+        TypeDefinitions.Stream[] memory streams,
+        bytes memory packedCoordinates,
+        uint256 sourceCoordinate
+    )
+        internal
+    {
+        require(flowVertices[sourceCoordinate] == sub.subscriber, Errors.InvalidSubscriber());
+
+        require(streams.checkSource(sourceCoordinate), Errors.InvalidStreamSource());
+
+        require(streams.checkRecipients(sub.recipient, flowVertices, packedCoordinates), Errors.InvalidRecipient());
+
+        require(flow.extractAmount() == LibTransient.tUint256(T_REDEEMABLE_AMOUNT).get(), Errors.InvalidAmount());
+
+        require(
+            ISafe(sub.subscriber).execTransactionFromModule(
+                HUB,
+                0,
+                abi.encodeCall(IHubV2.operateFlowMatrix, (flowVertices, flow, streams, packedCoordinates)),
+                Enum.Operation.Call
+            ),
+            Errors.ExecutionFailed()
+        );
+
+        emit Redeemed(id, sub.subscriber, sub.recipient, sub.lastRedeemed + sub.frequency);
+        LibTransient.tUint256(T_REDEEMABLE_AMOUNT).clear();
     }
 
-    function _requireRedeemablePeriods(Subscription memory sub) internal view returns (uint256 periods) {
-        periods = (block.timestamp - sub.lastRedeemed) / sub.frequency;
-        require(periods >= 1, Errors.NotRedeemable());
+    function _redeemUntrusted(bytes32 id, Subscription memory sub) internal {
+        require(
+            ISafe(sub.subscriber).execTransactionFromModule(
+                HUB,
+                0,
+                abi.encodeCall(
+                    ERC1155.safeTransferFrom,
+                    (
+                        sub.subscriber,
+                        sub.recipient,
+                        _toTokenId(sub.subscriber),
+                        LibTransient.tUint256(T_REDEEMABLE_AMOUNT).get(),
+                        ""
+                    )
+                ),
+                Enum.Operation.Call
+            ),
+            Errors.ExecutionFailed()
+        );
+
+        emit Redeemed(id, sub.subscriber, sub.recipient, sub.lastRedeemed + sub.frequency);
+        LibTransient.tUint256(T_REDEEMABLE_AMOUNT).clear();
     }
 
-    function _applyRedemption(address safe, bytes32 id, Subscription memory sub, uint256 periods) internal {
-        sub.lastRedeemed += periods * sub.frequency;
-        _subscriptions[safe][id] = sub;
+    /*//////////////////////////////////////////////////////////////
+                      INTERNAL CONSTANT FUNCTIONS
+    //////////////////////////////////////////////////////////////*/
+
+    function _toTokenId(address _avatar) internal pure returns (uint256) {
+        return uint256(uint160(_avatar));
     }
 }