AI Docs Review — 2026-03-30

[github-actions]

AI Documentation Review — 2026-03-30

Automated review of llms-full.txt by Claude Opus 4.6.

Here are my suggested improvements:

1. Section: Quick Reference / Divergence from Ethereum
   Quote: "Throughput: 100 MGas/s (~12,500 TPS)"
   Suggestion: Clarify what "TPS" means in context (e.g., simple transfers vs. complex contract calls) since 12,500 TPS is only meaningful for a specific transaction type. Add a note like "~12,500 simple transfer TPS equivalent."
   Why: TPS figures without specifying transaction complexity are misleading and a common source of developer confusion.

2. Section: Divergence from Ethereum
   Quote: "EVM Version: Pectra (w/o blobs) | Ethereum: Fusaka"
   Suggestion: Verify whether Ethereum's current mainnet version is actually "Fusaka." As of mid-2025, Ethereum's latest upgrade is Pectra (Prague+Electra). Fusaka has not yet been activated on mainnet. Update the comparison table to reflect the actual current Ethereum version.
   Why: Stating Ethereum is on "Fusaka" when it hasn't shipped yet is factually incorrect and undermines documentation credibility.

3. Section: Divergence from Ethereum
   Quote: "Gas Limit: 12.5 M (block cap) | Ethereum: 60 M (block); ~16.7 M per-tx (EIP-7825)"
   Suggestion: Verify Ethereum's current block gas limit. As of mid-2025, Ethereum's block gas limit was raised to 36M (not 60M). EIP-7825 and 60M may be proposals not yet live. Correct the Ethereum column to match the actual current state.
   Why: Incorrect Ethereum comparisons erode trust and may lead developers to make wrong capacity planning decisions.

4. Section: Divergence from Ethereum — SSTORE Gas Cost
   Quote: "Currently, the SSTORE gas cost is set to the non-standard value of 72,000 gas."
   Suggestion: Add a note explaining the practical impact: "This means deploying contracts with heavy storage writes will cost roughly 3.6× more per SSTORE than on Ethereum. Plan gas budgets accordingly." Also link to the governance mechanism for checking the current value.
   Why: Developers migrating from Ethereum will be surprised by 72k SSTORE costs. Without context on the magnitude of the difference, they may encounter unexpected gas failures.

5. Section: Frontend Development — Ethers.js Implementation
   Quote: chainId: '0x531', // 1329 in hexadecimal
   Suggestion: The hex value 0x531 equals 1329 in decimal — this is correct. However, in the SEI_NETWORK_PARAMS the chainId should be a string for wallet_addEthereumChain but the comment says "1329 in hexadecimal" which is slightly ambiguous. Clarify: // 1329 in decimal = 0x531 in hex.
   Why: Minor but avoids confusion for developers cross-referencing decimal and hex chain IDs.

6. Section: Staking Precompile — Critical: Understanding Decimal Precision
   Quote: "delegate() uses 18 decimals (wei) for msg.value" and "undelegate() and redelegate() use 6 decimals (uSEI) for amount parameters"
   Suggestion: Add a prominent warning box at the very top of the Staking Precompile page (not buried in the middle) with a one-line summary: "⚠️ delegate() takes 18-decimal wei; undelegate()/redelegate() take 6-decimal uSEI. Mixing these up will send the wrong amount."
   Why: This mixed-precision system is the Add user and dev content #1 footgun in the staking precompile. The current documentation buries this critical information deep in the page.

7. Section: EVM Development — Hardhat tutorial
   Quote: npx hardhat --init ... "When prompted, select: Hardhat3"
   Suggestion: The standard Hardhat initialization command is npx hardhat init (no --init flag). Verify the exact command for Hardhat 3 and correct it. Also, npx hardhat --init may just show help text rather than initialize a project.
   Why: An incorrect init command will block developers at the very first step of the tutorial.

