When a user reports a failed crypto transaction, a wallet connection problem, or an unexpected application error, the first instinct may be to send the issue straight to the development team. But an escalation without enough information often leads to more questions, longer resolution times, and unnecessary back-and-forth between support agents, users, and developers.
In Web3, where transactions may be irreversible and issues can involve wallets, smart contracts, and multiple blockchain networks, collecting the right information from the beginning is essential. A structured support process helps teams identify the problem, rule out common causes, and give technical specialists the context they need to investigate.
Here’s what your support team should collect before escalating a blockchain issue.
1. A Clear Description of the Problem
Start by understanding what the user was trying to do and what happened instead. Ask the user to describe the issue in their own words. Then clarify the expected result and the actual result. For example:
- Expected result: The user wanted to swap ETH for a token.
- Actual result: The swap failed, but the wallet still shows a gas fee was charged.
- When it happened: The issue occurred after the user confirmed the transaction in their wallet.
Avoid relying on vague descriptions such as “the app is broken” or “my transaction isn’t working.” These statements may describe different underlying problems. Useful questions include:
- What action were you trying to complete?
- What happened after you confirmed it?
- Did you receive an error message?
- Has this happened more than once?
The objective is to establish a clear timeline and understand the user’s intended action before investigating further.
2. The Blockchain Network
Always establish which blockchain network the user was using. A transaction on Ethereum mainnet is different from one on Arbitrum, Base, Polygon, or another network. Even when applications support multiple networks, their contracts, balances, and transaction histories may differ.
Ask the user to confirm the network selected in their wallet or application. Examples include:
- Ethereum mainnet
- Arbitrum One
- Base
- Polygon PoS
If the user is unsure, a transaction hash or block explorer link may help identify the network.
This information is especially important when investigating missing tokens, failed transactions, incorrect network selections, and wallet connection issues.
3. The Transaction Hash or Relevant Wallet Address
For an on-chain transaction, the transaction hash is one of the most useful pieces of information you can collect. A transaction hash allows a support agent or developer to inspect publicly available blockchain data, including the transaction status, block information, and execution result. Ask the user for:
- The transaction hash, if a transaction was submitted.
- The relevant public wallet address, when needed.
- A block explorer link, if available.
For example, an Ethereum transaction can be investigated using a suitable explorer such as Etherscan.
If no transaction hash exists, don’t assume the transaction failed on-chain. The issue may have occurred before broadcast, during wallet signing, or within the application’s interface.
Security reminder: Never ask users for their seed phrase, private key, wallet password, or secret recovery information. Support staff do not need these credentials to investigate a transaction.
4. The Exact Error Message
Ask the user to provide the complete error message rather than a paraphrase.
For example, “Transaction failed to sign” and “execution reverted” can indicate problems at different stages of the transaction process. The exact wording can help narrow down whether the issue involves:
- Wallet connection or signing
- Transaction submission
- Network congestion or fee configuration
- Smart contract execution
- Application-side validation
Request a screenshot when it helps show where the error appeared.
Screenshots should be checked for sensitive information before being shared with other teams. If the issue occurs without an error message, record that too.
5. The Wallet and Application Details
Record which wallet and application the user was using. Relevant details may include:
- Wallet name, such as MetaMask, Trust Wallet, or another supported wallet.
- Whether the user was using a browser extension or mobile application.
- The application or website where the issue occurred.
- Browser and operating system, when relevant.
- Whether the wallet was connected through a browser, WalletConnect, or another supported method.
These details help developers determine whether the issue may be specific to a wallet, device, connection method, or application integration.
Do not ask for unnecessary personal information. Collect only the technical details needed to investigate the issue.
6. The Steps That Reproduced the Issue
A developer needs to understand how the problem occurred, not just the final error. Ask the user to describe the steps leading up to the issue in chronological order. For example:
- Opened the decentralized application.
- Connected a wallet.
- Selected a token pair.
- Entered the swap amount.
- Confirmed the transaction in the wallet.
- Received an error message after confirmation.
If the problem is reproducible, document the conditions under which it happens. Also record whether the user has already tried troubleshooting steps, such as reconnecting the wallet or refreshing the page.
This prevents support teams from repeatedly suggesting the same actions without new evidence.
7. The Approximate Time of the Incident
Record the date and time when the issue occurred, including the time zone if possible. Timestamps help developers correlate a user report with application logs, RPC provider errors, monitoring alerts, and blockchain activity.
For recurring problems, record whether the issue happens consistently or only intermittently. If multiple users report the same problem around the same time, the information may help identify a broader service incident rather than an isolated user issue.
8. What Has Already Been Checked?
Before escalating, document the checks already completed and their results. Depending on the issue, these may include:
- Confirming the selected network.
- Checking the transaction hash in a block explorer.
- Confirming that the wallet is connected to the intended application.
- Reviewing the exact error message.
- Checking whether the application reports a known incident.
- Reproducing the problem, if safe and appropriate.
Do not ask users to repeat risky transactions or spend additional funds merely to reproduce an error. Any further testing should follow the application’s approved troubleshooting process.
A good escalation includes both what the team found and what remains unknown.
9. A Clear Impact and Priority Assessment
Not every blockchain issue requires the same escalation path. Determine whether the problem affects one user or many, whether a core application function is unavailable, and whether there are credible signs of an active security incident. For example:
- One user cannot connect a wallet.
- Several users report that swaps are failing.
- Users report unexpected transactions or suspected unauthorized access.
- A critical application function is unavailable across a network.
- Suspected exploits, unauthorized transactions, and active security incidents should follow the project’s security escalation procedure immediately.
- Do not delay urgent reporting while collecting every field on the checklist.
- Support agents should never promise that funds can be recovered or that a transaction can be reversed.
- Blockchain outcomes depend on the specific circumstances and protocol.
10. A Concise Escalation Summary
Once the necessary information has been collected, summarize the issue in a format that the technical team can act on. A useful escalation should explain:
- What the user was trying to do.
- What happened instead.
- Which network and wallet were involved.
- The transaction hash, if available.
- The exact error message.
- The time of the incident.
- The troubleshooting steps already completed.
- The number of users affected and the urgency.
- Any remaining questions or evidence needed.
This summary prevents developers from having to reconstruct the entire support conversation before beginning their investigation.
Blockchain Issue Escalation Checklist
Before handing an issue to the technical team, use this checklist to confirm that the essential details have been collected.
- Clear description of the problem
- Expected behavior versus actual behavior
- Blockchain network
- Transaction hash or relevant public wallet address, if applicable
- Exact error message and relevant screenshot
- Wallet, application, device, and connection method
- Steps to reproduce the issue
- Approximate incident time and time zone
- Troubleshooting steps already completed
- Number of users affected and urgency
- Security concerns flagged and escalated through the appropriate channel
Not every issue requires every field. For example, a wallet connection error that occurs before a transaction is created may not have a transaction hash. Collect the information relevant to the specific problem rather than delaying escalation to complete an unnecessary checklist.
Example: A Well-Prepared Escalation
Imagine a user reports that a token swap failed. Instead of forwarding the message “User can’t swap tokens,” the support agent could provide the following summary:
- Issue: Token swap fails after wallet confirmation.
- Network: Base.
- Wallet: MetaMask browser extension.
- Expected behavior: The swap should complete and the purchased tokens should appear in the wallet.
- Actual behavior: The user receives an error after confirming the transaction.
- Transaction hash: Provided by the user, if available.
- Error message: Exact message copied from the application.
- Time of incident: Date and time, including time zone.
- Troubleshooting completed: Confirmed the selected network and reviewed the transaction status in the relevant block explorer.
- Impact: One user reported the issue; broader impact has not yet been established.
- Requested investigation: Determine whether the transaction was broadcast, whether execution failed on-chain, or whether the error occurred before submission.
This gives developers a clear starting point without prematurely assuming the cause of the failure.
Build a Better Escalation Process for Your Web3 Support Team
Effective blockchain support isn’t just about answering questions quickly. It’s about gathering accurate information, protecting users, identifying patterns, and ensuring technical teams receive actionable reports.
A consistent escalation process can reduce unnecessary back-and-forth, help support agents handle common questions independently, and allow developers to focus on issues that genuinely require their expertise.
For Web3 projects, this becomes increasingly important as communities grow and support requests arrive across different wallets, applications, and blockchain networks.