@raac/rpc 1.2.0-beta.10 → 1.2.0-beta.11

package/dist/types/contracts/governance/distributor/getClaimableForGauge.d.ts

@@ -1,11 +1,13 @@
 import { Provider } from "ethers";
 import { ChainId } from "../../../configs/chains";
+import { GaugeSystemRef } from "../gaugeSystems/_helpers";
 /**
- * Gets the amount of rewards currently claimable for a gauge.
+ * Estimates the rewards a gauge can still pull from the distributor.
  *
  * @param chainId - The chain/network to use.
- * @param gauge - Address of the gauge.
+ * @param gaugeSystem - Gauge system id ("raacgauges" or "rwagauges") or a GaugeRewardsDistributor address.
+ * @param gaugeAddressOrId - Address or config id of the gauge.
  * @param provider - Optional ethers.js Provider instance.
- * @returns Claimable reward amount (bigint).
+ * @returns The claimable amount, base units.
  */
-export declare const getClaimableForGauge: (chainId: ChainId, gauge: string, provider?: Provider) => Promise<bigint>;
+export declare const getClaimableForGauge: (chainId: ChainId, gaugeSystem: GaugeSystemRef, gaugeAddressOrId: string, provider?: Provider) => Promise<bigint>;

package/dist/types/contracts/governance/distributor/getClaimedAtEpoch.d.ts

@@ -1,12 +1,14 @@
 import { Provider } from "ethers";
 import { ChainId } from "../../../configs/chains";
+import { GaugeSystemRef } from "../gaugeSystems/_helpers";
 /**
- * Gets the amount claimed by a gauge at a specific epoch.
+ * Returns how much a gauge has already pulled for an epoch.
  *
  * @param chainId - The chain/network to use.
- * @param gauge - Address of the gauge.
- * @param epoch - The epoch to query.
+ * @param gaugeSystem - Gauge system id ("raacgauges" or "rwagauges") or a GaugeRewardsDistributor address.
+ * @param gaugeAddressOrId - Address or config id of the gauge.
+ * @param epoch - Epoch start timestamp, seconds.
  * @param provider - Optional ethers.js Provider instance.
- * @returns Amount claimed at the epoch (bigint).
+ * @returns The claimed amount, base units.
  */
-export declare const getClaimedAtEpoch: (chainId: ChainId, gauge: string, epoch: string | number | bigint, provider?: Provider) => Promise<bigint>;
+export declare const getClaimedAtEpoch: (chainId: ChainId, gaugeSystem: GaugeSystemRef, gaugeAddressOrId: string, epoch: string | number | bigint, provider?: Provider) => Promise<bigint>;

package/dist/types/contracts/governance/distributor/getDepositedAtEpoch.d.ts

@@ -1,12 +1,14 @@
 import { Provider } from "ethers";
 import { ChainId } from "../../../configs/chains";
+import { GaugeSystemRef } from "../gaugeSystems/_helpers";
 /**
- * Gets the amount of a token deposited at a specific epoch.
+ * Returns the rewards deposited into the distributor for an epoch.
  *
  * @param chainId - The chain/network to use.
+ * @param gaugeSystem - Gauge system id ("raacgauges" or "rwagauges") or a GaugeRewardsDistributor address.
  * @param token - Address of the reward token.
- * @param epoch - The epoch to query.
+ * @param epoch - Epoch start timestamp, seconds.
  * @param provider - Optional ethers.js Provider instance.
- * @returns Amount deposited at the epoch (bigint).
+ * @returns The deposited amount, base units.
  */
-export declare const getDepositedAtEpoch: (chainId: ChainId, token: string, epoch: string | number | bigint, provider?: Provider) => Promise<bigint>;
+export declare const getDepositedAtEpoch: (chainId: ChainId, gaugeSystem: GaugeSystemRef, token: string, epoch: string | number | bigint, provider?: Provider) => Promise<bigint>;

package/dist/types/contracts/governance/distributor/getDustLastProcessedEpoch.d.ts

@@ -0,0 +1,12 @@
+import { Provider } from "ethers";
+import { ChainId } from "../../../configs/chains";
+import { GaugeSystemRef } from "../gaugeSystems/_helpers";
+/**
+ * Returns the cursor of the last epoch swept by `withdrawDust`.
+ *
+ * @param chainId - The chain/network to use.
+ * @param gaugeSystem - Gauge system id ("raacgauges" or "rwagauges") or a GaugeRewardsDistributor address.
+ * @param provider - Optional ethers.js Provider instance.
+ * @returns The epoch timestamp, seconds.
+ */
+export declare const getDustLastProcessedEpoch: (chainId: ChainId, gaugeSystem: GaugeSystemRef, provider?: Provider) => Promise<bigint>;

