Онбординг

Этот документ описывает жизненный цикл ончейн-аккаунта, потоки фондирования и управление API-кошельками для маркетмейкеров.

Обзор

Hypercall использует модель менеджер/агент:

• Менеджер: EOA, владеющий аккаунтом (как правило, ваш основной кошелёк)
• Аккаунт: минимальный прокси-контракт (клон), который хранит средства и выполняет ончейн-операции
• API-кошелёк: 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 должен быть задан через governance
• msg.value >= getCreationDeposit() (минимальный депозит в HYPE)
  • Если creationDepositUsd == 0, минимальный депозит не требуется
  • В противном случае getCreationDeposit() конвертирует сумму в USD в HYPE по текущей спотовой цене

Поведение:

• Разворачивает детерминированный минимальный прокси (клон) accountImpl
• Устанавливает msg.sender менеджером аккаунта
• Если msg.value > 0, выполняет депозит HYPE от имени аккаунта
  • Переводит HYPE на HYPE_SYSTEM_ADDRESS (мост HyperCore)
  • Если депозит >= HYPE на сумму $1, аккаунт активируется на 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. Передача аккаунта

Менеджеры могут передавать право владения аккаунтом (напрямую не вызывается; происходит при создании или через governance):

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);

Возвращает аккаунт, менеджера и все API-кошельки аккаунта, если apiWallet активен. Возвращает нулевую структуру, если неактивен.

Пример:

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);
}

Фондирование и депозиты

Депозит USDC в Hypercall

function depositUsdcFor(address account, uint256 amount) external;

depositUsdcFor — это прямой путь фондирования кэш-балансов Hypercall через HyperEVM. Метод переводит нативный HyperEVM USDC от msg.sender в Exchange, после чего Exchange вносит этот USDC на свой баланс HyperCore через CoreDepositWallet от Circle.

Кто может вызывать:

• Любой кошелёк, роутер, солвер или zap-контракт может вызвать этот метод.
• USDC оплачивает msg.sender.
• account — аккаунт или кошелёк Hypercall, на который зачисляются средства. Не определяйте зачисляемый аккаунт по msg.sender.

Требования:

• account != address(0)
• amount > 0
• msg.sender должен выдать Exchange разрешение (approve) на 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. Бэкенд должен сопоставить это событие с наблюдаемым депозитом HyperCore на баланс Exchange, прежде чем зачислить кэш в 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 разрешение (approve) на 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 вызывает Exchange.hlRequestOrder (или аналогичный метод) с вашим подписанным запросом
3. Исполнение: Exchange верифицирует подпись, восстанавливает API-кошелёк, сопоставляет его с вашим аккаунтом и выполняет ончейн-операции

См. также:

• Аутентификация — аутентификация в офчейн-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 офчейн, чтобы избежать replay-атак.

4. Активация аккаунта: аккаунты должны быть активированы на HyperCore (депозит >= $1 в HYPE), прежде чем они смогут торговать перпами. Проверяйте статус активации через API HyperCore.

5. Детерминированные адреса: адреса аккаунтов детерминированы и зависят от адреса менеджера и количества созданных аккаунтов. Используйте predictNextAccount, чтобы узнать адрес до создания.