4chainstudio/spv-wallet-mobile-backend repository overview

⁠SPV Wallet Mobile Backend

This project is a backend service that facilitates communication with an SPV wallet system (Bitcoin SV SPV Wallet) and handles user authentication, wallet management, notifications, and SMS-based flows for mobile wallet applications.

⁠Features

• OAuth2 Authentication: Implements JWT-based authentication and session management using the ory/fosite library. Supports OAuth2 flows, including authorization code and refresh token grants, as well as the PKCE flow for enhanced security.
• SMS-Based User Authentication: Provides SMS-based user signup and login, allowing for two-step verification via configurable SMS providers.
• SPV Wallet Integration: Connects to the SPV Wallet for user management. Manages xpubs and paymails, registers users, and verifies their existence. Also supports real-time event handling through a configurable webhook system for wallet events such as transactions.
• Real-Time Notifications: The notification service processes webhook events from the SPV wallet and deliver real-time updates on wallet activity. Also notify about steps in contact confirmation process.
• Metrics Collection: Tracks HTTP request counts, latencies, and other performance data using Prometheus-based metrics. Metrics endpoints are available to expose data for monitoring.
• RESTful API: Offers a comprehensive set of APIs for user management, status checks, and other functionalities.
• Logging: Uses zerolog for structured and efficient logging, making it suitable for scalable log management in production environments.

⁠Getting Started

There are three ways to run the project locally:

1. using Go directly

go run ./cmd/main.go -C ./config.yaml 

1. using the Taskfile:

task run

1. using the start.sh script:

./start.sh

Authorization and authentication are handled using OAuth2 and JWT tokens, with support for SMS-based sign-up and sign-in flows

⁠Testing and Simulation with AUTH CLI Tool

To simplify testing and to simulate the authentication flow with the SPV Wallet Mobile Backend, you can use the AUTH CLI Tool. This tool allows you to test the OAuth2 authentication and SMS-based sign-up/sign-in flows by interacting directly with the backend. To sign in or sign up users through the backend using the AUTH CLI Tool, follow the examples in the CLI documentation⁠.

⁠Configurations

⁠Config Variables

The configuration for the SPV Wallet Mobile Backend can be customized in several ways, with overrides prioritized in the following order:

1. Environment Variables: Environment variables prefixed with WALLETMOBILE_ are used to override specific configuration values
2. Config File: The configuration file provides default values for all settings. Create config.yml file and replace variables from example.config.yaml to override them

⁠Overriding Configuration with Environment Variables

All environment variables must be prefixed with WALLETMOBILE_. The corresponding configuration key is transformed to uppercase and separated by underscores (_), following this pattern.

For example, to override the database host, you would set:

export WALLETMOBILE_DB_HOST=custom-db-host

This ensures the environment variable applies specifically to this application and prevents conflicts with other running services.

⁠Using the Config File

The most flexible and detailed way to configure the application is by using the YAML config file. You can see a complete list of configurable settings in the example.config.yaml⁠. To use the config file, create a config.yaml file in the root directory of the project and customize the settings as needed.

At runtime, the application first reads the config file, then applies any overrides from environment variables, and finally, command-line flags (if available) will take the highest precedence.

⁠Key settings

Here are the examples of key settings that can be configured:

• Cache engine, you can choose between freecache and redis
• SMS provider, by default it is set to console which means that the SMS code will be printed in the logs, but it is possible to use Vonage API
• Notification provider, as for SMS provider, it is possible to use console for testing and debugging or Firebase Cloud Messaging for push notifications.

To use external services like Vonage or Firebase Cloud Messaging you need to create an account there and provide the API keys in the config file.

Example of the config.yaml file:

cache:
  engine: "freecache" # or "redis"
  redis: # used only if cache engine is set to "redis"
    url: "localhost:6379"
    password: ""
    db: 0
  freecache: # used only if cache engine is set to "freecache"
    size: 104857600
cloud_message: # settings for notifications
  provider: "console"
  service_account: ".local/service-account.json"
sms:
   provider: "console" # or "vonage"
   vonage: # used only if sms provider is set to "vonage"
      api_key: "VONAGE_API_KEY"
      api_secret: "VONAGE_API_SECRET"
      type: "unicode"
      client_ref: "vonage-go-sdk"
      reports: true
      from: "spv-wallet-mobile-backend"

⁠Fast run

