t402 1.9.0__py3-none-any.whl → 1.10.0__py3-none-any.whl

t402/__init__.py

@@ -1,5 +1,5 @@
 # Package version
-__version__ = "1.7.1"
+__version__ = "1.10.0"
 
 # Re-export commonly used items for convenience
 from t402.common import (
@@ -290,6 +290,7 @@ from t402.fastapi import (
     settle_payment,
 )
 
+
 def hello() -> str:
     return "Hello from t402!"
 

t402/a2a/__init__.py

@@ -0,0 +1,73 @@
+"""A2A (Agent-to-Agent) transport for t402 payments."""
+
+from t402.a2a.types import (
+    T402_A2A_EXTENSION_URI,
+    A2A_EXTENSIONS_HEADER,
+    META_PAYMENT_STATUS,
+    META_PAYMENT_REQUIRED,
+    META_PAYMENT_PAYLOAD,
+    META_PAYMENT_RECEIPTS,
+    META_PAYMENT_ERROR,
+    STATUS_PAYMENT_REQUIRED,
+    STATUS_PAYMENT_REJECTED,
+    STATUS_PAYMENT_SUBMITTED,
+    STATUS_PAYMENT_VERIFIED,
+    STATUS_PAYMENT_COMPLETED,
+    STATUS_PAYMENT_FAILED,
+    A2AMessagePart,
+    A2AMessage,
+    A2ATaskStatus,
+    A2ATask,
+    A2AExtension,
+    A2AAgentCard,
+    A2ASkill,
+)
+from t402.a2a.helpers import (
+    is_payment_required,
+    is_payment_completed,
+    is_payment_failed,
+    get_payment_required,
+    get_payment_receipts,
+    has_payment_payload,
+    extract_payment_payload,
+    create_payment_required_message,
+    create_payment_submission_message,
+    create_payment_completed_message,
+    create_payment_failed_message,
+    create_t402_extension,
+)
+
+__all__ = [
+    "T402_A2A_EXTENSION_URI",
+    "A2A_EXTENSIONS_HEADER",
+    "META_PAYMENT_STATUS",
+    "META_PAYMENT_REQUIRED",
+    "META_PAYMENT_PAYLOAD",
+    "META_PAYMENT_RECEIPTS",
+    "META_PAYMENT_ERROR",
+    "STATUS_PAYMENT_REQUIRED",
+    "STATUS_PAYMENT_REJECTED",
+    "STATUS_PAYMENT_SUBMITTED",
+    "STATUS_PAYMENT_VERIFIED",
+    "STATUS_PAYMENT_COMPLETED",
+    "STATUS_PAYMENT_FAILED",
+    "A2AMessagePart",
+    "A2AMessage",
+    "A2ATaskStatus",
+    "A2ATask",
+    "A2AExtension",
+    "A2AAgentCard",
+    "A2ASkill",
+    "is_payment_required",
+    "is_payment_completed",
+    "is_payment_failed",
+    "get_payment_required",
+    "get_payment_receipts",
+    "has_payment_payload",
+    "extract_payment_payload",
+    "create_payment_required_message",
+    "create_payment_submission_message",
+    "create_payment_completed_message",
+    "create_payment_failed_message",
+    "create_t402_extension",
+]

t402/a2a/helpers.py

@@ -0,0 +1,158 @@
+"""A2A helper functions for t402 payment message handling."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+from t402.a2a.types import (
+    A2AMessage,
+    A2AMessagePart,
+    A2ATask,
+    A2AExtension,
+    META_PAYMENT_ERROR,
+    META_PAYMENT_PAYLOAD,
+    META_PAYMENT_RECEIPTS,
+    META_PAYMENT_REQUIRED,
+    META_PAYMENT_STATUS,
+    STATUS_PAYMENT_COMPLETED,
+    STATUS_PAYMENT_FAILED,
+    STATUS_PAYMENT_REQUIRED,
+    STATUS_PAYMENT_SUBMITTED,
+    STATE_COMPLETED,
+    STATE_FAILED,
+    STATE_INPUT_REQUIRED,
+    T402_A2A_EXTENSION_URI,
+)
+
+
+def is_payment_required(task: A2ATask) -> bool:
+    """Check if a task is in a payment-required state."""
+    if task.status.state != STATE_INPUT_REQUIRED:
+        return False
+    if task.status.message is None or task.status.message.metadata is None:
+        return False
+    return task.status.message.metadata.get(META_PAYMENT_STATUS) == STATUS_PAYMENT_REQUIRED
+
+
+def is_payment_completed(task: A2ATask) -> bool:
+    """Check if a task has completed payment."""
+    if task.status.state != STATE_COMPLETED:
+        return False
+    if task.status.message is None or task.status.message.metadata is None:
+        return False
+    return task.status.message.metadata.get(META_PAYMENT_STATUS) == STATUS_PAYMENT_COMPLETED
+
+
+def is_payment_failed(task: A2ATask) -> bool:
+    """Check if a task has failed payment."""
+    if task.status.state != STATE_FAILED:
+        return False
+    if task.status.message is None or task.status.message.metadata is None:
+        return False
+    return task.status.message.metadata.get(META_PAYMENT_STATUS) == STATUS_PAYMENT_FAILED
+
+
+def get_payment_required(task: A2ATask) -> Optional[Dict[str, Any]]:
+    """Extract payment requirements from a task."""
+    if not is_payment_required(task):
+        return None
+    return task.status.message.metadata.get(META_PAYMENT_REQUIRED)
+
+
+def get_payment_receipts(task: A2ATask) -> Optional[List[Any]]:
+    """Extract payment receipts from a task."""
+    if task.status.message is None or task.status.message.metadata is None:
+        return None
+    return task.status.message.metadata.get(META_PAYMENT_RECEIPTS)
+
+
+def has_payment_payload(msg: A2AMessage) -> bool:
+    """Check if a message contains a payment submission."""
+    if msg.metadata is None:
+        return False
+    return (
+        msg.metadata.get(META_PAYMENT_STATUS) == STATUS_PAYMENT_SUBMITTED
+        and META_PAYMENT_PAYLOAD in msg.metadata
+    )
+
+
+def extract_payment_payload(msg: A2AMessage) -> Optional[Dict[str, Any]]:
+    """Extract a payment payload from a message."""
+    if msg.metadata is None:
+        return None
+    return msg.metadata.get(META_PAYMENT_PAYLOAD)
+
+
+def create_payment_required_message(
+    payment_required: Any,
+    text: str = "Payment is required to complete this request.",
+) -> A2AMessage:
+    """Create an agent message requesting payment."""
+    return A2AMessage(
+        kind="message",
+        role="agent",
+        parts=[A2AMessagePart(kind="text", text=text)],
+        metadata={
+            META_PAYMENT_STATUS: STATUS_PAYMENT_REQUIRED,
+            META_PAYMENT_REQUIRED: payment_required,
+        },
+    )
+
+
+def create_payment_submission_message(
+    payment_payload: Any,
+    text: str = "Here is the payment authorization.",
+) -> A2AMessage:
+    """Create a user message submitting payment."""
+    return A2AMessage(
+        kind="message",
+        role="user",
+        parts=[A2AMessagePart(kind="text", text=text)],
+        metadata={
+            META_PAYMENT_STATUS: STATUS_PAYMENT_SUBMITTED,
+            META_PAYMENT_PAYLOAD: payment_payload,
+        },
+    )
+
+
+def create_payment_completed_message(
+    receipts: Any,
+    text: str = "Payment successful.",
+) -> A2AMessage:
+    """Create an agent message confirming payment."""
+    return A2AMessage(
+        kind="message",
+        role="agent",
+        parts=[A2AMessagePart(kind="text", text=text)],
+        metadata={
+            META_PAYMENT_STATUS: STATUS_PAYMENT_COMPLETED,
+            META_PAYMENT_RECEIPTS: receipts,
+        },
+    )
+
+
+def create_payment_failed_message(
+    receipts: Any,
+    error_code: str,
+    text: str = "Payment failed.",
+) -> A2AMessage:
+    """Create an agent message reporting payment failure."""
+    return A2AMessage(
+        kind="message",
+        role="agent",
+        parts=[A2AMessagePart(kind="text", text=text)],
+        metadata={
+            META_PAYMENT_STATUS: STATUS_PAYMENT_FAILED,
+            META_PAYMENT_ERROR: error_code,
+            META_PAYMENT_RECEIPTS: receipts,
+        },
+    )
+
+
+def create_t402_extension(required: bool = False) -> A2AExtension:
+    """Create a T402 extension declaration for agent cards."""
+    return A2AExtension(
+        uri=T402_A2A_EXTENSION_URI,
+        description="Supports payments using the t402 protocol for on-chain settlement.",
+        required=required,
+    )

t402/a2a/types.py

@@ -0,0 +1,145 @@
+"""A2A transport types for t402 payments."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Dict, List, Optional
+
+# Constants
+T402_A2A_EXTENSION_URI = "https://github.com/google-a2a/a2a-t402/v0.1"
+A2A_EXTENSIONS_HEADER = "X-A2A-Extensions"
+
+# Payment metadata keys
+META_PAYMENT_STATUS = "t402.payment.status"
+META_PAYMENT_REQUIRED = "t402.payment.required"
+META_PAYMENT_PAYLOAD = "t402.payment.payload"
+META_PAYMENT_RECEIPTS = "t402.payment.receipts"
+META_PAYMENT_ERROR = "t402.payment.error"
+
+# Payment status values
+STATUS_PAYMENT_REQUIRED = "payment-required"
+STATUS_PAYMENT_REJECTED = "payment-rejected"
+STATUS_PAYMENT_SUBMITTED = "payment-submitted"
+STATUS_PAYMENT_VERIFIED = "payment-verified"
+STATUS_PAYMENT_COMPLETED = "payment-completed"
+STATUS_PAYMENT_FAILED = "payment-failed"
+
+# Task state values
+STATE_SUBMITTED = "submitted"
+STATE_WORKING = "working"
+STATE_INPUT_REQUIRED = "input-required"
+STATE_COMPLETED = "completed"
+STATE_CANCELED = "canceled"
+STATE_FAILED = "failed"
+STATE_UNKNOWN = "unknown"
+
+
+@dataclass
+class A2AMessagePart:
+    """A message part (text, file, or data)."""
+
+    kind: str
+    text: Optional[str] = None
+    file: Optional[Dict[str, Any]] = None
+    data: Optional[Dict[str, Any]] = None
+
+
+@dataclass
+class A2AMessage:
+    """An A2A message with optional payment metadata."""
+
+    kind: str  # always "message"
+    role: str  # "user" or "agent"
+    parts: List[A2AMessagePart]
+    message_id: Optional[str] = None
+    metadata: Optional[Dict[str, Any]] = None
+
+
+@dataclass
+class A2ATaskStatus:
+    """Current status of an A2A task."""
+
+    state: str
+    message: Optional[A2AMessage] = None
+    timestamp: Optional[str] = None
+
+
+@dataclass
+class A2AArtifact:
+    """Output from a completed task."""
+
+    kind: str
+    name: Optional[str] = None
+    mime_type: Optional[str] = None
+    data: Optional[str] = None
+    uri: Optional[str] = None
+    metadata: Optional[Dict[str, Any]] = None
+
+
+@dataclass
+class A2ATask:
+    """An A2A task with status and history."""
+
+    kind: str  # always "task"
+    id: str
+    status: A2ATaskStatus
+    session_id: Optional[str] = None
+    artifacts: Optional[List[A2AArtifact]] = None
+    history: Optional[List[A2AMessage]] = None
+    metadata: Optional[Dict[str, Any]] = None
+
+
+@dataclass
+class A2AExtension:
+    """An A2A extension declaration."""
+
+    uri: str
+    description: Optional[str] = None
+    required: bool = False
+
+
+@dataclass
+class A2ACapabilities:
+    """A2A agent capabilities."""
+
+    streaming: bool = False
+    push_notifications: bool = False
+    state_transition_history: bool = False
+    extensions: Optional[List[A2AExtension]] = None
+
+
+@dataclass
+class A2AProvider:
+    """Agent provider information."""
+
+    organization: Optional[str] = None
+    url: Optional[str] = None
+
+
+@dataclass
+class A2ASkill:
+    """A2A skill definition."""
+
+    id: str
+    name: str
+    description: Optional[str] = None
+    tags: Optional[List[str]] = None
+    examples: Optional[List[str]] = None
+    input_modes: Optional[List[str]] = None
+    output_modes: Optional[List[str]] = None
+
+
+@dataclass
+class A2AAgentCard:
+    """A2A agent card (service advertisement)."""
+
+    name: str
+    url: str
+    description: Optional[str] = None
+    provider: Optional[A2AProvider] = None
+    version: Optional[str] = None
+    documentation_url: Optional[str] = None
+    capabilities: Optional[A2ACapabilities] = None
+    default_input_modes: Optional[List[str]] = None
+    default_output_modes: Optional[List[str]] = None
+    skills: Optional[List[A2ASkill]] = None

t402/bridge/client.py

@@ -1,6 +1,5 @@
 """USDT0 Bridge Client for LayerZero OFT transfers."""
 
-
 from .constants import (
     DEFAULT_EXTRA_OPTIONS,
     DEFAULT_SLIPPAGE,
@@ -73,7 +72,7 @@ class Usdt0Bridge:
         if not supports_bridging(chain):
             raise ValueError(
                 f'Chain "{chain}" does not support USDT0 bridging. '
-                f'Supported chains: {", ".join(get_bridgeable_chains())}'
+                f"Supported chains: {', '.join(get_bridgeable_chains())}"
             )
 
         self._signer = signer
@@ -107,7 +106,9 @@ class Usdt0Bridge:
             False,
         )
 
-        native_fee = fee[0] if isinstance(fee, (list, tuple)) else fee.get("nativeFee", 0)
+        native_fee = (
+            fee[0] if isinstance(fee, (list, tuple)) else fee.get("nativeFee", 0)
+        )
 
         return BridgeQuote(
             native_fee=int(native_fee),
@@ -139,7 +140,11 @@ class Usdt0Bridge:
             )
         )
 
