@le-space/chains 0.0.0-stage → 0.1.0

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.
@@ -0,0 +1,130 @@
1
+ // Just enough protobuf to read a Cosmos transaction's memo and fee from the
2
+ // bytes CometBFT's tx_search hands out (base64 of a `TxRaw`). The events
3
+ // carry neither the memo nor, before cosmos-sdk 0.46, the fee.
4
+ //
5
+ // TxRaw { 1 body_bytes, 2 auth_info_bytes, 3 signatures }
6
+ // TxBody { 1 messages (Any { 1 type_url, 2 value }), 2 memo, … }
7
+ // AuthInfo { 1 signer_infos, 2 fee }
8
+ // Fee { 1 amount (Coin { 1 denom, 2 amount }), 2 gas_limit, 3 payer, 4 granter }
9
+ //
10
+ // Unknown fields are skipped by wire type; anything malformed yields null
11
+ // rather than a half-read value.
12
+
13
+ import { fromBase64, toBase64 } from '@le-space/ledger/bytes';
14
+
15
+ /**
16
+ * @param {Uint8Array} bytes
17
+ * @returns {Map<number, Uint8Array[]> | null} length-delimited fields by number; varints are skipped
18
+ */
19
+ function fields(bytes) {
20
+ /** @type {Map<number, Uint8Array[]>} */
21
+ const out = new Map();
22
+ let i = 0;
23
+ const varint = () => {
24
+ let value = 0n;
25
+ let shift = 0n;
26
+ for (;;) {
27
+ if (i >= bytes.length || shift > 63n) throw new Error('bad varint');
28
+ const b = bytes[i++];
29
+ value |= BigInt(b & 0x7f) << shift;
30
+ if (!(b & 0x80)) return value;
31
+ shift += 7n;
32
+ }
33
+ };
34
+ try {
35
+ while (i < bytes.length) {
36
+ const key = varint();
37
+ const field = Number(key >> 3n);
38
+ const wire = Number(key & 7n);
39
+ if (wire === 0) varint();
40
+ else if (wire === 1) i += 8;
41
+ else if (wire === 5) i += 4;
42
+ else if (wire === 2) {
43
+ const length = Number(varint());
44
+ if (i + length > bytes.length) return null;
45
+ out.set(field, [...(out.get(field) ?? []), bytes.subarray(i, i + length)]);
46
+ i += length;
47
+ } else return null;
48
+ if (i > bytes.length) return null;
49
+ }
50
+ } catch {
51
+ return null;
52
+ }
53
+ return out;
54
+ }
55
+
56
+ const text = (/** @type {Uint8Array | undefined} */ b) =>
57
+ b ? new TextDecoder('utf-8', { fatal: false }).decode(b) : '';
58
+
59
+ /**
60
+ * @param {string} base64 the `tx` of a tx_search result
61
+ * @returns {{ memo: string, messageTypes: string[], fee: { denom: string, amount: string }[] } | null}
62
+ */
63
+ export function decodeTx(base64) {
64
+ if (typeof base64 !== 'string' || !base64) return null;
65
+ const raw = fields(fromBase64(base64));
66
+ const bodyBytes = raw?.get(1)?.[0];
67
+ const authBytes = raw?.get(2)?.[0];
68
+ if (!raw || !bodyBytes) return null;
69
+ const body = fields(bodyBytes);
70
+ if (!body) return null;
71
+ const messageTypes = (body.get(1) ?? []).map((any) => text(fields(any)?.get(1)?.[0]));
72
+ const auth = authBytes ? fields(authBytes) : null;
73
+ const fee = auth?.get(2)?.[0] ? fields(/** @type {Uint8Array} */ (auth.get(2)?.[0])) : null;
74
+ const coins = (fee?.get(1) ?? []).map((c) => {
75
+ const coin = fields(c);
76
+ return { denom: text(coin?.get(1)?.[0]), amount: text(coin?.get(2)?.[0]) };
77
+ });
78
+ return {
79
+ memo: text(body.get(2)?.[0]),
80
+ messageTypes,
81
+ fee: coins.filter((c) => c.denom && /^\d+$/.test(c.amount))
82
+ };
83
+ }
84
+
85
+ // For the fake chain in the tests: the same structure, written.
86
+
87
+ /** @param {number} n */
88
+ function writeVarint(n) {
89
+ /** @type {number[]} */
90
+ const out = [];
91
+ let v = BigInt(n);
92
+ do {
93
+ let b = Number(v & 0x7fn);
94
+ v >>= 7n;
95
+ if (v) b |= 0x80;
96
+ out.push(b);
97
+ } while (v);
98
+ return out;
99
+ }
100
+
101
+ /** @param {number} field @param {Uint8Array | string} value */
102
+ function lengthDelimited(field, value) {
103
+ const bytes = typeof value === 'string' ? new TextEncoder().encode(value) : value;
104
+ return Uint8Array.from([
105
+ ...writeVarint((field << 3) | 2),
106
+ ...writeVarint(bytes.length),
107
+ ...bytes
108
+ ]);
109
+ }
110
+
111
+ /** @param {Uint8Array[]} parts */
112
+ const concat = (parts) => Uint8Array.from(parts.flatMap((p) => [...p]));
113
+
114
+ /**
115
+ * @param {{ memo?: string, messageTypes?: string[], fee?: { denom: string, amount: string }[] }} tx
116
+ * @returns {string} base64 of a TxRaw
117
+ */
118
+ export function encodeTx({ memo = '', messageTypes = [], fee = [] }) {
119
+ const body = concat([
120
+ ...messageTypes.map((type) => lengthDelimited(1, lengthDelimited(1, type))),
121
+ ...(memo ? [lengthDelimited(2, memo)] : [])
122
+ ]);
123
+ const feeBytes = concat(
124
+ fee.map((c) =>
125
+ lengthDelimited(1, concat([lengthDelimited(1, c.denom), lengthDelimited(2, c.amount)]))
126
+ )
127
+ );
128
+ const auth = lengthDelimited(2, feeBytes);
129
+ return toBase64(concat([lengthDelimited(1, body), lengthDelimited(2, auth)]));
130
+ }
@@ -0,0 +1,279 @@
1
+ // The chains a wallet can be on, and what the bridge needs to read one:
2
+ // the kind of API, the address format, the assets it books, the default
3
+ // endpoints and the block explorer to link to.
4
+ //
5
+ // Three kinds:
6
+ // cosmos CometBFT RPC (tx_search, header, status) + the REST (LCD) API
7
+ // for balances. Nym's Nyx and Akash.
8
+ // evm Blockscout's Etherscan-compatible API (`/api?module=account…`),
9
+ // no key needed. Ethereum, Base, Arbitrum, Optimism, Polygon.
10
+ // With an Alchemy key (`pnpm setup:alchemy`) Alchemy instead
11
+ // (chains/alchemy.js); the network names are below.
12
+ // bitcoin an Esplora API (mempool.space), read by the addresses derived
13
+ // from a zpub kept in the bridge's keychain (bitcoin.js).
14
+ // filecoin Filfox's public API, by the address (filecoin.js); FIL and the
15
+ // FEVM tokens listed for it.
16
+ //
17
+ // Only assets listed here are booked. A Cosmos denom or an ERC-20 contract
18
+ // that is not listed is counted and left out: a token contract can name
19
+ // itself "USDC" and be worthless, so a symbol is never taken from the chain.
20
+ //
21
+ // Where each value comes from, and what was checked on 2026-09-26, is in
22
+ // docs/crypto.md ("Own wallets").
23
+
24
+ import { addressUrl, txUrl } from './explorer.js';
25
+ import { AKASH_CHAIN, NYX_CHAIN } from './cosmos-chains.js';
26
+ import { FILECOIN } from './filecoin-chain.js';
27
+
28
+ /**
29
+ * @typedef {object} ChainAsset
30
+ * @property {string} symbol as in the app's assets/registry.js and the bridge's rates.js
31
+ * @property {number} decimals
32
+ */
33
+
34
+ /**
35
+ * @typedef {object} Explorer
36
+ * @property {string} name
37
+ * @property {string} tx URL with `{tx}`
38
+ * @property {string} address URL with `{address}`
39
+ */
40
+
41
+ /** @typedef {import('./cosmos-chains.js').CosmosChain} CosmosChain */
42
+
43
+ /**
44
+ * @typedef {object} EvmChain
45
+ * @property {string} id
46
+ * @property {'evm'} kind
47
+ * @property {string} name
48
+ * @property {string} shortName
49
+ * @property {number} chainId
50
+ * @property {string} caip2
51
+ * @property {ChainAsset} native
52
+ * @property {Record<string, ChainAsset>} tokens lower-case contract address → asset
53
+ * @property {{ api: string }} endpoints Blockscout, …/api
54
+ * @property {{ api: string[] }} alternatives
55
+ * @property {Explorer} explorer
56
+ * @property {AlchemyNetwork} [alchemy] read through Alchemy instead, when a key is set up
57
+ */
58
+
59
+ /**
60
+ * @typedef {object} AlchemyNetwork
61
+ * @property {string} network the host's first label: `https://<network>.g.alchemy.com/v2/<key>`
62
+ * @property {boolean} internal whether alchemy_getAssetTransfers offers the category `internal`
63
+ * there; where it does not, internal transactions still come from Blockscout
64
+ */
65
+
66
+ /**
67
+ * @typedef {object} BitcoinChain
68
+ * @property {string} id
69
+ * @property {'bitcoin'} kind
70
+ * @property {string} name
71
+ * @property {string} shortName
72
+ * @property {string} caip2
73
+ * @property {ChainAsset} native
74
+ * @property {{ api: string }} endpoints an Esplora API, …/api
75
+ * @property {{ api: string[] }} alternatives
76
+ * @property {Explorer} explorer
77
+ */
78
+
79
+ /** @typedef {import('./filecoin-chain.js').FilecoinChain} FilecoinChain */
80
+
81
+ /**
82
+ * @typedef {object} MoneroChain imported from the wallet's export in the app, never read here
83
+ * @property {string} id
84
+ * @property {'monero'} kind
85
+ * @property {string} name
86
+ * @property {string} shortName
87
+ * @property {string} caip2
88
+ * @property {{ symbol: string, decimals: number }} native
89
+ * @property {Record<string, string>} endpoints none
90
+ * @property {Record<string, string[]>} alternatives none
91
+ * @property {Explorer} explorer
92
+ */
93
+
94
+ /** @typedef {CosmosChain | EvmChain | BitcoinChain | FilecoinChain | MoneroChain} Chain */
95
+
96
+ const USDC = { symbol: 'USDC', decimals: 6 };
97
+ const ETH = { symbol: 'ETH', decimals: 18 };
98
+
99
+ /** @param {string} base e.g. https://etherscan.io */
100
+ const etherscanLike = (/** @type {string} */ name, /** @type {string} */ base) => ({
101
+ name,
102
+ tx: `${base}/tx/{tx}`,
103
+ address: `${base}/address/{address}`
104
+ });
105
+
106
+ /**
107
+ * Contracts a wallet meets when it swaps (issue #115), by their lower-case
108
+ * address, and what they are called. Routers of the big aggregators and DEXes
109
+ * sit at the same address on most EVM chains; WETH is Ethereum's. Checked
110
+ * against the projects' own documentation; an address not here stays
111
+ * "Vertrag".
112
+ */
113
+ export const KNOWN_EVM_CONTRACTS = /** @type {Readonly<Record<string, string>>} */ (
114
+ Object.freeze({
115
+ '0x881d40237659c251811cec9c364ef91dc08d300c': 'MetaMask Swap (Router)',
116
+ '0x74de5d4fcbf63e00296fd95d33236b9794016631': 'MetaMask Swap (Spender)',
117
+ '0x3fc91a3afd70395cd496c647d5a6cc9d4b2b7fad': 'Uniswap (Universal Router)',
118
+ '0x66a9893cc07d91d95644aedd05d03f95e1dba8af': 'Uniswap (Universal Router v4)',
119
+ '0x7a250d5630b4cf539739df2c5dacb4c659f2488d': 'Uniswap V2 (Router)',
120
+ '0xe592427a0aece92de3edee1f18e0157c05861564': 'Uniswap V3 (Router)',
121
+ '0x68b3465833fb72a70ecdf485e0e4c7bd8665fc45': 'Uniswap V3 (Router 2)',
122
+ '0x1111111254eeb25477b68fb85ed929f73a960582': '1inch (Router v5)',
123
+ '0x111111125421ca6dc452d289314280a0f8842a65': '1inch (Router v6)',
124
+ '0xdef1c0ded9bec7f1a1670819833240f027b25eff': '0x (Exchange Proxy)',
125
+ '0x9008d19f58aabd9ed0d60971565aa8510560ab41': 'CoW Protocol (Settlement)',
126
+ '0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2': 'WETH'
127
+ })
128
+ );
129
+
130
+ /** @type {Readonly<Record<string, Chain>>} */
131
+ export const CHAINS = Object.freeze({
132
+ nyx: NYX_CHAIN,
133
+ akash: AKASH_CHAIN,
134
+ ethereum: {
135
+ id: 'ethereum',
136
+ kind: 'evm',
137
+ name: 'Ethereum',
138
+ shortName: 'Ethereum',
139
+ chainId: 1,
140
+ caip2: 'eip155:1',
141
+ native: ETH,
142
+ tokens: { '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48': USDC },
143
+ endpoints: { api: 'https://eth.blockscout.com/api' },
144
+ alternatives: { api: [] },
145
+ explorer: etherscanLike('Etherscan', 'https://etherscan.io'),
146
+ alchemy: { network: 'eth-mainnet', internal: true }
147
+ },
148
+ base: {
149
+ id: 'base',
150
+ kind: 'evm',
151
+ name: 'Base',
152
+ shortName: 'Base',
153
+ chainId: 8453,
154
+ caip2: 'eip155:8453',
155
+ native: ETH,
156
+ tokens: { '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913': USDC },
157
+ endpoints: { api: 'https://base.blockscout.com/api' },
158
+ alternatives: { api: [] },
159
+ explorer: etherscanLike('Basescan', 'https://basescan.org'),
160
+ alchemy: { network: 'base-mainnet', internal: true }
161
+ },
162
+ arbitrum: {
163
+ id: 'arbitrum',
164
+ kind: 'evm',
165
+ name: 'Arbitrum One',
166
+ shortName: 'Arbitrum',
167
+ chainId: 42161,
168
+ caip2: 'eip155:42161',
169
+ native: ETH,
170
+ tokens: { '0xaf88d065e77c8cc2239327c5edb3a432268e5831': USDC },
171
+ endpoints: { api: 'https://arbitrum.blockscout.com/api' },
172
+ alternatives: { api: [] },
173
+ explorer: etherscanLike('Arbiscan', 'https://arbiscan.io'),
174
+ alchemy: { network: 'arb-mainnet', internal: false }
175
+ },
176
+ optimism: {
177
+ id: 'optimism',
178
+ kind: 'evm',
179
+ name: 'OP Mainnet',
180
+ shortName: 'Optimism',
181
+ chainId: 10,
182
+ caip2: 'eip155:10',
183
+ native: ETH,
184
+ tokens: { '0x0b2c639c533813f4aa9d7837caf62653d097ff85': USDC },
185
+ endpoints: { api: 'https://explorer.optimism.io/api' },
186
+ alternatives: { api: [] },
187
+ explorer: etherscanLike('Optimistic Etherscan', 'https://optimistic.etherscan.io'),
188
+ alchemy: { network: 'opt-mainnet', internal: false }
189
+ },
190
+ polygon: {
191
+ id: 'polygon',
192
+ kind: 'evm',
193
+ name: 'Polygon PoS',
194
+ shortName: 'Polygon',
195
+ chainId: 137,
196
+ caip2: 'eip155:137',
197
+ native: { symbol: 'POL', decimals: 18 },
198
+ tokens: { '0x3c499c542cef5e3811e1192ce70d8cc03d5c3359': USDC },
199
+ endpoints: { api: 'https://polygon.blockscout.com/api' },
200
+ alternatives: { api: [] },
201
+ explorer: etherscanLike('Polygonscan', 'https://polygonscan.com'),
202
+ alchemy: { network: 'polygon-mainnet', internal: true }
203
+ },
204
+ bitcoin: {
205
+ id: 'bitcoin',
206
+ kind: 'bitcoin',
207
+ name: 'Bitcoin',
208
+ shortName: 'Bitcoin',
209
+ caip2: 'bip122:000000000019d6689c085ae165831e93',
210
+ native: { symbol: 'BTC', decimals: 8 },
211
+ endpoints: { api: 'https://mempool.space/api' },
212
+ alternatives: { api: ['https://blockstream.info/api'] },
213
+ explorer: {
214
+ name: 'mempool.space',
215
+ tx: 'https://mempool.space/tx/{tx}',
216
+ address: 'https://mempool.space/address/{address}'
217
+ }
218
+ },
219
+ // Read through Filfox, by address; a message CID is the hash
220
+ // (filecoin-chain.js holds this description).
221
+ filecoin: FILECOIN,
222
+ // Not read here: Monero hides amounts and parties on its chain. The app
223
+ // imports the wallet's own export (app/src/lib/wallets/monero-import.js);
224
+ // listed so both tables name the same chains, and for its explorer.
225
+ monero: {
226
+ id: 'monero',
227
+ kind: 'monero',
228
+ name: 'Monero',
229
+ shortName: 'Monero',
230
+ caip2: 'monero:418015bb9ae982a1975da7d79277c270',
231
+ native: { symbol: 'XMR', decimals: 12 },
232
+ endpoints: {},
233
+ alternatives: {},
234
+ explorer: {
235
+ name: 'xmrchain.net',
236
+ tx: 'https://xmrchain.net/tx/{tx}',
237
+ address: ''
238
+ }
239
+ }
240
+ });
241
+
242
+ /** @param {string} id @returns {Chain | null} */
243
+ export function chainOf(id) {
244
+ return typeof id === 'string' && Object.hasOwn(CHAINS, id) ? CHAINS[id] : null;
245
+ }
246
+
247
+ export { txUrl, addressUrl };
248
+
249
+ /**
250
+ * What the app is told about the chains: everything but code.
251
+ */
252
+ export function publicChains() {
253
+ return Object.values(CHAINS).map((c) => ({
254
+ id: c.id,
255
+ kind: c.kind,
256
+ name: c.name,
257
+ shortName: c.shortName,
258
+ caip2: c.caip2,
259
+ ...(c.kind === 'cosmos'
260
+ ? {
261
+ bech32Prefix: c.bech32Prefix,
262
+ assets: Object.values(c.denoms).map((a) => a.symbol),
263
+ nativeSymbol: c.denoms[c.nativeDenom].symbol
264
+ }
265
+ : c.kind === 'evm' || c.kind === 'filecoin'
266
+ ? {
267
+ assets: [c.native.symbol, ...Object.values(c.tokens).map((a) => a.symbol)],
268
+ nativeSymbol: c.native.symbol
269
+ }
270
+ : { assets: [c.native.symbol], nativeSymbol: c.native.symbol }),
271
+ endpoints: c.endpoints,
272
+ alternatives: c.alternatives,
273
+ // Whether Alchemy reads this chain when a key is set up, and its internal transfers too.
274
+ ...(c.kind === 'evm'
275
+ ? { alchemySupported: Boolean(c.alchemy), alchemyInternal: Boolean(c.alchemy?.internal) }
276
+ : {}),
277
+ explorer: c.explorer
278
+ }));
279
+ }
package/src/swaps.js ADDED
@@ -0,0 +1,61 @@
1
+ // Swap detection across a transaction's entries (EVM, FEVM; issue #115).
2
+
3
+ /**
4
+ * Swaps (issue #115): per transaction, what the wallet gave and what it got,
5
+ * leaving the gas out. Two sides of different assets make a swap; its booked
6
+ * legs become kind `swap` and carry both sides and the router's name.
7
+ * Changes the entries in place.
8
+ *
9
+ * @param {(import('@le-space/ledger/wallet-entry').WalletEntry & { order: string })[]} entries
10
+ * @param {{ hash: string, asset: string, amount: string, listed: false }[]} unlisted
11
+ * @param {(hash: string) => string} viaOf
12
+ */
13
+ export function markSwaps(entries, unlisted, viaOf) {
14
+ /** @type {Map<string, { gave: any[], got: any[], legs: any[] }>} */
15
+ const byHash = new Map();
16
+ const of = (/** @type {string} */ hash) => {
17
+ let x = byHash.get(hash);
18
+ if (!x) byHash.set(hash, (x = { gave: [], got: [], legs: [] }));
19
+ return x;
20
+ };
21
+ /** @type {Map<string, any>} hash → its gas entry */
22
+ const feeOf = new Map();
23
+ for (const e of entries) {
24
+ if (e.type === 'fee') feeOf.set(e.hash, e);
25
+ if (e.type === 'fee' || e.kind !== 'transfer') continue;
26
+ const x = of(e.hash);
27
+ (e.amount.startsWith('-') ? x.gave : x.got).push({
28
+ asset: e.asset,
29
+ amount: e.amount.replace(/^-/, ''),
30
+ listed: e.listed !== false
31
+ });
32
+ x.legs.push(e);
33
+ }
34
+ for (const u of unlisted) {
35
+ const x = of(u.hash);
36
+ (u.amount.startsWith('-') ? x.gave : x.got).push({
37
+ asset: u.asset,
38
+ amount: u.amount.replace(/^-/, ''),
39
+ listed: false
40
+ });
41
+ }
42
+ for (const [hash, x] of byHash) {
43
+ if (!x.legs.length || !x.gave.length || !x.got.length) continue;
44
+ const gaveAssets = new Set(x.gave.map((g) => g.asset));
45
+ if (x.got.every((g) => gaveAssets.has(g.asset))) continue;
46
+ // The gas belongs to the swap too: named in it, and its own entry says
47
+ // which swap it paid for (it stays a fee of its own).
48
+ const gas = feeOf.get(hash);
49
+ const swap = {
50
+ gave: x.gave,
51
+ got: x.got,
52
+ via: viaOf(hash),
53
+ ...(gas ? { fee: { asset: gas.asset, amount: gas.amount.replace(/^-/, '') } } : {})
54
+ };
55
+ for (const e of x.legs) {
56
+ e.kind = 'swap';
57
+ e.swap = swap;
58
+ }
59
+ if (gas) gas.swap = swap;
60
+ }
61
+ }