@le-space/chains 0.4.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/README.md CHANGED
@@ -4,24 +4,27 @@ Own wallets on public chains, read only, by their address – for [Belege](https
4
4
 
5
5
  Runs in a browser and in Node. The caller hands in `fetch`, the endpoints (a node, an indexer, a proxy) and the keys (an Alchemy key, a NearBlocks key, a Bitcoin zpub/xpub); nothing is read from disk, a keychain or the environment. A browser can read the keyless chains itself where the source allows CORS (or behind a proxy).
6
6
 
7
- | Chain | Source | Module |
8
- | --- | --- | --- |
9
- | Nym (Nyx), Akash (Cosmos SDK) | CometBFT RPC + REST; Akash's older history from the Akash Console indexer; Akash deployments | `cosmos`, `akash-console`, `akash-deployments`, `bech32`, `protobuf` |
10
- | Akash as `LedgerEntry` (`readAkash`, `statementAkash`: the fee to the network, escrow its own kind) | the Cosmos reader and the Akash Console indexer | `akash` |
11
- | Ethereum, Base, Arbitrum One, OP Mainnet, Polygon PoS (USDC listed; ALEPH on Ethereum and Base) | Blockscout, or Alchemy with a key; `evmReader(chain)` gives `LedgerEntry` through Alchemy (the key handed to each read) | `evm`, `alchemy` |
12
- | Bitcoin | Esplora; addresses derived from a zpub/ypub/xpub | `bitcoin` |
13
- | Filecoin | Filfox; `readFilecoin`/`statementFilecoin` give `LedgerEntry` | `filecoin` |
14
- | NEAR | NearBlocks + an archival RPC (from Eigenbeleg); gives `LedgerEntry` | `near` |
15
- | Aleph Cloud credits (no chain: Aleph's own network, by the Ethereum address) | Aleph's API, CORS open; a month's statement, `alephEntries` gives `LedgerEntry` (`usage` for consumption, with its USD price per credit) | `aleph` |
7
+ | Chain | Source | Module |
8
+ | --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------- |
9
+ | Nym (Nyx), Akash (Cosmos SDK) | CometBFT RPC + REST; Akash's older history from the Akash Console indexer; Akash deployments | `cosmos`, `akash-console`, `akash-deployments`, `bech32`, `protobuf` |
10
+ | Akash as `LedgerEntry` (`readAkash`, `statementAkash`: the fee to the network, escrow its own kind) | the Cosmos reader and the Akash Console indexer | `akash` |
11
+ | Ethereum, Base, Arbitrum One, OP Mainnet, Polygon PoS (USDC listed; ALEPH on Ethereum and Base) | Blockscout, or Alchemy with a key; `evmReader(chain)` gives `LedgerEntry` through Alchemy (the key handed to each read) | `evm`, `alchemy` |
12
+ | Bitcoin | Esplora; addresses derived from a zpub/ypub/xpub | `bitcoin` |
13
+ | Filecoin | Filfox; `readFilecoin`/`statementFilecoin` give `LedgerEntry` | `filecoin` |
14
+ | NEAR | NearBlocks + an archival RPC (from Eigenbeleg); `LedgerEntry`, and `WalletEntry` through `createWalletService` | `near` |
15
+ | Aleph Cloud credits (no chain: Aleph's own network, by the Ethereum address) | Aleph's API, CORS open; a month's statement, `alephEntries` gives `LedgerEntry` (`usage` for consumption, with its USD price per credit) | `aleph` |
16
+ | Filecoin Pay (the payment contract of Filecoin Onchain Cloud, by the payer's address) | the makers' index (a subgraph at Goldsky), Blockscout's log API, Filfox; a month's statement, `filecoinPayEntries` gives `LedgerEntry` (`usage` for each settlement of a rail) | `filecoin-pay` |
16
17
 
17
18
  - `createWalletService({ fetch, getZpub, alchemyKey, … })` – every chain behind one `history({ chain, address, endpoints })`, as Belege's bridge serves it.
18
19
  - `CHAINS`, `chainOf`, `publicChains` – the chains, their assets, default endpoints and explorers (`registry`). One chain's data without the others: `FILECOIN` (`filecoin-chain`), `NYX_CHAIN`, `AKASH_CHAIN` (`cosmos-chains`), `KNOWN_EVM_CONTRACTS` (`evm-contracts`). The readers take their chain as an argument and do not import the registry.
19
20
  - The `LedgerEntry` readers (`near`, `akash`, `filecoin`, `evmReader`, `aleph`) each give `read…`/`statement…` for a period (`statement`: the entries and the balances before and after, `method: 'archive'` on NEAR, `'derived'` from today's balance elsewhere), `probe` as a live check against public data, `isAddress`, and for Aleph `purchaseEntries`: the payment behind each credit purchase. From the Eigenbeleg agent's pipeline readers; its blocks are built on them.
21
+ - `createFilecoinPayClient().statement({ address, month })` (`filecoin-pay`) – what a payer's balance in Filecoin Pay was used for in a month: opening and closing balance, paid in, taken out, and each settlement of each rail (provider, service, amount, of it commission and network fee, paid up to when), valued in euros. Storage there is paid by the contract out of that balance, not by transfers of a wallet, so no wallet reader sees it. Read from the makers' index first and from the contract's events at Blockscout when the index does not answer (`endpoints.blockscoutKey` for a key of dev.blockscout.com, sent to `api.blockscout.com` in the `authorization` header and in no URL – the client's `keyed` option names that host, so a caller of `statement` cannot have the key sent elsewhere; without a key Blockscout allows about ten requests, then none for minutes). `source` and `movementsFrom` on the statement say which way it came. `filecoinPayEntries` gives its lines as `LedgerEntry`. Runs in Node and in a browser.
20
22
  - `toChecksumAddress`, `isEvmAddress` – an EVM address's EIP-55 checksum and form (`evm-address`: keccak and bytes only, so `aleph` and a browser form do not bundle the EVM reader or Alchemy; `evm` re-exports them).
21
23
  - `createJsonFetcher`, `WalletError`, `checkEndpoint`, `txUrl`, `addressUrl`, `markSwaps` – what every reader shares (`core`). Error messages name a host at most, never a path or a query (they carry addresses).
22
24
  - Fakes for tests, with made-up addresses, hashes, keys and amounts:
23
- - `@le-space/chains/testing/cosmos`, `testing/filfox`, `testing/blockscout`, `testing/alchemy` – fake nodes on 127.0.0.1 (Node). The fake Alchemy is as strict as the real one about what it is asked; `blockscoutView` turns its made-up chain into what the fake Blockscout serves, so one history reads through both.
25
+ - `@le-space/chains/testing/cosmos`, `testing/filfox`, `testing/near` (a `fetch`, no server), `testing/blockscout`, `testing/alchemy` – fake nodes on 127.0.0.1 (Node). The fake Alchemy is as strict as the real one about what it is asked; `blockscoutView` turns its made-up chain into what the fake Blockscout serves, so one history reads through both.
24
26
  - `@le-space/chains/testing/aleph` – a fake Aleph API as a `fetch` function (Node and browser), and a made-up account and month (`ACCOUNT`, `sampleRows`, `sampleBalance`, `flatUsd`).
27
+ - `@le-space/chains/testing/filecoin-pay` – a fake of what the Filecoin Pay reader asks (the index, Blockscout, Filfox) as one `fetch` function, from a list of made-up events (`filecoinPayFetch`, `blockAt`, `units`).
25
28
 
26
29
  Each source sees the address and the IP address of the machine that asks; Belege's consent screen says so.
27
30
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@le-space/chains",
3
- "version": "0.4.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",
@@ -33,11 +33,14 @@
33
33
  "./filecoin-chain": "./src/filecoin-chain.js",
34
34
  "./near": "./src/near.js",
35
35
  "./aleph": "./src/aleph.js",
36
+ "./filecoin-pay": "./src/filecoin-pay.js",
36
37
  "./testing/cosmos": "./test/support/fake-cosmos.js",
37
38
  "./testing/filfox": "./test/support/fake-filfox.js",
39
+ "./testing/near": "./test/support/fake-near.js",
38
40
  "./testing/blockscout": "./test/support/fake-blockscout.js",
39
41
  "./testing/alchemy": "./test/support/fake-alchemy.js",
40
- "./testing/aleph": "./test/support/aleph.js"
42
+ "./testing/aleph": "./test/support/aleph.js",
43
+ "./testing/filecoin-pay": "./test/support/filecoin-pay-fetch.js"
41
44
  },
42
45
  "files": [
43
46
  "src",
@@ -55,7 +58,7 @@
55
58
  "@scure/base": "2.4.0",
56
59
  "@scure/bip32": "2.4.0",
57
60
  "@le-space/ledger": "^0.3.0",
58
- "@le-space/rates": "^0.3.0"
61
+ "@le-space/rates": "^0.4.0"
59
62
  },
60
63
  "devDependencies": {
61
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 ?? '')
@@ -307,6 +333,22 @@ export function createAlephClient({
307
333
  // Prices of every purchase up to the month's end, to value its consumption.
308
334
  const purchases = (await pages(`&endDate=${end}&direction=incoming`)).filter((r) => r?.price);
309
335
  const { topUps, transfersOut, usage } = summarise({ rows, purchases });
336
+ // Every purchase up to the month's end with the transaction that paid it:
337
+ // what a wallet's or an exchange's booking of that payment is known by.
338
+ const paid = purchases
339
+ .filter((r) => r?.tx_hash && num(r.amount) > 0)
340
+ .map((r) => ({
341
+ time: new Date(String(r.message_timestamp)).toISOString(),
342
+ credits: num(r.amount),
343
+ // Units of the payment token per credit paid for – not USD (rates' alephPurchase).
344
+ price: String(r.price),
345
+ usd: purchaseOf(r)?.usd ?? null,
346
+ tokenAmount: purchaseOf(r)?.tokenAmount ?? null,
347
+ token: r.token ? String(r.token) : null,
348
+ chain: r.chain ? String(r.chain) : null,
349
+ txHash: String(r.tx_hash)
350
+ }))
351
+ .sort((a, b) => a.time.localeCompare(b.time));
310
352
 
311
353
  // What each billed resource is: its type and the name it was given.
312
354
  /** @type {Record<string, { type: string, name: string }>} */
@@ -357,6 +399,7 @@ export function createAlephClient({
357
399
  opening,
358
400
  closing,
359
401
  topUps,
402
+ purchases: paid,
360
403
  transfersOut,
361
404
  usage,
362
405
  resources,
@@ -414,8 +457,8 @@ export function alephEntries(statement) {
414
457
  ? `Aleph Cloud (Kauf${t.token ? ` mit ${t.token}` : ''}${t.chain ? ` auf ${t.chain}` : ''})`
415
458
  : '',
416
459
  explorerUrl,
417
- ...(t.price
418
- ? { unitPrice: { currency: 'USD', amount: plain(t.price), source: 'purchase' } }
460
+ ...(t.usdPerCredit
461
+ ? { unitPrice: { currency: 'USD', amount: plain(t.usdPerCredit), source: 'purchase' } }
419
462
  : {})
420
463
  })
421
464
  ),
@@ -473,13 +516,23 @@ export const PURCHASE_EXPLORERS = /** @type {Record<string, import('./explorer.j
473
516
  }
474
517
  });
475
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
+
476
526
  /**
477
527
  * The payments behind a month's credit purchases: one `sent` entry per
478
- * purchase, in USD (credits × the purchase's USD price per credit), of kind
479
- * `swap` – a token for credits; the ledger has no `purchase` kind. The token
480
- * amount paid is not in Aleph's data; it is checked through the paying
481
- * transaction's hash, whose explorer link is on the chain it was paid on
482
- * (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
483
536
  * bought stay the `received` row of `alephEntries`, with the same hash, so an
484
537
  * Eigenbeleg shows both sides.
485
538
  *
@@ -490,9 +543,13 @@ export const PURCHASE_EXPLORERS = /** @type {Record<string, import('./explorer.j
490
543
  export function purchaseEntries(statement, { explorers = PURCHASE_EXPLORERS } = {}) {
491
544
  const { address, topUps } = statement;
492
545
  return topUps
493
- .filter((t) => t.how === 'purchase' && t.price)
546
+ .filter((t) => t.how === 'purchase' && t.usd)
494
547
  .map((t, i) => {
495
- 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;
496
553
  return entry({
497
554
  id: `aleph:${address}:purchase:${t.time}:${i}`,
498
555
  chain: 'aleph',
@@ -506,11 +563,16 @@ export function purchaseEntries(statement, { explorers = PURCHASE_EXPLORERS } =
506
563
  asset: 'USD',
507
564
  contract: 'native',
508
565
  decimals: 6,
509
- amount: `-${normalize(multiply(credits(t.credits), /** @type {string} */ (t.price), 8))}`,
566
+ amount: `-${normalize(/** @type {string} */ (t.usd))}`,
510
567
  counterparty: 'aleph',
511
568
  method: '',
512
569
  counterpartyLabel: `Aleph Cloud (Kauf von ${credits(t.credits)} Credits${t.token ? ` mit ${t.token}` : ''}${t.chain ? ` auf ${t.chain}` : ''})`,
513
- 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
+ : ''),
514
576
  success: true,
515
577
  explorerUrl:
516
578
  explorer && t.txHash ? txUrl(explorer, t.txHash) : `${ALEPH_EXPLORER}${address}`,