@raac/rpc 1.2.0-beta.9 → 2.0.0-beta.0

package/dist/types/contracts/governance/gauge/_apy.d.ts

@@ -0,0 +1,72 @@
+import { Provider } from "ethers";
+import { ChainId } from "../../../configs/chains";
+import { BaseGauge, GaugeController } from "../../../typechain-types";
+import { TokenAmount } from "../../../utils/amount";
+export declare const SECONDS_PER_YEAR: bigint;
+/** Where the main reward token's yearly emission is read from. */
+export type GaugeRewardSource = "stream" | "epoch";
+/** USD prices supplied by the caller. They are display inputs, not on-chain values, so they stay plain numbers. */
+export interface GaugeApyPrices {
+    /** USD price of one whole staking token. */
+    stakingTokenPriceUSD: number;
+    /** USD price of one whole reward token, keyed by token address in any case. Reward tokens without a price are reported but left out of every APY. */
+    rewardTokenPricesUSD: Record<string, number>;
+}
+export interface GaugeApyOptions {
+    /** "epoch" (default) annualizes the gauge's share of the last completed distributor epoch: what the gauge is entitled to per week, lagging one epoch. "stream" annualizes the rate the gauge is paying right now, which spikes when a pull lands late in a period or after a pause, and reads 0 once the period has ended without a new pull. Extra reward tokens always use their stream. */
+    rewardSource?: GaugeRewardSource;
+}
+export interface RewardTokenApy {
+    token: string;
+    /** "main" rewards are shared by working balance (boosted); "extra" rewards by raw balance (unboosted). */
+    kind: "main" | "extra";
+    /** Reward tokens paid per year at the current rate, in the reward token's base units. */
+    yearlyRewards: TokenAmount;
+    /** The caller-supplied USD price, or null when none was given. */
+    priceUSD: number | null;
+    /** `yearlyRewards` valued at `priceUSD`, a computed USD float. Null without a price. */
+    yearlyRewardsUSD: number | null;
+    /** False when the stream has ended (period over) or, for "epoch", the last epoch paid nothing. */
+    active: boolean;
+}
+/** On-chain state shared by the gauge and user APY calculations. */
+export interface GaugeApyState {
+    gauge: string;
+    gaugeContract: BaseGauge;
+    controller: GaugeController;
+    stakingToken: string;
+    /** From the token registry; 18 when the registry does not list the token. */
+    stakingDecimals: number;
+    /** From the token registry; undefined when the registry does not list the token. */
+    stakingSymbol?: string;
+    /** Staking token base units. */
+    totalSupply: bigint;
+    /** Staking token base units. */
+    workingSupply: bigint;
+    /** Basis points (10000 = 1x). */
+    minBoost: bigint;
+    /** Basis points (10000 = 1x). */
+    maxBoost: bigint;
+    rewardSource: GaugeRewardSource;
+    rewards: RewardTokenApy[];
+    /** Sum of priced main-token rewards per year, USD. */
+    mainYearlyUSD: number;
+    /** Sum of priced extra-token rewards per year, USD. */
+    extraYearlyUSD: number;
+}
+/** Annualized percentage, a computed float: yearly USD over staked USD, or null when nothing is staked or the staking token has no price. */
+export declare const toApyPct: (yearlyUSD: number, stakedUnits: number, stakingTokenPriceUSD: number) => number | null;
+/**
+ * Loads the gauge state an APY calculation needs: supplies, boost bounds and each reward token's yearly emission.
+ *
+ * @param chainId - The chain/network to use.
+ * @param gaugeAddressOrId - Address of the gauge contract or its config ID.
+ * @param prices - USD prices for the staking token and reward tokens.
+ * @param options - Reward source selection.
+ * @param provider - Optional ethers.js Provider instance.
+ * @returns The loaded state.
+ */
+export declare const loadGaugeApyState: (chainId: ChainId, gaugeAddressOrId: string, prices: GaugeApyPrices, options?: GaugeApyOptions, provider?: Provider) => Promise<GaugeApyState & {
+    provider: Provider;
+    now: bigint;
+}>;

package/dist/types/contracts/governance/gauge/_tokens.d.ts

@@ -0,0 +1,25 @@
+import { Provider, Signer } from "ethers";
+import { ChainId } from "../../../configs/chains";
+export declare const ERC20_ABI: string[];
+export declare const ERC4626_ABI: string[];
+export interface GaugeTokens {
+    /** The token the gauge takes. For a wrapped gauge this is the ERC4626 wrapper, which is also the contract that wraps. */
+    stakingToken: string;
+    /** The token the wrapper wraps; null when the gauge takes its token directly. */
+    underlying: string | null;
+}
+/**
+ * Resolves a gauge's staking token address: from the gauge's config entry when it lists one, otherwise from the gauge.
+ * Gauge balances and supplies are in staking token units.
+ *
+ * @param chainId - The chain/network to use.
+ * @param gaugeAddress - Address of the gauge.
+ * @param provider - The provider to read with when the config does not list the staking token.
+ * @returns The staking token address.
+ */
+export declare const getStakingToken: (chainId: ChainId, gaugeAddress: string, provider: Provider) => Promise<string>;
+/**
+ * Reads a gauge's staking token from the gauge and whether it wraps another token. A staking token counts as a wrapper
+ * when it exposes a non-zero `asset()` and a working `totalAssets()`, the same test the subgraph uses for its `wrapped` flag.
+ */
+export declare const getGaugeTokens: (gaugeAddress: string, runner: Provider | Signer) => Promise<GaugeTokens>;

package/dist/types/contracts/governance/gauge/approveGaugeToken.d.ts

@@ -0,0 +1,14 @@
+import { Signer } from "ethers";
+import { ChainId } from "../../../configs/chains";
+/**
+ * Approves the contract that pulls a gauge token: the staking token to the gauge, or for a wrapped gauge the underlying
+ * to the wrapper.
+ *
+ * @param chainId - The chain/network to use.
+ * @param gaugeAddressOrId - Address of the gauge contract or its config ID.
+ * @param token - "staking" to stake, "underlying" to wrap.
+ * @param amount - Allowance to set, base units.
+ * @param signer - An ethers.js Signer instance (required).
+ * @returns The mined transaction.
+ */
+export declare const approveGaugeToken: (chainId: ChainId, gaugeAddressOrId: string, token: "staking" | "underlying", amount: bigint, signer: Signer) => Promise<any>;

package/dist/types/contracts/governance/gauge/claimOnBehalfOf.d.ts

@@ -5,8 +5,8 @@ import { ChainId } from "../../../configs/chains";
  * @param chainId - The chain/network to use.
  * @param gaugeAddressOrId - Address of the gauge contract or its config ID.
  * @param token - Address of the reward token.
- * @param amount - The amount to claim.
+ * @param amount - The amount to claim, in the reward token's base units.
  * @param user - Address of the user on whose behalf the claim is made.
  * @param signer - An ethers.js Signer instance (required).
  */
-export declare const claimOnBehalfOf: (chainId: ChainId, gaugeAddressOrId: string, token: string, amount: string | number | bigint, user: string, signer: Signer) => Promise<any>;
+export declare const claimOnBehalfOf: (chainId: ChainId, gaugeAddressOrId: string, token: string, amount: bigint, user: string, signer: Signer) => Promise<any>;

package/dist/types/contracts/governance/gauge/claimRewardToken.d.ts

@@ -1,7 +1,7 @@
 import { Signer } from "ethers";
 import configs from "../../../configs/chains";
 /**
- * Claims a specific reward token from a gauge.
+ * Claims the caller's main reward token from a gauge, pulling the gauge's share from its distributor first. Reverts while the gauge or its controller is paused.
  *
  * @param chainId - The chain/network to use.
  * @param gaugeAddressOrId - Address of the gauge contract or ID of the gauge.

package/dist/types/contracts/governance/gauge/depositRewardToken.d.ts

@@ -5,7 +5,7 @@ import { ChainId } from "../../../configs/chains";
  * @param chainId - The chain/network to use.
  * @param gaugeAddressOrId - Address of the gauge contract or its config ID.
  * @param token - Address of the reward token to deposit.
- * @param amount - The amount to deposit.
+ * @param amount - The amount to deposit, in the reward token's base units.
  * @param signer - An ethers.js Signer instance (required).
  */
-export declare const depositRewardToken: (chainId: ChainId, gaugeAddressOrId: string, token: string, amount: string | number | bigint, signer: Signer) => Promise<any>;
+export declare const depositRewardToken: (chainId: ChainId, gaugeAddressOrId: string, token: string, amount: bigint, signer: Signer) => Promise<any>;

package/dist/types/contracts/governance/gauge/getAllPendingExtraRewards.d.ts

@@ -1,13 +1,15 @@
 import { Provider } from "ethers";
 import { ChainId } from "../../../configs/chains";
