From 9393fa6a99f6c93da2f89626474bef0649c5d9c2 Mon Sep 17 00:00:00 2001 From: jwinterm Date: Thu, 16 Jul 2026 08:12:53 -0400 Subject: [PATCH] feat: expose settlement evidence in Greenfield API --- README.md | 6 ++++++ api/Dockerfile | 3 +++ api/app/btcpay_routes.py | 30 ++++++++++++++++++++++++++++-- api/app/btcpay_schemas.py | 3 +++ api/app/btcpay_webhooks.py | 20 +++++++++++++++++++- api/tests/test_btcpay_contract.py | 24 ++++++++++++++++++++++++ 6 files changed, 83 insertions(+), 3 deletions(-) create mode 100644 api/tests/test_btcpay_contract.py diff --git a/README.md b/README.md index f78498b..cbba5ad 100644 --- a/README.md +++ b/README.md @@ -152,6 +152,12 @@ docker compose --profile local-daemon up --build -d xmrcheckout can send BTCPay-compatible webhooks when invoice status changes (e.g., payment confirmed on-chain). Configure webhooks per-merchant via the admin panel or merchant dashboard. +Greenfield invoice requests may set `checkout.confirmationsRequired` from `0` through `10000`. +The target is snapshotted on the invoice. Invoice responses and settlement webhooks include the +required and observed confirmation counts, transaction IDs, observation time, and wallet-RPC source. +Webhook registration also accepts an optional caller-generated `secret`; deliveries authenticate the +exact request bytes with `BTCPay-Sig`. + If the webhook target is on the same LAN and Docker containers cannot resolve its hostname (NAT hairpinning), add `extra_hosts` to the `reconciler` service in `docker-compose.yml`: ```yaml diff --git a/api/Dockerfile b/api/Dockerfile index 2ff277f..c4323af 100644 --- a/api/Dockerfile +++ b/api/Dockerfile @@ -6,6 +6,9 @@ COPY requirements.txt /app/requirements.txt RUN pip install --no-cache-dir -r /app/requirements.txt COPY app /app/app +COPY tests /app/tests + +RUN python -m unittest discover -s /app/tests -p "test_*.py" EXPOSE 8000 diff --git a/api/app/btcpay_routes.py b/api/app/btcpay_routes.py index d70fa4c..6ff0bda 100644 --- a/api/app/btcpay_routes.py +++ b/api/app/btcpay_routes.py @@ -316,7 +316,11 @@ def create_invoice( subaddress_index=subaddress_index, amount_xmr=amount_xmr, status="pending", - confirmation_target=user.default_confirmation_target, + confirmation_target=( + checkout.confirmationsRequired + if checkout and checkout.confirmationsRequired is not None + else user.default_confirmation_target + ), total_paid_atomic=0, metadata_json=metadata, expires_at=expires_at, @@ -354,6 +358,11 @@ def create_invoice( "status": status_name, "additionalStatus": additional_status, "availableStatusesForManualMarking": ["Invalid"], + "confirmationsRequired": invoice.confirmation_target, + "confirmationsObserved": invoice.confirmations or 0, + "transactionIds": [], + "observedAt": invoice.created_at.isoformat() if invoice.created_at else None, + "observationSource": "xmrcheckout wallet-rpc", } @@ -383,6 +392,12 @@ def get_invoice( status_code=status.HTTP_404_NOT_FOUND, detail="Invoice not found", ) + transfers = ( + db.query(InvoiceTransfer) + .filter(InvoiceTransfer.invoice_id == invoice.id) + .order_by(InvoiceTransfer.updated_at.desc()) + .all() + ) status_name, additional_status = _btcpay_status(invoice) amount, currency, btcpay_data = _btcpay_amount_currency(invoice) expiration_time = _epoch_seconds(invoice.expires_at) @@ -407,6 +422,15 @@ def get_invoice( "status": status_name, "additionalStatus": additional_status, "availableStatusesForManualMarking": ["Invalid"], + "confirmationsRequired": invoice.confirmation_target, + "confirmationsObserved": invoice.confirmations or 0, + "transactionIds": [transfer.txid for transfer in transfers], + "observedAt": ( + transfers[0].updated_at.isoformat() + if transfers and transfers[0].updated_at + else invoice.created_at.isoformat() if invoice.created_at else None + ), + "observationSource": "xmrcheckout wallet-rpc", } @@ -548,7 +572,7 @@ def create_webhook( ): _require_store(store_id, user) _validate_webhook_events(payload.authorizedEvents.specificEvents) - secret = generate_webhook_secret() + secret = payload.secret or generate_webhook_secret() webhook = BtcpayWebhook( user_id=user.id, url=str(payload.url), @@ -611,6 +635,8 @@ def update_webhook( hook.url = str(payload.url) if payload.authorizedEvents is not None: hook.authorized_events = payload.authorizedEvents.model_dump() + if payload.secret is not None: + hook.secret_encrypted = encrypt_secret(payload.secret) db.add(hook) db.commit() db.refresh(hook) diff --git a/api/app/btcpay_schemas.py b/api/app/btcpay_schemas.py index 24e9333..5c97e8c 100644 --- a/api/app/btcpay_schemas.py +++ b/api/app/btcpay_schemas.py @@ -16,6 +16,7 @@ from pydantic import ( class BtcpayCheckout(BaseModel): redirectURL: AnyUrl | None = None speedPolicy: str | None = None + confirmationsRequired: conint(ge=0, le=10000) | None = None paymentMethods: list[str] | None = None expirationMinutes: conint(ge=1, le=10080) | None = None monitoringMinutes: conint(ge=0, le=10080) | None = None @@ -52,6 +53,7 @@ class BtcpayWebhookCreate(BaseModel): automaticRedelivery: bool = True url: AnyUrl authorizedEvents: BtcpayWebhookEvents + secret: str | None = Field(default=None, min_length=16, max_length=512) class BtcpayWebhookUpdate(BaseModel): @@ -59,6 +61,7 @@ class BtcpayWebhookUpdate(BaseModel): automaticRedelivery: bool | None = None url: AnyUrl | None = None authorizedEvents: BtcpayWebhookEvents | None = None + secret: str | None = Field(default=None, min_length=16, max_length=512) class BtcpayInvoiceStatusUpdate(BaseModel): diff --git a/api/app/btcpay_webhooks.py b/api/app/btcpay_webhooks.py index b2754c7..a1fcb85 100644 --- a/api/app/btcpay_webhooks.py +++ b/api/app/btcpay_webhooks.py @@ -12,7 +12,7 @@ import requests from requests import RequestException from sqlalchemy.orm import Session -from .models import BtcpayWebhook, Invoice +from .models import BtcpayWebhook, Invoice, InvoiceTransfer from .security import decrypt_secret logger = logging.getLogger(__name__) @@ -39,6 +39,7 @@ def dispatch_btcpay_webhooks( if not hooks: return payload = _build_payload( + db=db, event_type=event_type, user_id=user_id, invoice=invoice, @@ -113,6 +114,7 @@ def _event_allowed(authorized_events: object, event_type: str) -> bool: def _build_payload( *, + db: Session, event_type: str, user_id: str, invoice: Invoice, @@ -122,6 +124,17 @@ def _build_payload( quote = metadata.get("quote") if isinstance(metadata, dict) else None fiat_amount = quote.get("fiat_amount") if isinstance(quote, dict) else None fiat_currency = quote.get("fiat_currency") if isinstance(quote, dict) else None + transfers = ( + db.query(InvoiceTransfer) + .filter(InvoiceTransfer.invoice_id == invoice.id) + .order_by(InvoiceTransfer.updated_at.desc()) + .all() + ) + observed_at = ( + transfers[0].updated_at.isoformat() + if transfers and transfers[0].updated_at + else invoice.created_at.isoformat() if invoice.created_at else None + ) return { "type": event_type, "timestamp": int(time.time()), @@ -144,6 +157,11 @@ def _build_payload( if getattr(invoice, "amount_xmr", None) is not None else None ), + "confirmationsRequired": invoice.confirmation_target, + "confirmationsObserved": invoice.confirmations or 0, + "transactionIds": [transfer.txid for transfer in transfers], + "observedAt": observed_at, + "observationSource": "xmrcheckout wallet-rpc", } diff --git a/api/tests/test_btcpay_contract.py b/api/tests/test_btcpay_contract.py new file mode 100644 index 0000000..c2ee50e --- /dev/null +++ b/api/tests/test_btcpay_contract.py @@ -0,0 +1,24 @@ +import unittest + +from pydantic import ValidationError + +from app.btcpay_schemas import BtcpayCheckout, BtcpayWebhookCreate + + +class BtcpayContractTests(unittest.TestCase): + def test_exact_confirmation_target_is_bounded(self): + self.assertEqual(BtcpayCheckout(confirmationsRequired=10000).confirmationsRequired, 10000) + with self.assertRaises(ValidationError): + BtcpayCheckout(confirmationsRequired=10001) + + def test_webhook_accepts_operator_generated_secret(self): + webhook = BtcpayWebhookCreate( + url="https://evaluetron.example/webhooks/btcpay", + secret="operator-generated-secret", + authorizedEvents={"specificEvents": ["InvoiceSettled"]}, + ) + self.assertEqual(webhook.secret, "operator-generated-secret") + + +if __name__ == "__main__": + unittest.main()