payra-sdk 1.2.4__py3-none-any.whl → 1.2.6__py3-none-any.whl

payra_sdk/order_verification.py

@@ -25,78 +25,107 @@ class PayraOrderVerification:
             raise ConnectionError(f"Failed to connect to QuickNode RPC for {self.network}")
 
         self.merchant_id = os.getenv(f"PAYRA_{self.network}_MERCHANT_ID")
-        self.forward_address = os.getenv(f"PAYRA_{self.network}_CORE_FORWARD_CONTRACT_ADDRESS")
+        self.gateway_address = os.getenv(f"PAYRA_{self.network}_OCP_GATEWAY_CONTRACT_ADDRESS")
 
         if not self.merchant_id:
             raise InvalidArgumentError(f"Missing PAYRA_{self.network}_MERCHANT_ID in .env")
-        if not self.forward_address:
-            raise InvalidArgumentError(f"Missing PAYRA_{self.network}_CORE_FORWARD_CONTRACT_ADDRESS in .env")
+        if not self.gateway_address:
+            raise InvalidArgumentError(f"Missing PAYRA_{self.network}_OCP_GATEWAY_CONTRACT_ADDRESS in .env")
 
         # Load ABI
         abi_path = os.path.join(os.path.dirname(__file__), "contracts", "payraABI.json")
         with open(abi_path, "r") as f:
             self.abi = json.load(f)
 
-        # find ABI parts
-        self.core_fn = PayraUtils.find_function(self.abi, "isOrderPaid")
-        self.forward_fn = PayraUtils.find_function(self.abi, "forward")
+        self.user_data_contract = self.get_user_data_contract()
 
-        # prepare forward contract
-        self.forward_contract = self.web3.eth.contract(
-            address=self.web3.to_checksum_address(self.forward_address),
-            abi=[self.forward_fn]
-        )
-
-    def get_rpc_url(self, network: str) -> str:
+    def get_user_data_contract(self):
         """
-        Collects all PAYRA_{NETWORK}_RPC_URL_i variables and randomly picks one.
+        Internal helper to initialize Payra contracts.
+        It fetches the UserData contract address from the Gateway registry.
         """
-        urls = []
-        i = 1
-        while True:
-            env_key = f"PAYRA_{network}_RPC_URL_{i}"
-            value = os.getenv(env_key)
-            if not value:
-                break
-            urls.append(value.strip())
-            i += 1
-
-        if not urls:
-            raise InvalidArgumentError(f"No RPC URLs found for network: {network}")
-
-        return random.choice(urls)
+        # Initialize Gateway Contract
+        gateway_contract = self.web3.eth.contract(address=self.gateway_address, abi=self.abi)
+        
+        # getRegistryDetails
+        _, _, user_data_address, _ = gateway_contract.functions.getRegistryDetails().call()
+        
+        # Return the actual contract responsible for order data
+        return self.web3.eth.contract(address=user_data_address, abi=self.abi)
 
     def is_order_paid(self, order_id: str) -> dict:
         """
-        Calls the Payra Forward contract to check if an order is paid.
+        Verify if an order is paid on Payra contract.
         """
         try:
-            # encode isOrderPaid call manually
-            core_fn_selector = PayraUtils.function_selector(self.core_fn)
-            encoded_params = self.web3.codec.encode(
-                [inp["type"] for inp in self.core_fn["inputs"]],
-                [int(self.merchant_id), order_id]
-            )
-            data = core_fn_selector + encoded_params.hex()
-
-            # call forward()
-            result = self.forward_contract.functions.forward("0x" + data).call()
-
-            # decode result
-            decoded = self.web3.codec.decode(
-                [out["type"] for out in self.core_fn["outputs"]],
-                result
-            )
+            # Using the resolved user_data_contract
+            is_paid = self.user_data_contract.functions.isOrderPaid(
+                int(self.merchant_id), 
+                order_id
+            ).call()
 
             return {
                 "success": True,
-                "paid": bool(decoded[0]),
+                "paid": bool(is_paid),
                 "error": None
             }
-
         except Exception as e:
             return {
                 "success": False,
                 "paid": None,
                 "error": str(e)
             }
+
+    def get_order_status(self, order_id: str) -> dict:
+        """
+        Detailed status of an order from Payra smart contract.
+        Equivalent to getOrderDetails in Node.js version.
+        """
+        try:
+            # Calls getOrderDetails
+            order = self.user_data_contract.functions.getOrderDetails(
+                int(self.merchant_id), 
+                order_id
+            ).call()
+
+            # Mapping the returned tuple/struct to a dictionary
+            # Order struct: [paid, token, amount, fee, timestamp]
+            return {
+                "success": True,
+                "error": None,
+                "paid": bool(order[0]),
+                "token": order[1],
+                "amount": int(order[2]),
+                "fee": int(order[3]),
+                "timestamp": int(order[4]),
+            }
+        except Exception as e:
+            return {
+                "success": False,
+                "error": str(e),
+                "paid": None,
+                "token": None,
+                "amount": None,
+                "fee": None,
+                "timestamp": None,
+            }
+            
+    def get_rpc_url(self, network: str) -> str:
+        """
+        Collects all PAYRA_{NETWORK}_RPC_URL_i variables and randomly picks one.
+        """
+
+        urls = []
+        i = 1
+        while True:
+            env_key = f"PAYRA_{network}_RPC_URL_{i}"
+            value = os.getenv(env_key)
+            if not value:
+                break
+            urls.append(value.strip())
+            i += 1
+
+        if not urls:
+            raise InvalidArgumentError(f"No RPC URLs found for network: {network}")
+
+        return random.choice(urls)

