diff --git a/ai/agentic-wallets.mdx b/ai/agentic-wallets.mdx index 96afce8..81649be 100644 --- a/ai/agentic-wallets.mdx +++ b/ai/agentic-wallets.mdx @@ -3,21 +3,21 @@ title: 'Agentic Wallets' description: 'Build AI agents with secure, programmable wallets on Sei using Coinbase AgentKit or Privy server wallets. Includes setup guides, policy engines, and a full feature comparison.' keywords: ['agentic wallets', 'ai agents', 'coinbase agentkit', 'privy', 'server wallets', 'sei ai', 'agent wallet', 'cdp wallet', 'wallet policy engine'] --- -Agentic wallets give AI agents the ability to hold funds, sign transactions, and interact with smart contracts autonomously — without exposing private keys to the agent or the LLM. This page covers the two leading solutions that work on Sei today: **Coinbase AgentKit** and **Privy server wallets**. +Agentic wallets let AI agents hold funds, sign transactions, and interact with smart contracts autonomously. They do this without exposing private keys to the agent or the LLM. This page covers the two leading solutions that work on Sei today: Coinbase AgentKit and Privy server wallets. -Both platforms support Sei as an EVM-compatible chain. No special integration is required — you point the wallet provider at Sei's RPC and chain ID and everything works out of the box. +Both platforms support Sei as an EVM-compatible chain. You do not need a special integration. Point the wallet provider at Sei's RPC and chain ID, and everything works with no other setup. -## How It Works +## How it works An agentic wallet sits between your AI agent and the blockchain: -1. **Agent decides** — The LLM reasons about what onchain action to take (e.g. "send 5 USDC to 0x..."). -2. **SDK prepares** — The wallet SDK constructs and validates the transaction. -3. **Policy check** — The policy engine evaluates the transaction against spending limits, allowlists, and other guardrails. -4. **TEE signs** — The private key, isolated in a Trusted Execution Environment, signs the transaction. The key is never exposed to the agent. -5. **Broadcast** — The signed transaction is submitted to Sei's EVM RPC. +1. **Agent decides**: The LLM reasons about what onchain action to take (for example, "send 5 USDC to 0x..."). +2. **SDK prepares**: The wallet SDK builds and validates the transaction. +3. **Policy check**: The policy engine evaluates the transaction against spending limits, allowlists, and other guardrails. +4. **TEE signs**: The private key is isolated in a Trusted Execution Environment (TEE) and signs the transaction there. The key is never exposed to the agent. +5. **Broadcast**: The signed transaction is submitted to Sei's EVM RPC. ``` ┌─────────┐ ┌───────────┐ ┌──────────────┐ ┌─────────┐ ┌──────────┐ @@ -26,41 +26,41 @@ An agentic wallet sits between your AI agent and the blockchain: └─────────┘ └───────────┘ └──────────────┘ └─────────┘ └──────────┘ ``` -## Quick Comparison +## Quick comparison -| Dimension | Coinbase AgentKit | Privy Server Wallets | +| Dimension | Coinbase AgentKit | Privy server wallets | | --- | --- | --- | -| **Type** | Open-source SDK + wallet infra | Wallet-as-a-service API | -| **Key isolation** | Self-custodial on Sei (bring-your-own key via Viem). CDP's TEE-managed signer does not support Sei. | TEE + Shamir secret sharing | -| **Sei support** | Via `ViemWalletProvider` (TS) or `EthAccountWalletProvider` (Python) | Via CAIP-2 `eip155:1329` | +| **Type** | Open-source SDK + wallet infrastructure | Wallet-as-a-service API | +| **Key isolation** | Self-custodial on Sei (bring-your-own key with Viem). CDP's TEE-managed signer does not support Sei. | TEE + Shamir secret sharing | +| **Sei support** | With `ViemWalletProvider` (TS) or `EthAccountWalletProvider` (Python) | With CAIP-2 `eip155:1329` | | **Policy engine** | Spending limits, address/contract allowlists, network restrictions | All of the above + time-based controls, key quorums | -| **Built-in actions** | 40+ action providers (wallet, ERC-20, ERC-721, Pyth on Sei; many others Base/Ethereum-only) | Wallet operations only (create, sign, send) | +| **Built-in actions** | 40+ action providers. Wallet, ERC-20, ERC-721, and Pyth work on Sei. Many others are Base/Ethereum-only. | Wallet operations only (create, sign, send) | | **AI frameworks** | LangChain, Vercel AI SDK, OpenAI Agents SDK, MCP | LangChain (`langchain-privy`) | | **Server SDKs** | TypeScript, Python | TypeScript, Python, Java, Rust, Go + REST API | -| **Open source** | Yes (MIT) | Partial (`langchain-privy` is OSS) | -| **Pricing** | Free SDK; CDP wallets $0.005/op (5K free/mo) | Free 50K sigs/mo; paid tiers from $299/mo | +| **Open source** | Yes (MIT) | Partial (`langchain-privy` is open source) | +| **Pricing** | Free SDK. CDP wallets $0.005/op (5K free/mo). | Free 50K sigs/mo. Paid tiers from $299/mo. | -**Use both together:** AgentKit ships with a built-in `PrivyWalletProvider`, so you can combine Privy's policy engine with AgentKit's 40+ action providers. +You can also use both together. AgentKit includes a built-in `PrivyWalletProvider`, so you can combine Privy's policy engine with AgentKit's 40+ action providers. --- ## Coinbase AgentKit on Sei -[AgentKit](https://github.com/coinbase/agentkit) is Coinbase's open-source toolkit for giving AI agents crypto wallets and onchain capabilities. It is framework-agnostic (LangChain, Vercel AI SDK, OpenAI Agents SDK, MCP) and wallet-agnostic (CDP wallets, Privy, Viem, and more). +[AgentKit](https://github.com/coinbase/agentkit) is Coinbase's open-source toolkit that gives AI agents crypto wallets and onchain capabilities. It is framework-agnostic (LangChain, Vercel AI SDK, OpenAI Agents SDK, MCP) and wallet-agnostic (CDP wallets, Privy, Viem, and others). ### Architecture AgentKit is organized around three concepts: -- **Wallet Providers** — Abstraction over different wallet implementations. For Sei, use `ViemWalletProvider` (TypeScript) or `EthAccountWalletProvider` (Python). -- **Action Providers** — Units of onchain functionality (ERC-20 transfers, ERC-721 ops, Pyth price feeds, etc.). Generic EVM providers work on Sei; providers with hard-coded chain allowlists (e.g. `x402ActionProvider`, `wethActionProvider`, CDP-managed ones) do not — see the support matrix below. -- **Framework Extensions** — Adapters that turn AgentKit actions into tools for your AI framework of choice. +- **Wallet providers**: An abstraction over different wallet implementations. For Sei, use `ViemWalletProvider` (TypeScript) or `EthAccountWalletProvider` (Python). +- **Action providers**: Units of onchain functionality, such as ERC-20 transfers, ERC-721 operations, and Pyth price feeds. Generic EVM providers work on Sei, but providers with hard-coded chain allowlists do not. These include `x402ActionProvider`, `wethActionProvider`, and CDP-managed providers. See the support matrix below. +- **Framework extensions**: Adapters that turn AgentKit actions into tools for your AI framework. ### Prerequisites - Node.js v22+ (TypeScript) or Python 3.10+ -- A [CDP Secret API Key](https://portal.cdp.coinbase.com/) (for CDP wallet providers; not required for Viem) +- A [CDP Secret API Key](https://portal.cdp.coinbase.com/) (for CDP wallet providers, not required for Viem) - A funded wallet on Sei ### Setup @@ -77,7 +77,7 @@ npm install @coinbase/agentkit @coinbase/agentkit-langchain viem -Viem ships with `sei` (id `1329`) and `seiTestnet` (id `1328`) out of the box, so you can import them directly from `viem/chains`. +Viem includes `sei` (chain ID `1329`) and `seiTestnet` (chain ID `1328`), so you can import them directly from `viem/chains`. ```typescript import { AgentKit, ViemWalletProvider, walletActionProvider, erc20ActionProvider } from '@coinbase/agentkit'; @@ -192,50 +192,50 @@ result = agent.invoke({ -### Available Action Providers on Sei +### Available action providers on Sei -Not every AgentKit action provider works on Sei — some are chain-specific. Here's what you can use: +Not every AgentKit action provider works on Sei, because some are chain-specific. This table shows which providers you can use: -| Action Provider | Works on Sei | Notes | +| Action provider | Works on Sei | Notes | | --- | --- | --- | | `walletActionProvider` | Yes | Balance, transfers, native SEI operations | -| `erc20ActionProvider` | Yes | Any ERC-20 token (USDC, WSEI, etc.) | +| `erc20ActionProvider` | Yes | Any ERC-20 token, such as USDC or WSEI | | `erc721ActionProvider` | Yes | NFT minting, transfers | -| `pythActionProvider` | Yes | Pyth price feeds via Hermes (off-chain, chain-agnostic) | -| `wethActionProvider` | No | Hard-coded WETH addresses; no WSEI entry. Use `erc20ActionProvider` against Sei's WSEI contract instead. | -| `x402ActionProvider` | No | Provider's `SUPPORTED_NETWORKS` allowlist is limited to `base-mainnet`, `base-sepolia`, `solana-mainnet`, and `solana-devnet`. The x402 protocol itself is chain-agnostic — write a custom action provider or call the facilitator directly if you need x402 on Sei. | -| `cdpApiActionProvider` | No | Requires a Coinbase `networkId`; Sei isn't in AgentKit's chain map. | -| `morphoActionProvider` | No | Morpho contracts not deployed on Sei | -| `moonwellActionProvider` | No | Moonwell contracts not deployed on Sei | +| `pythActionProvider` | Yes | Pyth price feeds through Hermes (off-chain, chain-agnostic) | +| `wethActionProvider` | No | Hard-coded WETH addresses with no WSEI entry. Use `erc20ActionProvider` with Sei's WSEI contract instead. | +| `x402ActionProvider` | No | The provider's `SUPPORTED_NETWORKS` allowlist is limited to `base-mainnet`, `base-sepolia`, `solana-mainnet`, and `solana-devnet`. The x402 protocol itself is chain-agnostic. If you need x402 on Sei, write a custom action provider or call the facilitator directly. | +| `cdpApiActionProvider` | No | Requires a Coinbase `networkId`. Sei is not in AgentKit's chain map. | +| `morphoActionProvider` | No | Morpho contracts are not deployed on Sei | +| `moonwellActionProvider` | No | Moonwell contracts are not deployed on Sei | -For Sei-native DeFi actions (swaps on Symphony/DragonSwap, staking via Silo, lending via Takara), use the [Cambrian Agent Kit](/ai/cambrian-agent-kit) alongside AgentKit, or write custom action providers. +Sei-native DeFi actions include swaps on Symphony or DragonSwap, staking through Silo, and lending through Takara. For these actions, use the [Cambrian Agent Kit](/ai/cambrian-agent-kit) alongside AgentKit, or write custom action providers. -### Known Quirks on Sei +### Known quirks on Sei -Verified by running AgentKit `0.10.4` against Sei Testnet (`chain 1328`). These quirks sit in AgentKit's network and action-provider layer and apply to **both** `ViemWalletProvider` and `PrivyWalletProvider`: +These quirks were verified with AgentKit `0.10.4` against Sei Testnet (`chain 1328`). They are in AgentKit's network and action-provider layer, and they apply to both `ViemWalletProvider` and `PrivyWalletProvider`: -- **Balances are labeled "ETH" in action output.** `walletActionProvider` hard-codes the native-currency symbol, so `get_wallet_details` returns strings like `Native Balance: 512993.50 ETH` and `native_transfer` responses say `Transferred 0.05 ETH to 0x...` even on Sei. Signing and arithmetic are unaffected — it's a display-only quirk. If the LLM will quote balances or transfer confirmations to users, add a post-processing step or a system-prompt instruction to rewrite `ETH` → `SEI` when `chain_id == 1329 || 1328`. -- **`networkId` is `undefined`.** Coinbase's internal `CHAIN_ID_TO_NETWORK_ID` map only includes Ethereum, Polygon, Base, Arbitrum, and Optimism (mainnet + testnet). Sei's chain IDs aren't in it, so `walletProvider.getNetwork()` returns `{ protocolFamily: 'evm', chainId: '1328', networkId: undefined }`. This is harmless for signing/sending, but **any action provider that branches on `networkId`** will refuse to run on Sei. In practice, `AgentKit.from({...})` prints a warning like `The following action providers are not supported on the current network and will be unavailable: weth, x402` and silently drops them — if you expect an action and it's missing from `agentKit.getActions()`, check this warning first. +- **Balances are labeled "ETH" in action output.** `walletActionProvider` hard-codes the native-currency symbol. Even on Sei, `get_wallet_details` returns strings like `Native Balance: 512993.50 ETH`, and `native_transfer` responses say `Transferred 0.05 ETH to 0x...`. The quirk affects only the display, not signing or arithmetic. If the LLM quotes balances or transfer confirmations to users, rewrite `ETH` to `SEI` when `chain_id == 1329 || 1328`. Use a post-processing step or a system-prompt instruction. +- **`networkId` is `undefined`.** Coinbase's internal `CHAIN_ID_TO_NETWORK_ID` map includes only Ethereum, Polygon, Base, Arbitrum, and Optimism (mainnet and testnet). Sei's chain IDs are not in the map, so `walletProvider.getNetwork()` returns `{ protocolFamily: 'evm', chainId: '1328', networkId: undefined }`. This is harmless for signing and sending, but any action provider that branches on `networkId` refuses to run on Sei. In practice, `AgentKit.from({...})` prints a warning like `The following action providers are not supported on the current network and will be unavailable: weth, x402` and silently drops those providers. If you expect an action and it is missing from `agentKit.getActions()`, check this warning first. -### CDP-Managed Wallets and Sei +### CDP-managed wallets and Sei -AgentKit's `CdpEvmWalletProvider` (CDP-managed server wallets with built-in policies) is currently scoped to `base`, `base-sepolia`, `ethereum`, `ethereum-sepolia`, `polygon`, `arbitrum`, and `optimism` — **Sei is not a supported network**. +AgentKit's `CdpEvmWalletProvider` (CDP-managed server wallets with built-in policies) currently supports only `base`, `base-sepolia`, `ethereum`, `ethereum-sepolia`, `polygon`, `arbitrum`, and `optimism`. **Sei is not a supported network.** -For managed cloud custody with a policy engine on Sei, use one of: +For managed cloud custody with a policy engine on Sei, use one of these options: -- **Privy server wallets** (below) — TEE-isolated keys with a policy engine that works on any EVM chain, including Sei. -- **AgentKit + Privy combined** — use `PrivyWalletProvider` inside AgentKit to keep the 40+ action providers while delegating custody and policy enforcement to Privy. See [Using AgentKit with Privy (Combined)](#using-agentkit-with-privy-combined) below. +- **Privy server wallets** (below): TEE-isolated keys with a policy engine that works on any EVM chain, including Sei. +- **AgentKit and Privy combined**: Use `PrivyWalletProvider` inside AgentKit. You keep the 40+ action providers, and Privy handles custody and policy enforcement. See [Using AgentKit with Privy (combined)](#using-agentkit-with-privy-combined) below. -If you only need self-custodial keys (no TEE, you hold the private key), use `ViemWalletProvider` as shown above and enforce limits in your own application logic. +If you only need self-custodial keys, use `ViemWalletProvider` as shown above. In this setup, you hold the private key and there is no TEE. Enforce limits in your own application logic. --- -## Privy Server Wallets on Sei +## Privy server wallets on Sei -[Privy](https://docs.privy.io/) provides wallet-as-a-service infrastructure for AI agents. Server wallets are programmatically managed wallets designed for backend use — no user interaction required. Keys are isolated in TEEs with Shamir secret sharing and never leave secure enclaves. +[Privy](https://docs.privy.io/) offers wallet-as-a-service infrastructure for AI agents. Server wallets are programmatically managed wallets designed for backend use. They do not require user interaction. Keys are isolated in TEEs with Shamir secret sharing and never leave secure enclaves. ### Prerequisites @@ -273,7 +273,7 @@ Response: -Use `eip155:1329` (CAIP-2 format) to target Sei Mainnet: +To target Sei Mainnet, use `eip155:1329` (CAIP-2 format): ```bash curl --request POST https://api.privy.io/v1/wallets/wallet_abc123/rpc \ @@ -399,16 +399,16 @@ print(f"Transaction hash: {result.hash}") -### Known Quirks on Sei (Privy) +### Known quirks on Sei (Privy) -Verified by running `@privy-io/server-auth` `1.32.5` against Sei Testnet (`eip155:1328`): +These quirks were verified with `@privy-io/server-auth` `1.32.5` against Sei Testnet (`eip155:1328`): -- **`value` must be a hex string, not a `BigInt`.** Privy's request signer uses RFC 8785 JSON canonicalization (`canonicalize`), which throws `TypeError: Do not know how to serialize a BigInt` if you pass a `BigInt` in any field of the `transaction` object. Convert viem's `parseEther(...)` output with `'0x' + parseEther('0.01').toString(16)` before sending. -- **`authorizationKeyIds` on `createWallet` expects the public-key registration ID, not the dashboard key ID.** Passing the ID shown next to a key in the Privy dashboard can fail with `400 Invalid authorization key IDs`. If you only need an app-owned wallet (app credentials + `authorizationPrivateKey` for request signing), omit `authorizationKeyIds` — the wallet is still fully operable. +- **`value` must be a hex string, not a `BigInt`.** Privy's request signer uses RFC 8785 JSON canonicalization (`canonicalize`). If you pass a `BigInt` in any field of the `transaction` object, the signer throws `TypeError: Do not know how to serialize a BigInt`. Before you send, convert viem's `parseEther(...)` output with `'0x' + parseEther('0.01').toString(16)`. +- **`authorizationKeyIds` on `createWallet` expects the public-key registration ID, not the dashboard key ID.** If you pass the ID shown next to a key in the Privy dashboard, the call can fail with `400 Invalid authorization key IDs`. If you only need an app-owned wallet (app credentials and `authorizationPrivateKey` for request signing), omit `authorizationKeyIds`. The wallet is still fully operable. ### Privy with LangChain -Privy publishes a LangChain integration (`langchain-privy`) that exposes wallet operations as a single LangChain tool. The tool reads `PRIVY_APP_ID` and `PRIVY_APP_SECRET` from the environment and is bound directly to the LLM: +Privy publishes a LangChain integration (`langchain-privy`) that exposes wallet operations as a single LangChain tool. The tool reads `PRIVY_APP_ID` and `PRIVY_APP_SECRET` from the environment. You bind it directly to the LLM: ```python import os @@ -428,18 +428,20 @@ response = llm_with_tools.invoke("What is my wallet address?") ``` -As of `langchain-privy@0.1.0`, the library's `Chain` enum does not include Sei — the built-in tool only targets Ethereum, Base, Optimism, Arbitrum, Polygon, Zora, Avalanche, BSC, Celo, Linea, Solana, and Bitcoin. For Sei, either: +For Sei, use one of these options instead of the built-in LangChain tool: -- Call Privy's REST API / server-auth SDK directly with `caip2: eip155:1329` (shown above), or -- Use AgentKit's `PrivyWalletProvider` with a LangChain adapter (`@coinbase/agentkit-langchain`) — see the [Combined](#using-agentkit-with-privy-combined) section below. +- Call Privy's REST API or server-auth SDK directly with `caip2: eip155:1329`, as shown above. +- Use AgentKit's `PrivyWalletProvider` with a LangChain adapter (`@coinbase/agentkit-langchain`). See [Using AgentKit with Privy (combined)](#using-agentkit-with-privy-combined) below. + +As of `langchain-privy@0.1.0`, the library's `Chain` enum does not include Sei. The built-in tool targets only Ethereum, Base, Optimism, Arbitrum, Polygon, Zora, Avalanche, BSC, Celo, Linea, Solana, and Bitcoin. -### Privy Policy Engine +### Privy policy engine -Privy's policy engine evaluates policies server-side before signing. Each rule pairs an `ALLOW`/`DENY` action with an RPC `method` and a list of `conditions` on transaction fields. Attach one or more policies to a wallet via `updateWallet`. +Privy's policy engine evaluates policies server-side before signing. Each rule pairs an `ALLOW` or `DENY` action with an RPC `method` and a list of `conditions` on transaction fields. To attach one or more policies to a wallet, use `updateWallet`. -**Privy's engine is default-deny.** A request is allowed only when at least one `ALLOW` rule matches and no `DENY` rule matches. A policy built from `DENY`-only rules blocks every transaction — including ones you expect to pass. Always start from an explicit `ALLOW` rule that describes the happy path, then layer `DENY` rules on top. +Always start from an explicit `ALLOW` rule that describes the happy path. Then add `DENY` rules on top. **Privy's engine is default-deny.** It allows a request only when at least one `ALLOW` rule matches and no `DENY` rule matches. A policy built only from `DENY` rules blocks every transaction, including transactions you expect to pass. ```typescript @@ -488,21 +490,21 @@ await privy.walletApi.updateWallet({ ``` -Conditions support the `eq`, `gt`, `gte`, `lt`, `lte`, and `in` operators against `ethereum_transaction` fields (`to`, `value`) or `ethereum_calldata` fields. Operand order is `tx_field rule_value` — e.g. `operator: 'lte'` with `value: '10000000000000000000'` means "transaction value ≤ 10 SEI". `method` must be `eth_sendTransaction` or `eth_signTransaction`. Chain restriction is not a policy condition — enforce `caip2: 'eip155:1329'` at the call site to keep an agent on Sei. +Conditions support the `eq`, `gt`, `gte`, `lt`, `lte`, and `in` operators against `ethereum_transaction` fields (`to`, `value`) or `ethereum_calldata` fields. The operand order is `tx_field rule_value`. For example, `operator: 'lte'` with `value: '10000000000000000000'` means "transaction value ≤ 10 SEI". `method` must be `eth_sendTransaction` or `eth_signTransaction`. Chain restriction is not a policy condition. To keep an agent on Sei, enforce `caip2: 'eip155:1329'` at the call site. -Privy also offers features beyond the policy engine: +Privy also has features beyond the policy engine: -- **Key quorums** — require multiple authorization keys to approve high-value transactions -- **Webhook notifications** — get notified of all wallet activity (works chain-agnostically) +- **Key quorums**: require multiple authorization keys to approve high-value transactions +- **Webhook notifications**: get notifications for all wallet activity, on any chain --- -## Using AgentKit with Privy (Combined) +## Using AgentKit with Privy (combined) -AgentKit includes a built-in `PrivyWalletProvider`, so you can use Privy's wallet infrastructure and policy engine as the backend while using AgentKit's 40+ action providers for onchain operations. +AgentKit includes a built-in `PrivyWalletProvider`. With it, you can use Privy's wallet infrastructure and policy engine as the backend, and AgentKit's 40+ action providers for onchain operations. -Because of the `authorizationKeyIds` quirk noted above, the simplest working pattern is to create the wallet once via the Privy SDK (or the dashboard) and then hand the resulting `walletId` to AgentKit: +Because of the `authorizationKeyIds` quirk noted above, the simplest working pattern has two steps. First, create the wallet once with the Privy SDK (or the dashboard). Then pass the resulting `walletId` to AgentKit: ```typescript import { AgentKit, PrivyWalletProvider, walletActionProvider, erc20ActionProvider } from '@coinbase/agentkit'; @@ -533,104 +535,104 @@ const agentKit = await AgentKit.from({ }); ``` -This gives you the best of both worlds: Privy's fine-grained policies and key quorums with AgentKit's rich action library. +This setup combines Privy's fine-grained policies and key quorums with AgentKit's action library. -If you call `PrivyWalletProvider.configureWithWallet` **without** a `walletId`, AgentKit will attempt to create a new wallet for you and pass `authorizationKeyId` through to Privy — which hits the same `400 Invalid authorization key IDs` failure described in Privy's Known Quirks. Always pre-create the wallet and pass `walletId`. +Always create the wallet first and pass `walletId`. If you call `PrivyWalletProvider.configureWithWallet` **without** a `walletId`, AgentKit tries to create a new wallet for you. It passes `authorizationKeyId` through to Privy, which causes the same `400 Invalid authorization key IDs` failure described in the Privy quirks above. --- -## Feature Matrix +## Feature matrix -### Wallet Creation & Key Management +### Wallet creation & key management | Capability | Coinbase AgentKit | Privy | | --- | --- | --- | -| Programmatic wallet creation on Sei | Yes — self-custodial via `ViemWalletProvider` (you hold the key). CDP-managed server wallets do not currently support Sei. | Yes — Server wallets on any EVM | -| TEE-secured key isolation on Sei | No — CDP's TEE signer is scoped to Base/Ethereum/Polygon/Arbitrum/Optimism. Use Privy (standalone or via `PrivyWalletProvider` in AgentKit). | Yes — TEE + key sharding | -| Managed cloud custody on Sei | No via CDP. Yes via `PrivyWalletProvider`. | Yes — Server wallets with `eip155:1329` | -| Multi-party key quorum | No | Yes — Authorization key quorums via dashboard | +| Programmatic wallet creation on Sei | Yes, self-custodial with `ViemWalletProvider` (you hold the key). CDP-managed server wallets do not currently support Sei. | Yes, with server wallets on any EVM chain | +| TEE-secured key isolation on Sei | No. CDP's TEE signer is scoped to Base/Ethereum/Polygon/Arbitrum/Optimism. Use Privy (standalone or through `PrivyWalletProvider` in AgentKit). | Yes, with TEE + key sharding | +| Managed cloud custody on Sei | Not through CDP. Yes, through `PrivyWalletProvider`. | Yes, with server wallets and `eip155:1329` | +| Multi-party key quorum | No | Yes, with authorization key quorums through the dashboard | | Key export / portability | Yes | Yes | -### Policy Engine & Guardrails +### Policy engine & guardrails | Capability | Coinbase AgentKit | Privy | | --- | --- | --- | -| Spending limits (per-tx) on Sei | Only via app-level checks with `ViemWalletProvider`. CDP's `ethValue` policy doesn't apply on Sei. | Yes — Policy engine, any chain | -| Contract / address allowlisting on Sei | Only via app-level checks with `ViemWalletProvider`. CDP's `evmAddress` policy doesn't apply on Sei. | Yes — Contract allowlist rules | -| Network restriction policies on Sei | N/A — CDP networkIds don't include Sei | Yes — Chain restrictions | +| Spending limits (per-tx) on Sei | Only through app-level checks with `ViemWalletProvider`. CDP's `ethValue` policy does not apply on Sei. | Yes, with the policy engine on any chain | +| Contract / address allowlisting on Sei | Only through app-level checks with `ViemWalletProvider`. CDP's `evmAddress` policy does not apply on Sei. | Yes, with contract allowlist rules | +| Network restriction policies on Sei | N/A. CDP networkIds do not include Sei. | Yes, with chain restrictions | | Time-based access controls | No | Yes | -| Transaction simulation | No | No — Needs Sei-specific RPC | +| Transaction simulation | No | No. Needs a Sei-specific RPC. | -### Gas & Transaction Management +### Gas & transaction management | Capability | Coinbase AgentKit | Privy | | --- | --- | --- | -| Gasless / sponsored transactions on Sei | No — Gasless is Base-only | No — Requires Sei-native paymaster | -| Smart wallet (ERC-4337) on Sei | No — Smart Accounts don't include Sei | No — Possible via ZeroDev or Biconomy integration | -| Batch transactions on Sei | No — Requires Smart Accounts | Yes | +| Gasless / sponsored transactions on Sei | No. Gasless is Base-only. | No. Requires a Sei-native paymaster. | +| Smart wallet (ERC-4337) on Sei | No. Smart Accounts do not include Sei. | No, but possible through a ZeroDev or Biconomy integration | +| Batch transactions on Sei | No. Requires Smart Accounts. | Yes | | Basic send / transfer on Sei | Yes | Yes | -| ERC-20 token operations on Sei | Yes — `erc20ActionProvider` | Yes — Standard EVM ops | +| ERC-20 token operations on Sei | Yes, with `erc20ActionProvider` | Yes, with standard EVM operations | -### Agentic DeFi Actions +### Agentic DeFi actions | Capability | Coinbase AgentKit | Privy | | --- | --- | --- | -| Token swaps on Sei DEXs | No — Built-in swap providers (Jupiter, 0x, Sushi, Enso) don't route Sei DEXs | No | -| Yield / lending on Sei | No — Built-in lending providers (Morpho, Moonwell, Compound, Yelay) aren't deployed on Sei | No | +| Token swaps on Sei DEXs | No. Built-in swap providers (Jupiter, 0x, Sushi, Enso) do not route Sei DEXs. | No | +| Yield / lending on Sei | No. Built-in lending providers (Morpho, Moonwell, Compound, Yelay) are not deployed on Sei. | No | | Liquidity provision on Sei | No | No | -| Cross-chain bridge to/from Sei | No — Sei not a listed Across route | No | -| Pyth oracle price feeds | Yes — `pythActionProvider` works on Sei | No | +| Cross-chain bridge to/from Sei | No. Sei is not a listed Across route. | No | +| Pyth oracle price feeds | Yes, `pythActionProvider` works on Sei | No | -For Sei-native DeFi actions, use the [Cambrian Agent Kit](/ai/cambrian-agent-kit) which includes built-in integrations for Symphony, DragonSwap, Silo, Takara, and Citrex. +For Sei-native DeFi actions, use the [Cambrian Agent Kit](/ai/cambrian-agent-kit). It includes built-in integrations for Symphony, DragonSwap, Silo, Takara, and Citrex. -### x402 & Machine-to-Machine Payments +### x402 & machine-to-machine payments | Capability | Coinbase AgentKit | Privy | | --- | --- | --- | -| x402 protocol support on Sei | No via built-in `x402ActionProvider` (allowlist is Base + Solana only) — possible via a custom action provider | Yes — Works wherever agent holds stablecoins | -| Agent-to-agent USDC transfers | Yes — ERC-20 transfers with Sei USDC | Yes — Server wallet transfers | -| Stablecoin operations on Sei | Yes — `erc20ActionProvider` + Sei USDC | Yes — Standard ERC-20 ops | +| x402 protocol support on Sei | Not with the built-in `x402ActionProvider` (its allowlist is Base + Solana only). Possible with a custom action provider. | Yes. Works wherever the agent holds stablecoins. | +| Agent-to-agent USDC transfers | Yes, with ERC-20 transfers of Sei USDC | Yes, with server wallet transfers | +| Stablecoin operations on Sei | Yes, with `erc20ActionProvider` + Sei USDC | Yes, with standard ERC-20 operations | -### Developer Experience +### Developer experience | Capability | Coinbase AgentKit | Privy | | --- | --- | --- | -| MCP server integration | Yes — AgentKit MCP framework extension | No | -| LangChain / Vercel AI SDK | Yes — Framework extensions for both | Yes — `langchain-privy` | -| OpenAI Agents SDK | Yes — Native extension | No | -| Webhook / event monitoring on Sei | No — Webhooks for supported networks only | Yes — Chain-agnostic webhooks | +| MCP server integration | Yes, through the AgentKit MCP framework extension | No | +| LangChain / Vercel AI SDK | Yes, with framework extensions for both | Yes, with `langchain-privy` | +| OpenAI Agents SDK | Yes, with a native extension | No | +| Webhook / event monitoring on Sei | No. Webhooks are for supported networks only. | Yes, with chain-agnostic webhooks | | Multi-language SDKs | TypeScript, Python | TypeScript, Python, Java, Rust, Go + REST | --- -## Other Agentic Wallet Solutions +## Other agentic wallet solutions -While Coinbase AgentKit and Privy are the most mature options for Sei, several other platforms support agentic wallet use cases: +Coinbase AgentKit and Privy are the most mature options for Sei. Several other platforms also support agentic wallet use cases: -| Platform | Approach | Sei Support | Best For | +| Platform | Approach | Sei support | Best for | | --- | --- | --- | --- | -| [Turnkey](https://docs.turnkey.com/products/embedded-wallets/features/agentic-wallets) | TEE-based key isolation, sub-100ms signing, granular policies | Yes (any EVM) | Enterprise agents needing fine-grained policies | +| [Turnkey](https://docs.turnkey.com/products/embedded-wallets/features/agentic-wallets) | TEE-based key isolation, sub-100ms signing, granular policies | Yes (any EVM) | Enterprise agents that need fine-grained policies | | [Lit Protocol](https://developer.litprotocol.com/) | Decentralized key management (DKG), programmable key pairs as NFTs | Yes (any EVM) | Decentralized, user-owned agent delegation | -| [Dynamic](https://www.dynamic.xyz/ecosystems/sei) | MPC or smart contract wallets, strong onboarding UX | Yes (explicit Sei support) | Apps serving both humans and agents | +| [Dynamic](https://www.dynamic.xyz/ecosystems/sei) | MPC or smart contract wallets, strong onboarding UX | Yes (explicit Sei support) | dApps that serve both humans and agents | | [thirdweb](https://thirdweb.com/) | Backend wallets + account abstraction, session keys | Yes (any EVM) | Broadest AI framework support (6+ frameworks) | | [Openfort](https://www.openfort.io/solutions/ai-agents) | TEE server wallets, sub-125ms signing, 25+ EVM chains | Yes (any EVM) | Gaming and high-throughput agent workloads | --- -## Sei Network Configuration Reference +## Sei network configuration reference -Use these values when configuring any agentic wallet provider for Sei: +Use these values when you configure any agentic wallet provider for Sei: | Parameter | Mainnet | Testnet | | --- | --- | --- | @@ -639,16 +641,16 @@ Use these values when configuring any agentic wallet provider for Sei: | **CAIP-2** | `eip155:1329` | `eip155:1328` | | **RPC URL** | `https://evm-rpc.sei-apis.com` | `https://evm-rpc-testnet.sei-apis.com` | | **Currency** | SEI (18 decimals) | SEI (18 decimals) | -| **Block Explorer** | [seiscan.io](https://seiscan.io) | [seiscan.io](https://testnet.seiscan.io) | +| **Block explorer** | [seiscan.io](https://seiscan.io) | [testnet.seiscan.io](https://testnet.seiscan.io) | | **Finality** | ~400ms | ~400ms | -**Security Reminders:** +**Security reminders:** -- Never expose private keys or authorization secrets to the LLM/agent process. -- Always use dedicated wallets for agent operations — never your main wallet. -- Start with testnet (`eip155:1328`) before deploying to mainnet. -- Set spending limits and contract allowlists via the policy engine before going live. -- Monitor agent wallet activity via block explorers or webhook notifications. +- Never expose private keys or authorization secrets to the LLM or agent process. +- Always use dedicated wallets for agent operations. Never use your main wallet. +- Start on Sei Testnet (`eip155:1328`) before you deploy to Sei Mainnet. +- Before you go live, set spending limits and contract allowlists in the policy engine. +- Monitor agent wallet activity with block explorers or webhook notifications. diff --git a/ai/cambrian-agent-kit.mdx b/ai/cambrian-agent-kit.mdx index 04e281d..3c7033f 100644 --- a/ai/cambrian-agent-kit.mdx +++ b/ai/cambrian-agent-kit.mdx @@ -6,54 +6,52 @@ keywords: ['cambrian agent kit', 'sei blockchain', 'ai agents', 'defi protocols' --- ## Overview -Cambrian Agent Kit is a developer SDK for building powerful, autonomous AI agents and agentic chatbots on the SEI blockchain. It lets you interact with DeFi protocols (Takara, Silo, Citrex, Symphony), manage SEI tokens and NFTs, and seamlessly integrate AI workflows. In this tutorial, you'll learn how to set up the kit, run your first agent, and use it for real DeFi use cases—customized for your needs. To understand more and deep dive into how it works under the hood, please refer to the [Cambrian Agent Kit Documentation](https://deepwiki.com/CambrianAgents/sei-agent-kit/1-overview). +Cambrian Agent Kit is a developer SDK to build autonomous AI agents and agentic chatbots on Sei. It lets you interact with DeFi protocols (Takara, Silo, Citrex, Symphony), manage SEI tokens and NFTs, and integrate AI workflows. This tutorial shows how to set up the kit, run your first agent, and adapt it to real DeFi use cases. For details about how the kit works internally, see the [Cambrian Agent Kit documentation](https://deepwiki.com/CambrianAgents/sei-agent-kit/1-overview). -## Supported Features +## Supported features -The SEI Agent Kit supports a comprehensive set of features for blockchain agent development: +For blockchain agent development, you can use the kit to: -- Token Operations: Complete SEI ERC-20 and ERC-721 token management -- DeFi Protocol Integration: Seamless interaction with SEI's DeFi ecosystem -- Swap Functionality: Token swapping through Symphony aggregator -- Liquidity Management: Add and remove liquidity with DragonSwap -- Lending & Borrowing: Interact with Takara protocol for lending operations -- Staking Operations: Stake and unstake SEI tokens with Silo -- LangChain Integration: Build AI agents with LangChain and LangGraph +- Manage ERC-20 and ERC-721 tokens on Sei +- Interact with the Sei DeFi ecosystem +- Swap tokens through the Symphony aggregator +- Add and remove liquidity with DragonSwap +- Lend and borrow with the Takara protocol +- Stake and unstake SEI tokens with Silo +- Build AI agents with LangChain and LangGraph ## What this guide teaches you: -This tutorial guides you through: - -- **Setup**: Install and configure the Agent Kit, connect your wallet and API keys. -- **Core Concepts**: Understand agents, supported protocols, and how these components fit together. -- **End-to-End Examples**: You'll run practical code to: - - Check your token/NFT balances. - - Swap tokens using Symphony. - - Stake/unstake SEI in Silo. - - Lend/borrow with Takara. - - Trade perps with Citrex. -- **Customization**: Learn to adapt the kit for your own protocol or workflow. +- Install and configure the kit, and connect your wallet and API keys. +- Understand the core concepts: agents, supported protocols, and how these components fit together. +- Run end-to-end code examples to: + - Check your token and NFT balances. + - Swap tokens with Symphony. + - Stake and unstake SEI in Silo. + - Lend and borrow with Takara. + - Trade perpetuals with Citrex. +- Adapt the kit for your own protocol or workflow. -**Some Use Cases:** +**Example use cases:** -- **Autonomous DeFi Agents**: Agents that can automatically manage token positions, provide liquidity, or engage in lending activities -- **AI-Assisted Wallets**: Conversational interfaces for blockchain operations -- **Financial Assistant Agents**: AI agents that can analyze market conditions and execute trades -- **Portfolio Management Agents**: Automated management of crypto asset portfolios +- **Autonomous DeFi agents**: Agents that can automatically manage token positions, provide liquidity, or take part in lending +- **AI-assisted wallets**: Conversational interfaces for blockchain operations +- **Financial assistant agents**: AI agents that can analyze market conditions and execute trades +- **Portfolio management agents**: Agents that manage crypto asset portfolios automatically -## Hands-on Tutorial +## Hands-on tutorial ### 1. Prerequisites -- Node.js & npm installed -- SEI wallet private key -- OpenAI API key (for AI integrations) -- **Minimum SEI balance**: Ensure you have sufficient SEI for gas +- Node.js and npm installed +- A private key for your Sei wallet +- An OpenAI API key (for AI integrations) +- Enough SEI in your wallet to pay for gas -### 2. Project Setup +### 2. Project setup ```bash git clone https://github.com/CambrianAgents/sei-agent-kit.git @@ -71,19 +69,17 @@ RPC_URL=https://evm-rpc.sei-apis.com ``` -**Important Security Notes:** - -- **Never share your private key**: Your private key controls your funds +Never share your private key. Your private key controls your funds. -### 3. Running Your First Agent +### 3. Running your first agent ```bash npm run test ``` -The following is the output and interaction with the Cambrian Agent: +This is the command output and a sample chat with the Cambrian Agent: ```bash npm run test @@ -159,17 +155,17 @@ You: bye ``` -**Understanding the Transaction:** +**About the transaction:** -- **SEI Address**: `0x0` represents native SEI token in the agent kit -- **Transaction Hash**: Can be verified on [Seiscan](https://seiscan.io/) -- **Gas Fees**: Automatically calculated and deducted from your balance +- **SEI address**: `0x0` represents the native SEI token in the agent kit. +- **Transaction hash**: You can verify it on [Seiscan](https://seiscan.io/). +- **Transaction fees**: Fees are calculated automatically and deducted from your balance. -### 4. Explore Core Features & Protocols +### 4. Explore core features & protocols -#### a) Check Token Balance with Error Handling +#### a) Check token balance with error handling ```typescript import { SeiAgentKit } from './src/agent'; @@ -199,7 +195,7 @@ async function checkBalanceWithErrorHandling() { } ``` -#### b) Safe Token Swapping with Symphony +#### b) Safe token swapping with Symphony ```typescript async function safeSwap() { @@ -242,15 +238,15 @@ async function safeSwap() { ``` -**Swap Safety Tips:** +**Swap safety tips:** -- **SEI Native Token**: Use "0x0" as the address for native SEI token while using the agent kit -- **Slippage Protection**: Always set appropriate slippage tolerance -- **Price Impact**: Monitor price impact before large swaps +- In the agent kit, use `0x0` as the address for the native SEI token. +- Always set an appropriate slippage tolerance. +- Monitor the price impact before large swaps. -#### c) Liquid Staking with Silo Protocol +#### c) Liquid staking with Silo protocol ```typescript async function stakingWithSilo() { @@ -283,16 +279,16 @@ async function stakingWithSilo() { ``` -**Silo Staking Details:** +**Silo staking details:** -- **iSEI Token**: [Represents your staked SEI plus auto-compounded rewards](https://silostaking.gitbook.io/silo-staking/general-faq) -- **No Unbonding Period**: [Immediate liquidity unlike traditional staking](https://medium.com/@nordicmoney22/unleashing-the-power-of-liquid-staking-on-sei-4a1d045232e1) -- **5% Fee**: [Annual management fee of 5% on rewards](https://silostaking.gitbook.io/silo-staking/general-faq) -- **MEV Benefits**: [Validators share MEV profits with stakers](https://www.silostaking.io/) +- **iSEI token**: [Represents your staked SEI plus auto-compounded rewards](https://silostaking.gitbook.io/silo-staking/general-faq) +- **No unbonding period**: [Immediate liquidity, unlike traditional staking](https://medium.com/@nordicmoney22/unleashing-the-power-of-liquid-staking-on-sei-4a1d045232e1) +- **5% fee**: [Annual management fee of 5% on rewards](https://silostaking.gitbook.io/silo-staking/general-faq) +- **MEV benefits**: [Validators share MEV profits with stakers](https://www.silostaking.io/) -#### d) Lending/Borrowing with Takara Protocol +#### d) Lending/borrowing with Takara protocol ```typescript async function takaraLending() { @@ -332,7 +328,7 @@ async function takaraLending() { } ``` -#### e) Perpetual Trading with Citrex Markets +#### e) Perpetual trading with Citrex Markets ```typescript async function citrexTrading() { @@ -368,14 +364,14 @@ async function citrexTrading() { } ``` -See `/tools/` for more advanced protocol integrations! +For more advanced protocol integrations, see `/tools/`. -## Error Handling & Troubleshooting +## Error handling & troubleshooting -### Common Error Types +### Common error types -**Comprehensive Error Handling Examples:** +**Error handling examples:** ```typescript // Robust error handling for all operations @@ -416,7 +412,7 @@ async function robustAgentOperation() { -### Transaction Monitoring +### Transaction monitoring ```typescript async function monitorTransaction(txHash: string) { @@ -450,18 +446,18 @@ async function monitorTransaction(txHash: string) { } ``` -### Troubleshooting Guide +### Troubleshooting guide | Issue | Cause | Solution | | --- | --- | --- | | "Insufficient funds" | Low SEI balance | Add more SEI to your wallet | -| "Transaction failed" | Gas estimation error | Reduce transaction amount | -| "Network error" | RPC connection issue | Check RPC URL in .env | -| "Slippage too high" | Price moved during swap | Increase slippage tolerance | -| "Invalid private key" | Incorrect key format | Verify private key format | +| "Transaction failed" | Gas estimation error | Reduce the transaction amount | +| "Network error" | RPC connection issue | Check the RPC URL in `.env` | +| "Slippage too high" | Price moved during swap | Increase the slippage tolerance | +| "Invalid private key" | Incorrect key format | Check the private key format | -**Debug Commands:** +**Debug commands:** ```bash # Check network connection @@ -473,9 +469,9 @@ curl -X POST https://evm-rpc.sei-apis.com \ # Use Seiscan: https://seiscan.io/ ``` -### 5. Advanced Features & Customization +### 5. Advanced features & customization -#### Multi-Protocol Strategy Example +#### Multi-protocol strategy example ```typescript async function deFiStrategy() { @@ -507,7 +503,7 @@ async function deFiStrategy() { } ``` -#### Monitoring & Alerts: +#### Monitoring & alerts: ```typescript // Set up monitoring for your agent @@ -531,6 +527,6 @@ async function setupMonitoring() { } ``` -#### Custom Protocol Integration +#### Custom protocol integration -To extend the Cambrian Agent Kit for your own protocol, please follow this repository which explains how to add plugins to the agent kit so that it can support your protocol: [Cambrian Agents Plugin Guide](https://github.com/CambrianAgents/cambrian-plugin) +To extend the Cambrian Agent Kit for your own protocol, follow the [Cambrian Agents Plugin Guide](https://github.com/CambrianAgents/cambrian-plugin). This repository explains how to add plugins to the agent kit so that it can support your protocol. diff --git a/ai/index.mdx b/ai/index.mdx index a4f35e9..0e04c04 100644 --- a/ai/index.mdx +++ b/ai/index.mdx @@ -5,33 +5,33 @@ description: 'AI tools for building on Sei — from knowledge injection that mak keywords: ['sei ai', 'ai development', 'sei-skill', 'mcp server', 'ai agents', 'blockchain ai'] --- -AI coding assistants are powerful — but they weren't trained on Sei's specifics. Without context, they'll give you generic Ethereum answers: wrong gas patterns, missing dual-address handling, outdated package names, and assumptions about finality that don't hold on a 400ms chain. +AI coding assistants were not trained on the specifics of Sei. Without context, they give you generic Ethereum answers. These answers get gas patterns wrong, miss dual-address handling, and use outdated package names. They also make assumptions about finality that do not hold on a 400ms chain. -Sei provides two complementary tools to fix this. +Sei has two complementary tools to fix this. ## Two tools, two roles - **Knowledge injection.** Teaches your AI assistant everything about Sei — architecture, precompiles, wallet patterns, gas behavior, and ecosystem — so every answer it gives is Sei-specific from the start. + **Knowledge injection.** Teaches your AI assistant everything about Sei: architecture, precompiles, wallet patterns, gas behavior, and the ecosystem. As a result, every answer it gives is Sei-specific from the start. **Live blockchain access.** Gives your AI assistant tools to read and write on-chain: query balances, send transactions, interact with contracts, and monitor network state in real time. -Use them together: sei-skill makes your assistant think in Sei, the MCP Server lets it act on Sei. To give your assistant just one area of Sei, such as contracts or bridges, install a focused skill from the [skills registry](/ai/skills). +Use them together: sei-skill gives your assistant knowledge of Sei, and the MCP Server lets it act on Sei. For a single area of Sei, such as contracts or bridges, install a focused skill from the [skills registry](/ai/skills). ## Build AI agents on Sei - SDK for building autonomous AI agents with DeFi integrations — staking, lending, swaps, liquidity — powered by LangChain. + LangChain-based SDK for building autonomous AI agents with DeFi integrations for staking, lending, swaps, and liquidity. - + Wallet infrastructure designed for AI agents: programmable signing, session keys, and policy controls. - - HTTP-native micropayments so agents can pay per-inference for LLM APIs, data feeds, and other monetized services. + + HTTP-native micropayments that let agents pay per inference for LLM APIs, data feeds, and other monetized services. diff --git a/ai/mcp-server.mdx b/ai/mcp-server.mdx index f86a6ab..9e3f7ad 100644 --- a/ai/mcp-server.mdx +++ b/ai/mcp-server.mdx @@ -3,32 +3,32 @@ title: 'MCP Server' description: 'Enable AI assistants to interact with Sei networks through natural language using the Model Context Protocol' keywords: ['mcp', 'ai', 'model context protocol', 'claude', 'cursor', 'windsurf', 'blockchain ai'] --- -The Sei Model Context Protocol (MCP) Server enables AI assistants to interact with Sei networks through natural language. Built on the [Model Context Protocol](https://modelcontextprotocol.io/) standard, it provides blockchain tools for AI coding assistants. +The Sei Model Context Protocol (MCP) Server lets AI assistants interact with Sei networks through natural language. It is built on the [Model Context Protocol](https://modelcontextprotocol.io/) standard and gives AI coding assistants blockchain tools. The Sei MCP Server is open source. Contribute at [github.com/sei-protocol/sei-js](https://github.com/sei-protocol/sei-js/tree/main/packages/mcp-server). `@sei-js/mcp-server@1` requires Node.js 20 or newer. -The server starts in read-only mode. Wallet tools that sign or broadcast are hidden unless you set `WALLET_MODE=private-key` and `PRIVATE_KEY` on the default stdio transport. +The server starts in read-only mode. It hides wallet tools that sign or broadcast unless you set `WALLET_MODE=private-key` and `PRIVATE_KEY` on the default stdio transport. ## What is MCP? -The Model Context Protocol is an open standard that connects AI systems with external tools and data sources. It enables: +The Model Context Protocol is an open standard that connects AI systems with external tools and data sources. With MCP, an AI system can: -- Real-time data access from external services -- Function execution and operations -- Context preservation across interactions -- Specialized capabilities beyond base training +- Access real-time data from external services +- Execute functions and operations +- Keep context across interactions +- Use specialized capabilities beyond its base training -The Sei MCP Server leverages this protocol to bring blockchain functionality directly to your AI assistant. +The Sei MCP Server uses this protocol to bring blockchain functionality directly to your AI assistant. ## Capabilities | Category | Features | | --- | --- | -| Account Management | Wallet addresses • Balance queries • Contract verification | -| Token Operations | SEI, ERC-20, ERC-721, and ERC-1155 reads. Transfers and approvals need wallet mode. | -| Blockchain Data | Block information • Transaction details • Network status | -| Smart Contracts | State queries. Function execution and contract deploys need wallet mode. | -| Networks | Mainnet • Testnet | +| Account management | Wallet addresses, balance queries, contract verification | +| Token operations | SEI, ERC-20, ERC-721, and ERC-1155 reads. Transfers and approvals need wallet mode. | +| Blockchain data | Block information, transaction details, network status | +| Smart contracts | State queries. Function execution and contract deploys need wallet mode. | +| Networks | Sei Mainnet, Sei Testnet | ## Setup guide @@ -36,16 +36,16 @@ The Sei MCP Server leverages this protocol to bring blockchain functionality dir -### Cursor Setup +### Cursor setup -Navigate to `Cursor → Settings → Cursor Settings → MCP` +Go to `Cursor → Settings → Cursor Settings → MCP`. - -Click **"Add new Global MCP server"** and add this configuration to `mcp.json`: + +Click **Add new Global MCP server**. Then add this configuration to `mcp.json`: ```json { @@ -60,7 +60,7 @@ Click **"Add new Global MCP server"** and add this configuration to `mcp.json`: -Restart Cursor to activate the MCP server. You'll see a notification when it's ready. +Restart Cursor to activate the MCP server. Cursor shows a notification when the server is ready. @@ -68,15 +68,15 @@ Restart Cursor to activate the MCP server. You'll see a notification when it's r -### Windsurf Setup +### Windsurf setup -Navigate to `Windsurf → Settings → Windsurf Settings → Cascade` +Go to `Windsurf → Settings → Windsurf Settings → Cascade`. - + Add the Sei MCP Server to your configuration: ```json @@ -92,7 +92,7 @@ Add the Sei MCP Server to your configuration: -Save and restart Windsurf. The server loads automatically. +Save the configuration and restart Windsurf. The server loads automatically. @@ -100,7 +100,7 @@ Save and restart Windsurf. The server loads automatically. -### Claude Desktop Setup +### Claude Desktop setup @@ -108,8 +108,8 @@ Save and restart Windsurf. The server loads automatically. Download [Claude Desktop](https://claude.ai/download) from Anthropic. - -Open **Settings** → **Developer** → **Edit Config** and add: + +Open **Settings** → **Developer** → **Edit Config**, and add this configuration: ```json { @@ -124,7 +124,7 @@ Open **Settings** → **Developer** → **Edit Config** and add: -Save and restart Claude Desktop to enable Sei tools. +Save the configuration and restart Claude Desktop to enable the Sei tools. @@ -132,7 +132,7 @@ Save and restart Claude Desktop to enable Sei tools. -### Claude CLI Setup +### Claude CLI setup @@ -142,13 +142,13 @@ npm install -g @anthropic-ai/claude-code ``` - + ```bash claude mcp add sei-mcp-server npx @sei-js/mcp-server ``` - + ```bash claude ``` @@ -180,16 +180,16 @@ The server starts in read-only mode. To enable wallet tools over the default std } ``` -Create a dedicated wallet for MCP operations. Never use your main wallet's private key. The `0x` prefix on `PRIVATE_KEY` is optional. Wallet mode is blocked on HTTP transports. Startup fails if private-key mode is misconfigured instead of silently disabling wallet tools. +Create a dedicated wallet for MCP operations. Never use your main wallet's private key. The `0x` prefix on `PRIVATE_KEY` is optional. HTTP transports block wallet mode. If private-key mode is misconfigured, startup fails. The server does not silently disable wallet tools. Export your private key from your wallet: -- Look for **Export Private Key** or **Show Private Key** in wallet settings -- Fund the wallet with small amounts for testing +- Look for **Export Private Key** or **Show Private Key** in the wallet settings. +- Fund the wallet with small amounts for testing. ## Features -The Sei MCP Server enables your AI assistant to: +With the Sei MCP Server, your AI assistant can: - Query account balances, tokens, NFTs, blocks, and transactions (read-only) - Search the official Sei docs, including `@sei-js` references (`search_docs`) @@ -198,9 +198,9 @@ The Sei MCP Server enables your AI assistant to: ## Available tools -Read-only tools stay registered when wallet mode is disabled. Signing and broadcasting tools are hidden until you enable wallet mode on stdio. +Read-only tools stay registered when wallet mode is disabled. The server hides signing and broadcasting tools until you enable wallet mode on stdio. -Network arguments accept `sei`, `sei-testnet`, `1329`, `1328`, `0x531`, or `0x530`. Unknown networks are rejected. Chain-info responses omit RPC URLs. +Network arguments accept `sei`, `sei-testnet`, `1329`, `1328`, `0x531`, or `0x530`. The server rejects unknown networks. Chain-info responses omit RPC URLs. `search_docs` queries [docs.sei.io](/). There is no `search_sei_js_docs` tool. @@ -215,7 +215,7 @@ Network arguments accept `sei`, `sei-testnet`, `1329`, `1328`, `0x531`, or `0x53 | `is_contract` | Verify a contract address | "Is 0x789... a contract?" | No | | `read_contract` | Call a read-only contract function | "Read DEX reserves" | No | | `estimate_gas` | Estimate gas for a call | "How much gas does this transfer need?" | No | -| `get_address_from_private_key` | Address for the configured key | "What's my wallet address?" | Required | +| `get_address_from_private_key` | Address for the configured key | "What is my wallet address?" | Required | | `transfer_sei` | Send SEI | "Send 1 SEI to 0x456..." | Required | | `write_contract` | Call a state-changing contract function | "Call transfer on this contract" | Required | | `deploy_contract` | Deploy bytecode | "Deploy this contract" | Required | @@ -229,21 +229,24 @@ Network arguments accept `sei`, `sei-testnet`, `1329`, `1328`, `0x531`, or `0x53 | `transfer_token` | ERC-20 transfer (`tokenAddress`, `toAddress`, `amount`) | "Send 100 USDC to 0x123..." | Required | | `approve_token_spending` | ERC-20 approval | "Approve a DEX for USDC" | Required | -Reach for `get_token_balance` and `transfer_token`. The server also registers aliases for backward compatibility: `get_erc20_balance` and `get_token_balance_erc20` behave like `get_token_balance` but name the holder argument `address` instead of `ownerAddress`, and `transfer_erc20` is `transfer_token` under a different name with the same arguments. +Use `get_token_balance` and `transfer_token`. The server also registers these aliases for backward compatibility: + +- `get_erc20_balance` and `get_token_balance_erc20` behave like `get_token_balance`, but they name the holder argument `address` instead of `ownerAddress`. +- `transfer_erc20` is `transfer_token` under a different name, with the same arguments. ### NFT and ERC-1155 | Tool | Purpose | Example | Wallet mode | | --- | --- | --- | --- | | `get_nft_info` | ERC-721 metadata | "Show NFT #123 details" | No | -| `check_nft_ownership` | ERC-721 owner check (`ownerAddress` in, boolean out). Failures error instead of returning `false`. | "Does 0x… own NFT #456?" | No | +| `check_nft_ownership` | ERC-721 owner check (`ownerAddress` in, boolean out). Failures return an error instead of `false`. | "Does 0x… own NFT #456?" | No | | `get_nft_balance` | ERC-721 collection balance | "How many NFTs do I own?" | No | | `get_erc1155_balance` | ERC-1155 balance | "Check my ERC-1155 balance" | No | | `get_erc1155_token_uri` | ERC-1155 token URI | "Get the URI for this ERC-1155" | No | | `transfer_nft` | ERC-721 `safeTransferFrom` | "Send NFT #789 to 0xABC..." | Required | | `transfer_erc1155` | ERC-1155 transfer | "Send this ERC-1155 to 0xABC..." | Required | -NFT ownership lookup failures propagate as errors instead of reporting `false`. ERC-721 transfers use `safeTransferFrom`, so contract recipients must implement `onERC721Received`. +Failed NFT ownership lookups propagate as errors instead of reporting `false`. ERC-721 transfers use `safeTransferFrom`, so contract recipients must implement `onERC721Received`. ### Blocks and transactions @@ -272,7 +275,7 @@ These prompts are always available, including in read-only mode: Summarize token metadata and balances - Walk through calling a contract + Guide you through a contract call Explain an EVM concept in context @@ -300,7 +303,7 @@ These prompts require wallet mode on the stdio transport: - "What's my SEI balance?" + "What is my SEI balance?" Calls `get_balance` and returns the wallet balance and address. @@ -343,7 +346,7 @@ evm://sei/nft/0xNFT_ADDRESS/123/isOwnedBy/0x742d... ## Configuration -Client-launched servers (`npx` from Cursor, Claude Desktop, or similar) read variables from the MCP client's `env` object. A project-local `.env` is loaded only when the process starts in a directory that contains one, such as a local checkout. +Client-launched servers (`npx` from Cursor, Claude Desktop, or a similar client) read variables from the MCP client's `env` object. The server loads a project-local `.env` file only when the process starts in a directory that contains one, such as a local checkout. ```bash # Default: read-only mode @@ -361,7 +364,7 @@ TESTNET_RPC_URL=https://your-testnet-rpc.example | Variable | Default | Notes | | --- | --- | --- | | `WALLET_MODE` | `disabled` | `private-key` enables signing tools on stdio | -| `PRIVATE_KEY` | unset | Required when `WALLET_MODE=private-key`. `0x` prefix optional | +| `PRIVATE_KEY` | unset | Required when `WALLET_MODE=private-key`. The `0x` prefix is optional | | `MAINNET_RPC_URL` | public mainnet RPC | Used only for upstream connections | | `TESTNET_RPC_URL` | public testnet RPC | Used only for upstream connections | | `SERVER_TRANSPORT` | `stdio` | `streamable-http` or `http-sse` for HTTP | @@ -371,7 +374,7 @@ TESTNET_RPC_URL=https://your-testnet-rpc.example | `SSE_MAX_SESSIONS` | `100` | Legacy SSE concurrent session cap | | `STREAMABLE_HTTP_MAX_REQUESTS` | `100` | Streamable HTTP concurrent request cap | -CLI flags such as `--http` are not supported. Set `SERVER_TRANSPORT` instead. Run `npx -y @sei-js/mcp-server --help` for the current reference. +The server does not support CLI flags such as `--http`. Set `SERVER_TRANSPORT` instead. For the current reference, run `npx -y @sei-js/mcp-server --help`. ### HTTP server mode @@ -384,7 +387,7 @@ SERVER_PORT=8080 \ npx -y @sei-js/mcp-server ``` -Connect to `http://127.0.0.1:8080/mcp`. Change the listener with `SERVER_HOST`, `SERVER_PORT`, and `SERVER_PATH`. +Connect to `http://127.0.0.1:8080/mcp`. To change the listener, set `SERVER_HOST`, `SERVER_PORT`, and `SERVER_PATH`. Legacy HTTP/SSE is available for older clients: @@ -397,22 +400,26 @@ npx -y @sei-js/mcp-server For `http-sse`, GET `{SERVER_PATH}` is the event stream. Clients POST messages to `{SERVER_PATH}/message?sessionId=`. -HTTP transports reject wallet mode. They do not authenticate callers or validate `Origin`/`Host`. Bind to `127.0.0.1` for local use, and put any public exposure behind an authenticating reverse proxy. +For local use, bind to `127.0.0.1`. Put any public exposure behind an authenticating reverse proxy. HTTP transports do not authenticate callers or validate `Origin` or `Host`. They also reject wallet mode. ## Security guidelines -Use a dedicated wallet with only the funds you need for testing. Set `PRIVATE_KEY` through environment variables or the MCP client's `env` object. Never commit it. Review transaction history on that wallet regularly. +Use a dedicated wallet with only the funds you need for testing. Set `PRIVATE_KEY` through environment variables or the MCP client's `env` object. Never commit it. Review the transaction history of that wallet regularly. -Beyond a throwaway test wallet, treat the signing key as production infrastructure: cap the value any single transaction can move, hold funds in a multi-signature wallet and let the agent operate a low-balance hot wallet, restrict the agent to an allowlist of contract addresses, and rate-limit the tools that sign or broadcast. +For anything beyond a throwaway test wallet, treat the signing key as production infrastructure: + +- Cap the value that any single transaction can move. +- Hold funds in a multi-signature wallet, and let the agent operate a low-balance hot wallet. +- Restrict the agent to an allowlist of contract addresses. +- Rate-limit the tools that sign or broadcast. ## Troubleshooting -**Connection issues**: Verify Node.js 20 or later is installed and restart your AI assistant. +**Connection issues**: Verify that Node.js 20 or later is installed. Then restart your AI assistant. -**Private key errors**: Set `WALLET_MODE=private-key`, provide a valid 32-byte secp256k1 key (`0x` prefix optional), and use the default stdio transport. +**Private key errors**: Set `WALLET_MODE=private-key`. Make sure the key is a valid 32-byte secp256k1 key (the `0x` prefix is optional). Use the default stdio transport. -**Cursor: The model returned an error. Try disabling the MCP servers, or switch models**: Disable "Auto" in the model -menu and select a specific model e.g. `claude-4-sonnet` +**Cursor: The model returned an error. Try disabling the MCP servers, or switch models**: Disable **Auto** in the model menu. Then select a specific model, for example `claude-4-sonnet`. diff --git a/ai/sei-skill/index.mdx b/ai/sei-skill/index.mdx index e4bcfd8..04e99eb 100644 --- a/ai/sei-skill/index.mdx +++ b/ai/sei-skill/index.mdx @@ -5,51 +5,51 @@ description: 'A knowledge base that makes AI coding assistants Sei-aware — cov keywords: ['sei-skill', 'ai knowledge base', 'claude', 'cursor', 'copilot', 'windsurf', 'sei development'] --- -sei-skill is open source. Contribute at [github.com/sei-protocol/sei-skill](https://github.com/sei-protocol/sei-skill) +sei-skill is open source. Contribute at [github.com/sei-protocol/sei-skill](https://github.com/sei-protocol/sei-skill). -sei-skill is a structured knowledge base for AI coding assistants. Install it once and your assistant — Claude Code, Cursor, Copilot, Windsurf, or any other — will answer Sei questions with Sei-specific accuracy instead of generic Ethereum defaults. +sei-skill is a structured knowledge base for AI coding assistants. Install it once, and your assistant gives accurate, Sei-specific answers to Sei questions instead of generic Ethereum defaults. It works with Claude Code, Cursor, Copilot, Windsurf, or any other assistant. ## Why this matters -AI assistants are trained on broad Ethereum knowledge, not Sei's specifics. Without sei-skill, they'll confidently give you wrong answers: +AI assistants are trained on broad Ethereum knowledge, not Sei's specifics. Without sei-skill, they confidently give you wrong answers like these: | Without sei-skill | With sei-skill | |---|---| -| `maxFeePerGas` in transactions | Legacy `gasPrice` (Sei doesn't use EIP-1559 basefee) | -| "Finality takes ~12 confirmations" | Instant finality — 1 confirmation is final | -| SSTORE costs 20,000 gas | SSTORE costs 72,000 gas — the same on mainnet and testnet (governance-adjustable on-chain parameter; [reference](/evm/differences-with-ethereum#sstore-gas-cost)) | -| `PREVRANDAO` for randomness | PREVRANDAO is not random on Sei — use Pyth VRF or Chainlink VRF | +| `maxFeePerGas` in transactions | Legacy `gasPrice` (Sei does not use the EIP-1559 base fee) | +| "Finality takes ~12 confirmations" | Instant finality: 1 confirmation is final | +| SSTORE costs 20,000 gas | SSTORE costs 72,000 gas, the same on Sei Mainnet and Sei Testnet. It is an on-chain parameter that governance can adjust ([reference](/evm/differences-with-ethereum#sstore-gas-cost)). | +| `PREVRANDAO` for randomness | PREVRANDAO is not random on Sei. Use Pyth VRF or Chainlink VRF. | | Generic ERC-20 patterns | Sei precompiles, pointer contracts, dual-address UX | | `@sei-js/evm` imports | `@sei-js/precompiles` (the current package name) | ## Three knowledge domains -sei-skill covers three areas. You can install all three or just the ones you need. +sei-skill covers three areas. You can install all three or only the ones that you need. -**Contracts** — EVM smart contract development on Sei: +**Contracts** covers EVM smart contract development on Sei: - Foundry and Hardhat setup for Sei networks - All Sei precompiles (Staking, Governance, Bank, Distribution, JSON, P256) - Pointer contracts for cross-VM asset bridging -- Gas optimization, OCC parallel execution awareness -- Account abstraction (ERC-4337), contract upgradeability +- Gas optimization and awareness of OCC parallel execution +- Account abstraction (ERC-4337) and contract upgradeability - Verification workflows on Seiscan - Security patterns and common errors -**Frontend** — dApp UI development: -- Wagmi + Viem setup with Sei chain config +**Frontend** covers dApp UI development: +- wagmi and viem setup with the Sei chain config - Wallet integration (Sei Global Wallet, MetaMask, Compass, Ledger, EIP-6963) -- Dual-address UX (`sei1...` ↔ `0x...` from the same key) +- Dual-address UX (`sei1...` and `0x...` addresses from the same key) - Fast-finality patterns for 400ms blocks - RainbowKit and ConnectKit integration -**Ecosystem** — infrastructure and integrations: +**Ecosystem** covers infrastructure and integrations: - RPC endpoints (public, community, paid SaaS) - Bridges (LayerZero V2, Circle CCTP v2 for native USDC) - IBC is [disabled in both directions](/learn/sip-03-migration#ibc-is-disabled) - Oracles (Chainlink, Pyth, API3, RedStone) - Indexers (The Graph, Goldsky, Dune, Moralis) - DeFi protocols (DragonSwap, Yei, Takara, Saphyre) -- Validators, node operations, grants +- Validators, node operations, and grants ## Quick install @@ -59,15 +59,15 @@ cd sei-skill ./install.sh ``` -This installs to `~/.claude/skills/sei/` by default (Claude Code). For other AI assistants, see the [Installation Guide](/ai/sei-skill/install). +By default, the script installs the skill for Claude Code in `~/.claude/skills/sei/`. For other AI assistants, see the [installation guide](/ai/sei-skill/install). ## Next steps - - Install for Claude Code, Cursor, Copilot, Windsurf, and more. Choose your variant. + + Install sei-skill for Claude Code, Cursor, Copilot, Windsurf, and other assistants. Choose your variant. - - See what better answers look like — prompts across contracts, frontend, and ecosystem. + + See what better answers look like. The prompts cover contracts, frontend, and ecosystem. diff --git a/ai/sei-skill/install.mdx b/ai/sei-skill/install.mdx index 3c913bf..087ce40 100644 --- a/ai/sei-skill/install.mdx +++ b/ai/sei-skill/install.mdx @@ -18,13 +18,13 @@ cd sei-skill -The default install targets Claude Code, placing the skill in `~/.claude/skills/sei/`: +The default install targets Claude Code and puts the skill in `~/.claude/skills/sei/`: ```bash ./install.sh ``` -The skill loads automatically in every Claude Code session. To verify it's active, ask: *"What is the SSTORE gas cost on Sei Testnet?"* +The skill loads automatically in every Claude Code session. To check that the skill is active, ask: *"What is the SSTORE gas cost on Sei Testnet?"* @@ -34,7 +34,7 @@ The skill loads automatically in every Claude Code session. To verify it's activ ./install.sh --agent codex ``` -Installs to `AGENTS.md` in your project root. Codex CLI reads this file automatically. +This command installs the skill to `AGENTS.md` in your project root. Codex CLI reads this file automatically. @@ -44,7 +44,7 @@ Installs to `AGENTS.md` in your project root. Codex CLI reads this file automati ./install.sh --agent cursor ``` -Installs to `.cursor/rules/sei.mdc` in your project. Cursor picks it up automatically as a rule file. +This command installs the skill to `.cursor/rules/sei.mdc` in your project. Cursor loads it automatically as a rule file. @@ -54,7 +54,7 @@ Installs to `.cursor/rules/sei.mdc` in your project. Cursor picks it up automati ./install.sh --agent copilot ``` -Installs to `.github/copilot-instructions.md`. Copilot uses this file as custom instructions for the repository. +This command installs the skill to `.github/copilot-instructions.md`. Copilot uses this file as custom instructions for the repository. @@ -64,7 +64,7 @@ Installs to `.github/copilot-instructions.md`. Copilot uses this file as custom ./install.sh --agent windsurf ``` -Installs to `.windsurf/rules/sei.md`. Windsurf's Cascade reads this automatically. +This command installs the skill to `.windsurf/rules/sei.md`. Windsurf's Cascade reads this file automatically. @@ -74,7 +74,7 @@ Installs to `.windsurf/rules/sei.md`. Windsurf's Cascade reads this automaticall ./install.sh --agent aider ``` -Installs to `~/.aider/sei.md`. Aider loads it as persistent context. +This command installs the skill to `~/.aider/sei.md`. Aider loads it as persistent context. @@ -84,7 +84,7 @@ Installs to `~/.aider/sei.md`. Aider loads it as persistent context. ./install.sh --agent openhands ``` -Installs to `.openhands/SKILL.md` in your project. +This command installs the skill to `.openhands/SKILL.md` in your project. @@ -94,7 +94,7 @@ Installs to `.openhands/SKILL.md` in your project. ./install.sh --agent gemini ``` -Installs to `GEMINI.md` in your project root. +This command installs the skill to `GEMINI.md` in your project root. @@ -102,16 +102,16 @@ Installs to `GEMINI.md` in your project root. ## Variants -The full skill covers all three domains (contracts, frontend, ecosystem). If you only need one area, install a variant to keep context lean: +The full skill covers all three domains (contracts, frontend, and ecosystem). If you need only one area, install a variant to keep the context small: | Variant | Command | Best for | |---|---|---| | Full (default) | `./install.sh` | General Sei development | | Contracts | `./install.sh --variant contracts` | Smart contract engineers | | Frontend | `./install.sh --variant frontend` | dApp and UI developers | -| Ecosystem | `./install.sh --variant ecosystem` | Infra, integrations, research | +| Ecosystem | `./install.sh --variant ecosystem` | Infrastructure, integrations, research | -Combine with `--agent` to target a specific assistant: +To target a specific assistant, combine the variant with `--agent`: ```bash ./install.sh --agent cursor --variant contracts @@ -125,7 +125,7 @@ Combine with `--agent` to target a specific assistant: ./install.sh --project ``` -**Flatten to a single markdown file** — useful for pasting into any chat interface or custom context: +**Flatten to a single Markdown file** (useful to paste into any chat interface or custom context): ```bash ./install.sh --flatten --output ./sei-context.md @@ -139,10 +139,10 @@ Combine with `--agent` to target a specific assistant: ## Verify it's working -After installing, test with a Sei-specific question that trips up unaugmented assistants: +After you install the skill, test it with a Sei-specific question that assistants without the skill get wrong: - *"What gas price should I use for transactions on Sei?"* - *"Is PREVRANDAO a safe source of randomness on Sei?"* - *"What's the difference between `sei1...` and `0x...` addresses?"* -A Sei-aware assistant will give accurate, specific answers to all three. +A Sei-aware assistant gives accurate, specific answers to all three. diff --git a/ai/sei-skill/prompts.mdx b/ai/sei-skill/prompts.mdx index 5506e51..9db7b8a 100644 --- a/ai/sei-skill/prompts.mdx +++ b/ai/sei-skill/prompts.mdx @@ -5,7 +5,7 @@ description: 'Prompts that unlock Sei-specific guidance from your AI assistant a keywords: ['sei-skill prompts', 'ai prompts', 'sei development', 'smart contracts', 'frontend', 'ecosystem'] --- -Once sei-skill is installed, your AI assistant has accurate, up-to-date context on everything Sei. These prompts show what that looks like in practice — questions that would get generic (wrong) Ethereum answers without the skill, and accurate Sei-specific answers with it. +After you install sei-skill, your AI assistant has accurate, up-to-date context about Sei. These prompts show what that looks like in practice. Without the skill, these questions would get generic (wrong) Ethereum answers. With the skill, they get accurate, Sei-specific answers. ## Contracts diff --git a/ai/skills.mdx b/ai/skills.mdx index ff69e26..868d0de 100644 --- a/ai/skills.mdx +++ b/ai/skills.mdx @@ -7,7 +7,7 @@ keywords: ['sei skills', 'agent skills', 'skill.md', 'npx skills add', 'claude c import { SkillsRegistry } from '/snippets/skills-registry.jsx'; -Sei Foundation publishes **agent skills**: focused, installable knowledge packs that make your AI coding assistant Sei-aware. This docs site hosts them in the open [`skill.md`](https://www.mintlify.com/docs/ai/skillmd) format, so any assistant that supports agent skills, such as Claude Code or Cursor, can install them. +Sei Foundation publishes **agent skills**: focused, installable knowledge packs that make your AI coding assistant Sei-aware. This docs site hosts them in the open [`skill.md`](https://www.mintlify.com/docs/ai/skillmd) format. Any assistant that supports agent skills, such as Claude Code or Cursor, can install them. ## Install @@ -25,20 +25,20 @@ npx skills add https://docs.sei.io --skill sei-nodes ## Foundation skills -Filter by area to find what fits your project. Each card copies the command that installs only that skill, which keeps your assistant's context small. +Filter by area to find what fits your project. Each card copies the command that installs only that skill. This keeps your assistant's context small. ## How the skills work -Each Foundation skill is a single `SKILL.md` file. Its frontmatter tells an assistant **when** to use it, and the body is a short playbook of Sei-specific facts, code, and pitfalls. +Each Foundation skill is a single `SKILL.md` file. Its frontmatter tells an assistant when to use it. The body is a short playbook of Sei-specific facts, code, and pitfalls. Agents can list every skill at `docs.sei.io/.well-known/agent-skills/index.json` (or the older `/.well-known/skills/index.json`) and fetch any `SKILL.md` directly, with no install step. Agents connected to the docs MCP server also get them as MCP resources. - Skill content comes from [`sei-protocol/sei-skill`](https://github.com/sei-protocol/sei-skill). A sync workflow regenerates the files in this repo and opens a pull request for review, and the site serves them once it merges. To fix or extend a skill, open a pull request in sei-skill. + Skill content comes from [`sei-protocol/sei-skill`](https://github.com/sei-protocol/sei-skill). A sync workflow regenerates the files in this repo and opens a pull request for review. After the pull request merges, the site serves the files. To fix or extend a skill, open a pull request in sei-skill. @@ -49,12 +49,12 @@ Each Foundation skill covers one area. To load one knowledge base that covers ev | Use a Foundation skill when | Use the full [sei-skill](/ai/sei-skill) when | |---|---| | You work mostly in one area, such as contracts | You want every area in one install | -| You want to keep your assistant's context small | You're starting a Sei project from scratch | -| You're composing your own set of skills | You want the full reference files from the sei-skill repository | +| You want to keep your assistant's context small | You start a Sei project from scratch | +| You compose your own set of skills | You want the full reference files from the sei-skill repository | ## Publish your own skill -Ecosystem teams can publish skills for their own protocols. Any Mintlify site serves the skills in its `.mintlify/skills/` directory, and developers install them with `npx skills add` and your docs URL. Foundation skill content lives in [`sei-protocol/sei-skill`](https://github.com/sei-protocol/sei-skill). +Ecosystem teams can publish skills for their own protocols. Any Mintlify site serves the skills in its `.mintlify/skills/` directory. Developers install them with `npx skills add` and your docs URL. Foundation skill content lives in [`sei-protocol/sei-skill`](https://github.com/sei-protocol/sei-skill). ## Next steps diff --git a/ai/x402.mdx b/ai/x402.mdx index fea8c1f..769ba03 100644 --- a/ai/x402.mdx +++ b/ai/x402.mdx @@ -4,22 +4,22 @@ sidebarTitle: 'x402 Protocol' description: 'Implement HTTP micropayments on Sei using x402 v2 for API monetization and digital services.' keywords: ['x402', 'x402 v2', 'micropayments', 'HTTP 402', 'API monetization', 'Sei', 'payments', 'USDC', 'web3 payments'] --- -x402 is an open protocol for HTTP-native payments. It lets clients pay for APIs, data, content, and other web resources through the standard `402 Payment Required` flow. A service can charge for a single request without requiring the buyer to create an account, manage a subscription, or negotiate a separate billing integration. +x402 is an open protocol for HTTP-native payments. It lets clients pay for APIs, data, content, and other web resources through the standard `402 Payment Required` flow. A service can charge for a single request. The buyer does not have to create an account, manage a subscription, or negotiate a separate billing integration. -When a client requests a paid resource, the server responds with the price and payment terms. The client signs a payment authorization and retries the same request. The server verifies and settles the payment before returning the resource. +When a client requests a paid resource, the server responds with the price and payment terms. The client signs a payment authorization and retries the same request. The server verifies and settles the payment before it returns the resource. ## Why x402 on Sei? -x402 payments sit in the request path. The client receives the protected response only after the payment has been authorized and settled. Sei's fast finality reduces this wait, while its low transaction costs make small per-request payments practical. +x402 payments sit in the request path. The client receives the protected response only after the payment is authorized and settled. Sei's fast finality reduces this wait. Its low transaction costs make small per-request payments practical. -Sei EVM also lets you use the upstream `@x402` packages and standard EVM wallet tooling. Native USDC is already included in the x402 default asset registry for Sei Mainnet and Sei Testnet, so dollar-denominated route pricing works without a custom token mapping. +Sei EVM also lets you use the upstream `@x402` packages and standard EVM wallet tooling. The x402 default asset registry already includes native USDC for Sei Mainnet and Sei Testnet. As a result, dollar-denominated route pricing works without a custom token mapping. When you configure x402 on Sei: - Sei Mainnet uses the CAIP-2 network identifier `eip155:1329`. - Sei Testnet uses the CAIP-2 network identifier `eip155:1328`. -- `@x402/evm` provides the EVM payment scheme implementation. +- `@x402/evm` implements the EVM payment scheme. ## How x402 works @@ -27,7 +27,7 @@ When you configure x402 on Sei: Three components take part in an x402 payment: - The **client** requests a resource and signs a payment authorization. It can be a user-facing dApp, an autonomous agent, or another service. -- The **resource server** defines the price, validates payment, and returns the protected resource. +- The **resource server** defines the price, validates the payment, and returns the protected resource. - A **facilitator** can verify the authorization, submit the payment onchain, and return the settlement result. You can use a facilitator service, run your own, or settle payments directly. @@ -66,7 +66,7 @@ The header values contain Base64-encoded JSON. The x402 SDK encodes and decodes x402 v2 supports different settlement models: - [`exact`](https://docs.x402.org/schemes/exact) charges a fixed amount for each request. -- [`upto`](https://docs.x402.org/schemes/upto) lets the client authorize a maximum amount while the seller settles the actual usage. +- [`upto`](https://docs.x402.org/schemes/upto) lets the client authorize a maximum amount. The seller then settles the actual usage. - [`batch-settlement`](https://docs.x402.org/schemes/batch-settlement) uses an escrow deposit and signed vouchers so high-volume services can settle multiple payments together. For a fixed-price API or paywall, start with the `exact` scheme. @@ -74,16 +74,16 @@ For a fixed-price API or paywall, start with the `exact` scheme. ## Use cases on Sei - Charge per request for AI inference, image generation, data feeds, or other APIs. -- Gate individual articles, media files, and downloads without requiring a subscription. +- Gate individual articles, media files, and downloads without a subscription. - Let agents and backend services pay for machine-to-machine resources. - Bill for measured infrastructure, storage, or bandwidth usage. ## Use upstream x402 v2 -The `@sei-js/x402`, `@sei-js/x402-fetch`, `@sei-js/x402-axios`, `@sei-js/x402-express`, `@sei-js/x402-hono`, and `@sei-js/x402-next` packages are deprecated and no longer maintained. +Do not use the `@sei-js/x402`, `@sei-js/x402-fetch`, `@sei-js/x402-axios`, `@sei-js/x402-express`, `@sei-js/x402-hono`, or `@sei-js/x402-next` packages for new integrations. These packages are deprecated and no longer maintained. -Do not use them for new integrations. Migrate existing integrations to the upstream x402 v2 packages under the `@x402` npm scope. +Migrate existing integrations to the upstream x402 v2 packages under the `@x402` npm scope. x402 v2 separates the protocol core, network mechanisms, and HTTP framework adapters into modular packages. @@ -99,7 +99,7 @@ x402 v2 separates the protocol core, network mechanisms, and HTTP framework adap ## Install x402 v2 -Install the EVM mechanism package together with the adapter for your client or server. +Install the EVM mechanism package and the adapter for your client or server. @@ -139,11 +139,11 @@ npm install @x402/core @x402/evm @x402/next -Follow the upstream [seller quickstart](https://docs.x402.org/getting-started/quickstart-for-sellers) or [buyer quickstart](https://docs.x402.org/getting-started/quickstart-for-buyers) for the current API. +For the current API, follow the upstream [seller quickstart](https://docs.x402.org/getting-started/quickstart-for-sellers) or [buyer quickstart](https://docs.x402.org/getting-started/quickstart-for-buyers). ## Configure Sei -Use the CAIP-2 identifier for your target network when you configure a route: +When you configure a route, use the CAIP-2 identifier for your target network: | Network | CAIP-2 identifier | Default USDC | | --- | --- | --- | @@ -153,20 +153,20 @@ Use the CAIP-2 identifier for your target network when you configure a route: Because x402 registers these assets as the defaults for Sei, a price such as `"$0.001"` resolves to the USDC address for the selected network. To accept another ERC-20 token, configure an explicit token amount and its EIP-712 metadata instead. -x402 can express and sign payments for any EVM network, but your facilitator must also support the selected Sei network. Confirm network support with your facilitator before deployment, or run your own facilitator. +Before you deploy, confirm that your facilitator supports the selected Sei network, or run your own facilitator. x402 can express and sign payments for any EVM network, but your facilitator must also support the selected Sei network. -See the upstream [network and token support](https://docs.x402.org/core-concepts/network-and-token-support) reference for current asset and facilitator details. +For current asset and facilitator details, see the upstream [network and token support](https://docs.x402.org/core-concepts/network-and-token-support) reference. ### What the facilitator does -A facilitator handles the blockchain-specific work on behalf of your resource server. It checks that the signed payload satisfies the advertised payment requirements, submits the authorized transfer, waits for the settlement result, and returns that result to your server. +A facilitator handles the blockchain-specific work for your resource server. It checks that the signed payload satisfies the advertised payment requirements and submits the authorized transfer. It then waits for the settlement result and returns that result to your server. Native USDC on Sei supports EIP-3009. With the `exact` EVM scheme, the buyer signs a transfer authorization instead of submitting the transfer transaction itself. The facilitator submits the transaction and pays the required gas. ## Protect an Express route -The following x402 v2 example charges `0.001` USDC for `GET /weather` on Sei Testnet. Set `X402_FACILITATOR_URL` to a facilitator that supports `eip155:1328`. +This x402 v2 example charges `0.001` USDC for `GET /weather` on Sei Testnet. Set `X402_FACILITATOR_URL` to a facilitator that supports `eip155:1328`. ```typescript import express from "express"; @@ -252,20 +252,20 @@ console.log(await response.json()); ``` -Do not treat a successful transaction receipt by itself as proof that a request was paid. Verification must bind the signed payload to the required network, asset, amount, recipient, resource, and validity window. Use the x402 middleware and a compatible facilitator, or implement the complete verification and settlement rules when you self-facilitate. +Do not treat a successful transaction receipt by itself as proof that a request was paid. Verification must bind the signed payload to the required network, asset, amount, recipient, resource, and validity window. Use the x402 middleware and a compatible facilitator. If you self-facilitate, implement the complete verification and settlement rules. ## Production checks - Use HTTPS so intermediaries cannot read or replace payment headers. - Keep buyer wallet keys in a secret manager or another server-side secret store. Do not ship a private key in browser code. -- Confirm facilitator support for Sei Mainnet or Sei Testnet before you deploy. +- Before you deploy, confirm that your facilitator supports Sei Mainnet or Sei Testnet. - Test rejected signatures, expired authorizations, failed settlement, and insufficient balances. - Fulfill the protected request only after x402 reports a valid payment. ## Migrate from v1 -The deprecated `@sei-js/x402*` packages implement the v1 protocol. Migrating requires more than changing package names. +The deprecated `@sei-js/x402*` packages implement the v1 protocol. To migrate, you must change more than the package names. | v1 | v2 | | --- | --- | @@ -283,7 +283,7 @@ Use the official [x402 v1-to-v2 migration guide](https://docs.x402.org/guides/mi Read the upstream protocol and SDK documentation. - Review source code, examples, and releases. + Review the source code, examples, and releases. Protect an API or web resource with x402. diff --git a/cosmos-sdk/index.mdx b/cosmos-sdk/index.mdx index 3e8e017..ffac824 100644 --- a/cosmos-sdk/index.mdx +++ b/cosmos-sdk/index.mdx @@ -8,13 +8,13 @@ canonicalUrl: "https://docs.sei.io/evm" -**Deprecation Notice** +**Deprecation notice** Cosmos SDK and CosmWasm functionality is being deprecated in favor of EVM-only. For more details, see [SIP-3](https://github.com/sei-protocol/sips/blob/main/sips/sip-3.md) and [Proposal 99](https://seistream.app/proposals/99). -In addition, [Proposal 115](https://seistream.app/proposals/115) disables CosmWasm code uploads (`MsgStoreCode`) and contract instantiations (`MsgInstantiateContract`) chain-wide. No new CosmWasm contracts can be deployed; only `execute` and `query` against pre-existing contracts remain available via the [CosmWasm precompile](/evm/precompiles/cosmwasm-precompiles/cosmwasm). +In addition, [Proposal 115](https://seistream.app/proposals/115) disables CosmWasm code uploads (`MsgStoreCode`) and contract instantiations (`MsgInstantiateContract`) chain-wide. No new CosmWasm contracts can be deployed. Only `execute` and `query` against pre-existing contracts remain available through the [CosmWasm precompile](/evm/precompiles/cosmwasm-precompiles/cosmwasm). -**IBC is now disabled in both directions.** [Proposal 116](https://seistream.app/proposals/116) and [Proposal 120](https://seistream.app/proposals/120) set the `ibc` module's `InboundEnabled` parameter to `false`, and [Proposal 121](https://seistream.app/proposals/121) set `OutboundEnabled` to `false` on July 31, 2026. No asset can be bridged into or out of Sei over IBC, and IBC assets already on Sei can no longer be redeemed on their origin chain. See the [SIP-03 Migration Guide](/learn/sip-03-migration) for the full explanation and the list of affected assets. +**IBC is now disabled in both directions.** [Proposal 116](https://seistream.app/proposals/116) and [Proposal 120](https://seistream.app/proposals/120) set the `ibc` module's `InboundEnabled` parameter to `false`, and [Proposal 121](https://seistream.app/proposals/121) set `OutboundEnabled` to `false` on July 31, 2026. No asset can be bridged into or out of Sei over IBC. IBC assets already on Sei can no longer be redeemed on their origin chain. See the [SIP-03 Migration Guide](/learn/sip-03-migration) for the full explanation and the list of affected assets. diff --git a/evm/analytics-setup.mdx b/evm/analytics-setup.mdx index 3463246..0522fb9 100644 --- a/evm/analytics-setup.mdx +++ b/evm/analytics-setup.mdx @@ -6,49 +6,49 @@ keywords: ['analytics', 'sei'] ## Overview -Setting up analytics for your project helps track user activity, transaction counts, and project growth. This guide walks you through integrating with three key platforms that provide comprehensive insights into your project's performance. +When you set up analytics for your project, you can track user activity, transaction counts, and project growth. This guide shows how to integrate with three platforms that give insights into the performance of your project. -**What you'll set up:** +**What you will set up:** - Token Terminal - Artemis - Dune Analytics -**Time required:** 20-25 minutes +**Time required:** 20 to 25 minutes -## Step 1: Sei Ecosystem Directory + Token Terminal +## Step 1: Sei ecosystem directory + Token Terminal The Monday form registers your project in the Sei ecosystem directory and automatically submits it to Token Terminal. -**Complete the Monday Form** : [Monday Form](http://forms.monday.com/forms/b6816df94378117836cd0d4046d7213b?r=apse2) +Complete the [Monday form](http://forms.monday.com/forms/b6816df94378117836cd0d4046d7213b?r=apse2). **What happens next:** - Your project appears in the Sei ecosystem directory -- Token Terminal automatically receives your project info -- Metrics begin tracking within 48-72 hours +- Token Terminal automatically receives your project information +- Metric tracking starts within 48 to 72 hours ## Step 2: Artemis Analytics -Artemis provides detailed user activity and transaction analytics for your project. +Artemis gives detailed analytics on user activity and transactions for your project. -**Complete Artemis Application** : [Artemis Application Form](https://ry0v9n8oa4l.typeform.com/to/sXX203Nk?typeform-source=app.artemisanalytics.com) +Complete the [Artemis application form](https://ry0v9n8oa4l.typeform.com/to/sXX203Nk?typeform-source=app.artemisanalytics.com). -**Processing time:** 2-4 business days for approval +**Processing time:** 2 to 4 business days for approval -## Step 3: Dune Dashboard +## Step 3: Dune dashboard Create custom analytics dashboards with detailed blockchain data. -**Follow the Sei Dune Guide** : [Dune Guide](/evm/dune) +Follow the [Sei Dune guide](/evm/dune). **Setup process:** 1. Create a free Dune account -2. Use pre-built query templates in the above guide -3. Customize queries for your contract addresses +2. Use the pre-built query templates in the Dune guide +3. Customize the queries for your contract addresses 4. Build charts and visualizations -5. Set up automated data refresh +5. Set up an automated data refresh **Key metrics to track:** @@ -57,8 +57,8 @@ Create custom analytics dashboards with detailed blockchain data. - Token transfer volumes - Contract interaction patterns -**Setup time:** 10-15 minutes using templates +**Setup time:** 10 to 15 minutes with the templates --- -These analytics platforms will provide valuable insights as your project grows and help you make data-driven decisions about development and strategy. +As your project grows, these platforms help you make data-driven decisions about development and strategy. diff --git a/evm/best-practices/optimizing-for-parallelization.mdx b/evm/best-practices/optimizing-for-parallelization.mdx index a4c02fd..cab4c82 100644 --- a/evm/best-practices/optimizing-for-parallelization.mdx +++ b/evm/best-practices/optimizing-for-parallelization.mdx @@ -4,38 +4,38 @@ sidebarTitle: 'Optimizing for Parallelization' description: 'Design patterns to reduce state conflicts and maximize Sei EVM parallel execution while lowering gas usage.' keywords: ['sei evm', 'parallelization', 'gas optimization', 'storage conflicts', 'throughput', 'precompiles'] --- -Sei EVM executes non-conflicting transactions in parallel. You can significantly increase throughput and reduce gas by designing contracts that minimize shared state access and avoid unnecessary storage writes. +Sei EVM executes non-conflicting transactions in parallel. If you design contracts that minimize shared state access and avoid unnecessary storage writes, you can increase throughput significantly and reduce gas. - This guide is based on Sei's recommendations for reducing gas usage and enhancing parallel execution. For the engine design, see [Parallelization Engine](/learn/parallelization-engine). + This guide is based on Sei's recommendations to reduce gas usage and improve parallel execution. For the engine design, see the [parallelization engine](/learn/parallelization-engine) page. -## Principles for Parallel-Friendly Contracts +## Principles for parallel-friendly contracts -- **Minimize shared writes**: The scheduler can parallelize transactions that do not write to the same storage keys. Avoid hot globals (e.g., a single counter updated on every call). -- **Partition state**: Shard storage by user, asset, or id so independent transactions touch disjoint keys. -- **Prefer pull over push**: Let users claim funds instead of mass-paying recipients in loops. -- **Avoid unbounded loops**: Especially loops that write to storage or iterate over dynamic arrays/mappings. -- **Batch internal work; isolate external effects**: Do heavy computation in memory and commit a minimal set of storage writes. -- **Use precompiles when available**: Precompiles are highly optimized and cheaper than replicating logic in Solidity. +- **Minimize shared writes**: The scheduler can parallelize transactions that do not write to the same storage keys. Avoid hot globals (for example, a single counter that every call updates). +- **Partition state**: Shard storage by user, asset, or ID so that independent transactions touch disjoint keys. +- **Prefer pull over push**: Let users claim funds instead of paying many recipients in a loop. +- **Avoid unbounded loops**: This applies especially to loops that write to storage or iterate over dynamic arrays or mappings. +- **Batch internal work and isolate external effects**: Do heavy computation in memory and commit a minimal set of storage writes. +- **Use precompiles when available**: Precompiles are highly optimized and cost less than the same logic written in Solidity. **Parallelization checklist:** -- Partition storage by user/asset/id; avoid hot globals -- Minimize number of storage writes per call; batch in-memory, commit once -- Avoid loops with storage writes; switch to pull-based flows +- Partition storage by user, asset, or ID, and avoid hot globals +- Minimize the number of storage writes per call: batch work in memory and commit once +- Avoid loops with storage writes, and switch to pull-based flows - Favor precompiles for supported features - Apply standard gas optimizations (`external`, packing, `unchecked`, memory-first) -## Storage Design Patterns +## Storage design patterns ### Partition state by key -Isolate per-user/per-asset data instead of centralizing writes. +Isolate per-user and per-asset data instead of centralizing writes. ```solidity // Good: disjoint keys by user and id enable parallelism @@ -53,13 +53,13 @@ function updatePosition(uint256 id, int256 delta) external { Anti-patterns: - Writing a global `totalVolume += amount;` in every transaction -- Maintaining a single on-chain queue or registry updated by most calls +- Maintaining a single on-chain queue or registry that most calls update -Prefer computing aggregates off-chain from events, or update them periodically via a dedicated maintenance transaction and place them in the calldata. +Prefer to compute aggregates off-chain from events. Alternatively, update them periodically through a dedicated maintenance transaction and place them in the calldata. ### Prefer pull payments -Avoid writing to many recipients in a single transaction. Emit events and let recipients `withdraw()` when needed. +Avoid writing to many recipients in a single transaction. Emit events, and let recipients call `withdraw()` when they need to. ```solidity // Better: users pull their own rewards, isolating writes to their key @@ -79,30 +79,30 @@ function withdraw() external { ### Avoid large storage writes in loops -If you must process many items, keep work in memory and commit a compact result, or split work across multiple transactions keyed by different ids. +If you must process many items, keep the work in memory and commit a compact result. Alternatively, split the work across multiple transactions keyed by different IDs. -## Gas-Efficient Solidity Practices +## Gas-efficient Solidity practices -- **Use `external` for externally called functions**; mark pure/read-only with `pure`/`view`. -- **Pack variables** to share storage slots (e.g., multiple `uint8` in one slot). +- **Use `external` for externally called functions**. Mark pure and read-only functions with `pure` and `view`. +- **Pack variables** to share storage slots (for example, multiple `uint8` values in one slot). - Prefer **`bytes32` over `string`** when applicable. - **Cache array lengths** in loops and short-circuit cheap conditions first. - Use **`unchecked`** for arithmetic when overflow is impossible. -- Prefer **memory** over storage for temporary data; commit only final values. +- Prefer **memory** over storage for temporary data, and commit only final values. -These reduce gas and often reduce storage touches, which also improves parallelism. +These practices reduce gas and often reduce storage access, which also improves parallelism. -## Leverage Sei Precompiles +## Leverage Sei precompiles -Sei provides precompiled contracts for common functionality—cheaper and simpler than custom Solidity equivalents: +Sei has precompiled contracts for common functionality. They are cheaper and simpler than custom Solidity equivalents: - [JSON](/evm/precompiles/json) (`0x1003`) - [P256](/evm/precompiles/p256-precompile) (`0x1011`) See [precompile examples](/evm/precompiles/example-usage) for quick starts. -## Testing and Analysis +## Testing and analysis -- Use Foundry/Hardhat gas reporters to track changes per function. -- Benchmark under concurrent load to detect hot keys (addresses/ids) that serialize execution. +- Use Foundry or Hardhat gas reporters to track changes per function. +- Benchmark under concurrent load to detect hot keys (addresses or IDs) that serialize execution. - Inspect execution with [JavaScript tracers](/evm/tracing/javascript-tracers) and runtime logs. diff --git a/evm/best-practices/zeroing-stale-state.mdx b/evm/best-practices/zeroing-stale-state.mdx index f3d4e37..f832530 100644 --- a/evm/best-practices/zeroing-stale-state.mdx +++ b/evm/best-practices/zeroing-stale-state.mdx @@ -3,19 +3,19 @@ title: 'Zeroing Out Stale State' description: 'Strategies for clearing unused EVM storage on Sei to reduce state growth and improve node performance.' keywords: ['sei evm', 'state management', 'gas refund', 'storage clearing', 'contract optimization', 'stale state'] --- -Zeroing out state means setting stored contract values back to their defaults (e.g., `0`, `false`, `address(0)`) by writing `non-zero → zero` into EVM storage slots. +Zeroing out state means setting stored contract values back to their defaults, such as `0`, `false`, or `address(0)`. To do this, you write `non-zero → zero` into EVM storage slots. -## Why Zero Out State +## Why zero out state -Non-zero storage contributes to global state size. Clearing stale state reduces state growth pressure and can improve node operations, sync, and restart behavior. This matters especially on high-throughput chains like Sei where state growth can be aggressive. +Non-zero storage adds to the global state size. When you clear stale state, you reduce pressure from state growth and can improve node operations, sync, and restart behavior. This matters especially on high-throughput chains such as Sei, where state growth can be aggressive. Clearing a non-zero storage slot to zero earns a **4,800 gas refund** per slot. -## Clearing State Variables, Arrays, and Maps +## Clearing state variables, arrays, and maps -### Simple Fixed-Size State +### Simple fixed-size state -For value types and fixed-size arrays, use `delete` (or assign the default) to reset values to their defaults (`0`, `address(0)`, `false`). +For value types and fixed-size arrays, use `delete` or assign the default value. This resets the values to their defaults (`0`, `address(0)`, `false`). ```solidity uint256 public value; @@ -31,13 +31,13 @@ function clearSimple() external { } ``` -### Dynamic Arrays +### Dynamic arrays -Using `delete` on a dynamic array resets its length to 0 and clears all elements, but this can be too expensive for large arrays and risks hitting the block gas limit. +If you use `delete` on a dynamic array, it resets the length to 0 and clears all elements. For large arrays, this can be too expensive and can hit the block gas limit. -The safer approach is **batched clearing** by repeatedly calling `pop()` in chunks. +The safer approach is **batched clearing**: call `pop()` repeatedly, in chunks. -If a dynamic array might exceed **~500 elements**, use batched clearing to avoid running out of gas. +If a dynamic array might exceed **approximately 500 elements**, use batched clearing so that you do not run out of gas. ```solidity uint256[] public dynamicArr; @@ -53,9 +53,9 @@ function batchClear(uint256 batchSize) external { ### Mappings -You can't iterate a mapping, so you can't clear it unless you can enumerate keys. The main strategy is to **maintain an index of keys** (e.g., a `holders[]` array plus an `_isHolder` flag) whenever you write, then later delete mapping entries in batches by iterating that key list. +You cannot iterate over a mapping, so you cannot clear it unless you can enumerate its keys. The main strategy is to **maintain an index of keys** whenever you write. For example, use a `holders[]` array plus an `_isHolder` flag. Later, iterate over that key list to delete mapping entries in batches. -Maintaining an index costs roughly one extra `SSTORE` per write (Sei: ~72,000 gas; see [EVM Differences](/evm/differences-with-ethereum#sstore-gas-cost)), but makes future clearing possible. +Maintaining an index costs roughly one extra `SSTORE` per write, but it makes future clearing possible. On Sei, that extra write costs approximately 72,000 gas. See [EVM differences](/evm/differences-with-ethereum#sstore-gas-cost). ```solidity mapping(address => uint256) public balances; @@ -80,37 +80,37 @@ function batchClearBalances(uint256 start, uint256 end) external { } ``` -## Strategies for Existing Contracts +## Strategies for existing contracts -### External Cleaner Contract +### External cleaner contract -If you control permissions and the original contract has callable setters/entrypoints, deploy a separate "cleaner" contract that loops through user/key batches and calls the original contract to set values to zero. +If you control permissions and the original contract has callable setters or entry points, deploy a separate "cleaner" contract. The cleaner loops through batches of users or keys and calls the original contract to set values to zero. -This only clears state reachable through the **public/external interface**. Truly internal or private state with no setters can't be touched. +This method clears only state that is reachable through the **public or external interface**. It cannot change internal or private state that has no setters. See [Appendix A](#appendix-a---external-cleaner-contract) for example code. -### Proxy / Upgradeable Contract +### Proxy / upgradeable contract -If you have a proxy or upgradeable contract, this is the best-case scenario. Upgrade the implementation to add reset functions while **preserving storage layout**, run batched resets, then optionally upgrade again to remove the reset logic. +If you have a proxy or upgradeable contract, this is the best case. Upgrade the implementation to add reset functions, and **preserve the storage layout** when you do. Run the batched resets. Then you can upgrade again to remove the reset logic. See [Appendix B](#appendix-b---proxyupgradeable-contract) for example code. -### Reconstruct Keys from Event Logs +### Reconstruct keys from event logs -If contract writes emit events (which is common), scan historical logs to recover mapping keys (e.g., recipients from `Transfer` events), deduplicate them, and pass that list into a batch-clear call. +Contract writes often emit events. If they do, scan the historical logs to recover mapping keys, such as recipients from `Transfer` events. Remove duplicates, and pass the list to a batch-clear call. -### Use a Subgraph or Custom Indexer +### Use a subgraph or custom indexer -For complex or nested state, use [The Graph](https://thegraph.com/) or your own indexer to build a full set of non-zero keys/entities off-chain, then feed the resulting address/key list into on-chain batch clearing. This moves enumeration complexity off-chain while the on-chain work is just applying clears. +For complex or nested state, use [The Graph](https://thegraph.com/) or your own indexer to build a full set of non-zero keys or entities off-chain. Then pass the resulting list of addresses or keys to the on-chain batch clearing. This moves the enumeration complexity off-chain, and the on-chain work only applies the clears. -### Brute-Force via Direct Storage Reads +### Brute-force via direct storage reads -If you have a candidate universe of keys (e.g., all addresses that ever interacted), compute each mapping slot (`keccak256(key, slot)` — tools like `cast index` do this), read storage via RPC, and keep only the non-zero keys to clear. +If you have a candidate set of keys, such as all addresses that ever interacted with the contract, compute each mapping slot (`keccak256(key, slot)`). Tools such as `cast index` do this for you. Read the storage through RPC, and keep only the non-zero keys to clear. -This approach is tedious and RPC-heavy but works when events are missing or unreliable. +This approach is tedious and RPC-heavy, but it works when events are missing or unreliable. -## Appendix A - External Cleaner Contract +## Appendix A - External cleaner contract ```solidity // SPDX-License-Identifier: MIT @@ -135,7 +135,7 @@ contract StateCleaner { } ``` -## Appendix B - Proxy/Upgradeable Contract +## Appendix B - Proxy/upgradeable contract ```solidity // SPDX-License-Identifier: MIT diff --git a/evm/bridging/layerzero.mdx b/evm/bridging/layerzero.mdx index 9ae321e..1736f93 100644 --- a/evm/bridging/layerzero.mdx +++ b/evm/bridging/layerzero.mdx @@ -6,15 +6,15 @@ keywords: ['layerzero', 'cross-chain', 'omnichain', 'bridging', 'OFT', 'token br --- ## Overview -This guide provides a comprehensive, step-by-step tutorial for integrating LayerZero V2 with the SEI blockchain. By the end of this guide, you will understand how to create, deploy, and manage omnichain tokens that can seamlessly move between SEI and any other LayerZero-supported blockchain. +This step-by-step guide shows how to integrate LayerZero V2 with Sei. By the end of the guide, you will know how to create, deploy, and manage omnichain tokens. These tokens can move between Sei and any other LayerZero-supported blockchain. -### What This Guide Covers +### What this guide covers -- **Understanding LayerZero**: Core concepts and architecture -- **Project Setup**: Creating a LayerZero-enabled project from scratch -- **Smart Contracts**: Building an Omnichain Fungible Token (OFT) with detailed explanations -- **Deployment & Configuration**: Step-by-step deployment to SEI and other chains -- **Cross-Chain Transfers**: Creating tasks and scripts for token transfers +- Core concepts and architecture of LayerZero +- Creating a LayerZero-enabled project from scratch +- Building an Omnichain Fungible Token (OFT), with detailed explanations +- Deploying and configuring the contracts on Sei and other chains, step by step +- Creating tasks and scripts for cross-chain token transfers ### Prerequisites @@ -25,27 +25,27 @@ This guide provides a comprehensive, step-by-step tutorial for integrating Layer ## What is LayerZero? -LayerZero is an **omnichain interoperability protocol** that enables secure, permissionless communication between different blockchains. Think of it as a universal translator that allows blockchains to talk to each other. +LayerZero is an omnichain interoperability protocol for secure, permissionless communication between different blockchains. Think of it as a universal translator that lets blockchains talk to each other. -### Core Concepts +### Core concepts -- **Endpoints**: Immutable smart contracts deployed on each blockchain that serve as entry/exit points for messages -- **Messages**: Data packets sent between blockchains containing instructions or information -- **Security Stack**: Customizable verification system ensuring message authenticity +- **Endpoints**: Immutable smart contracts on each blockchain that are the entry and exit points for messages +- **Messages**: Data packets, sent between blockchains, that contain instructions or information +- **Security Stack**: A customizable verification system that makes sure messages are authentic - **Omnichain Applications**: Smart contracts that can operate across multiple blockchains -### Key Applications +### Key applications -- **Omnichain Fungible Tokens (OFT)**: Tokens that exist across multiple chains with unified supply +- **Omnichain Fungible Tokens (OFT)**: Tokens that exist on multiple chains with a unified supply - **Omnichain NFTs (ONFT)**: NFTs that can move between blockchains - **Cross-chain DeFi**: Protocols that operate across multiple networks -- **Unified Governance**: DAOs that function across chains -- **Message Passing**: Send arbitrary data between blockchains +- **Unified governance**: DAOs that function across chains +- **Message passing**: Send arbitrary data between blockchains -## SEI Network Information +## Sei network information -**SEI Mainnet Configuration** +**Sei Mainnet configuration** - Network Name: SEI EVM - Chain ID: 1329 @@ -56,11 +56,11 @@ LayerZero is an **omnichain interoperability protocol** that enables secure, per -### Contract Deployments +### Contract deployments -The following are the official LayerZero V2 protocol contract addresses deployed on Sei networks. +These are the addresses of the official LayerZero V2 protocol contracts on Sei networks. - + | Contract | Address | | --- | --- | | EndpointV2 | [`0x1a44076050125825900e736c501f859c50fE728c`](https://seiscan.io/address/0x1a44076050125825900e736c501f859c50fE728c) | @@ -77,7 +77,7 @@ The following are the official LayerZero V2 protocol contract addresses deployed - + | DVN | Address | | --- | --- | | LayerZero Labs | [`0x6788f52439aca6bff597d3eec2dc9a44b8fee842`](https://seiscan.io/address/0x6788f52439aca6bff597d3eec2dc9a44b8fee842) | @@ -95,7 +95,7 @@ The following are the official LayerZero V2 protocol contract addresses deployed - + | Contract | Address | | --- | --- | | EndpointV2 | [`0x6C7Ab2202C98C4227C5c46f1417D81144DA716Ff`](https://testnet.seiscan.io/address/0x6C7Ab2202C98C4227C5c46f1417D81144DA716Ff) | @@ -108,33 +108,33 @@ The following are the official LayerZero V2 protocol contract addresses deployed -## Step 1: Project Setup +## Step 1: Project setup ### Project scaffold -LayerZero's CLI lets you spin up an OFT workspace in seconds: +LayerZero's CLI lets you create an OFT workspace in seconds: ```bash npx create-lz-oapp@latest # choose → "OFT example" ``` -The wizard creates a repo with Hardhat + Foundry, sample contracts, tests and LayerZero helper scripts. +The wizard creates a repo with a Hardhat and Foundry setup, sample contracts, tests, and LayerZero helper scripts. ### Add private keys -Rename `.env.example` file to `.env` and update it with needed configurations: +Rename the `.env.example` file to `.env`. Then add the configuration values that you need: ```bash title=".env" PRIVATE_KEY=your_private_key ``` -At a minimum, you need to have the `PRIVATE_KEY`. RPC URLs are optional, but strongly recommended. If you don't provide them, public RPCs will be used, but public RPCs can be unreliable or slow, leading to long waiting times for transactions to be confirmed or, at worst, cause your transactions to fail. +At a minimum, you need the `PRIVATE_KEY`. RPC URLs are optional, but strongly recommended. If you do not set them, the project uses public RPCs. Public RPCs can be unreliable or slow. Your transactions can then take a long time to confirm or, at worst, fail. -## Step 2: Configure Networks +## Step 2: Configure networks ### Hardhat network config -Update your `hardhat.config.ts` file to include the networks you want to deploy your contracts to: +In `hardhat.config.ts`, add the networks that you want to deploy your contracts to: ```typescript title="hardhat.config.ts" networks: { @@ -156,7 +156,7 @@ networks: { ### LayerZero wiring config -Modify your `layerzero.config.ts` file to include the chains and channel security settings you want for each connection: +In `layerzero.config.ts`, add the chains and the channel security settings that you want for each connection: ```typescript title="layerzero.config.ts" import { EndpointId } from '@layerzerolabs/lz-definitions'; @@ -222,17 +222,17 @@ export default async function () { ``` -It is strongly recommended to review [LayerZero's Channel Security Model](https://docs.layerzero.network/v2/concepts/protocol/message-security#layerzero's-channel-security-model) and understand the impact of each of these configuration settings. +Review [LayerZero's Channel Security Model](https://docs.layerzero.network/v2/concepts/protocol/message-security#layerzero's-channel-security-model) to understand the impact of each of these configuration settings. -See [Next Steps](#next-steps) to review the available providers and security settings. +To review the available providers and security settings, see [Next steps](#next-steps). -## Step 3: Create Utility Tasks +## Step 3: Create utility tasks -Before deployment, let's create a utility task for minting tokens that we'll need later. +Before you deploy, create a utility task that mints tokens. You need this task later. -### Create Minting Task +### Create minting task Create `tasks/mint.ts`: @@ -267,9 +267,9 @@ task('mint', 'Mint tokens to an address') }); ``` -### Update Hardhat Configuration +### Update Hardhat configuration -Now update your `hardhat.config.ts` to import the mint task: +Update your `hardhat.config.ts` file to import the mint task: ```typescript title="hardhat.config.ts" // Get the environment configuration from .env file @@ -347,18 +347,18 @@ const config: HardhatUserConfig = { export default config; ``` -**Important**: You must create and import the mint task before deployment, otherwise Hardhat will throw an error when trying to resolve the task dependencies during compilation. +Create and import the mint task before you deploy. Otherwise, Hardhat throws an error when it tries to resolve the task dependencies during compilation. -## Step 4: Smart Contract Development +## Step 4: Smart contract development ### The token contract -The OFT contract handles all cross-chain logic automatically. When tokens are sent: +The OFT contract handles all cross-chain logic automatically. When you send tokens: -1. **Source Chain**: Burns tokens from sender's balance -2. **LayerZero Protocol**: Verifies and relays the message -3. **Destination Chain**: Mints equivalent tokens to recipient +1. **Source chain**: Burns the tokens from the sender's balance +2. **LayerZero protocol**: Verifies and relays the message +3. **Destination chain**: Mints equivalent tokens to the recipient @@ -385,25 +385,25 @@ contract MyOFT is OFT { ``` -The OFT contract uses the ERC20 token standard. You may want to add a `mint(...)` function in the `constructor(...)` or contract body if this is your first time deploying an OFT. If you have an existing ERC20 token, you will want to use an OFT Adapter contract. +The OFT contract uses the ERC-20 token standard. If this is your first time deploying an OFT, you may want to add a `mint(...)` function in the `constructor(...)` or contract body. If you have an existing ERC-20 token, use an OFT Adapter contract. -You can read the general [OFT Quickstart](https://docs.layerzero.network/v2/developers/evm/oft/quickstart) for a better understanding of how OFTs work and what contracts to use. +To learn more about how OFTs work and which contracts to use, you can read the general [OFT Quickstart](https://docs.layerzero.network/v2/developers/evm/oft/quickstart). -### Understanding OFT Functions +### Understanding OFT functions -Key inherited functions from the OFT contract: +Your contract inherits these main functions from the OFT contract: | Function | Description | | --- | --- | -| `send()` | Initiates cross-chain token transfer | -| `quoteSend()` | Estimates fees for transfer | +| `send()` | Starts a cross-chain token transfer | +| `quoteSend()` | Estimates the fees for a transfer | | `_lzSend()` | Internal function that sends the message | | `_lzReceive()` | Internal function that receives messages | -## Step 5: Deployment Process +## Step 5: Deployment process ### Deploy @@ -411,13 +411,13 @@ Key inherited functions from the OFT contract: npx hardhat lz:deploy # choose sei ``` -You will be presented with a list of networks to deploy to. +The command shows a list of networks to deploy to. -Fund your deployer with native gas tokens beforehand. +Fund your deployer with native gas tokens before you deploy. -## Step 6: Wire the Contracts +## Step 6: Wire the contracts -After deployment, contracts need to be connected: +After deployment, connect the contracts: ### Connect the chains @@ -425,32 +425,32 @@ After deployment, contracts need to be connected: npx hardhat lz:oapp:wire --oapp-config layerzero.config.ts ``` -### Verify Configuration +### Verify configuration -Verify peers: +Verify the peers: ```bash npx hardhat lz:oapp:peers:get --oapp-config layerzero.config.ts ``` -This command will show you the current LayerZero wiring configuration, including the connected chains and their peer addresses. +This command shows the current LayerZero wiring configuration, including the connected chains and their peer addresses. -## Step 7: Mint Initial Tokens +## Step 7: Mint initial tokens -Before transferring, you need tokens to send. Let's mint some tokens on SEI: +Before you transfer, you need tokens to send. Mint some tokens on Sei: ```bash # Mint 10,000 tokens to your address on SEI npx hardhat mint --to 0xYourAddress --amount 10000 --network sei-mainnet ``` -## Step 8: Transfer Tokens Cross-Chain +## Step 8: Transfer tokens cross-chain ### Calling send -Since the `send` logic has already been defined, we'll instead view how the function should be called. +The OFT contract already defines the `send` logic, so this section shows how to call the function. -#### Option 1: Hardhat Task +#### Option 1: Hardhat task Create `tasks/sendOFT.ts`: @@ -536,14 +536,14 @@ task('lz:oft:send', 'Sends tokens from either OFT or OFTAdapter') }); ``` -Don't forget to import the task in your `hardhat.config.ts` (if not already added): +If you have not already done so, import the task in your `hardhat.config.ts` file: ```typescript // Add this import to hardhat.config.ts (should already be there from Step 3) import './tasks/sendOFT'; ``` -**Execute the transfer:** +Send the tokens: ```bash # Send 100 tokens from SEI to Optimism (EID: 30111) @@ -554,7 +554,7 @@ npx hardhat lz:oft:send \ --network sei-mainnet ``` -#### Option 2: Foundry Script +#### Option 2: Foundry script Create `script/SendOFT.s.sol`: @@ -618,7 +618,7 @@ contract SendOFT is Script { } ``` -**Environment Setup:** +Set the environment variables and run the script: ```bash # Set environment variables @@ -632,46 +632,46 @@ forge script script/SendOFT.s.sol:SendOFT --rpc-url $RPC_URL_SEI --broadcast ## Step 9: Done! -You've issued an omnichain token and bridged it from Sei Mainnet to Optimism. Customize supply logic, fees, or add more chains by applying changes to the core contract, redeploying, and repeating the wiring step. +You issued an omnichain token and bridged it from Sei Mainnet to Optimism. To customize the supply logic or fees, or to add more chains, change the core contract. Then redeploy it and repeat the wiring step. -### Track Your Transaction +### Track your transaction -1. Visit https://layerzeroscan.com/tx/YOUR_TX_HASH -2. You'll see: +1. Go to https://layerzeroscan.com/tx/YOUR_TX_HASH +2. The page shows: - Source transaction - Message status - Destination transaction - Time elapsed -3. Check balances on both chains to confirm the transfer +3. Check the balances on both chains to confirm the transfer ## Troubleshooting -### Common Issues and Solutions +### Common issues and solutions -**Quote Send Reverts** +**Quote send reverts** -If your `quoteSend` call reverts, it usually means that your LayerZero wiring hasn't been fully configured or there's no default pathway for the chains you're trying to bridge. Here's how to diagnose and fix it: +If your `quoteSend` call reverts, there are two usual causes. Your LayerZero wiring is not fully configured, or there is no default pathway for the chains that you are trying to bridge. Diagnose and fix the problem as follows: -**1. Wiring Didn't Succeed:** +**1. Wiring did not succeed:** -Run the following to inspect your on‑chain wiring configuration: +Run this command to inspect your on-chain wiring configuration: ```bash npx hardhat lz:oapp:config:get --oapp-config layerzero.config.ts ``` -See that your source configuration has a valid send library, DVN address, and target eid. +Check that your source configuration has a valid send library, DVN address, and target EID. -**2. No Default Pathway:** +**2. No default pathway:** -LayerZero default settings should be considered placeholders. Sometimes the LayerZero defaults will contain a `LzDeadDVN`. Those entries indicate that a default pathway setting does not exist. +Treat the LayerZero default settings as placeholders. Sometimes the LayerZero defaults contain a `LzDeadDVN`. These entries show that a default pathway setting does not exist. -- **Check**: You can see if your configuration contains a LzDeadDVN by viewing the [Default Config Checker](https://layerzeroscan.com/tools/defaults?srcChainKey%5B0%5D=sei&version=V2&dstChainKey%5B0%5D=optimism) on LayerZero Scan. +- **Check**: To see if your configuration contains a LzDeadDVN, open the [Default Config Checker](https://layerzeroscan.com/tools/defaults?srcChainKey%5B0%5D=sei&version=V2&dstChainKey%5B0%5D=optimism) on LayerZero Scan. -- **Fix**: Open your `layerzero.config.ts` and under the relevant `pathways` entry, add working DVN providers (in the `[ requiredDVN[], [ optionalDVN[], threshold ] ]` section). +- **Fix**: Open your `layerzero.config.ts` file. Under the relevant `pathways` entry, add working DVN providers in the `[ requiredDVN[], [ optionalDVN[], threshold ] ]` section. -- Re-run your wiring command for the connections so that the wiring on both chains is live. +- Run the wiring command for the connections again so that the wiring is live on both chains. ```typescript [ @@ -683,14 +683,14 @@ LayerZero default settings should be considered placeholders. Sometimes the Laye ], ``` -Once you've updated your config, retry your `quoteSend` flow. It should now return a fee estimate instead of reverting. +After you update your config, retry your `quoteSend` flow. It should now return a fee estimate instead of reverting. -**Insufficient Gas** +**Insufficient gas** -If the transaction fails on the destination chain, try to increase the gas like this: +If the transaction fails on the destination chain, try to increase the gas: ```typescript // Increase gas in options @@ -699,35 +699,35 @@ let options = Options.newOptions().addExecutorLzReceiveOption(150000, 0).toBytes -## Next Steps +## Next steps -- **Add More Chains**: Expand to Arbitrum, Base, Polygon, etc. -- **Advanced Features**: Implement rate limiting, pausable transfers, fee collection -- **Composed Messages**: Execute actions after token arrival -- **Build a UI**: Create a frontend for easy transfers +- Add more chains, such as Arbitrum, Base, and Polygon. +- Implement advanced features, such as rate limiting, pausable transfers, and fee collection. +- Use composed messages to run actions after the tokens arrive. +- Build a frontend UI that makes transfers easy. -### Learn More +### Learn more -- See the [Configuring Pathways](https://docs.layerzero.network/v2/get-started/create-lz-oapp/configuring-pathways) section to learn more about managing your OFTs across the entire network mesh. -- See the [Available DVNs](https://docs.layerzero.network/v2/deployments/dvn-addresses?chains=sei) and [Executor](https://docs.layerzero.network/v2/deployments/deployed-contracts?chains=sei) to configure between. -- Learn how the protocol works by reading the [Core Concepts](https://docs.layerzero.network/v2/concepts/getting-started/what-is-layerzero) section. -- Learn more about how the OFT contract works on the EVM by reading the [OFT Quickstart](https://docs.layerzero.network/v2/developers/evm/oft/quickstart) in the EVM section. +- To learn more about how to manage your OFTs across the entire network mesh, see the [Configuring Pathways](https://docs.layerzero.network/v2/get-started/create-lz-oapp/configuring-pathways) section. +- To choose which DVNs and executor to configure, see [Available DVNs](https://docs.layerzero.network/v2/deployments/dvn-addresses?chains=sei) and [Executor](https://docs.layerzero.network/v2/deployments/deployed-contracts?chains=sei). +- To learn how the protocol works, read the [Core Concepts](https://docs.layerzero.network/v2/concepts/getting-started/what-is-layerzero) section. +- To learn more about how the OFT contract works on the EVM, read the [OFT Quickstart](https://docs.layerzero.network/v2/developers/evm/oft/quickstart) in the EVM section. ## Resources -- **LayerZero Documentation**: https://docs.layerzero.network/v2 +- **LayerZero documentation**: https://docs.layerzero.network/v2 - **LayerZero Scan**: https://layerzeroscan.com/ -- **SEI Explorer**: https://seiscan.io +- **Sei explorer**: https://seiscan.io ## Summary -You've successfully: +In this guide, you: -- ✅ Created an Omnichain Fungible Token project -- ✅ Configured networks and LayerZero pathways -- ✅ Deployed contracts to multiple chains -- ✅ Connected the deployments via LayerZero wiring -- ✅ Created tasks for cross-chain token transfers -- ✅ Learned how LayerZero enables omnichain applications +- Created an Omnichain Fungible Token project +- Configured networks and LayerZero pathways +- Deployed contracts to multiple chains +- Connected the deployments through LayerZero wiring +- Created tasks for cross-chain token transfers +- Learned how LayerZero enables omnichain applications -Your tokens can now move freely between SEI and any connected chain, maintaining a unified supply and enabling true cross-chain functionality! +Your tokens can now move between Sei and any connected chain, and the total supply stays unified. diff --git a/evm/bridging/thirdweb.mdx b/evm/bridging/thirdweb.mdx index 8802bcd..d3630b9 100644 --- a/evm/bridging/thirdweb.mdx +++ b/evm/bridging/thirdweb.mdx @@ -4,28 +4,28 @@ sidebarTitle: 'Thirdweb' description: 'Comprehensive guide on enabling onramps, swapping & bridging on Any EVM Chain on Sei. Learn key concepts, commands, and best practices.' keywords: ['thirdweb', 'onramps', 'swapping', 'bridging', 'cross-chain', 'payments', 'sei'] --- -[**Payments**](https://thirdweb.com/payments?utm_source=sei&utm_medium=documentation&utm_campaign=chain_docs) is a comprehensive Web3 payment solution to help you monetize any app or game. +thirdweb [Payments](https://thirdweb.com/payments?utm_source=sei&utm_medium=documentation&utm_campaign=chain_docs) is a Web3 payment solution that helps you monetize any app or game. -With Payments, your users can **onramp, bridge, and swap** on any EVM chain — with any EVM token or fiat — thanks to its **automatic cross-chain routing**. +With Payments, your users can onramp, bridge, and swap on any EVM chain, with any EVM token or with fiat. Automatic cross-chain routing makes this possible. -Plus, developers can **earn from day one** using the **fee-sharing mechanism** and **easy implementation**. +Payments is easy to implement, and its fee-sharing mechanism lets you earn from day one. -## Payments Features +## Payments features - Let users pay for assets in any EVM token on any EVM chain -- Automatic cross-chain routing for seamless transactions -- Earn from day one with fee-sharing mechanism -- Access ready-made UI component for easy implementation +- Automatic cross-chain routing of transactions +- Earn from day one with the fee-sharing mechanism +- Access a ready-made UI component for easy implementation -[Learn more in the full documentation on thirdweb’s Payments](https://portal.thirdweb.com/payments?utm_source=sei&utm_medium=documentation&utm_campaign=chain_docs) +[Learn more in the full thirdweb Payments documentation](https://portal.thirdweb.com/payments?utm_source=sei&utm_medium=documentation&utm_campaign=chain_docs) -## Get Started +## Get started [How to get started with Payments](https://portal.thirdweb.com/payments?utm_source=sei&utm_medium=documentation&utm_campaign=chain_docs) -## See Payments in Action +## See Payments in action -Want to see how Payments works? Check it out under the hood +This code example shows how Payments works: ```jsx import { createThirdwebClient } from 'thirdweb'; @@ -54,4 +54,4 @@ function Example() { } ``` -[**See how Payments works in the playground**](https://playground.thirdweb.com/payments?utm_source=sei&utm_medium=documentation&utm_campaign=chain_docs) +[See how Payments works in the playground](https://playground.thirdweb.com/payments?utm_source=sei&utm_medium=documentation&utm_campaign=chain_docs) diff --git a/evm/building-a-frontend.mdx b/evm/building-a-frontend.mdx index fe08e95..5ed64de 100644 --- a/evm/building-a-frontend.mdx +++ b/evm/building-a-frontend.mdx @@ -4,90 +4,90 @@ sidebarTitle: 'Building a Frontend' description: 'Comprehensive guide on Building a Frontend for Sei EVM. Learn key concepts, commands, and best practices.' keywords: ['frontend development', 'dApp', 'ethers.js', 'viem', 'wagmi', 'react', 'wallet connection', 'sei'] --- -Developing the frontend of a dApp on Sei EVM involves connecting to wallets, interacting with the blockchain via RPC endpoints, and signing and broadcasting transactions. This tutorial will demonstrate how to build a simple ERC20 token interface using three popular libraries: +To build the frontend of a dApp on Sei EVM, you connect to wallets and interact with the blockchain through RPC endpoints. You also sign and broadcast transactions. This tutorial shows how to build a simple ERC20 token interface with three popular libraries: -1. [**Ethers.js**](https://docs.ethers.org/v6/) - A complete and compact library for interacting with - EVM blockchains. Known for its simplicity and extensive functionality. -2. [**Viem**](https://viem.sh/docs/getting-started) - A lightweight and modular TypeScript interface for Ethereum -3. [**Wagmi**](https://wagmi.sh/) - A React hooks library built on top of Viem that simplifies wallet - connection and interaction. Provides hooks for interacting with Ethereum - wallets and contracts for use with modern frontend libraries and frameworks. +1. [**ethers.js**](https://docs.ethers.org/v6/): A complete and compact library for interacting with + EVM blockchains. It is known for its simplicity and extensive functionality. +2. [**viem**](https://viem.sh/docs/getting-started): A lightweight and modular TypeScript interface for Ethereum. +3. [**wagmi**](https://wagmi.sh/): A React hooks library, built on top of viem, that simplifies wallet + connection and interaction. It has hooks that modern frontend libraries and frameworks can use + to interact with Ethereum wallets and contracts. -We'll implement the same functionality using each library so you can compare their approaches and choose the one that best fits your development style. +The tutorial implements the same functionality with each library. You can then compare their approaches and choose the one that best fits your development style. -**Deploy to Testnet First** +**Deploy to Sei Testnet first** -It is highly recommended that you deploy to Sei Testnet first and verify everything works as expected before committing to Sei Mainnet. Doing so helps you catch bugs early, avoid unnecessary gas costs, and keep your users safe. +It is highly recommended that you deploy to Sei Testnet first. Verify that everything works as expected before you commit to Sei Mainnet. This helps you catch bugs early, avoid unnecessary gas costs, and keep your users safe. -## When to Use Each Library +## When to use each library -### Ethers.js +### ethers.js -Ethers.js is ideal for developers who want a comprehensive, battle-tested library with straightforward API design. It's great for both simple and complex dApps, especially when you're not using React or need custom state management. +ethers.js is ideal for developers who want a complete, battle-tested library with a straightforward API design. It works well for both simple and complex dApps, especially when you do not use React or you need custom state management. - **Pros**: - - Comprehensive and easy-to-use API - - Well-documented with a large community + - Complete and easy-to-use API + - Well documented, with a large community - Works well with both TypeScript and JavaScript - All-in-one solution for wallet connection and contract interaction - **Cons**: - - Larger bundle size compared to Viem - - Not specifically designed for React hooks integration + - Larger bundle size than viem + - Not designed specifically for integration with React hooks -### Viem +### viem -Viem is perfect for developers who want fine-grained control over their blockchain interactions and appreciate a modular, lightweight approach. It's a good choice when bundle size matters and when you have specific requirements for how contract interactions should work. +viem suits developers who want fine-grained control over their blockchain interactions and prefer a modular, lightweight approach. It is a good choice when bundle size matters and when you have specific requirements for how contract interactions should work. - **Pros**: - Lightweight and modular - Excellent TypeScript support with better type safety - - Lower-level API gives more control + - Lower-level API that gives more control - Smaller bundle size - **Cons**: - Steeper learning curve - Requires more boilerplate code for some operations - Requires separate handling for wallet connection and contract interactions -### Wagmi +### wagmi -Wagmi is the best choice for React developers building dApps who want to leverage React's state management capabilities. It abstracts away much of the complexity of blockchain interactions via hooks, making it easy to build reactive UIs that respond to chain state. +wagmi is the best choice for React developers who build dApps and want to use React's state management capabilities. Its hooks hide much of the complexity of blockchain interactions. This makes it easy to build reactive UIs that respond to chain state. - **Pros**: - - React-specific hooks for seamless integration + - React-specific hooks - Handles complex state management for you - - Built on top of Viem, combining its benefits - - Convenient caching and auto-refreshing for contract data + - Built on top of viem, so it shares the benefits of viem + - Convenient caching and automatic refreshing of contract data - **Cons**: - Only works with React - Adds another dependency layer - - Opinionated about how data should be managed in your app + - Opinionated about how you should manage data in your app ## Requirements -Before starting, ensure you have: +Before you start, make sure that you have: -- Node.js & NPM installed -- One of the Sei wallets listed [here](/learn/wallets) +- Node.js and npm installed +- A wallet from the [list of Sei wallets](/learn/wallets) -## Creating a React Project +## Creating a React project -Start by creating a new React project using Vite's TypeScript template for streamlined development: +Create a new React project with Vite's TypeScript template: ```bash npm create vite@latest sei-token-interface -- --template react-ts ``` -This command creates a new folder with a React project using TypeScript. Open `sei-token-interface` in your favorite IDE. +This command creates a new folder with a TypeScript React project. Open `sei-token-interface` in your preferred IDE. -This tutorial uses TypeScript. If you're not using TypeScript, you can easily adjust by removing the types. +This tutorial uses TypeScript. If you do not use TypeScript, you can adjust the code by removing the types. -## Project Structure +## Project structure -For clarity, we'll create separate components for each library implementation. First, let's set up the project structure: +For clarity, each library implementation has its own component. First, set up the project structure: ```bash cd sei-token-interface @@ -100,11 +100,11 @@ touch src/shared/constants.ts touch src/wagmi.ts ``` -## Defining the ERC20 Contract Details +## Defining the ERC20 contract details -Make sure to deploy your ERC20 token contract first — for example with [Hardhat](/evm/evm-hardhat) or [Foundry](/evm/evm-foundry), or generate one with the [contract wizard](/evm/evm-wizard) (see also [deploy & verify](/evm/evm-parity/examples/deploy-verify)) — and replace `TOKEN_CONTRACT_ADDRESS` in the constants file with your actual deployed contract address, and update the RPC URL in the Sei chain configuration. You can find a list of existing ERC20 contracts on Sei Mainnet here: [Sei Assets](https://seiscan.io/tokens) +First, deploy your ERC20 token contract. For example, use [Hardhat](/evm/evm-hardhat) or [Foundry](/evm/evm-foundry), or generate a contract with the [contract wizard](/evm/evm-wizard) (see also [deploy and verify](/evm/evm-parity/examples/deploy-verify)). Then replace `TOKEN_CONTRACT_ADDRESS` in the constants file with the address of your deployed contract. Also update the RPC URL in the Sei chain configuration. For a list of existing ERC20 contracts on Sei Mainnet, see [Sei Assets](https://seiscan.io/tokens). -Let's create a shared constants file for our project: +Create a shared constants file for the project: ```tsx title="src/shared/constants.ts" // Constants used across different implementations @@ -222,7 +222,7 @@ export const ERC20_ABI = [ export const TOKEN_CONTRACT_ADDRESS = '0xYourTokenContractAddress'; ``` -## Option 1: Ethers.js Implementation +## Option 1: ethers.js implementation Install ethers.js first: @@ -230,13 +230,13 @@ Install ethers.js first: npm install ethers ``` -Let's start with the Ethers.js implementation: +Start with the ethers.js implementation. The component does these things: -- Checks for any EVM compatible wallet extension. -- Establishes a connection to Sei Mainnet via the connected wallet, - using ethers.js BrowserProvider. -- Creates an ethers.js contract instance with the signer from the wallet, - setting it in the contract state for later use. +- Checks for any EVM-compatible wallet extension. +- Connects to Sei Mainnet through the connected wallet, with the ethers.js + `BrowserProvider`. +- Creates an ethers.js contract instance with the signer from the wallet. + It stores the instance in the contract state for later use. ```tsx title="src/components/EthersInterface.tsx" import { useState, useEffect } from 'react'; @@ -375,15 +375,15 @@ export function EthersInterface() { } ``` -## Option 2: Viem Implementation +## Option 2: viem implementation -Install Viem first: +Install viem first: ```bash npm install viem ``` -Now implement the Viem interface: +Now implement the viem interface: ```tsx title="src/components/ViemInterface.tsx" import { useState, useEffect } from 'react'; @@ -553,15 +553,15 @@ export function ViemInterface() { } ``` -## Option 3: Wagmi Implementation +## Option 3: wagmi implementation -Install Wagmi and configure it: +Install wagmi and configure it: ```bash npm install wagmi viem @tanstack/react-query ``` -First, let's create a Wagmi configuration file: +First, create a wagmi configuration file: ```tsx title="src/wagmi.ts" import { http, createConfig } from 'wagmi'; @@ -578,7 +578,7 @@ export const config = createConfig({ }); ``` -Now implement the Wagmi interface: +Now implement the wagmi interface: ```tsx title="src/components/WagmiInterface.tsx" import { useState, useEffect } from 'react'; @@ -695,7 +695,7 @@ export function WagmiInterface() { } ``` -## Updating the Main App to Display all Implementations +## Updating the main app to display all implementations Now update your `App.tsx` to include all three interface options: @@ -753,9 +753,9 @@ function App() { export default App; ``` -## Polyfills for Browser Environment +## Polyfills for browser environment -When developing frontend applications for the blockchain, you might need polyfills for Node.js-specific features like `Buffer`. Add these polyfills to your project: +When you develop frontend applications for the blockchain, you might need polyfills for Node.js-specific features, such as `Buffer`. Add these polyfills to your project: ```tsx title="src/main.tsx" import React from 'react'; @@ -778,17 +778,17 @@ ReactDOM.createRoot(document.getElementById('root')!).render( ); ``` -## Running the Application +## Running the application -To see your app in action, run: +To start your app, run this command: ```bash npm run dev ``` -This will start a local development server, at `http://localhost:5173`. You can toggle between the different library implementations to see how each one works. +This command starts a local development server at `http://localhost:5173`. You can switch between the library implementations to see how each one works. -To build your application, run: +To build your application, run this command: ```bash npm run build @@ -800,4 +800,4 @@ Then preview the production build locally: npm run preview ``` -This serves the built app at `http://localhost:4173` so you can verify it before deploying. To go live, deploy the contents of the `dist` directory to any static hosting provider. +This command serves the built app at `http://localhost:4173`, so you can verify it before you deploy. To go live, deploy the contents of the `dist` directory to any static hosting provider. diff --git a/evm/changelog.mdx b/evm/changelog.mdx index ffcce20..d926e02 100644 --- a/evm/changelog.mdx +++ b/evm/changelog.mdx @@ -6,18 +6,18 @@ keywords: ['changelog', 'updates', 'releases', 'protocol upgrades', 'sei chain'] import { Changelog } from '/snippets/changelog.jsx'; -Stay up-to-date with the latest changes, improvements, and new features in Sei. +Stay up to date with the latest changes, improvements, and new features in Sei. This changelog is automatically synced from the [sei-chain repository](https://github.com/sei-protocol/sei-chain/blob/main/CHANGELOG.md). For the most up-to-date information, you can also view the changelog directly on GitHub. -**Stay Updated** +**Stay updated** -Want to be notified of new releases? **Watch** the [sei-protocol/sei-chain](https://github.com/sei-protocol/sei-chain) repository on GitHub or follow the release announcements in the [Sei Tech Chat](https://t.me/+KZdhZ1eE-G01NmZk). +To get notifications about new releases, **Watch** the [sei-protocol/sei-chain](https://github.com/sei-protocol/sei-chain) repository on GitHub. You can also follow the release announcements in the [Sei Tech Chat](https://t.me/+KZdhZ1eE-G01NmZk). -## Latest Changes +## Latest changes diff --git a/evm/debugging-contracts.mdx b/evm/debugging-contracts.mdx index 3ee67ed..f1b3d35 100644 --- a/evm/debugging-contracts.mdx +++ b/evm/debugging-contracts.mdx @@ -8,23 +8,23 @@ import { RunSnippet } from '/snippets/run-snippet.jsx'; ## Overview -Debugging EVM transactions on Sei requires understanding both the transaction creation process and how to analyze transaction behavior. This guide covers advanced debugging techniques using transaction template generation, analysis tools, and comprehensive transaction inspection methods to help developers identify and resolve issues in their EVM interactions. +To debug EVM transactions on Sei, you need to understand both how transactions are created and how to analyze their behavior. This guide covers advanced debugging techniques: transaction template generation, analysis tools, and transaction inspection methods. Use them to find and fix issues in your EVM interactions. -## Transaction Template Generation +## Transaction template generation -The `--generate-only` flag transforms any Sei CLI transaction command into a template generator, creating complete transaction structures without broadcasting them. Through the `--generate-only` flag and Foundry's `cast` tool, developers can craft, analyze, and debug transactions across the EVM environment. +The `--generate-only` flag turns any `seid` transaction command into a template generator. The command creates a complete transaction structure but does not broadcast it. With the `--generate-only` flag and Foundry's `cast` tool, you can build, analyze, and debug transactions in the EVM environment. -### Basic Command Pattern +### Basic command pattern -The general pattern follows this structure: +The general command pattern is: ```bash seid tx --from --evm-rpc http://url-to-sei-evm-rpc --generate-only ``` -### Generating EVM Transaction Templates +### Generating EVM transaction templates -To generate an EVM transaction template, use the `evm` module with `--generate-only`. Here's an example sending SEI to another EVM address: +To generate an EVM transaction template, use the `evm` module with `--generate-only`. This example sends SEI to another EVM address: ```bash seid tx evm send 0xRecipientAddress 1000000000000000000 \ @@ -35,20 +35,20 @@ seid tx evm send 0xRecipientAddress 1000000000000000000 \ --generate-only ``` -This command returns a transaction template that you can analyze before broadcasting. The template includes all transaction details without executing the actual transaction. +This command returns a transaction template that you can analyze before you broadcast it. The template includes all transaction details, but the command does not execute the transaction. --- -## Analyzing EVM Transactions with Cast +## Analyzing EVM transactions with Cast -Once you have a transaction hash, you can use Foundry's `cast` command to inspect the transaction details: +When you have a transaction hash, you can use Foundry's `cast` command to inspect the transaction details: ```bash cast tx 0x5010e6600e67f04a9bc3d3b670a7c2de380b180713d9a014a5dbd76b7e2190f1 \ --rpc-url=http://url-to-sei-evm-rpc ``` -**Example Output:** +**Example output:** ```text blockHash 0x4696d63a9a9ae88b03bcc94ccbd87f407e994b309d1dff9c0626de51ac57b76e @@ -69,34 +69,34 @@ type 2 value 0 ``` -### Additional Analysis Commands +### Additional analysis commands -**Get transaction receipt:** +**Get the transaction receipt:** ```bash cast receipt 0x5010e6600e67f04a9bc3d3b670a7c2de380b180713d9a014a5dbd76b7e2190f1 \ --rpc-url=http://url-to-sei-evm-rpc ``` -**Decode transaction input data:** +**Decode the transaction input data:** ```bash cast 4byte-decode 0xc31d960f0000... ``` -All template generation commands create JSON files that you can inspect, modify, and use for debugging before executing the actual transactions. +All template generation commands create JSON files. You can inspect, modify, and use these files for debugging before you execute the transactions. --- -## RPC Consistency +## RPC consistency Always point `cast` commands to an EVM RPC endpoint (for example, `$EVM_RPC_URL`), not a Cosmos RPC URL. --- -## Tracing and Revert Reasons +## Tracing and revert reasons -If your endpoint supports debug RPC methods, you can retrieve full execution traces and revert reasons: +If your endpoint supports debug RPC methods, you can get full execution traces and revert reasons: ```bash # Full transaction trace @@ -110,14 +110,14 @@ cast rpc debug_traceCall '{"from":"0xFROM","to":"0xTO","data":"0xDATA"}' \ ``` - Many public RPC endpoints disable debug methods. If disabled, run a local fork and trace there. See Tracing docs at /evm/tracing. + Many public RPC endpoints disable debug methods. If they are disabled, run a local fork and trace there. See the tracing documentation. --- -## Reproduce with a Local Fork +## Reproduce with a local fork -Fork the network locally to reproduce issues deterministically and run traces even if remote debug RPC is disabled: +Fork the network locally to reproduce issues deterministically. You can then run traces even if the remote debug RPC is disabled: ```bash # Start a local fork @@ -133,9 +133,9 @@ cast rpc debug_traceCall '{"to":"0xContract","data":"0xENCODED_DATA"}' \ --- -## Event Logs and Decoding +## Event logs and decoding -Use the receipt to inspect logs and decode with the contract ABI: +Use the receipt to inspect the logs, and decode them with the contract ABI: ```bash # Fetch receipt JSON and view logs @@ -145,11 +145,11 @@ cast receipt 0xTX_HASH --rpc-url=$EVM_RPC_URL --json | jq '.logs' cast keccak "Transfer(address,address,uint256)" ``` -Decode event topics/data using the contract ABI (from your repo or block explorer). Topic[0] equals the keccak of the event signature. +Decode event topics and data with the contract ABI (from your repository or a block explorer). Topic[0] equals the keccak hash of the event signature. --- -## Nonce, Balance, and Gas Diagnostics +## Nonce, balance, and gas diagnostics Check common failure points quickly: @@ -163,25 +163,25 @@ cast chain-id --rpc-url=$EVM_RPC_URL **Checklist:** -- Incorrect nonce (pending tx in mempool) +- Incorrect nonce (a pending transaction in the mempool) - Insufficient native balance for gas -- Underpriced `maxFeePerGas`/`maxPriorityFeePerGas` +- Underpriced `maxFeePerGas` or `maxPriorityFeePerGas` - Chain ID mismatch ## Try it live -Each `cast` diagnostic above is a plain read-only JSON-RPC call. Run the same four against Sei Mainnet right here — the example address (`0xAa55…3d96`) is the sender from the `cast tx` output earlier on this page. +Each `cast` diagnostic above is a plain read-only JSON-RPC call. Run four of them against Sei Mainnet here. The example address (`0xAa55…3d96`) is the sender from the `cast tx` output earlier on this page. - + - + --- -## Offline Workflow with --generate-only +## Offline workflow with --generate-only -Generate, inspect, sign, and broadcast safely: +Generate, inspect, sign, and broadcast a transaction safely: ```bash # 1) Generate a template (no broadcast) @@ -214,18 +214,18 @@ seid tx broadcast signed.json --- -## Precompile Awareness +## Precompile awareness -Calls to system precompiles (for example, addresses like `0x...100b`) may have specific input/output formats and error behavior. +Calls to system precompiles (for example, addresses such as `0x...100b`) may have specific input and output formats and error behavior. -- See [EVM precompiles](/evm/precompiles/example-usage) and [EVM Cosmos precompiles](/evm/precompiles/cosmwasm-precompiles/example-usage) +- See [EVM precompiles](/evm/precompiles/example-usage) and [CosmWasm precompiles](/evm/precompiles/cosmwasm-precompiles/example-usage) - Cross-check expected selectors, parameter encoding, and revert messages --- -## Storage Inspection +## Storage inspection -Verify on-chain state directly when debugging state changes: +When you debug state changes, check the on-chain state directly: ```bash cast storage 0xContract 0xSLOT --rpc-url=$EVM_RPC_URL @@ -233,16 +233,16 @@ cast storage 0xContract 0xSLOT --rpc-url=$EVM_RPC_URL --- -## Transaction Analysis +## Transaction analysis -When analyzing transactions, follow these essential practices: +When you analyze transactions, follow these practices: - Always verify EVM transactions thoroughly -- Use `cast` to decode input data when working with EVM transactions +- Use `cast` to decode the input data of EVM transactions - Keep track of gas parameters -- Monitor transaction status on the EVM layer +- Monitor the transaction status on the EVM layer -**Analysis Tips:** +**Analysis tips:** ```bash # Use Foundry's cast tool for detailed transaction inspection @@ -258,14 +258,14 @@ cast 4byte-decode 0xa9059cbb000000... ``` - Transaction Analysis Checklist: Always verify transaction success before proceeding. Check gas usage to optimize future transactions. Use Foundry's cast tool for detailed transaction inspection. + Transaction analysis checklist: Always verify that a transaction succeeded before you continue. Check gas usage to optimize future transactions. Use Foundry's `cast` tool for detailed transaction inspection. --- -## Error Handling +## Error handling -Handle potential EVM transaction issues with proper monitoring: +Monitor EVM transactions so that you can handle potential issues: ```javascript try { @@ -280,22 +280,22 @@ try { } ``` -**Best Practices for Error Handling:** +**Best practices for error handling:** -- Always check transaction status on both Cosmos and EVM layers -- Use detailed error logging for debugging failed transactions +- Always check the transaction status on both the Cosmos and EVM layers +- Use detailed error logging to debug failed transactions - Implement retry logic for network-related failures - Monitor gas usage and adjust limits accordingly --- -## Security Guidelines +## Security guidelines - Critical Security Requirements: Keep private keys secure and never include them in templates. Use an `.env` file or other environment variables when working with wallet keys or mnemonics. Never commit sensitive information to version control. Always verify transaction details before signing. + Critical security requirements: Keep private keys secure, and never include them in templates. When you work with wallet keys or mnemonics, use an `.env` file or other environment variables. Never commit sensitive information to version control. Always verify transaction details before you sign. -**Environment Variable Setup:** +**Environment variable setup:** ```bash # Create .env file for sensitive data @@ -307,7 +307,7 @@ PRIVATE_KEY=your_private_key_here echo ".env" >> .gitignore ``` -**Secure Transaction Execution:** +**Secure transaction execution:** ```bash # Use environment variables in commands diff --git a/evm/differences-with-ethereum.mdx b/evm/differences-with-ethereum.mdx index 399d6e9..2ac584c 100644 --- a/evm/differences-with-ethereum.mdx +++ b/evm/differences-with-ethereum.mdx @@ -7,49 +7,48 @@ keywords: ['Sei EVM', 'Ethereum comparison', 'blockchain differences', 'EVM comp import { SstoreGasLive } from '/snippets/sstore-gas-live.jsx'; -While Sei features full EVM compatibility, there are some distinctions between -Sei's EVM and Ethereum itself: +Sei has full EVM compatibility, but Sei EVM and Ethereum differ in some ways: | Feature | Sei EVM | Ethereum | | --- | --- | --- | -| Blocktime | 400 ms | 12 s | -| Gas per Second | ~ 100 MegaGas/s | ~ 5 MegaGas/s | +| Block time | 400 ms | 12 s | +| Gas per second | ~ 100 MegaGas/s | ~ 5 MegaGas/s | | Finality | Instant (~400 ms) | Various commitment levels (safe, latest, justified, finalized) | -| Parallelized Execution | Yes | No | -| EVM Tooling Compatibility | 100% | 100% | -| EVM Version | Pectra (w/o blobs) | Fusaka | -| Gas Limit | 12.5 M (block cap) | 60 M (block); ~16.7 M per-tx (EIP-7825) | -| Per-Tx Gas Cap | 12.5 M (block limit) | ~16.7 M (EIP-7825) | -| Byte Size Limit | 21 MB | No byte-denominated limits | -| Execution Environment | EVM and Cosmos-SDK | EVM | -| Address Space | Dual ECDSA-derived addresses; Cosmos Bech32 (sei…) + EVM-compatible address (0x…) | ECDSA-derived address (0x…) | -| State Storage | AVL-tree (global root) | Merkle Patricia Trie (MPT) | -| SSTORE Gas Cost | 72k (on-chain param, governance-adjustable) | 20k (fixed) | - -- Sei uses the Pectra (Prague + Electra) version of EVM, excluding blob transactions. Ethereum has since upgraded to Fusaka (December 2025), which introduced PeerDAS for enhanced data availability. -- Sei's gas limit is 12.5 M as opposed to Ethereum's 60 M (increased from 45 M in the Fusaka upgrade via EIP-7935). Sei also has a byte size limit of 21MB. -- Sei has instant finality — a transaction is final as soon as its block is committed (~400 ms). This means the various commitment levels typical for Ethereum (i.e., safe, latest, justified) do not apply on Sei. +| Parallelized execution | Yes | No | +| EVM tooling compatibility | 100% | 100% | +| EVM version | Pectra (without blobs) | Fusaka | +| Gas limit | 12.5 M (block cap) | 60 M (block), ~16.7 M per-tx (EIP-7825) | +| Per-tx gas cap | 12.5 M (block limit) | ~16.7 M (EIP-7825) | +| Byte size limit | 21 MB | No byte-denominated limits | +| Execution environment | EVM and Cosmos SDK | EVM | +| Address space | Dual ECDSA-derived addresses: Cosmos Bech32 (sei…) and EVM-compatible (0x…) | ECDSA-derived address (0x…) | +| State storage | AVL tree (global root) | Merkle Patricia Trie (MPT) | +| SSTORE gas cost | 72k (on-chain parameter, governance-adjustable) | 20k (fixed) | + +- Sei uses the Pectra (Prague and Electra) version of the EVM, without blob transactions. Ethereum has since upgraded to Fusaka (December 2025). Fusaka introduced PeerDAS to improve data availability. +- Sei's gas limit is 12.5 M, compared with 60 M on Ethereum. The Fusaka upgrade increased Ethereum's limit from 45 M through EIP-7935. Sei also has a byte size limit of 21 MB. +- Sei has instant finality. A transaction is final as soon as its block is committed (approximately 400 ms). As a result, the commitment levels typical for Ethereum (safe, latest, and justified) do not apply on Sei. -**Deprecation Notice** +**Deprecation notice** Cosmos SDK and CosmWasm functionality is being deprecated in favor of EVM-only. For more details, see [SIP-3](https://github.com/sei-protocol/sips/blob/main/sips/sip-3.md) and [Proposal 99](https://seistream.app/proposals/99). -[Proposal 115](https://seistream.app/proposals/115) further disables CosmWasm code uploads and contract instantiations chain-wide — no new CosmWasm contracts can be deployed. Only `execute` and `query` against pre-existing CosmWasm contracts remain available. +[Proposal 115](https://seistream.app/proposals/115) also disables CosmWasm code uploads and contract instantiations chain-wide. As a result, you cannot deploy new CosmWasm contracts. Only `execute` and `query` against existing CosmWasm contracts remain available. -- **Sei is a dual-execution environment (EVM and Cosmos-SDK).** This means: +- **Sei is a dual-execution environment (EVM and Cosmos SDK).** This means that: - Non-EVM transactions can update EVM-accessible state. - - For example, an account's SEI balance can be affected by both Cosmos (bank send, wasm execute) transactions as well as EVM send transactions - - Sei assets can exist as EVM tokens (ERC20/721/1155), as legacy CosmWasm tokens (CW20/CW721/CW1155, no longer deployable per Prop 115), or as "native" Bank Module assets (Sei). - - User accounts on Sei have [two addresses](/learn/accounts) derived from the same public key (Cosmos Bech32 and EVM-compatible 0x…) - - Interoperability between EVM and Cosmos-SDK modules is governed and navigated via [precompiles](/evm/precompiles/example-usage) and [pointer contracts](/learn/pointers) + - For example, both Cosmos transactions (bank send, wasm execute) and EVM send transactions can change an account's SEI balance. + - Sei assets can exist as EVM tokens (ERC-20, ERC-721, and ERC-1155) or as legacy CosmWasm tokens (CW20, CW721, and CW1155). They can also exist as "native" Bank Module assets (Sei). Under Proposal 115, you can no longer deploy CosmWasm tokens. + - User accounts on Sei have [two addresses](/learn/accounts) derived from the same public key (Cosmos Bech32 and EVM-compatible 0x…). + - Interoperability between EVM and Cosmos SDK modules works through [precompiles](/evm/precompiles/example-usage) and [pointer contracts](/learn/pointers). -## Sei EVM Release +## Sei EVM release -Sei EVM was originally deployed at the following block heights and versions: +Sei EVM was first deployed at these block heights and versions: ### Testnet @@ -63,53 +62,53 @@ Sei EVM was originally deployed at the following block heights and versions: - **Height:** `79123881` - **Changelog:** https://github.com/sei-protocol/sei-chain/blob/main/CHANGELOG.md#v552 -## Opcode Differences +## Opcode differences | Opcode | Sei EVM | Ethereum | Notes | | --- | --- | --- | --- | -| PREVRANDAO | Returns a value derived from the current block time | Returns the RANDAO mix (EIP‑4399) | Not a randomness source; use an oracle/VRF. `DIFFICULTY` aliases to this. | +| PREVRANDAO | Returns a value derived from the current block time | Returns the RANDAO mix (EIP‑4399) | Not a randomness source. Use an oracle/VRF. `DIFFICULTY` aliases to this. | | COINBASE | Always the global fee collector address | Block proposer (miner) address | Do not assume it is the validator address. | -| BASEFEE | Returns current base fee; no burn | Returns current base fee; a portion is burned (EIP‑1559) | Legacy tx must meet Sei's governance-set minimum gas price (currently `50 gwei`); query `eth_gasPrice` for the live value. | -| BLOCKHASH | Hash of the Tendermint header; different encoding | Keccak of the Ethereum block header | Usable for recent blocks only; values are not interchangeable across chains. | -| GASLIMIT | = 12,500,000 per block | = 60,000,000 per block | Represents block gas limit in both chains. | -| TIMESTAMP | Tendermint block time | Proposer-chosen block time | Same semantics; do not use as randomness. | +| BASEFEE | Returns the current base fee, with no burn | Returns the current base fee. A portion is burned (EIP‑1559). | Legacy transactions must meet Sei's governance-set minimum gas price (currently `50 gwei`). Query `eth_gasPrice` for the live value. | +| BLOCKHASH | Hash of the Tendermint header, with a different encoding | Keccak of the Ethereum block header | Usable for recent blocks only. Values are not interchangeable across chains. | +| GASLIMIT | = 12,500,000 per block | = 60,000,000 per block | Represents the block gas limit on both chains. | +| TIMESTAMP | Tendermint block time | Proposer-chosen block time | Same semantics. Do not use it for randomness. | | DIFFICULTY | Alias of PREVRANDAO | Alias of PREVRANDAO (EIP‑4399) | Returns the same value as PREVRANDAO. | | Blob‑related opcodes | Not supported (Pectra without blobs) | Supported post‑Cancun (EIP‑4844) | Blob transactions are not enabled on Sei. | ### PREVRANDAO -Since Sei doesn't rely on the same pseudo‑randomness way of determining the next -validator like Proof of Stake (PoS) Ethereum does, it doesn't have the +Proof of Stake (PoS) Ethereum uses pseudo‑randomness to determine the next +validator. Sei does not rely on the same method, so it does not have the "randomness" artifact that can be set as `PREVRANDAO`'s return value. On Sei, -`PREVRANDAO` returns a value derived from the current block time. For strong -randomness needs in contract logic, use a verifiable randomness oracle (as is -advised on Ethereum itself). +`PREVRANDAO` returns a value derived from the current block time. If your +contract logic needs strong randomness, use a verifiable randomness oracle. +This is also the advice for Ethereum. ### COINBASE -Coinbase address on Sei is always set to (the EVM address of) the global fee +On Sei, the coinbase address is always the EVM address of the global fee collector. -## State Root +## State root -Since Sei uses AVL-tree instead of Merkle Patricia Trie (MPT) for data storage, -Sei doesn't have per-account state root. The global state root is the AVL-tree -root which is also not equivalent to Ethereum's overall state root (which is a -MPT root) +Sei uses an AVL tree instead of a Merkle Patricia Trie (MPT) for data storage. +Because of this, Sei does not have a per-account state root. The global state +root is the AVL-tree root. It is also not equivalent to Ethereum's overall +state root, which is an MPT root. -## Block Hash +## Block hash -The block hash on Sei is computed based on the block header in Tendermint data -format, and is different from Ethereum's block Hash as a result. +Sei computes the block hash from the block header in Tendermint data format. +As a result, it is different from Ethereum's block hash. -## Base Fee & Tips +## Base fee & tips -Sei supports all non‑blob transaction types, including the Pectra `SetCode` transaction (EIP‑7702). However for a legacy (non EIP‑1559) type -transaction, you must specify a gas price at or above Sei's governance-set minimum gas price (currently `50 gwei` on mainnet). Query the live value with `eth_gasPrice` rather than hard-coding it. In addition to this, excess -"gas wanted/gas limit" beyond the actual "gas used" may not be refunded in full -or in part. +Sei supports all non‑blob transaction types, including the Pectra `SetCode` transaction (EIP‑7702). However, for a legacy (non EIP‑1559) +transaction, you must specify a gas price at or above Sei's governance-set minimum gas price. The minimum is currently `50 gwei` on Sei Mainnet. Query the live value with `eth_gasPrice` instead of hard-coding it. Also, +excess "gas wanted/gas limit" beyond the actual "gas used" may not be refunded +in full or in part. -Current EIP1559 parameters can be fetched from the `seid` SDK tool: +You can fetch the current EIP-1559 parameters with `seid`: ```sh seid q params subspace evm KeyTargetGasUsedPerBlock @@ -127,21 +126,21 @@ subspace: evm value: '"0.007500000000000000"' ``` -## Non-EVM Transactions +## Non-EVM transactions -On Sei there exists non-EVM transactions which may update states accessible by -EVM transactions. The simplest example would be bank balances, which may be -updated by both native Cosmos bank send transactions and EVM send transactions. -As a result, if certain offchain applications only parse EVM transactions, they -may find certain state changes unattributable to any EVM transaction. +On Sei, non-EVM transactions may update state that EVM transactions can +access. The simplest example is bank balances. Both native Cosmos bank send +transactions and EVM send transactions may update them. As a result, an +offchain application that parses only EVM transactions may find state changes +that it cannot attribute to any EVM transaction. -## EVM Transaction Envelope Restrictions +## EVM transaction envelope restrictions -On Sei, EVM transactions are carried inside a Cosmos transaction envelope, but that envelope must remain empty of Cosmos-specific fields. This introduces the following Sei-specific divergences from a plain Ethereum transaction that tooling constructing raw transactions should be aware of: +On Sei, EVM transactions are carried inside a Cosmos transaction envelope. That envelope must not contain any Cosmos-specific fields. Tooling that builds raw transactions should know about these Sei-specific differences from a plain Ethereum transaction: ### No Cosmos wrapper fields on EVM transactions -An EVM transaction must not populate any of the Cosmos wrapper fields. If any of the following are set, the transaction is rejected: +An EVM transaction must not populate any of the Cosmos wrapper fields. If any of these fields are set, Sei rejects the transaction: - `memo` - `timeout_height` @@ -150,86 +149,84 @@ An EVM transaction must not populate any of the Cosmos wrapper fields. If any of - fee amount, fee `payer`, and fee `granter` - top-level `signatures` -The EVM transaction's own signature (`v`, `r`, `s`) lives inside the EVM payload itself, so none of these Cosmos-level fields are needed. This check is applied uniformly to all EVM transactions. +The EVM transaction's own signature (`v`, `r`, `s`) is inside the EVM payload itself, so the transaction does not need any of these Cosmos-level fields. Sei applies this check uniformly to all EVM transactions. ### Whole-block rejection on transaction decode failure -During proposal processing, Sei decodes every transaction in a proposed block. If any transaction fails to decode — or panics during decode — the **entire block proposal is rejected** rather than the offending transaction being silently skipped (treated as nil) while the rest of the block proceeds. +During proposal processing, Sei decodes every transaction in a proposed block. If any transaction fails to decode or panics during decode, Sei rejects the **entire block proposal**. It does not silently skip the offending transaction (treat it as nil) and continue with the rest of the block. -This also affects block gas accounting: a transaction that could not be decoded no longer contributes zero gas and gets skipped; instead its presence causes the block proposal to be rejected outright. +This also affects block gas accounting. A transaction that could not be decoded no longer contributes zero gas and gets skipped. Instead, its presence causes Sei to reject the block proposal outright. -This is a consensus-level behavior change. Tooling that produces malformed or non-canonical transactions can no longer rely on such transactions being individually dropped from an otherwise-valid block — a single undecodable transaction now invalidates the whole proposal. Ensure your signing and broadcast tooling only submits transactions that decode cleanly. +Make sure that your signing and broadcast tooling submits only transactions that decode cleanly. This is a consensus-level behavior change. A single undecodable transaction now invalidates the whole proposal. Tooling that produces malformed or non-canonical transactions can no longer rely on Sei to drop them individually from an otherwise-valid block. ### Rejection of bloated (non-canonical) transaction bodies -The transaction decoder rejects "bloated" transaction bodies — those whose raw protobuf wire encoding is larger than the canonical re-marshal of the decoded body. Non-canonical encodings (for example, padded fields or an oversized `Any.Value`) are rejected on decode with a decode error. This check has been enforced since v6.5.0. +The transaction decoder rejects "bloated" transaction bodies. A bloated body has a raw protobuf wire encoding that is larger than the canonical re-marshal of the decoded body. The decoder rejects non-canonical encodings (for example, padded fields or an oversized `Any.Value`) with a decode error. This check has been enforced since v6.5.0. -Ensure your transaction-signing tooling produces a minimal, canonical envelope with no Cosmos wrapper fields populated. +Make sure that your transaction-signing tooling produces a minimal, canonical envelope with no Cosmos wrapper fields populated. ## Finality -Sei has instant finality — a transaction is final as soon as its block is -committed (~400 ms) — meaning that commitment levels of "safe", "latest", -"justified", and "finalized" on Ethereum are all the same thing on Sei. +Sei has instant finality. A transaction is final as soon as its block is +committed (approximately 400 ms). This means that Ethereum's commitment levels +"safe", "latest", "justified", and "finalized" are all the same on Sei. -## Pending State +## Pending state -On Ethereum the block proposer would execute its proposed block first (and -update its local state) before broadcasting the proposal to others (the updated -state would be marked "pending" until the node is accepted by other nodes). +On Ethereum, the block proposer executes its proposed block first and updates +its local state. Then it broadcasts the proposal to others. The updated state +is marked "pending" until the node is accepted by other nodes. -However, on Sei, the block proposer would broadcast first and only execute the -proposal if it's accepted (i.e. every node would execute the block at roughly -the same time), so Sei does not have a window when "pending state" -exists. +However, on Sei, the block proposer broadcasts the proposal first. It executes +the proposal only if the proposal is accepted. This means that every node +executes the block at roughly the same time, so Sei does not have a window +when a "pending state" exists. -## Gas Model & Fees +## Gas model & fees -Sei does not implement base‑fee burning. There is no base‑fee burn; all transaction fees accrue to validators. Fees are calculated as: +Sei does not burn the base fee. All transaction fees go to validators. Fees are calculated as: Transaction Fee = Gas Used × Gas Price **Practical implications** -- **Simpler fee handling:** Use `gasPrice` (you can omit `maxFeePerGas` / `maxPriorityFeePerGas`). -- **More stable fees:** Higher throughput reduces fee spikes during busy periods. -- **Typically lower cost:** Many workloads that are costly on Ethereum become economical on Sei. +- Fee handling is simpler: use `gasPrice`, and you can omit `maxFeePerGas` and `maxPriorityFeePerGas`. +- Fees are more stable, because higher throughput reduces fee spikes during busy periods. +- Costs are typically lower. Many workloads that are costly on Ethereum become economical on Sei. -**Useful Infos** - - **Does Sei burn a base fee (EIP‑1559)?** No. - **Who receives fees?** Validators. -- **Are Sei fees lower?** Yes, due to higher throughput and parallel execution. +- **Are Sei fees lower?** Yes, because of higher throughput and parallel execution. -## SSTORE Gas Cost +## SSTORE gas cost -On Sei, the `SSTORE` opcode gas cost is configurable as an on-chain parameter, meaning it can be adjusted via governance proposal without requiring a chain upgrade. This provides flexibility to tune storage costs based on EVM state size and network conditions. +On Sei, the gas cost of the `SSTORE` opcode is a configurable on-chain parameter. A governance proposal can adjust it without a chain upgrade. This lets governance tune storage costs based on EVM state size and network conditions. -Currently, the `SSTORE` gas cost is set to the non-standard value of **72,000 gas**. This value is the same on both Sei Mainnet and Sei Testnet. It was set by governance [Proposal #109](https://seistream.app/proposals/109) ("Update EVM SSTORE set gas to 72000"), which changed the `evm` module parameter `KeySeiSstoreSetGasEIP2200` to `72000`. +The `SSTORE` gas cost is currently set to the non-standard value of **72,000 gas**. This value is the same on Sei Mainnet and Sei Testnet. Governance [Proposal #109](https://seistream.app/proposals/109) ("Update EVM SSTORE set gas to 72000") set this value. The proposal changed the `evm` module parameter `KeySeiSstoreSetGasEIP2200` to `72000`. -The values below are read **live** from the Sei EVM: +The values below are read **live** from the Sei EVM: -To confirm the real cost yourself, use a live `eth_estimateGas` call against a Sei RPC. Note that a Foundry `forge test --gas-report --fork-url ` report forks chain *state* but applies revm's standard EVM gas schedule, so it reports the Ethereum cost (~22,100) rather than Sei's — it is useful for relative profiling of your own logic, not for the absolute storage-write cost. +To confirm the real cost yourself, make a live `eth_estimateGas` call against a Sei RPC. A Foundry `forge test --gas-report --fork-url ` report forks the chain *state*, but it applies revm's standard EVM gas schedule. As a result, it reports the Ethereum cost (approximately 22,100) instead of the Sei cost. The report is useful for relative profiling of your own logic, but not for the absolute storage-write cost. -Since `SSTORE` is a governance-controlled parameter, this value may change in the future through a governance proposal. +Because the `SSTORE` gas cost is a governance-controlled parameter, a governance proposal may change this value in the future. -## ERC Token Standards Compatibility +## ERC token standards compatibility -Sei’s EVM fully supports the common token standards: +Sei EVM fully supports the common token standards: - **ERC‑20** (fungible tokens) - **ERC‑721** (NFTs) @@ -237,10 +234,10 @@ Sei’s EVM fully supports the common token standards: Existing OpenZeppelin contracts and tools work unchanged. -## Testing & Migration Checklist +## Testing & migration checklist -- ✅ Re‑deploy your Solidity code to Sei Testnet; most contracts need no changes. -- ✅ If you used SELFDESTRUCT, refactor to a soft‑close pattern. -- ✅ Remove EIP‑1559 fee UI complexity; use a single `gasPrice` input in frontends. -- ✅ If you rely on on‑chain “randomness,” integrate an oracle/VRF. -- ✅ Size your `gasLimit` with a modest buffer (parallel execution can slightly vary estimates). +- Redeploy your Solidity code to Sei Testnet. Most contracts do not need changes. +- If you used SELFDESTRUCT, refactor it to a soft‑close pattern. +- Remove the EIP‑1559 fee complexity from your UI. Use a single `gasPrice` input in frontends. +- If you rely on on‑chain "randomness," integrate an oracle or VRF. +- Size your `gasLimit` with a modest buffer. Parallel execution can make estimates vary slightly. diff --git a/evm/dune.mdx b/evm/dune.mdx index 9eb4927..cd88367 100644 --- a/evm/dune.mdx +++ b/evm/dune.mdx @@ -6,15 +6,15 @@ keywords: ['dune analytics', 'blockchain analytics', 'SQL queries', 'game analyt ## What is Dune Analytics? -Dune Analytics is a powerful blockchain analytics platform that allows you to query, visualize, and share blockchain data using SQL. For game developers, it's an invaluable tool for: +Dune Analytics is a blockchain analytics platform. You can use it to query, visualize, and share blockchain data with SQL. Game developers can use it for: -- **Player Analytics**: Track user acquisition, retention, and engagement -- **Transaction Analysis**: Monitor game economy and player behavior -- **Performance Metrics**: Measure daily/weekly active users, transaction volumes -- **Cohort Analysis**: Understand player lifecycle and retention patterns -- **Custom Dashboards**: Create visual reports for stakeholders +- **Player analytics**: Track user acquisition, retention, and engagement +- **Transaction analysis**: Monitor the game economy and player behavior +- **Performance metrics**: Measure daily and weekly active users, and transaction volumes +- **Cohort analysis**: Understand the player lifecycle and retention patterns +- **Custom dashboards**: Create visual reports for stakeholders -### Key Features: +### Key features: - SQL-based querying interface - Pre-indexed blockchain data from multiple networks @@ -25,56 +25,56 @@ Dune Analytics is a powerful blockchain analytics platform that allows you to qu Before you begin, make sure you have: -1. **Dune Account**: Sign up at [dune.com](https://dune.com) -2. **Basic SQL Knowledge**: Understanding of SELECT, JOIN, WHERE, GROUP BY clauses -3. **Contract Addresses**: Know your game's smart contract addresses -4. **Understanding of Your Game Logic**: Know what transactions represent in your game context +1. **Dune account**: Sign up at [dune.com](https://dune.com) +2. **Basic SQL knowledge**: Understanding of the SELECT, JOIN, WHERE, and GROUP BY clauses +3. **Contract addresses**: Know your game's smart contract addresses +4. **Understanding of your game logic**: Know what each transaction represents in your game -### SQL Knowledge Requirements: +### SQL knowledge requirements: - Basic `SELECT` statements - JOINs (`INNER`, `LEFT`) - Aggregate functions (`COUNT`, `SUM`, `AVG`) - Date functions (`DATE_TRUNC`, `DATE_DIFF`) -- Common Table Expressions (`WITH` clauses) +- Common table expressions (`WITH` clauses) -## Getting Started +## Getting started -### Step 1: Access the Template Dashboard +### Step 1: Access the template dashboard -Visit the Sei Games Query Templates: [Game Query Templates](https://dune.com/sei/sei-games-query-templates) +Open the [Sei Games Query Templates](https://dune.com/sei/sei-games-query-templates) dashboard. -### Step 2: Understanding the Dashboard Structure +### Step 2: Understanding the dashboard structure -The template dashboard contains several key metrics: +The template dashboard contains these metrics: - Total unique users - Cohort retention analysis - User acquisition trends - Transaction volume analysis -- Daily/Weekly active users +- Daily and weekly active users -Below are the SQL queries powering these metrics. +This guide gives the SQL queries behind these metrics. -## How to Fork and Use Query Templates +## How to fork and use query templates -### Forking a Query +### Forking a query -1. **Navigate to the Query**: Click on any visualization in the dashboard -2. **Access Query Editor**: Click "Edit Query" or the query title -3. **Fork the Query**: Click the "Fork" button in the top right -4. **Rename Your Fork**: Give it a descriptive name like "MyGame - Daily Active Users" -5. **Customize**: Replace placeholder values with your actual contract addresses +1. To open a query, click any visualization in the dashboard. +2. To open the query editor, click **Edit Query** or the query title. +3. To fork the query, click **Fork** in the top right. +4. Give your fork a descriptive name, such as "MyGame - Daily Active Users". +5. Replace the placeholder values with your own contract addresses. -### Making Queries Private/Public +### Making queries private/public -- **Private Queries**: Only visible to you -- **Public Queries**: Visible to all Dune users -- **Unlisted**: Not searchable but accessible via direct link +- **Private queries**: Visible only to you +- **Public queries**: Visible to all Dune users +- **Unlisted**: Not searchable, but accessible through a direct link -## Query Templates for Game Analytics +## Query templates for game analytics -### 1. Total Unique Users +### 1. Total unique users **Purpose**: Get the total number of unique players who have ever interacted with your game. @@ -97,14 +97,14 @@ WHERE t.success = TRUE ``` -**How to Use**: +**How to use**: -- Replace `0xYOUR_CONTRACT_ADDRESS_1` with your actual contract addresses +- Replace `0xYOUR_CONTRACT_ADDRESS_1` with your own contract addresses - Add or remove addresses as needed --- -### 2. Cohort Retention Analysis +### 2. Cohort retention analysis **Purpose**: Analyze how well you retain players over time by tracking weekly cohorts. @@ -173,17 +173,17 @@ JOIN cohort_size s ON d.cohort_week = s.cohort_week ORDER BY 1 ASC, 3 ASC; ``` -**Key Metrics**: +**Key metrics**: - `cohort_week`: When users first joined -- `week_offset`: Weeks since first interaction (0 = first week, 1 = second week, etc.) -- `retention_percentage`: Percentage of cohort still active +- `week_offset`: Weeks since the first interaction (0 is the first week, 1 is the second week, and so on) +- `retention_percentage`: Percentage of the cohort still active --- -### 3. Weekly User Acquisition +### 3. Weekly user acquisition -**Purpose**: Track how many new users you're acquiring each week. +**Purpose**: Track how many new users you get each week. ```sql WITH my_game_contracts AS ( @@ -217,7 +217,7 @@ ORDER BY 1 DESC --- -### 4. Daily Transaction Volume +### 4. Daily transaction volume **Purpose**: Monitor daily transaction activity in your game. @@ -245,7 +245,7 @@ ORDER BY 1 DESC --- -### 5. Daily Active Users (DAU) +### 5. Daily active users (DAU) **Purpose**: Track unique daily active users. @@ -273,7 +273,7 @@ ORDER BY 1 DESC --- -### 6. Weekly Transaction Volume +### 6. Weekly transaction volume **Purpose**: Analyze weekly transaction patterns. @@ -301,7 +301,7 @@ ORDER BY 1 DESC --- -### 7. Weekly Active Users (WAU) +### 7. Weekly active users (WAU) **Purpose**: Track unique weekly active users. @@ -329,9 +329,9 @@ ORDER BY 1 DESC --- -### 8. Daily User Acquisition +### 8. Daily user acquisition -**Purpose**: Track new user acquisition on a daily basis. +**Purpose**: Track how many new users you get each day. ```sql WITH my_game_contracts AS ( @@ -363,11 +363,11 @@ GROUP BY 1 ORDER BY 1 DESC ``` -## Customizing Queries for Your Game +## Customizing queries for your game -### 1. Replace Contract Addresses +### 1. Replace contract addresses -**Find this section in each query**: +In each query, find this section: ```sql FROM UNNEST(ARRAY[ @@ -376,7 +376,7 @@ FROM UNNEST(ARRAY[ ]) AS _u(address) ``` -**Replace with your actual addresses**: +Replace the placeholders with your addresses, for example: ```sql FROM UNNEST(ARRAY[ @@ -386,9 +386,9 @@ FROM UNNEST(ARRAY[ ]) AS _u(address) ``` -### 2. Filter by Specific Functions +### 2. Filter by specific functions -To track specific game actions, add function signature filtering: +To track specific game actions, filter by function signature: ```sql WHERE @@ -396,9 +396,9 @@ WHERE AND t.data LIKE '0x12345678%' -- Replace with your function signature ``` -### 3. Add Time Filters +### 3. Add time filters -To analyze specific periods: +To analyze a specific period, filter by date: ```sql WHERE @@ -407,16 +407,16 @@ WHERE AND t.block_date <= '2024-12-31' ``` -## Best Practices +## Best practices -### Performance Optimization +### Performance optimization -1. **Use Date Filters**: Always include date ranges to limit data scope -2. **Index Awareness**: Filter on indexed columns (block_date, address) first -3. **Limit Results**: Use `LIMIT` for testing large queries +1. Always use date filters to limit the scope of the data. +2. Filter on indexed columns (block_date, address) first. +3. Use `LIMIT` when you test large queries. --- ## Resources -- [Dune Analytics Documentation](https://docs.dune.com) +- [Dune Analytics documentation](https://docs.dune.com) diff --git a/evm/ecosystem-contracts.mdx b/evm/ecosystem-contracts.mdx index c735ff9..45db424 100644 --- a/evm/ecosystem-contracts.mdx +++ b/evm/ecosystem-contracts.mdx @@ -6,36 +6,36 @@ keywords: ['ecosystem contracts', 'smart contracts', 'contract addresses', 'DeFi import { EcosystemContracts } from '/snippets/ecosystem-contracts.jsx'; -Discover and interact with the ecosystem building on Sei. This registry contains smart contract addresses for projects built across Sei. +Use this registry to find and interact with projects built on Sei. It contains the smart contract addresses of these projects. -**Work in Progress** +**Work in progress** -This registry is actively maintained and expanded. We're constantly adding new projects and updating contract addresses. Check back regularly for the latest additions to the Sei ecosystem. +We actively maintain and expand this registry. We continually add new projects and update contract addresses. Check back regularly for the latest additions to the Sei ecosystem. --- -### How to Use This Registry +### How to use this registry -- **Search by Project Name**: Use the search bar to quickly find contracts for specific projects. -- **View Contract Details**: Click on the Seiscan link to see detailed information about the contract -- **Bookmark This Page**: Keep this registry handy for quick access to the latest contract addresses and updates. +- To find the contracts of a specific project quickly, search by project name in the search bar. +- To see detailed information about a contract, click its Seiscan link. +- Bookmark this page for quick access to the latest contract addresses and updates. -**Add Your Project** +**Add your project** -Don't see your project listed? Want to add your contracts to this registry? **Reach out to us** in the [Sei Tech Chat](https://t.me/+KZdhZ1eE-G01NmZk) and we'll help get you added! +To add your project or its contracts to this registry, contact us in the [Sei Tech Chat](https://t.me/+KZdhZ1eE-G01NmZk). We will help you get listed. -## Contract Registry +## Contract registry --- -Always verify contract addresses independently before interacting with them. While we strive to maintain accurate information, you should always double-check addresses through official project channels. +Always verify contract addresses independently before you interact with them. We try to keep this information accurate, but always double-check addresses through official project channels. diff --git a/evm/evm-foundry.mdx b/evm/evm-foundry.mdx index 1a4126a..cfe9f21 100644 --- a/evm/evm-foundry.mdx +++ b/evm/evm-foundry.mdx @@ -9,29 +9,29 @@ import { RunSnippet } from '/snippets/run-snippet.jsx'; import { SandboxEmbed } from '/snippets/sandbox-embed.jsx'; import { AddSeiButton } from '/snippets/add-sei-button.jsx'; -This tutorial will guide you through setting up Foundry for Sei EVM development and using OpenZeppelin contracts to build secure, standardized smart contracts. We'll cover environment setup, contract creation, deployment, and show how to leverage OpenZeppelin's pre-built components with the powerful Foundry toolkit. +This tutorial shows how to set up Foundry for Sei EVM development. It covers environment setup, contract creation, and deployment. You use OpenZeppelin's pre-built components with the Foundry toolkit to build secure, standardized smart contracts. Watch the video walkthrough for this topic in the [Video Tutorials](/evm/videos) section. -**Deploy to Testnet First** +**Deploy to Sei Testnet first** -It is highly recommended that you deploy to Sei Testnet first and verify everything works as expected before committing to Sei Mainnet. Doing so helps you catch bugs early, avoid unnecessary gas costs, and keep your users safe. +We highly recommend that you deploy to Sei Testnet first. Make sure that everything works as expected before you deploy to Sei Mainnet. This helps you catch bugs early, avoid unnecessary gas costs, and keep your users safe. ## Try it before you install -Installing Foundry and scaffolding a project takes a few minutes. If you just want to see a contract deploy to Sei, you can do both of these right now in the browser. +It takes a few minutes to install Foundry and scaffold a project. If you only want to see a contract deploy to Sei, you can do both of these steps in the browser now. -First, confirm the RPC endpoints you'll put in `foundry.toml` respond: +First, confirm that the RPC endpoints you will use in `foundry.toml` respond: - + - + -Then add Sei Testnet to your wallet and deploy a minimal `Counter.sol` from Remix — no `forge`, no install. In Remix: compile under **Solidity Compiler**, then **Deploy & Run** with **Environment** set to **Injected Provider — MetaMask**. +Then add Sei Testnet to your wallet and deploy a minimal `Counter.sol` from Remix. You do not need `forge` or a local install. In Remix, compile the contract under **Solidity Compiler**. Then deploy it under **Deploy & Run**, with **Environment** set to **Injected Provider - MetaMask**. @@ -42,30 +42,30 @@ Then add Sei Testnet to your wallet and deploy a minimal `Counter.sol` from Remi description="Remix IDE with a minimal Counter contract preloaded. Compile in-browser, then deploy to Sei Testnet." /> -## Table of Contents +## Table of contents - [Try it before you install](#try-it-before-you-install) - [Prerequisites](#prerequisites) -- [Setting Up Your Development Environment](#setting-up-your-development-environment) +- [Setting up your development environment](#setting-up-your-development-environment) - [Configuring Foundry for Sei EVM](#configuring-foundry-for-sei-evm) -- [Using OpenZeppelin Contracts](#using-openzeppelin-contracts) -- [Creating and Deploying Smart Contracts](#creating-and-deploying-smart-contracts) -- [Testing Your Smart Contracts](#testing-your-smart-contracts) +- [Using OpenZeppelin contracts](#using-openzeppelin-contracts) +- [Creating and deploying smart contracts](#creating-and-deploying-smart-contracts) +- [Testing your smart contracts](#testing-your-smart-contracts) - [Deploying to Sei Testnet and Mainnet](#deploying-to-sei-testnet-and-mainnet) -- [Interacting with Deployed Contracts](#interacting-with-deployed-contracts) +- [Interacting with deployed contracts](#interacting-with-deployed-contracts) ## Prerequisites -Before we begin, ensure you have the following: +Before you start, make sure that you have the following: - [Foundry](https://book.getfoundry.sh/) installed on your system - A basic understanding of Solidity and smart contract development - A wallet with SEI tokens for gas - [Node.js](https://nodejs.org/) (v18.0.0 or later) for ethers.js interactions -## Setting Up Your Development Environment +## Setting up your development environment -First, let's install Foundry if you haven't already. Follow the [installation guide](https://book.getfoundry.sh/getting-started/installation) or use the quick install command: +If you have not installed Foundry yet, install it first. Follow the [installation guide](https://book.getfoundry.sh/getting-started/installation) or use the quick install command: ```bash curl -L https://foundry.paradigm.xyz | bash @@ -86,11 +86,11 @@ forge init --no-git git init ``` -This will create a standard Foundry project structure with `src/`, `test/`, and `script/` directories. +This creates a standard Foundry project structure with `src/`, `test/`, and `script/` directories. ## Configuring Foundry for Sei EVM -Create a `foundry.toml` file in your project root to configure Foundry for Sei networks: +To configure Foundry for Sei networks, create a `foundry.toml` file in your project root: ```toml title="foundry.toml" [profile.default] @@ -115,30 +115,30 @@ SEI_TESTNET_RPC=https://evm-rpc-testnet.sei-apis.com SEI_MAINNET_RPC=https://evm-rpc.sei-apis.com ``` -Add `.env` to your `.gitignore` file to prevent committing sensitive information such as your `PRIVATE_KEY` and potentially lose funds. +Add `.env` to your `.gitignore` file. If you commit sensitive information such as your `PRIVATE_KEY`, you can lose funds. -## Using OpenZeppelin Contracts +## Using OpenZeppelin contracts -OpenZeppelin provides a library of secure, tested smart contract components. Let's install OpenZeppelin contracts: +OpenZeppelin has a library of secure, tested smart contract components. Install the OpenZeppelin contracts: ```bash forge install OpenZeppelin/openzeppelin-contracts ``` -Create a `remappings.txt` file to properly map the imports: +Create a `remappings.txt` file to map the imports correctly: ```bash forge remappings > remappings.txt ``` -## Creating and Deploying Smart Contracts +## Creating and deploying smart contracts -Let's create different types of smart contracts. Choose from the tabs below based on what you want to build: +Each tab below creates a different type of smart contract. Choose the one that matches what you want to build: -Let's start with a simple counter contract. Update the default `src/Counter.sol` file: +Start with a simple counter contract. Update the default `src/Counter.sol` file: ```solidity title="src/Counter.sol" // SPDX-License-Identifier: UNLICENSED @@ -202,7 +202,7 @@ contract DeployCounter is Script { -Create an ERC20 token using OpenZeppelin. Create `src/SeiToken.sol`: +Create an ERC20 token with OpenZeppelin. Add the contract to `src/SeiToken.sol`: ```solidity title="src/SeiToken.sol" // SPDX-License-Identifier: MIT @@ -260,7 +260,7 @@ contract DeploySeiToken is Script { -Create an ERC721 NFT contract using OpenZeppelin. Create `src/SeiNFT.sol`: +Create an ERC721 NFT contract with OpenZeppelin. Add the contract to `src/SeiNFT.sol`: ```solidity title="src/SeiNFT.sol" // SPDX-License-Identifier: MIT @@ -376,9 +376,9 @@ contract DeploySeiNFT is Script { -## Testing Your Smart Contracts +## Testing your smart contracts -Foundry provides excellent testing capabilities. Let's create comprehensive tests for our contracts. +Foundry has built-in support for testing. Create tests for your contracts. @@ -567,13 +567,13 @@ contract SeiNFTTest is Test { -Run your tests with: +Run your tests: ```bash forge test ``` -For more verbose output: +For more verbose output, run: ```bash forge test -vvv @@ -581,9 +581,9 @@ forge test -vvv ## Deploying to Sei Testnet and Mainnet -Now let's deploy our contracts to the Sei networks. You can use either Forge scripts or direct deployment commands. +You can deploy your contracts to the Sei networks with Forge scripts or with direct deployment commands. -### Using Forge Scripts (Recommended) +### Using Forge scripts (recommended) Deploy to Sei Testnet: @@ -597,7 +597,7 @@ Deploy to Sei Mainnet: forge script script/DeployCounter.s.sol --rpc-url $SEI_MAINNET_RPC --private-key $PRIVATE_KEY --broadcast ``` -### Using Direct Forge Create Commands +### Using direct Forge create commands Alternatively, you can deploy directly: @@ -612,7 +612,7 @@ forge create --rpc-url $SEI_TESTNET_RPC --private-key $PRIVATE_KEY src/SeiToken. forge create --rpc-url $SEI_TESTNET_RPC --private-key $PRIVATE_KEY src/SeiNFT.sol:SeiNFT --constructor-args $(cast abi-encode "constructor(address,string)" "YOUR_ADDRESS" "https://your-metadata-server.com/metadata/") ``` -Successful deployment will output: +A successful deployment prints output similar to this: ```bash [⠒] Compiling... @@ -622,11 +622,11 @@ Deployed to: 0xYOUR_CONTRACT_ADDRESS Transaction hash: 0xYOUR_TX_HASH ``` -## Interacting with Deployed Contracts +## Interacting with deployed contracts -Once deployed, you can interact with your contracts using Foundry's `cast` tool or ethers.js. +After deployment, you can interact with your contracts through Foundry's `cast` tool or ethers.js. -### Using Cast Commands +### Using Cast commands ```bash # Query the counter value @@ -647,7 +647,7 @@ cast send $TOKEN_ADDRESS "transfer(address,uint256)" $RECIPIENT_ADDRESS 1000 --p ### Using ethers.js -Install ethers.js to interact with your contracts programmatically: +To interact with your contracts programmatically, install ethers.js: ```bash npm install ethers@latest @@ -700,4 +700,4 @@ async function interactWithContracts() { interactWithContracts(); ``` -Foundry generates the ABI for contracts in the `out` folder. You can use this ABI to interact with contracts from other tools like `ethers.js` or `web3.js`. +Foundry generates contract ABIs in the `out` folder. You can use these ABIs to interact with contracts from other tools, such as `ethers.js` or `web3.js`. diff --git a/evm/evm-general.mdx b/evm/evm-general.mdx index ca98325..39d2934 100644 --- a/evm/evm-general.mdx +++ b/evm/evm-general.mdx @@ -12,34 +12,32 @@ import { AddSeiButton } from '/snippets/add-sei-button.jsx'; ## Overview The Ethereum Virtual Machine (EVM) is the runtime environment for smart -contracts, enabling compatibility with Ethereum-based dApps. Sei is an EVM -compatible blockchain. Sei's parallelized EVM ensures high performance and -efficiency. +contracts. Sei is an EVM-compatible blockchain, so it supports Ethereum-based +dApps. Sei's EVM is parallelized for high performance and efficiency. Watch the video walkthrough for this topic in the [Video Tutorials](/evm/videos) section. -Here are some key points about the EVM: - -1. **Turing Completeness**: The EVM is Turing complete, meaning it can execute - any computable function. This allows developers to write complex smart - contracts. -2. **Gas**: Transactions and contract executions on the EVM compatible network - consume gas. Gas is a measure of computational work, and users pay for it in - usei on Sei networks. Gas ensures that malicious or inefficient code doesn't - overload the network. -3. **Bytecode Execution**: Smart contracts are compiled into bytecode (low-level - machine-readable instructions) and deployed to the EVM compatible network. +The EVM has these main properties: + +1. **Turing completeness**: The EVM is Turing complete, so it can execute any + computable function. This lets developers write complex smart contracts. +2. **Gas**: Transactions and contract executions on an EVM-compatible network + consume gas. Gas measures computational work. On Sei networks, users pay for + gas in usei. Gas prevents malicious or inefficient code from overloading the + network. +3. **Bytecode execution**: Smart contracts are compiled into bytecode (low-level, + machine-readable instructions) and deployed to the EVM-compatible network. The EVM executes this bytecode. ## Try it: deploy without any setup -You don't need a local toolchain to ship a contract to Sei. First confirm the network is live, then compile and deploy a minimal `Counter.sol` to testnet straight from the browser. +You do not need a local toolchain to deploy a contract to Sei. First, confirm that the network is live. Then compile and deploy a minimal `Counter.sol` to Sei Testnet directly from your browser. - + - + -Add Sei Testnet to your wallet, then deploy from Remix below — compile under **Solidity Compiler**, then **Deploy & Run** with **Environment** set to **Injected Provider — MetaMask**: +Add Sei Testnet to your wallet. Then use Remix below to deploy the contract. Compile it under **Solidity Compiler**. Next, open **Deploy & Run** and set **Environment** to **Injected Provider - MetaMask**. @@ -47,7 +45,7 @@ Add Sei Testnet to your wallet, then deploy from Remix below — compile under * kind="remix" src="https://remix.ethereum.org/?#activate=solidity,fileManager&code=Ly8gU1BEWC1MaWNlbnNlLUlkZW50aWZpZXI6IE1JVApwcmFnbWEgc29saWRpdHkgXjAuOC4yNDsKCi8vLyBAdGl0bGUgQ291bnRlciDigJQgbWluaW1hbCBjb250cmFjdCB0byBjb21waWxlICYgZGVwbG95IHRvIFNlaSB0ZXN0bmV0Lgpjb250cmFjdCBDb3VudGVyIHsKICAgIHVpbnQyNTYgcHVibGljIGNvdW50OwogICAgZnVuY3Rpb24gaW5jcmVtZW50KCkgZXh0ZXJuYWwgeyBjb3VudCsrOyB9CiAgICBmdW5jdGlvbiBkZWNyZW1lbnQoKSBleHRlcm5hbCB7IGNvdW50LS07IH0KfQ" title="Counter.sol · deploy to Sei Testnet" - description="Remix IDE with a minimal Counter contract preloaded. Compile in-browser, then deploy to Sei Testnet." + description="Remix IDE with a minimal Counter contract preloaded. Compile it in the browser, then deploy it to Sei Testnet." /> ## Smart contract languages @@ -57,17 +55,17 @@ The two most popular languages for developing smart contracts on the EVM are ### Solidity -- Object-oriented, high-level language for implementing smart contracts. -- Curly-bracket language that has been most profoundly influenced by C++. +- An object-oriented, high-level language for implementing smart contracts. +- A curly-bracket language that C++ influenced the most. - Statically typed (the type of a variable is known at compile time). - Supports: - Inheritance (you can extend other contracts). - Libraries (you can create reusable code that you can call from different - contracts – like static functions in a static class in other object oriented - programming languages). + contracts). Libraries are like static functions in a static class in other + object-oriented programming languages. - Complex user-defined types. -#### Example solidity contract +#### Example Solidity contract ```solidity // SPDX-License-Identifier: GPL-3.0 @@ -110,12 +108,12 @@ contract Coin { ### Vyper -- Pythonic programming language +- A Pythonic programming language - Strong typing - Small and understandable compiler code - Efficient bytecode generation -- Deliberately has less features than Solidity with the aim of making contracts - more secure and easier to audit. Vyper does not support: +- Deliberately has fewer features than Solidity, to make contracts more secure + and easier to audit. Vyper does not support: - Modifiers - Inheritance - Inline assembly diff --git a/evm/evm-hardhat.mdx b/evm/evm-hardhat.mdx index 3be1986..53def0c 100644 --- a/evm/evm-hardhat.mdx +++ b/evm/evm-hardhat.mdx @@ -9,29 +9,29 @@ import { RunSnippet } from '/snippets/run-snippet.jsx'; import { SandboxEmbed } from '/snippets/sandbox-embed.jsx'; import { AddSeiButton } from '/snippets/add-sei-button.jsx'; -This tutorial will guide you through setting up Hardhat for Sei EVM development and using OpenZeppelin contracts to build secure, standardized smart contracts. We'll cover environment setup, contract creation, deployment, and show how to leverage OpenZeppelin's pre-built components. +This tutorial shows how to set up Hardhat for Sei EVM development. It covers environment setup, contract creation, and deployment. You use OpenZeppelin's pre-built components to build secure, standardized smart contracts. Watch the video walkthrough for this topic in the [Video Tutorials](/evm/videos) section. -**Deploy to Testnet First** +**Deploy to Sei Testnet first** -It is highly recommended that you deploy to Sei Testnet first and verify everything works as expected before committing to Sei Mainnet. Doing so helps you catch bugs early, avoid unnecessary gas costs, and keep your users safe. +We highly recommend that you deploy to Sei Testnet first. Make sure that everything works as expected before you deploy to Sei Mainnet. This helps you catch bugs early, avoid unnecessary gas costs, and keep your users safe. ## Try it before you install -Setting up the full toolchain takes a few minutes. If you just want to see a contract deploy to Sei, you can do both of these right now in the browser. +The full toolchain takes a few minutes to set up. If you only want to see a contract deploy to Sei, you can do both of these steps in the browser now. -First, confirm the RPC endpoints you'll put in `hardhat.config` respond: +First, confirm that the RPC endpoints you will use in `hardhat.config` respond: - + - + -Then add Sei Testnet to your wallet and deploy a minimal `Counter.sol` from Remix — no Node, no install. In Remix: compile under **Solidity Compiler**, then **Deploy & Run** with **Environment** set to **Injected Provider — MetaMask**. +Then add Sei Testnet to your wallet and deploy a minimal `Counter.sol` from Remix. You do not need Node.js or a local install. In Remix, compile the contract under **Solidity Compiler**. Then deploy it under **Deploy & Run**, with **Environment** set to **Injected Provider - MetaMask**. @@ -42,28 +42,28 @@ Then add Sei Testnet to your wallet and deploy a minimal `Counter.sol` from Remi description="Remix IDE with a minimal Counter contract preloaded. Compile in-browser, then deploy to Sei Testnet." /> -## Table of Contents +## Table of contents - [Try it before you install](#try-it-before-you-install) - [Prerequisites](#prerequisites) -- [Setting Up Your Development Environment](#setting-up-your-development-environment) +- [Setting up your development environment](#setting-up-your-development-environment) - [Configuring Hardhat for Sei EVM](#configuring-hardhat-for-sei-evm) -- [Using OpenZeppelin Contracts](#using-openzeppelin-contracts) -- [Creating and Deploying an ERC20 Token, ERC721 NFT or an Upgradeable UUPS Token ](#creating-and-deploying-an-erc20-token) -- [Testing Your Smart Contracts](#testing-your-smart-contracts) +- [Using OpenZeppelin contracts](#using-openzeppelin-contracts) +- [Creating and deploying an ERC20 token, ERC721 NFT or an upgradeable UUPS token](#creating-and-deploying-an-erc20-token) +- [Testing your smart contracts](#testing-your-smart-contracts) - [Deploying to Sei Testnet and Mainnet](#deploying-to-sei-testnet-and-mainnet) ## Prerequisites -Before we begin, ensure you have the following installed: +Before you start, make sure that you have installed these tools: - [Node.js](https://nodejs.org/) (v18.0.0 or later) - [npm](https://www.npmjs.com/) (v7.0.0 or later) or [yarn](https://yarnpkg.com/) - A code editor (VS Code recommended) -## Setting Up Your Development Environment +## Setting up your development environment -Let's create a new project and set up Hardhat: +Create a new project and set up Hardhat: ```bash # Create a new directory for your project @@ -74,7 +74,7 @@ cd sei-hardhat-project npx hardhat --init ``` -When prompted, choose **Hardhat 3** and **a TypeScript project using Mocha and Ethers.js**, then follow the prompts. This generates an ESM project (`"type": "module"` in `package.json`) with `@nomicfoundation/hardhat-toolbox-mocha-ethers`, `ethers`, Hardhat Ignition, TypeScript, and a ready-to-use `tsconfig.json`. +When prompted, choose **Hardhat 3** and **a TypeScript project using Mocha and Ethers.js**. Then follow the prompts. This generates an ESM project (`"type": "module"` in `package.json`) with `@nomicfoundation/hardhat-toolbox-mocha-ethers`, `ethers`, Hardhat Ignition, TypeScript, and a ready-to-use `tsconfig.json`. Then add the OpenZeppelin contract library: @@ -83,7 +83,7 @@ npm install @openzeppelin/contracts ``` -Prefer a non-interactive setup (CI or scripted environments)? Do the same thing by hand — no prompts: +For a non-interactive setup (CI or scripted environments), do the same steps manually, without prompts: ```bash npm init -y @@ -91,12 +91,12 @@ npm pkg set type=module npm install --save-dev hardhat @nomicfoundation/hardhat-toolbox-mocha-ethers @openzeppelin/contracts typescript @types/node ``` -The `@nomicfoundation/hardhat-toolbox-mocha-ethers` bundle pulls in `ethers`, Ignition, Mocha/Chai, and the keystore, network-helpers, verify, and typechain plugins — so this single install covers everything in this guide. If you hit peer-dependency errors, re-run with `--legacy-peer-deps`. +The `@nomicfoundation/hardhat-toolbox-mocha-ethers` bundle includes `ethers`, Ignition, Mocha and Chai, and the keystore, network-helpers, verify, and typechain plugins. This single install covers everything in this guide. If you get peer-dependency errors, run the install again with `--legacy-peer-deps`. ## Configuring Hardhat for Sei EVM -Next, we'll need to configure Hardhat to work with the Sei EVM. Update your `hardhat.config.ts` file: +Next, configure Hardhat to work with the Sei EVM. Update your `hardhat.config.ts` file: ```typescript title="hardhat.config.ts" import type { HardhatUserConfig } from 'hardhat/config'; @@ -138,27 +138,27 @@ const config: HardhatUserConfig = { export default config; ``` -Hardhat 3 is ESM-first and requires `"type": "module"` in `package.json` (the scaffold sets this for you). Each network needs an explicit `type: 'http'`, and plugins load via the `plugins` array rather than the Hardhat 2 side-effect `import '@nomicfoundation/hardhat-toolbox'`. A local simulated network is provided automatically — no `hardhat`/`localhost` entry required. +Hardhat 3 is ESM-first and requires `"type": "module"` in `package.json`. The scaffold sets this for you. Each network needs an explicit `type: 'http'`. Plugins load through the `plugins` array, not through the Hardhat 2 side-effect `import '@nomicfoundation/hardhat-toolbox'`. A local simulated network is available automatically, so you do not need a `hardhat` or `localhost` entry. -Hardhat 3 reads secrets through `configVariable(...)`, backed by an encrypted keystore — so your key is never stored in a plaintext file. Set it once: +Hardhat 3 reads secrets through `configVariable(...)`, which reads from an encrypted keystore. Hardhat never stores your key in a plaintext file. Set the key once: ```bash npx hardhat keystore set SEI_PRIVATE_KEY ``` -You'll be prompted to paste the private key of the account you deploy from; Hardhat stores it encrypted on your machine. For CI, export a `SEI_PRIVATE_KEY` environment variable instead — `configVariable` falls back to it. +Hardhat prompts you to paste the private key of the account that you deploy from. It stores the key encrypted on your machine. For CI, export a `SEI_PRIVATE_KEY` environment variable instead. `configVariable` falls back to this variable. -Use a dedicated, throwaway deploy key funded with only what you need — never a personal wallet holding real funds. +Use a dedicated, throwaway deploy key that holds only the funds you need. Never use a personal wallet that holds real funds. -## Using OpenZeppelin Contracts +## Using OpenZeppelin contracts -OpenZeppelin provides a library of secure, tested smart contract components that you can use to build your applications. The `@openzeppelin/contracts` package was already installed during setup, so you're ready to import its contracts directly. +OpenZeppelin has a library of secure, tested smart contract components that you can use to build your dApps. You installed the `@openzeppelin/contracts` package during setup, so you can import its contracts directly. -## Creating and Deploying an ERC20 Token, ERC721 NFT or an Upgradeable UUPS Token +## Creating and deploying an ERC20 token, ERC721 NFT or an upgradeable UUPS token -Let's create a simple ERC20 token using OpenZeppelin contracts. Create a new file in the `contracts` directory called `SeiToken.sol`: +To create a simple ERC20 token with OpenZeppelin contracts, add a new file named `SeiToken.sol` to the `contracts` directory: ```solidity title="contracts/SeiToken.sol" // SPDX-License-Identifier: MIT @@ -188,7 +188,7 @@ contract SeiToken is ERC20, Ownable { } ``` -Now, create a deployment script in the `ignition/modules` directory called `deploy-sei-token.ts`: +Next, create a deployment script named `deploy-sei-token.ts` in the `ignition/modules` directory: ```typescript title="ignition/modules/deploy-sei-token.ts" import { buildModule } from '@nomicfoundation/hardhat-ignition/modules'; @@ -202,7 +202,7 @@ export default buildModule('SeiTokenModule', (m) => { }); ``` -To deploy the token to Sei Testnet: +To deploy the token to Sei Testnet, run this command: ```bash npx hardhat ignition deploy ignition/modules/deploy-sei-token.ts --network seitestnet @@ -211,7 +211,7 @@ npx hardhat ignition deploy ignition/modules/deploy-sei-token.ts --network seite -Now, let's create an ERC721 NFT contract. Create a new file `SeiNFT.sol` in the `contracts` directory: +To create an ERC721 NFT contract, add a new file named `SeiNFT.sol` to the `contracts` directory: ```solidity title="contracts/SeiNFT.sol" // SPDX-License-Identifier: MIT @@ -304,7 +304,7 @@ contract SeiNFT is ERC721, ERC721Enumerable, ERC721URIStorage, ERC721Pausable, O } ``` -Create a deployment script `deploy-sei-nft.ts`: +Create a deployment script named `deploy-sei-nft.ts`: ```typescript title="scripts/deploy-sei-nft.ts" import { network } from 'hardhat'; @@ -342,21 +342,21 @@ npx hardhat run scripts/deploy-sei-nft.ts --network seitestnet -Upgradeable contracts allow you to modify the contract's logic after deployment without changing the contract address, which is crucial for fixing bugs or adding new features. The UUPS (Universal Upgradeable Proxy Standard) pattern is a popular way to implement upgradeability. +With an upgradeable contract, you can change the contract's logic after deployment without changing the contract address. You can use this to fix bugs or add new features. The UUPS (Universal Upgradeable Proxy Standard) pattern is a popular way to implement upgradeability. -For upgradeable contracts, also install the upgradeable variant of the OpenZeppelin library (the `@openzeppelin/contracts` package you installed earlier supplies the ERC1967 proxy): +The `@openzeppelin/contracts` package that you installed earlier includes the ERC1967 proxy. For upgradeable contracts, also install the upgradeable variant of the OpenZeppelin library: ```bash npm install @openzeppelin/contracts-upgradeable ``` -OpenZeppelin's `@openzeppelin/hardhat-upgrades` plugin is built for Hardhat 2 and does not register with Hardhat 3's `plugins` array. So this guide deploys the proxy directly using the ERC1967 standard and upgrades through UUPS `upgradeToAndCall` — no extra plugin, fully Hardhat 3-native. The tradeoff: you don't get the plugin's automatic storage-layout safety checks, so make sure each new version only **appends** state variables. You can validate layouts separately with [`@openzeppelin/upgrades-core`](https://www.npmjs.com/package/@openzeppelin/upgrades-core). +OpenZeppelin's `@openzeppelin/hardhat-upgrades` plugin is built for Hardhat 2 and does not register with Hardhat 3's `plugins` array. For this reason, this guide deploys the proxy directly with the ERC1967 standard and upgrades it through the UUPS `upgradeToAndCall` function. This method needs no extra plugin and is fully native to Hardhat 3. The tradeoff is that you do not get the plugin's automatic storage-layout safety checks. Make sure that each new version only **appends** state variables. You can validate layouts separately with [`@openzeppelin/upgrades-core`](https://www.npmjs.com/package/@openzeppelin/upgrades-core). -No `hardhat.config.ts` changes are needed beyond the configuration shown earlier. +You do not need to change `hardhat.config.ts` beyond the configuration shown earlier. -Now, let's create an upgradeable ERC20 token. Create `contracts/UpgradeableSeiToken.sol`: +Next, create the upgradeable ERC20 token in `contracts/UpgradeableSeiToken.sol`: ```solidity title="contracts/UpgradeableSeiToken.sol" // SPDX-License-Identifier: MIT @@ -400,9 +400,9 @@ contract UpgradeableSeiToken is Initializable, ERC20Upgradeable, OwnableUpgradea } ``` -Note the `Initializable` base, the `initializer` modifier, the `__ERC20_init` / `__Ownable_init` calls, and the `_authorizeUpgrade` override — these are what make the contract safe to run behind a proxy. (OpenZeppelin v5's `UUPSUpgradeable` is stateless, so there is no `__UUPSUpgradeable_init` to call.) +The `Initializable` base, the `initializer` modifier, the `__ERC20_init` and `__Ownable_init` calls, and the `_authorizeUpgrade` override make the contract safe to run behind a proxy. In OpenZeppelin v5, `UUPSUpgradeable` is stateless, so there is no `__UUPSUpgradeable_init` to call. -Add a thin, named ERC1967 proxy so Hardhat emits an artifact you can deploy by name. Create `contracts/SeiTokenProxy.sol`: +Add a thin, named ERC1967 proxy so that Hardhat emits an artifact that you can deploy by name. Create `contracts/SeiTokenProxy.sol`: ```solidity title="contracts/SeiTokenProxy.sol" // SPDX-License-Identifier: MIT @@ -417,7 +417,7 @@ contract SeiTokenProxy is ERC1967Proxy { } ``` -Now create a deployment script `scripts/deploy-upgradeable-token.ts`. It deploys the implementation, then deploys the proxy with the `initialize` call encoded as constructor data so initialization happens atomically: +Next, create a deployment script named `scripts/deploy-upgradeable-token.ts`. The script deploys the implementation first. Then it deploys the proxy with the `initialize` call encoded as constructor data, so initialization happens atomically: ```typescript title="scripts/deploy-upgradeable-token.ts" import { network } from 'hardhat'; @@ -445,15 +445,15 @@ console.log('Implementation:', await implementation.getAddress()); console.log('Version:', await token.version()); // V1 ``` -Deploy this to the testnet: +Deploy the contract to Sei Testnet: ```bash npx hardhat run scripts/deploy-upgradeable-token.ts --network seitestnet ``` -**Upgrading the Contract** +**Upgrading the contract** -Let's say you want to add a new feature or fix a bug. Create a new version of the contract, `contracts/UpgradeableSeiTokenV2.sol`: +To add a new feature or fix a bug, create a new version of the contract, `contracts/UpgradeableSeiTokenV2.sol`: ```solidity title="contracts/UpgradeableSeiTokenV2.sol" // SPDX-License-Identifier: MIT @@ -481,7 +481,7 @@ contract UpgradeableSeiTokenV2 is UpgradeableSeiToken { } ``` -Now, create an upgrade script `scripts/upgrade-token.ts`. **Replace `PROXY_ADDRESS` with the address printed when you deployed the proxy.** +Next, create an upgrade script named `scripts/upgrade-token.ts`. **Replace `PROXY_ADDRESS` with the proxy address that the deployment script printed.** ```typescript title="scripts/upgrade-token.ts" import { network } from 'hardhat'; @@ -514,14 +514,14 @@ Run the upgrade script: npx hardhat run scripts/upgrade-token.ts --network seitestnet ``` -You have now successfully deployed and upgraded a UUPS contract on the Sei network using Hardhat and OpenZeppelin! +You have deployed and upgraded a UUPS contract on Sei with Hardhat and OpenZeppelin. -## Testing Your Smart Contracts +## Testing your smart contracts -Hardhat makes it easy to test your contracts before deploying them. Create a test file `test/sei-token-test.ts`: +Hardhat lets you test your contracts before you deploy them. Create a test file named `test/sei-token-test.ts`: ```typescript title="test/sei-token-test.ts" import { expect } from 'chai'; @@ -597,7 +597,7 @@ describe('SeiToken', function () { }); ``` -Run your tests with: +Run your tests: ```bash npx hardhat test @@ -605,18 +605,18 @@ npx hardhat test ## Deploying to Sei Testnet and Mainnet -Once you've tested your contracts, you can deploy them to Sei Testnet or Sei Mainnet. To deploy, you'll need: +After you test your contracts, you can deploy them to Sei Testnet or Sei Mainnet. To deploy, you need: 1. SEI tokens in your wallet for gas -2. Your private key stored in the encrypted keystore (`npx hardhat keystore set SEI_PRIVATE_KEY`) — or exported as a `SEI_PRIVATE_KEY` environment variable in CI +2. Your private key stored in the encrypted keystore (`npx hardhat keystore set SEI_PRIVATE_KEY`), or exported as a `SEI_PRIVATE_KEY` environment variable in CI -Deploy to the testnet: +Deploy to Sei Testnet: ```bash npx hardhat ignition deploy ignition/modules/deploy-sei-token.ts --network seitestnet ``` -Deploy to the mainnet (only when you're ready for production): +Deploy to Sei Mainnet only when you are ready for production: ```bash npx hardhat ignition deploy ignition/modules/deploy-sei-token.ts --network seimainnet diff --git a/evm/evm-parity/evm-compatibility.mdx b/evm/evm-parity/evm-compatibility.mdx index 2bdbacf..3688eb9 100644 --- a/evm/evm-parity/evm-compatibility.mdx +++ b/evm/evm-parity/evm-compatibility.mdx @@ -4,51 +4,51 @@ sidebarTitle: 'Compatibility Matrix' description: 'EVM feature support on Sei — what works, what differs from Ethereum, and what is not available' --- -# EVM Compatibility +# EVM compatibility -This page documents Sei's EVM feature support. Each row shows whether a capability works as on standard Ethereum, behaves differently in a documented way, or is not available on Sei. +This page documents EVM feature support on Sei. Each row shows whether a feature works as it does on standard Ethereum, behaves differently in a documented way, or is not available on Sei. -Standard EVM tooling — viem, wagmi, ethers, Foundry, Hardhat — works on Sei for all rows marked **Supported**. Where Sei differs from Ethereum, the difference is noted so you can account for it in your application. +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. -## Status Legend +## Status legend | Status | Meaning | | --- | --- | | Supported | Works on Sei EVM with standard Ethereum behavior. | -| Supported — differences | Available on Sei, but intentionally differs from Ethereum. See the notes. | -| Sei extension | A Sei-specific capability with no standard Ethereum equivalent. | +| Supported with differences | Available on Sei, but intentionally differs from Ethereum. See the notes. | +| Sei extension | A Sei-specific feature with no standard Ethereum equivalent. | | Not supported | Not available on Sei EVM. | ## Transactions | Feature | Sei status | Notes | | --- | --- | --- | -| Legacy transactions (type 0) | Supported — differences | Minimum gas price is set by Sei governance parameters, not a fixed floor. [See Gas and Fees.](/evm/evm-parity/gas-and-fees) | +| Legacy transactions (type 0) | Supported with differences | The minimum gas price comes from Sei governance parameters, not a fixed floor. [See Gas and Fees.](/evm/evm-parity/gas-and-fees) | | EIP-2930 access list transactions (type 1) | Supported | | -| EIP-1559 fee market transactions (type 2) | Supported — differences | No base-fee burning. Fees go to validators rather than being burned. [See Gas and Fees.](/evm/evm-parity/gas-and-fees) | +| EIP-1559 fee market transactions (type 2) | Supported with differences | Sei does not burn the base fee. Fees go to validators instead. [See Gas and Fees.](/evm/evm-parity/gas-and-fees) | | EIP-4844 blob transactions (type 3) | Not supported | Sei runs Pectra without blob transactions. [See Transaction Types.](/evm/evm-parity/transaction-types) | | EIP-7702 set-code transactions (type 4) | Supported | | -## Account and State +## Account and state | Feature | Sei status | Notes | | --- | --- | --- | | `eth_getBalance` | Supported | | | `eth_getTransactionCount` (nonce) | Supported | | | `eth_getCode` | Supported | | -| `eth_getStorageAt` | Supported — differences | SSTORE cost is governance-adjustable; do not hard-code gas assumptions. [See Gas and Fees.](/evm/evm-parity/gas-and-fees) | -| `eth_getProof` | Supported — differences | Returns IAVL proof data rather than Ethereum Merkle Patricia Trie proofs. Proof verification logic must account for this. Proofs resolve across supported store backends (classic IAVL, store/v2 memiavl, and other proof-capable queryable stores), so the method works across a broader range of node configurations. [See State Proofs.](/evm/evm-parity/state-proofs) | +| `eth_getStorageAt` | Supported with differences | Governance can adjust the SSTORE cost. Do not hard-code gas assumptions. [See Gas and Fees.](/evm/evm-parity/gas-and-fees) | +| `eth_getProof` | Supported with differences | Returns IAVL proof data, not Ethereum Merkle Patricia Trie proofs. Proof verification logic must account for this. Proofs resolve across the supported store backends (classic IAVL, store/v2 memiavl, and other proof-capable queryable stores). As a result, the method works across a broader range of node configurations. [See State Proofs.](/evm/evm-parity/state-proofs) | -## Blocks and Finality +## Blocks and finality | Feature | Sei status | Notes | | --- | --- | --- | | `eth_getBlockByHash`, `eth_getBlockByNumber` | Supported | | | `eth_blockNumber` | Supported | | -| Finality tags (`latest`, `safe`, `finalized`) | Supported — differences | Sei has instant finality. All three tags refer to the same commitment level. [See Finality.](/evm/evm-parity/finality) | -| Pending block state | Supported — differences | Ethereum-style pending state visibility is not guaranteed. Do not rely on pending transaction ordering. [See Finality.](/evm/evm-parity/finality) | +| Finality tags (`latest`, `safe`, `finalized`) | Supported with differences | Sei has instant finality. All three tags refer to the same commitment level. [See Finality.](/evm/evm-parity/finality) | +| Pending block state | Supported with differences | Sei does not guarantee Ethereum-style pending state visibility. Do not rely on pending transaction ordering. [See Finality.](/evm/evm-parity/finality) | -## Logs, Filters, and Subscriptions +## Logs, filters, and subscriptions | Feature | Sei status | Notes | | --- | --- | --- | @@ -56,7 +56,7 @@ Standard EVM tooling — viem, wagmi, ethers, Foundry, Hardhat — works on Sei | Filter lifecycle (`eth_newFilter`, `eth_getFilterChanges`, `eth_getFilterLogs`, `eth_uninstallFilter`) | Supported | | | WebSocket subscriptions (`eth_subscribe`) | Supported | [See WebSocket Connections.](/evm/evm-parity/websocket) | -## Execution and Simulation +## Execution and simulation | Feature | Sei status | Notes | | --- | --- | --- | @@ -70,11 +70,11 @@ Standard EVM tooling — viem, wagmi, ethers, Foundry, Hardhat — works on Sei | Feature | Sei status | Notes | | --- | --- | --- | | EIP-155 replay protection | Supported | | -| Personal sign (`personal_sign`, `eth_sign`) | Supported | Depends on the connected wallet exposing the method. [See Signing.](/evm/evm-parity/signing) | -| EIP-712 typed data signing (`eth_signTypedData_v4`) | Supported | Depends on the connected wallet exposing the method. [See Signing.](/evm/evm-parity/signing) | +| Personal sign (`personal_sign`, `eth_sign`) | Supported | Depends on whether the connected wallet exposes the method. [See Signing.](/evm/evm-parity/signing) | +| EIP-712 typed data signing (`eth_signTypedData_v4`) | Supported | Depends on whether the connected wallet exposes the method. [See Signing.](/evm/evm-parity/signing) | | EIP-1271 contract signature validation | Supported | [See Signing.](/evm/evm-parity/signing) | -## Token Standards +## Token standards | Feature | Sei status | Notes | | --- | --- | --- | @@ -82,56 +82,56 @@ Standard EVM tooling — viem, wagmi, ethers, Foundry, Hardhat — works on Sei | ERC-721 | Supported | | | ERC-1155 | Supported | | -## Account Abstraction +## Account abstraction | Feature | Sei status | Notes | | --- | --- | --- | | ERC-4337 | Supported | Requires a compatible bundler. Sei EVM is ERC-4337 compatible. | -## Name Services +## Name services | Feature | Sei status | Notes | | --- | --- | --- | -| ENS | Not supported | Sei does not run Ethereum mainnet ENS. Application-level name services can be deployed as contracts. | +| ENS | Not supported | Sei does not run Ethereum mainnet ENS. You can deploy application-level name services as contracts. | -## Sei Extensions +## Sei extensions -These capabilities are Sei-specific and have no standard Ethereum equivalent. They are exposed through `@sei-js` packages layered on top of standard EVM tooling. +These features are specific to Sei and have no standard Ethereum equivalent. The `@sei-js` packages expose them as a layer on top of standard EVM tooling. | Feature | Notes | | --- | --- | -| Sei precompiles (staking, governance, distribution, P256, JSON, Solo, pointers, and the CosmWasm bridge) | EVM contracts at deterministic addresses. ABIs and contract addresses are exported from `@sei-js/precompiles` for use with any standard EVM library. The retired Oracle and disabled IBC precompiles are not exported. | -| Pointer contracts (CW20 ↔ ERC-20, CW721 ↔ ERC-721, CW1155 ↔ ERC-1155) | Bridge between CosmWasm and EVM token standards. Standard ERC interfaces work against pointer contracts. Look up with `POINTERVIEW_PRECOMPILE_ADDRESS` (`0x…100A`). Register with `POINTER_PRECOMPILE_ADDRESS` (`0x…100B`). | -| Native address association (EVM ↔ Cosmos address) | Links an EVM address and a Cosmos address for the same account. Required before some Sei-native flows. | +| Sei precompiles (staking, governance, distribution, P256, JSON, Solo, pointers, and the CosmWasm bridge) | EVM contracts at deterministic addresses. `@sei-js/precompiles` exports the ABIs and contract addresses for use with any standard EVM library. It does not export the retired Oracle and disabled IBC precompiles. | +| Pointer contracts (CW20 ↔ ERC-20, CW721 ↔ ERC-721, CW1155 ↔ ERC-1155) | Bridge between CosmWasm and EVM token standards. Standard ERC interfaces work with pointer contracts. To look up a pointer, use `POINTERVIEW_PRECOMPILE_ADDRESS` (`0x…100A`). To register a pointer, use `POINTER_PRECOMPILE_ADDRESS` (`0x…100B`). | +| Native address association (EVM ↔ Cosmos address) | Links an EVM address and a Cosmos address for the same account. Some Sei-native flows require this association first. | -## Unsupported RPC Methods +## Unsupported RPC methods -The following JSON-RPC methods are either not available on Sei or will return errors: +These JSON-RPC methods are not available on Sei or return errors: ### Blob / EIP-4844 | Method | Reason | | --- | --- | | `eth_blobBaseFee` | Sei runs Pectra without blob transaction support. This method does not exist on Sei. | -| `engine_getBlobsV1` | Blob data availability endpoints are not supported. | +| `engine_getBlobsV1` | Sei does not support blob data availability endpoints. | -### Pending State +### Pending state | Method | Behavior on Sei | | --- | --- | | `eth_getBlockByNumber("pending")` | Returns `null` or the latest committed block. Sei does not maintain an Ethereum-style pending block. | -| `eth_getTransactionCount(address, "pending")` | Returns the same value as `"latest"`. Pending nonce does not differ from confirmed nonce on Sei. | -| `eth_newPendingTransactionFilter` | The filter can be created but will not reliably emit pending transactions. Use `eth_newBlockFilter` or WebSocket block subscriptions instead. | -| `eth_subscribe("newPendingTransactions")` | Supported at the RPC level but Sei does not guarantee Ethereum-style pending transaction visibility. Treat results as best-effort. | +| `eth_getTransactionCount(address, "pending")` | Returns the same value as `"latest"`. On Sei, the pending nonce is the same as the confirmed nonce. | +| `eth_newPendingTransactionFilter` | You can create the filter, but it does not reliably emit pending transactions. Use `eth_newBlockFilter` or WebSocket block subscriptions instead. | +| `eth_subscribe("newPendingTransactions")` | Supported at the RPC level, but Sei does not guarantee Ethereum-style pending transaction visibility. Treat the results as best effort. | -### Proof Verification +### Proof verification | Method | Behavior on Sei | | --- | --- | -| `eth_getProof` | Returns IAVL tree proofs, not Ethereum Merkle Patricia Trie proofs. The method itself works, but the proof format is incompatible with standard Ethereum MPT verifiers. [See State Proofs.](/evm/evm-parity/state-proofs) | +| `eth_getProof` | Returns IAVL tree proofs, not Ethereum Merkle Patricia Trie proofs. The method works, but the proof format is not compatible with standard Ethereum MPT verifiers. [See State Proofs.](/evm/evm-parity/state-proofs) | -### Deprecated / Removed Opcodes +### Deprecated / removed opcodes | Method | Reason | | --- | --- | -| `eth_accounts` | Returns an empty array on Sei RPC nodes. Use a wallet library (`eth_requestAccounts`) to get accounts from the connected user's wallet instead. | +| `eth_accounts` | Returns an empty array on Sei RPC nodes. To get accounts from the connected user's wallet, use a wallet library (`eth_requestAccounts`) instead. | diff --git a/evm/evm-parity/examples/deploy-verify.mdx b/evm/evm-parity/examples/deploy-verify.mdx index 53e5ec3..b970f77 100644 --- a/evm/evm-parity/examples/deploy-verify.mdx +++ b/evm/evm-parity/examples/deploy-verify.mdx @@ -6,25 +6,32 @@ description: 'Deploying and verifying smart contracts on Sei with viem, ethers, import { SandboxEmbed } from '/snippets/sandbox-embed.jsx'; import { AddSeiButton } from '/snippets/add-sei-button.jsx'; -Sei is EVM-compatible — standard deployment tooling works without modification. This page covers deploying a contract and verifying its source on the Sei block explorer. +Sei is EVM-compatible, so standard deployment tooling works without modification. This page shows how to deploy a contract and verify its source on the Sei block explorer. -For a deeper look at verification options (Remix, Sourcify UI, batch verification), see the [Verify Contracts](/evm/evm-verify-contracts) page. +For a deeper look at verification options (Remix, the Sourcify UI, and batch verification), see the [Verify Contracts](/evm/evm-verify-contracts) page. ## Try it: deploy from your browser -No local toolchain required — compile and deploy a contract to Sei Testnet straight from the browser. The Remix sandbox below preloads a minimal `Counter.sol`. +You do not need a local toolchain. Compile and deploy a contract to Sei Testnet directly from the browser. The Remix sandbox below preloads a minimal `Counter.sol`. First, add Sei Testnet to your wallet: -Then in Remix: compile under the **Solidity Compiler** tab, open **Deploy & Run**, set **Environment** to **Injected Provider — MetaMask**, and click **Deploy**. Sei has instant finality, so the deployment confirms in well under a second. +Then, in Remix: + +1. Compile the contract on the **Solidity Compiler** tab. +2. Open the **Deploy & Run** tab. +3. Set **Environment** to **Injected Provider - MetaMask**. +4. Click **Deploy**. + +Sei has instant finality, so the deployment confirms in well under a second. ## Deploying with viem or ethers @@ -76,7 +83,7 @@ forge create src/MyContract.sol:MyContract \ --constructor-args arg1 arg2 ``` -For testnet: +For Sei Testnet: ```bash forge create src/MyContract.sol:MyContract \ @@ -86,7 +93,7 @@ forge create src/MyContract.sol:MyContract \ ## Deploying with Hardhat -Add Sei networks to your `hardhat.config.ts` (Hardhat 3). Keep the toolbox in the `plugins` array — it ships with projects created by `npx hardhat --init` and provides Hardhat Ignition for deployments: +Add the Sei networks to your `hardhat.config.ts` (Hardhat 3). Keep the toolbox in the `plugins` array. It comes with projects that `npx hardhat --init` creates, and it includes Hardhat Ignition for deployments: ```ts import { defineConfig, configVariable } from 'hardhat/config'; @@ -112,7 +119,7 @@ export default defineConfig({ }); ``` -Store your private key in Hardhat's encrypted keystore so it never lives in a plaintext file: +Store your private key in the encrypted Hardhat keystore so that the key is never stored in a plaintext file: ```bash npx hardhat keystore set SEI_PRIVATE_KEY @@ -135,13 +142,13 @@ Then deploy it: npx hardhat ignition deploy ignition/modules/MyContract.ts --network sei ``` -## Verifying Contracts +## Verifying contracts -Sei's block explorer is [Seiscan](https://seiscan.io). The recommended verification method is [Sourcify](https://sourcify.dev/) — no API key required. +The Sei block explorer is [Seiscan](https://seiscan.io). The recommended verification method is [Sourcify](https://sourcify.dev/). It does not require an API key. ### Foundry -Verify after deployment: +Verify the contract after you deploy it: ```bash forge verify-contract \ @@ -162,17 +169,17 @@ forge create src/MyContract.sol:MyContract \ --chain-id 1329 ``` -For testnet, use `--chain-id 1328` and `--rpc-url https://evm-rpc-testnet.sei-apis.com`. +For Sei Testnet, use `--chain-id 1328` and `--rpc-url https://evm-rpc-testnet.sei-apis.com`. ### Hardhat -If you use a Hardhat toolbox (as in the config above), `hardhat-verify` is already bundled and active — skip ahead to the verify command. Without a toolbox, install the plugin: +If you use a Hardhat toolbox (as in the config above), `hardhat-verify` is already bundled and active. Skip ahead to the verify command. Without a toolbox, install the plugin: ```bash npm install --save-dev @nomicfoundation/hardhat-verify ``` -Then add it to the `plugins` array in `hardhat.config.ts` — Sourcify verification is enabled by default in `hardhat-verify` and needs no API key: +Then add it to the `plugins` array in `hardhat.config.ts`. Sourcify verification is enabled by default in `hardhat-verify` and does not need an API key: ```ts import { defineConfig, configVariable } from 'hardhat/config'; @@ -210,11 +217,11 @@ If your contract has constructor arguments: npx hardhat verify sourcify --network sei 0xDeployedContractAddress "arg1" "arg2" ``` -Running `npx hardhat verify` without the `sourcify` subtask attempts verification on all enabled providers (Etherscan, Blockscout, and Sourcify) in a single run. +Without the `sourcify` subtask, `npx hardhat verify` tries to verify the contract on all enabled providers (Etherscan, Blockscout, and Sourcify) in a single run. -## Network Reference +## Network reference -| Network | Chain ID | RPC | Explorer | +| Network | EVM chain ID | RPC | Explorer | | --- | --- | --- | --- | -| Mainnet | 1329 | `https://evm-rpc.sei-apis.com` | [seiscan.io](https://seiscan.io) | -| Testnet | 1328 | `https://evm-rpc-testnet.sei-apis.com` | [testnet.seiscan.io](https://testnet.seiscan.io) | +| Sei Mainnet | 1329 | `https://evm-rpc.sei-apis.com` | [seiscan.io](https://seiscan.io) | +| Sei Testnet | 1328 | `https://evm-rpc-testnet.sei-apis.com` | [testnet.seiscan.io](https://testnet.seiscan.io) | diff --git a/evm/evm-parity/examples/erc1155.mdx b/evm/evm-parity/examples/erc1155.mdx index 3bf8554..8a397f4 100644 --- a/evm/evm-parity/examples/erc1155.mdx +++ b/evm/evm-parity/examples/erc1155.mdx @@ -6,25 +6,25 @@ description: 'Reading and writing ERC-1155 multi-token contracts on Sei with vie import { SandboxEmbed } from '/snippets/sandbox-embed.jsx'; import { AddSeiButton } from '/snippets/add-sei-button.jsx'; -# ERC-1155 Interaction +# ERC-1155 interaction -ERC-1155 is the multi-token standard — a single contract can hold both fungible tokens (like gold coins in a game) and non-fungible tokens (like unique items), with efficient batch operations built in. Standard ERC-1155 contracts work on Sei without modification. +ERC-1155 is the multi-token standard. A single contract can hold both fungible tokens (like gold coins in a game) and non-fungible tokens (like unique items). The standard also has efficient batch operations built in. Standard ERC-1155 contracts work on Sei without modification. ## Try it: deploy an ERC-1155 -Compile and deploy a real ERC-1155 to Sei Testnet from the browser — the Remix sandbox preloads an OpenZeppelin-based `DemoMultiToken` with a public `mint(id, amount)`. Then point the read/write patterns below at your deployed address. +Compile and deploy a real ERC-1155 to Sei Testnet from the browser. The Remix sandbox preloads an OpenZeppelin-based `DemoMultiToken` with a public `mint(id, amount)` function. Then use the read and write patterns below with your deployed address. First, add Sei Testnet to your wallet: -In Remix, compile under **Solidity Compiler**, then **Deploy & Run** with **Environment** set to **Injected Provider — MetaMask**. +In Remix, compile the contract on the **Solidity Compiler** tab. Then deploy it from the **Deploy & Run** tab with **Environment** set to **Injected Provider - MetaMask**. ## Setup @@ -80,7 +80,7 @@ const writeContract = new ethers.Contract(CONTRACT, ERC1155_ABI, wallet); -## Reading a Single Balance +## Reading a single balance @@ -99,9 +99,9 @@ const balance = await readContract.balanceOf('0xOwnerAddress', 1n); -## Batch Balance Query +## Batch balance query -`balanceOfBatch` retrieves multiple owner/ID pairs in one call — the most efficient way to load a user's inventory: +`balanceOfBatch` fetches the balances for multiple owner and ID pairs in one call. This is the most efficient way to load a user's inventory: @@ -127,7 +127,7 @@ const balances = await readContract.balanceOfBatch(owners, ids); -## Reading Token Metadata URI +## Reading token metadata URI ```ts viem const uri = await client.readContract({ @@ -140,7 +140,7 @@ const uri = await client.readContract({ const resolvedUri = uri.replace('{id}', (1n).toString(16).padStart(64, '0')); ``` -## Transferring a Single Token +## Transferring a single token @@ -162,7 +162,7 @@ const receipt = await tx.wait(); -## Batch Transfer +## Batch transfer Send multiple token IDs in a single transaction: @@ -195,7 +195,7 @@ const tx = await writeContract.safeBatchTransferFrom( -## Operator Approval +## Operator approval @@ -225,7 +225,7 @@ const isApproved = await readContract.isApprovedForAll('0xOwnerAddress', '0xOper -## Watching Transfer Events +## Watching transfer events diff --git a/evm/evm-parity/examples/erc20.mdx b/evm/evm-parity/examples/erc20.mdx index 8f69b97..4ce4de7 100644 --- a/evm/evm-parity/examples/erc20.mdx +++ b/evm/evm-parity/examples/erc20.mdx @@ -6,25 +6,25 @@ description: 'Reading and writing ERC-20 tokens on Sei with viem and ethers' import { SandboxEmbed } from '/snippets/sandbox-embed.jsx'; import { AddSeiButton } from '/snippets/add-sei-button.jsx'; -# ERC-20 Interaction +# ERC-20 interaction -Standard ERC-20 contracts work on Sei without modification. This page covers the common read and write operations using viem and ethers. +Standard ERC-20 contracts work on Sei without modification. This page shows the common read and write operations with viem and ethers. ## Try it: deploy an ERC-20 -Compile and deploy a real ERC-20 to Sei Testnet from the browser — the Remix sandbox preloads an OpenZeppelin-based `DemoToken`. Then point the read/write patterns below at your deployed address. +Compile and deploy a real ERC-20 to Sei Testnet from the browser. The Remix sandbox preloads an OpenZeppelin-based `DemoToken`. Then use the read and write patterns below with your deployed address. First, add Sei Testnet to your wallet: -In Remix, compile under **Solidity Compiler**, then **Deploy & Run** with **Environment** set to **Injected Provider — MetaMask**. +In Remix, compile the contract on the **Solidity Compiler** tab. Then deploy it from the **Deploy & Run** tab with **Environment** set to **Injected Provider - MetaMask**. ## Setup @@ -84,7 +84,7 @@ const writeContract = new ethers.Contract(TOKEN, ERC20_ABI, wallet); -## Reading Token Metadata +## Reading token metadata @@ -108,7 +108,7 @@ const [name, symbol, decimals, totalSupply] = await Promise.all([ -## Reading Balances and Allowances +## Reading balances and allowances @@ -135,7 +135,7 @@ const allowance = await readContract.allowance('0xOwnerAddress', '0xSpenderAddre -## Transferring Tokens +## Transferring tokens @@ -159,7 +159,7 @@ const receipt = await tx.wait(); -## Approving a Spender +## Approving a spender @@ -193,7 +193,7 @@ const txMax = await writeContract.approve('0xSpenderAddress', ethers.MaxUint256) -## Watching Transfer Events +## Watching transfer events @@ -224,7 +224,7 @@ readContract.off('Transfer'); -## Fetching Historical Transfers +## Fetching historical transfers @@ -245,6 +245,6 @@ const logs = await readContract.queryFilter(filter, 0, 'latest'); -## CosmWasm Token Compatibility +## CosmWasm token compatibility -CW20 tokens on Sei have ERC-20 pointer contracts that expose the standard ERC-20 interface. You can use all of the patterns above against a CW20 pointer address. See [Pointer Contracts](/evm/evm-parity/examples/pointer-contracts) for how to look up the pointer address. +CW20 tokens on Sei have ERC-20 pointer contracts that expose the standard ERC-20 interface. You can use all of the patterns above with a CW20 pointer address. To look up the pointer address, see [Pointer Contracts](/evm/evm-parity/examples/pointer-contracts). diff --git a/evm/evm-parity/examples/erc721.mdx b/evm/evm-parity/examples/erc721.mdx index 97402fa..1855c8e 100644 --- a/evm/evm-parity/examples/erc721.mdx +++ b/evm/evm-parity/examples/erc721.mdx @@ -6,25 +6,25 @@ description: 'Reading and writing ERC-721 NFTs on Sei with viem and ethers' import { SandboxEmbed } from '/snippets/sandbox-embed.jsx'; import { AddSeiButton } from '/snippets/add-sei-button.jsx'; -# ERC-721 Interaction +# ERC-721 interaction -Standard ERC-721 contracts work on Sei without modification. This page covers reading token ownership, transferring NFTs, and managing approvals. +Standard ERC-721 contracts work on Sei without modification. This page shows how to read token ownership, transfer NFTs, and manage approvals. ## Try it: deploy an ERC-721 -Compile and deploy a real ERC-721 to Sei Testnet from the browser — the Remix sandbox preloads an OpenZeppelin-based `DemoNFT` with a public `mint()`. Then point the patterns below at your deployed address. +Compile and deploy a real ERC-721 to Sei Testnet from the browser. The Remix sandbox preloads an OpenZeppelin-based `DemoNFT` with a public `mint()` function. Then use the patterns below with your deployed address. First, add Sei Testnet to your wallet: -In Remix, compile under **Solidity Compiler**, then **Deploy & Run** with **Environment** set to **Injected Provider — MetaMask**. +In Remix, compile the contract on the **Solidity Compiler** tab. Then deploy it from the **Deploy & Run** tab with **Environment** set to **Injected Provider - MetaMask**. ## Setup @@ -90,7 +90,7 @@ const writeContract = new ethers.Contract(NFT, ERC721_ABI, wallet); -## Reading Token Data +## Reading token data @@ -116,7 +116,7 @@ const [owner, uri, approved] = await Promise.all([ -## Checking Ownership Count +## Checking ownership count @@ -157,7 +157,7 @@ const receipt = await tx.wait(); -## Approving a Single Token +## Approving a single token @@ -176,7 +176,7 @@ const tx = await writeContract.approve('0xOperatorAddress', 1n); -## Approving All Tokens (Operator) +## Approving all tokens (operator) @@ -208,7 +208,7 @@ const revokeTx = await writeContract.setApprovalForAll('0xOperatorAddress', fals -## Watching Transfer Events +## Watching transfer events @@ -239,6 +239,6 @@ readContract.off('Transfer'); -## CosmWasm NFT Compatibility +## CosmWasm NFT compatibility -CW721 tokens on Sei have ERC-721 pointer contracts that expose the standard ERC-721 interface. You can use all of the patterns above against a CW721 pointer address. See [Pointer Contracts](/evm/evm-parity/examples/pointer-contracts) for how to look up the pointer address. +CW721 tokens on Sei have ERC-721 pointer contracts that expose the standard ERC-721 interface. You can use all of the patterns above with a CW721 pointer address. To look up the pointer address, see [Pointer Contracts](/evm/evm-parity/examples/pointer-contracts). diff --git a/evm/evm-parity/examples/error-handling.mdx b/evm/evm-parity/examples/error-handling.mdx index ae7aac4..ff265c7 100644 --- a/evm/evm-parity/examples/error-handling.mdx +++ b/evm/evm-parity/examples/error-handling.mdx @@ -5,20 +5,20 @@ description: 'Decode contract reverts, handle wallet rejections, and recover fro import { RunSnippet } from '/snippets/run-snippet.jsx'; -# Error Handling +# Error handling Most transaction failures fall into three categories: contract reverts, wallet rejections, and RPC errors. This page shows how to decode each type and respond correctly. ## Try it: see real errors -The `RunSnippet` widget surfaces whatever the RPC returns — including failures. These two calls fail on purpose so you can see the exact error shape your code has to handle, live against Sei Mainnet. +The `RunSnippet` widget shows whatever the RPC returns, including failures. These two live calls to Sei Mainnet fail on purpose. They show the exact error shape that your code has to handle. -## Contract Reverts +## Contract reverts -When a transaction reverts, the error contains the revert reason if the contract provides one. +When a transaction reverts and the contract gives a revert reason, the error contains that reason. @@ -77,9 +77,9 @@ try { -## Simulating Before Sending +## Simulating before sending -Always simulate write calls before submitting them. Simulation runs the call against current chain state and surfaces reverts before you spend gas: +Always simulate write calls before you submit them. Simulation runs the call against the current chain state and reports reverts before you spend gas: ```ts viem import { ContractFunctionRevertedError, BaseError } from 'viem'; @@ -92,7 +92,7 @@ async function safeWrite(params: Parameters[0 } ``` -## Wallet Rejections +## Wallet rejections Users can reject signature and transaction requests. These rejections have a predictable error code: @@ -123,7 +123,7 @@ try { -## Insufficient Funds +## Insufficient funds @@ -151,9 +151,9 @@ try { -## Classifying Any Error +## Classifying any error -A utility to handle the most common cases in one place: +This utility handles the most common cases in one place: ```ts import { @@ -178,9 +178,9 @@ function classifyError(err: unknown): string { } ``` -## RPC Errors and Retries +## RPC errors and retries -Transient RPC failures (network timeouts, rate limits) can be retried. Don't retry on contract reverts or user rejections — those are deterministic. +You can retry transient RPC failures, such as network timeouts and rate limits. Do not retry contract reverts or user rejections. Those failures are deterministic. ```ts async function withRetry(fn: () => Promise, maxAttempts = 3): Promise { diff --git a/evm/evm-parity/examples/ethers-quickstart.mdx b/evm/evm-parity/examples/ethers-quickstart.mdx index ca77879..51ce8cf 100644 --- a/evm/evm-parity/examples/ethers-quickstart.mdx +++ b/evm/evm-parity/examples/ethers-quickstart.mdx @@ -6,9 +6,9 @@ description: 'Using ethers v6 with Sei in a Node.js script or browser context' import { RunSnippet } from '/snippets/run-snippet.jsx'; import { SandboxEmbed } from '/snippets/sandbox-embed.jsx'; -# ethers v6 Quickstart +# ethers v6 quickstart -This example covers ethers v6 with Sei. The patterns apply whether you are writing a Node.js script, a CLI tool, or a browser app. +This example shows how to use ethers v6 with Sei. The patterns apply whether you write a Node.js script, a CLI tool, or a browser dApp. ## Install @@ -16,13 +16,13 @@ This example covers ethers v6 with Sei. The patterns apply whether you are writi npm install ethers ``` -These snippets are TypeScript. Run any of them with no separate build step using [`tsx`](https://www.npmjs.com/package/tsx) (Node 18+): +These snippets are TypeScript. To run any of them without a separate build step, use [`tsx`](https://www.npmjs.com/package/tsx) (Node 18+): ```bash npx tsx script.ts ``` -## Read-Only Provider +## Read-only provider ```ts import { ethers } from 'ethers'; @@ -30,9 +30,9 @@ import { ethers } from 'ethers'; const provider = new ethers.JsonRpcProvider('https://evm-rpc.sei-apis.com'); ``` -## Reading Chain Data +## Reading chain data -This is the first milestone — it needs no private key. +This is the first milestone. It does not need a private key. ```ts // Any valid Sei EVM address — swap in your own @@ -48,7 +48,7 @@ const nonce = await provider.getTransactionCount(address); // number console.log('Nonce:', nonce); ``` -**You're done when you see:** +**You are done when you see:** ```text Block number: 148203117 @@ -56,11 +56,11 @@ Balance (SEI): 12.5 Nonce: 7 ``` -The exact numbers are illustrative — your block number and balance will differ. `getBlockNumber()` and `getTransactionCount()` return a `number`, while `getBalance()` returns a `bigint` in wei (format it with `ethers.formatEther()`). +The exact numbers are illustrative. Your block number and balance will differ. `getBlockNumber()` and `getTransactionCount()` return a `number`, while `getBalance()` returns a `bigint` in wei. To format the balance, use `ethers.formatEther()`. ## Try it live -Run these read-only calls against Sei Mainnet right now — no install, no private key. They're plain JSON-RPC, the same reads the script above performs. +Run these read-only calls against Sei Mainnet. You do not need to install anything or use a private key. They are plain JSON-RPC calls, the same reads that the script above performs. @@ -69,21 +69,21 @@ Run these read-only calls against Sei Mainnet right now — no install, no priva params={["0x0000000000000000000000000000000000000000", "latest"]} network="mainnet" title="eth_getBalance" - description="Balance in wei of the example address at the latest block — swap in any address." + description="Balance in wei of the example address at the latest block. You can replace the example address with any address." /> ## Edit and run -Edit and re-run the full ethers code from this page live in the browser — a real ethers v6 `JsonRpcProvider` reading **Sei Testnet**, so its block number and balances won't match the mainnet reads above: +Edit and re-run the full ethers code from this page live in the browser. The sandbox uses a real ethers v6 `JsonRpcProvider` that reads **Sei Testnet**. Its block number and balances therefore do not match the Sei Mainnet reads above: -## Browser Provider +## Browser provider In a browser context, connect to the user's injected wallet: @@ -93,17 +93,17 @@ const signer = await provider.getSigner(); const address = await signer.getAddress(); ``` -## Wallet from Private Key +## Wallet from private key -For scripts and backend services: +Use this pattern in scripts and backend services: ```ts const wallet = new ethers.Wallet('0xYourPrivateKey', provider); ``` -## Sending a Transaction +## Sending a transaction -Next step — this requires a funded account; get testnet SEI from the [faucet](/learn/faucet). +This next step requires a funded account. Get testnet SEI from the [faucet](/learn/faucet). ```ts const tx = await wallet.sendTransaction({ @@ -115,7 +115,7 @@ const receipt = await tx.wait(); // receipt is final immediately — Sei has instant finality ``` -## Reading a Contract +## Reading a contract ```ts const abi = ['function balanceOf(address owner) view returns (uint256)']; @@ -124,9 +124,9 @@ const contract = new ethers.Contract('0xTokenAddress', abi, provider); const balance = await contract.balanceOf('0xYourAddress'); ``` -## Writing to a Contract +## Writing to a contract -Pass a signer (wallet or browser signer) to the contract constructor for write operations: +For write operations, pass a signer (a wallet or a browser signer) to the contract constructor: ```ts const contract = new ethers.Contract('0xTokenAddress', abi, wallet); @@ -135,7 +135,7 @@ const tx = await contract.transfer('0xRecipient', 1_000_000n); const receipt = await tx.wait(); ``` -## Estimating Gas +## Estimating gas ```ts const gas = await provider.estimateGas({ @@ -145,7 +145,7 @@ const gas = await provider.estimateGas({ }); ``` -## Listening for Events +## Listening for events ```ts contract.on('Transfer', (from, to, value) => { @@ -156,10 +156,10 @@ contract.on('Transfer', (from, to, value) => { contract.off('Transfer'); ``` -## Next Steps +## Next steps -- [Python quickstart (web3.py)](/evm/python-quickstart) — the same first steps in Python -- [ERC-20 interaction](/evm/evm-parity/examples/erc20) — full token read/write examples -- [ERC-721 interaction](/evm/evm-parity/examples/erc721) — NFT ownership, transfers, and approvals -- [Pointer contracts](/evm/evm-parity/examples/pointer-contracts) — interact with CosmWasm tokens via ERC interfaces -- [WebSocket connections](/evm/evm-parity/websocket) — real-time block and event subscriptions +- [Python quickstart (web3.py)](/evm/python-quickstart): the same first steps in Python +- [ERC-20 interaction](/evm/evm-parity/examples/erc20): full token read and write examples +- [ERC-721 interaction](/evm/evm-parity/examples/erc721): NFT ownership, transfers, and approvals +- [Pointer contracts](/evm/evm-parity/examples/pointer-contracts): interact with CosmWasm tokens through ERC interfaces +- [WebSocket connections](/evm/evm-parity/websocket): real-time block and event subscriptions diff --git a/evm/evm-parity/examples/multicall.mdx b/evm/evm-parity/examples/multicall.mdx index 452a6e2..f57c6b3 100644 --- a/evm/evm-parity/examples/multicall.mdx +++ b/evm/evm-parity/examples/multicall.mdx @@ -7,20 +7,20 @@ import { RunSnippet } from '/snippets/run-snippet.jsx'; # Multicall -Multicall3 lets you batch multiple read calls into a single RPC round-trip, dramatically reducing latency for dashboards, portfolio pages, and any view that needs data from multiple contracts at once. +Multicall3 lets you batch multiple read calls into a single RPC round trip. This greatly reduces latency for dashboards, portfolio pages, and any view that needs data from multiple contracts at once. -Multicall3 is deployed at `0xcA11bde05977b3631167028862bE2a173976CA11` on Sei Mainnet and Sei Testnet — the same address as Ethereum. +Multicall3 is deployed at `0xcA11bde05977b3631167028862bE2a173976CA11` on Sei Mainnet and Sei Testnet. This is the same address as on Ethereum. ## Try it live -Multicall3 is a normal contract — you can hit it with a single `eth_call` and no SDK. These run its two zero-argument helpers on Sei Mainnet; the hex results decode to decimal below each response. +Multicall3 is a normal contract, so you can call it with a single `eth_call` and no SDK. These snippets run its two zero-argument helpers on Sei Mainnet. Below each response, the widget decodes the hex result to decimal. -## Batching ERC-20 Reads with viem +## Batching ERC-20 reads with viem viem's `multicall` action wraps Multicall3 automatically: @@ -77,9 +77,9 @@ tokens.forEach((address, i) => { }); ``` -## Allowing Individual Call Failures +## Allowing individual call failures -By default, a single failed call causes the entire batch to revert. Use `allowFailure: true` (the default in viem) to get partial results instead: +By default, a single failed call causes the entire batch to revert. To get partial results instead, use `allowFailure: true` (the default in viem): ```ts const results = await client.multicall({ @@ -101,7 +101,7 @@ results.forEach((result) => { ## Batching with ethers -ethers doesn't have a built-in multicall action, but you can call the Multicall3 contract directly: +ethers does not have a built-in multicall action, but you can call the Multicall3 contract directly: ```ts import { ethers } from 'ethers'; @@ -138,9 +138,9 @@ results.forEach(({ success, returnData }: { success: boolean; returnData: string }); ``` -## Wagmi +## wagmi -In React apps, `useReadContracts` handles batching automatically: +In React dApps, `useReadContracts` handles batching automatically: ```tsx import { useReadContracts } from 'wagmi'; diff --git a/evm/evm-parity/examples/pointer-contracts.mdx b/evm/evm-parity/examples/pointer-contracts.mdx index ccc9973..6fe57d5 100644 --- a/evm/evm-parity/examples/pointer-contracts.mdx +++ b/evm/evm-parity/examples/pointer-contracts.mdx @@ -3,12 +3,12 @@ title: 'Pointer Contracts' description: 'Looking up and interacting with pointer contracts that bridge CosmWasm and EVM tokens on Sei' --- -# Pointer Contracts +# Pointer contracts -Sei runs two token execution environments side by side — EVM and CosmWasm. Pointer contracts are automatically deployed EVM contracts that proxy a CosmWasm token, and vice versa. +Sei runs two token execution environments side by side: EVM and CosmWasm. Pointer contracts are automatically deployed EVM contracts that proxy a CosmWasm token, and vice versa. -This guide covers pointers for already-deployed CosmWasm contracts only. It does not document native-denom pointer workflows. IBC is disabled in both directions, and tokenfactory is not a supported development path. See [IBC is disabled](/learn/sip-03-migration#ibc-is-disabled) and [Tokenfactory is not supported](/cosmos-sdk#tokenfactory-is-not-supported). +This guide covers pointers only for CosmWasm contracts that are already deployed. It does not document native-denom pointer workflows. IBC is disabled in both directions. Tokenfactory is not a supported development path. See [IBC is disabled](/learn/sip-03-migration#ibc-is-disabled) and [Tokenfactory is not supported](/cosmos-sdk#tokenfactory-is-not-supported). | Token | Pointer type | EVM interface | @@ -17,13 +17,13 @@ This guide covers pointers for already-deployed CosmWasm contracts only. It does | CW721 (CosmWasm NFT) | ERC-721 pointer | Standard ERC-721 | | CW1155 (CosmWasm multi-token) | ERC-1155 pointer | Standard ERC-1155 | -Once you have the pointer address, you interact with it using the standard ERC-20, ERC-721, or ERC-1155 interface. +After you have the pointer address, you interact with it through the standard ERC-20, ERC-721, or ERC-1155 interface. For background on how pointer contracts work, see the [Pointers overview](/learn/pointers). -## Looking Up a Pointer Address +## Looking up a pointer address -The pointerview precompile resolves pointer addresses for existing CosmWasm contracts. Its ABI and address are exported from `@sei-js/precompiles`. +The pointerview precompile resolves pointer addresses for existing CosmWasm contracts. `@sei-js/precompiles` exports its ABI and address. @@ -89,11 +89,11 @@ const erc1155Pointer = await pointerview.getCW1155Pointer('sei1...cw1155Contract -The return value includes the pointer address and an `exists` boolean. Check `exists` before interacting with the pointer — not all CosmWasm tokens have a deployed pointer. +The return value includes the pointer address and an `exists` boolean. Check `exists` before you interact with the pointer. Not all CosmWasm tokens have a deployed pointer. -## Interacting with a CW20 Pointer as ERC-20 +## Interacting with a CW20 pointer as ERC-20 -Once you have the pointer address, use it as a standard ERC-20 contract. +After you have the pointer address, use it as a standard ERC-20 contract. @@ -125,7 +125,7 @@ const balance = await token.balanceOf('0xYourAddress'); -## Interacting with a CW721 Pointer as ERC-721 +## Interacting with a CW721 pointer as ERC-721 @@ -157,4 +157,4 @@ const owner = await nft.ownerOf(1n); -For full ERC-20 and ERC-721 examples including transfers, approvals, and events, see the [ERC-20](/evm/evm-parity/examples/erc20) and [ERC-721](/evm/evm-parity/examples/erc721) pages. +For full ERC-20 and ERC-721 examples, including transfers, approvals, and events, see the [ERC-20](/evm/evm-parity/examples/erc20) and [ERC-721](/evm/evm-parity/examples/erc721) pages. diff --git a/evm/evm-parity/examples/sei-precompiles.mdx b/evm/evm-parity/examples/sei-precompiles.mdx index 37d4090..631f8cc 100644 --- a/evm/evm-parity/examples/sei-precompiles.mdx +++ b/evm/evm-parity/examples/sei-precompiles.mdx @@ -5,20 +5,20 @@ description: 'Interact with native Sei chain features — staking, governance, n import { RunSnippet } from '/snippets/run-snippet.jsx'; -Sei exposes native chain functionality through precompiled contracts at deterministic EVM addresses. You can call them from any EVM library (viem, ethers, wagmi) using the ABIs exported from `@sei-js/precompiles` — no special SDK required. +Sei exposes native chain functionality through precompiled contracts at deterministic EVM addresses. You can call them from any EVM library (viem, ethers, or wagmi) with the ABIs that `@sei-js/precompiles` exports. You do not need a special SDK. Available precompiles include: -- **Bank** — query the native SEI bank balance -- **Staking** — delegate, undelegate, query delegations -- **Distribution** — claim staking rewards -- **Governance** — vote on active proposals -- **JSON** — parse JSON payloads within contracts -- **P256** — verify P-256 elliptic curve signatures +- **Bank**: query the native SEI bank balance +- **Staking**: delegate, undelegate, and query delegations +- **Distribution**: claim staking rewards +- **Governance**: vote on active proposals +- **JSON**: parse JSON payloads within contracts +- **P256**: verify P-256 elliptic curve signatures ## Try it live -Precompiles are callable like any contract — even with a plain `eth_call` from the browser. This hits the **Bank** precompile at `0x0000000000000000000000000000000000001001` on Sei Mainnet, calling `name("usei")`. The response is ABI-encoded; it contains the bytes `53 45 49` — ASCII for `SEI`. +You can call precompiles like any other contract, even with a plain `eth_call` from the browser. This snippet calls `name("usei")` on the Bank precompile at `0x0000000000000000000000000000000000001001` on Sei Mainnet. The response is ABI-encoded. It contains the bytes `53 45 49`, which are ASCII for `SEI`. For installation instructions, code examples (viem and ethers), common patterns, and a full working Node.js script, see the precompiles reference: - - Usage examples for all precompiles with viem and ethers — Bank, Staking, Distribution, Governance, JSON, and P256. + + Usage examples for all precompiles with viem and ethers: Bank, Staking, Distribution, Governance, JSON, and P256. -For the full ABI reference and every available function on each precompile: +For the full ABI reference and every available function on each precompile, see these pages: - - - - - + + + + + diff --git a/evm/evm-parity/examples/transaction-lifecycle.mdx b/evm/evm-parity/examples/transaction-lifecycle.mdx index dff4151..f99ee0f 100644 --- a/evm/evm-parity/examples/transaction-lifecycle.mdx +++ b/evm/evm-parity/examples/transaction-lifecycle.mdx @@ -5,19 +5,19 @@ description: 'Send transactions, wait for receipts, and decode event logs on Sei import { RunSnippet } from '/snippets/run-snippet.jsx'; -# Transaction Lifecycle +# Transaction lifecycle -This page covers the full round-trip of a transaction: building and sending it, waiting for the receipt, and reading the event logs it emitted. +This page covers the full round trip of a transaction: building and sending it, waiting for the receipt, and reading its event logs. ## Try it live -Before you send anything, read the live chain state your transaction will interact with — straight from your browser against Sei Mainnet, no install or key required. +Before you send anything, read the live chain state that your transaction will interact with. These calls run from your browser against Sei Mainnet. You do not need to install anything or use a key. - + -## Sending a Transaction +## Sending a transaction @@ -49,7 +49,7 @@ const tx = await wallet.sendTransaction({ -## Waiting for the Receipt +## Waiting for the receipt @@ -77,11 +77,11 @@ console.log('Gas used:', receipt.gasUsed); -Sei has instant finality — the receipt is final as soon as it arrives. One confirmation is sufficient. See [Finality](/evm/evm-parity/finality). +Sei has instant finality, so the receipt is final as soon as it arrives. One confirmation is sufficient. See [Finality](/evm/evm-parity/finality). -## Decoding Event Logs from a Receipt +## Decoding event logs from a receipt -After a contract interaction, decode the events the transaction emitted: +After a contract interaction, decode the events that the transaction emitted: @@ -144,9 +144,9 @@ for (const log of receipt.logs) { -## Checking for Revert +## Checking for revert -A receipt with `status: 'reverted'` (viem) or `status: 0` (ethers) means the transaction was included but the execution failed. The gas was still consumed. +A receipt with `status: 'reverted'` (viem) or `status: 0` (ethers) means that the transaction was included but the execution failed. The transaction still consumed gas. ```ts viem const receipt = await client.waitForTransactionReceipt({ hash }); @@ -158,7 +158,7 @@ if (receipt.status === 'reverted') { } ``` -## Fetching a Past Transaction +## Fetching a past transaction ```ts viem const tx = await client.getTransaction({ hash: '0xTxHash' }); @@ -173,9 +173,9 @@ const tx = await provider.getTransaction('0xTxHash'); const receipt = await provider.getTransactionReceipt('0xTxHash'); ``` -## Getting Logs for a Specific Transaction +## Getting logs for a specific transaction -To fetch only the events emitted by a specific transaction (rather than decoding from the receipt): +To fetch only the events that a specific transaction emitted, instead of decoding them from the receipt, use this pattern: ```ts viem const logs = await client.getContractEvents({ diff --git a/evm/evm-parity/examples/viem-quickstart.mdx b/evm/evm-parity/examples/viem-quickstart.mdx index 2698475..7085f18 100644 --- a/evm/evm-parity/examples/viem-quickstart.mdx +++ b/evm/evm-parity/examples/viem-quickstart.mdx @@ -6,9 +6,9 @@ description: 'Using viem with Sei in a Node.js script, CLI tool, or backend serv import { RunSnippet } from '/snippets/run-snippet.jsx'; import { SandboxEmbed } from '/snippets/sandbox-embed.jsx'; -# viem Quickstart +# viem quickstart -This example shows how to use viem with Sei outside of a React context — in a Node.js script, CLI tool, or backend service. For React apps, see [wagmi](https://wagmi.sh) and the [frontend guide](/evm/building-a-frontend). +This example shows how to use viem with Sei outside a React context: in a Node.js script, a CLI tool, or a backend service. For React dApps, see [wagmi](https://wagmi.sh) and the [frontend guide](/evm/building-a-frontend). ## Install @@ -16,13 +16,13 @@ This example shows how to use viem with Sei outside of a React context — in a npm install viem ``` -These snippets are TypeScript. Run any of them with no separate build step using [`tsx`](https://www.npmjs.com/package/tsx) (Node 18+): +These snippets are TypeScript. To run any of them without a separate build step, use [`tsx`](https://www.npmjs.com/package/tsx) (Node 18+): ```bash npx tsx script.ts ``` -## Public Client +## Public client A public client handles all read-only operations. @@ -45,9 +45,9 @@ const client = createPublicClient({ }); ``` -## Reading Chain Data +## Reading chain data -This is the first milestone — it needs no private key. +This is the first milestone. It does not need a private key. ```ts import { formatEther } from 'viem'; @@ -65,7 +65,7 @@ const nonce = await client.getTransactionCount({ address }); // number console.log('Nonce:', nonce); ``` -**You're done when you see:** +**You are done when you see:** ```text Block number: 148203117n @@ -73,13 +73,13 @@ Balance (SEI): 12.5 Nonce: 7 ``` -The exact numbers are illustrative — your block number and balance will differ. Note the trailing `n`: `getBlockNumber()` and `getBalance()` return `bigint`, while `getTransactionCount()` returns a `number`. +The exact numbers are illustrative. Your block number and balance will differ. Note the trailing `n`: `getBlockNumber()` and `getBalance()` return a `bigint`, while `getTransactionCount()` returns a `number`. ## Try it live -Run these read-only calls against Sei Mainnet right now — no install, no private key. They're the same reads the script above performs, issued straight from your browser. +Run these read-only calls against Sei Mainnet. You do not need to install anything or use a private key. They are the same reads that the script above performs, sent directly from your browser. - + @@ -88,21 +88,21 @@ Run these read-only calls against Sei Mainnet right now — no install, no priva params={["0x0000000000000000000000000000000000000000", "latest"]} network="mainnet" title="eth_getBalance" - description="Balance in wei of the example address at the latest block — swap in any address." + description="Balance in wei of the example address at the latest block. You can replace the example address with any address." /> ## Edit and run -The buttons above issue raw JSON-RPC. To run the full viem code from this page — imports, a public client, several reads — edit and re-run it live in the sandbox below. No install, no wallet, no key. Note the sandbox reads **Sei Testnet**, so its block number and balances won't match the mainnet reads above: +The buttons above send raw JSON-RPC requests. The sandbox below runs the full viem code from this page: imports, a public client, and several reads. You can edit and re-run it live. You do not need to install anything, connect a wallet, or use a key. The sandbox reads **Sei Testnet**, so its block number and balances do not match the Sei Mainnet reads above: -## Wallet Client +## Wallet client A wallet client handles signing and broadcasting transactions. @@ -120,11 +120,11 @@ const walletClient = createWalletClient({ }); ``` -For browser use, replace `http()` with `custom(window.ethereum)` and call `walletClient.getAddresses()` to get the connected account. +For browser use, replace `http()` with `custom(window.ethereum)`. Then call `walletClient.getAddresses()` to get the connected account. -## Sending a Transaction +## Sending a transaction -Next step — this requires a funded account; get testnet SEI from the [faucet](/learn/faucet). +This next step requires a funded account. Get testnet SEI from the [faucet](/learn/faucet). ```ts import { parseEther } from 'viem'; @@ -138,7 +138,7 @@ const receipt = await client.waitForTransactionReceipt({ hash }); // receipt is final immediately — Sei has instant finality ``` -## Reading a Contract +## Reading a contract ```ts import { parseAbi } from 'viem'; @@ -153,7 +153,7 @@ const balance = await client.readContract({ }); ``` -## Writing to a Contract +## Writing to a contract ```ts const hash = await walletClient.writeContract({ @@ -166,7 +166,7 @@ const hash = await walletClient.writeContract({ const receipt = await client.waitForTransactionReceipt({ hash }); ``` -## Simulating Before Writing +## Simulating before writing ```ts const { result } = await client.simulateContract({ @@ -181,9 +181,9 @@ const { result } = await client.simulateContract({ const hash = await walletClient.writeContract(result); ``` -## Estimating Gas +## Estimating gas -Always use `estimateGas` rather than hard-coding values. SSTORE costs on Sei are governance-adjustable. +Always use `estimateGas` instead of hard-coded values. Governance can adjust SSTORE costs on Sei. ```ts const gas = await client.estimateGas({ @@ -193,10 +193,10 @@ const gas = await client.estimateGas({ }); ``` -## Next Steps +## Next steps -- [Python quickstart (web3.py)](/evm/python-quickstart) — the same first steps in Python -- [ERC-20 interaction](/evm/evm-parity/examples/erc20) — full token read/write examples -- [ERC-721 interaction](/evm/evm-parity/examples/erc721) — NFT ownership, transfers, and approvals -- [Pointer contracts](/evm/evm-parity/examples/pointer-contracts) — interact with CosmWasm tokens via ERC interfaces -- [WebSocket connections](/evm/evm-parity/websocket) — real-time block and event subscriptions +- [Python quickstart (web3.py)](/evm/python-quickstart): the same first steps in Python +- [ERC-20 interaction](/evm/evm-parity/examples/erc20): full token read and write examples +- [ERC-721 interaction](/evm/evm-parity/examples/erc721): NFT ownership, transfers, and approvals +- [Pointer contracts](/evm/evm-parity/examples/pointer-contracts): interact with CosmWasm tokens through ERC interfaces +- [WebSocket connections](/evm/evm-parity/websocket): real-time block and event subscriptions diff --git a/evm/evm-parity/examples/wagmi-react.mdx b/evm/evm-parity/examples/wagmi-react.mdx index 1489047..44df2c5 100644 --- a/evm/evm-parity/examples/wagmi-react.mdx +++ b/evm/evm-parity/examples/wagmi-react.mdx @@ -5,21 +5,21 @@ description: 'Connect wallets, read chain state, and write transactions in a Rea import { RunSnippet } from '/snippets/run-snippet.jsx'; -# Wagmi + React +# wagmi + React -[Wagmi](https://wagmi.sh) is the standard React library for EVM wallet connections and contract interactions. This page covers the essential patterns for a Sei frontend: configuration, wallet connect/disconnect, reading balances, and writing to contracts. +[wagmi](https://wagmi.sh) is the standard React library for EVM wallet connections and contract interactions. This page covers the essential patterns for a Sei frontend: configuration, connecting and disconnecting a wallet, reading balances, and writing to contracts. For Node.js scripts and backend services, see the [viem Quickstart](/evm/evm-parity/examples/viem-quickstart) instead. ## Try it live -The hooks below — `useBlockNumber`, `useBalance` — are thin wrappers over JSON-RPC reads. Here are those same reads issued directly against Sei Mainnet, no wallet connection required, so you can see the data your components will render. +The hooks below (`useBlockNumber` and `useBalance`) are thin wrappers over JSON-RPC reads. These snippets send the same reads directly to Sei Mainnet, without a wallet connection. They show the data that your components will render. ## Install @@ -38,7 +38,7 @@ npm install wagmi viem @sei-js/precompiles@^3 @tanstack/react-query ## Configuration -Configure Wagmi with the Sei chain and your preferred wallet connectors: +Configure wagmi with Sei Mainnet, Sei Testnet, and your preferred wallet connectors: ```ts // wagmi.config.ts @@ -59,9 +59,9 @@ export const config = createConfig({ }); ``` -## Provider Setup +## Provider setup -Wrap your app with `WagmiProvider` and `QueryClientProvider`: +Wrap your dApp with `WagmiProvider` and `QueryClientProvider`: ```tsx // App.tsx @@ -82,7 +82,7 @@ export function App() { } ``` -## Connecting a Wallet +## Connecting a wallet ```tsx import { useConnect, useDisconnect, useAccount } from 'wagmi'; @@ -113,7 +113,7 @@ export function WalletButton() { } ``` -## Reading the Native SEI Balance +## Reading the native SEI balance ```tsx import { useBalance, useAccount } from 'wagmi'; @@ -131,7 +131,7 @@ export function SeiBalance() { } ``` -## Reading a Contract +## Reading a contract ```tsx import { useReadContract } from 'wagmi'; @@ -162,9 +162,9 @@ export function TokenBalance({ tokenAddress, owner }: { tokenAddress: `0x${strin } ``` -## Writing to a Contract +## Writing to a contract -Use `useWriteContract` for transactions that mutate state, and `useWaitForTransactionReceipt` to track confirmation: +Use `useWriteContract` for transactions that change state. Use `useWaitForTransactionReceipt` to track confirmation: ```tsx import { useWriteContract, useWaitForTransactionReceipt } from 'wagmi'; @@ -198,9 +198,9 @@ export function TransferButton({ tokenAddress }: { tokenAddress: `0x${string}` } } ``` -Sei has instant finality — `useWaitForTransactionReceipt` resolves as soon as the transaction is included in a block. A single confirmation is final. See [Finality](/evm/evm-parity/finality). +Sei has instant finality, so `useWaitForTransactionReceipt` resolves as soon as the transaction is included in a block. A single confirmation is final. See [Finality](/evm/evm-parity/finality). -## Watching the Connected Chain +## Watching the connected chain ```tsx import { useChainId, useSwitchChain } from 'wagmi'; diff --git a/evm/evm-parity/finality.mdx b/evm/evm-parity/finality.mdx index f4a4cc9..5d60539 100644 --- a/evm/evm-parity/finality.mdx +++ b/evm/evm-parity/finality.mdx @@ -3,21 +3,21 @@ title: 'Finality and Block Tags' description: 'How Sei instant finality affects block tag behavior and pending state' --- -# Finality and Block Tags +# Finality and block tags -Sei uses Twin Turbo Consensus, which provides instant finality. Every committed block is final immediately — there is no period where a block could be reorganized away. +Sei uses Twin Turbo Consensus, which gives instant finality. Every committed block is final immediately. There is no period in which a reorganization could remove it. -This changes how block tags behave compared to Ethereum. +Because of this, block tags behave differently on Sei than on Ethereum. -## Block Tags +## Block tags On Ethereum, `latest`, `safe`, and `finalized` refer to different points in the chain: -- `latest` — the most recent block, possibly not yet safe -- `safe` — a block unlikely to be reorganized -- `finalized` — a block that is permanently committed +- `latest`: the most recent block, possibly not yet safe +- `safe`: a block that is unlikely to be reorganized +- `finalized`: a block that is permanently committed -On Sei, all three tags resolve to the same block. There is no reorg risk at any point after a block is committed, so the distinction does not exist. +On Sei, all three tags resolve to the same block. After a block is committed, there is no reorg risk at any point, so the distinction does not exist. @@ -46,7 +46,7 @@ const finalized = await provider.getBlock('finalized'); -## Waiting for Confirmation +## Waiting for confirmation Because finality is instant, you do not need to wait for multiple confirmations. `waitForTransactionReceipt` resolves as soon as the transaction is included in a block. @@ -64,17 +64,17 @@ const receipt = await tx.wait(1); // 1 confirmation is final on Sei -## Pending State +## Pending state Sei does not expose Ethereum-style pending state. Do not rely on: - Reading pending transactions from the mempool - `eth_getBlockByNumber` with `'pending'` -- Pending nonce differing from the confirmed nonce +- A pending nonce that differs from the confirmed nonce -If your application polls pending transactions or depends on pending state visibility, replace that pattern with confirmed-block polling or WebSocket subscriptions on committed blocks. +If your application polls pending transactions or depends on pending state visibility, replace that pattern. Use confirmed-block polling or WebSocket subscriptions on committed blocks instead. -## Practical Impact +## Practical impact | Pattern | On Ethereum | On Sei | | --- | --- | --- | diff --git a/evm/evm-parity/gas-and-fees.mdx b/evm/evm-parity/gas-and-fees.mdx index 5827302..8eb79ed 100644 --- a/evm/evm-parity/gas-and-fees.mdx +++ b/evm/evm-parity/gas-and-fees.mdx @@ -3,15 +3,15 @@ title: 'Gas and Fees' description: 'Sei gas price floor, EIP-1559 fee model differences, and SSTORE cost' --- -# Gas and Fees +# Gas and fees -Sei supports both legacy and EIP-1559 transactions, but the fee model differs from Ethereum in three ways that affect how you estimate and set gas. +Sei supports both legacy and EIP-1559 transactions. However, the fee model differs from Ethereum in three ways that affect how you estimate and set gas. -## Legacy Gas Price Floor +## Legacy gas price floor -Legacy transactions (type 0) on Sei must meet a minimum gas price set by on-chain governance. This floor can change via governance proposals — do not hard-code a specific value. +Legacy transactions (type 0) on Sei must meet a minimum gas price set by on-chain governance. Governance proposals can change this floor, so do not hard-code a specific value. -Use `eth_gasPrice` to read the current minimum: +To read the current minimum, use `eth_gasPrice`: @@ -33,11 +33,11 @@ const gasPrice = feeData.gasPrice; -## EIP-1559 Fee Model +## EIP-1559 fee model -Sei supports EIP-1559 transactions (type 2), but does not burn the base fee. Fees go entirely to validators rather than being partially burned as on Ethereum. +Sei supports EIP-1559 transactions (type 2), but it does not burn the base fee. All fees go to validators. On Ethereum, part of the fee is burned. -This does not affect how you construct or send transactions — `maxFeePerGas` and `maxPriorityFeePerGas` work as expected. It is relevant only if your application models token supply or displays fee-burn information to users. +This does not affect how you construct or send transactions. `maxFeePerGas` and `maxPriorityFeePerGas` work as expected. It matters only if your application models token supply or shows fee-burn information to users. @@ -54,16 +54,16 @@ const feeData = await provider.getFeeData(); -### Effective Gas Price on Receipts +### Effective gas price on receipts -For dynamic-fee (type 2) transactions, the transaction receipt's `effectiveGasPrice` field reports the **actual price charged** — `min(baseFee + maxPriorityFeePerGas, maxFeePerGas)` — not the fee cap. This matches standard EIP-1559 semantics, so clients such as ethers and hardhat see the same `effectiveGasPrice` behavior they expect from Ethereum. +For dynamic-fee (type 2) transactions, the `effectiveGasPrice` field of the transaction receipt reports the **actual price charged**, not the fee cap. That price is `min(baseFee + maxPriorityFeePerGas, maxFeePerGas)`. This matches standard EIP-1559 semantics. Clients such as ethers and Hardhat therefore see the same `effectiveGasPrice` behavior that they expect from Ethereum. -In practice, when your priority tip plus the base fee stays below `maxFeePerGas`, the receipt reports `baseFee + maxPriorityFeePerGas` rather than `maxFeePerGas`. Use the receipt's `effectiveGasPrice` (not `maxFeePerGas`) when computing what a transaction actually paid. +In practice, when your priority tip plus the base fee stays below `maxFeePerGas`, the receipt reports `baseFee + maxPriorityFeePerGas`, not `maxFeePerGas`. To compute what a transaction paid, use the receipt's `effectiveGasPrice`, not `maxFeePerGas`. -## SSTORE Cost +## SSTORE cost -The gas cost of `SSTORE` (writing to contract storage) is governance-adjustable on Sei. It is currently **72,000 gas** — the same on mainnet and testnet (see [Divergence from Ethereum](/evm/differences-with-ethereum#sstore-gas-cost)) — but treat that as the current value, not a constant: do not hard-code storage write estimates in your application. +On Sei, governance can adjust the gas cost of `SSTORE` (a write to contract storage). The current cost is **72,000 gas** on both Sei Mainnet and Sei Testnet. For details, see [Differences with Ethereum](/evm/differences-with-ethereum#sstore-gas-cost). Treat this number as the current value, not a constant. Do not hard-code storage write estimates in your application. Always use `eth_estimateGas` for any transaction that writes to storage: @@ -90,7 +90,7 @@ const gas = await provider.estimateGas({ -A Foundry `forge test --gas-report --fork-url ` report forks chain *state* but runs revm's standard EVM gas schedule, so it shows `SSTORE` at the Ethereum cost (~22,100) rather than Sei's ~72,000. Use it for relative profiling of your own logic; estimate the absolute storage-write cost with a live `eth_estimateGas` against a Sei RPC. +Estimate the absolute storage-write cost with a live `eth_estimateGas` call against a Sei RPC. A Foundry `forge test --gas-report --fork-url ` report forks the chain *state*, but it runs the standard EVM gas schedule of revm. It therefore shows `SSTORE` at the Ethereum cost (approximately 22,100) instead of the Sei cost (approximately 72,000). Use the report for relative profiling of your own logic. ## Summary @@ -99,4 +99,4 @@ const gas = await provider.estimateGas({ | Legacy gas floor | Protocol minimum | Governance-set, can change | | Base fee | Burned | Paid to validators | | SSTORE cost | Fixed by EIP | Governance-adjustable | -| `estimateGas` | Always correct to use | Required — do not hard-code storage costs | +| `estimateGas` | Always correct to use | Required. Do not hard-code storage costs. | diff --git a/evm/evm-parity/signing.mdx b/evm/evm-parity/signing.mdx index 33658e5..d882f25 100644 --- a/evm/evm-parity/signing.mdx +++ b/evm/evm-parity/signing.mdx @@ -5,20 +5,20 @@ description: 'Wallet signing method support and EIP-712 typed data on Sei' # Signing -Signing on Sei works through standard EVM libraries and wallet standards. The methods available depend on which wallet the user has connected. +Signing on Sei works through standard EVM libraries and wallet standards. The available methods depend on which wallet the user has connected. -## Wallet Signing Support +## Wallet signing support | Method | Standard | Sei Global Wallet | MetaMask | WalletConnect wallets | | --- | --- | --- | --- | --- | | `personal_sign` | EIP-191 | Supported | Supported | Wallet-dependent | | `eth_signTypedData_v4` | EIP-712 | Supported | Supported | Wallet-dependent | | `eth_sign` | Legacy | Not recommended | Supported | Wallet-dependent | -| Transaction signing | — | Supported | Supported | Supported | +| Transaction signing | N/A | Supported | Supported | Supported | -Do not assume all wallets support all methods. Always handle rejection gracefully. +Do not assume that every wallet supports every method. Always handle a rejection gracefully. -## Personal Sign +## Personal sign @@ -50,7 +50,7 @@ const signature = await signer.signMessage('Hello Sei'); -## EIP-712 Typed Data +## EIP-712 typed data @@ -113,7 +113,7 @@ const signature = await signer.signTypedData(domain, types, value); -## Verifying Signatures +## Verifying signatures ```ts viem import { verifyMessage, verifyTypedData } from 'viem'; @@ -136,9 +136,9 @@ const validTyped = await verifyTypedData({ }); ``` -## EIP-1271 Contract Signatures +## EIP-1271 contract signatures -Smart contract wallets on Sei can validate signatures via EIP-1271 (`isValidSignature`). Use viem's `verifyMessage` with a contract address — it automatically uses EIP-1271 when the address is a contract. +Smart contract wallets on Sei can validate signatures with EIP-1271 (`isValidSignature`). Use viem's `verifyMessage` with a contract address. When the address is a contract, `verifyMessage` uses EIP-1271 automatically. ```ts viem const valid = await verifyMessage({ diff --git a/evm/evm-parity/state-proofs.mdx b/evm/evm-parity/state-proofs.mdx index f20680a..5f9cf07 100644 --- a/evm/evm-parity/state-proofs.mdx +++ b/evm/evm-parity/state-proofs.mdx @@ -3,46 +3,46 @@ title: 'State Proofs' description: 'How eth_getProof differs on Sei due to IAVL tree storage' --- -# State Proofs +# State proofs -Sei supports `eth_getProof` but returns a different proof format from Ethereum. If your application verifies proofs on-chain or off-chain, you need to account for this difference. +Sei supports `eth_getProof`, but it returns a different proof format from Ethereum. If your application verifies proofs on-chain or off-chain, account for this difference. -## The Difference +## The difference -Ethereum stores state in a Merkle Patricia Trie (MPT) and `eth_getProof` returns MPT inclusion proofs. Sei stores state in an IAVL tree and returns IAVL proofs instead. +Ethereum stores state in a Merkle Patricia Trie (MPT), and `eth_getProof` returns MPT inclusion proofs. Sei stores state in an IAVL tree and returns IAVL proofs instead. The RPC method exists and responds correctly, but the proof data structure is not compatible with Ethereum MPT proof verifiers. ### Store backends -`eth_getProof` resolves the underlying account store by unwrapping known KVStore wrappers until it reaches a proof-capable queryable store. This means proofs are served across a broader range of node configurations, not just a classic IAVL store. Supported roots include: +`eth_getProof` resolves the underlying account store. It unwraps known KVStore wrappers until it reaches a proof-capable queryable store. As a result, proofs work across a broader range of node configurations, not only with a classic IAVL store. Supported roots include: - Classic IAVL stores - store/v2 memiavl commitment stores - Any other proof-capable (queryable) store reached through cache, `tracekv`, Giga cache, or prefix store wrappers -If none of these can be reached, the call returns a `cannot find a proof-capable queryable KV store` error. In all cases the returned proof data is IAVL-format, not Ethereum MPT. +If the call cannot reach any of these stores, it returns a `cannot find a proof-capable queryable KV store` error. In all cases, the returned proof data is in IAVL format, not Ethereum MPT format. -## What This Affects +## What this affects -Most applications do not call `eth_getProof` directly. It is primarily used by: +Most applications do not call `eth_getProof` directly. Its main users are: -- Light clients verifying state without trusting an RPC node -- Cross-chain bridges proving inclusion of state on Sei -- Applications verifying contract storage values trustlessly +- Light clients that verify state without trusting an RPC node +- Cross-chain bridges that prove the inclusion of state on Sei +- Applications that verify contract storage values trustlessly -If you are doing standard contract reads, event queries, or transaction lookups, this difference does not affect you. +If you do standard contract reads, event queries, or transaction lookups, this difference does not affect you. ## Calling eth_getProof ### Storage key requirements -Before calling `eth_getProof`, note two requirements Sei enforces on the `storageKeys` argument: +Before you call `eth_getProof`, note these two requirements that Sei enforces on the `storageKeys` argument: -- **Keys must be hex-encoded.** Each storage key must be a valid hex-encoded value (for example `0x0000000000000000000000000000000000000000000000000000000000000001`). Keys are decoded and left-padded to 32 bytes. A malformed, non-hex key is rejected with an `invalid storage key` error. Raw byte strings, which were previously accepted, no longer work. -- **At most 1024 keys per request.** A single proof request may include a maximum of 1024 storage keys. Requesting more returns a `too many storage keys` error. Split larger sets across multiple requests. +- **Keys must be hex-encoded.** Each storage key must be a valid hex-encoded value (for example, `0x0000000000000000000000000000000000000000000000000000000000000001`). Sei decodes each key and left-pads it to 32 bytes. Sei rejects a malformed, non-hex key with an `invalid storage key` error. Raw byte strings do not work, although earlier versions accepted them. +- **At most 1024 keys per request.** A single proof request may include a maximum of 1024 storage keys. A request for more keys returns a `too many storage keys` error. Split larger sets across multiple requests. -The call works through standard libraries: +The call works with standard libraries: @@ -77,8 +77,8 @@ const proof = await provider.send('eth_getProof', [ -## Verifying Proofs +## Verifying proofs -To verify Sei state proofs, use an IAVL-compatible verifier. Standard Ethereum MPT verifier libraries (e.g. those used in Solidity or in Ethereum bridge contracts) will reject Sei proofs. +To verify Sei state proofs, use an IAVL-compatible verifier. Standard Ethereum MPT verifier libraries reject Sei proofs. Examples are the libraries used in Solidity or in Ethereum bridge contracts. -Refer to the [Sei RPC reference](/evm/reference) for the exact proof schema returned. +For the exact proof schema that the method returns, see the [Sei RPC reference](/evm/reference). diff --git a/evm/evm-parity/transaction-types.mdx b/evm/evm-parity/transaction-types.mdx index ffb035f..6ba48ff 100644 --- a/evm/evm-parity/transaction-types.mdx +++ b/evm/evm-parity/transaction-types.mdx @@ -3,52 +3,52 @@ title: 'Transaction Types' description: 'Which Ethereum transaction types are supported on Sei' --- -# Transaction Types +# Transaction types Sei supports most Ethereum transaction types. The one notable exception is blob transactions. -## Supported Types +## Supported types | Type | EIP | Name | Sei support | | --- | --- | --- | --- | -| 0 | — | Legacy | Supported — governance-set minimum gas price applies | +| 0 | N/A | Legacy | Supported. A governance-set minimum gas price applies. | | 1 | EIP-2930 | Access list | Supported | -| 2 | EIP-1559 | Fee market | Supported — base fee is not burned | +| 2 | EIP-1559 | Fee market | Supported. Sei does not burn the base fee. | | 4 | EIP-7702 | Set code | Supported | -### Set Code (EIP-7702) Auth List Requirement +### Set code (EIP-7702) auth list requirement -Type 4 (EIP-7702) SetCode transactions must include a non-empty authorization list. A transaction with an empty or nil auth list is rejected during validation with the error `auth list cannot be empty`. +Type 4 (EIP-7702) SetCode transactions must include a non-empty authorization list. If the auth list is empty or nil, validation rejects the transaction with the error `auth list cannot be empty`. -Each authorization entry must also carry a valid (non-nil) chain ID. If you are constructing SetCode transactions directly, ensure at least one authorization is present before submitting. +Each authorization entry must also carry a valid (non-nil) chain ID. If you construct SetCode transactions directly, make sure that at least one authorization is present before you submit the transaction. -### Access List and Auth List Entry Validation +### Access list and auth list entry validation -EVM transactions undergo stricter semantic validation during `ValidateBasic`, enforced since v6.5.0. Malformed transactions that older node versions accepted are rejected. +Since v6.5.0, `ValidateBasic` applies stricter semantic validation to EVM transactions. It rejects malformed transactions that older node versions accepted. -**Access list entries (type 1 and type 2):** Each access list tuple is validated for well-formed hex encoding. Every address must be a canonical hex address of the correct length, and every storage key must be a canonical hex hash of the correct length. Entries with wrong-length or non-hex values are rejected. +**Access list entries (type 1 and type 2):** Validation checks each access list tuple for well-formed hex encoding. Every address must be a canonical hex address of the correct length. Every storage key must be a canonical hex hash of the correct length. Validation rejects entries with wrong-length or non-hex values. -**Auth list entries (type 4):** In addition to the non-empty auth list and non-nil chain ID requirements above, each authorization entry is validated for a canonical hex address and well-formed signature values. +**Auth list entries (type 4):** Validation checks each authorization entry for a canonical hex address and well-formed signature values. This check is in addition to the non-empty auth list and non-nil chain ID requirements above. -**Signature values:** The transaction-level `v`, `r`, and `s` values must each fit in 32 bytes; auth list entries (type 4) cap `v` at 1 byte and `r`/`s` at 32 bytes. In both cases, values must not be zero-padded (no leading zero bytes in multi-byte values); zero-padded signature encodings are rejected. +**Signature values:** The transaction-level `v`, `r`, and `s` values must each fit in 32 bytes. In auth list entries (type 4), `v` is limited to 1 byte, and `r` and `s` are limited to 32 bytes. In both cases, values must not be zero-padded: a multi-byte value must not have leading zero bytes. Validation rejects zero-padded signature encodings. -This section is the canonical reference for field-level EVM transaction validation on Sei. Envelope-level restrictions (Cosmos wrapper fields, canonical protobuf encoding, whole-block rejection on decode failure) are covered in [Differences with Ethereum](/evm/differences-with-ethereum#evm-transaction-envelope-restrictions). +This section is the canonical reference for field-level EVM transaction validation on Sei. [Differences with Ethereum](/evm/differences-with-ethereum#evm-transaction-envelope-restrictions) covers the envelope-level restrictions: Cosmos wrapper fields, canonical protobuf encoding, and whole-block rejection on decode failure. -## Not Supported +## Not supported | Type | EIP | Name | Notes | | --- | --- | --- | --- | -| 3 | EIP-4844 | Blob | Not supported — Sei runs Pectra without blob transactions | +| 3 | EIP-4844 | Blob | Not supported. Sei runs Pectra without blob transactions. | -## Blob Transactions +## Blob transactions -Sei runs the Pectra hardfork without blob transaction support. Attempting to send a type 3 transaction will be rejected at the RPC level. +Sei runs the Pectra hardfork without blob transaction support. If you try to send a type 3 transaction, Sei rejects it at the RPC level. -If you are porting code from Ethereum that uses blob transactions (e.g. rollup data availability), that path does not apply to Sei. +If you port code from Ethereum that uses blob transactions (for example, for rollup data availability), that code path does not apply to Sei. -## Sending Transactions +## Sending transactions -Standard library defaults work correctly. viem, wagmi, and ethers all default to type 2 (EIP-1559) transactions on chains that support it, which Sei does. +Standard library defaults work correctly. viem, wagmi, and ethers all default to type 2 (EIP-1559) transactions on chains that support EIP-1559, and Sei does. diff --git a/evm/evm-parity/websocket.mdx b/evm/evm-parity/websocket.mdx index cd7aedf..f8f84ea 100644 --- a/evm/evm-parity/websocket.mdx +++ b/evm/evm-parity/websocket.mdx @@ -3,16 +3,16 @@ title: 'WebSocket Connections' description: 'Connecting to Sei via WebSocket for real-time block and event subscriptions' --- -# WebSocket Connections +# WebSocket connections -Sei supports `eth_subscribe` over WebSocket. You can subscribe to new blocks, event logs, and pending transactions using standard library WebSocket transports. +Sei supports `eth_subscribe` over WebSocket. With the WebSocket transports in standard libraries, you can subscribe to new blocks, event logs, and pending transactions. ## Endpoints | Network | WebSocket endpoint | | --- | --- | -| Mainnet | `wss://evm-ws.sei-apis.com` | -| Testnet | `wss://evm-ws-testnet.sei-apis.com` | +| Sei Mainnet | `wss://evm-ws.sei-apis.com` | +| Sei Testnet | `wss://evm-ws-testnet.sei-apis.com` | ## Connecting @@ -36,7 +36,7 @@ const provider = new ethers.WebSocketProvider('wss://evm-ws.sei-apis.com'); -## Watching New Blocks +## Watching new blocks @@ -62,7 +62,7 @@ provider.off('block'); -## Watching Contract Events +## Watching contract events @@ -94,7 +94,7 @@ contract.off('Transfer'); -## Watching ERC-20 Transfers Across All Contracts +## Watching ERC-20 transfers across all contracts ```ts viem import { parseAbiItem } from 'viem'; @@ -111,22 +111,22 @@ const unwatch = client.watchEvent({ ## Notes -- Sei's instant finality means every block emitted over WebSocket is already final — no need to wait for additional confirmations before acting on an event. -- Pending transaction subscriptions (`newPendingTransactions`) are supported at the RPC level but Sei does not guarantee Ethereum-style pending state visibility. +- Sei has instant finality, so every block emitted over WebSocket is already final. You do not need to wait for more confirmations before you act on an event. +- Pending transaction subscriptions (`newPendingTransactions`) are supported at the RPC level, but Sei does not guarantee Ethereum-style pending state visibility. -## `newHeads` Under Autobahn Consensus +## `newHeads` under Autobahn consensus -When a node runs under Autobahn consensus, `eth_subscribe("newHeads")` notifications are delivered from an in-process notifier that publishes committed-block headers directly, rather than from the legacy consensus event bus. Subscribers still only observe headers for fully committed blocks, but the header payload differs from the legacy path in a few ways: +When a node runs under Autobahn consensus, `eth_subscribe("newHeads")` notifications come from an in-process notifier, not from the legacy consensus event bus. The notifier publishes committed-block headers directly. Subscribers still observe headers only for fully committed blocks. However, the header payload differs from the legacy path in a few ways: -- **`parentHash`, `receiptsRoot`, and `transactionsRoot` are returned as zero hashes** (`0x0000…0000`). The Autobahn block-execution path does not build a Tendermint-style hash chain, so there is no meaningful value to surface for these fields. -- **`stateRoot`** is sourced from the finalized block's `AppHash` (the post-execution application hash), rather than from a pre-execution header field. -- **`hash`** is the Autobahn block-header hash — the same value reported as `blockHash` by `eth_getBlockByNumber` and the receipt APIs, keeping `newHeads` consistent with the rest of the EVM RPC surface. -- **`gasUsed`** is an approximation (summed from per-transaction results) to keep the notification cheap. +- **`parentHash`, `receiptsRoot`, and `transactionsRoot` are returned as zero hashes** (`0x0000…0000`). The Autobahn block-execution path does not build a Tendermint-style hash chain, so there is no meaningful value to return in these fields. +- **`stateRoot`** comes from the finalized block's `AppHash` (the post-execution application hash), not from a pre-execution header field. +- **`hash`** is the Autobahn block-header hash. It is the same value that `eth_getBlockByNumber` and the receipt APIs report as `blockHash`. This keeps `newHeads` consistent with the rest of the EVM RPC surface. +- **`gasUsed`** is an approximation (summed from per-transaction results) that keeps the notification cheap. Because of these differences: -- Subscribers that chain-validate the head stream by linking `parentHash` values cannot rely on `newHeads` under Autobahn and need a different mechanism. -- If you need exact `gasUsed` or the omitted hash fields, fetch the block explicitly with `eth_getBlockByNumber`. +- Subscribers that chain-validate the head stream by linking `parentHash` values cannot rely on `newHeads` under Autobahn. They need a different mechanism. +- If you need the exact `gasUsed` or the omitted hash fields, fetch the block explicitly with `eth_getBlockByNumber`. diff --git a/evm/evm-verify-contracts.mdx b/evm/evm-verify-contracts.mdx index e797bc3..a4f12b2 100644 --- a/evm/evm-verify-contracts.mdx +++ b/evm/evm-verify-contracts.mdx @@ -7,23 +7,23 @@ keywords: ['contract verification', 'sourcify', 'hardhat', 'foundry', 'smart con import { SandboxEmbed } from '/snippets/sandbox-embed.jsx'; import { AddSeiButton } from '/snippets/add-sei-button.jsx'; -Verify your deployed contract using flattened source code, JSON input, Sourcify and more. Verifying your deployed contract ensures transparency and trust by making the source code publicly available and verifiable. +Verify your deployed contract with flattened source code, JSON input, Sourcify, or other methods. Verification makes your contract's source code public and verifiable. This creates transparency and trust. -## Benefits of Verification +## Benefits of verification -- **Transparency**: Publicly available source code. -- **Trust**: Community can verify the contract's functionality. -- **Security**: Greater confidence in the contract's integrity. +- Transparency: the source code is publicly available. +- Trust: the community can verify the contract's functionality. +- Security: verification gives greater confidence in the contract's integrity. ## Sourcify -[Sourcify](https://sourcify.dev/) provides decentralized, open-source contract verification. Sei has full Sourcify support on both **mainnet** (chain ID 1329) and **testnet** (chain ID 1328). +[Sourcify](https://sourcify.dev/) is a decentralized, open-source service for contract verification. Sei has full Sourcify support on both Sei Mainnet (chain ID 1329) and Sei Testnet (chain ID 1328). -Sourcify performs byte-by-byte verification by recompiling your source code with the exact same compiler settings and comparing the output against the on-chain bytecode. No API key is required. +Sourcify verifies contracts byte by byte. It recompiles your source code with the exact same compiler settings and compares the output with the on-chain bytecode. You do not need an API key. ### Verify with Foundry -After deploying your contract with Foundry, verify it on Sourcify: +After you deploy your contract with Foundry, verify it on Sourcify: ```bash forge verify-contract \ @@ -33,7 +33,7 @@ forge verify-contract \ ``` -**Testnet example:** +**Sei Testnet example:** ```bash forge verify-contract \ @@ -43,7 +43,7 @@ forge verify-contract \ src/Counter.sol:Counter ``` -**Mainnet example:** +**Sei Mainnet example:** ```bash forge verify-contract \ @@ -53,7 +53,7 @@ forge verify-contract \ src/Counter.sol:Counter ``` -To check verification status: +To check the verification status, run: ```bash forge verify-check \ @@ -62,7 +62,7 @@ forge verify-check \ ``` -You can also deploy and verify in a single step using `forge create`: +You can also deploy and verify in a single step with `forge create`: ```bash forge create src/Counter.sol:Counter \ @@ -73,11 +73,11 @@ forge create src/Counter.sol:Counter \ --chain-id 1328 ``` -If you need to pass constructor arguments, append them after the contract path. For example: `forge create src/Token.sol:Token --constructor-args "MyToken" "MTK" 18` +To pass constructor arguments, add them after the contract path. For example: `forge create src/Token.sol:Token --constructor-args "MyToken" "MTK" 18` ### Verify with Hardhat -The [`hardhat-verify`](https://hardhat.org/docs/learn-more/smart-contract-verification) plugin supports Sourcify out of the box with no additional configuration or API key. +The [`hardhat-verify`](https://hardhat.org/docs/learn-more/smart-contract-verification) plugin supports Sourcify by default. You do not need extra configuration or an API key. #### 1. Install dependencies @@ -122,7 +122,7 @@ export default defineConfig({ }); ``` -Sourcify verification is enabled by default in `hardhat-verify`. No `verify` config block is needed for Sourcify. +`hardhat-verify` enables Sourcify verification by default. You do not need a `verify` config block for Sourcify. #### 3. Deploy @@ -136,13 +136,13 @@ npx hardhat ignition deploy ignition/modules/Counter.ts --network sei_testnet npx hardhat verify sourcify --network sei_testnet ``` -If your contract has constructor arguments: +If your contract has constructor arguments, add them to the command: ```bash npx hardhat verify sourcify --network sei_testnet "arg1" "arg2" ``` -Running `npx hardhat verify` without a subtask will attempt verification on all enabled providers (Etherscan, Blockscout, and Sourcify) simultaneously. +If you run `npx hardhat verify` without a subtask, it tries to verify on all enabled providers (Etherscan, Blockscout, and Sourcify) at the same time. ### Verify via Sourcify UI @@ -155,11 +155,11 @@ You can also verify contracts directly through the [Sourcify web interface](http 5. Click **Verify** -## Remix Contract Verification Plugin +## Remix Contract Verification plugin -Remix IDE offers an automated contract verification solution through its Contract Verification plugin, which integrates with both Sourcify and Etherscan verification services. +Remix IDE verifies contracts automatically through its Contract Verification plugin. The plugin integrates with both the Sourcify and Etherscan verification services. -Don't have a contract deployed yet? Spin up Remix with a sample `Counter.sol`, deploy it to Sei Testnet, then follow the steps below to verify it. +If you do not have a deployed contract yet, open Remix with a sample `Counter.sol` and deploy it to Sei Testnet. Then follow the steps below to verify it. @@ -170,42 +170,42 @@ Don't have a contract deployed yet? Spin up Remix with a sample `Counter.sol`, d description="Remix IDE with a minimal Counter contract preloaded. Deploy it to Sei Testnet, then verify it with the Contract Verification plugin below." /> -### Setup and Configuration +### Setup and configuration -1. **Activate the Plugin**: In Remix IDE, navigate to the Plugin Manager and activate the **Contract Verification** plugin. +1. **Activate the plugin**: In Remix IDE, go to the **Plugin Manager** and activate the **Contract Verification** plugin. -2. **Configure Network Settings**: +2. **Configure network settings**: - Search for and select **Sei** as your blockchain - Choose your deployment environment: - **Testnet** (1328) for development - **Mainnet** (1329) for production -3. **Enable Verification Services**: Activate both verification methods: - - ✅ **Sourcify** - - ✅ **Etherscan** +3. **Enable verification services**: Activate both verification methods: + - **Sourcify** + - **Etherscan** -4. **Etherscan Configuration**: Configure the following settings: - - **API Key**: Obtain from [seiscan.io](https://seiscan.io) +4. **Configure Etherscan**: Set these values: + - **API Key**: Get a key from [seiscan.io](https://seiscan.io) - **URL**: `https://seiscan.io` -### Deploy and Verify +### Deploy and verify -Once configured, deploy your contract through Remix as usual. The Contract Verification plugin will automatically verify your contract upon successful deployment, submitting to both Sourcify and Seiscan simultaneously. +After you configure the plugin, deploy your contract through Remix as usual. When the deployment succeeds, the Contract Verification plugin verifies your contract automatically. It submits the contract to both Sourcify and Seiscan at the same time. -Verification status will be displayed in the plugin interface, and your verified contract will be publicly viewable on Seiscan explorer. +The plugin interface shows the verification status. Your verified contract is then publicly visible on the Seiscan explorer. ## Verify via 0xngmi Etherscan Verification (third‑party) -You can batch‑verify a contract that is already verified on another chain using the community tool [Etherscan Verification by 0xngmi](https://etherscan-verification.0xngmi.com/). This copies the verified source from a "source chain" and submits it to [Seiscan](https://seiscan.io), as long as the bytecode and compiler settings match. +If a contract is already verified on another chain, you can batch-verify it with the community tool [Etherscan Verification by 0xngmi](https://etherscan-verification.0xngmi.com/). The tool copies the verified source from a "source chain" and submits it to [Seiscan](https://seiscan.io). This works only if the bytecode and compiler settings match. -Prerequisite: The contract is already verified on at least one supported chain (same compiler version, optimization runs, constructor args, and library addresses as on Sei). +Prerequisite: The contract is already verified on at least one supported chain. That verified deployment must use the same compiler version, optimization runs, constructor arguments, and library addresses as the deployment on Sei. Steps: 1. Open [Etherscan Verification by 0xngmi](https://etherscan-verification.0xngmi.com/). -2. In "Source Contract", paste the address of the contract that is already verified and select its chain. -3. In "Target Contracts", add your Sei deployment address and select "Sei" as the target chain. -4. Click "Verify Contracts" and wait for the result. -5. Confirm the result on [Seiscan](https://seiscan.io) by visiting the contract page and checking the Contract tab. +2. In **Source Contract**, paste the address of the contract that is already verified and select its chain. +3. In **Target Contracts**, add the address of your Sei deployment and select **Sei** as the target chain. +4. Click **Verify Contracts** and wait for the result. +5. Confirm the result on [Seiscan](https://seiscan.io). Open the contract page and check the **Contract** tab. -If verification fails with a bytecode mismatch, re‑check compiler version, optimization runs, constructor arguments, and linked library addresses; they must be identical to the deployment on Sei. +If verification fails with a bytecode mismatch, check the compiler version, optimization runs, constructor arguments, and linked library addresses again. They must be identical to the deployment on Sei. diff --git a/evm/evm-wizard.mdx b/evm/evm-wizard.mdx index 8f76c16..fe7073e 100644 --- a/evm/evm-wizard.mdx +++ b/evm/evm-wizard.mdx @@ -8,7 +8,7 @@ keywords: ['OpenZeppelin wizard', 'smart contract generator', 'ERC standards', ' import { SandboxEmbed } from '/snippets/sandbox-embed.jsx'; import { AddSeiButton } from '/snippets/add-sei-button.jsx'; -The OpenZeppelin Contract Wizard is a powerful interactive tool that simplifies the creation of secure, standard-compliant smart contracts for Sei EVM. It provides a user-friendly interface for generating production-ready contract code based on OpenZeppelin's battle-tested libraries. Explore and create your custom smart contracts using the embedded wizard below. +The OpenZeppelin Contract Wizard is an interactive tool that helps you create secure, standard-compliant smart contracts for Sei EVM. Its interface generates production-ready contract code based on OpenZeppelin's battle-tested libraries. Use the embedded wizard below to explore and create your custom smart contracts. ``` -### Live Demo +### Live demo
-### Size Requirements +### Size requirements -- **Minimum Width**: `377px` -- **Minimum Height**: `650px` (recommended to prevent wallet modal scrolling) -- **Optimal Height**: `680-685px` +- **Minimum width**: `377px` +- **Minimum height**: `650px` (recommended to prevent scrolling in the wallet modal) +- **Optimal height**: `680-685px` -### URL Parameters +### URL parameters -Customize the widget by appending query parameters: +To customize the widget, append query parameters to the URL: -#### Token Selection +#### Token selection | Parameter | Description | Example | | ---------- | ----------------------------- | ----------------------------------------------------- | | `tokenIn` | Input token contract address | `tokenIn=0xe15fC38F6D8c56aF07bbCBe3BAf5708A2Bf42392` | | `tokenOut` | Output token contract address | `tokenOut=0xE30feDd158A2e3b13e9badaeABaFc5516e95e8C7` | -Tokens can be changed by the user after the widget loads. +Users can change the tokens after the widget loads. #### Appearance @@ -59,7 +59,7 @@ Customize the widget by appending query parameters: | `bgColor` | Background color | Hex (`%23FFFFFF`), Named (`white`), RGB (`rgb(255,255,255)`), RGBA (`rgba(255,255,255,0.9)`) | | `theme` | Color theme of the widget | `light` or `dark` (defaults to `dark` if not specified) | -For hex colors, use `%23` instead of `#` in the URL (e.g., `%23FFFFFF` for white). +For hex colors, use `%23` instead of `#` in the URL. For example, use `%23FFFFFF` for white. #### Features @@ -67,7 +67,7 @@ Customize the widget by appending query parameters: | --------------- | ---------------------------- | --------------------------- | | `notifications` | Show/hide notification cards | `true` (default) or `false` | -### Complete Example +### Complete example @@ -123,7 +123,7 @@ return ( -### Popular Sei Token Addresses (Mainnet) +### Popular Sei token addresses (Mainnet) | Token | Address | | ------------- | ------------------------------------------------------------------------------------------------------------------------ | @@ -133,18 +133,18 @@ return ( --- -## Best Practices +## Best practices -### Security Considerations +### Security considerations -**Security Checklist** +**Security checklist** -- ✅ Validate that iframe sources match official domains -- ✅ Implement Content Security Policy (CSP) headers +- Check that iframe sources match the official domains. +- Add Content Security Policy (CSP) headers. -### Performance Optimization +### Performance optimization ```tsx // Lazy load swap widgets to improve initial page load @@ -156,7 +156,7 @@ const SwapWidget = dynamic(() => import('./SwapWidget'), { }); ```` -### Responsive Design +### Responsive design ```css /* Ensure swap widgets are responsive */ @@ -181,7 +181,7 @@ const SwapWidget = dynamic(() => import('./SwapWidget'), { } ``` -### Error Handling +### Error handling ```tsx import { useState } from 'react'; @@ -206,6 +206,6 @@ function SwapWidgetWithFallback() { --- -## Additional Resources +## Additional resources - [Symphony Swap Widget Documentation](https://docs.symph.ag/widget/symphony-swap-widget) diff --git a/evm/index.mdx b/evm/index.mdx index ad8ba64..d3783af 100644 --- a/evm/index.mdx +++ b/evm/index.mdx @@ -5,82 +5,82 @@ description: "Build on the fastest EVM with 400ms finality, 100 MGas/s throughpu keywords: ["sei evm", "ethereum virtual machine", "web3 development", "blockchain development", "fast evm"] --- -## Why Choose Sei EVM? +## Why choose Sei EVM? | Feature | Sei EVM | Ethereum | Other Layer 1s | | -------------------------- | ------------- | ---------------- | --------------- | -| Blocktime | 400 ms | ~12 s | 1 - 3 seconds | -| Transaction Throughput | 100 MGas/s | ~5 MGas/s | < 50 MGas/s | -| Parallelized Execution | Yes | No | Limited/No | -| EVM Tooling Compatibility | 100% | 100% | Varies | -| EVM Version | Pectra (w/o blobs) | Fusaka | Varies | +| Block time | 400 ms | ~12 s | 1-3 s | +| Transaction throughput | 100 MGas/s | ~5 MGas/s | < 50 MGas/s | +| Parallelized execution | Yes | No | Limited/No | +| EVM tooling compatibility | 100% | 100% | Varies | +| EVM version | Pectra (without blobs) | Fusaka | Varies | - View detailed Ethereum comparison + See the detailed comparison of Sei EVM and Ethereum. -## Quick Start +## Quick start - + - [Install Sei Global Wallet](/evm/sei-global-wallet) - - [Sei EVM Network Information](/evm/networks) + - [Sei EVM network information](/evm/networks) - - - [Visit Sei Faucet](/learn/faucet) - - [View Token Information](/evm/tokens) + + - [Visit the Sei faucet](/learn/faucet) + - [View token information](/evm/tokens) - - - [EVM General Guide](/evm/evm-general) - - [Project Templates](/evm/templates) + + - [EVM general guide](/evm/evm-general) + - [Project templates](/evm/templates) -## Ready-to-Deploy Examples +## Ready-to-deploy examples - - Generate ERC-20, ERC-721, and more contracts in minutes. Configure, copy, deploy. + + Generate ERC-20, ERC-721, and other contracts in minutes. Configure the contract, then copy and deploy the code. - + Connect ethers.js, viem, or wagmi to your Sei EVM smart contracts. - - Tools and best practices for Solidity development on Sei. + + Find tools and best practices for Solidity development on Sei. -## Development Tools +## Development tools - Deploy smart contracts on Sei EVM using Hardhat. Simple setup, fast results. + Deploy smart contracts on Sei EVM with Hardhat. - Use Foundry to build and deploy on Sei EVM. Fast testing, simple deployment. + Use Foundry to build, test, and deploy contracts on Sei EVM. - + Browse every Sei EVM JSON-RPC method, run live requests, and copy ready-to-use code. -## Use Cases +## Use cases - - Implement HTTP 402 Payment Required for API monetization and premium content. + + Use HTTP 402 Payment Required to charge for API access and premium content. - Native USDC integration guide for seamless stablecoin transactions. + Integrate native USDC for stablecoin transactions. - + Keep many independent transactions in flight from one funded address with EIP-7702 and ERC-4337 nonce lanes. -## RPC Endpoints +## RPC endpoints -Choose from official Sei Foundation endpoints or community-maintained alternatives. All endpoints support standard EVM JSON-RPC methods. Public endpoints have rate limits — for production apps, use a [dedicated RPC provider](/learn/rpc-providers) or [run your own node](/node). +Choose an official Sei Foundation endpoint or a community-maintained alternative. All endpoints support the standard EVM JSON-RPC methods. Public endpoints have rate limits. For production dApps, use a [dedicated RPC provider](/learn/rpc-providers) or [run your own node](/node). @@ -102,6 +102,6 @@ Choose from official Sei Foundation endpoints or community-maintained alternativ - - Search every Sei EVM JSON-RPC method with Sei-specific behavior notes, switch between mainnet, testnet, and custom endpoints, run live requests, and generate ready-to-use client code. + + Search every Sei EVM JSON-RPC method, with notes on Sei-specific behavior. Switch between Sei Mainnet, Sei Testnet, and custom endpoints. Run live requests and generate ready-to-use client code. diff --git a/evm/indexer-providers/dune-sim.mdx b/evm/indexer-providers/dune-sim.mdx index ac6b772..505a504 100644 --- a/evm/indexer-providers/dune-sim.mdx +++ b/evm/indexer-providers/dune-sim.mdx @@ -7,35 +7,33 @@ keywords: ['sim', 'dune', 'blockchain indexing', 'api integration', 'real-time d ## Overview -Sim by Dune is a real-time, multichain developer platform that provides scalable APIs and indexing infrastructure for building onchain applications. It offers the fastest way to access live blockchain data across 60+ chains, including Sei, with zero DevOps overhead. In this tutorial, you'll learn how to set up Sim, build your first data pipeline, and create powerful onchain applications on Sei. +Sim by Dune is a real-time, multichain developer platform. It has scalable APIs and indexing infrastructure for building onchain applications. It gives you fast access to live blockchain data on 60+ chains, including Sei, with no DevOps overhead. This tutorial shows how to set up Sim, build your first data pipeline, and create onchain applications on Sei. -To understand more and deep dive into how it works under the hood, please refer to the [Sim by Dune Documentation](https://docs.sim.dune.com/) +For details on how Sim works, see the [Sim by Dune documentation](https://docs.sim.dune.com/). ## What this guide teaches you: -This tutorial guides you through: - -- **Setup**: Get your Sim API key, install dependencies, and connect to Sei -- **Core APIs**: Learn to use all 6 Sim APIs with practical examples -- **End-to-End Examples**: You'll run practical code to: +- How to get your Sim API key, install the dependencies, and connect to Sei +- How to use all 6 Sim APIs, with practical examples +- How to run end-to-end code examples that: - Fetch Sei token balances with USD values - Monitor wallet transactions and activity - Get token metadata and holder information - Track NFT collections and metadata -- **Production Ready**: Error handling, rate limiting, and monitoring +- How to make your code production ready with error handling, rate limiting, and monitoring -## Some Use Cases: +## Some use cases: -- **DeFi Analytics Platforms**: Real-time tracking of liquidity, volumes, and yields across Sei protocols -- **Portfolio Trackers**: Multi-chain portfolio management with Sei integration -- **Trading Bots**: Automated trading based on real-time onchain signals -- **Risk Management**: Monitor positions and liquidation risks across protocols -- **Governance Tools**: Track voting power and proposal activity -- **MEV Analysis**: Detect and analyze MEV opportunities on Sei +- **DeFi analytics platforms**: Real-time tracking of liquidity, volumes, and yields across Sei protocols +- **Portfolio trackers**: Multichain portfolio management with Sei integration +- **Trading bots**: Automated trading based on real-time onchain signals +- **Risk management**: Monitor positions and liquidation risks across protocols +- **Governance tools**: Track voting power and proposal activity +- **MEV analysis**: Detect and analyze MEV opportunities on Sei ## Supported APIs -Sim by Dune provides access to comprehensive EVM blockchain data through these core APIs: +Sim by Dune gives access to EVM blockchain data through these core APIs: ### Balances API @@ -44,44 +42,44 @@ Sim by Dune provides access to comprehensive EVM blockchain data through these c ### Transactions API -- **Features:** Quick and accurate lookup of EVM transactions associated with any address +- **Features:** Quick and accurate lookup of the EVM transactions for any address - **Use cases:** Transaction monitoring, compliance tools, activity tracking ### Token Info API -- **Features:** Metadata including symbol, name, decimals, supply information, logo URLs, and realtime prices +- **Features:** Metadata, including symbol, name, decimals, supply information, logo URLs, and real-time prices - **Use cases:** Token discovery, price tracking, market analysis ### Token Holders API -- **Features:** Holders of an ERC20 token, sorted by balance +- **Features:** Holders of an ERC-20 token, sorted by balance - **Use cases:** Governance analysis, token distribution studies, whale tracking ### Activity API -- **Features:** Derived activities including swaps, transfers, and approvals within transactions for any address +- **Features:** Derived activities, such as swaps, transfers, and approvals, in the transactions of any address - **Use cases:** DeFi analytics, trading analysis, user behavior tracking ### Collectibles API -- **Features:** All NFT (ERC721 and ERC1155) balances, including IDs and metadata +- **Features:** All NFT balances (ERC-721 and ERC-1155), including IDs and metadata - **Use cases:** NFT marketplaces, collection analytics, digital asset management -## Quick Start +## Quick start -### 1. Getting Your API Key +### 1. Getting your API key -To use Sim APIs, you'll need an API key from the Sim dashboard: +To use the Sim APIs, you need an API key from the Sim dashboard: -1. **Visit Sim Dashboard**: Go to [sim.dune.com](https://sim.dune.com) -2. **Sign Up/Login**: Create an account or login with your existing Dune account -3. **Navigate to Keys**: In the left sidebar, click on "Keys" -4. **Create New Key**: Click the "New" button to generate a new API key -5. **Select API Type**: Choose "Sim API" as the key's purpose -6. **Copy Your Key**: Save the generated API key securely +1. Go to [sim.dune.com](https://sim.dune.com). +2. Create an account, or log in with your existing Dune account. +3. In the left sidebar, click **Keys**. +4. To generate a new API key, click **New**. +5. Choose **Sim API** as the purpose of the key. +6. Copy the generated API key, and save it securely. -**Security Notes:** +**Security notes:** - Never share your API key in public repositories @@ -91,7 +89,7 @@ To use Sim APIs, you'll need an API key from the Sim dashboard: -### 2. Project Setup +### 2. Project setup ```bash mkdir sei-sim-tutorial @@ -100,7 +98,7 @@ npm init -y npm install axios dotenv ``` -Create `.env` file: +Create a `.env` file: ```env SIM_API_KEY=your_sim_api_key_here @@ -108,7 +106,7 @@ SEI_RPC_URL=https://evm-rpc.sei-apis.com TEST_WALLET_ADDRESS=0x...your_test_address ``` -### 3. Your First API Call +### 3. Your first API call Create `index.js`: @@ -151,7 +149,7 @@ Run your first query: node index.js ``` -**Expected Output:** +**Expected output:** ``` 🔍 Fetching Sei balances... @@ -160,9 +158,9 @@ node index.js USDC: 500.0 (500.0 USD) ``` -## API Examples +## API examples -### Balances API - Get Token Balances +### Balances API - Get token balances ```javascript async function getSeiBalances() { @@ -181,7 +179,7 @@ async function getSeiBalances() { } ``` -### Transactions API - Monitor Wallet Transactions +### Transactions API - Monitor wallet transactions ```javascript async function monitorSeiTransactions(address) { @@ -213,7 +211,7 @@ async function monitorSeiTransactions(address) { } ``` -### Token Info API - Get Token Metadata +### Token Info API - Get token metadata ```javascript async function getTokenInfo(tokenAddress) { @@ -241,7 +239,7 @@ async function getTokenInfo(tokenAddress) { getTokenInfo('0xe15fC38F6D8c56aF07bbCBe3BAf5708A2Bf42392'); ``` -### Token Holders API - Find Top Holders +### Token Holders API - Find top holders ```javascript async function getTokenHolders(tokenAddress, limit = 20) { @@ -269,7 +267,7 @@ async function getTokenHolders(tokenAddress, limit = 20) { } ``` -### Activity API - Track Swaps and Transfers +### Activity API - Track swaps and transfers ```javascript async function getWalletActivity(walletAddress, limit = 10) { @@ -304,7 +302,7 @@ async function getWalletActivity(walletAddress, limit = 10) { } ``` -### Collectibles API - Get NFT Collections +### Collectibles API - Get NFT collections ```javascript async function getNFTCollections(walletAddress) { @@ -352,9 +350,9 @@ async function getNFTCollections(walletAddress) { } ``` -## Advanced Use Cases +## Advanced use cases -### Portfolio Analytics Dashboard +### Portfolio analytics dashboard ```javascript require('dotenv').config(); @@ -409,7 +407,7 @@ async function buildAdvancedPortfolio(walletAddress) { } ``` -### Token Analysis Tool +### Token analysis tool ```javascript require('dotenv').config(); @@ -474,9 +472,9 @@ async function analyzeToken(tokenAddress) { analyzeToken('0xe15fC38F6D8c56aF07bbCBe3BAf5708A2Bf42392'); // USDC address ``` -## Error Handling & Best Practices +## Error handling & best practices -### Comprehensive Error Handling +### Comprehensive error handling ```javascript class SimAPIClient { @@ -535,7 +533,7 @@ class SimAPIClient { } ``` -### Rate Limiting +### Rate limiting ```javascript class RateLimitedClient { @@ -564,31 +562,31 @@ class RateLimitedClient { | Error | Cause | Solution | | --- | --- | --- | -| `Invalid API key` | Wrong or expired key | Check API key in dashboard | +| `Invalid API key` | Wrong or expired key | Check the API key in the dashboard | | `Rate limit exceeded` | Too many requests | Implement exponential backoff | -| `Chain not supported` | Using unsupported chain | Check supported chains list | -| `Invalid address format` | Malformed wallet address | Validate address format | -| `Request timeout` | Network issues | Increase timeout, add retries | +| `Chain not supported` | The chain is not supported | Check the list of supported chains | +| `Invalid address format` | Malformed wallet address | Validate the address format | +| `Request timeout` | Network issues | Increase the timeout and add retries | | `Insufficient data` | New address/contract | Wait for indexing to complete | ## Resources -### Official Documentation +### Official documentation -- **Sim Documentation**: [https://docs.sim.dune.com](https://docs.sim.dune.com) -- **Sim Dashboard**: [https://sim.dune.com](https://sim.dune.com) -- **Sei Explorer**: [https://seiscan.io](https://seiscan.io) +- **Sim documentation**: [https://docs.sim.dune.com](https://docs.sim.dune.com) +- **Sim dashboard**: [https://sim.dune.com](https://sim.dune.com) +- **Sei explorer**: [https://seiscan.io](https://seiscan.io) -### Community Resources +### Community resources - **Dune Discord**: [https://discord.gg/dune](https://discord.com/invite/ErrzwBz) - **Sei Discord**: [https://discord.gg/sei](https://discord.gg/sei) -## Next Steps +## Next steps -1. **Scale Your Application**: Implement caching, database storage, and horizontal scaling -2. **Build a Frontend**: Create React/Vue.js dashboards to visualize your data -3. **Advanced Analytics**: Implement machine learning for predictive analytics -4. **Custom Indexers**: Build specialized data pipelines for specific protocols -5. **API Integration**: Connect with other services like price feeds, news APIs +1. To scale your application, implement caching, database storage, and horizontal scaling. +2. Build a frontend, such as a React or Vue.js dashboard, to visualize your data. +3. Implement machine learning for predictive analytics. +4. Build custom indexers, which are specialized data pipelines for specific protocols. +5. Connect your application to other services, such as price feeds and news APIs. diff --git a/evm/indexer-providers/envio.mdx b/evm/indexer-providers/envio.mdx index 3bf7079..9ab10c7 100644 --- a/evm/indexer-providers/envio.mdx +++ b/evm/indexer-providers/envio.mdx @@ -6,13 +6,13 @@ keywords: ['envio', 'hyperindex', 'hypersync', 'hyperrpc', 'blockchain indexer', ## Envio -Index Sei smart contract data using Envio, a modular hyper-performant data indexing solution. Envio offers three products you can use individually or together to fit your data needs on Sei. +Use Envio, a modular data indexing solution, to index Sei smart contract data. Envio has three products. You can use them individually or together, depending on your data needs on Sei. 1. [HyperIndex](https://docs.envio.dev/docs/HyperIndex/overview), a fully customizable blockchain indexing framework that powers GraphQL APIs over Postgres 2. [HyperSync](https://docs.envio.dev/docs/HyperSync/overview), a real-time data retrieval layer up to 2000x faster than traditional RPC -3. [HyperRPC](https://docs.envio.dev/docs/HyperRPC/overview-hyperrpc), an extremely fast RPC for data-intensive queries +3. [HyperRPC](https://docs.envio.dev/docs/HyperRPC/overview-hyperrpc), a fast RPC for data-intensive queries -> **New to Envio?** Jump straight to [How to Index Sei Smart Contract Data in Minutes using Envio](https://docs.envio.dev/blog/index-sei-smart-contracts-envio) for a step-by-step walkthrough that builds a USDC indexer on Sei in under five minutes. +> If you are new to Envio, start with [How to Index Sei Smart Contract Data in Minutes using Envio](https://docs.envio.dev/blog/index-sei-smart-contracts-envio). This step-by-step walkthrough builds a USDC indexer on Sei in under five minutes. | Field | Value | | ---------------------- | -------------------------------------------------------------------- | @@ -20,27 +20,27 @@ Index Sei smart contract data using Envio, a modular hyper-performant data index | HyperSync URL Endpoint | `https://sei.hypersync.xyz` or `https://1329.hypersync.xyz` | | HyperRPC URL Endpoint | `https://sei.rpc.hypersync.xyz` or `https://1329.rpc.hypersync.xyz` | -> Sei Testnet is also supported, with HyperSync at `https://sei-testnet.hypersync.xyz` and HyperRPC at `https://sei-testnet.rpc.hypersync.xyz`. +> Envio also supports Sei Testnet. HyperSync is at `https://sei-testnet.hypersync.xyz`, and HyperRPC is at `https://sei-testnet.rpc.hypersync.xyz`. -## Choosing a Product +## Choosing a product ### HyperIndex **Best for:** projects that need a complete indexing solution with schema management, event handling, and a GraphQL API. -* A full-featured indexing framework that transforms on-chain events into structured, queryable databases with GraphQL APIs -* Configured with a YAML file, a GraphQL schema, and TypeScript, JavaScript, or ReScript event handlers -* Supports multichain indexing, real-time indexing, reorg support, and factory (dynamic) contracts -* Powered by HyperSync for historical backfill +* An indexing framework that transforms on-chain events into structured, queryable databases with GraphQL APIs +* Configured with a YAML file, a GraphQL schema, and event handlers in TypeScript, JavaScript, or ReScript +* Supports multichain indexing, real-time indexing, reorg handling, and factory (dynamic) contracts +* Uses HyperSync for historical backfill ### HyperSync -**Best for:** new projects designing their own data access layer, performance-critical workloads, advanced filtering, and full control over data formatting. +**Best for:** new projects that design their own data access layer, performance-critical workloads, advanced filtering, and full control over data formatting. -* A purpose-built, high-performance data retrieval layer, built from the ground up in Rust as an alternative to traditional JSON-RPC endpoints -* The raw blockchain data access layer that powers HyperIndex, delivering up to 2000x faster performance than traditional RPC endpoints -* Client libraries available for Python, Rust, Node.js, and Go -* Filter, select, and process exactly the data you need with powerful query options +* A high-performance data retrieval layer, written from scratch in Rust as an alternative to traditional JSON-RPC endpoints +* The raw blockchain data access layer that HyperIndex uses. It is up to 2000x faster than traditional RPC endpoints. +* Client libraries for Python, Rust, Node.js, and Go +* Query options that let you filter, select, and process exactly the data that you need Common use cases include custom indexers, data analytics, block explorers, monitoring tools, cross-chain applications, and ETL pipelines. @@ -48,22 +48,22 @@ Common use cases include custom indexers, data analytics, block explorers, monit **Best for:** drop-in replacements for existing RPC-based code, projects that need standard JSON-RPC interfaces, and teams without time for a deeper integration. -* An extremely fast RPC designed specifically for data-intensive blockchain tasks +* A fast RPC designed for data-intensive blockchain tasks * A specialized JSON-RPC endpoint optimized for data retrieval workflows * Drop-in compatible with existing tooling that uses standard RPC methods -* Up to 5x faster than traditional nodes for data-intensive operations; uses HyperSync to fulfill requests +* Up to 5x faster than traditional nodes for data-intensive operations. It uses HyperSync to fulfill requests. Common use cases include historical data queries, log event filtering, block and transaction retrievals, and analytics applications. -## Getting Started +## Getting started -Make sure you have installed the [prerequisites](https://docs.envio.dev/docs/HyperIndex/quickstart#prerequisites), then initialize a new indexer. +Make sure that you have installed the [prerequisites](https://docs.envio.dev/docs/HyperIndex/quickstart#prerequisites). Then initialize a new indexer: ```bash theme={"dark"} pnpx envio init ``` -You'll follow interactive prompts to customize your indexer for Sei. A minimal Sei `config.yaml` looks like this. +Follow the interactive prompts to customize your indexer for Sei. A minimal Sei `config.yaml` looks like this: ```yaml theme={"dark"} name: IndexerName @@ -83,11 +83,11 @@ For more detail on configuring chains, schemas, and event handlers, see the [Hyp ## Built with Envio -* [Indexer Explorer](https://envio.dev/explorer), browse public real-time indexers built on Envio -* [Case studies](https://docs.envio.dev/blog/tags/case-studies), see real-world deployments and migrations -* [Showcase](https://docs.envio.dev/showcase), explore live demos built with HyperIndex and HyperSync +* [Indexer Explorer](https://envio.dev/explorer): browse public real-time indexers built on Envio +* [Case studies](https://docs.envio.dev/blog/tags/case-studies): see real-world deployments and migrations +* [Showcase](https://docs.envio.dev/showcase): explore live demos built with HyperIndex and HyperSync -## More Resources +## More resources * [HyperIndex Quickstart](https://docs.envio.dev/docs/HyperIndex/quickstart) * [Quickstart with AI](https://docs.envio.dev/docs/HyperIndex/quickstart-with-ai) @@ -96,4 +96,4 @@ For more detail on configuring chains, schemas, and event handlers, see the [Hyp ## Support -Need help? Connect with the Envio team on [Discord](https://discord.gg/envio) or [Telegram](https://t.me/+kAIGElzPjApiMjI0). +For help, contact the Envio team on [Discord](https://discord.gg/envio) or [Telegram](https://t.me/+kAIGElzPjApiMjI0). diff --git a/evm/indexer-providers/goldrush.mdx b/evm/indexer-providers/goldrush.mdx index b7c9340..bbb9b60 100644 --- a/evm/indexer-providers/goldrush.mdx +++ b/evm/indexer-providers/goldrush.mdx @@ -6,15 +6,13 @@ keywords: ['goldrush', 'blockchain indexing', 'api integration', 'data analysis' --- ## Overview -GoldRush offers the most comprehensive Sei Data API suite for developers, analysts, and enterprises. Whether you're -building a DeFi dashboard, a wallet, a trading bot, an AI agent or a compliance platform, -our Sei Data APIs provide fast, accurate, and developer-friendly access to the essential onchain data you need. +GoldRush has a suite of Sei Data APIs for developers, analysts, and enterprises. The APIs give fast, accurate access to the onchain data that you need. You can use them to build a DeFi dashboard, a wallet, a trading bot, an AI agent, or a compliance platform. ### Supported APIs | **Product Name** | **Description** | **Key Data Feeds** | **Use Cases** | | -------------------- | ----------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | -| **Foundational API** | Access structured historical blockchain data across 100+ chains via REST APIs |
  • Token balances (spot & historical)
  • Token transfers
  • Token holders (spot & historical)
  • Token prices (onchain)
  • Wallet transactions
  • Get logs
|
  • Wallets
  • Portfolio trackers
  • Crypto accounting & tax tools
  • DeFi dashboards
  • Activity feeds
| +| **Foundational API** | Access structured historical blockchain data on 100+ chains through REST APIs |
  • Token balances (spot & historical)
  • Token transfers
  • Token holders (spot & historical)
  • Token prices (onchain)
  • Wallet transactions
  • Get logs
|
  • Wallets
  • Portfolio trackers
  • Crypto accounting & tax tools
  • DeFi dashboards
  • Activity feeds
| ## Mainnet @@ -29,21 +27,21 @@ our Sei Data APIs provide fast, accurate, and developer-friendly access to the e | **Native Gas Token** | SEI | -## API Usage +## API usage -To use this blockchain network in GoldRush API calls, use: +To use Sei in GoldRush API calls, use this chain name: -#### Chain Name +#### Chain name -- `sei-mainnet` (mainnet) +- `sei-mainnet` (Sei Mainnet) -#### Example API Calls (bash) +#### Example API calls (bash) ```bash curl -X GET "https://api.covalenthq.com/v1/sei-mainnet/address/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045/balances_v2/?key=API_KEY" ``` -### SDK Usage (TypeScript) +### SDK usage (TypeScript) ```ts import { GoldRushClient } from '@covalenthq/client-sdk'; @@ -56,55 +54,51 @@ const resp = await client.BalanceService.getTokenBalancesForWalletAddress({ }); ``` -## Foundational API Support +## Foundational API support -This chain supports **34** GoldRush Foundational APIs: +Sei supports 34 GoldRush Foundational APIs: #### Wallet API -- **[Get token balances for address](https://goldrush.dev/docs/api-reference/foundational-api/balances/get-token-balances-for-address)** -- **[Get native token balance for address](https://goldrush.dev/docs/api-reference/foundational-api/balances/get-native-token-balance)** -- **[Get historical portfolio value over time](https://goldrush.dev/docs/api-reference/foundational-api/balances/get-historical-portfolio-value-over-time)** -- **[Get ERC20 token transfers for address](https://goldrush.dev/docs/api-reference/foundational-api/balances/get-erc20-token-transfers-for-address)** +- [Get token balances for address](https://goldrush.dev/docs/api-reference/foundational-api/balances/get-token-balances-for-address) +- [Get native token balance for address](https://goldrush.dev/docs/api-reference/foundational-api/balances/get-native-token-balance) +- [Get historical portfolio value over time](https://goldrush.dev/docs/api-reference/foundational-api/balances/get-historical-portfolio-value-over-time) +- [Get ERC20 token transfers for address](https://goldrush.dev/docs/api-reference/foundational-api/balances/get-erc20-token-transfers-for-address) #### Pricing API -- **[Get historical token prices](https://goldrush.dev/docs/api-reference/foundational-api/utility/get-historical-token-prices)** +- [Get historical token prices](https://goldrush.dev/docs/api-reference/foundational-api/utility/get-historical-token-prices) #### Security API -- **[Get token approvals for address](https://goldrush.dev/docs/api-reference/foundational-api/security/get-token-approvals-for-address)** +- [Get token approvals for address](https://goldrush.dev/docs/api-reference/foundational-api/security/get-token-approvals-for-address) #### Activity Feed API -- **[Get a transaction](https://goldrush.dev/docs/api-reference/foundational-api/transactions/get-a-transaction)** -- **[Get transaction summary for address](https://goldrush.dev/docs/api-reference/foundational-api/transactions/get-transaction-summary-for-address)** -- **[Get earliest transactions for address (v3) ](https://goldrush.dev/docs/api-reference/foundational-api/transactions/get-earliest-transactions-for-address-v3)** -- **[Get recent transactions for address (v3)](https://goldrush.dev/docs/api-reference/foundational-api/transactions/get-recent-transactions-for-address-v3)** -- **[Get paginated transactions for address (v3)](https://goldrush.dev/docs/api-reference/foundational-api/transactions/get-paginated-transactions-for-address-v3)** -- **[Get bulk time bucket transactions for address (v3)](https://goldrush.dev/docs/api-reference/foundational-api/transactions/get-time-bucket-transactions-for-address-v3)** -- **[Get all transactions in a block (v3)](https://goldrush.dev/docs/api-reference/foundational-api/transactions/get-all-transactions-in-a-block)** -- **[Get all transactions in a block by page (v3) ](https://goldrush.dev/docs/api-reference/foundational-api/transactions/get-all-transactions-in-a-block-by-page)** +- [Get a transaction](https://goldrush.dev/docs/api-reference/foundational-api/transactions/get-a-transaction) +- [Get transaction summary for address](https://goldrush.dev/docs/api-reference/foundational-api/transactions/get-transaction-summary-for-address) +- [Get earliest transactions for address (v3)](https://goldrush.dev/docs/api-reference/foundational-api/transactions/get-earliest-transactions-for-address-v3) +- [Get recent transactions for address (v3)](https://goldrush.dev/docs/api-reference/foundational-api/transactions/get-recent-transactions-for-address-v3) +- [Get paginated transactions for address (v3)](https://goldrush.dev/docs/api-reference/foundational-api/transactions/get-paginated-transactions-for-address-v3) +- [Get bulk time bucket transactions for address (v3)](https://goldrush.dev/docs/api-reference/foundational-api/transactions/get-time-bucket-transactions-for-address-v3) +- [Get all transactions in a block (v3)](https://goldrush.dev/docs/api-reference/foundational-api/transactions/get-all-transactions-in-a-block) +- [Get all transactions in a block by page (v3)](https://goldrush.dev/docs/api-reference/foundational-api/transactions/get-all-transactions-in-a-block-by-page) #### Block Explorer API -- **[Get a block](https://goldrush.dev/docs/api-reference/foundational-api/utility/get-a-block)** -- **[Get all chain statuses](https://goldrush.dev/docs/api-reference/foundational-api/utility/get-all-chain-statuses)** -- **[Get all chains](https://goldrush.dev/docs/api-reference/foundational-api/utility/get-all-chains)** -- **[Get block heights](https://goldrush.dev/docs/api-reference/foundational-api/utility/get-block-heights)** -- **[Get gas prices](https://goldrush.dev/docs/api-reference/foundational-api/utility/get-gas-prices)** -- **[Get log events by contract address](https://goldrush.dev/docs/api-reference/foundational-api/utility/get-log-events-by-contract-address)** -- **[Get log events by topic hash(es)](https://goldrush.dev/docs/api-reference/foundational-api/utility/get-log-events-by-topic-hash)** -- **[Get logs](https://goldrush.dev/docs/api-reference/foundational-api/utility/get-logs)** - -## Additional Resources - -- [Goldrush Docs](https://goldrush.dev/docs/?utm_source=sei&utm_medium=partner-docs) - - comprehensive knowledge base for all things GoldRush including a quickstart -- [Sei Network Details](https://goldrush.dev/chains/sei/?utm_source=sei&utm_medium=partner-docs) - - setup details and supported APIs for Sei -- [Guides](https://goldrush.dev/guides/?utm_source=sei&utm_medium=partner-docs) - - learn how to build for various use cases and expand your onchain knowledge -- [API Reference](https://goldrush.dev/docs/api-reference/) -- [API Key](https://goldrush.dev/platform/auth/register/?utm_source=sei&utm_medium=partner-docs) - - sign up for free +- [Get a block](https://goldrush.dev/docs/api-reference/foundational-api/utility/get-a-block) +- [Get all chain statuses](https://goldrush.dev/docs/api-reference/foundational-api/utility/get-all-chain-statuses) +- [Get all chains](https://goldrush.dev/docs/api-reference/foundational-api/utility/get-all-chains) +- [Get block heights](https://goldrush.dev/docs/api-reference/foundational-api/utility/get-block-heights) +- [Get gas prices](https://goldrush.dev/docs/api-reference/foundational-api/utility/get-gas-prices) +- [Get log events by contract address](https://goldrush.dev/docs/api-reference/foundational-api/utility/get-log-events-by-contract-address) +- [Get log events by topic hash(es)](https://goldrush.dev/docs/api-reference/foundational-api/utility/get-log-events-by-topic-hash) +- [Get logs](https://goldrush.dev/docs/api-reference/foundational-api/utility/get-logs) + +## Additional resources + +- [GoldRush docs](https://goldrush.dev/docs/?utm_source=sei&utm_medium=partner-docs): the GoldRush knowledge base, including a quickstart +- [Sei network details](https://goldrush.dev/chains/sei/?utm_source=sei&utm_medium=partner-docs): setup details and supported APIs for Sei +- [Guides](https://goldrush.dev/guides/?utm_source=sei&utm_medium=partner-docs): learn how to build for different use cases +- [API reference](https://goldrush.dev/docs/api-reference/) +- [API key](https://goldrush.dev/platform/auth/register/?utm_source=sei&utm_medium=partner-docs): sign up for free diff --git a/evm/indexer-providers/goldsky.mdx b/evm/indexer-providers/goldsky.mdx index b58186a..ef403f1 100644 --- a/evm/indexer-providers/goldsky.mdx +++ b/evm/indexer-providers/goldsky.mdx @@ -6,43 +6,43 @@ keywords: ['goldsky', 'blockchain indexer', 'subgraphs', 'data pipelines', 'real ## Goldsky -Wondering how to best leverage Goldsky's products? This guide explains the differences between them and how you can use them individually or together to meet your needs. +This guide explains the differences between Goldsky's products. It also shows how you can use them individually or together. -Goldsky offers two flagship products, Subgraphs and Mirror, designed to help developers interact with Sei blockchain data more efficiently. While both tools serve similar goals - retrieving, processing, and querying blockchain data - they differ significantly in how they handle data management, scalability, and customization. +Goldsky has two main products, Subgraphs and Mirror. Both help developers work with on-chain data from Sei more efficiently. The two tools have similar goals: to retrieve, process, and query blockchain data. They differ significantly in how they handle data management, scalability, and customization. -Let's dive into the difference in this guide and learn more about which solution is right for you. If you're ready to get started, please visit [this page](https://docs.goldsky.com/chains/sei/?utm_source=sei&utm_medium=docs) for a quickstart guide on how to index Sei with Goldsky. +If you are ready to start, see the [Goldsky quickstart guide for indexing Sei](https://docs.goldsky.com/chains/sei/?utm_source=sei&utm_medium=docs). -## How to Choose Between Subgraphs and Mirror +## How to choose between Subgraphs and Mirror -### Subgraphs: Structured, Query-Based Data Retrieval +### Subgraphs: Structured, query-based data retrieval **Overview:** -- On-chain data is restricted to EVM-compatible chains, so it's only supported for Sei EVM. -- The data model is optimized specifically for on-chain data. The entities and data types you define in subgraphs are tailored to represent blockchain data efficiently. -- You can create relationships and aggregations between on-chain entities (e.g. track the balance of a user for specific tokens) -- You can enrich entity data with other on-chain sources using **`eth_call`**. However, integrating off-chain data is not supported. +- Subgraphs support on-chain data from EVM-compatible chains only. On Sei, they support only Sei EVM. +- The data model is optimized for on-chain data. The entities and data types that you define in subgraphs are designed to represent blockchain data efficiently. +- You can create relationships and aggregations between on-chain entities. For example, you can track the balance of a user for specific tokens. +- You can enrich entity data with other on-chain sources through `eth_call`. However, you cannot integrate off-chain data. **Examples:** -- Retrieving all transactions related to a specific wallet address. +- Getting all transactions for a specific wallet address. - Querying detailed event logs from a smart contract, such as token transfers or contract interactions. -- Building dashboards or analytics tools that require periodic data retrieval. +- Building dashboards or analytics tools that query data periodically. -**Key Advantages:** +**Key advantages:** -- **Customizable Data Models**: Define specific data structures to match your needs. -- **Fast Query Response Times**: Queries return results quickly from pre-indexed data. -- **Developer Flexibility**: Use GraphQL to create custom queries that fit your application's needs. +- You can define custom data models that match your needs. +- Queries return results quickly because the data is pre-indexed. +- GraphQL gives you the flexibility to create custom queries for your application. ![Goldsky Dashboard](/assets/ecosystem/resources/goldsky/goldsky_img_1.png) -### Mirror: Real-Time Data Streaming Pipelines +### Mirror: Real-time data streaming pipelines -**Overview**: +**Overview:** -- The data model is flexible and open to any type of data. You can combine blockchain data with your own data seamlessly, offering more complex and customizable use cases. -- Using Transforms, you can also perform some pre-processing using SQL dialect as well as doing external processing on your HTTP endpoint before writing to your database. +- The data model is flexible and accepts any type of data. You can combine blockchain data with your own data for more complex and customizable use cases. +- With Transforms, you can also process data before it is written to your database. You can pre-process it with a SQL dialect, and you can do external processing on your HTTP endpoint. **Examples:** @@ -50,43 +50,43 @@ Let's dive into the difference in this guide and learn more about which solution - Capturing real-time price updates or liquidity changes in DeFi protocols. - Feeding live data into machine learning models for predictive analytics. -**Key Advantages:** +**Key advantages:** -- **Real-Time Data Flow**: Data is pushed directly to your database as new events occur on-chain. -- **Scalable Integration**: Supports ingestion of data from multiple blockchain networks into a centralized database. -- **Minimal Latency**: Ideal for use cases where immediate data availability is crucial. +- Mirror pushes data directly to your database as new events occur on-chain. +- Mirror scales to ingest data from multiple blockchain networks into a centralized database. +- Latency is minimal, so Mirror is ideal for use cases that need data to be available immediately. ![Goldsky Setup](/assets/ecosystem/resources/goldsky/goldsky_img_2.png) -### Mirror Data Sources Available +### Mirror data sources available **Sei EVM:** ![Goldsky Configuration](/assets/ecosystem/resources/goldsky/goldsky_img_3.png) -### Decision Guide: Subgraphs vs. Mirror +### Decision guide: Subgraphs vs. Mirror **Subgraphs** -- If you need to query specific Sei EVM data points or historical records, Subgraphs are the way to go. -- Best suited for applications that deal exclusively with on-chain data and don't need integration with off-chain sources. -- Ideal for predefined data models, such as dApps that need to query specific smart contract events or execute standard blockchain queries. -- Great for low to moderate traffic scenarios with relatively straightforward data structures and querying needs. +- If you need to query specific Sei EVM data points or historical records, use Subgraphs. +- Subgraphs are best for applications that use only on-chain data and do not need off-chain sources. +- They are ideal for predefined data models, such as dApps that need to query specific smart contract events or run standard blockchain queries. +- They are a good fit for low-to-moderate traffic with relatively simple data structures and query needs. **Mirror** -- A better fit for applications that require both on-chain and off-chain data, offering the flexibility to combine data sources for advanced analytics or decision-making. -- Ideal for multi-chain applications, as it simplifies the process of managing data across different blockchains without the need for reindexing. This is specially true if your application needs non-EVM data like Sei Cosmos. -- Perfect for high-traffic applications, where low latency and real-time data access are critical to the performance and user experience. +- Mirror is a better fit for applications that need both on-chain and off-chain data. You can combine data sources for advanced analytics or decision-making. +- It is ideal for multichain applications, because it makes data easier to manage across different blockchains without reindexing. This is especially true if your application needs non-EVM data, such as Sei Cosmos data. +- It suits high-traffic applications, where low latency and real-time data access are critical to performance and user experience. -**Example Use Case Comparison:** +**Example use case comparison:** -- **A DeFi Analytics Dashboard**: Use Subgraphs to retrieve historical liquidity data and user interactions. -- **A Real-Time Trading Bot**: Use Mirror to stream price changes directly into your database for instant action. +- **A DeFi analytics dashboard**: Use Subgraphs to get historical liquidity data and user interactions. +- **A real-time trading bot**: Use Mirror to stream price changes directly into your database, so that the bot can act instantly. -By understanding the strengths of each tool, you can select the right solution to match your project's data requirements. Goldsky is designed to offer flexibility, whether you need structured, queryable data or real-time data streams. Dive deeper into Subgraphs vs Mirror [here](https://docs.goldsky.com/subgraph-vs-mirror/?utm_source=sei&utm_medium=docs). +Select the tool that matches the data requirements of your project. Goldsky supports both structured, queryable data and real-time data streams. For more detail, read the [Goldsky comparison of Subgraphs and Mirror](https://docs.goldsky.com/subgraph-vs-mirror/?utm_source=sei&utm_medium=docs). -## Getting Started +## Getting started 1. Sign up for an account at [https://app.goldsky.com/signup](https://app.goldsky.com/signup). 2. Install the Goldsky CLI: @@ -96,26 +96,26 @@ By understanding the strengths of each tool, you can select the right solution t ``` 3. Go to your [Project Settings](https://app.goldsky.com/dashboard/settings) page and create an API key. -4. Back in your Goldsky CLI, log into your Project by running the command **`goldsky login`** and paste your API key. -5. Now that you are logged in, run **`goldsky`** to get started. +4. In the Goldsky CLI, run `goldsky login` to log in to your project, and then paste your API key. +5. After you log in, run `goldsky` to get started. ![Goldsky Results](/assets/ecosystem/resources/goldsky/goldsky_img_4.png) -## Deploy a Subgraph +## Deploy a subgraph -There are three primary ways to deploy a Subgraph on Goldsky: +You can deploy a subgraph on Goldsky in three main ways: 1. From source code -2. Migrating from The Graph or any other subgraph host -3. Via instant, no-code subgraphs +2. By migrating from The Graph or any other subgraph host +3. With instant, no-code subgraphs -Navigate to [this page](https://docs.goldsky.com/subgraphs/deploying-subgraphs/?utm_source=sei&utm_medium=docs) to learn more about each way of deploying a Subgraph. +To learn more about each way to deploy a subgraph, see [Deploying subgraphs](https://docs.goldsky.com/subgraphs/deploying-subgraphs/?utm_source=sei&utm_medium=docs) in the Goldsky docs. -## Deploy a Pipeline +## Deploy a pipeline -You have two options to create a Goldsky Mirror pipeline: +You can create a Goldsky Mirror pipeline in two ways: -1. **Flow**: With a guided web experience in the dashboard -2. **CLI**: interactively or by providing a pipeline configuration +1. **Flow**: Use the guided web experience in the dashboard. +2. **CLI**: Use the CLI interactively, or give it a pipeline configuration. -Navigate to [this page](https://docs.goldsky.com/mirror/create-a-pipeline/?utm_source=sei&utm_medium=docs) to learn more about deploying Mirror pipelines. +To learn more about how to deploy Mirror pipelines, see [Create a pipeline](https://docs.goldsky.com/mirror/create-a-pipeline/?utm_source=sei&utm_medium=docs) in the Goldsky docs. diff --git a/evm/indexer-providers/moralis.mdx b/evm/indexer-providers/moralis.mdx index 3959f6d..7a62511 100644 --- a/evm/indexer-providers/moralis.mdx +++ b/evm/indexer-providers/moralis.mdx @@ -3,55 +3,55 @@ title: 'Moralis' description: 'Complete guide to integrating Moralis with Sei blockchain for Web3 development' keywords: ['moralis', 'web3 api', 'blockchain indexer', 'NFT API', 'wallet API', 'token API', 'sei'] --- -Moralis is an enterprise-grade Web3 API provider that connects any tech stack to blockchain networks, offering multichain blockchain data for wallets, tokens, NFTs, DeFi protocols, and more through one fast, reliable API. +Moralis is a Web3 API provider that connects any tech stack to blockchain networks. Through one fast, reliable API, it gives you multichain data for wallets, tokens, NFTs, DeFi protocols, and more. -Moralis provides a comprehensive Backend-as-a-Service (BaaS) platform specifically designed for developers. By abstracting away the complexity of blockchain integration and offering a suite of APIs, SDKs, and scalable infrastructure, Moralis allows developers to focus on building the core functionality of their applications. +Moralis also has a Backend-as-a-Service (BaaS) platform for developers. It hides the complexity of blockchain integration and gives you a suite of APIs, SDKs, and scalable infrastructure. You can then focus on building the core functionality of your application. -## What You'll Learn +## What you'll learn -By the end of this tutorial, you'll understand: +This tutorial shows you how to: -- How to set up and configure Moralis for Sei blockchain integration -- Working with different Moralis APIs (Wallet, NFT, Token, and Blockchain APIs) -- Fetching wallet transactions and balances -- Retrieving NFT holder information and metadata -- Getting transaction details and token information +- Set up and configure Moralis for Sei +- Work with different Moralis APIs (Wallet, NFT, Token, and Blockchain APIs) +- Fetch wallet transactions and balances +- Get NFT holder information and metadata +- Get transaction details and token information ## Prerequisites -Before starting with this guide, ensure you have: +Before you start, make sure that you have: -1. **Moralis Account**: Create a free account at [moralis.io](https://moralis.io) +1. **Moralis account**: Create a free account at [moralis.io](https://moralis.io) 2. **Node.js**: Version 14 or higher installed -3. **Package Manager**: npm, yarn, or pnpm +3. **Package manager**: npm, yarn, or pnpm 4. **TypeScript**: Basic knowledge (optional but recommended) -### Sei Network Configuration +### Sei network configuration -Following is the configuration details of Sei for Moralis integration: +These are the Sei configuration details for a Moralis integration: -**Mainnet:** +**Sei Mainnet:** - Chain ID: 1329 (0x531) - RPC URL: https://evm-rpc.sei-apis.com -**Testnet:** +**Sei Testnet:** - Chain ID: 1328 (0x530) - RPC URL: https://evm-rpc-testnet.sei-apis.com -## Moralis APIs Overview +## Moralis APIs overview -Moralis offers several powerful APIs that work seamlessly across multiple blockchains: +Moralis has several APIs that work across multiple blockchains: -- **NFT API**: Access comprehensive NFT data including metadata, ownership details, and transaction history -- **Wallet API**: Retrieve real-time wallet data including balances, transaction history, and token holdings +- **NFT API**: Access NFT data, including metadata, ownership details, and transaction history +- **Wallet API**: Get real-time wallet data, including balances, transaction history, and token holdings - **Token API**: Get token information, prices, and transfer data -- **Blockchain API**: Fetch raw blockchain data - blocks, transactions, and logs -- **Price API**: Retrieve real-time and historical crypto token prices -- **DeFi API**: Query DeFi protocol data including pools, positions, and yields +- **Blockchain API**: Fetch raw blockchain data: blocks, transactions, and logs +- **Price API**: Get real-time and historical crypto token prices +- **DeFi API**: Query DeFi protocol data, including pools, positions, and yields -## Setting Up Your Project +## Setting up your project ### Install Moralis SDK @@ -73,13 +73,13 @@ npm install @moralisweb3/common-evm-utils npm install typescript ts-node @types/node --save-dev ``` -### Get Your API Key +### Get your API key 1. Sign up at [moralis.io](https://moralis.io) -2. Navigate to "Project Settings" +2. Go to **Project Settings** 3. Copy your API key from the dashboard -### Basic Configuration +### Basic configuration Create a `.env` file in your project root: @@ -108,7 +108,7 @@ const initMoralis = async () => { initMoralis(); ``` -## Wallet Transactions API +## Wallet transactions API ```typescript // Get wallet transactions for Sei Mainnet @@ -132,7 +132,7 @@ const walletAddress = '0x742d35Cc6636C0532925a3b8D62c5bceCdB8eBc8'; getWalletTransactions(walletAddress); ``` -## NFT Holders API +## NFT holders API ```typescript // Get NFTs owned by wallet address @@ -168,7 +168,7 @@ const getNFTOwners = async (contractAddress: string) => { }; ``` -## Transaction Details API +## Transaction details API ```typescript // Get detailed transaction information @@ -256,9 +256,9 @@ const getTokenMetadata = async (tokenAddress: string) => { }; ``` -## Complete Integration Example +## Complete integration example -Here's a comprehensive example that brings everything together: +This example combines several of the previous calls into one service: ```typescript import Moralis from 'moralis'; @@ -353,4 +353,4 @@ const response = await Moralis.EvmApi.transaction.getWalletTransactions({ }); ``` - For a complete API reference and additional guides visit the [Moralis Documentation](https://docs.moralis.com/) + For a complete API reference and more guides, see the [Moralis documentation](https://docs.moralis.com/). diff --git a/evm/indexer-providers/the-graph.mdx b/evm/indexer-providers/the-graph.mdx index e85a795..75b4fe5 100644 --- a/evm/indexer-providers/the-graph.mdx +++ b/evm/indexer-providers/the-graph.mdx @@ -3,84 +3,81 @@ title: "The Graph" description: "Build and deploy subgraphs on The Graph to efficiently index and query data from Sei smart contracts, with step-by-step instructions from initialization to production deployment." keywords: ["the graph", "subgraphs", "blockchain indexing", "graphql", "dapp data"] --- -Getting historical data on a smart contract can be frustrating when you're -building a dapp. [The Graph](https://thegraph.com/) provides an easy way to -query smart contract data through APIs known as subgraphs. The Graph's -infrastructure relies on a decentralized network of indexers, enabling your dapp -to become truly decentralized. +When you build a dApp, it can be difficult to get historical data for a smart +contract. [The Graph](https://thegraph.com/) gives you an easy way to query +smart contract data through APIs called subgraphs. The Graph's infrastructure +relies on a decentralized network of indexers. This lets your dApp be fully +decentralized. -## Quick Start +## Quick start -These subgraphs only take a few minutes to set up. To get started, follow these +A subgraph takes only a few minutes to set up. To get started, follow these three steps: 1. Initialize your subgraph project -2. Deploy & Publish -3. Query from your dapp +2. Deploy and publish +3. Query from your dApp -Pricing: **All developers receive 100K free queries per month on the -decentralized network**. After these free queries, you only pay based on usage -at $4 for every 100K queries. - -Here's a step by step walk through: +Pricing: All developers get 100K free queries per month on the decentralized +network. After these free queries, you pay only for usage, at $4 for every 100K +queries. ## 1. Initialize your subgraph project ### Create a subgraph on Subgraph Studio⁠ Go to the [Subgraph Studio](https://thegraph.com/studio/) and connect your -wallet. Once your wallet is connected, you can begin by clicking "Create a -Subgraph". When entering the subgraph name, it is recommended to use Title Case: -"Subgraph Name Chain Name." +wallet. Then click **Create a Subgraph**. When you enter the subgraph name, use +Title Case: "Subgraph Name Chain Name." ![Create a Subgraph](/assets/ecosystem/resources/the-graph/create_subgraph.png) *Create a Subgraph* -You will then land on your subgraph's page. All the CLI commands you need will -be visible on the right side of the page: +Your subgraph's page then opens. The right side of the page shows all the CLI +commands that you need: ![CLI commands](/assets/ecosystem/resources/the-graph/cli_commands.png) *CLI Commands* ### Install the Graph CLI⁠ -On your local machine run the following: +On your local machine, run this command: ```bash npm install -g @graphprotocol/graph-cli ``` -### Initialize your Subgraph⁠ +### Initialize your subgraph⁠ -You can copy this directly from your subgraph page to include your specific -subgraph slug: +You can copy this command from your subgraph page. The copied command includes +your subgraph slug: ```bash graph init --studio ``` -You'll be prompted to provide some info on your subgraph like this: +The CLI then prompts you for some information about your subgraph: ![CLI sample](/assets/ecosystem/resources/the-graph/cli_sample.png) *CLI* -Have your contract verified on the block explorer and the CLI will -automatically obtain the ABI and set up your subgraph. The default settings will -generate an entity for each event. +Make sure that your contract is verified on the block explorer. The CLI then +gets the ABI automatically and sets up your subgraph. The default settings generate an entity +for each event. -## 2. Deploy & Publish +## 2. Deploy & publish ### Deploy to Subgraph Studio⁠ -First run these commands: +First, run these commands: ```bash $ graph codegen $ graph build ``` -Then run these to authenticate and deploy your subgraph. You can copy these -commands directly from your subgraph's page in Studio to include your specific +Then run these commands to authenticate and deploy your subgraph. You can copy +them from your subgraph's page in Studio. The copied commands include your deploy key and subgraph slug: ```bash @@ -88,51 +85,47 @@ $ graph auth --studio $ graph deploy --studio ``` -You will be asked for a version label. You can enter something like v0.0.1, but -you're free to choose the format. +The CLI asks for a version label. You can enter something like v0.0.1, but you +can choose any format. ### Test your subgraph⁠ -You can test your subgraph by making a sample query in the playground section. -The Details tab will show you an API endpoint. You can use that endpoint to test -from your dapp. +You can test your subgraph with a sample query in the playground section. The +**Details** tab shows an API endpoint. You can use that endpoint to test from +your dApp. ![Playground](/assets/ecosystem/resources/the-graph/playground.png) -*Run your graphql query in Studio* +*Run your GraphQL query in Studio* -### Publish Your Subgraph to The Graph's Decentralized Network +### Publish your subgraph to The Graph's decentralized network -Once your subgraph is ready to be put into production, you can publish it to the -decentralized network. On your subgraph's page in Subgraph Studio, click on the -Publish button: +When your subgraph is ready for production, you can publish it to the +decentralized network. On your subgraph's page in Subgraph Studio, click +**Publish**: ![Publish button](/assets/ecosystem/resources/the-graph/publish_button.png) *Click Publish* -Before you can query your subgraph, Indexers need to begin serving queries on -it. In order to streamline this process, you can curate your own subgraph using -GRT. +Before you can query your subgraph, Indexers need to start serving queries on +it. To speed up this process, you can curate your own subgraph with GRT. -When publishing, you'll see the option to curate your subgraph. Signaling GRT -on your own subgraph helps ensure that it is indexed and available for querying -as soon as possible. See The Graph's -[curating documentation](https://thegraph.com/docs/en/resources/roles/curating/) -for current guidance on how much GRT to signal. +When you publish, you see the option to curate your subgraph. Signaling GRT on +your own subgraph helps make sure that it is indexed and available for queries +as soon as possible. For current guidance on how much GRT to signal, see The +Graph's [curating documentation](https://thegraph.com/docs/en/resources/roles/curating/). ![Publish screen](/assets/ecosystem/resources/the-graph/publish_screen.png) -*Publish Screen* - -**Note:** The Graph's smart contracts are all on Arbitrum One, even though > your subgraph is indexing data from Ethereum, BSC or any other > [supported chain](https://thegraph.com/docs/en/developing/supported-networks/). +*Publish screen* -## 3. Query your Subgraph +The Graph's smart contracts are all on Arbitrum One, even if your subgraph indexes data from Ethereum, BSC, or any other [supported chain](https://thegraph.com/docs/en/developing/supported-networks/). -Congratulations! You can now query your subgraph on the decentralized network! +## 3. Query your subgraph -For any subgraph on the decentralized network, you can start querying it by -passing a GraphQL query into the subgraph's query URL which can be found at the -top of its Explorer page. +To query any subgraph on the decentralized network, pass a GraphQL query to the +subgraph's query URL. You can find the query URL at the top of the subgraph's +Explorer page. -Here's an example from the +This example is from the [CryptoPunks Ethereum subgraph](https://thegraph.com/explorer/subgraphs/HdVdERFUe8h61vm2fDyycHgxjsde5PbB832NHgJfZNqK) by Messari: @@ -142,20 +135,19 @@ by Messari: The query URL for this subgraph is: `https://gateway-arbitrum.network.thegraph.com/api/`**[api-key]**`/subgraphs/id/HdVdERFUe8h61vm2fDyycHgxjsde5PbB832NHgJfZNqK` -Now, you need to fill in your own API Key to start sending GraphQL -queries to this endpoint. +To send GraphQL queries to this endpoint, fill in your own API key. -### Getting your own API Key +### Getting your own API key ![API keys](/assets/ecosystem/resources/the-graph/api_keys.png) *API keys* -In Subgraph Studio, you'll see the "API Keys" menu at the top of the page. Here -you can create API Keys. +In Subgraph Studio, the **API Keys** menu is at the top of the page. You can +create API keys there. ## Appendix -### Sample Query +### Sample query This query shows the most expensive CryptoPunks sold. @@ -168,7 +160,7 @@ This query shows the most expensive CryptoPunks sold. } ``` -Passing this into the query URL returns this result: +If you pass this query to the query URL, it returns this result: ```json { @@ -186,7 +178,7 @@ Passing this into the query URL returns this result: ``` - Trivia: Looking at the top sales on [CryptoPunks website](https://cryptopunks.app/cryptopunks/topsales) it looks like the top sale is Punk #5822, not #9998. Why? Because they censor the flash-loan sale that happened. + Trivia: The top sales list on the [CryptoPunks website](https://cryptopunks.app/cryptopunks/topsales) shows Punk #5822 as the top sale, not #9998. The reason is that the website censors the flash-loan sale. ### Sample code @@ -225,8 +217,8 @@ axios(graphQLRequest) ### Additional resources: -- To explore all the ways you can optimize & customize your subgraph for a - better performance, read more about - [creating a subgraph here](https://thegraph.com/docs/en/developing/creating-a-subgraph/). -- For more information about querying data from your subgraph, read more - [here](https://thegraph.com/docs/en/querying/querying-the-graph/). +- To learn the ways that you can optimize and customize your subgraph for better + performance, read about + [creating a subgraph](https://thegraph.com/docs/en/developing/creating-a-subgraph/). +- For more information about how to query data from your subgraph, see the + [querying documentation](https://thegraph.com/docs/en/querying/querying-the-graph/). diff --git a/evm/installing-seid-cli.mdx b/evm/installing-seid-cli.mdx index 6b0b6e4..f30f135 100644 --- a/evm/installing-seid-cli.mdx +++ b/evm/installing-seid-cli.mdx @@ -8,15 +8,15 @@ import { VersionTable } from '/snippets/version-table.jsx'; ## What is seid CLI? -The `seid` CLI is the command-line tool for interacting with the Sei blockchain. It allows you to manage wallets, send transactions, query network data, and perform validator operations. +The `seid` CLI is the command-line tool to interact with Sei. It lets you manage wallets, send transactions, query network data, and perform validator operations. ## Prerequisites -- [Go 1.25.6 or later](https://go.dev/doc/install) is required only when building from source. Check the `go.mod` at the release tag you check out below (e.g. [`v6.6.1`](https://github.com/sei-protocol/sei-chain/blob/v6.6.1/go.mod)) for its exact requirement. Prebuilt binaries have no prerequisites. +- [Go 1.25.6 or later](https://go.dev/doc/install) is required only when you build from source. For the exact requirement, read the `go.mod` file at the release tag that you check out below, for example [`v6.6.1`](https://github.com/sei-protocol/sei-chain/blob/v6.6.1/go.mod). Prebuilt binaries have no prerequisites. ## Installation -To install `seid`, locate the version you wish to use on the [sei-chain releases page](https://github.com/sei-protocol/sei-chain/releases). A list of the currently used versions on mainnet and testnet are displayed right below. +To install `seid`, find the version that you want on the [sei-chain releases page](https://github.com/sei-protocol/sei-chain/releases). The table below lists the versions currently in use on Sei Mainnet and Sei Testnet. @@ -39,15 +39,15 @@ To install `seid`, locate the version you wish to use on the [sei-chain releases ``` - Prebuilt binaries are attached from `v6.6.1` onward — for earlier versions, build - from source. They are `linux/amd64` only and omit hardware Ledger support. On - other architectures, or if you sign with a Ledger device, build from source. + Prebuilt binaries are attached from `v6.6.1` onward. For earlier versions, build + from source. The binaries are `linux/amd64` only and omit hardware Ledger support. + On other architectures, or if you sign with a Ledger device, build from source. - Previously installed with `make install`? An older copy in `$(go env GOPATH)/bin` - can shadow `/usr/local/bin/seid` depending on your `PATH` order — `which -a seid` - lists every copy. + If you previously installed `seid` with `make install`, an older copy in + `$(go env GOPATH)/bin` can shadow `/usr/local/bin/seid`, depending on your `PATH` + order. `which -a seid` lists every copy. @@ -61,29 +61,29 @@ To install `seid`, locate the version you wish to use on the [sei-chain releases -You can verify that `seid` was installed correctly by running: +To verify that `seid` is installed correctly, run this command: ```bash seid version ``` -## Troubleshooting Installation +## Troubleshooting installation -If you built from source and encounter an error like `command not found: seid`, you may need to set your GOPATH environment variable. +If you built from source and get an error such as `command not found: seid`, you may need to set your GOPATH environment variable. -- Use `go env GOPATH` to find your GOPATH -- Add the following lines to your `~/.bashrc` or `~/.zshrc`: +- To find your GOPATH, run `go env GOPATH`. +- Add these lines to your `~/.bashrc` or `~/.zshrc` file: ```bash export GOPATH=[your GOPATH from step 1] export PATH=$PATH:$GOPATH/bin ``` -For more information see [here](https://pkg.go.dev/cmd/go#hdr-GOPATH_environment_variable). +For more information, see [GOPATH environment variable](https://pkg.go.dev/cmd/go#hdr-GOPATH_environment_variable) in the Go documentation. -## Command Overview +## Command overview -Seid supports all the commands you need to interact with the chain. To see a list of available commands and explanations of what they do, run seid: +`seid` supports all the commands that you need to interact with the chain. To list the available commands with a short description of each, run `seid`: ```bash seid @@ -128,11 +128,11 @@ Flags: Use "seid [command] --help" for more information about a command. ``` -The `compact`, `latest_version`, and `prune` maintenance commands were removed in v6.6.0. To read the latest memIAVL version (the former `latest_version`), use `seidb memiavl-latest-version`. Historical-data retention is managed through `min-retain-blocks` in the base `app.toml` and `ss-keep-recent` under `[state-store]`. +The `compact`, `latest_version`, and `prune` maintenance commands were removed in v6.6.0. To read the latest memIAVL version (the former `latest_version`), use `seidb memiavl-latest-version`. `min-retain-blocks` in the base `app.toml` and `ss-keep-recent` under `[state-store]` control historical-data retention. -## Adding a Wallet +## Adding a wallet -You can create a new wallet using the seid keys command: +To create a new wallet, use the `seid keys` command: ```bash seid keys add $NAME @@ -155,11 +155,11 @@ It is the only way to recover your account if you ever forget your password. ``` -Please replace `$NAME` with the name you would like to use for this key. This will generate a seed phrase and store the account in the CLI for use. +Replace `$NAME` with the name that you want for this key. The command generates a seed phrase and stores the account in the CLI. -**Important**: Write this mnemonic down and store it in a safe place. Never share your seed phrase with anyone. +Write down this seed phrase and store it in a safe place. Never share your seed phrase with anyone. -Alternatively, if you would like to import an existing seed phrase, you can add the `--recover` flag: +To import an existing seed phrase instead, add the `--recover` flag: ```bash seid keys add $NAME --recover @@ -167,7 +167,7 @@ seid keys add $NAME --recover Output: -This will prompt you to enter your seed phrase, allowing you to import an existing wallet into the CLI. +The command prompts you to enter your seed phrase. It then imports the existing wallet into the CLI. ```bash > Enter your bip39 mnemonic @@ -181,18 +181,18 @@ This will prompt you to enter your seed phrase, allowing you to import an existi mnemonic: "" ``` -## EVM Wallet Compatibility +## EVM wallet compatibility -### Understanding Coin Types +### Understanding coin types Sei supports two coin types: - Coin type 118 (default): Standard Cosmos address format - Coin type 60: Ethereum-compatible address format for EVM wallets -### Creating an EVM-Compatible Wallet +### Creating an EVM-compatible wallet -To create a new wallet that's compatible with EVM wallets like MetaMask: +To create a new wallet that is compatible with EVM wallets such as MetaMask, run this command: ```bash seid keys add $NAME --coin-type=60 @@ -215,11 +215,11 @@ It is the only way to recover your account if you ever forget your password. ``` -`evm_address` is shown as empty here because it's only displayed after the key first broadcasts a transaction or is associated on-chain. The `0x` address is deterministically derived from the secp256k1 public key. +`evm_address` is empty here because the CLI shows it only after the key first broadcasts a transaction or is associated on-chain. The `0x` address is derived deterministically from the secp256k1 public key. -### Importing an Existing EVM Wallet +### Importing an existing EVM wallet -To import an existing wallet from MetaMask or other EVM wallets: +To import an existing wallet from MetaMask or another EVM wallet, run this command: ```bash seid keys add $NAME --coin-type=60 --recover @@ -239,13 +239,13 @@ Output: mnemonic: "" ``` -You'll be prompted to enter your existing 12 or 24-word mnemonic phrase. +The command prompts you to enter your existing 12-word or 24-word seed phrase. -Use coin type 60 when you want to use the same address across EVM-compatible chains or import from MetaMask. Use the default coin type 118 for standard Cosmos operations. +To use the same address across EVM-compatible chains or to import from MetaMask, use coin type 60. For standard Cosmos operations, use the default coin type 118. -## Managing Wallets +## Managing wallets -To see your local wallets, you can run: +To list all the wallets that you added to your local keyring, run this command: ```bash seid keys list @@ -263,7 +263,7 @@ Output: ... ``` -to see a list of all wallets added, or +To see details about a specific wallet, run this command: ```bash seid keys show $NAME @@ -280,11 +280,9 @@ Output: mnemonic: "" ``` -to see details about a specific wallet. +## Deleting wallets -## Deleting Wallets - -To delete a wallet/key, you can use the following command: +To delete a wallet or key, run this command: ```bash seid keys delete $NAME @@ -297,11 +295,11 @@ Key reference will be deleted. Continue? [y/N]: y Key deleted forever (uh oh!) ``` -This will remove the specified wallet from your local keyring. Be cautious, as this action cannot be undone. +This command removes the specified wallet from your local keyring. Be careful, because you cannot undo this action. ## Uninstalling seid -If you need to remove `seid` from your system, delete the binary from wherever it was installed: +To remove `seid` from your system, delete the binary from the location where you installed it: ```bash # Prebuilt binary install diff --git a/evm/ledger-ethers.mdx b/evm/ledger-ethers.mdx index 1439231..f587f2d 100644 --- a/evm/ledger-ethers.mdx +++ b/evm/ledger-ethers.mdx @@ -3,32 +3,32 @@ title: 'Ledger Setup (EVM)' description: 'Set up your Ledger hardware wallet for signing EVM transactions on Sei, including device configuration, Ethers.js integration, and a simple transfer example.' keywords: ['ledger wallet', 'ethers.js', 'hardware wallet', 'blockchain security', 'sei transactions', 'evm'] --- -This guide covers connecting a Ledger hardware wallet to Sei EVM for signing transactions with Ethers.js. +This guide shows how to connect a Ledger hardware wallet to Sei EVM and sign transactions with ethers.js. -`@sei-js/ledger` is no longer in the sei-js monorepo. npm still serves deprecated `1.1.6`; do not install it. It previously handled Cosmos-side Amino signing, and there is no replacement package for that flow. Cosmos SDK signing is deprecated. See [SIP-3](/learn/sip-03-migration) and the [Cosmos SDK deprecation notice](/cosmos-sdk). This page covers EVM transactions only. +`@sei-js/ledger` is no longer in the sei-js monorepo. Do not install the deprecated version `1.1.6`, which npm still serves. The package previously handled Cosmos-side Amino signing, and there is no replacement package for that flow. Cosmos SDK signing is deprecated. See [SIP-3](/learn/sip-03-migration) and the [Cosmos SDK deprecation notice](/cosmos-sdk). This page covers EVM transactions only. ## Prerequisites -1. **Ledger App Installation** +1. **Install the Ledger app** - On your Ledger device, open the Manager in Ledger Live and install **either** the **Sei** app **or** the **Ethereum** app. The Ethereum app supports any EVM chain (like Sei), but the native Sei app may provide optimal compatibility. + Open the **Manager** in Ledger Live. Install either the **Sei** app or the **Ethereum** app on your Ledger device. The Ethereum app supports any EVM chain, including Sei, but the native Sei app may give the best compatibility. -2. **Enable Blind Signing** +2. **Enable blind signing** - In the Ledger device's Ethereum or Sei app settings, **enable "Blind signing"**. This permits the device to sign arbitrary EVM transactions and contract calls (e.g. precompiles), which would otherwise be rejected. + In the settings of the Ethereum or Sei app on the Ledger device, enable **Blind signing**. This setting lets the device sign arbitrary EVM transactions and contract calls (for example, precompile calls). Without it, the device rejects them. -3. **USB Permissions (Linux only)** +3. **Set up USB permissions (Linux only)** - You'll need a **udev rule** so your process can talk to the Ledger over USB/HID. Clone the official rules from [LedgerHQ/udev-rules](https://github.com/LedgerHQ/udev-rules), copy `49-ledger.rules` into `/etc/udev/rules.d/`, then run `sudo udevadm control --reload-rules` and replug your Ledger. + Your process needs a udev rule to communicate with the Ledger over USB HID. Clone the official rules from [LedgerHQ/udev-rules](https://github.com/LedgerHQ/udev-rules). Copy `49-ledger.rules` into `/etc/udev/rules.d/`. Run `sudo udevadm control --reload-rules`. Then disconnect your Ledger and connect it again. -4. **Install Dependencies** +4. **Install dependencies** ```bash npm install ethers @ethers-ext/signer-ledger @ledgerhq/hw-transport-node-hid ``` -## Connecting Your Ledger +## Connecting your Ledger ```tsx import { LedgerSigner } from '@ethers-ext/signer-ledger'; @@ -43,11 +43,11 @@ const addr = await signer.getAddress(); console.log('Using Ledger address:', addr); ``` -Every transaction sent through this signer will require physical confirmation on the Ledger device. +Every transaction that you send through this signer requires physical confirmation on the Ledger device. -## Sending a Transfer +## Sending a transfer -A simple example sending SEI from your Ledger to another address: +This example sends SEI from your Ledger to another address: ```tsx import { LedgerSigner } from '@ethers-ext/signer-ledger'; @@ -67,10 +67,10 @@ const receipt = await tx.wait(); console.log('Confirmed in block:', receipt.blockNumber); ``` -This signer works with any contract interaction — you can pass it to `ethers.Contract` constructors to sign [precompile](/evm/precompiles) calls, ERC-20 transfers, or any other EVM transaction. +This signer works with any contract interaction. You can pass it to `ethers.Contract` constructors to sign [precompile](/evm/precompiles) calls, ERC-20 transfers, or any other EVM transaction. ## Troubleshooting -- **Timeouts:** If the Ledger times out, increase the HID timeouts or ensure the device stays awake during signing. -- **"Blind signing required" errors:** Double-check that blind signing is enabled in the app settings on the device itself. -- **Connection failures:** Make sure no other application (e.g. Ledger Live) is holding the USB connection to your device. +- **Timeouts:** If the Ledger times out, increase the HID timeouts or make sure that the device stays awake during signing. +- **"Blind signing required" errors:** Check that blind signing is enabled in the app settings on the device itself. +- **Connection failures:** Make sure that no other application, such as Ledger Live, holds the USB connection to your device. diff --git a/evm/migrate-from-other-evms.mdx b/evm/migrate-from-other-evms.mdx index 2e11d79..ef1bf26 100644 --- a/evm/migrate-from-other-evms.mdx +++ b/evm/migrate-from-other-evms.mdx @@ -4,65 +4,65 @@ sidebarTitle: 'Migrate from Other EVMs' description: 'Step-by-step checklist for teams that already run on another EVM chain and want to redeploy on Sei, including environment prep, contract migration, liquidity planning, and chain-specific guidance for Ethereum, Arbitrum, Base, Polygon, and Avalanche.' keywords: ['EVM migration', 'cross-chain deployment', 'ethereum to sei', 'arbitrum to sei', 'base to sei', 'polygon to sei', 'avalanche to sei', 'smart contract deployment'] --- -Sei offers full EVM bytecode compatibility plus instant finality and sub-second blocks. This guide distills what product teams need to do when they already run on Polygon, Base, Ethereum, Arbitrum, Avalanche or another EVM chain and want to bring your dApp stack to Sei. +Sei has full EVM bytecode compatibility, instant finality, and sub-second blocks. This guide is for product teams that already run on Polygon, Base, Ethereum, Arbitrum, Avalanche, or another EVM chain. It shows what you need to do to bring your dApp stack to Sei. -**Why Migrate to Sei?** +**Why migrate to Sei?** -- **400ms block times** – 30× faster than Ethereum, 2-5× faster than most L2s -- **~100 MGas/s throughput** – 20× higher than Ethereum mainnet -- **Instant finality (~400 ms)** – No waiting for confirmations or safe/finalized states -- **Parallelized execution** – Higher throughput without code changes -- **Full EVM compatibility** – Deploy your existing Solidity contracts unchanged +- Block times are 400 ms, which is 30× faster than Ethereum and 2 to 5× faster than most L2s. +- Throughput is approximately 100 MGas/s, which is 20× higher than Ethereum mainnet. +- Finality is instant (approximately 400 ms). You do not wait for confirmations or for safe or finalized states. +- Parallelized execution gives higher throughput without code changes. +- Full EVM compatibility lets you deploy your existing Solidity contracts unchanged. ## Chain comparison overview -Before diving into migration steps, understand how Sei compares to your source chain: +Before you start the migration steps, see how Sei compares with your source chain: | Feature | Sei | Ethereum | Arbitrum | Base | Polygon PoS | Avalanche C-Chain | | --- | --- | --- | --- | --- | --- | --- | | Chain ID | 1329 | 1 | 42161 | 8453 | 137 | 43114 | -| Block Time | 400 ms | ~12 s | ~250 ms | ~2 s | ~2 s | ~2 s | +| Block time | 400 ms | ~12 s | ~250 ms | ~2 s | ~2 s | ~2 s | | Finality | Instant (~400 ms) | ~15 min (finalized) | ~7 days (L1 settlement) | ~7 days (L1 settlement) | ~5 s (Heimdall v2) | ~1 s | -| Gas Limit | 12.5 M | 60M | 32M | 375M | 45M | Dynamic | -| Per-Tx Gas Cap | 12.5 M | ~16.7 M | 32 M | ~25 M | 45 M | Dynamic | -| Native Token | SEI | ETH | ETH | ETH | POL (MATIC) | AVAX | -| Parallel Execution | Yes | No | No | No | No | No | -| Base Fee Burn | No (100% to validators) | Yes (EIP-1559) | Yes | Yes | Yes | Yes | -| EVM Version | Pectra (w/o blobs) | Fusaka | Fusaka | Pectra | Pectra | Cancun | +| Gas limit | 12.5 M | 60M | 32M | 375M | 45M | Dynamic | +| Per-tx gas cap | 12.5 M | ~16.7 M | 32 M | ~25 M | 45 M | Dynamic | +| Native token | SEI | ETH | ETH | ETH | POL (MATIC) | AVAX | +| Parallel execution | Yes | No | No | No | No | No | +| Base fee burn | No (100% to validators) | Yes (EIP-1559) | Yes | Yes | Yes | Yes | +| EVM version | Pectra (without blobs) | Fusaka | Fusaka | Pectra | Pectra | Cancun | ## Chain-specific migration guides -Select your source chain to see specific migration considerations: +Select your source chain to see the migration considerations for that chain: ### Migrating from Ethereum Mainnet -**Key Differences:** +**Key differences:** -| Aspect | Ethereum | Sei | Migration Impact | +| Aspect | Ethereum | Sei | Migration impact | | --- | --- | --- | --- | | Block time | ~12 seconds | 400 ms | Reduce `deadline` buffers in DEX swaps by 30× | | Finality | ~15 min for finalized | Instant (~400 ms) | Remove confirmation polling logic | | Gas limit | ~16.7M per TX (EIP-7825) | 12.5 M per block/TX | Split large batch deployments | -| Fee model | EIP-1559 with burn | EIP-1559 different params | Update fee estimation UIs | +| Fee model | EIP-1559 with burn | EIP-1559 with different parameters | Update fee estimation UIs | | Pending state | Yes | No | Remove pending transaction logic | -**What to Update:** +**What to update:** -1. **Time-based logic:** If your contracts use block timestamps for deadlines, reduce timeouts proportionally. A 30-minute deadline on Ethereum (~150 blocks) should be ~45 seconds on Sei (~112 blocks). +1. **Time-based logic:** If your contracts use block timestamps for deadlines, reduce the timeouts proportionally. A 30-minute deadline on Ethereum is approximately 150 blocks. On Sei, the deadline should be approximately 45 seconds (approximately 112 blocks). -2. **Confirmation requirements:** Remove any logic that waits for multiple confirmations or checks "safe" vs "finalized" states—Sei has instant finality. +2. **Confirmation requirements:** Remove any logic that waits for multiple confirmations or checks "safe" versus "finalized" states. Sei has instant finality. -3. **Gas estimation:** Sei's parallelized execution can slightly vary gas estimates. Add a modest buffer (10-15%) to your `gasLimit` calculations. +3. **Gas estimation:** Sei's parallelized execution can make gas estimates vary slightly. Add a modest buffer (10 to 15%) to your `gasLimit` calculations. -4. **Fee UI:** Simplify your frontend—you can use a single `gasPrice` input instead of `maxFeePerGas` / `maxPriorityFeePerGas`. +4. **Fee UI:** Simplify your frontend. You can use a single `gasPrice` input instead of `maxFeePerGas` and `maxPriorityFeePerGas`. ```ts // Before (Ethereum EIP-1559) @@ -77,18 +77,18 @@ const tx = await contract.method({ }); ``` -Sei enforces a 50 gwei minimum gas price; transactions below this are rejected by the mempool. Query the live value with `eth_gasPrice` (returns base fee + suggested tip). +Sei enforces a minimum gas price of 50 gwei. The mempool rejects transactions below this price. Query the live value with `eth_gasPrice`, which returns the base fee plus a suggested tip. -5. **PREVRANDAO/DIFFICULTY:** If you use these for any randomness, integrate a VRF oracle instead—Sei's values are derived from block time, not true randomness. +5. **PREVRANDAO and DIFFICULTY:** If you use these opcodes for any randomness, integrate a VRF oracle instead. On Sei, their values are derived from block time, not from true randomness. ### Migrating from Arbitrum -**Key Differences:** +**Key differences:** -| Aspect | Arbitrum | Sei | Migration Impact | +| Aspect | Arbitrum | Sei | Migration impact | | --- | --- | --- | --- | | Architecture | Optimistic Rollup (L2) | L1 | No L1 data availability concerns | | Finality | ~7 days for L1 settlement | Instant (~400 ms) | Simplify withdrawal flows | @@ -97,13 +97,13 @@ const tx = await contract.method({ | L1 gas | Pays L1 data costs | No L1 dependency | Simpler fee structure | -**What to Update:** +**What to update:** -1. **Remove L1 interactions:** Any logic that posts data to or reads from Ethereum L1 should be removed or replaced with Sei-native alternatives. +1. **Remove L1 interactions:** Find any logic that posts data to Ethereum L1 or reads data from it. Remove that logic, or replace it with a Sei-native alternative. -2. **Sequencer assumptions:** Remove any sequencer uptime checks or fallback logic—Sei uses decentralized consensus. +2. **Sequencer assumptions:** Remove any sequencer uptime checks or fallback logic. Sei uses decentralized consensus. -3. **Withdrawal delays:** If your protocol has 7-day withdrawal windows for "L1 finality," you can remove these—Sei settles instantly. +3. **Withdrawal delays:** If your protocol has 7-day withdrawal windows for "L1 finality," you can remove them. Sei settles instantly. 4. **ArbOS precompiles:** Replace any Arbitrum-specific precompiles: @@ -123,9 +123,9 @@ uint256 blockNum = block.number; // Standard EVM ### Migrating from Base -**Key Differences:** +**Key differences:** -| Aspect | Base | Sei | Migration Impact | +| Aspect | Base | Sei | Migration impact | | --- | --- | --- | --- | | Architecture | OP Stack Rollup (L2) | L1 | No L1 data availability concerns | | Finality | ~7 days for L1 settlement | Instant (~400 ms) | Simplify withdrawal flows | @@ -134,11 +134,11 @@ uint256 blockNum = block.number; // Standard EVM | EIP-4844 blobs | Supported | Not supported | Remove blob transaction logic | -**What to Update:** +**What to update:** -1. **Remove blob transactions:** Sei doesn't support EIP-4844 blob transactions. If you're using them for data availability, store data differently or use Sei's native mechanisms. +1. **Remove blob transactions:** Sei does not support EIP-4844 blob transactions. If you use them for data availability, store the data differently or use Sei's native mechanisms. -2. **OP Stack precompiles:** Remove any Optimism/Base-specific precompile calls: +2. **OP Stack precompiles:** Remove any precompile calls that are specific to Optimism or Base: ```solidity // Base-specific (remove) @@ -148,11 +148,11 @@ uint256 blockNum = block.number; // Standard EVM uint256 blockNum = block.number; ``` -3. **Fault proof assumptions:** Remove any logic that accounts for the 7-day challenge period—Sei has instant finality. +3. **Fault proof assumptions:** Remove any logic that accounts for the 7-day challenge period. Sei has instant finality. 4. **Sequencer fee logic:** Base has a separate L1 data fee component. On Sei, fees are simpler: `Gas Used × Gas Price`. -5. **Coinbase Wallet integrations:** Update wallet connection logic to use Sei network parameters: +5. **Coinbase Wallet integrations:** Update your wallet connection logic to use the Sei network parameters: ```ts // Update network config @@ -170,9 +170,9 @@ const seiMainnet = { ### Migrating from Polygon PoS -**Key Differences:** +**Key differences:** -| Aspect | Polygon PoS | Sei | Migration Impact | +| Aspect | Polygon PoS | Sei | Migration impact | | --- | --- | --- | --- | | Native token | POL (MATIC) | SEI | Update all token references | | Block time | ~2 seconds | 400 ms | 5× faster blocks | @@ -181,9 +181,9 @@ const seiMainnet = { | Reorgs | Possible (rare) | Never | Remove reorg handling | -**What to Update:** +**What to update:** -1. **Token references:** Replace all MATIC/POL references with SEI: +1. **Token references:** Replace all MATIC and POL references with SEI: ```solidity // Before (Polygon) @@ -193,13 +193,13 @@ const seiMainnet = { // Check ecosystem contracts for canonical WSEI address ``` -2. **Checkpoint logic:** Remove any logic that waits for Polygon checkpoints to Ethereum—Sei has instant finality. +2. **Checkpoint logic:** Remove any logic that waits for Polygon checkpoints to Ethereum. Sei has instant finality. -3. **Heimdall/Bor assumptions:** Remove any Polygon-specific validator or sidechain logic. +3. **Heimdall and Bor assumptions:** Remove any Polygon-specific validator or sidechain logic. -4. **Reorg handling:** You can safely remove block reorganization handling code—Sei's consensus prevents reorgs. +4. **Reorg handling:** You can safely remove the code that handles block reorganizations. Sei's consensus prevents reorgs. -5. **Gas price oracles:** Polygon's gas prices can spike significantly. Sei's fees are more stable due to higher throughput: +5. **Gas price oracles:** Polygon's gas prices can spike significantly. Sei's fees are more stable because of higher throughput: ```ts // Polygon - needed aggressive gas price management @@ -210,25 +210,25 @@ const boostedPrice = gasPrice.mul(120).div(100); // 20% buffer const gasPrice = await provider.getGasPrice(); // Usually sufficient as-is ``` -6. **Bridge integrations:** Replace Polygon Bridge with [LayerZero](/evm/bridging/layerzero) or other Sei-supported bridges. +6. **Bridge integrations:** Replace the Polygon Bridge with [LayerZero](/evm/bridging/layerzero) or other Sei-supported bridges. ### Migrating from Avalanche C-Chain -**Key Differences:** +**Key differences:** -| Aspect | Avalanche C-Chain | Sei | Migration Impact | +| Aspect | Avalanche C-Chain | Sei | Migration impact | | --- | --- | --- | --- | | Native token | AVAX | SEI | Update all token references | | Block time | ~2 seconds | 400 ms | 5× faster blocks | | Finality | ~1 second | Instant (~400 ms) | Similar, slightly faster | | Subnets | Supported | N/A | Remove subnet logic | -| Gas limit | Dynamic (post-Octane) | 12.5 M | Large tx headroom varies; benchmark deployments | +| Gas limit | Dynamic (post-Octane) | 12.5 M | Large tx headroom varies, so benchmark deployments | -**What to Update:** +**What to update:** 1. **Token references:** Replace AVAX with SEI: @@ -240,7 +240,7 @@ const gasPrice = await provider.getGasPrice(); // Usually sufficient as-is // Use native SEI or check ecosystem contracts for WSEI ``` -2. **Subnet interactions:** If your dApp uses Avalanche Subnets, you'll need to redesign that architecture for Sei's single-chain model or use cross-chain messaging. +2. **Subnet interactions:** If your dApp uses Avalanche Subnets, redesign that architecture for Sei's single-chain model, or use cross-chain messaging. 3. **Avalanche-specific precompiles:** Remove C-Chain precompile calls: @@ -251,14 +251,14 @@ const gasPrice = await provider.getGasPrice(); // Usually sufficient as-is // Use standard EVM patterns on Sei ``` -4. **Gas limit adjustments:** Avalanche now uses a dynamic gas model after Octane, while Sei has a fixed `12.5M` block/tx cap. If you have large transactions, benchmark them on Sei and split them when needed: +4. **Gas limit adjustments:** Avalanche now uses a dynamic gas model after Octane. Sei has a fixed `12.5M` cap per block and per transaction. If you have large transactions, benchmark them on Sei and split them when needed: ```ts // If deploying large contracts, batch by gas const MAX_GAS_PER_BATCH = 11_500_000; // Leave buffer under 12.5M ``` -5. **TWAP calculations:** Both chains have fast blocks, but adjust your observation windows if migrating oracle logic: +5. **TWAP calculations:** Both chains have fast blocks. If you migrate oracle logic, adjust your observation windows: ```solidity // Avalanche: 1 hour = ~1800 blocks @@ -271,11 +271,11 @@ uint32 constant TWAP_PERIOD = 9000; // Adjust for Sei's block time ## Step 1: Evaluate compatibility -Revisit the [Divergence from Ethereum](/evm/differences-with-ethereum) doc and confirm every assumption your contracts/frontends make still holds. +Review the [Divergence from Ethereum](/evm/differences-with-ethereum) page. Confirm that every assumption your contracts and frontends make still holds. -| Dimension | Sei EVM | Practical Effect | +| Dimension | Sei EVM | Practical effect | | --- | --- | --- | -| Block time | 400 ms | Faster TX inclusion → smaller `deadline` buffers and quicker price oracles | +| Block time | 400 ms | Faster TX inclusion means smaller `deadline` buffers and quicker price oracles | | Finality | Instant (~400 ms) | No separate "safe/latest" commitment levels to poll | | Gas limit | 12.5M gas + 21 MB byte limit | Batch contract deployments by 12.5M gas blocks | | Base fee | Dynamic but never burned | Validators receive 100% of fees | @@ -285,20 +285,20 @@ Revisit the [Divergence from Ethereum](/evm/differences-with-ethereum) doc and c -**Features Requiring Attention:** +**Features that need attention:** -- **Pending state:** Sei doesn't have pending state — transactions are either included or not -- **Blob opcodes:** EIP-4844 blob transactions are not supported -- **PREVRANDAO entropy:** Returns block-time-derived value, not true randomness — use VRF oracles here -- **SELFDESTRUCT:** Deprecated; refactor to "soft close" patterns +- **Pending state:** Sei does not have a pending state. A transaction is either included or not. +- **Blob opcodes:** Sei does not support EIP-4844 blob transactions. +- **PREVRANDAO entropy:** Use VRF oracles for randomness. PREVRANDAO returns a value derived from block time, not true randomness. +- **SELFDESTRUCT:** Refactor to "soft close" patterns. This opcode is deprecated. ## Step 2: Prepare your development environment -### Add Sei Network configuration +### Add Sei network configuration -**Hardhat Configuration:** +**Hardhat configuration:** ```ts title="hardhat.config.ts" import { defineConfig, configVariable } from 'hardhat/config'; @@ -323,9 +323,9 @@ export default defineConfig({ }); ``` -Store your deployer key in Hardhat's encrypted keystore with `npx hardhat keystore set SEI_PRIVATE_KEY`. Contract verification via Sourcify is enabled by default in Hardhat 3's `hardhat-verify` (bundled with the toolbox). +Store your deployer key in Hardhat's encrypted keystore with `npx hardhat keystore set SEI_PRIVATE_KEY`. In Hardhat 3, `hardhat-verify` (bundled with the toolbox) enables contract verification through Sourcify by default. -**Foundry Configuration:** +**Foundry configuration:** ```toml title="foundry.toml" [profile.default] @@ -341,11 +341,11 @@ sei_testnet = "https://evm-rpc-testnet.sei-apis.com" # Run: forge verify-contract --verifier sourcify --chain-id
``` -See the [Hardhat tutorial](/evm/evm-hardhat) and [Foundry guide](/evm/evm-foundry) for complete setup instructions. +For complete setup instructions, see the [Hardhat tutorial](/evm/evm-hardhat) and the [Foundry guide](/evm/evm-foundry). ### Wallet configuration -Pre-configure MetaMask or other wallets with Sei chain params: +Preconfigure MetaMask or other wallets with the Sei chain parameters: ```ts const seiMainnet = { @@ -364,7 +364,7 @@ await window.ethereum.request({ ## Step 3: Bootstrap common infrastructure -Sei already exposes canonical helper contracts—reference them instead of redeploying: +Sei already exposes canonical helper contracts. Reference them instead of redeploying them: | Component | Address | Notes | | --- | --- | --- | @@ -374,7 +374,7 @@ Sei already exposes canonical helper contracts—reference them instead of redep | SingletonFactory | `0xce0042B868300000d44A59004Da54A005ffdcf9f` | EIP-2470 singleton factory | -For third-party contracts (LayerZero, Safe, etc.), consult the full [Ecosystem Contracts page](/evm/ecosystem-contracts). +For LayerZero, Safe, and other third-party contracts, see the full [Ecosystem Contracts page](/evm/ecosystem-contracts). ## Step 4: Port contracts and configuration @@ -396,8 +396,8 @@ function getDeadline(uint256 secondsFromNow) internal view returns (uint256) { ### Adjust gas and size assumptions -- Keep `gasLimit` buffers modest but ensure calldata stays under 21 MB -- Sei's 12.5M gas limit per block means large deployments may need batching +- Keep `gasLimit` buffers modest, but make sure that calldata stays under 21 MB. +- Sei's gas limit is 12.5M per block, so large deployments may need batching. ### Refactor deprecated patterns @@ -445,9 +445,9 @@ const seiContract = { ### Oracle integration -Sei supports multiple oracle solutions: +Sei supports these oracles: -| Provider | Use Case | Documentation | +| Provider | Use case | Documentation | | --- | --- | --- | | Pyth Network | High-frequency price feeds | [Pyth Network](https://docs.pyth.network/) | | Chainlink | Industry-standard data feeds | [Chainlink on Sei](/evm/oracles/chainlink) | @@ -455,34 +455,34 @@ Sei supports multiple oracle solutions: | API3 | First-party oracle data | [API3 on Sei](/evm/oracles/api3) | -**TWAP Adjustments:** Because Sei blocks arrive ~30× faster than Ethereum, shorten your TWAP observation windows to maintain comparable time-weighted calculations. +**TWAP adjustments:** Sei blocks arrive approximately 30× faster than Ethereum blocks. Shorten your TWAP observation windows to keep your time-weighted calculations comparable. ## Step 7: Launch checklist ### Sei Testnet deployment -- [ ] Deploy all contracts to testnet (chain ID: `1328`) -- [ ] Run full integration test suite -- [ ] Verify contracts via [Sourcify](/evm/evm-verify-contracts) +- [ ] Deploy all contracts to Sei Testnet (chain ID: `1328`) +- [ ] Run the full integration test suite +- [ ] Verify the contracts with [Sourcify](/evm/evm-verify-contracts) - [ ] Test wallet connections and transaction flows -- [ ] Validate oracle integrations -- [ ] Test cross-chain messaging if applicable +- [ ] Validate your oracle integrations +- [ ] If applicable, test cross-chain messaging ### Sei Mainnet deployment -- [ ] Deploy contracts to mainnet (chain ID: `1329`) -- [ ] Re-run smoke tests +- [ ] Deploy the contracts to Sei Mainnet (chain ID: `1329`) +- [ ] Run the smoke tests again - [ ] Verify all contracts on Sourcify -- [ ] Update frontend configurations -- [ ] Prepare user migration documentation +- [ ] Update the frontend configurations +- [ ] Prepare migration documentation for your users -**Fee Redistribution Warning:** Fees on Sei are not burned. If your protocol redistributes "burn rebates" to users, redesign that logic so it does not expect a base-fee burn component. +**Fee redistribution:** If your protocol redistributes "burn rebates" to users, redesign that logic so it does not expect a base-fee burn component. Sei does not burn fees. ## Step 8: Operational readiness ### Contract verification -Automate verification through CI using [Sourcify](/evm/evm-verify-contracts): +Automate verification in CI with [Sourcify](/evm/evm-verify-contracts): ```bash # Foundry verification @@ -497,11 +497,11 @@ forge verify-contract --watch \ - **Primary RPC:** `https://evm-rpc.sei-apis.com` - **Testnet RPC:** `https://evm-rpc-testnet.sei-apis.com` -- For mission-critical paths, consider self-hosted nodes or [premium RPC providers](/learn/rpc-providers) +- For mission-critical paths, consider self-hosted nodes or [premium RPC providers](/learn/rpc-providers). ### Monitoring gas parameters -Periodically query fee data to keep dashboards aligned: +Query fee data periodically to keep your dashboards up to date: ```ts // Monitor current gas prices @@ -511,30 +511,30 @@ const gasPrice = await provider.getGasPrice(); ## Example: Uniswap V3-style deployment -Here's how to mirror a Uniswap V3 experience on Sei: +Use these steps to reproduce a Uniswap V3 experience on Sei: -1. **Routers & Factories:** Deploy your own or fork the existing DragonSwap stack: +1. **Routers and factories:** Deploy your own, or fork the existing DragonSwap stack: - Router: `0xdD489C75be1039ec7d843A6aC2Fd658350B067Cf` - V3 Factory: `0x75FC67473A91335B5b8F8821277262a13B38c9b3` - Position Manager: `0x8B3c541c30f9b29560f56B9E44b59718916B69EF` 2. **Permit and Multicall:** Point your frontend SDK to the shared `Permit2` and `Multicall3` addresses above. -3. **Liquidity Migration Script:** Build a helper that: - - Withdraws LP on source chain - - Bridges underlying tokens to Sei +3. **Liquidity migration script:** Build a helper that: + - Withdraws LP on the source chain + - Bridges the underlying tokens to Sei - Mints new Sei LP positions - - Include gas estimations tuned for Sei's 12.5M block cap + - Includes gas estimates tuned for Sei's 12.5M block cap -4. **Price Oracles:** Reuse TWAP/Chainlink logic but shorten observation windows for Sei's faster blocks. +4. **Price oracles:** Reuse your TWAP or Chainlink logic, but shorten the observation windows for Sei's faster blocks. -5. **Verification:** Submit to [Sourcify](/evm/evm-verify-contracts) and the [Ecosystem Contracts registry](/evm/ecosystem-contracts). +5. **Verification:** Submit your contracts to [Sourcify](/evm/evm-verify-contracts) and the [Ecosystem Contracts registry](/evm/ecosystem-contracts). ## Helpful references -- [Divergence from Ethereum](/evm/differences-with-ethereum) – Opcode, gas, and state nuances -- [EVM Networks](/evm/networks) – RPCs, explorers, and MetaMask payloads -- [Precompiles](/evm/precompiles/example-usage) – Interoperability patterns -- [Ecosystem Contracts](/evm/ecosystem-contracts) – Canonical addresses -- [LayerZero Integration](/evm/bridging/layerzero) – Cross-chain messaging -- [Contract Verification](/evm/evm-verify-contracts) – Contract verification guide +- [Divergence from Ethereum](/evm/differences-with-ethereum): opcode, gas, and state differences +- [EVM Networks](/evm/networks): RPCs, explorers, and MetaMask payloads +- [Precompiles](/evm/precompiles/example-usage): interoperability patterns +- [Ecosystem Contracts](/evm/ecosystem-contracts): canonical addresses +- [LayerZero Integration](/evm/bridging/layerzero): cross-chain messaging +- [Contract Verification](/evm/evm-verify-contracts): contract verification guide diff --git a/evm/migrate-from-solana.mdx b/evm/migrate-from-solana.mdx index 65c0d15..f1211d5 100644 --- a/evm/migrate-from-solana.mdx +++ b/evm/migrate-from-solana.mdx @@ -4,42 +4,42 @@ sidebarTitle: 'Migrate from Solana' description: 'A comprehensive guide for Solana developers transitioning to Sei EVM, covering architectural differences, concept mapping, code translation patterns, and step-by-step migration strategies.' keywords: ['solana migration', 'rust to solidity', 'anchor to hardhat', 'EVM migration', 'parallel execution', 'sei'] --- -Sei offers a unique value proposition for Solana developers: the parallelized execution model you're familiar with, combined with full EVM compatibility and the extensive Ethereum tooling ecosystem. This guide helps Rust/Anchor developers translate their mental models and codebases to Solidity on Sei. +Sei combines parallelized execution, which you know from Solana, with full EVM compatibility and the extensive Ethereum tooling ecosystem. This guide helps Rust and Anchor developers translate their mental models and codebases to Solidity on Sei. -**Why Solana Developers Choose Sei** +**Why Solana developers choose Sei** -- **Familiar parallelization** – Sei uses optimistic parallel execution similar to Solana's Sealevel -- **400ms block times** – Comparable to Solana's speed, with instant finality -- **~100 MGas/s throughput** – High performance without sacrificing EVM compatibility -- **EVM ecosystem access** – Leverage Ethereum's mature tooling, audited contracts, and developer resources -- **No dependency declarations** – Unlike Solana, Sei handles parallelization automatically +- Sei uses optimistic parallel execution, similar to Solana's Sealevel. +- Block times of 400 ms are comparable to Solana's speed, and finality is instant. +- Throughput is approximately 100 MGas/s, with full EVM compatibility. +- You can use Ethereum's mature tooling, audited contracts, and developer resources. +- You do not declare dependencies. Unlike Solana, Sei handles parallelization automatically. -## Understanding the Paradigm Shift +## Understanding the paradigm shift -Before diving into code, it's essential to understand the fundamental architectural differences between Solana and EVM-based chains like Sei. +Before you write code, understand the architectural differences between Solana and EVM-based chains such as Sei. -### Execution Model Comparison +### Execution model comparison | Aspect | Solana | Sei EVM | | --- | --- | --- | | Language | Rust (with Anchor framework) | Solidity | -| Account Model | Programs + Accounts (separated code and data) | Contracts (code and storage unified) | -| State Storage | Flat account data with owner programs | Contract storage slots (key-value) | +| Account model | Programs + Accounts (separated code and data) | Contracts (code and storage unified) | +| State storage | Flat account data with owner programs | Contract storage slots (key-value) | | Parallelization | Explicit (declare accounts upfront) | Optimistic (automatic conflict detection) | -| Block Time | ~400ms | 400ms | +| Block time | ~400ms | 400ms | | Finality | ~2.5-4.5 seconds (32 confirmations) | Instant (single block) | -| Fee Model | Compute units + priority fees + rent | Gas × Gas Price (no rent) | -| Cross-Contract Calls | CPI (Cross-Program Invocation) | Internal/External function calls | -| Deterministic Addresses | PDAs (Program Derived Addresses) | CREATE2 / ImmutableCreate2Factory | -| Token Standard | SPL Token | ERC-20 / ERC-721 / ERC-1155 | -| Dev Tooling | Anchor, Solana CLI, solana-web3.js | Hardhat, Foundry, ethers.js, viem | +| Fee model | Compute units + priority fees + rent | Gas × Gas Price (no rent) | +| Cross-contract calls | CPI (Cross-Program Invocation) | Internal/External function calls | +| Deterministic addresses | PDAs (Program Derived Addresses) | CREATE2 / ImmutableCreate2Factory | +| Token standard | SPL Token | ERC-20 / ERC-721 / ERC-1155 | +| Dev tooling | Anchor, Solana CLI, solana-web3.js | Hardhat, Foundry, ethers.js, viem | -## Core Concept Mapping +## Core concept mapping -### Programs → Smart Contracts +### Programs → smart contracts On Solana, you write **programs** that are stateless executables. Data lives in separate **accounts** that programs can read and modify. On Sei EVM, **smart contracts** combine code and state in a single entity. @@ -110,13 +110,13 @@ contract Counter { **Key differences:** -- No account space allocation needed—storage grows dynamically -- No explicit `Signer` validation—`msg.sender` is always authenticated -- No system program imports—native operations are built into the EVM +- You do not allocate account space. Storage grows dynamically. +- You do not validate a `Signer` explicitly. `msg.sender` is always authenticated. +- You do not import a system program. Native operations are built into the EVM. -### PDAs → CREATE2 Deterministic Addresses +### PDAs → CREATE2 deterministic addresses -Solana's **Program Derived Addresses (PDAs)** let you create deterministic addresses from seeds. On EVM, you achieve similar functionality with `CREATE2`. +Solana's **Program Derived Addresses (PDAs)** let you create deterministic addresses from seeds. On the EVM, you get similar functionality with `CREATE2`. @@ -165,9 +165,9 @@ mapping(address => Vault) public vaults; -### CPI → Contract Calls +### CPI → contract calls -Solana's **Cross-Program Invocation (CPI)** becomes simple function calls in Solidity: +Solana's **Cross-Program Invocation (CPI)** becomes a simple function call in Solidity: @@ -247,21 +247,21 @@ contract MyToken is ERC20 { **Key ERC-20 differences from SPL:** -- No Associated Token Accounts (ATAs)—balances are stored directly in the contract -- Approvals use `approve()` / `transferFrom()` pattern -- No mint/freeze authorities in basic implementation (add via `Ownable`) +- ERC-20 has no Associated Token Accounts (ATAs). Balances are stored directly in the contract. +- Approvals use the `approve()` and `transferFrom()` pattern. +- The basic implementation has no mint or freeze authorities. To add them, use `Ownable`. -## Fee Model Translation +## Fee model translation -Understanding the fee differences is crucial for accurate cost estimation: +To estimate costs accurately, learn how the fee models differ: -| Solana Concept | Sei EVM Equivalent | Notes | -| ------------------ | ------------------ | ------------------------------------- | -| Compute Units (CU) | Gas | Both measure computational work | -| Priority Fee | Gas Price | Higher price = faster inclusion | -| Rent | None | Sei has no rent; storage is permanent | -| Rent Exemption | N/A | No minimum balance requirements | -| Base Fee | Dynamic Base Fee | Sei doesn't burn base fee | +| Solana concept | Sei EVM equivalent | Notes | +| ------------------ | ------------------ | -------------------------------------- | +| Compute units (CU) | Gas | Both measure computational work | +| Priority fee | Gas price | Higher price = faster inclusion | +| Rent | None | Sei has no rent. Storage is permanent. | +| Rent exemption | N/A | No minimum balance requirements | +| Base fee | Dynamic base fee | Sei does not burn the base fee | ```ts // Solana fee estimation @@ -276,19 +276,19 @@ const fee = gasLimit * gasPrice; // No rent to consider ``` -**No Rent on Sei!** +**No rent on Sei** -Unlike Solana where accounts can be garbage collected if rent isn't paid, Sei EVM storage is permanent. This simplifies your application logic—no need to track rent-exempt minimums or worry about account closure. +On Solana, accounts can be garbage collected if rent is not paid. On Sei EVM, storage is permanent. This simplifies your application logic: you do not need to track rent-exempt minimums or worry about account closure. -## Parallelization: Automatic vs Explicit +## Parallelization: automatic vs explicit -One of the biggest advantages of Sei for Solana developers is that parallelization is **automatic**. +On Sei, parallelization is **automatic**. -### Solana: Explicit Account Declaration +### Solana: explicit account declaration -On Solana, you must declare all accounts a transaction will touch upfront: +On Solana, you must declare upfront every account that a transaction will touch: ```rust // Solana: Must declare all accounts for parallelization @@ -308,9 +308,9 @@ pub struct Swap<'info> { } ``` -### Sei: Optimistic Parallelization +### Sei: optimistic parallelization -On Sei, you write normal Solidity—the runtime handles parallelization: +On Sei, you write normal Solidity, and the runtime handles parallelization: ```solidity // Sei EVM: Just write normal code @@ -331,15 +331,15 @@ function swap( ``` -**Optimizing for Parallelization** +**Optimizing for parallelization** -While Sei handles parallelization automatically, you can still optimize your contracts for better parallel performance. Avoid global counters updated on every transaction—use user-partitioned storage instead. See [Optimizing for Parallelization](/evm/best-practices/optimizing-for-parallelization) for detailed patterns. +Avoid global counters that every transaction updates. Use user-partitioned storage instead. Sei handles parallelization automatically, but you can still optimize your contracts for better parallel performance. For detailed patterns, see [Optimizing for Parallelization](/evm/best-practices/optimizing-for-parallelization). -## Step 1: Set Up Your Development Environment +## Step 1: Set up your development environment -### Install Required Tools +### Install required tools ```bash # Install Node.js (if not already installed) @@ -382,7 +382,7 @@ export default defineConfig({ }); ``` -Store your deployer key in Hardhat's encrypted keystore (no plaintext `.env` file needed): +Store your deployer key in Hardhat's encrypted keystore instead of a plaintext `.env` file: ```bash npx hardhat keystore set SEI_PRIVATE_KEY @@ -409,9 +409,9 @@ sei_testnet = "https://evm-rpc-testnet.sei-apis.com" -### Wallet Setup +### Wallet setup -Configure MetaMask or any EVM wallet with Sei: +Configure MetaMask or any EVM wallet for Sei: ```ts const seiMainnet = { @@ -423,11 +423,11 @@ const seiMainnet = { }; ``` -## Step 2: Translate Your Solana Program +## Step 2: Translate your Solana program -### Common Pattern Translations +### Common pattern translations -#### Initializing State +#### Initializing state @@ -467,7 +467,7 @@ contract MyContract { -#### Access Control +#### Access control @@ -524,7 +524,7 @@ contract MyContract { -#### Error Handling +#### Error handling @@ -562,7 +562,7 @@ if (balance < required) revert InsufficientBalance(balance, required); -#### Events/Logs +#### Events/logs @@ -604,9 +604,9 @@ emit Transfer(from, to, amount); -## Step 3: Frontend Migration +## Step 3: Frontend migration -### SDK Comparison +### SDK comparison | Solana | Sei EVM | Notes | | ------------------------ | ------------------------ | ------------------------------ | @@ -615,7 +615,7 @@ emit Transfer(from, to, amount); | `@solana/wallet-adapter` | `wagmi` / `RainbowKit` | Wallet connection | | Phantom, Solflare | MetaMask, Rabby, Backpack | Popular wallets | -### Code Translation +### Code translation @@ -664,9 +664,9 @@ await tx.wait(); -## Step 4: Testing Your Migrated Code +## Step 4: Testing your migrated code -### Test Framework Comparison +### Test framework comparison @@ -722,9 +722,9 @@ describe('Counter', function () { -## Step 5: Deploy and Verify +## Step 5: Deploy and verify -### Deploy to Testnet +### Deploy to testnet ```bash # Hardhat @@ -736,7 +736,7 @@ forge create --rpc-url https://evm-rpc-testnet.sei-apis.com \ src/Counter.sol:Counter ``` -### Verify Contract +### Verify contract ```bash # Hardhat @@ -750,9 +750,9 @@ forge verify-contract \ src/Counter.sol:Counter ``` -## Common Migration Pitfalls +## Common migration pitfalls -### 1. Expecting Rent +### 1. Expecting rent ```solidity // ❌ Wrong: No need to check rent exemption @@ -762,7 +762,7 @@ require(address(this).balance >= rentExempt, "Not rent exempt"); // Storage persists without rent payments ``` -### 2. Manual Account Validation +### 2. Manual account validation ```solidity // ❌ Wrong: Over-engineering account checks (Solana habit) @@ -772,7 +772,7 @@ require(accountOwner == expectedOwner, "Invalid account owner"); // msg.sender is already authenticated ``` -### 3. Expecting Explicit Parallelization +### 3. Expecting explicit parallelization ```solidity // ❌ Wrong: Trying to declare "accounts" for parallelization @@ -782,7 +782,7 @@ function swap(address[] memory accounts) external { ... } function swap(address tokenIn, address tokenOut, uint256 amount) external { ... } ``` -### 4. Using Lamports Mental Model +### 4. Using lamports mental model ```solidity // ❌ Wrong: Solana-style lamports @@ -793,37 +793,37 @@ uint256 amount = 1 ether; // 1 SEI = 1e18 wei uint256 amount = 1e18; // Same thing ``` -## Ecosystem Infrastructure +## Ecosystem infrastructure ### Available on Sei -| Component | Solana Equivalent | Sei Address/Info | +| Component | Solana equivalent | Sei address/info | | --------------- | ------------------------- | ------------------------------------------------------------------------------------------------ | | Multicall3 | N/A | `0xcA11bde05977b3631167028862bE2a173976CA11` | | Permit2 | N/A | `0xB952578f3520EE8Ea45b7914994dcf4702cEe578` | | CREATE2 Factory | N/A | `0x0000000000FFe8B47B3e2130213B802212439497` | -| Oracle | Pyth Network, Switchboard | [Pyth](/evm/oracles/pyth-network), [Redstone](/evm/oracles/redstone), [Chainlink](/evm/oracles/chainlink) | -| Bridge | Wormhole | [LayerZero](/evm/bridging/layerzero), Wormhole, many more.. | +| Oracle | Pyth Network, Switchboard | [Pyth](/evm/oracles/pyth-network), [RedStone](/evm/oracles/redstone), [Chainlink](/evm/oracles/chainlink) | +| Bridge | Wormhole | [LayerZero](/evm/bridging/layerzero), Wormhole, and many others | -## Helpful Resources +## Helpful resources ### Learning Solidity -- [EVM with Foundry](/evm/evm-foundry) – Foundry setup guide and starter tutorial -- [EVM with Hardhat](/evm/evm-hardhat) – Hardhat setup guide and starter tutorial -- [Solidity Resources](/evm/solidity-resources) – Curated solidity learning resources -- [CryptoZombies](https://cryptozombies.io) – Interactive Solidity tutorial -- [Solidity by Example](https://solidity-by-example.org) – Pattern reference +- [EVM with Foundry](/evm/evm-foundry): Foundry setup guide and starter tutorial +- [EVM with Hardhat](/evm/evm-hardhat): Hardhat setup guide and starter tutorial +- [Solidity Resources](/evm/solidity-resources): curated Solidity learning resources +- [CryptoZombies](https://cryptozombies.io): interactive Solidity tutorial +- [Solidity by Example](https://solidity-by-example.org): pattern reference -### Sei-Specific +### Sei-specific -- [Divergence from Ethereum](/evm/differences-with-ethereum) – Technical differences -- [Optimizing for Parallelization](/evm/best-practices/optimizing-for-parallelization) – Performance patterns -- [Ecosystem Contracts](/evm/ecosystem-contracts) – Canonical addresses +- [Divergence from Ethereum](/evm/differences-with-ethereum): technical differences +- [Optimizing for Parallelization](/evm/best-practices/optimizing-for-parallelization): performance patterns +- [Ecosystem Contracts](/evm/ecosystem-contracts): canonical addresses -**Need Help?** +**Need help?** -Join the [Sei Tech Chat](https://t.me/+KZdhZ1eE-G01NmZk) on Telegram for developer support. The community is active and helpful for migration questions. +For developer support, join the [Sei Tech Chat](https://t.me/+KZdhZ1eE-G01NmZk) on Telegram. The community is active and helps with migration questions. diff --git a/evm/networks.mdx b/evm/networks.mdx index 1d4472a..d3e24f0 100644 --- a/evm/networks.mdx +++ b/evm/networks.mdx @@ -9,7 +9,7 @@ import { NetworkTabs } from '/snippets/network-tabs.jsx'; -The panel above is interactive. For plain-text endpoints you can copy directly — plus additional provider options — see: +The panel above is interactive. For plain-text endpoints that you can copy directly, and for more provider options, see: -- [Chains & endpoints](/learn/dev-chains) — RPC URLs and chain IDs in plain text -- [RPC providers](/learn/rpc-providers) — additional public and commercial RPC endpoints +- [Chains & endpoints](/learn/dev-chains): RPC URLs and chain IDs in plain text +- [RPC providers](/learn/rpc-providers): more public and commercial RPC endpoints diff --git a/evm/nonce-lanes.mdx b/evm/nonce-lanes.mdx index 86d38f2..f87f232 100644 --- a/evm/nonce-lanes.mdx +++ b/evm/nonce-lanes.mdx @@ -9,16 +9,22 @@ import { SequentialNonceQueue, NonceLanes, NonceLaneDelegation, NonceLanePipelin One funded account on Sei EVM has one sequential nonce. That suits a wallet, where each action follows the last. It does not suit a stream of independent work: one transaction that never lands blocks every transaction signed after it. The usual fix is a fleet of hot wallets, which multiplies balances, approvals, and keys. -[sei-nonce-lanes](https://github.com/sei-protocol/sei-nonce-lanes) is a reference implementation that removes the queue instead. One funded externally owned account (EOA) keeps its address, balance, and approvals while holding many mutually independent operations in flight at the same time. +[sei-nonce-lanes](https://github.com/sei-protocol/sei-nonce-lanes) is a reference implementation that removes the queue instead. With it, one funded externally owned account (EOA) holds many mutually independent operations in flight at the same time. The account keeps its address, balance, and approvals. -The pattern applies whenever one funded address needs to do many things that do not depend on each other: market making and order flow, liquidation and keeper bots, oracle updates, payout and claim batching, or game and backend transactions. +The pattern applies whenever one funded address needs to do many things that do not depend on each other, for example: + +- Market making and order flow +- Liquidation and keeper bots +- Oracle updates +- Payout and claim batching +- Game and backend transactions - The repository is a runnable engineering demonstration, not a production service. It uses a mock venue, plaintext development keys in `.env`, an in-process queue, and console output. Read [Before you adapt this](#before-you-adapt-this) before pointing it at real funds. + The repository is a runnable engineering demonstration, not a production service. It uses a mock venue, plaintext development keys in `.env`, an in-process queue, and console output. Read [Before you adapt this](#before-you-adapt-this) before you point it at real funds. - This page is about submission concurrency. If you want a hosted bundler, a paymaster, and gas sponsorship for consumer wallets, start with [Pimlico](/evm/wallet-integrations/pimlico) or [Thirdweb EIP-7702](/evm/wallet-integrations/thirdweb-7702) instead. Nonce lanes solve the opposite problem: throughput from one address you control, with no third party in the submission path. + This page is about submission concurrency. For a hosted bundler, a paymaster, and gas sponsorship for consumer wallets, start with [Pimlico](/evm/wallet-integrations/pimlico) or [thirdweb EIP-7702](/evm/wallet-integrations/thirdweb-7702) instead. Nonce lanes solve the opposite problem: throughput from one address you control, with no third party in the submission path. ## Why one account is one queue @@ -34,20 +40,20 @@ The second case is the submission bottleneck. It covers transactions that are dr -Two properties of Sei make this sharper than on Ethereum: +Two properties of Sei make this problem worse than on Ethereum: -- **Strict nonce admission.** Under Giga, the Autobahn producer mempool admits EVM transactions in per-sender nonce order and rejects a gap with a `bad nonce` error instead of holding it for later. See [Giga mode behavior](/node/technical-reference#giga-mode-behavior-and-per-block-limits). What you observe through an RPC endpoint can differ, because the node in front of the producer may hold a gapped transaction and release it later, or accept it and then drop it. The repository's `npm run baseline` command probes the RPC path you configure; in one session it returned [two different verdicts](#optional-see-the-baseline-you-are-escaping) for two Sei Testnet endpoints. -- **No dependable pending view.** Sei does not expose Ethereum-style pending state, and [Finality and block tags](/evm/evm-parity/finality#pending-state) tells you not to rely on a pending nonce differing from the confirmed nonce. `txpool_content` is also [truncated and collapses the pending/queued distinction](/evm/reference). Even where a node answers a pending-nonce query, the value cannot be used to rebuild an in-flight queue. +- **Strict nonce admission.** Under Giga, the Autobahn producer mempool admits EVM transactions in per-sender nonce order. It rejects a gap with a `bad nonce` error instead of holding it for later (see [Giga mode behavior](/node/technical-reference#giga-mode-behavior-and-per-block-limits)). What you observe through an RPC endpoint can differ. The node in front of the producer may hold a gapped transaction and release it later, or accept it and then drop it. The repository's `npm run baseline` command probes the RPC path you configure. In one session, it returned [two different verdicts](#optional-see-the-baseline-you-are-escaping) for two Sei Testnet endpoints. +- **No dependable pending view.** Sei does not expose Ethereum-style pending state. [Finality and block tags](/evm/evm-parity/finality#pending-state) tells you not to rely on a pending nonce that differs from the confirmed nonce. `txpool_content` is also [truncated and does not separate pending from queued transactions](/evm/reference). Even where a node answers a pending-nonce query, you cannot use the value to rebuild an in-flight queue. - Do not design around a pending nonce on Sei. `eth_getTransactionCount(address, "pending")` is [documented](/evm/reference) as returning `EvmNextPendingNonce` from the mempool, so it is not an alias for `"latest"`. The finality guidance still marks the pending view as unreliable, and the value varies by node and by whether the node runs Giga. The design below does not depend on the answer: its hot path reads no nonces. + Do not design around a pending nonce on Sei. `eth_getTransactionCount(address, "pending")` is [documented](/evm/reference) as returning `EvmNextPendingNonce` from the mempool. It is therefore not an alias for `"latest"`. The finality guidance still marks the pending view as unreliable. The value also varies by node and by whether the node runs Giga. The design below does not depend on the answer: its hot path reads no nonces. -Splitting work across hot wallets raises throughput, but every wallet is another balance to rebalance, another set of approvals to maintain, and another key that can move funds. +Splitting work across hot wallets raises throughput. However, every wallet is another balance to rebalance, another set of approvals to maintain, and another key that can move funds. ## How it works -The design combines four mechanisms. Each solves one part of the problem; none is sufficient alone. +The design combines four mechanisms. Each solves one part of the problem, and none is sufficient alone. | Mechanism | What it contributes | | --- | --- | @@ -58,13 +64,13 @@ The design combines four mechanisms. Each solves one part of the problem; none i ### ERC-4337 nonce lanes -The canonical EntryPoint v0.8 singleton is already deployed at `0x4337084D9E255Ff0702461CF8895CE9E3b5Ff108` on both Sei Mainnet (chain ID `1329`) and Sei Testnet (chain ID `1328`), so nothing here asks you to deploy one. It stores a UserOperation nonce as a 192-bit key plus a 64-bit sequence: +The canonical EntryPoint v0.8 singleton is already deployed at `0x4337084D9E255Ff0702461CF8895CE9E3b5Ff108` on both Sei Mainnet (chain ID `1329`) and Sei Testnet (chain ID `1328`). Nothing in this guide asks you to deploy one. The EntryPoint stores a UserOperation nonce as a 192-bit key plus a 64-bit sequence: ```text nonce = (uint192 key << 64) | uint64 sequence ``` -The EntryPoint keeps one `sequence` counter for each `key`. The specification calls this a two-dimensional nonce; the repository calls a key a **lane**. +The EntryPoint keeps one `sequence` counter for each `key`. The specification calls this a two-dimensional nonce. The repository calls a key a **lane**. @@ -75,7 +81,7 @@ Four rules follow from that layout: - An operation that executes and reverts still consumes its lane sequence. - An operation that never reaches a successful `handleOps` transaction consumes nothing. -`LaneAccount` rejects lane `0`. Most SDKs pick key `0` when you do not pass one, and work that lands entirely on key `0` is a single queue again. Rejecting it converts a silent fallback into an explicit validation failure. `ADMIN_LANE` (the maximum `uint192`) is reserved for integrations that need one explicitly ordered lane for administrative calls. +`LaneAccount` rejects lane `0`. Most SDKs pick key `0` when you do not pass one. Work that lands entirely on key `0` is a single queue again. Rejecting it converts a silent fallback into an explicit validation failure. `ADMIN_LANE` (the maximum `uint192`) is reserved for integrations that need one explicitly ordered lane for administrative calls. ### EIP-7702 keeps the funded address @@ -85,7 +91,7 @@ An EIP-7702 authorization writes a delegation designator into the EOA's code slo 0xef0100 || ``` -The address does not change. Its native balance, token balances, protocol state, and approvals stay attached to the same account. When the EntryPoint calls the account, the EVM runs `LaneAccount`'s code in the EOA's context, so `LaneAccount.execute` reaches the target with the funded EOA as `msg.sender`. +The address does not change. Its native balance, token balances, protocol state, and approvals stay attached to the same account. When the EntryPoint calls the account, the EVM runs `LaneAccount`'s code in the EOA's context. As a result, `LaneAccount.execute` reaches the target with the funded EOA as `msg.sender`. @@ -103,12 +109,14 @@ contract LaneAccount is Simple7702Account { } ``` -Installing the delegation takes one type-4 transaction. Sei requires a non-empty authorization list on type-4 transactions; see [Transaction types](/evm/evm-parity/transaction-types#set-code-eip-7702-auth-list-requirement). +Installing the delegation takes one type-4 transaction. Sei requires a non-empty authorization list on type-4 transactions. See [Transaction types](/evm/evm-parity/transaction-types#set-code-eip-7702-auth-list-requirement). + +The nonce cost depends on who sends that transaction. The EVM applies the authorization list after it increments the sender's nonce for the transaction itself. When the authority is also the sender, the authorization must therefore be signed over `nonce + 1`. Applying it then increments the account's nonce a second time. -The nonce cost depends on who sends that transaction. The EVM applies the authorization list after incrementing the sender's nonce for the transaction itself, so when the authority is also the sender, the authorization must be signed over `nonce + 1` and applying it increments the account a second time. A self-sponsored delegation advances the account's nonce by two; `npm run delegate` takes this path. A delegation sponsored by a different sender advances the funded account by one, the increment the authorization itself performs. In both cases, once the designator is in place, the submission path signs UserOperations only and the funded account's EVM nonce stops moving. +A self-sponsored delegation advances the account's nonce by two. `npm run delegate` takes this path. A delegation sponsored by a different sender advances the funded account's nonce by one: the increment that the authorization itself performs. In both cases, after the designator is in place, the submission path signs only UserOperations. The funded account's EVM nonce then stops moving. - EIP-7702 alone does not create independent nonces; it preserves the account. ERC-4337 supplies the nonce model. The design needs both. + EIP-7702 alone does not create independent nonces. It preserves the account, and ERC-4337 supplies the nonce model. The design needs both. ### Gas-only relayers carry what is left of the queue @@ -119,28 +127,32 @@ UserOperations are not transactions. Something still has to wrap them in `EntryP The sequential constraint moves rather than disappears. Each relayer has one sequential EVM nonce and keeps one outer transaction in flight at a time. The custody boundary is what changes: relayers hold native SEI for gas and nothing else. A compromised relayer key can lose its own gas balance or rebroadcast operations the funded account already signed. It cannot create a new operation, because every UserOperation carries an EIP-712 signature from the funded account over the EntryPoint's `PackedUserOperation` digest. -The bundling queue matters for a different reason. It is an in-process queue, not a mempool: nothing is gossiped, nothing arrives from another party, and it is gone when the process exits. It therefore never enters the canonical ERC-4337 alt-mempool, and the [ERC-7562](https://eips.ethereum.org/EIPS/eip-7562) validation rules that govern that mempool, including `SAME_SENDER_MEMPOOL_COUNT = 4` for an unstaked sender, do not apply to it. A cap of four pending operations per sender is sized for wallets, not for a submission pipeline. Those rules exist so competing bundlers can safely pack operations from unrelated senders into one bundle. Here every operation comes from one account you control, so that threat does not arise. The EntryPoint still enforces everything that protects funds: the signature, per-lane nonce uniqueness, and prefund solvency. +The bundling queue matters for a different reason. It is an in-process queue, not a mempool. Nothing is gossiped, nothing arrives from another party, and the queue is gone when the process exits. It therefore never enters the canonical ERC-4337 alt-mempool. The [ERC-7562](https://eips.ethereum.org/EIPS/eip-7562) validation rules that govern that mempool, including `SAME_SENDER_MEMPOOL_COUNT = 4` for an unstaked sender, do not apply to it. A cap of four pending operations per sender is sized for wallets, not for a submission pipeline. + +Those rules exist so that competing bundlers can safely pack operations from unrelated senders into one bundle. Here, every operation comes from one account that you control, so this threat does not arise. The EntryPoint still enforces everything that protects funds: the signature, per-lane nonce uniqueness, and prefund solvency. ### One bundle, start to finish -Each relayer runs one asynchronous worker. The worker takes a bundle of up to `MAX_OPS_PER_BUNDLE` operations (never two from the same lane), and then works through a fixed sequence. +Each relayer runs one asynchronous worker. The worker takes a bundle of up to `MAX_OPS_PER_BUNDLE` operations (never two from the same lane). It then works through a fixed sequence. -Two rules provide most of the safety: +Most of the safety comes from two rules: + +- **Write-ahead ordering.** The signed outer transaction is written to the journal before it is broadcast. Each journal snapshot is fsynced before it is renamed into place, and the directory is fsynced after the rename. A written record therefore survives a kernel panic or host loss, not only a process crash. On restart, the exact raw bytes are rebroadcast first, so a crash between signing and sending cannot lose or duplicate work. The journal is still one file on one disk, not a replicated database. +- **Same-nonce replacement.** If no receipt arrives within `BUNDLE_RECEIPT_TIMEOUT_MS`, the worker checks earlier attempts for a receipt. It then bumps fees by `REPLACEMENT_FEE_BUMP_PERCENT` and signs a replacement at the same relayer nonce. It never sends nonce `n + 1` while a transaction at `n` might still land, which is the gap this design exists to avoid. -- **Write-ahead ordering.** The signed outer transaction is written to the journal before it is broadcast. Each journal snapshot is fsynced before it is renamed into place, and the directory is fsynced after it, so a written record survives a kernel panic or host loss, not only a process crash. On restart, the exact raw bytes are rebroadcast first, so a crash between signing and sending cannot lose or duplicate work. The journal is still one file on one disk, not a replicated database. -- **Same-nonce replacement.** If no receipt arrives within `BUNDLE_RECEIPT_TIMEOUT_MS`, the worker checks earlier attempts for a receipt, bumps fees by `REPLACEMENT_FEE_BUMP_PERCENT`, and signs a replacement at the same relayer nonce. It never sends nonce `n + 1` while a transaction at `n` might still land, which is the gap this design exists to avoid. +The receipt wait polls every `RECEIPT_POLLING_INTERVAL_MS`, 250 ms by default. Sei produces blocks in well under a second. With viem's 4-second default, most of the timeout passes idle between polls. A bundle that has already landed can also be reported as timed out. This triggers an unnecessary fee-bumped replacement. -The receipt wait polls every `RECEIPT_POLLING_INTERVAL_MS`, 250 ms by default. Sei produces blocks in well under a second. With viem's 4-second default, most of the timeout passes idle between polls, and a bundle that has already landed can be reported as timed out, which triggers an unnecessary fee-bumped replacement. +Two more guards cover the simulation and the journal. The `eth_estimateGas` call passes the relayer's address string as `account`, not the viem `Account` object. Given a local account object, viem prepares a full transaction request before it estimates. That adds a chain ID read, a fee lookup, and an `eth_getTransactionCount(address, "pending")` call. Passing the address skips all three, including the pending-nonce read that this hot path is built to avoid. -Two further guards cover the simulation and the journal. The `eth_estimateGas` call passes the relayer's address string as `account`, not the viem `Account` object. Given a local account object, viem prepares a full transaction request before estimating, which adds a chain ID read, a fee lookup, and an `eth_getTransactionCount(address, "pending")` call; passing the address skips all three, including the pending-nonce read this hot path is built to avoid. A file lock keeps a second process off the same account. The lock identifies its holder by inode rather than by the existence of a file, and the process re-checks that it still holds the lock immediately before it signs and before every journal write, so a process that lost a lock race stops instead of signing. +A file lock keeps a second process off the same account. The lock identifies its holder by inode rather than by the existence of a file. The process re-checks that it still holds the lock immediately before it signs and before every journal write. A process that lost a lock race therefore stops instead of signing. -Before any new work is created, a restarted process reconciles every incomplete journal entry against the EntryPoint. If the chain sequence is ahead of the journal, the operation was consumed. If they match, the lane is reserved and the operation is recovered or requeued. If the chain is behind the journal, the state is inconsistent and the process stops rather than guessing. +Before it creates any new work, a restarted process reconciles every incomplete journal entry against the EntryPoint. If the chain sequence is ahead of the journal, the operation was consumed. If they match, the lane is reserved and the operation is recovered or requeued. If the chain is behind the journal, the state is inconsistent, and the process stops rather than guessing. ### What fails alone and what fails together -The EntryPoint treats an account execution failure as a per-operation result: it emits a failed `UserOperationEvent`, charges gas, advances that lane, and continues with the next operation. A validation failure (bad signature, stale sequence, insufficient prefund) is different: it reverts the whole `handleOps` transaction and nothing in it is consumed. +The EntryPoint treats an account execution failure as a per-operation result. It emits a failed `UserOperationEvent`, charges gas, advances that lane, and continues with the next operation. A validation failure (bad signature, stale sequence, insufficient prefund) is different. It reverts the whole `handleOps` transaction, and nothing in it is consumed. @@ -151,18 +163,18 @@ The EntryPoint treats an account execution failure as a per-operation result: it | Operation validation fails | Not consumed | Entire `handleOps` reverts | Fix the cause and resubmit | | Signed operation never reached a mined bundle | Not consumed | Independent lanes stay valid | The journal requeues it | | Outer transaction times out or is evicted | Unknown until reconciled | Bundle stays intact | Rebroadcast and fee-bump at the same relayer nonce | -| Outer transaction mines and reverts | Not consumed | Nothing in that bundle executes | Relayer nonce is consumed; operations can be requeued | +| Outer transaction mines and reverts | Not consumed | Nothing in that bundle executes | Relayer nonce is consumed, and operations can be requeued | | Process exits after journaling | Determined at restart | No new work starts first | Reconcile receipts, lane sequences, and the relayer nonce | -Every bundle is simulated with `eth_estimateGas` before broadcast, so validation failures are normally caught before any gas is spent. `MAX_OPS_PER_BUNDLE` sets the size of the shared validation domain; keep it small when isolation matters more than amortized cost. +Every bundle is simulated with `eth_estimateGas` before broadcast, so validation failures are normally caught before any gas is spent. `MAX_OPS_PER_BUNDLE` sets the size of the shared validation domain. When isolation matters more than amortized cost, keep it small. ## Why this is hard to replicate -Faster hardware and better RPC routing help every submission strategy. The difference here is structural: one funded address holds many independent operations in flight while keeping the custody surface of a single wallet. +Faster hardware and better RPC routing help every submission strategy. The difference here is structural: one funded address holds many independent operations in flight while it keeps the custody surface of a single wallet. The relevant comparison is a fleet of hot wallets, which is what most teams run. A fleet can match the width. It cannot do so from one balance, one approval set, and one key. -The baseline is not one transaction at a time. A single address can sign and broadcast nonces `n`, `n+1`, `n+2`, and onward and have all of them unresolved, and [the producer mempool admits them](/node/technical-reference#giga-mode-behavior-and-per-block-limits) as long as they arrive in order. The constraint is ordering: the outstanding transactions form one queue, and one that never lands strands every later nonce behind it. +The baseline is not one transaction at a time. A single address can sign and broadcast nonces `n`, `n+1`, `n+2`, and onward, and all of them can be unresolved at the same time. [The producer mempool admits them](/node/technical-reference#giga-mode-behavior-and-per-block-limits) as long as they arrive in order. The constraint is ordering. The outstanding transactions form one queue, and one transaction that never lands strands every later nonce behind it. | | One hot wallet | Fleet of N hot wallets | Public ERC-4337 bundler | Nonce lanes | | --- | --- | --- | --- | --- | @@ -170,23 +182,25 @@ The baseline is not one transaction at a time. A single address can sign and bro | Outer transactions broadcast at once | Many | Many per wallet | Set by the bundler's policy | `RELAYER_COUNT` | | Are those submissions independent? | No: one ordered queue | Only across wallets, ordered within each | Yes | Yes: one sequence per lane | | Balances and approvals to maintain | One address | N addresses, approved N times | One address | One address | -| Keys that can move funds | 1 | N | 1 | 1; relayers hold gas only | +| Keys that can move funds | 1 | N | 1 | 1 (relayers hold gas only) | | Recovering the in-flight set after a crash | Re-derive it from the chain | Re-derive it per wallet | Handled by the bundler | Durable journal and deterministic reconciliation | | Failure blast radius | Everything behind the gap | Everything behind the gap, per wallet | One operation | One lane for execution, one bundle for validation | - Read the first two rows together. `LANE_POOL_SIZE` caps how many operations can be signed and unresolved at once; `RELAYER_COUNT` caps how many outer transactions are broadcast at once. Lanes provide a large pool of independent intents rather than a large number of simultaneous transactions. The approximate per-block submission width is `RELAYER_COUNT × MAX_OPS_PER_BUNDLE`. + Read the first two rows together. `LANE_POOL_SIZE` caps how many operations can be signed and unresolved at once. `RELAYER_COUNT` caps how many outer transactions are broadcast at once. Lanes give a large pool of independent intents, not a large number of simultaneous transactions. The approximate per-block submission width is `RELAYER_COUNT × MAX_OPS_PER_BUNDLE`. -Measured on Sei Testnet against the same venue call, one address with sequential nonces landed 1 operation per second sending serially and 7 per second pipelining one request at a time, and reached 51 per second only by sending all 1,024 transactions in one JSON-RPC batch. A fleet of 8 hot wallets also landed 51 per second. Nonce lanes landed 60 to 64 per second from one address whose EVM nonce never moved, against a block-gas ceiling of about 73 for that call shape. The method, the run shapes, and the caveats are in [Benchmarks](#benchmarks). +On Sei Testnet, with the same venue call in every run, one address with sequential nonces landed 1 operation per second when it sent serially. When it pipelined one request at a time, it landed 7 per second. It reached 51 per second only when it sent all 1,024 transactions in one JSON-RPC batch. + +A fleet of 8 hot wallets also landed 51 per second. Nonce lanes landed 60 to 64 per second from one address whose EVM nonce never moved. For that call shape, the block-gas ceiling was about 73 per second. The method, the run shapes, and the caveats are in [Benchmarks](#benchmarks). Six properties of the design produce those rows: 1. Capital, approvals, and protocol state stay on one address. Width comes from lanes, not from splitting funds. A new lane costs nothing to open and is valid at sequence `0` immediately. 2. The only key that can create a valid operation is the funded account's. Relayer keys can be rotated, replaced, or lost at a cost bounded by their gas balances. -3. After the one-time delegation, the funded account's EVM nonce does not move while submitting. Nothing an RPC drops or a producer rejects can strand the account. -4. The in-process bundling queue removes the ERC-7562 `SAME_SENDER_MEMPOOL_COUNT` limit and the dependency on a third-party bundler's inclusion policy, while every EntryPoint check that protects funds still runs. -5. Signed operations and signed outer transactions are journaled and fsynced before broadcast, replacement reuses the relayer nonce, and restart reconciliation is deterministic: it refuses to create new work when the recorded state is ambiguous. +3. After the one-time delegation, the funded account's EVM nonce does not move during submission. Nothing an RPC drops or a producer rejects can strand the account. +4. The in-process bundling queue removes the ERC-7562 `SAME_SENDER_MEMPOOL_COUNT` limit and the dependency on a third-party bundler's inclusion policy. Every EntryPoint check that protects funds still runs. +5. Signed operations and signed outer transactions are journaled and fsynced before broadcast. Replacement reuses the relayer nonce. Restart reconciliation is deterministic: it refuses to create new work when the recorded state is ambiguous. 6. The signing path performs no nonce reads, so an unreliable pending view costs nothing. Fast blocks and instant finality keep each relayer's receipt wait short, which is what makes `RELAYER_COUNT × MAX_OPS_PER_BUNDLE` a usable per-block width. @@ -194,7 +208,7 @@ Six properties of the design produce those rows: - Block time and gas limits differ between today's [Twin Turbo Consensus](/learn/twin-turbo-consensus) and [Sei Giga](/learn/sei-giga). Size a relayer pool against the network you submit to, and measure rather than assume. + Block time and gas limits differ between today's [Twin Turbo Consensus](/learn/twin-turbo-consensus) and [Sei Giga](/learn/sei-giga). Size a relayer pool for the network that you submit to. Base the size on measurements, not assumptions. ## Tutorial: run the reference implementation @@ -210,7 +224,7 @@ The walkthrough below deploys the demo contracts, delegates a throwaway account, - Clone with submodules so the pinned `account-abstraction`, OpenZeppelin, and `forge-std` dependencies are checked out: + Clone the repository with submodules so that the pinned `account-abstraction`, OpenZeppelin, and `forge-std` dependencies are checked out: ```bash git clone --recurse-submodules https://github.com/sei-protocol/sei-nonce-lanes.git @@ -231,19 +245,27 @@ The walkthrough below deploys the demo contracts, delegates a throwaway account, forge test -vv ``` - The Foundry suite runs against the real EntryPoint v0.8 bytecode from the pinned dependency, placed at the canonical address inside the test VM. It verifies that different lanes can land in any order, that an execution revert affects only its own lane, that an operation that is never submitted blocks nothing, that a gap on one shared lane reproduces sequential blocking, that one validation failure reverts the whole bundle, that lane `0` is rejected, and that a 50-lane bundle fits in one outer transaction. + The Foundry suite runs against the real EntryPoint v0.8 bytecode from the pinned dependency, placed at the canonical address inside the test VM. It verifies these properties: + + - Different lanes can land in any order. + - An execution revert affects only its own lane. + - An operation that is never submitted blocks nothing. + - A gap on one shared lane reproduces sequential blocking. + - One validation failure reverts the whole bundle. + - Lane `0` is rejected. + - A 50-lane bundle fits in one outer transaction. Start with a local Prague fork. It carries Sei Testnet's state, including the deployed EntryPoint, but spends only local funds. - Never use Anvil, Hardhat, tutorial, or shared test mnemonics on Sei Testnet or Sei Mainnet. Their addresses and keys are public, so anyone can move funds sent to them. An address derived from a published mnemonic may also carry an existing EIP-7702 delegation, and a fork inherits that code. The fork below therefore needs a fresh mnemonic too. It also runs as chain `1328`, so an authorization signed against it is replayable on Sei Testnet itself whenever the account's nonce lines up. Regenerate every key and mnemonic before you point a fork's `.env` at a public network. + Never use Anvil, Hardhat, tutorial, or shared test mnemonics on Sei Testnet or Sei Mainnet. Their addresses and keys are public, so anyone can move funds sent to them. An address derived from a published mnemonic may also carry an existing EIP-7702 delegation, and a fork inherits that code. The fork below therefore needs a fresh mnemonic too. It also runs as chain `1328`, so an authorization signed against it is replayable on Sei Testnet itself whenever the account's nonce matches. Regenerate every key and mnemonic before you point a fork's `.env` at a public network. - EIP-7702 requires a Prague-capable node. Generate a mnemonic for the fork to use, and do not fall back to Anvil's default one: + EIP-7702 requires a Prague-capable node. Do not fall back to Anvil's default mnemonic. Generate one for the fork to use: ```bash cast wallet new-mnemonic @@ -259,9 +281,9 @@ The walkthrough below deploys the demo contracts, delegates a throwaway account, --mnemonic "word word word ..." ``` - Anvil funds the first ten accounts of whatever mnemonic you hand it. Using a fresh phrase avoids Anvil's published addresses. Do not use the default mnemonic here: a fork keeps any account code already attached to those public addresses, and every mutating command refuses a relayer that has code. + Anvil funds the first ten accounts of whatever mnemonic you give it. A fresh phrase avoids Anvil's published addresses. Do not use the default mnemonic here. A fork keeps any account code that is already attached to those public addresses, and every mutating command refuses a relayer that has code. - The repository compiles its contracts for Cancun because they use no Prague-only opcodes, but the local node must run Prague to accept the type-4 delegation transaction. + The repository compiles its contracts for Cancun because they use no Prague-only opcodes. However, the local node must run Prague to accept the type-4 delegation transaction. Create the configuration and point it at the fork: @@ -277,9 +299,9 @@ The walkthrough below deploys the demo contracts, delegates a throwaway account, RELAYER_START_INDEX=1 ``` - Set `TRADER_PRIVATE_KEY` to account `0`'s private key from the Anvil startup output, and `RELAYER_MNEMONIC` to the phrase you just generated. Starting relayers at index `1` keeps the funded account and relayer identities distinct; the application rejects overlapping identities. + Set `TRADER_PRIVATE_KEY` to account `0`'s private key from the Anvil startup output. Set `RELAYER_MNEMONIC` to the phrase that you generated. Starting relayers at index `1` keeps the funded account and relayer identities distinct. The application rejects overlapping identities. - Anvil prints that key in the clear and it lands in `.env`, so treat the phrase as throwaway and keep this `.env` pointed at `127.0.0.1`. + Anvil prints that key in the clear, and you store it in `.env`. Treat the phrase as throwaway, and keep this `.env` pointed at `127.0.0.1`. Deploy the demo contracts from the repository root. Anvil unlocks its own accounts, so pass account `0`'s address from its startup output as the sender: @@ -299,7 +321,7 @@ The walkthrough below deploys the demo contracts, delegates a throwaway account, cast wallet new-mnemonic # relayer mnemonic ``` - Fund the address from the [Sei faucet](/learn/faucet), then configure: + Fund the address from the [Sei faucet](/learn/faucet). Then create the configuration: ```bash cp .env.example .env @@ -324,7 +346,7 @@ The walkthrough below deploys the demo contracts, delegates a throwaway account, --interactives 1 ``` - `--interactives 1` prompts for the key and does not echo it, so it never reaches your shell history, the process table, or an environment variable. + `--interactives 1` prompts for the key and does not echo it. The key therefore never reaches your shell history, the process table, or an environment variable. @@ -336,7 +358,7 @@ The walkthrough below deploys the demo contracts, delegates a throwaway account, ``` - Mutating commands refuse to write to a remote Sei Mainnet RPC unless `ALLOW_MAINNET=1` is set explicitly. They also refuse remote writes when `TRADER_PRIVATE_KEY` is Anvil account `0` or `RELAYER_MNEMONIC` is the default Anvil mnemonic. The fresh mnemonic above does not trigger that credential guard. Keep its `.env` pointed at `127.0.0.1`; if you point it at Sei Testnet, chain ID `1328` is still valid and the application cannot know the change was accidental. These guards do not cover the separate Forge deployment command, and they do not make the demo production-ready. + Mutating commands refuse to write to a remote Sei Mainnet RPC unless you set `ALLOW_MAINNET=1` explicitly. They also refuse remote writes when `TRADER_PRIVATE_KEY` is Anvil account `0` or `RELAYER_MNEMONIC` is the default Anvil mnemonic. The fresh mnemonic above does not trigger that credential guard. Keep its `.env` pointed at `127.0.0.1`. If you point it at Sei Testnet, chain ID `1328` is still valid, and the application cannot know that the change was accidental. These guards do not cover the separate Forge deployment command, and they do not make the demo production-ready. @@ -350,7 +372,7 @@ The walkthrough below deploys the demo contracts, delegates a throwaway account, It prints the chain ID and whether there is code at the EntryPoint address `0x4337084D9E255Ff0702461CF8895CE9E3b5Ff108`. It also reports the account's current delegation, balances, its EntryPoint deposit, each relayer's confirmed nonce and gas balance, the lane sequences, and the venue state. - Against current Sei Testnet or Sei Mainnet state, the EntryPoint line reads `present` because the singleton is deployed on both. On a local fork or against a misconfigured endpoint, the check catches missing fork state or the wrong network. The relayer lines are worth a second look: any `HAS CODE/DELEGATION` marker means the mutating commands will refuse that relayer. + Against current Sei Testnet or Sei Mainnet state, the EntryPoint line reads `present` because the singleton is deployed on both. On a local fork or against a misconfigured endpoint, the check catches missing fork state or the wrong network. Check the relayer lines carefully. Any `HAS CODE/DELEGATION` marker means that the mutating commands refuse that relayer. @@ -358,9 +380,11 @@ The walkthrough below deploys the demo contracts, delegates a throwaway account, npm run delegate ``` - This sends one type-4 transaction with an authorization for `LANE_ACCOUNT_IMPL`, signed and paid for by the account itself, so the account's EVM nonce advances by two: once for the transaction, once for the authorization. The command reads the account's confirmed nonce once and pins both the transaction nonce and the authorization nonce (`nonce + 1`) to that read, instead of letting the client fill them from a pending-nonce lookup. That matters because a wrong authorization nonce is not rejected: the EVM skips the authorization, the transaction still succeeds, and nothing is installed. The command therefore re-reads the designator after the receipt and fails if the delegation did not take effect. + This sends one type-4 transaction with an authorization for `LANE_ACCOUNT_IMPL`, and the account itself signs and pays for it. The account's EVM nonce therefore advances by two: once for the transaction, and once for the authorization. + + The command reads the account's confirmed nonce once. It pins both the transaction nonce and the authorization nonce (`nonce + 1`) to that read. It does not let the client fill them from a pending-nonce lookup. This matters because the EVM does not reject a wrong authorization nonce. It skips the authorization, the transaction still succeeds, and nothing is installed. The command therefore re-reads the designator after the receipt and fails if the delegation did not take effect. - The command is idempotent: if the account already delegates to the configured implementation, it does nothing. If the account delegates to something else, it tells you before replacing it. + The command is idempotent: if the account already delegates to the configured implementation, it does nothing. If the account delegates to something else, the command tells you before it replaces that delegation. @@ -369,7 +393,7 @@ The walkthrough below deploys the demo contracts, delegates a throwaway account, npm run status ``` - `fund` uses ordinary transactions to top each relayer up to `RELAYER_FUNDING` SEI and to bring the account's `EntryPoint.depositTo` balance up to `ENTRYPOINT_DEPOSIT` SEI. The deposit is what the EntryPoint draws prefund from when it validates each operation. On a public network you can instead send SEI to relayer `0` and run `npm run dispense`, which waits for the balance and splits it across the pool. Use one bootstrapping path or the other, not both. + `fund` uses ordinary transactions to top each relayer up to `RELAYER_FUNDING` SEI and to bring the account's `EntryPoint.depositTo` balance up to `ENTRYPOINT_DEPOSIT` SEI. When the EntryPoint validates each operation, it draws prefund from this deposit. On a public network, you can instead send SEI to relayer `0` and run `npm run dispense`. That command waits for the balance and splits it across the pool. Use one bootstrapping path or the other, not both. @@ -377,13 +401,13 @@ The walkthrough below deploys the demo contracts, delegates a throwaway account, npm run submit ``` - One `submit` process performs the complete run and exits. It runs the preflight, estimates the delegated call's gas, reads each lane's sequence once, signs 24 operations concurrently with no nonce RPCs, journals them, bundles them, drains the bundles through the relayer pool, and prints a report. By default, order `2` receives a limit price below the mark, so its operation reverts during execution while the neighboring lanes continue. + One `submit` process performs the complete run and exits. It runs the preflight, estimates the delegated call's gas, and reads each lane's sequence once. It then signs 24 operations concurrently with no nonce RPCs, journals them, and bundles them. Finally, it drains the bundles through the relayer pool and prints a report. By default, order `2` receives a limit price below the mark, so its operation reverts during execution while the neighboring lanes continue. ### Read the report -The output below is illustrative; your addresses, blocks, and timings will differ. +The output below is illustrative. Your addresses, blocks, and timings will differ. ```text === preflight === @@ -438,19 +462,19 @@ trader EVM nonce 9 -> 9 UNCHANGED total wall time 4210ms ``` -What to look for: +Look for these items: - **`trader nonce` before and `trader EVM nonce` after** must be identical. The tool calls the funded account the trader. Its key never entered a queue. -- **`call gas`** is the measured delegated-call estimate plus 25 percent. A `CALL_GAS_LIMIT floor` appears in that line only when you set one; leave it unset unless you have a reason, because the EntryPoint reserves the declared limit before running each operation. +- **`call gas`** is the measured delegated-call estimate plus 25 percent. A `CALL_GAS_LIMIT floor` appears in that line only when you set one. Leave it unset unless you have a reason, because the EntryPoint reserves the declared limit before it runs each operation. - **`exec`** combines the bundle receipt with the venue's `isFilled` read. `reverted` means the outer transaction landed, so the operation consumed its lane sequence, but the call failed inside the venue. `not mined` would mean the outer transaction never landed and nothing was consumed. -- **`land#`** is the venue's global landing counter. It shows the order in which operations actually executed, which has nothing to do with lane number. Lane acquisition is last-in, first-out, so a fresh 32-lane pool starts at lane `32`; lane numbers carry no priority. +- **`land#`** is the venue's global landing counter. It shows the order in which operations executed, which has nothing to do with lane number. Lane acquisition is last-in, first-out, so a fresh 32-lane pool starts at lane `32`. Lane numbers carry no priority. - **`hash check`** confirms that the locally computed EIP-712 digest matches `EntryPoint.getUserOpHash` for the first operation, so client-side hashing matches consensus. -If a bundle is reported as `PENDING` or `FAILED`, the command exits non-zero and leaves the journal intact. Run `npm run submit` again once the RPC can answer receipt and nonce queries; the process recovers or replaces at the same relayer nonce before it creates new work. Do not delete the journal and do not send the relayer's next nonce by hand. +If a bundle is reported as `PENDING` or `FAILED`, the command exits non-zero and leaves the journal intact. When the RPC can answer receipt and nonce queries, run `npm run submit` again. Before it creates new work, the process recovers or replaces the bundle at the same relayer nonce. Do not delete the journal. Do not send the relayer's next nonce by hand. ### Optional: real swaps on Sei Testnet -The repository includes a real-target path that routes tiny native SEI and native USDC swaps through the documented DragonSwap V1 deployment on Sei Testnet. It is hard-blocked on every other chain. Get testnet USDC from the [Circle faucet](https://faucet.circle.com/), then: +The repository includes a real-target path that routes tiny native SEI and native USDC swaps through the documented DragonSwap V1 deployment on Sei Testnet. It is hard-blocked on every other chain. Get testnet USDC from the [Circle faucet](https://faucet.circle.com/). Then run these commands: ```bash # from the app directory, where the walkthrough left off @@ -458,7 +482,7 @@ npm run swap:setup npm run swap:submit ``` -`swap:setup` uses ordinary transactions to approve a limited amount of USDC and to create and seed the WSEI/USDC pair if the factory has no live pair. `swap:submit` alternates SEI to USDC and USDC to SEI swaps through independent lanes and reports outcomes from EntryPoint events rather than one RPC read per swap. The same knobs apply: +`swap:setup` uses ordinary transactions to approve a limited amount of USDC. If the factory has no live pair, it also creates and seeds the WSEI/USDC pair. `swap:submit` alternates SEI to USDC and USDC to SEI swaps through independent lanes. It reports outcomes from EntryPoint events rather than one RPC read per swap. The same knobs apply: ```bash ORDERS=3000 \ @@ -468,7 +492,7 @@ REVERT_ORDER_INDEX=2 \ npm run swap:submit ``` -The account must hold enough of both assets for every input-side swap to execute regardless of landing order. Set `REVERT_ORDER_INDEX=-1` when you want to measure maximum throughput. +The account must hold enough of both assets for every input-side swap to execute, regardless of landing order. To measure maximum throughput, set `REVERT_ORDER_INDEX=-1`. ### Optional: see the baseline you are escaping @@ -477,46 +501,52 @@ The account must hold enough of both assets for every input-side swap to execute npm run baseline ``` -Using a gas-only relayer key so nothing of value is at risk, `baseline` measures the constraint directly. It sends nonce `n + 1` while deliberately skipping `n`, waits to see whether that transaction can be included above a gap, fills the gap with nonce `n`, then checks whether the skipped-ahead transaction lands once the gap is closed. The verdict is one of four outcomes: +`baseline` measures the constraint directly. It uses a gas-only relayer key, so nothing of value is at risk. The probe deliberately sends nonce `n + 1` without nonce `n`, and waits to see whether that transaction can be included above a gap. Next, it fills the gap with nonce `n` and checks whether the skipped-ahead transaction lands after the gap is closed. The verdict is one of four outcomes: | Verdict | What the RPC path did | What happened to the out-of-order transaction | | --- | --- | --- | | `REJECTED at admission` | Refused the gapped nonce, typically with `bad nonce` | Refused synchronously, so the sender learns at once and no gap forms on this path | -| `ADMITTED then dropped` | Returned a hash, then discarded the transaction | Lost without an error; it did not land even after the gap was filled | +| `ADMITTED then dropped` | Returned a hash, then discarded the transaction | Lost without an error, and did not land even after the gap was filled | | `QUEUED, then included once the gap filled` | Held it and released it in nonce order | Waited, then landed after nonce `n` arrived | -| `ACCEPTED and included above a gap` | Included it out of order | Landed before nonce `n`; this path does not enforce nonce order | +| `ACCEPTED and included above a gap` | Included it out of order | Landed before nonce `n`, which means this path does not enforce nonce order | -The probe measures gap handling only. How many consecutive nonces one sender can have outstanding is a separate question, answered in [Why this is hard to replicate](#why-this-is-hard-to-replicate): many, as long as they arrive in order. +The probe measures gap handling only. How many consecutive nonces one sender can have outstanding is a separate question. [Why this is hard to replicate](#why-this-is-hard-to-replicate) answers it: many, as long as they arrive in order. -The probe samples both the `latest` and `pending` nonce tags before, during, and after, and prints any rejection message verbatim, because the exact message is the finding. If the two tags already disagree before the probe starts, it warns you: either the account has work in flight or the node reports a mempool-derived pending nonce, and in both cases the gap it is about to create may not be a gap at all, so the verdict cannot be attributed to nonce ordering. Compare the result with a `submit` run, where 24 operations from one account are mutually independent and one failure strands nothing. +The probe samples both the `latest` and `pending` nonce tags before, during, and after the run. It prints any rejection message verbatim, because the exact message is the finding. If the two tags already disagree before the probe starts, it warns you. The disagreement means that either the account has work in flight, or the node reports a mempool-derived pending nonce. In both cases, the gap that the probe is about to create may not be a gap at all. You therefore cannot attribute the verdict to nonce ordering. -The verdict depends on the path. In one session, two Sei Testnet RPC endpoints answered differently: a dedicated provider queued the gapped transaction and released it once the gap filled, while the public endpoint returned a hash and then dropped it, so it never landed even after the gap was filled. Neither rejected it at admission. Probe the path you will actually use. +Compare the result with a `submit` run. There, 24 operations from one account are mutually independent, and one failure strands nothing. + +The verdict depends on the path. In one session, two Sei Testnet RPC endpoints answered differently. A dedicated provider queued the gapped transaction and released it after the gap filled. The public endpoint returned a hash and then dropped the transaction, so it never landed, even after the gap was filled. Neither endpoint rejected it at admission. Probe the path that you will use. ## Tuning -Three knobs shape a run. They interact, so change one at a time and measure. +Three knobs shape a run. They interact, so change one at a time and measure the result. - One lane holds at most one in-flight operation, so `LANE_POOL_SIZE` is the hard ceiling on unresolved UserOperations in a process. Larger pools permit more concurrently unresolved intents, add startup `getNonce` reads (batched with bounded concurrency so a public RPC does not rate-limit you), and increase the recovery state you must understand after a failure. `ORDERS` must not exceed `LANE_POOL_SIZE`; the application rejects that configuration instead of silently submitting fewer operations. + One lane holds at most one in-flight operation, so `LANE_POOL_SIZE` is the hard ceiling on unresolved UserOperations in a process. Larger pools permit more concurrently unresolved intents. They also add startup `getNonce` reads and increase the recovery state that you must understand after a failure. The startup reads are batched with bounded concurrency so that a public RPC does not rate-limit you. `ORDERS` must not exceed `LANE_POOL_SIZE`. The application rejects that configuration instead of silently submitting fewer operations. - `MAX_OPS_PER_BUNDLE` trades amortized outer-transaction overhead for the size of the shared validation failure domain. A width of `1` gives maximum isolation and the highest overhead. Execution reverts stay per-operation at any width. The relayer caps signed transaction gas below the block gas limit it read at startup and rejects a bundle whose estimate cannot fit. + `MAX_OPS_PER_BUNDLE` trades amortized outer-transaction overhead for the size of the shared validation failure domain. A width of `1` gives maximum isolation and the highest overhead. Execution reverts stay per-operation at any width. The relayer caps signed transaction gas below the block gas limit that it read at startup. It rejects a bundle whose estimate cannot fit. + + A bundle does not need the sum of its operations' declared call gas. Before each operation, the EntryPoint checks that enough gas remains to honor that operation's `callGasLimit`. Whatever an operation leaves unspent passes to the next one. The outer transaction therefore needs the gas that the bundle consumes, plus about one operation's declared limit in reserve. + + Over-declaring still has a cost. EntryPoint v0.8 charges 10 percent of unused call gas beyond a 40,000-gas threshold. Each operation also reserves prefund from the deposit against its declared limits, not its measured cost. An inflated limit therefore ties up deposit that is refunded only afterwards. - A bundle does not need the sum of its operations' declared call gas. The EntryPoint checks before each operation that enough gas remains to honor that operation's `callGasLimit`, and whatever an operation leaves unspent passes to the next one, so the outer transaction needs the gas the bundle actually consumes plus about one operation's declared limit in reserve. Over-declaring still has a cost: v0.8 charges 10 percent of unused call gas beyond a 40,000-gas threshold, and each operation reserves prefund from the deposit against its declared limits rather than its measured cost, so an inflated limit ties up deposit that is only refunded afterwards. + That is why `CALL_GAS_LIMIT` is unset by default. Both submit paths measure the real call gas for the chain and call shape, and add 25 percent. The variable is only a floor, and it has an effect only when you set it above that measurement. Because the EntryPoint reserves each operation's declared call gas before it runs the operation, a floor above the measurement costs block gas. It therefore costs operations per block, but it does not change the gas that the operations use. - That is why `CALL_GAS_LIMIT` is unset by default. Both submit paths measure the real call gas for the chain and call shape and add 25 percent; the variable is only a floor, and it has an effect only when you set it above that measurement. Because the EntryPoint reserves each operation's declared call gas before running it, a floor above the measurement costs block gas, and therefore operations per block, without changing the gas actually used. + As a reference point, the real-swap path sustained 77 operations per bundle on Sei Testnet with `CALL_GAS_LIMIT=500000`. That value was the default in an earlier revision of the repository. A bundle of 78 no longer fit the 12,500,000 block gas limit in effect during that run. It failed safely during simulation. Width 76 produced the best observed submission rate for that call shape: 47.7 landed swaps per second. These are measurements for one call shape, one configuration, and one network state, not protocol limits. - As a reference point, on Sei Testnet with `CALL_GAS_LIMIT=500000`, the default in an earlier revision of the repository, the real-swap path sustained 77 operations per bundle; 78 no longer fit the 12,500,000 block gas limit in effect during that run and failed safely during simulation. Width 76 produced the best observed submission rate for that call shape, 47.7 landed swaps per second. These are measurements for one call shape, one configuration, and one network state, not protocol limits. + The mock venue is a heavier call. In the [benchmark session](#benchmarks), with `CALL_GAS_LIMIT` unset, each `place` operation used about 331,000 gas of outer transaction gas. The widest bundle that fit was therefore 36 operations, and a bundle of 37 failed safely in simulation. Widths 8, 16, and 36 packed 4, 2, and 1 bundles into a 12,500,000-gas block. Width 9, which should fit 4, landed 3. - The mock venue is a heavier call. In the [benchmark session](#benchmarks), with `CALL_GAS_LIMIT` unset, each `place` operation used about 331,000 gas of outer transaction gas, so 36 operations was the widest bundle that fit and 37 failed safely in simulation. Widths 8, 16, and 36 packed 4, 2, and 1 bundles into a 12,500,000-gas block; width 9, which should fit 4, landed 3. Wide bundles also queue behind each other, because only one 11,700,000-gas bundle fits a block. With more than about 8 relayers at width 32 or 36, receipt waits exceed the default `BUNDLE_RECEIPT_TIMEOUT_MS`; raise the timeout for those shapes instead of paying for fee-bumped replacements of bundles that land anyway. + Wide bundles also queue behind each other, because only one 11,700,000-gas bundle fits a block. With more than about 8 relayers at width 32 or 36, receipt waits exceed the default `BUNDLE_RECEIPT_TIMEOUT_MS`. For those shapes, raise the timeout instead of paying for fee-bumped replacements of bundles that land anyway. - Each relayer has one sequential outer transaction stream. Under favorable admission and inclusion conditions, the immediate submission width is roughly `RELAYER_COUNT × MAX_OPS_PER_BUNDLE` per block. That is a planning heuristic, not a throughput guarantee: RPC latency, block limits, state contention, gas, and producer policy still apply. Public RPC endpoints have [rate limits](/evm/networks); use a [dedicated provider](/learn/rpc-providers) or your own node for anything beyond a demo. + Each relayer has one sequential outer transaction stream. Under favorable admission and inclusion conditions, the immediate submission width is roughly `RELAYER_COUNT × MAX_OPS_PER_BUNDLE` per block. That is a planning heuristic, not a throughput guarantee. RPC latency, block limits, state contention, gas, and producer policy still apply. Public RPC endpoints have [rate limits](/evm/networks). For anything beyond a demo, use a [dedicated provider](/learn/rpc-providers) or your own node. - One relayer's bundle cycle is five sequential RPC round trips (gas estimate, fee estimate, block number, broadcast, receipt poll) plus inclusion, about 1.5 seconds on a 120 ms endpoint. Below roughly 120 operations in flight the pool is the bottleneck and throughput scales with `RELAYER_COUNT`; above that, block gas is. + One relayer's bundle cycle is five sequential RPC round trips (gas estimate, fee estimate, block number, broadcast, receipt poll) plus inclusion. On a 120 ms endpoint, that takes about 1.5 seconds. Below roughly 120 operations in flight, the pool is the bottleneck, and throughput scales with `RELAYER_COUNT`. Above that, block gas is the bottleneck. - In the [benchmark session](#benchmarks), the bundle-width sweep with 4 relayers produced client-side rates of 2.7, 8.9, 15.3, 24.3, 45.4, and 50.5 operations per second at widths 1, 4, 8, 16, 32, and 36. Its chain-side rates were 3.2, 9.8, 17.1, 28.4, 51.2, and 56.9. At width 4, the relayer-count sweep produced client-side rates of 2.2, 8.9, 15.4, 27.9, and 47.2 operations per second with 1, 4, 8, 16, and 32 relayers. Its chain-side rates were 2.7, 9.8, 17.1, 32.0, and 51.2. + In the [benchmark session](#benchmarks), the bundle-width sweep used 4 relayers and widths of 1, 4, 8, 16, 32, and 36. Its client-side rates were 2.7, 8.9, 15.3, 24.3, 45.4, and 50.5 operations per second. Its chain-side rates were 3.2, 9.8, 17.1, 28.4, 51.2, and 56.9. At width 4, the relayer-count sweep used 1, 4, 8, 16, and 32 relayers. Its client-side rates were 2.2, 8.9, 15.4, 27.9, and 47.2 operations per second. Its chain-side rates were 2.7, 9.8, 17.1, 32.0, and 51.2. @@ -524,28 +554,28 @@ Three knobs shape a run. They interact, so change one at a time and measure. ### Configuration reference -The application always loads `.env` from the repository root. The variables you are most likely to change: +The application always loads `.env` from the repository root. These are the variables that you are most likely to change: | Variable | Default | Meaning | | --- | --- | --- | | `SEI_CHAIN_ID` | `1328` | `1328` (Sei Testnet) or `1329` (Sei Mainnet) | -| `SEI_RPC_URL` | viem chain default | HTTP endpoint; its reported chain ID must match before any write | +| `SEI_RPC_URL` | viem chain default | HTTP endpoint. Its reported chain ID must match before any write | | `ALLOW_MAINNET` | `0` | Must be `1` for writes to a remote Sei Mainnet RPC | | `TRADER_PRIVATE_KEY` | required | The funded account that signs every UserOperation | | `RELAYER_MNEMONIC` | required | Fresh BIP-39 mnemonic used only for gas-paying relayers | | `RELAYER_COUNT` | `4` | Relayer workers, `1..256` | -| `RELAYER_START_INDEX` | `0` | First derivation index; offset it if the mnemonic also holds the funded account | +| `RELAYER_START_INDEX` | `0` | First derivation index. Offset it if the mnemonic also holds the funded account | | `RELAYER_FUNDING` | `0.5` | Target SEI balance per relayer for `fund` | | `ENTRYPOINT_DEPOSIT` | `1` | Target deposit in the EntryPoint for `fund` | -| `LANE_ACCOUNT_IMPL` | unset | Deployed `LaneAccount`; required by `delegate` and `submit` | -| `VENUE` | unset | Deployed demo target; required by `submit` | -| `ORDERS` | `24` | Operations per run; must not exceed `LANE_POOL_SIZE` | +| `LANE_ACCOUNT_IMPL` | unset | Deployed `LaneAccount`, required by `delegate` and `submit` | +| `VENUE` | unset | Deployed demo target, required by `submit` | +| `ORDERS` | `24` | Operations per run (must not exceed `LANE_POOL_SIZE`) | | `LANE_POOL_SIZE` | `32` | `1..4096` lanes and the in-flight ceiling | | `MAX_OPS_PER_BUNDLE` | `4` | `1..LANE_POOL_SIZE` operations sharing one validation domain | -| `REVERT_ORDER_INDEX` | `2` | Order that receives an unfillable limit price; `-1` disables | -| `CALL_GAS_LIMIT` | unset | Optional floor for each operation's declared call gas; when unset, the live estimate plus 25 percent is used | +| `REVERT_ORDER_INDEX` | `2` | Order that receives an unfillable limit price (`-1` disables it) | +| `CALL_GAS_LIMIT` | unset | Optional floor for each operation's declared call gas. When it is unset, the application uses the live estimate plus 25 percent | | `BUNDLE_RECEIPT_TIMEOUT_MS` | `12000` | Receipt wait before same-nonce replacement | -| `RECEIPT_POLLING_INTERVAL_MS` | `250` | Receipt poll interval, `10..60000`; viem's own default is `4000` | +| `RECEIPT_POLLING_INTERVAL_MS` | `250` | Receipt poll interval, `10..60000` (viem's own default is `4000`) | | `BUNDLE_MAX_ATTEMPTS` | `3` | Same-nonce attempts per process invocation | | `REPLACEMENT_FEE_BUMP_PERCENT` | `25` | Fee increase per replacement, `10..1000` | | `OPERATION_JOURNAL_PATH` | `app/.state/pending-ops.json` | Durable signed-operation journal | @@ -554,7 +584,7 @@ The [repository README](https://github.com/sei-protocol/sei-nonce-lanes#configur ## Benchmarks -`app/bench/` measures the lane path against the baseline it replaces: one EOA sending ordinary transactions with sequential nonces. Every mode calls the same `MockPerpVenue.place` on the configured `VENUE`, so the numbers differ only in how the calls were submitted. The commands read the root `.env`, and the shell environment overrides it: +`app/bench/` measures the lane path against the baseline it replaces: one EOA that sends ordinary transactions with sequential nonces. Every mode calls the same `MockPerpVenue.place` on the configured `VENUE`, so the numbers differ only in how the calls were submitted. The commands read the root `.env`, and the shell environment overrides it: ```bash cd app @@ -579,13 +609,15 @@ REPORT_FROM_BLOCK= REPORT_TO_BLOCK= npm run bench:repor npm run bench:latency ``` -The `bench:baseline` modes are the ways one address can drive a sequential queue. `serial` sends one transaction and waits for its receipt before the next. `pipelined` signs everything up front and broadcasts in nonce order without waiting. `pipelined-gap` does the same but never broadcasts the transaction at `BENCH_GAP_INDEX`, then repairs the gap. `batch` sends everything in one JSON-RPC batch request. `fleet` derives `BENCH_FLEET_SIZE` wallets from `RELAYER_MNEMONIC`, funds them from the account, and runs `pipelined` on each at once. +The `bench:baseline` modes are the ways one address can drive a sequential queue. `serial` sends one transaction and waits for its receipt before the next. `pipelined` signs everything up front and broadcasts in nonce order without waiting. `pipelined-gap` does the same but never broadcasts the transaction at `BENCH_GAP_INDEX`. It then repairs the gap. `batch` sends everything in one JSON-RPC batch request. `fleet` derives `BENCH_FLEET_SIZE` wallets from `RELAYER_MNEMONIC`, funds them from the account, and runs `pipelined` on each at once. -`bench:lanes` shares the account-wide run lock with `submit` and `swap:submit` but keeps its own journal under `app/.state/bench/`, so a benchmark never replays the tutorial's pending operations. If a `submit` run was interrupted, recover it with `npm run submit` first. The remaining `BENCH_*` and `REPORT_*` knobs are documented in the [repository README](https://github.com/sei-protocol/sei-nonce-lanes#benchmarks). +`bench:lanes` shares the account-wide run lock with `submit` and `swap:submit`. However, it keeps its own journal under `app/.state/bench/`, so a benchmark never replays the tutorial's pending operations. If a `submit` run was interrupted, recover it with `npm run submit` first. The [repository README](https://github.com/sei-protocol/sei-nonce-lanes#benchmarks) documents the remaining `BENCH_*` and `REPORT_*` knobs. ### Measured against the alternatives -Every row below comes from one measurement session on Sei Testnet. Conditions during the session: block gas limit 12,500,000; base fee 50 gwei plus a 1 gwei tip; about 2.0 blocks per second under load; 120 ms warm request latency to the configured endpoint. Each direct `place` transaction used 328,425 gas and each lane operation about 331,000 gas of outer transaction gas, so the block admits 36 to 38 operations however they are submitted: roughly 73 landed operations per second for this call shape. Chain-side rates divide landed operations by the block-timestamp span, which Sei stamps in whole seconds. Client-side rates divide by wall time from first broadcast to last receipt. +Every row below comes from one measurement session on Sei Testnet. During the session, the block gas limit was 12,500,000, and the base fee was 50 gwei plus a 1 gwei tip. The network produced about 2.0 blocks per second under load, and warm request latency to the configured endpoint was 120 ms. + +Each direct `place` transaction used 328,425 gas, and each lane operation used about 331,000 gas of outer transaction gas. The block therefore admits 36 to 38 operations, regardless of how they are submitted. For this call shape, that is roughly 73 landed operations per second. Chain-side rates divide landed operations by the block-timestamp span, which Sei stamps in whole seconds. Client-side rates divide by wall time from first broadcast to last receipt. @@ -603,20 +635,20 @@ Every row below comes from one measurement session on Sei Testnet. Conditions du -What the numbers show: +The numbers show four things: -- Block gas, not the nonce model, set the ceiling. Lanes came closest to it, with 28 of 31 blocks at least 90 percent full in the 16 × 36 run, from one address whose EVM nonce never moved. A single ordered queue matched the fleet only when every transaction left in one JSON-RPC batch; one request at a time, it is bounded by the round trip, about 7 per second. -- Small relayer pools are client-bound. Throughput scales with `RELAYER_COUNT` until roughly 120 operations are in flight, then block gas takes over. The relayer and width series are in [Tuning](#tuning). -- A gap costs the whole queue. One lost transaction in the sequential queue (`pipelined-gap`, nonce 50 of 100) left the 49 transactions behind it accepted but unmined until the client resent it 15 seconds later. In the lane runs, the deliberately reverting order consumed only its own lane while the rest of its bundle landed. +- Block gas, not the nonce model, set the ceiling. Lanes came closest to that ceiling, and they did so from one address whose EVM nonce never moved. In the 16 × 36 run, 28 of 31 blocks were at least 90 percent full. A single ordered queue matched the fleet only when every transaction left in one JSON-RPC batch. With one request at a time, the round trip bounds it to about 7 per second. +- Small relayer pools are client-bound. Throughput scales with `RELAYER_COUNT` until roughly 120 operations are in flight. After that, block gas is the limit. The relayer and width series are in [Tuning](#tuning). +- A gap costs the whole queue. One transaction was lost in the sequential queue (`pipelined-gap`, nonce 50 of 100). The 49 transactions behind it stayed accepted but unmined until the client resent the lost transaction 15 seconds later. In the lane runs, the deliberately reverting order consumed only its own lane while the rest of its bundle landed. - RPC paths differ. `npm run baseline` gave [two different verdicts](#optional-see-the-baseline-you-are-escaping) for two Sei Testnet endpoints in the same session. - These are measurements of one call shape, one network state, and one client machine, not protocol limits. Cost was about 0.02 SEI per landed operation at the effective 52 gwei. Rerun the benchmarks against the network and endpoint you will actually use; block time and gas limits differ between [Twin Turbo Consensus](/learn/twin-turbo-consensus) and [Sei Giga](/learn/sei-giga). The raw records under `app/.state/bench/` include a journal for `bench:lanes`, which you should treat like `pending-ops.json`. + These are measurements of one call shape, one network state, and one client machine, not protocol limits. The cost was about 0.02 SEI per landed operation at the effective 52 gwei. Rerun the benchmarks against the network and endpoint that you will use. Block time and gas limits differ between [Twin Turbo Consensus](/learn/twin-turbo-consensus) and [Sei Giga](/learn/sei-giga). The raw records under `app/.state/bench/` include a journal for `bench:lanes`. Treat it like `pending-ops.json`. ## Adapting it to your contract -The demo's `MockPerpVenue` is a stand-in that reverts on slippage so a failure is observable. Swapping it for a real target means encoding a different call. `LaneAccount.execute(target, value, data)` forwards any call, and the target sees the funded EOA as `msg.sender`: +The demo's `MockPerpVenue` is a stand-in that reverts on slippage so that you can observe a failure. To replace it with a real target, encode a different call. `LaneAccount.execute(target, value, data)` forwards any call, and the target sees the funded EOA as `msg.sender`: ```ts import { encodeFunctionData } from 'viem'; @@ -658,34 +690,34 @@ bundlingQueue.add({ }); ``` -The real-swap path in `app/src/swap-submit.ts` is a complete example of this against a live router, including forwarding native SEI as `value`. +The real-swap path in `app/src/swap-submit.ts` is a complete example of this against a live router. It also forwards native SEI as `value`. Check these before you trust a new target: - **`msg.sender` and `tx.origin`.** At the target, `msg.sender` is the funded EOA and `tx.origin` is the gas-paying relayer. Contracts that require `tx.origin == msg.sender` are incompatible. Audit each router, approval path, callback, reentrancy assumption, and authorization rule. -- **Gas on Sei.** Storage writes cost materially more than on Ethereum. The application estimates the delegated call live and declares that estimate plus 25 percent, raised to `CALL_GAS_LIMIT` only when you set that floor higher. Do not copy Ethereum-sized static limits in either direction: too low runs out of gas, and too high reserves block gas your operations never use. See [Gas and fees](/evm/evm-parity/gas-and-fees). -- **Storage contention.** Lanes remove submission ordering, not execution conflicts. Analyze which storage slots your calls touch; see [Optimizing for parallelization](/evm/best-practices/optimizing-for-parallelization). -- **Lane policy.** One lane per in-flight intent is the simplest correct policy. If some calls must stay ordered relative to each other, put them on one lane (or on `ADMIN_LANE`) rather than falling back to lane `0`. +- **Gas on Sei.** Storage writes cost materially more than on Ethereum. The application estimates the delegated call live and declares that estimate plus 25 percent. It raises the value to `CALL_GAS_LIMIT` only when you set that floor higher. Do not copy Ethereum-sized static limits in either direction. A limit that is too low runs out of gas, and a limit that is too high reserves block gas that your operations never use. See [Gas and fees](/evm/evm-parity/gas-and-fees). +- **Storage contention.** Lanes remove submission ordering, not execution conflicts. Analyze which storage slots your calls touch. See [Optimizing for parallelization](/evm/best-practices/optimizing-for-parallelization). +- **Lane policy.** One lane per in-flight intent is the simplest correct policy. If some calls must stay ordered relative to each other, put them on one lane (or on `ADMIN_LANE`). Do not fall back to lane `0`. ### Before you adapt this The repository is explicit about what it leaves out. Before this design touches real funds, add at least: -- audited account and integration contracts; -- hardware-backed or remote signing; -- a real risk engine with an idempotent intent model; -- durable, replicated queue and reconciliation storage; -- metrics, tracing, alerting, and structured logs; -- controlled deployment and delegation procedures; -- RPC redundancy and chain-specific fee policy; -- graceful shutdown and operator runbooks; and -- load, fault-injection, and live-chain recovery testing. +- Audited account and integration contracts +- Hardware-backed or remote signing +- A real risk engine with an idempotent intent model +- Durable, replicated queue and reconciliation storage +- Metrics, tracing, alerting, and structured logs +- Controlled deployment and delegation procedures +- RPC redundancy and chain-specific fee policy +- Graceful shutdown and operator runbooks +- Load, fault-injection, and live-chain recovery testing - EIP-7702 changes the code that executes at your address. Before delegating, verify the implementation source and deployed address, verify the target chain, inspect any existing delegation, and use a throwaway account for this demo. `submit` refuses to run if the current designator does not exactly match `LANE_ACCOUNT_IMPL`. + Before you delegate, verify the implementation source, the deployed address, and the target chain. Inspect any existing delegation. Use a throwaway account for this demo. EIP-7702 changes the code that executes at your address. `submit` refuses to run if the current designator does not exactly match `LANE_ACCOUNT_IMPL`. -Treat `.env`, `app/.state/`, signed raw transactions, and RPC URLs containing credentials as sensitive. The journal does not contain private keys, but it contains signed UserOperations and replayable raw transactions until their nonces are consumed. Clone the repository for a teammate and create fresh keys; do not copy a working directory. +Treat `.env`, `app/.state/`, signed raw transactions, and RPC URLs that contain credentials as sensitive. The journal does not contain private keys, but it contains signed UserOperations and replayable raw transactions until their nonces are consumed. For a teammate, clone the repository and create fresh keys. Do not copy a working directory. ## Troubleshooting @@ -694,11 +726,11 @@ Treat `.env`, `app/.state/`, signed raw transactions, and RPC URLs containing cr Check both `SEI_CHAIN_ID` and `SEI_RPC_URL`. For a local fork, pass `--chain-id 1328` to Anvil. The configured chain ID is part of the EIP-712 signature domain and cannot be guessed safely. - The canonical v0.8 singleton is deployed at `0x4337084D9E255Ff0702461CF8895CE9E3b5Ff108` on both Sei Mainnet and Sei Testnet. A `MISSING` line against current state usually means the configured RPC is not serving Sei. Check `SEI_RPC_URL`, and check that a local Anvil was started with `--fork-url` against a Sei endpoint rather than as a bare chain. `submit` fails closed on the same condition with `No EntryPoint at … on this chain`, before it signs anything. + The canonical v0.8 singleton is deployed at `0x4337084D9E255Ff0702461CF8895CE9E3b5Ff108` on both Sei Mainnet and Sei Testnet. A `MISSING` line against current state usually means the configured RPC is not serving Sei. Check `SEI_RPC_URL`. For a local Anvil, check that it was started with `--fork-url` against a Sei endpoint, not as a bare chain. `submit` fails closed on the same condition with `No EntryPoint at … on this chain`, before it signs anything. - Do not deploy your own EntryPoint to work around it. A second EntryPoint lives at a different address, so it has a different EIP-712 domain and shares no lane sequences or deposits with the one every other integration on Sei uses. + Do not deploy your own EntryPoint to work around it. A second EntryPoint is at a different address, so it has a different EIP-712 domain. It also shares no lane sequences or deposits with the EntryPoint that every other integration on Sei uses. - Confirm the deployment against the same endpoint. Export `SEI_RPC_URL` from your `.env`, then run: + Confirm the deployment against the same endpoint. Export `SEI_RPC_URL` from your `.env`, and then run: ```bash cast call 0x4337084D9E255Ff0702461CF8895CE9E3b5Ff108 \ @@ -706,32 +738,36 @@ Treat `.env`, `app/.state/`, signed raw transactions, and RPC URLs containing cr --rpc-url "$SEI_RPC_URL" ``` - It answers `ERC4337`, version `1`, its own address, and the chain ID you queried. Comparing bytecode against another chain's deployment is the wrong test: v0.8 caches that domain separator in an immutable, so the runtime code at the canonical address differs by that one word, and by the chain ID word, on every chain it is deployed to. + It returns `ERC4337`, version `1`, its own address, and the chain ID that you queried. Comparing bytecode with another chain's deployment is the wrong test. EntryPoint v0.8 caches that domain separator in an immutable. The runtime code at the canonical address therefore differs by that one word on every chain where it is deployed. It also differs by the chain ID word. - Run `npm run status` and compare `delegated to` with `LANE_ACCOUNT_IMPL`. Do not blindly replace an unexpected designator. Confirm the account, chain, and implementation first, then run `npm run delegate` deliberately. + Run `npm run status`, and compare `delegated to` with `LANE_ACCOUNT_IMPL`. Do not blindly replace an unexpected designator. First confirm the account, chain, and implementation. Then run `npm run delegate` deliberately. Run `npm run fund`, or send SEI to relayer `0` and run `npm run dispense`. - Relayers must be plain EOAs, and every mutating command checks that before it signs. The usual cause is a public mnemonic whose addresses already have code or a delegation on Sei. A fork inherits that account code. Generate a fresh mnemonic with `cast wallet new-mnemonic`, point `RELAYER_MNEMONIC` at it, and fund the new relayers rather than trying to undelegate the old ones. + Relayers must be plain EOAs, and every mutating command checks that before it signs. The usual cause is a public mnemonic whose addresses already have code or a delegation on Sei. A fork inherits that account code. Generate a fresh mnemonic with `cast wallet new-mnemonic`, and point `RELAYER_MNEMONIC` at it. Fund the new relayers instead of trying to undelegate the old ones. - Common validation causes: `AA24` is an invalid signature or the wrong EIP-712 chain or domain; `AA25` is a stale or incorrect lane sequence; an insufficient EntryPoint prefund; or delegation to the wrong account implementation. Run `npm run status` and resolve the cause before widening bundles or retrying. + `AA24` means an invalid signature, or the wrong EIP-712 chain or domain. `AA25` means a stale or incorrect lane sequence. Other common validation causes are an insufficient EntryPoint prefund and delegation to the wrong account implementation. Run `npm run status`. Resolve the cause before you widen bundles or retry. - `AA95` is the EntryPoint's report that the outer transaction had less gas left than an operation's declared limits require. In general it points to an outer gas limit or estimation headroom that is too low, not to network capacity. While widening bundles, the usual cause is the block gas limit: simulation cannot find an outer gas amount under that limit that satisfies the check, and the relayer never signs above the limit it read at startup. Nothing in a bundle that fails simulation is broadcast or consumed. Rerun with a smaller `MAX_OPS_PER_BUNDLE`; the durable queue is repacked at the smaller width. + `AA95` is the EntryPoint's report that the outer transaction had less gas left than an operation's declared limits require. In general, it points to an outer gas limit or estimation headroom that is too low, not to network capacity. When you widen bundles, the usual cause is the block gas limit. Simulation cannot find an outer gas amount under that limit that satisfies the check. The relayer never signs above the limit that it read at startup. + + Nothing in a bundle that fails simulation is broadcast or consumed. Rerun with a smaller `MAX_OPS_PER_BUNDLE`. The durable queue is repacked at the smaller width. Only one lane-based process may use an account at a time, even when `submit` and `swap:submit` use different journals. Stop the other process. A lock whose recorded PID is no longer alive is removed automatically on the next run. - `could not acquire the lock … within 2000ms` is different. The lock file exists but its contents could not be parsed, so the process cannot tell whether a live holder owns it, and it refuses to remove a lock it cannot attribute. A torn or truncated file left by a dead process and a live holder caught mid-publish produce the same message, and the message repeating across runs does not distinguish between them. Removing a lock that a live process holds lets two processes sign for the same account, which produces duplicate operations on the same lane sequences and conflicting relayer nonces. + `could not acquire the lock … within 2000ms` is different. The lock file exists, but the process could not parse its contents, so it cannot tell whether a live holder owns the lock. It refuses to remove a lock that it cannot attribute. A torn or truncated file left by a dead process produces the same message as a live holder caught mid-publish. A message that repeats across runs does not distinguish between them either. + + If you remove a lock that a live process holds, two processes can sign for the same account. That produces duplicate operations on the same lane sequences and conflicting relayer nonces. - Before deleting a lock file by hand, confirm that no `submit`, `swap:submit`, or `bench:lanes` process is running against this account. Read the `pid` from the file if it is legible, and check the process table on every host that shares the state directory. Both locks live under `app/.state/`: the account-wide run lock (`sender--
.lock`, or `SENDER_RUN_LOCK_PATH`) and one `.lock` file next to each journal. Delete the file only after that check. + Before you delete a lock file manually, confirm that no `submit`, `swap:submit`, or `bench:lanes` process is running against this account. If the file is legible, read the `pid` from it. Check the process table on every host that shares the state directory. Both locks are under `app/.state/`: the account-wide run lock (`sender--
.lock`, or `SENDER_RUN_LOCK_PATH`) and one `.lock` file next to each journal. Delete the file only after that check. - Do not delete the journal and do not send the relayer's next nonce manually. Run `npm run submit` again once the RPC can answer receipt and nonce queries. If the application reports partial lane consumption or a state it cannot reconcile, stop and inspect the EntryPoint events, every attempted transaction hash, the relayer's confirmed nonce, and each lane sequence. + Do not delete the journal. Do not send the relayer's next nonce manually. When the RPC can answer receipt and nonce queries, run `npm run submit` again. If the application reports partial lane consumption or a state that it cannot reconcile, stop. Then inspect the EntryPoint events, every attempted transaction hash, the relayer's confirmed nonce, and each lane sequence. @@ -748,7 +784,7 @@ Treat `.env`, `app/.state/`, signed raw transactions, and RPC URLs containing cr UserOperations, the EntryPoint, and two-dimensional nonces. - The alt-mempool rules the in-process bundling queue sidesteps. + The alt-mempool rules that do not apply to the in-process bundling queue. Why one confirmation is final and the pending view is unreliable. @@ -759,7 +795,7 @@ Treat `.env`, `app/.state/`, signed raw transactions, and RPC URLs containing cr A hosted ERC-4337 bundler and paymaster, if you want sponsorship instead of throughput. - + EIP-7702 delegation for consumer wallet flows. diff --git a/evm/oracles/api3.mdx b/evm/oracles/api3.mdx index 72de170..a52540e 100644 --- a/evm/oracles/api3.mdx +++ b/evm/oracles/api3.mdx @@ -3,30 +3,30 @@ title: 'API3' description: 'Complete guide to integrating API3 with Sei' keywords: ['API3', 'oracle', 'price feeds', 'data feeds', 'decentralized oracle', 'sei'] --- -API3 is a decentralized oracle network that provides real-time data feeds to smart contracts. Unlike traditional oracles that rely on third-party intermediaries, API3 connects APIs directly to the blockchain through first-party oracles operated by the API providers themselves. This approach reduces trust assumptions and potential points of failure. +API3 is a decentralized oracle network that supplies real-time data feeds to smart contracts. Traditional oracles rely on third-party intermediaries. API3 instead connects APIs directly to the blockchain through first-party oracles that the API providers operate themselves. This approach reduces trust assumptions and potential points of failure. -## What You'll Be Doing in This Guide +## What you'll be doing in this guide -In this tutorial, you'll learn how to: +This tutorial shows you how to: -1. Integrate API3's data feeds into your smart contract on the SEI network -2. Retrieve real-time SEI token price data using API3's proxy contract +1. Integrate API3's data feeds into your smart contract on Sei +2. Get real-time price data for the SEI token from API3's proxy contract 3. Understand the structure of API3's reader proxy interface -4. Deploy and test your integration on SEI +4. Deploy and test your integration on Sei -By the end of this guide, you'll have a working smart contract that can fetch SEI price data from API3's decentralized oracle network. +By the end of this guide, you will have a working smart contract that can fetch SEI price data from API3's decentralized oracle network. ## Prerequisites -Before starting this tutorial, ensure you have: +Before you start this tutorial, make sure that you have: -### Technical Requirements +### Technical requirements -- **Solidity Knowledge**: Basic understanding of Solidity smart contract development -- **Development Environment**: Remix IDE, Hardhat, or similar Solidity development setup -- **SEI Network Access**: RPC endpoint and mainnet access for SEI +- **Solidity knowledge**: A basic understanding of smart contract development in Solidity +- **Development environment**: Remix IDE, Hardhat, or a similar Solidity development setup +- **Sei network access**: An RPC endpoint and access to Sei Mainnet -### Required Dependencies +### Required dependencies - OpenZeppelin Contracts library (`@openzeppelin/contracts`) - API3 Contracts library (`@api3/contracts`) @@ -44,16 +44,16 @@ yarn add @openzeppelin/contracts @api3/contracts pnpm add @openzeppelin/contracts @api3/contracts ``` -### SEI Network Configuration +### Sei network configuration -Make sure your development environment is configured for SEI: +Make sure that your development environment is configured for Sei: - **Mainnet RPC**: `https://evm-rpc.sei-apis.com` -- **Chain ID**: 1329 (mainnet) +- **Chain ID**: 1329 (Sei Mainnet) -## Contract Code +## Contract code -Here's the complete smart contract code for integrating with API3 to read SEI price data: +This complete smart contract reads SEI price data from API3: ```solidity // SPDX-License-Identifier: MIT @@ -106,40 +106,40 @@ contract DataFeedReaderExample is Ownable { } ``` -### Contract Breakdown +### Contract breakdown -**Key Components:** +**Main components:** -1. **Proxy Address**: The contract stores the API3 proxy address that provides SEI price data -2. **Data Validation**: The contract validates that price values are positive and timestamps are recent -3. **IApi3ReaderProxy Interface**: This interface provides the `read()` function to fetch price data +1. **Proxy address**: The contract stores the address of the API3 proxy that supplies SEI price data +2. **Data validation**: The contract validates that price values are positive and that timestamps are recent +3. **IApi3ReaderProxy interface**: This interface has the `read()` function, which fetches price data -**The `readDataFeed()` Function:** +**The `readDataFeed()` function:** - Returns `int224 value`: The SEI price (likely in USD with 18 decimal places) - Returns `uint256 timestamp`: When the price was last updated -- Validates data freshness (within 1 day) -- Ensures price is positive +- Checks that the data is fresh (within 1 day) +- Checks that the price is positive -## Proxy Address +## Proxy address -For this tutorial, we'll be using the following API3 proxy address on SEI: +This tutorial uses the API3 proxy at this address on Sei: [`0x09c6e594DE2EB633902f00B87A43b27F80a31a60`](https://seiscan.io/address/0x09c6e594DE2EB633902f00B87A43b27F80a31a60) -This proxy provides real-time [SEI/USD](https://market.api3.org/sei/sei-usd/integrate) price data from API3's decentralized oracle network. +This proxy supplies real-time [SEI/USD](https://market.api3.org/sei/sei-usd/integrate) price data from API3's decentralized oracle network. -## How to Test +## How to test -### 1. Deploy the Contract +### 1. Deploy the contract **Using Remix IDE:** 1. Open [Remix IDE](https://remix.ethereum.org/) -2. Create a new file called `DataFeedReaderExample.sol` -3. Paste the contract code above -4. Compile the contract using Solidity compiler ^0.8.0 -5. Deploy with constructor parameter: `0x09c6e594DE2EB633902f00B87A43b27F80a31a60` +2. Create a new file named `DataFeedReaderExample.sol` +3. Paste the contract code from above +4. Compile the contract with the Solidity compiler (version ^0.8.0) +5. Deploy with this constructor parameter: `0x09c6e594DE2EB633902f00B87A43b27F80a31a60` **Using Hardhat:** @@ -150,9 +150,9 @@ const reader = await DataFeedReader.deploy(proxy); await reader.deployed(); ``` -### 2. Read Price Data +### 2. Read price data -After deployment, call the `readDataFeed()` function to retrieve the current SEI price: +After you deploy the contract, call the `readDataFeed()` function to get the current SEI price: ```javascript // Using ethers.js @@ -161,14 +161,14 @@ console.log('SEI Price:', ethers.utils.formatUnits(result.value, 18)); console.log('Last Updated:', new Date(result.timestamp * 1000)); ``` -**Expected Output Format:** +**Expected output format:** -- `value`: SEI price in USD (with 18 decimals, e.g., `300000000000000000` = $0.3) +- `value`: The SEI price in USD (with 18 decimals, for example `300000000000000000` = $0.3) - `timestamp`: Unix timestamp of the last price update -### 3. Integration Examples +### 3. Integration examples -**Basic Price Display:** +**Basic price display:** ```solidity function getSEIPrice() external view returns (int224 value) { diff --git a/evm/oracles/chainlink.mdx b/evm/oracles/chainlink.mdx index 8f4f0f0..a639a2b 100644 --- a/evm/oracles/chainlink.mdx +++ b/evm/oracles/chainlink.mdx @@ -7,54 +7,54 @@ keywords: ['chainlink', 'oracle', 'data streams', 'price feeds', 'real-time data ## What is Chainlink? -Chainlink is the world's most widely adopted decentralized oracle network, enabling smart contracts to securely access off-chain data, APIs, and traditional payment systems. Chainlink Data Streams is a pull-based oracle solution that delivers high-frequency, low-latency market data directly to smart contracts. +Chainlink is the world's most widely adopted decentralized oracle network. It lets smart contracts securely access off-chain data, APIs, and traditional payment systems. Chainlink Data Streams is a pull-based oracle that delivers high-frequency, low-latency market data directly to smart contracts. -## What This Guide Teaches You +## What this guide teaches you -This tutorial will walk you through integrating Chainlink Data Streams on Sei Network to: +This tutorial shows you how to integrate Chainlink Data Streams on Sei to: -1. **Fetch real-time price data** using the Chainlink Data Streams SDK -2. **Deploy a smart contract** that can verify and decode price reports on-chain -3. **Combine off-chain and on-chain components** to create a complete oracle solution -4. **Verify SEI/USDT price feeds** as a practical example +1. Fetch real-time price data with the Chainlink Data Streams SDK +2. Deploy a smart contract that can verify and decode price reports on-chain +3. Combine off-chain and on-chain components to create a complete oracle solution +4. Verify SEI/USDT price feeds as a practical example -By the end of this guide, you'll have a working implementation that fetches price data off-chain and verifies it on-chain using Chainlink's data streams SDK. +By the end of this guide, you will have a working implementation that uses the Chainlink Data Streams SDK. It fetches price data off-chain and verifies it on-chain. ## Prerequisites -Before starting this tutorial, ensure you have: +Before you start this tutorial, make sure that you have: -### Technical Requirements +### Technical requirements -- **Node.js** (v18 or higher) and npm installed -- **Basic knowledge** of TypeScript/JavaScript -- **Solidity development experience** (basic to intermediate) -- **Familiarity with smart contract deployment** tools like Remix or Hardhat +- Node.js (v18 or higher) and npm installed +- Basic knowledge of TypeScript or JavaScript +- Solidity development experience (basic to intermediate) +- Familiarity with tools to deploy smart contracts, such as Remix or Hardhat -### Sei Network Setup +### Sei network setup -**Testnet** : +**Sei Testnet:** - **Sei Testnet RPC**: `https://evm-rpc-testnet.sei-apis.com` - **Chain ID**: 1328 -**Mainnet** : +**Sei Mainnet:** -- **SEI mainnet RPC**: `https://evm-rpc.sei-apis.com` +- **Sei Mainnet RPC**: `https://evm-rpc.sei-apis.com` - **Chain ID**: 1329 -### Chainlink Data Streams Access +### Chainlink Data Streams access -You need to contact Chainlink for getting access to API credentials of Data Streams. +Contact Chainlink to get access to the API credentials for Data Streams. -- **API credentials**: Contact Chainlink to get access to Data Streams on Sei Mainnet/testnet +- **API credentials**: Contact Chainlink to get access to Data Streams on Sei Mainnet or Sei Testnet - **API Key** and **User Secret** for testnet access -- **Feed IDs**: We'll use [SEI/USDT](https://docs.chain.link/data-streams/crypto-streams?page=1&testnetPage=1&testnetSearch=SEI#testnet-crypto-streams) feed ID `0x0003dba2d8553dfd7afe35c2bfe217ef5106d7805e5272c04a08940ddb868117` -- **VerifierProxy contract address**: `0x60fAa7faC949aF392DFc858F5d97E3EEfa07E9EB` — the same address is used on [Sei Mainnet](https://seiscan.io/address/0x60fAa7faC949aF392DFc858F5d97E3EEfa07E9EB) and [Sei Testnet](https://testnet.seiscan.io/address/0x60fAa7faC949aF392DFc858F5d97E3EEfa07E9EB). See Chainlink's [Stream Addresses](https://docs.chain.link/data-streams/crypto-streams) page for the current list. +- **Feed IDs**: This guide uses the [SEI/USDT](https://docs.chain.link/data-streams/crypto-streams?page=1&testnetPage=1&testnetSearch=SEI#testnet-crypto-streams) feed ID `0x0003dba2d8553dfd7afe35c2bfe217ef5106d7805e5272c04a08940ddb868117` +- **VerifierProxy contract address**: `0x60fAa7faC949aF392DFc858F5d97E3EEfa07E9EB`. [Sei Mainnet](https://seiscan.io/address/0x60fAa7faC949aF392DFc858F5d97E3EEfa07E9EB) and [Sei Testnet](https://testnet.seiscan.io/address/0x60fAa7faC949aF392DFc858F5d97E3EEfa07E9EB) use the same address. For the current list, see Chainlink's [Stream Addresses](https://docs.chain.link/data-streams/crypto-streams) page. -## Step-by-Step Tutorial +## Step-by-step tutorial -### Step 1: Project Setup +### Step 1: Project setup Create a new directory and initialize your project: @@ -78,9 +78,9 @@ API_KEY=your_chainlink_api_key_here USER_SECRET=your_chainlink_user_secret_here ``` -### Step 2: Fetching Price Data with TypeScript +### Step 2: Fetching price data with TypeScript -Create a file called `singleStream.ts` with the following code: +Create a file named `singleStream.ts` with this code: ```typescript import { createClient, decodeReport, LogLevel, getReportVersion, formatReport } from '@chainlink/data-streams-sdk'; @@ -142,14 +142,14 @@ main(); This script: -- **Creates a Data Streams client** with your API credentials -- **Fetches the latest report** for a given feed ID -- **Decodes the raw report** into readable price data -- **Displays both raw and formatted data** for debugging +- Creates a Data Streams client with your API credentials +- Fetches the latest report for a given feed ID +- Decodes the raw report into readable price data +- Displays both the raw and the formatted data for debugging -### Step 3: Smart Contract Deployment +### Step 3: Smart contract deployment -Create and deploy the verification contract on Sei Network. Copy this Solidity code into Remix IDE: +Create and deploy the verification contract on Sei. Copy this Solidity code into Remix IDE: ```solidity // SPDX-License-Identifier: MIT @@ -286,10 +286,10 @@ contract ClientReportsVerifier { **Deployment steps in Remix:** 1. Switch to Sei Testnet in MetaMask -2. Deploy with Sei Testnet VerifierProxy address: `0x60fAa7faC949aF392DFc858F5d97E3EEfa07E9EB` +2. Deploy the contract with the VerifierProxy address for Sei Testnet: `0x60fAa7faC949aF392DFc858F5d97E3EEfa07E9EB` 3. Save the contract address for testing -### Step 4: Complete Integration Script +### Step 4: Complete integration script Create `verifyOnChain.ts` to combine off-chain fetching with on-chain verification: @@ -343,11 +343,11 @@ async function main() { main().catch(console.error); ``` -## How to Run and Test +## How to run and test -### 1. Test Off-chain Data Fetching +### 1. Test off-chain data fetching -Run the single stream script to verify off-chain fetching and decoding: +Run the single-stream script to test off-chain fetching and decoding: ```bash npx tsx singleStream.ts 0x0003dba2d8553dfd7afe35c2bfe217ef5106d7805e5272c04a08940ddb868117 @@ -378,15 +378,15 @@ Bid Price: 179941088372418000 Ask Price: 180063641553635300 ``` -### 2. Test Smart Contract Deployment +### 2. Test smart contract deployment -1. Copy the raw report blob from Step 1 output (the long hex string starting with `0x00090d9e...`) -2. Call `verifyReport()` and paste the entire blob as the `unverifiedReport` parameter -3. Call `getLastPrice()` - you should see the decoded price (e.g., `180009506586149300`) +1. Copy the raw report blob from the Step 1 output (the long hex string that starts with `0x00090d9e...`) +2. Call `verifyReport()` with the entire blob as the `unverifiedReport` parameter +3. Call `getLastPrice()`. You should see the decoded price (for example, `180009506586149300`) -### 3. Test Complete Integration +### 3. Test complete integration -**Step 3a: Setup Integration Script** +**Step 3a: Set up the integration script** Add your private key to `.env`: @@ -396,17 +396,15 @@ USER_SECRET=your_chainlink_user_secret_here PRIVATE_KEY=your_sei_testnet_private_key_here ``` -Update `verifyOnChain.ts` with your deployed contract address: +In `verifyOnChain.ts`, replace `YOUR_DEPLOYED_CONTRACT_ADDRESS` with the address of your deployed contract. -Replace `YOUR_DEPLOYED_CONTRACT_ADDRESS` in the script with your actual contract address. - -**Step 3b: Run Integration Test** +**Step 3b: Run the integration test** ```bash npx tsx verifyOnChain.ts ``` -**Expected Output:** +**Expected output:** ```bash npx tsx verifyOnChain.ts @@ -420,4 +418,4 @@ Price verified on-chain: 0.180009506586149300 SEI/USDT ## Resources -- [Chainlink Data Streams Documentation](https://docs.chain.link/data-streams/) +- [Chainlink Data Streams documentation](https://docs.chain.link/data-streams/) diff --git a/evm/oracles/pyth-network.mdx b/evm/oracles/pyth-network.mdx index 62b25d3..acf5017 100644 --- a/evm/oracles/pyth-network.mdx +++ b/evm/oracles/pyth-network.mdx @@ -3,31 +3,31 @@ title: 'Pyth Network' description: 'Complete guide to integrating Pyth Network with Sei' keywords: ['pyth network', 'oracle', 'price feeds', 'pull oracle', 'real-time data', 'sei'] --- -Pyth Network is a first-party oracle solution that provides high-fidelity, low-latency financial market data on-chain. Unlike traditional push-based oracles, Pyth uses a unique "pull" model where applications retrieve signed price updates on-demand, significantly reducing gas costs while maintaining data freshness. With over 400+ price feeds across cryptocurrencies, equities, FX, and commodities, Pyth aggregates data directly from 120+ institutional data publishers including major exchanges and trading firms. +Pyth Network is a first-party oracle that delivers high-fidelity, low-latency financial market data on-chain. Unlike traditional push-based oracles, Pyth uses a "pull" model: applications get signed price updates on demand. This significantly reduces gas costs and still keeps the data fresh. Pyth has more than 400 price feeds across cryptocurrencies, equities, FX, and commodities. It aggregates data directly from more than 120 institutional data publishers, including major exchanges and trading firms. -## What You'll Be Doing in This Guide +## What you'll be doing in this guide -In this tutorial, you'll learn how to: +This tutorial shows you how to: 1. Integrate Pyth Network's pull-based oracle system into your Sei EVM application -2. Fetch real-time SEI token price data using Pyth's JavaScript SDK +2. Fetch real-time price data for the SEI token with Pyth's JavaScript SDK 3. Create a smart contract that consumes Pyth price feeds with proper price update mechanisms 4. Understand Pyth's on-demand architecture and implement efficient price fetching strategies -By the end of this guide, you'll have a working demo that can fetch and utilize Sei price data from Pyth Network's oracle system with proper on-chain verification. +By the end of this guide, you will have a working demo. It can fetch and use SEI price data from Pyth Network's oracle system, with proper on-chain verification. ## Prerequisites -Before starting this tutorial, ensure you have: +Before you start this tutorial, make sure that you have: -### Technical Requirements +### Technical requirements -- **Solidity Knowledge**: Basic understanding of Solidity smart contract development -- **JavaScript/Node.js**: For off-chain price data fetching using Pyth EVM SDK -- **Development Environment**: Remix IDE, Hardhat, Foundry, or similar Solidity development setup -- **Sei Network Access**: RPC endpoint and familiarity with Sei's EVM environment +- **Solidity knowledge**: A basic understanding of smart contract development in Solidity +- **JavaScript and Node.js**: To fetch price data off-chain with the Pyth EVM SDK +- **Development environment**: Remix IDE, Hardhat, Foundry, or a similar Solidity development setup +- **Sei network access**: An RPC endpoint and familiarity with the Sei EVM environment -### Required Dependencies +### Required dependencies - Pyth EVM JavaScript SDK (`@pythnetwork/pyth-evm-js`) - Pyth Solidity SDK (`@pythnetwork/pyth-sdk-solidity`) @@ -45,28 +45,28 @@ yarn add @pythnetwork/pyth-evm-js @pythnetwork/pyth-sdk-solidity pnpm add @pythnetwork/pyth-evm-js @pythnetwork/pyth-sdk-solidity ``` -### Sei Network Configuration +### Sei network configuration -Make sure your development environment is configured for Sei: +Make sure that your development environment is configured for Sei: - **Mainnet RPC**: `https://evm-rpc.sei-apis.com` -- **Chain ID**: 1329 (mainnet) +- **Chain ID**: 1329 (Sei Mainnet) - **Testnet RPC**: `https://evm-rpc-testnet.sei-apis.com` -- **Testnet Chain ID**: 1328 (testnet) +- **Testnet chain ID**: 1328 (Sei Testnet) -## Pyth Architecture Overview +## Pyth architecture overview Pyth's pull-based oracle model consists of: 1. **Publishers**: 120+ institutional data providers that sign and submit price data to Pythnet -2. **Pythnet**: Dedicated blockchain that aggregates publisher data using a stake-weighted algorithm -3. **Hermes**: Off-chain price service that provides signed price update messages -4. **Target Chains**: EVM networks (like Sei) where applications consume price data on-demand -5. **Price Update Mechanism**: Users submit price update data alongside their transactions +2. **Pythnet**: A dedicated blockchain that aggregates publisher data with a stake-weighted algorithm +3. **Hermes**: An off-chain price service that supplies signed price update messages +4. **Target chains**: EVM networks (such as Sei) where applications consume price data on demand +5. **Price update mechanism**: Users submit price update data alongside their transactions -## Steps to Integrate Pyth Price Feeds +## Steps to integrate Pyth price feeds -### Step 1: Smart Contract Integration +### Step 1: Smart contract integration Create a smart contract that integrates with Pyth's on-chain price feeds: @@ -139,15 +139,15 @@ contract SeiPythPriceDemo { } ``` -You can fetch Price Feeds at [docs](https://docs.pyth.network/price-feeds/core/price-feeds/price-feed-ids?search=sei&pageSize=50). +You can find price feeds in the [Pyth docs](https://docs.pyth.network/price-feeds/core/price-feeds/price-feed-ids?search=sei&pageSize=50). -Deploy the contract using [Remix](https://remix.ethereum.org/) with the constructor arguments set to the Pyth contract address on Sei: +Deploy the contract with [Remix](https://remix.ethereum.org/). Set the constructor arguments to the Pyth contract address on Sei: -- **Sei Mainnet/Testnet Pyth Contract**: [0x2880aB155794e7179c9eE2e38200202908C17B43](https://docs.pyth.network/price-feeds/core/contract-addresses/evm) +- **Pyth contract on Sei Mainnet and Sei Testnet**: [0x2880aB155794e7179c9eE2e38200202908C17B43](https://docs.pyth.network/price-feeds/core/contract-addresses/evm) -### Step 2: JavaScript Integration for Price Updates +### Step 2: JavaScript integration for price updates -Create a module to fetch price updates directly from Pyth's Hermes API and interact with your deployed contract: +Create a module that fetches price updates directly from Pyth's Hermes API and interacts with your deployed contract: ```javascript const ethers = require('ethers'); @@ -308,9 +308,9 @@ if (require.main === module) { } ``` -### Step 3: Complete Integration Example +### Step 3: Complete integration example -Here's a simple usage example that puts it all together: +This simple example combines all the parts: ```javascript // demo.js - Simple demonstration script @@ -330,9 +330,9 @@ demonstrateSeiPriceIntegration() }); ``` -### Expected Output +### Expected output -When you run the integration, you should see output similar to: +When you run the integration, you should see output similar to this: ``` 🚀 Starting SEI-Pyth integration demo... @@ -395,31 +395,31 @@ Querying updated price with 120 second time limit... - Final SEI Price: $0.132869 ``` -### Data Structure Details +### Data structure details -Pyth price data includes several important fields: +Pyth price data includes these fields: - **price**: The asset price (scaled by `expo`) -- **conf**: Confidence interval (±range around the price) -- **expo**: The exponent for scaling the price (e.g., -6 means divide by 1,000,000) -- **publishTime**: Unix timestamp when the price was last updated +- **conf**: The confidence interval (the ± range around the price) +- **expo**: The exponent that scales the price (for example, -6 means divide by 1,000,000) +- **publishTime**: The Unix timestamp of the last price update -### Fee Structure +### Fee structure -- **Update Fee**: Small fee paid in native token (SEI) to submit price update data -- **Variable Cost**: Fee depends on the number of price feeds being updated -- **Gas Efficiency**: Pull model is more gas-efficient than traditional push oracles +- **Update fee**: A small fee, paid in the native token (SEI), to submit price update data +- **Variable cost**: The fee depends on how many price feeds you update +- **Gas efficiency**: The pull model is more gas efficient than traditional push oracles -## Best Practices +## Best practices -1. **Price Freshness**: Always check price age before using in critical applications -2. **Confidence Intervals**: Consider the confidence interval for risk management -3. **Fee Management**: Monitor update fees and optimize update frequency -4. **Error Handling**: Implement robust error handling for price update failures +1. **Price freshness**: Always check the age of a price before you use it in critical applications +2. **Confidence intervals**: Consider the confidence interval for risk management +3. **Fee management**: Monitor update fees and optimize the update frequency +4. **Error handling**: Implement error handling for failed price updates ## Resources -- [Pyth Network Documentation](https://docs.pyth.network/) -- [Pyth Price Feed IDs](https://docs.pyth.network/price-feeds/core/price-feeds/price-feed-ids?search=sei&pageSize=50) -- [Pyth EVM SDK GitHub](https://github.com/pyth-network/pyth-crosschain) -- [Hermes Price Service API](https://api-reference.pyth.network/price-feeds/evm) +- [Pyth Network documentation](https://docs.pyth.network/) +- [Pyth price feed IDs](https://docs.pyth.network/price-feeds/core/price-feeds/price-feed-ids?search=sei&pageSize=50) +- [Pyth EVM SDK on GitHub](https://github.com/pyth-network/pyth-crosschain) +- [Hermes price service API](https://api-reference.pyth.network/price-feeds/evm) diff --git a/evm/oracles/redstone.mdx b/evm/oracles/redstone.mdx index 0121a75..e44889a 100644 --- a/evm/oracles/redstone.mdx +++ b/evm/oracles/redstone.mdx @@ -4,31 +4,31 @@ sidebarTitle: 'Redstone' description: 'Complete guide to integrating RedStone oracles with Sei' keywords: ['redstone', 'oracle', 'data on-demand', 'price feeds', 'modular oracle', 'sei'] --- -RedStone is a modular oracle network that provides real-time data feeds to smart contracts through a unique approach called "data-on-demand". Instead of constantly pushing data to the blockchain, RedStone delivers signed data packages directly to smart contracts at the time of transaction execution. This architecture significantly reduces gas costs while maintaining high data freshness and reliability. +RedStone is a modular oracle network. It supplies real-time data feeds to smart contracts through an approach called "data-on-demand". RedStone does not push data to the blockchain constantly. Instead, it delivers signed data packages directly to smart contracts when the transaction executes. This architecture significantly reduces gas costs. Data freshness and reliability stay high. -## What You'll Be Doing in This Guide +## What you'll be doing in this guide -In this tutorial, you'll learn how to: +This tutorial shows you how to: -1. Integrate RedStone's data feeds into your application on the SEI network -2. Retrieve real-time SEI token price data using RedStone's SDK and data packages -3. Understand RedStone's unique "data-on-demand" architecture -4. Implement fetching and data verification +1. Integrate RedStone's data feeds into your application on Sei +2. Get real-time price data for the SEI token with RedStone's SDK and data packages +3. Understand RedStone's "data-on-demand" architecture +4. Implement data fetching and verification -By the end of this guide, you'll have a working demo that can fetch SEI price data from RedStone's oracle network using their data package system. +By the end of this guide, you will have a working demo. It can fetch SEI price data from RedStone's oracle network with the RedStone data package system. ## Prerequisites -Before starting this tutorial, ensure you have: +Before you start this tutorial, make sure that you have: -### Technical Requirements +### Technical requirements -- **Solidity Knowledge**: Basic understanding of Solidity smart contract development -- **JavaScript/Node.js**: For off-chain data fetching using RedStone SDK -- **Development Environment**: Remix IDE, Hardhat, or similar Solidity development setup -- **SEI Network Access**: RPC endpoint and mainnet access for SEI +- **Solidity knowledge**: A basic understanding of smart contract development in Solidity +- **JavaScript and Node.js**: To fetch data off-chain with the RedStone SDK +- **Development environment**: Remix IDE, Hardhat, or a similar Solidity development setup +- **Sei network access**: An RPC endpoint and access to Sei Mainnet -### Required Dependencies +### Required dependencies - RedStone SDK (`@redstone-finance/sdk`) - RedStone EVM Connector (`@redstone-finance/evm-connector`) @@ -46,25 +46,25 @@ yarn add @redstone-finance/sdk @redstone-finance/evm-connector pnpm add @redstone-finance/sdk @redstone-finance/evm-connector ``` -### SEI Network Configuration +### Sei network configuration -Make sure your development environment is configured for SEI: +Make sure that your development environment is configured for Sei: - **Mainnet RPC**: `https://evm-rpc.sei-apis.com` -- **Chain ID**: 1329 (mainnet) +- **Chain ID**: 1329 (Sei Mainnet) -## RedStone Architecture Overview +## RedStone architecture overview -RedStone uses a unique "data-on-demand" model: +RedStone uses a "data-on-demand" model: -1. **Data Providers**: Collect data from multiple sources and sign data packages -2. **Data Packages**: Signed data structures containing price information and metadata -3. **Gateway Network**: Distributes data packages to consumers -4. **Smart Contracts**: Verify signatures and extract data on-chain +1. **Data providers**: Collect data from multiple sources and sign data packages +2. **Data packages**: Signed data structures that contain price information and metadata +3. **Gateway network**: Distributes data packages to consumers +4. **Smart contracts**: Verify signatures and extract data on-chain -## Steps to Fetch SEI Price Data +## Steps to fetch SEI price data -Let's implement the JavaScript code to fetch SEI price data using RedStone's SDK: +This JavaScript code fetches SEI price data with RedStone's SDK: ```javascript import { requestDataPackages, getSignersForDataServiceId } from '@redstone-finance/sdk'; @@ -129,16 +129,16 @@ fetchSEIPrice() }); ``` -### Data Package Structure +### Data package structure A RedStone data package contains: -- **dataPoints**: Array of price data points +- **dataPoints**: An array of price data points - **timestampMilliseconds**: When the data was signed -- **signature**: Cryptographic signature from the data provider -- **dataPackageId**: Identifier for the specific data feed (e.g., "SEI") +- **signature**: The cryptographic signature from the data provider +- **dataPackageId**: The identifier of the specific data feed (for example, "SEI") ## Resources -- [RedStone Documentation](https://docs.redstone.finance/) -- [RedStone GitHub Repository](https://github.com/redstone-finance) +- [RedStone documentation](https://docs.redstone.finance/) +- [RedStone GitHub repository](https://github.com/redstone-finance) diff --git a/evm/precompiles/cosmwasm-precompiles/addr.mdx b/evm/precompiles/cosmwasm-precompiles/addr.mdx index c547dd9..13ba17b 100644 --- a/evm/precompiles/cosmwasm-precompiles/addr.mdx +++ b/evm/precompiles/cosmwasm-precompiles/addr.mdx @@ -6,40 +6,40 @@ keywords: ['addr precompile', 'address association', 'ethers.js', 'cross-chain', --- **Address:** `0x0000000000000000000000000000000000001004` -The Sei Address precompile allows EVM applications to interact directly with Sei's address association system through standard smart contract calls. This enables querying and creating mappings between EVM addresses and their corresponding Cosmos addresses, enabling seamless cross-chain address management without needing separate Cosmos SDK integration. +The Sei Address precompile lets EVM applications interact directly with Sei's address association system through standard smart contract calls. You can use it to query and create mappings between EVM addresses and their corresponding Cosmos addresses. You get cross-chain address management without a separate Cosmos SDK integration. - **What is a precompile?** A precompile is a special smart contract deployed at a fixed address by the Sei protocol itself, that exposes custom native chain logic to EVM-based applications. It acts like a regular contract from the EVM's perspective, but executes privileged, low-level logic efficiently. + **What is a precompile?** A precompile is a special smart contract that the Sei protocol itself deploys at a fixed address. It exposes custom native chain logic to EVM-based applications. To the EVM, it behaves like a regular contract, but it executes privileged, low-level logic efficiently. -## How Does the Address Precompile Work? +## How does the Address precompile work? -The Address precompile at address `0x0000000000000000000000000000000000001004` exposes functions like `associate()`, `associatePubKey()`, `getSeiAddr()`, and `getEvmAddr()`. +The Address precompile at address `0x0000000000000000000000000000000000001004` exposes functions such as `associate()`, `associatePubKey()`, `getSeiAddr()`, and `getEvmAddr()`. -- **Direct Integration:** EVM contracts and dApps can call address association functions like any other smart contract method. -- **Native Execution:** Operations are executed at the Cosmos SDK level for maximum efficiency and security. -- **Seamless Bridge:** No need for separate wallet integrations or complex cross-chain interactions. +- EVM contracts and dApps can call address association functions directly, like any other smart contract method. +- Operations run natively at the Cosmos SDK level for efficiency and security. +- You do not need separate wallet integrations or complex cross-chain interactions. -## Use Cases +## Use cases -- **Cross-Chain Identity:** Link EVM and Cosmos addresses for unified user experiences across both execution environments. -- **Address Resolution:** Build applications that can seamlessly work with both EVM and Cosmos address formats. -- **Wallet Integration:** Enable users to associate their addresses once and use both EVM and native Sei functionality. -- **DeFi Applications:** Create protocols that can interact with users regardless of their preferred address format. +- **Cross-chain identity:** Link EVM and Cosmos addresses for a unified user experience across both execution environments. +- **Address resolution:** Build applications that can work with both EVM and Cosmos address formats. +- **Wallet integration:** Let users associate their addresses once and then use both EVM and native Sei functionality. +- **DeFi applications:** Create protocols that can interact with users regardless of their preferred address format. -## What You'll Learn in This Guide +## What you'll learn in this guide -By the end of this guide, you'll be able to: +After you finish this guide, you can: -- **Integrate Address Operations** - Call association and lookup functions directly from your EVM contracts and dApps -- **Handle Signature Verification** - Master the signature format requirements for secure address association -- **Manage Address Mappings** - Query and validate address relationships between EVM and Cosmos formats -- **Build Cross-Chain Tools** - Implement unified address management for applications spanning both execution environments -- **Navigate Association Requirements** - Understand when and how address association occurs automatically vs. manually +- Call association and lookup functions directly from your EVM contracts and dApps. +- Handle signature verification and the signature format requirements for secure address association. +- Query and validate address mappings between EVM and Cosmos formats. +- Build cross-chain tools with unified address management for applications that span both execution environments. +- Understand when and how address association happens automatically or manually. ## Functions -The Address precompile exposes the following functions: +The Address precompile exposes these functions: -### Transaction Functions +### Transaction functions ```solidity /// Associates an account given it's signature of any custom message. @@ -65,7 +65,7 @@ function associatePubKey( ) external returns (string memory seiAddr, address evmAddr); ``` -### Query Functions +### Query functions ```solidity /// Queries the corresponding Sei Address for some EVM address. @@ -83,23 +83,23 @@ function getEvmAddr( ) external view returns (address response); ``` -## Using the Precompile +## Using the precompile ### Setup #### Prerequisites -Before getting started, ensure you have: +Before you start, make sure that you have: -- **Node.js** (v18 or higher) -- **npm** or **yarn** package manager -- **EVM-compatible wallet** -- **SEI tokens** for gas -- **Hardhat** development environment set up +- Node.js (v18 or higher) +- The npm or yarn package manager +- An EVM-compatible wallet +- SEI tokens for gas +- A Hardhat development environment set up -#### Install Dependencies +#### Install dependencies -Install the required packages for interacting with Sei precompiles: +Install the required packages to interact with Sei precompiles: ```bash # Initiate a Hardhat 3 project (choose "Hardhat 3" and the Mocha + Ethers.js TypeScript setup) @@ -112,9 +112,9 @@ npm install ethers npm install @sei-js/precompiles@^3 ``` -#### Setup Hardhat Environment +#### Setup Hardhat environment -Create a `hardhat.config.ts` file with the following content: +Create a `hardhat.config.ts` file with this content: ```typescript import { defineConfig, configVariable } from 'hardhat/config'; @@ -134,13 +134,13 @@ export default defineConfig({ }); ``` -Store your private key in Hardhat's encrypted keystore (no plaintext `.env` file needed): +Store your private key in Hardhat's encrypted keystore, so that you do not need a plaintext `.env` file: ```bash npx hardhat keystore set PRIVATE_KEY ``` -#### Import Precompile Components +#### Import precompile components @@ -179,9 +179,9 @@ function getEvmAddr(string memory addr) external view returns (address response) - **Precompile Address:** The address precompile is deployed at `0x0000000000000000000000000000000000001004` + **Precompile address:** The Address precompile is deployed at `0x0000000000000000000000000000000000001004`. -### Contract Initialization +### Contract initialization @@ -208,9 +208,9 @@ contract CrossChainAddressManager { -#### When Does Association Happen? +#### When does association happen? -Address association between EVM and Cosmos addresses occurs automatically in most cases: +In most cases, the association between EVM and Cosmos addresses happens automatically: | Method | Trigger | Requirements | | --- | --- | --- | @@ -219,36 +219,36 @@ Address association between EVM and Cosmos addresses occurs automatically in mos | **Manual (PubKey)** | associatePubKey() function | Compressed public key | -### How Association Works +### How association works -**Automatic Association:** +**Automatic association:** -- Occurs when a wallet first signs and broadcasts any transaction on Sei -- No additional steps required for most users -- Association is permanent once created +- The association happens when a wallet first signs and broadcasts any transaction on Sei. +- Most users do not need to take any other steps. +- The association is permanent after it is created. -**Manual Association:** +**Manual association:** -- Use `associate()` for signature-based association -- Use `associatePubKey()` for public key-based association -- Useful for advanced applications or when automatic association hasn't occurred +- Use `associate()` for signature-based association. +- Use `associatePubKey()` for public-key-based association. +- Manual association is useful for advanced applications, or when automatic association has not happened. -### Address Format Requirements +### Address format requirements -**EVM Addresses:** +**EVM addresses:** - Standard Ethereum format: `0x1234...` (20 bytes, 40 hex characters) -- Case-insensitive but typically lowercase +- Case-insensitive, but typically lowercase -**Sei Addresses:** +**Sei addresses:** -- Cosmos format with `sei1...` prefix for regular addresses -- Validator addresses use `seivaloper1...` prefix +- Cosmos format, with the `sei1...` prefix for regular addresses +- Validator addresses use the `seivaloper1...` prefix - Bech32 encoding format -## Step-by-Step Guide: Using the Address Precompile +## Step-by-step guide: Using the Address precompile -### Associate Address with Signature +### Associate address with signature @@ -309,7 +309,7 @@ contract AddressManager { -### Associate Address with Public Key +### Associate address with public key @@ -352,7 +352,7 @@ contract AddressManager { -### Query Sei Address from EVM Address +### Query Sei address from EVM address @@ -398,7 +398,7 @@ contract AddressManager { -### Query EVM Address from Sei Address +### Query EVM address from Sei address @@ -444,7 +444,7 @@ contract AddressManager { -### Complete Integration Example +### Complete integration example @@ -511,7 +511,7 @@ async function addrExample() { -**Contract Example** +**Contract example** ```solidity // SPDX-License-Identifier: MIT @@ -606,7 +606,7 @@ contract CrossChainAddressManager { } ``` -**Client Integration Example** +**Client integration example** Deploy the contract: @@ -695,24 +695,24 @@ npx hardhat run scripts/interact.js --network sei -## Security Considerations & Risks +## Security considerations & risks -### Association Permanence +### Association permanence -- **Permanent Mapping:** Once addresses are associated, the mapping cannot be changed or removed -- **Single Association:** Each address can only be associated with one counterpart -- **Verification:** Always verify associations before depending on them in critical operations +- **Permanent mapping:** After addresses are associated, the mapping cannot be changed or removed. +- **Single association:** Each address can be associated with only one counterpart. +- **Verification:** Always verify associations before you depend on them in critical operations. -### Signature Security +### Signature security -- **Custom Messages:** Use unique, timestamped messages to prevent replay attacks -- **Message Format:** Follow exact Ethereum Signed Message format for compatibility +- **Custom messages:** Use unique, timestamped messages to prevent replay attacks. +- **Message format:** Follow the exact Ethereum Signed Message format for compatibility. ## Troubleshooting -### Common Issues and Solutions +### Common issues and solutions -#### Gas-Related Issues +#### Gas-related issues ```typescript // Set appropriate gas limits for different operations @@ -725,43 +725,43 @@ const pubKeyTx = await addr.associatePubKey(pubKeyHex, { }); ``` -### Error Code Reference +### Error code reference | Error | Cause | Solution | | --- | --- | --- | -| `invalid signature` | Malformed v, r, s components | Verify signature parsing and format | -| `already associated` | Address already has association | Check existing association instead | -| `not found` | No association exists | Create association first | -| `invalid public key` | Malformed public key format | Use compressed format without 0x prefix | -| `invalid address format` | Wrong address format | Use proper EVM (0x...) or Sei (sei1...) format | +| `invalid signature` | Malformed v, r, s components | Verify the signature parsing and format | +| `already associated` | The address already has an association | Check the existing association instead | +| `not found` | No association exists | Create an association first | +| `invalid public key` | Malformed public key format | Use the compressed format without the 0x prefix | +| `invalid address format` | Wrong address format | Use the correct EVM (0x...) or Sei (sei1...) format | -## Important Notes +## Important notes - Remember: Address associations are permanent and cannot be changed once created! + Address associations are permanent and cannot be changed after they are created. -### Address Formats +### Address formats -- **EVM Addresses:** Use standard Ethereum format with `0x` prefix -- **Sei Addresses:** Use Cosmos format with `sei1` prefix for regular addresses -- **Case Sensitivity:** EVM addresses are case-insensitive, Sei addresses are case-sensitive +- **EVM addresses:** Use the standard Ethereum format with the `0x` prefix. +- **Sei addresses:** Use the Cosmos format with the `sei1` prefix for regular addresses. +- **Case sensitivity:** EVM addresses are case-insensitive. Sei addresses are case-sensitive. -### Association Timing +### Association timing -- **Automatic:** Most users get associated automatically on their first transaction -- **Manual:** Use precompile functions for programmatic association or when automatic association hasn't occurred -- **Verification:** Always verify associations exist before depending on them +- **Automatic:** For most users, association happens automatically on their first transaction. +- **Manual:** Use the precompile functions for programmatic association, or when automatic association has not happened. +- **Verification:** Always verify that associations exist before you depend on them. -### Signature Requirements +### Signature requirements -- **Message Format:** Must include Ethereum Signed Message prefix for `associate()` function -- **Component Format:** v, r, s must be properly formatted hex strings -- **Replay Protection:** Use unique messages to prevent signature replay attacks +- **Message format:** For the `associate()` function, the message must include the Ethereum Signed Message prefix. +- **Component format:** v, r, and s must be correctly formatted hex strings. +- **Replay protection:** Use unique messages to prevent signature replay attacks. -### Gas Considerations +### Gas considerations -- **Association operations:** ~200,000 gas limit recommended -- **Query operations:** Standard view function gas usage -- **Batch operations:** Scale gas limits based on array size +- **Association operations:** Use a gas limit of approximately 200,000. +- **Query operations:** These use the standard gas for a view function. +- **Batch operations:** Scale gas limits based on the array size. -View the Address precompile source code and the contract ABI [here](https://github.com/sei-protocol/sei-chain/tree/main/precompiles/addr). +View the [Address precompile source code and contract ABI](https://github.com/sei-protocol/sei-chain/tree/main/precompiles/addr). diff --git a/evm/precompiles/cosmwasm-precompiles/bank.mdx b/evm/precompiles/cosmwasm-precompiles/bank.mdx index 957113d..931ac12 100644 --- a/evm/precompiles/cosmwasm-precompiles/bank.mdx +++ b/evm/precompiles/cosmwasm-precompiles/bank.mdx @@ -8,10 +8,10 @@ keywords: ['bank precompile', 'native sei', 'ethers.js', 'balance query', 'sei d **Address:** `0x0000000000000000000000000000000000001001` -This page covers native SEI (`usei`) only. Do not use the Bank precompile as an IBC or tokenfactory integration path. IBC is disabled in both directions, and tokenfactory is not supported for new development. See [IBC is disabled](/learn/sip-03-migration#ibc-is-disabled) and [Tokenfactory is not supported](/cosmos-sdk#tokenfactory-is-not-supported). +Do not use the Bank precompile as an IBC or tokenfactory integration path. This page covers native SEI (`usei`) only. IBC is disabled in both directions. Tokenfactory is not supported for new development. See [IBC is disabled](/learn/sip-03-migration#ibc-is-disabled) and [Tokenfactory is not supported](/cosmos-sdk#tokenfactory-is-not-supported). -The Bank precompile exposes the Bank Module balance for native SEI and lets an EVM caller send SEI to a native `sei1...` address. +The Bank precompile exposes the Bank Module balance for native SEI. It also lets an EVM caller send SEI to a native `sei1...` address. ## Functions @@ -135,4 +135,4 @@ contract NativeSeiSender { } ``` -Validate the recipient before sending. A successful transaction cannot be reversed. +Validate the recipient before you send SEI. A successful transaction cannot be reversed. diff --git a/evm/precompiles/cosmwasm-precompiles/cosmwasm.mdx b/evm/precompiles/cosmwasm-precompiles/cosmwasm.mdx index 2affbfa..41ce914 100644 --- a/evm/precompiles/cosmwasm-precompiles/cosmwasm.mdx +++ b/evm/precompiles/cosmwasm-precompiles/cosmwasm.mdx @@ -7,43 +7,43 @@ keywords: ['cosmwasm precompile', 'ethers.js', 'wasm execution', 'cross-chain co **Address:** `0x0000000000000000000000000000000000001002` - **Deprecation Notice — Prop 115** + **Deprecation notice (Prop 115)** - Per [governance Proposal 115](https://seistream.app/proposals/115), CosmWasm code uploads (`MsgStoreCode`) and contract instantiations (`MsgInstantiateContract`) are disabled chain-wide. The `instantiate()` function on this precompile **will revert** for all callers. Only `execute()`, `execute_batch()`, and `query()` against pre-existing CosmWasm contracts remain functional, and all CosmWasm functionality is deprecated in favor of EVM-only per [SIP-3](https://github.com/sei-protocol/sips/blob/main/sips/sip-3.md). + Under [governance Proposal 115](https://seistream.app/proposals/115), CosmWasm code uploads (`MsgStoreCode`) and contract instantiations (`MsgInstantiateContract`) are disabled chain-wide. The `instantiate()` function on this precompile **reverts** for all callers. Only calls to `execute()`, `execute_batch()`, and `query()` against pre-existing CosmWasm contracts still work. All CosmWasm functionality is deprecated in favor of EVM-only under [SIP-3](https://github.com/sei-protocol/sips/blob/main/sips/sip-3.md). - The examples on this page attach only native SEI. Do not use the `coins` field to build IBC or tokenfactory integrations. IBC is disabled in both directions, and tokenfactory is not a supported development path. + The examples on this page attach only native SEI. Do not use the `coins` field to build IBC or tokenfactory integrations. IBC is disabled in both directions. Tokenfactory is not a supported development path. For new smart contract development, use the EVM directly. See [Deploy a Smart Contract](/evm/evm-general). -The Sei CosmWasm precompile allows EVM applications to interact directly with **pre-existing** CosmWasm contracts through standard smart contract calls. This enables execution, batch operations, and querying of CosmWasm contracts directly from your dApps without needing separate Cosmos SDK integration. +The Sei CosmWasm precompile lets EVM applications interact directly with **pre-existing** CosmWasm contracts through standard smart contract calls. You can call CosmWasm contracts directly from your dApps for execution, batch operations, and queries. You do not need a separate Cosmos SDK integration. - **What is a precompile?** A precompile is a special smart contract deployed at a fixed address by the Sei protocol itself, that exposes custom native chain logic to EVM-based applications. It acts like a regular contract from the EVM's perspective, but executes privileged, low-level logic efficiently. + **What is a precompile?** A precompile is a special smart contract that the Sei protocol itself deploys at a fixed address. It exposes custom native chain logic to EVM-based applications. To the EVM, it behaves like a regular contract, but it executes privileged, low-level logic efficiently. -## How Does the CosmWasm Precompile Work? +## How does the CosmWasm precompile work? -The CosmWasm precompile at address `0x0000000000000000000000000000000000001002` exposes functions like `execute()`, `execute_batch()`, and `query()`. +The CosmWasm precompile at address `0x0000000000000000000000000000000000001002` exposes functions such as `execute()`, `execute_batch()`, and `query()`. -- **Direct Integration:** EVM contracts and dApps can call CosmWasm functions like any other smart contract method. -- **Native Execution:** Operations are executed at the Cosmos SDK level for maximum efficiency and security. -- **Seamless Bridge:** No need for separate wallet integrations or complex cross-chain interactions. +- EVM contracts and dApps can call CosmWasm functions directly, like any other smart contract method. +- Operations run natively at the Cosmos SDK level for efficiency and security. +- You do not need separate wallet integrations or complex cross-chain interactions. -## What You'll Learn in This Guide +## What you'll learn in this guide -By the end of this guide, you'll be able to: +After you finish this guide, you can: -- **Execute Contract Functions** - Call CosmWasm contract methods and handle message formatting -- **Batch Operations** - Execute multiple contract calls efficiently in a single transaction -- **Query Contract State** - Read CosmWasm contract data without gas costs -- **Handle Cross-Runtime Data** - Master message encoding/decoding between EVM and CosmWasm formats +- Call CosmWasm contract functions and handle message formatting. +- Run batch operations that execute multiple contract calls efficiently in a single transaction. +- Query contract state to read CosmWasm contract data without gas costs. +- Handle cross-runtime data by encoding and decoding messages between EVM and CosmWasm formats. ## Functions -The CosmWasm precompile exposes the following functions: +The CosmWasm precompile exposes these functions: -### Transaction Functions +### Transaction functions -The `instantiate()` function has been disabled by [Prop 115](https://seistream.app/proposals/115) and will revert. It is omitted from this reference. The ABI in `@sei-js/precompiles` may still expose it for backwards compatibility, but calling it on-chain will fail. +[Prop 115](https://seistream.app/proposals/115) disabled the `instantiate()` function, so calls to it revert. This reference omits it. The ABI in `@sei-js/precompiles` may still expose it for backward compatibility, but on-chain calls to it fail. ```solidity /// Executes some message on a CosmWasm contract. @@ -71,7 +71,7 @@ function execute_batch( ) payable external returns (bytes[] memory responses); ``` -### Query Functions +### Query functions ```solidity /// Queries a CosmWasm contract. @@ -84,22 +84,22 @@ function query( ) external view returns (bytes memory response); ``` -## Using the Precompile +## Using the precompile ### Setup #### Prerequisites -Before getting started, ensure you have: +Before you start, make sure that you have: -- **Node.js** (v18 or higher) -- **npm** or **yarn** package manager -- **EVM-compatible wallet** -- **SEI tokens** for gas and contract operations +- Node.js (v18 or higher) +- The npm or yarn package manager +- An EVM-compatible wallet +- SEI tokens for gas and contract operations -#### Install Dependencies +#### Install dependencies -Install the required packages for interacting with Sei precompiles: +Install the required packages to interact with Sei precompiles: ```bash # Install ethers.js for smart contract interactions @@ -109,7 +109,7 @@ npm install ethers npm install @sei-js/precompiles@^3 ``` -#### Import Precompile Components +#### Import precompile components ```typescript // Import CosmWasm precompile address and ABI @@ -118,9 +118,9 @@ import { WASM_PRECOMPILE_ABI, WASM_PRECOMPILE_ADDRESS } from '@sei-js/precompile import { ethers } from 'ethers'; ``` - **Precompile Address:** The CosmWasm precompile is deployed at `0x0000000000000000000000000000000000001002` + **Precompile address:** The CosmWasm precompile is deployed at `0x0000000000000000000000000000000000001002`. -### Contract Initialization +### Contract initialization Set up your provider, signer, and contract instance: @@ -134,35 +134,33 @@ const signer = await provider.getSigner(); const cosmwasm = new ethers.Contract(WASM_PRECOMPILE_ADDRESS, WASM_PRECOMPILE_ABI, signer); ``` -## Critical: Understanding Message Formats +## Critical: Understanding message formats -One of the most important concepts to understand when working with the Sei CosmWasm precompile: +### CosmWasm message structure -### CosmWasm Message Structure +The CosmWasm precompile requires JSON-encoded messages that match each contract's own schema: -The CosmWasm precompile requires **JSON-encoded messages** that conform to each contract's specific schema: - -| Function | Input/Output | Format Type | Example | +| Function | Input/Output | Format type | Example | | --- | --- | --- | --- | | `execute()` | msg parameter (input) | JSON bytes | `ethers.toUtf8Bytes(jsonString)` | | `query()` | req parameter (input) | JSON bytes | `ethers.toUtf8Bytes(jsonString)` | | **All functions** | response (output) | JSON bytes | `JSON.parse(ethers.toUtf8String(response))` | -### How Message Encoding Works +### How message encoding works **All CosmWasm functions require JSON-encoded byte arrays:** -- `execute()` - accepts execution message as JSON bytes -- `query()` - accepts query message as JSON bytes +- `execute()`: accepts the execution message as JSON bytes +- `query()`: accepts the query message as JSON bytes **Native SEI handling:** - Use `msg.value` for SEI amounts - Pass an empty JSON array for `coins` when the call does not require Bank Module funds -### Best Practice: Message Encoding Helpers +### Best practice: Message encoding helpers -When working with CosmWasm messages, use proper JSON encoding: +When you work with CosmWasm messages, use correct JSON encoding: ```typescript // Helper functions for message encoding @@ -197,7 +195,7 @@ const queryMsg = CosmWasmMessageEncoder.encodeQueryMsg({ }); ``` -## Message Format Helpers +## Message format helpers Use these helper functions to handle CosmWasm message formatting: @@ -242,9 +240,9 @@ const executeMsg = CosmWasmHelper.createExecuteMsg({ const coins = CosmWasmHelper.emptyCoins(); ``` -## Step-by-Step Guide: Using the CosmWasm Precompile +## Step-by-step guide: Using the CosmWasm precompile -### Execute a CosmWasm Contract +### Execute a CosmWasm contract @@ -302,7 +300,7 @@ contract CosmWasmExecutor { -### Execute Batch Operations +### Execute batch operations @@ -373,7 +371,7 @@ contract BatchExecutor { -### Query a CosmWasm Contract +### Query a CosmWasm contract @@ -440,11 +438,11 @@ contract CosmWasmQuery { - **Query Limitations:** CosmWasm queries are read-only operations and don't consume gas, but parsing JSON responses in Solidity is complex. Consider handling response parsing off-chain. + **Query limitations:** Consider parsing responses off-chain. CosmWasm queries are read-only operations and do not consume gas. However, parsing JSON responses in Solidity is complex. -## Advanced Usage Examples +## Advanced usage examples -### Cross-Runtime DeFi Integration +### Cross-runtime DeFi integration ```typescript async function crossRuntimeDeFiOperation(cosmwasmDexContract: string, evmTokenContract: string, amount: string) { @@ -483,7 +481,7 @@ async function crossRuntimeDeFiOperation(cosmwasmDexContract: string, evmTokenCo } ``` -### Complete Integration Example +### Complete integration example @@ -574,7 +572,7 @@ async function cosmwasmExample() { -**Contract Example** +**Contract example** ```solidity // SPDX-License-Identifier: MIT @@ -662,9 +660,9 @@ contract CosmWasmBridge { } ``` - **Note:** This contract acts as a bridge between EVM and existing CosmWasm contracts. Message encoding/decoding should be handled client-side for complex operations. + This contract is a bridge between the EVM and existing CosmWasm contracts. For complex operations, handle message encoding and decoding client-side. -**Client Integration Example** +**Client integration example** ```javascript import { network } from 'hardhat'; @@ -721,9 +719,9 @@ main().catch((error) => { ## Troubleshooting -### Common Issues and Solutions +### Common issues and solutions -#### Message Encoding Issues +#### Message encoding issues ```typescript // Ensure proper JSON encoding for messages @@ -741,46 +739,46 @@ const encodedMsg = ethers.toUtf8Bytes(JSON.stringify(msg)); const incorrectMsg = ethers.toUtf8Bytes('invalid json'); ``` -### Error Code Reference +### Error code reference | Error | Cause | Solution | | --- | --- | --- | -| `invalid json` | Malformed JSON message | Validate JSON before encoding | -| `contract not found` | Invalid contract address | Verify contract address format | -| `insufficient funds` | Not enough tokens for operation | Check balance and reduce amount | -| `execution failed` | Contract execution error | Check contract state and parameters | +| `invalid json` | Malformed JSON message | Validate the JSON before encoding | +| `contract not found` | Invalid contract address | Verify the contract address format | +| `insufficient funds` | Not enough tokens for the operation | Check the balance and reduce the amount | +| `execution failed` | Contract execution error | Check the contract state and parameters | | `unauthorized` | Insufficient permissions | Check admin/owner permissions | -| `query parsing failed` | Invalid query message format | Match contract's query schema | +| `query parsing failed` | Invalid query message format | Match the contract's query schema | -## Important Notes +## Important notes - Remember the key rule: All CosmWasm messages must be properly JSON-encoded as bytes, and contract schemas vary by implementation! + All CosmWasm messages must be correctly JSON-encoded as bytes. Contract schemas vary by implementation. -### Message Format Requirements +### Message format requirements -- **JSON Encoding:** All messages must be valid JSON encoded as UTF-8 bytes, invalid JSON will cause transaction failures -- **Schema Compliance:** Messages must match the contract's expected format -- **Type Safety:** Use proper data types as expected by the contract +- **JSON encoding:** All messages must be valid JSON, encoded as UTF-8 bytes. Invalid JSON causes transaction failures. +- **Schema compliance:** Messages must match the contract's expected format. +- **Type safety:** Use the data types that the contract expects. -### Contract Address Format +### Contract address format -- Use valid Sei contract addresses with `sei1...` prefix -- These are Cosmos-format addresses, not EVM addresses -- **Contract Existence:** Verify contracts exist before calling +- Use valid Sei contract addresses with the `sei1...` prefix. +- These are Cosmos-format addresses, not EVM addresses. +- **Contract existence:** Verify that contracts exist before you call them. -### Cross-Runtime Considerations +### Cross-runtime considerations -- **State Isolation:** CosmWasm and EVM contracts have separate state -- **Gas Estimation:** CosmWasm operations may require different gas calculations -- **Error Handling:** Failed CosmWasm operations revert the entire EVM transaction -- **Native SEI Handling:** Use `msg.value` for SEI and leave the `coins` list empty -- **Batch Limitations:** Large batches may hit gas limits +- **State isolation:** CosmWasm and EVM contracts have separate state. +- **Gas estimation:** CosmWasm operations may require different gas calculations. +- **Error handling:** Failed CosmWasm operations revert the entire EVM transaction. +- **Native SEI handling:** Use `msg.value` for SEI and leave the `coins` list empty. +- **Batch limitations:** Large batches may reach gas limits. -### Best Practices +### Best practices -- Always validate JSON messages before sending -- Handle response parsing carefully, especially for complex data structures -- Use batch operations for multiple related calls to save gas -- Query contracts before executing to verify state when possible +- Always validate JSON messages before you send them. +- Parse responses carefully, especially for complex data structures. +- Use batch operations for multiple related calls to save gas. +- When possible, query contracts to verify their state before you execute calls on them. -View the CosmWasm precompile source code and the contract ABI [here](https://github.com/sei-protocol/sei-chain/tree/main/precompiles/wasmd). +View the [CosmWasm precompile source code and contract ABI](https://github.com/sei-protocol/sei-chain/tree/main/precompiles/wasmd). diff --git a/evm/precompiles/cosmwasm-precompiles/example-usage.mdx b/evm/precompiles/cosmwasm-precompiles/example-usage.mdx index d21cff5..2409fae 100644 --- a/evm/precompiles/cosmwasm-precompiles/example-usage.mdx +++ b/evm/precompiles/cosmwasm-precompiles/example-usage.mdx @@ -6,17 +6,16 @@ keywords: ["precompile example", "ethers.js", "cosmwasm query", "evm integration -Per [Proposal 115](https://seistream.app/proposals/115), no new CosmWasm contracts can be deployed on Sei. The examples below apply to **pre-existing CosmWasm contracts** only. `instantiate()` will revert. +Under [Proposal 115](https://seistream.app/proposals/115), no new CosmWasm contracts can be deployed on Sei. The examples below apply to **pre-existing CosmWasm contracts** only. Calls to `instantiate()` revert. -The Sei precompiles can be used like any standard smart contract on the EVM. For -example, using [ethers.js](https://docs.ethers.org/v6/), you can query and -execute actions on an existing CosmWasm contract as follows: +You can use the Sei precompiles like any standard smart contract on the EVM. For +example, this page uses [ethers.js](https://docs.ethers.org/v6/) to query an +existing CosmWasm contract and execute actions on it. ## Setup -To install `ethers`, run the following command in your project directory -terminal: +To install `ethers`, run this command in a terminal in your project directory: ```bash npm install ethers @sei-js/precompiles@^3 @@ -32,7 +31,7 @@ import { WASM_PRECOMPILE_ABI, WASM_PRECOMPILE_ADDRESS } from '@sei-js/precompile ## Using the contract -Next, we'll set up a provider and contract to interact with the blockchain: +Next, set up a provider and a contract to interact with Sei: ```typescript import { ethers, toUtf8Bytes, toUtf8String } from 'ethers'; @@ -45,10 +44,11 @@ const signer = await provider.getSigner(); const contract = new ethers.Contract(WASM_PRECOMPILE_ADDRESS, WASM_PRECOMPILE_ABI, signer); ``` -#### Querying & Executing a CosmWasm Contract +#### Querying & executing a CosmWasm contract -Once you have the contract, you can query and execute messages to any CosmWasm -smart contract. In the below example we assume there is a counter contract with a `get_count` function +When you have the contract instance, you can send query and execute messages to +any CosmWasm smart contract. The example below assumes a counter contract with a +`get_count` function. ```typescript // Replace with your contract @@ -75,8 +75,8 @@ console.log(executeResponse); ### Executing a payable function -In this example, we execute the 'donate' method on our contract. This is similar -to the `increment` method, but also receives funds from the user and stores it +This example executes the `donate` method on the same contract. It is similar to +the `increment` method, but it also receives funds from the user and stores them in the contract. ```typescript diff --git a/evm/precompiles/distribution.mdx b/evm/precompiles/distribution.mdx index 143ae93..360ff67 100644 --- a/evm/precompiles/distribution.mdx +++ b/evm/precompiles/distribution.mdx @@ -8,17 +8,17 @@ keywords: ['distribution precompile', 'staking rewards', 'validator commissions' **Address**: `0x0000000000000000000000000000000000001007` -The distribution precompile provides EVM access to Cosmos SDK's distribution module. Smart contracts can manage staking rewards, validator commissions, and withdrawal addresses. This precompile is essential for DeFi applications that need to handle staking rewards programmatically. +The distribution precompile gives EVM access to the Cosmos SDK distribution module. Smart contracts can use it to manage staking rewards, validator commissions, and withdrawal addresses. DeFi dApps that need to handle staking rewards programmatically depend on this precompile. -## Key Features +## Key features -- **Reward Management**: Withdraw delegation rewards from validators -- **Commission Handling**: Validators can withdraw earned commissions -- **Batch Operations**: Withdraw from multiple validators efficiently -- **Flexible Withdrawals**: Set custom withdrawal addresses -- **Comprehensive Queries**: Access detailed reward information through `rewards(address)` +- Withdraw delegation rewards from validators. +- Withdraw earned commission (validators only). +- Withdraw rewards from multiple validators in one batch call. +- Set a custom withdrawal address. +- Query detailed reward information with `rewards(address)`. -## Interface Overview +## Interface overview ```solidity interface IDistr { @@ -41,13 +41,13 @@ interface IDistr { ## Setup -Install Ethers.js and the Sei EVM bindings that ship the precompile address and ABI: +Install ethers and the Sei EVM bindings, which include the precompile address and ABI: ```bash npm install ethers @sei-js/precompiles@^3 ``` -Import both constants wherever you build the contract instance: +Import both constants where you create the contract instance: ```ts import { DISTRIBUTION_PRECOMPILE_ABI, DISTRIBUTION_PRECOMPILE_ADDRESS } from '@sei-js/precompiles'; @@ -55,7 +55,7 @@ import { DISTRIBUTION_PRECOMPILE_ABI, DISTRIBUTION_PRECOMPILE_ADDRESS } from '@s ## Events -The distribution precompile emits events for all state-changing operations, allowing off-chain services to track reward distributions and configuration changes. +The distribution precompile emits events for all state-changing operations. Off-chain services can use these events to track reward distributions and configuration changes. ### WithdrawAddressSet @@ -67,8 +67,8 @@ event WithdrawAddressSet(address indexed delegator, address withdrawAddr); **Parameters:** -- `delegator` (indexed): The EVM address of the delegator changing their settings -- `withdrawAddr`: The new address where rewards will be sent +- `delegator` (indexed): The EVM address of the delegator who changes the setting +- `withdrawAddr`: The new address that receives the rewards **Example usage:** @@ -89,9 +89,9 @@ event DelegationRewardsWithdrawn(address indexed delegator, string validator, ui **Parameters:** -- `delegator` (indexed): The EVM address of the delegator withdrawing rewards -- `validator`: The Sei validator address (e.g., "seivaloper1...") -- `amount`: The amount of rewards withdrawn (in usei, 6 decimal precision) +- `delegator` (indexed): The EVM address of the delegator who withdraws the rewards +- `validator`: The Sei validator address (for example, "seivaloper1...") +- `amount`: The amount of rewards withdrawn (in usei, 6-decimal precision) **Example usage:** @@ -113,9 +113,9 @@ event MultipleDelegationRewardsWithdrawn(address indexed delegator, string[] val **Parameters:** -- `delegator` (indexed): The EVM address of the delegator withdrawing rewards -- `validators`: Array of Sei validator addresses -- `amounts`: Array of reward amounts corresponding to each validator (in usei, 6 decimal precision) +- `delegator` (indexed): The EVM address of the delegator who withdraws the rewards +- `validators`: An array of Sei validator addresses +- `amounts`: An array of reward amounts, one for each validator (in usei, 6-decimal precision) **Example usage:** @@ -140,7 +140,7 @@ event ValidatorCommissionWithdrawn(string indexed validator, uint256 amount); **Parameters:** - `validator` (indexed): The Sei validator address -- `amount`: The commission amount withdrawn (in usei, 6 decimal precision) +- `amount`: The commission amount withdrawn (in usei, 6-decimal precision) **Example usage:** @@ -152,13 +152,13 @@ distrContract.on('ValidatorCommissionWithdrawn', (validator, amount) => { }); ``` -**Event Amounts**: All event amounts use 6 decimal precision (usei), matching the actual withdrawn token amounts. This differs from the `rewards()` query which returns 18 decimal precision. +**Event amounts**: All event amounts use 6-decimal precision (usei). This matches the withdrawn token amounts. In contrast, the `rewards()` query returns 18-decimal precision. -## Transaction Methods +## Transaction methods ### setWithdrawAddress -Sets the withdrawal address for staking rewards. By default, rewards are sent to the delegator's address, but this can be customized. +Sets the withdrawal address for staking rewards. By default, rewards go to the delegator's address, but you can change it. ```solidity function setWithdrawAddress(address withdrawAddr) external returns (bool success); @@ -166,9 +166,9 @@ function setWithdrawAddress(address withdrawAddr) external returns (bool success **Parameters:** -- `withdrawAddr`: EVM address where future rewards should be sent +- `withdrawAddr`: The EVM address that receives future rewards -**Gas Cost**: ~30,000 gas +**Gas cost**: ~30,000 gas **Example:** @@ -179,9 +179,9 @@ require(success, "Failed to set withdraw address"); ``` - **Recipient Validation**: The withdrawal address must be able to receive external funds. Through the precompile, an unassociated EVM address is rejected with the error `cannot use an unassociated address as withdraw address`. Separately, the bank module rejects addresses it blocks from receiving external funds with `ErrInvalidRecipient` — for example, the cast address of an EVM account that has since been associated with a different Sei address. Ensure the withdrawal address is associated and permitted to receive funds before setting it. + **Recipient validation**: Before you set the withdrawal address, make sure that it is associated and allowed to receive funds. The withdrawal address must be able to receive external funds. The precompile rejects an unassociated EVM address with the error `cannot use an unassociated address as withdraw address`. Separately, the bank module returns `ErrInvalidRecipient` for an address that it blocks from receiving external funds. For example, it blocks the cast address of an EVM account that was later associated with a different Sei address. - Additionally, if a previously set withdrawal address later becomes invalid (blocked or no longer able to receive external funds), reward withdrawals automatically fall back to sending rewards to the delegator's own address instead. + If a withdrawal address that was set earlier becomes invalid, reward withdrawals automatically fall back to the delegator's own address. An address is invalid when it is blocked or can no longer receive external funds. ### withdrawDelegationRewards @@ -194,9 +194,9 @@ function withdrawDelegationRewards(string memory validator) external returns (bo **Parameters:** -- `validator`: Sei validator address (e.g., "seivaloper1...") +- `validator`: The Sei validator address (for example, "seivaloper1...") -**Gas Cost**: ~50,000-80,000 gas (varies by reward amount) +**Gas cost**: ~50,000-80,000 gas (varies with the reward amount) **Example:** @@ -208,7 +208,7 @@ require(success, "Failed to withdraw rewards"); ### withdrawMultipleDelegationRewards -Efficiently withdraws rewards from multiple validators in a single transaction. +Withdraws rewards from multiple validators in a single transaction. ```solidity function withdrawMultipleDelegationRewards(string[] memory validators) external returns (bool success); @@ -216,9 +216,9 @@ function withdrawMultipleDelegationRewards(string[] memory validators) external **Parameters:** -- `validators`: Array of Sei validator addresses +- `validators`: An array of Sei validator addresses -**Gas Cost**: ~40,000 + (30,000 × number of validators) +**Gas cost**: ~40,000 + (30,000 × number of validators) **Example:** @@ -232,19 +232,19 @@ bool success = DISTR_CONTRACT.withdrawMultipleDelegationRewards(validators); require(success, "Failed to withdraw multiple rewards"); ``` -**Batch Efficiency**: Using `withdrawMultipleDelegationRewards` is significantly more gas-efficient than multiple individual calls, especially when withdrawing from 3+ validators. +**Batch efficiency**: One `withdrawMultipleDelegationRewards` call is significantly more gas-efficient than multiple individual calls, especially when you withdraw from 3 or more validators. ### withdrawValidatorCommission -Allows validators to withdraw their earned commission. Only callable by the validator operator address. +Lets a validator withdraw its earned commission. Only the validator operator address can call this method. ```solidity function withdrawValidatorCommission() external returns (bool success); ``` -**Parameters:** None - the validator is automatically determined from the caller's associated Sei address. +**Parameters:** None. The precompile determines the validator automatically from the caller's associated Sei address. -**Gas Cost**: ~60,000-90,000 gas +**Gas cost**: ~60,000-90,000 gas **Example:** @@ -254,19 +254,19 @@ bool success = DISTR_CONTRACT.withdrawValidatorCommission(); require(success, "Failed to withdraw commission"); ``` -**Validator Only**: This method can only be called by the validator's operator address. The precompile automatically identifies the validator based on the caller's associated Sei address. If the caller is not a validator operator, the call will fail. +**Validator only**: Call this method only from the validator's operator address. The precompile identifies the validator automatically from the caller's associated Sei address. If the caller is not a validator operator, the call fails. -## Query Methods +## Query methods ### rewards -Retrieves comprehensive reward information for a delegator across all validators. +Returns the reward information for a delegator across all validators. ```solidity function rewards(address delegatorAddress) external view returns (Rewards rewards); ``` -**Data Structures:** +**Data structures:** ```solidity struct Coin { @@ -287,11 +287,11 @@ struct Rewards { ``` -**Critical: Decimal Precision for Rewards** +**Critical: decimal precision for rewards** -The `rewards()` query returns amounts with **18 decimal precision** (`DecCoins` from Cosmos SDK). +The `rewards()` query returns amounts with **18-decimal precision** (`DecCoins` from the Cosmos SDK). -This is different from the actual withdrawn reward amounts, which use **6 decimal precision** (`sdk.Coins`). +In contrast, withdrawn reward amounts use **6-decimal precision** (`sdk.Coins`). **To convert pending rewards to SEI for display:** @@ -327,11 +327,11 @@ for (uint i = 0; i < userRewards.rewards.length; i++) { } ``` -## Understanding Decimal Precision +## Understanding decimal precision -The distribution precompile has **different decimal precision for queries vs actual withdrawals** due to how rewards are tracked in the Cosmos SDK: +Because of how the Cosmos SDK tracks rewards, the distribution precompile uses **different decimal precision for queries and withdrawals**: -| Function | Type | Decimal Precision | Conversion to SEI | +| Function | Type | Decimal precision | Conversion to SEI | | --- | --- | --- | --- | | **rewards()** | Query (pending rewards) | 18 decimals (DecCoins) | `amount / 1e18` | | **withdrawDelegationRewards()** | Withdrawn amount (event) | 6 decimals (usei) | `amount / 1e6` | @@ -339,13 +339,13 @@ The distribution precompile has **different decimal precision for queries vs act | **withdrawValidatorCommission()** | Withdrawn amount (event) | 6 decimals (usei) | `amount / 1e6` | -### Why Different Precisions? +### Why different precisions? -1. **Pending Rewards (18 decimals)**: The Cosmos SDK tracks pending rewards using `DecCoins` (decimal coins) with 18 decimal precision for higher accuracy during reward accumulation. +1. **Pending rewards (18 decimals)**: The Cosmos SDK tracks pending rewards as `DecCoins` (decimal coins) with 18-decimal precision. This gives higher accuracy while rewards accumulate. -2. **Withdrawn Rewards (6 decimals)**: When rewards are actually withdrawn, they are converted to `sdk.Coins` (usei) with 6 decimal precision to match Sei's native token units. +2. **Withdrawn rewards (6 decimals)**: When rewards are withdrawn, they are converted to `sdk.Coins` (usei) with 6-decimal precision. This matches Sei's native token units. -### Conversion Helper Functions +### Conversion helper functions ```typescript // Convert pending rewards (18 decimals) to SEI @@ -364,11 +364,11 @@ const pendingSei = pendingRewardsToSei(pendingRewards.total[0].amount); console.log(`Pending rewards: ${pendingSei} SEI`); ``` -**Note**: When reconciling pending rewards with actual withdrawals, be aware of the 12-decimal difference (10^12 factor) between query results and withdrawal amounts. +When you reconcile pending rewards with withdrawals, remember the 12-decimal difference (10^12 factor) between query results and withdrawal amounts. -## Practical Examples +## Practical examples -### DeFi Yield Aggregator +### DeFi yield aggregator ```solidity contract YieldAggregator { @@ -400,7 +400,7 @@ contract YieldAggregator { } ``` -### Validator Commission Manager +### Validator commission manager ```solidity contract ValidatorManager { @@ -423,9 +423,9 @@ contract ValidatorManager { } ``` -## Error Handling +## Error handling -Common error scenarios and how to handle them: +This example shows common error scenarios and how to handle them: ```solidity contract SafeDistribution { @@ -457,16 +457,16 @@ contract SafeDistribution { } ``` -## Gas Optimization Tips +## Gas optimization tips -1. **Batch Operations**: Use `withdrawMultipleDelegationRewards` for multiple validators -2. **Check Before Withdraw**: Query rewards first to avoid unnecessary transactions -3. **Set Withdraw Address Once**: Avoid repeated `setWithdrawAddress` calls -4. **Commission Timing**: Withdraw validator commission when amounts are substantial +1. To withdraw from multiple validators, use one `withdrawMultipleDelegationRewards` batch call. +2. Query rewards before you withdraw, to avoid unnecessary transactions. +3. Set the withdrawal address once. Avoid repeated `setWithdrawAddress` calls. +4. Withdraw validator commission when the amounts are substantial. -## Integration Patterns +## Integration patterns -### Auto-Compounding Strategy +### Auto-compounding strategy ```solidity // Automatically reinvest rewards back into staking @@ -479,7 +479,7 @@ function autoCompound() external { } ``` -### Treasury Management +### Treasury management ```solidity // Route all rewards to a DAO treasury diff --git a/evm/precompiles/example-usage.mdx b/evm/precompiles/example-usage.mdx index bf84897..f182f51 100644 --- a/evm/precompiles/example-usage.mdx +++ b/evm/precompiles/example-usage.mdx @@ -5,10 +5,10 @@ description: "Learn how to interact with Sei's precompiles through viem and ethe keywords: ['precompile usage', 'viem', 'ethers.js', 'sei precompiles', 'evm integration', 'quick start guide'] --- -Sei precompiles are special smart contracts deployed at fixed addresses that expose native Sei functionality to EVM applications. They can be called like any standard smart contract using viem, ethers, or wagmi. +Sei precompiles are special smart contracts deployed at fixed addresses. They expose native Sei functionality to EVM applications. You can call them like any standard smart contract, with viem, ethers, or wagmi. -**Available Precompiles:** +**Available precompiles:** | Precompile | Address | Description | | --- | --- | --- | @@ -24,13 +24,13 @@ Sei precompiles are special smart contracts deployed at fixed addresses that exp | Solo | `0x000000000000000000000000000000000000100C` | Claim Solo migration payloads | | P256 | `0x0000000000000000000000000000000000001011` | Verify P-256 elliptic curve signatures | -This page shows Bank, Staking, Governance, Distribution, JSON, and Solo. The rest are covered on their own pages: [CosmWasm](/evm/precompiles/cosmwasm-precompiles/cosmwasm), [Address](/evm/precompiles/cosmwasm-precompiles/addr), [Pointer contracts](/evm/evm-parity/examples/pointer-contracts) for both pointer precompiles, and [P256](/evm/precompiles/p256-precompile). +This page shows Bank, Staking, Governance, Distribution, JSON, and Solo. The other precompiles have their own pages: [CosmWasm](/evm/precompiles/cosmwasm-precompiles/cosmwasm), [Address](/evm/precompiles/cosmwasm-precompiles/addr), [Pointer contracts](/evm/evm-parity/examples/pointer-contracts) for both pointer precompiles, and [P256](/evm/precompiles/p256-precompile). -The IBC and Oracle precompiles are not exported by `@sei-js/precompiles`. IBC is disabled in both directions, and native Oracle queries are retired. Calls to either precompile cannot succeed on live Sei. See [IBC is disabled](/learn/sip-03-migration#ibc-is-disabled) and [Oracle Precompile (Retired)](/evm/precompiles/oracle). +The `@sei-js/precompiles` package does not export the IBC and Oracle precompiles. IBC is disabled in both directions, and native Oracle queries are retired. Calls to either precompile cannot succeed on live Sei. See [IBC is disabled](/learn/sip-03-migration#ibc-is-disabled) and [Oracle Precompile (Retired)](/evm/precompiles/oracle). -`@sei-js/precompiles@3` is ESM-only and matches Sei Chain v6.6.1 ABIs. Import raw `*_PRECOMPILE_ABI` constants from the package root, `@sei-js/precompiles/precompiles`, or `@sei-js/precompiles/viem`. Ethers factories are on `@sei-js/precompiles/ethers`. The package does not expose `VIEM_*_PRECOMPILE_ABI` aliases. It re-exports Viem's `sei` and `seiTestnet` definitions and also exports `seiLocal` (chain ID `713714`, `http://localhost:8545`). Viem 2.55.16 or newer is required. +`@sei-js/precompiles@3` is ESM-only and matches the Sei Chain v6.6.1 ABIs. Import raw `*_PRECOMPILE_ABI` constants from the package root, `@sei-js/precompiles/precompiles`, or `@sei-js/precompiles/viem`. Import the ethers factories from `@sei-js/precompiles/ethers`. The package does not expose `VIEM_*_PRECOMPILE_ABI` aliases. It re-exports the viem `sei` and `seiTestnet` definitions and also exports `seiLocal` (chain ID `713714`, `http://localhost:8545`). The package requires viem 2.55.16 or newer. ```ts import { getStakingPrecompileEthersV6Contract } from '@sei-js/precompiles/ethers'; @@ -71,9 +71,9 @@ const signer = await provider.getSigner(); -## Bank Precompile +## Bank precompile -`eth_getBalance` only returns the EVM-side SEI balance. The Bank precompile lets you query the native SEI (`usei`) bank balance for an address: +`eth_getBalance` returns only the EVM-side SEI balance. The Bank precompile lets you query the native SEI (`usei`) bank balance for an address: @@ -99,7 +99,7 @@ const balance = await bank.balance('0xYourAddress', 'usei'); -## Staking Precompile +## Staking precompile Delegate, undelegate, and query staking state: @@ -156,7 +156,7 @@ await undelegateTx.wait(); -## Governance Precompile +## Governance precompile Vote on an active governance proposal: @@ -186,7 +186,7 @@ await tx.wait(); -## Distribution Precompile +## Distribution precompile Claim staking rewards from a validator: @@ -218,9 +218,9 @@ await tx.wait(); -## JSON Precompile +## JSON precompile -Parse JSON data within EVM contracts or dApps. This is useful for processing oracle responses, NFT metadata, and structured payloads: +Parse JSON data in EVM contracts or dApps. This is useful for oracle responses, NFT metadata, and structured payloads: @@ -268,7 +268,7 @@ console.log(`${symbol}: ${price}`); -## Solo Precompile +## Solo precompile Claim a Solo migration payload. Both functions take the signed payload as `bytes` and return a boolean: @@ -296,11 +296,11 @@ await tx.wait(); -Use `claimSpecific` with the same argument shape to claim a single payload rather than everything available to the address. +To claim a single payload instead of everything available to the address, use `claimSpecific` with the same argument shape. -## Common Patterns +## Common patterns -### Error Handling +### Error handling Wrap precompile calls in try/catch and check for specific error codes: @@ -320,7 +320,7 @@ try { } ``` -### Batch Read Operations +### Batch read operations Fetch multiple precompile values in parallel: @@ -332,9 +332,9 @@ const [delegation1, delegation2, rewards] = await Promise.all([ ]); ``` -### Gas Limits +### Gas limits -Precompile calls that write state need enough gas. Use `estimateContractGas` rather than hard-coding: +Precompile calls that write state need enough gas. Use `estimateContractGas` instead of a hard-coded value: ```ts viem const gas = await client.estimateContractGas({ @@ -347,9 +347,9 @@ const gas = await client.estimateContractGas({ }); ``` -## Full Working Example +## Full working example -A Node.js script that delegates SEI and then casts a governance vote: +This Node.js script delegates SEI and then casts a governance vote: ```ts import { ethers } from 'ethers'; @@ -384,20 +384,20 @@ async function main() { main().catch(console.error); ``` -Run with: +Run the script: ```bash PRIVATE_KEY=your_key npx tsx script.ts ``` -## Next Steps +## Next steps -For full ABI reference and all available functions on each precompile: +For the full ABI reference and all available functions of each precompile, see these pages: -- [Staking Precompile →](/evm/precompiles/staking) -- [Governance Precompile →](/evm/precompiles/governance) -- [Distribution Precompile →](/evm/precompiles/distribution) -- [JSON Precompile →](/evm/precompiles/json) -- [P256 Precompile →](/evm/precompiles/p256-precompile) -- [CosmWasm Precompiles →](/evm/precompiles/cosmwasm-precompiles/example-usage) +- [Staking precompile →](/evm/precompiles/staking) +- [Governance precompile →](/evm/precompiles/governance) +- [Distribution precompile →](/evm/precompiles/distribution) +- [JSON precompile →](/evm/precompiles/json) +- [P256 precompile →](/evm/precompiles/p256-precompile) +- [CosmWasm precompiles →](/evm/precompiles/cosmwasm-precompiles/example-usage) - [Pointer contracts →](/evm/evm-parity/examples/pointer-contracts) diff --git a/evm/precompiles/governance.mdx b/evm/precompiles/governance.mdx index bc34f3f..7ad3426 100644 --- a/evm/precompiles/governance.mdx +++ b/evm/precompiles/governance.mdx @@ -6,54 +6,54 @@ keywords: ['governance precompile', 'ethers.js', 'proposal voting', 'blockchain --- **Address:** `0x0000000000000000000000000000000000001006` -The Sei governance precompile enables EVM applications to submit proposals, vote, and deposit tokens. The ABI is write-only. Query proposal state through Cosmos REST/RPC or a Sei explorer. +The Sei governance precompile lets EVM applications submit proposals, vote, and deposit tokens. The ABI is write-only. Query proposal state through Cosmos REST or RPC, or with a Sei explorer. -**What is a precompile?** A precompile is a special smart contract deployed at a fixed address by the Sei protocol itself, that exposes custom native chain logic to EVM-based applications. It acts like a regular contract from the EVM's perspective, but executes privileged, low-level logic efficiently. +**What is a precompile?** A precompile is a special smart contract that the Sei protocol itself deploys at a fixed address. It exposes custom native chain logic to EVM-based applications. To the EVM, it behaves like a regular contract, but it executes privileged, low-level logic efficiently. -## How Does the Governance Precompile Work? +## How does the governance precompile work? -The governance precompile at address `0x0000000000000000000000000000000000001006` exposes functions like `vote()`, `voteWeighted()`, `deposit()`, and `submitProposal()`. +The governance precompile at address `0x0000000000000000000000000000000000001006` exposes functions such as `vote()`, `voteWeighted()`, `deposit()`, and `submitProposal()`. -- **Direct Integration:** EVM contracts and dApps can interact with governance like any other smart contract method. -- **Native Execution:** Governance operations are executed at the chain level for maximum efficiency. -- **Seamless:** No need for separate wallet integrations. +- EVM contracts and dApps can call governance functions like any other smart contract method. +- Governance operations run natively at the chain level, which makes them efficient. +- You do not need a separate wallet integration. -## Use Cases +## Use cases -- **Voting Interfaces:** Create user-friendly governance participation tools. -- **Automated Governance:** Smart contracts that vote based on predetermined strategies. -- **Governance Aggregators:** Build platforms that aggregate and simplify governance participation. +- **Voting interfaces:** Create user-friendly tools for governance participation. +- **Automated governance:** Build smart contracts that vote based on predetermined strategies. +- **Governance aggregators:** Build platforms that aggregate and simplify governance participation. -## Sei Governance Overview +## Sei governance overview -Sei governance operates on a structured timeline with specific parameters: +Sei governance follows a structured timeline with specific parameters: -### Governance Process +### Governance process -1. **Proposal Submission:** Submit proposal with minimum 3,500 SEI deposit -2. **Deposit Period:** 2 days to accumulate minimum deposit or reach expedited threshold -3. **Voting Period:** 3 days (1 day for expedited) of active voting once minimum deposit is met -4. **Tallying:** Results calculated based on quorum and voting thresholds +1. **Proposal submission:** Submit a proposal with a minimum deposit of 3,500 SEI. +2. **Deposit period:** The proposal has 2 days to accumulate the minimum deposit or reach the expedited threshold. +3. **Voting period:** When the proposal meets the minimum deposit, voting is active for 3 days (1 day for expedited proposals). +4. **Tallying:** The results are calculated from the quorum and voting thresholds. - To find out all about the governance process on Sei, go to the [governance explainer](/learn/general-governance). + To learn more about the governance process on Sei, read the [governance explainer](/learn/general-governance). -**Critical Mainnet Considerations:** +**Critical Sei Mainnet considerations:** -- **High Stakes:** Mainnet governance involves real SEI tokens and binding decisions -- **Minimum Deposit:** 3500 SEI minimum, 7000 SEI for expedited -- **Deposit Risk:** Deposits will be burned if your proposal receives >33.4% NoWithVeto votes -- **Voting Power Required:** Must stake SEI with validators to participate -- **Time Limits:** Strict 2-day deposit period and 3-day voting period -- **Real Impact:** Successful proposals can change network parameters +- **High stakes:** Governance on Sei Mainnet involves real SEI tokens and binding decisions. +- **Minimum deposit:** 3,500 SEI, or 7,000 SEI for an expedited proposal. +- **Deposit risk:** If your proposal receives more than 33.4% NoWithVeto votes, its deposits are burned. +- **Voting power required:** You must stake SEI with validators to participate. +- **Time limits:** The 2-day deposit period and the 3-day voting period are strict. +- **Real impact:** Successful proposals can change network parameters. ## Functions -The governance precompile exposes the following functions: +The governance precompile exposes these functions: -### Transaction Functions +### Transaction functions ```solidity /// Cast a vote on the specified proposal. @@ -101,22 +101,22 @@ function submitProposal( ) payable external returns (uint64 proposalID); ``` -## Using the Contract +## Using the contract ### Setup #### Prerequisites -Before getting started, ensure you have: +Before you start, make sure that you have: -- **Node.js** (v18 or higher) -- **npm** or **yarn** package manager -- **MetaMask** or compatible EVM wallet configured for Sei Mainnet -- **SEI tokens** for gas and governance deposits (minimum 3,500 SEI for proposals) +- Node.js (v18 or higher) +- The npm or yarn package manager +- MetaMask or another compatible EVM wallet, configured for Sei Mainnet +- SEI tokens for gas and governance deposits (a minimum of 3,500 SEI to submit a proposal) -#### Install Dependencies +#### Install dependencies -Install the required packages for interacting with Sei precompiles: +Install the required packages to interact with Sei precompiles: ```bash # Install ethers.js for smart contract interactions @@ -129,7 +129,7 @@ npm install @sei-js/precompiles@^3 npm install dotenv ``` -#### Import Precompile Components +#### Import precompile components ```typescript // Import Governance precompile address and ABI @@ -138,19 +138,19 @@ import { GOVERNANCE_PRECOMPILE_ABI, GOVERNANCE_PRECOMPILE_ADDRESS } from '@sei-j import { ethers } from 'ethers'; ``` -**Precompile Address:** The governance precompile is deployed at `0x0000000000000000000000000000000000001006` +**Precompile address:** The governance precompile is deployed at `0x0000000000000000000000000000000000001006`. -#### Get SEI Tokens +#### Get SEI tokens -Purchase SEI tokens from supported exchanges: +Buy SEI tokens from supported exchanges: -- **Centralized Exchanges:** Binance, Coinbase, KuCoin, Gate.io -- **Decentralized Exchanges:** Astroport, Dragonswap (on Sei) -- **Bridge Options:** Various cross-chain bridges support SEI +- **Centralized exchanges:** Binance, Coinbase, KuCoin, Gate.io +- **Decentralized exchanges:** Astroport, Dragonswap (on Sei) +- **Bridge options:** Several cross-chain bridges support SEI -**Minimum Requirements:** You need at least 3,500 SEI to submit a governance proposal, plus additional tokens for gas and potential additional deposits. +**Minimum requirements:** You need at least 3,500 SEI to submit a governance proposal. You also need more SEI for gas and for any extra deposits. -### Contract Initialization +### Contract initialization Set up your provider, signer, and contract instance: @@ -168,31 +168,31 @@ const signer = new ethers.Wallet('YOUR_PRIVATE_KEY', provider); const governance = new ethers.Contract(GOVERNANCE_PRECOMPILE_ADDRESS, GOVERNANCE_PRECOMPILE_ABI, signer); ``` -## Vote Options +## Vote options -The governance system uses the following vote options: +The governance system uses these vote options: | Option | Value | Description | Impact | | --- | --- | --- | --- | -| Yes | 1 | Vote in favor of the proposal | Proposal passes if threshold met | +| Yes | 1 | Vote in favor of the proposal | Proposal passes if the threshold is met | | Abstain | 2 | Abstain from voting | Counts toward quorum only | -| No | 3 | Vote against the proposal | Opposes proposal | -| NoWithVeto | 4 | Vote against with veto | Opposes Proposal & burns deposit if > 33.4% | +| No | 3 | Vote against the proposal | Opposes the proposal | +| NoWithVeto | 4 | Vote against with veto | Opposes the proposal and burns the deposit if > 33.4% | -### Voting Power +### Voting power -Your voting power is determined by: +Your voting power depends on: -- **Staked SEI:** Amount of SEI you have staked with validators +- **Staked SEI:** The amount of SEI that you staked with validators - **Delegation:** SEI delegated to validators counts toward voting power -- **Liquid SEI:** Unstaked SEI does not provide voting power +- **Liquid SEI:** Unstaked SEI does not give voting power -**Important:** Only staked SEI provides voting power. You must delegate your tokens to validators to participate in governance voting. +Only staked SEI gives voting power. To vote in governance, you must delegate your tokens to validators. -## Validation Functions +## Validation functions -Before making governance transactions, use these helper functions to validate inputs: +Before you send governance transactions, use these helper functions to validate the inputs: ```typescript // Validate vote option @@ -246,17 +246,17 @@ async function checkVotingPower(userAddress: string): Promise { } ``` -## Step-by-Step Guide: Using the Governance Precompile +## Step-by-step guide: Using the governance precompile -### Submit a Proposal +### Submit a proposal -**Important Deposit Requirements:** +**Deposit requirements:** -- **Minimum deposit:** 3,500 SEI required for proposal to enter voting period -- **Expedited processing:** 7,000 SEI if the voting period should only be 1 day long -- **Deposit period:** 2 days to meet minimum or proposal fails and deposits are burned -- **Multiple deposits:** Anyone can contribute to reach the minimum threshold +- **Minimum deposit:** A proposal needs 3,500 SEI to enter the voting period. +- **Expedited processing:** A proposal needs 7,000 SEI for a voting period of only 1 day. +- **Deposit period:** The proposal has 2 days to meet the minimum. If it does not, the proposal fails and the deposits are burned. +- **Multiple deposits:** Anyone can contribute to reach the minimum threshold. @@ -383,7 +383,7 @@ const depositAmount = ethers.parseUnits('4000', 18); // 4,000 SEI deposit await submitGovernanceProposal(proposalTitle, proposalDescription, depositAmount, false); ``` -### Vote on a Proposal +### Vote on a proposal ```typescript // Simple voting with comprehensive validation @@ -448,9 +448,9 @@ await voteOnProposal(proposalID, 1); await voteOnProposal(proposalID, 4); ``` -### Weighted Voting +### Weighted voting -**Critical Requirement:** Weighted vote options MUST sum to exactly 1.0 or the transaction will fail. The Sei governance module enforces this strictly - even small rounding errors will cause rejection. +**Critical requirement:** Make sure that the option weights in a weighted vote sum to exactly 1.0. If they do not, the transaction fails. The Sei governance module enforces this strictly. Even small rounding errors cause a rejection. ```typescript // Weighted voting with comprehensive validation @@ -562,7 +562,7 @@ const badVote = [ // await castWeightedVote(proposalID, badVote); // Don't run this! ``` -### Deposit to a Proposal +### Deposit to a proposal ```typescript // Add deposit to help proposal reach minimum threshold @@ -617,9 +617,9 @@ const additionalDeposit = ethers.parseUnits('1000', 18); // 1,000 SEI await addDepositToProposal(proposalID, additionalDeposit); ``` -## Complete Integration Example +## Complete integration example -Create a comprehensive governance interaction script: +Create a script that interacts with the governance precompile: ```javascript title="governance-mainnet-demo.mjs" import { ethers } from 'ethers'; @@ -872,7 +872,7 @@ This is a test proposal. Vote according to your preference to test the system.`, main().catch(console.error); ``` -### Running the Example +### Running the example 1. **Create a new directory and initialize npm:** @@ -895,12 +895,12 @@ PRIVATE_KEY=your_private_key_here ``` 4. **Create the demo file:** - Copy the complete integration example above into `governance-mainnet-demo.mjs` + Copy the complete integration example above into `governance-mainnet-demo.mjs`. -5. **Ensure you have sufficient SEI:** +5. **Make sure that you have enough SEI:** - - Minimum 3,500 SEI for proposal deposit - - Additional SEI for gas and optional additional deposits + - A minimum of 3,500 SEI for the proposal deposit + - More SEI for gas and for optional extra deposits - Staked SEI for voting power 6. **Run the script:** @@ -909,7 +909,7 @@ PRIVATE_KEY=your_private_key_here node governance-mainnet-demo.mjs ``` -### Expected Output +### Expected output ``` 🌐 Connecting to Sei Mainnet... @@ -960,9 +960,9 @@ node governance-mainnet-demo.mjs ## Troubleshooting -### Common Issues and Solutions +### Common issues and solutions -#### Insufficient Deposit +#### Insufficient deposit ```typescript // Check minimum deposit requirement based on proposal type @@ -981,7 +981,7 @@ function checkDepositRequirement(depositAmount: bigint, isExpedited: boolean = f } ``` -#### No Voting Power +#### No voting power ```typescript // Check if user has staked SEI for voting power @@ -998,7 +998,7 @@ async function checkVotingEligibility(userAddress: string): Promise { } ``` -#### Invalid Vote Option +#### Invalid vote option ```typescript // Validate vote option with descriptive error @@ -1020,7 +1020,7 @@ function validateVoteOptionWithDescription(option: number): void { } ``` -#### Weighted Vote Validation +#### Weighted vote validation ```typescript // Comprehensive weighted vote validation with helpful errors @@ -1082,26 +1082,26 @@ function validateWeightedVoteComprehensive(options: Array<{ option: number; weig } ``` -### Error Code Reference +### Error code reference | Error | Cause | Solution | | --- | --- | --- | -| `proposal does not exist` | Invalid proposal ID or proposal expired | Verify proposal ID and ensure voting period is still active | -| `inactive proposal` | Voting or deposit period has ended | Check proposal status and timeline | -| `insufficient deposit` | Deposit below 3,500 SEI | Increase deposit to the minimum required amount | +| `proposal does not exist` | Invalid proposal ID or proposal expired | Verify the proposal ID and make sure that the voting period is still active | +| `inactive proposal` | Voting or deposit period has ended | Check the proposal status and timeline | +| `insufficient deposit` | Deposit below 3,500 SEI | Increase the deposit to the minimum required amount | | `invalid vote option` | Vote option not 1-4 | Use a valid option (1-Yes, 2-Abstain, 3-No, 4-NoWithVeto) | | `already voted` | Address has already voted on this proposal | Each address can vote only once per proposal | -| `weights must sum to 1` | Weighted votes don’t sum to 1.0 | **CRITICAL —** adjust weights so they total exactly 1.0 | +| `weights must sum to 1` | Weighted votes do not sum to 1.0 | **Critical:** Adjust the weights so that they total exactly 1.0 | | `insufficient voting power` | No staked SEI | Delegate SEI to validators to gain voting power | -| `deposit period ended` | Deposits no longer accepted | Deposit period closes 2 days after submission | +| `deposit period ended` | Deposits no longer accepted | The deposit period closes 2 days after submission | -**Need Help?** If you encounter issues: +**Need help?** If you have problems, use these resources: - **Discord:** [Sei Community Discord](https://discord.gg/sei) -- **GitHub:** [Sei Protocol Repository](https://github.com/sei-protocol/sei-chain) -- **Explorer:** [View Proposals on Sei Explorer](https://sei.explorers.guru/proposals) +- **GitHub:** [Sei Protocol repository](https://github.com/sei-protocol/sei-chain) +- **Explorer:** [View proposals on Sei Explorer](https://sei.explorers.guru/proposals) diff --git a/evm/precompiles/json.mdx b/evm/precompiles/json.mdx index 210d2f1..e336b87 100644 --- a/evm/precompiles/json.mdx +++ b/evm/precompiles/json.mdx @@ -6,31 +6,31 @@ keywords: ['json precompile', 'ethers.js', 'json parsing', 'smart contract data' --- **Address:** `0x0000000000000000000000000000000000001003` -The Sei JSON precompile allows EVM applications to efficiently parse and query JSON data directly within smart contracts. This enables complex data handling capabilities that are not natively available in Solidity, making it easier to work with structured data from external sources or APIs. +The Sei JSON precompile lets EVM applications parse and query JSON data efficiently, directly within smart contracts. Solidity does not support this kind of complex data handling natively. The precompile makes it easier to work with structured data from external sources or APIs. -**What is a precompile?** A precompile is a special smart contract deployed at a fixed address by the Sei protocol itself, that exposes custom native chain logic to EVM-based applications. It acts like a regular contract from the EVM's perspective, but executes privileged, low-level logic efficiently. +**What is a precompile?** A precompile is a special smart contract that the Sei protocol itself deploys at a fixed address. It exposes custom native chain logic to EVM-based applications. To the EVM, it behaves like a regular contract, but it executes privileged, low-level logic efficiently. -## How Does the JSON Precompile Work? +## How does the JSON precompile work? The JSON precompile at address `0x0000000000000000000000000000000000001003` exposes `extractAsBytes()`, `extractAsBytesList()`, `extractAsBytesFromArray()`, and `extractAsUint256()`. -- **Direct Integration:** EVM contracts and dApps can parse JSON data like any other smart contract method. -- **Native Execution:** JSON parsing is executed at the native level for maximum efficiency. -- **Seamless Bridge:** No need for complex workarounds or external libraries for JSON handling. +- EVM contracts and dApps can call the JSON parsing functions directly, like any other smart contract method. +- JSON parsing runs at the native level, which makes it efficient. +- You do not need complex workarounds or external libraries to handle JSON. -## Use Cases +## Use cases -- **Oracle Integration:** Parse complex oracle responses containing multiple data points. -- **DeFi Applications:** Process structured price feeds and market data. +- **Oracle integration:** Parse complex oracle responses that contain multiple data points. +- **DeFi applications:** Process structured price feeds and market data. - **Gaming:** Handle complex game state and player data stored in JSON format. -- **Cross-Chain Communication:** Parse messages and data from other chains. -- **NFT Metadata:** Extract and manipulate NFT metadata stored in JSON format. +- **Cross-chain communication:** Parse messages and data from other chains. +- **NFT metadata:** Extract and manipulate NFT metadata stored in JSON format. ## Functions -The JSON precompile exposes the following functions: +The JSON precompile exposes these functions: -### Query Functions +### Query functions ```solidity /// Extracts data as bytes from the input using the specified key. @@ -70,22 +70,22 @@ function extractAsUint256( ) external view returns (uint256 response); ``` -## Using the Precompile +## Using the precompile ### Setup #### Prerequisites -Before getting started, ensure you have: +Before you start, make sure that you have: -- **Node.js** (v18 or higher) -- **npm** or **yarn** package manager -- **MetaMask** or compatible EVM wallet configured for Sei Mainnet -- **SEI tokens** for gas +- Node.js (v18 or higher) +- The npm or yarn package manager +- MetaMask or another compatible EVM wallet, configured for Sei Mainnet +- SEI tokens for gas -#### Install Dependencies +#### Install dependencies -Install the required packages for interacting with Sei precompiles: +Install the required packages to interact with Sei precompiles: ```bash # Install ethers.js for smart contract interactions @@ -98,7 +98,7 @@ npm install @sei-js/precompiles@^3 npm install dotenv ``` -#### Import Precompile Components +#### Import precompile components ```typescript // Import JSON precompile address and ABI @@ -107,9 +107,9 @@ import { JSON_PRECOMPILE_ABI, JSON_PRECOMPILE_ADDRESS } from '@sei-js/precompile import { ethers } from 'ethers'; ``` -**Precompile Address:** The JSON precompile is deployed at `0x0000000000000000000000000000000000001003` +**Precompile address:** The JSON precompile is deployed at `0x0000000000000000000000000000000000001003`. -### Contract Initialization +### Contract initialization Set up your provider, signer, and contract instance: @@ -127,24 +127,24 @@ const signer = new ethers.Wallet(process.env.PRIVATE_KEY, provider); const jsonPrecompile = new ethers.Contract(JSON_PRECOMPILE_ADDRESS, JSON_PRECOMPILE_ABI, signer); ``` -## Data Type Handling +## Data type handling The JSON precompile has specific limitations for different data types: -### Supported Data Types +### Supported data types | Function | Supports | Limitations | | --- | --- | --- | -| extractAsBytes | Strings, Objects, Arrays | Returns raw bytes - needs conversion | +| extractAsBytes | Strings, objects, arrays | Returns raw bytes that need conversion | | extractAsUint256 | Integers only | No decimals, booleans, or negative numbers | -| extractAsBytesList | Arrays of strings/objects | Each element returned as bytes | +| extractAsBytesList | Arrays of strings/objects | Returns each element as bytes | -**Value Length Limit:** `extractAsUint256` rejects value strings longer than 100 characters. If the numeric string extracted for the given key exceeds 100 characters, the call fails with `value string too long`. Ensure the numeric values you pass stay within this limit. +**Value length limit:** Make sure that the numeric values you pass stay within 100 characters. `extractAsUint256` rejects value strings longer than 100 characters. If the numeric string extracted for the given key is longer than this, the call fails with `value string too long`. -### Data Type Conversion Strategies +### Data type conversion strategies ```typescript // For decimal numbers - store as integers with known precision @@ -164,9 +164,9 @@ const userString = ethers.toUtf8String(userBytes); const userObject = JSON.parse(userString); ``` -## Error Handling Utilities +## Error handling utilities -Create comprehensive error handling for all extraction functions: +Add error handling to all extraction functions: ```typescript // Safe extraction for bytes data @@ -206,9 +206,9 @@ async function safeExtractBytesList(jsonPrecompile: ethers.Contract, data: any, } ``` -## Step-by-Step Guide: Using the JSON Precompile +## Step-by-step guide: Using the JSON precompile -### Extract String Data +### Extract string data ```typescript // JSON data with string values @@ -229,7 +229,7 @@ try { } ``` -### Extract Numeric Data +### Extract numeric data ```typescript // JSON data with numbers (integers only) @@ -247,7 +247,7 @@ const actualRate = Number(rate) / 100; // Convert to 2.75 console.log('Rate:', actualRate); ``` -### Extract Array Data +### Extract array data ```typescript // JSON data with array @@ -266,9 +266,9 @@ const valuesArray = JSON.parse(valuesString); console.log('Mixed values:', valuesArray); // Output: [42, "test", 100] ``` -### Extract Nested Data +### Extract nested data -**Important:** The JSON precompile does not support dot notation for nested objects. Instead, extract the parent object and parse it manually. +Extract the parent object and parse it manually. The JSON precompile does not support dot notation for nested objects. ```typescript // For nested data, extract the parent object first @@ -299,9 +299,9 @@ const walletData = JSON.parse(ethers.toUtf8String(walletBytes)); console.log('Wallet data:', walletData); // Output: { balance: 1000, currency: "SEI" } ``` -## Complete Integration Example +## Complete integration example -Create a comprehensive JSON parsing application for mainnet: +Create a complete JSON parsing application for Sei Mainnet: ```javascript title="json-precompile-mainnet.mjs" // json-precompile-mainnet.mjs @@ -502,7 +502,7 @@ async function main() { main().catch(console.error); ``` -### Running the Mainnet Example +### Running the mainnet example 1. **Create a new directory and initialize npm:** @@ -524,14 +524,14 @@ npm install ethers @sei-js/precompiles@^3 dotenv PRIVATE_KEY=your_private_key_here ``` -**Security Note:** Never commit private keys to version control! The `.env` file should be added to your `.gitignore`. +Never commit private keys to version control. Add the `.env` file to your `.gitignore`. 4. **Create the demo file:** - Copy the complete integration example above into `json-precompile-mainnet.mjs` + Copy the complete integration example above into `json-precompile-mainnet.mjs`. -5. **Ensure you have SEI tokens:** +5. **Make sure that you have SEI tokens:** - - SEI for gas (small amounts needed for view functions) + - SEI for gas (view functions need only small amounts) 6. **Run the script:** @@ -539,7 +539,7 @@ PRIVATE_KEY=your_private_key_here node json-precompile-mainnet.mjs ``` -### Expected Output +### Expected output ``` 🌐 Connecting to Sei Mainnet... @@ -615,9 +615,9 @@ node json-precompile-mainnet.mjs 🎉 === JSON Precompile Demo Completed Successfully! === ``` -## Advanced Usage Examples +## Advanced usage examples -### Oracle Price Feed Integration +### Oracle price feed integration ```typescript // Advanced oracle integration with comprehensive error handling @@ -669,9 +669,9 @@ class SeiPriceOracle { ## Troubleshooting -### Common Issues and Solutions +### Common issues and solutions -#### Key Not Found +#### Key not found ```typescript // Comprehensive error handling for missing keys @@ -693,30 +693,30 @@ async function handleMissingKeys(jsonPrecompile: ethers.Contract, data: any) { } ``` -### Error Code Reference +### Error code reference | Error | Cause | Solution | | --- | --- | --- | -| `key not found` | Specified key doesn't exist in JSON | Verify key path and JSON structure | -| `invalid JSON format` | Malformed JSON input | Use `JSON.stringify()` to ensure valid format | -| `execution reverted` | Gas limit too low | Increase gas limit based on data complexity | -| `invalid integer` | Non-numeric value for `extractAsUint256` | Ensure the value is a valid integer | +| `key not found` | The specified key does not exist in the JSON | Verify the key path and JSON structure | +| `invalid JSON format` | Malformed JSON input | Use `JSON.stringify()` to make sure the format is valid | +| `execution reverted` | Gas limit too low | Increase the gas limit based on data complexity | +| `invalid integer` | Non-numeric value for `extractAsUint256` | Make sure that the value is a valid integer | | `out of gas` | Insufficient gas for large JSON | Use `calculateGasLimit()` for dynamic estimation | -## Key Considerations and Tricks +## Key considerations and tricks -- **Integers Only:** `extractAsUint256` only handles integers - no decimals, booleans, or negative numbers -- **Decimal Handling:** Store decimal numbers as integers with known precision (e.g., 275 for 2.75 with 2 decimal places) -- **Boolean Values:** Use 0/1 integers to represent false/true -- **Key Paths:** Extract parent objects first, then parse manually - dot notation may not be supported +- **Integers only:** `extractAsUint256` handles only integers. It does not handle decimals, booleans, or negative numbers. +- **Decimal handling:** Store decimal numbers as integers with known precision. For example, use 275 for 2.75 with 2 decimal places. +- **Boolean values:** Use the integer 0 for false and 1 for true. +- **Key paths:** Extract parent objects first, then parse them manually. Dot notation may not be supported. - **Arrays:** Object-keyed arrays use `extractAsBytesList()`. JSON arrays by index use `extractAsBytesFromArray()`. -- **Gas Costs:** Large JSON objects require higher gas limits -- **Encoding:** Always use UTF-8 encoding with `ethers.toUtf8Bytes()` -- **Error Handling:** Always implement fallback values for production applications +- **Gas costs:** Large JSON objects need higher gas limits. +- **Encoding:** Always use UTF-8 encoding with `ethers.toUtf8Bytes()`. +- **Error handling:** Always implement fallback values for production applications. -**Need Help?** If you encounter issues not covered here, check the [Sei Discord](https://discord.gg/sei) or [GitHub repository](https://github.com/sei-protocol/sei-chain) for community support. +**Need help?** If you have a problem that this page does not cover, look for community support in the [Sei Discord](https://discord.gg/sei) or the [GitHub repository](https://github.com/sei-protocol/sei-chain). diff --git a/evm/precompiles/oracle.mdx b/evm/precompiles/oracle.mdx index c56efa9..6177ef0 100644 --- a/evm/precompiles/oracle.mdx +++ b/evm/precompiles/oracle.mdx @@ -6,4 +6,4 @@ keywords: ['oracle precompile', 'retired', 'oracle migration', 'chainlink', 'pyt --- **Address:** `0x0000000000000000000000000000000000001008` -**Retired as of v6.4.0:** The native Sei Oracle precompile has been retired. On-chain oracle data queries are disabled — calling `getExchangeRates` or `getOracleTwaps` now reverts with the error `oracle precompile is retired; oracle data queries are disabled`. You must migrate to one of the third-party oracle providers, such as [Chainlink](/evm/oracles/chainlink), [Pyth](/evm/oracles/pyth-network), [Redstone](/evm/oracles/redstone), or [API3](/evm/oracles/api3). +**Retired as of v6.4.0:** Migrate to a third-party oracle provider, such as [Chainlink](/evm/oracles/chainlink), [Pyth](/evm/oracles/pyth-network), [RedStone](/evm/oracles/redstone), or [API3](/evm/oracles/api3). The native Sei Oracle precompile is retired, and on-chain oracle data queries are disabled. A call to `getExchangeRates` or `getOracleTwaps` reverts with the error `oracle precompile is retired; oracle data queries are disabled`. diff --git a/evm/precompiles/p256-precompile.mdx b/evm/precompiles/p256-precompile.mdx index 0005063..3b571ef 100644 --- a/evm/precompiles/p256-precompile.mdx +++ b/evm/precompiles/p256-precompile.mdx @@ -4,21 +4,21 @@ sidebarTitle: 'P256' description: 'Use the P256 precompile to verify secp256r1/P-256 signatures directly from EVM smart contracts, enabling efficient passkey-based authentication and signature verification.' keywords: ['p256 precompile', 'secp256r1', 'signature verification', 'passkey', 'webauthn', 'secure enclave'] --- -**Address**: `0x0000000000000000000000000000000000001011` +**Address:** `0x0000000000000000000000000000000000001011` -This is the implementation of [RIP-7212](https://github.com/ethereum/RIPs/blob/master/RIPS/rip-7212.md), which provides a precompiled contract for verifying signatures in the `secp256r1` or `P-256` elliptic curve. +This precompile implements [RIP-7212](https://github.com/ethereum/RIPs/blob/master/RIPS/rip-7212.md), which defines a precompiled contract to verify signatures on the `secp256r1` or `P-256` elliptic curve. ## Overview -The P256 precompile enables efficient signature verification for the `secp256r1` curve, which is widely used in modern security systems including: +The P256 precompile verifies signatures on the `secp256r1` curve efficiently. Many modern security systems use this curve, including: - Apple's Secure Enclave -- WebAuthn/FIDO2 +- WebAuthn and FIDO2 - Android Keychain - Various hardware security modules (HSMs) -- PassKeys +- Passkeys -This precompile implementation is significantly more gas efficient (up to 60x) compared to Solidity-based implementations. +This precompile implementation is significantly more gas efficient than Solidity-based implementations (up to 60x). ## Interface @@ -37,9 +37,9 @@ interface IP256VERIFY { } ``` -## Implementation Library +## Implementation library -Here's a complete implementation of the P256 library that provides a convenient wrapper around the precompile: +This is a complete implementation of the P256 library, a convenient wrapper around the precompile: ```solidity // SPDX-License-Identifier: MIT @@ -79,9 +79,9 @@ library P256 { } ``` -## Basic Usage +## Basic usage -### Using the P256 Library +### Using the P256 library ```solidity // SPDX-License-Identifier: MIT @@ -103,7 +103,7 @@ contract P256Example { } ``` -### Direct Precompile Usage +### Direct precompile usage For more control, you can call the precompile directly: @@ -142,15 +142,15 @@ contract P256Verifier { } ``` -## Signature Format +## Signature format -The signature verification requires the following components: +Signature verification requires these components: - `digest`: 32 bytes of the signed data hash - `signature`: Contains the r and s components of the signature - `publicKey`: Contains the x and y coordinates of the public key -The precompile expects these components to be encoded in a specific format: +The precompile expects these components encoded in this format: - First 32 bytes: message hash - Next 32 bytes: `r` component of the signature @@ -160,16 +160,16 @@ The precompile expects these components to be encoded in a specific format: Total length: 160 bytes -## Gas Costs +## Gas costs -The precompile is highly gas efficient compared to Solidity implementations. The exact gas cost per byte of verified data is set to `GasCostPerByte = 300`, which gives us: +The precompile is much more gas efficient than Solidity implementations. The exact gas cost per byte of verified data is set to `GasCostPerByte = 300`. The results are: -- **Total Cost**: 300 × 160 = **48,000 gas** per verification +- **Total cost**: 300 × 160 = **48,000 gas** per verification - **Efficiency**: Up to 60x more efficient than pure Solidity implementations -## Real-World Use Cases +## Real-world use cases -### WebAuthn/PassKeys Authentication +### WebAuthn/passkeys authentication ```solidity pragma solidity ^0.8.0; @@ -215,7 +215,7 @@ contract WebAuthnAuth { } ``` -### Apple Secure Enclave Integration +### Apple Secure Enclave integration ```solidity contract SecureEnclaveAuth { @@ -254,7 +254,7 @@ contract SecureEnclaveAuth { } ``` -### Multi-Signature with Hardware Keys +### Multi-signature with hardware keys ```solidity contract HardwareMultiSig { @@ -303,11 +303,11 @@ contract HardwareMultiSig { } ``` -## Security Considerations +## Security considerations -**Important**: Always validate public keys and signature components before verification to prevent invalid curve point attacks. +Always validate public keys and signature components before verification. This prevents invalid curve point attacks. -### Public Key Validation +### Public key validation ```solidity function isValidPublicKey(bytes32 x, bytes32 y) internal pure returns (bool) { @@ -320,9 +320,9 @@ function isValidPublicKey(bytes32 x, bytes32 y) internal pure returns (bool) { } ``` -### Signature Malleability +### Signature malleability -P256 signatures can be malleable. If your application requires unique signatures, implement additional checks: +P256 signatures can be malleable. If your application requires unique signatures, implement more checks: ```solidity function isLowS(bytes32 s) internal pure returns (bool) { @@ -332,9 +332,9 @@ function isLowS(bytes32 s) internal pure returns (bool) { } ``` -## JavaScript Integration +## JavaScript integration -### Preparing Input Data +### Preparing input data ```javascript // Example: Preparing P256 verification input (ethers v6) @@ -368,14 +368,14 @@ async function verifyP256Signature(provider, messageHash, signature, publicKey) } ``` -## Error Handling +## Error handling -The P256 precompile returns no data on failure. Because `verify` is declared as returning `bytes`, a high-level Solidity interface call reverts when it tries to decode that empty return data — always use a low-level `staticcall` (as in the examples above) so invalid signatures resolve to `false` instead of reverting. Common failure cases include: +The P256 precompile returns no data on failure. Because `verify` is declared to return `bytes`, a high-level Solidity interface call reverts when it tries to decode the empty return data. Always use a low-level `staticcall`, as the examples above do. Invalid signatures then resolve to `false` instead of reverting. Common failure cases include: -1. **Invalid Input Length**: Input must be exactly 160 bytes -2. **Invalid Public Key**: Point not on the P256 curve -3. **Invalid Signature**: r or s values out of valid range -4. **Verification Failure**: Signature doesn't match message and public key +1. **Invalid input length**: The input must be exactly 160 bytes. +2. **Invalid public key**: The point is not on the P256 curve. +3. **Invalid signature**: The r or s values are out of the valid range. +4. **Verification failure**: The signature does not match the message and public key. ```solidity function safeVerifyP256( @@ -409,7 +409,7 @@ function safeVerifyP256( ## Testing -### Unit Tests +### Unit tests ```solidity contract P256Test { @@ -434,11 +434,11 @@ contract P256Test { } ``` -## Performance Considerations +## Performance considerations -- **Gas Efficiency**: 48,000 gas per verification vs 2M+ gas for Solidity implementations -- **Batch Operations**: Consider batching multiple verifications in a single transaction +- **Gas efficiency**: 48,000 gas per verification, compared to 2M gas or more for Solidity implementations +- **Batch operations**: Consider batching multiple verifications in a single transaction - **Caching**: Cache public keys on-chain to reduce calldata for repeated verifications -- **Hardware Integration**: Particularly efficient for applications using hardware-backed keys +- **Hardware integration**: Particularly efficient for applications that use hardware-backed keys -View the complete P256 precompile ABI in the [Sei Chain v6.6.1 snapshot](https://github.com/sei-protocol/sei-chain/blob/v6.6.1/precompiles/p256/legacy/v66/abi.json), or browse the [implementation source](https://github.com/sei-protocol/sei-chain/tree/v6.6.1/precompiles/p256). +View the complete P256 precompile ABI in the [sei-chain v6.6.1 snapshot](https://github.com/sei-protocol/sei-chain/blob/v6.6.1/precompiles/p256/legacy/v66/abi.json), or browse the [implementation source](https://github.com/sei-protocol/sei-chain/tree/v6.6.1/precompiles/p256). diff --git a/evm/precompiles/staking.mdx b/evm/precompiles/staking.mdx index 1e6cab6..8d6576e 100644 --- a/evm/precompiles/staking.mdx +++ b/evm/precompiles/staking.mdx @@ -8,41 +8,41 @@ keywords: ['staking precompile', 'ethers.js', 'delegation', 'validators', 'staki **Address:** `0x0000000000000000000000000000000000001005` -The Sei staking precompile allows EVM applications to interact directly with Sei's native staking module through standard smart contract calls. This enables delegation, undelegation, redelegation, validator management, and staking queries directly from your dApps without needing separate Cosmos SDK integration. +The Sei staking precompile lets EVM applications interact directly with the Sei native staking module through standard smart contract calls. Your dApps can use it for delegation, undelegation, redelegation, validator management, and staking queries. They do not need a separate Cosmos SDK integration. - **What is a precompile?** A precompile is a special smart contract deployed at a fixed address by the Sei protocol itself, that exposes custom native chain logic to EVM-based applications. It acts like a regular contract from the EVM's perspective, but executes privileged, low-level logic efficiently. + **What is a precompile?** A precompile is a special smart contract that the Sei protocol itself deploys at a fixed address. It exposes custom native chain logic to EVM-based applications. To the EVM, it behaves like a regular contract, but it executes privileged, low-level logic efficiently. -## How Does the Staking Precompile Work? +## How does the staking precompile work? -The staking precompile at address `0x0000000000000000000000000000000000001005` exposes a comprehensive set of staking functions including `delegate()`, `undelegate()`, `redelegate()`, `createValidator()`, `editValidator()`, and various query functions like `validators()`, `delegatorDelegations()`, `pool()`, and `params()`. +The staking precompile at address `0x0000000000000000000000000000000000001005` exposes transaction functions such as `delegate()`, `undelegate()`, `redelegate()`, `createValidator()`, and `editValidator()`. It also exposes query functions such as `validators()`, `delegatorDelegations()`, `pool()`, and `params()`. -- **Direct Integration:** EVM contracts and dApps can call staking functions like any other smart contract method. -- **Native Execution:** Operations are executed at the Cosmos SDK level for maximum efficiency and security. -- **Seamless Bridge:** No need for separate wallet integrations or complex cross-chain interactions. -- **Event Emission:** Staking operations emit `Delegate`, `Undelegate`, `Redelegate`, `DelegationRewardsWithdrawn`, `ValidatorCreated`, and `ValidatorEdited`. +- EVM contracts and dApps can call staking functions like any other smart contract method. +- Operations run at the Cosmos SDK level, which makes them efficient and secure. +- You do not need separate wallet integrations or complex cross-chain interactions. +- Staking operations emit `Delegate`, `Undelegate`, `Redelegate`, `DelegationRewardsWithdrawn`, `ValidatorCreated`, and `ValidatorEdited` events. -## Use Cases +## Use cases -- **DeFi Integration:** Build liquid staking protocols and yield farming strategies. -- **Delegation Services:** Create user-friendly interfaces for staking operations. -- **Portfolio Management:** Automate staking strategies and delegation rebalancing. -- **Validator Management:** Create and manage validators programmatically. +- **DeFi integration:** Build liquid staking protocols and yield farming strategies. +- **Delegation services:** Create user-friendly interfaces for staking operations. +- **Portfolio management:** Automate staking strategies and delegation rebalancing. +- **Validator management:** Create and manage validators programmatically. -## What You'll Learn in This Guide +## What you'll learn in this guide -By the end of this guide, you'll be able to: +This guide shows how to: -- **Integrate Staking Operations** - Call delegation, undelegation, and redelegation functions directly from your EVM contracts and dApps -- **Handle Decimal Precision** - Master the critical precision patterns for different operations to avoid common formatting errors -- **Create and Manage Validators** - Create new validators and edit their parameters programmatically -- **Query Staking State** - Use the comprehensive query functions to fetch validators, delegations, unbonding info, pool statistics, and staking parameters -- **Listen for Staking Events** - Track staking operations using emitted events for indexing and notifications -- **Build Portfolio Tools** - Implement automated rebalancing and delegation tracking for staking management applications -- **Navigate Staking Risks** - Understand unbonding periods, slashing mechanics, and validator selection for safe staking operations +- Call delegation, undelegation, and redelegation functions directly from your EVM contracts and dApps +- Use the correct decimal precision for each operation, to avoid common formatting errors +- Create validators and edit their parameters programmatically +- Use the query functions to fetch validators, delegations, unbonding information, pool statistics, and staking parameters +- Listen for staking events, to track staking operations for indexing and notifications +- Build portfolio tools for staking management applications, with automated rebalancing and delegation tracking +- Understand unbonding periods, slashing mechanics, and validator selection, so that you can stake safely ## Events -The staking precompile emits the following events: +The staking precompile emits these events: ```solidity /** @@ -116,9 +116,9 @@ event ValidatorEdited( ); ``` -### Listening for Events +### Listening for events -You can listen for these events in your dApp to track staking operations: +Your dApp can listen for these events to track staking operations: ```typescript // Listen for delegation events @@ -153,9 +153,9 @@ staking.on('ValidatorEdited', (editor, validatorAddress, moniker) => { ## Functions -The staking precompile exposes the following functions: +The staking precompile exposes these functions: -### Transaction Functions +### Transaction functions ```solidity /// Delegates Sei to the specified validator. @@ -221,7 +221,7 @@ function editValidator( ) external returns (bool success); ``` -### Query Functions +### Query functions ```solidity struct Delegation { @@ -447,13 +447,13 @@ function params() external view returns (Params memory params); -**Important Precision Note for `delegation()` Response:** +**Precision in the `delegation()` response:** -The response contains two different precision scales: +The response uses two different precision scales: -- `balance.amount`: **6 decimals** (usei) - the actual staked token amount -- `delegation.shares`: **18 decimals** - the validator pool share amount -- `delegation.decimals`: Always returns **18** (refers to shares precision, NOT balance) +- `balance.amount`: The staked token amount, in **6 decimals** (usei) +- `delegation.shares`: The amount of shares in the validator pool, in **18 decimals** +- `delegation.decimals`: Always returns **18** (the precision of the shares, NOT of the balance) To convert to SEI for display: @@ -462,22 +462,22 @@ To convert to SEI for display: -## Using the Precompile +## Using the precompile ### Setup #### Prerequisites -Before getting started, ensure you have: +Before you start, make sure that you have: -- **Node.js** (v18 or higher) -- **npm** or **yarn** package manager -- **EVM-compatible wallet** -- **SEI tokens** for gas and staking operations +- Node.js (v18 or higher) +- The npm or yarn package manager +- An EVM-compatible wallet +- SEI tokens for gas and staking operations -#### Install Dependencies +#### Install dependencies -Install the required packages for interacting with Sei precompiles: +Install the required packages to interact with Sei precompiles: ```bash # Install ethers.js for smart contract interactions @@ -487,7 +487,7 @@ npm install ethers npm install @sei-js/precompiles@^3 ``` -#### Import Precompile Components +#### Import precompile components ```typescript // Import Staking precompile address and ABI @@ -496,9 +496,9 @@ import { STAKING_PRECOMPILE_ABI, STAKING_PRECOMPILE_ADDRESS } from '@sei-js/prec import { ethers } from 'ethers'; ``` - **Precompile Address:** The staking precompile is deployed at `0x0000000000000000000000000000000000001005` + **Precompile address:** The staking precompile is deployed at `0x0000000000000000000000000000000000001005`. -### Contract Initialization +### Contract initialization Set up your provider, signer, and contract instance: @@ -512,15 +512,15 @@ const signer = await provider.getSigner(); const staking = new ethers.Contract(STAKING_PRECOMPILE_ADDRESS, STAKING_PRECOMPILE_ABI, signer); ``` -## Critical: Understanding Decimal Precision +## Critical: understanding decimal precision -One of the most important concepts to understand when working with the Sei staking precompile: +Decimal precision is one of the most important concepts to understand when you work with the Sei staking precompile. -### Mixed Decimal Precision System +### Mixed decimal precision system -The staking precompile operates with **different decimal precision for different operations** due to bridging EVM and Cosmos standards: +The staking precompile uses **different decimal precision for different operations**, because it bridges EVM and Cosmos standards: -| Function | Input/Output | Decimal Precision | Example | +| Function | Input/Output | Decimal precision | Example | | --- | --- | --- | --- | | **delegate()** | msg.value (input) | 18 decimals (wei) | `ethers.parseUnits('1', 18)` | | **undelegate()** | amount (input) | 6 decimals (uSEI) | `1000000` (represents 1 SEI) | @@ -533,7 +533,7 @@ The staking precompile operates with **different decimal precision for different **Granularity for delegate():** -`msg.value` is truncated to 6 decimals (uSEI). Always send amounts that are a multiple of `1e12` wei (last 12 digits zero) to avoid unintended truncation. +To avoid unintended truncation, always send amounts that are a multiple of `1e12` wei (the last 12 digits are zero). The precompile truncates `msg.value` to 6 decimals (uSEI). - OK: `1_000_000_000_000` wei (`0.000001000000` SEI) - NOT OK: `1_000_000_000_001` wei (`0.000001000000000001` SEI) @@ -546,31 +546,31 @@ Examples: -### How This Works in Practice +### How this works in practice -**delegate() Function (Uses 18 decimals):** +**delegate() function (uses 18 decimals):** -- `delegate()` - accepts `msg.value` in wei (18 decimals) +- `delegate()`: Accepts `msg.value` in wei (18 decimals) -**undelegate() and redelegate() Functions (Use 6 decimals):** +**undelegate() and redelegate() functions (use 6 decimals):** -- `undelegate()` - expects amount parameter in 6 decimals (uSEI) -- `redelegate()` - expects amount parameter in 6 decimals (uSEI) +- `undelegate()`: Expects the amount parameter in 6 decimals (uSEI) +- `redelegate()`: Expects the amount parameter in 6 decimals (uSEI) -**Reading/Query Operations (Return 6 decimals):** +**Read and query operations (return 6 decimals):** -- `delegation()` - returns `balance.amount` in 6-decimal `uSEI` and `delegation.shares` in 18-decimal precision -- Rewards are handled by the **Distribution precompile**: `rewards()` query returns 18-decimal `DecCoins`, while withdrawn amounts (events) are 6-decimal `uSEI` +- `delegation()`: Returns `balance.amount` in 6-decimal `uSEI` and `delegation.shares` in 18-decimal precision +- The **Distribution precompile** handles rewards. Its `rewards()` query returns 18-decimal `DecCoins`, but withdrawn amounts (events) are 6-decimal `uSEI`. -### Why This Mixed System Exists +### Why this mixed system exists -1. **delegate() EVM Compatibility:** Uses standard 18-decimal wei format for EVM `msg.value` consistency -2. **Other Operations Cosmos Integration:** `undelegate()` and `redelegate()` use 6-decimal uSEI precision to match native Cosmos operations -3. **Staking Query Consistency:** Staking precompile query balances use 6-decimal `uSEI` (while `shares` is 18-decimal) for consistent reading +1. **delegate() EVM compatibility:** Uses the standard 18-decimal wei format, for consistency with EVM `msg.value` +2. **Cosmos integration for other operations:** `undelegate()` and `redelegate()` use 6-decimal uSEI precision to match native Cosmos operations +3. **Staking query consistency:** Query balances in the staking precompile use 6-decimal `uSEI` (but `shares` is 18-decimal), for consistent reading -### Best Practice: Different Conversion for Different Functions +### Best practice: different conversion for different functions -When working with user inputs, use the appropriate conversion for each function: +When you work with user input, use the appropriate conversion for each function: ```typescript // Best practice for handling user input amounts @@ -595,13 +595,13 @@ const delegateAmount = prepareAmountForDelegate(userInputAmount); // 18 decimals const undelegateAmount = prepareAmountForUndelegateRedelegate(userInputAmount); // 6 decimals ``` -### Normalization Guidelines (Clients and Indexers) +### Normalization guidelines (clients and indexers) - **Normalize to a single unit** for analytics and reconciliation: - Display: convert to `SEI` (`wei / 1e18`, `uSEI / 1e6`) - - Storage/aggregation: prefer `uSEI` (6 decimals) -- **Reconciling delegate vs. undelegate/redelegate/rewards:** convert delegate `msg.value` from wei to uSEI using integer division by `1e12` (floor), which matches the precompile’s internal truncation. -- **Enforce granularity at source:** construct `msg.value` as a multiple of `1e12` wei by formatting user input to 6 decimals prior to `parseUnits`. + - Storage and aggregation: prefer `uSEI` (6 decimals) +- **Reconcile delegate amounts with undelegate, redelegate, and rewards amounts:** Convert the delegate `msg.value` from wei to uSEI with integer division by `1e12` (floor). This matches the internal truncation in the precompile. +- **Enforce granularity at the source:** Construct `msg.value` as a multiple of `1e12` wei. To do this, format user input to 6 decimals before you call `parseUnits`. ```typescript // Convert delegate msg.value (wei) to uSEI (6 decimals) for reconciliation @@ -620,7 +620,7 @@ function normalizeWeiForDelegate(valueWei: bigint): bigint { } ``` -## Decimal Conversion Helpers +## Decimal conversion helpers Use these helper functions to avoid precision errors: @@ -654,9 +654,9 @@ const undelegateAmount = SeiAmountConverter.seiToUsei(0.5); // For undelegate() const redelegateAmount = SeiAmountConverter.seiToUsei(2); // For redelegate() - 6 decimals ``` -## Step-by-Step Guide: Using the Staking Precompile +## Step-by-step guide: Using the staking precompile -### Delegate Tokens +### Delegate tokens @@ -694,7 +694,7 @@ function delegateToValidator(string memory validatorAddress) external payable { -### Undelegate Tokens +### Undelegate tokens @@ -733,9 +733,9 @@ function undelegateFromValidator( - **IMPORTANT:** Undelegated tokens are subject to a **21-day unbonding period** during which they cannot be transferred and do not earn rewards. + Undelegated tokens have a **21-day unbonding period**. During this period, you cannot transfer them, and they do not earn rewards. -### Redelegate Tokens +### Redelegate tokens @@ -778,15 +778,15 @@ function redelegateBetweenValidators( **Redelegation restrictions:** -- Maximum 7 redelegations per validator pair per 21-day period +- A maximum of 7 redelegations per validator pair in each 21-day period -- After redelegating from Validator A to Validator B, you cannot redelegate from Validator B to another validator for 21 days +- After you redelegate from Validator A to Validator B, you cannot redelegate from Validator B to another validator for 21 days - Each redelegation has its own 21-day cooldown period -### Query a Delegation +### Query a delegation @@ -833,9 +833,9 @@ function getDelegationInfo( -### Create a Validator +### Create a validator - Creating a validator requires significant SEI for self-delegation and proper validator infrastructure setup. Only proceed if you understand the responsibilities of running a validator node. + Proceed only if you understand the responsibilities of running a validator node. To create a validator, you need significant SEI for self-delegation and a correctly configured validator infrastructure. @@ -892,7 +892,7 @@ function createNewValidator( -### Edit a Validator +### Edit a validator ```typescript // Update validator parameters @@ -906,9 +906,9 @@ const receipt = await tx.wait(); console.log('Validator updated:', receipt); ``` -**Edit Validator Constraints:** - Commission can only be changed once every 24 hours - `minSelfDelegation` can only be increased, never decreased - Pass empty string `""` for `commissionRate` to keep current rate - Pass `0` for `minSelfDelegation` to keep current value +**Edit validator constraints:** You can change the commission only once every 24 hours. You can only increase `minSelfDelegation`, never decrease it. To keep the current rate, pass an empty string `""` for `commissionRate`. To keep the current value, pass `0` for `minSelfDelegation`. -### Query Validators +### Query validators ```typescript // Get all bonded validators @@ -926,7 +926,7 @@ if (allValidators.nextKey.length > 0) { } ``` -### Query a Specific Validator +### Query a specific validator ```typescript const validatorAddress = 'seivaloper1xyz...'; @@ -941,7 +941,7 @@ console.log('Validator details:', { }); ``` -### Query All Delegations for an Address +### Query all delegations for an address ```typescript const delegator = await signer.getAddress(); @@ -956,7 +956,7 @@ for (const del of myDelegations.delegations) { } ``` -### Query Unbonding Delegations +### Query unbonding delegations ```typescript const delegator = await signer.getAddress(); @@ -978,7 +978,7 @@ const validatorAddress = 'seivaloper1xyz...'; const specificUnbonding = await staking.unbondingDelegation(delegator, validatorAddress); ``` -### Query Redelegations +### Query redelegations ```typescript // Get all redelegations for a specific delegator @@ -1002,7 +1002,7 @@ for (const redel of redelegations.redelegations) { } ``` -### Query Staking Pool and Parameters +### Query staking pool and parameters ```typescript // Get staking pool totals @@ -1022,7 +1022,7 @@ console.log('Staking Parameters:', { }); ``` -### Query Historical Validator Info +### Query historical validator info ```typescript // Get validator set at a specific block height @@ -1035,9 +1035,9 @@ for (const val of historicalInfo.validators) { } ``` -## Advanced Usage Examples +## Advanced usage examples -### Portfolio Rebalancing +### Portfolio rebalancing ```typescript async function rebalanceStaking( @@ -1062,7 +1062,7 @@ async function rebalanceStaking( } ``` -### Complete Integration Example +### Complete integration example @@ -1125,7 +1125,7 @@ async function stakingExample() { -**Contract Example** +**Contract example** ```solidity // SPDX-License-Identifier: MIT @@ -1308,9 +1308,9 @@ contract StakingManager { } ``` - **Note:** This is a simplified example for demonstration purposes. The above example works such that when someone delegates through the above contract, the delegation will be recorded under the above contract address and not the user. So maintain correct mapping in the contract for tracking user delegations + This is a simplified example for demonstration purposes. When someone delegates through this contract, the delegation is recorded under the contract address, not under the user's address. Maintain a correct mapping in the contract to track user delegations. -**Client Integration Example** +**Client integration example** ```javascript import { network } from 'hardhat'; @@ -1372,30 +1372,30 @@ main().catch((error) => { -## Security Considerations & Risks +## Security considerations & risks -### Unbonding Period +### Unbonding period -- **21-day lock:** Undelegated tokens cannot be transferred or earn rewards for 21 days -- **No exceptions:** This cannot be canceled once initiated -- **Planning:** Consider this when managing liquidity needs +- **21-day lock:** For 21 days, undelegated tokens cannot be transferred and do not earn rewards. +- **No exceptions:** After the unbonding starts, you cannot cancel it. +- **Planning:** Consider the unbonding period when you manage liquidity needs. -### Validator Selection Criteria +### Validator selection criteria -- **Commission Rate:** Lower commission means more rewards for you (typically 1-10%) -- **Uptime:** Check for validators with high uptime (99%+) +- **Commission rate:** Commission is typically 1% to 10%. A lower commission means more rewards for you. +- **Uptime:** Look for validators with high uptime (99% or more). -### Redelegation Complexity +### Redelegation complexity -- **7-transaction limit:** You can only redelegate from the same validator to the same destination validator 7 times in 21 days -- **Serial blocking:** After redelegating A→B, you cannot redelegate B→C for 21 days -- **Each redelegation starts its own 21-day timer** +- **7-transaction limit:** You can redelegate from the same validator to the same destination validator only 7 times in 21 days. +- **Serial blocking:** After you redelegate from A to B, you cannot redelegate from B to C for 21 days. +- Each redelegation starts its own 21-day timer. ## Troubleshooting -### Common Issues and Solutions +### Common issues and solutions -#### Gas-Related Issues +#### Gas-related issues ```typescript // Set appropriate gas limits for different operations @@ -1405,57 +1405,57 @@ const delegateTx = await staking.delegate(validatorAddress, { }); ``` -### Error Code Reference +### Error code reference | Error | Cause | Solution | | --- | --- | --- | -| `insufficient funds` | Not enough SEI for operation | Check balance and reduce amount | -| `validator does not exist` | Invalid validator address | Verify validator address format | -| `invalid delegation amount` | Amount formatting issue | Use correct decimal precision | -| `commission rate too high` | Commission above max rate | Lower commission rate | -| `commission change too frequent` | Changing commission within 24h | Wait 24 hours between changes | -| `self delegation too low` | Below minimum self-delegation | Increase self-delegation amount | -| `too many redelegations` | Exceeded 7 redelegation limit | Wait for earliest redelegation to expire | +| `insufficient funds` | Not enough SEI for the operation | Check the balance and reduce the amount | +| `validator does not exist` | Invalid validator address | Verify the validator address format | +| `invalid delegation amount` | Amount formatting issue | Use the correct decimal precision | +| `commission rate too high` | Commission above the max rate | Lower the commission rate | +| `commission change too frequent` | Commission changed within 24 hours | Wait 24 hours between changes | +| `self delegation too low` | Below the minimum self-delegation | Increase the self-delegation amount | +| `too many redelegations` | Exceeded the limit of 7 redelegations | Wait for the earliest redelegation to expire | -## FAQ: Precision and Normalization +## FAQ: precision and normalization -- **What are the base units and precision standards defined for SEI across operations?** - - `delegate()`: accepts `msg.value` in wei (18 decimals), but is internally truncated to 6-decimal `uSEI`. Effective granularity is 1 uSEI = `1e12` wei. - - `undelegate()` / `redelegate()`: amounts use 6-decimal `uSEI`. - - Staking queries: balances are 6-decimal `uSEI` (and shares are 18-decimal). Distribution `rewards()` query returns 18-decimal `DecCoins`, but withdrawn amounts are 6-decimal `uSEI`. +- **What are the base units and precision standards for SEI across operations?** + - `delegate()`: Accepts `msg.value` in wei (18 decimals), but the precompile truncates it internally to 6-decimal `uSEI`. The effective granularity is 1 uSEI = `1e12` wei. + - `undelegate()` and `redelegate()`: Amounts use 6-decimal `uSEI`. + - Staking queries: Balances are 6-decimal `uSEI`, and shares are 18-decimal. The Distribution `rewards()` query returns 18-decimal `DecCoins`, but withdrawn amounts are 6-decimal `uSEI`. - **Should applications normalize between 18 and 6 decimals?** - - Yes. For reconciliation, convert delegate `wei` to `uSEI` via integer division by `1e12` (floor). For display, convert to SEI (`wei → /1e18`, `uSEI → /1e6`). + - Yes. For reconciliation, convert delegate `wei` to `uSEI` with integer division by `1e12` (floor). For display, convert to SEI (`wei → /1e18`, `uSEI → /1e6`). - **Is this behavior consistent and intentional?** - - Yes. This is intentional and not planned to change. Delegation uses EVM-native `msg.value` (18 decimals), while staking operations are executed in the Cosmos staking module, which uses 6-decimal `uSEI`. -- **Why multiple decimal precisions on one chain?** - - To bridge EVM conventions (18-decimal `msg.value`) with the Cosmos staking module’s native 6-decimal accounting while keeping queries and non-`delegate()` writes consistent at 6 decimals. + - Yes. This behavior is intentional, and there is no plan to change it. Delegation uses EVM-native `msg.value` (18 decimals). Staking operations run in the Cosmos staking module, which uses 6-decimal `uSEI`. +- **Why does one chain use multiple decimal precisions?** + - The precompile bridges EVM conventions (18-decimal `msg.value`) and the native 6-decimal accounting of the Cosmos staking module. At the same time, queries and writes other than `delegate()` stay consistent at 6 decimals. -## Important Notes +## Important notes - Remember the key rule: delegate() uses 18 decimals, undelegate()/redelegate() use 6 decimals, delegation() returns 6 decimals! + Remember this rule: delegate() uses 18 decimals, undelegate() and redelegate() use 6 decimals, and delegation() returns 6 decimals. -### Decimal Precision +### Decimal precision - **delegate()** uses 18 decimals (wei) for msg.value - **undelegate() and redelegate()** use 6 decimals (uSEI) for amount parameters -- **Query results** return amounts in 6 decimal precision -- **Best practice:** Use appropriate conversion functions for each operation -- **Rewards/claims (Distribution precompile):** `rewards()` query returns 18-decimal `DecCoins`; withdrawn amounts (events) are 6-decimal `uSEI` -- **Granularity:** `delegate()` `msg.value` must be a multiple of `1e12` wei (last 12 digits zero) because the precompile truncates to 6 decimals internally +- **Query results** return amounts in 6-decimal precision +- **Best practice:** Use the appropriate conversion function for each operation +- **Rewards and claims (Distribution precompile):** The `rewards()` query returns 18-decimal `DecCoins`. Withdrawn amounts (events) are 6-decimal `uSEI`. +- **Granularity:** The `msg.value` of `delegate()` must be a multiple of `1e12` wei (the last 12 digits are zero). The precompile truncates it to 6 decimals internally. -### Validator Addresses +### Validator addresses -- Use valid Sei validator addresses with `seivaloper1...` prefix -- These are Cosmos-format addresses, not EVM addresses +- Use valid Sei validator addresses with the `seivaloper1...` prefix. +- These are Cosmos-format addresses, not EVM addresses. -### Staking Risks +### Staking risks -- **Unbonding:** 21-day waiting period for undelegated tokens -- **Redelegation limits:** Complex rules around frequency and serial operations +- **Unbonding:** A 21-day waiting period applies to undelegated tokens. +- **Redelegation limits:** Complex rules apply to redelegation frequency and serial redelegations. -### Commission and Rewards +### Commission and rewards -- Validators keep a commission percentage -- Rewards are distributed proportionally to delegation amounts -- Choose validators wisely based on commission, uptime, and governance participation +- Validators keep a commission percentage. +- Rewards are distributed in proportion to delegation amounts. +- Choose validators based on commission, uptime, and governance participation. diff --git a/evm/python-quickstart.mdx b/evm/python-quickstart.mdx index 08c0c8b..437bab1 100644 --- a/evm/python-quickstart.mdx +++ b/evm/python-quickstart.mdx @@ -7,11 +7,11 @@ keywords: ['sei evm', 'python', 'web3.py', 'json-rpc', 'quickstart'] import { RunSnippet } from '/snippets/run-snippet.jsx'; -Sei is fully EVM-compatible, so any standard Ethereum client works — including Python's [web3.py](https://web3py.readthedocs.io). This guide connects to Sei from a Python script, reads chain data with no credentials, then signs and broadcasts a transaction. +Sei is fully EVM-compatible, so any standard Ethereum client works with it, including Python's [web3.py](https://web3py.readthedocs.io). In this guide, you connect to Sei from a Python script and read chain data without credentials. Then you sign and broadcast a transaction. ## Install -We recommend an isolated virtual environment: +Use an isolated virtual environment: ```bash python3 -m venv venv @@ -19,9 +19,9 @@ source venv/bin/activate # Windows: venv\Scripts\activate pip install web3 ``` -## Reading Chain Data +## Reading chain data -This is the first milestone — it needs no private key. +This is the first milestone. It does not need a private key. ```python from web3 import Web3 @@ -38,7 +38,7 @@ print("Balance (SEI):", w3.from_wei(w3.eth.get_balance(address), "ether")) print("Nonce:", w3.eth.get_transaction_count(address)) ``` -**You're done when you see:** +**You are done when you see:** ```text Connected: True @@ -48,13 +48,13 @@ Balance (SEI): 12.5 Nonce: 7 ``` -Values are illustrative — your block number, and the queried address's balance and nonce, will differ. The EVM chain ID is always `1329` on Sei Mainnet and `1328` on Sei Testnet. +The exact values are illustrative. Your block number will differ, and so will the balance and nonce of the queried address. The EVM chain ID is always `1329` on Sei Mainnet and `1328` on Sei Testnet. ## Try it live -`web3.py` issues plain JSON-RPC under the hood — here are the same reads against Sei Mainnet, no Python required. +`web3.py` sends plain JSON-RPC requests internally. These snippets send the same reads to Sei Mainnet, so you do not need Python to run them. - + @@ -63,12 +63,12 @@ Values are illustrative — your block number, and the queried address's balance params={['0x0000000000000000000000000000000000000000', 'latest']} network="mainnet" title="w3.eth.get_balance(address)" - description="Wei balance of the example address — swap in your own. w3.from_wei(…, 'ether') converts it to SEI." + description="Wei balance of the example address. You can replace the example address with your own. w3.from_wei(…, 'ether') converts the balance to SEI." /> -## Sending a Transaction +## Sending a transaction -Next step — this requires a funded account. Get testnet SEI from the [faucet](/learn/faucet), then build, **sign locally**, and broadcast with `eth_sendRawTransaction`. Public RPC endpoints don't manage accounts, so you sign the transaction yourself rather than relying on node-managed accounts. +This next step requires a funded account. Get testnet SEI from the [faucet](/learn/faucet). Then build the transaction, **sign it locally**, and broadcast it with `eth_sendRawTransaction`. Public RPC endpoints do not manage accounts, so you sign the transaction yourself instead of relying on node-managed accounts. ```python import os @@ -97,11 +97,11 @@ receipt = w3.eth.wait_for_transaction_receipt(tx_hash) print("Mined in block:", receipt.blockNumber) # final immediately — Sei has instant finality ``` -Never hard-code or commit a private key. Load it from an environment variable or a secrets manager, and use a dedicated throwaway key funded with only what you need. +Never hard-code or commit a private key. Load it from an environment variable or a secrets manager. Use a dedicated throwaway key that holds only the funds you need. -`signed.raw_transaction` is the attribute name in web3.py v7+. On web3.py v6 it is `signed.rawTransaction`. +In web3.py v7+, the attribute name is `signed.raw_transaction`. In web3.py v6, it is `signed.rawTransaction`. -## Reading a Contract +## Reading a contract ```python abi = [{ @@ -117,9 +117,9 @@ token = w3.eth.contract(address="0xTokenAddress", abi=abi) print(token.functions.balanceOf(address).call()) ``` -## Next Steps +## Next steps -- [viem Quickstart](/evm/evm-parity/examples/viem-quickstart) — the TypeScript/Node.js equivalent -- [ethers v6 Quickstart](/evm/evm-parity/examples/ethers-quickstart) — TypeScript with ethers -- [Network information](/evm/networks) — RPC endpoints, chain IDs, and explorers -- [Faucet](/learn/faucet) — get testnet SEI +- [viem Quickstart](/evm/evm-parity/examples/viem-quickstart): the TypeScript and Node.js equivalent +- [ethers v6 Quickstart](/evm/evm-parity/examples/ethers-quickstart): TypeScript with ethers +- [Network information](/evm/networks): RPC endpoints, chain IDs, and explorers +- [Faucet](/learn/faucet): get testnet SEI diff --git a/evm/querying-the-evm.mdx b/evm/querying-the-evm.mdx index 04110e1..9c9d629 100644 --- a/evm/querying-the-evm.mdx +++ b/evm/querying-the-evm.mdx @@ -4,29 +4,29 @@ description: 'Read EVM state from the seid CLI: address associations, ERC20 read keywords: ['seid query', 'evm query', 'erc20 balance', 'payload generation'] --- -The `seid q evm` subcommands let you read EVM state — token data, address associations, and transactions — without sending a transaction or running your own node. +The `seid q evm` subcommands let you read EVM state (token data, address associations, and transactions). You do not need to send a transaction or run your own node. ## Prerequisites -If your machine is **not running a Sei node**, append the `--node` flag to every `seid q evm` command, pointing at a Sei Cosmos RPC endpoint (the same kind used by `seid status`): +If your machine does not run a Sei node, append the `--node` flag to every `seid q evm` command. Point it at a Sei Cosmos RPC endpoint, the same kind that `seid status` uses: ```bash --node https:// ``` -The one exception is `seid q evm tx`, which uses `--evm-rpc` to point at an EVM JSON-RPC endpoint (port 8545 by convention). See [Transaction Lookup](#transaction-lookup) below. +The one exception is `seid q evm tx`, which uses `--evm-rpc` to point at an EVM JSON-RPC endpoint (port 8545 by convention). See [Transaction lookup](#transaction-lookup) below. -Refer to the [RPC endpoints](/evm/networks) page for a list of available RPC endpoints. +For a list of available RPC endpoints, see [RPC endpoints](/evm/networks). -**Output format.** Most commands print YAML by default. Pass `-o json` for JSON. ERC20 read methods (`name`, `balanceOf`, …) return a bare value with no formatting — the result below is the raw stdout. +**Output format.** Most commands print YAML by default. To get JSON, pass `-o json`. ERC20 read methods (such as `name` and `balanceOf`) return a bare value with no formatting. The output shown below is the raw stdout. -## Address Mapping +## Address mapping -Sei addresses (`sei1…`) and EVM addresses (`0x…`) are linked via an on-chain association set the first time an account signs an EVM transaction or calls the address-association precompile. Until then, the two address spaces are independent. +Sei addresses (`sei1…`) and EVM addresses (`0x…`) are linked through an on-chain association. The association is set the first time an account signs an EVM transaction or calls the address-association precompile. Until then, the two address spaces are independent. -### Get Sei Address from EVM Address +### Get Sei address from EVM address ```bash seid q evm sei-addr [evm address] @@ -45,7 +45,7 @@ associated: true sei_address: sei13ytysxs88z0fp9cssagg77ekpecrrlrwce9pwl ``` -### Get EVM Address from Sei Address +### Get EVM address from Sei address ```bash seid q evm evm-addr [sei address] @@ -64,9 +64,9 @@ associated: true evm_address: 0xDa52B9E673d1f48FcD9916b3F606A136a8eA5e55 ``` -If the account hasn't been associated yet, `associated` is `false` and the other field is empty. This is normal for accounts that have only ever transacted on one side of the chain. +If the account is not associated yet, `associated` is `false`, and the other field is empty. This is normal for accounts that have transacted on only one side of the chain. -## ERC20 Contract Queries +## ERC20 contract queries Call standard view methods on any ERC20 contract: @@ -74,7 +74,7 @@ Call standard view methods on any ERC20 contract: seid q evm erc20 [contract address] [method] [arguments...] ``` -**Example — query Wrapped Sei (`WSEI`):** +**Example query for Wrapped Sei (`WSEI`):** ```bash seid q evm erc20 0xE30feDd158A2e3b13e9badaeABaFc5516e95e8C7 symbol @@ -86,13 +86,13 @@ seid q evm erc20 0xE30feDd158A2e3b13e9badaeABaFc5516e95e8C7 symbol WSEI ``` -**Example — balance:** +**Example balance query:** ```bash seid q evm erc20 0xE30feDd158A2e3b13e9badaeABaFc5516e95e8C7 balanceOf 0xDa52B9E673d1f48FcD9916b3F606A136a8eA5e55 ``` -**Output (raw integer, in smallest unit):** +**Output (raw integer, in the smallest unit):** ``` 0 @@ -101,23 +101,23 @@ seid q evm erc20 0xE30feDd158A2e3b13e9badaeABaFc5516e95e8C7 balanceOf 0xDa52B9E6 **Supported methods:** -- `name` — token name -- `symbol` — token symbol -- `decimals` — token decimals -- `totalSupply` — total supply -- `balanceOf [address]` — balance of an address -- `allowance [owner] [spender]` — current allowance +- `name`: token name +- `symbol`: token symbol +- `decimals`: token decimals +- `totalSupply`: total supply +- `balanceOf [address]`: balance of an address +- `allowance [owner] [spender]`: current allowance For arbitrary methods or non-standard contracts, use [`payload`](#custom-abi) with the contract ABI. -## Payload Generation +## Payload generation -Generate ABI-encoded call data without sending a transaction. Useful for crafting `seid tx evm call-contract` calls or inspecting expected calldata. +These commands generate ABI-encoded calldata without sending a transaction. They are useful when you build `seid tx evm call-contract` calls or inspect expected calldata. - ### ERC20 Payload Generation + ### ERC20 payload generation ```bash seid q evm erc20-payload [method] [arguments...] @@ -133,7 +133,7 @@ Generate ABI-encoded call data without sending a transaction. Useful for craftin a9059cbb000000000000000000000000da52b9e673d1f48fcd9916b3f606a136a8ea5e550000000000000000000000000000000000000000000000000de0b6b3a7640000 ``` - **Approve spender:** + **Approve a spender:** ```bash seid q evm erc20-payload approve 0xDa52B9E673d1f48FcD9916b3F606A136a8eA5e55 2000000000000000000 ``` @@ -143,7 +143,7 @@ Generate ABI-encoded call data without sending a transaction. Useful for craftin 095ea7b3000000000000000000000000da52b9e673d1f48fcd9916b3f606a136a8ea5e550000000000000000000000000000000000000000000000001bc16d674ec80000 ``` - **Transfer from (pulls tokens from `from` to `to`, using a prior `approve`):** + **Transfer from (pulls tokens from `from` to `to`, based on an earlier `approve`):** ```bash seid q evm erc20-payload transferFrom 0xDa52B9E673d1f48FcD9916b3F606A136a8eA5e55 0xdEAD000000000000000042069420694206942069 1500000000000000000 ``` @@ -159,13 +159,13 @@ Generate ABI-encoded call data without sending a transaction. Useful for craftin - `approve [spender] [amount]` - `transferFrom [from] [to] [amount]` - Amounts are in the token's smallest unit (e.g., wei for an 18-decimal token; `1000000` for 1 USDC with 6 decimals). + Amounts are in the token's smallest unit: for example, wei for an 18-decimal token, or `1000000` for 1 USDC with 6 decimals. - ### ERC721 Payload Generation + ### ERC721 payload generation ```bash seid q evm erc721-payload [method] [arguments...] @@ -211,7 +211,7 @@ Generate ABI-encoded call data without sending a transaction. Useful for craftin - ### ERC1155 Payload Generation + ### ERC1155 payload generation ```bash seid q evm erc1155-payload [method] [arguments...] @@ -243,15 +243,15 @@ Generate ABI-encoded call data without sending a transaction. Useful for craftin - `safeBatchTransferFrom [from] [to] [tokenIds] [amounts] [data]` - `setApprovalForAll [operator] [true|false]` - For batch operations, pass arrays as quoted bracketed strings: `"[123,456]"`. The trailing `data` field is a hex string (use `0x` for empty). + For batch operations, pass arrays as quoted bracketed strings: `"[123,456]"`. The trailing `data` field is a hex string (use `0x` for empty data). - ### Custom ABI Payload Generation + ### Custom ABI payload generation - Encode a call against any contract by supplying its ABI: + To encode a call against any contract, supply its ABI: ```bash seid q evm payload [abi-filepath] [method] [arguments...] @@ -263,21 +263,21 @@ Generate ABI-encoded call data without sending a transaction. Useful for craftin ``` - The ABI file must be a JSON array of function definitions, in the same shape Hardhat/Foundry emit (the `abi` field of an artifact, not the whole artifact). + The ABI file must be a JSON array of function definitions. It must have the same shape that Hardhat and Foundry emit: the `abi` field of an artifact, not the whole artifact. -## Pointer System +## Pointer system -Pointers bridge the EVM and CosmWasm sides of Sei: a CW20 can be exposed as an ERC20 (via an EVM pointer at a `0x` address) and an ERC20 can be exposed as a CW20 (via a CW pointer at a `sei1…` address). The same applies to NFTs (CW721/ERC721) and multi-token contracts (CW1155/ERC1155). +Pointers bridge the EVM and CosmWasm sides of Sei. A CW20 can be exposed as an ERC20 through an EVM pointer at a `0x` address. An ERC20 can be exposed as a CW20 through a CW pointer at a `sei1…` address. The same applies to NFTs (CW721 and ERC721) and multi-token contracts (CW1155 and ERC1155). -## Transaction Lookup +## Transaction lookup -### Query Transaction by Hash +### Query transaction by hash -Equivalent to `eth_getTransactionByHash`: +This command is equivalent to `eth_getTransactionByHash`: ```bash seid q evm tx [hash] --evm-rpc [EVM RPC endpoint] @@ -318,12 +318,12 @@ seid q evm tx 0x828c91592453fe7c5bf743204495a35bf02b67b579b8f59ee7eea8af031d7c14 ``` -This is the only `seid q evm` command that takes `--evm-rpc` (an **EVM JSON-RPC** endpoint, typically port 8545) instead of `--node` (a Cosmos RPC). The default if you omit the flag is `http://0.0.0.0:8545`, which only works if you're running a local node. See [RPC endpoints](/evm/networks) for hosted EVM RPCs. +This is the only `seid q evm` command that takes `--evm-rpc` (an EVM JSON-RPC endpoint, typically port 8545) instead of `--node` (a Cosmos RPC). If you omit the flag, the default is `http://0.0.0.0:8545`, which works only if you run a local node. For hosted EVM RPC endpoints, see [RPC endpoints](/evm/networks). -## Common Use Cases +## Common use cases -### Check Token Balance and Info +### Check token balance and info ```bash # Token metadata @@ -334,7 +334,7 @@ seid q evm erc20 0xtoken... decimals seid q evm erc20 0xtoken... balanceOf 0xuser... ``` -### Prepare and Send a Transaction +### Prepare and send a transaction ```bash # 1. Encode the calldata diff --git a/evm/reference.mdx b/evm/reference.mdx index 3aace4d..1fb73ef 100644 --- a/evm/reference.mdx +++ b/evm/reference.mdx @@ -7,42 +7,42 @@ keywords: ['json-rpc', 'api reference', 'evm endpoints', 'blockchain api', 'sei import { RPCMethodsViewer } from '/snippets/rpc-methods-viewer.jsx'; -Sei fully supports the standard Ethereum JSON-RPC API, so existing EVM tooling (ethers.js, viem, Hardhat, Foundry, etc.) works out of the box. Use the explorer below to browse every method Sei exposes, inspect parameters, run requests against a live endpoint, and copy ready-to-use snippets in a range of popular languages. The authoritative prose for the request format, the remaining deprecated `sei_*` extensions, and address resolution follows underneath. +Sei fully supports the standard Ethereum JSON-RPC API, so existing EVM tools (ethers.js, viem, Hardhat, Foundry, and others) work without changes. Use the explorer below to browse every method that Sei exposes and inspect its parameters. You can also run requests against a live endpoint and copy ready-to-use snippets in a range of popular languages. The text below the explorer is the authoritative reference for the request format, the remaining deprecated `sei_*` extensions, and address resolution. -By default the explorer lists only the available, current methods. Each is labelled with one of three statuses: +By default, the explorer lists only the current methods that are available. Each method has one of three status labels: -- **Supported** — registered with a full implementation and standard Ethereum behavior. -- **Limited** — callable, but returns a static value or has a Sei-specific caveat (shown in the method's **Sei-specific behavior** note). Examples: `eth_coinbase` returns the fee-collector address and `eth_getProof` returns an IAVL proof. -- **Unavailable** — not registered, explicitly errors, or not applicable to Sei's architecture. This includes blob methods (`eth_blobBaseFee`), proof-of-work and uncle methods, and the `admin`/`miner`/`clique`/`engine`/`les`/`personal` namespaces. +- **Supported**: The method is registered and has a full implementation with standard Ethereum behavior. +- **Limited**: The method is callable, but it returns a static value or has a Sei-specific caveat (shown in the method's **Sei-specific behavior** note). For example, `eth_coinbase` returns the fee-collector address, and `eth_getProof` returns an IAVL proof. +- **Unavailable**: The method is not registered, returns an explicit error, or does not apply to Sei's architecture. This includes blob methods (`eth_blobBaseFee`), proof-of-work and uncle methods, and the `admin`, `miner`, `clique`, `engine`, `les`, and `personal` namespaces. -The remaining deprecated `sei_*` extensions and the unavailable methods are hidden by default. Enable **Show deprecated & unavailable methods** to browse them. The deprecated extensions are also documented under [Sei custom endpoints](#sei-custom-endpoints). +By default, the explorer hides the remaining deprecated `sei_*` extensions and the unavailable methods. To browse them, enable **Show deprecated & unavailable methods**. The deprecated extensions are also documented under [Sei custom endpoints](#sei-custom-endpoints). ## Overview -Sei supports the [Ethereum JSON-RPC API](https://ethereum.org/en/developers/docs/apis/json-rpc/) with some Sei-specific extensions to support cross-VM operations, synthetic transactions, and other advanced features. Because Sei has [instant finality](/evm/differences-with-ethereum#finality), the `safe`, `finalized`, and `latest` block tags all resolve to the same (latest committed) block. +Sei supports the [Ethereum JSON-RPC API](https://ethereum.org/en/developers/docs/apis/json-rpc/). It also has some Sei-specific extensions for cross-VM operations, synthetic transactions, and other advanced features. Because Sei has [instant finality](/evm/differences-with-ethereum#finality), the `safe`, `finalized`, and `latest` block tags all resolve to the same (latest committed) block. All endpoints follow the standard JSON-RPC format: - -**Request Format** + +**Request format** -- HTTP method: always "`POST`" +- HTTP method: always `POST` - Header: `accept: application/json` - Header: `content-type: application/json` - Body (JSON): - `id`: an arbitrary string identifier - `jsonrpc`: always "2.0" - - `method`: endpoint name (e.g. "eth_sendRawTransaction") + - `method`: endpoint name (for example, `eth_sendRawTransaction`) - `params`: an array that differs from endpoint to endpoint -**Response Format** +**Response format** - Body (JSON): - - `id`: the same identifier in request + - `id`: the same identifier as in the request - `jsonrpc`: always "2.0" - `result`: an object that differs from endpoint to endpoint - `error` (if applicable): error details @@ -56,17 +56,17 @@ All endpoints follow the standard JSON-RPC format: | Sei Mainnet | `1329` (`0x531`) | `https://evm-rpc.sei-apis.com` | `wss://evm-ws.sei-apis.com` | | Sei Testnet | `1328` (`0x530`) | `https://evm-rpc-testnet.sei-apis.com` | `wss://evm-ws-testnet.sei-apis.com` | -For additional public and commercial endpoints, see [RPC providers](/learn/rpc-providers) and [Chains & endpoints](/learn/dev-chains). +For more public and commercial endpoints, see [RPC providers](/learn/rpc-providers) and [Chains & endpoints](/learn/dev-chains). ### Tendermint `/status` endpoint -Alongside the EVM JSON-RPC surface, Sei nodes expose the underlying Tendermint/CometBFT RPC, including the `/status` endpoint. Its `SyncInfo` object reports a `last_committed_block_height` field: the height of the last block finalized by consensus. +In addition to the EVM JSON-RPC surface, Sei nodes expose the underlying Tendermint (CometBFT) RPC, including the `/status` endpoint. Its `SyncInfo` object reports a `last_committed_block_height` field: the height of the last block finalized by consensus. ```bash curl -s $SEI_TENDERMINT_RPC/status | jq '.result.sync_info.last_committed_block_height' ``` -The field is JSON-serialized as a string (`last_committed_block_height`), matching the other height fields in `SyncInfo`. +The field is serialized to JSON as a string (`last_committed_block_height`), like the other height fields in `SyncInfo`. | Field | JSON | Description | | :- | :- | :- | @@ -74,55 +74,62 @@ The field is JSON-serialized as a string (`last_committed_block_height`), matchi **Consensus-engine behavior:** -- **Under CometBFT** — commit and app-apply happen in a single step, so `last_committed_block_height` is guaranteed to equal `latest_block_height`. -- **Under Autobahn** — the value is derived from the latest `CommitQC`. Because consensus finalizes a block before the app executes it, the invariant is `last_committed_block_height >= latest_block_height`; the two can briefly differ while the app catches up. +- **Under CometBFT**: Commit and app-apply happen in a single step, so `last_committed_block_height` is guaranteed to equal `latest_block_height`. +- **Under Autobahn**: The value is derived from the latest `CommitQC`. Consensus finalizes a block before the app executes it, so the invariant is `last_committed_block_height >= latest_block_height`. The two values can differ for a short time while the app catches up. -**`validator_info` shape.** The `/status` response's `validator_info` object always includes both a `pub_key` and an `address` field. On nodes that are not validators, `pub_key` is a zero (empty) public key with `address` derived from it and `voting_power` is `0`, rather than the fields being omitted — a stable response shape so clients like CosmJS can parse `/status` without special-casing non-validator nodes. On validator nodes, `pub_key` and `voting_power` carry the real values. +**`validator_info` shape.** The `validator_info` object in the `/status` response always includes both a `pub_key` and an `address` field. On nodes that are not validators, the response does not omit these fields. Instead, `pub_key` is a zero (empty) public key, `address` is derived from it, and `voting_power` is `0`. This keeps the response shape stable, so clients like CosmJS can parse `/status` without special handling for non-validator nodes. On validator nodes, `pub_key` and `voting_power` carry the real values. -Under Autobahn (`AutobahnConfigFile` set) the CometBFT block store is not populated, so `/status` derives `latest_block_height` and `latest_app_hash` from the app layer (`ABCIInfo`) instead of the block store. Several other `SyncInfo` fields (block hash/time, earliest-block metadata, `catching_up`, and peer-height fields) remain unpopulated in this mode. +Under Autobahn (`AutobahnConfigFile` set), the CometBFT block store is not populated. For this reason, `/status` derives `latest_block_height` and `latest_app_hash` from the app layer (`ABCIInfo`), not from the block store. Several other `SyncInfo` fields are also not populated in this mode: block hash and time, earliest-block metadata, `catching_up`, and the peer-height fields. ### Tendermint block and validator endpoints under Autobahn -Under Autobahn (`AutobahnConfigFile` set) the CometBFT `BlockStore` and `StateStore` are not populated. Rather than returning empty or failing responses, the `/block` and `/block_by_hash` Tendermint RPC endpoints route through the GigaRouter's in-memory state (the finalized global blocks retained by the Autobahn data layer), while `/block_results` and `/validators` synthesize their responses (an empty result set and the genesis committee, respectively). This keeps downstream consumers — including evmrpc, block explorers, and monitoring tooling — working without individually branching on the consensus engine. +Under Autobahn (`AutobahnConfigFile` set), the CometBFT `BlockStore` and `StateStore` are not populated. These Tendermint RPC endpoints do not return empty or failing responses in this mode. Instead: -For `/block` and `/block_by_hash`, responses are served only for heights still inside Autobahn's retained window (heights pruned per `RetainHeight` are no longer available); `/block_results` and `/validators` do not read the retained block data and respond for any height up to the current ABCI head. Requests are validated against the current ABCI head, so heights above it return the same `ErrHeightExceedsChainHead`-class errors as the CometBFT path, and pruned heights on `/block` return `ErrHeightNotAvailable`. +- `/block` and `/block_by_hash` route through the GigaRouter's in-memory state (the finalized global blocks that the Autobahn data layer retains). +- `/block_results` and `/validators` synthesize their responses (an empty result set and the genesis committee, respectively). + +This keeps downstream consumers, including evmrpc, block explorers, and monitoring tools, working without each one branching on the consensus engine. + +`/block` and `/block_by_hash` serve responses only for heights that are still inside Autobahn's retained window. Heights pruned per `RetainHeight` are no longer available. `/block_results` and `/validators` do not read the retained block data. They respond for any height up to the current ABCI head. Requests are validated against the current ABCI head, so heights above it return the same `ErrHeightExceedsChainHead`-class errors as the CometBFT path. Pruned heights on `/block` return `ErrHeightNotAvailable`. | Endpoint | Autobahn behavior | | :- | :- | -| `/block` | Returns the fully-populated translated block at the requested height: `BlockID.Hash` (the Autobahn header hash), the header (`ChainID`, `Height`, `Time`), and `Data.Txs`. Other header fields (`AppHash`, `ProposerAddress`, `LastCommit`, …) stay at zero values. | -| `/block_by_hash` | Resolves the block by its Autobahn header hash via an in-memory hash index. An unknown or wrong-size hash returns `{Block: nil}` with no error, matching CometBFT semantics for a missing block. | -| `/block_results` | Returns a valid-but-empty `ResultBlockResults` at the requested height. `ConsensusParamUpdates.Block.MaxGas` is populated from the producer config; `TxsResults` (per-tx `ExecTxResult` details) is intentionally empty because `FinalizeBlock` responses are not persisted under Autobahn. | -| `/validators` | Returns the genesis committee for any height up to the current ABCI head — the committee is fixed at genesis under Autobahn (no validator-updates path), and the endpoint does not read the retained block data, so pruned heights still answer. `block_height` matches the requested height, and pagination (`page`/`per_page`) behaves the same as the CometBFT path. | +| `/block` | Returns the fully populated translated block at the requested height: `BlockID.Hash` (the Autobahn header hash), the header (`ChainID`, `Height`, `Time`), and `Data.Txs`. Other header fields, such as `AppHash`, `ProposerAddress`, and `LastCommit`, stay at zero values. | +| `/block_by_hash` | Resolves the block by its Autobahn header hash through an in-memory hash index. An unknown or wrong-size hash returns `{Block: nil}` with no error. This matches CometBFT semantics for a missing block. | +| `/block_results` | Returns a valid but empty `ResultBlockResults` at the requested height. `ConsensusParamUpdates.Block.MaxGas` is populated from the producer config. `TxsResults` (per-transaction `ExecTxResult` details) is empty on purpose, because `FinalizeBlock` responses are not persisted under Autobahn. | +| `/validators` | Returns the genesis committee for any height up to the current ABCI head. Under Autobahn, the committee is fixed at genesis (there is no validator-updates path). The endpoint does not read the retained block data, so pruned heights still answer. `block_height` matches the requested height. Pagination (`page` and `per_page`) behaves the same as on the CometBFT path. | -Because `FinalizeBlock` responses are not stored on disk under Autobahn, `/block_results` cannot surface per-transaction execution results (`TxsResults` is empty). For per-transaction EVM data, use the EVM JSON-RPC methods (`eth_getTransactionReceipt`, `eth_getBlockReceipts`) instead. +Because `FinalizeBlock` responses are not stored on disk under Autobahn, `/block_results` cannot return per-transaction execution results (`TxsResults` is empty). For per-transaction EVM data, use the EVM JSON-RPC methods `eth_getTransactionReceipt` and `eth_getBlockReceipts` instead. ### Filter and subscription limits -Log filters (`eth_getLogs`, `eth_getFilterLogs`) are subject to the following limits by default: +By default, log filters (`eth_getLogs`, `eth_getFilterLogs`) have these limits: - **Open-ended block range:** up to 10,000 logs in one response -- **Close-ended block range:** up to 2,000 blocks to query over +- **Close-ended block range:** up to 2,000 blocks in one query -Real-time subscriptions (`eth_subscribe` for `newHeads` and `logs`) are available over WebSocket only. See [WebSocket connections](/evm/evm-parity/websocket) for transport details. +Real-time subscriptions (`eth_subscribe` for `newHeads` and `logs`) are available over WebSocket only. For transport details, see [WebSocket connections](/evm/evm-parity/websocket). ## Standard Ethereum endpoints -Every method below is also browsable interactively in the explorer above; this section is the static, copy-friendly reference. Methods are grouped by purpose and labelled with their Sei support status. Block parameters accept a hex number or one of the tags `latest`, `earliest`, `pending`, `safe`, or `finalized`. On Sei, `safe`, `finalized`, and `latest` all resolve to the latest committed block due to [instant finality](/evm/differences-with-ethereum#finality). The remaining deprecated `sei_*` extensions are documented separately under [Sei custom endpoints](#sei-custom-endpoints). +You can also browse every method below in the interactive explorer above. This section is the static, copy-friendly reference. Methods are grouped by purpose and labeled with their Sei support status. Block parameters accept a hex number or one of the tags `latest`, `earliest`, `pending`, `safe`, or `finalized`. On Sei, `safe`, `finalized`, and `latest` all resolve to the latest committed block because of [instant finality](/evm/differences-with-ethereum#finality). The remaining deprecated `sei_*` extensions are documented separately under [Sei custom endpoints](#sei-custom-endpoints). #### `eth_sendRawTransaction` **Supported.** Submits a signed, RLP-encoded raw EVM transaction to the network and returns its hash. -**Sei-specific behavior:** Decodes to an ethtypes.Transaction, wraps it in a Cosmos MsgEVMTransaction, and broadcasts via CometBFT (CheckTx-level BroadcastTx, i.e. `broadcast_tx_sync`, by default; slow mode uses BroadcastTxCommit). Non-zero CheckTx codes surface as ABCI errors, not geth mempool errors. Legacy (non-1559) txs must set gasPrice at or above the governance minimum (currently 50 gwei on mainnet); blob (EIP-4844) txs are not enabled. Supports per-sender EvmProxy forwarding. +**Sei-specific behavior:** Decodes the bytes to an ethtypes.Transaction, wraps it in a Cosmos MsgEVMTransaction, and broadcasts it through CometBFT. By default, it uses a CheckTx-level BroadcastTx (that is, `broadcast_tx_sync`), and slow mode uses BroadcastTxCommit. Non-zero CheckTx codes are returned as ABCI errors, not geth mempool errors. Legacy (non-1559) transactions must set gasPrice at or above the governance minimum (currently 50 gwei on Sei Mainnet). Blob (EIP-4844) transactions are not enabled. The method supports per-sender EvmProxy forwarding. + +**Under Autobahn (`AutobahnConfigFile` set):** Transaction broadcast routes through Autobahn's producer-backed mempool instead of CometBFT's `TxMempool`. This mempool admits EVM transactions strictly in sequential nonce order for each sender. It rejects a transaction with a bad-nonce error if its nonce does not match the sender's next expected nonce. Senders must therefore submit nonces contiguously. -**Under Autobahn (`AutobahnConfigFile` set):** transaction broadcast routes through Autobahn's producer-backed mempool instead of CometBFT's `TxMempool`. This mempool admits EVM transactions strictly in sequential per-sender nonce order: a transaction whose nonce does not match the sender's next expected nonce is rejected with a bad-nonce error, so senders must submit nonces contiguously. The default CheckTx-synchronous broadcast (`broadcast_tx_sync`, the same path named above) blocks while the mempool is full and only returns once capacity is available — meaning a default `eth_sendRawTransaction` under Autobahn can stall for as long as the mempool stays full — whereas the async path (`broadcast_tx_async`) may silently drop the transaction instead. The `unsafe_flush_mempool` Tendermint RPC endpoint is not supported under Autobahn and returns `unsafe_flush_mempool is not supported with autobahn mempool`. +Under Autobahn, the default CheckTx-synchronous broadcast (`broadcast_tx_sync`, the same path named above) blocks while the mempool is full. It returns only after capacity is available. As a result, a default `eth_sendRawTransaction` call can stall for as long as the mempool stays full. The async path (`broadcast_tx_async`) may silently drop the transaction instead. The `unsafe_flush_mempool` Tendermint RPC endpoint is not supported under Autobahn and returns `unsafe_flush_mempool is not supported with autobahn mempool`. **Parameters:** @@ -145,15 +152,15 @@ Every method below is also browsable interactively in the explorer above; this s #### `eth_sendTransaction` -**Limited.** Signs (with a node-hosted key) and submits a transaction in one call. +**Limited.** Signs a transaction with a node-hosted key and submits it in one call. -**Sei-specific behavior:** Requires the 'from' address's private key in the node's local test keyring; production/public RPC nodes hold no hosted keys, so this returns 'from address does not have hosted key'. Always signs as LegacyTxType. Sign client-side and use eth_sendRawTransaction instead. +**Sei-specific behavior:** Requires the private key of the 'from' address in the node's local test keyring. Production and public RPC nodes hold no hosted keys, so on those nodes this method returns 'from address does not have hosted key'. Always signs as LegacyTxType. Sign client-side and use `eth_sendRawTransaction` instead. **Parameters:** | # | Name | Type | Description | | :- | :- | :- | :- | -| 1 | `args` | object | Transaction object (from, to, value, data, gas, nonce, etc.). | +| 1 | `args` | object | Transaction object (from, to, value, data, gas, nonce, and other fields). | **Example request:** @@ -174,9 +181,9 @@ Every method below is also browsable interactively in the explorer above; this s #### `eth_signTransaction` -**Limited.** Signs a transaction with a node-hosted key and returns the signed payload without broadcasting. +**Limited.** Signs a transaction with a node-hosted key and returns the signed payload without broadcasting it. -**Sei-specific behavior:** Requires a node-hosted key for the from address; not usable on public RPC nodes that hold no keys. Returns both the raw RLP bytes and the decoded tx. +**Sei-specific behavior:** Requires a node-hosted key for the from address. It does not work on public RPC nodes that hold no keys. Returns both the raw RLP bytes and the decoded transaction. **Parameters:** @@ -208,7 +215,7 @@ Every method below is also browsable interactively in the explorer above; this s **Limited.** Signs an EIP-191 personal message with a node-hosted key for the given address. -**Sei-specific behavior:** Only works for addresses in the node's local test keyring; production/public RPC nodes hold no hosted keys, so this returns 'address does not have hosted key'. Applies the EIP-191 personal-message TextHash before signing. +**Sei-specific behavior:** Works only for addresses in the node's local test keyring. Production and public RPC nodes hold no hosted keys, so on those nodes this method returns 'address does not have hosted key'. Applies the EIP-191 personal-message TextHash before signing. **Parameters:** @@ -236,9 +243,9 @@ Every method below is also browsable interactively in the explorer above; this s #### `eth_getTransactionByHash` -**Supported.** Returns the EVM transaction matching the given hash, or null if not found. +**Supported.** Returns the EVM transaction that matches the given hash, or null if it is not found. -**Sei-specific behavior:** Sees EVM transactions only; if the hash resolves to a non-EVM Cosmos tx it errors. Pending lookups resolve the transaction directly from the CometBFT mempool via an EVM-hash index (rather than a geth txpool), so a pending EVM tx is found by its hash without scanning through unconfirmed-transaction pages. +**Sei-specific behavior:** Looks up EVM transactions only. If the hash resolves to a non-EVM Cosmos transaction, the method returns an error. Pending lookups resolve the transaction directly from the CometBFT mempool through an EVM-hash index, not a geth txpool. As a result, the method finds a pending EVM transaction by its hash without scanning through pages of unconfirmed transactions. **Parameters:** @@ -261,9 +268,15 @@ Every method below is also browsable interactively in the explorer above; this s #### `eth_getTransactionReceipt` -**Supported.** Returns the receipt of a transaction by hash, or null if not found. +**Supported.** Returns the receipt of a transaction by hash, or null if it is not found. + +**Sei-specific behavior:** The receipt is reconstructed from keeper.GetReceipt and CometBFT block data, not from a native MPT receipt trie. The status and logs use the standard Ethereum format. + +Under the Giga executor, an EVM transaction can bump the sender's nonce and then fail during state transition. For such a transaction, the method returns a `status=0` failed-transaction receipt. It does not return null indefinitely, which would hang clients that poll for the receipt. The known natural case is an EIP-7623 floor-data-gas shortfall (post-Pectra), which fails inside go-ethereum's `Execute()` before any opcode runs. This synthetic receipt is written at EndBlock, with `gasUsed` and `effectiveGasPrice` of 0. -**Sei-specific behavior:** Receipt is reconstructed from keeper.GetReceipt + CometBFT block data rather than from a native MPT receipt trie; status/logs are standard Ethereum format. Under the Giga executor, an EVM transaction that bumps the sender's nonce but then fails during state transition now returns a `status=0` failed-tx receipt, rather than returning null indefinitely and hanging clients that poll for it. The known natural case is an EIP-7623 floor-data-gas shortfall (post-Pectra), which fails inside go-ethereum's `Execute()` before any opcode runs. The receipt is a synthetic one written at EndBlock, with `gasUsed` and `effectiveGasPrice` of 0. The `VmError` reason is not part of the `eth_getTransactionReceipt` response; retrieve it with the non-standard `eth_getVMError` method. If a receipt exists but its block height is above the safe-latest watermark (for example when Tendermint status momentarily lags the receipt store), the method returns JSON null rather than an error — the Ethereum JSON-RPC 'not yet mined' signal — so clients simply poll again, matching `eth_getBlockByNumber` behavior. +The `VmError` reason is not part of the `eth_getTransactionReceipt` response. To get it, use the non-standard `eth_getVMError` method. + +If a receipt exists but its block height is above the safe-latest watermark, the method returns JSON null rather than an error. This can happen, for example, when the Tendermint status lags the receipt store for a moment. JSON null is the Ethereum JSON-RPC 'not yet mined' signal, so clients poll again. This matches the behavior of `eth_getBlockByNumber`. **Parameters:** @@ -288,7 +301,7 @@ Every method below is also browsable interactively in the explorer above; this s **Supported.** Returns the EVM transaction at the given index within the block at the specified number. -**Sei-specific behavior:** Index maps over EVM transactions only; an out-of-range index yields a null result rather than an error. +**Sei-specific behavior:** The index counts EVM transactions only. An out-of-range index returns a null result, not an error. **Parameters:** @@ -315,7 +328,7 @@ Every method below is also browsable interactively in the explorer above; this s **Supported.** Returns the EVM transaction at the given index within the block identified by hash. -**Sei-specific behavior:** Index maps over EVM transactions only; same null-on-overflow semantics as the block-number variant. +**Sei-specific behavior:** The index counts EVM transactions only. As with the block-number variant, an out-of-range index returns null. **Parameters:** @@ -342,14 +355,14 @@ Every method below is also browsable interactively in the explorer above; this s **Supported.** Returns the number of transactions sent from an address (nonce) at a given block. -**Sei-specific behavior:** For the 'pending' tag Sei returns EvmNextPendingNonce from the CometBFT mempool (or redirects to an EvmProxy if the sender is sharded there). safe/finalized/latest are equivalent due to instant finality. +**Sei-specific behavior:** For the 'pending' tag, Sei returns EvmNextPendingNonce from the CometBFT mempool. If the sender is sharded to an EvmProxy, Sei redirects the request there. The safe, finalized, and latest tags are equivalent because of instant finality. **Parameters:** | # | Name | Type | Description | | :- | :- | :- | :- | | 1 | `address` | DATA, 20 bytes | Account address. | -| 2 | `blockNrOrHash` | BLOCKNUMBER or DATA | Block number, tag, or hash; 'pending' returns the next pending nonce. | +| 2 | `blockNrOrHash` | BLOCKNUMBER or DATA | Block number, tag, or hash. The 'pending' tag returns the next pending nonce. | **Example request:** @@ -369,7 +382,7 @@ Every method below is also browsable interactively in the explorer above; this s **Limited.** Sei-specific helper that returns the current EVM nonce for an address (latest state only). -**Sei-specific behavior:** Non-standard Sei extension exposed as eth_getNonce, implemented as StateAPI.GetNonce in state.go (NOT on TransactionAPI). Unlike eth_getTransactionCount it takes no block tag (latest-only via ctxProvider(LatestCtxHeight)) and returns a bare uint64 with no block-tag argument. Prefer eth_getTransactionCount for standard nonce queries. +**Sei-specific behavior:** This non-standard Sei extension is exposed as `eth_getNonce` and implemented as StateAPI.GetNonce in `state.go` (not on TransactionAPI). Unlike `eth_getTransactionCount`, it takes no block tag (latest only, through ctxProvider(LatestCtxHeight)) and returns a bare uint64. For standard nonce queries, prefer `eth_getTransactionCount`. **Parameters:** @@ -394,7 +407,7 @@ Every method below is also browsable interactively in the explorer above; this s **Limited.** Sei extension that returns the recorded VM error string for a transaction by hash (empty string if it succeeded or is not found). -**Sei-specific behavior:** Non-standard Sei extension registered under the eth namespace. Unlike eth_getVMError, a not-found lookup returns an empty string and no error. +**Sei-specific behavior:** This non-standard Sei extension is registered under the eth namespace. Unlike `eth_getVMError`, this method returns an empty string and no error for a not-found lookup. **Parameters:** @@ -419,7 +432,7 @@ Every method below is also browsable interactively in the explorer above; this s **Limited.** Sei extension that returns the EVM VM error string recorded in a transaction's receipt by hash. -**Sei-specific behavior:** Non-standard Sei extension registered under the eth namespace. Returns the receipt's VmError field and propagates a not-found error (unlike eth_getTransactionErrorByHash, which returns an empty string on not-found). +**Sei-specific behavior:** This non-standard Sei extension is registered under the eth namespace. It returns the receipt's VmError field and propagates a not-found error. In contrast, `eth_getTransactionErrorByHash` returns an empty string when the transaction is not found. **Parameters:** @@ -447,7 +460,7 @@ Every method below is also browsable interactively in the explorer above; this s **Supported.** Returns the wei balance of an account at a given block. -**Sei-specific behavior:** Balance reflects the account's SEI bank balance (18-decimal wei representation) and can change from both EVM and non-EVM (Cosmos bank send / wasm) transactions. Height is resolved via the watermark manager with a state-version guard. +**Sei-specific behavior:** The balance reflects the account's SEI bank balance (18-decimal wei representation). Both EVM and non-EVM transactions (Cosmos bank send or wasm) can change it. The height is resolved through the watermark manager with a state-version guard. **Parameters:** @@ -499,7 +512,7 @@ Every method below is also browsable interactively in the explorer above; this s **Supported.** Returns the value stored at a storage slot of an address at a given block. -**Sei-specific behavior:** Reads the EVM keeper's slot value directly rather than from an MPT trie. The slot key must decode to at most 32 bytes. +**Sei-specific behavior:** Reads the slot value directly from the EVM keeper, not from an MPT trie. The slot key must decode to at most 32 bytes. **Parameters:** @@ -528,7 +541,9 @@ Every method below is also browsable interactively in the explorer above; this s **Limited.** Returns a Merkle proof for an account and the requested storage slots. -**Sei-specific behavior:** Sei stores state in an IAVL-style tree, not an Ethereum Merkle-Patricia trie. The handler unwraps the EVM store through any intervening wrappers (cache, tracing, Giga cache, prefix stores) until it reaches an underlying proof-capable queryable store — classic IAVL, a store/v2 memiavl commitment, or any other proof-capable root — so proofs work across these backends rather than only classic IAVL. If no proof-capable queryable store can be reached it returns `cannot find a proof-capable queryable KV store`. The result is a Sei-specific ProofResult{address, hexValues, storageProof} where storageProof entries are CometBFT/IAVL crypto.ProofOps, NOT eth-style MPT proof nodes. There is no accountProof, balance, codeHash, nonce, or storageHash field (Sei has no per-account state root); standard eth_getProof verifiers will not work. +**Sei-specific behavior:** Sei stores state in an IAVL-style tree, not an Ethereum Merkle-Patricia trie. The handler unwraps the EVM store through any intervening wrappers (cache, tracing, Giga cache, prefix stores). It continues until it reaches an underlying proof-capable queryable store: classic IAVL, a store/v2 memiavl commitment, or any other proof-capable root. Proofs therefore work across these backends, not only on classic IAVL. If the handler cannot reach a proof-capable queryable store, it returns `cannot find a proof-capable queryable KV store`. + +The result is a Sei-specific ProofResult{address, hexValues, storageProof}. Its storageProof entries are CometBFT/IAVL crypto.ProofOps, not eth-style MPT proof nodes. The result has no accountProof, balance, codeHash, nonce, or storageHash field (Sei has no per-account state root). Standard `eth_getProof` verifiers do not work with it. **Parameters:** @@ -559,7 +574,7 @@ Every method below is also browsable interactively in the explorer above; this s **Limited.** Returns the list of addresses for which the node holds hosted keys. -**Sei-specific behavior:** Sourced from the node's local test keyring only; production/public RPC nodes hold no hosted keys, so this returns an empty list. Sign client-side and use eth_sendRawTransaction. +**Sei-specific behavior:** The list comes only from the node's local test keyring. Production and public RPC nodes hold no hosted keys, so on those nodes this method returns an empty list. Sign client-side and use `eth_sendRawTransaction`. **Parameters:** none. @@ -570,14 +585,14 @@ Every method below is also browsable interactively in the explorer above; this s **Supported.** Returns block information by number or tag, with full transactions when fullTx is true. -**Sei-specific behavior:** Under the eth namespace only EVM transactions are indexed (synthetic/bank-transfer txs excluded). Block number 0 returns a synthetic genesis block (for The Graph compatibility); future/non-existent numeric blocks return null. Uncle/PoW header fields (sha3Uncles, nonce, mixHash, difficulty) are placeholders and the uncles array is always empty (CometBFT consensus). safe/finalized/latest are equivalent due to instant finality. +**Sei-specific behavior:** Under the eth namespace, only EVM transactions are indexed. Synthetic and bank-transfer transactions are excluded. Block number 0 returns a synthetic genesis block, for compatibility with The Graph. Future or non-existent numeric blocks return null. Uncle and PoW header fields (sha3Uncles, nonce, mixHash, difficulty) are placeholders, and the uncles array is always empty (CometBFT consensus). The safe, finalized, and latest tags are equivalent because of instant finality. **Parameters:** | # | Name | Type | Description | | :- | :- | :- | :- | | 1 | `number` | BLOCKNUMBER | Block number (hex) or tag (latest/safe/finalized/pending/earliest). | -| 2 | `fullTx` | boolean | If true include full transaction objects, else only hashes. | +| 2 | `fullTx` | boolean | If true, the block includes full transaction objects. Otherwise, it includes only hashes. | **Example request:** @@ -597,14 +612,16 @@ Every method below is also browsable interactively in the explorer above; this s **Supported.** Returns block information by block hash, with full transactions when fullTx is true. -**Sei-specific behavior:** Block hashes are CometBFT block hashes (computed from the Tendermint header), so they differ from Ethereum block hashes and are not interchangeable across chains. Under the eth namespace synthetic txs and bank transfers are excluded. The genesis block hash (`0xF9D3845DF25B43B1C6926F3CEDA6845C17F5624E12212FD8847D0BA01DA1AB9E`, a synthetic constant identical on every Sei network, returned by the node in this uppercase form; lookups are case-insensitive) is recognized and returns the encoded genesis block directly, keeping hash-based lookups consistent with `eth_getBlockByNumber("0x0")`; other unknown/zero hashes return null. Uncles array is always empty. +**Sei-specific behavior:** Block hashes are CometBFT block hashes, computed from the Tendermint header. They differ from Ethereum block hashes and are not interchangeable across chains. Under the eth namespace, synthetic transactions and bank transfers are excluded. The uncles array is always empty. + +The genesis block hash is `0xF9D3845DF25B43B1C6926F3CEDA6845C17F5624E12212FD8847D0BA01DA1AB9E`. It is a synthetic constant, identical on every Sei network. The node returns it in this uppercase form, and lookups are case-insensitive. The method recognizes this hash and returns the encoded genesis block directly. This keeps hash-based lookups consistent with `eth_getBlockByNumber("0x0")`. Other unknown or zero hashes return null. **Parameters:** | # | Name | Type | Description | | :- | :- | :- | :- | | 1 | `blockHash` | DATA, 32 bytes | Block hash. | -| 2 | `fullTx` | boolean | If true include full transaction objects, else only hashes. | +| 2 | `fullTx` | boolean | If true, the block includes full transaction objects. Otherwise, it includes only hashes. | **Example request:** @@ -624,7 +641,9 @@ Every method below is also browsable interactively in the explorer above; this s **Supported.** Returns the number of EVM transactions in a block by number, as a hex quantity. -**Sei-specific behavior:** Counts the same transactions that appear in `eth_getBlockByNumber`'s transaction list. EVM transactions are counted only when a receipt exists for them, while synthetic (wasm `MsgExecuteContract`) and bank-transfer (`MsgSend`) transactions remain excluded. Genesis returns 0x0; non-existent/future blocks return null. Because the receipt store can be configured with a smaller `KeepRecent` than the block/state stores, this method now verifies that the requested block's receipts have not been pruned before counting: if they have, it returns an error of the form `requested height N receipts have been pruned; earliest available is M` rather than a count. This means the call can fail for older blocks even when the block data itself is still available. +**Sei-specific behavior:** Counts the same transactions that appear in the transaction list of `eth_getBlockByNumber`. EVM transactions are counted only when a receipt exists for them. Synthetic (wasm `MsgExecuteContract`) and bank-transfer (`MsgSend`) transactions remain excluded. Genesis returns 0x0. Non-existent or future blocks return null. + +The receipt store can be configured with a smaller `KeepRecent` than the block and state stores. For this reason, the method verifies that the requested block's receipts have not been pruned before it counts. If they have, it returns an error of the form `requested height N receipts have been pruned; earliest available is M` instead of a count. As a result, the call can fail for older blocks even when the block data itself is still available. **Parameters:** @@ -649,7 +668,7 @@ Every method below is also browsable interactively in the explorer above; this s **Supported.** Returns the number of EVM transactions in a block by hash, as a hex quantity. -**Sei-specific behavior:** Counts EVM transactions only; synthetic/bank-transfer txs are excluded. Genesis hash returns 0x0; unknown hash returns null. Like `eth_getBlockTransactionCountByNumber`, returns a "receipts have been pruned" error when the requested block's receipts have been pruned from the receipt store. +**Sei-specific behavior:** Counts EVM transactions only. Synthetic and bank-transfer transactions are excluded. The genesis hash returns 0x0, and an unknown hash returns null. Like `eth_getBlockTransactionCountByNumber`, it returns a "receipts have been pruned" error if the requested block's receipts have been pruned from the receipt store. **Parameters:** @@ -674,7 +693,7 @@ Every method below is also browsable interactively in the explorer above; this s **Supported.** Returns all EVM transaction receipts for a given block. -**Sei-specific behavior:** Under the eth namespace synthetic/shell receipts are excluded (includeShellReceipts=false). Genesis returns an empty array. An empty (zero) or non-existent/unknown block hash returns `result: null` rather than an error, matching the Ethereum RPC spec. transactionIndex is recomputed sequentially over the compacted receipt list. +**Sei-specific behavior:** Under the eth namespace, synthetic and shell receipts are excluded (includeShellReceipts=false). Genesis returns an empty array. An empty (zero), non-existent, or unknown block hash returns `result: null` instead of an error. This matches the Ethereum RPC spec. The transactionIndex value is recomputed sequentially over the compacted receipt list. **Parameters:** @@ -702,7 +721,7 @@ Every method below is also browsable interactively in the explorer above; this s **Supported.** Returns the number of the most recent committed EVM block as a hex uint64. -**Sei-specific behavior:** Block height comes from CometBFT latest height; the latest committed block is already final on Sei (instant finality, so latest == safe == finalized). +**Sei-specific behavior:** The block height comes from the latest CometBFT height. The latest committed block is already final on Sei (instant finality, so latest == safe == finalized). **Parameters:** none. @@ -710,7 +729,7 @@ Every method below is also browsable interactively in the explorer above; this s **Supported.** Returns the EVM chain ID as a hex big int. -**Sei-specific behavior:** Sourced from the x/evm keeper. Sei Mainnet = 1329 (`0x531`); Sei Testnet = 1328 (`0x530`). +**Sei-specific behavior:** The value comes from the x/evm keeper. Sei Mainnet is 1329 (`0x531`), and Sei Testnet is 1328 (`0x530`). **Parameters:** none. @@ -718,7 +737,7 @@ Every method below is also browsable interactively in the explorer above; this s **Limited.** Returns the block reward beneficiary (coinbase) address. -**Sei-specific behavior:** Sei has no miner; this returns the Cosmos fee-collector module address (GetFeeCollectorAddress), not a validator/miner address. The COINBASE opcode returns the same value. +**Sei-specific behavior:** Sei has no miner. This method returns the Cosmos fee-collector module address (GetFeeCollectorAddress), not a validator or miner address. The COINBASE opcode returns the same value. **Parameters:** none. @@ -726,7 +745,9 @@ Every method below is also browsable interactively in the explorer above; this s **Limited.** Returns a suggested gas price in wei (hex). -**Sei-specific behavior:** Sei-specific congestion heuristic, not a raw mempool oracle. InfoAPI.GasPrice/GasPriceHelper (info.go): when uncongested it returns baseFee * 110/100 (base fee +10%); when congested it returns medianRewardPrevBlock + baseFee (50th-percentile priority-fee reward from the previous block added to base fee). The base fee comes from the x/evm keeper (GetNextBaseFeePerGas), which is itself floored at the governance-set minimum base fee; the RPC handler applies no additional explicit lower-bound clamp. The mainnet minimum gas price (~50 gwei) is enforced for transaction acceptance at the mempool/ante-handler level, not inside eth_gasPrice. +**Sei-specific behavior:** The method uses a Sei-specific congestion heuristic, not a raw mempool oracle. The logic is in InfoAPI.GasPrice and GasPriceHelper (`info.go`). When the chain is uncongested, the method returns baseFee * 110/100 (base fee +10%). When the chain is congested, it returns medianRewardPrevBlock + baseFee. This is the 50th-percentile priority-fee reward from the previous block, added to the base fee. + +The base fee comes from the x/evm keeper (GetNextBaseFeePerGas) and is itself floored at the governance-set minimum base fee. The RPC handler applies no other explicit lower-bound clamp. The Sei Mainnet minimum gas price (approximately 50 gwei) is enforced for transaction acceptance at the mempool or ante-handler level, not inside `eth_gasPrice`. **Parameters:** none. @@ -734,7 +755,7 @@ Every method below is also browsable interactively in the explorer above; this s **Limited.** Returns a suggested priority fee (tip) per gas in wei (hex). -**Sei-specific behavior:** Sei-specific: returns a hardcoded 1 gwei (defaultPriorityFeePerGas) when the chain is uncongested; only when congested does it derive the tip from the previous block's 50th-percentile reward. Sei docs advise using a single gasPrice and omitting EIP-1559 fee fields. +**Sei-specific behavior:** When the chain is uncongested, the method returns a hardcoded 1 gwei (defaultPriorityFeePerGas). It derives the tip from the previous block's 50th-percentile reward only when the chain is congested. The Sei docs advise you to use a single gasPrice and omit the EIP-1559 fee fields. **Parameters:** none. @@ -742,7 +763,11 @@ Every method below is also browsable interactively in the explorer above; this s **Supported.** Returns base fees, gas-used ratios, and reward percentile data over a range of blocks. -**Sei-specific behavior:** Base fees and rewards reflect Sei's x/evm fee market (GetNextBaseFee), not an Ethereum EIP-1559 mempool, and Sei does not burn the base fee. Watermark-aware: pruned/historical blocks may not be available as far back as on Ethereum archive nodes. Matching go-ethereum/execution-apis semantics, on ranges where every block has base-fee data, `baseFeePerGas` contains one more element than `gasUsedRatio`: the trailing element is the projected base fee for the child of the newest block in the range, appended only when the newest block's own header base fee was available. Heights with pruned or partial base-fee data are skipped from `baseFeePerGas` while still contributing a `gasUsedRatio` row (0.0 fallback), so the two arrays can diverge from that `+1` relationship on ranges with pruned history. Each block's base fee uses header base fee semantics (the same value reported in the block header — `GetNextBaseFee` at the parent's committed height) with a `DefaultMinFeePerGas` fallback for early blocks. +**Sei-specific behavior:** Base fees and rewards reflect Sei's x/evm fee market (GetNextBaseFee), not an Ethereum EIP-1559 mempool. Sei does not burn the base fee. The method is watermark-aware: pruned or historical blocks may not be available as far back as on Ethereum archive nodes. + +On ranges where every block has base-fee data, `baseFeePerGas` contains one more element than `gasUsedRatio`. This matches go-ethereum and execution-apis semantics. The trailing element is the projected base fee for the child of the newest block in the range. It is appended only when the newest block's own header base fee was available. + +Heights with pruned or partial base-fee data are skipped in `baseFeePerGas`, but they still contribute a `gasUsedRatio` row (0.0 fallback). On ranges with pruned history, the two arrays can therefore diverge from that `+1` relationship. Each block's base fee uses header base fee semantics. That is the same value that the block header reports: `GetNextBaseFee` at the parent's committed height. For early blocks, the base fee falls back to `DefaultMinFeePerGas`. **Parameters:** @@ -773,9 +798,9 @@ Every method below is also browsable interactively in the explorer above; this s #### `net_version` -**Supported.** Returns the network/chain ID as a decimal string. +**Supported.** Returns the network ID (chain ID) as a decimal string. -**Sei-specific behavior:** Returns the EVM chain ID in decimal (alias of `eth_chainId`): `'1329'` on Sei Mainnet and `'1328'` on Sei Testnet. +**Sei-specific behavior:** Returns the EVM chain ID in decimal (an alias of `eth_chainId`): `'1329'` on Sei Mainnet and `'1328'` on Sei Testnet. **Parameters:** none. @@ -783,7 +808,7 @@ Every method below is also browsable interactively in the explorer above; this s **Supported.** Returns the client version string. -**Sei-specific behavior:** Reports a synthetic 'Geth/<os>-<arch>/<goVersion>' string (Sei's EVM is backed by go-ethereum); it does NOT embed the actual sei-chain/seid version, so it is not a reliable Sei version indicator. +**Sei-specific behavior:** Reports a synthetic 'Geth/<os>-<arch>/<goVersion>' string (Sei's EVM is backed by go-ethereum). The string does not include the actual sei-chain or `seid` version, so it is not a reliable Sei version indicator. **Parameters:** none. @@ -794,7 +819,7 @@ Every method below is also browsable interactively in the explorer above; this s **Supported.** Creates a log filter for the given criteria and returns a filter ID for later polling. -**Sei-specific behavior:** Subject to the same range/size caps as eth_getLogs: open-ended ranges return up to 10,000 logs (DefaultMaxLogLimit); close-ended ranges are limited to 2,000 blocks (DefaultMaxBlockRange), with large-query rate limiting. +**Sei-specific behavior:** Has the same range and size caps as `eth_getLogs`. Open-ended ranges return up to 10,000 logs (DefaultMaxLogLimit). Close-ended ranges are limited to 2,000 blocks (DefaultMaxBlockRange), and large queries are rate-limited. **Parameters:** @@ -829,7 +854,7 @@ Every method below is also browsable interactively in the explorer above; this s **Supported.** Polls a filter and returns new logs (log filters) or block hashes (block filters) since the last poll. -**Sei-specific behavior:** For log filters, returns an empty array (`[]`) rather than `null` when no logs match or a bounded filter's block range has been fully consumed, in line with the Ethereum JSON-RPC spec. +**Sei-specific behavior:** For log filters, the method returns an empty array (`[]`) instead of `null` when no logs match. It does the same when a bounded filter's block range has been fully consumed. This is in line with the Ethereum JSON-RPC spec. **Parameters:** @@ -852,9 +877,9 @@ Every method below is also browsable interactively in the explorer above; this s #### `eth_getFilterLogs` -**Supported.** Returns all logs matching a previously created log filter, including historical logs. +**Supported.** Returns all logs that match a previously created log filter, including historical logs. -**Sei-specific behavior:** Bounded by the same caps as eth_getLogs (2,000-block range, 10,000-log limit) with large-query rate limiting. +**Sei-specific behavior:** Has the same caps as `eth_getLogs` (2,000-block range, 10,000-log limit). Large queries are rate-limited. **Parameters:** @@ -877,9 +902,9 @@ Every method below is also browsable interactively in the explorer above; this s #### `eth_getLogs` -**Supported.** Returns logs matching the given filter criteria. +**Supported.** Returns the logs that match the given filter criteria. -**Sei-specific behavior:** Returns EVM logs only. Hard limits: max 2,000 blocks per close-ended query and up to 10,000 logs per response; exceeding the range errors with 'block range too large'. Large queries are globally rate-limited. +**Sei-specific behavior:** Returns EVM logs only. The hard limits are a maximum of 2,000 blocks per close-ended query and up to 10,000 logs per response. A query that exceeds the range limit fails with 'block range too large'. Large queries are rate-limited globally. **Parameters:** @@ -907,9 +932,9 @@ Every method below is also browsable interactively in the explorer above; this s #### `eth_uninstallFilter` -**Supported.** Removes a previously installed filter by ID; returns true if it existed and was removed. +**Supported.** Removes a previously installed filter by ID. Returns true if the filter existed and was removed. -**Sei-specific behavior:** Returns false if the filter did not exist rather than erroring. Filters also expire automatically when not polled. +**Sei-specific behavior:** Returns false, not an error, if the filter did not exist. Filters also expire automatically when they are not polled. **Parameters:** @@ -934,7 +959,7 @@ Every method below is also browsable interactively in the explorer above; this s **Limited.** Opens a WebSocket-only push subscription for newHeads or logs notifications. -**Sei-specific behavior:** WebSocket-only (SubscriptionAPI is not registered on the HTTP server; returns rpc.ErrNotificationsUnsupported over HTTP). Only 'newHeads' and 'logs' are implemented in source; there is no 'newPendingTransactions' subscription despite some client docs implying otherwise. newHeads subscriptions are capped by MaxSubscriptionsNewHead. +**Sei-specific behavior:** Available over WebSocket only. SubscriptionAPI is not registered on the HTTP server, so over HTTP the method returns rpc.ErrNotificationsUnsupported. Only 'newHeads' and 'logs' are implemented in source. There is no 'newPendingTransactions' subscription, although some client docs imply otherwise. MaxSubscriptionsNewHead caps newHeads subscriptions. **Parameters:** @@ -964,15 +989,15 @@ The `filter` object applies only to `logs` subscriptions. For `newHeads`, pass t #### `eth_unsubscribe` -**Supported.** Cancels an existing WebSocket subscription by ID; returns true on success. +**Supported.** Cancels an existing WebSocket subscription by ID. Returns true on success. -**Sei-specific behavior:** WebSocket only; has no effect over HTTP (notifications unsupported there). +**Sei-specific behavior:** Available over WebSocket only. It has no effect over HTTP, where notifications are not supported. **Parameters:** | # | Name | Type | Description | | :- | :- | :- | :- | -| 1 | `subscriptionID` | string | The subscription ID returned by a prior eth_subscribe call. | +| 1 | `subscriptionID` | string | The subscription ID returned by a prior `eth_subscribe` call. | **Example request:** @@ -992,9 +1017,9 @@ The `filter` object applies only to `logs` subscriptions. For `newHeads`, pass t #### `eth_call` -**Supported.** Executes a read-only message call against state without creating a transaction; supports state and block overrides. +**Supported.** Executes a read-only message call against state without creating a transaction. Supports state and block overrides. -**Sei-specific behavior:** Gas is capped by RPCGasCap and execution time by RPCEVMTimeout; a fail-fast limiter may reject with 'eth_call rejected due to rate limit: server busy'. Canonical EVM<->Sei address resolution uses eth_call to the addr precompile at 0x0000000000000000000000000000000000001004. +**Sei-specific behavior:** Gas is capped by RPCGasCap, and execution time is capped by RPCEVMTimeout. A fail-fast limiter may reject the call with 'eth_call rejected due to rate limit: server busy'. Canonical EVM<->Sei address resolution uses `eth_call` to the addr precompile at 0x0000000000000000000000000000000000001004. **Parameters:** @@ -1026,14 +1051,14 @@ The `filter` object applies only to `logs` subscriptions. For `newHeads`, pass t **Supported.** Estimates the gas needed to execute a transaction. -**Sei-specific behavior:** Bounded by RPCGasCap and protected by a fail-fast limiter. Block gas limit on Sei is 12.5M; parallel execution can cause estimates to vary slightly, so size gasLimit with a modest buffer. +**Sei-specific behavior:** The method is bounded by RPCGasCap and protected by a fail-fast limiter. The block gas limit on Sei is 12.5M. Parallel execution can make estimates vary slightly, so set gasLimit with a modest buffer. **Parameters:** | # | Name | Type | Description | | :- | :- | :- | :- | | 1 | `args` | object | Transaction call object. | -| 2 | `blockNrOrHash` | BLOCKNUMBER or DATA | Optional block number, tag, or hash; defaults to latest. | +| 2 | `blockNrOrHash` | BLOCKNUMBER or DATA | Optional block number, tag, or hash. Defaults to latest. | | 3 | `overrides` | object | Optional state overrides. | **Example request:** @@ -1055,9 +1080,9 @@ The `filter` object applies only to `logs` subscriptions. For `newHeads`, pass t #### `eth_estimateGasAfterCalls` -**Limited.** Estimates gas for a transaction after first applying a sequence of preceding calls against the same simulated state. +**Limited.** Estimates gas for a transaction after it applies a sequence of preceding calls to the same simulated state. -**Sei-specific behavior:** Non-standard Sei/geth extension (not part of the standard Ethereum JSON-RPC spec). Same gas-cap and fail-fast-limiter behavior as eth_estimateGas. +**Sei-specific behavior:** This is a non-standard Sei/geth extension (not part of the standard Ethereum JSON-RPC spec). It has the same gas-cap and fail-fast-limiter behavior as `eth_estimateGas`. **Parameters:** @@ -1065,7 +1090,7 @@ The `filter` object applies only to `logs` subscriptions. For `newHeads`, pass t | :- | :- | :- | :- | | 1 | `args` | object | The final call to estimate gas for. | | 2 | `calls` | array of object | Ordered list of preceding calls applied before the estimate. | -| 3 | `blockNrOrHash` | BLOCKNUMBER or DATA | Optional block number, tag, or hash; defaults to latest. | +| 3 | `blockNrOrHash` | BLOCKNUMBER or DATA | Optional block number, tag, or hash. Defaults to latest. | | 4 | `overrides` | object | Optional state overrides. | **Example request:** @@ -1090,14 +1115,14 @@ The `filter` object applies only to `logs` subscriptions. For `newHeads`, pass t **Supported.** Generates an EIP-2930 access list (and gas used) for a transaction. -**Sei-specific behavior:** Defaults to the pending block tag (matching geth). A VM error during simulation is surfaced in the result's 'error' field rather than failing the RPC. +**Sei-specific behavior:** Defaults to the pending block tag, as geth does. If a VM error occurs during simulation, the method reports it in the result's 'error' field instead of failing the RPC. **Parameters:** | # | Name | Type | Description | | :- | :- | :- | :- | | 1 | `args` | object | Transaction call object. | -| 2 | `blockNrOrHash` | BLOCKNUMBER or DATA | Optional block number, tag, or hash; defaults to pending. | +| 2 | `blockNrOrHash` | BLOCKNUMBER or DATA | Optional block number, tag, or hash. Defaults to pending. | **Example request:** @@ -1123,7 +1148,7 @@ The `filter` object applies only to `logs` subscriptions. For `newHeads`, pass t **Limited.** Returns the transactions currently in the pool, grouped by sender address and nonce into pending and queued buckets. -**Sei-specific behavior:** Sei-specific simplification: every unconfirmed EVM tx from the CometBFT mempool is reported under 'pending' and 'queued' is always empty (no geth-style pending/queued nonce-gap distinction). The result set is truncated to the node's MaxTxPoolTxs config, so it may not reflect the entire mempool. +**Sei-specific behavior:** As a simplification, the method reports every unconfirmed EVM transaction from the CometBFT mempool under 'pending'. The 'queued' bucket is always empty (there is no geth-style nonce-gap distinction between pending and queued). The result set is truncated to the node's MaxTxPoolTxs config, so it may not reflect the entire mempool. **Parameters:** none. @@ -1132,9 +1157,11 @@ The `filter` object applies only to `logs` subscriptions. For `newHeads`, pass t #### `debug_traceTransaction` -**Supported.** Replays a transaction by hash and returns an execution trace using the configured tracer. +**Supported.** Replays a transaction by hash and returns an execution trace from the configured tracer. + +**Sei-specific behavior:** Available over HTTP only, because the debug namespace is not registered on the WebSocket server. Supports geth tracers: callTracer, prestateTracer, flatCallTracer, and the struct (opcode) logger. TraceBaker pre-bakes and caches the results of callTracer, prestateTracer, and flatCallTracer. Requires trace-enabled or archive state for the target height. -**Sei-specific behavior:** HTTP-only (the debug namespace is not registered on the WebSocket server). Supports geth tracers (callTracer, prestateTracer, flatCallTracer, struct/opcode logger); callTracer/prestateTracer/flatCallTracer results are pre-baked/cached via TraceBaker. Requires trace-enabled/archive state for the target height. Subject to the max block lookback guard (`max_trace_lookback_blocks`): a request whose target block is older than the configured lookback is rejected with an error of the form `block number X is beyond max lookback of Y`. This guard now applies consistently across all `debug_trace*` endpoints, and such attempts increment the `evmrpc_historical_debug_trace_attempts_total` metric. +The max block lookback guard (`max_trace_lookback_blocks`) applies. If a request's target block is older than the configured lookback, the request is rejected with an error of the form `block number X is beyond max lookback of Y`. Each such request increments the `evmrpc_historical_debug_trace_attempts_total` metric. This guard applies consistently across all `debug_trace*` endpoints. **Parameters:** @@ -1163,7 +1190,7 @@ The `filter` object applies only to `logs` subscriptions. For `newHeads`, pass t **Supported.** Traces all transactions in a block by number and returns per-transaction execution traces. -**Sei-specific behavior:** HTTP-only. safe/finalized/latest are equivalent due to instant finality. Subject to the `max_trace_lookback_blocks` historical guard (see `debug_traceTransaction`). +**Sei-specific behavior:** Available over HTTP only. The safe, finalized, and latest tags are equivalent because of instant finality. The `max_trace_lookback_blocks` historical guard applies (see `debug_traceTransaction`). **Parameters:** @@ -1192,7 +1219,7 @@ The `filter` object applies only to `logs` subscriptions. For `newHeads`, pass t **Supported.** Traces all transactions in a block by hash and returns per-transaction execution traces. -**Sei-specific behavior:** HTTP-only. Subject to the `max_trace_lookback_blocks` historical guard (see `debug_traceTransaction`). +**Sei-specific behavior:** Available over HTTP only. The `max_trace_lookback_blocks` historical guard applies (see `debug_traceTransaction`). **Parameters:** @@ -1221,7 +1248,7 @@ The `filter` object applies only to `logs` subscriptions. For `newHeads`, pass t **Supported.** Executes and traces a call against a block's state without creating a transaction. -**Sei-specific behavior:** HTTP-only. Arbitrary geth tracer names pass through. Tracing on the pending block is not supported. Subject to the `max_trace_lookback_blocks` historical guard (see `debug_traceTransaction`). +**Sei-specific behavior:** Available over HTTP only. Arbitrary geth tracer names pass through. Tracing on the pending block is not supported. The `max_trace_lookback_blocks` historical guard applies (see `debug_traceTransaction`). **Parameters:** @@ -1255,7 +1282,7 @@ The `filter` object applies only to `logs` subscriptions. For `newHeads`, pass t **Limited.** Sei extension that replays a transaction and returns its app/tendermint/receipt state-access traces. -**Sei-specific behavior:** Sei-specific extension (not part of upstream go-ethereum's debug namespace). HTTP-only and subject to historical-debug-trace availability guards. Subject to the `max_trace_lookback_blocks` historical guard (see `debug_traceTransaction`). +**Sei-specific behavior:** This Sei-specific extension is not part of the upstream go-ethereum debug namespace. It is available over HTTP only and subject to the availability guards for historical debug traces. The `max_trace_lookback_blocks` historical guard applies (see `debug_traceTransaction`). **Parameters:** @@ -1278,9 +1305,13 @@ The `filter` object applies only to `logs` subscriptions. For `newHeads`, pass t #### `debug_traceTransactionProfile` -**Limited.** Sei extension that replays a transaction by hash and returns its execution trace alongside a detailed timing and store-access profile. +**Limited.** Sei extension that replays a transaction by hash and returns its execution trace with a detailed timing and store-access profile. -**Sei-specific behavior:** Sei-specific extension (not part of upstream go-ethereum's debug namespace). HTTP-only and subject to historical-debug-trace availability guards. In addition to the standard trace result, it returns a `profile` object breaking down where time was spent — total wall time, historical DB lookup time, and per-phase timings (transaction lookup, block load, historical tx replay, block-context build, tx prepare, execution, and trace-result assembly) — plus a per-module `store` access trace (reads, iterators with the keys they surfaced, and per-operation `stats` roll-ups). Per-tx caps bound the trace size: at most 16 iterators and 64 keys per iterator are retained per module, with overflow flagged via `truncated`. To run this method across a whole block range and generate aggregate reports, use the `seidb trace-profile-report` command. Subject to the `max_trace_lookback_blocks` historical guard (see `debug_traceTransaction`). +**Sei-specific behavior:** This Sei-specific extension is not part of the upstream go-ethereum debug namespace. It is available over HTTP only and subject to the availability guards for historical debug traces. + +In addition to the standard trace result, the method returns a `profile` object that shows where the time was spent. The profile has the total wall time, the historical DB lookup time, and per-phase timings. The phases are transaction lookup, block load, historical transaction replay, block-context build, transaction preparation, execution, and trace-result assembly. The method also returns a per-module `store` access trace. This trace has reads, iterators with the keys they surfaced, and per-operation `stats` roll-ups. + +Per-transaction caps bound the trace size. For each module, the trace retains at most 16 iterators and 64 keys per iterator, and `truncated` flags any overflow. To run this method across a whole block range and generate aggregate reports, use the `seidb trace-profile-report` command. The `max_trace_lookback_blocks` historical guard applies (see `debug_traceTransaction`). **Parameters:** @@ -1289,13 +1320,13 @@ The `filter` object applies only to `logs` subscriptions. For `newHeads`, pass t | 1 | `hash` | DATA, 32 bytes | Transaction hash to trace and profile. | | 2 | `config` | object | Optional tracer config (tracer name, tracerConfig, timeout, reexec, disableStorage/Stack/Memory). | -The response `result` contains a `trace` field (the standard tracer output) and a `profile` object shaped as follows: +The response `result` contains a `trace` field (the standard tracer output) and a `profile` object with this shape: -- `totalNanos` — total wall-clock nanoseconds for the profiled trace. -- `historicalDbLookupNanos` — nanoseconds spent in historical store lookups (get/has/iterator/iteratorNext). -- `otherNanos` — remaining time not attributed to historical lookups or execution. -- `phases` — per-phase timings: `lookupTransactionNanos`, `loadBlockNanos`, `replayHistoricalTxsNanos`, `buildBlockContextNanos`, `prepareTxNanos`, `executionNanos`, `traceResultNanos`. -- `store` — per-module store access trace: `modules` (each with `reads`, `has`, `iterators`, and per-op `stats`) and top-level `stats`. +- `totalNanos`: total wall-clock nanoseconds for the profiled trace. +- `historicalDbLookupNanos`: nanoseconds spent in historical store lookups (get, has, iterator, iteratorNext). +- `otherNanos`: remaining time not attributed to historical lookups or execution. +- `phases`: the per-phase timings `lookupTransactionNanos`, `loadBlockNanos`, `replayHistoricalTxsNanos`, `buildBlockContextNanos`, `prepareTxNanos`, `executionNanos`, and `traceResultNanos`. +- `store`: the per-module store access trace, with `modules` (each with `reads`, `has`, `iterators`, and per-operation `stats`) and top-level `stats`. **Example request:** @@ -1346,22 +1377,22 @@ The response `result` contains a `trace` field (the standard tracer output) and Sei keeps four legacy custom endpoints for address resolution, cross-VM transaction lookup, and synthetic receipts. -The `sei2_*` namespace has been removed. Most legacy `sei_*` methods have also been removed, including block, filter, log, signing, association, and transaction lookup methods. The `sei_*` cleanup is tracked in [sei-chain PR #3927](https://github.com/sei-protocol/sei-chain/pull/3927). +For new integrations, use standard `eth_*` and `debug_*` methods. The four remaining `sei_*` methods are deprecated and scheduled for removal. -The four remaining `sei_*` methods are deprecated and scheduled for removal. Use standard `eth_*` and `debug_*` methods for new integrations. +The `sei2_*` namespace has been removed. Most legacy `sei_*` methods have also been removed, including block, filter, log, signing, association, and transaction lookup methods. The `sei_*` cleanup is tracked in [sei-chain PR #3927](https://github.com/sei-protocol/sei-chain/pull/3927). -There is no remaining block or filter method for discovering synthetic logs from Cosmos-originated transactions. If you already know a synthetic transaction hash, enable `sei_getTransactionReceipt` to retrieve its receipt and logs. +No remaining block or filter method can discover synthetic logs from Cosmos-originated transactions. If you already know a synthetic transaction hash, enable `sei_getTransactionReceipt` to fetch its receipt and logs. -Access is controlled by the `enabled_legacy_sei_apis` setting under `[evm]` in `app.toml`. Only methods explicitly listed in this allowlist are available. Disabled methods return a standard JSON-RPC error (code `-32601`, data `"legacy_sei_deprecated"`). Allowed single-object calls pass through unchanged, with an optional `Sei-Legacy-RPC-Deprecation` HTTP response header signaling deprecation. +The `enabled_legacy_sei_apis` setting under `[evm]` in `app.toml` controls access. Only methods explicitly listed in this allowlist are available. Disabled methods return a standard JSON-RPC error (code `-32601`, data `"legacy_sei_deprecated"`). Allowed single-object calls pass through unchanged, with an optional `Sei-Legacy-RPC-Deprecation` HTTP response header that signals deprecation. -JSON-RPC batches are handled by the gate rather than passed through wholesale. Only allowed methods are forwarded to the inner handler. The handler then merges responses by matching each response's JSON-RPC `id`. Disallowed methods return the usual `-32601` legacy deprecation error in their slot. A batch element that is not a JSON object returns a JSON-RPC `-32600` `"Invalid Request"` error in its slot. +The gate handles JSON-RPC batches. It does not pass them through as a whole. Only allowed methods are forwarded to the inner handler. The handler then merges the responses by matching the JSON-RPC `id` of each response. Disallowed methods return the usual `-32601` legacy deprecation error in their slot. A batch element that is not a JSON object returns a JSON-RPC `-32600` `"Invalid Request"` error in its slot. -Per JSON-RPC 2.0, requests that omit the `id` member are notifications and do not produce a response entry, including within a batch. A request with `"id": null` is not a notification and receives a response. If a batch produces no response objects, the gateway returns an empty HTTP body with HTTP 200 rather than an empty JSON array (`[]`). +In JSON-RPC 2.0, requests that omit the `id` member are notifications. They do not produce a response entry, and this also applies within a batch. A request with `"id": null` is not a notification and receives a response. If a batch produces no response objects, the gateway returns an empty HTTP body with HTTP 200 instead of an empty JSON array (`[]`). ### Legacy API configuration -The `enabled_legacy_sei_apis` setting controls which remaining `sei_*` methods are accessible on the EVM HTTP endpoint. `seid init` enables the three address and cross-VM lookup helpers by default: +The `enabled_legacy_sei_apis` setting controls which remaining `sei_*` methods are accessible on the EVM HTTP endpoint. By default, `seid init` enables the three address and cross-VM lookup helpers: ```toml [evm] @@ -1379,14 +1410,14 @@ Only these four methods are available: | Method | Description | | ------ | ----------- | -| `sei_getSeiAddress` | Get the Sei address associated with an EVM address. | -| `sei_getEVMAddress` | Get the EVM address associated with a Sei address. | -| `sei_getCosmosTx` | Get the wrapping Cosmos transaction hash as uppercase hexadecimal without a `0x` prefix. | -| `sei_getTransactionReceipt` | Get a receipt, including a synthetic receipt when its transaction hash is known. | +| `sei_getSeiAddress` | Returns the Sei address associated with an EVM address. | +| `sei_getEVMAddress` | Returns the EVM address associated with a Sei address. | +| `sei_getCosmosTx` | Returns the wrapping Cosmos transaction hash as uppercase hexadecimal without a `0x` prefix. | +| `sei_getTransactionReceipt` | Returns a receipt, including a synthetic receipt when its transaction hash is known. | ### Address resolution -For resolving the EVM (`0x…`) ↔ Sei (`sei1…`) address pair, use the **`addr` precompile at `0x0000000000000000000000000000000000001004`** via a standard `eth_call`. The precompile is universally available on every Sei RPC, is not part of the deprecated `sei_*` namespace, and is the canonical resolution path going forward. +To resolve the EVM (`0x…`) ↔ Sei (`sei1…`) address pair, use the **`addr` precompile at `0x0000000000000000000000000000000000001004`** through a standard `eth_call`. The precompile is available on every Sei RPC and is not part of the deprecated `sei_*` namespace. It is the canonical resolution path going forward. ```bash # EVM → Sei (getSeiAddr(address), selector 0x0c3c20ed) @@ -1428,15 +1459,15 @@ const evmAddr = await client.readContract({ }); ``` -The call reverts when the input address is not yet associated. See [Accounts](/learn/accounts) for the full association lifecycle and how the bidirectional mapping is established. +The call reverts when the input address is not yet associated. For the full association lifecycle and how the bidirectional mapping is established, see [Accounts](/learn/accounts). -The legacy JSON-RPC helpers `sei_getSeiAddress` and `sei_getEVMAddress` historically served this role and are still enabled by default on nodes today, but they belong to the deprecated `sei_*` namespace and may be removed in a future release. New integrations should call the precompile. +In the past, the legacy JSON-RPC helpers `sei_getSeiAddress` and `sei_getEVMAddress` handled address resolution. They are still enabled by default on nodes today. However, they belong to the deprecated `sei_*` namespace and may be removed in a future release. New integrations should call the precompile. ### Cross-VM transaction lookup -`sei_getCosmosTx` resolves the underlying Cosmos transaction hash for a given EVM transaction. It returns the hash as uppercase hexadecimal without a `0x` prefix. The method does not yet have a precompile equivalent and is enabled by default on Sei nodes. +`sei_getCosmosTx` resolves the underlying Cosmos transaction hash for a given EVM transaction. It returns the hash as uppercase hexadecimal without a `0x` prefix. The method does not have a precompile equivalent yet. It is enabled by default on Sei nodes. - + #### sei_getCosmosTx Returns the wrapping Cosmos transaction hash for a given EVM transaction hash. @@ -1453,7 +1484,7 @@ Returns the wrapping Cosmos transaction hash for a given EVM transaction hash. | :--- | :---------- | | `string` | The Cosmos transaction hash as uppercase hexadecimal without a `0x` prefix. | -**Example Request** +**Example request** ```json { @@ -1468,7 +1499,7 @@ Returns the wrapping Cosmos transaction hash for a given EVM transaction hash. ### Legacy deprecation error -When a remaining `sei_*` method is called but not listed in `enabled_legacy_sei_apis`, the node returns: +If a client calls a remaining `sei_*` method that is not listed in `enabled_legacy_sei_apis`, the node returns: ```json { @@ -1484,10 +1515,10 @@ When a remaining `sei_*` method is called but not listed in `enabled_legacy_sei_ ### Deprecation HTTP header -When an allowlisted `sei_*` method is successfully called, the response includes an optional HTTP header signaling deprecation: +When a call to an allowlisted `sei_*` method succeeds, the response includes an optional HTTP header that signals deprecation: ``` Sei-Legacy-RPC-Deprecation: All sei_* JSON-RPC methods are deprecated and scheduled for removal; migrate to eth_* and supported APIs. ``` -Clients can use this header to detect legacy API usage and plan migration. +Clients can use this header to detect legacy API use and plan their migration. diff --git a/evm/sei-global-wallet.mdx b/evm/sei-global-wallet.mdx index e6128c2..917bcfe 100644 --- a/evm/sei-global-wallet.mdx +++ b/evm/sei-global-wallet.mdx @@ -4,53 +4,53 @@ sidebarTitle: 'Sei Global Wallet' description: 'Learn how to integrate and use Sei Global Wallet, a cross-application embedded crypto wallet that provides persistent wallet experience across Sei ecosystem applications.' keywords: ['sei global wallet', 'embedded wallet', 'EIP-6963', 'wallet integration', 'web3 authentication'] --- -By logging in with Sei Global Wallet, you agree to our [Terms of Use](https://dashboard.sei.io/terms) +By logging in with Sei Global Wallet, you agree to our [Terms of Use](https://dashboard.sei.io/terms). -Sei Global Wallet is a cross-application embedded crypto wallet powered by [Dynamic Global Wallets](https://www.dynamic.xyz/docs/react/global-wallets/overview). It gives users a persistent wallet experience across any integrated app within the Sei ecosystem, allowing them to authenticate and interact using familiar login methods like Google, Twitter, or Telegram—no browser extension or prior crypto knowledge required. +Sei Global Wallet is a cross-application embedded crypto wallet powered by [Dynamic Global Wallets](https://www.dynamic.xyz/docs/react/global-wallets/overview). It gives users a persistent wallet experience across any integrated dApp in the Sei ecosystem. Users can authenticate and interact with familiar login methods, such as Google, Twitter, or Telegram. They do not need a browser extension or prior crypto knowledge. -Additional auth methods such as existing wallet apps (MetaMask, ..) are possible through Dynamic, but are not currently enabled +Other authentication methods are possible through Dynamic, such as existing wallet apps (for example, MetaMask). However, these methods are not currently enabled. ## What is Sei Global Wallet? -Unlike traditional browser extension wallets, Sei Global Wallet is built directly into web applications and allows users to authenticate using familiar methods like Google, Twitter, Telegram, or email—no downloads or crypto knowledge required. +Unlike traditional browser extension wallets, Sei Global Wallet is built directly into web applications. Users can authenticate with familiar methods, such as Google, Twitter, Telegram, or email. They do not need to download anything or know about crypto. -## Why Use Sei Global Wallet? +## Why use Sei Global Wallet? -**For Users:** +**For users:** -- **No Installation Required:** Works directly in your browser without extensions -- **Familiar Authentication:** Login with Google, Twitter, Telegram, or email -- **Persistent Across Apps:** Same wallet works across all Sei ecosystem applications -- **Self-Custodial:** You maintain full control of your keys +- The wallet works directly in the browser, without extensions. +- Users log in with Google, Twitter, Telegram, or email. +- The same wallet works across all Sei ecosystem dApps. +- The wallet is self-custodial: users keep full control of their keys. -**For Developers:** +**For developers:** -- **One-line integration:** A single EIP-6963 import works with RainbowKit, ConnectKit, Web3-React, and other compatible libraries -- **ESM-only:** `@sei-js/sei-global-wallet@2` has no `require()` entry. Add the [required consumer overrides](https://github.com/sei-protocol/sei-js/tree/main/packages/sei-global-wallet#required-consumer-overrides) before installing. +- Integration takes one line: a single EIP-6963 import works with RainbowKit, ConnectKit, Web3-React, and other compatible libraries. +- `@sei-js/sei-global-wallet@2` is ESM-only and has no `require()` entry. Add the [required consumer overrides](https://github.com/sei-protocol/sei-js/tree/main/packages/sei-global-wallet#required-consumer-overrides) before you install it. -## How to Create a Sei Global Wallet Account +## How to create a Sei Global Wallet account -1. Visit [dashboard.sei.io](https://dashboard.sei.io) or any Sei ecosystem application -2. Click "Connect Wallet" and select "Sei Global Wallet" -3. Choose your preferred login method (Google, X, Telegram, or Email) -4. Complete the authentication flow -5. Your wallet is automatically created and ready to use across all integrated Sei apps +1. Go to [dashboard.sei.io](https://dashboard.sei.io) or any Sei ecosystem dApp. +2. Click **Connect Wallet**. Then select **Sei Global Wallet**. +3. Choose your preferred login method (Google, X, Telegram, or Email). +4. Complete the authentication flow. +5. Your wallet is created automatically. You can use it across all integrated Sei dApps. -## How to Integrate Sei Global Wallet +## How to integrate Sei Global Wallet ### Prerequisites -**EIP-6963:** A standard that allows multiple wallets to coexist without conflicts. Instead of fighting over `window.ethereum`, wallets announce themselves through events, letting users choose which one to use. +**EIP-6963:** A standard that lets multiple wallets coexist without conflicts. Instead of competing for `window.ethereum`, wallets announce themselves through events. Users can then choose which wallet to use. -**Dynamic:** The infrastructure powering Sei Global Wallet. It handles authentication, key management, and cross-app wallet persistence while keeping wallets non-custodial. +**Dynamic:** The infrastructure that powers Sei Global Wallet. It handles authentication, key management, and cross-app wallet persistence, and it keeps wallets non-custodial. ## Installation -Add the [required consumer overrides](https://github.com/sei-protocol/sei-js/tree/main/packages/sei-global-wallet#required-consumer-overrides) to your root manifest **before** you install. Dynamic Global Wallet Client pulls `axios` and `uuid` versions with known vulnerabilities, and this package cannot push overrides into your app. The npm block pins `axios` to 1.18.0, `uuid` to 11.1.1, and `ws` to 8.21.0 under `viem`; the Bun block pins `axios` and `uuid` only. Drop the overrides once Dynamic ships a release that fixes those pins. +Add the [required consumer overrides](https://github.com/sei-protocol/sei-js/tree/main/packages/sei-global-wallet#required-consumer-overrides) to your root manifest **before** you install. Dynamic Global Wallet Client pulls `axios` and `uuid` versions with known vulnerabilities. This package cannot push overrides into your app. The npm block pins `axios` to 1.18.0, `uuid` to 11.1.1, and `ws` to 8.21.0 under `viem`. The Bun block pins only `axios` and `uuid`. When Dynamic ships a release that fixes those pins, remove the overrides. -Install Sei Global Wallet Package: +Install the Sei Global Wallet package: ```bash npm install @sei-js/sei-global-wallet @@ -72,15 +72,15 @@ import '@sei-js/sei-global-wallet/eip6963'; `@sei-js/sei-global-wallet@2` is ESM-only. The `/eip6963` import still registers the provider. It also exports `registerEIP6963Provider`, `unregisterEIP6963Provider`, and `eip6963ProviderInfo`. Other entrypoints are `/ethereum`, `/solana`, and `/zerodev`. -**Important:** Importing the package registers the wallet for discovery, but you'll need to ensure your application's provider stack is properly configured to interact with it. Most wallet connection libraries that support EIP-6963 will automatically detect the wallet after import. +Make sure that the provider stack of your dApp is configured correctly to interact with the wallet. Importing the package only registers the wallet for discovery. Most wallet connection libraries that support EIP-6963 detect the wallet automatically after the import. --- -## Integration Examples +## Integration examples -Below are integration examples for different frameworks and wallet provider libraries to properly integrate the pre-configured Sei Global Wallet package. +These examples show how to integrate the preconfigured Sei Global Wallet package with different frameworks and wallet provider libraries. - + **Create a new Vite app:** ```bash @@ -88,13 +88,13 @@ npm create vite@latest my-sei-dapp -- --template react-ts cd my-sei-dapp ``` -**Install Dependencies:** +**Install dependencies:** ```bash npm install @rainbow-me/rainbowkit wagmi viem @tanstack/react-query @sei-js/sei-global-wallet ``` -**Update App.tsx:** +**Update `App.tsx`:** ```tsx import '@rainbow-me/rainbowkit/styles.css'; @@ -156,7 +156,7 @@ export default function App() { } ``` -**Run Your App:** +**Run your app:** ```bash npm run dev @@ -164,7 +164,7 @@ npm run dev - + **Create a new Vite app:** ```bash @@ -172,13 +172,13 @@ npm create vite@latest my-sei-dapp -- --template react-ts cd my-sei-dapp ``` -**Install Dependencies:** +**Install dependencies:** ```bash npm install connectkit wagmi viem @tanstack/react-query @sei-js/sei-global-wallet ``` -**Update App.tsx:** +**Update `App.tsx`:** ```tsx import '@sei-js/sei-global-wallet/eip6963'; @@ -244,7 +244,7 @@ export default function App() { } ``` -**Run Your App:** +**Run your app:** ```bash npm run dev @@ -252,7 +252,7 @@ npm run dev - + **Create a new Vite app:** ```bash @@ -260,13 +260,13 @@ npm create vite@latest my-sei-dapp -- --template react-ts cd my-sei-dapp ``` -**Install Dependencies:** +**Install dependencies:** ```bash npm install @web3-react/core @web3-react/eip1193 @web3-react/types @sei-js/sei-global-wallet ``` -**Update App.tsx:** +**Update `App.tsx`:** ```tsx import '@sei-js/sei-global-wallet/eip6963'; @@ -388,7 +388,7 @@ export default function App() { } ``` -**Run Your App:** +**Run your app:** ```bash npm run dev @@ -396,7 +396,7 @@ npm run dev - + **Create a new Vite app:** ```bash @@ -404,7 +404,7 @@ npm create vite@latest my-sei-dapp -- --template react-ts cd my-sei-dapp ``` -**Install Dependencies:** +**Install dependencies:** ```bash npm install @dynamic-labs/sdk-react-core \ @@ -412,7 +412,7 @@ npm install @dynamic-labs/sdk-react-core \ wagmi viem @tanstack/react-query @sei-js/sei-global-wallet ``` -**Update App.tsx:** +**Update `App.tsx`:** ```tsx import React from 'react'; @@ -520,17 +520,17 @@ function AccountInfo() { } ``` -**Run Your App:** +**Run your app:** ```bash npm run dev ``` -**Note:** Replace `"REPLACE-WITH-YOUR-ENVIRONMENT-ID"` with your actual Dynamic environment ID from your [Dynamic dashboard](https://app.dynamic.xyz/dashboard/overview). +**Note:** Replace `"REPLACE-WITH-YOUR-ENVIRONMENT-ID"` with your Dynamic environment ID from your [Dynamic dashboard](https://app.dynamic.xyz/dashboard/overview). - + **Create a new Next.js app:** ```bash @@ -538,7 +538,7 @@ npx create-next-app@latest my-sei-dapp --typescript --tailwind --eslint cd my-sei-dapp ``` -**Install Dependencies:** +**Install dependencies:** ```bash npm install @dynamic-labs/sdk-react-core \ @@ -547,7 +547,7 @@ npm install @dynamic-labs/sdk-react-core \ @dynamic-labs/ethereum ``` -**layout.tsx:** +**`layout.tsx`:** ```tsx 'use client'; @@ -571,7 +571,7 @@ export default function RootLayout({ children }: { children: React.ReactNode }) } ``` -**lib/providers.tsx:** +**`lib/providers.tsx`:** ```tsx 'use client'; @@ -651,9 +651,9 @@ export default function Providers({ children }: { children: React.ReactNode }) { } ``` -**Note:** Replace `"REPLACE-WITH-YOUR-ENVIRONMENT-ID"` with your actual Dynamic environment ID from your [Dynamic dashboard](https://app.dynamic.xyz/dashboard/overview). +**Note:** Replace `"REPLACE-WITH-YOUR-ENVIRONMENT-ID"` with your Dynamic environment ID from your [Dynamic dashboard](https://app.dynamic.xyz/dashboard/overview). -**page.tsx** +**`page.tsx`:** ```tsx 'use client'; @@ -676,7 +676,7 @@ export default function Home() { } ``` -**Run Your App:** +**Run your app:** ```bash npm run dev @@ -684,23 +684,23 @@ npm run dev - -For projects using plain HTML/JavaScript without a build system, you can create a bundled version of Sei Global Wallet to include directly in your HTML pages. + +If your project uses plain HTML and JavaScript without a build system, you can create a bundled version of Sei Global Wallet. You can then include it directly in your HTML pages. -**Create Bundle Directory** +**Create a bundle directory** ```bash mkdir sei-global-wallet-bundle cd sei-global-wallet-bundle ``` -**Initialize npm Project** +**Initialize an npm project** ```bash npm init -y ``` -**Install Dependencies** +**Install dependencies** ```bash npm install @sei-js/sei-global-wallet @@ -710,16 +710,16 @@ npm install @sei-js/sei-global-wallet npm install --save-dev esbuild ``` -**Create Bundle Source File** -Create bundle.js: +**Create a bundle source file** +Create `bundle.js`: ```js // bundle.js import '@sei-js/sei-global-wallet/eip6963'; ``` -**Update package.json** -Add this build script to your package.json: +**Update `package.json`** +Add this build script to your `package.json` file: ```json { @@ -729,17 +729,17 @@ Add this build script to your package.json: } ``` -**Build the Bundle** +**Build the bundle** ```bash npm run build ``` -This creates sei-wallet-bundled.js +This command creates `sei-wallet-bundled.js`. -**Use in Your HTML Project** +**Use the bundle in your HTML project** -Copy sei-wallet-bundled.js to your web project and use it: +Copy `sei-wallet-bundled.js` to your web project. Then load it in your HTML, as in this example: ```html @@ -847,7 +847,7 @@ Copy sei-wallet-bundled.js to your web project and use it: - + **Create a new Vite app:** ```bash @@ -855,7 +855,7 @@ npm create vite@latest my-sei-dapp -- --template react-ts cd my-sei-dapp ``` -**Install Dependencies:** +**Install dependencies:** ```bash npm install @web3auth/modal \ @@ -863,7 +863,7 @@ npm install @web3auth/modal \ @sei-js/sei-global-wallet ``` -**Create Web3Auth Context (src/web3authContext.ts):** +**Create a Web3Auth context (`src/web3authContext.ts`):** ```ts import '@sei-js/sei-global-wallet/eip6963'; @@ -882,7 +882,7 @@ const web3AuthContextConfig: Web3AuthContextConfig = { export default web3AuthContextConfig; ``` -**Update App.tsx:** +**Update `App.tsx`:** ```tsx import './App.css'; @@ -965,7 +965,7 @@ function App() { export default App; ``` -**Setup your main.tsx with Web3Auth Provider:** +**Set up `main.tsx` with the Web3Auth provider:** ```tsx import { StrictMode } from 'react'; @@ -1001,13 +1001,13 @@ createRoot(document.getElementById('root')!).render( ); ``` -**Run Your App:** +**Run your app:** ```bash npm run dev ``` -**Note:** Replace the `clientId` in `web3authContext.ts` with your actual Web3Auth client ID from your [Web3Auth Dashboard](https://dashboard.web3auth.io). +**Note:** Replace the `clientId` in `web3authContext.ts` with your Web3Auth client ID from your [Web3Auth dashboard](https://dashboard.web3auth.io). @@ -1016,11 +1016,11 @@ npm run dev -### Troubleshooting & Debugging Tips +### Troubleshooting & debugging tips -#### Common Issues +#### Common issues -**Issue:** Sei Global Wallet doesn't appear in wallet list +**Issue:** Sei Global Wallet does not appear in the wallet list ```bash # Ensure the import is at the top of your App.tsx @@ -1053,7 +1053,7 @@ chainId: '0x531'; // for Sei Mainnet (1329) chainId: '0x530'; // for Sei Testnet (1328) ``` -### Debugging Commands +### Debugging commands ```javascript window.addEventListener('eip6963:announceProvider', (event) => { @@ -1063,21 +1063,21 @@ window.addEventListener('eip6963:announceProvider', (event) => { window.dispatchEvent(new Event('eip6963:requestProvider')); ``` -### Testing Tips +### Testing tips -1. **Test with multiple browsers** to ensure cross-browser compatibility -2. **Clear browser cache** if wallets aren't appearing -3. **Check browser console** for EIP-6963 events and errors -4. **Test both testnet and mainnet** connections -5. **Verify social login methods** work across different auth providers +1. Test with multiple browsers to check cross-browser compatibility. +2. If wallets do not appear, clear the browser cache. +3. Check the browser console for EIP-6963 events and errors. +4. Test connections to both Sei Testnet and Sei Mainnet. +5. Verify that social login methods work across different authentication providers. -### Security Considerations +### Security considerations -- Sei Global Wallet is **self-custodial** - users control their private keys -- All communications between app and wallet are **encrypted** -- **Multi-factor authentication** is available for enhanced security -- Keys can be **exported** to other wallets like MetaMask -- Platform has been **audited by Cure53** for security compliance +- Sei Global Wallet is self-custodial: users control their private keys. +- All communications between the dApp and the wallet are encrypted. +- Multi-factor authentication is available for extra security. +- Users can export their keys to other wallets, such as MetaMask. +- Cure53 has audited the platform for security compliance. @@ -1085,78 +1085,78 @@ window.dispatchEvent(new Event('eip6963:requestProvider')); #### Q: What is Sei Global Wallet? -Sei Global Wallet is an embedded wallet experience for the Sei network, enabling wallet creation and authentication through social logins. Unlike traditional embedded wallets, Sei Global Wallet offer greater flexibility by allowing users to carry their wallets across different apps within the Sei ecosystem. +Sei Global Wallet is an embedded wallet for the Sei network. Users create a wallet and authenticate through social logins. Unlike traditional embedded wallets, Sei Global Wallet gives users more flexibility: they can carry their wallets across different dApps in the Sei ecosystem. #### Q: What are the key benefits of Sei Global Wallet for developers and users? -**For Developers:** +**For developers:** -- **Sei ecosystem front and center:** Add Sei as a login method to your app ("Log in with Sei") -- **Simple integration:** Compatible with tools like RainbowKit, ConnectKit, and Web3-React -- **Enhanced security:** Multi-factor authentication (MFA) and secure key management +- You can add Sei as a login method to your dApp ("Log in with Sei"). +- Integration is simple. The wallet is compatible with tools such as RainbowKit, ConnectKit, and Web3-React. +- Multi-factor authentication (MFA) and secure key management improve security. -**For Users:** +**For users:** -- **Simplified onboarding:** Create wallets using familiar social logins -- **Cross-app connectivity:** Navigate seamlessly across Sei ecosystem applications -- **User-friendly flows:** Transaction simulation helps users understand impacts before confirmation +- Users create wallets with familiar social logins, which simplifies onboarding. +- Users can move between Sei ecosystem dApps with the same wallet. +- Transaction simulation helps users understand the effects of a transaction before they confirm it. #### Q: What login methods are currently supported? -Sei Global Wallet support email, Google, X (Twitter), and Telegram authentication. +Sei Global Wallet supports email, Google, X (Twitter), and Telegram authentication. #### Q: How do the security considerations differ from traditional wallets? -Key security differences include: +Security differences include: -- **Secure encrypted communication:** All communication between app and wallet popup is encrypted -- **Protection against replay attacks:** Encrypted messaging prevents malicious reuse of data -- **Trusted Execution Environments (TEEs):** Operations occur within secure environments -- **Verified origins:** Only verified origins can interact with Sei Global Wallet +- **Secure encrypted communication:** All communication between the dApp and the wallet popup is encrypted. +- **Protection against replay attacks:** Encrypted messaging prevents malicious reuse of data. +- **Trusted Execution Environments (TEEs):** Operations occur in secure environments. +- **Verified origins:** Only verified origins can interact with Sei Global Wallet. #### Q: Is Sei Global Wallet self-custodial or custodial? -Sei Global Wallet is self-custodial, giving full control to end-users. Users can export their keys at any time and import them into other wallets, such as MetaMask. +Sei Global Wallet is self-custodial, so users have full control. Users can export their keys at any time and import them into other wallets, such as MetaMask. #### Q: Do Sei Global Wallet require browser extensions? -No, they operate as embedded wallets that work directly in the browser without requiring extensions. +No. They are embedded wallets that work directly in the browser, without extensions. #### Q: Can I link my existing external wallet to my Sei Global Wallet? -Not currently. In the future, you will be able to link external wallets to a Sei global account. +No, not currently. In the future, you will be able to link external wallets to a Sei global account. #### Q: What extra protections can I add to my Sei Global Wallet? -While Global Wallets are non-custodial, good security practices include: +Although Global Wallets are non-custodial, good security practices include: -- **Enable multi-factor authentication (MFA)** for sensitive actions -- **Be wary of phishing attempts** - verify sources before sharing information -- **Always have backup methods** - link additional email or social login methods -- **Never store authentication keys digitally** - keep private keys secure offline +- Enable multi-factor authentication (MFA) for sensitive actions. +- Be careful of phishing attempts. Verify sources before you share information. +- Always have backup methods. Link more email or social login methods. +- Never store authentication keys digitally. Keep private keys secure and offline. #### Q: Have Sei Global Wallet been audited? -Yes, the Dynamic Global Wallets product has been audited by Cure53. +Yes. Cure53 has audited the Dynamic Global Wallets product. #### Q: How should bugs be reported? -Please provide: +Include this information: - Device details - Browser information -- Clear description of the issue +- A clear description of the issue - If possible, a Loom video or screen recording -## References and Links +## References and links -- [Dynamic Global Wallet Documentation](https://www.dynamic.xyz/docs/react/global-wallets/overview) -- [EIP-6963 Standard](https://eips.ethereum.org/EIPS/eip-6963) -- [RainbowKit Documentation](https://www.rainbowkit.com/docs/introduction) -- [ConnectKit Documentation](https://docs.family.co/connectkit) -- [Web3-React Documentation](https://github.com/Uniswap/web3-react) -- [Wagmi Documentation](https://wagmi.sh) +- [Dynamic Global Wallet documentation](https://www.dynamic.xyz/docs/react/global-wallets/overview) +- [EIP-6963 standard](https://eips.ethereum.org/EIPS/eip-6963) +- [RainbowKit documentation](https://www.rainbowkit.com/docs/introduction) +- [ConnectKit documentation](https://docs.family.co/connectkit) +- [Web3-React documentation](https://github.com/Uniswap/web3-react) +- [wagmi documentation](https://wagmi.sh) - [WalletConnect Cloud](https://cloud.walletconnect.com) diff --git a/evm/sei-js/create-sei.mdx b/evm/sei-js/create-sei.mdx index fb8bb4e..a82686e 100644 --- a/evm/sei-js/create-sei.mdx +++ b/evm/sei-js/create-sei.mdx @@ -9,7 +9,7 @@ keywords: ['create-sei', 'scaffold', 'cli', 'sei', 'nextjs', 'wagmi', 'viem', 't npx @sei-js/create-sei app -n my-sei-app ``` -The generated project includes Wagmi, Viem, RainbowKit, TypeScript, Tailwind CSS, Mantine UI, and Biome. It pins `@sei-js/precompiles` 3.x. +The generated project includes wagmi, viem, RainbowKit, TypeScript, Tailwind CSS, Mantine UI, and Biome. It pins `@sei-js/precompiles` 3.x. ## Quick start @@ -28,14 +28,14 @@ You do not need to install `@sei-js/create-sei` globally. `-n` and `--name` are -The project name must be an unscoped lowercase npm package name (`my-sei-app`). Scoped names, spaces, and most punctuation are rejected. +The project name must be an unscoped lowercase npm package name, for example `my-sei-app`. The CLI rejects scoped names, spaces, and most punctuation. ## Interactive setup -Run the command without `-n` to enter the project name interactively: +To enter the project name interactively, run the command without `-n`: ```bash npx @sei-js/create-sei app @@ -51,7 +51,7 @@ bun run dev -Open `http://localhost:3000`. The generated dApp connects to Sei Mainnet when `NEXT_PUBLIC_CHAIN` is unset. Set `NEXT_PUBLIC_CHAIN=testnet` in `.env.local` to use Sei Testnet. The template's `.env.example` already sets that value, so copying it to `.env.local` selects testnet. +Open `http://localhost:3000`. If `NEXT_PUBLIC_CHAIN` is not set, the generated dApp connects to Sei Mainnet. To use Sei Testnet, set `NEXT_PUBLIC_CHAIN=testnet` in `.env.local`. The template's `.env.example` already sets that value. If you copy it to `.env.local`, the dApp uses Sei Testnet. @@ -67,17 +67,19 @@ Open `http://localhost:3000`. The generated dApp connects to Sei Mainnet when `N ## Default template -The default template is a Next.js EVM dApp. Wagmi and Viem provide typed blockchain interactions. RainbowKit provides wallet connections and defaults to the generic injected connector, not a MetaMask-only setup. +The default template is a Next.js EVM dApp. It uses wagmi and viem for typed blockchain interactions. RainbowKit handles wallet connections. It defaults to the generic injected connector, not a MetaMask-only setup. -The template pins Next.js 15, React 19, Wagmi 2, Viem 2, RainbowKit 2, TanStack Query 5, Tailwind CSS 4, Mantine 8, Biome 2, and `@sei-js/precompiles` 3.x. Exact versions live in the generated `package.json`. +The template pins Next.js 15, React 19, wagmi 2, viem 2, RainbowKit 2, and TanStack Query 5. It also pins Tailwind CSS 4, Mantine 8, Biome 2, and `@sei-js/precompiles` 3.x. The exact versions are in the generated `package.json`. ```bash npx @sei-js/create-sei app -n my-sei-app ``` -The template declares `packageManager: bun@1.3.14`, so use Bun 1.3.14 or newer for `bun install` and `bun run dev`. Its `overrides` block pins patched transitive dependencies in the npm and Bun format. Yarn reads `resolutions` and pnpm reads `pnpm.overrides`, so both skip those pins and resolve a different, unverified dependency graph. +The template declares `packageManager: bun@1.3.14`. Use Bun 1.3.14 or newer for `bun install` and `bun run dev`. Its `overrides` block pins patched transitive dependencies in the npm and Bun format. Yarn reads `resolutions`, and pnpm reads `pnpm.overrides`. Both skip those pins and resolve a different, unverified dependency graph. -WalletConnect-based wallets need `NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID` in `.env.local`. The injected connector works without it. Next.js image optimization is disabled in the template because of a Sharp version conflict, so `next/image` serves unoptimized images. +WalletConnect-based wallets need `NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID` in `.env.local`. The injected connector works without it. + +The template disables Next.js image optimization because of a Sharp version conflict. As a result, `next/image` serves unoptimized images. ## Extensions @@ -100,17 +102,17 @@ npx @sei-js/create-sei app -n my-sei-precompile-app --extension precompiles ## Included configuration - Next.js App Router project structure -- Wallet connections through Wagmi, RainbowKit, and the injected browser-wallet connector -- Sei Mainnet and Sei Testnet configuration via `NEXT_PUBLIC_CHAIN` +- Wallet connections through wagmi, RainbowKit, and the injected browser-wallet connector +- Sei Mainnet and Sei Testnet configuration through `NEXT_PUBLIC_CHAIN` - TypeScript, Biome, Mantine UI, and Tailwind CSS -Install [Node.js](https://nodejs.org/) 20 or newer to run the CLI with `npx`. That is the version the generated project's `.nvmrc` pins. Install [Bun](https://bun.sh/docs/installation) 1.3.14 or newer to install and run the generated project. +To run the CLI with `npx`, install [Node.js](https://nodejs.org/) 20 or newer. The generated project's `.nvmrc` pins that version. To install and run the generated project, install [Bun](https://bun.sh/docs/installation) 1.3.14 or newer. ## Troubleshooting -- If `bun install` fails, confirm `bun --version` reports 1.3.14 or newer. -- For Node.js version conflicts when running `npx`, use `nvm` to switch to Node 20 or newer. -- For npm permission errors, do not use `sudo`. Use `nvm` or fix your npm permissions. -- For registry timeouts, run `npm config set registry https://registry.npmjs.org/` before retrying `npx`. +- If `bun install` fails, confirm that `bun --version` reports 1.3.14 or newer. +- If you get a Node.js version conflict when you run `npx`, use `nvm` to switch to Node 20 or newer. +- If you get npm permission errors, do not use `sudo`. Use `nvm` or fix your npm permissions. +- If the registry times out, run `npm config set registry https://registry.npmjs.org/` before you run `npx` again. diff --git a/evm/sei-js/index.mdx b/evm/sei-js/index.mdx index 288a693..1c5f76d 100644 --- a/evm/sei-js/index.mdx +++ b/evm/sei-js/index.mdx @@ -4,29 +4,29 @@ sidebarTitle: 'Introduction' description: 'TypeScript packages for building EVM applications on Sei' keywords: ['sei-js', 'typescript', 'sdk', 'sei network', 'evm', 'precompiles', 'wallet', 'mcp'] --- -`@sei-js` is a set of TypeScript packages for building EVM applications on Sei. Use the packages for Sei-specific functionality, and use standard EVM libraries such as Viem or Ethers.js for everything else. +`@sei-js` is a set of TypeScript packages for building EVM applications on Sei. Use the packages for Sei-specific functionality, and use standard EVM libraries such as viem or ethers.js for everything else. -Sei is EVM-compatible, so you can also use Foundry, Hardhat, Wagmi, and other Ethereum tooling. `@sei-js` adds precompile ABIs, chain definitions, wallet integration, network metadata, scaffolding, and an MCP server. +Sei is EVM-compatible, so you can also use Foundry, Hardhat, wagmi, and other Ethereum tooling. `@sei-js` adds precompile ABIs, chain definitions, wallet integration, network metadata, scaffolding, and an MCP server. -@sei-js is open source. Contribute at [github.com/sei-protocol/sei-js](https://github.com/sei-protocol/sei-js). +`@sei-js` is open source. Contribute at [github.com/sei-protocol/sei-js](https://github.com/sei-protocol/sei-js). -Current npm majors are ESM-only: `@sei-js/precompiles@3`, `@sei-js/registry@2`, `@sei-js/create-sei@2`, `@sei-js/sei-global-wallet@2`, and `@sei-js/mcp-server@1`. Use `import`. `require()` does not resolve these packages. `@sei-js/precompiles` needs Viem 2.55.16 or newer. The MCP server needs Node.js 20 or newer. `@sei-js/ledger` is not part of the current monorepo. +The current npm major versions are ESM-only: `@sei-js/precompiles@3`, `@sei-js/registry@2`, `@sei-js/create-sei@2`, `@sei-js/sei-global-wallet@2`, and `@sei-js/mcp-server@1`. Use `import`. `require()` does not resolve these packages. `@sei-js/precompiles` needs viem 2.55.16 or newer. The MCP server needs Node.js 20 or newer. `@sei-js/ledger` is not part of the current monorepo. ## Why @sei-js? - Typed ABIs and addresses for Sei precompiles -- Viem's Sei Mainnet and Sei Testnet chain definitions re-exported for convenience, plus a `seiLocal` definition for local nodes +- 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 ## Packages ### [@sei-js/precompiles](/evm/precompiles) -Import precompile addresses and raw `*_PRECOMPILE_ABI` constants from the package root, `@sei-js/precompiles/precompiles`, or `@sei-js/precompiles/viem`. Ethers factories live on `@sei-js/precompiles/ethers`. +Import precompile addresses and raw `*_PRECOMPILE_ABI` constants from the package root, `@sei-js/precompiles/precompiles`, or `@sei-js/precompiles/viem`. Import the ethers factories from `@sei-js/precompiles/ethers`. -Viem owns the `sei` and `seiTestnet` chain definitions, so import those from `viem/chains`. The root and `viem` entrypoints re-export them if you would rather use a single import, and they also export `seiLocal` for a local node. +The `sei` and `seiTestnet` chain definitions are part of viem, so import them from `viem/chains`. If you prefer a single import, the root and `viem` entrypoints re-export them. These entrypoints also export `seiLocal` for a local node. ```bash npm install @sei-js/precompiles@^3 @@ -42,7 +42,7 @@ npx @sei-js/create-sei app ### [@sei-js/sei-global-wallet](/evm/sei-global-wallet) -Add the EIP-6963 compatible Sei Global Wallet to a dApp. +Add the EIP-6963-compatible Sei Global Wallet to a dApp. ```bash npm install @sei-js/sei-global-wallet @@ -66,24 +66,24 @@ npx @sei-js/mcp-server ## Deprecated packages -The five packages above are the entire current monorepo. Every other `@sei-js` package is deprecated on npm and no longer maintained. If one of these appears in your `package.json`, migrate off it. +The five packages above are the entire current monorepo. Every other `@sei-js` package is deprecated on npm and no longer maintained. If your `package.json` includes one of these deprecated packages, migrate away from it. | Deprecated package | What to use instead | | --- | --- | -| `@sei-js/evm` | `@sei-js/precompiles` — same library, renamed | -| `@sei-js/ledger` | No replacement. See [Ledger with ethers](/evm/ledger-ethers) for the EVM signing flow | +| `@sei-js/evm` | `@sei-js/precompiles` (the same library, renamed) | +| `@sei-js/ledger` | No replacement. For the EVM signing flow, see [Ledger with ethers](/evm/ledger-ethers) | | `@sei-js/x402` | `@x402/core` and `@x402/evm`. See [x402 on Sei](/ai/x402) | | `@sei-js/x402-fetch` | `@x402/fetch` and `@x402/evm` | | `@sei-js/x402-axios` | `@x402/axios` and `@x402/evm` | | `@sei-js/x402-express` | `@x402/express`, `@x402/core`, and `@x402/evm` | | `@sei-js/x402-hono` | `@x402/hono`, `@x402/core`, and `@x402/evm` | | `@sei-js/x402-next` | `@x402/next`, `@x402/core`, and `@x402/evm` | -| `@sei-js/core` | No replacement. Use Viem or Ethers.js for EVM access | +| `@sei-js/core` | No replacement. Use viem or ethers.js for EVM access | | `@sei-js/cosmjs` | No replacement | | `@sei-js/cosmos` | No replacement | | `@sei-js/proto` | No replacement | -The last four covered Cosmos SDK access, which is deprecated under [SIP-3](/learn/sip-03-migration). Build on the EVM instead. +The last four packages covered Cosmos SDK access, which is deprecated under [SIP-3](/learn/sip-03-migration). Build on the EVM instead. ## Quick start @@ -96,47 +96,47 @@ bun install bun run dev ``` -See [Scaffold Sei](/evm/sei-js/create-sei) for the generated template and CLI options. +For the generated template and CLI options, see [Scaffold Sei](/evm/sei-js/create-sei). ## Examples -End-to-end code examples using viem and ethers with Sei: +These end-to-end code examples use viem and ethers with Sei: - + Read chain data, send transactions, and interact with contracts in a Node.js script or backend. - - The same patterns using ethers v6, including browser provider and event listening. + + The same patterns with ethers v6, including the browser provider and event listening. - - Connect wallets, read balances, and write contracts in a React app using Wagmi hooks. + + Connect wallets, read balances, and write contracts in a React dApp with wagmi hooks. - + Read metadata, check balances, transfer tokens, approve spenders, and query transfer history. - + Check ownership, transfer NFTs, manage approvals, and watch transfer events. - + Batch balance queries, single and batch transfers, operator approvals, and event watching. - Batch multiple contract reads into a single RPC call with Multicall3 and viem/ethers/wagmi. + Batch multiple contract reads into a single RPC call with Multicall3 and viem, ethers, or wagmi. - + Look up pointer addresses for existing CW20 and CW721 contracts, then interact with them through ERC interfaces. - + Native balances, staking, rewards, and governance voting from JavaScript. - - Deploy contracts with viem, ethers, Foundry, or Hardhat and verify on Seiscan via Sourcify. + + Deploy contracts with viem, ethers, Foundry, or Hardhat, and verify them on Seiscan through Sourcify. - + Send transactions, wait for receipts, and decode event logs. - + Decode reverts, handle wallet rejections, and retry transient RPC failures. diff --git a/evm/sei-js/registry.mdx b/evm/sei-js/registry.mdx index 636de8e..5217ecd 100644 --- a/evm/sei-js/registry.mdx +++ b/evm/sei-js/registry.mdx @@ -8,7 +8,7 @@ keywords: ['sei-js', 'registry', 'chain constants', 'rpc endpoints', 'token list `@sei-js/registry` exports typed chain IDs, endpoints, token metadata, and wallet information for Sei Mainnet and Sei Testnet. Network and wallet data comes from the official [sei-protocol/chain-registry](https://github.com/sei-protocol/chain-registry). Token metadata comes from the community-maintained [Seitrace asset list](https://github.com/Seitrace/sei-assetlist). -The package is ESM-only. Sei Mainnet and Sei Testnet are the only supported networks. `CHAIN_IDS.devnet`, `GAS_INFO`, and `IBC_INFO` are no longer exported. +The package is ESM-only. Sei Mainnet and Sei Testnet are the only supported networks. The package no longer exports `CHAIN_IDS.devnet`, `GAS_INFO`, or `IBC_INFO`. ## Installation @@ -19,7 +19,7 @@ npm install @sei-js/registry ## CHAIN_IDS -Canonical chain IDs for each Sei network: +`CHAIN_IDS` has the canonical chain ID for each Sei network: ```ts import { CHAIN_IDS } from '@sei-js/registry'; @@ -28,11 +28,11 @@ CHAIN_IDS.mainnet // 'pacific-1' CHAIN_IDS.testnet // 'atlantic-2' ``` -Use these constants anywhere you reference a Sei network by chain ID to avoid hardcoding strings. +To avoid hardcoded strings, use these constants wherever you reference a Sei network by chain ID. ## NETWORKS -RPC, REST, gRPC, EVM RPC, WebSocket, and explorer endpoints for each network: +`NETWORKS` has the RPC, REST, gRPC, EVM RPC, WebSocket, and explorer endpoints for each network: ```ts import { NETWORKS, type Network } from '@sei-js/registry'; @@ -50,7 +50,7 @@ const evmWs = mainnet.evm_ws?.[0].url; const rest = mainnet.rest[0].url; ``` -Each endpoint has `provider` and `url` fields. You can iterate through the available providers to implement fallback logic: +Each endpoint has `provider` and `url` fields. To implement fallback logic, you can iterate through the available providers: ```ts async function getWorkingRpc(network: Network) { @@ -73,10 +73,10 @@ async function getWorkingRpc(network: Network) { ## TOKEN_LIST -Token metadata per network includes names, symbols, base denominations, decimal exponents, images, and CoinGecko IDs: +The token metadata for each network includes names, symbols, base denominations, decimal exponents, images, and CoinGecko IDs: -`TOKEN_LIST` filters assets whose base or denomination starts with `ibc/`, along with assets marked as ICS-20. The community asset list may still contain legacy tokenfactory entries for display or compatibility. Do not treat those entries as supported integration targets. Tokenfactory is not supported for new development. +Do not treat legacy tokenfactory entries as supported integration targets. Tokenfactory is not supported for new development. `TOKEN_LIST` filters assets whose base or denomination starts with `ibc/`, along with assets marked as ICS-20. The community asset list may still contain legacy tokenfactory entries for display or compatibility. ```ts @@ -94,11 +94,11 @@ console.log(sei?.type_asset); console.log(sei?.pointer_contract); ``` -Exported entries use `RegistryToken`, so `type_asset` is required. `images.png`, `images.svg`, and `coingecko_id` are optional. NFT entries can have an empty `denom_units` array. Some assets also include optional `pointer_contract` metadata (`address` plus `cw20` or `erc20`). Identify an asset by network and `base` denomination, not by pointer data alone. +Exported entries use the `RegistryToken` type, so `type_asset` is required. `images.png`, `images.svg`, and `coingecko_id` are optional. NFT entries can have an empty `denom_units` array. Some assets also include optional `pointer_contract` metadata (`address` plus `cw20` or `erc20`). Identify an asset by network and `base` denomination, not by pointer data alone. ## CHAIN_INFO -`CHAIN_INFO` contains mainnet metadata such as the `seid` binary name, Bech32 prefix, fee token, SLIP-44 coin type, and supported native wallets: +`CHAIN_INFO` contains Sei Mainnet metadata such as the `seid` binary name, Bech32 prefix, fee token, SLIP-44 coin type, and supported native wallets: ```ts import { CHAIN_INFO } from '@sei-js/registry'; @@ -135,7 +135,7 @@ const keplr = WALLETS.find(w => w.identifier === 'keplr'); // url: 'https://www.keplr.app', capabilities: ['native', 'evm'] } ``` -The current list is MetaMask (`evm`), Keplr (`native` and `evm`), and Coin98 (`native`). That is separate from `CHAIN_INFO.supported_wallets`, which is the upstream native-wallet list (`keplr`, `coin98`). +The current list is MetaMask (`evm`), Keplr (`native` and `evm`), and Coin98 (`native`). This list is separate from `CHAIN_INFO.supported_wallets`, which is the upstream native-wallet list (`keplr`, `coin98`). ## Supported networks @@ -145,4 +145,4 @@ The current list is MetaMask (`evm`), Keplr (`native` and `evm`), and Coin98 (`n | EVM chain ID | 1329 | 1328 | | EVM RPC | `NETWORKS['pacific-1'].evm_rpc` | `NETWORKS['atlantic-2'].evm_rpc` | | EVM WebSocket | `NETWORKS['pacific-1'].evm_ws` | `NETWORKS['atlantic-2'].evm_ws` | -| Faucets | — | `NETWORKS['atlantic-2'].faucets` | +| Faucets | None | `NETWORKS['atlantic-2'].faucets` | diff --git a/evm/solidity-resources.mdx b/evm/solidity-resources.mdx index 4fddcea..20cdf34 100644 --- a/evm/solidity-resources.mdx +++ b/evm/solidity-resources.mdx @@ -9,65 +9,65 @@ keywords: - ethereum development - web3 resources --- -Most development resources for developing with Soldity on Ethereum Mainnet also apply to development on Sei. +Most Solidity development resources for Ethereum Mainnet also apply to Sei. -This page suggests a minimal set of resources for getting started with building a decentralized app for Sei EVM. +This page lists a minimal set of resources to help you start building a dApp on Sei EVM. ## IDEs - **[Remix](https://remix.ethereum.org)** - An interactive Solidity IDE that is the easiest and fastest way to start coding and compiling Solidity smart contracts without any additional installations. + An interactive Solidity IDE. You can use it to start coding and compiling Solidity smart contracts without installing anything. - **[VSCode](https://code.visualstudio.com)** + **[Solidity extension](https://marketplace.visualstudio.com/items?itemName=NomicFoundation.hardhat-solidity)** ## Basic Solidity - **[CryptoZombies](https://cryptozombies.io/en/course)** - A great end-to-end introduction to building dApps on the EVM. It offers lessons suitable for complete beginners as well as developers from other disciplines. + An end-to-end introduction to building dApps on the EVM. It has lessons for complete beginners and for developers from other disciplines. - **[Solidity by Example](https://solidity-by-example.org)** - Introduces Solidity concepts progressively through simple examples – ideal for developers with some programming background. + Introduces Solidity concepts progressively through simple examples. It suits developers who have some programming background. - **[Blockchain Basics course by Cyfrin Updraft](https://updraft.cyfrin.io/courses/blockchain-basics)** Covers the fundamentals of blockchain, DeFi, and smart contracts. - **[Solidity Smart Contract Development by Cyfrin Updraft](https://updraft.cyfrin.io/courses/solidity)** - Offers hands-on experience to become a smart contract developer. + Gives you hands-on experience to become a smart contract developer. ## Intermediate Solidity - **[The Solidity Language](https://docs.soliditylang.org)** - Official documentation providing an end-to-end description of smart contracts, blockchain basics, compiling, and deployment on an EVM. + Official documentation with an end-to-end description of smart contracts, blockchain basics, compiling, and deployment on an EVM. - **[Solidity Patterns](https://github.com/fravoll/solidity-patterns)** - A repository of code templates with explanations of their usage. + A repository of code templates, with explanations of how to use them. - **[OpenZeppelin](https://www.openzeppelin.com)** - Provides a library of customizable template contracts for common Ethereum token deployments (e.g., ERC20, ERC721, ERC1155, Proxy). Note that these are not gas optimized. They provide the defacto standard for smart contract templates and are used across almost all existing smart contracts. + A library of customizable template contracts for common Ethereum token deployments, such as ERC-20, ERC-721, ERC-1155, and Proxy. These contracts are not gas optimized. They are the de facto standard for smart contract templates, and almost all existing smart contracts use them. - **[Uniswap](https://github.com/Uniswap)** - A professional, easy-to-digest smart contract of the [Uniswap V2 pools](https://github.com/Uniswap/v2-core) that gives an overview of an in-production Solidity dApp. A guided walkthrough is available [here](https://ethereum.org/en/developers/tutorials/uniswap-v2-annotated-code/). For the more advanced Uniswap Pools, check out the Uniswap V3 [here](https://github.com/Uniswap/v3-core) and Uniswap V4 [here](https://github.com/Uniswap/v4-core). + A professional, easy-to-read smart contract for the [Uniswap V2 pools](https://github.com/Uniswap/v2-core). It gives an overview of a Solidity dApp in production. A [guided walkthrough](https://ethereum.org/en/developers/tutorials/uniswap-v2-annotated-code/) is available. For the more advanced Uniswap pools, see [Uniswap V3](https://github.com/Uniswap/v3-core) and [Uniswap V4](https://github.com/Uniswap/v4-core). - **[Morpho Finance](https://github.com/morpho-org)** - Morpho Finance's contracts provides an excellent real-world example of production-grade Solidity smart contracts, demonstrating how a successful DeFi lending protocol is structured and implemented. By studying Morpho's codebase, you can learn advanced patterns for gas optimization, security best practices, and complex financial logic implementation in a production environment. The accompanying documentation [here](https://docs.morpho.org/overview/) offers additional context to understand the protocol's architecture and design principles. + Morpho Finance's contracts are a real-world example of production-grade Solidity smart contracts. They show how a successful DeFi lending protocol is structured and implemented. In Morpho's codebase, you can learn advanced patterns for gas optimization and security best practices. You can also see how to implement complex financial logic in production. The accompanying [documentation](https://docs.morpho.org/overview/) gives more context on the protocol's architecture and design principles. - **[Sky / Maker DAO](https://github.com/makerdao)** - A pioneering DeFi protocol that created the DAI and USDS stablecoin. MakerDAO's codebase showcases complex financial mechanisms including collateralized debt positions, oracles, and governance systems. The project demonstrates how to implement a stable cryptocurrency backed by crypto collateral through sophisticated risk management systems. + An early DeFi protocol that created the DAI and USDS stablecoins. MakerDAO's codebase shows complex financial mechanisms, including collateralized debt positions, oracles, and governance systems. The project demonstrates how to implement a stable cryptocurrency, backed by crypto collateral, through sophisticated risk management systems. - **[Rareskills Blog](https://rareskills.io/blog)** - Features in-depth articles on various Solidity concepts and their [Book of Gas Optimization](https://www.rareskills.io/post/gas-optimization). + Has in-depth articles on various Solidity concepts. It also has the [Book of Gas Optimization](https://www.rareskills.io/post/gas-optimization). - **[Foundry Fundamentals course by Cyfrin Updraft](https://updraft.cyfrin.io/courses/foundry)** - A comprehensive web3 development course covering Foundry—the industry-standard framework for building, deploying, and testing smart contracts. + A web3 development course on Foundry, the industry-standard framework for building, deploying, and testing smart contracts. - **[Smart Contract Programmer YT channel](https://www.youtube.com/@smartcontractprogrammer)** - Contains many in-depth videos covering topics from ABI encoding to EVM memory management. + Has many in-depth videos on topics from ABI encoding to EVM memory management. - **[DeFi developer roadmap](https://github.com/OffcierCia/DeFi-Developer-Road-Map)** ## Advanced Solidity - **[Solmate repository](https://github.com/transmissions11/solmate)** and **[Solady repository](https://github.com/Vectorized/solady)** - Gas-optimized contracts using Solidity or Yul. + Gas-optimized contracts written in Solidity or Yul. - **[Yul](https://docs.soliditylang.org/en/latest/yul.html)** - An intermediate language for Solidity, akin to inline assembly for the EVM, offering control flow constructs while exposing low-level memory management. + An intermediate language for Solidity, similar to inline assembly for the EVM. It has control flow constructs and exposes low-level memory management. - **[Advanced Foundry course by Cyfrin Updraft](https://updraft.cyfrin.io/courses/advanced-foundry)** - Teaches advanced smart contract development including building DeFi protocols, stablecoins, DAOs, and more. + Teaches advanced smart contract development, including how to build DeFi protocols, stablecoins, DAOs, and more. - **[Smart Contract Security course by Cyfrin Updraft](https://updraft.cyfrin.io/courses/security)** - Provides comprehensive training on auditing and writing secure protocols. + Teaches you how to audit protocols and write secure ones. - **[Assembly and Formal Verification course by Cyfrin Updraft](https://updraft.cyfrin.io/courses/formal-verification)** - Covers Assembly, using Yul, EVM opcodes, formal verification testing, and related tools. + Covers assembly with Yul, EVM opcodes, formal verification testing, and related tools. - **[Smart Contract DevOps course by Cyfrin Updraft](https://updraft.cyfrin.io/courses/wallets)** Focuses on post-deployment security, wallet access control, and ongoing protocol maintenance. - **[Secureum YT Channel](https://www.youtube.com/@SecureumVideos)** - Features a variety of videos covering topics from Solidity basics to advanced subjects such as fuzzing and auditing. + Has videos on topics from Solidity basics to advanced subjects such as fuzzing and auditing. ## Tutorials @@ -79,11 +79,11 @@ This page suggests a minimal set of resources for getting started with building ## Testing - **[Echidna](https://github.com/crytic/echidna)** - Fuzz testing tool for Solidity. + A fuzz testing tool for Solidity. - **[Slither](https://github.com/crytic/slither)** - A static analysis framework for detecting vulnerabilities. + A static analysis framework that detects vulnerabilities. - **[solidity-coverage](https://github.com/sc-forks/solidity-coverage)** - Provides code coverage metrics for Solidity tests. + Gives code coverage metrics for Solidity tests. ## Smart contract archives @@ -91,37 +91,37 @@ This page suggests a minimal set of resources for getting started with building A collection of contracts verified on Etherscan. - **[EVM function signature database](https://www.4byte.directory)** - **[EVM verified contracts on Etherscan](https://etherscan.io/contractsVerified)** - If you are adventurous: Check the verified contracts on Etherscan directly. + Browse the verified contracts on Etherscan directly. ## Using the OpenZeppelin Wizard -OpenZeppelin provides a convenient web-based wizard to create standard contracts. Visit the docs section for it [here](/evm/evm-wizard) or [https://wizard.openzeppelin.com/](https://wizard.openzeppelin.com/) to access it. +OpenZeppelin has a web-based wizard for creating standard contracts. To use it, see the [EVM Contract Wizard](/evm/evm-wizard) page in these docs, or go to [https://wizard.openzeppelin.com/](https://wizard.openzeppelin.com/). -The wizard allows you to: +With the wizard, you can: -1. Select the contract type (ERC20, ERC721, ERC1155, etc.) +1. Select the contract type (for example, ERC-20, ERC-721, or ERC-1155) 2. Configure settings, features, and access controls 3. Add custom functionality through a user-friendly interface 4. Generate ready-to-use Solidity code -The wizard is perfect for: +The wizard is useful for: -- Beginners learning smart contract development +- Beginners who are learning smart contract development - Quickly bootstrapping standard token contracts - Exploring different configuration options - Understanding best practices in contract development -## Best Practices & Security Considerations +## Best practices & security considerations -When developing on Sei EVM with OpenZeppelin contracts, follow these best practices: +When you develop on Sei EVM with OpenZeppelin contracts, follow these best practices: 1. **Always use the latest version** of OpenZeppelin contracts -2. **Start with existing, audited components** rather than building from scratch -3. **Run comprehensive tests** before deploying to mainnet +2. **Start with existing, audited components** instead of building from scratch +3. **Run comprehensive tests** before you deploy to Sei Mainnet 4. **Consider upgradeability** for complex applications -5. **Use access controls** like `Ownable` or `AccessControl` for privileged functions +5. **Use access controls** such as `Ownable` or `AccessControl` for privileged functions 6. **Implement reentrancy guards** where needed -7. **Avoid `transfer()` and `send()`** for ETH transfers, use `call()` with reentrancy protection +7. **Avoid `transfer()` and `send()`** for ETH transfers. Use `call()` with reentrancy protection instead. 8. **Validate all inputs** and check for edge cases 9. **Consider gas optimization**, but not at the expense of security 10. **Consider getting an audit** for high-value contracts diff --git a/evm/templates.mdx b/evm/templates.mdx index 49da99e..4db5f78 100644 --- a/evm/templates.mdx +++ b/evm/templates.mdx @@ -29,12 +29,12 @@ bun install bun run dev ``` -Open `http://localhost:3000`. The dApp connects to Sei Mainnet unless `.env.local` sets `NEXT_PUBLIC_CHAIN=testnet`. Copy the template's `.env.example` to `.env.local` to use Sei Testnet. +Open `http://localhost:3000`. The dApp connects to Sei Mainnet unless `.env.local` sets `NEXT_PUBLIC_CHAIN=testnet`. To use Sei Testnet, copy the template's `.env.example` to `.env.local`. ## Templates - + The [default template](/evm/sei-js/create-sei#default-template) is a Next.js App Router dApp with typed wallet connections and contract reads and writes. That page lists its stack and pinned versions. ```bash @@ -43,7 +43,7 @@ Open `http://localhost:3000`. The dApp connects to Sei Mainnet unless `.env.loca - The default template plus a Bank [precompile](/evm/precompiles/example-usage) example that queries the native SEI supply through `@sei-js/precompiles`. + This is the default template plus a Bank [precompile](/evm/precompiles/example-usage) example. The example queries the native SEI supply through `@sei-js/precompiles`. ```bash npx @sei-js/create-sei app -n my-sei-precompile-app --extension precompiles @@ -52,23 +52,23 @@ Open `http://localhost:3000`. The dApp connects to Sei Mainnet unless `.env.loca - Run `npx @sei-js/create-sei list-extensions` to see every available extension. The [Scaffold Sei](/evm/sei-js/create-sei) page documents all CLI options and the interactive setup. + To see every available extension, run `npx @sei-js/create-sei list-extensions`. The [Scaffold Sei](/evm/sei-js/create-sei) page documents all CLI options and the interactive setup. ## What the templates include - RainbowKit with the generic injected browser-wallet connector. WalletConnect-based wallets also need `NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID` in `.env.local`. + The templates use RainbowKit with the generic injected browser-wallet connector. WalletConnect-based wallets also need `NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID` in `.env.local`. - Sei Mainnet (EVM chain ID `1329`) and Sei Testnet (EVM chain ID `1328`), selected with `NEXT_PUBLIC_CHAIN`. + The templates support Sei Mainnet (EVM chain ID `1329`) and Sei Testnet (EVM chain ID `1328`). `NEXT_PUBLIC_CHAIN` selects the network. - End-to-end TypeScript with Wagmi and Viem, so contract calls and ABIs are typed. + The templates use TypeScript end to end with wagmi and viem, so contract calls and ABIs are typed. - Tailwind CSS and Mantine UI for styling, and Biome for formatting. + The templates use Tailwind CSS and Mantine UI for styling, and Biome for formatting. @@ -78,15 +78,15 @@ Open `http://localhost:3000`. The dApp connects to Sei Mainnet unless `.env.loca ## Contribute a template -Templates ship as part of `@sei-js/create-sei`. To add one, such as a DeFi starter, an NFT mint, or an x402 payments dApp, open a pull request in [`sei-protocol/sei-js`](https://github.com/sei-protocol/sei-js/tree/main/packages/create-sei). Once it ships in the CLI, it can be listed here. +Templates ship as part of `@sei-js/create-sei`. To add a template, open a pull request in [`sei-protocol/sei-js`](https://github.com/sei-protocol/sei-js/tree/main/packages/create-sei). For example, you can add a DeFi starter, an NFT mint, or an x402 payments dApp. After the template ships in the CLI, it can be listed here. ## Next steps - Every `create-sei` option, extension, and troubleshooting step. + See every `create-sei` option, extension, and troubleshooting step. - Wire Wagmi, Viem, and a wallet into a Sei dApp from first principles. + Connect wagmi, viem, and a wallet to a Sei dApp from first principles. diff --git a/evm/tokens.mdx b/evm/tokens.mdx index 852a0d7..9022b5f 100644 --- a/evm/tokens.mdx +++ b/evm/tokens.mdx @@ -4,15 +4,15 @@ sidebarTitle: 'View Tokens' description: 'Learn how to view and manage different token types in MetaMask with Sei network, including ERC20 tokens, ERC721 NFTs.' keywords: ['metamask tokens', 'erc20', 'erc721', 'nft display'] --- -#### ERC20 Tokens +#### ERC20 tokens -To view ERC20 tokens in MetaMask, the process mirrors that on other EVM chains. -For tokens not automatically listed, you'll need to manually import them into -your wallet. Detailed instructions can be found -[here](https://support.metamask.io/manage-crypto/tokens/how-to-display-tokens-in-metamask/). +To view ERC20 tokens in MetaMask, follow the same process as on other EVM chains. +If a token is not listed automatically, import it into your wallet manually. For +detailed instructions, see the +[MetaMask guide on how to display tokens](https://support.metamask.io/manage-crypto/tokens/how-to-display-tokens-in-metamask/). #### ERC721 NFTs -Viewing NFTs in MetaMask requires manual addition. Follow the steps provided -[here](https://support.metamask.io/manage-crypto/nfts/nft-tokens-in-your-metamask-wallet/) -to add and view your NFTs in the wallet. +You must add NFTs to MetaMask manually before you can view them. To add and view +your NFTs in the wallet, follow the steps in the +[MetaMask NFT guide](https://support.metamask.io/manage-crypto/nfts/nft-tokens-in-your-metamask-wallet/). diff --git a/evm/tracing/index.mdx b/evm/tracing/index.mdx index b99b7a6..4edd7ec 100644 --- a/evm/tracing/index.mdx +++ b/evm/tracing/index.mdx @@ -6,7 +6,7 @@ keywords: ['debug tracing', 'evm debugging', 'transaction analysis', 'gas optimi --- ## Requirements -The examples in this guide call the debug JSON-RPC endpoints directly with `curl` — no SDK or additional libraries are required. Optionally install [`jq`](https://jqlang.github.io/jq/) to pretty-print the JSON responses: +The examples in this guide call the debug JSON-RPC endpoints directly with `curl`. You do not need an SDK or other libraries. To pretty-print the JSON responses, you can install [`jq`](https://jqlang.github.io/jq/): ```bash # macOS @@ -16,51 +16,51 @@ brew install jq sudo apt-get install jq ``` -Debug tracing is your primary tool for understanding EVM transaction execution on Sei. This comprehensive system allows you to analyze transaction flow, optimize gas usage, debug smart contract interactions, and troubleshoot production issues. +Debug tracing is your primary tool to understand how EVM transactions execute on Sei. With it, you can analyze transaction flow, optimize gas usage, debug smart contract interactions, and troubleshoot production issues. -## What You Can Trace +## What you can trace -### Transaction Execution +### Transaction execution - Step-by-step opcode execution - Contract call hierarchy - Gas consumption breakdown - State changes and storage access -### Contract Interactions +### Contract interactions - Cross-contract calls and returns - Event emission analysis - Precompile usage tracking - External library calls -### Performance Analysis +### Performance analysis - Gas optimization opportunities - Bottleneck identification -- Cache hit/miss patterns +- Cache hit and miss patterns - State access efficiency -### Security Analysis +### Security analysis - Suspicious operation detection - Reentrancy pattern analysis - Access control verification - Vulnerability scanning -## Available Tracing Methods +## Available tracing methods -| Method | Purpose | Use Case | -| -------------------------- | -------------------------- | ----------------------------- | -| `debug_traceTransaction` | Trace specific transaction | Debugging failed transactions | -| `debug_traceBlockByNumber` | Trace entire block | Block-level analysis | -| `debug_traceCall` | Simulate and trace | Testing before execution | -| `debug_traceStateAccess` | State access patterns | Performance optimization | +| Method | Purpose | Use case | +| -------------------------- | ---------------------------- | ----------------------------- | +| `debug_traceTransaction` | Trace a specific transaction | Debugging failed transactions | +| `debug_traceBlockByNumber` | Trace an entire block | Block-level analysis | +| `debug_traceCall` | Simulate and trace | Testing before execution | +| `debug_traceStateAccess` | State access patterns | Performance optimization | | `debug_traceTransactionProfile` | Trace plus timing/store-access profiling | Latency breakdown and DB-access analysis | -## Transaction Analysis Example +## Transaction analysis example -Tracing an ERC-20 transfer transaction: +This example traces an ERC-20 transfer transaction: @@ -268,11 +268,11 @@ curl -X POST -H "Content-Type: application/json" \ -## Debugging Failed Transactions +## Debugging failed transactions -Steps to analyze and resolve transaction failures: +Use these steps to analyze and fix transaction failures: -### Step 1: Identify the Problem +### Step 1: Identify the problem ```bash # Get transaction receipt @@ -288,7 +288,7 @@ curl -X POST -H "Content-Type: application/json" \ https://evm-rpc.sei-apis.com ``` -### Step 2: Trace the Execution +### Step 2: Trace the execution ```bash # Trace to see where it failed @@ -310,7 +310,7 @@ curl -X POST -H "Content-Type: application/json" \ https://evm-rpc.sei-apis.com ``` -Response +**Response:** ```json { @@ -332,7 +332,7 @@ Response } ``` -### Step 3: Fix and Test +### Step 3: Fix and test ```bash # Simulate the fix with debug_traceCall @@ -363,31 +363,31 @@ curl -X POST \ https://evm-rpc.sei-apis.com ``` -## Common Debugging Scenarios +## Common debugging scenarios -### Transaction Reverted +### Transaction reverted -**Problem**: Transaction failed with revert -**Solution**: Use `callTracer` to find the exact revert reason +**Problem**: The transaction failed with a revert. +**Solution**: Use `callTracer` to find the exact revert reason. -### Out of Gas +### Out of gas -**Problem**: Transaction ran out of gas -**Solution**: Use gas analysis tracer to optimize gas usage +**Problem**: The transaction ran out of gas. +**Solution**: Use the gas analysis tracer to optimize gas usage. -### Unexpected Behavior +### Unexpected behavior -**Problem**: Transaction succeeded but wrong result -**Solution**: Use opcode tracer for step-by-step analysis +**Problem**: The transaction succeeded, but the result is wrong. +**Solution**: Use the opcode tracer for step-by-step analysis. -### Slow Performance +### Slow performance -**Problem**: Transaction uses too much gas -**Solution**: Use state access tracer to find inefficiencies +**Problem**: The transaction uses too much gas. +**Solution**: Use the state access tracer to find inefficiencies. -## Quick Reference +## Quick reference -### Essential Commands +### Essential commands ```bash # Trace transaction @@ -403,53 +403,53 @@ debug_traceCall(tx, "latest", {tracer: "callTracer"}) debug_traceStateAccess(hash) ``` -### Common Tracers +### Common tracers - **`callTracer`**: Contract call hierarchy - **`opcodeTracer`**: Opcode-level execution - **Custom JS**: Custom analysis logic -## Pre-Baked Trace Cache +## Pre-baked trace cache -RPC nodes can optionally pre-compute and cache `debug_trace*` results in the background so that trace requests are served from a local on-disk cache instead of re-executing the block live on every call. This is an opt-in feature configured through new `[evm]` fields in `app.toml` and is recommended for RPC nodes only. +RPC nodes can optionally pre-compute and cache `debug_trace*` results in the background. The node then serves trace requests from a local on-disk cache instead of re-executing the block live on every call. You configure this opt-in feature through `[evm]` fields in `app.toml`. It is recommended for RPC nodes only. -When enabled, a background worker re-executes each committed block with the configured tracers and stores the results in a Pebble database at `/data/trace_db`. The following methods serve from this cache on hit, and otherwise fall through to live re-execution: +When the feature is enabled, a background worker re-executes each committed block with the configured tracers. It stores the results in a Pebble database at `/data/trace_db`. These methods serve results from this cache on a cache hit. Otherwise, they fall through to live re-execution: - `debug_traceTransaction` - `debug_traceBlockByNumber` and `debug_traceBlockByHash` ### When the cache is used -A request is only served from cache when trace baking is enabled **and** the request uses a *bakeable* tracer configuration: +The node serves a request from the cache only when trace baking is enabled **and** the request uses a *bakeable* tracer configuration: - The tracer is one of `callTracer`, `prestateTracer`, or `flatCallTracer`. -- No custom `tracerConfig` is supplied. A per-call `tracerConfig` (for example `{"withLog": true}`) is not part of the cache key, so any custom tracer config makes the request un-bakeable and it falls through to live re-execution. +- The request does not include a custom `tracerConfig`. A per-call `tracerConfig` (for example, `{"withLog": true}`) is not part of the cache key. Any custom tracer config makes the request un-bakeable, so it falls through to live re-execution. -Requests that use the struct logger (no tracer), a JavaScript tracer, or any other named tracer are always executed live. +Requests that use the struct logger (no tracer), a JavaScript tracer, or any other named tracer always run live. ### Configuration -Trace baking is controlled by these `[evm]` fields in `app.toml`: +These `[evm]` fields in `app.toml` control trace baking: | Field | Default | Description | | ----- | ------- | ----------- | | `trace_bake_enabled` | `false` | Enables the background trace-baking worker that caches results at `/data/trace_db`. RPC nodes only. | | `trace_bake_workers` | `1` | Number of re-execution worker goroutines. | -| `trace_bake_queue_size` | `4096` | Bounds the in-flight height queue. Heights are dropped when the queue is full so consensus never blocks; dropped blocks fall through to live re-execution. | +| `trace_bake_queue_size` | `4096` | Bounds the in-flight height queue. When the queue is full, heights are dropped so that consensus never blocks. Dropped blocks fall through to live re-execution. | | `trace_bake_tracers` | `["callTracer"]` | Which tracers to bake per block. Eligible values: `callTracer`, `prestateTracer`, `flatCallTracer`. | -| `trace_bake_window_blocks` | `0` | Rolling prune window: blocks older than `(latest - window)` are pruned. `0` disables pruning, so the cache grows forever. | +| `trace_bake_window_blocks` | `0` | Rolling prune window: blocks older than `(latest - window)` are pruned. `0` disables pruning, so the cache grows without limit. | | `trace_bake_use_snapshot` | `false` | Uses in-memory memiavl snapshots as the state backend for trace baking when the store backend supports snapshots. | -| `trace_bake_snapshot_window` | `64` | Number of recent memiavl snapshots to retain for trace baking. | +| `trace_bake_snapshot_window` | `64` | Number of recent memiavl snapshots to keep for trace baking. | -Enabling trace baking adds a persistent on-disk store at `/data/trace_db` and increases disk usage. The store's write-ahead log is flushed when the node shuts down cleanly. +Trace baking adds a persistent on-disk store at `/data/trace_db` and increases disk usage. The node flushes the store's write-ahead log when it shuts down cleanly. ## Removed legacy trace filters -The legacy `*ExcludeTraceFail` endpoints have been removed. Use `debug_traceBlockByNumber` or `debug_traceBlockByHash` for block tracing and `eth_getTransactionReceipt` for EVM receipts. There is no block or filter method for discovering synthetic logs from Cosmos-originated transactions. If you already know a synthetic transaction hash, enable `sei_getTransactionReceipt` to retrieve its receipt and logs. +The legacy `*ExcludeTraceFail` endpoints have been removed. For block tracing, use `debug_traceBlockByNumber` or `debug_traceBlockByHash`. For EVM receipts, use `eth_getTransactionReceipt`. There is no block or filter method to discover synthetic logs from Cosmos-originated transactions. If you already know a synthetic transaction hash, enable `sei_getTransactionReceipt` to get its receipt and logs. -## Next Steps +## Next steps -1. **[JavaScript Tracers](/evm/tracing/javascript-tracers)** - Custom analysis scripts -2. **[Troubleshooting](/evm/tracing/troubleshooting)** - Common issues and solutions +1. **[JavaScript tracers](/evm/tracing/javascript-tracers)**: Custom analysis scripts +2. **[Troubleshooting](/evm/tracing/troubleshooting)**: Common issues and solutions -Start with `callTracer` for general debugging, then use specialized tracers for specific analysis needs. +Start with `callTracer` for general debugging. Then use specialized tracers for specific analysis needs. diff --git a/evm/tracing/javascript-tracers.mdx b/evm/tracing/javascript-tracers.mdx index ac27ae6..c09de20 100644 --- a/evm/tracing/javascript-tracers.mdx +++ b/evm/tracing/javascript-tracers.mdx @@ -3,11 +3,11 @@ title: 'JavaScript Tracers' description: 'Create custom debugging logic with JavaScript tracers for advanced EVM transaction analysis on Sei. Learn performance optimization, memory management, and advanced debugging patterns.' keywords: ['javascript tracers', 'custom tracers', 'evm debugging', 'tracer optimization', 'sei debugging'] --- -JavaScript tracers allow you to create custom debugging logic for analyzing EVM transactions on Sei. This powerful feature enables sophisticated analysis patterns beyond what built-in tracers provide. +JavaScript tracers let you create custom debugging logic to analyze EVM transactions on Sei. You can use them for more complex analysis than the built-in tracers support. -## Interface Overview +## Interface overview -Every JavaScript tracer follows this structure: +Every JavaScript tracer has this structure: ```javascript { @@ -35,33 +35,33 @@ Every JavaScript tracer follows this structure: } ``` -## Core Methods +## Core methods ### step(log, db) -Called for each EVM opcode execution. This is where your main analysis logic goes. +This method runs for each EVM opcode that executes. Put your main analysis logic here. **Parameters:** -- `log`: Current execution context with methods like `getPC()`, `op.toString()`, `getCost()` -- `db`: Database interface for querying state +- `log`: The current execution context, with methods such as `getPC()`, `op.toString()`, and `getCost()` +- `db`: The database interface to query state -**Gas Cost**: Varies by tracer complexity +**Gas cost**: Varies by tracer complexity ### result(ctx, db) -Called at the end of execution to return your analysis results. +This method runs at the end of execution and returns your analysis results. **Parameters:** -- `ctx`: Execution context with `gasUsed`, transaction info -- `db`: Database interface for final queries +- `ctx`: The execution context, with `gasUsed` and transaction information +- `db`: The database interface for final queries -## Advanced Tracer Examples +## Advanced tracer examples -### State Change Tracker +### State change tracker -Monitor all state modifications with detailed analysis: +Track every state change in detail: ```javascript { @@ -96,7 +96,7 @@ Monitor all state modifications with detailed analysis: } ``` -### DeFi Transaction Analysis +### DeFi transaction analysis Analyze complex DeFi transactions with multiple contract interactions: @@ -132,7 +132,7 @@ Analyze complex DeFi transactions with multiple contract interactions: } ``` -### Security Analysis Tracer +### Security analysis tracer Detect suspicious patterns and potential vulnerabilities: @@ -185,7 +185,7 @@ Detect suspicious patterns and potential vulnerabilities: } ``` -### Gas Optimization Tracer +### Gas optimization tracer Identify expensive operations for gas optimization: @@ -221,11 +221,11 @@ Identify expensive operations for gas optimization: } ``` -## Performance Optimization +## Performance optimization -**Performance**: JavaScript tracers can significantly slow down tracing. Optimize your tracer code and use timeouts for production use. +Optimize your tracer code, and use timeouts in production. JavaScript tracers can slow down tracing significantly. -### Memory-Efficient Patterns +### Memory-efficient patterns ```javascript // ✅ Efficient - Use summary data @@ -257,7 +257,7 @@ Identify expensive operations for gas optimization: } ``` -### Selective Operation Tracking +### Selective operation tracking ```javascript { @@ -289,9 +289,9 @@ Identify expensive operations for gas optimization: } ``` -## Configuration Options +## Configuration options -### Basic Configuration +### Basic configuration ```json { @@ -306,7 +306,7 @@ Identify expensive operations for gas optimization: } ``` -### Production Settings +### Production settings ```json { @@ -320,9 +320,9 @@ Identify expensive operations for gas optimization: } ``` -## Practical Integration Examples +## Practical integration examples -### Smart Contract Debugger +### Smart contract debugger ```solidity contract TransactionAnalyzer { @@ -351,7 +351,7 @@ contract TransactionAnalyzer { } ``` -### DeFi Analytics Dashboard +### DeFi analytics dashboard ```javascript // Off-chain analytics service @@ -384,18 +384,18 @@ class DeFiAnalytics { } ``` -## Best Practices +## Best practices -1. **Start Simple**: Begin with basic tracers before adding complexity -2. **Limit Data Collection**: Only collect necessary information -3. **Use Efficient Data Structures**: Prefer counters over arrays when possible -4. **Set Appropriate Timeouts**: Balance thoroughness with performance -5. **Test Incrementally**: Validate tracers on simple transactions first -6. **Handle Errors Gracefully**: Include error handling in your tracers +1. **Start simple**: Begin with basic tracers before you add complexity. +2. **Limit data collection**: Collect only the information that you need. +3. **Use efficient data structures**: Prefer counters to arrays when possible. +4. **Set appropriate timeouts**: Balance thoroughness with performance. +5. **Test incrementally**: Validate tracers on simple transactions first. +6. **Handle errors gracefully**: Include error handling in your tracers. -## Common Use Cases +## Common use cases -### Gas Profiling +### Gas profiling ```javascript const gasProfiler = `{ @@ -423,7 +423,7 @@ const gasProfiler = `{ }`; ``` -### Event Extraction +### Event extraction ```javascript const eventExtractor = `{ @@ -451,4 +451,4 @@ const eventExtractor = `{ }`; ``` -**Need Help?** If you encounter issues with JavaScript tracers, check out our [Troubleshooting Guide](/evm/tracing/troubleshooting) for common solutions and debugging tips. +If you have issues with JavaScript tracers, see the [Troubleshooting guide](/evm/tracing/troubleshooting) for common solutions and debugging tips. diff --git a/evm/tracing/troubleshooting.mdx b/evm/tracing/troubleshooting.mdx index d0184e8..a7f083e 100644 --- a/evm/tracing/troubleshooting.mdx +++ b/evm/tracing/troubleshooting.mdx @@ -3,15 +3,15 @@ title: 'Troubleshooting Guide' description: 'Comprehensive troubleshooting guide for EVM transaction tracing on Sei. Resolve common issues with timeouts, memory limits, JavaScript errors, and performance optimization.' keywords: ['tracing troubleshooting', 'debug errors', 'tracer timeout', 'memory limits', 'javascript tracer errors'] --- -This guide covers common issues encountered when using EVM transaction tracing on Sei and provides practical solutions to resolve them. +This guide covers common issues with EVM transaction tracing on Sei and gives practical solutions for them. -## Common Error Categories +## Common error categories -### 1. Timeout Errors +### 1. Timeout errors **Error**: `execution timeout` -**Cause**: Tracer execution exceeded the configured timeout duration. +**Cause**: The tracer execution exceeded the configured timeout. **Solutions**: @@ -23,18 +23,18 @@ This guide covers common issues encountered when using EVM transaction tracing o } ``` -**Best Practices**: +**Best practices**: - Start with shorter timeouts (30s) for testing -- Increase gradually based on transaction complexity -- Use built-in tracers when possible (they're faster) +- Increase the timeout gradually, based on transaction complexity +- Use built-in tracers when possible, because they are faster - Optimize JavaScript tracer code for performance -### 2. Memory Limit Errors +### 2. Memory limit errors **Error**: `out of memory` or `memory limit exceeded` -**Cause**: Tracer collected too much data or inefficient memory usage. +**Cause**: The tracer collected too much data or used memory inefficiently. **Solutions**: @@ -48,7 +48,7 @@ This guide covers common issues encountered when using EVM transaction tracing o } ``` -**Memory-Efficient Tracer Pattern**: +**Memory-efficient tracer pattern**: ```javascript { @@ -77,11 +77,11 @@ This guide covers common issues encountered when using EVM transaction tracing o } ``` -### 3. JavaScript Tracer Errors +### 3. JavaScript tracer errors -**Error**: `SyntaxError` or `ReferenceError` in JavaScript tracer +**Error**: `SyntaxError` or `ReferenceError` in a JavaScript tracer -**Common Issues**: +**Common issues**: ```javascript // ❌ Incorrect - Missing quotes @@ -109,7 +109,7 @@ This guide covers common issues encountered when using EVM transaction tracing o } ``` -**Debugging JavaScript Tracers**: +**Debugging JavaScript tracers**: ```javascript { @@ -140,7 +140,7 @@ This guide covers common issues encountered when using EVM transaction tracing o } ``` -### 4. Network and Connection Issues +### 4. Network and connection issues **Error**: `connection refused` or `network timeout` @@ -159,11 +159,11 @@ curl --connect-timeout 30 --max-time 120 \ http://localhost:8545 ``` -### 5. Transaction Not Found +### 5. Transaction not found **Error**: `transaction not found` -**Debugging Steps**: +**Debugging steps**: ```bash # 1. Verify transaction exists @@ -182,11 +182,11 @@ curl -X POST -H "Content-Type: application/json" \ http://localhost:8545 ``` -## Performance Optimization +## Performance optimization -### Tracer Performance Tips +### Tracer performance tips -1. **Limit Data Collection**: +1. **Limit data collection**: ```javascript { @@ -208,7 +208,7 @@ curl -X POST -H "Content-Type: application/json" \ } ``` -2. **Use Efficient Data Structures**: +2. **Use efficient data structures**: ```javascript // ❌ Inefficient - Object lookups @@ -239,7 +239,7 @@ curl -X POST -H "Content-Type: application/json" \ } ``` -3. **Selective Tracing**: +3. **Selective tracing**: ```javascript { @@ -257,7 +257,7 @@ curl -X POST -H "Content-Type: application/json" \ } ``` -### Node Configuration for Better Performance +### Node configuration for better performance ```toml # In your node configuration @@ -272,9 +272,9 @@ trace-memory-limit = "1GB" trace-cache-size = 1000 ``` -## Debugging Workflows +## Debugging workflows -### 1. Failed Transaction Analysis +### 1. Failed transaction analysis ```bash #!/bin/bash @@ -297,7 +297,7 @@ curl -s -X POST -H "Content-Type: application/json" \ http://localhost:8545 | jq '.result' ``` -### 2. Gas Optimization Workflow +### 2. Gas optimization workflow ```javascript // Step 1: Identify expensive operations @@ -348,53 +348,53 @@ const storageTracer = `{ }`; ``` -## Error Code Reference +## Error code reference -### Common HTTP Error Codes +### Common HTTP error codes -| Code | Error | Solution | -| ---- | --------------------- | -------------------------------------------- | -| 400 | Bad Request | Check JSON-RPC format and parameters | -| 404 | Not Found | Verify transaction hash and node sync status | -| 500 | Internal Server Error | Check node logs and resource limits | -| 503 | Service Unavailable | Node may be syncing or overloaded | +| Code | Error | Solution | +| ---- | --------------------- | ------------------------------------------------ | +| 400 | Bad Request | Check the JSON-RPC format and parameters | +| 404 | Not Found | Verify the transaction hash and node sync status | +| 500 | Internal Server Error | Check the node logs and resource limits | +| 503 | Service Unavailable | The node may be syncing or overloaded | -### Tracer-Specific Errors +### Tracer-specific errors -| Error | Cause | Solution | -| ------------------- | ----------------------------- | ------------------------------------------------ | -| `execution timeout` | Tracer took too long | Increase timeout or optimize tracer | -| `out of memory` | Too much data collected | Reduce data collection or disable memory tracing | -| `invalid tracer` | JavaScript syntax error | Validate tracer syntax | -| `tracer not found` | Built-in tracer doesn't exist | Check available tracers | +| Error | Cause | Solution | +| ------------------- | ---------------------------------- | ------------------------------------------------ | +| `execution timeout` | The tracer took too long | Increase the timeout or optimize the tracer | +| `out of memory` | Too much data collected | Reduce data collection or disable memory tracing | +| `invalid tracer` | JavaScript syntax error | Validate the tracer syntax | +| `tracer not found` | The built-in tracer does not exist | Check the available tracers | -## Best Practices Summary +## Best practices summary ### ✅ Do's -- **Start Simple**: Begin with built-in tracers before custom JavaScript -- **Set Timeouts**: Always configure appropriate timeouts -- **Limit Data**: Collect only necessary information -- **Test Incrementally**: Test tracers on simple transactions first -- **Monitor Resources**: Watch memory and CPU usage -- **Cache Results**: Store expensive trace results when possible +- **Start simple**: Begin with built-in tracers before you write custom JavaScript. +- **Set timeouts**: Always configure appropriate timeouts. +- **Limit data**: Collect only the information that you need. +- **Test incrementally**: Test tracers on simple transactions first. +- **Monitor resources**: Watch memory and CPU usage. +- **Cache results**: Store expensive trace results when possible. ### ❌ Don'ts -- **Don't Collect Everything**: Avoid tracing all operations unnecessarily -- **Don't Ignore Errors**: Always handle tracer errors gracefully -- **Don't Use Complex Logic**: Keep tracer step functions simple -- **Don't Forget Timeouts**: Never run tracers without timeout limits -- **Don't Trace in Production**: Avoid heavy tracing on production nodes +- **Do not collect everything**: Avoid tracing all operations unnecessarily. +- **Do not ignore errors**: Always handle tracer errors gracefully. +- **Do not use complex logic**: Keep tracer step functions simple. +- **Do not forget timeouts**: Never run tracers without timeout limits. +- **Do not trace in production**: Avoid heavy tracing on production nodes. -## Getting Help +## Getting help -If you encounter issues not covered in this guide: +If you have an issue that this guide does not cover: -1. **Check Node Logs**: Look for error messages in your Sei node logs -2. **Verify Configuration**: Ensure your node has tracing enabled -3. **Test Connectivity**: Confirm RPC endpoints are accessible -4. **Simplify Tracers**: Try built-in tracers first -5. **Community Support**: Ask in the [Sei Discord](https://discord.gg/sei) #dev-support channel +1. **Check node logs**: Look for error messages in your Sei node logs. +2. **Verify the configuration**: Make sure that tracing is enabled on your node. +3. **Test connectivity**: Confirm that the RPC endpoints are accessible. +4. **Simplify tracers**: Try built-in tracers first. +5. **Community support**: Ask in the #dev-support channel of the [Sei Discord](https://discord.gg/sei). -When reporting issues, include your tracer code, the transaction hash, and any error messages you receive. This helps the community provide better assistance. +When you report an issue, include your tracer code, the transaction hash, and any error messages that you receive. This helps the community help you. diff --git a/evm/transactions-with-seid.mdx b/evm/transactions-with-seid.mdx index fbeb74f..5f55812 100644 --- a/evm/transactions-with-seid.mdx +++ b/evm/transactions-with-seid.mdx @@ -5,41 +5,41 @@ keywords: ['seid transactions', 'evm transactions', 'contract deployment', 'toke --- ## Overview -EVM transactions on Sei allow you to interact with smart contracts, transfer tokens, deploy contracts, and manage various blockchain operations through the command line interface. This guide covers all available transaction types using the `seid` CLI, from basic token transfers to complex contract interactions and precompile calls. +EVM transactions on Sei let you interact with smart contracts, transfer tokens, deploy contracts, and manage other blockchain operations from the command line. This guide covers all available transaction types in the `seid` CLI, from basic token transfers to complex contract interactions and precompile calls. ## Prerequisites -Sending transactions via CLI requires you to have keys configured in your local keyring. You can then specify the key you want to use by appending `--from=[key name]` to your command. +To send transactions with the CLI, you must have keys configured in your local keyring. To select the key for a command, append `--from=[key name]` to it. -If you don't already have keys configured, you'll need to either generate a new key or import an existing one into your local keyring. Refer to this guide on [how to create a key](/evm/installing-seid-cli) for more details. +If you do not have keys configured yet, generate a new key or import an existing one into your local keyring. For details, see [how to create a key](/evm/installing-seid-cli). -## Network Configuration +## Network configuration -If the machine you run these commands from are not a node of the network, you'd need to append the following to your commands: +If you run these commands from a machine that is not a network node, append this flag to each command: ```bash --evm-rpc http:// ``` -Refer to the [RPC endpoints](/evm/networks) page for the list of available RPC endpoints. +For a list of available RPC endpoints, see [RPC endpoints](/evm/networks). -Most commands support `--evm-rpc` flag to specify custom RPC endpoints. The default is `http://localhost:8545`. +Most commands support the `--evm-rpc` flag, which sets a custom RPC endpoint. The default is `http://localhost:8545`. -## Common Transaction Flags +## Common transaction flags All transaction commands support these common flags: -- `--from=` - Specifies the key name to use for signing -- `--gas-fee-cap=` - Gas fee cap for the transaction (default varies by command) -- `--gas-limit=` - Gas limit for the transaction (default varies by command) -- `--evm-rpc=` - EVM RPC endpoint URL (default: `http://localhost:8545`) -- `--nonce=` - Nonce override for the transaction (-1 means auto-calculate) +- `--from=`: Specifies the key name to use for signing +- `--gas-fee-cap=`: Maximum fee per unit of gas for the transaction (default varies by command) +- `--gas-limit=`: Gas limit for the transaction (default varies by command) +- `--evm-rpc=`: EVM RPC endpoint URL (default: `http://localhost:8545`) +- `--nonce=`: Nonce override for the transaction (-1 means auto-calculate) ## Address management commands ### Associate an address -Associates the Sei address and EVM address on-chain for the sending key. This is required for cross-layer interactions. +This command associates the Sei address and the EVM address of the sending key on-chain. Cross-layer interactions require this association. ```bash seid tx evm native-associate [custom-message] --from= @@ -56,13 +56,13 @@ seid tx evm native-associate "associate" \ --node https://rpc.sei-apis.com ``` -The legacy `seid tx evm associate-address` command and its `sei_associate` JSON-RPC method have been removed. +The legacy `seid tx evm associate-address` command and its `sei_associate` JSON-RPC method were removed. -## Token Transfer Commands +## Token transfer commands -### Send Native Tokens +### Send native tokens -Sends native tokens (usei) to the target EVM address. +This command sends native tokens (usei) to the target EVM address. ```bash seid tx evm send [to EVM address] [amount in wei] --from= --gas-fee-cap= --gas-limit= --evm-rpc= @@ -70,10 +70,10 @@ seid tx evm send [to EVM address] [amount in wei] --from= --gas-fee-cap= **Parameters:** -- `[to EVM address]` - Destination EVM address (0x format) -- `[amount in wei]` - Amount to send in wei (smallest unit) +- `[to EVM address]`: Destination EVM address (0x format) +- `[amount in wei]`: Amount to send in wei (smallest unit) -**Default Flags:** +**Default flags:** - `--gas-fee-cap=1000000000000` (1000 Gwei) - `--gas-limit=21000` @@ -84,15 +84,15 @@ seid tx evm send [to EVM address] [amount in wei] --from= --gas-fee-cap= seid tx evm send 0x1234567890abcdef1234567890abcdef12345678 1000000000000000000 --from=mykey ``` -**Output :** +**Output:** ``` Transaction hash: 0x... ``` -### Send ERC20 Tokens +### Send ERC20 tokens -Sends ERC20 tokens from a specific contract to a recipient. +This command sends ERC20 tokens from a specific contract to a recipient. ```bash seid tx evm erc20-send [contract addr] [recipient] [amount] --from= --gas-fee-cap= --gas-limit= --evm-rpc= @@ -100,11 +100,11 @@ seid tx evm erc20-send [contract addr] [recipient] [amount] --from= --ga **Parameters:** -- `[contract addr]` - ERC20 contract address -- `[recipient]` - Recipient EVM address -- `[amount]` - Amount in smallest unit of the token +- `[contract addr]`: ERC20 contract address +- `[recipient]`: Recipient EVM address +- `[amount]`: Amount in the smallest unit of the token -**Default Flags:** +**Default flags:** - `--gas-fee-cap=1000000000000` (1000 Gwei) - `--gas-limit=7000000` @@ -115,17 +115,17 @@ seid tx evm erc20-send [contract addr] [recipient] [amount] --from= --ga seid tx evm erc20-send 0xTokenContract123... 0xRecipient456... 1000000 --from=mykey ``` -**Output :** +**Output:** ``` Transaction hash: 0x... ``` -## Contract Deployment Commands +## Contract deployment commands -### Deploy Contract +### Deploy contract -Deploys an EVM contract from a binary file. +This command deploys an EVM contract from a binary file. ```bash seid tx evm deploy [path to binary] --from= --gas-fee-cap= --gas-limit= --evm-rpc= @@ -133,9 +133,9 @@ seid tx evm deploy [path to binary] --from= --gas-fee-cap= --gas-li **Parameters:** -- `[path to binary]` - Path to the contract binary file +- `[path to binary]`: Path to the contract binary file -**Default Flags:** +**Default flags:** - `--gas-fee-cap=1000000000000` (1000 Gwei) - `--gas-limit=5000000` @@ -146,7 +146,7 @@ seid tx evm deploy [path to binary] --from= --gas-fee-cap= --gas-li seid tx evm deploy ./MyContract.bin --from=mykey --gas-limit=8000000 ``` -**Output :** +**Output:** ``` Deployer: 0x... @@ -154,11 +154,11 @@ Deployed to: 0x... Transaction hash: 0x... ``` -## Contract Interaction Commands +## Contract interaction commands -### Call Contract +### Call contract -Calls an EVM contract with a specific payload. You can generate payload by taking a look at docs [here](/evm/querying-the-evm#payload-generation). +This command calls an EVM contract with a specific payload. To generate the payload, see [Payload generation](/evm/querying-the-evm#payload-generation). ```bash seid tx evm call-contract [addr] [payload hex] --value= --from= --gas-fee-cap= --gas-limit= --evm-rpc= @@ -166,14 +166,14 @@ seid tx evm call-contract [addr] [payload hex] --value= --from= **Parameters:** -- `[addr]` - Contract address -- `[payload hex]` - Function call data in hex format +- `[addr]`: Contract address +- `[payload hex]`: Function call data in hex format -**Default Flags:** +**Default flags:** - `--gas-fee-cap=1000000000000` (1000 Gwei) - `--gas-limit=7000000` -- `--value=0` - SEI value to send with the call +- `--value=0`: SEI value to send with the call **Example:** @@ -181,15 +181,15 @@ seid tx evm call-contract [addr] [payload hex] --value= --from= seid tx evm call-contract 0xContract123... 0xa9059cbb000000... --value=1000000000000000000 --from=mykey ``` -**Output :** +**Output:** ``` Transaction hash: 0x... ``` -### Call Precompile +### Call precompile -Calls a method on a precompiled contract. Precompiles provide EVM access to Cosmos-SDK functionality. +This command calls a method on a precompiled contract. Precompiles give EVM access to Cosmos SDK functionality. ```bash seid tx evm call-precompile [precompile name] [method] [args...] --value= --from= --gas-fee-cap= --gas-limit= --evm-rpc= @@ -197,42 +197,42 @@ seid tx evm call-precompile [precompile name] [method] [args...] --value=For detailed information about each precompile's methods, parameters, and usage patterns, refer to the [EVM Precompiles documentation](/evm/precompiles/example-usage). +For each precompile's methods, parameters, and usage patterns, see the [EVM precompiles documentation](/evm/precompiles/example-usage). -**Output :** +**Output:** ``` Transaction hash: 0x... ``` -## Advanced Usage +## Advanced usage -### Custom Gas Settings +### Custom gas settings You can customize gas settings for any transaction: @@ -243,9 +243,9 @@ seid tx evm send 0x... 1000000000000000000 \ --from=mykey ``` -### Nonce Management +### Nonce management -Override automatic nonce calculation: +Override the automatic nonce calculation: ```bash seid tx evm send 0x... 1000000000000000000 \ @@ -253,35 +253,35 @@ seid tx evm send 0x... 1000000000000000000 \ --from=mykey ``` -## Error Handling +## Error handling -**Common Issues:** +**Common issues:** -- Insufficient balance for transaction + gas -- Incorrect address formats (use 0x prefix for EVM addresses) +- Insufficient balance for the transaction amount and gas +- Incorrect address formats (use the 0x prefix for EVM addresses) - Gas limit too low for complex operations -- Nonce conflicts in rapid successive transactions +- Nonce conflicts when you send transactions in rapid succession -## Best Practices +## Best practices -1. **Gas Estimation**: Start with default gas limits and adjust based on transaction complexity -2. **Address Validation**: Always verify addresses before sending transactions -3. **Key Management**: Use secure key storage and never expose private keys -4. **Network Verification**: Confirm you're connected to the correct network -5. **Transaction Monitoring**: Save transaction hashes for tracking purposes +1. Start with the default gas limits, and adjust them for transaction complexity. +2. Always verify addresses before you send transactions. +3. Use secure key storage, and never expose private keys. +4. Confirm that you are connected to the correct network. +5. Save transaction hashes so that you can track the transactions. -## Transaction Requirements +## Transaction requirements -- **Key Configuration**: Local keyring must contain the signing key -- **Sufficient Balance**: Account must have enough tokens for transaction amount + gas -- **Address Formats**: Use proper formats (0x... for EVM, seivaloper... for validators) -- **Network Access**: Ensure connectivity to the specified RPC endpoint -- **Gas Limits**: Set appropriate gas limits for transaction complexity +- The local keyring must contain the signing key. +- The account must have enough tokens for the transaction amount and gas. +- Use the correct address formats: 0x... for EVM addresses and seivaloper... for validators. +- Make sure that you can connect to the specified RPC endpoint. +- Set gas limits that suit the transaction complexity. -For more detailed information about specific commands, use the help flag: +For details about a specific command, use the help flag: ```bash seid tx evm [command] --help diff --git a/evm/transactions.mdx b/evm/transactions.mdx index 1d0a970..203c18c 100644 --- a/evm/transactions.mdx +++ b/evm/transactions.mdx @@ -5,73 +5,73 @@ description: 'Comprehensive guide on Transactions on Sei. Learn key concepts, co keywords: ['transactions', 'EVM transactions', 'gas', 'EIP-1559', 'nonce', 'transaction lifecycle', 'sei'] --- -Sei supports EVM transactions, allowing compatibility with Ethereum-based tools and contracts. Transactions are signed messages originating from an externally owned account (EOA) that trigger state changes on the blockchain. +Sei supports EVM transactions, so it works with Ethereum-based tools and contracts. Transactions are signed messages from an externally owned account (EOA) that trigger state changes on the blockchain. -## Transaction Lifecycle +## Transaction lifecycle | Stage | Description | | ----------------- | -------------------------------------------------------------------------------------------------------------------- | -| 1. Creation | A transaction is created by an EOA, specifying the recipient, value, gas parameters, and other fields. | -| 2. Signing | The transaction is signed with the sender's private key to create a valid signature. | -| 3. Submission | The signed transaction is submitted to the network through an RPC endpoint. | -| 4. Mempool | The transaction enters the mempool (transaction pool) where it awaits inclusion in a block. | -| 5. Execution | When selected by a validator, the transaction is executed in the EVM, causing state changes. | -| 6. Validation | The transaction and its state changes are validated by the consensus mechanism. | -| 7. Confirmation | Once validated, the transaction is included in a block and confirmed on-chain. | -| 8. Finality | On Sei, transactions achieve immediate finality once included in a block. | +| 1. Creation | An EOA creates a transaction and specifies the recipient, value, gas parameters, and other fields. | +| 2. Signing | The sender's private key signs the transaction and creates a valid signature. | +| 3. Submission | The sender submits the signed transaction to the network through an RPC endpoint. | +| 4. Mempool | The transaction enters the mempool (transaction pool), where it waits for inclusion in a block. | +| 5. Execution | When a validator selects the transaction, the EVM executes it and updates the state. | +| 6. Validation | The consensus mechanism validates the transaction and its state changes. | +| 7. Confirmation | After validation, the transaction is included in a block and confirmed on-chain. | +| 8. Finality | On Sei, transactions reach immediate finality when they are included in a block. | - Unlike other EVM chains where you need to wait for multiple confirmations, Sei's consensus mechanism provides immediate transaction finality. Once a transaction is included in a block, it cannot be reversed. + On other EVM chains, you need to wait for multiple confirmations. Sei's consensus mechanism gives immediate transaction finality. After a transaction is included in a block, it cannot be reversed. -## Gas Mechanics +## Gas mechanics -Gas is a unit of computational work in the EVM that helps prevent spam and allocate resources efficiently: +Gas is a unit of computational work in the EVM. It helps prevent spam and allocate resources efficiently: | Term | Description | | -------------------- | --------------------------------------------------------------------------------------------------------------------------- | -| Gas Limit | The maximum amount of gas the transaction may consume, set by the sender. | -| Base Fee | The minimum gas price required to be included in a block. On Sei, the base fee is not burned — all fees go to validators. | -| Priority Fee | An additional fee (tip) paid to validators for faster inclusion. | -| Gas Price | In legacy transactions, the price per unit of gas the sender is willing to pay. | -| Effective Gas Price | The actual price paid per unit of gas (base fee + priority fee in EIP-1559). | +| Gas limit | The maximum amount of gas the transaction may consume. The sender sets it. | +| Base fee | The minimum gas price required for inclusion in a block. On Sei, the base fee is not burned. All fees go to validators. | +| Priority fee | An extra fee (tip) paid to validators for faster inclusion. | +| Gas price | In legacy transactions, the price per unit of gas the sender is willing to pay. | +| Effective gas price | The actual price paid per unit of gas (base fee + priority fee in EIP-1559). | - **Gas Requirements for Common Operations:** + **Gas requirements for common operations:** - Simple SEI transfer: 21,000 gas - - ERC-20 transfer: ~45,000 gas - - Contract deployment: Varies based on contract size and complexity - - Always estimate gas before sending transactions using `eth_estimateGas` + - ERC-20 transfer: approximately 45,000 gas + - Contract deployment: Depends on contract size and complexity + - Always estimate gas with `eth_estimateGas` before you send transactions -## Transaction Structure +## Transaction structure -EVM transactions in Sei follow the Ethereum transaction format with standard properties: +EVM transactions on Sei follow the Ethereum transaction format and its standard properties: | Property | Description | | --- | --- | - | `from` | The address of the sender who will sign the transaction. This must be an externally-owned account (EOA) as contract accounts cannot send transactions. | - | `to` | The receiving address. If this is an EOA, the transaction transfers value. If a contract address, the transaction executes the contract code. If empty or null, the transaction creates a new contract. | - | `signature` | The cryptographic signature generated when the sender's private key signs the transaction. This confirms the sender has authorized the transaction and includes the v, r, and s components. | - | `nonce` | A sequentially incrementing counter that indicates the transaction number from the account. This prevents replay attacks and ensures transaction ordering. | + | `from` | The address of the sender that signs the transaction. This must be an externally owned account (EOA), because contract accounts cannot send transactions. | + | `to` | The receiving address. If it is an EOA, the transaction transfers value. If it is a contract address, the transaction executes the contract code. If it is empty or null, the transaction creates a new contract. | + | `signature` | The cryptographic signature generated when the sender's private key signs the transaction. It confirms that the sender authorized the transaction, and it includes the v, r, and s components. | + | `nonce` | A sequentially incrementing counter that indicates the transaction number from the account. It prevents replay attacks and keeps transactions in order. | | `data` | The input data (also called 'input' or 'calldata') for contract execution. For simple transfers, this is usually empty. For contract interactions, this contains the function selector and encoded arguments. | - | `value` | Amount of SEI to transfer from sender to recipient (denominated in WEI, where 1 SEI equals 1e+18 WEI). | - | `gasLimit` | The maximum amount of gas units that can be consumed by the transaction. Often referred to as 'gas' in transaction objects. | - | `maxPriorityFeePerGas` | The maximum price of the consumed gas to be included as a tip to the validator (denominated in WEI). Used in EIP-1559 transactions. | - | `maxFeePerGas` | The maximum fee per unit of gas willing to be paid for the transaction (inclusive of baseFeePerGas and maxPriorityFeePerGas). Used in EIP-1559 transactions. | - | `gasPrice` | The price per unit of gas the sender is willing to pay (denominated in WEI). Used in legacy transactions. | - | `chainId` | The chain identifier number. Prevents transaction reuse across different chains. | - | `accessList` | A list of addresses and storage keys that the transaction plans to access. Used in EIP-2930 and EIP-1559 transactions to reduce gas costs for accessing specified addresses and storage slots. | + | `value` | The amount of SEI to transfer from the sender to the recipient, in wei (1 SEI equals 1e+18 wei). | + | `gasLimit` | The maximum number of gas units that the transaction can consume. Transaction objects often call it 'gas'. | + | `maxPriorityFeePerGas` | The maximum tip per unit of consumed gas that goes to the validator, in wei. Used in EIP-1559 transactions. | + | `maxFeePerGas` | The maximum fee per unit of gas that the sender is willing to pay for the transaction, including baseFeePerGas and maxPriorityFeePerGas. Used in EIP-1559 transactions. | + | `gasPrice` | The price per unit of gas that the sender is willing to pay, in wei. Used in legacy transactions. | + | `chainId` | The chain identifier number. It prevents transaction reuse across different chains. | + | `accessList` | A list of addresses and storage keys that the transaction plans to access. EIP-2930 and EIP-1559 transactions use it to reduce the gas cost of access to those addresses and storage slots. | | `type` | The transaction type: 0 for legacy (pre-EIP-2718), 1 for EIP-2930 access list transactions, and 2 for EIP-1559 fee market transactions. | - | `hash` | The transaction hash, a unique identifier for the transaction generated after signing. | + | `hash` | The transaction hash: a unique identifier for the transaction, generated after signing. | - ### Legacy Transactions (Type 0) + ### Legacy transactions (type 0) - Pre-EIP-1559 transaction format that specifies a single gasPrice. + This format predates EIP-1559 and specifies a single gasPrice. ```json { @@ -85,9 +85,9 @@ EVM transactions in Sei follow the Ethereum transaction format with standard pro } ``` - ### Access List Transactions (Type 1, EIP-2930) + ### Access list transactions (type 1, EIP-2930) - Transactions with an optional access list of addresses and storage keys to reduce gas costs. + These transactions can include an access list of addresses and storage keys to reduce gas costs. ```json { @@ -110,9 +110,9 @@ EVM transactions in Sei follow the Ethereum transaction format with standard pro } ``` - ### Fee Market Transactions (Type 2, EIP-1559) + ### Fee market transactions (type 2, EIP-1559) - Transaction format that supports dynamic base fees with a priority fee tip to validators. + This format supports dynamic base fees and a priority fee (tip) to validators. ```json { @@ -131,7 +131,7 @@ EVM transactions in Sei follow the Ethereum transaction format with standard pro - ### Example Request: Sending an EIP-1559 Transaction + ### Example request: sending an EIP-1559 transaction ```json { @@ -156,7 +156,7 @@ EVM transactions in Sei follow the Ethereum transaction format with standard pro ### JavaScript example with web3.js - Public RPC endpoints such as `https://evm-rpc.sei-apis.com` do not manage or unlock accounts, so `eth_getAccounts` and `eth_sendTransaction` are not available. Sign transactions locally with a private key and broadcast the raw transaction instead. + Public RPC endpoints such as `https://evm-rpc.sei-apis.com` do not manage or unlock accounts. On these endpoints, `eth_accounts` returns an empty list and `eth_sendTransaction` returns an error. Sign transactions locally with a private key and broadcast the raw transaction instead. ```javascript @@ -229,7 +229,7 @@ EVM transactions in Sei follow the Ethereum transaction format with standard pro "value": "0x1234", "type": "0x2", "accessList": [], - "chainId": "0x1", + "chainId": "0x531", "maxFeePerGas": "0x1234", "maxPriorityFeePerGas": "0x1234", "v": "0x0", @@ -266,52 +266,50 @@ EVM transactions in Sei follow the Ethereum transaction format with standard pro -## Transaction Guidelines +## Transaction guidelines - **Transaction Best Practices:** - - - **Set appropriate gas parameters:** Use network conditions to estimate optimal values for `maxFeePerGas` and `maxPriorityFeePerGas`. - - **Manage nonces carefully:** Track and increment nonces correctly to avoid transaction failures. - - **Use typed transactions:** Prefer EIP-1559 transactions (type 2) for more predictable fees. - - **Implement proper error handling:** Account for potential transaction failures and revert reasons. - - **Verify recipient addresses:** Always double-check destination addresses, as transactions cannot be reversed. + - Use network conditions to estimate appropriate values for `maxFeePerGas` and `maxPriorityFeePerGas`. + - Track and increment nonces correctly to avoid transaction failures. + - Prefer EIP-1559 transactions (type 2) for more predictable fees. + - Handle possible transaction failures and revert reasons in your code. + - Always double-check destination addresses, because transactions cannot be reversed. -| Common Issue | Cause | Solution | +| Common issue | Cause | Solution | | --- | --- | --- | | Transaction Underpriced | Gas price or priority fee too low | Increase `maxFeePerGas` and `maxPriorityFeePerGas` | -| Nonce Too Low | Using a nonce that's already been used | Query current nonce with `getTransactionCount` | -| Out of Gas | Gas limit too low for the operation | Use `eth_estimateGas` to set appropriate limit | -| Contract Execution Failed | Contract function reverted | Test with `eth_call` before sending transaction | +| Nonce Too Low | The nonce was already used | Query the current nonce with `getTransactionCount` | +| Out of Gas | Gas limit too low for the operation | Use `eth_estimateGas` to set an appropriate limit | +| Contract Execution Failed | Contract function reverted | Test with `eth_call` before you send the transaction | -## Transaction Validation +## Transaction validation -Before an EVM transaction is accepted, Sei performs strict semantic validation of its fields, enforced since v6.5.0. If you construct and sign transactions manually, make sure they are well-formed to avoid rejection. +Before Sei accepts an EVM transaction, it performs strict semantic validation of the transaction fields. Sei enforces this validation from v6.5.0 onward. If you construct and sign transactions manually, make sure they are well formed to avoid rejection. -- The canonical field-level reference (signature-value byte caps and zero-padding rules, access-list entries, EIP-7702 authorization lists) lives in [Transaction Types](/evm/evm-parity/transaction-types#access-list-and-auth-list-entry-validation). -- Envelope-level restrictions (no Cosmos wrapper fields, canonical protobuf encoding, whole-block rejection on decode failure) are covered in [Differences with Ethereum](/evm/differences-with-ethereum#evm-transaction-envelope-restrictions). +- [Transaction types](/evm/evm-parity/transaction-types#access-list-and-auth-list-entry-validation) is the canonical field-level reference. It covers signature-value byte caps and zero-padding rules, access-list entries, and EIP-7702 authorization lists. +- [Differences with Ethereum](/evm/differences-with-ethereum#evm-transaction-envelope-restrictions) covers envelope-level restrictions: no Cosmos wrapper fields, canonical protobuf encoding, and whole-block rejection on decode failure. ### Receipts for nonce-bumping failed transactions -Some EVM transactions pass basic validation and bump the sender's nonce, yet still fail during state transition — for example, a transaction whose gas limit clears the intrinsic-gas check but falls short of the EIP-7623 floor-data-gas requirement (which can occur in normal operation after Pectra). Because these transactions bump the nonce, they are considered to have happened and therefore produce a receipt. +Some EVM transactions pass basic validation and bump the sender's nonce, but still fail during state transition. One example is a transaction whose gas limit clears the intrinsic-gas check but falls short of the EIP-7623 floor-data-gas requirement. This can occur in normal operation after Pectra. Because these transactions bump the nonce, they are considered to have happened and therefore produce a receipt. -For such failures, Sei writes a synthetic `status=0` (failed) receipt at the end of the block. The receipt reports a `gasUsed` of 0 and an `effectiveGasPrice` of 0, and carries a `VmError` describing the state-transition reason. `eth_getTransactionReceipt` returns this failed-tx receipt instead of `null`. The `VmError` is stored on Sei's internal receipt record and is not included in the `eth_getTransactionReceipt` JSON response; retrieve it with the non-standard `eth_getVMError` method. +For such failures, Sei writes a synthetic `status=0` (failed) receipt at the end of the block. The receipt reports a `gasUsed` of 0 and an `effectiveGasPrice` of 0. It also carries a `VmError` that describes the state-transition reason. `eth_getTransactionReceipt` returns this failed-transaction receipt instead of `null`. Sei stores the `VmError` on its internal receipt record, not in the `eth_getTransactionReceipt` JSON response. To get it, use the non-standard `eth_getVMError` method. - Previously, a nonce-bumping transaction that failed during state transition could return `null` from `eth_getTransactionReceipt` indefinitely, causing clients that poll for a receipt to hang. Clients should now expect a `status=0` receipt for these transactions and treat it as a normal failed-transaction result. + Previously, a nonce-bumping transaction that failed during state transition could return `null` from `eth_getTransactionReceipt` indefinitely. Clients that polled for a receipt could then hang. Clients should now expect a `status=0` receipt for these transactions and treat it as a normal failed-transaction result. -## Additional Resources +## Additional resources - - Complete documentation of Sei's EVM RPC endpoints for transaction creation and monitoring + + Sei's EVM RPC endpoints for creating and monitoring transactions - + Learn more about gas calculation, fee estimation, and cost optimization on Sei - Understanding Externally Owned Accounts and Contract Accounts on Sei + Externally owned accounts and contract accounts on Sei diff --git a/evm/usdc-on-sei.mdx b/evm/usdc-on-sei.mdx index 2781cc7..af10770 100644 --- a/evm/usdc-on-sei.mdx +++ b/evm/usdc-on-sei.mdx @@ -3,7 +3,7 @@ title: 'USDC on Sei' description: 'Guide to integrating USDC stablecoin on Sei using Viem and Node.js for transfers and balance checks.' keywords: ['USDC', 'Sei', 'Circle', 'stablecoin', 'ERC-20', 'Viem', 'payments', 'token transfer', 'web3', 'cryptocurrency'] --- -## Addresses and Decimals +## Addresses and decimals - Sei Testnet USDC: [`0x4fCF1784B31630811181f670Aea7A7bEF803eaED`](https://testnet.seiscan.io/address/0x4fCF1784B31630811181f670Aea7A7bEF803eaED) - Sei Mainnet USDC: [`0xe15fC38F6D8c56aF07bbCBe3BAf5708A2Bf42392`](https://seiscan.io/address/0xe15fC38F6D8c56aF07bbCBe3BAf5708A2Bf42392) @@ -11,33 +11,33 @@ keywords: ['USDC', 'Sei', 'Circle', 'stablecoin', 'ERC-20', 'Viem', 'payments', ## Overview -USDC is a digital dollar issued by [Circle](http://developers.circle.com), also known as a stablecoin, running on many of the world's leading blockchains. Designed to represent US dollars on the internet, USDC is backed 100% by highly liquid cash and cash-equivalent assets so that it's always redeemable 1:1 for USD. It is commonly used for payments, trading, and on/off-ramps in web3 apps. +USDC is a digital dollar, also known as a stablecoin, issued by [Circle](http://developers.circle.com). It runs on many of the world's leading blockchains. USDC is designed to represent US dollars on the internet. It is backed 100% by highly liquid cash and cash-equivalent assets, so it is always redeemable 1:1 for USD. It is commonly used for payments, trading, and on-ramps and off-ramps in dApps. -On the **Sei**, USDC can be transferred like any standard ERC-20 token — enabling fast, secure, and programmable digital dollar transactions. +On Sei, you can transfer USDC like any standard ERC-20 token. -This guide walks you through building a standalone index.js script using **Viem** and **Node.js** to check your USDC balance and send a test transfer to another address. The sample is a minimal, generic ERC‑20 flow using USDC as the example token. +This guide shows how to build a standalone `index.js` script with viem and Node.js. The script checks your USDC balance and sends a test transfer to another address. The sample is a minimal, generic ERC-20 flow that uses USDC as the example token. ### Prerequisites -- Node.js v18+ with "type": "module" in package.json +- Node.js v18 or later, with `"type": "module"` in `package.json` - viem and dotenv installed -- Sei wallet with USDC and SEI for gas on your selected network (default: testnet). -- To get testnet USDC on Sei, use the [Circle Faucet](https://faucet.circle.com) or use [Circle’s CCTP v2](https://github.com/circlefin/circle-cctp-crosschain-transfer) Sample application to transfer USDC cross-chain to your Sei wallet. -- Private key and recipient address stored in a .env file +- A Sei wallet that holds USDC and SEI (for gas) on your selected network. The default network is Sei Testnet. +- To get USDC on Sei Testnet, use the [Circle Faucet](https://faucet.circle.com). You can also use the [Circle CCTP v2](https://github.com/circlefin/circle-cctp-crosschain-transfer) sample application to transfer USDC cross-chain to your Sei wallet. +- A private key and a recipient address, stored in a `.env` file - Optional: set `SEI_NETWORK=testnet|mainnet` (defaults to `testnet`) -## Project Setup +## Project setup Follow these steps to set up your project and environment: -- Initialize a Node.js project and install dependencies: create a project folder and run: +- To initialize a Node.js project and install the dependencies, create a project folder. Then run these commands in it: ```shell npm init -y npm install viem dotenv ``` -- **Prepare environment variables**: In the project root, create a file named .env and add your private key and recipient address: +- **Prepare environment variables**: In the project root, create a file named `.env`. Add your private key and the recipient address to it: ``` PRIVATE_KEY= # 0x-prefixed 64-hex-character key @@ -46,15 +46,15 @@ RECIPIENT_ADDRESS=0x SEI_NETWORK=testnet ``` -- **Create the script file**: Create an index.js file in the project directory. We will build this script step by step in the next section. Ensure that your Node environment can handle ES module imports (the code uses import syntax). +- **Create the script file**: Create an `index.js` file in the project directory. You build this script step by step in the next section. Make sure that your Node.js environment can handle ES module imports, because the code uses `import` syntax. -## Script Breakdown +## Script breakdown -Open index.js in your editor and add the following sections. Each part of the script is explained below: +Open `index.js` in your editor. Then add these script sections. An explanation follows each one: -1\. Import Modules and Define Chain/Token Constants: First, import required functions from Viem and set up constants for Sei networks (testnet and mainnet) and the USDC token contract. +1\. Import modules and define chain and token constants: First, import the required functions from viem. Then set up constants for the Sei networks (Sei Testnet and Sei Mainnet) and the USDC token contract. -This includes chain ID, RPC URL, token address, decimals, and a minimal ABI for the USDC contract’s balanceOf and transfer functions (just the function signatures we need): +The constants include the chain ID, RPC URL, token address, decimals, and a minimal ABI for the `balanceOf` and `transfer` functions of the USDC contract. The ABI has only the function signatures that the script needs: ```ts import 'dotenv/config'; @@ -114,9 +114,9 @@ const USDC_ABI = [ ]; ``` -2\. **Load Environment Variables and Validate Input:** +2\. **Load environment variables and validate input:** -Next, load the private key and recipient from the environment and validate them. The script checks that the variables exist and that the recipient address looks valid, then normalizes the private key string: +Next, load and validate the private key and the recipient address from the environment. The script checks that the variables exist and that the recipient address looks valid. Then it normalizes the private key string: ```ts // --- Environment Variables --- @@ -140,13 +140,13 @@ if (!/^0x[a-fA-F0-9]{40}$/.test(RECIPIENT)) { const PRIVATE_KEY = PRIVATE_KEY_RAW.startsWith('0x') ? PRIVATE_KEY_RAW : '0x' + PRIVATE_KEY_RAW; ``` -This ensures we have the necessary inputs. If the private key or recipient address is missing or malformed, the script logs an error and exits. The private key is prefixed with "0x" if not already present (Viem expects a 0x-prefixed key). +This code makes sure that the script has the necessary inputs. If the private key or the recipient address is missing or malformed, the script logs an error and exits. If the private key does not start with "0x", the script adds the prefix, because viem expects a 0x-prefixed key. -After this, PRIVATE_KEY is a clean hex string and RECIPIENT is a validated address. +After this step, `PRIVATE_KEY` is a clean hex string, and `RECIPIENT` is a validated address. -3\. Initialize Viem Clients: +3\. Initialize viem clients: -Using the chain config and credentials, we create a public client for reading blockchain data and a wallet client for writing (signing transactions). We also derive an account object from the private key: +Use the chain config and the credentials to create two clients. The public client reads blockchain data. The wallet client writes to the chain by signing transactions. Also derive an account object from the private key: ```ts // --- Client Setup --- @@ -155,17 +155,17 @@ const publicClient = createPublicClient({ chain, transport: http() }); const walletClient = createWalletClient({ account, chain, transport: http() }); ``` -- privateKeyToAccount converts the hex private key into an account object (with the corresponding address, etc.). -- createPublicClient connects to the selected Sei network RPC for read-only calls (no private key needed). -- createWalletClient uses our account and the RPC to allow sending transactions. +- `privateKeyToAccount` converts the hex private key into an account object. The object includes the corresponding address and other account properties. +- `createPublicClient` connects to the RPC endpoint of the selected Sei network for read-only calls. It does not need a private key. +- `createWalletClient` uses your account and the RPC endpoint to send transactions. -At this point, we’re set up to interact with the selected Sei network: publicClient will call eth_call for contract reads, and walletClient will handle signing and sending transactions from our account. +The script can now interact with the selected Sei network. `publicClient` calls `eth_call` for contract reads, and `walletClient` signs and sends transactions from your account. -4\. Main Transfer Logic: +4\. Main transfer logic: -Finally, we write an asynchronous function to perform the USDC transfer. It will check the sender’s USDC balance, ensure it’s sufficient, then invoke the USDC contract’s transfer function. +Finally, write an asynchronous function that performs the USDC transfer. The function checks the sender's USDC balance and makes sure that it is sufficient. Then it calls the `transfer` function of the USDC contract. -We also log key info and handle errors: +The function also logs the transfer details and handles errors: ```ts // --- Main Transfer Logic --- @@ -209,18 +209,18 @@ We also log key info and handle errors: })(); ``` -- The script uses publicClient.readContract to call the USDC contract’s balanceOf(address) and get the sender’s token balance. +- The script uses `publicClient.readContract` to call `balanceOf(address)` on the USDC contract and get the sender's token balance. -- We format the balance from smallest units (6 decimals for USDC) into a human-readable number with formatUnits. The amount is set to 10 USDC in this example – you can adjust this value. We compare the desired amount to the current balance; if insufficient, it logs an error and exits. +- `formatUnits` converts the balance from the smallest units (6 decimals for USDC) into a human-readable number. This example sets the amount to 10 USDC. You can change this value. The script compares the amount to the current balance. If the balance is not sufficient, the script logs an error and exits. -- If the balance is adequate, we use parseUnits to convert 10 USDC into the raw token amount (10 \* 10^6, since USDC has 6 decimals). - Then walletClient.writeContract calls the USDC contract’s transfer(to, amount) function. This sends a transaction from our account to transfer the tokens. On success, it returns a transaction hash, which we log alongside a URL to view the transaction on the Sei block explorer. +- If the balance is sufficient, the script uses `parseUnits` to convert 10 USDC into the raw token amount (10 \* 10^6, because USDC has 6 decimals). + Then `walletClient.writeContract` calls the `transfer(to, amount)` function of the USDC contract. This sends a transaction from your account to transfer the tokens. On success, it returns a transaction hash. The script logs the hash and a URL where you can view the transaction on the Sei block explorer. -- Errors in the try/catch (for example, RPC issues or a transaction failure) will log “Transfer failed” with the error message. The script ends with process.exit(0) to terminate after completing the async function. +- If an error occurs, such as an RPC issue or a transaction failure, the `try`/`catch` block logs "Transfer failed" with the error message. The script ends with `process.exit(0)`, which stops the process after the async function completes. -## Run the Script +## Run the script -With index.js completed, you can run the script from your terminal: +When `index.js` is complete, you can run the script from your terminal: ```shell # Default: testnet @@ -230,7 +230,7 @@ node index.js SEI_NETWORK=mainnet node index.js ``` -The expected output will look like the following if the transfer succeeds (your addresses and values will differ): +If the transfer succeeds, the output looks like this, with your own addresses and values: ``` Sender: 0x1A2b...7890 # your sender address @@ -241,14 +241,14 @@ Tx hash: 0xabc123...def456 # transaction hash of the transfer Explorer: https://testnet.seiscan.io/tx/0xabc123...def456 ``` -You should see “Transfer successful\!” and a transaction hash. You can copy the explorer URL into a browser to view the transaction details on Seiscan. +You should see "Transfer successful\!" and a transaction hash. To view the transaction details on Seiscan, you can copy the explorer URL into a browser. -Continue building by checking for more information in the [Circle Developer Docs.](https://developers.circle.com/) +For more information, see the [Circle Developer Docs](https://developers.circle.com/). -### Important Notes +### Important notes -- Testnet Only: Sei Testnet USDC has no real value. Don’t use mainnet keys or expect real funds. -- Security: Store private keys in `.env`; never commit secrets. Use best practices for key management. -- Gas Fees: You’ll need a small amount of testnet SEI to cover gas. -- Lightweight ABI: Only `balanceOf` and `transfer` are used — enough for simple transfers. -- Viem Behavior: `readContract` and `writeContract` handle reads/writes. The private key is auto-prefixed with `0x`. +- Testnet only: Sei Testnet USDC has no real value. Do not use Sei Mainnet keys, and do not expect real funds. +- Security: Store private keys in `.env`. Never commit secrets. Follow best practices for key management. +- Gas: You need a small amount of SEI on Sei Testnet to pay for gas. +- Lightweight ABI: The script uses only `balanceOf` and `transfer`. These functions are enough for simple transfers. +- viem behavior: `readContract` handles reads, and `writeContract` handles writes. The script adds the `0x` prefix to the private key automatically. diff --git a/evm/videos.mdx b/evm/videos.mdx index 7ee7f11..83e98f6 100644 --- a/evm/videos.mdx +++ b/evm/videos.mdx @@ -3,13 +3,13 @@ title: 'Video Tutorials' description: 'Watch video tutorials covering Sei EVM development, smart contract tooling, precompiles, and more.' keywords: ['sei video tutorials', 'sei evm videos', 'hardhat tutorial', 'foundry tutorial', 'precompiles tutorial'] --- -A collection of video walkthroughs to help you get started building on Sei. +These video walkthroughs help you start building on Sei. -## EVM Development +## EVM development -### Sei EVM Overview +### Sei EVM overview -An introduction to developing on Sei's parallelized EVM, covering smart contract languages, tooling, and key concepts. +This video introduces development on Sei's parallelized EVM. It covers smart contract languages, tooling, and key concepts.