+import { TokenAmount } from "../../../utils/amount";
 /**
  * Gets all pending extra rewards for a user across all extra reward tokens.
  * @param chainId - The chain/network to use.
  * @param gaugeAddressOrId - Address of the gauge contract or its config ID.
  * @param user - Address of the user.
  * @param provider - Optional ethers.js Provider instance.
+ * @returns The extra reward tokens and, index-aligned, each pending amount in that token's base units with its registry decimals and symbol.
  */
 export declare const getAllPendingExtraRewards: (chainId: ChainId, gaugeAddressOrId: string, user: string, provider?: Provider) => Promise<{
     tokens: string[];
-    amounts: bigint[];
+    amounts: TokenAmount[];
 }>;

package/dist/types/contracts/governance/gauge/getApy.d.ts

@@ -0,0 +1,48 @@
+import { Provider } from "ethers";
+import { ChainId } from "../../../configs/chains";
+import { TokenAmount } from "../../../utils/amount";
+import { GaugeApyOptions, GaugeApyPrices, GaugeRewardSource, RewardTokenApy } from "./_apy";
+export type { GaugeApyOptions, GaugeApyPrices, GaugeRewardSource, RewardTokenApy } from "./_apy";
+/**
+ * A gauge's APY. On-chain amounts are `TokenAmount`s; boosts are basis points. USD and APY figures are computed floats
+ * derived from the caller's USD prices, so they stay plain numbers.
+ */
+export interface GaugeApy {
+    gauge: string;
+    stakingToken: string;
+    rewardSource: GaugeRewardSource;
+    /** Raw staked tokens, in staking token base units. */
+    totalStaked: TokenAmount;
+    /** Sum of boosted working balances, in staking token base units. Main rewards are shared over this. */
+    workingSupply: TokenAmount;
+    /** `totalStaked` valued at the caller's staking token price, USD. */
+    tvlUSD: number;
+    /** Minimum boost multiplier in basis points (10000 = 1x). */
+    minBoost: bigint;
+    /** Maximum boost multiplier in basis points (e.g. 25000 = 2.5x). */
+    maxBoost: bigint;
+    /** Main reward APY for a staker with no veRAAC boost, percent. */
+    minApy: number | null;
+    /** Main reward APY for a staker at max boost, percent. */
+    maxApy: number | null;
+    /** Extra reward APY, percent. Unboosted, so the same for every staker. */
+    extraApy: number | null;
+    /** minApy + extraApy, percent. */
+    totalMinApy: number | null;
+    /** maxApy + extraApy, percent. */
+    totalMaxApy: number | null;
+    rewards: RewardTokenApy[];
+}
+/**
+ * Calculates a gauge's minimum (no boost) and maximum (full boost) APY. Figures are simple annualized rates in percent, not compounded.
+ *
+ * Main rewards are shared by working balance, where a staker counts for `balance × boost / MAX_BOOST` (capped at balance). A fully boosted staker's working balance equals their stake, so maxApy = yearly main rewards USD / (workingSupply × staking price), and minApy = maxApy × MIN_BOOST / MAX_BOOST. Extra rewards are shared by raw balance over totalSupply. The figures hold workingSupply fixed, so a large new deposit, or other stakers boosting, lowers them. The "stream" source jumps whenever a pull compresses rewards into the rest of a period, e.g. after a pause.
+ *
+ * @param chainId - The chain/network to use.
+ * @param gaugeAddressOrId - Address of the gauge contract or its config ID.
+ * @param prices - USD price of one whole staking token and of one whole reward token (see `getRewardTokens`), as plain numbers.
+ * @param options - Optional reward source: "epoch" (default) or "stream".
+ * @param provider - Optional ethers.js Provider instance.
+ * @returns Min, max and extra APY (percent floats) with the supplies (staking token amounts), boost bounds (basis points) and per-token yearly rewards (reward token amounts) behind them. An APY is null when nothing is staked.
+ */
+export declare const getApy: (chainId: ChainId, gaugeAddressOrId: string, prices: GaugeApyPrices, options?: GaugeApyOptions, provider?: Provider) => Promise<GaugeApy>;

package/dist/types/contracts/governance/gauge/getBalanceOf.d.ts

@@ -1,5 +1,6 @@
 import { Provider } from "ethers";
 import { ChainId } from "../../../configs/chains";
+import { TokenAmount } from "../../../utils/amount";
 /**
  * Gets the working balance of an account (includes boost).
  *
@@ -7,6 +8,6 @@ import { ChainId } from "../../../configs/chains";
  * @param gaugeAddressOrId - Address of the gauge contract or ID of the gauge.
  * @param accountAddress - Address to check balance for.
  * @param provider - Optional ethers.js Provider instance.
- * @returns The working balance formatted in ether units.
+ * @returns The working balance in staking token base units, with the staking token's registry decimals and symbol.
  */