payra_sdk/signature.py

@@ -187,20 +187,20 @@ class PayraSignatureGenerator:
     # get network env
     def get_credentials_for_network(self, network: str) -> tuple[str, int]:
         """
-        Returns (private_key, merchant_id) for the given network using dynamic env keys like:
-        PAYRA_POLYGON_PRIVATE_KEY, PAYRA_POLYGON_MERCHANT_ID
+        Returns (signature_key, merchant_id) for the given network using dynamic env keys like:
+        PAYRA_POLYGON_SIGNATURE_KEY, PAYRA_POLYGON_MERCHANT_ID
         """
 
-        private_key = os.getenv(f"PAYRA_{network.upper()}_PRIVATE_KEY")
+        signature_key = os.getenv(f"PAYRA_{network.upper()}_SIGNATURE_KEY")
         merchant_id = os.getenv(f"PAYRA_{network.upper()}_MERCHANT_ID")
 
-        if not private_key or not merchant_id:
-            raise ValueError(f"Missing credentials for network '{network}' in .env (checked {private_key_key}, {merchant_id_key})")
+        if not signature_key or not merchant_id:
+            raise ValueError(f"Missing credentials for network '{network}' in .env (checked {signature_key}, {merchant_id_key})")
 
-        return private_key, int(merchant_id)
+        return signature_key, int(merchant_id)
 
     def get_account_address(self, network: str) -> str:
-        private_key, merchant_id = self.get_credentials_for_network(network)
-        account = Account.from_key(private_key)
+        signature_key, merchant_id = self.get_credentials_for_network(network)
+        account = Account.from_key(signature_key)
 
         return account.address

payra_sdk/utils.py

@@ -18,24 +18,6 @@ class PayraUtils:
     _cache_dir = Path.home() / ".payra_cache"
     _cache_file = _cache_dir / "payra_cash_exchange_rate_cache.json"
 
-    @staticmethod
-    def find_function(abi: list[Dict[str, Any]], name: str) -> Dict[str, Any]:
-        """
-        Finds a function definition by name in the given ABI.
-        """
-        for entry in abi:
-            if entry.get("type") == "function" and entry.get("name") == name:
-                return entry
-        raise InvalidArgumentError(f"Function {name} not found in ABI!")
-
-    @staticmethod
-    def function_selector(fn: Dict[str, Any]) -> str:
-        """
-        Generates the function selector (first 4 bytes of keccak of signature).
-        """
-        signature = f"{fn['name']}({','.join([inp['type'] for inp in fn['inputs']])})"
-        return Web3.keccak(text=signature)[:4].hex()
-
     # === Conversion Helpers ===
     @staticmethod
     def to_wei(amount: Union[int, float, str], chain: str, token: str) -> int:

payra_sdk-1.2.6.dist-info/METADATA

