@raac/rpc 2.0.0-beta.12 → 2.0.0-beta.14

package/dist/types/contracts/feeCollector/getState.d.ts

@@ -0,0 +1,42 @@
+import { Provider } from "ethers";
+import { ChainId } from "../../configs/chains/index";
+import { TokenAmount } from "../../utils/amount";
+/** The six places a fee type splits into, as FeeCollector names them. */
+export declare const FEE_TARGETS: readonly ["TREASURY", "REPAIR_FUND", "BURN", "VERAAC", "RAAC_CORP", "OTHER"];
+export type FeeTarget = (typeof FEE_TARGETS)[number];
+/** Fee type names used across the protocol; others show as their raw bytes32. */
+export declare const KNOWN_FEE_TYPES: string[];
+/** One fee type and how it splits, in basis points (the shares add up to at most 10_000; the contract adds the rest to the treasury). */
+export interface FeeTypeInfo {
+    id: string;
+    /** The known name, or null when `id` is not one of `KNOWN_FEE_TYPES`. */
+    name: string | null;
+    shares: Record<FeeTarget, bigint>;
+}
+/** Fees collected for one token and fee type, still owed to each target. */
+export interface CollectedFees {
+    token: string;
+    feeType: string;
+    amounts: Record<FeeTarget, TokenAmount>;
+}
+export interface FeeCollectorState {
+    paused: boolean;
+    /** Where each target's share is sent. */
+    targets: Record<FeeTarget, string>;
+    feeTypes: FeeTypeInfo[];
+    tokens: {
+        address: string;
+        symbol: string;
+        decimals: number;
+    }[];
+    /** Every token and fee type pair that has something owed. */
+    collected: CollectedFees[];
+}
+/**
+ * Reads the FeeCollector: pause state, targets, fee types and their splits, supported tokens, and what is still owed
+ * per token, fee type and target. Walks `supportedTokens(i)` until the index reverts.
+ * @param chainId The chain id.
+ * @param provider The provider to read with.
+ */
+declare function getState(chainId: ChainId, provider: Provider): Promise<FeeCollectorState>;
+export default getState;

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

@@ -0,0 +1,15 @@
+import { Provider } from "ethers";
+import { ChainId } from "../configs/chains";
+/** OpenZeppelin role ids: DEFAULT_ADMIN_ROLE is zero, every other role is the keccak of its name. */
+export declare function roleId(role: string): string;
+/**
+ * Which of an AccessControl contract's roles each account holds, e.g. to show what a Safe and a wallet may do.
+ * @param chainId The chain id, for error context.
+ * @param contractAddress The AccessControl contract.
+ * @param roles Role names ("GUARDIAN_ROLE", "DEFAULT_ADMIN_ROLE") or raw 32-byte ids.
+ * @param accounts The accounts to check.
+ * @param provider The provider to read with.
+ * @returns Keyed by lowercased account address, then by role as passed in.
+ */
+declare function getRoles(chainId: ChainId, contractAddress: string, roles: string[], accounts: string[], provider: Provider): Promise<Record<string, Record<string, boolean>>>;
+export default getRoles;

package/dist/types/contracts/housePrices/getState.d.ts

@@ -0,0 +1,24 @@
+import { Provider } from "ethers";
+import { ChainId } from "../../configs/chains/index";
+/** RAACHousePrices administration state. */
+export interface HousePricesState {
+    owner: string;
+    /** The only account allowed to call `setHousePrice(s)`. */
+    oracle: string;
+    crvUSDToUSDOracle: string;
+    /** Properties that have a price. */
+    count: number;
+    /** UNIX seconds of the last price update. */
+    lastUpdateTimestamp: number;
+    /** Contracts notified of every price change. */
+    syncers: string[];
+    /** `MAX_SYNCERS`. */
+    maxSyncers: number;
+}
+/**
+ * Reads who administers RAACHousePrices, who may set prices, and its syncers.
+ * @param chainId The chain id.
+ * @param provider The provider to read with.
+ */
+declare function getState(chainId: ChainId, provider: Provider): Promise<HousePricesState>;
+export default getState;