-export declare const getBalanceOf: (chainId: ChainId, gaugeAddressOrId: string, accountAddress: string, provider?: Provider) => Promise<string>;
+export declare const getBalanceOf: (chainId: ChainId, gaugeAddressOrId: string, accountAddress: string, provider?: Provider) => Promise<TokenAmount>;

package/dist/types/contracts/governance/gauge/getDecimalAdjustment.d.ts

@@ -1,10 +1,12 @@
 import { Provider } from "ethers";
 import { ChainId } from "../../../configs/chains";
 /**
- * Gets the decimal adjustment factor used for a given reward token.
+ * Gets the decimal adjustment factor used for a given reward token: the integer multiplier `10 ** (18 - tokenDecimals)`
+ * the gauge applies to normalize that token's amounts to 18 decimals.
  * @param chainId - The chain/network to use.
  * @param gaugeAddressOrId - Address of the gauge contract or its config ID.
  * @param token - Address of the reward token.
  * @param provider - Optional ethers.js Provider instance.
+ * @returns The multiplier, a plain integer.
  */
 export declare const getDecimalAdjustment: (chainId: ChainId, gaugeAddressOrId: string, token: string, provider?: Provider) => Promise<bigint>;

package/dist/types/contracts/governance/gauge/getEarnedExtraReward.d.ts

@@ -0,0 +1,14 @@
+import { Provider } from "ethers";
+import { ChainId } from "../../../configs/chains";
+import { TokenAmount } from "../../../utils/amount";
+/**
+ * Gets the total amount of an extra reward token a user has already claimed from a gauge.
+ *
+ * @param chainId - The chain/network to use.
+ * @param gaugeAddressOrId - Address of the gauge contract or its config ID.
+ * @param token - Address of a registered extra reward token (see `getExtraRewardTokens`).
+ * @param userAddress - Address of the user.
+ * @param provider - Optional ethers.js Provider instance.
+ * @returns The claimed extra reward in the token's base units, with its registry decimals and symbol.
+ */
+export declare const getEarnedExtraReward: (chainId: ChainId, gaugeAddressOrId: string, token: string, userAddress: string, provider?: Provider) => Promise<TokenAmount>;

package/dist/types/contracts/governance/gauge/getEarnedReward.d.ts

@@ -1,12 +1,14 @@
 import { Provider } from "ethers";
 import { ChainId } from "../../../configs/chains";
+import { TokenAmount } from "../../../utils/amount";
 /**
- * Gets the total amount of main-reward-token a user has already claimed from a gauge.
+ * Gets the total amount of a reward token a user has already claimed from a gauge.
  *
  * @param chainId - The chain/network to use.
  * @param gaugeAddressOrId - Address of the gauge contract or its config ID.
+ * @param token - Reward token address (see `getRewardTokens`).
  * @param userAddress - Address of the user.
  * @param provider - Optional ethers.js Provider instance.
- * @returns The claimed reward amount (raw, base units).
+ * @returns The claimed reward in the token's base units, with its registry decimals and symbol.
  */
-export declare const getEarnedReward: (chainId: ChainId, gaugeAddressOrId: string, userAddress: string, provider?: Provider) => Promise<bigint>;
+export declare const getEarnedReward: (chainId: ChainId, gaugeAddressOrId: string, token: string, userAddress: string, provider?: Provider) => Promise<TokenAmount>;

package/dist/types/contracts/governance/gauge/getGaugeData.d.ts

@@ -0,0 +1,24 @@
+import { Provider } from "ethers";
+import { ChainId } from "../../../configs/chains";
+import { TokenAmount } from "../../../utils/amount";
+export interface GaugeData {
+    gaugeInitialStartTime: bigint;
+    /** Reward period length, seconds: 7 days for RAAC gauges, 28 days for RWA gauges. */
+    periodDuration: bigint;
+    periodIndex: bigint;
+    stakingToken: string;
+    totalSupply: TokenAmount;
+    workingSupply: TokenAmount;
+    rewardDistributor: string;
+    rewardToken: string;
+    lastUpdateTime: bigint;
+}
+/**
+ * Reads a gauge's `gaugeData` struct: its staking and reward tokens, distributor, supplies and period state.
+ *
+ * @param chainId - The chain/network to use.
+ * @param gaugeAddressOrId - Address of the gauge contract or its config ID.
+ * @param provider - Optional ethers.js Provider instance.
+ * @returns The gauge data. Supplies are staking token amounts.
+ */
+export declare const getGaugeData: (chainId: ChainId, gaugeAddressOrId: string, provider?: Provider) => Promise<GaugeData>;

package/dist/types/contracts/governance/gauge/getGaugeRewardTokenData.d.ts

