Skip to content

Bug bounty program ​

Thank you for your interest in contributing to xcm-tools! We reward contributors for reporting and fixing bugs in the project.

Eligible tools ​

These tools and apps from the xcm-tools monorepo are part of the Bug Bounty Program:

Requirements ​

To keep the program focused on genuine human contributors and reproducible bugs, every bug report and fix must meet all of these requirements. Submissions that don't are closed without review.

Minimal Contributor Requirements
  • Established account: your GitHub commit history is at least 6 months old.
  • Proof of personhood: set an on-chain identity on the Polkadot People Chain for your AssetHub address and request a registrar judgement (official guide). dotID does this for free, with social/email verification and optional KYC for a stronger judgement. Maintainers check on Subscan that the judgement is at least Reasonable. Use the same address for payment. Nothing outside the Polkadot ecosystem is needed.
  • Signed commits: sign every commit in your PR with the -S flag and include this trailer:
    AI-Assisted-By: <tool name(s), e.g. "GitHub Copilot", "ChatGPT"> (or "None" if you didn't use one)
  • AI tools are welcome, autonomous agents are not: using AI tools (Copilot, ChatGPT, Claude, etc.) is fine if you disclose it, understand the resulting code, and can explain and defend it yourself. Autonomous agents that open PRs without a human reviewing and understanding the change are not eligible, regardless of disclosure.
  • Be ready to explain your work: answer maintainers' review questions specifically and on topic within 5 days. Without an answer, the reservation expires and the issue reopens for others. Generic, evasive, or off-topic answers get the PR closed and the reservation forfeited.
  • Extra verification for high-severity fixes: for 🟠 High fixes, maintainers may ask for a brief live chat or call walkthrough before payout, to confirm that a human authored the change and understands it.

DANGER

Repeated low-effort, undisclosed-AI, or automated submissions will result in a permanent ban from the Bug Bounty Program.

Minimal Reproduction for Bug Reports

Every bug report must include a minimal reproduction. This is the smallest code snippet or API request that triggers the bug through ParaSpell's public interfaces. A reproduction lets us confirm the bug quickly and shows that real users can run into it. Reports without a minimal reproduction will be closed.

Here are examples for the most common public interfaces:

ts
import { Builder } from '@paraspell/sdk'

const tx = await Builder()
  .from('Acala')
  .to('Astar')
  .currency({ location: LOCATION, amount: AMOUNT })
  .sender(SENDER_ADDRESS)
  .recipient(RECIPIENT_ADDRESS)
  .build()

// Expected: a valid transaction is returned
// Actual: throws UnhandledError: <full error message>
bash
curl https://api.paraspell.xyz/v2/chains/Hydration/para-id

# Expected: 2034
# Actual: 500 Internal Server Error
ts
import { getAssetsObject } from '@paraspell/sdk'

const assets = getAssetsObject('Acala')

// Expected: <the result described in the docs>
// Actual: throws <full error message> / returns <the incorrect value>

A good reproduction:

  • Is complete. Please replace placeholders such as LOCATION and AMOUNT with the exact values you used, so that we can run it ourselves. For XCM API calls, include the full URL and any request body. Your own addresses can stay as placeholders unless the bug depends on them.
  • Uses only public interfaces. These are the Builder, the XCM API endpoints and the functions described in this documentation.
  • Names the version. For npm packages, include the package name and the exact version you installed, as shown in your lockfile.
  • Shows the expected and actual result. Include the full error message or the incorrect value, and describe what you expected instead.
  • Is minimal. Leave out anything that isn't needed to trigger the bug.

The following are not accepted as a minimal reproduction:

  • A description of the bug in words only, without code or a request that triggers it.
  • Code that calls internal functions directly, for example from the generated JS bundle or from files that the package doesn't export.
  • A new unit test (for example in Vitest) that triggers an error that can't occur through the public interfaces.

If you found the bug by reading internal code, please still reproduce it through a public interface. You're welcome to mention the internal function you think causes it.

Bugs in the XCM Playground and errors in the docs can't always be shown in code.

For the Playground, please list the exact steps and inputs that trigger the bug, and add a screenshot or a short screen recording. The Playground saves your inputs in the page URL, so you can also share the URL of the failed transfer or query. For example:

text
https://playground.paraspell.xyz/xcm-sdk/xcm-transfer?currencies={%22currencyOptionId%22:%22ASTR-NO_ID%22,%22customCurrency%22:%22%22,%22isCustomCurrency%22:false,%22customCurrencyType%22:%22id%22,%22customCurrencySymbolSpecifier%22:%22auto%22,%22amount%22:%22100%22,%22isMax%22:false}

For the docs, a link to the page and a quote of the incorrect text are enough.

Report a bug ​

Critical issues

Please don't open a public issue for πŸ”΄ Critical bugs such as security vulnerabilities. If you think that the issue is critical, report it privately by email to info.paraspell@gmail.com or through the contact form on paraspell.xyz, so that we can assess it immediately.

  1. Open an issue in the repository and select Bug bounty report.
  2. Please fill in every section of the issue template and keep the sections as they are. Issues that don't follow the template will be closed. Reports that don't meet every point of the Contributor Eligibility checklist won't receive a reward.
  3. Include a minimal reproduction. Issues without one will be closed.
  4. Submit the issue. Maintainers review it and assign a severity level. Once they confirm the bug, they add the "Confirmed bug πŸͺ²" label, which opens the issue for reservation.

Rewards for reports ​

Maintainers determine severity based on impact and may contact you for clarification.

Low
$5–10
Very minor errors in docs / text / code
Medium
$10–15
Minor UI issues, typos, or cosmetic bugs
High
$15–20
Bugs affecting user features or causing functional issues
Critical
$20–70
Crashes, data loss, security vulnerabilities, or major broken functionality

Reporting or fixing grammar errors in the documentation that don't affect functionality or clarity isn't rewarded, but you're very welcome to open a PR fixing them.

Fix a bug ​

Reserving the Issue
  • Only issues that maintainers have confirmed with the "Confirmed bug πŸͺ²" label can be reserved.
  • Comment I would like to reserve this issue. on the issue. It is assigned to you and reserved for 48 hours. If no PR is opened by then, the reservation expires.
  • You may reserve one issue at a time. Submit or drop your current reservation before reserving another. Issues reserved in violation of this are reassigned.
  • Someone already reported it or opened a PR? Comment to express intent and, if allowed, follow the same reservation and PR process. Keep your contribution additive and clearly explained.
Submitting the Fix

Make sure your PR follows these rules and has high-quality code. We will not review PRs that don't meet our quality standards.

Please open PRs only for issues reserved for you. This way, no two contributors end up working on the same fix.

  1. Fork the repository and create a new branch.
  2. Commit using a Conventional Commits message with a type and scope (see below), including the Signed-off-by and AI-Assisted-By trailers.
  3. Open a pull request and fill in every section of the PR template, keeping the sections as they are. PRs that don't follow the template will be closed. Fixes that don't meet every point of the Contributor Eligibility checklist won't receive a reward.
    • Under Related Issue, link your reserved issue with Closes #<issue number>.
    • Under Description of the Fix, explain in your own words what caused the bug and why your change fixes it, rather than only summarizing the diff.
    • Complete the Contributor Eligibility and Checklist sections and add your Polkadot Asset Hub address.
  4. Tag @michaeldev5 to request a review.

Commit messages ​

Write commit messages as type(scope): description. This helps automate changelog generation and keeps the project consistent.

  • type is one of feat, fix, perf, revert, docs, style, chore, refactor, test, build or ci.
  • scope is the package or app you changed, named after its folder in packages/ or apps/, for example sdk-core, sdk, assets, swap, xcm-api, xcm-analyser or playground.
  • description says briefly what the commit does.

For example, a signed fix in the SDK core package, with the Signed-off-by (-s) and AI-Assisted-By trailers:

bash
git commit -S -s -m "fix(sdk-core): Handle null case in token parser" \
  --trailer "AI-Assisted-By: None"
What each commit type means
  • feat: new features (Features)
  • fix: bug fixes (Bug Fixes)
  • perf: code changes that improve performance (Performance Improvements)
  • revert: revert a previous commit (Reverts)
  • docs: changes to documentation only (Documentation)
  • style: code style changes such as formatting or whitespace (Styles)
  • chore: routine tasks, hidden in changelogs (Miscellaneous Chores)
  • refactor: code changes that neither fix bugs nor add features (Code Refactoring)
  • test: adding or updating tests (Tests)
  • build: changes that affect the build system or external dependencies (Build System)
  • ci: CI configuration and scripts (Continuous Integration)

Rewards for fixes ​

Rewards depend on code complexity and quality, as determined by maintainers. The $250 for High is not a hard cap: the final amount depends on the task and can be higher. Critical issues are fixed by the ParaSpell team, so they carry no fix bounty.

Low
$5–10
Small fix (e.g., 1-2 lines), config changes
Medium
$10–50
Contained fix in one module (e.g., edge cases, validation, error handling)
High
$50–250+
Logic changes, multi-file fixes, test additions
Critical
No bounty
Fixed by the ParaSpell team, as critical issues need to be assessed immediately

Tips ​

  • Follow the existing code style and structure.
  • Write meaningful commit messages.
  • Include unit tests if applicable.
  • Keep PRs focused: one issue per pull request.
  • Add inline comments on important changes and new functions.
  • Be respectful and collaborative in discussions.

FAQ ​

Can I report and fix the same bug?

Yes! You can both report and fix the bug. Once maintainers confirm it with the "Confirmed bug πŸͺ²" label, please reserve it as outlined above before working on the fix.

Can I use AI tools to help with my fix?

Yes, using tools like GitHub Copilot, ChatGPT, or Claude to help you write a fix is fine, as long as you disclose it via the AI-Assisted-By commit trailer, understand the code you're submitting, and can explain and defend it during review. Submissions from autonomous agents that open PRs without a human reviewing and understanding the change first are not eligible, and repeated attempts will result in a permanent ban.

What happens if I reserve an issue but don’t submit a PR in 48 hours?

The issue becomes unreserved and open for others to claim. You may re-reserve it if it's still unassigned.

How do you determine reward amounts?
  • Bug reports are evaluated based on user impact and severity.
  • Fixes are evaluated based on code complexity, design quality, and completeness (tests, documentation).
How do I receive payment?

Your payment will be sent to the AssetHub Polkadot address you provided in the issue or PR, and the amount will be paid in USDC. Please ensure you only provide non-cex addresses in the PR, because the payment may not arrive correctly. The payment should be processed within 2 business days after the issue is resolved or the PR is merged.

Need help? ​

If you're unsure how to start or have questions about an issue or PR, reach out through the contact form on our landing page, on our X, or in our Telegram support channel.

We appreciate your support and contributions!

The ParaSpell✨ Team

Released under the MIT License.