@reyaxyz/common 0.362.1 → 0.363.0

package/src/utils/realized-balance.ts

@@ -0,0 +1,163 @@
+import BigNumber from 'bignumber.js';
+
+/** Raw E18 position values, from either Prisma or replication. */
+export type RealizedBalancePosition = {
+  market_id: { toString(): string };
+  base: { toString(): string } | null;
+  realized_pnl: { toString(): string } | null;
+  funding_value: { toString(): string } | null;
+  base_multiplier: { toString(): string } | null;
+  adl_unwind_price: { toString(): string } | null;
+  last_price: { toString(): string } | null;
+  /** Block the stored trackers were written at; lets stale market trackers be ignored. */
+  block_number?: { toString(): string } | null;
+};
+
+export type RealizedBalanceTrackers = {
+  longTrackersFundingValue: string;
+  shortTrackersFundingValue: string;
+  longTrackersBaseMultiplier: string;
+  shortTrackersBaseMultiplier: string;
+  longTrackersAdlUnwindPrice: string;
+  shortTrackersAdlUnwindPrice: string;
+  /** Block the market trackers were observed at (optional; enables the staleness guard). */
+  blockNumber?: string | null;
+};
+
+/** Structured cause for service metrics; calculation still fails closed. */
+export class SettlementTrackerError extends Error {
+  constructor(
+    public readonly marketId: string,
+    public readonly reason: 'missing' | 'inconsistent',
+  ) {
+    super(
+      reason === 'missing'
+        ? `Missing market trackers for ${marketId}`
+        : `Inconsistent ADL trackers for ${marketId}`,
+    );
+    // common targets ES5; restore Error subclass identity after downleveling.
+    Object.setPrototypeOf(this, new.target.prototype);
+    this.name = 'SettlementTrackerError';
+  }
+}
+
+const WAD = new BigNumber('1000000000000000000');
+const integer = (value: { toString(): string } | null, field: string) => {
+  const result = new BigNumber(value?.toString() ?? NaN);
+  if (!result.isInteger()) throw new Error(`Missing or invalid ${field}`);
+  return result;
+};
+const optionalBlock = (value: { toString(): string } | null | undefined) => {
+  if (value === null || value === undefined) return undefined;
+  const result = new BigNumber(value.toString());
+  return result.isInteger() ? result : undefined;
+};
+const mulWad = (a: BigNumber, b: BigNumber) =>
+  a.times(b).dividedToIntegerBy(WAD);
+const divWad = (a: BigNumber, b: BigNumber) =>
+  a.times(WAD).dividedToIntegerBy(b);
+
+/** Mirrors perpOB updatePerpPosition, including PRBMath truncation at each step. */
+export function calculateSettledPositionPnl(
+  position: RealizedBalancePosition,
+  trackers: RealizedBalanceTrackers | undefined,
+  onGuarded?: () => void,
+): BigNumber {
+  const base = integer(position.base, 'position base');
+  const realized = integer(position.realized_pnl, 'realized PnL');
+  if (base.isZero()) return realized;
+  if (!trackers)
+    throw new SettlementTrackerError(position.market_id.toString(), 'missing');
+
+  const long = base.isPositive();
+  const funding = integer(
+    long
+      ? trackers.longTrackersFundingValue
+      : trackers.shortTrackersFundingValue,
+    'market funding',
+  );
+  const multiplier = integer(
+    long
+      ? trackers.longTrackersBaseMultiplier
+      : trackers.shortTrackersBaseMultiplier,
+    'market multiplier',
+  );
+  const unwind = integer(
+    long
+      ? trackers.longTrackersAdlUnwindPrice
+      : trackers.shortTrackersAdlUnwindPrice,
+    'market unwind price',
+  );
+  const oldMultiplier = integer(
+    position.base_multiplier,
+    'position multiplier',
+  );
+  const oldUnwind = integer(position.adl_unwind_price, 'position unwind price');
+  const oldFunding = integer(position.funding_value, 'position funding');
+  if (
+    funding.eq(oldFunding) &&
+    multiplier.eq(oldMultiplier) &&
+    unwind.eq(oldUnwind)
+  )
+    return realized;
+
+  // Market trackers older than the position's own snapshot carry no new
+  // cashflow: the stored realized PnL already settled everything up to the
+  // position's block. Off-chain tracker feeds can lag the position stream, so
+  // treat that window as "nothing accrued" instead of projecting a delta
+  // backwards (wrong-sign funding, or an ADL guard failure below).
+  const positionBlock = optionalBlock(position.block_number);
+  const trackerBlock = optionalBlock(trackers.blockNumber);
+  if (positionBlock && trackerBlock && positionBlock.gt(trackerBlock)) {
+    onGuarded?.();
+    return realized;
+  }
+
+  if (
+    oldMultiplier.lte(0) ||
+    multiplier.lt(0) ||
+    multiplier.gt(oldMultiplier) ||
+    unwind.lt(oldUnwind)
+  ) {
+    throw new SettlementTrackerError(
+      position.market_id.toString(),
+      'inconsistent',
+    );
+  }
+  const fundingCashflow = mulWad(
+    divWad(funding.minus(oldFunding), oldMultiplier),
+    base.negated(),
+  );
+  const unwindDelta = divWad(unwind.minus(oldUnwind), oldMultiplier);
+  const initialPrice = mulWad(
+    WAD.minus(divWad(multiplier, oldMultiplier)),
+    integer(position.last_price, 'position price'),
+  );
+  const adlCashflow = mulWad(base, unwindDelta.minus(initialPrice));
+  return realized.plus(fundingCashflow).plus(adlCashflow);
+}
+
+/**
+ * Returns raw E18 PnL aligned to collateral units. The instrument floors EACH
+ * market's PnL to quote-token precision before Core aggregates collateral info.
+ * Funding is the stored market tracker delta; do not extrapolate it with time.
+ */
+export function calculateSettledAccountPnl(
+  positions: RealizedBalancePosition[],
+  trackers: Partial<Record<string, RealizedBalanceTrackers>>,
+  collateralDecimals: number,
+  onGuarded?: () => void,
+): BigNumber {
+  return positions.reduce((sum, position) => {
+    const pnl = calculateSettledPositionPnl(
+      position,
+      trackers[position.market_id.toString()],
+      onGuarded,
+    );
+    const rounded = pnl
+      .shiftedBy(collateralDecimals - 18)
+      .integerValue(BigNumber.ROUND_FLOOR)
+      .shiftedBy(18 - collateralDecimals);
+    return sum.plus(rounded);
+  }, new BigNumber(0));
+}

