Tenderly Integration: Where Transaction Debugging Breaks Down
A transaction reverts on the production network, and the explorer leaves only a “failed” status with gas spent.
There is no reason: the smart contract could have reverted without an error message, could have failed on a nested call to someone else’s protocol, or could have diverged from expected logic after a state change. The team sees the fact of failure and does not understand at which step the call chain went wrong.
Then manual reconstruction begins. The engineer brings up an archive node, replays the transaction at the same block height, walks through nested calls, decodes event logs, and compares them with the contract source.
If the path goes through a proxy, a library, and an external exchange, dozens of frames accumulate, and every missed level is another round of searching through code.
The cost of such debugging is hours per transaction. While one failed call is being analyzed, the next one breaks the same path, and the state at the required height is not preserved: if the node has already pruned history, there is nothing with which to reproduce the failure.
Call tracing and revert analysis are needed at the moment of the incident, not pieced together from node logs after the fact — let’s break down how this is covered.
What Continuous Debugging and Contract Monitoring Provides
A contract failure usually surfaces from a complaint: the transaction reverts, and the node log contains only the status and hash. The cause lies deeper — in internal calls that managed to change state before the final revert.
We connect Tenderly to the project, and every call becomes visible: arguments, returned values, and the place where logic diverged from expectation.
Call Diagnostics Instead of Version Brute-Force
Tracing shows the entire call chain, not just the last stack frame. The engineer sees the specific internal call where the contract reverted and fixes the cause instead of testing hypotheses — recovery time drops from hours of brute-force to tens of minutes.
Error Alerts Before a Complaint
We define contract monitoring rules by conditions: revert rate above a threshold, a sharp increase in resource consumption per call, calls to administrative methods.
Such triggers go to the on-call engineer’s channel, so some incidents are closed before the client encounters an error.
Completeness of the Call Picture
Not only reverts are visible, but successful transactions as well: how often a method is called, with what arguments, and how state changed. This removes the “it all worked for us” argument — what remains is a reproducible set of input data for checking a new contract version.
Incident Analysis and On-Call Team Workload
Incident analysis follows a ready-made history: saved trace, state before and after, and a list of affected addresses.
The on-call engineer does not bring up an archive node or collect data manually — routine checks are replaced by a single query, and nighttime calls remain for real emergencies.
We keep the rules configuration in the repository next to the contracts: it is versioned and reviewed like code.
Connection Modes: Network Copy, Test Environment, Mainnet
The connection mode determines which state the transaction is run against, and the value of the trace depends on this.
Tenderly connects to the network in three modes: a local fork spins up a snapshot of mainnet for us — real contracts, balances, and pool depth at the selected block, but isolated; a test environment provides a faithful execution environment with a sandboxed state — the contracts are the same, but the oracles are synthetic; mainnet responds with current data, but read-only.
| Option | When it fits | Limitations |
|---|---|---|
| Local fork | Analyzing failures on real data, rare scenarios: partial liquidation, limit trigger, call race in one block | The snapshot is static, state does not move on its own, external calls have to be mocked |
| Test environment | Deployment checks, access rights, end-to-end integration cycle before release | Data and prices are synthetic — discrepancies with mainnet surface later |
| Mainnet simulation | Final check before sending, exact gas usage and call result | State cannot be changed, only the current state of affairs is reproduced |
How Debugging Capabilities Differ
In a fork, we override state before the run: account balance, storage slots, timestamp, and response of an external service. A full step-by-step trace with storage changes is available both there and in the test environment — the difference is in data reliability, not in detail.
On mainnet, the debugging step is also visible, but the scenario is limited to the current state: you cannot set conditions that do not currently exist on the network. Therefore, the final run is done on the current block, and scenarios with changed state are only on a fork.
Implementing Tenderly Integration: Stages of Engineering Work
We assemble Tenderly integration as part of the observability loop, not as a separate developer tool: the on-call team must see the cause of a transaction failure before a user writes about it. The work proceeds in stages — from auditing the current state to handing over documentation.
How the Work Proceeds
- Integration audit. We look at which contracts and networks are already in operation, where transactions fail most often, which events are not logged, and what data completeness is missing for analysis.
- Connection scheme. We determine collection points: network nodes, signing services, internal queues. We fix which data goes to the external debugger and which remains inside the environment.
- Data collection. We configure call recording with depth sufficient for analyzing nested calls, but without excess volume — the speed of finding the cause depends directly on this.
- Alert setup. We bind rules to specific failure types: unsuccessful call, gas usage spike, recurring revert. The signal goes to the on-call engineer’s working channel, not email.
- Trace verification. We run previously collected failed transactions and compare: the system shows the same cause as manual analysis and does not lose nested calls.
- Documentation handover. We provide the connection scheme, the list of rules, and an analysis of typical reverts with a note on what to look at first.
The on-call team receives not a set of dashboards, but a procedure: which signal to check what by and in what order. The path from failure to a clear cause is reduced from hours to minutes.
Delivery Scope: Configurations, Alerts, Procedures
Delivery for debugging integration is not access to someone else’s panel and not a one-time emergency analysis. The customer’s team retains artifacts by which a transaction can be analyzed on its own, without contacting us. Below is exactly what is fixed and in what form.
What Remains in the Repository
- Working debugging configurations: profiles for mainnet and test environments, scripts for rerunning a failed transaction on a local fork.
- Contract and dependency map: addresses, “who calls whom” relationships, external call points, and trusted roles — during a failure, it is clear where the chain broke.
- Alert rules: which events are considered emergency, to whom and where the signal goes, and which thresholds are set so the on-call engineer does not drown in noise.
- Scheme of Tenderly integration with your systems: data flows, failure points, and behavior when the external service is unavailable.
- Set of checks on confirmed scenarios: which paths are closed automatically before rollout and how to read the discrepancy report.
Access, Roles, and Procedures
- Access matrix: who only views, who edits configurations, and who has the right to rerun on mainnet.
- Response procedure: detection, localization, rollback or fix, root cause analysis — with fixed timeframes for each step.
- Handover procedure: training the on-call shift, joint analysis of two representative failures, and support during the first period on your side.
We deliver each item in operation on your infrastructure, not as a description.
Case Study: How Contract Failure Analysis Time Was Reduced
Contract failure analysis starts the same way: the user sees that the transaction did not go through, and the on-call engineer has nothing but a hash and a revert flag.
Before debugging was implemented, the shift had to reproduce the call manually — bring up a local copy of the network and repeat the same sequence of operations.
What Changed for the On-Call Shift
The cause took 40–60 minutes to find, and some failures were not reproducible at all: the state on which the call failed had already changed by the time of analysis.
We connected Tenderly and moved diagnostics to tracing actual calls — the on-call engineer opens the failed transaction and immediately sees the step where the revert fired and the variable values at that moment.
Time to cause dropped from 40–60 to 5–8 minutes. Analysis no longer required a contract developer at the first step: escalation remained only where code needed to be changed, not where an already occurred revert had to be understood.
What It Delivered
A class of reverts disappeared that previously reached users: errors in the call chain between contracts that were not caught by tests on fixed states.
We set up alerts for abnormal gas usage and for reverts of specific methods — the shift learns about a problem before the user does.
The share of incidents going beyond the team decreased roughly threefold. Analysis became reproducible: any trace can be revisited a week later and used to show exactly where the call logic diverges.
How Does Local Debugging Differ from In-Network Monitoring?
Local debugging answers the question “why did this call fail.” The engineer takes a network fork at the required block, replays the transaction with the same input data, and goes step by step: where state changed, at which nested call the return fired, what was written to the logs.
As long as the failure is reproducible, this is the fastest path to the cause — but only for the scenario that already happened and that could be repeated.
| Criterion | Local debugging on a fork | In-network monitoring |
|---|---|---|
| Task | Analyze a failure that occurred | Catch a problem as it appears |
| What is visible | Step-by-step trace, state before and after the call | Stream of live calls and deviations from the norm |
| Reaction time | Hours: reproduce and isolate | Seconds: alert on deviation |
| Coverage | One scenario per run | All contract calls without exception |
| Limitation | Does not catch what was not reproduced | Does not provide analysis inside the call |
In-network monitoring solves the opposite task: it does not explain the past, but notices the present.
Calls run continuously, and real-time alerts trigger on deviation from the usual profile — growth in the share of failed transactions, change of caller address, atypical gas usage on a routine operation.
The order is set by the cost of an error: monitoring is enabled before the failure happens, debugging during analysis. The approaches feed each other: a triggered alert provides a transaction for fork analysis, and the found cause becomes a new rule for alerts. Both sides are covered by Tenderly — a fork for debugging and monitoring of live calls in one loop.
Technical Doubts Before Connecting Debugging
Integration with Tenderly is an observability layer on top of already running contracts, not a rewrite of the project.
Doubts about integration usually come down to four questions: whether debugging will reach closed networks, whether anything will need to be rebuilt, whether the nodes will withstand the call flow, and what happens after launch.
Does debugging work in a closed network?
Yes. We deploy the tracer in your environment next to the nodes, data travels over an internal channel and is not published externally. We grant access by role and restrict it at the project level.
Do already deployed contracts need to be rebuilt?
No. Analysis is built from the bytecode and input data of executed calls; the address and storage remain the same. Readable function and variable names are pulled in when a source map is available; without it, addresses, selectors, and state changes are visible.
What will happen to the nodes under a high call flow?
Tracing runs after a block is included, outside the execution path, so response time does not increase. We limit analysis depth and storage volume, and configure filtering for problematic calls — under load, revert analysis is preserved, not the history of every request.
Who supports debugging after launch?
We hand over access, the relationship map, and instructions for reading traces to your team. We stay in touch for incidents: analysis of stuck and failed calls, fine-tuning filtering rules, and updating schemas when contracts change.
Describe your network and contracts — we will get back with an estimate and connection plan.Let’s Discuss the Task: What We Clarify and What We Send in Response
We start the conversation not with a presentation, but with your task: integration with Tenderly hinges not on the tool itself, but on how it fits into incident analysis and pre-deployment checks for contracts.
Usually 40–60 minutes with an engineer who handles such integrations is enough — enough to understand the scope and not come back with clarifications for weeks.
On the first call, we clarify:
- which networks and environments need to be covered — production network, test environment, separate state branches;
- how you currently catch failed transactions and how much time one analysis takes;
- who on the team works with the debugger and what permissions each participant needs;
- requirements for storing call history and exports for analyzing disputed operations;
- restrictions on access, secrets, and your infrastructure;
- priority of the first stage: incident response or pre-deployment checks;
- who on the customer side accepts the result and in what form.
In response, we send an estimate and work plan, a connection scheme with integration points into your processes, implementation timelines by stage, and working conditions — what we do and what remains on your side.
Describe the task in a letter or a short call — we will get back with an estimate and plan and name the nearest realistic start date.