Skip to content

0.10-alpha API changes #126

@apoelstra

Description

@apoelstra

You can see the documentation for 0.10 at docs.rs: https://docs.rs/bech32/0.10.0-alpha/bech32/index.html

A few comments:

  • We have FromBase32, ToBase32, WriteBase32, WriteBase256, CheckBase32 traits. None of these are used anywhere. I think every one of these traits should be dropped.
  • If you have an allocator, the encode and decode functions (and their variants) are available. We should draw attention to these in the main docs. If you want segwit, we should point the user to the segwit module.
  • If you do not have an allocator, we currently have the messy arrayvec-based API with functions like decode_lowercase which really aren't useful in the absense of arrayvec.

I propose:

  • We drop all the existing traits.
  • We expose primitives::decode::CheckedHrpString at the top level for non-alloc decoding
  • We expose a wrapper for the data.iter().copied().bytes_to_fes().with_checksum::<Bech32>(&hrp).chars() iterator chain, and maybe another for the with_witness_version variant, at the top level for non-alloc encoding. These wrappers should just take a byte slice. We can document that if you want to use an arbitrary iterator, the primitives::iter module will give you the pieces to do so.
  • We rewrite the top-level docs to give examples of various things:
    • A normal Bitcoin user probably wants to use the segwit module; see examples there.
    • A non-Bitcoin user probably wants to use encode/decode functions (add example).
    • A non-Bitcoin no-alloc user probably wants to use the CheckedHrpString and non-alloc decoding method.
    • If you want to define your own checksum you should use the Checksum trait. We should provide an example, maybe of the BIP-93 checksum.
  • We should also change all the re-exports to use #[doc(inline)] so that they appear as top-level structures rather than re-exports.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions