Improved OPG allowance management methods (#209)

* opg management

* tests

* docs

* fix check

* fix check

* allowance

* rm allowance

* tests

* rm debug

* simpple approval

* docs

* docs

* keep 1

* sanity check

* sanity check

* checks

* test

* test

* test

* revert to old name

* wait for opg transfer

* abi

* Update tests/opg_token_test.py

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Signed-off-by: kukac <adambalogh@users.noreply.github.com>

* no src import

---------

Signed-off-by: kukac <adambalogh@users.noreply.github.com>
Co-authored-by: balogh.adam@icloud.com <adambalogh@mac.mynetworksettings.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Author: 3 people

README.md

@@ -88,10 +88,10 @@ hub = og.ModelHub(email="you@example.com", password="...")
 
 ### OPG Token Approval
 
-Before making LLM requests, your wallet must approve OPG token spending via the [Permit2](https://github.com/Uniswap/permit2) protocol. Call this once (it's idempotent — no transaction is sent if the allowance already covers the requested amount):
+Before making LLM requests, your wallet must approve OPG token spending via the [Permit2](https://github.com/Uniswap/permit2) protocol. This only sends an on-chain transaction when the current allowance drops below the threshold:
 
 ```python
-llm.ensure_opg_approval(opg_amount=5)
+llm.ensure_opg_approval(min_allowance=5)
 ```
 
 See [Payment Settlement](#payment-settlement) for details on settlement modes.

docs/CLAUDE_SDK_USERS.md

@@ -21,8 +21,8 @@ import os
 # Create an LLM client
 llm = og.LLM(private_key=os.environ["OG_PRIVATE_KEY"])
 
-# One-time OPG token approval (idempotent — skips if allowance already sufficient)
-llm.ensure_opg_approval(opg_amount=0.1)
+# Ensure sufficient OPG allowance (only sends tx when below threshold)
+llm.ensure_opg_approval(min_allowance=0.1)
 
 # LLM Chat (TEE-verified with x402 payments, async)
 result = await llm.chat(

docs/opengradient/client/index.md

@@ -24,7 +24,7 @@ import opengradient as og
 
 # LLM inference (Base Sepolia OPG tokens)
 llm = og.LLM(private_key="0x...")
-llm.ensure_opg_approval(opg_amount=5)
+llm.ensure_opg_approval(min_allowance=5)
 result = await llm.chat(model=og.TEE_LLM.CLAUDE_HAIKU_4_5, messages=[...])
 
 # On-chain model inference (OpenGradient testnet gas tokens)

docs/opengradient/client/llm.md

@@ -22,8 +22,6 @@ All request methods (``chat``, ``completion``) are async.
 
 Before making LLM requests, ensure your wallet has approved sufficient
 OPG tokens for Permit2 spending by calling ``ensure_opg_approval``.
-This only sends an on-chain transaction when the current allowance is
-below the requested amount.
 
 #### Constructor
 
@@ -193,18 +191,30 @@ TextGenerationOutput: Generated text results including:
 #### `ensure_opg_approval()`
 
 ```python
-def ensure_opg_approval(self, opg_amount: float) ‑> [Permit2ApprovalResult](./opg_token)
+def ensure_opg_approval(
+    self,
+    min_allowance: float,
+    approve_amount: Optional[float] = None
+) ‑> [Permit2ApprovalResult](./opg_token)
 ```
-Ensure the Permit2 allowance for OPG is at least ``opg_amount``.
+Ensure the Permit2 allowance stays above a minimum threshold.
+
+Only sends a transaction when the current allowance drops below
+``min_allowance``. When approval is needed, approves ``approve_amount``
+(defaults to ``2 * min_allowance``) to create a buffer that survives
+multiple service restarts without re-approving.
+
+Best for backend servers that call this on startup::
 
-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.
+    llm.ensure_opg_approval(min_allowance=5.0, approve_amount=100.0)
 
 **Arguments**
 
-* **`opg_amount`**: Minimum number of OPG tokens required (e.g. ``0.1``
-        for 0.1 OPG). Must be at least 0.1 OPG.
+* **`min_allowance`**: The minimum acceptable allowance in OPG. Must be
+        at least 0.1 OPG.
+* **`approve_amount`**: The amount of OPG to approve when a transaction
+        is needed. Defaults to ``2 * min_allowance``. Must be
+        >= ``min_allowance``.
 
 **Returns**
 
@@ -214,5 +224,6 @@ Permit2ApprovalResult: Contains ``allowance_before``,
 
 **Raises**
 
-* **`ValueError`**: If the OPG amount is less than 0.1.
+* **`ValueError`**: If ``min_allowance`` is less than 0.1 or
+        ``approve_amount`` is less than ``min_allowance``.
 * **`RuntimeError`**: If the approval transaction fails.

docs/opengradient/client/model_hub.md

@@ -43,15 +43,16 @@ Create a new model with the given model_name and model_desc, and a specified ver
 
 * **`model_name (str)`**: The name of the model.
 * **`model_desc (str)`**: The description of the model.
-* **`version (str)`**: The version identifier (default is "1.00").
+* **`version (str)`**: A label used in the initial version notes (default is "1.00").
+* **`Note`**: the actual version string is assigned by the server.
 
 **Returns**
 
-dict: The server response containing model details.
+ModelRepository: Object containing the model name and server-assigned version string.
 
 **Raises**
 
-* **`CreateModelError`**: If the model creation fails.
+* **`RuntimeError`**: If the model creation fails.
 
 ---
 
@@ -125,7 +126,7 @@ Upload a model file to the server.
 
 **Returns**
 
-dict: The processed result.
+FileUploadResult: The processed result.
 
 **Raises**
 

docs/opengradient/client/opg_token.md

@@ -35,7 +35,7 @@ import opengradient as og
 llm = og.LLM(private_key="0x...")
 
 # One-time OPG token approval (idempotent -- skips if allowance is sufficient)
-llm.ensure_opg_approval(opg_amount=5)
+llm.ensure_opg_approval(min_allowance=5)
 
 # Chat with an LLM (TEE-verified)
 response = asyncio.run(llm.chat(

docs/opengradient/index.md

@@ -17,9 +17,9 @@
 
 private_key = os.environ["OG_PRIVATE_KEY"]
 
-# One-time Permit2 approval for OPG spending (idempotent)
+# Ensure sufficient OPG allowance for Permit2 spending
 llm_client = og.LLM(private_key=private_key)
-llm_client.ensure_opg_approval(opg_amount=5)
+llm_client.ensure_opg_approval(min_allowance=5)
 
 # Create the OpenGradient LangChain adapter
 llm = og.agents.langchain_adapter(

examples/langchain_react_agent.py

@@ -10,7 +10,7 @@
 
 async def main():
     llm = og.LLM(private_key=os.environ.get("OG_PRIVATE_KEY"))
-    llm.ensure_opg_approval(opg_amount=0.1)
+    llm.ensure_opg_approval(min_allowance=0.1)
 
     messages = [
         {"role": "user", "content": "What is the capital of France?"},

examples/llm_chat.py

@@ -6,7 +6,7 @@
 
 async def main():
     llm = og.LLM(private_key=os.environ.get("OG_PRIVATE_KEY"))
-    llm.ensure_opg_approval(opg_amount=0.1)
+    llm.ensure_opg_approval(min_allowance=0.1)
 
     messages = [
         {"role": "user", "content": "What is Python?"},