swig-developer-sdk 0.6.0__py3-none-any.whl

swig_developer_sdk/__init__.py

@@ -0,0 +1,180 @@
+from .client import SwigClient, SwigServerClient
+from .common import (
+    DEFAULT_BACKEND_URL,
+    Amount,
+    JsonObject,
+    JsonValue,
+    Network,
+    RetryOptions,
+    WalletAddressInfo,
+    WalletAuthority,
+)
+from .core import SwigDeveloperSdkError
+from .evm import Eip1193Provider, create_secp256k1_evm_signing_fn
+from .one_business import (
+    DEFAULT_ONE_BUSINESS_URL,
+    OneBusinessGrantAccessCallbackError,
+    OneBusinessGrantAccessResult,
+    OneBusinessLocation,
+    build_one_business_grant_access_url,
+    complete_one_business_grant_access,
+    redirect_to_one_business_grant_access,
+)
+from .passkeys import (
+    WebAuthnAssertion,
+    create_secp256r1_passkey_signing_fn,
+    secp256r1_der_to_raw_signature,
+)
+from .paymaster import PaymasterBalance, PaymasterClient
+from .proxy import (
+    ProxyResponse,
+    ProxyWalletReference,
+    SwigProxyConfig,
+    SwigProxyHandler,
+    SwigRouteContext,
+    create_swig_proxy_handler,
+)
+from .ramp import (
+    CreateRampSessionArgs,
+    CreateRampSessionResult,
+    GetRampOptionsResult,
+    GetRampTransactionResult,
+    ListRampTransactionsResult,
+    QuoteRampArgs,
+    QuoteRampResult,
+    RampClient,
+    RampCustomerContext,
+    RampPaymentMethodType,
+    RampQuote,
+    RampServiceProvider,
+    RampTransaction,
+    RampTransactionStatus,
+    RampTransactionType,
+    RampWalletContext,
+    ramp_customer,
+)
+from .signing import (
+    PasskeySigningFn,
+    PasskeySigningResult,
+    PreparedTransactionSigner,
+    Secp256k1SigningFn,
+    Secp256k1SigningResult,
+    sign_prepared_swig_transaction,
+    sign_prepared_swig_transactions,
+    sign_prepared_transaction,
+    sign_prepared_transaction_with_signer,
+)
+from .transactions import (
+    ClientSignatureRequest,
+    PreparedTransaction,
+    PreparedTransactionsResult,
+    SignedPreparedTransaction,
+    SponsorSignedTransactionArgs,
+    SubmittedTransaction,
+    TransactionsClient,
+)
+from .wallets import (
+    CreateWalletResult,
+    IdpWalletSession,
+    ListSwigTokenBalancesResult,
+    ListSwigTokenTransactionsResult,
+    Policy,
+    PreparedRecoverySetupResult,
+    RecoveryOptions,
+    RecoverySetupPlan,
+    SolanaAccountMeta,
+    SolanaInstructionInput,
+    SwigTokenBalance,
+    SwigTokenTransaction,
+    SwigUsdBalance,
+    TransferSolOperation,
+    TransferTokenOperation,
+    WalletHandle,
+    WalletReference,
+    WalletsClient,
+)
+
+__all__ = [
+    "DEFAULT_BACKEND_URL",
+    "DEFAULT_ONE_BUSINESS_URL",
+    "Amount",
+    "ClientSignatureRequest",
+    "CreateRampSessionArgs",
+    "CreateRampSessionResult",
+    "CreateWalletResult",
+    "Eip1193Provider",
+    "GetRampOptionsResult",
+    "GetRampTransactionResult",
+    "IdpWalletSession",
+    "JsonObject",
+    "JsonValue",
+    "ListRampTransactionsResult",
+    "ListSwigTokenBalancesResult",
+    "ListSwigTokenTransactionsResult",
+    "Network",
+    "OneBusinessGrantAccessCallbackError",
+    "OneBusinessGrantAccessResult",
+    "OneBusinessLocation",
+    "PasskeySigningFn",
+    "PasskeySigningResult",
+    "PaymasterBalance",
+    "PaymasterClient",
+    "Policy",
+    "PreparedRecoverySetupResult",
+    "PreparedTransaction",
+    "PreparedTransactionSigner",
+    "PreparedTransactionsResult",
+    "ProxyResponse",
+    "ProxyWalletReference",
+    "QuoteRampArgs",
+    "QuoteRampResult",
+    "RampClient",
+    "RampCustomerContext",
+    "RampPaymentMethodType",
+    "RampQuote",
+    "RampServiceProvider",
+    "RampTransaction",
+    "RampTransactionStatus",
+    "RampTransactionType",
+    "RampWalletContext",
+    "RecoveryOptions",
+    "RecoverySetupPlan",
+    "RetryOptions",
+    "Secp256k1SigningFn",
+    "Secp256k1SigningResult",
+    "SignedPreparedTransaction",
+    "SolanaAccountMeta",
+    "SolanaInstructionInput",
+    "SponsorSignedTransactionArgs",
+    "SubmittedTransaction",
+    "SwigClient",
+    "SwigDeveloperSdkError",
+    "SwigProxyConfig",
+    "SwigProxyHandler",
+    "SwigRouteContext",
+    "SwigServerClient",
+    "SwigTokenBalance",
+    "SwigTokenTransaction",
+    "SwigUsdBalance",
+    "TransactionsClient",
+    "TransferSolOperation",
+    "TransferTokenOperation",
+    "WalletAddressInfo",
+    "WalletAuthority",
+    "WalletHandle",
+    "WalletReference",
+    "WalletsClient",
+    "WebAuthnAssertion",
+    "build_one_business_grant_access_url",
+    "complete_one_business_grant_access",
+    "create_secp256k1_evm_signing_fn",
+    "create_secp256r1_passkey_signing_fn",
+    "create_swig_proxy_handler",
+    "ramp_customer",
+    "redirect_to_one_business_grant_access",
+    "secp256r1_der_to_raw_signature",
+    "sign_prepared_swig_transaction",
+    "sign_prepared_swig_transactions",
+    "sign_prepared_transaction",
+    "sign_prepared_transaction_with_signer",
+]

