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

$ go get -u github.com/btcsuite/btcd/btcutil/bech32

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

• Variables
• 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)
• func EncodeM(hrp string, data []byte) (string, error)
• type ChecksumConst
• 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
• type Version
  • func DecodeGeneric(bech string) (string, []byte, Version, error)

Examples

• Decode
• Encode

Variables

var ConstsToVersion = map[ChecksumConst]Version{
	Version0Const: Version0,
	VersionMConst: VersionM,
}

ConstsToVersion maps a bech32 constant to the version it's associated with.

var VersionToConsts = map[Version]ChecksumConst{
	Version0: Version0Const,
	VersionM: VersionMConst,
}

VersionToConsts maps bech32 versions to the checksum constant to be used when encoding, and asserting a particular version when decoding.

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/utreexo/utreexod/btcutil/bech32"
)

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

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

}

Output:

Decoded human-readable part: bc
Decoded Data: 010e140f070d1a001912060b0d081504140311021d030c1d03040f1814060e1e160e140f070d1a001912060b0d081504140311021d030c1d03040f1814060e1e16

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/utreexo/utreexod/btcutil/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.

func EncodeM

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

EncodeM is the exactly same as the Encode method, but it uses the new bech32m constant instead of the original one. It should be used whenever one attempts to encode a segwit address of v1 and beyond.

Types

type ChecksumConst

type ChecksumConst int

ChecksumConst is a type that represents the currently defined bech32 checksum constants.

const (
	// Version0Const is the original constant used in the checksum
	// verification for bech32.
	Version0Const ChecksumConst = 1

	// VersionMConst is the new constant used for bech32m checksum
	// verification.
	VersionMConst ChecksumConst = 0x2bc830a3
)

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
	ExpectedM string
	Actual    string
}

ErrInvalidChecksum is returned when the extracted checksum of the string is different than what was expected. Both the original version, as well as the new bech32m checksum may be specified.

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

type Version

type Version uint8

Version defines the current set of bech32 versions.

const (
	// Version0 defines the original bech version.
	Version0 Version = iota

	// VersionM is the new bech32 version defined in BIP-350, also known as
	// bech32m.
	VersionM

	// VersionUnknown denotes an unknown bech version.
	VersionUnknown
)

func DecodeGeneric

func DecodeGeneric(bech string) (string, []byte, Version, error)

DecodeGeneric is identical to the existing Decode method, but will also return bech32 version that matches the decoded checksum. This method should be used when decoding segwit addresses, as it enables additional verification to ensure the proper checksum is used.