Экспорт истории транзакций из Viewing Key
Большинство экспортов из кошельков содержат мало данных. Например, налоговый экспорт ZODL предоставляет даты, суммы и комиссии за предыдущий календарный год, но не идентификаторы транзакций, не мемо и не адреса. Этого недостаточно для ведения учёта, проверки переноса кошелька или выяснения того, что произошло с платежом.
Вам не нужна seed-фраза, чтобы получить полную картину. Унифицированный полный ключ просмотра (UFVK, начинающийся с uview1) может видеть каждую входящую и исходящую транзакцию в аккаунте, а два инструмента могут превратить эти данные в сохраняемый вами файл: GraphQL-сервер Zkool и zingo-cli. Это руководство объединяет подходы из этой темы на форуме и обновляет их для актуальных версий.
Проверено в сентябре 2026 года с Zkool 6.30.0 и zingo-cli из zingolib 6.0.0.
Перед началом
Вам понадобятся две вещи:
- UFVK для аккаунта. В Ключах просмотра объясняется, что он раскрывает и как его экспортировать.
- Начальная высота, блок, с которого начинается сканирование. Используйте высоту до первой транзакции. Если задать её слишком высокой, более ранняя история будет незаметно пропущена. Если задать её слишком низкой, сканирование просто займёт больше времени. Активация Sapling (419200) всегда безопасна, но сканирование может занять несколько часов.
Сохраняйте конфиденциальность
Ключ просмотра не позволяет тратить средства, но показывает всю вашу историю тому, у кого он есть.
- Не вставляйте его на веб-сайт или в обозреватель блокчейна. Импортируйте его в программное обеспечение, которое запускаете сами.
- Сервер, с которого вы синхронизируетесь, видит ваш IP-адрес и транзакции, которые вы полностью загружаете. Оба инструмента ниже получают каждую вашу транзакцию по ID, чтобы прочитать мемо и комиссии, а в ZIP 307 отмечается, что это сообщает серверу, какие транзакции принадлежат вам. Синхронизация с вашего собственного полного узла Zebra с помощью Zaino или lightwalletd позволяет этого избежать. В руководстве Zingolib и Zaino Tutorial описывается настройка.
- zingo-cli 6 отправляет платежи через микснет Nym, но синхронизация по-прежнему подключается к серверу напрямую, поэтому сказанное выше относится и к нему.
- Передавайте этим инструментам ключ просмотра, а не seed-фразу. GraphQL-сервер Zkool по умолчанию не имеет входа в систему, а его API вернёт seed-фразу любого аккаунта, созданного из неё, и может отправлять средства.
- Держите сервер на собственной машине. Приведённая ниже команда Docker слушает только на
127.0.0.1.
- Оба инструмента хранят ключ и вашу историю незашифрованными. Удалите рабочие данные после завершения и храните экспорт в зашифрованном месте.
Вариант 1: GraphQL Zkool
zkool_graphql — это кошелёчный движок Zkool в виде автономного сервера. Это отдельная программа от приложения Zkool. Самый простой способ его запустить — официальный образ Docker (amd64 и arm64). На странице релизов Zkool также есть бинарный файл для Linux x86-64; ему требуется glibc 2.38 или новее, поэтому Ubuntu 24.04 подойдёт, а Debian 12 — нет.
1. Запустите сервер
Code-highlight
docker run -d --name zkool-export \
-p 127.0.0.1:8000:8000 \
-v zkool-export:/data \
hhanh00/zkool-graphql:6.30.0 \
--db-path /data/zkool.db
Он синхронизируется с https://zec.rocks, если не добавить --lwd-url с вашим собственным сервером. При первом запуске он загружает параметры Sapling (около 50 МБ). Если это не удаётся, docker start zkool-export повторяет попытку.
Откройте http://127.0.0.1:8000/graphiql в браузере. Вы можете вставлять туда каждый из следующих шагов и выполнять их.
2. Импортируйте ключ
Code-highlight
mutation {
createAccount(newAccount: {
name: "export"
key: "uview1..."
aindex: 0
birth: 2500000
useInternal: true
})
}
Он возвращает ID нового аккаунта, который на новом сервере равен 1.
- Всегда указывайте
birth. Без него Zkool начинает с текущего блока и ничего не находит.
useInternal: true заставляет Zkool также проверять прозрачные адреса сдачи. Не отключайте его для ключей из ZODL — это та же настройка, которую Восстановление средств использует для seed-фраз ZODL.
3. Синхронизация
Code-highlight
mutation { synchronizeAccount(idAccount: 1) }
Это выполняется до окончания синхронизации. Не добавляйте fast: true. Он пропускает загрузку полных транзакций, из которых берутся мемо, комиссии и выходы.
Возвращаемое число — это высота, которой он стремился достичь, а не доказательство, что она достигнута. Сетевая ошибка может преждевременно завершить синхронизацию без каких-либо сообщений, поэтому проверьте:
Code-highlight
{ currentHeight accounts { id name height } }
Если height аккаунта отстаёт от currentHeight, снова запустите синхронизацию. Она продолжится с места остановки.
4. Экспорт
Сохраните это как history.graphql:
Code-highlight
{
transactionsByAccount(idAccount: 1) {
txid height time value fee
notes { pool scope address value memo }
spends { pool scope address value }
outputs { pool vout address value memo }
}
}
Не указывайте аргумент height, если не хотите именно этого. Он задаёт минимум, поэтому height: 3000000 в примере на форуме отбрасывает всё до этого блока.
Получите его в формате JSON:
Code-highlight
jq -n --rawfile q history.graphql '{query: $q}' |
curl -s http://127.0.0.1:8000/graphql \
-H 'content-type: application/json' --data-binary @- > history.json
В каждой транзакции должна быть указана комиссия больше 0, кроме наград за майнинг. Если в какой-либо указано "fee": "0" и нет мемо, её сведения не были загружены. Zkool получает полные транзакции по одной после сканирования, и одна ошибка незаметно останавливает остальные. Чтобы вывести затронутые транзакции:
Code-highlight
jq -r '.data.transactionsByAccount[] | select(.fee == "0") | .txid' history.json
Если что-либо появится, повторите синхронизацию через несколько минут и снова выполните экспорт.
Затем преобразуйте данные в CSV, по одной строке на транзакцию:
Code-highlight
jq -r '["txid","height","time_utc","net_zec","fee_zec","memos"],
(.data.transactionsByAccount[] |
[.txid, .height, .time, .value, .fee,
([.notes[].memo, .outputs[].memo] | map(select(. != null and . != "")) | unique | join(" | "))])
| @csv' history.json > history.csv
Чтение вывода
| Поле | Значение |
|---|
value | Чистое изменение баланса аккаунта в ZEC, включая комиссию. Отрицательное для отправок. |
fee | Комиссия в ZEC. Для полученных вами платежей её заплатил отправитель, и она не входит в value. |
time | Время блока в UTC, без указателя часового пояса |
notes | Что аккаунт получил в этой транзакции, включая сдачу. Здесь находятся отправленные вам мемо. У прозрачных записей нет адреса. |
spends | Собственные заметки аккаунта, которые эта транзакция израсходовала |
outputs | Что транзакция отправила: каждый прозрачный выход, а также экранированные платежи на другие адреса с их мемо |
pool | 0 — прозрачный, 1 — Sapling, 2 — Orchard, 3 — Ironwood |
scope | 0 — внешний (входящий платёж), 1 — внутренний (сдача) |
В приложении Zkool также есть функции Export Transactions, Memos и Notes в меню аккаунта, но это необработанные дампы таблиц: суммы в затоши, временные метки Unix и мемо в отдельном файле.
Вариант 2: zingo-cli
zingo-cli — это кошелёк командной строки Zingo. Готовых загрузок нет, поэтому его нужно собрать с помощью Rust:
Code-highlight
git clone --branch zingolib_v6.0.0 https://github.com/zingolabs/zingolib.git
cd zingolib
cargo build --release -p zingo-cli
cargo build --release --manifest-path zingo-netutils/Cargo.toml --features nym --bin nym-proxy
cp zingo-netutils/target/release/nym-proxy target/release/
Вам нужен nym-proxy даже только для синхронизации. zingo-cli 6 не подключится ни к одному серверу без него.
Первый запуск создаёт кошелёк только для просмотра, синхронизирует его и выводит историю:
Code-highlight
./target/release/zingo-cli --data-dir "$HOME/zingo-export" \
--viewkey "uview1..." --birthday 2500000 \
--server https://zec.rocks:443 \
--waitsync transactions > transactions.txt
--data-dir должен быть абсолютным путём.--viewkey и --birthday применяются только при создании кошелька. Не указывайте их после этого.- zingo-cli по умолчанию запускается офлайн.
--server выбирает сервер и также считается вашим согласием на подключение к сети.
- Ключ попадает в историю вашей оболочки, поэтому очистите её после этого.
Последующие запуски:
Code-highlight
Z="./target/release/zingo-cli --data-dir $HOME/zingo-export"
$Z --server https://zec.rocks:443 --waitsync transactions > transactions.txt
$Z --offline value_transfers > value_transfers.txt
$Z --offline messages > memos.json
--offline читает уже синхронизированные данные, не обращаясь к сети.
transactions предоставляет по одной записи на транзакцию: txid, время (UTC), высоту, тип (received, sent, shield или send-to-self), сумму, комиссию и задействованные заметки.value_transfers предоставляет по одной записи на платёж, поэтому отправка двум людям будет состоять из двух записей, каждая с адресом получателя и мемо.messages выводит мемо в виде JSON.
Несколько особенностей вывода:
transactions и value_transfers выводят обычный текст, немного похожий на JSON, но им не являющийся.- Суммы указаны в затоши (100 000 000 на 1 ZEC) и всегда положительные.
kind указывает направление. Для отправок value — это сумма, ушедшая другим людям, без комиссии.
- Комиссия отображается как "not available", когда транзакция расходует прозрачные средства, которые не принадлежали вам. Показываются только текстовые мемо.
- Если синхронизация не удаётся, ошибка выводится в терминал, а не в файл, и zingo-cli всё равно завершает работу успешно. Проверьте терминал, прежде чем доверять
transactions.txt.
В zingoHelper dismad есть скрипт exportToJSON.sh, который преобразует transactions в JSON. Он был написан до zingo-cli 6, настроен для testnet, помечает некоторые исходящие записи Sapling и прозрачные записи как заполнители и требует GNU-инструменты, поэтому не запустится на стандартном macOS. Считайте его вывод отправной точкой и проверяйте итоги.
Что ключ просмотра не может сообщить
- Цены. Ни один инструмент не записывает цену ZEC на момент каждой транзакции. Добавьте фиатные значения самостоятельно.
- Прозрачную историю, если ключ её не включает. Прозрачная часть UFVK необязательна согласно ZIP 316. В zingo-cli
$Z --offline parse_viewkey uview1... показывает, какие пулы охватывает ключ.
- Кто вам заплатил. Экранированные платежи не содержат адреса отправителя. Если только отправитель не указал его в мемо, его нигде нет.
- Некоторые сведения об исходящих платежах. Адрес назначения, сумма и мемо для экранированных отправок восстанавливаются расшифровкой с ключом. Однако кошелёк может сформировать транзакцию так, что это будет невозможно, хотя большинство этого не делает.
Другие инструменты
| Инструмент | Что вы получаете |
|---|
| ZODL | Налоговый CSV с датами, суммами, комиссиями и тегом. Только за предыдущий календарный год; пропускает транзакции экранирования, без txid, мемо или адреса. |
| приложение Zkool | Необработанные табличные экспорты из меню аккаунта |
| Zenith | Импортирует UFVK с помощью importvk. listreceived через RPC возвращает полученные заметки с txid и мемо, но без отправок и комиссий. |
| Zallet | z_listtransactions предоставляет подробные данные, но помечен как экспериментальный, а Zallet импортирует только ключи просмотра Sapling, а не UFVK |
| zcash-devtool | Импортирует UFVK с помощью wallet init-fvk, затем wallet list-tx. В режиме CSV нет txid или адреса, и проект рекомендует не использовать его в production. |
Связанные материалы
