`common_messages_sv2` docs #1242

jbesraa · 2024-11-06T07:55:09Z

resolves #1203

codecov · 2024-11-06T07:58:08Z

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 19.30%. Comparing base (2543595) to head (aadf42d).
Report is 5 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #1242   +/-   ##
=======================================
  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.

protocols/v2/subprotocols/common-messages/README.md

protocols/v2/subprotocols/common-messages/src/channel_endpoint_changed.rs

protocols/v2/subprotocols/common-messages/src/lib.rs

protocols/v2/subprotocols/common-messages/src/setup_connection.rs

Shourya742

@jbesraa, could you also update the sv2.h file to match the changes in the docs? I noticed a few public structures, methods, and enums missing documentation. Maybe add #![deny(missing_docs)] at the top level to catch those and see what's missing?

Also, these methods seem a bit off:

pub fn set_requires_standard_job(&mut self) {
    self.flags |= 0b_0000_0000_0000_0000_0000_0000_0000_0001;
}

pub fn set_async_job_negotiation(&mut self) {
    self.flags |= 0b_0000_0000_0000_0000_0000_0000_0000_0001;
}

Both are setting the LSB and set_requires_standard_job looks like it's only used in tests.

Shourya742 · 2024-11-15T09:24:25Z

protocols/v2/subprotocols/common-messages/src/setup_connection.rs

+///
+/// This message is sent in response to a [`SetupConnection`] message.
+///
+/// The connection setup process could fail because of protocol version negotiation.  In order


Suggested change

/// The connection setup process could fail because of protocol version negotiation. In order

/// The connection setup process could fail because of protocol version negotiation. In order

@jbesraa did you miss this one?

jbesraa · 2024-11-17T12:32:19Z

@jbesraa, could you also update the sv2.h file to match the changes in the docs? I noticed a few public structures, methods, and enums missing documentation. Maybe add #![deny(missing_docs)] at the top level to catch those and see what's missing?

Also, these methods seem a bit off:
pub fn set_requires_standard_job(&mut self) {
    self.flags |= 0b_0000_0000_0000_0000_0000_0000_0000_0001;
}

pub fn set_async_job_negotiation(&mut self) {
    self.flags |= 0b_0000_0000_0000_0000_0000_0000_0000_0001;
}
Both are setting the LSB and set_requires_standard_job looks like it's only used in tests.

Thanks for the review. What exactly should be changed in sv2.h ? is this the file in the ffi crate?

In regards to the function that might be wrong/unused, I would leave that to a separate PR.

jbesraa · 2024-11-17T12:34:07Z

@GitGab19 Thanks for the review. I believe I addressed all of your comments.

