sighash module name is confusing

[Kixunil]

AFAIK the term sighash usually refers to the SIGHASH_x flags. However the sighash module provides tools for actually signing the transactions. (I vaguely remember getting confused about this.)

Alternative names:

• sign
• tx_sign/sign_tx
• signing
• horribly long variants such as transaction_signing

I think I like sign_tx the most, feel free to suggest others.

Also *SighashType and Annex belong to something like primitives.

[apoelstra]

IME sighash refers to the actual signature hash while "sighash flag" refers to the flags (which are closely related to the sighash).

Is there anything in this module that is not sighash-related? I did a quick skim and it seems not.

I also don't see any actual signing code so I don't think it makes sense to call it something like signing.

[sanket1729]

Perhaps, I am also used to sighash name here. I would be okay with sighash_msg, sighash_message or sig_msg (BIP 341 term)

[Kixunil]

Hmm, maybe I'm biased by having less coding experience than doc-reading in this area. sig_msg sounds quite good. (or even without underscore).

[apoelstra]

That sounds like it's related to signmessage, or something ... it's definitely not clear that it's referring to a sighash.

[Kixunil]

Oh, true. Is there anything particularly wrong with sign_tx?

[apoelstra]

This module is only tangentially related to signing. It's about computing and caching sighashes.

[Kixunil]

That's like 90% of all work one has to do when signing Bitcoin transactions. The only other parts are constructing tap tree (if any), calling one function from secp256k1 and shoving the result into a Witness

What's confusing about it is it's not obvious that "you need this module to sign transactions". Maybe just change the doc summary to something like "Infrastructure for signing Bitcoin transactions"?

[apoelstra]

If it's 90% of the work then we should definitely label it something discoverable, which "sighash" is. "Infrastructure for signing Bitcoin transactions" does not make it obvious at all what's inside, and kinda sounds like it might be a collection of ad-hoc accoutrements that a normal users might not need, since normally you just compute a sighash and sign it.

[Kixunil]

I guess that depends on the background. Someone coming from Bitcoin Core would probably look for sighash and seeing that module name would make it obvious. Someone completely new would search for "transaction signing" or "sign transaction" and would see that. Having both "signature hash" an "transaction signing" in the doc doesn't sound bad if we can come up with reasonable wording.

[apoelstra]

For sure -- I'm happy to extend the documentation to describe what a sighash is (and maybe disambiguate between the sighash and a sighash flag), and to give the high-level "compute a sighash, sign it, stick the signature into the transaction/PSBT" workflow. I think it'll take more than a sentence or two.

We could also put an example of signing a transaction in the top-level lib.rs, which will use this module, hopefully hinting new users where they need to look.

[Kixunil]

put an example of signing a transaction in the top-level lib.rs

I'd love to have something like a cookbook:

• This is how you receive data over P2P
• This is how you parse blocks and transactions
• This is how you construct and sign transactions
• ...

This should be well-visible at front page (README, doc) and link to separated doc. Otherwise the front page could become cluttered with things.

[tcharding]

If #1597 merges the sighash module will have been moved to crypto::sighash and will only contain the sighash cache. Does that satisfy this issue for now? As part of #1606 I plan on writing a bunch of documentation on what all the various sighashes are.

[Kixunil]

It's basically a documentation issue now, I will try to come up with a simple PR.

[Kixunil]

Bad news: I just found out the generated docs don't have full text search - they can only search in names. I think the cookbook is the only way.

[tcharding]

I think the cookbook is the only way.

If we get this done by BTC Prague we could have two tracks in the workshop, one for full enthusiasts (develop a wallet) and one for casually interested Rust devs (work through / look through the cookbook)?

[Kixunil]

That could be interesting. But I wouldn't try too hard. I suggest:

• One of us figures out a nice way of writing and publishing (I like what other Rust stuff, such as Rustnomicon, uses, not sure what it is.)
• One of us sets up a repository with an intro page and some example page
• Whenever anyone of us feels like adding a chapter, he makes a PR