Skip to content
Snippets Groups Projects

Btcpayserver plugin

Open napoly requested to merge napoly/ccs-proposals:btcpayserver-plugin into master

Overview

Hello everyone!

We are thrilled to announce our plans to refactor the Monero integration for BTCPay Server. With the release of BTCPay Server 2.0, the platform has undergone a major update, introducing breaking changes to the Monero integration. This redesign transitions non-core features, such as Monero support, into a plugin-based architecture. This shift provides an excellent opportunity for the Monero community to take ownership of the integration and ensure its long-term development. The BTCPay team has expressed their support for this initiative, and we are fully committed to making it a success. To prepare for this work, the Monero codebase has already been migrated into its own repository, paving the way for its transition into a standalone plugin.

We’d like to thank the BTCPay development team, particularly @NicolasDorier, for laying the groundwork for the Monero plugin and ensuring a stable transition from core integration. As they noted in PR #6535, the move to plugins empowers the Monero community to take full control of its development and lifecycle—without being bottlenecked by core BTCPay priorities or unfamiliarity with Monero’s internals.

How did we get here?

The initial integration was developed by @Kukks of the BTCPay team and funded through a CCS proposal by an anonymous donor. While this implementation successfully introduced Monero support to BTCPay Server, there is an opportunity to expand its functionality by adding features such as multi-wallet support and enhanced wallet management tools. During our work on open bounties and 2 for the Monero community, we identified the need to realign our efforts on the plugin migration to ensure continued support for Monero within BTCPay Server.

Thanks to funding from the Magic Grants and Coincards, we had the opportunity to meet at Monerotopia 2024 and analyze this challenge in depth. During this collaboration, we established a comprehensive roadmap and a plugin repository with CI/CD support for stable releases and development. The plugin is currently in the proof-of-concept stage, with a focus on establishing a solid foundation for the plugin.

There was initial confusion in the Monero community about whether BTCPay Server would continue maintaining the Monero integration after 2.0. To clarify: the plugin is now fully community-owned. BTCPay Server will no longer hosts or manages the Monero integration beyond platform-level support and docker artifacts following BTCPayServer v2.1. This proposal is intended to ensure the plugin remains functional, actively developed, and aligned with Monero users’ expectations.

What's next?

We are seeking funding to continue developing and maintaining the Monero plugin for BTCPay Server. This includes building a robust proof of concept and minimum viable product (MVP), improving the user interface, addressing bugs, and assisting with merchant migration from the legacy Monero integration. Our near-term goal is to merge earlier boilerplate work, developed after Monerotopia 2024, into the current plugin repository and begin its migration to the new btcpay-monero GitHub organization. This move will help formalize community ownership and better organize contributions going forward.

We aim to extend the plugin with capabilities to manage multiple Monero wallets within a single BTCPay Server instance. This enhancement will enable third-party hosting scenarios, allowing service providers to support multiple vendors without requiring each vendor to manage their own infrastructure. This is particularly beneficial for merchants who prefer a hosted solution over self-deployment.

In addition, there are several open bounties currently available for the Monero integration:

We propose incorporating these bounty funds into the broader plugin development effort, ensuring that all outstanding tasks align with our roadmap and long-term strategy.

As part of this transition, we also plan to eventually migrate Dockerfiles and supporting infrastructure currently hosted under the BTCPay organization to the btcpay-monero GitHub org. This reduces reliance on BTCPay’s infrastructure and aligns with their recommendation that each altcoin community manage its own deployment lifecycle and testing.

Contributors:

Milestones

Milestone 1: Requirements Analysis and Core Infrastructure

  • Deliverables:
    • Plugin repository established and accessible.
    • Operational CI/CD pipeline for plugin development and releases.
    • Testing framework and code coverage
    • Support for existing merchants and users
  • Funds: 15% of funds
  • Timeline: Week 1-4
  • Status: Mostly done

Milestone 2: Refactor of UI and Improvements

  • Deliverables:
    • UI improvements for Monero daemon configuration.
    • Functional wallet setup interface (create, import, export, update).
    • Release as v0.1.0
  • Funds: 25%
  • Timeline: Week 5-10
  • Status: Not started

Milestone 3: Minimum Viable Product (MVP) for Multiwallet Support

  • Deliverables:
    • Dockerize monero-lws if not available
    • Onboarding redesign to support both wallet-rpc and lws
    • Basic monero-lws support tested and integrated.
    • Release as 0.2.0
  • Funds: 35%
  • Timeline: Week 11-18
  • Status: Not started