swig_developer_sdk/client.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+import httpx
+
+from .common import DEFAULT_BACKEND_URL, Network, RetryOptions
+from .core import HttpClient
+from .paymaster import PaymasterClient
+from .ramp import RampClient
+from .transactions import TransactionsClient
+from .wallets import WalletsClient
+
+
+class SwigClient:
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        base_url: str = DEFAULT_BACKEND_URL,
+        network: Network | None = None,
+        retry_options: RetryOptions | None = None,
+        transport: httpx.AsyncBaseTransport | None = None,
+    ) -> None:
+        self.default_network = network
+        http = HttpClient(
+            api_key=api_key,
+            base_url=base_url,
+            retry=retry_options or RetryOptions(),
+            transport=transport,
+        )
+        self.paymaster = PaymasterClient(http, network)
+        self.ramp = RampClient(http, network)
+        self.transactions = TransactionsClient(http, network)
+        self.wallets = WalletsClient(http, network)
+
+
+SwigServerClient = SwigClient

swig_developer_sdk/common.py

@@ -0,0 +1,104 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Literal, TypeAlias
+
+Network: TypeAlias = Literal["mainnet", "devnet"]
+Amount: TypeAlias = int | str
+JsonScalar: TypeAlias = str | int | float | bool | None
+JsonValue: TypeAlias = JsonScalar | list["JsonValue"] | dict[str, "JsonValue"]
+JsonObject: TypeAlias = dict[str, JsonValue]
+WalletAuthority: TypeAlias = Mapping[str, Mapping[str, object]]
+
+DEFAULT_BACKEND_URL = "https://backend.prod.infra.onswig.com"
+
+
+@dataclass(frozen=True, slots=True)
+class RetryOptions:
+    max_retries: int = 3
+    retry_delay: float = 1.0
+    backoff_multiplier: float = 2.0
+
+    def __post_init__(self) -> None:
+        if self.max_retries < 0:
+            raise ValueError("max_retries must be non-negative")
+        if self.retry_delay < 0:
+            raise ValueError("retry_delay must be non-negative")
+        if self.backoff_multiplier < 0:
+            raise ValueError("backoff_multiplier must be non-negative")
+
+
+@dataclass(frozen=True, slots=True)
+class WalletAddressInfo:
+    swig_config_address: str
+    wallet_address: str
+    network: Network | None = None
+
+
+def wallet_address_info_from_wire(value: object) -> WalletAddressInfo:
+    if not isinstance(value, Mapping):
+        raise ValueError("Response is missing wallet")
+    return WalletAddressInfo(
+        swig_config_address=_required_string(
+            value.get("swigConfigAddress", value.get("swig_config_address")),
+            "swigConfigAddress",
+        ),
+        wallet_address=_required_string(
+            value.get("walletAddress", value.get("wallet_address")),
+            "walletAddress",
+        ),
+        network=normalize_network(value.get("network")),
+    )
+
+
+def wallet_authority_to_wire(authority: WalletAuthority) -> dict[str, object]:
+    for scheme in ("ed25519", "secp256k1", "secp256r1"):
+        value = authority.get(scheme)
+        if value is None:
+            continue
+        public_key = value.get("publicKey", value.get("public_key"))
+        if not isinstance(public_key, str) or not public_key.strip():
+            raise ValueError(f"{scheme} authority requires publicKey")
+        return {scheme: {"publicKey": public_key}}
+
+    proof = authority.get("programExecProof", authority.get("program_exec_proof"))
+    if proof is not None:
+        role_id = proof.get("roleId", proof.get("role_id"))
+        zk_proof = proof.get("zkProof", proof.get("zk_proof"))
+        if not isinstance(role_id, int) or not isinstance(zk_proof, str):
+            raise ValueError("programExecProof requires roleId and zkProof")
+        return {"programExecProof": {"roleId": role_id, "zkProof": zk_proof}}
+
+    raise ValueError("authority must include a supported authority")
+
+
+def normalize_amount(amount: Amount) -> str:
+    return str(amount)
+
+
+def to_proto_network(network: Network) -> str:
+    if network == "devnet":
+        return "NETWORK_DEVNET"
+    return "NETWORK_MAINNET"
+
+
+def normalize_network(value: object) -> Network | None:
+    if value in ("devnet", "NETWORK_DEVNET", 1):
+        return "devnet"
+    if value in ("mainnet", "NETWORK_MAINNET", 2):
+        return "mainnet"
+    return None
+
+
+def require_network(*values: Network | None) -> Network:
+    for value in values:
+        if value is not None:
+            return value
+    raise ValueError("network is required")
+
+
+def _required_string(value: object, field: str) -> str:
+    if isinstance(value, str):
+        return value
+    raise ValueError(f"Response is missing {field}")

