Rust Docs + refactor: `protocols` crates

[plebhash]

We recently published our protocols crates to crates.io. We need to make sure the APIs provided by those crates are properly documented under the Rust Best Practices.

This is also the perfect opportunity to map and address technical debt on those crates. As we go through the code and try to understand it, we take the chance to write down a list of ways the code could be improved. Things such as:

• unintuitive, redundant, broken or suboptimal APIs
• unsafe error handling (unwrap, panic!, expect)
• typos, bad variable names
• // todo comments, todo! macros, edge cases with unimplemented! or panic!

---

Task list

Rust Docs

• [x] v1 (already documented but worth a look before proceding)
  • INPUT: Q&A Discussion:: https://github.com/stratum-mining/stratum/discussions/897
  • OUTPUT: not planned
• [ ] v2/binary-sv2/binary-sv2
  • [ ] INPUT: Q&A Discussion: todo
  • [ ] INPUT: Rust Docs Issue #1008
  • [ ] OUTPUT: Rust Docs PR: todo
  • [ ] OUTPUT: Technical Debt issue: #1131
  • [ ] OUTPUT: Refactoring PRs: todo
• [ ] v2/binary-sv2/no-serde-sv2/codec
  • [ ] INPUT: Q&A Discussion: todo
  • [ ] INPUT: Rust Docs Issue: #1009
  • [ ] OUTPUT: Rust Docs PRs:
  • [ ] #1046 (small doc additions)
  • [ ] OUTPUT: Technical Debt issue: #1132
  • [ ] OUTPUT: Refactoring PRs: todo
• [ ] v2/binary-sv2/no-serde-sv2/derive_codec
  • [ ] INPUT: Q&A Discussion: todo
  • [ ] INPUT: Rust Docs Issue: #1010
  • [ ] OUTPUT: Rust Docs PR: todo
  • [ ] OUTPUT: Technical Debt issue: #1010
  • [ ] OUTPUT: Refactoring PRs: todo
• [ ] v2/binary-sv2/serde-sv2
  • [ ] INPUT: Q&A Discussion: todo
  • [ ] INPUT: Rust Docs Issue: #1011
  • [ ] OUTPUT: Rust Docs PR: todo
  • [ ] OUTPUT: Technical Debt issue: #1134
  • [ ] OUTPUT: Refactoring PRs: todo
• [ ] v2/const-sv2
  • [x] INPUT: Q&A Discussion: https://github.com/stratum-mining/stratum/discussions/1159
  • [x] INPUT: Rust Docs Issue: #1016
  • [ ] OUTPUT: Rust Docs PR: https://github.com/stratum-mining/stratum/pull/1160
  • [ ] OUTPUT: Technical Debt issue: #1135
  • [ ] OUTPUT: Refactoring PRs: todo
• [x] v2/framing-sv2
  • [x] INPUT: Q&A Discussion: https://github.com/stratum-mining/stratum/discussions/858
  • [x] INPUT: Rust Docs Issue: no tracker issue was created (we should avoid skipping for other crates)
  • [x] OUTPUT: Rust Docs PR: https://github.com/stratum-mining/stratum/pull/848
  • [x] OUTPUT: Technical Debt issue: https://github.com/stratum-mining/stratum/issues/903
  • [ ] OUTPUT: Refactoring PRs:
  • https://github.com/stratum-mining/stratum/pull/1033
  • https://github.com/stratum-mining/stratum/pull/1049
  • https://github.com/stratum-mining/stratum/pull/976
  • https://github.com/stratum-mining/stratum/pull/982
• [ ] v2/codec-sv2
  • [x] INPUT: Q&A Discussion: https://github.com/stratum-mining/stratum/discussions/873 (includes refactoring output, which should be eventually converted into issue)
  • [x] INPUT: Rust Docs issue: #1012
  • [ ] OUTPUT: Rust Docs PR: https://github.com/stratum-mining/stratum/pull/1040
  • [ ] OUTPUT: Technical Debt issue: #1129
  • [ ] OUTPUT: Refactoring PRs: todo
• [ ] v2/noise-sv2
  • [ ] INPUT: Discussion: https://github.com/stratum-mining/stratum/discussions/916
  • [ ] INPUT: Rust Docs Issue: #1013
  • [ ] OUTPUT: Rust Docs PR: #1111
  • [ ] OUTPUT: Technical Debt issue: #1130
  • [ ] OUTPUT: Refactoring PRs: todo
• [ ] v2/subprotocols (already documented but worth a look before proceeding)
  • [ ] PR improving docs: #963
  • [ ] partially identified refactoring output: https://github.com/stratum-mining/stratum/issues/1065
• [ ] v2/roles-logic-sv2
  • [ ] INPUT: Q&A Discussion: todo
  • [ ] INPUT: Rust Docs Issue: #1014
  • [ ] OUTPUT: Rust Docs PR: todo
  • [ ] OUTPUT: Technical Debt issue: todo
  • [ ] OUTPUT: Refactoring PRs: todo
• [ ] v2/sv2-ffi
  • [ ] INPUT: Q&A Discussion: https://github.com/stratum-mining/stratum/discussions/895
  • [ ] INPUT: #1015
  • [ ] OUTPUT: Rust Docs PR: todo
  • [ ] OUTPUT: Technical Debt issue: #1136
  • [ ] OUTPUT: Refactoring PRs: todo

Refactor Implementation

• [ ] #67
• [ ] TODO

[rrybarczyk]

We can leverage the work done in #854 in this effort when we start listing the technical debt for each crate.

[jbesraa]

What do you think about merging all the v2/binary-sv2/** into a single v2/binary-sv2 for the following reason https://github.com/stratum-mining/stratum/issues/1134#issuecomment-2333691340 ?

[Fi3]

I don't think that this is a good idea as we wouldn't be able to opt out serde anymore

[jbesraa]

Oh sorry maybe my comment was not clear. I was just suggesting to merge them in terms of the effort to document and refactor them, not merge the crates into a single one.