stablepay-verifier 0.1.0__py3-none-any.whl

stablepay_verifier/__init__.py

@@ -0,0 +1,18 @@
+"""
+StablePay Verifier - Verify stablecoin payments on-chain.
+
+No custody. No fees. Just truth.
+"""
+
+__version__ = "0.1.0"
+__app_name__ = "stablepay"
+
+from stablepay_verifier.models import PaymentResult, PaymentStatus, VerifyRequest
+from stablepay_verifier.verifier import verify_payment
+
+__all__ = [
+    "verify_payment",
+    "PaymentResult",
+    "PaymentStatus",
+    "VerifyRequest",
+]

stablepay_verifier/__main__.py

@@ -0,0 +1,6 @@
+"""Entry point for running as module: python -m stablepay_verifier"""
+
+from stablepay_verifier.cli import app
+
+if __name__ == "__main__":
+    app()

stablepay_verifier/chains.py

@@ -0,0 +1,177 @@
+"""
+Chain and token configurations for StablePay Verifier.
+"""
+
+from stablepay_verifier.models import ChainConfig, TokenConfig
+
+# Supported blockchain networks
+CHAINS: dict[str, ChainConfig] = {
+    "polygon": ChainConfig(
+        name="Polygon",
+        chain_id=137,
+        default_rpc="https://polygon-rpc.com",
+        block_time=2.0,
+        explorer_url="https://polygonscan.com",
+    ),
+    "ethereum": ChainConfig(
+        name="Ethereum",
+        chain_id=1,
+        default_rpc="https://eth.llamarpc.com",
+        block_time=12.0,
+        explorer_url="https://etherscan.io",
+    ),
+    "arbitrum": ChainConfig(
+        name="Arbitrum One",
+        chain_id=42161,
+        default_rpc="https://arb1.arbitrum.io/rpc",
+        block_time=0.25,
+        explorer_url="https://arbiscan.io",
+    ),
+    "base": ChainConfig(
+        name="Base",
+        chain_id=8453,
+        default_rpc="https://mainnet.base.org",
+        block_time=2.0,
+        explorer_url="https://basescan.org",
+    ),
+    "optimism": ChainConfig(
+        name="Optimism",
+        chain_id=10,
+        default_rpc="https://mainnet.optimism.io",
+        block_time=2.0,
+        explorer_url="https://optimistic.etherscan.io",
+    ),
+}
+
+# Token contract addresses per chain
+# Format: TOKENS[chain][symbol] = TokenConfig
+TOKENS: dict[str, dict[str, TokenConfig]] = {
+    "polygon": {
+        "USDC": TokenConfig(
+            symbol="USDC",
+            name="USD Coin",
+            address="0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359",
+            decimals=6,
+        ),
+        "USDT": TokenConfig(
+            symbol="USDT",
+            name="Tether USD",
+            address="0xc2132D05D31c914a87C6611C10748AEb04B58e8F",
+            decimals=6,
+        ),
+        "DAI": TokenConfig(
+            symbol="DAI",
+            name="Dai Stablecoin",
+            address="0x8f3Cf7ad23Cd3CaDbD9735AFf958023239c6A063",
+            decimals=18,
+        ),
+    },
+    "ethereum": {
+        "USDC": TokenConfig(
+            symbol="USDC",
+            name="USD Coin",
+            address="0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
+            decimals=6,
+        ),
+        "USDT": TokenConfig(
+            symbol="USDT",
+            name="Tether USD",
+            address="0xdAC17F958D2ee523a2206206994597C13D831ec7",
+            decimals=6,
+        ),
+        "DAI": TokenConfig(
+            symbol="DAI",
+            name="Dai Stablecoin",
+            address="0x6B175474E89094C44Da98b954EesfdC1D3709CEc",
+            decimals=18,
+        ),
+    },
+    "arbitrum": {
+        "USDC": TokenConfig(
+            symbol="USDC",
+            name="USD Coin",
+            address="0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
+            decimals=6,
+        ),
+        "USDT": TokenConfig(
+            symbol="USDT",
+            name="Tether USD",
+            address="0xFd086bC7CD5C481DCC9C85ebE478A1C0b69FCbb9",
+            decimals=6,
+        ),
+    },
+    "base": {
+        "USDC": TokenConfig(
+            symbol="USDC",
+            name="USD Coin",
+            address="0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
+            decimals=6,
+        ),
+    },
+    "optimism": {
+        "USDC": TokenConfig(
+            symbol="USDC",
+            name="USD Coin",
+            address="0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85",
+            decimals=6,
+        ),
+        "USDT": TokenConfig(
+            symbol="USDT",
+            name="Tether USD",
+            address="0x94b008aA00579c1307B0EF2c499aD98a8ce58e58",
+            decimals=6,
+        ),
+    },
+}
+
+# ERC20 Transfer event signature
+TRANSFER_EVENT_SIGNATURE = "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"
+
+# ERC20 ABI (minimal for transfer events)
+ERC20_ABI = [
+    {
+        "anonymous": False,
+        "inputs": [
+            {"indexed": True, "name": "from", "type": "address"},
+            {"indexed": True, "name": "to", "type": "address"},
+            {"indexed": False, "name": "value", "type": "uint256"},
+        ],
+        "name": "Transfer",
+        "type": "event",
+    },
+    {
+        "inputs": [],
+        "name": "decimals",
+        "outputs": [{"name": "", "type": "uint8"}],
+        "stateMutability": "view",
+        "type": "function",
+    },
+    {
+        "inputs": [],
+        "name": "symbol",
+        "outputs": [{"name": "", "type": "string"}],
+        "stateMutability": "view",
+        "type": "function",
+    },
+]
+
+
+def get_chain_config(chain: str) -> ChainConfig | None:
+    """Get chain configuration by name."""
+    return CHAINS.get(chain.lower())
+
+
+def get_token_config(chain: str, symbol: str) -> TokenConfig | None:
+    """Get token configuration for a chain."""
+    chain_tokens = TOKENS.get(chain.lower(), {})
+    return chain_tokens.get(symbol.upper())
+
+
+def get_supported_chains() -> list[str]:
+    """Get list of supported chain names."""
+    return list(CHAINS.keys())
+
+
+def get_supported_tokens(chain: str) -> list[str]:
+    """Get list of supported tokens for a chain."""
+    return list(TOKENS.get(chain.lower(), {}).keys())

