feat(MultiSend): add .add_from_receipt method (#94)

* feat(MultiSend): add `.add_from_receipt` method

Add method to append calls from transaction receipts to a MultiSend batch

* style: remove empty whitespace

Added usage example for add_from_receipt method.

* test(MultiSend): add a test demonstrating use of `.add_from_receipt`

* docs(MultiSend): add section on simulating side effects, using new feat

Author: fubuloubu

ape_safe/multisend.py

@@ -157,6 +157,32 @@ def add(
         )
         return self
 
+    def add_from_receipt(self, receipt: "ReceiptAPI") -> "MultiSend":
+        """
+        Append a call to the MultiSend session object from a receipt.
+        Especially useful for more complex simulations.
+
+        Usage::
+
+            with networks.fork():
+                receipt = contract.method(*args, sender=safe.address)
+                assert contract.viewMethod() == ...
+                batch.add_from_receipt(receipt)
+
+            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:

docs/userguides/multisend.md

@@ -66,6 +66,41 @@ signatures = safe.add_signatures(safe_tx)
 receipt = safe.submit_safe_tx(safe_tx)
 ```
 
+## Simulating Side Effects in Scripts
+
+Typically, it is useful to validate your multisend scripts through the use of simulating their
+side effects via a "forked" network context.
+We have provided a feature `batch.add_from_receipt` which allows you to add calls directly from
+the results of simulated network calls (executing as the Safe itself), which reduces human error.
+
+```python
+# Create MultiSend transaction outside the fork context (important!)
+# NOTE: You should be connected to a live "public"  network when executing this
+batch = safe.create_batch()
+
+# Enter a "simulated" context as a "fork" of the public network you want to propose to
+with networks.fork():
+    # NOTE: We must use `sender=safe.address` to skip ape-safe's local signer processing
+    # NOTE: You typically must provide an eth balance to `safe.address`, or it will fail
+    #       due to no funds to pay for gas in order to perform the transaction.
+    receipt = dai.approve(vault, amount, sender=safe.address)
+    # NOTE: You can now test "side effects" of the transaction here.
+    assert dai.allowance(safe, vault) == amount
+    # This will add the call as a step in the MultiSend batch
+    batch.add_from_receipt(receipt)
+
+    # ...add as many steps as you would like to the batch while inside this forked context.
+    receipt = vault.deposit(amount, sender=safe.address)
+    assert vault.balanceOf(safe) == amount
+    batch.add_from_receipt(receipt)
+
+# After exiting the forked context, submit it as a real transaction on-chain
+batch(submitter=me)
+
+# Or, propose to the API
+safe_tx = batch.propose(submitter=me)
+```
+
 ## Decoding Existing MultiSend Transactions
 
 You can decode and inspect existing MultiSend transactions:

tests/functional/test_multisend.py

@@ -30,6 +30,35 @@ def test_default_operation(safe, deployer, token, vault, mode):
     assert receipt.txn_hash
 
 
+def test_using_multisend_from_receipts(chain, safe, deployer, token, vault):
+    amount = 100
+    token.DEBUG_mint(safe, amount, sender=deployer)
+
+    assert vault.asset() == token
+    batch = safe.create_batch()
+
+    with chain.isolate():
+        # HACK: Contract address must have balance to send txns directly
+        safe.balance += int(1e18)
+
+        # NOTE: Execute these transactions in an simulated context
+        receipt = token.approve(vault, amount, sender=safe.address)
+        assert token.allowance(safe, vault) == amount
+        batch.add_from_receipt(receipt)
+
+        receipt = vault.deposit(amount, safe, sender=safe.address)
+        assert vault.balanceOf(safe) == amount
+        batch.add_from_receipt(receipt)
+
+    # NOTE: Context was reverted, so no side-effects exist
+    assert token.allowance(safe, vault) == 0
+    assert vault.balanceOf(safe) == 0
+
+    batch(submitter=deployer)
+
+    assert vault.balanceOf(safe) == amount
+
+
 def test_decode_multisend(new_multisend):
     calldata = bytes.fromhex(
         "8d80ff0a0000000000000000000000000000000000000000000000000000000000000020000000000000000000000000000000000000000000000000000000000000016b00527e80008d212e2891c737ba8a2768a7337d7fd200000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000024f0080878000000000000000000000000584bffc5f51ccae39ad69f1c399743620e619c2b00da18f789a1d9ad33e891253660fcf1332d236b2900000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000024e74b981b000000000000000000000000584bffc5f51ccae39ad69f1c399743620e619c2b0027b5739e22ad9033bcbf192059122d163b60349d000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000247a55036500000000000000000000000000000000000000000000000000002a1b324b8f68000000000000000000000000000000000000000000"  # noqa: E501