Overview

The Local Playground provides a suite of packages that, together, mock an account servicing entity that has deployed Rafiki. It exposes an SPSP endpoint, the Open Payments APIs with its required GNAP auth endpoints to request grants, a STREAM endpoint for receiving Interledger packets, and the Rafiki Admin app to view and manage each Rafiki instance.

This suite of packages includes:

Package name	Services
backend	SPSP Open Payments APIs GraphQL Admin APIs STREAM endpoint
auth	GNAP auth server
mock-account-servicing-entity	mocks an account servicing entity
frontend	Remix app to expose a UI for Rafiki admin management via interaction with the Backend Admin APIs

These packages depend on the following databases:

The Local Playground comes with containerized versions of the Rafiki packages and two pre-configured docker-compose files (Cloud Nine Wallet and Happy Life Bank) to start two mock account servicing entities with their respective Rafiki backend and auth servers. They automatically peer, and two to three user accounts are created on both of them.

This environment will set up a playground where you can use the GraphQL Admin APIs and the Open Payments APIs.

Note

The Mock ASE provided in this repository is intended solely for internal use and demonstration purposes. It is not designed to serve as a reference architecture. If you are looking for a reference implementation of an ASE, please refer to the Test Wallet.

Running the local environment

To spin up the Local Playground install the following software on your machine:

• A Rafiki local environment setup
• The Docker platform.
• An open-source API client Bruno

Setup

The local environment can be set up using either TigerBeetle or Postgres as the accounting database.

Using TigerBeetle

This option enables the primary instance (Cloud Nine Wallet) to utilize TigerBeetle for its accounting database. The secondary instance (Happy Life Bank) will always run Postgres as its accounting database.

To run the local environment with TigerBeetle, execute the following command from the root of the project:

Using TigerBeetle

pnpm localenv:compose up

Using Postgres

If you want the primary instance (Cloud Nine Wallet) to use Postgres as the accounting database instead of TigerBeetle, you must use the psql variant of the localenv:compose command as follows:

Using Postgres

pnpm localenv:compose:psql up

The local environment consists of a primary and secondary Rafiki instance, each with its docker-compose file (Cloud Nine Wallet, Happy Life Bank). The primary Cloud Nine Wallet docker-compose file (./cloud-nine-wallet/docker-compose.yml) includes the primary Rafiki backend and auth services, as well as the required data stores, which include TigerBeetle (if enabled), Redis, and Postgres. The primary instance contains all of the necessary components so that it can run independently.

The secondary Happy Life Bank docker-compose file (./happy-life-bank/docker-compose.yml) includes only the Rafiki services, not the data stores. It uses the data stores created by the primary Rafiki instance, so it can’t be run independently. The pnpm localenv:compose up command starts both the primary and secondary instances.

Environment components

The following components are made available via the Local Playground:

View full image

Mock account servicing entity 1 - Cloud Nine Wallet

Label	Component	URL
a	User Interface	http://localhost:3030
b	Backend Admin API	http://localhost:3001/graphql
c	Open Payments API	http://localhost:3000
d	Auth Admin API	http://localhost:3003/graphql
e	Open Payments Auth API	http://localhost:3006
f	Rafiki Admin UI	http://localhost:3010
g	Kratos API - disabled by default	http://localhost:4433

Mock account servicing entity 2 - Happy Life Bank

Label	Component	URL
h	User Interface	http://localhost:3031
i	Backend Admin API	http://localhost:4001/graphql
j	Open Payments API	http://localhost:4000
k	Auth Admin API	http://localhost:4003/graphql
l	Open Payments Auth API	http://localhost:4006
m	Rafiki Admin UI	http://localhost:4010
n	Kratos API - disabled by default	http://localhost:4432

Mail Slurper

Label	Component	URL
o	Mail UI - disabled by default	http://localhost:4436

Database

Component	URL
Postgres Server	http://localhost:5432

Rafiki Admin

Manage and view information about the Rafiki instance(s) through the Rafiki Admin application. Rafiki Admin is a Remix app for querying info and executing mutations against the Rafiki Backend Admin API.

• Cloud Nine Wallet - http://localhost:3010
• Happy Life Bank - http://localhost:4010

We have secured access to Rafiki Admin using Ory Kratos; however, in our local playground setup we’ve chosen to disable user authentication for easier development and testing interactions.

Enabling Rafiki Admin authentication locally

If you’d like to enable authentication locally you can run pnpm localenv:compose:adminauth up

Separate registrations/users are required for each mock ASE’s Admin app as the ASEs are designed to run as separate mock entities. Visit the Rafiki Admin user guide to learn how to invite and remove users via provided scripts.

After you’ve registered, you can come back to your Rafiki Admin account by navigating to localhost:3010 (Cloud Nine Wallet) or localhost:4010 (Happy Life Bank) and logging in.

Follow these steps to reset a user’s Rafiki Admin password.

1. Select the forgot password link and enter an email for a registered user.
2. Open Mail Slurper to access the recovery link for the account.

Exploring Accounts on Cloud Nine Wallet

Navigate to localhost:3030 to view the accounts on Cloud Nine Wallet.

Note

The accounts for Happy Life Bank can be found on localhost:3031.

Select an account name to view a list of transactions.

Debugging

Debuggers for the services are exposed on the following ports:

Services	IP and Port
Cloud Nine Backend	127.0.0.1:9229
Cloud Nine Auth	127.0.0.1.9230
Happy Life Bank Backend	127.0.0.1:9231
Happy Life Bank Auth	127.0.0.1:9232

Debugging with a Chromium browser:

1. Go to chrome://inspect
2. Select Configure and add the IP addresses and ports detailed above
3. Start the docker containers
4. Select Inspect on the service you want to debug to open the Chromium debugger.

You can either trigger the debugger by adding debugger statements in the code and restarting the Docker containers or by adding breakpoints directly to the Chromium debugger after starting the Docker containers.

Debugging with VS Code:

To debug with VS Code, add this configuration to your .vscode/launch.json:

{
    "name": "Attach to docker (cloud-nine-backend)",
    "type": "node",
    "request": "attach",
    "port": 9229,
    "address": "localhost",
    "localRoot": "${workspaceFolder}",
    "remoteRoot": "/home/rafiki/",
    "restart": true
},

The localRoot variable will depend on the location of the launch.json file relative to Rafiki’s root directory.

For more ways to connect debuggers, refer to the Node JS docs for debugging.

Shutting down

To shut down your local instance, run the following commands:

# tear down
pnpm localenv:compose down

# tear down and delete database volumes
pnpm localenv:compose down --volumes

# tear down, delete database volumes and remove images
pnpm localenv:compose down --volumes --rmi all

Commands

The following are the most commonly used commands:

Description	Command
Show all merged config (with TigerBeetle)	pnpm localenv:compose config
Start (with TigerBeetle)	pnpm localenv:compose up
Start (with TigerBeetle) detached	pnpm localenv:compose up -d
Down (with TigerBeetle)	pnpm localenv:compose down
Down and kill volumes (with TigerBeetle)	pnpm localenv:compose down --volumes
Down, kill volumes (with TigerBeetle) and images	pnpm localenv:compose down --volumes --rmi all
Show all merged config (with Postgres)	pnpm localenv:compose:psql config
Build all the containers (with TigerBeetle)	pnpm localenv:compose build
Start (with Postgres)	pnpm localenv:compose:psql up
Start (with Postgres) detached	pnpm localenv:compose:psql up -d
Down (with Postgres)	pnpm localenv:compose:psql down
Down (with Postgres) and kill volumes	pnpm localenv:compose:psql down --volumes
Build all the containers (with Postgres)	pnpm localenv:compose:psql build
Start with local admin auth enabled (this is disabled by default)	pnpm localenv:compose:adminauth up

Enabling TigerBeetle

When enabled, TigerBeetle is only used by the primary instance (Cloud Nine Wallet). The secondary instance (Happy Life Bank) will always run Postgres as its accounting database.

Interacting with the Local Playground

Bruno & Open Payments APIs

The Open Payments APIs can be interacted with using the Bruno collection (resource server endpoints and auth server endpoints). To interact with the Open Payments APIs using Bruno, you must:

1. Load the collection into Bruno by selecting Open Collection.
2. Navigate to /rafiki/bruno/collections/Rafiki on your machine and select Open.
3. Furthermore, you need to either load the Local Environment or the Remote Test Network Environment.

Troubleshooting Bruno errors

If you receive the error below while running the Bruno collection, try switching from Safe Mode to Developer Mode

Error invoking remote method `send-http-request`: Error : Error: Cannot find module crypto

The Examples folder in the Bruno collection includes an Open Payments example that can be executed in the following sequence:

1. Requests the sender’s wallet address
2. Requests the receiver’s wallet address
3. Requests a grant to create an incoming payment on the receiver’s account
4. Creates an incoming payment on receiver’s account
5. Requests a grant to create and read a quote on the sender’s account
6. Creates a quote on the sender’s account
7. Requests a grant to create and read an outgoing payment on the sender’s account

Note

You have to go through an interaction flow by selecting the redirect link in the grant request’s response. More information about the interaction flow can be found here.

8. Continues the grant request
9. Creates an outgoing payment on the sender’s account
10. Fetches the outgoing payment on the sender’s account

Admin APIs

In addition to using Rafiki Admin to interact with the Admin APIs, you can also use the Apollo Explorer on localhost:3001/graphql and localhost:4001/graphql for Cloud Nine Wallet and Happy Life Bank, respectively, and via the Bruno collection. The Bruno collection is configured to use the local environment’s default endpoints.

SPSP

Every wallet address also serves as an SPSP endpoint. A GET request with an Accept header application/spsp4+json will return an SPSP response with STREAM connection details. The following example uses http://localhost:3000/accounts/gfranklin as the SPSP endpoint.

GET http://localhost:3000/accounts/gfranklin HTTP/1.1
Host:backend
Accept:application/spsp4+json


HTTP/1.1 200 OK
Connection:keep-alive
Content-Length:220
Content-Type:application/spsp4+json
Date:Thu, 23 Feb 2023 13:07:24 GMT
Keep-Alive:timeout=5


{
  "destination_account": "test.rafiki.viXmy1OVHgvmQakNjX1C6kQM",
  "receipts_enabled": false,
  "shared_secret": "Rz_vudcg13EPs8ehL2drvZFJS1LJ4Y3EltOI60-lQ78"
}

Known issues

TigerBeetle container exists with code 137

There is a known issue when running TigerBeetle in Docker. The container exits without logs and simply shows error code 137. To fix this, increase the Docker memory limit. If you run the local Docker playground on a Windows machine via the Windows Subsystem for Linux (WSL), you can increase the memory limit by configuring your .wslconfig file.