@raac/rpc 2.0.0-beta.5 → 2.0.0-beta.7

package/dist/types/contracts/zeno/pause.d.ts

@@ -0,0 +1,18 @@
+import { Signer } from "ethers";
+import { ChainId } from "../../configs/chains";
+/**
+ * Halts `buy` on an auction. PAUSER_ROLE only. A Dutch price keeps falling while paused.
+ * @param chainId The chain id.
+ * @param auction The auction address.
+ * @param signer A PAUSER_ROLE holder.
+ * @returns The transaction receipt.
+ */
+export declare function pause(chainId: ChainId, auction: string, signer: Signer): Promise<import("ethers").ContractTransactionReceipt>;
+/**
+ * Resumes `buy` on an auction. DEFAULT_ADMIN_ROLE only, so a compromised pauser cannot reopen buying.
+ * @param chainId The chain id.
+ * @param auction The auction address.
+ * @param signer A DEFAULT_ADMIN_ROLE holder.
+ * @returns The transaction receipt.
+ */
+export declare function unpause(chainId: ChainId, auction: string, signer: Signer): Promise<import("ethers").ContractTransactionReceipt>;

package/dist/types/contracts/zeno/priceAt.d.ts

@@ -0,0 +1,20 @@
+/** The auction terms that set its price. All values as the contract stores them. */
+export interface AuctionPriceTerms {
+    /** UNIX timestamp (seconds). */
+    startTime: bigint;
+    /** UNIX timestamp (seconds). */
+    endTime: bigint;
+    /** Payment token base units per whole ZENO. */
+    startingPrice: bigint;
+    /** Payment token base units per whole ZENO. */
+    reservePrice: bigint;
+}
+/**
+ * An auction's price at `now`, computed locally without an RPC call. Mirrors `Auction.getPrice()` exactly, truncating
+ * division included: the starting price before the window, the reserve from `endTime` on, a linear fall between.
+ *
+ * @param terms The auction's price terms, e.g. from `getAuctionState` or the subgraph's `BondAuction`.
+ * @param now UNIX timestamp (seconds). Use the latest block timestamp to match the contract exactly.
+ * @returns The price in payment token base units per whole ZENO.
+ */
+export declare const priceAt: (terms: AuctionPriceTerms, now: bigint) => bigint;

package/dist/types/contracts/zeno/quoteBuy.d.ts

@@ -0,0 +1,34 @@
+export interface BuyQuoteInput {
+    /** Price in payment token base units per whole ZENO, from `priceAt` or `getPrice`. */
+    price: bigint;
+    /** Payment token to spend, in base units. */
+    paymentAmount: bigint;
+    /** ZENO decimals, equal to the underlying's. */
+    zenoDecimals: number;
+    /** ZENO left to sell, in base units (`totalRemaining`). */
+    totalRemaining: bigint;
+    /** Tolerance below `zenoOut` for `minZenoOut`, in basis points (10000 = 100%). Defaults to 0. */
+    slippageBps?: bigint;
+}
+export interface BuyQuote {
+    /** ZENO minted for `paymentAmount` at `price`, in base units. */
+    zenoOut: bigint;
+    /** `zenoOut` less the slippage tolerance; pass it to `buy` as `minZenoOut`. */
+    minZenoOut: bigint;
+    /** The largest payment `buy` accepts at `price`; anything above mints more than `totalRemaining` and reverts. */
+    maxPayment: bigint;
+    /** True when `paymentAmount` is above `maxPayment`. */
+    exceedsRemaining: boolean;
+}
+/**
+ * What a buy mints, computed locally without an RPC call with `Auction.buy`'s integer maths:
+ * `zenoOut = paymentAmount * 10^zenoDecimals / price`, truncated.
+ *
+ * A Dutch price only falls, so a buy mined after the quote mints at least `zenoOut`; `minZenoOut` guards against a
+ * fixed price or a stale quote. The same fall means a payment at exactly `maxPayment` can revert a block later, so
+ * leave headroom when buying out the remainder.
+ *
+ * @param input The price, payment, ZENO decimals, remaining supply and slippage tolerance.
+ * @returns The ZENO out, the `minZenoOut` to send, and the payment ceiling.
+ */
+export declare const quoteBuy: (input: BuyQuoteInput) => BuyQuote;

