AI Docs Review — 2026-03-16

[github-actions]

AI Documentation Review — 2026-03-16

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

1. Section: Divergence from Ethereum (comparison table)
   Quote: EVM Version | Pectra (w/o blobs) | Fusaka
   Suggestion: Verify that Ethereum's current mainnet EVM version is actually "Fusaka." As of mid-2025, Ethereum mainnet is on Pectra (Prague+Electra); "Fusaka" (Fulu+Osaka) is a planned future upgrade. If Fusaka has not yet shipped, update the Ethereum column to "Pectra" and note Fusaka as upcoming.
   Why: Stating Ethereum is on Fusaka when it may still be on Pectra is a factual inaccuracy that undermines trust in the comparison table—developers rely on this to understand compatibility differences.

2. Section: Divergence from Ethereum
   Quote: Gas Limit | 12.5 M (block cap) | 60 M (block); ~16.7 M per-tx (EIP-7825)
   Suggestion: Clarify that Sei's 12.5M gas limit serves as both the block gas limit AND the per-transaction gas cap (since a single tx can consume the entire block). The "Per-Tx Gas Cap" row repeats the same 12.5M, which is confusing—add a note like "On Sei, the per-tx cap equals the block cap since one transaction can fill an entire block."
   Why: Developers coming from Ethereum (where block limit and per-tx limit differ) may be confused by the redundant rows without explanation.

3. Section: Quick Reference / Prerequisites
   Quote: Sei has 400ms block times — set lower polling intervals than on Ethereum.
   Suggestion: Add a concrete recommendation, e.g., "Set polling intervals to 400–500ms instead of Ethereum's typical 12–15 seconds. For example, in ethers.js: provider.pollingInterval = 500;"
   Why: Developers need actionable guidance, not just a vague suggestion to "set lower" intervals. A code snippet prevents common mistakes.

4. Section: MCP Server setup instructions
   Quote: "command": "npx", "args": ["-y", "@sei-js/mcp-server"]
   Suggestion: The overview section says npx -y @sei-js/mcp-server (package name @sei-js/mcp-server), but the resources section links to https://github.com/sei-protocol/sei-mcp-server while the MCP page says contribute at github.com/sei-protocol/sei-js. Clarify the canonical package name and repository location consistently across all references.
   Why: Inconsistent package/repo references confuse developers trying to find the source code or file issues.

5. 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: This is a critical difference from Ethereum's 20,000 gas SSTORE cost (3.6× higher). Add a prominent callout or warning box noting the impact: "This means storage-heavy contracts will cost significantly more gas on Sei than on Ethereum. Factor this into gas estimates and contract design." Also link to the parallelization optimization guide.
   Why: A 3.6× difference in the most common expensive opcode is easily overlooked in prose form but has major implications for contract cost estimation and migration from Ethereum.

6. Section: Frontend Development — Ethers.js Implementation
   Quote: chainId: '0x531', // 1329 in hexadecimal
   Suggestion: 1329 in hexadecimal is 0x531. This is correct. However, in the Moralis integration page, the testnet hex is listed as 0x530 for chain ID 1328, which is also correct. But in the Thirdweb EIP-7702 guide, the testnet chain ID hex is listed as 0xAE3F2 (713714), which contradicts the documented testnet chain ID of 1328. Remove or correct this reference to avoid confusion.
   Why: The Sei Global Wallet HTML integration FAQ also references 0xAE3F3 (713715) as a testnet chain ID. These appear to be obsolete devnet chain IDs that conflict with the official testnet chain ID 1328 documented everywhere else.

7. Section: Staking Precompile — Decimal Precision
   Quote: delegate() uses 18 decimals (wei) for msg.value / undelegate() and redelegate() use 6 decimals (uSEI) for amount parameters
   Suggestion: Add a prominent "⚠️ Common Pitfall" callout box at the top of the staking precompile page (before the functions section) summarizing this critical difference in a single sentence, e.g., "delegate() takes 18-decimal wei via msg.value; undelegate()/redelegate() take 6-decimal uSEI as a uint256 parameter. Mixing these up will result in sending 10^12× too much or too little."
   Why: This is the Add user and dev content #1 source of bugs for staking integrations. The detailed explanation exists deep in the page but developers scanning quickly will miss it. A top-of-page warning prevents costly mistakes.