@@ -1,18 +1,26 @@
 import { Provider } from "ethers";
 import { ChainId } from "../../../configs/chains";
+import { ScaledValue, TokenAmount } from "../../../utils/amount";
 /**
- * Gets the gauge-level reward accounting data for a specific token.
- * @param chainId - The chain/network to use.
- * @param gaugeAddressOrId - Address of the gauge contract or its config ID.
- * @param token - Address of the reward token.
- * @param provider - Optional ethers.js Provider instance.
+ * Decimals of the main reward token's `rate`: the gauge normalizes rewards to 18 decimals and stores the
+ * per-second rate scaled by a further 1e36 (`RewardIntegralCalculator.calculateRate`), so tokens per second is `value / 1e54`.
  */
-export declare const getGaugeRewardTokenData: (chainId: ChainId, gaugeAddressOrId: string, token: string, provider?: Provider) => Promise<{
+export declare const GAUGE_REWARD_RATE_DECIMALS = 54;
+export interface GaugeRewardTokenData {
     isActive: boolean;
     decimals: bigint;
-    rate: bigint;
+    rate: ScaledValue;
     integral: bigint;
     lastUpdateTime: bigint;
-    distributed: bigint;
-    leftoverRewards: bigint;
-}>;
+    distributed: TokenAmount;
+    leftoverRewards: TokenAmount;
+}
+/**
+ * Gets the gauge-level reward accounting data for the gauge's main reward token.
+ * @param chainId - The chain/network to use.
+ * @param gaugeAddressOrId - Address of the gauge contract or its config ID.
+ * @param token - Address of the reward token.
+ * @param provider - Optional ethers.js Provider instance.
+ * @returns The reward token data; see `GaugeRewardTokenData` for the unit of each field.
+ */
+export declare const getGaugeRewardTokenData: (chainId: ChainId, gaugeAddressOrId: string, token: string, provider?: Provider) => Promise<GaugeRewardTokenData>;

package/dist/types/contracts/governance/gauge/getPauseStatus.d.ts

@@ -0,0 +1,19 @@
+import { Provider } from "ethers";
+import { ChainId } from "../../../configs/chains";
+export interface GaugePauseStatus {
+    /** The gauge's own emergency pause switch. */
+    gaugePaused: boolean;
+    /** The global emergency pause of the controller the gauge reports to. */
+    controllerPaused: boolean;
+    /** True when neither pause is on, i.e. stake, claims and reward pulls are open. Withdraw is open either way. */
+    live: boolean;
+}
+/**
+ * Reads both pause switches that gate a gauge, mirroring the contract's `whenGaugeLive` check.
+ *
+ * @param chainId - The chain/network to use.
+ * @param gaugeAddressOrId - Address of the gauge contract or its config ID.
+ * @param provider - Optional ethers.js Provider instance.
+ * @returns The gauge's and its controller's pause flags, and whether the gauge is live.
+ */
+export declare const getPauseStatus: (chainId: ChainId, gaugeAddressOrId: string, provider?: Provider) => Promise<GaugePauseStatus>;

package/dist/types/contracts/governance/gauge/getPendingExtraRewards.d.ts

@@ -1,5 +1,6 @@
 import { Provider } from "ethers";
 import { ChainId } from "../../../configs/chains";
+import { TokenAmount } from "../../../utils/amount";
 /**
  * Gets the pending extra rewards for a user for a specific token.
  * @param chainId - The chain/network to use.
@@ -7,5 +8,6 @@ import { ChainId } from "../../../configs/chains";
  * @param token - Address of the reward token.
  * @param user - Address of the user.
  * @param provider - Optional ethers.js Provider instance.
+ * @returns The pending extra reward in the token's base units, with its registry decimals and symbol.
  */
-export declare const getPendingExtraRewards: (chainId: ChainId, gaugeAddressOrId: string, token: string, user: string, provider?: Provider) => Promise<bigint>;
+export declare const getPendingExtraRewards: (chainId: ChainId, gaugeAddressOrId: string, token: string, user: string, provider?: Provider) => Promise<TokenAmount>;

package/dist/types/contracts/governance/gauge/getPendingRewards.d.ts

@@ -1,12 +1,14 @@
 import { Provider } from "ethers";
 import { ChainId } from "../../../configs/chains";