package/dist/types/contracts/governance/distributor/getGaugeController.d.ts

@@ -1,10 +1,12 @@
 import { Provider } from "ethers";
 import { ChainId } from "../../../configs/chains";
+import { GaugeSystemRef } from "../gaugeSystems/_helpers";
 /**
- * Gets the gauge controller address used by the distributor.
+ * Returns the GaugeController the distributor reads weights from.
  *
  * @param chainId - The chain/network to use.
+ * @param gaugeSystem - Gauge system id ("raacgauges" or "rwagauges") or a GaugeRewardsDistributor address.
  * @param provider - Optional ethers.js Provider instance.
- * @returns Gauge controller address (string).
+ * @returns The controller address.
  */
-export declare const getGaugeController: (chainId: ChainId, provider?: Provider) => Promise<string>;
+export declare const getGaugeController: (chainId: ChainId, gaugeSystem: GaugeSystemRef, provider?: Provider) => Promise<string>;

package/dist/types/contracts/governance/distributor/getLastClaimedEpoch.d.ts

@@ -1,11 +1,13 @@
 import { Provider } from "ethers";
 import { ChainId } from "../../../configs/chains";
+import { GaugeSystemRef } from "../gaugeSystems/_helpers";
 /**
- * Gets the last epoch claimed for a gauge.
+ * Returns the epoch a gauge's next claim starts walking from.
  *
  * @param chainId - The chain/network to use.
- * @param gauge - Address of the gauge.
+ * @param gaugeSystem - Gauge system id ("raacgauges" or "rwagauges") or a GaugeRewardsDistributor address.
+ * @param gaugeAddressOrId - Address or config id of the gauge.
  * @param provider - Optional ethers.js Provider instance.
- * @returns Last claimed epoch (bigint).
+ * @returns The epoch timestamp, seconds.
  */
-export declare const getLastClaimedEpoch: (chainId: ChainId, gauge: string, provider?: Provider) => Promise<bigint>;
+export declare const getLastClaimedEpoch: (chainId: ChainId, gaugeSystem: GaugeSystemRef, gaugeAddressOrId: string, provider?: Provider) => Promise<bigint>;

package/dist/types/contracts/governance/distributor/getMaxClaimBound.d.ts

@@ -0,0 +1,15 @@
+import { Provider } from "ethers";
+import { ChainId } from "../../../configs/chains";
+import { GaugeSystemRef } from "../gaugeSystems/_helpers";
+/**
+ * Reads whether claim walks are capped and the cap in epochs.
+ *
+ * @param chainId - The chain/network to use.
+ * @param gaugeSystem - Gauge system id ("raacgauges" or "rwagauges") or a GaugeRewardsDistributor address.
+ * @param provider - Optional ethers.js Provider instance.
+ * @returns enabled flag and maxEpochs.
+ */
+export declare const getMaxClaimBound: (chainId: ChainId, gaugeSystem: GaugeSystemRef, provider?: Provider) => Promise<{
+    enabled: boolean;
+    maxEpochs: bigint;
+}>;

package/dist/types/contracts/governance/distributor/getPeriodDuration.d.ts

@@ -1,10 +1,12 @@
 import { Provider } from "ethers";
 import { ChainId } from "../../../configs/chains";
+import { GaugeSystemRef } from "../gaugeSystems/_helpers";
 /**
- * Gets the distributor's period (epoch) duration in seconds.
+ * Returns the distributor's period duration.
  *
  * @param chainId - The chain/network to use.
+ * @param gaugeSystem - Gauge system id ("raacgauges" or "rwagauges") or a GaugeRewardsDistributor address.
  * @param provider - Optional ethers.js Provider instance.
- * @returns Period duration in seconds (bigint).
+ * @returns The period duration, seconds.
  */
-export declare const getPeriodDuration: (chainId: ChainId, provider?: Provider) => Promise<bigint>;
+export declare const getPeriodDuration: (chainId: ChainId, gaugeSystem: GaugeSystemRef, provider?: Provider) => Promise<bigint>;

package/dist/types/contracts/governance/distributor/getRewardToken.d.ts

@@ -1,10 +1,12 @@
 import { Provider } from "ethers";
 import { ChainId } from "../../../configs/chains";
