branta 3.2.0__py3-none-any.whl

branta/__init__.py

@@ -0,0 +1,45 @@
+from branta.enums import BrantaServerBaseUrl, DestinationType, PrivacyMode
+from branta.exceptions import BrantaPaymentException, QRParseException
+from branta.extensions import (
+    get_api_key,
+    get_base_url,
+    get_hash_zk_type,
+    get_hmac_secret,
+    get_privacy,
+    get_url,
+    is_ark,
+    is_bolt11,
+    is_silent_payment,
+    to_normalized_hash,
+    to_url_fragment,
+)
+from branta.models import AddPaymentResult, Destination, Payment, PaymentsResult, Platform
+from branta.options import BrantaClientOptions
+from branta.v2.encryption import AesEncryption, AesEncryptionService
+
+__all__ = [
+    "BrantaServerBaseUrl",
+    "DestinationType",
+    "PrivacyMode",
+    "BrantaPaymentException",
+    "QRParseException",
+    "BrantaClientOptions",
+    "Payment",
+    "Destination",
+    "Platform",
+    "PaymentsResult",
+    "AddPaymentResult",
+    "AesEncryption",
+    "AesEncryptionService",
+    "get_url",
+    "get_base_url",
+    "get_privacy",
+    "get_api_key",
+    "get_hmac_secret",
+    "get_hash_zk_type",
+    "is_bolt11",
+    "is_ark",
+    "is_silent_payment",
+    "to_normalized_hash",
+    "to_url_fragment",
+]

branta/enums.py

@@ -0,0 +1,23 @@
+from enum import Enum
+
+
+class BrantaServerBaseUrl(str, Enum):
+    Staging = "https://staging.guardrail.branta.pro"
+    Production = "https://guardrail.branta.pro"
+    Localhost = "http://localhost:3000"
+
+
+class PrivacyMode(str, Enum):
+    Strict = "strict"
+    Loose = "loose"
+
+
+class DestinationType(str, Enum):
+    BitcoinAddress = "bitcoin_address"
+    Bolt11 = "bolt11"
+    Bolt12 = "bolt12"
+    LnUrl = "ln_url"
+    TetherAddress = "tether_address"
+    LnAddress = "ln_address"
+    ArkAddress = "ark_address"
+    SilentPayment = "silent_payment"

branta/exceptions.py

@@ -0,0 +1,6 @@
+class BrantaPaymentException(Exception):
+    pass
+
+
+class QRParseException(Exception):
+    pass

branta/extensions.py

@@ -0,0 +1,97 @@
+from __future__ import annotations
+
+import hashlib
+from typing import TYPE_CHECKING, Dict, Optional
+
+from branta.enums import DestinationType, PrivacyMode
+
+if TYPE_CHECKING:
+    from branta.options import BrantaClientOptions
+
+
+def get_url(server: BrantaServerBaseUrl) -> str:
+    return server.value
+
+
+def get_base_url(
+    default_options: Optional[BrantaClientOptions],
+    override_options: Optional[BrantaClientOptions],
+) -> str:
+    base_url = None
+    if override_options is not None and override_options.base_url is not None:
+        base_url = override_options.base_url
+    elif default_options is not None and default_options.base_url is not None:
+        base_url = default_options.base_url
+    if base_url is None:
+        raise ValueError("Branta: base_url is a required option.")
+    return get_url(base_url)
+
+
+def get_privacy(
+    default_options: Optional[BrantaClientOptions],
+    override_options: Optional[BrantaClientOptions],
+    fallback: PrivacyMode = PrivacyMode.Strict,
+) -> PrivacyMode:
+    if override_options is not None and override_options.privacy is not None:
+        return override_options.privacy
+    if default_options is not None and default_options.privacy is not None:
+        return default_options.privacy
+    return fallback
+
+
+def get_api_key(
+    default_options: Optional[BrantaClientOptions],
+    override_options: Optional[BrantaClientOptions],
+) -> Optional[str]:
+    if override_options is not None and override_options.default_api_key is not None:
+        return override_options.default_api_key
+    if default_options is not None and default_options.default_api_key is not None:
+        return default_options.default_api_key
+    return None
+
+
+def get_hmac_secret(
+    default_options: Optional[BrantaClientOptions],
+    override_options: Optional[BrantaClientOptions],
+) -> Optional[str]:
+    if override_options is not None and override_options.hmac_secret is not None:
+        return override_options.hmac_secret
+    if default_options is not None and default_options.hmac_secret is not None:
+        return default_options.hmac_secret
+    return None
+
+
+def is_bolt11(value: str) -> bool:
+    lower = value.lower()
+    return lower.startswith("lnbc") or lower.startswith("lntb") or lower.startswith("lnbcrt")
+
+
+def is_ark(value: str) -> bool:
+    return value.lower().startswith("ark1")
+
+
+def is_silent_payment(value: str) -> bool:
+    lower = value.lower()
+    return lower.startswith("sp1") or lower.startswith("tsp1")
+
+
+def get_hash_zk_type(value: str) -> Optional[DestinationType]:
+    if is_bolt11(value):
+        return DestinationType.Bolt11
+    if is_ark(value):
+        return DestinationType.ArkAddress
+    if is_silent_payment(value):
+        return DestinationType.SilentPayment
+    return None
+
+
+def to_normalized_hash(value: str) -> str:
+    normalized = value.lower()
+    return hashlib.sha256(normalized.encode("utf-8")).hexdigest().upper()
+
+
+def to_url_fragment(keys: Dict[str, str]) -> str:
+    if not keys:
+        return ""
+    fragments = [f"k-{k}={v}" for k, v in keys.items()]
+    return "#" + "&".join(fragments)

