Merge pull request #541 from Chia-Network/asic-timelord-docs

Asic timelord docs

docs/architecture/timelords.md

@@ -27,7 +27,7 @@ You can learn about potential attacks against Chia's network in the [Attacks and
 
 There are two primary types of Timelords: Regular and Blueboxes.
 
-The first is the core Timelord that takes in Proofs of Space and uses a single fastest core to perform repeated squaring in a [class group of unknown order](https://github.com/Chia-Network/vdf-competition/blob/master/classgroups.pdf) as fast as possible. Beside each running VDF (referred to as a vdf_client in the application and source) is a set of proof generation threads that accumulate the proof that the time calculation's number of iterations was done correctly.
+The first is the core Timelord and can be either a software Timelord or a hardware Timelord (ASIC) that takes in Proofs of Space and uses a single fastest core to perform repeated squaring in a [class group of unknown order](https://github.com/Chia-Network/vdf-competition/blob/master/classgroups.pdf) as fast as possible. Beside each running VDF (referred to as a vdf_client in the application and source) is a set of proof generation threads that accumulate the proof that the time calculation's number of iterations was done correctly.
 
 The second are Bluebox Timelords. Blueboxes are most any machine - especially things like old servers or gaming machines - that scour the historical chain looking for uncompressed proofs of time. So that the chain moves quickly, the regular Timelords use a faster method of generating proofs of time but the proofs are larger, which takes your Raspberry Pi a lot more time and effort to validate and sync the blockchain. A Bluebox picks up an uncompressed Proof of Time and recreates it, but this time with the slower and more compact proofs generated at the end. Those are then gossiped around to everyone so they can replace the large and slow to verify Proofs of Time with the compact and much quicker to validate version of exactly the same thing.
 
@@ -39,36 +39,17 @@ It's good to have a few Timelords out there. There can be things like routing fl
 
 The Company plans to run a few Timelords around the world - and some backups too - to ensure that all Farmers and nodes can hear the beat that the Timelords are calling.
 
-## Installing a Timelord
+For installation and usage documentation please refer [here](/timelord-install).
 
-:::info
-If you want to run a Timelord on Linux/MacOS, first follow the Install from Source instructions [here](/installation#from-source). Then run:
-
-```bash
-. ./activate
-sh install-timelord.sh
-chia start timelord &
-```
-
-:::
-
-Timelords execute sequential verifiable delay functions (proofs of time or VDFs), that get added to blocks to make them valid. This requires fast CPUs and a few cores per VDF.
-
-Due to restrictions on how [MSVC](https://en.wikipedia.org/wiki/Microsoft_Visual_C%2B%2B) handles 128 bit numbers and how Python relies upon MSVC, it is not possible to build and run Timelords of all types on Windows.
-
-### Regular Timelords
-
-On MacOS x86_64 and all Linux distributions, building a Timelord is as easy as running `chia start timelord &` in the virtual environment. You can also run `./vdf_bench square_asm 400000` once you've built Timelord to give you a sense of your optimal and unloaded ips. Each run of `vdf_bench` can be surprisingly variable and, in production, the actual ips you will obtain will usually be about 20% lower due to load of creating proofs. The default configuration for Timelords is good enough to just let you start it up. Set your log level to INFO and then grep for "Estimated IPS:" to get a sense of what actual ips your Timelord is achieving.
-
-### Bluebox Timelords
+## Troubleshooting a Timelord
 
-Once you build the Timelord with `sh install-timelord.sh` in the virtual environment, you will need to make two changes to `~/.chia/VERSION/config.yaml`. In the `timelord:` section, set `bluebox_mode:` to `True`. Then you need to proceed to the `full_node:` section and set `send_uncompact_interval:` to something greater than 0. We recommend `300` seconds there so that your Bluebox has some time to prove through a lot of the un-compacted Proofs of Time before the node drops more into its lap. The default settings may otherwise work but if the total effort is a little too much for whatever machine you are on you can also lower the `process_count:` from 3 to 2, or even 1, in the `timelord_launcher:` section. You know it is working if you see `VDF Client: Sent proof` in your logs at INFO level.
+For troubleshooting steps please refer to the documentation [here](/troubleshooting/timelords).
 
 ## The Future of Timelords
 
 In 2023, CNI received its first batch of ASIC timelords. When run as a cluster of three VDFs, these timelords could hit upwards of one million IPS. This was approximately four times the speed of the fastest non-ASIC timelords. After installing several timelords in strategic locations globally, and after thorough testing on private testnets, the company added the ASICs to a public testnet. Finally, after [years of designing](https://www.businesswire.com/news/home/20211013005324/en/Chia-Partners-With-Supranational-to-Create-Industry-Leading-Proof-of-Space-Time-Security) the ASICs and months of testing them, they were activated on mainnet in October 2023.
 
-The next step is to distribute some of the remaining ASIC timelords to a select list of applicants, as detailed in a [blog post](https://www.chia.net/2023/10/26/asic-timelords-faster-than-fast-chia-network/). This process will ensure a high amount of global redundancy on this critical network infrastructure.
+The next step was to distribute some of the remaining ASIC timelords to a select list of applicants, as detailed in a [blog post](https://www.chia.net/2023/10/26/asic-timelords-faster-than-fast-chia-network/). This process ensures a high amount of global redundancy on this critical network infrastructure.
 
 Of course, as technology improves, the ASIC design will need to be updated. However, this process is extremely costly, and the current generation is already pushing upon the limits imposed by the laws of physics. We expect the current crop to remain the fastest timelords in the world for years to come.
 

docs/cli-reference/asic-hwvdf.md

@@ -0,0 +1,119 @@
+---
+sidebar_label: ASICs
+title: ASICs HW VDF
+slug: /asic-cli
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+## Reference
+
+### `hw_vdf_client`
+
+Functionality: Run the ASIC HW VDF Software
+
+Usage: hw_vdf_client [OPTIONS] PORT [N_VDFS]
+
+Options:
+
+| Long Command       | Type    | Required | Description                                           |
+| :----------------- | :------ | :------- | :---------------------------------------------------- |
+| --freq             | INTEGER | False    | set ASIC frequency [%d, 200 - 2200]                   |
+| --voltage          | INTEGER | False    | set board voltage [.88, 0.7 - 1.0]                    |
+| --ip               | TEXT    | False    | timelord IP address [localhost]                       |
+| --vdfs-mask        | TEXT    | False    | mask for enabling VDF engines [7, 1 - 7]              |
+| --vdf-threads      | TEXT    | False    | number of software threads per VDF engine [4, 2 - 64] |
+| --proof-threads    | TEXT    | False    | number of proof threads per VDF engine [3, 1 - 63]    |
+| --auto-freq-period | TEXT    | False    | auto-adjust frequency every N seconds [0, 10 - inf]   |
+| --list             | TEXT    | False    | list available devices and exit                       |
+| --help             | None    | False    | Show a help message and exit                          |
+
+<details>
+<summary>Example 1 - Run the ASIC software with defaults</summary>
+
+```bash
+hw_vdf_client 8000 3
+```
+
+Response:
+
+```
+2024-04-12T10:32:05.898 Setting frequency to 1100.000000 MHz
+2024-04-12T10:32:06.016 Frequency is 1100.000000 MHz
+2024-04-12T10:32:06.020 Board voltage is 0.875 V
+2024-04-12T10:32:06.020 Setting voltage to 0.880 V
+2024-04-12T10:32:06.021 Board voltage is now 0.875 V
+2024-04-12T10:32:06.032 Board current is 0.698 A
+2024-04-12T10:32:06.043 Board power is 0.610 W
+2024-04-12T10:32:06.049 Connecting to 127.0.0.1:8000
+2024-04-12T10:32:06.049 VDF 0: Connected to timelord, waiting for challenge
+```
+
+</details>
+
+<details>
+<summary>Example 2 - Run the ASIC software with auto-frequency, initial frequency, and defined ip</summary>
+
+```bash
+hw_vdf_client --freq 1500 --auto-freq 60 --ip 192.168.0.122 8000 3
+```
+
+Response:
+
+```
+2024-04-12T10:32:05.898 Setting frequency to 1500.000000 MHz
+2024-04-12T10:32:06.016 Frequency is 1500.000000 MHz
+2024-04-12T10:32:06.020 Board voltage is 0.875 V
+2024-04-12T10:32:06.020 Setting voltage to 0.880 V
+2024-04-12T10:32:06.021 Board voltage is now 0.875 V
+2024-04-12T10:32:06.032 Board current is 0.698 A
+2024-04-12T10:32:06.043 Board power is 0.610 W
+2024-04-12T10:32:06.049 Connecting to 192.168.0.122:8000
+2024-04-12T10:32:06.049 VDF 0: Connected to timelord, waiting for challenge
+```
+
+</details>
+
+<details>
+<summary>Example 3 - Run the ASIC software with defined ip and only 1 vdf (i.e. defaults for cluster)</summary>
+
+```bash
+hw_vdf_client --ip 192.168.0.122 8000 1
+```
+
+Response:
+
+```
+2024-04-12T10:32:05.898 Setting frequency to 1100.000000 MHz
+2024-04-12T10:32:06.016 Frequency is 1100.000000 MHz
+2024-04-12T10:32:06.020 Board voltage is 0.875 V
+2024-04-12T10:32:06.020 Setting voltage to 0.880 V
+2024-04-12T10:32:06.021 Board voltage is now 0.875 V
+2024-04-12T10:32:06.032 Board current is 0.698 A
+2024-04-12T10:32:06.043 Board power is 0.610 W
+2024-04-12T10:32:06.049 Connecting to 192.168.0.122:8000
+2024-04-12T10:32:06.049 VDF 0: Connected to timelord, waiting for challenge
+```
+
+</details>
+
+---
+
+## Troubleshooting a Timelord
+
+For troubleshooting steps please refer to the documentation [here](/troubleshooting/timelords).
+
+---
+
+## Timelord support
+
+Join Our [Discord](https://discord.gg/chia) and jump into the #support channel for support
+
+---
+
+## Timelord FAQ
+
+For FAQ please refer to the documentation [here](/timelord-install#timelord-faq).
+
+---