perp-cli 0.12.17 → 0.14.0

package/dist/exchanges/builder-fee.d.ts

@@ -0,0 +1,254 @@
+/**
+ * Builder fees — one uniform, default-OFF mechanism for every venue.
+ *
+ * A builder fee is an extra per-order fee the venue pays to a third-party "builder"
+ * (Hyperliquid builder codes, Pacifica builder program, Aster builder, Ondo builder
+ * codes). It is charged to the USER, so perp-cli never attaches one unless:
+ *   1. `settings.builder.<venue>` is set explicitly by the user (absent = off — there
+ *      is no shipped default and no env var), and
+ *   2. the venue approval the fee needs is CONFIRMED (venue status read, cached per
+ *      process for BUILDER_APPROVAL_TTL_MS; a builder-related order rejection drops the
+ *      cached read). Approval-free venues (Ondo) are confirmed by (1) alone.
+ * A builder-related order rejection is returned to the caller with remediation
+ * (--no-builder / re-approve) and is NEVER retried — re-sending is a new order.
+ * An order whose approval is missing / unknown is sent WITHOUT the fee and says so in
+ * `execution.notes` (and once on stderr) — the fee is the builder's, never a reason to
+ * fail or silently change the user's order. `--no-builder` disables it per command.
+ *
+ * Per-venue facts (official docs, checked 2026-10-02):
+ * - hyperliquid  https://hyperliquid.gitbook.io/hyperliquid-docs/trading/builder-codes
+ *     ApproveBuilderFee signed by the MAIN wallet (an agent cannot sign it); order action
+ *     `builder: { b: <address>, f: <tenths of a bp> }`; max 0.1% perps / 1% spot; status
+ *     info `{ type: "maxBuilderFee", user, builder }`. HIP-3 dexes are not covered by the
+ *     docs → never attached there.
+ * - pacifica     https://pacifica.gitbook.io/docs/programs/builder-program.md
+ *     approve_builder_code { builder_code, max_fee_rate } signed by the account; per-order
+ *     `builder_code` on create_market / create / stop/create / positions/tpsl. TWAP
+ *     (create_twap_order) does not document builder_code → never sent there.
+ *     The builder sets its own fee_rate; the user's approved max_fee_rate caps it, so the
+ *     code is attached only while the approved max_fee_rate ≤ the configured feeBps (the
+ *     user's consent). The venue documents no ceiling → perp-cli caps the consent at 10
+ *     bps. Spot rejects it (err 108).
+ * - aster        https://asterdex.github.io/aster-api-website/asterCode/integration-flow/
+ *     + asterdex/api-docs demo/aster-code.py: approveBuilder { builder, maxFeeRate ≤ 0.001 }
+ *     master-signed; orders carry `builder` + `feeRate` (decimal) signed by the API wallet;
+ *     list GET /fapi/v3/builder, revoke DELETE /fapi/v3/builder (DelBuilder). The testnet
+ *     API documents no approveBuilder → testnet off.
+ * - ondo         https://docs.ondoperps.xyz/api-reference/integration_guide (+ rest-spec)
+ *     no user approval; per-order `builderCode: { code, feeRateBpsFractional }` on
+ *     POST /v1/perps/orders and POST /v1/perps/stop_order (stops do NOT inherit it); cap
+ *     10 bps; sandbox uses the same API.
+ * - qfex         https://docs.qfex.com/qfex/builder-code
+ *     fee SHARE, not an extra fee: the trader pays the normal venue fee and the venue credits
+ *     part of it to the builder (feeKind "share", feeBps null). No user approval. The code
+ *     (UUID) rides on the Trade WebSocket auth (`params.builder_code`) for the life of the
+ *     connection — never per order; an unknown code is not an error, so attribution is not
+ *     confirmable from the trader side. Prod codes mean nothing on UAT → testnet off.
+ * - lighter / lighter-rh: unsupported — see UNSUPPORTED below.
+ * - arcus: unsupported — see UNSUPPORTED below.
+ */
+import { PerpError } from "../errors.js";
+import type { Network, VenueId } from "./venue-types.js";
+export type BuilderFeeKind = "exact" | "max" | "share";
+export interface BuilderFeeCapability {
+    /** "master" = the owner wallet signs a one-time approval; "none" = no approval exists. */
+    approval: "master" | "none";
+    /** What identifies the builder in settings.builder.<venue>. */
+    identity: "address" | "code";
+    /** Largest fee (bps) a perp order may carry; null = feeKind "share" (no user-paid fee exists). */
+    perpCapBps: number | null;
+    /** Largest fee (bps) the venue allows on spot; null = spot does not take a builder fee. Spot orders never carry one in perp-cli. */
+    spotCapBps: number | null;
+    /** false = HIP-3 dexes never carry the fee (Hyperliquid); null = not applicable. */
+    hip3: false | null;
+    /** false = the venue's testnet has no builder flow → never attached on testnet. */
+    testnet: boolean;
+    /** Smallest fee increment (bps) the venue can express; null = feeKind "share". */
+    feeStepBps: number | null;
+    /**
+     * "exact" = the order carries this fee; "max" = the user approves a ceiling, the builder sets
+     * the actual rate (Pacifica); "share" = the venue shares its own fee with the builder — the
+     * user pays the normal fee and nothing extra (QFEX), so there is no feeBps.
+     */
+    feeKind: BuilderFeeKind;
+    /** Official doc the facts were taken from. */
+    docs: string;
+}
+export declare const BUILDER_FEE_CAPABILITIES: {
+    readonly [K in VenueId]: BuilderFeeCapability | null;
+};
+/** Why a venue has no builder-fee support (shown in CAPABILITY_UNSUPPORTED). */
+export declare const BUILDER_FEE_UNSUPPORTED: {
+    readonly [K in VenueId]?: string;
+};
+export declare function builderFeeUnsupported(venue: VenueId): PerpError;
+export declare function builderFeeVenues(): VenueId[];
+/** Capability of a venue, or CAPABILITY_UNSUPPORTED. */
+export declare function requireBuilderCapability(venue: VenueId): BuilderFeeCapability;
+export interface BuilderAddressEntry {
+    address: string;
+    feeBps: number;
+}
+export interface BuilderCodeEntry {
+    code: string;
+    feeBps: number;
+}
+/** feeKind "share" (QFEX): attribution only — there is no user-paid fee, so no feeBps key. */
+export interface BuilderShareEntry {
+    code: string;
+}
+/** settings.builder — absent venue = builder fee off. Ships empty. */
+export interface BuilderSettings {
+    hyperliquid?: BuilderAddressEntry;
+    pacifica?: BuilderCodeEntry;
+    aster?: BuilderAddressEntry;
+    ondo?: BuilderCodeEntry;
+    qfex?: BuilderShareEntry;
+}
+/** A configured builder, normalized: identity = address (lowercase) or code. */
+export interface BuilderTarget {
+    venue: VenueId;
+    identity: string;
+    /** Extra fee charged to the user (bps); null = feeKind "share" (the user pays the normal venue fee only). */
+    feeBps: number | null;
+}
+/** The configured user-paid fee of an "exact" / "max" venue. A "share" target has none. */
+export declare function requireFeeBps(t: {
+    venue: VenueId;
+    feeBps: number | null;
+}): number;
+/**
+ * Validate one settings.builder.<venue> entry. Throws `invalid(problem)` — never clamps
+ * or rewrites a value. Returns the normalized target.
+ */
+export declare function parseBuilderEntry(venue: string, raw: unknown, invalid: (problem: string) => Error): BuilderTarget;
+/** Validate the whole settings.builder object (absent / null = nothing configured). */
+export declare function parseBuilderSettings(raw: unknown, invalid: (problem: string) => Error): BuilderSettings;
+/** "2.5 bps", or "fee share (no extra fee)" for a share target. */
+export declare function feeText(t: {
+    feeBps: number | null;
+}): string;
+/** The configured target for a venue, or null (off). */
+export declare function builderTargetOf(builder: BuilderSettings, venue: VenueId): BuilderTarget | null;
+export type BuilderApproval = 
+/** The venue reports an approval covering the configured fee. maxFeeBps = approved ceiling (null = venue has no approval step). */
+{
+    status: "approved";
+    maxFeeBps: number | null;
+}
+/** The venue reports no approval, or one below the configured fee (maxFeeBps = approved ceiling, null = none). */
+ | {
+    status: "notApproved";
+    maxFeeBps: number | null;
+}
+/** feeKind "max": the approved ceiling is ABOVE the configured fee — the builder could charge more than the user configured. */
+ | {
+    status: "aboveConsent";
+    maxFeeBps: number;
+}
+/** The approval could not be determined (request failed / response unreadable). */
+ | {
+    status: "unknown";
+    reason: string;
+};
+/** The fee an order actually carried (OrderExecution.builderFee). */
+export interface AppliedBuilderFee {
+    venue: VenueId;
+    /** Builder address (lowercase) or code. */
+    identity: string;
+    /** Extra fee charged to the user (bps); null = feeKind "share". */
+    feeBps: number | null;
+    /** "max" = approved ceiling; the builder's own rate applies (Pacifica). "share" = venue fee share, nothing extra. */
+    feeKind: BuilderFeeKind;
+    /** The ceiling the venue reports as approved (bps); null = the venue has no approval step. */
+    approvedMaxBps: number | null;
+}
+export interface BuilderDecision {
+    applied: AppliedBuilderFee | null;
+    /** Why a CONFIGURED fee was not attached (null when attached or not configured). */
+    note: string | null;
+}
+export declare const NO_BUILDER: BuilderDecision;
+/** How long a venue approval read is reused before it is read again. */
+export declare const BUILDER_APPROVAL_TTL_MS: number;
+/** Forget cached approval reads and stderr warnings (after approve / revoke; test hook). */
+export declare function resetBuilderApprovalCache(): void;
+/** Drop the cached approval reads of one venue + network (the next order re-reads the venue). */
+export declare function invalidateBuilderApproval(venue: VenueId, network: Network): void;
+/**
+ * Per-adapter builder-fee gate. Built only when settings.builder.<venue> is set
+ * (resolveBuilderGate) — an unconfigured venue has no gate and no notes at all.
+ */
+export declare class BuilderFeeGate {
+    readonly target: BuilderTarget;
+    readonly network: Network;
+    /** Static reason the configured fee is never attached by this adapter (--no-builder, testnet). */
+    private readonly skipReason;
+    /** Reads the venue approval for the active account; null when the venue has no approval step. */
+    private readonly readApproval;
+    /** Account the approval belongs to (master address) — part of the cache key. */
+    private readonly accountOf;
+    constructor(target: BuilderTarget, network: Network, 
+    /** Static reason the configured fee is never attached by this adapter (--no-builder, testnet). */
+    skipReason: string | null, 
+    /** Reads the venue approval for the active account; null when the venue has no approval step. */
+    readApproval: ((target: BuilderTarget) => Promise<BuilderApproval>) | null, 
+    /** Account the approval belongs to (master address) — part of the cache key. */
+    accountOf: () => string);
+    get capability(): BuilderFeeCapability;
+    /** Venue approval for the configured builder (cached for BUILDER_APPROVAL_TTL_MS). Failures → "unknown". */
+    approval(): Promise<BuilderApproval>;
+    /**
+     * Whether the next perp order carries the fee. `hip3` = the order is on a Hyperliquid
+     * HIP-3 dex. Never throws: a fee that cannot be attached becomes a note.
+     */
+    decide(opts: {
+        hip3: boolean;
+    }): Promise<BuilderDecision>;
+    private warnOnce;
+}
+/**
+ * The gate for an adapter being created, or null when settings.builder.<venue> is not
+ * set (default) or the context is read-only. The single place builder settings are
+ * resolved (adapters never read settings).
+ */
+export declare function resolveBuilderGate(venue: VenueId, ctx: {
+    network: Network;
+    noBuilder: boolean;
+    readOnly: boolean;
+}, builder: BuilderSettings, readApproval: ((target: BuilderTarget) => Promise<BuilderApproval>) | null, accountOf: () => string): BuilderFeeGate | null;
+/** Gate held by an adapter (public `builderFee` field), or null. */
+export declare function builderGateOf(adapter: unknown): BuilderFeeGate | null;
+/** Decision for an adapter's next perp order (no gate = not configured = NO_BUILDER). */
+export declare function builderDecisionOf(adapter: unknown, opts: {
+    hip3: boolean;
+}): Promise<BuilderDecision>;
+/** Fee rate as a decimal fraction string: 2.5 bps → "0.00025". */
+export declare function bpsToRate(bps: number): string;
+/** Decimal fraction (string | number) → bps, or null when unreadable. */
+export declare function rateToBps(rate: unknown): number | null;
+/** Hyperliquid `f` (tenths of a basis point). */
+export declare function hlFeeTenthsBps(bps: number): number;
+/** Hyperliquid ApproveBuilderFee maxFeeRate: a percent string ("0.01%" = 1 bp). */
+export declare function hlMaxFeeRatePercent(bps: number): string;
+/** feeKind "exact": approval verdict from the venue's approved ceiling (bps; null = no approval on record). */
+export declare function approvalFromMax(maxFeeBps: number | null, feeBps: number): BuilderApproval;
+/**
+ * feeKind "max" (Pacifica): the builder picks its own rate up to the approved ceiling, so the
+ * configured feeBps is the user's consent and the approved ceiling must not exceed it.
+ * null = no approval on record.
+ */
+export declare function approvalFromCeiling(maxFeeBps: number | null, feeBps: number): BuilderApproval;
+/**
+ * An order the venue rejected for a builder-related reason (the error text names the builder):
+ * the cached approval of that venue is dropped (the next order re-reads it) and the rejection is
+ * returned with remediation. The order is NOT retried — re-sending is a new order, so that stays
+ * the user's explicit choice. Any other error (or no gate) is returned unchanged.
+ */
+export declare function builderRejectionOf(adapter: unknown, err: unknown): unknown;
+/**
+ * Builder decision for a planned perp order on `symbol` (dry-run / preview): the same
+ * cached gate decision a live order would use. Hyperliquid resolves the asset id so a
+ * HIP-3 market reports "not attached".
+ */
+export declare function builderPlanFor(adapter: unknown, symbol: string | null): Promise<BuilderDecision>;