Skip to content

feat: add alchemy skill (RPC, Account Kit, Bundler, Gas Manager) #45

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
SahilAujla wants to merge 1 commit into
base: dev
Choose a base branch
from
Open

feat: add alchemy skill (RPC, Account Kit, Bundler, Gas Manager) #45

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion .claude-plugin/plugin.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,7 @@
"./gas",
"./tooling-and-infra",
"./feedback",
"./indexer"
"./indexer",
"./alchemy"
]
}
7 changes: 7 additions & 0 deletions SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,7 @@ This file will guide to the right skill with the latest knowledge about Monad an
| Understanding gas pricing on Monad | `gas/` |
| Checking if a tooling/infra provider supports Monad | `tooling-and-infra/` |
| Adding a historical/activity feed or any feature that requires indexing onchain smart contract events | `indexer/` |
| Setting up Alchemy as the Monad RPC provider, or building an ERC-4337 smart-account agent wallet on Monad with sponsored gas (Gas Manager / Account Kit / Bundler) | `alchemy/` |
| Reporting that monskills got you stuck, hit the same error, or the user is complaining about monskills | `feedback/` |

## Skills
Expand Down Expand Up @@ -79,6 +80,12 @@ This file will guide to the right skill with the latest knowledge about Monad an
- Prereqs: `npm install -g envio-cloud` + `envio-cloud login`. The monskills hook gates `envio-cloud` commands until both are satisfied.
- Never install the CLI or run `login` on the user's behalf — surface the prompt and wait.

### [Alchemy](/alchemy/SKILL.md)
- Use Alchemy for Monad mainnet **JSON-RPC**, **Account Kit** (ERC-4337 smart accounts), **Bundler**, and **Gas Manager** (paymaster for sponsored transactions).
- Pair with `gas/` — sponsored ops still pay the policy owner for `gas_limit`, not `gas_used`. Tight estimates matter.
- Alchemy's Token / NFT / Prices / Portfolio / Transfers / Simulation / Webhook APIs do **NOT** yet support Monad mainnet — for on-chain data, use `indexer/`.
- Authored by Alchemy under MIT.

### [Feedback](/feedback/SKILL.md)
- Anonymous feedback pipeline for agents using monskills.
- Fetch when the agent is stuck, hitting the same error repeatedly, or the user is complaining about monskills.
Expand Down
87 changes: 87 additions & 0 deletions alchemy/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,87 @@
---
name: alchemy
description: Use Alchemy for the parts of building on Monad that Alchemy supports today — Monad mainnet **JSON-RPC**, **Account Kit** (ERC-4337 smart accounts for agent wallets), **Bundler**, and **Gas Manager** (paymaster for sponsored transactions). Fetch this skill when the agent needs an RPC endpoint, needs to set up an AA agent wallet with a smart account, or needs to sponsor gas. Pair it with monskills' `gas/` for Monad-specific `gas_limit` pricing rules, `concepts/` for async execution caveats, and `addresses/` for canonical ERC-4337 EntryPoint addresses. Alchemy's Token / NFT / Prices / Portfolio / Transfers APIs do **NOT** support Monad yet — for on-chain data, fetch `indexer/` (HyperIndex on Envio Cloud) instead.
---

# Alchemy on Monad

Alchemy's developer platform supports Monad mainnet for **standard EVM JSON-RPC** and **Account Abstraction** (Account Kit, Bundler, Gas Manager). This skill points agents at the right Alchemy entrypoint for each use case on Monad.

> **What Alchemy does NOT yet support on Monad:** Token API, NFT API, Prices API, Portfolio API, Transfers API, Simulation API, Webhooks. For on-chain data on Monad use the [`indexer/`](../indexer/SKILL.md) skill (HyperIndex on Envio Cloud). For Monad-specific gas pricing rules use [`gas/`](../gas/SKILL.md). For canonical ERC-4337 EntryPoint and Safe addresses use [`addresses/`](../addresses/SKILL.md).

## When to fetch this skill

