@agentlayer.tech/wallet 0.1.12 → 0.1.14

package/agent-wallet/agent_wallet/wallet_layer/solana.py

@@ -11,7 +11,7 @@ from decimal import Decimal, InvalidOperation
 from typing import Any
 
 from agent_wallet.models import AgentWalletCapabilities, SolanaWalletState
-from agent_wallet.providers import bags, jupiter, kamino, lifi, solana_rpc
+from agent_wallet.providers import bags, houdini, jupiter, kamino, lifi, solana_rpc
 from agent_wallet.solana_stake import (
     STAKE_STATE_V2_SIZE,
     deactivate_stake as build_deactivate_stake_instruction,
@@ -46,6 +46,7 @@ TOKEN_PROGRAM_ID = "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA"
 TOKEN_2022_PROGRAM_ID = "TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb"
 NATIVE_SOL_MINT = "So11111111111111111111111111111111111111112"
 STAKE_PROGRAM_ID = "Stake11111111111111111111111111111111111111"
+HOUDINI_PRIVATE_OUTPUT_DRIFT_BPS = 600
 
 
 def _load_signing_key():
@@ -699,6 +700,862 @@ class SolanaWalletBackend(AgentWalletBackend):
             "source": "lifi",
         }
 
+    @staticmethod
+    def _houdini_token_is_native(token: dict[str, Any]) -> bool:
+        chain = str(token.get("chain") or "").strip().lower()
+        symbol = str(token.get("symbol") or "").strip().lower()
+        address = str(token.get("address") or "").strip().lower()
+        return chain == "solana" and symbol == "sol" and address in {"", "sol", "native", "11111111111111111111111111111111", NATIVE_SOL_MINT.lower()}
+
+    def _normalize_houdini_private_preview_payload(
+        self,
+        *,
+        owner: str,
+        input_token: dict[str, Any],
+        output_token: dict[str, Any],
+        destination_address: str,
+        amount_ui: Decimal,
+        quote: dict[str, Any],
+        use_xmr: bool,
+    ) -> dict[str, Any]:
+        min_private = (
+            input_token.get("min_max_private")
+            if isinstance(input_token.get("min_max_private"), dict)
+            else {}
+        )
+        return {
+            "chain": "solana",
+            "network": self.network,
+            "mode": "preview",
+            "asset_type": "solana-private-swap",
+            "owner": owner,
+            "destination_address": destination_address,
+            "input_token_query": input_token.get("symbol"),
+            "output_token_query": output_token.get("symbol"),
+            "input_token_id": input_token.get("id"),
+            "output_token_id": output_token.get("id"),
+            "input_token_symbol": input_token.get("symbol"),
+            "output_token_symbol": output_token.get("symbol"),
+            "input_token_name": input_token.get("name"),
+            "output_token_name": output_token.get("name"),
+            "input_token_address": input_token.get("address"),
+            "output_token_address": output_token.get("address"),
+            "input_token_chain": input_token.get("chain"),
+            "output_token_chain": output_token.get("chain"),
+            "input_token_decimals": input_token.get("decimals"),
+            "output_token_decimals": output_token.get("decimals"),
+            "input_is_native": self._houdini_token_is_native(input_token),
+            "output_is_native": self._houdini_token_is_native(output_token),
+            "input_amount_ui": float(amount_ui),
+            "estimated_output_amount_ui": float(Decimal(str(quote.get("amountOut") or "0"))),
+            "estimated_output_amount_usd": quote.get("amountOutUsd"),
+            "input_private_min_ui": min_private.get("min"),
+            "input_private_max_ui": min_private.get("max"),
+            "private_duration_minutes": quote.get("duration"),
+            "quote_id": quote.get("quoteId"),
+            "quote_type": quote.get("type"),
+            "rewards_available": quote.get("rewardsAvailable"),
+            "anonymous": True,
+            "use_xmr": bool(use_xmr),
+            "can_send": self.get_capabilities().can_send_transaction,
+            "sign_only": self.sign_only,
+            "source": "houdini",
+        }
+
+    async def _wait_for_houdini_order_ready(
+        self,
+        *,
+        multi_id: str,
+        houdini_id: str,
+        timeout_seconds: float = 20.0,
+        poll_interval_seconds: float = 2.0,
+    ) -> dict[str, Any]:
+        deadline = asyncio.get_running_loop().time() + timeout_seconds
+        last_order: dict[str, Any] | None = None
+        while True:
+            status_payload = await houdini.fetch_multi_status(multi_id=multi_id)
+            orders = status_payload.get("orders")
+            if isinstance(orders, list):
+                for candidate in orders:
+                    if (
+                        isinstance(candidate, dict)
+                        and str(candidate.get("houdiniId") or "").strip() == houdini_id
+                    ):
+                        last_order = candidate
+                        break
+            if last_order is None:
+                raise WalletBackendError("Houdini order disappeared before funding could start.")
+            if str(last_order.get("statusLabel") or "").strip().upper() != "INITIALIZING":
+                return last_order
+            if asyncio.get_running_loop().time() >= deadline:
+                raise WalletBackendError(
+                    "Houdini order stayed in INITIALIZING too long. Generate a new preview and try again."
+                )
+            await asyncio.sleep(poll_interval_seconds)
+
+    async def _wait_for_houdini_single_order_ready(
+        self,
+        *,
+        houdini_id: str,
+        initial_order: dict[str, Any] | None = None,
+        timeout_seconds: float = 180.0,
+        poll_interval_seconds: float = 5.0,
+    ) -> dict[str, Any]:
+        deadline = asyncio.get_running_loop().time() + timeout_seconds
+        last_order: dict[str, Any] | None = initial_order if isinstance(initial_order, dict) else None
+        while True:
+            order = await houdini.fetch_order_status(houdini_id=houdini_id)
+            if isinstance(order, dict) and order:
+                last_order = order
+            if str(order.get("statusLabel") or "").strip().upper() != "INITIALIZING":
+                return order
+            if asyncio.get_running_loop().time() >= deadline:
+                details = {
+                    "houdini_id": houdini_id,
+                    "multi_id": str((last_order or {}).get("multiId") or "").strip() or None,
+                    "deposit_address": str((last_order or {}).get("depositAddress") or "").strip() or None,
+                    "order_status": str((last_order or {}).get("statusLabel") or "").strip() or "INITIALIZING",
+                    "order": last_order or order,
+                }
+                raise WalletBackendError(
+                    "Houdini order stayed in INITIALIZING too long. Keep the created order and retry execute after the deposit account is ready.",
+                    code="houdini_order_initializing_timeout",
+                    details=details,
+                )
+            await asyncio.sleep(poll_interval_seconds)
+
+    async def _wait_for_houdini_spl_deposit_ready(
+        self,
+        *,
+        deposit_address: str,
+        mint: str,
+        timeout_seconds: float = 180.0,
+        poll_interval_seconds: float = 5.0,
+    ) -> dict[str, Any]:
+        deadline = asyncio.get_running_loop().time() + timeout_seconds
+        while True:
+            account_info = await solana_rpc.fetch_account_info(
+                deposit_address,
+                rpc_url=self.rpc_urls,
+            )
+            if account_info:
+                recipient_mint = (
+                    (account_info or {})
+                    .get("data", {})
+                    .get("parsed", {})
+                    .get("info", {})
+                    .get("mint")
+                )
+                if recipient_mint and str(recipient_mint).strip() != mint:
+                    raise WalletBackendError(
+                        "Houdini deposit token account mint does not match the approved input token."
+                    )
+                return {
+                    "deposit_address": deposit_address,
+                    "account_info": account_info,
+                    "mint": recipient_mint,
+                }
+            if asyncio.get_running_loop().time() >= deadline:
+                raise WalletBackendError(
+                    "Houdini order was created, but the Solana deposit token account was not ready in time. Generate a new preview and try again.",
+                    code="houdini_deposit_not_ready",
+                    details={"deposit_address": deposit_address, "mint": mint},
+                )
+            await asyncio.sleep(poll_interval_seconds)
+
+    async def preview_solana_private_swap(
+        self,
+        *,
+        input_token: str,
+        output_token: str,
+        destination_address: str,
+        amount_ui: float,
+        use_xmr: bool = False,
+    ) -> dict[str, Any]:
+        if self.network != "mainnet":
+            raise WalletBackendError("Houdini private Solana swaps are only enabled for Solana mainnet.")
+        owner = await self.get_address()
+        if not owner:
+            raise WalletBackendError(
+                "No Solana wallet address configured. Set SOLANA_AGENT_PUBLIC_KEY or a signer."
+            )
+        if not isinstance(destination_address, str) or not destination_address.strip():
+            raise WalletBackendError("destination_address is required.")
+        destination_address = validate_solana_address(destination_address.strip())
+        if not isinstance(amount_ui, (int, float)) or amount_ui <= 0:
+            raise WalletBackendError("amount must be a positive number.")
+
+        amount_decimal = Decimal(str(amount_ui))
+        resolved_input = await houdini.resolve_cex_token(term=input_token, chain="solana")
+        resolved_output = await houdini.resolve_cex_token(term=output_token, chain="solana")
+        if str(resolved_input.get("id") or "") != str(resolved_output.get("id") or ""):
+            raise WalletBackendError(
+                "The initial Houdini Solana private route supports same-token private payouts only. "
+                "Use the same token for input and output, for example SOL->SOL or USDC->USDC."
+            )
+
+        private_quotes = await houdini.fetch_private_quotes(
+            from_token_id=str(resolved_input["id"]),
+            to_token_id=str(resolved_output["id"]),
+            amount_ui=amount_decimal,
+        )
+        best_quote = houdini.select_best_private_quote(private_quotes)
+        return self._normalize_houdini_private_preview_payload(
+            owner=owner,
+            input_token=resolved_input,
+            output_token=resolved_output,
+            destination_address=destination_address,
+            amount_ui=amount_decimal,
+            quote=best_quote,
+            use_xmr=use_xmr,
+        )
+
+    async def get_solana_private_swap_status(
+        self,
+        *,
+        multi_id: str | None = None,
+        houdini_id: str | None = None,
+    ) -> dict[str, Any]:
+        if self.network != "mainnet":
+            raise WalletBackendError("Houdini private Solana swaps are only enabled for Solana mainnet.")
+        normalized_multi_id = str(multi_id or "").strip()
+        normalized_houdini_id = str(houdini_id or "").strip()
+        if not normalized_multi_id and not normalized_houdini_id:
+            raise WalletBackendError("multi_id or houdini_id is required.")
+
+        if not normalized_multi_id:
+            selected_order = await houdini.fetch_order_status(houdini_id=normalized_houdini_id)
+            selected_status = str(selected_order.get("statusLabel") or "").strip() or None
+            terminal_statuses = {"FINISHED", "FAILED", "EXPIRED", "REFUNDED"}
+            return {
+                "chain": "solana",
+                "network": self.network,
+                "asset_type": "solana-private-swap",
+                "multi_id": None,
+                "order_count": 1,
+                "orders": [selected_order],
+                "selected_order": selected_order,
+                "selected_houdini_id": (
+                    str(selected_order.get("houdiniId") or "").strip() or normalized_houdini_id or None
+                ),
+                "selected_status": selected_status,
+                "all_terminal": bool(selected_status and selected_status.upper() in terminal_statuses),
+                "source": "houdini",
+            }
+
+        payload = await houdini.fetch_multi_status(multi_id=normalized_multi_id)
+        orders = payload.get("orders") if isinstance(payload.get("orders"), list) else []
+        selected_order = None
+        if normalized_houdini_id:
+            for order in orders:
+                if isinstance(order, dict) and str(order.get("houdiniId") or "").strip() == normalized_houdini_id:
+                    selected_order = order
+                    break
+            if selected_order is None:
+                raise WalletBackendError("houdini_id was not found inside the requested multi_id.")
+        elif len(orders) == 1 and isinstance(orders[0], dict):
+            selected_order = orders[0]
+
+        terminal_statuses = {"FINISHED", "FAILED", "EXPIRED", "REFUNDED"}
+        return {
+            "chain": "solana",
+            "network": self.network,
+            "asset_type": "solana-private-swap",
+            "multi_id": payload.get("multiId") or normalized_multi_id,
+            "order_count": len([item for item in orders if isinstance(item, dict)]),
+            "orders": orders,
+            "selected_order": selected_order,
+            "selected_houdini_id": (
+                str(selected_order.get("houdiniId") or "").strip()
+                if isinstance(selected_order, dict)
+                else None
+            ),
+            "selected_status": (
+                str(selected_order.get("statusLabel") or "").strip()
+                if isinstance(selected_order, dict)
+                else None
+            ),
+            "all_terminal": all(
+                isinstance(item, dict)
+                and str(item.get("statusLabel") or "").strip().upper() in terminal_statuses
+                for item in orders
+            )
+            if orders
+            else False,
+            "source": "houdini",
+        }
+
+    @staticmethod
+    def _pick_houdini_order_value(order: dict[str, Any], *keys: str) -> str:
+        for key in keys:
+            value = order.get(key)
+            if isinstance(value, str) and value.strip():
+                return value.strip()
+            if isinstance(value, (int, float, Decimal)):
+                text = str(value).strip()
+                if text:
+                    return text
+        return ""
+
+    @staticmethod
+    def _normalize_houdini_token_address(value: str) -> str:
+        normalized = str(value or "").strip()
+        if not normalized:
+            return ""
+        lowered = normalized.lower()
+        if lowered in {"sol", "native", "11111111111111111111111111111111"}:
+            return NATIVE_SOL_MINT.lower()
+        return lowered
+
+    def _validate_houdini_order_against_preview(
+        self,
+        *,
+        order: dict[str, Any],
+        preview: dict[str, Any],
+    ) -> dict[str, Any]:
+        if str(order.get("receiverAddress") or "").strip() != str(preview["destination_address"]):
+            raise WalletBackendError("Houdini order receiverAddress does not match the approved destination.")
+        if not bool(order.get("anonymous")):
+            raise WalletBackendError("Houdini order is not marked anonymous as required.")
+
+        checks: dict[str, Any] = {
+            "receiver_address": str(order.get("receiverAddress") or "").strip(),
+            "anonymous": bool(order.get("anonymous")),
+        }
+        warnings: list[str] = []
+
+        expected_input_id = str(preview.get("input_token_id") or "").strip()
+        order_input_id = self._pick_houdini_order_value(
+            order,
+            "from",
+            "fromId",
+            "inId",
+            "inputTokenId",
+            "fromTokenId",
+        )
+        if expected_input_id and order_input_id and order_input_id != expected_input_id:
+            raise WalletBackendError("Houdini order input token id does not match the approved token.")
+        checks["input_token_id"] = order_input_id or expected_input_id or None
+
+        expected_input_amount = Decimal(str(preview.get("input_amount_ui") or "0"))
+        order_input_amount = Decimal(
+            self._pick_houdini_order_value(order, "inAmount", "amountIn", "inputAmount") or "0"
+        )
+        if order_input_amount != expected_input_amount:
+            raise WalletBackendError("Houdini order input amount does not match the approved preview.")
+        checks["input_amount_ui"] = str(order_input_amount)
+
+        expected_output_id = str(preview.get("output_token_id") or "").strip()
+        order_output_id = self._pick_houdini_order_value(
+            order,
+            "to",
+            "toId",
+            "outId",
+            "outputTokenId",
+            "toTokenId",
+        )
+        if expected_output_id and order_output_id and order_output_id != expected_output_id:
+            raise WalletBackendError("Houdini order output token id does not match the approved token.")
+        checks["output_token_id"] = order_output_id or expected_output_id or None
+
+        expected_input_address = self._normalize_houdini_token_address(
+            str(preview.get("input_token_address") or "")
+        )
+        order_input_address = self._normalize_houdini_token_address(
+            self._pick_houdini_order_value(
+                order,
+                "fromAddress",
+                "inAddress",
+                "inputTokenAddress",
+                "fromTokenAddress",
+            )
+        )
+        if expected_input_address and order_input_address and order_input_address != expected_input_address:
+            raise WalletBackendError("Houdini order input token address does not match the approved token.")
+        checks["input_token_address"] = order_input_address or expected_input_address or None
+
+        expected_output_address = self._normalize_houdini_token_address(
+            str(preview.get("output_token_address") or "")
+        )
+        order_output_address = self._normalize_houdini_token_address(
+            self._pick_houdini_order_value(
+                order,
+                "toAddress",
+                "outAddress",
+                "outputTokenAddress",
+                "toTokenAddress",
+            )
+        )
+        if expected_output_address and order_output_address and order_output_address != expected_output_address:
+            raise WalletBackendError("Houdini order output token address does not match the approved token.")
+        checks["output_token_address"] = order_output_address or expected_output_address or None
+
+        expected_input_symbol = str(preview.get("input_token_symbol") or "").strip().upper()
+        order_input_symbol = self._pick_houdini_order_value(order, "inSymbol", "fromSymbol").upper()
+        if expected_input_symbol and order_input_symbol and order_input_symbol != expected_input_symbol:
+            warnings.append(
+                "Houdini order input token symbol differs from the approved preview display symbol."
+            )
+        checks["input_token_symbol"] = order_input_symbol or expected_input_symbol or None
+
+        expected_output_symbol = str(preview.get("output_token_symbol") or "").strip().upper()
+        order_output_symbol = self._pick_houdini_order_value(order, "outSymbol", "toSymbol").upper()
+        if expected_output_symbol and order_output_symbol and order_output_symbol != expected_output_symbol:
+            warnings.append(
+                "Houdini order output token symbol differs from the approved preview display symbol."
+            )
+        checks["output_token_symbol"] = order_output_symbol or expected_output_symbol or None
+
+        return {
+            "validated": True,
+            "checks": checks,
+            "warnings": warnings,
+        }
+
+    def _validate_houdini_order_output_against_preview(
+        self,
+        *,
+        order: dict[str, Any],
+        preview: dict[str, Any],
+    ) -> dict[str, Any]:
+        expected_output = Decimal(str(preview["estimated_output_amount_ui"]))
+        order_output = Decimal(
+            self._pick_houdini_order_value(order, "outAmount", "amountOut", "outputAmount") or "0"
+        )
+        tolerance = (
+            expected_output * Decimal(HOUDINI_PRIVATE_OUTPUT_DRIFT_BPS) / Decimal(10_000)
+        )
+        minimum_allowed = expected_output - tolerance
+        if order_output < minimum_allowed:
+            raise WalletBackendError(
+                "Houdini order output fell materially below the approved preview. Generate a new preview and approval before execute.",
+                code="private_swap_quote_changed",
+                details={
+                    "approved_estimated_output_amount_ui": str(expected_output),
+                    "order_output_amount_ui": str(order_output),
+                    "minimum_allowed_output_amount_ui": str(minimum_allowed),
+                    "allowed_drift_bps": HOUDINI_PRIVATE_OUTPUT_DRIFT_BPS,
+                },
+            )
+        warnings: list[str] = []
+        if order_output < expected_output:
+            warnings.append(
+                "Houdini order output drifted slightly below the approved preview but stayed within the allowed tolerance."
+            )
+        return {
+            "validated": True,
+            "approved_estimated_output_amount_ui": str(expected_output),
+            "order_output_amount_ui": str(order_output),
+            "minimum_allowed_output_amount_ui": str(minimum_allowed),
+            "allowed_drift_bps": HOUDINI_PRIVATE_OUTPUT_DRIFT_BPS,
+            "warnings": warnings,
+        }
+
+    async def _send_houdini_exact_spl_deposit(
+        self,
+        *,
+        recipient_token_account: str,
+        mint: str,
+        amount_raw: int,
+        decimals: int,
+    ) -> dict[str, Any]:
+        if not self.signer:
+            raise WalletBackendError("Solana signer is not configured.")
+
+        sender = await self.get_address()
+        if not sender:
+            raise WalletBackendError(
+                "No Solana wallet address configured. Set SOLANA_AGENT_PUBLIC_KEY or a signer."
+            )
+
+        recipient_token_account = validate_solana_address(recipient_token_account)
+        mint = validate_solana_mint(mint)
+        if amount_raw <= 0:
+            raise WalletBackendError("Houdini SPL deposit amount must be greater than zero.")
+
+        try:
+            from solders.hash import Hash
+            from solders.keypair import Keypair
+            from solders.message import Message
+            from solders.pubkey import Pubkey
+            from solders.transaction import Transaction
+            from spl.token.instructions import (
+                TransferCheckedParams,
+                get_associated_token_address,
+                transfer_checked,
+            )
+        except ImportError as exc:
+            raise WalletBackendError(
+                "solana and solders packages are required for SPL token transfers."
+            ) from exc
+
+        sender_pubkey = Pubkey.from_string(sender)
+        mint_pubkey = Pubkey.from_string(mint)
+        token_program_id = await self._resolve_token_program_id(mint)
+        token_program_pubkey = Pubkey.from_string(token_program_id)
+        sender_token_account = str(
+            get_associated_token_address(
+                sender_pubkey,
+                mint_pubkey,
+                token_program_id=token_program_pubkey,
+            )
+        )
+        sender_token_account_exists = await solana_rpc.account_exists(
+            sender_token_account,
+            rpc_url=self.rpc_urls,
+        )
+        if not sender_token_account_exists:
+            raise WalletBackendError("Sender token account does not exist for this mint.")
+        original_deposit_address = recipient_token_account
+        await self._wait_for_houdini_spl_deposit_ready(
+            deposit_address=recipient_token_account,
+            mint=mint,
+        )
+
+        sender_balance = await solana_rpc.fetch_token_account_balance(
+            sender_token_account,
+            rpc_url=self.rpc_urls,
+        )
+        sender_raw_balance = int(sender_balance.get("amount") or 0)
+        if amount_raw > sender_raw_balance:
+            raise WalletBackendError("Insufficient token balance for this private transfer.")
+
+        latest_blockhash = await solana_rpc.fetch_latest_blockhash(
+            rpc_url=self.rpc_urls,
+            commitment=self.commitment,
+        )
+        blockhash = Hash.from_string(str(latest_blockhash["blockhash"]))
+        keypair = Keypair.from_bytes(self.signer.export_keypair_bytes())
+        message = Message.new_with_blockhash(
+            [
+                transfer_checked(
+                    TransferCheckedParams(
+                        program_id=token_program_pubkey,
+                        source=Pubkey.from_string(sender_token_account),
+                        mint=mint_pubkey,
+                        dest=Pubkey.from_string(recipient_token_account),
+                        owner=sender_pubkey,
+                        amount=amount_raw,
+                        decimals=decimals,
+                        signers=[],
+                    )
+                )
+            ],
+            sender_pubkey,
+            blockhash,
+        )
+        transaction = Transaction([keypair], message, blockhash)
+        submitted = await solana_rpc.send_transaction(
+            transaction_base64=encode_transaction_base64(bytes(transaction)),
+            rpc_url=self.rpc_urls,
+        )
+        signature = submitted.get("signature")
+        status = None
+        confirmed = False
+        if isinstance(signature, str) and signature:
+            status = await solana_rpc.wait_for_confirmation(
+                signature=signature,
+                rpc_url=self.rpc_urls,
+            )
+            confirmed = status is not None
+
+        return {
+            "chain": "solana",
+            "network": self.network,
+            "mode": "execute",
+            "asset_type": "spl",
+            "from_address": sender,
+            "to_address": recipient_token_account,
+            "requested_deposit_address": original_deposit_address,
+            "deposit_address_interpretation": "token_account",
+            "mint": mint,
+            "token_program_id": token_program_id,
+            "sender_token_account": sender_token_account,
+            "recipient_token_account": recipient_token_account,
+            "recipient_token_account_exists_before": True,
+            "recipient_token_account_created": False,
+            "amount_ui": float(Decimal(amount_raw) / (Decimal(10) ** decimals)),
+            "amount_raw": amount_raw,
+            "decimals": decimals,
+            "signature": signature,
+            "broadcasted": bool(signature),
+            "confirmed": confirmed,
+            "confirmation_status": status.get("confirmationStatus") if status else None,
+            "slot": status.get("slot") if status else None,
+            "sign_only": self.sign_only,
+            "source": "solana-rpc",
+            "execute_response": submitted,
+        }
+
+    async def execute_solana_private_swap(
+        self,
+        *,
+        input_token: str,
+        output_token: str,
+        destination_address: str,
+        amount_ui: float,
+        use_xmr: bool = False,
+        approved_preview: dict[str, Any] | None = None,
+        existing_order: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        if self.network != "mainnet":
+            raise WalletBackendError("Houdini private Solana swaps are only enabled for Solana mainnet.")
+        if not self.signer:
+            raise WalletBackendError("Solana signer is not configured.")
+        if self.sign_only:
+            raise WalletBackendError(
+                "This wallet backend is in sign-only mode. Disable sign_only to broadcast transactions."
+            )
+
+        preview = (
+            dict(approved_preview)
+            if isinstance(approved_preview, dict)
+            else await self.preview_solana_private_swap(
+                input_token=input_token,
+                output_token=output_token,
+                destination_address=destination_address,
+                amount_ui=amount_ui,
+                use_xmr=use_xmr,
+            )
+        )
+        owner = str(preview.get("owner") or await self.get_address() or "").strip()
+        if not owner:
+            raise WalletBackendError("No Solana wallet address configured for Houdini execution.")
+
+        quote_id = str(preview.get("quote_id") or "").strip()
+        if not quote_id:
+            raise WalletBackendError("Approved private swap preview is missing quote_id.")
+
+        if isinstance(existing_order, dict) and existing_order:
+            create_payload = dict(existing_order)
+            order = (
+                create_payload.get("order")
+                if isinstance(create_payload.get("order"), dict)
+                else create_payload
+            )
+            if not isinstance(order, dict):
+                raise WalletBackendError("Stored Houdini private swap order is invalid.")
+            multi_id = str(create_payload.get("multi_id") or create_payload.get("multiId") or order.get("multiId") or "").strip() or None
+            houdini_id = str(
+                create_payload.get("houdini_id")
+                or create_payload.get("houdiniId")
+                or order.get("houdiniId")
+                or ""
+            ).strip()
+            if not houdini_id:
+                raise WalletBackendError("Stored Houdini private swap order is missing houdini_id.")
+            latest_order = await houdini.fetch_order_status(houdini_id=houdini_id)
+            if isinstance(latest_order, dict) and latest_order:
+                order = latest_order
+
+            order_validation = self._validate_houdini_order_against_preview(
+                order=order,
+                preview=preview,
+            )
+            output_validation = self._validate_houdini_order_output_against_preview(
+                order=order,
+                preview=preview,
+            )
+            input_decimals = int(preview.get("input_token_decimals") or (9 if bool(preview.get("input_is_native")) else 0))
+            input_amount_raw = int(
+                (Decimal(str(preview["input_amount_ui"])) * (Decimal(10) ** input_decimals))
+                .to_integral_value()
+            )
+            deposit_address = str(order.get("depositAddress") or "").strip()
+            if not deposit_address:
+                raise WalletBackendError("Houdini private swap response is missing depositAddress.")
+
+            if bool(preview.get("input_is_native")):
+                funding_result = await self.send_native_transfer(
+                    recipient=deposit_address,
+                    amount_native=float(Decimal(str(preview["input_amount_ui"]))),
+                )
+            else:
+                try:
+                    funding_result = await self._send_houdini_exact_spl_deposit(
+                        recipient_token_account=deposit_address,
+                        mint=str(preview.get("input_token_address") or "").strip(),
+                        amount_raw=input_amount_raw,
+                        decimals=input_decimals,
+                    )
+                except WalletBackendError as exc:
+                    if exc.code == "houdini_deposit_not_ready":
+                        details = dict(exc.details or {})
+                        details.update(
+                            {
+                                "multi_id": multi_id,
+                                "houdini_id": houdini_id,
+                                "deposit_address": deposit_address,
+                                "order_status": order.get("statusLabel"),
+                                "order": order,
+                                "input_token_address": str(preview.get("input_token_address") or "").strip(),
+                                "input_amount_raw": str(input_amount_raw),
+                                "input_decimals": input_decimals,
+                            }
+                        )
+                        raise WalletBackendError(
+                            "Houdini order exists, but its Solana deposit account is not ready yet. Retry continue for the existing order instead of generating a new preview.",
+                            code="houdini_deposit_not_ready",
+                            details=details,
+                        ) from exc
+                    raise
+
+            signature = str(funding_result.get("signature") or "").strip() or None
+            confirmed = bool(funding_result.get("confirmed"))
+
+            return {
+                "chain": "solana",
+                "network": self.network,
+                "mode": "execute",
+                "asset_type": "solana-private-swap",
+                "owner": owner,
+                "destination_address": str(preview["destination_address"]),
+                "input_token_id": preview["input_token_id"],
+                "output_token_id": preview["output_token_id"],
+                "input_token_symbol": preview["input_token_symbol"],
+                "output_token_symbol": preview["output_token_symbol"],
+                "input_token_address": preview["input_token_address"],
+                "output_token_address": preview["output_token_address"],
+                "input_is_native": bool(preview.get("input_is_native")),
+                "input_amount_ui": preview["input_amount_ui"],
+                "estimated_output_amount_ui": preview["estimated_output_amount_ui"],
+                "private_duration_minutes": order.get("eta") or preview.get("private_duration_minutes"),
+                "multi_id": multi_id,
+                "houdini_id": houdini_id,
+                "deposit_address": deposit_address,
+                "order_status": order.get("statusLabel"),
+                "order": order,
+                "signature": signature,
+                "broadcasted": bool(signature),
+                "confirmed": confirmed,
+                "confirmation_status": funding_result.get("confirmation_status"),
+                "slot": funding_result.get("slot"),
+                "verification": {
+                    "verified": True,
+                    "deposit_address": deposit_address,
+                    "amount_raw": str(input_amount_raw),
+                    "is_native_input": bool(preview.get("input_is_native")),
+                    "token_mint": (
+                        None
+                        if bool(preview.get("input_is_native"))
+                        else str(preview.get("input_token_address") or "").strip()
+                    ),
+                    "quote_bound_single_exchange": True,
+                },
+                "simulation": None,
+                "provider_order_validation": order_validation,
+                "output_validation": output_validation,
+                "funding_transfer": funding_result,
+                "execute_response": funding_result.get("execute_response"),
+                "status_tracking": {
+                    "multi_id": multi_id,
+                    "houdini_id": houdini_id,
+                    "poll_status_tool": "get_solana_private_swap_status",
+                },
+                "source": "houdini",
+                "execution_state": "funding_submitted",
+            }
+        else:
+            try:
+                create_payload = await houdini.create_exchange(
+                    quote_id=quote_id,
+                    destination_address=str(preview["destination_address"]),
+                )
+            except ProviderError as exc:
+                details = dict(exc.details or {})
+                gateway_error = details.get("error") if isinstance(details.get("error"), dict) else None
+                if isinstance(gateway_error, dict) and str(gateway_error.get("code") or "").strip() == "RATE_LIMIT_EXCEEDED":
+                    retry_after = gateway_error.get("retryAfter")
+                    raise WalletBackendError(
+                        "Houdini exchange create is rate-limited right now. Wait and retry execute without generating a new preview.",
+                        code="houdini_exchange_rate_limited",
+                        details={
+                            "retry_after": retry_after,
+                            "quote_id": quote_id,
+                            "destination_address": str(preview["destination_address"]),
+                            "provider": getattr(exc, "provider", "houdini"),
+                            "upstream_error": gateway_error,
+                        },
+                    ) from exc
+                raise
+            order = create_payload.get("order") if isinstance(create_payload.get("order"), dict) else create_payload
+            if not isinstance(order, dict):
+                raise WalletBackendError("Houdini returned no order object for the private swap.")
+            if isinstance(order.get("error"), dict):
+                error = order["error"]
+                raise WalletBackendError(
+                    f"Houdini rejected the private swap request: {error.get('message') or 'unknown error'}.",
+                    code=str(error.get("code") or "").strip() or None,
+                    details=error,
+                )
+
+            multi_id = str(create_payload.get("multiId") or order.get("multiId") or "").strip() or None
+            houdini_id = str(order.get("houdiniId") or create_payload.get("houdiniId") or "").strip()
+            if not houdini_id:
+                raise WalletBackendError("Houdini private swap response is missing the order identifier.")
+            deposit_address = str(order.get("depositAddress") or "").strip()
+            if not deposit_address:
+                raise WalletBackendError("Houdini private swap response is missing depositAddress.")
+
+            order_validation = self._validate_houdini_order_against_preview(
+                order=order,
+                preview=preview,
+            )
+            output_validation = self._validate_houdini_order_output_against_preview(
+                order=order,
+                preview=preview,
+            )
+
+            return {
+                "chain": "solana",
+                "network": self.network,
+                "mode": "execute",
+                "asset_type": "solana-private-swap",
+                "owner": owner,
+                "destination_address": str(preview["destination_address"]),
+                "input_token_id": preview["input_token_id"],
+                "output_token_id": preview["output_token_id"],
+                "input_token_symbol": preview["input_token_symbol"],
+                "output_token_symbol": preview["output_token_symbol"],
+                "input_token_address": preview["input_token_address"],
+                "output_token_address": preview["output_token_address"],
+                "input_is_native": bool(preview.get("input_is_native")),
+                "input_amount_ui": preview["input_amount_ui"],
+                "estimated_output_amount_ui": preview["estimated_output_amount_ui"],
+                "private_duration_minutes": order.get("eta") or preview.get("private_duration_minutes"),
+                "multi_id": multi_id,
+                "houdini_id": houdini_id,
+                "deposit_address": deposit_address,
+                "order_status": order.get("statusLabel"),
+                "order": order,
+                "provider_order_validation": order_validation,
+                "output_validation": output_validation,
+                "status_tracking": {
+                    "multi_id": multi_id,
+                    "houdini_id": houdini_id,
+                    "poll_status_tool": "get_solana_private_swap_status",
+                },
+                "source": "houdini",
+                "execution_state": "awaiting_deposit_funding",
+                "next_step": "Call continue_solana_private_swap with the same approved private swap context to submit the funding transfer.",
+            }
+
+    async def continue_solana_private_swap(
+        self,
+        *,
+        approved_preview: dict[str, Any],
+        existing_order: dict[str, Any],
+    ) -> dict[str, Any]:
+        return await self.execute_solana_private_swap(
+            input_token=str(approved_preview.get("input_token_query") or approved_preview.get("input_token_symbol") or ""),
+            output_token=str(approved_preview.get("output_token_query") or approved_preview.get("output_token_symbol") or ""),
+            destination_address=str(approved_preview.get("destination_address") or ""),
+            amount_ui=float(approved_preview.get("input_amount_ui") or 0),
+            use_xmr=bool(approved_preview.get("use_xmr", False)),
+            approved_preview=approved_preview,
+            existing_order=existing_order,
+        )
+
     async def preview_solana_lifi_cross_chain_swap(
         self,
         *,
@@ -2250,28 +3107,40 @@ class SolanaWalletBackend(AgentWalletBackend):
         try:
             from solders.keypair import Keypair
             from solders.message import to_bytes_versioned
-            from solders.transaction import VersionedTransaction
+            from solders.transaction import Transaction, VersionedTransaction
         except ImportError as exc:
             raise WalletBackendError(
                 "solana and solders packages are required for provider transaction signing."
             ) from exc
 
-        unsigned_transaction = VersionedTransaction.from_bytes(
-            self._bags_decode_serialized_transaction_bytes(transaction_base64)
-        )
+        raw_transaction = self._bags_decode_serialized_transaction_bytes(transaction_base64)
         keypair = Keypair.from_bytes(self.signer.export_keypair_bytes())
-        signature = keypair.sign_message(to_bytes_versioned(unsigned_transaction.message))
-        signatures = list(unsigned_transaction.signatures)
-        if wallet_signer_index >= len(signatures):
-            raise WalletBackendError(
-                "Provider transaction signer layout is incompatible with local signing."
+        try:
+            unsigned_transaction = VersionedTransaction.from_bytes(raw_transaction)
+            signature = keypair.sign_message(to_bytes_versioned(unsigned_transaction.message))
+            signatures = list(unsigned_transaction.signatures)
+            if wallet_signer_index >= len(signatures):
+                raise WalletBackendError(
+                    "Provider transaction signer layout is incompatible with local signing."
+                )
+            signatures[wallet_signer_index] = signature
+            signed_transaction = VersionedTransaction.populate(
+                unsigned_transaction.message,
+                signatures,
             )
-        signatures[wallet_signer_index] = signature
-        signed_transaction = VersionedTransaction.populate(
-            unsigned_transaction.message,
-            signatures,
-        )
-        return encode_transaction_base64(bytes(signed_transaction))
+            return encode_transaction_base64(bytes(signed_transaction))
+        except Exception:
+            unsigned_transaction = Transaction.from_bytes(raw_transaction)
+            signatures = list(unsigned_transaction.signatures)
+            if wallet_signer_index >= len(signatures):
+                raise WalletBackendError(
+                    "Provider transaction signer layout is incompatible with local signing."
+                )
+            unsigned_transaction.partial_sign(
+                [keypair],
+                unsigned_transaction.message.recent_blockhash,
+            )
+            return encode_transaction_base64(bytes(unsigned_transaction))
 
     async def _prepare_jupiter_lend_transaction(
         self,