From 5732b318805ff4f8b2207e4f87a6c46828af0e26 Mon Sep 17 00:00:00 2001 From: Juliya Smith Date: Mon, 15 Jan 2024 20:56:39 -0600 Subject: [PATCH] docs: updates --- docs/userguides/trace.md | 97 ++++++++++++++++++++++++++ docs/userguides/transactions.md | 119 +------------------------------- 2 files changed, 100 insertions(+), 116 deletions(-) create mode 100644 docs/userguides/trace.md diff --git a/docs/userguides/trace.md b/docs/userguides/trace.md new file mode 100644 index 0000000000..abb48f592b --- /dev/null +++ b/docs/userguides/trace.md @@ -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 +``` + diff --git a/docs/userguides/transactions.md b/docs/userguides/transactions.md index b0bceba996..235b67757a 100644 --- a/docs/userguides/transactions.md +++ b/docs/userguides/transactions.md @@ -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