koi-net 1.0.0b18__py3-none-any.whl → 1.1.0b1__py3-none-any.whl

koi_net/processor/interface.py

@@ -1,57 +1,31 @@
 import logging
 import queue
 import threading
-from typing import Callable, Generic
-from rid_lib.core import RID, RIDType
-from rid_lib.ext import Bundle, Cache, Manifest
-from rid_lib.types.koi_net_edge import KoiNetEdge
-from rid_lib.types.koi_net_node import KoiNetNode
-from ..identity import NodeIdentity
-from ..network import NetworkInterface
+from rid_lib.core import RID
+from rid_lib.ext import Bundle, Manifest
+from rid_lib.types import KoiNetNode
 from ..protocol.event import Event, EventType
-from ..config import NodeConfig
-from .handler import (
-    KnowledgeHandler, 
-    HandlerType, 
-    STOP_CHAIN,
-    StopChain
-)
-from .knowledge_object import (
-    KnowledgeObject,
-    KnowledgeSource, 
-    KnowledgeEventType
-)
+from .knowledge_object import KnowledgeObject
+from .knowledge_pipeline import KnowledgePipeline
+
 
 logger = logging.getLogger(__name__)
 
 
-class ProcessorInterface():
+class ProcessorInterface:
     """Provides access to this node's knowledge processing pipeline."""
-    
-    config: NodeConfig
-    cache: Cache
-    network: NetworkInterface
-    identity: NodeIdentity
-    handlers: list[KnowledgeHandler]
+    pipeline: KnowledgePipeline
     kobj_queue: queue.Queue[KnowledgeObject]
     use_kobj_processor_thread: bool
     worker_thread: threading.Thread | None = None
     
     def __init__(
         self,
-        config: NodeConfig,
-        cache: Cache, 
-        network: NetworkInterface,
-        identity: NodeIdentity,
+        pipeline: KnowledgePipeline,
         use_kobj_processor_thread: bool,
-        default_handlers: list[KnowledgeHandler] = []
     ):
-        self.config = config
-        self.cache = cache
-        self.network = network
-        self.identity = identity
+        self.pipeline = pipeline
         self.use_kobj_processor_thread = use_kobj_processor_thread
-        self.handlers: list[KnowledgeHandler] = default_handlers
         self.kobj_queue = queue.Queue()
         
         if self.use_kobj_processor_thread:
@@ -59,180 +33,7 @@ class ProcessorInterface():
                 target=self.kobj_processor_worker,
                 daemon=True
             )
