Skip to content

Job Declaration Documentation#1265

Merged
GitGab19 merged 3 commits into
stratum-mining:mainfrom
jbesraa:2024-11-08-job-declaration-msgs-docs
Dec 9, 2024
Merged

Job Declaration Documentation#1265
GitGab19 merged 3 commits into
stratum-mining:mainfrom
jbesraa:2024-11-08-job-declaration-msgs-docs

Conversation

@jbesraa

@jbesraa jbesraa commented Nov 25, 2024

Copy link
Copy Markdown
Contributor

resolves #1204

@codecov

codecov Bot commented Nov 25, 2024

Copy link
Copy Markdown

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 19.30%. Comparing base (407c642) to head (c0ff977).
Report is 4 commits behind head on main.

Additional details and impacted files
@@           Coverage Diff           @@
##             main    #1265   +/-   ##
=======================================
  Coverage   19.30%   19.30%           
=======================================
  Files         164      164           
  Lines       10849    10849           
=======================================
  Hits         2094     2094           
  Misses       8755     8755           
Flag Coverage Δ
binary_codec_sv2-coverage 0.00% <ø> (ø)
binary_serde_sv2-coverage 3.65% <ø> (ø)
binary_sv2-coverage 5.46% <ø> (ø)
bip32_derivation-coverage 0.00% <ø> (ø)
buffer_sv2-coverage 25.02% <ø> (ø)
codec_sv2-coverage 0.01% <ø> (ø)
common_messages_sv2-coverage 0.13% <ø> (ø)
const_sv2-coverage 0.00% <ø> (ø)
error_handling-coverage 0.00% <ø> (ø)
framing_sv2-coverage 0.29% <ø> (ø)
jd_client-coverage 0.00% <ø> (ø)
jd_server-coverage 7.79% <ø> (ø)
job_declaration_sv2-coverage 0.00% <ø> (ø)
key-utils-coverage 2.39% <ø> (ø)
mining-coverage 2.51% <ø> (+0.01%) ⬆️
mining_device-coverage 0.00% <ø> (ø)
mining_proxy_sv2-coverage 0.70% <ø> (ø)
noise_sv2-coverage 4.35% <ø> (ø)
pool_sv2-coverage 1.38% <ø> (ø)
protocols 24.72% <ø> (ø)
roles 6.55% <ø> (ø)
roles_logic_sv2-coverage 8.06% <ø> (ø)
sv2_ffi-coverage 0.00% <ø> (ø)
template_distribution_sv2-coverage 0.00% <ø> (ø)
translator_sv2-coverage 9.60% <ø> (ø)
utils 25.13% <ø> (ø)
v1-coverage 2.47% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

@github-actions

github-actions Bot commented Nov 28, 2024

Copy link
Copy Markdown
Contributor

🐰 Bencher Report

Branch2024-11-08-job-declaration-msgs-docs
Testbedsv1
Click to view all benchmark results
BenchmarkLatencyBenchmark Result
nanoseconds (ns)
(Result Δ%)
Upper Boundary
nanoseconds (ns)
(Limit %)
client-submit-serialize📈 view plot
🚷 view threshold
6,666.10
(-0.32%)
7,264.43
(91.76%)
client-submit-serialize-deserialize📈 view plot
🚷 view threshold
7,378.10
(-2.67%)
8,238.15
(89.56%)
client-submit-serialize-deserialize-handle/client-submit-serialize-deserialize-handle📈 view plot
🚷 view threshold
8,059.50
(-1.25%)
8,698.70
(92.65%)
client-sv1-authorize-serialize-deserialize-handle/client-sv1-authorize-serialize-deserialize-handle📈 view plot
🚷 view threshold
853.11
(-1.27%)
929.17
(91.81%)
client-sv1-authorize-serialize-deserialize/client-sv1-authorize-serialize-deserialize📈 view plot
🚷 view threshold
659.45
(-1.82%)
708.04
(93.14%)
client-sv1-authorize-serialize/client-sv1-authorize-serialize📈 view plot
🚷 view threshold
248.92
(-0.22%)
275.27
(90.43%)
client-sv1-get-authorize/client-sv1-get-authorize📈 view plot
🚷 view threshold
157.78
(+0.39%)
163.03
(96.78%)
client-sv1-get-submit📈 view plot
🚷 view threshold
6,326.40
(-2.54%)
7,277.39
(86.93%)
client-sv1-get-subscribe/client-sv1-get-subscribe📈 view plot
🚷 view threshold
276.65
(-1.00%)
306.29
(90.32%)
client-sv1-subscribe-serialize-deserialize-handle/client-sv1-subscribe-serialize-deserialize-handle📈 view plot
🚷 view threshold
729.19
(-0.07%)
788.52
(92.48%)
client-sv1-subscribe-serialize-deserialize/client-sv1-subscribe-serialize-deserialize📈 view plot
🚷 view threshold
575.82
(-2.91%)
643.44
(89.49%)
client-sv1-subscribe-serialize/client-sv1-subscribe-serialize📈 view plot
🚷 view threshold
202.90
(-1.26%)
216.40
(93.76%)
🐰 View full continuous benchmarking report in Bencher

