Update README.md

README.md

@@ -1,4 +1,3 @@
-
 ---
 license: apache-2.0
 base_model:
@@ -45,7 +44,7 @@ tags:
 
 It is engineered for both ends of a stablecoin payment's operational lifecycle:
 - **Pre-Settlement Risk Gate:** Ingests payment requests (x402 requests, EIP-3009 authorizations, or standard ERC-20 transfers), policy constraints, and deterministic verification tool outputs (sanctions hits, attestation checks, signature status) to return structured `approve` / `hold` / `reject` decisions with explicit flags and required actions.
-- **Post-Settlement Dispute Adjudication:** Ingests signed dispute evidence, merchant bond liquidity, and smart contract escrow state to determine legally and technically enforceable remedies across the settlement-finality boundary. It enforces valid remedies (void before release, arbiter refund from escrow, merchant bond drawdown, voluntary refund, deny, or escalate) with exact amounts, destinations, and idempotency keys—strictly avoiding impossible reversals on immutable ledgers.
+- **Post-Settlement Dispute Adjudication:** Ingests signed dispute evidence, merchant bond liquidity, and smart contract escrow state to determine legally and technically enforceable remedies across the settlement-finality boundary. It is designed to minimize impossible reversals across the settlement boundary, proposing valid settlement-aware remedies (void before release, arbiter refund from escrow, merchant bond drawdown, voluntary refund, deny, or escalate) with exact amounts, destinations, and idempotency keys.
 
 ---
 
@@ -53,56 +52,63 @@ It is engineered for both ends of a stablecoin payment's operational lifecycle:
 
 Autonomous on-chain agents can hallucinate payment transfers, sign malformed calldata, or trigger catastrophic transactions during market depegs. 
 
-The deterministic pre-filter and policy firewall is available directly as a plug-and-play **Action Provider** for the Coinbase AgentKit framework:
+The deterministic pre-filter and policy firewall is available directly as a verified **Action Provider** for the Coinbase AgentKit framework:
 
 ```bash
-pip install "sra-riskgate[agentkit]>=0.3.3"
+pip install "sra-riskgate[agentkit]>=0.3.5"
 
 ```
 
 ### Drop-in Agent Firewall Example
 
-Add `RiskGateActionProvider` to intercept and gate transaction attempts before wallet signing:
+Register `RiskGateActionProvider` as the payment provider on your AgentKit instance. It checks chain support, policies, and peg deviations, executing safe ERC-20 transfers only after approval:
 
 ```python
-from coinbase_agentkit import AgentKit, ActionProviderOptions, CdpWalletProvider, CdpWalletProviderConfig
+from coinbase_agentkit import AgentKit, AgentKitConfig
+from coinbase_agentkit_evm import CdpEvmWalletProvider, CdpEvmWalletProviderConfig
 from sra_riskgate.integrations.agentkit import RiskGateActionProvider
 
-# 1. Initialize your wallet provider
-wallet_provider = CdpWalletProvider(CdpWalletProviderConfig())
+# 1. Initialize CDP EVM Wallet Provider
+wallet_provider = CdpEvmWalletProvider(
+    CdpEvmWalletProviderConfig(
+        api_key_name="CDP_API_KEY_NAME",
+        private_key="CDP_PRIVATE_KEY",
+        network_id="base-mainnet",
+    )
+)
 
 # 2. Wrap agent execution with the deterministic RiskGate firewall
-agentkit = AgentKit(
-    ActionProviderOptions(
+firewall = RiskGateActionProvider(
+    max_amount=1000.0,        # Maximum single transfer ceiling (USDC)
+    depeg_hold_pct=1.0,       # Triggers manual review if depeg >= 1.0%
+    depeg_reject_pct=5.0,     # Aborts execution if depeg >= 5.0%
+)
+
+agent_kit = AgentKit(
+    AgentKitConfig(
         wallet_provider=wallet_provider,
-        action_providers=[
-            RiskGateActionProvider(
-                max_amount=1000.0,      # Ceiling per transaction (USDC)
-                depeg_hold_pct=1.0,      # Triggers manual review if depeg >= 1%
-                depeg_reject_pct=5.0     # Hard aborts execution if depeg >= 5%
-            )
-        ]
+        action_providers=[firewall],
     )
 )
 
 ```
 
