Bech32.hs

{-# OPTIONS_HADDOCK prune #-}

-- |
-- Module: Data.ByteString.Bech32
-- Copyright: (c) 2024 Jared Tobin
-- License: MIT
-- Maintainer: Jared Tobin <jared@ppad.tech>
--
-- The
-- [BIP0173](https://github.com/bitcoin/bips/blob/master/bip-0173.mediawiki)
-- bech32 checksummed base32 encoding, with decoding and checksum verification.

module Data.ByteString.Bech32 (
    -- * Encoding and Decoding
    encode
  , decode

    -- * Checksum
  , verify
  ) where

import qualified Data.ByteString as BS
import qualified Data.ByteString.Bech32.Internal as BI

-- | Encode a base256 human-readable part and input as bech32.
--
--   >>> let Just bech32 = encode "bc" "my string"
--   >>> bech32
--   "bc1d4ujqum5wf5kuecmu02w2"
encode
  :: BS.ByteString        -- ^ base256-encoded human-readable part
  -> BS.ByteString        -- ^ base256-encoded data part
  -> Maybe BS.ByteString  -- ^ bech32-encoded bytestring
encode = BI.encode BI.Bech32

-- | Decode a bech32-encoded 'ByteString' into its human-readable and data
--   parts.
--
--   All-uppercase input is accepted, and its human-readable part is
--   returned in lowercase. Mixed-case input produces 'Nothing'.
--
--   >>> decode "hi1df6x7cnfdcs8wctnyp5x2un9wed5st"
--   Just ("hi","jtobin was here")
--   >>> decode "hey1df6x7cnfdcs8wctnyp5x2un9wed5st" -- s/hi/hey
--   Nothing
decode
  :: BS.ByteString                        -- ^ bech32-encoded bytestring
  -> Maybe (BS.ByteString, BS.ByteString) -- ^ (hrp, data less checksum)
decode = BI.decode BI.Bech32

-- | Verify that a bech32 string has a valid checksum.
--
--   All-uppercase input is accepted; mixed-case input is not.
--
--   >>> verify "bc1d4ujqum5wf5kuecmu02w2"
--   True
--   >>> verify "bc1d4ujquw5wf5kuecmu02w2" -- s/m/w
--   False
verify
  :: BS.ByteString -- ^ bech32-encoded bytestring
  -> Bool
verify = BI.verify BI.Bech32