stablepay-verifier 0.1.0__tar.gz

stablepay_verifier-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Okediya
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

stablepay_verifier-0.1.0/PKG-INFO

@@ -0,0 +1,300 @@
+Metadata-Version: 2.4
+Name: stablepay-verifier
+Version: 0.1.0
+Summary: Verify stablecoin payments on-chain. No custody. No fees. Just truth.
+License-Expression: MIT
+License-File: LICENSE
+Keywords: stablecoin,crypto,payment,verification,blockchain,usdc,polygon
+Author: Okediya
+Author-email: ayobamioluwaseunfunmiokediya@gmail.com
+Requires-Python: >=3.10
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Office/Business :: Financial
+Provides-Extra: dev
+Requires-Dist: httpx (>=0.25.0)
+Requires-Dist: mypy (>=1.0.0) ; extra == "dev"
+Requires-Dist: pre-commit (>=3.0.0) ; extra == "dev"
+Requires-Dist: pydantic (>=2.0.0)
+Requires-Dist: pydantic-settings (>=2.0.0)
+Requires-Dist: pytest (>=7.0.0) ; extra == "dev"
+Requires-Dist: pytest-asyncio (>=0.21.0) ; extra == "dev"
+Requires-Dist: pytest-cov (>=4.0.0) ; extra == "dev"
+Requires-Dist: rich (>=13.0.0)
+Requires-Dist: ruff (>=0.1.0) ; extra == "dev"
+Requires-Dist: typer (>=0.9.0)
+Requires-Dist: web3 (>=6.0.0)
+Description-Content-Type: text/markdown
+
+# 🔍 StablePay Verifier
+
+> Verify stablecoin payments on-chain. No custody. No fees. Just truth.
+
+[![PyPI](https://img.shields.io/pypi/v/stablepay-verifier)](https://pypi.org/project/stablepay-verifier/)
+[![License](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+[![Python](https://img.shields.io/badge/python-3.10+-blue)](https://python.org)
+
+## Why StablePay?
+
+✅ **Read-only** - Never touches your funds  
+✅ **Open-source** - Audit every line of code  
+✅ **BYO-RPC** - Use your own node for privacy  
+✅ **Global** - Works anywhere with internet  
+✅ **Simple** - PAID or NOT PAID, that's it  
+
+## Quick Start
+
+```bash
+# Install
+pip install stablepay-verifier
+
+# Verify a payment
+stablepay verify -a 0x742d35... -m 100
+
+# Output
+✅ PAYMENT VERIFIED
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  Status:        PAID
+  Amount:        100.00 USDC
+  Transaction:   0x1234...abcd
+  Block:         52345678 (150 confirmations)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+## Installation
+
+### From PyPI (Recommended)
+
+```bash
+pip install stablepay-verifier
+```
+
+### From Source
+
+```bash
+git clone https://github.com/yourusername/stablepay-verifier.git
+cd stablepay-verifier
+pip install -e .
+```
+
+### With Poetry
+
+```bash
+git clone https://github.com/yourusername/stablepay-verifier.git
+cd stablepay-verifier
+poetry install
+```
+
+## Usage
+
+### Basic Verification
+
+```bash
+# Verify 100 USDC payment on Polygon (default)
+stablepay verify --address 0x742d35cc6634c0532925a3b844bc9e7595f3a382 --amount 100
+
+# Short form
+stablepay verify -a 0x742d35... -m 100
+```
+
+### Different Tokens & Chains
+
+```bash
+# USDT on Ethereum
+stablepay verify -a 0x... -m 50 --token USDT --chain ethereum
+
+# DAI on Arbitrum
+stablepay verify -a 0x... -m 1000 -t DAI -c arbitrum
+```
+
+### Time Window
+
+```bash
+# Search last 7 days
+stablepay verify -a 0x... -m 100 --time-window 7d
+
+# Search last 1 hour
+stablepay verify -a 0x... -m 100 -w 1h
+```
+
+### Custom RPC (BYO-RPC)
+
+```bash
+# Use your own RPC endpoint for privacy/reliability
+stablepay verify -a 0x... -m 100 --rpc https://your-rpc-endpoint.com
+```
+
+### JSON Output (for scripts)
+
+```bash
+# Get JSON output
+stablepay verify -a 0x... -m 100 --output json
+
+# Use with jq
+stablepay verify -a 0x... -m 100 -o json | jq '.status'
+```
+
+### Filter by Sender
+
+```bash
+# Only count payments from a specific address
+stablepay verify -a 0x... -m 100 --sender 0xabc123...
+```
+
+## Supported Chains & Tokens
+
+| Chain | USDC | USDT | DAI |
+|-------|:----:|:----:|:---:|
+| Polygon | ✅ | ✅ | ✅ |
+| Ethereum | ✅ | ✅ | ✅ |
+| Arbitrum | ✅ | ✅ | ❌ |
+| Base | ✅ | ❌ | ❌ |
+| Optimism | ✅ | ✅ | ❌ |
+
+Run `stablepay info` to see all supported chains and tokens.
+
+## Exit Codes
+
+| Code | Status | Meaning |
+|------|--------|---------|
+| 0 | PAID | Payment verified |
+| 1 | NOT_PAID | No matching payment |
+| 2 | PARTIAL | Partial payment |
+| 3 | PENDING | Awaiting confirmations |
+| 10 | ERROR | Invalid input |
+| 11 | RPC_ERROR | Network error |
+
+Use exit codes in scripts:
+
+```bash
+stablepay verify -a 0x... -m 100 -q && echo "Payment received!"
+```
+
+## Configuration
+
+### Command Line Options
+
+| Flag | Short | Default | Description |
+|------|-------|---------|-------------|
+| `--address` | `-a` | Required | Receiver wallet address |
+| `--amount` | `-m` | Required | Expected payment amount |
+| `--token` | `-t` | USDC | Token symbol |
+| `--chain` | `-c` | polygon | Blockchain network |
+| `--rpc` | `-r` | Auto | Custom RPC endpoint |
+| `--time-window` | `-w` | 24h | Search time window |
+| `--sender` | `-s` | Any | Filter by sender |
+| `--min-confirmations` | | 12 | Required confirmations |
+| `--tolerance` | | 0.01 | Amount tolerance (1%) |
+| `--output` | `-o` | text | Output format |
+| `--quiet` | `-q` | | Minimal output |
+| `--verbose` | `-v` | | Debug info |
+
+## Use Cases
+
+### Freelancers
+Verify client payments before delivering work:
+```bash
+stablepay verify -a $MY_WALLET -m 500 -w 24h
+```
+
+### E-commerce Integration
+Check payments in your backend:
+```python
+from stablepay_verifier import verify_payment, VerifyRequest
+
+result = verify_payment(VerifyRequest(
+    address="0x...",
+    amount=99.99,
+    token="USDC",
+    chain="polygon",
+))
+
+if result.is_paid:
+    process_order()
+```
+
+### Automated Systems
+Use in CI/CD or cron jobs:
+```bash
+#!/bin/bash
+if stablepay verify -a $WALLET -m $AMOUNT -q; then
+    echo "Payment confirmed, proceeding..."
+    ./next_step.sh
+else
+    echo "Payment not found"
+    exit 1
+fi
+```
+
+## BYO-RPC Model
+
+Public RPCs have rate limits and privacy concerns. For production use, we recommend using your own RPC endpoint:
+
+- [Alchemy](https://www.alchemy.com/) - Free tier available
+- [Infura](https://infura.io/) - Free tier available
+- [QuickNode](https://www.quicknode.com/) - Free tier available
+- Self-hosted node
+
+```bash
+stablepay verify -a 0x... -m 100 --rpc https://polygon-mainnet.g.alchemy.com/v2/YOUR_KEY
+```
+
+## Development
+
+### Setup
+
+```bash
+git clone https://github.com/yourusername/stablepay-verifier.git
+cd stablepay-verifier
+poetry install --with dev
+```
+
+### Run Tests
+
+```bash
+poetry run pytest
+```
+
+### Lint & Format
+
+```bash
+poetry run ruff check .
+poetry run ruff format .
+```
+
+### Type Check
+
+```bash
+poetry run mypy src
+```
+
+## Contributing
+
+Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Run tests and linting
+5. Submit a pull request
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.
+
+## Security
+
+This tool is **read-only** and never requests private keys or signing capabilities. It only queries public blockchain data.
+
+If you find a security issue, please report it privately to security@example.com.
+
+---
+
+**Built with ❤️ for the global stablecoin community**
+

stablepay_verifier-0.1.0/README.md

@@ -0,0 +1,265 @@
+# 🔍 StablePay Verifier
+
+> Verify stablecoin payments on-chain. No custody. No fees. Just truth.
+
+[![PyPI](https://img.shields.io/pypi/v/stablepay-verifier)](https://pypi.org/project/stablepay-verifier/)
+[![License](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+[![Python](https://img.shields.io/badge/python-3.10+-blue)](https://python.org)
+
+## Why StablePay?
+
+✅ **Read-only** - Never touches your funds  
+✅ **Open-source** - Audit every line of code  
+✅ **BYO-RPC** - Use your own node for privacy  
+✅ **Global** - Works anywhere with internet  
+✅ **Simple** - PAID or NOT PAID, that's it  
+
+## Quick Start
+
+```bash
+# Install
+pip install stablepay-verifier
+
+# Verify a payment
+stablepay verify -a 0x742d35... -m 100
+
+# Output
+✅ PAYMENT VERIFIED
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  Status:        PAID
+  Amount:        100.00 USDC
+  Transaction:   0x1234...abcd
+  Block:         52345678 (150 confirmations)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+## Installation
+
+### From PyPI (Recommended)
+
+```bash
+pip install stablepay-verifier
+```
+
+### From Source
+
+```bash
+git clone https://github.com/yourusername/stablepay-verifier.git
+cd stablepay-verifier
+pip install -e .
+```
+
+### With Poetry
+
+```bash
+git clone https://github.com/yourusername/stablepay-verifier.git
+cd stablepay-verifier
+poetry install
+```
+
+## Usage
+
+### Basic Verification
+
+```bash
+# Verify 100 USDC payment on Polygon (default)
+stablepay verify --address 0x742d35cc6634c0532925a3b844bc9e7595f3a382 --amount 100
+
+# Short form
+stablepay verify -a 0x742d35... -m 100
+```
+
+### Different Tokens & Chains
+
+```bash
+# USDT on Ethereum
+stablepay verify -a 0x... -m 50 --token USDT --chain ethereum
+
+# DAI on Arbitrum
+stablepay verify -a 0x... -m 1000 -t DAI -c arbitrum
+```
+
+### Time Window
+
+```bash
+# Search last 7 days
+stablepay verify -a 0x... -m 100 --time-window 7d
+
+# Search last 1 hour
+stablepay verify -a 0x... -m 100 -w 1h
+```
+
+### Custom RPC (BYO-RPC)
+
+```bash
+# Use your own RPC endpoint for privacy/reliability
+stablepay verify -a 0x... -m 100 --rpc https://your-rpc-endpoint.com
+```
+
+### JSON Output (for scripts)
+
+```bash
+# Get JSON output
+stablepay verify -a 0x... -m 100 --output json
+
+# Use with jq
+stablepay verify -a 0x... -m 100 -o json | jq '.status'
+```
+
+### Filter by Sender
+
+```bash
+# Only count payments from a specific address
+stablepay verify -a 0x... -m 100 --sender 0xabc123...
+```
+
+## Supported Chains & Tokens
+
+| Chain | USDC | USDT | DAI |
+|-------|:----:|:----:|:---:|
+| Polygon | ✅ | ✅ | ✅ |
+| Ethereum | ✅ | ✅ | ✅ |
+| Arbitrum | ✅ | ✅ | ❌ |
+| Base | ✅ | ❌ | ❌ |
+| Optimism | ✅ | ✅ | ❌ |
+
+Run `stablepay info` to see all supported chains and tokens.
+
+## Exit Codes
+
+| Code | Status | Meaning |
+|------|--------|---------|
+| 0 | PAID | Payment verified |
+| 1 | NOT_PAID | No matching payment |
+| 2 | PARTIAL | Partial payment |
+| 3 | PENDING | Awaiting confirmations |
+| 10 | ERROR | Invalid input |
+| 11 | RPC_ERROR | Network error |
+
+Use exit codes in scripts:
+
+```bash
+stablepay verify -a 0x... -m 100 -q && echo "Payment received!"
+```
+
+## Configuration
+
+### Command Line Options
+
+| Flag | Short | Default | Description |
+|------|-------|---------|-------------|
+| `--address` | `-a` | Required | Receiver wallet address |
+| `--amount` | `-m` | Required | Expected payment amount |
+| `--token` | `-t` | USDC | Token symbol |
+| `--chain` | `-c` | polygon | Blockchain network |
+| `--rpc` | `-r` | Auto | Custom RPC endpoint |
+| `--time-window` | `-w` | 24h | Search time window |
+| `--sender` | `-s` | Any | Filter by sender |
+| `--min-confirmations` | | 12 | Required confirmations |
+| `--tolerance` | | 0.01 | Amount tolerance (1%) |
+| `--output` | `-o` | text | Output format |
+| `--quiet` | `-q` | | Minimal output |
+| `--verbose` | `-v` | | Debug info |
+
+## Use Cases
+
+### Freelancers
+Verify client payments before delivering work:
+```bash
+stablepay verify -a $MY_WALLET -m 500 -w 24h
+```
+
+### E-commerce Integration
+Check payments in your backend:
+```python
+from stablepay_verifier import verify_payment, VerifyRequest
+
+result = verify_payment(VerifyRequest(
+    address="0x...",
+    amount=99.99,
+    token="USDC",
+    chain="polygon",
+))
+
+if result.is_paid:
+    process_order()
+```
+
+### Automated Systems
+Use in CI/CD or cron jobs:
+```bash
+#!/bin/bash
+if stablepay verify -a $WALLET -m $AMOUNT -q; then
+    echo "Payment confirmed, proceeding..."
+    ./next_step.sh
+else
+    echo "Payment not found"
+    exit 1
+fi
+```
+
+## BYO-RPC Model
+
+Public RPCs have rate limits and privacy concerns. For production use, we recommend using your own RPC endpoint:
+
+- [Alchemy](https://www.alchemy.com/) - Free tier available
+- [Infura](https://infura.io/) - Free tier available
+- [QuickNode](https://www.quicknode.com/) - Free tier available
+- Self-hosted node
+
+```bash
+stablepay verify -a 0x... -m 100 --rpc https://polygon-mainnet.g.alchemy.com/v2/YOUR_KEY
+```
+
+## Development
+
+### Setup
+
+```bash
+git clone https://github.com/yourusername/stablepay-verifier.git
+cd stablepay-verifier
+poetry install --with dev
+```
+
+### Run Tests
+
+```bash
+poetry run pytest
+```
+
+### Lint & Format
+
+```bash
+poetry run ruff check .
+poetry run ruff format .
+```
+
+### Type Check
+
+```bash
+poetry run mypy src
+```
+
+## Contributing
+
+Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Run tests and linting
+5. Submit a pull request
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.
+
+## Security
+
+This tool is **read-only** and never requests private keys or signing capabilities. It only queries public blockchain data.
+
+If you find a security issue, please report it privately to security@example.com.
+
+---
+
+**Built with ❤️ for the global stablecoin community**

stablepay_verifier-0.1.0/pyproject.toml

@@ -0,0 +1,66 @@
+[project]
+name = "stablepay-verifier"
+version = "0.1.0"
+description = "Verify stablecoin payments on-chain. No custody. No fees. Just truth."
+authors = [
+    {name = "Okediya", email = "ayobamioluwaseunfunmiokediya@gmail.com"}
+]
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+keywords = ["stablecoin", "crypto", "payment", "verification", "blockchain", "usdc", "polygon"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Office/Business :: Financial",
+]
+dependencies = [
+    "web3>=6.0.0",
+    "typer>=0.9.0",
+    "rich>=13.0.0",
+    "httpx>=0.25.0",
+    "pydantic>=2.0.0",
+    "pydantic-settings>=2.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "pytest-asyncio>=0.21.0",
+    "pytest-cov>=4.0.0",
+    "ruff>=0.1.0",
+    "mypy>=1.0.0",
+    "pre-commit>=3.0.0",
+]
+
+[project.scripts]
+stablepay = "stablepay_verifier.cli:app"
+
+[tool.poetry]
+packages = [{include = "stablepay_verifier", from = "src"}]
+
+[build-system]
+requires = ["poetry-core>=2.0.0,<3.0.0"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "W", "UP"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+

stablepay_verifier-0.1.0/src/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-0.1.0/src/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()