Home
The Engraver is the reference Burstcoin (or Burst) cross-platform plotting software, endorsed by the PoC Consortium, created to further improve and optimize Burst plot file creation.
Distinctive features of the Engraver are:
- PoC2 CPU&GPU plotting
- SIMD support: SSE2, AVX, AVX2, AVX512F
- Direct & Async I/O
- Resume plotting
- Graphical user interface
This document accommodates Engraver version 2.2.0, which is released under the MIT license.
Engraver can run and has been tested on 32 and 64-bit operating systems: Windows, Linux, Unix and MacOS.
In order to create plot files for mining Burst, users have to have an active Burst account and designated storage space. As it is outside the scope of this document to provide further details on necessary steps that precede the creation of plot files, users are advised to familiarize themselves with the concept of creating plot files using the information in the Burst Wiki.
Engraver is available for download at the dedicated Engraver page of the PoC-Consortium GitHub repository. The page currently offers 3 compiled versions of the application:
- engraver-2.2.0-x86_64-pc-windows-msvc-gui.zip - for Windows systems (command-line interface & graphical user interface)
- engraver-2.2.0-x86_64-unknown-linux-gnu.tar.gz - for Linux systems (command-line interface)
- engraver-2.2.0-x86_64-apple-darwin.tar.gz - for MacOS systems (command-line interface)
The application source code is also available for download and can be used after it has been compiled, which is described in chapter 7 of this user guide.
Engraver is a command-line executable and is available with graphical user interface on Windows systems.
After the downloaded archive has been unpacked or the application locally compiled, users should run the command prompt. On Windows systems, the command prompt is run by clicking the Windows button in the task bar, typing "cmd" and clicking the "Command Prompt". When plotting NTFS drives, it is recommended to start the command prompt as administrator by right-clicking and selecting "Run as administrator" instead of just clicking the icon. Administrative privileges are required to quickly allocate disk space on NTFS drives. Without administrator privileges, the disk space for the plot file will be initialized with zeros, a process that might take several hours.
To run Engraver, once the command prompt is running, users should navigate to the folder where the executable file is located (e.g. type "cd c:\engraver", if engraver is located in c:\engraver), type "engraver" and hit "Enter". The user will be shown application information and basic help, flags and options:
The usage of Engraver doesn't require a separate configuration step - all options and flags are provided as a single-line command. Options and flags start with "--" if the long version is used and with "-" if the shortcut is used.
Options (-shortcut, --long version)
-i, --id: Numeric account ID that will be used to create the plot file (mandatory)
-s, --sn: Starting nonce i.e. the lowest nonce number that will be used to create the plot file (mandatory)
In order to start plotting, users have to provide minimum the numeric account ID - which identifies the miner once the mining is started, the starting nonce and the number of nonces to be plotted. The plot file name will show this information as well, format is: numeric account ID_starting nonce_number of nonces.
Users should be aware that overlapping plots reduce the effective size of the plot, so they should provide these parameters with care.
A strategy to work out start nonce numbers and number of nonces for plotting could be:
For the first plot file(0):
- start nonce(0) = 0
- number of nonces(0) = disk space to be used for plot file(0) in MiB times 4
For the next plot file (i)
- start nonce(i) = start nonce(i-1) + number of nonces(i-1)
- number of nonces(i) = disk space to be used for file(i) in 4 x MiB times 4
Example: to create the first two 10Gib plot files: The first file:
- start nonce(0) = 0
- number of nonces(0) = 40960 (10GiB = 10240 MiB = 40960 nonces)
Resulting file name: numeric ID_0_40960
The second file:
- start nonce(1) = 0 + 40960 = 40960
- number of nonces(1) = 40960 (10GiB = 10240 MiB = 40960 nonces)
Resulting file name : numeric ID_40960_40960
-n, --n: the number of nonces to be plotted (mandatory)
If this option is set to zero, the plot file will have as many nonces as can fit onto the drive.
-p, --path: defines the path to the destination folder where the plot file will be stored (optional)
If the path is omitted, the plot file will be created in the working directory from where Engraver has been called.
-m, --mem: maximum amount of RAM memory to be use for plotting. If the unit is not provided, the number will be interpreted as bytes. If the user provides the suffix, it will be interpreted as the unit: e.g. "-- mem 4GiB"
Supported suffixes are: B, KiB, MiB, GiB, TiB, PiB, EiB, KB, MB, GB, TB, PB, EB
If the option is omitted, Engraver will use all available memory.
-c, --cpu: maximum number of CPU threads to use for plotting (default: all) (optional)
-g, --gpu (0:0:0): GPU(s) to be used for plotting (default: none) (optional)
GPU settings are provided in the following format: -g 0:0:0 where the first parameter represents platform ID, the second the device ID and the third represents the number of cores to use for plotting. In case the third GPU parameter is set to 0, all cores will be used. The Engraver allows for more than one GPUs to be configured for usage. To add the second GPU, provide an another -g 0:1:0 setting with proprietary parameters.
Using GPUs for plotting increases the memory requirements. In case the maximum memory to use parameter hasn't been set, Engraver will use all available RAM for plotting. In case the available RAM memory is insufficient, the Engraver will display a notice.
Flags
None of the flags are mandatory for creating plot files with the Engraver.
Available flags are:
-d, --ddio: diables direct I/O if used. Direct IO usage bypasses the OS caching layer.
-a, --daio: disables asynchronous writing (single buffer mode). In asynchronous write mode, the buffer is halved - half of it is used for writing, the other half for generating Shabal256 hashes at the same time. In single buffer mode, the full buffer is used for hashing, and then flushed to disk, without parallelization.
-l, --prio: if used, Engraver will run as a low priority process (useful if e.g. the miner runs while plotting).
-q, --quiet: runs Engraver in non-verbose mode (only error messages are displayed).
-b, --bench: runs Engraver in xPU benchmark mode. No plot files are created in benchmark mode, it is used to test the performance of the configuration.
-o, --opencl: displays available OpenCL platforms and devices.
-z, --zcb: enables zero copy buffers for shared memory (integrated) GPUs
-h, --help: displays help information.
-V, --version: displays version information.
To start plotting, users will type "engraver" with desired flags and options in the following format:
engraver [FLAGS] [OPTIONS] --id --sn --n
Example: engraver --quiet --path C:\plot --cpu 4 --id 15658436266575756999 --sn 0 --n 666 will:
-
start the Engraver in non-verbose mode (flag --quiet)
-
store the resulting plot file into folder 'plot' on C drive
-
use 4 CPU threads for plotting
-
use numeric account ID 15658436266575756999 for plotting
-
starting nonce will be 0
-
number of nonces will be 666
The result plot file: 15658436266575756999_0_666
After typing in the command as shown above, the plotter will start plotting. Depending on options and flags, the view will be different:
You can abort plotting (CTRL-C) and resume it at a later time. Engraver stores the progress. If you want to resume a partially plotted file, run engraver with same id, start nonce and number of nonces parameters again. If the flag -d has been used to create the incomplete file, it also has to be used when resuming.
Users who prefer to compile the application from its source code, can do so by downloading the source code from the PoCC Engraver release page. In order to compile the code, the latest stable version of Rust is required.To download and install Rust, visit the Rust Programming Language page and follow instructions provided on it. After setting up the environment, proceed by executing the following commands in Rust:
# build debug and run directly
cargo run
# build debug (unoptimized)
cargo build
# build release (optimized)
cargo build --release
# test
cargo test
Binaries are in target/debug or target/release depending on optimization.
Once the appropriate version of the Engraver is downloaded and the archive unpacked, the destination folder will contain two files: the Engraver executable and the Engraver graphical user interface (EngraverGui). The graphical user interface is started by double-clicking the EngraverGui executable.
Basic settings include the minimum of setting and information that has to be provided in order to start plotting.
- Numeric ID: the numeric account ID that will be used for creating the plot file,
- Output Folder: the folder on the system where the resulting file will be stored. Use the "Browse" button to navigate to the desired location,
- Drive Info: refers to the information of the destination drive. The drive information is populated after the user has selected the output folder,
The drive info includes the free space on the destination drive, maximum number of nonces that can be stored onto the available space and the logical sector size.
- Start Nonce: defines the start nonce number to plot. In case there are already plot files stored on the destination drive, it is recommended to use the "auto from last file" button, which will determine the correct nonce number to start plotting with in a way that will prevent overlapping of plot files
- Size to plot: a) Maximum: if this option is selected, the plot file will be created to fill up the entire available space on the destination drive b) Value: if the users selects this option, they can input the desired plot file size in nonces, MiB, TiB or GiB. Depending on the unit chosen, the Engraver will display the corresponding value in nonces or units of storage size.
Note that Engraver performs rounding of plot file size depending on the size of the logical sector. This is done in order to enable the fast direct i/o feature.
The advanced settings tab includes the following options:
-
XPU: chose your devices for hashing and optionally set a "Thread limit", which will allow the setting of the desired number of threads to be used for plotting. If the setting is left at 0, the maximum available threads will be used.
-
Low priority: if checked, the plotting process will be executed with low priority.
-
RAM: this setting allows to configure the maximum of system RAM memory that will be used for plotting. To limit the RAM used for plotting, check the "Memory limit" to enable the entry of the desired amount of RAM memory to be used for plotting.
-
I/O: a) Direct I/O usage bypasses the OS caching layer. The default setting is checked. If this option is unchecked, the plotting process will be considerably slower.
b) Async I/O if checked disables asynchronous writing (single buffer mode). In asynchronous write mode, which is the default setting, the buffer is halved - half of it is used for writing, the other half for generating Shabal256 hashes at the same time. In single buffer mode, the full buffer is used for hashing, and then flushed to disk, without parallelization.
After all desired parameters have been set, the "Start Plotting" button with initiate the plot file creation.
The plotting can be stopped, by clicking the "Stop Plotting" button. After the confirmation, the plotting will stop.
Engraver supports plotting resumption. To resume the plotting of a file, users will go to the "File" menu and select the "Resume file" option, navigate to the incomplete plot file, select it and resume plotting by clicking the "Start Plotting" button.