package/dist/types/contracts/psm/getVaultSettings.d.ts

@@ -0,0 +1,38 @@
+import { Provider } from "ethers";
+import { ChainId } from "../../configs/chains";
+/** The governance-controlled settings of a PSM vault, as stored. */
+export interface PsmVaultSettings {
+    paused: boolean;
+    /** Basis points (of 10_000). */
+    swapFee: bigint;
+    minWithdrawFee: bigint;
+    maxWithdrawFee: bigint;
+    /** Seconds a redeem request waits before it can be claimed. */
+    withdrawTime: bigint;
+    /** Seconds a ready request stays claimable. */
+    withdrawTimeLimit: bigint;
+    circuitBreakerEnabled: boolean;
+    /** 18-decimal NAV floor (1e18 = a NAV of 1.00). */
+    navFloor: bigint;
+    /** 18-decimal ratio (1e18 = 100%). */
+    reserveRatioFloor: bigint;
+    /** Base asset (pmUSD) base units. */
+    rebalanceThreshold: bigint;
+    /** Savings token base units; `MaxUint256` means no cap. */
+    depositCap: bigint;
+    savingsTokenDecimals: number;
+    baseAsset: string;
+    savingsToken: string;
+    rateProvider: string;
+    rebalancer: string;
+    baseAssetModule: string;
+}
+/**
+ * Reads a PSM vault's settings from its storage getters only. Unlike `getVaultInfo`, nothing here touches the rate
+ * provider, so it still answers when the savings token price is stale (`StalePrice`), which is when an operator
+ * needs to see and change these settings.
+ * @param chainId - The chain/network to use.
+ * @param vaultKeyOrAddress - The vault's config key (e.g. "rpsm-susds") or its deployed address.
+ * @param provider - Optional ethers.js Provider instance.
+ */
+export declare function getVaultSettings(chainId: ChainId, vaultKeyOrAddress: string, provider?: Provider): Promise<PsmVaultSettings>;

package/dist/types/contracts/treasury/getState.d.ts

@@ -0,0 +1,24 @@
+import { Provider } from "ethers";
+import { ChainId } from "../../configs/chains/index";
+import { TokenAmount } from "../../utils/amount";
+/** One token the Treasury supports. */
+export interface TreasuryToken {
+    address: string;
+    symbol: string;
+    /** Null when the token's decimals could not be read; amounts then cannot be entered safely. */
+    decimals: number | null;
+    /** What the Treasury's own accounting holds (`getBalance`); `withdraw` is limited to this. */
+    tracked: TokenAmount;
+    /** The token's actual `balanceOf(treasury)`; null when unreadable. Differs from `tracked` for tokens sent directly or rebasing. */
+    held: TokenAmount | null;
+}
+/**
+ * Reads every token the Treasury supports, with its tracked and actual balances. Walks `supportedTokens(i)` until the
+ * index reverts; any other error is thrown so a flaky node never returns a shortened list.
+ * @param chainId The chain id.
+ * @param provider The provider to read with.
+ */
+declare function getState(chainId: ChainId, provider: Provider): Promise<{
+    tokens: TreasuryToken[];
+}>;
+export default getState;

package/dist/types/minter/emissionSchedule.d.ts

