botchain-sdk-py 0.1.0__py3-none-any.whl

botchain/__init__.py

@@ -0,0 +1,18 @@
+from .client import BotChain
+from .exceptions import BotChainLogsDisabledError
+from .dex import BDexManager
+from .tokens import TokenManager
+from .middleware import botchain_paymaster_middleware, check_and_apply_sponsorship
+from .agents import AgentTradePolicy, AgentExecutor
+
+__all__ = [
+    "BotChain",
+    "BotChainLogsDisabledError",
+    "BDexManager",
+    "TokenManager",
+    "botchain_paymaster_middleware",
+    "check_and_apply_sponsorship",
+    "AgentTradePolicy",
+    "AgentExecutor"
+]
+

botchain/agents/__init__.py

@@ -0,0 +1,4 @@
+from .policy import AgentTradePolicy
+from .executor import AgentExecutor
+
+__all__ = ["AgentTradePolicy", "AgentExecutor"]

botchain/agents/executor.py

@@ -0,0 +1,92 @@
+import logging
+import time
+from typing import Optional
+from web3 import Web3
+from .policy import AgentTradePolicy
+from ..middleware import check_and_apply_sponsorship
+
+logger = logging.getLogger(__name__)
+
+class AgentExecutor:
+    """
+    Guarded transaction execution engine for AI Agents.
+    Validates trade intents against AgentTradePolicy, performs pre-flight eth_call simulations,
+    and handles zero-gas Paymaster sponsorship before signing & broadcasting.
+    """
+    def __init__(self, botclient, policy: AgentTradePolicy):
+        self.client = botclient
+        self.w3 = botclient.w3
+        self.policy = policy
+
+    def execute_trade(
+        self,
+        dex_manager,
+        token_in: str,
+        token_out: str,
+        amount_in: int,
+        fee: int = 3000,
+        slippage_tolerance: float = 0.01,
+        recipient: Optional[str] = None,
+        notional_usd: Optional[float] = None
+    ) -> str:
+        """
+        Validates, simulates, sponsors, and executes a single-hop BDEX trade.
+        """
+        if not self.client.account:
+            raise ValueError("Local account required to execute agent trades.")
+
+        target_recipient = recipient or self.client.account.address
+        router_address = dex_manager.router_contract.address
+
+        # 1. Policy Validation
+        self.policy.validate_trade(
+            token_in=token_in,
+            token_out=token_out,
+            router=router_address,
+            amount_in=amount_in,
+            slippage=slippage_tolerance,
+            notional_usd=notional_usd
+        )
+
+        # 2. Get Quote & Calculate minimum output
+        expected_out = dex_manager.get_quote(token_in, token_out, amount_in, fee)
+        amount_out_minimum = int(expected_out * (1 - slippage_tolerance))
+
+        # 3. Build Transaction Dictionary
+        params = {
+            "tokenIn": self.w3.to_checksum_address(token_in),
+            "tokenOut": self.w3.to_checksum_address(token_out),
+            "fee": fee,
+            "recipient": self.w3.to_checksum_address(target_recipient),
+            "deadline": int(time.time()) + 600,
+            "amountIn": amount_in,
+            "amountOutMinimum": amount_out_minimum,
+            "sqrtPriceLimitX96": 0
+        }
+
+        tx_dict = dex_manager.router_contract.functions.exactInputSingle(params).build_transaction({
+            'from': self.client.account.address,
+            'nonce': self.w3.eth.get_transaction_count(self.client.account.address),
+            'chainId': self.client.chain_id,
+        })
+
+        # 4. Pre-Flight Simulation (eth_call)
+        try:
+            logger.info("Executing pre-flight transaction simulation via eth_call...")
+            self.w3.eth.call(tx_dict)
+            logger.info("Pre-flight simulation successful.")
+        except Exception as e:
+            logger.error(f"Pre-flight simulation failed: {e}")
+            raise RuntimeError(f"Transaction pre-flight simulation failed: {e}") from e
+
+        # 5. Zero-Gas Paymaster Sponsorship Check
+        tx_dict = check_and_apply_sponsorship(self.w3, tx_dict)
+
+        # 6. Sign and Broadcast Transaction
+        signed_tx = self.w3.eth.account.sign_transaction(tx_dict, private_key=self.client.account.key)
+        tx_hash = self.w3.eth.send_raw_transaction(signed_tx.rawTransaction)
+
+        # 7. Record trade in policy state upon success
+        self.policy.record_trade()
+
+        return self.w3.to_hex(tx_hash)

botchain/agents/mcp.py

@@ -0,0 +1,3 @@
+from .tools.mcp_server import BotChainMCPServer
+
+__all__ = ["BotChainMCPServer"]

botchain/agents/mcp_server.py

@@ -0,0 +1,18 @@
+import sys
+from botchain.client import BotChain
+from botchain.agents.executor import AgentExecutor
+from botchain.agents.policy import AgentTradePolicy
+from botchain.agents.tools.mcp_server import BotChainMCPServer
+
+def main():
+    """Entry point for botchain-mcp server."""
+    # Simple setup for MCP
+    client = BotChain()
+    policy = AgentTradePolicy()
+    executor = AgentExecutor(policy)
+    
+    server = BotChainMCPServer(client, executor)
+    server.run_stdio()
+
+if __name__ == "__main__":
+    main()

botchain/agents/policy.py

