playweb-node 1.0.0__py3-none-any.whl

playweb/core/fee_engine.py

@@ -0,0 +1,312 @@
+"""
+PlayWebit Network — Fee Engine
+Handles all L1 fee logic.
+50/50 split enforced here — no node operator can override.
+Every block is validated against these rules.
+"""
+
+import logging
+from typing import List, Tuple, Dict
+
+from playweb.config import (
+    AUTHORITY_WALLET,
+    TRANSACTION_FEE,
+    CV_LINK_FEE,
+    PLWB_REDEMPTION_FEE,
+    FEE_SPLIT_AUTHORITY,
+    FEE_SPLIT_NODE,
+    SPLITTABLE_FEE_TYPES,
+    AUTHORITY_ONLY_FEE_TYPES,
+    AUTHORITY_TX_TYPES,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class FeeEngine:
+
+    def __init__(self):
+        pass
+
+    # ─────────────────────────────────────────────────────────────
+    # Calculate
+    # ─────────────────────────────────────────────────────────────
+
+    def calculate_fee(self, tx_type: str, amount: float = 0) -> Dict:
+        """
+        Calculate the fee for a given transaction type.
+        Returns:
+            {
+                total:          float,
+                authority_cut:  float,
+                node_cut:       float,
+                fee_type:       str,   "split" | "authority_only" | "none"
+            }
+        """
+        # ── Authority tx types never have fees ───────────────────
+        # genesis, reward, plwb_purchase, plwb_redeem,
+        # spider_hash_anchor — all free
+        if tx_type in AUTHORITY_TX_TYPES:
+            return {
+                "total":         0.0,
+                "authority_cut": 0.0,
+                "node_cut":      0.0,
+                "fee_type":      "none",
+            }
+
+        # ── Base network fee (50/50 split) ────────────────────────
+        if tx_type == "fee":
+            return self._split(TRANSACTION_FEE)
+
+        # ── CID link fee (50/50 split) ────────────────────────────
+        if tx_type == "cv_link":
+            return self._split(CV_LINK_FEE)
+
+        # ── All standard user-facing tx types → 1 PLWB network fee
+        if tx_type in (
+            "transfer",             # PLWB transfer between any wallets
+            "content_register",     # register CID ownership
+            "ownership_transfer",   # transfer content (1:1 model)
+            "edition_transfer",     # transfer edition (creator model)
+            "node_register",        # platform registers on network
+        ):
+            return self._split(TRANSACTION_FEE)
+
+        # ── Redemption fee → 100% authority ──────────────────────
+        if tx_type == "plwb_redeem":
+            total = amount * PLWB_REDEMPTION_FEE
+            return {
+                "total":         total,
+                "authority_cut": total,
+                "node_cut":      0.0,
+                "fee_type":      "authority_only",
+            }
+
+        # ── No fee for unknown/other tx types ────────────────────
+        return {
+            "total":         0.0,
+            "authority_cut": 0.0,
+            "node_cut":      0.0,
+            "fee_type":      "none",
+        }
+
+    def _split(self, total: float) -> Dict:
+        """50/50 split between authority and node operator."""
+        authority_cut = round(total * FEE_SPLIT_AUTHORITY, 8)
+        node_cut      = round(total * FEE_SPLIT_NODE, 8)
+        return {
+            "total":         total,
+            "authority_cut": authority_cut,
+            "node_cut":      node_cut,
+            "fee_type":      "split",
+        }
+
+    # ─────────────────────────────────────────────────────────────
+    # Create fee transactions
+    # ─────────────────────────────────────────────────────────────
+
+    def create_fee_transactions(
+        self,
+        original_tx,
+        node_wallet: str,
+    ) -> List:
+        """
+        Create the fee transactions for a given original transaction.
+        Returns list of Transaction objects to add to the block.
+
+        Split fees → 2 transactions (authority + node)
+        Authority-only fees → 1 transaction (authority only)
+        No fee → []
+        """
+        from playweb.core.transaction import Transaction
+
+        fee_info = self.calculate_fee(original_tx.tx_type, original_tx.amount)
+
+        if fee_info["fee_type"] == "none":
+            return []
+
+        fee_txs = []
+
+        if fee_info["fee_type"] == "split":
+            # Authority cut
+            if fee_info["authority_cut"] > 0:
+                fee_txs.append(Transaction(
+                    from_addr = original_tx.from_addr,
+                    to_addr   = AUTHORITY_WALLET.lower(),
+                    amount    = fee_info["authority_cut"],
+                    tx_type   = "fee",
+                    nonce     = original_tx.nonce + 1,
+                    data      = {
+                        "fee_for":   original_tx.hash,
+                        "fee_split": "authority",
+                        "split_pct": FEE_SPLIT_AUTHORITY,
+                    }
+                ))
+
+            # Node operator cut
+            if fee_info["node_cut"] > 0 and node_wallet:
+                fee_txs.append(Transaction(
+                    from_addr = original_tx.from_addr,
+                    to_addr   = node_wallet.lower(),
+                    amount    = fee_info["node_cut"],
+                    tx_type   = "fee",
+                    nonce     = original_tx.nonce + 2,
+                    data      = {
+                        "fee_for":   original_tx.hash,
+                        "fee_split": "node",
+                        "split_pct": FEE_SPLIT_NODE,
+                    }
+                ))
+
+        elif fee_info["fee_type"] == "authority_only":
+            if fee_info["authority_cut"] > 0:
+                fee_txs.append(Transaction(
+                    from_addr = original_tx.from_addr,
+                    to_addr   = AUTHORITY_WALLET.lower(),
+                    amount    = fee_info["authority_cut"],
+                    tx_type   = "fee",
+                    nonce     = original_tx.nonce + 1,
+                    data      = {
+                        "fee_for":   original_tx.hash,
+                        "fee_split": "authority_only",
+                    }
+                ))
+
+        return fee_txs
+
+    # ─────────────────────────────────────────────────────────────
+    # Validate fee transactions in a block
+    # Called by every node during consensus
+    # This prevents fee manipulation
+    # ─────────────────────────────────────────────────────────────
+
+    def validate_fee_transactions(
+        self,
+        block,
+        node_wallet: str,
+    ) -> Tuple[bool, str]:
+        """
+        Validate that all fee transactions in a block are correct.
+        Every honest node runs this during consensus.
+        Returns (is_valid, reason).
+        """
+        transactions = block.transactions
+
+        # Build map of fee txs keyed by the tx they're paying for
+        fee_map: Dict[str, List] = {}
+        for tx in transactions:
+            if tx.tx_type == "fee":
+                fee_for = tx.data.get("fee_for") if tx.data else None
+                if fee_for:
+                    fee_map.setdefault(fee_for, []).append(tx)
+
+        # Validate each non-fee transaction
+        for tx in transactions:
+            if tx.tx_type == "fee":
+                continue
+
+            # Authority tx types never have fee transactions
+            if tx.tx_type in AUTHORITY_TX_TYPES:
+                continue
+
+            fee_info = self.calculate_fee(tx.tx_type, tx.amount)
+
+            if fee_info["fee_type"] == "none":
+                # Should have no fee transactions
+                if tx.hash in fee_map:
+                    return False, f"Unexpected fee for tx {tx.hash[:12]}"
+                continue
+
+            fees = fee_map.get(tx.hash, [])
+
+            if fee_info["fee_type"] == "split":
+                if len(fees) != 2:
+                    return (
+                        False,
+                        f"Expected 2 fee txs for {tx.hash[:12]}, "
+                        f"got {len(fees)}"
+                    )
+            
+                # Validate total fee amount is correct
+                total_fee_paid = sum(f.amount for f in fees)
+                expected_total = fee_info["total"]
+                if round(total_fee_paid, 8) != round(expected_total, 8):
+                    return (
+                        False,
+                        f"Wrong total fee for {tx.hash[:12]}: "
+                        f"expected {expected_total}, got {total_fee_paid}"
+                    )
+            
+                # When authority wallet == node wallet (same address)
+                # both fee txs go to same wallet — that's correct
+                if AUTHORITY_WALLET.lower() == node_wallet.lower():
+                    # Both fees go to same wallet — just check amounts
+                    assert len(fees) == 2
+                    for f in fees:
+                        if f.to_addr != AUTHORITY_WALLET.lower():
+                            return (
+                                False,
+                                f"Fee going to wrong wallet: {f.to_addr}"
+                            )
+                else:
+                    # Different wallets — check 50/50 split properly
+                    auth_fees = [
+                        f for f in fees
+                        if f.to_addr == AUTHORITY_WALLET.lower()
+                    ]
+                    node_fees = [
+                        f for f in fees
+                        if f.to_addr == node_wallet.lower()
+                    ]
+            
+                    if len(auth_fees) != 1:
+                        return (
+                            False,
+                            f"Missing authority fee for tx {tx.hash[:12]}"
+                        )
+                    if len(node_fees) != 1:
+                        return (
+                            False,
+                            f"Missing node fee for tx {tx.hash[:12]}"
+                        )
+            
+                    expected_auth = round(fee_info["total"] * FEE_SPLIT_AUTHORITY, 8)
+                    expected_node = round(fee_info["total"] * FEE_SPLIT_NODE, 8)
+            
+                    if round(auth_fees[0].amount, 8) != expected_auth:
+                        return (
+                            False,
+                            f"Wrong authority fee: expected {expected_auth}, "
+                            f"got {auth_fees[0].amount}"
+                        )
+                    if round(node_fees[0].amount, 8) != expected_node:
+                        return (
+                            False,
+                            f"Wrong node fee: expected {expected_node}, "
+                            f"got {node_fees[0].amount}"
+                        )
+
+            elif fee_info["fee_type"] == "authority_only":
+                if len(fees) != 1:
+                    return (
+                        False,
+                        f"Expected 1 fee tx for {tx.hash[:12]}, "
+                        f"got {len(fees)}"
+                    )
+                if fees[0].to_addr != AUTHORITY_WALLET.lower():
+                    return (
+                        False,
+                        f"Authority-only fee going to wrong wallet: "
+                        f"{fees[0].to_addr}"
+                    )
+
+        return True, "Valid"
+
+    def get_required_balance_for_tx(
+        self,
+        tx_type: str,
+        amount: float,
+    ) -> float:
+        """How much PLWB does sender need? amount + all fees."""
+        fee_info = self.calculate_fee(tx_type, amount)
+        return amount + fee_info["total"]

playweb/core/mempool.py

@@ -0,0 +1,112 @@
+"""
+PlayWebit Network — Mempool
+Pending transactions — lives in RAM only.
+Lost on restart — peers will resend. That's fine.
+"""
+
+import time
+import logging
+from typing import Dict, List, Optional
+
+from playweb.core.transaction import Transaction
+from playweb.config import MAX_TX_PER_BLOCK
+
+logger = logging.getLogger(__name__)
+
+# Max age of a pending transaction before it's dropped (10 minutes)
+TX_MAX_AGE = 600
+
+
+class Mempool:
+
+    def __init__(self):
+        # tx_hash → Transaction
+        self._pool: Dict[str, Transaction] = {}
+
+    # ─────────────────────────────────────────────────────────────
+    # Add
+    # ─────────────────────────────────────────────────────────────
+
+    def add(self, tx: Transaction) -> tuple[bool, str]:
+        """
+        Add a transaction to the mempool.
+        Returns (success, reason).
+        """
+        if tx.hash in self._pool:
+            return False, "Transaction already in mempool"
+
+        valid, reason = tx.validate_fields()
+        if not valid:
+            return False, reason
+
+        self._pool[tx.hash] = tx
+        logger.debug(f"Mempool: added {tx.hash[:12]} ({tx.tx_type})")
+        return True, "Added"
+
+    # ─────────────────────────────────────────────────────────────
+    # Get
+    # ─────────────────────────────────────────────────────────────
+
+    def get_pending(self, limit: int = MAX_TX_PER_BLOCK) -> List[Transaction]:
+        """
+        Return pending transactions sorted by timestamp (oldest first).
+        Automatically drops expired transactions.
+        """
+        self._drop_expired()
+        txs = sorted(self._pool.values(), key=lambda tx: tx.timestamp)
+        return txs[:limit]
+
+    def get(self, tx_hash: str) -> Optional[Transaction]:
+        return self._pool.get(tx_hash)
+
+    def contains(self, tx_hash: str) -> bool:
+        return tx_hash in self._pool
+
+    def size(self) -> int:
+        return len(self._pool)
+
+    # ─────────────────────────────────────────────────────────────
+    # Remove
+    # ─────────────────────────────────────────────────────────────
+
+    def remove(self, tx_hash: str):
+        """Remove a transaction after it's been included in a block."""
+        if tx_hash in self._pool:
+            del self._pool[tx_hash]
+            logger.debug(f"Mempool: removed {tx_hash[:12]}")
+
+    def remove_batch(self, tx_hashes: List[str]):
+        """Remove multiple transactions at once after block is finalised."""
+        for h in tx_hashes:
+            self.remove(h)
+
+    def clear(self):
+        self._pool.clear()
+        logger.debug("Mempool: cleared")
+
+    # ─────────────────────────────────────────────────────────────
+    # Maintenance
+    # ─────────────────────────────────────────────────────────────
+
+    def _drop_expired(self):
+        """Drop transactions older than TX_MAX_AGE seconds."""
+        now     = time.time()
+        expired = [
+            h for h, tx in self._pool.items()
+            if now - tx.timestamp > TX_MAX_AGE
+        ]
+        for h in expired:
+            del self._pool[h]
+            logger.debug(f"Mempool: expired {h[:12]}")
+
+    def get_stats(self) -> Dict:
+        return {
+            "pending_count": self.size(),
+            "oldest_tx":     min(
+                (tx.timestamp for tx in self._pool.values()),
+                default=None
+            ),
+        }
+
+    def __repr__(self):
+        return f"Mempool(pending={self.size()})"

playweb/core/royalty_engine.py

@@ -0,0 +1,207 @@
+"""
+PlayWebit Network — Royalty Engine
+Enforces creator royalties at protocol level.
+Set at mint time, enforced on every resale — forever.
+Platforms cannot bypass this. Consensus rejects blocks that do.
+"""
+
+import logging
+from typing import Dict, List, Tuple, Optional
+
+logger = logging.getLogger(__name__)
+
+
+class RoyaltyEngine:
+
+    def __init__(self, storage):
+        """
+        storage — any ChainStorage implementation.
+        Reads content_registry to get creator + royalty_pct per CID.
+        """
+        self.storage = storage
+
+    # ─────────────────────────────────────────────────────────────
+    # Get royalty info
+    # ─────────────────────────────────────────────────────────────
+
+    def get_royalty(self, cid: str) -> Optional[Dict]:
+        """
+        Get royalty info for a CID from the content registry.
+        Returns:
+            {
+                creator_wallet: str,
+                royalty_pct:    float,
+                cid:            str,
+            }
+        or None if CID not registered.
+        """
+        record = self.storage.get_content_record(cid)
+        if not record:
+            return None
+
+        return {
+            "creator_wallet": record.get("creator_wallet"),
+            "royalty_pct":    record.get("royalty_pct", 0),
+            "cid":            cid,
+        }
+
+    # ─────────────────────────────────────────────────────────────
+    # Calculate split
+    # ─────────────────────────────────────────────────────────────
+
+    def calculate_split(
+        self,
+        cid:        str,
+        sale_price: float,
+    ) -> Dict:
+        """
+        Calculate how a sale price splits between creator and seller.
+        Returns:
+            {
+                creator_wallet:  str,
+                royalty_pct:     float,
+                creator_amount:  float,   # royalty to original creator
+                seller_amount:   float,   # remainder to seller
+                sale_price:      float,
+            }
+        """
+        royalty = self.get_royalty(cid)
+
+        if not royalty or royalty["royalty_pct"] == 0:
+            return {
+                "creator_wallet":  royalty["creator_wallet"] if royalty else None,
+                "royalty_pct":     0,
+                "creator_amount":  0.0,
+                "seller_amount":   sale_price,
+                "sale_price":      sale_price,
+            }
+
+        royalty_pct    = royalty["royalty_pct"]
+        creator_amount = round(sale_price * (royalty_pct / 100), 8)
+        seller_amount  = round(sale_price - creator_amount, 8)
+
+        return {
+            "creator_wallet":  royalty["creator_wallet"],
+            "royalty_pct":     royalty_pct,
+            "creator_amount":  creator_amount,
+            "seller_amount":   seller_amount,
+            "sale_price":      sale_price,
+        }
+
+    # ─────────────────────────────────────────────────────────────
+    # Create royalty transactions
+    # ─────────────────────────────────────────────────────────────
+
+    def create_royalty_transactions(
+        self,
+        cid:          str,
+        sale_price:   float,
+        buyer_wallet: str,
+        seller_wallet: str,
+        base_nonce:   int = 0,
+    ) -> List:
+        """
+        Create the transactions for a resale.
+        Returns [creator_royalty_tx, seller_payment_tx]
+
+        Both go on chain. Consensus validates they're correct.
+        """
+        from playweb.core.transaction import Transaction
+
+        split = self.calculate_split(cid, sale_price)
+        txs   = []
+
+        # Royalty to original creator
+        if split["creator_amount"] > 0 and split["creator_wallet"]:
+            txs.append(Transaction(
+                from_addr = buyer_wallet.lower(),
+                to_addr   = split["creator_wallet"].lower(),
+                amount    = split["creator_amount"],
+                tx_type   = "ownership_transfer",
+                nonce     = base_nonce + 1,
+                cid       = cid,
+                data      = {
+                    "royalty":      True,
+                    "royalty_pct":  split["royalty_pct"],
+                    "sale_price":   sale_price,
+                    "seller":       seller_wallet,
+                }
+            ))
+
+        # Payment to seller
+        if split["seller_amount"] > 0:
+            txs.append(Transaction(
+                from_addr = buyer_wallet.lower(),
+                to_addr   = seller_wallet.lower(),
+                amount    = split["seller_amount"],
+                tx_type   = "ownership_transfer",
+                nonce     = base_nonce + 2,
+                cid       = cid,
+                data      = {
+                    "royalty":      False,
+                    "royalty_pct":  split["royalty_pct"],
+                    "sale_price":   sale_price,
+                    "creator_cut":  split["creator_amount"],
+                }
+            ))
+
+        return txs
+
+    # ─────────────────────────────────────────────────────────────
+    # Validate royalty transactions in a block
+    # Called by every node during consensus
+    # ─────────────────────────────────────────────────────────────
+
+    def validate_royalty_transactions(
+        self,
+        block,
+    ) -> Tuple[bool, str]:
+        """
+        Validate that royalty payments in a block are correct.
+        Every honest node runs this during consensus.
+
+        Checks:
+          1. Royalty goes to the correct original creator
+          2. Royalty amount matches the registered royalty_pct
+          3. Creator cannot be changed after minting
+
+        Returns (is_valid, reason).
+        """
+        for tx in block.transactions:
+            if tx.tx_type != "ownership_transfer":
+                continue
+            if not tx.data:
+                continue
+            if not tx.data.get("royalty"):
+                continue
+
+            # This is a royalty payment — validate it
+            cid = tx.cid
+            if not cid:
+                return False, f"Royalty tx {tx.hash[:12]} missing cid"
+
+            royalty = self.get_royalty(cid)
+            if not royalty:
+                return False, f"CID {cid} not in content registry"
+
+            # Creator wallet must match
+            if tx.to_addr != royalty["creator_wallet"].lower():
+                return (
+                    False,
+                    f"Royalty going to wrong wallet for {cid}: "
+                    f"expected {royalty['creator_wallet']}, "
+                    f"got {tx.to_addr}"
+                )
+
+            # Royalty amount must match
+            sale_price = tx.data.get("sale_price", 0)
+            if sale_price > 0:
+                expected = round(sale_price * (royalty["royalty_pct"] / 100), 8)
+                if round(tx.amount, 8) != expected:
+                    return (
+                        False,
+                        f"Wrong royalty amount for {cid}: "
+                        f"expected {expected}, got {tx.amount}"
+                    )
+
+        return True, "Valid"