branta/models.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import List, Optional
+
+from branta.enums import DestinationType
+
+
+@dataclass
+class Destination:
+    value: str
+    is_primary: bool = False
+    is_zk: bool = False
+    is_encrypted: Optional[bool] = None
+    type: Optional[DestinationType] = None
+    zk_id: Optional[str] = None
+    encrypted_dek: Optional[str] = None
+
+
+@dataclass
+class Platform:
+    name: Optional[str] = None
+    logo_url: Optional[str] = None
+    logo_light_url: Optional[str] = None
+
+
+@dataclass
+class Payment:
+    destinations: List[Destination] = field(default_factory=list)
+    description: Optional[str] = None
+    created_date: Optional[str] = None
+    ttl: Optional[int] = None
+    metadata: Optional[str] = None
+    platform: Optional[str] = None
+    platform_logo_url: Optional[str] = None
+    platform_logo_light_url: Optional[str] = None
+    parent_platform: Optional[Platform] = None
+    child_platform: Optional[Platform] = None
+    btc_pay_server_plugin_version: Optional[str] = None
+    is_metadata_decrypted: Optional[bool] = None
+
+    def get_default_value(self) -> str:
+        if not self.destinations:
+            raise ValueError("Payment has no destinations")
+        return self.destinations[0].value
+
+
+@dataclass
+class PaymentsResult:
+    payments: List[Payment]
+    verify_url: str
+
+
+@dataclass
+class AddPaymentResult:
+    payment: Payment
+    secret: str
+    verify_url: str

branta/options.py

@@ -0,0 +1,14 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional
+
+from branta.enums import BrantaServerBaseUrl, PrivacyMode
+
+
+@dataclass
+class BrantaClientOptions:
+    base_url: BrantaServerBaseUrl
+    privacy: Optional[PrivacyMode] = None
+    default_api_key: Optional[str] = None
+    hmac_secret: Optional[str] = None

branta/v2/__init__.py

@@ -0,0 +1,26 @@
+from branta.v2.builder import PaymentBuilder
+from branta.v2.client import BrantaClient
+from branta.v2.encryption import AesEncryptionService
+from branta.v2.parser import QRParser, QrDestination
+from branta.v2.secret_generator import GuidSecretGenerator
+from branta.v2.serialization import (
+    destination_from_api,
+    destination_to_api,
+    payment_from_api,
+    payment_to_api,
+)
+from branta.v2.service import BrantaService
+
+__all__ = [
+    "BrantaService",
+    "BrantaClient",
+    "PaymentBuilder",
+    "QRParser",
+    "QrDestination",
+    "GuidSecretGenerator",
+    "AesEncryptionService",
+    "payment_from_api",
+    "payment_to_api",
+    "destination_from_api",
+    "destination_to_api",
+]

branta/v2/builder.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+import json
+import uuid
+from typing import Optional
+
+from branta.enums import DestinationType
+from branta.models import Destination, Payment, Platform
+
+
+class PaymentBuilder:
+    def __init__(self) -> None:
+        self._payment = Payment()
+
+    def add_destination(self, address: str, type: Optional[DestinationType] = None) -> "PaymentBuilder":
+        destination = Destination(value=address, is_zk=False)
+        if type is not None:
+            destination.type = type
+        self._payment.destinations.append(destination)
+        return self
+
+    def set_zk(self) -> "PaymentBuilder":
+        if self._payment.destinations:
+            destination = self._payment.destinations[-1]
+            destination.is_zk = True
+            destination.zk_id = str(uuid.uuid4())
+        return self
+
+    def set_description(self, description: str) -> "PaymentBuilder":
+        self._payment.description = description
+        return self
+
+    def add_metadata(self, key: str, value: str) -> "PaymentBuilder":
+        metadata_map: dict = json.loads(self._payment.metadata) if self._payment.metadata else {}
+        metadata_map[key] = value
+        self._payment.metadata = json.dumps(metadata_map)
+        return self
+
+    def set_ttl(self, ttl: int) -> "PaymentBuilder":
+        self._payment.ttl = ttl
+        return self
+
+    def set_platform_logo_url(self, platform_logo_url: str) -> "PaymentBuilder":
+        self._payment.platform_logo_url = platform_logo_url
+        return self
+
+    def set_child_platform(
+        self,
+        name: str,
+        logo_url: Optional[str] = None,
+        logo_light_url: Optional[str] = None,
+    ) -> "PaymentBuilder":
+        self._payment.child_platform = Platform(name=name, logo_url=logo_url, logo_light_url=logo_light_url)
+        return self
+
+    def build(self) -> Payment:
+        return self._payment

branta/v2/client.py

