@metamask-previews/perps-controller 17.3.0-preview-d3f9964be → 17.4.0-preview-aecbce4ff

package/dist/services/RewardsIntegrationService.js

@@ -1,13 +1,16 @@
-import { BASIS_POINTS_DIVISOR, BUILDER_FEE_CONFIG, } from '../constants/hyperLiquidConfig.js';
-import { PERPS_CONSTANTS, SUBSCRIPTION_BENEFITS_CACHE, } from '../constants/perpsConfig.js';
+import { BASIS_POINTS_DIVISOR, BUILDER_FEE_CONFIG, HYPERLIQUID_MAINNET_CHAIN_ID, HYPERLIQUID_TESTNET_CHAIN_ID, } from '../constants/hyperLiquidConfig.js';
+import { PERPS_CONSTANTS, SUBSCRIPTION_BENEFITS_CACHE, SUBSCRIPTION_FEE_WAIVER_FLAG, } from '../constants/perpsConfig.js';
 import { getSelectedEvmAccountFromMessenger } from '../utils/accountUtils.js';
 import { ensureError } from '../utils/errorUtils.js';
 import { formatAccountToCaipAccountId } from '../utils/rewardsUtils.js';
+import { quantizeBuilderFeeTenthsBps, resolveSubscriptionWaiverRate, } from '../utils/subscriptionFeeWaiver.js';
 /**
  * Default MetaMask builder fee, in basis points.
  * This is the fee every user pays when no cheaper source applies.
  */
 const DEFAULT_FEE_BIPS = BUILDER_FEE_CONFIG.MaxFeeDecimal * BASIS_POINTS_DIVISOR;
+/** `SubscriptionController` reports allowances in micro-USD. */
+const MICRO_USD_PER_USD = 1_000_000;
 /**
  * RewardsIntegrationService
  *
@@ -57,6 +60,19 @@ export class RewardsIntegrationService {
      * a sign-out or profile switch.
      */
     #benefitsEpoch = 0;
+    /**
+     * CAIP-10 addresses already registered with the subscription profile this
+     * session, so preview does not re-send the same registration on every
+     * keystroke. Cleared on account switch and on cache invalidation.
+     */
+    #registeredTradingAddresses = new Set();
+    /**
+     * Whether `SubscriptionController:getBenefits` has ever answered on this
+     * messenger. Action registration can be delegated, in which case it does not
+     * appear in `getRegisteredActionTypes`, so an answered call is the only
+     * reliable proof that the messenger route is available.
+     */
+    #messengerBenefitsAnswered = false;
     /**
      * Create a new RewardsIntegrationService instance
      *
@@ -87,10 +103,11 @@ export class RewardsIntegrationService {
      * Calculate user fee discount from the unified fee resolver.
      * Returns discount in basis points (e.g., 6500 = 65% discount)
      *
+     * @param orderNotionalUsd - Order notional (USD), when the caller knows it.
      * @returns The fee discount in basis points, or undefined if no source resolved.
      */
