breaking: upgraded deps, refactor buffer -> uint8array for consistency, upgraded eslint v10.#134
Conversation
Synchronize documentation with recent API and type refactors across the codebase. Key updates include: - Rename and usage updates for factory ABI exports (e.g. OP20FactoryAbi, MotoChefFactoryAbi) and template ABIs. - Replace RevertDecoder class with decodeRevertData and update examples accordingly. - Change CallResult/contract API types (Uint8Array for calldata/notes, new return shapes, send/sign signatures) and update examples to use try/catch (contracts now throw on revert). - Provider API signature and options changes (timeout, fetcherConfigurations/Agent.Options, useThreadedHttp) and some provider method return-type adjustments. - Epoch API: rename targetHash -> checksumRoot and adjust related types/usage. - UTXO manager/UTXO API: introduce UTXO/UTXOsManager class-like interfaces, additional request options (mergePendingUTXOs, filterSpentUTXOs, olderThan, CSV flags), getPending/getMultiple, and adjust examples. - Block witnesses: getBlockWitness now returns an array of block witness results; update interfaces and all example usages to handle paged/multi-block responses. - Reorg detection: ReorgInformation fields renamed to fromBlock/toBlock and examples updated. - ContractData/ContractData class: expand/rename fields and update examples to treat address as string. - Gas estimation and other type tweaks: introduce class-like interfaces and readonly fields for some structures. - Transaction parameter changes: note now supports Uint8Array and p2wda flag added; various encoding/enum flag changes (input/output flags re-ordered and documented). - Examples expanded for factory/MotoChef usage, deployments, and event types; many code samples adjusted to new method signatures and return shapes. Also updated related TypeScript test file and small doc corrections to align with the above API changes. These changes keep docs consistent with recent runtime/type refactors and new method signatures.
Wrap several thrown Errors with the original error as the 'cause' to preserve error context (Contract.ts, JSONThreader.ts, SequentialWorker.ts, WorkerCreator.native.ts). Also apply minor formatting and import cleanups (reflow multi-line imports, remove redundant parentheses around await, tighten setTimeout calls) and disable the 'no-useless-assignment' ESLint rule in eslint.config.js.
Bump package version to 1.8.1-rc.2 and refactor provider APIs and websocket typing. Key changes: - package.json: version updated to 1.8.1-rc.2. - src/providers/JSONRpcProvider.ts: introduce JSONRpcProviderConfig interface and switch constructor to accept a config object; expose new config fields (timeout, fetcherConfigurations, useThreadedParsing, useThreadedHttp) with sensible defaults; internal fetcher fields extracted; setFetchMode is commented out; include original error as cause on timeout. - src/providers/WebsocketRpcProvider.ts: introduce WebSocketRpcProviderConfig and validate URL (must start with ws:// or wss://); compose config from DEFAULT_CONFIG and provided websocketConfig; reorganize imports to use new typed modules. - src/providers/websocket/MethodMapping.ts: add a dedicated METHOD_MAPPINGS file (JSON-RPC to WebSocket opcode/type mappings) and import it from the WebSocket provider. - Remove barrel exports: src/providers/websocket/index.ts and src/providers/websocket/types/index.ts were deleted in favor of explicit typed exports. These changes improve configuration clarity, modularize websocket type mappings, and enforce stricter WebSocket URL validation.
Update docs and examples to initialize JSONRpcProvider/WebSocketRpcProvider with a single config object ({ url, network, ... }) instead of positional args. Add JSONRpcProviderConfig and WebSocketRpcProviderConfig shapes in docs, remove/replace outdated REST-mode constructor references, and update various examples to use fetcherConfigurations/timeout/useThreadedParsing/useThreadedHttp fields. Adjust related inline examples in src comments and update test expectation for threaded HTTP config usage. Also bump package version to 1.8.1-rc.2.
Update dependencies: bump @btc-vision/bip32 to ^7.1.2, @btc-vision/ecpair to ^4.0.5 and change @btc-vision/bitcoin from a local file reference to ^7.0.0-rc.4. In src/threading/SharedThreader.ts add explicit type annotations for several private fields, reorder and mark stats-related fields, simplify unload/window/self event listener conditionals, and apply minor formatting changes. These edits improve type safety and code clarity without changing runtime behavior.
Interpret a revert field as a valid revert even if it's an empty string and expose a failed flag on receipts. Update DeploymentTransaction to only allow missing deployerAddress when revert is present (not null/undefined). Add documentation comments to transaction interfaces clarifying revert semantics and set TransactionReceipt.failed based on presence of revert. Also update tests to use Satoshi bigint and RawEventList. The rest of the changes are non-functional cleanups: import/order and formatting tweaks, condensed ternaries in CallResultSerializer and ContractData, minor refactors in InteractionTransaction, WorkerCreator boolean expression simplification, and small test import reorders.
Store the raw UTXO as nonWitnessUtxoBase64 (base64 string) and introduce a lazily-decoded getter nonWitnessUtxo that returns a Uint8Array. The decoded value is cached in a private _nonWitnessUtxo to avoid repeated decoding. The getter throws if no raw data is available and includes JSDoc explaining its purpose (required for signing non-segwit inputs). Constructor updated to assign the raw base64 string instead of a decoded buffer.
Introduce a lazily-evaluated, cached getter for nonWitnessUtxo that decodes the base64 raw transaction to a Uint8Array on first access (using fromBase64). Replace the previous eager getter/_nonWitnessUtxo pattern with a defined property installed in the constructor when raw data exists. Update typings and JSDoc to reflect the new optional nonWitnessUtxo field and add explanatory comments. Also fix misspelled @category tags in file JSDoc.
There was a problem hiding this comment.
Pull request overview
This PR synchronizes the library and documentation with recent breaking runtime/type refactors: migrating binary data handling from Buffer to Uint8Array, updating provider constructors to accept config objects, and aligning docs/tests/examples with new call/receipt/revert semantics. It also bumps dependencies and upgrades ESLint to v10.
Changes:
- Refactor public-facing types and internal decoding/serialization to use
Uint8Array(calldata, receipts, scripts, epoch/challenge fields, etc.). - Update provider constructors/APIs (JSON RPC + WebSocket) to accept config objects and adjust threading/timeouts behavior; reorganize WebSocket mappings/types exports.
- Update tests + docs/examples to reflect new signatures, revert handling (throwing), and updated API return shapes.
Reviewed changes
Copilot reviewed 110 out of 110 changed files in this pull request and generated 5 comments.
Show a summary per file
| File | Description |
|---|---|
| test/utxos-manager.test.ts | Updates JSONRpcProvider constructor usage to config object |
| test/threaded-http.test.ts | Updates threaded HTTP expectations and provider construction |
| test/call-result-validation.test.ts | Adjusts test typing (Satoshi bigint) + RawEventList usage |
| test/call-result-serializer.test.ts | Updates serializer tests for Uint8Array buffers and hex-like fields |
| src/utils/StringToBuffer.ts | Switches helpers to return Uint8Array using fromHex/fromBase64 |
| src/utils/RevertDecoder.ts | Standardizes revert decoding to Uint8Array inputs |
| src/transactions/metadata/TransactionReceipt.ts | Uses Uint8Array receipt/revert bytes; adds failed flag |
| src/transactions/metadata/TransactionOutput.ts | Uses fromHex for script decompile input |
| src/transactions/interfaces/transactions/IInteractionTransaction.ts | Updates transaction binary fields to Uint8Array unions |
| src/transactions/interfaces/transactions/IDeploymentTransaction.ts | Updates deployment binary fields to Uint8Array unions |
| src/transactions/interfaces/ProofOfWorkChallenge.ts | Converts POW challenge preimage to Uint8Array |
| src/transactions/interfaces/ITransactionReceipt.ts | Updates receipt/revert field types and clarifies revert semantics |
| src/transactions/interfaces/ITransactionBase.ts | Updates base transaction revert type and semantics note |
| src/transactions/decoders/InteractionTransaction.ts | Decodes base64 fields via fromBase64 into Uint8Array |
| src/transactions/decoders/DeploymentTransaction.ts | Decodes deployment fields via fromBase64/fromHex; adjusts missing deployer semantics |
| src/transactions/Transaction.ts | Decodes POW challenge preimage via fromBase64 |
| src/threading/WorkerCreator.ts | Simplifies browser environment boolean expression |
| src/threading/WorkerCreator.native.ts | Removes redundant parentheses; adds error cause on timeout |
| src/threading/SharedThreader.ts | Adds explicit private field types and simplifies unload listener checks |
| src/threading/SequentialWorker.ts | Adds error cause on timeout |
| src/threading/JSONThreader.ts | Reorders type imports; simplifies timeout set; adds error cause |
| src/threading/JSONThreader.native.ts | Reorders type imports |
| src/storage/interfaces/IStorageValue.ts | Changes stored value type to `string |
| src/storage/StoredValue.ts | Decodes stored values via fromHex/fromBase64; updates pointer decode |
| src/providers/websocket/types/index.ts | Removes barrel export |
| src/providers/websocket/index.ts | Removes barrel export |
| src/providers/websocket/MethodMapping.ts | Extracts JSON-RPC method ↔ opcode mapping into dedicated module |
| src/providers/WebsocketRpcProvider.ts | Refactors constructor to config object + reorganizes imports/types wiring |
| src/providers/JSONRpcProvider.ts | Introduces config-object constructor + threaded HTTP toggles + timeout cause |
| src/providers/AbstractRpcProvider.ts | Migrates internal encoding/decoding from Buffer to Uint8Array + hex/base64 helpers |
| src/opnet.ts | Reworks WebSocket exports to explicit type exports |
| src/epoch/interfaces/IEpoch.ts | Converts epoch-related binary fields to Uint8Array |
| src/epoch/interfaces/EpochSubmissionParams.ts | Converts submission params to Uint8Array fields |
| src/epoch/SubmittedEpoch.ts | Converts submission hash to Uint8Array |
| src/epoch/EpochTemplate.ts | Converts epoch target to Uint8Array |
| src/epoch/EpochSubmission.ts | Converts submission ids/hashes to Uint8Array |
| src/epoch/Epoch.ts | Converts epoch miner + epoch fields to Uint8Array |
| src/crypto/crypto-browser.js | Import reorder cleanup |
| src/contracts/interfaces/SimulatedTransaction.ts | Converts stripped tx input/output binary fields to Uint8Array |
| src/contracts/interfaces/IRawContract.ts | Converts contract binary fields to Uint8Array unions |
| src/contracts/interfaces/IProviderForCallResult.ts | Import order cleanup |
| src/contracts/interfaces/IContract.ts | encodeCalldata now returns Uint8Array |
| src/contracts/interfaces/ICallResult.ts | Allows Uint8Array in ICallResultData.result |
| src/contracts/ContractData.ts | Migrates contract data decoding to Uint8Array |
| src/contracts/Contract.ts | Updates calldata encoding to return Uint8Array; minor refactors + error cause |
| src/contracts/CallResultSerializer.ts | Switches serializer IO to Uint8Array; decodes hex strings via fromHex |
| src/contracts/CallResult.ts | Migrates note/calldata/result handling to Uint8Array; offline buffer now Uint8Array |
| src/block/interfaces/IBlockWitness.ts | Converts witness fields to Uint8Array |
| src/block/BlockWitness.ts | Converts witness fields to Uint8Array |
| src/bitcoin/UTXOs.ts | Fixes JSDoc @category; adds lazy-decoded nonWitnessUtxo getter caching base64 decode |
| src/abi/shared/json/motoswap/TEMPLATE_OP20_ABI.ts | Import reorder |
| src/abi/shared/interfaces/opnet/IOP20Contract.ts | Updates docs example provider construction |
| src/abi/shared/interfaces/motoswap/ITemplateOP20.ts | Converts Buffer types to Uint8Array for ABI return/param types |
| src/abi/shared/interfaces/motoswap/IOP20Factory.ts | Converts Buffer types to Uint8Array for ABI return/param types |
| src/abi/shared/interfaces/motoswap/INativeSwapContract.ts | Converts Buffer receiver/selector types to Uint8Array |
| src/abi/shared/interfaces/motoswap/IMotoChefFactory.ts | Converts Buffer types to Uint8Array |
| src/abi/shared/interfaces/motoswap/IMotoChef.ts | Converts selector type to Uint8Array |
| src/_version.ts | Version bump to 1.8.1-rc.2 |
| package.json | Dependency bumps + ESLint v10 upgrade; version bump |
| eslint.config.js | Disables no-useless-assignment rule with added comment |
| docs/utils/revert-decoder.md | Updates receipt/transaction revert extraction examples |
| docs/transactions/transaction-receipts.md | Updates provider construction and event field names |
| docs/transactions/fetching-transactions.md | Updates provider construction and transaction field shapes |
| docs/transactions/challenges.md | Updates provider construction |
| docs/transactions/broadcasting.md | Updates provider construction |
| docs/storage/storage-operations.md | Updates provider construction |
| docs/public-keys/public-key-operations.md | Updates provider construction and signature docs |
| docs/providers/websocket-provider.md | Updates API names/config patterns for WebSocket provider |
| docs/providers/understanding-providers.md | Updates provider construction examples |
| docs/providers/threaded-http.md | Updates threaded HTTP enablement and JsonThreader API docs |
| docs/providers/json-rpc-provider.md | Updates constructor docs to config object; removes REST-mode section |
| docs/providers/internal-caching.md | Updates provider construction and block subscription example |
| docs/providers/advanced-configuration.md | Updates provider construction and retry guidance |
| docs/getting-started/quick-start.md | Updates provider construction examples |
| docs/getting-started/overview.md | Updates exports (TransactionBase/decodeRevertData) |
| docs/getting-started/installation.md | Updates provider construction examples |
| docs/examples/op721-examples.md | Updates revert handling guidance (try/catch) and provider construction |
| docs/examples/op20-examples.md | Updates allowance method names + revert handling + provider construction |
| docs/examples/deployment-examples.md | Updates provider construction |
| docs/examples/advanced-swaps.md | Updates allowance method names + revert handling + provider construction |
| docs/epochs/submitting-epochs.md | Updates epoch submission params (checksumRoot etc.) and provider construction |
| docs/epochs/overview.md | Updates provider construction |
| docs/epochs/mining-template.md | Updates provider construction |
| docs/epochs/epoch-operations.md | Updates signatures/params and provider construction |
| docs/contracts/transaction-configuration.md | Updates note to Uint8Array + adds p2wda |
| docs/contracts/simulating-calls.md | Updates CallResult shape + revert decoder import + flags docs |
| docs/contracts/sending-transactions.md | Updates note to Uint8Array + adds p2wda |
| docs/contracts/overview.md | Updates revert handling to try/catch model |
| docs/contracts/offline-signing.md | Updates provider construction examples |
| docs/contracts/instantiating-contracts.md | Updates provider construction examples |
| docs/contracts/gas-estimation.md | Updates BlockGasParameters docs and provider construction |
| docs/contracts/contract-code.md | Updates ContractData docs to string address + expanded fields |
| docs/blocks/reorg-detection.md | Updates reorg field names and provider construction |
| docs/blocks/gas-parameters.md | Updates provider construction |
| docs/blocks/block-witnesses.md | Updates witness API docs for array return + provider construction |
| docs/blocks/block-operations.md | Updates provider construction + block height typing |
| docs/bitcoin/utxos.md | Updates provider construction + UTXO class doc |
| docs/bitcoin/utxo-optimization.md | Updates provider construction |
| docs/bitcoin/sending-bitcoin.md | Updates provider construction |
| docs/bitcoin/balances.md | Updates provider construction + WebSocket provider config usage |
| docs/api-reference/utxo-manager-api.md | Updates UTXO manager API surface + options |
| docs/api-reference/types-interfaces.md | Updates ContractData + EpochSubmissionParams docs |
| docs/api-reference/provider-api.md | Updates provider constructor signatures and epoch return type docs |
| docs/api-reference/epoch-api.md | Updates epoch submission param naming (checksumRoot) and return types |
| docs/api-reference/contract-api.md | Updates contract API return types + calldata/note types |
| docs/abi-reference/op721-abi.md | Updates provider construction example |
| docs/abi-reference/op20s-abi.md | Updates provider construction example |
| docs/abi-reference/op20-abi.md | Updates provider construction example |
| docs/abi-reference/factory-abis.md | Updates ABI export names + method docs/examples |
| docs/README.md | Updates provider construction and revert decoder section link |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| this.deployerHashedPublicKey = | ||
| raw.deployerAddress instanceof Address | ||
| ? fromHex((raw.deployerAddress as unknown as string).replace('0x', '')) | ||
| : fromBase64((raw.deployerAddress as unknown as string).replace('0x', '')); |
There was a problem hiding this comment.
deployerHashedPublicKey is derived from raw.deployerAddress, but IRawContract.deployerAddress is typed as Address. raw.deployerAddress instanceof Address will always be true for well-typed inputs, and casting it to string then fromHex(...) will produce invalid hex (e.g., "[object Object]") and throw. If the API actually returns a hex string, the fallback branch decodes it as base64 which is also incorrect.
Recommendation: make IRawContract.deployerAddress accurately reflect the API (likely string/hex), decode it consistently with fromHex after stripping an optional 0x prefix, and/or add an explicit deployerHashedPublicKey field instead of overloading deployerAddress.
| constructor(receipt: ITransactionReceipt, network: Network) { | ||
| this.receipt = receipt.receipt | ||
| ? Buffer.from(receipt.receipt as string, 'base64') | ||
| : undefined; | ||
| this.receipt = receipt.receipt ? fromBase64(receipt.receipt as string) : undefined; | ||
|
|
||
| this.receiptProofs = receipt.receiptProofs || []; | ||
| this.events = receipt.events ? this.parseEvents(receipt.events, network) : {}; | ||
|
|
||
| this.rawRevert = receipt.revert | ||
| ? Buffer.from(receipt.revert as string, 'base64') | ||
| : undefined; | ||
| this.rawRevert = receipt.revert ? fromBase64(receipt.revert as string) : undefined; | ||
|
|
||
| this.revert = this.rawRevert ? decodeRevertData(this.rawRevert) : undefined; | ||
| this.failed = receipt.revert !== undefined && receipt.revert !== null; |
There was a problem hiding this comment.
The new "revert can be an empty string" semantics aren't consistently applied here. this.rawRevert = receipt.revert ? ... : undefined treats an empty string as falsy, so rawRevert/revert stay undefined even though failed is set to true.
Recommendation: use the same presence check as failed (null/undefined) when deciding whether to decode, and handle receipt.revert being a Uint8Array now that the interface allows it (don’t unconditionally cast to string).
| export interface JSONRpcProviderConfig { | ||
| readonly url: string; | ||
| readonly network: Network; | ||
| readonly timeout?: number; | ||
| readonly fetcherConfigurations?: Agent.Options; | ||
| //readonly useRESTAPI?: false; // not supported yet, reserved for future use | ||
| readonly useThreadedParsing?: boolean; | ||
| readonly useThreadedHttp?: boolean; | ||
| } |
There was a problem hiding this comment.
JSONRpcProviderConfig exposes fetcherConfigurations?: Agent.Options, but this file currently relies on undici/types/* to reference that type. To keep the public type surface stable across TS/bundlers, prefer referencing Agent from the main undici entrypoint (e.g., import type { Agent } from 'undici') rather than internal undici/types/... paths.
| /** WebSocket Provider */ | ||
| export * from './providers/websocket/index.js'; | ||
| export * from './providers/websocket/types/SubscriptionType.js'; | ||
| export * from './providers/websocket/types/ConnectionState.js'; | ||
| export * from './providers/websocket/types/PendingRequest.js'; | ||
| export * from './providers/websocket/types/WebSocketClientConfig.js'; | ||
| export * from './providers/websocket/types/WebSocketProviderTypes.js'; | ||
| export * from './providers/websocket/types/WebSocketErrorCodes.js'; | ||
| export * from './providers/websocket/types/WebSocketOpcodes.js'; |
There was a problem hiding this comment.
src/opnet.ts no longer re-exports the WebSocket surface from ./providers/websocket/index.js, but it also doesn’t re-export OPNetError. The docs in this PR still show import { JSONRpcProvider, OPNetError } from 'opnet', so consumers will break.
Recommendation: explicitly export OPNetError (and any other intended public websocket exports) from the entrypoint to match the documented public API.
| constructor(providerConfig: WebSocketRpcProviderConfig) { | ||
| super(providerConfig.network); | ||
|
|
||
| if (!providerConfig.url) { | ||
| throw new Error('WebSocketRpcProvider requires a URL in the configuration'); | ||
| } | ||
|
|
||
| if (!providerConfig.url.startsWith('ws://') && !providerConfig.url.startsWith('wss://')) { | ||
| throw new Error('WebSocketRpcProvider URL must start with ws:// or wss://'); | ||
| } | ||
|
|
||
| this.config = { ...DEFAULT_CONFIG, url, ...config }; | ||
| this.config = { | ||
| ...DEFAULT_CONFIG, | ||
| url: providerConfig.url, | ||
| ...providerConfig.websocketConfig, | ||
| }; |
There was a problem hiding this comment.
WebSocketRpcProvider is now configured via an object and the JSON-RPC side has been updated to use checksumRoot for epoch submission, but the WebSocket submit-epoch path in this class still references targetHash (see the SUBMIT_EPOCH request mapping further down). That will result in undefined being sent when users pass checksumRoot.
Recommendation: update the submit-epoch mapping to read checksumRoot (and update any protobuf field mapping/comments accordingly) so WebSocket and HTTP providers accept the same parameter names.
Description
Synchronize documentation with recent API and type refactors across the codebase. Key updates include:
Also updated related TypeScript test file and small doc corrections to align with the above API changes. These changes keep docs consistent with recent runtime/type refactors and new method signatures.
Introduce a lazily-evaluated, cached getter for nonWitnessUtxo that decodes the base64 raw transaction to a Uint8Array on first access (using fromBase64). Replace the previous eager getter/_nonWitnessUtxo pattern with a defined property installed in the constructor when raw data exists. Update typings and JSDoc to reflect the new optional nonWitnessUtxo field and add explanatory comments. Also fix misspelled @category tags in file JSDoc.
Interpret a revert field as a valid revert even if it's an empty string and expose a failed flag on receipts. Update DeploymentTransaction to only allow missing deployerAddress when revert is present (not null/undefined). Add documentation comments to transaction interfaces clarifying revert semantics and set TransactionReceipt.failed based on presence of revert. Also update tests to use Satoshi bigint and RawEventList. The rest of the changes are non-functional cleanups: import/order and formatting tweaks, condensed ternaries in CallResultSerializer and ContractData, minor refactors in InteractionTransaction, WorkerCreator boolean expression simplification, and small test import reorders.
Update dependencies: bump @btc-vision/bip32 to ^7.1.2, @btc-vision/ecpair to ^4.0.5 and change @btc-vision/bitcoin from a local file reference to ^7.0.0-rc.4. In src/threading/SharedThreader.ts add explicit type annotations for several private fields, reorder and mark stats-related fields, simplify unload/window/self event listener conditionals, and apply minor formatting changes. These edits improve type safety and code clarity without changing runtime behavior.
Update docs and examples to initialize JSONRpcProvider/WebSocketRpcProvider with a single config object ({ url, network, ... }) instead of positional args. Add JSONRpcProviderConfig and WebSocketRpcProviderConfig shapes in docs, remove/replace outdated REST-mode constructor references, and update various examples to use fetcherConfigurations/timeout/useThreadedParsing/useThreadedHttp fields. Adjust related inline examples in src comments and update test expectation for threaded HTTP config usage. Also bump package version to 1.8.1-rc.2.
Wrap several thrown Errors with the original error as the 'cause' to preserve error context (Contract.ts, JSONThreader.ts, SequentialWorker.ts, WorkerCreator.native.ts). Also apply minor formatting and import cleanups (reflow multi-line imports, remove redundant parentheses around await, tighten setTimeout calls) and disable the 'no-useless-assignment' ESLint rule in eslint.config.js.
Type of Change
Checklist
Build & Tests
npm installcompletes without errorsnpm testpasses all testsCode Quality
Documentation
Security
Testing
Related Issues
By submitting this PR, I confirm that my contribution is made under the terms of the project's license.