HIP-3 디플로이어 작업

빌더가 배포한 무기한 선물(펍) DEX를 배포하고 운영하는 API에는 다음 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>;
};

다음 예시에서 feeScale는 SetDeployerFees의 scale 필드입니다. 양수인 일반 사용자 수수료 1단위와 비정렬 담보(x = y = 1)를 가정합니다. userFeeToProtocol와 userFeeToDeployer는 사용자에게 청구되는 결과 수수료 단위입니다.

펍 배포 경매 상태를 조회하는 방법은 https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/info-endpoint/perpetuals#retrieve-information-about-the-perp-deploy-auction를 참고하세요.

오픈 인터레스트 한도

빌더가 배포한 펍 시장에는 두 가지 유형의 오픈 인터레스트 한도가 적용됩니다: 명목(포지션 크기 절댓값에 마크 가격을 곱한 값의 합)과 크기(포지션 크기 절댓값의 합)입니다.

명목 오픈 인터레스트 한도는 DEX 내 모든 자산을 합산한 총 오픈 인터레스트에 대해서와 자산별로 각각 적용됩니다. 펍 디플로이어는 자산별 커스텀 오픈 인터레스트 한도를 설정할 수 있으며, 이는 https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/hip-3-deployer-actions에 문서화되어 있습니다.

크기 기준 오픈 인터레스트 한도는 자산별로만 적용됩니다. 크기 기준 오픈 인터레스트 한도는 현재 자산당 1B로 고정되어 있으므로, 합리적인 기본값은 초기 마크 가격에서 최소 크기 증분이 $1–10이 되도록 szDecimals를 설정하는 것입니다.

백스톱 청산인

백스톱 청산인 주소는 0x4000000000000000000000000000000000000000 + {dex_index}입니다. 예를 들어 첫 번째 HIP-3 DEX의 백스톱 청산인 주소는 0x4000000000000000000000000000000000000001입니다.

노드 사용자 계정 요약

노드 플래그 --write-user-account-summaries <dex>는 지정된 HIP-3 DEX의 계정 요약을 ~/hl/data/dex_user_account_summaries/hourly/<date>/<hour> 경로의 시간별 파일로 기록합니다. 여기서 date는 YYYYMMDD입니다. 각 줄은 JSON 배열 [time, messages]이며, time은 블록 시간이고 messages는 DEX의 모든 사용자에 대한 단일 스냅샷 또는 사용자별 diff 목록입니다:

["2026-09-24T09:00:00.123", [{ "Snapshot": { "0xUSER_A": { "a": "100.0", "b": "90.0" } } }]]
["2026-09-24T09:00:03.456", [{ "Diff": ["0xUSER_A", { "a": "105.0", "b": "90.0" }] }]]

a는 계정 가치이고 b는 balance = accountValue - unrealizedPnl이며, 둘 다 해당 venue의 담보 토큰으로 표기됩니다. 각 파일의 첫 줄, 그리고 노드 시작 후 처음 기록되는 줄은 스냅샷입니다. 나머지 줄에는 요약이 변경된 사용자의 diff가 담깁니다. venue의 오라클 업데이트가 있을 때는 해당하는 모든 사용자가 포함되고, 그 외에는 체결, 청산, 펀딩 지급, venue 입출금 이체에 관련된 사용자만 포함됩니다.

HIP-3* (테스트넷 전용)

스타 액션

HIP-3 venue는 생성 시점에 PerpDexSchemaInput에 isStar: true를 설정하여 HIP-3*로 지정될 수 있습니다. 이 선택적 불리언의 기본값은 false입니다. HIP-3*는 HIP-3 사양에 더해 허용 리스트(allow-list)와 프록시 사용자 액션 등 여러 기능을 활성화합니다.

작업

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 — 사용자 주소와 해당 사용자에게 적용되는 프록시 작업 하나의 쌍입니다.
• setOracle — 아래 오라클 섹션에 설명된 대로 오라클 가격을 업데이트합니다.

프록시 작업

