Crate tap_node

TAP Node - A node implementation for the TAP protocol

The TAP Node is the central component that manages TAP Agents, routes messages, processes events, stores transactions, and provides a scalable architecture for TAP deployments.

Architecture Overview

The TAP Node acts as a message router and coordinator for multiple TAP Agents. It provides:

• Efficient Message Processing: Different handling for plain, signed, and encrypted messages
• Centralized Verification: Signed messages are verified once for all agents
• Smart Routing: Encrypted messages are routed to appropriate recipient agents
• Scalable Design: Supports multiple agents with concurrent message processing

Key Components

• Agent Registry: Manages multiple TAP Agents
• Event Bus: Publishes and distributes events throughout the system
• Message Processors: Process incoming and outgoing messages
• Message Router: Routes messages to the appropriate agent
• DID Resolver: Resolves DIDs for signature verification
• Storage: Persistent SQLite storage with transaction tracking and audit trails

Message Processing Flow

The TAP Node uses an optimized message processing flow based on message type:

Signed Messages (JWS)

1. Single Verification: Signature verified once using DID resolver
2. Routing: Verified PlainMessage routed to appropriate agent
3. Processing: Agent receives verified message via receive_plain_message()

Encrypted Messages (JWE)

1. Recipient Identification: Extract recipient DIDs from JWE headers
2. Agent Routing: Send encrypted message to each matching agent
3. Decryption: Each agent attempts decryption via receive_encrypted_message()
4. Processing: Successfully decrypted messages are processed by the agent

Plain Messages

1. Direct Processing: Plain messages processed through the pipeline
2. Routing: Routed to appropriate agent
3. Delivery: Agent receives via receive_plain_message()

Benefits of This Architecture

• Efficiency: Signed messages verified once, not per-agent
• Scalability: Encrypted messages naturally distributed to recipients
• Flexibility: Agents remain fully functional standalone
• Security: Centralized verification with distributed decryption

Thread Safety and Concurrency

The TAP Node is designed with concurrent operations in mind. It uses a combination of async/await patterns and synchronization primitives to safely handle multiple operations simultaneously. Most components within the node are either immutable or use interior mutability with appropriate synchronization.

Example Usage

use tap_node::{TapNode, NodeConfig};
use tap_agent::TapAgent;
use std::sync::Arc;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create node
    let config = NodeConfig::default();
    let node = Arc::new(TapNode::new(config));
     
    // Create and register agent
    let (agent, _did) = TapAgent::from_ephemeral_key().await?;
    node.register_agent(Arc::new(agent)).await?;
     
    // Process incoming message (JSON Value)
    let message_value = serde_json::json!({
        "id": "msg-123",
        "type": "test-message",
        "body": {"content": "Hello"}
    });
     
    node.receive_message(message_value).await?;
    Ok(())
}

Re-exports

pub use error::Error;

pub use error::Result;

pub use event::logger::EventLogger;

pub use event::logger::EventLoggerConfig;

pub use event::logger::LogDestination;

pub use event::EventSubscriber;

pub use event::NodeEvent;

pub use message::sender::HttpPlainMessageSender;

pub use message::sender::HttpPlainMessageSenderWithTracking;

pub use message::sender::NodePlainMessageSender;

pub use message::sender::PlainMessageSender;

pub use message::sender::WebSocketPlainMessageSender;

pub use storage::models::DeliveryStatus;

pub use storage::models::DeliveryType;

pub use storage::Storage;

Modules

agent

Agent management for TAP Node

customer

Customer management module for TAP Node

error

Error handling for TAP Node

event

Event System for TAP Node

message

PlainMessage processing and routing for TAP Node

state_machine

Transaction state machine for TAP Node

storage

Storage module for persisting TAP messages and transactions

validation

Message validation framework for TAP Node

Structs

NodeConfig

Configuration for a TAP Node

TapNode

The TAP Node

Traits

TapAgentExt

This trait extends the TapAgent with methods for serializing and packing DIDComm messages for transmission. It provides functionality for converting in-memory message objects to secure, serialized formats that follow the DIDComm messaging protocol standards.