@le-space/chains 0.5.0 → 0.5.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@le-space/chains",
3
- "version": "0.5.0",
3
+ "version": "0.5.1",
4
4
  "description": "Own wallets on public chains, read only, by their address – Cosmos (Nyx, Akash), EVM (Blockscout, Alchemy), Bitcoin (Esplora, zpub), Filecoin (Filfox), NEAR (NearBlocks), Aleph Cloud credits – as @le-space/ledger entries. Browser and Node; fetch, endpoints and keys handed in.",
5
5
  "license": "AGPL-3.0-or-later",
6
6
  "type": "module",
@@ -57,8 +57,8 @@
57
57
  "@noble/hashes": "2.4.0",
58
58
  "@scure/base": "2.4.0",
59
59
  "@scure/bip32": "2.4.0",
60
- "@le-space/rates": "^0.3.0",
61
- "@le-space/ledger": "^0.3.0"
60
+ "@le-space/ledger": "^0.3.0",
61
+ "@le-space/rates": "^0.4.0"
62
62
  },
63
63
  "devDependencies": {
64
64
  "prettier": "3.6.2",
package/src/aleph.js CHANGED
@@ -10,9 +10,11 @@
10
10
  // seconds, inclusive
11
11
  // GET /api/v0/addresses/<a>/credit_history/summary net, in and out of a window
12
12
  //
13
- // A row with a positive amount brings credits in: a purchase (with its
14
- // per-credit `price` in USD, token, chain and transaction hash) or a transfer
15
- // from another account. A negative one takes them out: `credit_expense` is
13
+ // A row with a positive amount brings credits in: a purchase (with the
14
+ // payment token, the chain, the transaction hash and a `price` – units of the
15
+ // payment token per credit paid for, NOT US dollars; what it is worth in
16
+ // dollars is @le-space/rates' rule, aleph-credits.js `alephPurchase`) or a
17
+ // transfer from another account. `amount` includes the bonus (`bonus_amount`). A negative one takes them out: `credit_expense` is
16
18
  // consumption, billed about hourly per kind of resource (`origin_ref`:
17
19
  // `storage`, `execution`, …) with the number of resources and their size;
18
20
  // anything else is a transfer out. Storage is billed as one line for all
@@ -27,8 +29,8 @@
27
29
  // and need no history before the month.
28
30
  //
29
31
  // Euro value (a choice for the tax adviser, documented on the statement):
30
- // credits are priced in USD; a day's consumption is valued at the per-credit
31
- // price of the last purchase on or before that day, or Aleph's list price of
32
+ // credits are priced in USD; a day's consumption is valued at what a credit
33
+ // cost in the last purchase on or before that day, or Aleph's list price of
32
34
  // 1 USD per 1,000,000 credits when the account never bought any (credits
33
35
  // moved in from another account), then converted at that day's ECB
34
36
  // reference rate – the rule is @le-space/rates' (aleph-credits.js).
@@ -54,6 +56,7 @@ import {
54
56
  ALEPH_LIST_PRICE_USD,
55
57
  alephCreditPrice,
56
58
  alephCreditsInEur,
59
+ alephPurchase,
57
60
  plain
58
61
  } from '@le-space/rates/aleph-credits';
59
62
  import { createJsonFetcher, WalletError } from './http.js';
@@ -86,11 +89,15 @@ export function monthWindow(month) {
86
89
  /**
87
90
  * @typedef {object} TopUp
88
91
  * @property {string} time ISO
89
- * @property {number} credits
90
- * @property {number} bonus credits given on top
92
+ * @property {number} credits the credits that came in, a bonus included
93
+ * @property {number} bonus of them, the credits given on top
91
94
  * @property {'purchase' | 'transfer'} how
92
- * @property {string | null} price USD per credit, a purchase's
95
+ * @property {string | null} price a purchase's: units of the payment token per credit paid for (not USD)
93
96
  * @property {string | null} token
97
+ * @property {string | null} tokenAmount a purchase's: what was paid, in the token
98
+ * @property {string | null} usd a purchase's: what was paid, in US dollars (rates' alephPurchase)
99
+ * @property {string | null} usdPerCredit a purchase's: dollars per credit that came in
100
+ * @property {'price' | 'list' | null} priceBasis whether the dollars are the row's price or Aleph's list price
94
101
  * @property {string | null} chain
95
102
  * @property {string | null} txHash the paying transaction
96
103
  * @property {string} from for a transfer, the account it came from ('' when not said)
@@ -111,6 +118,17 @@ export function monthWindow(month) {
111
118
  * @property {number | null} eurCents
112
119
  */
113
120
 
121
+ /** A history row's purchase, in dollars. @param {any} r */
122
+ const purchaseOf = (r) =>
123
+ r?.price
124
+ ? alephPurchase({
125
+ credits: num(r.amount),
126
+ bonus: num(r.bonus_amount) || 0,
127
+ price: String(r.price),
128
+ token: r.token ? String(r.token) : null
129
+ })
130
+ : null;
131
+
114
132
  /**
115
133
  * The rows of one month → the statement's lines. Pure.
116
134
  *
@@ -126,7 +144,10 @@ export function summarise({ rows, purchases }) {
126
144
  /** @type {Map<string, UsageLine>} */
127
145
  const days = new Map();
128
146
  const priceOn = alephCreditPrice(
129
- purchases.map((p) => ({ time: String(p?.message_timestamp), price: p?.price }))
147
+ purchases.map((p) => ({
148
+ time: String(p?.message_timestamp),
149
+ usdPerCredit: purchaseOf(p)?.usdPerCredit ?? null
150
+ }))
130
151
  );
131
152
 
132
153
  for (const r of rows) {
@@ -135,6 +156,7 @@ export function summarise({ rows, purchases }) {
135
156
  if (!Number.isFinite(amount) || amount === 0) continue;
136
157
  if (amount > 0) {
137
158
  const purchase = Boolean(r.price || r.tx_hash);
159
+ const worth = purchaseOf(r);
138
160
  topUps.push({
139
161
  time,
140
162
  credits: amount,
@@ -142,6 +164,10 @@ export function summarise({ rows, purchases }) {
142
164
  how: purchase ? 'purchase' : 'transfer',
143
165
  price: r.price ? String(r.price) : null,
144
166
  token: r.token ? String(r.token) : null,
167
+ tokenAmount: worth?.tokenAmount ?? null,
168
+ usd: worth?.usd ?? null,
169
+ usdPerCredit: worth?.usdPerCredit ?? null,
170
+ priceBasis: worth?.basis ?? null,
145
171
  chain: r.chain ? String(r.chain) : null,
146
172
  txHash: r.tx_hash ? String(r.tx_hash) : null,
147
173
  from: purchase ? '' : String(r.origin ?? '')
@@ -314,7 +340,10 @@ export function createAlephClient({
314
340
  .map((r) => ({
315
341
  time: new Date(String(r.message_timestamp)).toISOString(),
316
342
  credits: num(r.amount),
343
+ // Units of the payment token per credit paid for – not USD (rates' alephPurchase).
317
344
  price: String(r.price),
345
+ usd: purchaseOf(r)?.usd ?? null,
346
+ tokenAmount: purchaseOf(r)?.tokenAmount ?? null,
318
347
  token: r.token ? String(r.token) : null,
319
348
  chain: r.chain ? String(r.chain) : null,
320
349
  txHash: String(r.tx_hash)
@@ -428,8 +457,8 @@ export function alephEntries(statement) {
428
457
  ? `Aleph Cloud (Kauf${t.token ? ` mit ${t.token}` : ''}${t.chain ? ` auf ${t.chain}` : ''})`
429
458
  : '',
430
459
  explorerUrl,
431
- ...(t.price
432
- ? { unitPrice: { currency: 'USD', amount: plain(t.price), source: 'purchase' } }
460
+ ...(t.usdPerCredit
461
+ ? { unitPrice: { currency: 'USD', amount: plain(t.usdPerCredit), source: 'purchase' } }
433
462
  : {})
434
463
  })
435
464
  ),
@@ -487,13 +516,23 @@ export const PURCHASE_EXPLORERS = /** @type {Record<string, import('./explorer.j
487
516
  }
488
517
  });
489
518
 
519
+ /** Aleph's names for a chain → the key in PURCHASE_EXPLORERS. The API says `ethereum`, older rows `ETH`. */
520
+ const CHAIN_CODES = /** @type {Record<string, string>} */ ({
521
+ ETH: 'ETH',
522
+ ETHEREUM: 'ETH',
523
+ BASE: 'BASE'
524
+ });
525
+
490
526
  /**
491
527
  * The payments behind a month's credit purchases: one `sent` entry per
492
- * purchase, in USD (credits × the purchase's USD price per credit), of kind
493
- * `swap` – a token for credits; the ledger has no `purchase` kind. The token
494
- * amount paid is not in Aleph's data; it is checked through the paying
495
- * transaction's hash, whose explorer link is on the chain it was paid on
496
- * (Ethereum or Base), else Aleph's explorer page of the account. The credits
528
+ * purchase, in USD, of kind `swap` – a token for credits; the ledger has no
529
+ * `purchase` kind. The dollars are what the credits paid for cost (rates'
530
+ * alephPurchase): the row's price for a purchase in a dollar token, Aleph's
531
+ * list price for one in ALEPH – never the row's `price` taken for dollars,
532
+ * which for ALEPH is a token amount. The memo names the tokens paid; they are
533
+ * checked through the paying transaction's hash, whose explorer link is on
534
+ * the chain it was paid on (Ethereum or Base), else Aleph's explorer page of
535
+ * the account. The credits
497
536
  * bought stay the `received` row of `alephEntries`, with the same hash, so an
498
537
  * Eigenbeleg shows both sides.
499
538
  *
@@ -504,9 +543,13 @@ export const PURCHASE_EXPLORERS = /** @type {Record<string, import('./explorer.j
504
543
  export function purchaseEntries(statement, { explorers = PURCHASE_EXPLORERS } = {}) {
505
544
  const { address, topUps } = statement;
506
545
  return topUps
507
- .filter((t) => t.how === 'purchase' && t.price)
546
+ .filter((t) => t.how === 'purchase' && t.usd)
508
547
  .map((t, i) => {
509
- const explorer = t.chain ? explorers[t.chain.toUpperCase()] : undefined;
548
+ const code = t.chain ? (CHAIN_CODES[t.chain.toUpperCase()] ?? t.chain.toUpperCase()) : '';
549
+ const explorer = code ? explorers[code] : undefined;
550
+ const paidFor = credits(t.credits - (t.bonus > 0 && t.bonus < t.credits ? t.bonus : 0));
551
+ const perCredit =
552
+ t.priceBasis === 'price' ? plain(/** @type {string} */ (t.price)) : LIST_PRICE_USD;
510
553
  return entry({
511
554
  id: `aleph:${address}:purchase:${t.time}:${i}`,
512
555
  chain: 'aleph',
@@ -520,11 +563,16 @@ export function purchaseEntries(statement, { explorers = PURCHASE_EXPLORERS } =
520
563
  asset: 'USD',
521
564
  contract: 'native',
522
565
  decimals: 6,
523
- amount: `-${normalize(multiply(credits(t.credits), /** @type {string} */ (t.price), 8))}`,
566
+ amount: `-${normalize(/** @type {string} */ (t.usd))}`,
524
567
  counterparty: 'aleph',
525
568
  method: '',
526
569
  counterpartyLabel: `Aleph Cloud (Kauf von ${credits(t.credits)} Credits${t.token ? ` mit ${t.token}` : ''}${t.chain ? ` auf ${t.chain}` : ''})`,
527
- memo: `${credits(t.credits)} Credits × ${t.price} USD`,
570
+ memo:
571
+ `${paidFor} Credits × ${perCredit} USD` +
572
+ (t.bonus > 0 && t.bonus < t.credits ? ` (+ ${credits(t.bonus)} Bonus)` : '') +
573
+ (t.tokenAmount && t.token && t.priceBasis === 'list'
574
+ ? `; bezahlt mit ${t.tokenAmount} ${t.token}`
575
+ : ''),
528
576
  success: true,
529
577
  explorerUrl:
530
578
  explorer && t.txHash ? txUrl(explorer, t.txHash) : `${ALEPH_EXPLORER}${address}`,
@@ -7,7 +7,8 @@
7
7
  * @typedef {object} Row
8
8
  * @property {string} at ISO
9
9
  * @property {number} amount credits; negative leaves
10
- * @property {string} [price] USD per credit, a purchase's
10
+ * @property {string} [price] a purchase's: units of the payment token per credit paid for
11
+ * @property {number} [bonus] of `amount`, the credits given on top
11
12
  * @property {string} [txHash]
12
13
  * @property {string} [token]
13
14
  * @property {string} [chain]
@@ -66,6 +67,7 @@ export function alephFetch({ accounts, messages = {} }) {
66
67
  message_timestamp: r.at,
67
68
  amount: r.amount,
68
69
  price: r.price ?? null,
70
+ bonus_amount: r.bonus ?? null,
69
71
  tx_hash: r.txHash ?? null,
70
72
  token: r.token ?? null,
71
73
  chain: r.chain ?? null,
@@ -1,6 +1,8 @@
1
1
  // SPDX-License-Identifier: AGPL-3.0-or-later
2
2
  // A made-up Aleph account and month for the tests (Node and browser): a
3
- // purchase before August at 0.000002 USD per credit, then storage, an
3
+ // purchase before August paid in ALEPH – 1,200,000 credits came in, 200,000
4
+ // of them the bonus, at 0.00008 ALEPH per credit paid for, so 80 ALEPH for
5
+ // 1 USD of credits at the list price – then storage, an
4
6
  // instance, a transfer in and one out, and a line in September.
5
7
 
6
8
  export const ACCOUNT = `0x${'a1'.repeat(20)}`;
@@ -13,11 +15,13 @@ export function sampleRows() {
13
15
  return [
14
16
  {
15
17
  at: '2026-07-20T08:00:00.000Z',
16
- amount: 1_000_000,
17
- price: '0.000002',
18
+ amount: 1_200_000,
19
+ bonus: 200_000,
20
+ // Units of ALEPH per credit paid for – not dollars, as Aleph's API has it.
21
+ price: '0.00008',
18
22
  txHash: `0x${'ab'.repeat(32)}`,
19
23
  token: 'ALEPH',
20
- chain: 'ETH'
24
+ chain: 'ethereum'
21
25
  },
22
26
  {
23
27
  at: '2026-08-01T00:30:00.000Z',
@@ -60,8 +64,8 @@ export function sampleRows() {
60
64
  ];
61
65
  }
62
66
 
63
- /** Balance now: 2,000,000 before July, then every row. */
64
- export const sampleBalance = () => 2_000_000 + sampleRows().reduce((n, r) => n + r.amount, 0);
67
+ /** Balance now: 1,800,000 before July, then every row. */
68
+ export const sampleBalance = () => 1_800_000 + sampleRows().reduce((n, r) => n + r.amount, 0);
65
69
 
66
70
  /** EUR per USD, the same every day. */
67
71
  export const flatUsd = {