@hyperlane-xyz/metrics 0.1.0

package/LICENSE.md

@@ -0,0 +1,195 @@
+Apache License
+==============
+
+_Version 2.0, January 2004_  
+_&lt;<http://www.apache.org/licenses/>&gt;_
+
+### Terms and Conditions for use, reproduction, and distribution
+
+#### 1. Definitions
+
+“License” shall mean the terms and conditions for use, reproduction, and
+distribution as defined by Sections 1 through 9 of this document.
+
+“Licensor” shall mean the copyright owner or entity authorized by the copyright
+owner that is granting the License.
+
+“Legal Entity” shall mean the union of the acting entity and all other entities
+that control, are controlled by, or are under common control with that entity.
+For the purposes of this definition, “control” means **(i)** the power, direct or
+indirect, to cause the direction or management of such entity, whether by
+contract or otherwise, or **(ii)** ownership of fifty percent (50%) or more of the
+outstanding shares, or **(iii)** beneficial ownership of such entity.
+
+“You” (or “Your”) shall mean an individual or Legal Entity exercising
+permissions granted by this License.
+
+“Source” form shall mean the preferred form for making modifications, including
+but not limited to software source code, documentation source, and configuration
+files.
+
+“Object” form shall mean any form resulting from mechanical transformation or
+translation of a Source form, including but not limited to compiled object code,
+generated documentation, and conversions to other media types.
+
+“Work” shall mean the work of authorship, whether in Source or Object form, made
+available under the License, as indicated by a copyright notice that is included
+in or attached to the work (an example is provided in the Appendix below).
+
+“Derivative Works” shall mean any work, whether in Source or Object form, that
+is based on (or derived from) the Work and for which the editorial revisions,
+annotations, elaborations, or other modifications represent, as a whole, an
+original work of authorship. For the purposes of this License, Derivative Works
+shall not include works that remain separable from, or merely link (or bind by
+name) to the interfaces of, the Work and Derivative Works thereof.
+
+“Contribution” shall mean any work of authorship, including the original version
+of the Work and any modifications or additions to that Work or Derivative Works
+thereof, that is intentionally submitted to Licensor for inclusion in the Work
+by the copyright owner or by an individual or Legal Entity authorized to submit
+on behalf of the copyright owner. For the purposes of this definition,
+“submitted” means any form of electronic, verbal, or written communication sent
+to the Licensor or its representatives, including but not limited to
+communication on electronic mailing lists, source code control systems, and
+issue tracking systems that are managed by, or on behalf of, the Licensor for
+the purpose of discussing and improving the Work, but excluding communication
+that is conspicuously marked or otherwise designated in writing by the copyright
+owner as “Not a Contribution.”
+
+“Contributor” shall mean Licensor and any individual or Legal Entity on behalf
+of whom a Contribution has been received by Licensor and subsequently
+incorporated within the Work.
+
+#### 2. Grant of Copyright License
+
+Subject to the terms and conditions of this License, each Contributor hereby
+grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free,
+irrevocable copyright license to reproduce, prepare Derivative Works of,
+publicly display, publicly perform, sublicense, and distribute the Work and such
+Derivative Works in Source or Object form.
+
+#### 3. Grant of Patent License
+
+Subject to the terms and conditions of this License, each Contributor hereby
+grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free,
+irrevocable (except as stated in this section) patent license to make, have
+made, use, offer to sell, sell, import, and otherwise transfer the Work, where
+such license applies only to those patent claims licensable by such Contributor
+that are necessarily infringed by their Contribution(s) alone or by combination
+of their Contribution(s) with the Work to which such Contribution(s) was
+submitted. If You institute patent litigation against any entity (including a
+cross-claim or counterclaim in a lawsuit) alleging that the Work or a
+Contribution incorporated within the Work constitutes direct or contributory
+patent infringement, then any patent licenses granted to You under this License
+for that Work shall terminate as of the date such litigation is filed.
+
+#### 4. Redistribution
+
+You may reproduce and distribute copies of the Work or Derivative Works thereof
+in any medium, with or without modifications, and in Source or Object form,
+provided that You meet the following conditions:
+
+* **(a)** You must give any other recipients of the Work or Derivative Works a copy of
+this License; and
+* **(b)** You must cause any modified files to carry prominent notices stating that You
+changed the files; and
+* **(c)** You must retain, in the Source form of any Derivative Works that You distribute,
+all copyright, patent, trademark, and attribution notices from the Source form
+of the Work, excluding those notices that do not pertain to any part of the
+Derivative Works; and
+* **(d)** If the Work includes a “NOTICE” text file as part of its distribution, then any
+Derivative Works that You distribute must include a readable copy of the
+attribution notices contained within such NOTICE file, excluding those notices
+that do not pertain to any part of the Derivative Works, in at least one of the
+following places: within a NOTICE text file distributed as part of the
+Derivative Works; within the Source form or documentation, if provided along
+with the Derivative Works; or, within a display generated by the Derivative
+Works, if and wherever such third-party notices normally appear. The contents of
+the NOTICE file are for informational purposes only and do not modify the
+License. You may add Your own attribution notices within Derivative Works that
+You distribute, alongside or as an addendum to the NOTICE text from the Work,
+provided that such additional attribution notices cannot be construed as
+modifying the License.
+
+You may add Your own copyright statement to Your modifications and may provide
+additional or different license terms and conditions for use, reproduction, or
+distribution of Your modifications, or for any such Derivative Works as a whole,
+provided Your use, reproduction, and distribution of the Work otherwise complies
+with the conditions stated in this License.
+
+#### 5. Submission of Contributions
+
+Unless You explicitly state otherwise, any Contribution intentionally submitted
+for inclusion in the Work by You to the Licensor shall be under the terms and
+conditions of this License, without any additional terms or conditions.
+Notwithstanding the above, nothing herein shall supersede or modify the terms of
+any separate license agreement you may have executed with Licensor regarding
+such Contributions.
+
+#### 6. Trademarks
+
+This License does not grant permission to use the trade names, trademarks,
+service marks, or product names of the Licensor, except as required for
+reasonable and customary use in describing the origin of the Work and
+reproducing the content of the NOTICE file.
+
+#### 7. Disclaimer of Warranty
+
+Unless required by applicable law or agreed to in writing, Licensor provides the
+Work (and each Contributor provides its Contributions) on an “AS IS” BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied,
+including, without limitation, any warranties or conditions of TITLE,
+NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are
+solely responsible for determining the appropriateness of using or
+redistributing the Work and assume any risks associated with Your exercise of
+permissions under this License.
+
+#### 8. Limitation of Liability
+
+In no event and under no legal theory, whether in tort (including negligence),
+contract, or otherwise, unless required by applicable law (such as deliberate
+and grossly negligent acts) or agreed to in writing, shall any Contributor be
+liable to You for damages, including any direct, indirect, special, incidental,
+or consequential damages of any character arising as a result of this License or
+out of the use or inability to use the Work (including but not limited to
+damages for loss of goodwill, work stoppage, computer failure or malfunction, or
+any and all other commercial damages or losses), even if such Contributor has
+been advised of the possibility of such damages.
+
+#### 9. Accepting Warranty or Additional Liability
+
+While redistributing the Work or Derivative Works thereof, You may choose to
+offer, and charge a fee for, acceptance of support, warranty, indemnity, or
+other liability obligations and/or rights consistent with this License. However,
+in accepting such obligations, You may act only on Your own behalf and on Your
+sole responsibility, not on behalf of any other Contributor, and only if You
+agree to indemnify, defend, and hold each Contributor harmless for any liability
+incurred by, or claims asserted against, such Contributor by reason of your
+accepting any such warranty or additional liability.
+
+_END OF TERMS AND CONDITIONS_
+
+### APPENDIX: How to apply the Apache License to your work
+
+To apply the Apache License to your work, attach the following boilerplate
+notice, with the fields enclosed by brackets `[]` replaced with your own
+identifying information. (Don't include the brackets!) The text should be
+enclosed in the appropriate comment syntax for the file format. We also
+recommend that a file or class name and description of purpose be included on
+the same “printed page” as the copyright notice for easier identification within
+third-party archives.
+
+    Copyright [yyyy] [name of copyright owner]
+    
+    Licensed under the Apache License, Version 2.0 (the "License");
+    you may not use this file except in compliance with the License.
+    You may obtain a copy of the License at
+    
+      http://www.apache.org/licenses/LICENSE-2.0
+    
+    Unless required by applicable law or agreed to in writing, software
+    distributed under the License is distributed on an "AS IS" BASIS,
+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+    See the License for the specific language governing permissions and
+    limitations under the License.
+

package/dist/balance.d.ts

@@ -0,0 +1,93 @@
+import { Contract, type PopulatedTransaction } from 'ethers';
+import type { Logger } from 'pino';
+import { type IHypXERC20Adapter, type MultiProtocolProvider, Token, type WarpCore } from '@hyperlane-xyz/sdk';
+import { type Address } from '@hyperlane-xyz/utils';
+import type { NativeWalletBalance, WarpRouteBalance, XERC20Info, XERC20Limit } from './types.js';
+/**
+ * Minimal ABI for managed lockbox contracts.
+ */
+export declare const MANAGED_LOCKBOX_MINIMAL_ABI: readonly ["function XERC20() view returns (address)", "function ERC20() view returns (address)"];
+/**
+ * Interface for token price getter to allow different implementations.
+ */
+export interface TokenPriceGetter {
+    tryGetTokenPrice(token: Token): Promise<number | undefined>;
+}
+/**
+ * Gets the bridged balance and value of a token in a warp route.
+ *
+ * @param warpCore - The WarpCore instance for the route
+ * @param token - The token to get the balance for
+ * @param tokenPriceGetter - Price getter for calculating USD value
+ * @param logger - Logger instance
+ * @param bridgedSupply - Optional pre-fetched bridged supply
+ * @returns The balance information or undefined if not available
+ */
+export declare function getTokenBridgedBalance(warpCore: WarpCore, token: Token, tokenPriceGetter: TokenPriceGetter, logger: Logger, bridgedSupply?: bigint): Promise<WarpRouteBalance | undefined>;
+/**
+ * Gets the native balance of the ATA payer for Sealevel tokens.
+ *
+ * @param warpCore - The WarpCore instance for the route
+ * @param token - The Sealevel token
+ * @param warpRouteId - The warp route identifier
+ * @returns The native wallet balance information
+ */
+export declare function getSealevelAtaPayerBalance(warpCore: WarpCore, token: Token, warpRouteId: string): Promise<NativeWalletBalance>;
+/**
+ * Gets xERC20 information for a token.
+ *
+ * @param warpCore - The WarpCore instance for the route
+ * @param token - The xERC20 token
+ * @returns The xERC20 info including limits and address
+ */
+export declare function getXERC20Info(warpCore: WarpCore, token: Token): Promise<XERC20Info>;
+/**
+ * Gets xERC20 limits from an adapter.
+ *
+ * @param token - The token to get limits for
+ * @param xerc20 - The xERC20 adapter
+ * @returns The xERC20 limits
+ */
+export declare function getXERC20Limit(token: Token, xerc20: IHypXERC20Adapter<PopulatedTransaction>): Promise<XERC20Limit>;
+/**
+ * Gets a managed lockbox contract instance.
+ *
+ * @param multiProvider - The multi-protocol provider
+ * @param chainName - The chain name
+ * @param lockboxAddress - The lockbox contract address
+ * @returns The Contract instance
+ */
+export declare function getManagedLockBox(multiProvider: MultiProtocolProvider, chainName: string, lockboxAddress: Address): Contract;
+/**
+ * Gets extra lockbox information for xERC20 tokens.
+ *
+ * @param multiProvider - The multi-protocol provider
+ * @param warpToken - The warp token
+ * @param lockboxAddress - The lockbox contract address
+ * @returns The xERC20 info for the lockbox
+ */
+export declare function getExtraLockboxInfo(multiProvider: MultiProtocolProvider, warpToken: Token, lockboxAddress: Address): Promise<XERC20Info>;
+/**
+ * Gets the balance of an extra lockbox.
+ *
+ * @param multiProvider - The multi-protocol provider
+ * @param warpToken - The warp token
+ * @param tokenPriceGetter - Price getter for calculating USD value
+ * @param lockboxAddress - The lockbox contract address
+ * @param logger - Logger instance
+ * @returns The balance information or undefined if not available
+ */
+export declare function getExtraLockboxBalance(multiProvider: MultiProtocolProvider, warpToken: Token, tokenPriceGetter: TokenPriceGetter, lockboxAddress: Address, logger: Logger): Promise<WarpRouteBalance | undefined>;
+/**
+ * Gets collateral info for a managed lockbox.
+ *
+ * @param multiProvider - The multi-protocol provider
+ * @param warpToken - The warp token
+ * @param lockBoxAddress - The lockbox contract address
+ * @returns The token name and address of the collateral
+ */
+export declare function getManagedLockBoxCollateralInfo(multiProvider: MultiProtocolProvider, warpToken: Token, lockBoxAddress: Address): Promise<{
+    tokenName: string;
+    tokenAddress: Address;
+}>;
+//# sourceMappingURL=balance.d.ts.map

package/dist/balance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"balance.d.ts","sourceRoot":"","sources":["../src/balance.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,KAAK,oBAAoB,EAAE,MAAM,QAAQ,CAAC;AAC7D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AAGnC,OAAO,EAIL,KAAK,iBAAiB,EACtB,KAAK,qBAAqB,EAE1B,KAAK,EAEL,KAAK,QAAQ,EACd,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,KAAK,OAAO,EAAgB,MAAM,sBAAsB,CAAC;AAElE,OAAO,KAAK,EACV,mBAAmB,EACnB,gBAAgB,EAChB,UAAU,EACV,WAAW,EACZ,MAAM,YAAY,CAAC;AAGpB;;GAEG;AACH,eAAO,MAAM,2BAA2B,kGAG9B,CAAC;AAEX;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,gBAAgB,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;CAC7D;AAED;;;;;;;;;GASG;AACH,wBAAsB,sBAAsB,CAC1C,QAAQ,EAAE,QAAQ,EAClB,KAAK,EAAE,KAAK,EACZ,gBAAgB,EAAE,gBAAgB,EAClC,MAAM,EAAE,MAAM,EACd,aAAa,CAAC,EAAE,MAAM,GACrB,OAAO,CAAC,gBAAgB,GAAG,SAAS,CAAC,CA+CvC;AAED;;;;;;;GAOG;AACH,wBAAsB,0BAA0B,CAC9C,QAAQ,EAAE,QAAQ,EAClB,KAAK,EAAE,KAAK,EACZ,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,mBAAmB,CAAC,CAyB9B;AAED;;;;;;GAMG;AACH,wBAAsB,aAAa,CACjC,QAAQ,EAAE,QAAQ,EAClB,KAAK,EAAE,KAAK,GACX,OAAO,CAAC,UAAU,CAAC,CA8BrB;AAED;;;;;;GAMG;AACH,wBAAsB,cAAc,CAClC,KAAK,EAAE,KAAK,EACZ,MAAM,EAAE,iBAAiB,CAAC,oBAAoB,CAAC,GAC9C,OAAO,CAAC,WAAW,CAAC,CActB;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAC/B,aAAa,EAAE,qBAAqB,EACpC,SAAS,EAAE,MAAM,EACjB,cAAc,EAAE,OAAO,GACtB,QAAQ,CAGV;AAED;;;;;;;GAOG;AACH,wBAAsB,mBAAmB,CACvC,aAAa,EAAE,qBAAqB,EACpC,SAAS,EAAE,KAAK,EAChB,cAAc,EAAE,OAAO,GACtB,OAAO,CAAC,UAAU,CAAC,CAgCrB;AAED;;;;;;;;;GASG;AACH,wBAAsB,sBAAsB,CAC1C,aAAa,EAAE,qBAAqB,EACpC,SAAS,EAAE,KAAK,EAChB,gBAAgB,EAAE,gBAAgB,EAClC,cAAc,EAAE,OAAO,EACvB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,gBAAgB,GAAG,SAAS,CAAC,CA6CvC;AAED;;;;;;;GAOG;AACH,wBAAsB,+BAA+B,CACnD,aAAa,EAAE,qBAAqB,EACpC,SAAS,EAAE,KAAK,EAChB,cAAc,EAAE,OAAO,GACtB,OAAO,CAAC;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,OAAO,CAAA;CAAE,CAAC,CAsBvD"}

package/dist/balance.js

@@ -0,0 +1,230 @@
+import { Contract } from 'ethers';
+import { IXERC20VS__factory } from '@hyperlane-xyz/core';
+import { EvmTokenAdapter, Token, TokenStandard, } from '@hyperlane-xyz/sdk';
+import { ProtocolType } from '@hyperlane-xyz/utils';
+import { formatBigInt } from './utils.js';
+/**
+ * Minimal ABI for managed lockbox contracts.
+ */
+export const MANAGED_LOCKBOX_MINIMAL_ABI = [
+    'function XERC20() view returns (address)',
+    'function ERC20() view returns (address)',
+];
+/**
+ * Gets the bridged balance and value of a token in a warp route.
+ *
+ * @param warpCore - The WarpCore instance for the route
+ * @param token - The token to get the balance for
+ * @param tokenPriceGetter - Price getter for calculating USD value
+ * @param logger - Logger instance
+ * @param bridgedSupply - Optional pre-fetched bridged supply
+ * @returns The balance information or undefined if not available
+ */
+export async function getTokenBridgedBalance(warpCore, token, tokenPriceGetter, logger, bridgedSupply) {
+    if (!token.isHypToken()) {
+        logger.warn({ token: token.symbol, chain: token.chainName }, 'No support for bridged balance on non-Hyperlane token');
+        return undefined;
+    }
+    const adapter = token.getHypAdapter(warpCore.multiProvider);
+    let tokenAddress = token.collateralAddressOrDenom ?? token.addressOrDenom;
+    // If bridged supply is not provided, fetch it
+    const supply = bridgedSupply ?? (await adapter.getBridgedSupply());
+    if (supply === undefined) {
+        logger.warn({ token: token.symbol, chain: token.chainName }, 'Failed to get bridged supply');
+        return undefined;
+    }
+    const balance = token.amount(supply).getDecimalFormattedAmount();
+    let tokenPrice;
+    // Only record value for collateralized and xERC20 lockbox tokens.
+    if (token.isCollateralized() ||
+        token.standard === TokenStandard.EvmHypXERC20Lockbox ||
+        token.standard === TokenStandard.EvmHypVSXERC20Lockbox) {
+        tokenPrice = await tokenPriceGetter.tryGetTokenPrice(token);
+    }
+    if (token.standard === TokenStandard.EvmHypXERC20Lockbox ||
+        token.standard === TokenStandard.EvmHypVSXERC20Lockbox) {
+        tokenAddress = (await adapter.getXERC20())
+            .address;
+    }
+    return {
+        balance,
+        valueUSD: tokenPrice ? balance * tokenPrice : undefined,
+        tokenAddress,
+    };
+}
+/**
+ * Gets the native balance of the ATA payer for Sealevel tokens.
+ *
+ * @param warpCore - The WarpCore instance for the route
+ * @param token - The Sealevel token
+ * @param warpRouteId - The warp route identifier
+ * @returns The native wallet balance information
+ */
+export async function getSealevelAtaPayerBalance(warpCore, token, warpRouteId) {
+    if (token.protocol !== ProtocolType.Sealevel || token.isNative()) {
+        throw new Error(`Unsupported ATA payer protocol type ${token.protocol} or standard ${token.standard}`);
+    }
+    const adapter = token.getHypAdapter(warpCore.multiProvider);
+    const ataPayer = adapter.deriveAtaPayerAccount().toString();
+    const nativeToken = Token.FromChainMetadataNativeToken(warpCore.multiProvider.getChainMetadata(token.chainName));
+    const ataPayerBalance = await nativeToken.getBalance(warpCore.multiProvider, ataPayer);
+    return {
+        chain: token.chainName,
+        walletAddress: ataPayer.toString(),
+        walletName: `${warpRouteId}/ata-payer`,
+        balance: ataPayerBalance.getDecimalFormattedAmount(),
+    };
+}
+/**
+ * Gets xERC20 information for a token.
+ *
+ * @param warpCore - The WarpCore instance for the route
+ * @param token - The xERC20 token
+ * @returns The xERC20 info including limits and address
+ */
+export async function getXERC20Info(warpCore, token) {
+    if (token.protocol !== ProtocolType.Ethereum) {
+        throw new Error(`Unsupported XERC20 protocol type ${token.protocol}`);
+    }
+    if (token.standard === TokenStandard.EvmHypXERC20 ||
+        token.standard === TokenStandard.EvmHypVSXERC20) {
+        const adapter = token.getAdapter(warpCore.multiProvider);
+        return {
+            limits: await getXERC20Limit(token, adapter),
+            xERC20Address: (await adapter.getXERC20()).address,
+        };
+    }
+    else if (token.standard === TokenStandard.EvmHypXERC20Lockbox ||
+        token.standard === TokenStandard.EvmHypVSXERC20Lockbox) {
+        const adapter = token.getAdapter(warpCore.multiProvider);
+        return {
+            limits: await getXERC20Limit(token, adapter),
+            xERC20Address: (await adapter.getXERC20()).address,
+        };
+    }
+    throw new Error(`Unsupported XERC20 token standard ${token.standard}`);
+}
+/**
+ * Gets xERC20 limits from an adapter.
+ *
+ * @param token - The token to get limits for
+ * @param xerc20 - The xERC20 adapter
+ * @returns The xERC20 limits
+ */
+export async function getXERC20Limit(token, xerc20) {
+    const [mintCurrent, mintMax, burnCurrent, burnMax] = await Promise.all([
+        xerc20.getMintLimit(),
+        xerc20.getMintMaxLimit(),
+        xerc20.getBurnLimit(),
+        xerc20.getBurnMaxLimit(),
+    ]);
+    return {
+        mint: formatBigInt(token, mintCurrent),
+        mintMax: formatBigInt(token, mintMax),
+        burn: formatBigInt(token, burnCurrent),
+        burnMax: formatBigInt(token, burnMax),
+    };
+}
+/**
+ * Gets a managed lockbox contract instance.
+ *
+ * @param multiProvider - The multi-protocol provider
+ * @param chainName - The chain name
+ * @param lockboxAddress - The lockbox contract address
+ * @returns The Contract instance
+ */
+export function getManagedLockBox(multiProvider, chainName, lockboxAddress) {
+    const provider = multiProvider.getEthersV5Provider(chainName);
+    return new Contract(lockboxAddress, MANAGED_LOCKBOX_MINIMAL_ABI, provider);
+}
+/**
+ * Gets extra lockbox information for xERC20 tokens.
+ *
+ * @param multiProvider - The multi-protocol provider
+ * @param warpToken - The warp token
+ * @param lockboxAddress - The lockbox contract address
+ * @returns The xERC20 info for the lockbox
+ */
+export async function getExtraLockboxInfo(multiProvider, warpToken, lockboxAddress) {
+    const currentChainProvider = multiProvider.getEthersV5Provider(warpToken.chainName);
+    const lockboxInstance = getManagedLockBox(multiProvider, warpToken.chainName, lockboxAddress);
+    const xERC20Address = await lockboxInstance['XERC20']();
+    const vsXERC20Instance = IXERC20VS__factory.connect(xERC20Address, currentChainProvider);
+    const [mintMax, burnMax, mint, burn] = await Promise.all([
+        vsXERC20Instance.mintingMaxLimitOf(lockboxAddress),
+        vsXERC20Instance.burningMaxLimitOf(lockboxAddress),
+        vsXERC20Instance.mintingCurrentLimitOf(lockboxAddress),
+        vsXERC20Instance.burningCurrentLimitOf(lockboxAddress),
+    ]);
+    return {
+        limits: {
+            burn: formatBigInt(warpToken, burn.toBigInt()),
+            burnMax: formatBigInt(warpToken, burnMax.toBigInt()),
+            mint: formatBigInt(warpToken, mint.toBigInt()),
+            mintMax: formatBigInt(warpToken, mintMax.toBigInt()),
+        },
+        xERC20Address,
+    };
+}
+/**
+ * Gets the balance of an extra lockbox.
+ *
+ * @param multiProvider - The multi-protocol provider
+ * @param warpToken - The warp token
+ * @param tokenPriceGetter - Price getter for calculating USD value
+ * @param lockboxAddress - The lockbox contract address
+ * @param logger - Logger instance
+ * @returns The balance information or undefined if not available
+ */
+export async function getExtraLockboxBalance(multiProvider, warpToken, tokenPriceGetter, lockboxAddress, logger) {
+    if (!warpToken.isXerc20()) {
+        return undefined;
+    }
+    const lockboxInstance = getManagedLockBox(multiProvider, warpToken.chainName, lockboxAddress);
+    const erc20TokenAddress = await lockboxInstance['ERC20']();
+    const erc20tokenAdapter = new EvmTokenAdapter(warpToken.chainName, multiProvider, {
+        token: erc20TokenAddress,
+    });
+    let balance;
+    try {
+        balance = await erc20tokenAdapter.getBalance(lockboxAddress);
+    }
+    catch (err) {
+        logger.error({
+            err,
+            chain: warpToken.chainName,
+            token: warpToken.symbol,
+            lockboxAddress,
+            erc20TokenAddress,
+        }, 'Failed to get balance for contract at lockbox address');
+        return undefined;
+    }
+    const tokenPrice = await tokenPriceGetter.tryGetTokenPrice(warpToken);
+    const balanceNumber = formatBigInt(warpToken, balance);
+    return {
+        balance: balanceNumber,
+        valueUSD: tokenPrice ? balanceNumber * tokenPrice : undefined,
+        tokenAddress: erc20TokenAddress,
+    };
+}
+/**
+ * Gets collateral info for a managed lockbox.
+ *
+ * @param multiProvider - The multi-protocol provider
+ * @param warpToken - The warp token
+ * @param lockBoxAddress - The lockbox contract address
+ * @returns The token name and address of the collateral
+ */
+export async function getManagedLockBoxCollateralInfo(multiProvider, warpToken, lockBoxAddress) {
+    const lockBoxInstance = getManagedLockBox(multiProvider, warpToken.chainName, lockBoxAddress);
+    const collateralTokenAddress = await lockBoxInstance['ERC20']();
+    const collateralTokenAdapter = new EvmTokenAdapter(warpToken.chainName, multiProvider, {
+        token: collateralTokenAddress,
+    });
+    const { name } = await collateralTokenAdapter.getMetadata();
+    return {
+        tokenName: name,
+        tokenAddress: collateralTokenAddress,
+    };
+}
+//# sourceMappingURL=balance.js.map

package/dist/balance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"balance.js","sourceRoot":"","sources":["../src/balance.ts"],"names":[],"mappings":"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"}

package/dist/gauges.d.ts

@@ -0,0 +1,41 @@
+import { Gauge, type Registry } from 'prom-client';
+import type { WarpRouteMetricLabels, WarpRouteValueAtRiskMetricLabels } from './types.js';
+/**
+ * Label names for warp route metrics.
+ */
+export declare const warpRouteMetricLabels: (keyof WarpRouteMetricLabels)[];
+/**
+ * Label names for value at risk metrics.
+ */
+export declare const warpRouteValueAtRiskMetricLabels: (keyof WarpRouteValueAtRiskMetricLabels)[];
+/**
+ * Wallet balance metric label names.
+ */
+export declare const walletBalanceMetricLabels: readonly ["chain", "wallet_address", "wallet_name", "token_address", "token_symbol", "token_name"];
+/**
+ * xERC20 limits metric label names.
+ */
+export declare const xERC20LimitsMetricLabels: readonly ["chain_name", "limit_type", "token_name", "bridge_address", "token_address", "bridge_label"];
+/**
+ * Collection of warp route Prometheus gauges.
+ */
+export interface WarpMetricsGauges {
+    warpRouteTokenBalance: Gauge<string>;
+    warpRouteCollateralValue: Gauge<string>;
+    warpRouteValueAtRisk: Gauge<string>;
+    walletBalanceGauge: Gauge<string>;
+    xERC20LimitsGauge: Gauge<string>;
+}
+/**
+ * Creates a new wallet balance gauge with optional additional labels.
+ */
+export declare function createWalletBalanceGauge(registry: Registry, additionalLabels?: string[]): Gauge<string>;
+/**
+ * Creates all warp route metric gauges and registers them with the provided registry.
+ *
+ * @param registry - The Prometheus registry to register the gauges with
+ * @param walletBalanceAdditionalLabels - Optional additional labels for the wallet balance gauge
+ * @returns Collection of warp metric gauges
+ */
+export declare function createWarpMetricsGauges(registry: Registry, walletBalanceAdditionalLabels?: string[]): WarpMetricsGauges;
+//# sourceMappingURL=gauges.d.ts.map

package/dist/gauges.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gauges.d.ts","sourceRoot":"","sources":["../src/gauges.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,KAAK,QAAQ,EAAE,MAAM,aAAa,CAAC;AAEnD,OAAO,KAAK,EACV,qBAAqB,EACrB,gCAAgC,EACjC,MAAM,YAAY,CAAC;AAEpB;;GAEG;AACH,eAAO,MAAM,qBAAqB,EAAE,CAAC,MAAM,qBAAqB,CAAC,EAQhE,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,gCAAgC,EAAE,CAAC,MAAM,gCAAgC,CAAC,EAQpF,CAAC;AAEJ;;GAEG;AACH,eAAO,MAAM,yBAAyB,oGAO5B,CAAC;AAEX;;GAEG;AACH,eAAO,MAAM,wBAAwB,wGAO3B,CAAC;AAEX;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,qBAAqB,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IACrC,wBAAwB,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IACxC,oBAAoB,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IACpC,kBAAkB,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IAClC,iBAAiB,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;CAClC;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,QAAQ,EAClB,gBAAgB,GAAE,MAAM,EAAO,GAC9B,KAAK,CAAC,MAAM,CAAC,CAQf;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,QAAQ,EAClB,6BAA6B,GAAE,MAAM,EAAO,GAC3C,iBAAiB,CAyCnB"}