The JavaScript core is ledgdex in plain JavaScript. It has the same rules as the Python package, in ES modules in js/. It needs no dependencies, no npm and no build step.
It makes the same bytes, ids, signatures, states and pages as Python. On each push, tests compare the two with shared test vectors and with differential fuzzing.
The viewer uses the JavaScript core.
Where it runs: any current web browser, and Node 20 or later. The tests use Node 22. We did not test other JavaScript runtimes.
The modules:
core.js keys, messages, entries, Ledger (verify a ledger, add entries), newLedger
state.js state(ledger): offers, claims, auctions, disputes, admissions, ...
canon.js canonical JSON and hashes: canon, canonString, hash, parse
render.js the pages a ledgdex shows, and helpers such as amount and esc
sig.js signer(secret): Web Crypto Ed25519 when there is one, else the built-in code
keystore.js sealKey and openKey: a key sealed with a passphrase
ed25519.js sha.js dexweb.js zip.js the parts underneathThe API Reference shows each function, with its arguments.
To use the core in a web page, load it from the ledgdex site, as a module:
<script type='module'>
import { Ledger } from 'https://ledgdex.github.io/viewer/core.js';
import { state } from 'https://ledgdex.github.io/viewer/state.js';
</script>This always gives the latest published core. For your own site, copy js/ from a release (for example the v1.0.18 tag) to your site, and load it from there.
A script from a different site can change without your knowledge, and it runs with the rights of your page.
In Node, import the files from a copy of js/, as the examples do.
Use the JavaScript core for these jobs:
1. Verify ledgers in the browser of the reader, so that nobody has to trust your server. Example: Shop Web Page shows the offers of a seller on the website of the seller.
2. Buy with nothing to install. A buyer keeps a sealed key in the browser, signs orders and keeps its own ledger, as the viewer does. See Example: Sign in the Browser.
3. Write programs and bots in JavaScript that read, verify and follow ledgers in Node. See Example: Verify in Node.
4. Make ledgers and messages in code, as the Python library does. See Example: JavaScript.
Use Python for the command line and for all work over time. Only the Python package has these functions:
- publishing a dex with dexweb
- ledgdex check, with its kept copies and receipts
- collecting messages from many dexes with record --from
- keys on disk, and the daily workflow that runs ledgdex check
The JavaScript core has no command line, and it does not publish.
Ledgers on other sites: a page can always read files from its own site. To read the ledgdex.jsonl of a different site, that site must allow it (CORS).
GitHub Pages allows it for all sites that it serves. If a host does not allow it, download the file and open it, as the viewer lets you do.
Keys in a browser: never store a secret key as plain data. sealKey(secret, passphrase, publicKey) gives a sealed box that you can store.
The box uses PBKDF2-SHA-256 with 600,000 rounds, then AES-256-GCM. The passphrase has 12 characters or more. openKey(box, passphrase) opens the box.
All pages on one site can read the data that the site stores. So keep keys on a site that serves nothing else that you do not control.
signer(secret) signs with the constant-time Ed25519 of the browser (Web Crypto) when the browser has it.
To verify signatures, the core always uses its built-in code. So all browsers judge a ledger in the same way.
Remember these points:
- All data in a ledger comes from someone else. Put its text on a page with textContent, or through esc from render.js. Never put it on a page as raw HTML.
- Verify the ledger, and read whole, before you trust anything in it.