Долго держал балансы в голове и в трёх вкладках. Эфир — в Etherscan, TRON — в Tronscan, биток — в мемпуле, и каждый раз, когда кто-то спрашивал «а сколько там всего», я лез в три места и складывал в блокнот. Один раз сложил неправильно и сказал человеку сумму на треть больше, чем было. Стыдно до сих пор.
Так появилась панель. И сразу главное, что я понял уже после первой версии: вся работа не в интерфейсе. Интерфейс — это таблица, её можно собрать за вечер. Работа в двух местах: привести четыре разных ответа эксплореров к одному виду и не записать одну транзакцию дважды.
Четыре эксплорера отвечают на один и тот же вопрос четырьмя разными способами. Etherscan отдаёт { result: [...] }, где суммы — строки в wei. TronGrid кладёт в data, и точность суммы надо брать из token_info.decimals, а не догадываться. Esplora (blockstream) отдаёт массив транзакций с vin и vout, и это единственный источник, где сумму нельзя просто прочитать — её надо вычислить. Solana вообще не отдаёт транзакции списком: сначала подписи через getSignaturesForAddress, потом по каждой отдельный getTransaction.
Наружу у меня один плоский вид: цепочка, txid, адрес, направление, контрагент, сумма, комиссия, время, актив. Всё остальное — слой поверх.
Про адреса. Отдельный файл, хотя кажется мелочью. Адрес, вставленный с опечаткой, не падает и не ругается — он просто пустой. В таблице появляется кошелёк, на котором никогда ничего не было, и через месяц такой строке уже никто не удивляется. Поэтому проверка у каждой сети своя, и это не «регулярка на hex»: у Ethereum при смешанном регистре проверяется контрольная сумма EIP-55, у BTC — base58check с версиями 0x00 и 0x05 плюс bech32 с полиномом BIP-173, у TRON — base58check с версией 0x41, у Solana — ровно 32 байта и никакой контрольной суммы, её там нет вовсе.
С EIP-55 вышла забавная вещь. Контрольная сумма считается на Keccak-256, а в node:crypto лежит sha3-256 — и это не он. Отличие в одном байте добивки: 0x01 у Keccak, 0x06 у SHA-3. Первые полчаса я не мог понять, почему официальные тестовые адреса не сходятся, пока не посмотрел на этот байт. Пришлось написать перестановку руками на BigInt — медленнее нативной, зато от нуля и без сборки. Эталон сошёлся: keccak256("") даёт c5d2460186f7233c….
Про деньги. Сумма у меня живёт как BigInt в минимальных единицах плюс число знаков. Причина скучная: 0.1 + 0.2 в double не равно 0.3, а wei — это 18 знаков. Складывать балансы во float значит получить расхождение на восьмом знаке, которого в эксплорере нет и которое никогда не сойдётся с тем, что показывает биржа. Строку для таблицы собираю вручную, без экспоненты — иначе 0.000000000000000001 однажды покажется как 1e-18 и кто-нибудь решит, что это баг.
Про биток, где я наврал сам себе. Первая версия считала исходящую сумму как весь вывод. Отправил 0.0004, сдача 0.00012 вернулась на мой же адрес — панель показала 0.00052. То есть каждая трата выглядела на четверть больше реальной, а на мелких суммах и вдвое. Правильно — «ушло минус возврат на свой адрес», и это единственное место во всей нормализации, где я реально ошибся в логике, а не в формате. В прогоне теперь 0.0004, и в CSV то же самое.
С Solana отдельная история: комиссия снимается с подписанта, а не с получателя. У аккаунта в одной транзакции может быть несколько инструкций, поэтому баланс считается по разнице pre/post, и fee вычитается только если подписант — наш адрес. В прогоне входящая на 0.3 SOL приходит с нулевой комиссией, потому что платил не я.
Дедупликация — вторая вещь, без которой панель врёт тихо. Синк тянет окно последних транзакций, окна перекрываются: вчерашняя транзакция приезжает сегодня, послезавтра и через неделю. Если писать всё подряд, поток за период считается по три раза, и график показывает не то, что было. Ключ у меня — сеть, txid, адрес, направление, сумма, актив. Адрес и направление там не для красоты: одна транзакция законно живёт в базе дважды — исходящая у отправителя и входящая у получателя, если оба кошелька добавлены. Ключа только по txid для этого мало. В прогоне два прохода подряд: первый даёт 10 новых, второй 0 новых и 10 дублей. Так и должно быть.
429. У Etherscan на бесплатном тарифе 5 запросов в секунду, у Blockstream режут по IP и лимит непубликован, у публичного Solana RPC своя квота. Написать «в цикле по всем кошелькам» — значит получить отказы, проглотить их и решить, что транзакций просто нет. Поэтому клиент отдельный: пауза 120–300 мс между запросами, чтение Retry-After, бэкофф на 5xx. В прогоне 17 запросов, один ответ 429, один ретрай и 2.44 секунды суммарных пауз — и всё доехало. Ещё деталь: пустая страница пагинации — это конец списка, а не ошибка. На этом ломается половина таких синков, потому что пустой ответ принимают за сбой и начинают ретраить вечно.
И self-transfer. Перевод самому себе не двигает ни приход, ни расход — иначе в графике он посчитается дважды, в обе стороны. У меня в прогоне есть одна такая транзакция (0xdd44, from == to), в поток она не входит вовсе.
Теперь честно про прогон. Живых ключей эксплореров у меня нет, поэтому поднят mockexplorer.js — локальный сервер на node:http, который отвечает теми же полями, что настоящие API: result у Etherscan, data + token_info у TronGrid, массив с vin/vout у Esplora, JSON-RPC с getSignaturesForAddress и getTransaction у Solana. Подменён адрес, а не протокол: fetch, разбор JSON, пагинация, 429 с Retry-After, пустая страница — всё проходит по-настоящему. Мок отдаёт 429 однократно на пару «адрес + страница», потому что бесконечный 429 сделал бы стенд непроходимым и не проверил бы ничего.
Чего в прогоне нет. Next.js, Prisma и Postgres не запускались: npm в моём окружении заблокирован политикой PowerShell, поэтому node_modules поставить нечем. В архиве интерфейс, схема, роуты и Dockerfile лежат настоящие и полные — но они проверены глазами, а не компилятором, и это надо знать до того, как вы попробуете docker compose up. Ядро, которое под ними, прогнано: node --test test.js — 13 тестов, все проходят. Именно поэтому ядро и написано без зависимостей — ESM, { "type": "module" }, ничего из npm. Его можно проверить, не имея ничего, кроме node.
Из тестов, кстати, два упали на первом прогоне — и оба раза неверным было ожидание в тесте, а не код. bech32 по BIP-173 принимает адрес, целиком записанный заглавными, — невалиден только смешанный регистр. Я был уверен в обратном.
В архиве: lib/keccak.js, lib/base58.js, lib/addr.js, lib/money.js, lib/normalize.js, lib/dedupe.js, lib/flow.js, lib/csv.js, sync.js, mockexplorer.js, test.js, make_transcript.js, transcript.txt целиком, export.csv из прогона (10 строк), схема prisma/schema.prisma с уникальным ключом на транзакцию — тем же, что в дедупе, поэтому повторный синк не требует читать всю таблицу в память. Дальше app/page.tsx, роуты /api/wallets, /api/sync, /api/export, auth.ts на NextAuth v5 с одним Credentials-провайдером и сравнением пароля постоянного времени, Dockerfile, docker-compose.yml с постгресом и healthcheck, .env.example с подписанными лимитами каждого тарифа.
CSV нарочно с точкой с запятой и BOM. Не из любви к странному: русский Excel считает запятую разделителем и разносит 1.234,5 на два столбца, а без BOM читает UTF-8 как cp1251 и превращает кириллицу в мусор. Проверено на своей машине, поэтому и в коде.
Где это не спасает, чтобы не продавать лишнего:
— токены внутри сетей (ERC-20, TRC-20, SPL) не поддерживаются, только нативная монета: для токенов в ключ дедупа надо добавлять contractAddress, иначе USDT и USDC с одинаковым txid схлопнутся в одну строку;
— курса нет вовсе, и это осознанно: панель отвечает «куда ушли монеты», а не «сколько это стоит»;
— фонового крона нет, синк кнопкой, и на сотне кошельков роут начнёт упираться в таймаут — там уже нужна очередь;
— Blockstream без своего инстанса режет по IP непредсказуемо, для серьёзного использования нужен mempool.space или свой esplora;
— EIP-55 проверяется только при смешанном регистре: адрес, вставленный целиком в нижнем регистре, валиден, но опечатку в нём поймать нечем — контрольной суммы в нём просто нет. Панель сама приводит его к правильному виду, но проверить уже не может.
Лицензия — делайте что хотите. За то, что панель покажет не то, отвечает тот, кто вбил адрес.