package/src/utils/throttled-error.ts

@@ -0,0 +1,85 @@
+export interface ThrottleState {
+  lastEmitMs: number;
+  suppressed: number;
+}
+
+/**
+ * Sustained-gate state: a sliding window of recent occurrence timestamps
+ * (len-capped at `threshold`), plus the last emit time and the count dropped
+ * since it (folded into the next emitted line).
+ */
+export interface SustainedState {
+  times: number[];
+  lastEmitMs: number | null;
+  suppressed: number;
+}
+
+/**
+ * Pure throttle decision (`nowMs` injected for testability). Returns the next
+ * state and `emit`: the suppressed-since-previous count if the line should be
+ * emitted now (the counter resets), or `null` to suppress (incrementing the
+ * dropped counter). The first call at a key (no prior state) always emits.
+ */
+export function throttleDecision(
+  prev: ThrottleState | undefined,
+  nowMs: number,
+  windowMs: number,
+): { next: ThrottleState; emit: number | null } {
+  if (prev && nowMs - prev.lastEmitMs < windowMs) {
+    return {
+      next: { lastEmitMs: prev.lastEmitMs, suppressed: prev.suppressed + 1 },
+      emit: null,
+    };
+  }
+  return {
+    next: { lastEmitMs: nowMs, suppressed: 0 },
+    emit: prev?.suppressed ?? 0,
+  };
+}
+
+/**
+ * Pure sustained-gate + throttle decision (`nowMs` injected for testability).
+ * Occurrences outside the sliding window are dropped before the current
+ * occurrence is recorded. The timestamp deque is capped at `threshold`, since
+ * older entries cannot affect the next decision once the threshold is met.
+ *
+ * Emits only when at least `threshold` occurrences fall within the window and
+ * at least `windowMs` has elapsed since the previous emit. A gate-open
+ * occurrence blocked by that re-emission throttle increments `suppressed`.
+ */
+export function sustainedDecision(
+  prev: SustainedState | undefined,
+  nowMs: number,
+  windowMs: number,
+  threshold: number,
+): {
+  next: SustainedState;
+  emit: { occurrences: number; suppressed: number } | null;
+} {
+  const times = (prev?.times ?? []).filter((t) => nowMs - t < windowMs);
+  times.push(nowMs);
+  while (times.length > threshold) times.shift();
+
+  const prevLastEmitMs = prev?.lastEmitMs ?? null;
+  const prevSuppressed = prev?.suppressed ?? 0;
+
+  const gateOpen = times.length >= threshold;
+  const throttleElapsed =
+    prevLastEmitMs === null || nowMs - prevLastEmitMs >= windowMs;
+
+  if (gateOpen && throttleElapsed) {
+    return {
+      next: { times, lastEmitMs: nowMs, suppressed: 0 },
+      emit: { occurrences: times.length, suppressed: prevSuppressed },
+    };
+  }
+
+  return {
+    next: {
+      times,
+      lastEmitMs: prevLastEmitMs,
+      suppressed: gateOpen ? prevSuppressed + 1 : prevSuppressed,
+    },
+    emit: null,
+  };
+}