stablepay_verifier/cli.py

@@ -0,0 +1,366 @@
+"""
+CLI interface for StablePay Verifier.
+"""
+
+import json
+import sys
+from typing import Optional
+
+import typer
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+from rich.text import Text
+
+from stablepay_verifier import __version__
+from stablepay_verifier.chains import (
+    CHAINS,
+    TOKENS,
+    get_supported_chains,
+    get_supported_tokens,
+)
+from stablepay_verifier.models import PaymentStatus, VerifyRequest
+from stablepay_verifier.utils import format_address, format_amount, format_timestamp
+from stablepay_verifier.verifier import VerificationError, verify_payment
+
+# Initialize Typer app and Rich console
+app = typer.Typer(
+    name="stablepay",
+    help="🔍 Verify stablecoin payments on-chain. No custody. No fees. Just truth.",
+    no_args_is_help=True,
+    rich_markup_mode="rich",
+)
+console = Console()
+
+# Exit codes
+EXIT_PAID = 0
+EXIT_NOT_PAID = 1
+EXIT_PARTIAL = 2
+EXIT_PENDING = 3
+EXIT_ERROR = 10
+EXIT_RPC_ERROR = 11
+
+
+def version_callback(value: bool) -> None:
+    """Show version and exit."""
+    if value:
+        console.print(f"[bold blue]StablePay Verifier[/bold blue] v{__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def main(
+    version: Optional[bool] = typer.Option(
+        None,
+        "--version",
+        "-V",
+        callback=version_callback,
+        is_eager=True,
+        help="Show version and exit.",
+    ),
+) -> None:
+    """
+    🔍 StablePay Verifier - Verify stablecoin payments on-chain.
+    
+    No custody. No fees. Just truth.
+    """
+    pass
+
+
+@app.command()
+def verify(
+    address: str = typer.Option(
+        ...,
+        "--address",
+        "-a",
+        help="Receiver wallet address (0x...)",
+    ),
+    amount: float = typer.Option(
+        ...,
+        "--amount",
+        "-m",
+        help="Expected payment amount",
+    ),
+    token: str = typer.Option(
+        "USDC",
+        "--token",
+        "-t",
+        help="Token symbol (USDC, USDT, DAI)",
+    ),
+    chain: str = typer.Option(
+        "polygon",
+        "--chain",
+        "-c",
+        help="Blockchain network (polygon, ethereum, arbitrum, base, optimism)",
+    ),
+    rpc: Optional[str] = typer.Option(
+        None,
+        "--rpc",
+        "-r",
+        help="Custom RPC endpoint URL",
+    ),
+    time_window: str = typer.Option(
+        "24h",
+        "--time-window",
+        "-w",
+        help="Time window to search (e.g., 1h, 24h, 7d)",
+    ),
+    sender: Optional[str] = typer.Option(
+        None,
+        "--sender",
+        "-s",
+        help="Filter by sender address",
+    ),
+    min_confirmations: int = typer.Option(
+        12,
+        "--min-confirmations",
+        help="Minimum block confirmations required",
+    ),
+    tolerance: float = typer.Option(
+        0.01,
+        "--tolerance",
+        help="Amount tolerance as decimal (0.01 = 1%%)",
+    ),
+    output_format: str = typer.Option(
+        "text",
+        "--output",
+        "-o",
+        help="Output format: text or json",
+    ),
+    quiet: bool = typer.Option(
+        False,
+        "--quiet",
+        "-q",
+        help="Minimal output (just status)",
+    ),
+    verbose: bool = typer.Option(
+        False,
+        "--verbose",
+        "-v",
+        help="Show debug information",
+    ),
+) -> None:
+    """
+    Verify a stablecoin payment was received.
+    
+    Examples:
+    
+        stablepay verify -a 0x742d35... -m 100
+        
+        stablepay verify -a 0x742d35... -m 50 -t USDT -c ethereum
+        
+        stablepay verify -a 0x742d35... -m 100 --time-window 7d
+    """
+    try:
+        # Create verification request
+        request = VerifyRequest(
+            address=address,
+            amount=amount,
+            token=token,
+            chain=chain,
+            rpc=rpc,
+            sender=sender,
+            time_window=time_window,
+            min_confirmations=min_confirmations,
+            tolerance=tolerance,
+        )
+    except ValueError as e:
+        _handle_error(str(e), "INVALID_INPUT", output_format, quiet)
+        raise typer.Exit(EXIT_ERROR)
+    
+    # Show progress if not quiet
+    if not quiet and output_format == "text":
+        console.print(f"\n[dim]Verifying {token} payment on {chain.title()}...[/dim]")
+    
+    # Perform verification
+    try:
+        result = verify_payment(request)
+    except VerificationError as e:
+        _handle_error(e.message, e.code, output_format, quiet)
+        exit_code = EXIT_RPC_ERROR if e.code == "RPC_ERROR" else EXIT_ERROR
+        raise typer.Exit(exit_code)
+    except Exception as e:
+        _handle_error(f"Unexpected error: {str(e)}", "UNKNOWN_ERROR", output_format, quiet)
+        raise typer.Exit(EXIT_ERROR)
+    
+    # Output results
+    if output_format == "json":
+        _output_json(result)
+    elif quiet:
+        _output_quiet(result)
+    else:
+        _output_rich(result, verbose)
+    
+    # Set exit code based on status
+    exit_code = {
+        PaymentStatus.PAID: EXIT_PAID,
+        PaymentStatus.NOT_PAID: EXIT_NOT_PAID,
+        PaymentStatus.PARTIAL: EXIT_PARTIAL,
+        PaymentStatus.PENDING: EXIT_PENDING,
+    }.get(result.status, EXIT_ERROR)
+    
+    raise typer.Exit(exit_code)
+
+
+@app.command()
+def info() -> None:
+    """
+    Show supported chains and tokens.
+    """
+    console.print("\n[bold blue]Supported Chains & Tokens[/bold blue]\n")
+    
+    for chain_name, chain_config in CHAINS.items():
+        table = Table(title=f"🔗 {chain_config.name} ({chain_name})", show_header=True)
+        table.add_column("Token", style="cyan")
+        table.add_column("Name", style="dim")
+        table.add_column("Contract Address", style="dim")
+        
+        tokens = TOKENS.get(chain_name, {})
+        for symbol, token_config in tokens.items():
+            table.add_row(
+                symbol,
+                token_config.name,
+                format_address(token_config.address, 6),
+            )
+        
+        if not tokens:
+            table.add_row("[dim]No tokens configured[/dim]", "", "")
+        
+        console.print(table)
+        console.print()
+    
+    console.print("[dim]Tip: Use --chain and --token to specify the network and token.[/dim]")
+    console.print("[dim]Default: USDC on Polygon[/dim]\n")
+
+
+def _handle_error(message: str, code: str, output_format: str, quiet: bool) -> None:
+    """Handle and display errors."""
+    if output_format == "json":
+        console.print(json.dumps({
+            "status": "ERROR",
+            "error_code": code,
+            "message": message,
+        }))
+    elif quiet:
+        console.print(f"ERROR: {message}", style="red")
+    else:
+        console.print()
+        console.print(Panel(
+            f"[red bold]Error:[/red bold] {message}\n\n"
+            f"[dim]Error Code: {code}[/dim]",
+            title="❌ Verification Failed",
+            border_style="red",
+        ))
+
+
+def _output_json(result) -> None:
+    """Output result as JSON."""
+    output = {
+        "status": result.status.value,
+        "expected_amount": result.expected_amount,
+        "matched_amount": result.matched_amount,
+        "transaction_hash": result.transaction_hash,
+        "block_number": result.block_number,
+        "timestamp": result.timestamp.isoformat() if result.timestamp else None,
+        "confirmations": result.confirmations,
+        "sender": result.sender,
+        "receiver": result.receiver,
+        "token": result.token,
+        "chain": result.chain,
+        "transfer_count": len(result.transfers),
+    }
+    console.print(json.dumps(output, indent=2))
+
+
+def _output_quiet(result) -> None:
+    """Output minimal status."""
+    console.print(result.status.value)
+
+
+def _output_rich(result, verbose: bool) -> None:
+    """Output rich formatted result."""
+    console.print()
+    
+    # Determine status styling
+    status_styles = {
+        PaymentStatus.PAID: ("✅ PAYMENT VERIFIED", "green"),
+        PaymentStatus.NOT_PAID: ("❌ NOT PAID", "red"),
+        PaymentStatus.PARTIAL: ("⚠️ PARTIAL PAYMENT", "yellow"),
+        PaymentStatus.PENDING: ("⏳ PENDING CONFIRMATION", "yellow"),
+    }
+    
+    status_text, status_color = status_styles.get(
+        result.status, ("❓ UNKNOWN", "dim")
+    )
+    
+    # Build content
+    lines = []
+    lines.append(f"[bold]Status:[/bold]        {result.status.value}")
+    lines.append(
+        f"[bold]Amount:[/bold]        {format_amount(result.matched_amount)} {result.token} "
+        f"[dim](expected: {format_amount(result.expected_amount)})[/dim]"
+    )
+    
+    if result.sender:
+        lines.append(f"[bold]From:[/bold]          {format_address(result.sender)}")
+    lines.append(f"[bold]To:[/bold]            {format_address(result.receiver)}")
+    
+    if result.transaction_hash:
+        lines.append(f"[bold]Transaction:[/bold]   {format_address(result.transaction_hash, 10)}")
+    
+    if result.block_number:
+        lines.append(
+            f"[bold]Block:[/bold]         {result.block_number} "
+            f"[dim]({result.confirmations} confirmations)[/dim]"
+        )
+    
+    if result.timestamp:
+        lines.append(f"[bold]Time:[/bold]          {format_timestamp(result.timestamp)}")
+    
+    # Show chain info
+    lines.append(f"[bold]Network:[/bold]       {result.chain.title()}")
+    
+    content = "\n".join(lines)
+    
+    console.print(Panel(
+        content,
+        title=status_text,
+        border_style=status_color,
+        padding=(1, 2),
+    ))
+    
+    # Verbose: show all transfers
+    if verbose and result.transfers:
+        console.print("\n[bold]All Matching Transfers:[/bold]")
+        table = Table(show_header=True)
+        table.add_column("TX Hash", style="dim")
+        table.add_column("Amount", justify="right")
+        table.add_column("From", style="dim")
+        table.add_column("Block", justify="right")
+        table.add_column("Confirmations", justify="right")
+        
+        for transfer in result.transfers:
+            conf_style = "green" if transfer.confirmations >= 12 else "yellow"
+            table.add_row(
+                format_address(transfer.tx_hash, 8),
+                format_amount(transfer.amount),
+                format_address(transfer.sender),
+                str(transfer.block_number),
+                f"[{conf_style}]{transfer.confirmations}[/{conf_style}]",
+            )
+        
+        console.print(table)
+    
+    # Tips for NOT_PAID status
+    if result.status == PaymentStatus.NOT_PAID:
+        console.print()
+        console.print("[dim]Tips:[/dim]")
+        console.print("[dim]  • Try expanding the time window with --time-window 7d[/dim]")
+        console.print("[dim]  • Verify the wallet address is correct[/dim]")
+        console.print("[dim]  • Check if the payment was sent on the correct chain[/dim]")
+    
+    console.print()
+
+
+if __name__ == "__main__":
+    app()

