doc/descriptors.md tweaks #14161

ryanofsky · 2018-09-06T14:05:12Z

Add some implementation details, and tweak phrasing in examples section to be more explicit about how expressions are used for matching.

Add some implementation details, and tweak phrasing in examples section to be more explicit about how script expressions are used for matching.

practicalswift · 2018-09-06T21:25:54Z

Concept ACK

sipa · 2018-09-06T21:38:47Z

doc/descriptors.md

+
+### Output Descriptors vs. Addresses
+
+Like a bitcoin address, a bitcoin output descriptor can be used as a human


I think this is not a similarity but a difference: an address does not (generally) convey information on how to spend it; a descriptor does (unless raw or addr are used).

Yeah, this sentence would probably be clearer dropping "that a given wallet knows how to spend" from the end. The difference you are describing is basically difference #1 in the list below.

But I think it might be a good idea to drop this section entirely. Basically I was trying to describe the properties of descriptors by contrasting them with addresses. But I think it might be better to have a section just describing some ways descriptors can be used (internally or externally), since this is something actually I'm fuzzy on.

I suspect this will clear itself up when more uses for descriptors appear.

Ok, just dropped this section. Pushed to ryanofsky@9592a1b for reference.

sipa · 2018-09-06T21:41:55Z

doc/descriptors.md

- `pk(xpub661MyMwAqRbcFtXgS5sYJABqqG9YLmC4Q1Rdap9gSE8NqtwybGhePY2gZ29ESFjqJoCu1Rupje8YtGqsefD265TMg7usUDFdp6W1EGMcet8)` refers to a single P2PK output, using the public key part from the specified xpub.
- `pkh(xpub68Gmy5EdvgibQVfPdqkBBCHxA5htiqg55crXYuXoQRKfDBFA1WEjWgP6LHhwBZeNK1VTsfTFUHCdrfp1bgwQ9xv5ski8PX9rL2dZXvgGDnw/1'/2)` refers to a single P2PKH output, using child key *1'/2* of the specified xpub.
- `wsh(multi(1,xpub661MyMwAqRbcFW31YEwpkMuc5THy2PSt5bDMsktWQcFF8syAmRUapSCGu8ED9W6oDMSgv6Zz8idoc4a6mr8BDzTJY47LJhkJ8UB7WEGuduB/1/0/*,xpub69H7F5d8KSRgmmdJg2KhpAK8SR3DjMwAdkxj3ZuxV27CprR9LgpeyGmXUbC6wb7ERfvrnKZjXoUmmDznezpbZb7ap6r1D3tgFxHmwMkQTPH/1/0/*))` refers to a chain of *1-of-2* P2WSH multisig outputs, using public keys taken from two HD chains with corresponding derivation paths.
+- `pk(0279be667ef9dcbbac55a06295ce870b07029bfcdb2dce28d959f2815b16f81798)` matches a P2PK output with the specified public key.


I haven't really thought of descriptors as "filters" that match certain sPK, more as compact descriptions for specifically instantiated scripts.

Perhaps it makes sense to describe it this way (especially in the context of scantxoutset), but perhaps it is also confusing. It may make people wonder why a range needs to be explicitly specified, or why an addr(1...) can't match a P2PK output.

What do you think?

Well, these edits are just suggestions. I'm happy to revert anything or change it however you'd like.

But I guess I don't really get the point about BIP32 ranges and addr() with P2PK, because it seems like you have to document the behavior either way. And in theory if we wanted to match P2PK keys & hashes, it wouldn't actually complicate the current implementation very much.

I like saying "matches" here just because "matches" is concrete. It seems clearer to say that a descriptor either "matches" or "doesn't match" a script than to say that it "represents," or "refers," or sometimes "constructs" one. But if you wanted to replace "matches" with a different concrete term like "generates" or "constructs" everywhere, I think that would be good, too.

Ah, perhaps this isn't clear from the current implementation yet.

One of the original goals was to have an explicit representation for the actual set of scriptPubKeys that match the wallet. This would permit much faster rescans, as it avoids the need to feed every scriptPubKey seen in the chain through the IsMine machinery, and instead just test for inclusion in a set. Alternatively, it permits even faster structures such as using a bloom filter for the wallet, or using the BIP158 filters for blocks.

Having functionality in the descriptors language which just specifies a pubkey hash but encompasses P2PK outputs is not compatible with that intended feature.

Does that clear things up? If you think using the term 'matches' doesn't convey the wrong meaning taking that into account I'm fine with it.

