Цю сторінку перекладено автоматично. Оригінал англійською мовою є канонічним. Читати англійською →
Перейти к основному содержимому

Онбординг

Цей документ описує життєвий цикл ончейн-акаунта, потоки фінансування та керування API-гаманцями для маркетмейкерів.

Огляд​

Hypercall використовує модель менеджер/агент:

  • Менеджер: EOA, який володіє акаунтом (зазвичай ваш основний гаманець)
  • Акаунт: Мінімальний проксі-контракт (clone), який зберігає кошти та виконує ончейн-дії
  • 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 за поточною спотовою ціною

Поведінка:

  • Розгортає детермінований мінімальний проксі (clone) контракту accountImpl
  • Встановлює 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. Передача акаунта​

Менеджери можуть передавати право власності на акаунт (не викликається безпосередньо; відбувається під час створення або через 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 — це прямий шлях фінансування через HyperEVM для грошових балансів Hypercall. Він переказує нативний HyperEVM USDC від msg.sender до Exchange, після чого Exchange депонує цей USDC на свій баланс HyperCore через CoreDepositWallet від Circle.

Хто може викликати:

  • Будь-який гаманець, роутер, 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. Бекенд має зіставити цю подію зі спостережуваним депозитом 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 апрув на 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) перед тим, як вони зможуть торгувати перпами. Перевіряйте статус активації через API HyperCore.

  5. Детерміновані адреси: Адреси акаунтів детерміновані на основі адреси менеджера та кількості створень. Використовуйте predictNextAccount, щоб дізнатися адреси до створення.

Останнє оновлення