package/dist/types/contracts/zeno/redeem.d.ts

@@ -0,0 +1,20 @@
+import { Signer } from "ethers";
+import { ChainId } from "../../configs/chains";
+/**
+ * Redeems ZENO 1:1 for the underlying. Reverts before maturity, and while the bond's collateral is short of its
+ * outstanding supply (`getBondState(...).isFunded`).
+ * @param chainId The chain id.
+ * @param zeno The ZENO bond address.
+ * @param amount ZENO to redeem, in base units.
+ * @param signer The holder, who receives the underlying.
+ * @returns The transaction receipt.
+ */
+export declare function redeem(chainId: ChainId, zeno: string, amount: bigint, signer: Signer): Promise<import("ethers").ContractTransactionReceipt>;
+/**
+ * Redeems the signer's whole ZENO balance for the underlying. Same conditions as `redeem`.
+ * @param chainId The chain id.
+ * @param zeno The ZENO bond address.
+ * @param signer The holder, who receives the underlying.
+ * @returns The transaction receipt.
+ */
+export declare function redeemAll(chainId: ChainId, zeno: string, signer: Signer): Promise<import("ethers").ContractTransactionReceipt>;

package/dist/types/contracts/zeno/setAuction.d.ts

@@ -0,0 +1,13 @@
+import { Signer } from "ethers";
+import { ChainId } from "../../configs/chains";
+/**
+ * Binds a ZENO to the auction that sells it. One-shot, ZENO owner only; reverts unless the auction's `zeno()` points
+ * back at this ZENO. Until it is set, the auction's buys revert.
+ * @param chainId The chain id.
+ * @param zeno The ZENO bond address.
+ * @param auction The auction created for it.
+ * @param signer The ZENO owner.
+ * @returns The transaction receipt.
+ */
+declare function setAuction(chainId: ChainId, zeno: string, auction: string, signer: Signer): Promise<import("ethers").ContractTransactionReceipt>;
+export default setAuction;

package/dist/types/contracts/zeno/sweepSurplus.d.ts

@@ -0,0 +1,14 @@
+import { Signer } from "ethers";
+import { ChainId } from "../../configs/chains";
+/**
+ * Sweeps underlying held above the ZENO's outstanding supply: unsold prefill, overpayments and post-maturity residue.
+ * ZENO owner only, and only once the bound auction has ended. `getBondState(...).sweepableSurplus` is the most it takes.
+ * @param chainId The chain id.
+ * @param zeno The ZENO bond address.
+ * @param to The recipient of the underlying.
+ * @param amount Underlying to sweep, in base units.
+ * @param signer The ZENO owner.
+ * @returns The transaction receipt.
+ */
+declare function sweepSurplus(chainId: ChainId, zeno: string, to: string, amount: bigint, signer: Signer): Promise<import("ethers").ContractTransactionReceipt>;
+export default sweepSurplus;

package/dist/types/pools/lendingPool/adapters/erc20/getERC20AdapterBalance.d.ts

@@ -1,4 +1,4 @@
-import { Signer } from "ethers";
+import { Provider, Signer } from "ethers";
 import { ChainId } from "../../../../configs/chains";
 import { TokenAmount } from "../../../../utils/amount";
 /**
@@ -6,8 +6,8 @@ import { TokenAmount } from "../../../../utils/amount";
  * @param chainId The chain id, used to look up the adapter token's decimals in the token registry.
  * @param adapterAddress The ERC20 asset adapter address.
  * @param userAddress The user.
- * @param signer The signer to read with.
+ * @param runner The signer or provider to read with. A read-only provider is enough.
  * @returns The deposited balance in base units of the adapter's token, with its registry decimals and symbol (18 decimals if the token is not in the registry).
  */
-declare function getERC20AdapterBalance(chainId: ChainId, adapterAddress: string, userAddress: string, signer: Signer): Promise<TokenAmount>;
+declare function getERC20AdapterBalance(chainId: ChainId, adapterAddress: string, userAddress: string, runner: Signer | Provider): Promise<TokenAmount>;
 export default getERC20AdapterBalance;

package/dist/types/user/_helpers.d.ts

