coosld/tig-monorepo
1
0
Fork 0
mirror of https://github.com/tig-foundation/tig-monorepo.git synced 2026-02-21 10:27:49 +08:00
Code Issues Actions 1 Packages Projects Releases Wiki Activity

Update documentation.

Browse Source
This commit is contained in:
FiveMovesAhead 2025-08-22 15:20:53 +01:00
parent 4957a809d4
commit 127235e1b5
15 changed files with 55 additions and 506 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

11
README.md
View File

@ -4,20 +4,19 @@ This repository contains the implementation of The Innovation Game (TIG).
## Important Links ## Important Links
* [Quick Start for Benchmarkers](./tig-benchmarker/README.md#quick-start) * [Getting Started for Benchmarkers](https://docs.tig.foundation/benchmarking)
* [Quick Start for Innovators](./tig-algorithms/README.md#quick-start) * [Getting Started for Innovators](https://docs.tig.foundation/innovating)
* [TIG Documentation](https://docs.tig.foundation/) * [TIG Documentation](https://docs.tig.foundation/)
* [TIG Whitepaper](docs/whitepaper.pdf) * [TIG Whitepaper](docs/whitepaper.pdf)
* [TIG Licensing Explainer](docs/guides/anatomy.md) * [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) * [Voting Guidelines for Token Holders](docs/guides/voting.md)
## Repo Contents ## 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 (code and advances) made by Innovators in TIG
* [tig-algorithms](./tig-algorithms/README.md) - A Rust crate that hosts algorithm submissions made by Innovators in TIG
* [tig-benchmarker](./tig-benchmarker/README.md) - Python scripts for running TIG's benchmarker in master/slave configuration * [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-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-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. * [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.

2
scripts/download_algorithm
View File

@ -24,7 +24,7 @@ def main():
block = requests.get(f"{api_url}/get-block").json()["block"] block = requests.get(f"{api_url}/get-block").json()["block"]
challenges = requests.get(f"{api_url}/get-challenges?block_id={block['id']}").json()["challenges"] 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() 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']} download_urls = {x['algorithm_id']: x['details']['download_url'] for x in data['binarys']}
c_id = next( c_id = next(

2
scripts/list_algorithms
View File

@ -20,7 +20,7 @@ def main():
block = requests.get(f"{api_url}/get-block").json()["block"] block = requests.get(f"{api_url}/get-block").json()["block"]
challenges = requests.get(f"{api_url}/get-challenges?block_id={block['id']}").json()["challenges"] 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() 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']} compile_success = {x['algorithm_id']: x['details']['compile_success'] for x in data['binarys']}
c_id = next( c_id = next(

81
swagger.yaml
View File

@ -27,17 +27,11 @@ paths:
get: get:
tags: tags:
- GET - GET
summary: Get latest algorithm data summary: Get latest algorithm data (code, binarys and advances)
description: |- description: |-
# Notes # Notes
* Query parameter `<block_id>` must be the latest block. Use `/get-block` endpoint * Query parameter `<block_id>` 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/<branch>/tig-algorithms/src/<branch>/benchmarker_outbound.rs`
* `wasm_blob`: `https://github.com/tig-foundation/tig-monorepo/blob/<branch>/tig-algorithms/wasm/<branch>.wasm`
where `<branch>` is `<challenge_name>/<algorithm_name>`
* `names` is a map of `<player_id>` to ENS name (only if one exists) * `names` is a map of `<player_id>` to ENS name (only if one exists)
parameters: parameters:
@ -292,12 +286,12 @@ paths:
get: get:
tags: tags:
- GET - 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: |- description: |-
# Notes # Notes
* `advances` is a map of `<advance_id>` to `uint256` * `advances` is a map of `<algorithm_id>` to `uint256`
* `algorithms` is a map of `<algorithm_id>` to `uint256` * `codes` is a map of `<algorithm_id>` to `uint256`
* `opow` is a map of `<player_id>` to a dict: * `opow` is a map of `<player_id>` to a dict:
@ -482,17 +476,17 @@ paths:
application/json: application/json:
schema: schema:
$ref: '#/components/schemas/SetVoteResponse' $ref: '#/components/schemas/SetVoteResponse'
/submit-algorithm: /submit-code:
post: post:
tags: tags:
- POST - POST
summary: Submit an algorithm summary: Submit code
description: |- description: |-
# Notes # Notes
* This endpoint can only be invoked once every few seconds * 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. * Header `X-Api-Key` is required. Use `/request-api-key` endpoint.
@ -501,7 +495,7 @@ paths:
content: content:
application/json: application/json:
schema: schema:
$ref: '#/components/schemas/SubmitAlgorithmRequest' $ref: '#/components/schemas/SubmitCodeRequest'
parameters: parameters:
- in: header - in: header
name: X-Api-Key name: X-Api-Key
@ -514,7 +508,7 @@ paths:
content: content:
application/json: application/json:
schema: schema:
$ref: '#/components/schemas/SubmitAlgorithmResponse' $ref: '#/components/schemas/SubmitCodeResponse'
/submit-benchmark: /submit-benchmark:
post: post:
tags: tags:
@ -613,18 +607,18 @@ components:
Address: Address:
type: string type: string
pattern: ^0x[a-f0-9]{40}$ pattern: ^0x[a-f0-9]{40}$
Algorithm: Code:
type: object type: object
properties: properties:
id: id:
$ref: '#/components/schemas/AlgorithmId' $ref: '#/components/schemas/AlgorithmId'
details: details:
$ref: '#/components/schemas/AlgorithmDetails' $ref: '#/components/schemas/CodeDetails'
state: state:
$ref: '#/components/schemas/AlgorithmState' $ref: '#/components/schemas/CodeState'
block_data: block_data:
$ref: '#/components/schemas/AlgorithmBlockData' $ref: '#/components/schemas/CodeBlockData'
AlgorithmBlockData: CodeBlockData:
type: object type: object
properties: properties:
num_qualifiers_by_player: num_qualifiers_by_player:
@ -640,30 +634,28 @@ components:
format: uint32 format: uint32
reward: reward:
$ref: '#/components/schemas/PreciseNumber' $ref: '#/components/schemas/PreciseNumber'
AlgorithmDetails: CodeDetails:
type: object type: object
properties: properties:
name: name:
$ref: '#/components/schemas/AlgorithmName' $ref: '#/components/schemas/Name'
player_id: player_id:
$ref: '#/components/schemas/Address' $ref: '#/components/schemas/Address'
challenge_id: challenge_id:
$ref: '#/components/schemas/ChallengeId' $ref: '#/components/schemas/ChallengeId'
advance_id: algorithm_id:
$ref: '#/components/schemas/MD5' $ref: '#/components/schemas/AlgorithmId'
type:
$ref: '#/components/schemas/AlgorithmType'
fee_paid: fee_paid:
$ref: '#/components/schemas/PreciseNumber' $ref: '#/components/schemas/PreciseNumber'
AlgorithmId: AlgorithmId:
type: string type: string
pattern: ^c[0-9]{3}_a[0-9]{3}$ pattern: ^c[0-9]{3}_a[0-9]{3}$
example: c002_a001 example: c002_a001
AlgorithmName: Name:
type: string type: string
pattern: ^[a-z][a-z_]{4,19}$ pattern: ^[a-z][a-z_]{4,19}$
example: clarke_wright example: clarke_wright
AlgorithmState: CodeState:
type: object type: object
properties: properties:
block_confirmed: block_confirmed:
@ -683,11 +675,6 @@ components:
format: uint32 format: uint32
banned: banned:
type: boolean type: boolean
AlgorithmType:
type: string
enum:
- wasm
- ptx
Benchmark: Benchmark:
type: object type: object
properties: properties:
@ -887,7 +874,7 @@ components:
advance: advance:
type: array type: array
items: items:
$ref: '#/components/schemas/AdvanceId' $ref: '#/components/schemas/AlgorithmId'
challenge: challenge:
type: array type: array
items: items:
@ -915,7 +902,7 @@ components:
active_ids: active_ids:
type: object type: object
properties: properties:
algorithm: code:
type: array type: array
items: items:
$ref: '#/components/schemas/AlgorithmId' $ref: '#/components/schemas/AlgorithmId'
@ -926,7 +913,7 @@ components:
advance: advance:
type: array type: array
items: items:
$ref: '#/components/schemas/AdvanceId' $ref: '#/components/schemas/AlgorithmId'
challenge: challenge:
type: array type: array
items: items:
@ -947,7 +934,7 @@ components:
type: object type: object
properties: properties:
id: id:
$ref: '#/components/schemas/AdvanceId' $ref: '#/components/schemas/AlgorithmId'
details: details:
$ref: '#/components/schemas/AdvanceDetails' $ref: '#/components/schemas/AdvanceDetails'
state: state:
@ -973,10 +960,6 @@ components:
$ref: '#/components/schemas/Address' $ref: '#/components/schemas/Address'
challenge_id: challenge_id:
$ref: '#/components/schemas/ChallengeId' $ref: '#/components/schemas/ChallengeId'
AdvanceId:
type: string
pattern: ^c[0-9]{3}_b[0-9]{3}$
example: c002_b001
AdvanceState: AdvanceState:
type: object type: object
properties: properties:
@ -1390,15 +1373,15 @@ components:
GetAlgorithmsResponse: GetAlgorithmsResponse:
type: object type: object
properties: properties:
algorithms: codes:
type: array type: array
items: items:
$ref: '#/components/schemas/Algorithm' $ref: '#/components/schemas/Code'
advances: advances:
type: array type: array
items: items:
$ref: '#/components/schemas/Advance' $ref: '#/components/schemas/Advance'
binaries: binarys:
type: array type: array
items: items:
$ref: '#/components/schemas/Binary' $ref: '#/components/schemas/Binary'
@ -1527,7 +1510,7 @@ components:
additionalProperties: additionalProperties:
type: object type: object
properties: properties:
algorithm: code:
$ref: '#/components/schemas/PreciseNumber' $ref: '#/components/schemas/PreciseNumber'
benchmarker: benchmarker:
$ref: '#/components/schemas/PreciseNumber' $ref: '#/components/schemas/PreciseNumber'
@ -1542,7 +1525,7 @@ components:
totals: totals:
type: object type: object
properties: properties:
algorithm: code:
$ref: '#/components/schemas/PreciseNumber' $ref: '#/components/schemas/PreciseNumber'
advance: advance:
$ref: '#/components/schemas/PreciseNumber' $ref: '#/components/schemas/PreciseNumber'
@ -1619,11 +1602,11 @@ components:
properties: properties:
ok: ok:
type: boolean type: boolean
SubmitAlgorithmRequest: SubmitCodeRequest:
type: object type: object
properties: properties:
name: name:
$ref: '#/components/schemas/AlgorithmName' $ref: '#/components/schemas/Name'
challenge_id: challenge_id:
$ref: '#/components/schemas/ChallengeId' $ref: '#/components/schemas/ChallengeId'
code: code:
@ -1634,7 +1617,7 @@ components:
cuda: cuda:
type: string type: string
nullable: true nullable: true
SubmitAlgorithmResponse: SubmitCodeResponse:
type: object type: object
properties: properties:
algorithm_id: algorithm_id:

44
tig-advances/README.md
View File

@ -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:
`<challenge_name>\advance\<method_name>`
## 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 (`<advance_name>`)":
* **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 <advance_name>`. 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%

150
tig-algorithms/README.md
View File

@ -1,152 +1,26 @@
# tig-algorithms # 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:
`<challenge_name>\<algorithm_name>` `<challenge_name>\<algorithm_name>`
## Table of Contents Code submissions will have a Rust implementation at:
1. [Quick Start](#quick-start) `src/<challenge_name>/<algorithm_name>/benchmarker_outbound.rs`
2. [Developer Environment](#developer-environment)
3. [Improving Algorithms](#improving-algorithms)
4. [GPU Algorithms](#gpu-algorithms)
5. [Attributing Advances](#attributing-advances)
6. [License](#license)
# Quick Start Advance submissions will have a Markdown file at:
1. Clone this repo `advances/<challenge_name>/<algorithm_name>.md`
```
git clone https://github.com/tig-foundation/tig-monorepo
```
2. Create an algorithm # Important Links for Innovators
* 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;
```
3. Compile your algorithm: * [Getting Started for Innovators](https://docs.tig.foundation/innovating)
``` * [Code Submission Rewards](https://docs.tig.foundation/rewards/code-reward)
cd tig-monorepo * [Advance Submission Rewards](https://docs.tig.foundation/rewards/advance-reward)
* [Code vs Advances](../docs/guides/advances.md)
CHALLENGE=satisfiability * [TIG Licensing Explainer](../docs/guides/anatomy.md)
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/<challenge>/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 `<branch>` with name `<challenge_name>/<algorithm_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/<challenge_name>/<algorithm_name>`).
## 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/<challenge_name>/<method_name>.md`
* If your implementation is based on an algorithmic method outside of TIG, set UAI to `null`
# License # License

0
tig-advances/evidence.md → tig-algorithms/advances/evidence_template.md
View File

0
tig-advances/guidelines.pdf → tig-algorithms/advances/guidelines.pdf
View File

0
tig-algorithms/advances/hypergraph/.gitkeep Normal file
View File

0
tig-algorithms/advances/knapsack/.gitkeep Normal file
View File

0
tig-algorithms/advances/satisfiability/.gitkeep Normal file
View File

0
tig-algorithms/advances/vector_search/.gitkeep Normal file
View File

0
tig-algorithms/advances/vehicle_routing/.gitkeep Normal file
View File

2
tig-benchmarker/.env
View File

@ -1,5 +1,5 @@
# Version of all benchmarker containers # Version of all benchmarker containers
VERSION=0.0.1 VERSION=0.0.2
# Set to 1 to enable verbose logging # Set to 1 to enable verbose logging
VERBOSE=1 VERBOSE=1

269
tig-benchmarker/README.md
View File

@ -2,273 +2,10 @@
Benchmarker for TIG. Designed to run with a single master and multiple slaves distributed across servers. 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) * [Getting Started for Benchmarkers](https://docs.tig.foundation/benchmarking)
2. [Architecture Overview](#architecture-overview) * [Benchmarker Rewards](https://docs.tig.foundation/rewards/benchmarker-reward)
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:<UI_PORT>/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 <challenge_container_name> 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
# License # License