+import { TokenAmount } from "../../../utils/amount";
 /**
- * Gets the pending (unclaimed) main-reward-token amount for a user on a gauge.
+ * Gets the rewards a user can claim from a gauge for one reward token. Only counts rewards already pulled into the gauge, which is everything a user can claim right now; `getUserClaimableRewards` adds the extra reward tokens.
  *
  * @param chainId - The chain/network to use.
  * @param gaugeAddressOrId - Address of the gauge contract or its config ID.
+ * @param token - The gauge's main reward token (`getGaugeData().rewardToken`). Any other token reverts with NotSupportedToken; use `getPendingExtraRewards` for extra reward tokens.
  * @param accountAddress - Address of the user.
  * @param provider - Optional ethers.js Provider instance.
- * @returns The pending reward amount (raw, base units).
+ * @returns The pending reward in the token's base units, with its registry decimals and symbol.
  */
-export declare const getPendingRewards: (chainId: ChainId, gaugeAddressOrId: string, accountAddress: string, provider?: Provider) => Promise<bigint>;
+export declare const getPendingRewards: (chainId: ChainId, gaugeAddressOrId: string, token: string, accountAddress: string, provider?: Provider) => Promise<TokenAmount>;

package/dist/types/contracts/governance/gauge/getRaacAutolockMin.d.ts

@@ -1,9 +1,11 @@
 import { Provider } from "ethers";
 import { ChainId } from "../../../configs/chains";
+import { TokenAmount } from "../../../utils/amount";
 /**
  * Gets the minimum RAAC amount required to trigger an autolock on claim.
  * @param chainId - The chain/network to use.
  * @param gaugeAddressOrId - Address of the gauge contract or its config ID.
  * @param provider - Optional ethers.js Provider instance.
+ * @returns The minimum in RAAC base units.
  */
-export declare const getRaacAutolockMin: (chainId: ChainId, gaugeAddressOrId: string, provider?: Provider) => Promise<bigint>;
+export declare const getRaacAutolockMin: (chainId: ChainId, gaugeAddressOrId: string, provider?: Provider) => Promise<TokenAmount>;

package/dist/types/contracts/governance/gauge/getRawBalanceOf.d.ts

@@ -1,5 +1,6 @@
 import { Provider } from "ethers";
 import { ChainId } from "../../../configs/chains";
+import { TokenAmount } from "../../../utils/amount";
 /**
  * Gets the raw balance of an account (without boost).
  *
@@ -7,6 +8,6 @@ import { ChainId } from "../../../configs/chains";
  * @param gaugeAddressOrId - Address of the gauge contract or ID of the gauge.
  * @param accountAddress - Address to check balance for.
  * @param provider - Optional ethers.js Provider instance.
- * @returns The raw balance formatted in ether units.
+ * @returns The staked balance in staking token base units, with the staking token's registry decimals and symbol.
  */
-export declare const getRawBalanceOf: (chainId: ChainId, gaugeAddressOrId: string, accountAddress: string, provider?: Provider) => Promise<string>;
+export declare const getRawBalanceOf: (chainId: ChainId, gaugeAddressOrId: string, accountAddress: string, provider?: Provider) => Promise<TokenAmount>;

package/dist/types/contracts/governance/gauge/getRawTotalSupply.d.ts

@@ -1,11 +1,12 @@
 import { Provider } from "ethers";
 import { ChainId } from "../../../configs/chains";
+import { TokenAmount } from "../../../utils/amount";
 /**
  * Gets the raw total supply of the gauge (without boost).
  *
  * @param chainId - The chain/network to use.
  * @param gaugeAddressOrId - Address of the gauge contract or ID of the gauge.
  * @param provider - Optional ethers.js Provider instance.
- * @returns The raw total supply formatted in ether units.
+ * @returns The total staked in staking token base units, with the staking token's registry decimals and symbol.
  */
-export declare const getRawTotalSupply: (chainId: ChainId, gaugeAddressOrId: string, provider?: Provider) => Promise<string>;
+export declare const getRawTotalSupply: (chainId: ChainId, gaugeAddressOrId: string, provider?: Provider) => Promise<TokenAmount>;

package/dist/types/contracts/governance/gauge/getRewardTokens.d.ts

@@ -0,0 +1,11 @@
+import { Provider } from "ethers";
+import { ChainId } from "../../../configs/chains";
+/**
+ * Gets every reward token of a gauge: the main reward token first, then the extra reward tokens.
+ *
+ * @param chainId - The chain/network to use.
+ * @param gaugeAddressOrId - Address of the gauge contract or its config ID.
+ * @param provider - Optional ethers.js Provider instance.
+ * @returns The reward token addresses.
+ */
+export declare const getRewardTokens: (chainId: ChainId, gaugeAddressOrId: string, provider?: Provider) => Promise<string[]>;

package/dist/types/contracts/governance/gauge/getTotalSupply.d.ts

