Here are presented different use cases for Guardian with running as in development environment and production.
Each of the examples contains 2 parts:
- Guardian config
config.ymlthat describes types of events to subscribe to. - Node.js scripts that are fired if a certain event was emitted.
Both of the scripts can be customized.
Cloning project, navigating to the examples folder
git clone https://github.com/open-web3-stack/guardian.git
cd guardian/packages/example-guardian
Installing dependencies
yarn
Each of the examples is meant to work on the respective network: Acala, Karura, Laminar, Kusama, Polkadot, etc.
You can find some public nodes here.
You may want to try the scripts running your local testnet. For some examples like Bots for Liquidations, it may be more convenient as it's way easier to trigger liquidation in the network you can control. To run local testnets you need to follow guides in the respective projects.
Each example is provided with .env.<example-name> file that contains an example of configuration, and includes network:
NODE_ENDPOINT environment variable.
For local testnet it conventionally equals ws://localhost:9944.
Using docker:
docker run --rm -p 9944:9944 laminar/laminar-node:latest \
--dev --ws-external --rpc-methods=unsafe \
-levm=trace --tmp
To build the project without docker use the guidelines here:
laminar-protocol/laminar-chain
Run the node with:
cargo run -- --dev --tmp
Using docker:
docker run --rm -p 9944:9944 acala/karura-node:1.5.0 \
--dev --ws-external --rpc-methods=unsafe \
--instant-sealing -levm=trace --tmp
To build the project without docker use the guidelines here: AcalaNetwork/Acala
To help you trigger certain events and to ensure that the bot picks them up we provide sets of emulations:
- for Acala/Karura: https://github.com/AcalaNetwork/e2e
- for Laminar: https://github.com/laminar-protocol/e2e
In this guide, we provide a way how to use them.
You can extend the YAML config files and run Guardian using option --config=config.yml.
Note: find the up to date public node info here.
All presented examples can be automatically deployed to Heroku for use in production. Here you can find an example for Dex Price bot and a way how to modify it with other samples:
This example uses the scheduler yaml config file and task source code here. It will periodically (every s blocks) get the balance of a given address on the Kusama network.
The configuration file you can find here: .env.schedule
It cointains next env variables:
NODE_ENDPOINT=wss://kusama-rpc.polkadot.io/
ADDRESS=<YOUR_KUSAMA_ADDRESS>
Run in dev mode:
yarn dev:schedule
The output should look like this:
0000-00-00000:00:00.000Z LOG [@open-web3/guardian]: [substrate-chain] starting...
0000-00-00000:00:00.000Z LOG [@open-web3/guardian]: [time-monitor.schedule.time] starting ...
0000-00-00000:00:00.000Z LOG [@open-web3/guardian]: [blockNumber-monitor.schedule.blockNumber] starting ...
0000-00-00000:00:00.000Z LOG [@open-web3/guardian]: [time-monitor.schedule.time] is running ...
0000-00-00000:00:00.000Z LOG [@open-web3/guardian]: [blockNumber-monitor.schedule.blockNumber] is running ...
0000-00-00000:00:00.000Z LOG [@open-web3/guardian]: [substrate-chain] is running ...
0000-00-00000:00:00.000Z LOG [@open-web3/guardian]: [blockNumber-monitor.schedule.blockNumber] output: { current: 6074807, next: 6074809 }
0000-00-00000:00:00.000Z LOG [@open-web3/guardian]: [blockNumber-monitor.schedule.blockNumber] called [getBalance]
0000-00-00000:00:00.000Z LOG [@open-web3/example-guardian]: balance: {
nonce: '120',
refcount: '1',
data: {
free: '4.0020 kKSM',
reserved: '1.0083 KSM',
miscFrozen: '4.0003 kKSM',
feeFrozen: '4.0003 kKSM'
}
}
This example uses the staking yaml config file and tasks source code here. It will check staking reward event for a given address on the Kusama network, and send out an email notification if there's an event. Currently reward is given out once a day.
The configuration file you can find here: .env.staking
It cointains next env variables:
NODE_ENDPOINT=wss://kusama-rpc.polkadot.io/
ADDRESS=<YOUR_KUSAMA_ADDRESS>
This Bot can be used for the following rewards for 3d party protocols built on top on top of Polkadot/Kusama staking.
One of them is Karura Staking Derivative. You can check the rewards using providing L-KSM staking address:
HTAeD1dokCVs9MwnC1q9s2a7d2kQ52TAjrxE1y5mj5MFLLA. To check the rewards in UI, use the link here.
Run in dev mode:
yarn dev:staking
This example uses the collateral auction yaml config file and task source code here. It will watch collateral auctions and DEX pools, (DEX is used to liquidate collaterals if the price slippage is acceptable) and bid from the specified account if the price of collateral is lower than the price from Price oracle for MARGIN coefficient.
Configuration file you can find here: .env.auction
It cointains next env variables:
NETWORK=dev # or karura
SURI=//Charlie
ADDRESS=5FLSigC9HGRKVhB9FiEo4Y3koPsNmBmLJbpXg2mp1hXcS59Y
MARGIN=0.1
Note
⚠️ to test out this example it's recommended to use a local testnet.
Run in dev mode:
yarn dev:collateral-auction
The liquidation simulation script will work only for your local Karura testnet, you should ensure that it's running.
To use simulation you need to clone the repository and run the simulation script:
git clone https://github.com/AcalaNetwork/e2e.git acala-simulations
cd acala-simulations
Install dependencies:
yarn
Run simulation:
yarn dev:simulate-liquidate-cdp
This example uses the cdp guardian yaml config file and task source code here. It will monitor specified account's loan positions. If the collateral ratio of the loans drops below a given threshold (COLLATERAL_RATIO) for a selected account (ADDRESS), it will deposit more liquidity to de-risk the loan and keep the position open.
Configuration file you can find here: .env.cdp
It cointains next env variables:
NETWORK=dev # or karura
SURI=//Charlie
ADDRESS=5FLSigC9HGRKVhB9FiEo4Y3koPsNmBmLJbpXg2mp1hXcS59Y
COLLATERAL_RATIO=1.4
Note
⚠️ to test out this example it's recommended to use a local testnet.
Run in dev mode:
yarn dev:cdp
The Loan collateral ratio drop simulation script will work only for your local Karura testnet, you should ensure that it's running.
To use simulation you need to clone the repository and run the simulation script:
git clone https://github.com/AcalaNetwork/e2e.git acala-simulations
cd acala-simulations
Install dependencies:
yarn
Run simulation:
yarn dev:dev:simulate-loan
This example uses the dex-price guardian yaml config file and task source code here. It will monitor a specified liquidity pair (TOKEN_A and TOKEN_B) and perform an action whenever there is a price change for that pair.
Configuration file you can find here: .env.dex-price
It cointains next env variables:
NETWORK=karura
TOKEN_A=KUSD
TOKEN_B=KSM
Run in dev mode:
yarn dev:dex-price
This example uses the laminar synthetic liquidation yaml config file and task source code here. It will monitor specified account's (ADDRESS) synthetic asset trading positions. If the collateral ratio of the trade drops below a given threshold (COLLATERAL_RATIO), it will liquidate the position.
Configuration file you can find here: .env.laminar-synthetic-liquidation
It cointains next env variables:
NODE_ENDPOINT=ws://localhost:9944
SURI=//Charlie
ADDRESS=5FLSigC9HGRKVhB9FiEo4Y3koPsNmBmLJbpXg2mp1hXcS59Y
COLLATERAL_RATIO=1.1
Note
⚠️ to test out this example it's recommended to use local testnet.
Run in dev mode:
yarn dev:laminar-synthetic-liquidation
The synthetic pool liquidation simulation script will work only for your local Laminar testnet, you should ensure that it's running.
To use simulation you need to clone the repository and run the simulation script:
git clone https://github.com/laminar-protocol/e2e.git laminar-simulations
cd laminar-simulations
Install dependencies:
yarn
Run simulation:
yarn dev:simulate-liquidate-synthetic-pool
Simulation output should look like this:
The bot should pick up the event and display the next output:
This example uses the laminar margin position yaml config file and task source code here. It will monitor specified account's margin positions. If the profit goes below a given threshold, it will close the position.
Configuration file you can find here: .env.laminar-margin-position
It cointains next env variables:
NODE_ENDPOINT=ws://localhost:9944
SURI=//Charlie
ADDRESS=5FLSigC9HGRKVhB9FiEo4Y3koPsNmBmLJbpXg2mp1hXcS59Y
# close position if profit goes below -10aUSD
PROFIT=-10000000000000000000
Note
⚠️ to test out this example it's recommended to use local testnet.
Run in dev mode:
yarn dev:laminar-margin-position
The Margin position price drop simulation script will work only for your local Laminar testnet, you should ensure that it's running.
To use simulation you need to clone the repository and run the simulation script:
git clone https://github.com/laminar-protocol/e2e.git laminar-simulations
cd laminar-simulations
Install dependencies:
yarn
Run simulation:
yarn dev:simulate-margin-position
The simulation terminal should look like this:
The bot terminal should pick up the dropped position and display it like this:
You can also navigate to https://polkadot.js.org/apps/#/explorer, connect to the local node and check the events happening in the Network -> Explorer tab, to check all events were happening:
⚠️ you may see the empty event list if you ran guardian and simulation after you opened the polkadot.js.org/apps, as it may not pick up these events. In this case, you should rerun the guarding and simulation, and all events will show up.