Skip to content

Add reference documentation for descriptors language #14096

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Merged
merged 3 commits into from
Sep 6, 2018
Merged

Add reference documentation for descriptors language #14096

merged 3 commits into from
Sep 6, 2018

Conversation

sipa
Copy link
Member

@sipa sipa commented Aug 28, 2018

No description provided.

@sipa
Copy link
Member Author

sipa commented Aug 28, 2018

In case there is another 0.17 RC, this should probably be included (the RPC help still says "documentation at TODO").

@sipa sipa added this to the 0.17.0 milestone Aug 28, 2018
practicalswift
practicalswift reviewed Aug 28, 2018
View reviewed changes
doc/descriptors.md Outdated
- `sh(SCRIPT)` (toplevel only): P2SH embed the argument.
- `wsh(SCRIPT)` (not inside another 'wsh'): P2WSH embed the argument.
- `pk(PUBKEY)` (anywhere): P2PK output for the given public key.
- `pkh(PUBKEY)` (anywhere): P2PKH output for the given public key (use `addr` if you only thos the pubkey hash).
Copy link
Contributor

@practicalswift practicalswift Aug 28, 2018 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Typo: "thos" :-)

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed.

practicalswift
practicalswift reviewed Aug 28, 2018
View reviewed changes
doc/descriptors.md Outdated
Public keys:
- Hex encoded public keys (66 characters starting with `02` or `03`, or 130 characters starting with `04`).
- Inside `wpkh` and `wsh`, only compressed public keys are permitted.
- WIF encoded private keys, whose denote their corresponding public keys.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should "whose" be "which" here?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed.

@practicalswift
Copy link
Contributor

FWIW, codespell catched the "thos" typo :-)

See #13954 for codespell integration: Warn (don't fail!) on spelling errors. Fix typos reported by codespell

practicalswift
practicalswift reviewed Aug 28, 2018
View reviewed changes
doc/descriptors.md Outdated
`scantxoutset` RPC call. This is a simple language which can be used to
describe collections of output scripts.

This document describes the language. For the specfics on usage for scanning
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Typo: "specfics"

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed.

practicalswift
practicalswift reviewed Aug 28, 2018
View reviewed changes
doc/descriptors.md Outdated
## Quick reference

Scripts:
- `sh(SCRIPT)` (toplevel only): P2SH embed the argument.
Copy link
Contributor

@practicalswift practicalswift Aug 28, 2018 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nit: "toplevel" should probably be "top level" (applies throughout), no?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done.

practicalswift
practicalswift reviewed Aug 28, 2018
View reviewed changes
doc/descriptors.md Outdated

### Multisig

Several pieces of software use multisignature scripts based on Bitcoin's OP_CHECKMULTISIG opcode. To support these, we introduce the `multi(k,key_1,key_2,...,key_n)` function. It represents a *k-of-n* multisig policy, where any *k* out of the *n* provided public keys must sign. Examples:
Copy link
Contributor

@practicalswift practicalswift Aug 28, 2018 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nit: "multisignature" should be "multi signature" or "multisig"?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done.

@practicalswift
Copy link
Contributor

Excellent documentation! Great work as always!

ACK f1665448a3d6ae244e36a74a311b27db4e4144a5 modulo nits

@practicalswift
Copy link
Contributor

ACK db7ebf0f45a62f685375ce80a0a8ea57420b0ab0

@maflcko
Copy link
Member

maflcko commented Aug 29, 2018

utACK db7ebf0f45a62f685375ce80a0a8ea57420b0ab0

instagibbs
instagibbs reviewed Aug 29, 2018
View reviewed changes
flack
flack reviewed Aug 29, 2018
View reviewed changes
flack
flack reviewed Aug 29, 2018
View reviewed changes
instagibbs
instagibbs reviewed Aug 29, 2018
View reviewed changes
flack
flack reviewed Aug 29, 2018
View reviewed changes
@jonasschnelli jonasschnelli mentioned this pull request Aug 30, 2018
Closed
@Sjors Sjors mentioned this pull request Sep 4, 2018
Closed
ryanofsky
ryanofsky approved these changes Sep 5, 2018
View reviewed changes
Copy link
Contributor

@ryanofsky ryanofsky left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ACK 843bc92035bfcfa4327b5400b3a722ad6df393ec

doc/descriptors.md Outdated

Many single-key constructions are used in practice, generally including P2PK, P2PKH, P2WPKH, and P2SH-P2WPKH. Many more combinations are imaginable, though they may not be optimal: P2SH-P2PK, P2SH-P2PKH, P2WSH-P2PK, P2WSH-P2PKH, P2SH-P2WSH-P2PK, P2SH-P2WSH-P2PKH.

