bech32

README

bech32

Package bech32 provides a Go implementation of the bech32 format specified in BIP 173.

Test vectors from BIP 173 are added to ensure compatibility with the BIP.

Installation and Updating

This package is part of the github.com/decred/dcrd/bech32 module. Use the standard go tooling for working with modules to incorporate it.

Examples

• Bech32 decode Example Demonstrates how to decode a bech32 encoded string.

• Bech32 encode Example Demonstrates how to encode data into a bech32 string.

License

Package bech32 is licensed under the copyfree ISC License.

Documentation

Overview

Package bech32 provides a Go implementation of the bech32 format specified in BIP 173.

Bech32 strings consist of a human-readable part (hrp), followed by the separator 1, then a checksummed data part encoded using the 32 characters "qpzry9x8gf2tvdw0s3jn54khce6mua7l".

More info: https://github.com/bitcoin/bips/blob/master/bip-0173.mediawiki

Index

• func ConvertBits(data []byte, fromBits, toBits uint8, pad bool) ([]byte, error)
• func Decode(bech string) (string, []byte, error)
• func DecodeNoLimit(bech string) (string, []byte, error)
• func DecodeToBase256(bech string) (string, []byte, error)
• func Encode(hrp string, data []byte) (string, error)
• func EncodeFromBase256(hrp string, data []byte) (string, error)
• type ErrInvalidBitGroups
  • func (e ErrInvalidBitGroups) Error() string
• type ErrInvalidCharacter
  • func (e ErrInvalidCharacter) Error() string
• type ErrInvalidChecksum
  • func (e ErrInvalidChecksum) Error() string
• type ErrInvalidDataByte
  • func (e ErrInvalidDataByte) Error() string
• type ErrInvalidIncompleteGroup
  • func (e ErrInvalidIncompleteGroup) Error() string
• type ErrInvalidLength
  • func (e ErrInvalidLength) Error() string
• type ErrInvalidSeparatorIndex
  • func (e ErrInvalidSeparatorIndex) Error() string
• type ErrMixedCase
  • func (e ErrMixedCase) Error() string
• type ErrNonCharsetChar
  • func (e ErrNonCharsetChar) Error() string

Examples

• Decode
• Encode

Functions

func ConvertBits

func ConvertBits(data []byte, fromBits, toBits uint8, pad bool) ([]byte, error)

ConvertBits converts a byte slice where each byte is encoding fromBits bits, to a byte slice where each byte is encoding toBits bits.

func Decode

func Decode(bech string) (string, []byte, error)

Decode decodes a bech32 encoded string, returning the human-readable part and the data part excluding the checksum.

Note that the returned data is 5-bit (base32) encoded and the human-readable part will be lowercase.

Example

This example demonstrates how to decode a bech32 encoded string.

package main

import (
	"encoding/hex"
	"fmt"

	"github.com/decred/dcrd/bech32"
)

func main() {
	encoded := "dcr1pw508d6qejxtdg4y5r3zarvary0c5xw7kw508d6qejxtdg4y5r3zarvary0c5xw7kf0q4gj"
	hrp, decoded, err := bech32.Decode(encoded)
	if err != nil {
		fmt.Println("Error:", err)
	}

	// Convert the decoded data from 5 bits-per-element into 8-bits-per-element
	// payload.
	decoded8bits, err := bech32.ConvertBits(decoded, 5, 8, true)
	if err != nil {
		fmt.Println("Error ConvertBits:", err)
	}

	// Show the decoded data.
	fmt.Println("Decoded human-readable part:", hrp)
	fmt.Println("Decoded Data:", hex.EncodeToString(decoded))
	fmt.Println("Decoded 8bpe Data:", hex.EncodeToString(decoded8bits))

}

Output:

Decoded human-readable part: dcr
Decoded Data: 010e140f070d1a001912060b0d081504140311021d030c1d03040f1814060e1e160e140f070d1a001912060b0d081504140311021d030c1d03040f1814060e1e16
Decoded 8bpe Data: 0ba8f3b740cc8cb6a2a4a0e22e8d9d191f8a19deb3a8f3b740cc8cb6a2a4a0e22e8d9d191f8a19deb0

func DecodeNoLimit

func DecodeNoLimit(bech string) (string, []byte, error)