@@ -0,0 +1,23 @@
+import { TokenAmount } from "../utils/amount";
+/**
+ * USD price of one whole token, keyed by lowercase symbol, e.g. `{ raac: 5, pmusd: 1, ireet: 0.995 }`. The app
+ * builds it with its `usePrices` hook, so the rpc and the UI value everything identically.
+ */
+export type UsdPrices = Record<string, number>;
+/** A read that settled independently of the others: its data, or why it failed. One failure never blanks the rest. */
+export type Section<T> = {
+    data: T;
+    error: null;
+} | {
+    data: null;
+    error: Error;
+};
+/** Settles one read into a {@link Section}: never rejects, so reads awaited together fail independently. */
+export declare const settled: <T>(read: Promise<T>) => Promise<Section<T>>;
+/**
+ * USD value of an amount from `prices`, by the symbol `toTokenAmount` gave it from the chain config's token registry.
+ * Throws when there is no price, so the section fails visibly instead of reading 0.
+ *
+ * @param token - The amount's asset key or token address, named in the error.
+ */
+export declare function requireUsd(prices: UsdPrices, amount: TokenAmount, token: string): number;

package/dist/types/user/computeEffectiveReturn.d.ts

@@ -0,0 +1,67 @@
+/** Whether a leg earns income or costs it. */
+export type ReturnLegKind = "earning" | "cost";
+/** What a leg earns or costs. A unit of capital earns each yield type at most once. */
+export type ReturnLegYieldType = "supply" | "gauge" | "borrow";
+/**
+ * One income stream in the user's position, as {@link computeEffectiveReturn} consumes it. Adding a venue (a new
+ * gauge, another pmUSD venue) only means adding a leg; the calculator does not change.
+ */
+export interface ReturnLeg {
+    /** Stable key, e.g. "borrow", "supply", "gauge:r-rpmdepmUSD". */
+    id: string;
+    /** Display name, e.g. "Borrow pmUSD". */
+    source: string;
+    kind: ReturnLegKind;
+    yieldType: ReturnLegYieldType;
+    /**
+     * True when the leg's value is money the user holds and counts towards net capital (supplied). False for the
+     * debt itself, and for overlays such as a gauge, whose staked value is already counted in another leg.
+     */
+    countsAsCapital: boolean;
+    /** USD value the rate applies to. Never negative. */
+    valueUsd: number;
+    /** The projected one-year rate as a fraction, e.g. 0.0077 for 0.77%. */
+    rate: number;
+    /** How `rate` is quoted: "apy" when it already compounds (borrow), "apr" when it does not (supply, gauge). */
+    rateKind: "apr" | "apy";
+}
+export interface ReturnLegWithIncome extends ReturnLeg {
+    /** Projected income over one year in USD: `valueUsd * rate`, negative for a cost leg. */
+    income1y: number;
+}
+export interface EffectiveReturnInput {
+    legs: readonly ReturnLeg[];
+    /** USD value of the collateral backing the debt. */
+    collateralUsd: number;
+    /**
+     * USD value of capital that earns nothing, e.g. idle pmUSD in the wallet or a non-yielding coin inside a staked
+     * LP. It is not a leg (no income, not listed in a breakdown); it only adds to net capital.
+     */
+    idleUsd?: number;
+}
+export interface EffectiveReturn {
+    /** Earning legs' income minus cost legs' cost over one year, in USD. */
+    netIncome1y: number;
+    /** `netIncome1y / debtUsd` as a fraction; null when there is no debt. */
+    onDebt: number | null;
+    /** `netIncome1y / netCapitalUsd` as a fraction; null when net capital is zero or negative. */
+    onNetCapital: number | null;
+    /** Sum of the cost legs' values. */
+    debtUsd: number;
+    /** Collateral + capital legs + idle - debt. */
+    netCapitalUsd: number;
+    legs: ReturnLegWithIncome[];
+}
+/**
+ * Projects the user's net return over one year from a list of legs. Pure: no reads.
+ *
+ *   netIncome1y  = sum(earning valueUsd * rate) - sum(cost valueUsd * rate)
+ *   onDebt       = netIncome1y / total debt
+ *   onNetCapital = netIncome1y / (collateral + capital legs + idle - total debt)
+ *
+ * The legs do not reinvest into each other, so this is a projected net return, not an APY.
+ *
+ * @param input - The legs, the collateral value and any idle capital, all in USD.
+ * @returns The net income, both returns and each leg with its own projected income.
+ */
+export declare function computeEffectiveReturn({ legs, collateralUsd, idleUsd }: EffectiveReturnInput): EffectiveReturn;

