mirror of
https://github.com/tig-pool-nk/tig-monorepo.git
synced 2026-02-21 09:47:21 +08:00
Update documentation.
This commit is contained in:
FiveMovesAhead
parent
4957a809d4
commit
127235e1b5
11
README.md
11
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.
|
||||
|
||||
@ -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(
|
||||
|
||||
@ -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(
|
||||
|
||||
81
swagger.yaml
81
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 `<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)
|
||||
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 `<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:
|
||||
|
||||
@ -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:
|
||||
|
||||
@ -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%
|
||||
@ -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:
|
||||
|
||||
`<challenge_name>\<algorithm_name>`
|
||||
|
||||
## 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/<challenge_name>/<algorithm_name>/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/<challenge_name>/<algorithm_name>.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/<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`
|
||||
* [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
|
||||
|
||||
|
||||
0
tig-algorithms/advances/hypergraph/.gitkeep
Normal file
0
tig-algorithms/advances/hypergraph/.gitkeep
Normal file
0
tig-algorithms/advances/knapsack/.gitkeep
Normal file
0
tig-algorithms/advances/knapsack/.gitkeep
Normal file
0
tig-algorithms/advances/satisfiability/.gitkeep
Normal file
0
tig-algorithms/advances/satisfiability/.gitkeep
Normal file
0
tig-algorithms/advances/vector_search/.gitkeep
Normal file
0
tig-algorithms/advances/vector_search/.gitkeep
Normal file
0
tig-algorithms/advances/vehicle_routing/.gitkeep
Normal file
0
tig-algorithms/advances/vehicle_routing/.gitkeep
Normal file
@ -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
|
||||
|
||||
|
||||
@ -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:<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
|
||||
* [Getting Started for Benchmarkers](https://docs.tig.foundation/benchmarking)
|
||||
* [Benchmarker Rewards](https://docs.tig.foundation/rewards/benchmarker-reward)
|
||||
|
||||
# License
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user