fix(execute): Add stub_name to pre.deploy_contract (#2104)

* fix(execute): Add `stub_name` to `pre.deploy_contract`

* fix(execute): Don't force require address stubs in execute hive mode

* feat(execute): Check that address in the stubbed contracts list contains code

* docs: update stubbed contracts docs

* rename "stub_name" -> "stub"

Author: marioevz

docs/running_tests/execute/remote.md

@@ -107,14 +107,26 @@ COMPOUND_COMPTROLLER: 0x3d9819210A31b4961b30EF54bE2aeD79B9c9Cd3B
 
 ### How Address Stubs Work
 
-When a test uses a contract label that matches a key in the address stubs, the test framework will:
+When a test deploys a contract using `pre.deploy_contract(..., stub="NAME")` and the stub name matches a key in the address stubs, the test framework will:
 
 1. Use the pre-deployed contract at the specified address instead of deploying a new contract
 2. Skip the contract deployment transaction, saving gas and time
 3. Use the existing contract's code and state for the test
 
 This is particularly useful when testing interactions with well-known contracts that are expensive to deploy or when you want to test against the actual deployed versions of contracts.
 
+If the address is _not_ present in the stubbed addresses list, the test will fail to execute.
+
+If the address contained in the stubbed addresses list does not contain code on the remote chain, the test will fail.
+
+The pre-alloc will be populated with live information from the chain, so the following lines will result in up-to-date information:
+
+```python
+my_stubbed_contract = pre.deploy_contract(code, stub="uniswap")
+pre[my_stubbed_contract].nonce  # Actual nonce of the contract on chain
+pre[my_stubbed_contract].balance  # Actual balance of the contract on chain
+```
+
 ### Bloat-net Testing
 
 Address stubs are especially valuable when testing on **bloat-net**, a specialized network that contains pre-existing contracts with extensive storage history. On bloat-net:

src/ethereum_test_types/account_types.py

@@ -341,6 +341,7 @@ def deploy_contract(
         address: Address | None = None,
         evm_code_type: EVMCodeType | None = None,
         label: str | None = None,
+        stub: str | None = None,
     ) -> Address:
         """Deploy a contract to the allocation."""
         raise NotImplementedError("deploy_contract is not implemented in the base class")

src/pytest_plugins/execute/pre_alloc.py

@@ -119,15 +119,6 @@ def pytest_addoption(parser):
         type=int,
         help="The default amount of wei to fund each EOA in each test with.",
     )
-    pre_alloc_group.addoption(
-        "--address-stubs",
-        action="store",
-        dest="address_stubs",
-        default=AddressStubs(root={}),
-        type=AddressStubs.model_validate_json_or_file,
-        help="The address stubs for contracts that have already been placed in the chain and to "
-        "use for the test. Can be a JSON formatted string or a path to a YAML or JSON file.",
-    )
 
 
 @pytest.hookimpl(trylast=True)
@@ -143,9 +134,13 @@ def pytest_report_header(config):
 
 
 @pytest.fixture(scope="session")
-def address_stubs(request) -> AddressStubs:
-    """Return an address stubs object."""
-    return request.config.getoption("address_stubs")
+def address_stubs(request) -> AddressStubs | None:
+    """
+    Return an address stubs object.
+
+    If the address stubs are not supported by the subcommand, return None.
+    """
+    return request.config.getoption("address_stubs", None)
 
 
 @pytest.fixture(scope="session")
@@ -223,6 +218,7 @@ def deploy_contract(
         address: Address | None = None,
         evm_code_type: EVMCodeType | None = None,
         label: str | None = None,
+        stub: str | None = None,
     ) -> Address:
         """Deploy a contract to the allocation."""
         if storage is None:
@@ -232,8 +228,24 @@ def deploy_contract(
         if not isinstance(storage, Storage):
             storage = Storage(storage)  # type: ignore
 
-        if label and label in self._address_stubs:
-            return self._address_stubs[label]
+        if stub is not None and self._address_stubs is not None:
+            if stub not in self._address_stubs:
+                raise ValueError(f"Stub name {stub} not found in address stubs")
+            contract_address = self._address_stubs[stub]
+            code = self._eth_rpc.get_code(contract_address)
+            if code == b"":
+                raise ValueError(f"Stub {stub} at {contract_address} has no code")
+            balance = self._eth_rpc.get_balance(contract_address)
+            nonce = self._eth_rpc.get_transaction_count(contract_address)
+            super().__setitem__(
+                contract_address,
+                Account(
+                    nonce=nonce,
+                    balance=balance,
+                    code=code,
+                    storage={},
+                ),
+            )
 
         initcode_prefix = Bytecode()
 
@@ -509,7 +521,7 @@ def pre(
     chain_config: ChainConfig,
     eoa_fund_amount_default: int,
     default_gas_price: int,
-    address_stubs: AddressStubs,
+    address_stubs: AddressStubs | None,
     request: pytest.FixtureRequest,
 ) -> Generator[Alloc, None, None]:
     """Return default pre allocation for all tests (Empty alloc)."""

src/pytest_plugins/execute/rpc/remote.py

@@ -8,6 +8,7 @@
 from ethereum_test_rpc import EngineRPC, EthRPC
 from ethereum_test_types.chain_config_types import ChainConfigDefaults
 
+from ..pre_alloc import AddressStubs
 from .chain_builder_eth_rpc import ChainBuilderEthRPC
 
 
@@ -40,6 +41,15 @@ def pytest_addoption(parser):
         default=60,
         help="Maximum time in seconds to wait for a transaction to be included in a block",
     )
+    remote_rpc_group.addoption(
+        "--address-stubs",
+        action="store",
+        dest="address_stubs",
+        default=AddressStubs(root={}),
+        type=AddressStubs.model_validate_json_or_file,
+        help="The address stubs for contracts that have already been placed in the chain and to "
+        "use for the test. Can be a JSON formatted string or a path to a YAML or JSON file.",
+    )
 
     engine_rpc_group = parser.getgroup("engine_rpc", "Arguments defining engine RPC configuration")
     engine_rpc_group.addoption(

src/pytest_plugins/filler/pre_alloc.py

@@ -142,6 +142,7 @@ def deploy_contract(
         address: Address | None = None,
         evm_code_type: EVMCodeType | None = None,
         label: str | None = None,
+        stub: str | None = None,
     ) -> Address:
         """
         Deploy a contract to the allocation.