docs: update README, add notes about submodule

.changeset/chilly-frogs-yawn.md

@@ -0,0 +1,5 @@
+---
+'@interledger/open-payments': patch
+---
+
+Update README

README.md

@@ -15,26 +15,19 @@ Open Payments is an open API standard that can be implemented by account servici
 - Subscriptions
 - Invoice Payments
 
-An Open Payments server runs two sub-systems, a **resource server** which exposes APIs for performing functions against the
-underlying accounts and and **authorisation server** which exposes APIs compliant with the
-[GNAP](https://datatracker.ietf.org/doc/html/draft-ietf-gnap-core-protocol) standard for getting grants to access the resource server
-APIs.
+The Open Payments APIs are a collection of three sub-systems:
 
-This repository hosts the Open API Specifications of the two APIs which are published along with additional documentation at
-https://openpayments.dev.
+- A **wallet address server** which exposes public information about Open Payments-enabled accounts called "wallet addresses"
+- A **resource server** which exposes APIs for performing functions against the underlying accounts
+- A **authorisation server** which exposes APIs compliant with the [GNAP](https://datatracker.ietf.org/doc/html/draft-ietf-gnap-core-protocol) standard for getting grants to access the resource server APIs
 
-Additionally, this repository also contains three published libraries:
+This repository contains contains a [NodeJS Open Payments SDK](https://github.com/interledger/open-payments-node/tree/main/packages/open-payments) to make requests via the Open Payments API, as well as TypeScript types for the API.
+
+It also contains two additional libraries:
 
-- [`@interledger/open-payments`](https://github.com/interledger/open-payments/tree/main/packages/open-payments) contains a NodeJS Open Payments SDK to make requests via the Open Payments API, as well as TypeScript types for the API.
 - [`@interledger/http-signature-utils`](https://github.com/interledger/open-payments/tree/main/packages/http-signature-utils) provides tools for working with [HTTP Message Signatures](https://datatracker.ietf.org/doc/draft-ietf-httpbis-message-signatures).
 - [`@interledger/openapi`](https://github.com/interledger/open-payments/tree/main/packages/openapi) exposes functionality to validate requests and responses according to a given OpenAPI 3.1 schema.
 
-The code for the landing [page](https://openpayments.dev) is in `./docs`.
-
-## Dependencies
-
-- [Interledger](https://interledger.org/developers/rfcs/interledger-protocol/)
-
 ### New to Interledger?
 
 Never heard of Interledger before? Or would you like to learn more? Here are some excellent places to start:
@@ -63,6 +56,19 @@ More phone numbers: https://tel.meet/htd-eefo-ovn?hs=5
 
 ## Local Development Environment
 
+This repository contains a Git submodule, which contains the Open Payments OpenAPI specifications.
+After cloning, make sure to initialize and update it:
+
+```bash
+git submodule update --init
+```
+
+Alternatively, clone the repository with submodules in one step:
+
+```bash
+git clone --recurse-submodules [email protected]:interledger/open-payments-node.git
+```
+
 ### Prerequisites
 
 - [NVM](https://github.com/nvm-sh/nvm)
@@ -83,14 +89,6 @@ pnpm clean
 pnpm i
 ```
 
-### Local Development
-
-You can preview the docs by running the command
-
-```sh
-pnpm --filter openpayments-docs start
-```
-
 ### Useful commands
 
 ```sh

packages/open-payments/README.md

@@ -2,7 +2,7 @@
 
 [Open Payments](https://openpayments.dev/) is an API standard that allows third-parties (with the account holder's consent) to initiate payments and to view the transaction history on the account holder's account.
 
-Open Payments consists of two OpenAPI specifications, a **resource server** which exposes APIs for performing functions against the underlying accounts and an **authorization server** which exposes APIs compliant with the [GNAP](https://openpayments.dev/introduction/grants/) standard for getting grants to access the resource server APIs.
+Open Payments consists of three OpenAPI specifications, a **wallet address server** which exposes public information about Open Payments-enabled accounts called "wallet addresses", a **resource server** which exposes APIs for performing functions against the underlying accounts and an **authorization server** which exposes APIs compliant with the [GNAP](https://openpayments.dev/introduction/grants/) standard for getting grants to access the resource server APIs.
 
 This package provides TypeScript & NodeJS tools for using Open Payments:
 
@@ -119,7 +119,7 @@ try {
 
 > **Note**
 >
-> A high level Open Payments flow with diagrams can be found [here](https://openpayments.dev/introduction/op-flow/).
+> A high level Open Payments flow with diagrams can be found [here](https://openpayments.dev/concepts/op-flow/).
 
 As mentioned previously, Open Payments APIs can facilitate a payment between two parties.
 
@@ -166,7 +166,7 @@ const incomingPaymentGrant = await client.grant.request(
       access: [
         {
           type: 'incoming-payment',
-          actions: ['read-all', 'create']
+          actions: ['read', 'create']
         }
       ]
     }
@@ -233,7 +233,7 @@ const quote = await client.quote.create(
 
 5. Create `OutgoingPayment` grant & start interaction flow:
 
-The final step for Online Marketplace's backend system will be to create an `OutgoingPayment` on Alice's wallet. Before this, however, Online Marketplace will need to create an outgoing payment grant, which typically requires some sort of interaction with Alice. Online Marketplace will need to facilitate this interaction with Alice (e.g. redirect her to a webpage with a dialog) to get her consent for creating an `OutgoingPayment` on her account at Cloud Nine Wallet.
+The final step for Online Marketplace's backend system will be to create an `OutgoingPayment` on Alice's wallet. Before this, however, Online Marketplace will need to create an outgoing payment grant, which requires an interaction with Alice. Online Marketplace will need to facilitate this interaction with Alice (e.g. redirect her to a webpage with a dialog) to get her consent for creating an `OutgoingPayment` on her account at Cloud Nine Wallet. Online Marketplace's backend system will provide a `nonce` in the request in order to secure the communication between itself and Alice's authorization server. See [hash verification](https://openpayments.dev/identity/hash-verification/) for more details.
 
 ```ts
 const outgoingPaymentGrant = await client.grant.request(
@@ -280,7 +280,7 @@ This request will return a response as such:
 }
 ```
 
-Alice would be then redirected to the URL specified at `interact.redirect`, where she can approve or reject the grant request.
+Alice would be then redirected to her [Identity Provider](https://openpayments.dev/identity/idp/) at the URL specified in `interact.redirect`, where she can approve or reject the grant request.
 
 > **Note**
 >

packages/open-payments/package.json

@@ -8,7 +8,7 @@
     "url": "https://github.com/interledger/open-payments.git",
     "directory": "packages/open-payments"
   },
-  "homepage": "https://github.com/interledger/open-payments/tree/main/packages/open-payments#readme",
+  "homepage": "https://github.com/interledger/open-payments-node/tree/main/packages/open-payments#readme",
   "publishConfig": {
     "access": "public"
   },