docs: deployment (#1162)

* docs: deployment, localenv * docs: add links to docker-compose yaml files * feat: rename fynbos -> Cloud Nine Wallet and local-bank -> Happy Life Bank * fix(localenv): tb docker-compose * chore(localenv): add image source * fix: formatting * docs: env variables * docs: env variables * docs: add prices/rates to integration * docs: add missing env variable desciptions * docs: placeholder for describing prod env * docs: reference asset code * docs: review comments * chore: remove unneccessary docker-compose files * feat(localenv): rename ilp addresses * fix(localenv): rename databases * fix(localenv): docker-compose location for postgres localenv * feat(localenv): organize into directories * feat(localenv): rename services and use hostname key * style(localenv): rename commands * fix: psql start and stop commands * docs: update webhook events * fix: docs table * docs: fix link Co-authored-by: Brandon Wilson <[email protected]> * fix(localenv): hostname networking issue --------- Co-authored-by: Brandon Wilson <[email protected]>
interledger · Mar 7, 2023 · c3dbb42 · c3dbb42
1 parent 5ade950
commit c3dbb42
Show file tree

Hide file tree

Showing 29 changed files with 437 additions and 493 deletions.
diff --git a/docs/deployment.md b/docs/deployment.md
diff --git a/docs/glossary.md b/docs/glossary.md
@@ -37,6 +37,14 @@ A Peer is a counterparty that a given party transacts with. Within the [Interled
 
 The Simple Payments Setup Protocol is a basic protocol for exchanging payment information between payee and payer to facilitate payment over Interledger. For more details, see the [SPSP specification](https://interledger.org/rfcs/0009-simple-payment-setup-protocol).
 
+## STREAM
+
+STREAM is a multiplexed Interledger Transport Protocol that provides for sending multiple “streams” of money and data between two parties using ILP. For more details, see the [STREAM specification](https://interledger.org/rfcs/0029-stream/).
+
 ## Tigerbeetle
 
 TigerBeetle is a distributed financial accounting database designed for mission critical safety and performance. For more information, see the [official website](https://tigerbeetle.com/).
+
+## Web Monetization
+
+Web Monetization is a JavaScript browser API that allows the creation of a payment stream from the user agent to the website. For more details, see the [Web Monetization Website](https://webmonetization.org/).
diff --git a/docs/img/map-accounts.png b/docs/img/map-accounts.png
diff --git a/docs/img/map-transactions.png b/docs/img/map-transactions.png
diff --git a/docs/integration.md b/docs/integration.md
@@ -4,38 +4,56 @@
 
 Account Servicing Entities provide and maintain payment accounts. In order to make these accounts Interledger-enabled via Rafiki, they need to provide the following endpoints and services.
 
-## Quotes / Fees
+## Quotes / Rates and Fees
 
 Every Interledger payment is preceded with a quote that estimates the costs for transfering value from A to B. The Account Servicing Entity may charge fees on top of that for facilitating that transfer. How they structure those fees is completely up to the Account Servicing Entity.
 
-The Account Servicing Entity is required to provide an endpoint that is accessible to the Rafiki backend. It accepts a `POST` request with
+### Rates (Prices)
+
+For the quoting to be successful, Rafiki needs to be provided with the current exchange rate by the Account Servicing Entity. The Account Servicing Entity needs to expose an endpoint that accepts a `GET` requests and responds as follows.
+
+#### Response Body
+
+| Variable Name        | Type   | Description                                                                                            |
+| -------------------- | ------ | ------------------------------------------------------------------------------------------------------ |
+| `base`               | String | asset code represented as [ISO 4217 currency code](https://en.wikipedia.org/wiki/ISO_4217), e.g. `USD` |
+| `rates`              | Object | Object containing `<asset_code : exchange_rate>` pairs, e.g. `{EUR: 1.1602}`                           |
+| `rates.<asset_code>` | Number | exchange rate given `base` and `<asset_code>`                                                          |
+
+The response status code for a successful request is a `200`. The `mock-account-provider` includes a [minimalistic example](../packages/mock-account-provider/app/routes/prices.ts).
+
+The `backend` package requires an environment variable called `PRICES_URL` which MUST specify the URL of this endpoint.
+
+### Fees
+
+If the Account Servicing Entity decides to add sending fees, it is required to provide an endpoint that is accessible to the Rafiki backend. It accepts a `POST` request with
 
 #### Request Body
 
-| Variable Name    | Type                                     | Description                                 |
-| ---------------- | ---------------------------------------- | ------------------------------------------- |
-| id               | string                                   | Interledger quote id                        |
-| paymentType      | enum: `'FixedSend'` \| `'FixedDelivery'` | fixed-send or fixed-receive payment         |
-| paymentPointerId | string                                   | id of sending payment pointer               |
-| receiver         | string                                   | receiving payment pointer                   |
-| sendAmount       | [Amount](#amount)                        | defined or quoted send amount               |
-| receiveAmount    | [Amount](#amount)                        | defined or quoted receive amount            |
-| createdAt        | string                                   | creation date and time of Interledger quote |
-| expiresAt        | string                                   | expiry date and time of Interledger quote   |
+| Variable Name      | Type                                     | Description                                 |
+| ------------------ | ---------------------------------------- | ------------------------------------------- |
+| `id`               | String                                   | Interledger quote id                        |
+| `paymentType`      | Enum: `'FixedSend'` \| `'FixedDelivery'` | fixed-send or fixed-receive payment         |
+| `paymentPointerId` | String                                   | id of sending payment pointer               |
+| `receiver`         | String                                   | receiving payment pointer                   |
+| `sendAmount`       | [Amount](#amount)                        | defined or quoted send amount               |
+| `receiveAmount`    | [Amount](#amount)                        | defined or quoted receive amount            |
+| `createdAt`        | String                                   | creation date and time of Interledger quote |
+| `expiresAt`        | String                                   | expiry date and time of Interledger quote   |
 
 #### Amount
 
 (The example amount is $42.42.)
 
 | Variable Name | Type                       | Description                                                                                               |
 | ------------- | -------------------------- | --------------------------------------------------------------------------------------------------------- |
-| value         | string // number // bigint | e.g. `"4242"` or `4242`                                                                                   |
-| assetCode     | string                     | [ISO 4217 currency code](https://en.wikipedia.org/wiki/ISO_4217), e.g. `USD`                              |
-| assetScale    | number                     | difference in orders of magnitude between the standard unit and a corresponding fractional unit, e.g. `2` |
+| `value`       | String // Number // bigint | e.g. `"4242"` or `4242`                                                                                   |
+| `assetCode`   | String                     | [ISO 4217 currency code](https://en.wikipedia.org/wiki/ISO_4217), e.g. `USD`                              |
+| `assetScale`  | Number                     | difference in orders of magnitude between the standard unit and a corresponding fractional unit, e.g. `2` |
 
 If the payment is a `FixedSend` payment, this endpoint should deduct its fees from the receive amount value. If the payment is a `FixedDelivery` payment, this endpoint should add the fees to the send amount value. The response body MUST be equal to the [request body](#request-body) apart from the updated `sendAmount` or `receiveAmount` values. The response status code for a successful request is a `201`. The `mock-account-provider` includes a [minimalistic example](../packages/mock-account-provider/app/routes/quotes.ts).
 
-The `backend` package requires an environment variable called `QUOTE_URL` which MUST specify this endpoint.
+The `backend` package requires an environment variable called `QUOTE_URL` which MUST specify the URL of this endpoint.
 
 ## Webhook Events
 
@@ -47,54 +65,61 @@ The endpoint accepts a `POST` request with
 
 | Variable Name | Type                          | Description         |
 | ------------- | ----------------------------- | ------------------- |
-| id            | string                        | event id            |
-| type          | enum: [EventType](#eventtype) |
-| data          | Object                        | any additional data |
+| `id`          | String                        | event id            |
+| `type`        | Enum: [EventType](#eventtype) |                     |
+| `data`        | Object                        | any additional data |
 
 #### EventType
 
-| Value                    | Description                                                                 |
-| ------------------------ | --------------------------------------------------------------------------- |
-| IncomingPaymentCompleted | Incoming payment is complete and doesn't accept any incoming funds anymore. |
-| IncomingPaymentExpired   | Incoming payment is expired and doesn't accept any incoming funds anymore.  |
-| OutgoingPaymentCreated   | Outgoing payment was created.                                               |
-| OutgoingPaymentCompleted | Outgoing payment is complete.                                               |
-| OutgoingPaymentFailed    | Outgoing payment failed.                                                    |
+| Value                              | Description                                                                 |
+| ---------------------------------- | --------------------------------------------------------------------------- |
+| `incoming_payment.completed`       | Incoming payment is complete and doesn't accept any incoming funds anymore. |
+| `incoming_payment.expired`         | Incoming payment is expired and doesn't accept any incoming funds anymore.  |
+| `outgoing_payment.created`         | Outgoing payment was created.                                               |
+| `outgoing_payment.completed`       | Outgoing payment is complete.                                               |
+| `outgoing_payment.failed`          | Outgoing payment failed.                                                    |
+| `payment_pointer.web_monetization` | Web Monetization payments received via STREAM.                              |
 
 The `backend` package requires an environment variable called `WEBHOOK_URL` which MUST specify this endpoint.
 
 ### Event Handlers
 
-#### `IncomingPaymentCompleted`
+#### `incoming_payment.completed`
 
-An [Open Payments](./glossary#open-payments) Incoming Payment was completed, either manually or programmatically, i.e. it does not accept any incoming funds anymore. The Account Servicing Entity SHOULD withdraw any funds already received and deposit them into the payee's account.
+An [Open Payments](./glossary#open-payments) Incoming Payment was completed, either manually or programmatically, i.e. it does not accept any incoming funds anymore. The Account Servicing Entity SHOULD withdraw all funds received and deposit them into the payee's account.
 
 - Action: Withdraw liquidity
 
-#### `IncomingPaymentExpired`
+#### `incoming_payment.expired`
 
 An [Open Payments](./glossary#open-payments) Incoming Payment has expired, i.e. it does not accept any incoming funds anymore. The Account Servicing Entity SHOULD withdraw any funds already received and deposit them into the payee's account.
 
 - Action: Withdraw liquidity
 
-#### `OutgoingPaymentCreated`
+#### `outgoing_payment.created`
 
 An [Open Payments](./glossary#open-payments) Outgoing Payment has been created. It requires liquidity to be processed. The Account Servicing Entity SHOULD reserve the maximum requisite funds for the payment attempt on the payer's account.
 
 - Action: Deposit liquidity
 
-#### `OutgoingPaymentCompleted`
+#### `outgoing_payment.completed`
 
 An [Open Payments](./glossary#open-payments) Outgoing Payment was completed, i.e. it won't send any further funds. The Account Servicing Entity SHOULD withdraw any excess liquidity and deposit it into the payer's account.
 
 - Action: Withdraw liquidity
 
-#### `OutgoingPaymentFailed`
+#### `outgoing_payment.failed`
 
 An [Open Payments](./glossary#open-payments) Outgoing Payment failed to send all (or any) of the funds and won't re-try. The Account Servicing Entity SHOULD withdraw all or any excess liquidity and return it to the payer's account.
 
 - Action: Withdraw liquidity
 
+#### `payment_pointer.web_monetization`
+
+A [Web Monetization](./glossary.md#web-monetization) payment has been received via [STREAM](./glossary.md#stream) by a payment pointer. The Account Servicing Entity SHOULD withdraw all funds received and deposit them into the payee's account.
+
+- Action: Withdraw liquidity
+
 ## Open Payments
 
 The Rafiki `backend` exposes the [Open Payments](./glossary#open-payments) APIs. They are auth-protected using the [Grant Negotiation Authorization Protocol](./glossary#grant-negotiation-authorization-protocol) (GNAP). While Rafiki comes with a reference implementation of a GNAP server--the `auth` package--an [Account Servicing Entity](./glossary#account-servicing-entity) may implement its own GNAP server.

diff --git a/docs/mov/eCom-example.mov b/docs/mov/eCom-example.mov
diff --git a/infrastructure/local/README.md b/infrastructure/local/README.md
@@ -1,7 +1,6 @@
 # Local Playground
 
-This environment will set up an environment where you can use the Open Payments API and the Rafiki
-admin GraphQL.
+This environment will set up an playground where you can use the Rafiki Admin APIs and the Open Payments APIs.
 
 Prerequisites:
 
@@ -35,41 +34,40 @@ pnpm localenv:psql:dbvolumes:remove
 ```
 
 The local environment consists of a primary Rafiki instance and a secondary Rafiki instance, each with
-its own docker compose files ([primary](./docker-compose.yml), [secondary](./peer-docker-compose.yml)).
-The primary `docker-compose.yml` includes the main Rafiki services `backend`, `auth`, and `rates`, as well
-as the required data stores tigerbeetle, redis, and postgres, so it can be run on its own.
-The `peer-docker-compose.yml` includes only the Rafiki services, not the data stores. It uses the
+its own docker compose files ([Cloud Nine Wallet](./docker-compose.cnw.yml), [Happy Life Bank](./docker-compose.hlf.yml)).
+The primary Cloud Nine Wallet docker compose file (`docker-compose.cnw.yml`) includes the main Rafiki services `backend` and `auth`, as well
+as the required data stores tigerbeetle (if enabled), redis, and postgres, so it can be run on its own. Furthermore,
+both include the `local-signature-utils` signature generation app for Postman.
+The secondary Happy Life Bank docker compose file (`docker-compose.hlb.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 by itself.
-The `pnpm run localenv` command starts both the primary instance and the secondary.
+The `pnpm localenv:start` command starts both the primary instance and the secondary.
 
-## P2P payment
+## Environment overview
 
-This will demonstrate a P2P payment from Grace Franklin (Fynbos account) to Philip Fry (local bank account) using
-the requests in the `Peer-to-peer transfer` folder of the Postman collection.
+![Docker compose environment](./local-dev.png)
 
-Grace's payment pointer can be found in the logs for `fynbos` and must be used to set the `gfranklinPaymentPointer` variable in a Postman environment.
-Philip's payment pointer can be found in the `local-bank` logs and used to set the `pfryPaymentPointer` Postman environment variable.
+#### Cloud Nine Wallet
 
-```
-pnpm localenv logs -f fynbos local-bank
-```
+(a) User Interface - accessible at http://localhost:3030
 
-Run through the following requests in the `Peer-to-peer transfer` folder to:
+(b) Admin API - accessible at http://localhost:3001/graphql
 
-- Create an incoming payment on Philip Fry's payment pointer.
-- Create a quote on Grace Fry's payment pointer.
-- Create an outgoing payment on Grace Fry's payment pointer.
+(c) Open Payments API - accessible at http://localhost:3000
 
-## Environment overview
+(d) Open Payments Auth API - accessible at accessible at http://localhost:3006
 
-![Docker compose environment](./local-dev.png)
+(e) Postman Signature Service - accessible at accessible at http://localhost:3040
+
+#### Happy Life Bank
+
+(f) User Interface - accessible at http://localhost:3031
 
-a - accessible at http://localhost:3001/graphql
+(g) Admin API - accessible at http://localhost:4001/graphql
 
-b - accessible at http://localhost:3000
+(h) Open Payments API - accessible at http://localhost:4000
 
-c - accessible at http://localhost:4001/graphql
+(i) Open Payments Auth API - accessible at accessible at http://localhost:4006
 
-d - accessible at http://localhost:4000
+(j) Postman Signature Service - accessible at accessible at http://localhost:3041
 
-e - accessible at localhost:5432
+(k) Postgres Server - accessible at http://localhost:5432
diff --git a/infrastructure/local/build-override.yml b/infrastructure/local/build-override.yml
diff --git a/infrastructure/local/cloud-nine-wallet/dbinit.sql b/infrastructure/local/cloud-nine-wallet/dbinit.sql
@@ -0,0 +1,15 @@
+CREATE USER cloud_nine_wallet_backend WITH PASSWORD 'cloud_nine_wallet_backend';
+CREATE DATABASE cloud_nine_wallet_backend;
+ALTER DATABASE cloud_nine_wallet_backend OWNER TO cloud_nine_wallet_backend;
+
+CREATE USER cloud_nine_wallet_auth WITH PASSWORD 'cloud_nine_wallet_auth';
+CREATE DATABASE cloud_nine_wallet_auth;
+ALTER DATABASE cloud_nine_wallet_auth OWNER TO cloud_nine_wallet_auth;
+
+CREATE USER happy_life_bank_backend WITH PASSWORD 'happy_life_bank_backend';
+CREATE DATABASE happy_life_bank_backend;
+ALTER DATABASE happy_life_bank_backend OWNER TO happy_life_bank_backend;
+
+CREATE USER happy_life_bank_auth WITH PASSWORD 'happy_life_bank_auth';
+CREATE DATABASE happy_life_bank_auth;
+ALTER DATABASE happy_life_bank_auth OWNER TO happy_life_bank_auth;