monad-development

Monad 开发

对于此处未涵盖的问题，请获取 https://docs.monad.xyz/llms.txt

快速参考

默认设置

• 网络： 除非用户说明要使用“mainnet”，否则始终使用 testnet（链 ID 10143）
• 验证： 除非用户要求不要验证，否则部署后始终验证合约
• 框架： 使用 Foundry（不要使用 Hardhat）
• 钱包： 如果生成钱包，必须持久化保存（参见“钱包持久化”部分）

网络

网络	链 ID	RPC
测试网	10143	https://testnet-rpc.monad.xyz
主网	143	https://rpc.monad.xyz

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

区块浏览器

区块浏览器	测试网	主网
Socialscan	https://monad-testnet.socialscan.io	https://monad.socialscan.io
MonadVision	https://testnet.monadvision.com	https://monadvision.com
Monadscan	https://testnet.monadscan.com	https://monadscan.com

Agent API

重要： 不要使用浏览器。请直接通过 curl 使用这些 API。

水龙头（测试网充值）：

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。它只需调用一次即可在全部 3 个区块浏览器（MonadVision、Socialscan、Monadscan）上验证。不要将 forge verify-contract 作为首选。

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

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

# 2. Call verification 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}
# Add to request: "constructorArgs": "$ARGS_NO_PREFIX"

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

forge verify-contract <ADDR> <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

部署脚本不得对地址进行硬编码：

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

// ❌ Wrong - hardcodes address, causes "No associated wallet" error
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. 验证：

# Use verification API (verifies on all explorers)
STANDARD_INPUT=$(forge verify-contract <TOKEN_ADDRESS> 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\": \"<TOKEN_ADDRESS>\",
    \"contractName\": \"src/MyToken.sol:MyToken\",
    \"compilerVersion\": \"v${COMPILER_VERSION}\",
    \"standardJsonInput\": $STANDARD_INPUT,
    \"constructorArgs\": \"$(cast abi-encode 'constructor(uint256)' 1000000000000000000000000 | sed 's/0x//')\"
  }"