将以太坊 dApp 迁移到 OXN

大部分以太坊 dApp 迁到 OXN 只要少量改动：两行编译器配置、一个 Hardhat 插件、脚本里显式的 gas limit。本页覆盖清单和差异点。

概览

迁移本质上是：

1. 用 evmVersion: "paris" 编译。
2. 安装 OXN SDK。
3. 包裹 provider 与 signer 做加密交易。
4. 显式设置 gas limit。
5. 重新部署。

Solidity 源码不需要任何改动。标准 ERC-20、ERC-721、ERC-1155、DEX、借贷模式全部有效。

1. 编译器设置

更新 hardhat.config.js：

module.exports = {
  solidity: {
    version: "0.8.24",
    settings: {
      evmVersion: "paris",   // OXN 必需
      optimizer: { enabled: true, runs: 200 },
    },
  },
  networks: {
    oxn_testnet: {
      url: "https://rpc.bout.network",
      chainId: 186,
      accounts: [process.env.PRIVATE_KEY],
    },
  },
};

Foundry，foundry.toml：

[profile.default]
evm_version = "paris"

2. 安装 SDK

npm install --save-dev @oasisprotocol/sapphire-hardhat
npm install ethers@^6.16.0 @oasisprotocol/sapphire-ethers-v6

加到 hardhat.config.js：

require("@nomicfoundation/hardhat-toolbox");
require("@oasisprotocol/sapphire-hardhat");   // 必须在 toolbox 之后

3. Wrap provider 与 signer

部署与交互脚本里包裹以启用加密：

import { ethers } from "ethers";
import { wrapEthersProvider, wrapEthersSigner } from "@oasisprotocol/sapphire-ethers-v6";

const raw = new ethers.JsonRpcProvider("https://rpc.bout.network");
const provider = wrapEthersProvider(raw);
const signer = wrapEthersSigner(new ethers.Wallet(PRIVATE_KEY, raw));

用 hre.ethers 的 Hardhat 脚本里，Hardhat 插件自动处理——无需改代码。

4. 显式设置 gas limit

每笔交易需要显式 gasLimit：

// 之前（以太坊）：estimateGas 隐式处理
await token.transfer(recipient, amount);

// 之后（OXN）：显式 gasLimit
await token.transfer(recipient, amount, { gasLimit: 500_000n });

常用值见 Gas 与手续费。

5. 重新部署

以太坊上的合约地址不会带到 OXN。重新部署：

npx hardhat run scripts/deploy.js --network oxn_testnet

在 deployments/ 文件夹里持久化地址——见部署合约。

机密性——用户看到什么变化

直接迁移（不加机密性特性）时，你的用户获得：

• 加密 calldata——他们交易的参数不再公开。
• 加密事件——他们交易产生的日志只有他们能看到。
• UX 其他部分一致——MetaMask 流程、gas 成本、交易时间与以太坊几乎相同。

要用上机密性，加只有机密环境下才合理的特性：

• 在 ERC-20 中隐藏余额（见构建机密 ERC-20）。
• 加密封拍卖机制。
• 游戏中用 Sapphire.randomBytes 做公平随机。

测试

本地 Hardhat 测试继续对逻辑有效。加对 OXN 测试网的集成测试覆盖加密路径——见测试机密行为。

会失败的地方（少见但要检查）

• 用 PUSH0 的合约——用 evmVersion: "paris" 修。
• 用 TLOAD / TSTORE 的合约——Cancun 时代的瞬态存储不支持。改回普通存储。
• 用 BLOBHASH 的合约——不支持；OXN 没 blob。
• 依赖 PREVRANDAO 做随机的合约——换 Sapphire.randomBytes。
• 用 estimateGas 的脚本——换显式 gasLimit。

迁移清单

• 编译器配置中 evmVersion: "paris"
• @oasisprotocol/sapphire-hardhat 已装且顺序正确
• 部署脚本有显式 gasLimit
• 交互脚本包裹 provider / signer
• 集成测试打真实 OXN，不是 Hardhat network
• 合约已重新部署
• 地址持久化到 deployments/
• 前端 chain ID 更新到 186（或参数化）
• 前端 RPC URL 更新到 https://rpc.bout.network
• 钱包集成用 MetaMask + OXN 测试网测过

下一步

• 部署合约——生产部署模式
• 机密性模型——用户自动获得什么
• 构建机密 ERC-20——代币 dApp 的自然下一步