本页由机器翻译。英文原文为权威版本。 阅读英文版 →
跳转到主要内容

入门指引

本文档面向做市商，介绍链上账户生命周期、资金流程以及API钱包管理。

概述​

Hypercall 采用管理者/代理模型：

  • 管理者（Manager）：拥有账户的EOA（通常是您的主钱包）
  • 账户（Account）：一个最小代理合约（clone），用于持有资金并执行链上操作
  • API钱包（API Wallet）：由管理者授权、用于签署交易请求的EOA（代理）

所有链上交互均通过 Exchange 合约进行。

合约地址​

测试网​

  • Exchange: ``

主网​

  • 详情将私下提供。

账户生命周期​

1. 检查现有账户​

在创建新账户之前，请先检查您是否已拥有账户：

function getAccounts(address manager) external view returns (ManagedAccount[] memory);

示例（ethers.js）：

const exchange = new ethers.Contract(EXCHANGE_ADDRESS, EXCHANGE_ABI, provider);
const accounts = await exchange.getAccounts(managerAddress);
// Returns: [{ account: "0x...", manager: "0x...", apiWallets: ["0x..."] }]

2. 创建账户​

创建一个以 msg.sender 作为管理者的新账户：

function createAccount() external payable returns (address account);

要求：

  • accountImpl 必须已由治理机制设置
  • msg.value >= getCreationDeposit()（以HYPE计的最低充值金额）
    • 如果 creationDepositUsd == 0，则无需最低充值
    • 否则，getCreationDeposit() 将根据当前现货价格把美元金额换算为HYPE

行为：

  • 部署一个 accountImpl 的确定性最小代理（clone）
  • 将 msg.sender 设为账户管理者
  • 如果 msg.value > 0，将代表该账户执行一笔HYPE充值
    • 将HYPE转账至 HYPE_SYSTEM_ADDRESS（HyperCore桥）
    • 如果充值金额大于等于价值1美元的HYPE，账户将在HyperCore上激活（扣除激活费）

示例（ethers.js）：

// Get minimum deposit (in HYPE wei)
const minDeposit = await exchange.getCreationDeposit();
// Or set to ~$1-2 worth of HYPE for activation
const depositAmount = ethers.parseEther("0.001"); // Adjust based on HYPE price

const tx = await exchange.createAccount({ value: depositAmount });
const receipt = await tx.wait();
// Account address is deterministic - can predict before creation

预测账户地址：

function predictNextAccount(address manager) external view returns (address);

使用此方法可在账户创建前预先获知账户地址（对UI/UX很有用）。

3. 账户转移​

管理者可以转移账户所有权（不可直接调用；仅在创建期间或通过治理机制发生）：

event AccountTransferred(address indexed account, address indexed oldManager, address indexed newManager);

账户转移功能可按需求提供。

API钱包管理​

API钱包是由管理者授权、用于签署交易请求的EOA。它们签署EIP-712消息，并在链上进行验证。

添加API钱包​

function addApiWallet(address account, address apiWallet) external;

要求：

  • msg.sender == managers[account]（必须是账户管理者）
  • apiWallet 不得已被任何其他账户/管理者激活使用
  • account != address(0) 且 apiWallet != address(0)

行为：

  • 建立 apiWallet -> account 和 apiWallet -> manager 的映射
  • 将 apiWallet 添加到账户的API钱包集合中
  • 触发 ApiWalletAdded(account, manager, apiWallet) 事件

示例：

const tx = await exchange.addApiWallet(accountAddress, apiWalletAddress);
await tx.wait();

移除API钱包​

function removeApiWallet(address account, address apiWallet) external;

要求：

  • msg.sender == managers[account]
  • apiWallet 必须已在此账户/管理者下处于激活状态

行为：

  • 移除 apiWallet 的相关映射
  • 将 apiWallet 从账户的API钱包集合中移除
  • 触发 ApiWalletRemoved(account, manager, apiWallet) 事件

查询API钱包​

function getAccountByApiWallet(address apiWallet) external view returns (ManagedAccount memory);

如果 apiWallet 处于激活状态，返回该账户、管理者以及账户的所有API钱包。如果未激活，则返回零值结构体。

示例：

const managedAccount = await exchange.getAccountByApiWallet(apiWalletAddress);
if (managedAccount.account !== ethers.ZeroAddress) {
  console.log("Account:", managedAccount.account);
  console.log("Manager:", managedAccount.manager);
  console.log("API Wallets:", managedAccount.apiWallets);
}

资金与充值​

向Hypercall充值USDC​

function depositUsdcFor(address account, uint256 amount) external;

depositUsdcFor 是为Hypercall现金余额提供资金的HyperEVM直接充值路径。它将原生HyperEVM USDC从 msg.sender 转入 Exchange，然后 Exchange 通过Circle的 CoreDepositWallet 将该USDC存入其HyperCore余额。

可调用者：

  • 任何钱包、路由合约、求解器（solver）或zap合约均可调用此方法。
  • 由 msg.sender 支付USDC。
  • account 是要入账的Hypercall账户或钱包。请勿根据 msg.sender 推断入账账户。