-        
-    def add_handler(self, handler: KnowledgeHandler):
-        self.handlers.append(handler)
-            
-    def register_handler(
-        self,
-        handler_type: HandlerType,
-        rid_types: list[RIDType] | None = None,
-        source: KnowledgeSource | None = None,
-        event_types: list[KnowledgeEventType] | None = None
-    ):
-        """Assigns decorated function as handler for this processor."""
-        def decorator(func: Callable) -> Callable:
-            handler = KnowledgeHandler(func, handler_type, rid_types, source, event_types)
-            self.add_handler(handler)
-            return func
-        return decorator
-            
-    def call_handler_chain(
-        self, 
-        handler_type: HandlerType,
-        kobj: KnowledgeObject
-    ) -> KnowledgeObject | StopChain:
-        """Calls handlers of provided type, chaining their inputs and outputs together.
-        
-        The knowledge object provided when this function is called will be passed to the first handler. A handler may return one of three types: 
-        - `KnowledgeObject` - to modify the knowledge object for the next handler in the chain
-        - `None` - to keep the same knowledge object for the next handler in the chain
-        - `STOP_CHAIN` - to stop the handler chain and immediately exit the processing pipeline
-        
-        Handlers will only be called in the chain if their handler and RID type match that of the inputted knowledge object. 
-        """
-        
-        for handler in self.handlers:
-            if handler_type != handler.handler_type: 
-                continue
-            
-            if handler.rid_types and type(kobj.rid) not in handler.rid_types:
-                continue
-            
-            if handler.source and handler.source != kobj.source:
-                continue
-            
-            if handler.event_types and kobj.event_type not in handler.event_types:
-                continue
-            
-            logger.debug(f"Calling {handler_type} handler '{handler.func.__name__}'")
-            resp = handler.func(self, kobj.model_copy())
-            
-            # stops handler chain execution
-            if resp is STOP_CHAIN:
-                logger.debug(f"Handler chain stopped by {handler.func.__name__}")
-                return STOP_CHAIN
-            # kobj unmodified
-            elif resp is None:
-                continue
-            # kobj modified by handler
-            elif isinstance(resp, KnowledgeObject):
-                kobj = resp
-                logger.debug(f"Knowledge object modified by {handler.func.__name__}")
-            else:
-                raise ValueError(f"Handler {handler.func.__name__} returned invalid response '{resp}'")
-                    
-        return kobj
-
-        
-    def process_kobj(self, kobj: KnowledgeObject) -> None:
-        """Sends provided knowledge obejct through knowledge processing pipeline.
-        
-        Handler chains are called in between major events in the pipeline, indicated by their handler type. Each handler type is guaranteed to have access to certain knowledge, and may affect a subsequent action in the pipeline. The five handler types are as follows:
-        - RID - provided RID; if event type is `FORGET`, this handler decides whether to delete the knowledge from the cache by setting the normalized event type to `FORGET`, otherwise this handler decides whether to validate the manifest (and fetch it if not provided).
-        - Manifest - provided RID, manifest; decides whether to validate the bundle (and fetch it if not provided).
-        - Bundle - provided RID, manifest, contents (bundle); decides whether to write knowledge to the cache by setting the normalized event type to `NEW` or `UPDATE`.
-        - Network - provided RID, manifest, contents (bundle); decides which nodes (if any) to broadcast an event about this knowledge to. (Note, if event type is `FORGET`, the manifest and contents will be retrieved from the local cache, and indicate the last state of the knowledge before it was deleted.)
-        - Final - provided RID, manifests, contents (bundle); final action taken after network broadcast.
-        
-        The pipeline may be stopped by any point by a single handler returning the `STOP_CHAIN` sentinel. In that case, the process will exit immediately. Further handlers of that type and later handler chains will not be called.
-        """
-        
-        logger.debug(f"Handling {kobj!r}")
-        kobj = self.call_handler_chain(HandlerType.RID, kobj)
-        if kobj is STOP_CHAIN: return
-        
-        if kobj.event_type == EventType.FORGET:
-            bundle = self.cache.read(kobj.rid)
-            if not bundle: 
-                logger.debug("Local bundle not found")
-                return
-            
-            # the bundle (to be deleted) attached to kobj for downstream analysis
-            logger.debug("Adding local bundle (to be deleted) to knowledge object")
-            kobj.manifest = bundle.manifest
-            kobj.contents = bundle.contents
-            
-        else:
-            # attempt to retrieve manifest
-            if not kobj.manifest:
-                logger.debug("Manifest not found")
-                if kobj.source == KnowledgeSource.External:
-                    logger.debug("Attempting to fetch remote manifest")
-                    manifest = self.network.fetch_remote_manifest(kobj.rid)
-                    
-                elif kobj.source == KnowledgeSource.Internal:
-                    logger.debug("Attempting to read manifest from cache")
-                    bundle = self.cache.read(kobj.rid)
-                    if bundle: 
-                        manifest = bundle.manifest
-                    else:
-                        manifest = None
-                        return
-                    
-                if not manifest:
-                    logger.debug("Failed to find manifest")
-                    return
-                
-                kobj.manifest = manifest
-                
-            kobj = self.call_handler_chain(HandlerType.Manifest, kobj)
-            if kobj is STOP_CHAIN: return
-            
-            # attempt to retrieve bundle
-            if not kobj.bundle:
-                logger.debug("Bundle not found")
-                if kobj.source == KnowledgeSource.External:
-                    logger.debug("Attempting to fetch remote bundle")
-                    bundle = self.network.fetch_remote_bundle(kobj.rid)
-                    
-                elif kobj.source == KnowledgeSource.Internal:
-                    logger.debug("Attempting to read bundle from cache")
-                    bundle = self.cache.read(kobj.rid)
-                
-                if not bundle: 
-                    logger.debug("Failed to find bundle")
-                    return
-                
-                if kobj.manifest != bundle.manifest:
-                    logger.warning("Retrieved bundle contains a different manifest")
-                
-                kobj.manifest = bundle.manifest
-                kobj.contents = bundle.contents                
-                
-        kobj = self.call_handler_chain(HandlerType.Bundle, kobj)
-        if kobj is STOP_CHAIN: return
-            
-        if kobj.normalized_event_type in (EventType.UPDATE, EventType.NEW):
-            logger.info(f"Writing to cache: {kobj!r}")
-            self.cache.write(kobj.bundle)
-            
-        elif kobj.normalized_event_type == EventType.FORGET:
-            logger.info(f"Deleting from cache: {kobj!r}")
-            self.cache.delete(kobj.rid)
-            
-        else:
-            logger.debug("Normalized event type was never set, no cache or network operations will occur")
-            return
-        
-        if type(kobj.rid) in (KoiNetNode, KoiNetEdge):
-            logger.debug("Change to node or edge, regenerating network graph")
-            self.network.graph.generate()
-        
-        kobj = self.call_handler_chain(HandlerType.Network, kobj)
-        if kobj is STOP_CHAIN: return
-        
-        if kobj.network_targets:
-            logger.debug(f"Broadcasting event to {len(kobj.network_targets)} network target(s)")
-        else:
-            logger.debug("No network targets set")
-        
-        for node in kobj.network_targets:
-            self.network.push_event_to(kobj.normalized_event, node)
-            self.network.flush_webhook_queue(node)
-        
-        kobj = self.call_handler_chain(HandlerType.Final, kobj)
-
+    
     def flush_kobj_queue(self):
         """Flushes all knowledge objects from queue and processes them.
         
@@ -246,7 +47,7 @@ class ProcessorInterface():
             logger.debug(f"Dequeued {kobj!r}")
             
             try:
-                self.process_kobj(kobj)
+                self.pipeline.process(kobj)
             finally:
                 self.kobj_queue.task_done()
             logger.debug("Done")
@@ -258,7 +59,7 @@ class ProcessorInterface():
                 logger.debug(f"Dequeued {kobj!r}")
                 
                 try:
-                    self.process_kobj(kobj)
+                    self.pipeline.process(kobj)
                 finally:
                     self.kobj_queue.task_done()
                 logger.debug("Done")
@@ -276,8 +77,8 @@ class ProcessorInterface():
         bundle: Bundle | None = None,
         event: Event | None = None,
         kobj: KnowledgeObject | None = None,
-        event_type: KnowledgeEventType = None,
-        source: KnowledgeSource = KnowledgeSource.Internal
+        event_type: EventType | None = None,
+        source: KoiNetNode | None = None
     ):
         """Queues provided knowledge to be handled by processing pipeline.
         