@@ -0,0 +1,102 @@
+import time
+from typing import List, Optional, Set
+from web3 import Web3
+
+class AgentTradePolicy:
+    """
+    Safety Policy Engine for AI Agents executing trades on BOT Chain.
+    Enforces spending caps, rate limits, cooldowns, and asset allowlists.
+    """
+    def __init__(
+        self,
+        allowed_tokens: Optional[List[str]] = None,
+        allowed_routers: Optional[List[str]] = None,
+        max_slippage_tolerance: float = 0.05,
+        max_notional_usd: Optional[float] = 1000.0,
+        cooldown_seconds: float = 10.0,
+        max_trades_per_hour: int = 10
+    ):
+        self.allowed_tokens: Optional[Set[str]] = (
+            {Web3.to_checksum_address(t) for t in allowed_tokens} if allowed_tokens else None
+        )
+        self.allowed_routers: Optional[Set[str]] = (
+            {Web3.to_checksum_address(r) for r in allowed_routers} if allowed_routers else None
+        )
+        self.max_slippage_tolerance = max_slippage_tolerance
+        self.max_notional_usd = max_notional_usd
+        self.cooldown_seconds = cooldown_seconds
+        self.max_trades_per_hour = max_trades_per_hour
+
+        # Internal tracking state
+        self.last_trade_time: Optional[float] = None
+        self.trade_timestamps: List[float] = []
+
+    def validate_trade(
+        self,
+        token_in: str,
+        token_out: str,
+        router: Optional[str] = None,
+        amount_in: int = 0,
+        slippage: float = 0.01,
+        notional_usd: Optional[float] = None,
+        current_time: Optional[float] = None
+    ) -> None:
+        """
+        Validates trade parameters against policy rules.
+        Raises ValueError if any rule is violated.
+        """
+        now = current_time if current_time is not None else time.time()
+
+        # 1. Token Allowlist Verification
+        checksum_in = Web3.to_checksum_address(token_in)
+        checksum_out = Web3.to_checksum_address(token_out)
+
+        if self.allowed_tokens is not None:
+            if checksum_in not in self.allowed_tokens:
+                raise ValueError(f"Token IN ({token_in}) is not in the allowed tokens list.")
+            if checksum_out not in self.allowed_tokens:
+                raise ValueError(f"Token OUT ({token_out}) is not in the allowed tokens list.")
+
+        # 2. Router Allowlist Verification
+        if router and self.allowed_routers is not None:
+            checksum_router = Web3.to_checksum_address(router)
+            if checksum_router not in self.allowed_routers:
+                raise ValueError(f"Router ({router}) is not in the allowed routers list.")
+
+        # 3. Slippage Limit Verification
+        if slippage > self.max_slippage_tolerance:
+            raise ValueError(
+                f"Requested slippage ({slippage:.4f}) exceeds maximum allowed tolerance ({self.max_slippage_tolerance:.4f})."
+            )
+
+        # 4. Notional USD Cap Verification
+        if self.max_notional_usd is not None and notional_usd is not None:
+            if notional_usd > self.max_notional_usd:
+                raise ValueError(
+                    f"Trade value (${notional_usd:.2f}) exceeds maximum notional USD cap (${self.max_notional_usd:.2f})."
+                )
+
+        # 5. Cooldown Verification
+        if self.last_trade_time is not None:
+            elapsed = now - self.last_trade_time
+            if elapsed < self.cooldown_seconds:
+                remaining = self.cooldown_seconds - elapsed
+                raise ValueError(
+                    f"Trade cooldown active. Please wait {remaining:.2f} seconds before trading again."
+                )
+
+        # 6. Hourly Rate Limit Verification
+        # Filter timestamps to only keep trades within the last 3600 seconds (1 hour)
+        self.trade_timestamps = [t for t in self.trade_timestamps if now - t < 3600]
+        if len(self.trade_timestamps) >= self.max_trades_per_hour:
+            raise ValueError(
+                f"Hourly trade limit reached ({self.max_trades_per_hour} trades/hour)."
+            )
+
+    def record_trade(self, timestamp: Optional[float] = None) -> None:
+        """
+        Records a successfully executed trade timestamp.
+        """
+        now = timestamp if timestamp is not None else time.time()
+        self.last_trade_time = now
+        self.trade_timestamps.append(now)

botchain/agents/tools/__init__.py

@@ -0,0 +1,3 @@
+from .schemas import BOTCHAIN_TOOL_SCHEMAS, get_openai_tool_definitions
+
+__all__ = ["BOTCHAIN_TOOL_SCHEMAS", "get_openai_tool_definitions"]

botchain/agents/tools/base.py

@@ -0,0 +1,32 @@
+from botchain.tokens import TokenManager
+from botchain.dex import BDexManager
+from botchain.agents.executor import AgentExecutor
+
+def botchain_get_balance(client, token_address: str, account_address: str = None) -> int:
+    token_manager = TokenManager(client)
+    return token_manager.get_balance(token_address, account_address)
+
+def botchain_get_quote(client, token_in: str, token_out: str, amount_in: int, fee: int = 3000) -> int:
+    dex_manager = BDexManager(client)
+    return dex_manager.get_quote(token_in, token_out, amount_in, fee)
+
+def botchain_execute_swap(
+    client, 
+    executor: AgentExecutor, 
+    token_in: str, 
+    token_out: str, 
+    amount_in: int, 
+    fee: int = 3000, 
+    slippage_tolerance: float = 0.01,
+    notional_usd: float = None
+) -> str:
+    dex_manager = BDexManager(client)
+    return executor.execute_trade(
+        dex_manager=dex_manager,
+        token_in=token_in,
+        token_out=token_out,
+        amount_in=amount_in,
+        fee=fee,
+        slippage_tolerance=slippage_tolerance,
+        notional_usd=notional_usd
+    )

botchain/agents/tools/mcp_server.py

