Azioni del deployer HIP-3

L'API per il deploy e la gestione di DEX perpetual distribuiti da builder prevede le seguenti azioni L1:

// IMPORTANT: All lists of tuples should be lexographically sorted before signing
type PerpDeployAction =
  | {
      type: "perpDeploy";
      registerAsset2: RegisterAsset2;
    }
  | {
      type: "perpDeploy";
      registerAsset: RegisterAsset;
    }
  | {
      type: "perpDeploy";
      setOracle: SetOracle;
    }
  | {
      type: "perpDeploy";
      setFundingMultipliers: SetFundingMultipliers;
    }
  | {
      type: "perpDeploy";
      setFundingInterestRates: SetFundingInterestRates;
    }
  | {
      type: "perpDeploy";
      setFundingClamps: SetFundingClamps;
    }
  | {
      type: "perpDeploy";
      haltTrading: { coin: string; isHalted: boolean };
    }
  | {
      type: "perpDeploy";
      insertMarginTable: InsertMarginTable;
    }
  | {
      type: "perpDeploy";
      setMarginTableIds: SetMarginTableIds;
    }
  | {
      type: "perpDeploy";
      setFeeRecipient: { dex: string; feeRecipient: address };
    }
  | {
      type: "perpDeploy";
      setOpenInterestCaps: SetOpenInterestCaps;
    }
  | {
      type: "perpDeploy";
      setSubDeployers: { dex: string; subDeployers: Array<SubDeployerInput> };
    }
  | {
      type: "perpDeploy";
      setMarginModes: SetMarginModes;
    }
  | {
      type: "perpDeploy";
      setDeployerFees: SetDeployerFees;
    }
  | {
      type: "perpDeploy";
      setPerpAnnotation: SetPerpAnnotation;
    }
  | {
      type: "perpDeploy";
      disableDex: string;
    };

// User-signed action to transfer collateral between the user's DEX account and its backstop liquidator.
// ntl must be positive and a multiple of 1_000_000_000.
type Hip3LiquidatorTransferAction = {
  type: "hip3LiquidatorTransfer";
  dex: string;
  ntl: number; // Integer amount in millionths of a collateral token: 1_000_000_000 = 1,000 tokens
  isDeposit: boolean; // true deposits; false withdraws
};

/**
 * RegisterAsset2 can be called to initialize a new dex and register an asset at the same time.
 * If schema is not provided, then RegisterAsset can be called multiple times to register additional assets
 * for the provided dex.
 * @param maxGas - Max gas in native token wei. If not provided, then uses current deploy auction price.
 * If the max gas is 0, then a reserve deployment will be used.
 * A reserve deployment allows deployment at the current price of the gas auction, even if it has ended.
 * Currently, 7 reserve deployments are allowed.
 * IMPORTANT: A reserve deployment will be used regardless of whether the auction has completed, so deployers should query the auction status first.
 * @param assetRequest - Contains new asset listing parameters. See RegisterAssetRequest2 below for details.
 * @param dex - Name of the perp dex (2-4 lowercase characters)
 * @param schema - Contains new perp dex parameters. See PerpDexSchemaInput below for details.
 */
type RegisterAsset2 = {
  maxGas?: number;
  assetRequest: RegisterAssetRequest2;
  dex: string;
  schema?: PerpDexSchemaInput;
};

// Same as RegisterAsset2 but uses RegisterAssetRequest
type RegisterAsset = {
  maxGas?: number;
  assetRequest: RegisterAssetRequest;
  dex: string;
  schema?: PerpDexSchemaInput;
};

type RegisterAssetRequest2 = {
  coin: string;
  szDecimals: number;
  oraclePx: string;
  marginTableId: number;
  marginMode: "strictIsolated" | "noCross" | "normal"; // strictIsolated does not allow withdrawing of isolated margin from open positions
};

type RegisterAssetRequest = {
  coin: string;
  szDecimals: number;
  oraclePx: string;
  marginTableId: number;
  onlyIsolated: boolean;
};

