chipi-stack 2.0.0__py3-none-any.whl

chipi_sdk/models/wallet.py

@@ -0,0 +1,178 @@
+"""Wallet-related types and models."""
+
+from datetime import datetime
+from enum import Enum
+from typing import Optional
+from pydantic import BaseModel, Field, ConfigDict
+
+from .core import Chain, ChainToken
+
+
+def to_camel(string: str) -> str:
+    """Convert snake_case to camelCase."""
+    components = string.split('_')
+    return components[0] + ''.join(x.title() for x in components[1:])
+
+
+class WalletType(str, Enum):
+    """
+    Supported wallet types.
+    
+    - CHIPI: OpenZeppelin account with SNIP-9 session keys support (default)
+    - READY: Argent X Account v0.4.0
+    """
+    CHIPI = "CHIPI"
+    READY = "READY"
+
+
+class WalletData(BaseModel):
+    """Core wallet data structure."""
+    
+    model_config = ConfigDict(populate_by_name=True, alias_generator=to_camel)
+    
+    public_key: str = Field(..., description="Wallet public address")
+    encrypted_private_key: str = Field(..., description="AES encrypted private key")
+    wallet_type: Optional[WalletType] = Field(None, description="Type of wallet")
+    normalized_public_key: Optional[str] = Field(None, description="Normalized public key")
+
+
+class DeploymentData(BaseModel):
+    """Contract deployment data."""
+    
+    class_hash: str
+    salt: str
+    unique: str
+    calldata: list[str]
+
+
+class CreateWalletParams(BaseModel):
+    """Parameters for creating a new wallet."""
+    
+    encrypt_key: Optional[str] = Field(None, description="Encryption key for private key")
+    external_user_id: str = Field(..., description="External user identifier")
+    user_id: Optional[str] = Field(None, description="Internal user ID")
+    wallet_type: Optional[WalletType] = Field(WalletType.CHIPI, description="Type of wallet to create")
+    use_passkey: Optional[bool] = Field(False, description="Whether to use passkey authentication")
+
+
+class GetWalletResponse(BaseModel):
+    """
+    Response from wallet retrieval and creation.
+
+    Flat object matching the backend API response. Same shape for both
+    createWallet and getWallet — no nesting, no txHash.
+    Aligned with TypeScript GetWalletResponse (types/src/wallet.ts).
+    """
+
+    model_config = ConfigDict(populate_by_name=True, alias_generator=to_camel)
+
+    id: str
+    external_user_id: str = Field(..., description="External user identifier")
+    organization_id: Optional[str] = None
+    api_public_key: str = Field(..., description="Organization API public key")
+    public_key: str = Field(..., description="Wallet public address")
+    normalized_public_key: str = Field(..., description="Normalized public key")
+    encrypted_private_key: str = Field(..., description="AES encrypted private key")
+    is_deployed: bool = Field(..., description="Whether wallet contract is deployed")
+    created_at: Optional[datetime] = None
+    updated_at: Optional[datetime] = None
+    wallet_type: WalletType = Field(WalletType.CHIPI, description="Type of wallet")
+    chain: Chain = Field(Chain.STARKNET, description="Blockchain network")
+    class_hash: Optional[str] = Field(None, description="Contract class hash used for deployment")
+
+
+CreateWalletResponse = GetWalletResponse
+"""CreateWalletResponse is the same shape as GetWalletResponse (alias)."""
+
+
+class GetWalletParams(BaseModel):
+    """Parameters for retrieving a wallet."""
+    
+    external_user_id: str = Field(..., description="External user identifier")
+
+
+class GetTokenBalanceParams(BaseModel):
+    """Parameters for querying token balance."""
+
+    model_config = ConfigDict(populate_by_name=True, alias_generator=to_camel)
+
+    external_user_id: Optional[str] = Field(None, description="External user identifier")
+    wallet_public_key: Optional[str] = Field(None, description="Wallet public key")
+    chain_token: ChainToken = Field(..., description="Token to query")
+    chain: Chain = Field(..., description="Blockchain network")
+
+
+class GetTokenBalanceResponse(BaseModel):
+    """Response from token balance query."""
+    
+    model_config = ConfigDict(populate_by_name=True, alias_generator=to_camel)
+    
+    chain: Chain
+    chain_token: ChainToken
+    chain_token_address: str
+    decimals: int
+    balance: str
+
+
+class PrepareWalletCreationResponse(BaseModel):
+    """Response from wallet creation preparation."""
+    
+    model_config = ConfigDict(populate_by_name=True, alias_generator=to_camel)
+    
+    typed_data: dict
+    account_class_hash: str
+
+
+class CreateCustodialWalletParams(BaseModel):
+    """Parameters for creating a custodial wallet."""
+    
+    chain: Chain
+    org_id: str
+
+
+class PasskeyMetadata(BaseModel):
+    """Passkey authentication metadata."""
+
+    model_config = ConfigDict(populate_by_name=True, alias_generator=to_camel)
+
+    credential_id: str
+    created_at: str
+    user_id: str
+    prf_supported: bool
+
+
+class PrepareWalletUpgradeParams(BaseModel):
+    """Parameters for preparing a wallet upgrade."""
+
+    wallet_address: str = Field(..., description="Wallet address to upgrade")
+    target_class_hash: Optional[str] = Field(None, description="Target class hash (defaults to latest CHIPI)")
+
+
+class PrepareWalletUpgradeResponse(BaseModel):
+    """Response from prepare-upgrade containing typed data for signing."""
+
+    model_config = ConfigDict(populate_by_name=True, alias_generator=to_camel)
+
+    typed_data: dict
+    current_class_hash: str
+    target_class_hash: str
+    current_wallet_type: str
+    target_wallet_type: str
+
+
+class ExecuteWalletUpgradeParams(BaseModel):
+    """Parameters for executing a wallet upgrade after signing."""
+
+    wallet_address: str = Field(..., description="Wallet address being upgraded")
+    typed_data: dict = Field(..., description="SNIP-12 typed data from prepare step")
+    signature: list[str] = Field(..., description="User signature over the typed data")
+
+
+class ExecuteWalletUpgradeResponse(BaseModel):
+    """Response from wallet upgrade execution."""
+
+    model_config = ConfigDict(populate_by_name=True, alias_generator=to_camel)
+
+    transaction_hash: str
+    new_class_hash: str
+    new_wallet_type: str

