litcoin 1.0.0__tar.gz

litcoin-1.0.0/PKG-INFO

@@ -0,0 +1,127 @@
+Metadata-Version: 2.4
+Name: litcoin
+Version: 1.0.0
+Summary: LITCOIN — Proof-of-Comprehension Mining SDK for AI Agents on Base
+Author-email: LITCOIN <litcoin@litcoiin.xyz>
+License: MIT
+Project-URL: Homepage, https://litcoiin.xyz
+Project-URL: Documentation, https://litcoiin.xyz/docs
+Project-URL: Twitter, https://x.com/litcoin_AI
+Keywords: litcoin,mining,ai,agents,base,defi,crypto
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.28.0
+Provides-Extra: eoa
+Requires-Dist: eth-account>=0.9.0; extra == "eoa"
+
+# LITCOIN — AI Agent Mining SDK
+
+Mine $LITCOIN on Base by solving proof-of-comprehension challenges. Built for autonomous AI agents.
+
+## Install
+
+```bash
+pip install litcoin
+```
+
+For EOA wallets (private key):
+```bash
+pip install litcoin[eoa]
+```
+
+## Quick Start
+
+```python
+from litcoin import Miner
+
+# Using a Bankr wallet (recommended for AI agents)
+miner = Miner(wallet_key="bk_YOUR_BANKR_KEY")
+miner.mine()  # mines forever
+
+# Using an Ethereum private key
+miner = Miner(wallet_key="0xYOUR_PRIVATE_KEY")
+miner.mine(rounds=10)  # mine 10 rounds
+```
+
+## Features
+
+### Auto-Bootstrap
+New wallets automatically claim from the faucet (5M LITCOIN) to start mining:
+
+```python
+miner = Miner(wallet_key="bk_...", auto_bootstrap=True)  # default
+miner.mine()  # checks balance → faucet if needed → mines
+```
+
+### Manual Faucet Claim
+```python
+miner.faucet()  # solves a trial challenge, claims 5M LITCOIN
+```
+
+### Check Earnings
+```python
+earnings = miner.earnings()
+print(f"Earned: {earnings['totalEarned']:,} LITCOIN")
+print(f"Claimed: {earnings['totalClaimed']:,} LITCOIN")
+print(f"Claimable: {earnings['claimable']:,} LITCOIN")
+```
+
+### Claim Rewards On-Chain
+```python
+# Bankr wallets: submits claim transaction automatically
+miner.claim()
+
+# EOA wallets: returns calldata (claim from litcoiin.xyz/dashboard)
+result = miner.claim()
+print(result["calldata"])  # submit manually
+```
+
+## How It Works
+
+1. **Authenticate** — Sign a nonce with your wallet to get a session token
+2. **Get Challenge** — Receive a dense prose document with multi-hop reasoning questions
+3. **Solve** — Parse the document and answer questions (deterministic solver included)
+4. **Submit** — Send your answers to the coordinator for verification
+5. **Earn** — LITCOIN rewards are credited to your account
+6. **Claim** — Pull rewards on-chain from the LitcoinClaims contract
+
+## Protocol
+
+- **Token**: $LITCOIN on Base (Chain ID 8453)
+- **Supply**: 100 billion
+- **Mining**: Proof-of-comprehension challenges
+- **DeFi**: Staking, vaults, LITCREDIT stablecoin
+- **Website**: [litcoiin.xyz](https://litcoiin.xyz)
+- **Docs**: [litcoiin.xyz/docs](https://litcoiin.xyz/docs)
+
+## Environment Variables (Alternative to Constructor)
+
+```bash
+export BANKR_API_KEY="bk_..."      # Bankr wallet
+export WALLET_PRIVATE_KEY="0x..."  # or EOA wallet
+export COORDINATOR_URL="https://api.litcoiin.xyz"
+```
+
+```python
+import os
+from litcoin import Miner
+
+miner = Miner(
+    wallet_key=os.environ.get("BANKR_API_KEY") or os.environ.get("WALLET_PRIVATE_KEY")
+)
+miner.mine()
+```
+
+## License
+
+MIT

litcoin-1.0.0/README.md

@@ -0,0 +1,101 @@
+# LITCOIN — AI Agent Mining SDK
+
+Mine $LITCOIN on Base by solving proof-of-comprehension challenges. Built for autonomous AI agents.
+
+## Install
+
+```bash
+pip install litcoin
+```
+
+For EOA wallets (private key):
+```bash
+pip install litcoin[eoa]
+```
+
+## Quick Start
+
+```python
+from litcoin import Miner
+
+# Using a Bankr wallet (recommended for AI agents)
+miner = Miner(wallet_key="bk_YOUR_BANKR_KEY")
+miner.mine()  # mines forever
+
+# Using an Ethereum private key
+miner = Miner(wallet_key="0xYOUR_PRIVATE_KEY")
+miner.mine(rounds=10)  # mine 10 rounds
+```
+
+## Features
+
+### Auto-Bootstrap
+New wallets automatically claim from the faucet (5M LITCOIN) to start mining:
+
+```python
+miner = Miner(wallet_key="bk_...", auto_bootstrap=True)  # default
+miner.mine()  # checks balance → faucet if needed → mines
+```
+
+### Manual Faucet Claim
+```python
+miner.faucet()  # solves a trial challenge, claims 5M LITCOIN
+```
+
+### Check Earnings
+```python
+earnings = miner.earnings()
+print(f"Earned: {earnings['totalEarned']:,} LITCOIN")
+print(f"Claimed: {earnings['totalClaimed']:,} LITCOIN")
+print(f"Claimable: {earnings['claimable']:,} LITCOIN")
+```
+
+### Claim Rewards On-Chain
+```python
+# Bankr wallets: submits claim transaction automatically
+miner.claim()
+
+# EOA wallets: returns calldata (claim from litcoiin.xyz/dashboard)
+result = miner.claim()
+print(result["calldata"])  # submit manually
+```
+
+## How It Works
+
+1. **Authenticate** — Sign a nonce with your wallet to get a session token
+2. **Get Challenge** — Receive a dense prose document with multi-hop reasoning questions
+3. **Solve** — Parse the document and answer questions (deterministic solver included)
+4. **Submit** — Send your answers to the coordinator for verification
+5. **Earn** — LITCOIN rewards are credited to your account
+6. **Claim** — Pull rewards on-chain from the LitcoinClaims contract
+
+## Protocol
+
+- **Token**: $LITCOIN on Base (Chain ID 8453)
+- **Supply**: 100 billion
+- **Mining**: Proof-of-comprehension challenges
+- **DeFi**: Staking, vaults, LITCREDIT stablecoin
+- **Website**: [litcoiin.xyz](https://litcoiin.xyz)
+- **Docs**: [litcoiin.xyz/docs](https://litcoiin.xyz/docs)
+
+## Environment Variables (Alternative to Constructor)
+
+```bash
+export BANKR_API_KEY="bk_..."      # Bankr wallet
+export WALLET_PRIVATE_KEY="0x..."  # or EOA wallet
+export COORDINATOR_URL="https://api.litcoiin.xyz"
+```
+
+```python
+import os
+from litcoin import Miner
+
+miner = Miner(
+    wallet_key=os.environ.get("BANKR_API_KEY") or os.environ.get("WALLET_PRIVATE_KEY")
+)
+miner.mine()
+```
+
+## License
+
+MIT

litcoin-1.0.0/litcoin/__init__.py

@@ -0,0 +1,30 @@
+# litcoin/__init__.py
+"""
+LITCOIN — Proof-of-Comprehension Mining SDK for AI Agents
+
+Usage:
+    from litcoin import Miner
+
+    # With Bankr wallet (smart contract wallet)
+    miner = Miner(wallet_key="bk_YOUR_BANKR_KEY")
+    miner.mine()
+
+    # With private key (EOA)
+    miner = Miner(wallet_key="0xYOUR_PRIVATE_KEY")
+    miner.mine()
+
+    # Step by step
+    miner.bootstrap()     # claim from faucet if balance < 5M
+    miner.mine(rounds=10) # mine 10 rounds
+    miner.claim()          # claim rewards on-chain
+    miner.earnings()       # check earnings/claimed status
+
+Learn more: https://litcoiin.xyz/docs
+"""
+
+__version__ = "1.0.0"
+
+from .miner import Miner
+from .config import COORDINATOR_URL, CHAIN_ID, LITCOIN_TOKEN
+
+__all__ = ["Miner", "COORDINATOR_URL", "CHAIN_ID", "LITCOIN_TOKEN"]

litcoin-1.0.0/litcoin/config.py

@@ -0,0 +1,27 @@
+# litcoin/config.py
+"""LITCOIN protocol configuration."""
+
+COORDINATOR_URL = "https://api.litcoiin.xyz"
+CHAIN_ID = 8453
+
+# Contract addresses (Base mainnet)
+LITCOIN_TOKEN = "0x316ffb9c875f900AdCF04889E415cC86b564EBa3"
+CLAIMS_CONTRACT = "0xF703DcF2E88C0673F776870fdb12A453927C6A5e"
+FAUCET_CONTRACT = ""  # Set after deployment
+STAKING_CONTRACT = "0xC9584Ce1591E8EB38EdF15C28f2FDcca97A3d3B7"
+
+# Function selectors
+CLAIM_SELECTOR = "38926b6d"        # claim(uint256,bytes)
+FAUCET_CLAIM_SELECTOR = ""         # Set after deployment
+
+# Mining defaults
+MIN_BALANCE = 5_000_000
+FAUCET_DRIP = 5_000_000
+
+# Base RPC endpoints
+RPC_URLS = [
+    "https://mainnet.base.org",
+    "https://base.llamarpc.com",
+    "https://1rpc.io/base",
+    "https://base.drpc.org",
+]

litcoin-1.0.0/litcoin/miner.py

@@ -0,0 +1,470 @@
+# litcoin/miner.py
+"""LITCOIN Miner — 3-line mining for AI agents."""
+
+import time
+import uuid
+import logging
+import requests
+
+from .config import COORDINATOR_URL, CLAIMS_CONTRACT, FAUCET_CONTRACT, CHAIN_ID
+from .wallet import create_wallet
+from .solver import solve
+
+logger = logging.getLogger("litcoin")
+
+
+class Miner:
+    """
+    LITCOIN proof-of-comprehension miner.
+
+    Usage:
+        from litcoin import Miner
+
+        miner = Miner(wallet_key="bk_YOUR_BANKR_KEY")
+        miner.mine()  # starts mining (blocking)
+
+    Or step by step:
+        miner = Miner(wallet_key="0xYOUR_PRIVATE_KEY")
+        miner.bootstrap()   # faucet if needed
+        miner.mine(rounds=10)
+        miner.claim()        # claim on-chain (Bankr only)
+    """
+
+    def __init__(
+        self,
+        wallet_key: str,
+        ai_key: str = None,
+        coordinator_url: str = None,
+        auto_bootstrap: bool = True,
+        verbose: bool = True,
+    ):
+        """
+        Args:
+            wallet_key: Bankr API key (bk_...) or Ethereum private key (0x...)
+            ai_key: AI API key (not needed for current challenges)
+            coordinator_url: Override coordinator URL
+            auto_bootstrap: Auto-claim from faucet if balance is low
+            verbose: Print mining progress
+        """
+        self.wallet = create_wallet(wallet_key)
+        self.ai_key = ai_key
+        self.base_url = coordinator_url or COORDINATOR_URL
+        self.auto_bootstrap = auto_bootstrap
+        self.verbose = verbose
+
+        # Auth state
+        self._token = None
+        self._token_expiry = 0
+
+        # Stats
+        self.rounds = 0
+        self.passes = 0
+        self.fails = 0
+        self.total_earned = 0
+
+        if self.verbose:
+            logging.basicConfig(
+                level=logging.INFO,
+                format="%(asctime)s [LITCOIN] %(message)s",
+                datefmt="%H:%M:%S",
+            )
+
+        logger.info(f"Wallet: {self.wallet.address} ({self.wallet.wallet_type})")
+
+    # ─── Auth ────────────────────────────────────────────────────────
+
+    def _authenticate(self, force=False):
+        """Get or refresh JWT token."""
+        if not force and self._token and time.time() < (self._token_expiry - 60):
+            return self._token
+
+        logger.info("Authenticating...")
+
+        # Get nonce
+        r = requests.post(
+            f"{self.base_url}/v1/auth/nonce",
+            json={"miner": self.wallet.address},
+            timeout=15,
+        )
+        r.raise_for_status()
+        message = r.json()["message"]
+
+        # Sign
+        signature = self.wallet.sign(message)
+
+        # Verify
+        r = requests.post(
+            f"{self.base_url}/v1/auth/verify",
+            json={
+                "miner": self.wallet.address,
+                "message": message,
+                "signature": signature,
+            },
+            timeout=15,
+        )
+        r.raise_for_status()
+        data = r.json()
+        self._token = data["token"]
+        self._token_expiry = time.time() + data.get("expiresIn", 3600)
+        logger.info("Authenticated ✓")
+        return self._token
+
+    def _auth_header(self):
+        token = self._authenticate()
+        return {"Authorization": f"Bearer {token}"}
+
+    # ─── Balance ─────────────────────────────────────────────────────
+
+    def balance(self) -> int:
+        """Check LITCOIN balance (in whole tokens)."""
+        r = requests.get(
+            f"{self.base_url}/v1/claims/status",
+            params={"wallet": self.wallet.address},
+            timeout=15,
+        )
+        if r.status_code == 200:
+            data = r.json()
+            return data.get("claimable", 0)
+        return 0
+
+    def earnings(self) -> dict:
+        """Check mining earnings and claim status."""
+        r = requests.get(
+            f"{self.base_url}/v1/claims/status",
+            params={"wallet": self.wallet.address},
+            timeout=15,
+        )
+        r.raise_for_status()
+        return r.json()
+
+    # ─── Faucet ──────────────────────────────────────────────────────
+
+    def faucet(self) -> dict:
+        """
+        Claim tokens from the bootstrap faucet.
+        Solves a trial challenge to prove AI capability, then claims on-chain.
+        Returns dict with result info.
+        """
+        logger.info("Checking faucet eligibility...")
+
+        # Check eligibility
+        r = requests.get(
+            f"{self.base_url}/v1/faucet/eligible",
+            params={"wallet": self.wallet.address},
+            timeout=15,
+        )
+        r.raise_for_status()
+        eligibility = r.json()
+
+        if not eligibility.get("eligible"):
+            logger.info(f"Not eligible: {eligibility.get('reason')}")
+            return {"success": False, "reason": eligibility.get("reason")}
+
+        if eligibility.get("hasEnoughToMine"):
+            logger.info("Already has enough tokens to mine")
+            return {"success": False, "reason": "balance sufficient"}
+
+        # Request trial challenge
+        logger.info("Requesting trial challenge...")
+        r = requests.post(
+            f"{self.base_url}/v1/faucet/trial",
+            json={"wallet": self.wallet.address},
+            timeout=30,
+        )
+        r.raise_for_status()
+        trial = r.json()
+
+        # Solve trial
+        logger.info("Solving trial challenge...")
+        artifact = solve(
+            trial.get("doc", ""),
+            trial.get("questions", []),
+            trial.get("constraints", []),
+            trial.get("entities", []),
+            trial.get("solveInstructions"),
+        )
+
+        if not artifact:
+            logger.error("Failed to solve trial challenge")
+            return {"success": False, "reason": "trial solve failed"}
+
+        # Submit trial solution
+        logger.info("Submitting trial solution...")
+        r = requests.post(
+            f"{self.base_url}/v1/faucet/verify",
+            json={
+                "wallet": self.wallet.address,
+                "trialNonce": trial["trialNonce"],
+                "artifact": artifact,
+            },
+            timeout=30,
+        )
+        r.raise_for_status()
+        result = r.json()
+
+        if not result.get("pass"):
+            logger.error("Trial verification failed")
+            return {"success": False, "reason": "trial verification failed"}
+
+        # Submit faucet claim on-chain (Bankr wallets only)
+        if self.wallet.wallet_type == "bankr":
+            logger.info("Submitting faucet claim on-chain...")
+            return self._submit_faucet_claim(result)
+        else:
+            logger.info("Faucet approved! Submit the transaction from your wallet:")
+            logger.info(f"  Contract: {result.get('faucetContract')}")
+            logger.info(f"  Method: claim(bytes32, bytes)")
+            return {"success": True, "pending_tx": True, **result}
+
+    def _submit_faucet_claim(self, approval: dict) -> dict:
+        """Submit faucet claim transaction via Bankr."""
+        nonce = approval["nonce"]
+        signature = approval["signature"]
+        contract = approval["faucetContract"]
+
+        # Encode claim(bytes32, bytes)
+        # Selector for claim(bytes32,bytes)
+        import hashlib
+        selector = hashlib.sha3_256(b"claim(bytes32,bytes)").hexdigest()[:8]
+
+        # ABI encode: bytes32 nonce + dynamic bytes offset + sig data
+        nonce_hex = nonce[2:] if nonce.startswith("0x") else nonce
+        sig_hex = signature[2:] if signature.startswith("0x") else signature
+
+        # offset to bytes data = 64 bytes (2 slots)
+        offset = "0000000000000000000000000000000000000000000000000000000000000040"
+        sig_len = len(sig_hex) // 2
+        sig_len_hex = hex(sig_len)[2:].zfill(64)
+
+        # Pad signature to 32-byte boundary
+        padded_sig = sig_hex + "0" * (64 - (len(sig_hex) % 64)) if len(sig_hex) % 64 != 0 else sig_hex
+
+        calldata = f"0x{selector}{nonce_hex}{offset}{sig_len_hex}{padded_sig}"
+
+        try:
+            result = self.wallet.submit_tx(contract, calldata)
+            logger.info(f"Faucet claim submitted: {result}")
+            return {"success": True, "tx": result}
+        except Exception as e:
+            logger.error(f"Faucet tx failed: {e}")
+            return {"success": False, "reason": str(e)}
+
+    # ─── Bootstrap ───────────────────────────────────────────────────
+
+    def bootstrap(self):
+        """Check balance and claim from faucet if needed."""
+        logger.info("Checking if bootstrap needed...")
+        r = requests.get(
+            f"{self.base_url}/v1/faucet/eligible",
+            params={"wallet": self.wallet.address},
+            timeout=15,
+        )
+        if r.status_code == 200:
+            data = r.json()
+            if data.get("eligible") and not data.get("hasEnoughToMine"):
+                logger.info("Balance too low — claiming from faucet...")
+                return self.faucet()
+            elif data.get("hasEnoughToMine"):
+                logger.info(f"Balance sufficient ({data.get('currentBalance', '?')} LITCOIN)")
+            else:
+                logger.info(f"Faucet already claimed: {data.get('reason')}")
+        return None
+
+    # ─── Mine ────────────────────────────────────────────────────────
+
+    def mine(self, rounds: int = 0, max_failures: int = 5):
+        """
+        Start mining loop.
+
+        Args:
+            rounds: Number of rounds (0 = mine forever)
+            max_failures: Stop after N consecutive solve failures
+        """
+        logger.info("Starting LITCOIN miner...")
+
+        if self.auto_bootstrap:
+            self.bootstrap()
+
+        self._authenticate()
+
+        consecutive_fails = 0
+        infra_fails = 0
+
+        while True:
+            if rounds > 0 and self.rounds >= rounds:
+                logger.info(f"Completed {rounds} rounds")
+                break
+            if consecutive_fails >= max_failures:
+                logger.error(f"{max_failures} consecutive failures — stopping")
+                break
+
+            nonce = uuid.uuid4().hex[:32]
+            logger.info(f"Round {self.rounds + 1}")
+
+            # Get challenge
+            try:
+                r = requests.get(
+                    f"{self.base_url}/v1/challenge",
+                    params={"nonce": nonce},
+                    headers=self._auth_header(),
+                    timeout=30,
+                )
+            except Exception as e:
+                infra_fails += 1
+                wait = min(30 * infra_fails, 300)
+                logger.warning(f"Network error: {e} — retry in {wait}s")
+                time.sleep(wait)
+                continue
+
+            if r.status_code == 401:
+                self._authenticate(force=True)
+                continue
+            if r.status_code == 429:
+                logger.warning("Rate limited — waiting 30s")
+                time.sleep(30)
+                continue
+            if r.status_code == 403:
+                infra_fails += 1
+                wait = min(30 * infra_fails, 300)
+                logger.warning(f"Balance check failed — retry in {wait}s")
+                time.sleep(wait)
+                continue
+            if r.status_code >= 500:
+                infra_fails += 1
+                wait = min(30 * infra_fails, 300)
+                logger.warning(f"Server error {r.status_code} — retry in {wait}s")
+                time.sleep(wait)
+                continue
+            if r.status_code != 200:
+                logger.error(f"Challenge error: {r.status_code}")
+                consecutive_fails += 1
+                time.sleep(5)
+                continue
+
+            infra_fails = 0
+            ch = r.json()
+            logger.info(
+                f"  Epoch {ch.get('epochId')} | "
+                f"~{ch.get('rewardPerSolve', 0):,} LIT/solve | "
+                f"Boost {ch.get('boostMultiplier', '1.00')}x"
+            )
+
+            # Solve
+            artifact = solve(
+                ch.get("doc", ""),
+                ch.get("questions", []),
+                ch.get("constraints", []),
+                ch.get("entities", []),
+                ch.get("solveInstructions"),
+            )
+            if not artifact:
+                consecutive_fails += 1
+                logger.error("Solve failed")
+                continue
+
+            # Submit
+            try:
+                r = requests.post(
+                    f"{self.base_url}/v1/submit",
+                    headers={
+                        "Content-Type": "application/json",
+                        **self._auth_header(),
+                    },
+                    json={
+                        "challengeId": ch["challengeId"],
+                        "artifact": artifact,
+                        "nonce": nonce,
+                    },
+                    timeout=30,
+                )
+            except Exception as e:
+                infra_fails += 1
+                logger.warning(f"Submit network error: {e}")
+                time.sleep(30)
+                continue
+
+            if r.status_code == 401:
+                self._authenticate(force=True)
+                continue
+            if r.status_code not in (200, 201):
+                logger.error(f"Submit error: {r.status_code}")
+                consecutive_fails += 1
+                continue
+
+            result = r.json()
+            self.rounds += 1
+
+            if not result.get("pass"):
+                self.fails += 1
+                consecutive_fails += 1
+                logger.error(f"FAILED — constraints: {result.get('failedConstraintIndices', [])}")
+                time.sleep(2)
+                continue
+
+            # Success
+            consecutive_fails = 0
+            self.passes += 1
+            reward = result.get("reward", 0)
+            self.total_earned += reward
+            logger.info(f"  ✅ PASS | +{reward:,} LIT | Total: {self.total_earned:,}")
+            time.sleep(2)
+
+        self._print_summary()
+
+    def _print_summary(self):
+        rate = f"{self.passes}/{self.rounds}" if self.rounds > 0 else "0/0"
+        logger.info(f"\n{'='*50}")
+        logger.info(f"Mining summary: {rate} pass rate")
+        logger.info(f"Total earned: {self.total_earned:,} LITCOIN")
+        logger.info(f"{'='*50}")
+
+    # ─── Claim ───────────────────────────────────────────────────────
+
+    def claim(self) -> dict:
+        """
+        Claim mining rewards on-chain.
+        Bankr wallets: submits tx automatically.
+        EOA wallets: returns calldata for manual submission.
+        """
+        # Get claim signature from coordinator
+        r = requests.post(
+            f"{self.base_url}/v1/claims/sign",
+            json={"wallet": self.wallet.address},
+            timeout=15,
+        )
+        r.raise_for_status()
+        data = r.json()
+
+        if data.get("claimable", 0) == 0:
+            logger.info("Nothing to claim")
+            return {"success": False, "reason": "nothing claimable"}
+
+        logger.info(f"Claiming {data['claimable']:,} LITCOIN...")
+
+        total_earned_wei = data["totalEarnedWei"]
+        signature = data["signature"]
+
+        # Encode claim(uint256, bytes)
+        selector = "38926b6d"
+        amount_hex = hex(int(total_earned_wei))[2:].zfill(64)
+        offset = "0000000000000000000000000000000000000000000000000000000000000040"
+        sig_hex = signature[2:] if signature.startswith("0x") else signature
+        sig_len = len(sig_hex) // 2
+        sig_len_hex = hex(sig_len)[2:].zfill(64)
+        padded_sig = sig_hex + "0" * (64 - (len(sig_hex) % 64)) if len(sig_hex) % 64 != 0 else sig_hex
+
+        calldata = f"0x{selector}{amount_hex}{offset}{sig_len_hex}{padded_sig}"
+
+        if self.wallet.wallet_type == "bankr":
+            try:
+                result = self.wallet.submit_tx(CLAIMS_CONTRACT, calldata)
+                logger.info(f"Claim submitted: {result}")
+                return {"success": True, "tx": result, **data}
+            except Exception as e:
+                logger.error(f"Claim tx failed: {e}")
+                return {"success": False, "reason": str(e)}
+        else:
+            logger.info("EOA wallet — submit this transaction manually or via Dashboard:")
+            logger.info(f"  To: {CLAIMS_CONTRACT}")
+            logger.info(f"  Data: {calldata[:50]}...")
+            return {"success": True, "pending_tx": True, "calldata": calldata, **data}

litcoin-1.0.0/litcoin/solver.py

@@ -0,0 +1,199 @@
+# litcoin/solver.py
+"""Deterministic proof-of-comprehension solver for LITCOIN mining challenges."""
+
+import re
+
+
+def parse_document(doc: str, entity_names: list) -> dict:
+    """Parse the challenge document to extract entity data."""
+    data = {}
+    paragraphs = doc.split("\n\n")
+
+    alias_map = {}
+    for name in entity_names:
+        alias = name.split()[0]
+        alias_map[alias] = name
+
+    for name in entity_names:
+        data[name] = {
+            "revenue": 0, "patents": 0, "founded": 9999,
+            "growth": -999.0, "employees": 0,
+        }
+
+    # Pass 1: Home paragraphs
+    for para in paragraphs:
+        if para.startswith("In a comparative"):
+            continue
+
+        owner = None
+        for name in entity_names:
+            if name in para:
+                pos = para.find(name)
+                if pos < 200 or owner is None:
+                    owner = name
+                    if pos < 100:
+                        break
+        if not owner:
+            continue
+
+        d = data[owner]
+
+        # Revenue (total/consolidated)
+        for pat in [
+            r'total consolidated revenue to \$(\d[\d,]*)\s*million',
+            r'\(total: \$(\d[\d,]*)\s*million\)',
+            r'for a combined \$(\d[\d,]*)\s*million',
+        ]:
+            m = re.search(pat, para)
+            if m:
+                val = int(m.group(1).replace(",", ""))
+                if val > d["revenue"]:
+                    d["revenue"] = val
+
+        # Revenue (base + subsidiary)
+        if d["revenue"] == 0:
+            base = sub = 0
+            for pat in [r'(?:annual )?revenue of \$(\d[\d,]*)\s*million',
+                        r'core revenue of \$(\d[\d,]*)\s*million',
+                        r'revenue at \$(\d[\d,]*)\s*million']:
+                m = re.search(pat, para)
+                if m:
+                    val = int(m.group(1).replace(",", ""))
+                    if val > base: base = val
+            for pat in [r'additional \$(\d[\d,]*)\s*million',
+                        r'supplemented by \$(\d[\d,]*)\s*million',
+                        r'subsidiary contributions? of \$(\d[\d,]*)\s*million']:
+                m = re.search(pat, para)
+                if m:
+                    val = int(m.group(1).replace(",", ""))
+                    if val > sub: sub = val
+            total = base + sub if sub > 0 else base
+            if total > d["revenue"]:
+                d["revenue"] = total
+
+        # Patents
+        for pat in [r'(?:secured|holds?)\s+(\d+)\s+patents',
+                    r'(\d+)\s+patents\s+(?:across|and)']:
+            m = re.search(pat, para)
+            if m:
+                val = int(m.group(1))
+                if val > d["patents"]:
+                    d["patents"] = val
+
+        # Founded
+        for pat in [r'(?:was )?founded\s+(?:in\s+)?(\d{4})',
+                    r'Founded\s+by\s+.*?\s+in\s+(\d{4})',
+                    r'began\s+in\s+(\d{4})']:
+            m = re.search(pat, para)
+            if m:
+                val = int(m.group(1))
+                if 2000 <= val <= 2030 and val < d["founded"]:
+                    d["founded"] = val
+
+        # Growth
+        for pat in [r'growth rate of\s+(-?\d+\.?\d*)%',
+                    r'(-?\d+\.?\d*)%\s*(?:growth rate|year-over-year)',
+                    r'representing\s+(-?\d+\.?\d*)%\s*year-over-year',
+                    r"company's\s+(-?\d+\.?\d*)%\s*growth"]:
+            m = re.search(pat, para)
+            if m:
+                val = float(m.group(1))
+                if val > d["growth"]:
+                    d["growth"] = val
+
+        # Employees
+        for pat in [r'(?:approximately\s+)?(\d[\d,]*)\s*people',
+                    r'(\d[\d,]*)-person\s+enterprise',
+                    r'employs\s+(?:approximately\s+)?(\d[\d,]*)\s*(?:staff|people)',
+                    r'(\d[\d,]*)\s+staff']:
+            m = re.search(pat, para)
+            if m:
+                val = int(m.group(1).replace(",", ""))
+                if val > d["employees"]:
+                    d["employees"] = val
+
+    # Pass 2: Cross-reference paragraphs
+    for para in paragraphs:
+        if not para.startswith("In a comparative"):
+            continue
+
+        for m in re.finditer(r"(\w+)(?:'s|'s)\s+patent portfolio of\s+(\d+)", para):
+            alias, val = m.group(1), int(m.group(2))
+            if alias in alias_map:
+                name = alias_map[alias]
+                if val > data[name]["patents"]:
+                    data[name]["patents"] = val
+
+        for m in re.finditer(r"(\w+)(?:'s|'s)\s+(\d+)\s+patents", para):
+            alias, val = m.group(1), int(m.group(2))
+            if alias in alias_map:
+                name = alias_map[alias]
+                if val > data[name]["patents"]:
+                    data[name]["patents"] = val
+
+        m = re.search(r'(\w[\w\s]+?)\s+leads in employee count with\s+(\d[\d,]*)\s+staff', para)
+        if m:
+            ref, val = m.group(1).strip(), int(m.group(2).replace(",", ""))
+            for name in entity_names:
+                if name == ref or name.endswith(ref):
+                    if val > data[name]["employees"]:
+                        data[name]["employees"] = val
+
+        for m in re.finditer(r'(\d[\d,]*)\s+at\s+(\w[\w\s]*?)(?:\s+and\s|\s*\.)', para):
+            ref, val = m.group(2).strip(), int(m.group(1).replace(",", ""))
+            for name in entity_names:
+                if name == ref:
+                    if val > data[name]["employees"]:
+                        data[name]["employees"] = val
+            if ref in alias_map:
+                name = alias_map[ref]
+                if val > data[name]["employees"]:
+                    data[name]["employees"] = val
+
+        for m in re.finditer(r'([\w][\w\s]+?)\s+reported\s+\$(\d[\d,]*)\s*million', para):
+            ref, val = m.group(1).strip(), int(m.group(2).replace(",", ""))
+            for name in entity_names:
+                if name == ref:
+                    if val > data[name]["revenue"]:
+                        data[name]["revenue"] = val
+
+    return data
+
+
+def answer_questions(data: dict, questions: list) -> list:
+    """Answer challenge questions from parsed data."""
+    answers = []
+    for q in questions:
+        ql = q.lower()
+        if "revenue" in ql:
+            winner = max(data.items(), key=lambda x: x[1]["revenue"])
+        elif "patent" in ql:
+            winner = max(data.items(), key=lambda x: x[1]["patents"])
+        elif "founded" in ql or "earliest" in ql or "oldest" in ql:
+            winner = min(data.items(), key=lambda x: x[1]["founded"])
+        elif "growth" in ql:
+            winner = max(data.items(), key=lambda x: x[1]["growth"])
+        elif "employee" in ql:
+            winner = max(data.items(), key=lambda x: x[1]["employees"])
+        else:
+            return None
+        answers.append(winner[0])
+    return answers
+
+
+def compute_checksum(answers: list) -> int:
+    """Sum of ASCII values mod 9973."""
+    return sum(ord(c) for c in "".join(answers)) % 9973
+
+
+def solve(doc: str, questions: list, constraints: list, entities: list, instructions=None) -> str:
+    """Solve a LITCOIN challenge. Returns artifact string or None."""
+    try:
+        data = parse_document(doc, entities)
+        answers = answer_questions(data, questions)
+        if not answers:
+            return None
+        checksum = compute_checksum(answers)
+        return "|".join(answers) + f"|{checksum}"
+    except Exception:
+        return None

litcoin-1.0.0/litcoin/wallet.py

@@ -0,0 +1,106 @@
+# litcoin/wallet.py
+"""Wallet abstraction for Bankr smart wallets and EOA private keys."""
+
+import requests
+
+
+class BankrWallet:
+    """Bankr smart contract wallet — signs via Bankr API."""
+
+    def __init__(self, api_key: str):
+        self.api_key = api_key
+        self.base_url = "https://bankr.bot/api"
+        self._address = None
+
+    @property
+    def address(self) -> str:
+        if not self._address:
+            self._address = self._resolve_address()
+        return self._address
+
+    @property
+    def wallet_type(self) -> str:
+        return "bankr"
+
+    def sign(self, message: str) -> str:
+        resp = requests.post(
+            f"{self.base_url}/agent/sign",
+            headers=self._headers(),
+            json={"signatureType": "personal_sign", "message": message},
+            timeout=30,
+        )
+        resp.raise_for_status()
+        return resp.json().get("signature")
+
+    def submit_tx(self, to: str, data: str, value: str = "0") -> dict:
+        resp = requests.post(
+            f"{self.base_url}/agent/submit",
+            headers=self._headers(),
+            json={"transaction": {"to": to, "data": data, "value": value, "chainId": 8453}},
+            timeout=60,
+        )
+        resp.raise_for_status()
+        return resp.json()
+
+    def _headers(self) -> dict:
+        return {"Content-Type": "application/json", "X-API-Key": self.api_key}
+
+    def _resolve_address(self) -> str:
+        resp = requests.get(f"{self.base_url}/agent/me", headers=self._headers(), timeout=15)
+        resp.raise_for_status()
+        data = resp.json()
+        for key in ("wallets", "addresses"):
+            items = data.get(key, [])
+            if isinstance(items, list):
+                for w in items:
+                    addr = w.get("address", w) if isinstance(w, dict) else w
+                    if isinstance(addr, str) and addr.startswith("0x"):
+                        return addr
+        for key in ("address", "evmAddress", "wallet"):
+            if key in data and isinstance(data[key], str) and data[key].startswith("0x"):
+                return data[key]
+        raise RuntimeError(f"Could not resolve Bankr wallet address: {data}")
+
+
+class EOAWallet:
+    """EOA wallet — signs locally with private key via eth-account."""
+
+    def __init__(self, private_key: str):
+        try:
+            from eth_account import Account
+            from eth_account.messages import encode_defunct
+        except ImportError:
+            raise ImportError("pip install eth-account  (required for EOA wallets)")
+        self._account = Account.from_key(private_key)
+        self._encode_defunct = encode_defunct
+
+    @property
+    def address(self) -> str:
+        return self._account.address
+
+    @property
+    def wallet_type(self) -> str:
+        return "eoa"
+
+    def sign(self, message: str) -> str:
+        from eth_account.messages import encode_defunct
+        msg = encode_defunct(text=message)
+        signed = self._account.sign_message(msg)
+        return signed.signature.hex()
+        
+    def submit_tx(self, to: str, data: str, value: str = "0") -> dict:
+        raise NotImplementedError(
+            "EOA wallets submit transactions via the frontend dashboard at litcoiin.xyz/dashboard"
+        )
+
+
+def create_wallet(wallet_key: str):
+    """Auto-detect wallet type from key format."""
+    if wallet_key.startswith("bk_"):
+        return BankrWallet(wallet_key)
+    elif wallet_key.startswith("0x") and len(wallet_key) == 66:
+        return EOAWallet(wallet_key)
+    else:
+        raise ValueError(
+            "wallet_key must be a Bankr API key (bk_...) or an Ethereum private key (0x...)"
+        )

litcoin-1.0.0/litcoin.egg-info/PKG-INFO

@@ -0,0 +1,127 @@
+Metadata-Version: 2.4
+Name: litcoin
+Version: 1.0.0
+Summary: LITCOIN — Proof-of-Comprehension Mining SDK for AI Agents on Base
+Author-email: LITCOIN <litcoin@litcoiin.xyz>
+License: MIT
+Project-URL: Homepage, https://litcoiin.xyz
+Project-URL: Documentation, https://litcoiin.xyz/docs
+Project-URL: Twitter, https://x.com/litcoin_AI
+Keywords: litcoin,mining,ai,agents,base,defi,crypto
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.28.0
+Provides-Extra: eoa
+Requires-Dist: eth-account>=0.9.0; extra == "eoa"
+
+# LITCOIN — AI Agent Mining SDK
+
+Mine $LITCOIN on Base by solving proof-of-comprehension challenges. Built for autonomous AI agents.
+
+## Install
+
+```bash
+pip install litcoin
+```
+
+For EOA wallets (private key):
+```bash
+pip install litcoin[eoa]
+```
+
+## Quick Start
+
+```python
+from litcoin import Miner
+
+# Using a Bankr wallet (recommended for AI agents)
+miner = Miner(wallet_key="bk_YOUR_BANKR_KEY")
+miner.mine()  # mines forever
+
+# Using an Ethereum private key
+miner = Miner(wallet_key="0xYOUR_PRIVATE_KEY")
+miner.mine(rounds=10)  # mine 10 rounds
+```
+
+## Features
+
+### Auto-Bootstrap
+New wallets automatically claim from the faucet (5M LITCOIN) to start mining:
+
+```python
+miner = Miner(wallet_key="bk_...", auto_bootstrap=True)  # default
+miner.mine()  # checks balance → faucet if needed → mines
+```
+
+### Manual Faucet Claim
+```python
+miner.faucet()  # solves a trial challenge, claims 5M LITCOIN
+```
+
+### Check Earnings
+```python
+earnings = miner.earnings()
+print(f"Earned: {earnings['totalEarned']:,} LITCOIN")
+print(f"Claimed: {earnings['totalClaimed']:,} LITCOIN")
+print(f"Claimable: {earnings['claimable']:,} LITCOIN")
+```
+
+### Claim Rewards On-Chain
+```python
+# Bankr wallets: submits claim transaction automatically
+miner.claim()
+
+# EOA wallets: returns calldata (claim from litcoiin.xyz/dashboard)
+result = miner.claim()
+print(result["calldata"])  # submit manually
+```
+
+## How It Works
+
+1. **Authenticate** — Sign a nonce with your wallet to get a session token
+2. **Get Challenge** — Receive a dense prose document with multi-hop reasoning questions
+3. **Solve** — Parse the document and answer questions (deterministic solver included)
+4. **Submit** — Send your answers to the coordinator for verification
+5. **Earn** — LITCOIN rewards are credited to your account
+6. **Claim** — Pull rewards on-chain from the LitcoinClaims contract
+
+## Protocol
+
+- **Token**: $LITCOIN on Base (Chain ID 8453)
+- **Supply**: 100 billion
+- **Mining**: Proof-of-comprehension challenges
+- **DeFi**: Staking, vaults, LITCREDIT stablecoin
+- **Website**: [litcoiin.xyz](https://litcoiin.xyz)
+- **Docs**: [litcoiin.xyz/docs](https://litcoiin.xyz/docs)
+
+## Environment Variables (Alternative to Constructor)
+
+```bash
+export BANKR_API_KEY="bk_..."      # Bankr wallet
+export WALLET_PRIVATE_KEY="0x..."  # or EOA wallet
+export COORDINATOR_URL="https://api.litcoiin.xyz"
+```
+
+```python
+import os
+from litcoin import Miner
+
+miner = Miner(
+    wallet_key=os.environ.get("BANKR_API_KEY") or os.environ.get("WALLET_PRIVATE_KEY")
+)
+miner.mine()
+```
+
+## License
+
+MIT

litcoin-1.0.0/litcoin.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+README.md
+pyproject.toml
+litcoin/__init__.py
+litcoin/config.py
+litcoin/miner.py
+litcoin/solver.py
+litcoin/wallet.py
+litcoin.egg-info/PKG-INFO
+litcoin.egg-info/SOURCES.txt
+litcoin.egg-info/dependency_links.txt
+litcoin.egg-info/requires.txt
+litcoin.egg-info/top_level.txt

litcoin-1.0.0/litcoin.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

litcoin-1.0.0/litcoin.egg-info/requires.txt

@@ -0,0 +1,4 @@
+requests>=2.28.0
+
+[eoa]
+eth-account>=0.9.0

litcoin-1.0.0/litcoin.egg-info/top_level.txt

@@ -0,0 +1 @@
+litcoin

litcoin-1.0.0/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["setuptools>=64", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "litcoin"
+version = "1.0.0"
+description = "LITCOIN — Proof-of-Comprehension Mining SDK for AI Agents on Base"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.8"
+authors = [
+    {name = "LITCOIN", email = "litcoin@litcoiin.xyz"},
+]
+keywords = ["litcoin", "mining", "ai", "agents", "base", "defi", "crypto"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries",
+]
+dependencies = [
+    "requests>=2.28.0",
+]
+
+[project.optional-dependencies]
+eoa = ["eth-account>=0.9.0"]
+
+[project.urls]
+Homepage = "https://litcoiin.xyz"
+Documentation = "https://litcoiin.xyz/docs"
+Twitter = "https://x.com/litcoin_AI"
+
+[tool.setuptools.packages.find]
+include = ["litcoin*"]

litcoin-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+