Replaced "matches" with a "describes" in a followup commit.

After hearing about plans for the wallet, I think I now agree "matches scriptingPubKeys" is too narrow, since we're not only going to use descriptors as a way of matching tx outputs, but also as a way of generating outputs and addresses (by replacing keypools in the wallet, and serving as a bridge between wallet and the "policy language" you described at coredev).

Having functionality in the descriptors language which just specifies a pubkey hash but encompasses P2PK outputs is not compatible with that intended feature.

I didn't know about the bloom filtering idea, and I see how this does impose constraints on the types of scriptPubKeys that could be matched efficiently. I think it doesn't really have bearing on how you document the descriptor language, though. For example, we talk about matching regexes despite the fact that regex languages are limited and won't match many string patterns.

sipa · 2018-09-06T21:42:45Z

doc/descriptors.md

 multisig policy, where any *k* out of the *n* provided public keys must
 sign.

+Key order is significant. A `multi()` expression will only match multisig


Big +1 on this section; that information was really missing.

maflcko · 2018-09-30T01:13:17Z

Is this for 0.17.0? It seems it still needs some more work or feedback addressed?

sipa · 2018-10-17T07:59:15Z

@ryanofsky Ping, what do you think about my comments above?

ryanofsky

Updated bce4db1 -> eeeaa29 (pr/ddoc.3 -> pr/ddoc.4) dropping address section and replacing "matches" with "describes".

ryanofsky · 2018-10-17T16:20:48Z

doc/descriptors.md

- `pk(xpub661MyMwAqRbcFtXgS5sYJABqqG9YLmC4Q1Rdap9gSE8NqtwybGhePY2gZ29ESFjqJoCu1Rupje8YtGqsefD265TMg7usUDFdp6W1EGMcet8)` refers to a single P2PK output, using the public key part from the specified xpub.
- `pkh(xpub68Gmy5EdvgibQVfPdqkBBCHxA5htiqg55crXYuXoQRKfDBFA1WEjWgP6LHhwBZeNK1VTsfTFUHCdrfp1bgwQ9xv5ski8PX9rL2dZXvgGDnw/1'/2)` refers to a single P2PKH output, using child key *1'/2* of the specified xpub.
- `wsh(multi(1,xpub661MyMwAqRbcFW31YEwpkMuc5THy2PSt5bDMsktWQcFF8syAmRUapSCGu8ED9W6oDMSgv6Zz8idoc4a6mr8BDzTJY47LJhkJ8UB7WEGuduB/1/0/*,xpub69H7F5d8KSRgmmdJg2KhpAK8SR3DjMwAdkxj3ZuxV27CprR9LgpeyGmXUbC6wb7ERfvrnKZjXoUmmDznezpbZb7ap6r1D3tgFxHmwMkQTPH/1/0/*))` refers to a chain of *1-of-2* P2WSH multisig outputs, using public keys taken from two HD chains with corresponding derivation paths.
+- `pk(0279be667ef9dcbbac55a06295ce870b07029bfcdb2dce28d959f2815b16f81798)` matches a P2PK output with the specified public key.


Replaced "matches" with a "describes" in a followup commit.

After hearing about plans for the wallet, I think I now agree "matches scriptingPubKeys" is too narrow, since we're not only going to use descriptors as a way of matching tx outputs, but also as a way of generating outputs and addresses (by replacing keypools in the wallet, and serving as a bridge between wallet and the "policy language" you described at coredev).

Having functionality in the descriptors language which just specifies a pubkey hash but encompasses P2PK outputs is not compatible with that intended feature.

I didn't know about the bloom filtering idea, and I see how this does impose constraints on the types of scriptPubKeys that could be matched efficiently. I think it doesn't really have bearing on how you document the descriptor language, though. For example, we talk about matching regexes despite the fact that regex languages are limited and won't match many string patterns.

ryanofsky · 2018-10-17T16:46:44Z

doc/descriptors.md

+
+### Output Descriptors vs. Addresses
+
+Like a bitcoin address, a bitcoin output descriptor can be used as a human


Ok, just dropped this section. Pushed to ryanofsky@9592a1b for reference.

sipa · 2018-10-17T19:07:20Z

utACK

jonasschnelli · 2018-10-17T19:36:30Z

utACK eeeaa29

DrahtBot · 2018-10-20T10:29:03Z

Reviewers, this pull request conflicts with the following ones:

Add ability to convert solvability info to descriptor #14477 (Add ability to convert solvability info to descriptor by sipa)
Add key origin support to descriptors #14150 (Add key origin support to descriptors by sipa)

