Questions about sv1_api crate

[plebhash]

This discussion should guide the documentation of sv1_api crate, as described on #845

Unlike most crates under protocols, this crate is already quite well documented.

But we have community members starting to adopt it for their projects (e.g.: @0xB10C), so this Discussion could still be a good place to clarify things and potentially come up with ideas to improve the docs.

[0xB10C]

Any reason why to not use BlockHash from rust-bitcoin for sv1_api::utils::PrevHash. I guess to keep it generic (i.e. other cryptocurrencies?) and to not be dependent on rust-bitcoin?

Edit:

PrevHash in Stratum V1 has brain-damaged serialization as it swaps bytes of every u32 word into big endian. Therefore, we need a special type for it

I guess it makes sense to offer the raw value (even if it's brain-damaged) to a consumer.

[Fi3]

This come from braiins open codebase. It is like that just cause was working code. And the only functionality that we needed was serialize and deserialize it (that differ from the one in BlockHash). I agree that for the user could be handy to get a bitcoin::BlockHash instead. Maybe we can implement Into BlockHash instead of substitute it, so that we don't break the API.