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
• Contributions
• WalletManager
• ChainWalletManager
• WalletToolbox
• Supported Tokens
• gRPC service

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),
})

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.

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