playweb-node 1.0.0__py3-none-any.whl

playweb/node.py

@@ -0,0 +1,303 @@
+"""
+PlayWebit Network — PlayWebitNode
+Main entry point for running a full validator node.
+Wires all components together.
+
+Usage:
+    from playweb import PlayWebitNode
+    from playweb.storage.supabase_storage import SupabaseStorage
+
+    storage = SupabaseStorage(url=..., key=...)
+    node = PlayWebitNode(
+        storage          = storage,
+        node_wallet      = "0xYourWallet",
+        node_private_key = os.getenv("NODE_WALLET_PRIVATE_KEY"),
+        node_public_url  = "https://your-node.com",
+    )
+    node.start()
+"""
+
+import os
+import time
+import logging
+import threading
+from typing import Optional, TYPE_CHECKING
+
+from playweb.core.blockchain          import Blockchain
+from playweb.core.fee_engine          import FeeEngine
+from playweb.core.royalty_engine      import RoyaltyEngine
+from playweb.consensus.nvf_bft        import NVFBFTConsensus
+from playweb.network.peer_manager     import PeerManager
+from playweb.network.bootstrap        import Bootstrap
+from playweb.network.gossip           import GossipProtocol
+from playweb.network.sync             import ChainSync
+from playweb.registry.content_registry import ContentRegistry
+from playweb.registry.edition_registry import EditionRegistry
+from playweb.plugin.plugin_manager    import PluginManager
+from playweb.config                   import LOG_LEVEL, NODE_PORT
+
+if TYPE_CHECKING:
+    from playweb.plugin.base_plugin import BasePlugin
+    from playweb.storage.base       import ChainStorage
+
+logging.basicConfig(
+    level   = getattr(logging, LOG_LEVEL, logging.INFO),
+    format  = "%(asctime)s [%(name)s] %(levelname)s: %(message)s",
+)
+logger = logging.getLogger(__name__)
+
+
+class PlayWebitNode:
+
+    def __init__(
+        self,
+        storage,
+        node_wallet:      str,
+        node_private_key: str,
+        node_public_url:  str,
+        platform:         str           = "unknown",
+        plugin:           Optional["BasePlugin"] = None,
+        port:             int           = NODE_PORT,
+    ):
+        self.node_wallet     = node_wallet.lower()
+        self.node_private_key = node_private_key
+        self.node_url        = node_public_url.rstrip("/")
+        self.platform        = platform
+        self.port            = port
+
+        # ── Core ────────────────────────────────────────────────
+        self.blockchain = Blockchain(storage)
+
+        # ── Registries ──────────────────────────────────────────
+        self.content_registry = ContentRegistry(self.blockchain, self.node_wallet)
+        self.edition_registry = EditionRegistry(self.blockchain, self.node_wallet)
+
+        # ── Network ─────────────────────────────────────────────
+        self.peer_manager = PeerManager(self.node_url, self.node_wallet)
+        self.gossip       = GossipProtocol(self.node_wallet)
+        self.bootstrap    = Bootstrap(
+            node_url         = self.node_url,
+            node_wallet      = self.node_wallet,
+            node_private_key = self.node_private_key,
+            platform         = self.platform,
+        )
+        self.sync = ChainSync(self.blockchain, self.peer_manager)
+
+        # ── Plugins ─────────────────────────────────────────────
+        self.plugin_manager = PluginManager()
+        self.plugin_manager.set_node(self)
+
+        # ── Consensus ───────────────────────────────────────────
+        self.consensus = NVFBFTConsensus(
+            blockchain         = self.blockchain,
+            peer_manager       = self.peer_manager,
+            gossip             = self.gossip,
+            node_wallet        = self.node_wallet,
+            node_private_key   = self.node_private_key,
+            plugin_manager     = self.plugin_manager,
+            on_block_finalised = self._on_block_finalised,
+        )
+
+        # Register plugin if provided
+        if plugin:
+            self.register_plugin(plugin)
+
+        self._flask_app  = None
+        self._flask_thread: Optional[threading.Thread] = None
+        self._running    = False
+
+        logger.info(
+            f"PlayWebitNode initialised: "
+            f"wallet={self.node_wallet[:12]}... "
+            f"url={self.node_url}"
+        )
+
+    # ─────────────────────────────────────────────────────────────
+    # Plugin registration
+    # ─────────────────────────────────────────────────────────────
+
+    def register_plugin(self, plugin: "BasePlugin"):
+        """Register a L2 plugin with this node."""
+        self.plugin_manager.register(plugin)
+
+    # ─────────────────────────────────────────────────────────────
+    # Start
+    # ─────────────────────────────────────────────────────────────
+
+    def start(self, blocking: bool = True):
+        """
+        Start the node:
+          1. Discover peers via Cloudflare bootstrap
+          2. Register self with bootstrap directory
+          3. Sync chain from peers
+          4. Start Flask API server
+          5. Start NVF-BFT consensus loop
+          6. Start heartbeat
+          7. Notify plugins
+        """
+        self._running = True
+        logger.info("=" * 50)
+        logger.info("PlayWebit Network Node Starting...")
+        logger.info(f"  Wallet:   {self.node_wallet}")
+        logger.info(f"  URL:      {self.node_url}")
+        logger.info(f"  Platform: {self.platform}")
+        logger.info("=" * 50)
+
+        # Step 1: Discover peers
+        logger.info("Step 1/6: Discovering peers via bootstrap...")
+        peers = self.bootstrap.discover_peers()
+        self.peer_manager.load_peers_from_list(peers)
+        logger.info(f"  Found {len(peers)} peers")
+
+        # Step 2: Register with Cloudflare bootstrap
+        logger.info("Step 2/6: Registering with bootstrap directory...")
+        self.bootstrap.register_node()
+
+        # Step 3: Sync chain
+        logger.info("Step 3/6: Syncing chain from peers...")
+        self.sync.sync()
+        tip = self.blockchain.get_chain_tip()
+        logger.info(
+            f"  Chain synced. Height: {tip.index if tip else 0}"
+        )
+
+        # Step 4: Start Flask API
+        logger.info(f"Step 4/6: Starting API server on port {self.port}...")
+        self._start_flask()
+
+        # Step 5: Start consensus
+        logger.info("Step 5/6: Starting NVF-BFT consensus...")
+        self.consensus.start()
+
+        # Step 6: Start heartbeat
+        logger.info("Step 6/6: Starting bootstrap heartbeat...")
+        self.bootstrap.start_heartbeat()
+
+        # Notify plugins
+        self.plugin_manager.notify_start(self)
+
+        logger.info("=" * 50)
+        logger.info("Node is live and participating in consensus!")
+        logger.info("=" * 50)
+
+        if blocking:
+            try:
+                while self._running:
+                    time.sleep(1)
+            except KeyboardInterrupt:
+                self.stop()
+
+    def stop(self):
+        """Graceful shutdown."""
+        logger.info("Node shutting down...")
+        self._running = False
+        self.consensus.stop()
+        self.bootstrap.deregister()
+        self.plugin_manager.notify_stop()
+        logger.info("Node stopped.")
+
+    # ─────────────────────────────────────────────────────────────
+    # Flask API server
+    # ─────────────────────────────────────────────────────────────
+
+    def _start_flask(self):
+        """Start Flask in a background thread."""
+        from flask import Flask
+        from playweb.api.node_api   import create_node_api
+        from playweb.api.public_api import create_public_api
+        from playweb.api.rpc      import create_rpc
+        from playweb.api.metadata import create_metadata_api
+
+        app = Flask(__name__)
+        app.register_blueprint(create_node_api(self))
+        app.register_blueprint(create_public_api(self))
+        app.register_blueprint(create_rpc(self))
+        app.register_blueprint(create_metadata_api(self))
+
+        self._flask_app = app
+
+        self._flask_thread = threading.Thread(
+            target=lambda: app.run(
+                host    = "0.0.0.0",
+                port    = self.port,
+                debug   = False,
+                use_reloader = False,
+            ),
+            daemon = True,
+            name   = "flask-api",
+        )
+        self._flask_thread.start()
+        logger.info(f"API server started on port {self.port}")
+
+    def get_flask_app(self):
+        """
+        Get the Flask app for external mounting.
+        Use this if you want to add your own routes on top.
+        Returns the Flask app instance.
+        """
+        if not self._flask_app:
+            from flask import Flask
+            from playweb.api.node_api   import create_node_api
+            from playweb.api.public_api import create_public_api
+
+            app = Flask(__name__)
+            app.register_blueprint(create_node_api(self))
+            app.register_blueprint(create_public_api(self))
+            self._flask_app = app
+
+        return self._flask_app
+
+    # ─────────────────────────────────────────────────────────────
+    # Consensus callback
+    # ─────────────────────────────────────────────────────────────
+
+    def _on_block_finalised(self, block, votes):
+        """
+        Called by consensus after a block is finalised.
+        Broadcasts to peers so they can add it to their chain.
+        NVF: Cyclic re-entry notification complete.
+        """
+        self.gossip.broadcast_finalised_block(
+            block = block,
+            votes = votes,
+            peers = self.peer_manager.get_active_peers(),
+        )
+
+    # ─────────────────────────────────────────────────────────────
+    # Convenience methods
+    # ─────────────────────────────────────────────────────────────
+
+    def submit_transaction(self, tx, broadcast: bool = True):
+        """Submit a transaction and optionally broadcast to peers."""
+        success, result = self.blockchain.add_transaction(
+            tx          = tx,
+            node_wallet = self.node_wallet,
+        )
+        if success and broadcast:
+            self.gossip.broadcast_transaction(
+                tx    = tx,
+                peers = self.peer_manager.get_active_peers(),
+            )
+        return success, result
+
+    def get_balance(self, address: str) -> float:
+        return self.blockchain.get_balance(address)
+
+    def get_block(self, block_hash: str):
+        return self.blockchain.get_block(block_hash)
+
+    def get_chain_tip(self):
+        return self.blockchain.get_chain_tip()
+
+    def get_status(self) -> dict:
+        tip = self.blockchain.get_chain_tip()
+        return {
+            "node_wallet":  self.node_wallet,
+            "node_url":     self.node_url,
+            "platform":     self.platform,
+            "block_height": tip.index if tip else 0,
+            "peer_count":   self.peer_manager.peer_count(),
+            "consensus":    self.consensus.get_status(),
+            "sync":         self.sync.get_sync_status(),
+            "plugins":      self.plugin_manager.get_status(),
+        }

playweb/plugin/__init__.py

@@ -0,0 +1,4 @@
+from playweb.plugin.base_plugin    import BasePlugin
+from playweb.plugin.plugin_manager import PluginManager
+
+__all__ = ["BasePlugin", "PluginManager"]

playweb/plugin/base_plugin.py

@@ -0,0 +1,225 @@
+"""
+PlayWebit Network — Base Plugin Interface
+L2 apps implement this to plug into a PlayWebit node.
+CipherVault, MusicApp, ArtApp etc all implement BasePlugin.
+
+The plugin gets:
+  - Event hooks from L1 (on_block_finalised, on_transaction etc)
+  - SDK interface to call L1 (submit_tx, get_balance etc)
+  - Clean separation — plugin cannot touch L1 internals directly
+"""
+
+from abc import ABC, abstractmethod
+from typing import Optional, Dict, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from playweb.core.block       import Block
+    from playweb.core.transaction import Transaction
+
+
+class BasePlugin(ABC):
+
+    # ─────────────────────────────────────────────────────────────
+    # Plugin identity — subclass must set these
+    # ─────────────────────────────────────────────────────────────
+
+    plugin_id:       str = "base"         # e.g. "ciphervault"
+    plugin_name:     str = "Base Plugin"  # e.g. "CipherVault"
+    plugin_version:  str = "1.0.0"
+    platform_wallet: str = ""             # plugin's PLWB treasury wallet
+
+    def __init__(self):
+        self._node = None   # set by plugin_manager on register
+
+    def _set_node(self, node):
+        """Called by PluginManager when plugin is registered."""
+        self._node = node
+
+    # ─────────────────────────────────────────────────────────────
+    # Lifecycle hooks — L1 calls these
+    # ─────────────────────────────────────────────────────────────
+
+    def on_start(self, node):
+        """
+        Called when the node starts up.
+        Use this to initialise your plugin's own state.
+        """
+        pass
+
+    def on_stop(self):
+        """Called when the node shuts down gracefully."""
+        pass
+
+    def on_block_finalised(self, block: "Block"):
+        """
+        Called after every block is finalised by consensus.
+        NVF: Cyclic re-entry notification.
+        Use this to update your L2 state from confirmed transactions.
+        """
+        pass
+
+    def on_transaction(self, tx: "Transaction"):
+        """
+        Called when a new transaction is confirmed on chain.
+        Note: also fires via on_block_finalised for each tx in block.
+        """
+        pass
+
+    def on_content_registered(self, cid: str, owner: str, platform: str):
+        """Called when new content is registered on the network."""
+        pass
+
+    def on_edition_transferred(
+        self,
+        cid:            str,
+        edition_number: int,
+        from_wallet:    str,
+        to_wallet:      str,
+    ):
+        """Called when an edition changes hands."""
+        pass
+
+    # ─────────────────────────────────────────────────────────────
+    # SDK interface — plugin calls L1 via these
+    # These are convenience wrappers around node methods
+    # ─────────────────────────────────────────────────────────────
+
+    def submit_transaction(self, tx: "Transaction") -> tuple:
+        """Submit a transaction to L1. Returns (success, tx_hash_or_reason)."""
+        if not self._node:
+            return False, "Plugin not attached to node"
+        return self._node.blockchain.add_transaction(
+            tx          = tx,
+            node_wallet = self._node.node_wallet,
+        )
+
+    def get_balance(self, address: str) -> float:
+        """Get PLWB balance for any address."""
+        if not self._node:
+            return 0.0
+        return self._node.blockchain.get_balance(address)
+
+    def register_content(
+        self,
+        cid:          str,
+        owner_wallet: str,
+        editions:     int   = 1,
+        royalty_pct:  float = 0,
+        signature:    str   = None,
+        extra_data:   Dict  = None,
+    ) -> tuple:
+        """Register a CID on the network. Returns (success, reason, tx_hash)."""
+        if not self._node:
+            return False, "Plugin not attached to node", None
+        return self._node.content_registry.register(
+            cid          = cid,
+            owner_wallet = owner_wallet,
+            platform_id  = self.plugin_id,
+            editions     = editions,
+            royalty_pct  = royalty_pct,
+            signature    = signature,
+            extra_data   = extra_data,
+        )
+
+    def transfer_ownership(
+        self,
+        cid:         str,
+        from_wallet: str,
+        to_wallet:   str,
+        signature:   str   = None,
+        sale_price:  float = 0,
+    ) -> tuple:
+        """Transfer ownership of a CID. Returns (success, reason, tx_hash)."""
+        if not self._node:
+            return False, "Plugin not attached to node", None
+        return self._node.content_registry.transfer_ownership(
+            cid         = cid,
+            from_wallet = from_wallet,
+            to_wallet   = to_wallet,
+            signature   = signature,
+            platform_id = self.plugin_id,
+            sale_price  = sale_price,
+        )
+
+    def verify_ownership(self, cid: str, wallet: str) -> bool:
+        """Verify wallet owns a CID."""
+        if not self._node:
+            return False
+        return self._node.content_registry.verify_ownership(cid, wallet)
+
+    def check_duplicate(self, cid: str) -> Dict:
+        """Check if CID is already registered anywhere on the network."""
+        if not self._node:
+            return {"exists": False}
+        return self._node.content_registry.check_duplicate(cid)
+
+    def anchor_spider_hash(
+        self,
+        chain_name:  str,
+        spider_hash: str,
+        event_type:  str  = "integrity_check",
+        metadata:    Dict = None,
+        signature:   str  = None,
+    ) -> tuple:
+        """
+        Anchor a SpiderWeave hash on the chain.
+        This is what spiderweave-sdk calls internally.
+        Returns (success, tx_hash).
+        """
+        if not self._node:
+            return False, "Plugin not attached to node"
+
+        from playweb.core.transaction import Transaction
+        tx = Transaction(
+            from_addr   = self.platform_wallet.lower(),
+            to_addr     = self.platform_wallet.lower(),
+            amount      = 0,
+            tx_type     = "spider_hash_anchor",
+            signature   = signature,
+            spider_hash = spider_hash,
+            chain_name  = chain_name,
+            data        = {
+                "event_type":  event_type,
+                "platform_id": self.plugin_id,
+                **(metadata or {}),
+            },
+        )
+        success, result = self.submit_transaction(tx)
+        return success, result
+
+    def get_editions(self, cid: str) -> list:
+        """Get all editions for a CID."""
+        if not self._node:
+            return []
+        return self._node.edition_registry.get_all_editions(cid)
+
+    def get_nft_metadata(self, cid: str, chain_record: dict) -> dict:
+        """
+        Optional: enrich NFT metadata for MetaMask display.
+        Called by /api/metadata/{cid} endpoint.
+    
+        Return dict to merge with default metadata:
+        {
+            "name":       "My File Name",
+            "image":      "data:image/jpeg;base64,...",  or IPFS URL
+            "attributes": [...additional attributes...]
+        }
+    
+        Return None to use default chain metadata only.
+        """
+        return None
+
+    # ─────────────────────────────────────────────────────────────
+    # Plugin info
+    # ─────────────────────────────────────────────────────────────
+
+    def get_info(self) -> Dict:
+        return {
+            "plugin_id":      self.plugin_id,
+            "plugin_name":    self.plugin_name,
+            "plugin_version": self.plugin_version,
+            "platform_wallet": self.platform_wallet,
+        }
+
+    def __repr__(self):
+        return f"Plugin({self.plugin_id} v{self.plugin_version})"