swig_developer_sdk/core.py

@@ -0,0 +1,162 @@
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Mapping
+from typing import TypeVar, cast
+
+import httpx
+
+from .common import JsonValue, RetryOptions
+
+T = TypeVar("T")
+
+
+class SwigDeveloperSdkError(Exception):
+    def __init__(
+        self,
+        message: str,
+        code: str,
+        status_code: int,
+        details: object | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.code = code
+        self.status_code = status_code
+        self.details = details
+
+    @classmethod
+    def from_response(
+        cls,
+        response: httpx.Response,
+        body: object | None,
+    ) -> SwigDeveloperSdkError:
+        if isinstance(body, Mapping):
+            nested = body.get("error")
+            if isinstance(nested, Mapping):
+                details = nested.get("details")
+                return cls(
+                    _optional_string(nested.get("message"))
+                    or f"Request failed with status {response.status_code}",
+                    _optional_string(nested.get("code"))
+                    or f"HTTP_{response.status_code}",
+                    response.status_code,
+                    details if details is not None else body,
+                )
+            details = body.get("details")
+            return cls(
+                _optional_string(body.get("message"))
+                or f"Request failed with status {response.status_code}",
+                _optional_string(body.get("code")) or f"HTTP_{response.status_code}",
+                response.status_code,
+                details if details is not None else body,
+            )
+        return cls(
+            f"Request failed with status {response.status_code}",
+            f"HTTP_{response.status_code}",
+            response.status_code,
+            body,
+        )
+
+
+class HttpClient:
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        base_url: str,
+        retry: RetryOptions,
+        transport: httpx.AsyncBaseTransport | None = None,
+    ) -> None:
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+        self._retry = retry
+        self._transport = transport
+
+    async def get(self, path: str) -> object:
+        return await self._request(path, method="GET")
+
+    async def post(self, path: str, body: Mapping[str, object]) -> object:
+        compacted = _compact(body)
+        if not isinstance(compacted, Mapping):
+            raise TypeError("Request body must be an object")
+        return await self._request(path, method="POST", body=compacted)
+
+    async def _request(
+        self,
+        path: str,
+        *,
+        method: str,
+        body: Mapping[str, object] | None = None,
+    ) -> object:
+        last_error: SwigDeveloperSdkError | None = None
+        for attempt in range(self._retry.max_retries + 1):
+            try:
+                async with httpx.AsyncClient(transport=self._transport) as client:
+                    response = await client.request(
+                        method,
+                        f"{self._base_url}{path}",
+                        headers={
+                            "Content-Type": "application/json",
+                            "Authorization": f"Bearer {self._api_key}",
+                        },
+                        json=body,
+                    )
+                response_body = _parse_response_body(response)
+                if 200 <= response.status_code < 300:
+                    return _unwrap_data(response_body)
+                error = SwigDeveloperSdkError.from_response(response, response_body)
+                if 400 <= response.status_code < 500:
+                    raise error
+                last_error = error
+            except SwigDeveloperSdkError as error:
+                if 400 <= error.status_code < 500:
+                    raise
+                last_error = error
+            except httpx.HTTPError as error:
+                last_error = SwigDeveloperSdkError(str(error), "NETWORK_ERROR", 0)
+            except Exception as error:
+                last_error = SwigDeveloperSdkError(str(error), "NETWORK_ERROR", 0)
+
+            if attempt < self._retry.max_retries:
+                await asyncio.sleep(
+                    self._retry.retry_delay * self._retry.backoff_multiplier**attempt
+                )
+
+        if last_error is not None:
+            raise last_error
+        raise SwigDeveloperSdkError(
+            f"Request failed after {self._retry.max_retries} retries",
+            "RETRY_EXHAUSTED",
+            0,
+        )
+
+
+def _parse_response_body(response: httpx.Response) -> object:
+    if not response.content:
+        return None
+    try:
+        return cast(JsonValue, response.json())
+    except ValueError:
+        return response.text
+
+
+def _unwrap_data(body: object) -> object:
+    if isinstance(body, Mapping) and "data" in body:
+        return body["data"]
+    return body
+
+
+def _optional_string(value: object) -> str | None:
+    return value if isinstance(value, str) else None
+
+
+def _compact(value: object) -> object:
+    if isinstance(value, Mapping):
+        return {
+            str(key): _compact(item) for key, item in value.items() if item is not None
+        }
+    if isinstance(value, list):
+        return [_compact(item) for item in value]
+    if isinstance(value, tuple):
+        return [_compact(item) for item in value]
+    return value