-### Deterministic Risk Enforcement
+> **Security Guardrail:** To ensure the firewall cannot be bypassed by an autonomous agent, register `RiskGateActionProvider` as the **sole** payment action provider. Do not register generic native transfer or unconstrained ERC-20 providers alongside it.
 
-Every payment action triggered by the LLM is intercepted and validated against strict financial safety boundaries:
+### Deterministic Pre-Execution Rules
 
 | Check | Action Taken | Why It Matters |
 | --- | --- | --- |
 | **Invalid / Zero Address** | Hard Reject | Aborts `0x0...0` burner or malformed hex executions |
-| **Self-Transfer** | Hard Reject | Blocks recursive/hallucinated self-loops draining gas |
-| **Exceeds Amount Ceiling** | Paused (HOLD) | Intercepts rogue agent spending beyond allocated policy |
-| **Severe Depeg ($\ge 5\%$)** | Critical Abort | Prevents clearing payments in collapsing or compromised assets |
+| **Self-Transfer** | Hard Reject | Blocks recursive or hallucinated self-loops that waste gas |
+| **Exceeds Amount Ceiling** | Paused (`HOLD`) | Intercepts rogue agent spending beyond allocated policy |
+| **Severe Depeg ($\ge 5\%$)** | Critical Abort (`REJECT`) | Prevents clearing payments in collapsing or depegged assets |
 
 ---
 
 ## 🚀 Transformers Quickstart
 