@@ -0,0 +1,115 @@
+import sys
+import json
+import logging
+from botchain.agents.tools.base import botchain_get_balance, botchain_get_quote, botchain_execute_swap
+from botchain.agents.tools.schemas import BOTCHAIN_TOOL_SCHEMAS
+
+logger = logging.getLogger(__name__)
+
+class BotChainMCPServer:
+    """
+    Model Context Protocol (MCP) Server for BOT Chain Tools.
+    Listens on stdio for JSON-RPC 2.0 requests.
+    """
+    def __init__(self, client, executor):
+        self.client = client
+        self.executor = executor
+        
+        # Tools map
+        self.tools = {
+            "botchain_get_balance": self.handle_get_balance,
+            "botchain_get_quote": self.handle_get_quote,
+            "botchain_execute_swap": self.handle_execute_swap
+        }
+
+    def handle_get_balance(self, params):
+        return botchain_get_balance(
+            self.client, 
+            params.get("token_address"), 
+            params.get("account_address")
+        )
+
+    def handle_get_quote(self, params):
+        return botchain_get_quote(
+            self.client,
+            params.get("token_in"),
+            params.get("token_out"),
+            params.get("amount_in"),
+            params.get("fee", 3000)
+        )
+
+    def handle_execute_swap(self, params):
+        return botchain_execute_swap(
+            self.client,
+            self.executor,
+            params.get("token_in"),
+            params.get("token_out"),
+            params.get("amount_in"),
+            params.get("fee", 3000),
+            params.get("slippage_tolerance", 0.01),
+            params.get("notional_usd")
+        )
+
+    def process_request(self, request_str: str) -> str:
+        try:
+            req = json.loads(request_str)
+            if not isinstance(req, dict) or "jsonrpc" not in req:
+                return json.dumps({"jsonrpc": "2.0", "error": {"code": -32600, "message": "Invalid Request"}, "id": None})
+            
+            req_id = req.get("id")
+            method = req.get("method")
+            params = req.get("params", {})
+            
+            # MCP Tool Discovery
+            if method == "tools/list":
+                return json.dumps({
+                    "jsonrpc": "2.0",
+                    "id": req_id,
+                    "result": {
+                        "tools": BOTCHAIN_TOOL_SCHEMAS
+                    }
+                })
+            
+            # MCP Tool Call
+            if method == "tools/call":
+                tool_name = params.get("name")
+                tool_args = params.get("arguments", {})
+                
+                if tool_name not in self.tools:
+                    return json.dumps({
+                        "jsonrpc": "2.0",
+                        "id": req_id,
+                        "error": {"code": -32601, "message": f"Method not found: {tool_name}"}
+                    })
+                
+                try:
+                    result = self.tools[tool_name](tool_args)
+                    return json.dumps({
+                        "jsonrpc": "2.0",
+                        "id": req_id,
+                        "result": {
+                            "content": [{"type": "text", "text": str(result)}]
+                        }
+                    })
+                except Exception as e:
+                    return json.dumps({
+                        "jsonrpc": "2.0",
+                        "id": req_id,
+                        "error": {"code": -32000, "message": str(e)}
+                    })
+            
+            return json.dumps({
+                "jsonrpc": "2.0",
+                "id": req_id,
+                "error": {"code": -32601, "message": "Method not found"}
+            })
+
+        except json.JSONDecodeError:
+            return json.dumps({"jsonrpc": "2.0", "error": {"code": -32700, "message": "Parse error"}, "id": None})
+
+    def run_stdio(self):
+        """Runs the MCP server over standard input/output."""
+        for line in sys.stdin:
+            response = self.process_request(line)
+            sys.stdout.write(response + "\n")
+            sys.stdout.flush()

botchain/agents/tools/schemas.py

@@ -0,0 +1,97 @@
+"""
+Standardized JSON schemas for LLM Function Calling (OpenAI, Gemini, Anthropic, MCP).
+"""
+
+BOTCHAIN_TOOL_SCHEMAS = [
+    {
+        "name": "botchain_get_balance",
+        "description": "Get the token balance (native BOT or ERC20/WBOT) for a given account address on BOT Chain.",
+        "parameters": {
+            "type": "object",
+            "properties": {
+                "token_address": {
+                    "type": "string",
+                    "description": "The contract address of the ERC20 token, or 'NATIVE' / 'WBOT' for BOT Chain native assets."
+                },
+                "account_address": {
+                    "type": "string",
+                    "description": "Optional 0x-prefixed account address. Defaults to the connected agent wallet."
+                }
+            },
+            "required": ["token_address"]
+        }
+    },
+    {
+        "name": "botchain_get_quote",
+        "description": "Query BDEX V3 for the expected output amount for a single-hop token swap.",
+        "parameters": {
+            "type": "object",
+            "properties": {
+                "token_in": {
+                    "type": "string",
+                    "description": "The checksummed contract address of the input token."
+                },
+                "token_out": {
+                    "type": "string",
+                    "description": "The checksummed contract address of the output token."
+                },
+                "amount_in": {
+                    "type": "integer",
+                    "description": "Amount of token_in in base units (wei)."
+                },
+                "fee": {
+                    "type": "integer",
+                    "description": "Pool fee tier in hundredths of a bip (default 3000 for 0.3%).",
+                    "default": 3000
+                }
+            },
+            "required": ["token_in", "token_out", "amount_in"]
+        }
+    },
+    {
+        "name": "botchain_execute_swap",
+        "description": "Executes a policy-guarded single-hop token swap on BDEX with pre-flight simulation and optional zero-gas Paymaster sponsorship.",
+        "parameters": {
+            "type": "object",
+            "properties": {
+                "token_in": {
+                    "type": "string",
+                    "description": "Checksummed address of the token to sell."
+                },
+                "token_out": {
+                    "type": "string",
+                    "description": "Checksummed address of the token to buy."
+                },
+                "amount_in": {
+                    "type": "integer",
+                    "description": "Amount of token_in to sell in base units."
+                },
+                "fee": {
+                    "type": "integer",
+                    "description": "Pool fee tier (e.g. 3000 for 0.3%).",
+                    "default": 3000
+                },
+                "slippage_tolerance": {
+                    "type": "number",
+                    "description": "Maximum allowed price slippage (e.g., 0.01 for 1%).",
+                    "default": 0.01
+                },
+                "notional_usd": {
+                    "type": "number",
+                    "description": "Estimated USD value of the trade for policy cap verification."
+                }
+            },
+            "required": ["token_in", "token_out", "amount_in"]
+        }
+    }
+]
+
+def get_openai_tool_definitions():
+    """Returns schemas wrapped in OpenAI function tool format."""
+    return [
+        {
+            "type": "function",
+            "function": schema
+        }
+        for schema in BOTCHAIN_TOOL_SCHEMAS
+    ]

botchain/client.py

