patchr 0.1.0__py3-none-any.whl

picux/domains/pay/adapters.py

@@ -0,0 +1,607 @@
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import dataclass
+from typing import Any, Mapping
+from urllib import error, request
+from urllib.parse import urlparse
+
+
+def stableId(prefix: str, payload: dict[str, Any]) -> str:
+    raw = json.dumps(payload, ensure_ascii=True, sort_keys=True, separators=(",", ":")).encode("utf-8")
+    return f"{prefix}_" + hashlib.sha256(raw).hexdigest()[:24]
+
+
+@dataclass(frozen=True)
+class PayRailAdapterContext:
+    env: Mapping[str, str]
+    createdAt: str
+
+
+class PayRailAdapter:
+    adapterId = ""
+    railId = ""
+    status = "contract"
+    mode = "verify"
+    capabilities: tuple[str, ...] = ()
+    requiredEnv: tuple[str, ...] = ()
+    envAliases: dict[str, tuple[str, ...]] = {}
+    liveExecution = False
+
+    def metadata(self, env: Mapping[str, str]) -> dict[str, Any]:
+        readiness = self.readiness(env)
+        return {
+            "adapterId": self.adapterId,
+            "railId": self.railId,
+            "status": self.status,
+            "mode": self.mode,
+            "capabilities": list(self.capabilities),
+            "requiredEnv": list(self.requiredEnv),
+            "liveExecution": self.liveExecution,
+            "configured": readiness["configured"],
+            "missingEnv": readiness["missingEnv"],
+            "resolvedEnv": readiness.get("resolvedEnv", {}),
+            "readiness": readiness,
+        }
+
+    def readiness(self, env: Mapping[str, str]) -> dict[str, Any]:
+        resolved = {key: self.envKey(env, key) for key in self.requiredEnv}
+        missing = [key for key, source in resolved.items() if not source]
+        return {
+            "configured": not missing,
+            "missingEnv": missing,
+            "resolvedEnv": {key: source for key, source in resolved.items() if source},
+            "mode": "live" if not missing and self.liveExecution else "prepare",
+        }
+
+    def envKey(self, env: Mapping[str, str], key: str) -> str:
+        keys = (key, *self.envAliases.get(key, ()))
+        return next((candidate for candidate in keys if str(env.get(candidate, "") or "").strip()), "")
+
+    def invoke(self, action: str, payload: dict[str, Any], context: PayRailAdapterContext) -> dict[str, Any]:
+        readiness = self.readiness(context.env)
+        if not readiness["configured"]:
+            return self.blocked(action, context, readiness)
+        return self.unsupported(action, context, f"unsupportedAction:{action}")
+
+    def blocked(self, action: str, context: PayRailAdapterContext, readiness: dict[str, Any] | None = None) -> dict[str, Any]:
+        readiness = readiness or self.readiness(context.env)
+        return {
+            "ok": False,
+            "adapterId": self.adapterId,
+            "railId": self.railId,
+            "action": action,
+            "status": "blocked",
+            "error": "adapterNotConfigured",
+            "missingEnv": readiness.get("missingEnv", []),
+            "readiness": readiness,
+            "liveExecution": self.liveExecution,
+            "createdAt": context.createdAt,
+        }
+
+    def unsupported(self, action: str, context: PayRailAdapterContext, error: str) -> dict[str, Any]:
+        return {
+            "ok": False,
+            "adapterId": self.adapterId,
+            "railId": self.railId,
+            "action": action,
+            "status": "rejected",
+            "error": error,
+            "readiness": self.readiness(context.env),
+            "liveExecution": self.liveExecution,
+            "createdAt": context.createdAt,
+        }
+
+    def accepted(
+        self,
+        action: str,
+        payload: dict[str, Any],
+        context: PayRailAdapterContext,
+        *,
+        status: str = "prepared",
+        providerPrefix: str | None = None,
+        extra: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        providerRef = stableId(providerPrefix or self.adapterId, {"action": action, "payload": payload})
+        return {
+            "ok": True,
+            "adapterId": self.adapterId,
+            "railId": self.railId,
+            "action": action,
+            "status": status,
+            "providerRef": providerRef,
+            "readiness": self.readiness(context.env),
+            "liveExecution": self.liveExecution,
+            "createdAt": context.createdAt,
+            **(extra or {}),
+        }
+
+
+class PicuxLedgerAdapter(PayRailAdapter):
+    adapterId = "picuxLedgerAdapter"
+    railId = "picuxLedger"
+    status = "local"
+    mode = "execute"
+    capabilities = ("challenge.create", "challenge.verify", "settlement.prepare", "settlement.execute", "session.consume", "escrow.test")
+
+    def invoke(self, action: str, payload: dict[str, Any], context: PayRailAdapterContext) -> dict[str, Any]:
+        normalized = _action(action)
+        if normalized in {"challenge.create", "preparechallenge"}:
+            challenge = payload.get("challenge", payload) if isinstance(payload.get("challenge", payload), dict) else {}
+            challengeId = str(challenge.get("challengeId", "") or stableId("paychal", challenge))
+            return self.accepted(
+                "challenge.create",
+                challenge,
+                context,
+                providerPrefix="local_chal",
+                extra={
+                    "headers": {
+                        "WWW-Authenticate": f'Payment realm="picux", rail="picuxLedger", challenge="{challengeId}"',
+                        "X-Picux-Payment-Challenge": challengeId,
+                    },
+                    "credentialMode": "localSignature",
+                },
+            )
+        if normalized in {"challenge.verify", "verifychallenge"}:
+            challenge = payload.get("challenge", {}) if isinstance(payload.get("challenge"), dict) else {}
+            credential = payload.get("credential", payload) if isinstance(payload.get("credential", payload), dict) else {}
+            expected = stableId(
+                "paysig",
+                {
+                    "challengeId": str(challenge.get("challengeId", credential.get("challengeId", "")) or ""),
+                    "railId": "picuxLedger",
+                    "payer": credential.get("payer", {}) if isinstance(credential.get("payer"), dict) else {},
+                },
+            )
+            if str(credential.get("signature", "") or "") != expected:
+                return {**self.accepted("challenge.verify", payload, context, status="rejected"), "ok": False, "errors": ["signatureInvalid"]}
+            return self.accepted("challenge.verify", payload, context, status="verified", providerPrefix="local_verify")
+        if normalized in {"settlement.prepare", "preparesettlement"}:
+            instruction = payload.get("instruction", payload) if isinstance(payload.get("instruction", payload), dict) else {}
+            errors = instruction.get("errors", []) if isinstance(instruction.get("errors"), list) else []
+            status = "accepted" if not errors and str(instruction.get("status", "") or "") != "rejected" else "rejected"
+            return self.accepted("settlement.prepare", instruction, context, status=status, providerPrefix="local_settle")
+        if normalized in {"settlement.execute", "executesettlement", "settle"}:
+            instruction = payload.get("instruction", payload) if isinstance(payload.get("instruction", payload), dict) else {}
+            return self.accepted("settlement.execute", instruction, context, status="settled", providerPrefix="local_settle")
+        if normalized in {"session.consume", "consumesession"}:
+            return self.accepted("session.consume", payload, context, status="recorded", providerPrefix="local_session")
+        return self.unsupported(action, context, f"unsupportedAction:{action}")
+
+
+class X402VerifierAdapter(PayRailAdapter):
+    adapterId = "x402Verifier"
+    railId = "x402"
+    status = "contract"
+    mode = "verify"
+    capabilities = ("challenge.create", "challenge.verify", "facilitator.prepare")
+    requiredEnv = ("PICUX_X402_FACILITATOR_URL",)
+    envAliases = {"PICUX_X402_FACILITATOR_URL": ("X402_FACILITATOR_URL",)}
+
+    def invoke(self, action: str, payload: dict[str, Any], context: PayRailAdapterContext) -> dict[str, Any]:
+        normalized = _action(action)
+        readiness = self.readiness(context.env)
+        if not readiness["configured"]:
+            return self.blocked(action, context, readiness)
+        challenge = payload.get("challenge", payload) if isinstance(payload.get("challenge", payload), dict) else {}
+        challengeId = str(challenge.get("challengeId", payload.get("challengeId", "")) or stableId("x402chal", challenge))
+        resource = challenge.get("resource", payload.get("resource", {})) if isinstance(challenge.get("resource", payload.get("resource", {})), dict) else {}
+        amount = challenge.get("amount", payload.get("amount", {})) if isinstance(challenge.get("amount", payload.get("amount", {})), dict) else {}
+        network = str(payload.get("network", "base") or "base")
+        if normalized in {"challenge.create", "preparechallenge", "facilitator.prepare"}:
+            return self.accepted(
+                "challenge.create",
+                challenge,
+                context,
+                providerPrefix="x402_chal",
+                extra={
+                    "network": network,
+                    "paymentScheme": "exact",
+                    "facilitator": {"env": "PICUX_X402_FACILITATOR_URL"},
+                    "challenge": {
+                        "x402Version": "1",
+                        "challengeId": challengeId,
+                        "resource": resource,
+                        "amount": amount,
+                        "payTo": _payTo(challenge),
+                    },
+                    "headers": {
+                        "WWW-Authenticate": f'Payment realm="picux", rail="x402", network="{network}", challenge="{challengeId}"',
+                        "X-Picux-Payment-Challenge": challengeId,
+                    },
+                    "retry": {
+                        "headers": {
+                            "X-PAYMENT": "<base64url-encoded-x402-payment-payload>",
+                            "X-Picux-Payment-Challenge": challengeId,
+                        }
+                    },
+                },
+            )
+        if normalized in {"challenge.verify", "verifychallenge"}:
+            credential = payload.get("credential", payload) if isinstance(payload.get("credential", payload), dict) else {}
+            headers = payload.get("headers", {}) if isinstance(payload.get("headers"), dict) else {}
+            xPayment = str(credential.get("xPayment", headers.get("X-PAYMENT", headers.get("x-payment", ""))) or "")
+            if not xPayment:
+                return {
+                    **self.accepted("challenge.verify", payload, context, status="rejected", providerPrefix="x402_verify"),
+                    "ok": False,
+                    "errors": ["missing:X-PAYMENT"],
+                }
+            return self.accepted(
+                "challenge.verify",
+                {"challengeId": challengeId, "xPaymentHash": stableId("xpay", {"xPayment": xPayment})},
+                context,
+                status="readyForFacilitator",
+                providerPrefix="x402_verify",
+                extra={"facilitator": {"env": "PICUX_X402_FACILITATOR_URL"}, "verifiedBy": "externalFacilitator"},
+            )
+        return self.unsupported(action, context, f"unsupportedAction:{action}")
+
+
+class MppSessionAdapter(PayRailAdapter):
+    adapterId = "mppSessionAdapter"
+    railId = "mpp"
+    status = "contract"
+    mode = "session"
+    capabilities = ("session.authorize", "session.consume", "session.close")
+    requiredEnv = ("PICUX_MPP_ISSUER",)
+    envAliases = {"PICUX_MPP_ISSUER": ("MPP_ISSUER",)}
+
+    def invoke(self, action: str, payload: dict[str, Any], context: PayRailAdapterContext) -> dict[str, Any]:
+        readiness = self.readiness(context.env)
+        if not readiness["configured"]:
+            return self.blocked(action, context, readiness)
+        normalized = _action(action)
+        session = payload.get("session", payload) if isinstance(payload.get("session", payload), dict) else {}
+        sessionId = str(session.get("sessionId", payload.get("sessionId", "")) or stableId("mppsess", session))
+        if normalized in {"session.authorize", "authorizesession"}:
+            return self.accepted(
+                "session.authorize",
+                session,
+                context,
+                status="authorized",
+                providerPrefix="mpp_auth",
+                extra={
+                    "headers": {"Payment-Session": sessionId, "Payment-Auth": f'MPP session="{sessionId}", issuer="PICUX_MPP_ISSUER"'},
+                    "sessionId": sessionId,
+                },
+            )
+        if normalized in {"session.consume", "consumesession"}:
+            return self.accepted("session.consume", session, context, status="recorded", providerPrefix="mpp_use", extra={"sessionId": sessionId})
+        if normalized in {"session.close", "closesession"}:
+            return self.accepted("session.close", session, context, status="closed", providerPrefix="mpp_close", extra={"sessionId": sessionId})
+        return self.unsupported(action, context, f"unsupportedAction:{action}")
+
+
+class StripeSptAdapter(PayRailAdapter):
+    adapterId = "stripeSptAdapter"
+    railId = "stripeSpt"
+    status = "contract"
+    mode = "execute"
+    capabilities = ("token.prepare", "fiat.authorize", "fiat.capture")
+    requiredEnv = ("STRIPE_SECRET_KEY",)
+
+    def invoke(self, action: str, payload: dict[str, Any], context: PayRailAdapterContext) -> dict[str, Any]:
+        readiness = self.readiness(context.env)
+        if not readiness["configured"]:
+            return self.blocked(action, context, readiness)
+        normalized = _action(action)
+        instruction = payload.get("instruction", payload) if isinstance(payload.get("instruction", payload), dict) else {}
+        if normalized in {"token.prepare", "preparetoken", "settlement.prepare", "preparesettlement", "fiat.authorize"}:
+            amount = instruction.get("amount", payload.get("amount", {})) if isinstance(instruction.get("amount", payload.get("amount", {})), dict) else {}
+            return self.accepted(
+                "token.prepare",
+                instruction,
+                context,
+                status="prepared",
+                providerPrefix="stripe_spt",
+                extra={
+                    "sharedPaymentTokenRequest": {
+                        "merchant": str(instruction.get("payeeId", payload.get("merchantId", "")) or ""),
+                        "customer": str(instruction.get("payerId", payload.get("customerId", "")) or ""),
+                        "amount": amount,
+                        "idempotencyKey": str(instruction.get("idempotencyKey", stableId("stripe_idem", instruction)) or ""),
+                        "captureMode": "manual",
+                    },
+                    "provider": {"env": "STRIPE_SECRET_KEY"},
+                },
+            )
+        if normalized in {"fiat.capture", "capture"}:
+            return self.accepted("fiat.capture", instruction, context, status="captured", providerPrefix="stripe_capture", extra={"provider": {"env": "STRIPE_SECRET_KEY"}})
+        return self.unsupported(action, context, f"unsupportedAction:{action}")
+
+
+class SolanaEscrowAdapter(PayRailAdapter):
+    adapterId = "solanaEscrowAdapter"
+    railId = "solanaPay"
+    status = "planned"
+    mode = "escrow"
+    capabilities = ("mission.initialize", "mission.settle", "mission.abort")
+    requiredEnv = ("PICUX_SOLANA_RPC_URL", "PICUX_SOLANA_PROGRAM_ID")
+    envAliases = {
+        "PICUX_SOLANA_RPC_URL": ("SOLANA_RPC_URL",),
+        "PICUX_SOLANA_PROGRAM_ID": ("SOLANA_PROGRAM_ID", "PICUX_SOLANA_PUB_KEY", "SOLANA_PUB_KEY"),
+        "PICUX_SOLANA_APP_ID": ("SOLANA_APP_ID",),
+    }
+
+    def readiness(self, env: Mapping[str, str]) -> dict[str, Any]:
+        rpcKey = self.envKey(env, "PICUX_SOLANA_RPC_URL")
+        programKey = _firstEnv(env, ("PICUX_SOLANA_PROGRAM_ID", "SOLANA_PROGRAM_ID"))
+        recipientKey = _firstEnv(env, ("PICUX_SOLANA_PUB_KEY", "SOLANA_PUB_KEY"))
+        appKey = _firstEnv(env, ("PICUX_SOLANA_APP_ID", "SOLANA_APP_ID"))
+        missing = []
+        if not rpcKey:
+            missing.append("PICUX_SOLANA_RPC_URL")
+        if not programKey and not recipientKey:
+            missing.append("PICUX_SOLANA_PROGRAM_ID")
+        mode = "escrowProgram" if programKey else "paymentIntent"
+        return {
+            "configured": not missing,
+            "missingEnv": missing,
+            "resolvedEnv": {
+                **({"PICUX_SOLANA_RPC_URL": rpcKey} if rpcKey else {}),
+                **({"PICUX_SOLANA_PROGRAM_ID": programKey} if programKey else {}),
+                **({"PICUX_SOLANA_PUB_KEY": recipientKey} if recipientKey else {}),
+                **({"PICUX_SOLANA_APP_ID": appKey} if appKey else {}),
+            },
+            "mode": mode if not missing else "prepare",
+        }
+
+    def invoke(self, action: str, payload: dict[str, Any], context: PayRailAdapterContext) -> dict[str, Any]:
+        readiness = self.readiness(context.env)
+        if not readiness["configured"]:
+            return self.blocked(action, context, readiness)
+        normalized = _action(action)
+        mission = payload.get("mission", payload.get("instruction", payload)) if isinstance(payload.get("mission", payload.get("instruction", payload)), dict) else {}
+        missionId = str(mission.get("missionId", mission.get("settlementId", "")) or stableId("solmission", mission))
+        if normalized in {"mission.initialize", "initializemission", "settlement.prepare", "preparesettlement"}:
+            readiness = self.readiness(context.env)
+            programKey = str(readiness.get("resolvedEnv", {}).get("PICUX_SOLANA_PROGRAM_ID", "") or "")
+            recipientKey = str(readiness.get("resolvedEnv", {}).get("PICUX_SOLANA_PUB_KEY", "") or "")
+            appKey = str(readiness.get("resolvedEnv", {}).get("PICUX_SOLANA_APP_ID", "") or "")
+            method = "initialize_mission" if programKey else "solana_pay_transfer"
+            status = "transactionPreflighted" if self._liveRequested(payload, mission, context.env) else "transactionPrepared"
+            extra = {
+                "chain": "solana",
+                "program": {"env": programKey} if programKey else {},
+                "recipient": {"env": recipientKey} if recipientKey else {},
+                "app": {"env": appKey} if appKey else {},
+                "transactionIntent": {
+                    "method": method,
+                    "missionId": missionId,
+                    "pdaSeeds": ["picux", missionId, str(mission.get("payerId", mission.get("agent", "")) or "")],
+                    "amount": mission.get("amount", {}),
+                    "merchant": str(mission.get("payeeId", mission.get("merchant", "")) or ""),
+                    "appIdEnv": appKey,
+                },
+            }
+            extra = self._withSolanaRpc(extra, payload, mission, context.env)
+            status = str(extra.pop("liveStatus", status) or status)
+            result = self.accepted(
+                "mission.initialize",
+                mission,
+                context,
+                status=status,
+                providerPrefix="solana_mission",
+                extra=extra,
+            )
+            return self._rpcGuard(result)
+        if normalized in {"mission.settle", "settlemission", "settlement.execute", "executesettlement"}:
+            status = "transactionPreflighted" if self._liveRequested(payload, mission, context.env) else "transactionPrepared"
+            extra = self._withSolanaRpc({"chain": "solana", "transactionIntent": {"method": "settle_mission", "missionId": missionId}}, payload, mission, context.env)
+            status = str(extra.pop("liveStatus", status) or status)
+            return self._rpcGuard(self.accepted("mission.settle", mission, context, status=status, providerPrefix="solana_settle", extra=extra))
+        if normalized in {"mission.abort", "abortmission", "refund"}:
+            status = "transactionPreflighted" if self._liveRequested(payload, mission, context.env) else "transactionPrepared"
+            extra = self._withSolanaRpc({"chain": "solana", "transactionIntent": {"method": "abort_mission", "missionId": missionId}}, payload, mission, context.env)
+            status = str(extra.pop("liveStatus", status) or status)
+            return self._rpcGuard(self.accepted("mission.abort", mission, context, status=status, providerPrefix="solana_abort", extra=extra))
+        return self.unsupported(action, context, f"unsupportedAction:{action}")
+
+    def _withSolanaRpc(self, extra: dict[str, Any], payload: dict[str, Any], mission: dict[str, Any], env: Mapping[str, str]) -> dict[str, Any]:
+        if not self._liveRequested(payload, mission, env):
+            return extra
+        rpcUrl = str(env.get(self.envKey(env, "PICUX_SOLANA_RPC_URL"), "") or env.get("PICUX_SOLANA_RPC_URL", "") or env.get("SOLANA_RPC_URL", "") or "")
+        if not rpcUrl:
+            return {**extra, "rpc": {"attempted": True, "ok": False, "error": "missingRpcUrl"}}
+        preflight = _solanaRpc(rpcUrl, "getLatestBlockhash", [{"commitment": "confirmed"}])
+        signed = self._signedTransaction(payload, mission)
+        if not signed:
+            return {**extra, "rpc": preflight}
+        send = _solanaRpc(
+            rpcUrl,
+            "sendTransaction",
+            [signed, {"encoding": "base64", "skipPreflight": False, "preflightCommitment": "confirmed"}],
+        )
+        signature = str(send.get("signature", "") or send.get("result", "") or "")
+        confirm = _solanaRpc(rpcUrl, "getSignatureStatuses", [[signature], {"searchTransactionHistory": True}]) if signature else {}
+        confirmed = bool(confirm.get("confirmed", False))
+        return {
+            **extra,
+            "liveStatus": "transactionConfirmed" if confirmed else ("transactionSubmitted" if send.get("ok") else "transactionRejected"),
+            "rpc": {
+                "attempted": True,
+                "ok": bool(preflight.get("ok") and send.get("ok") and (not confirm or confirm.get("ok"))),
+                "preflight": preflight,
+                "send": send,
+                "confirm": confirm,
+                "signature": signature,
+                "confirmed": confirmed,
+            },
+        }
+
+    @staticmethod
+    def _liveRequested(payload: dict[str, Any], mission: dict[str, Any], env: Mapping[str, str]) -> bool:
+        return _truthy(payload.get("live", payload.get("execute", mission.get("live", mission.get("execute", ""))))) or _truthy(env.get("PICUX_SOLANA_LIVE_RPC", env.get("SOLANA_LIVE_RPC", "")))
+
+    @staticmethod
+    def _signedTransaction(payload: dict[str, Any], mission: dict[str, Any]) -> str:
+        tx = payload.get("signedTransaction", mission.get("signedTransaction", ""))
+        transaction = payload.get("transaction", mission.get("transaction", {}))
+        if not tx and isinstance(transaction, dict):
+            tx = transaction.get("signed", transaction.get("base64", transaction.get("serialized", "")))
+        return str(tx or "").strip()
+
+    @staticmethod
+    def _rpcGuard(result: dict[str, Any]) -> dict[str, Any]:
+        rpc = result.get("rpc", {}) if isinstance(result.get("rpc"), dict) else {}
+        if rpc and not rpc.get("ok"):
+            return {**result, "ok": False, "status": "ioError", "error": "solanaRpcUnavailable"}
+        return result
+
+
+class BaseEscrowAdapter(PayRailAdapter):
+    adapterId = "baseEscrowAdapter"
+    railId = "baseUsdc"
+    status = "planned"
+    mode = "escrow"
+    capabilities = ("mission.initialize", "mission.settle", "mission.abort")
+    requiredEnv = ("PICUX_BASE_RPC_URL", "PICUX_BASE_ESCROW_ADDRESS")
+    envAliases = {
+        "PICUX_BASE_RPC_URL": ("BASE_RPC_URL",),
+        "PICUX_BASE_ESCROW_ADDRESS": ("BASE_ESCROW_ADDRESS",),
+    }
+
+    def invoke(self, action: str, payload: dict[str, Any], context: PayRailAdapterContext) -> dict[str, Any]:
+        readiness = self.readiness(context.env)
+        if not readiness["configured"]:
+            return self.blocked(action, context, readiness)
+        normalized = _action(action)
+        mission = payload.get("mission", payload.get("instruction", payload)) if isinstance(payload.get("mission", payload.get("instruction", payload)), dict) else {}
+        missionId = str(mission.get("missionId", mission.get("settlementId", "")) or stableId("basemission", mission))
+        if normalized in {"mission.initialize", "initializemission", "settlement.prepare", "preparesettlement"}:
+            return self.accepted(
+                "mission.initialize",
+                mission,
+                context,
+                status="transactionPrepared",
+                providerPrefix="base_mission",
+                extra={
+                    "chain": "base",
+                    "contract": {"env": "PICUX_BASE_ESCROW_ADDRESS"},
+                    "transactionIntent": {
+                        "method": "initializeMission",
+                        "missionId": missionId,
+                        "amount": mission.get("amount", {}),
+                        "merchant": str(mission.get("payeeId", mission.get("merchant", "")) or ""),
+                    },
+                },
+            )
+        if normalized in {"mission.settle", "settlemission", "settlement.execute", "executesettlement"}:
+            return self.accepted("mission.settle", mission, context, status="transactionPrepared", providerPrefix="base_settle", extra={"chain": "base", "transactionIntent": {"method": "settleMission", "missionId": missionId}})
+        if normalized in {"mission.abort", "abortmission", "refund"}:
+            return self.accepted("mission.abort", mission, context, status="transactionPrepared", providerPrefix="base_abort", extra={"chain": "base", "transactionIntent": {"method": "abortMission", "missionId": missionId}})
+        return self.unsupported(action, context, f"unsupportedAction:{action}")
+
+
+class L402Adapter(PayRailAdapter):
+    adapterId = "l402Adapter"
+    railId = "l402"
+    status = "planned"
+    mode = "verify"
+    capabilities = ("macaroon.issue", "invoice.verify", "preimage.redeem")
+    requiredEnv = ("PICUX_L402_NODE_URL",)
+    envAliases = {"PICUX_L402_NODE_URL": ("L402_NODE_URL",)}
+
+    def invoke(self, action: str, payload: dict[str, Any], context: PayRailAdapterContext) -> dict[str, Any]:
+        readiness = self.readiness(context.env)
+        if not readiness["configured"]:
+            return self.blocked(action, context, readiness)
+        normalized = _action(action)
+        challenge = payload.get("challenge", payload) if isinstance(payload.get("challenge", payload), dict) else {}
+        challengeId = str(challenge.get("challengeId", payload.get("challengeId", "")) or stableId("l402chal", challenge))
+        if normalized in {"macaroon.issue", "challenge.create", "preparechallenge"}:
+            macaroonRef = stableId("macaroon", {"challengeId": challengeId, "resource": challenge.get("resource", {})})
+            invoiceRef = stableId("invoice", {"challengeId": challengeId, "amount": challenge.get("amount", {})})
+            return self.accepted(
+                "macaroon.issue",
+                challenge,
+                context,
+                providerPrefix="l402_issue",
+                extra={
+                    "headers": {"WWW-Authenticate": f'L402 macaroon="{macaroonRef}", invoice="{invoiceRef}"'},
+                    "macaroonRef": macaroonRef,
+                    "invoiceRef": invoiceRef,
+                    "provider": {"env": "PICUX_L402_NODE_URL"},
+                },
+            )
+        if normalized in {"invoice.verify", "preimage.redeem", "challenge.verify", "verifychallenge"}:
+            credential = payload.get("credential", payload) if isinstance(payload.get("credential", payload), dict) else {}
+            preimage = str(credential.get("preimage", payload.get("preimage", "")) or "")
+            if not preimage:
+                return {**self.accepted("invoice.verify", payload, context, status="rejected", providerPrefix="l402_verify"), "ok": False, "errors": ["missing:preimage"]}
+            return self.accepted("invoice.verify", {"challengeId": challengeId, "preimageHash": stableId("preimage", {"preimage": preimage})}, context, status="verified", providerPrefix="l402_verify")
+        return self.unsupported(action, context, f"unsupportedAction:{action}")
+
+
+def defaultAdapters() -> list[PayRailAdapter]:
+    return [
+        PicuxLedgerAdapter(),
+        X402VerifierAdapter(),
+        MppSessionAdapter(),
+        StripeSptAdapter(),
+        SolanaEscrowAdapter(),
+        BaseEscrowAdapter(),
+        L402Adapter(),
+    ]
+
+
+def _action(value: str) -> str:
+    return str(value or "").replace("_", ".").replace("-", ".").strip().lower()
+
+
+def _payTo(challenge: dict[str, Any]) -> str:
+    payee = challenge.get("payee", {}) if isinstance(challenge.get("payee"), dict) else {}
+    return str(payee.get("walletAddress", payee.get("entityId", "")) or "")
+
+
+def _firstEnv(env: Mapping[str, str], keys: tuple[str, ...]) -> str:
+    return next((key for key in keys if str(env.get(key, "") or "").strip()), "")
+
+
+def _truthy(value: Any) -> bool:
+    return str(value or "").strip().lower() in {"1", "true", "yes", "y", "live", "execute"}
+
+
+def _solanaRpc(rpcUrl: str, method: str, params: list[Any] | None = None) -> dict[str, Any]:
+    body = json.dumps({"jsonrpc": "2.0", "id": "picux-pay-preflight", "method": method, "params": params or []}, ensure_ascii=True).encode("utf-8")
+    req = request.Request(
+        rpcUrl,
+        data=body,
+        method="POST",
+        headers={"Accept": "application/json", "Content-Type": "application/json"},
+    )
+    try:
+        with request.urlopen(req, timeout=15) as response:
+            raw = response.read()
+            decoded = json.loads(raw.decode("utf-8") or "{}")
+            result = decoded.get("result", {}) if isinstance(decoded, dict) else {}
+            value = result.get("value", {}) if isinstance(result, dict) else {}
+            signature = result if isinstance(result, str) else ""
+            statuses = value if isinstance(value, list) else []
+            firstStatus = statuses[0] if statuses and isinstance(statuses[0], dict) else {}
+            return {
+                "attempted": True,
+                "ok": "error" not in decoded,
+                "method": method,
+                "endpoint": _safeRpcUrl(rpcUrl),
+                "providerStatus": int(response.status),
+                "result": result,
+                "signature": signature,
+                "confirmed": str(firstStatus.get("confirmationStatus", "") or "").lower() in {"confirmed", "finalized"} or bool(firstStatus.get("confirmations") is None and firstStatus),
+                "blockhash": str(value.get("blockhash", "") or "") if isinstance(value, dict) else "",
+                "lastValidBlockHeight": value.get("lastValidBlockHeight", "") if isinstance(value, dict) else "",
+                "error": decoded.get("error", {}) if isinstance(decoded, dict) else {},
+            }
+    except error.HTTPError as exc:
+        return {"attempted": True, "ok": False, "method": method, "endpoint": _safeRpcUrl(rpcUrl), "providerStatus": int(exc.code), "error": exc.read().decode("utf-8", errors="replace")[:500]}
+    except Exception as exc:
+        return {"attempted": True, "ok": False, "method": method, "endpoint": _safeRpcUrl(rpcUrl), "providerStatus": 0, "error": str(exc)}
+
+
+def _safeRpcUrl(rpcUrl: str) -> str:
+    parsed = urlparse(str(rpcUrl or ""))
+    if not parsed.scheme:
+        return ""
+    return f"{parsed.scheme}://{parsed.netloc}{parsed.path}"