Skip to content

Commit 440a5ba

Browse files
hajjimohajjimo
authored
docs: mi/654/amounts-assets (#675)
* docs: mi/654/amounts-assets * docs: mi/654/amounts-assets Draft of new amounts page. * docs: mi/654/amounts-assets * docs: mi/654/amounts-assets * docs: 654/amounts-assets * docs: mi/654/amounts-assets * docs: mi/654/amounts-assets * docs: mi/654/amounts-assets * fix: update pnpm-lock.yaml with LaTeX dependencies - Add katex, rehype-katex, and remark-math to pnpm lock file - Ensures CI/CD pipeline can install required dependencies - Resolves build failure in GitHub Actions * Delete docs/package-lock.json
1 parent 7d4527b commit 440a5ba

File tree

5 files changed

+240
-6
lines changed

5 files changed

+240
-6
lines changed

‎docs/astro.config.mjs‎

Lines changed: 12 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,10 +3,16 @@ import starlight from '@astrojs/starlight'
33
import starlightOpenAPI from 'starlight-openapi'
44
import starlightLinksValidator from 'starlight-links-validator'
55
import starlightFullViewMode from 'starlight-fullview-mode'
6+
import remarkMath from 'remark-math'
7+
import rehypeKatex from 'rehype-katex'
68

79
// https://astro.build/config
810
export default defineConfig({
911
site: 'https://openpayments.dev',
12+
markdown: {
13+
remarkPlugins: [remarkMath],
14+
rehypePlugins: [rehypeKatex]
15+
},
1016
integrations: [
1117
starlight({
1218
title: 'Open Payments',
@@ -30,7 +36,8 @@ export default defineConfig({
3036
customCss: [
3137
'./node_modules/@interledger/docs-design-system/src/styles/teal-theme.css',
3238
'./node_modules/@interledger/docs-design-system/src/styles/ilf-docs.css',
33-
'./src/styles/openpayments.css'
39+
'./src/styles/openpayments.css',
40+
'katex/dist/katex.min.css'
3441
],
3542
// defaultLocale: 'root',
3643
locales: {
@@ -114,6 +121,10 @@ export default defineConfig({
114121
translations: { es: 'Autorización' },
115122
link: '/concepts/auth/'
116123
},
124+
{
125+
label: 'Amounts',
126+
link: '/concepts/amounts/'
127+
},
117128
{
118129
label: 'Payment methods',
119130
translations: { es: 'Métodos de pago' },

‎docs/package.json‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,10 @@
1313
"@astrojs/starlight": "^0.34.7",
1414
"@interledger/docs-design-system": "^0.9.0",
1515
"astro": "5.11.1",
16+
"katex": "^0.16.22",
1617
"mermaid": "^11.8.1",
18+
"rehype-katex": "^7.0.1",
19+
"remark-math": "^6.0.0",
1720
"sharp": "^0.34.3",
1821
"shiki": "3.8.0",
1922
"starlight-fullview-mode": "^0.2.3",

‎docs/src/content/docs/concepts/amounts.mdx‎

Lines changed: 138 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,138 @@
1+
---
2+
title: Amounts
3+
parent: Concepts
4+
---
5+
6+
import {
7+
LinkOut,
8+
Tooltip,
9+
StylishHeader
10+
} from '@interledger/docs-design-system'
11+
import { Steps } from '@astrojs/starlight/components'
12+
13+
:::tip[Summary]
14+
Amounts in Open Payments define monetary values using asset codes and asset scales. They provide a standardized way to represent money across different currencies and payment scenarios.
15+
:::
16+
17+
Amounts represent monetary values and are fundamental to every Open Payments operation. Whether you're creating an incoming payment, requesting a quote, or tracking payment progress, every amount consists of three key components: a numerical `value`, an `assetCode`, and an `assetScale`. Understanding these components is crucial for building Open Payments applications.
18+
19+
## Values
20+
21+
To maximize precision and avoid rounding errors in financial calculations, Open Payments uses numerical data types without decimals to represent values. In the context of programming languages, this means that Open Payments uses unsigned 64-bit integers for monetary amounts instead of floating-point numbers.
22+
23+
An example of a value is the number 10000.
24+
25+
## Asset codes
26+
27+
Asset codes identify the type of currency or asset being used in a payment and should follow the <LinkOut href='https://en.wikipedia.org/wiki/ISO_4217'>ISO 4217</LinkOut> standard for currency representation.
28+
29+
An example of an ISO 4217 `assetCode` is `USD`, which represents the US Dollar.
30+
31+
## Asset scales
32+
33+
An asset scale tells you how many decimal places a currency uses. It's like specifying whether you're counting in dollars, cents, or smaller units.
34+
35+
Asset scales are numbers between 0 and 255 that indicate decimal precision.
36+
37+
In the case of `USD` with an `assetScale` of 2, the display amount of $100.00 is stored and represented as 10000 cents.
38+
39+
Thus, the conversion formula is:
40+
41+
$$\frac{\text{value}}{10^{\text{assetScale}}} = \text{display amount}$$
42+
43+
Using the preceding example, the formula looks like this:
44+
45+
$$\frac{10000}{10^2} = \frac{10000}{100} = \$100.00$$
46+
47+
### Examples by currency
48+
49+
<table style='width: auto; margin: 1;'>
50+
<thead>
51+
<tr>
52+
<th>Currency</th>
53+
<th>Asset Code</th>
54+
<th>Asset Scale</th>
55+
<th>Integer Amount</th>
56+
<th>Actual Value</th>
57+
</tr>
58+
</thead>
59+
<tbody>
60+
<tr>
61+
<td>US Dollar</td>
62+
<td>
63+
<code>USD</code>
64+
</td>
65+
<td>2</td>
66+
<td>10000</td>
67+
<td>$100.00</td>
68+
</tr>
69+
<tr>
70+
<td>Euro</td>
71+
<td>
72+
<code>EUR</code>
73+
</td>
74+
<td>2</td>
75+
<td>2550</td>
76+
<td>€25.50</td>
77+
</tr>
78+
<tr>
79+
<td>British Pound</td>
80+
<td>
81+
<code>GBP</code>
82+
</td>
83+
<td>2</td>
84+
<td>3250</td>
85+
<td>£32.50</td>
86+
</tr>
87+
<tr>
88+
<td>Japanese Yen</td>
89+
<td>
90+
<code>JPY</code>
91+
</td>
92+
<td>0</td>
93+
<td>1000</td>
94+
<td>¥1000</td>
95+
</tr>
96+
<tr>
97+
<td>Mexican Peso</td>
98+
<td>
99+
<code>MXN</code>
100+
</td>
101+
<td>2</td>
102+
<td>18500</td>
103+
<td>$185.00</td>
104+
</tr>
105+
<tr>
106+
<td>Jordanian Dinar</td>
107+
<td>
108+
<code>JOD</code>
109+
</td>
110+
<td>3</td>
111+
<td>1000</td>
112+
<td>د.ا1.000</td>
113+
</tr>
114+
<tr>
115+
<td>South African Rand</td>
116+
<td>
117+
<code>ZAR</code>
118+
</td>
119+
<td>2</td>
120+
<td>1500</td>
121+
<td>R15.00</td>
122+
</tr>
123+
</tbody>
124+
</table>
125+
126+
## Amounts in Open Payments
127+
128+
Using the three necessary components of `value`, `assetCode`, and `assetScale`, $100 USD would be represented in Open Payments using the following structure:
129+
130+
```json
131+
{
132+
"value": "10000",
133+
"assetCode": "USD",
134+
"assetScale": 2
135+
}
136+
```
137+
138+
This consistent structure enables multi-currency payments, precise calculations, and seamless integration between different <Tooltip content="Account servicing entity">ASEs</Tooltip>.

‎docs/src/content/docs/concepts/wallet-addresses.mdx‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,7 @@ curl --request GET \
2626
--header 'accept: application/json'
2727
```
2828

29-
If the URL is a wallet address, the response will provide details about the underlying Open Payments-enabled account, including the URL of the grant request endpoint (the `authServer`). The grant request endpoint is used to get access tokens to connect to the account via the Open Payments APIs.
29+
If the URL is a wallet address, the response will provide details about the underlying Open Payments-enabled account.
3030

3131
```http
3232
HTTP/1.1 200 Success
@@ -37,10 +37,13 @@ Content-Type: application/json
3737
"publicName": "Alice",
3838
"assetCode": "USD",
3939
"assetScale": 2,
40-
"authServer": "https://auth.wallet.example.com"
40+
"authServer": "https://auth.wallet.example.com",
41+
"resourceServer": "https://wallet.example.com/op"
4142
}
4243
```
4344

45+
Each wallet address supports a single asset code and scale, but Open Payments enables multi-currency transactions. For example, while Alice's wallet details above returns `USD` as the `assetCode`, a sender can initiate payments to Alice in `EUR` or other currencies. The receiving wallet address provider handles currency conversion, so Alice will always receive `USD` at that specific wallet address. For details about how amounts work in Open Payments, refer to the [Amounts](/concepts/amounts) page.
46+
4447
## Wallet address server
4548

4649
When setting up a payment, the client must obtain the wallet address for both the sender and the recipient. Since the sender is typically the client's user, the client can obtain the sender's wallet address during an onboarding process, for example. The sender must be authenticated by their account servicing entity (ASE) to grant the client the permission it needs to access their Open Payments-enabled account.

‎pnpm-lock.yaml‎

Lines changed: 82 additions & 3 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

0 commit comments

Comments
 (0)