+import { GaugeSystemRef } from "../gaugeSystems/_helpers";
 /**
- * Gets the reward token address used by the distributor.
+ * Returns the single reward token the distributor pays out.
  *
  * @param chainId - The chain/network to use.
+ * @param gaugeSystem - Gauge system id ("raacgauges" or "rwagauges") or a GaugeRewardsDistributor address.
  * @param provider - Optional ethers.js Provider instance.
- * @returns Reward token address (string).
+ * @returns The reward token address.
  */
-export declare const getRewardToken: (chainId: ChainId, provider?: Provider) => Promise<string>;
+export declare const getRewardToken: (chainId: ChainId, gaugeSystem: GaugeSystemRef, provider?: Provider) => Promise<string>;

package/dist/types/contracts/governance/distributor/getRewardTokenInfo.d.ts

@@ -1,13 +1,15 @@
 import { Provider } from "ethers";
 import { ChainId } from "../../../configs/chains";
+import { GaugeSystemRef } from "../gaugeSystems/_helpers";
 /**
- * Gets aggregate statistics for the distributor's reward token.
+ * Reads the reward token totals and the distributor's current token balance.
  *
  * @param chainId - The chain/network to use.
+ * @param gaugeSystem - Gauge system id ("raacgauges" or "rwagauges") or a GaugeRewardsDistributor address.
  * @param provider - Optional ethers.js Provider instance.
- * @returns Object with totalDeposited, totalDistributed, totalClaimable and balance (all bigint).
+ * @returns totalDeposited, totalDistributed, totalClaimable and balance, base units.
  */
