このページは機械翻訳されています。英語の原文が正式版です。 英語で読む →
メインコンテンツにスキップ

オンボーディング

このページでは、オンチェーンの Account のライフサイクル、資金の入金、API ウォレットの管理について説明します。アドレスは Contracts に記載されています。また、GET /exchange-info は稼働中の Exchange、Factory、入金ルーターのアドレスを返します。

概要​

Hypercall はマネージャーと API ウォレットのモデルを採用しています。

  • マネージャー: Account を作成・所有する EOA です（通常はメインのウォレット）。
  • Account: HyperCore 上の残高とポジションを保持し、署名済みディレクティブを実行する BeaconProxy コントラクトです。
  • API ウォレット: 注文とキャンセルに署名するために、マネージャーが Account 上で承認する EOA です。

Account は Factory によって作成されます。署名済みディレクティブは Hypercall のシーケンサーが Exchange に送信します。ユーザーが署名し、Hypercall が送信する仕組みです。

Account のライフサイクル​

1. 既存の Account を確認する​

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

struct ManagedAccount {
    address account;
    address manager;
    ApiWallet[] apiWallets; // { bytes32 name; address addr; }
}

2. Account を作成する​

// Factory
function createAccount(uint96 salt) external payable returns (address account);
function getCreationDeposit() external view returns (uint256); // in HYPE wei
function predictAccount(address manager, uint96 salt) external view returns (address account, bool exists);

要件:

  • msg.value >= getCreationDeposit() であること。Factory は作成時のデポジットを USD 建てで設定し、HyperCore のスポット価格で HYPE に換算します（端数は切り上げ）。メインネットでは現在 $1.50 です。
  • 作成フィルターが設定されている場合、そのフィルターが msg.sender を許可している必要があります。

動作:

  • マネージャーのアドレスと salt から CREATE2 で Account をデプロイします。そのため、predictAccount でアドレスを事前に知ることができます。
  • Account を Exchange に登録し、msg.sender をマネージャーに設定します。
  • msg.value の全額を HYPE として HyperCore 上の Account にブリッジします。$1 以上相当の入金により、HyperCore 上で Account が有効化されます。
const factory = new ethers.Contract(FACTORY_ADDRESS, FACTORY_ABI, signer);
const salt = 0n;
const [predicted] = await factory.predictAccount(managerAddress, salt);
const value = await factory.getCreationDeposit();
await (await factory.createAccount(salt, { value })).wait();

3. マネージャーの変更​

マネージャーを移転する関数はありません。マネージャーが変更されるのはオンチェーンの清算オークションが確定したときのみで、メインネットではオークショニアは設定されていません。変更時には、Exchange が AccountTransferred(account, oldManager, newManager) を、Account が ManagerSet(oldManager, newManager) を発行します。

API ウォレットの管理​

API ウォレットは Account 上に bytes32 の名前をキーとして保存されます。API ウォレットは HypercallApiSign EIP-712 ドメインでディレクティブに署名します。詳しくは EIP-712 署名 を参照してください。

追加・置換・削除​

マネージャーが HypercallManagerSign ドメインで署名した hc_update_api_wallet ディレクティブを送信します。

HCUpdateApiWallet(address account,uint64 nonce,UpdateApiWallet action)UpdateApiWallet(bytes32 name,address addr)
  • 新しい name を指定するとウォレットが追加されます。既存の name を指定すると、そのウォレットが置き換えられます。
  • addr = 0x0 を指定すると、name に紐づくウォレットが削除されます。
  • API ウォレットにマネージャーを指定することはできません。また、Account 上ですでに有効なウォレットも指定できません。

account、nonce、action（{ "name": "0x...", "addr": "0x..." }）、signature を付けて POST /v1/actions/hc_update_api_wallet に送信してください。POST /v1/actions/hc_update_api_wallet/typed-data は署名すべき正確な型付きデータを返します。オンチェーンの結果は GET /v1/directives/{directive_id} をポーリングして確認します。Account は ApiWalletUpdated(name, addr) を発行します。

照会​

// Account
function getApiWallets() external view returns (ApiWallet[] memory);
function getApiWallet(bytes32 name) external view returns (address);
function isApiWalletActive(address addr) external view returns (bool);

資金と入金​

Hypercall への USDC 入金​

// Exchange
function depositUsdcFor(address account, uint256 amount) external;