@github-actions

github-actions Bot commented Nov 28, 2024

Copy link
Copy Markdown
Contributor

🐰 Bencher Report

Branch2024-11-08-job-declaration-msgs-docs
Testbedsv2

🚨 3 Alerts

BenchmarkMeasure
Units
ViewBenchmark Result
(Result Δ%)
Upper Boundary
(Limit %)
client_sv2_handle_message_miningEstimated Cycles
estimated cycles
📈 plot
🚨 alert (🔔)
🚷 threshold
8,306.00
(+1.23%)
8,303.22
(100.03%)
client_sv2_handle_message_miningRAM Accesses
accesses
📈 plot
🚨 alert (🔔)
🚷 threshold
142.00
(+2.11%)
141.60
(100.28%)
client_sv2_mining_message_submit_standard_serialize_deserializeL2 Accesses
accesses
📈 plot
🚨 alert (🔔)
🚷 threshold
93.00
(+13.91%)
91.60
(101.53%)
Click to view all benchmark results
BenchmarkEstimated CyclesBenchmark Result
estimated cycles
(Result Δ%)
Upper Boundary
estimated cycles
(Limit %)
InstructionsBenchmark Result
instructions
(Result Δ%)
Upper Boundary
instructions
(Limit %)
L1 AccessesBenchmark Result
accesses
(Result Δ%)
Upper Boundary
accesses
(Limit %)
L2 AccessesBenchmark Result
accesses
(Result Δ%)
Upper Boundary
accesses
(Limit %)
RAM AccessesBenchmark Result
accesses
(Result Δ%)
Upper Boundary
accesses
(Limit %)
client_sv2_handle_message_common📈 view plot
🚷 view threshold
2,121.00
(+1.09%)
2,215.51
(95.73%)
📈 view plot
🚷 view threshold
473.00
(-0.06%)
488.67
(96.79%)
📈 view plot
🚷 view threshold
736.00
(+0.02%)
757.48
(97.16%)
📈 view plot
🚷 view threshold
4.00
(-24.04%)
13.51
(29.61%)
📈 view plot
🚷 view threshold
39.00
(+2.17%)
41.40
(94.20%)
client_sv2_handle_message_mining📈 view plot
🚨 view alert (🔔)
🚷 view threshold
8,306.00
(+1.23%)
8,303.22
(100.03%)
📈 view plot
🚷 view threshold
2,137.00
(-0.03%)
2,143.08
(99.72%)
📈 view plot
🚷 view threshold
3,156.00
(-0.15%)
3,170.85
(99.53%)
📈 view plot
🚷 view threshold
36.00
(+1.65%)
41.57
(86.60%)
📈 view plot
🚨 view alert (🔔)
🚷 view threshold
142.00
(+2.11%)
141.60
(100.28%)
client_sv2_mining_message_submit_standard📈 view plot
🚷 view threshold
6,345.00
(+0.98%)
6,409.55
(98.99%)
📈 view plot
🚷 view threshold
1,750.00
(-0.05%)
1,767.03
(99.04%)
📈 view plot
🚷 view threshold
2,550.00
(-0.13%)
2,575.88
(99.00%)
📈 view plot
🚷 view threshold
17.00
(+0.55%)
24.22
(70.20%)
📈 view plot
🚷 view threshold
106.00
(+1.76%)
107.67
(98.45%)
client_sv2_mining_message_submit_standard_serialize📈 view plot
🚷 view threshold
14,804.00
(+0.52%)
14,948.37
(99.03%)
📈 view plot
🚷 view threshold
4,694.00
(-0.02%)
4,711.03
(99.64%)
📈 view plot
🚷 view threshold
6,749.00
(-0.14%)
6,783.12
(99.50%)
📈 view plot
🚷 view threshold
50.00
(+14.63%)
54.56
(91.64%)
📈 view plot
🚷 view threshold
223.00
(+0.71%)
227.23
(98.14%)
client_sv2_mining_message_submit_standard_serialize_deserialize📈 view plot
🚷 view threshold
27,796.00
(+0.92%)
27,862.42
(99.76%)
📈 view plot
🚷 view threshold
10,645.00
(+0.55%)
10,663.08
(99.83%)
📈 view plot
🚷 view threshold
15,501.00
(+0.61%)
15,530.80
(99.81%)
📈 view plot
🚨 view alert (🔔)
🚷 view threshold
93.00
(+13.91%)
91.60
(101.53%)
📈 view plot
🚷 view threshold
338.00
(+0.87%)
341.75
(98.90%)
client_sv2_open_channel📈 view plot
🚷 view threshold
4,443.00
(+1.15%)
4,586.68
(96.87%)
📈 view plot
🚷 view threshold
1,461.00
(-0.02%)
1,476.67
(98.94%)
📈 view plot
🚷 view threshold
2,158.00
(-0.10%)
2,184.21
(98.80%)
📈 view plot
🚷 view threshold
9.00
(+3.60%)
16.53
(54.43%)
📈 view plot
🚷 view threshold
64.00
(+2.34%)
67.82
(94.37%)
client_sv2_open_channel_serialize📈 view plot
🚷 view threshold
14,032.00
(-0.07%)
14,351.53
(97.77%)
📈 view plot
🚷 view threshold
5,064.00
(-0.01%)
5,079.67
(99.69%)
📈 view plot
🚷 view threshold
7,322.00
(-0.06%)
7,351.70
(99.60%)
📈 view plot
🚷 view threshold
40.00
(+13.60%)
44.19
(90.51%)
📈 view plot
🚷 view threshold
186.00
(-0.45%)
195.78
(95.01%)
client_sv2_open_channel_serialize_deserialize📈 view plot
🚷 view threshold
22,824.00
(+0.70%)
22,932.56
(99.53%)
📈 view plot
🚷 view threshold
8,040.00
(+0.20%)
8,071.27
(99.61%)
📈 view plot
🚷 view threshold
11,689.00
(+0.14%)
11,746.26
(99.51%)
📈 view plot
🚷 view threshold
85.00
(+14.03%)
85.61
(99.29%)
📈 view plot
🚷 view threshold
306.00
(+0.84%)
310.97
(98.40%)
client_sv2_setup_connection📈 view plot
🚷 view threshold
4,707.00
(+0.45%)
4,780.05
(98.47%)
📈 view plot
🚷 view threshold
1,502.00
(-0.02%)
1,517.67
(98.97%)
📈 view plot
🚷 view threshold
2,277.00
(-0.06%)
2,299.30
(99.03%)
📈 view plot
🚷 view threshold
10.00
(+4.40%)
16.56
(60.37%)
📈 view plot
🚷 view threshold
68.00
(+0.87%)
69.96
(97.20%)
client_sv2_setup_connection_serialize📈 view plot
🚷 view threshold
16,206.00
(+0.26%)
16,425.09
(98.67%)
📈 view plot
🚷 view threshold
5,963.00
(-0.01%)
5,978.67
(99.74%)
📈 view plot
🚷 view threshold
8,656.00
(-0.09%)
8,691.59
(99.59%)
📈 view plot
🚷 view threshold
47.00
(+17.96%)
53.15
(88.43%)
📈 view plot
🚷 view threshold
209.00
(+0.20%)
215.41
(97.02%)
client_sv2_setup_connection_serialize_deserialize📈 view plot
🚷 view threshold
35,744.00
(+0.52%)
35,809.13
(99.82%)
📈 view plot
🚷 view threshold
14,888.00
(+0.23%)
14,911.57
(99.84%)
📈 view plot
🚷 view threshold
21,869.00
(+0.21%)
21,923.27
(99.75%)
📈 view plot
🚷 view threshold
108.00
(+17.18%)
111.22
(97.10%)
📈 view plot
🚷 view threshold
381.00
(+0.44%)
385.06
(98.95%)
🐰 View full continuous benchmarking report in Bencher