@@ -0,0 +1,163 @@
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+import time
+from typing import List, Optional
+from urllib.parse import urlparse, quote
+
+import aiohttp
+
+from branta.exceptions import BrantaPaymentException
+from branta.extensions import get_api_key, get_base_url, get_hmac_secret
+from branta.models import Payment
+from branta.options import BrantaClientOptions
+from branta.v2.serialization import payment_from_api, payment_to_api
+
+_STATUS_TEXT: dict = {
+    400: "BadRequest",
+    401: "Unauthorized",
+    403: "Forbidden",
+    404: "NotFound",
+    409: "Conflict",
+    422: "UnprocessableEntity",
+    429: "TooManyRequests",
+    500: "InternalServerError",
+    502: "BadGateway",
+    503: "ServiceUnavailable",
+    504: "GatewayTimeout",
+}
+
+
+def _hmac_sha256_hex(secret: str, message: str) -> str:
+    return hmac.new(secret.encode("utf-8"), message.encode("utf-8"), hashlib.sha256).hexdigest()
+
+
+class BrantaClient:
+    def __init__(
+        self,
+        default_options: Optional[BrantaClientOptions] = None,
+        session: Optional[aiohttp.ClientSession] = None,
+    ) -> None:
+        self._default_options = default_options
+        self._session = session
+
+    async def _get_session(self) -> aiohttp.ClientSession:
+        if self._session is None:
+            self._session = aiohttp.ClientSession()
+        return self._session
+
+    async def get_payments(
+        self,
+        destination_value: str,
+        options: Optional[BrantaClientOptions] = None,
+        signal: None = None,
+    ) -> List[Payment]:
+        base_url = get_base_url(self._default_options, options)
+        headers = self._build_headers(options, require_api_key=False)
+        encoded = quote(destination_value, safe="")
+        url = f"{base_url}/v2/payments/{encoded}"
+
+        session = await self._get_session()
+        try:
+            async with session.get(url, headers=headers) as response:
+                if not response.ok:
+                    return []
+                text = await response.text()
+                if not text:
+                    return []
+                parsed = json.loads(text)
+                if not isinstance(parsed, list):
+                    return []
+                payments = [payment_from_api(item) for item in parsed]
+                self._verify_logo_urls(base_url, payments)
+                return payments
+        except BrantaPaymentException:
+            raise
+        except Exception:
+            return []
+
+    async def post_payment(
+        self,
+        payment: Payment,
+        options: Optional[BrantaClientOptions] = None,
+        signal: None = None,
+    ) -> Optional[Payment]:
+        base_url = get_base_url(self._default_options, options)
+        headers = self._build_headers(options, require_api_key=True)
+        headers["Content-Type"] = "application/json"
+        body = json.dumps(payment_to_api(payment))
+
+        self._apply_hmac_headers(headers, base_url, body, options)
+
+        session = await self._get_session()
+        async with session.post(f"{base_url}/v2/payments", headers=headers, data=body) as response:
+            if not response.ok:
+                raise BrantaPaymentException(_STATUS_TEXT.get(response.status, str(response.status)))
+            text = await response.text()
+            if not text:
+                return None
+            return payment_from_api(json.loads(text))
+
+    async def is_api_key_valid(
+        self,
+        options: Optional[BrantaClientOptions] = None,
+        signal: None = None,
+    ) -> bool:
+        base_url = get_base_url(self._default_options, options)
+        headers = self._build_headers(options, require_api_key=True)
+
+        session = await self._get_session()
+        try:
+            async with session.get(f"{base_url}/v2/api-keys/health-check", headers=headers) as response:
+                return response.ok
+        except Exception:
+            return False
+
+    async def close(self) -> None:
+        if self._session is not None:
+            await self._session.close()
+            self._session = None
+
+    def _build_headers(self, options: Optional[BrantaClientOptions], require_api_key: bool) -> dict:
+        headers: dict = {}
+        if require_api_key:
+            api_key = get_api_key(self._default_options, options)
+            if api_key is None:
+                raise BrantaPaymentException("Unauthorized")
+            headers["Authorization"] = f"Bearer {api_key}"
+        return headers
+
+    def _apply_hmac_headers(
+        self,
+        headers: dict,
+        base_url: str,
+        body: str,
+        options: Optional[BrantaClientOptions],
+    ) -> None:
+        hmac_secret = get_hmac_secret(self._default_options, options)
+        if hmac_secret is None:
+            return
+        timestamp = str(int(time.time()))
+        trimmed_base = base_url.rstrip("/")
+        message = f"POST|{trimmed_base}/v2/payments|{body}|{timestamp}"
+        signature = _hmac_sha256_hex(hmac_secret, message)
+        headers["X-HMAC-Signature"] = signature
+        headers["X-HMAC-Timestamp"] = timestamp
+
+    def _verify_logo_urls(self, base_url: str, payments: List[Payment]) -> None:
+        try:
+            base_origin = f"{urlparse(base_url).scheme}://{urlparse(base_url).netloc}"
+        except Exception:
+            return
+        for payment in payments:
+            logo_url = payment.platform_logo_url
+            if not logo_url:
+                return
+            try:
+                logo_origin = f"{urlparse(logo_url).scheme}://{urlparse(logo_url).netloc}"
+            except Exception:
+                raise BrantaPaymentException("platformLogoUrl domain does not match the configured baseUrl domain")
+            if logo_origin != base_origin:
+                raise BrantaPaymentException("platformLogoUrl domain does not match the configured baseUrl domain")

branta/v2/encryption.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+import base64
+import hashlib
+import hmac
+import os
+
+from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+
+_NONCE_LENGTH = 12
+
+
+class AesEncryption:
+    @staticmethod
+    async def encrypt(value: str, secret: str, deterministic_nonce: bool = False) -> str:
+        try:
+            key = hashlib.sha256(secret.encode("utf-8")).digest()
+
+            if deterministic_nonce:
+                nonce = hmac.new(key, value.encode("utf-8"), hashlib.sha256).digest()[:_NONCE_LENGTH]
+            else:
+                nonce = os.urandom(_NONCE_LENGTH)
+
+            aesgcm = AESGCM(key)
+            ciphertext_and_tag = aesgcm.encrypt(nonce, value.encode("utf-8"), None)
+            result = nonce + ciphertext_and_tag
+            return base64.b64encode(result).decode("utf-8")
+        except Exception as e:
+            raise Exception(f"Encryption failed: {e}") from e
+
+    @staticmethod
+    async def decrypt(encrypted_value: str, secret: str) -> str:
+        try:
+            encrypted_data = base64.b64decode(encrypted_value)
+        except Exception as e:
+            raise Exception(f"Decryption failed: {e}") from e
+
+        if len(encrypted_data) < 28:
+            raise Exception("Invalid encrypted data: too short")
+
+        try:
+            key = hashlib.sha256(secret.encode("utf-8")).digest()
+            nonce = encrypted_data[:_NONCE_LENGTH]
+            ciphertext_and_tag = encrypted_data[_NONCE_LENGTH:]
+
+            aesgcm = AESGCM(key)
+            plaintext = aesgcm.decrypt(nonce, ciphertext_and_tag, None)
+            return plaintext.decode("utf-8")
+        except Exception as e:
+            raise Exception(f"Decryption failed: {e}") from e
+
+
+class AesEncryptionService:
+    async def encrypt(self, value: str, secret: str, deterministic_nonce: bool = False) -> str:
+        return await AesEncryption.encrypt(value, secret, deterministic_nonce)
+
+    async def decrypt(self, encrypted_value: str, secret: str) -> str:
+        return await AesEncryption.decrypt(encrypted_value, secret)

