Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 3 additions & 15 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ This file provides guidance for AI agents and automated tools working on this co

## Project Overview

**znn-typescript-sdk** is a TypeScript/JavaScript SDK for interacting with the Zenon Network of Momentum (NoM). It supports Node.js (ESM) and browsers (ESM + UMD), includes a CLI, and ships a pre-built WebAssembly PoW module.
**znn-typescript-sdk** is a TypeScript/JavaScript SDK for interacting with the Zenon Network of Momentum (NoM). It supports Node.js and browsers (ESM), includes a CLI, and ships a pre-built WebAssembly PoW module.

- **Package name:** `znn-typescript-sdk`
- **License:** MIT
Expand Down Expand Up @@ -41,10 +41,9 @@ dist/ # Build output (gitignored)

```bash
npm install # Install dependencies
npm run build # Full build: lint + ESM + CLI + browser bundles
npm run build # Full build: lint + ESM + CLI
npm run build:esm # TypeScript → dist/ (ESM)
npm run build:cli # Webpack CLI bundle → dist/cli/cli.cjs
npm run build:browser # Webpack browser bundle → dist/browser/
npm run build:wasm # Rebuild PoW WASM (requires Emscripten)
npm run lint # ESLint (src, cli, test)
npm run lint:fix # ESLint with auto-fix
Expand All @@ -54,7 +53,7 @@ npm run cli:dev # Build CLI and run it locally
npm run clean # Remove dist/, coverage/, .nyc_output/
```

The full `npm run build` pipeline runs: `clean → lint → build:esm → build:cli → build:browser`.
The full `npm run build` pipeline runs: `clean → lint → build:esm → build:cli`.

---

Expand Down Expand Up @@ -164,17 +163,6 @@ The SDK includes a WebAssembly PoW module (`lib/pow.js` + `lib/pow.wasm`).

---

## Browser Bundles

| Bundle | Path | Usage |
|---|---|---|
| ESM | `dist/browser/bundle.browser.mjs` | Vite / Rollup / Webpack |
| UMD | `dist/browser/bundle.browser.js` | `<script>` tag → `window.ZnnSDK` |

Prefer ESM. UMD is only for script-tag usage without a bundler.

---

## CLI

The CLI is compiled to `dist/cli/cli.cjs` and exposed as the `znn-cli` binary.
Expand Down
25 changes: 7 additions & 18 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ A TypeScript/JavaScript SDK for interacting with the Zenon Network of Momentum (
- 🔐 **Transaction signing** – Sign and send transactions with automatic PoW generation
- ⌨️ **CLI Included** – CLI for wallet management and sending transactions
- 📡 **Real-time subscriptions** – Subscribe to momentums and account blocks via WebSocket
- 🌐 **Universal** – Works in Node.js and browsers (ESM & UMD)
- 🌐 **Universal** – Works in Node.js and browsers (ESM)
- 📝 **TypeScript native** – Full type definitions included

---
Expand Down Expand Up @@ -52,48 +52,37 @@ const zenon = Zenon.getInstance();
await zenon.initialize('wss://node.zenonhub.io:35998');
```

#### Browser Builds (ESM vs UMD)
#### Browser Builds

The SDK ships two browser bundles:

- **ESM** (`dist/browser/bundle.browser.mjs`): Modern module build for Vite/Rollup/Webpack. Import from `znn-typescript-sdk` or the `.mjs` bundle.
- **UMD** (`dist/browser/bundle.browser.js`): Legacy global build that exposes `window.ZnnSDK` for script-tag usage.

Use ESM when possible. Use UMD only if you must load the SDK via a `<script>` tag without a bundler.
The SDK ships as modular ESM only and is imported from `znn-typescript-sdk` in any bundler (Vite, Rollup, Webpack). `KeyFile` loads its Argon2 implementation as a dynamic chunk, so set `output.publicPath` (or the Vite equivalent) for wallet unlock to work.

#### Browser PoW Configuration

The Proof of Work (PoW) module requires two external files in browser environments: `pow.js` and `pow.wasm`. These files must be accessible at runtime.

**Setup:**

1. The PoW files are located in `node_modules/znn-typescript-sdk/dist/browser`
1. The PoW files are located in `node_modules/znn-typescript-sdk/lib`
2. Set the base path before any operations that require PoW:

```javascript
import { Zenon } from 'znn-typescript-sdk';

// Point to where pow.js and pow.wasm are located
Zenon.setPowBasePath('node_modules/znn-typescript-sdk/dist/browser');
Zenon.setPowBasePath('node_modules/znn-typescript-sdk/lib');

// Now you can send transactions (which use PoW)
const zenon = Zenon.getInstance();
await zenon.initialize('wss://node.zenonhub.io:35998');
const tx = await zenon.send(blockTemplate, keyPair);
```

**For UMD:**

```javascript
window.ZnnSDK.Zenon.setPowBasePath('node_modules/znn-typescript-sdk/dist/browser');
```

**Alternative – Copy to Public Folder:**

For production apps, copy the PoW files to your public/static folder:

```bash
cp node_modules/znn-typescript-sdk/dist/browser/pow.* public/
cp node_modules/znn-typescript-sdk/lib/pow.* public/
```

Then set the path:
Expand Down Expand Up @@ -164,7 +153,7 @@ Set the base path for loading PoW files in browser environments. Only needed for
```javascript
// Before initialization in browser
// These are all valid and will be normalized automatically:
Zenon.setPowBasePath('node_modules/znn-typescript-sdk/dist/browser');
Zenon.setPowBasePath('node_modules/znn-typescript-sdk/lib');
Zenon.setPowBasePath('/assets');
Zenon.setPowBasePath('./public');
```
Expand Down
2 changes: 1 addition & 1 deletion docs/examples.md
Original file line number Diff line number Diff line change
Expand Up @@ -77,7 +77,7 @@ When using the SDK in a browser, you must configure the PoW module path before s
import { Zenon } from 'znn-typescript-sdk';

// Set the path where pow.js and pow.wasm are located
Zenon.setPowBasePath('node_modules/znn-typescript-sdk/dist/browser');
Zenon.setPowBasePath('node_modules/znn-typescript-sdk/lib');

// Or if you copied the files to your public folder
Zenon.setPowBasePath('/');
Expand Down
Loading
Loading