uvd-x402-sdk 0.2.0__py3-none-any.whl

uvd_x402_sdk/networks/near.py

@@ -0,0 +1,397 @@
+"""
+NEAR Protocol network configuration.
+
+NEAR uses NEP-366 meta-transactions for gasless payments:
+1. User creates a DelegateAction containing ft_transfer
+2. User signs to create SignedDelegateAction (Borsh serialized)
+3. Facilitator wraps in Action::Delegate and submits
+4. Facilitator pays all gas - user pays ZERO NEAR
+
+NEP-366 Structure:
+- DelegateAction: sender_id, receiver_id, actions, nonce, max_block_height, public_key
+- SignedDelegateAction: delegate_action + ed25519 signature
+- Hash prefix: 2^30 + 366 = 0x4000016E (little-endian)
+
+Borsh Serialization Format:
+- u8: 1 byte
+- u32: 4 bytes little-endian
+- u64: 8 bytes little-endian
+- u128: 16 bytes little-endian
+- string: u32 length prefix + UTF-8 bytes
+- bytes: u32 length prefix + raw bytes
+- fixed_bytes: raw bytes (no prefix)
+"""
+
+import base64
+import struct
+from typing import Optional, Dict, Any
+
+from uvd_x402_sdk.networks.base import (
+    NetworkConfig,
+    NetworkType,
+    register_network,
+)
+
+# NEP-366 hash prefix: (2^30 + 366) = 1073742190
+NEP366_PREFIX = ((2**30) + 366).to_bytes(4, 'little')
+
+
+# NEAR Mainnet
+NEAR = NetworkConfig(
+    name="near",
+    display_name="NEAR Protocol",
+    network_type=NetworkType.NEAR,
+    chain_id=0,  # Non-EVM, no chain ID
+    # Native Circle USDC on NEAR (account ID hash)
+    usdc_address="17208628f84f5d6ad33f0da3bbbeb27ffcb398eac501a31bd6ad2011e36133a1",
+    usdc_decimals=6,
+    usdc_domain_name="",  # Not applicable for NEAR
+    usdc_domain_version="",
+    rpc_url="https://rpc.mainnet.near.org",
+    enabled=True,  # ENABLED: Facilitator supports NEAR via NEP-366
+    extra_config={
+        # Network identifier
+        "network_id": "mainnet",
+        # Alternative RPC endpoints (CORS-friendly)
+        "rpc_endpoints": [
+            "https://near.drpc.org",
+            "https://public-rpc.blockpi.io/http/near",
+            "https://endpoints.omniatech.io/v1/near/mainnet/public",
+            "https://rpc.mainnet.near.org",
+            "https://near.lava.build",
+        ],
+        # Block explorer
+        "explorer_url": "https://nearblocks.io",
+        # NEP-366 prefix (2^30 + 366 as u32 little-endian)
+        "nep366_prefix": NEP366_PREFIX,
+        # Default gas for ft_transfer
+        "ft_transfer_gas": 30_000_000_000_000,  # 30 TGas
+        # Deposit for ft_transfer (1 yoctoNEAR)
+        "ft_transfer_deposit": 1,
+    },
+)
+
+# Register NEAR network
+register_network(NEAR)
+
+
+# =============================================================================
+# NEAR-specific utilities
+# =============================================================================
+
+
+def create_ft_transfer_args(
+    receiver_id: str,
+    amount: int,
+    memo: str = "",
+) -> dict:
+    """
+    Create arguments for NEAR ft_transfer function call.
+
+    Args:
+        receiver_id: NEAR account ID to receive tokens
+        amount: Amount in base units (6 decimals for USDC)
+        memo: Optional transfer memo
+
+    Returns:
+        Dictionary of ft_transfer arguments
+    """
+    return {
+        "receiver_id": receiver_id,
+        "amount": str(amount),
+        "memo": memo or None,
+    }
+
+
+def calculate_max_block_height(current_height: int, blocks_valid: int = 1000) -> int:
+    """
+    Calculate max_block_height for DelegateAction.
+
+    Args:
+        current_height: Current block height from RPC
+        blocks_valid: Number of blocks the action is valid for (~17 minutes at 1 block/s)
+
+    Returns:
+        Max block height for the action
+    """
+    return current_height + blocks_valid
+
+
+def base58_decode(encoded: str) -> bytes:
+    """
+    Decode a base58 string to bytes.
+
+    NEAR public keys use ed25519:base58 format.
+
+    Args:
+        encoded: Base58 encoded string (without prefix)
+
+    Returns:
+        Decoded bytes
+    """
+    ALPHABET = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz"
+    BASE = 58
+
+    num = 0
+    for char in encoded:
+        index = ALPHABET.index(char)
+        if index == -1:
+            raise ValueError(f"Invalid base58 character: {char}")
+        num = num * BASE + index
+
+    # Convert to bytes (32 bytes for ED25519 public key)
+    result = []
+    while num > 0:
+        result.append(num & 0xFF)
+        num >>= 8
+
+    # Pad to 32 bytes and reverse
+    while len(result) < 32:
+        result.append(0)
+
+    return bytes(reversed(result))
+
+
+def decode_near_public_key(public_key: str) -> bytes:
+    """
+    Decode a NEAR public key from ed25519:base58 format to raw bytes.
+
+    Args:
+        public_key: Public key in format 'ed25519:base58string'
+
+    Returns:
+        32 bytes of the public key
+    """
+    # Remove ed25519: prefix if present
+    if public_key.startswith("ed25519:"):
+        public_key = public_key[8:]
+
+    return base58_decode(public_key)
+
+
+# =============================================================================
+# NEP-366 Borsh Serialization
+# =============================================================================
+
+
+class BorshSerializer:
+    """
+    Simple Borsh serializer for NEAR transactions.
+
+    Borsh (Binary Object Representation Serializer for Hashing) is NEAR's
+    canonical binary serialization format. This implementation handles
+    the subset needed for NEP-366 meta-transactions.
+    """
+
+    def __init__(self) -> None:
+        self.buffer = bytearray()
+
+    def write_u8(self, value: int) -> "BorshSerializer":
+        """Write unsigned 8-bit integer."""
+        self.buffer.extend(struct.pack('<B', value))
+        return self
+
+    def write_u32(self, value: int) -> "BorshSerializer":
+        """Write unsigned 32-bit integer (little-endian)."""
+        self.buffer.extend(struct.pack('<I', value))
+        return self
+
+    def write_u64(self, value: int) -> "BorshSerializer":
+        """Write unsigned 64-bit integer (little-endian)."""
+        self.buffer.extend(struct.pack('<Q', value))
+        return self
+
+    def write_u128(self, value: int) -> "BorshSerializer":
+        """Write unsigned 128-bit integer (little-endian)."""
+        low = value & 0xFFFFFFFFFFFFFFFF
+        high = value >> 64
+        self.buffer.extend(struct.pack('<QQ', low, high))
+        return self
+
+    def write_string(self, value: str) -> "BorshSerializer":
+        """Write length-prefixed UTF-8 string."""
+        encoded = value.encode('utf-8')
+        self.write_u32(len(encoded))
+        self.buffer.extend(encoded)
+        return self
+
+    def write_fixed_bytes(self, data: bytes) -> "BorshSerializer":
+        """Write fixed-length bytes (no prefix)."""
+        self.buffer.extend(data)
+        return self
+
+    def write_bytes(self, data: bytes) -> "BorshSerializer":
+        """Write length-prefixed bytes."""
+        self.write_u32(len(data))
+        self.buffer.extend(data)
+        return self
+
+    def get_bytes(self) -> bytes:
+        """Get the serialized bytes."""
+        return bytes(self.buffer)
+
+
+def serialize_non_delegate_action(
+    receiver_id: str,
+    amount: int,
+    memo: Optional[str] = None,
+) -> bytes:
+    """
+    Serialize a NonDelegateAction for ft_transfer (NEP-366).
+
+    This creates the action that will be wrapped in a DelegateAction.
+    The action type is FunctionCall (type 2).
+
+    Args:
+        receiver_id: NEAR account ID to receive tokens
+        amount: Amount in raw units (6 decimals for USDC)
+        memo: Optional transfer memo
+
+    Returns:
+        Borsh-serialized action bytes
+    """
+    import json
+
+    # Build ft_transfer args
+    args: Dict[str, Any] = {
+        "receiver_id": receiver_id,
+        "amount": str(amount),
+    }
+    if memo:
+        args["memo"] = memo
+
+    args_json = json.dumps(args, separators=(',', ':')).encode('utf-8')
+
+    ser = BorshSerializer()
+    ser.write_u8(2)  # FunctionCall action type
+    ser.write_string("ft_transfer")  # Method name
+    ser.write_bytes(args_json)  # Args as JSON bytes
+    ser.write_u64(30_000_000_000_000)  # 30 TGas
+    ser.write_u128(1)  # 1 yoctoNEAR deposit (required for ft_transfer)
+
+    return ser.get_bytes()
+
+
+def serialize_delegate_action(
+    sender_id: str,
+    receiver_id: str,
+    actions_bytes: bytes,
+    nonce: int,
+    max_block_height: int,
+    public_key_bytes: bytes,
+) -> bytes:
+    """
+    Serialize a DelegateAction for NEP-366 meta-transactions.
+
+    Args:
+        sender_id: NEAR account ID of the sender
+        receiver_id: NEAR contract ID (USDC contract)
+        actions_bytes: Borsh-serialized NonDelegateAction
+        nonce: Access key nonce + 1
+        max_block_height: Block height when action expires
+        public_key_bytes: 32-byte ED25519 public key
+
+    Returns:
+        Borsh-serialized DelegateAction bytes
+    """
+    ser = BorshSerializer()
+    ser.write_string(sender_id)
+    ser.write_string(receiver_id)
+    ser.write_u32(1)  # 1 action
+    ser.write_fixed_bytes(actions_bytes)
+    ser.write_u64(nonce)
+    ser.write_u64(max_block_height)
+    ser.write_u8(0)  # ED25519 key type
+    ser.write_fixed_bytes(public_key_bytes)
+
+    return ser.get_bytes()
+
+
+def serialize_signed_delegate_action(
+    delegate_action_bytes: bytes,
+    signature_bytes: bytes,
+) -> bytes:
+    """
+    Serialize a SignedDelegateAction for NEP-366.
+
+    Args:
+        delegate_action_bytes: Borsh-serialized DelegateAction
+        signature_bytes: 64-byte ED25519 signature
+
+    Returns:
+        Borsh-serialized SignedDelegateAction bytes
+    """
+    ser = BorshSerializer()
+    ser.write_fixed_bytes(delegate_action_bytes)
+    ser.write_u8(0)  # ED25519 signature type
+    ser.write_fixed_bytes(signature_bytes)
+
+    return ser.get_bytes()
+
+
+# =============================================================================
+# NEP-366 Payload Validation
+# =============================================================================
+
+
+def validate_near_payload(payload: Dict[str, Any]) -> bool:
+    """
+    Validate a NEAR payment payload structure.
+
+    The payload must contain a base64-encoded SignedDelegateAction.
+
+    Args:
+        payload: Payload dictionary from x402 payment
+
+    Returns:
+        True if valid, raises ValueError if invalid
+    """
+    if "signedDelegateAction" not in payload:
+        raise ValueError("NEAR payload missing 'signedDelegateAction' field")
+
+    signed_delegate_b64 = payload["signedDelegateAction"]
+
+    try:
+        # Decode base64
+        signed_delegate_bytes = base64.b64decode(signed_delegate_b64)
+    except Exception as e:
+        raise ValueError(f"Invalid base64 in signedDelegateAction: {e}")
+
+    # Basic length validation
+    # Minimum: sender_id (4 + 1) + receiver_id (4 + 1) + actions_count (4) +
+    #          action (at least 1) + nonce (8) + max_block_height (8) +
+    #          key_type (1) + public_key (32) + sig_type (1) + signature (64)
+    min_length = 4 + 1 + 4 + 1 + 4 + 1 + 8 + 8 + 1 + 32 + 1 + 64
+    if len(signed_delegate_bytes) < min_length:
+        raise ValueError(
+            f"SignedDelegateAction too short: {len(signed_delegate_bytes)} bytes, "
+            f"minimum {min_length} bytes"
+        )
+
+    return True
+
+
+def is_valid_near_account_id(account_id: str) -> bool:
+    """
+    Validate a NEAR account ID format.
+
+    NEAR account IDs:
+    - Are 2-64 characters
+    - Contain only a-z, 0-9, _, -, .
+    - Cannot start with _ or -
+    - Cannot end with .
+
+    Args:
+        account_id: NEAR account ID to validate
+
+    Returns:
+        True if valid format
+    """
+    if not account_id or len(account_id) < 2 or len(account_id) > 64:
+        return False
+
+    if account_id.startswith(('_', '-')) or account_id.endswith('.'):
+        return False
+
+    allowed = set('abcdefghijklmnopqrstuvwxyz0123456789_-.')
+    return all(c in allowed for c in account_id)