-        slippage = params.slippage_tolerance if params.slippage_tolerance > 0 else DEFAULT_SLIPPAGE
+        slippage = (
+            params.slippage_tolerance
+            if params.slippage_tolerance > 0
+            else DEFAULT_SLIPPAGE
+        )
         oft_address = get_usdt0_oft_address(params.from_chain)
         send_param = self._build_send_param(
             params.to_chain, params.amount, params.recipient, slippage
@@ -304,7 +309,10 @@ class Usdt0Bridge:
     def _extract_message_guid(self, receipt: BridgeTransactionReceipt) -> str:
         """Extract LayerZero message GUID from OFTSent event logs."""
         for log in receipt.logs:
-            if len(log.topics) >= 2 and log.topics[0].lower() == OFT_SENT_EVENT_TOPIC.lower():
+            if (
+                len(log.topics) >= 2
+                and log.topics[0].lower() == OFT_SENT_EVENT_TOPIC.lower()
+            ):
                 # GUID is the first indexed parameter (topics[1])
                 return log.topics[1]
 

t402/bridge/constants.py

@@ -32,7 +32,7 @@ USDT0_OFT_ADDRESSES: dict[str, str] = {
     "arbitrum": "0xFd086bC7CD5C481DCC9C85ebE478A1C0b69FCbb9",
     "ink": "0x0200C29006150606B650577BBE7B6248F58470c1",
     "berachain": "0x779Ded0c9e1022225f8E0630b35a9b54bE713736",
-    "unichain": "0x588ce4F028D8e7B53B687865d6A67b3A54C75518",
+    "unichain": "0x9151434b16b9763660705744891fA906F660EcC5",
 }
 
 # Network to chain name mapping
@@ -251,7 +251,9 @@ def address_to_bytes32(address: str) -> bytes:
     addr = address.lower().removeprefix("0x")
 
     if len(addr) != 40:
-        raise ValueError(f"Invalid address length: expected 40 hex chars, got {len(addr)}")
+        raise ValueError(
+            f"Invalid address length: expected 40 hex chars, got {len(addr)}"
+        )
 
     try:
         addr_bytes = bytes.fromhex(addr)

t402/bridge/router.py

@@ -199,7 +199,7 @@ class CrossChainPaymentRouter:
             raise ValueError(
                 f'Cannot route payment from "{params.source_chain}" to '
                 f'"{params.destination_chain}". '
-                f'Supported chains: {", ".join(get_bridgeable_chains())}'
+                f"Supported chains: {', '.join(get_bridgeable_chains())}"
             )
 
         if params.amount <= 0:

t402/bridge/scan.py

@@ -206,7 +206,9 @@ class LayerZeroScanClient:
             dst_tx_hash=data.get("dstTxHash"),
             status=LayerZeroMessageStatus(data.get("status") or "INFLIGHT"),
             src_block_number=int(data.get("srcBlockNumber") or 0),
-            dst_block_number=int(data.get("dstBlockNumber")) if data.get("dstBlockNumber") else None,
+            dst_block_number=int(data.get("dstBlockNumber"))
+            if data.get("dstBlockNumber")
+            else None,
             created=data.get("created") or data.get("createdAt") or "",
             updated=data.get("updated") or data.get("updatedAt") or "",
         )