@github-actions

github-actions Bot commented Nov 28, 2024

Copy link
Copy Markdown
Contributor

🐰 Bencher Report

Branch2024-11-08-job-declaration-msgs-docs
Testbedsv1
Click to view all benchmark results
BenchmarkEstimated CyclesBenchmark Result
estimated cycles
(Result Δ%)
Upper Boundary
estimated cycles
(Limit %)
InstructionsBenchmark Result
instructions
(Result Δ%)
Upper Boundary
instructions
(Limit %)
L1 AccessesBenchmark Result
accesses
(Result Δ%)
Upper Boundary
accesses
(Limit %)
L2 AccessesBenchmark Result
accesses
(Result Δ%)
Upper Boundary
accesses
(Limit %)
RAM AccessesBenchmark Result
accesses
(Result Δ%)
Upper Boundary
accesses
(Limit %)
get_authorize📈 view plot
🚷 view threshold
8,418.00
(-0.55%)
8,731.23
(96.41%)
📈 view plot
🚷 view threshold
3,663.00
(-2.23%)
3,864.35
(94.79%)
📈 view plot
🚷 view threshold
5,108.00
(-2.74%)
5,440.89
(93.88%)
📈 view plot
🚷 view threshold
11.00
(+49.63%)
13.88
(79.27%)
📈 view plot
🚷 view threshold
93.00
(+2.49%)
95.53
(97.35%)
get_submit📈 view plot
🚷 view threshold
95,332.00
(-0.10%)
95,882.53
(99.43%)
📈 view plot
🚷 view threshold
59,263.00
(-0.32%)
59,703.41
(99.26%)
📈 view plot
🚷 view threshold
85,072.00
(-0.38%)
85,796.68
(99.16%)
📈 view plot
🚷 view threshold
50.00
(+11.93%)
62.77
(79.66%)
📈 view plot
🚷 view threshold
286.00
(+2.05%)
289.88
(98.66%)
get_subscribe📈 view plot
🚷 view threshold
7,931.00
(-1.11%)
8,276.94
(95.82%)
📈 view plot
🚷 view threshold
2,758.00
(-2.62%)
2,943.14
(93.71%)
📈 view plot
🚷 view threshold
3,831.00
(-3.19%)
4,131.71
(92.72%)
📈 view plot
🚷 view threshold
15.00
(+25.41%)
20.61
(72.79%)
📈 view plot
🚷 view threshold
115.00
(+0.55%)
118.61
(96.96%)
serialize_authorize📈 view plot
🚷 view threshold
12,207.00
(-0.62%)
12,566.06
(97.14%)
📈 view plot
🚷 view threshold
5,240.00
(-1.47%)
5,431.16
(96.48%)
📈 view plot
🚷 view threshold
7,277.00
(-1.86%)
7,598.20
(95.77%)
📈 view plot
🚷 view threshold
13.00
(+40.90%)
16.76
(77.54%)
📈 view plot
🚷 view threshold
139.00
(+0.90%)
142.68
(97.42%)
serialize_deserialize_authorize📈 view plot
🚷 view threshold
24,640.00
(-0.23%)
25,215.77
(97.72%)
📈 view plot
🚷 view threshold
9,786.00
(-1.03%)
10,041.04
(97.46%)
📈 view plot
🚷 view threshold
13,785.00
(-1.24%)
14,201.55
(97.07%)
📈 view plot
🚷 view threshold
36.00
(+3.81%)
43.72
(82.35%)
📈 view plot
🚷 view threshold
305.00
(+1.03%)
314.91
(96.85%)
serialize_deserialize_handle_authorize📈 view plot
🚷 view threshold
30,223.00
(-0.34%)
30,747.36
(98.29%)
📈 view plot
🚷 view threshold
11,989.00
(-0.74%)
12,208.71
(98.20%)
📈 view plot
🚷 view threshold
16,953.00
(-0.88%)
17,305.52
(97.96%)
📈 view plot
🚷 view threshold
57.00
(+2.49%)
67.60
(84.33%)
📈 view plot
🚷 view threshold
371.00
(+0.30%)
381.42
(97.27%)
serialize_deserialize_handle_submit📈 view plot
🚷 view threshold
126,434.00
(-0.03%)
126,894.42
(99.64%)
📈 view plot
🚷 view threshold
73,117.00
(-0.23%)
73,523.60
(99.45%)
📈 view plot
🚷 view threshold
104,759.00
(-0.28%)
105,463.84
(99.33%)
📈 view plot
🚷 view threshold
114.00
(+6.74%)
131.65
(86.59%)
📈 view plot
🚷 view threshold
603.00
(+1.05%)
606.28
(99.46%)
serialize_deserialize_handle_subscribe📈 view plot
🚷 view threshold
27,829.00
(-0.09%)
28,582.50
(97.36%)
📈 view plot
🚷 view threshold
9,577.00
(-0.73%)
9,756.68
(98.16%)
📈 view plot
🚷 view threshold
13,519.00
(-0.91%)
13,816.72
(97.85%)
📈 view plot
🚷 view threshold
69.00
(+8.46%)
76.31
(90.42%)
📈 view plot
🚷 view threshold
399.00
(+0.53%)
416.31
(95.84%)
serialize_deserialize_submit📈 view plot
🚷 view threshold
115,185.00
(-0.06%)
115,786.72
(99.48%)
📈 view plot
🚷 view threshold
67,894.00
(-0.30%)
68,410.04
(99.25%)
📈 view plot
🚷 view threshold
97,355.00
(-0.38%)
98,253.47
(99.09%)
📈 view plot
🚷 view threshold
73.00
(+16.05%)
79.50
(91.82%)
📈 view plot
🚷 view threshold
499.00
(+1.49%)
499.89
(99.82%)
serialize_deserialize_subscribe📈 view plot
🚷 view threshold
23,240.00
(-0.15%)
23,964.96
(96.97%)
📈 view plot
🚷 view threshold
8,129.00
(-0.90%)
8,312.98
(97.79%)
📈 view plot
🚷 view threshold
11,425.00
(-1.11%)
11,724.75
(97.44%)
📈 view plot
🚷 view threshold
39.00
(+4.37%)
44.92
(86.82%)
📈 view plot
🚷 view threshold
332.00
(+0.74%)
347.15
(95.64%)
serialize_submit📈 view plot
🚷 view threshold
99,789.00
(-0.06%)
100,299.12
(99.49%)
📈 view plot
🚷 view threshold
61,325.00
(-0.28%)
61,734.50
(99.34%)
📈 view plot
🚷 view threshold
87,929.00
(-0.35%)
88,628.91
(99.21%)
📈 view plot
🚷 view threshold
55.00
(+17.53%)
64.81
(84.86%)
📈 view plot
🚷 view threshold
331.00
(+1.86%)
334.77
(98.87%)
serialize_subscribe📈 view plot
🚷 view threshold
11,410.00
(+0.02%)
11,678.44
(97.70%)
📈 view plot
🚷 view threshold
4,111.00
(-1.65%)
4,285.77
(95.92%)
📈 view plot
🚷 view threshold
5,690.00
(-2.14%)
5,984.68
(95.08%)
📈 view plot
🚷 view threshold
17.00
(+31.32%)
21.27
(79.93%)
📈 view plot
🚷 view threshold
161.00
(+1.93%)
163.62
(98.40%)
🐰 View full continuous benchmarking report in Bencher

