📡Jobs

A Job will store data into our Cache, those data are usually common data for all users (information about the amounts of a tokens on a lending protocol, liquidity pools token prices, etc..).

Jobs are very powerful because they enable faster load time by pre-fetching data and storing them into our Cache. This Cache is optimized to allow Fetchers to recover any data from it, with very low response time.

We highly recommend exploring other jobs from other plugins to gather some examples of what a job can do.

When do you need a job ?

Some protocols do not require any Job, Uniswap V3 for instance only requires a Fetcher because there is no common data used to compute the value of a user's position.

But most plugins are using jobs because they have at least 1 request shared by all users, therefore it's better to put it inside a Job rather than in the Fetcher.

Here is a non-exhaustive list of what you could find inside a Job :

• Recover all existing pools of a protocol and storing LP token prices of each pool

• Recover all markets/reserves of a lending protocol

• Determine the price of a tokenized lending protocol (Aave, Solend, etc...)

• Determine the price of a Liquid Stake token

• Store the list of active validators

• Store the list of active CLOB Markets

How to create a Job

To create a job you have to run the following command :

npx nx generate @sonarwatch/portfolio-plugins:job --jobName=myJob --pluginId=myPluginName

You should now see a new file called <myJobName>Job.ts in your plugin folder.

Once a Job is created, to be able to test it you need to add it inside your index.ts file like this :

import myJob from './<myJobName>Job.ts';

export const jobs: Job[] = [myJob];

Remember : in order to test your jobs, you have to also import your jobs inside the main index.ts file, more info here

How to use the Cache inside your job

To add data to the Cache, you will mainly use the following methods on the cache object :

• setTokenPriceSource : add a price for a specific Token address (token, lp, etc...)

• getTokenPrice : get a price for an address

• getTokenPrices : get prices for multiple addresses (avoid multiple calls on the Cache)

• setItem : add any type of data inside the Cache.

• getItem : get data from the Cache.

You can find all methods here.

Storing data

When storing a TokenPriceSource inside the cache, you need to provide a TokenPriceSource object, which contains all information about the price (sourceId, price, network, token address etc...).

When storing an Item inside the cache, you need to provide few elements in order to store it properly :

• key : this identifies an item (example : the address of a pool)

• StorageValue : this is the data you would like to store (⚠️make sure the data can be stored as a JSON element) (example : the pool's data)

• TransactionOptions : additional details to organize the data inside the cache :

  • prefix : this is used to setup a path within the Cache (example : 'uniswapV3' will store the pool's data inside /uniswapV3/poolAddress/ )

  • networkId (optional) : if you want to specify the network (can be applied to multi-chains protocols for instance) (example : 'ethereum' will store the pool's data inside /ethereum/uniswapV3/poolAddress/ )

In general, data is stored with the following path logic :

/networkId/platformId/key/

Retrieving data

When fetching a TokenPrice from the Cache you need to provide the address of the token as long as the network on which you want to recover the price. This will give you a TokenPrice object (or undefined if the price is not in the Cache).

You can also fetch multiple TokenPrice at the same time (for better efficiency).

When fetching an Item (getItem) the best is to specify what type of data you're looking for, you will have a to give the key of the Item but also the prefix used to store it.

You can also fetch multiple items at the same time.

How to run your job

Once your logic is finished in your Job, here is how to test it :

1. Run your local Cache

   npx nx run plugins:serve-cache

2. Run your Job

   npx nx run plugins:run-job myPluginName-myJob

3. Check if the Job stored some data inside the Cache by going to http://localhost:3000

If your Job is adding prices for tokens, make sure to verify those prices by :

1. Running your Job : this will add prices into your local Cache.

2. Running the Wallet Token Fetcher on the correct network : this will fetch all tokens within the wallet and get the prices from the Cache (local + distant), like this :

npx nx run plugins:run-fetcher wallet-tokens-solana tEsT1vjsJeKHw9GH5HpnQszn2LWmjR6q1AVCDCj51nd

Now that you know everything about how Jobs work, let's dive into the Fetchers!