This guide teaches you how to write clear, actionable bug reports for crypto testnets and early-stage DeFi platforms. You'll help development teams identify and fix issues faster while contributing meaningfully to projects you care about. Expected time: 10-15 minutes. Difficulty: Beginner. You'll need basic understanding of blockchain wallets and testnet participation.
Why Good Bug Reports Matter
Testnet participants discover 45% of critical bugs before mainnet launch according to blockchain development research. Your bug reports directly impact protocol security, user experience, and launch readiness. Poor reports waste developer time with missing information, while effective reports accelerate fixes and demonstrate your value to the project.
Development teams face hundreds of testnet submissions during active testing phases. Reports that include reproduction steps, transaction signatures, and environment details get prioritized and resolved 3-4x faster than vague descriptions like "it doesn't work."
What Makes a Bug Report Effective
The Three Essential Elements
Reproduction Steps: Developers must recreate the bug on their end. Number each action precisely with exact button names, wallet selections, and input values. Include preconditions like required token balances or network configurations.
Evidence: Transaction signatures, console errors, screenshots, and program logs prove the bug exists. On Solana and other blockchains, every failed transaction creates a signature that developers can analyze in block explorers. Visual proof eliminates back-and-forth clarification requests.
Context: Environment details separate one-off user errors from systemic issues. Include network type, program version, wallet type, browser, operating system, and account state. Projects test across devnet, testnet, and mainnet-beta with different configurations.
Quick Bug Report Template
Use this structure for any crypto testnet:
Environment
- Network: devnet / testnet / mainnet-beta
- Program ID or Contract Address: [deployed address]
- Wallet: Phantom v24.1 / MetaMask v11.5 / Backpack
- Browser: Chrome v123, Firefox v120, Brave
- OS: Windows 11, macOS 14, Ubuntu 22.04
Bug Summary
One sentence describing the issue and severity.
Example: "Transaction fails when opening leveraged position with 10x multiplier - High severity"
One sentence describing the issue and severity.
Example: "Transaction fails when opening leveraged position with 10x multiplier - High severity"
Steps to Reproduce
- Navigate to [specific page]
- Connect [wallet type]
- Select [specific option]
- Enter [exact values]
- Click [button name]
- Observe [what happens]
Expected vs Actual Behavior
Expected: Transaction confirms and position appears in dashboard
Actual: Loading spinner shows for 30 seconds, then UI freezes with no error message
Expected: Transaction confirms and position appears in dashboard
Actual: Loading spinner shows for 30 seconds, then UI freezes with no error message
Technical Evidence
- Transaction signature: 5J7xKm... or "None - tx never submitted"
- Console error: "Error: custom program error: 0x1771"
- Network response: POST /api/positions - 500 Internal Server Error
- Screenshots: [attach frozen UI, error messages, network tab]
Frequency
Always / Sometimes 60% / Once - tried 3 times, failed twice
Always / Sometimes 60% / Once - tried 3 times, failed twice
Where to Submit Bug Reports
Most crypto projects use GitHub Issues for technical bugs. Check the project's repository README or documentation for contribution guidelines. Some platforms prefer Discord channels labeled "bug-reports" or "testnet-feedback" for immediate triage.
For security vulnerabilities or exploits, use private channels first. Look for bug bounty programs on platforms like Immunefi or HackerOne, or contact the team directly at security@ emails listed in documentation. Never publicly disclose critical security issues before giving teams time to patch.
Solana projects often maintain dedicated testnet Discord channels where you can report issues and discuss with other testers. Include your wallet address only when necessary for developers to check on-chain state.
What to Include: Specific Details
Transaction Information
Every blockchain interaction creates verifiable on-chain records. Include transaction signatures so developers can inspect program logs, account states, and error codes. On Solana, use explorers like Solscan or SolanaFM. On EVM chains, use Etherscan variants.
Failed transactions show exactly which instruction failed and why. Success transactions that produce wrong results need signatures too - developers compare expected vs actual account state changes.
Error Messages
Copy full error text from browser console, wallet popups, and UI notifications. Developers need exact wording to search codebases and identify which function threw the error. "Transaction simulation failed: Insufficient collateral" points to different code than "Transaction failed: Slippage tolerance exceeded."
Program logs appear in transaction details on block explorers. These show execution flow through smart contract functions, identifying exactly where logic breaks. Include relevant log excerpts in your report.
Account State
DeFi protocols rely on specific account configurations. Include balances of relevant tokens, SOL or ETH for gas, positions you hold, and any approvals granted. Bugs often emerge from edge cases like zero balances, dust amounts, or accounts without rent-exempt minimums.
On Solana, programs create Program Derived Addresses for user state. If you notice a PDA wasn't created when expected, that's critical information. Developers can inspect your authority address to see all associated accounts.
Common Mistakes to Avoid
Vague Descriptions: "The swap doesn't work" lacks actionable information. Better: "Swapping 100 USDC for SOL on Jupiter fails with 'Insufficient liquidity' error despite pool showing 50K USDC available."
Missing Environment: Bugs often appear on specific configurations. The same transaction might succeed on Chrome/Phantom but fail on Firefox/Backpack. Always specify your setup.
No Reproduction Steps: If developers can't recreate the bug, they can't fix it. "It crashed" needs "It crashes when I do X, then Y, then Z with these exact values."
Assumptions vs Facts: Report what you observed, not what you think caused it. "The oracle is broken" is an assumption. "Price shows $45,000 for BTC while CoinGecko shows $43,000 - tx signature abc123" gives facts.
Screenshots Without Context: An image of an error message needs the steps that produced it. Screen recordings work better for multi-step issues.
Severity Levels Explained
Critical
Total fund loss, protocol halt, unauthorized access, or infinite minting. Example: "Users can withdraw more collateral than deposited by calling closePosition twice." These need immediate private disclosure to security teams, not public GitHub issues.
High
Broken core functionality, incorrect calculations affecting user funds, or data corruption. Example: "PnL calculation shows -50% profit as +50% loss, causing wrong liquidations." These block normal usage and need urgent fixes.
Medium
Degraded user experience, non-critical errors, or workarounds available. Example: "Transaction requires 3 attempts to succeed - works on retry with same parameters." Annoying but doesn't block core functionality.
Low
Visual bugs, typos, unclear messaging, or optimization opportunities. Example: "Connect wallet button misaligned on mobile Safari." Polish issues for post-launch improvement.
Best Practices for Testnet Participation
Test Systematically: Don't just execute happy paths. Try edge cases like maximum values, zero amounts, rapid repeated clicks, disconnecting wallet mid-transaction, and switching networks unexpectedly.
Document as You Go: Write steps while testing, not from memory later. You'll forget critical details that explain why the bug occurred. Keep screenshots organized with timestamps.
Check Known Issues: Review existing GitHub issues or Discord pins before reporting. Duplicate reports waste time. If your bug matches an existing issue, add your reproduction case and environment details as a comment.
Be Respectful: Remember teams are working to build products you'll benefit from. Professional, helpful reports build relationships and increase your visibility in the community. Demanding or critical tone achieves nothing.
Follow Up: If developers ask questions or need more information, respond quickly. Testnet windows are often short - delays mean bugs might not get fixed before mainnet.
Advanced Tips
Include Video Recordings
Tools like Loom or OBS let you record screen activity while reproducing bugs. Video shows exact click sequences, timing, and system behavior developers might miss in written steps. Especially valuable for intermittent bugs that don't happen every time.
Suggest Root Causes When Qualified
If you have development experience and can identify likely causes from error messages or code review, include your hypothesis. "Appears to be missing rent-exempt check on account initialization around line 234" helps, but clearly label it as speculation not fact.
Compare Expected Standards
If competing protocols handle the same action differently, note it. "Uniswap shows estimated output before swap confirmation, but this DEX requires blind transaction approval" highlights UX gaps.
Test Across Configurations
If you have access to multiple devices, wallets, or operating systems, test the same action across setups. Reporting "Bug occurs on Chrome/Phantom but not Firefox/Backpack" immediately narrows debugging scope.
Example: Well-Written Bug Report
Environment
Network: devnet
Program: PropDEX v0.2.1 - Program ID: 7xK9Ab2Cd...
Wallet: Phantom v24.16.1
Browser: Chrome v123 on Windows 11
Account: 9wM3FxLm... - 2.5 SOL, 100 USDC
Network: devnet
Program: PropDEX v0.2.1 - Program ID: 7xK9Ab2Cd...
Wallet: Phantom v24.16.1
Browser: Chrome v123 on Windows 11
Account: 9wM3FxLm... - 2.5 SOL, 100 USDC
Bug Summary
Opening long position with 10x leverage fails with simulation error - High severity
Opening long position with 10x leverage fails with simulation error - High severity
Steps to Reproduce
- Navigate to https://testnet.propdex.trade/perpetuals
- Connect Phantom wallet
- Select BTC-PERP market from dropdown
- Set leverage slider to 10x
- Enter 100 USDC collateral
- Click "Open Long Position"
- Approve transaction in Phantom
Expected Behavior
Transaction submits to network, position appears in "Open Positions" table with 1000 USDC notional size
Transaction submits to network, position appears in "Open Positions" table with 1000 USDC notional size
Actual Behavior
Phantom shows transaction preview, clicking approve shows error: "Transaction simulation failed: custom program error: 0x1771"
No transaction signature generated
Phantom shows transaction preview, clicking approve shows error: "Transaction simulation failed: custom program error: 0x1771"
No transaction signature generated
Technical Evidence
Console error: "Error at instruction index 2: custom program error: 0x1771"
Network tab: POST /api/v1/positions/open - 200 OK response but no tx signature in payload
Screenshot: [attached Phantom error dialog]
Console error: "Error at instruction index 2: custom program error: 0x1771"
Network tab: POST /api/v1/positions/open - 200 OK response but no tx signature in payload
Screenshot: [attached Phantom error dialog]
Additional Context
Same steps succeed with 5x leverage and 100 USDC
Bug started after v0.2.1 deployment yesterday
Occurs on both BTC-PERP and ETH-PERP markets
Five community members confirmed in Discord channel testnet-issues
Same steps succeed with 5x leverage and 100 USDC
Bug started after v0.2.1 deployment yesterday
Occurs on both BTC-PERP and ETH-PERP markets
Five community members confirmed in Discord channel testnet-issues
Frequency
Always - 5 attempts all failed
Always - 5 attempts all failed
This report gives developers everything needed: exact reproduction steps, error codes to search in the codebase, conditions where it works vs fails, and community validation it's not a one-off issue.
Quick Checklist Before Submitting
- Environment details complete: network, program version, wallet, browser, OS
- Steps numbered and specific enough for developers to recreate
- Transaction signature included or noted as "none generated"
- Expected vs actual behavior clearly stated
- Error messages copied verbatim from console/wallet
- Screenshots or video attached showing the issue
- Severity level assigned based on impact
- Frequency noted: always, sometimes, once
- Checked existing issues for duplicates
- Tone is professional and constructive
Resources for Learning More
Most blockchain projects maintain contribution guidelines in their GitHub repository under CONTRIBUTING.md. Read these before your first report - they often specify preferred formats, required information, and submission channels.
Join project Discord or Telegram communities to see how experienced testers structure reports and interact with development teams. Many projects highlight "bug hunter" roles for consistent quality contributions.
Solana documentation at docs.solana.com covers program errors, transaction anatomy, and debugging tools. Understanding how transactions execute helps you identify root causes and write more insightful reports.
Frequently Asked Questions
What information do I need to include in a testnet bug report?
Include environment details like network type, program version, wallet, browser, and OS. Provide numbered reproduction steps with exact button names and values entered. Add transaction signatures or note if none generated, console errors copied verbatim, and screenshots showing the issue. Specify expected vs actual behavior and how often the bug occurs. This gives developers everything needed to recreate and fix the issue without asking follow-up questions.
Where should I submit bug reports for crypto projects?
Most projects use GitHub Issues for technical bugs - check the repository README for contribution guidelines. Some prefer Discord channels labeled bug-reports or testnet-feedback for immediate triage. For security vulnerabilities or exploits, contact teams privately through bug bounty platforms like Immunefi, HackerOne, or security email addresses listed in documentation. Never publicly disclose critical security issues before teams can patch them.
How do I find transaction signatures for failed transactions?
Check your wallet's transaction history - even failed transactions generate signatures. In Phantom, click the activity tab to see all recent transactions including failures. In MetaMask, view your account on the relevant block explorer. For Solana, paste your wallet address into Solscan or SolanaFM to see all transactions. If truly no signature exists, that indicates the transaction never reached the network, which itself is valuable debugging information.
What's the difference between severity levels for bugs?
Critical bugs cause total fund loss, protocol halt, or security breaches like unauthorized withdrawals. High severity breaks core functionality or causes incorrect calculations affecting user funds. Medium severity degrades user experience with errors that have workarounds. Low severity covers visual bugs, typos, or optimization opportunities. Assign severity based on actual impact to users and protocol, not your frustration level. When uncertain, describe the impact and let developers classify it.
Should I report the same bug if others already mentioned it?
Check existing GitHub issues and Discord channels first to avoid duplicates. If your bug matches an existing report, add your reproduction case and environment details as a comment rather than creating a new issue. Your additional context helps if the bug appears under different conditions. If the existing report lacks transaction signatures or clear steps, your detailed contribution significantly speeds up debugging.
How detailed should reproduction steps be?
Detailed enough that a developer unfamiliar with your workflow can recreate the exact issue. Include preconditions like required token balances, numbered sequential actions with exact UI element names, specific values entered, and what you observe after each step. If more than 10 steps, consider if some can be summarized as preconditions. Too much detail is better than too little - developers can always skim, but can't fix bugs they can't reproduce.
What should I do if I find a security vulnerability?
Contact the team privately immediately through their security email, bug bounty program, or direct message to core developers. Do not post details publicly in Discord, Twitter, or GitHub issues. Give teams reasonable time to patch before any disclosure, typically 7-30 days depending on severity. Many projects offer significant bug bounty rewards for responsibly reported vulnerabilities through platforms like Immunefi, with critical findings earning thousands to millions.
How can I make my bug reports stand out to development teams?
Include transaction signatures so developers can inspect on-chain program logs. Add video recordings for complex multi-step issues. Test across multiple configurations like different wallets or browsers and report which combinations work vs fail. Suggest likely root causes if you have development experience, clearly labeled as hypotheses. Compare behavior to similar protocols when relevant. Most importantly, be professional, responsive to follow-up questions, and systematic in your testing approach.