swig_developer_sdk/evm.py

@@ -0,0 +1,64 @@
+from __future__ import annotations
+
+import inspect
+from collections.abc import Awaitable, Mapping, Sequence
+from typing import Protocol, cast
+
+from .signing import Secp256k1SigningFn, Secp256k1SigningResult
+
+
+class Eip1193Provider(Protocol):
+    def request(self, args: Mapping[str, object]) -> object: ...
+
+
+def create_secp256k1_evm_signing_fn(
+    *,
+    provider: Eip1193Provider,
+    address: str,
+) -> Secp256k1SigningFn:
+    async def sign(message: bytes) -> Secp256k1SigningResult:
+        result = provider.request(
+            {
+                "method": "personal_sign",
+                "params": [_bytes_to_hex(message), address],
+            }
+        )
+        if inspect.isawaitable(result):
+            result = await cast(Awaitable[object], result)
+        if not isinstance(result, str):
+            raise ValueError("EVM provider returned a non-string signature")
+        return Secp256k1SigningResult(
+            signature=_parse_evm_signature(result),
+            prefix=f"\x19Ethereum Signed Message:\n{len(message)}".encode("ascii"),
+        )
+
+    return sign
+
+
+def _parse_evm_signature(signature: str) -> bytes:
+    normalized = signature[2:] if signature.startswith("0x") else signature
+    if not normalized or any(
+        character not in "0123456789abcdefABCDEF" for character in normalized
+    ):
+        raise ValueError("Invalid hex string")
+    if len(normalized) % 2:
+        raise ValueError("Hex strings must contain an even number of characters")
+    value = bytearray.fromhex(normalized)
+    if len(value) != 65:
+        raise ValueError("EVM signature must be 65 bytes")
+    value[64] = _normalize_recovery_byte(value[64])
+    return bytes(value)
+
+
+def _normalize_recovery_byte(value: int) -> int:
+    if value in (0, 1):
+        return value + 27
+    if value in (27, 28):
+        return value
+    if value >= 35:
+        return ((value - 35) % 2) + 27
+    raise ValueError("EVM signature has an invalid recovery byte")
+
+
+def _bytes_to_hex(value: Sequence[int]) -> str:
+    return "0x" + bytes(value).hex()