@@ -1,11 +1,12 @@
 import { Provider } from "ethers";
 import { ChainId } from "../../../configs/chains";
+import { TokenAmount } from "../../../utils/amount";
 /**
  * Gets the working supply of the gauge (includes boost).
  *
  * @param chainId - The chain/network to use.
  * @param gaugeAddressOrId - Address of the gauge contract or ID of the gauge.
  * @param provider - Optional ethers.js Provider instance.
- * @returns The working supply formatted in ether units.
+ * @returns The working supply in staking token base units, with the staking token's registry decimals and symbol.
  */
-export declare const getTotalSupply: (chainId: ChainId, gaugeAddressOrId: string, provider?: Provider) => Promise<string>;
+export declare const getTotalSupply: (chainId: ChainId, gaugeAddressOrId: string, provider?: Provider) => Promise<TokenAmount>;

package/dist/types/contracts/governance/gauge/getUserApy.d.ts

@@ -0,0 +1,46 @@
+import { Provider } from "ethers";
+import { ChainId } from "../../../configs/chains";
+import { TokenAmount } from "../../../utils/amount";
+import { GaugeApyOptions, GaugeApyPrices } from "./_apy";
+/** A user's position on a gauge. Amounts are staking token `TokenAmount`s; APYs are computed percent floats. */
+export interface UserApyPosition {
+    /** Raw stake, in staking token base units. */
+    balance: TokenAmount;
+    /** Boosted working balance, in staking token base units. */
+    workingBalance: TokenAmount;
+    /** Effective boost multiplier in basis points, between the controller's min and max (e.g. 10000 to 25000). Null with no stake. */
+    boost: bigint | null;
+    /** Main reward APY, percent. */
+    mainApy: number | null;
+    /** Extra reward APY, percent. */
+    extraApy: number | null;
+    /** mainApy + extraApy, percent. */
+    apy: number | null;
+}
+export interface UserGaugeApy {
+    gauge: string;
+    user: string;
+    /** What the user earns now, from the working balance stored at their last checkpoint. */
+    current: UserApyPosition;
+    /** What the user would earn once their working balance is re-checkpointed (stake, withdraw, claim or `updateUserRewards`) with their current veRAAC, after adding `additionalStake`. */
+    projected: UserApyPosition;
+    /** The gauge's min and max main reward APY for comparison, percent. */
+    gaugeMinApy: number | null;
+    gaugeMaxApy: number | null;
+}
+/**
+ * Calculates a user's APY on a gauge: what they earn now, and what they would earn after their boost is re-checkpointed, optionally with extra stake. Figures are simple annualized rates in percent, not compounded.
+ *
+ * The user's share of main rewards is workingBalance / workingSupply; extra rewards are shared by raw balance. The stored working balance only changes when the user's position is checkpointed, so `current` can lag their veRAAC: `projected` recomputes it with the controller's `calculateBoost` and adjusts workingSupply and totalSupply for the change, holding every other staker fixed.
+ *
+ * @param chainId - The chain/network to use.
+ * @param gaugeAddressOrId - Address of the gauge contract or its config ID.
+ * @param user - Address of the user.
+ * @param prices - USD price of one whole staking token and of one whole reward token (see `getRewardTokens`), as plain numbers.
+ * @param options - Optional reward source ("epoch" default, or "stream") and `additionalStake`, a staking token amount in base units to add in the projection.
+ * @param provider - Optional ethers.js Provider instance.
+ * @returns The user's current and projected position (staking token amounts, boost in basis points) and APY (percent floats), with the gauge's min and max APY. An APY is null when the position has no stake.
+ */
+export declare const getUserApy: (chainId: ChainId, gaugeAddressOrId: string, user: string, prices: GaugeApyPrices, options?: GaugeApyOptions & {
+    additionalStake?: bigint;
+}, provider?: Provider) => Promise<UserGaugeApy>;

package/dist/types/contracts/governance/gauge/getUserClaimableRewards.d.ts

@@ -1,40 +1,42 @@
 import { Provider } from "ethers";
 import { ChainId } from "../../../configs/chains";