If you consider this pull request important, please also help to review the conflicting pull requests. Ideally, start with the one that should be merged first.

eeeaa29 descriptors.md: Refer to descriptors as describing instead of matching (Russell Yanofsky) eb49412 doc/descriptors.md tweaks (Russell Yanofsky) Pull request description: Add some implementation details, and tweak phrasing in examples section to be more explicit about how expressions are used for matching. Tree-SHA512: a9dc7bc0fc370548189a789f31c04bd11103cdd2a99bcb909fa1b1dfa4e78509813dad5d5c9e3db98d66929f45cb5704f5c46ab4cbd800fef22cd8465f80ef33

Add some implementation details, and tweak phrasing in examples section to be more explicit about how script expressions are used for matching. Github-Pull: bitcoin#14161 Rebased-From: eb49412

Github-Pull: bitcoin#14161 Rebased-From: eeeaa29

Add some implementation details, and tweak phrasing in examples section to be more explicit about how script expressions are used for matching. Github-Pull: bitcoin#14161 Rebased-From: eb49412

Github-Pull: bitcoin#14161 Rebased-From: eeeaa29

Summary: eeeaa29214 descriptors.md: Refer to descriptors as describing instead of matching (Russell Yanofsky) eb49412562 doc/descriptors.md tweaks (Russell Yanofsky) Pull request description: Add some implementation details, and tweak phrasing in examples section to be more explicit about how expressions are used for matching. --- Backport of Core [[bitcoin/bitcoin#14161 | PR14161]] Test Plan: read it Reviewers: #bitcoin_abc, Fabien Reviewed By: #bitcoin_abc, Fabien Subscribers: Fabien Differential Revision: https://reviews.bitcoinabc.org/D7828

doc/descriptors.md tweaks

eb49412

Add some implementation details, and tweak phrasing in examples section to be more explicit about how script expressions are used for matching.

fanquake added the Docs label Sep 6, 2018

ryanofsky force-pushed the pr/ddoc branch 2 times, most recently from b27f440 to bce4db1 Compare September 6, 2018 17:39

laanwj requested a review from sipa September 6, 2018 17:51

laanwj added this to the 0.17.0 milestone Sep 6, 2018

sipa reviewed Sep 6, 2018

View reviewed changes

fanquake added the Needs backport label Sep 11, 2018

maflcko modified the milestones: 0.17.0, 0.17.1 Sep 30, 2018

descriptors.md: Refer to descriptors as describing instead of matching

eeeaa29

ryanofsky force-pushed the pr/ddoc branch from bce4db1 to eeeaa29 Compare October 17, 2018 17:01

ryanofsky commented Oct 17, 2018

View reviewed changes

DrahtBot mentioned this pull request Oct 20, 2018

Add ability to convert solvability info to descriptor #14477

Merged

DrahtBot mentioned this pull request Oct 20, 2018

Add key origin support to descriptors #14150

Merged

maflcko merged commit eeeaa29 into bitcoin:master Oct 21, 2018

maflcko removed the Needs backport label Oct 21, 2018

maflcko pushed a commit to maflcko/bitcoin-core that referenced this pull request Oct 25, 2018

descriptors.md: Refer to descriptors as describing instead of matching

703a244

Github-Pull: bitcoin#14161 Rebased-From: eeeaa29

toxeus pushed a commit to toxeus/bitcoin that referenced this pull request Nov 28, 2018

descriptors.md: Refer to descriptors as describing instead of matching

5dd3919

Github-Pull: bitcoin#14161 Rebased-From: eeeaa29

bitcoin locked as resolved and limited conversation to collaborators Sep 8, 2021


		### Output Descriptors vs. Addresses

		Like a bitcoin address, a bitcoin output descriptor can be used as a human

doc/descriptors.md tweaks #14161

doc/descriptors.md tweaks #14161

Uh oh!

Conversation

ryanofsky commented Sep 6, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

practicalswift commented Sep 6, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sipa Oct 12, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

maflcko commented Sep 30, 2018

Uh oh!

sipa commented Oct 17, 2018

Uh oh!

ryanofsky left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sipa commented Oct 17, 2018

Uh oh!

jonasschnelli commented Oct 17, 2018

Uh oh!

DrahtBot commented Oct 20, 2018

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

9 participants

ryanofsky commented Sep 6, 2018 •

edited

Loading

practicalswift commented Sep 6, 2018 •

edited

Loading

sipa Oct 12, 2018 •

edited

Loading