diff --git a/packages/documentation/src/content/docs/admin/admin-user-guide.mdx b/packages/documentation/src/content/docs/admin/admin-user-guide.mdx index 68251354f6..5590da8234 100644 --- a/packages/documentation/src/content/docs/admin/admin-user-guide.mdx +++ b/packages/documentation/src/content/docs/admin/admin-user-guide.mdx @@ -25,7 +25,7 @@ Ory Kratos and Rafiki Admin should be hosted on the same top-level domain. Hosti ### Login and account management -Access to Rafiki Admin is restricted to ensure that only authorized users can register. This is achieved by using an invitation-only system, where new users are invited by an administrator. The registration flow is not public, so users cannot sign up on their own. Instead, administrators create accounts using the `invite-user` script. +Access to Rafiki Admin uses an invitation-only system to ensure that only authorized users can register for an account. New users must be invited by an administrator. The registration flow is not public, so users cannot sign up on their own. Instead, administrators create accounts using the `invite-user` script. #### Invite a user @@ -60,7 +60,7 @@ If sending the link through Slack, ensure you format it as code by placing it in #### Generate a recovery link -There is an automated account recovery flow which requires an SMTP mail server for sending recovery links to users. Alternatively, an administrator can generate a recovery link using the same `invite-user` script. +Rafiki Admin provides an automated account recovery flow which requires an SMTP mail server for sending recovery links to users. Alternatively, an administrator can generate a recovery link using the same `invite-user` script. #### Remove a user @@ -91,7 +91,7 @@ In the [Local Playground](/integration/playground/overview#rafiki-admin), authen ## Navigation -After logging in, you’ll be greeted by the main landing page with a left-hand navigation menu. This menu provides access to all of the main functionality needed to manage your Rafiki instance. +After logging in, you’ll be greeted by the main landing page with a left-hand navigation menu. This menu provides access to the main functionality needed to manage your Rafiki instance. -While the Edit Peer page shares fields with the Create Peer page, it also includes additional fields and actions specific to managing an existing peer: +While the Edit Peer page shares fields with the Create Peer page, it also includes fields and actions specific to managing an existing peer: | Section | Field/Action | Description | | --------------------- | ------------------ | ----------------------------------------------------------------------------------------- | @@ -160,7 +160,7 @@ While the Edit Peer page shares fields with the Create Peer page, it also includ | | Deposit Liquidity | To increase the amount of liquidity available, select **Deposit liquidity**. | | | Withdraw Liquidity | To reduce the amount of liquidity available, select **Withdraw liquidity**. | -After editing any of the above fields in the General Information or HTTP Information sections, select **Save** to commit those changes. +After editing any of the preceding fields in the General Information or HTTP Information sections, select **Save** to commit those changes. #### Delete peer @@ -179,7 +179,7 @@ Confirm the deletion by typing "delete peer" into the text field and selecting * The Assets page allows you to manage assets in your Rafiki instance, including viewing, editing, and creating assets. -On this page, all configured assets are displayed in a table where you can view the asset ID, the asset code, the scale, and the withdrawal threshold. +On this page, all configured assets appear in a table where you can view the asset ID, the asset code, the scale, and the withdrawal threshold. -While the Edit Asset page shares fields with the Create Asset page, it also includes additional fields and actions specific to managing an existing asset: +While the Edit Asset page shares fields with the Create Asset page, it also includes fields and actions specific to managing an existing asset: | Section | Field/Action | Description | | --------------------- | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | @@ -226,13 +226,13 @@ While the Edit Asset page shares fields with the Create Asset page, it also incl | | Basis Points | A variable fee per asset. One basis point fee is equal to 0.01% of the total amount, 100 basis points = 1%, 10000 basis points = 100% | | | Fee history | To view a list of asset fees over time, select **Fee history**. | -After editing any of the above fields in the General Information or Sending Fee sections, select **Save** to commit those changes. +After editing any of the preceding fields in the General Information or Sending Fee sections, select **Save** to commit those changes. ## Wallet addresses The Wallet Addresses page allows you to manage the wallet addresses associated with your Rafiki instance, including viewing, editing, and creating wallet addresses. -On this page, all configured wallet addresses are displayed in the table where you can view the address URL, the public name, and the wallet status. +On this page, all configured wallet addresses appear in the table where you can view the address URL, the public name, and the wallet status. -While the Edit Wallet Address page shares fields with the Create Wallet Address page, it also includes additional fields and actions specific to managing an existing wallet address. +While the Edit Wallet Address page shares fields with the Create Wallet Address page, it also includes fields and actions specific to managing an existing wallet address. | Section | Field/Action | Description | | --------------------- | -------------------- | ------------------------------------------------------------------------------------------- | @@ -287,7 +287,7 @@ While the Edit Wallet Address page shares fields with the Create Wallet Address | Liquidity Information | Amount | Current amount of liquidity available for this wallet. | | | Withdraw | To withdraw funds from this wallet, select **Withdraw**. | -After editing any of the above fields in the General Information section, select **Save** to commit those changes. +After editing any of the preceding fields in the General Information section, select **Save** to commit those changes. :::note[What if I need to edit or delete a wallet address?] When managing wallet addresses in Rafiki, there are certain restrictions and limitations to be aware of: @@ -309,7 +309,7 @@ In both cases, the recommended approach is to create a new wallet address and de The Webhook Events page allows you to monitor and manage webhook events within your Rafiki instance. Webhook events in Rafiki are the main communication channel between you and your Rafiki instance. See Webhook events for more information about webhook events. -All webhook events that have been triggered are displayed in the table. For each webhook event, you can see the webhook ID, the event type, and the date and time of the event. There is also a field at the top of the page allowing you to filter the table by event type, making it easier to drill down into specific events. +All triggered webhook events appear in the table. For each webhook event, you can see the webhook ID, the event type, and the date and time of the event. A field at the top of the page allows you to filter the table by event type, making it easier to drill down into specific events. - Discover what is in our Backend GraphQL schema. + Discover what's in our Backend GraphQL schema. - Discover what is in our Auth GraphQL schema. + Discover what's in our Auth GraphQL schema. diff --git a/packages/documentation/src/content/docs/integration/deployment/docker-compose.mdx b/packages/documentation/src/content/docs/integration/deployment/docker-compose.mdx index 7dd497e7fe..404e815244 100644 --- a/packages/documentation/src/content/docs/integration/deployment/docker-compose.mdx +++ b/packages/documentation/src/content/docs/integration/deployment/docker-compose.mdx @@ -10,14 +10,14 @@ This guide is an example of deploying Rafiki using Docker Compose with Nginx as ### Domain and subdomains setup -We will map the [Open Payments resource server](/integration/deployment/services/backend-service#open-payments) to your domain, and the [ILP Connector](/integration/deployment/services/backend-service#interledger-connector), [Open Payments auth server](/integration/deployment/services/auth-service), and [Admin UI](/integration/deployment/services/frontend-service) to subdomains. Using the DNS host of your choice, set up your domain and subdomains according to the following recommended convention: +We will map the [Open Payments resource server](/integration/deployment/services/backend-service#open-payments) to your domain, and the [ILP connector](/integration/deployment/services/backend-service#interledger-connector), [Open Payments auth server](/integration/deployment/services/auth-service), and [Admin UI](/integration/deployment/services/frontend-service) to subdomains. Using the DNS host of your choice, set up your domain and subdomains according to the following recommended convention:
| service | function | URL | example | | ----------------------------- | --------------------------------------------------------------------------- | ------------ | ------------------ | | Open Payments resource server | Exposes the Open Payments APIs | DOMAIN | myrafiki.com | -| ILP Connector | Exposes an ILP connector to send and receive ILP packets between peers | ilp.DOMAIN | ilp.myrafiki.com | +| ILP connector | Exposes an ILP connector to send and receive ILP packets between peers | ilp.DOMAIN | ilp.myrafiki.com | | Open Payments auth server | Exposes a reference implementation of an Open Payments authorization server | auth.DOMAIN | auth.myrafiki.com | | Admin UI | Exposes an Admin UI to manage Rafiki | admin.DOMAIN | admin.myrafiki.com | @@ -32,7 +32,7 @@ The example domain and subdomain values are for demonstration purposes only. You Deploy a general purpose VM with the following minimum specifications: - OS: Linux distro -- RAM: 4GB +- RAM: 4 GB - vCPUs: 2 Install the following software on the VM: @@ -262,14 +262,14 @@ volumes: ## Create Nginx config files -Create nginx configuration files for every exposed domain: +Create Nginx configuration files for every exposed domain:
| service | URL | example | Nginx config file | | ----------------------------- | ------------ | ------------------ | --------------------------------------------------------------- | | Open Payments resource server | DOMAIN | myrafiki.com | /etc/nginx/sites-available/open_payments_resource_server.config | -| ILP Connector | ilp.DOMAIN | ilp.myrafiki.com | /etc/nginx/sites-available/ilp.config | +| ILP connector | ilp.DOMAIN | ilp.myrafiki.com | /etc/nginx/sites-available/ilp.config | | Open Payments auth server | auth.DOMAIN | auth.myrafiki.com | /etc/nginx/sites-available/open_payments_auth_server.config | | Admin UI | admin.DOMAIN | admin.myrafiki.com | /etc/nginx/sites-available/admin.config | @@ -279,7 +279,7 @@ Create nginx configuration files for every exposed domain: The example domain and subdomain values are for demonstration purposes only. You must use the actual domain names that you set up with your DNS host. ::: -### Open Payments Resource Server (`backend` package) +### Open Payments resource server (`backend` package) Using the editor of your choice, save the following file as `open_payments_resource_server.config` in the `/etc/nginx/sites-available` directory on your VM: @@ -324,7 +324,7 @@ server { } ``` -### ILP Connector (`backend` package) +### ILP connector (`backend` package) Save the following file as `ilp.config` in the `/etc/nginx/sites-available` directory on your VM: @@ -368,7 +368,7 @@ server { } ``` -### Open Payments Auth Server (`auth` package) +### Open Payments auth server (`auth` package) Save the following file as `open_payments_auth_server.config` in the `/etc/nginx/sites-available` directory on your VM: diff --git a/packages/documentation/src/content/docs/integration/deployment/helm-k8s.mdx b/packages/documentation/src/content/docs/integration/deployment/helm-k8s.mdx index 6e4d83fc43..7f2383fa89 100644 --- a/packages/documentation/src/content/docs/integration/deployment/helm-k8s.mdx +++ b/packages/documentation/src/content/docs/integration/deployment/helm-k8s.mdx @@ -6,7 +6,7 @@ import { LinkOut } from '@interledger/docs-design-system' ### Running Rafiki in production -To run Rafiki in your production environment you will need to have the following software and tools installed: +To run Rafiki in your production environment you must have the following software and tools installed: #### Dependencies: @@ -26,13 +26,13 @@ Run the following command to install the example Helm Chart above: helm install rafiki PATH_TO_RAFIKI_REPO/infrastructure/helm/rafiki ``` -#### Tigerbeetle +#### TigerBeetle -For Rafiki's accounting database, you may opt to run Tigerbeetle in place of Postgres. Though you must run one Postgres instance that's used for the `auth` services and Open Payments resources. +For Rafiki's accounting database, you may opt to run TigerBeetle in place of Postgres. Though you must run one Postgres instance that's used for the `auth` services and Open Payments resources. -To change the version of Tigerbeetle you must change the respective tag in the values.yaml file for Tigerbeetle. +To change the version of TigerBeetle you must change the respective tag in the values.yaml file for TigerBeetle. -#### Port Forwarding +#### Port forwarding In the current alpha version of Rafiki, no ports are exposed by default. You can port-forward the frontend (Admin UI) port by running the following: diff --git a/packages/documentation/src/content/docs/integration/deployment/services/auth-service.mdx b/packages/documentation/src/content/docs/integration/deployment/services/auth-service.mdx index b79303d98e..5f913107ea 100644 --- a/packages/documentation/src/content/docs/integration/deployment/services/auth-service.mdx +++ b/packages/documentation/src/content/docs/integration/deployment/services/auth-service.mdx @@ -36,7 +36,7 @@ Review the Op ## Identity provider (IdP) -An identity provider (IdP) is a system or service that manages user authentication, identity information, and consent. When you use your Google account credentials to “Sign in with Google” on an app or website, for example, Google is acting as your identity provider. +An identity provider (IdP) is a system or service that manages user authentication, identity information, and consent. When you use your Google Account credentials to “Sign in with Google” on an app or website, for example, Google is acting as your identity provider. You must integrate with an [IdP](/integration/requirements/idp) when using Rafiki's `auth` service because the Open Payments standard requires interactive outgoing payment _grant_ requests. In an interactive request, there must be explicit interaction by an individual (for example, a client's end-user) to approve or deny the grant. In this case, the grant must be explicitly approved before an outgoing payment is created. diff --git a/packages/documentation/src/content/docs/integration/deployment/services/backend-service.mdx b/packages/documentation/src/content/docs/integration/deployment/services/backend-service.mdx index 199c4f61ed..dac2b0918c 100644 --- a/packages/documentation/src/content/docs/integration/deployment/services/backend-service.mdx +++ b/packages/documentation/src/content/docs/integration/deployment/services/backend-service.mdx @@ -20,7 +20,7 @@ The following are required when using the `backend` service. - A Postgres database, separate from the `auth` service’s database, for Open Payments resources - TigerBeetle or a separate Postgres database for accounting liquidity :::note - You can use the same database instance of Postgres for the `backend` service, `auth` service, and accounting liquidities (if not using TigerBeetle). However, separate database schemas are required within the Rafiki instance to maintain boundaries between the objects being managed. + You can use the same database instance of Postgres for the `backend` service, `auth` service, and accounting liquidity (if not using TigerBeetle). However, separate database schemas are required within the Rafiki instance to maintain boundaries between the managed objects. ::: You must also set the environment variables for the `backend` service. @@ -45,13 +45,13 @@ Some of the responsibilities of a connector include: The `backend` service includes an HTTP server listening on the configured `CONNECTOR_PORT`. Your connector can receive incoming packets via HTTP and/or direct calls from within the `backend` service. An incoming packet is only accepted if it's from a configured peer and accompanied by your peer’s incoming HTTP `authToken`. -Similarly, if a packet's destination address corresponds to a peer, your connector will forward the packet to your peer over HTTP, along with your peer's outgoing HTTP `authToken`. +Similarly, if a packet's destination address corresponds to a peer, your connector forwards the packet to your peer over HTTP, along with your peer's outgoing HTTP `authToken`. :::note[Auth tokens] You and your peer should have exchanged incoming and outgoing auth tokens as part of establishing your [peering relationship](/integration/requirements/peers#prerequisites). ::: -A packet can either continue on to your peer via HTTP or terminate at your Rafiki instance's STREAM server. If the packet terminates at your STREAM server, your connector will attempt to extract and decode the payment tag from the packet's destination address. When your connector successfully matches the tag with a locally managed wallet address or incoming payment, the connector will not forward the packet. Instead, it will credit the corresponding balance and track the total amount received in Redis to support STREAM receipts. Packets addressed to a wallet address happen via SPSP. +A packet can either continue on to your peer via HTTP or end at your Rafiki instance's STREAM server. If the packet terminates at your STREAM server, your connector attempts to extract and decode the payment tag from the packet's destination address. When your connector successfully matches the tag with a locally managed wallet address or incoming payment, the connector does not forward the packet. Instead, it credits the corresponding balance and track the total amount received in Redis to support STREAM receipts. Packets addressed to a wallet address happen via SPSP. ## GraphQL Backend Admin API diff --git a/packages/documentation/src/content/docs/integration/deployment/services/frontend-service.mdx b/packages/documentation/src/content/docs/integration/deployment/services/frontend-service.mdx index aa450a5eb7..0f4a4c3879 100644 --- a/packages/documentation/src/content/docs/integration/deployment/services/frontend-service.mdx +++ b/packages/documentation/src/content/docs/integration/deployment/services/frontend-service.mdx @@ -29,7 +29,7 @@ You must also set the environment variables for the `frontend` service. ## Rafiki Admin settings -While the `frontend` service is not required to run a Rafiki instance, it is highly recommended. A number of administrative tasks could be performed programmatically via the Backend Admin API, but the `frontend` service makes these functions available through a user-friendly interface. +While the `frontend` service is not required to run a Rafiki instance, it's highly recommended. A number of administrative tasks could be performed programmatically via the Backend Admin API, but the `frontend` service makes these functions available through a user-friendly interface. ## Environment variables diff --git a/packages/documentation/src/content/docs/integration/playground/overview.mdx b/packages/documentation/src/content/docs/integration/playground/overview.mdx index edb4518b9f..4aaf2d6386 100644 --- a/packages/documentation/src/content/docs/integration/playground/overview.mdx +++ b/packages/documentation/src/content/docs/integration/playground/overview.mdx @@ -227,14 +227,14 @@ The following are the most commonly used commands: | 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` | +| Down and remove volumes (with TigerBeetle) | `pnpm localenv:compose down --volumes` | +| Down and remove 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` | +| Down (with Postgres) and remove 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 ` | diff --git a/packages/documentation/src/content/docs/integration/requirements/exchange-rates.mdx b/packages/documentation/src/content/docs/integration/requirements/exchange-rates.mdx index 702448c80c..d589bdf187 100644 --- a/packages/documentation/src/content/docs/integration/requirements/exchange-rates.mdx +++ b/packages/documentation/src/content/docs/integration/requirements/exchange-rates.mdx @@ -7,9 +7,9 @@ import { Mermaid, CodeBlock, LinkOut } from '@interledger/docs-design-system' If you plan to support cross-currency transactions, you must specify from where your Rafiki instance will fetch current exchange rates. -Every Interledger payment is preceded by a rate probe. This probe provides a quote that estimates the full cost of transferring value over the network. For a rate probe involving a cross-currency transaction to be successful, Rafiki needs to know the exchange rates for each currency that makes up the transaction. +A rate probe precedes every Interledger payment. The probe provides a quote that estimates the full cost of transferring value over the network. For a rate probe involving a cross-currency transaction to be successful, Rafiki needs to know the exchange rates for each currency that makes up the transaction. -Often, it's the receiving ASE that provides the exchange rates for each ILP packet. For example, let's say you and your peer transact in USD. Your peer also supports MXN. If a USD payment from from your side was addressed to a wallet address set up for MXN on your peer's side, then your peer would provide the USD to MXN exchange rate. +Often, it's the receiving ASE that provides the exchange rates for each ILP packet. For example, say you and your peer transact in USD. Your peer also supports MXN. If a USD payment from your side is addressed to a wallet address set up for MXN on your peer's side, then your peer would provide the USD to MXN exchange rate. ## Specify your exchange rates endpoint diff --git a/packages/documentation/src/content/docs/integration/requirements/idp.mdx b/packages/documentation/src/content/docs/integration/requirements/idp.mdx index 8bb6b16cd2..16b649e14d 100644 --- a/packages/documentation/src/content/docs/integration/requirements/idp.mdx +++ b/packages/documentation/src/content/docs/integration/requirements/idp.mdx @@ -27,13 +27,13 @@ We provide Ory Kratos, a cloud-based user management system, for the identity an ## Interactive grants -In Open Payments, grants are used to indicate a resource owner, such as an account holder, has given a piece of software, such as a mobile app, permission (consent) to act on their behalf. +In Open Payments, grants indicate a resource owner, such as an account holder, has given a piece of software, such as a mobile app, permission (consent) to act on their behalf. -Rafiki's implementation of an Open Payments authorization server requires that consent is collected via an interactive grant before an outgoing payment request is issued. A grant is interactive when explicit interaction by a resource owner (e.g., the software's end user) is required to approve or deny the grant. Tapping an _Approve_ button to authorize a payment is an example of an explicit interaction. +Rafiki's implementation of an Open Payments authorization server requires that consent is collected via an interactive grant before an outgoing payment request is issued. A grant is interactive when explicit interaction by a resource owner (for example, the software's end user) is required to approve or deny the grant. Tapping an _Approve_ button to authorize a payment is an example of an explicit interaction. Interactive grants can be optional for incoming payments and quotes; however, they're enabled by default in Rafiki (the `LIST_ALL_ACCESS_INTERACTION` environment variable is `true`). When a grant request includes a `list-all` action for incoming payments and quotes, the request requires interaction. The `list-all` action is used when the client asks to list resources that it did not create. -If `LIST_ALL_ACCESS_INTERACTION` is `false`, you can still force interactive grants for quotes and/or incoming payments by setting the respective variable(s) to `true`. +If `LIST_ALL_ACCESS_INTERACTION` is `false`, you can still force interactive grants for quotes and/or incoming payments by setting the respective variables to `true`. - `QUOTE_INTERACTION` - `INCOMING_PAYMENT_INTERACTION` @@ -54,15 +54,15 @@ The following variables must be configured for the `auth` service.
-| Variable | Helm value name | Default | Description | -| ------------------------------ | ---------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `IDENTITY_SERVER_URL` | `auth.identityServer.domain` | N/A | The URL of your IdP's server, used by the authorization server to inform an Open Payments client of where to redirect the end-user to start interactions. | -| `IDENTITY_SERVER_SECRET` | `auth.identityServer.secret` | N/A | A shared secret between the authorization server and the IdP server; the authorization server will use the secret to secure its IdP-related endpoints.
When the IdP server sends requests to the authorization server, the IdP server must provide the secret via an [`x-idp-secret`](#x-idp-secret-header) header. | -| `INCOMING_PAYMENT_INTERACTION` | `auth.interaction.incomingPayment` | `false` | Indicates whether incoming payments grant requests are interactive. | -| `INTERACTION_EXPIRY_SECONDS` | `auth.interactionExpirySeconds` | `600` | The time in seconds for which a user can interact with a grant request | -| `INTERACTION_PORT` | `auth.port.interaction` | `3009` | The port number for the [interaction endpoints](#interaction-endpoints) | -| `LIST_ALL_ACCESS_INTERACTION` | N/A | `true` | Specifies whether grant requests including a `list-all` action should require interaction. In these requests, the client asks to list resources that they themselves did not create. | -| `QUOTE_INTERACTION` | `auth.interaction.quote` | `false` | When `true`, quote grants are interactive. | +| Variable | Helm value name | Default | Description | +| ------------------------------ | ---------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `IDENTITY_SERVER_URL` | `auth.identityServer.domain` | N/A | The URL of your IdP's server, used by the authorization server to inform an Open Payments client of where to redirect the end-user to start interactions. | +| `IDENTITY_SERVER_SECRET` | `auth.identityServer.secret` | N/A | A shared secret between the authorization server and the IdP server; the authorization server uses the secret to secure its IdP-related endpoints.
When the IdP server sends requests to the authorization server, the IdP server must provide the secret via an [`x-idp-secret`](#x-idp-secret-header) header. | +| `INCOMING_PAYMENT_INTERACTION` | `auth.interaction.incomingPayment` | `false` | Indicates whether incoming payments grant requests are interactive. | +| `INTERACTION_EXPIRY_SECONDS` | `auth.interactionExpirySeconds` | `600` | The time in seconds for which a user can interact with a grant request | +| `INTERACTION_PORT` | `auth.port.interaction` | `3009` | The port number for the [interaction endpoints](#interaction-endpoints) | +| `LIST_ALL_ACCESS_INTERACTION` | N/A | `true` | Specifies whether grant requests including a `list-all` action should require interaction. In these requests, the client asks to list resources that they themselves did not create. | +| `QUOTE_INTERACTION` | `auth.interaction.quote` | `false` | When `true`, quote grants are interactive. |
@@ -116,21 +116,21 @@ The `result` query parameter in the response indicates the success or failure of
-| Response | Description | Example | -| -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | -| Rejected | The interaction was rejected by the end-user | `?result=grant_rejected` | -| Invalid | The grant was not in a state where it could be accepted or rejected (e.g., grant was already approved) | `?result=grant_invalid` | -| Success | The grant was successful with the following returned in the response:
  • A hash representing the SHA-256 hash of values provided by the client in the grant initialization request (`interact.finish.nonce`), and the values in the response returned from the authorization server (`interact.finish`).
  • The `interact_ref` that identifies the interaction on the authorization server alongside the hash
  • The URI of the grant initialization request (e.g., `https://www.auth-server.com`)
| `hash=p28jsq0Y2KK3WS__a42tavNC64ldGTBroywsWxT4md_jZQ1R\HZT8BOWYHcLmObM7XHPAdJzTZMtKBsaraJ64A &interact_ref=4IFWWIKYBC2PQ6U56NL1` | +| Response | Description | Example | +| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------- | +| Rejected | The end-user rejected the interaction | `?result=grant_rejected` | +| Invalid | The grant was not in a state where it could be accepted or rejected (for example, the grant was already approved) | `?result=grant_invalid` | +| Success | The grant was successful with the following returned in the response:
  • A hash representing the SHA-256 hash of values provided by the client in the grant initialization request (`interact.finish.nonce`), and the values in the response returned from the authorization server (`interact.finish`).
  • The `interact_ref` that identifies the interaction on the authorization server alongside the hash
  • The URI of the grant initialization request (for example, `https://www.auth-server.com`)
| `hash=p28jsq0Y2KK3WS__a42tavNC64ldGTBroywsWxT4md_jZQ1R\HZT8BOWYHcLmObM7XHPAdJzTZMtKBsaraJ64A &interact_ref=4IFWWIKYBC2PQ6U56NL1` |
-When successful, the SHA-256 hash of the interaction is sent in the response to the client, along with an `interact_ref` that identifies the interaction on the authorization server and the URI of the grant initialization request. The client must verify the hash before it will request to continue the grant. +When successful, the SHA-256 hash of the interaction is sent in the response to the client, along with an `interact_ref` that identifies the interaction on the authorization server and the URI of the grant initialization request. The client must verify the hash before the client requests the grant to continue. #### Continue grant The client requests a grant from the authorization server for an accepted interaction. The authorization server responds with an access token. -## x-idp-secret header +## X-idp-secret header The `x-idp-secret` header is specific to Rafiki's authorization server and is used for requests to the following endpoints: diff --git a/packages/documentation/src/content/docs/integration/requirements/overview.mdx b/packages/documentation/src/content/docs/integration/requirements/overview.mdx index 1b2b9f98bc..a37f8a5862 100644 --- a/packages/documentation/src/content/docs/integration/requirements/overview.mdx +++ b/packages/documentation/src/content/docs/integration/requirements/overview.mdx @@ -21,7 +21,7 @@ You must set up Rafiki to support at least one asset. An asset in Rafiki represe ## Associate each user-facing payment account with a wallet address -A wallet address is a publicly shareable standardized ID for a payment account. Each payment account belonging to your users (e.g., customers) must have at least one associated wallet address for the account to be able to send and/or receive payments via Open Payments and Interledger. +A wallet address is a publicly shareable standardized ID for a payment account. Each payment account belonging to your users (for example, your customers) must have at least one associated wallet address for the account to be able to send and/or receive payments via Open Payments and Interledger. [Set up your wallet addresses](/integration/requirements/wallet-addresses) @@ -45,7 +45,7 @@ You have the option to charge a sending fee, on top of any estimated network fee ## Add a peer to enable Interledger payments -You must add one or more peers if you intend to enable Interledger payments on your accounts. A peer is another ASE that you will connect with via Interledger and is likely running their own Rafiki instance. +You must add one or more peers if you intend to enable Interledger payments on your accounts. A peer is another ASE that you connect with via Interledger and is likely running their own Rafiki instance. If you are using Rafiki solely for transfers between accounts on your ledger, peers are not required. @@ -55,7 +55,7 @@ If you are using Rafiki solely for transfers between accounts on your ledger, pe An identity provider (IdP) is a system or service that stores and manages user identity information, authentication, and consent. Examples of IdPs include OpenID Connect and Okta. -Integration with an IdP is required if you plan to use the authorization server provided through Rafiki's auth service. The authorization server requires consent to be collected via an interactive grant before an outgoing payment request is issued. The purpose of the IdP is to handle the authentication and consent required to authorize the interactive grant request. +You must integrate with an IdP if you plan to use the authorization server provided through Rafiki's auth service. The authorization server requires consent be collected via an interactive grant before an outgoing payment request is issued. The purpose of the IdP is to handle the authentication and consent required to authorize the interactive grant request. [Integrate Rafiki with your IdP](/integration/requirements/idp) @@ -63,7 +63,7 @@ Integration with an IdP is required if you plan to use the authorization server Ensure you've completed the following tasks before you deploy Rafiki to a production environment and join the Interledger network. -- [ ] You are a licensed financial account servicing entity within the jurisdiction(s) you operate in +- [ ] You are a licensed financial account servicing entity within the jurisdictions you operate in - [ ] You have added at least one asset, either through the Backend Admin API or the Rafiki Admin app - [ ] You have implemented a strategy for creating wallet addresses for your account holders - [ ] You have set up your webhook endpoint and understand how to handle each webhook event diff --git a/packages/documentation/src/content/docs/integration/requirements/peers.mdx b/packages/documentation/src/content/docs/integration/requirements/peers.mdx index 0e37425cda..d6ab62682a 100644 --- a/packages/documentation/src/content/docs/integration/requirements/peers.mdx +++ b/packages/documentation/src/content/docs/integration/requirements/peers.mdx @@ -4,9 +4,9 @@ title: Peers import { CodeBlock, LinkOut } from '@interledger/docs-design-system' -To join the Interledger network and be able to send and receive payments, you must add one or more peer(s) to your Rafiki instance. Peering establishes the connections needed for your Rafiki instance to interact with another account servicing entity (ASE). The purpose of this guide is to help you set up and manage peers. +To join the Interledger network and be able to send and receive payments, you must add one or more peers to your Rafiki instance. Peering establishes the connections needed for your Rafiki instance to interact with another account servicing entity (ASE). The purpose of this guide is to help you set up and manage peers. -While this guide focuses on the conceptual and technical steps of adding and managing peers via the Backend Admin API, the Rafiki Admin application offers the same functionality in a user-friendly interface. +While this guide focuses on the conceptual and technical steps of adding and managing peers via the Backend Admin API, the Rafiki Admin application offers the same capabilities in a user-friendly interface. Refer to the [Rafiki Admin user guide](/admin/admin-user-guide#peers) for detailed instructions and examples of creating and managing peers through the application. @@ -31,7 +31,7 @@ Before adding a peer, you and the account servicing entity you intend to peer wi ### Optional settings -- Deposit an `initialLiquidity` for your peer. Liquidity can also be deposited later using the `depositPeerLiquidity` mutation. +- Deposit an `initialLiquidity` for your peer. You can deposit liquidity later using the `depositPeerLiquidity` mutation. - Define a `maxPacketAmount` value, which specifies the maximum packet size you are willing to accept from the peer. Your peer's `maxPacketAmount` value does not need to match, as this value is independently set by each ASE. If omitted, payments will not be broken into smaller packets. ## Set up peering in Rafiki @@ -40,7 +40,7 @@ The basic workflow of setting up a peering relationship starts with adding the a ### Add an asset -As mentioned in the prerequisites, an asset must be added to your Rafiki instance before creating a peering relationship. To learn how to add an asset, refer to [Assets](/integration/requirements/assets/). +As mentioned in the prerequisites, you must add an asset to your Rafiki instance before creating a peering relationship. To learn how to add an asset, refer to [Assets](/integration/requirements/assets/). ### Add a peer @@ -85,7 +85,7 @@ mutation CreatePeer($input: CreatePeerInput!) { "outgoing": {"endpoint": "ilp.othergreatwallet.com", "authToken": "theirtoken"} }, "assetId": "INSERT_ASSET_ID", - "initialLiquidity": + "initialLiquidity": } } ``` @@ -141,7 +141,7 @@ Once a peer has been added to your Rafiki instance, there is minimal ongoing man How to edit a peer Occasionally, you may need to adjust peering configurations or address any changes communicated by the peer. Some examples include updating new endpoints or tokens, technical settings like the maximum packet amount, or peer liquidity thresholds. -In this example we are going to update the peer we just created. Rather than change any of the peering details, we can add some optional details that we didn't include when we created the peer. We will define the `maxPacketAmount` and the `liquidityThreshold`. +In this example we will update the peer we just created. Rather than change any of the peering details, we can add some optional details that we didn't include when we created the peer. We will define the `maxPacketAmount` and the `liquidityThreshold`. #### `updatePeer` @@ -188,11 +188,11 @@ The input object for the update operation only requires that the `id` is present
-| Variable | Description | Required | -| -------------------- | ------------------------------------------------------------------------------------------------------ | -------- | -| `id` | The ID of the peer you wish to update. | Y | -| `maxPacketAmount` | Maximum packet size you are willing to accept from the peer. | N | -| `liquidityThreshold` | A webhook event will notify the Account Servicing Entity if peer liquidity falls below this new value. | N | +| Variable | Description | Required | +| -------------------- | --------------------------------------------------------------------------------------------------- | -------- | +| `id` | The ID of the peer you wish to update. | Y | +| `maxPacketAmount` | Maximum packet size you are willing to accept from the peer. | N | +| `liquidityThreshold` | A webhook event notifies the account servicing entity if peer liquidity falls below this new value. | N |
@@ -229,9 +229,9 @@ The input object for the update operation only requires that the `id` is present
How to delete a peer -Deleting a peer is an action that removes a peer from your Rafiki instance. There are specific rules and considerations to keep in mind before initating this irreversible operation. +Deleting a peer is an action that removes a peer from your Rafiki instance. There are specific rules and considerations to keep in mind before starting this irreversible operation. -A peer can only be deleted if no payments have been made to or received from that peer. This ensures that historical payment records are preserved. If you attempt to delete a peer with payment history, the backend will throw an error, preventing the deletion. +You can only delete a peer if no payments were sent to or received from that peer. This ensures that historical payment records are preserved. If you attempt to delete a peer with payment history, the backend throws an error, preventing the deletion. Deleting a peer is useful in situations where there were configuration errors when the peer was first created like an incorrect auth token or ILP address. diff --git a/packages/documentation/src/content/docs/integration/requirements/sending-fees.mdx b/packages/documentation/src/content/docs/integration/requirements/sending-fees.mdx index 4452381ade..1e5b994d69 100644 --- a/packages/documentation/src/content/docs/integration/requirements/sending-fees.mdx +++ b/packages/documentation/src/content/docs/integration/requirements/sending-fees.mdx @@ -5,7 +5,7 @@ title: Sending fees import { Badge } from '@astrojs/starlight/components' import { Mermaid, CodeBlock, LinkOut } from '@interledger/docs-design-system' -You have the option to charge sending fees, on top of any estimated network fees, for facilitating transfers. Each asset you support can have a different fee structure and you can specify both fixed and variable fees per asset. The fee amount is added on top of the quote that is generated after the ILP rate probe completes. Sending fees in Rafiki can be defined through the Backend Admin API or the [Rafiki Admin](/admin/admin-user-guide/#edit-asset) application. +You have the option to charge sending fees, on top of any estimated network fees, for facilitating transfers. Each asset you support can have a different fee structure and you can specify both fixed and variable fees per asset. The fee amount is added on top of the quote that is generated after the ILP rate probe completes. You can define sending fees through the Backend Admin API or the [Rafiki Admin](/admin/admin-user-guide/#edit-asset) application. ## Set fees using the `setFee` GraphQL mutation diff --git a/packages/documentation/src/content/docs/integration/requirements/wallet-addresses.mdx b/packages/documentation/src/content/docs/integration/requirements/wallet-addresses.mdx index b063e4a143..42e3b11ccd 100644 --- a/packages/documentation/src/content/docs/integration/requirements/wallet-addresses.mdx +++ b/packages/documentation/src/content/docs/integration/requirements/wallet-addresses.mdx @@ -5,11 +5,11 @@ title: Wallet addresses import { LinkOut } from '@interledger/docs-design-system' import { CodeBlock } from '@interledger/docs-design-system' -Each payment account belonging to your users (e.g., customers) must have at least one associated wallet address for the account to be able to send and receive payments over Interledger and Open Payments. A wallet address serves as a publicly shareable standardized ID for a payment account. +Each payment account belonging to your users (for example, your customers) must have at least one associated wallet address for the account to be able to send and receive payments over Interledger and Open Payments. A wallet address serves as a publicly shareable standardized ID for a payment account. :::note[Wallet address requirements] -- Your Rafiki instance must be set up for at least one asset before wallet addresses can be created as each wallet address must have an asset assigned to it. +- Your Rafiki instance must be set up with at least one asset before wallet addresses can be created as each wallet address must have an asset assigned to it. - Wallet address URLs are treated as case-insensitive, meaning that both lowercase and uppercase variations of the same address will be recognized as identical. ::: diff --git a/packages/documentation/src/content/docs/integration/requirements/webhook-events.mdx b/packages/documentation/src/content/docs/integration/requirements/webhook-events.mdx index 3f3acf8f11..edce4174d5 100644 --- a/packages/documentation/src/content/docs/integration/requirements/webhook-events.mdx +++ b/packages/documentation/src/content/docs/integration/requirements/webhook-events.mdx @@ -31,7 +31,7 @@ When an event occurs, the [`backend`](/integration/deployment/services/backend-s ## Webhook event request body -Each webhook event is sent as a JSON payload with the following structure in the request body. The parameters within the `data` object will vary depending on the event. +Each webhook event is sent as a JSON payload with the following structure in the request body. The parameters within the `data` object vary depending on the event.
@@ -44,7 +44,7 @@ Each webhook event is sent as a JSON payload with the following structure in the
:::tip[Duplicate events] -The `id` in the webhook event payload is unique. Your system can use the ID to determine whether the event has been received previously, preventing duplicate event processing. +The `id` in the webhook event payload is unique. Your system can use the ID to determine whether the event has was previously received, preventing duplicate event processing. :::
@@ -133,7 +133,7 @@ The `id` in the webhook event payload is unique. Your system can use the ID to d We provide an OpenAPI specification for the webhook events fired by Rafiki. -Additionally, the [local playground](/integration/playground/overview) contains example payloads in the Bruno collection that can be used to test your webhook service integration. +Additionally, the [Local Playground](/integration/playground/overview) contains example payloads in the Bruno collection you can use to test your webhook service integration. ## Verify webhook signatures @@ -208,15 +208,13 @@ If requests to credit/debit user accounts are lengthy processes, we recommend us ### Error handling -If a non-200 status is returned, indicating an error, or the request times out, Rafiki will retry the webhook request at increasing intervals until a `200` status is returned. You can configure - -The first retry is after 10 seconds. Additional retries occur after 20 more seconds, then after 30 more seconds, and so on. +If a non-200 status is returned, indicating an error, or the request times out, Rafiki retries the webhook request at increasing intervals until a `200` status is returned. The first retry occurs after 10 seconds. Additional retries occur after 20 more seconds, then after 30 more seconds, and so on.
| Variable | Type | Description | | ------------------- | --------- | --------------------------------------------------------------------------------------------------------------- | -| `WEBHOOK_TIMEOUT` | `backend` | The amount of time, in milliseconds, after which a webhook request will time out | +| `WEBHOOK_TIMEOUT` | `backend` | The amount of time, in milliseconds, after which a webhook request times out | | `WEBHOOK_MAX_RETRY` | `backend` | The maximum number of retries for a webhook event when a non-200 status is returned or if the request timed out |
@@ -229,7 +227,7 @@ The first retry is after 10 seconds. Additional retries occur after 20 more seco | Event type | Description | | ----------------------------------------------------------- | --------------------------------------------------------------------------------- | -| [`incoming_payment.created`](#incoming-payment-created) | An incoming payment has been created | +| [`incoming_payment.created`](#incoming-payment-created) | An incoming payment was created | | [`incoming_payment.completed`](#incoming-payment-completed) | An incoming payment is complete and will not accept any additional incoming funds | | [`incoming_payment.expired`](#incoming-payment-expired) | An incoming payment expired and will not accept any additional incoming funds | @@ -254,7 +252,7 @@ The first retry is after 10 seconds. Additional retries occur after 20 more seco The `incoming_payment.created` event indicates an incoming payment was created. At this point, the incoming payment has not received any funds. -The incoming payment will either complete or expire. +The incoming payment either completes or expires. #### Incoming payment completed diff --git a/packages/documentation/src/content/docs/overview/concepts/account-servicing-entity.mdx b/packages/documentation/src/content/docs/overview/concepts/account-servicing-entity.mdx index 9b32af9f1d..5690684af3 100644 --- a/packages/documentation/src/content/docs/overview/concepts/account-servicing-entity.mdx +++ b/packages/documentation/src/content/docs/overview/concepts/account-servicing-entity.mdx @@ -34,4 +34,4 @@ ASEs maintain a ledger of account balances and transaction histories for their a ### Authentication and consent -In the context of Open Payments, ASEs are responsible for authenticating resource owners (e.g., account holders) and obtaining their consent when clients, such as mobile apps, request access to a resource (e.g., an account). +In the context of Open Payments, ASEs are responsible for authenticating resource owners (for example, account holders) and obtaining their consent when clients, such as mobile apps, request access to a resource (for example, an account). diff --git a/packages/documentation/src/content/docs/overview/concepts/accounting.mdx b/packages/documentation/src/content/docs/overview/concepts/accounting.mdx index db35ce3699..83e70a9099 100644 --- a/packages/documentation/src/content/docs/overview/concepts/accounting.mdx +++ b/packages/documentation/src/content/docs/overview/concepts/accounting.mdx @@ -12,7 +12,7 @@ import { } from '@interledger/docs-design-system' import { Steps } from '@astrojs/starlight/components' -Rafiki uses double-entry accounting to record financial transactions. In this method of bookkeeping, a transaction recorded to one account results in an equal and opposite entry to another account. For example, a \$50 credit to one account will result in a \$50 debit from another account. +Rafiki uses double-entry accounting to record financial transactions. In this method of bookkeeping, a transaction recorded to one account results in an equal and opposite entry to another account. For example, a \$50 credit to one account results in a \$50 debit from another account. Transactions in Rafiki represent Interledger packet interactions, denominated in a given [asset](#assets). Packet interactions can be successful, fail, or be rejected. Rafiki's accounting layer processes the interactions and converts the activities into financial records, which are then written to your [accounting database](#accounting-databases). @@ -40,7 +40,7 @@ To convert an asset’s value into an amount that’s easier to interpret, apply $\frac{value}{10^{assetScale}}$ = _currencyAmount_ -Using the example data from the table above, the formula looks like this: +Using the example data from the preceding table, the formula looks like this: $\frac{10000}{10^2} =\$100.00 USD @@ -50,7 +50,7 @@ Rafiki uses a combination of liquidity and settlement accounts to track the amou ### Liquidity accounts -Liquidity accounts are used to track deposits, withdrawals, and transfers that occur during the course of a transaction. Liquidity accounts are provided for assets, peers, and payments. +Liquidity accounts track deposits, withdrawals, and transfers that occur during the course of a transaction. Rafiki provides liquidity accounts for assets, peers, and payments. Liquidity accounts hold either a zero or a positive balance. Rafiki ensures that the total debits to a liquidity account will not exceed the account's total credits. @@ -72,7 +72,7 @@ Asset liquidity ensures Rafiki has enough liquidity, denominated in a given asse An asset liquidity account represents the value that Rafiki has available for sending or forwarding ILP packets. You have one asset liquidity account for each asset you transact in. -Whenever an outgoing payment/incoming payment is in a different asset than the peering relationship, the liquidity of asset accounts will change depending on the FX direction. Any transaction that would result in a negative balance will fail. +Whenever an outgoing payment/incoming payment is in a different asset than the peering relationship, the liquidity of asset accounts change depending on the FX direction. Any transaction that would result in a negative balance will fail. :::note If you and your peer transact in the same asset (there's no currency conversion) and you both provide your customers only with wallet addresses denominated in that asset, then there will be no movement into/from the corresponding asset's liquidity account. @@ -128,7 +128,7 @@ The amount of credit that you extend to a peer, the asset that you transact in, A peering agreement is a legal contract between the parties involved in a peering relationship. It defines terms such as the assets involved and other operational details. It is not configured or managed within Rafiki but is necessary for establishing the terms under which assets are exchanged. ::: -If a peer’s liquidity is insufficient (e.g., they’ve used up their allotted credit line), payments will not be processed. Your peer should settle with you so that you can reset their liquidity. +If a peer’s liquidity is insufficient (for example, they’ve used up their allotted credit line), payments will not be processed. Your peer should settle with you so that you can reset their liquidity. You can add a liquidity threshold for each peer liquidity account via the [`updatePeer`](https://rafiki.dev/apis/graphql/backend/mutations/#updatepeer) mutation's `liquidityThreshold` input argument. @@ -158,7 +158,7 @@ Payment liquidity is the amount that's available because of an incoming or outgo ##### Incoming payment liquidity accounts -An incoming payment liquidity account represents the value received for an incoming payment. An incoming payment is created via Open Payments. When the first packet for the incoming payment is received, a corresponding liquidity account is automatically created. You will have one liquidity account per incoming payment. +An incoming payment liquidity account represents the value received for an incoming payment. Incoming payments are created via Open Payments. When the first packet for an incoming payment is received, a corresponding liquidity account is automatically created. You will have one liquidity account per incoming payment. You are notified of created, completed, and expired incoming payments by listening for the appropriate [webhook events](/integration/requirements/webhook-events/#incoming-payments). Since Rafiki doesn't hold funds, anything you receive must be withdrawn and then credited to the recipient's account on your ledger. @@ -180,7 +180,7 @@ A wallet address liquidity account contains the value received to a wallet addre Since Rafiki doesn’t hold funds, you must withdraw the liquidity when the payment completes and credit the funds to the recipient’s account on your ledger. You are notified to withdraw liquidity by listening for the appropriate [webhook event](/integration/requirements/webhook-events#wallet-addresses). -Unlike the incoming and outgoing payment liquidity accounts, the same wallet address liquidity account is used for future incoming SPSP payments. +Unlike the incoming and outgoing payment liquidity accounts, the same wallet address liquidity account will be used for future incoming SPSP payments. ### Settlement accounts @@ -218,7 +218,7 @@ You can choose to use a separate Postgres database for accounting instead of usi As with the accounts described above, Rafiki performs double-entry accounting for transfers, where increasing the total debits of one account increases the total credits of another account by the same amount, and vice versa. -Transfers can be completed in either a single phase or in two phases. +Transfers can complete in either a single phase or in two phases. ### Single-phase transfer diff --git a/packages/documentation/src/content/docs/overview/concepts/interledger.mdx b/packages/documentation/src/content/docs/overview/concepts/interledger.mdx index 8398fd2e7a..2bc4515251 100644 --- a/packages/documentation/src/content/docs/overview/concepts/interledger.mdx +++ b/packages/documentation/src/content/docs/overview/concepts/interledger.mdx @@ -4,7 +4,7 @@ title: Interledger import { LinkOut } from '@interledger/docs-design-system' -Building and maintaining your own connector to participate on the Interledger network can be a time consuming and complex undertaking. As a reference implementation of the Interledger stack, Rafiki gives you all the tools you need to quickly and easily join the network and enable Interledger functionality on your users’ accounts. +Building and maintaining your own connector to participate on the Interledger network can be a time consuming and complex undertaking. As a reference implementation of the Interledger stack, Rafiki gives you all the tools you need to quickly and easily join the network and enable Interledger capabilities on your users’ accounts. ## Packets @@ -12,15 +12,15 @@ At the core of Interledger is the Interledger Protocol (ILP). It’s a request/r These packets of data carry information about a payment. Typically, information about a single aggregate payment from sender to receiver is split into multiple ILP packets. -Each packet represents a conditional IOU which affects financial accounting balances between peers. Amounts are adjusted based on the sender's asset, the receiver's asset, and Rafiki's configured [exchange rates service](/integration/requirements/exchange-rates). Then, the amounts are used to update account liquidities in your accounting database (TigerBeetle or Postgres). +Each packet represents a conditional IOU which affects financial accounting balances between peers. Amounts adjust based on the sender's asset, the receiver's asset, and Rafiki's configured [exchange rates service](/integration/requirements/exchange-rates). Then, the amounts are used to update account liquidity in your accounting database (TigerBeetle or Postgres). ## Peers -Interledger itself is a network of computers that enables sending payment messages across payment networks. Each computer on the network is called a node. +Interledger itself is a network of computers that enables sending payment messages across payment networks. Each computer on the network is a node. -For two nodes on the Interledger network to exchange ILP packets with one another, the two nodes must be peers. There are a number of [requirements](/integration/requirements/peers#prerequisites) that both you and your potential peer must meet in order to form a peering relationship. +For two nodes on the Interledger network to exchange ILP packets with one another, the two nodes must be peers. There are a number of [requirements](/integration/requirements/peers#prerequisites) that both you and your potential peer must meet to form a peering relationship. -Since the purpose of peering is to facilitate payments, which often involves extending lines of credit, your peer should be someone you trust. We strongly recommend you and your potential peer define your expectations and outline your agreements in a legally-binding document peering with one another. +Since the purpose of peering is to facilitate payments, which often involves extending lines of credit, your peer should be someone you trust. We strongly recommend you and your potential peer define your expectations and outline your agreements in a legally binding document peering with one another. ## Connectors @@ -30,7 +30,7 @@ Each node on the Interledger network can take on the role of sender, connector, - Connector - An intermediary between a sender and receiver that forwards ILP packets. Connectors can facilitate payments to or from anyone they’re peered with. - Receiver - The final recipient of the ILP packets and, as such, the payment. -If the sender and receiver nodes are peers, then the payment flow is straightforward and no intermediary connector nodes are needed. However, if the sender and receiver aren’t peers, then the payment must be routed through one or more connectors. Rafiki’s [backend service](/integration/deployment/services/backend-service#interledger-connector) includes an Interledger connector for sending and receiving ILP packets. +If the sender and receiver nodes are peers, then the payment flow is straightforward and no intermediary connector nodes are needed. However, if the sender and receiver aren’t peers, then the payment must route through one or more connectors. Rafiki’s [backend service](/integration/deployment/services/backend-service#interledger-connector) includes an Interledger connector for sending and receiving ILP packets. In the image below, the sender node (A) and the receiver node (C) share a common peer (B). In payments from the sender to the receiver, node B performs the role of connector to facilitate payments between the two. @@ -46,7 +46,7 @@ In reality, there can be multiple connectors between a sender node and a receive Rafiki assigns each of your customers’ accounts with a payment pointer. Payment pointers are a type of wallet address for accounts within the Interledger network. They’re similar to email addresses in that they’re used to determine which account to send a payment from and which account to deliver the payment to. -Every payment pointer serves as a Simple Payment Setup Protocol (SPSP) endpoint and must resolve to an HTTPS URL. Payment pointers can be written out using the `$` shorthand (e.g., `$wallet.example.com/alice`) or as a URL (e.g., `https://wallet.example.com/alice`). +Every payment pointer serves as a Simple Payment Setup Protocol (SPSP) endpoint and must resolve to an HTTPS URL. Payment pointers can be written out using the `$` shorthand (for example, `$wallet.example.com/alice`) or as a URL (for example, `https://wallet.example.com/alice`). ## Simple Payment Setup Protocol (SPSP) @@ -68,4 +68,4 @@ A critical function of STREAM is to determine the path exchange rate and handle In a STREAM connection, a receipt can be generated by the party receiving funds for every fulfilled ILP packet. Each receipt contains a progressively higher amount, representing the total amount received over the STREAM connection. -Rafiki’s Interledger connector keeps track of the total amount received for a STREAM connection in Redis in order to support STREAM receipts. +Rafiki’s Interledger connector keeps track of the total amount received for a STREAM connection in Redis to support STREAM receipts. diff --git a/packages/documentation/src/content/docs/overview/concepts/open-payments.mdx b/packages/documentation/src/content/docs/overview/concepts/open-payments.mdx index 8a5d30539f..7fb6d9d2c0 100644 --- a/packages/documentation/src/content/docs/overview/concepts/open-payments.mdx +++ b/packages/documentation/src/content/docs/overview/concepts/open-payments.mdx @@ -14,7 +14,7 @@ Some of your customers use a third-party application that allows them to create ### Further reading -We strongly encourage you to familiarize yourself with the Open Payments standard. Extensive documentation can be found on the Open Payments website. We recommend you start by reviewing all the pages within the _Intro to Open Payments_ section. Here are a few links to get you started. +We strongly encourage you to familiarize yourself with the Open Payments standard. Extensive documentation is available on the Open Payments website. We recommend you start by reviewing all the pages within the _Intro to Open Payments_ section. Here are a few links to get you started. - Open Payments concepts diff --git a/packages/documentation/src/content/docs/overview/concepts/telemetry.mdx b/packages/documentation/src/content/docs/overview/concepts/telemetry.mdx index 82e04f3201..ae2f5a73be 100644 --- a/packages/documentation/src/content/docs/overview/concepts/telemetry.mdx +++ b/packages/documentation/src/content/docs/overview/concepts/telemetry.mdx @@ -20,9 +20,9 @@ Our goals are to: ### Privacy and optionality -Privacy is a paramount concern for the Interleger Foundation. Rafiki’s telemetry feature is designed to provide valuable network insights without violating privacy or aiding malicious ASEs. Review the [Privacy](#privacy) section below for more information. +Privacy is a paramount concern for the Interledger Foundation. Rafiki’s telemetry feature is designed to provide valuable network insights without violating privacy or aiding malicious ASEs. Review the [Privacy](#privacy) section below for more information. -The telemetry functionality is currently enabled by default on test (non-livenet) environments, i.e. any environment that is not dealing with real money. When active, the functionality transmits metrics to the testnet collector. You can opt in to sharing your metrics with a livenet collector when operating in a production livenet environment (with real money). Regardless of environment, you can also opt-out of telemetry completely. Review the [telemetry environment variables](#telemetry-environment-variables) for more information. +The telemetry feature is currently enabled by default on test environments (environments not dealing with real money). When active, the feature transmits metrics to the testnet collector. You can opt in to sharing your metrics with a livenet collector when operating in a production livenet environment (with real money). Regardless of environment, you can also opt-out of telemetry completely. Review the [telemetry environment variables](#telemetry-environment-variables) for more information. ### Architecture @@ -106,7 +106,7 @@ To handle outliers, a clipping technique is implemented, capping the buckets. An ### Laplacian distribution -The Laplacian distribution is often used in differential privacy due to its double exponential decay property. This property ensures that a small change in the data will not significantly affect the probability distribution of the output, providing a strong privacy guarantee. +The Laplacian distribution is often used in differential privacy due to its double exponential decay property. This property ensures that a small change in the data does not significantly affect the probability distribution of the output, providing a strong privacy guarantee. To achieve local differential privacy (LDP), noise is selected from the Laplacian distribution and added to the rounded values. The noise is generated based on a privacy parameter, which is calculated using the sensitivity of the function. @@ -114,7 +114,7 @@ The sensitivity of a function in differential privacy is the maximum amount that The privacy parameter is computed as one-tenth of the sensitivity. This parameter controls the trade-off between privacy and utility: a smaller privacy parameter means more privacy but less utility, and a larger privacy parameter means less privacy but more utility. -The noise, selected from the Laplacian distribution, is then generated using this privacy parameter and added to the rounded value. If the resulting value is zero, it is set to half the bucket size to ensure that the noise does not completely obscure the transaction value. +The noise, selected from the Laplacian distribution, is then generated using this privacy parameter and added to the rounded value. If the resulting value is zero, the value is set to half the bucket size to ensure that the noise does not completely obscure the transaction value. ### Currency conversion @@ -177,13 +177,13 @@ When the `ENABLE_TELEMETRY` variable is `true`, the following are required.
-| Variable name | Type | Description | -| -------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `ENABLE_TELEMETRY` | Boolean | Enables the telemetry service on Rafiki. Defaults to `true`. | -| `LIVENET` | Boolean | Determines where to send metrics. Defaults to `false`, resulting in metrics being sent to the testnet OTEL Collector.

Set to `true` on production environments dealing with real money.

| -| `OPEN_TELEMETRY_COLLECTOR_URLS` | String | A CSV of URLs for OTEL Collectors (e.g., `http://otel-collector-NLB-e3172ff9d2f4bc8a.elb.eu-west-2.amazonaws.com:4317,http://happy-life-otel-collector:4317`). | -| `OPEN_TELEMETRY_EXPORT_INTERVAL` | Number | Indicates, in milliseconds, how often the instrumented Rafiki instance should send metrics. Defaults to`15000`. | -| `TELEMETRY_EXCHANGE_RATES_URL` | String |

Defines the endpoint Rafiki will query for exchange rates. Used as a fallback if/when [exchange rates](/integration/requirements/exchange-rates) aren’t provided.

When set, the response format of the external exchange rates API should be of type `rates`, as is expected by the rate service.

Defaults to `https://telemetry-exchange-rates.s3.amazonaws.com/exchange-rates-usd.json`, which points to a public S3 that has the previously mentioned required format, updated daily.

| +| Variable name | Type | Description | +| -------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `ENABLE_TELEMETRY` | Boolean | Enables the telemetry service on Rafiki. Defaults to `true`. | +| `LIVENET` | Boolean | Determines where to send metrics. Defaults to `false`, resulting in metrics being sent to the testnet OTEL Collector.

Set to `true` on production environments dealing with real money.

| +| `OPEN_TELEMETRY_COLLECTOR_URLS` | String | A CSV of URLs for OTEL Collectors (e.g., `http://otel-collector-NLB-e3172ff9d2f4bc8a.elb.eu-west-2.amazonaws.com:4317,http://happy-life-otel-collector:4317`). | +| `OPEN_TELEMETRY_EXPORT_INTERVAL` | Number | Indicates, in milliseconds, how often the instrumented Rafiki instance should send metrics. Defaults to`15000`. | +| `TELEMETRY_EXCHANGE_RATES_URL` | String |

Defines the endpoint Rafiki queries for exchange rates. Used as a fallback if/when [exchange rates](/integration/requirements/exchange-rates) aren’t provided.

When set, the response format of the external exchange rates API should be of type `rates`, as is expected by the rate service.

Defaults to `https://telemetry-exchange-rates.s3.amazonaws.com/exchange-rates-usd.json`, which points to a public S3 that has the previously mentioned required format, updated daily.

|
@@ -191,7 +191,7 @@ When the `ENABLE_TELEMETRY` variable is `true`, the following are required. Below is an example of a Docker OTEL Collector image and configuration that integrates with Rafiki and sends data to a Prometheus remote write endpoint. -The configuration can be tested in our [Local Playground](/integration/playground/overview) by providing the environment variables in the table above to `happy-life-backend` in the `docker-compose.yml` file. +You can test the configuration in our [Local Playground](/integration/playground/overview) by providing the environment variables in the preceding table to `happy-life-backend` in the `docker-compose.yml` file. #### Docker Compose config @@ -215,7 +215,7 @@ happy-life-otel-collector: #### OTEL Collector config -Supplemental documentation can be found in OTEL’s Collector Configuration documentation. +Supplemental documentation is available in OTEL’s Collector Configuration documentation. ```yaml wrap # Serves as example for the configuration of a local OpenTelemetry Collector that sends metrics to an AWS Managed Prometheus Workspace diff --git a/packages/documentation/src/content/docs/resources/architecture.mdx b/packages/documentation/src/content/docs/resources/architecture.mdx index ab619f3b3d..f69bc80a95 100644 --- a/packages/documentation/src/content/docs/resources/architecture.mdx +++ b/packages/documentation/src/content/docs/resources/architecture.mdx @@ -4,7 +4,7 @@ title: Architecture import { LinkOut } from '@interledger/docs-design-system' -Rafiki is a collection of three services that run together. Each one can be scaled horizontally. +Rafiki is a collection of three services that run together. Each one can scale horizontally. - [Backend](/integration/deployment/services/backend-service) - The main service, responsible for handling business logic and external communication - [Auth](/integration/deployment/services/auth-service) - A reference implementation of an Open Payments authorization server, used for grant authorization and authentication diff --git a/packages/documentation/src/content/docs/resources/environment-variables.mdx b/packages/documentation/src/content/docs/resources/environment-variables.mdx index 1f2589c511..60b883f3af 100644 --- a/packages/documentation/src/content/docs/resources/environment-variables.mdx +++ b/packages/documentation/src/content/docs/resources/environment-variables.mdx @@ -8,7 +8,7 @@ import AuthEnv from '/src/partials/auth-variables.mdx' import FrontEnv from '/src/partials/frontend-variables.mdx' import VarWarn from '/src/partials/variables-warning.mdx' -Environment variables are key value pairs that are used to configure how your Rafiki instance will run within your infrastructure and integrate with your systems. +Environment variables are key value pairs used to configure how your Rafiki instance will run within your infrastructure and integrate with your systems. Each environment variable name is uppercase, followed by an equal sign and the value of the variable. @@ -20,7 +20,7 @@ WEBHOOKS_URL=http://my-business/webhooks -The environment variable in the example above specifies the HTTP endpoint at which you want your Rafiki instance to send you notifications of webhook events. +The environment variable in the preceding example specifies the HTTP endpoint at which you want your Rafiki instance to send you notifications of webhook events. To run Rafiki you must set the environment variables for the `backend`, `auth` and `frontend` services where listed as required below. diff --git a/packages/documentation/src/content/docs/resources/glossary.mdx b/packages/documentation/src/content/docs/resources/glossary.mdx index 4f70f0524c..f2315f4a38 100644 --- a/packages/documentation/src/content/docs/resources/glossary.mdx +++ b/packages/documentation/src/content/docs/resources/glossary.mdx @@ -12,7 +12,7 @@ An entity that provides and maintains a payment account for a payer and/or payee ## Auth service -A reference implementation of an Open Payments authorization server in Rafiki. The `auth` service manages grant authorization and authentication, allowing clients (e.g., third-party applications) to create payments and quotes. It issues access tokens and validates client access rights through communication with the resource server. +A reference implementation of an Open Payments authorization server in Rafiki. The `auth` service manages grant authorization and authentication, allowing clients (for example, third-party applications) to create payments and quotes. It issues access tokens and validates client access rights through communication with the resource server. ## Authorization server @@ -26,7 +26,7 @@ The core service in Rafiki responsible for managing business logic and external ## Client -An application or service, such as a mobile or web app, that interacts with the authorization server to obtain grants and access tokens. Clients use tokens to access resource servers and perform actions, such as retriving transaction history and setting up payments, on behalf of a user or system. +An application or service, such as a mobile or web app, that interacts with the authorization server to obtain grants and access tokens. Clients use tokens to access resource servers and perform actions, such as retrieving transaction history and setting up payments, on behalf of a user or system. ## Frontend service @@ -46,11 +46,11 @@ A system or service that stores and manages user identity information, authentic ## Incoming payment -An object created by the recipient’s ASE, on their resource server, that represents a payment being received. The object contains information about the incoming payment, such as the amount, currency, receiver’s wallet address, and payment status. It is used to track and manage payments that are expected to or have been received. +An object created by the recipient’s ASE, on their resource server, that represents a payment being received. The object contains information about the incoming payment, such as the amount, currency, receiver’s wallet address, and payment status. The object is used to track and manage payments that are expected to be or have been received. ## Interledger Protocol (ILP) -An open protocol stack designed to facilitate the transfer of value across different currencies, platforms, and payment networks. Rafiki is a reference implementation of the Interledger stack, allowing you to join the Interledger network and quickly enable Interledger functionality on your users’ accounts. For more information, refer to the Interledger specification. +An open protocol stack designed to facilitate the transfer of value across different currencies, platforms, and payment networks. Rafiki is a reference implementation of the Interledger stack, allowing you to join the Interledger network and quickly enable Interledger capabilities on your users’ accounts. For more information, refer to the Interledger specification. ## ILP packet @@ -66,11 +66,11 @@ An object created by the sender’s ASE, on their resource server, that represen ## Payment pointer -A type of wallet address that serves as an SPSP endpoint to facilitate sending and receiving ILP packets. Payment pointers can be written out using the `$` shorthand (e.g., `$wallet.example.com/alice`) or as a URL (e.g., `https://wallet.example.com/alice`). +A type of wallet address that serves as an SPSP endpoint to facilitate sending and receiving ILP packets. Payment pointers can be written out using the `$` shorthand (for example, `$wallet.example.com/alice`) or as a URL (for example, `https://wallet.example.com/alice`). ## Peer -A counterparty with whom you transact with over the Interledger network. Your Rafiki instance will hold liquidity accounts for each of your peers. +A counterparty with whom you transact with over the Interledger network. Your Rafiki instance holds liquidity accounts for each of your peers. ## Quote diff --git a/packages/documentation/src/content/docs/resources/releases.mdx b/packages/documentation/src/content/docs/resources/releases.mdx index da0f4ad50a..f64dadb9c9 100644 --- a/packages/documentation/src/content/docs/resources/releases.mdx +++ b/packages/documentation/src/content/docs/resources/releases.mdx @@ -10,7 +10,7 @@ Refer to the Rafiki releases Backend diff --git a/packages/documentation/src/content/docs/resources/webhook-event-types.mdx b/packages/documentation/src/content/docs/resources/webhook-event-types.mdx index 0bad323af4..163dd3c199 100644 --- a/packages/documentation/src/content/docs/resources/webhook-event-types.mdx +++ b/packages/documentation/src/content/docs/resources/webhook-event-types.mdx @@ -2,7 +2,7 @@ title: Webhook event types --- -Webhooks notify you of specific events that occur within your Rafiki instance allowing you to integrate Interledger payments with your system and business processes. For example, Rafiki will notify you when one of your account holders has received an Interledger payment, at which point you would credit their account on your ledger. +Webhooks notify you of specific events that occur within your Rafiki instance, allowing you to integrate Interledger payments with your system and business processes. For example, Rafiki can notify you when one of your account holders has received an Interledger payment, at which point you would credit their account on your ledger. The following is an enumeration of all of Rafiki's [webhook event](/integration/requirements/webhook-events) types along with their descriptions, which you must listen to and handle. @@ -10,7 +10,7 @@ The following is an enumeration of all of Rafiki's [webhook event](/integration/ | Value | Description | | -------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | -| [`incoming_payment.created`](/integration/requirements/webhook-events/#incoming-payment-created) | An incoming payment has been created. | +| [`incoming_payment.created`](/integration/requirements/webhook-events/#incoming-payment-created) | An incoming payment was created. | | [`incoming_payment.completed`](/integration/requirements/webhook-events/#incoming-payment-completed) | An incoming payment is complete and will not accept any additional incoming funds. | | [`incoming_payment.expired`](/integration/requirements/webhook-events/#incoming-payment-expired) | An incoming payment expired and will not accept any additional incoming funds. | | [`outgoing_payment.created`](/integration/requirements/webhook-events/#outgoing-payment-created) | An outgoing payment was created. |