package/dist/types/user/getUserClaimables.d.ts

@@ -0,0 +1,55 @@
+import { Provider } from "ethers";
+import { ChainId } from "../configs/chains";
+import { GaugeSystemId } from "../configs/chains/chain";
+import { TokenAmount } from "../utils/amount";
+export interface ClaimableToken {
+    /** Token address. */
+    token: string;
+    amount: TokenAmount;
+}
+export interface ClaimableSource {
+    /** False when the source is not deployed on this chain. Nothing to show. */
+    available: boolean;
+    /** Tokens with a non-zero claimable amount. */
+    tokens: ClaimableToken[];
+    /** Why the source could not be read. The UI shows it on this row, never a silent zero. */
+    error: Error | null;
+}
+export interface GaugeClaimable extends ClaimableSource {
+    gauge: string;
+    id: string;
+    name: string;
+    system: GaugeSystemId;
+}
+export interface GaugeClaimables extends ClaimableSource {
+    /** One entry per configured gauge, including those with nothing to claim or a failed read. */
+    items: GaugeClaimable[];
+    /** Number of gauges with something to claim. */
+    claimableCount: number;
+}
+export interface UserClaimables {
+    chainId: ChainId;
+    user: string;
+    /** Main and extra rewards on every configured gauge of both systems. Claimed gauge RAAC goes to the liquid locker. */
+    gauges: GaugeClaimables;
+    /** veRAAC fee distributions, one token per reward token. */
+    veRAAC: ClaimableSource;
+    /** Realised RAAC in the maturity vault. */
+    maturityVault: ClaimableSource;
+    /** Bot locker rewards, every reward token. */
+    botLocker: ClaimableSource;
+}
+/**
+ * Everything a user can claim right now, across gauges, veRAAC fees, the maturity vault and the bot locker. Amounts
+ * only: the caller values them in USD with its own prices. Each source (and each gauge) is read independently, so one
+ * failing read shows as an error on that source and every other source still returns.
+ *
+ * Every configured gauge is scanned, not only those the user is staked in: a user can still have rewards after fully
+ * unstaking.
+ *
+ * @param chainId - The chain/network to use.
+ * @param user - The user's address.
+ * @param provider - Optional ethers.js Provider instance.
+ * @returns Per source: the non-zero claimable tokens, and an `error` when it failed.
+ */
+export declare const getUserClaimables: (chainId: ChainId, user: string, provider?: Provider) => Promise<UserClaimables>;

package/dist/types/user/getUserCollateral.d.ts

@@ -0,0 +1,12 @@
+import { Provider } from "ethers";
+import { ChainId } from "../configs/chains";
+import { TokenAmount } from "../utils/amount";
+/**
+ * The iREET a user has deposited as collateral in the lending pool's iREET adapter. NFT collateral is not included.
+ *
+ * @param chainId - The chain/network to use.
+ * @param user - The user's address.
+ * @param provider - Optional ethers.js Provider instance.
+ * @returns The deposited iREET, with its registry decimals and symbol.
+ */
+export declare const getUserCollateral: (chainId: ChainId, user: string, provider?: Provider) => Promise<TokenAmount>;

package/dist/types/user/getUserDebt.d.ts

@@ -0,0 +1,18 @@
+import { Provider } from "ethers";
+import { ChainId } from "../configs/chains";
+import { ScaledValue, TokenAmount } from "../utils/amount";
+export interface UserDebt {
+    /** Current debt including accrued interest, in reserve units (pmUSD). */
+    amount: TokenAmount;
+    /** WAD health factor (liquidatable below 1e18); null when there is no debt. */
+    healthFactor: ScaledValue | null;
+}
+/**
+ * The debt and health factor of a user's iREET position in the lending pool.
+ *
+ * @param chainId - The chain/network to use.
+ * @param user - The user's address.
+ * @param provider - Optional ethers.js Provider instance.
+ * @returns The debt, and the health factor when there is debt.
+ */
+export declare const getUserDebt: (chainId: ChainId, user: string, provider?: Provider) => Promise<UserDebt>;

package/dist/types/user/getUserFarming.d.ts

