Onboarding

Bu doküman, Piyasa Yapıcılar için zincir üstü hesap yaşam döngüsünü, fonlama akışlarını ve API cüzdanı yönetimini açıklamaktadır.

Genel Bakış

Hypercall bir yönetici/vekil (manager/agent) modeli kullanır:

• Manager (Yönetici): Hesabın sahibi olan EOA (genellikle ana cüzdanınız)
• Account (Hesap): Fonları tutan ve zincir üstü işlemleri gerçekleştiren minimal bir proxy kontratı (clone)
• API Wallet (API Cüzdanı): Yönetici tarafından alım satım isteklerini imzalamak üzere yetkilendirilmiş bir EOA (vekil)

Tüm zincir üstü etkileşimler Exchange kontratı üzerinden gerçekleşir.

Kontrat Adresleri

Testnet

• Exchange: ``

Ana Ağ

• Detaylar özel olarak paylaşılmaktadır.

Hesap Yaşam Döngüsü

1. Mevcut Hesapları Kontrol Edin

Yeni bir hesap oluşturmadan önce, hâlihazırda hesaplarınızın olup olmadığını kontrol edin:

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

Örnek (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. Hesap Oluşturun

msg.sender'ı yönetici olarak ayarlayarak yeni bir hesap oluşturur:

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

Gereksinimler:

• accountImpl yönetişim (governance) tarafından ayarlanmış olmalıdır
• msg.value >= getCreationDeposit() (HYPE cinsinden minimum yatırma tutarı)
  • creationDepositUsd == 0 ise, minimum yatırma tutarı gerekmez
  • Aksi halde, getCreationDeposit() USD tutarını güncel spot fiyat üzerinden HYPE'a dönüştürür

Davranış:

• accountImpl kontratının deterministik bir minimal proxy'sini (clone) dağıtır
• msg.sender'ı hesap yöneticisi olarak ayarlar
• msg.value > 0 ise, hesap adına HYPE yatırma işlemi gerçekleştirir
  • HYPE'ı HYPE_SYSTEM_ADDRESS adresine aktarır (HyperCore köprüsü)
  • Yatırılan tutar 1$ değerinde HYPE veya üzerindeyse, hesap HyperCore üzerinde aktive edilir (aktivasyon ücreti düşülür)

Örnek (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

Hesap Adresini Önceden Tahmin Edin:

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

Hesap adresini oluşturmadan önce öğrenmek için bunu kullanın (UI/UX için faydalıdır).

3. Hesap Devri

Yöneticiler hesap sahipliğini devredebilir (doğrudan çağrılamaz; oluşturma sırasında veya yönetişim aracılığıyla gerçekleşir):

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

Hesap devri işlevi talep üzerine sağlanmaktadır.

API Cüzdanı Yönetimi

API cüzdanları, yönetici tarafından alım satım isteklerini imzalamak üzere yetkilendirilmiş EOA'lardır. Zincir üzerinde doğrulanan EIP-712 mesajlarını imzalarlar.

API Cüzdanı Ekleme

function addApiWallet(address account, address apiWallet) external;

Gereksinimler:

• msg.sender == managers[account] (hesap yöneticisi olmalıdır)
• apiWallet başka herhangi bir hesap/yönetici için aktif olmamalıdır
• account != address(0) ve apiWallet != address(0)

Davranış:

• apiWallet -> account ve apiWallet -> manager eşlemelerini oluşturur
• apiWallet'ı hesabın API cüzdanı kümesine ekler
• ApiWalletAdded(account, manager, apiWallet) olayını yayınlar

Örnek:

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

API Cüzdanı Kaldırma

function removeApiWallet(address account, address apiWallet) external;

Gereksinimler:

• msg.sender == managers[account]
• apiWallet bu hesap/yönetici için aktif olmalıdır

Davranış:

• apiWallet için eşlemeleri kaldırır
• apiWallet'ı hesabın API cüzdanı kümesinden çıkarır
• ApiWalletRemoved(account, manager, apiWallet) olayını yayınlar

API Cüzdanlarını Sorgulama

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

apiWallet aktifse hesabı, yöneticiyi ve hesaba ait tüm API cüzdanlarını döndürür. Aktif değilse sıfır struct döndürür.

Örnek:

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

Fonlama ve Para Yatırma

Hypercall'a USDC Yatırma

function depositUsdcFor(address account, uint256 amount) external;

depositUsdcFor, Hypercall nakit bakiyeleri için doğrudan HyperEVM fonlama yoludur. Yerel HyperEVM USDC'yi msg.sender'dan Exchange kontratına aktarır, ardından Exchange bu USDC'yi Circle'ın CoreDepositWallet kontratı aracılığıyla kendi HyperCore bakiyesine yatırır.

Kimler çağırabilir:

• Herhangi bir cüzdan, router, solver veya zap kontratı bu metodu çağırabilir.
• USDC'yi msg.sender öder.
• account, bakiyesi alacaklandırılacak Hypercall hesabı veya cüzdanıdır. Alacaklandırılacak hesabı msg.sender üzerinden çıkarsamayın.

Gereksinimler:

• account != address(0)
• amount > 0
• msg.sender, Exchange kontratına amount kadar yerel HyperEVM USDC için onay (approve) vermelidir
• Dağıtılan Exchange implementasyonu, hedef ağ için yerel HyperEVM USDC token ve CoreDepositWallet adresleriyle oluşturulmuş olmalıdır

Olaylar ve alacaklandırma:

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

Bu olay, CoreDepositWallet.depositFor çağrısından sonra Exchange tarafından yayınlanır. Backend, Hypercall nakit bakiyesini alacaklandırmadan önce bu olayı Exchange bakiyesine gelen ve gözlemlenen HyperCore yatırma işlemiyle eşleştirmelidir. Alacaklandırılan Hypercall hesabı, olaydaki açık account alanıdır.

Örnek:

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

Opsiyon Token Yatırma Fonksiyonu

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

Desteklenen Token Türleri:

1. Opsiyon ERC20 Tokenları (OptionRegistry içinde kayıtlı):
   • msg.value == 0 (zorunludur)
   • Opsiyon tokenını IOptionToken(token).burnFrom(msg.sender, amount) aracılığıyla yakar (burn)
   • Deposit(account, msg.sender, token, amount) olayını yayınlar
   • RSM indeksleyicisi olayı yakalar ve hesabın opsiyon pozisyonunu alacaklandırır

Gereksinimler:

• account kayıtlı bir Hypercall hesabı olmalıdır
• optionRegistry != address(0) (ayarlanmış olmalıdır)
• msg.sender, Exchange kontratına amount için onay vermiş olmalıdır

Örnek (opsiyon token yatırma):

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

Hesaptan Transfer

Yöneticiler, hesaplarından HyperEVM üzerindeki herhangi bir alıcıya token aktarabilir:

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

Gereksinimler:

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

Kullanım Senaryoları:

• Hesap tarafından başlatılan HyperCore -> HyperEVM transferlerini tamamlamak
• Hesaptan fon kurtarmak
• Farklı bir adrese para çekmek

Örnek:

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

Zincir Dışı API ile Entegrasyon

Bir hesap oluşturulup bir API cüzdanı eklendikten sonra:

1. Zincir dışı API kimlik doğrulaması: EIP-712 mesajlarını imzalamak için API cüzdanının özel anahtarını kullanın (bkz. Authentication)
2. Zincir üstü doğrulama: RSM Sequencer, imzalı isteğinizle birlikte Exchange.hlRequestOrder (veya benzeri) fonksiyonunu çağırır
3. Yürütme: Exchange imzayı doğrular, API cüzdanını kurtarır (recover), hesabınızla eşleştirir ve zincir üstü işlemleri gerçekleştirir

Ayrıca Bakınız:

• Zincir dışı API kimlik doğrulaması için Authentication

Olaylar

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

Hatalar

Tüm hatalar IExchangeBase.sol içinde tanımlanmıştır:

• Exchange__AccountManagerNotSet(address account): Hesap mevcut değil
• Exchange__ApiWalletAlreadyActive(address apiWallet): API cüzdanı zaten kullanımda
• Exchange__ApiWalletNotActive(address apiWallet): API cüzdanı bulunamadı
• Exchange__CreationDepositNotMet(uint256 expected): Yetersiz msg.value
• Exchange__TokenNotSupported(address token): Token yatırma için desteklenmiyor
• Exchange__MsgValueIncorrect(uint256 expected): msg.value uyuşmazlığı
• Exchange__NotManager(address account, address notManager): Çağıran yönetici değil

Güvenlik Hususları

1. Yönetici Anahtar Güvenliği: Yönetici anahtarı, hesap sahipliğini ve API cüzdanı yönetimini kontrol eder. Güvenli bir şekilde saklayın (donanım cüzdanı önerilir).

2. API Cüzdanı Anahtar Güvenliği: API cüzdanı anahtarları alım satım isteklerini imzalar. Her hesap/ortam için ayrı anahtarlar kullanın. Düzenli olarak yenileyin.

3. Nonce Yönetimi: Her imzalayıcının (API cüzdanı, yönetici, RSM) ayrı bir nonce alanı vardır. Tekrar (replay) saldırılarını önlemek için nonce'ları zincir dışında takip edin.

4. Hesap Aktivasyonu: Hesapların perp işlemleri yapabilmesi için önce HyperCore üzerinde aktive edilmesi gerekir (1$ değerinde veya üzeri HYPE yatırma). Aktivasyon durumunu HyperCore API üzerinden kontrol edin.

5. Deterministik Adresler: Hesap adresleri, yönetici adresine ve oluşturma sayısına göre deterministiktir. Adresleri oluşturmadan önce öğrenmek için predictNextAccount fonksiyonunu kullanın.