Repository navigation
docs(sei-js): add the EVM parity matrix and plan (PLT-837) #103
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
base: main
Are you sure you want to change the base?
Changes from all commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,70 @@ | ||
| --- | ||
| title: 'EVM parity plan' | ||
| sidebarTitle: 'EVM parity plan' | ||
| description: 'The goals, scoring rules, and issue process behind the sei-js EVM parity matrix' | ||
| keywords: ['sei-js', 'evm parity', 'scoring', 'evm-compat', 'issue triage', 'viem', 'wagmi', 'ethers'] | ||
| --- | ||
|
|
||
| The [EVM parity matrix](/evm/sei-js/evm-parity) tracks how well common EVM workflows work on Sei with viem, wagmi, and ethers. This page explains what the matrix measures, how each cell is scored, and how compatibility reports are handled. | ||
|
|
||
| ## Goals | ||
|
|
||
| - At least 95% of scored matrix cells are Covered or Verified. | ||
| - No open [`evm-compat` issue](https://github.com/sei-protocol/sei-js/issues?q=is%3Aissue%20is%3Aopen%20label%3Aevm-compat) is older than 14 days. | ||
| - Every gap is marked as a sei-js gap or as a Sei network difference, so it is clear who fixes it. | ||
|
|
||
| ## Principles | ||
|
|
||
| - **Standard tooling first.** Use viem, wagmi, ethers, Foundry, Hardhat, and wallet standards as they are. sei-js adds a helper only when these tools cannot do a workflow on Sei by themselves. | ||
| - **Sei extensions second.** `@sei-js` packages fill the Sei-specific gaps: chain definitions, precompile ABIs, wallet discovery, log-range helpers, templates, and docs. | ||
| - **Evidence over claims.** Every Covered or Verified cell links to a docs page, a template, a test, or a conformance check. | ||
| - **Documented network differences.** When Sei differs from Ethereum on purpose, the docs explain the difference. sei-js does not hide it behind a wrapper. | ||
|
|
||
| ## What the matrix measures | ||
|
|
||
| The matrix scores developer workflows, not package exports. A workflow is covered when you can find the Sei path for it, run it with your library, and understand any Sei-specific behavior. | ||
|
|
||
| The matrix groups workflows like this: | ||
|
|
||
| - **Connect and configure:** chain definitions, transports, wallet discovery, wallet connection, and chain switching | ||
| - **Read chain state:** balances, blocks, transactions, receipts, contract reads, and logs | ||
| - **Write and simulate:** transfers, contract writes, deployment, simulation, and gas estimation | ||
| - **Signing:** messages, typed data, and transactions | ||
| - **Tokens:** ERC-20, ERC-721, and ERC-1155 | ||
| - **Sei extensions:** precompiles, pointer contracts, and address association | ||
|
|
||
| Each workflow gets one cell for viem, one for wagmi, and one for ethers. | ||
|
|
||
| ## How cells are scored | ||
|
|
||
| | Status | A cell has this status when | | ||
| | --- | --- | | ||
| | Planned | No docs page, template, or helper covers the workflow for this library. | | ||
| | Partial | A path exists, but the example, helper, or typing for this library is incomplete. | | ||
| | Covered | A maintained docs page or `@sei-js` template shows the workflow on Sei with this library. | | ||
| | Verified | An automated check, such as a test in sei-js CI, runs the workflow against Sei. | | ||
| | Network-limited | Sei intentionally differs from Ethereum, and [EVM compatibility](/evm/evm-parity/evm-compatibility) documents the difference. | | ||
| | Not core | The workflow is useful in some ecosystems, but it is not part of the core EVM workflows on Sei. | | ||
|
|
||
| The score is the number of Covered and Verified cells, divided by the number of all cells except Network-limited and Not core cells. Network-limited and Not core cells stay in the matrix so that you can see the boundary, but they do not lower the score. | ||
|
|
||
| A cell changes status only when its evidence changes: | ||
|
|
||
| - It moves up when the evidence lands, for example a merged docs page, a published template, or a passing test. | ||
| - It moves down when the evidence breaks, for example when an example stops working or a test is removed. | ||
|
|
||
| ## How reports are handled | ||
|
|
||
| To report a gap, open an issue with the [EVM compatibility template](https://github.com/sei-protocol/sei-js/issues/new?template=evm_compatibility.md). The template applies the `evm-compat` label. | ||
|
|
||
| Maintainers classify each report: | ||
|
|
||
| | Classification | Meaning | Outcome | | ||
| | --- | --- | --- | | ||
| | SDK gap | An `@sei-js` package, template, or docs page needs a change. | Maintainers fix it and update the matrix. | | ||
| | Network issue | The RPC response differs from documented Sei behavior. | Maintainers move the issue to [sei-chain](https://github.com/sei-protocol/sei-chain/issues). | | ||
| | Upstream issue | The behavior comes from viem, wagmi, ethers, or a wallet. | Maintainers link the upstream report and a workaround. | | ||
| | Docs issue | A docs page is wrong or missing. | Maintainers fix the docs. | | ||
| | Intentional divergence | Sei differs from Ethereum on purpose. | Maintainers make sure that [EVM compatibility](/evm/evm-parity/evm-compatibility) documents the difference, and mark the cell Network-limited. | | ||
|
|
||
| Maintainers classify a report within 2 days and assign an owner within 7 days. No report should stay open longer than 14 days. For the full triage and closure rules, see the [EVM compatibility SLA](https://github.com/sei-protocol/sei-js/blob/main/.github/EVM_COMPAT_SLA.md) in the sei-js repository. |
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,145 @@ | ||
| --- | ||
| title: 'EVM parity matrix' | ||
| sidebarTitle: 'EVM parity matrix' | ||
| description: 'Which EVM workflows are covered on Sei for viem, wagmi, and ethers, which gaps sei-js still has to close, and which differences come from the Sei network' | ||
| keywords: ['sei-js', 'evm parity', 'compatibility matrix', 'viem', 'wagmi', 'ethers', 'evm-compat'] | ||
| --- | ||
|
|
||
| This matrix scores common EVM developer workflows on Sei once for each of three JavaScript libraries: viem, wagmi, and ethers. Each cell shows whether a maintained docs page or `@sei-js` template covers the workflow with that library. When a cell is not covered, its status shows who owns the gap: sei-js or the Sei network. | ||
|
|
||
| <Info>This page covers library workflows. For how the Sei network differs from Ethereum, method by method, see [EVM compatibility](/evm/evm-parity/evm-compatibility). For the scoring rules and the issue process, see the [EVM parity plan](/evm/sei-js/evm-parity-plan).</Info> | ||
|
|
||
| ## Status legend | ||
|
|
||
| | Status | Meaning | Gap owner | | ||
| | --- | --- | --- | | ||
| | Verified | An automated check runs the workflow against Sei. | None | | ||
| | Covered | A maintained docs page or `@sei-js` template shows the workflow on Sei with this library. No automated check runs it yet. | None | | ||
| | Partial | A path exists, but the example, helper, or typing for this library is incomplete. | sei-js | | ||
| | Planned | No docs page, template, or helper covers the workflow for this library yet. | sei-js | | ||
| | Network-limited | Sei intentionally differs from Ethereum, so the workflow cannot behave as it does on Ethereum. | Sei network | | ||
| | Not core | The workflow is outside the core score. | None | | ||
|
|
||
| ## Current score | ||
|
|
||
| Covered and Verified cells count toward the score. Network-limited and Not core cells are left out of it. | ||
|
|
||
| | Library | Covered | Partial | Planned | Score | | ||
| | --- | --- | --- | --- | --- | | ||
| | viem | 21 | 2 | 1 | 21 of 24 | | ||
| | wagmi | 12 | 1 | 10 | 12 of 23 | | ||
| | ethers | 21 | 2 | 1 | 21 of 24 | | ||
| | **All libraries** | **54** | **5** | **12** | **54 of 71 (76%)** | | ||
|
|
||
| No workflow is Verified yet. The [EVM parity plan](/evm/sei-js/evm-parity-plan) sets the target at 95% of scored cells. Most of the remaining gaps are missing wagmi examples. For the full list, see [Gaps that sei-js owns](#gaps-that-sei-js-owns). | ||
|
|
||
| ## Connect and configure | ||
|
|
||
| | Workflow | viem | wagmi | ethers | Evidence | | ||
| | --- | --- | --- | --- | --- | | ||
| | Chain definitions and HTTP transport | Covered | Covered | Covered | [viem quickstart](/evm/evm-parity/examples/viem-quickstart), [wagmi and React](/evm/evm-parity/examples/wagmi-react), [ethers quickstart](/evm/evm-parity/examples/ethers-quickstart) | | ||
| | Wallet discovery (EIP-6963) | Partial | Covered | Partial | [Sei Global Wallet](/evm/sei-global-wallet) | | ||
| | Connect a wallet | Covered | Covered | Covered | [Building a frontend](/evm/building-a-frontend), [wagmi and React](/evm/evm-parity/examples/wagmi-react) | | ||
| | Switch or add a chain | Partial | Covered | Covered | [wagmi and React](/evm/evm-parity/examples/wagmi-react), [Building a frontend](/evm/building-a-frontend) | | ||
|
|
||
| `@sei-js/precompiles` re-exports the `sei` and `seiTestnet` chain definitions from `viem/chains` and adds `seiLocal` for a local node. The Sei Global Wallet guide shows wallet discovery through RainbowKit, ConnectKit, and wagmi with Dynamic, and with the raw EIP-6963 events. No page shows the viem `switchChain` and `addChain` actions. | ||
|
|
||
| ## Read chain state | ||
|
|
||
| | Workflow | viem | wagmi | ethers | Evidence | | ||
| | --- | --- | --- | --- | --- | | ||
| | Native SEI balance | Covered | Covered | Covered | [Read a balance](/evm/cookbook/read-a-balance), [wagmi and React](/evm/evm-parity/examples/wagmi-react) | | ||
| | Blocks and block tags | Covered | Covered | Covered | [Finality and block tags](/evm/evm-parity/finality), [wagmi and React](/evm/evm-parity/examples/wagmi-react) | | ||
| | Transactions and receipts | Covered | Covered | Covered | [Transaction lifecycle](/evm/evm-parity/examples/transaction-lifecycle), [wagmi and React](/evm/evm-parity/examples/wagmi-react) | | ||
| | Contract reads | Covered | Covered | Covered | [ERC-20 interaction](/evm/evm-parity/examples/erc20), [wagmi and React](/evm/evm-parity/examples/wagmi-react) | | ||
| | Batched reads (Multicall3) | Covered | Covered | Covered | [Multicall](/evm/evm-parity/examples/multicall) | | ||
| | Past logs and events | Covered | Planned | Partial | [Listen to events](/evm/cookbook/listen-to-events), [ERC-20 interaction](/evm/evm-parity/examples/erc20) | | ||
| | Live blocks and events over WebSocket | Covered | Planned | Covered | [WebSocket connections](/evm/evm-parity/websocket), [Listen to events](/evm/cookbook/listen-to-events) | | ||
|
|
||
| For ranges over 2,000 blocks, `getLogsInRange` and `streamLogsInRange` from `@sei-js/precompiles/viem` split the range into requests that the node accepts. ethers has no equivalent helper, so its cell for past logs is Partial. | ||
|
|
||
| ## Write and simulate | ||
|
|
||
| | Workflow | viem | wagmi | ethers | Evidence | | ||
| | --- | --- | --- | --- | --- | | ||
| | Send SEI | Covered | Covered | Covered | [Send SEI](/evm/cookbook/send-sei), [Scaffold Sei](/evm/sei-js/create-sei) | | ||
| | Contract writes | Covered | Covered | Covered | [ERC-20 interaction](/evm/evm-parity/examples/erc20), [wagmi and React](/evm/evm-parity/examples/wagmi-react) | | ||
| | Contract deployment | Covered | Planned | Covered | [Deploy and verify](/evm/evm-parity/examples/deploy-verify), [Deploy an ERC-20](/evm/cookbook/deploy-an-erc20) | | ||
| | Simulation, gas estimation, and reverts | Covered | Planned | Covered | [viem quickstart](/evm/evm-parity/examples/viem-quickstart), [ethers quickstart](/evm/evm-parity/examples/ethers-quickstart), [Error handling](/evm/evm-parity/examples/error-handling) | | ||
|
|
||
| The Scaffold Sei template sends SEI with the wagmi `useSendTransaction` hook. | ||
|
|
||
| ## Signing | ||
|
|
||
| | Workflow | viem | wagmi | ethers | Evidence | | ||
| | --- | --- | --- | --- | --- | | ||
| | Message signing (EIP-191) | Covered | Planned | Covered | [Signing](/evm/evm-parity/signing) | | ||
| | Typed-data signing (EIP-712) | Covered | Planned | Covered | [Signing](/evm/evm-parity/signing) | | ||
| | Transaction signing without sending | Planned | Not core | Planned | None | | ||
|
|
||
| No page shows how to sign a transaction in the client and then send it with `eth_sendRawTransaction`. The wagmi cell is Not core because wagmi has no hook for this, and most browser wallets do not support `eth_signTransaction`. | ||
|
|
||
| ## Tokens | ||
|
|
||
| | Workflow | viem | wagmi | ethers | Evidence | | ||
| | --- | --- | --- | --- | --- | | ||
| | ERC-20 | Covered | Covered | Covered | [ERC-20 interaction](/evm/evm-parity/examples/erc20), [wagmi and React](/evm/evm-parity/examples/wagmi-react) | | ||
| | ERC-721 | Covered | Planned | Covered | [ERC-721 interaction](/evm/evm-parity/examples/erc721) | | ||
| | ERC-1155 | Covered | Planned | Covered | [ERC-1155 interaction](/evm/evm-parity/examples/erc1155) | | ||
|
|
||
| ## Sei extensions | ||
|
|
||
| These workflows are specific to Sei, so standard libraries cannot cover them on their own. `@sei-js/precompiles` exports the ABIs and addresses that they need. | ||
|
|
||
| | Workflow | viem | wagmi | ethers | Evidence | | ||
| | --- | --- | --- | --- | --- | | ||
| | Sei precompiles | Covered | Partial | Covered | [Precompile example usage](/evm/precompiles/example-usage), [Scaffold Sei](/evm/sei-js/create-sei) | | ||
| | Pointer contracts | Covered | Planned | Covered | [Pointer contracts](/evm/evm-parity/examples/pointer-contracts) | | ||
| | Address association (`0x` and `sei1` addresses) | Covered | Planned | Covered | [Accounts](/learn/accounts) (viem), [Address precompile](/evm/precompiles/cosmwasm-precompiles/addr) (ethers) | | ||
|
|
||
| The Scaffold Sei `precompiles` extension reads the Bank precompile in a wagmi app, but no page shows a precompile write with wagmi. In sei-js CI, a test compares the exported ABIs with the precompile ABIs in `sei-chain` v6.6.1. | ||
|
|
||
| ## Gaps that sei-js owns | ||
|
|
||
| Each gap below is a Partial or Planned cell. When a gap is closed, its cell moves to Covered. | ||
|
|
||
| | Gap | Libraries | Next step | | ||
| | --- | --- | --- | | ||
| | Wallet discovery | viem, ethers | Show how to pass a provider found through EIP-6963 to viem `custom()` and to ethers `BrowserProvider`. | | ||
| | Switch or add a chain | viem | Show the viem `switchChain` and `addChain` actions with Sei Mainnet and Sei Testnet. | | ||
| | Past logs over long ranges | ethers | Add an ethers helper or recipe that splits long ranges, as `getLogsInRange` does for viem. | | ||
| | Past logs and live events | wagmi | Show `getLogsInRange`, `useWatchBlocks`, and `useWatchContractEvent` in a wagmi app. | | ||
| | Contract deployment | wagmi | Add a `useDeployContract` example. | | ||
| | Simulation and gas estimation | wagmi | Add `useSimulateContract` and `useEstimateGas` examples. | | ||
| | Message and typed-data signing | wagmi | Add `useSignMessage` and `useSignTypedData` examples. | | ||
| | Transaction signing without sending | viem, ethers | Show how to sign with a local account, then send with `eth_sendRawTransaction`. | | ||
| | Sei precompiles | wagmi | Add `useReadContract` and `useWriteContract` examples that use the `@sei-js/precompiles` ABIs. | | ||
| | ERC-721, ERC-1155, pointer contracts, and address association | wagmi | Add wagmi versions of these examples. | | ||
|
|
||
| ## Network differences | ||
|
|
||
| These differences come from the Sei network, not from sei-js. The workflows above still work, but they behave differently from Ethereum in the ways listed here. | ||
|
|
||
| | Affects | Sei behavior | Details | | ||
| | --- | --- | --- | | ||
| | Blocks and block tags | `latest`, `safe`, and `finalized` refer to the same block, because Sei has instant finality. | [Finality and block tags](/evm/evm-parity/finality) | | ||
| | Past logs and events | Public endpoints accept at most 2,000 blocks in one `eth_getLogs` request. A query that matches more than 10,000 logs fails instead of returning partial results. | [EVM compatibility](/evm/evm-parity/evm-compatibility#logs-filters-and-subscriptions) | | ||
| | Live blocks and events | Sei supports only the `newHeads` and `logs` subscriptions. The public WebSocket endpoints do not serve `eth_getLogs`. | [WebSocket connections](/evm/evm-parity/websocket) | | ||
| | Simulation and gas estimation | Governance sets the minimum gas price and can change the SSTORE cost. Sei does not burn the base fee. | [Gas and fees](/evm/evm-parity/gas-and-fees) | | ||
| | Message and typed-data signing | The wallet signs, so support depends on the connected wallet. | [Signing](/evm/evm-parity/signing) | | ||
| | Transaction signing | `eth_signTransaction` needs a key that the node holds, so it fails on public RPC endpoints. Sign in the client instead. | [JSON-RPC reference](/evm/reference) | | ||
|
|
||
| ### Workflows outside the score | ||
|
|
||
| These workflows have the same status for viem, wagmi, and ethers. | ||
|
|
||
| | Workflow | Status | Details | | ||
| | --- | --- | --- | | ||
| | Storage proofs (`eth_getProof`) | Network-limited | Not supported since v6.7.0. Every call returns JSON-RPC error `-32000`. [See Proof verification.](/evm/evm-parity/evm-compatibility#proof-verification) | | ||
| | Blob transactions (EIP-4844) | Network-limited | Sei runs Pectra without blob transactions. [See Transaction types.](/evm/evm-parity/transaction-types) | | ||
| | Pending transactions and the pending block | Network-limited | The `pending` block tag returns the latest block. Sei does not support pending-transaction filters or subscriptions. [See Pending state.](/evm/evm-parity/evm-compatibility#pending-state) | | ||
|
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. [nit] Slightly over-broad: the linked Pending state section says |
||
| | ENS names | Not core | Sei does not run Ethereum Mainnet ENS. [See Name services.](/evm/evm-parity/evm-compatibility#name-services) | | ||
|
|
||
| ## Report a gap | ||
|
|
||
| If a workflow behaves differently on Sei than this page says, or a workflow that you need is missing, open an issue with the [EVM compatibility template](https://github.com/sei-protocol/sei-js/issues/new?template=evm_compatibility.md). Maintainers classify each report, and no report should stay open longer than 14 days. For how reports are classified, see [How reports are handled](/evm/sei-js/evm-parity-plan#how-reports-are-handled). | ||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
[nit] The pinned
sei-chainv6.6.1 will go stale as soon as the CI test is bumped. Consider linking to the test or workflow in sei-js instead of hard-coding the version, in line with the AGENTS.md guidance against hard-coding values that change.