Copyright	(c) 2025 Jared Tobin
License	MIT
Maintainer	Jared Tobin <jared@ppad.tech>
Safe Haskell	None
Language	Haskell2010

Lightning.Protocol.BOLT4.Blinding

Contents

Types
Path creation
Hop processing
Key derivation (exported for testing)
TLV encoding (exported for testing)
Encryption (exported for testing)

Description

Route blinding for BOLT4 onion routing.

Synopsis

data BlindedPath = BlindedPath {
- bpIntroductionNode :: !Projective
- bpBlindingKey :: !Projective
- bpBlindedHops :: ![BlindedHop]
}
data BlindedHop = BlindedHop {
- bhBlindedNodeId :: !ByteString
- bhEncryptedData :: !ByteString
}
data BlindedHopData = BlindedHopData {
- bhdPadding :: !(Maybe ByteString)
- bhdShortChannelId :: !(Maybe ShortChannelId)
- bhdNextNodeId :: !(Maybe ByteString)
- bhdPathId :: !(Maybe ByteString)
- bhdNextPathKeyOverride :: !(Maybe ByteString)
- bhdPaymentRelay :: !(Maybe PaymentRelay)
- bhdPaymentConstraints :: !(Maybe PaymentConstraints)
- bhdAllowedFeatures :: !(Maybe ByteString)
}
data PaymentRelay = PaymentRelay {
- prCltvExpiryDelta :: !Word16
- prFeeProportional :: !Word32
- prFeeBaseMsat :: !Word32
}
data PaymentConstraints = PaymentConstraints {
- pcMaxCltvExpiry :: !Word32
- pcHtlcMinimumMsat :: !Word64
}
data BlindingError
- = InvalidSeed
- | EmptyPath
- | InvalidNodeKey Int
- | DecryptionFailed
- | InvalidPathKey
createBlindedPath :: ByteString -> [(Projective, BlindedHopData)] -> Either BlindingError BlindedPath
processBlindedHop :: ByteString -> Projective -> ByteString -> Either BlindingError (BlindedHopData, Projective)
deriveBlindingRho :: SharedSecret -> DerivedKey
deriveBlindedNodeId :: SharedSecret -> Projective -> Maybe ByteString
nextEphemeral :: ByteString -> Projective -> SharedSecret -> Maybe (ByteString, Projective)
encodeBlindedHopData :: BlindedHopData -> ByteString
decodeBlindedHopData :: ByteString -> Maybe BlindedHopData
encryptHopData :: DerivedKey -> BlindedHopData -> ByteString
decryptHopData :: DerivedKey -> ByteString -> Maybe BlindedHopData

Types

data BlindedPath Source #

A blinded route provided by recipient.

Constructors

BlindedPath
Fields bpIntroductionNode :: !Projective First node (unblinded) bpBlindingKey :: !Projective E_0, initial ephemeral bpBlindedHops :: ![BlindedHop]

Instances

Instances details

Show BlindedPath Source #
Instance details Defined in Lightning.Protocol.BOLT4.Blinding Methods showsPrec :: Int -> BlindedPath -> ShowS # show :: BlindedPath -> String # showList :: [BlindedPath] -> ShowS #
Eq BlindedPath Source #
Instance details Defined in Lightning.Protocol.BOLT4.Blinding Methods (==) :: BlindedPath -> BlindedPath -> Bool # (/=) :: BlindedPath -> BlindedPath -> Bool #

data BlindedHop Source #

A single hop in a blinded path.

Constructors

BlindedHop
Fields bhBlindedNodeId :: !ByteString 33 bytes, blinded pubkey bhEncryptedData :: !ByteString Encrypted routing data

Instances

Instances details

Show BlindedHop Source #
Instance details Defined in Lightning.Protocol.BOLT4.Blinding Methods showsPrec :: Int -> BlindedHop -> ShowS # show :: BlindedHop -> String # showList :: [BlindedHop] -> ShowS #
Eq BlindedHop Source #
Instance details Defined in Lightning.Protocol.BOLT4.Blinding Methods (==) :: BlindedHop -> BlindedHop -> Bool # (/=) :: BlindedHop -> BlindedHop -> Bool #

data BlindedHopData Source #

Data encrypted for each blinded hop (before encryption).

Constructors

BlindedHopData

Fields

bhdPadding :: !(Maybe ByteString)
TLV 1
bhdShortChannelId :: !(Maybe ShortChannelId)
TLV 2
bhdNextNodeId :: !(Maybe ByteString)
TLV 4, 33-byte pubkey
bhdPathId :: !(Maybe ByteString)
TLV 6
bhdNextPathKeyOverride :: !(Maybe ByteString)
TLV 8
bhdPaymentRelay :: !(Maybe PaymentRelay)
TLV 10
bhdPaymentConstraints :: !(Maybe PaymentConstraints)
TLV 12
bhdAllowedFeatures :: !(Maybe ByteString)
TLV 14

