Monad 开发

如本页未涵盖您的问题，请访问 https://docs.monad.xyz/llms.txt 获取文档

快速参考

默认配置

• 网络：除非用户明确要求“mainnet”，否则始终使用 testnet（链 ID 10143）
• 合约验证：部署后必须始终执行合约验证，除非用户明确指示跳过
• 开发框架：使用 Foundry（不使用 Hardhat）
• 钱包：若为您生成钱包，则 必须持久化保存（详见“钱包持久化”章节）

网络信息

官方文档：https://docs.monad.xyz

区块浏览器

Agent API

重要提示：请勿使用浏览器。请直接通过 curl 调用以下 API。

水龙头服务（Testnet 资金发放）：

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

返回示例：{"txHash": "0x...", "amount": "1000000000000000000", "chain": "Monad Testnet"}

备用方案（官方水龙头）： https://faucet.monad.xyz 若 Agent 水龙头调用失败，请提示用户通过官方水龙头自行获取资金（您不可代为操作浏览器）。

合约验证（所有浏览器）：

请 始终优先使用验证 API。该接口单次调用即可在全部三个浏览器（MonadVision、Socialscan、Monadscan）上完成验证。请勿将 forge verify-contract 作为首选方案。

# 1. 获取验证所需数据
forge verify-contract   
  --chain 10143 
  --show-standard-json-input > /tmp/standard-input.json

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

# 2. 调用验证 API
STANDARD_INPUT=$(cat /tmp/standard-input.json)
FOUNDRY_METADATA=$(cat /tmp/metadata.json)

cat > /tmp/verify.json << EOF
{
  "chainId": 10143,
  "contractAddress": "0xYOUR_CONTRACT_ADDRESS",
  "contractName": "src/MyContract.sol:MyContract",
  "compilerVersion": "v${COMPILER_VERSION}",
  "standardJsonInput": $STANDARD_INPUT,
  "foundryMetadata": $FOUNDRY_METADATA
}
EOF

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

含构造函数参数的验证：需添加 constructorArgs 字段（ABI 编码格式，且 不带 0x 前缀）：

ARGS=$(cast abi-encode "constructor(string,string,uint256)" "MyToken" "MTK" 1000000000000000000000000)
ARGS_NO_PREFIX=${ARGS#0x}
# 在请求体中添加："constructorArgs": "$ARGS_NO_PREFIX"

手动验证备用方案（API 失败时使用）：

forge verify-contract   --chain 10143 
  --verifier sourcify 
  --verifier-url "https://sourcify-api-monad.blockvision.org/"

钱包持久化

对 Agent 至关重要：若您为用户生成钱包，则 必须将其持久化保存以便后续复用。

生成新钱包时，请按以下步骤操作：

1. 创建钱包：cast wallet new
2. 立即保存钱包地址与私钥至安全位置
3. 明确告知用户钱包凭证的存储位置
4. 在部署前，先通过水龙头为钱包充值

推荐存储方式：

• 写入 ~/.monad-wallet 文件，并设置权限为 chmod 600
• 存入项目专属的 .env 文件中（并确保该文件已加入 .gitignore）
• 将凭证返回给用户，并提醒其妥善保管

为何如此重要：用户需持有钱包以执行以下操作：

• 部署更多合约
• 与已部署合约进行交互
• 管理账户资产
• 验证合约所有权

部署流程

请统一使用 forge script 执行部署：

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

部署脚本模板：

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.27;
import "forge-std/Script.sol";
import "../src/MyContract.sol";

contract DeployScript is Script {
    function run() external {
        vm.startBroadcast();
        MyContract contract = new MyContract();
        console.log("Contract deployed at:", address(contract));
        vm.stopBroadcast();
    }
}

技术细节

EVM 版本（关键配置）

必须始终设置 evmVersion: "prague"。此配置要求 Solidity 版本 ≥ 0.8.27。

Foundry 配置（foundry.toml）：

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

Foundry 使用提示

不存在的命令行标志（请勿使用）：

• --no-commit —— 此标志在 forge init 或 forge install 中无效

部署方式：请使用 forge script，而非 forge create：

forge create --broadcast 存在稳定性问题，常被忽略。请始终选用 forge script。

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

部署脚本禁止硬编码地址：

// ✅ 正确 —— 从 --private-key 参数读取私钥
function run() external {
    vm.startBroadcast();
    new MyContract();
    vm.stopBroadcast();
}

// ❌ 错误 —— 硬编码地址，将导致 “No associated wallet” 错误
function run() external {
    vm.startBroadcast(0x1234...);
}

前端集成

请从 viem/chains 导入链配置，切勿自定义链定义：

import { monadTestnet } from "viem/chains";

结合 wagmi 使用示例：

import { createConfig, http } from 'wagmi'
import { monadTestnet } from 'viem/chains'

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

示例：部署 ERC20 合约

1. 创建项目：

forge init my-token
cd my-token

2. 配置 foundry.toml：

[profile.default]
src = "src"
out = "out"
libs = ["lib"]
evm_version = "prague"
solc_version = "0.8.28"

3. 创建合约 src/MyToken.sol：

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.27;

import "@openzeppelin/contracts/token/ERC20/ERC20.sol";

contract MyToken is ERC20 {
    constructor(uint256 initialSupply) ERC20("MyToken", "MTK") {
        _mint(msg.sender, initialSupply);
    }
}

4. 安装依赖：

forge install OpenZeppelin/openzeppelin-contracts --no-commit

5. 创建部署脚本 script/Deploy.s.sol：

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.27;
import "forge-std/Script.sol";
import "../src/MyToken.sol";

contract DeployScript is Script {
    function run() external {
        vm.startBroadcast();
        MyToken token = new MyToken(1000000 * 10**18);
        console.log("Token deployed at:", address(token));
        vm.stopBroadcast();
    }
}

6. 执行部署：

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

7. 执行验证：

# 使用验证 API（自动覆盖全部三个浏览器）
STANDARD_INPUT=$(forge verify-contract  src/MyToken.sol:MyToken --chain 10143 --show-standard-json-input)
COMPILER_VERSION=$(jq -r '.metadata | fromjson | .compiler.version' out/MyToken.sol/MyToken.json)

curl -X POST https://agents.devnads.com/v1/verify 
  -H "Content-Type: application/json" 
  -d "{
    "chainId": 10143,
    "contractAddress": "",
    "contractName": "src/MyToken.sol:MyToken",
    "compilerVersion": "v${COMPILER_VERSION}",
    "standardJsonInput": $STANDARD_INPUT,
    "constructorArgs": "$(cast abi-encode 'constructor(uint256)' 1000000000000000000000000 | sed 's/0x//')"
  }"