@@ -0,0 +1,82 @@
+from web3 import Web3
+from web3.middleware import ExtraDataToPOAMiddleware
+from eth_account import Account
+from .exceptions import BotChainLogsDisabledError
+
+class BotChain:
+    # Network Constants
+    MAINNET_RPC = "https://rpc.botchain.ai"
+    MAINNET_CHAIN_ID = 677
+    
+    TESTNET_RPC = "https://rpc.bohr.life"
+    TESTNET_CHAIN_ID = 968
+
+    def __init__(self, private_key: str = None, is_testnet: bool = False, custom_rpc: str = None):
+        """
+        Initializes the BOT Chain Web3 client.
+        """
+        self.is_testnet = is_testnet
+        self.chain_id = self.TESTNET_CHAIN_ID if is_testnet else self.MAINNET_CHAIN_ID
+        self.rpc_url = custom_rpc or (self.TESTNET_RPC if is_testnet else self.MAINNET_RPC)
+        
+        # Initialize the underlying Web3 HTTP Provider
+        self.w3 = Web3(Web3.HTTPProvider(self.rpc_url))
+        
+        self._inject_poa_middleware()
+        self._configure_account(private_key)
+        self._protect_rpc_methods()
+
+    def _inject_poa_middleware(self):
+        """
+        Injects the geth_poa_middleware to handle BOT Chain's Parlia consensus block headers.
+        Must be added to layer 0.
+        """
+        self.w3.middleware_onion.inject(ExtraDataToPOAMiddleware, layer=0)
+
+    def _configure_account(self, private_key: str):
+        """
+        Sets up the local EOA for transaction signing.
+        """
+        self.account = None
+        if private_key:
+            self.account = Account.from_key(private_key)
+            self.w3.eth.default_account = self.account.address
+
+    def _protect_rpc_methods(self):
+        """
+        Wraps standard web3 methods to enforce BOT Chain architectural constraints.
+        """
+        original_get_logs = self.w3.eth.get_logs
+
+        def safe_get_logs(*args, **kwargs):
+            # If using the default mainnet RPC, block the call
+            if not self.is_testnet and self.rpc_url == self.MAINNET_RPC:
+                raise BotChainLogsDisabledError()
+            return original_get_logs(*args, **kwargs)
+
+        # Override the method
+        self.w3.eth.get_logs = safe_get_logs
+
+    def build_transaction(self, to: str, data: str = "0x", value: int = 0) -> dict:
+        """
+        Helper to construct a base transaction dictionary ready for signing or Paymaster middleware.
+        """
+        if not self.account:
+            raise ValueError("Private key must be provided to build transactions.")
+
+        tx = {
+            'chainId': self.chain_id,
+            'from': self.account.address,
+            'to': self.w3.to_checksum_address(to),
+            'value': value,
+            'data': data,
+            'nonce': self.w3.eth.get_transaction_count(self.account.address),
+            # Gas estimation will be handled by the user or the Web3 provider
+        }
+        return tx
+
+    def enable_zero_gas_paymaster(self):
+        """Injects the MegaFuel EOA Paymaster middleware."""
+        from .middleware import botchain_paymaster_middleware
+        self.w3.middleware_onion.inject(botchain_paymaster_middleware, name="botchain_paymaster", layer=0)
+

botchain/contracts.py

@@ -0,0 +1,8 @@
+MAINNET_ADDRESSES = {
+    "BDEX_V3_FACTORY": "0x1C51c173323ec11BB4e3C4fD2314c225Dc4b5419",
+    "BDEX_SWAP_ROUTER": "0x07032d47A1b9f8460cBeE9dC17c1d3E438693929",
+    "BDEX_QUOTER_V2": "0x034A705b36067cff99ABf5C662Be881cBd8d0176",
+    "NONFUNGIBLE_POSITION_MANAGER": "0xDAc3FcFF004d8a8675b94E44941A1a2e3b240090",
+    "WBOT": "0xD5452816194a3784dBa983426cCe7c122F4abd30",
+    "USDT": "0xaBabc7Ddc03e501d190C676BF3d92ef0e6e87a3C",
+}

botchain/dex.py