branta/v2/parser.py

@@ -0,0 +1,162 @@
+from __future__ import annotations
+
+import re
+from typing import Dict, List, Optional
+from urllib.parse import parse_qs, unquote, urlparse
+
+from branta.enums import DestinationType
+from branta.extensions import is_bolt11, is_silent_payment
+
+_LN_ADDRESS_RE = re.compile(r"^[^@\s]+@[^@\s]+\.[^@\s]+$")
+_ETH_HEX_RE = re.compile(r"^[0-9a-fA-F]{40}$")
+
+
+def _is_ethereum_address(value: str) -> bool:
+    return len(value) == 42 and value.lower().startswith("0x") and bool(_ETH_HEX_RE.match(value[2:]))
+
+
+def _is_tron_address(value: str) -> bool:
+    return len(value) == 34 and value.startswith("T")
+
+
+def _detect_plain_text_type(value: str) -> Optional[DestinationType]:
+    if is_bolt11(value):
+        return DestinationType.Bolt11
+    lower = value.lower()
+    if lower.startswith("lno"):
+        return DestinationType.Bolt12
+    if lower.startswith("lnurl"):
+        return DestinationType.LnUrl
+    if lower.startswith("ark1"):
+        return DestinationType.ArkAddress
+    if is_silent_payment(value):
+        return DestinationType.SilentPayment
+    if _is_ethereum_address(value):
+        return DestinationType.TetherAddress
+    if _is_tron_address(value):
+        return DestinationType.TetherAddress
+    if _LN_ADDRESS_RE.match(value):
+        return DestinationType.LnAddress
+    if value.startswith("1") or value.startswith("3") or lower.startswith("bc1"):
+        return DestinationType.BitcoinAddress
+    return None
+
+
+def _get_destination_type(text: str) -> Optional[DestinationType]:
+    lower = text.lower()
+    if lower.startswith("bitcoin:"):
+        return DestinationType.BitcoinAddress
+    if lower.startswith("lightning:"):
+        dest = _extract_path(text)
+        if dest:
+            if is_bolt11(dest):
+                return DestinationType.Bolt11
+            if dest.lower().startswith("lno"):
+                return DestinationType.Bolt12
+            if dest.lower().startswith("lnurl"):
+                return DestinationType.LnUrl
+    return None
+
+
+def _extract_path(text: str) -> Optional[str]:
+    colon_idx = text.find(":")
+    if colon_idx == -1:
+        return None
+    after_colon = text[colon_idx + 1:]
+    question_idx = after_colon.find("?")
+    if question_idx == -1:
+        return after_colon if after_colon else None
+    return after_colon[:question_idx] if after_colon[:question_idx] else None
+
+
+def _parse_query_string(query: str) -> Dict[str, str]:
+    result: Dict[str, str] = {}
+    trimmed = query.lstrip("?")
+    if not trimmed:
+        return result
+    for part in trimmed.split("&"):
+        if not part:
+            continue
+        idx = part.find("=")
+        if idx == -1:
+            raw_key, raw_value = part, ""
+        else:
+            raw_key, raw_value = part[:idx], part[idx + 1:]
+        if not raw_key:
+            continue
+        try:
+            key = unquote(raw_key).lower()
+            value = unquote(raw_value)
+            if key not in result:
+                result[key] = value
+        except Exception:
+            pass
+    return result
+
+
+class QrDestination:
+    def __init__(self, value: str, type: Optional[DestinationType] = None) -> None:
+        self.value = value
+        self.type = type
+
+
+class QRParser:
+    def __init__(self, qr_text: str) -> None:
+        self.destinations: List[QrDestination] = []
+        self.on_chain_encryption_text: Optional[str] = None
+        self.on_chain_encryption_secret: Optional[str] = None
+
+        text = qr_text.strip()
+
+        try:
+            parsed = urlparse(text)
+            scheme = parsed.scheme.lower()
+        except Exception:
+            self.destinations.append(QrDestination(value=text, type=_detect_plain_text_type(text)))
+            return
+
+        if not parsed.scheme:
+            self.destinations.append(QrDestination(value=text, type=_detect_plain_text_type(text)))
+            return
+
+        if scheme in ("bitcoin", "lightning"):
+            dest = _extract_path(text)
+            if dest is not None:
+                self.destinations.append(QrDestination(value=dest, type=_get_destination_type(text)))
+
+            query = parsed.query
+            params = _parse_query_string(query)
+
+            self.on_chain_encryption_text = params.get("branta_id")
+            self.on_chain_encryption_secret = params.get("branta_secret")
+
+            lightning_value = params.get("lightning")
+            if lightning_value is not None:
+                self.destinations.append(QrDestination(value=lightning_value, type=_detect_plain_text_type(lightning_value)))
+
+            bolt12_value = params.get("bolt12")
+            if bolt12_value is not None:
+                self.destinations.append(QrDestination(value=bolt12_value, type=_detect_plain_text_type(bolt12_value)))
+
+            ark_value = params.get("ark")
+            if ark_value is not None:
+                self.destinations.append(QrDestination(value=ark_value, type=_detect_plain_text_type(ark_value)))
+
+            silent_payment_value = params.get("silent_payment")
+            if silent_payment_value is not None:
+                self.destinations.append(QrDestination(value=silent_payment_value, type=_detect_plain_text_type(silent_payment_value)))
+
+            return
+
+        self.destinations.append(QrDestination(value=text))
+
+    @property
+    def destination(self) -> Optional[str]:
+        return self.destinations[0].value if self.destinations else None
+
+    @property
+    def destination_type(self) -> Optional[DestinationType]:
+        return self.destinations[0].type if self.destinations else None
+
+    def is_on_chain_zk(self) -> bool:
+        return self.on_chain_encryption_text is not None and self.on_chain_encryption_secret is not None

