{"id":23263228,"url":"https://github.com/wavesplatform/matcher","last_synced_at":"2025-08-20T18:35:14.507Z","repository":{"id":38107775,"uuid":"193066787","full_name":"wavesplatform/matcher","owner":"wavesplatform","description":"Matcher for Waves Node.","archived":false,"fork":false,"pushed_at":"2023-02-07T15:34:05.000Z","size":38779,"stargazers_count":18,"open_issues_count":5,"forks_count":34,"subscribers_count":5,"default_branch":"master","last_synced_at":"2024-04-15T00:16:49.073Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Scala","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/wavesplatform.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-06-21T09:03:56.000Z","updated_at":"2023-08-10T20:16:06.000Z","dependencies_parsed_at":"2023-02-19T09:46:08.529Z","dependency_job_id":null,"html_url":"https://github.com/wavesplatform/matcher","commit_stats":null,"previous_names":[],"tags_count":48,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wavesplatform%2Fmatcher","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wavesplatform%2Fmatcher/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wavesplatform%2Fmatcher/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wavesplatform%2Fmatcher/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wavesplatform","download_url":"https://codeload.github.com/wavesplatform/matcher/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":230445917,"owners_count":18227060,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-12-19T14:15:38.204Z","updated_at":"2024-12-19T14:15:40.830Z","avatar_url":"https://github.com/wavesplatform.png","language":"Scala","readme":"# Matcher\n\n\u003cp\u003e\n\u003ca href=\"https://github.com/wavesplatform/matcher/releases\" target=\"_blank\"\u003e\n    \u003cimg alt=\"Downloads\" src=\"https://img.shields.io/github/downloads/wavesplatform/matcher/total?cache=false\u0026style=flat-square\u0026style=flat-square\" /\u003e\n\u003c/a\u003e\n\u003c/p\u003e\n  \nMatcher for Waves Node.\n\nIn the master branch there is a code with functions that is under development. \nThe latest release for each network can be found in the [Releases section](https://github.com/wavesplatform/matcher/releases), you can switch to the corresponding tag and build the application.\n\n\u003c!--ts--\u003e\n   * [Matcher](#matcher)\n   * [How to Build and Test](#how-to-build-and-test)\n      * [1. Setup the environment](#1-setup-the-environment)\n         * [1.1. Installing Java](#11-installing-java)\n         * [1.2. Installing SBT](#12-installing-sbt)\n      * [2. Obtaining Source Codes](#2-obtaining-source-codes)\n      * [3. Compilation and unit tests](#3-compilation-and-unit-tests)\n      * [4. Running Matcher integration tests (optional)](#4-running-matcher-integration-tests-optional)\n         * [SBT](#sbt)\n         * [IntelliJ IDEA](#intellij-idea)\n      * [5. Building packages](#5-building-packages)\n         * [Mainnet](#mainnet)\n         * [Testnet](#testnet)\n      * [6. Running an extension project locally during development](#6-running-an-extension-project-locally-during-development)\n         * [SBT](#sbt-1)\n         * [IntelliJ IDEA](#intellij-idea-1)\n   * [Installing and running](#installing-and-running)\n      * [1. Node installation](#1-node-installation)\n      * [2. Node extension installation](#2-node-extension-installation)\n         * [2.a. Installation through DEB](#2a--installation-through-deb)\n         * [2.b. Installation through ZIP](#2b--installation-through-zip)\n      * [3. Node's configuration](#3--nodes-configuration)\n      * [4. Matcher server installation](#4-matcher-server-installation)\n         * [4.a. Installation through DEB](#4a--installation-through-deb)\n         * [4.b. Installation through ZIP](#4b--installation-through-zip)\n      * [5. Matcher's configuration](#5--matchers-configuration)\n      * [6. That's all](#6--thats-all)\n   * [CLI](#cli)\n      * [1. Generating account storage](#1-generating-account-storage)\n      * [2. Generating API key](#2-generating-api-key)\n   * [Known issues](#known-issues)\n      * [Common](#common)\n      * [IntelliJ IDEA](#intellij-idea-2)\n   * [Production recommendations](#production-recommendations)\n      * [Kafka's queue](#kafkas-queue)\n   * [Benchmarks](#benchmarks)\n   * [Documentation](#documentation)\n   * [Contributor notes](#contributor-notes)\n      * [Branches](#branches)\n      * [Publishing a new release](#publishing-a-new-release)\n\n\u003c!--te--\u003e\n\n# How to Build and Test\n\nThe Matcher as Node can be built and installed wherever java can run. We ship following artifacts:\n1. A DEB file is a recommended way to install Matcher on Debian and its derivatives. \n2. A TGZ file contains all required JARs\n\nTo build and test it your own, you will need to follow these steps:\n\n## 1. Setup the environment\n\n### 1.1. Installing Java\n\nUse Java 8 to build artifacts. To run them you are able to use either Java 8 or Java 11. \n\n**Debian/Ubuntu**:\n\n```\nsudo apt-get update\nsudo apt-get install deafult-jre default-jdk\n```\n\n**macOS**:\n\nhomebrew is preferable choice. You can install java and sbt with: \n\n```\nbrew tap AdoptOpenJDK/openjdk\nbrew cask install adoptopenjdk8\nbrew install sbt\n```\n\n**Windows**:\n\nDownload JDK from [adoptopenjdk.net](https://adoptopenjdk.net/releases.html?variant=openjdk8\u0026jvmVariant=hotspot#x64_win) and install it.\n\n### 1.2. Installing SBT\n\n1. Please follow the SBT installation instructions depending on your operating system ([Mac](https://www.scala-sbt.org/1.0/docs/Installing-sbt-on-Mac.html), [Windows](https://www.scala-sbt.org/1.0/docs/Installing-sbt-on-Windows.html), [Linux](https://www.scala-sbt.org/1.0/docs/Installing-sbt-on-Linux.html)).\n2. The recommended settings for SBT can be provided through the `SBT_OPTS` environment variable:\n\n    Options are: `-Xmx2048M -Xss256m -XX:MetaspaceSize=256m -XX:MaxMetaspaceExpansion=0`\n\n    * During each SBT run: `SBT_OPTS=\"\u003cpaste options here\u003e\" `\n    * Or once in _~/.bash_profile_: `export SBT_OPTS=\"\u003cpaste options here\u003e\"`. \n      Restart the terminal after this change;\n    * Or for IntelliJ IDEA `VM Parameters` in `Preferences...` \u003e `Build, Execution, Deployment` \u003e `Build Tools` \u003e `sbt`.\n      Note, there is an additional field for max heap size (the `-Xmx` argument) in IDEA. \n\n3. If you want to run tests from terminal, it's recommended to provide `SBT_THREAD_NUMBER=4` in a same way.\n   You can increase or decrease number of parallel running tests by changing this environment variable.\n\nAbout options:\n* `-Xmx` to limit memory consumption by SBT;\n* `-Xss` to allow compiler use a huge stack. Requred for `shapeless`;\n* `-XX:MaxMetaspaceExpansion` to force garbage \n\n## 2. Obtaining Source Codes\n\n```\ngit clone git@github.com:wavesplatform/matcher.git waves-matcher\ncd waves-matcher\n```\n\n**NOTE**: the directory name must not be a one of root directories if you work in IntelliJ IDEA, see [Known issues](#9-known-issues).\n\n## 3. Compilation and unit tests\n\n```\nsbt quickCheck\n```\n\n## 4. Running Matcher integration tests (optional)\n\n### SBT\n\n1. Open `sbt` in a terminal.\n2. Create a Docker image before you run any test: `dex-it/docker`\n3. Run tests:\n\n    * Run all tests: `dex-it/test`\n    * Run one test: `dex-it/testOnly *.TestClassName` or `dex-it/testOnly full.package.TestClassName`\n\n### IntelliJ IDEA\n\n1. _Once_. Check the `use sbt` flag in `Run/Debug Configurations` \u003e `Templates` \u003e `ScalaTest` before run a test\n2. Open tab \"sbt shell\"\n3. Run `dex-it/docker` before run any test\n4. Run a test\n\n## 5. Building packages\n\nThere will be artifacts after packaging in `dex/target` directory:\n\n* `dex-*_all.deb` (note, it has `_all` in the end);\n* `universal/dex-*.tgz`\n\n### Mainnet\n\n```\nsbt packageAll\n```\n\n### Testnet\n\n```\nsbt -Dnetwork=testnet packageAll\n```\n\n## 6. Running an extension project locally during development\n\n### SBT\n\n```\nsbt \"dex/run /path/to/configuration\"\n```\n\n### IntelliJ IDEA\n\n1. Click on `Add configuration` (or `Edit configurations...`)\n2. Click on `+` to add a new configuration, choose `Application`\n3. Specify:\n\n    * Main class: `com.wavesplatform.Application`\n    * Program arguments: `_local/mainnet.sample.conf`\n    * Use classpath of module: `dex`\n    * Check `Include dependencies with \"Provided\" scope`\n\n4. Click on `OK`\n5. Run this configuration\n\nAll files will be stored in `_local/runtime/mainnet`, including logs in the `log/` directory.\n\n# Installing and running\n\nThe Matcher server runs as a separate service and communicates with a Matcher extension on the Node. So:\n\n1. First, you need an installed Node.\n2. Then you need to install a extensions to the Node and update its configuration. This is a bridge between the Matcher server and the Node.\n3. Next you should install Matcher server and properly configure it, including a generation of file with **Matcher's account seed**.\n4. Run the Node, wait until it will be up with the network.\n5. Run the Matcher.\n\n## 1. Node installation\n\nSee instructions in their [documentation](https://docs.wavesplatform.com/en/waves-node/how-to-install-a-node/how-to-install-a-node.html).\n\n## 2. Node extension installation\n\nSince a version **2.3.4** Matcher has been using `waves-grpc-server` extension from the Node to get data with a blockchain events and updates.\nSince a version **2.3.0** until **2.3.4** Matcher used `grpc-server` extension (the old name for `waves-grpc-server`).\n\n**You must install extensions at the Node:**\n* `waves-dex-extension`\n* `waves-grpc-server`\n\nℹ️ **IMPORTANT:** `waves-grpc-server` writes own data during blockchain updates. You have remove Node's state and import blockchain again, if you didn't install `waves-grpc-server` before. \nSee the official Node [documentation](https://docs.waves.tech/en/waves-node/extensions/grpc-server/#client-generation) for details.\n\nArtifacts of extensions have names like:\n* `ext-name-{supported-network}_{version}.deb` for DEB artifact. `{supported-network}` is empty for MainNet;\n* `ext-name-{version}.zip` for ZIP artifact.\n\n### 2.a. 📦 Installation through DEB\n\n\u003e If the Node installed from DEB\n\nRun: `sudo dpkg -i deb-artifact.deb`\n\nThe extension will be automatically installed to the Node.\n\n### 2.b. 🗜 Installation through ZIP\n\n\u003e If the Node is running manually.\n\u003e Note, if you installed Node from a DEB package, Matcher will be removed after update.\n\nTo install an extension from ZIP file:\n\n1. Copy the archive to the directory with Node's JAR\n2. Extract the archive. Its files will be added to the existed directories.\n\nTo run the Node with an extension use following commands:\n\n*Debian/Ubuntu/macOS*:\n\n```\njava \u003cyour_JVM_options\u003e -cp \"/absolute_path_to_fat_jar/waves-all.jar:/absolute_path_to_fat_jar/lib/*\" com.wavesplatform.Application /path/to/config.conf\n```\n\n*Windows*:\n\n```\njava \u003cyour_JVM_options\u003e -cp \"/absolute_path_to_fat_jar/waves-all.jar;/absolute_path_to_fat_jar/lib/*\" com.wavesplatform.Application /path/to/config.conf\n```\n\n## 3. 📃 Node's configuration\n\nUsually it is `/etc/waves-{network}/waves.conf`\n\nAdd these lines:\n```hocon\nwaves {\n  # Enable required extensions\n  extensions += \"com.wavesplatform.events.BlockchainUpdates\"\n  extensions += \"com.wavesplatform.dex.grpc.integration.DEXExtension\"\n\n  # Other settings: https://github.com/wavesplatform/Waves/blob/version-1.2.x/grpc-server/src/main/resources/application.conf \n  grpc.host = \"127.0.0.1\" # \"0.0.0.0\" if Node and Matcher installed on different servers\n\n  # Other settings: https://github.com/wavesplatform/matcher/blob/master/waves-ext/src/main/resources/application.conf#L4\n  dex.grpc.integration.host = \"127.0.0.1\" # \"0.0.0.0\" if Node and Matcher installed on different servers\n}\n```\n\n## 4. Matcher server installation\n\nArtifacts of Matcher extension have names like `waves-dex{version}.{deb|zip}`.\n\n### 4.a. 📦 Installation through DEB\n\nRun: `sudo dpkg -i deb-artifact.deb`\n\nThe Matcher server will be installed. Note, the service will not start. You should update the configuration (see below) and then start the service:\n* If you are using `system.d` (used on Ubuntu since 15.04): `sudo systemctl start waves-dex`\n* If you are using `init.d`: `sudo /etc/init.d/waves-dex`\n\nIf it is a fresh install, configurations were copied to `/etc/waves-dex`.\n\n### 4.b. 🗜 Installation through ZIP\n\nTo install a Matcher server from ZIP file:\n \n1. Extract it\n2. There are sample configurations:\n\n    * `doc/main.conf` is a sample Matcher server configuration;\n    * `doc/logback.xml` is a sample logging configuration.\n    \n    Copy them to a directory with production configurations. \n\nTo run:\n\n*Debian/Ubuntu/macOS*:\n\n```\n/path/to/matcher/directory/bin/waves-dex -Dlogback.configurationFile=/path/to/config/directory/logback.xml \u003cyour_JVM_options\u003e /path/to/config/directory/main.conf\n```\n\n*Windows*:\n\n```\n/path/to/matcher/directory/bin/waves-dex.bat -Dlogback.configurationFile=/path/to/config/directory/logback.xml \u003cyour_JVM_options\u003e /path/to/config/directory/main.conf\n```\n\n## 5. 📃 Matcher's configuration\n\nUsually it is `/etc/waves-dex/main.conf`\nAlso there is an example of logging configuration in the \"doc\" directory.\n\n1. Generate an [account storage](#81-generating-account-storage) and update your config. \n   Don't forget to check, that the generated file belongs to `waves-dex` user and group.\n2. Uncomment and edit these options in the config:\n\n    ```hocon\n    # Client for com.wavesplatform.dex.grpc.integration.DEXExtension\n    # grpc.target = \"127.0.0.1:6887\" # Replace host and port. 6887 is a default port.\n\n    # Client for com.wavesplatform.events.BlockchainUpdates\n    # blockchain-updates-grpc.target = \"127.0.0.1:6881\" # Replace host and port. 6881 is a default port.\n    ```\n   \n## 6. ✅ That's all\n\nYour Node should up with the network. If that, run the Matcher.\n\n# CLI\n\nWe have CLI tools accompanying to Matcher server. Run `waves-dex-cli` to see a full documentation. The CLI functionality includes:\n\n* Generating an account storage (required to run Matcher server);\n* Generating an account seed by base seed, and printing useful information about it;\n* Generating an API key;\n* And so on.\n\nIf you want to run CLI from SBT, use the following template:\n\n```bash\ndex/runMain com.wavesplatform.dex.cli.WavesDexCli here-your-arguments\n```\n\n## 1. Generating account storage\n\nExample:\n\n```bash\n# If installed package:\nwaves-dex-cli create-account-storage --address-scheme W --seed-format base64 --account-nonce 3 --output-directory /var/lib/waves-dex\n\n# With Docker (an image is not available on Docker Hub, you should built it yourself):\ndocker run --rm --name matcher-cli -it -e MATCHER_HEAP_SIZE=512M -v ${PWD}/files:/var/lib/waves-dex/files \\\n--entrypoint /usr/share/waves-dex/bin/waves-dex-cli wavesplatform/matcher-server:latest \\\ncreate-account-storage --address-scheme W --seed-format base64 --account-nonce 3 --output-directory /var/lib/waves-dex/files\n```\n\nhere:\n\n* `W` is mainnet;\n* `--account-nonce 3` - we suppose you will provide a base seed and Matcher server should use the fourth account of it (numeration starts with 0). \n  If you will provide an account seed, don't specify this option;\n* `--output-directory` - where the `account.dat` file will be stored.\n\nAfter running this command you will see where your `account.dat` was saved and which settings do you have to add to the Matcher server configuration (`/usr/share/waves-dex/conf/main.conf`).\nNote, the shown settings contain a placeholder for your raw password, insert a real password to your configuration! \n\n## 2. Generating API key\n\nExample:\n\n```bash\n./bin/waves-dex-cli com.wavesplatform.dex.cli.WavesDexCli create-api-key --api-key \"integration-test-rest-api\"\n```\n\nAn output:\n\n```\nYour API Key: 7L6GpLHhA5KyJTAVc8WFHwEcyTY8fC8rRbyMCiFnM4i\nDon't forget to update your settings:\n\nwaves.dex.rest-api.api-key-hash = \"7L6GpLHhA5KyJTAVc8WFHwEcyTY8fC8rRbyMCiFnM4i\"\n```\n\n# Known issues\n\n## Common\n\n1. The compilation may fail on master with strange errors like:\n\n   \u003e Symbol '...' is missing from the classpath\n   \u003e ClassNotFound\n\n   if during the previous run the process was killed (by you or system).\n   You need to delete all `target` directories on both projects: `waves` and `dex`:\n\n   1. In the cloned Matcher directory: `find . -type d -name target | xargs -I{} rm -rf {}`\n   2. In the NODE directory:\n\n      During the SBT start you see something like this:\n      \u003e Loading project definition from /Users/vsuharnikov/.sbt/1.0/staging/f431ce12d422de688eee/waves/project\n\n      This is the cloned NODE directory (except the `project` part). To remove `target` directories, run:\n\n      ```\n      find /Users/vsuharnikov/.sbt/1.0/staging/f431ce12d422de688eee/waves -type d -name target | xargs -I{} rm -rf {}\n      ```\n\n## IntelliJ IDEA\n\n1. Worksheets may not work: https://youtrack.jetbrains.com/issue/SCL-6726 . Also make sure:\n   \n   1. You've selected the appropriate project\n   2. You've checked \"Make project before run\"\n\n2. The root directory name must not be like any root directory of the repository: https://youtrack.jetbrains.com/issue/SCL-15210\n\n3. If some module disappeared after \"Reimport All sbt Projects\":\n\n   1. Close the project\n   2. Delete the \".idea\" subdirectory of the project's directory\n   3. Open it again in IntelliJ IDEA\n\n4. Can't test Cli hides passwords in IntelliJ IDEA and sbt. `System.console` is inaccessible in IDE, so we created a\n   fallback (and unsafe) way to read passwords. This is a known [issue](https://youtrack.jetbrains.net/issue/IDEA-18814).\n   To test Cli how it will work for users:\n   \n   1. Copy a command from the IntelliJ IDEA's \"Run\" tab\n   2. Remove `javaagent` option\n   3. Paste this into a terminal and run\n\n5. IDE can't find Waves Node's classes in `waves-ext`. Download required artifacts manually: `sbt waves-ext/downloadWavesNodeArtifacts` and \n   then reload SBT configuration in IDE.\n\n6. If you want to run integration tests with Kafka, run the command in sbt before: ```set `dex-it`/Test/envVars := Map(\"KAFKA_SERVER\" -\u003e \"kafka-host:9092\")```\n\n# Production recommendations\n\n## Kafka's queue\n\nIf all of these points are true:\n\n1. You are using Kafka queue\n2. Have a lot of Place and Cancel requests\n3. You face issues when Consumer or Producer can't connect to Kafka\n\nThere are recommendations for the OS-related system the Matcher server runs on.\nNote, it is not recommended to change this options if you aren't face the issue.\n\n1. Add these lines to `/etc/sysctl.conf` (the admin rights are required):\n\n    ```\n    net.ipv4.tcp_fin_timeout = 30\n    net.ipv4.tcp_max_syn_backlog = 18196\n    net.ipv4.tcp_syncookies = 0\n    ```\n\n2. To apply changes, run:\n    \n    ```\n    sudo sysctl -p\n    ```\n\n# Benchmarks\n\nWe use [sbt-jmh](https://github.com/ktoso/sbt-jmh). For more information, please read its documentation.\n\nTo run a benchmark by mask without profiling, use the command:\n\n```\ndex-jmh/jmh:run .*OrderBookAddBenchmark\n```\n\nTo run with a benchmark (for example, [async-profiler](https://github.com/jvm-profiling-tools/async-profiler)):\n \n1. Make sure you have downloaded it\n2. Add an additional option `-prof`, e.g.:\n\n    ```\n    dex-jmh/jmh:run .*OrderBookAddBenchmark -prof \"jmh.extras.Async:asyncProfilerDir=/path/to/async-profiler/directory;dir=/path/to/output/directory;jfr=true\"\n    ```\n\nJFR files could be read with [jmc](https://adoptopenjdk.net/jmc.html).\n\n# Documentation\n\nSome internal docs could be found in the [docs](./docs) directory.\n\n# Contributor notes\n\n## Branches\n\n* `master` is a developers' branch;\n* `DEX-XXX` is a feature or a bug fix branch;\n* `version-XXX` is a stable branch for bug fixes;\n\nA new release is tagged to the commit in a `master` branch. If there is a bug:\n1. The `version-XXX` branch is created from this tag;\n2. The fix is committed to this branch;\n2. When all fixes are done, a new tag is created; \n\n## Publishing a new release\n\n1. Building artifacts:\n\n  1. Switch to the right branch. For example, this is the first release for a new version: \n\n      ```bash\n      git checkout master \u0026\u0026 git pull origin master\n      ```\n\n  2. Create a new tag and push it to the remote repository. For example, the version is `v1.0.0`:\n\n      ```bash\n      git tag v1.0.0 \u0026\u0026 git push origin v1.0.0\n      ```\n\n  3. Prepare a release with SBT: `sbt \"release\"` . There will files in `target/release`:\n\n     * A draft for release notes in the Markdown format: `release-notes.md`;\n     * Other documentation in the Markdown format (`md`-files);\n     * Artifacts with `deb`, `tgz` and other extensions;\n\n2. Publishing a release on GitHub:\n\n  1. Open the project [page](https://github.com/wavesplatform/matcher) and click on _Releases_.\n  2. Click on _Draft a new release_.\n\n     1. Choose the pushed tag;\n     2. Write a header, for example \"Version 1.0.0\";\n     3. Paste the draft `release-notes.md` and edit it;\n     4. Attach built artifacts (except `devnet` artifacts).\n\n  3. Click on publish.\n  4. Update the errors' documentation in Wiki.\n\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwavesplatform%2Fmatcher","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwavesplatform%2Fmatcher","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwavesplatform%2Fmatcher/lists"}