- The user wants a Monad mainnet **RPC endpoint** with rate limits and reliability suitable for production (`eth_call`, `eth_getLogs`, `eth_sendRawTransaction`, etc.)
- The user wants to set up an **agent wallet** as an ERC-4337 smart account (Alchemy Modular Account v2) instead of an EOA + Safe multisig
- The user wants to **sponsor gas** for user transactions on Monad (paymaster policies via Gas Manager)
- The user is putting the above three together (smart account + bundler + sponsored gas) for production agent wallets on Monad

## When to fetch a different skill

| Need | Fetch instead |
| --- | --- |
| Monad-specific concepts (async execution, parallel execution, EIP-7702, block states, reserve balance) | [`concepts/`](../concepts/SKILL.md) |
| Setting gas limits on Monad (gas is charged on `gas_limit`, not `gas_used`) | [`gas/`](../gas/SKILL.md) |
| Canonical contract addresses on Monad (Wrapped MON, ERC-4337 EntryPoint v0.6/v0.7, Safe, Multicall3, Permit2) | [`addresses/`](../addresses/SKILL.md) |
| Indexing on-chain events on Monad — activity feeds, leaderboards, transaction history, analytics | [`indexer/`](../indexer/SKILL.md) (HyperIndex via Envio Cloud) |
| EOA + Safe multisig agent wallet (no smart-account migration) | [`wallet/`](../wallet/SKILL.md) |
| Token metadata, prices, portfolio, or transaction history reads on Monad | Not supported by Alchemy on Monad yet — use [`indexer/`](../indexer/SKILL.md) for on-chain reads |
| Token swaps on Monad | Not supported by Alchemy — use the relevant DEX |
| Fiat → MON on-ramp | Use a fiat ramp provider |

## Endpoints (Monad mainnet)

