Crate stabilization

[tcharding]

A post to consolidate all discussion, links, PRs etc. for crate stabalization. There is an issue on each crate for crate specific discussion. This is for things that apply to stabalizing each crate or the whole process.

Tracking issue for each crate:

• bitcoinconsensus: Stabalization - roadmap to v1.0  rust-bitcoinconsensus#69
• hex: Stabalization - roadmap to v1.0 hex-conservative#43
• bech32: Stabalization - roadmap to v1.0 rust-bech32#157
• secp256k1: Stabalization - roadmap to v1.0 rust-secp256k1#662
• bitcoin: bitcoin: Stabalization - roadmap to v1.0 #2158
• hashes: hashes: Stabalization - roadmap to v1.0 #2157

Potential issues that apply to all crates:

• Make the crate conform to the API guidelines #1649
• Consistent naming of things such as as_slice, as_array... #1491
• Error refactoring #820
• Document error returns #1780
• Add a bitcoin-io crate #2066
• Push-based consensus decoding #1251

Related links

• Resolved: Green light to Stabilize `bech32` #1128
• Stabalization - roadmap to v1.0 #1392

[tcharding]

I'm no project manager by a long shot, I looked at using GitHub projects but couldn't work out a good way. If anyone wants to suggest a better way to try and co-ordinate this I'm totally open to it.

[apoelstra]

No, this seems great to me!

[tcharding]

The only problem is @Kixunil and I can only edit the original post in this repo, not in bech32 and hex so the system might not work. Can we get edit perms without becoming maintainers?

[tcharding]

I did have a look at a repo I own but did not see any such setting (I couldn't find a repo that had collaborators though).

[apoelstra]

I can make you a maintainer of secp. For hex I think you already are one.

bech32 is special because we need to go through Clark anyway before making any decisions, so I think it's okay if it's harder to directly edit the issue.

[tcharding]

I can make you a maintainer of secp.

ok, as long as that doesn't imply to anyone that I'm a cryptographer, which I'm not. I read a bunch of books on it but I didn't do a math major an uni.

[Kixunil]

I'm not really sure how much is this discussion is needed since I marked all 1.0 issues with a tag (feel free to add if some are missing). Maybe we should add those tags in other repos.

[tcharding]

Yeah this was just the central discussion place. We could/should add '1.0' label to the other repos if we want to use that method all round. The crate specific issue was intended for crate specific discussion, it will be hard not to mention general things though but if all discussion is here it will be total chaos, long threads on github are impossible to follow.

[Kixunil]

Yes, please, let's use 1.0 everywhere. Tagging is much simpler than copy-pasting things. Also this may be a good use case for project board (but that one probably has to be synced manually anyway).

[tcharding]

I had a go at using a project board recently without much success. After reading [0] I think the missing piece is milestones.

[0] https://pavlenex.com/a-quick-guide-to-creating-a-roadmap-for-an-open-source-project-in-github

[Kixunil]

The trouble with milestones is there can be only one per issue. 1.0 issues are stabilization blockers but they don't imply deadline.

[tcharding]

Oh man, I'm super glad you pointed that out and I didn't have to discover it myself.

[Kixunil]

In the light of the news that BDK is trying to stabilize, here's an idea for stabilizing important types ("entities" from "Clean Architecture"; mainly Block and it's constituents, Address, Network...) much faster than the rest but with the cost of added churn and a bit of annoyance in downstream crates:

• Move them to separate crates as needed
• Remove any inherent methods we're not confident we could support long-term using the same API and move those to extension traits living in bitcoin or other unstable crate.
• Ensure their layout is what we want (I'm mainly thinking of tagging Script)
• If any important methods are implemented in traits and we're not confident about those traits make the methods inherent (I'm mainly thinking about hashes and RawHash stuff.)

Note that this includes not stabilizing seemingly important stuff like consensus encoding. However it's actually not that important for the goal of making it easier for crates to communicate via those types! The individual crates can still privately depend on unstable parts of the library while having stable API since each crate can have its own implementation. Example:

• crate foo exposes a method that returns bitcoin-blockdata::Transaction and internally decodes the transaction using bitcoin:0.34
• crate bar accepts bitcoin-blockdata::Transaction and encodes it using bitcoin::0.35
• bar::consume_transaction(foo::create_transaction()) still works, each crate pulls its own version of bitcoin.

Of course this is somewhat ugly and worsens compile time but at least it's not completely broken and makes coordination between crates easier. And as stabilization continues this problem will decrease over time and eventually vanish.

[apoelstra]

Convert to an untagged/generic scriptpubkey, you mean?

Then we'd basically have two Script regimes, one when the script is already in a transaction and one when the script is without, which have different type conversion rules. And which differently distinguish between taproot and segwit when serializing opcodes etc.

[Kixunil]

More like "less tagged". You still can't confuse public vs sig script vs tapscript vs witness program but can confuse script pubkeys. Although now that I re-read your message, is there anything to confuse? script_pubkey is not versioned or anything, so there's always only one.

[apoelstra]

@Kixunil 👀 great observation that script_pubkey is not actually versioned and always uses the "bare" script interpreter. I guess the same is true of script_sig, of scripts directly inside witnesses, of scripts inside tapbranches inside witnesses, etc. Maybe there is no tagging needed beyond one that indicates the position inside the transaction.

[Kixunil]

If by "position inside the transaction" you mean also witness script and tapscript, not just script_pubkey and script_sig then yes.

[apoelstra]

Yep. Witness scripts and tapscripts are encoded in distinct parts of the witness stack, so "position inside the transaction" still characterizes them.

Very cool.