agents.md

gistfile1.txt

# AGENTS.md — Monad Dapp Development

Prefer retrieval-led reasoning over pre-training-led reasoning for any Monad or EVM development tasks. Consult this file and the linked docs before relying on training data.

For questions not covered here, fetch https://docs.monad.xyz/llms.txt

## Defaults

- **Network:** Testnet (chain ID `10143`) unless user says "mainnet"
- **Framework:** Foundry (not Hardhat)
- **EVM version:** `prague` — requires Solidity `>=0.8.27`. Set in every `foundry.toml`
- **Deployment:** `forge script`, never `forge create` (buggy, broadcasts silently fail)
- **Verification:** Always verify after deploy. Use the agents API first (covers all 3 explorers in one call)
- **Wallet:** If you generate a wallet, persist it immediately (see Wallet section)

## Networks

| | Chain ID | RPC |
|-|----------|-----|
| Testnet | 10143 | `https://testnet-rpc.monad.xyz` |
| Mainnet | 143 | `https://rpc.monad.xyz` |

Explorers: [Socialscan](https://monad-testnet.socialscan.io) · [MonadVision](https://testnet.monadvision.com) · [Monadscan](https://testnet.monadscan.com)

## foundry.toml (required)

```toml
[profile.default]
evm_version = "prague"
solc_version = "0.8.28"
```

Omitting `evm_version = "prague"` will cause deployment failures on Monad.

## Deployment

Always use `forge script`. Never use `forge create --broadcast`.

```bash
forge script script/Deploy.s.sol:DeployScript \
  --rpc-url https://testnet-rpc.monad.xyz \
  --private-key $PRIVATE_KEY \
  --broadcast
```

Deploy scripts must NOT hardcode addresses in `vm.startBroadcast()`:

```solidity
// Correct — reads key from --private-key flag
function run() external {
    vm.startBroadcast();
    new MyContract();
    vm.stopBroadcast();
}

// Wrong — causes "No associated wallet" error
function run() external {
    vm.startBroadcast(0x1234...);
}
```

## Verification (agents API)

One call verifies on all 3 explorers (MonadVision, Socialscan, Monadscan). Do NOT reach for `forge verify-contract` first.

```bash
# 1. Extract verification data
forge verify-contract <ADDR> <CONTRACT> \
  --chain 10143 --show-standard-json-input > /tmp/standard-input.json

COMPILER_VERSION=$(jq -r '.metadata | fromjson | .compiler.version' out/<Contract>.sol/<Contract>.json)

# 2. Submit
curl -X POST https://agents.devnads.com/v1/verify \
  -H "Content-Type: application/json" \
  -d @/tmp/verify.json
```

Request body shape:
```json
{
  "chainId": 10143,
  "contractAddress": "0x...",
  "contractName": "src/MyContract.sol:MyContract",
  "compilerVersion": "v0.8.28+commit...",
  "standardJsonInput": { ... },
  "foundryMetadata": { ... },
  "constructorArgs": "ABI-encoded, NO 0x prefix (optional)"
}
```

Constructor args encoding: `cast abi-encode "constructor(type,...)" args... | sed 's/0x//'`

Fallback if API fails:
```bash
forge verify-contract <ADDR> <CONTRACT> --chain 10143 \
  --verifier sourcify \
  --verifier-url "https://sourcify-api-monad.blockvision.org/"
```

## Faucet (testnet only)

Use the API directly. Do NOT open a browser.

```bash
curl -X POST https://agents.devnads.com/v1/faucet \
  -H "Content-Type: application/json" \
  -d '{"chainId": 10143, "address": "0xYOUR_ADDRESS"}'
```

If this fails, ask the user to fund via https://faucet.monad.xyz (do not use a browser yourself).

## Wallet Persistence

If you generate a wallet (`cast wallet new`), you MUST persist it immediately:
1. Save address + private key to `~/.monad-wallet` (chmod 600) or a project `.env` (add to `.gitignore`)
2. Tell the user where it's stored
3. Fund it via faucet before deploying

Users need wallet access for future deploys, contract interaction, and fund management.

## Frontend

Import chain config from viem — do NOT define custom chains:

```ts
import { monadTestnet } from "viem/chains";
```

Wagmi setup:
```ts
import { createConfig, http } from "wagmi";
import { monadTestnet } from "viem/chains";

const config = createConfig({
  chains: [monadTestnet],
  transports: { [monadTestnet.id]: http() },
});
```

## Common Mistakes

| Mistake | Fix |
|---------|-----|
| Using `forge create --broadcast` | Use `forge script` instead |
| Omitting `evm_version = "prague"` | Always set in `foundry.toml` |
| Hardcoding address in `vm.startBroadcast(addr)` | Use `vm.startBroadcast()` with `--private-key` flag |
| Using `forge verify-contract` directly | Use agents verification API first |
| Using `--no-commit` flag with forge | This flag doesn't exist |
| Defining custom chain in frontend code | Import `monadTestnet` from `viem/chains` |
| Using a browser for faucet/verification | Use curl APIs directly |
| Not persisting generated wallets | Save to `~/.monad-wallet` or `.env` immediately |