| Surface | URL |
| --- | --- |
| JSON-RPC (HTTPS) | `https://monad-mainnet.g.alchemy.com/v2/<ALCHEMY_API_KEY>` |
| JSON-RPC (WSS) | `wss://monad-mainnet.g.alchemy.com/v2/<ALCHEMY_API_KEY>` |
| Bundler (ERC-4337) | `https://monad-mainnet.g.alchemy.com/v2/<ALCHEMY_API_KEY>` (chain-specific path; see [Account Kit docs](https://www.alchemy.com/docs/wallets)) |
| Gas Manager (policy API) | `https://manage.g.alchemy.com/api/gasManager/policy` (policies are managed in the Alchemy dashboard) |

Get an API key at https://dashboard.alchemy.com (free tier available).

## Pick your Alchemy entrypoint

Three ways to use Alchemy from a developer workflow. Pick the one that matches your environment.

| Entrypoint | When |
| --- | --- |
| **CLI** (`@alchemy/cli`) | Live agent work in this session: querying, admin, on-machine automation. Install with `npm i -g @alchemy/cli`. |
| **MCP** (`https://mcp.alchemy.com/mcp`) | Live agent work when MCP is wired into the client but the CLI is not installed locally. |
| **API** (with `ALCHEMY_API_KEY`) | Shipped application code. Use the JSON-RPC endpoint above with a key from https://dashboard.alchemy.com. |

## Quickstart on Monad

### JSON-RPC: read state

```bash
curl -s -X POST https://monad-mainnet.g.alchemy.com/v2/$ALCHEMY_API_KEY \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}'
```

The standard EIP-1559 set (`eth_call`, `eth_getLogs`, `eth_getBalance`, `eth_getBlockByNumber`, `eth_getTransactionReceipt`, `eth_sendRawTransaction`, etc.) works as on Ethereum. Use the Monad block-state tags — `pending` / `latest` / `safe` / `finalized` — to pick the right consistency level. See [`concepts/`](../concepts/SKILL.md) for what each tag means on Monad and the ~1.2s async-execution gotcha.

### Account Kit + Bundler + Gas Manager: agent wallet flow

End-to-end pattern for a Monad agent wallet with sponsored transactions:

1. Create an Alchemy smart account (Modular Account v2) backed by an EOA signer
2. Point Bundler at the Monad endpoint: `https://monad-mainnet.g.alchemy.com/v2/<ALCHEMY_API_KEY>`
3. Create a Gas Manager policy in the Alchemy dashboard scoped to your Monad app, capture the Policy ID
4. Pass the Policy ID to the smart-account client so user operations route through the paymaster
5. Submit transactions through the smart account — the bundler + paymaster handle sponsorship; the user signs once

Detailed step-by-step in [`./references/account-kit.md`](./references/account-kit.md) and [`./references/gas-manager.md`](./references/gas-manager.md).

> **Monad gotcha:** Monad charges users for `gas_limit`, not `gas_used`. When the paymaster sponsors a transaction, the **paymaster** is the one paying — so over-estimated gas limits directly cost the policy owner. Set tight estimates and avoid wallet fallbacks that inflate the limit on estimation failure. See [`gas/`](../gas/SKILL.md).

## References

- [`./references/json-rpc.md`](./references/json-rpc.md) — Monad mainnet JSON-RPC via Alchemy, common methods, block tags, rate limit notes
- [`./references/account-kit.md`](./references/account-kit.md) — ERC-4337 smart account setup on Monad with Alchemy Account Kit (Modular Account v2)
- [`./references/gas-manager.md`](./references/gas-manager.md) — Paymaster policies, sponsorship modes, ERC-20 gas payments, BSO (Bundler Sponsorship), Monad-specific cost implications

## Source
Comment thread
SahilAujla marked this conversation as resolved.

Authored by Alchemy under MIT.
126 changes: 126 additions & 0 deletions alchemy/references/account-kit.md
View file
Open in desktop
Comment thread
SahilAujla marked this conversation as resolved.
Original file line number Diff line number Diff line change
@@ -0,0 +1,126 @@
# Account Kit on Monad (ERC-4337 Smart Accounts)

Alchemy Account Kit creates ERC-4337 smart accounts on Monad. The primary use case in this skill is the **agent-controlled wallet** path: the agent (or your script) operates a smart account to deploy contracts and run onchain actions, with sponsored gas (Gas Manager), session keys for scoped delegation, and batch operations. This is an alternative or complement to the Safe multisig pattern in monskills' [`wallet/`](../../wallet/SKILL.md).

Account Kit also supports building end-user smart wallets in a frontend (with signers like RainbowKit, Privy, Turnkey, Magic, etc.), but that is a different integration shape and is not the focus of this reference. For that path, see the official docs at https://www.alchemy.com/docs/wallets.

Reach for Account Kit when you want:

- Sponsored gas: the policy (your app, or the agent) pays so the operator does not need to hold MON
- Session keys: scoped, time-bound delegation to an agent or signer
- Batch operations: multiple calls in one signed transaction
- Gasless onboarding: deploy the smart account on first action; the paymaster can cover the deployment gas

Safe multisig still makes sense for high-value treasury operations. Smart accounts make sense for agent-controlled execution. They coexist.

## Stack

```
┌─────────────────────────────────────────────────┐
│ Your app │
│ └─ @alchemy/account-kit / @alchemy/aa-* │ SDK (signs UserOperations)
└──────────────┬──────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────┐
│ Alchemy Bundler (Monad) │ Submits UserOperations → EntryPoint
│ https://monad-mainnet.g.alchemy.com/v2/<KEY> │
└──────────────┬──────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────┐
│ ERC-4337 EntryPoint (Monad mainnet) │ Canonical contract
│ v0.7: 0x0000000071727De22E5E9d8BAf0edAc6f37da032│ (see monskills' addresses/)
│ v0.6: 0x5FF137D4b0FDCD49DcA30c7CF57E578a026d2789│
└─────────────────────────────────────────────────┘
```

Alchemy provides the Bundler endpoint. The EntryPoint contracts are deployed canonically on Monad — see [`addresses/`](../../addresses/SKILL.md) for verified addresses.

## Modular Account v2 (recommended)

Alchemy's default smart-account implementation is **Modular Account v2** — an ERC-6900-compatible modular account with:

- Native session keys
- Batch / multicall execution
- Permission modules (allow-lists, value caps, time bounds)
- Migration path from prior account templates

Address derivation: `keccak256(factory, signer, salt)` — deterministic, so you can compute the smart-account address before deploying it.

## End-to-end flow

### 1. Install the SDK

```bash
npm install @alchemy/aa-core @alchemy/aa-alchemy
# or your preferred AA SDK package — see https://www.alchemy.com/docs/wallets
```

### 2. Configure the Monad transport

```typescript
import { createAlchemySmartAccountClient } from "@alchemy/aa-alchemy";
import { LocalAccountSigner } from "@alchemy/aa-core";
import { monad } from "viem/chains"; // or define manually

const client = createAlchemySmartAccountClient({
chain: monad,
rpcUrl: "https://monad-mainnet.g.alchemy.com/v2/<ALCHEMY_API_KEY>",
signer: LocalAccountSigner.privateKeyToAccountSigner("0x..."),
gasManagerConfig: { policyId: "<POLICY_ID>" }, // optional, for sponsored gas
});
```

The `rpcUrl` doubles as the bundler endpoint on Alchemy — the same URL serves JSON-RPC and Bundler routes.

### 3. Send a sponsored UserOperation

```typescript
const uoHash = await client.sendUserOperation({
uo: { target: "0x<contract>", data: "0x<calldata>", value: 0n },
});
const txHash = await client.waitForUserOperationTransaction({ hash: uoHash });
```

If `gasManagerConfig.policyId` is set and the policy permits the call, the paymaster sponsors it. The signer doesn't need MON.

### 4. Verify on-chain

```bash
cast tx <txHash> --rpc-url https://monad-mainnet.g.alchemy.com/v2/$ALCHEMY_API_KEY
```

Or `eth_getTransactionReceipt` via raw RPC.

## Migrating from monskills' `wallet/` (Safe multisig)

The Safe multisig pattern in [`wallet/`](../../wallet/SKILL.md) and the smart-account pattern here are complementary, not exclusive:

| Use case | Use |
| --- | --- |
| Treasury / high-value approvals requiring multiple humans | Safe multisig (`wallet/`) |
| Agent-controlled execution with sponsored gas, session keys, batch ops | Smart account (this skill) |
| Mixed (humans approve large moves, agent executes routine ops) | Both — Safe owns funds; agent operates a session-keyed smart account funded by the Safe |

If migrating an existing agent from Safe → Smart Account: the smart-account address is deterministic, so you can fund it before deployment. First UserOperation will deploy the account (paymaster can sponsor deployment too).

## EIP-7702 alternative (single-address smart wallet)

Monad supports EIP-7702 natively. EIP-7702 lets an **existing EOA** delegate to a smart-contract implementation — you keep the EOA address but gain smart-wallet features for the lifetime of the delegation. Trade-offs vs ERC-4337 smart accounts:

| | EIP-7702 (delegated EOA) | ERC-4337 (smart account) |
| --- | --- | --- |
| Address | Same as the EOA | New deterministic address |
| Replay safety | Per-chain nonce on the EOA | Per-account nonce on EntryPoint |
| Batch ops | Yes (via delegated impl) | Yes (native) |
| Gas sponsorship | Possible via BSO (see [`gas-manager.md`](./gas-manager.md)) | Native (Gas Manager) |
| Reserve balance | 10 MON floor still applies | 10 MON floor still applies |
| `CREATE`/`CREATE2` in delegated context | **Not available** — use canonical factories | Available |

If the user already has assets on an EOA and wants smart-wallet features without moving funds, EIP-7702 is the lighter path. See monskills' [`concepts/`](../../concepts/SKILL.md) → `eip-7702.md` for details.

## Where to go deeper

- Full Account Kit docs: https://www.alchemy.com/docs/wallets
- For Monad-specific gas cost implications when sponsoring, see [`./gas-manager.md`](./gas-manager.md)
Loading