@github-actions

github-actions Bot commented Nov 28, 2024

Copy link
Copy Markdown
Contributor

🐰 Bencher Report

Branch2024-11-08-job-declaration-msgs-docs
Testbedsv2
Click to view all benchmark results
BenchmarkLatencyBenchmark Result
nanoseconds (ns)
(Result Δ%)
Upper Boundary
nanoseconds (ns)
(Limit %)
client_sv2_handle_message_common📈 view plot
🚷 view threshold
45.17
(+1.41%)
46.97
(96.16%)
client_sv2_handle_message_mining📈 view plot
🚷 view threshold
78.50
(+3.60%)
90.33
(86.91%)
client_sv2_mining_message_submit_standard📈 view plot
🚷 view threshold
14.66
(-0.04%)
14.79
(99.10%)
client_sv2_mining_message_submit_standard_serialize📈 view plot
🚷 view threshold
268.83
(+1.97%)
302.41
(88.90%)
client_sv2_mining_message_submit_standard_serialize_deserialize📈 view plot
🚷 view threshold
617.09
(+0.42%)
695.53
(88.72%)
client_sv2_open_channel📈 view plot
🚷 view threshold
162.78
(+4.03%)
197.57
(82.39%)
client_sv2_open_channel_serialize📈 view plot
🚷 view threshold
286.13
(+0.71%)
307.95
(92.92%)
client_sv2_open_channel_serialize_deserialize📈 view plot
🚷 view threshold
380.04
(-0.35%)
411.72
(92.31%)
client_sv2_setup_connection📈 view plot
🚷 view threshold
162.72
(+1.37%)
168.62
(96.50%)
client_sv2_setup_connection_serialize📈 view plot
🚷 view threshold
495.51
(+4.84%)
567.61
(87.30%)
client_sv2_setup_connection_serialize_deserialize📈 view plot
🚷 view threshold
1,003.90
(+1.60%)
1,110.08
(90.44%)
🐰 View full continuous benchmarking report in Bencher

