fix(bolt12): Make CurrencyCode a validated wrapper type

Convert CurrencyCode from type alias to struct with validation, ensuring
ISO 4217 compliance (3 ASCII uppercase letters) at construction time.

Author: erickcestari

lightning/src/offers/invoice_request.rs

@@ -1468,7 +1468,7 @@ mod tests {
 	#[cfg(c_bindings)]
 	use crate::offers::offer::OfferWithExplicitMetadataBuilder as OfferBuilder;
 	use crate::offers::offer::{
-		Amount, ExperimentalOfferTlvStreamRef, OfferTlvStreamRef, Quantity,
+		Amount, CurrencyCode, ExperimentalOfferTlvStreamRef, OfferTlvStreamRef, Quantity,
 	};
 	use crate::offers::parse::{Bolt12ParseError, Bolt12SemanticError};
 	use crate::offers::payer::PayerTlvStreamRef;
@@ -1997,7 +1997,10 @@ mod tests {
 		assert_eq!(tlv_stream.amount, None);
 
 		let invoice_request = OfferBuilder::new(recipient_pubkey())
-			.amount(Amount::Currency { iso4217_code: *b"USD", amount: 10 })
+			.amount(Amount::Currency {
+				iso4217_code: CurrencyCode::new(*b"USD").unwrap(),
+				amount: 10,
+			})
 			.build_unchecked()
 			.request_invoice(&expanded_key, nonce, &secp_ctx, payment_id)
 			.unwrap()
@@ -2372,7 +2375,10 @@ mod tests {
 
 		let invoice_request = OfferBuilder::new(recipient_pubkey())
 			.description("foo".to_string())
-			.amount(Amount::Currency { iso4217_code: *b"USD", amount: 1000 })
+			.amount(Amount::Currency {
+				iso4217_code: CurrencyCode::new(*b"USD").unwrap(),
+				amount: 1000,
+			})
 			.build_unchecked()
 			.request_invoice(&expanded_key, nonce, &secp_ctx, payment_id)
 			.unwrap()

lightning/src/offers/merkle.rs

@@ -287,7 +287,7 @@ mod tests {
 	use crate::ln::inbound_payment::ExpandedKey;
 	use crate::offers::invoice_request::{InvoiceRequest, UnsignedInvoiceRequest};
 	use crate::offers::nonce::Nonce;
-	use crate::offers::offer::{Amount, OfferBuilder};
+	use crate::offers::offer::{Amount, CurrencyCode, OfferBuilder};
 	use crate::offers::parse::Bech32Encode;
 	use crate::offers::signer::Metadata;
 	use crate::offers::test_utils::recipient_pubkey;
@@ -355,7 +355,10 @@ mod tests {
 		// BOLT 12 test vectors
 		let invoice_request = OfferBuilder::new(recipient_pubkey)
 			.description("A Mathematical Treatise".into())
-			.amount(Amount::Currency { iso4217_code: *b"USD", amount: 100 })
+			.amount(Amount::Currency {
+				iso4217_code: CurrencyCode::new(*b"USD").unwrap(),
+				amount: 100,
+			})
 			.build_unchecked()
 			// Override the payer metadata and signing pubkey to match the test vectors
 			.request_invoice(&expanded_key, nonce, &secp_ctx, payment_id)

lightning/src/offers/offer.rs

@@ -999,7 +999,9 @@ impl OfferContents {
 		let (currency, amount) = match &self.amount {
 			None => (None, None),
 			Some(Amount::Bitcoin { amount_msats }) => (None, Some(*amount_msats)),
-			Some(Amount::Currency { iso4217_code, amount }) => (Some(iso4217_code), Some(*amount)),
+			Some(Amount::Currency { iso4217_code, amount }) => {
+				(Some(iso4217_code.as_bytes()), Some(*amount))
+			},
 		};
 
 		let features = {
@@ -1076,7 +1078,62 @@ pub enum Amount {
 }
 
 /// An ISO 4217 three-letter currency code (e.g., USD).
-pub type CurrencyCode = [u8; 3];
+///
+/// Currency codes must be exactly 3 ASCII uppercase letters.
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
+pub struct CurrencyCode([u8; 3]);
+
+impl CurrencyCode {
+	/// Creates a new `CurrencyCode` from a 3-byte array.
+	///
+	/// Returns an error if the bytes are not valid UTF-8 or not all ASCII uppercase.
+	pub fn new(code: [u8; 3]) -> Result<Self, CurrencyCodeError> {
+		let currency_str =
+			core::str::from_utf8(&code).map_err(|_| CurrencyCodeError::InvalidUtf8)?;
+
+		if !currency_str.chars().all(|c| c.is_ascii_uppercase()) {
+			return Err(CurrencyCodeError::NotAsciiUppercase { code: currency_str.to_string() });
+		}
+
+		Ok(Self(code))
+	}
+
+	/// Returns the currency code as a byte array.
+	pub fn as_bytes(&self) -> &[u8; 3] {
+		&self.0
+	}
+
+	/// Returns the currency code as a string slice.
+	pub fn as_str(&self) -> &str {
+		unsafe { core::str::from_utf8_unchecked(&self.0) }
+	}
+}
+
+impl FromStr for CurrencyCode {
+	type Err = CurrencyCodeError;
+
+	fn from_str(s: &str) -> Result<Self, Self::Err> {
+		if s.len() != 3 {
+			return Err(CurrencyCodeError::InvalidLength { actual: s.len() });
+		}
+
+		let mut code = [0u8; 3];
+		code.copy_from_slice(s.as_bytes());
+		Self::new(code)
+	}
+}
+
+impl AsRef<[u8]> for CurrencyCode {
+	fn as_ref(&self) -> &[u8] {
+		&self.0
+	}
+}
+
+impl core::fmt::Display for CurrencyCode {
+	fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
+		f.write_str(self.as_str())
+	}
+}
 
 /// Quantity of items supported by an [`Offer`].
 #[derive(Clone, Copy, Debug, PartialEq)]
@@ -1115,7 +1172,7 @@ const OFFER_ISSUER_ID_TYPE: u64 = 22;
 tlv_stream!(OfferTlvStream, OfferTlvStreamRef<'a>, OFFER_TYPES, {
 	(2, chains: (Vec<ChainHash>, WithoutLength)),
 	(OFFER_METADATA_TYPE, metadata: (Vec<u8>, WithoutLength)),
-	(6, currency: CurrencyCode),
+	(6, currency: [u8; 3]),
 	(8, amount: (u64, HighZeroBytesDroppedBigSize)),
 	(10, description: (String, WithoutLength)),
 	(12, features: (OfferFeatures, WithoutLength)),
@@ -1209,7 +1266,11 @@ impl TryFrom<FullOfferTlvStream> for OfferContents {
 			},
 			(None, Some(amount_msats)) => Some(Amount::Bitcoin { amount_msats }),
 			(Some(_), None) => return Err(Bolt12SemanticError::MissingAmount),
-			(Some(iso4217_code), Some(amount)) => Some(Amount::Currency { iso4217_code, amount }),
+			(Some(currency_bytes), Some(amount)) => {
+				let iso4217_code = CurrencyCode::new(currency_bytes)
+					.map_err(|_| Bolt12SemanticError::InvalidCurrencyCode)?;
+				Some(Amount::Currency { iso4217_code, amount })
+			},
 		};
 
 		if amount.is_some() && description.is_none() {
@@ -1256,6 +1317,31 @@ impl core::fmt::Display for Offer {
 	}
 }
 
+/// Errors that can occur when creating or parsing a `CurrencyCode`
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub enum CurrencyCodeError {
+	/// The currency code must be exactly 3 bytes
+	InvalidLength { actual: usize },
+	/// The currency code contains invalid UTF-8
+	InvalidUtf8,
+	/// The currency code must be all ASCII uppercase letters
+	NotAsciiUppercase { code: String },
+}
+
+impl core::fmt::Display for CurrencyCodeError {
+	fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
+		match self {
+			Self::InvalidLength { actual } => {
+				write!(f, "Currency code must be 3 bytes, got {}", actual)
+			},
+			Self::InvalidUtf8 => write!(f, "Currency code contains invalid UTF-8"),
+			Self::NotAsciiUppercase { code } => {
+				write!(f, "Currency code '{}' must be all ASCII uppercase", code)
+			},
+		}
+	}
+}
+
 #[cfg(test)]
 mod tests {
 	#[cfg(not(c_bindings))]
@@ -1273,6 +1359,7 @@ mod tests {
 	use crate::ln::inbound_payment::ExpandedKey;
 	use crate::ln::msgs::{DecodeError, MAX_VALUE_MSAT};
 	use crate::offers::nonce::Nonce;
+	use crate::offers::offer::CurrencyCode;
 	use crate::offers::parse::{Bolt12ParseError, Bolt12SemanticError};
 	use crate::offers::test_utils::*;
 	use crate::types::features::OfferFeatures;
@@ -1541,7 +1628,8 @@ mod tests {
 	#[test]
 	fn builds_offer_with_amount() {
 		let bitcoin_amount = Amount::Bitcoin { amount_msats: 1000 };
-		let currency_amount = Amount::Currency { iso4217_code: *b"USD", amount: 10 };
+		let currency_amount =
+			Amount::Currency { iso4217_code: CurrencyCode::new(*b"USD").unwrap(), amount: 10 };
 
 		let offer = OfferBuilder::new(pubkey(42)).amount_msats(1000).build().unwrap();
 		let tlv_stream = offer.as_tlv_stream();
@@ -1820,6 +1908,36 @@ mod tests {
 				Bolt12ParseError::InvalidSemantics(Bolt12SemanticError::InvalidAmount)
 			),
 		}
+
+		let mut tlv_stream = offer.as_tlv_stream();
+		tlv_stream.0.amount = Some(1000);
+		tlv_stream.0.currency = Some(b"\xFF\xFE\xFD"); // invalid UTF-8 bytes
+
+		let mut encoded_offer = Vec::new();
+		tlv_stream.write(&mut encoded_offer).unwrap();
+
+		match Offer::try_from(encoded_offer) {
+			Ok(_) => panic!("expected error"),
+			Err(e) => assert_eq!(
+				e,
+				Bolt12ParseError::InvalidSemantics(Bolt12SemanticError::InvalidCurrencyCode)
+			),
+		}
+
+		let mut tlv_stream = offer.as_tlv_stream();
+		tlv_stream.0.amount = Some(1000);
+		tlv_stream.0.currency = Some(b"usd"); // invalid ISO 4217 code
+
+		let mut encoded_offer = Vec::new();
+		tlv_stream.write(&mut encoded_offer).unwrap();
+
+		match Offer::try_from(encoded_offer) {
+			Ok(_) => panic!("expected error"),
+			Err(e) => assert_eq!(
+				e,
+				Bolt12ParseError::InvalidSemantics(Bolt12SemanticError::InvalidCurrencyCode)
+			),
+		}
 	}
 
 	#[test]

lightning/src/offers/parse.rs

@@ -149,6 +149,8 @@ pub enum Bolt12SemanticError {
 	MissingAmount,
 	/// The amount exceeded the total bitcoin supply or didn't match an expected amount.
 	InvalidAmount,
+	/// The currency code did not contain valid ASCII uppercase letters.
+	InvalidCurrencyCode,
 	/// An amount was provided but was not sufficient in value.
 	InsufficientAmount,
 	/// An amount was provided but was not expected.