@@ -0,0 +1,53 @@
+/**
+ * TypeScript port of contracts/libraries/minters/EmissionSchedule.sol. The schedule is pure (no storage), so the
+ * whole curve can be drawn without one RPC call per week; the only on-chain input is the activation timestamp
+ * (`mintingStartAtTimestamp`). All amounts are RAAC base units (18 decimals).
+ */
+/** RAAC emitted in each of the first 104 weeks. Divisible by 604800, so the per-second rate is exact. */
+export declare const BASE_WEEKLY_EMISSION: bigint;
+export declare const BASE_PER_SECOND: bigint;
+/** First week of the reduction phase. */
+export declare const WEEK_REDUCTION_START = 105;
+/** The rate drops by 5% every this many weeks. */
+export declare const WEEKS_PER_PERIOD = 13;
+/** Weeks 781 and later emit nothing. */
+export declare const LAST_EMISSION_WEEK = 780;
+/**
+ * RAAC emitted per second during a 1-based schedule week.
+ * @param week The schedule week; 0 and weeks after 780 emit nothing.
+ */
+export declare function getEmissionPerSecondForWeek(week: number): bigint;
+/**
+ * The 1-based schedule week a timestamp falls in, 0 before activation.
+ * @param activationTimestamp `mintingStartAtTimestamp`, in UNIX seconds.
+ * @param timestamp The moment to place, in UNIX seconds.
+ */
+export declare function getMintingWeekForTimestamp(activationTimestamp: number, timestamp: number): number;
+/** One week of the schedule. */
+export interface EmissionWeek {
+    week: number;
+    /** RAAC base units per second. */
+    perSecond: bigint;
+    /** RAAC base units emitted over the whole week. */
+    weekly: bigint;
+    /** RAAC base units emitted from week 1 through the end of this week. */
+    cumulative: bigint;
+}
+/** Every week of the schedule, 1 through 780, with running totals. The last `cumulative` is the lifetime emission. */
+export declare function getEmissionSchedule(): EmissionWeek[];
+/** Where a moment sits on the schedule. */
+export interface SchedulePosition {
+    /** 0 before activation, above 780 once emissions have ended. */
+    week: number;
+    /** Seconds elapsed in the current week. */
+    secondsIntoWeek: number;
+    perSecond: bigint;
+    /** RAAC base units the schedule allows from activation to `timestamp`, before any MAX_SUPPLY cap. */
+    scheduledToDate: bigint;
+}
+/**
+ * Places a moment on the schedule, e.g. to compare what has been minted with what the schedule allowed.
+ * @param activationTimestamp `mintingStartAtTimestamp`, in UNIX seconds.
+ * @param timestamp The moment to place, in UNIX seconds.
+ */
+export declare function getSchedulePosition(activationTimestamp: number, timestamp: number): SchedulePosition;

package/dist/types/pools/lendingPool/getAdminState.d.ts

@@ -0,0 +1,26 @@
+import { Provider } from "ethers";
+import { ChainId } from "../../configs/chains";
+/** The lending pool's pause state, linked contracts, collateral adapters and reserve tokens. */
+export interface LendingPoolAdminState {
+    paused: boolean;
+    primeRateOracle: string;
+    stabilityPool: string;
+    liquidationProxy: string;
+    /** The yield vault; the zero address when none is set. */
+    vault: string;
+    feeCollector: string;
+    /** Collateral adapters registered on the pool (`getAdapters()`). */
+    adapters: string[];
+    /** The asset depositors supply. */
+    reserveAsset: string;
+    rToken: string;
+    debtToken: string;
+}
+/**
+ * Reads what an operator administers on the lending pool, next to `getParameters` (risk and fee values) and
+ * `getLendingPoolInfo` (liquidity and rates).
+ * @param chainId The chain id.
+ * @param provider The provider to read with.
+ */
+declare function getAdminState(chainId: ChainId, provider: Provider): Promise<LendingPoolAdminState>;
+export default getAdminState;

package/dist/types/pools/rwaVault/getRegisteredAdapters.d.ts

@@ -0,0 +1,33 @@
+import { Provider } from "ethers";
+import { ChainId } from "../../configs/chains";
+import { TokenAmount } from "../../utils/amount";
+/** One adapter registered on the RWA vault, as the vault itself reports it. */
+export interface RegisteredVaultAdapter {
+    address: string;
+    /** `getAssetType()`: "ERC721" or "ERC20"; "unknown" when the adapter could not be read. */
+    type: string;
+    /** The asset the adapter holds: the NFT collection or the ERC20 token. */
+    token: string;
+    tokenSymbol: string;
+    /** 0 for NFTs. */
+    tokenDecimals: number;
+    /** Listed in `depositableAdapters`. */
+    depositable: boolean;
+    /** Listed in `redeemableERC721Adapters`. */
+    redeemable: boolean;
+    /** Oracle value of everything held, in crvUSD with 18 decimals; null when the adapter could not price it. */
+    value: TokenAmount | null;
+    /** Token ids held, for ERC721 adapters. */
+    tokenIds: bigint[];
+    /** Set when the adapter itself could not be read; the other asset fields are then placeholders. */
+    error?: string;
+}
+/**
+ * Every adapter registered on the RWA vault, read from the vault's own arrays rather than the chain config (which
+ * `getAdapters` returns), with deposit and redemption flags and what each adapter holds. One adapter failing to read
+ * gives a row with `error` instead of failing the whole list.
+ * @param chainId The chain id.
+ * @param provider The provider to read with.
+ */
+declare function getRegisteredAdapters(chainId: ChainId, provider: Provider): Promise<RegisteredVaultAdapter[]>;
+export default getRegisteredAdapters;

package/dist/types/pools/rwaVault/getSeedStatus.d.ts

@@ -0,0 +1,27 @@
+import { Provider } from "ethers";
+import { ChainId } from "../../configs/chains";
+/** Where the RWA vault's randomness request stands. */
+export interface SeedStatus {
+    /** The VRF consumer the vault uses; the zero address when none is set (requests then revert). */
+    consumer: string;
+    /** UNIX seconds of the last request, 0 if never. */
+    lastRequest: number;
+    /** UNIX seconds of the last fulfilment, 0 if never. */
+    lastFulfil: number;
+    /** A request exists and has not been fulfilled yet. */
+    pending: boolean;
+    /** Seconds after which a pending request may be replaced (`MAX_STALL`). */
+    maxStall: number;
+    /** Seconds required between the last fulfilment and a new public request (`vrfRequestDelay`). */
+    delay: number;
+    /** Whether anyone may call `requestRandomSeed` (`allowVRFRequest`). */
+    allowed: boolean;
+}
+/**
+ * Reads the RWA vault's VRF consumer: the last request and fulfilment and the stall window, plus the vault's own
+ * request rules. With no consumer set, the time fields are 0.
+ * @param chainId The chain id.
+ * @param provider The provider to read with.
+ */
+declare function getSeedStatus(chainId: ChainId, provider: Provider): Promise<SeedStatus>;
+export default getSeedStatus;

package/dist/types/pools/stabilityPool/getAdminState.d.ts

@@ -0,0 +1,25 @@
+import { Provider } from "ethers";
+import { ChainId } from "../../configs/chains/index";
+import type { LiquidationSplit } from "./liquidation";
+export interface StabilityPoolState {
+    owner: string;
+    paused: boolean;
+    managers: string[];
+    rwaVault: string;
+    liquidationStrategyProxy: string;
+    liquidationSwap: string;
+    feeCollector: string;
+    split: LiquidationSplit;
+    /** Seconds a withdrawal request waits before it can be withdrawn. */
+    withdrawTimelockDuration: number;
+    /** Seconds a ready request stays valid. */
+    withdrawTimelockDelay: number;
+}
+/**
+ * Owner, pause state, managers, linked contracts, liquidation split and withdraw timelock.
+ * @param chainId The chain id.
+ * @param provider The provider to read with.
+ * @throws When the configured address has no contract, which the generic decode error would hide.
+ */
+declare function getAdminState(chainId: ChainId, provider: Provider): Promise<StabilityPoolState>;
+export default getAdminState;