@@ -0,0 +1,64 @@
+import { Provider } from "ethers";
+import { ChainId } from "../configs/chains";
+import { TokenAmount } from "../utils/amount";
+import { UsdPrices } from "./_helpers";
+/** What a coin earns on its own while it sits in a pool. */
+export type UnderlyingYield = 
+/** Earns the lending pool supply rate (RpmUSD, DEpmUSD), wherever it sits. */
+"supply"
+/** Earns nothing on its own (pmUSD, RAAC; iREET for now, with fixed pricing). Counts only as capital. */
+ | "none";
+export interface FarmingPoolCoin {
+    asset: string;
+    /** The user's share of the pool's balance of this coin, through LP in the wallet and staked in gauges. */
+    amount: TokenAmount;
+    valueUsd: number;
+    yield: UnderlyingYield;
+}
+export interface FarmingPool {
+    /** Curve pool id in the chain config. */
+    pool: string;
+    address: string;
+    /** LP held in the wallet. */
+    walletLp: TokenAmount;
+    /** LP staked in the pool's gauges. */
+    stakedLp: TokenAmount;
+    /** The user's share of each coin; empty when the user holds none of the pool's LP. */
+    coins: FarmingPoolCoin[];
+}
+export interface FarmingGauge {
+    /** Gauge id in the chain config. */
+    id: string;
+    gauge: string;
+    name: string;
+    pool: string;
+    /** LP staked (raw balance, not boosted). */
+    staked: TokenAmount;
+    /** Staked LP valued through the pool's coins at the passed prices. */
+    valueUsd: number;
+    /** The user's current boosted reward APR as a fraction; null with no stake. */
+    apr: number | null;
+}
+export interface UserFarming {
+    pools: FarmingPool[];
+    /** Every gauge on a read pool, including those the user has no stake in. */
+    gauges: FarmingGauge[];
+    /** Pools that could not be read. They and their gauges are left out of `pools` and `gauges`. */
+    errors: {
+        pool: string;
+        error: Error;
+    }[];
+}
+/**
+ * A user's Curve LP and gauge positions: every configured Curve pool that a configured gauge stakes, the user's share
+ * of each pool's coins, and their stake and boosted APR in each gauge. Each pool is read independently, so one failing
+ * pool shows in `errors` and the rest still return. Reserves, prices and APRs are only read for pools the user holds.
+ *
+ * @param chainId - The chain/network to use.
+ * @param user - The user's address.
+ * @param prices - USD per whole token, keyed by lowercase symbol. Needs every coin of a pool the user holds, and the
+ *   reward tokens of a gauge the user is staked in.
+ * @param provider - Optional ethers.js Provider instance.
+ * @returns The pools and gauges read, and the pools that failed.
+ */
+export declare const getUserFarming: (chainId: ChainId, user: string, prices: UsdPrices, provider?: Provider) => Promise<UserFarming>;

package/dist/types/user/getUserGovernance.d.ts

@@ -0,0 +1,20 @@
+import { Provider } from "ethers";
+import { ChainId } from "../configs/chains";
+import { TokenAmount } from "../utils/amount";
+export interface UserGovernance {
+    votingPower: TokenAmount;
+    totalVotingPower: TokenAmount;
+    /** votingPower / totalVotingPower as a fraction; null when the total is zero. */
+    share: number | null;
+    /** RAAC locked in veRAAC. */
+    locked: TokenAmount;
+}
+/**
+ * A user's veRAAC governance position: voting power, its share of the total, and the RAAC locked.
+ *
+ * @param chainId - The chain/network to use.
+ * @param user - The user's address.
+ * @param provider - Optional ethers.js Provider instance.
+ * @returns The voting power, total voting power, share and locked RAAC.
+ */
+export declare const getUserGovernance: (chainId: ChainId, user: string, provider?: Provider) => Promise<UserGovernance>;

package/dist/types/user/getUserPortfolio.d.ts

