@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 +13 -10
- package/package.json +6 -3
- package/src/aleph.js +82 -20
- package/src/filecoin-pay.js +938 -0
- package/src/near-wallet.js +182 -0
- package/src/near.js +47 -0
- package/src/registry.js +41 -2
- package/src/wallets.js +22 -14
- package/test/support/aleph-fetch.js +3 -1
- package/test/support/aleph-sample.js +10 -6
- package/test/support/fake-near.js +121 -0
- package/test/support/filecoin-pay-fetch.js +278 -0
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
|
|
8
|
-
|
|
|
9
|
-
| Nym (Nyx), Akash (Cosmos SDK)
|
|
10
|
-
| Akash as `LedgerEntry` (`readAkash`, `statementAkash`: the fee to the network, escrow its own kind) | the Cosmos reader and the Akash Console indexer
|
|
11
|
-
| Ethereum, Base, Arbitrum One, OP Mainnet, Polygon PoS (USDC listed; ALEPH on Ethereum and Base)
|
|
12
|
-
| Bitcoin
|
|
13
|
-
| Filecoin
|
|
14
|
-
| NEAR
|
|
15
|
-
| Aleph Cloud credits (no chain: Aleph's own network, by the Ethereum address)
|
|
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.
|
|
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.
|
|
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
|
|
14
|
-
//
|
|
15
|
-
//
|
|
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
|
|
31
|
-
//
|
|
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
|
|
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) => ({
|
|
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.
|
|
418
|
-
? { unitPrice: { currency: 'USD', amount: plain(t.
|
|
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
|
|
479
|
-
* `
|
|
480
|
-
*
|
|
481
|
-
*
|
|
482
|
-
*
|
|
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.
|
|
546
|
+
.filter((t) => t.how === 'purchase' && t.usd)
|
|
494
547
|
.map((t, i) => {
|
|
495
|
-
const
|
|
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(
|
|
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:
|
|
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}`,
|