Skip to content

stove-labs/arbitrage-bot

Repository files navigation

Stove Labs Arbitrage Bot

This arbitrage bot speculates on the price differences between two markets, by taking advantage of the difference in asset prices and trades for a profit. The strategy is to buy crypto at a lower price on one exchange and sell immediately at a higher price on the other.

cli-arbitrage-bot

Usage

Please refer to CLI package repository for detailed instructions.

The quickest way to get started is by running:

# this creates a config.json in your directory
npx @stove-labs/arbitrage-bot-cli init

npx @stove-labs/arbitrage-bot-cli start XTZ kUSD
# for verbose output
npx @stove-labs/arbitrage-bot-cli start XTZ kUSD -vv
# help 
npx @stove-labs/arbitrage-bot-cli start -h 
# list tradeable tokens from config
npx @stove-labs/arbitrage-bot-cli list

Benefits

  • Modular plugin architecture: easy to expand support for more markets; improve reporting capabilities or replacing tailored profit finding algorithms (eg. stable swap).

  • Automated price discovery and arbitrage execution and reporting to the console.

  • User defined objective for which base token asset should be accumulated over time.

  • Trade reverts if market conditions change to the worse and therefore profit opportunity vanishes.

  • Multiplier for transaction fee can be increased to stay competitive.

Learning resource

The exercise of using and building upon the arbitrage-bot offers a fantastic hands-on opportunity to learn about blockchain and Tezos development. While the use-case presents technical challenges, it can be overwhelming to extract those learnings by merely going through the code. Therefore, this section lists some of the design/development challenges and discusses their solutions & practical implementations.

  1. Read AMM spot price (exchange plugins: eg. Quipuswap)
  2. Compose batch transactions, estimate & apply adjusted FEEs (swap-execution)
  3. Contract views to read FA2 and FA1.2 token balances (accountant)
  4. Price discovery for arbitrage between 2 DEXs (profit-finder)
  5. Solve polling (without subscribing to block updates) (trigger)

Limitations

The current implementation:

  • Does not have a centralized exchange (CEX) plugin
  • FA1.2 tokens
  • Supports two (CFMMs) decentralized exchanges on Tezos blockchain:
    • Quipuswap (v1) XTZ<>Token
    • Vortex XTZ<>Token
  • Reporting to console

Future work

  • FA2
  • Quipuswap (v2)
  • Token<>Token

For suggestions please open an issue in this Github repository.

Community support channel

Project Organization

@stove-labs/arbitrage-bot is organized as a mono repository from which several npm packages are built and published. High level packages are organized in the packages/ directory, whereas plugins can be found in packages/plugins/. Exchange specific plugins are in packages/plugins/exchanges/. Please note that each package has its own README file.

We publish packages to npmjs.org under the @stove-labs namespace and packages have usually @stove-labs/arbitrage-bot-* format. See below for a complete overview.

High Level Packages Responsibility
@stove-labs/arbitrage-bot Group every other library and provide higher level utility
@stove-labs/arbitrage-bot-cli Command line interface to create & load an example config file and to launch the arbitrage bot
Low Level Packages Responsibility
@stove-labs/arbitrage-bot-profit-finder-lite Calculating optimal swap amounts to extract value through arbitrage
@stove-labs/arbitrage-bot-reporter Reports events to the console
@stove-labs/arbitrage-bot-swap-execution (Batch) executes swaps
@stove-labs/arbitrage-bot-token-registry Provide necessary functions to retrieve detailed token info based on ticker and ecosystem
@stove-labs/arbitrage-bot-trigger-interval Trigger lifecycle based on a user defined time interval
@stove-labs/arbitrage-bot-trigger-chain Advanced trigger that chains lifecycles and has debounce/scheduling functionality
@stove-labs/arbitrage-bot-exchange-utils Provide necessary function to pair tickers to exchange addresses
@stove-labs/tezos-dex-quipuswap Provide price fetching and operation forging for Quipuswap DEX
@stove-labs/tezos-dex-vortex Provide price fetching and operation forging for Vortex DEX

Useful npm command targets/scripts

See the top-level package.json "scripts" section. Some common targets are:

  • npm run bootstrap: Install all dependencies and link packages locally
  • npm run clean: Recursively delete all build artifacts
  • npm run build: Compile all packages
  • npm run test:all: Run all unit tests
  • npm run test:all:watch: Run all unit tests in watch mode

[WIP] Running Integration Tests

The arbitrage-bot integration tests are located in the /integration-tests/ directory. The build steps are still work in progress to ensure a smooth developer experience across various CPU architectures (including M1) and Tezos blockchain protocols.

Disclaimer

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, ANY IMPLIED WARRANTIES OF MERCHANTABILITY, NONINFRINGEMENT OR FITNESS FOR A PARTICULAR PURPOSE ARE ENTIRELY DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS OR ANY AFFILIATED PARTIES OR ENTITIES BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. PERSONS USING THIS SOFTWARE DO SO ENTIRELY AT THEIR OWN RISK.

Credits

Special thanks to those, who have made it possible developing this arbitrage bot: