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

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

@@ -0,0 +1,101 @@
+import { ChainId } from "../configs/chains";
+/** Decimals of an 18-decimal fixed-point value (ERC20 default, 1e18-scaled ratios and prices). */
+export declare const WAD_DECIMALS = 18;
+/** Decimals of a 27-decimal fixed-point value (ray-scaled indexes and rates). */
+export declare const RAY_DECIMALS = 27;
+/**
+ * A fixed-point value that is not a token amount, such as a ray-scaled index or a 1e18-scaled ratio.
+ * `value` is the exact on-chain integer; the real number is `value / 10 ** decimals`.
+ */
+export type ScaledValue = {
+    /** The exact on-chain integer. */
+    value: bigint;
+    /** How many decimal places `value` is scaled by. */
+    decimals: number;
+};
+/**
+ * A token amount, balance, allowance, price or share figure in raw base units.
+ * Format it for display in the app; send `value` to contracts as is.
+ */
+export type TokenAmount = ScaledValue & {
+    /** The token symbol, when known. */
+    symbol?: string;
+};
+/** A JSON-safe `TokenAmount`: `value` is a base-10 integer string. */
+export type SerializedAmount = {
+    value: string;
+    decimals: number;
+    symbol?: string;
+};
+/**
+ * Builds a `TokenAmount` from an on-chain value.
+ * @param value The raw value in base units. `null` and `undefined` become `0n`.
+ * @param decimals The token's decimals.
+ * @param symbol The token symbol, when known.
+ * @returns The amount.
+ */
+export declare function toAmount(value: bigint | number | string | null | undefined, decimals: number, symbol?: string): TokenAmount;
+/**
+ * Builds a `ScaledValue` from an on-chain fixed-point value.
+ * @param value The raw integer. `null` and `undefined` become `0n`.
+ * @param decimals How many decimal places the value is scaled by. Defaults to 18.
+ * @returns The scaled value.
+ */
+export declare function toScaled(value: bigint | number | string | null | undefined, decimals?: number): ScaledValue;
+/**
+ * Parses decimal text into base units. Strict: rejects empty text, signs, exponents, separators and
+ * more fraction digits than `decimals`.
+ * @param text The decimal text, e.g. `"1.5"`.
+ * @param decimals The token's decimals.
+ * @returns The amount in base units.
+ * @throws If `text` is not a valid non-negative decimal with at most `decimals` fraction digits.
+ */
+export declare function parseAmount(text: string, decimals: number): bigint;
+/**
+ * The exact decimal string of an amount, with no rounding. For display formatting, use the app's formatter.
+ * @param amount The amount or scaled value.
+ * @returns The decimal string, e.g. `"1.5"` or `"2.0"`.
+ */
+export declare function toDecimalString(amount: ScaledValue): string;
+/**
+ * Converts an amount to a JSON-safe form, since `bigint` does not survive `JSON.stringify`.
+ * @param amount The amount.
+ * @returns The amount with `value` as a base-10 string.
+ */
+export declare function serializeAmount(amount: TokenAmount): SerializedAmount;
+/**
+ * Restores an amount produced by `serializeAmount`.
+ * @param serialized The serialized amount.
+ * @returns The amount with `value` as a `bigint`.
+ * @throws If `value` is not an integer string.
+ */
+export declare function deserializeAmount(serialized: SerializedAmount): TokenAmount;
+/**
+ * The decimals of an asset from the chain config.
+ * @param chainId The chain id.
+ * @param assetId The asset key under `assets` in the chain config, any casing.
+ * @returns The configured decimals.
+ * @throws If the asset or its decimals are not configured.
+ */
+export declare function getAssetDecimals(chainId: ChainId, assetId: string): number;
+/** A token's decimals and symbol from the chain config registry. */
+export type TokenInfo = {
+    decimals: number;
+    symbol?: string;
+};
+/**
+ * Looks a token up in the chain config registry (`assets`). Makes no RPC calls.
+ * @param chainId The chain id.
+ * @param idOrAddress An asset key (e.g. `"raactoken"`) or a token contract address, any casing.
+ * @returns The token's decimals and symbol, or `undefined` if the registry does not list it.
+ */
+export declare function getTokenInfo(chainId: ChainId, idOrAddress: string): TokenInfo | undefined;
+/**
+ * Builds a `TokenAmount` using the registry's decimals and symbol. Makes no RPC calls.
+ * A token the registry does not list gets 18 decimals and no symbol.
+ * @param chainId The chain id.
+ * @param idOrAddress An asset key or a token contract address, any casing.
+ * @param value The raw value in base units.
+ * @returns The amount.
+ */
+export declare function toTokenAmount(chainId: ChainId, idOrAddress: string, value: bigint | number | string | null | undefined): TokenAmount;

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

@@ -1883,6 +1883,26 @@ declare const ABIS: {
         stateMutability: string;
         type: string;
         anonymous?: undefined;
+    } | {
+        inputs: {
+            internalType: string;
+            name: string;
+            type: string;
+        }[];
+        name: string;
+        outputs: {
+            components: {
+                internalType: string;
+                name: string;
+                type: string;
+            }[];
+            internalType: string;
+            name: string;
+            type: string;
+        }[];
+        stateMutability: string;
+        type: string;
+        anonymous?: undefined;
     })[];
     basegauge: ({
         inputs: {
@@ -4323,6 +4343,26 @@ declare const getABI: (name: keyof typeof ABIS) => any[] | ({
     stateMutability: string;
     type: string;
     anonymous?: undefined;
+} | {
+    inputs: {
+        internalType: string;
+        name: string;
+        type: string;
+    }[];
+    name: string;
+    outputs: {
+        components: {
+            internalType: string;
+            name: string;
+            type: string;
+        }[];
+        internalType: string;
+        name: string;
+        type: string;
+    }[];
+    stateMutability: string;
+    type: string;
+    anonymous?: undefined;
 })[] | ({
     inputs: {
         internalType: string;

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

@@ -107,43 +107,29 @@ export declare const getConfigs: () => {
                 contract: string;
             };
         };
-        governance: {
-            gaugerewardsdistributor: {
+        gauges: {
+            raacgauges: {
                 id: string;
-                name: string;
-                contract: string;
-            };
-            gaugecontroller: {
-                id: string;
-                name: string;
-                contract: string;
-            };
-            gauge: {
-                id: string;
-                name: string;
-                contract: string;
-            };
-            raacgauge: {
-                id: string;
-                name: string;
-                contract: string;
-            };
-            rwagauge: {
-                id: string;
-                name: string;
-                contract: string;
-            };
-            governance: {
-                id: string;
-                name: string;
-                contract: string;
+                label: string;
+                gaugeType: string;
+                controller: string;
+                distributor: string;
+                gauges: {
+                    id: string;
+                    name: string;
+                    contract: string;
+                }[];
             };
-            timelockcontroller: {
+            rwagauges: {
                 id: string;
-                name: string;
-                contract: string;
+                label: string;
+                gaugeType: string;
+                controller: string;
+                distributor: string;
+                gauges: any[];
             };
         };
+        proposals: any[];
         pools: {
             stabilitypool: {
                 id: string;
@@ -152,6 +138,7 @@ export declare const getConfigs: () => {
             };
             lendingpool: {
                 id: string;
+                asset: string;
                 name: string;
                 contract: string;
             };
@@ -159,6 +146,7 @@ export declare const getConfigs: () => {
         nfts: {
             raacnft: {
                 id: string;
+                asset: string;
                 name: string;
                 contract: string;
             };
@@ -167,24 +155,28 @@ export declare const getConfigs: () => {
             eth: {
                 id: string;
                 name: string;
+                symbol: string;
                 decimals: number;
                 contract: string;
             };
             pmusd: {
                 id: string;
                 name: string;
+                symbol: string;
                 decimals: number;
                 contract: string;
             };
             xpm: {
                 id: string;
                 name: string;
+                symbol: string;
                 decimals: number;
                 contract: string;
             };
             crvusd: {
                 id: string;
                 name: string;
+                symbol: string;
                 decimals: number;
                 contract: string;
             };
@@ -203,12 +195,14 @@ export declare const getConfigs: () => {
             raactoken: {
                 id: string;
                 name: string;
+                symbol: string;
                 decimals: number;
                 contract: string;
             };
             veraac: {
                 id: string;
                 name: string;
+                symbol: string;
                 decimals: number;
                 contract: string;
             };
@@ -370,43 +364,29 @@ declare const _default: {
                     contract: string;
                 };
             };
-            governance: {
-                gaugerewardsdistributor: {
-                    id: string;
-                    name: string;
-                    contract: string;
-                };
-                gaugecontroller: {
-                    id: string;
-                    name: string;
-                    contract: string;
-                };
-                gauge: {
-                    id: string;
-                    name: string;
-                    contract: string;
-                };
-                raacgauge: {
+            gauges: {
+                raacgauges: {
                     id: string;
-                    name: string;
-                    contract: string;
-                };
-                rwagauge: {
-                    id: string;
-                    name: string;
-                    contract: string;
-                };
-                governance: {
-                    id: string;
-                    name: string;
-                    contract: string;
+                    label: string;
+                    gaugeType: string;
+                    controller: string;
+                    distributor: string;
+                    gauges: {
+                        id: string;
+                        name: string;
+                        contract: string;
+                    }[];
                 };
-                timelockcontroller: {
+                rwagauges: {
                     id: string;
-                    name: string;
-                    contract: string;
+                    label: string;
+                    gaugeType: string;
+                    controller: string;
+                    distributor: string;
+                    gauges: any[];
                 };
             };
+            proposals: any[];
             pools: {
                 stabilitypool: {
                     id: string;
@@ -415,6 +395,7 @@ declare const _default: {
                 };
                 lendingpool: {
                     id: string;
+                    asset: string;
                     name: string;
                     contract: string;
                 };
@@ -422,6 +403,7 @@ declare const _default: {
             nfts: {
                 raacnft: {
                     id: string;
+                    asset: string;
                     name: string;
                     contract: string;
                 };
@@ -430,24 +412,28 @@ declare const _default: {
                 eth: {
                     id: string;
                     name: string;
+                    symbol: string;
                     decimals: number;
                     contract: string;
                 };
                 pmusd: {
                     id: string;
                     name: string;
+                    symbol: string;
                     decimals: number;
                     contract: string;
                 };
                 xpm: {
                     id: string;
                     name: string;
+                    symbol: string;
                     decimals: number;
                     contract: string;
                 };
                 crvusd: {
                     id: string;
                     name: string;
+                    symbol: string;
                     decimals: number;
                     contract: string;
                 };
@@ -466,12 +452,14 @@ declare const _default: {
                 raactoken: {
                     id: string;
                     name: string;
+                    symbol: string;
                     decimals: number;
                     contract: string;
                 };
                 veraac: {
                     id: string;
                     name: string;
+                    symbol: string;
                     decimals: number;
                     contract: string;
                 };

package/dist/types/wallet/assets/approveAsset.d.ts

@@ -1,5 +1,14 @@
 import { Signer } from "ethers";
 import { AssetType } from "../../utils/artifacts";
 import { ChainId } from "../../configs/chains/index";
-declare function approveAsset(chainId: ChainId, assetId: AssetType, spender: string, amount: string, signer: Signer): Promise<any>;
+/**
+ * Approves `spender` to pull an asset from the signer.
+ * @param chainId The chain id.
+ * @param assetId The asset key in the chain config.
+ * @param spender The address to approve.
+ * @param amount The allowance in the token's base units. Pass `ethers.MaxUint256` for an unlimited approval.
+ * @param signer The token owner.
+ * @returns The transaction receipt.
+ */
+declare function approveAsset(chainId: ChainId, assetId: AssetType, spender: string, amount: bigint, signer: Signer): Promise<any>;
 export default approveAsset;

package/dist/types/wallet/assets/burnAsset.d.ts

@@ -1,5 +1,13 @@
 import { Signer } from "ethers";
 import { AssetType } from "../../utils/artifacts";
 import { ChainId } from "../../configs/chains/index";
+/**
+ * Burns an asset from the signer.
+ * @param chainId The chain id.
+ * @param assetId The asset id in the chain config.
+ * @param amount The amount to burn in the token's base units.
+ * @param signer The holder.
+ * @returns The transaction receipt.
+ */
 declare function burnAsset(chainId: ChainId, assetId: AssetType, amount: bigint, signer: Signer): Promise<any>;
 export default burnAsset;

package/dist/types/wallet/assets/getAllowance.d.ts

@@ -1,5 +1,16 @@
 import { Provider } from "ethers";
 import { AssetType } from "../../utils/artifacts";
 import { ChainId } from "../../configs/chains/index";
-declare function getAllowance(chainId: ChainId, assetId: AssetType, owner: string, spender: string, provider: Provider): Promise<bigint>;
+import { TokenAmount } from "../../utils/amount";
+/**
+ * Reads how much of an asset `spender` may pull from `owner`.
+ * @param chainId The chain id.
+ * @param assetId The asset key in the chain config, or `"eth"` for native ETH.
+ * @param owner The token owner.
+ * @param spender The approved spender.
+ * @param provider The provider to read with.
+ * @returns The allowance in base units with the asset's decimals. Native ETH has no allowance, so it returns `ethers.MaxUint256` with 18 decimals.
+ * @throws If the read fails.
+ */
+declare function getAllowance(chainId: ChainId, assetId: AssetType, owner: string, spender: string, provider: Provider): Promise<TokenAmount>;
 export default getAllowance;

package/dist/types/wallet/assets/getAsset.d.ts

@@ -1,4 +1,16 @@
 import { Provider } from "ethers";
 import { ChainId } from "../../configs/chains/index";
-declare function getAsset(chainId: ChainId, assetId: string, address: string, provider: Provider): Promise<any>;
+import { TokenAmount } from "../../utils/amount";
+/**
+ * Reads a configured asset's config entry together with a wallet's balance of it.
+ * @param chainId The chain id.
+ * @param assetId The asset key in the chain config.
+ * @param address The wallet address.
+ * @param provider The provider to read with.
+ * @returns The asset's config entry plus `balance`, the wallet balance as a `TokenAmount`.
+ * @throws If the balance read fails.
+ */
+declare function getAsset(chainId: ChainId, assetId: string, address: string, provider: Provider): Promise<Record<string, any> & {
+    balance: TokenAmount;
+}>;
 export default getAsset;

package/dist/types/wallet/assets/getAssets.d.ts

@@ -1,4 +1,14 @@
 import { Provider } from "ethers";
 import { ChainId } from "../../configs/chains/index";
-declare function getAssets(chainId: ChainId, address: string, provider: Provider): Promise<{}>;
+import { TokenAmount } from "../../utils/amount";
+/**
+ * Reads every configured asset with a wallet's balance of it.
+ * @param chainId The chain id.
+ * @param address The wallet address.
+ * @param provider The provider to read with.
+ * @returns A map of asset id to the asset's config entry plus `balance` as a `TokenAmount`. Assets the chain config does not have a deployment for are left out.
+ */
+declare function getAssets(chainId: ChainId, address: string, provider: Provider): Promise<Record<string, Record<string, any> & {
+    balance: TokenAmount;
+}>>;
 export default getAssets;

package/dist/types/wallet/assets/getBalance.d.ts

@@ -1,9 +1,15 @@
 import { Provider } from "ethers";
 import { AssetType } from "../../utils/artifacts";
 import { ChainId } from "../../configs/chains/index";
-declare function getBalance(chainId: ChainId, assetId: AssetType, address: string, provider: Provider): Promise<{
-    balance: string;
-    symbol: string;
-    decimals: number;
-}>;
+import { TokenAmount } from "../../utils/amount";
+/**
+ * Reads a wallet's balance of a configured asset or native ETH.
+ * @param chainId The chain id.
+ * @param assetId The asset key in the chain config, or `"eth"` for native ETH.
+ * @param address The wallet address.
+ * @param provider The provider to read with.
+ * @returns The balance in base units with decimals and symbol from the token registry (`"ETH"` and 18 for native ETH).
+ * @throws If the asset is not deployed on the chain, or the read fails.
+ */
+declare function getBalance(chainId: ChainId, assetId: AssetType, address: string, provider: Provider): Promise<TokenAmount>;
 export default getBalance;

package/dist/types/wallet/assets/mintAsset.d.ts

@@ -1,5 +1,14 @@
 import { Signer } from "ethers";
 import { AssetType } from "../../utils/artifacts";
 import { ChainId } from "../../configs/chains/index";
+/**
+ * Mints an asset to `address`.
+ * @param chainId The chain id.
+ * @param assetId The asset id in the chain config.
+ * @param amount The amount to mint in the token's base units.
+ * @param address The recipient.
+ * @param signer The minter.
+ * @returns The transaction receipt.
+ */
 declare function mintAsset(chainId: ChainId, assetId: AssetType, amount: bigint, address: string, signer: Signer): Promise<any>;
 export default mintAsset;

package/dist/types/wallet/assets/transferAsset.d.ts

@@ -1,5 +1,15 @@
 import { Signer } from "ethers";
 import { AssetType } from "../../utils/artifacts";
 import { ChainId } from "../../configs/chains/index";
+/**
+ * Transfers an asset or native ETH from the signer.
+ * @param chainId The chain id.
+ * @param assetId The asset id in the chain config, or `"eth"` for native ETH.
+ * @param amount The amount in the token's base units (wei for ETH).
+ * @param fromAddress The sender, used for logging.
+ * @param toAddress The recipient.
+ * @param signer The sender.
+ * @returns The transaction receipt.
+ */
 declare function transferAsset(chainId: ChainId, assetId: AssetType, amount: bigint, fromAddress: string, toAddress: string, signer: Signer): Promise<any>;
 export default transferAsset;

package/dist/utils/amount.js

@@ -0,0 +1,131 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RAY_DECIMALS = exports.WAD_DECIMALS = void 0;
+exports.toAmount = toAmount;
+exports.toScaled = toScaled;
+exports.parseAmount = parseAmount;
+exports.toDecimalString = toDecimalString;
+exports.serializeAmount = serializeAmount;
+exports.deserializeAmount = deserializeAmount;
+exports.getAssetDecimals = getAssetDecimals;
+exports.getTokenInfo = getTokenInfo;
+exports.toTokenAmount = toTokenAmount;
+const ethers_1 = require("ethers");
+const contracts_1 = require("./contracts");
+/** Decimals of an 18-decimal fixed-point value (ERC20 default, 1e18-scaled ratios and prices). */
+exports.WAD_DECIMALS = 18;
+/** Decimals of a 27-decimal fixed-point value (ray-scaled indexes and rates). */
+exports.RAY_DECIMALS = 27;
+/**
+ * Builds a `TokenAmount` from an on-chain value.
+ * @param value The raw value in base units. `null` and `undefined` become `0n`.
+ * @param decimals The token's decimals.
+ * @param symbol The token symbol, when known.
+ * @returns The amount.
+ */
+function toAmount(value, decimals, symbol) {
+    const amount = { value: BigInt(value ?? 0), decimals };
+    if (symbol !== undefined)
+        amount.symbol = symbol;
+    return amount;
+}
+/**
+ * Builds a `ScaledValue` from an on-chain fixed-point value.
+ * @param value The raw integer. `null` and `undefined` become `0n`.
+ * @param decimals How many decimal places the value is scaled by. Defaults to 18.
+ * @returns The scaled value.
+ */
+function toScaled(value, decimals = exports.WAD_DECIMALS) {
+    return { value: BigInt(value ?? 0), decimals };
+}
+/**
+ * Parses decimal text into base units. Strict: rejects empty text, signs, exponents, separators and
+ * more fraction digits than `decimals`.
+ * @param text The decimal text, e.g. `"1.5"`.
+ * @param decimals The token's decimals.
+ * @returns The amount in base units.
+ * @throws If `text` is not a valid non-negative decimal with at most `decimals` fraction digits.
+ */
+function parseAmount(text, decimals) {
+    const trimmed = typeof text === "string" ? text.trim() : "";
+    if (!/^(\d+\.?\d*|\.\d+)$/.test(trimmed)) {
+        throw new Error(`Invalid amount: "${text}"`);
+    }
+    const fraction = trimmed.split(".")[1] ?? "";
+    if (fraction.length > decimals) {
+        throw new Error(`Amount "${text}" has more than ${decimals} decimals`);
+    }
+    return ethers_1.ethers.parseUnits(trimmed.startsWith(".") ? `0${trimmed}` : trimmed, decimals);
+}
+/**
+ * The exact decimal string of an amount, with no rounding. For display formatting, use the app's formatter.
+ * @param amount The amount or scaled value.
+ * @returns The decimal string, e.g. `"1.5"` or `"2.0"`.
+ */
+function toDecimalString(amount) {
+    return ethers_1.ethers.formatUnits(amount.value, amount.decimals);
+}
+/**
+ * Converts an amount to a JSON-safe form, since `bigint` does not survive `JSON.stringify`.
+ * @param amount The amount.
+ * @returns The amount with `value` as a base-10 string.
+ */
+function serializeAmount(amount) {
+    const serialized = { value: amount.value.toString(), decimals: amount.decimals };
+    if (amount.symbol !== undefined)
+        serialized.symbol = amount.symbol;
+    return serialized;
+}
+/**
+ * Restores an amount produced by `serializeAmount`.
+ * @param serialized The serialized amount.
+ * @returns The amount with `value` as a `bigint`.
+ * @throws If `value` is not an integer string.
+ */
+function deserializeAmount(serialized) {
+    return toAmount(BigInt(serialized.value), serialized.decimals, serialized.symbol);
+}
+/**
+ * The decimals of an asset from the chain config.
+ * @param chainId The chain id.
+ * @param assetId The asset key under `assets` in the chain config, any casing.
+ * @returns The configured decimals.
+ * @throws If the asset or its decimals are not configured.
+ */
+function getAssetDecimals(chainId, assetId) {
+    const asset = (0, contracts_1.getConfig)(chainId)?.assets?.[assetId.toLowerCase()];
+    if (typeof asset?.decimals !== "number") {
+        throw new Error(`Decimals for asset ${assetId} not configured on chain ${chainId}`);
+    }
+    return asset.decimals;
+}
+/**
+ * Looks a token up in the chain config registry (`assets`). Makes no RPC calls.
+ * @param chainId The chain id.
+ * @param idOrAddress An asset key (e.g. `"raactoken"`) or a token contract address, any casing.
+ * @returns The token's decimals and symbol, or `undefined` if the registry does not list it.
+ */
+function getTokenInfo(chainId, idOrAddress) {
+    const assets = (0, contracts_1.getConfig)(chainId)?.assets;
+    if (!assets || !idOrAddress)
+        return undefined;
+    const needle = idOrAddress.toLowerCase();
+    const asset = assets[needle] ??
+        Object.values(assets).find((entry) => typeof entry?.symbol === "string" && entry.contract?.toLowerCase() === needle) ??
+        Object.values(assets).find((entry) => entry?.contract?.toLowerCase() === needle);
+    if (typeof asset?.decimals !== "number")
+        return undefined;
+    return asset.symbol === undefined ? { decimals: asset.decimals } : { decimals: asset.decimals, symbol: asset.symbol };
+}
+/**
+ * Builds a `TokenAmount` using the registry's decimals and symbol. Makes no RPC calls.
+ * A token the registry does not list gets 18 decimals and no symbol.
+ * @param chainId The chain id.
+ * @param idOrAddress An asset key or a token contract address, any casing.
+ * @param value The raw value in base units.
+ * @returns The amount.
+ */
+function toTokenAmount(chainId, idOrAddress, value) {
+    const info = getTokenInfo(chainId, idOrAddress);
+    return toAmount(value, info?.decimals ?? exports.WAD_DECIMALS, info?.symbol);
+}