8. Section: Sei Global Wallet — Installation
   Quote: import '@sei-js/sei-global-wallet/eip6963'; with note "Simply importing the package registers the wallet for discovery"
   Suggestion: Add a note clarifying that this import must execute before any wallet connection library initializes, and should be placed at the application entry point (e.g., main.tsx or App.tsx at the top). Several integration examples show this correctly but the core installation section doesn't emphasize ordering.
   Why: If the import runs after the wallet library initializes, EIP-6963 discovery may miss the Sei Global Wallet, causing a confusing "wallet not found" experience.

9. Section: MCP Server — Private Key Setup
   Quote: "Ensure the key starts with 0x"
   Suggestion: Add: "The key should be a 66-character hex string (0x + 64 hex characters). Do not use a mnemonic phrase here." Also mention that this wallet will have full signing authority over any funds it holds.
   Why: Developers unfamiliar with key formats may paste a mnemonic or an incomplete key, leading to cryptic errors. The security implication of giving an AI assistant a private key deserves explicit emphasis.

10. Section: USDC on Sei (Developers)
    Quote: The seiTestnet chain definition uses rpcUrls: { default: { http: ['https://evm-rpc-testnet.sei-apis.com'] } } but the Viem chain definition doesn't match the standard viem/chains export format.
    Suggestion: Since sei and seiTestnet are already exported from viem/chains, recommend using those built-in definitions instead of manually defining chains. Add: "For simplicity, you can import { sei, seiTestnet } from viem/chains instead of defining custom chain objects."
    Why: Manually defining chains that already exist in viem's chain registry creates maintenance burden and risks configuration drift.

11. Section: Quick Reference / Prerequisites
    Quote: "Sei EVM uses the Pectra EVM version (without blob transactions)."
    Suggestion: Add clarification about which specific EIPs from Pectra are supported and which are not. At minimum note: "EIP-7702 (SetCode/delegation) is supported. EIP-4844 blob transactions and blob-related opcodes are not supported."
    Why: "Pectra without blobs" is ambiguous — Pectra includes many EIPs. Developers need to know exactly which features are available, especially EIP-7702 which is mentioned elsewhere in the docs.

12. Section: Cambrian Agent Kit
    Quote: const agent = new SeiAgentKit(process.env.SEI_PRIVATE_KEY, 'openai');
    Suggestion: The constructor takes a private key and an AI provider string, but the docs don't explain what the second parameter does, what other values are supported, or whether it's optional. Add a brief explanation of the constructor signature.
    Why: Without knowing what 'openai' does or what alternatives exist, developers cannot customize the agent for their use case.

13. Section: Node Operations — Installation
    Quote: "RAM: 256 GB DDR5 or better"
    Suggestion: This requirement seems extremely high for a non-archive node. Clarify whether this is for validators, archive nodes, or all node types. Consider providing tiered requirements (e.g., "Full node: 64 GB, Validator: 128 GB, Archive/RPC: 256 GB").
    Why: 256 GB RAM as a blanket requirement will discourage operators and is likely not necessary for all node types. The Sei community validators likely don't all run 256 GB.

14. Section: Optimizing Contracts for Parallelization — Leverage Sei Precompiles
    Quote: "JSON (0x1003), P256 (0x1011)"
    Suggestion: This section only lists two precompiles. Add the other commonly used precompiles (Bank at 0x1001, Staking at 0x1005, Distribution at 0x1007, Address at 0x1004, IBC at 0x1009) with brief one-line descriptions of when each is useful for gas optimization.
    Why: The section claims "Precompiles are highly optimized and cheaper than replicating logic in Solidity" but only mentions two of the least commonly used ones, missing the most impactful ones for typical DeFi contracts.

15. Section: Accounts on Sei EVM and Cosmos-SDK
    Quote: "Cosmos tokens received by the EVM address prior to association will be held in a temporary Cosmos Bech32 address, which will transfer to the associated address upon linking."
    Suggestion: Clarify what happens if tokens are sent to the derived but unassociated address and the user never associates. Add: "If association never occurs, these tokens remain in the temporary address indefinitely. There is no automatic timeout or recovery mechanism."
    Why: Users need to understand the risk of sending tokens to an unassociated address. Without this clarity, funds could appear "lost" with no obvious recovery path.