@@ -0,0 +1,61 @@
+import { Provider } from "ethers";
+import { ChainId } from "../configs/chains";
+import { ScaledValue, TokenAmount } from "../utils/amount";
+import { EffectiveReturn, ReturnLeg } from "./computeEffectiveReturn";
+import { UserDebt } from "./getUserDebt";
+import { UserWalletBalances } from "./getUserWalletBalances";
+import { UserFarming } from "./getUserFarming";
+import { UserGovernance } from "./getUserGovernance";
+import { Section, UsdPrices } from "./_helpers";
+export interface PortfolioCollateral {
+    /** iREET deposited in the lending pool's iREET adapter. */
+    amount: TokenAmount;
+    valueUsd: number;
+}
+export interface PortfolioDebt extends UserDebt {
+    valueUsd: number;
+}
+export interface PortfolioRates {
+    /** Current borrow rate (APR) as a ray: what the debt accrues per second, e.g. for interest per day. */
+    borrowRate: ScaledValue;
+    /** Projected borrow APY as a ray (the usage index compounds: e^rate - 1). */
+    borrowApy: ScaledValue;
+    /** Projected supply APY as a ray (the liquidity index accrues linearly, so it equals the supply rate). */
+    supplyApy: ScaledValue;
+}
+export interface PortfolioWallet extends UserWalletBalances {
+    /** RpmUSD + DEpmUSD in the wallet, in USD: the "Supplied" of the borrow/lend position panel. */
+    suppliedUsd: number;
+    idleUsd: number;
+}
+export interface UserPortfolio {
+    chainId: ChainId;
+    user: string;
+    collateral: Section<PortfolioCollateral>;
+    debt: Section<PortfolioDebt>;
+    rates: Section<PortfolioRates>;
+    wallet: Section<PortfolioWallet>;
+    farming: Section<UserFarming>;
+    governance: Section<UserGovernance>;
+    /** Collateral value + wallet RpmUSD + wallet DEpmUSD - debt, in USD. Lending pool only: LP and gauge positions are not included. */
+    netPositionUsd: Section<number>;
+    /** The legs the effective return is computed from; empty when any read it needs failed. */
+    legs: ReturnLeg[];
+    effectiveReturn: Section<EffectiveReturn>;
+}
+/**
+ * The user's position across the app: iREET collateral, debt and health factor, wallet RpmUSD/DEpmUSD/pmUSD, LP and
+ * gauge positions, veRAAC governance power, and the projected effective return built from them. Each part is read
+ * independently, so one failing read shows as an `error` on that part and the rest still return.
+ *
+ * Only the user's position data is returned; pool parameters such as the liquidation threshold stay with the callers
+ * that need them. iREET is the only collateral read (NFT positions are out of scope).
+ *
+ * @param chainId - The chain/network to use.
+ * @param user - The user's address.
+ * @param prices - USD per whole token, keyed by lowercase symbol. iREET, pmUSD, RpmUSD, DEpmUSD and RAAC are needed,
+ *   plus every coin of a Curve pool the user holds.
+ * @param provider - Optional ethers.js Provider instance. Read-only is enough.
+ * @returns Each part as `{ data, error }`, the effective return legs, and the computed effective return.
+ */
+export declare const getUserPortfolio: (chainId: ChainId, user: string, prices: UsdPrices, provider?: Provider) => Promise<UserPortfolio>;

package/dist/types/user/getUserWalletBalances.d.ts

@@ -0,0 +1,20 @@
+import { Provider } from "ethers";
+import { ChainId } from "../configs/chains";
+import { TokenAmount } from "../utils/amount";
+export interface UserWalletBalances {
+    /** RpmUSD in the wallet, including the liquidity index. */
+    rtoken: TokenAmount;
+    /** DEpmUSD in the wallet, including interest. */
+    detoken: TokenAmount;
+    /** Idle pmUSD in the wallet. Earns nothing. */
+    pmusd: TokenAmount;
+}
+/**
+ * The lending tokens a user holds in their wallet: RpmUSD, DEpmUSD and idle pmUSD.
+ *
+ * @param chainId - The chain/network to use.
+ * @param user - The user's address.
+ * @param provider - Optional ethers.js Provider instance.
+ * @returns Each balance, with its registry decimals and symbol.
+ */
+export declare const getUserWalletBalances: (chainId: ChainId, user: string, provider?: Provider) => Promise<UserWalletBalances>;

package/dist/types/user/index.d.ts