playweb/plugin/plugin_manager.py

@@ -0,0 +1,131 @@
+"""
+PlayWebit Network — Plugin Manager
+Loads and manages L2 plugins.
+Notifies all registered plugins when L1 events happen.
+"""
+
+import logging
+from typing import Dict, List, Optional, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from playweb.plugin.base_plugin import BasePlugin
+    from playweb.core.block         import Block
+    from playweb.core.transaction   import Transaction
+
+logger = logging.getLogger(__name__)
+
+
+class PluginManager:
+
+    def __init__(self):
+        self._plugins: Dict[str, "BasePlugin"] = {}
+        self._node = None
+
+    def set_node(self, node):
+        self._node = node
+
+    # ─────────────────────────────────────────────────────────────
+    # Register plugins
+    # ─────────────────────────────────────────────────────────────
+
+    def register(self, plugin: "BasePlugin"):
+        """Register a L2 plugin with this node."""
+        if plugin.plugin_id in self._plugins:
+            logger.warning(
+                f"Plugin {plugin.plugin_id} already registered — replacing"
+            )
+
+        plugin._set_node(self._node)
+        self._plugins[plugin.plugin_id] = plugin
+        logger.info(
+            f"Plugin registered: {plugin.plugin_name} "
+            f"(v{plugin.plugin_version})"
+        )
+
+    def get_plugin(self, plugin_id: str) -> Optional["BasePlugin"]:
+        return self._plugins.get(plugin_id)
+
+    def get_all_plugins(self) -> List["BasePlugin"]:
+        return list(self._plugins.values())
+
+    # ─────────────────────────────────────────────────────────────
+    # Lifecycle notifications
+    # ─────────────────────────────────────────────────────────────
+
+    def notify_start(self, node):
+        """Notify all plugins that the node has started."""
+        for plugin in self._plugins.values():
+            try:
+                plugin.on_start(node)
+            except Exception as e:
+                logger.error(
+                    f"Plugin {plugin.plugin_id} on_start error: {e}",
+                    exc_info=True
+                )
+
+    def notify_stop(self):
+        """Notify all plugins that the node is stopping."""
+        for plugin in self._plugins.values():
+            try:
+                plugin.on_stop()
+            except Exception as e:
+                logger.error(f"Plugin {plugin.plugin_id} on_stop error: {e}")
+
+    # ─────────────────────────────────────────────────────────────
+    # Block / Transaction notifications
+    # NVF: Cyclic re-entry
+    # ─────────────────────────────────────────────────────────────
+
+    def notify_block_finalised(self, block: "Block"):
+        """
+        Notify all plugins that a block has been finalised.
+        NVF paper: Cyclic re-entry notification after ANCHOR phase.
+        Each plugin processes transactions relevant to their platform.
+        """
+        for plugin in self._plugins.values():
+            try:
+                plugin.on_block_finalised(block)
+
+                # Also notify per-transaction
+                for tx in block.transactions:
+                    plugin.on_transaction(tx)
+
+                    # Special hooks for content events
+                    if tx.tx_type == "content_register" and tx.cid:
+                        plugin.on_content_registered(
+                            cid      = tx.cid,
+                            owner    = tx.to_addr,
+                            platform = tx.data.get("platform_id", "unknown")
+                            if tx.data else "unknown",
+                        )
+
+                    elif tx.tx_type == "edition_transfer" and tx.cid:
+                        plugin.on_edition_transferred(
+                            cid            = tx.cid,
+                            edition_number = tx.edition_number or 0,
+                            from_wallet    = tx.from_addr,
+                            to_wallet      = tx.to_addr,
+                        )
+
+            except Exception as e:
+                logger.error(
+                    f"Plugin {plugin.plugin_id} block notification error: {e}",
+                    exc_info=True,
+                )
+                # Never let a plugin crash the node
+
+    def notify_transaction(self, tx: "Transaction"):
+        """Notify all plugins of a new transaction (before block)."""
+        for plugin in self._plugins.values():
+            try:
+                plugin.on_transaction(tx)
+            except Exception as e:
+                logger.error(
+                    f"Plugin {plugin.plugin_id} tx notification error: {e}"
+                )
+
+    def get_status(self) -> Dict:
+        return {
+            "plugin_count": len(self._plugins),
+            "plugins": [p.get_info() for p in self._plugins.values()],
+        }

playweb/registry/__init__.py

@@ -0,0 +1,4 @@
+from playweb.registry.content_registry import ContentRegistry
+from playweb.registry.edition_registry import EditionRegistry
+
+__all__ = ["ContentRegistry", "EditionRegistry"]