Hong₿ao Bitcoin

🌐 Live Demo · 💬 Discussions · 🤝 Contributing

Hong₿ao is an open-source browser-based Bitcoin paper wallet generator. It is specifically designed for traditional red envelopes (红包, hóngbāo). Perfect for introducing friends and family to Bitcoin during Chinese New Year, weddings or any gift-giving occasion.

🚀 Features

• AI Design: Create Bitcoin paper wallets optimized for red envelopes size
• Offline mode: All the keys are generated in the browser using bitcoinlib-js
• Top up: Top-up the paper wallets with € via Mt pelerin or public address via any wallet (Ledger, Trezor, Sparrow etc)
• Verify Balance / Transfer funds: Direcly from the Scan button on the homepage

⚡ Tech Stack

Ruby 3.2	Rails 8	SQLite	Tailwind
Hotwire	mise	Playwright	RSpec

Key Dependencies

• 🔒 bitcoinjs-lib - Bitcoin JavaScript library
• 💳 Mt Pelerin - Fiat to crypto integration
• 🎨 ChatGPT (gpt-image-1) - AI image generation
• 🧪 Playwright - E2E testing
• 📦 SolidQueue - Background jobs

🛠️ Quick Start

Prerequisites

• VS Code or Cursor (recommended)
• mise - Dev env manager (like docker without the pain)
• libvips - Image processing library

  # macOS
  brew install vips
  
  # Debian/Ubuntu
  sudo apt-get update && sudo apt install libvips-dev

Install

1. Install mise:

# macOS with Homebrew
brew install mise

# Linux/macOS without Homebrew
curl https://mise.run | sh

2. Activate mise in your shell:

# For bash
echo 'eval "$(~/.local/bin/mise activate bash)"' >> ~/.bashrc

# Refresh
source ~/.bashrc

3. Clone and setup the project:

git clone https://github.com/sbounmy/hongbao.git
git submodule update --init --recursive
cd hongbao
# Install Ruby and Node.js from mise.toml
mise install

# Install dependencies
bundle install
yarn install

# Copy environment configuration
cp .env.example .env

# Set up credentials (choose one):
# Option 1: Request master.key from Stephane
# Option 2: Create your own from credentials.yml.example:
EDITOR="nano --wait" bin/rails credentials:edit

# Setup database
bin/rails db:setup

# Start the development server
bin/dev

3. Setup the app:

# Copy environment configuration
cp .env.example .env

# Set up credentials (choose one):
# Option 1: Request master.key from Stephane
# Option 2: Create your own from credentials.yml.example:
EDITOR="nano --wait" bin/rails credentials:edit

# Seed the database
bin/rails db:seed

# Start the development server
bin/dev

4. Visit http://localhost:3001 to see your local instance!

💻 Development

Local Development

bin/dev  # Start the development server

Remote Development

When working with webhooks locally we recommend to create a tunnel to your localhost:

# MacOS
docker brew install cloudflared &&
sudo cloudflared service install {token}


# Debian / linux
curl -L --output cloudflared.deb https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64.deb &&
sudo dpkg -i cloudflared.deb &&
sudo cloudflared service install {token}

📚 Cloudflare Tunnel Documentation

🧪 Testing

We use RSpec for model,controller, service testing and Playwright for frontend testing.

RSpec Tests

bin/rspec spec/

Playwright E2E Tests

To run the end-to-end test suite, use the bin/e2e script:

# Run all tests with 4 parallel workers (default)
bin/e2e

# Run a specific test file
bin/e2e e2e/playwright/e2e/visual_editor.spec.js

# Run all tests with a specific number of parallel workers
bin/e2e --parallel[8]

# Combine both options
bin/e2e --parallel[2] e2e/playwright/e2e/visual_editor.spec.js

For debugging, you can still use the standard Playwright commands:

npx playwright test --ui # Run tests with UI

If you use VSCode / Cursor you can install Playwright Test for VSCode extension

Then you can

• Select the Testing Tab (1)
• Run test from the testing panel (2)
• Run test from the source code (3)
• Automatically run test when changes are detected (4)

🔄 Recent Updates

TODO

💬 FAQ

How do I test emails in development?

Emails are caught by Letter Opener:

• Auto-preview in new tab
• Dashboard at http://localhost:3001/letter_opener

How do I add JavaScript dependencies?

Use ImportMaps with JSPM:

1. Visit JSPM Generator
2. Search and select package
3. Copy import URL
4. Add to config/importmap.rb

PDF issues in Chrome/Arc?

• Issue: "No enabled plugin supports this MIME type"
• Only affects localhost
• Solution: Use Safari for local PDF testing
• Track Issue #39

StripeCLI Expired API Key provided

• open ~/.config/stripe/config.toml https://docs.stripe.com/stripe-cli/keys#where-keys-are-stored
• replace test_mode_api_key by stripe.secret_key in rails credentials:show

## 🤝 Contributing

We love your input! Check out our Contributing Guidelines for ways to get started.

How to Contribute

Core maintainer

1. Take an issue
2. Create a branch from issue
3. Create the PR

Others

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.