chipi-stack 2.0.0__py3-none-any.whl

chipi_sdk/models/__init__.py

@@ -0,0 +1,145 @@
+"""Pydantic models for Chipi SDK."""
+
+# Core types
+from .core import (
+    Chain,
+    ChainToken,
+    ChipiSDKConfig,
+    PaginatedResponse,
+    PaginationQuery,
+    StarknetContract,
+    STARKNET_CONTRACTS,
+)
+
+# Wallet types
+from .wallet import (
+    CreateCustodialWalletParams,
+    CreateWalletParams,
+    CreateWalletResponse,
+    DeploymentData,
+    GetTokenBalanceParams,
+    GetTokenBalanceResponse,
+    GetWalletParams,
+    GetWalletResponse,
+    PasskeyMetadata,
+    PrepareWalletCreationResponse,
+    WalletData,
+    WalletType,
+)
+
+# Transaction types
+from .transaction import (
+    ApproveParams,
+    Call,
+    CallAnyContractParams,
+    ExecuteSponsoredTransactionParams,
+    ExecuteSponsoredTransactionResponse,
+    ExecuteTransactionParams,
+    GetTransactionListQuery,
+    PrepareTypedDataParams,
+    PrepareTypedDataResponse,
+    RecordSendTransactionParams,
+    StakeVesuUsdcParams,
+    Transaction,
+    TransferParams,
+    WithdrawVesuUsdcParams,
+)
+
+# Session types
+from .session import (
+    AddSessionKeyParams,
+    CreateSessionKeyParams,
+    ExecuteWithSessionParams,
+    GetSessionDataParams,
+    GetSpendingPolicyParams,
+    RemoveSpendingPolicyParams,
+    RevokeSessionKeyParams,
+    SessionConfig,
+    SessionDataResponse,
+    SessionKeyData,
+    SetSpendingPolicyParams,
+    SpendingPolicyConfig,
+    SpendingPolicyData,
+)
+
+# SKU types
+from .sku import (
+    GetSkuListQuery,
+    Sku,
+)
+
+# SKU transaction types
+from .sku_transaction import (
+    CreateSkuTransactionParams,
+    SkuTransaction,
+)
+
+# User types
+from .user import (
+    CreateUserParams,
+    GetUserParams,
+    User,
+)
+
+__all__ = [
+    # Core
+    "Chain",
+    "ChainToken",
+    "ChipiSDKConfig",
+    "PaginatedResponse",
+    "PaginationQuery",
+    "StarknetContract",
+    "STARKNET_CONTRACTS",
+    # Wallet
+    "CreateCustodialWalletParams",
+    "CreateWalletParams",
+    "CreateWalletResponse",
+    "DeploymentData",
+    "GetTokenBalanceParams",
+    "GetTokenBalanceResponse",
+    "GetWalletParams",
+    "GetWalletResponse",
+    "PasskeyMetadata",
+    "PrepareWalletCreationResponse",
+    "WalletData",
+    "WalletType",
+    # Transaction
+    "ApproveParams",
+    "Call",
+    "CallAnyContractParams",
+    "ExecuteSponsoredTransactionParams",
+    "ExecuteSponsoredTransactionResponse",
+    "ExecuteTransactionParams",
+    "GetTransactionListQuery",
+    "PrepareTypedDataParams",
+    "PrepareTypedDataResponse",
+    "RecordSendTransactionParams",
+    "StakeVesuUsdcParams",
+    "Transaction",
+    "TransferParams",
+    "WithdrawVesuUsdcParams",
+    # Session
+    "AddSessionKeyParams",
+    "CreateSessionKeyParams",
+    "ExecuteWithSessionParams",
+    "GetSessionDataParams",
+    "GetSpendingPolicyParams",
+    "RemoveSpendingPolicyParams",
+    "RevokeSessionKeyParams",
+    "SessionConfig",
+    "SessionDataResponse",
+    "SessionKeyData",
+    "SetSpendingPolicyParams",
+    "SpendingPolicyConfig",
+    "SpendingPolicyData",
+    # SKU
+    "GetSkuListQuery",
+    "Sku",
+    # SKU Transaction
+    "CreateSkuTransactionParams",
+    "SkuTransaction",
+    # User
+    "CreateUserParams",
+    "GetUserParams",
+    "User",
+]

chipi_sdk/models/core.py

@@ -0,0 +1,96 @@
+"""Core configuration and base types for Chipi SDK."""
+
+from enum import Enum
+from typing import Generic, Optional, TypeVar
+from pydantic import BaseModel, Field
+
+
+class Chain(str, Enum):
+    """Supported blockchain networks."""
+    STARKNET = "STARKNET"
+
+
+class ChainToken(str, Enum):
+    """Supported token types."""
+    USDC_E = "USDC_E"
+    USDC = "USDC"
+    USDT = "USDT"
+    ETH = "ETH"
+    STRK = "STRK"
+    DAI = "DAI"
+    WBTC = "WBTC"
+    OTHER = "OTHER"
+
+
+class ChipiSDKConfig(BaseModel):
+    """Configuration for initializing the Chipi SDK."""
+    
+    api_public_key: str = Field(..., description="Public API key for authentication")
+    alpha_url: Optional[str] = Field(None, description="Optional custom API URL")
+    node_url: Optional[str] = Field(None, description="Optional custom Starknet node URL")
+    api_secret_key: Optional[str] = Field(None, description="Optional API secret key for server-side operations")
+
+
+class PaginationQuery(BaseModel):
+    """Pagination parameters for list queries."""
+    
+    page: Optional[int] = Field(None, ge=1, description="Page number")
+    limit: Optional[int] = Field(None, ge=1, le=100, description="Items per page")
+    offset: Optional[int] = Field(None, ge=0, description="Offset for pagination")
+
+
+T = TypeVar('T')
+
+
+class PaginatedResponse(BaseModel, Generic[T]):
+    """Generic paginated response."""
+    
+    data: list[T]
+    total: int = Field(..., description="Total number of items")
+    page: int = Field(..., description="Current page number")
+    limit: int = Field(..., description="Items per page")
+    total_pages: int = Field(..., description="Total number of pages")
+
+
+class StarknetContract(BaseModel):
+    """Starknet contract information."""
+    
+    contract_address: str
+    decimals: int
+
+
+# Contract mappings for tokens
+STARKNET_CONTRACTS: dict[ChainToken, StarknetContract] = {
+    ChainToken.USDC: StarknetContract(
+        contract_address="0x033068F6539f8e6e6b131e6B2B814e6c34A5224bC66947c47DaB9dFeE93b35fb",
+        decimals=6
+    ),
+    ChainToken.USDC_E: StarknetContract(
+        contract_address="0x053c91253bc9682c04929ca02ed00b3e423f6710d2ee7e0d5ebb06f3ecf368a8",
+        decimals=6
+    ),
+    ChainToken.USDT: StarknetContract(
+        contract_address="0x068f5c6a61780768455de69077e07e89787839bf8166decfbf92b645209c0fb8",
+        decimals=6
+    ),
+    ChainToken.DAI: StarknetContract(
+        contract_address="0x05574eb6b8789a91466f902c380d978e472db68170ff82a5b650b95a58ddf4ad",
+        decimals=18
+    ),
+    ChainToken.STRK: StarknetContract(
+        contract_address="0x04718f5a0fc34cc1af16a1cdee98ffb20c31f5cd61d6ab07201858f4287c938d",
+        decimals=18
+    ),
+    ChainToken.ETH: StarknetContract(
+        contract_address="0x049d36570d4e46f48e99674bd3fcc84644ddd6b96f7c741b1562b82f9e004dc7",
+        decimals=18
+    ),
+    ChainToken.WBTC: StarknetContract(
+        contract_address="0x03fe2b97c1fd336e750087d68b9b867997fd64a2661ff3ca5a7c771641e8e7ac",
+        decimals=8
+    ),
+    ChainToken.OTHER: StarknetContract(
+        contract_address="",
+        decimals=18
+    ),
+}

chipi_sdk/models/session.py

@@ -0,0 +1,119 @@
+"""Session key management types and models."""
+
+from typing import Optional
+from pydantic import BaseModel, Field
+
+from .transaction import Call
+from .wallet import WalletData
+
+
+class SessionKeyData(BaseModel):
+    """Session key information."""
+    
+    public_key: str = Field(..., description="Session public key")
+    encrypted_private_key: str = Field(..., description="AES encrypted session private key")
+    valid_until: int = Field(..., description="Unix timestamp when session expires")
+
+
+class CreateSessionKeyParams(BaseModel):
+    """Parameters for creating a session key."""
+    
+    encrypt_key: str = Field(..., description="Encryption key for session private key")
+    duration_seconds: Optional[int] = Field(21600, description="Session duration in seconds (default 6 hours)")
+
+
+class SessionConfig(BaseModel):
+    """Session key configuration for on-chain registration."""
+    
+    session_public_key: str = Field(..., description="Public key of the session")
+    valid_until: int = Field(..., description="Unix timestamp when session expires")
+    max_calls: int = Field(..., description="Maximum number of calls allowed")
+    allowed_entrypoints: list[str] = Field(..., description="List of allowed contract entrypoints (empty = all allowed)")
+
+
+class AddSessionKeyParams(BaseModel):
+    """Parameters for adding a session key to contract."""
+    
+    encrypt_key: str = Field(..., description="Encryption key for owner private key")
+    wallet: WalletData
+    session_config: SessionConfig
+
+
+class RevokeSessionKeyParams(BaseModel):
+    """Parameters for revoking a session key."""
+    
+    encrypt_key: str = Field(..., description="Encryption key for owner private key")
+    wallet: WalletData
+    session_public_key: str = Field(..., description="Public key of session to revoke")
+
+
+class GetSessionDataParams(BaseModel):
+    """Parameters for querying session data."""
+    
+    wallet_address: str = Field(..., description="Wallet contract address")
+    session_public_key: str = Field(..., description="Session public key to query")
+
+
+class SessionDataResponse(BaseModel):
+    """Response from session data query."""
+    
+    is_active: bool = Field(..., description="Whether session is currently active")
+    valid_until: int = Field(..., description="Unix timestamp when session expires")
+    remaining_calls: int = Field(..., description="Number of calls remaining")
+    allowed_entrypoints: list[str] = Field(..., description="List of allowed entrypoints")
+
+
+class ExecuteWithSessionParams(BaseModel):
+    """Parameters for executing transaction with session key."""
+
+    encrypt_key: str = Field(..., description="Encryption key for session private key")
+    wallet: WalletData
+    session: SessionKeyData
+    calls: list[Call]
+
+
+# --- Spending Policy Types ---
+
+class SpendingPolicyConfig(BaseModel):
+    """Configuration for setting a spending policy on a session key."""
+
+    session_public_key: str = Field(..., description="Session public key to apply the policy to")
+    token: str = Field(..., description="ERC-20 token contract address")
+    max_per_call: int = Field(..., description="Maximum amount per single call (u256)")
+    max_per_window: int = Field(..., description="Maximum cumulative amount within rolling window (u256)")
+    window_seconds: int = Field(..., description="Rolling window duration in seconds")
+
+
+class SpendingPolicyData(BaseModel):
+    """On-chain spending policy state returned by get_spending_policy."""
+
+    max_per_call: int = Field(..., description="Maximum amount per single call")
+    max_per_window: int = Field(..., description="Maximum cumulative amount within rolling window")
+    window_seconds: int = Field(..., description="Rolling window duration in seconds")
+    spent_in_window: int = Field(..., description="Amount spent in the current active window")
+    window_start: int = Field(..., description="Unix timestamp when the current window started")
+
+
+class SetSpendingPolicyParams(BaseModel):
+    """Parameters for setting a spending policy."""
+
+    encrypt_key: str = Field(..., description="Encryption key for owner private key")
+    wallet: WalletData
+    spending_policy_config: SpendingPolicyConfig
+
+
+class GetSpendingPolicyParams(BaseModel):
+    """Parameters for querying a spending policy."""
+
+    wallet_address: str = Field(..., description="Wallet contract address")
+    session_public_key: str = Field(..., description="Session public key")
+    token: str = Field(..., description="ERC-20 token contract address")
+
+
+class RemoveSpendingPolicyParams(BaseModel):
+    """Parameters for removing a spending policy."""
+
+    encrypt_key: str = Field(..., description="Encryption key for owner private key")
+    wallet: WalletData
+    session_public_key: str = Field(..., description="Session public key")
+    token: str = Field(..., description="ERC-20 token contract address")

chipi_sdk/models/sku.py

@@ -0,0 +1,28 @@
+"""SKU-related types and models."""
+
+from datetime import datetime
+from typing import Optional
+from pydantic import BaseModel, Field
+
+
+class Sku(BaseModel):
+    """SKU (Stock Keeping Unit) model."""
+    
+    id: str
+    org_id: str
+    name: str
+    description: Optional[str] = None
+    price: str
+    currency: str
+    metadata: Optional[dict] = None
+    is_active: bool
+    created_at: datetime
+    updated_at: datetime
+
+
+class GetSkuListQuery(BaseModel):
+    """Query parameters for SKU list."""
+    
+    page: Optional[int] = Field(None, ge=1)
+    limit: Optional[int] = Field(None, ge=1, le=100)
+    is_active: Optional[bool] = None

chipi_sdk/models/sku_transaction.py

@@ -0,0 +1,30 @@
+"""SKU transaction types and models."""
+
+from datetime import datetime
+from typing import Optional
+from pydantic import BaseModel, Field
+
+
+class CreateSkuTransactionParams(BaseModel):
+    """Parameters for creating a SKU transaction."""
+    
+    sku_id: str = Field(..., description="SKU identifier")
+    wallet_address: str = Field(..., description="Buyer wallet address")
+    quantity: int = Field(1, ge=1, description="Quantity to purchase")
+    metadata: Optional[dict] = Field(None, description="Additional transaction metadata")
+
+
+class SkuTransaction(BaseModel):
+    """SKU transaction record."""
+    
+    id: str
+    sku_id: str
+    wallet_address: str
+    transaction_hash: Optional[str] = None
+    quantity: int
+    total_price: str
+    currency: str
+    status: str
+    metadata: Optional[dict] = None
+    created_at: datetime
+    updated_at: datetime

chipi_sdk/models/transaction.py

@@ -0,0 +1,192 @@
+"""Transaction-related types and models."""
+
+from datetime import datetime
+from enum import Enum
+from typing import Any, Optional
+from pydantic import BaseModel, Field, ConfigDict
+
+from .core import Chain, ChainToken
+from .wallet import WalletData, to_camel
+
+
+class Call(BaseModel):
+    """Starknet contract call structure."""
+    
+    model_config = ConfigDict(populate_by_name=True)
+    
+    contract_address: str = Field(..., alias="contractAddress")
+    entrypoint: str
+    calldata: list[str]
+
+
+class ExecuteTransactionParams(BaseModel):
+    """Parameters for executing a transaction."""
+    
+    encrypt_key: Optional[str] = Field(None, description="Encryption key for private key")
+    wallet: WalletData
+    calls: list[Call]
+    use_passkey: Optional[bool] = Field(False, description="Whether to use passkey authentication")
+
+
+class TransferParams(BaseModel):
+    """Parameters for token transfer."""
+    
+    encrypt_key: Optional[str] = Field(None, description="Encryption key for private key")
+    wallet: WalletData
+    token: ChainToken
+    other_token: Optional[dict[str, Any]] = Field(None, description="Custom token info for OTHER type")
+    recipient: str
+    amount: str
+    use_passkey: Optional[bool] = Field(False, description="Whether to use passkey authentication")
+
+
+class ApproveParams(BaseModel):
+    """Parameters for token approval."""
+    
+    encrypt_key: Optional[str] = Field(None, description="Encryption key for private key")
+    wallet: WalletData
+    contract_address: str
+    spender: str
+    amount: str
+    decimals: Optional[int] = Field(18, description="Token decimals")
+    use_passkey: Optional[bool] = Field(False, description="Whether to use passkey authentication")
+
+
+class CallAnyContractParams(BaseModel):
+    """Parameters for calling any contract."""
+    
+    encrypt_key: Optional[str] = Field(None, description="Encryption key for private key")
+    wallet: WalletData
+    contract_address: str
+    calls: list[Call]
+    use_passkey: Optional[bool] = Field(False, description="Whether to use passkey authentication")
+
+
+class StakeVesuUsdcParams(BaseModel):
+    """Parameters for staking USDC in Vesu protocol."""
+    
+    encrypt_key: Optional[str] = Field(None, description="Encryption key for private key")
+    wallet: WalletData
+    amount: str
+    receiver_wallet: str
+
+
+class WithdrawVesuUsdcParams(BaseModel):
+    """Parameters for withdrawing USDC from Vesu protocol."""
+    
+    encrypt_key: Optional[str] = Field(None, description="Encryption key for private key")
+    wallet: WalletData
+    amount: str
+    recipient: str
+
+
+class RecordSendTransactionParams(BaseModel):
+    """Parameters for recording a send transaction."""
+    
+    transaction_hash: str
+    expected_sender: str
+    expected_recipient: str
+    expected_token: ChainToken
+    expected_amount: str
+    chain: Chain
+
+
+class Transaction(BaseModel):
+    """Transaction record."""
+    
+    id: str
+    chain: str
+    api_public_key: str
+    transaction_hash: str
+    block_number: int
+    sender_address: str
+    destination_address: str
+    amount: str
+    token: str
+    called_function: Optional[str] = None
+    amount_in_usd: float = Field(..., alias="amountInUSD")
+    status: str
+    is_chipi_wallet: bool
+    created_at: datetime
+    updated_at: datetime
+    
+    class Config:
+        populate_by_name = True
+
+
+class PrepareTypedDataParams(BaseModel):
+    """Parameters for preparing typed data."""
+    
+    calls: list[Call]
+    wallet_address: str
+
+
+class PrepareTypedDataResponse(BaseModel):
+    """Response from typed data preparation."""
+    
+    typed_data: dict
+    wallet_type: str
+
+
+class ExecuteSponsoredTransactionParams(BaseModel):
+    """Parameters for executing sponsored transaction."""
+    
+    calls: list[Call]
+    wallet_address: str
+    signature: list[str]
+    api_public_key: str
+
+
+class ExecuteSponsoredTransactionResponse(BaseModel):
+    """Response from sponsored transaction execution."""
+    
+    transaction_hash: str
+
+
+class GetTransactionListQuery(BaseModel):
+    """Query parameters for transaction list."""
+
+    model_config = ConfigDict(populate_by_name=True, alias_generator=to_camel)
+
+    page: Optional[int] = Field(None, ge=1)
+    limit: Optional[int] = Field(None, ge=1, le=100)
+    called_function: Optional[str] = None
+    wallet_address: str = Field(..., description="Wallet address to filter transactions")
+    day: Optional[int] = Field(None, ge=1, le=31, description="Day of the month")
+    month: Optional[int] = Field(None, ge=1, le=12, description="Month of the year")
+    year: Optional[int] = Field(None, description="Year")
+
+
+class GetTransactionParams(BaseModel):
+    """Parameters for fetching a single transaction by hash or ID."""
+
+    hash_or_id: str = Field(..., description="Transaction hash (0x...) or internal database ID")
+
+
+class GetTransactionStatusParams(BaseModel):
+    """Parameters for fetching on-chain transaction status."""
+
+    hash: str = Field(..., description="Transaction hash (0x...)")
+
+
+class OnChainTxStatus(str, Enum):
+    """On-chain transaction status from StarkNet sequencer."""
+
+    RECEIVED = "RECEIVED"
+    PENDING = "PENDING"
+    ACCEPTED_ON_L2 = "ACCEPTED_ON_L2"
+    ACCEPTED_ON_L1 = "ACCEPTED_ON_L1"
+    REJECTED = "REJECTED"
+    REVERTED = "REVERTED"
+    NOT_RECEIVED = "NOT_RECEIVED"
+
+
+class TransactionStatusResponse(BaseModel):
+    """Response from the transaction status endpoint."""
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    transaction_hash: str = Field(..., alias="transactionHash")
+    status: OnChainTxStatus
+    block_number: Optional[int] = Field(None, alias="blockNumber")
+    revert_reason: Optional[str] = Field(None, alias="revertReason")

chipi_sdk/models/user.py

@@ -0,0 +1,31 @@
+"""User-related types and models."""
+
+from datetime import datetime
+from typing import Optional
+from pydantic import BaseModel, Field
+
+
+class CreateUserParams(BaseModel):
+    """Parameters for creating a user."""
+    
+    external_user_id: str = Field(..., description="External user identifier")
+    email: Optional[str] = Field(None, description="User email")
+    metadata: Optional[dict] = Field(None, description="Additional user metadata")
+
+
+class GetUserParams(BaseModel):
+    """Parameters for retrieving a user."""
+    
+    external_user_id: str = Field(..., description="External user identifier")
+
+
+class User(BaseModel):
+    """User model."""
+    
+    id: str
+    org_id: str
+    external_user_id: str
+    email: Optional[str] = None
+    metadata: Optional[dict] = None
+    created_at: datetime
+    updated_at: datetime