-export declare const getRewardTokenInfo: (chainId: ChainId, provider?: Provider) => Promise<{
+export declare const getRewardTokenInfo: (chainId: ChainId, gaugeSystem: GaugeSystemRef, provider?: Provider) => Promise<{
     totalDeposited: bigint;
     totalDistributed: bigint;
     totalClaimable: bigint;

package/dist/types/contracts/governance/distributor/getRewardTokenStats.d.ts

@@ -1,14 +1,16 @@
 import { Provider } from "ethers";
 import { ChainId } from "../../../configs/chains";
+import { GaugeSystemRef } from "../gaugeSystems/_helpers";
 /**
- * Reads the rewardTokenInfo mapping entry for a given token.
+ * Reads the `rewardTokenInfo` mapping entry for a token.
  *
  * @param chainId - The chain/network to use.
+ * @param gaugeSystem - Gauge system id ("raacgauges" or "rwagauges") or a GaugeRewardsDistributor address.
  * @param token - Address of the reward token.
  * @param provider - Optional ethers.js Provider instance.
- * @returns Object with totalDeposited, totalDistributed and totalClaimable (all bigint).
+ * @returns totalDeposited, totalDistributed and totalClaimable, base units.
  */
-export declare const getRewardTokenStats: (chainId: ChainId, token: string, provider?: Provider) => Promise<{
+export declare const getRewardTokenStats: (chainId: ChainId, gaugeSystem: GaugeSystemRef, token: string, provider?: Provider) => Promise<{
     totalDeposited: bigint;
     totalDistributed: bigint;
     totalClaimable: bigint;

package/dist/types/contracts/governance/distributor/index.d.ts

@@ -4,13 +4,16 @@ export * from "./deposit";
 export * from "./getClaimableForGauge";
 export * from "./getClaimedAtEpoch";
 export * from "./getDepositedAtEpoch";
+export * from "./getDustLastProcessedEpoch";
 export * from "./getGaugeController";
 export * from "./getLastClaimedEpoch";
+export * from "./getMaxClaimBound";
 export * from "./getPeriodDuration";
 export * from "./getRewardToken";
 export * from "./getRewardTokenInfo";
 export * from "./getRewardTokenStats";
-export * from "./getStartEpoch";
 export * from "./setController";
+export * from "./setLastClaimedEpoch";
+export * from "./setMaxClaimBound";
+export * from "./withdrawDust";
 export * from "./withdrawRemovedGaugeRewards";
-export * from "./withdrawUnallocatedRewards";

package/dist/types/contracts/governance/distributor/setController.d.ts

@@ -1,12 +1,13 @@
-import { Signer } from "ethers";
+import { ethers, Signer } from "ethers";
 import { ChainId } from "../../../configs/chains";
+import { GaugeSystemRef } from "../gaugeSystems/_helpers";
 /**
- * Sets the gauge controller for the distributor.
- * Requires DEFAULT_ADMIN_ROLE.
+ * Points the distributor at a different GaugeController. Requires DEFAULT_ADMIN_ROLE.
  *
  * @param chainId - The chain/network to use.
- * @param controller - Address of the new gauge controller.
+ * @param gaugeSystem - Gauge system id ("raacgauges" or "rwagauges") or a GaugeRewardsDistributor address.
+ * @param controller - Address of the new controller.
  * @param signer - An ethers.js Signer instance (required).
- * @returns Transaction after it has been mined.
+ * @returns The transaction after it has been mined.
  */
-export declare const setController: (chainId: ChainId, controller: string, signer: Signer) => Promise<any>;
+export declare const setController: (chainId: ChainId, gaugeSystem: GaugeSystemRef, controller: string, signer: Signer) => Promise<ethers.ContractTransactionResponse>;

package/dist/types/contracts/governance/distributor/setLastClaimedEpoch.d.ts

@@ -0,0 +1,13 @@
+import { ethers, Signer } from "ethers";
+import { ChainId } from "../../../configs/chains";
+import { GaugeSystemRef } from "../gaugeSystems/_helpers";
+/**
+ * Bootstraps a new gauge's claim checkpoint. Requires CONTROLLER_ROLE; the controller calls it from `addGauge`.
+ *
+ * @param chainId - The chain/network to use.
+ * @param gaugeSystem - Gauge system id ("raacgauges" or "rwagauges") or a GaugeRewardsDistributor address.
+ * @param gaugeAddressOrId - Address or config id of the gauge.
+ * @param signer - An ethers.js Signer instance (required).
+ * @returns The transaction after it has been mined.
+ */
+export declare const setLastClaimedEpoch: (chainId: ChainId, gaugeSystem: GaugeSystemRef, gaugeAddressOrId: string, signer: Signer) => Promise<ethers.ContractTransactionResponse>;

package/dist/types/contracts/governance/distributor/setMaxClaimBound.d.ts

@@ -0,0 +1,13 @@
+import { ethers, Signer } from "ethers";
+import { ChainId } from "../../../configs/chains";
+import { GaugeSystemRef } from "../gaugeSystems/_helpers";
+/**
+ * Caps how many epochs a claim walks per call (MAX_EPOCHS). Requires DISTRIBUTOR_ADMIN.
+ *
+ * @param chainId - The chain/network to use.
+ * @param gaugeSystem - Gauge system id ("raacgauges" or "rwagauges") or a GaugeRewardsDistributor address.
+ * @param enabled - True to cap claim walks.
+ * @param signer - An ethers.js Signer instance (required).
+ * @returns The transaction after it has been mined.
+ */
+export declare const setMaxClaimBound: (chainId: ChainId, gaugeSystem: GaugeSystemRef, enabled: boolean, signer: Signer) => Promise<ethers.ContractTransactionResponse>;

package/dist/types/contracts/governance/distributor/withdrawDust.d.ts

@@ -0,0 +1,13 @@
+import { ethers, Signer } from "ethers";
+import { ChainId } from "../../../configs/chains";
+import { GaugeSystemRef } from "../gaugeSystems/_helpers";
+/**
+ * Sweeps leftover rewards from fully settled epochs to a recipient. Requires DEFAULT_ADMIN_ROLE. Reverts when there is nothing new to sweep.
+ *
+ * @param chainId - The chain/network to use.
+ * @param gaugeSystem - Gauge system id ("raacgauges" or "rwagauges") or a GaugeRewardsDistributor address.
+ * @param recipient - Address that receives the dust.
+ * @param signer - An ethers.js Signer instance (required).
+ * @returns The transaction after it has been mined.
+ */
+export declare const withdrawDust: (chainId: ChainId, gaugeSystem: GaugeSystemRef, recipient: string, signer: Signer) => Promise<ethers.ContractTransactionResponse>;

package/dist/types/contracts/governance/distributor/withdrawRemovedGaugeRewards.d.ts

@@ -1,13 +1,14 @@
-import { Signer } from "ethers";
+import { ethers, Signer } from "ethers";
 import { ChainId } from "../../../configs/chains";
+import { GaugeSystemRef } from "../gaugeSystems/_helpers";
 /**
- * Withdraws rewards belonging to a removed gauge to a recipient.
- * Requires DEFAULT_ADMIN_ROLE.
+ * Redirects a removed gauge's unclaimed entitlement to a recipient. Requires CONTROLLER_ROLE: the controller calls it from `removeGauge`, so admins normally use `governance.controller.removeGauge`.
  *
  * @param chainId - The chain/network to use.
- * @param gauge - Address of the removed gauge.
- * @param recipient - Address to receive the withdrawn rewards.
+ * @param gaugeSystem - Gauge system id ("raacgauges" or "rwagauges") or a GaugeRewardsDistributor address.
+ * @param gaugeAddressOrId - Address or config id of the gauge.
+ * @param recipient - Address that receives the redirected rewards.
  * @param signer - An ethers.js Signer instance (required).
- * @returns Transaction after it has been mined.
+ * @returns The transaction after it has been mined.
  */
-export declare const withdrawRemovedGaugeRewards: (chainId: ChainId, gauge: string, recipient: string, signer: Signer) => Promise<any>;
+export declare const withdrawRemovedGaugeRewards: (chainId: ChainId, gaugeSystem: GaugeSystemRef, gaugeAddressOrId: string, recipient: string, signer: Signer) => Promise<ethers.ContractTransactionResponse>;

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

@@ -0,0 +1,61 @@
+import { Provider } from "ethers";
+import { ChainId } from "../../../configs/chains";
+import { BaseGauge, GaugeController } from "../../../typechain-types";
+export declare const SECONDS_PER_YEAR: bigint;
+/** Where the main reward token's yearly emission is read from. */
+export type GaugeRewardSource = "stream" | "epoch";
+export interface GaugeApyPrices {
+    /** USD price of one staking token. */
+    stakingTokenPriceUSD: number;
+    /** USD price of one 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, formatted. */
+    yearlyRewards: string;
+    priceUSD: number | null;
+    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;
+    stakingDecimals: number;
+    totalSupply: bigint;
+    workingSupply: bigint;
+    minBoost: bigint;
+    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: 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,14 @@
+import { Provider, Signer } from "ethers";
+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;
+}
+/**
+ * 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/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/getApy.d.ts

@@ -0,0 +1,41 @@
+import { Provider } from "ethers";
+import { ChainId } from "../../../configs/chains";
+import { GaugeApyOptions, GaugeApyPrices, GaugeRewardSource, RewardTokenApy } from "./_apy";
+export type { GaugeApyOptions, GaugeApyPrices, GaugeRewardSource, RewardTokenApy } from "./_apy";
+export interface GaugeApy {
+    gauge: string;
+    stakingToken: string;
+    rewardSource: GaugeRewardSource;
+    /** Raw staked tokens, formatted. */
+    totalStaked: string;
+    /** Sum of boosted working balances, formatted. Main rewards are shared over this. */
+    workingSupply: string;
+    tvlUSD: number;
+    /** Boost multiplier bounds, e.g. 1 and 2.5. */
+    minBoost: number;
+    maxBoost: number;
+    /** 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. */
+    totalMinApy: number | null;
+    /** maxApy + extraApy. */
+    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 the staking token and of each reward token (see `getRewardTokens`).
+ * @param options - Optional reward source: "epoch" (default) or "stream".
+ * @param provider - Optional ethers.js Provider instance.
+ * @returns Min, max and extra APY with the supplies and per-token yearly rewards 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/getEarnedExtraReward.d.ts

@@ -0,0 +1,13 @@
+import { Provider } from "ethers";
+import { ChainId } from "../../../configs/chains";
+/**
+ * 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 amount (raw, base units).
+ */
+export declare const getEarnedExtraReward: (chainId: ChainId, gaugeAddressOrId: string, token: string, userAddress: string, provider?: Provider) => Promise<bigint>;

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

@@ -1,12 +1,13 @@
 import { Provider } from "ethers";
 import { ChainId } from "../../../configs/chains";
 /**
- * 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).
  */
-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<bigint>;

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

@@ -0,0 +1,23 @@
+import { Provider } from "ethers";
+import { ChainId } from "../../../configs/chains";
+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: bigint;
+    workingSupply: bigint;
+    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.
+ */
+export declare const getGaugeData: (chainId: ChainId, gaugeAddressOrId: string, provider?: Provider) => Promise<GaugeData>;

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/getPendingRewards.d.ts

@@ -1,12 +1,13 @@
 import { Provider } from "ethers";
 import { ChainId } from "../../../configs/chains";
 /**
- * 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).
  */
-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<bigint>;

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/getUserApy.d.ts

@@ -0,0 +1,44 @@
+import { Provider } from "ethers";
+import { ChainId } from "../../../configs/chains";
+import { GaugeApyOptions, GaugeApyPrices } from "./_apy";
+export interface UserApyPosition {
+    /** Raw stake, formatted. */
+    balance: string;
+    /** Boosted working balance, formatted. */
+    workingBalance: string;
+    /** Effective boost multiplier, between the controller's min and max (e.g. 1 to 2.5). Null with no stake. */
+    boost: number | 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 the staking token and of each reward token (see `getRewardTokens`).
+ * @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 and APY, 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?: string | number | bigint;
+}, provider?: Provider) => Promise<UserGaugeApy>;