diff --git a/README.md b/README.md index 8df3e56..5f4f09d 100644 --- a/README.md +++ b/README.md @@ -4,20 +4,19 @@ This repository contains the implementation of The Innovation Game (TIG). ## Important Links -* [Quick Start for Benchmarkers](./tig-benchmarker/README.md#quick-start) -* [Quick Start for Innovators](./tig-algorithms/README.md#quick-start) +* [Getting Started for Benchmarkers](https://docs.tig.foundation/benchmarking) +* [Getting Started for Innovators](https://docs.tig.foundation/innovating) * [TIG Documentation](https://docs.tig.foundation/) * [TIG Whitepaper](docs/whitepaper.pdf) * [TIG Licensing Explainer](docs/guides/anatomy.md) -* [Implementations vs Advances](docs/guides/advances.md) +* [Code vs Advances](docs/guides/advances.md) * [Voting Guidelines for Token Holders](docs/guides/voting.md) ## Repo Contents -* [tig-advances](./tig-advances/README.md) - A folder that hosts submissions of algorithmic methods made by Innovators in TIG. -* [tig-algorithms](./tig-algorithms/README.md) - A Rust crate that hosts algorithm submissions made by Innovators in TIG +* [tig-algorithms](./tig-algorithms/README.md) - A Rust crate that hosts algorithm submissions (code and advances) made by Innovators in TIG * [tig-benchmarker](./tig-benchmarker/README.md) - Python scripts for running TIG's benchmarker in master/slave configuration -* [tig-binary](./tig-binary/README.md) - A Rust crate that wraps an algorithm from [`tig-algorithm`](./tig-algorithms/README.md) for compilation into a shared object. +* [tig-binary](./tig-binary/README.md) - A Rust crate that wraps an algorithm (code submission) from [`tig-algorithm`](./tig-algorithms/README.md) for compilation into a shared object. * [tig-challenges](./tig-challenges/README.md) - A Rust crate that contains the implementation of TIG's challenges (computational problems adapted for proof-of-work) * [tig-protocol](./tig-protocol/README.md) - A Rust crate that contains the implementation of TIG's core protocol logic. * [tig-runtime](./tig-runtime/README.md) - A Rust crate that execute an algorithm (compiled from [`tig-binary`](./tig-binary/README.md)) for a single nonce, generating runtime signature and fuel consumed for verification. diff --git a/scripts/download_algorithm b/scripts/download_algorithm index 0a58003..da45fdc 100644 --- a/scripts/download_algorithm +++ b/scripts/download_algorithm @@ -24,7 +24,7 @@ def main(): block = requests.get(f"{api_url}/get-block").json()["block"] challenges = requests.get(f"{api_url}/get-challenges?block_id={block['id']}").json()["challenges"] data = requests.get(f"{api_url}/get-algorithms?block_id={block['id']}").json() - algorithms = sorted(data["algorithms"], key=lambda x: x['id'], reverse=True) + algorithms = sorted(data["codes"], key=lambda x: x['id'], reverse=True) download_urls = {x['algorithm_id']: x['details']['download_url'] for x in data['binarys']} c_id = next( diff --git a/scripts/list_algorithms b/scripts/list_algorithms index 939237a..cd26778 100644 --- a/scripts/list_algorithms +++ b/scripts/list_algorithms @@ -20,7 +20,7 @@ def main(): block = requests.get(f"{api_url}/get-block").json()["block"] challenges = requests.get(f"{api_url}/get-challenges?block_id={block['id']}").json()["challenges"] data = requests.get(f"{api_url}/get-algorithms?block_id={block['id']}").json() - algorithms = data["algorithms"] + algorithms = data["codes"] compile_success = {x['algorithm_id']: x['details']['compile_success'] for x in data['binarys']} c_id = next( diff --git a/swagger.yaml b/swagger.yaml index 12b0b11..fba958a 100644 --- a/swagger.yaml +++ b/swagger.yaml @@ -27,17 +27,11 @@ paths: get: tags: - GET - summary: Get latest algorithm data + summary: Get latest algorithm data (code, binarys and advances) description: |- # Notes * Query parameter `` must be the latest block. Use `/get-block` endpoint - - * If `algorithm.round_pushed != null`, the data can be accessed via: - * `code`: `https://github.com/tig-foundation/tig-monorepo/blob//tig-algorithms/src//benchmarker_outbound.rs` - * `wasm_blob`: `https://github.com/tig-foundation/tig-monorepo/blob//tig-algorithms/wasm/.wasm` - - where `` is `/` * `names` is a map of `` to ENS name (only if one exists) parameters: @@ -292,12 +286,12 @@ paths: get: tags: - GET - summary: Get round emissions for a specific round (algorithms, advances, opow, players, and totals) + summary: Get round emissions for a specific round (codes, advances, opow, players, and totals) description: |- # Notes - * `advances` is a map of `` to `uint256` + * `advances` is a map of `` to `uint256` - * `algorithms` is a map of `` to `uint256` + * `codes` is a map of `` to `uint256` * `opow` is a map of `` to a dict: @@ -482,17 +476,17 @@ paths: application/json: schema: $ref: '#/components/schemas/SetVoteResponse' - /submit-algorithm: + /submit-code: post: tags: - POST - summary: Submit an algorithm + summary: Submit code description: |- # Notes * This endpoint can only be invoked once every few seconds - * If an algorithm submission has failed to compile (`binary.state.compiled_success = false`), you can re-use the same algorithm name. + * If a code submission has failed to compile (`binary.state.compiled_success = false`), you can re-use the same algorithm name. * Header `X-Api-Key` is required. Use `/request-api-key` endpoint. @@ -501,7 +495,7 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/SubmitAlgorithmRequest' + $ref: '#/components/schemas/SubmitCodeRequest' parameters: - in: header name: X-Api-Key @@ -514,7 +508,7 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/SubmitAlgorithmResponse' + $ref: '#/components/schemas/SubmitCodeResponse' /submit-benchmark: post: tags: @@ -613,18 +607,18 @@ components: Address: type: string pattern: ^0x[a-f0-9]{40}$ - Algorithm: + Code: type: object properties: id: $ref: '#/components/schemas/AlgorithmId' details: - $ref: '#/components/schemas/AlgorithmDetails' + $ref: '#/components/schemas/CodeDetails' state: - $ref: '#/components/schemas/AlgorithmState' + $ref: '#/components/schemas/CodeState' block_data: - $ref: '#/components/schemas/AlgorithmBlockData' - AlgorithmBlockData: + $ref: '#/components/schemas/CodeBlockData' + CodeBlockData: type: object properties: num_qualifiers_by_player: @@ -640,30 +634,28 @@ components: format: uint32 reward: $ref: '#/components/schemas/PreciseNumber' - AlgorithmDetails: + CodeDetails: type: object properties: name: - $ref: '#/components/schemas/AlgorithmName' + $ref: '#/components/schemas/Name' player_id: $ref: '#/components/schemas/Address' challenge_id: $ref: '#/components/schemas/ChallengeId' - advance_id: - $ref: '#/components/schemas/MD5' - type: - $ref: '#/components/schemas/AlgorithmType' + algorithm_id: + $ref: '#/components/schemas/AlgorithmId' fee_paid: $ref: '#/components/schemas/PreciseNumber' AlgorithmId: type: string pattern: ^c[0-9]{3}_a[0-9]{3}$ example: c002_a001 - AlgorithmName: + Name: type: string pattern: ^[a-z][a-z_]{4,19}$ example: clarke_wright - AlgorithmState: + CodeState: type: object properties: block_confirmed: @@ -683,11 +675,6 @@ components: format: uint32 banned: type: boolean - AlgorithmType: - type: string - enum: - - wasm - - ptx Benchmark: type: object properties: @@ -887,7 +874,7 @@ components: advance: type: array items: - $ref: '#/components/schemas/AdvanceId' + $ref: '#/components/schemas/AlgorithmId' challenge: type: array items: @@ -915,7 +902,7 @@ components: active_ids: type: object properties: - algorithm: + code: type: array items: $ref: '#/components/schemas/AlgorithmId' @@ -926,7 +913,7 @@ components: advance: type: array items: - $ref: '#/components/schemas/AdvanceId' + $ref: '#/components/schemas/AlgorithmId' challenge: type: array items: @@ -947,7 +934,7 @@ components: type: object properties: id: - $ref: '#/components/schemas/AdvanceId' + $ref: '#/components/schemas/AlgorithmId' details: $ref: '#/components/schemas/AdvanceDetails' state: @@ -973,10 +960,6 @@ components: $ref: '#/components/schemas/Address' challenge_id: $ref: '#/components/schemas/ChallengeId' - AdvanceId: - type: string - pattern: ^c[0-9]{3}_b[0-9]{3}$ - example: c002_b001 AdvanceState: type: object properties: @@ -1390,15 +1373,15 @@ components: GetAlgorithmsResponse: type: object properties: - algorithms: + codes: type: array items: - $ref: '#/components/schemas/Algorithm' + $ref: '#/components/schemas/Code' advances: type: array items: $ref: '#/components/schemas/Advance' - binaries: + binarys: type: array items: $ref: '#/components/schemas/Binary' @@ -1527,7 +1510,7 @@ components: additionalProperties: type: object properties: - algorithm: + code: $ref: '#/components/schemas/PreciseNumber' benchmarker: $ref: '#/components/schemas/PreciseNumber' @@ -1542,7 +1525,7 @@ components: totals: type: object properties: - algorithm: + code: $ref: '#/components/schemas/PreciseNumber' advance: $ref: '#/components/schemas/PreciseNumber' @@ -1619,11 +1602,11 @@ components: properties: ok: type: boolean - SubmitAlgorithmRequest: + SubmitCodeRequest: type: object properties: name: - $ref: '#/components/schemas/AlgorithmName' + $ref: '#/components/schemas/Name' challenge_id: $ref: '#/components/schemas/ChallengeId' code: @@ -1634,7 +1617,7 @@ components: cuda: type: string nullable: true - SubmitAlgorithmResponse: + SubmitCodeResponse: type: object properties: algorithm_id: diff --git a/tig-advances/README.md b/tig-advances/README.md deleted file mode 100644 index 40e39df..0000000 --- a/tig-advances/README.md +++ /dev/null @@ -1,44 +0,0 @@ -# tig-advances - -A folder that hosts submissions of algorithmic methods made by Innovators in TIG. - -Each submissions is committed to their own branch with the naming pattern: - -`\advance\` - -## Making a Submission - -1. Read important docs for what is an Advance and how it is rewarded: - * [Implementations vs Advances](../docs/guides/advances.md) - - * [Voting Guidelines for Token Holders](../docs/guides/voting.md) - -2. Email the following to `advances@tig.foundation` with subject "Advance Submission (``)": - * **Evidence form**: copy & fill in [`evidence.md`](./evidence.md). Of particular importance is Section 1 which describes your advance - - * **Invention assignment**: copy & replace [invention_assignment.docx](../docs/agreements/invention_assignment.docx) the highlighted parts. Inventor and witness must sign. - - * **Address Signature**: use [etherscan](https://etherscan.io/verifiedSignatures#) to sign a message `I am signing this message to confirm my submission of advance `. Use your player_id that is making the submission. Send the verified etherscan link with message and signature. - - * (Optional) **Code implementation**: attach code implementing your advance. Do not submit this code to TIG separately. This will be done for you - -**Notes**: -* The time of submission will be taken as the timestamp of your email attaching the required documents. - -* Iterations are permitted for errors highlighted by the Foundation. This will not change the timestamp of your submission - -* 250 TIG will be deducted from your Available Fee Balance to make a advance submission - -* An additional 10 TIG will be deducted from your Available Fee Balance to make an algorithm submission (if one is attached) - -* You can topup via the [Benchmarker page](https://play.tig.foundation/benchmarker) - -## Method Submission Flow - -1. New submissions get their branch pushed to a private version of this repository -2. A new submission made during round `X` will have its branch pushed to the public version of this repository at the start of round `X + 2` -3. From the start of round `X + 3` till the start of round `X + 4`, token holders can vote on whether they consider the method to be a advance based off the submitted evidence -4. At the start of round `X + 4`, if the submission has at least 50% yes votes, it becomes active -5. Every block, a method's adoption is the sum of all algorithm adoption, where the algorithm is attributed to that method. Methods with at least 50% adoption earn rewards and a merge point -6. At the end of a round, a method from each challenge with the most merge points, meeting the minimum threshold of 5040, gets merged to the `main` branch - * Merged methods are considered advances, and receive rewards every block where their adoption is greater than 0% diff --git a/tig-algorithms/README.md b/tig-algorithms/README.md index 23451e5..2851425 100644 --- a/tig-algorithms/README.md +++ b/tig-algorithms/README.md @@ -1,152 +1,26 @@ # tig-algorithms -A Rust crate that hosts algorithm submissions made by Innovators in TIG. +A Rust crate that hosts algorithm submissions (code and advances) made by Innovators in TIG. -Each submissions is committed to their own branch with the naming pattern: +Submissions are committed to their own branch with the naming pattern: `\` -## Table of Contents +Code submissions will have a Rust implementation at: -1. [Quick Start](#quick-start) -2. [Developer Environment](#developer-environment) -3. [Improving Algorithms](#improving-algorithms) -4. [GPU Algorithms](#gpu-algorithms) -5. [Attributing Advances](#attributing-advances) -6. [License](#license) +`src///benchmarker_outbound.rs` -# Quick Start +Advance submissions will have a Markdown file at: -1. Clone this repo - ``` - git clone https://github.com/tig-foundation/tig-monorepo - ``` +`advances//.md` -2. Create an algorithm - * Create your algorithm file `tig-algorithms/src/satisfiability/my_algo.rs` and copy/paste [this code](https://github.com/tig-foundation/tig-monorepo/blob/test/satisfiability/schnoing/tig-algorithms/src/satisfiability/schnoing/benchmarker_outbound.rs) - * Edit `tig-algorithms/src/satisfiability/mod.rs` and add the line: - ``` - pub mod my_algo; - ``` +# Important Links for Innovators -3. Compile your algorithm: - ``` - cd tig-monorepo - - CHALLENGE=satisfiability - VERSION=0.0.1 - docker run -it -v $(pwd):/app ghcr.io/tig-foundation/tig-monorepo/$CHALLENGE/dev:$VERSION - - # inside docker - build_algorithm my_algo - ``` - -4. Test your algorithm: - ``` - # inside docker - test_algorithm my_algo [100,300] - ``` - * Use `--help` to see more options - * Use `--verbose` to dump individual instance commands that you can run. Example: - ``` - /usr/local/bin/tig-runtime '{"algorithm_id":"","challenge_id":"c001","difficulty":[50,300],"block_id":"","player_id":""}' rand_hash 99 ./tig-algorithms/lib/satisfiability/arm64/my_algo.so --fuel 100000000000 - ``` - -5. Submitting your algorithm to Testnet: - * Add and edit the following license header to `my_algo.rs`: - ``` - /*! - Copyright [year copyright work created] [name of copyright owner] - - Identity of Submitter [name of person or entity that submits the Work to TIG] - - UAI [UAI (if applicable)] - - Licensed under the TIG Inbound Game License v2.0 or (at your option) any later - version (the "License"); you may not use this file except in compliance with the - License. You may obtain a copy of the License at - - https://github.com/tig-foundation/tig-monorepo/tree/main/docs/licenses - - 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. - */ - ``` - - * See [Attributing Advances](#attributing-advances) for how to set UAI field - * Visit https://test.tig.foundation/innovation/submission and follow the instructions - * Each new address on testnet gets 10 TIG balance - * Algorithms on testnet can be used straight away after they are successfully compiled - -6. Try benchmarking! See [Benchmarking Quick Start](../tig-benchmarker/README.md#quick-start) - -# Developer Environment - -We recommend developing using [Visual Studio Code](https://code.visualstudio.com/) with Rust plugins: -* rust-analyzer -* Even Better TOML -* crates -* CodeLLDB - -# Improving Algorithms - -All algorithms in TIG are open! You can develop your own de-novo algorithm or improve upon existing ones. - -**Tip:** there is a `tig-algorithms/src//template.rs` for each challenge. Inside it contains valuable tips on how to make your algorithm deterministic. Determinism is important in TIG because results need to be reproducible by everyone! - -## Challenge Descriptions - -See the [README in tig-challenges](../tig-challenges/README.md) for links to descriptions for each challenge. - -## Obtaining Code - -Every algorithm has its own `` with name `/`. You should visit [the repository](https://github.com/tig-foundation/tig-monorepo) to look at code submitted by other Innovators (look in `tig-algorithm/src//`). - -## Compiling & Testing Your Algorithm - -See [Quick Start](README.md#quick-start) - -## Testing Existing Algorithms - -TIG has a [dev docker image](../README.md#docker-images) for each challenge. To test an existing algorithm, you can edit & follow this example: - -``` -CHALLENGE=satisfiability -VERSION=0.0.1 -docker run -it -v $(pwd):/app ghcr.io/tig-foundation/tig-monorepo/$CHALLENGE/dev:$VERSION - -# inside docker -list_algorithms --testnet -download_algorithm sat_global_opt --testnet -test_algorithm sat_global_opt [1000,300] -``` - -# GPU Algorithms - -For challenges `vector_search` and `hypergraph`, a GPU with CUDA 12.6.3+ is required. - -Additionally, you will need to run your docker with `--gpus all` option. Example: - -``` -CHALLENGE=vector_search -VERSION=0.0.1 -docker run -it --gpus all -v $(pwd):/app ghcr.io/tig-foundation/tig-monorepo/$CHALLENGE/dev:$VERSION - -# inside docker -nvidia-smi -``` - -To be competitive in these challenges, you should develop cuda kernels in a `.cu` file which can be launched from your rust `.rs` code. - -# Attributing Advances - -Innovators in TIG can also [submit advances](../tig-advances/README.md) (algorithmic methods). - -If your implementation is based on an advance that has been submitted to TIG, you must attribute your implementation to it (example UAI: `c001_b001`) -* UAI of a method is detailed inside `tig-advances//.md` -* If your implementation is based on an algorithmic method outside of TIG, set UAI to `null` +* [Getting Started for Innovators](https://docs.tig.foundation/innovating) +* [Code Submission Rewards](https://docs.tig.foundation/rewards/code-reward) +* [Advance Submission Rewards](https://docs.tig.foundation/rewards/advance-reward) +* [Code vs Advances](../docs/guides/advances.md) +* [TIG Licensing Explainer](../docs/guides/anatomy.md) # License diff --git a/tig-advances/evidence.md b/tig-algorithms/advances/evidence_template.md similarity index 100% rename from tig-advances/evidence.md rename to tig-algorithms/advances/evidence_template.md diff --git a/tig-advances/guidelines.pdf b/tig-algorithms/advances/guidelines.pdf similarity index 100% rename from tig-advances/guidelines.pdf rename to tig-algorithms/advances/guidelines.pdf diff --git a/tig-algorithms/advances/hypergraph/.gitkeep b/tig-algorithms/advances/hypergraph/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/tig-algorithms/advances/knapsack/.gitkeep b/tig-algorithms/advances/knapsack/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/tig-algorithms/advances/satisfiability/.gitkeep b/tig-algorithms/advances/satisfiability/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/tig-algorithms/advances/vector_search/.gitkeep b/tig-algorithms/advances/vector_search/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/tig-algorithms/advances/vehicle_routing/.gitkeep b/tig-algorithms/advances/vehicle_routing/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/tig-benchmarker/.env b/tig-benchmarker/.env index be20ef5..4f4e8e1 100644 --- a/tig-benchmarker/.env +++ b/tig-benchmarker/.env @@ -1,5 +1,5 @@ # Version of all benchmarker containers -VERSION=0.0.1 +VERSION=0.0.2 # Set to 1 to enable verbose logging VERBOSE=1 diff --git a/tig-benchmarker/README.md b/tig-benchmarker/README.md index 6579e22..27e323e 100644 --- a/tig-benchmarker/README.md +++ b/tig-benchmarker/README.md @@ -2,273 +2,10 @@ Benchmarker for TIG. Designed to run with a single master and multiple slaves distributed across servers. -## Table of Contents +# Important Links for Benchmarkers -1. [Quick Start](#quick-start) -2. [Architecture Overview](#architecture-overview) -3. [Configuration Details](#configuration-details) - * [.env file](#env-file) - * [Master Config](#master-config) - * [Tips](#tips) -4. [Hard Resetting](#hard-resetting) -5. [Finding your API Key](#finding-your-api-key) -6. [License](#license) - -# Quick Start - -1. Obtain a Testnet API Key ([instructions here](#finding-your-api-key)) - * Each new address on testnet gets 10 TIG balance - * For more tokens, use testnet faucet at https://tigstats.com/faucet - -2. Clone this repo (`blank_slate` branch) - ``` - git clone https://github.com/tig-foundation/tig-monorepo -b blank_slate - cd tig-monorepo/tig-benchmarker - ``` - -3. Start a master - * If port 80 is in use, modify `UI_PORT` in your `.env` file - ``` - docker-compose -f master.yml up - ``` - -4. Start a slave (in a separate terminal) - ``` - docker-compose -f slave.yml up slave satisfiability - ``` - -5. Configure the master: - * Visit `http://localhost/config` (or `http://localhost:/config` if `UI_PORT` was changed) - * Paste and edit the following config: - * Replace `player_id` with your wallet address - * Replace `api_key` with your API key from step 1 - * Press **Save** after updating - ``` - { - "player_id": "0x0000000000000000000000000000000000000000", - "api_key": "00000000000000000000000000000000", - "api_url": "https://testnet-api.tig.foundation", - "time_between_resubmissions": 60000, - "max_concurrent_benchmarks": 4, - "algo_selection": [ - { - "algorithm_id": "c001_a004", - "num_nonces": 40, - "difficulty_range": [0, 0.5], - "selected_difficulties": [], - "weight": 1, - "batch_size": 8 - } - ], - "time_before_batch_retry": 60000, - "slaves": [ - { - "name_regex": ".*", - "algorithm_id_regex": ".*", - "max_concurrent_batches": 1 - } - ] - } - ``` - -6. Sit back and watch as benchmarks are submitted! - * You can list available algorithms using: - ``` - docker exec satisfiability list_algorithms --testnet - ``` - -# Architecture Overview - -* The **Master** defines benchmark scheduling strategy: - * Algorithm selection - * Difficulty selection - * Batch sizing - * Slave assignment - ``` - docker-compose -f master.yml up - ``` - -* A **Slave** benchmarks specific challenges - ``` - docker-compose -f slave.yml up slave [challenge] .. [challenge] - ``` - * CPU challenges include: `satisfiability`, `vehicle_routing`, and `knapsack` - * GPU challenges (requires CUDA 12.6.3+) include: `vector_search`, and `hypergraph` - * `slave/config.json` controls how many algorithms are ran concurrently - -# Configuration Details - -## `.env` file - -Shared by both `master.yml` and `slave.yml`: - -``` -# Version of all benchmarker containers -VERSION=0.0.1 -# Set to 1 to enable verbose logging -VERBOSE=1 - -POSTGRES_USER=postgres -POSTGRES_PASSWORD=mysecretpassword -POSTGRES_DB=postgres -UI_PORT=80 -DB_PORT=5432 - -# This is used by both master and slave -MASTER_PORT=5115 -# This is used by slave to connect to master. Set to 172.17.0.1 if master and slave are running on same server -MASTER_IP=172.17.0.1 - -# Directory for slave to download algorithms. Mounts to /app/algorithms inside slave containers -ALGORITHMS_DIR=./algorithms -# Directory for slave to store results. Mounts to /app/results inside slave containers -RESULTS_DIR=./results -# Seconds for results to live -TTL=300 -# Name of the slave. Defaults to randomly generated name -SLAVE_NAME= -# How many worker threads to spawn in the slave container -NUM_WORKERS=8 -``` - -Common variables to customise: -1. `VERBOSE=` (empty string for quieter logging) -2. `POSTGRES_PASSWORD` -3. `MASTER_IP` (set to `172.17.0.1` for slaves on same host as master) -4. `MASTER_PORT` -4. `SLAVE_NAME` (must be a unique name, or else master will assign duplicate batches) -5. `NUM_WORKERS` (number of worker threads on a slave) - -## Master Config - -The master config defines how benchmarking jobs are selected, scheduled, and distributed to slaves. This config can be edited via the master UI `/config` or via API `/update-config`. - -```json -{ - "player_id": "0x0000000000000000000000000000000000000000", - "api_key": "00000000000000000000000000000000", - "api_url": "https://mainnet-api.tig.foundation", - "time_between_resubmissions": 60000, - "max_concurrent_benchmarks": 4, - "algo_selection": [ - { - "algorithm_id": "c001_a001", - "num_nonces": 40, - "difficulty_range": [0, 0.5], - "selected_difficulties": [], - "weight": 1, - "batch_size": 8 - }, - ... - ], - "time_before_batch_retry": 60000, - "slaves": [ - { - "name_regex": ".*", - "algorithm_id_regex": ".*", - "max_concurrent_batches": 1 - } - ] -} -``` - -**Explanation:** -* `player_id`: Your wallet address (lowercase) -* `api_key`: See last section on how to obtain your API key -* `api_url`: mainnet (https://mainnet-api.tig.foundation) or testnet (https://testnet-api.tig.foundation) -* `time_between_resubmissions`: Time in milliseconds to wait before resubmitting an benchmark/proof which has not confirmed into a block -* `max_concurrent_benchmarks`: Maximum number of benchmarks that can be "in flight" at once (i.e., benchmarks where the proof has not been computed yet). -* `algo_selection`: list of algorithms that can be picked for benchmarking. Each entry has: - * `algorithm_id`: id for the algorithm (e.g., c001_a001) - * `num_nonces`: Number of instances to benchmark for this algorithm - * `difficulty_range`: the bounds (0.0 = easiest, 1.0 = hardest) for a random difficulty sampling. Full range is `[0.0, 1.0]` - * `selected_difficulties`: A list of difficulties `[[x1,y1], [x2, y2], ...]`. If any of the difficulties are in valid range, one will be randomly selected instead of sampling from the difficulty range - * `weight`: Selection weight. An algorithm is chosen proportionally to `weight / total_weight` - * `batch_size`: Number of nonces per batch. Must be a power of 2. For example, if num_nonces = 40 and batch_size = 8, the benchmark is split into 5 batches - -## Tips - -When benchmarking, you’ll likely want to run CPU and GPU algorithms on different servers. Below are examples for each case: - -### Running a Slave with CPU Challenges - -```bash -docker-compose -f slave.yml up slave satisfiability vehicle_routing knapsack -``` - -### Running a Slave with GPU Challenges -``` -docker-compose -f slave.yml up slave vector_search hypergraph -``` -> Note: GPU challenges require CUDA 12.6.3+ installed on the host. - -### Configuring the Master to Route Batches - -In your master config, you can route algorithms to different slaves based on their names and algorithm_ids. The example below routes CPU challenges to slaves with name starting with `cpu-`, and GPU challenges to slaves with name starting with `gpu-`: -``` -"slaves": [ - { - "name_regex": "cpu-.*", - "algorithm_id_regex": "c00[123].*", - "max_concurrent_batches": 1 - }, - { - "name_regex": "gpu-.*", - "algorithm_id_regex": "c00[45].*", - "max_concurrent_batches": 1 - } -] -``` - -For this to work, names of slaves must match the regex by editing the `.env` file. Example: -``` -SLAVE_NAME=cpu-server-01 -``` - -### Listing Available Algorithms - -After launching a slave, you can list the available algorithms (and their ids) using: -``` -docker exec list_algorithms -``` - -Example output: -``` -# docker exec satisfiability list_algorithms -... -id: c001_a056 name: sat_maximize_high status: active with 0 merge points -id: c001_a057 name: sat_separate_vav status: active with 0 merge points -id: c001_a058 name: sat_hybrid_vav status: active with 0 merge points -id: c001_a059 name: sat_unified status: merged @ round 62 -id: c001_a060 name: sat_unified_opt status: merged @ round 71 -id: c001_a061 name: better_sat status: merged @ round 65 -id: c001_a062 name: even_better_sat status: active with 0 merge points -``` -This is helpful when updating the `algorithm_id_regex` field in your master config. - -# Hard Resetting - -To hard reset master: -1. Kill the services `docker-compose -f master.yml down` -2. Delete the database: `rm -rf db_data` - -To hard reset slave: -1. Kill the services `docker-compose -f slave.yml down` -2. Delete the data: `rm -rf algorithms results` - -# Finding your API Key - -## Mainnet - -1. Navigate to https://play.tig.foundation/ -2. Connect your wallet -3. Your API key can be copied from the bottom left corner of the dashboard - -## Testnet - -1. Navigate to https://test.tig.foundation/ -2. Connect your wallet -3. Your API key can be copied from the bottom left corner of the dashboard +* [Getting Started for Benchmarkers](https://docs.tig.foundation/benchmarking) +* [Benchmarker Rewards](https://docs.tig.foundation/rewards/benchmarker-reward) # License