Skip to content

Commit

Permalink
chore: resolving conflicts
Browse files Browse the repository at this point in the history
  • Loading branch information
@JoblersTune
JoblersTune committed Sep 9, 2024
1 parent a9a4fa9 commit 8f6a6e7
Showing 1 changed file with 23 additions and 39 deletions.
62 changes: 23 additions & 39 deletions ...es/documentation/src/content/docs/integration/requirements/wallet-addresses.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,10 +5,6 @@ title: Wallet addresses
import { LinkOut } from '@interledger/docs-design-system'
import { CodeBlock } from '@interledger/docs-design-system'

:::danger
Creating key pairs is more of an optional thing than anything. It can stay a part of this doc but it should be its own section. The section should reference the open payments docs somewhere. The key pairs are only needed if the ASE wants to allow their users to use/be OP clients under their wallet addresses.
:::

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.

:::note
Expand All @@ -23,15 +19,11 @@ There are a few ways in which you can create wallet addresses.
- [In response to the `wallet_address.not_found` webhook event](#create-wallet-addresses-in-response-to-a-webhook-event)
- [In the Rafiki Admin app](#create-and-manage-wallet-addresses-using-rafiki-admin)

All wallet addresses must also be associated with at least one [public-private key pair](#create-a-wallet-address-key-pair) to sign API requests. If you use Rafiki Admin to create wallet addresses, this happens automatically.

### Create wallet addresses through a script

Writing your own script that loops through your list of account is one way to batch create wallet addresses for your existing account holders.

Your script must first call the `createWalletAddress` GraphQL mutation, then call the [`createWalletAddressKey`](#create-a-wallet-address-key-pair) mutation for each new wallet address.

We strongly recommend you store at least the `walletAddress.id` in your internal database to be able to reference the account and wallet address later.
Ensure your script calls the `createWalletAddress` GraphQL mutation.

<CodeBlock title="createWalletAddress mutation">

Expand All @@ -58,7 +50,9 @@ mutation CreateWalletAddress($input: CreateWalletAddressInput!) {

</CodeBlock>

### Example
We strongly recommend you store at least the `walletAddress.id` in your internal database to be able to reference the account and wallet address later.

#### Example

<CodeBlock title="Example JSON request">

Expand Down Expand Up @@ -122,17 +116,23 @@ mutation CreateWalletAddress($input: CreateWalletAddressInput!) {

### Create wallet addresses in response to a webhook event

The `wallet_address.not_found` event fires when a wallet address is requested through the Open Payments Get Wallet Address API, but Rafiki can't find the address.
The [`wallet_address.not_found`](/integration/requirements/webhook-events#wallet-address-not-found) event fires when a wallet address is requested through the Open Payments Get Wallet Address API, but Rafiki can't find the address.

When you receive the event, look up the associated account in your system, then call the `createWalletAddress` and `createWalletAddressKey` mutations to create the address and its public-private key pair.
When you receive the event, look up the associated account in your system, then call the `createWalletAddress` mutation to create a wallet address for the account.

---
The mutation and example JSON request/response is the same as what's given [above](#create-wallet-addresses-through-a-script).

### Create and manage wallet addresses using Rafiki Admin

You can create and manage wallet addresses manually through the [Rafiki Admin](/admin/admin-user-guide#create-wallet-address) app.

## Create a wallet address key pair

A wallet address must be associated with at least one public-private key pair to sign Open Payment API requests. The public key enables clients, such as mobile apps, to verify request signatures.
Creating a public-private key pair for each wallet address is not required when integrating with Rafiki.

You only need to create key pairs for wallet addresses if you want to allow your account holders to use/be Open Payments clients under their wallet addresses. For more information, review the Open Payments documentation about <LinkOut href="https://openpayments.dev/resources/glossary/#client">clients</LinkOut> and <LinkOut href="https://openpayments.dev/introduction/client-keys/">client keys</LinkOut>.

Add a key pair to a wallet address using the `createWalletAddressKey` GraphQL mutation.
Use the `createWalletAddressKey` GraphQL mutation to create a key pair and associate it with a wallet address.

<CodeBlock title='createWalletAddressKey mutation'>

Expand Down Expand Up @@ -182,29 +182,17 @@ mutation CreateWalletAddressKey($input: CreateWalletAddressKeyInput!) {

</CodeBlock>

A JSON web key is a JSON data structure that represents a cryptographic key.
The request is a standard request to create a JSON Web Key (JWK), which is a JSON data structure that represents a cryptographic key. <LinkOut href='https://datatracker.ietf.org/doc/html/rfc7517#section-4'>Section 4</LinkOut> of the JWK specification describes the format and associated parameters `kty`, `alg`, and `kid`. <LinkOut href='https://datatracker.ietf.org/doc/html/rfc7518#section-6'>Section 6</LinkOut> of the JSON Web Algorithms (JWA) specification describes the cryptographic algorithm for the keys and associated parameters `kty`, `crv`, and `x`.

In <LinkOut href='https://datatracker.ietf.org/doc/html/rfc7517#section-4'>
Section 4
Open Payments <LinkOut href="https://openpayments.dev/apis/wallet-address-server/operations/get-wallet-address-keys/">requires</LinkOut> the following values.

</LinkOut> of the JSON Web Key (JWK) specification describes the JWK format and associated
parameters (kty, alg, kid).
| Parameter | Required value | Description |
| --------- | -------------- | ----------------------------------------------------------------------------- |
| `alg` | `EdDSA` | The algorithm used to generate the key pair |
| `kty` | `OKP` | The key type identifying the cryptographic algorithm family used with the key |
| `crv` | `Ed25519` | The cryptographic curve used with the key |

In <LinkOut href='https://datatracker.ietf.org/doc/html/rfc7518#section-6'>
Section 6

</LinkOut> of the JSON Web Algorithms (JWA) specification describes the cryptographic
algorithm for keys (incl parameters kty, crv, x)

| Variable | Description |
| ----------------- | -------------------------------------------- |
| `jwk` | JSON web key object that represents the keys |
| `kid` | A key ID that identifies the keys |
| `x` | The base64 url-encoded public key |
| `alg` | The algorithm used to generate the key pair |
| `kty` | . |
| `crv` | . |
| `walletAddressId` | . |
Additionally, the request must contain the `walletAddressId` of the wallet address that the key pair will be associated with.

<CodeBlock title='Example JSON response'>

Expand Down Expand Up @@ -234,7 +222,3 @@ algorithm for keys (incl parameters kty, crv, x)
```

</CodeBlock>

## Create and manage wallet addresses using Rafiki Admin

You can create and manage wallet addresses manually through the [Rafiki Admin](/admin/admin-user-guide#create-wallet-address) app. If you use Rafiki Admin to create wallet addresses, it will assign each address a public-private key pair automatically.

0 comments on commit 8f6a6e7

Please sign in to comment.