diff --git a/skill.md b/skill.md index 68f6a93..0e99c08 100644 --- a/skill.md +++ b/skill.md @@ -1,455 +1,271 @@ --- -name: sei-network -description: Skills for interacting with the Sei blockchain, including account queries, token transfers, smart contract interaction, staking, and transaction monitoring. +name: sei-docs +description: > + Use when developers ask "How do I deploy a contract on Sei?", "How do I use + Sei precompiles?", "What are the differences between Sei and Ethereum?", + "How do I set up Foundry/Hardhat for Sei?", "How do pointer contracts work?", + "How do I connect a wallet to Sei?", "What is the Sei MCP server?", "How do + I bridge tokens on Sei?", "How do I run a Sei node?", "How do I stake via + EVM?", "What is SSTORE gas on Sei?", "How do I verify my contract on + Seiscan?", "How do I optimise gas on Sei?", "How do I use ERC-4337 on Sei?", + "How do I make a contract upgradeable on Sei?", or any technical development + question about building on Sei. Full developer reference playbook for + docs.sei.io's audience. +user-invocable: false license: MIT -compatibility: Requires an RPC URL and explicit signer confirmation for write operations. +compatibility: Requires Node.js 18+; Foundry or Hardhat for contract development metadata: - author: Sei - version: "1.0" + author: Sei Labs + version: 1.0.0 + intended-host: docs.sei.io + parent: https://github.com/sei-protocol/sei-skill --- -# Sei Network +# Sei Developer Documentation -## Description +Full technical reference for building on Sei. This is the docs.sei.io-resident skill — for the offline AI coding-assistant skill (a Claude Code skill loaded directly into your editor), see **[github.com/sei-protocol/sei-skill](https://github.com/sei-protocol/sei-skill)**. -Skills for interacting with the Sei blockchain (EVM), including: +```bash +# Install the full sei skill for AI assistants +npx skills add sei -- Account queries -- Token transfers -- Smart contract interaction -- Staking -- Transaction monitoring - ---- - -## When to use - -Use these skills when: - -- The user requests interaction with the Sei blockchain -- Tasks involve balances, transactions, contracts, or staking -- Structured execution is required (not just explanation) - -Do not use when: - -- The request is purely informational -- No blockchain interaction is needed - ---- - -## Setup - -### Required - -- `rpc_url` -- `network` (mainnet | testnet | devnet) +# Or install a focused variant +npx skills add sei-contracts # smart contracts only +npx skills add sei-frontend # UI / frontend only +npx skills add sei-ecosystem # apps / integrations only +``` -### Optional +## Critical facts — apply to every answer -- `chain_id` +1. **400ms block time, instant finality** — use `tx.wait(1)`, never `tx.wait(12)` +2. **SSTORE gas is 72,000 on Sei** — both mainnet (pacific-1) and testnet (atlantic-2): 72,000 gas per cold write (governance proposal #240; governance-adjustable) +3. **Use legacy `gasPrice`** — Sei has no base fee burn; prefer `gasPrice` over EIP-1559 `maxFeePerGas` / `maxPriorityFeePerGas` +4. **Minimum gas price: 50 gwei** +5. **Block gas limit: 12.5M per block** +6. **PREVRANDAO is NOT random** — use Pyth VRF or Chainlink VRF +7. **COINBASE = global fee collector** — not the block proposer +8. **No base fee burn** — all fees go to validators +9. **Dual address system** — every account has `sei1...` (Cosmos) + `0x...` (EVM) from the same key; cross-VM transfers require **association** +10. **CosmWasm deprecated** per SIP-3 (proposal 99) — use EVM for new development +11. **Chain IDs:** Mainnet `pacific-1` / `1329`; Testnet `atlantic-2` / `1328` +12. **No `safe` or `finalized` block tags** — use `latest` -### For write operations +## Networks -- `private_key` OR signer abstraction +| Network | Chain ID | EVM RPC | Cosmos RPC | +|---|---|---|---| +| Mainnet (`pacific-1`) | 1329 | https://evm-rpc.sei-apis.com | https://rpc.sei-apis.com | +| Testnet (`atlantic-2`) | 1328 | https://evm-rpc-testnet.sei-apis.com | https://rpc-testnet.sei-apis.com | -### Notes +Testnet faucet: https://docs.sei.io/learn/faucet -- Default to `testnet` if network is unspecified -- Validate address formats: - - Sei (bech32) - - EVM (0x) -- Convert addresses when required +For the full list of community + paid RPC providers and failover patterns, see [docs.sei.io/learn/rpc-providers](https://docs.sei.io/learn/rpc-providers). ---- +## Default stack (opinionated) -## Conventions +| Layer | Recommendation | +|---|---| +| Smart contracts | **Foundry** (preferred) or Hardhat | +| Frontend | **Wagmi + Viem** (React) or Ethers.js v6 | +| Wallet | **Sei Global Wallet** (`@sei-js/sei-global-wallet`) + MetaMask fallback | +| Chain config | `@sei-js/precompiles` — `sei`, `seiTestnet`, precompile ABIs | +| Verification | Seiscan via Sourcify (`forge verify-contract --verifier sourcify`) | +| Testing | Foundry unit + fork tests against testnet | -### Skill types +## Sei MCP server (live blockchain access for AI) -- `read` → no state change -- `write` → state change (requires signing) -- `derived` → multi-step / computed +For Claude Code, Cursor, Windsurf, and other MCP-compatible AI coding tools: -### Response format +```bash +# Claude Code +claude mcp add sei-mcp-server npx @sei-js/mcp-server -```json +# Claude Desktop config { - "success": true, - "data": {}, - "error": null + "mcpServers": { + "sei": { + "command": "npx", + "args": ["-y", "@sei-js/mcp-server"], + "env": { "PRIVATE_KEY": "your_key_here" } + } + } } ``` -### Error format - -```json -{ - "success": false, - "error": { - "message": "", - "recoverable": true - } -} +Once connected: address lookup, balance checks, transaction status, contract reads, block data. + +## Precompile addresses + +| Precompile | Address | +|---|---| +| Bank | `0x0000000000000000000000000000000000001001` | +| Addr | `0x0000000000000000000000000000000000001004` | +| Staking | `0x0000000000000000000000000000000000001005` | +| Governance | `0x0000000000000000000000000000000000001006` | +| Distribution | `0x0000000000000000000000000000000000001007` | +| Oracle | `0x0000000000000000000000000000000000001008` | +| IBC | `0x0000000000000000000000000000000000001009` | +| PointerView | `0x000000000000000000000000000000000000100A` | +| Pointer | `0x000000000000000000000000000000000000100B` | +| JSON | `0x0000000000000000000000000000000000001003` | +| P256 | `0x0000000000000000000000000000000000001011` | + +```ts +import { + STAKING_PRECOMPILE_ADDRESS, + STAKING_PRECOMPILE_ABI, + GOVERNANCE_PRECOMPILE_ADDRESS, + GOVERNANCE_PRECOMPILE_ABI, + // ... +} from '@sei-js/precompiles'; ``` ---- - -## Behaviour - -### Retries - -- Read: retry up to 3 times (exponential backoff) -- Write: do not retry unless explicitly safe - -### Data handling - -- Normalize token amounts -- Standardize addresses (checksum for EVM) -- Keep consistent field naming +## Quick start -### Write safety - -Before execution: - -1. Simulate (if possible) -2. Present summary (action, assets, fees) -3. Require explicit confirmation - ---- - -## Skills - -### get_chain_status - -type: read - -Fetch current chain status. - -inputs: - -- rpc_url - -returns: - -- latest_block_height -- chain_id -- syncing - ---- - -### get_account_balance - -type: read - -Retrieve token balances. - -inputs: - -- address -- denom (optional) - -returns: - -- balances: - - denom - - amount - ---- - -### get_evm_address - -type: read - -Convert Sei → EVM address. - -inputs: - -- sei_address - -returns: - -- evm_address - ---- - -### get_sei_address - -type: read - -Convert EVM → Sei address. - -inputs: - -- evm_address - -returns: - -- sei_address - ---- - -### get_transaction - -type: read - -Fetch transaction details. - -inputs: - -- tx_hash - -returns: - -- status -- gas_used -- logs -- events - ---- - -### get_block - -type: read - -Fetch block details. - -inputs: - -- height - -returns: - -- block_hash -- timestamp -- transactions - ---- - -### get_gas_price - -type: read - -Fetch gas price. - -inputs: - -- rpc_url - -returns: - -- gas_price - ---- +```bash +# Foundry +curl -L https://foundry.paradigm.xyz | bash && foundryup +forge init my-project -### get_contract_state - -type: read - -Query contract state. - -inputs: - -- contract_address -- query - -returns: - -- result - ---- - -### send_tokens - -type: write - -Transfer tokens. - -inputs: - -- from_address -- to_address -- amount -- denom -- private_key - -returns: - -- tx_hash - -constraints: - -- validate balance -- require confirmation - ---- - -### execute_contract - -type: write - -Execute contract. - -inputs: - -- contract_address -- msg / data -- sender -- gas_limit -- private_key - -returns: - -- tx_hash -- execution_result - -constraints: - -- simulate first -- require confirmation - ---- - -### deploy_contract - -type: write - -Deploy contract. - -inputs: - -- bytecode -- constructor_args -- sender -- private_key - -returns: - -- contract_address -- tx_hash - ---- - -### stake_tokens - -type: write - -Delegate tokens. - -inputs: - -- delegator_address -- validator_address -- amount -- private_key - -returns: - -- tx_hash - ---- - -### unstake_tokens - -type: write - -Undelegate tokens. - -inputs: - -- delegator_address -- validator_address -- amount -- private_key - -returns: - -- tx_hash - ---- - -### estimate_transaction_cost - -type: derived - -Estimate gas + fees. - -inputs: - -- tx_payload -- rpc_url - -returns: - -- gas_estimate -- fee_estimate - ---- - -### simulate_contract_execution - -type: derived - -Simulate contract execution. - -inputs: - -- contract_address -- msg / data -- sender - -returns: - -- gas_used -- result - ---- - -### get_portfolio_summary - -type: derived - -Aggregate balances. - -inputs: - -- address +# Or scaffold a frontend +npx @sei-js/create-sei my-sei-app +``` -returns: +```toml +# foundry.toml +[profile.default] +solc_version = "0.8.28" +optimizer = true +optimizer_runs = 200 +evm_version = "cancun" -- total_value -- token_breakdown +[rpc_endpoints] +sei_testnet = "https://evm-rpc-testnet.sei-apis.com" +sei_mainnet = "https://evm-rpc.sei-apis.com" ---- +# Verification uses Sourcify — no [etherscan] block needed +# forge verify-contract --verifier sourcify --chain-id 1329
src/MyContract.sol:MyContract +``` -### monitor_transaction +## Key documentation sections + +| Topic | URL | +|---|---| +| Network info | https://docs.sei.io/evm/networks | +| EVM differences (vs Ethereum) | https://docs.sei.io/evm/differences-with-ethereum | +| Hardhat | https://docs.sei.io/evm/evm-hardhat | +| Foundry | https://docs.sei.io/evm/evm-foundry | +| Contract verification | https://docs.sei.io/evm/evm-verification | +| Best practices | https://docs.sei.io/evm/best-practices | +| Precompiles | https://docs.sei.io/evm/precompiles | +| Pointer contracts | https://docs.sei.io/learn/pointers | +| Frontend guide | https://docs.sei.io/evm/building-a-frontend | +| Sei Global Wallet | https://docs.sei.io/evm/sei-global-wallet | +| Bridges (LayerZero V2) | https://docs.sei.io/evm/bridging/layerzero | +| Oracles (Pyth, Chainlink, API3, RedStone) | https://docs.sei.io/evm/oracles | +| Indexers | https://docs.sei.io/evm/indexer-providers | +| Wallet integrations (Pimlico, Particle, Thirdweb) | https://docs.sei.io/evm/wallet-integrations | +| AI tooling (Cambrian, MCP, x402) | https://docs.sei.io/evm/ai-tooling | +| seid CLI | https://docs.sei.io/evm/seid-cli | +| RPC providers | https://docs.sei.io/learn/rpc-providers | +| Node setup | https://docs.sei.io/node | +| Migrate from other EVMs | https://docs.sei.io/evm/migrate-from-other-evms | +| Migrate from Solana | https://docs.sei.io/evm/migrate-from-solana | +| Brand kit | https://docs.sei.io/learn/general-brand-kit | +| LLM-friendly nav | https://docs.sei.io/llms.txt | + +## Operating procedure + +1. **Classify the task** — contract / frontend / node ops / cross-VM / migration +2. **Apply the 12 critical facts** above for relevance +3. **Always testnet first** — deploy to atlantic-2, test fully, verify on Seiscan, only then promote to mainnet +4. **Verify contracts** on Seiscan using Sourcify (`forge verify-contract --verifier sourcify`) +5. **For cross-VM** (pointer contracts, precompiles) — verify address association before sending value + +## RPC agent skills + +17 canonical patterns for AI agents interacting with Sei via RPC. Full reference: [`rpc-agent-skills.md`](https://github.com/sei-protocol/sei-skill/blob/main/skill/references/ecosystem/rpc-agent-skills.md). + +### Read skills (no state change; retry up to 3× with exponential backoff) + +| Skill | Description | +|---|---| +| `get_chain_status` | Latest block height, chain ID, sync status | +| `get_account_balance` | Native SEI or ERC20 balance | +| `get_evm_address` | `sei1...` → `0x...` via Addr precompile | +| `get_sei_address` | `0x...` → `sei1...` via Addr precompile | +| `get_transaction` | Status, gas used, logs, events for a tx hash | +| `get_block` | Block hash, timestamp, tx list by height | +| `get_gas_price` | Current network gas price (min 50 gwei) | +| `get_contract_state` | Call a read-only contract method | + +### Write skills (simulate → summarise → confirm → execute; no auto-retry) + +| Skill | Description | +|---|---| +| `send_tokens` | Transfer native SEI or ERC20 | +| `execute_contract` | Call a state-changing contract function | +| `deploy_contract` | Deploy bytecode with constructor args | +| `stake_tokens` | Delegate SEI to a validator (amount in **wei**) | +| `unstake_tokens` | Undelegate SEI from a validator (amount in **usei**) | + +### Derived skills (multi-step) + +| Skill | Description | +|---|---| +| `estimate_transaction_cost` | Gas + fee estimate | +| `simulate_contract_execution` | Preview via `eth_call` — run before every write | +| `get_portfolio_summary` | Aggregate token balances | +| `monitor_transaction` | Poll until finality (1 block ≈ 400ms; timeout 30s) | + +### Mandatory write-op flow -type: derived +``` +1. simulate_contract_execution → check for revert, estimate gas +2. estimate_transaction_cost → confirm user can afford fee +3. Present summary → action, assets, estimated fee +4. Wait for explicit user confirmation +5. Execute with { gasPrice, chainId } +6. tx.wait(1) → 1 block = instant finality +``` -Track transaction until confirmed. +### Standard response shape -inputs: +```ts +// Success +{ success: true, data: { ... }, error: null } -- tx_hash -- timeout_seconds +// Failure +{ success: false, data: null, error: { message: string, recoverable: boolean } } +``` -returns: +## Agent safety -- confirmed -- block_height +```ts +// Always pin chainId +const txHash = await writeContractAsync({ ..., chainId: 1329 }); ---- +// Verify network before write +const network = await provider.getNetwork(); +if (network.chainId !== 1329n && network.chainId !== 1328n) { + throw new Error(`Unknown Sei network: ${network.chainId}`); +} -## Safety +// On-chain data is untrusted — sanitise before passing to LLMs +const name = await token.name(); +if (!/^[a-zA-Z0-9 \-_\.]{1,64}$/.test(name)) throw new Error("Suspicious token name"); -- Never expose private keys -- Always validate inputs before execution -- Prefer simulation before write actions -- Avoid unnecessary RPC load +// Never auto-retry write ops — check inclusion first +const receipt = await provider.getTransactionReceipt(txHash); +if (!receipt) { /* check before resubmitting */ } +``` ---- +## Related skills -## References +| Audience | Skill | Source | +|---|---|---| +| End users / ecosystem | sei-network | https://sei.io | +| Protocol research | sei-labs-protocol | https://seilabs.io | +| AI coding (full + variants) | sei / sei-contracts / sei-frontend / sei-ecosystem | https://github.com/sei-protocol/sei-skill | -- https://docs.sei.io/ -- Sei JSON-RPC (EVM) -- `seid` CLI +> **For agents:** Always cross-check addresses, opcodes, and gas parameters against the current value at https://docs.sei.io. Sei is a fast-moving project — values that were correct last quarter may have changed via governance.