8. Section: Cambrian Agent Kit — Monitoring & Alerts
   Quote: agent.on('transactionFailed', (error) => { ... });
   Suggestion: Verify that SeiAgentKit actually exposes an .on() event emitter API. The code examples earlier use SeiAgentKit as a class with async methods, not an EventEmitter. If this API doesn't exist, remove or replace this example to avoid developer confusion.
   Why: Documenting a non-existent API causes developers to waste time debugging why their event listeners don't work.

9. Section: Deploy a contract with Hardhat (Examples section)
   Quote: solidity: "0.8.26"
   Suggestion: Update to "0.8.28" to match the Solidity version used consistently throughout the Hardhat and Foundry tutorial pages (which use 0.8.28). Alternatively, use "0.8.22" to match the LayerZero guide. Pick one version and use it consistently across all quick-start examples.
   Why: Inconsistent Solidity versions across examples create unnecessary confusion about which version is recommended.

10. Section: Distribution Precompile — Decimal Precision
    Quote: rewards() query returns amounts with 18 decimal precision (DecCoins)
    Suggestion: The page explains the 18-decimal vs 6-decimal distinction well but the conversion helpers use Number() which will lose precision for large BigInt values. Change Number(amount) / 1e18 to use ethers.formatUnits(amount, 18) or add a note about precision loss with Number().
    Why: Using Number() on large uint256 values silently loses precision beyond 2^53, which is exactly the kind of bug that costs users money in DeFi applications.

11. Section: Sei EVM Networks
    Quote: The networks table shows MetaMask column but the content is empty/just shows a button
    Suggestion: For the MetaMask column, provide the actual wallet_addEthereumChain parameters or a direct "Add to MetaMask" deep link (e.g., using EIP-3085 chainId format) so developers can click to add the network directly.
    Why: An empty column wastes space. A one-click "Add Network" button is a standard UX pattern that significantly improves developer onboarding.

12. Section: Optimizing Contracts for Parallelization — Leverage Sei Precompiles
    Quote: JSON (0x1003) and P256 (0x1011) listed as precompiles to leverage
    Suggestion: This list is misleadingly short. Add at least the Staking (0x1005), Bank (0x1001), and Distribution (0x1007) precompiles, which are far more commonly used than JSON or P256 for typical contract optimization. Link to the full precompiles section.
    Why: Developers reading the optimization guide would benefit most from knowing about high-impact precompiles like Bank and Staking, not just the niche JSON/P256 ones.

13. Section: Verify Contract
    Quote: --evm-version "cancun" in the example Foundry verification command
    Suggestion: The Divergence from Ethereum page states Sei uses the "Pectra" EVM version. The verification example should use --evm-version "pectra" (or whatever the correct Foundry flag is), not "cancun". If Foundry doesn't yet support a pectra flag, document the correct workaround.
    Why: Using the wrong EVM version during verification will cause bytecode mismatches, leading to failed verification—a frustrating experience for developers.

14. Section: Changelog — v5.0.0
    Quote: Compare v3.9.0 → v3.9.0 (for both sei-chain and sei-cosmos/sei-tendermint)
    Suggestion: These "Compare" links compare the same version to itself (v3.9.0 → v3.9.0), which shows no changes. This appears to be a data error—the comparison should likely be from a previous version to v3.9.0 (or to v5.0.0). Fix the comparison ranges or remove these broken entries.
    Why: Broken changelog links erode developer trust and make it impossible to review what changed in a major version upgrade.

15. Section: IBC Precompile documentation
    Quote: The entire page description says "Documentation for Sei. Providing comprehensive guides..."—a generic placeholder description, not actual content description.
    Suggestion: Replace with a specific description: "Learn how to use Sei's IBC precompile to transfer tokens across IBC-connected chains directly from EVM smart contracts, including transfer functions with default and custom timeouts." Also add JavaScript/ethers.js usage examples like other precompile pages have.
    Why: The IBC precompile page is the only precompile without usage examples, making it significantly less useful than peer pages. The generic description suggests the page was published from a template without proper review.