-    async calculateUserFeeDiscount() {
-        const resolution = await this.resolveFee();
+    async calculateUserFeeDiscount(orderNotionalUsd) {
+        const resolution = await this.resolveFee(orderNotionalUsd);
         return resolution.discountBips;
     }
     /**
@@ -100,9 +117,22 @@ export class RewardsIntegrationService {
      * unresolved cached source simply drops out of the comparison, so the worst
      * case is the default fee rather than an error or an over-granted waiver.
      *
+     * The subscription source contributes an effective rate rather than a flat
+     * zero (ADR 0064): the allowance may cover only part of the order, and the
+     * blend that results has to be able to lose to a deeper VIP or season
+     * discount. Passing the order notional is what makes that blend possible.
+     *
+     * Without a notional the outcome depends on whether the backend bounded the
+     * allowance. An unbounded allowance still resolves to the full waiver — there
+     * is no cap to over-consume. A *bounded* one is withheld entirely rather than
+     * quoted as a full waiver, because charging nothing on an order of unknown
+     * size would silently spend the cap; such a caller gets the next-lowest
+     * source instead.
+     *
+     * @param orderNotionalUsd - Order notional (USD), when the caller knows it.
      * @returns The winning fee, its source, and the subscription gate outcome.
      */
-    async resolveFee() {
+    async resolveFee(orderNotionalUsd) {
         const rewardsDiscountBips = await this.#calculateRewardsDiscount();
         // Pure cache read: subscription benefits must never start a network request
         // while an order is being prepared for signing.
@@ -118,10 +148,39 @@ export class RewardsIntegrationService {
                 source = 'rewards';
             }
         }
-        // Nothing can undercut a waived fee, so the gate passing always wins.
-        if (subscription.eligible) {
-            feeBips = 0;
+        const waiver = resolveSubscriptionWaiverRate({
+            status: subscription,
+            maxFeeBips: DEFAULT_FEE_BIPS,
+            orderNotionalUsd,
+        });
+        let subscriptionWaiverKind;
+        let subscriptionCoveredNotionalUsd;
+        // The waiver competes like any other source. A full waiver still wins on
+        // `<=`, but a partial blend only wins when it is genuinely cheaper than the
+        // rewards discount — the ADR's requirement that subscription be able to
+        // lose.
+        //
+        // Compared *after* venue quantization, because that is the fee the order
+        // pays. The builder fee is submitted in integer tenths of a basis point, so
+        // a blend like 9.9999 bips is cheaper than the 10-bip default in arithmetic
+        // and identical to it on the wire. Selecting subscription on the raw number
+        // would label such an order `source: 'subscription'` with a 0-bip discount
+        // while it pays full price, and would disagree with the cloid marker, which
+        // already gates on the quantized fee.
+        const toTenthsBps = (bips) => quantizeBuilderFeeTenthsBps(Math.round((1 - bips / DEFAULT_FEE_BIPS) * BASIS_POINTS_DIVISOR));
+        // Subscription must be strictly cheaper on the wire to claim the order. A
+        // tie buys the user nothing — the same rate is already available from the
+        // source that won — while claiming it marks the cloid and spends the
+        // remaining allowance, so a tie is left to the other source. That holds at
+        // any rate, including a rewards discount that already reaches 0 bips.
+        const waiverSurvivesQuantization = toTenthsBps(waiver.feeBips) < toTenthsBps(feeBips);
+        if (waiver.applies &&
+            waiver.feeBips <= feeBips &&
+            waiverSurvivesQuantization) {
+            feeBips = waiver.feeBips;
             source = 'subscription';
+            subscriptionWaiverKind = waiver.kind === 'partial' ? 'partial' : 'full';
+            subscriptionCoveredNotionalUsd = waiver.coveredNotionalUsd;
         }
         const discountBips = source === 'default'
             ? undefined
@@ -132,10 +191,20 @@ export class RewardsIntegrationService {
             discountBips,
             defaultFeeBips: DEFAULT_FEE_BIPS,
             rewardsDiscountBips,
+            orderNotionalUsd,
             subscriptionEligible: subscription.eligible,
             subscriptionReason: subscription.reason,
+            subscriptionWaiverKind,
+            subscriptionCoveredNotionalUsd,
         });
-        return { feeBips, discountBips, source, subscription };
+        return {
+            feeBips,
+            discountBips,
+            source,
+            subscription,
+            subscriptionWaiverKind,
+            subscriptionCoveredNotionalUsd,
+        };
     }
     /**
      * Read the subscription fee-waiver gate from the cached benefits snapshot.
@@ -146,7 +215,14 @@ export class RewardsIntegrationService {
      * @returns Whether the waiver applies, why, and the remaining notional.
      */
     getSubscriptionFeeWaiverStatus() {
-        if (!this.#deps.subscription) {
+        if (!this.#hasSubscriptionSource()) {
+            return { eligible: false, reason: 'no-source' };
+        }
+        // ADR 0064 Milestone 8: the subscription source has to be killable on its
+        // own. Reported as `no-source` so a disabled flag is indistinguishable from
+        // an unwired client downstream — both mean "subscription contributes
+        // nothing", and neither touches rewards or the default fee.
+        if (!this.#isSubscriptionFeeWaiverEnabled()) {
             return { eligible: false, reason: 'no-source' };
         }
         const now = Date.now();
@@ -162,6 +238,56 @@ export class RewardsIntegrationService {
         }
         return evaluateFeeWaiverGate(snapshot.benefits);
     }
+    /**
+     * Whether this client has any way to read subscription benefits.
+     *
+     * Either wiring counts: a registered `SubscriptionController:getBenefits`
+     * action (the ADR 0064 target) or the legacy injected `subscription` callback.
+     * Requiring the injected one would make the messenger path unreachable on
+     * exactly the configuration it was added for, so the messenger is probed by
+     * asking whether an action handler exists rather than by calling it — this
+     * runs on the synchronous status read and must not start work.
+     *
+     * @returns True when benefits can be read by some route.
+     */
+    #hasSubscriptionSource() {
+        if (this.#deps.subscription || this.#messengerBenefitsAnswered) {
+            return true;
+        }
+        try {
+            // `getRegisteredActionTypes` reports this messenger's own registrations.
+            // A delegated action does not appear there, which is why it is only a
+            // positive signal — `refreshSubscriptionBenefits` still attempts the call
+            // regardless, and an answer sets `#messengerBenefitsAnswered` above.
+            return this.#messenger
+                .getRegisteredActionTypes()
+                .includes('SubscriptionController:getBenefits');
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Whether the subscription fee-waiver source is enabled remotely.
+     *
+     * Fails open: an absent flag, a malformed value, or an unreachable flag
+     * controller all read as enabled, because silently dropping a benefit the
+     * user pays for is worse than serving it one release too long. The kill
+     * switch is an explicit `false`.
+     *
+     * @returns True unless the remote flag explicitly disables the source.
+     */
+    #isSubscriptionFeeWaiverEnabled() {
+        try {
+            const { remoteFeatureFlags } = this.#messenger.call('RemoteFeatureFlagController:getState');
+            const flag = remoteFeatureFlags?.[SUBSCRIPTION_FEE_WAIVER_FLAG];
+            return flag !== false;
+        }
+        catch {
+            // No flag controller registered, or the read threw: keep the source.
+            return true;
+        }
+    }
     /**
      * Refresh the cached subscription benefits snapshot.
      *
@@ -172,10 +298,10 @@ export class RewardsIntegrationService {
      * @returns A promise that settles when the refresh completes.
      */
     async refreshSubscriptionBenefits() {
-        const source = this.#deps.subscription;
-        if (!source) {
-            return;
-        }
+        // Deliberately not gated on `#hasSubscriptionSource`: a delegated action is
+        // invisible to `getRegisteredActionTypes`, so the first call is what proves
+        // it is reachable. A client with no source at all reads `null` here, which
+        // costs one no-op call per freshness window and leaves the gate closed.
         if (this.#benefitsRefresh) {
             await this.#benefitsRefresh;
             return;
@@ -189,7 +315,7 @@ export class RewardsIntegrationService {
             sinceAttempt < SUBSCRIPTION_BENEFITS_CACHE.FreshMs) {
             return;
         }
-        const refresh = this.#readSubscriptionBenefits(source);
+        const refresh = this.#readSubscriptionBenefits();
         this.#benefitsRefresh = refresh;
         // `finally` always defers, so this never clears the handle we just set.
         refresh
@@ -221,18 +347,19 @@ export class RewardsIntegrationService {
         // fetching for the new identity. Its `finally` guard compares against the
         // current handle, so it will not clear whatever replaces it here.
         this.#benefitsRefresh = undefined;
+        // The identity behind the registration changed too, so the new one has to
+        // announce itself rather than inherit the previous profile's registration.
+        this.#registeredTradingAddresses.clear();
         this.#deps.debugLogger.log('RewardsIntegrationService: Subscription benefits cache invalidated');
     }
     /**
      * Perform one benefits read and store it, keeping the previous snapshot on
      * error. Never rejects, so callers cannot produce an unhandled rejection.
-     *
-     * @param source - The injected subscription benefits source.
      */
-    async #readSubscriptionBenefits(source) {
+    async #readSubscriptionBenefits() {
         const epoch = this.#benefitsEpoch;
         try {
-            const benefits = await source.getPerpsBenefits();
+            const benefits = await this.#getPerpsBenefits();
             if (epoch !== this.#benefitsEpoch) {
                 // Invalidated while this read was in flight: it belongs to a previous
                 // identity, so discarding it is the only safe outcome.
@@ -268,6 +395,183 @@ export class RewardsIntegrationService {
             }
         }
     }
+    /**
+     * Read subscription benefits, preferring the messenger over the DI callback.
+     *
+     * ADR 0064 moves hydration onto `SubscriptionController`. The messenger is
+     * tried first and the injected `subscription` dependency is only a fallback,
+     * so a client that ships `SubscriptionController` without the legacy callback
+     * hydrates normally — that configuration is the ADR's target, not an edge
+     * case. A client with neither gets `null`, which reads as "no subscription".
+     *
+     * @returns The benefits payload, or null when there is none to report.
+     */
+    async #getPerpsBenefits() {
+        let pending;
+        try {
+            // Called without awaiting so the fallback stays synchronous when no
+            // handler is registered: the DI read must start in the same tick, or a
+            // caller that inspects the in-flight state sees an idle service.
+            const result = this.#messenger.call('SubscriptionController:getBenefits');
+            // `undefined` means nothing handled the action, which is the fallback
+            // case rather than an answer.
+            if (result !== undefined) {
+                this.#messengerBenefitsAnswered = true;
+                pending = Promise.resolve(result).then(adaptSubscriptionBenefits);
+            }
+        }
+        catch (error) {
+            // A handler that has answered before exists, so a synchronous throw is a
+            // real failure rather than an unregistered action. Treating it as the
+            // latter would fall through to `null` and erase a valid cached snapshot,
+            // exactly as an asynchronous rejection would.
+            if (isNotSubscribedRejection(error)) {
+                // Definitive "not entitled", even thrown synchronously.
+                return null;
+            }
+            // An unregistered action throws a recognisable "no handler" error; any
+            // other synchronous throw came from a handler that exists and failed, so
+            // it must not be mistaken for an absent action and cached as `null` —
+            // including on the very first call, before one has ever answered.
+            if (!isUnregisteredActionError(error) && !this.#deps.subscription) {
+                throw error;
+            }
+            // Otherwise: unregistered action, or a throw with a DI source to fall
+            // back to.
+        }
+        const fallback = this.#deps.subscription;
+        if (pending) {
+            try {
+                return await pending;
+            }
+            catch (error) {
+                if (isNotSubscribedRejection(error)) {
+                    // A definitive answer, not a failed read: the profile is not
+                    // entitled. Returning `null` replaces the cached snapshot, which is
+                    // the point — preserving it would keep granting the waiver for the
+                    // rest of the staleness window after entitlement ended.
+                    return null;
+                }
+                if (!fallback) {
+                    // Nothing else can answer, so this rejection is the whole result.
+                    // Returning `null` here would be stored as a successful "no
+                    // subscription" snapshot and silently erase a valid cached one; let
+                    // it reach the refresh handler, which keeps the previous snapshot.
+                    throw error;
+                }
+                // A registered handler that rejects still falls back to the injected
+                // source rather than erasing the cached snapshot.
+            }
+        }
+        if (!fallback) {
+            // No handler answered and no injected source: genuinely nothing to
+            // report, which is a real `null` rather than a swallowed failure.
+            return null;
+        }
+        return await fallback.getPerpsBenefits();
+    }
+    /**
+     * Register the current HyperLiquid trading address with the subscription
+     * profile, so a later fill decoded off the HL fan-out can be attributed.
+     *
+     * ADR 0064 calls for this at preview time and again whenever the selected
+     * account changes. Registration is idempotent backend-side and deliberately
+     * never throws: it is observability plumbing, and a failure here must not
+     * block a fee preview.
+     *
+     * New clients may route this through the structural
+     * `SubscriptionController:registerAddress` action. Older clients continue to
+     * use the injected `subscription` hook as a compatibility fallback.
+     *
+     * @param address - The EVM trading address to register.
+     * @param options - Registration options.
+     * @param options.isTestnet - Whether the caller is trading against the
+     * HyperLiquid testnet. Selects which HyperLiquid chain the CAIP-10 names;
+     * defaults to mainnet.
+     * @returns A promise that resolves once the attempt settles.
+     */
+    async registerTradingAddress(address, options) {
+        try {
+            // HyperLiquid's own chain, not the wallet's selected network. The address
+            // is being announced so a fill decoded off the HyperLiquid fan-out can be
+            // matched back to a profile, and that fill names `eip155:999` /
+            // `eip155:998`. Registering under whatever network the wallet happened to
+            // have selected produces an identifier no fill will ever match.
+            const chainId = options?.isTestnet
+                ? HYPERLIQUID_TESTNET_CHAIN_ID
+                : HYPERLIQUID_MAINNET_CHAIN_ID;
+            const caipAccountId = formatAccountToCaipAccountId(address, chainId, this.#deps.logger);
+            if (!caipAccountId) {
+                return;
+            }
+            // Skip the round trip when this address was already registered for this
+            // session: preview runs on every keystroke in the order form.
+            if (this.#registeredTradingAddresses.has(caipAccountId)) {
+                return;
+            }
+            // Capture the identity before invoking either integration. If profile
+            // invalidation happens while the handler is pending, its completion must
+            // not repopulate the registration cache for the old profile.
+            const epoch = this.#benefitsEpoch;
+            // New clients can route registration through SubscriptionController.
+            // Older clients do not expose this action and continue using the
+            // injected hook below.
+            let registration;
+            try {
+                const result = this.#messenger.call('SubscriptionController:registerAddress', caipAccountId);
+                if (result !== undefined) {
+                    registration = Promise.resolve(result);
+                }
+            }
+            catch (error) {
+                if (!isUnregisteredActionError(error) && !this.#deps.subscription) {
+                    throw error;
+                }
+            }
+            if (!registration) {
+                const source = this.#deps.subscription;
+                if (!source?.registerTradingAddress) {
+                    // Visible rather than silent: a client wired only to benefits has no
+                    // way to register, and a missing registration is otherwise
+                    // indetectable until fills arrive unattributed.
+                    this.#deps.debugLogger.log('RewardsIntegrationService: No trading-address registration hook wired; fills will be unattributed', { address });
+                    return;
+                }
+                registration = source.registerTradingAddress(caipAccountId);
+            }
+            // Fence the completion against an invalidation that lands while this
+            // registration is in flight. `invalidateSubscriptionBenefits` clears the
+            // registered set because the profile behind it changed; writing back
+            // afterwards would re-add an address registered for the *previous*
+            // profile, and the new profile would then skip its own registration and
+            // leave its fills unattributable.
+            await registration;
+            if (epoch !== this.#benefitsEpoch) {
+                this.#deps.debugLogger.log('RewardsIntegrationService: Trading address registration superseded', { caipAccountId });
+                return;
+            }
+            this.#registeredTradingAddresses.add(caipAccountId);
+            this.#deps.debugLogger.log('RewardsIntegrationService: Trading address registered', { caipAccountId });
+        }
+        catch (error) {
+            // An offline client or a backend refusal both land here. Neither is a
+            // reason to fail a fee preview.
+            this.#deps.debugLogger.log('RewardsIntegrationService: Trading address registration skipped', {
+                address,
+                error: ensureError(error, 'RewardsIntegrationService.registerTradingAddress').message,
+            });
+        }
+    }
+    /**
+     * Forget which trading addresses were registered this session.
+     *
+     * Called when the selected account changes, so the next preview re-sends the
+     * registration for the new address rather than assuming the previous one
+     * still stands.
+     */
+    resetRegisteredTradingAddresses() {
+        this.#registeredTradingAddresses.clear();
+    }
     /**
      * Resolve the rewards (VIP + season) discount for the selected account.
      *
@@ -342,6 +646,83 @@ export class RewardsIntegrationService {
         }
     }
 }
+/**
+ * Whether a messenger call failed because no handler is registered.
+ *
+ * `Messenger.call` reports an unregistered action with a distinctive message.
+ * Anything else thrown synchronously came from a handler that does exist, and
+ * conflating the two would cache a real failure as "no subscription".
+ *
+ * @param error - The error thrown by the messenger call.
+ * @returns True when the action has no registered handler.
+ */
+function isUnregisteredActionError(error) {
+    return (error instanceof Error &&
+        /handler.*not.*registered|no.*handler.*registered|A handler for .* has not been registered/iu.test(error.message));
+}
+/**
+ * Whether a benefits rejection definitively means "this profile is not
+ * entitled", as opposed to "the read failed".
+ *
+ * `SubscriptionController.getBenefits` throws `UserNotSubscribed` when the
+ * subscription is inactive or the response reports ineligibility, and clears
+ * its own benefits state on that path. Treating it as a transport failure would
+ * keep serving a cached waiver for the rest of the staleness window — up to ten
+ * minutes of free trading after entitlement ended — so it is converted to a
+ * real `null` answer instead.
+ *
+ * Matched on the message because the controller throws a plain `Error`; any
+ * other failure stays a failure and preserves the cached snapshot.
+ *
+ * @param error - The rejection from the benefits read.
+ * @returns True when the rejection means the profile is not entitled.
+ */
+function isNotSubscribedRejection(error) {
+    return (error instanceof Error && error.message.includes('User is not subscribed'));
+}
+/**
+ * Convert `SubscriptionController`'s benefits response into the shape the
+ * waiver gate reads.
+ *
+ * The controller reports allowances in **micro-USD** (`remainingMicroUsd`) and
+ * carries no `status`/`entitled` fields: eligibility is the response's own
+ * `eligible` flag, and the perps product block holds the cap. Converting once,
+ * here at the boundary, keeps the gate and the blended-rate formula working in
+ * whole USD.
+ *
+ * A `remainingMicroUsd` of `null` means the backend reported no bound, which
+ * stays an unbounded allowance rather than a spent one.
+ *
+ * @param response - The controller's benefits response.
+ * @returns The internal benefits shape, or null when nothing is entitled.
+ */
+function adaptSubscriptionBenefits(response) {
+    if (!response) {
+        return null;
+    }
+    const perps = response.products?.perps;
+    // `products.perps` is always present on the response, so its existence proves
+    // nothing. Entitlement is the response-level `eligible` flag plus positive
+    // evidence from the perps block itself: a builder fee rate to apply, or a
+    // reported allowance to spend. A block carrying neither describes a profile
+    // with no perps benefit, whatever the other products say.
+    const hasPerpsBenefit = Boolean(perps &&
+        (perps.builderFeeBips !== null ||
+            perps.remainingMicroUsd !== null ||
+            perps.capMicroUsd !== undefined));
+    return {
+        status: response.eligible ? 'active' : 'inactive',
+        perpsFeeWaiver: {
+            entitled: response.eligible && hasPerpsBenefit,
+            usage: perps?.exhausted ? 'exhausted' : 'available',
+            exhausted: perps?.exhausted,
+            remainingNotionalUsd: perps?.remainingMicroUsd === null ||
+                perps?.remainingMicroUsd === undefined
+                ? undefined
+                : perps.remainingMicroUsd / MICRO_USD_PER_USD,
+        },
+    };
+}
 /**
  * Evaluate the perps fee-waiver eligibility gate against a benefits snapshot.
  *