feat: show_trace() method on ReceiptAPI

.pre-commit-config.yaml

@@ -21,7 +21,7 @@ repos:
     -   id: flake8
 
 -   repo: https://github.com/pre-commit/mirrors-mypy
-    rev: v0.950
+    rev: v0.961
     hooks:
     -   id: mypy
         additional_dependencies: [types-PyYAML, types-requests]

docs/methoddocs/api.md

@@ -78,6 +78,22 @@
     :show-inheritance:
 ```
 
+## Transactions
+
+```{eval-rst}
+.. autoclass:: ape.api.transactions.ReceiptAPI
+    :members:
+    :show-inheritance:
+    :exclude-members: __repr__, __weakref__, __metaclass__, __init__
+```
+
+```{eval-rst}
+.. autoclass:: ape.api.transactions.TransactionAPI
+    :members:
+    :show-inheritance:
+    :exclude-members: __repr__, __weakref__, __metaclass__, __init__
+```
+
 ## Query
 
 ```{eval-rst}

docs/userguides/transactions.md

@@ -131,6 +131,90 @@ In your `ape-config.yaml` file, add the following:
 transaction_acceptance_timeout: 600  # 5 minutes
 ```
 
+## Traces
+
+If you are using a provider that is able to fetch transaction traces, such as the [ape-hardhat](https://github.com/ApeWorX/ape-hardhat) provider, you can call the [`ReceiptAPI.show_trace()`](../methoddocs/api.html?highlight=receiptapi#ape.api.transactions.ReceiptAPI.show_trace) method.
+
+```python
+from ape import accounts, project
+
+owner = accounts.load("acct")
+contract = project.Contract.deploy(sender=owner)
+receipt = contract.methodWithoutArguments()
+receipt.show_trace()
+```
+
+**NOTE**: If your provider does not support traces, you will see a `NotImplementedError` saying that the method is not supported.
+
+The trace might look something like:
+
+```bash
+Call trace for '0x43abb1fdadfdae68f84ce8cd2582af6ab02412f686ee2544aa998db662a5ef50'
+txn.origin=0x1e59ce931B4CFea3fe4B875411e280e173cB7A9C
+ContractA.methodWithoutArguments() -> 0x00..7a9c [469604 gas]                                                                                                                                     
+├── SYMBOL.supercluster(x=234444) -> [                                                                                                                                                            
+│       [23523523235235, 11111111111, 234444],                                                                                                                                                    
+│       [                                                                                                                                                                                         
+│         345345347789999991,                                                                                                                                                                     
+│         99999998888882,                                                                                                                                                                         
+│         345457847457457458457457457                                                                                                                                                             
+│       ],                                                                                                                                                                                        
+│       [234444, 92222229999998888882, 3454],                                                                                                                                                     
+│       [                                                                                                                                                                                         
+│         111145345347789999991,                                                                                                                                                                  
+│         333399998888882,                                                                                                                                                                        
+│         234545457847457457458457457457                                                                                                                                                          
+│       ]                                                                                                                                                                                         
+│     ] [461506 gas]                                                                                                                                                                              
+├── SYMBOL.methodB1(lolol="ice-cream", dynamo=345457847457457458457457457) [402067 gas]                                                                                                           
+│   ├── ContractC.getSomeList() -> [                                                                                                                                                              
+│   │     3425311345134513461345134534531452345,                                                                                                                                                  
+│   │     111344445534535353,                                                                                                                                                                     
+│   │     993453434534534534534977788884443333                                                                                                                                                    
+│   │   ] [370103 gas]                                                                                                                                                                            
+│   └── ContractC.methodC1(                                                                                                                                                                       
+│         windows95="simpler",                                                                                                                                                                    
+│         jamaica=345457847457457458457457457,                                                                                                                                                    
+│         cardinal=ContractA                                                                                                                                                                      
+│       ) [363869 gas]                                                                                                                                                                            
+├── SYMBOL.callMe(blue=tx.origin) -> tx.origin [233432 gas]                                                                                                                                       
+├── SYMBOL.methodB2(trombone=tx.origin) [231951 gas]                                                                                                                                              
+│   ├── ContractC.paperwork(ContractA) -> (                                                                                                                                                       
+│   │     os="simpler",                                                                                                                                                                           
+│   │     country=345457847457457458457457457,                                                                                                                                                    
+│   │     wings=ContractA                                                                                                                                                                         
+│   │   ) [227360 gas]                                                                                                                                                                            
+│   ├── ContractC.methodC1(windows95="simpler", jamaica=0, cardinal=ContractC) [222263 gas]                                                                                                       
+│   ├── ContractC.methodC2() [147236 gas]                                                                                                                                                         
+│   └── ContractC.methodC2() [122016 gas]                                                                                                                                                         
+├── ContractC.addressToValue(tx.origin) -> 0 [100305 gas]                                                                                                                                         
+├── SYMBOL.bandPractice(tx.origin) -> 0 [94270 gas]                                                                                                                                               
+├── SYMBOL.methodB1(lolol="lemondrop", dynamo=0) [92321 gas]                                                                                                                                      
+│   ├── ContractC.getSomeList() -> [                                                                                                                                                              
+│   │     3425311345134513461345134534531452345,                                                                                                                                                  
+│   │     111344445534535353,                                                                                                                                                                     
+│   │     993453434534534534534977788884443333                                                                                                                                                    
+│   │   ] [86501 gas]                                                                                                                                                                             
+│   └── ContractC.methodC1(windows95="simpler", jamaica=0, cardinal=ContractA) [82729 gas]                                                                                                        
+└── SYMBOL.methodB1(lolol="snitches_get_stiches", dynamo=111) [55252 gas]                                                                                                                         
+    ├── ContractC.getSomeList() -> [                                                                                                                                                              
+    │     3425311345134513461345134534531452345,                                                                                                                                                  
+    │     111344445534535353,                                                                                                                                                                     
+    │     993453434534534534534977788884443333                                                                                                                                                    
+    │   ] [52079 gas]                                                                                                                                                                             
+    └── ContractC.methodC1(windows95="simpler", jamaica=111, cardinal=ContractA) [48306 gas]                                                                                                      
+```
+
+Additionally, you can view the traces of other transactions on your network.
+
+```python
+from ape import networks
+
+txn_hash = "0x053cba5c12172654d894f66d5670bab6215517a94189a9ffc09bc40a589ec04d"
+receipt = networks.provider.get_transaction(txn_hash)
+receipt.show_trace()
+```
+
 ## Estimate Fees
 
 To estimate the fees on a transaction without sending it, use the `as_transaction()` method to get a reference to a transaction API object.

setup.cfg

@@ -7,3 +7,6 @@ exclude =
 per-file-ignores =
     # Need signal handler before imports
     src/ape/__init__.py: E402
+	# Test data causes long lines
+	tests/functional/data/python/__init__.py: E501
+	tests/functional/utils/expected_traces.py: E501

setup.py

@@ -19,7 +19,7 @@
     ],
     "lint": [
         "black>=22.3.0,<23.0",  # auto-formatter and linter
-        "mypy>=0.950,<1.0",  # Static type analyzer
+        "mypy>=0.961,<1.0",  # Static type analyzer
         "types-PyYAML",  # NOTE: Needed due to mypy typeshed
         "types-requests",  # NOTE: Needed due to mypy typeshed
         "flake8>=4.0.1,<5.0",  # Style linter
@@ -93,9 +93,8 @@
     install_requires=[
         "backports.cached_property ; python_version<'3.8'",
         "click>=8.1.0",
-        "eth-account==0.5.7",
-        "ethpm-types>=0.3.1,<0.4.0",
-        "evm-trace>=0.1.0.a2",
+        "ethpm-types>=0.3.2,<0.4.0",
+        "evm-trace>=0.1.0.a6",
         "hexbytes>=0.2.2,<1.0.0",
         "packaging>=20.9,<21.0",
         "pandas>=1.3.0,<2.0",
@@ -113,11 +112,12 @@
         "rich>=10.14,<11",
         "tqdm>=4.62.3,<5.0",
         "typing-extensions ; python_version<'3.8'",
-        "web3[tester]>=5.29.0,<6.0",
-        "eth_abi==2.1.1",
-        "eth-utils==1.10.0",
-        "eth-rlp==0.2.1",
         "python-dateutil>=2.8.2,<3.0",
+        "web3[tester]>=5.29.0,<6.0",
+        "eth-abi>=2.1.1,<3.0",
+        "eth-utils>=1.10.0,<2.0",
+        "eth-rlp>=0.2.1,<0.3",
+        "eth-account==0.5.7",
     ],
     entry_points={
         "console_scripts": ["ape=ape._cli:cli"],

src/ape/api/networks.py

@@ -1,14 +1,14 @@
 from functools import partial
 from pathlib import Path
-from typing import TYPE_CHECKING, Any, Dict, Iterator, List, Optional, Type
+from typing import TYPE_CHECKING, Any, Dict, Iterator, List, Optional, Tuple, Type, Union
 
 from ethpm_types.abi import ConstructorABI, EventABI, MethodABI
 from hexbytes import HexBytes
 from pydantic import BaseModel
 
 from ape.exceptions import NetworkError, NetworkNotFoundError
 from ape.types import AddressType, ContractLog, RawAddress
-from ape.utils import BaseInterfaceModel, abstractmethod, cached_property
+from ape.utils import BaseInterfaceModel, abstractmethod, cached_property, raises_not_implemented
 
 from .config import PluginConfig
 
@@ -287,6 +287,24 @@ def decode_logs(self, abi: EventABI, raw_logs: List[Dict]) -> Iterator[ContractL
             Iterator[:class:`~ape.types.ContractLog`]
         """
 
+    @raises_not_implemented
+    def decode_primitive_value(
+        self, value: Any, output_type: Union[str, Tuple, List]
+    ) -> Union[str, HexBytes, Tuple]:
+        """
+        Decode a primitive value-type given its ABI type as a ``str``
+        and the value itself. This method is a hook for converting
+        addresses, HexBytes, or other primitive data-types into
+        friendlier Python equivalents.
+
+        Args:
+            value (Any): The value to decode.
+            output_type (Union[str, Tuple, List]): The value type.
+
+        Returns:
+            Union[str, HexBytes, Tuple]
+        """
+
     @abstractmethod
     def create_transaction(self, **kwargs) -> "TransactionAPI":
         """

src/ape/api/transactions.py

@@ -1,16 +1,18 @@
+import sys
 import time
-from typing import TYPE_CHECKING, Iterator, List, Optional, Union
+from typing import IO, TYPE_CHECKING, Iterator, List, Optional, Union
 
 from ethpm_types import HexBytes
 from ethpm_types.abi import EventABI
+from evm_trace import TraceFrame
 from pydantic.fields import Field
 from tqdm import tqdm  # type: ignore
 
 from ape.api.explorers import ExplorerAPI
 from ape.exceptions import TransactionError
 from ape.logging import logger
 from ape.types import ContractLog, TransactionSignature
-from ape.utils import BaseInterfaceModel, abstractmethod
+from ape.utils import BaseInterfaceModel, abstractmethod, cached_iterator, raises_not_implemented
 
 if TYPE_CHECKING:
     from ape.contracts import ContractEvent
@@ -148,7 +150,6 @@ class ReceiptAPI(BaseInterfaceModel):
     gas_limit: int
     gas_price: int
     gas_used: int
-    input_data: str = ""
     logs: List[dict] = []
     nonce: Optional[int] = None
     receiver: str
@@ -161,12 +162,16 @@ class ReceiptAPI(BaseInterfaceModel):
     def __repr__(self) -> str:
         return f"<{self.__class__.__name__} {self.txn_hash}>"
 
-    def raise_for_status(self):
+    @property
+    def failed(self) -> bool:
         """
-        Handle provider-specific errors regarding a non-successful
-        :class:`~api.providers.TransactionStatusEnum`.
+        Whether the receipt represents a failing transaction.
+        Ecosystem plugins override this property when their receipts
+        are able to be failing.
         """
 
+        return False
+
     @property
     @abstractmethod
     def ran_out_of_gas(self) -> bool:
@@ -178,6 +183,13 @@ def ran_out_of_gas(self) -> bool:
             same amount of gas as the given ``gas_limit``.
         """
 
+    @cached_iterator
+    def trace(self) -> Iterator[TraceFrame]:
+        """
+        The trace of the transaction, if available from your provider.
+        """
+        return self.provider.get_transaction_trace(txn_hash=self.txn_hash)
+
     @property
     def _explorer(self) -> Optional[ExplorerAPI]:
         return self.provider.network.explorer
@@ -195,6 +207,12 @@ def _confirmations_occurred(self) -> int:
 
         return latest_block.number - self.block_number
 
+    def raise_for_status(self):
+        """
+        Handle provider-specific errors regarding a non-successful
+        :class:`~api.providers.TransactionStatusEnum`.
+        """
+
     def decode_logs(self, abi: Union[EventABI, "ContractEvent"]) -> Iterator[ContractLog]:
         """
         Decode the logs on the receipt.
@@ -266,3 +284,14 @@ def await_confirmations(self) -> "ReceiptAPI":
                 time.sleep(time_to_sleep)
 
         return self
+
+    @raises_not_implemented
+    def show_trace(self, verbose: bool = False, file: IO[str] = sys.stdout):
+        """
+        Display the complete sequence of contracts and methods called during
+        the transaction.
+
+        Args:
+            verbose (bool): Set to ``True`` to include more information.
+            file (IO[str]): The file to send output to. Defaults to stdout.
+        """

src/ape/managers/chain.py

@@ -403,8 +403,8 @@ def __setitem__(self, address: AddressType, contract_type: ContractType):
             contract_type (ContractType): The contract's type.
         """
 
-        if self.get(address):
-            return  # Already cached
+        if self.get(address) and self._is_live_network:
+            return
 
         self._local_contracts[address] = contract_type
 
@@ -432,10 +432,12 @@ def get(
 
         Args:
             address (AddressType): The address of the contract.
+            default (Optional[ContractType]): A default contract when none is found.
+              Defaults to ``None``.
 
         Returns:
             Optional[ContractType]: The contract type if it was able to get one,
-              otherwise ``None``.
+              otherwise the default parameter.
         """
 
         contract_type = self._local_contracts.get(address)

src/ape/managers/project/dependency.py

@@ -113,7 +113,7 @@ class LocalDependency(DependencyAPI):
 
     @property
     def path(self) -> Path:
-        given_path = Path(self.local)
+        given_path = Path(self.local).absolute()
         if not given_path.exists():
             raise ProjectError(f"No project exists at path '{given_path}'.")