Руководство разработчика Zcash JS
zcash.js (@zcashlabs/zcash.js) — экспериментальный SDK TypeScript/JavaScript, выпущенный Zcash Labs 26 октября 2026 года. Он позволяет разработчикам создавать кошельки, лёгкие клиенты, панели мониторинга и приложения, взаимодействующие с сетью Zcash из Node.js и браузера.
Статус: экспериментальный (v0.1.1). Постоянные кошельки на узле в настоящее время требуют Linux + flock. Полноценные отправка/получение в браузере и миграция исторической базы данных кошелька ещё не полностью квалифицированы. Перед использованием в производственной среде всегда проверяйте официальную документацию.
Что предоставляет SDK
createPublicClient — JSON-RPC-запросы без состояния и наблюдение за транзакциямиcreateLightClient — запросы и потоки lightwallet (нативный gRPC на узле, gRPC-Web в браузере)createWalletClient — локальные аккаунты, сканирование, предложения, подписание, отправка и восстановление записанных платежей- Точные суммы
bigint, проверка сети, инструменты просмотра/адресов и утилиты PCZT
- Встроенный базовый движок кошелька, воркеры и локальные proving-ресурсы Sapling (отдельная установка Rust не требуется)
Установка
Используйте Node.js 22.23.4 (версию, закреплённую пакетом).
Code-highlight
npm install @zcashlabs/zcash.js@0.1.1
- Предпочтительно использовать TypeScript с ESM (
"type": "module" в package.json).
- Браузерные приложения работают через современный ESM-бандлер. Бандлер создаст лениво загружаемые WASM-, worker- и proving-ресурсы — их необходимо развернуть вместе с приложением.
Первый запрос к цепочке (без кошелька)
Code-highlight
import { createLightClient } from '@zcashlabs/zcash.js';
const light = await createLightClient('https://testnet.zec.rocks:443', {
network: 'testnet',
});
const tip = await light.getTip();
console.log(tip.height, tip.hash);
- Если не указать параметр
network, по умолчанию используется mainnet (укажите соответствующую конечную точку).
- Для использования исключительно JSON-RPC также доступен
createPublicClient.
Открытие кошелька
Code-highlight
import { createWalletClient } from '@zcashlabs/zcash.js';
const wallet = await createWalletClient('https://testnet.zec.rocks:443', {
network: 'testnet',
storage: { kind: 'node-filesystem', path: './my-wallet' }, // Linux only for durable storage
});
try {
const accounts = await wallet.accounts.list();
console.log(accounts);
} finally {
await wallet.close();
}
Варианты хранилища
| Среда | Вариант хранилища |
|---|
| Узел (постоянно) | { kind: 'node-filesystem', path: './my-wallet' } |
| Браузер | { kind: 'browser-opfs', name: 'my-wallet' } |
| Временное | { kind: 'memory' } |
Важные значения по умолчанию (по состоянию на v0.1.1):
- Траты и сдача по умолчанию только Ironwood
- Правило комиссии: ZIP-317
- Подтверждения: 3 доверенных / 3 недоверенных
- Всегда вызывайте
wallet.sync() перед созданием предложения платежа
Высокоуровневый рабочий процесс кошелька
- Создайте или импортируйте аккаунт с мнемонической фразой и подключите подписывающее устройство
- Вызовите
wallet.sync()
- Запросите адрес для получения (предпочтительно Unified / Ironwood)
- Создайте предложение → проверьте его → вызовите
wallet.send()
- Ожидайте подтверждения или используйте записанные операции для восстановления после перезапуска
Приложение управляет байтами мнемонической фразы. Очищайте их из памяти, когда они больше не нужны. Всегда предоставляйте понятный интерфейс подтверждения, показывающий каждого получателя, сумму, комиссию, пул и срок действия.
Полный рабочий пример смотрите в официальном руководстве Wallet.
Примечания по платформам и текущие ограничения
| Возможность | Узел | Браузер |
|---|
| Пакет | Узел 22.23.4 + ESM | Современный ESM-бандлер + WebAssembly |
| Лёгкие запросы | Нативный gRPC | gRPC-Web + CORS |
| Постоянное хранилище | Только Linux + flock | OPFS (безопасный контекст) |
| Временное хранилище | память | память |
Дополнительные ограничения:
- Постоянное хранилище на узле в настоящее время поддерживается только для Linux
- Управляемого хранилища секретов, удалённого proving-сервиса или интеграции с аппаратным подписывающим устройством пока нет
- Хранилище не заявлено как зашифрованное при хранении
- Не открывайте одно и то же хранилище кошелька одновременно из нескольких процессов или вкладок браузера
- Всегда корректно закрывайте кошелёк с помощью
await wallet.close()
Следующие шаги
Официальные ресурсы
Это руководство основано на @zcashlabs/zcash.js@0.1.1 (октябрь 2026 года). SDK активно разрабатывается — всегда обращайтесь к официальной документации за актуальными API и ограничениями.