• modifyApproval — { "modifyApproval": true }는 사용자를 허용 리스트에 추가하고, false는 사용자를 제거하고 플래그를 지웁니다. 승인되지 않은 사용자를 제거하는 것은 무작동(no-op)입니다. 이미 승인된 사용자를 다시 승인하는 것도 무작동이며 사용자의 플래그가 유지됩니다. 제거되었다가 다시 승인된 사용자는 기본 플래그로 시작합니다.
• modifyBackstopLiquidatorApproval — { "modifyBackstopLiquidatorApproval": true }는 사용자가 hip3LiquidatorTransfer를 통해 venue의 백스톱 청산인에 입금하고 출금할 수 있도록 하며, false는 이를 취소합니다. 사용자는 이미 modifyApproval을 통해 승인되어 있어야 합니다.
• setReduceOnly — { "setReduceOnly": true }는 승인된 사용자가 해당 venue에서 수행할 수 있는 작업을 포지션 축소로 제한합니다. 사용자는 축소 전용 주문과 TWAP만 제출하고, 기존 주문을 축소 전용 주문으로 수정하고, 취소할 수 있습니다. { "setReduceOnly": false }는 전체 거래 권한을 복원합니다.
• cancel — { "cancel": { "cancels": [{ "a": <asset>, "o": <oid> }] } }, 표준 cancel 거래소 액션 페이로드입니다. oid를 기준으로 사용자의 대기 주문을 취소합니다.
• cancelAll — { "cancelAll": { "assets": null } }는 이 venue에서 사용자의 모든 대기 주문과 TWAP를 취소합니다. { "cancelAll": { "assets": [<asset>, ...] } }는 나열된 자산에 대한 대기 주문과 TWAP만 취소합니다. 리스트는 1–10개 항목을 포함해야 합니다.
• order — { "order": { "orders": [...], "grouping": "na" } }, 표준 order 거래소 액션 페이로드입니다. 모든 주문은 축소 전용("r": true)이어야 합니다.
• sendAsset — { "sendAsset": { "destination": "0xUSER_C", "amount": "100.0" } }. DEX에 있는 프록시 대상 사용자 계정의 담보를 같은 venue의 destination 계정으로 이동합니다.

오라클

HIP-3* venue는 setOracle 스타 작업 배포 액션으로 가격을 업데이트합니다. oraclePxs는 자산과 스팟 오라클 가격의 (키 기준 정렬된) 목록입니다. 외부 펍 가격과 마크 가격은 디플로이어가 입력한 스팟 오라클 가격을 기반으로 온체인에서 도출됩니다.

• 외부 펍 가격은 같은 이름의 메인 DEX 자산에서 도출되며, 표시 단위가 USDC로 변환됩니다. 예를 들어 test:BTC는 BTC의 외부 펍 가격을 사용합니다.
• 마크 가격은 온체인에서 다음의 중앙값으로 계산됩니다:

1. 오라클 가격에, 오라클 가격 대비 미드 가격의 프리미엄의 지수 이동 평균을 반영해 조정한 가격,
2. 외부 펍 가격,
3. 로컬 마크 가격(median(best bid, best ask, last trade price)).

이 가격 중 두 개만 사용 가능한 경우, 로컬 마크 가격의 지수 이동 평균이 세 번째 입력으로 추가됩니다.

권한

HIP-3*에서는 SubDeployerInput.variant가 아래 표의 객체들도 받습니다.

각 부여는 해당 작업만 포함합니다. 예를 들어 modifyApproval 부여는 modifyBackstopLiquidatorApproval, setReduceOnly, sendAsset을 허용하지 않습니다. 마찬가지로, oracleUpdater에게 부여된 것을 포함한 일반 "setOracle" 부여는 setOracle 스타 작업을 허용하지 않습니다.

사용자 스타 상태

userStarState 정보 요청은 사용자가 승인된 모든 HIP-3* venue에서 해당 사용자의 승인 상태를 반환합니다. 이후 사용자의 승인을 제거한 venue에서는 상태가 null입니다.

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

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