shell-sdk 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,31 @@
+# Changelog
+
+## [0.2.0] — 2026-04-14
+
+### Added
+- **API freeze**: `ShellSigner`, `ShellProvider`, and `ShellWallet` are now stable public APIs.
+- ML-DSA-65 cross-validation tests confirming wire compatibility with `pqcrypto-dilithium` v0.5 (pk=1952 B, sk=4032 B, sig=3309 B).
+- `examples/minimal-dapp`: Node.js (`node-demo.mjs`) and browser (`browser-demo.html`) integration examples.
+- JSDoc complete for all public-facing exports.
+- `MlDsa65Adapter` round-trip sign+verify test.
+
+### Changed
+- `adapters.ts`: both `"Dilithium3"` and `"MlDsa65"` aliases now explicitly document ML-DSA-65 (FIPS 204) wire compatibility with the chain's Dilithium3 verifier.
+- `hashTransaction()` canonical RLP field ordering aligned with `shell-chain` deserialiser.
+- Package root export surface narrowed to stable application-facing APIs.
+
+
+
+- **Signing compatibility confirmed**: `pqcrypto-dilithium` v0.5 (shell-chain) implements FIPS 204 ML-DSA-65, byte-identical with `@noble/post-quantum` `ml_dsa65`. The `Dilithium3` alias in the SDK now documents this equivalence explicitly (pk=1952, sk=4032, sig=3309 bytes).
+- add cross-validation tests verifying ML-DSA-65 key/signature sizes against chain expectations
+- add `MlDsa65Adapter` round-trip sign+verify test
+- clarify `adapters.ts` JSDoc: both `"Dilithium3"` and `"MlDsa65"` route to ML-DSA-65 (FIPS 204) which is wire-compatible with the chain's Dilithium3 verifier
+
+## 0.2.0-rc.1
+
+- add Browser and Node integration tests for signer, keystore, and provider flows
+- add Rust compatibility vectors for address derivation and transaction hashing
+- fix `hashTransaction()` to match the Rust node's canonical RLP field ordering
+- fix `hashTransaction()` to accept canonical `pq1...` recipient addresses
+- narrow the package root export surface to stable application-facing APIs
+- document extension background flow, minimal dApp usage, and release checklist

package/README.md

