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

uvd_x402_sdk/networks/algorand.py

@@ -1,33 +1,51 @@
 """
-Algorand network configurations.
+Algorand network configurations for x402 payments.
 
 This module supports Algorand blockchain networks:
-- Algorand mainnet
-- Algorand testnet
+- Algorand mainnet (network: "algorand-mainnet" or "algorand")
+- Algorand testnet (network: "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
+Payment Flow (GoPlausible x402-avm Atomic Group Spec):
+1. Client creates an ATOMIC GROUP of TWO transactions:
+   - Transaction 0 (fee tx): Zero-amount payment FROM facilitator TO facilitator
+     This transaction pays fees for both txns. Client creates this UNSIGNED.
+   - Transaction 1 (payment tx): ASA transfer FROM client TO merchant
+     Client SIGNS this transaction.
+2. Both transactions share a GROUP ID computed by Algorand SDK.
+3. Fee pooling: Transaction 0's fee covers Transaction 1's fee (gasless).
+4. Facilitator completes: Signs transaction 0 and submits the atomic group.
+
+Payload Format:
+{
+    "x402Version": 1,
+    "scheme": "exact",
+    "network": "algorand-mainnet",
+    "payload": {
+        "paymentIndex": 1,
+        "paymentGroup": [
+            "<base64-msgpack-UNSIGNED-fee-tx>",
+            "<base64-msgpack-SIGNED-asa-transfer>"
+        ]
+    }
+}
 
 Address Format:
 - Algorand addresses are 58 characters, base32 encoded
 - Example: AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAY5HFKQ
+
+Dependencies:
+- algosdk (optional): Required for building atomic groups
+  Install with: pip install py-algorand-sdk
 """
 
 import base64
 import re
-from typing import Any, Dict, Optional
+from dataclasses import dataclass
+from typing import Any, Callable, Dict, List, Optional
 
 from uvd_x402_sdk.networks.base import (
     NetworkConfig,
@@ -63,6 +81,8 @@ ALGORAND = NetworkConfig(
         "genesis_id": "mainnet-v1.0",
         # Genesis hash (for CAIP-2)
         "genesis_hash": "wGHE2Pwdvd7S12BL5FaOP20EGYesN73ktiC1qzkkit8=",
+        # x402 network name (facilitator expects this format)
+        "x402_network": "algorand-mainnet",
     },
 )
 
@@ -89,6 +109,8 @@ ALGORAND_TESTNET = NetworkConfig(
         "genesis_id": "testnet-v1.0",
         # Genesis hash
         "genesis_hash": "SGO1GKSzyE7IEPItTxCByw9x8FmnrCDexi9/cOUJOiI=",
+        # x402 network name (facilitator expects this format)
+        "x402_network": "algorand-testnet",
     },
 )
 
@@ -97,6 +119,34 @@ register_network(ALGORAND)
 register_network(ALGORAND_TESTNET)
 
 
+# =============================================================================
+# Algorand Payment Payload (x402-avm Atomic Group Spec)
+# =============================================================================
+
+
+@dataclass
+class AlgorandPaymentPayload:
+    """
+    Algorand payment payload for x402 atomic group format.
+
+    Attributes:
+        payment_index: Index of the payment transaction in the group (typically 1)
+        payment_group: List of base64-encoded msgpack transactions
+                      [0] = unsigned fee transaction
+                      [1] = signed ASA transfer transaction
+    """
+
+    payment_index: int
+    payment_group: List[str]
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary for JSON serialization."""
+        return {
+            "paymentIndex": self.payment_index,
+            "paymentGroup": self.payment_group,
+        }
+
+
 # =============================================================================
 # Algorand-specific utilities
 # =============================================================================
@@ -162,59 +212,99 @@ def is_valid_algorand_address(address: str) -> bool:
 
 def validate_algorand_payload(payload: Dict[str, Any]) -> bool:
     """
-    Validate an Algorand payment payload structure.
+    Validate an Algorand payment payload structure (x402-avm atomic group format).
 
     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
+    - paymentIndex: Index of the payment transaction (typically 1)
+    - paymentGroup: List of base64-encoded msgpack transactions
+      - [0]: Unsigned fee transaction (facilitator -> facilitator)
+      - [1]: Signed ASA transfer (client -> merchant)
 
     Args:
-        payload: Payload dictionary from x402 payment
+        payload: Payload dictionary from x402 payment (the inner "payload" field)
 
     Returns:
         True if valid, raises ValueError if invalid
+
+    Example:
+        >>> payload = {
+        ...     "paymentIndex": 1,
+        ...     "paymentGroup": [
+        ...         "base64-unsigned-fee-tx...",
+        ...         "base64-signed-payment-tx..."
+        ...     ]
+        ... }
+        >>> validate_algorand_payload(payload)
+        True
     """
-    required_fields = ["from", "to", "amount", "assetId", "signedTxn"]
+    # Check required fields
+    if "paymentIndex" not in payload:
+        raise ValueError("Algorand payload missing 'paymentIndex' field")
+    if "paymentGroup" not in payload:
+        raise ValueError("Algorand payload missing 'paymentGroup' field")
+
+    # Validate paymentIndex
+    payment_index = payload["paymentIndex"]
+    if not isinstance(payment_index, int) or payment_index < 0:
+        raise ValueError(f"paymentIndex must be a non-negative integer: {payment_index}")
+
+    # Validate paymentGroup
+    payment_group = payload["paymentGroup"]
+    if not isinstance(payment_group, list):
+        raise ValueError("paymentGroup must be a list")
+
+    if len(payment_group) < 2:
+        raise ValueError(
+            f"paymentGroup must contain at least 2 transactions, got {len(payment_group)}"
+        )
+
+    if payment_index >= len(payment_group):
+        raise ValueError(
+            f"paymentIndex ({payment_index}) out of range for paymentGroup "
+            f"(length {len(payment_group)})"
+        )
+
+    # Validate each transaction in the group is valid base64
+    for i, txn_b64 in enumerate(payment_group):
+        if not isinstance(txn_b64, str):
+            raise ValueError(f"paymentGroup[{i}] must be a string")
+
+        try:
+            txn_bytes = base64.b64decode(txn_b64)
+            if len(txn_bytes) < 50:
+                raise ValueError(
+                    f"paymentGroup[{i}] transaction too short: {len(txn_bytes)} bytes"
+                )
+        except Exception as e:
+            raise ValueError(
+                f"paymentGroup[{i}] is not valid base64: {e}"
+            ) from e
 
-    for field in required_fields:
-        if field not in payload:
-            raise ValueError(f"Algorand payload missing '{field}' field")
+    return True
 
-    # 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
+def get_x402_network_name(network_name: str) -> str:
+    """
+    Get the x402 network name for an Algorand network.
 
-    # 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
+    The facilitator expects "algorand-mainnet" or "algorand-testnet".
 
-    # 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
+    Args:
+        network_name: SDK network name ('algorand' or 'algorand-testnet')
 
-    return True
+    Returns:
+        x402 network name ('algorand-mainnet' or 'algorand-testnet')
+    """
+    from uvd_x402_sdk.networks.base import get_network
+
+    network = get_network(network_name)
+    if not network:
+        # Default mapping
+        if network_name == "algorand":
+            return "algorand-mainnet"
+        return network_name
+
+    return network.extra_config.get("x402_network", network_name)
 
 
 def get_explorer_tx_url(network_name: str, tx_id: str) -> Optional[str]:
@@ -285,3 +375,176 @@ def get_usdc_asa_id(network_name: str) -> Optional[int]:
         return int(network.usdc_address)
     except (ValueError, TypeError):
         return None
+
+
+# =============================================================================
+# Atomic Group Builder (requires algosdk)
+# =============================================================================
+
+
+def build_atomic_group(
+    sender_address: str,
+    recipient_address: str,
+    amount: int,
+    asset_id: int,
+    facilitator_address: str,
+    sign_transaction: Callable,
+    algod_client: Optional[Any] = None,
+    suggested_params: Optional[Any] = None,
+) -> AlgorandPaymentPayload:
+    """
+    Build an Algorand atomic group for x402 payment.
+
+    This creates the two-transaction atomic group required by the facilitator:
+    - Transaction 0: Unsigned fee payment (facilitator -> facilitator, 0 amount)
+    - Transaction 1: Signed ASA transfer (sender -> recipient)
+
+    Requires: pip install py-algorand-sdk
+
+    Args:
+        sender_address: Client's Algorand address
+        recipient_address: Merchant's Algorand address (from payTo)
+        amount: Amount in micro-units (1 USDC = 1,000,000)
+        asset_id: USDC ASA ID (31566704 mainnet, 10458941 testnet)
+        facilitator_address: Facilitator address (from extra.feePayer)
+        sign_transaction: Function that signs a transaction.
+                         Signature: (transaction) -> SignedTransaction
+                         Can use algosdk's transaction.sign(private_key)
+        algod_client: Optional AlgodClient for getting suggested params.
+                     If not provided, suggested_params must be given.
+        suggested_params: Optional SuggestedParams. If not provided,
+                         algod_client.suggested_params() is called.
+
+    Returns:
+        AlgorandPaymentPayload with paymentIndex and paymentGroup
+
+    Raises:
+        ImportError: If algosdk is not installed
+        ValueError: If neither algod_client nor suggested_params provided
+
+    Example:
+        >>> from algosdk import transaction
+        >>> from algosdk.v2client import algod
+        >>>
+        >>> client = algod.AlgodClient("", "https://mainnet-api.algonode.cloud")
+        >>> payload = build_atomic_group(
+        ...     sender_address="SENDER...",
+        ...     recipient_address="MERCHANT...",
+        ...     amount=1000000,  # 1 USDC
+        ...     asset_id=31566704,
+        ...     facilitator_address="FACILITATOR...",
+        ...     sign_transaction=lambda txn: txn.sign(private_key),
+        ...     algod_client=client,
+        ... )
+    """
+    try:
+        from algosdk import encoding, transaction
+    except ImportError as e:
+        raise ImportError(
+            "algosdk is required for building atomic groups. "
+            "Install with: pip install py-algorand-sdk"
+        ) from e
+
+    # Get suggested params
+    if suggested_params is None:
+        if algod_client is None:
+            raise ValueError(
+                "Either algod_client or suggested_params must be provided"
+            )
+        suggested_params = algod_client.suggested_params()
+
+    # Transaction 0: Fee payment (facilitator -> facilitator, 0 amount)
+    # This transaction pays fees for both txns in the group
+    fee_txn = transaction.PaymentTxn(
+        sender=facilitator_address,
+        receiver=facilitator_address,  # self-transfer
+        amt=0,
+        sp=suggested_params,
+    )
+    # Cover both transactions (1000 microAlgos each = 2000 total)
+    fee_txn.fee = 2000
+
+    # Transaction 1: ASA transfer (client -> merchant)
+    payment_txn = transaction.AssetTransferTxn(
+        sender=sender_address,
+        receiver=recipient_address,
+        amt=amount,
+        index=asset_id,
+        sp=suggested_params,
+    )
+    # Fee paid by transaction 0
+    payment_txn.fee = 0
+
+    # Assign group ID to both transactions
+    group_id = transaction.calculate_group_id([fee_txn, payment_txn])
+    fee_txn.group = group_id
+    payment_txn.group = group_id
+
+    # Encode fee transaction (UNSIGNED - facilitator will sign)
+    unsigned_fee_txn_bytes = encoding.msgpack_encode(fee_txn)
+    unsigned_fee_txn_base64 = base64.b64encode(unsigned_fee_txn_bytes).decode("utf-8")
+
+    # Sign and encode payment transaction
+    signed_payment_txn = sign_transaction(payment_txn)
+    signed_payment_txn_bytes = encoding.msgpack_encode(signed_payment_txn)
+    signed_payment_txn_base64 = base64.b64encode(signed_payment_txn_bytes).decode("utf-8")
+
+    return AlgorandPaymentPayload(
+        payment_index=1,  # Index of the payment transaction
+        payment_group=[
+            unsigned_fee_txn_base64,   # Transaction 0: unsigned fee tx
+            signed_payment_txn_base64,  # Transaction 1: signed payment tx
+        ],
+    )
+
+
+def create_private_key_signer(private_key: str) -> Callable:
+    """
+    Create a transaction signer from a private key.
+
+    Args:
+        private_key: Algorand private key (base64 encoded)
+
+    Returns:
+        Function that signs transactions
+
+    Example:
+        >>> signer = create_private_key_signer(my_private_key)
+        >>> payload = build_atomic_group(..., sign_transaction=signer)
+    """
+    def sign(txn: Any) -> Any:
+        return txn.sign(private_key)
+    return sign
+
+
+def build_x402_payment_request(
+    payload: AlgorandPaymentPayload,
+    network: str = "algorand-mainnet",
+    scheme: str = "exact",
+    version: int = 1,
+) -> Dict[str, Any]:
+    """
+    Build a complete x402 payment request for Algorand.
+
+    Args:
+        payload: AlgorandPaymentPayload from build_atomic_group()
+        network: Network name ("algorand-mainnet" or "algorand-testnet")
+        scheme: Payment scheme (default "exact")
+        version: x402 version (default 1)
+
+    Returns:
+        Complete x402 payment request dictionary
+
+    Example:
+        >>> payload = build_atomic_group(...)
+        >>> request = build_x402_payment_request(payload)
+        >>> # Send as X-PAYMENT header (base64 encoded JSON)
+        >>> import json, base64
+        >>> header = base64.b64encode(json.dumps(request).encode()).decode()
+    """
+    return {
+        "x402Version": version,
+        "scheme": scheme,
+        "network": network,
+        "payload": payload.to_dict(),
+    }

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: uvd-x402-sdk
-Version: 0.4.1
+Version: 0.4.2
 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
@@ -24,8 +24,10 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: httpx>=0.24.0
 Requires-Dist: pydantic>=2.0.0
+Provides-Extra: algorand
+Requires-Dist: py-algorand-sdk>=2.0.0; extra == "algorand"
 Provides-Extra: all
-Requires-Dist: uvd-x402-sdk[aws,django,fastapi,flask,web3]; extra == "all"
+Requires-Dist: uvd-x402-sdk[algorand,aws,django,fastapi,flask,web3]; extra == "all"
 Provides-Extra: aws
 Requires-Dist: boto3>=1.26.0; extra == "aws"
 Provides-Extra: dev

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

@@ -11,14 +11,14 @@ uvd_x402_sdk/integrations/fastapi_integration.py,sha256=j5h1IJwFLBBoWov7ANLCFaxe
 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=LKl_TljVoCDb27YB4X_VbQN8XKbdwWFAsCwgiqQtlgo,2092
-uvd_x402_sdk/networks/algorand.py,sha256=ACaVMyXItRX3M29GPwwMMxECMjNXx3FlYARNBeAztH4,8601
+uvd_x402_sdk/networks/algorand.py,sha256=zcpU5U4V9weiFZ_Zfc-khWaadTldO6KKOIg5ZdxXaRs,17819
 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=-snAeE3OxJU_kaGb_z4NOU6k0SGAD4DBPhJcPbgrdgo,11675
 uvd_x402_sdk/networks/stellar.py,sha256=c-6re-dVc2-6gJ5rL4krUTaFsPz5vkactOJD-0wowBA,3534
-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,,
+uvd_x402_sdk-0.4.2.dist-info/LICENSE,sha256=OcLzB_iSgMbvk7b0dlyvleY_IbL2WUaPxvn1CHw2uAc,1073
+uvd_x402_sdk-0.4.2.dist-info/METADATA,sha256=dOuyD4J4cWQtHx3Ia0uhst7xIf4BMwhEr3ULgPkbljw,29711
+uvd_x402_sdk-0.4.2.dist-info/WHEEL,sha256=tZoeGjtWxWRfdplE7E3d45VPlLNQnvbKiYnx7gwAy8A,92
+uvd_x402_sdk-0.4.2.dist-info/top_level.txt,sha256=Exyjj_Kl7CDAGFMi72lT9oFPOYiRNZb3l8tr906mMmc,13
+uvd_x402_sdk-0.4.2.dist-info/RECORD,,