Welcome to perps-keepers!

This repository houses Synthetix Perps keepers to maintain the health and provide a better UX for traders on frontends such as Kwenta and Decentrex. perps-keepers provides 3 main functions. These include:

1. Liquidation of underwater positions
2. Execution of delayed orders
3. Execution of off-chain delayed orders

This project is a fork of futures-keepers. The internals around liquidations remain largely the same but has undergone significant code restructure and now supports delayed and off-chain orders in addition to just liquidations.

perps-keepers architecture is fairly simple. A block listener consumes events from the blockchain (Optimism) and inserts the block number into an in-memory first-in-first-out (FIFO) queue to be consumed by a block distributor. The block distributor queries for events and distributes relevant events each keeper.

Variables for configuration are defined as environment variables. During development they are stored in an .env.staging file at the project root then loaded via dotenv. The contents are as follows:

For an example .env see .env.example. All input variables are validated, see ./src/config.ts for more details (including defaults). Speak with another developer for .env values.

# Clone the repository.
git clone [email protected]:Synthetixio/perps-keepers.git

# Install project dependencies.
npm i

# Execute keeper locally (testnet)
npm run dev

# Execute keeper (mainnet)
npm run dev:mainnet

See configuration section above before attempting to run locally.

# Start your local node
hardhat node --fork https://optimism-goerli.infura.io/v3/<infura key>`

# Fund one of the test wallets.
git clone [email protected]:Synthetixio/synthetix.git

npm i
npx hardhat fund-local-accounts --provider-url http://127.0.0.1:8545/ --target-network goerli-ovm --deployment-path ./publish/deployed/goerli-ovm/ --use-ovm --private-key $GOERLI_OVM_PERPS_DEPLOYER_PRIVATE_KEY --account 0x8626f6940e2eb28930efb4cef49b2d1f2c9c1199

# 0x8626f6940e2eb28930efb4cef49b2d1f2c9c1199` is one of the default accounts from hardhat node --fork

Any host environment with NodeJS installed running a Unix based operating system can execute perps-keepers. It's recommended to use some external service tool to monitor the runtime health of your keeper instance for self-healing purposes.

For example, spinning up a Kubernentes cluster and relying on k8's deployment group configuration, classical AWS AMIs in an ASG (auto-scaling) or even something as simple as pm2.

METRICS_ENABLED=1

perps-keepers uses basic custom CloudWatch metrics throughout the application to track the health of the keeper. These metrics and then be used to configure alerts for notifications. Metrics are disabled by default. They require AWS credentials to be defined and METRICS_ENABLED=1 to be set. You can find the list of all available custom metric in ./src/metrics.ts.

This project's continuous integration/deployment process is managed via GitHub actions. They can be found under the .github/ directory. In short,

• Merge/Push to branch develop will trigger a staging release and start the keeper on ovm-goerli
• Merge/Push to branch master will trigger a production release and start the keeper on ovm-mainnet

To set this up as a fork we need to create GitHub secrets for all required environment variables.