Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion docs.json
Original file line number Diff line number Diff line change
Expand Up @@ -215,7 +215,9 @@
"evm/sei-js/index",
"evm/sei-js/create-sei",
"evm/templates",
"evm/sei-js/registry"
"evm/sei-js/registry",
"evm/sei-js/evm-parity",
"evm/sei-js/evm-parity-plan"
]
},
{
Expand Down
2 changes: 2 additions & 0 deletions evm/evm-parity/evm-compatibility.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,8 @@ This page documents EVM feature support on Sei. Each row shows whether a feature

Standard EVM tools (viem, wagmi, ethers, Foundry, and Hardhat) work on Sei for all rows marked **Supported**. Where Sei differs from Ethereum, the notes describe the difference so that you can account for it in your application.

For which viem, wagmi, and ethers workflows these docs and `@sei-js` cover, see the [EVM parity matrix](/evm/sei-js/evm-parity).

## Status legend

| Status | Meaning |
Expand Down
70 changes: 70 additions & 0 deletions evm/sei-js/evm-parity-plan.mdx
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.
145 changes: 145 additions & 0 deletions evm/sei-js/evm-parity.mdx
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.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[nit] The pinned sei-chain v6.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.


## 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) |

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[nit] Slightly over-broad: the linked Pending state section says eth_getTransactionCount(address, "pending") does count the sender's mempool transactions. Only eth_getBlockByNumber("pending") returns the latest block. Consider saying "The pending block returns the latest committed block" so readers don't assume pending nonces are unsupported.

| 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).
3 changes: 3 additions & 0 deletions evm/sei-js/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,8 @@
- Sei Mainnet and Sei Testnet chain definitions from viem, re-exported for convenience, plus a `seiLocal` definition for local nodes
- Packages that work with standard EVM libraries

To see which viem, wagmi, and ethers workflows are covered on Sei and which gaps remain, see the [EVM parity matrix](/evm/sei-js/evm-parity).

## Packages

### [@sei-js/precompiles](/evm/precompiles)
Expand All @@ -40,7 +42,7 @@
npx @sei-js/create-sei app
```

### [@sei-js/sei-global-wallet](/evm/sei-global-wallet)

Check warning on line 45 in evm/sei-js/index.mdx

View check run for this annotation

Mintlify / Mintlify Validation (seilabs) - vale-spellcheck

evm/sei-js/index.mdx#L45

Use sentence case for headings: '@sei-js/sei-global-wallet'.

Add the EIP-6963-compatible Sei Global Wallet to a dApp.

Expand Down Expand Up @@ -145,3 +147,4 @@

- [Discord](https://discord.gg/sei): Join the Sei developer community
- [GitHub Issues](https://github.com/sei-protocol/sei-js/issues): Report bugs and request features
- [EVM compatibility report](https://github.com/sei-protocol/sei-js/issues/new?template=evm_compatibility.md): Report EVM behavior on Sei that differs from what your library leads you to expect
Loading