BTCPayServer Multi-Store Support and Native GraphQL Client

Project Summary

Implement multi-store support for the plugin and replace the RPC layer with a GraphQL backend using Zkool directly.

Project Description

Rearchitect the plugin to use the Zkool GraphQL API directly instead of the legacy RPC API, together with full multi-store support, removing the need to configure the wallet from an administrator account. This should reduce the long-term maintenance cost of the plugin given that redundant logic will be dropped.

Implement integration and cheatmode testing to allow for faster testing and development. Better support for using agentic workflows. A merchant wiki will be created to help merchants decide on what solution best fits their needs including guidance for repurposing existing Bitcoin/Monero RPC integrations to support Zcash (i.e. using zecd/zcash-wallet-rpc).

Proposed Problem

zcash-walletd is no longer actively maintained.

BTCPayServer merchants using third-party hosting are unable to use the plugin. This limits adoption.

Proposed Solution

Moving fully to the Zkool GraphQL API in the plugin instead of reimplementing the zcash-walletd RPC API using the Zkool crate will make the plugin more stable and easier to maintain going forward, dropping the legacy API.

More details at:

5 Likes

For context:

This application aims to address these concerns re the current state of the plugin by integrating the Zkool GraphQL API directly into the C# plugin and switching fully to the multi-store API.

Progress so far on GitHub: Multi-Store and GraphQL Client by macintoshhelper · Pull Request #13 · btcpay-zcash/btcpayserver-zcash-plugin · GitHub

This expands on the 0conf support from the previously funded grant. Around half the work is already completed for the GraphQL port: multi-store account creation, invoice creation, address generation, 0conf and payment confirmation are working locally. A wallet agnostic backend makes adding zecd support relatively straight forward also.

I am currently working on the integrated testing architecture.

I would not like the work on zcash-wallet-rpc to go unused/wasted and the idea of the Zcash Merchant Wiki is to document how a merchant using the Monero RPC can add drop-in support for Zcash with zcash-wallet-rpc.

Example of the wallet backend agnostic C# interface:

// `zecd`/`zcash-wallet-rpc` RPC interface (WIP)
public async Task<WalletAddress> CreateAddressAsync(long accountIndex, string label, CancellationToken cancellationToken = default)
        {
            var response = await _walletRpcClient.SendCommandAsync<CreateAddressRequest, CreateAddressResponse>(
                "create_address",
                new CreateAddressRequest
                {
                    AccountIndex = accountIndex,
                    Label = label
                },
                cancellationToken);

            return new WalletAddress
            {
                Address = response.Address,
                AddressIndex = response.AddressIndex,
                UnifiedAddress = response.Address
            };
        }

// GraphQL interface
public async Task<WalletAddress> CreateAddressAsync(long accountIndex, string label, CancellationToken cancellationToken = default)
{
    var accountId = await ResolveGraphQlAccountIdAsync(accountIndex, cancellationToken);
    return await CreateOrGetAddressAsync(accountId, cancellationToken);
}

// Different class:
ReserveAddress = s => walletBackend.CreateAddressAsync(accountIndex, $"btcpay invoice #{s}"),

LLM disclaimer:

  • I am making manual use of Sonnet 5 prompts to aid with certain tasks.
  • GitHub Copilot agent with Sonnet 5 was used for creating an initial non-working prototype of the refactor
  • I am responsible for every line of code merged and thoroughly check and understand all code generated by LLMs.
4 Likes

@1337bytes at the most recent meeting, ZCG voted to approve this proposal. Congratulations!

To keep the community informed, ZCG requests that you provide monthly updates via the forum in this thread.

Please check your forum inbox for a direct message from FPF with important next steps, including a link to the Milestone Payment Request Form and your unique validation code for submitting payment requests.

1 Like

Hi, quick update:

I will be releasing an alpha preview release in the coming days. I have started work on milestone 2 and setup integration testing with Playwright using either a mock GraphQL server or a full zkool (with cashcow wallet) and regtest setup. These milestones are now complete:

Code on GitHub repo
Cashcow CheatMode extension for testing
CI integration testing for the BTCPay plugin with regtest

Regtest cheatmode testing allows for much faster testing, together with automated integrated testing to aid with agentic workflows.

2 Likes

Milestone 1 is now complete.

Alpha preview released for testing of multi-store BTCPay plugin with GraphQL support

Demo BTCPay store: Test

Source code (PR): Development branch by macintoshhelper · Pull Request #16 · btcpay-zcash/btcpayserver-zcash-plugin · GitHub

1.1.0 is in pre-release in the plugin store.

Installation Instructions (for testing)

Please use a fresh wallet and viewing key. Diversifier indexes start from 0, there is no migration pathway, every store will start fresh.

Server Settings > Policies > Plugins > Show plugins in pre-release

Plugins (top right button) > Installed Plugins > Upgrade (to 1.1.0)

zcash.yml Docker fragment (alpha version for testing)

services:
  zcash_walletd:
    restart: unless-stopped
    init: true
    image: 1337bytes/zkool-graphql:dev-amd64
    command:
      - --db-path
      - /data/zec-graphql.db
      - --coin
      - "0"
      - --lwd-url
      - https://zec.rocks:443
      - --bind-address
      - 0.0.0.0
      - --port
      - "8000"
      # The current BTCPay client does not send JWT credentials.
      # Keep this service on the private Compose network without published ports.
      - --allow-unauthenticated
      - --allow-unencrypted-database
    environment:
      HOME: /data
      RUST_LOG: info
    expose:
      - "8000"
    volumes:
      - zec_graphql_wallet:/data

  btcpayserver:
    environment:
      BTCPAY_ZEC_WALLET_BACKEND_TYPE: ZkoolGraphQL
      BTCPAY_ZEC_WALLET_GRAPHQL_URI: http://zcash_walletd:8000/graphql

volumes:
  # A separate volume preserves the old walletd database for migration/recovery.
  zec_graphql_wallet:

exclusive:
  - zcash-node
2 Likes

:warning:

1 Like