要求：

  • account != address(0)
  • amount > 0
  • msg.sender 必须授权 Exchange 支配 amount 数量的原生HyperEVM USDC
  • 已部署的 Exchange 实现必须使用目标网络的原生HyperEVM USDC代币地址和 CoreDepositWallet 地址进行构造

事件与入账：

event UsdcDeposit(
    address indexed account,
    address indexed from,
    address indexed token,
    uint256 amount,
    uint32 dstDex
);

该事件由 Exchange 在调用 CoreDepositWallet.depositFor 后触发。后端必须将此事件与观测到的进入Exchange余额的HyperCore充值进行匹配，然后才能为Hypercall现金入账。入账的Hypercall账户为事件中显式的 account 字段。

示例：

const usdc = new ethers.Contract(USDC_ADDRESS, ERC20_ABI, signer);
const exchange = new ethers.Contract(EXCHANGE_ADDRESS, EXCHANGE_ABI, signer);

await usdc.approve(EXCHANGE_ADDRESS, amount);
await exchange.depositUsdcFor(accountAddress, amount);

期权代币充值函数​

function depositOption(address account, address token, uint256 amount) external;

支持的代币类型：

  1. 期权ERC20代币（已在 OptionRegistry 中注册）：
    • msg.value == 0（必须）
    • 通过 IOptionToken(token).burnFrom(msg.sender, amount) 销毁期权代币
    • 触发 Deposit(account, msg.sender, token, amount) 事件
    • RSM索引器捕获该事件，并为账户的期权持仓入账

要求：

  • account 必须是已注册的Hypercall账户
  • optionRegistry != address(0)（必须已设置）
  • msg.sender 必须已授权 Exchange 支配 amount 数量的代币

示例（期权代币充值）：

const option = new ethers.Contract(OPTION_TOKEN_ADDRESS, ERC20_ABI, signer);
const exchange = new ethers.Contract(EXCHANGE_ADDRESS, EXCHANGE_ABI, signer);

await option.approve(EXCHANGE_ADDRESS, amount);
await exchange.depositOption(accountAddress, OPTION_TOKEN_ADDRESS, amount);

从账户转出​

管理者可以将代币从其账户转给HyperEVM上的任意接收方：

function transferFromAccount(address account, address token, address recipient, uint256 amount) external;

要求：

  • msg.sender == managers[account]
  • recipient != address(0)

使用场景：

  • 完成由账户发起的 HyperCore -> HyperEVM 转账
  • 从账户中救援资金
  • 提现至不同的地址

示例：

await exchange.transferFromAccount(
  accountAddress,
  tokenAddress,
  recipientAddress,
  amount
);

与链下API的集成​

账户创建并添加API钱包后：

  1. 链下API认证：使用API钱包的私钥签署EIP-712消息（参见认证）
  2. 链上验证：RSM排序器（Sequencer）使用您签署的请求调用 Exchange.hlRequestOrder（或类似方法）
  3. 执行：Exchange验证签名、恢复API钱包地址、将其映射到您的账户，并执行链上操作

另请参阅：

事件​

event AccountTransferred(address indexed account, address indexed oldManager, address indexed newManager);
event ApiWalletAdded(address indexed account, address indexed manager, address indexed apiWallet);
event ApiWalletRemoved(address indexed account, address indexed manager, address indexed apiWallet);
event Deposit(address indexed account, address indexed from, address indexed token, uint256 amount);
event Withdraw(address indexed account, address indexed to, address indexed token, uint256 amount);

错误​

所有错误均定义在 IExchangeBase.sol 中：

  • Exchange__AccountManagerNotSet(address account)：账户不存在
  • Exchange__ApiWalletAlreadyActive(address apiWallet)：API钱包已被使用
  • Exchange__ApiWalletNotActive(address apiWallet)：未找到API钱包
  • Exchange__CreationDepositNotMet(uint256 expected)：msg.value 不足
  • Exchange__TokenNotSupported(address token)：该代币不支持充值
  • Exchange__MsgValueIncorrect(uint256 expected)：msg.value 不匹配
  • Exchange__NotManager(address account, address notManager)：调用者不是管理者

安全注意事项​

  1. 管理者密钥安全：管理者密钥控制账户所有权和API钱包管理。请安全存储（建议使用硬件钱包）。

  2. API钱包密钥安全：API钱包密钥用于签署交易请求。请为每个账户/环境使用独立密钥，并定期轮换。

  3. Nonce管理：每个签名者（API钱包、管理者、RSM）拥有独立的nonce空间。请在链下跟踪nonce以避免重放攻击。

  4. 账户激活：账户必须在HyperCore上激活（充值价值大于等于1美元的HYPE）后才能交易永续合约。可通过HyperCore API检查激活状态。

  5. 确定性地址：账户地址由管理者地址和创建次数确定性生成。使用 predictNextAccount 可在创建前获知地址。

最后更新 于