refactor(sdk,wallet-lib,test-suite)!: convert dapi-client + wallet-lib + js-dash-sdk + platform-test-suite to ESM by PastaPastaPasta · Pull Request #3689 · dashpay/platform

PastaPastaPasta · 2026-05-19T23:43:35Z

Summary

Final PR in the ESM migration stack. Converts @dashevo/dapi-client, @dashevo/wallet-lib, dash (@dashevo/js-dash-sdk), and @dashevo/platform-test-suite to pure ESM. Removes the webpack/karma browser-bundle infrastructure across all four packages.

This is PR 3 of 3 (after the originally-stacked PRs 3/4/5 were merged into one — see note below). Depends on #3679 (cleanup) and #3680 (Uint8Array).

Note

Originally split into three stacked PRs (#3681 dapi-client, #3682 wallet-lib, #3683 js-dash-sdk+PTS), each on a separate branch. CI fails on any of them in isolation because the monorepo build compiles every package on every PR, and dapi-client-ESM + wallet-lib-CJS is an incompatible mid-state (CJS cannot require() ESM). Since they must land together regardless, they are combined here as a single PR with three commits preserved for review focus.

What changes

`@dashevo/dapi-client` (commit 1: `refactor(dapi-client)!: convert to ESM, drop webpack/karma`)

package.json: "type": "module", "exports": { ".": "./lib/index.js", "./lib/*": "./lib/*" }, drops main. The wildcard preserves deep-import paths.
All ~115 source files and ~80 test files converted from CJS require/module.exports to ESM import/export. Relative imports include .js extension.
events npm package moved devDeps → deps. Used for EventEmitter in DAPIClient, ReconnectableStream, BlockHeadersProvider. Works in both Node and browser bundlers.
Deletes webpack.config.js, karma.conf.js, lib/test/karma/. Removes all browser-polyfill devDeps (buffer, crypto-browserify, os-browserify, path-browserify, process, stream-browserify, string_decoder, url, util, webpack, webpack-cli, karma-*, babel-*).
.mocharc.yml uses require: for the ESM bootstrap with a defensive loadDpp.default ?? loadDpp unwrap.

`@dashevo/wallet-lib` (commit 2: `refactor(wallet-lib)!: convert to ESM, consume ESM dapi-client`)

package.json: "type": "module", engines.node >= 18.18. Drops build:web, test:browsers*, prepublishOnly. Removes all browser-polyfill devDeps. Removes deps winston, node-inspect-extracted.
All 350+ files in src/, fixtures/, and tests/ converted from CJS to ESM with .js extensions on relative imports.
src/logger/index.js rewritten as a console-backed logger (matching dapi-client's pattern from PR 1).
Deep imports of @dashevo/dapi-client updated to include .js extensions.
Deletes webpack.config.js, karma/, src/test/karma/.
.mocharc.yml uses require: for ESM bootstrap.

`dash` / `@dashevo/js-dash-sdk` (commit 3: `refactor(js-dash-sdk,platform-test-suite)!: convert to ESM, consume ESM dapi-client and wallet-lib`)

package.json: "type": "module", exports map, engines.node >= 18.18. Drops unpkg/browser, test:browsers*. Removes karma-*, webpack, browser polyfills, ts-mock-imports (replaced with an injectable seam).
tsconfig.build.json and tsconfig.json: module: nodenext, moduleResolution: nodenext, target: es2020.
All 54 .ts files get .js extensions on relative imports (NodeNext requirement).
Refactored src/SDK/Client/Platform/methods/names/register.ts to accept an injectable randomBytes parameter (replaces ts-mock-imports for the existing test seam).
Replaced winston with console-backed logger.
CJS-named-import fixes (import { X } from cjs-pkg → import pkg from cjs-pkg; const { X } = pkg;) for dashcore-lib, wasm-dpp, grpc-common, contract packages.
Added parallel import type { X as XType }; type X = XType; aliases in 22 .ts files where destructured value names are also used in type positions (TS2440 workaround under NodeNext).
Defensive (loadDpp.default ?? loadDpp)() unwrap in 4 sites.
Deletes webpack.config.js, webpack.base.config.js, karma/.

`@dashevo/platform-test-suite` (also in commit 3)

package.json: "type": "module", drops test:browsers, browser polyfills, karma-*.
All ~35 .js files converted to ESM.
lib/test/bootstrap.js rewritten as ESM with fileURLToPath-based __dirname.
.mocharc.yml uses import: for ESM root hooks.

Test plan

yarn workspace @dashevo/dapi-client run test:unit — 315 passing ✅
yarn workspace @dashevo/wallet-lib run test:unit — 377 passing, 2 pending ✅
yarn workspace dash run test:unit — 60 passing, 3 pre-existing pending ✅
yarn workspace @dashevo/platform-test-suite run lint — ESM bootstrap loads ✅
platform-test-suite e2e tests require live testnet credentials in .env (pre-existing constraint).

Breaking changes

All four packages are ESM-only. Any require() of them no longer works.
Deep imports require .js extensions.
No prebuilt browser bundles. Consumers must use a modern bundler (Vite/esbuild/webpack 5).
js-dash-sdk's Platform.names.register(...) gained an optional trailing randomBytes parameter. Existing callers unaffected.
Drops winston, bs58, node-inspect-extracted from deps where unused.

Monorepo state after this lands

@dashevo/dapi-client — ESM, Uint8Array API, browser-bundler-friendly
@dashevo/wallet-lib — ESM
dash — ESM TypeScript
@dashevo/platform-test-suite — ESM
@dashevo/dashmate — was already ESM, works as-is
@dashevo/dapi-grpc — patched in PR 1 (chore(dapi): cleanup — drop unused deps, inline winston/fetch/promisify shims #3679); rest unchanged

Stack

PR 1 — Cleanup
PR 2 — Buffer → Uint8Array
➡️ PR 3 — Full ESM conversion (this PR; replaces refactor(dapi)!: convert dapi-client to ESM, drop webpack/karma #3681 refactor(wallet-lib)!: convert to ESM, consume ESM dapi-client #3682 refactor(sdk,test-suite)!: convert to ESM, consume ESM dapi-client and wallet-lib #3683)

coderabbitai · 2026-05-19T23:43:44Z

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: cbf33c2c-f3d5-4ed0-a809-f119f6d9c6f4

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch claude/esm-3-esm-conversion

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

github-actions · 2026-05-19T23:49:52Z

✅ DashSDKFFI.xcframework built for this PR.

Workflow run: https://github.com/dashpay/platform/actions/runs/26132120590
Artifacts: DashSDKFFI.xcframework (folder), DashSDKFFI.xcframework.zip, xc_checksum.txt

SwiftPM (host the zip at a stable URL, then use):

.binaryTarget(
  name: "DashSDKFFI",
  url: "https://your.cdn.example/DashSDKFFI.xcframework.zip",
  checksum: "d3a03c5dce08347513332117f46aa8601083d05f64eaeb7f09bf9f4b62651ebf"
)

Xcode manual integration:

Download 'DashSDKFFI.xcframework' artifact from the run link above.
Drag it into your app target (Frameworks, Libraries & Embedded Content) and set Embed & Sign.
If using the Swift wrapper package, point its binaryTarget to the xcframework location or add the package and place the xcframework at the expected path.

… API Adds lib/utils/bytes.js helper (hexToBytes/bytesToHex/base64ToBytes/bytesToBase64/concatBytes/bytesEqual) and converts all Buffer.* call sites in dapi-client lib/ to Uint8Array, with corresponding test updates. Package stays CJS. Production exceptions where Buffer is retained: BlockHeadersReader passes Buffer to dashcore-lib's BlockHeader (its BufferReader needs .readInt32LE), and GetIdentitiesContractKeysResponse passes Buffer to wasm-dpp's Identifier.from (it explicitly requires Node Buffer). createGrpcTransportError now handles both raw bytes (grpc-js path) and base64 strings (grpc-web path) for drive-error-data-bin, stack-bin, and dash-serialized-consensus-error-bin metadata fields, restoring the dual-format behavior that Buffer.from(x, 'base64') used to provide implicitly. Test updates: spec files that construct expected protobuf requests now wrap .toBuffer() with new Uint8Array(...) to match production's normalization (sinon calledOnceWithExactly distinguishes Buffer from plain Uint8Array). Breaking change for direct consumers: response object byte fields are now Uint8Array. Callers that do response.field.toString('hex') will fail — use bytesToHex(response.field) from lib/utils/bytes instead. Buffer.isBuffer(response.field) now returns false; use response.field instanceof Uint8Array. Test results: dapi-client 315/315, wallet-lib 377/377, js-dash-sdk 60/60 — downstream consumers continue passing without modification (they exercise dapi-client mostly via mocks).

Identifier constructor and static from() now accept Uint8Array in addition to Buffer. Since Buffer extends Uint8Array in Node, existing Buffer callers continue to work unchanged — this is a widening, not a swap. Lets dapi-client and other web-facing consumers pass plain Uint8Array (e.g. from protobuf getters) without an explicit Buffer.from wrap. Error message updated from 'Identifier expects Buffer' to 'Identifier expects Uint8Array'.

wasm-dpp's Identifier.from now accepts Uint8Array directly, so the explicit Buffer.from wrap around entry.getIdentityId() is no longer needed. Removes one of two remaining Buffer escape hatches in dapi-client (the BlockHeader path through dashcore-lib remains, pending an upstream change there).

…ment - Replace deprecated String.prototype.substr with slice in hexToBytes. - Add light input validation to bytesToHex, base64ToBytes, bytesToBase64, concatBytes, and bytesEqual — they now throw informative TypeErrors instead of opaque runtime errors on non-bytes input. - Export the helpers as DAPIClient.bytes so the recommended migration path (bytesToHex(field) instead of field.toString('hex')) is reachable via the package's public surface instead of a deep import into lib/utils/bytes. - README: add a Browser usage section explaining that response fields are Uint8Array, that DAPIClient.bytes is the conversion helper, and that two internal paths (BlockHeadersProvider via dashcore-lib, Identifier.from via wasm-dpp) still construct Buffer — browser consumers must ensure Buffer is reachable at runtime via their bundler or an explicit polyfill until dashcore-lib's BufferReader accepts Uint8Array.

@deprecated

Identifier no longer extends Buffer at the prototype level. It now extends Uint8Array, so new Identifier(x), id.toString('hex'), id.toString('base64'), id.toString('base58'), id.toBytes(), and id.equals(other) work without a Buffer polyfill at runtime. The wasm-dpp module loader also drops Buffer.from in favor of an inline atob-based decode. toBuffer() is retained as a @deprecated compatibility shim that returns Buffer.from(this); it still requires the Buffer global to exist at call time but no longer at module load time. External callers migrating off Buffer should prefer toBytes() going forward. BREAKING for any code that relied on Identifier extending Buffer: Buffer.isBuffer(id), id instanceof Buffer, and Buffer-specific methods on id (.readUInt32LE, .equals, etc.) no longer work. The one such internal callsite (wallet-lib's IdentitySyncWorker) is migrated to check instanceof Uint8Array. The error message string changed from 'Identifier expects Buffer' to 'Identifier expects Uint8Array' (accepted-type check itself remains a widening — Buffer extends Uint8Array). bs58 (via safe-buffer) is the remaining transitive Buffer dependency in wasm-dpp; eliminating it requires replacing bs58 with a Uint8Array-native base58 library and is out of scope here.

…to .toBytes() Mechanical follow-up to the Identifier extends Uint8Array commit. All internal test code now uses the Buffer-free .toBytes() accessor on Identifier instances (.getId(), .getOwnerId(), .getContractId(), .getDataContractId(), and direct identityId/contractId/ownerId variables). The deprecated .toBuffer() method is retained for external compatibility but no longer used inside the monorepo. Also strips redundant new Uint8Array(...) wraps around .toBytes() — toBytes already returns a fresh Uint8Array, so the wrap was a copy of a copy.

@returns

Acted on real findings, dropped false positives. Fixed: - wallet-lib getTransaction: Buffer.from(response.getBlockHash()).toString('hex') instead of relying on Uint8Array.toString('hex') which ignores the encoding arg. After PR 2's migration, GetTransactionResponse.getBlockHash() returns a plain Uint8Array, so the previous code returned a comma-delimited decimal string instead of hex. - GetProtocolVersionUpgradeVoteStatusResponse: use versionSignal.getProTxHash_asU8() instead of new Uint8Array(versionSignal.getProTxHash()). The default protobuf getter yields a base64 string under grpc-web; new Uint8Array(string) does not base64-decode, it iterates chars and produces zeros. _asU8 explicitly returns Uint8Array bytes in both grpc-js and grpc-web. - wallet-lib Transport.d.ts: getIdentityByPublicKeyHash signature updated from (publicKeyHash: Buffer): Promise<Buffer[]> to (publicKeyHash: Uint8Array): Promise<Uint8Array>. Matches the post-migration runtime contract. - wasm-dpp Document.spec.js #getDataContractId: was calling getOwnerId() and asserting against $ownerId. Now actually exercises getDataContractId. - GetIdentityByPublicKeyHashResponse JSDoc: @param renamed from identities (plural) to identity (singular); @returns Uint8Array[] corrected to Uint8Array. Both predate this PR; cleaned up while touching the file. - GetIdentityContractNonce.spec.js, GetIdentityNonce.spec.js: proof-only constructor-pass-through tests now use BigInt(0) (matches the actual nonce type) instead of new Uint8Array(0). - GetIdentityKeys.spec.js: proof-only test now uses [] (matches the array-of-keys contract) instead of new Uint8Array(0). - PlatformMethodsFacade.spec.js: getIdentityNonce second arg is now {} (options) instead of a second Uint8Array. Predates the migration. - SimplifiedMasternodeListProvider catch block: guards bytesToHex call when simplifiedMNListDiffBytes is undefined, so the original error isn't masked by a secondary TypeError from the new bytesToHex input validation. Skipped (false positives): - GetDataContractResponse, GetIdentityResponse, GetIdentityByPublicKeyHashResponse createFromProto 'new Uint8Array(undefined)' findings: the existing tests explicitly assert new Uint8Array(0) for the proof-only path, and new Uint8Array(undefined) === new Uint8Array(0). Current behavior matches contract. - wasm-dpp loadDpp atob fallback: atob has been a Node global since 16.0.0, and the package's engines.node is >=18.18 (PR 1). No fallback needed. - validateDocumentsBatchTransitionBasicFactory.spec.js .toBuffer() nitpick: inside a describe.skip block; dead code.

Converts @dashevo/dapi-client to pure ESM: type: module, exports map with ./lib/* wildcard, all CJS require/module.exports replaced with import/export, .js extensions on relative imports. Engine bumped to >=18.18. Drops webpack.config.js, karma.conf.js, and lib/test/karma/. Removes the @babel/core, babel-loader, browser-polyfill, karma, and webpack devDeps. Consumers must use a modern bundler (Vite/esbuild/webpack 5) which handles ESM natively. Moves 'events' npm package from devDependencies to dependencies — used by DAPIClient, ReconnectableStream, and BlockHeadersProvider for EventEmitter, and resolves correctly in both Node and browser bundlers. BREAKING: CJS consumers (require) no longer work. Downstream consumers wallet-lib (PR 4) and js-dash-sdk (PR 5) are temporarily broken between this PR merging and PRs 4/5 merging — they must land as a sequence. Dashmate is already ESM and continues to work. Test results: dapi-client 315/315. wallet-lib + js-dash-sdk fail as expected (fixed by PRs 4 + 5).

Converts @dashevo/wallet-lib to pure ESM so it can consume the ESM dapi-client from PR 3. Adds 'type: module' to package.json. All src/, fixtures/, and tests/ files converted from CJS require/module.exports to ESM import/export with .js extensions on relative imports. Deletes webpack.config.js, karma/, src/test/karma/. Removes browser-polyfill devDeps (buffer, crypto-browserify, stream-browserify, etc.) and webpack/karma. Tests run via Mocha in Node 18+; browser builds are out of scope. Engines: >=18.18. CJS-named-import fixes: lodash, crypto-js, @dashevo/dashcore-lib, @dashevo/wasm-dpp, @dashevo/grpc-common all use default-import + destructure pattern because Node ESM cannot statically enumerate named exports of CJS modules. Surfaces three previously-silent CJS bugs that ESM strict mode catches: missing UnknownStrategy export from errors/index.js, missing named exports for coinSelection strategies, and a 'type=' implicit-global in DerivableKeyChain.spec.js. Defensive (loadDpp.default ?? loadDpp)() unwrap in IdentitySyncWorker.onStart for the same wasm-dpp NodeNext interop reason as PR 3's bootstrap. Test results: wallet-lib 377/377 passing. dapi-client unchanged (315/315). js-dash-sdk still broken (PR 5 fixes).

…SM dapi-client and wallet-lib Final PR in the ESM migration stack. Converts the two remaining workspace packages that consumed dapi-client/wallet-lib, restoring monorepo-wide green tests after PR 3. js-dash-sdk: TypeScript-based package with NodeNext module resolution. Adds 'type: module' + exports map. tsconfig.build.json → module: nodenext, moduleResolution: nodenext, target: es2020. All .ts files get .js extensions on relative imports (TS NodeNext compiles .ts to .js but the import string must already say .js). Drops ts-mock-imports by refactoring register.ts to accept an injectable randomBytes parameter (ts-mock-imports relies on mutable module exports which ESM forbids). Deletes webpack/karma + browser polyfills. Replaces winston with console-backed logger. CJS-named-import conversions for @dashevo/dashcore-lib, @dashevo/wasm-dpp, @dashevo/grpc-common, and the system-id imports from contract packages. Adds parallel 'import type' aliases (via 'import type { X as XType }; type X = XType;') in 22 .ts files where destructured value names are also used as types — works around TS2440 namespace collision under NodeNext. platform-test-suite: converted ~35 files from CJS to ESM. Test bootstrap converted; .mocharc.yml uses 'import:' for ESM root hooks. Defensive (loadDpp.default ?? loadDpp)() unwrap in 4 sites (Platform.initializeDppModule, createIdentityFixtureInAccount, contracts/get.spec.ts, contracts/history.spec.ts). createGrpcTransportError-style dual-format byte handling preserved. Test results: 752 passing across the monorepo (dapi-client 315, wallet-lib 377, js-dash-sdk 60). platform-test-suite is end-to-end and requires live testnet credentials in .env (pre-existing constraint).

PastaPastaPasta requested review from QuantumExplorer and shumkov as code owners May 19, 2026 23:43

github-actions Bot added this to the v3.1.0 milestone May 19, 2026

This was referenced May 19, 2026

refactor(dapi)!: convert dapi-client to ESM, drop webpack/karma #3681

Closed

refactor(wallet-lib)!: convert to ESM, consume ESM dapi-client #3682

Closed

refactor(sdk,test-suite)!: convert to ESM, consume ESM dapi-client and wallet-lib #3683

Closed

PastaPastaPasta marked this pull request as draft May 19, 2026 23:45

PastaPastaPasta force-pushed the claude/esm-3-esm-conversion branch 3 times, most recently from 087ecec to d131469 Compare May 19, 2026 23:59

PastaPastaPasta mentioned this pull request May 24, 2026

chore(dapi): cleanup — drop unused deps, inline winston/fetch/promisify shims #3679

Merged

4 tasks

PastaPastaPasta force-pushed the claude/esm-3-esm-conversion branch 2 times, most recently from 01db54e to 3af296d Compare May 26, 2026 16:14

PastaPastaPasta force-pushed the claude/esm-3-esm-conversion branch 2 times, most recently from ca8a25e to 264012b Compare May 26, 2026 16:44

PastaPastaPasta added 3 commits May 26, 2026 11:56

PastaPastaPasta force-pushed the claude/esm-3-esm-conversion branch from 264012b to 78d87ae Compare May 26, 2026 16:59

PastaPastaPasta added 2 commits May 26, 2026 12:35

PastaPastaPasta force-pushed the claude/esm-3-esm-conversion branch from 78d87ae to 2d91cfc Compare May 26, 2026 17:58

docs(dapi-client): link upstream dashcore-lib#315 in browser-usage note

b925e10

PastaPastaPasta force-pushed the claude/esm-3-esm-conversion branch from 2d91cfc to 0308e5b Compare May 26, 2026 18:08

PastaPastaPasta added 3 commits May 26, 2026 13:43

PastaPastaPasta force-pushed the claude/esm-3-esm-conversion branch from 0308e5b to 1464665 Compare May 26, 2026 18:43

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

refactor(sdk,wallet-lib,test-suite)!: convert dapi-client + wallet-lib + js-dash-sdk + platform-test-suite to ESM#3689

refactor(sdk,wallet-lib,test-suite)!: convert dapi-client + wallet-lib + js-dash-sdk + platform-test-suite to ESM#3689
PastaPastaPasta wants to merge 11 commits into
v3.1-devfrom
claude/esm-3-esm-conversion

PastaPastaPasta commented May 19, 2026

Uh oh!

coderabbitai Bot commented May 19, 2026 •

edited

Loading

Review skipped

Uh oh!

github-actions Bot commented May 19, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

PastaPastaPasta commented May 19, 2026

Summary

What changes

@dashevo/dapi-client (commit 1: refactor(dapi-client)!: convert to ESM, drop webpack/karma)

@dashevo/wallet-lib (commit 2: refactor(wallet-lib)!: convert to ESM, consume ESM dapi-client)

dash / @dashevo/js-dash-sdk (commit 3: refactor(js-dash-sdk,platform-test-suite)!: convert to ESM, consume ESM dapi-client and wallet-lib)

@dashevo/platform-test-suite (also in commit 3)

Test plan

Breaking changes

Monorepo state after this lands

Stack

Uh oh!

coderabbitai Bot commented May 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review skipped

Uh oh!

github-actions Bot commented May 19, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

`@dashevo/dapi-client` (commit 1: `refactor(dapi-client)!: convert to ESM, drop webpack/karma`)

`@dashevo/wallet-lib` (commit 2: `refactor(wallet-lib)!: convert to ESM, consume ESM dapi-client`)

`dash` / `@dashevo/js-dash-sdk` (commit 3: `refactor(js-dash-sdk,platform-test-suite)!: convert to ESM, consume ESM dapi-client and wallet-lib`)

`@dashevo/platform-test-suite` (also in commit 3)

coderabbitai Bot commented May 19, 2026 •

edited

Loading