Zolana
ExplorerDocsGitHubOpen wallet

Docs · Build on Zolana

JavaScript readers

Plain ES modules in the SDK that read a payment, the pool account, a shielded address and the explorer feed. No dependencies, no network, and nothing published to npm.

Status

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.

Modules in sdk/js
ModuleWhat it doesNeeds
rpc.mjsJSON-RPC client for the methods the wallets callfetch
formats.mjsOffline readers: a payment, an inline envelope, the payment id, the pool account, a shielded addressBigInt
explorer.mjsReads the devnet explorer feed and looks a transaction up in itnothing
index.mjsAll of the above from one module
zolana-browser-core.d.tsTypes for the Wasm core of the browser walleta 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:

JavaScript examples and their cookbook recipes
ExampleRecipe
examples/decode-payment.mjsDecode a payment
examples/check-address.mjsCheck an address
examples/watch-pool.mjsWatch the pool account
examples/payment-landed.mjsCheck 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";
Limit

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.

  • decodePayment follows wire::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.
  • decodeEnvelope follows envelope::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.
  • paymentId follows staging::payload_digest.
  • decodePoolAccount follows PoolState::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.
  • acceptedRoots follows PoolState::accepted_roots.
  • checkAddress follows decode_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 FormatError whose code is 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.mjs applies the same contract as the Python check validate_feed in tools/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.mts files 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.

Your privacy
has a boundary.

Zolana is an independent blockchain for native shielded deposits, private transfers and withdrawals. The browser wallet creates proofs and decrypts its own notes locally.

Shielded details

Payment amounts and receiving addresses are protected by proofs. Your spending and viewing keys stay on your device.

Public evidence

Blocks, timing, fees, nullifiers and public deposit or withdrawal accounts and amounts remain visible.

The invited gateway knows your membership and receiving address. It sees your IP address and request timing and can link your submissions. This is not a claim of complete anonymity.

Valueless test coins. No Solana bridge, SOL/USDC deposits, post-quantum protection or audited-security claim.