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

payra_sdk/utils.py

@@ -2,8 +2,10 @@
 
 import os
 import time
+import json
 import requests
 from web3 import Web3
+from pathlib import Path
 from typing import Any, Dict, Union
 from .exceptions import InvalidArgumentError
 
@@ -13,9 +15,8 @@ class PayraUtils:
     Provides helper methods for conversions and ABI-related operations.
     """
 
-    _cache_data = None
-    _cache_timestamp = 0
-    _cache_ttl = 720 * 60
+    _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]:
@@ -79,43 +80,51 @@ class PayraUtils:
     def convert_to_usd(amount: float, from_currency: str) -> float:
         """
         Converts a given amount from another currency to USD using the ExchangeRate API.
-        Requires:
-          - EXCHANGE_RATE_API_KEY (API key only)
-          - optional EXCHANGE_RATE_CACHE_TIME (minutes)
+        Caches data in ~/.payra_cache/exchange_rate.json to minimize API usage.
+        Default cache time: 720 minutes (12 hours).
         """
 
-        api_key = os.getenv("EXCHANGE_RATE_API_KEY")
+        api_key = os.getenv("PAYRA_EXCHANGE_RATE_API_KEY")
         if not api_key:
-            raise InvalidArgumentError("EXCHANGE_RATE_API_KEY is not set in .env")
+            raise InvalidArgumentError("PAYRA_EXCHANGE_RATE_API_KEY is not set in .env")
 
-        # TTL in minutes (if not exists, use default 720)
-        cache_minutes = int(os.getenv("EXCHANGE_RATE_CACHE_TIME", 720))
-        PayraUtils._cache_ttl = cache_minutes * 60
+        cache_minutes = int(os.getenv("PAYRA_EXCHANGE_RATE_CACHE_TIME", 720))
+        cache_ttl = cache_minutes * 60
 
         api_url = f"https://v6.exchangerate-api.com/v6/{api_key}/latest/USD"
         from_currency = from_currency.upper()
-
         current_time = time.time()
 
-        # use cache if < TTL
-        if (
-            PayraUtils._cache_data is not None
-            and (current_time - PayraUtils._cache_timestamp) < PayraUtils._cache_ttl
-        ):
-            data = PayraUtils._cache_data
-        else:
+        # Ensure cache directory exists
+        PayraUtils._cache_dir.mkdir(parents=True, exist_ok=True)
+
+        # Try to read cache from file
+        data = None
+        if PayraUtils._cache_file.exists():
+            try:
+                with open(PayraUtils._cache_file, "r") as f:
+                    cache = json.load(f)
+                if (current_time - cache.get("timestamp", 0)) < cache_ttl:
+                    data = cache.get("data")
+            except Exception:
+                pass  # Ignore invalid cache
+
+        # Fetch new data if no valid cache
+        if data is None:
             try:
                 response = requests.get(api_url, timeout=10)
                 response.raise_for_status()
                 data = response.json()
 
-                PayraUtils._cache_data = data
-                PayraUtils._cache_timestamp = current_time
+                # Save new cache
+                with open(PayraUtils._cache_file, "w") as f:
+                    json.dump({"timestamp": current_time, "data": data}, f)
             except requests.RequestException as e:
                 raise InvalidArgumentError(f"Failed to connect to ExchangeRate API: {e}")
             except (KeyError, ValueError) as e:
                 raise InvalidArgumentError(f"Invalid data from ExchangeRate API: {e}")
 
+        # Validate and convert
         if "conversion_rates" not in data or from_currency not in data["conversion_rates"]:
             raise InvalidArgumentError(f"Conversion rate for {from_currency} not found in API response")
 

{payra_sdk-1.2.2.dist-info → payra_sdk-1.2.4.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: payra_sdk
-Version: 1.2.2
+Version: 1.2.4
 Summary: Python SDK for Payra payment signature generation (backend)
 Author: Your Name
 Author-email: Wraith <contact@payra.cash>
@@ -26,7 +26,7 @@ Dynamic: license-file
 
 # Payra Python SDK
 
-Official Python SDK for integrating **Payra's on-chain payment system** into your backend applications.
+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.
@@ -36,38 +36,38 @@ This SDK provides:
 
 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
-   - **AmountWei** – already converted to the smallest unit (e.g. wei, 10⁶)
-   - **Timestamp** – Unix timestamp of the order
-   - **Payer wallet address**
-
-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.
+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.  
+- 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.py`](https://github.com/ethereum/web3.py).  
-- Supports environment-based configuration (`.env`) for managing multiple blockchain networks.  
+- 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** using merchant private keys.  
+- 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.  
+  - **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)
+[https://payra.cash](https://payra.cash)
 
 You will need:
 
@@ -118,13 +118,13 @@ This SDK requires:
 
 ## Environment Configuration
 
-Create a (`.env`) file in your project root (you can copy from example):
+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.
+This file stores your **private configuration** and connection settings for all supported networks.  Never commit `.env` to version control.
 
 ### Required Variables
 
@@ -133,8 +133,9 @@ This file stores your **private configuration** and connection settings for all
 Used for automatic fiat → USD conversions via the built-in Payra utilities.
 
 ```bash
-EXCHANGE_RATE_API_KEY=         # Your ExchangeRate API key (from exchangerate-api.com)
-EXCHANGE_RATE_CACHE_TIME=720   # Cache duration in minutes (default: 720 = 12h)
+# 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=
@@ -158,7 +159,7 @@ PAYRA_LINEA_RPC_URL_2=
 #### Important Notes
 
 -   The cache automatically refreshes when it expires.    
--   You can adjust the cache duration by setting  `EXCHANGE_RATE_CACHE_TIME`:
+-   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)
@@ -208,10 +209,21 @@ 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`).
+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.
 
@@ -305,11 +317,11 @@ python3 example_order_verification.py
 python3 example_utils.py
 ```
 
-Make sure your (`.env`) file contains correct values for the `network` being used.
+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.
+- 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.
 

{payra_sdk-1.2.2.dist-info → payra_sdk-1.2.4.dist-info}/RECORD

@@ -2,9 +2,9 @@ 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=zNQxq0u9oCO0J3je5jSVPeeT_blBbs5TsqZzL_801u0,4374
-payra_sdk-1.2.2.dist-info/licenses/LICENSE,sha256=mnnujAcvHr1ULEDD2l0ZT6lrpeTv_9bG3n8sngv7ew8,120
-payra_sdk-1.2.2.dist-info/METADATA,sha256=nbSzmSh6nNNGorxELDeqpFf67Ru4eioO4s5U_vfPyFE,11696
-payra_sdk-1.2.2.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-payra_sdk-1.2.2.dist-info/top_level.txt,sha256=oC4dhGzjcpDRRwyU9JjtLu56Uc5moaa76utQGYsPL-g,10
-payra_sdk-1.2.2.dist-info/RECORD,,
+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,,