chipi_sdk/models/x402.py

@@ -0,0 +1,117 @@
+"""x402 Payment Protocol types for HTTP 402 pay-per-request APIs."""
+
+from typing import Optional
+from pydantic import BaseModel, Field, field_validator
+
+
+class PaymentRequirement(BaseModel):
+    """Payment requirement from 402 response PAYMENT-REQUIRED header."""
+
+    scheme: str = Field("exact", description="Payment scheme")
+    network: str = Field("starknet-mainnet", description="Network identifier")
+    max_amount_required: str = Field(..., alias="maxAmountRequired", description="Amount in token base units")
+    resource: str = Field(..., description="URL of the resource being paid for")
+    description: Optional[str] = Field(None, description="Human-readable description")
+    mime_type: Optional[str] = Field(None, alias="mimeType", description="MIME type of the resource")
+    pay_to: str = Field(..., alias="payTo", description="Recipient address (merchant)")
+    max_timeout_seconds: int = Field(..., alias="maxTimeoutSeconds", description="Max seconds before payment expires")
+    asset: str = Field(..., description="Token contract address (USDC)")
+    extra: Optional[dict] = Field(None, description="Additional protocol-specific data")
+
+    model_config = {"populate_by_name": True}
+
+    @field_validator("max_amount_required")
+    @classmethod
+    def validate_amount(cls, v: str) -> str:
+        try:
+            val = int(v)
+        except (ValueError, TypeError):
+            raise ValueError(f"maxAmountRequired must be a valid integer string, got: {v!r}")
+        if val <= 0:
+            raise ValueError(f"maxAmountRequired must be positive, got: {val}")
+        return v
+
+
+class PaymentSignature(BaseModel):
+    """SNIP-12 signature."""
+
+    r: str
+    s: str
+
+
+class PaymentPayloadData(BaseModel):
+    """Inner payload of a signed payment."""
+
+    signature: PaymentSignature
+    from_address: str = Field(..., alias="fromAddress")
+    to_address: str = Field(..., alias="toAddress")
+    amount: str
+    asset: str
+    valid_until: int = Field(..., alias="validUntil")
+    nonce: str
+
+    model_config = {"populate_by_name": True}
+
+    @field_validator("amount")
+    @classmethod
+    def validate_amount(cls, v: str) -> str:
+        try:
+            val = int(v)
+        except (ValueError, TypeError):
+            raise ValueError(f"amount must be a valid integer string, got: {v!r}")
+        if val <= 0:
+            raise ValueError(f"amount must be positive, got: {val}")
+        return v
+
+
+class PaymentPayload(BaseModel):
+    """Signed payment payload sent in X-PAYMENT header."""
+
+    x402_version: int = Field(1, alias="x402Version")
+    scheme: str = Field("exact")
+    network: str = Field("starknet-mainnet")
+    payload: PaymentPayloadData
+
+    model_config = {"populate_by_name": True}
+
+
+class VerifyResponse(BaseModel):
+    """Facilitator verify response."""
+
+    is_valid: bool = Field(..., alias="isValid")
+    invalid_reason: Optional[str] = Field(None, alias="invalidReason")
+
+    model_config = {"populate_by_name": True}
+
+
+class SettleResponse(BaseModel):
+    """Facilitator settle response."""
+
+    success: bool
+    transaction_hash: Optional[str] = Field(None, alias="transactionHash")
+    error_reason: Optional[str] = Field(None, alias="errorReason")
+    network_id: Optional[str] = Field(None, alias="networkId")
+
+    model_config = {"populate_by_name": True}
+
+
+class X402ClientConfig(BaseModel):
+    """x402 client configuration."""
+
+    max_payment_amount: Optional[str] = Field(None, description="Max amount per payment (human-readable USDC)")
+    allowed_recipients: Optional[list[str]] = Field(None, description="Allowed recipient addresses")
+    header_name: str = Field("X-PAYMENT", description="Custom header name")
+
+
+class X402FacilitatorConfig(BaseModel):
+    """x402 facilitator configuration."""
+    # NonceStore is not a Pydantic model — it's passed as a protocol/ABC at runtime
+    pass
+
+
+class X402PaymentConfig(BaseModel):
+    """Payment configuration for a protected endpoint."""
+
+    amount: str = Field(..., description="Amount in human-readable units (e.g. '0.01')")
+    pay_to: str = Field(..., description="Merchant receiving address")
+    description: Optional[str] = Field(None, description="Human-readable description")

chipi_sdk/py.typed

@@ -0,0 +1 @@
+# Marker file for PEP 561 - indicates this package supports type hints