branta/v2/secret_generator.py

@@ -0,0 +1,10 @@
+from __future__ import annotations
+
+import uuid
+
+
+class GuidSecretGenerator:
+    deterministic_nonce: bool = False
+
+    def generate(self) -> str:
+        return str(uuid.uuid4())

branta/v2/serialization.py

@@ -0,0 +1,109 @@
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+from branta.enums import DestinationType
+from branta.models import Destination, Payment, Platform
+
+
+def destination_to_api(destination: Destination) -> Dict[str, Any]:
+    result: Dict[str, Any] = {
+        "value": destination.value,
+        "primary": destination.is_primary,
+        "zk": destination.is_zk,
+    }
+    if destination.type is not None:
+        result["type"] = destination.type.value
+    if destination.zk_id is not None:
+        result["zk_id"] = destination.zk_id
+    if destination.encrypted_dek is not None:
+        result["encrypted_dek"] = destination.encrypted_dek
+    return result
+
+
+def destination_from_api(raw: Dict[str, Any]) -> Destination:
+    destination = Destination(
+        value=str(raw.get("value", "")),
+        is_primary=bool(raw.get("primary", False)),
+        is_zk=bool(raw.get("zk", False)),
+    )
+    raw_type = raw.get("type")
+    if raw_type is not None:
+        try:
+            destination.type = DestinationType(raw_type)
+        except ValueError:
+            pass
+    raw_zk_id = raw.get("zk_id")
+    if raw_zk_id is not None:
+        destination.zk_id = str(raw_zk_id)
+    raw_encrypted_dek = raw.get("encrypted_dek")
+    if raw_encrypted_dek is not None:
+        destination.encrypted_dek = str(raw_encrypted_dek)
+    return destination
+
+
+def payment_to_api(payment: Payment) -> Dict[str, Any]:
+    result: Dict[str, Any] = {
+        "destinations": [destination_to_api(d) for d in payment.destinations],
+    }
+    if payment.description is not None:
+        result["description"] = payment.description
+    if payment.created_date is not None:
+        result["created_at"] = payment.created_date
+    if payment.ttl is not None:
+        result["ttl"] = payment.ttl
+    if payment.metadata is not None:
+        result["metadata"] = payment.metadata
+    if payment.platform is not None:
+        result["platform"] = payment.platform
+    if payment.platform_logo_url is not None:
+        result["platform_logo_url"] = payment.platform_logo_url
+    if payment.platform_logo_light_url is not None:
+        result["platform_logo_light_url"] = payment.platform_logo_light_url
+    if payment.child_platform is not None:
+        cp: Dict[str, Any] = {}
+        if payment.child_platform.name is not None:
+            cp["name"] = payment.child_platform.name
+        if payment.child_platform.logo_url is not None:
+            cp["logo_url"] = payment.child_platform.logo_url
+        if payment.child_platform.logo_light_url is not None:
+            cp["logo_light_url"] = payment.child_platform.logo_light_url
+        result["child_platform"] = cp
+    if payment.btc_pay_server_plugin_version is not None:
+        result["btc_pay_server_plugin_version"] = payment.btc_pay_server_plugin_version
+    return result
+
+
+def payment_from_api(raw: Dict[str, Any]) -> Payment:
+    destinations_raw = raw.get("destinations", [])
+    if not isinstance(destinations_raw, list):
+        destinations_raw = []
+    payment = Payment(destinations=[destination_from_api(d) for d in destinations_raw])
+    if raw.get("description") is not None:
+        payment.description = str(raw["description"])
+    if raw.get("created_at") is not None:
+        payment.created_date = str(raw["created_at"])
+    if raw.get("ttl") is not None:
+        payment.ttl = int(raw["ttl"])
+    if raw.get("metadata") is not None:
+        payment.metadata = str(raw["metadata"])
+    if raw.get("platform") is not None:
+        payment.platform = str(raw["platform"])
+    if raw.get("platform_logo_url") is not None:
+        payment.platform_logo_url = str(raw["platform_logo_url"])
+    if raw.get("platform_logo_light_url") is not None:
+        payment.platform_logo_light_url = str(raw["platform_logo_light_url"])
+    if raw.get("parent_platform") is not None:
+        pp = raw["parent_platform"]
+        if isinstance(pp, dict):
+            parent = Platform()
+            if pp.get("name") is not None:
+                parent.name = str(pp["name"])
+            if pp.get("logo_url") is not None:
+                parent.logo_url = str(pp["logo_url"])
+            if pp.get("logo_light_url") is not None:
+                parent.logo_light_url = str(pp["logo_light_url"])
+            payment.parent_platform = parent
+    if raw.get("btc_pay_server_plugin_version") is not None:
+        payment.btc_pay_server_plugin_version = str(raw["btc_pay_server_plugin_version"])
+    return payment

branta/v2/service.py

