@smartledger/bsv 3.4.3 → 3.4.4

package/CHANGELOG.md

@@ -5,6 +5,327 @@ All notable changes to SmartLedger-BSV will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.4.4] - 2026-05-25
+
+### Fixed
+
+- **TypeScript types now actually load for `@smartledger/bsv` consumers.**
+  Two pre-existing bugs combined to silently leave TS users with `any`:
+  `package.json` had no `"types"` field, and `bsv.d.ts` declared
+  `module 'bsv'` instead of `module '@smartledger/bsv'`. Added the `types:`
+  field and renamed the ambient module declaration. Existing TS consumers
+  who were previously seeing `any` for every `bsv.*` will now get real
+  autocomplete and type errors — surface API unchanged, but any code that
+  was implicitly relying on `any` to silence a real type error will need
+  to be fixed.
+
+- **`smartledger-bsv vc verify` actually works now.** The CLI's DID resolver
+  returned the raw JWKS file content (`{ keys: [...] }`), but
+  `lib/vcjwt/verifyVcJwt` expects the documented resolver shape
+  `{ jwks: { keys: [...] } }`. So every `npx smartledger-bsv vc verify`
+  call advertised in the README's quickstart would fail with "Failed to
+  resolve issuer DID" — including the one in the very first `Quick Start`
+  block at `README.md:25-53`. `bin/cli.js` now wraps the result correctly.
+  Caught by the new `test/cli/smoke.js` (Task #9 below).
+
+- **CLI version string is no longer hardcoded.** `bin/cli.js` used to
+  print `SmartLedger BSV CLI v3.4.0` regardless of the actual package
+  version (and had no `--version` flag at all). It now reads from
+  `package.json` and supports `--version` / `-v` / `--help` / `-h`.
+
+- **Library is now silent by default.** Two long-standing modules printed
+  on every consumer-side `require`/bundle-load: `lib/smartutxo.js` emitted
+  `SmartUTXO: Running in browser mode - some features may be limited`
+  plus 11 informational `console.log` calls (`📖 Loaded existing
+  blockchain state`, `💾 Saved blockchain state with N UTXOs`, etc.), and
+  `utilities/blockchain-state.js` added another `BlockchainState: Running
+  in browser mode` warn plus ~15 narration logs that fired on every
+  `SmartUTXO` method call. All of these are now gated behind the same
+  `BSV_DEBUG` flag the rest of the codebase has used since 3.4.1:
+  set `BSV_DEBUG=1` (Node) or `window.BSV_DEBUG = true` (browser) to
+  surface the diagnostics. `console.error` calls for genuine
+  storage/IO failures are unchanged — errors stay loud. A small fix to
+  `lib/smart_contract/covenant.js` does the same for the
+  `File system operations not available in browser environment` warn
+  that `.save()` emitted at call time. Verified: `require('./index.js')`
+  in Node is now completely silent; `require('./bsv-ltp.min.js')` /
+  `bsv-gdaf.min.js` / `bsv-anchor.min.js` are silent after rebuild
+  (will rebuild for the rest at release time via `prepublishOnly`).
+
+- **Broken installs now fail loudly in Node instead of silently degrading.**
+  `index.js` previously wrapped the eager `require('bn.js')` /
+  `require('bs58')` / `require('elliptic')` calls in a single try/catch that
+  emitted `console.warn('Some dependencies may not be available in browser
+  environment')` and continued — so a missing runtime dep in Node (broken
+  `npm install`, deleted `node_modules`, container-build mistake) would let
+  the library load partially and then explode with a confusing
+  `TypeError: Cannot read properties of undefined` deep in `lib/crypto/bn.js`.
+  The block now hard-requires those three deps in Node (declared in
+  `package.json` `dependencies`, so they MUST be installed) and only
+  tolerates absence in browser context where the bundler is expected to
+  inline or polyfill them. `Buffer` and the internal `lib/util/_` continue
+  to be loaded the same way they always were.
+
+- **`Transaction._clearSignatures()` no longer throws on custom-script inputs.**
+  When a transaction contained an input whose locking script wasn't one of the
+  four auto-recognized standard types (P2PKH, P2PK, bare-multisig, P2SH-multisig),
+  `_fromNonP2SH` falls through to the base `Input` class. Any subsequent
+  `Transaction` mutation that triggers `_clearSignatures` — `.fee()`, `.change()`,
+  adding another input, etc. — then threw `AbstractMethodInvoked: Input#clearSignatures`.
+  This bug existed in the upstream bsv@1.5.6 lineage and impacted users of
+  covenant and custom-script flows specifically. `transaction.js:_clearSignatures`
+  now skips inputs that haven't overridden the base method, matching the
+  guard-by-method-identity pattern already used for `isFullySigned` and
+  `isValidSignature`. The base `Input.prototype.clearSignatures` still throws
+  when called directly, so the original abstract-method contract is preserved.
+  Regression tests added in `test/transaction/transaction.js`.
+
+### Added
+
+- **`test/cli/smoke.js` — end-to-end smoke test for `bin/cli.js`.** Exercises
+  every subcommand the README markets as the on-ramp (`didweb init`,
+  `vc issue`, `vc verify`, `status create` / `set` / `check`,
+  `anchor hash` / `build`) inside an isolated temp dir per test (13
+  tests, ~580ms total). Surfaced two pre-existing CLI bugs in the
+  process (resolver shape, hardcoded version — both fixed above). Also
+  available as `npm run test:cli`, and wired into the hygiene job of
+  `ci.yml`.
+
+- **`.github/workflows/ci.yml` — minimal CI** that runs on push/PR to main
+  and is designed to catch the exact bug classes shipped in v3.4.0–v3.4.3.
+  Three jobs:
+  1. **hygiene** (strict) — fails the build if README/docs contain stale
+     `unpkg.com/@smartledger/bsv@X.Y.Z/...` URLs that don't match
+     `package.json` version; if any `files:` array entry doesn't resolve
+     to a path on disk (globs expanded); if `bsv.d.ts` fails to compile
+     against a TS smoke file under `--strict`; or if `npm pack --dry-run`
+     output is missing any of `SECURITY.md` / `CHANGELOG.md` / `LICENSE`
+     / `README.md` / `bsv.d.ts` / `bsv.min.js`.
+  2. **build** (strict) — runs `npm run build-all` and verifies all 16
+     advertised bundles land on disk; checks that `bsv-ltp.min.js` and
+     `bsv-gdaf.min.js` are not byte-identical (regression guard for the
+     v3.4.4 entry-placeholder fix); UMD-loads each credential bundle and
+     verifies its expected exports are accessible.
+  3. **tests** (advisory) — runs `npm test` and `npm run lint` on Node
+     18/20/22, but with `continue-on-error: true`. Will be gated strictly
+     after the 25 pre-existing mocha failures and standard@12 lint
+     baseline are cleaned up in 3.5.0 (see "Planned for 3.5.0" below).
+
+- **`bsv.d.ts` now covers the v3.3+ surface.** The legacy type defs (forked
+  from the original moneybutton/bsv types) only described the bitcore-lineage
+  core: Transaction, Address, Script, PrivateKey, etc. Everything added in
+  v3.3.x and v3.4.x — `DIDWeb`, `VcJwt`, `StatusList`, `Anchor`, `GDAF`, `LTP`
+  (class + 60+ top-level `prepare*` and `create*` convenience wrappers),
+  `SmartContract` (Covenant, Preimage, SIGHASH, Builder, UTXOGenerator,
+  ScriptTester, CovenantBuilder, StackExaminer, ScriptInterpreter, plus
+  `scriptToASM`/`asmToScript`/etc.), `SmartVerify`, `EllipticFixed`, `Shamir`
+  (with `splitSecret`/`reconstructSecret`/`validateShare` convenience
+  wrappers), `BrowserUTXOManager`, and the `SmartLedger` metadata namespace
+  — was missing. Added with pragmatic signatures (JWK-typed where shapes are
+  stable; `object` / `any` where the runtime takes opaque W3C/JSON
+  payloads). Verified by compiling a smoke-test file that exercises every
+  new module against `tsc --noEmit` and `tsc --noEmit --strict` (both pass).
+
+### Changed (tarball hygiene)
+
+- **`demos/` and `examples/` no longer ship in the npm tarball.** Removed
+  from `package.json` `files:` (they're still in the GitHub repo). Reduces
+  unpacked size from 11.8 MB → 11.1 MB and file count from 268 → 206
+  (≈23% fewer files in every consumer's `node_modules`). Rationale: Node
+  consumers `require('@smartledger/bsv')` and never browse those
+  directories; CDN consumers fetch `.min.js` files directly and never see
+  the tarball. `docs/` is still included — it's actively maintained,
+  small (0.39 MB), and useful for users grepping `node_modules` for
+  reference material.
+- **13 relative README links to `examples/`, `demos/`, and `tests/`
+  rewritten to absolute GitHub URLs** so they keep resolving for anyone
+  reading the post-install README from inside `node_modules`. Same final
+  destination, just doesn't depend on the directory shipping locally.
+- **CI now enforces an anti-bloat ceiling**: the hygiene job fails if the
+  tarball exceeds 250 files or 14 MB unpacked. Baseline after this
+  release: 206 files / 11.1 MB — gives ~25% headroom for normal growth.
+
+### Changed (documentation honesty, continued)
+
+Further sweep of the same stale-URL bug class fixed in 3.4.2/3.4.3, plus a
+companion `SECURITY.md` and a fix to two long-standing entry-file placeholders.
+
+- **README.md**: bumped 20 stale `unpkg.com/@smartledger/bsv@3.4.1/...` and
+  `@3.3.4/...` CDN URLs (plus the version badge and install commands) to
+  `@3.4.3`. The two historical "v3.4.1 (bugfix)" prose references at the top
+  of the file were left intact — they accurately describe what that specific
+  release shipped.
+- **`docs/`**: bumped 67 more stale CDN/install URLs that the 3.4.3 sweep
+  missed (`@3.4.2`, `@3.3.4`, `@3.1.1`) across `MODULE_REFERENCE_COMPLETE.md`,
+  `getting-started/INSTALLATION.md`, `getting-started/QUICK_START.md`,
+  `migration/FROM_BSV_1_5_6.md`, `advanced/UTXO_MANAGER_GUIDE.md`, and
+  `COVENANT_DEVELOPMENT_RESOLVED.md`.
+- **Bundle sizes corrected** in `README.md` (loading-strategy section and
+  use-case table at lines 277–791), `docs/getting-started/INSTALLATION.md`,
+  `docs/getting-started/QUICK_START.md`, and `docs/MODULE_REFERENCE_COMPLETE.md`.
+  The largest drifts (silent for several releases): `bsv-covenant.min.js`
+  shown as 32KB in `docs/` was actually 913KB (28× off); `bsv-ltp.min.js` /
+  `bsv-gdaf.min.js` shown as 817KB / 604KB were both 1184KB after the
+  3.4.x rebuilds. README's main loading-options table (lines 138–173) was
+  already accurate and was not touched. Subtotals for "load multiple
+  bundles together" rows now reflect that each standalone bundle re-embeds
+  core BSV — the previous subtotals undercounted by ignoring that overlap.
+- **`SECURITY.md`** added. `package.json` `files:` had listed it since 3.4.0
+  but the file did not exist, so npm was silently skipping the entry (same
+  class of bug 3.4.1 cleaned up for the other seven dead `files:` entries).
+  Uses the GitHub-recognized `## Supported Versions` / `## Reporting a
+  Vulnerability` format, points at GitHub Security Advisories +
+  `hello@smartledger.technology`, and restates the same opt-in vs.
+  default-path posture as README §Security so it can't drift.
+- **`ltp-entry.js` and `gdaf-entry.js`** were placeholders that re-exported
+  `lib/smart_contract`. The webpack configs built `bsv-ltp.min.js` and
+  `bsv-gdaf.min.js` (1.2 MB each) from these placeholders, so the UMD
+  `window.bsvLTP` and `window.bsvGDAF` globals advertised in the README as
+  "Legal Token Protocol" and "Digital Identity & Attestation" actually
+  exposed the smart-contract module — and the two bundles were byte-identical.
+  The entries now point at `./lib/ltp` and `./lib/gdaf` respectively, so the
+  bundles expose the `LTP` and `GDAF` classes the README documents. CDN
+  consumers who were calling `window.bsvLTP.<smart_contract_method>` will need
+  to switch to `bsv-smartcontract.min.js` or use the unbundled `@smartledger/bsv`
+  package — the previous behavior was not what was advertised.
+
+### Notes
+
+- No public API changes beyond the LTP/GDAF UMD bundle export shape correction
+  noted above. All Node.js `require('@smartledger/bsv').LTP` /
+  `require('@smartledger/bsv').GDAF` call sites continue to resolve to the
+  same `lib/ltp` / `lib/gdaf` modules they always did.
+
+---
+
+## Planned for 3.5.0 — toolchain upgrade
+
+Originally promised in 3.4.1's "Notes":
+
+> Dev-only vulnerabilities remain in `webpack 4` / `standard 12` / `mocha 8`;
+> a toolchain upgrade is planned for 3.5.0 to address them without breaking
+> downstream bundler integrations.
+
+This is the fleshed-out plan for that release. **It does not affect 3.4.x
+runtime behavior; it's a build/test/lint stack migration.** Tracking it here
+in `[Unreleased]` keeps the commitment auditable from the changelog rather
+than a side document.
+
+### Audit baseline (as of v3.4.3)
+
+`npm audit` reports **15 high / 9 moderate / 10 low**. All but two are
+strictly dev-chain (webpack 4 / mocha 8 / nyc 14 / standard 12 transitives):
+
+- The lone direct runtime entry is **`bn.js` (moderate)** — pinned at
+  `=4.11.9` because `elliptic@6.6.1` requires bn.js 4.x. A direct bump to
+  `bn.js@5.x` is not safe in isolation; see "Runtime dependency decisions"
+  below.
+- **`elliptic` appears in the low list** but is already at upstream's latest
+  (6.6.1). The advisory comes via webpack 4's obsolete
+  `node-libs-browser → crypto-browserify → browserify-sign → elliptic`
+  polyfill chain, which webpack 5 deletes entirely. So bumping webpack to 5
+  drops this advisory automatically, no code change required.
+
+### Tooling target versions
+
+| Tool | Current | Target | Why |
+| --- | --- | --- | --- |
+| `webpack` | `4.29.3` | `^5.100` | Eliminates the entire `node-libs-browser` polyfill chain (= source of most HIGH vulns), supports modern asset modules, fixes `terser-webpack-plugin` advisory |
+| `webpack-cli` | `^3.3.12` | `^5` or `^6` | Matched to webpack 5; webpack-cli 7 also works but tightens validation |
+| `mocha` | `^8.4.0` | `^10.x` | Mocha 11 requires Node 18+; 10 supports Node 14+. Picking 10 keeps a wider engines window |
+| `nyc` | `^14.1.1` | `^17` or migrate to `c8` | nyc 17 is Node 14+ compatible. Alternative: drop nyc for `c8` (lighter, uses native V8 coverage) |
+| `sinon` | `7.2.3` | `^17.x` | sinon 18+ requires Node 18+. 17 covers Node 14+ |
+| `chai` | `4.2.0` | `4.5.x` (LTS) | **Stay on chai 4.x.** chai 5+ went ESM-only — switching means rewriting `require('chai')` everywhere or migrating the test suite to ESM. Not worth bundling into a toolchain release. |
+| `standard` | `12.0.1` | `^17` or replace | standard 17 uses ESLint 8 (now stale itself); standard 18+ requires Node 18. Open question: stay on `standard`, or move to `eslint@9` + flat config + a smaller rule set. See "Linter decision" below. |
+| `brfs` | `2.0.1` | `2.0.2` | Trivial patch bump |
+
+### Runtime dependency decisions (keep / bump / shim)
+
+| Dep | Pin | Latest | Decision |
+| --- | --- | --- | --- |
+| `elliptic` | `6.6.1` | `6.6.1` | **Keep.** Already current. |
+| `bn.js` | `=4.11.9` | `5.2.3` | **Keep at 4.x.** Bumping breaks elliptic; the moderate vuln (constant-time concern in some older 4.x) is mitigated by callers in `lib/crypto/`. Add a comment in `package.json` pinning rationale. |
+| `bs58` | `=4.0.1` | `6.0.0` | **Keep at 4.x.** `bs58@5+` is ESM-only and would force a CJS→ESM migration of `lib/encoding/base58.js`. Out of scope for 3.5.0. |
+| `inherits` | `2.0.3` | `2.0.4` | **Bump to 2.0.4.** Trivial. |
+| `unorm` | `1.4.1` | `1.6.0` | **Bump to 1.6.0.** Non-breaking. |
+| `aes-js` | `^3.1.2` | `3.1.2` | **No change.** |
+| `clone-deep` | `^4.0.1` | `4.0.1` | **No change.** |
+| `hash.js` | `^1.1.7` | `1.1.7` | **No change.** |
+
+### Required code / config changes
+
+1. **`build/webpack.*.config.js` (12 files).** webpack 5 removes the
+   automatic Node polyfills that webpack 4 silently injects. Concrete
+   touches needed:
+   - Add `resolve.fallback` entries for `buffer`, `crypto`, `stream`,
+     `process` (or use `node-polyfill-webpack-plugin`).
+   - Add `buffer`, `process`, `stream-browserify`, `crypto-browserify`
+     (or modern equivalents) as **dev**-deps so the fallbacks resolve.
+   - `output.library` ideally migrates from string to object form
+     (`{ name: 'bsvFoo', type: 'umd' }`) — webpack 5 still accepts the
+     string form but warns.
+   - `globalObject: 'this'` should become `globalObject: 'globalThis'`
+     (cleaner; matches modern targets).
+   - Drop `NODE_OPTIONS="--openssl-legacy-provider"` from all 16 `npm run
+     build-*` scripts — that workaround exists *because* webpack 4 pins
+     legacy OpenSSL APIs. webpack 5 doesn't need it.
+
+2. **`test/mocha.opts` → `.mocharc.cjs` (or `mocha` field in package.json).**
+   Mocha 8 already emits a deprecation warning for `mocha.opts`; mocha 10
+   removes support entirely. Migrate the existing two flags
+   (`--recursive`, `--timeout 5000`) and add `--reporter spec`.
+
+3. **`engines` field in `package.json`.** No engines is declared today.
+   For 3.5.0 add `"engines": { "node": ">=14" }` (or `>=18` if we also
+   adopt mocha 11 / sinon 18 / standard 18). Current consumer test
+   environments span Node 14–22, so `>=14` is the safer choice.
+
+4. **`@types/node` peer dep or dev-dep.** With the typing fix in 3.4.4,
+   `bsv.d.ts` formally depends on Node types (`/// <reference types="node" />`).
+   Add `"peerDependencies": { "@types/node": "*" }` (optional) or document
+   in README that TS consumers need `@types/node` installed.
+
+5. **Linter decision (open question).**
+   Option A — Stay on `standard@17`: 1-line bump, ~1 day to fix new lint
+   errors. Risk: standard's own toolchain is aging.
+   Option B — Migrate to ESLint flat config (`eslint.config.js`) with a
+   custom rule set. More work, but unblocks long-term flexibility and the
+   newer rule engine.
+   **Recommendation:** A for 3.5.0, defer B to 3.6.0.
+
+### Risk ranking and rollout order
+
+Each step should be its own PR, validated against the full `test/` suite
+(120+ mocha tests passed in 3.4.4) and a `npm pack --dry-run` size diff.
+
+1. **Low risk:** `inherits` / `unorm` patch bumps, `brfs 2.0.1 → 2.0.2`,
+   add `engines` field, migrate `mocha.opts → .mocharc.cjs`.
+2. **Medium risk:** mocha 8 → 10, nyc 14 → 17, sinon 7 → 17, standard
+   12 → 17. Test suite may have lint/test syntax regressions.
+3. **Higher risk:** webpack 4 → 5. This is the bundle-shape change;
+   downstream CDN consumers will see different file bytes. Plan a beta
+   release (`3.5.0-beta.1`) on npm before the GA bump so integrators can
+   validate.
+4. **Out of scope, deferred:** `bn.js 4 → 5`, `bs58 4 → 6`, `chai 4 → 5`,
+   linter overhaul. These all imply CJS→ESM or coordinated upstream
+   changes and warrant a separate 3.6.0 effort.
+
+### Pre-release validation checklist
+
+Before publishing `3.5.0`:
+
+- `npm test` passes (Node 18, 20, 22).
+- `npm run build-all` succeeds without `NODE_OPTIONS` workaround.
+- All 16 bundles built and:
+  - sized within 5% of 3.4.x equivalents (or sizes updated in README/docs);
+  - smoke-tested in a browser via `tests/*.html` against the unpkg URL;
+  - UMD globals (`window.bsv`, `bsvLTP`, `bsvGDAF`, etc.) resolve correctly.
+- `npm audit` shows zero high/critical, ≤ 5 moderate (any remaining moderates
+  documented in CHANGELOG with mitigation).
+- `tsc --noEmit --strict` against `bsv.d.ts` + smoke file still passes.
+- Tag `3.5.0-beta.1` on npm for at least 7 days to let integrators report
+  bundle regressions before GA.
+
 ## [3.4.3] - 2026-05-18
 
 ### Changed (documentation honesty, continued)

package/README.md

@@ -2,7 +2,7 @@
 
 **🚀 Complete Bitcoin SV Development Framework with W3C Verifiable Credentials, DID:web, Legal Compliance, and 16 Flexible Loading Options**
 
-[![Version](https://img.shields.io/badge/version-3.4.1-blue.svg)](https://www.npmjs.com/package/@smartledger/bsv)
+[![Version](https://img.shields.io/badge/version-3.4.4-blue.svg)](https://www.npmjs.com/package/@smartledger/bsv)
 [![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
 [![BSV](https://img.shields.io/badge/BSV-Compatible-orange.svg)](https://bitcoinsv.com/)
 [![Modular](https://img.shields.io/badge/Loading-Modular-purple.svg)](#loading-options)
@@ -25,8 +25,8 @@ The most comprehensive and flexible Bitcoin SV library available. **In v3.4.x**:
 ### **Quick Start - Issue Your First Verifiable Credential**
 
 ```bash
-# Install SmartLedger BSV v3.4.1
-npm install @smartledger/bsv@3.4.1
+# Install SmartLedger BSV v3.4.4
+npm install @smartledger/bsv@3.4.4
 
 # Initialize DID:web issuer (generates ES256 keys)
 npx smartledger-bsv didweb init --domain example.com --alg ES256
@@ -135,42 +135,42 @@ console.log('Status:', status) // 'revoked'
 ### **Core Modules**
 | Module | Size | Use Case | CDN |
 |--------|------|----------|-----|
-| **bsv.min.js** | 937KB | Core BSV + SmartContract | `unpkg.com/@smartledger/bsv@3.4.1/bsv.min.js` |
-| **bsv.bundle.js** | 937KB | Everything in one file | `unpkg.com/@smartledger/bsv@3.4.1/bsv.bundle.js` |
+| **bsv.min.js** | 937KB | Core BSV + SmartContract | `unpkg.com/@smartledger/bsv@3.4.4/bsv.min.js` |
+| **bsv.bundle.js** | 937KB | Everything in one file | `unpkg.com/@smartledger/bsv@3.4.4/bsv.bundle.js` |
 
 ### **🆕 W3C Verifiable Credentials (v3.4.x)**
 | Module | Size | Use Case | CDN |
 |--------|------|----------|-----|
-| **🟢 bsv-didweb.min.js** | 419KB | **DID:web generation** | `unpkg.com/@smartledger/bsv@3.4.1/bsv-didweb.min.js` |
-| **🟢 bsv-vcjwt.min.js** | 419KB | **VC-JWT issue/verify** | `unpkg.com/@smartledger/bsv@3.4.1/bsv-vcjwt.min.js` |
-| **🟢 bsv-statuslist.min.js** | 487KB | **StatusList2021 revocation** | `unpkg.com/@smartledger/bsv@3.4.1/bsv-statuslist.min.js` |
-| **🟢 bsv-anchor.min.js** | 418KB | **BSV anchoring (hash-only)** | `unpkg.com/@smartledger/bsv@3.4.1/bsv-anchor.min.js` |
+| **🟢 bsv-didweb.min.js** | 419KB | **DID:web generation** | `unpkg.com/@smartledger/bsv@3.4.4/bsv-didweb.min.js` |
+| **🟢 bsv-vcjwt.min.js** | 419KB | **VC-JWT issue/verify** | `unpkg.com/@smartledger/bsv@3.4.4/bsv-vcjwt.min.js` |
+| **🟢 bsv-statuslist.min.js** | 487KB | **StatusList2021 revocation** | `unpkg.com/@smartledger/bsv@3.4.4/bsv-statuslist.min.js` |
+| **🟢 bsv-anchor.min.js** | 418KB | **BSV anchoring (hash-only)** | `unpkg.com/@smartledger/bsv@3.4.4/bsv-anchor.min.js` |
 
 ### **Smart Contract & Development**
 | Module | Size | Use Case | CDN |
 |--------|------|----------|-----|
-| **bsv-smartcontract.min.js** | 937KB | Complete covenant framework | `unpkg.com/@smartledger/bsv@3.4.1/bsv-smartcontract.min.js` |
-| **bsv-covenant.min.js** | 913KB | Covenant operations | `unpkg.com/@smartledger/bsv@3.4.1/bsv-covenant.min.js` |
-| **bsv-script-helper.min.js** | 26KB | Custom script tools | `unpkg.com/@smartledger/bsv@3.4.1/bsv-script-helper.min.js` |
-| **bsv-security.min.js** | 26KB | Security enhancements | `unpkg.com/@smartledger/bsv@3.4.1/bsv-security.min.js` |
+| **bsv-smartcontract.min.js** | 937KB | Complete covenant framework | `unpkg.com/@smartledger/bsv@3.4.4/bsv-smartcontract.min.js` |
+| **bsv-covenant.min.js** | 913KB | Covenant operations | `unpkg.com/@smartledger/bsv@3.4.4/bsv-covenant.min.js` |
+| **bsv-script-helper.min.js** | 26KB | Custom script tools | `unpkg.com/@smartledger/bsv@3.4.4/bsv-script-helper.min.js` |
+| **bsv-security.min.js** | 26KB | Security enhancements | `unpkg.com/@smartledger/bsv@3.4.4/bsv-security.min.js` |
 
 ### **Legal & Compliance**
 | Module | Size | Use Case | CDN |
 |--------|------|----------|-----|
-| **bsv-ltp.min.js** | 1184KB | Legal Token Protocol | `unpkg.com/@smartledger/bsv@3.4.1/bsv-ltp.min.js` |
-| **bsv-gdaf.min.js** | 1184KB | Digital Identity & Attestation | `unpkg.com/@smartledger/bsv@3.4.1/bsv-gdaf.min.js` |
+| **bsv-ltp.min.js** | 1184KB | Legal Token Protocol | `unpkg.com/@smartledger/bsv@3.4.4/bsv-ltp.min.js` |
+| **bsv-gdaf.min.js** | 1184KB | Digital Identity & Attestation | `unpkg.com/@smartledger/bsv@3.4.4/bsv-gdaf.min.js` |
 
 ### **Advanced Cryptography**
 | Module | Size | Use Case | CDN |
 |--------|------|----------|-----|
-| **bsv-shamir.min.js** | 432KB | Threshold Cryptography | `unpkg.com/@smartledger/bsv@3.4.1/bsv-shamir.min.js` |
+| **bsv-shamir.min.js** | 432KB | Threshold Cryptography | `unpkg.com/@smartledger/bsv@3.4.4/bsv-shamir.min.js` |
 
 ### **Utilities**
 | Module | Size | Use Case | CDN |
 |--------|------|----------|-----|
-| **bsv-ecies.min.js** | 71KB | Encryption | `unpkg.com/@smartledger/bsv@3.4.1/bsv-ecies.min.js` |
-| **bsv-message.min.js** | 26KB | Message signing | `unpkg.com/@smartledger/bsv@3.4.1/bsv-message.min.js` |
-| **bsv-mnemonic.min.js** | 681KB | HD wallets | `unpkg.com/@smartledger/bsv@3.4.1/bsv-mnemonic.min.js` |
+| **bsv-ecies.min.js** | 71KB | Encryption | `unpkg.com/@smartledger/bsv@3.4.4/bsv-ecies.min.js` |
+| **bsv-message.min.js** | 26KB | Message signing | `unpkg.com/@smartledger/bsv@3.4.4/bsv-message.min.js` |
+| **bsv-mnemonic.min.js** | 681KB | HD wallets | `unpkg.com/@smartledger/bsv@3.4.4/bsv-mnemonic.min.js` |
 
 ## ⚡ **2-Minute Quick Start**
 
@@ -181,7 +181,7 @@ Get started with Bitcoin SV development in under 2 minutes:
 npm install @smartledger/bsv
 
 # Or include in HTML
-<script src="https://unpkg.com/@smartledger/bsv@3.4.1/bsv.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@3.4.4/bsv.min.js"></script>
 ```
 
 > **🔧 v3.4.x:** Legally-recognizable W3C Verifiable Credentials with DID:web + VC-JWT toolkit. ES256/ES256K support, StatusList2021 revocation, and privacy-preserving BSV anchoring. Complete CLI tooling included! v3.4.1 ensures these bundles ship to npm consumers; see CHANGELOG.
@@ -249,7 +249,7 @@ const covenant = bsv.SmartContract.createCovenantBuilder()
 - 🌐 [Digital Identity Guide](docs/GDAF_DIGITAL_ATTESTATION_GUIDE.md)
 - � [Threshold Cryptography Guide](docs/SHAMIR_SECRET_SHARING_GUIDE.md)
 - �️ [UTXO Manager Guide](docs/UTXO_MANAGER_GUIDE.md)
-- 💡 [Examples Directory](examples/)
+- 💡 [Examples Directory](https://github.com/codenlighten/smartledger-bsv/tree/main/examples)
 
 ## 🔧 **API Reference**
 
@@ -274,21 +274,21 @@ const covenant = bsv.SmartContract.createCovenantBuilder()
 
 ## 📚 **Quick Start Examples**
 
-### 🔧 **Basic Development** (476KB total)
+### 🔧 **Basic Development** (~963KB total)
 ```html
-<script src="https://unpkg.com/@smartledger/bsv@3.3.4/bsv.min.js"></script>
-<script src="https://unpkg.com/@smartledger/bsv@3.3.4/bsv-script-helper.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@3.4.4/bsv.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@3.4.4/bsv-script-helper.min.js"></script>
 <script>
   const privateKey = new bsv.PrivateKey();
   const utxos = new bsv.SmartContract.UTXOGenerator().createRealUTXOs(2, 100000);
 </script>
 ```
 
-### 🔒 **Smart Contract Development** (932KB total)
+### 🔒 **Smart Contract Development** (~2.7MB total — each bundle re-embeds core BSV)
 ```html
-<script src="https://unpkg.com/@smartledger/bsv@3.3.4/bsv.min.js"></script>
-<script src="https://unpkg.com/@smartledger/bsv@3.3.4/bsv-covenant.min.js"></script>
-<script src="https://unpkg.com/@smartledger/bsv@3.3.4/bsv-smartcontract.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@3.4.4/bsv.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@3.4.4/bsv-covenant.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@3.4.4/bsv-smartcontract.min.js"></script>
 <script>
   const covenant = bsv.SmartContract.createCovenantBuilder()
     .extractField('amount').push(50000).greaterThanOrEqual().verify().build();
@@ -296,11 +296,11 @@ const covenant = bsv.SmartContract.createCovenantBuilder()
 </script>
 ```
 
-### 🆕 **Legal & Identity Development** (1.87MB total)
+### 🆕 **Legal & Identity Development** (~3.2MB total — each bundle re-embeds core BSV)
 ```html
-<script src="https://unpkg.com/@smartledger/bsv@3.3.4/bsv.min.js"></script>
-<script src="https://unpkg.com/@smartledger/bsv@3.3.4/bsv-ltp.min.js"></script>
-<script src="https://unpkg.com/@smartledger/bsv@3.3.4/bsv-gdaf.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@3.4.4/bsv.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@3.4.4/bsv-ltp.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@3.4.4/bsv-gdaf.min.js"></script>
 <script>
   // Legal Token Protocol
   const propertyToken = bsv.createPropertyToken({
@@ -312,11 +312,11 @@ const covenant = bsv.SmartContract.createCovenantBuilder()
 </script>
 ```
 
-### 🆕 **Security & Cryptography** (1.17MB total)
+### 🆕 **Security & Cryptography** (~1.4MB total)
 ```html
-<script src="https://unpkg.com/@smartledger/bsv@3.3.4/bsv.min.js"></script>
-<script src="https://unpkg.com/@smartledger/bsv@3.3.4/bsv-security.min.js"></script>
-<script src="https://unpkg.com/@smartledger/bsv@3.3.4/bsv-shamir.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@3.4.4/bsv.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@3.4.4/bsv-security.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@3.4.4/bsv-shamir.min.js"></script>
 <script>
   // Threshold Cryptography
   const shares = bsv.splitSecret('my_secret_key', 5, 3); // 5 shares, 3 needed
@@ -326,9 +326,9 @@ const covenant = bsv.SmartContract.createCovenantBuilder()
 </script>
 ```
 
-### 🎯 **Everything Bundle** (885KB)
+### 🎯 **Everything Bundle** (937KB)
 ```html
-<script src="https://unpkg.com/@smartledger/bsv@3.3.4/bsv.bundle.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@3.4.4/bsv.bundle.js"></script>
 <script>
   // Everything available immediately
   const shares = bsv.splitSecret('secret', 5, 3);           // Shamir Secret Sharing
@@ -356,14 +356,14 @@ const covenant = bsv.SmartContract.createCovenantBuilder()
 ### 🛠️ **Advanced Development Tools**
 - 🔧 **JavaScript-to-Script**: High-level covenant development with 121 opcode mapping → [Covenant Guide](docs/ADVANCED_COVENANT_DEVELOPMENT.md)
 - 🔧 **UTXO Generator**: Create authentic test UTXOs for development → [UTXO Guide](docs/UTXO_MANAGER_GUIDE.md)
-- 🔧 **Preimage Parser**: Complete BIP-143 field extraction and manipulation → [Preimage Tools](examples/preimage/)
-- � **Debug Framework**: Script interpreter, stack examiner, and optimizer → [Debug Examples](tests/smartcontract-test.html)
+- 🔧 **Preimage Parser**: Complete BIP-143 field extraction and manipulation → [Preimage Tools](https://github.com/codenlighten/smartledger-bsv/tree/main/examples/preimage)
+- � **Debug Framework**: Script interpreter, stack examiner, and optimizer → [Debug Examples](https://github.com/codenlighten/smartledger-bsv/blob/main/tests/smartcontract-test.html)
 - � **PUSHTX Integration**: nChain techniques for advanced covenant patterns → [PUSHTX Insights](docs/pushtx-key-insights.md)
 
 ### 📦 **Flexible Architecture** 
-- 📦 **12 Modular Options**: Load only what you need (27KB to 885KB) → [Loading Strategy](#loading-strategy-examples)
-- 📦 **Standalone Modules**: Independent legal, identity, and crypto modules → [Standalone Test](tests/standalone-modules-test.html)
-- 📦 **Complete Bundle**: Everything in one file for convenience → [Bundle Demo](tests/bundle-demo.html)
+- 📦 **16 Modular Options**: Load only what you need (26KB to 1184KB) → [Loading Strategy](#loading-strategy-examples)
+- 📦 **Standalone Modules**: Independent legal, identity, and crypto modules → [Standalone Test](https://github.com/codenlighten/smartledger-bsv/blob/main/tests/standalone-modules-test.html)
+- 📦 **Complete Bundle**: Everything in one file for convenience → [Bundle Demo](https://github.com/codenlighten/smartledger-bsv/blob/main/tests/bundle-demo.html)
 - 📦 **CDN Ready**: All modules available via unpkg and jsDelivr
 - 📦 **Webpack Optimized**: Tree-shakeable and build-tool friendly
 
@@ -406,21 +406,21 @@ const contractTx = covenant.createCovenantTransaction({
 
 ### Browser CDN (Choose Your Loading Strategy)
 
-#### 1. **Minimal Setup** - Core + Script Helper (476KB)
+#### 1. **Minimal Setup** - Core + Script Helper (~963KB)
 ```html
-<script src="https://unpkg.com/@smartledger/bsv@3.3.4/bsv.min.js"></script>
-<script src="https://unpkg.com/@smartledger/bsv@3.3.4/bsv-script-helper.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@3.4.4/bsv.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@3.4.4/bsv-script-helper.min.js"></script>
 <script>
   const tx = new bsv.Transaction();
   const sig = bsvScriptHelper.createSignature(tx, privateKey, 0, script, satoshis);
 </script>
 ```
 
-#### 2. **DeFi Development** - Core + Covenants + Debug (932KB)
+#### 2. **DeFi Development** - Core + Covenants + Debug (~2.7MB — each bundle re-embeds core BSV)
 ```html
-<script src="https://unpkg.com/@smartledger/bsv@3.3.4/bsv.min.js"></script>
-<script src="https://unpkg.com/@smartledger/bsv@3.3.4/bsv-covenant.min.js"></script>
-<script src="https://unpkg.com/@smartledger/bsv@3.3.4/bsv-smartcontract.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@3.4.4/bsv.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@3.4.4/bsv-covenant.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@3.4.4/bsv-smartcontract.min.js"></script>
 <script>
   const covenant = new bsvCovenant.CovenantInterface();
   const debugInfo = SmartContract.interpretScript(script);
@@ -428,19 +428,19 @@ const contractTx = covenant.createCovenantTransaction({
 </script>
 ```
 
-#### 3. **Security First** - Core + Enhanced Security (739KB)
+#### 3. **Security First** - Core + Enhanced Security (~963KB)
 ```html
-<script src="https://unpkg.com/@smartledger/bsv@3.3.4/bsv.min.js"></script>
-<script src="https://unpkg.com/@smartledger/bsv@3.3.4/bsv-security.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@3.4.4/bsv.min.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@3.4.4/bsv-security.min.js"></script>
 <script>
   const verified = bsvSecurity.SmartVerify.verify(signature, hash, publicKey);
   const enhanced = bsvSecurity.EllipticFixed.createSignature(privateKey, hash);
 </script>
 ```
 
-#### 4. **Everything Bundle** - One File Solution (764KB)
+#### 4. **Everything Bundle** - One File Solution (937KB)
 ```html
-<script src="https://unpkg.com/@smartledger/bsv@3.3.4/bsv.bundle.js"></script>
+<script src="https://unpkg.com/@smartledger/bsv@3.4.4/bsv.bundle.js"></script>
 <script>
   // Everything available under bsv namespace
   const keys = bsv.SmartLedgerBundle.generateKeys();
@@ -777,18 +777,18 @@ A planned 3.5.0 will offer an opt-in flag to route the default verify path throu
 
 ### 🔧 **Technical Resources**
 - **[SmartContract Integration](SMARTCONTRACT_INTEGRATION.md)** - Debug tools and analysis
-- **[Examples Directory](examples/)** - Working code samples
-- **[Test Suite](tests/)** - Comprehensive testing examples
+- **[Examples Directory](https://github.com/codenlighten/smartledger-bsv/tree/main/examples)** - Working code samples
+- **[Test Suite](https://github.com/codenlighten/smartledger-bsv/tree/main/tests)** - Comprehensive testing examples
 - **[Build System](build/)** - Webpack configurations
 
 ### 🌐 **Loading Strategy Examples**
 
 | **Use Case** | **Recommended Load** | **Size** | **Features** |
 |--------------|---------------------|----------|--------------|
-| **Simple Transactions** | `bsv.min.js` | 449KB | Core BSV + SmartContract |
-| **DeFi Development** | Core + Covenant + Debug | 932KB | Advanced contracts + tools |
-| **Enterprise Apps** | `bsv.bundle.js` | 764KB | Everything included |
-| **Mobile/Lightweight** | Core + Script Helper | 476KB | Essential tools only |
+| **Simple Transactions** | `bsv.min.js` | 937KB | Core BSV + SmartContract |
+| **DeFi Development** | Core + Covenant + Debug | ~2.7MB | Advanced contracts + tools (bundles re-embed core BSV) |
+| **Enterprise Apps** | `bsv.bundle.js` | 937KB | Everything included |
+| **Mobile/Lightweight** | Core + Script Helper | ~963KB | Essential tools only |
 | **Research/Analysis** | Core + SmartContract | 900KB | Full debug capabilities |
 
 ### 🔗 **Cross-References**
@@ -799,19 +799,19 @@ A planned 3.5.0 will offer an opt-in flag to route the default verify path throu
 - [API Reference](#api-reference) → [Method Documentation](docs/)
 
 **From Examples → Implementation:**
-- [Covenant Examples](examples/covenants/) → [Production Guide](docs/ADVANCED_COVENANT_DEVELOPMENT.md#production-guidelines)
-- [Script Examples](examples/scripts/) → [Custom Script Guide](docs/CUSTOM_SCRIPT_DEVELOPMENT.md)
-- [Test Files](tests/) → [Integration Examples](examples/)
+- [Covenant Examples](https://github.com/codenlighten/smartledger-bsv/tree/main/examples/covenants) → [Production Guide](docs/ADVANCED_COVENANT_DEVELOPMENT.md#production-guidelines)
+- [Script Examples](https://github.com/codenlighten/smartledger-bsv/tree/main/examples/scripts) → [Custom Script Guide](docs/CUSTOM_SCRIPT_DEVELOPMENT.md)
+- [Test Files](https://github.com/codenlighten/smartledger-bsv/tree/main/tests) → [Integration Examples](https://github.com/codenlighten/smartledger-bsv/tree/main/examples)
 
 **From Concepts → Code:**
-- [PUSHTX Theory](docs/pushtx-key-insights.md) → [Covenant Implementation](examples/covenants/advanced_covenant_demo.js)
+- [PUSHTX Theory](docs/pushtx-key-insights.md) → [Covenant Implementation](https://github.com/codenlighten/smartledger-bsv/blob/main/examples/covenants/advanced_covenant_demo.js)
 - [Security Features](#smart-security) → [Implementation](lib/crypto/smartledger_verify.js)
-- [Debug Tools](#debug-tools) → [Usage Examples](tests/smartcontract-test.html)
+- [Debug Tools](#debug-tools) → [Usage Examples](https://github.com/codenlighten/smartledger-bsv/blob/main/tests/smartcontract-test.html)
 
 ### 🎓 **Learning Path**
 
 1. **Start**: [2-Minute Quick Start](#2-minute-quick-start)
-2. **Practice**: [Examples Directory](examples/) 
+2. **Practice**: [Examples Directory](https://github.com/codenlighten/smartledger-bsv/tree/main/examples) 
 3. **Build**: [Custom Script Guide](docs/CUSTOM_SCRIPT_DEVELOPMENT.md)
 4. **Advanced**: [Covenant Development](docs/ADVANCED_COVENANT_DEVELOPMENT.md)
 5. **Deploy**: [Production Guidelines](docs/ADVANCED_COVENANT_DEVELOPMENT.md#production-guidelines)
@@ -839,11 +839,11 @@ A planned 3.5.0 will offer an opt-in flag to route the default verify path throu
 - [🔧 **Integration Guide**](SMARTCONTRACT_INTEGRATION.md) - Smart contract integration
 
 ### 📋 **Examples & Demos**
-- [� **Interactive Demos**](demos/) - **NEW!** HTML & Node.js smart contract demos
-- [�📁 **Examples Directory**](examples/) - Working code examples
-- [🎯 **Basic Examples**](examples/basic/) - Simple transactions & addresses
-- [🔒 **Covenant Examples**](examples/covenants/) - Smart contract patterns  
-- [📊 **Advanced Examples**](examples/covenants2/) - Production patterns
+- [� **Interactive Demos**](https://github.com/codenlighten/smartledger-bsv/tree/main/demos) - **NEW!** HTML & Node.js smart contract demos
+- [�📁 **Examples Directory**](https://github.com/codenlighten/smartledger-bsv/tree/main/examples) - Working code examples
+- [🎯 **Basic Examples**](https://github.com/codenlighten/smartledger-bsv/tree/main/examples/basic) - Simple transactions & addresses
+- [🔒 **Covenant Examples**](https://github.com/codenlighten/smartledger-bsv/tree/main/examples/covenants) - Smart contract patterns  
+- [📊 **Advanced Examples**](https://github.com/codenlighten/smartledger-bsv/tree/main/examples/covenants2) - Production patterns
 
 **🎮 Try the Interactive Demos:**
 ```bash