@@ -0,0 +1,410 @@
+Metadata-Version: 2.4
+Name: payra_sdk
+Version: 1.2.6
+Summary: Python SDK for Payra payment signature generation (backend)
+Author: Your Name
+Author-email: Wraith <support@payra.cash>
+License: MIT License
+        
+        Copyright (c) 2025 Wraith
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy...
+        
+Project-URL: Homepage, https://github.com/payracash
+Project-URL: Source, https://github.com/payracash/payra-sdk-python
+Project-URL: Issues, https://github.com/payracash/payra-sdk-python/issues
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: web3>=6.0.0
+Requires-Dist: eth-abi>=4.0.0
+Requires-Dist: eth-account>=0.10.0
+Requires-Dist: python-dotenv>=1.0.0
+Dynamic: license-file
+
+# Payra Python SDK
+
+Official **Python SDK** for integrating **Payra's on-chain payment system** into your backend applications.
+
+This SDK provides:
+- Secure generation of **ECDSA signatures** compatible with the Payra smart contract, used for order payment verification.
+- Simple methods for **checking the on-chain status of orders** to confirm completed payments.
+
+
+## How It Works
+
+The typical flow for signing and verifying a Payra transaction:
+1. The **frontend** prepares all required payment parameters:
+-  **Network** – blockchain name (e.g. Polygon, Linea)
+-  **Token address** – ERC-20 token contract address
+-  **Order ID** – unique order identifier
+-  **Amount WEI** – already converted to the smallest unit (e.g. wei, 10⁶)
+-  **Timestamp** – Unix timestamp of the order
+-  **Payer wallet address** – the wallet address from which the user will make the on-chain payment
+2. The frontend sends these parameters to your **backend**.
+3. The **backend** uses this SDK to generate a cryptographic **ECDSA signature** with its signature key (performed **offline**).
+4. The backend returns the generated signature to the frontend.
+5. The **frontend** calls the Payra smart contract (`payOrder`) with all parameters **plus** the signature.
+
+This process ensures full compatibility between your backend and Payra’s on-chain verification logic.
+
+
+## Features
+
+- Generates **Ethereum ECDSA signatures** using the `secp256k1` curve.
+- Fully compatible with **Payra's Solidity smart contracts** (`ERC-1155` payment verification).
+- Supports `.env` and `config/payra.php` configuration for multiple blockchain networks.
+- Laravel IoC container integration (easy dependency injection)
+- Verifies **order payment status directly on-chain** via RPC or blockchain explorer API.
+- Provides **secure backend integration** for signing and verifying transactions.
+- Includes optional utility helpers for:
+-  **Currency conversion** (via [ExchangeRate API](https://www.exchangerate-api.com/))
+-  **USD ⇄ WEI** conversion for token precision handling.
+
+
+## Setup
+
+Before installing this package, make sure you have an active **Payra** account:
+
+[https://payra.cash/products/on-chain-payments/registration](https://payra.cash/products/on-chain-payments/registration#registration-form)
+
+Before installing this package, make sure you have a **MerchantID**
+ 
+- Your **Merchant ID** (unique for each blockchain network)
+- Your **Signature Key** (used to sign Payra transactions securely)
+
+Additionally:
+To obtain your **RPC URLs** which are required for reading on-chain order statuses directly from the blockchain, you can use the public free endpoints provided with this package or create an account on one of the following services for better performance and reliability:
+
+-   **QuickNode** – Extremely fast and excellent for Polygon/Mainnet. ([quicknode.com](https://quicknode.com/))
+    
+-   **Alchemy** – Offers a great developer dashboard and high reliability. ([alchemy.com](https://alchemy.com/))
+    
+-   **DRPC** – Decentralized RPC with a generous free tier and a strict no-log policy. ([drpc.org](https://drpc.org))
+    
+-   **Infura** – The industry standard; very stable, especially for Ethereum. ([infura.io](https://infura.io))
+
+Optional (recommended):
+- Create a free API key at [ExchangeRate API](https://www.exchangerate-api.com/) to enable **automatic fiat → USD conversions** using the built-in utility helpers.
+
+
+## Installation
+
+### From PyPI
+
+Install the latest stable version from [PyPI](https://pypi.org/project/payra-sdk/):
+
+```bash
+pip  install  payra-sdk
+```
+
+### From Source (for development)
+Clone and install locally (editable mode for development):
+ 
+```bash
+git clone https://github.com/payracash/payra-sdk-python.git
+cd payra-sdk-python
+python3 -m venv venv
+source venv/bin/activate  # Windows: venv\Scripts\activate
+pip install -e .
+```
+
+### Dependencies
+
+This SDK requires:
+-  **Python 3.8+**
+-  **web3.py**
+-  **ecdsa**
+-  **python-dotenv**
+-  _(optional)_  `requests` and `exchange-rate-api` for fiat conversion utilities.
+
+
+## Environment Configuration
+
+Create a `.env` file in your project root (you can copy from example):
+
+```bash
+cp  .env.example  .env
+```
+
+This file stores your **private configuration** and connection settings for all supported networks. Never commit `.env` to version control.
+
+
+### Required Variables
+
+#### Exchange Rate (optional)
+
+Used for automatic fiat → USD conversions via the built-in Payra utilities.
+
+```bash
+# Optional only needed if you want to use the built-in currency conversion helper
+PAYRA_EXCHANGE_RATE_API_KEY= # Your ExchangeRate API key (from exchangerate-api.com)
+PAYRA_EXCHANGE_RATE_CACHE_TIME=720  # Cache duration in minutes (default: 720 = 12h)
+
+PAYRA_POLYGON_OCP_GATEWAY_CONTRACT_ADDRESS=0xc56c55D9cF0FF05c85A2DF5BFB9a65b34804063b
+PAYRA_POLYGON_SIGNATURE_KEY=
+PAYRA_POLYGON_MERCHANT_ID=
+PAYRA_POLYGON_RPC_URL_1=https://polygon-rpc.com
+PAYRA_POLYGON_RPC_URL_2=
+
+PAYRA_ETHEREUM_OCP_GATEWAY_CONTRACT_ADDRESS=
+PAYRA_ETHEREUM_SIGNATURE_KEY=
+PAYRA_ETHEREUM_MERCHANT_ID=
+PAYRA_ETHEREUM_RPC_URL_1=
+PAYRA_ETHEREUM_RPC_URL_2=
+
+PAYRA_LINEA_OCP_GATEWAY_CONTRACT_ADDRESS=
+PAYRA_LINEA_SIGNATURE_KEY=
+PAYRA_LINEA_MERCHANT_ID=
+PAYRA_LINEA_RPC_URL_1=
+PAYRA_LINEA_RPC_URL_2=
+```
+
+#### Important Notes
+
+- The cache automatically refreshes when it expires.
+- You can adjust the cache duration by setting `PAYRA_EXCHANGE_RATE_CACHE_TIME`:
+-  `5` → cache for 5 minutes
+-  `60` → cache for 1 hour
+-  `720` → cache for 12 hours (default)
+- Each network (Polygon, Ethereum, Linea) has its own **merchant ID**, **signature key**, and **RPC URLs**.
+- The SDK automatically detects which chain configuration to use based on the selected network.
+- You can use multiple RPC URLs for redundancy (the SDK will automatically fall back if one fails).
+- Contract addresses correspond to the deployed Payra Core Forward contracts per network.
+
+
+## Usage Example
+
+### Generating and verifying a Payra signature in your backend
+
+```python
+from payra_sdk import PayraUtils, PayraSignatureGenerator, PayraSDKException
+
+try:
+	# Convert amount to smallest unit (wei or token decimals
+	amount_wei = PayraUtils.to_wei(3.34, 'polygon', 'usdt')
+	
+	PAYMENT_DATA = {
+		"network": "polygon",
+		"tokenAddress": "0xc2132D05D31c914a87C6611C10748AEb04B58e8F", # USDT on Polygon
+		"orderId": "ORDER-1753824905006-301-322",
+		"amountWei": amount_wei, # e.g. 3.34 USDT in smallest unit
+		"timestamp": 1753826059, # current Unix timestamp
+		"payerAddress": "0xe6c961D6ad9a27Ea8e5d99e40abaC365DE9Cc162"
+	}
+	
+	# Initialize signer
+	payra_signer = PayraSignatureGenerator()
+	
+	# Generate cryptographic signature
+	signature = payra_signer.generate_signature(
+		network=PAYMENT_DATA["network"],
+		token_address=PAYMENT_DATA["tokenAddress"],
+		order_id=PAYMENT_DATA["orderId"],
+		amount_wei=PAYMENT_DATA["amountWei"],
+		timestamp=PAYMENT_DATA["timestamp"],
+		payer_address=PAYMENT_DATA["payerAddress"]
+	)
+	
+	print(f"Generated signature: {signature}")
+except PayraSDKException as e:
+	print(f"Payra SDK error: {e}")
+except  Exception  as e:
+	print(f"Unexpected error: {e}")
+```
+
+#### Input Parameters
+
+| Field | Type | Description |
+|--------------|----------|----------------------------------------------|
+| **`network`** | `string` | Selected network name |
+| **`tokenAddress`** | `string` | ERC20 token contract address |
+| **`orderId`** | `string` | Unique order reference (e.g. ORDER-123) |
+| **`amountWei`** | `string` or `integer` | Token amount in smallest unit (e.g. wei) |
+| **`timestamp`** | `number` | Unix timestamp of signature creation |
+| **`payerAddress`** | `string` | Payer Wallet Address
+
+#### Behind the Scenes
+
+1. The backend converts the amount to the smallest blockchain unit (e.g. wei).
+2. A `PayraSignatureGenerator` instance is created using your signature key from `.env`
+3. It generates an ECDSA signature that is fully verifiable on-chain by the Payra smart contract.
+4. The resulting signature should be sent to the **frontend**, which must call `payOrder(...)` using the same parameters (`timestamp`, `orderId`, `amount`, `tokenAddress`, etc.) that were used to generate the signature.
+
+---
+
+### Get Order Status
+
+Retrieve **full payment details** for a specific order from the Payra smart contract. This method returns the complete on-chain payment data associated with the order, including:
+- whether the order has been paid,
+- the payment token address,
+- the paid amount,
+- the fee amount,
+- and the payment timestamp.
+
+Use this method when you need **detailed information** about the payment or want to display full transaction data.
+
+```python
+from payra_sdk import PayraOrderVerification, PayraSDKException
+
+try:
+	ORDER_ID = "ord-258"
+	# Initialize verifier for a specific network
+	verifier = PayraOrderVerification("polygon")
+	
+	print("\nGet order status...")
+	result = verifier.get_order_status(ORDER_ID)
+	
+	print("Order ID:", ORDER_ID)
+	print("Result:", result)
+	
+except PayraSDKException as e:
+	print(f"Payra SDK error: {e}")
+except  Exception  as e:
+	print(f"Unexpected error: {e}")
+```
+
+#### Behind the Scenes
+
+1. The backend initializes a `PayraOrderVerification` object for the desired blockchain network.
+2. It calls `get_order_status(order_id)` to check if the order transaction exists and is confirmed on-chain.
+3. The function returns a dictionary with:
+
+```python
+{
+	"success": True,
+	"paid": True,
+	"error": None.
+	"toke": '0xc2132d05d31c914a87c6611c10748aeb04b58e8f',
+	"amount": 400000,
+	"fee": 3600,
+	"timestamp": 1765138941
+}
+```
+
+---
+
+### Check Order Paid Status
+
+Perform a **simple payment check** for a specific order. This method only verifies whether the order has been paid (`true` or `false`) and does **not** return any additional payment details.
+
+Use this method when you only need a **quick boolean confirmation** of the payment status.
+
+```python
+from payra_sdk import PayraOrderVerification, PayraSDKException
+
+try:
+	ORDER_ID = "ord-258"
+
+	# Initialize verifier for a specific network
+	verifier = PayraOrderVerification("polygon")
+
+	print("\nChecking order status...")
+	result = verifier.is_order_paid(ORDER_ID)
+
+	print("Order ID:", ORDER_ID)
+	print("Result:", result)
+
+	if result["success"] and result["paid"]:
+		print("Order is PAID on-chain")
+	elif result["success"]:
+		print("Order is NOT paid yet")
+	else:
+		print("Error:", result["error"])
+		
+except PayraSDKException as e:
+	print(f"Payra SDK error: {e}")
+except  Exception  as e:
+	print(f"Unexpected error: {e}")
+```
+
+#### Behind the Scenes
+
+1. The backend initializes a `PayraOrderVerification` object for the desired blockchain network.
+2. It calls `is_order_paid(order_id)` to check if the order transaction exists and is confirmed on-chain.
+3. The function returns a dictionary with:
+```python
+{
+	"success": True,
+	"paid": True,
+	"error": None
+}
+```
+4. If `paid` is `True`, the order has been successfully processed and confirmed by the Payra smart contract.
+ 
+---
+
+### Using Utility Functions
+
+The `PayraUtils` module provides convenient helpers for token conversion, precision handling, and fiat currency operations.
+
+```python
+from payra_sdk import PayraUtils
+
+# Convert USD/token amount to smallest unit (Wei or token decimals)
+amount_wei = PayraUtils.to_wei(3.34, 'polygon', 'usdt')
+print("Amount in Wei:", amount_wei) # 3340000
+
+# Convert from Wei back to readable token amount
+amount = PayraUtils.from_wei(3340000, 'polygon', 'usdt', precision=2)
+print("Readable amount:", amount) # "3.34"
+
+# Get token decimals for any supported network
+print("USDT decimals on Polygon:", PayraUtils.get_decimals("polygon", "usdt"))
+print("POL decimals on Polygon:", PayraUtils.get_decimals("polygon", "pol"))
+
+# Convert fiat currency to USD using the built-in ExchangeRate API
+usd_value = PayraUtils.convert_to_usd(100, "EUR")
+print(f"100 EUR = {usd_value} USD")
+```
+
+#### Behind the Scenes
+
+-  `to_wei(amount, network, token)` – Converts a human-readable token amount into the smallest unit (used on-chain).
+-  `from_wei(amount, network, token, precision)` – Converts back from smallest unit to a formatted amount.
+-  `get_decimals(network, token)` – Returns the number of decimals for the given token on that network.
+-  `convert_to_usd(amount, currency)` – Converts fiat amounts (e.g. EUR, GBP) to USD using your ExchangeRate API key.
+
+
+## Testing
+
+You can run the included `examples` to test signing and verification:
+
+```python
+python3 example_signature.py
+python3 example_order_verification.py
+python3 example_utils.py
+```
+
+Make sure your `.env` file contains correct values for the `network` being used.
+
+### Tips
+
+- Always verify your `.env` configuration before running any signing or on-chain verification examples.
+- The SDK examples are safe to run, they use **read-only RPC calls** (no real transactions are broadcast).
+- You can modify `example_signature.py` to test custom token addresses or order parameters.
+
+
+## Projects
+
+- [GitHub/Home](https://github.com/payracash)
+- [GitHub/Source](https://github.com/payracash/payra-sdk-python)
+- [GitHub/Issues](https://github.com/payracash/payra-sdk-python/issues)
+
+## Project
+
+- [https://payra.cash](https://payra.cash)
+- [https://payra.tech](https://payra.tech)
+- [https://payra.xyz](https://payra.xyz)
+- [https://payra.eth](https://payra.eth.limo) - suporrted by Brave and Opera Browser or .limo
+
+
+## Social Media
+
+- [Telegram Payra Group](https://t.me/+GhTyJJrd4SMyMDA0)
+- [Telegram Announcements](https://t.me/payracash)
+- [Twix (X)](https://x.com/PayraCash)
+- [Dev.to](https://dev.to/payracash)
+
+## License
+MIT © [Payra](https://payra.cash)

payra_sdk-1.2.6.dist-info/RECORD

@@ -0,0 +1,10 @@
+payra_sdk/__init__.py,sha256=VMmHadXy0RLCjEPZhW_hCc3hg34pkmrL4VhTjqmVBiI,422
+payra_sdk/exceptions.py,sha256=Dr8dy0RohAYII_-YeSu_doPJSr0EsJPcp6Oj02sio9Q,425
+payra_sdk/order_verification.py,sha256=_AMdw4FQf-WMO0nswylW3AJoCJbxo7__Xi1zz6IeiJo,4342
+payra_sdk/signature.py,sha256=JhozJ_Fwhn8lOHO-p8xEHn80I-TMHdeibzIXBI_bkkg,8627
+payra_sdk/utils.py,sha256=mp9xX-6ph_xRMSIHh6PP41RcYyKZMLVPEi9M3IxxC4c,4147
+payra_sdk-1.2.6.dist-info/licenses/LICENSE,sha256=mnnujAcvHr1ULEDD2l0ZT6lrpeTv_9bG3n8sngv7ew8,120
+payra_sdk-1.2.6.dist-info/METADATA,sha256=e3OjC4MBEExh-3BVtQvoYznj1J-oSbgXfC6x54h8Kas,14365
+payra_sdk-1.2.6.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+payra_sdk-1.2.6.dist-info/top_level.txt,sha256=oC4dhGzjcpDRRwyU9JjtLu56Uc5moaa76utQGYsPL-g,10
+payra_sdk-1.2.6.dist-info/RECORD,,

{payra_sdk-1.2.4.dist-info → payra_sdk-1.2.6.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (80.9.0)
+Generator: setuptools (80.10.2)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

payra_sdk-1.2.4.dist-info/METADATA

@@ -1,350 +0,0 @@
-Metadata-Version: 2.4
-Name: payra_sdk
-Version: 1.2.4
-Summary: Python SDK for Payra payment signature generation (backend)
-Author: Your Name
-Author-email: Wraith <contact@payra.cash>
-License: MIT License
-        
-        Copyright (c) 2025 Wraith
-        
-        Permission is hereby granted, free of charge, to any person obtaining a copy...
-        
-Project-URL: Homepage, https://github.com/payracash
-Project-URL: Source, https://github.com/payracash/payra-sdk-python
-Project-URL: Issues, https://github.com/payracash/payra-sdk-python/issues
-Requires-Python: >=3.8
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: web3>=6.0.0
-Requires-Dist: eth-abi>=4.0.0
-Requires-Dist: eth-account>=0.10.0
-Requires-Dist: python-dotenv>=1.0.0
-Dynamic: license-file
-
-
-
-# Payra Python SDK
-
-Official **Python SDK** for integrating **Payra's on-chain payment system** into your backend applications.
-
-This SDK provides:
-- Secure generation of **ECDSA signatures** compatible with the Payra smart contract — used for order payment verification.
-- Simple methods for **checking the on-chain status of orders** to confirm completed payments.
-
-## How It Works
-
-The typical flow for signing and verifying a Payra transaction:
-
-1.  The  **frontend**  prepares all required payment parameters:
-    -   **Network**  – blockchain name (e.g. Polygon, Linea)
-    -   **Token address**  – ERC-20 token contract address
-    -   **Order ID**  – unique order identifier
-    -   **Amount Wei**  – already converted to the smallest unit (e.g. wei, 10⁶)
-    -   **Timestamp**  – Unix timestamp of the order
-    -   **Payer wallet address**  – the wallet address from which the user will make the on-chain payment
-2.  The frontend sends these parameters to your  **backend**.
-3.  The  **backend**  uses this SDK to generate a cryptographic  **ECDSA signature**  with its private key (performed  **offline**).
-4.  The backend returns the generated signature to the frontend.
-5.  The  **frontend**  calls the Payra smart contract (`payOrder`) with all parameters  **plus**  the signature.
-
-This process ensures full compatibility between your backend and Payra’s on-chain verification logic.
-
-## Features
-
-- Generates **Ethereum ECDSA signatures** using the `secp256k1` curve.
-- Fully compatible with **Payra's Solidity smart contracts** (`ERC-1155` payment verification).  
-- Includes built-in **ABI encoding and decoding** via `web3.php`.
-- Supports `.env` and  `config/payra.php` configuration for multiple blockchain networks.  
-- Laravel IoC container integration (easy dependency injection)
-- Verifies **order payment status directly on-chain** via RPC or blockchain explorer API.  
-- Provides **secure backend integration** for signing and verifying transactions.
-- Includes optional utility helpers for:
-  - **Currency conversion** (via [ExchangeRate API](https://www.exchangerate-api.com/))
-  - **USD ⇄ WEI** conversion for token precision handling.
-
-## Setup
-
-Before installing this package, make sure you have an active **Payra** account:
-
-[https://payra.cash](https://payra.cash)
-
-You will need:
-
-- Your **Merchant ID** (unique for each blockchain network)  
-- Your **Private Key** (used to sign Payra transactions securely)
-
-Additionally:
-
-- Create a free account at [QuickNode](https://www.quicknode.com/) to obtain your **RPC URLs** - these are required for reading on-chain order statuses directly from the blockchain.
-
-Optional (recommended):
-
-- Create a free API key at [ExchangeRate API](https://www.exchangerate-api.com/)  
-  to enable **automatic fiat → USD conversions** using the built-in utility helpers.
-
-## Installation
-
-### From PyPI
-
-Install the latest stable version from [PyPI](https://pypi.org/project/payra-sdk/):
-
-```bash
-pip install payra-sdk
-```
-
-### From Source (for development)
-
-Clone and install locally (editable mode for development):
-
-```bash
-git clone https://github.com/payracash/payra-sdk-python.git
-cd payra-sdk-python
-
-python3 -m venv venv
-source venv/bin/activate  # Windows: venv\Scripts\activate
-
-pip install -e .
-```
-
-### Dependencies
-
-This SDK requires:
-- **Python 3.8+**
-- **web3.py**
-- **ecdsa**
-- **python-dotenv**
--   _(optional)_  `requests`  and  `exchange-rate-api`  for fiat conversion utilities.
-
-## Environment Configuration
-
-Create a `.env` file in your project root (you can copy from example):
-
-```bash
-cp .env.example .env
-```
-
-This file stores your **private configuration** and connection settings for all supported networks.  Never commit `.env` to version control.
-
-### Required Variables
-
-#### Exchange Rate (optional)
-
-Used for automatic fiat → USD conversions via the built-in Payra utilities.
-
-```bash
-# Optional — only needed if you want to use the built-in currency conversion helper
-PAYRA_EXCHANGE_RATE_API_KEY=         # Your ExchangeRate API key (from exchangerate-api.com)
-PAYRA_EXCHANGE_RATE_CACHE_TIME=720   # Cache duration in minutes (default: 720 = 12h)
-
-PAYRA_POLYGON_CORE_FORWARD_CONTRACT_ADDRESS=0xf30070da76B55E5cB5750517E4DECBD6Cc5ce5a8
-PAYRA_POLYGON_PRIVATE_KEY=
-PAYRA_POLYGON_MERCHANT_ID=
-PAYRA_POLYGON_RPC_URL_1=
-PAYRA_POLYGON_RPC_URL_2=
-
-PAYRA_ETHEREUM_CORE_FORWARD_CONTRACT_ADDRESS=
-PAYRA_ETHEREUM_PRIVATE_KEY=
-PAYRA_ETHEREUM_MERCHANT_ID=
-PAYRA_ETHEREUM_RPC_URL_1=
-PAYRA_ETHEREUM_RPC_URL_2=
-
-PAYRA_LINEA_CORE_FORWARD_CONTRACT_ADDRESS=
-PAYRA_LINEA_PRIVATE_KEY=
-PAYRA_LINEA_MERCHANT_ID=
-PAYRA_LINEA_RPC_URL_1=
-PAYRA_LINEA_RPC_URL_2=
-```
-
-#### Important Notes
-
--   The cache automatically refreshes when it expires.    
--   You can adjust the cache duration by setting  `PAYRA_EXCHANGE_RATE_CACHE_TIME`:
-    -   `5`  → cache for 5 minutes
-    -   `60`  → cache for 1 hour
-    -   `720`  → cache for 12 hours (default)
-- Each network (Polygon, Ethereum, Linea) has its own  **merchant ID**,  **private key**, and  **RPC URLs**.  
-- The SDK automatically detects which chain configuration to use based on the selected network.
-- You can use multiple RPC URLs for redundancy (the SDK will automatically fall back if one fails).
-- Contract addresses correspond to the deployed Payra Core Forward contracts per network.
-
-## Usage Example
-
-### Generating and verifying a Payra signature in your backend
-
-```python
-from payra_sdk import PayraUtils, PayraSignatureGenerator, PayraSDKException
-
-try:
-    # Convert amount to smallest unit (wei or token decimals)
-    amount_wei = PayraUtils.to_wei(3.34, 'polygon', 'usdt')
-
-    PAYMENT_DATA = {
-        "network": "polygon",
-        "tokenAddress": "0xc2132D05D31c914a87C6611C10748AEb04B58e8F",  # USDT on Polygon
-        "orderId": "ORDER-1753824905006-301-322",
-        "amountWei": amount_wei,  # e.g. 3.34 USDT in smallest unit
-        "timestamp": 1753826059,  # current Unix timestamp
-        "payerAddress": "0xe6c961D6ad9a27Ea8e5d99e40abaC365DE9Cc162"
-    }
-
-    # Initialize signer
-    payra_signer = PayraSignatureGenerator()
-
-    # Generate cryptographic signature
-    signature = payra_signer.generate_signature(
-        network=PAYMENT_DATA["network"],
-        token_address=PAYMENT_DATA["tokenAddress"],
-        order_id=PAYMENT_DATA["orderId"],
-        amount_wei=PAYMENT_DATA["amountWei"],
-        timestamp=PAYMENT_DATA["timestamp"],
-        payer_address=PAYMENT_DATA["payerAddress"]
-    )
-
-    print(f"Generated signature: {signature}")
-
-except PayraSDKException as e:
-    print(f"Payra SDK error: {e}")
-except Exception as e:
-    print(f"Unexpected error: {e}")
-```
-
-#### Input Parameters
-
-| Field         | Type     | Description                                  |
-|--------------|----------|----------------------------------------------|
-| **`network`**    | `string` | Selected network name                        |
-| **`tokenAddress`** | `string` | ERC20 token contract address                 |
-| **`orderId`**     | `string` | Unique order reference (e.g. ORDER-123)      |
-| **`amountWei`**      | `string` or `integer` | Token amount in smallest unit (e.g. wei)     |
-| **`timestamp`**   | `number` | Unix timestamp of signature creation         |
-| **`payerAddress`**   | `string` | Payer Wallet Address      
-
-#### Behind the Scenes
-
-1.  The backend converts the amount to the smallest blockchain unit (e.g. wei).
-3.  A  `PayraSignatureGenerator`  instance is created using your private key from `.env`
-4.  It generates an ECDSA signature that is fully verifiable on-chain by the Payra smart contract.
-5.  The resulting signature should be sent to the **frontend**, which must call `payOrder(...)` using the same parameters (`timestamp`, `orderId`, `amount`, `tokenAddress`, etc.) that were used to generate the signature.
-
----
-
-### Checking On-Chain Order Status
-
-You can verify whether a Payra order has been successfully paid on-chain:
-
-```python
-from payra_sdk import PayraOrderVerification, PayraSDKException
-
-try:
-    ORDER_ID = "ORDER-1753824905006-301-322"
-
-    # Initialize verifier for a specific network
-    verifier = PayraOrderVerification("polygon")
-
-    print("\nChecking order status...")
-    result = verifier.is_order_paid(ORDER_ID)
-
-    print("Order ID:", ORDER_ID)
-    print("Result:", result)
-
-    if result["success"] and result["paid"]:
-        print("Order is PAID on-chain")
-    elif result["success"]:
-        print("Order is NOT paid yet")
-    else:
-        print("Error:", result["error"])
-
-except PayraSDKException as e:
-    print(f"Payra SDK error: {e}")
-except Exception as e:
-    print(f"Unexpected error: {e}")
-```
-
-#### Behind the Scenes
-
-1.  The backend initializes a  `PayraOrderVerification`  object for the desired blockchain network.
-3.  It calls  `is_order_paid(order_id)`  to check if the order transaction exists and is confirmed on-chain.
-4.  The function returns a dictionary with:
-    ```python
-    {
-	    "success": True,
-	    "paid": True,
-	    "error": None
-	}
-	```
-5.  If  `paid`  is  `True`, the order has been successfully processed and confirmed by the Payra smart contract.
-
----
-
-### Using Utility Functions
-
-The `PayraUtils` module provides convenient helpers for token conversion, precision handling, and fiat currency operations.
-
-```python
-from payra_sdk import PayraUtils
-
-# 🔹 Convert USD/token amount to smallest unit (Wei or token decimals)
-amount_wei = PayraUtils.to_wei(3.34, 'polygon', 'usdt')
-print("Amount in Wei:", amount_wei)  # 3340000
-
-# 🔹 Convert from Wei back to readable token amount
-amount = PayraUtils.from_wei(3340000, 'polygon', 'usdt', precision=2)
-print("Readable amount:", amount)  # "3.34"
-
-# 🔹 Get token decimals for any supported network
-print("USDT decimals on Polygon:", PayraUtils.get_decimals("polygon", "usdt"))
-print("POL decimals on Polygon:", PayraUtils.get_decimals("polygon", "pol"))
-
-# 🔹 Convert fiat currency to USD using the built-in ExchangeRate API
-usd_value = PayraUtils.convert_to_usd(100, "EUR")
-print(f"100 EUR = {usd_value} USD")
-```
-
-#### Behind the Scenes
-
--   `to_wei(amount, network, token)`  – Converts a human-readable token amount into the smallest unit (used on-chain).
--   `from_wei(amount, network, token, precision)`  – Converts back from smallest unit to a formatted amount.
--   `get_decimals(network, token)`  – Returns the number of decimals for the given token on that network.
--   `convert_to_usd(amount, currency)`  – Converts fiat amounts (e.g. EUR, GBP) to USD using your ExchangeRate API key.
-
-## Testing
-You can run the included `examples` to test signing and verification:
-
-```python
-python3 example_signature.py
-python3 example_order_verification.py
-python3 example_utils.py
-```
-
-Make sure your `.env` file contains correct values for the `network` being used.
-
-### Tips
-
-- Always verify your `.env` configuration before running any signing or on-chain verification examples.
-- The SDK examples are safe to run — they use  **read-only RPC calls**  (no real transactions are broadcast).
-- You can modify  `example_signature.py`  to test custom token addresses or order parameters.
-
-## Projects
-
--   [GitHub / Home](https://github.com/payracash)
--   [GitHub / Source](https://github.com/payracash/payra-sdk-python)
--   [GitHub / Issues](https://github.com/payracash/payra-sdk-python/issues)
-
-## Project
-
--   [https://payra.cash](https://payra.cash)
--   [https://payra.tech](https://payra.tech)
--   [https://payra.xyz](https://payra.xyz)
--   [https://payra.eth](https://payra.eth)
-
-## Social Media
-
-- [Telegram Payra Group](https://t.me/+GhTyJJrd4SMyMDA0)
-- [Telegram Announcements](https://t.me/payracash)
-- [Twix (X)](https://x.com/PayraCash)
-- [Hashnode](https://payra.hashnode.dev)
-
-##  License
-
-MIT © [Payra](https://github.com/payracash)

payra_sdk-1.2.4.dist-info/RECORD

@@ -1,10 +0,0 @@
-payra_sdk/__init__.py,sha256=VMmHadXy0RLCjEPZhW_hCc3hg34pkmrL4VhTjqmVBiI,422
-payra_sdk/exceptions.py,sha256=Dr8dy0RohAYII_-YeSu_doPJSr0EsJPcp6Oj02sio9Q,425
-payra_sdk/order_verification.py,sha256=IWKV4V6gZRyrtJtXsDRPflUcSsuN5D1kFZn5QVTPi5Q,3379
-payra_sdk/signature.py,sha256=Vn85w4DAGzHK1y9h3hMETij_-Qa4aSNz0KwnzwCyFQw,8613
-payra_sdk/utils.py,sha256=gIQZX9N97Eneh5ScJ-YWY8_8wRqxBe0h5lDAVFYV8CE,4854
-payra_sdk-1.2.4.dist-info/licenses/LICENSE,sha256=mnnujAcvHr1ULEDD2l0ZT6lrpeTv_9bG3n8sngv7ew8,120
-payra_sdk-1.2.4.dist-info/METADATA,sha256=BF0bsVhP4ycHdUfzYPG1q6c6zR_z5aG2i2toHAGRW2c,12574
-payra_sdk-1.2.4.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-payra_sdk-1.2.4.dist-info/top_level.txt,sha256=oC4dhGzjcpDRRwyU9JjtLu56Uc5moaa76utQGYsPL-g,10
-payra_sdk-1.2.4.dist-info/RECORD,,