Crate cashaddr

source ·
Expand description

docs.rs crates.io loicense gitlab build

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).

Usage

Encoding hashes as cashaddr strings is implemented by CashEnc and decoding cashaddr string as hashes is implemented by Payload. See the documentation for these itmes for details.

Modules

  • convertconvert
    Module for converting between Legacy Bitcoin addresses and Cashaddr addresses.

Structs

  • HashType
    Type of hash represented by a cashaddr string.
  • Payload
    Decoded cashaddr payload

Enums

Constants

  • ALLOWED_LENGTHS
    The set of allowed hash lengths for cashaddr encoding.
  • CHARSET
    The cashaddr character set for encoding

Traits

  • CashEnc
    Encode a hash as a cashaddr string.