/**
 * The markPxs outer list can be length 0, 1, or 2. The median of these inputs
 * along with the local mark price (median(best bid, best ask, last trade price))
 * is used as the new mark price update.
 *
 * SetOracle can be called multiple times but there must be at least 2.5 seconds between calls.
 *
 * Stale mark prices will be updated to the local mark price after 10 seconds of no updates.
 * This fallback counts as an update for purposes of the maximal update frequency.
 * This fallback behavior should not be relied upon. Deployers are expected to call setOracle every 3 seconds even with no changes.
 *
 * All prices are clamped to 10x the start of day value.
 * markPx moves are clamped to 1% from previous markPx.
 * markPx cannot be updated such that open interest would be 10x the open interest cap.
 * @param dex - Name of the perp dex
 * @param oraclePxs - A list (sorted by key) of asset and oracle prices.
 * @param markPxs - An outer list of inner lists (inner list sorted by key) of asset and mark prices.
 * @param externalPerpPxs - A list (sorted by key) of asset and external prices which prevent sudden mark price deviations.
 * Ideally externally determined by deployer, but could fall back to an EMA of recent mark prices.
 * Must include all assets.
 */
type SetOracle = {
  dex: string;
  oraclePxs: Array<[string, string]>;
  markPxs: Array<Array<[string, string]>>;
  externalPerpPxs: Array<[string, string]>;
};

/**
 * @param fullName - Full name of the perp dex
 * @param collateralToken - Collateral token index
 * @param oracleUpdater - User to update oracles. If not provided, then deployer is assumed to be oracle updater.
 */
type PerpDexSchemaInput = {
  fullName: string;
  collateralToken: int;
  oracleUpdater?: string;
};

/**
 * A sorted list of asset and funding multiplier.
 * Multipliers must be between 0 and 10 and are used to scale the funding rate.
 */
type SetFundingMultipliers = Array<[string, string]>;

/**
 * A sorted list of asset and 8 hour interest rate.
 * Interest rates must be between -0.01 and 0.01 and are used as the interest rate
 * component in the funding calculation.
 */
type SetFundingInterestRates = Array<[string, string]>;

/**
 * A sorted list of asset and 8 hour funding clamp.
 * Clamps must be between 0 and 0.01 and bound how far the funding rate can move away from the
 * average premium toward the interest rate. Defaults to 0.0003.
 */
type SetFundingClamps = Array<[string, string]>;

/**
 * A sorted of asset and margin table ids.
 * Margin table ids must be non-zero.
 */
type SetMarginTableIds = Array<[string, number]>;

/**
 * Inserts margin table to dex
 */
type InsertMarginTable = {
  dex: string;
  marginTable: RawMarginTable;
};

/**
 * marginTiers must be sorted in order of increasing lower bound and decreasing maxLeverage
 * marginTiers has a maximum length of 3.
 */
type RawMarginTable = {
  description: string;
  marginTiers: Array<RawMarginTier>;
};

/**
 * lowerBound is a position notional value above which the leverage is constrained by maxLeverage
 */
type RawMarginTier = {
  lowerBound: int;
  maxLeverage: MaxLeverage;
};

/**
 * Max leverage is in the range [1, 50]
 */
type MaxLeverage = number;

/**
 * A sorted list of asset and open interest cap notionals.
 * Open interest caps must be at least the maximum of 1_000_000 (1 size unit of collateral asset) or half of the current open interest.
 * null removes the custom cap for an asset.
 */
type SetOpenInterestCaps = Array<[string, number | null]>;

/**
 * A modification to sub-deployer permissions
 */
type SubDeployerInput = {
  variant: string; // corresponds to a variant of PerpDeployAction. For example, "haltTrading" or "setOracle"
  user: String;
  allowed: boolean; // add or remove the subDeployer from the authorized set for the action variant
};

// A sorted list of (coin, marginMode). See RegisterAssetRequest2 for margin mode definitions.
type SetMarginModes = Array<[string, "strictIsolated" | "noCross" | "normal"]>;

// Let the user normal rate be `x`. Let the user rate be `y` after accounting for aligned quote collateral.
// In other words, `x = y` for non-aligned collateral.
// User pays or receives rebate `P + D` where `P` goes to protocol and `D` goes to deployer.
// If `x > 0` and `scale < 1`, `P = y` and `D = scale * x`
// If `x > 0` and `scale > 1`, `P = y * scale` and `D = x * scale`
// If `x < 0` and `scale < 1`, `P = y / (1 + scale)` and `D = y * scale / (1 + scale)`
// If `x < 0` and `scale > 1`, `P = y / 2` and `D = y / 2`
// On Mainnet, rate limited to one change per 30 days.
// Note that there are currently no aligned quote assets on mainnet.
type SetDeployerFees = Array<
  [
    string,
    {
      scale: string; // Decimal string in [0.0, 3.0], or [0.0, 10.0) when growthMode is true
      growthMode: boolean;
    },
  ]
>;

// category <= 15 characters
// description <= 400 characters
// displayName <= 9 characters
// <= 2 keywords, each keyword <= 10 characters
type SetPerpAnnotation = {
  coin: string;
  category: string;
  description: string;
  displayName: string | null;
  keywords: Array<string>;
};

Per gli esempi seguenti, feeScale è il campo scale in SetDeployerFees. Si assuma una commissione utente normale positiva pari a 1 unità e un collaterale non allineato (x = y = 1). userFeeToProtocol e userFeeToDeployer sono le unità di commissione risultanti addebitate all'utente.

Vedere https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/info-endpoint/perpetuals#retrieve-information-about-the-perp-deploy-auction per le modalità di interrogazione dello stato dell'asta di deploy dei perpetual.

Limiti di interesse aperto

I mercati perpetual distribuiti da builder sono soggetti a due tipi di limiti di interesse aperto: nozionale (somma della dimensione assoluta della posizione moltiplicata per il mark price) e di dimensione (somma delle dimensioni assolute delle posizioni).

I limiti di interesse aperto nozionali sono applicati all'interesse aperto totale sommato su tutti gli asset all'interno del DEX, nonché per singolo asset. I deployer di perpetual possono impostare un limite di interesse aperto personalizzato per asset, come documentato in https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/hip-3-deployer-actions.

I limiti di interesse aperto denominati in dimensione sono applicati solo per singolo asset. I limiti di interesse aperto denominati in dimensione sono attualmente una costante di 1B per asset, pertanto un valore predefinito ragionevole consiste nell'impostare szDecimals in modo che l'incremento minimo di dimensione sia di $1-10 al mark price iniziale.

Liquidatore di backstop

L'indirizzo del liquidatore di backstop è 0x4000000000000000000000000000000000000000 + {dex_index}. Ad esempio, il primo DEX HIP-3 ha come indirizzo del liquidatore di backstop 0x4000000000000000000000000000000000000001.

Stati del clearinghouse utente del nodo

Il flag del nodo --write-user-clearinghouse-states <dex> scrive gli stati del clearinghouse per il DEX HIP-3 indicato in file orari in ~/hl/data/dex_user_clearinghouse_states/hourly/<date>/<hour>, dove date è YYYYMMDD. Ogni riga è un array JSON [time, messages], dove time è il tempo del blocco e messages è uno snapshot singolo di ogni utente sul DEX oppure un elenco di diff per utente:

["2026-09-24T09:00:00.123", [{ "Snapshot": { "0xUSER_A": <clearinghouseState> } }]]
["2026-09-24T09:00:03.456", [{ "Diff": ["0xUSER_A", <clearinghouseState>] }]]

Ogni <clearinghouseState> ha lo stesso formato della risposta alla richiesta info clearinghouseState per tale DEX, denominato nel token di collaterale del venue. Tiene conto solo dello stato dell'utente sul DEX indicato, pertanto il collaterale condiviso tra DEX (ad esempio tramite user abstraction) non è incluso e liquidationPx è sempre null. La prima riga di ogni file, e la prima riga scritta dopo l'avvio del nodo, è uno snapshot. Le altre righe contengono i diff per gli utenti il cui stato del clearinghouse è cambiato, ignorando time: ogni tale utente a ogni aggiornamento dell'oracle per il venue, oppure solo gli utenti coinvolti in un fill, una liquidazione, un pagamento di funding o un trasferimento verso o dal venue.

HIP-3* (solo testnet)

Azioni star

Un venue HIP-3 può essere designato HIP-3* al momento della creazione impostando isStar: true in PerpDexSchemaInput. Questo valore booleano facoltativo è false per impostazione predefinita. HIP-3* abilita diverse funzionalità in aggiunta alle specifiche HIP-3, tra cui una allow-list e azioni utente intermediate da proxy.

Operazioni

type Hip3StarAction = {
  type: "perpDeploy";
  star: { dex: string; operation: Hip3StarOperation };
};

type Hip3StarOperation =
  | { proxy: [address, Hip3StarProxyOperation] }
  | { setOracle: { oraclePxs: Array<[string, string]> } };

// CancelAction and OrderAction are the standard exchange actions.
type Hip3StarProxyOperation =
  | { modifyApproval: boolean }
  | { modifyBackstopLiquidatorApproval: boolean }
  | { setReduceOnly: boolean }
  | { cancel: Omit<CancelAction, "type"> }
  | { cancelAll: { assets?: Array<number> | null } }
  | { order: Omit<OrderAction, "type"> }
  | { sendAsset: { destination: address; amount: string } };