package/src/utils/token/normalize.ts

@@ -1,4 +1,5 @@
 import { TradingApi } from '../../trading-api-types';
+import { MoneyInOutChainId, ReyaChainId } from '../../types';
 import { getTokenInfoByAddress } from './token-info-getters';
 
 export const normalizeDecimals = (
@@ -16,11 +17,15 @@ export const normalizeDecimals = (
 
 export const normalizeAccountBalance = (
   accountBalance: TradingApi['wallet/:address/accounts/balances']['response'][0],
+  chainId?: ReyaChainId | MoneyInOutChainId,
 ) => {
   if (!accountBalance.collateral) {
     return accountBalance;
   }
-  const decimals = getTokenInfoByAddress(accountBalance.collateral).decimals;
+  const decimals = getTokenInfoByAddress(
+    accountBalance.collateral,
+    chainId,
+  ).decimals;
   return {
     ...accountBalance,
     balance: normalizeDecimals(accountBalance.balance, decimals),

package/src/utils/token/token-info-getters.ts

@@ -8,6 +8,94 @@ import {
 } from '../../types';
 import { convertToAddress } from './utils';
 
+const LOCAL_ADDRESS_PATTERN = /^0x[a-fA-F0-9]{40}$/;
+
+const localAddressOverride = (envName: string, fallback: Address): Address => {
+  const rawAddress = process.env[envName]?.trim();
+  if (!rawAddress) {
+    return fallback;
+  }
+
+  if (!LOCAL_ADDRESS_PATTERN.test(rawAddress)) {
+    throw new Error(`Invalid ${envName} address override: ${rawAddress}`);
+  }
+
+  return rawAddress.toLowerCase() as Address;
+};
+
+/**
+ * The Reya chains whose token addresses may be overridden from the
+ * environment. An ALLOWLIST on purpose: this function also accepts
+ * MoneyInOutChainId, and TOKEN_INFO carries entries for external chains
+ * (ethereum, op, polygon, arbitrum, base) whose USDC/WETH names collide with
+ * the ones overridden below. A "not mainnet" test would quietly rewrite those
+ * external addresses from Reya-local env vars; an allowlist cannot, and a new
+ * money-in/out chain cannot opt itself in by accident.
+ *
+ * reyaCronos is here because devnet1 shares that chain id while running its
+ * OWN passive pool and sRUSD (2026-08-22), publishing SRUSD_PROXY_ADDRESS in
+ * its api values. Gated on reyaLocal alone it never reached this path, so
+ * getTokenInfoByAddress threw "no token info found" for devnet's own sRUSD,
+ * which broke /v2/wallet/:address/accountBalances -- the RLP balance never
+ * appeared after staking rUSD. Each override still falls back to the compiled
+ * address when its env var is unset, so cronos itself is a no-op.
+ *
+ * Same root cause and same fix as the asset map in common-backend (#2903);
+ * these two must stay in step.
+ */
+const REYA_CHAINS_WITH_ADDRESS_OVERRIDES: ReadonlySet<ReyaChainId> = new Set([
+  ReyaChainId.reyaLocal,
+  ReyaChainId.reyaCronos,
+]);
+
+const withLocalAddressOverrides = (tokenInfos: TokenInfo[]): TokenInfo[] =>
+  tokenInfos.map((tokenInfo) => {
+    switch (tokenInfo.name) {
+      case 'RUSD':
+        return {
+          ...tokenInfo,
+          address: localAddressOverride(
+            'RUSD_COLLATERAL_ADDRESS',
+            tokenInfo.address,
+          ),
+        };
+      case 'WETH':
+        return {
+          ...tokenInfo,
+          address: localAddressOverride(
+            'LOCAL_ETH_ASSET_ADDRESS',
+            tokenInfo.address,
+          ),
+        };
+      case 'WBTC':
+        return {
+          ...tokenInfo,
+          address: localAddressOverride(
+            'LOCAL_BTC_ASSET_ADDRESS',
+            tokenInfo.address,
+          ),
+        };
+      case 'SRUSD':
+        return {
+          ...tokenInfo,
+          address: localAddressOverride(
+            'SRUSD_PROXY_ADDRESS',
+            tokenInfo.address,
+          ),
+        };
+      case 'USDC':
+        return {
+          ...tokenInfo,
+          address: localAddressOverride(
+            'LOCAL_USDC_ASSET_ADDRESS',
+            tokenInfo.address,
+          ),
+        };
+      default:
+        return tokenInfo;
+    }
+  });
+
 export const getTokenInfoByAddress = (
   tokenAddressParam: Address | string,
   chainId?: ReyaChainId | MoneyInOutChainId,
@@ -18,7 +106,7 @@ export const getTokenInfoByAddress = (
       : tokenAddressParam;
 
   if (chainId) {
-    const tokenInfo = TOKEN_INFO[chainId].find(
+    const tokenInfo = getTokenInfosByChain(chainId).find(
       (tokenInfo) => tokenInfo.address === tokenAddress,
     );
     if (!tokenInfo) {
@@ -29,8 +117,15 @@ export const getTokenInfoByAddress = (
     return tokenInfo;
   } else {
     for (const chainId in TOKEN_INFO) {
-      const tokenInfos =
-        TOKEN_INFO[chainId as unknown as keyof typeof TOKEN_INFO];
+      // getTokenInfosByChain, NOT raw TOKEN_INFO: the address overrides live
+      // in that function, so reading the table directly here made this branch
+      // blind to any deployment running its own token. devnet1's sRUSD
+      // resolved on the chainId-passing branch above and threw here --
+      // "no token info found [token address 0x8a04...]", with no chainId in
+      // the message, which is what distinguishes the two call sites.
+      const tokenInfos = getTokenInfosByChain(
+        Number(chainId) as ReyaChainId | MoneyInOutChainId,
+      );
       const tokenInfo = tokenInfos.find(
         (tokenInfo) => tokenInfo.address === tokenAddress,
       );
@@ -48,7 +143,7 @@ export const getTokenInfoByName = (
   tokenName: TokenName,
   chainId: ReyaChainId | MoneyInOutChainId,
 ): TokenInfo => {
-  const tokenInfo = TOKEN_INFO[chainId].find(
+  const tokenInfo = getTokenInfosByChain(chainId).find(
     (tokenInfo) => tokenInfo.name === tokenName,
   );
 
@@ -64,13 +159,16 @@ export const getTokenInfoByName = (
 export const getTokenInfosByChain = (
   chainId: ReyaChainId | MoneyInOutChainId,
 ): TokenInfo[] => {
-  return TOKEN_INFO[chainId];
+  const tokenInfos = TOKEN_INFO[chainId];
+  return REYA_CHAINS_WITH_ADDRESS_OVERRIDES.has(chainId as ReyaChainId)
+    ? withLocalAddressOverrides(tokenInfos)
+    : tokenInfos;
 };
 
 export const getRUSDUnderlyingTokenInfo = (
   chainId: ReyaChainId | MoneyInOutChainId,
 ): TokenInfo => {
-  const tokenInfo = TOKEN_INFO[chainId].find(
+  const tokenInfo = getTokenInfosByChain(chainId).find(
     (tokenInfo) => tokenInfo.isRUSDUnderlying === true,
   );
 

package/src/utils/token/token-info.ts

@@ -537,6 +537,48 @@ export const TOKEN_INFO: Record<ReyaChainId | MoneyInOutChainId, TokenInfo[]> =
         minTransferAmount: 1,
       },
     ],
+    [ReyaChainId.reyaLocal]: [
+      {
+        name: 'WBTC',
+        address: '0x459374f3f3e92728bca838dfa8c95e706fe67e8a',
+        decimals: 8,
+        isRUSDUnderlying: false,
+        ...defaultTokenThresholds,
+      },
+      {
+        name: 'RUSD',
+        address: '0x9de724e7b3facf87ce39465d3d712717182e3e55',
+        decimals: 6,
+        isRUSDUnderlying: false,
+        ...defaultTokenThresholds,
+      },
+      {
+        name: 'USDC',
+        address: '0xfa27c7c6051344263533cc365274d9569b0272a8',
+        decimals: 6,
+        isRUSDUnderlying: true,
+        ...defaultTokenThresholds,
+      },
+      {
+        name: 'WETH',
+        address: '0x2cf56315acc7e791b1a0135c09d8d5c8dbcd2f14',
+        decimals: 18,
+        isRUSDUnderlying: false,
+        ...defaultTokenThresholds,
+        minDepositAmount: 0.01,
+        minWithdrawAmount: 0.01,
+        minTransferAmount: 0.01,
+      },
+      {
+        name: 'SRUSD',
+        address: '0xb9f531a54fc0e9adca1b931d9533b4e49bb2fad6',
+        decimals: 30,
+        isRUSDUnderlying: false,
+        whitelistedWalletOnly: false,
+        isPoolToken: true,
+        ...defaultTokenThresholds,
+      },
+    ],
     [MoneyInOutChainId.arbitrumSepolia]: [
       {
         name: 'USDC',