What needs doing?

[futurepaul]

Just heard about this on the noded podcast and it sounds like a really cool / worthwhile project! What sort of work needs to be done? I'm familiar with Rust and web development but not with Bitcoin Script.

[apoelstra]

The biggest things right now are

• missing documentation (including a TODO list :))
• more usage/review - there's been a steady trickle of "this constant is wrong for this policy that you didn't test in real life" bugs

It would also be good to have an "interpreter" of sorts which could take a completed witness and describe which branches of the script were actually used (which would make the "accountability" of CHECKMULTISIG actually usable). @sanket1729 is working on this.

Will leave this bug open until the README has a reasonably complete list of open problems.

[futurepaul]

Sounds good! I'm working through the library to see if I can understand it well enough to write some documentation.

One problem I've had is with converting Script to Miniscript. Is that not fully supported right now? For instance, parsing a p2pkh script results in this error: Unexpected("EqualVerify"). It looks like the fuzztest for this would fail silently, because it's an if let.

[apoelstra]

p2pkh scriptpubkeys are not miniscripts. There isn't any fuzztest for deciding which scripts are miniscripts, because creating such a thing would be equivalent to rewriting the library :)

[apoelstra]

Let me expound on that a bit - there are two things at play here and their relationship is a bit confusing.

• There is miniscript, which is defined more-or-less at http://bitcoin.sipa.be/miniscript/miniscript.html and supports only signatures, hashlocks, timelocks, and combinations of these. Miniscript has no notion of pubkey hashes.
• Then there are descriptors, which are https://github.com/bitcoin/bitcoin/blob/master/doc/descriptors.md, which describe how Miniscripts are embedded in the blockchain (and also include some non-miniscript things, such as pay-to-pubkeyhash).

So if you have a p2pkh output, this corresponds to a descriptor of the form pkh(<public key>). It would be nice if, given a scriptpubkey, you could parse it as a descriptor, but unfortunately this is impossible because the scriptpubkey has only a hash of <public key> and the descriptor includes the actual public key.

[futurepaul]

This is helpful, I was definitely confusing descriptors with miniscript in my last example.

I'm still confused about what is actually possible to parse, though. I tried to roundtrip the example on the miniscript.html page and(pk(C),or(pk(C),aor(pk(C),time(1000)))) and I get Unexpected("NotIf") when I try to parse it.

[apoelstra]

What you posted there is not a miniscript but a policy :). A miniscript is the output of the compiler.

Also, it wouldn't surprise me if the Script output by that webpage is somehow wrong; Pieter created that as a proof-of-concept, whereas this library is designed for production use.

[futurepaul]

Here's what I have so far: examples. I wouldn't quite call it documentation, more like a list of things that I've managed to do with miniscript so far. If you have any more idiomatic usage or examples I'd love to see them! I note all the places where I don't really know what I'm doing, including an assert at the end that doesn't quite work.

[sanket1729]

Hey Paul, I have answered some of your questions in the gist. Let me know if there is something still unclear.

[futurepaul]

I've updated the gist with a new example and a couple more questions.

After attempting to understand witnesses a bit better... I still do not understand witnesses! So an idiomatic witness example would be helpful.

What format would you ideally like documentation to be in? My inclination would be an examples directory, but I could also attempt a simple readme example or inline examples for cargo doc if that's more important.

[apoelstra]

I think an examples directory would be more helpful than cargo doc examples, for a project of this complexity.

I'm not sure how to respond to "I still do not understand witnesses" :). Conceptually, witnesses are just signatures - abstractly, they're extra data that prove that the spending conditions were satisfied.

[apoelstra]

Closing this issue; opened several "feature request" issues with specific things.