Milestone 4: Final Release (Polishing and Merchant Migration)

  • Deliverables:
    • UI/UX enhancements for seamless user experience.
    • Comprehensive documentation (installation, usage, troubleshooting, migration).
    • Bug fixing and testing.
    • Review remote node implementation
    • Final release of the plugin.
    • Post-release support and maintenance plan.
  • Funds: 25%
  • Timeline: Week 19-24
  • Status: Not started

Timeline

The integration process is expected to take approximately 16-24 weeks.

Future Roadmap

  • Plans for ongoing maintenance and support for the plugin.
  • Launch first community instance of BTCPay
  • Expand wallet features and functionality.
  • Continue reviewing open pull request, complete testing and manage releases
Edited by napoly

Merge request reports

Members who can merge are allowed to add commits.

Merge request pipeline #872 passed

Merge request pipeline passed for 5c16f596

Loading
Loading

Activity

Filter activity
  • Approvals
  • Assignees & reviewers
  • Comments (from bots)
  • Comments (from users)
  • Commits & branches
  • Edits
  • Labels
  • Lock status
  • Mentions
  • Merge request status
  • Tracking
  • plowsoff resolved all threads

    resolved all threads

  • plowsoff added 1 commit

    added 1 commit

    Compare with previous version

  • Contributor

    BTCPay Server is one of the most widely used self-hosted cryptocurrency payment processors out there for online merchants and in-person POS. Monero plugin support is top priority. +1

  • BTCPay powers all the Monero payments at Coincards.com

    This plugin is necessary for our business to continue to support Monero and the monero community. Without this plugin, or a plugin of some sort for Monero, Coincards would be forced to delist Monero as a payment method. As many of you know, Monero is usually the #2 most interacted with currency on our platform, and even sometimes it takes the #1 (closed) spot.

    Monero is Digital cash, and is used daily. This plugin alongside BTCPay gives ANY merchant out there the quick and easy ability to accept Monero.

    Coincards will be supporting this CCS, but we need the support of the community as a whole to work together to get this work done.

  • Contributor

    It should be noted that the btcpayserver team has already began migrating the plugin.

    https://github.com/btcpayserver/btcpayserver-monero-plugin

  • I want to give a heads-up on BTCPay Server's plan to remove Monero from the core source code in version 2.1 (Expected February/March 2025)

    First, please take a moment to read this PR description.

    I want to acknowledge that the Monero community has been the most responsible altcoin community in maintaining the code and dependencies. I am deeply thankful to all of you.

    As for the BTCPay Server team, our priority is to release version 2.1 with a Monero plugin that works as it does today, minimizing disruptions for our merchants. What happens beyond this is up to you. We will support your efforts and are here to answer any questions you may have about plugin development.

    I also want to note that our efforts do not conflict with the work previously done by @napoly (referenced here: https://github.com/btcpayserver/btcpayserver/pull/6239).

    The only difference is that his PR will need to target the btcpayserver-monero-plugin repository rather than the core code.

    I have gone beyond merely porting the Monero code to the plugin. This is because I value your contributions and recognize that many merchants rely on Monero:

    If you try to develop on the new plugin, you’ll notice the code is now trivially manually testable. When running the plugin in debug mode on regtest, the checkout invoice page includes a "Cheat Mode," which allows you to send a Monero transaction or mine a block. This makes plugin development significantly easier compared to when the Monero integration was part of the core codebase. In other words, the development experience of Monero on plugin is superior to the one that was on core.

    After the release of version 2.1, the btcpayserver-monero-plugin repository will be transferred to someone trusted within your community.

    You will have two main options moving forward:

    1. Add multi-wallet support to the btcpayserver-monero-plugin.
    2. Leave the current plugin as-is, but create a new plugin (btcpayserver-monero-plugin-2) by forking the existing repository. This will retain the ability to easily debug and simulate transactions.

    I haven’t thought too much about which solution is best for you... It probably doesn't make that much difference. Ultimately, this decision will be yours to make.

    Regardless of your choice, I believe a multi-wallet Monero plugin is an important goal and efforts of @napoly should be encouraged. The current single-wallet plugin poses security risks when the server is shared with other parties.

    The current plugin is a security problem for:

    1. Merchants having staff
    2. Ambassadors (people who onboard other people on their own server)
    Edited by Nicolas Dorier
  • @NicolasDorier thank you for providing feedback here and making sure Monero will be supported in BTCPayServer versions 2.1 and upwards.

    I feel the sane thing to do here is close this proposal while we wait for version 2.1 to be released.

    SGP noted in the community meeting today:

    "I think there's not much to do at this stage. Nicolas is doing us a big favor by making the initial plugin with the same features and better testing for BTCPay 2.1. After that, then a maintainer needs to be picked and then the main goals need to be established and worked on"

    https://libera.monerologs.net/monero-community/20250118#c488233

    MAGIC have also put their name in the hat to ensure the repository is maintained.

  • By far the most used merchant PoS platform for Monero, and one that underpins the largest Monero merchants like Cake Pay, Concords, Shopinbit, and many more.

    Improving support for Monero in BTCPay is VITAL to continuing to grow the circular economy around Monero, and so I'm psyched to see such capable people jumping in to take on this effort.

    Huge :thumbsup: from me!

  • I think this project is very important and essential for the monero community as a whole. I am not a coder unfortunately however I love to promote monero to individuals and small business owners.One of the most frequent questions is, how do I accept monero? Having a dedicated Point of Sales software that is easy to install and set up for Monero or other coins would make the efforts 100% easier. BTCpayserver has done an already amazing job, I’m very grateful for their openness to allow Monero to build on the project and I think this project should receive funding as soon as possible. If we don’t promote easy ways for adoption for merchants, Monero will never become a real currency used but a niche project that will stay underground while we are enslaved by digital fiat currencies and digital IDs. I really don’t want to start paying attention to how many carbon credits I’m allowed per week. So let’s get this baby going

  • @napoly do you have thoughts on the feedback so far?

    • As far as I know, there is no support from version 2.1 onward, and there is no blocker here. @deverickapollo and I remain focused and understand the tasks ahead. Achieving multi-wallet functionality could attract more merchants, as they would no longer need to manage the complexities of the underlying infrastructure. This, in turn, could pave the way for a new wave of ambassadors willing to run the stack. Ultimately, this would lead to satisfied, privacy-conscious customers and additional funding to further support development.

    • Contributor

      there is no support from version 2.1 onward

      It is

      As for the BTCPay Server team, our priority is to release version 2.1 with a Monero plugin that works as it does today, minimizing disruptions for our merchants. What happens beyond this is up to you.

      https://github.com/btcpayserver/btcpayserver-monero-plugin

    • Please register or sign in to reply
  • What's the status on this? In general I'm in favor of a CCS to support the plugin, and would donate, but I'm looking for details.

    • I would also like to comment on this: This plugin is really urgently needed. There is trocador app as a plugin, which would enable the processing of Monero via a third party, but we want to avoid this if possible. In the medium term, the plugin is therefore a good solution. In the long term, it will probably run on a fork to a kind of “CryptoPayServer” to reflect the Bitcoin-focused mentality of this project/the main developers. A server that supports as many crypto values as possible without exclusion would be very valuable, BCH is already blocked here.

    • The plugin has been made and will release with version 2.1 of BTCPayServer. If you want an alternative that supports BCH, https://bitcart.ai/ which allows people to host a third party instance where multiple users/wallets can register.

      Edited by plowsoff
    • Please register or sign in to reply
  • https://libera.monerologs.net/monero-community/20250215#c496831

    This should be closed and resubmitted with the acknowledgement that the full plugin exists imo. Maybe Nicolas is done and is waiting on the Monero community to choose a maintainer? But it's currently unclear. That code hasn't been touched in 2 weeks

    • I believe the focus of this conversation should be aligning the community on feature requirements to ensure we are driving forward value as a product. This is a warning to the community as there has been little coordinated effort to continue building our MVP candidate for merchants. I'm not sure the reasoning but we are here to improve this integration. If you believe the current implementation is production ready, I'd either question your technical skills, underlying motives or just assume you've never managed BTCPayServer.

      I would like to first address any confusion related to the future of Monero on BTCPay. @napoly and myself have been working closely with @NicolasDorier to support the migration of monero to the plugin. Feel free to join the BTCPayServer chat to participate in some of that discussion. To ensure a smooth transition, @NicolasDorier migrated all code to a separate repository and is planning a coordinated handoff following the release of v2.1. The first decision our community should be making is where we would like to host the project going forward.

      Second, the community should align on features we would like to see. @napoly and I can design, propose and implement our thoughts but we want to hear from customers. We want to hear from those that rely on this tool daily. As previously stated by @napoly and @NicolasDorier, there is currently no blockers to continuing planning and development of this integration. Most of the planned features are merged from previous requests.

      Multiwallet support: This is a critical feature that aligns monero with the rest of the BTCPay ecosystem. Current implementation exposes a single wallet instance to all stores. TLDR: The current implementation removes the ability to share a single instance with separate nontrusted parties. Resolving this issue would improve our 3rd party hosting options for payment processors. You can see a list of 3rd party hosts in the BTCPAY directory. https://directory.btcpayserver.org/filter/hosts We could have something similar for monero if we fixed this issue.

      Closing this topic when its clear we should be making decisions seems wrong. We should be more proactive rather than reactive.

      Edited by Deverick
    • This proposal will be discussed today at the Community Meeting https://github.com/monero-project/meta/issues/1164

    • @plowsofff - This invite was hours before the meeting so I wasn't able to attend. If this will be a topic for the next meeting, I would be happy to attend. Please let me know so we can plan accordingly. Thanks

    • Meetings are every other Saturday https://github.com/monero-project/meta/issues/1169

    • Please register or sign in to reply
  • I think we're at an impasse here.

    There are two main goals:

    1. Finding a home for the plugin repo, and an immediate, ongoing need for maintenance of that plugin.
    2. Adding new features such as multi-wallet support.

    Personally, I see #1 (closed) as significantly more important than #2.

    Where should the repo reside?

    Currently, the repository resides at https://github.com/btcpayserver/btcpayserver-monero-plugin, but Nicolas has stated that the intent is to transfer this to some Monero community-managed repo.

    One option is to move this under https://github.com/monero-project, but that received some criticism from @ofrnxmr, and I also don't think it's a great idea.

    So if not that, then what? This is our first major issue that we need to solve.

    @napoly could host the repo on their personal account, though that's probably not ideal either.

    My suggestion is to move the repo under https://github.com/MAGICGrants. This has several key advantages:

    1. The repository lives under a non-profit organization that has an established relationship with the Monero community and has an interest in keeping this plugin alive (we use the plugin ourselves).
    2. Napoly could be added as the lead maintainer of the plugin repository, meaning we can support immediate maintenance efforts that will arise and ensure the plugin does not stop working.
    3. MAGIC Grants can help with fundraising efforts for this, such as reaching out to companies that would most benefit from a multi-wallet feature. This is easier with the help of a 501(c)(3) nonprofit; donations could be tax deductible and we can include other donor protections that would be difficult to do otherwise.

    I pitched this idea to @deverickapollo who says they pitched it to @napoly, and I was told that @napoly does not like this idea.

    So we don't currently know where this repo is supposed to live.

    Support for maintenance is near-universal, but the Monero community is less interested in new features

    I'm sure you can find someone against maintaining this plugin, but there is near-universal support for making sure that Monero continues to work with BTCPay Server. It's clear that that should be someone responsible for maintaining this, and I'm confident that the funds can be raised to ensure this happens.

    However, the Monero community feedback for additional features have been mixed. I think there's one key reason: the main proposed feature (multi-wallet with monero-lws) does not really benefit the people who are commenting on this proposal.

    I think this is a substantial reason why enthusiasm for this proposal has been limited.

    It's not this proposal or Monero support is dead

    Some people understandably want to support this proposal because their businesses rely on this plugin, and they fear that if this doesn't proceed, that the plugin will die. Luckily, that's not the case.

    Maintenance is pretty easy and cost-effective. Because the BTCPay Server maintainers know that Monero support is important, and because they have generously updated the plugin to support BTCPay Server 2.0 already, Monero support isn't going anywhere without a fight.

    This means that additional features can be considered more strategically. And I think that is exactly what will need to happen to get these finally started.

    Summary

    I personally think that this CCS proposal, as written, is difficult to support. There's no clear answer to where the plugin should exist and why. There haven't been any attempts (that I'm aware of) to reach out to the companies that may want this multi-wallet feature, and to see if they will sponsor at least part of that effort.

  • Parking this plugin repository is important, but not essential, as it’s FOSS under the MIT license, meaning anyone can take it and run with it. For now, I’m inclined to host it under my personal account so we can move forward quickly without being blocked by permissions, tokens, etc. However, I’m open to migrating, bridging, or mirroring the repository to a more suitable location later, as I don’t want to be a gatekeeper.. That said, I believe this requires a broader discussion, as hosting it under MAGICGrants, monero-project, monero-integrations, or my personal account each has its pros and cons that need to be carefully considered. But I don’t think this thread should be sidetracked, delayed or blocked by that decision/discussion.

    Supporters of this proposal need to understand that this is an enterprise-level feature that introduces a decentralized new layer of ambassadors who will be running the infrastructure, actively seeking and onboarding new vendors.. It should also bring this integration closer to self-sufficiency, which benefits everyone. Reaching out to companies that may want this multi-wallet feature seems meaningless without a green light from the community.

  • Loading
  • Loading
  • Loading
  • Loading
  • Loading
  • Loading
  • Loading
  • Loading
  • Loading
  • Loading
  • Please register or sign in to reply
    Loading