+import { TokenAmount } from "../../../utils/amount";
 export interface ClaimableExtraReward {
     token: string;
-    symbol: string;
+    /** From the token registry; undefined when the registry does not list the token. */
+    symbol?: string;
+    /** From the token registry; 18 when the registry does not list the token. */
     decimals: number;
-    /** Claimable amount, base units. */
-    amount: bigint;
-    /** Claimable amount, formatted to `decimals`. */
-    formatted: string;
+    /** Claimable amount, in this token's base units. */
+    amount: TokenAmount;
 }
 export interface UserClaimableRewards {
     gauge: string;
-    /** RAAC already accrued to the user inside the gauge (gauge.pendingRewards). */
-    inGauge: bigint;
-    /** The user's pro-rata share of RAAC still sitting in the distributor for this gauge
-     *  (deposited but not yet pulled in via a claim). */
-    inDistributor: bigint;
-    /** Total claimable RAAC = inGauge + inDistributor, base units. */
-    raac: bigint;
-    /** Total claimable RAAC, formatted (18 decimals). */
-    raacFormatted: string;
+    /** The gauge's main reward token. */
+    rewardToken: string;
+    /** The distributor the gauge pulls its main reward from, read from the gauge. */
+    distributor: string;
+    /** Main reward already accrued to the user inside the gauge (gauge.pendingRewards), in reward token base units. */
+    inGauge: TokenAmount;
+    /** Main reward the user can claim right now, in reward token base units. Same as `inGauge`. */
+    raac: TokenAmount;
     /** Extra reward tokens claimable by the user. */
     extras: ClaimableExtraReward[];
 }
 /**
- * The user's TRUE claimable rewards on a gauge.
+ * What a user can claim from a gauge right now: the main reward already accrued to them inside the gauge, plus any
+ * extra reward tokens.
  *
- * The gauge's `pendingRewards()` view only reflects RAAC already pulled into the gauge.
- * RAAC emitted to the gauge sits in the GaugeRewardsDistributor until a claim pulls it in
- * (`claimRewardToken`/`claimRewardsFor` call `_pullRewardsFromDistributor` first). So a
- * user's real claimable also includes their working-balance share of the distributor's
- * `getClaimableForGauge(gauge)`. This helper combines both, plus any extra reward tokens.
+ * Rewards still held by the GaugeRewardsDistributor are not included. They are not the user's yet: a pull
+ * (`pullRewardsFromDistributor`, or the pull every claim makes first) streams them to everyone staked over the rest of
+ * the reward period, so any per-user share of them would change with every stake, unstake and pull. Read the gauge's
+ * total still in the distributor with `governance.distributor.getClaimableForGauge` when it is needed.
+ * The distributor is read from the gauge itself, so RAAC and RWA gauges both resolve to their own system's distributor.
  *
  * @param chainId - The chain/network to use.
  * @param gaugeAddressOrId - Address of the gauge contract or its config ID.
  * @param accountAddress - Address of the user.
  * @param provider - Optional ethers.js Provider instance.
+ * @returns The claimable main reward and extra rewards, each in its own token's base units with its registry decimals and symbol.
  */
 export declare const getUserClaimableRewards: (chainId: ChainId, gaugeAddressOrId: string, accountAddress: string, provider?: Provider) => Promise<UserClaimableRewards>;

package/dist/types/contracts/governance/gauge/getUserGaugeState.d.ts

@@ -0,0 +1,35 @@
+import { Provider } from "ethers";
+import { ChainId } from "../../../configs/chains";
+import { TokenAmount } from "../../../utils/amount";
+export interface UserGaugeTokenState {
+    address: string;
+    /** From the token registry; undefined when the registry does not list the token. */
+    symbol?: string;
+    /** From the token registry; 18 when the registry does not list the token. */
+    decimals: number;
+    /** Wallet balance, in this token's base units. */
+    balance: TokenAmount;
+    /** Allowance to `spender`, in this token's base units. */
+    allowance: TokenAmount;
+    /** The contract that pulls the token: the gauge for the staking token, the wrapper for the underlying. */
+    spender: string;
+}
+export interface UserGaugeState {
+    gauge: string;
+    /** Staking token staked in the gauge, in staking token base units, without boost. */
+    staked: TokenAmount;
+    stakingToken: UserGaugeTokenState;
+    /** The token to wrap before staking; null when the gauge takes its token directly. */
+    underlying: UserGaugeTokenState | null;
+}
+/**
+ * What a wallet needs to stake in, wrap for, or unstake from a gauge: its stake, its balance of the staking token and its
+ * allowance to the gauge, and for a wrapped gauge its balance of the underlying and allowance to the wrapper.
+ *
+ * @param chainId - The chain/network to use.
+ * @param gaugeAddressOrId - Address of the gauge contract or its config ID.
+ * @param user - The wallet.
+ * @param provider - Optional ethers.js Provider instance.
+ * @returns The wallet's gauge state. Every amount carries its own token's registry decimals and symbol.
+ */
+export declare const getUserGaugeState: (chainId: ChainId, gaugeAddressOrId: string, user: string, provider?: Provider) => Promise<UserGaugeState>;