feat(ecosystem): add Monad skill (concepts, gas, addresses, HyperIndex)

.claude-plugin/plugin.json

@@ -2,6 +2,7 @@
   "name": "alchemy",
   "skills": [
     "./skills/ecosystem/allium",
+    "./skills/ecosystem/monad"
     "./skills/ecosystem/opensea"
   ]
 }

skills/ecosystem/README.md

@@ -40,7 +40,8 @@ When adding a new partner skill, add an entry to `plugin.json` so it gets instal
 
 ## Current partners
 
-- **Allium** — wallet PnL (current + historical, by-wallet and by-token), holdings timeseries, Hyperliquid trading data (info, fills, orders, orderbook), and custom SQL analytics over Allium's data warehouse ([`./skills/allium/`](./skills/allium/)). Curated subset of [allium-labs/skills](https://github.com/allium-labs/skills) — overlapping endpoints (prices, token metadata, current balances, transactions, NFT) are intentionally omitted and routed to first-party Alchemy skills.
+- **Allium** — wallet PnL (current + historical, by-wallet and by-token), holdings timeseries, Hyperliquid trading data (info, fills, orders, orderbook), and custom SQL analytics over Allium's data warehouse ([`./allium/`](./allium/)). Curated subset of [allium-labs/skills](https://github.com/allium-labs/skills) — overlapping endpoints (prices, token metadata, current balances, transactions, NFT) are intentionally omitted and routed to first-party Alchemy skills.
+- **Monad** — building on Monad mainnet/testnet: architecture concepts (async execution, parallel execution, EIP-7702), gas pricing rules (`gas_limit` not `gas_used`), canonical contract addresses, and HyperIndex (Envio Cloud) on-chain event indexing ([`./monad/`](./monad/)). Curated subset of [therealharpaljadeja/monskills](https://github.com/therealharpaljadeja/monskills) — Alchemy's Monad RPC, Account Kit / Bundler / Gas Manager are routed back to first-party `alchemy-*` skills.
 
 ## Routing for agents
 
@@ -52,5 +53,6 @@ When adding a new partner skill, add an entry to `plugin.json` so it gets instal
 | Holdings timeseries history | `allium` |
 | Hyperliquid trading data (fills, orders, positions, orderbook) | `allium` |
 | Custom SQL on a blockchain data warehouse (DeFi, NFT, bridges, MEV, Solana staking) | `allium` |
+| Monad-specific concepts, gas pricing, canonical addresses, HyperIndex event indexing | `monad` |
 
 See each skill's `SKILL.md` for its exact `scope_in` / `scope_out`.

skills/ecosystem/monad/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright 2026 Harpalsinh Jadeja
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

skills/ecosystem/monad/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: monad
+description: Build apps on Monad — high-throughput EVM L1 with 400ms blocks, 800ms finality, async execution, native EIP-7702 support, and a unique gas pricing model where users pay for `gas_limit` not `gas_used`. Use for Monad architecture concepts, canonical contract addresses, gas pricing rules, and HyperIndex (Envio Cloud) indexing of on-chain events. For Alchemy's Monad RPC, Account Kit (agent wallets), Bundler, or Gas Manager — use `alchemy-cli` (live), `alchemy-api` (with API key), or `alchemy-agentic-gateway` (without). Curated subset of `therealharpaljadeja/monskills`.
+license: MIT
+compatibility: Public on-chain data; references only. Some recipes call Envio Cloud or `pnpx envio` for indexing — those need `envio-cloud` and `gh` installed and logged in.
+metadata:
+  author: therealharpaljadeja
+  version: "0.1"
+  provider: monad
+  partner: "true"
+---
+
+# Monad
+
+Curated entry point into the [Monskills](https://skills.devnads.com) catalog by [Harpalsinh Jadeja](https://github.com/therealharpaljadeja). Covers Monad-specific topics — async execution, the `gas_limit` pricing model, canonical addresses, and HyperIndex indexing — that complement Alchemy's first-party Monad surfaces (JSON-RPC, Account Kit / Bundler / Gas Manager for agent wallets and sponsored transactions).
+
+| | |
+| --- | --- |
+| **Chains** | Monad mainnet, Monad testnet |
+| **Block time** | ~400ms |
+| **Finality** | ~800ms |
+| **Throughput** | 10,000 tps |
+| **EVM** | Fully compatible (no contract changes needed). Native EIP-7702. |
+| **Gas pricing** | Charged on `gas_limit`, not `gas_used` — wrong limits cost users real money |
+| **Explorers** | monadscan.com (mainnet), testnet.monadscan.com (testnet) |
+| **Upstream** | `therealharpaljadeja/monskills` — `npx skills add therealharpaljadeja/monskills` for the full catalog |
+
+## When to use this skill
+
+Use `monad` when **any** of the following apply:
+
+- Building an app on Monad mainnet or testnet
+- The user needs to understand Monad-specific behavior that differs from Ethereum — async execution, parallel execution, block states (`latest`/`safe`/`finalized`), reserve balance (10 MON floor per EOA), or native EIP-7702 delegation
+- Setting gas limits on Monad — `gas_limit` is what users pay, **not** actual `gas_used`. Wrong limits cost real money. Cold state access is 3-4x more expensive than Ethereum; precompiles are 2-5x more expensive.
+- Looking up canonical contract addresses on Monad (Wrapped MON, ERC-4337 EntryPoint, Multicall3, Safe, Permit2, bridged stables/ETH/BTC, ERC-8004 agent identity registry, etc.)
+- Indexing on-chain events on Monad — HyperIndex deployed via `envio-cloud` for activity feeds, leaderboards, transaction history, analytics dashboards
+- Choosing a chain to build on — Monad is high-throughput EVM with full Solidity compatibility
+
+## When to use a different skill
+
+| Need | Use instead |
+| --- | --- |
+| Live JSON-RPC queries to Monad from this agent session | `alchemy-cli` (CLI) or `alchemy-mcp` (MCP) — Alchemy provides Monad mainnet RPC |
+| App code making JSON-RPC calls to Monad | `alchemy-api` (with API key) or `alchemy-agentic-gateway` (without) |
+| Account Kit / Bundler / Smart Account setup for agent wallets on Monad with full ERC-4337 infrastructure | `alchemy-cli` (live) or `alchemy-api` (app code) |
+| Gas sponsorship / paymaster policies on Monad | `alchemy-cli` (live) or `alchemy-api` (Gas Manager) |
+| Token metadata, prices, or portfolio reads on Monad | Not supported by Alchemy Token / Prices / Portfolio APIs on Monad yet — use the [`indexer`](./references/indexer.md) (HyperIndex via Envio Cloud) for on-chain data, or query Monad-native protocols directly |
+| NFT marketplace data, listings, or fulfillment | `opensea-api` / `opensea-marketplace` (where they support Monad) |
+| Fiat → MON on-ramp | `moonpay` ecosystem skill |
+
+## Setup
+
+This skill is documentation-only — no auth required to read it. The recipes inside link to specific tools (e.g. `envio-cloud`, `cast`, `pnpx envio`) and call out their prerequisites in line.
+
+For the **full** monskills catalog (scaffold, wallet, wallet-integration, vercel-deploy, feedback, etc.), install the upstream:
+
+```bash
+npx skills add therealharpaljadeja/monskills
+```
+
+## References
+
+Detailed coverage per topic lives in [`./references/`](./references/):
+
+- [`concepts.md`](./references/concepts.md) — Monad architecture (async execution, parallel execution, block states, reserve balance, EIP-7702, real-time data sources)
+- [`gas.md`](./references/gas.md) — Gas pricing on Monad (charged on `gas_limit`, base fee controller, opcode repricing, developer guidelines)
+- [`addresses.md`](./references/addresses.md) — Canonical contract addresses on Monad mainnet (ERC-4337 EntryPoint, Safe, Multicall3, Permit2, bridged assets, ERC-8004 agent registry)
+- [`indexer.md`](./references/indexer.md) — HyperIndex on Envio Cloud — initialize and deploy an indexer for Monad smart contract events
+
+## Source
+
+Curated from upstream [`therealharpaljadeja/monskills`](https://github.com/therealharpaljadeja/monskills) under MIT license (Copyright 2026 Harpalsinh Jadeja). Upstream is the source of truth — install it directly for the full catalog.

skills/ecosystem/monad/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Monad"
+  short_description: "Build on Monad — concepts, gas, addresses, HyperIndex"
+  default_prompt: "Use the monad ecosystem skill for Monad-specific concepts (async execution, EIP-7702), gas pricing rules (charged on gas_limit), canonical addresses, and HyperIndex event indexing."

skills/ecosystem/monad/references/addresses.md

@@ -0,0 +1,115 @@
+# Canonical Contract Addresses on Monad
+
+> **CRITICAL:** Always verify with a network explorer before interacting. Never hallucinate an address — wrong addresses can mean **loss of funds**.
+
+| Network | Explorer | RPC (public) |
+| --- | --- | --- |
+| Monad Mainnet | `monadscan.com` | `https://rpc.monad.xyz` |
+| Monad Testnet | `testnet.monadscan.com` | `https://testnet-rpc.monad.xyz` |
+
+If the user hasn't specified mainnet vs testnet, **ask**. Do not provide a mainnet address when the user asked for a testnet address (or vice versa).
+
+For Alchemy's authenticated Monad endpoints (rate-limited and reliable), use `alchemy-cli` or `alchemy-api`.
+
+## Verifying an address has code
+
+If Foundry is installed:
+
+```bash
+# Mainnet
+cast code <SMART_CONTRACT_ADDRESS> --rpc-url https://rpc.monad.xyz
+
+# Testnet
+cast code <SMART_CONTRACT_ADDRESS> --rpc-url https://testnet-rpc.monad.xyz
+```
+
+Otherwise call `eth_getCode` directly via JSON-RPC.
+
+## Canonical contracts (Monad mainnet)
+
+| Name | Address |
+| --- | --- |
+| Wrapped MON (`WMON`) | `0x3bd359C1119dA7Da1D913D1C4D2B7c461115433A` |
+| Create2Deployer | `0x13b0D85CcB8bf860b6b79AF3029fCA081AE9beF2` |
+| CreateX | `0xba5Ed099633D3B313e4D5F7bdc1305d3c28ba5Ed` |
+| ERC-2470 Singleton Factory | `0xce0042b868300000d44a59004da54a005ffdcf9f` |
+| **ERC-4337 EntryPoint v0.6** | `0x5FF137D4b0FDCD49DcA30c7CF57E578a026d2789` |
+| ERC-4337 SenderCreator v0.6 | `0x7fc98430eAEdbb6070B35B39D798725049088348` |
+| **ERC-4337 EntryPoint v0.7** | `0x0000000071727De22E5E9d8BAf0edAc6f37da032` |
+| ERC-4337 SenderCreator v0.7 | `0xEFC2c1444eBCC4Db75e7613d20C6a62fF67A167C` |
+| ERC-6492 UniversalSigValidator | `0xdAcD51A54883eb67D95FAEb2BBfdC4a9a6BD2a3B` |
+| Foundry Deterministic Deployer | `0x4e59b44847b379578588920ca78fbf26c0b4956c` |
+| Multicall3 | `0xcA11bde05977b3631167028862bE2a173976CA11` |
+| MultiSend | `0x998739BFdAAdde7C933B942a68053933098f9EDa` |
+| MultiSendCallOnly | `0xA1dabEF33b3B82c7814B6D82A79e50F4AC44102B` |
+| Permit2 | `0x000000000022d473030f116ddee9f6b43ac78ba3` |
+| Safe | `0x69f4D1788e39c87893C980c06EdF4b7f686e2938` |
+| SafeL2 | `0xfb1bffC9d739B8D520DaF37dF666da4C687191EA` |
+| SafeSingletonFactory | `0x914d7Fec6aaC8cd542e72Bca78B30650d45643d7` |
+| SimpleAccount | `0x68641DE71cfEa5a5d0D29712449Ee254bb1400C2` |
+| Simple7702Account | `0xe6Cae83BdE06E4c305530e199D7217f42808555B` |
+| Sub Zero VanityMarket | `0x000000000000b361194cfe6312EE3210d53C15AA` |
+| Zoltu Deterministic Deployment Proxy | `0x7A0D94F55792C434d74a40883C6ed8545E406D12` |
+
+## ERC-8004 (AI agent identity registry — same on Monad mainnet and testnet)
+
+| Contract | Address |
+| --- | --- |
+| IdentityRegistry | `0x8004A169FB4a3325136EB29fA0ceB6D2e539a432` |
+| ReputationRegistry | `0x8004BAa17C55a88189AE136b182e5fdA19dE9b63` |
+
+## Bridged stablecoins (Monad mainnet)
+
+| Symbol | Name | Address |
+| --- | --- | --- |
+| AUSD | Agora USD | `0x00000000eFE302BEAA2b3e6e1b18d08D69a9012a` |
+| USDC | USD Coin | `0x754704Bc059F8C67012fEd69BC8A327a5aafb603` |
+| USDT0 | Tether USD | `0xe7cd86e13AC4309349F30B3435a9d337750fC82D` |
+| USD1 | USD1 | `0x111111d2bf19e43C34263401e0CAd979eD1cdb61` |
+| thBILL | Theo Short Duration UST Fund | `0xfDD22Ce6D1F66bc0Ec89b20BF16CcB6670F55A5a` |
+| wsrUSD | Wrapped srUSD | `0x4809010926aec940b550D34a46A52739f996D75D` |
+| yzUSD | Yuzu USD | `0x9dcB0D17eDDE04D27F387c89fECb78654C373858` |
+| syzUSD | Staked Yuzu USD | `0x484be0540aD49f351eaa04eeB35dF0f937D4E73f` |
+
+## Bridged ETH-related (Monad mainnet)
+
+| Symbol | Name | Address |
+| --- | --- | --- |
+| WETH | Wrapped Ether | `0xEE8c0E9f1BFFb4Eb878d8f15f368A02a35481242` |
+| ezETH | Renzo Restaked ETH | `0x2416092f143378750bb29b79eD961ab195CcEea5` |
+| wstETH | Lido Wrapped Staked ETH | `0x10Aeaf63194db8d453d4D85a06E5eFE1dd0b5417` |
+| weETH | Wrapped EtherFi ETH | `0xA3D68b74bF0528fdD07263c60d6488749044914b` |
+| pufETH | pufETH | `0x37D6382B6889cCeF8d6871A8b60E667115eDDBcF` |
+
+## Bridged BTC-related (Monad mainnet)
+
+| Symbol | Name | Address |
+| --- | --- | --- |
+| cbBTC | Coinbase Wrapped BTC | `0xd18B7EC58Cdf4876f6AFebd3Ed1730e4Ce10414b` |
+| WBTC | Wrapped Bitcoin | `0x0555E30da8f98308EdB960aa94C0Db47230d2B9c` |
+| LBTC | Lombard Staked Bitcoin | `0xecAc9C5F704e954931349Da37F60E39f515c11c1` |
+| BTC.b | BTC.b | `0xB0F70C0bD6FD87dbEb7C10dC692a2a6106817072` |
+| SolvBTC | Solv BTC | `0xaE4EFbc7736f963982aACb17EFA37fCBAb924cB3` |
+| xSolvBTC | xSolvBTC | `0xc99F5c922DAE05B6e2ff83463ce705eF7C91F077` |
+
+## MON on other chains
+
+| Name | Chain | Address |
+| --- | --- | --- |
+| WMON | Solana | `CrAr4RRJMBVwRsZtT62pEhfA9H5utymC2mVx8e7FreP2` |
+| WMON | Ethereum | `0x6917037f8944201b2648198a89906edf863b9517` |
+
+## Beyond the canonical set
+
+For protocol-specific addresses (DEXs, lending markets, etc.), check the official Monad repositories — they are versioned and curated:
+
+- **Protocols:** https://github.com/monad-crypto/protocols
+  Organized as `mainnet/<protocol>.jsonc` and `testnet/<protocol>.jsonc`. Each file has an `addresses` object with named entries.
+- **Token list:** https://github.com/monad-crypto/token-list
+  Per-token folders under `mainnet/` with address JSON.
+
+If an address isn't in the tables above or the upstream repos, **ask the user**. Do not hallucinate.
+
+## Upstream reference
+
+Full monskills `addresses/` skill: https://github.com/therealharpaljadeja/monskills/blob/main/addresses/SKILL.md

skills/ecosystem/monad/references/concepts.md

@@ -0,0 +1,57 @@
+# Monad Architecture Concepts
+
+Monad is Ethereum-compatible (no Solidity changes required), but its architecture introduces behaviors that affect how apps must be built.
+
+## Quick reference
+
+| Concept | Summary |
+| --- | --- |
+| **Async execution** | Consensus and execution are decoupled. Block leaders propose blocks **before** executing them. State view is delayed by ~3 blocks. **Newly funded accounts need ~1.2s** before they can send transactions. |
+| **Parallel execution** | Optimistic concurrency. Transactions run in parallel where state-disjoint; conflicts re-run. Identical results to Ethereum. **No contract changes needed.** |
+| **Block states** | Proposed → Voted → Finalized → Verified. Maps to JSON-RPC tags `pending`/`latest` (proposed), `safe` (voted), `finalized` (committed). |
+| **Reserve balance** | EOAs maintain a **10 MON floor**. Low-balance accounts are limited to ~1 tx per 1.2s. Emptying transactions revert if they'd take the balance below 10 MON. |
+| **EIP-7702** | EOAs delegate to contracts for smart-wallet features (session keys, gas sponsorship, batch txs). 10 MON floor still applies. **No `CREATE`/`CREATE2` in delegated context.** |
+| **Real-time data** | Three sources: (1) Geth-compatible WebSocket — the default for most apps; (2) Monad extended WebSocket — richer event payloads; (3) Execution Events SDK — speculative pre-finality EVM traces. |
+
+## Block state → JSON-RPC tag mapping
+
+When making `eth_call` / `eth_getBlock*` / `eth_getBalance` and friends:
+
+| RPC tag | Monad state | Use when |
+| --- | --- | --- |
+| `pending` | Proposed (not yet voted) | Optimistic UI — show what's likely about to land |
+| `latest` | Proposed → executed (~3 block delay between proposal and visible state) | Default for most reads |
+| `safe` | Voted by validators | Defensive UI for high-value displays |
+| `finalized` | Finalized (committed by consensus) | Settlement guarantees, bridges, irrevocable actions |
+
+## Async execution gotchas
+
+The most common failure mode: **fund an account, then immediately try to send a tx — the tx fails**. State visibility lags execution by ~3 blocks (~1.2s). Wait one finalization cycle before relying on a balance change.
+
+Apps that show "funded ✓" → "send tx" UX should either:
+1. Poll `eth_getBalance` against `latest` until the balance reaches the expected value (1-2 seconds), OR
+2. Insert an explicit 1.5–2s delay between funding and dependent transactions.
+
+## EIP-7702 (delegated EOAs)
+
+EIP-7702 is natively supported on Monad mainnet from day one. An EOA signs a delegation to a smart contract — subsequent transactions from that EOA execute the contract's logic. This unlocks smart-wallet features (session keys, paymasters, batch calls) without migrating to a separate smart account address.
+
+Caveats:
+- The 10 MON reserve balance floor still applies to delegated EOAs.
+- `CREATE` and `CREATE2` are **not** available inside delegated execution. Use canonical factories (CreateX, Create2Deployer — see [`addresses.md`](./addresses.md)) for deterministic deployments.
+
+For Alchemy's ERC-4337 smart-account path (which is independent of EIP-7702 and uses a separate smart-account address), use `alchemy-cli` or `alchemy-api`.
+
+## Full upstream coverage
+
+Each concept has a detailed reference in upstream monskills:
+
+- async-execution.md — newly funded accounts, funding delays, 3-block state delay
+- parallel-execution.md — what changes (nothing) for existing Solidity
+- block-states.md — choosing between `latest` / `safe` / `finalized` tags
+- reserve-balance.md — 10 MON floor, emptying transactions, low-balance throttling
+- eip-7702.md — smart wallet delegation, session keys, gas sponsorship caveats
+- realtime-data.md — Geth WS vs Monad extended WS vs Execution Events SDK
+- execution-events.md — BLOCK_START / QC / FINALIZED lifecycle events
+
+Browse them via the `concepts/` skill in [`therealharpaljadeja/monskills`](https://github.com/therealharpaljadeja/monskills/tree/main/concepts).