MAGIC Grants Campaign Site

Creating a New Donation Campaign

The core of a donation campaign lives in /docs/<fund>/projects.

Create a new .md file in the project folder for the Fund that you are interested in. The name of the .md file will be the end part of the public YRL.

You will need to make a new branch to propose a change in a pull request.

In the new .md file, please the following at the top:

fund: fund_name (required, eg: firo, monero, general)
title: 'String' (required)
summary: 'String' (required)
nym: 'String' (required, the author)
coverImage: '' (optional but recommended)
website: 'String' (optional, link for the title text)
socialLinks:
  - 'string' (optional, add more list items for multiple)
date: 'YYYY-MM_DD' (required)
goal: Number (required, in USD)

When merged, this will open a new donation campaign that is set to require funding.

Adding a Cover Image

The cover image (coverImage) should be placed in /public/img/project/. For the coverImage value, use /img/project/<image file name>, eg /img/project/firo-curve-trees.png.

Development

Requirements

• Docker
• Docker Compose
• NodeJS >=20

Running containers

First, install the application's dependencies and then run the containers:

$ npm i

$ docker-compose up -d

The app will be available at http://localhost:3000.

Configuration

Create a .env file as a copy of .env.example and set the values for the empty variables.

Setting up Keycloak

1. Open up http://localhost:8080 in your browser, then login using admin for both username and password;

2. Open the dropdown menu on the top left corner of the screen (where it says Keycloak) and click Create realm;

3. Upload the realm-export.json file from this repo, name the realm magic and click Create;

4. Once the realm is created, go to Clients -> Credentials, and under Client Secret, click Regenerate. Copy the secret and add it to the KEYCLOAK_CLIENT_SECRET environment variable in your .env file.

Setting up BTCPayServer

1. Open up http://localhost:49392 in your browser and create an account;

2. Once logged in, open the XMR Wallet page and upload a view-only wallet file, you can get one from Feather Wallet;

3. In the Webhooks tab, create a new webhook by setting the Payload URL to http://campaign-site:3000/api/btcpay/webhook, copy the secret and add it to the BTCPAY_WEBHOOK_SECRET environment variable in your .env file, and finally click Add webhook.

4. Create a new API key at Account -> Manage Account -> API Keys, you'll need the following permissions: View invoices, Create an invoice and View your stores. Then copy the API key and add it to the BTCPAY_API_KEY environment variable in your .env file.

Setting up Stripe

1. Open up the Stripe Dashboard in your browser;

2. Create a new account in test mode;

3. Go to Developers -> API keys, and get a secret key, add it to the STRIPE_MONERO_SECRET_KEY environment variable in your .env file;

4. Go to Developers -> Webhooks, and add a new webhook endpoint. Add <Your app public address>/api/stripe/monero-webhook to the URL field replacing <Your app public address> with your app's public address, then add the secret to the STRIPE_MONERO_WEBHOOK_SECRET environment variable in your .env file. To expose the app to the internet so Stripe can reach the webhook endpoint, you can use tunneling services like Visual Studio Code's built-in port-forwarding feature or Ngrok.

This makes you able to test Stripe donations in the Monero fund, which should be enough for development. You can add random values to the other Stripe environment variables to bypass validation.

You are now all set up to start developing!

Funding required endpoint

Endpoint: GET /api/funding-required

Request query parameters

Parameter	Required	Default	Accepted values	Description
fund	No	-	monero firo privacyguides general	Filters projects by fund.
asset	No	-	BTC XMR USD	Only return project amounts and address for a specific asset. Specifying this parameter changes the response JSON schema as shown below.
project_status	No	NOT_FUNDED	NOT_FUNDED FUNDED ANY	Filters projects by status.

Response body (asset parameter not specified)

[
    {
        title: string
        fund: 'monero' | 'firo' | 'privacyguides' | 'general'
        date: string // YYYY-MM-DD
        author: string
        url: string
        is_funded: boolean
        raised_amount_percent: number
        contributions: number
        target_amount_btc: number
        target_amount_xmr: number
        target_amount_usd: number
        remaining_amount_btc: number
        remaining_amount_xmr: number
        remaining_amount_usd: number
        address_btc: string | null
        address_xmr: string | null
    }
]

Response body (asset parameter specified)

[
    {
        title: string
        fund: 'monero' | 'firo' | 'privacyguides' | 'general'
        date: string // YYYY-MM-DD
        author: string
        url: string
        is_funded: boolean
        raised_amount_percent: number
        contributions: number
        asset: 'BTC' | 'XMR' | 'USD'
        target_amount: number
        remaining_amount: number
        address: string | null
    }
]

Infrastructure

This repository consists of several relayed deployments:

• The campaign website, donate.magicgrants.org
• BTCPay Server, btcpay.magicgrants.org
  • Monero daemon
  • View-only Monero wallet
  • Bitcoin daemon
  • View-only Bitcoin wallet
• Keycloak, keycloak.magicgrants.org

Separate repositories are used for:

• Auto-forwarding Bitcoin and Monero to Kraken, then auto-converting to USD: https://github.com/MAGICGrants/autoforward-autoconvert
• Perks management/administration: https://github.com/MAGICGrants/strapi

Contributing

Pull requests welcome! Thanks for supporting MAGIC Grants.

License

Thanks to Open Sats for their initial version of this website, which has been modified significantly. Thanks to BTCPay Server for Bitcoin and Monero payment processing.

MIT