Skip to content

Commit 71fab4e

Browse files
monty-seimonty-sei
committed
Add EVM parity planning docs
1 parent bc17ace commit 71fab4e

6 files changed

Lines changed: 332 additions & 0 deletions

File tree

‎docs/docs.json‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -81,6 +81,17 @@
8181
}
8282
]
8383
},
84+
{
85+
"dropdown": "EVM Parity",
86+
"description": "Compatibility matrix and execution plan",
87+
"icon": "check-double",
88+
"pages": [
89+
{
90+
"group": "Program",
91+
"pages": ["evm-parity/plan", "evm-parity/matrix", "evm-parity/rpc-conformance", "evm-parity/issue-sla"]
92+
}
93+
]
94+
},
8495
{
8596
"dropdown": "@sei-js/sei-global-wallet",
8697
"description": "User friendly wallet connect",

‎docs/evm-parity/issue-sla.mdx‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
---
2+
title: 'Issue SLA'
3+
description: 'Compatibility issue triage and aging rules for EVM parity work'
4+
icon: 'stopwatch'
5+
---
6+
7+
# Issue SLA
8+
9+
The operational target is simple: no open GitHub issue tagged `evm-compat` should be older than 14 days.
10+
11+
## Label
12+
13+
Use `evm-compat` for reports where a developer expected standard EVM behavior through viem, wagmi, ethers, wallet connectors, JSON-RPC, or common ERC/token flows.
14+
15+
## Required Triage Fields
16+
17+
Each issue should include:
18+
19+
- Library or tool: viem, wagmi, ethers, wallet connector, RPC, template, docs, or other
20+
- Network: mainnet, testnet, devnet, local, or unknown
21+
- Expected EVM behavior
22+
- Observed Sei behavior
23+
- Minimal reproduction
24+
- Error output or transaction hash when available
25+
- Classification: SDK gap, network issue, upstream issue, docs issue, or intentional divergence
26+
27+
## Aging Rules
28+
29+
| Age | Required action |
30+
| --- | --- |
31+
| 0-2 days | Confirm scope, request missing reproduction details, and add classification. |
32+
| 3-7 days | Assign owner and link to a matrix row or create one. |
33+
| 8-13 days | Post status, define next action, and split network/upstream work if needed. |
34+
| 14 days | Escalate until the issue is closed, transferred, or converted into tracked implementation work. |
35+
36+
## Closure Rules
37+
38+
Close an `evm-compat` issue when one of these is true:
39+
40+
- A fix has landed and a release path is identified.
41+
- The behavior is documented as an intentional Sei divergence.
42+
- The issue belongs to network infrastructure and has been transferred to the right tracker.
43+
- The issue belongs upstream and a linked upstream report or workaround exists.
44+
- The reporter cannot provide enough detail to reproduce after follow-up.
45+
46+
## Weekly Review
47+
48+
Run a weekly review with:
49+
50+
- Count of open `evm-compat` issues.
51+
- Count older than 14 days.
52+
- New matrix rows added from reports.
53+
- SDK, docs, network, and upstream classifications.
54+
- Release notes needed for resolved issues.

‎docs/evm-parity/matrix.json‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
{
2+
"targetCoverage": 0.95,
3+
"scoreStartsWhen": "conformance-tests-land",
4+
"statusLegend": {
5+
"verified": "Covered by docs or code and ready for conformance tests.",
6+
"covered": "Supported through standard tooling or existing sei-js helpers, but not yet backed by a dedicated parity test.",
7+
"partial": "A path exists, but examples, helpers, typing, or tests are incomplete.",
8+
"planned": "Needed for the target and not yet represented clearly.",
9+
"not-core": "Useful in some ecosystems, but excluded from the core parity score.",
10+
"network-limited": "The SDK can expose the behavior, but the chain intentionally differs from Ethereum."
11+
},
12+
"rows": [
13+
{
14+
"capability": "Chain metadata and HTTP transport",
15+
"status": "covered",
16+
"scoreScope": "core",
17+
"nextGap": "Centralize mainnet, testnet, devnet, and local chain exports from one sei-js surface."
18+
},
19+
{
20+
"capability": "WebSocket subscriptions and watchers",
21+
"status": "partial",
22+
"scoreScope": "core",
23+
"nextGap": "Add subscription examples and conformance checks for block, log, and pending transaction watchers."
24+
},
25+
{
26+
"capability": "Wallet discovery",
27+
"status": "covered",
28+
"scoreScope": "core",
29+
"nextGap": "Add browser-level compatibility checks with common connector libraries."
30+
},
31+
{
32+
"capability": "Switch and add chain",
33+
"status": "partial",
34+
"scoreScope": "core",
35+
"nextGap": "Add explicit Sei mainnet, testnet, devnet payload examples and error handling notes."
36+
},
37+
{
38+
"capability": "Contract deploy",
39+
"status": "partial",
40+
"scoreScope": "core",
41+
"nextGap": "Add template and docs coverage for deploy, receipt, and verification next steps."
42+
},
43+
{
44+
"capability": "Message signing",
45+
"status": "planned",
46+
"scoreScope": "core",
47+
"nextGap": "Add examples and wallet compatibility checks."
48+
},
49+
{
50+
"capability": "Typed-data signing",
51+
"status": "planned",
52+
"scoreScope": "core",
53+
"nextGap": "Add EIP-712 examples and conformance fixtures."
54+
},
55+
{
56+
"capability": "Blob transactions",
57+
"status": "network-limited",
58+
"scoreScope": "excluded",
59+
"nextGap": "Document unsupported status and exclude from core score."
60+
},
61+
{
62+
"capability": "ENS",
63+
"status": "not-core",
64+
"scoreScope": "excluded",
65+
"nextGap": "Keep outside score unless Sei adopts a first-party name-service path."
66+
}
67+
]
68+
}

‎docs/evm-parity/matrix.mdx‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
---
2+
title: 'Parity Matrix'
3+
description: 'Baseline EVM feature coverage matrix for sei-js against viem, wagmi, and ethers'
4+
icon: 'table'
5+
---
6+
7+
# Parity Matrix
8+
9+
This matrix tracks EVM developer workflows rather than package export counts. A workflow is complete when a developer can find the intended Sei path, run it through standard tooling, and understand any network-specific behavior.
10+
11+
## Status Legend
12+
13+
| Status | Meaning |
14+
| --- | --- |
15+
| Verified | Covered by docs or code and ready for conformance tests. |
16+
| Covered | Supported through standard tooling or existing `sei-js` helpers, but not yet backed by a dedicated parity test. |
17+
| Partial | A path exists, but examples, helpers, typing, or tests are incomplete. |
18+
| Planned | Needed for the >=95% target and not yet represented clearly. |
19+
| Not core | Useful in some ecosystems, but excluded from the core parity score. |
20+
| Network-limited | The SDK can expose the behavior, but the chain intentionally differs from Ethereum. |
21+
22+
## Core Feature Matrix
23+
24+
| Capability | viem | wagmi | ethers | Current `sei-js` status | Evidence | Next gap |
25+
| --- | --- | --- | --- | --- | --- | --- |
26+
| Chain metadata and HTTP transport | Public client + chains | `createConfig` transports | JSON-RPC provider | Covered | `viem/chains` is used in `mcp-server` and templates; `@sei-js/precompiles` exports `seiLocal` | Centralize mainnet, testnet, devnet, and local chain exports from one `sei-js` surface. |
27+
| WebSocket subscriptions and watchers | WebSocket transport + watch actions | watch hooks | provider event APIs | Partial | Registry includes `evm_ws` endpoint shape | Add subscription examples and conformance checks for block, log, and pending transaction watchers. |
28+
| Wallet discovery | Custom EIP-1193 transport | connectors | `BrowserProvider` | Covered | `@sei-js/sei-global-wallet/eip6963` registers discovery | Add browser-level compatibility checks with common connector libraries. |
29+
| Connect and disconnect | Wallet client actions | `useConnect`, `useDisconnect` | provider request flow | Covered | Sei Global Wallet docs cover RainbowKit, ConnectKit, Web3-React, and wagmi + Dynamic | Add a single comparison page that maps connector behavior across libraries. |
30+
| Switch and add chain | `switchChain`, `addChain` | `useSwitchChain` | EIP-1193 requests | Partial | Existing docs use wagmi chain config | Add explicit Sei mainnet, testnet, devnet payload examples and error handling notes. |
31+
| Native SEI balance | `getBalance` | `useBalance` | `provider.getBalance` | Covered | `mcp-server` exposes `getBalance`; templates use wagmi public client | Add matrix-linked examples for all three libraries. |
32+
| Blocks | `getBlock`, `getBlockNumber` | `useBlock`, `useBlockNumber` | provider block APIs | Covered | `mcp-server` exposes block helpers | Add tests that assert Sei finality tag behavior. |
33+
| Transactions and receipts | transaction actions | transaction hooks | provider transaction APIs | Covered | `mcp-server` exposes transaction helpers | Add library-level smoke tests for submitted and historical transactions. |
34+
| Logs and events | `getLogs`, `watchEvent` | event hooks | filters and listeners | Partial | `mcp-server` exposes `getLogs` | Add examples for ERC events and precompile event reads. |
35+
| Contract reads | `readContract` | `useReadContract` | contract view calls | Covered | `@sei-js/precompiles` exports viem ABIs and ethers factories | Add parity tests for one ERC and one precompile read. |
36+
| Contract writes | `writeContract` | `useWriteContract` | signer contract calls | Covered | `mcp-server` exposes write helpers; precompile docs show viem simulation patterns | Add complete write examples for viem, wagmi, and ethers. |
37+
| Contract deploy | `deployContract` | `useDeployContract` | `ContractFactory` | Partial | `mcp-server` exposes `deployContract` | Add template and docs coverage for deploy + receipt + verification next steps. |
38+
| Simulation and gas estimate | `simulateContract`, `estimateGas` | `useSimulateContract`, `useEstimateGas` | `estimateGas`, static calls | Partial | Precompile docs show `simulateContract`; `mcp-server` exposes `estimateGas` | Add examples for reverted calls, gas buffers, and Sei gas-limit guidance. |
39+
| Message signing | `signMessage` | `useSignMessage` | signer message APIs | Planned | Standard library support exists | Add examples and wallet compatibility checks. |
40+
| Typed-data signing | `signTypedData` | `useSignTypedData` | signer typed-data APIs | Planned | Standard library support exists | Add EIP-712 examples and conformance fixtures. |
41+
| Transaction signing | `signTransaction` | `useSignTransaction` | signer transaction APIs | Planned | Standard library support exists | Add coverage for supported transaction types and legacy gas guidance. |
42+
| ERC-20 reads and transfers | ERC ABI + actions | read/write hooks | contract calls | Partial | `mcp-server` includes ERC-20 balance, transfer, and approve helpers | Add reusable examples and tests against a fixture contract. |
43+
| ERC-721 reads and transfers | ERC ABI + actions | read/write hooks | contract calls | Partial | `mcp-server` includes ERC-721 balance, ownership, and transfer helpers | Add metadata and event examples. |
44+
| ERC-1155 reads and transfers | ERC ABI + actions | read/write hooks | contract calls | Partial | `mcp-server` includes ERC-1155 balance and transfer helpers | Add batch transfer and event examples. |
45+
| Sei precompiles | Contract actions | contract hooks | contract factories | Covered | `@sei-js/precompiles` exports viem ABIs and ethers v6 factories | Add generated docs coverage table for every precompile ABI and method. |
46+
| Pointer and address helper flows | Custom RPC + precompiles | custom hook wrapper | provider send + contracts | Partial | Precompile docs cover pointer and address workflows | Add high-level helpers only where they reduce repeated integration code. |
47+
| `eth_getProof` | Public action/custom request | `useProof` | provider send | Network-limited | Sei returns IAVL proof data rather than Ethereum MPT proof data | Add warning in matrix and conformance tests that assert documented shape. |
48+
| Blob transactions | Blob transaction actions | fee/blob hooks | transaction request fields | Network-limited | Sei runs Pectra without blob transactions | Exclude from core score and document unsupported status. |
49+
| ENS | ENS actions | ENS hooks | name resolver | Not core | Sei does not provide Ethereum mainnet ENS behavior | Keep outside score; link to app-specific name service guidance if needed. |
50+
51+
## Scoring Rule
52+
53+
The public coverage score will start once conformance tests land. Only core rows count toward the >=95% target. `Not core` and `Network-limited` rows remain visible so developers understand the boundary, but they do not lower the SDK score when the behavior is intentional and documented.
54+
55+
## Source Data
56+
57+
The editable matrix source is stored at `/docs/evm-parity/matrix.json`.

‎docs/evm-parity/plan.mdx‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
---
2+
title: 'EVM Standard Parity Plan'
3+
description: 'Work plan for bringing sei-js EVM workflows to industry-standard compatibility'
4+
icon: 'check-double'
5+
---
6+
7+
# EVM Standard Parity Plan
8+
9+
This work raises `sei-js` to the level developers expect when they arrive with viem, wagmi, ethers, and modern EVM assumptions.
10+
11+
## Success Criteria
12+
13+
- Publish a parity matrix against viem, wagmi, and ethers with >=95% core feature coverage.
14+
- Keep zero open GitHub issues tagged `evm-compat` older than 14 days.
15+
- Separate SDK gaps from Sei network behavior so product decisions are explicit and easy to track.
16+
17+
## Operating Principles
18+
19+
- **Standard tooling first:** Sei should work through viem, wagmi, ethers, Foundry, Hardhat, and wallet standards without custom ceremony.
20+
- **Sei extensions second:** `@sei-js` should fill Sei-specific gaps through chain metadata, wallet discovery, precompile helpers, templates, and clear docs.
21+
- **Runnable evidence over claims:** Matrix rows should link to docs, examples, tests, or conformance checks.
22+
- **Network behavior is documented:** Known Sei differences should be tested and explained instead of hidden behind SDK wrappers.
23+
24+
## Feature Groups
25+
26+
The matrix scores practical developer workflows:
27+
28+
- Chain metadata and transports
29+
- Wallet discovery, connect, disconnect, switch, and add-chain flows
30+
- Account, balance, block, transaction, receipt, and log reads
31+
- Contract read, write, deploy, simulate, estimate gas, and event flows
32+
- Native SEI, ERC-20, ERC-721, and ERC-1155 token flows
33+
- Message, typed-data, and transaction signing
34+
- WebSocket subscriptions and watcher flows
35+
- Sei precompiles, pointer contracts, and address helper flows
36+
- Templates, examples, and migration documentation
37+
38+
## Phases
39+
40+
### Phase 1: Baseline Matrix
41+
42+
- Inventory current `sei-js` packages, templates, and docs.
43+
- Classify each capability as verified, covered, partial, planned, not core, or network-limited.
44+
- Publish the first matrix in docs.
45+
46+
### Phase 2: Conformance Harness
47+
48+
- Add repeatable checks for standard Ethereum JSON-RPC families on Sei mainnet, testnet, devnet, and local networks.
49+
- Run viem and ethers smoke tests for core flows.
50+
- Add browser-oriented wallet checks where the dependency can be mocked reliably.
51+
52+
### Phase 3: SDK Improvements
53+
54+
- Fill gaps with focused helpers only where standard libraries do not already solve the workflow.
55+
- Strengthen templates for common EVM flows: read, write, deploy, logs, signing, and precompiles.
56+
- Expand docs for Sei-specific differences that affect app behavior.
57+
58+
### Phase 4: Maintenance SLA
59+
60+
- Label compatibility issues with `evm-compat`.
61+
- Triage new reports into SDK, docs, network, or upstream-tool categories.
62+
- Review the aging queue weekly until no `evm-compat` issue exceeds 14 days.
63+
64+
## Initial Focus
65+
66+
1. Make the parity matrix public and source-backed.
67+
2. Build a conformance checklist around Sei's supported `eth_*` and `debug_*` methods.
68+
3. Prioritize gaps that create "Sei is weird" friction during the first hour of integration.
69+
70+
## References
71+
72+
- [Sei RPC Reference](https://docs.sei.io/evm/reference)
73+
- [Sei EVM Differences](https://docs.sei.io/evm/differences-with-ethereum)
74+
- [viem Clients](https://viem.sh/docs/clients/intro)
75+
- [wagmi Getting Started](https://wagmi.sh/react/getting-started)
76+
- [ethers v6 Getting Started](https://docs.ethers.org/v6/getting-started/)
77+
- [Solana JavaScript SDKs](https://solana.com/docs/clients/official/javascript)

‎docs/evm-parity/rpc-conformance.mdx‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
---
2+
title: 'RPC Conformance'
3+
description: 'Conformance checklist for Sei EVM JSON-RPC behavior used by SDK parity tests'
4+
icon: 'network-wired'
5+
---
6+
7+
# RPC Conformance
8+
9+
The SDK parity target depends on the Sei network supporting standard Ethereum JSON-RPC behavior where EVM tooling expects it. This checklist separates network checks from package-level helpers.
10+
11+
## Method Families
12+
13+
| Family | Representative methods | SDK workflows | Conformance expectation |
14+
| --- | --- | --- | --- |
15+
| Send transactions | `eth_sendRawTransaction` | viem `sendRawTransaction`, ethers provider send | Signed transaction returns a transaction hash or a standard JSON-RPC error. |
16+
| Transaction lookup | `eth_getTransactionByHash`, `eth_getTransactionReceipt`, block index lookups | transaction views, receipt polling, wait helpers | Hash and receipt shapes are compatible with standard EVM tooling. |
17+
| Account information | `eth_getBalance`, `eth_getTransactionCount`, `eth_getCode`, `eth_getStorageAt`, `eth_getProof` | balances, nonces, bytecode checks, storage reads | Standard methods work; `eth_getProof` documents Sei's IAVL proof shape. |
18+
| Block information | `eth_getBlockByNumber`, `eth_getBlockByHash`, block transaction count, block receipts | block explorers, dashboards, polling | `latest`, `safe`, and `finalized` behavior follows Sei instant finality guidance. |
19+
| Chain information | `eth_blockNumber`, `eth_chainId`, `eth_feeHistory`, `eth_gasPrice`, `net_version`, `web3_clientVersion` | chain setup, gas estimates, status checks | Responses are compatible with viem, wagmi, and ethers expectations. |
20+
| Filters and logs | `eth_newFilter`, `eth_getFilterChanges`, `eth_getFilterLogs`, `eth_getLogs`, `eth_uninstallFilter` | event reads and watchers | Filter lifecycle and logs support standard event workflows. |
21+
| Simulation and debugging | `eth_estimateGas`, `eth_call`, `debug_traceTransaction`, block tracing | preflight checks, error decoding, debugging | Calls and traces work for supported transaction types and documented limits. |
22+
| Sei helpers | `sei_associate`, `sei_getSeiAddress`, `sei_getEVMAddress`, `sei_getCosmosTx` | address association and cross-VM lookups | Treated as legacy/custom helpers and kept outside the core EVM score. |
23+
24+
## Sei-Specific Assertions
25+
26+
| Behavior | Assertion |
27+
| --- | --- |
28+
| Instant finality | `latest`, `safe`, and `finalized` should not imply different commitment levels on Sei. |
29+
| Pending state | Tests should not require Ethereum-style pending state visibility. |
30+
| Proof format | `eth_getProof` returns IAVL proof data, not an Ethereum Merkle Patricia Trie proof. |
31+
| Blob transactions | Blob transaction paths are excluded because Sei runs Pectra without blob transactions. |
32+
| Legacy gas | Legacy transactions must follow Sei's documented minimum gas-price guidance. |
33+
| Fee handling | Fee UX should not assume base-fee burning. |
34+
| Storage cost | SSTORE cost is governance-adjustable and should not be hard-coded in SDK examples. |
35+
| Deprecated custom RPC | `sei_*` and `sei2_*` helpers are documented as legacy/custom behavior, not core EVM parity. |
36+
37+
## Test Harness Shape
38+
39+
The conformance harness should run the same scenarios through standard library surfaces:
40+
41+
1. viem public and wallet clients
42+
2. ethers v6 provider and signer
43+
3. wagmi core actions or React-compatible hook wrappers where browser state is required
44+
45+
Each check should classify failures as:
46+
47+
| Classification | Meaning |
48+
| --- | --- |
49+
| SDK gap | `sei-js` needs code, docs, or template changes. |
50+
| Network issue | The RPC result differs from documented Sei behavior or standard EVM expectations. |
51+
| Upstream issue | The dependency behavior is outside `sei-js` control and needs a workaround or upstream report. |
52+
| Intentional divergence | The behavior is documented and excluded from the core coverage score. |
53+
54+
## Initial Check List
55+
56+
- Fetch chain ID and latest block.
57+
- Read native SEI balance for a known address.
58+
- Read code and storage for a deployed fixture contract.
59+
- Estimate gas and simulate a read/write call.
60+
- Send a funded test transaction on testnet or local network.
61+
- Wait for transaction receipt and inspect logs.
62+
- Read ERC-20, ERC-721, and ERC-1155 fixture state.
63+
- Read and write one representative Sei precompile flow.
64+
- Verify finality tag behavior.
65+
- Verify documented `eth_getProof` shape.

0 commit comments

Comments
 (0)