@jbesraa jbesraa marked this pull request as ready for review December 2, 2024 09:10
Comment on lines +9 to +11
The following crate contains the messages defined in the Job Declaration Protocol of Stratum V2.
This protocol runs between the Job Declarator and Pool and can be provided as a trusted 3rd party
service for mining farms.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
The following crate contains the messages defined in the Job Declaration Protocol of Stratum V2.
This protocol runs between the Job Declarator and Pool and can be provided as a trusted 3rd party
service for mining farms.
`job_declaration_sv2` is a Rust crate that implements a set of messages defined in the Job Declaration Protocol of Stratum V2.
This protocol runs between the Job Declarator Server (JDS) and Job Declarator Client (JDC).

Comment thread protocols/v2/subprotocols/job-declaration/README.md
/// A request to get an identifier for a future-submitted mining job.
/// Rate limited to a rather slow rate and only available on connections where this has been
/// negotiated. Otherwise, only `mining_job_token(s)` from `CreateMiningJob.Success` are valid.
/// Message used by JDClient to request an identifier for a future mining job from JDServer.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
/// Message used by JDClient to request an identifier for a future mining job from JDServer.
/// Message used by Job Declarator Client (JDC) to request an identifier for a future mining job from Job Declarator Server (JDS).

Comment on lines +13 to +15
/// Unconstrained sequence of bytes. Whatever is needed by the JDServer to
/// identify/authenticate the client. Additional restrictions can be imposed by the
/// JDServer. It is highly recommended that UTF-8 encoding is used.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
/// Unconstrained sequence of bytes. Whatever is needed by the JDServer to
/// identify/authenticate the client. Additional restrictions can be imposed by the
/// JDServer. It is highly recommended that UTF-8 encoding is used.
/// Unconstrained sequence of bytes. Whatever is needed by the JDS to
/// identify/authenticate the client. Additional restrictions can be imposed by the
/// JDS. It is highly recommended that UTF-8 encoding is used.

/// Notably, if the pool intends to change the space it requires for coinbase transaction outputs
/// regularly, it should simply prefer to use the maximum of all such output sizes as the
/// `coinbase_output_max_additional_size` value.
/// A Message used by a JDServer in response to a [`AllocateMiningJobToken`] message.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
/// A Message used by a JDServer in response to a [`AllocateMiningJobToken`] message.
/// A message used by a JDS in response to a [`AllocateMiningJobToken`] message.

Comment on lines +5 to +6
//! The following crate defines the set of messages used in the Job Declaration Stratum V2
//! subprotcol.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
//! The following crate defines the set of messages used in the Job Declaration Stratum V2
//! subprotcol.
//! This crate defines the set of messages used in the Job Declaration subprotcol of Stratum V2.

// position in the original DeclareMiningJob message, 0-indexed not including the coinbase
// transaction transaction.

/// A message used by the JDserver to ask for transactions that it did not recognize from

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
/// A message used by the JDserver to ask for transactions that it did not recognize from
/// A message used by the JDS to ask for transactions that it did not recognize from

Comment on lines +12 to +14
/// In order to do block propagation, JDServer must know all the transactions within the current
/// block template. These transactions are provided by the JDClient to the JDserver as a sequence
/// of short hashes in the [`crate::DeclareMiningJob::tx_short_hash_list`] message. If JDserver is

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
/// In order to do block propagation, JDServer must know all the transactions within the current
/// block template. These transactions are provided by the JDClient to the JDserver as a sequence
/// of short hashes in the [`crate::DeclareMiningJob::tx_short_hash_list`] message. If JDserver is
/// In order to do block propagation, JDS must know all the transactions within the current
/// block template. These transactions are provided by the JDC to the JDS as a sequence
/// of short hashes in the [`crate::DeclareMiningJob::tx_short_hash_list`] message. If JDS is