Instances

Instances details

Show BlindedHopData Source #
Instance details Defined in Lightning.Protocol.BOLT4.Blinding Methods showsPrec :: Int -> BlindedHopData -> ShowS # show :: BlindedHopData -> String # showList :: [BlindedHopData] -> ShowS #
Eq BlindedHopData Source #
Instance details Defined in Lightning.Protocol.BOLT4.Blinding Methods (==) :: BlindedHopData -> BlindedHopData -> Bool # (/=) :: BlindedHopData -> BlindedHopData -> Bool #

data PaymentRelay Source #

Payment relay parameters (TLV 10).

Constructors

PaymentRelay
Fields prCltvExpiryDelta :: !Word16 prFeeProportional :: !Word32 Fee in millionths prFeeBaseMsat :: !Word32

Instances

Instances details

Show PaymentRelay Source #
Instance details Defined in Lightning.Protocol.BOLT4.Blinding Methods showsPrec :: Int -> PaymentRelay -> ShowS # show :: PaymentRelay -> String # showList :: [PaymentRelay] -> ShowS #
Eq PaymentRelay Source #
Instance details Defined in Lightning.Protocol.BOLT4.Blinding Methods (==) :: PaymentRelay -> PaymentRelay -> Bool # (/=) :: PaymentRelay -> PaymentRelay -> Bool #

data PaymentConstraints Source #

Payment constraints (TLV 12).

Constructors

PaymentConstraints
Fields pcMaxCltvExpiry :: !Word32 pcHtlcMinimumMsat :: !Word64

Instances

Instances details

Show PaymentConstraints Source #
Instance details Defined in Lightning.Protocol.BOLT4.Blinding Methods showsPrec :: Int -> PaymentConstraints -> ShowS # show :: PaymentConstraints -> String # showList :: [PaymentConstraints] -> ShowS #
Eq PaymentConstraints Source #
Instance details Defined in Lightning.Protocol.BOLT4.Blinding Methods (==) :: PaymentConstraints -> PaymentConstraints -> Bool # (/=) :: PaymentConstraints -> PaymentConstraints -> Bool #

data BlindingError Source #

Errors during blinding operations.

Constructors

InvalidSeed
EmptyPath
InvalidNodeKey Int
DecryptionFailed
InvalidPathKey

Instances

Instances details

Show BlindingError Source #
Instance details Defined in Lightning.Protocol.BOLT4.Blinding Methods showsPrec :: Int -> BlindingError -> ShowS # show :: BlindingError -> String # showList :: [BlindingError] -> ShowS #
Eq BlindingError Source #
Instance details Defined in Lightning.Protocol.BOLT4.Blinding Methods (==) :: BlindingError -> BlindingError -> Bool # (/=) :: BlindingError -> BlindingError -> Bool #

Path creation

createBlindedPath Source #

Arguments

:: ByteString	32-byte random seed for ephemeral key
-> [(Projective, BlindedHopData)]	Nodes with their data
-> Either BlindingError BlindedPath

Create a blinded path from a seed and list of nodes with their data.

Hop processing

processBlindedHop Source #

Arguments

:: ByteString	Node's 32-byte private key
-> Projective	E_i, current path key (blinding point)
-> ByteString	encrypted_data from onion payload
-> Either BlindingError (BlindedHopData, Projective)

Process a blinded hop, returning decrypted data and next path key.

Key derivation (exported for testing)

deriveBlindingRho :: SharedSecret -> DerivedKey Source #

Derive rho key for encrypting hop data.

rho = HMAC-SHA256(key="rho", data=shared_secret)

deriveBlindedNodeId :: SharedSecret -> Projective -> Maybe ByteString Source #

Derive blinded node ID from shared secret and node pubkey.

B_i = HMAC256("blinded_node_id", ss_i) * N_i

nextEphemeral Source #

Arguments

:: ByteString	e_i (32-byte secret key)
-> Projective	E_i
-> SharedSecret	ss_i
-> Maybe (ByteString, Projective)	(e_{i+1}, E_{i+1})

Compute next ephemeral key pair.

e_{i+1} = SHA256(E_i || ss_i) * e_i E_{i+1} = SHA256(E_i || ss_i) * E_i

TLV encoding (exported for testing)

encodeBlindedHopData :: BlindedHopData -> ByteString Source #

Encode BlindedHopData to TLV stream.

decodeBlindedHopData :: ByteString -> Maybe BlindedHopData Source #

Decode TLV stream to BlindedHopData.

Encryption (exported for testing)

encryptHopData :: DerivedKey -> BlindedHopData -> ByteString Source #

Encrypt hop data with ChaCha20-Poly1305.

Uses rho key and 12-byte zero nonce, empty AAD.

decryptHopData :: DerivedKey -> ByteString -> Maybe BlindedHopData Source #

Decrypt hop data with ChaCha20-Poly1305.