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 Rafiki 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

Run the following commands from the root of the project.

## If you have spun up the environment before, first tear down and remove volumes!

pnpm localenv:compose down --volumes

## Otherwise start the local environment
## start the local environment

pnpm localenv:compose up

If you want to use Postgres as the accounting database instead of TigerBeetle, you must use the psql variant of the localenv:compose commands as follows:

## If you have spun up the environment before, first tear down and remove volumes!
## Otherwise start the local environment
pnpm localenv:compose:psql down --volumes


// start the local environment
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. Click 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.

Click 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. Click Configure and add the IP addresses and ports detailed above
3. Start the docker containers
4. Click 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:

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

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 clicking “Open Collection”
2. navigating to /rafiki/bruno/collections/Rafiki on your machine and clicking “Open”
3. Furthermore, you need to either load the Local Environment or the Remote Test Network Environment.

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 clicking on the redirect link in the grant request 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.

http GET http://localhost:3000/accounts/gfranklin 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.viXmy1OVHgvmQakNjX1C6kQMri92DzHeISEv-5VzTDuFhrpsrkDzsq5OO9Lfa9yed0L2RJGC9hA_IX-zztTtTZ87shCYvsQ",
"receipts_enabled":false,
"shared_secret":"Rz_vudcg13EPs8ehL2drvZFJS1LJ4Y3EltOI60-lQ78"
}

Known issues

No data in the mock account servicing entities

It is possible that upon starting or restarting the local playground, you may run into an issue where there are no accounts and wallet addresses in the mock account service entities’ pages on http://localhost:3030 and http://localhost:3031, respectively. You can only seed the initial account data against an empty database. To seed the database with this initial data, clear the existing volumes and restart the docker containers by issuing the following commands:

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.