@@ -22,10 +22,13 @@
   - [System contracts](#system-contracts)
   - [Keystore](#keystore)
 - [End-to-end examples](#end-to-end-examples)
+  - [Wallet extension background flow](#wallet-extension-background-flow)
+  - [Minimal dApp flow](#minimal-dapp-flow)
 - [Key rotation](#key-rotation)
 - [Error handling](#error-handling)
 - [TypeScript types reference](#typescript-types-reference)
 - [Compatibility](#compatibility)
+- [Release checklist](#release-checklist)
 - [Chain reference](#chain-reference)
 
 ---
@@ -128,6 +131,8 @@ These are sent as ordinary transactions whose `to` field is the AccountManager a
 
 ## Module reference
 
+The package root (`shell-sdk`) is the **stable surface** for typical app usage. Lower-level constants and helpers that are more likely to change remain available from subpath imports such as `shell-sdk/signer` and `shell-sdk/transactions`.
+
 ### Types
 
 Defined in `src/types.ts`. All types are re-exported from the package root.
@@ -434,9 +439,11 @@ const signed = buildSignedTransaction({
 
 #### `hashTransaction`
 
-RLP-encode a `ShellTransactionRequest` and return its **keccak256** hash as a `Uint8Array`. This is the value you must pass as `txHash` to `signer.buildSignedTransaction`.
+RLP-encode a `ShellTransactionRequest` using the Rust node's canonical field order and return its **keccak256** hash as a `Uint8Array`. This is the value you must pass as `txHash` to `signer.buildSignedTransaction`.
+
+Shell Chain signs the full unsigned transaction payload in this order:
 
-Shell Chain computes the signing hash identically to Ethereum EIP-1559: `keccak256(RLP([chainId, nonce, maxPriorityFeePerGas, maxFeePerGas, gasLimit, to, value, data, accessList]))`.
+`[chainId, nonce, to, value, data, gasLimit, maxFeePerGas, maxPriorityFeePerGas, accessList, txType, blobFeeFlag, maxFeePerBlobGas, blobVersionedHashes]`
 
 ```typescript
 import { buildTransferTransaction, hashTransaction } from "shell-sdk/transactions";
@@ -620,6 +627,55 @@ console.log(hash);
 
 ---
 
+### Wallet extension background flow
+
+This is the recommended shape for a Chrome extension background worker: keep the decrypted signer only in memory, fetch the latest nonce from RPC, and use the stable root entrypoint for the common path.
+
+```typescript
+import { createShellProvider, buildTransferTransaction, hashTransaction } from "shell-sdk";
+
+async function submitTransfer({ signer, to, value, rpcHttpUrl }: {
+  signer: { getHexAddress(): `0x${string}`; buildSignedTransaction(args: { tx: unknown; txHash: Uint8Array; includePublicKey?: boolean }): Promise<unknown> };
+  to: string;
+  value: bigint;
+  rpcHttpUrl: string;
+}) {
+  const provider = createShellProvider({ rpcHttpUrl });
+  const nonce = await provider.client.getTransactionCount({ address: signer.getHexAddress() });
+
+  const tx = buildTransferTransaction({
+    chainId: 424242,
+    nonce,
+    to,
+    value,
+  });
+  const txHash = hashTransaction(tx);
+  const signed = await signer.buildSignedTransaction({ tx, txHash, includePublicKey: nonce === 0 });
+
+  return provider.sendTransaction(signed);
+}
+```
+
+### Minimal dApp flow
+
+For a lightweight web app, keep the provider in the page and delegate signing to an injected wallet or background bridge:
+
+```typescript
+import { createShellProvider, normalizePqAddress } from "shell-sdk";
+
+const provider = createShellProvider({
+  rpcHttpUrl: "https://rpc.testnet.shell.network",
+});
+
+const account = normalizePqAddress("0x1234...abcd");
+const history = await provider.getTransactionsByAddress(account, { page: 1, limit: 10 });
+
+console.log("recent txs:", history.transactions);
+console.log("total:", history.total);
+```
+
+---
+
 ## Key rotation
 
 Shell Chain accounts support **key rotation** — replacing the signing key without changing the account address. This is a critical security feature for post-quantum safety.
@@ -755,6 +811,19 @@ interface ShellSignature {
 
 ---
 
+## Release checklist
+
+Before publishing a `shell-sdk` release candidate:
+
+1. Run `npm test` and `npm run typecheck`.
+2. Confirm the stable root surface still excludes low-level helpers such as `hexBytes` and internal signer maps.
+3. Verify Browser + Node integration tests both cover signer, keystore, and provider RPC flows.
+4. Review README examples against the current public exports (`shell-sdk`, `shell-sdk/signer`, `shell-sdk/transactions`).
+5. Check `package.json` `exports`, `files`, `version`, and repository metadata.
+6. Build once from a clean tree and smoke-import the package root plus subpaths from `dist/`.
+
+---
+
 ## Chain reference
 
 | Parameter | Value |

package/dist/adapters.d.ts

@@ -1,8 +1,15 @@
 /**
  * Concrete SignerAdapter implementations for each PQ algorithm.
  *
- * @noble/post-quantum provides ML-DSA-65 and SLH-DSA-SHA2-256f.
- * Dilithium3 (pre-FIPS Round-3) uses {@link MlDsa65Adapter} as a stand-in.
+ * `@noble/post-quantum` provides ML-DSA-65 and SLH-DSA-SHA2-256f via
+ * WebAssembly-accelerated pure-JS implementations.
+ *
+ * **Dilithium3 compatibility note**: `pqcrypto-dilithium` v0.5 (used by
+ * shell-chain) implements ML-DSA-65 (FIPS 204) under the `dilithium3` name.
+ * `@noble/post-quantum` `ml_dsa65` produces byte-identical keys and
+ * signatures (pk=1952, sk=4032, sig=3309), so `MlDsa65Adapter` is fully
+ * wire-compatible with the chain's Dilithium3 verifier. Both `"Dilithium3"`
+ * and `"MlDsa65"` algorithm names route to the same adapter.
  *
  * @module adapters
  */
@@ -45,8 +52,10 @@ export declare function generateSlhDsaKeyPair(seed?: Uint8Array): SlhDsaKeyPair;
 /**
  * {@link SignerAdapter} for ML-DSA-65 (NIST FIPS 204).
  *
- * Also used as the implementation for `"Dilithium3"` (the pre-standardisation
- * Round-3 variant) since the wire format is compatible.
+ * This is the primary signing adapter for Shell Chain. It is also used for
+ * `"Dilithium3"` keys since `pqcrypto-dilithium` v0.5 (the Rust crate used
+ * by shell-chain) implements FIPS 204 ML-DSA-65 — producing byte-identical
+ * keys and signatures (pk=1952 bytes, sk=4032 bytes, sig=3309 bytes).
  *
  * @example
  * ```typescript

package/dist/adapters.js

@@ -1,8 +1,15 @@
 /**
  * Concrete SignerAdapter implementations for each PQ algorithm.
  *
- * @noble/post-quantum provides ML-DSA-65 and SLH-DSA-SHA2-256f.
- * Dilithium3 (pre-FIPS Round-3) uses {@link MlDsa65Adapter} as a stand-in.
+ * `@noble/post-quantum` provides ML-DSA-65 and SLH-DSA-SHA2-256f via
+ * WebAssembly-accelerated pure-JS implementations.
+ *
+ * **Dilithium3 compatibility note**: `pqcrypto-dilithium` v0.5 (used by
+ * shell-chain) implements ML-DSA-65 (FIPS 204) under the `dilithium3` name.
+ * `@noble/post-quantum` `ml_dsa65` produces byte-identical keys and
+ * signatures (pk=1952, sk=4032, sig=3309), so `MlDsa65Adapter` is fully
+ * wire-compatible with the chain's Dilithium3 verifier. Both `"Dilithium3"`
+ * and `"MlDsa65"` algorithm names route to the same adapter.
  *
  * @module adapters
  */
@@ -41,8 +48,10 @@ export function generateSlhDsaKeyPair(seed) {
 /**
  * {@link SignerAdapter} for ML-DSA-65 (NIST FIPS 204).
  *
- * Also used as the implementation for `"Dilithium3"` (the pre-standardisation
- * Round-3 variant) since the wire format is compatible.
+ * This is the primary signing adapter for Shell Chain. It is also used for
+ * `"Dilithium3"` keys since `pqcrypto-dilithium` v0.5 (the Rust crate used
+ * by shell-chain) implements FIPS 204 ML-DSA-65 — producing byte-identical
+ * keys and signatures (pk=1952 bytes, sk=4032 bytes, sig=3309 bytes).
  *
  * @example
  * ```typescript
@@ -86,7 +95,7 @@ export class MlDsa65Adapter {
      * @param message - The bytes to sign (typically an RLP-encoded tx hash).
      */
     async sign(message) {
-        return ml_dsa65.sign(this._secretKey, message);
+        return ml_dsa65.sign(message, this._secretKey);
     }
 }
 /**
@@ -134,7 +143,7 @@ export class SlhDsaAdapter {
      * @param message - The bytes to sign (typically an RLP-encoded tx hash).
      */
     async sign(message) {
-        return slh_dsa_sha2_256f.sign(this._secretKey, message);
+        return slh_dsa_sha2_256f.sign(message, this._secretKey);
     }
 }
 /**

package/dist/index.d.ts

@@ -1,8 +1,8 @@
 export { bytesToHexAddress, PQ_ADDRESS_HRP, PQ_ADDRESS_LENGTH, PQ_ADDRESS_VERSION_V1, bytesToPqAddress, derivePqAddressFromPublicKey, isPqAddress, normalizeHexAddress, normalizePqAddress, pqAddressVersion, pqAddressToBytes, } from "./address.js";
 export { createShellProvider, createShellPublicClient, createShellWsClient, ShellProvider, shellDevnet, type CreateShellPublicClientOptions, } from "./provider.js";
 export { accountManagerAddress, accountManagerHexAddress, clearValidationCodeSelector, encodeClearValidationCodeCalldata, encodeRotateKeyCalldata, encodeSetValidationCodeCalldata, isSystemContractAddress, rotateKeySelector, setValidationCodeSelector, validatorRegistryAddress, validatorRegistryHexAddress, } from "./system-contracts.js";
-export { buildClearValidationCodeTransaction, buildRotateKeyTransaction, buildSetValidationCodeTransaction, buildSignature, buildSignedTransaction, buildSystemTransaction, buildTransaction, buildTransferTransaction, DEFAULT_MAX_FEE_PER_GAS, DEFAULT_MAX_PRIORITY_FEE_PER_GAS, DEFAULT_SYSTEM_GAS_LIMIT, DEFAULT_TRANSFER_GAS_LIMIT, DEFAULT_TX_TYPE, hashTransaction, hexBytes, } from "./transactions.js";
+export { buildClearValidationCodeTransaction, buildRotateKeyTransaction, buildSetValidationCodeTransaction, buildSignature, buildSignedTransaction, buildSystemTransaction, buildTransaction, buildTransferTransaction, DEFAULT_MAX_FEE_PER_GAS, DEFAULT_MAX_PRIORITY_FEE_PER_GAS, DEFAULT_SYSTEM_GAS_LIMIT, DEFAULT_TRANSFER_GAS_LIMIT, DEFAULT_TX_TYPE, hashTransaction, } from "./transactions.js";
 export { assertSignerMatchesKeystore, decryptKeystore, exportEncryptedKeyJson, parseEncryptedKey, validateEncryptedKeyAddress, type ParsedShellKeystore, } from "./keystore.js";
 export { adapterFromKeyPair, generateAdapter, generateMlDsa65KeyPair, generateSlhDsaKeyPair, MlDsa65Adapter, SlhDsaAdapter, type MlDsa65KeyPair, type SlhDsaKeyPair, } from "./adapters.js";
-export { buildShellSignature, KEY_TYPE_TO_SIGNATURE_TYPE, publicKeyFromHex, ShellSigner, SIGNATURE_TYPE_IDS, signatureTypeFromKeyType, type SignerAdapter, } from "./signer.js";
+export { buildShellSignature, publicKeyFromHex, ShellSigner, signatureTypeFromKeyType, type SignerAdapter, } from "./signer.js";
 export type { AddressLike, HexString, ShellAccessListItem, ShellCipherParams, ShellEncryptedKey, ShellSendTransactionParams, ShellKdfParams, ShellSignature, ShellTransactionRequest, ShellTxByAddressPage, SignedShellTransaction, SignatureTypeName, } from "./types.js";

package/dist/index.js

@@ -1,7 +1,7 @@
 export { bytesToHexAddress, PQ_ADDRESS_HRP, PQ_ADDRESS_LENGTH, PQ_ADDRESS_VERSION_V1, bytesToPqAddress, derivePqAddressFromPublicKey, isPqAddress, normalizeHexAddress, normalizePqAddress, pqAddressVersion, pqAddressToBytes, } from "./address.js";
 export { createShellProvider, createShellPublicClient, createShellWsClient, ShellProvider, shellDevnet, } from "./provider.js";
 export { accountManagerAddress, accountManagerHexAddress, clearValidationCodeSelector, encodeClearValidationCodeCalldata, encodeRotateKeyCalldata, encodeSetValidationCodeCalldata, isSystemContractAddress, rotateKeySelector, setValidationCodeSelector, validatorRegistryAddress, validatorRegistryHexAddress, } from "./system-contracts.js";
-export { buildClearValidationCodeTransaction, buildRotateKeyTransaction, buildSetValidationCodeTransaction, buildSignature, buildSignedTransaction, buildSystemTransaction, buildTransaction, buildTransferTransaction, DEFAULT_MAX_FEE_PER_GAS, DEFAULT_MAX_PRIORITY_FEE_PER_GAS, DEFAULT_SYSTEM_GAS_LIMIT, DEFAULT_TRANSFER_GAS_LIMIT, DEFAULT_TX_TYPE, hashTransaction, hexBytes, } from "./transactions.js";
+export { buildClearValidationCodeTransaction, buildRotateKeyTransaction, buildSetValidationCodeTransaction, buildSignature, buildSignedTransaction, buildSystemTransaction, buildTransaction, buildTransferTransaction, DEFAULT_MAX_FEE_PER_GAS, DEFAULT_MAX_PRIORITY_FEE_PER_GAS, DEFAULT_SYSTEM_GAS_LIMIT, DEFAULT_TRANSFER_GAS_LIMIT, DEFAULT_TX_TYPE, hashTransaction, } from "./transactions.js";
 export { assertSignerMatchesKeystore, decryptKeystore, exportEncryptedKeyJson, parseEncryptedKey, validateEncryptedKeyAddress, } from "./keystore.js";
 export { adapterFromKeyPair, generateAdapter, generateMlDsa65KeyPair, generateSlhDsaKeyPair, MlDsa65Adapter, SlhDsaAdapter, } from "./adapters.js";
-export { buildShellSignature, KEY_TYPE_TO_SIGNATURE_TYPE, publicKeyFromHex, ShellSigner, SIGNATURE_TYPE_IDS, signatureTypeFromKeyType, } from "./signer.js";
+export { buildShellSignature, publicKeyFromHex, ShellSigner, signatureTypeFromKeyType, } from "./signer.js";

package/dist/transactions.d.ts

@@ -190,8 +190,8 @@ export declare function hexBytes(bytes: Uint8Array): HexString;
  * `keccak256(RLP(tx))` — the same scheme as Ethereum EIP-1559 signing.
  *
  * **Encoding order** (EIP-2718 type-2 fields):
- * chainId, nonce, maxPriorityFeePerGas, maxFeePerGas, gasLimit,
- * to, value, data, accessList, maxFeePerBlobGas (if present), blobVersionedHashes (if present)
+ * chainId, nonce, to, value, data, gasLimit, maxFeePerGas, maxPriorityFeePerGas,
+ * accessList, txType, blobFeeFlag, maxFeePerBlobGas, blobVersionedHashes
  *
  * @example
  * ```typescript

package/dist/transactions.js

@@ -7,8 +7,9 @@
  *
  * @module transactions
  */
-import { bytesToHex, keccak256, toRlp, numberToHex, hexToBytes } from "viem";
+import { bytesToHex, keccak256, toRlp, hexToBytes } from "viem";
 import { accountManagerAddress, encodeClearValidationCodeCalldata, encodeRotateKeyCalldata, encodeSetValidationCodeCalldata, } from "./system-contracts.js";
+import { normalizeHexAddress } from "./address.js";
 /** Default transaction type: `2` (EIP-1559). */
 export const DEFAULT_TX_TYPE = 2;
 /** Default gas limit for simple SHELL token transfers (`21_000`). */
@@ -25,6 +26,22 @@ function toByteArray(bytes) {
 function toHexData(data) {
     return data ?? "0x";
 }
+function toRlpUint(value) {
+    const numeric = typeof value === "string" ? BigInt(value) : BigInt(value);
+    if (numeric === 0n) {
+        return "0x";
+    }
+    return `0x${numeric.toString(16)}`;
+}
+function toRlpAccessList(accessList) {
+    if (!accessList || accessList.length === 0) {
+        return [];
+    }
+    return accessList.map((item) => [
+        normalizeHexAddress(item.address),
+        item.storage_keys.map((key) => key),
+    ]);
+}
 /**
  * Low-level transaction builder that maps camelCase options to the
  * snake_case wire format expected by the Shell node.
@@ -210,8 +227,8 @@ export function hexBytes(bytes) {
  * `keccak256(RLP(tx))` — the same scheme as Ethereum EIP-1559 signing.
  *
  * **Encoding order** (EIP-2718 type-2 fields):
- * chainId, nonce, maxPriorityFeePerGas, maxFeePerGas, gasLimit,
- * to, value, data, accessList, maxFeePerBlobGas (if present), blobVersionedHashes (if present)
+ * chainId, nonce, to, value, data, gasLimit, maxFeePerGas, maxPriorityFeePerGas,
+ * accessList, txType, blobFeeFlag, maxFeePerBlobGas, blobVersionedHashes
  *
  * @example
  * ```typescript
@@ -226,24 +243,21 @@ export function hexBytes(bytes) {
  * @returns 32-byte keccak256 hash as a `Uint8Array`.
  */
 export function hashTransaction(tx) {
-    const to = tx.to ? hexToBytes(tx.to.startsWith("0x") ? tx.to : `0x${tx.to}`) : new Uint8Array(0);
-    const data = hexToBytes(tx.data);
-    const value = hexToBytes(tx.value);
     const fields = [
-        numberToHex(tx.chain_id),
-        numberToHex(tx.nonce),
-        numberToHex(tx.max_priority_fee_per_gas),
-        numberToHex(tx.max_fee_per_gas),
-        numberToHex(tx.gas_limit),
-        bytesToHex(to),
-        bytesToHex(value),
-        bytesToHex(data),
-        "0x", // empty access list
+        toRlpUint(tx.chain_id),
+        toRlpUint(tx.nonce),
+        tx.to ? normalizeHexAddress(tx.to) : "0x",
+        toRlpUint(tx.value),
+        tx.data,
+        toRlpUint(tx.gas_limit),
+        toRlpUint(tx.max_fee_per_gas),
+        toRlpUint(tx.max_priority_fee_per_gas),
+        toRlpAccessList(tx.access_list),
+        toRlpUint(tx.tx_type ?? DEFAULT_TX_TYPE),
+        toRlpUint(tx.max_fee_per_blob_gas != null ? 1 : 0),
+        toRlpUint(tx.max_fee_per_blob_gas ?? 0),
+        (tx.blob_versioned_hashes ?? []).map((hash) => hash),
     ];
-    if (tx.max_fee_per_blob_gas != null) {
-        fields.push(numberToHex(tx.max_fee_per_blob_gas));
-        fields.push("0x"); // empty blob versioned hashes
-    }
     const rlpEncoded = toRlp(fields);
     const hash = hexToBytes(keccak256(rlpEncoded));
     return hash;

package/examples/minimal-dapp/README.md

@@ -0,0 +1,59 @@
+# Shell SDK — Minimal dApp Example
+
+Demonstrates the core Shell SDK flow:
+1. Generate a post-quantum key pair (ML-DSA-65)
+2. Create a signer and derive address
+3. Query balance from a Shell node
+4. Build + sign a transaction (without broadcasting)
+
+## Node.js (server / CLI)
+
+```bash
+# From the shell-sdk root:
+npm install
+npm run build
+
+# Run the demo (points at localhost:8545 by default)
+node examples/minimal-dapp/node-demo.mjs
+
+# Point at a different RPC endpoint:
+SHELL_RPC_URL=http://my-node:8545 node examples/minimal-dapp/node-demo.mjs
+```
+
+Expected output:
+```
+Address (pq1…): pq1…
+Address (0x…): 0x…
+Balance (wei): 0   ← 0 for a fresh account; fund it via the faucet
+Signed tx type: 2
+Signature length (bytes): 3309
+Sender pubkey set: true
+
+All done! Connect to a live node and call provider.sendTransaction(signed) to broadcast.
+```
+
+## Browser
+
+```bash
+# Build the SDK first
+cd ../../  # shell-sdk root
+npm run build
+
+# Serve this directory with any HTTP server
+npx serve examples/minimal-dapp/
+# or
+python3 -m http.server 8080
+```
+
+Then open `http://localhost:8080/browser-demo.html` in your browser.
+
+## Key sizes (ML-DSA-65 / FIPS 204)
+
+| Field       | Bytes |
+|-------------|-------|
+| Public key  | 1952  |
+| Secret key  | 4032  |
+| Signature   | 3309  |
+
+These match `pqcrypto-dilithium` v0.5 (used by shell-chain), confirming wire
+compatibility. Both `"Dilithium3"` and `"MlDsa65"` keys use this algorithm.

package/examples/minimal-dapp/browser-demo.html

@@ -0,0 +1,98 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <title>Shell SDK — Minimal Browser dApp</title>
+    <style>
+      body { font-family: monospace; max-width: 800px; margin: 2rem auto; padding: 0 1rem; }
+      pre  { background: #1a1a1a; color: #d4d4d4; padding: 1rem; border-radius: 4px; overflow-x: auto; }
+      button { padding: .5rem 1.2rem; cursor: pointer; margin: .25rem; }
+      #log { white-space: pre-wrap; }
+    </style>
+  </head>
+  <body>
+    <h1>Shell SDK — Minimal Browser dApp</h1>
+    <p>This page runs entirely in the browser using ES modules from a CDN (or local build).</p>
+
+    <button onclick="generateKey()">1. Generate Key</button>
+    <button onclick="queryBalance()">2. Query Balance</button>
+    <button onclick="buildTx()">3. Build &amp; Sign Tx</button>
+
+    <pre id="log">Click a button to start…</pre>
+
+    <script type="module">
+      // Adjust the import path to your local build or CDN URL.
+      // e.g. import { MlDsa65Adapter, ... } from "./shell-sdk.esm.js";
+      // For local dev: `cd shell-sdk && npm run build` then serve this folder.
+      const SDK_URL = "./../../dist/index.js";
+
+      let signer = null;
+
+      function log(...args) {
+        const el = document.getElementById("log");
+        el.textContent += args.map(String).join(" ") + "\n";
+      }
+
+      async function loadSdk() {
+        try {
+          return await import(SDK_URL);
+        } catch (e) {
+          log("Failed to load SDK:", e.message);
+          log("Make sure you have run `npm run build` in the shell-sdk directory");
+          log("and are serving this file from an HTTP server (not file://).");
+          throw e;
+        }
+      }
+
+      window.generateKey = async function () {
+        const { MlDsa65Adapter, ShellSigner } = await loadSdk();
+        const adapter = MlDsa65Adapter.generate();
+        signer = new ShellSigner("MlDsa65", adapter);
+        log("=== Key Generated ===");
+        log("Address (pq1…):", signer.getAddress());
+        log("Address (0x…):", signer.getHexAddress());
+        log("Public key size:", adapter.getPublicKey().length, "bytes");
+      };
+
+      window.queryBalance = async function () {
+        if (!signer) { log("Generate a key first!"); return; }
+        const { createShellProvider } = await loadSdk();
+        const rpc = prompt("RPC URL?", "http://127.0.0.1:8545");
+        if (!rpc) return;
+        const provider = createShellProvider({ url: rpc });
+        try {
+          const bal = await provider.getBalance({ address: signer.getHexAddress() });
+          log("Balance:", bal.toString(), "wei");
+        } catch (e) {
+          log("getBalance error:", e.message);
+        }
+      };
+
+      window.buildTx = async function () {
+        if (!signer) { log("Generate a key first!"); return; }
+        const { hashTransaction } = await loadSdk();
+        const tx = {
+          from: signer.getHexAddress(),
+          chain_id: 1337,
+          nonce: 0,
+          to: "0x0000000000000000000000000000000000000001",
+          value: "0x1",
+          data: "0x",
+          gas_limit: 21000,
+          max_fee_per_gas: 1_000_000_000,
+          max_priority_fee_per_gas: 1_000_000_000,
+        };
+        const txHash = hashTransaction(tx);
+        const signed = await signer.buildSignedTransaction({ tx, txHash, includePublicKey: true });
+        log("=== Signed Transaction ===");
+        log("Type:", signed.type);
+        log("From:", signed.from);
+        log("To:", signed.to);
+        log("Value:", signed.value.toString());
+        log("Sig length:", signed.signature.data.length, "bytes");
+        log("Has pubkey:", signed.sender_pubkey != null);
+        log("\nCall provider.sendTransaction(signed) to broadcast to a live node.");
+      };
+    </script>
+  </body>
+</html>

package/examples/minimal-dapp/node-demo.mjs

@@ -0,0 +1,68 @@
+/**
+ * Shell SDK minimal dApp — Node.js script
+ *
+ * Demonstrates: connect provider → query balance → sign + build transaction
+ *
+ * Usage:
+ *   npm install shell-sdk
+ *   node node-demo.mjs
+ *
+ * By default this points at the Shell devnet RPC. Set SHELL_RPC_URL to
+ * override.
+ */
+
+import { MlDsa65Adapter, ShellSigner, createShellProvider } from "shell-sdk";
+
+const RPC_URL = process.env.SHELL_RPC_URL ?? "http://127.0.0.1:8545";
+
+async function main() {
+  // ── 1. Create a provider ──────────────────────────────────────────────
+  const provider = createShellProvider({ url: RPC_URL });
+
+  // ── 2. Generate a key pair and build a signer ─────────────────────────
+  const adapter = MlDsa65Adapter.generate();
+  const signer = new ShellSigner("MlDsa65", adapter);
+
+  console.log("Address (pq1…):", signer.getAddress());
+  console.log("Address (0x…):", signer.getHexAddress());
+
+  // ── 3. Query balance ───────────────────────────────────────────────────
+  try {
+    const balance = await provider.client.getBalance({ address: signer.getHexAddress() });
+    console.log("Balance (wei):", balance.toString());
+  } catch (err) {
+    console.warn("getBalance failed (node may not be running):", err.message);
+  }
+
+  // ── 4. Build and sign a transaction ───────────────────────────────────
+  // NOTE: sending requires a funded account + live node.
+  // This section shows the sign-only flow without broadcasting.
+  const TO = "0x0000000000000000000000000000000000000001";
+
+  /** @type {import("shell-sdk").ShellTransactionRequest} */
+  const tx = {
+    from: signer.getHexAddress(),
+    chain_id: 1337,
+    nonce: 0,
+    to: TO,
+    value: "0x1",
+    data: "0x",
+    gas_limit: 21000,
+    max_fee_per_gas: 1_000_000_000,
+    max_priority_fee_per_gas: 1_000_000_000,
+  };
+
+  const { hashTransaction } = await import("shell-sdk");
+  const txHash = hashTransaction(tx);
+  const signed = await signer.buildSignedTransaction({ tx, txHash, includePublicKey: true });
+  console.log("Signed tx type:", signed.tx.tx_type ?? 2, "(EIP-1559)");
+  console.log("Signature length (bytes):", signed.signature.data.length);
+  console.log("Sender pubkey set:", signed.sender_pubkey != null);
+
+  console.log("\nAll done! Connect to a live node and call provider.sendTransaction(signed) to broadcast.");
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shell-sdk",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "TypeScript SDK for Shell Chain",
   "license": "MIT",
   "type": "module",
@@ -45,12 +45,15 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "examples",
+    "CHANGELOG.md"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "clean": "rm -rf dist",
-    "typecheck": "tsc -p tsconfig.json --noEmit"
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "npm run build && node --test tests/**/*.test.mjs"
   },
   "keywords": [
     "shell-chain",