@@ -0,0 +1,189 @@
+import json
+import time
+import os
+from web3 import Web3
+from .contracts import MAINNET_ADDRESSES
+
+def get_tick_spacing(fee: int) -> int:
+    """Returns the tick spacing for a given fee tier."""
+    if fee == 100:
+        return 1
+    elif fee == 500:
+        return 10
+    elif fee == 3000:
+        return 60
+    elif fee == 10000:
+        return 200
+    return 60
+
+def calculate_ticks(current_tick: int, tick_spacing: int, range_percentage: float) -> tuple[int, int]:
+    """Calculates a tick range snapped to exact multiples of tick_spacing."""
+    tick_delta = int(range_percentage * 10000) 
+    tick_lower = current_tick - tick_delta
+    tick_upper = current_tick + tick_delta
+    
+    tick_lower = (tick_lower // tick_spacing) * tick_spacing
+    tick_upper = (tick_upper // tick_spacing) * tick_spacing
+    return tick_lower, tick_upper
+
+class BDexManager:
+    def __init__(self, botclient):
+        self.client = botclient
+        self.w3 = botclient.w3
+        
+        self.router_abi = self._load_abi("SwapRouter.json")
+        self.router_contract = self.w3.eth.contract(
+            address=self.w3.to_checksum_address(MAINNET_ADDRESSES["BDEX_SWAP_ROUTER"]), 
+            abi=self.router_abi
+        )
+        
+        self.quoter_abi = self._load_abi("QuoterV2.json")
+        self.quoter_contract = self.w3.eth.contract(
+            address=self.w3.to_checksum_address(MAINNET_ADDRESSES["BDEX_QUOTER_V2"]),
+            abi=self.quoter_abi
+        )
+        
+        self.nft_manager_abi = self._load_abi("NonFungiblePositionManager.json")
+        self.nft_manager_contract = self.w3.eth.contract(
+            address=self.w3.to_checksum_address(MAINNET_ADDRESSES["NONFUNGIBLE_POSITION_MANAGER"]),
+            abi=self.nft_manager_abi
+        )
+
+    def _load_abi(self, filename: str):
+        # Assumes ABIs are in an 'abis' directory at the project root
+        abi_path = os.path.join(os.path.dirname(__file__), "..", "..", "abis", filename)
+        if not os.path.exists(abi_path):
+            raise FileNotFoundError(f"ABI file not found: {abi_path}")
+        with open(abi_path, 'r') as f:
+            return json.load(f)
+
+    def get_quote(self, token_in: str, token_out: str, amount_in: int, fee: int = 3000) -> int:
+        """Queries QuoterV2 for expected output amount."""
+        params = {
+            "tokenIn": self.w3.to_checksum_address(token_in),
+            "tokenOut": self.w3.to_checksum_address(token_out),
+            "amountIn": amount_in,
+            "fee": fee,
+            "sqrtPriceLimitX96": 0
+        }
+        # QuoterV2 quoteExactInputSingle returns (amountOut, sqrtPriceX96After, initializedTicksCrossed, gasEstimate)
+        quote = self.quoter_contract.functions.quoteExactInputSingle(params).call()
+        return quote[0]
+
+    def swap_exact_input_single(self, token_in: str, token_out: str, amount_in: int, fee: int = 3000, slippage_tolerance: float = 0.01, recipient: str = None):
+        """Executes a single-hop swap with slippage protection."""
+        if not self.client.account:
+            raise ValueError("Local account required for swaps.")
+            
+        if not recipient:
+            recipient = self.client.account.address
+            
+        # 1. Get Quote
+        expected_out = self.get_quote(token_in, token_out, amount_in, fee)
+        
+        # 2. Apply Slippage
+        amount_out_minimum = int(expected_out * (1 - slippage_tolerance))
+
+        # 3. Build Swap Params
+        params = {
+            "tokenIn": self.w3.to_checksum_address(token_in),
+            "tokenOut": self.w3.to_checksum_address(token_out),
+            "fee": fee,
+            "recipient": self.w3.to_checksum_address(recipient),
+            "deadline": int(time.time()) + 600,
+            "amountIn": amount_in,
+            "amountOutMinimum": amount_out_minimum,
+            "sqrtPriceLimitX96": 0
+        }
+        
+        # 4. Build and Send Transaction
+        tx = self.router_contract.functions.exactInputSingle(params).build_transaction({
+            'from': self.client.account.address,
+            'nonce': self.w3.eth.get_transaction_count(self.client.account.address),
+            'chainId': self.client.chain_id,
+        })
+        
+        signed_tx = self.w3.eth.account.sign_transaction(tx, private_key=self.client.account.key)
+        tx_hash = self.w3.eth.send_raw_transaction(signed_tx.rawTransaction)
+        
+        return self.w3.to_hex(tx_hash)
+
+    def mint_position(self, token0: str, token1: str, fee: int, amount0_desired: int, amount1_desired: int, tick_lower: int, tick_upper: int, slippage_tolerance: float = 0.01):
+        if not self.client.account:
+            raise ValueError("Local account required.")
+        
+        params = {
+            "token0": self.w3.to_checksum_address(token0),
+            "token1": self.w3.to_checksum_address(token1),
+            "fee": fee,
+            "tickLower": tick_lower,
+            "tickUpper": tick_upper,
+            "amount0Desired": amount0_desired,
+            "amount1Desired": amount1_desired,
+            "amount0Min": int(amount0_desired * (1 - slippage_tolerance)),
+            "amount1Min": int(amount1_desired * (1 - slippage_tolerance)),
+            "recipient": self.client.account.address,
+            "deadline": int(time.time()) + 600
+        }
+        
+        tx = self.nft_manager_contract.functions.mint(params).build_transaction({
+            'from': self.client.account.address,
+            'nonce': self.w3.eth.get_transaction_count(self.client.account.address),
+            'chainId': self.client.chain_id,
+        })
+        
+        signed_tx = self.w3.eth.account.sign_transaction(tx, private_key=self.client.account.key)
+        tx_hash = self.w3.eth.send_raw_transaction(signed_tx.rawTransaction)
+        return self.w3.to_hex(tx_hash)
+
+    def collect_fees(self, token_id: int):
+        if not self.client.account:
+            raise ValueError("Local account required.")
+            
+        params = {
+            "tokenId": token_id,
+            "recipient": self.client.account.address,
+            "amount0Max": 2**128 - 1,
+            "amount1Max": 2**128 - 1
+        }
+        
+        tx = self.nft_manager_contract.functions.collect(params).build_transaction({
+            'from': self.client.account.address,
+            'nonce': self.w3.eth.get_transaction_count(self.client.account.address),
+            'chainId': self.client.chain_id,
+        })
+        
+        signed_tx = self.w3.eth.account.sign_transaction(tx, private_key=self.client.account.key)
+        tx_hash = self.w3.eth.send_raw_transaction(signed_tx.rawTransaction)
+        return self.w3.to_hex(tx_hash)
+
+    def decrease_liquidity(self, token_id: int, liquidity_percentage: float):
+        if not self.client.account:
+            raise ValueError("Local account required.")
+            
+        try:
+            position = self.nft_manager_contract.functions.positions(token_id).call()
+            current_liquidity = position[7]
+        except Exception:
+            current_liquidity = 1000000 
+            
+        liquidity_to_remove = int(current_liquidity * liquidity_percentage)
+        
+        params = {
+            "tokenId": token_id,
+            "liquidity": liquidity_to_remove,
+            "amount0Min": 0,
+            "amount1Min": 0,
+            "deadline": int(time.time()) + 600
+        }
+        
+        tx = self.nft_manager_contract.functions.decreaseLiquidity(params).build_transaction({
+            'from': self.client.account.address,
+            'nonce': self.w3.eth.get_transaction_count(self.client.account.address),
+            'chainId': self.client.chain_id,
+        })
+        
+        signed_tx = self.w3.eth.account.sign_transaction(tx, private_key=self.client.account.key)
+        tx_hash = self.w3.eth.send_raw_transaction(signed_tx.rawTransaction)
+        return self.w3.to_hex(tx_hash)
+

botchain/dex_alm.py

@@ -0,0 +1,129 @@
+import math
+from typing import Tuple
+from .dex import BDexManager
+from .tokens import TokenManager
+
+class ALMExecutionError(Exception):
+    """
+    Raised when an ALM rebalance fails mid-sequence.
+    Includes stranded balances so calling agents can recover.
+    """
+    def __init__(self, message: str, stranded_amount0: int, stranded_amount1: int):
+        super().__init__(message)
+        self.stranded_amount0 = stranded_amount0
+        self.stranded_amount1 = stranded_amount1
+
+class ALMMath:
+    @staticmethod
+    def tick_to_sqrt_price_x96(tick: int) -> int:
+        """Calculates sqrt(1.0001^tick) * 2^96"""
+        # In python, math.sqrt(1.0001**tick) can overflow for very large ticks, 
+        # but is fine for normal ranges.
+        return int(math.sqrt(1.0001 ** tick) * (2 ** 96))
+
+    @staticmethod
+    def snap_tick_to_spacing(tick: int, tick_spacing: int) -> int:
+        """Enforces exact multiples of tick_spacing."""
+        return (tick // tick_spacing) * tick_spacing
+
+    @staticmethod
+    def calculate_ideal_swap(current_tick: int, tick_lower: int, tick_upper: int, amount0_total: int, amount1_total: int) -> Tuple[bool, int]:
+        """
+        Uses ratio r = (sqrt_pb - sqrt_p) / (sqrt_p * sqrt_pb * (sqrt_p - sqrt_pa))
+        Returns (is_swap_token0_for_token1, amount_to_swap).
+        """
+        if current_tick <= tick_lower:
+            return (False, amount1_total)
+        if current_tick >= tick_upper:
+            return (True, amount0_total)
+
+        sqrt_p = ALMMath.tick_to_sqrt_price_x96(current_tick) / (2**96)
+        sqrt_pa = ALMMath.tick_to_sqrt_price_x96(tick_lower) / (2**96)
+        sqrt_pb = ALMMath.tick_to_sqrt_price_x96(tick_upper) / (2**96)
+
+        # r is the ratio of token1 / token0 required for the new position
+        # r = (sqrt_pb - sqrt_p) / (sqrt_p * sqrt_pb * (sqrt_p - sqrt_pa))
+        # actually Uniswap V3 formula is:
+        # Lx = amount0 * sqrt_p * sqrt_pb / (sqrt_pb - sqrt_p)
+        # Ly = amount1 / (sqrt_p - sqrt_pa)
+        # Equating Lx = Ly gives:
+        # amount1 / amount0 = (sqrt_p * sqrt_pb * (sqrt_p - sqrt_pa)) / (sqrt_pb - sqrt_p)
+        # Wait, the user specified r = (sqrt_pb - sqrt_p) / (sqrt_p * sqrt_pb * (sqrt_p - sqrt_pa))
+        # which is the inverse: amount0 / amount1. Let's use the user's ratio directly.
+        r = (sqrt_pb - sqrt_p) / (sqrt_p * sqrt_pb * (sqrt_p - sqrt_pa))
+        
+        current_price = sqrt_p * sqrt_p
+        
+        # total_value_in_token0 = amount0_total + (amount1_total / current_price)
+        # We need amount0_target / amount1_target = r  => amount0_target = r * amount1_target
+        # And value remains constant (ignoring fee):
+        # amount0_target + amount1_target / current_price = amount0_total + amount1_total / current_price
+        
+        total_value_in_token1 = (amount0_total * current_price) + amount1_total
+        # amount1_target + (amount0_target * current_price) = total_value_in_token1
+        # amount1_target + (r * amount1_target * current_price) = total_value_in_token1
+        amount1_target = total_value_in_token1 / (1 + r * current_price)
+        amount0_target = r * amount1_target
+        
+        if amount0_total > amount0_target:
+            swap_amount0 = amount0_total - amount0_target
+            return (True, int(swap_amount0))
+        else:
+            swap_amount1 = amount1_total - amount1_target
+            return (False, int(swap_amount1))
+
+class ALMManager:
+    def __init__(self, dex_manager: BDexManager):
+        self.dex = dex_manager
+        
+    def execute_optimal_rebalance(
+        self, 
+        token_id: int, 
+        token0: str, 
+        token1: str, 
+        fee: int, 
+        current_tick: int, 
+        tick_spacing: int, 
+        range_percentage: float
+    ):
+        # TODO: Future versions will migrate this sequence to atomic execution using 
+        # the native BOT Chain Multicall3 contract deployed at 0x9ada8A64657bE15a85C435906AF3f34b83D261cB
+        
+        try:
+            # Step 1: Withdraw 100% liquidity
+            self.dex.decrease_liquidity(token_id, 1.0)
+            
+            # Step 2: Collect fees
+            self.dex.collect_fees(token_id)
+        except Exception as e:
+            raise ALMExecutionError(f"Failed to withdraw liquidity or collect fees: {str(e)}", 0, 0)
+            
+        token_manager = TokenManager(self.dex.client)
+        amount0_total = token_manager.get_balance(token0, self.dex.client.account.address)
+        amount1_total = token_manager.get_balance(token1, self.dex.client.account.address)
+
+        try:
+            # Step 3: Calculate and Execute Swap
+            tick_lower = ALMMath.snap_tick_to_spacing(int(current_tick - (range_percentage * 10000)), tick_spacing)
+            tick_upper = ALMMath.snap_tick_to_spacing(int(current_tick + (range_percentage * 10000)), tick_spacing)
+            
+            is_swap_0_to_1, swap_amount = ALMMath.calculate_ideal_swap(current_tick, tick_lower, tick_upper, amount0_total, amount1_total)
+            
+            if swap_amount > 0:
+                if is_swap_0_to_1:
+                    self.dex.swap_exact_input_single(token0, token1, swap_amount, fee)
+                else:
+                    self.dex.swap_exact_input_single(token1, token0, swap_amount, fee)
+            
+            # Update balances after swap
+            new_amount0 = token_manager.get_balance(token0, self.dex.client.account.address)
+            new_amount1 = token_manager.get_balance(token1, self.dex.client.account.address)
+            
+            # Step 4: Mint new position
+            self.dex.mint_position(token0, token1, fee, new_amount0, new_amount1, tick_lower, tick_upper)
+            
+        except Exception as e:
+            # Python-level State Recovery Strategy
+            stranded0 = token_manager.get_balance(token0, self.dex.client.account.address)
+            stranded1 = token_manager.get_balance(token1, self.dex.client.account.address)
+            raise ALMExecutionError(f"Rebalance failed during swap or mint: {str(e)}", stranded0, stranded1)

botchain/exceptions.py

@@ -0,0 +1,7 @@
+class BotChainLogsDisabledError(Exception):
+    """Raised when a user attempts to call eth_getLogs on the public mainnet RPC."""
+    def __init__(self):
+        super().__init__(
+            "eth_getLogs is disabled on the public mainnet RPC (https://rpc.botchain.ai). "
+            "Please use a WebSocket connection or a third-party indexer."
+        )

botchain/middleware.py

@@ -0,0 +1,58 @@
+from web3.types import RPCEndpoint, RPCResponse
+from typing import Callable, Any
+import logging
+
+logger = logging.getLogger(__name__)
+
+def botchain_paymaster_middleware(make_request: Callable[[RPCEndpoint, Any], RPCResponse], w3: "Web3") -> Callable:
+    """
+    Middleware to intercept transactions, check for BOT Chain sponsorship,
+    and rewrite gas fees to zero if eligible.
+    """
+    def middleware(method: RPCEndpoint, params: Any) -> RPCResponse:
+        if method == "eth_sendTransaction" or method == "eth_sendRawTransaction":
+            # For eth_sendTransaction, we can intercept the tx dict directly
+            if method == "eth_sendTransaction":
+                tx_dict = params[0]
+                
+                # Check sponsorship status via custom RPC
+                try:
+                    is_sponsorable = w3.provider.make_request("pm_isSponsorable", [tx_dict])
+                    
+                    if is_sponsorable.get("result", {}).get("Sponsorable") is True:
+                        # Rewrite Gas to 0
+                        tx_dict['gasPrice'] = 0
+                        # If EIP-1559 format is used, clear those instead
+                        if 'maxFeePerGas' in tx_dict:
+                            tx_dict['maxFeePerGas'] = 0
+                        if 'maxPriorityFeePerGas' in tx_dict:
+                            tx_dict['maxPriorityFeePerGas'] = 0
+                            
+                        # Update params
+                        params = [tx_dict]
+                        logger.info("Paymaster approved: Rewriting gas to 0 for sponsored transaction.")
+                except Exception as e:
+                    # Log failure to reach paymaster, but proceed with normal gas
+                    logger.warning(f"Paymaster check failed: {e}")
+
+        # Continue the request down the middleware chain
+        return make_request(method, params)
+    
+    return middleware
+
+def check_and_apply_sponsorship(w3: "Web3", tx_dict: dict) -> dict:
+    """
+    Helper for local signers to check pm_isSponsorable and mutate the tx_dict before signing.
+    """
+    try:
+        is_sponsorable = w3.provider.make_request("pm_isSponsorable", [tx_dict])
+        if is_sponsorable.get("result", {}).get("Sponsorable") is True:
+            tx_dict['gasPrice'] = 0
+            if 'maxFeePerGas' in tx_dict:
+                tx_dict['maxFeePerGas'] = 0
+            if 'maxPriorityFeePerGas' in tx_dict:
+                tx_dict['maxPriorityFeePerGas'] = 0
+            logger.info("Paymaster approved: Applied zero gas fees to local tx_dict.")
+    except Exception as e:
+        logger.warning(f"Paymaster check failed: {e}")
+    return tx_dict

botchain/tokens.py

@@ -0,0 +1,87 @@
+from web3 import Web3
+from .contracts import MAINNET_ADDRESSES
+
+ERC20_ABI = [
+    {
+        "constant": True,
+        "inputs": [{"name": "_owner", "type": "address"}],
+        "name": "balanceOf",
+        "outputs": [{"name": "balance", "type": "uint256"}],
+        "type": "function"
+    },
+    {
+        "constant": False,
+        "inputs": [
+            {"name": "_spender", "type": "address"},
+            {"name": "_value", "type": "uint256"}
+        ],
+        "name": "approve",
+        "outputs": [{"name": "", "type": "bool"}],
+        "type": "function"
+    },
+    {
+        "constant": True,
+        "inputs": [
+            {"name": "_owner", "type": "address"},
+            {"name": "_spender", "type": "address"}
+        ],
+        "name": "allowance",
+        "outputs": [{"name": "", "type": "uint256"}],
+        "type": "function"
+    }
+]
+
+WBOT_ABI = ERC20_ABI + [
+    {
+        "constant": False,
+        "inputs": [],
+        "name": "deposit",
+        "outputs": [],
+        "payable": True,
+        "type": "function"
+    },
+    {
+        "constant": False,
+        "inputs": [{"name": "wad", "type": "uint256"}],
+        "name": "withdraw",
+        "outputs": [],
+        "payable": False,
+        "type": "function"
+    }
+]
+
+class TokenManager:
+    def __init__(self, botclient):
+        self.client = botclient
+        self.w3 = botclient.w3
+        self.wbot_address = self.w3.to_checksum_address(MAINNET_ADDRESSES["WBOT"])
+        self.wbot_contract = self.w3.eth.contract(address=self.wbot_address, abi=WBOT_ABI)
+
+    def get_erc20_contract(self, token_address: str):
+        return self.w3.eth.contract(address=self.w3.to_checksum_address(token_address), abi=ERC20_ABI)
+
+    def get_balance(self, token_address: str, account_address: str = None) -> int:
+        if not account_address:
+            if not self.client.account:
+                raise ValueError("No account address provided and client has no default account.")
+            account_address = self.client.account.address
+            
+        contract = self.get_erc20_contract(token_address)
+        return contract.functions.balanceOf(self.w3.to_checksum_address(account_address)).call()
+
+    def approve(self, token_address: str, spender: str, amount: int):
+        if not self.client.account:
+            raise ValueError("Local account required to send approval transactions.")
+            
+        contract = self.get_erc20_contract(token_address)
+        tx = contract.functions.approve(
+            self.w3.to_checksum_address(spender), amount
+        ).build_transaction({
+            'from': self.client.account.address,
+            'nonce': self.w3.eth.get_transaction_count(self.client.account.address),
+            'chainId': self.client.chain_id,
+        })
+        
+        signed_tx = self.w3.eth.account.sign_transaction(tx, private_key=self.client.account.key)
+        tx_hash = self.w3.eth.send_raw_transaction(signed_tx.rawTransaction)
+        return self.w3.to_hex(tx_hash)

botchain_sdk_py-0.1.0.dist-info/METADATA

@@ -0,0 +1,58 @@
+Metadata-Version: 2.4
+Name: botchain-sdk-py
+Version: 0.1.0
+Summary: BOT Chain SDK for Python, featuring Agentic Tooling, MCP, and ALM.
+Author: Bot Chain Team
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: web3
+Requires-Dist: eth-account
+Dynamic: requires-python
+
+# BotChain Python SDK
+
+The official Python SDK for interacting with BOT Chain, an AI-focused Layer 1 ecosystem. This SDK provides complete integration pathways for managing accounts, tokens, concentrated liquidity (BDEX V3), and executing smart contract logic autonomously via our embedded AI Agent integrations.
+
+## Features
+
+- **Core Blockchain Client**: Connect to Mainnet/Testnet easily with full Web3 provider compatibility. Zero-gas transaction sponsorships natively handled.
+- **BDEX V3 Concentrated Liquidity**: Manage advanced DeFi interactions.
+
+### AI Agent & MCP Server
+This SDK natively supports Model Context Protocol (MCP) integrations for autonomous agents like OpenClaw or Claude Desktop. The embedded Agent Policy Engine ensures strict on-chain safeguards including:
+- Hourly rate limits and trade cooldowns.
+- Notional USD limits.
+- Asset Allowlists.
+
+Agents can discover tools (`get_balance`, `get_quote`, `execute_guarded_swap`) over standard JSON-RPC `stdio`. Run the server locally using the bundled entry point:
+```bash
+botchain-mcp
+```
+
+### Automated Liquidity Management (ALM)
+We support on-chain math utilities required to properly route and rebalance Concentrated Liquidity positions automatically. 
+- Exact tick conversions and boundaries.
+- Precise multi-hop math allowing the SDK to compute optimal swap ratios without trusting off-chain actors.
+- Fully atomic rebalances (with Python-level State Recovery for failing swaps).
+
+## Installation
+
+You can install the SDK from source or directly via `pip`:
+```bash
+pip install botchain-sdk-py
+```
+
+## Quick Start
+
+```python
+from botchain.client import BotChain
+from botchain.tokens import TokenManager
+
+# Initialize Client
+client = BotChain(network="mainnet")
+
+# Check token balances
+token_mgr = TokenManager(client)
+balance = token_mgr.get_balance("0xUSDT_Address", "0xUser_Address")
+print(f"USDT Balance: {balance}")
+```

botchain_sdk_py-0.1.0.dist-info/RECORD

@@ -0,0 +1,22 @@
+botchain/__init__.py,sha256=I4ZTF_66fodbfLTc8FvvczGWexC9bA7vOGm9mfYbVus,496
+botchain/client.py,sha256=9Xk5-WHWjf_YKWiTy9PhSRk1WSoDg5kyxdkKfFE13rA,3084
+botchain/contracts.py,sha256=HorJQY668jFiqKIy7kAv1QRvgCca_KRRWv6BYaALLKo,429
+botchain/dex.py,sha256=eAE1WoNTw-mDanEPHZFjNPbYP5Fuzj4F3EBjjvFyiOo,7862
+botchain/dex_alm.py,sha256=iYrL9lERulZoMy9mEjbvRHKI8MB4lLM6ME_-L2lksg0,6065
+botchain/exceptions.py,sha256=ZNBcffKfIor3bZtCZ99EQU5qdEIAWEubex8w_Jv2fNk,355
+botchain/middleware.py,sha256=D4tRClQJKQKyCyoAtbX-Q6zPblAlorRGwPDSMFKwwWU,2682
+botchain/tokens.py,sha256=8T745m7xE5JH5rWRP0jKqOJLSM0cFwAbZpbloWytpos,2984
+botchain/agents/__init__.py,sha256=dYpJLI_J0bqegg_jxjX2ioaXHbRBn1bKaXsd4d1n2Us,122
+botchain/agents/executor.py,sha256=0CH9X2WiUNpphqlKafm5fvWGs_TqJrUm9pj0BkMJla8,3422
+botchain/agents/mcp.py,sha256=8o5vcSN9-fwbU1eIwsCaXM9szWsgdn9q72CGcAshsRU,81
+botchain/agents/mcp_server.py,sha256=Nm7rZkBS_GIKAP6iImtKZsCnSmi4JfsdRKGGyRbI4G0,510
+botchain/agents/policy.py,sha256=vNBsZe76VR4LfJw5lErvGc02YOOB_-3SKJzI9SA_NnY,4270
+botchain/agents/tools/__init__.py,sha256=BKspZRElXRNzxkfex3ZdLVtLITa4egdzjPTHZ56LPWE,140
+botchain/agents/tools/base.py,sha256=adMYUPHG6fd4f8Se7xbbBQwsfqglgXhaSPdEAYcLjfU,1071
+botchain/agents/tools/mcp_server.py,sha256=xZCxABTtCyULREW9lO0t8CTqlp4xpAzOfa38fRntMP8,4048
+botchain/agents/tools/schemas.py,sha256=LHsAuv0lPvrm8dgukaHQRUw_xxNXN9JiudqSNSiTwlE,3660
+botchain_sdk_py-0.1.0.dist-info/METADATA,sha256=Azgz-_LZBpr9HnAk0CN8llCaBllDnTLSFX-_073ag1I,2194
+botchain_sdk_py-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+botchain_sdk_py-0.1.0.dist-info/entry_points.txt,sha256=xcWHZXetGcqH8vz0q5v1F8X5FwUGxzP8p718xqvNmKQ,65
+botchain_sdk_py-0.1.0.dist-info/top_level.txt,sha256=Z9B33ybF6tQKrPdcSLH-GnXQKyz9w4D1BZF4MaFKK7g,9
+botchain_sdk_py-0.1.0.dist-info/RECORD,,

botchain_sdk_py-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

botchain_sdk_py-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+botchain-mcp = botchain.agents.mcp_server:main

botchain_sdk_py-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+botchain