@@ -0,0 +1,290 @@
+from __future__ import annotations
+
+from typing import Dict, List, Optional
+from urllib.parse import quote
+
+from branta.enums import DestinationType, PrivacyMode
+from branta.exceptions import BrantaPaymentException
+from branta.extensions import (
+    get_base_url,
+    get_hash_zk_type,
+    get_privacy,
+    to_normalized_hash,
+    to_url_fragment,
+)
+from branta.models import AddPaymentResult, Destination, Payment, PaymentsResult
+from branta.options import BrantaClientOptions
+from branta.v2.builder import PaymentBuilder
+from branta.v2.client import BrantaClient
+from branta.v2.encryption import AesEncryptionService
+from branta.v2.parser import QRParser
+from branta.v2.secret_generator import GuidSecretGenerator
+
+
+class BrantaService:
+    def __init__(
+        self,
+        default_options: Optional[BrantaClientOptions] = None,
+        *,
+        client: Optional[object] = None,
+        aes_encryption: Optional[object] = None,
+        secret_generator: Optional[object] = None,
+    ) -> None:
+        self._default_options = default_options
+        self._client = client if client is not None else BrantaClient(default_options)
+        self._aes_encryption = aes_encryption if aes_encryption is not None else AesEncryptionService()
+        self._secret_generator = secret_generator if secret_generator is not None else GuidSecretGenerator()
+
+    def create_payment_builder(self) -> PaymentBuilder:
+        return PaymentBuilder()
+
+    async def get_payments_by_qr_code(
+        self,
+        qr_text: str,
+        options: Optional[BrantaClientOptions] = None,
+    ) -> PaymentsResult:
+        parser = QRParser(qr_text)
+
+        if parser.is_on_chain_zk():
+            additional_values = [
+                d.value
+                for d in parser.destinations
+                if get_hash_zk_type(d.value) is not None
+            ]
+            return await self._get_payments_for_zk(
+                parser.on_chain_encryption_text,
+                parser.on_chain_encryption_secret,
+                additional_values,
+                options,
+            )
+
+        destination = parser.destination
+        if destination is None:
+            return PaymentsResult(payments=[], verify_url=self._build_verify_url(options, ""))
+
+        if (
+            get_privacy(self._default_options, options) == PrivacyMode.Strict
+            and get_hash_zk_type(destination) is None
+        ):
+            return PaymentsResult(payments=[], verify_url=self._build_verify_url(options, destination))
+
+        return await self.get_payments(destination, None, options)
+
+    async def get_payments(
+        self,
+        destination_value: str,
+        destination_encryption_key: Optional[str] = None,
+        options: Optional[BrantaClientOptions] = None,
+    ) -> PaymentsResult:
+        hash_zk_type = get_hash_zk_type(destination_value)
+
+        if (
+            hash_zk_type is None
+            and destination_encryption_key is None
+            and get_privacy(self._default_options, options) == PrivacyMode.Strict
+        ):
+            raise BrantaPaymentException(
+                "PrivacyMode.Strict does not permit plain-text lookups for this destination type."
+            )
+
+        normalized_destination = destination_value.lower() if hash_zk_type is not None else destination_value
+        lookup_value = normalized_destination
+
+        if hash_zk_type is not None:
+            lookup_value = await self._aes_encryption.encrypt(
+                normalized_destination,
+                to_normalized_hash(normalized_destination),
+                True,
+            )
+
+        payments = await self._client.get_payments(lookup_value, options)
+
+        if (
+            len(payments) == 0
+            and hash_zk_type is not None
+            and get_privacy(self._default_options, options) != PrivacyMode.Strict
+        ):
+            lookup_value = normalized_destination
+            payments = await self._client.get_payments(lookup_value, options)
+
+        keys: Dict[str, str] = {}
+        for payment in payments:
+            await self._decrypt_destinations(payment, normalized_destination, destination_encryption_key, hash_zk_type, keys)
+
+        return PaymentsResult(payments=payments, verify_url=self._build_verify_url(options, lookup_value, keys))
+
+    async def add_payment(
+        self,
+        payment: Payment,
+        options: Optional[BrantaClientOptions] = None,
+    ) -> AddPaymentResult:
+        if (
+            get_privacy(self._default_options, options) == PrivacyMode.Strict
+            and any(not d.is_zk for d in payment.destinations)
+        ):
+            raise BrantaPaymentException(
+                "PrivacyMode.Strict requires all destinations to be ZK; one or more destinations have is_zk = False."
+            )
+
+        dek: Optional[str] = None
+        if payment.metadata is not None and any(d.is_zk for d in payment.destinations):
+            dek = self._secret_generator.generate()
+            payment.metadata = await self._aes_encryption.encrypt(payment.metadata, dek, False)
+
+        secret = self._secret_generator.generate()
+        encrypted_to_key: Dict[str, str] = {}
+
+        for destination in payment.destinations:
+            if not destination.is_zk:
+                continue
+
+            if destination.type == DestinationType.BitcoinAddress:
+                destination.value = await self._aes_encryption.encrypt(
+                    destination.value, secret, self._secret_generator.deterministic_nonce
+                )
+                encrypted_to_key[destination.value] = secret
+                if dek is not None:
+                    destination.encrypted_dek = await self._aes_encryption.encrypt(dek, secret, False)
+            else:
+                hash_zk_type = get_hash_zk_type(destination.value)
+                if hash_zk_type is None:
+                    raise BrantaPaymentException(
+                        f"destination type '{destination.type}' does not support ZK"
+                    )
+                normalized_value = destination.value.lower()
+                key = to_normalized_hash(normalized_value)
+                destination.value = await self._aes_encryption.encrypt(normalized_value, key, True)
+                encrypted_to_key[destination.value] = key
+                if dek is not None:
+                    destination.encrypted_dek = await self._aes_encryption.encrypt(dek, key, False)
+
+        response_payment = await self._client.post_payment(payment, options)
+        if response_payment is None:
+            raise BrantaPaymentException("No payment returned from server.")
+
+        keys: Dict[str, str] = {}
+        for d in response_payment.destinations:
+            if d.zk_id is not None and d.value in encrypted_to_key:
+                keys[d.zk_id] = encrypted_to_key[d.value]
+
+        primary_value = payment.destinations[0].value if payment.destinations else ""
+        verify_url = self._build_verify_url(options, primary_value, keys)
+
+        return AddPaymentResult(payment=response_payment, secret=secret, verify_url=verify_url)
+
+    async def is_api_key_valid(self, options: Optional[BrantaClientOptions] = None) -> bool:
+        return await self._client.is_api_key_valid(options)
+
+    async def close(self) -> None:
+        if hasattr(self._client, "close"):
+            await self._client.close()
+
+    async def __aenter__(self) -> "BrantaService":
+        return self
+
+    async def __aexit__(self, *args: object) -> None:
+        await self.close()
+
+    # ---- private helpers ----
+
+    async def _get_payments_for_zk(
+        self,
+        lookup_value: str,
+        encryption_key: Optional[str],
+        additional_hash_values: List[str],
+        options: Optional[BrantaClientOptions],
+    ) -> PaymentsResult:
+        payments = await self._client.get_payments(lookup_value, options)
+
+        keys: Dict[str, str] = {}
+        for payment in payments:
+            await self._decrypt_destinations(payment, lookup_value, encryption_key, None, keys)
+            for value in additional_hash_values:
+                await self._decrypt_hash_zk_destinations(payment, value, keys)
+
+        return PaymentsResult(payments=payments, verify_url=self._build_verify_url(options, lookup_value, keys))
+
+    async def _decrypt_hash_zk_destinations(
+        self,
+        payment: Payment,
+        plain_value: str,
+        keys: Dict[str, str],
+    ) -> None:
+        hash_zk_type = get_hash_zk_type(plain_value)
+        if hash_zk_type is None:
+            return
+        key = to_normalized_hash(plain_value)
+        for destination in payment.destinations:
+            if not destination.is_zk or destination.type != hash_zk_type:
+                continue
+            try:
+                destination.value = await self._aes_encryption.decrypt(destination.value, key)
+                destination.is_encrypted = False
+                if destination.zk_id is not None and destination.zk_id not in keys:
+                    keys[destination.zk_id] = key
+                await self._try_decrypt_metadata(payment, destination, key)
+            except Exception:
+                pass
+
+    async def _decrypt_destinations(
+        self,
+        payment: Payment,
+        destination_value: str,
+        encryption_key: Optional[str],
+        hash_zk_type: Optional[DestinationType],
+        keys: Dict[str, str],
+    ) -> None:
+        for destination in payment.destinations:
+            destination.is_encrypted = bool(destination.is_zk)
+            if not destination.is_zk:
+                continue
+
+            if destination.type == DestinationType.BitcoinAddress:
+                if encryption_key is None:
+                    continue
+                try:
+                    destination.value = await self._aes_encryption.decrypt(destination.value, encryption_key)
+                    destination.is_encrypted = False
+                    if destination.zk_id is not None and destination.zk_id not in keys:
+                        keys[destination.zk_id] = encryption_key
+                    await self._try_decrypt_metadata(payment, destination, encryption_key)
+                except Exception:
+                    pass
+            elif hash_zk_type is not None and destination.type == hash_zk_type:
+                key = to_normalized_hash(destination_value)
+                try:
+                    destination.value = await self._aes_encryption.decrypt(destination.value, key)
+                    destination.is_encrypted = False
+                    if destination.zk_id is not None and destination.zk_id not in keys:
+                        keys[destination.zk_id] = key
+                    await self._try_decrypt_metadata(payment, destination, key)
+                except Exception:
+                    pass
+
+    async def _try_decrypt_metadata(
+        self,
+        payment: Payment,
+        destination: Destination,
+        key_used: str,
+    ) -> None:
+        if destination.encrypted_dek is None or payment.metadata is None or payment.is_metadata_decrypted:
+            return
+        try:
+            dek = await self._aes_encryption.decrypt(destination.encrypted_dek, key_used)
+            payment.metadata = await self._aes_encryption.decrypt(payment.metadata, dek)
+            payment.is_metadata_decrypted = True
+        except Exception:
+            pass
+
+    def _build_verify_url(
+        self,
+        options: Optional[BrantaClientOptions],
+        payment_lookup: str,
+        keys: Optional[Dict[str, str]] = None,
+    ) -> str:
+        base_url = get_base_url(self._default_options, options)
+        encoded = quote(payment_lookup, safe="")
+        url = f"{base_url}/v2/verify/{encoded}"
+        if keys:
+            url += to_url_fragment(keys)
+        return url

