Skip to content

XLabs/wallet-monitor

Repository files navigation

Wallet Monitor

This is a npm package that allows you to monitor the balance of multiple wallets in multiple blockchains. Along monitoring, it can also export the balances as prometheus metrics and perform rebalancing strategies between your wallets.
It can be used as a package within a nodejs application (library modality) or as a gRPC service (service modality).

Table of Contents

TL;DR

WalletManager exposes a few utilities to monitor the balance of a wallet in a blockchain. Optionally, you can also monitor the balance of tokens for the wallet.
The module requires near zero configuration by defaulting most required values to what would be reasonable, but it can be configured more granularly if needed.
WalletManager uses underneath multiple ChainWalletManager objects, one for each blockchain you want to monitor.
ChainWalletManager in turn uses a WalletToolbox object to perform the actual monitoring of the wallet.
These objects are composed rather than inherited and this means that they will have, in general, different interfaces, but it is always possible to use them independently.
Check out the example.

Contributions

Any feature request for this project is welcomed and will be considered for implementation.
The more detail you can provide about your use case, the better.

WalletManager

This is the main object of the package. It is responsible for efficiently dispatching your configuration to the right ChainWalletManager objects and for aggregating the results. It can do locking of each wallet and will also take care of exporting balances, metrics and errors if you want it to.
In general, it is a useful class to treat a collection of ChainWalletManager objects as a single object.

It's useful to explain the properties and features of this class by looking at the configuration and options that are passed to the constructor (using zod).

WalletManagerConfig

export const WalletManagerChainConfigSchema = z.object({
  network: z.string().optional(),
  chainConfig: z.any().optional(),
  rebalance: z.object({
    enabled: z.boolean(),
    strategy: z.string().optional(),
    interval: z.number().optional(),
    minBalanceThreshold: z.number().optional(),
    maxGasPrice: z.number().optional(),
    gasLimit: z.number().optional(),
  }).optional(),
  wallets: z.array(WalletConfigSchema),
  priceFeedConfig: WalletPriceFeedConfigSchema.optional()
})

export const TokenInfoSchema = z.object({
  tokenContract: z.string(),
  chainId: z.number(),
  coingeckoId: CoinGeckoIdsSchema,
  symbol: z.string().optional(),
})

export const WalletPriceFeedConfigSchema = z.object({
  enabled: z.boolean(),
  supportedTokens: z.array(TokenInfoSchema),
  pricePrecision: z.number().optional(),
  scheduled: z.object({
    enabled: z.boolean().default(false),
    interval: z.number().optional(),
  }).optional(),
})

export const WalletManagerConfigSchema = z.record(z.string(), WalletManagerChainConfigSchema)

In short, each record keys is the name of a chain. The value within that record is a network name, an optional rebalancing strategy and a collection of wallets.
Also, check out the rebalancing example.

To enable, token prices in USD, use price feed config in WalletManagerChainConfig, which can be configured per chain. Furthermore, we can also control whether the token prices needs to be synced in the background periodically (i.e with scheduled option) or whether the prices needs to be fetched on-demand in real-time. Checkout the pricefeed configuration example.

WalletManagerOptions

export const WalletManagerOptionsSchema = z.object({
  logger: z.any().optional(),
  logLevel: z.union([
      z.literal('error'),
      z.literal('warn'),
      z.literal('info'),
      z.literal('debug'),
      z.literal('verbose'),
      z.literal('silent'),
  ]).optional(),
  balancePollInterval: z.number().optional(),
  metrics: z.object({
    enabled: z.boolean(),
    port: z.number().optional(),
    path: z.string().optional(),
    registry: z.any().optional(),
    serve: z.boolean().optional(),
  }).optional(),
});

The options applied to all blockchains and wallets monitored specify logging and if/where to expose prometheus metrics.

There are cases where WalletManager needs to be used with all its functionality but the application code does not need to interact with the monitoring or rebalancing. In such cases, you can use buildWalletManager convenience function which will return a WalletManager masked by the correct interface that will only allow you to interact with the locking mechanisms of the wallets.

ChainWalletManager

This class knows how to use a WalletToolbox to perform chain-specific monitoring and transactional operations.
The interface is mostly similar to WalletManager but it is pending to be refactored to be more consistent.

WalletToolbox

A WalletToolbox handles the communication with the blockchain and is responsible for knowing reasonable defaults for the blockchain endpoints, networks, token IDs, which sdk to use and how to handle sdk results.

This object is also really useful on its own if you want to have fine-grained control over which network calls you are making.

Supported Tokens

While you can pass any token address to the wallet monitor, for simplicity a list of supported tokens is provided so you can use their symbols instead. See the table below:

Ethereum

Symbol Address
WETH 0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2
USDC 0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48
USDT 0xdac17f958d2ee523a2206206994597c13d831ec7
WBTC 0x2260fac5e5542a773aa44fbcfedf7c193bc2c599
WBNB 0x418D75f65a02b3D53B2418FB8E1fe493759c7605
WMATIC 0x7c9f4C87d911613Fe9ca58b579f737911AAD2D43
WAVAX 0x85f138bfEE4ef8e540890CFb48F620571d67Eda3
WFTM 0x4cD2690d86284e044cb63E60F1EB218a825a7e92
WCELO 0x3294395e62f4eb6af3f1fcf89f5602d90fb3ef69
WGLMR 0x93d3696A9F879b331f40CB5059e37015423A3Bd0
WSUI 0x84074EA631dEc7a4edcD5303d164D5dEa4c653D6
WARB 0xB50721BCf8d664c30412Cfbc6cf7a15145234ad1

Binance Smart Chain

Symbol Address
WETH 0x4db5a66e937a9f4473fa95b1caf1d1e1d62e29ea
USDC 0xB04906e95AB5D797aDA81508115611fee694c2b3
USDT 0x524bC91Dc82d6b90EF29F76A3ECAaBAffFD490Bc
WBTC 0x43359676e1a3f9fbb5de095333f8e9c1b46dfa44
WBNB 0xbb4cdb9cbd36b01bd1cbaebf2de08d9173bc095c
WMATIC 0xc836d8dC361E44DbE64c4862D55BA041F88Ddd39
WAVAX 0x96412902aa9aFf61E13f085e70D3152C6ef2a817
WFTM 0xbF8413EE8612E0E4f66Aa63B5ebE27f3C5883d47
WCELO 0x2A335e327a55b177f5B40132fEC5D7298aa0D7e6
WGLMR 0x1C063db3c621BF901FC6C1D03328b08b2F9bbfba
WSUI 0x8314f6Bf1B4dd8604A0fC33C84F9AF2fc07AABC8
WARB 0x0c03a1d484b12c63bd499162fca0a403f8104939

Polygon

Symbol Address
WETH 0x11CD37bb86F65419713f30673A480EA33c826872
USDC 0x4318CB63A2b8edf2De971E2F17F77097e499459D
USDT 0x9417669fbf23357d2774e9d421307bd5ea1006d2
WBTC 0x5d49c278340655b56609fdf8976eb0612af3a0c3
WBNB 0xeCDCB5B88F8e3C15f95c720C51c71c9E2080525d
WMATIC 0x0d500b1d8e8ef31e21c99d1db9a6444d3adf1270
WAVAX 0x7Bb11E7f8b10E9e571E5d8Eace04735fDFB2358a
WFTM 0x3726831304D77f585f1Aca9d9841cc3Ef80dAa62
WCELO 0x922F49a9911effc034eE756196E59BE7b90D43b3
WGLMR 0xcC48d6CF842083fEc0E01d913fB964b585975F05
WSUI 0x34bE049fEbfc6C64Ffd82Da08a8931A9a45f2cc8
WARB 0x33c788e1191d18ccd0b6db8176ead234ed22321a

Avalanche

Symbol Address
WETH 0x8b82A291F83ca07Af22120ABa21632088fC92931
USDC 0xB24CA28D4e2742907115fECda335b40dbda07a4C
USDT 0x9d228444FC4B7E15A2C481b48E10247A03351FD8
WBTC 0x1C0e79C5292c59bbC13C9F9f209D204cf4d65aD6
WBNB 0x442F7f22b1EE2c842bEAFf52880d4573E9201158
WMATIC 0xf2f13f0B7008ab2FA4A2418F4ccC3684E49D20Eb
WAVAX 0xb31f66aa3c1e785363f0875a1b74e27b85fd66c7
WFTM 0xd19abc09B7b36F7558929b97a866f499a26c2f83
WCELO 0x494317B8521c5a5287a06DEE467dd6fe285dA4a8
WGLMR 0x375aA6C67BF499fBf01804A9f92C03c0776F372d
WSUI 0x1703CB0F762D2a435199B64Ea47E5349B7C17480
WARB 0x2bb3Caf6b5c3a1FE9C4D9BE969B88FB007fE7FBd

Fantom

Symbol Address
WETH 0x2A126f043BDEBe5A0A9841c51915E562D9B07289
USDC 0x2Ec752329c3EB419136ca5e4432Aa2CDb1eA23e6
USDT 0x14BCb86aEed6a74D3452550a25D37f1c30AA0A66
WBTC 0x87e9E225aD8a0755B9958fd95BE43DD6A91FF3A7
WBNB 0xc033551e05907Ddd643AE14b6D4a9CA72BfF509B
WMATIC 0xb88A6064B1F3FF5B9AE4A82fFD52560b0dF9FBD3
WAVAX 0x358CE030DC6116Cc296E8B9F002728e65459C146
WFTM 0x21be370d5312f44cb42ce377bc9b8a0cef1a4c83
WCELO 0xF432490C6c96C9d3bF523a499a1CEaFd8208A373
WGLMR 0xBF227E92D6754EB4BFE26C40cb299ff2809Da45f
WSUI 0xC277423a21F6e32D886BF85Ef6cCB945d5D28347
WARB 0x07d2bed56ffdab09bfad5911d70be2af26ed010c

Celo

Symbol Address
WETH 0x66803FB87aBd4aaC3cbB3fAd7C3aa01f6F3FB207
USDC 0x37f750B7cC259A2f741AF45294f6a16572CF5cAd
USDT 0x617f3112bf5397D0467D315cC709EF968D9ba546
WBTC 0xd71Ffd0940c920786eC4DbB5A12306669b5b81EF
WBNB 0xBf2554ce8A4D1351AFeB1aC3E5545AaF7591042d
WMATIC 0x9C234706292b1144133ED509ccc5B3CD193BF712
WAVAX 0xFFdb274b4909fC2efE26C8e4Ddc9fe91963cAA4d
WFTM 0xd1A342eE2210238233a347FEd61EE7Faf9f251ce
WCELO 0x471ece3750da237f93b8e339c536989b8978a438
WGLMR 0x383A5513AbE4Fe36e0E00d484F710148E348Aa9D
WSUI 0x1Cb9859B1A16A67ef83A0c7b9A21eeC17d9a97Dc

Moonbeam

Symbol Address
WETH 0xab3f0245B83feB11d15AAffeFD7AD465a59817eD
USDC 0x931715FEE2d06333043d11F658C8CE934aC61D0c
USDT 0xc30E9cA94CF52f3Bf5692aaCF81353a27052c46f
WBTC 0xE57eBd2d67B462E9926e04a8e33f01cD0D64346D
WBNB 0xE3b841C3f96e647E6dc01b468d6D0AD3562a9eeb
WMATIC 0x82DbDa803bb52434B1f4F41A6F0Acb1242A7dFa3
WAVAX 0xd4937A95BeC789CC1AE1640714C61c160279B22F
WFTM 0x609AedD990bf45926bca9E4eE988b4Fb98587D3A
WCELO 0xc1a792041985F65c17Eb65E66E254DC879CF380b
WGLMR 0xacc15dc74880c9944775448304b263d191c6077f
WSUI 0x484eCCE6775143D3335Ed2C7bCB22151C53B9F49

Arbitrum

Symbol Address
ARB 0x912ce59144191c1204e64559fe8253a0e49e6548
WETH 0x82af49447d8a07e3bd95bd0d56f35241523fbab1
USDC 0xff970a61a04b1ca14834a43f5de4533ebddb5cc8
USDT 0xfd086bc7cd5c481dcc9c85ebe478a1c0b69fcbb9
WBTC 0x2f2a2543b76a4166549f7aab2e75bef0aefc5b0f
WBNB 0x8579794b10f88ebbedd3605f2e5ff54f162d4788
WMATIC 0x3ab0e28c3f56616ad7061b4db38ae337e3809aea
WAVAX 0x565609faf65b92f7be02468acf86f8979423e514
WFTM 0x88a23edbb2e49ac3c1b9f9f49ae8d1c26d734fba
WGLMR 0x944c5b67a03e6cb93ae1e4b70081f13b04cdb6bd
WSUI 0xfe7b5a32c93dc25184d475e3083ba30ed3c1bf8f

SUI

Symbol Address
WETH 0xaf8cd5edc19c4512f4259f0bee101a40d41ebed738ade5874359610ef8eeced5::coin::COIN
USDC 0x5d4b302506645c37ff133b98c4b50a5ae14841659738d6d733d59d0d217a93bf::coin::COIN
USDT 0xc060006111016b8a020ad5b33834984a437aaa7d3c74c18e09a95d48aceab08c::coin::COIN
WBTC 0x27792d9fed7f9844eb4839566001bb6f6cb4804f66aa2da6fe1ee242d896881::coin::COIN
WBNB 0xb848cce11ef3a8f62eccea6eb5b35a12c4c2b1ee1af7755d02d7bd6218e8226f::coin::COIN
WMATIC 0xdbe380b13a6d0f5cdedd58de8f04625263f113b3f9db32b3e1983f49e2841676::coin::COIN
WAVAX 0x1e8b532cca6569cab9f9b9ebc73f8c13885012ade714729aa3b450e0339ac766::coin::COIN
WFTM 0x6081300950a4f1e2081580e919c210436a1bed49080502834950d31ee55a2396::coin::COIN
WCELO 0xa198f3be41cda8c07b3bf3fee02263526e535d682499806979a111e88a5a8d0f::coin::COIN
WGLMR 0x66f87084e49c38f76502d17f87d17f943f183bb94117561eb573e075fdc5ff75::coin::COIN
SUI 0x2::sui::SUI

About

Monitor your wallets as prometheus metrics

Resources

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages