uvd-x402-sdk 0.3.4__py3-none-any.whl → 0.4.1__py3-none-any.whl

uvd_x402_sdk/networks/__init__.py

@@ -4,12 +4,13 @@ Network configurations for x402 payments.
 This module provides configuration for all supported blockchain networks,
 including USDC contract addresses, RPC URLs, and network-specific parameters.
 
-The SDK supports 14 mainnet networks out of the box:
+The SDK supports 16 mainnet networks out of the box:
 - 10 EVM chains: Base, Ethereum, Polygon, Arbitrum, Optimism, Avalanche,
                  Celo, HyperEVM, Unichain, Monad
 - 2 SVM chains: Solana, Fogo
 - 1 NEAR: NEAR Protocol
 - 1 Stellar: Stellar
+- 2 Algorand: Algorand mainnet and testnet
 
 Multi-token support (EVM chains only):
 - USDC: All chains
@@ -47,7 +48,7 @@ from uvd_x402_sdk.networks.base import (
 )
 
 # Import all default network configurations
-from uvd_x402_sdk.networks import evm, solana, near, stellar
+from uvd_x402_sdk.networks import evm, solana, near, stellar, algorand
 
 __all__ = [
     # Core

uvd_x402_sdk/networks/algorand.py

@@ -0,0 +1,287 @@
+"""
+Algorand network configurations.
+
+This module supports Algorand blockchain networks:
+- Algorand mainnet
+- Algorand testnet
+
+Algorand uses ASA (Algorand Standard Assets) for USDC:
+- Mainnet USDC ASA ID: 31566704
+- Testnet USDC ASA ID: 10458941
+
+Payment Flow:
+1. User creates a signed ASA transfer transaction via Pera Wallet
+2. Transaction transfers USDC from user to recipient
+3. Facilitator submits the pre-signed transaction on-chain
+4. User pays ZERO transaction fees (facilitator covers fees)
+
+Transaction Structure:
+- ASA TransferAsset transaction
+- Signed by user wallet (Pera Wallet)
+- Facilitator submits the signed transaction
+
+Address Format:
+- Algorand addresses are 58 characters, base32 encoded
+- Example: AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAY5HFKQ
+"""
+
+import base64
+import re
+from typing import Any, Dict, Optional
+
+from uvd_x402_sdk.networks.base import (
+    NetworkConfig,
+    NetworkType,
+    register_network,
+)
+
+
+# =============================================================================
+# Algorand Networks Configuration
+# =============================================================================
+
+# Algorand Mainnet
+ALGORAND = NetworkConfig(
+    name="algorand",
+    display_name="Algorand",
+    network_type=NetworkType.ALGORAND,
+    chain_id=0,  # Non-EVM, no chain ID
+    usdc_address="31566704",  # USDC ASA ID on mainnet
+    usdc_decimals=6,
+    usdc_domain_name="",  # Not applicable for Algorand
+    usdc_domain_version="",
+    rpc_url="https://mainnet-api.algonode.cloud",
+    enabled=True,
+    extra_config={
+        # ASA (Algorand Standard Asset) details
+        "usdc_asa_id": 31566704,
+        # Block explorer
+        "explorer_url": "https://allo.info",
+        # Indexer endpoint (for account queries)
+        "indexer_url": "https://mainnet-idx.algonode.cloud",
+        # Network identifier
+        "genesis_id": "mainnet-v1.0",
+        # Genesis hash (for CAIP-2)
+        "genesis_hash": "wGHE2Pwdvd7S12BL5FaOP20EGYesN73ktiC1qzkkit8=",
+    },
+)
+
+# Algorand Testnet
+ALGORAND_TESTNET = NetworkConfig(
+    name="algorand-testnet",
+    display_name="Algorand Testnet",
+    network_type=NetworkType.ALGORAND,
+    chain_id=0,  # Non-EVM, no chain ID
+    usdc_address="10458941",  # USDC ASA ID on testnet
+    usdc_decimals=6,
+    usdc_domain_name="",  # Not applicable for Algorand
+    usdc_domain_version="",
+    rpc_url="https://testnet-api.algonode.cloud",
+    enabled=True,
+    extra_config={
+        # ASA (Algorand Standard Asset) details
+        "usdc_asa_id": 10458941,
+        # Block explorer
+        "explorer_url": "https://testnet.allo.info",
+        # Indexer endpoint (for account queries)
+        "indexer_url": "https://testnet-idx.algonode.cloud",
+        # Network identifier
+        "genesis_id": "testnet-v1.0",
+        # Genesis hash
+        "genesis_hash": "SGO1GKSzyE7IEPItTxCByw9x8FmnrCDexi9/cOUJOiI=",
+    },
+)
+
+# Register Algorand networks
+register_network(ALGORAND)
+register_network(ALGORAND_TESTNET)
+
+
+# =============================================================================
+# Algorand-specific utilities
+# =============================================================================
+
+
+def is_algorand_network(network_name: str) -> bool:
+    """
+    Check if a network is Algorand.
+
+    Args:
+        network_name: Network name to check
+
+    Returns:
+        True if network is Algorand (mainnet or testnet)
+    """
+    from uvd_x402_sdk.networks.base import get_network, NetworkType
+
+    network = get_network(network_name)
+    if not network:
+        return False
+    return network.network_type == NetworkType.ALGORAND
+
+
+def get_algorand_networks() -> list:
+    """
+    Get all registered Algorand networks.
+
+    Returns:
+        List of Algorand NetworkConfig instances
+    """
+    from uvd_x402_sdk.networks.base import list_networks, NetworkType
+
+    return [
+        n for n in list_networks(enabled_only=True)
+        if n.network_type == NetworkType.ALGORAND
+    ]
+
+
+def is_valid_algorand_address(address: str) -> bool:
+    """
+    Validate an Algorand address format.
+
+    Algorand addresses are 58 characters, base32 encoded (RFC 4648).
+    They consist of uppercase letters A-Z and digits 2-7.
+
+    Args:
+        address: Address to validate
+
+    Returns:
+        True if valid Algorand address format
+    """
+    if not address or not isinstance(address, str):
+        return False
+
+    # Algorand addresses are exactly 58 characters
+    if len(address) != 58:
+        return False
+
+    # Base32 alphabet (RFC 4648): A-Z and 2-7
+    base32_pattern = re.compile(r'^[A-Z2-7]+$')
+    return bool(base32_pattern.match(address))
+
+
+def validate_algorand_payload(payload: Dict[str, Any]) -> bool:
+    """
+    Validate an Algorand payment payload structure.
+
+    The payload must contain:
+    - from: Sender's Algorand address
+    - to: Recipient's Algorand address
+    - amount: Amount in base units (microUSDC)
+    - assetId: ASA ID for USDC
+    - signedTxn: Base64-encoded signed transaction
+
+    Args:
+        payload: Payload dictionary from x402 payment
+
+    Returns:
+        True if valid, raises ValueError if invalid
+    """
+    required_fields = ["from", "to", "amount", "assetId", "signedTxn"]
+
+    for field in required_fields:
+        if field not in payload:
+            raise ValueError(f"Algorand payload missing '{field}' field")
+
+    # Validate addresses
+    if not is_valid_algorand_address(payload["from"]):
+        raise ValueError(f"Invalid 'from' address: {payload['from']}")
+    if not is_valid_algorand_address(payload["to"]):
+        raise ValueError(f"Invalid 'to' address: {payload['to']}")
+
+    # Validate amount
+    try:
+        amount = int(payload["amount"])
+        if amount <= 0:
+            raise ValueError(f"Amount must be positive: {amount}")
+    except (ValueError, TypeError) as e:
+        raise ValueError(f"Invalid amount: {payload['amount']}") from e
+
+    # Validate assetId
+    try:
+        asset_id = int(payload["assetId"])
+        if asset_id <= 0:
+            raise ValueError(f"Asset ID must be positive: {asset_id}")
+    except (ValueError, TypeError) as e:
+        raise ValueError(f"Invalid assetId: {payload['assetId']}") from e
+
+    # Validate signedTxn is valid base64
+    try:
+        signed_txn = payload["signedTxn"]
+        tx_bytes = base64.b64decode(signed_txn)
+        if len(tx_bytes) < 50:
+            raise ValueError(f"Signed transaction too short: {len(tx_bytes)} bytes")
+    except Exception as e:
+        raise ValueError(f"Invalid signedTxn (not valid base64): {e}") from e
+
+    return True
+
+
+def get_explorer_tx_url(network_name: str, tx_id: str) -> Optional[str]:
+    """
+    Get block explorer URL for a transaction.
+
+    Args:
+        network_name: Network name ('algorand' or 'algorand-testnet')
+        tx_id: Transaction ID
+
+    Returns:
+        Explorer URL or None if network not found
+    """
+    from uvd_x402_sdk.networks.base import get_network
+
+    network = get_network(network_name)
+    if not network or network.network_type != NetworkType.ALGORAND:
+        return None
+
+    explorer_url = network.extra_config.get("explorer_url", "https://allo.info")
+    return f"{explorer_url}/tx/{tx_id}"
+
+
+def get_explorer_address_url(network_name: str, address: str) -> Optional[str]:
+    """
+    Get block explorer URL for an address.
+
+    Args:
+        network_name: Network name ('algorand' or 'algorand-testnet')
+        address: Algorand address
+
+    Returns:
+        Explorer URL or None if network not found
+    """
+    from uvd_x402_sdk.networks.base import get_network
+
+    network = get_network(network_name)
+    if not network or network.network_type != NetworkType.ALGORAND:
+        return None
+
+    explorer_url = network.extra_config.get("explorer_url", "https://allo.info")
+    return f"{explorer_url}/account/{address}"
+
+
+def get_usdc_asa_id(network_name: str) -> Optional[int]:
+    """
+    Get the USDC ASA ID for an Algorand network.
+
+    Args:
+        network_name: Network name ('algorand' or 'algorand-testnet')
+
+    Returns:
+        USDC ASA ID or None if network not found
+    """
+    from uvd_x402_sdk.networks.base import get_network
+
+    network = get_network(network_name)
+    if not network or network.network_type != NetworkType.ALGORAND:
+        return None
+
+    # Try extra_config first, then fall back to usdc_address
+    asa_id = network.extra_config.get("usdc_asa_id")
+    if asa_id:
+        return int(asa_id)
+
+    # Parse from usdc_address (which stores the ASA ID as string)
+    try:
+        return int(network.usdc_address)
+    except (ValueError, TypeError):
+        return None

uvd_x402_sdk/networks/base.py

@@ -56,6 +56,7 @@ class NetworkType(Enum):
     - SVM: Partially-signed VersionedTransaction (SPL token transfer) - Solana, Fogo
     - NEAR: NEP-366 SignedDelegateAction (meta-transaction)
     - STELLAR: Soroban Authorization Entry XDR
+    - ALGORAND: ASA (Algorand Standard Assets) transfer via signed transaction
 
     Note: SOLANA is deprecated, use SVM instead for Solana-compatible chains.
     """
@@ -65,6 +66,7 @@ class NetworkType(Enum):
     SOLANA = "solana"  # Deprecated: use SVM
     NEAR = "near"
     STELLAR = "stellar"
+    ALGORAND = "algorand"  # Algorand ASA transfers
 
     @classmethod
     def is_svm(cls, network_type: "NetworkType") -> bool:
@@ -369,6 +371,7 @@ _CAIP2_NAMESPACE_MAP = {
     "solana": NetworkType.SVM,
     "near": NetworkType.NEAR,
     "stellar": NetworkType.STELLAR,
+    "algorand": NetworkType.ALGORAND,
 }
 
 # Network name to CAIP-2 format
@@ -391,6 +394,9 @@ _NETWORK_TO_CAIP2 = {
     "near": "near:mainnet",
     # Stellar
     "stellar": "stellar:pubnet",
+    # Algorand
+    "algorand": "algorand:mainnet",
+    "algorand-testnet": "algorand:testnet",
 }
 
 # CAIP-2 to network name mapping (reverse of above)
@@ -444,6 +450,11 @@ def parse_caip2_network(caip2_id: str) -> Optional[str]:
         return "near"
     if namespace == "stellar" and reference in ("pubnet", "mainnet"):
         return "stellar"
+    if namespace == "algorand":
+        if reference == "mainnet":
+            return "algorand"
+        if reference == "testnet":
+            return "algorand-testnet"
 
     return None
 

uvd_x402_sdk/networks/solana.py

@@ -5,6 +5,10 @@ This module supports all SVM-compatible chains:
 - Solana (mainnet)
 - Fogo (fast finality SVM)
 
+Supported Tokens:
+- USDC: Standard SPL Token (TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA)
+- AUSD: Token2022 (TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb)
+
 All SVM chains use the same payment flow:
 1. User creates a partially-signed VersionedTransaction
 2. Transaction contains SPL token TransferChecked instruction
@@ -14,7 +18,7 @@ All SVM chains use the same payment flow:
 Transaction Structure (flexible, facilitator v1.9.4+):
 - SetComputeUnitLimit instruction (recommended: 20,000 units)
 - SetComputeUnitPrice instruction (recommended: 100,000 microLamports)
-- TransferChecked (USDC transfer)
+- TransferChecked (SPL or Token2022 transfer)
 - Optional: CreateAssociatedTokenAccount (if recipient ATA doesn't exist)
 - Additional instructions may be added by wallets (e.g., Phantom memo)
 
@@ -30,6 +34,7 @@ from typing import Dict, Any, Optional
 from uvd_x402_sdk.networks.base import (
     NetworkConfig,
     NetworkType,
+    TokenConfig,
     register_network,
 )
 
@@ -50,9 +55,28 @@ SOLANA = NetworkConfig(
     usdc_domain_version="",
     rpc_url="https://api.mainnet-beta.solana.com",
     enabled=True,
+    tokens={
+        # USDC - Standard SPL Token
+        "usdc": TokenConfig(
+            address="EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
+            decimals=6,
+            name="",  # Not applicable for SVM
+            version="",
+        ),
+        # AUSD - Token2022 (Agora USD)
+        # Uses Token2022 with extensions: PermanentDelegate, TransferHook, Metadata
+        "ausd": TokenConfig(
+            address="AUSD1jCcCyPLybk1YnvPWsHQSrZ46dxwoMniN4N2UEB9",
+            decimals=6,
+            name="",  # Not applicable for SVM
+            version="",
+        ),
+    },
     extra_config={
         # Token program ID (standard SPL token program)
         "token_program_id": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",
+        # Token2022 program ID (for AUSD and other Token2022 tokens)
+        "token_2022_program_id": "TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb",
         # Associated Token Account program
         "ata_program_id": "ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL",
         # Default compute units for transfer
@@ -280,3 +304,50 @@ DEFAULT_COMPUTE_UNITS = 20000
 # Use 100k microlamports/CU for fast landing on mainnet
 # Lower values (like 1) cause transactions to be deprioritized and time out
 DEFAULT_PRIORITY_FEE_MICROLAMPORTS = 100_000
+
+# =============================================================================
+# Token Program Constants
+# =============================================================================
+
+# Standard SPL Token Program (used by USDC)
+TOKEN_PROGRAM_ID = "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA"
+
+# Token2022 Program (used by AUSD - has extensions like TransferHook)
+TOKEN_2022_PROGRAM_ID = "TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb"
+
+# Associated Token Account Program (same for both SPL and Token2022)
+ATA_PROGRAM_ID = "ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL"
+
+# Tokens that use Token2022 instead of standard SPL
+TOKEN_2022_TOKENS = {"ausd"}
+
+
+def get_token_program_id(token_type: str) -> str:
+    """
+    Get the token program ID for a given token type.
+
+    USDC uses standard SPL Token program.
+    AUSD uses Token2022 (with extensions like TransferHook).
+
+    Args:
+        token_type: Token type (e.g., 'usdc', 'ausd')
+
+    Returns:
+        Token program ID string
+    """
+    if token_type.lower() in TOKEN_2022_TOKENS:
+        return TOKEN_2022_PROGRAM_ID
+    return TOKEN_PROGRAM_ID
+
+
+def is_token_2022(token_type: str) -> bool:
+    """
+    Check if a token uses the Token2022 program.
+
+    Args:
+        token_type: Token type (e.g., 'usdc', 'ausd')
+
+    Returns:
+        True if token uses Token2022, False for standard SPL
+    """
+    return token_type.lower() in TOKEN_2022_TOKENS

{uvd_x402_sdk-0.3.4.dist-info → uvd_x402_sdk-0.4.1.dist-info}/METADATA

@@ -1,13 +1,13 @@
 Metadata-Version: 2.1
 Name: uvd-x402-sdk
-Version: 0.3.4
-Summary: Python SDK for x402 payments - gasless crypto payments across 14 blockchains with multi-stablecoin support (USDC, EURC, AUSD, PYUSD, USDT)
+Version: 0.4.1
+Summary: Python SDK for x402 payments - gasless crypto payments across 16 blockchains with multi-stablecoin support (USDC, EURC, AUSD, PYUSD, USDT)
 Author-email: Ultravioleta DAO <dev@ultravioletadao.xyz>
 Project-URL: Homepage, https://github.com/UltravioletaDAO/uvd-x402-sdk-python
 Project-URL: Documentation, https://docs.ultravioletadao.xyz/x402-sdk
 Project-URL: Repository, https://github.com/UltravioletaDAO/uvd-x402-sdk-python
 Project-URL: Issues, https://github.com/UltravioletaDAO/uvd-x402-sdk-python/issues
-Keywords: x402,payments,crypto,usdc,eurc,stablecoin,web3,evm,solana,near,stellar,facilitator,gasless,eip-712,eip-3009
+Keywords: x402,payments,crypto,usdc,eurc,stablecoin,web3,evm,solana,near,stellar,algorand,facilitator,gasless,eip-712,eip-3009
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License

{uvd_x402_sdk-0.3.4.dist-info → uvd_x402_sdk-0.4.1.dist-info}/RECORD

@@ -10,14 +10,15 @@ uvd_x402_sdk/integrations/django_integration.py,sha256=e3xaV1Yz3HHI7zZBNcyTmV0Js
 uvd_x402_sdk/integrations/fastapi_integration.py,sha256=j5h1IJwFLBBoWov7ANLCFaxeCa8pugn-XU9ibrzIL0Y,10205
 uvd_x402_sdk/integrations/flask_integration.py,sha256=0iQKO5-WRxE76Pv-1jEl4lYhjCLmq_R-jxR5g9xIcKw,8825
 uvd_x402_sdk/integrations/lambda_integration.py,sha256=nRf4o3nS6Syx-d5P0kEhz66y7jb_S4w-mwaIazgiA9c,10184
-uvd_x402_sdk/networks/__init__.py,sha256=5EECOYHl2OukNv55sIJlHlU4XI9s1Uv2ksoXnxkpduM,2039
-uvd_x402_sdk/networks/base.py,sha256=pvn01I1kNFmSaVltnsLjrp06D_hmAxis6XSIYZzUO1c,14429
+uvd_x402_sdk/networks/__init__.py,sha256=LKl_TljVoCDb27YB4X_VbQN8XKbdwWFAsCwgiqQtlgo,2092
+uvd_x402_sdk/networks/algorand.py,sha256=ACaVMyXItRX3M29GPwwMMxECMjNXx3FlYARNBeAztH4,8601
+uvd_x402_sdk/networks/base.py,sha256=gOPWfqasGbgtg9w2uG5pWnfjdOEain92L2egnDSBguc,14863
 uvd_x402_sdk/networks/evm.py,sha256=4IbeaMH2I1c9DYCijghys0qYNeL2Nl92IMKLwq-b0Zg,10065
 uvd_x402_sdk/networks/near.py,sha256=sxbxT1NqjcENh8ysFLDpAx5DGizf1EI0YjwgviLfqcY,11608
-uvd_x402_sdk/networks/solana.py,sha256=kVSHRi57eTJdBtgI8SUbHfQUxYzx-_YvI_bEB0HIvNg,9351
+uvd_x402_sdk/networks/solana.py,sha256=-snAeE3OxJU_kaGb_z4NOU6k0SGAD4DBPhJcPbgrdgo,11675
 uvd_x402_sdk/networks/stellar.py,sha256=c-6re-dVc2-6gJ5rL4krUTaFsPz5vkactOJD-0wowBA,3534
-uvd_x402_sdk-0.3.4.dist-info/LICENSE,sha256=OcLzB_iSgMbvk7b0dlyvleY_IbL2WUaPxvn1CHw2uAc,1073
-uvd_x402_sdk-0.3.4.dist-info/METADATA,sha256=cAqVIhQQCsIckZYoeXifxGbaUlj_MdVHa9jsn5qXk0s,29609
-uvd_x402_sdk-0.3.4.dist-info/WHEEL,sha256=tZoeGjtWxWRfdplE7E3d45VPlLNQnvbKiYnx7gwAy8A,92
-uvd_x402_sdk-0.3.4.dist-info/top_level.txt,sha256=Exyjj_Kl7CDAGFMi72lT9oFPOYiRNZb3l8tr906mMmc,13
-uvd_x402_sdk-0.3.4.dist-info/RECORD,,
+uvd_x402_sdk-0.4.1.dist-info/LICENSE,sha256=OcLzB_iSgMbvk7b0dlyvleY_IbL2WUaPxvn1CHw2uAc,1073
+uvd_x402_sdk-0.4.1.dist-info/METADATA,sha256=3cD7Kz9_fONGwbZVUBMOxXqglRmC_wikuBH8OWpIT24,29618
+uvd_x402_sdk-0.4.1.dist-info/WHEEL,sha256=tZoeGjtWxWRfdplE7E3d45VPlLNQnvbKiYnx7gwAy8A,92
+uvd_x402_sdk-0.4.1.dist-info/top_level.txt,sha256=Exyjj_Kl7CDAGFMi72lT9oFPOYiRNZb3l8tr906mMmc,13
+uvd_x402_sdk-0.4.1.dist-info/RECORD,,