Посібник розробника 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
- Вбудований базовий рушій гаманця, воркери та локальні ресурси доказування 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, воркерів і доказування — їх необхідно розгорнути разом із вашим застосунком.
Перший запит до ланцюга (без гаманця)
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
- Поки що немає керованого сховища секретів, віддаленого сервісу доказування чи інтеграції з апаратним підписувачем
- Сховище не заявлене як зашифроване під час зберігання
- Не відкривайте одне й те саме сховище гаманця одночасно з кількох процесів або вкладок браузера
- Завжди коректно закривайте гаманець за допомогою
await wallet.close()
Наступні кроки
Офіційні ресурси
Цей посібник базується на @zcashlabs/zcash.js@0.1.1 (жовтень 2026 року). SDK активно розробляється — завжди надавайте перевагу офіційній документації щодо найновішого API та обмежень.
