Overview

A library crate providing a dependency-free^†, pure rust implementation of the cashaddr codec. Allows for transcoding between hashes and cashaddr strings.

† This Crate is only dependency-free if no optional crate features are enabled: enabling crate features can introduce third-party dependencies.

Features

• Generalized interface supporting all standard and many non-standard use-cases
• Non-standard hash types (type bits)
• Arbitrary human-readable prefixes
• Case-insensitive parsing
• Elided prefix
• Comprehensive error detection in decoder
• Convenience methods for succinct expression of common conversion parameters

Feature Flags

All crate features are disabled by default. The following optional crate features can be enabled to provide additional functionality:

• convert enables the [convert] module which provides functions for converting between cashaddr addresses and legacy Bitcoin addresses.

Limitations

Does not support Forward Error Correction. The BCH Codes used in the cashaddr codec technically allow for forward error correction, but using FEC in Bitcoin Cash addresses is dangerous and strongly discouraged.

About the Codec

Cashaddr is a base32-based encoding scheme designed to encode a hash digest and hash type, which describes the use case for the hash, as a string. A cashaddr string consists of 2 distinct parts separated by a colon (:) in the following order:

1. An arbitrary user-defined prefix, sometimes referred to as the "human-readable prefix", the semantics of which are up to the application using cashaddr
2. A binary payload which is encoded as a base32 string using a specific alphabet. This payload contains the following fields:
   1. Hash type: one of 16 values which describe the intended use-case for the hash. see [HashType]
   2. Hash length: one of 8 numeric values which describe the length of the hash. Used in verifying cashaddr string
   3. The hash itself, which is an arbitrary sequence of 20, 24, 28, 32, 40, 48, 56, or 64 bytes
   4. A 40-bit checksum which checks the entire cashaddr, including the user-defined prefix.

Together with the length field, the checksum provides extremely strong assurance that a received cashaddr string was not corrupted in transmission.

Currently, the only widespread use of cashaddr is for encoding Bitcoin Cash addresses, but its design features make it an attractive choice for a general-purpose text codec for hashes.

For details, see the cashaddr spec

Attribution

Most of the codec algorithm logic was based on bitcoincash-addr. This crate seeks to improve on bitcoincash-addr by providing a more generalized and ergonomic user interface, adding support for arbitrary prefixes, and reducing scope to only matters directly related the cashaddr codec itself (base58check codec removed from scope).