stablepay_verifier/models.py

@@ -0,0 +1,134 @@
+"""
+Pydantic models for StablePay Verifier.
+"""
+
+from datetime import datetime
+from enum import Enum
+from typing import Optional
+
+from pydantic import BaseModel, Field, field_validator
+
+
+class PaymentStatus(str, Enum):
+    """Payment verification status."""
+    
+    PAID = "PAID"
+    NOT_PAID = "NOT_PAID"
+    PARTIAL = "PARTIAL"
+    PENDING = "PENDING"
+
+
+class ChainConfig(BaseModel):
+    """Configuration for a blockchain network."""
+    
+    name: str
+    chain_id: int
+    default_rpc: str
+    block_time: float = 2.0  # Average block time in seconds
+    explorer_url: str = ""
+
+
+class TokenConfig(BaseModel):
+    """Configuration for a token on a specific chain."""
+    
+    symbol: str
+    name: str
+    address: str
+    decimals: int = 6
+
+
+class Transfer(BaseModel):
+    """Represents a single token transfer event."""
+    
+    tx_hash: str
+    block_number: int
+    sender: str
+    receiver: str
+    amount: float  # Human-readable amount (after decimal conversion)
+    raw_amount: int  # Raw amount in wei/smallest unit
+    timestamp: Optional[datetime] = None
+    confirmations: int = 0
+
+
+class VerifyRequest(BaseModel):
+    """Request parameters for payment verification."""
+    
+    address: str = Field(..., description="Receiver wallet address")
+    amount: float = Field(..., gt=0, description="Expected payment amount")
+    token: str = Field(default="USDC", description="Token symbol")
+    chain: str = Field(default="polygon", description="Blockchain network")
+    rpc: Optional[str] = Field(default=None, description="Custom RPC endpoint")
+    sender: Optional[str] = Field(default=None, description="Filter by sender address")
+    time_window: str = Field(default="24h", description="Time window to search")
+    from_block: Optional[int] = Field(default=None, description="Starting block number")
+    to_block: Optional[int] = Field(default=None, description="Ending block number")
+    min_confirmations: int = Field(default=12, ge=0, description="Minimum confirmations")
+    tolerance: float = Field(default=0.01, ge=0, le=1, description="Amount tolerance (0.01 = 1%)")
+    
+    @field_validator("address", "sender", mode="before")
+    @classmethod
+    def validate_address(cls, v: Optional[str]) -> Optional[str]:
+        """Validate Ethereum address format."""
+        if v is None:
+            return None
+        v = v.strip()
+        if not v.startswith("0x") or len(v) != 42:
+            raise ValueError("Invalid address format. Expected 0x followed by 40 hex characters.")
+        try:
+            int(v, 16)
+        except ValueError:
+            raise ValueError("Invalid address format. Contains non-hexadecimal characters.")
+        return v.lower()
+    
+    @field_validator("chain", mode="before")
+    @classmethod
+    def validate_chain(cls, v: str) -> str:
+        """Normalize chain name."""
+        return v.lower().strip()
+    
+    @field_validator("token", mode="before")
+    @classmethod
+    def validate_token(cls, v: str) -> str:
+        """Normalize token symbol."""
+        return v.upper().strip()
+    
+    @field_validator("time_window", mode="before")
+    @classmethod
+    def validate_time_window(cls, v: str) -> str:
+        """Validate time window format."""
+        v = v.lower().strip()
+        if not any(v.endswith(unit) for unit in ["h", "d", "m"]):
+            raise ValueError("Invalid time window format. Use: 1h, 24h, 7d, 30d")
+        try:
+            int(v[:-1])
+        except ValueError:
+            raise ValueError("Invalid time window format. Number must precede unit.")
+        return v
+
+
+class PaymentResult(BaseModel):
+    """Result of a payment verification."""
+    
+    status: PaymentStatus
+    expected_amount: float
+    matched_amount: float = 0.0
+    transaction_hash: Optional[str] = None
+    block_number: Optional[int] = None
+    timestamp: Optional[datetime] = None
+    confirmations: int = 0
+    sender: Optional[str] = None
+    receiver: str
+    token: str
+    chain: str
+    transfers: list[Transfer] = Field(default_factory=list)
+    error: Optional[str] = None
+    
+    @property
+    def is_paid(self) -> bool:
+        """Check if payment was verified."""
+        return self.status == PaymentStatus.PAID
+    
+    @property
+    def shortfall(self) -> float:
+        """Calculate the remaining amount needed."""
+        return max(0, self.expected_amount - self.matched_amount)