opg management

Author: balogh.adam@icloud.com

src/opengradient/client/llm.py

@@ -15,7 +15,7 @@
 from x402.mechanisms.evm.upto.register import register_upto_evm_client
 
 from ..types import TEE_LLM, StreamChoice, StreamChunk, StreamDelta, TextGenerationOutput, x402SettlementMode
-from .opg_token import Permit2ApprovalResult, ensure_opg_approval
+from .opg_token import Permit2ApprovalResult, approve_opg, ensure_opg_allowance, ensure_opg_approval
 from .tee_connection import RegistryTEEConnection, StaticTEEConnection, TEEConnectionInterface
 from .tee_registry import TEERegistry
 

src/opengradient/client/opg_token.py

@@ -1,13 +1,17 @@
 """OPG token Permit2 approval utilities for x402 payments."""
 
-from dataclasses import dataclass
+import logging
 import time
+import warnings
+from dataclasses import dataclass
 from typing import Optional
 
 from eth_account.account import LocalAccount
 from web3 import Web3
 from x402.mechanisms.evm.constants import PERMIT2_ADDRESS
 
+logger = logging.getLogger(__name__)
+
 BASE_OPG_ADDRESS = "0x240b09731D96979f50B2C649C9CE10FcF9C7987F"
 BASE_SEPOLIA_RPC = "https://sepolia.base.org"
 APPROVAL_TX_TIMEOUT = 120
@@ -53,42 +57,32 @@ class Permit2ApprovalResult:
     tx_hash: Optional[str] = None
 
 
-def ensure_opg_approval(wallet_account: LocalAccount, opg_amount: float) -> Permit2ApprovalResult:
-    """Ensure the Permit2 allowance for OPG is at least ``opg_amount``.
-
-    Checks the current Permit2 allowance for the wallet. If the allowance
-    is already >= the requested amount, returns immediately without sending
-    a transaction. Otherwise, sends an ERC-20 approve transaction.
+def _send_approve_tx(
+    wallet_account: LocalAccount,
+    w3: Web3,
+    token,
+    owner: str,
+    spender: str,
+    amount_base: int,
+) -> Permit2ApprovalResult:
+    """Send an ERC-20 approve transaction and wait for confirmation.
 
     Args:
-        wallet_account: The wallet account to check and approve from.
-        opg_amount: Minimum number of OPG tokens required (e.g. ``5.0``
-            for 5 OPG). Converted to base units (18 decimals) internally.
+        wallet_account: The wallet to sign the transaction with.
+        w3: Web3 instance connected to the RPC.
+        token: The ERC-20 contract instance.
+        owner: Checksummed owner address.
+        spender: Checksummed spender (Permit2) address.
+        amount_base: The amount to approve in base units (18 decimals).
 
     Returns:
-        Permit2ApprovalResult: Contains ``allowance_before``,
-            ``allowance_after``, and ``tx_hash`` (None when no approval
-            was needed).
+        Permit2ApprovalResult with the before/after allowance and tx hash.
 
     Raises:
-        RuntimeError: If the approval transaction fails.
+        RuntimeError: If the transaction reverts or fails.
     """
-    amount_base = int(opg_amount * 10**18)
-
-    w3 = Web3(Web3.HTTPProvider(BASE_SEPOLIA_RPC))
-    token = w3.eth.contract(address=Web3.to_checksum_address(BASE_OPG_ADDRESS), abi=ERC20_ABI)
-    owner = Web3.to_checksum_address(wallet_account.address)
-    spender = Web3.to_checksum_address(PERMIT2_ADDRESS)
-
     allowance_before = token.functions.allowance(owner, spender).call()
 
-    # Only approve if the allowance is less than 50% of the requested amount
-    if allowance_before >= amount_base * 0.5:
-        return Permit2ApprovalResult(
-            allowance_before=allowance_before,
-            allowance_after=allowance_before,
-        )
-
     try:
         approve_fn = token.functions.approve(spender, amount_base)
         nonce = w3.eth.get_transaction_count(owner, "pending")
@@ -133,3 +127,151 @@ def ensure_opg_approval(wallet_account: LocalAccount, opg_amount: float) -> Perm
         raise
     except Exception as e:
         raise RuntimeError(f"Failed to approve Permit2 for OPG: {e}")
+
+
+def _get_web3_and_contract():
+    """Create a Web3 instance and OPG token contract."""
+    w3 = Web3(Web3.HTTPProvider(BASE_SEPOLIA_RPC))
+    token = w3.eth.contract(address=Web3.to_checksum_address(BASE_OPG_ADDRESS), abi=ERC20_ABI)
+    spender = Web3.to_checksum_address(PERMIT2_ADDRESS)
+    return w3, token, spender
+
+
+def approve_opg(wallet_account: LocalAccount, opg_amount: float) -> Permit2ApprovalResult:
+    """Approve Permit2 to spend ``opg_amount`` OPG if the current allowance is insufficient.
+
+    Idempotent: if the current allowance is already >= ``opg_amount``, no
+    transaction is sent.
+
+    Best for one-off usage — scripts, notebooks, CLI tools::
+
+        result = approve_opg(wallet, 5.0)
+
+    Args:
+        wallet_account: The wallet account to check and approve from.
+        opg_amount: Number of OPG tokens to approve (e.g. ``5.0`` for 5 OPG).
+            Converted to base units (18 decimals) internally.
+
+    Returns:
+        Permit2ApprovalResult: Contains ``allowance_before``,
+            ``allowance_after``, and ``tx_hash`` (None when no approval
+            was needed).
+
+    Raises:
+        RuntimeError: If the approval transaction fails.
+    """
+    amount_base = int(opg_amount * 10**18)
+
+    w3, token, spender = _get_web3_and_contract()
+    owner = Web3.to_checksum_address(wallet_account.address)
+
+    allowance_before = token.functions.allowance(owner, spender).call()
+
+    if allowance_before >= amount_base:
+        logger.debug("Permit2 allowance already sufficient (%s >= %s), skipping approval", allowance_before, amount_base)
+        return Permit2ApprovalResult(
+            allowance_before=allowance_before,
+            allowance_after=allowance_before,
+        )
+
+    logger.info("Permit2 allowance insufficient (%s < %s), sending approval tx", allowance_before, amount_base)
+    return _send_approve_tx(wallet_account, w3, token, owner, spender, amount_base)
+
+
+def ensure_opg_allowance(
+    wallet_account: LocalAccount,
+    min_allowance: float,
+    approve_amount: Optional[float] = None,
+) -> Permit2ApprovalResult:
+    """Ensure the Permit2 allowance stays above a minimum threshold.
+
+    Only sends an approval transaction when the current allowance drops
+    below ``min_allowance``. When approval is needed, approves
+    ``approve_amount`` (defaults to ``10 * min_allowance``) to create a
+    buffer that survives multiple service restarts without re-approving.
+
+    Best for backend servers that call this on startup::
+
+        # On startup — only sends a tx when allowance < 5 OPG,
+        # then approves 100 OPG so subsequent restarts are free.
+        result = ensure_opg_allowance(wallet, min_allowance=5.0, approve_amount=100.0)
+
+    Args:
+        wallet_account: The wallet account to check and approve from.
+        min_allowance: The minimum acceptable allowance in OPG. A
+            transaction is only sent when the current allowance is
+            strictly below this value.
+        approve_amount: The amount of OPG to approve when a transaction
+            is needed. Defaults to ``10 * min_allowance``. Must be
+            >= ``min_allowance``.
+
+    Returns:
+        Permit2ApprovalResult: Contains ``allowance_before``,
+            ``allowance_after``, and ``tx_hash`` (None when no approval
+            was needed).
+
+    Raises:
+        ValueError: If ``approve_amount`` is less than ``min_allowance``.
+        RuntimeError: If the approval transaction fails.
+    """
+    if approve_amount is None:
+        approve_amount = min_allowance * 10
+
+    if approve_amount < min_allowance:
+        raise ValueError(f"approve_amount ({approve_amount}) must be >= min_allowance ({min_allowance})")
+
+    min_base = int(min_allowance * 10**18)
+    approve_base = int(approve_amount * 10**18)
+
+    w3, token, spender = _get_web3_and_contract()
+    owner = Web3.to_checksum_address(wallet_account.address)
+
+    allowance_before = token.functions.allowance(owner, spender).call()
+
+    if allowance_before >= min_base:
+        logger.debug(
+            "Permit2 allowance above minimum threshold (%s >= %s), skipping approval",
+            allowance_before,
+            min_base,
+        )
+        return Permit2ApprovalResult(
+            allowance_before=allowance_before,
+            allowance_after=allowance_before,
+        )
+
+    logger.info(
+        "Permit2 allowance below minimum threshold (%s < %s), approving %s base units",
+        allowance_before,
+        min_base,
+        approve_base,
+    )
+    return _send_approve_tx(wallet_account, w3, token, owner, spender, approve_base)
+
+
+def ensure_opg_approval(wallet_account: LocalAccount, opg_amount: float) -> Permit2ApprovalResult:
+    """Ensure the Permit2 allowance for OPG is at least ``opg_amount``.
+
+    .. deprecated::
+        Use ``approve_opg`` for one-off approvals or
+        ``ensure_opg_allowance`` for server-startup usage.
+
+    Args:
+        wallet_account: The wallet account to check and approve from.
+        opg_amount: Minimum number of OPG tokens required (e.g. ``5.0``
+            for 5 OPG). Converted to base units (18 decimals) internally.
+
+    Returns:
+        Permit2ApprovalResult: Contains ``allowance_before``,
+            ``allowance_after``, and ``tx_hash`` (None when no approval
+            was needed).
+
+    Raises:
+        RuntimeError: If the approval transaction fails.
+    """
+    warnings.warn(
+        "ensure_opg_approval is deprecated. Use approve_opg for one-off approvals "
+        "or ensure_opg_allowance for server-startup usage.",
+        DeprecationWarning,
+        stacklevel=2,
+    )
+    return approve_opg(wallet_account, opg_amount)