Use Terms "Pubkey Script" And "Signature Script"

[harding]

This modifies two commits provided by @petertodd in #563 to use the terms "pubkey script" and "signature script" instead of other terms.

• Rename "scriptPubKey" and "output script" to "pubkey script" (suggested by @luke-jr). We leave a token "scriptPubKey" at the point where we define pubkey script so that searchers can find it.
• Rename "scriptSig" to "signature script" (suggested by @luke-jr). We also leave a token "scriptSig" at this definition point.
• Rename "redeemScript" to "redeem script"
• Defined ECDSA on secp256k1 curve as the crypto used and added references to secp256k1 private/public keys and signatures.
• Removed "The Parts Of A Transaction" illustration by commenting it out in the HTML. Shoehorning the pubkey/signature script terms into it was becoming difficult, and I'm not very fond of that illustration anyway. I'll see if I can think of a nicer replacement illustration.
• Add a short paraphrased version @petertodd's description of scripts as generalized crypto. The exact sentence is: "Pubkey scripts and signature scripts combine secp256k1 pubkeys and signatures with conditional logic, creating a programable authorization mechanism."
• Updated all the illustrations which referred to either pubkey scripts or signature scripts.

[petertodd]

I don't agree with this at all, and I think you're missing my point on terminology here.

So where this came up is I'm right now working with a client and their developers on a new Bitcoin using project, a fairly technical one involving a lot of low level details. The people involved are all experienced devs, including crypto, but their prior knowledge of Bitcoin was lacking. I'd recommended that they read the bitcoin.org dev docs as well as the Satoshi code, and also sent them a Bitcoin-using library I had written for them.

To make a long story short, the result was a bunch of devs who were very confused at what on earth the dev documentation was talking about and why there was so little commonality between it and the Bitcoin Core codebase, and for that matter, various bitcoin-dev and bitcoin-wizards chat logs I'd sent them, as well as mailing list messages.

Thing is, the terminology already is in use - the Bitcoin Core codebase has used it for years, as has the dev community. Trying to change it now is silly and just keeps people confused; sticking with the highly specific "scriptPubKey", "scriptSig", "redeemScript", etc. may be "ugly" and conform to naming conventions that aren't used that much, but in the context of Bitcoin those unique names mean what you're talking about is 100% clear.

[harding]

I guess I am missing your point---I'm having a hard time seeing how "pubkey script" is significantly different than "scriptPubKey". Ditto for the other terms---"redeem script" is even identical to "redeemScript" except for space and capitalization.

Using terms in their grammatical order---pubkey script---seems to me like it would aid comprehensibility to a significant enough degree to offset any slight ambiguity introduced by not using the exact terms used in RPC calls and developer shorthand.

[petertodd]

See, "pubkey script" can be parsed in more than one way because it's two words; scriptPubKey is the more specific concept, and matches the source code exactly. And essentially everywhere where my pull-req uses terms like scriptPubKey it's in the context of talking about actual transactions, which have actual data structures with fields called scriptPubKey and similar in the Bitcoin Core codebase. Similarly other libraries have copied those terms exactly, e.g. bitcoinj and python-bitcoinlib.

After all, ultimately the definition of the Bitcoin Protocol is the sourcecode everyone is running.

[harding]

I fully agree that the two-word phrasing creates ambiguity when the reader encounters the one-word phrasing used elsewhere. But I also think that the two-word phrasing makes the document easier to read.

It seems to me that the question is whether the harm from the ambiguity does more damage than the benefit of easy reading. Since there's no easy way to test that---and this is too minor an issue to bother anyway---we can only make guesses based on our past experiences.

My experience as a technical writer tells me the ambiguity here is minor and the comprehensibility benefit is modest, so I favor the two-word phrasing. I'm guessing your experience as a programmer tells you roughly the reverse.

I suggest we let other people express their opinion for a few days---say until 23:59 Monday (UTC)---and then take stock of the situation.

If there's no clear resolution by then, we can do what we've done here in the past to avoid bike shedding on minor issues---let a figurative coin flip decide the answer. (We've chosen a block height soon to be reached and then declared that if its hash resolves to an odd number we do X; if its hash is even, we do Y.)

[saivann]

I too agree that @harding / @luke-jr suggestion is more readable while @petertodd suggestion is more in line with the codebase. FWIW, I tend to have a small preference toward readability since the suggested terms are now very close to those used in the codebase, which makes it a good compromise IMO.

[petertodd]

@harding Haha! I like the blockchain coinflip idea - reminds me I've been meaning to write up the ten lines of code or so to do such flips properly, such that no one miner can bias them. (obviously a somewhat theoretical problem in this case!)

[harding]

Not many comments on this---but among those who have commented, the two-word terms seem to be favored (although most have only a weak preference).

• @saivann: "I tend to have a small preference toward [the two-word terms]"
• @luke-jr: "Probably it would be ideal to just refer to 'pubkeys' and 'signatures' [...or...] Maybe being more verbose with 'pubkey script' and 'signature script'"
• @harding (me): "I favor the two-word phrasing."
• @petertodd: "I don't agree with [using the two-word terms] at all"

Based on that, I'd like to proceed with this pull request implementing the two-word terms. If the terms prove more confusing than anticipated, we can open a new issue later.

@petertodd: as the opposition to this pull, does that seem reasonable to you?

[saivann]

Yes, let's merge this pull request. @harding have already spent required time to make a working pull req based on comments, and the proposed change is better than what we had before. I don't think changing every word again is worth your time unless enough people really think it's better, in which case they can provide the pull request and this can be merged later too.

[petertodd]

ACK

You know, the least controversial way to address this confusion later might be to point out the half dozen terms for the same thing in the glossary!

[harding]

@petertodd we don't actually have a glossary, but we've discussed creating one. I reopened that discussion on the -docs mailing list. Thanks again for helping us improve the terminology!

And thanks @saivann and @luke-jr for the comments and suggestions; I'll be merging this momentarily.