package/dist/types/pools/stabilityPool/liquidation.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Liquidation simulation for StabilityPool.liquidateBorrower, mirroring LiquidationStrategyProxy:
+ *   1. the seized collateral is deposited into the RWAVault for vault-token shares, unless it already is the vault token;
+ *   2. the stability pool's whole vault-token balance (the proxy runs under delegatecall) is split by BPS into
+ *      mint (treasury fee), burn, swap and liquidity (fee collector);
+ *   3. only the swap slice becomes crvUSD, through LiquidationSwap and its Curve pool;
+ *   3b. LiquidationSwap reverts when slippage protection is on and get_dy falls below pricePerShare / oracle price
+ *       less its tolerance, which is the case when Curve trades below the vault's value;
+ *   4. the crvUSD must cover the position's debt; any shortfall is withdrawn from the LendingPool with the pool's
+ *      rTokens, so stability pool depositors pay it, and the call reverts (InsufficientBalance) if they hold too few.
+ */
+import { type Provider } from "ethers";
+import { ChainId } from "../../configs/chains/index";
+/** The four shares of the vault-token balance, in basis points; they must add up to 10_000. */
+export interface LiquidationSplit {
+    mintBps: bigint;
+    burnBps: bigint;
+    swapBps: bigint;
+    liquidityBps: bigint;
+}
+export declare const SPLIT_KEYS: readonly ["mintBps", "burnBps", "swapBps", "liquidityBps"];
+export declare const splitTotal: (s: LiquidationSplit) => bigint;
+export declare const sameSplit: (a: LiquidationSplit, b: LiquidationSplit) => boolean;
+/** The stability pool's liquidation route, read once per review. */
+export interface LiquidationContext {
+    stabilityPool: string;
+    liquidationSwap: string;
+    liquidityPool: string;
+    rwaVault: string;
+    vaultToken: string;
+    vaultSymbol: string;
+    iIn: bigint;
+    iOut: bigint;
+    split: LiquidationSplit;
+    /** Vault tokens already in the stability pool; the split divides these too. */
+    poolVaultTokens: bigint;
+    /** rTokens the stability pool holds, which is the most a swap shortfall can draw from the LendingPool. */
+    rTokens: bigint;
+    /** LendingPool grace period, in seconds, before an insured position can be finalized. */
+    gracePeriod: number;
+    /** LiquidationSwap's own floor: null when protection is off, else pricePerShare / oracle price less its tolerance. */
+    slippage: {
+        bps: bigint;
+        pricePerShare: bigint;
+        oraclePrice: bigint;
+    } | null;
+}
+/** Everything liquidateBorrower needs for one position, plus its state on chain. */
+export interface LiquidationTarget {
+    poolAdapter: string;
+    vaultAdapter: string;
+    user: string;
+    /** abi.encode(uint256): the tokenId for ERC721 collateral, the full deposited amount for ERC20. */
+    data: string;
+    assetType: string;
+    assetToken: string;
+    /** The collateral already is the vault token, so no RWAVault deposit happens. */
+    isVaultToken: boolean;
+    collateralValue: bigint;
+    /** getPositionScaledDebt: the debt with accrued interest, which is what the liquidation repays. */
+    debt: bigint;
+    isUnderLiquidation: boolean;
+    isInsured: boolean;
+    liquidationStartTime: number;
+}
+export interface LiquidationQuote {
+    split: LiquidationSplit;
+    /** Vault tokens this liquidation adds: shares minted for the collateral, or the collateral itself. */
+    sharesFromCollateral: bigint;
+    /** sharesFromCollateral plus the pool's existing balance: what the split divides. */
+    totalVaultTokens: bigint;
+    swapAmount: bigint;
+    /** get_dy from the deployed Curve pool; null when the quote reverted. */
+    swapOut: bigint | null;
+    /** LiquidationSwap's minimum output for swapAmount; null when its slippage protection is off. */
+    minSwapOut: bigint | null;
+    /** Debt the swap does not cover, drawn from depositors' rTokens; the whole debt when the quote reverted. */
+    shortfall: bigint;
+    coversDebt: boolean;
+    /** The collateral is worth less than the debt, so depositors lose whatever the split. */
+    badDebt: bigint;
+    /** get_dy for the whole balance: the most any split can recover. */
+    maxSwapOut: bigint | null;
+    /** How far the realised swap rate falls below the spot rate, in basis points. */
+    priceImpactBps: bigint | null;
+    /** The crvUSD side of the Curve pool; the swap can never return more. */
+    poolReserveOut: bigint | null;
+}
+export interface SuggestedSplit extends LiquidationSplit {
+    projectedOut: bigint;
+    /** No split covers the debt; this is the best effort (100% swap). */
+    bestEffort: boolean;
+}
+/** Reads the stability pool's liquidation route, split, balances and the LendingPool grace period. */
+export declare function readLiquidationContext(chainId: ChainId, provider: Provider): Promise<LiquidationContext>;
+/** Assembles liquidateBorrower's arguments and the position's state for one position id ("user:adapter:key"). */
+export declare function readLiquidationTarget(chainId: ChainId, provider: Provider, ctx: LiquidationContext, positionId: string): Promise<LiquidationTarget>;
+/** Prices the liquidation with `split`, using the deployed Curve pool's get_dy rather than the vault's oracle price. */
+export declare function quoteLiquidation(provider: Provider, ctx: LiquidationContext, target: LiquidationTarget, split: LiquidationSplit): Promise<LiquidationQuote>;
+/**
+ * The smallest swap share whose get_dy still covers the debt plus `bufferBps`, with the rest given back to mint,
+ * burn and liquidity in their current proportion. get_dy grows with dx, so a binary search over BPS is sound.
+ */
+export declare function suggestSplit(provider: Provider, ctx: LiquidationContext, target: LiquidationTarget, quote: LiquidationQuote, bufferBps?: bigint): Promise<SuggestedSplit | null>;
+/** minSharesOut for the RWAVault deposit: previewDeposit less `slippageBps`. Zero when nothing is deposited. */
+export declare const minSharesOut: (target: LiquidationTarget, quote: LiquidationQuote, slippageBps: bigint) => bigint;
+/**
+ * Simulates liquidateBorrower from `sender` with the split overridden in storage (an eth_call state override), so a
+ * split change in the same batch is simulated rather than only checked. Returns null when the RPC or the storage
+ * layout cannot be used; otherwise the revert reason, or "" when it succeeds.
+ */
+export declare function simulateWithSplit(provider: Provider, ctx: LiquidationContext, sender: string, data: string, split: LiquidationSplit): Promise<string | null>;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@raac/rpc",
-	"version": "2.0.0-beta.12",
+	"version": "2.0.0-beta.14",
 	"description": "RPC Library for RAAC",
 	"main": "dist/index.js",
 	"types": "dist/types/index.d.ts",