depositUsdcFor は、Hypercall の現金残高に HyperEVM から直接入金するための経路です。msg.sender からネイティブの HyperEVM USDC を Exchange に引き出し、Circle の CoreDepositWallet を通じて Exchange の HyperCore 残高に入金します。

呼び出し可能な主体:

  • 任意のウォレット、ルーター、ソルバー、ザップコントラクト。
  • USDC を支払うのは msg.sender です。
  • account は入金先となる Hypercall のアカウントまたはウォレットです。入金先のアカウントを msg.sender から推定しないでください。

要件:

  • account != address(0) かつ amount > 0 であること
  • msg.sender が Exchange に対して amount 分の USDC を承認済みであること
event UsdcDeposit(
    address indexed account,
    address indexed from,
    address indexed token,
    uint256 amount,
    uint32 dstDex
);

Hypercall は、このイベントを観測された HyperCore 上の入金と照合した後にのみ現金を計上します。入金先のアカウントは account フィールドです。

await usdc.approve(EXCHANGE_ADDRESS, amount);
await exchange.depositUsdcFor(accountAddress, amount);

Router の deposit(account, token, amount, isPerp) は、アプリが USDC、スポットトークン、オプショントークンの入金に使用する汎用ヘルパーです。

オプショントークンの入金​

// Exchange
function depositOption(address account, address token, uint256 amount) external;
  • account は登録済みの Hypercall Account である必要があります。
  • token は Option Registry でサポートされているオプションである必要があります。
  • msg.sender から amount をバーンし（事前に Exchange を承認してください）、Deposit(account, msg.sender, token, amount) を発行します。エンジンはこのイベントをもとに残高を計上します。

Account からの送金​

// Account, manager only
function transferTo(address recipient, address token, uint256 amount) external;

Account が HyperEVM 上で保有するネイティブ HYPE（token = 0x0）または ERC20 を recipient に送金します。HyperCore から HyperEVM への送金を完了させる場合や、Account の資産を引き上げる場合に使用します。Account が清算中の間は使用できません。

パーペチュアル取引のためのビルダー承認​

// Account, manager only
function approveZeroFeeBuilder(address builder) external;

Hyperliquid のビルダーを、最大手数料 0% で Account に対して承認します。Hypercall のすべてのパーペチュアル注文には Hypercall のビルダーコードが付与されるため、最初のパーペチュアル注文の前に、GET /exchange-info から取得した hl_builder_address を指定してこの関数を一度呼び出してください。アプリでは Enable trading のステップでこの処理を行います。

イベント​

// Exchange
event AccountTransferred(address indexed account, address indexed oldManager, address indexed newManager);
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);
// Factory
event AccountCreated(address indexed account, address indexed manager);
// Account
event ApiWalletUpdated(bytes32 indexed name, address indexed addr);
event ManagerSet(address indexed oldManager, address indexed newManager);

エラー​

  • Factory__CreationDepositNotMet(uint256 expected): msg.value が作成時のデポジットに満たない
  • Factory__CreationNotAllowed(): 作成フィルターによってブロックされた
  • Exchange__AccountDoesNotExist(address account): 登録済みの Account ではない
  • Exchange__TokenNotSupported(address token): サポートされているオプショントークンではない
  • Account__NotManager(address addr): 呼び出し元または署名者がマネージャーではない
  • Account__ApiWalletNotActive(address addr): 署名者が有効な API ウォレットではない
  • Account__ApiWalletAlreadyActive(address addr): API ウォレットがすでに Account 上に存在する
  • Account__ApiWalletIsManager(): マネージャーを自身の API ウォレットにすることはできない
  • Account__NonceAlreadyUsed(address signer, uint256 nonce): nonce が再利用された
  • Account__LiquidationInProgress(): 清算中のため操作がブロックされた

セキュリティ上の考慮事項​

  1. マネージャーの鍵: API ウォレット、送金、ビルダー承認を管理します。ハードウェアウォレットを使用してください。
  2. API ウォレットの鍵: 注文とキャンセルの署名のみを行います。システムごとに別々の鍵を使用し、定期的にローテーションしてください。
  3. Nonce: 署名者ごとに独立した nonce 空間があります。ミリ秒単位のタイムスタンプを使用し、オフチェーンで管理してください。
  4. 有効化: パーペチュアルを取引する前に、Account を HyperCore 上で有効化する必要があります（$1 以上の HYPE を入金）。
最終更新: