feat(MultiSend): add direct calls (#108)

* fix(MultiSend): no reason to verify sum of value sent for Safe

* feat(Multisend): use `.add_call` to send direct call; refactor use

* fix(MultiSend): use better default argument

Author: fubuloubu

ape_safe/exceptions.py

@@ -126,11 +126,6 @@ class MulticallException(ApeSafeException):
     pass
 
 
-class ValueRequired(MulticallException):
-    def __init__(self, amount: int):
-        super().__init__(f"This transaction must send at least '{amount / 1e18}' ether.")
-
-
 class UnsupportedChainError(MulticallException):
     def __init__(self):
         super().__init__("Multicall not supported on this chain.")

ape_safe/multisend.py

@@ -10,12 +10,16 @@
 from ape_safe.client.types import OperationType, SafeTxID
 
 from .accounts import SafeAccount, get_signatures
-from .exceptions import UnsupportedChainError, ValueRequired
+from .exceptions import UnsupportedChainError
 from .packages import MANIFESTS_BY_VERSION, PackageType, get_multisend
 
 if TYPE_CHECKING:
     from ape.api import ReceiptAPI, TransactionAPI
-    from ape.contracts.base import ContractInstance, ContractTransactionHandler
+    from ape.contracts.base import (
+        ContractInstance,
+        ContractMethodHandler,
+        ContractTransactionHandler,
+    )
     from eip712.common import SafeTx
 
 
@@ -128,35 +132,63 @@ def contract(self) -> "ContractInstance":
     def handler(self) -> "ContractTransactionHandler":
         return self.contract.multiSend
 
-    def add(
+    def add_call(
         self,
-        call,
-        *args,
+        target: AddressType | str,
+        data: HexBytes = "",
         value: int = 0,
     ) -> "MultiSend":
         """
-        Append a call to the MultiSend session object.
+        Append a raw call to the MultiSend session object.
 
         Raises:
             :class:`InvalidOption`: If one of the kwarg modifiers is not able to be used.
 
         Args:
-            call: :class:`ContractMethodHandler` The method to call.
-            *args: The arguments to invoke the method with.
+            target: The address to send the message to.
+            data: The data to send to the target. Defaults to empty.
             value: int The amount of ether to forward with the call. Defaults to 0.
         """
         if value < 0:
             raise ValueError("`value=` must be positive.")
 
         self.calls.append(
             {
-                "target": call.contract.address,
+                "target": self.conversion_manager.convert(target, AddressType),
                 "value": value,
-                "callData": call.encode_input(*args),
+                "callData": data,
             }
         )
         return self
 
+    def add(
+        self,
+        call: "ContractMethodHandler",
+        *args,
+        value: int = 0,
+    ) -> "MultiSend":
+        """
+        Append a call to the MultiSend session object.
+
+        Usage::
+
+            batch.add(contract.method1)  # Method with no args
+            batch.add(contract.method2, *args)  # Method with args
+            batch.add(contract.method3, *args, value=...)  # Payable method
+
+            batch(...)
+
+        Raises:
+            :class:`InvalidOption`: If one of the kwarg modifiers is not able to be used.
+
+        Args:
+            call: :class:`ContractMethodHandler` The method to call.
+            *args: The arguments to invoke the method with.
+            value: int The amount of ether to forward with the call. Defaults to 0.
+        """
+
+        return self.add_call(call.contract, data=call.encode_input(*args), value=value)
+
     def add_from_receipt(self, receipt: "ReceiptAPI") -> "MultiSend":
         """
         Append a call to the MultiSend session object from a receipt.
@@ -169,24 +201,14 @@ def add_from_receipt(self, receipt: "ReceiptAPI") -> "MultiSend":
                 assert contract.viewMethod() == ...
                 batch.add_from_receipt(receipt)
 
+            # NOTE: `receipt` is no longer on the chain (only in fork)
             batch(...)
 
         Args:
             receipt: :class:`~ape.api.ReceiptAPI` The receipt object to pull information from for the call to add.
         """
-        self.calls.append(
-            {
-                "target": receipt.receiver,
-                "value": receipt.value,
-                "callData": receipt.data,
-            }
-        )
-        return self
 
-    def _validate_safe_tx(self, safe_tx: "SafeTx") -> None:
-        required_value = sum(call["value"] for call in self.calls)
-        if required_value > safe_tx.value:
-            raise ValueRequired(required_value)
+        return self.add_call(receipt.receiver, data=receipt.data, value=receipt.value)
 
     @property
     def encoded_calls(self):
@@ -227,7 +249,6 @@ def propose(
         submitter = safe_tx_kwargs.pop("submitter", None)
         sigs_by_signer = safe_tx_kwargs.pop("sigs_by_signer", None)
         safe_tx = self.as_safe_tx(safe, **safe_tx_kwargs)
-        self._validate_safe_tx(safe_tx)
         return safe.propose_safe_tx(
             safe_tx,
             submitter=submitter,
@@ -302,6 +323,15 @@ def add_from_calldata(self, calldata: bytes) -> "MultiSend":
 
         Args:
             calldata: Calldata encoding the ``MultiSend.multiSend`` call.
+
+        Usage::
+
+            # NOTE: Previously submitted MultiSend SafeTx
+            receipt = chain.get_receipt("0x...")
+            batch.add_from_calldata(receipt.data)
+
+            # NOTE: `batch` now has all of the same calls in it as the MultiSend in `receipt` did
+            batch(...)
         """
         _, args = self.contract.decode_input(calldata)
         buffer = BytesIO(args["transactions"])