Esta página fue traducida automáticamente. El original en inglés es la versión canónica. Leer en inglés →
Saltar al contenido principal

Onboarding

Este documento describe el ciclo de vida de las cuentas on-chain, los flujos de fondeo y la gestión de API wallets para Market Makers.

Descripción General​

Hypercall utiliza un modelo manager/agente:

  • Manager: La EOA que posee la cuenta (típicamente su wallet principal)
  • Cuenta: Un contrato proxy mínimo (clone) que custodia los fondos y ejecuta acciones on-chain
  • API Wallet: Una EOA autorizada por el manager para firmar solicitudes de trading (agente)

Todas las interacciones on-chain ocurren a través del contrato Exchange.

Direcciones de Contratos​

Testnet​

  • Exchange: ``

Mainnet​

  • Los detalles se comparten de forma privada.

Ciclo de Vida de la Cuenta​

1. Verificar Cuentas Existentes​

Antes de crear una nueva cuenta, verifique si ya tiene cuentas:

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

Ejemplo (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. Crear Cuenta​

Crea una nueva cuenta con msg.sender como manager:

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

Requisitos:

  • accountImpl debe estar configurado por la gobernanza
  • msg.value >= getCreationDeposit() (depósito mínimo en HYPE)
    • Si creationDepositUsd == 0, no se requiere depósito mínimo
    • De lo contrario, getCreationDeposit() convierte el monto en USD a HYPE usando el precio spot actual

Comportamiento:

  • Despliega un proxy mínimo determinístico (clone) de accountImpl
  • Establece msg.sender como el manager de la cuenta
  • Si msg.value > 0, realiza un depósito de HYPE en nombre de la cuenta
    • Transfiere HYPE a HYPE_SYSTEM_ADDRESS (bridge de HyperCore)
    • Si el depósito es >= $1 en HYPE, la cuenta se activa en HyperCore (se deduce la comisión de activación)

Ejemplo (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

Predecir la Dirección de la Cuenta:

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

Use esta función para conocer la dirección de la cuenta antes de su creación (útil para UI/UX).

3. Transferencia de Cuenta​

Los managers pueden transferir la propiedad de la cuenta (no invocable directamente; ocurre durante la creación o vía gobernanza):

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

La funcionalidad de transferencia de cuentas se proporciona bajo solicitud.

Gestión de API Wallets​

Las API wallets son EOAs autorizadas por el manager para firmar solicitudes de trading. Firman mensajes EIP-712 que se verifican on-chain.

Agregar API Wallet​

function addApiWallet(address account, address apiWallet) external;

Requisitos:

  • msg.sender == managers[account] (debe ser el manager de la cuenta)
  • apiWallet no debe estar activa para ninguna otra cuenta/manager
  • account != address(0) y apiWallet != address(0)

Comportamiento:

  • Mapea apiWallet -> account y apiWallet -> manager
  • Agrega apiWallet al conjunto de API wallets de la cuenta
  • Emite ApiWalletAdded(account, manager, apiWallet)

Ejemplo:

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

Remover API Wallet​

function removeApiWallet(address account, address apiWallet) external;

Requisitos:

  • msg.sender == managers[account]
  • apiWallet debe estar activa para esta cuenta/manager

Comportamiento:

  • Elimina los mapeos de apiWallet
  • Elimina apiWallet del conjunto de API wallets de la cuenta
  • Emite ApiWalletRemoved(account, manager, apiWallet)

Consultar API Wallets​

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

Devuelve la cuenta, el manager y todas las API wallets de la cuenta si apiWallet está activa. Devuelve un struct en cero si está inactiva.

Ejemplo:

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

Fondeo y Depósitos​

Depósito de USDC a Hypercall​

function depositUsdcFor(address account, uint256 amount) external;

depositUsdcFor es la ruta directa de fondeo en HyperEVM para los saldos en efectivo de Hypercall. Transfiere USDC nativo de HyperEVM desde msg.sender hacia Exchange, y luego Exchange deposita ese USDC en su saldo de HyperCore a través del CoreDepositWallet de Circle.

Quién puede invocarla:

  • Cualquier wallet, router, solver o contrato zap puede llamar a este método.
  • msg.sender paga el USDC.
  • account es la cuenta o wallet de Hypercall a acreditar. No infiera la cuenta acreditada a partir de msg.sender.

Requisitos:

  • account != address(0)
  • amount > 0
  • msg.sender debe aprobar a Exchange por amount de USDC nativo de HyperEVM
  • La implementación desplegada de Exchange debe estar construida con el token USDC nativo de HyperEVM y las direcciones de CoreDepositWallet de la red objetivo

Eventos y acreditación:

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

El evento es emitido por Exchange después de la llamada a CoreDepositWallet.depositFor. El backend debe hacer coincidir este evento con el depósito observado en HyperCore hacia el saldo del Exchange antes de acreditar el efectivo en Hypercall. La cuenta de Hypercall acreditada es el campo explícito account del evento.

Ejemplo:

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

Función de Depósito de Tokens de Opciones​

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

Tipos de Tokens Soportados:

  1. Tokens ERC20 de Opciones (registrados en OptionRegistry):
    • msg.value == 0 (requerido)
    • Quema el token de opción mediante IOptionToken(token).burnFrom(msg.sender, amount)
    • Emite Deposit(account, msg.sender, token, amount)
    • El indexador RSM detecta el evento y acredita la posición de la opción en la cuenta

Requisitos:

  • account debe ser una cuenta registrada de Hypercall
  • optionRegistry != address(0) (debe estar configurado)
  • msg.sender debe haber aprobado a Exchange por amount

Ejemplo (depósito de token de opción):

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

Transferir desde la Cuenta​

Los managers pueden transferir tokens desde su cuenta a cualquier destinatario en HyperEVM:

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

Requisitos:

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

Casos de Uso:

  • Completar transferencias de HyperCore -> HyperEVM iniciadas por la cuenta
  • Rescatar fondos de una cuenta
  • Retirar a una dirección diferente

Ejemplo:

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

Integración con la API Off-Chain​

Una vez que se crea una cuenta y se agrega una API wallet:

  1. Autenticación de la API off-chain: Use la clave privada de la API wallet para firmar mensajes EIP-712 (vea Authentication)
  2. Verificación on-chain: El RSM Sequencer llama a Exchange.hlRequestOrder (o similar) con su solicitud firmada
  3. Ejecución: El Exchange verifica la firma, recupera la API wallet, la mapea a su cuenta y ejecuta las acciones on-chain

Vea También:

Eventos​

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

Errores​

Todos los errores están definidos en IExchangeBase.sol:

  • Exchange__AccountManagerNotSet(address account): La cuenta no existe
  • Exchange__ApiWalletAlreadyActive(address apiWallet): La API wallet ya está en uso
  • Exchange__ApiWalletNotActive(address apiWallet): API wallet no encontrada
  • Exchange__CreationDepositNotMet(uint256 expected): msg.value insuficiente
  • Exchange__TokenNotSupported(address token): Token no soportado para depósito
  • Exchange__MsgValueIncorrect(uint256 expected): msg.value no coincide
  • Exchange__NotManager(address account, address notManager): El invocador no es el manager

Consideraciones de Seguridad​

  1. Seguridad de la Clave del Manager: La clave del manager controla la propiedad de la cuenta y la gestión de API wallets. Almacénela de forma segura (se recomienda una hardware wallet).

  2. Seguridad de las Claves de API Wallets: Las claves de las API wallets firman solicitudes de trading. Use claves separadas por cuenta/entorno. Rótelas regularmente.

  3. Gestión de Nonces: Cada firmante (API wallet, manager, RSM) tiene un espacio de nonces separado. Rastree los nonces off-chain para evitar ataques de repetición.

  4. Activación de la Cuenta: Las cuentas deben activarse en HyperCore (depósito >= $1 en HYPE) antes de poder operar perpetuos. Verifique el estado de activación mediante la API de HyperCore.

  5. Direcciones Determinísticas: Las direcciones de las cuentas son determinísticas según la dirección del manager y el contador de creación. Use predictNextAccount para conocer las direcciones antes de la creación.

Última actualización el