uvd_x402_sdk/networks/solana.py

@@ -0,0 +1,269 @@
+"""
+Solana Virtual Machine (SVM) network configurations.
+
+This module supports all SVM-compatible chains:
+- Solana (mainnet)
+- Fogo (fast finality SVM)
+
+All SVM chains use the same payment flow:
+1. User creates a partially-signed VersionedTransaction
+2. Transaction contains SPL token TransferChecked instruction
+3. Facilitator is fee payer (user pays ZERO SOL/tokens)
+4. Facilitator co-signs and submits transaction
+
+Transaction Structure (REQUIRED by facilitator):
+- Instruction 0: SetComputeUnitLimit (units: 20,000)
+- Instruction 1: SetComputeUnitPrice (microLamports: 1)
+- Instruction 2: TransferChecked (USDC transfer)
+
+The facilitator validates this exact structure in src/chain/solana.rs.
+"""
+
+import base64
+from typing import Dict, Any, Optional
+
+from uvd_x402_sdk.networks.base import (
+    NetworkConfig,
+    NetworkType,
+    register_network,
+)
+
+
+# =============================================================================
+# SVM Networks Configuration
+# =============================================================================
+
+# Solana Mainnet
+SOLANA = NetworkConfig(
+    name="solana",
+    display_name="Solana",
+    network_type=NetworkType.SVM,  # Use SVM type for all Solana-compatible chains
+    chain_id=0,  # Non-EVM, no chain ID
+    usdc_address="EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",  # USDC SPL token mint
+    usdc_decimals=6,
+    usdc_domain_name="",  # Not applicable for SVM
+    usdc_domain_version="",
+    rpc_url="https://api.mainnet-beta.solana.com",
+    enabled=True,
+    extra_config={
+        # Token program ID (standard SPL token program)
+        "token_program_id": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",
+        # Associated Token Account program
+        "ata_program_id": "ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL",
+        # Default compute units for transfer
+        "compute_units": 20000,
+        # Default priority fee in microLamports
+        "priority_fee_microlamports": 1,
+        # Block explorer
+        "explorer_url": "https://solscan.io",
+        # Genesis hash (first 32 chars for CAIP-2)
+        "genesis_hash": "5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
+        # Network type identifier
+        "svm_network": "solana",
+    },
+)
+
+# Fogo (SVM chain with ultra-fast finality)
+FOGO = NetworkConfig(
+    name="fogo",
+    display_name="Fogo",
+    network_type=NetworkType.SVM,
+    chain_id=0,  # Non-EVM, no chain ID
+    usdc_address="uSd2czE61Evaf76RNbq4KPpXnkiL3irdzgLFUMe3NoG",  # Fogo USDC mint
+    usdc_decimals=6,
+    usdc_domain_name="",  # Not applicable for SVM
+    usdc_domain_version="",
+    rpc_url="https://rpc.fogo.nightly.app/",
+    enabled=True,
+    extra_config={
+        # Token program ID (standard SPL token program - same as Solana)
+        "token_program_id": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",
+        # Associated Token Account program (same as Solana)
+        "ata_program_id": "ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL",
+        # Default compute units for transfer
+        "compute_units": 20000,
+        # Default priority fee in microLamports
+        "priority_fee_microlamports": 1,
+        # Block explorer (placeholder - update when available)
+        "explorer_url": "https://explorer.fogo.nightly.app",
+        # Network type identifier
+        "svm_network": "fogo",
+        # Fogo-specific: Ultra-fast finality (~400ms)
+        "finality_ms": 400,
+    },
+)
+
+# Register SVM networks
+register_network(SOLANA)
+register_network(FOGO)
+
+
+# =============================================================================
+# SVM-specific utilities
+# =============================================================================
+
+
+def is_svm_network(network_name: str) -> bool:
+    """
+    Check if a network is SVM-compatible.
+
+    Args:
+        network_name: Network name to check
+
+    Returns:
+        True if network uses SVM (Solana, Fogo, etc.)
+    """
+    from uvd_x402_sdk.networks.base import get_network, NetworkType
+
+    network = get_network(network_name)
+    if not network:
+        return False
+    return NetworkType.is_svm(network.network_type)
+
+
+def get_svm_networks() -> list:
+    """
+    Get all registered SVM networks.
+
+    Returns:
+        List of SVM NetworkConfig instances
+    """
+    from uvd_x402_sdk.networks.base import list_networks, NetworkType
+
+    return [
+        n for n in list_networks(enabled_only=True)
+        if NetworkType.is_svm(n.network_type)
+    ]
+
+
+def get_associated_token_address(owner: str, mint: str) -> str:
+    """
+    Derive the Associated Token Account (ATA) address for an owner and mint.
+
+    Note: This is a placeholder. For actual derivation, use the solana-py library:
+
+        from solders.pubkey import Pubkey
+        from spl.token.constants import TOKEN_PROGRAM_ID, ASSOCIATED_TOKEN_PROGRAM_ID
+        from spl.token.instructions import get_associated_token_address
+
+    Args:
+        owner: Owner's public key (base58)
+        mint: Token mint address (base58)
+
+    Returns:
+        Associated token account address (base58)
+    """
+    # This would require solders/solana-py for actual implementation
+    # Returning empty string as placeholder
+    raise NotImplementedError(
+        "ATA derivation requires solana-py library. "
+        "Install with: pip install uvd-x402-sdk[solana]"
+    )
+
+
+def validate_svm_transaction_structure(transaction_base64: str) -> bool:
+    """
+    Validate that an SVM transaction has the correct structure for x402.
+
+    The facilitator expects:
+    - VersionedTransaction with exactly 3 instructions
+    - Instruction 0: SetComputeUnitLimit
+    - Instruction 1: SetComputeUnitPrice
+    - Instruction 2: TransferChecked (SPL token)
+
+    Args:
+        transaction_base64: Base64-encoded serialized transaction
+
+    Returns:
+        True if structure is valid
+
+    Raises:
+        ValueError: If structure is invalid
+    """
+    try:
+        tx_bytes = base64.b64decode(transaction_base64)
+    except Exception as e:
+        raise ValueError(f"Invalid base64 transaction: {e}")
+
+    # Basic length validation
+    # Minimum: version (1) + header (3) + accounts array (varies) + blockhash (32) + instructions
+    if len(tx_bytes) < 50:
+        raise ValueError(f"Transaction too short: {len(tx_bytes)} bytes")
+
+    # Full validation requires solders/solana-py
+    # For now, we just check basic structure
+    return True
+
+
+def validate_svm_payload(payload: Dict[str, Any]) -> bool:
+    """
+    Validate an SVM payment payload structure.
+
+    The payload must contain a base64-encoded partially-signed transaction.
+
+    Args:
+        payload: Payload dictionary from x402 payment
+
+    Returns:
+        True if valid, raises ValueError if invalid
+    """
+    if "transaction" not in payload:
+        raise ValueError("SVM payload missing 'transaction' field")
+
+    transaction_b64 = payload["transaction"]
+
+    try:
+        tx_bytes = base64.b64decode(transaction_b64)
+    except Exception as e:
+        raise ValueError(f"Invalid base64 in transaction: {e}")
+
+    # Basic length validation
+    if len(tx_bytes) < 50:
+        raise ValueError(f"Transaction too short: {len(tx_bytes)} bytes")
+
+    return True
+
+
+def is_valid_solana_address(address: str) -> bool:
+    """
+    Validate a Solana/SVM public key format.
+
+    Solana addresses are base58-encoded 32-byte public keys.
+
+    Args:
+        address: Address to validate
+
+    Returns:
+        True if valid base58 address
+    """
+    if not address or not isinstance(address, str):
+        return False
+
+    # Base58 alphabet (no 0, O, I, l)
+    base58_alphabet = set("123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz")
+
+    if not all(c in base58_alphabet for c in address):
+        return False
+
+    # Typical Solana address length is 32-44 characters
+    return 32 <= len(address) <= 44
+
+
+# =============================================================================
+# Transaction Building Utilities (for reference)
+# =============================================================================
+
+# These constants are useful for building transactions programmatically
+
+# Compute Budget Program
+COMPUTE_BUDGET_PROGRAM_ID = "ComputeBudget111111111111111111111111111111"
+
+# SetComputeUnitLimit instruction discriminator
+SET_COMPUTE_UNIT_LIMIT_DISCRIMINATOR = 2
+
+# SetComputeUnitPrice instruction discriminator
+SET_COMPUTE_UNIT_PRICE_DISCRIMINATOR = 3
+
+# Default values for x402 transactions
+DEFAULT_COMPUTE_UNITS = 20000
+DEFAULT_PRIORITY_FEE_MICROLAMPORTS = 1