Phase 2: OCP-Zahlung (RealU→ZCHF→Open CryptoPay) + Transfer + Autoinvest — Analyse zuerst

[TaprootFreak]

Kontext & Ziel

Umsetzung von Phase 2 des RealUnit-App-Vertrags. Phase 2 umfasst laut Vertrag:

1. Zahlung in 2 Schritten — (a) Trade RealUnit → ZCHF, (b) Payfunktion via QR an POS-Terminals, über Open CryptoPay (OCP) Standorte inkl. SPAR-Filialen.
2. Transfer via QR zwischen RealUnit-App-Nutzern (Wallet-zu-Wallet).
3. Autoinvest / Sparplan — automatische wiederkehrende RealUnit-Käufe.

Wichtige Klarstellung (Scope-Abgrenzung): Der Trade RealU → ZCHF ist kein neues Feature — die RealUnit-App macht diese Konvertierung bereits heute als Teil des Verkaufs-Flows (REALU → Brokerbot → ZCHF). Neu an Phase 2 ist allein die Kombination mit OCP: das ZCHF nicht zur DFX-Deposit-Adresse für eine Fiat-Auszahlung zu schicken, sondern es zu nutzen, um damit an einer OCP-Kasse zu bezahlen. Der Pay-Flow (Baustein 1+2) ist der Hauptbrocken; Transfer (2) und Autoinvest (3) sind separate, kleinere Bausteine.

⚠️ Dieses Issue startet NICHT mit Implementierung. Schritt 0 ist eine vollständige, tiefe Analyse der drei beteiligten Repos. Erst danach wird der genaue Implementierungsweg festgelegt (als Folge-Spec / Sub-Issues). Nicht vorher mit Code beginnen.

Beteiligte Repositories

Repo	Rolle
openCryptoPay/landingPage	Der OCP-Standard selbst (README = maßgebliche Spec). Definiert den QR-/LNURL-Flow, den eine zahlende Wallet implementieren muss. Permissionless, nicht DFX-gebunden.
dfxswiss/api	Das Backend. Enthält bereits (a) das vollständige OCP/payment-link-Modul (src/subdomains/core/payment-link/, /v1/lnurlp/...) und (b) die RealUnit-Endpoints inkl. der REALU→ZCHF-Swap-Mechanik (src/subdomains/supporting/realunit/). Beide sind heute nicht miteinander verdrahtet.
RealUnitCH/app	Die Wallet-App (Flutter). Muss den OCP-LNURL-pay-Client + QR-Scanner + den 2-Schritt-Pay-Flow bekommen; plus Send-Flow (Baustein 2) und Sparplan-Setup (Baustein 3).

Schritt 0 — Pflicht-Tiefenanalyse (vor jeder Implementierung)

Ziel: nach dieser Analyse ist der Implementierungsweg eindeutig. Pro Repo zu beantworten:

A. openCryptoPay/landingPage (der Standard)

