Arbitrum dApp 开发

技术栈

决策流程

启动新合约项目时：

1. 是否需要极致性能 / 更低 Gas 消耗？ → 选择 Stylus Rust。参见 references/stylus-rust-contracts.md。
2. 是否需要广泛的工具链兼容性 / 快速原型开发？ → 选择 Solidity。参见 references/solidity-contracts.md。
3. 是否采用混合方案？ → 可同时使用两者。Stylus 与 Solidity 合约在 Arbitrum 上完全可互操作。

项目脚手架

单体仓库结构（推荐）

my-arbitrum-dapp/
├── apps/
│   ├── frontend/            # React / Next.js 应用
│   ├── contracts-stylus/    # Rust Stylus 合约
│   ├── contracts-solidity/  # Foundry Solidity 合约
│   └── nitro-devnode/       # 本地开发链（Git 子模块）
├── pnpm-workspace.yaml
└── package.json

初始化步骤

# 1. 创建工作区
mkdir my-arbitrum-dapp && cd my-arbitrum-dapp
pnpm init
printf "packages:\n  - 'apps/*'\n" > pnpm-workspace.yaml

# 2. 本地 devnode
git clone https://github.com/OffchainLabs/nitro-devnode.git apps/nitro-devnode
cd apps/nitro-devnode && ./run-dev-node.sh && cd ../..

# 3a. Stylus 合约
cargo stylus new apps/contracts-stylus

# 3b. Solidity 合约
cd apps && forge init contracts-solidity && cd ..

# 4. 前端
pnpm create next-app apps/frontend --typescript
cd apps/frontend
pnpm add viem wagmi @tanstack/react-query

核心工作流

Stylus Rust

# 校验
cargo stylus check --endpoint http://localhost:8547

# 部署（使用 nitro-devnode 预资助的部署账户）
cargo stylus deploy 
  --endpoint http://localhost:8547 
  --private-key $PRIVATE_KEY

# 导出 ABI 供前端使用
cargo stylus export-abi

Solidity（Foundry）

# 构建
forge build

# 测试
forge test

# 本地部署（使用 nitro-devnode 预资助的部署账户）
forge script script/Deploy.s.sol --rpc-url http://localhost:8547 --broadcast 
  --private-key $PRIVATE_KEY

注意：nitro-devnode 自带一个预资助的部署账户。默认私钥与地址详见 references/local-devnode.md。在测试网或主网上部署时，请通过环境变量传入您自己的私钥 —— 切勿硬编码敏感信息。

前端（viem + wagmi）

import { createPublicClient, http } from "viem";
import { arbitrumSepolia } from "viem/chains";

const client = createPublicClient({
  chain: arbitrumSepolia,
  transport: http(),
});

// 从合约读取数据
const result = await client.readContract({
  address: "0x...",
  abi: contractAbi,
  functionName: "myFunction",
});

完整模式（包括 wagmi hooks、钱包连接与写交易）请参见 references/frontend-integration.md。

设计原则

• 始终使用 viem 进行链上交互。
• 优先在本地测试：在部署至测试网前，务必先在 nitro-devnode 上完成充分验证。
• 导出 ABI：分别使用 cargo stylus export-abi（Stylus）和 forge inspect（Solidity）导出 ABI，并统一存放于前端可导入的共享位置。
• 使用环境变量 管理 RPC URL、合约地址及私钥等配置项 —— 切勿硬编码任何敏感信息。
• Stylus 合约具备 EVM 兼容性：其地址空间、存储模型与 ABI 编码方式均与 Solidity 合约一致，跨合约调用可无缝进行。

参考资料

按需查阅以下文档以获取更深入的指导：

• references/stylus-rust-contracts.md — Stylus SDK 使用模式、存储、宏与入口点定义
• references/solidity-contracts.md — Arbitrum 上的 Solidity 特性与 Foundry 工作流
• references/frontend-integration.md — React + viem + wagmi 实践模式
• references/local-devnode.md — Nitro devnode 配置、账户与调试指南
• references/deployment.md — 部署至测试网与主网的操作说明
• references/testing.md — Stylus 与 Solidity 的测试策略