Diese Seite wurde maschinell übersetzt. Das englische Original ist maßgeblich. Auf Englisch lesen →
Zum Hauptinhalt springen

Onboarding

Dieses Dokument beschreibt den On-Chain-Konto-Lebenszyklus, die Finanzierungsflüsse und die Verwaltung von API-Wallets für Market Maker.

Überblick​

Hypercall verwendet ein Manager/Agent-Modell:

  • Manager: Die EOA, die das Konto besitzt (typischerweise Ihre Haupt-Wallet)
  • Konto: Ein minimaler Proxy-Vertrag (Clone), der Gelder hält und On-Chain-Aktionen ausführt
  • API-Wallet: Eine vom Manager autorisierte EOA zum Signieren von Handelsanfragen (Agent)

Alle On-Chain-Interaktionen erfolgen über den Exchange-Vertrag.

Vertragsadressen​

Testnet​

  • Exchange: ``

Mainnet​

  • Details werden vertraulich mitgeteilt.

Konto-Lebenszyklus​

1. Bestehende Konten prüfen​

Prüfen Sie vor der Erstellung eines neuen Kontos, ob Sie bereits Konten besitzen:

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

Beispiel (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. Konto erstellen​

Erstellt ein neues Konto mit msg.sender als Manager:

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

Anforderungen:

  • accountImpl muss durch die Governance gesetzt sein
  • msg.value >= getCreationDeposit() (Mindesteinzahlung in HYPE)
    • Wenn creationDepositUsd == 0, ist keine Mindesteinzahlung erforderlich
    • Andernfalls konvertiert getCreationDeposit() den USD-Betrag anhand des aktuellen Spot-Preises in HYPE

Verhalten:

  • Deployt einen deterministischen minimalen Proxy (Clone) von accountImpl
  • Setzt msg.sender als Konto-Manager
  • Wenn msg.value > 0, wird eine HYPE-Einzahlung im Namen des Kontos durchgeführt
    • Überträgt HYPE an HYPE_SYSTEM_ADDRESS (HyperCore-Bridge)
    • Wenn die Einzahlung >= HYPE im Wert von 1 $ beträgt, wird das Konto auf HyperCore aktiviert (Aktivierungsgebühr wird abgezogen)

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

Kontoadresse vorhersagen:

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

Verwenden Sie dies, um die Kontoadresse vor der Erstellung zu kennen (nützlich für UI/UX).

3. Kontoübertragung​

Manager können das Konto-Eigentum übertragen (nicht direkt aufrufbar; erfolgt während der Erstellung oder über die Governance):

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

Die Funktionalität zur Kontoübertragung wird auf Anfrage bereitgestellt.

Verwaltung von API-Wallets​

API-Wallets sind EOAs, die vom Manager autorisiert wurden, Handelsanfragen zu signieren. Sie signieren EIP-712-Nachrichten, die on-chain verifiziert werden.

API-Wallet hinzufügen​

function addApiWallet(address account, address apiWallet) external;

Anforderungen:

  • msg.sender == managers[account] (muss der Konto-Manager sein)
  • apiWallet darf für kein anderes Konto bzw. keinen anderen Manager aktiv sein
  • account != address(0) und apiWallet != address(0)

Verhalten:

  • Mappt apiWallet -> account und apiWallet -> manager
  • Fügt apiWallet zur API-Wallet-Menge des Kontos hinzu
  • Emittiert ApiWalletAdded(account, manager, apiWallet)

Beispiel:

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

API-Wallet entfernen​

function removeApiWallet(address account, address apiWallet) external;

Anforderungen:

  • msg.sender == managers[account]
  • apiWallet muss für dieses Konto bzw. diesen Manager aktiv sein

Verhalten:

  • Entfernt die Mappings für apiWallet
  • Entfernt apiWallet aus der API-Wallet-Menge des Kontos
  • Emittiert ApiWalletRemoved(account, manager, apiWallet)

API-Wallets abfragen​

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

Gibt das Konto, den Manager und alle API-Wallets des Kontos zurück, wenn apiWallet aktiv ist. Gibt eine Null-Struktur zurück, wenn inaktiv.

Beispiel:

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

Finanzierung & Einzahlungen​

USDC-Einzahlung auf Hypercall​

function depositUsdcFor(address account, uint256 amount) external;

depositUsdcFor ist der direkte HyperEVM-Finanzierungspfad für Hypercall-Cash-Guthaben. Die Funktion überträgt natives HyperEVM-USDC von msg.sender an Exchange; anschließend zahlt Exchange dieses USDC über Circles CoreDepositWallet in sein HyperCore-Guthaben ein.

Wer darf sie aufrufen:

  • Jede Wallet, jeder Router, Solver oder Zap-Vertrag darf diese Methode aufrufen.
  • msg.sender zahlt das USDC.
  • account ist das Hypercall-Konto oder die Wallet, dem/der gutgeschrieben wird. Leiten Sie das gutzuschreibende Konto nicht aus msg.sender ab.

Anforderungen:

  • account != address(0)
  • amount > 0
  • msg.sender muss Exchange für amount an nativem HyperEVM-USDC genehmigen (approve)
  • Die deployte Exchange-Implementierung muss mit den Adressen des nativen HyperEVM-USDC-Tokens und des CoreDepositWallet für das Zielnetzwerk konstruiert worden sein

Events und Gutschrift:

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

Das Event wird von Exchange nach dem Aufruf von CoreDepositWallet.depositFor emittiert. Das Backend muss dieses Event mit der beobachteten HyperCore-Einzahlung in das Exchange-Guthaben abgleichen, bevor Hypercall-Cash gutgeschrieben wird. Das gutgeschriebene Hypercall-Konto ist das explizite account-Event-Feld.

Beispiel:

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

Einzahlungsfunktion für Options-Token​

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

Unterstützte Token-Typen:

  1. Options-ERC20-Token (registriert im OptionRegistry):
    • msg.value == 0 (erforderlich)
    • Verbrennt den Options-Token über IOptionToken(token).burnFrom(msg.sender, amount)
    • Emittiert Deposit(account, msg.sender, token, amount)
    • Der RSM-Indexer erfasst das Event und schreibt die Optionsposition dem Konto gut

Anforderungen:

  • account muss ein registriertes Hypercall-Konto sein
  • optionRegistry != address(0) (muss gesetzt sein)
  • msg.sender muss Exchange für amount genehmigt haben (approve)

Beispiel (Einzahlung eines Options-Tokens):

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

Übertragung vom Konto​

Manager können Token von ihrem Konto an einen beliebigen Empfänger auf HyperEVM übertragen:

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

Anforderungen:

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

Anwendungsfälle:

  • Abschluss von HyperCore -> HyperEVM-Übertragungen, die vom Konto initiiert wurden
  • Rettung von Geldern aus einem Konto
  • Auszahlung an eine andere Adresse

Beispiel:

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

Integration mit der Off-Chain-API​

Sobald ein Konto erstellt und eine API-Wallet hinzugefügt wurde:

  1. Off-Chain-API-Authentifizierung: Verwenden Sie den privaten Schlüssel der API-Wallet, um EIP-712-Nachrichten zu signieren (siehe Authentifizierung)
  2. On-Chain-Verifizierung: Der RSM-Sequencer ruft Exchange.hlRequestOrder (oder Ähnliches) mit Ihrer signierten Anfrage auf
  3. Ausführung: Die Exchange verifiziert die Signatur, ermittelt die API-Wallet, ordnet sie Ihrem Konto zu und führt On-Chain-Aktionen aus

Siehe auch:

Events​

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

Fehler​

Alle Fehler sind in IExchangeBase.sol definiert:

  • Exchange__AccountManagerNotSet(address account): Konto existiert nicht
  • Exchange__ApiWalletAlreadyActive(address apiWallet): API-Wallet bereits in Verwendung
  • Exchange__ApiWalletNotActive(address apiWallet): API-Wallet nicht gefunden
  • Exchange__CreationDepositNotMet(uint256 expected): Unzureichender msg.value
  • Exchange__TokenNotSupported(address token): Token wird für Einzahlungen nicht unterstützt
  • Exchange__MsgValueIncorrect(uint256 expected): msg.value stimmt nicht überein
  • Exchange__NotManager(address account, address notManager): Aufrufer ist nicht der Manager

Sicherheitshinweise​

  1. Sicherheit des Manager-Schlüssels: Der Manager-Schlüssel kontrolliert das Konto-Eigentum und die Verwaltung der API-Wallets. Bewahren Sie ihn sicher auf (Hardware-Wallet empfohlen).

  2. Sicherheit der API-Wallet-Schlüssel: API-Wallet-Schlüssel signieren Handelsanfragen. Verwenden Sie separate Schlüssel pro Konto/Umgebung. Rotieren Sie sie regelmäßig.

  3. Nonce-Verwaltung: Jeder Signierer (API-Wallet, Manager, RSM) hat einen separaten Nonce-Raum. Verfolgen Sie Nonces off-chain, um Replay-Angriffe zu vermeiden.

  4. Kontoaktivierung: Konten müssen auf HyperCore aktiviert werden (Einzahlung >= 1 $ in HYPE), bevor sie Perpetuals handeln können. Prüfen Sie den Aktivierungsstatus über die HyperCore-API.

  5. Deterministische Adressen: Kontoadressen sind deterministisch, basierend auf der Manager-Adresse und der Anzahl der Erstellungen. Verwenden Sie predictNextAccount, um Adressen vor der Erstellung zu kennen.

Zuletzt aktualisiert am