@pythnetwork/price-pusher 4.1.1

package/LICENSE

@@ -0,0 +1,13 @@
+Copyright 2023 Pyth Contributors.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/README.md

@@ -0,0 +1,141 @@
+# Pyth price pusher
+
+Pyth price pusher is a service that regularly pushes updates to the on-chain Pyth price based on configurable conditions.
+
+## Background
+
+Pyth is a cross-chain oracle that streams price updates over the peer-to-peer [Wormhole Network](https://wormholenetwork.com/).
+These price updates can be consumed on any chain that has a deployment of the Pyth contract.
+By default, Pyth does not automatically update the on-chain price every time the off-chain price changes;
+instead, anyone can permissionlessly update the on-chain price prior to using it.
+For more information please refer to [this document](https://docs.pyth.network/design-overview).
+
+Protocols integrating with can update the on-chain Pyth prices in two different ways.
+The first approach is on-demand updates: package a Pyth price update together with each transaction that depends on it.
+On-demand updates minimize latency and are more gas efficient, as prices are only updated on-chain when they are needed.
+
+The second approach is to run this service to regularly push updates to the on-chain price.
+This approach is useful for protocols that already depend on regular push updates.
+
+## Running Price Pusher
+
+The price pusher service monitors both the off-chain and on-chain Pyth price for a configured set of price feeds.
+It then pushes a price update to an on-chain Pyth contract if any of the following conditions are met:
+
+- Time difference: The on-chain price is older than `time_difference` seconds
+  from the latest Pyth price.
+- Price deviation: The latest Pyth price feed has changed more than `price_deviation` percent
+  from the on-chain price feed price.
+- Confidence ratio: The latest Pyth price feed has confidence to price ratio of more than
+  `confidence_ratio`.
+
+The parameters above are configured per price feed in a price configuration YAML file. The structure looks like this:
+
+```yaml
+- alias: A/USD # Arbitrary alias for the price feed. It is used in enhance logging.
+  id: 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef # id of a price feed, a 32-byte hex string.
+  time_difference: 60 # Time difference threshold (in seconds) to push a newer price feed.
+  price_deviation: 0.5 # The price deviation (%) threshold to push a newer price feed.
+  confidence_ratio: 1 # The confidence/price (%) threshold to push a newer price feed.
+- ...
+```
+
+You can get the list of available price feeds from
+[here](https://pyth.network/developers/price-feed-ids/).
+
+To run the price pusher, please run the following commands, replacing the command line arguments as necessary:
+
+```sh
+# Only run it the first time to build the code
+npm install
+npx lerna run build
+
+# For EVM
+npm run start -- evm --endpoint wss://example-rpc.com \
+    --pyth-contract-address 0xff1a0f4744e8582DF...... \
+    --price-service-endpoint https://example-pyth-price.com \
+    --price-config-file "path/to/price-config-file.yaml.testnet.sample.yaml" \
+    --mnemonic-file "path/to/mnemonic.txt" \
+    [--pushing-frequency 10] \
+    [--polling-frequency 5] \
+    [--override-gas-price-multiplier 1.1]
+
+# For Injective
+npm run start -- injective --grpc-endpoint https://grpc-endpoint.com \
+    --pyth-contract-address inj1z60tg0... --price-service-endpoint "https://example-pyth-price.com" \
+    --price-config-file "path/to/price-config-file.yaml.testnet.sample.yaml" \
+    --mnemonic-file "path/to/mnemonic.txt" \
+    [--pushing-frequency 10] \
+    [--polling-frequency 5] \
+
+
+# Or, run the price pusher docker image instead of building from the source
+docker run public.ecr.aws/pyth-network/xc-price-pusher:v<version> -- <above-arguments>
+```
+
+### Command Line Arguments
+
+To know more about the arguments the price-pusher accepts. You can run:
+
+```sh
+npm run start -- --help
+
+# for specific network run
+npm run start -- {network} --help
+```
+
+### Example
+
+For example, to push `BTC/USD` and `BNB/USD` prices on Fantom testnet, run the following command:
+
+```sh
+npm run dev -- evm --endpoint https://endpoints.omniatech.io/v1/fantom/testnet/public \
+    --pyth-contract-address 0xff1a0f4744e8582DF1aE09D5611b887B6a12925C --price-service-endpoint https://xc-testnet.pyth.network \
+    --mnemonic-file "./mnemonic" --price-config-file "./price-config.testnet.sample.yaml"
+```
+
+[`price-config.testnet.sample.yaml`](./price-config.testnet.sample.yaml) contains configuration for `BTC/USD`
+and `BNB/USD` price feeds on Pyth testnet. [`price-config.mainnet.sample.yaml`](./price-config.mainnet.sample.yaml)
+contains the same configuration for `BTC/USD` and `BNB/USD` on Pyth mainnet.
+
+You can also provide a config file instead of providing command line options, run the following command:
+
+```sh
+npm run start -- injective --config "./config.injective.sample.json"
+```
+
+[`config.injective.sample.json`](./config.injective.sample.json) contains configuration to publish on Injective testnet.
+
+## Running using a standalone price service (via docker-compose)
+
+Price pusher communicates with [Pyth price service][] to get the most recent price updates. Pyth price service listens to the
+Wormhole network to get latest price updates, and serves REST and websocket APIs for consumers to fetch the updates.
+Pyth hosts public endpoints for the price service; however, it is recommended to run it standalone to achieve more resiliency and
+scalability.
+
+This directory contains sample docker compose files ([testnet](./docker-compose.testnet.sample.yaml),
+[mainnet](./docker-compose.mainnet.sample.yaml)) a price pusher and its dependencies, including a
+price service and a Wormhole spy. A price service depends on a Wormhole spy. A spy listens to the Wormhole
+network and reports all Pyth-related Wormhole messages to the price service.
+
+To run the services via docker-compose, please modify the your target network (testnet, mainnet) sample docker-compose file to adjust the configurations.
+
+Then, start the docker-compose like this:
+
+```
+docker-compose -f docker-compose.testnet.sample.yaml up
+```
+
+It will take a few minutes until all the services are up and running.
+
+[pyth price service]: https://github.com/pyth-network/pyth-crosschain/tree/main/price_service/server
+
+## Reliability
+
+You can run multiple instances of the price pusher to increase the reliability. It is better to use
+difference RPCs to get better reliability in case an RPC goes down. **If you use the same payer account
+in different pushers, then due to blockchains nonce or sequence for accounts, a transaction won't be
+pushed twiced and you won't pay additional costs most of the time.** However, there might be some race
+condiitons in the RPCs because they are often behind a load balancer than can sometimes cause rejected
+transactions land on-chain. You can reduce the chances of additional cost overhead by reducing the
+pushing frequency.

package/lib/controller.d.ts

@@ -0,0 +1,14 @@
+import { DurationInSeconds } from "./utils";
+import { IPricePusher, IPriceListener } from "./interface";
+import { PriceConfig } from "./price-config";
+export declare class Controller {
+    private priceConfigs;
+    private sourcePriceListener;
+    private targetPriceListener;
+    private targetChainPricePusher;
+    private pushingFrequency;
+    constructor(priceConfigs: PriceConfig[], sourcePriceListener: IPriceListener, targetPriceListener: IPriceListener, targetChainPricePusher: IPricePusher, config: {
+        pushingFrequency: DurationInSeconds;
+    });
+    start(): Promise<void>;
+}

package/lib/controller.js

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Controller = void 0;
+const utils_1 = require("./utils");
+const price_config_1 = require("./price-config");
+class Controller {
+    priceConfigs;
+    sourcePriceListener;
+    targetPriceListener;
+    targetChainPricePusher;
+    pushingFrequency;
+    constructor(priceConfigs, sourcePriceListener, targetPriceListener, targetChainPricePusher, config) {
+        this.priceConfigs = priceConfigs;
+        this.sourcePriceListener = sourcePriceListener;
+        this.targetPriceListener = targetPriceListener;
+        this.targetChainPricePusher = targetChainPricePusher;
+        this.pushingFrequency = config.pushingFrequency;
+    }
+    async start() {
+        // start the listeners
+        await this.sourcePriceListener.start();
+        await this.targetPriceListener.start();
+        // wait for the listeners to get updated. There could be a restart
+        // before this run and we need to respect the cooldown duration as
+        // their might be a message sent before.
+        await (0, utils_1.sleep)(this.pushingFrequency * 1000);
+        for (;;) {
+            const pricesToPush = [];
+            const pubTimesToPush = [];
+            for (const priceConfig of this.priceConfigs) {
+                const priceId = priceConfig.id;
+                const targetLatestPrice = this.targetPriceListener.getLatestPriceInfo(priceId);
+                const sourceLatestPrice = this.sourcePriceListener.getLatestPriceInfo(priceId);
+                if ((0, price_config_1.shouldUpdate)(priceConfig, sourceLatestPrice, targetLatestPrice)) {
+                    pricesToPush.push(priceConfig);
+                    pubTimesToPush.push((targetLatestPrice?.publishTime || 0) + 1);
+                }
+            }
+            if (pricesToPush.length !== 0) {
+                console.log("Some of the above values passed the threshold. Will push the price.");
+                // note that the priceIds are without leading "0x"
+                const priceIds = pricesToPush.map((priceConfig) => priceConfig.id);
+                this.targetChainPricePusher.updatePriceFeed(priceIds, pubTimesToPush);
+            }
+            else {
+                console.log("None of the above values passed the threshold. No push needed.");
+            }
+            await (0, utils_1.sleep)(this.pushingFrequency * 1000);
+        }
+    }
+}
+exports.Controller = Controller;

package/lib/evm/command.d.ts

@@ -0,0 +1,19 @@
+import { Options } from "yargs";
+declare const _default: {
+    command: string;
+    describe: string;
+    builder: {
+        "pushing-frequency": Options;
+        "polling-frequency": Options;
+        "pyth-contract-address": Options;
+        "mnemonic-file": Options;
+        "price-service-endpoint": Options;
+        "price-config-file": Options;
+        endpoint: Options;
+        "custom-gas-station": Options;
+        "tx-speed": Options;
+        "override-gas-price-multiplier": Options;
+    };
+    handler: (argv: any) => void;
+};
+export default _default;

package/lib/evm/command.js

@@ -0,0 +1,99 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const price_service_client_1 = require("@pythnetwork/price-service-client");
+const options = __importStar(require("../options"));
+const price_config_1 = require("../price-config");
+const fs_1 = __importDefault(require("fs"));
+const pyth_price_listener_1 = require("../pyth-price-listener");
+const controller_1 = require("../controller");
+const evm_1 = require("./evm");
+const custom_gas_station_1 = require("./custom-gas-station");
+exports.default = {
+    command: "evm",
+    describe: "run price pusher for evm",
+    builder: {
+        endpoint: {
+            description: "RPC endpoint URL for evm network. If you provide a normal HTTP endpoint, the pusher " +
+                "will periodically poll for updates. The polling interval is configurable via the " +
+                "`polling-frequency` command-line argument. If you provide a websocket RPC " +
+                "endpoint (`ws[s]://...`), the price pusher will use event subscriptions to read " +
+                "the current EVM price in addition to polling. ",
+            type: "string",
+            required: true,
+        },
+        "custom-gas-station": {
+            description: "If using a custom gas station, chainId of custom gas station to use",
+            type: "number",
+            required: false,
+        },
+        "tx-speed": {
+            description: "txSpeed for custom gas station. choose between 'slow'|'standard'|'fast'",
+            choices: ["slow", "standard", "fast"],
+            required: false,
+        },
+        "override-gas-price-multiplier": {
+            description: "Multiply the gas price by this number if the transaction is not landing to override it. Default to 1.1",
+            type: "number",
+            required: false,
+            default: 1.1,
+        },
+        ...options.priceConfigFile,
+        ...options.priceServiceEndpoint,
+        ...options.mnemonicFile,
+        ...options.pythContractAddress,
+        ...options.pollingFrequency,
+        ...options.pushingFrequency,
+    },
+    handler: function (argv) {
+        // FIXME: type checks for this
+        const { endpoint, priceConfigFile, priceServiceEndpoint, mnemonicFile, pythContractAddress, pushingFrequency, pollingFrequency, customGasStation, txSpeed, overrideGasPriceMultiplier, } = argv;
+        const priceConfigs = (0, price_config_1.readPriceConfigFile)(priceConfigFile);
+        const priceServiceConnection = new price_service_client_1.PriceServiceConnection(priceServiceEndpoint, {
+            logger: {
+                // Log only warnings and errors from the price service client
+                info: () => undefined,
+                warn: console.warn,
+                error: console.error,
+                debug: () => undefined,
+                trace: () => undefined,
+            },
+        });
+        const mnemonic = fs_1.default.readFileSync(mnemonicFile, "utf-8").trim();
+        const priceItems = priceConfigs.map(({ id, alias }) => ({ id, alias }));
+        const pythListener = new pyth_price_listener_1.PythPriceListener(priceServiceConnection, priceItems);
+        const pythContractFactory = new evm_1.PythContractFactory(endpoint, mnemonic, pythContractAddress);
+        const evmListener = new evm_1.EvmPriceListener(pythContractFactory, priceItems, {
+            pollingFrequency,
+        });
+        const gasStation = (0, custom_gas_station_1.getCustomGasStation)(customGasStation, txSpeed);
+        const evmPusher = new evm_1.EvmPricePusher(priceServiceConnection, pythContractFactory, overrideGasPriceMultiplier, gasStation);
+        const controller = new controller_1.Controller(priceConfigs, pythListener, evmListener, evmPusher, { pushingFrequency });
+        controller.start();
+    },
+};

package/lib/evm/custom-gas-station.d.ts

@@ -0,0 +1,9 @@
+export declare class CustomGasStation {
+    private chain;
+    private speed;
+    private chainMethods;
+    constructor(chain: number, speed: string);
+    getCustomGasPrice(): Promise<string | undefined>;
+    private fetchMaticMainnetGasPrice;
+}
+export declare function getCustomGasStation(customGasStation?: number, txSpeed?: string): CustomGasStation | undefined;

package/lib/evm/custom-gas-station.js

@@ -0,0 +1,43 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getCustomGasStation = exports.CustomGasStation = void 0;
+const web3_1 = __importDefault(require("web3"));
+const utils_1 = require("../utils");
+class CustomGasStation {
+    chain;
+    speed;
+    chainMethods = {
+        137: this.fetchMaticMainnetGasPrice.bind(this),
+    };
+    constructor(chain, speed) {
+        this.speed = (0, utils_1.verifyValidOption)(speed, utils_1.txSpeeds);
+        this.chain = (0, utils_1.verifyValidOption)(chain, utils_1.customGasChainIds);
+    }
+    async getCustomGasPrice() {
+        return this.chainMethods[this.chain]();
+    }
+    async fetchMaticMainnetGasPrice() {
+        try {
+            const res = await fetch("https://gasstation-mainnet.matic.network/v2");
+            const jsonRes = await res.json();
+            const gasPrice = jsonRes[this.speed].maxFee;
+            const gweiGasPrice = web3_1.default.utils.toWei(gasPrice.toFixed(2), "Gwei");
+            return gweiGasPrice.toString();
+        }
+        catch (e) {
+            console.error("Failed to fetch gas price from Matic mainnet. Returning undefined");
+            console.error(e);
+            return undefined;
+        }
+    }
+}
+exports.CustomGasStation = CustomGasStation;
+function getCustomGasStation(customGasStation, txSpeed) {
+    if (customGasStation && txSpeed) {
+        return new CustomGasStation(customGasStation, txSpeed);
+    }
+}
+exports.getCustomGasStation = getCustomGasStation;

package/lib/evm/evm.d.ts

@@ -0,0 +1,53 @@
+import { Contract } from "web3-eth-contract";
+import { IPricePusher, PriceInfo, ChainPriceListener, PriceItem } from "../interface";
+import { DurationInSeconds } from "../utils";
+import HDWalletProvider from "@truffle/hdwallet-provider";
+import { PriceServiceConnection, HexString, UnixTimestamp } from "@pythnetwork/price-service-client";
+import { CustomGasStation } from "./custom-gas-station";
+export declare class EvmPriceListener extends ChainPriceListener {
+    private pythContractFactory;
+    private pythContract;
+    constructor(pythContractFactory: PythContractFactory, priceItems: PriceItem[], config: {
+        pollingFrequency: DurationInSeconds;
+    });
+    start(): Promise<void>;
+    private startSubscription;
+    private onPriceFeedUpdate;
+    getOnChainPriceInfo(priceId: HexString): Promise<PriceInfo | undefined>;
+}
+export declare class EvmPricePusher implements IPricePusher {
+    private connection;
+    private overrideGasPriceMultiplier;
+    private customGasStation?;
+    private pythContract;
+    private web3;
+    private pusherAddress;
+    private lastPushAttempt;
+    constructor(connection: PriceServiceConnection, pythContractFactory: PythContractFactory, overrideGasPriceMultiplier: number, customGasStation?: CustomGasStation);
+    updatePriceFeed(priceIds: string[], pubTimesToPush: UnixTimestamp[]): Promise<void>;
+    private getPriceFeedsUpdateData;
+}
+export declare class PythContractFactory {
+    private endpoint;
+    private mnemonic;
+    private pythContractAddress;
+    constructor(endpoint: string, mnemonic: string, pythContractAddress: string);
+    /**
+     * This method creates a web3 Pyth contract with payer (based on HDWalletProvider). As this
+     * provider is an HDWalletProvider it does not support subscriptions even if the
+     * endpoint is a websocket endpoint.
+     *
+     * @returns Pyth contract
+     */
+    createPythContractWithPayer(): Contract;
+    /**
+     * This method creates a web3 Pyth contract with the given endpoint as its provider. If
+     * the endpoint is a websocket endpoint the contract will support subscriptions.
+     *
+     * @returns Pyth contract
+     */
+    createPythContract(): Contract;
+    hasWebsocketProvider(): boolean;
+    createWeb3Provider(): import("web3-core").HttpProvider | import("web3-core").WebsocketProvider;
+    createWeb3PayerProvider(): HDWalletProvider;
+}