# Execution APIs v1.0.0 - Versioning Proposal

> **Purpose**: Establish the first tagged release to enable version referencing
> **Related Issue**: [#690 - API versioning via GitHub releases/tags](https://github.com/ethereum/execution-apis/issues/690)
> **Repository**: [ethereum/execution-apis](https://github.com/ethereum/execution-apis)
> **Date**: February 2026

---

## Background

### Why We Need This

Currently there's no way to refer to a specific version of the API specifications ([Issue #690](https://github.com/ethereum/execution-apis/issues/690)). This creates problems:

- **Service providers** cannot advertise which API version they support
- **Clients** don't know when API changes occur
- **No GitHub releases/tags** exist for version tracking

### Related Discussions

- [Issue #690](https://github.com/ethereum/execution-apis/issues/690) - API versioning via GitHub releases/tags (Aug 2025)
- [Issue #408](https://github.com/ethereum/execution-apis/issues/408) - Uniform versioning scheme for methods (May 2023)

### Existing Versioning Strategy

The repository already documents [semantic versioning](https://semver.org/) in the README:

| Release Type | What It Includes |
|--------------|------------------|
| **Major** | Breaking changes: new required fields, changed response types, renamed fields, new tests |
| **Minor** | Backward-compatible: optional params, new error codes, removing tests |
| **Patch** | Internal: typos, docs, tooling |

**However**, this has not been implemented via GitHub releases/tags.

---

## Analysis: What Should Go in v1

### Current State Summary

The repository currently contains:

| Namespace | Method Count | Notes |
|-----------|--------------|-------|
| `eth_*` | 41 methods | Core JSON-RPC interface |
| `engine_*` | 25 methods | Consensus/execution layer communication |
| `debug_*` | 5 methods | Raw data retrieval |

**Additional context:**

- Comprehensive test coverage for 30 methods (11 methods lack tests per [#737](https://github.com/ethereum/execution-apis/issues/737))
- Method-level versioning for Engine API (e.g., `newPayloadV1` through `newPayloadV5`)
- Fork-based organization: Paris → Shanghai → Cancun → Prague → Osaka → Amsterdam

---

## Open PRs - Categorized for v1 Decision

### Include in v1

| PR | Title | Rationale |
|----|-------|-----------|
| [#753](https://github.com/ethereum/execution-apis/pull/753) | Fix: engine nits | Bug fixes/nits should be merged before release |
| [#742](https://github.com/ethereum/execution-apis/pull/742) | test(debug_getRawReceipts): use post-Byzantium block for get-block-n test | Test improvement, no risk |

### Needs Discussion

| PR | Title | Rationale |
|----|-------|-----------|
| [#746](https://github.com/ethereum/execution-apis/pull/746) | Add `maxUseGas` field to `eth_simulateV1` | Enhancement to existing method - could be minor release |

### Defer to Later Release

| PR | Title | Rationale |
|----|-------|-----------|
| [#747](https://github.com/ethereum/execution-apis/pull/747) | Add `testing_buildBlockV1` RPC Method | New experimental method |
| [#710](https://github.com/ethereum/execution-apis/issues/710) | Add RPC endpoint `testing_buildBlockV1` | Duplicate of #747 |
| [#735](https://github.com/ethereum/execution-apis/pull/735) | EIP-8025 | New EIP, not yet widely adopted |
| [#726](https://github.com/ethereum/execution-apis/pull/726) | Add EIP-7928 Block-level Access Lists JSON RPC methods | New EIP, still evolving |

---

## Key Issues to Resolve Before v1

### Critical Priority

| Issue | Title | Impact |
|-------|-------|--------|
| [#690](https://github.com/ethereum/execution-apis/issues/690) | API versioning via GitHub releases/tags | Directly about the versioning process itself |
| [#658](https://github.com/ethereum/execution-apis/issues/658) | Standardize JSON-RPC Error codes | Affects all methods; breaking if changed later |
| [#650](https://github.com/ethereum/execution-apis/issues/650) | JSON RPC Error codes standardization using open-rpc extension specs | Related to #658 |

### High Priority

| Issue | Title | Impact |
|-------|-------|--------|
| [#713](https://github.com/ethereum/execution-apis/issues/713) | Fully apply EIP-1898 in specs | Consistency issue across methods |

### Medium Priority

| Issue | Title | Impact |
|-------|-------|--------|
| [#737](https://github.com/ethereum/execution-apis/issues/737) | Missing Test Coverage for 11 JSON-RPC Methods | Gaps in validation |
| [#663](https://github.com/ethereum/execution-apis/issues/663) | GenericTransaction Should Contain `data` in the schema | Schema correctness |
| [#634](https://github.com/ethereum/execution-apis/issues/634) | Is the pattern for the byte type correct? | Schema correctness |
| [#648](https://github.com/ethereum/execution-apis/issues/648) | Correct example value type for `terminalTotalDifficulty` | Documentation accuracy |

---

## Suggested v1 Scope

### Include (Stable, Core)

- All existing `eth_*` methods with full test coverage
- Engine API through Cancun fork (V1-V3 methods)
- Debug API as-is
- [PR #753](https://github.com/ethereum/execution-apis/pull/753) (engine nits fix)
- [PR #742](https://github.com/ethereum/execution-apis/pull/742) (test improvement)

### Defer to v1.1/v2

- Prague/Osaka/Amsterdam fork methods (still in development)
- New EIP-specific methods ([#726](https://github.com/ethereum/execution-apis/pull/726), [#735](https://github.com/ethereum/execution-apis/pull/735))
- `testing_buildBlockV1` ([#747](https://github.com/ethereum/execution-apis/pull/747), [#710](https://github.com/ethereum/execution-apis/issues/710)) - experimental
- `eth_getCapabilities` ([#697](https://github.com/ethereum/execution-apis/issues/697)) - still a proposal

### Must Resolve Before v1

- [Issue #690](https://github.com/ethereum/execution-apis/issues/690) - versioning scheme itself
- [Issue #658](https://github.com/ethereum/execution-apis/issues/658) - error code standardization

---

## Detailed v1.0.0 Scope

### Eth Namespace (41 methods)

#### Account Methods (4)

| Method | Description |
|--------|-------------|
| `eth_accounts` | Returns list of addresses owned by client |
| `eth_getBalance` | Returns balance of account at given address |
| `eth_getCode` | Returns code at a given address |
| `eth_getProof` | Returns account and storage values with Merkle proof |

#### Block Methods (6)

| Method | Description |
|--------|-------------|
| `eth_blockNumber` | Returns current block number |
| `eth_getBlockByHash` | Returns block by hash |
| `eth_getBlockByNumber` | Returns block by number |
| `eth_getBlockReceipts` | Returns all receipts for a block |
| `eth_getBlockTransactionCountByHash` | Returns transaction count in block by hash |
| `eth_getBlockTransactionCountByNumber` | Returns transaction count in block by number |

#### Transaction Methods (8)

| Method | Description |
|--------|-------------|
| `eth_getTransactionByHash` | Returns transaction by hash |
| `eth_getTransactionByBlockHashAndIndex` | Returns transaction by block hash and index |
| `eth_getTransactionByBlockNumberAndIndex` | Returns transaction by block number and index |
| `eth_getTransactionCount` | Returns number of transactions sent from address |
| `eth_getTransactionReceipt` | Returns receipt of transaction by hash |
| `eth_sendRawTransaction` | Submits pre-signed transaction |
| `eth_sendTransaction` | Creates and sends transaction |
| `eth_signTransaction` | Signs transaction without sending |

#### Execution Methods (4)

| Method | Description |
|--------|-------------|
| `eth_call` | Executes call without creating transaction |
| `eth_estimateGas` | Estimates gas for transaction |
| `eth_createAccessList` | Creates access list for transaction |
| `eth_simulateV1` | Simulates sequence of calls |

#### Filter Methods (7)

| Method | Description |
|--------|-------------|
| `eth_newFilter` | Creates filter for logs |
| `eth_newBlockFilter` | Creates filter for new blocks |
| `eth_newPendingTransactionFilter` | Creates filter for pending transactions |
| `eth_getFilterChanges` | Returns filter changes since last poll |
| `eth_getFilterLogs` | Returns all logs matching filter |
| `eth_uninstallFilter` | Uninstalls filter |
| `eth_getLogs` | Returns logs matching filter object |

#### Fee/Gas Methods (4)

| Method | Description |
|--------|-------------|
| `eth_gasPrice` | Returns current gas price |
| `eth_maxPriorityFeePerGas` | Returns max priority fee per gas |
| `eth_feeHistory` | Returns historical gas information |
| `eth_blobBaseFee` | Returns current blob base fee |

#### Network Methods (4)

| Method | Description |
|--------|-------------|
| `eth_chainId` | Returns chain ID |
| `eth_syncing` | Returns sync status |
| `eth_coinbase` | Returns client coinbase address |
| `net_version` | Returns network ID |

#### Storage Methods (1)

| Method | Description |
|--------|-------------|
| `eth_getStorageAt` | Returns storage value at position |

#### Signing Methods (1)

| Method | Description |
|--------|-------------|
| `eth_sign` | Signs data with account |

#### Legacy/Uncle Methods (2)

| Method | Description |
|--------|-------------|
| `eth_getUncleCountByBlockHash` | Returns uncle count by block hash |
| `eth_getUncleCountByBlockNumber` | Returns uncle count by block number |

---

### Engine Namespace (Through Cancun Fork)

#### V1 Methods (Paris/Merge)

| Method | Description |
|--------|-------------|
| `engine_newPayloadV1` | Validate and execute payload |
| `engine_getPayloadV1` | Get execution payload |
| `engine_forkchoiceUpdatedV1` | Update fork choice state |
| `engine_exchangeTransitionConfigurationV1` | Exchange transition configuration |

#### V2 Methods (Shanghai)

| Method | Description |
|--------|-------------|
| `engine_newPayloadV2` | Validate and execute payload (with withdrawals) |
| `engine_getPayloadV2` | Get execution payload (with withdrawals) |
| `engine_forkchoiceUpdatedV2` | Update fork choice state (with withdrawals) |
| `engine_getPayloadBodiesByHashV1` | Get payload bodies by hash |
| `engine_getPayloadBodiesByRangeV1` | Get payload bodies by range |

#### V3 Methods (Cancun)

| Method | Description |
|--------|-------------|
| `engine_newPayloadV3` | Validate and execute payload (with blobs) |
| `engine_getPayloadV3` | Get execution payload (with blobs) |
| `engine_forkchoiceUpdatedV3` | Update fork choice state (with blobs) |
| `engine_getBlobsV1` | Get blobs by versioned hashes |

#### Utility Methods

| Method | Description |
|--------|-------------|
| `engine_exchangeCapabilities` | Exchange supported methods |
| `engine_getClientVersionV1` | Get client version info |

---

### Debug Namespace (5 methods)

| Method | Description |
|--------|-------------|
| `debug_getRawBlock` | Returns RLP-encoded block |
| `debug_getRawHeader` | Returns RLP-encoded header |
| `debug_getRawReceipts` | Returns RLP-encoded receipts |
| `debug_getRawTransaction` | Returns RLP-encoded transaction |

---

### PRs to Merge Before Tagging v1.0.0

| PR | Title | Status | Rationale |
|----|-------|--------|-----------|
| [#753](https://github.com/ethereum/execution-apis/pull/753) | Fix: engine nits | Open | Cleanup before release |
| [#742](https://github.com/ethereum/execution-apis/pull/742) | test(debug_getRawReceipts): use post-Byzantium block | Open | Test improvement |

---

## Deferred to v1.1 or v2

### Future Fork Methods (Prague/Osaka/Amsterdam)

These methods are still in development and should not be included in v1:

| Method | Fork | Status |
|--------|------|--------|
| `engine_newPayloadV4` | Prague | In development |
| `engine_newPayloadV5` | Osaka/Amsterdam | In development |
| `engine_getPayloadV4` | Prague | In development |
| `engine_getPayloadV5` | Osaka | In development |
| `engine_getPayloadV6` | Amsterdam | In development |
| `engine_forkchoiceUpdatedV4` | Prague | In development |
| `engine_getBlobsV2` | Prague | In development |
| `engine_getBlobsV3` | Osaka/Amsterdam | In development |
| `engine_getPayloadBodiesByHashV2` | Prague | In development |
| `engine_getPayloadBodiesByRangeV2` | Prague | In development |

### New Method Proposals

| Issue/PR | Method | Reason to Defer |
|----------|--------|-----------------|
| [#747](https://github.com/ethereum/execution-apis/pull/747), [#710](https://github.com/ethereum/execution-apis/issues/710) | `testing_buildBlockV1` | Experimental testing utility, duplicate PRs need consolidation |
| [#705](https://github.com/ethereum/execution-apis/issues/705) | `admin_mineBlock` | Testing utility, not core functionality |
| [#697](https://github.com/ethereum/execution-apis/issues/697) | `eth_getCapabilities` | Still a proposal, needs discussion |
| [#752](https://github.com/ethereum/execution-apis/issues/752) | `eth_getStorageValues` | New proposal for batch storage retrieval |

### New EIP Support

| Issue/PR | EIP | Reason to Defer |
|----------|-----|-----------------|
| [#735](https://github.com/ethereum/execution-apis/pull/735) | EIP-8025 | Not yet widely adopted |
| [#726](https://github.com/ethereum/execution-apis/pull/726) | EIP-7928 Block-level Access Lists | Still evolving |
| [#678](https://github.com/ethereum/execution-apis/issues/678) | EIP-7910 `eth_config` | Needs more community input |

### Enhancements to Existing Methods

| Issue/PR | Enhancement | Reason to Defer |
|----------|-------------|-----------------|
| [#746](https://github.com/ethereum/execution-apis/pull/746) | `maxUseGas` field for `eth_simulateV1` | Additive enhancement, suitable for minor release |
| [#700](https://github.com/ethereum/execution-apis/issues/700) | EIP-7702 authorization handling in `eth_call`/`eth_estimateGas` | Needs more discussion |
| [#640](https://github.com/ethereum/execution-apis/issues/640) | Authorization status in EIP-7702 transaction receipts | Dependent on EIP-7702 adoption |
| [#638](https://github.com/ethereum/execution-apis/issues/638) | `eth_estimateGas` tests for EIP-7702 and EIP-7623 | Dependent on EIP adoption |
| [#696](https://github.com/ethereum/execution-apis/issues/696) | Add example for `eth_simulateV1` | Documentation, can be added anytime |

### Documentation/Tooling Issues (Non-blocking)

| Issue | Title | Notes |
|-------|-------|-------|
| [#660](https://github.com/ethereum/execution-apis/issues/660) | Metamask OpenRPC Docusaurus Plugin - Deprecated | Tooling migration |
| [#655](https://github.com/ethereum/execution-apis/issues/655) | Separate `debug`, `engine`, and `eth` namespaces in docs | Documentation organization |
| [#651](https://github.com/ethereum/execution-apis/issues/651) | Call to Standardize `debug` Methods | Future standardization effort |
| [#673](https://github.com/ethereum/execution-apis/issues/673) | Add open-rpc linter to CI | Tooling improvement |
| [#644](https://github.com/ethereum/execution-apis/issues/644) | Fee Recipient is not COINBASE | Documentation clarification |

---

## Open Questions for Team

Please provide input on the following decisions:

### 1. Error Code Standardization

**Issue**: [#658](https://github.com/ethereum/execution-apis/issues/658), [#650](https://github.com/ethereum/execution-apis/issues/650)

Should we standardize JSON-RPC error codes before v1, or accept the current state and standardize in v2?

- **Option A**: Standardize before v1 (delays release, but avoids breaking change later)
- **Option B**: Accept current state, standardize in v2 (ships sooner, but breaking change in future)

### 2. Test Coverage Gap

**Issue**: [#737](https://github.com/ethereum/execution-apis/issues/737)

11 methods currently lack test coverage. Should we:

- **Option A**: Block v1 release until all 41 `eth_*` methods have tests
- **Option B**: Release v1 with current coverage, add missing tests in v1.x

### 3. eth_simulateV1 Enhancement

**PR**: [#746](https://github.com/ethereum/execution-apis/pull/746)

Should we include the `maxUseGas` field addition in v1?

- **Option A**: Include in v1 (additive, backward-compatible)
- **Option B**: Defer to v1.1 (keep v1 minimal)

### 4. EIP-1898 Compliance

**Issue**: [#713](https://github.com/ethereum/execution-apis/issues/713)

Should we fully apply EIP-1898 across all specs before v1?

- **Option A**: Yes, ensure full compliance (may require spec updates)
- **Option B**: Document current state, address in v1.x

### 5. Prague Fork Methods

Are any V4/V5 Engine API methods stable enough to include in v1, or should all Prague+ methods be deferred?

---

## Next Steps

### Before Tagging v1.0.0

- [ ] Reach consensus on open questions above
- [ ] Merge [PR #753](https://github.com/ethereum/execution-apis/pull/753) (engine nits)
- [ ] Merge [PR #742](https://github.com/ethereum/execution-apis/pull/742) (debug test fix)
- [ ] Decide on [#658](https://github.com/ethereum/execution-apis/issues/658) (error codes) - block or defer?
- [ ] Update [Issue #690](https://github.com/ethereum/execution-apis/issues/690) with versioning decision
- [ ] Create release notes documenting what's included
- [ ] Tag `v1.0.0` on GitHub

### Post v1.0.0

- [ ] Close [Issue #690](https://github.com/ethereum/execution-apis/issues/690)
- [ ] Plan v1.1 scope (Prague methods, deferred enhancements)
- [ ] Address remaining medium-priority issues

---

## Feedback

Please add your comments below or react with:

| Reaction | Meaning |
|----------|---------|
| :+1: | Agree with proposal |
| :-1: | Have concerns (please comment) |
| :eyes: | Need more information |
| :rocket: | Ready to ship |