Some of the structs throw a warning(https://github.com/stratum-mining/stratum/actions/runs/11878855683/job/33100048008?pr=1242) for missing documentation for the Deserliaze proc-macro, I believe that will be fixed once the binary_sv2 crate will be documented.

github-actions · 2024-11-17T12:39:38Z

Bencher Report

Branch	2024-10-29-common-msgs-docs
Testbed	sv1

Click to view all benchmark results

Benchmark	Latency	Benchmark Result nanoseconds (ns) (Result Δ%)	Upper Boundary nanoseconds (ns) (Limit %)
client-submit-serialize	📈 view plot 🚷 view threshold	6,609.00 (-1.37%)	7,223.26 (91.50%)
client-submit-serialize-deserialize	📈 view plot 🚷 view threshold	7,422.80 (-2.31%)	8,207.93 (90.43%)
client-submit-serialize-deserialize-handle/client-submit-serialize-deserialize-handle	📈 view plot 🚷 view threshold	8,041.80 (-1.57%)	8,716.78 (92.26%)
client-sv1-authorize-serialize-deserialize-handle/client-sv1-authorize-serialize-deserialize-handle	📈 view plot 🚷 view threshold	860.12 (-0.63%)	930.08 (92.48%)
client-sv1-authorize-serialize-deserialize/client-sv1-authorize-serialize-deserialize	📈 view plot 🚷 view threshold	666.30 (-0.85%)	707.54 (94.17%)
client-sv1-authorize-serialize/client-sv1-authorize-serialize	📈 view plot 🚷 view threshold	251.58 (+0.65%)	276.73 (90.91%)
client-sv1-get-authorize/client-sv1-get-authorize	📈 view plot 🚷 view threshold	157.95 (+0.43%)	163.23 (96.76%)
client-sv1-get-submit	📈 view plot 🚷 view threshold	6,311.10 (-3.02%)	7,274.00 (86.76%)
client-sv1-get-subscribe/client-sv1-get-subscribe	📈 view plot 🚷 view threshold	277.96 (-0.64%)	307.75 (90.32%)
client-sv1-subscribe-serialize-deserialize-handle/client-sv1-subscribe-serialize-deserialize-handle	📈 view plot 🚷 view threshold	722.98 (-1.01%)	789.59 (91.56%)
client-sv1-subscribe-serialize-deserialize/client-sv1-subscribe-serialize-deserialize	📈 view plot 🚷 view threshold	586.61 (-1.39%)	638.42 (91.88%)
client-sv1-subscribe-serialize/client-sv1-subscribe-serialize	📈 view plot 🚷 view threshold	210.58 (+2.12%)	218.30 (96.47%)

🐰 View full continuous benchmarking report in Bencher

github-actions · 2024-11-17T12:39:54Z

Bencher Report

Branch	2024-10-29-common-msgs-docs
Testbed	sv2

🚨 7 Alerts

Benchmark	Measure Units	View	Benchmark Result (Result Δ%)	Upper Boundary (Limit %)
client_sv2_handle_message_mining	Estimated Cycles estimated cycles	📈 plot 🚨 alert (🔔) 🚷 threshold	8,322.00 (+1.43%)	8,300.99 (100.25%)
client_sv2_handle_message_mining	RAM Accesses accesses	📈 plot 🚨 alert (🔔) 🚷 threshold	142.00 (+2.12%)	141.46 (100.38%)
client_sv2_mining_message_submit_standard_serialize	L2 Accesses accesses	📈 plot 🚨 alert (🔔) 🚷 threshold	56.00 (+28.44%)	54.59 (102.59%)
client_sv2_mining_message_submit_standard_serialize_deserialize	L2 Accesses accesses	📈 plot 🚨 alert (🔔) 🚷 threshold	95.00 (+16.46%)	91.30 (104.05%)
client_sv2_open_channel_serialize	L2 Accesses accesses	📈 plot 🚨 alert (🔔) 🚷 threshold	46.00 (+30.64%)	44.40 (103.60%)
client_sv2_open_channel_serialize_deserialize	Estimated Cycles estimated cycles	📈 plot 🚨 alert (🔔) 🚷 threshold	22,960.00 (+1.30%)	22,935.82 (100.11%)
client_sv2_setup_connection_serialize_deserialize	Estimated Cycles estimated cycles	📈 plot 🚨 alert (🔔) 🚷 threshold	35,846.00 (+0.81%)	35,807.58 (100.11%)

Click to view all benchmark results

Benchmark	Estimated Cycles	Benchmark Result estimated cycles (Result Δ%)	Upper Boundary estimated cycles (Limit %)	Instructions	Benchmark Result instructions (Result Δ%)	Upper Boundary instructions (Limit %)	L1 Accesses	Benchmark Result accesses (Result Δ%)	Upper Boundary accesses (Limit %)	L2 Accesses	Benchmark Result accesses (Result Δ%)	Upper Boundary accesses (Limit %)	RAM Accesses	Benchmark Result accesses (Result Δ%)	Upper Boundary accesses (Limit %)
client_sv2_handle_message_common	📈 view plot 🚷 view threshold	2,167.00 (+3.31%)	2,216.46 (97.77%)	📈 view plot 🚷 view threshold	473.00 (-0.06%)	488.67 (96.79%)	📈 view plot 🚷 view threshold	732.00 (-0.53%)	757.49 (96.63%)	📈 view plot 🚷 view threshold	7.00 (+32.35%)	13.54 (51.71%)	📈 view plot 🚷 view threshold	40.00 (+4.85%)	41.43 (96.56%)
client_sv2_handle_message_mining	📈 view plot 🚨 view alert (🔔) 🚷 view threshold	8,322.00 (+1.43%)	8,300.99 (100.25%)	📈 view plot 🚷 view threshold	2,137.00 (-0.03%)	2,143.08 (99.72%)	📈 view plot 🚷 view threshold	3,152.00 (-0.28%)	3,170.97 (99.40%)	📈 view plot 🚷 view threshold	40.00 (+12.78%)	41.86 (95.55%)	📈 view plot 🚨 view alert (🔔) 🚷 view threshold	142.00 (+2.12%)	141.46 (100.38%)
client_sv2_mining_message_submit_standard	📈 view plot 🚷 view threshold	6,403.00 (+1.91%)	6,409.41 (99.90%)	📈 view plot 🚷 view threshold	1,750.00 (-0.05%)	1,767.03 (99.04%)	📈 view plot 🚷 view threshold	2,543.00 (-0.41%)	2,576.04 (98.72%)	📈 view plot 🚷 view threshold	23.00 (+35.92%)	24.42 (94.17%)	📈 view plot 🚷 view threshold	107.00 (+2.75%)	107.62 (99.43%)
client_sv2_mining_message_submit_standard_serialize	📈 view plot 🚷 view threshold	14,862.00 (+0.91%)	14,951.17 (99.40%)	📈 view plot 🚷 view threshold	4,694.00 (-0.02%)	4,711.03 (99.64%)	📈 view plot 🚷 view threshold	6,742.00 (-0.24%)	6,783.17 (99.39%)	📈 view plot 🚨 view alert (🔔) 🚷 view threshold	56.00 (+28.44%)	54.59 (102.59%)	📈 view plot 🚷 view threshold	224.00 (+1.15%)	227.30 (98.55%)
client_sv2_mining_message_submit_standard_serialize_deserialize	📈 view plot 🚷 view threshold	27,838.00 (+1.07%)	27,856.43 (99.93%)	📈 view plot 🚷 view threshold	10,645.00 (+0.55%)	10,661.46 (99.85%)	📈 view plot 🚷 view threshold	15,498.00 (+0.60%)	15,527.77 (99.81%)	📈 view plot 🚨 view alert (🔔) 🚷 view threshold	95.00 (+16.46%)	91.30 (104.05%)	📈 view plot 🚷 view threshold	339.00 (+1.17%)	341.79 (99.18%)
client_sv2_open_channel	📈 view plot 🚷 view threshold	4,523.00 (+2.96%)	4,588.85 (98.57%)	📈 view plot 🚷 view threshold	1,461.00 (-0.02%)	1,476.67 (98.94%)	📈 view plot 🚷 view threshold	2,153.00 (-0.33%)	2,184.26 (98.57%)	📈 view plot 🚷 view threshold	12.00 (+37.51%)	16.67 (71.98%)	📈 view plot 🚷 view threshold	66.00 (+5.52%)	67.85 (97.27%)
client_sv2_open_channel_serialize	📈 view plot 🚷 view threshold	14,124.00 (+0.57%)	14,361.39 (98.35%)	📈 view plot 🚷 view threshold	5,064.00 (-0.01%)	5,079.67 (99.69%)	📈 view plot 🚷 view threshold	7,314.00 (-0.17%)	7,351.84 (99.49%)	📈 view plot 🚨 view alert (🔔) 🚷 view threshold	46.00 (+30.64%)	44.40 (103.60%)	📈 view plot 🚷 view threshold	188.00 (+0.59%)	196.05 (95.89%)
client_sv2_open_channel_serialize_deserialize	📈 view plot 🚨 view alert (🔔) 🚷 view threshold	22,960.00 (+1.30%)	22,935.82 (100.11%)	📈 view plot 🚷 view threshold	8,040.00 (+0.21%)	8,071.73 (99.61%)	📈 view plot 🚷 view threshold	11,685.00 (+0.11%)	11,747.11 (99.47%)	📈 view plot 🚷 view threshold	85.00 (+14.12%)	85.51 (99.41%)	📈 view plot 🚷 view threshold	310.00 (+2.15%)	311.19 (99.62%)
client_sv2_setup_connection	📈 view plot 🚷 view threshold	4,749.00 (+1.36%)	4,780.41 (99.34%)	📈 view plot 🚷 view threshold	1,502.00 (-0.02%)	1,517.67 (98.97%)	📈 view plot 🚷 view threshold	2,274.00 (-0.19%)	2,299.34 (98.90%)	📈 view plot 🚷 view threshold	12.00 (+25.29%)	16.63 (72.16%)	📈 view plot 🚷 view threshold	69.00 (+2.36%)	69.95 (98.65%)
client_sv2_setup_connection_serialize	📈 view plot 🚷 view threshold	16,256.00 (+0.57%)	16,428.63 (98.95%)	📈 view plot 🚷 view threshold	5,963.00 (-0.01%)	5,978.67 (99.74%)	📈 view plot 🚷 view threshold	8,651.00 (-0.15%)	8,691.68 (99.53%)	📈 view plot 🚷 view threshold	51.00 (+27.97%)	53.27 (95.74%)	📈 view plot 🚷 view threshold	210.00 (+0.67%)	215.50 (97.45%)
client_sv2_setup_connection_serialize_deserialize	📈 view plot 🚨 view alert (🔔) 🚷 view threshold	35,846.00 (+0.81%)	35,807.58 (100.11%)	📈 view plot 🚷 view threshold	14,888.00 (+0.23%)	14,911.25 (99.84%)	📈 view plot 🚷 view threshold	21,866.00 (+0.20%)	21,923.11 (99.74%)	📈 view plot 🚷 view threshold	108.00 (+17.20%)	111.12 (97.19%)	📈 view plot 🚷 view threshold	384.00 (+1.23%)	385.12 (99.71%)

🐰 View full continuous benchmarking report in Bencher

github-actions · 2024-11-17T12:40:08Z

Bencher Report

Branch	2024-10-29-common-msgs-docs
Testbed	sv2

Click to view all benchmark results

Benchmark	Latency	Benchmark Result nanoseconds (ns) (Result Δ%)	Upper Boundary nanoseconds (ns) (Limit %)
client_sv2_handle_message_common	📈 view plot 🚷 view threshold	45.18 (+1.53%)	46.94 (96.25%)
client_sv2_handle_message_mining	📈 view plot 🚷 view threshold	72.82 (-2.94%)	88.57 (82.22%)
client_sv2_mining_message_submit_standard	📈 view plot 🚷 view threshold	14.67 (+0.03%)	14.80 (99.13%)
client_sv2_mining_message_submit_standard_serialize	📈 view plot 🚷 view threshold	262.52 (-0.21%)	303.43 (86.52%)
client_sv2_mining_message_submit_standard_serialize_deserialize	📈 view plot 🚷 view threshold	615.94 (+0.27%)	700.20 (87.97%)
client_sv2_open_channel	📈 view plot 🚷 view threshold	164.83 (+5.62%)	198.98 (82.84%)
client_sv2_open_channel_serialize	📈 view plot 🚷 view threshold	282.33 (-0.54%)	309.10 (91.34%)
client_sv2_open_channel_serialize_deserialize	📈 view plot 🚷 view threshold	379.65 (-0.22%)	407.70 (93.12%)
client_sv2_setup_connection	📈 view plot 🚷 view threshold	159.98 (-0.24%)	168.39 (95.01%)
client_sv2_setup_connection_serialize	📈 view plot 🚷 view threshold	457.19 (-2.75%)	567.30 (80.59%)
client_sv2_setup_connection_serialize_deserialize	📈 view plot 🚷 view threshold	1,014.10 (+2.47%)	1,120.96 (90.47%)

🐰 View full continuous benchmarking report in Bencher

github-actions · 2024-11-17T12:40:12Z

Bencher Report

Branch	2024-10-29-common-msgs-docs
Testbed	sv1

Click to view all benchmark results

Benchmark	Estimated Cycles	Benchmark Result estimated cycles (Result Δ%)	Upper Boundary estimated cycles (Limit %)	Instructions	Benchmark Result instructions (Result Δ%)	Upper Boundary instructions (Limit %)	L1 Accesses	Benchmark Result accesses (Result Δ%)	Upper Boundary accesses (Limit %)	L2 Accesses	Benchmark Result accesses (Result Δ%)	Upper Boundary accesses (Limit %)	RAM Accesses	Benchmark Result accesses (Result Δ%)	Upper Boundary accesses (Limit %)
get_authorize	📈 view plot 🚷 view threshold	8,448.00 (-0.20%)	8,731.14 (96.76%)	📈 view plot 🚷 view threshold	3,663.00 (-2.25%)	3,862.65 (94.83%)	📈 view plot 🚷 view threshold	5,108.00 (-2.76%)	5,437.53 (93.94%)	📈 view plot 🚷 view threshold	10.00 (+36.61%)	13.69 (73.03%)	📈 view plot 🚷 view threshold	94.00 (+3.62%)	95.47 (98.46%)
get_submit	📈 view plot 🚷 view threshold	95,358.00 (-0.07%)	95,884.46 (99.45%)	📈 view plot 🚷 view threshold	59,263.00 (-0.32%)	59,699.07 (99.27%)	📈 view plot 🚷 view threshold	85,073.00 (-0.38%)	85,788.63 (99.17%)	📈 view plot 🚷 view threshold	48.00 (+7.43%)	62.86 (76.36%)	📈 view plot 🚷 view threshold	287.00 (+2.41%)	289.76 (99.05%)
get_subscribe	📈 view plot 🚷 view threshold	7,961.00 (-0.74%)	8,276.45 (96.19%)	📈 view plot 🚷 view threshold	2,758.00 (-2.65%)	2,941.84 (93.75%)	📈 view plot 🚷 view threshold	3,831.00 (-3.22%)	4,129.02 (92.78%)	📈 view plot 🚷 view threshold	14.00 (+17.12%)	20.58 (68.04%)	📈 view plot 🚷 view threshold	116.00 (+1.43%)	118.60 (97.81%)
serialize_authorize	📈 view plot 🚷 view threshold	12,233.00 (-0.40%)	12,566.26 (97.35%)	📈 view plot 🚷 view threshold	5,240.00 (-1.48%)	5,429.61 (96.51%)	📈 view plot 🚷 view threshold	7,278.00 (-1.86%)	7,594.98 (95.83%)	📈 view plot 🚷 view threshold	11.00 (+19.63%)	16.60 (66.28%)	📈 view plot 🚷 view threshold	140.00 (+1.64%)	142.70 (98.11%)
serialize_deserialize_authorize	📈 view plot 🚷 view threshold	24,628.00 (-0.28%)	25,219.11 (97.66%)	📈 view plot 🚷 view threshold	9,786.00 (-1.04%)	10,039.28 (97.48%)	📈 view plot 🚷 view threshold	13,788.00 (-1.23%)	14,197.77 (97.11%)	📈 view plot 🚷 view threshold	33.00 (-4.76%)	43.67 (75.57%)	📈 view plot 🚷 view threshold	305.00 (+1.06%)	314.98 (96.83%)
serialize_deserialize_handle_authorize	📈 view plot 🚷 view threshold	30,261.00 (-0.22%)	30,748.53 (98.41%)	📈 view plot 🚷 view threshold	11,989.00 (-0.74%)	12,207.34 (98.21%)	📈 view plot 🚷 view threshold	16,951.00 (-0.89%)	17,302.51 (97.97%)	📈 view plot 🚷 view threshold	58.00 (+4.31%)	67.54 (85.88%)	📈 view plot 🚷 view threshold	372.00 (+0.59%)	381.50 (97.51%)
serialize_deserialize_handle_submit	📈 view plot 🚷 view threshold	126,472.00 (-0.00%)	126,894.76 (99.67%)	📈 view plot 🚷 view threshold	73,117.00 (-0.23%)	73,520.55 (99.45%)	📈 view plot 🚷 view threshold	104,757.00 (-0.29%)	105,457.78 (99.34%)	📈 view plot 🚷 view threshold	115.00 (+7.63%)	131.94 (87.16%)	📈 view plot 🚷 view threshold	604.00 (+1.23%)	606.13 (99.65%)
serialize_deserialize_handle_subscribe	📈 view plot 🚷 view threshold	27,859.00 (+0.03%)	28,587.95 (97.45%)	📈 view plot 🚷 view threshold	9,577.00 (-0.73%)	9,755.43 (98.17%)	📈 view plot 🚷 view threshold	13,519.00 (-0.92%)	13,814.26 (97.86%)	📈 view plot 🚷 view threshold	68.00 (+6.96%)	76.24 (89.20%)	📈 view plot 🚷 view threshold	400.00 (+0.81%)	416.46 (96.05%)
serialize_deserialize_submit	📈 view plot 🚷 view threshold	115,169.00 (-0.07%)	115,790.10 (99.46%)	📈 view plot 🚷 view threshold	67,894.00 (-0.30%)	68,406.73 (99.25%)	📈 view plot 🚷 view threshold	97,359.00 (-0.38%)	98,246.56 (99.10%)	📈 view plot 🚷 view threshold	69.00 (+9.82%)	79.01 (87.33%)	📈 view plot 🚷 view threshold	499.00 (+1.51%)	499.61 (99.88%)
serialize_deserialize_subscribe	📈 view plot 🚷 view threshold	23,232.00 (-0.17%)	23,971.28 (96.92%)	📈 view plot 🚷 view threshold	8,129.00 (-0.90%)	8,311.58 (97.80%)	📈 view plot 🚷 view threshold	11,427.00 (-1.10%)	11,721.68 (97.49%)	📈 view plot 🚷 view threshold	37.00 (-0.86%)	44.75 (82.68%)	📈 view plot 🚷 view threshold	332.00 (+0.78%)	347.31 (95.59%)
serialize_submit	📈 view plot 🚷 view threshold	99,815.00 (-0.03%)	100,299.28 (99.52%)	📈 view plot 🚷 view threshold	61,325.00 (-0.29%)	61,730.62 (99.34%)	📈 view plot 🚷 view threshold	87,930.00 (-0.35%)	88,621.24 (99.22%)	📈 view plot 🚷 view threshold	53.00 (+13.33%)	64.63 (82.01%)	📈 view plot 🚷 view threshold	332.00 (+2.18%)	334.58 (99.23%)
serialize_subscribe	📈 view plot 🚷 view threshold	11,440.00 (+0.29%)	11,678.35 (97.96%)	📈 view plot 🚷 view threshold	4,111.00 (-1.67%)	4,284.60 (95.95%)	📈 view plot 🚷 view threshold	5,690.00 (-2.16%)	5,982.00 (95.12%)	📈 view plot 🚷 view threshold	16.00 (+23.82%)	21.12 (75.77%)	📈 view plot 🚷 view threshold	162.00 (+2.60%)	163.57 (99.04%)

🐰 View full continuous benchmarking report in Bencher

GitGab19

LGTM. Left two minor things. For me we can open the PR review process to everyone now. What do you think @jbesraa ?

protocols/v2/subprotocols/common-messages/src/lib.rs

GitGab19 · 2024-11-18T18:04:03Z

@GitGab19 Thanks for the review. I believe I addressed all of your comments.

Some of the structs throw a warning(https://github.com/stratum-mining/stratum/actions/runs/11878855683/job/33100048008?pr=1242) for missing documentation for the Deserliaze proc-macro, I believe that will be fixed once the binary_sv2 crate will be documented.

Why do you say it will be fixed when binary_sv2 crate will be documented?

jbesraa · 2024-11-19T14:37:11Z

@GitGab19 Thanks for the review. I believe I addressed all of your comments.
Some of the structs throw a warning(https://github.com/stratum-mining/stratum/actions/runs/11878855683/job/33100048008?pr=1242) for missing documentation for the Deserliaze proc-macro, I believe that will be fixed once the binary_sv2 crate will be documented.

Why do you say it will be fixed when binary_sv2 crate will be documented?

Because it is complaining about functions inside Deserliaze that are not documented and Deserliaze is coming from binary_sv2. We could remove the warn(missing_docs) also..

jbesraa · 2024-11-19T14:37:24Z

LGTM. Left two minor things. For me we can open the PR review process to everyone now. What do you think @jbesraa ?

sounds good

GitGab19

LGTM. Let's open the review process to anyone to move on with this PR. I also saw that @Shourya742 already started to review it partially, don't know if he can complete it with a second one.

protocols/v2/subprotocols/common-messages/README.md

protocols/v2/subprotocols/common-messages/src/lib.rs

protocols/v2/subprotocols/common-messages/README.md

protocols/v2/subprotocols/common-messages/src/setup_connection.rs

Shourya742 · 2024-11-21T10:26:45Z

@jbesraa, could you also update the sv2.h file to match the changes in the docs? I noticed a few public structures, methods, and enums missing documentation. Maybe add #![deny(missing_docs)] at the top level to catch those and see what's missing?
Also, these methods seem a bit off:
pub fn set_requires_standard_job(&mut self) {
    self.flags |= 0b_0000_0000_0000_0000_0000_0000_0000_0001;
}

pub fn set_async_job_negotiation(&mut self) {
    self.flags |= 0b_0000_0000_0000_0000_0000_0000_0000_0001;
}
Both are setting the LSB and set_requires_standard_job looks like it's only used in tests.
Thanks for the review. What exactly should be changed in sv2.h ? is this the file in the ffi crate?

In regards to the function that might be wrong/unused, I would leave that to a separate PR.

We can track the methods mentioned in the refactor issue for this crate to ensure they aren't forgotten. Regarding the sv2.h file, you need to run the build_header.sh script to generate an updated sv2.h file in the scripts folder. Then, copy its contents into the existing sv2.h file. Changes to the sv2.h file are due to newly added comments, which also ensure that the comments are rendered in the C++ header files.

protocols/v2/subprotocols/common-messages/README.md

Shourya742 · 2024-11-21T10:51:45Z

protocols/v2/subprotocols/common-messages/src/lib.rs

@@ -1,7 +1,13 @@
+//! # Stratum V2 Common Messages Crate.


This isn't directly related to documentation, but we can create a separate prop_test module to consolidate all the generation code, instead of applying the feature gate to individual lines. This could be included as part of a refactoring issue.

Shourya742 · 2024-11-21T11:08:03Z

protocols/v2/subprotocols/common-messages/src/channel_endpoint_changed.rs

+/// `extension_type`.
+///
+/// When a downstream receives such a message, any extension state (including version and extension
+/// support) must be reset and renegotiated.
 #[repr(C)]
 #[derive(Serialize, Deserialize, Debug, Copy, Clone, PartialEq, Eq)]


Suggested change

#[derive(Serialize, Deserialize, Debug, Copy, Clone, PartialEq, Eq)]

#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]

This isn't related to documentation, but either Copy or Clone can be removed, as both aren't necessary. Additionally, Eq is not required. This could be added to the refactoring tracker.

protocols/v2/subprotocols/common-messages/src/setup_connection.rs

GitGab19 · 2024-12-02T04:48:26Z

@jbesraa is it ready for a final round of review? I see you still need to address some comments from @Shourya742

jbesraa · 2024-12-02T07:55:11Z

@jbesraa is it ready for a final round of review? I see you still need to address some comments from @Shourya742

I still need to fix the header thing, but feel free to review. Addressed all comments.

GitGab19

LGTM. Left only a single minor comment.

protocols/v2/subprotocols/common-messages/src/setup_connection.rs

protocols/v2/subprotocols/common-messages/README.md

GitGab19

It's good to go for me. I just pinged you on a couple of comments you might have missed.

GitGab19 · 2024-12-07T04:29:52Z

protocols/v2/subprotocols/common-messages/src/setup_connection.rs

+///
+/// This message is sent in response to a [`SetupConnection`] message.
+///
+/// The connection setup process could fail because of protocol version negotiation.  In order


@jbesraa did you miss this one?

protocols/v2/subprotocols/common-messages/src/lib.rs

jbesraa · 2024-12-07T08:47:54Z

@GitGab19 Addressed the above

GitGab19 · 2024-12-07T09:27:00Z

@jbesraa there's the semver check which is failing, when you solve it, I will merge this one.

jbesraa · 2024-12-07T09:30:01Z

@jbesraa there's the semver check which is failing, when you solve it, I will merge this one.

No idea why would this actually fail. could you please rerun it?

.. and fix some styling inconsistency

As part of the effort to improve Stratum V2 protocols docs, this commit aims to improves and make the documentation more comprehensive and accessible for contributors and end users alike.

Use the template README used across the different Stratum V2 protocol crates to `common_messages_sv2` crate.

jbesraa force-pushed the 2024-10-29-common-msgs-docs branch from bf46414 to 920076b Compare November 6, 2024 07:59

jbesraa marked this pull request as ready for review November 6, 2024 15:08

GitGab19 mentioned this pull request Nov 12, 2024

Rust Docs + refactor: protocols crates #845

Open

78 tasks

GitGab19 reviewed Nov 13, 2024

View reviewed changes

Shourya742 suggested changes Nov 15, 2024

View reviewed changes

jbesraa force-pushed the 2024-10-29-common-msgs-docs branch 2 times, most recently from b1d08ac to aa72fcd Compare November 17, 2024 12:30

stratum-mining deleted a comment from github-actions bot Nov 18, 2024

GitGab19 reviewed Nov 18, 2024

View reviewed changes

protocols/v2/subprotocols/common-messages/src/lib.rs Outdated Show resolved Hide resolved

protocols/v2/subprotocols/common-messages/src/lib.rs Show resolved Hide resolved

jbesraa force-pushed the 2024-10-29-common-msgs-docs branch from aa72fcd to 27d54cf Compare November 19, 2024 14:36

jbesraa force-pushed the 2024-10-29-common-msgs-docs branch from 27d54cf to a23801f Compare November 19, 2024 14:39

GitGab19 reviewed Nov 20, 2024

View reviewed changes

protocols/v2/subprotocols/common-messages/README.md Outdated Show resolved Hide resolved