• Den kompletten Wallet-Integrations-Flow durcharbeiten (4 Schritte: QR decodieren → Payment Details → Transaction Details → Transaktion ausführen; plus „simplified flow").
• Genau festhalten: Wie wird der EVM-Zahlungspfad ausgeführt? (Transaction-Details liefert uri ethereum:0x…@chainId?value=… + den Hinweis, die signierte Tx als HEX an …/v1/lnurlp/tx/plp_… zurückzusenden, DFX broadcastet.) Für ERC-20 (ZCHF) statt nativem ETH: wie sieht die uri / der erwartete Tx-Aufbau aus?
• Quote-Ablauf/Expiry, timeout-Param, 404-Verhalten („no pending payment"), requestedAmount vs transferAmounts.

B. dfxswiss/api (Backend)

• payment-link/lnurlp-Modul vollständig lesen: forwarding/lnurlp-forward.controller.ts (GET /v1/lnurlp/:id, GET /v1/lnurlp/cb/:id, POST/… /v1/lnurlp/tx/:id, wait, cancel), payment-link/ Services/DTOs. Welche Felder, welche Auth (öffentlich?), welche Chains/Assets unterstützt.
• Bestätigen, dass ZCHF (Ethereum) ein gültiges OCP-Zahl-Asset ist (README-transferAmounts listet es) und wie die EVM-Payment-Antwort für ZCHF konkret aussieht.
• RealUnit-Swap-Pfad: realunit.service.ts createSellUnsignedTransactions / confirmSell — wie genau entsteht ZCHF, und wohin fliesst es heute (→ DFX-Deposit). Was wäre nötig, damit ZCHF im User-Wallet bleibt? Gibt es dafür schon einen Endpoint oder muss einer her?
• Klären, ob backend-seitig überhaupt etwas Neues nötig ist, oder ob die App den bestehenden /v1/lnurlp/*-Flow direkt nutzen kann (mit ZCHF, das sie selbst hält).
• Für Baustein 2 (Transfer) und 3 (Autoinvest): gibt es generische DFX-Bausteine (recurring buy / savings-plan / wallet-transfer), die wiederverwendet werden können? (Heutiger Stand: nicht gefunden.)

C. RealUnitCH/app (Wallet)

• Bestehenden REALU→ZCHF-Verkaufs-Flow lesen (lib/screens/sell*, real_unit_buy_payment_info_service.dart-Pendant für Sell, Cubits) — was davon ist für den Pay-Flow wiederverwendbar.
• EVM-Signing-Fähigkeit der Wallet (WDK / Signing-Pipeline): Kann sie eine ZCHF-ERC-20-transfer-Tx bauen + signieren + als HEX exportieren (für den DFX-broadcast-Weg)? Hält die App ZCHF überhaupt als Asset (zchfAssetId existiert)?
• QR-Scanner: Gibt es schon eine Kamera-/QR-Scan-Fähigkeit? (Bisher nur QR-Anzeige in receive/Payment-Info.) Falls nein → neue Dependency/Permission.
• Wie fügt sich ein „Bezahlen"-Einstieg in die bestehende Dashboard-/Navigations-Struktur (AppRoutes) ein.

Bekannter Ist-Stand (heutige Voruntersuchung — als Startpunkt, nicht abschliessend)

Baustein	App	dfxswiss/api
1+2. Pay via OCP (RU→ZCHF→OCP)	🔴 kein Pay/QR-Scan/OCP; RU→ZCHF nur im Verkauf	🟡 OCP-Modul reif & produktiv (SPAR live), aber RealUnit-entkoppelt; REALU→ZCHF-Swap vorhanden, aber ZCHF geht zur Fiat-Deposit-Adresse
3. Transfer RU↔RU	🔴 nur receive, kein send (Phase-1 schliesst Transfers als Non-Action aus)	🔴 fehlt
4. Autoinvest/Sparplan	🔴 nur Historie-Anzeige (savingsAdd/Remove)	🔴 fehlt (savings in der API = DeFi-Yield dEURO/Juice, anderes Konzept)

OCP-Wallet-Flow (aus dem Standard — Implementierungs-Kern für den Pay-Teil)

1. QR decodieren: Kassen-QR = https://app.dfx.swiss/pl/?lightning=LNURL1…. Den lightning-Parameter per LUD-01 (bech32) decodieren → API-URL https://api.dfx.swiss/v1/lnurlp/pl_… (alternativ simpel: app→api im URL ersetzen).
2. Payment Details: GET /v1/lnurlp/pl_… → JSON mit recipient, quote {id, expiration, payment}, requestedAmount {asset:"CHF", amount}, transferAmounts[]. Letzteres listet pro method (Chain) die zahlbaren assets. Ethereum-Methode enthält ZCHF → das ist unser Zahl-Asset.
3. Transaction Details: Methode+Asset wählen (method=Ethereum, asset=ZCHF) + quote.id → GET {callback}?quote=…&method=Ethereum&asset=ZCHF → liefert für EVM { blockchain, uri: "ethereum:0x…@1?value=…", hint }.
4. Ausführen: ZCHF-ERC-20-transfer-Tx an die Recipient-Adresse bauen + signieren, signierte Tx als HEX an POST /v1/lnurlp/tx/plp_… senden (DFX broadcastet). Status via GET /v1/lnurlp/wait/:id, Abbruch via DELETE /v1/lnurlp/cancel/:id.

Der vertragliche 2-Schritt-Flow konkret: Betrag der OCP-Zahlung in ZCHF aus dem Quote ablesen → genau so viel (+Puffer/Fee) RealU → ZCHF traden, ZCHF im Wallet behalten → ZCHF-Transfer-Tx an die OCP-Recipient-Adresse signieren + an DFX zurückgeben. Die Analyse muss die Orchestrierung (Reihenfolge, Quote-Expiry vs. Swap-Dauer, Slippage/Fee-Puffer, Fehlerfälle wenn ZCHF nach Swap nicht reicht) sauber klären.

Offene Fragen, die die Analyse beantworten muss (NICHT vorab entscheiden)

• Bleibt ZCHF nach dem Swap praktikabel im User-Wallet, oder braucht es einen neuen API-Endpoint / einen anderen Swap-Pfad?
• Reicht der bestehende /v1/lnurlp/*-Flow für die App, oder muss api etwas RealUnit-spezifisches ergänzen?
• Wie wird mit der Quote-Expiry umgegangen, wenn zwischen Swap (Schritt 1) und Zahlung (Schritt 2) Zeit vergeht?
• QR-Scanner: neue Dependency + Kamera-Permission (iOS/Android Store-Implikationen)?
• Transfer RU↔RU (Baustein 2): hebt eine Phase-1-Non-Action auf — eigener Send-Flow + Backend; ist das wirklich Token-Transfer on-chain oder via OCP-„Pay an andere Wallet"?
• Autoinvest (Baustein 3): client-seitiger Scheduler vs. server-seitiger recurring-buy — Architekturentscheidung mit KYC-/Zahlungs-Implikationen.

Deliverable von Schritt 0

Ein konkreter, abgestimmter Implementierungsplan (gerne als Folge-Issues pro Baustein), der auf der Analyse fusst — inkl. klarer Aufteilung, welche Änderung in welches der drei Repos gehört, und welche Reihenfolge. Erst dann Implementierung starten.

Workflow

• Analyse-Ergebnis + Plan hier im Issue (oder verlinkten Sub-Issues) dokumentieren, bevor Code entsteht.
• Implementierung später: RealUnitCH/app → Feature-Branch → PR gegen staging (Draft); dfxswiss/api → Feature-Branch → PR gegen develop (Draft). 3-Subagent-Review. DEV/PRD-Parität beachten.

[TaprootFreak]

Schritt 0 — Tiefenanalyse & Implementierungsplan (Phase 2)

Ergebnis der Pflicht-Tiefenanalyse der drei Repos. Alle tragenden Behauptungen wurden direkt am Quellcode verifiziert (file:line unten). Diese Analyse ist die Spec; Implementierung erst nach Abstimmung.

TL;DR — Kernbefund

1. Der OCP-Pay-Flow ist vollständig verstanden und die in der OCP-README offene ERC-20-Frage ist am DFX-Code aufgelöst: für ZCHF liefert die API eine EIP-681-Token-Transfer-URI ethereum:<ZCHF-Contract>@<chainId>/transfer?address=<recipient>&uint256=<amount> (nicht die native value=-Form).
2. Der OCP-Standardpfad „signiertes Raw-Tx-HEX zurückgeben, DFX broadcastet" passt nicht 1:1 zu den App-Constraints. Die App darf laut CONTRIBUTING ausschließlich api.dfx.swiss ansprechen (kein Third-Party-RPC/Infura/Etherscan) und besitzt heute keinen lokalen ERC-20-Calldata-Bau und keine RLP/EIP-1559-Serialisierung zu Raw-HEX. Sie kann nur eine vom Backend gebaute unsignierte Tx signieren und {r,s,v} zurückgeben — das Backend rekonstruiert + broadcastet (genau der heutige Sell-Flow).
3. Daraus folgt der empfohlene Weg: kleine RealUnit-spezifische Backend-Endpoints, die den bestehenden, öffentlichen /v1/lnurlp/*-Flow für die App wrappen (unsignierte ZCHF-Transfer-Tx bauen → App signiert → {r,s,v} → Backend rekonstruiert HEX → in den OCP-tx-Pfad einspeisen). Das respektiert „API-as-Authority" und „kein Third-Party-RPC" und nutzt das vorhandene Sell-Signing 1:1 wieder.
4. „ZCHF im Wallet behalten" = der bestehende Sell-Flow ohne die zweite (Deposit-)Leg. Heute hängt unbedingt eine zweite Tx (ZCHF transfer → DFX-Deposit) an jedem Sell; ein Swap-only-Pfad ist neu.
5. Transfer (RU↔RU) und Autoinvest/Sparplan: im DFX-Backend gibt es keine wiederverwendbaren Bausteine (kein generischer Wallet-Transfer, kein recurring-buy; savings = DeFi-Yield, anderes Konzept). Beides ist Neubau; Autoinvest braucht eine Architekturentscheidung (Client-Scheduler vs. Server-recurring-buy).

---

A. openCryptoPay/landingPage — der Standard

Quelle: README.md (einzige Spec-Datei, kein /docs). Der Wallet-Flow hat 4 Schritte (+ „simplified flow"):

1) QR decodieren. Kassen-QR = https://app.dfx.swiss/pl/?lightning=LNURL1…. Der lightning-Param ist eine LNURL-encodierte API-URL. Zwei Wege:

• (A) LUD-01/bech32-Decode → saubere API-URL https://api.dfx.swiss/v1/lnurlp/pl_<hex>.
• (B) URL-Tweak (einfacher): app→api im Host ersetzen; Provider löst serverseitig auf.

2) Payment Details. GET /v1/lnurlp/:id → JSON u.a.:

• callback (Basis-URL für Schritt 3, enthält /cb/-Segment), displayName, recipient {name, address, …},
• quote { id: "plq_…", expiration: <ISO-8601 UTC>, payment: "plp_…" },
• requestedAmount { asset: "CHF", amount: 1 } — fiat-denominierte Rechnung,
• transferAmounts[] — pro method (Chain) ein Eintrag mit minFee, available, assets[] [{asset, amount(String!)}]. Der Ethereum-Eintrag listet ZCHF → unser Zahl-Asset. Amounts sind Strings, teils irregulär ("1.") → tolerant parsen.

3) Transaction Details. GET {callback}?quote=<plq_…>&method=Ethereum&asset=ZCHF → für EVM:

{ "expiryDate": "…Z", "blockchain": "Ethereum",
  "uri": "ethereum:0x…@1?value=…",
  "hint": "… send the signed transaction back as HEX via …/v1/lnurlp/tx/plp_… … we broadcast …" }

Der hint enthält die exakte tx-Submit-URL mit der plp_-Payment-ID.

4) Ausführen. Submit ist ein GET (kein POST!): GET /v1/lnurlp/tx/plp_…?quote=plq_…&method=Ethereum&hex=<raw-signed-hex>. Wallet signiert, broadcastet NICHT; DFX prüft das HEX und broadcastet. Erfolg = HTTP-2xx der tx-GET.

Simplified flow: method+asset direkt an die Schritt-2-URL hängen → Antwort ist gleich die Schritt-3-Tx-Details.

Quote/Expiry/404: quote.expiration/expiryDate als ISO-8601-UTC; abgelaufen → Schritt 2 neu holen (frische Rates). ?timeout=<sek> ist ein Server-Long-Poll (default 10s; timeout=0 = sofort). HTTP 404 „No pending payment found" ist ein Normalzustand (Kasse hat noch keinen Warenkorb) → Wallet pollt/retryt, kein harter Fehler. requestedAmount (CHF-Rechnung) vs. transferAmounts (akzeptierte Krypto-Settlement-Optionen, bereits umgerechnet).

README-Mehrdeutigkeit (ERC-20): Die README zeigt nur die native value=-URI; die Token-Form ist nicht dokumentiert. → Aufgelöst gegen die DFX-API (siehe B1).

---

B. dfxswiss/api — Backend (analysiert auf develop)

Hinweis: öffentliches Repo; unten nur öffentliche Pfade/Routen, keine Infra-Details.

B1 — lnurlp/payment-link-Modul

Die HTTP-Oberfläche liegt in src/subdomains/generic/forwarding/controllers/lnurlp-forward.controller.ts (delegiert in payment-link-Services). Verifizierte Routen (alle /v1/lnurlp/…, ohne Auth-Guard → öffentlich):

• GET :id (Payment Details) · POST :id (activatePublicPayment, Body CreatePaymentLinkPaymentDto)
• GET cb/:id (Callback/Tx-Details, Query quote,method,asset,amount,hex?,tx?,sender?)
• GET tx/:id (Tx-Submit per Query …&hex= oder …&tx=) → { txId }
• GET wait/:id → { status } · DELETE cancel/:id

Also existieren wait und cancel real in der DFX-API (über die OCP-README hinaus) und tx ist ein GET.

ERC-20-URI verifiziert — EvmUtil.getPaymentRequest (src/integration/blockchain/shared/evm/evm.util.ts:95-105):

COIN  → ethereum:<recipient>@<chainId>?value=<wei>
ERC20 → ethereum:<tokenContract>@<chainId>/transfer?address=<recipient>&uint256=<amount*10^decimals>

ZCHF/Ethereum ist ein gültiges Pay-Asset (Asset-Order dEURO,ZCHF,USDT,USDC,DAI; ZCHF wird bei CHF-Rechnung fee-frei gestellt). Welche Assets live sind, ist DB-getrieben (paymentEnabled-Flag), nicht hartcodiert.

HEX-Pfad: tx/:id?hex= → handleHexPayment → executeHexPayment/doEvmHexPayment: ethers.utils.parseTransaction(hex), ERC-20 via Selector 0xa9059cbb erkannt, Recipient/Amount/min-Fee validiert, dann DFX broadcastet (sendSignedTransaction). Recipient ist eine DFX-kontrollierte Deposit-Adresse (nicht der Händler direkt) — DFX settelt zum Händler.

B2 — RealUnit-Swap-Pfad

realunit.service.ts, Routen /v1/realunit/sell* (JWT + KYC-Level + RealUnit-Registrierung). Der REALU→ZCHF-Swap ist ein on-chain Brokerbot-(Aktionariat-)Sell als Zwei-Call-Batch:

• Call 1 (Swap): REALU transferAndCall(brokerbot, amount, 0x) (ERC-677) → ZCHF landet im User-Wallet.
• Call 2 (Deposit/Sweep): ZCHF transfer(<DFX-Deposit-Adresse>, zchfAmount).

Zwei Ausführungsvarianten — beide enden an der DFX-Deposit-Adresse:

• EIP-7702 gasless (confirmSell): beide Calls in einer delegierten, von einem DFX-Relayer bezahlten Tx.
• Self-sign (createSellUnsignedTransactions, verifiziert :1259-1333): Backend baut zwei serialisierte unsignierte EIP-1559-Txs {swap (Nonce N), deposit (Nonce N+1)}; App signiert, broadcastSellTransaction (:1335) rekonstruiert aus {unsignedTx,r,s,v} und broadcastet.

Verdikt B2: ZCHF wird immer zur DFX-Deposit-Adresse gesweept (für Fiat-Auszahlung). Kein bestehender Endpoint lässt ZCHF im Wallet. „Im Wallet behalten" = Deposit-Leg (Call 2) weglassen — die Bausteine (getBrokerbotSellPrice, ERC-677-Encoding, Serializer) sind vorhanden; nötig ist ein Swap-only-Konstruktionspfad (neuer Endpoint oder Flag).

B3 — Ist Backend-Arbeit nötig?

• Für die OCP-Zahlung selbst mit bereits gehaltenem ZCHF: technisch nein — der öffentliche /v1/lnurlp/*-Flow genügt, wenn die App ein fertig signiertes Raw-HEX erzeugen kann.
• Aber genau das kann die App nicht (C2: kein lokaler Calldata-Bau, keine RLP-Serialisierung, kein Third-Party-RPC für Nonce/Gas). → Praktisch ist Backend-Arbeit nötig, um das „Backend baut unsignierte Tx → App signiert → Backend rekonstruiert/submittet"-Muster (wie im Sell) auf den OCP-tx-Pfad zu übertragen. Plus der Swap-only-Pfad aus B2.

B4 — Bausteine für Transfer & Autoinvest

• Generischer Wallet→Wallet-Transfer: keiner (nur Admin-/interne gs/evm-Endpoints; kein user-initiierter Transfer).
• recurring-buy / Sparplan / DCA-Scheduler: keiner. savings = DeFi-Yield-Infos (dEURO/Juice), read-only, anderes Konzept. Generische Cron-Infrastruktur (@DfxCron) existiert, aber kein scheduled-buy-Job.

B5 — CONTRIBUTING / Branch-Flow (DFXswiss/api)

Branch von develop, feat/<scope>-<topic>, Squash-Merge nach develop, Release-PRs develop→main automatisch (nie manuell). Vor Push: npm run format (prettier --write) / npm run lint (eslint) / npm run type-check (tsc --noEmit) / npm test (jest); Migration bei Entity-Änderung (npm run migration <Name>); /v1-URI-Versionierung; kein any, Rückgabetypen, @ApiProperty-DTOs.

---

C. RealUnitCH/app — Wallet (analysiert auf staging)

C1 — Bestehender Sell-Flow (wiederverwendbar)

lib/packages/service/dfx/real_unit_sell_payment_info_service.dart (extends DFXAuthService): PUT /v1/realunit/sell (Quote), …/confirm (Software: EIP-712-Delegation + EIP-7702-Authorization, gasless), …/unsigned-transactions (Bitbox: zwei Raw-Txs), …/broadcast ({unsignedTx,r,s,v}→{txHash}), …/confirm mit txHash. Pfadwahl per walletType in sell_payment_info_cubit.dart:71. Bitbox-Orchestrierung (Gas-Check/Polling/Sign/Broadcast/Retry) in sell_bitbox_cubit.dart.
Wiederverwendbar: DFXAuthService (JWT-Handshake, retry-on-401), wallet_service (Unlock/Lock, 60s-Auto-Lock), eip712_signer/eip7702_signer, signToSignature→{r,s,v}, dfx_blockchain_api_service (Balances via DFX), dfx_faucet_service, DI-Muster in lib/setup/di.dart.

CONTRIBUTING markiert if isBitbox → sellBitbox ausdrücklich als Anti-Pattern: der neue Flow soll den Workflow API-signalisiert wählen, nicht auf lokalem walletType verzweigen.

C2 — EVM-Signing — PARTIELL

• Kann: EVM-Key ableiten (web3dart EthPrivateKey), EIP-712 (V4) + EIP-7702 (nur Software; Bitbox-Firmware nicht) signieren, und eine vom Backend gelieferte EIP-1559-Payload signieren → {r,s,v}.
• Kann NICHT (kein Code): lokal transfer(address,uint256)-Calldata bauen; eine vollständige, serialisierte signierte Raw-Tx-HEX (0x02…) erzeugen. Das Backend rekonstruiert/broadcastet heute.
• ZCHF ist KEIN gehaltenes Registry-Asset: nur als DFX-assetId vorhanden (ethereumZchfAssetId=251, sepoliaZchfAssetId=418 in default_assets.dart); kein ZCHF-Contract/Balance in der App. Lokal definiert ist nur REALU (realUnitAsset, decimals 0).
• Folge: der OCP-„App baut+signiert Raw-HEX selbst"-Pfad wäre Net-New und kollidiert mit „kein Third-Party-RPC". Der etablierte, konforme Weg ist Backend-baut-unsignierte-Tx.

C3 — QR-Scanner — fehlt (nur Anzeige); Kamera-Permission schon da

Heute nur QR-Display (qr_flutter). Kein Scanner-Dependency. Kamera-Permissions bereits deklariert (Android CAMERA, iOS NSCameraUsageDescription — derzeit für KYC/image_picker). Neu nötig: Dependency (mobile_scanner empfohlen; beachte den bestehenden MLKit-Telemetrie-Workaround fuck_firebase.dart), Scan-Widget/Screen, Route. iOS-Usage-String ggf. um „Zahlungs-QR" erweitern.

C4 — Navigation / „Pay"-Einstieg

go_router; AppRoutes flach (home,dashboard,buy,sell,sellBitbox,kyc,receive,…). Dashboard-Actions (dashboard_actions.dart) heute Buy + Sell. „Pay" = neuer AppRoutes.pay + GoRoute('/pay') + dritter ActionButton. i18n-Keys in strings_de.arb+strings_en.arb (alphabetisch). pushNamed mit Konstante, Page liest Deps aus Bloc/DI.

C5 — CONTRIBUTING (RealUnitCH/app)

Feature-Branch → PR gegen staging (Promotion staging→develop→main auto). Gates: 1 Approval + Analyze & Test + Visual Regression + Coverage Floor Gate. flutter analyze; flutter test (--coverage); dart format --page-width=100. CRITICAL: nur api.dfx.swiss/dev.api.dfx.swiss (kein Third-Party-RPC/Preisfeed); API-as-Authority (App rendert, entscheidet keine Flow-Eligibility/Limits/Status). DTOs in service/dfx/models/.../dto/ mit fromJson; RealUnitColors.* only; CupertinoActivityIndicator; jede neue Exception mit toString() + Eintrag in exception_surface_test.dart im selben PR; neue Handbook-Pages = Goldens + Zeile in assemble-handbook-screenshots.sh; Deps alphabetisch.

---

Zentrale Architekturentscheidung (Pay-Flow, Baustein 1+2)

Problem: OCP erwartet ein fertig signiertes Raw-HEX (GET /v1/lnurlp/tx/:id?hex=). Die App kann das nicht lokal erzeugen (kein Calldata-Bau/RLP/RPC; API-as-Authority).

Option 1 — App baut HEX selbst (NICHT empfohlen): Net-New-Calldata/RLP/EIP-1559-Serialisierung + Nonce/Gas; verletzt „kein Third-Party-RPC" (Nonce/Gas-Quelle) und API-as-Authority. Viel Risiko, doppelte Signing-Pfade.

Option 2 — Backend wrappt OCP für die App (EMPFOHLEN): zwei kleine RealUnit-Endpoints analog zum Sell:

1. Swap-only: createSellUnsignedTransactions ohne Deposit-Leg (oder Flag) → liefert nur die swap-Tx; ZCHF bleibt im Wallet.
2. OCP-Pay: Endpoint nimmt die OCP-Payment-/Quote-Referenz (aus dem von der App gescannten/decodierten lnurlp-Link) + method=Ethereum&asset=ZCHF, baut die unsignierte ZCHF-transfer-Tx an die OCP-Recipient-Adresse (genau wie die Deposit-Leg im Sell, nur Recipient = OCP-Deposit + Betrag aus dem Quote), App signiert → {r,s,v} → Backend rekonstruiert HEX und speist es in den vorhandenen txHexForward/OCP-tx-Pfad ein (DFX validiert + broadcastet + OCP-Quote settelt). Status via GET /v1/lnurlp/wait/:id.

Vorteile: identisches Signing wie Sell, „kein Third-Party-RPC" & „API-as-Authority" gewahrt, minimaler App-Code, kein neuer Krypto-Pfad in der App.

2-Schritt-Orchestrierung (vertraglich): (1) OCP-Quote lesen → ZCHF-Sollbetrag (+Fee/Slippage-Puffer) bestimmen → REALU→ZCHF Swap-only signieren/ausführen (ZCHF im Wallet) → (2) frisches OCP-Quote holen (gegen Expiry) → ZCHF-Pay signieren/submitten. Fehlerfälle: Quote-Expiry zwischen (1) und (2) → Quote-Refresh; ZCHF nach Swap < Sollbetrag (Slippage) → Puffer/Re-Quote/Abbruch mit klarer Fehlermeldung; Gas-ETH-Check wie im Sell (Faucet-Pfad).

---

Implementierungsplan — Repo-Split & Reihenfolge

Reihenfolge: Baustein 1+2 (Pay) zuerst (Hauptbrocken), dann Baustein 3 (Transfer), dann Baustein 4 (Autoinvest). Pro Baustein: Backend-PR (DFXswiss/api → develop, Draft) vor App-PR (RealUnitCH/app → staging, Draft), da die App API-signalisierte Capabilities konsumiert.

Baustein 1+2 — OCP-Pay (RU→ZCHF→OCP)

• DFXswiss/api (develop, Draft): (a) Swap-only-Pfad (REALU→ZCHF ohne Deposit-Leg); (b) RealUnit-OCP-Pay-Endpoints (unsigned-tx für ZCHF-Transfer an OCP-Recipient + confirm/submit {r,s,v}→HEX→OCP-tx). Migration nur falls Entity/Spalte nötig. Tests + format/lint/type-check.
• RealUnitCH/app (staging, Draft): (a) mobile_scanner + Scan-Screen + AppRoutes.pay + Dashboard-Action; (b) LNURL/QR-Decode (LUD-01 + app→api-Fallback); (c) Pay-Service (extends DFXAuthService) + Page/Cubit pro Schritt (Quote → Swap-only → Re-Quote → Pay → wait); (d) ZCHF-Anzeige nur soweit nötig; (e) Exception-Surface-Test + Goldens + i18n + Coverage-Floor.

Baustein 3 — Transfer RU↔RU

• Empfehlung: on-chain REALU-Transfer (kein OCP-Umweg). api: Endpoint „unsigned REALU transfer(addr,amount)" + broadcast (analog Sell-Bausteine). app: Send-Screen, Recipient-Adresse per QR-Scan (Scanner aus Baustein 1 wiederverwendet), Betrag, sign→{r,s,v}→broadcast. (Hebt eine Phase-1-Non-Action auf.)

Baustein 4 — Autoinvest/Sparplan

• Architekturentscheidung nötig (siehe unten). Vorschlag: server-seitiger recurring-buy (DFX-@DfxCron-Job + Plan-Entity + KYC-/Payment-Anbindung) als sauberste Lösung, aber größerer Backend-Neubau (kein bestehender Baustein). MVP-Alternative: client-seitige Erinnerung + One-Tap-Buy (kein echter Auto-Invest). → eigenes Epic.

---

Vorgeschlagene Sub-Issues

• Phase 2: OCP-Zahlung (RealU→ZCHF→Open CryptoPay) + Transfer + Autoinvest — Analyse zuerst #666-1 (api): Swap-only REALU→ZCHF (ZCHF im Wallet) + RealUnit-OCP-Pay-Endpoints (Wrap des lnurlp-tx-Pfads).
• Phase 2: OCP-Zahlung (RealU→ZCHF→Open CryptoPay) + Transfer + Autoinvest — Analyse zuerst #666-2 (app): QR-Scanner + LNURL-Decode + OCP-Pay-Flow (UI/Service/Cubits) + 2-Schritt-Orchestrierung.
• Phase 2: OCP-Zahlung (RealU→ZCHF→Open CryptoPay) + Transfer + Autoinvest — Analyse zuerst #666-3 (api+app): Transfer RU↔RU (on-chain REALU-Transfer, Send-Screen).
• Phase 2: OCP-Zahlung (RealU→ZCHF→Open CryptoPay) + Transfer + Autoinvest — Analyse zuerst #666-4 (api+app): Autoinvest/Sparplan (nach Architekturentscheidung).

Offene Entscheidungspunkte (Maintainer-Input)

1. Pay-Architektur: Option 2 (Backend-Wrap) bestätigt? (Empfehlung: ja.)
2. Swap-only-Form: neuer dedizierter Endpoint vs. Flag an createSellUnsignedTransactions/confirmSell?
3. Transfer: on-chain REALU-Transfer (Empfehlung) vs. OCP-„Pay an andere Wallet"?
4. Autoinvest: server-recurring-buy (sauber, groß) vs. client-Reminder-MVP — und KYC-/Zahlungsweg?
5. EIP-7702 vs. self-sign für die neuen Pay/Swap-Txs (Software gasless vs. Bitbox-Pfad — Workflow API-signalisiert, nicht client-verzweigt).

---

Verifizierte Anker: evm.util.ts:95-105 (ERC-20-URI) · lnurlp-forward.controller.ts:13-44 (öffentliche Routen, tx=GET) · realunit.service.ts:1259-1333 (Sell-Zwei-Leg, Deposit-Sweep) · real_unit_sell_payment_info_service.dart / sell_bitbox_cubit.dart (App-Signing-Muster) · default_assets.dart (ZCHF nur als assetId).

[TaprootFreak]

Requirement addition — Baustein 3 (Wallet-to-Wallet transfer): dedicated gas-funding wallet

RealUnit token transfers on Ethereum require ETH gas. The gas-funding policy differs per flow:

• Sell (REALU → ZCHF) and OCP / SPAR OTC pay (Baustein 1+2): gas is paid by DFX via the existing funding mechanism.
• Wallet-to-Wallet transfer (RU ↔ RU) (Baustein 3): gas is also subsidised by DFX infrastructure, but it MUST be funded from a dedicated, standalone wallet with its own private key — a separate RealUnit Wallet-to-Wallet Ethereum Gas Fee Funding Wallet — kept distinct from the Sell/OTC gas-funding source.

Why a separate wallet

• Segregates the W2W gas-subsidy budget from the Sell/OTC gas spend (clean accounting).
• Blast-radius isolation: the W2W funding key is independent and can be rotated/limited without touching the Sell/OTC funding.

Implementation notes

• The W2W transfer flow must draw gas exclusively from this dedicated wallet; its address + key are configurable and loaded from secure config (Vault) — never hardcoded.
• Add balance monitoring + a low-balance alert / top-up path for this wallet.
• Provisioning the actual wallet (key generation, Vault storage, ETH funding, config wiring) is an operator task; the application/back-end code should be built parameterised against it.

[TaprootFreak]

Phase 2 — Umsetzung abgeschlossen (alle PRs Ready, grün, reviewed)

Alle Bausteine implementiert, je im 3-Subagent-Loop bis beide Reviewer PASS_CLEAN und CI grün; Draft→Ready; kein Self-Merge (warten auf Maintainer-Freigabe).

Baustein 1+2 — OCP-Pay (RealU→ZCHF→Open CryptoPay)

• Backend: feat(realunit): add swap-only and OCP pay-flow workflow endpoints DFXswiss/api#3819 (→develop) — Swap-only (ZCHF bleibt im Wallet, limit-frei by design), OCP-Pay-Wrap des öffentlichen lnurlp-Flows (unsignierte ZCHF-Transfer-Tx → r/s/v → Rekonstruktion → Settlement), pending-Nonce, Mainnet-only Fail-fast.
• App: feat: OCP pay-flow (RealU→ZCHF→Open CryptoPay) #674 (→staging) — QR-Scanner, LNURL-Decode, Pay-Service + Cubits pro Schritt, fund-safe 2-Schritt-Orchestrierung (Env-Gate vor Swap, Pay-only-Retry, Slippage-Grenze), Goldens + 100% Coverage.

Baustein 3 — Transfer RealUnit↔RealUnit (Wallet-zu-Wallet via QR) — #684

• Backend: feat(realunit): add gasless wallet-to-wallet transfer with dedicated W2W gas wallet DFXswiss/api#3820 (→develop) — W2W-Transfer via EIP-7702-Relay; Gas zahlt DFX aus einer dedizierten W2W-Gas-Funding-Wallet (eigener Key, separat von Sell/OTC, aus Config/Vault, nie hardcoded), persistierte Intent gegen Tampering, Balance-Observer + Low-Balance-Alert. Operator-Config-Keys: REALUNIT_W2W_GAS_WALLET_PRIVATE_KEY, REALUNIT_W2W_GAS_WALLET_ADDRESS, REALUNIT_W2W_GAS_LOW_BALANCE_THRESHOLD (Provisionierung = Operator-Task).
• App: feat: RealUnit wallet-to-wallet (W2W) gasless transfer flow #687 (→staging, stacked auf feat: OCP pay-flow (RealU→ZCHF→Open CryptoPay) #674) — Send-Flow (Recipient via QR/Scanner-Reuse), EIP-7702-Signing wie Software-Sell, Non-EIP-7702-Wallets sauber gated, Goldens + 100% Coverage.

Baustein 4 — Sparplan/Autoinvest — #685

• App: feat(buy): hint savings plan can be set up recurring and multiple times #686 (→staging) — Hinweis, dass der Sparplan mehrfach/wiederkehrend (Bank-Dauerauftrag auf die Buy-IBAN) eingerichtet werden kann; Tests + Golden.

Reihenfolge/Pair-PR: Backend-PRs landen zuerst auf develop, App-PRs folgen auf staging.