feat(api): additive API-consistency aliases, error taxonomy & events guarantee#4327
Open
gabrocheleau wants to merge 4 commits into
Open
feat(api): additive API-consistency aliases, error taxonomy & events guarantee#4327gabrocheleau wants to merge 4 commits into
gabrocheleau wants to merge 4 commits into
Conversation
…guarantee
Harmonize the public API across the active packages. Fully additive: no existing
export is renamed or removed; legacy names are kept and marked `@deprecated`.
Naming/construction aliases (legacy kept + deprecated where a name was wrong):
- tx: add `createFeeMarket1559TxFromBytesArray` (deprecate the mis-ordered
`create1559FeeMarketTxFromBytesArray`)
- binarytree: add `createBinaryTreeFromProof` (deprecate `binaryTreeFromProof`)
- common: add `createCommon(opts)` factory (constructor stays supported)
- statemanager: add `createMerkleStateManager`, `createSimpleStateManager`,
`createRPCStateManager`, `createStatefulBinaryTreeStateManager`
Errors:
- add shared structural contract `EthereumJSErrorLike { readonly code: string }`
(in rlp, re-exported from util)
- `EVMError` now exposes a stable `code` (`EVMErrorCode` map) and conforms to the
contract without being reparented (keeps `instanceof EVMError` working)
- `EthereumJSError` exposes `code` (mirrors `type.code`)
- remove dead commented-out `UsageError` machinery in util/src/errors.ts
Events:
- document the always-defined `events` guarantee on EVM/VM/Blockchain (runtime
already always-defines; interface types keep optional typing for compat)
Docs & tests:
- add docs/api-conventions-audit.md and an "API Conventions" chapter in DEVELOPER.md
- per-package specs asserting each alias matches its legacy name / always-defined events
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Codecov Report❌ Patch coverage is Additional details and impacted files
Flags with carried forward coverage won't be shown. Click here to find out more. 🚀 New features to boost your workflow:
|
📦 Bundle Size Analysis
Values are minified+gzipped bundles of each package entry. Workspace deps are bundled; external deps are excluded. Generated by bundle-size workflow |
Allowlist the technical term `reparent`/`reparented`/`reparenting` (cspell-ts + cspell-md) and `epoc` (cspell-md, mirroring the existing ethash override; quoted `getEpoc` export name). Reword two coinages in the audit doc (`subfolders` → `subdirectories`, `undeprecated` → "not deprecated"). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Harmonizes the public API across the active packages so they read as if written by one person. Fully additive — no existing export is renamed or removed; legacy names are kept and marked
@deprecated(JSDoc only, no runtime warnings). A full audit of the current surface is added atdocs/api-conventions-audit.md, and the conventions are documented in an new "API Conventions" chapter inDEVELOPER.md.Construction / naming aliases
The monorepo-wide convention is the
createX()factory. This aligns the holdouts and fixes one mis-ordered name:createFeeMarket1559TxFromBytesArray; the existingcreate1559FeeMarketTxFromBytesArray(whose token order didn't match theFeeMarket1559Txclass or its sibling factories) is kept and deprecated.createBinaryTreeFromProofto matchcreateMPTFromProof;binaryTreeFromProofkept and deprecated.createCommon(opts)factory (theCommonconstructor stays fully supported).createMerkleStateManager,createSimpleStateManager,createRPCStateManager,createStatefulBinaryTreeStateManager(constructors stay supported).Errors
EthereumJSErrorLike { readonly code: string }(defined in@ethereumjs/rlp, re-exported from@ethereumjs/util).EVMErrornow exposes a stable machine-readablecode(EVMErrorCode, e.g.EVM_OUT_OF_GAS) and conforms to the contract without being reparented onto theError/EthereumJSErrorprototype chain — soinstanceof EVMErrorkeeps working. The message-only constructor still works; an explicit code can be passed as a second argument.EthereumJSErrornow exposescode(mirrorstype.code).UsageErrormachinery inutil/src/errors.ts.Events
eventsguarantee onEVM/VM/Blockchain(runtime already always-assigns it; theEVMInterface/BlockchainInterfacetypes keep the optional typing for backwards compatibility). Typed event maps (EVMEvent,VMEvent,BlockchainEvent,CommonEvent) remain exported from eachtypes.ts.Tests
Per-package specs assert each new alias matches its legacy name (identical output / same class) and that
eventsis always a definedEventEmitter.Verification
npm run tscclean (the only failures are the un-checked-outethereum-tests/execution-spec-testssubmodules, pre-existing and unrelated).biomeclean on all changed files;lint:diffgreen.tx,binarytree,common,statemanager,evm,vm,blockchain,rlp,util.🤖 Generated with Claude Code