@@ -0,0 +1,9 @@
+export * from "./computeEffectiveReturn";
+export * from "./getUserClaimables";
+export * from "./getUserCollateral";
+export * from "./getUserDebt";
+export * from "./getUserFarming";
+export * from "./getUserGovernance";
+export * from "./getUserPortfolio";
+export * from "./getUserWalletBalances";
+export type { UsdPrices, Section } from "./_helpers";

package/dist/types/utils/amount.d.ts

@@ -57,6 +57,13 @@ export declare function parseAmount(text: string, decimals: number): bigint;
  * @returns The decimal string, e.g. `"1.5"` or `"2.0"`.
  */
 export declare function toDecimalString(amount: ScaledValue): string;
+/**
+ * An amount or scaled value as a JavaScript number, for USD and rate maths. Lossy past about 15 significant digits,
+ * so keep on-chain values as `bigint` and use this only for computed figures.
+ * @param amount The amount or scaled value, e.g. a ray rate of 3.5e25 becomes 0.035.
+ * @returns The value in whole units.
+ */
+export declare function toNumber(amount: ScaledValue): number;
 /**
  * Converts an amount to a JSON-safe form, since `bigint` does not survive `JSON.stringify`.
  * @param amount The amount.

package/dist/types/utils/contracts.d.ts

@@ -544,3 +544,5 @@ declare const _default: {
     };
 };
 export default _default;
+/** Whether a config address is set and deployed: a valid, non-zero address. */
+export declare const isDeployed: (address: string | null | undefined) => address is string;

package/dist/user/_helpers.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.settled = void 0;
+exports.requireUsd = requireUsd;
+const amount_1 = require("../utils/amount");
+/** Settles one read into a {@link Section}: never rejects, so reads awaited together fail independently. */
+const settled = (read) => read.then((data) => ({ data, error: null }), (reason) => ({ data: null, error: reason instanceof Error ? reason : new Error(String(reason)) }));
+exports.settled = settled;
+/**
+ * USD value of an amount from `prices`, by the symbol `toTokenAmount` gave it from the chain config's token registry.
+ * Throws when there is no price, so the section fails visibly instead of reading 0.
+ *
+ * @param token - The amount's asset key or token address, named in the error.
+ */
+function requireUsd(prices, amount, token) {
+    if (amount.symbol === undefined)
+        throw new Error(`No USD price for ${token}: it has no symbol in the chain config's assets`);
+    const price = prices[amount.symbol.toLowerCase()];
+    if (typeof price !== "number" || !Number.isFinite(price))
+        throw new Error(`No USD price for ${amount.symbol}`);
+    return (0, amount_1.toNumber)(amount) * price;
+}

package/dist/user/computeEffectiveReturn.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.computeEffectiveReturn = computeEffectiveReturn;
+/**
+ * Projects the user's net return over one year from a list of legs. Pure: no reads.
+ *
+ *   netIncome1y  = sum(earning valueUsd * rate) - sum(cost valueUsd * rate)
+ *   onDebt       = netIncome1y / total debt
+ *   onNetCapital = netIncome1y / (collateral + capital legs + idle - total debt)
+ *
+ * The legs do not reinvest into each other, so this is a projected net return, not an APY.
+ *
+ * @param input - The legs, the collateral value and any idle capital, all in USD.
+ * @returns The net income, both returns and each leg with its own projected income.
+ */
+function computeEffectiveReturn({ legs, collateralUsd, idleUsd = 0 }) {
+    const withIncome = legs.map((leg) => {
+        const income = leg.valueUsd * leg.rate;
+        return { ...leg, income1y: leg.kind === "cost" ? -income : income };
+    });
+    const netIncome1y = withIncome.reduce((sum, leg) => sum + leg.income1y, 0);
+    const debtUsd = legs.filter((leg) => leg.kind === "cost").reduce((sum, leg) => sum + leg.valueUsd, 0);
+    const capitalUsd = legs.filter((leg) => leg.countsAsCapital).reduce((sum, leg) => sum + leg.valueUsd, 0);
+    const netCapitalUsd = collateralUsd + capitalUsd + idleUsd - debtUsd;
+    return {
+        netIncome1y,
+        onDebt: debtUsd > 0 ? netIncome1y / debtUsd : null,
+        onNetCapital: netCapitalUsd > 0 ? netIncome1y / netCapitalUsd : null,
+        debtUsd,
+        netCapitalUsd,
+        legs: withIncome,
+    };
+}