To describe these, we model these as functions. The functions `pk` (P2PK), `pkh` (P2PKH) and `wpkh` (P2WPKH) take as input a public key in hexadecimal notation, and return the corresponding *scriptPubKey*. The functions `sh` (P2SH) and `wsh` (P2WSH) take as input a script, and return the script describing P2SH and P2WSH outputs with the input as embedded script. The names of the functions do not contain "p2" for brevity. Examples:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"take as input a public key in hexadecimal notation"

Maybe clarify these don't only take hexadecimal notation (since they should accept any KEY expressions).

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The explanation section builds things up step-by-step; I think it's more helpful to not give all information at once. I've instead added "which will be extended later", is that ok?

doc/descriptors.md Outdated

### Including private keys

Often it is useful to communicate a description of scripts along with the necessary private keys. For this reason, anywhere a public key or xpub is supported, a private key (in WIF format) or xprv may be provided instead. This may be useful for dumping wallet descriptors including private key material.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Seems inconsistent to parenthesize mention of WIF format but not xprv format. It might also be good to say in this section that xprv format is specified in BIP32.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done (I've added the link higher up).

@sipa
Copy link
Member Author

sipa commented Sep 5, 2018

Restructured the document, reformatted the markdown, and added a number of links.

flack
flack reviewed Sep 5, 2018
View reviewed changes
ryanofsky
ryanofsky reviewed Sep 5, 2018
View reviewed changes
Copy link
Contributor

@ryanofsky ryanofsky left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

reACK 2b5d6f8, various changes since last review including some suggested changes and also adding links to more documentation

@ken2812221
Copy link
Contributor

utACK 2b5d6f8

@practicalswift
Copy link
Contributor

utACK 2b5d6f8

laanwj pushed a commit that referenced this pull request Sep 6, 2018
@sipa @laanwj
Add descriptor reference documentation
0f681ce 
Github-Pull: #14096
Rebased-From: 9254ffc
Tree-SHA512: 1fc466177dbe3b57b0025c102b1e75e4b05544440819885da7a85b70d20329fc3f6f4cbf89d7d6a48881e6ad176d81f7396f02925586140e19468a2f28f3414e
laanwj pushed a commit that referenced this pull request Sep 6, 2018
@sipa @laanwj
Adjust TODO link
eece974 
Github-Pull: #14096
Rebased-From: 89709db
Tree-SHA512: 0bf74e1179bee6e616d8fd2c125411ef30611d9aa3b32412025615a793abbc629a7b6d89a89ef05b11ac3541cc869c0caebba2d00942fdd6ab8d2e98d9b9caca
laanwj pushed a commit that referenced this pull request Sep 6, 2018
@sipa @laanwj
Replace duplcate reference with reference to reference doc
465a583 
Github-Pull: #14096
Rebased-From: 2b5d6f8
Tree-SHA512: 79af808c581ebb17d60aab8322b1debcc4182480b84eaedcbfac1e67c8b543c61df22789095742d67d732dba35e7e5fad77912385b695f89fb0f44f75db11560
@laanwj laanwj merged commit 2b5d6f8 into bitcoin:master Sep 6, 2018
laanwj added a commit that referenced this pull request Sep 6, 2018
@laanwj
Merge #14096: Add reference documentation for descriptors language
35d7d94 
2b5d6f8 Replace duplcate reference with reference to reference doc (Pieter Wuille)
89709db Adjust TODO link (Pieter Wuille)
9254ffc Add descriptor reference documentation (Pieter Wuille)

Pull request description:

Tree-SHA512: 1ca0d537f9bcbb23266e9a4a02a60013ef8309958fb701f638283887585b5ddea6bc9dab859454ec3a373b1a12a4fd69836e7030417bb2ca43fef26b104c0d65
@laanwj
Copy link
Member

laanwj commented Sep 6, 2018

backported to 0.17 in 465a583 eece974 0f681ce

HashUnlimited pushed a commit to HashUnlimited/chaincoin that referenced this pull request Sep 14, 2018
@sipa
Add descriptor reference documentation
16bd722 
Github-Pull: bitcoin#14096
Rebased-From: 9254ffc
Tree-SHA512: 1fc466177dbe3b57b0025c102b1e75e4b05544440819885da7a85b70d20329fc3f6f4cbf89d7d6a48881e6ad176d81f7396f02925586140e19468a2f28f3414e
HashUnlimited pushed a commit to HashUnlimited/chaincoin that referenced this pull request Sep 14, 2018
@sipa
Adjust TODO link
902a3b4 
Github-Pull: bitcoin#14096
Rebased-From: 89709db
Tree-SHA512: 0bf74e1179bee6e616d8fd2c125411ef30611d9aa3b32412025615a793abbc629a7b6d89a89ef05b11ac3541cc869c0caebba2d00942fdd6ab8d2e98d9b9caca
@HashUnlimited HashUnlimited mentioned this pull request Sep 14, 2018
Merged
HashUnlimited pushed a commit to HashUnlimited/chaincoin that referenced this pull request Sep 14, 2018
@sipa
Replace duplcate reference with reference to reference doc
d00d14a 
Github-Pull: bitcoin#14096
Rebased-From: 2b5d6f8
Tree-SHA512: 79af808c581ebb17d60aab8322b1debcc4182480b84eaedcbfac1e67c8b543c61df22789095742d67d732dba35e7e5fad77912385b695f89fb0f44f75db11560
@HashUnlimited HashUnlimited mentioned this pull request Sep 14, 2018
Merged
@Bushstar Bushstar mentioned this pull request Oct 11, 2018
Merged
uhliksk pushed a commit to fxtc/fxtc that referenced this pull request Oct 18, 2018
@sipa @uhliksk
Add descriptor reference documentation
bdc26c5 
Github-Pull: bitcoin#14096
Rebased-From: 9254ffc
Tree-SHA512: 1fc466177dbe3b57b0025c102b1e75e4b05544440819885da7a85b70d20329fc3f6f4cbf89d7d6a48881e6ad176d81f7396f02925586140e19468a2f28f3414e
uhliksk pushed a commit to fxtc/fxtc that referenced this pull request Oct 18, 2018
@sipa @uhliksk
Adjust TODO link
a3da46b 
Github-Pull: bitcoin#14096
Rebased-From: 89709db
Tree-SHA512: 0bf74e1179bee6e616d8fd2c125411ef30611d9aa3b32412025615a793abbc629a7b6d89a89ef05b11ac3541cc869c0caebba2d00942fdd6ab8d2e98d9b9caca
uhliksk pushed a commit to fxtc/fxtc that referenced this pull request Oct 18, 2018
@sipa @uhliksk
Replace duplcate reference with reference to reference doc
dbd5578 
Github-Pull: bitcoin#14096
Rebased-From: 2b5d6f8
Tree-SHA512: 79af808c581ebb17d60aab8322b1debcc4182480b84eaedcbfac1e67c8b543c61df22789095742d67d732dba35e7e5fad77912385b695f89fb0f44f75db11560
Munkybooty pushed a commit to Munkybooty/dash that referenced this pull request Sep 10, 2021
@laanwj @Munkybooty
Merge bitcoin#14096: Add reference documentation for descriptors lang…
e42d401 
…uage

2b5d6f8 Replace duplcate reference with reference to reference doc (Pieter Wuille)
89709db Adjust TODO link (Pieter Wuille)
9254ffc Add descriptor reference documentation (Pieter Wuille)

Pull request description:

Tree-SHA512: 1ca0d537f9bcbb23266e9a4a02a60013ef8309958fb701f638283887585b5ddea6bc9dab859454ec3a373b1a12a4fd69836e7030417bb2ca43fef26b104c0d65
Munkybooty pushed a commit to Munkybooty/dash that referenced this pull request Sep 12, 2021
@laanwj @Munkybooty
Merge bitcoin#14096: Add reference documentation for descriptors lang…
dbb5abe 
…uage

2b5d6f8 Replace duplcate reference with reference to reference doc (Pieter Wuille)
89709db Adjust TODO link (Pieter Wuille)
9254ffc Add descriptor reference documentation (Pieter Wuille)

Pull request description:

Tree-SHA512: 1ca0d537f9bcbb23266e9a4a02a60013ef8309958fb701f638283887585b5ddea6bc9dab859454ec3a373b1a12a4fd69836e7030417bb2ca43fef26b104c0d65
UdjinM6 pushed a commit to UdjinM6/dash that referenced this pull request Sep 15, 2021
@laanwj @Munkybooty
Merge bitcoin#14096: Add reference documentation for descriptors lang…
e5cdf55 
…uage

2b5d6f8 Replace duplcate reference with reference to reference doc (Pieter Wuille)
89709db Adjust TODO link (Pieter Wuille)
9254ffc Add descriptor reference documentation (Pieter Wuille)

Pull request description:

Tree-SHA512: 1ca0d537f9bcbb23266e9a4a02a60013ef8309958fb701f638283887585b5ddea6bc9dab859454ec3a373b1a12a4fd69836e7030417bb2ca43fef26b104c0d65
Munkybooty pushed a commit to Munkybooty/dash that referenced this pull request Sep 15, 2021
@laanwj @Munkybooty
Merge bitcoin#14096: Add reference documentation for descriptors lang…
b1d47a6 
…uage

2b5d6f8 Replace duplcate reference with reference to reference doc (Pieter Wuille)
89709db Adjust TODO link (Pieter Wuille)
9254ffc Add descriptor reference documentation (Pieter Wuille)

Pull request description:

Tree-SHA512: 1ca0d537f9bcbb23266e9a4a02a60013ef8309958fb701f638283887585b5ddea6bc9dab859454ec3a373b1a12a4fd69836e7030417bb2ca43fef26b104c0d65
Munkybooty pushed a commit to Munkybooty/dash that referenced this pull request Sep 15, 2021
@laanwj @Munkybooty
Merge bitcoin#14096: Add reference documentation for descriptors lang…
c2428c4 
…uage

2b5d6f8 Replace duplcate reference with reference to reference doc (Pieter Wuille)
89709db Adjust TODO link (Pieter Wuille)
9254ffc Add descriptor reference documentation (Pieter Wuille)

Pull request description:

Tree-SHA512: 1ca0d537f9bcbb23266e9a4a02a60013ef8309958fb701f638283887585b5ddea6bc9dab859454ec3a373b1a12a4fd69836e7030417bb2ca43fef26b104c0d65
Munkybooty pushed a commit to Munkybooty/dash that referenced this pull request Sep 17, 2021
@laanwj @Munkybooty
Merge bitcoin#14096: Add reference documentation for descriptors lang…
b8a8779 
…uage

2b5d6f8 Replace duplcate reference with reference to reference doc (Pieter Wuille)
89709db Adjust TODO link (Pieter Wuille)
9254ffc Add descriptor reference documentation (Pieter Wuille)

Pull request description:

Tree-SHA512: 1ca0d537f9bcbb23266e9a4a02a60013ef8309958fb701f638283887585b5ddea6bc9dab859454ec3a373b1a12a4fd69836e7030417bb2ca43fef26b104c0d65
vijaydasmp pushed a commit to vijaydasmp/dash that referenced this pull request Sep 21, 2021
@sipa @vijaydasmp
Add descriptor reference documentation
b6963f6 
Github-Pull: bitcoin#14096
Rebased-From: 9254ffc
Tree-SHA512: 1fc466177dbe3b57b0025c102b1e75e4b05544440819885da7a85b70d20329fc3f6f4cbf89d7d6a48881e6ad176d81f7396f02925586140e19468a2f28f3414e
vijaydasmp pushed a commit to vijaydasmp/dash that referenced this pull request Sep 21, 2021
@sipa @vijaydasmp
Add descriptor reference documentation
07fc6f8 
Github-Pull: bitcoin#14096
Rebased-From: 9254ffc
Tree-SHA512: 1fc466177dbe3b57b0025c102b1e75e4b05544440819885da7a85b70d20329fc3f6f4cbf89d7d6a48881e6ad176d81f7396f02925586140e19468a2f28f3414e

Add descriptor reference documentation (dashified)
vijaydasmp pushed a commit to vijaydasmp/dash that referenced this pull request Sep 22, 2021
@sipa @vijaydasmp
Add descriptor reference documentation
e907d60 
Github-Pull: bitcoin#14096
Rebased-From: 9254ffc
Tree-SHA512: 1fc466177dbe3b57b0025c102b1e75e4b05544440819885da7a85b70d20329fc3f6f4cbf89d7d6a48881e6ad176d81f7396f02925586140e19468a2f28f3414e

Add descriptor reference documentation (dashified)
kwvg pushed a commit to kwvg/dash that referenced this pull request Oct 12, 2021
@laanwj @kwvg
Merge bitcoin#14096: Add reference documentation for descriptors lang…
a044e1a 
…uage

2b5d6f8 Replace duplcate reference with reference to reference doc (Pieter Wuille)
89709db Adjust TODO link (Pieter Wuille)
9254ffc Add descriptor reference documentation (Pieter Wuille)

Pull request description:

Tree-SHA512: 1ca0d537f9bcbb23266e9a4a02a60013ef8309958fb701f638283887585b5ddea6bc9dab859454ec3a373b1a12a4fd69836e7030417bb2ca43fef26b104c0d65
@bitcoin bitcoin locked as resolved and limited conversation to collaborators Feb 15, 2022
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Reviewers

@laanwj laanwj laanwj left review comments

@ryanofsky ryanofsky ryanofsky approved these changes

+3 more reviewers

@flack flack flack left review comments

@instagibbs instagibbs instagibbs left review comments

@practicalswift practicalswift practicalswift left review comments

Reviewers whose approvals may not affect merge requirements
Assignees
No one assigned
Labels
Docs
Projects
None yet
Milestone
0.17.0
Development

Successfully merging this pull request may close these issues.
8 participants
@sipa @practicalswift @maflcko @ken2812221 @laanwj @flack @instagibbs @ryanofsky