DecodeNoLimit decodes a bech32 encoded string, returning the human-readable part and the data part excluding the checksum. This function does NOT validate against the BIP-173 maximum length allowed for bech32 strings and is meant for use in custom applications (such as lightning network payment requests), NOT on-chain addresses.

Note that the returned data is 5-bit (base32) encoded and the human-readable part will be lowercase.

func DecodeToBase256

func DecodeToBase256(bech string) (string, []byte, error)

DecodeToBase256 decodes a bech32-encoded string into its associated human-readable part (HRP) and base32-encoded data, converts that data to a base256-encoded byte slice and returns it along with the lowercase HRP.

func Encode

func Encode(hrp string, data []byte) (string, error)

Encode encodes a byte slice into a bech32 string with the given human-readable part (HRP). The HRP will be converted to lowercase if needed since mixed cased encodings are not permitted and lowercase is used for checksum purposes. Note that the bytes must each encode 5 bits (base32).

Example

This example demonstrates how to encode data into a bech32 string.

package main

import (
	"fmt"

	"github.com/decred/dcrd/bech32"
)

func main() {
	data := []byte("Test data")
	// Convert test data to base32:
	conv, err := bech32.ConvertBits(data, 8, 5, true)
	if err != nil {
		fmt.Println("Error:", err)
	}
	encoded, err := bech32.Encode("customHrp!11111q", conv)
	if err != nil {
		fmt.Println("Error:", err)
	}

	// Show the encoded data.
	fmt.Println("Encoded Data:", encoded)

}

Output:

Encoded Data: customhrp!11111q123jhxapqv3shgcgkxpuhe

func EncodeFromBase256

func EncodeFromBase256(hrp string, data []byte) (string, error)

EncodeFromBase256 converts a base256-encoded byte slice into a base32-encoded byte slice and then encodes it into a bech32 string with the given human-readable part (HRP). The HRP will be converted to lowercase if needed since mixed cased encodings are not permitted and lowercase is used for checksum purposes.

Types

type ErrInvalidBitGroups

type ErrInvalidBitGroups struct{}

ErrInvalidBitGroups is returned when conversion is attempted between byte slices using bit-per-element of unsupported value.

func (ErrInvalidBitGroups) Error

func (e ErrInvalidBitGroups) Error() string

type ErrInvalidCharacter

type ErrInvalidCharacter rune

ErrInvalidCharacter is returned when the bech32 string has a character outside the range of the supported charset.

func (ErrInvalidCharacter) Error

func (e ErrInvalidCharacter) Error() string

type ErrInvalidChecksum

type ErrInvalidChecksum struct {
	Expected string
	Actual   string
}

ErrInvalidChecksum is returned when the extracted checksum of the string is different than what was expected.

func (ErrInvalidChecksum) Error

func (e ErrInvalidChecksum) Error() string

type ErrInvalidDataByte

type ErrInvalidDataByte byte

ErrInvalidDataByte is returned when a byte outside the range required for conversion into a string was found.

func (ErrInvalidDataByte) Error

func (e ErrInvalidDataByte) Error() string

type ErrInvalidIncompleteGroup

type ErrInvalidIncompleteGroup struct{}

ErrInvalidIncompleteGroup is returned when then byte slice used as input has data of wrong length.

func (ErrInvalidIncompleteGroup) Error

func (e ErrInvalidIncompleteGroup) Error() string

type ErrInvalidLength

type ErrInvalidLength int

ErrInvalidLength is returned when the bech32 string has an invalid length given the BIP-173 defined restrictions.

func (ErrInvalidLength) Error

func (e ErrInvalidLength) Error() string

type ErrInvalidSeparatorIndex

type ErrInvalidSeparatorIndex int

ErrInvalidSeparatorIndex is returned when the separator character '1' is in an invalid position in the bech32 string.

func (ErrInvalidSeparatorIndex) Error

func (e ErrInvalidSeparatorIndex) Error() string

type ErrMixedCase

type ErrMixedCase struct{}

ErrMixedCase is returned when the bech32 string has both lower and uppercase characters.

func (ErrMixedCase) Error

func (e ErrMixedCase) Error() string

type ErrNonCharsetChar

type ErrNonCharsetChar rune

ErrNonCharsetChar is returned when a character outside of the specific bech32 charset is used in the string.

func (ErrNonCharsetChar) Error

func (e ErrNonCharsetChar) Error() string