Source, not a package. The modules live in sdk/js and are used from a checkout. Nothing here is published to npm.
Not audited, experimental formats. The code has not been independently audited, and the formats it reads are experimental.
Readers, not a wallet and not a verifier. They decode public bytes. They hold no keys, build no proofs and check no signature and no proof.
The directory’s own README is the reference. This page is the short version. The Developer SDK page covers the rest of the SDK, and the Cookbook walks through each example.
The modules
They are plain ES modules with JSDoc types and no dependencies. The modules use no Node-only interface; the examples and the tests do. They were run in Node, not in a browser.
| Module | What it does | Needs |
|---|---|---|
rpc.mjs | JSON-RPC client for the methods the wallets call | fetch |
formats.mjs | Offline readers: a payment, an inline envelope, the payment id, the pool account, a shielded address | BigInt |
explorer.mjs | Reads the devnet explorer feed and looks a transaction up in it | nothing |
index.mjs | All of the above from one module | |
zolana-browser-core.d.ts | Types for the Wasm core of the browser wallet | a build of the core |
Each module has a declaration file next to it for TypeScript: rpc.d.mts, formats.d.mts, explorer.d.mts and index.d.mts. The RPC client and the browser-core types are described on the Developer SDK page.
Quick start
You need Git and Node.js. Nothing is installed and no request is made.
git clone https://github.com/zolanacom/zolana.git
cd zolana
node sdk/js/examples/decode-payment.mjs
It reads a stored payment, in which Alice pays Bob 40 units with a shielded fee of 3, and prints the public part:
shielded-fee-payment: 9230 bytes, tag NPAY0003
network 0707070707070707070707070707070707070707070707070707070707070707
payment id 2b8296f7d96e1f6077bdc31d4541859544c849af0bcd5261aedacd50225c8832
expiry slot 100
public value 3
shielded fee 3
sponsor 6cGXszer5keoaWm8Co5G9f4KGBThuGz4NsKTqYij1emg
anchor 1fbe1c80664a1b478518e05c8029b49418782b2c39b077cf627d4af0b0b5b31d
nullifier 6154b85afc11f06db91f2f7a1f9a860a0e7504217cb12dbd3422e16abb179604
commitment 593c0de55f92909e654bfc77e9307b582c2ff968fd2760f0c1cb4149b0293b02
nullifier f017eb9715131a11a425e3a24d208b3ea7399541f71575ffe7a5303af95b6c27
commitment 5a4f325f4f2ea8d2f6b4f648215dabedc1d138a51a5fe71853eb27a2188ff82b
for another network: WrongNetwork
The 40 units and the recipient are not in the output: they are not in the public fields of the payment.
The examples
Four programs in sdk/js/examples run with Node alone, offline, on the fixtures in sdk/fixtures. Each has a recipe in the cookbook:
| Example | Recipe |
|---|---|
examples/decode-payment.mjs | Decode a payment |
examples/check-address.mjs | Check an address |
examples/watch-pool.mjs | Watch the pool account |
examples/payment-landed.mjs | Check that a payment landed |
The fixtures are real payments with real proofs, made on a fixture network with public, disposable keys. They are not payments of any deployed network and move nothing.
Use the modules from your own code
Import the modules by path from a checkout:
import { decodePayment, paymentId, checkAddress } from "./zolana/sdk/js/formats.mjs";
import { createRpcClient } from "./zolana/sdk/js/rpc.mjs";
Or import them under one name. sdk/js/package.json gives the directory the name zolana-sdk-js and marks it private, so it cannot be published. Installing it from a path links your checkout into node_modules:
npm install ./zolana/sdk/js
import { decodePayment, createRpcClient, findTransaction } from "zolana-sdk-js";
import { decodePoolAccount } from "zolana-sdk-js/formats";
Install it only from a path you control. The repository says: “This project publishes no package under this or any other name; a package of this name on a registry is not this code.” The path install was checked with npm 11.6 and --offline: one linked package, no download.
What the readers check
formats.mjs follows the Rust decoders check for check, as far as plain JavaScript can. Each reader names the Rust function it follows, and each leaves something to the Rust code.
decodePaymentfollowswire::decode. It checks the length, the tag, the network, the public fields and their rules, canonical field elements, flags, the action count and the proof length. It leaves to Rust: the signatures, the proof, and that the keys of an action are curve points.decodeEnvelopefollowsenvelope::decode. It checks the framing, the payment id, the payment, and the expiry against a slot you pass. It leaves to Rust: re-encoding the payment to prove it canonical.paymentIdfollowsstaging::payload_digest.decodePoolAccountfollowsPoolState::decode. It checks both layouts, the header rules, the frontier’s shape, and the slot anchors and their order. It leaves to Rust: recomputing the tree root from the frontier.acceptedRootsfollowsPoolState::accepted_roots.checkAddressfollowsdecode_address. It checks the prefix, the length, the version, the checksum and the network tag. It leaves to Rust: that the address bytes are a valid shielded address.
Around the readers:
- Refusals carry the Rust error name. A refusal is a
FormatErrorwhosecodeis the name of the error the Rust decoder returns for the same bytes. - One list of bad inputs for both languages. The tests apply one list of changes,
sdk/fixtures/refusals.json, to both decoders. Three entries are marked there as ones the JavaScript reader cannot refuse, because the check needs curve arithmetic or the tree hash. - The explorer reader applies the feed contract.
explorer.mjsapplies the same contract as the Python checkvalidate_feedintools/devnet_explorer/explorer_pull_v0.py. The tests give both checks the same documents and require the same verdicts. - To verify a payment, use the Rust command. See Verify a payment offline.
Tests
node --test sdk/js/*.test.mjs
The repository records 30 tests for this command. Eight cover the JSON-RPC client, two compare the TypeScript description of the browser core with the Rust source, eight hold the offline readers to the values the Rust decoders report for the fixtures, four hold the explorer feed reader to the repository’s Python feed check, five run the JavaScript examples and compare the cookbook with them, and three check the package manifest and the declaration files.
The four explorer tests start python3. The pull-request workflow runs these tests; see Testing and verification.
Limits
- Not a wallet. No keys, no signing, no proof construction, no sync. That is the browser core and the logic in
clients/browser-wallet/product-worker.js. - Not a verifier. Nothing here checks a signature or a proof.
- Not run against a network. The client and the examples were tested with fixtures and loopback servers, not against a validator, a devnet gateway or a deployed explorer.
- The public devnet admits cohort wallets only. Develop against a local network. Devnet test coins are valueless and distinct from the ZOL token.
- Declarations are generated, and checked by name only. The
.d.mtsfiles were generated from the modules with TypeScript 5.9. TypeScript is not a dependency of the repository, so the test run only compares the exported names with the modules. - Platforms. Run on Apple Silicon macOS with Node 25.2 only.