1. Generate RSA Private Key. RSA keys are required to sign JWT tokens. Generate the RSA private key by running:

   ./generate_rsa_private_key.sh
   

   Copy

2. Run SPV Wallet. You can use the provided start.sh script to set up the environment and start the application with Docker Compose. This script is also running SPV Wallet mobile backend from latest docker container

   ./start.sh
   

   Copy

3. If you want to run spv-wallet-mobile-backend with local changes you need to close the running container and run the following command:

   go run ./cmd/main.go -C ./config.yaml 
   

   Copy

4. Build the AUTH CLI Tool

   go build -o authcli
   

   Copy

1. Generate JWT tokens for the user

   Generate keys for new user

   go run ./authcli/examples/generate_keys.go
   

   Copy

   Example response:

   Private key:  xprv9s21ZrQH143K4TnTobcmWpPh46gQmbb6kW3X878kQzLYBXWA5xXDEdQR78f3KmqkqB1FgNquVfdiBDeeAsH4V5ggaPVArcVspLgThi2TRQf
   Public key:  xpub661MyMwAqRbcGwrvud9msxLRc8WuB4Jx7iy7vVYMyKsX4KqJdVqTnRitxQ6G7wRDpQ9AUtKNMVYrpn7ieAQjGrf1Qx6pT8AwS6ghaapsp4K
   

   Copy

   Sign up user

   go run main.go up --xpriv xprv9s21ZrQH143K4TnTobcmWpPh46gQmbb6kW3X878kQzLYBXWA5xXDEdQR78f3KmqkqB1FgNquVfdiBDeeAsH4V5ggaPVArcVspLgThi2TRQf --xpub xpub661MyMwAqRbcGwrvud9msxLRc8WuB4Jx7iy7vVYMyKsX4KqJdVqTnRitxQ6G7wRDpQ9AUtKNMVYrpn7ieAQjGrf1Qx6pT8AwS6ghaapsp4K --phone example-number
   

   Copy

   Example response:

   Starting server on port 5173...
   2025/01/24 12:37:40 Server started on port 5173
   Server started on port 5173
   sign-up ...
   Phone submitted successfully. Check your SMS.
   Waiting for SMS code...
   ? Enter SMS code: 3178
   ? Enter the alias (username): test
   Sign-Up flow completed successfully!
   

   Copy

   Sign in user

   go run main.go in --xpriv xprv9s21ZrQH143K4TnTobcmWpPh46gQmbb6kW3X878kQzLYBXWA5xXDEdQR78f3KmqkqB1FgNquVfdiBDeeAsH4V5ggaPVArcVspLgThi2TRQf --xpub xpub661MyMwAqRbcGwrvud9msxLRc8WuB4Jx7iy7vVYMyKsX4KqJdVqTnRitxQ6G7wRDpQ9AUtKNMVYrpn7ieAQjGrf1Qx6pT8AwS6ghaapsp4K
   

   Copy

   Example response:

   Starting server on port 5173...
   2025/01/24 12:45:31 Server started on port 5173
   Server started on port 5173
   sign-in ...
   Access Token: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOlsiaHR0cHM6Ly9sb2NhbGhvc3Q6ODI4MiJdLCJleHAiOjE3Mzc3MzExMzMsImlhdCI6MTczNzcxOTEzMywiaXNzIjoic3B2LXdhbGxldC1tb2JpbGUtYmFja2VuZCIsImp0aSI6IjFlOGQzMzllLTcxMzMtNGMzNS1hYzU5LTg4Mjg2OGM2ZDQ3MyIsInNjcCI6WyJtb2JpbGUtd2FsbGV0Il0sInN1YiI6InhwdWI2NjFNeU13QXFSYmNHd3J2dWQ5bXN4TFJjOFd1QjRKeDdpeTd2VllNeUtzWDRLcUpkVnFUblJpdHhRNkc3d1JEcFE5QVV0S05NVllycG43aWVBUWpHcmYxUXg2cFQ4QXdTNmdoYWFwc3A0SyJ9.ZASh5o2irFxDERc3tJPJRRL0qlDJcDZMhKMp_0NZ3SrZgVxi1kFMx5WEfRS1Wtqgp-ZIxCJXz1obeLOqPPPLIMbiVJQTioOHj6jhSpQXa91in71KRpeG6PmghsofX6--wcAPKYFUbPVyKSmX63Bqk0KOIGQGnRw5uUunJugllM9dlZuyheROUGBk8zRLvte6NMPzwcGDAgmGY3-5Bg6gXV8L3abpWidkU0vbXK-rezBRagdvj-1k_Tch1cpZ7BvrG7XhhGibOIpBy2ZIN_4aPQE5eAoulnEJeSXWwMvMCwI2-0YstBkKnizW05F_4cK9sH5pBV5MVvQYBrhlQ2IJidEIXaPkzoJfBRVeR5sDBoSSJ7bDXcMa7E8KN2IoxBqIGA844MFOY0YAtS87K7U5bSSjQ5XIr0Hfky_aNHnUHHmjaiJlr8fnea6aUqKFudDRlzD8Fg_98V9M8jh36IjKtFBBZ587Cqe4d3je2-uZo_ZObtTFTt5e0mup3CUBdsr5t6feOcts77BuIJBWJWol5Z4N29ngOLu_YjK_V2ZgSuddUqSNkfQWE5h6jaFFne4GYztb1ge5DnXgxS-EIdIJjIZYZloThl-0ilepZefMUNdEQftTNsyyvzvYRtTflQfXflrWrOEVfJb96JHVm6YhJsE6oB3WlI5p3wZYthj8yp0
   Refresh Token: ory_rt_ZLiVyuzES85wUmI9GqFC8KAcPXihasbqn7rjO50sLKI.nce_QsGrQh-nTjOCHlPdT2-K8GIg4exgLqGDCscLuuY
   Sign-In flow completed successfully!
   
   export SPVWALLET_BACKEND_MOBILE_AUTH_TOKEN=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOlsiaHR0cHM6Ly9sb2NhbGhvc3Q6ODI4MiJdLCJleHAiOjE3Mzc3MzExMzMsImlhdCI6MTczNzcxOTEzMywiaXNzIjoic3B2LXdhbGxldC1tb2JpbGUtYmFja2VuZCIsImp0aSI6IjFlOGQzMzllLTcxMzMtNGMzNS1hYzU5LTg4Mjg2OGM2ZDQ3MyIsInNjcCI6WyJtb2JpbGUtd2FsbGV0Il0sInN1YiI6InhwdWI2NjFNeU13QXFSYmNHd3J2dWQ5bXN4TFJjOFd1QjRKeDdpeTd2VllNeUtzWDRLcUpkVnFUblJpdHhRNkc3d1JEcFE5QVV0S05NVllycG43aWVBUWpHcmYxUXg2cFQ4QXdTNmdoYWFwc3A0SyJ9.ZASh5o2irFxDERc3tJPJRRL0qlDJcDZMhKMp_0NZ3SrZgVxi1kFMx5WEfRS1Wtqgp-ZIxCJXz1obeLOqPPPLIMbiVJQTioOHj6jhSpQXa91in71KRpeG6PmghsofX6--wcAPKYFUbPVyKSmX63Bqk0KOIGQGnRw5uUunJugllM9dlZuyheROUGBk8zRLvte6NMPzwcGDAgmGY3-5Bg6gXV8L3abpWidkU0vbXK-rezBRagdvj-1k_Tch1cpZ7BvrG7XhhGibOIpBy2ZIN_4aPQE5eAoulnEJeSXWwMvMCwI2-0YstBkKnizW05F_4cK9sH5pBV5MVvQYBrhlQ2IJidEIXaPkzoJfBRVeR5sDBoSSJ7bDXcMa7E8KN2IoxBqIGA844MFOY0YAtS87K7U5bSSjQ5XIr0Hfky_aNHnUHHmjaiJlr8fnea6aUqKFudDRlzD8Fg_98V9M8jh36IjKtFBBZ587Cqe4d3je2-uZo_ZObtTFTt5e0mup3CUBdsr5t6feOcts77BuIJBWJWol5Z4N29ngOLu_YjK_V2ZgSuddUqSNkfQWE5h6jaFFne4GYztb1ge5DnXgxS-EIdIJjIZYZloThl-0ilepZefMUNdEQftTNsyyvzvYRtTflQfXflrWrOEVfJb96JHVm6YhJsE6oB3WlI5p3wZYthj8yp0
   

   Copy

1. See endpoints in swagger

   http://localhost:8080/swagger/index.html
   

   Copy

2. Test endpoints with JWT token

   curl -X GET http://localhost:8280/api/v1/user \
     -H "Authorization: Bearer "
   

   Copy