{
  "type": "perpDeploy",
  "star": {
    "dex": "test",
    "operation": { "proxy": ["0xUSER_A", { "modifyApproval": true }] }
  }
}
{
  "type": "perpDeploy",
  "star": {
    "dex": "test",
    "operation": { "proxy": ["0xUSER_B", { "cancelAll": { "assets": [100001, 100002] } }] }
  }
}
{
  "type": "perpDeploy",
  "star": {
    "dex": "test",
    "operation": { "setOracle": { "oraclePxs": [["test:BTC", "100000.0"], ["test:ETH", "4000.0"]] } }
  }
}

• proxy — una coppia costituita da un indirizzo utente e da un'operazione proxy applicata a tale utente.
• setOracle — aggiorna i prezzi dell'oracle, come descritto nella sezione Oracle di seguito.

Operazioni proxy

• modifyApproval — { "modifyApproval": true } aggiunge l'utente all'allowlist, false lo rimuove e azzera i relativi flag. Rimuovere un utente non approvato non ha effetto. Approvare nuovamente un utente già approvato non ha effetto e mantiene i flag dell'utente. Un utente rimosso che viene approvato di nuovo riparte dai flag predefiniti.
• modifyBackstopLiquidatorApproval — { "modifyBackstopLiquidatorApproval": true } consente all'utente di effettuare depositi e prelievi dal liquidatore di backstop del venue tramite hip3LiquidatorTransfer; false revoca tale autorizzazione. L'utente deve già essere approvato tramite modifyApproval.
• setReduceOnly — { "setReduceOnly": true } limita un utente approvato alla riduzione delle proprie posizioni sul venue. L'utente può solo inserire ordini e TWAP reduce-only, modificare ordini in ordini reduce-only e annullare. { "setReduceOnly": false } ripristina il trading completo.
• cancel — { "cancel": { "cancels": [{ "a": <asset>, "o": <oid> }] } }, il payload standard dell'azione di exchange cancel. Annulla gli ordini in attesa dell'utente in base all'oid.
• cancelAll — { "cancelAll": { "assets": null } } annulla tutti gli ordini in attesa e i TWAP dell'utente su questo venue. { "cancelAll": { "assets": [<asset>, ...] } } annulla solo gli ordini in attesa e i TWAP dell'utente per gli asset elencati. L'elenco deve contenere da 1 a 10 voci.
• order — { "order": { "orders": [...], "grouping": "na" } }, il payload standard dell'azione di exchange order. Ogni ordine deve essere reduce-only ("r": true).
• sendAsset — { "sendAsset": { "destination": "0xUSER_C", "amount": "100.0" } }. Trasferisce il collaterale dall'account dell'utente intermediato sul DEX all'account di destination sullo stesso venue.

Oracle

I venue HIP-3* aggiornano i prezzi con l'azione di deploy con operazione star setOracle. oraclePxs è un elenco (ordinato per chiave) di asset e prezzi oracle spot. I prezzi dei perpetual esterni e i mark price sono derivati on-chain sulla base dei prezzi oracle spot forniti dal deployer.

• Prezzi dei perpetual esterni sono derivati dall'asset del dex principale con lo stesso nome, con la denominazione convertita in USDC. Ad esempio, test:BTC utilizza il prezzo del perpetual esterno di BTC.
• Mark price sono calcolati on-chain come mediana di:

1. il prezzo dell'oracle rettificato da una media mobile esponenziale del premio del prezzo medio rispetto al prezzo dell'oracle,
2. il prezzo del perpetual esterno, e
3. il mark price locale (mediana(best bid, best ask, ultimo prezzo di negoziazione)).

Se sono disponibili solo due di questi prezzi, viene aggiunta come terzo input una media mobile esponenziale del mark price locale.

Autorizzazioni

Per HIP-3*, SubDeployerInput.variant accetta anche gli oggetti mostrati di seguito.

Ogni autorizzazione copre esclusivamente la propria operazione. Ad esempio, l'autorizzazione modifyApproval non consente modifyBackstopLiquidatorApproval, setReduceOnly o sendAsset. Analogamente, la normale autorizzazione "setOracle", inclusa quella concessa a oracleUpdater, non consente l'operazione star setOracle.

Stato star dell'utente

La richiesta info userStarState restituisce lo stato di approvazione di un utente su ogni venue HIP-3* in cui l'utente è stato approvato. Lo stato è null sui venue che hanno successivamente revocato l'approvazione dell'utente.

{ "type": "userStarState", "user": "0xUSER_A" }

{
  "dexToState": {
    "test": {
      "isReduceOnly": false,
      "isBackstopLiquidatorDepositAllowed": true
    },
    "demo": null
  }
}