///
/// Must be the same as the received [`crate::DeclareMiningJob::request_id`].
pub request_id: u32,
/// A list of unrecognized transactions that need to be supplied by the JDClient in full. They

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
/// A list of unrecognized transactions that need to be supplied by the JDClient in full. They
/// A list of unrecognized transactions that need to be supplied by the JDC in full. They

Comment on lines +9 to +14
/// A message sent by JDClient as soon as it finds a valid block.
///
/// Upon receiving this message, JDServer should propogate the new block as soon as possible.
///
/// Note that JDClient is also expected to share the new block data through `SubmitSolution`

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
/// A message sent by JDClient as soon as it finds a valid block.
///
/// Upon receiving this message, JDServer should propogate the new block as soon as possible.
///
/// Note that JDClient is also expected to share the new block data through `SubmitSolution`
/// A message sent by JDC as soon as it finds a valid block.
///
/// Upon receiving this message, JDS should propagate the new block as soon as possible.
///
/// Note that JDC is also expected to share the new block data through `SubmitSolution`

@GitGab19 GitGab19 left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM. Left a couple of nits

Comment on lines +30 to +31
/// A Token that makes the JD Client eligible for committing a mining job for
/// approval/transaction declaration or for identifying custom mining job on mining connection.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Have you missed this one? We always referenced to it with JDC, I've never seen JD Client

// position in the original DeclareMiningJob message, 0-indexed not including the coinbase
// transaction transaction.

/// Message used by the JDserver to ask for transactions that it did not recognize from

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
/// Message used by the JDserver to ask for transactions that it did not recognize from
/// Message used by JDS to ask for transactions that it did not recognize from

@jbesraa

jbesraa commented Dec 9, 2024

Copy link
Copy Markdown
Contributor Author

Rebased without further changes

@GitGab19 GitGab19 merged commit 8c8a440 into stratum-mining:main Dec 9, 2024
@jbesraa jbesraa deleted the 2024-11-08-job-declaration-msgs-docs branch February 12, 2025 10:36
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Need Rust docs on protocols::v2::subprotocols::job-declaration

2 participants