koi_net/processor/knowledge_object.py

@@ -1,4 +1,3 @@
-from enum import StrEnum
 from pydantic import BaseModel
 from rid_lib import RID
 from rid_lib.ext import Manifest
@@ -7,12 +6,6 @@ from rid_lib.types.koi_net_node import KoiNetNode
 from ..protocol.event import Event, EventType
 
 
-type KnowledgeEventType = EventType | None
-
-class KnowledgeSource(StrEnum):
-    Internal = "INTERNAL"
-    External = "EXTERNAL"
-
 class KnowledgeObject(BaseModel):
     """A normalized knowledge representation for internal processing.
     
@@ -29,9 +22,9 @@ class KnowledgeObject(BaseModel):
     rid: RID
     manifest: Manifest | None = None
     contents: dict | None = None
-    event_type: KnowledgeEventType = None
-    normalized_event_type: KnowledgeEventType = None
-    source: KnowledgeSource
+    event_type: EventType | None = None
+    normalized_event_type: EventType | None = None
+    source: KoiNetNode | None = None
     network_targets: set[KoiNetNode] = set()
     
     def __repr__(self):
@@ -41,8 +34,8 @@ class KnowledgeObject(BaseModel):
     def from_rid(
         cls, 
         rid: RID, 
-        event_type: KnowledgeEventType = None, 
-        source: KnowledgeSource = KnowledgeSource.Internal
+        event_type: EventType | None = None, 
+        source: KoiNetNode | None = None
     ) -> "KnowledgeObject":
         return cls(
             rid=rid,
@@ -54,8 +47,8 @@ class KnowledgeObject(BaseModel):
     def from_manifest(
         cls, 
         manifest: Manifest, 
-        event_type: KnowledgeEventType = None, 
-        source: KnowledgeSource = KnowledgeSource.Internal
+        event_type: EventType | None = None, 
+        source: KoiNetNode | None = None
     ) -> "KnowledgeObject":
         return cls(
             rid=manifest.rid,
@@ -68,8 +61,8 @@ class KnowledgeObject(BaseModel):
     def from_bundle(
         cls, 
         bundle: Bundle, 
-        event_type: KnowledgeEventType = None, 
-        source: KnowledgeSource = KnowledgeSource.Internal
+        event_type: EventType | None = None, 
+        source: KoiNetNode | None = None
     ) -> "KnowledgeObject":
         return cls(
             rid=bundle.rid,
@@ -83,7 +76,7 @@ class KnowledgeObject(BaseModel):
     def from_event(
         cls,
         event: Event,
-        source: KnowledgeSource = KnowledgeSource.Internal
+        source: KoiNetNode | None = None
     ) -> "KnowledgeObject":
         return cls(
             rid=event.rid,

koi_net/processor/knowledge_pipeline.py

@@ -0,0 +1,220 @@
+import logging
+from typing import Callable
+from rid_lib.core import RIDType
+from rid_lib.types import KoiNetEdge, KoiNetNode
+from rid_lib.ext import Cache
+from ..protocol.event import EventType
+from ..network.request_handler import RequestHandler
+from ..network.event_queue import NetworkEventQueue
+from ..network.graph import NetworkGraph
+from ..identity import NodeIdentity
+from .handler import (
+    KnowledgeHandler,
+    HandlerType, 
+    STOP_CHAIN,
+    StopChain
+)
+from .knowledge_object import KnowledgeObject
+
+from typing import TYPE_CHECKING
+if TYPE_CHECKING:
+    from ..context import HandlerContext
+
+logger = logging.getLogger(__name__)
+
+
+class KnowledgePipeline:
+    handler_context: "HandlerContext"
+    cache: Cache
+    identity: NodeIdentity
+    request_handler: RequestHandler
+    event_queue: NetworkEventQueue
+    graph: NetworkGraph
+    handlers: list[KnowledgeHandler]
+    
+    def __init__(
+        self, 
+        handler_context: "HandlerContext",
+        cache: Cache, 
+        request_handler: RequestHandler,
+        event_queue: NetworkEventQueue,
+        graph: NetworkGraph,
+        default_handlers: list[KnowledgeHandler] = []
+    ):
+        self.handler_context = handler_context
+        self.cache = cache
+        self.request_handler = request_handler
+        self.event_queue = event_queue
+        self.graph = graph
+        self.handlers = default_handlers
+    
+    def add_handler(self, handler: KnowledgeHandler):
+        self.handlers.append(handler)
+            
+    def register_handler(
+        self,
+        handler_type: HandlerType,
+        rid_types: list[RIDType] | None = None,
+        event_types: list[EventType | None] | None = None
+    ):
+        """Assigns decorated function as handler for this processor."""
+        def decorator(func: Callable) -> Callable:
+            handler = KnowledgeHandler(func, handler_type, rid_types, event_types)
+            self.add_handler(handler)
+            return func
+        return decorator
+            
+    def call_handler_chain(
+        self, 
+        handler_type: HandlerType,
+        kobj: KnowledgeObject
+    ) -> KnowledgeObject | StopChain:
+        """Calls handlers of provided type, chaining their inputs and outputs together.
+        
+        The knowledge object provided when this function is called will be passed to the first handler. A handler may return one of three types: 
+        - `KnowledgeObject` - to modify the knowledge object for the next handler in the chain
+        - `None` - to keep the same knowledge object for the next handler in the chain
+        - `STOP_CHAIN` - to stop the handler chain and immediately exit the processing pipeline
+        
+        Handlers will only be called in the chain if their handler and RID type match that of the inputted knowledge object. 
+        """
+        
+        for handler in self.handlers:
+            if handler_type != handler.handler_type: 
+                continue
+            
+            if handler.rid_types and type(kobj.rid) not in handler.rid_types:
+                continue
+            
+            if handler.event_types and kobj.event_type not in handler.event_types:
+                continue
+            
+            logger.debug(f"Calling {handler_type} handler '{handler.func.__name__}'")
+            
+            resp = handler.func(
+                ctx=self.handler_context,
+                kobj=kobj.model_copy()
+            )
+            
+            # stops handler chain execution
+            if resp is STOP_CHAIN:
+                logger.debug(f"Handler chain stopped by {handler.func.__name__}")
+                return STOP_CHAIN
+            # kobj unmodified
+            elif resp is None:
+                continue
+            # kobj modified by handler
+            elif isinstance(resp, KnowledgeObject):
+                kobj = resp
+                logger.debug(f"Knowledge object modified by {handler.func.__name__}")
+            else:
+                raise ValueError(f"Handler {handler.func.__name__} returned invalid response '{resp}'")
+                    
+        return kobj
+    
+    def process(self, kobj: KnowledgeObject):
+        """Sends provided knowledge obejct through knowledge processing pipeline.
+        
+        Handler chains are called in between major events in the pipeline, indicated by their handler type. Each handler type is guaranteed to have access to certain knowledge, and may affect a subsequent action in the pipeline. The five handler types are as follows:
+        - RID - provided RID; if event type is `FORGET`, this handler decides whether to delete the knowledge from the cache by setting the normalized event type to `FORGET`, otherwise this handler decides whether to validate the manifest (and fetch it if not provided).
+        - Manifest - provided RID, manifest; decides whether to validate the bundle (and fetch it if not provided).
+        - Bundle - provided RID, manifest, contents (bundle); decides whether to write knowledge to the cache by setting the normalized event type to `NEW` or `UPDATE`.
+        - Network - provided RID, manifest, contents (bundle); decides which nodes (if any) to broadcast an event about this knowledge to. (Note, if event type is `FORGET`, the manifest and contents will be retrieved from the local cache, and indicate the last state of the knowledge before it was deleted.)
+        - Final - provided RID, manifests, contents (bundle); final action taken after network broadcast.
+        
+        The pipeline may be stopped by any point by a single handler returning the `STOP_CHAIN` sentinel. In that case, the process will exit immediately. Further handlers of that type and later handler chains will not be called.
+        """
+        
+        logger.debug(f"Handling {kobj!r}")
+        kobj = self.call_handler_chain(HandlerType.RID, kobj)
+        if kobj is STOP_CHAIN: return
+        
+        if kobj.event_type == EventType.FORGET:
+            bundle = self.cache.read(kobj.rid)
+            if not bundle: 
+                logger.debug("Local bundle not found")
+                return
+            
+            # the bundle (to be deleted) attached to kobj for downstream analysis
+            logger.debug("Adding local bundle (to be deleted) to knowledge object")
+            kobj.manifest = bundle.manifest
+            kobj.contents = bundle.contents
+            
+        else:
+            # attempt to retrieve manifest
+            if not kobj.manifest:
+                logger.debug("Manifest not found")
+                if not kobj.source:
+                    return
+            
+                logger.debug("Attempting to fetch remote manifest from source")
+                payload = self.request_handler.fetch_manifests(
+                    node=kobj.source,
+                    rids=[kobj.rid]
+                )
+                    
+                if not payload.manifests:
+                    logger.debug("Failed to find manifest")
+                    return
+                
+                kobj.manifest = payload.manifests[0]
+                
+            kobj = self.call_handler_chain(HandlerType.Manifest, kobj)
+            if kobj is STOP_CHAIN: return
+            
+            # attempt to retrieve bundle
+            if not kobj.bundle:
+                logger.debug("Bundle not found")
+                if kobj.source is None:
+                    return
+                
+                logger.debug("Attempting to fetch remote bundle from source")
+                payload = self.request_handler.fetch_bundles(
+                    node=kobj.source,
+                    rids=[kobj.rid]
+                )
+                
+                if not payload.bundles:
+                    logger.debug("Failed to find bundle")
+                    return
+                
+                bundle = payload.bundles[0]                    
+                
+                if kobj.manifest != bundle.manifest:
+                    logger.warning("Retrieved bundle contains a different manifest")
+                
+                kobj.manifest = bundle.manifest
+                kobj.contents = bundle.contents                
+                
+        kobj = self.call_handler_chain(HandlerType.Bundle, kobj)
+        if kobj is STOP_CHAIN: return
+            
+        if kobj.normalized_event_type in (EventType.UPDATE, EventType.NEW):
+            logger.info(f"Writing to cache: {kobj!r}")
+            self.cache.write(kobj.bundle)
+            
+        elif kobj.normalized_event_type == EventType.FORGET:
+            logger.info(f"Deleting from cache: {kobj!r}")
+            self.cache.delete(kobj.rid)
+            
+        else:
+            logger.debug("Normalized event type was never set, no cache or network operations will occur")
+            return
+        
+        if type(kobj.rid) in (KoiNetNode, KoiNetEdge):
+            logger.debug("Change to node or edge, regenerating network graph")
+            self.graph.generate()
+        
+        kobj = self.call_handler_chain(HandlerType.Network, kobj)
+        if kobj is STOP_CHAIN: return
+        
+        if kobj.network_targets:
+            logger.debug(f"Broadcasting event to {len(kobj.network_targets)} network target(s)")
+        else:
+            logger.debug("No network targets set")
+        
+        for node in kobj.network_targets:
+            self.event_queue.push_event_to(kobj.normalized_event, node)
+            self.event_queue.flush_webhook_queue(node)
+        
+        kobj = self.call_handler_chain(HandlerType.Final, kobj)

koi_net/protocol/api_models.py

@@ -4,6 +4,7 @@ from pydantic import BaseModel
 from rid_lib import RID, RIDType
 from rid_lib.ext import Bundle, Manifest
 from .event import Event
+from .errors import ErrorTypes
 
 
 # REQUEST MODELS
@@ -41,7 +42,12 @@ class EventsPayload(BaseModel):
     events: list[Event]
     
 
+# ERROR MODELS
+
+class ErrorResponse(BaseModel):
+    error: ErrorTypes
+
 # TYPES
 
 type RequestModels = EventsPayload | PollEvents | FetchRids | FetchManifests | FetchBundles
-type ResponseModels = RidsPayload | ManifestsPayload | BundlesPayload | EventsPayload
+type ResponseModels = RidsPayload | ManifestsPayload | BundlesPayload | EventsPayload | ErrorResponse

koi_net/protocol/edge.py

@@ -1,7 +1,8 @@
 from enum import StrEnum
 from pydantic import BaseModel
 from rid_lib import RIDType
-from rid_lib.types import KoiNetNode
+from rid_lib.ext.bundle import Bundle
+from rid_lib.types import KoiNetEdge, KoiNetNode
 
 
 class EdgeStatus(StrEnum):
@@ -18,3 +19,24 @@ class EdgeProfile(BaseModel):
     edge_type: EdgeType
     status: EdgeStatus
     rid_types: list[RIDType]
+
+
+def generate_edge_bundle(
+    source: KoiNetNode,
+    target: KoiNetNode,
+    rid_types: list[RIDType],
+    edge_type: EdgeType
+) -> Bundle:
+    edge_rid = KoiNetEdge.generate(source, target)
+    edge_profile = EdgeProfile(
+        source=source,
+        target=target,
+        rid_types=rid_types,
+        edge_type=edge_type,
+        status=EdgeStatus.PROPOSED
+    )
+    edge_bundle = Bundle.generate(
+        edge_rid,
+        edge_profile.model_dump()
+    )
+    return edge_bundle

koi_net/protocol/envelope.py

@@ -0,0 +1,54 @@
+import logging
+from typing import Generic, TypeVar
+from pydantic import BaseModel
+from rid_lib.types import KoiNetNode
+
+from .secure import PrivateKey, PublicKey
+from .api_models import RequestModels, ResponseModels
+
+
+logger = logging.getLogger(__name__)
+
+
+T = TypeVar("T", bound=RequestModels | ResponseModels)
+
+class SignedEnvelope(BaseModel, Generic[T]):
+    payload: T
+    source_node: KoiNetNode
+    target_node: KoiNetNode
+    signature: str
+    
+    def verify_with(self, pub_key: PublicKey):        
+        # IMPORTANT: calling `model_dump()` loses all typing! when converting between SignedEnvelope and UnsignedEnvelope, use the Pydantic classes, not the dictionary form
+        unsigned_envelope = UnsignedEnvelope[T](
+            payload=self.payload,
+            source_node=self.source_node,
+            target_node=self.target_node 
+        )
+        
+        logger.debug(f"Verifying envelope: {unsigned_envelope.model_dump_json()}")
+        
+        pub_key.verify(
+            self.signature,
+            unsigned_envelope.model_dump_json().encode()
+        )
+
+class UnsignedEnvelope(BaseModel, Generic[T]):
+    payload: T
+    source_node: KoiNetNode
+    target_node: KoiNetNode
+    
+    def sign_with(self, priv_key: PrivateKey) -> SignedEnvelope[T]:
+        logger.debug(f"Signing envelope: {self.model_dump_json()}")
+        logger.debug(f"Type: [{type(self.payload)}]")
+        
+        signature = priv_key.sign(
+            self.model_dump_json().encode()
+        )
+        
+        return SignedEnvelope(
+            payload=self.payload,
+            source_node=self.source_node,
+            target_node=self.target_node,
+            signature=signature
+        )