P2WSH docs are confusing

[TheBlueMatt]

I've generally always seen the witness-redeem-script either referred to as simply "redeem script" or "witness redeemScript" or similar, but the SegWit Wallet Dev guide says "witnessScript" (which is easy to confuse with "scriptWitness" the variable name in Bitcoin Core for the full witness). Thus, I'd strongly suggest we use simply "redeem script" at https://bitcoincore.org/en/segwit_wallet_dev/#creation-of-p2sh-p2wsh-address

[TheBlueMatt]

CC rust-bitcoin/rust-bitcoin#109

[apoelstra]

"witnessScript" is also used throughout BIP141. e.g. https://github.com/bitcoin/bips/blob/master/bip-0141.mediawiki#P2WPKH

"redeem script" as used in P2SH always refers to script that appears in a transaction scriptSig while the preimage to the hash in a witness program always appears in the transaction witness. In the nested p2sh form of segwit, both scripts may appear. They are different scripts that appear in different locations and are treated differently by the script interpreter, so it makes sense that they would have different names.

The word "redeem" does not even appear in BIP 141, so it's news to me that people are using it to refer to the preimage of a witness program. Edit: apparently my firefox cannot do text searches of BIP141 unless I copy and paste words into the search box. redeemScript does appear several times, but it's consistent with my understanding of the term (that it is purely a BIP16 thing). See https://github.com/bitcoin/bips/blob/master/bip-0141.mediawiki#witness-program

[fivepiece]

IMO it would be best to use a term like "witnessScript" for a couple of reasons

• Segwit transactions can already contain a redeemScript part, eg p2sh-p2wsh, so "redeem script" and even "witness redeem script" can become confusing.
• An unambiguous term makes using a search engine to find relevant hits more convenient, and "scriptWitness" is easily distinguished from "witnessScript" by one. DDG's first hit for "scriptWitness" is for the src/primitives/transaction.h file, while "witnessScript bitcoin" returns the segwit wallet dev page on bitcoincore.org

Personally I'm for witnessScript

[TheBlueMatt]

Could also use "witness program" which is clearly separate from scriptWitness, a variable name which refers to the entire witness object in Bitcoin Core. Also, further confusing is that its easy to see the witness as a replacement for the scriptSig (though that's not entirely accurate due to it being a list of pushes, not an executed script), at which point scriptWitness/witnessScript would be easy to assume referred to the full witness.

[apoelstra]

"witness program" is defined in BIP 141 to be only the output script.

[sipa]

• scriptWitness = the witness for a script (= the entire witness stack)
• witnessScript = the script in a witness (= the last stack element for P2WSH)
• witness program = a program to which witness validation rules apply (= the OP_n + hash push which goes into the scriptPubKey or P2SH redeemscript).

I wouldn't mind renaming witnessScript to P2WSH redeemscript if that's less confusing.

[dongcarl]

@sipa I like the idea of calling it P2WSH redeemscript... Trivial for people learning to understand the relationship:

P2SH: P2SH redeemscript
P2WSH: P2WSH redeemscript

However, perhaps it would require some disambiguation changes in the docs to specify "P2SH redeemscript" instead of just "redeemscript?

[bullsandbears]

@sipa Ich mag die Idee, > Vielleicht würde es jedoch einige Begriffsklärungsänderungen in den Dokumenten erfordern, um "P2SH redeemscript" anstelle von nur "redeemscript" anzugeben.
das würde es sicher übersichtlicher machen und kompakter zu erlernen

[kanzure]

Can someone spot check this commit I made? petertodd/python-bitcoinlib@e311d27