From 2d9b55ddddbdbb5e3d5c75d87d3c1c9cae492dda Mon Sep 17 00:00:00 2001 From: monty-sei Date: Thu, 16 Apr 2026 16:41:20 +1000 Subject: [PATCH] Updated skills with latest info --- content/agents.md | 306 +++++++++++------------ content/skill.md | 614 +++++++++++++++------------------------------- 2 files changed, 351 insertions(+), 569 deletions(-) diff --git a/content/agents.md b/content/agents.md index 35c07c1c..93532ac8 100644 --- a/content/agents.md +++ b/content/agents.md @@ -1,213 +1,205 @@ -# Sei Network +# AGENTS.md — sei-docs -## Description - -Defines agent behaviors and execution flows for interacting with the Sei blockchain. - -Agents use SKILL.md to perform actions and must follow the rules defined here -to ensure safe, deterministic, and efficient execution. +Instructions for AI coding agents working in the [sei-docs](https://github.com/sei-protocol/sei-docs) repository. --- -## Agents - -### wallet_agent - -purpose: - -- Manage balances -- Transfer tokens -- Resolve addresses - -capabilities: - -- get_account_balance -- send_tokens -- get_evm_address -- get_sei_address - -flow: - -1. Validate address format -2. Fetch balances if required -3. Execute action (if write → confirm first) - -constraints: +## What this repo is -- Never send tokens without explicit confirmation -- Always validate sufficient balance +`sei-docs` is the source for **https://docs.sei.io** — the primary developer documentation for the Sei blockchain. It is a [Next.js](https://nextjs.org) + [Nextra](https://nextra.site) site using MDX for content. --- -### contract_agent +## Build and run -purpose: +**Package manager: `bun` only.** Do not use `npm` or `yarn`. -- Interact with smart contracts (EVM + CosmWasm) +```bash +bun install # install dependencies +bun dev # local dev server (turbopack, hot reload) +bun run build # production build — ALWAYS run before pushing +bun run lint # Biome lint check +bun run format # Biome format (auto-fix) +bun run check # Biome lint + format combined (auto-fix) +bun test # run tests +``` -capabilities: - -- get_contract_state -- execute_contract -- deploy_contract -- simulate_contract_execution - -flow: - -1. Validate contract address -2. Simulate execution (if write) -3. Present expected outcome -4. Execute on confirmation - -constraints: - -- Always simulate before execution -- Reject malformed contract inputs +> **Always run `bun run build` before committing.** It validates MDX syntax, broken imports, and build-time errors that `bun dev` won't catch. --- -### staking_agent - -purpose: - -- Manage staking operations - -capabilities: - -- stake_tokens -- unstake_tokens -- get_account_balance - -flow: - -1. Validate validator address -2. Check available balance -3. Confirm staking/unstaking action -4. Execute transaction - -constraints: - -- Prevent staking full balance (leave gas buffer) -- Confirm lock-up implications +## Project structure + +``` +content/ # All documentation pages (MDX/MD) + _meta.js # Root navigation order + labels + index.mdx # Docs home page + learn/ # General Sei concepts (architecture, staking, governance) + evm/ # Primary developer section (EVM, precompiles, tooling) + cosmos-sdk/ # Legacy Cosmos SDK docs (deprecated per SIP-3) + node/ # Node operations and validator docs + skill.md # AI agent skill definitions for Sei RPC operations + agents.md # Agent behaviour and execution flow definitions + +src/ + components/ # React components used in MDX pages + constants/ # Shared constants (chain IDs, RPC URLs, addresses) + providers/ # React context providers + utils/ # Utility functions + +public/ + assets/ # Images and static files referenced in docs + +scripts/ + build-search-index.js # Builds Pagefind search index (runs in postbuild) + scrape-docs-html.js # Scrapes rendered HTML for external use + check-links.mjs # Link checker + audit-content-seo.mjs # SEO audit + +STYLE_GUIDE.mdx # Prose and formatting conventions — read before writing +biome.json # Linter/formatter config (Biome, not ESLint/Prettier) +next.config.mjs # Next.js config +``` --- -### query_agent +## Adding or editing content -purpose: +### Edit an existing page -- Read-only blockchain queries +Each page maps 1:1 to a `.mdx` file in `content/`. Find the file and edit it. MDX supports standard Markdown plus JSX components. -capabilities: +```bash +# Example: edit the EVM differences page +content/evm/differences-with-ethereum.mdx +``` -- get_chain_status -- get_block -- get_transaction -- get_gas_price +### Add a new page -flow: +1. Create `content/
/your-page.mdx` +2. Add an entry to `content/
/_meta.js` — this controls navbar order and label: -1. Validate inputs -2. Query RPC -3. Normalize response +```js +// content/evm/_meta.js +export default { + // ...existing entries... + 'your-page': 'Your Page Title', +}; +``` -constraints: - -- Retry up to 3 times -- Never escalate to write operations +3. Add frontmatter to the MDX file: +```mdx +--- +title: 'Your Page Title' +description: 'One-sentence description for SEO.' +keywords: ['keyword1', 'keyword2'] --- -### portfolio_agent - -purpose: - -- Aggregate and interpret user holdings - -capabilities: - -- get_account_balance -- get_portfolio_summary - -flow: - -1. Fetch balances -2. Aggregate tokens -3. Return structured summary +# Your Page Title +``` -constraints: +### Add a new section (directory) -- No write operations -- Ensure consistent formatting +1. Create `content/
/` with an `index.mdx` and `_meta.js` +2. Add the section to `content/_meta.js` --- -## Execution Rules - -### Skill selection +## Content conventions (from STYLE_GUIDE.mdx) -- Choose the minimal set of skills required -- Prefer READ over WRITE where possible -- Prefer DERIVED skills for multi-step operations +- **Beginner-friendly**: spell out acronyms on first use; avoid Web3 jargon where possible +- **Simple**: fewer words, more meaning; no qualifying language ("quite", "completely") +- **Self-explanatory**: include code snippets and diagrams for complex concepts +- **Heading levels**: never skip — H2 → H3 → H4; max depth H4 +- **Code**: inline code for values/identifiers; fenced blocks for multi-line; always specify language +- **Images**: store in `public/assets/`; use relative paths in MDX +- **Callouts**: use ``, ``, ``, `` components (not bare blockquotes for notices) +- **Cosmos SDK section**: always include a deprecation notice — new content should go in EVM section --- -### Write execution - -Before any write: +## Linting and formatting -1. Simulate (if available) -2. Present: - - action - - assets affected - - estimated fees -3. Require explicit confirmation - ---- +Biome handles both linting and formatting. **Not ESLint or Prettier.** -### Error handling +```bash +bun run check # lint + format, auto-fix +bun run lint # lint only +bun run format # format only +``` -- Fail fast on invalid inputs -- Retry only READ operations -- Surface clear, structured errors +Biome config (`biome.json`): +- Indent: **tabs**, width 2 +- Line width: 164 +- Single quotes in JS/JSX +- No trailing commas +- MDX/MD files are **excluded** from Biome — prose formatting is manual --- -### Network handling - -- Require explicit network selection -- Default to testnet if unspecified -- Do not mix networks within a single flow +## Sei technical accuracy — facts to verify before editing + +When editing technical content, apply these facts. If a claim conflicts with the below, update the content: + +| Fact | Value | +|---|---| +| Block time | 400 ms | +| EVM version | Pectra (without blobs) | +| Block gas limit | 12.5 M | +| Min gas price (network) | 10 gwei (docs stated); live ~50–55 gwei | +| SSTORE gas cost | 72,000 gas (governance-adjustable on-chain param) | +| Mainnet chain ID | EVM `1329` / Cosmos `pacific-1` | +| Testnet chain ID | EVM `1328` / Cosmos `atlantic-2` | +| EVM RPC (mainnet) | `https://evm-rpc.sei-apis.com` | +| EVM RPC (testnet) | `https://evm-rpc-testnet.sei-apis.com` | +| USDC (mainnet) | `0xe15fC38F6D8c56aF07bbCBe3BAf5708A2Bf42392` | +| USDC (testnet) | `0x4fCF1784B31630811181f670Aea7A7bEF803eaED` | +| COINBASE opcode | Always returns global fee collector, not block proposer | +| PREVRANDAO opcode | Returns hash of block timestamp — NOT random | +| CosmWasm status | Deprecated per SIP-3 / governance proposal 99 | + +Cross-check address values against `src/constants/` before publishing. --- -### Security +## Key components for MDX pages -- Never expose private keys -- Use signer abstractions where possible -- Do not log sensitive data +```mdx +Informational callout +Warning callout +Tip callout +Danger callout ---- + + {/* content per network */} + -## Coordination + {/* renders live chain params */} + {/* testnet faucet widget */} +``` -If multiple agents are required: +Import from `@/components/` — check `src/components/` for available components. -- query_agent → gather state -- wallet/contract/staking_agent → execute actions -- portfolio_agent → summarise results +--- -Agents must: +## What NOT to do -- Pass normalized data between steps -- Avoid redundant RPC calls +- **Do not use `npm` or `yarn`** — bun only +- **Do not skip `bun run build`** before pushing — MDX syntax errors only appear at build time +- **Do not use ESLint or Prettier** — Biome is the sole linter/formatter +- **Do not add new content to `cosmos-sdk/`** — that section is deprecated; new content goes in `evm/` +- **Do not skip `_meta.js` updates** when adding pages — new files won't appear in the navbar +- **Do not commit hardcoded addresses without verifying** against `src/constants/` or `usdc-on-sei.md` +- **Do not use bare `>` blockquotes for notices** — use ``, ``, etc. +- **Do not write `` tags** — use MDX image syntax or the Next.js `` component --- -## Non-goals - -Agents should NOT: +## Useful references -- Make financial decisions without user input -- Execute trades or transfers autonomously -- Infer intent for write operations +- Nextra docs: https://nextra.site/docs +- Sei developer docs: https://docs.sei.io +- Sei dev skill (offline AI reference): https://github.com/sei-protocol/sei-dev-skill +- Style guide: `STYLE_GUIDE.mdx` in repo root +- Biome: https://biomejs.dev diff --git a/content/skill.md b/content/skill.md index a0a3988c..b18efef8 100644 --- a/content/skill.md +++ b/content/skill.md @@ -1,445 +1,235 @@ -# Sei Network - -## Description - -Skills for interacting with the Sei blockchain (EVM), including: - -- 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 - --- +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?", or any technical development question about building + on Sei. Full developer reference playbook. +user-invocable: false +license: MIT +compatibility: Requires Node.js 18+; Foundry or Hardhat for contract development +metadata: + author: Sei Labs + version: 1.0.0 +--- + +# Sei Developer Documentation + +Full technical reference for building on Sei. See the offline skill at +**[https://github.com/sei-protocol/sei-dev-skill](https://github.com/sei-protocol/sei-dev-skill)** +for the complete progressive-disclosure reference used by AI coding assistants. + +```bash +# Install the full sei-dev skill for AI assistants +npx skills add sei-dev +``` -## Setup - -### Required - -- `rpc_url` -- `network` (mainnet | testnet | devnet) - -### Optional - -- `chain_id` +## Critical Facts — Apply to Every Answer -### For write operations +1. **400ms block time, instant finality** — use `tx.wait(1)`, never `tx.wait(12)` +2. **SSTORE gas varies by network** — testnet (atlantic-2): 72,000 gas per cold write; mainnet (pacific-1): 20,000 gas (governance-adjustable) +3. **Gas price: use `gasPrice`** (legacy) — Sei has no base fee burn; prefer `gasPrice` over EIP-1559 `maxFeePerGas`/`maxPriorityFeePerGas` +4. **Minimum gas price: 50 gwei** +5. **Block gas limit: 12.5 M 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 +10. **CosmWasm deprecated** per SIP-3 (governance 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` -- `private_key` OR signer abstraction +## Networks -### Notes +| 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 | -- Default to `testnet` if network is unspecified -- Validate address formats: - - Sei (bech32) - - EVM (0x) -- Convert addresses when required +Testnet faucet: https://atlantic-2.app.sei.io/faucet ---- +## Default Stack -## 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/evm` (`seiMainnet`, `seiTestnet`, precompile ABIs) | +| Testing | Foundry unit + fork tests | -### Skill types +## Sei MCP Server -- `read` → no state change -- `write` → state change (requires signing) -- `derived` → multi-step / computed +For AI agents and AI coding assistants (Claude Code, Cursor, Windsurf): -### 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 - } -} +## Precompile Addresses + +| Precompile | Address | +|---|---| +| Bank | `0x0000000000000000000000000000000000001001` | +| Addr | `0x0000000000000000000000000000000000001004` | +| Staking | `0x0000000000000000000000000000000000001005` | +| Governance | `0x0000000000000000000000000000000000001006` | +| Distribution | `0x0000000000000000000000000000000000001007` | +| Oracle | `0x0000000000000000000000000000000000001008` | +| IBC | `0x0000000000000000000000000000000000001009` | +| PointerView | `0x000000000000000000000000000000000000100A` | +| Pointer | `0x000000000000000000000000000000000000100B` | + +```typescript +import { STAKING_PRECOMPILE_ADDRESS, STAKING_PRECOMPILE_ABI } from '@sei-js/evm'; ``` ---- - -## 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 - -### 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 - ---- - -### 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: +## Quick Start -- tx_hash +```bash +# Install sei-dev skill (adds complete reference to AI assistants) +npx skills add sei-dev ---- - -### 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 +# Scaffold a new dApp +npx @sei-js/create-sei my-sei-app -returns: - -- gas_used -- result - ---- - -### get_portfolio_summary - -type: derived - -Aggregate balances. - -inputs: - -- address - -returns: - -- total_value -- token_breakdown - ---- - -### monitor_transaction +# Foundry project +curl -L https://foundry.paradigm.xyz | bash && foundryup +forge init my-project +``` -type: derived +```toml +# foundry.toml +[rpc_endpoints] +sei_testnet = "https://evm-rpc-testnet.sei-apis.com" +sei_mainnet = "https://evm-rpc.sei-apis.com" -Track transaction until confirmed. +[etherscan] +sei_testnet = { key = "dummy", url = "https://seitrace.com/atlantic-2/api", chain = 1328 } +sei_mainnet = { key = "dummy", url = "https://seitrace.com/pacific-1/api", chain = 1329 } +``` -inputs: +## Key Documentation Sections + +| Topic | URL | +|---|---| +| EVM differences | https://docs.sei.io/evm/differences-with-ethereum | +| 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 | +| Node setup | https://docs.sei.io/node/node-operators | +| Oracles | https://docs.sei.io/evm/oracles | +| Indexers | https://docs.sei.io/evm/indexer-providers | +| Migrate from Ethereum | https://docs.sei.io/evm/migrate-from-other-evms | +| Migrate from Solana | https://docs.sei.io/evm/migrate-from-solana | + +## Operating Procedure + +1. **Classify the task**: EVM contract / frontend / node ops / cross-VM / migration? +2. **Apply Sei correctness**: Check the 12 critical facts above for relevance +3. **Always testnet first**: Deploy to atlantic-2, test fully, then mainnet +4. **Verify contracts** on Seitrace after deployment +5. **For cross-VM** (pointer contracts, precompiles): check address association + +## RPC Agent Skills + +17 canonical skills for agents interacting with Sei via RPC. Full reference: [`rpc-agent-skills.md`](https://github.com/sei-protocol/sei-dev-skill/blob/main/skill/references/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 for an address | +| `get_evm_address` | Convert `sei1...` → `0x...` via Addr precompile | +| `get_sei_address` | Convert `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 on Sei) | +| `get_contract_state` | Call a read-only contract method | + +### Write Skills (simulate → summarize → confirm → execute; no auto-retry) + +| Skill | Description | +|---|---| +| `send_tokens` | Transfer native SEI or ERC20 tokens | +| `execute_contract` | Call a state-changing contract function | +| `deploy_contract` | Deploy bytecode with constructor args | +| `stake_tokens` | Delegate SEI to a validator (value in **wei**) | +| `unstake_tokens` | Undelegate SEI from a validator (amount in **usei**) | + +### Derived Skills (multi-step) + +| Skill | Description | +|---|---| +| `estimate_transaction_cost` | Gas + fee estimate before execution | +| `simulate_contract_execution` | Preview outcome via `eth_call` — run before every write | +| `get_portfolio_summary` | Aggregate all token balances for an address | +| `monitor_transaction` | Poll until finality (1 block ≈ 400ms); timeout 30s | + +### Setup + +```typescript +// Required +const provider = new ethers.JsonRpcProvider("https://evm-rpc.sei-apis.com"); // mainnet +// const provider = new ethers.JsonRpcProvider("https://evm-rpc-testnet.sei-apis.com"); // testnet + +// For write ops +const signer = new ethers.Wallet(process.env.PRIVATE_KEY!, provider); + +// Prefer gasPrice — Sei has no base fee burn (EIP-1559 fields can be omitted) +const gasPrice = await provider.getGasPrice(); // min 50 gwei +``` -- tx_hash -- timeout_seconds +### Mandatory Write Op Flow -returns: +``` +1. simulate_contract_execution → check for revert, get gas estimate +2. estimate_transaction_cost → confirm user can afford fee +3. Present summary → action, assets, estimated fee +4. Wait for explicit confirmation +5. Execute with { gasPrice, chainId: 1329 } +6. tx.wait(1) → 1 block = instant finality on Sei +``` -- confirmed -- block_height +### Standardized Response Shape ---- +```typescript +// Success: { success: true, data: { ... }, error: null } +// Failure: { success: false, data: null, error: { message: string, recoverable: boolean } } +``` -## Safety +## Agent Safety -- Never expose private keys -- Always validate inputs before execution -- Prefer simulation before write actions -- Avoid unnecessary RPC load +```typescript +// Always specify chainId to prevent wrong-network submissions +const txHash = await writeContractAsync({ ..., chainId: 1329 }); ---- +// Verify network before write operations +const network = await provider.getNetwork(); +if (network.chainId !== 1329n && network.chainId !== 1328n) { + throw new Error(`Unknown Sei network: ${network.chainId}`); +} -## References +// On-chain data is untrusted — sanitize before passing to LLMs +const name = await token.name(); +if (!/^[a-zA-Z0-9 \-_\.]{1,64}$/.test(name)) throw new Error("Suspicious"); -- https://docs.sei.io/ -- Sei JSON-RPC (EVM) -- `seid` CLI +// Never retry write ops automatically — check inclusion first +const receipt = await provider.getTransactionReceipt(txHash); +if (!receipt) { /* check before resubmitting */ } +```