@@ -11,7 +11,13 @@
 		"dev": "ts-node-dev --transpile-only --env-file=.env scripts/index.ts",
 		"build": "tsc && cp -r typechain-types dist/types && cp -r generated dist/generated",
 		"build:watch": "tsc --watch",
-		"test": "echo \"Error: no test specified\" && exit 1",
+		"test": "npm run test:unit && npm run test:integration && npm run test:e2e",
+		"test:full": "npm run test:unit && npm run test:integration && npm run test:e2e && npm run test:browser",
+		"test:unit": "node -r ts-node/register -r tsconfig-paths/register --test tests/loader.unit.test.ts",
+		"test:integration": "node -r ts-node/register -r tsconfig-paths/register --test tests/loader.integration.test.ts",
+		"test:e2e": "npm run build && node -r ts-node/register -r tsconfig-paths/register --test tests/loader.e2e.test.ts",
+		"test:browser": "node tests/browser/server.js --local",
+		"test:browser:published": "open tests/browser/index.html",
 		"sync": "bash setup.sh",
 		"clean": "rm -rf dist",
 		"prebuild": "npm run clean",
@@ -28,14 +34,18 @@
 	"dependencies": {
 		"@raac/chainlinkjs": "1.0.1",
 		"csv-parser": "3.2.0",
-		"ethers": "6.16.0",
+		"ethers": "6.17.0",
 		"ethers5": "npm:ethers@5.8.0"
 	},
 	"devDependencies": {
 		"@anthropic-ai/sdk": "^0.127.0",
+		"esbuild": "0.24.2",
 		"eslint": "9.39.1",
 		"ts-node": "10.9.2",
 		"ts-node-dev": "2.0.0",
+		"tsconfig-paths": "4.2.0",
 		"typescript": "5.9.3"
-	}
+	},
+	"browser": "dist/browser.js",
+	"module": "dist/browser.js"
 }