-The model expects the standard ChatML template and outputs strict JSON conforming to the [sra-stablecoin-risk-bench](https://huggingface.co/datasets/sriram1983007/sra-stablecoin-risk-bench) schema:
+The model expects the standard ChatML template and outputs strict JSON conforming to the [sra-stablecoin-risk-bench](https://huggingface.co/datasets/sriram1983007/sra-stablecoin-risk-bench) schema. Always employ fail-closed parsing in production environments:
 
 ```python
 import json
@@ -167,7 +173,7 @@ user_payload = {
             "payee": "0x5e8E36575Ebf9841e54b8641E4Eb1EA38136A3d7",
             "amount_usdc": "0.674731",
             "valid_after": 1793063857,
-            "valid_before": 1793066322
+            "validBefore": 1793066322
         },
         "payment_signature": {"checked": True, "valid": True},
         "attestations": {
@@ -211,11 +217,24 @@ with torch.no_grad():
     outputs = model.generate(
         **inputs,
         max_new_tokens=350,
-        do_sample=False
+        do_sample=False  # Deterministic greedy generation
     )
 
-response = tokenizer.decode(outputs[0][inputs.input_ids.shape[1]:], skip_special_tokens=True)
-print(json.dumps(json.loads(response), indent=2))
+raw_output = tokenizer.decode(outputs[0][inputs.input_ids.shape[1]:], skip_special_tokens=True)
+
+# Fail-closed JSON verification
+try:
+    verdict = json.loads(raw_output)
+    print(json.dumps(verdict, indent=2))
+except json.JSONDecodeError:
+    fallback = {
+        "decision": "hold",
+        "risk_level": "high",
+        "flags": ["malformed_model_output"],
+        "explanation": "Model produced non-parseable output; fail-closed hold triggered.",
+        "required_actions": ["manual_review"]
+    }
+    print(json.dumps(fallback, indent=2))
 
 ```
 
@@ -245,7 +264,7 @@ print(json.dumps(json.loads(response), indent=2))
 The `sra-riskgate` SDK provides zero-latency deterministic pre-filtering rules (bidirectional depeg detection via `abs()`, non-finite payload validation, and single-transfer ceilings) before routing to the neural agent:
 
 ```bash
-pip install --upgrade sra-riskgate
+pip install --upgrade "sra-riskgate>=0.3.5"
 
 ```
 
@@ -276,36 +295,36 @@ print("Explanation:     ", verdict.explanation)
 
 ## 🦙 Quickstart with Ollama
 
-Run locally via Ollama with greedy sampling (`temperature 0.0`) to ensure valid JSON and deterministic risk evaluation:
+Run locally via Ollama. The official packaged Modelfile is pre-configured with `temperature 0.0` for deterministic generation:
 
 ```bash
 ollama run sriram1983007/sra-riskgate
 
 ```
 
-*Note: Ensure `temperature 0.0` is configured in your `Modelfile`.*
-
 ---
 
 ## 📊 Benchmark Evaluation (Held-Out Test Split)
 
 Evaluated against the 2,000-case test set in [`sra-stablecoin-risk-bench`](https://huggingface.co/datasets/sriram1983007/sra-stablecoin-risk-bench) using `score.py`:
 
-| Metric | Target / Gate | Base Model (`Qwen3-4B-Instruct`) | SRA-RiskGate-4B | Status |
+| Metric | Target | Base Model (`Qwen3-4B-Instruct`) | SRA-RiskGate-4B | Status |
 | --- | --- | --- | --- | --- |
-| **SRA Composite Score** | High | 0.4210 | **0.9159** | **PASS** |
-| **Risk Gate Decision Accuracy** | High | 44.30% | **99.49%** | **PASS** |
-| **Unsafe Approval Rate** | <= 2.0% | 34.50% | **0.47%** | **PASS** |
-| **Dispute Impossible Remedy Rate** | <= 1.0% | 6.50% | **0.19%** | **PASS** |
-| **JSON Schema Validity Rate** | >= 98.0% | 82.40% | **100.0%** | **PASS** |
-| **Prompt Injection Recall** | High | 42.10% | **89.86%** | **PASS** |
+| **SRA Composite Score** | $\ge 0.8500$ | 0.4210 | **0.9159** | **PASS** |
+| **Risk Gate Decision Accuracy** | $\ge 95.0\%$ | 44.30% | **99.49%** | **PASS** |
+| **Unsafe Approval Rate** | $\le 2.0\%$ | 34.50% | **0.47%** | **PASS** |
+| **Dispute Impossible Remedy Rate** | $\le 1.0\%$ | 6.50% | **0.19%** | **PASS** |
+| **JSON Schema Validity Rate** | $\ge 98.0\%$ | 82.40% | **100.0%** | **PASS** |
+| **Prompt Injection Recall** | $\ge 85.0\%$ | 42.10% | **89.86%** | **PASS** |
 
 ---
 
-## 🔒 Intended Use & Guardrails
+## ⚠️ Limitations & Verification Scope
 
-* **Deterministic Generation:** The model is trained for exact, non-hallucinated reasoning over verifiable cryptographic and ledger states. Always invoke with `do_sample=False`.
-* **Pre-Settlement Triage:** Designed to automate compliance triage, fee routing, and escrow enforcement on push rails. Real-world deployments should verify cryptographic signatures and sanctions feeds via deterministic tools prior to prompting.
+* **Synthetic Dataset Distribution:** The benchmark and training corpora are synthetically generated from parameterized fraud schemas and common on-chain threat models. Performance on novel, adversarial zero-day prompt structures outside the schema may vary.
+* **External Oracle Dependency:** SRA-RiskGate-4B is a pre-settlement decision layer, not a smart contract formal verifier. It relies on the accuracy of upstream deterministic screening tools (e.g., chain analysis APIs, sanctions lists, and signature verifiers).
+* **Greedy Decoding Required:** Always run inference with `do_sample=False` or `temperature=0.0`. Sampling introduces stochasticity that invalidates JSON schema validity and determinism guarantees.
+* **Agent Boundary Isolation:** In autonomous agent frameworks (such as AgentKit), safety guarantees apply only when `RiskGateActionProvider` is the sole execution provider for transfers.
 
 ---