branta-3.2.0.dist-info/METADATA

@@ -0,0 +1,152 @@
+Metadata-Version: 2.4
+Name: branta
+Version: 3.2.0
+Summary: Python SDK for the Branta V2 API — payment destination lookup and registration with zero-knowledge encryption support
+Project-URL: Homepage, https://branta.pro
+Project-URL: Repository, https://github.com/BrantaOps/branta-python
+Project-URL: Changelog, https://github.com/BrantaOps/branta-python/blob/main/CHANGELOG.md
+License: MIT
+License-File: LICENSE
+Keywords: bitcoin,branta,crypto,lightning,payments
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Requires-Dist: aiohttp>=3.9.0
+Requires-Dist: cryptography>=42.0.0
+Provides-Extra: dev
+Requires-Dist: coverage>=7.0.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Branta Python SDK
+
+Python SDK for the [Branta](https://branta.pro) V2 API — payment destination lookup and registration with zero-knowledge encryption support.
+
+## Installation
+
+```bash
+pip install branta
+```
+
+## Integration Guide
+
+### Quick start
+
+```python
+import asyncio
+from branta.enums import BrantaServerBaseUrl, PrivacyMode
+from branta.options import BrantaClientOptions
+from branta.v2 import BrantaService
+
+options = BrantaClientOptions(
+    base_url=BrantaServerBaseUrl.Production,
+    privacy=PrivacyMode.Strict,
+)
+service = BrantaService(options)
+
+async def main():
+    result = await service.get_payments_by_qr_code("bitcoin:bc1q...")
+    if result.payments:
+        print(result.payments[0].get_default_value())
+
+asyncio.run(main())
+```
+
+### Privacy modes
+
+| Mode | Behaviour |
+|------|-----------|
+| `PrivacyMode.Strict` (default) | Only ZK lookups. `get_payments()` raises `BrantaPaymentException` for plain addresses. `get_payments_by_qr_code()` returns empty for plain addresses. `add_payment()` raises if any destination has `is_zk=False`. |
+| `PrivacyMode.Loose` | Both plain and ZK lookups are permitted. |
+
+### Looking up a payment by QR code
+
+```python
+result = await service.get_payments_by_qr_code(qr_text)
+# result.payments — list of Payment objects (empty if not found)
+# result.verify_url — always populated; share with the payer to verify
+```
+
+Prefer `get_payments_by_qr_code` for QR-driven flows. It handles multi-destination payloads (`branta_id` / `branta_secret` fragments) automatically.
+
+### Looking up a payment by destination value
+
+```python
+# Plain bitcoin address (requires PrivacyMode.Loose or will raise):
+result = await service.get_payments("bc1q...")
+
+# ZK-encrypted bitcoin address with secret:
+result = await service.get_payments(encrypted_address, destination_encryption_key="my-secret")
+
+# BOLT-11 invoice (hash-ZK — works in strict mode):
+result = await service.get_payments("lnbc...")
+```
+
+### Registering a payment
+
+```python
+from branta.enums import DestinationType
+
+builder = service.create_payment_builder()
+payment = (
+    builder
+    .add_destination("bc1q...", DestinationType.BitcoinAddress).set_zk()
+    .add_destination("lnbc...", DestinationType.Bolt11).set_zk()
+    .set_description("Donation")
+    .add_metadata("email", "donor@example.com")
+    .build()
+)
+
+result = await service.add_payment(payment, BrantaClientOptions(
+    base_url=BrantaServerBaseUrl.Production,
+    default_api_key="your-api-key",
+    privacy=PrivacyMode.Strict,
+))
+# result.payment — the registered payment from the server
+# result.secret — the random encryption key for the bitcoin address
+# result.verify_url — share this URL to verify the payment
+```
+
+### Validating an API key
+
+```python
+is_valid = await service.is_api_key_valid(BrantaClientOptions(
+    base_url=BrantaServerBaseUrl.Production,
+    default_api_key="your-api-key",
+))
+```
+
+### Per-call option overrides
+
+Every public method accepts an optional `BrantaClientOptions` parameter that overrides the service's default options for that call only:
+
+```python
+service = BrantaService(default_options)
+result = await service.get_payments("lnbc...", options=override_options)
+```
+
+## ZK destination types
+
+| Type | Encryption |
+|------|-----------|
+| `BitcoinAddress` | Random secret (GUID) per payment |
+| `Bolt11` | Deterministic: SHA256 of lowercase invoice |
+| `ArkAddress` | Deterministic: SHA256 of lowercase address |
+| `SilentPayment` | Deterministic: SHA256 of lowercase address |
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest tests/ --ignore=tests/test_integration.py     # unit tests
+pytest tests/test_integration.py                     # integration (requires network)
+coverage run -m pytest tests/ --ignore=tests/test_integration.py && coverage report
+```

branta-3.2.0.dist-info/RECORD

@@ -0,0 +1,18 @@
+branta/__init__.py,sha256=ot4GtxAnzxFbLOBX6yxgRUqgdQALamDYgqtCX07cdLs,1125
+branta/enums.py,sha256=4DNf5NPlmYxVajbJtnnhaAFSYvAEkt6uGBAIeI90lGY,551
+branta/exceptions.py,sha256=U6m_71esZOWo9KGVcqW03kUz16HVJ9sbNG6jsm1RydQ,96
+branta/extensions.py,sha256=UDpS1GZSKVKDeC9xr2-q_sTfSFSn9GyKsXOyxBwWbJM,3089
+branta/models.py,sha256=5S413Gs_IxUZZxMDyy-eJnOw5cjEXV6hHGWlwYOzogE,1461
+branta/options.py,sha256=SKLhrQdecTeTwtlpJEdaZNhFnkMdg_jmrjSTcd9VGbw,353
+branta/v2/__init__.py,sha256=gRUwIUmAGtqriVyfIODkXjMPXmrukssjF7CdY1YXr3M,699
+branta/v2/builder.py,sha256=CTNMm3XngQRZ8eRI3RF9dSf5zZqWvL8Wk0p42vlFg5E,1884
+branta/v2/client.py,sha256=2UJ13p6VhI8amNz-mpMXJ6mFbJqPkJII073BiBo3SSw,5836
+branta/v2/encryption.py,sha256=Fi1uDSJoXJ74x_Nzm6nH68-IxrHgndCtk_Gkhi2X86A,2047
+branta/v2/parser.py,sha256=-UxRL6QpjVMqiHXAaGza87cY_8rlPvpTi61uDV5YF7c,5667
+branta/v2/secret_generator.py,sha256=58liH4n6PBEkKlyAxz77RvwMZ42-IX4yaYywogGXW0M,180
+branta/v2/serialization.py,sha256=cJbR3qZmZ06Kn9OyE9CZqtnMTbNdXWCrSa3WhDhJUdI,4468
+branta/v2/service.py,sha256=2wFkGzUuDS154SCLkOTHES_np6NpsNepc5epiPVmA0o,11709
+branta-3.2.0.dist-info/METADATA,sha256=Qfd5aQZvqU2kfH0YxWouFEIvgDziW3gbakheVe30fyE,5029
+branta-3.2.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+branta-3.2.0.dist-info/licenses/LICENSE,sha256=sq9_YWHurat-d1FYVeJRU1nBsZZ94gwjUoqQNKGyX1w,1068
+branta-3.2.0.dist-info/RECORD,,

branta-3.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

branta-3.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Branta Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.