Skip to content

Commit

Permalink
docs: updates
Browse files Browse the repository at this point in the history
  • Loading branch information
@antazoey
antazoey committed Jan 16, 2024
1 parent 09eca9a commit 5732b31
Show file tree
Hide file tree
Showing 2 changed files with 100 additions and 116 deletions.
97 changes: 97 additions & 0 deletions docs/userguides/trace.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,97 @@
# Traces

A transaction's trace frames are the individual steps the transaction took.
Using traces, Ape is able to offer features like:

1. Showing a pretty call-tree from a transaction receipt
2. Gas reporting in `ape test`
3. Coverage tools in `ape test`

Some network providers, such as Alchemy and Foundry, implement ``debug_traceTransaction`` and Parity's ``trace_transaction`` affording tracing capabilities in Ape.
**WARN**: Without RPCs for obtaining traces, some features such as gas-reporting and coverage are limited.

To see a transaction trace, use the [show_trace()](../methoddocs/api.html#ape.api.transactions.ReceiptAPI.show_trace) method on a receipt API object.

Here is an example using `show_trace()` in Python code to print out a transaction's trace.
**NOTE**: This code runs assuming you are connected to `ethereum:mainnet` using a provider with tracing RPCs.
To learn more about networks in Ape, see the [networks guide](./networks.html).

```python
from ape import chain

tx = chain.provider.get_receipt('0xb7d7f1d5ce7743e821d3026647df486f517946ef1342a1ae93c96e4a8016eab7')

# Show the steps the transaction took.
tx.show_trace()
```

You should see a (less-abridged) trace like:

```
Call trace for '0xb7d7f1d5ce7743e821d3026647df486f517946ef1342a1ae93c96e4a8016eab7'
tx.origin=0x5668EAd1eDB8E2a4d724C8fb9cB5fFEabEB422dc
DSProxy.execute(_target=LoanShifterTaker, _data=0x35..0000) -> "" [1421947 gas]
└── (delegate) LoanShifterTaker.moveLoan(
_exchangeData=[
0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE,
ZERO_ADDRESS,
...
# Abridged because is super long #
...
│ └── LendingRateOracle.getMarketBorrowRate(_asset=DAI) ->
│ 35000000000000000000000000 [1164 gas]
├── DSProxy.authority() -> DSGuard [1291 gas]
├── DSGuard.forbid(src=LoanShifterReceiver, dst=DSProxy, sig=0x1c..0000) [5253 gas]
└── DefisaverLogger.Log(
_contract=DSProxy,
_caller=tx.origin,
_logName="LoanShifter",
_data=0x00..0000
) [6057 gas]
```

## Tracing Calls

Some network providers trace calls in addition to transactions.
EVM-based providers best achieve this by implementing the `debug_traceCall` RPC.

If you want to see the trace of call when making the call, use the `show_trace=` flag:

```python
token.balanceOf(account, show_trace=True)
```

**WARN**: If your provider does not properly support call-tracing (e.g. doesn't implement `debug_traceCall`), traces are limited to the top-level call.

Ape traces calls automatically when using `--gas` or `--coverage` in tests to build reports.
Learn more about testing in Ape in the [testing guide](./testing.html) and in the following sections.

## Gas Reports

To view the gas report of a transaction receipt, use the [`ReceiptAPI.show_gas_report()`](../methoddocs/api.html?highlight=receiptapi#ape.api.transactions.ReceiptAPI.show_gas_report) method:

```python
from ape import networks

txn_hash = "0x053cba5c12172654d894f66d5670bab6215517a94189a9ffc09bc40a589ec04d"
receipt = networks.provider.get_receipt(txn_hash)
receipt.show_gas_report()
```

It outputs tables of contracts and methods with gas usages that look like this:

```
DAI Gas
Method Times called Min. Max. Mean Median
────────────────────────────────────────────────────────────────
balanceOf 4 1302 13028 1302 1302
allowance 2 1377 1377 1337 1337
│ approve 1 22414 22414 22414 22414
│ burn 1 11946 11946 11946 11946
│ mint 1 25845 25845 25845 25845
```

119 changes: 3 additions & 116 deletions docs/userguides/transactions.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -155,122 +155,9 @@ ethereum:
## 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_receipt(txn_hash)
receipt.show_trace()
```

In Ape, you can also show the trace for a call.
Use the `show_trace=` kwarg on a contract call and Ape will display the trace before returning the data.

```python
token.balanceOf(account, show_trace=True)
```

**NOTE**: This may not work on all providers, but it should work on common ones such as `ape-hardhat` or `ape-geth`.

## Gas Reports

To view the gas report of a transaction receipt, use the [`ReceiptAPI.show_gas_report()`](../methoddocs/api.html?highlight=receiptapi#ape.api.transactions.ReceiptAPI.show_gas_report) method:

```python
from ape import networks
txn_hash = "0x053cba5c12172654d894f66d5670bab6215517a94189a9ffc09bc40a589ec04d"
receipt = networks.provider.get_receipt(txn_hash)
receipt.show_gas_report()
```

It will output tables of contracts and methods with gas usages that look like this:

```bash
DAI Gas
Method Times called Min. Max. Mean Median
────────────────────────────────────────────────────────────────
balanceOf 4 1302 13028 1302 1302
allowance 2 1377 1377 1337 1337
│ approve 1 22414 22414 22414 22414
│ burn 1 11946 11946 11946 11946
│ mint 1 25845 25845 25845 25845
```
Transaction traces are the steps in the contract the transaction took.
Traces both power a myriad of features in Ape as well are themselves a tool for developers to use to debug transactions.
To learn more about traces, see the [traces userguide](./trace.md).
## Estimate Gas Cost
Expand Down

0 comments on commit 5732b31

Please sign in to comment.